dsh-rule-engine

dsh-rule-engine

项目背景

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

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

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

这是什么

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

四层骨架：

• 容器：解析 AGENTS.md 的全部规则（可生成理解产物）；
• 匹配机 ＋ 工具守卫 ＋ 文本检测：判断某次动作落在哪条规则上；
• 时序检查 ＋ 授权询问：把“什么时候做的”纳入判定，必要时弹窗询问；
• 自证调度 ＋ 命令面：对语义类规则做自证提示，并提供 /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 的设计原则值得单独记一句：不是“可覆盖”，是“默认无”——通用用户零配置即零本机行为，发布物无权限制其他用户的写入方式。

加一个词怎么做

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

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

质量账本怎么看

默认关闭。开启后：

• 数据落在 ~/.dsh/quality-ledger.jsonl（每单一行，本机数据，永不发布）；
• 在输入框里查趋势：/guard quality（账本未开启或无记录时如实说明，不编造趋势）；
• 落盘的是单向指纹，不是原文：签名 = sha256(归一化内容) 取前 12 位（归一化：去引号 → 绝对路径替换为 <path> → 数字替换为 <n> → 折叠空白 → 小写），机制层公开可审计；
• 每单记录 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 <id> <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 级自证泛化、审计日志集中于插件私有状态文件、守卫使用单调拒绝（模型无法自行绕过）。

局限

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

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

版本更新

只收已发布版本，每行一句变化。历史全量见 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 官方项目，与官方无隶属关系。使用风险自负，请在生产环境前充分测试。

License

MIT