前言¶
在 DSH 里跑多 Agent 会话时，常见做法是把 AgentsReadMe.md、代码规范或 style guide 贴进首轮对话，或指望用户规则里那几段话一直生效。前者会在上下文压缩后被摘要掉；后者和「每个子 Agent 都要遵守同一套硬约束」也不是同一层机制。DSH 会在每次模型步进前按顺序组装 system prompt，dsh-readme 利用这一结构，在指定文本文件存在的前提下，于该 Agent 第一次发起模型请求之前把文件内容注入为 system prompt 的一段，并在整段会话内（含主 Agent 与其派生的子 Agent）作为绑定式工作约束生效。
下面介绍插件定位、安装配置方式，以及使用时需要留意的边界。
这是什么¶
dsh-readme 是社区维护的 DSH 插件（GitHub：LXinH3RT/dsh-readme，目录分类 admin-security）。它读取用户指定路径上的一个文本文件——可以是团队约定、项目的 AgentsReadMe.md、写作风格指南等——并在每个 Agent 首次模型请求前，将该文件内容注入 system prompt，而不是作为普通聊天消息发送。
维护者：LXinH3RT。许可证：MIT（以仓库为准）。当前 package 版本为 0.2.0，要求 DSH >=0.1.7-rc.2。
为什么用 system prompt 段而不是消息¶
README 中的设计说明可以概括为两点：
- 结构保证「首次运行前已读」：挂载为 prompt section 时，不存在「还没组装 section 就发出请求」的竞态；section 文本可以是函数，因此每步可重新求值，但不需要 session hook 去抢时机。
- 抗上下文压缩：以聊天消息喂入的内容可能在长时间会话中被 summarised；system prompt 中的 section 不会因此被同样方式挤掉。
核心功能¶
以下能力均来自仓库 README 与 package.json 描述，未在资料中出现的细节不写。
- 全局注入：主 Agent 与其 spawn 的子 Agent，在各自第一次模型请求前都会带上同一份约束段（在
path已配置且可读的前提下）。 - 懒加载：不在插件加载时读文件；在第一次 prompt 组装时读取，因此安装数小时后才开的会话仍能看到磁盘上当前内容。
- 缓存：按
(path, size, mtime)缓存；文件未变时每步仅stat，不重复读盘。 reloadOnChange：默认true，文件变更后重新读取；关闭则固定首次读取内容，便于 prompt caching（字节级稳定）。- 体积上限
maxBytes：默认32768，范围1024–4194304；超长会截断，且明确告知模型文件被截断，避免模型误以为读全了却违反被裁掉的部分。 - 缺失与异常：
onMissing为notice时在 prompt 中留一行提示模型说明读不到；silent则什么都不注入。空文件、未配置path、二进制（首 8 KiB 含 NUL）、目录、不可读等各有处理；空路径或未配置时不注入空壳标题以省 token。 - 顺序
order：默认520，位于 plan policy（500）之后、team policy（600）之前。 - 模板字面量：文件内
{{...}}按字面量保留（section 注册时interpolate: false）。 - 单实例：section 名为
dsh-readme:constraints；同一 preset 不要挂两行本插件，否则会重复注册同名 section。 - 设置页：在插件行的
plugins.row.config座位注册；也可手写 profile patch 或环境变量覆盖。
模型侧看到的 framing（中文示例，摘自 README）会强调：条目为强制规范，冲突时以此为准；不要复述、摘要或转述文件，直接按文件工作。并标注来源路径、字节数与时间戳，随后原样放入文件正文。
安装与启用¶
插件是普通 DSH bundle。资料给出三种方式。
从本地目录安装：
dsh plugin add /path/to/dsh-readme
在 profile 的 package.json 中手动声明（本地 file:）：
{
"dependencies": { "dsh-readme": "file:/path/to/dsh-readme" },
"dsh": { "profile": { "bundles": ["dsh-readme", "..."] } }
}
从 GitHub 依赖（git: 形式，非 dsh plugin add github:... 拼接）：
{
"dependencies": { "dsh-readme": "github:LXinH3RT/dsh-readme" },
"dsh": { "profile": { "bundles": ["dsh-readme", "..."] } }
}
修改 bundle 列表后需重启 DSH（bundle 行在启动时读取）。安装完成后还要配置 path，见下一节。
配置¶
图形界面¶
打开 Settings → Plugins，在列出该 bundle 的行上找到 dsh-readme，点 Configure 编辑路径并保存。写入 active profile 的 patch 文档，无需重启；下一次 prompt 组装即读新路径。
页面使用宿主下发的表单状态；revision 冲突、只读字段等行为由宿主处理，而非插件自行静默丢弃。
Profile patch（手写）¶
# 仅用 id 定位行；不要在此重复 name:，bundle 层插入的行 name 与 file:/// URL 锚定，裸包名会导致 name mismatch 整段被跳过
- id: dsh-readme
config:
path: ~/workspace/AgentsReadMe.md
| 字段 | 默认值 | 含义 |
|---|---|---|
enabled |
true |
是否注入；false 时不写任何内容进 prompt |
path |
"" |
约束文件；支持 ~、$VAR、${VAR}、%VAR%；相对路径相对会话工作目录；空表示未配置，插件保持静默 |
maxBytes |
32768 |
注入上限 |
reloadOnChange |
true |
文件变更是否重读 |
onMissing |
notice |
读失败时 notice 或 silent |
order |
520 |
section 在 prompt 中的位置 |
环境变量（无面板部署可用）：DSH_README_ENABLED、DSH_README_PATH、DSH_README_ORDER、DSH_README_MAX_BYTES、DSH_README_RELOAD_ON_CHANGE、DSH_README_ON_MISSING。优先级：配置 > 环境 > 内置默认；空字符串不会覆盖下层。
典型用法¶
- 在仓库或家目录维护一份约束 Markdown，例如
~/workspace/AgentsReadMe.md，写清编码规范、禁止操作、评审 checklist 等。 - 按上文安装 bundle 并重启（若改了
bundles）。 - 在 Configure 或 patch 里设置
path指向该文件；需要 headless 时用DSH_README_PATH。 - 新开 DSH 会话，主 Agent 与子 Agent 在首次请求前都会带上「工作约束」段；改文件后若
reloadOnChange为 true，后续步进会按 mtime 重读。
本地验证插件逻辑（不依赖 DSH 宿主）：
node test/smoke.mjs
适用场景与注意¶
适合：需要把同一份硬约束绑定到整棵 Agent 树、且希望约束留在 system prompt 而非首轮 user 消息的团队或个人；分类落在 admin-security 也符合「治理类规则进 prompt」的用法。
务必注意：
- 插件以当前 DSH 进程权限读
path所指文件；安装前请自行审阅源码与 MIT 许可证，勿指向无权限或敏感路径。 maxBytes截断后模型会被告知，但仍应控制单文件体积，避免关键条款落在截断线之后。- 不要在同一 preset 重复添加本插件多行。
- DSH 生态是「一切皆插件」；社区目录页（SkillHub）与 DeepSeek / 幻方无官方从属关系，本文仅介绍该开源 bundle 的行为。
结尾¶
dsh-readme 把「一份指定文本文件」变成每个 Agent 首次运行前就生效的 system prompt 约束段，用 DSH 的 section 组装机制替代「贴消息 + 赌不被压缩」的 fragile 做法。需要安装说明与字段语义时以 GitHub README 为准。
- 目录页：https://www.skillhub.cn/plugins/LXinH3RT/dsh-readme
- 仓库：https://github.com/LXinH3RT/dsh-readme
