dsh-global-rules

给 DeepSeek Harness 的原生 AGENTS.md 机制补上它缺的那一块:全局规则拆成多个独立文件,并配一个设置页 GUI。

为什么需要它

DSH 内建的 @deepseek-ai/dsh-agent-instructions 只读一个用户全局文件:

// dsh-agent-instructions/lib/index.js
const USER_GLOBAL_FILE = "AGENTS.md";        // 硬编码常量
const userGlobal = join(config.dshHome, USER_GLOBAL_FILE);   // 无循环

对比项目层——它会遍历一整个候选名列表:

for (const dir of ancestorChain(projectRoot, cwd))
  for (const candidates of [config.instructionFileCandidates, ...])

也就是说:项目层支持多文件,全局层写死一个。instructionFileCandidates 配置碰不到全局层,候选名里的子路径会被 resolveInstructionFileCandidates 过滤掉,@path import 官方也明确不做。

于是全局规则只能全塞进 $DSH_HOME/AGENTS.md 一个文件里。本插件解决的就是这件事。

它做什么

$DSH_HOME/rules/ 下一个 markdown 文件 = 一条全局规则,每条独立增删改、独立开关:

$DSH_HOME/rules/
  01-回答风格.md
  02-代码改动规范.md
  03-隐私禁区.md
  04-临时停用的规则.md.disabled   ← 暂停即改名，内容一字节不丢

每条规则作为一个有序的 system-prompt 段(order: 100,紧随部署 persona 之后)注入,对所有会话与模型生效。

改完下一步请求即生效,无需重启 DSH。 因为段的 text 是每次装配时求值的函数,而不是启动时快照的字符串。

安装

dsh plugin --profile web add github:kingzhz/dsh-global-rules
dsh web          # host 侧代码在进程启动时装载，需重启一次

装好后在 设置 → 全局规则 打开 GUI。

只有 host 侧需要重启一次。之后增删改规则文件、开关规则都不需要重启——包括 GUI 里的操作。

GUI

设置页提供:

• 按优先级分档列出规则(每档显示条数与字节合计),显示标题、文件名、生效/暂停状态
• 每条规则一个优先级下拉,改档即写入其 front matter
• 点任意一条即在下方编辑,保存走原子写(同目录临时文件 + rename)
• 新建规则(自动加数字前缀,保持顺序稳定)
• 删除规则(二次确认)
• 暂停 / 启用:改名加去 .disabled,内容零丢失
• 顶部显示规则目录路径与预算占用(已用 / 上限)

也可以完全不用 GUI:直接往 rules/ 目录扔 .md 文件即可。

优先级

多条规则冲突时该听谁的?用优先级表达。

---
priority: 0
---

# 安全红线

绝对不执行 rm -rf、不 force push。

优先级	front matter	system-prompt 段 order	预算耗尽时
P0 最高	priority: 0	100	最后被丢
P1 高	priority: 1	200	倒数第二被丢
P2 默认	priority: 2(不写即此档)	300	正常
P3 低	priority: 3	400	最先被丢

也接受 priority: p1 这种写法。超出范围的值会被夹到最近的档(负数 → P0,99 → P3);写成非数字则退回 P2,不会报错。

为什么这是真优先级,不只是标签

每个优先级档注册成独立的 system-prompt 段,order 依次为 100/200/300/400。DSH 按 order 升序拼接段,于是:

1. 位置真的分层 —— P0 的规则排在 P1 之前,P1 在 P2 之前。
2. 预算按优先级分配 —— 从最高档开始满足,不够时先丢 P3、再丢 P2。低优先级规则挤不掉高优先级规则。
3. 显式冲突声明 —— 注入文本开头写明"按优先级从高到低排列;两条冲突时以更靠前的为准"。

一个诚实的边界: DSH 不会在机制层面强制"高优先级覆盖低优先级"——最终是模型读文本。上面的位置分层 + 显式声明 + 预算保护,是实际能做到的最强形态。

同一优先级内,文件名数字前缀决定顺序。

配置

- id: global-rules
  name: 'dsh-global-rules'
  config:
    rulesDir: ~/.dsh/rules     # 默认 <DSH_HOME>/rules
    maxBytes: 32768            # 注入文本的字节上限，默认 32768
    maxSourceBytes: 262144     # 单个规则文件的读取上限，默认 256 KiB
    order: 100                 # 最高优先级档（P0）的段序号，默认 100
    heading: Global rules      # 注入块的开头说明
    enabled: true              # 置 false 则完全不注入

order 是 P0 的段序号;P1/P2/P3 依次 +100。$DSH_HOME 解析顺序:显式配置 → $DSH_HOME 环境变量 → ~/.dsh。

预算行为

预算按优先级从高到低分配:先满足 P0,再 P1,依此类推。某档放不下时,该规则在剩余额度内截断(额度太小则整体省略),并附一条 [Global rules omitted for budget: ...] 提示,日志同时记录。

渲染结果绝不会超过 maxBytes。单文件超过 maxSourceBytes 时截断注入并在日志告警——磁盘上的原文件不动。

访问范围

如实列出这个插件碰什么、不碰什么。

类别	范围
读	rules/ 目录下的 *.md / *.md.disabled(仅此目录,仅此两种形态)
写	同上白名单。原子写(临时文件 + rename),崩溃不会截断原文件
改名	同上白名单,用于「暂停/恢复」
网络	零。host 侧只 import node:fs / node:fs/promises / node:path / node:os / node:crypto
会话	不读取。不碰 session 记录、不读对话内容
路径	客户端永远不传路径,只传文件名;host 侧用严格白名单正则校验后才 join。链外路径一律拒绝

路径穿越防护

host 侧只接受裸文件名,并校验:

const RULE_FILE_PATTERN = /^[^\\/:*?"<>|\u0000-\u001f]{1,120}\.md(\.disabled)?$/

含 /、\、:、盘符、绝对路径、..、空名的输入全部抛错拒绝。已实测 7 类穿越攻击(见下)。

测试

自带一套零依赖测试(不需要 npm install):

node tests/run.mjs

文件	覆盖
tests/priority.test.mjs	段注册与 order、front matter 解析与拼写变体、越界夹取、畸形头不报错、预算按优先级裁剪、RPC 优先级往返、写入不破坏/不重复头
tests/regression.test.mjs	路径穿越防护(7 类 × 4 个方法)、CRUD 生命周期、Fetch 路由请求形状校验、无残留临时文件
tests/client-bundle.test.mjs	bundle 注册、slot 注册、页面在分档数据下的渲染

测试全部使用独立的临时目录,不会读写你真实的 rules/。

已验证

项	结果
配置树组合(dsh --dump-config)	插件行正确注入,无加载错误
独立实例启动(dsh web --port 0)	正常启动,不破坏 DSH
client bundle 投递	200,内容完整,含 settings.section 注册
RPC 端到端(含认证)	200,rules.list 返回四档元数据
优先级端到端	建 P0 规则 → front matter 落盘 → 改档生效 → 删除
CRUD 全循环	建 / 改 / 停 / 删 全通
路径穿越防护	../、..\、绝对路径、子目录、ok.md/../x.md、空名 —— 4 个方法全部拒绝
规则真实注入	会话日志 system/message 中确认出现规则全文
测试套件	3/3 文件通过(共 92 项执行断言)

实现说明

两半组成:

• host 半(lib/index.js):扫描规则目录(带 (mtimeMs, size) 缓存,外部编辑可见)、注册 systemPrompt.section()、提供 connection.fetch.register() 的 CRUD RPC 路由。
• client 半(lib/client/rules-panel.js):手写 CommonJS bundle,无构建步骤。用 React.createElement(不用 JSX),只 require('react'),通过 window.__ModuleLoader__.load() 注册。改完刷新页面即可。

两个刻意的实现选择:

1. interpolate: false — 规则是用户手写的散文,可能含字面 {{...}};而 system-prompt 的变量插值是严格的,未知引用会抛错。规则文本绝不能有能力搞崩提示词装配。
2. ctx.inject(['connection'], …) 而非 ctx.get('connection') — 前者会等 connection 服务真正出现再注册路由,消除「服务晚于插件激活」的时序竞态。而 connection 刻意不放进静态 inject 列表:headless / CLI profile 没有 Connection,静态 inject 会让插件(连同规则)在那里装不上。

已知取舍

• 暂停靠改名,会在磁盘留痕 —— .disabled 是真实文件名变更。若该目录在 git 里,git status 会多一行改名;不 git add 就不会进索引。
• GUI 面板本身需要刷新浏览器才能看到 —— host 侧即时生效,但 client bundle 的 boot graph 是启动时生成的。
• 读是同步的 —— systemPrompt 的 text 提供者必须同步返回字符串,因此用 readFileSync;文件很小,且有 stat 缓存。
• 不接管 $DSH_HOME/AGENTS.md —— 官方插件继续读它,两者并存互不干扰。
• 段顺序固定为 order: 100,暂不支持逐条排序(靠文件名数字前缀控制)。

License

MIT