规则注入 LXinH3RT/dsh-readme

dsh-readme

English · 简体中文

指定一个文本文件（团队规范、项目的 AgentsReadMe.md、风格指南……），插件会在每个智能体首次运行之前读取它，并把内容注入该智能体的系统提示词。这些规则因此在整场会话中生效——包括主智能体，也包括它派生的每一个子智能体。

为什么做成系统提示词小节，而不是一条消息

DSH 在每一次模型步骤之前组装系统提示词，而小节的文本可以是一个函数，因此每步都会重新求值。把文件挂成这样一个小节，就完全不需要监听会话事件：不存在“能发出请求却没组装过该小节”的步骤，所以“首次运行前已阅读”是结构性保证，而不是插件去抢的时序。

它同时能扛住上下文压缩。以聊天消息形式喂进去的文件，半小时后可能被摘要掉；系统提示词小节不会。

安装

插件是一个普通的 DSH 打包插件（bundle）。从目录安装：

dsh plugin add /path/to/dsh-readme

或者手工挂到 profile 上——在 profile 的 package.json 里把它加进 dependencies 和 dsh.profile.bundles，再重新安装依赖：

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

之后重启 DSH：打包行（bundle）只在启动时读取。

也可以直接从本仓库安装（git: 形式的依赖；上面的 file: 是本地检出时的写法）：

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

然后告诉插件读哪个文件——见配置。

配置

插件自带一个配置页，挂在插件页的 plugins.row.config 槽上：打开设置 → 插件，在本插件所在组合的页面上，点 dsh-readme 这一行右侧的“配置”，即可直接改路径并保存。改动写入当前 profile 的 patch 文档，无需重启，下一次提示词组装就用新文件。

配置页用宿主传入的表单状态读写，因此校验、版本冲突与只读降级都由宿主负责：写入带 revision，过期会提示冲突；profile 的 patch 或命令行覆盖了该字段时，页面显示为只读而不是静默丢弃。

同样的字段也可以在 profile 的 patch 里手写：

只按 id 覆盖。不要写 name：打包层插入的行，其 name 是 DSH 生成的 file:///... 绝对地址，再写一个包名会判定为 “name mismatch” 并把整条 patch 跳过。
- id: dsh-readme
config:
path: ~/workspace/AgentsReadMe.md

| 字段 | 默认值 | 含义 |
| enabled | true | 是否注入。关闭后本插件不向提示词写入任何内容。 |
| path | "" | 目标文件。支持 ~、$VAR、${VAR}、%VAR%；相对路径按会话工作目录解析。留空表示尚未配置，插件保持安静。 |
| maxBytes | 32768 | 注入文本的上限，范围 1024–4194304。超长文件会被截断，并明确告知模型——否则模型会以为读完了全文，理直气壮地违反被切掉的那部分。 |
| reloadOnChange | true | 文件变化后重新读取。关闭则固定为首次读取的内容，提示词在各步之间保持字节一致，更利于提示词缓存。 |
| onMissing | notice | 读不到文件时注入什么：notice 写一行说明、让模型告知用户；silent 什么都不写。 |
| order | 520 | 在提示词中的位置。520 位于计划策略（500）之后、团队策略（600）之前。 |

每一项也可以用环境变量给（DSH_README_ENABLED、DSH_README_PATH、DSH_README_ORDER、 DSH_README_MAX_BYTES、DSH_README_RELOAD_ON_CHANGE、DSH_README_ON_MISSING），适合没有面板的无头部署。优先级：配置 > 环境变量 > 内置默认值。空字符串不算“显式指定”，会继续往下层落。

模型看到的内容

工作约束（来自 dsh-readme）

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

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

（文件内容，原样）

这段框定是刻意的。“下面是一个文件”会被读成可与默认做法权衡的参考资料，而那正是约束文件要防的事；所以这里直说权威来自哪里、冲突时以谁为准，以及——让这份注入不至于太贵的一句——不要复述文件。

行为细节

- 惰性读取，在首次组装时。 不是插件加载时。安装几小时之后才开始的会话，看到的仍是文件当下内容。
- 按 (path, size, mtime) 缓存。 未变化的文件每步只花一次 stat，不读盘。
- 缺失 / 空文件 / 二进制 / 目录 / 不可读各有独立状态。空文件和未配置路径注入空字符串——为空标题每步花 token，等于什么都没说。
- 二进制文件会被拒绝（前 8 KiB 中出现 NUL），避免误把压缩包设成 path 后往提示词里灌乱码。
- 截断按 UTF-8 边界切，不会切断多字节字符；BOM 会被剥掉。
- 文件里的 {{...}} 是普通文本：小节以 interpolate: false 注册，因此一份写着模板语法的 README 不会被提示词渲染器改写。
- 每个挂载一个小节，名字是 dsh-readme:constraints。不要给这个插件在预设里再加一行；两个实例会用同一个名字注册两次。
- 配置页只会降级，不会把页面弄坏。 浏览器半整体包在 try/catch 里，缺少槽位或本地化服务时直接返回——一个抛出异常的客户端 bundle 会把它自己的整个界面一起弄没。宿主没有为这一行提供配置作用域时，页面如实说明，而不是一直转圈。

测试

node test/smoke.mjs

不需要 DSH 宿主、不需要网络、不需要 @deepseek-ai/schemastery：覆盖路径展开、所有读取状态、二进制与截断防护、缓存与渲染结果。

许可

MIT