jilian-dsh/dsh-rule-engine

dsh-rule-engine

npm
version

项目背景

这个项目来自一个非常具体的个人需求：

- 作者是零编程基础用户，但极其重视规则的制定、执行、遵守与复盘。
- 作者发现：规则如果只写在文本里、靠模型“自觉”执行，会反复失效（例如时间词写错、内联命令违规、交付前漏验证等）。
- 因此核心思路是：规则的执行不能只靠自觉，要尽量靠插件在机制层强制。
- 本插件所有规则均从 AGENTS.md 动态解析，规则增删改后无需重写插件。

当前实现基于已有的 AGENTS.md 规则体系拓展，社区暂无类似插件供参考（大概率为该等约束可能限制开发自由性，不适用于专业编程人员），可能存在大量不完备、误判或边界问题。欢迎任何使用者提出调整建议、提交 issue 或 PR。项目仍处于“可运行但需要持续打磨”的阶段。

这是什么

DSH 规则执行引擎 v3 的插件实现。它把 ~/.dsh/AGENTS.md 当作唯一真相源，自动解析规则四要素与执行等级，再通过「工具守卫 + 文本检测 + 时序检查 + 审计台账」执行你的规则——不是内置一套与用户无关的安全清单。

四层骨架：

1. 容器：解析 AGENTS.md 的全部规则（可生成理解产物）；
2. 匹配机 ＋ 工具守卫 ＋ 文本检测：判断某次动作落在哪条规则上；
3. 时序检查 ＋ 授权询问：把“什么时候做的”纳入判定，必要时弹窗询问；
4. 自证调度 ＋ 命令面：对语义类规则做自证提示，并提供 /guard 命令。

规则全部从 AGENTS.md 实时解析，规则增删改后无需重写插件。语义类判定按「词表只产嫌疑 → 模型裁决确认」两段走：只有裁决确认为违规才提醒；无真实用户消息的回合不检测、不投递。

当前版本

0.6.6（以 package.json 的 version 为准）。

使用指引

安装

本插件已按官方 bundle 规范打包，包内自带 cordis.patch.yml。推荐：

dsh plugin --profile web add dsh-rule-engine

或手动把 dsh-rule-engine 加入 profile 的 dsh.profile.bundles 数组，包内 cordis.patch.yml 会自动挂载插件行：

- insert:
- id: dsh-rule-engine
name: 'dsh-rule-engine'

从源码手动调试时也可以沿用 insert 方式挂载；正式安装建议走 bundle。

最低准备

- 一份规则文件：~/.dsh/AGENTS.md（或你的 DSH_HOME 下的同名文件）。没有它也能用——引擎零错加载、零规则、零误拦。
- Node.js >=22（见 package.json 的 engines）。
- 无运行时依赖；两个 peer 依赖由 DSH 侧提供。

何时需要配置

默认零配置即可用。 只有下面两类需求才需要写 ~/.dsh/rule-engine.json：

- 想让引擎懂你的语言习惯（例如把中文词当作许可词、动作词）；
- 想启用本机专属集成（统一入口脚本保护、手册/技能豁免、记忆沉淀链、追加受保护文件）。

配置在插件启动时读取；改完保存后重载插件（或重启 DSH）生效。命令面见下一章。

配置

两轨：通用层与个人层

| 层 | 在哪 | 内容 | 谁维护 |
|---|---|---|---|
| 通用层 | lib/（随包发布） | 机制 ＋ 语言无关最小集 | 插件作者 |
| 个人层 | ~/.dsh/rule-engine.json | 你的语言/习惯词表、本机集成开关 | 你 |

一句话：代码里只有机制；中文与本机专属设置都写在 rule-engine.json。

键的取值语义

- 键缺省（不写）→ 用内置默认（通用最小集）；
- 键存在 → 按键完全替换（不做合并，配置即真相）；
- 写 {} 或删键 → 回退内置默认。

个人层能配什么（示例一律占位名）

{
"lexicons": {
"approval": "确认|同意|可以",
"action_words": "执行|落盘|部署"
},
"patterns": {
"time_words": "今天|昨天|刚才",
"self_cert_hints": { "example": "占位词一|占位词二" }
},
"criticismPersonal": ["示例词一", "示例词二"],
"localIntegrations": {
"entryScript": "your-entry-script.mjs",
"protectedFiles": ["skills/your-manual/SKILL.md"],
"m8": { "enabled": true, "entryMarker": "your-entry-script.mjs" },
"manualExempt": {
"skills": ["your-manual", "your-planner"],
"paths": ["your-manual/SKILL.md"]
}
},
"qualityLedger": { "enabled": true, "window": 5 }
}

| 键 | 作用 | 缺省行为 |
| --- | --- | --- |
| lexicons | 行为词表（许可词、动作词、拒绝词、疑问词、状态信号词等） | 用内置通用最小集 |
| patterns | 文本健康检测正则 ＋ 规则激活词 | 用内置通用最小集 |
| criticismPersonal | 批评检测的个人词表（通用层只留语言无关形态） | 空——仅靠形态判据 |
| localIntegrations | 本机集成：entryScript（统一入口脚本名）／protectedFiles（追加受保护文件）／m8（记忆沉淀链）／manualExempt（手册与技能豁免） | 全部不存在：配置存在＝守卫存在，配置不存在＝该守卫在代码路径上根本不存在 |
| qualityLedger | 质量账本（每单一行，默认关；不开不产生任何文件） | 关闭 |

localIntegrations 的设计原则值得单独记一句：不是“可覆盖”，是“默认无”——通用用户零配置即零本机行为，发布物无权限制其他用户的写入方式。

加一个词怎么做

1. 打开 ~/.dsh/rule-engine.json（或你 DSH_HOME 下的同名文件）；
2. 在 lexicons / patterns 里找到对应键，用 | 追加词（正则元字符需转义）；
3. 保存 → 重载插件（或重启 DSH）；
4. 想回滚：删掉该键 → 恢复内置默认。

非法正则/未知键会在启动时记审计，不会静默半套生效。

质量账本怎么看

默认关闭。开启后：

- 数据落在 ~/.dsh/quality-ledger.jsonl（每单一行，本机数据，永不发布）；
- 在输入框里查趋势：/guard quality（账本未开启或无记录时如实说明，不编造趋势）；
- 落盘的是单向指纹，不是原文：签名 = sha256(归一化内容) 取前 12 位（归一化：去引号 → 绝对路径替换为  → 数字替换为  → 折叠空白 → 小写），机制层公开可审计；
- 每单记录 rework（返工数）、interventions（介入数）、frictions（引擎拦截次数）、tokens；
- 该机制不拦截、不评分、不上传——纯旁路统计。

命令

| 命令 | 作用 |
|---|---|
| /guard status | 引擎状态（规则数/置信度/放行/解锁） |
| /guard rules | 规则清单 + 理解产物 |
| /guard active | 最近激活了哪些规则、为什么 |
| /guard log [N] | 最近 N 条审计 |
| /guard unlock [N] | 解锁配置写保护 N 分钟（仅用户） |
| /guard bypass [N] | 临时整体放行 N 分钟（仅用户） |
| /guard lock | 立即恢复全部守卫（取消解锁/放行） |
| /guard revoke | 撤销全部授权记录 |
| /guard reload | 强制重解析 AGENTS.md |
| /guard mode  | 设置任务契约模式（review/answer/change/monitor/watch/off） |
| /guard budget ... | 设置预算（agents=N files=... deps=allow hash=allow） |
| /guard contract | 查看当前任务契约 |
| /guard contract categories ... | 设定契约类别白名单（build/test/install 等非破坏类） |
| /guard label   | 给审计记录打标（correct/incorrect/inconclusive） |
| /guard tools | 查看工具放行白名单（永久+本会话，含时间/来源会话） |
| /guard tools revoke  | 撤销白名单条目（持久化+会话集同步移除） |

任务契约与反过度工程默认关闭：可在设置页开启总开关，开启后默认观察模式（只审计提醒），切到 armed 才真正拦截；把某个操作锁进“只读/只改”等边界，用的是 /guard mode。

权限与失败边界

面向插件商城自动审核与安装者；普通用户可跳过。

- 文件访问：读写插件私有状态文件（审计台账、工具白名单、验证通过记录、回合末判例卡片）；读取你的 AGENTS.md 与 rule-engine.json。写入仅限插件私有状态文件；对用户业务文件的写动作只在你的规则触发的守卫流程内执行（例如版本守卫的备份/回滚）。
- 网络：仅两处只读 GET（GitHub release 检查、升级影响读取），8 秒超时、无凭据、无请求体，地址由 package.json 解析（不访问任意地址）。
- 命令执行：无 child_process／子进程调用；“命令检测”= 对命令文本做正则分析（词表），不运行任何被检测的命令。
- 凭据：只读取运行配置类环境变量（如 DSH_LLM_PROVIDER／DSH_LLM_MODEL／DSH_WORKSPACE）；不读取 API Key、令牌；审计与注入消息不含凭据。
- 依赖：无运行时 dependencies；peer 依赖为官方接口包；package.json 无安装期生命周期脚本。
- 失败边界：模型裁决/意图兜底不可用时 fail-closed（不投递、不误放）；审计写入失败不阻断拦截（拦截先于落盘）；低置信判定不参与硬拦；守卫拒绝只针对变更类动作，只读操作无条件放行。
- 权限等级（保守自评）：高（可写持久状态、访问只读网络端点、读取环境变量配置）——建议安装前阅读本章并按需二次审查。

安全设计要点（与上面同源，单独列出便于速览）：

- 只读操作（read / grep / glob / read_image / str_replace_editor view）无条件放行，拦截只针对变更类操作；
- 插件自身配置与理解产物对模型只读：直接 edit/write 会被守卫拒绝，需解锁；
- AGENTS.md 变化后自动重解析（watch ＋ stat 兜底），规则增删改无需重启；而修改插件自身 lib 代码后必须重启 DSH 生效，重启后以行为实测验证；
- 授权证据按“操作类型 ＋ 目标路径前缀”结构化匹配，区分“询问”与“授权”；授权默认 10 分钟 TTL，无路径的全局授权缩短为 2 分钟，可一键撤销；
- 备份证据按“目标路径 → 备份路径”记录，删除/覆盖前必须存在对应路径且备份文件真实存在；
- 版本/手册类文件写后自检：版本号连续、append 不覆盖上一行，失败自动回滚并审计；
- 跨工具一致性：同一敏感操作经 edit / write / str_replace_editor / pwsh 必须得到相同结论；
- 命令输出静默错误检测：全 false/0/null 或与上一条完全一致时审计 ＋ 注入提醒，不阻断；
- 消息注入判别：user/message 先判来源，系统/插件注入一律跳过（不覆盖回合状态、不产生授权），并留审计；
- 工具分类制：工具按 analysis / artifact / mutating / unknown 四类判定；未写 unknownPolicy 或写成 off 时首次调用放行并留审计，写成 deny 才拒绝，写成 ask 才询问；取值不区分大小写和首尾空格，认不出的取值按拒绝处理；已归类的只读命令按命令链分段判定后无条件放行；
- 授权双轨：自动来源授权绝不写入全局池（全局仅显式白名单）；
- 技能目录实时联动、D 级自证泛化、审计日志集中于插件私有状态文件、守卫使用单调拒绝（模型无法自行绕过）。

局限

当前版本已经具备完整四层骨架，但距离“成熟”仍有距离。以下方向难度较高、尚未完全实现，欢迎社区共同推进：

1. 理解器深化：目前只对低置信规则做一次增量理解；未来应支持规则变更窗口期、增量重理解、低置信人工复核队列。
2. 授权语义精确化：当前询问授权记录偏宽泛（类型 ＋ 路径前缀）；未来可要求在面板上显式声明操作类型，或支持“一次授权仅针对单个调用”。
3. 备份证据完整化：当前只校验备份文件存在；未来可增加哈希/大小一致性校验、备份链管理与自动清理。
4. 流程类规则深度执行：涉及下载校验、会话多层验证、版本判断、知识沉淀等业务语义的规则，目前偏“自证提示”，尚未做到机器可判定。
5. 跨会话持久化：授权/备份目前为内存态，重启失效；持久化涉及写入保护、并发与恢复，风险较高，暂未实现（验证通过记录已持久化，不受此限）。
6. 输出文本实时拦截：受平台架构限制，助手消息无法“拦下不发”，只能事后审计 ＋ 纠正注入——这是平台边界，不是插件能单独突破的。

版本更新

只收已发布版本，每行一句变化。历史全量见 git 历史。

| 版本 | 日期 | 变化 |
| --- | --- | --- |
| 0.6.6 | 2026-09-23 | 分域词表迁配置；契约拒绝进卡片／deniedKeys；ask 按类型授权；unknownPolicy 缺键默认放行；规则2按 lane 记账与合并投递 |
| 0.6.5 | 2026-09-20 | 注释里的行号引用改为稳定标识 |
| 0.6.4 | 2026-09-10 | 待决询问提升为会话级；官方 bundle 豁免兑现（装配不一致的收敛豁免）；授权登记改复数路径、多路径匹配 |
| 0.6.3 | 2026-09-09 | 词表全量配置化；新增分层残留闸与三项门禁修复 |
| 0.6.2 | 2026-09-08 | 兼容新版 Remote 合同；peer 锚扩；只读白名单 3 轮扩充 |
| 0.6.1 | 2026-09-07 | 发布脚本豁免预插；豁免判定单源化；发布语境严格计数 |
| 0.6.0 | 2026-09-04 | 通用与本机分离：本机集成层改为“配置存在＝守卫存在”；相应语义反转 |
| 0.5.17 | 2026-09-03 | 时间词拆组（当下词与历史日期分判）；证据锚扩充 |
| 0.5.16 | 2026-09-02 | 批评≠授权双层重构（强形态直接提醒／弱形态交裁决）；权限披露 |
| 0.5.15 | 2026-09-02 | 回合末裁决卡片（可交互；判例登记一次性；重启不丢） |
| 0.5.14 | 2026-09-01 | 分点三柱；技能词收紧；引证检测扩展；查证纪律 |
| 0.5.13 | 2026-08-31 | 通用化（声明式绑定/禁用语义/会话寻址/验证通道）＋ 阶段二三能力 |
| 0.5.12 | 2026-08-30 | 意图优先级修正、意图兜底同步等待、只读判定三档、授权粒度并入会话 |
| 0.5.11 | 2026-08-29 | 判定内核第一轮：新建豁免、分析通道收紧、判据同源、词表唯一源 |
| 0.5.10 | 2026-08-27 | 分析通道单真源、写类判定单真源、统一入口加固、误判打标闭环 |
| 0.5.9 | 2026-08-27 | 工具分类单真源、官方工具全集覆盖、前缀自动归类、未归类工具默认拒绝 |
| 0.5.8 | 2026-08-26 | 白名单持久化、只读命令词表补全 |
| 0.5.7 | 2026-08-26 | 注入噪音治理（词表只产嫌疑＋裁决＋投递资格闸＋审计完整性）；注入通道重入修复 |
| 0.5.6 | 2026-08-26 | 同回复聚合注入、已自证规则不重复触发、规则统计面板接口 |

致谢

感谢以下项目与作者的无私开源付出，本项目在开发过程中直接受益：

- DeepSeek Harness 官方团队（@deepseek-ai）：提供了 DSH 平台、插件机制与官方文档。
- 社区插件的作者们：
- dsh-guardian（lonelymoon87）
- dsh-visualize（Nagi-ovo）
- dsh-rules-manager（jilian-dsh）
- dsh-vision-router、dsh-example-injector 等未列出的作者
- 设计思想与机制来源（本项目直接内化/借鉴）：
- stop-that-shit（lennney）：任务边界、反过度工程、预算与四类越界——任务契约模块的设计源头。
- dsh-agi-harness（yjh051108）：闸=最小决策单元、Wilson 下界、拒因即指路、自由面/盲区显式声明、任务签名+质量趋势（quality-ledger）、变异测试+棘轮。
- Claude Code 权限范式（Anthropic 官方文档）：默认询问、deny 永远赢、通配符规则只加不放。
- mattpocock/skills「writing-for-agents」：写给 agent 的文档方法论。
- dsh-zvec-grep（sugarforever）：后台任务型插件写法。
- 升级与审查工具链：
- oh-my-dsh / dsh-plugin-upgrade-skill（社区）：0.1.2 升级卡库与对策集。
- build-dsh-plugin（AI-Scarlett）：插件完备性审计。
- cordis-plugin-thinking-loop-guard（argszero）：纯思考空转的源码级判读。
- 学习参考的社区文档/库作者：
- dsh-handbook（Electricitysheep）
- SandBase deepseek-harness-handbook（sandbaseai）
- awesome-dsh-plugin / Oh! dsh（生态目录）
- 以及 DSH 官方文档镜像与源码维护者
- 贡献建议与实证的个人：TheBuilderJR、Reximmortal1021、AI-Scarlett、ckcfcc、goatliamia 等。

免责声明
本项目是个人/社区项目，不属于 DeepSeek Harness 官方项目，与官方无隶属关系。使用风险自负，请在生产环境前充分测试。

许可证

MIT