dsh-rule-engine 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-rule-engine contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# dsh-rule-engine
+
+DSH 规则执行引擎 v3 的插件实现。它把 `~/.dsh/AGENTS.md` 当作唯一真相源，自动解析规则四要素与执行等级，再通过「工具守卫 + 文本检测 + 时序检查 + 审计台账」执行用户规则，而不是内置一套与用户无关的安全清单。
+
+## 项目背景
+
+这个项目来自一个非常具体的个人需求：
+
+- 作者是**零编程基础**用户，但极其重视规则的制定、执行、遵守与复盘。
+- 作者发现：规则如果只写在文本里、靠模型“自觉”执行，会反复失效（例如时间词写错、内联命令违规、交付前漏验证等）。
+- 因此核心思路是：**规则的执行不能只靠自觉，要尽量靠插件在机制层强制**。
+- 本插件所有规则均从 `AGENTS.md` 动态解析，规则增删改后无需重写插件。
+
+当前实现基于已有的 `AGENTS.md` 规则体系拓展，社区暂无类似插件供参考（大概率为该等约束可能限制开发自由性，不适用于专业编程人员），**可能存在大量不完备、误判或边界问题**。欢迎任何使用者提出调整建议、提交 issue 或 PR。项目仍处于“可运行但需要持续打磨”的阶段。
+
+## 功能分层
+
+- 阶段 1 容器：解析 AGENTS.md 全部规则 → 理解产物（`rule-understanding.json` 可生成）
+- 阶段 2 匹配机 + 工具守卫 + 文本检测
+- 阶段 3 时序检查 + 授权询问集成
+- 阶段 4 D 级自证调度 + `/guard` 命令完善
+
+当前实现以「模式库兜底」为主，LLM 理解器预留扩展点；所有规则均从 AGENTS.md 实时解析。
+
+## 命令
+
+| 命令 | 作用 |
+|---|---|
+| `/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 |
+
+## 装配方式
+
+本插件已按官方 **bundle** 规范打包，包内自带 `cordis.patch.yml`。
+
+推荐安装方式：
+
+```bash
+dsh plugin --profile web add dsh-rule-engine
+```
+
+或手动将 `dsh-rule-engine` 加入 profile 的 `dsh.profile.bundles` 数组。包内的 `cordis.patch.yml` 会自动挂载插件行：
+
+```yaml
+- insert:
+    - id: dsh-rule-engine
+      name: 'dsh-rule-engine'
+```
+
+如果你是从源码手动调试，也可以沿用 insert 方式挂载，但正式安装建议走 bundle。
+
+## 安全设计
+
+- 只读操作（read/grep/glob/read_image/str_replace_editor view）无条件放行，拦截只针对变更类操作
+- 插件自身配置/理解产物对模型只读：直接 `edit/write` 会被守卫拒绝，需 `/guard unlock`
+- AGENTS.md mtime 变化后自动重解析（`fs.watch` + stat 兜底），规则增删改无需重启
+- 低置信规则不参与硬拦，避免误伤；在 `/guard rules` 中标记人工复核
+- 授权证据按“操作类型 + 目标路径前缀”结构化匹配，区分“询问”与“授权”
+- 备份证据按“目标路径 → 备份路径”记录，删除/覆盖前必须存在对应路径且备份文件真实存在
+- 版本/手册类文件写后自检：版本号连续、append 不覆盖上一行，失败自动回滚并审计
+- 跨工具一致性：同一敏感操作经 `edit` / `write` / `str_replace_editor` / `pwsh` 必须得到相同拦截/放行结论
+- 命令输出静默错误检测：全 false/0/null 或与上一条完全一致时审计 + 注入提醒，不阻断
+- 技能目录实时联动：`ctx.skills` 目录变化后自动刷新，已禁用/不存在的技能不触发 12B
+- LLM 增量理解：对非 high 置信规则调用 `ctx.llm` 补全结构化理解，失败自动回退模式库
+- D 级自证泛化：按规则特征触发自证提示，每规则每会话限 3 次
+- 授权记录默认 10 分钟 TTL，无路径的全局授权 TTL 缩短为 2 分钟；可用 `/guard revoke` 撤销
+- 用户直接命令式指令（如“删除这个文件”）也视为授权
+- 规则 1 支持“用户明确要求重试”豁免
+- 会话状态有容量上限并自动清理，防止长跑内存膨胀
+- LLM 理解按“规则 + AGENTS.md mtime”去重，避免重复烧 token
+- 审计日志：`~/.dsh/rule-engine.log.jsonl`
+- 守卫使用 `ctx.tools.guard()` 单调拒绝，模型无法自行绕过
+
+## 当前局限与后续优化路线
+
+当前版本已经具备完整四层骨架，但距离“成熟”仍有距离。以下是一些**难度较高、尚未完全实现**的优化方向，欢迎社区共同推进：
+
+1. **LLM 理解器深化**
+   当前只对非 high 置信规则做一次 LLM 增量理解；未来应支持“规则变更窗口期”、增量重理解、低置信人工复核队列。
+
+2. **授权语义精确化**
+   当前 ask 授权记录为宽泛 `any` + 路径前缀；未来可要求 ask 面板显式声明操作类型，或支持“一次授权仅针对单个 callId”。
+
+3. **备份证据完整化**
+   当前校验备份文件存在；未来可增加哈希/大小一致性校验、备份链管理与自动清理。
+
+4. **规则 12C / 13B / 10 / 15 / 19 等流程类规则深度执行**
+   这些规则需要更多业务语义（下载校验、会话三层验证、版本判断、知识沉淀），目前偏“自证提示”，尚未做到机器可判定。
+
+5. **跨会话持久化**
+   授权/备份目前为内存态，重启失效。持久化涉及写入保护、并发与恢复，风险较高，暂未实现。
+
+6. **输出文本实时拦截**
+   受 DSH 官方架构限制，`assistant/message` 无法“拦下不发”，只能事后审计 + 纠正注入；这是平台边界，不是插件能单独突破的。
+
+## 致谢
+
+感谢以下项目与作者的无私开源付出，本项目在开发过程中直接受益：
+
+- **DeepSeek Harness 官方团队（@deepseek-ai）**：提供了 DSH 平台、插件机制与官方文档。
+- **本机已安装插件的作者们**：
+  - dsh-guardian（lonelymoon87）
+  - dsh-visualize（Nagi-ovo）
+  - dsh-usage（kestiny18）
+  - dsh-rules-manager（jilian-dsh）
+  - dsh-vision-router、dsh-super-injector 等未列出的作者
+- **学习参考的社区文档/库作者**：
+  - dsh-handbook（Electricitysheep）
+  - SandBase deepseek-harness-handbook（sandbaseai）
+  - 以及 DSH 官方文档镜像与源码维护者
+
+## 免责声明
+
+本项目是**个人/社区项目**，**不属于 DeepSeek Harness 官方项目**，与官方无隶属关系。使用风险自负，请在生产环境前充分测试。
+
+## 开发与测试
+
+```bash
+npm test
+bash scripts/build.sh
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,7 @@
+# dsh-rule-engine bundle 配置层
+# 按官方 bundle 规范：插件行按包名引用，由 Node 模块解析定位已安装代码。
+- insert:
+    - id: dsh-rule-engine
+      name: 'dsh-rule-engine'
+    - id: dsh-rule-engine-service
+      name: 'dsh-rule-engine/lib/service.js'

package/lib/core/audit.js

@@ -0,0 +1,44 @@
+// audit.js - 审计台账（JSONL）。
+// 每次拦截/纠察/自证都追加一行；超限自动裁剪保留尾部。
+import { appendFileSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { auditFilePath } from "./paths.js";
+
+const LOG_MAX_BYTES = 512 * 1024;
+const LOG_KEEP_LINES = 400;
+
+export function audit(entry) {
+  try {
+    const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n";
+    appendFileSync(auditFilePath(), line, "utf8");
+    trimLog();
+  } catch {
+    // 审计失败不阻断主流程
+  }
+}
+
+function trimLog() {
+  try {
+    const p = auditFilePath();
+    if (statSync(p).size <= LOG_MAX_BYTES) return;
+    const lines = readFileSync(p, "utf8").split("\n");
+    const kept = lines.slice(-LOG_KEEP_LINES).join("\n");
+    writeFileSync(p, kept, "utf8");
+  } catch {
+    // 裁剪失败忽略
+  }
+}
+
+export function readAuditLog(n) {
+  try {
+    const lines = readFileSync(auditFilePath(), "utf8").split("\n").filter(Boolean);
+    return lines.slice(-n).map((line) => {
+      try {
+        return JSON.parse(line);
+      } catch {
+        return { raw: line };
+      }
+    });
+  } catch {
+    return [];
+  }
+}

package/lib/core/authorization.js

@@ -0,0 +1,227 @@
+// authorization.js - 授权证据结构化匹配（P0：授权关联具体操作，区分询问与授权）
+// 纯函数，可独立测试。
+import { GENERIC_EXEC_TOOLS, pathTarget, commandText, writeTargetPathsFromCommand } from "./patterns.js";
+
+export const AUTH_TTL_MS = 10 * 60 * 1000;
+
+const AUTH_WORDS_RE = /(?:可以|同意|授权|去做|开始|执行吧|批准|允许|确认|好的|行|去吧|ok|yes)/i;
+const QUESTION_WORDS_RE = /(?:影响吗|可以吗|要不要|是否|能不能|行不行|需不需要|吗\s*$|？|\?)/i;
+const DIRECTIVE_RE = /(?:请\s*)?(?:删除|移除|修改|编辑|替换|写入|创建|复制|移动|执行|运行|下载|提交|推送|备份|安装|卸载|清理|启动|停止|重建|修复|保存)/i;
+const APPROVAL_RE = /(?:允许|同意|可以|是|好|确认|授权|执行|批准|去吧|开始|ok|yes)/i;
+const REJECTION_RE = /(?:不允许|拒绝|不要|否|取消|不同意|no|No)/i;
+
+const TYPE_HINTS = [
+  { re: /删除|移除|remove|delete/i, type: "delete" },
+  { re: /修改|编辑|替换|写入|写文件|edit|write|replace/i, type: "write" },
+  { re: /备份|backup/i, type: "backup" },
+  { re: /git\s+(push|commit)|提交|推送/i, type: "git" },
+  { re: /执行|命令|运行|run|execute|pwsh|bash/i, type: "command" },
+  { re: /技能|skill/i, type: "skill" },
+  { re: /下载|网络|curl|fetch/i, type: "network" }
+];
+
+const PATH_TOKEN_RE = /["'][A-Za-z]:[\\/](?!\/)[^"']+["']|[A-Za-z]:[\\/](?!\/)[^\s'"`，。；：！？（）【】《》、]+|(?:^|[\s"'`])\/(?:[^\s"'`，。；：！？（）【】《》、]+)/g;
+
+export function normalizePath(p) {
+  if (typeof p !== "string") return "";
+  return p.replace(/\\/g, "/").toLowerCase();
+}
+
+/** 从文本推断操作类型 */
+export function inferTypeFromText(text) {
+  const s = String(text || "");
+  for (const hint of TYPE_HINTS) {
+    if (hint.re.test(s)) return hint.type;
+  }
+  return "any";
+}
+
+/** 从文本提取路径前缀（取最长的路径 token；支持引号包裹的含空格路径） */
+export function inferPathPrefixFromText(text) {
+  const s = String(text || "");
+  const matches = s.match(PATH_TOKEN_RE) || [];
+  if (matches.length === 0) return "";
+  const normalized = matches
+    .map((m) => normalizePath(m.replace(/^["']|["']$/g, "")))
+    .filter(Boolean);
+  if (normalized.length === 0) return "";
+  return normalized.sort((a, b) => b.length - a.length)[0];
+}
+
+/** 从一次工具调用推导操作范围 */
+export function operationOf(toolName, args) {
+  const name = String(toolName || "");
+  const p = pathTarget(args);
+  const cmd = commandText(args);
+  let type = "any";
+  let pathPrefix = "";
+
+  if (name === "edit" || name === "write" || (name === "str_replace_editor" && args?.command !== "view")) {
+    type = "write";
+    pathPrefix = normalizePath(p || "");
+  } else if (name === "pwsh" || name === "bash") {
+    const text = cmd || "";
+    type = inferTypeFromText(text);
+    if (/git\s+(push|commit)/i.test(text)) type = "git";
+    else if (/remove-item|rm\s+-r|rmdir|del\s+/i.test(text)) type = "delete";
+    else if (/backup|copy-item[^\n]*\.(?:bak|backups)[\\/]?|copy-item[^\n]*trash-/i.test(text)) type = "backup";
+    else if (/set-content|add-content|out-file|writealltext|copy-item|move-item|rename-item/i.test(text)) type = "write";
+    const writeTargets = writeTargetPathsFromCommand(text).map(normalizePath).filter(Boolean);
+    pathPrefix = writeTargets.sort((a, b) => b.length - a.length)[0] || inferPathPrefixFromText(text);
+  } else if (name === "skill") {
+    type = "skill";
+    pathPrefix = "";
+  } else if (GENERIC_EXEC_TOOLS.has(name)) {
+    type = "command";
+    pathPrefix = "";
+  } else if (name === "ask_user_question") {
+    type = "ask";
+    pathPrefix = "";
+  }
+
+  return { type, pathPrefix };
+}
+
+/** 判断授权记录是否匹配本次操作 */
+export function authMatches(auth, op) {
+  if (!auth || !op) return false;
+  if (auth.type !== "any" && op.type !== "any" && auth.type !== op.type) return false;
+  if (auth.pathPrefix) {
+    const p = normalizePath(op.pathPrefix || "");
+    if (!p.startsWith(auth.pathPrefix)) return false;
+  }
+  return true;
+}
+
+/** 在授权列表中查找匹配项，返回最近一条（过期记录忽略） */
+export function findMatchingAuth(auths, op, now = Date.now()) {
+  if (!Array.isArray(auths)) return null;
+  const matches = auths.filter((a) => authMatches(a, op) && (!a.expiresAt || a.expiresAt > now));
+  if (matches.length === 0) return null;
+  return matches.sort((a, b) => (b.at || 0) - (a.at || 0))[0];
+}
+
+export function describeAuth(auth) {
+  if (!auth) return "无";
+  const type = auth.type || "any";
+  const path = auth.pathPrefix ? `路径 ${auth.pathPrefix}` : "全局";
+  const expires = auth.expiresAt ? `｜到期 ${new Date(auth.expiresAt).toISOString()}` : "";
+  return `${type}｜${path}｜${new Date(auth.at || 0).toISOString()}${expires}｜仅本次运行有效`;
+}
+
+export function describeOp(op) {
+  if (!op) return "未知";
+  return `${op.type || "any"}｜路径 ${op.pathPrefix || "未指定"}`;
+}
+
+/** 用户消息是否为“询问影响”而非授权 */
+export function isQuestionMessage(text) {
+  return QUESTION_WORDS_RE.test(String(text || ""));
+}
+
+/** 用户消息是否包含明确授权词（且不是询问句） */
+export function isAuthMessage(text) {
+  const s = String(text || "");
+  return AUTH_WORDS_RE.test(s) && !isQuestionMessage(s);
+}
+
+/** 用户消息是否为直接命令式指令（非询问，视为授权执行） */
+export function isDirectiveMessage(text) {
+  const s = String(text || "");
+  return DIRECTIVE_RE.test(s) && !isQuestionMessage(s);
+}
+
+/** 选项/自由文本是否表示批准 */
+export function isApprovalText(text) {
+  return APPROVAL_RE.test(String(text || ""));
+}
+
+/** 选项/自由文本是否表示拒绝 */
+export function isRejectionText(text) {
+  return REJECTION_RE.test(String(text || ""));
+}
+
+/** 从 ask_user_question 的 arguments 中提取问题文本（用于推断授权范围） */
+export function askQuestionText(questions) {
+  if (!Array.isArray(questions)) return "";
+  const parts = [];
+  for (const q of questions) {
+    if (q && typeof q === "object") {
+      if (q.question) parts.push(q.question);
+      if (q.header) parts.push(q.header);
+      if (q.detail) parts.push(q.detail);
+      if (Array.isArray(q.options)) {
+        for (const o of q.options) {
+          if (o && typeof o === "object") {
+            if (o.label) parts.push(o.label);
+            if (o.description) parts.push(o.description);
+          } else if (typeof o === "string") {
+            parts.push(o);
+          }
+        }
+      }
+    } else if (typeof q === "string") {
+      parts.push(q);
+    }
+  }
+  return parts.join(" ");
+}
+
+/** 从 ask_user_question 的结果中提取是否批准 */
+export function askResultApproved(result) {
+  const answers = extractAnswers(result);
+  if (!answers || answers.length === 0) return false;
+  let approved = false;
+  let rejected = false;
+  for (const item of answers) {
+    const texts = [...(item.selected || []), item.custom || ""].filter(Boolean);
+    for (const t of texts) {
+      if (isRejectionText(t)) rejected = true;
+      else if (isApprovalText(t)) approved = true;
+    }
+  }
+  return approved && !rejected;
+}
+
+function extractToolResultText(result) {
+  const msg = result?.message ?? result;
+  const content = Array.isArray(msg?.content)
+    ? msg.content
+    : Array.isArray(result?.content)
+      ? result.content
+      : null;
+  if (!content) return null;
+  const block = content.find((b) => b && b.type === "tool-result");
+  if (!block) return null;
+  const inner = Array.isArray(block.content) ? block.content : [];
+  const text = inner
+    .filter((b) => b && b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text)
+    .join("\n");
+  return text || null;
+}
+
+function extractAnswers(result) {
+  if (!result) return [];
+  if (Array.isArray(result)) return result;
+  if (typeof result === "string") {
+    try {
+      return extractAnswers(JSON.parse(result));
+    } catch {
+      return [];
+    }
+  }
+  // tool/result 事件实际形状：message.content[0] = { type:'tool-result', content:[{type:'text', text:'{...}'}] }
+  const toolText = extractToolResultText(result);
+  if (toolText) {
+    try {
+      return extractAnswers(JSON.parse(toolText));
+    } catch {
+      return [];
+    }
+  }
+  if (Array.isArray(result.answers)) return result.answers;
+  if (Array.isArray(result.value?.answers)) return result.value.answers;
+  if (Array.isArray(result.result?.answers)) return result.result.answers;
+  return [];
+}

package/lib/core/config.js

@@ -0,0 +1,30 @@
+// config.js - 插件配置加载。
+// 配置缺失时使用默认值；损坏时也回退默认并记录错误，避免裸奔。
+import { readFileSync } from "node:fs";
+import { configFilePath } from "./paths.js";
+
+export const DEFAULT_CONFIG = {
+  enabled: true,
+  correctInject: true,
+  selfProtect: true,
+  injectLimitPerRulePerSession: 3
+};
+
+export function loadPluginConfig() {
+  try {
+    const raw = readFileSync(configFilePath(), "utf8");
+    const data = JSON.parse(raw);
+    return {
+      ok: true,
+      error: null,
+      ...DEFAULT_CONFIG,
+      ...(data && typeof data === "object" ? data : {})
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: `配置读取失败，已用默认配置：${error instanceof Error ? error.message : String(error)}`,
+      ...DEFAULT_CONFIG
+    };
+  }
+}