dsh-rule-engine

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

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）生效。命令面见下一章。

配置

两轨：通用层与个人层

层 · 在哪 · 内容 · 谁维护

通用层 · 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 位（归一化：去引号 → 绝对路径替换为 <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 或与上一条完全一致

…(truncated)