dsh-readme

Read one text file — a team conventions file, a project's AgentsReadMe.md, a style guide — and inject its contents into the system prompt of every agent before that agent's first model request. The file's rules then apply for the whole session, in that session's main agent and in every subagent it spawns.

Why a system prompt section and not a message

DSH assembles the system prompt before each model step, from ordered sections. A section's text may be a function, so it is re-evaluated per step. Mounting the file as a section therefore needs no session hooks at all: there is no step that could send a request without first assembling the section, so "read before the first run" is a structural guarantee rather than a race the plugin tries to win.

It also survives context compression. A file fed in as a chat message can be summarised away half an hour later; a system-prompt section cannot.

Install

The plugin is a normal DSH bundle. Either install it from a directory:

dsh plugin add /path/to/dsh-readme

or point the profile at it by hand — add the package to dependencies and to dsh.profile.bundles in the profile's package.json, then reinstall:

{
  "dependencies": { "dsh-readme": "file:/path/to/dsh-readme" },
  "dsh": { "profile": { "bundles": ["dsh-readme", "..."] } }
}

Restart DSH afterwards: bundle rows are read at startup.

Or install it straight from this repository (a git: dependency; the file: form above is what a local checkout uses):

{
  "dependencies": { "dsh-readme": "github:LXinH3RT/dsh-readme" },
  "dsh": { "profile": { "bundles": ["dsh-readme", "..."] } }
}

Then tell the plugin which file to read — see Configure.

Configure

The plugin ships its own configuration page, registered on the plugin page's plugins.row.config seat: open Settings → Plugins, open the bundle that lists this row, then use Configure on the dsh-readme row to edit the path and save. The write goes to the active profile's patch document and needs no restart — the next prompt assembly reads the new file.

The page reads and writes the form state the host hands it, so validation, revision conflicts and the read-only fallback are the host's, not the plugin's: a write carries a revision and a stale one is reported as a conflict; a field already fixed by the profile patch or a command-line overlay shows as read-only instead of being silently dropped.

Every field can also be written by hand in the profile patch:

# Address the row by ID only. Do NOT repeat `name:` here: for a row inserted by a
# bundle layer, DSH anchors the name to a generated file:/// URL, so a bare package
# name is rejected as a "name mismatch" and the whole patch entry is skipped.
- id: dsh-readme
  config:
    path: ~/workspace/AgentsReadMe.md

Field	Default	Meaning
enabled	true	Inject at all. Off means the plugin writes nothing into the prompt.
path	""	The file. Supports ~, $VAR, ${VAR}, %VAR%. A relative path resolves against the session's working directory. Empty means "not configured yet", and the plugin stays silent.
maxBytes	32768	Cap on injected text, 1024–4194304. A longer file is truncated and the model is told so, because a model that assumes it read the whole file will confidently violate the part that was cut.
reloadOnChange	true	Re-read when the file changes. Off pins the first read for the life of the mount, which keeps the prompt byte-identical across steps and friendlier to prompt caching.
onMissing	notice	What to inject when the file cannot be read: notice puts one line in the prompt telling the model to say so; silent injects nothing.
order	520	Position in the prompt. 520 is after the plan policy (500) and before the team policy (600).

Each setting can also come from the environment (DSH_README_ENABLED, DSH_README_PATH, DSH_README_ORDER, DSH_README_MAX_BYTES, DSH_README_RELOAD_ON_CHANGE, DSH_README_ON_MISSING), which is useful for a headless deployment with no panel. Precedence: configuration wins, the environment is the deployment default, the built-in defaults are last. An empty string does not override anything — it falls through to the layer beneath.

What the model sees

## 工作约束（来自 dsh-readme）

用户为这个会话指定了一份约束文件，下面是它的全部内容，在本次会话处理第一个请求之前已经读取。
这些条目是**强制规范**：它们优先于通用默认做法、工具的使用建议和你自己的习惯。
若它们与任何其他说明冲突，以此处为准；如果某条要求在本任务里无法执行，先说明原因，再按最接近的方式做。
不要复述、摘要或转述这份文件——直接照着它工作。

来源：~/notes/conventions.md · 共 1240 字节 · 2026-10-24 21:40

---
（文件内容，原样）
---

The framing is deliberate. "Here is a file" reads as reference material the model may weigh against its defaults, which is exactly what a constraints file exists to prevent; the header instead states where the authority comes from, what wins a conflict, and — the line that keeps the injection affordable — that the file is not to be echoed back.

Behaviour details

• Read lazily, on the first assembly. Not at plugin load. A session started hours after install sees the file as it is now.
• Cached by (path, size, mtime). An unchanged file costs one stat per step, not a read.
• Missing, empty, binary, directory, unreadable: each has its own state. An empty file or an unconfigured path injects nothing at all — injecting an empty header would spend tokens on every step to say nothing.
• Binary files are refused (a NUL in the first 8 KiB), so pointing path at a zip by mistake produces a notice instead of mojibake in the prompt.
• Truncation cuts on a UTF-8 boundary, never mid-character, and a BOM is stripped.
• {{...}} in the file is literal text: the section is registered with interpolate: false, so a README documenting a template is not rewritten by the prompt renderer.
• One section per mount, named dsh-readme:constraints. Do not add a second row for this plugin to a preset; two instances would register the same section name twice.
• The settings page degrades instead of breaking. The browser half wraps its whole body in try/catch and returns early when the slot or locale services are absent — a client bundle that throws takes its entire surface with it. When the host serves no configuration scope for this row, the page says so rather than spinning forever.

Tests

node test/smoke.mjs

No DSH host, no network, no @deepseek-ai/schemastery: the test covers path expansion, every read state, the binary and truncation guards, the cache and the rendered text.

License

MIT