越界拦截 yunling-bionic/dsh-rule-guard

dsh-rule-guard

智能体老是改你没让它改的文件。 这个插件在它动手之前拦住，并把「违反了哪条目标、该怎么改」直接回给它。

在工具真正执行之前插入一次复核：取项目规则 + 当前目标 + 待执行动作，判断该动作是否在当前目标内；不在则拒绝执行，并把违反的目标与修正建议回给模型。

rule-guard 拦截示例

上图为实际运行记录：连续两次 Error: [rule-guard] 这一步不在当前目标之内 ——一次因为改动范围超出指令，一次因为把用户指令里的试探当成了执行请求。

中文 · English

- 版本：0.4.3
- 依赖：DeepSeek Harness ≥ 0.2.x
- 许可：MIT
- 安装：dsh plugin add dsh-rule-guard（或从源码目录 dsh plugin add ./dsh-rule-guard）

一、设计目标

智能体在长任务中容易产生范围外动作：改动未被要求的文件、顺手重构、把构建产物一并纳入修改、偏离当前目标。

本插件在动作落盘之前插入一次独立复核，将这类偏离挡在执行之前。复核由当前会话的模型完成，判定口径与项目规则文件一致。

二、判定原则

判据只有一条：这一动作是否在当前目标之内。

以下内容不作为判据：
- 是否写文件
- 技术风险高低
- 代码风格差异

判决口径为 fail-closed：

| 情形 | 处理 |
| 明确不在目标内 | 拒绝 |
| 复核失败（模型调用异常） | 拒绝 |
| 复核输出不可解析 | 拒绝 |
| 多路判决冲突 | 拒绝 |

本版本不含放行分支（fail-open），亦不提供任何豁免开关。因此表述模糊的指令会被直接拒绝，这是设计取舍：模糊授权不等于授权。

三、送审范围

送审（有副作用的动作）

- 文件写入与编辑（write / edit / str_replace_editor / 脚本内落盘）
- shell 非只读命令（重定向、Set-Content、Remove-Item、装包、起服务等）
- 网络请求、启动子代理、定时任务、桌面操作、office 文档落盘
- 未知工具：默认送审
- 读取工作区之外的路径

免审

- 纯读取，且路径在工作区内
- 只读 shell 白名单（Get-Content、git log 等）

四、使用方式

如需放行，请在指令中同时给出三项信息：做什么、在哪里、为什么。

允许示例：把 E:\SK\视觉\vision_mem_raw.py 的 --win-sec 默认值改为 60，因为瞬时层窗口按 60 秒计算。

拒绝示例：继续 / 优化一下 / 看着办

如需临时放宽力度，应在指令中写明授权范围；插件不提供配置开关：

本轮允许修改 视觉/ 目录下的任何文件，无需逐条确认。
本轮仅执行只读操作，无需复核。

被拒绝时，查看插件目录下的 rule-guard.log：event=deny 的记录包含违反的目标与建议做法。

被拒时的实际样子（会话里直接显示原因，不需要翻日志）：

rule-guard 拒绝示例

上图是一次真实拦截：编辑动作被判「不在当前目标之内」，理由里点名了违反的规则原句（改动只碰被要求的文件。不做顺手重构，不改无关文件……）；紧随其后的一次导出操作同样被拦。

五、工作原理

挂载于 Harness 的 tools/pre-execute 瀑布钩子，在动作执行前插入一次模型复核（temperature=0）：

有副作用的动作 / 未知工具 / 读取工作区外 │ ▼ rule-guard 复核 │ ┌────┴─────┐ ▼ ▼ allow deny │ │ 正常执行 返回错误（违反的目标 + 修正建议），模型修正后重试

复核输入由三部分组成：

1. 项目规则：<工作区>/AGENTS.md、<工作区>/.dsh/rules.md（存在时读取）
2. 当前目标：本会话中用户最近一条指令
3. 待执行动作：工具名、参数，以及脚本正文开头 4 KiB

缓存策略：仅复用「拒绝」判决，按会话隔离，有效期 10 分钟。

六、自定义规则

规则文件由用户掌握，插件只负责读取与执行。定义方式有两种，效果相同：

方式一：手动编辑

在工作区根目录建立并维护 AGENTS.md（或 .dsh/rules.md）：

项目规则

- 只修改用户明确要求的文件，不做顺手重构
- 不改动 dist/、build/ 等产物目录
- 依赖变更必须先说明理由
- 提交前必须通过 npm test

方式二：让 AI 按需修改

直接要求 AI 修改该规则文件即可，例如：

把"提交前必须通过 npm test"加进 AGENTS.md 的项目规则里

两种方式的共同前提：规则文件是数据，可以进版本库、可以回顾改动；插件本身不含硬编码的项目规则。

规则来源（0.4.1 起三者同时生效，按顺序拼接后送入复核）

① <工作区>/AGENTS.md 项目自己的规则，可进版本库 ② <工作区>/.dsh/rules.md 同上，二选一即可 ③ <数据目录>/RULES.md 复核机制的通用规则（首次安装生成，可直接改，改了就生效）

0.4.0 的问题：第 ③ 个文件只生成、不读取，按提示改了不生效。0.4.1 已修。

示例见 examples/AGENTS.md。未提供规则文件时，仅按当前目标判断。

首次安装提示：首次加载时通过客户端横幅提示（可关闭，只弹一次），同时在标准插件数据目录生成 RULES.md 与 INSTALL-NOTICE.txt，并向 rule-guard.log 记一条 first-run-notice：

标准插件数据目录（与 dshHomePath('rule-guard') 等价）
Windows %APPDATA%\dsh-desktop\harness\rule-guard\
Linux/mac ~/.dsh/rule-guard/
RULES.md 复核机制的通用规则（首次生成；用户改过则不覆盖） INSTALL-NOTICE.txt 中英文提示原文 .first-run-done 首次标记（存在即不再提示）

横幅由客户端入口 client.js 渲染（注册于 slot shell.overlay），内容为：

rule-guard 已安装 · 规则可以自己定可以自己定规则，方式两种：一是自己手动编辑规则文件；二是直接让 AI 按需要修改这个规则文件。

You can define your own rules. Two ways: edit the rule file by hand, or simply ask the AI
to modify that rule file as needed.

规则文件放在数据目录，不放在安装包内，因此升级插件不会覆盖用户改动。
横幅关闭状态记在浏览器 localStorage（键 dsh-rule-guard:first-run-notice:v1），刷新后不再弹出。

七、日志

插件目录下的 rule-guard.log，每行一条 JSON：

{"ts":"2026-10-31T11:30:00.000Z","event":"deny","tool":"write","session":"sess-abc","call":"call-12","paths":["src/app.ts"],"digest":"","reason":"该写入不在当前目标内","fix":"只修改 README"}

| event | 含义 | 关键字段 |
| plugin-loaded | 插件加载完成 | version |
| allow | 复核通过 | tool paths call |
| deny | 拒绝（含复核失败与不可解析） | reason fix |
| skip | 免审，未复核 | why |
| cache-hit-deny | 同等动作命中缓存拒绝 | paths |

每条记录包含工具名、目标路径、会话 ID、调用 ID 与参数摘要，可用来定位到具体轮次与动作。

常用查询：

Select-String '"event":"deny"' rule-guard.log | Select-Object -Last 5
Select-String 'src/app.ts' rule-guard.log

八、兼容性

- DeepSeek Harness ≥ 0.2.x（依赖 tools/pre-execute、ctx.llm、workingDirectory 服务）
- 已在 DSH Desktop 0.11.1（Harness 0.2.1-rc.2）实测加载

九、成本与限制

- 每次送审增加一次模型调用：约 2–5 秒延迟与少量 token 开销
- 复核使用当前会话的模型，模型能力越强，判定越准确
- 送审范围包含行为类工具、未知工具与工作区外读取
- 判决 fail-closed，表述模糊的指令会被拒绝
- 缓存仅复用「拒绝」，按会话隔离，10 分钟
- 属于软约束：模型可能被措辞误导，不应视为安全边界

十、目录结构

dsh-rule-guard/
├── package.json # dsh.bundle.patch 元数据 ├── cordis.patch.yml # 挂载条目 ├── lib/index.js # 插件实现（无第三方依赖） ├── examples/AGENTS.md # 规则示例 ├── LICENSE └── README.md

License

MIT © 2026 YL（韵铃）