dsh-rule-engine

项目背景

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

• 作者是零编程基础用户，但极其重视规则的制定、执行、遵守与复盘。
• 作者发现：规则如果只写在文本里、靠模型“自觉”执行，会反复失效（例如时间词写错、内联命令违规、交付前漏验证等）。
• 因此核心思路是：规则的执行不能只靠自觉，要尽量靠插件在机制层强制。
• 本插件所有规则均从 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）生效。命令面见下一章。

配置

两轨：通用层与个人层

一句话：代码里只有机制；中文与本机专属设置都写在 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 }
}

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

加一个词怎么做

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

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

质量账本怎么看

默认关闭。开启后：

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

命令

任务契约与反过度工程默认关闭：可在设置页开启总开关，开启后默认观察模式（只审计提醒），切到 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 历史。

致谢

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

• 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