dsh-rule-engine 0.4.3 → 0.5.1

package/README.md

@@ -22,6 +22,13 @@ DSH 规则执行引擎 v3 的插件实现。它把 `~/.dsh/AGENTS.md` 当作唯
 
 当前实现以「模式库兜底」为主，LLM 理解器预留扩展点；所有规则均从 AGENTS.md 实时解析。
 
+## 任务契约与反过度工程（可选）
+
+- 默认**关闭**；可在规则引擎设置页开启「任务边界与反过度工程」总开关。
+- 开启后默认**观察模式**，只审计提醒；切到 `armed` 才真正拦截。
+- 弹窗询问默认**关闭**；`askEnabled` 开启后，对依赖/hash 等动作走官方 approval 询问。
+- 支持 `/guard mode|budget|contract|label` 命令。
+
 ## 命令
 
 | 命令 | 作用 |
@@ -35,6 +42,10 @@ DSH 规则执行引擎 v3 的插件实现。它把 `~/.dsh/AGENTS.md` 当作唯
 | `/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 label <id> <label>` | 给审计记录打标（correct/incorrect/inconclusive） |
 
 ## 装配方式
 
@@ -110,7 +121,6 @@ dsh plugin --profile web add dsh-rule-engine
 - **本机已安装插件的作者们**：
   - dsh-guardian（lonelymoon87）
   - dsh-visualize（Nagi-ovo）
-  - dsh-usage（kestiny18）
   - dsh-rules-manager（jilian-dsh）
   - dsh-vision-router、dsh-super-injector 等未列出的作者
 - **学习参考的社区文档/库作者**：

package/lib/core/audit.js

@@ -3,6 +3,7 @@
 // P2-9：裁剪改为惰性——每 APPEND_TRIM_INTERVAL 次追加才做一次大小检查，
 // 避免每次写入都 statSync（高频 deny/纠察时降低 IO）。
 import { appendFileSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
 import { auditFilePath } from "./paths.js";
 
 const LOG_MAX_BYTES = 512 * 1024;
@@ -13,7 +14,7 @@ let appendCount = 0;
 
 export function audit(entry) {
   try {
-    const line = JSON.stringify({ ts: new Date().toISOString(), ...entry }) + "\n";
+    const line = JSON.stringify({ ts: new Date().toISOString(), eventId: randomUUID(), ...entry }) + "\n";
     appendFileSync(auditFilePath(), line, "utf8");
     appendCount++;
     if (appendCount >= APPEND_TRIM_INTERVAL) {

package/lib/core/config.js

@@ -1,13 +1,22 @@
 // config.js - 插件配置加载。
 // 配置缺失时使用默认值；损坏时也回退默认并记录错误，避免裸奔。
-import { readFileSync } from "node:fs";
+import { readFileSync, writeFileSync } from "node:fs";
 import { configFilePath } from "./paths.js";
 
 export const DEFAULT_CONFIG = {
   enabled: true,
   correctInject: true,
   selfProtect: true,
-  injectLimitPerRulePerSession: 3
+  injectLimitPerRulePerSession: 3,
+  taskContractEnabled: false,
+  askEnabled: false,
+  taskContractMode: "observe",
+  taskContractDefaults: {
+    agentBudget: 0,
+    hashPolicy: "deny",
+    dependencyPolicy: "ask",
+    allowedPaths: null
+  }
 };
 
 export function loadPluginConfig() {
@@ -28,3 +37,23 @@ export function loadPluginConfig() {
     };
   }
 }
+
+/** 合并并保存插件配置（设置页调用；UTF-8 无 BOM） */
+export function savePluginConfig(partial) {
+  const current = loadPluginConfig();
+  const next = {
+    ...current,
+    ...(partial || {}),
+    taskContractDefaults: {
+      ...DEFAULT_CONFIG.taskContractDefaults,
+      ...((current.taskContractDefaults || {})),
+      ...((partial?.taskContractDefaults) || {})
+    }
+  };
+  // 规范化
+  next.taskContractEnabled = next.taskContractEnabled === true;
+  next.askEnabled = next.askEnabled === true;
+  next.taskContractMode = next.taskContractMode === "armed" ? "armed" : "observe";
+  writeFileSync(configFilePath(), JSON.stringify(next, null, 2) + "\n", "utf8");
+  return next;
+}

package/lib/core/contract.js

@@ -0,0 +1,234 @@
+// contract.js - 任务契约（Task Contract）
+// 参考 lennney/stop-that-shit 的 review/answer/change/monitor/watch 模式与预算机制。
+// 纯函数，可独立测试；不依赖 Cordis。
+import { normalizePath } from "./authorization.js";
+
+export const MODES = new Set(["review", "answer", "change", "monitor", "watch", "off"]);
+export const LEVELS = new Set(["watch", "guard", "lock", "off"]);
+export const HASH_POLICIES = new Set(["deny", "ask", "allow"]);
+export const SCOPE_POLICIES = new Set(["deny", "ask", "allow"]);
+
+export function defaultContract() {
+  return {
+    mode: "unconfirmed",
+    level: "watch",
+    agentBudget: 0,
+    agentsUsed: 0,
+    hashPolicy: "deny",
+    allowedPaths: null,
+    dependencyPolicy: "ask",
+    source: "default"
+  };
+}
+
+/** 从 /guard mode 指令解析契约模式；无法解析返回 null */
+export function parseModeCommand(text) {
+  const m = /^mode\s+([a-z]+)(?:\s+(watch|guard|lock|off))?$/i.exec(String(text || "").trim());
+  if (!m) return null;
+  const mode = m[1].toLowerCase();
+  if (!MODES.has(mode)) return null;
+  let level = m[2]?.toLowerCase() || null;
+  if (mode === "watch" || mode === "off") level = level || mode;
+  else if (!level) level = "guard";
+  if (!LEVELS.has(level)) return null;
+  return { mode, level };
+}
+
+/** 从 /guard budget 指令解析预算；无法解析返回 null */
+export function parseBudgetCommand(text) {
+  const s = String(text || "").trim();
+  if (!/^budget\b/i.test(s)) return null;
+  const tokens = s.replace(/^budget\b/i, "").split(/[\s,]+/).filter(Boolean);
+  if (tokens.length === 0) return null;
+  const out = {};
+  let changed = false;
+  for (const token of tokens) {
+    const agents = /^agents=(\d+)$/i.exec(token);
+    if (agents) {
+      out.agentBudget = Math.min(Number(agents[1]), 8);
+      changed = true;
+      continue;
+    }
+    const files = /^files=(.+)$/i.exec(token);
+    if (files) {
+      out.allowedPaths = files[1].split("|").map((v) => normalizePath(v)).filter(Boolean);
+      changed = true;
+      continue;
+    }
+    const hash = /^hash=(deny|ask|allow)$/i.exec(token);
+    if (hash && HASH_POLICIES.has(hash[1].toLowerCase())) {
+      out.hashPolicy = hash[1].toLowerCase();
+      changed = true;
+      continue;
+    }
+    const deps = /^deps=(deny|ask|allow)$/i.exec(token);
+    if (deps && SCOPE_POLICIES.has(deps[1].toLowerCase())) {
+      out.dependencyPolicy = deps[1].toLowerCase();
+      changed = true;
+      continue;
+    }
+  }
+  return changed ? out : null;
+}
+
+/** 从用户自然语言推断任务模式；低置信返回 null */
+export function naturalMode(text, previous = defaultContract()) {
+  const s = String(text || "").trim();
+  if (/^(?:stop|stop now|停止|停下来)[.!。！\s]*$/i.test(s)) {
+    return { mode: "answer", source: "explicit-stop" };
+  }
+  if (/\breview only\b|\b(?:do not|don't) (?:edit|change|fix) (?:anything|the (?:repo|repository|files?|code))\b|只审查|只看不改|不要修改(?:任何|代码|文件)/i.test(s)) {
+    return { mode: "review", source: "natural-explicit" };
+  }
+  if (/\banswer only\b|只回答/i.test(s)) {
+    return { mode: "answer", source: "natural-explicit" };
+  }
+  if (/\bmonitor only\b|只监控|只观察/i.test(s)) {
+    return { mode: "monitor", source: "natural-explicit" };
+  }
+  const wasNonMutating = ["answer", "review", "monitor"].includes(previous.mode);
+  const explicitChange = /^(?:please\s+)?(?:fix|implement|change|apply|patch)\b|^(?:请)?(?:修复|修改|实现|应用补丁)|^把.+(?:修复|修改|改掉)/i.test(s);
+  if (wasNonMutating && explicitChange) {
+    return { mode: "change", source: "natural-explicit" };
+  }
+  return null;
+}
+
+/** 应用一次契约变更（指令/自然语言），返回新契约与是否变化 */
+export function applyContract(previous, patch) {
+  const next = { ...defaultContract(), ...(previous || {}) };
+  if (!patch) return { contract: next, changed: false };
+  let changed = false;
+  if (patch.mode && patch.mode !== next.mode) {
+    next.mode = patch.mode;
+    next.agentsUsed = 0;
+    changed = true;
+  }
+  if (patch.level && patch.level !== next.level) {
+    next.level = patch.level;
+    changed = true;
+  }
+  if (Number.isInteger(patch.agentBudget) && patch.agentBudget !== next.agentBudget) {
+    next.agentBudget = patch.agentBudget;
+    next.agentsUsed = 0;
+    changed = true;
+  }
+  if (patch.hashPolicy && patch.hashPolicy !== next.hashPolicy) {
+    next.hashPolicy = patch.hashPolicy;
+    changed = true;
+  }
+  if (Array.isArray(patch.allowedPaths)) {
+    next.allowedPaths = patch.allowedPaths;
+    changed = true;
+  }
+  if (patch.dependencyPolicy && patch.dependencyPolicy !== next.dependencyPolicy) {
+    next.dependencyPolicy = patch.dependencyPolicy;
+    changed = true;
+  }
+  if (patch.source) next.source = patch.source;
+  if (patch.mode && !patch.level && next.level === "watch") {
+    next.level = "guard";
+    changed = true;
+  }
+  if (next.mode === "unconfirmed" && next.level !== "off") {
+    next.level = "watch";
+  }
+  return { contract: next, changed };
+}
+
+/** 全局是否启用任务契约 */
+export function taskContractActive(config) {
+  return Boolean(config?.taskContractEnabled);
+}
+
+/** 是否处于观察模式（全局 observe 或契约 watch） */
+export function isObserving(contract, config) {
+  if (!taskContractActive(config)) return false;
+  if (config?.taskContractMode === "armed") {
+    return contract?.level === "watch" || contract?.level === "off";
+  }
+  return true;
+}
+
+/** 是否处于 armed（全局 armed 且契约 guard/lock） */
+export function isArmed(contract, config) {
+  if (!taskContractActive(config)) return false;
+  if (config?.taskContractMode !== "armed") return false;
+  return contract?.level === "guard" || contract?.level === "lock";
+}
+
+/** 判断 action 是否在允许路径内 */
+export function pathAllowed(path, allowedPaths) {
+  if (!Array.isArray(allowedPaths) || allowedPaths.length === 0) return true;
+  if (!path) return false;
+  const p = normalizePath(path);
+  return allowedPaths.some((allowed) => {
+    const a = normalizePath(allowed);
+    if (a === "**") return true;
+    if (a.endsWith("/**")) {
+      const prefix = a.slice(0, -3);
+      return p === prefix || p.startsWith(prefix.endsWith("/") ? prefix : prefix + "/");
+    }
+    return p === a;
+  });
+}
+
+/**
+ * 任务契约裁决（纯函数）。
+ * 返回 { outcome: 'allow'|'deny'|'ask'|'report', family, reasonCode, reason, nextStep }
+ */
+export function decideContractAction({ contract, action, config = {} }) {
+  const mode = contract?.mode || "unconfirmed";
+  const level = contract?.level || "watch";
+  if (mode === "unconfirmed" || level === "watch" || level === "off") {
+    return { outcome: "allow", family: null, reasonCode: "CONTROL_INACTIVE", reason: "任务契约未武装，不拦截", nextStep: "" };
+  }
+
+  const nonMutatingMode = ["answer", "review", "monitor"].includes(mode);
+  if (nonMutatingMode && action.mutability === "write") {
+    return { outcome: "deny", family: "I", reasonCode: "MODE_FORBIDS_MUTATION", reason: `任务模式 ${mode} 不允许修改文件`, nextStep: "改用只读操作，或获得明确的 change 授权" };
+  }
+  if (nonMutatingMode && action.mutability === "unknown") {
+    return { outcome: "deny", family: "I", reasonCode: "MUTABILITY_UNPROVEN", reason: `任务模式 ${mode} 下该操作无法证明只读`, nextStep: "改用明确只读命令，或获得 change 授权" };
+  }
+
+  if (action.hashIntent && contract.hashPolicy !== "allow") {
+    if (contract.hashPolicy === "ask" && config.askEnabled) {
+      return { outcome: "ask", family: "H", reasonCode: "HASH_NOT_AUTHORIZED", reason: "检测到哈希/校验和操作，当前 hash=ask", nextStep: "获得 hash=allow 或确认消费者" };
+    }
+    return { outcome: "deny", family: "H", reasonCode: "HASH_NOT_AUTHORIZED", reason: "检测到哈希/校验和操作，当前 hash=deny", nextStep: "使用 hash=allow 或说明消费者" };
+  }
+
+  if (Array.isArray(contract.allowedPaths) && contract.allowedPaths.length > 0 && action.mutability === "write") {
+    const outside = (action.affectedPaths || []).filter((p) => !pathAllowed(p, contract.allowedPaths));
+    if (action.affectedPaths?.length === 0) {
+      return { outcome: "deny", family: "S", reasonCode: "WRITE_PATH_UNPROVEN", reason: "写操作无法证明在文件边界内", nextStep: "使用带明确路径的写工具，或扩大 files= 范围" };
+    }
+    if (outside.length) {
+      return { outcome: "deny", family: "S", reasonCode: "PATH_OUTSIDE_CONTRACT", reason: `写路径超出文件边界：${outside.join(", ")}`, nextStep: "保持在 files= 范围内，或更新文件边界" };
+    }
+  }
+
+  if (action.dependencyIntent && contract.dependencyPolicy !== "allow") {
+    if (contract.dependencyPolicy === "ask" && config.askEnabled) {
+      return { outcome: "ask", family: "S", reasonCode: "DEPENDENCY_NOT_AUTHORIZED", reason: "检测到添加依赖操作，当前 deps=ask", nextStep: "获得 deps=allow 或确认该依赖" };
+    }
+    return { outcome: "deny", family: "S", reasonCode: "DEPENDENCY_NOT_AUTHORIZED", reason: "检测到添加依赖操作，当前 deps=deny", nextStep: "使用 deps=allow 或说明必要性" };
+  }
+
+  if (action.mutability === "delegate" && action.unboundedDelegation) {
+    return { outcome: "deny", family: "S", reasonCode: "UNBOUNDED_DELEGATION", reason: "该委托可能无界启动子代理，无法满足 agents=N", nextStep: "使用显式子代理调用，或关闭任务契约" };
+  }
+
+  const delegationCount = action.mutability === "delegate" ? (Number.isInteger(action.delegationCount) ? action.delegationCount : 1) : 0;
+  if (action.mutability === "delegate" && (contract.agentsUsed + delegationCount > contract.agentBudget)) {
+    return { outcome: "deny", family: "S", reasonCode: "AGENT_BUDGET_EXHAUSTED", reason: `子代理预算不足：已用 ${contract.agentsUsed}/${contract.agentBudget}，本次需要 ${delegationCount}`, nextStep: "继续本地完成，或获得 agents=N 授权" };
+  }
+
+  return { outcome: "allow", family: null, reasonCode: "WITHIN_CONTRACT", reason: "动作在任务契约内", nextStep: "" };
+}
+
+export function contractSummary(contract) {
+  const c = contract || defaultContract();
+  return `mode=${c.mode}; agents=${c.agentsUsed}/${c.agentBudget}; hash=${c.hashPolicy || "deny"}; deps=${c.dependencyPolicy || "ask"}; files=${Array.isArray(c.allowedPaths) && c.allowedPaths.length ? c.allowedPaths.join("|") : "unbounded"}; level=${c.level}`;
+}

package/lib/core/guard-core.js

@@ -25,6 +25,8 @@ import { describeAuth, describeOp, findMatchingAuth, operationOf, askQuestionTex
 import { computeMountSignature, profileNameFromArgs } from "./mount-signature.js";
 import { findBackupForPath, getSessionState, maybeReloadIfChanged } from "./state.js";
 import { isVersionedFile, validateEditedFile } from "./version-guard.js";
+import { decideContractAction, defaultContract, isArmed } from "./contract.js";
+import { classifyAction } from "./overengineering.js";
 
 function sessionIdOf(exec) {
   const agent = exec?.agent;
@@ -160,6 +162,22 @@ export function nonBundleInProfileBundles(name, args) {
   return bad.length ? bad : null;
 }
 
+/** 任务契约守卫：仅在总开关开启且会话 armed 时硬拦；ask 场景交给 tools/pre-execute */
+function taskContractGuardDecision(state, exec, session) {
+  if (!state.taskContract?.taskContractEnabled) return null;
+  const contract = session?.contract || defaultContract();
+  if (!isArmed(contract, state.taskContract)) return null;
+  const action = classifyAction(exec?.name, exec?.arguments);
+  const dec = decideContractAction({ contract, action, config: state.taskContract });
+  if (dec.outcome === "deny") {
+    return makeHit(
+      { ruleId: "__task-contract", title: `任务契约：${dec.reasonCode}`, action: "deny" },
+      `【硬拦截】${dec.reason}（${dec.reasonCode}｜任务契约｜放行：${dec.nextStep || "..."}｜ERR-${Math.random().toString(36).slice(2, 8).toUpperCase()}）`
+    );
+  }
+  return null;
+}
+
 /**
  * 裁决一次工具调用。
  * @param {object} state createState 返回的运行时状态
@@ -181,6 +199,10 @@ export function guardDecision(state, exec, now = Date.now()) {
   // 只读操作无条件放行（read/grep/glob/read_image/str_replace_editor view）
   if (isReadOnlyTool(name, args)) return null;
 
+  // 任务契约守卫（总开关关闭时不生效）
+  const contractHit = taskContractGuardDecision(state, exec, session);
+  if (contractHit) return contractHit;
+
   // E3：已有匹配授权时，拦截重复 ask_user_question，避免 AI 反复询问已授权事项
   if (name === "ask_user_question") {
     const qText = askQuestionText(args?.questions);

package/lib/core/overengineering.js

@@ -0,0 +1,95 @@
+// overengineering.js - 反过度工程模式库（SHIT）
+// 参考 lennney/stop-that-shit：Scope / Hash / Intent / Task thrashing。
+// 纯函数，可独立测试。
+import { commandText, isReadOnlyTool, pathTarget } from "./patterns.js";
+import { normalizePath } from "./authorization.js";
+
+const HASH_RE =
+  /\b(?:get-filehash|sha256sum|sha1sum|md5sum|openssl\s+dgst|certutil\s+-hashfile|checksum)\b/i;
+
+const DEPENDENCY_RE =
+  /\b(?:npm|pnpm|yarn|bun|pip|pip3|poetry|go\s+get|gem\s+install|apt-get\s+install|brew\s+install|winget\s+install)\b[\s\S]{0,120}?\b(?:install|add|update|upgrade|i\b)\b/i;
+
+const READ_WORDS_RE =
+  /\b(?:get-content|get-childitem|get-item|get-command|get-date|select-string|findstr|cat|type|dir|ls|grep|more|netstat|where|test-path|read)\b/i;
+
+/** 是否命中“无消费者哈希/校验和”类动作 */
+export function detectHashIntent(toolName, args) {
+  const name = String(toolName || "");
+  const cmd = commandText(args) || "";
+  if (name === "pwsh" || name === "bash") return HASH_RE.test(cmd);
+  const text = JSON.stringify(args || {});
+  return HASH_RE.test(text);
+}
+
+/** 是否命中“添加依赖”类动作 */
+export function detectDependencyIntent(toolName, args) {
+  const name = String(toolName || "");
+  const cmd = commandText(args) || "";
+  if (name === "pwsh" || name === "bash") return DEPENDENCY_RE.test(cmd);
+  const text = JSON.stringify(args || {});
+  return DEPENDENCY_RE.test(text);
+}
+
+/** 粗分类一次工具调用的可变更性 */
+export function classifyAction(toolName, args) {
+  const name = String(toolName || "");
+  const p = pathTarget(args);
+  const cmd = commandText(args);
+  let mutability = "unknown";
+  if (isReadOnlyTool(name, args)) {
+    mutability = "read";
+  } else if (name === "edit" || name === "write" || (name === "str_replace_editor" && args?.command !== "view")) {
+    mutability = "write";
+  } else if (name === "pwsh" || name === "bash") {
+    // 无法证明只读的一律视为 unknown（armed 下会按 MUTABILITY_UNPROVEN 处理）
+    mutability = "unknown";
+  } else if (name === "subagent" || name === "tool-subagent" || name === "tool-subagent-fork" || name === "workflow") {
+    mutability = "delegate";
+  }
+  const affectedPaths = p ? [normalizePath(p)] : [];
+  const delegationCount = name === "workflow" ? 0 : 1;
+  const unboundedDelegation = name === "workflow";
+  return {
+    mutability,
+    hashIntent: detectHashIntent(name, args),
+    dependencyIntent: detectDependencyIntent(name, args),
+    affectedPaths,
+    delegationCount,
+    unboundedDelegation
+  };
+}
+
+/** 记录一次工具动作（用于 Task thrashing 检测） */
+export function recordAction(session, toolName, args) {
+  if (!session || !Array.isArray(session.recentActions)) session.recentActions = [];
+  const key = `${toolName}:${commandText(args) || JSON.stringify(args || {})}`;
+  session.recentActions.push({ key, at: Date.now() });
+  if (session.recentActions.length > 20) session.recentActions = session.recentActions.slice(-20);
+  return session.recentActions;
+}
+
+/**
+ * 判断是否为重复任务打转（同一工具+同一命令在短时间内出现 ≥3 次）。
+ * 返回 true 时建议注入提醒/升级拦截。
+ */
+export function isRepeatedTaskAction(session, toolName, args, windowMs = 10 * 60 * 1000) {
+  if (!session || !Array.isArray(session.recentActions)) return false;
+  const key = `${toolName}:${commandText(args) || JSON.stringify(args || {})}`;
+  const now = Date.now();
+  const count = session.recentActions.filter((a) => a.key === key && now - a.at <= windowMs).length;
+  return count >= 3;
+}
+
+/** 输出文本中的越界/过度工程表述检测（B/D 级提示用） */
+export function detectOverengineeringText(text) {
+  const s = String(text || "");
+  const hits = [];
+  if (/(?:顺手|顺便|额外|多加|防止以后|以防万一|先加上|先建个)/.test(s) && /(?:重构|依赖|抽象|兼容|迁移|flag|校验|哈希|hash|全量测试|保险)/i.test(s)) {
+    hits.push("检测到可能的过度工程表述：请用 Stop Ladder 四问自证（是否被要求/是否必要/可达证据/省略是否会失败）");
+  }
+  if (/(?:再检查一遍|再跑一次测试|再审计一次|重新验证一遍)/.test(s) && !/(?:新证据|发现|失败|报错|修改后|变更后)/.test(s)) {
+    hits.push("检测到可能的重复打转：请确认是否有新证据，避免 Task thrashing");
+  }
+  return hits;
+}

package/lib/core/state.js

@@ -6,6 +6,7 @@ import { agentsFilePath, disabledRulesFilePath } from "./paths.js";
 import { understandAll } from "./understander.js";
 import { writeUnderstanding } from "./understanding-store.js";
 import { AUTH_TTL_MS } from "./authorization.js";
+import { defaultContract } from "./contract.js";
 
 const MAX_SESSIONS = 200;
 const MAX_RETRY_KEYS = 500;
@@ -34,10 +35,27 @@ export function createState() {
     lastEvent: null,
     reloadCount: 0,
     mountRevision: 0,
-    mountSignature: ""
+    mountSignature: "",
+    taskContract: {
+      taskContractEnabled: false,
+      askEnabled: false,
+      taskContractMode: "observe"
+    },
+    labels: new Map()
   };
 }
 
+/** 把插件配置中的任务契约设置同步到运行时状态 */
+export function applyTaskContractConfig(state, conf) {
+  state.taskContract = {
+    taskContractEnabled: conf?.taskContractEnabled === true,
+    askEnabled: conf?.askEnabled === true,
+    taskContractMode: conf?.taskContractMode === "armed" ? "armed" : "observe",
+    defaults: conf?.taskContractDefaults || {}
+  };
+  return state.taskContract;
+}
+
 /** AGENTS.md mtime 变化时自动重解析（规则 21：规则是流动数据） */
 export function maybeReloadIfChanged(state, now = Date.now()) {
   if (now - state.lastMtimeCheck < MTIME_CHECK_INTERVAL_MS) return false;
@@ -95,7 +113,9 @@ export function getSessionState(state, sessionId) {
       mountAuditSignature: "",
       lastCommandOutput: "",
       lastSeen: Date.now(),
-      turn: freshTurn()
+      turn: freshTurn(),
+      contract: { ...defaultContract(), ...(state.taskContract?.defaults || {}) },
+      recentActions: []
     };
     state.sessions.set(key, s);
   }

package/lib/core/text-detect.js

@@ -7,6 +7,7 @@ import {
   TIME_WORDS,
   URL_RE
 } from "./patterns.js";
+import { detectOverengineeringText } from "./overengineering.js";
 
 /** 从 assistant message 内容中提取纯文本 */
 export function extractAssistantText(message) {
@@ -181,5 +182,16 @@ export function detectViolations({ configs, session, text, reasoningText = "", m
     }
   }
 
+  // 反过度工程/越界表述（Stop Ladder 自证）
+  const overengineeringHits = detectOverengineeringText(text);
+  for (const reason of overengineeringHits) {
+    hits.push({
+      ruleId: "__task-contract",
+      title: "反过度工程",
+      kind: "self-certify",
+      reason
+    });
+  }
+
   return hits;
 }

package/lib/index.js

@@ -32,6 +32,7 @@ import {
   isQuestionMessage
 } from "./core/authorization.js";
 import {
+  applyTaskContractConfig,
   getSessionState,
   maybeReloadIfChanged,
   recordAuthorization,
@@ -41,6 +42,23 @@ import {
 } from "./core/state.js";
 import { state } from "./core/runtime.js";
 import { detectViolations, extractAssistantText } from "./core/text-detect.js";
+import {
+  applyContract,
+  contractSummary,
+  decideContractAction,
+  defaultContract,
+  isArmed,
+  isObserving,
+  naturalMode,
+  parseBudgetCommand,
+  parseModeCommand
+} from "./core/contract.js";
+import {
+  classifyAction,
+  detectOverengineeringText,
+  isRepeatedTaskAction,
+  recordAction
+} from "./core/overengineering.js";
 import { writeUnderstanding } from "./core/understanding-store.js";
 import { agentsFilePath, auditFilePath } from "./core/paths.js";
 import { isVersionedFile, validateEditedFile } from "./core/version-guard.js";
@@ -53,6 +71,7 @@ export const inject = ["tools", "commands", "agents", "workspaceRegistry", "skil
 
 const pluginConfig = loadPluginConfig();
 state.enabled = pluginConfig.enabled;
+applyTaskContractConfig(state, pluginConfig);
 // reloadRules 内部已统一刷新理解产物（P0-3），此处不再重复写
 reloadRules(state);
 
@@ -89,6 +108,14 @@ function parseArgs(raw) {
   return raw || {};
 }
 
+function sessionIdOfExec(exec) {
+  const agent = exec?.agent;
+  if (!agent) return "global";
+  if (typeof agent.session === "object" && agent.session?.id) return agent.session.id;
+  if (typeof agent.session === "string") return agent.session;
+  return "global";
+}
+
 function extractUserText(message) {
   if (!message) return "";
   if (typeof message === "string") return message;
@@ -151,6 +178,23 @@ function handleSessionEvent(ctx, session, event) {
     s.lastUserText = text;
     s.turn.userText = text;
     s.turn.questionOnly = isQuestionMessage(text);
+    if (state.taskContract?.taskContractEnabled) {
+      const patch = naturalMode(text, s.contract);
+      if (patch) {
+        const res = applyContract(s.contract, patch);
+        if (res.changed) {
+          s.contract = res.contract;
+          audit({
+            kind: "task-contract",
+            rule: "__task-contract",
+            name: "任务契约更新",
+            event: "user/message",
+            reason: `${patch.source}: ${contractSummary(s.contract)}`,
+            session: sid
+          });
+        }
+      }
+    }
     if (isAuthMessage(text) || isDirectiveMessage(text)) {
       recordAuthorization(state, sid, {
         type: inferTypeFromText(text),
@@ -201,6 +245,28 @@ function handleSessionEvent(ctx, session, event) {
     if (isManualReadTool(toolName, args)) s.manualReadSeen = true;
     if (toolName === "skill" && args?.name) s.turn.skillNames.push(args.name);
     s.turn.toolNames.push(toolName);
+    if (state.taskContract?.taskContractEnabled) {
+      recordAction(s, toolName, args);
+      if (isObserving(s.contract, state.taskContract)) {
+        const action = classifyAction(toolName, args);
+        const problems = [];
+        if (action.hashIntent && s.contract.hashPolicy !== "allow") problems.push("hash 未授权");
+        if (action.dependencyIntent && s.contract.dependencyPolicy !== "allow") problems.push("依赖未授权");
+        if (isRepeatedTaskAction(s, toolName, args)) problems.push("重复动作打转");
+        if (problems.length) {
+          audit({
+            kind: "task-observe",
+            rule: "__task-contract",
+            name: "任务契约观察",
+            event: "tool/call",
+            tool: toolName,
+            args: summarizeArgs(args),
+            reason: `[观察] ${problems.join("；")}`,
+            session: sid
+          });
+        }
+      }
+    }
     const active = activateForToolCall(state.configs, toolName, args);
     if (active.length) state.lastActive = active.map((c) => ({ ruleId: c.ruleId, title: c.title, reason: `工具 ${toolName} 命中` }));
     return;
@@ -229,6 +295,23 @@ function handleSessionEvent(ctx, session, event) {
       }
     }
 
+    // 任务契约：子代理成功执行后扣减预算（仅 armed 生效）
+    if (!isError && pendingCall && state.taskContract?.taskContractEnabled && isArmed(s.contract, state.taskContract)) {
+      const action = classifyAction(pendingCall.name, pendingCall.args);
+      if (action.mutability === "delegate" && action.delegationCount > 0) {
+        s.contract.agentsUsed += action.delegationCount;
+        audit({
+          kind: "task-budget",
+          rule: "__task-contract",
+          name: "子代理预算扣减",
+          event: "tool/result",
+          reason: `已用 ${s.contract.agentsUsed}/${s.contract.agentBudget}`,
+          session: sid,
+          tool: pendingCall.name
+        });
+      }
+    }
+
     // 规则 27：装配变更成功后全局 revision +1；审计命令输出通过/失败后更新本会话审计 revision
     if (pendingCall) {
       if (!isError && isAssemblyMutationTool(pendingCall.name, pendingCall.args)) {
@@ -414,6 +497,10 @@ const USAGE = [
   "  /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 label <id> <label>  给审计记录打标（correct/incorrect/inconclusive）",
   "",
   "说明：",
   "  - 守卫 = 硬拦截：违反规则的工具调用直接拒绝，模型无法自行绕过；",
@@ -436,6 +523,17 @@ function parseCommand(rawInput) {
   m = text.match(/^log\s*(\d+)?$/i);
   if (m) return { kind: "log", n: m[1] ? Number(m[1]) : 10 };
   if (/^reload$/i.test(text)) return { kind: "reload" };
+  if (/^mode\b/i.test(text)) {
+    const parsed = parseModeCommand(text);
+    if (parsed) return { kind: "mode", ...parsed };
+  }
+  if (/^budget\b/i.test(text)) {
+    const parsed = parseBudgetCommand(text);
+    if (parsed) return { kind: "budget", patch: parsed };
+  }
+  if (/^contract$/i.test(text)) return { kind: "contract" };
+  m = text.match(/^label\s+(\S+)\s+(correct|incorrect|inconclusive)$/i);
+  if (m) return { kind: "label", eventId: m[1], label: m[2].toLowerCase() };
   return { kind: "invalid" };
 }
 
@@ -453,6 +551,7 @@ async function executeGuard(ctx, invocation) {
       const parts = [
         "【规则引擎状态】",
         `  总开关：${state.enabled ? "开启" : "已关闭"}`,
+        `  任务契约：${state.taskContract?.taskContractEnabled ? `开启（模式 ${state.taskContract.taskContractMode}｜ask ${state.taskContract.askEnabled ? "开" : "关"}）` : "关闭"}`,
         `  规则容器：${state.configOk ? `正常（${state.configs.length} 条规则）` : "⚠ " + state.configError}`,
         `  理解置信度：high ${high} / medium ${medium} / low ${low}`,
         `  配置加载：${conf.ok ? "正常" : "⚠ " + conf.error}`,
@@ -525,7 +624,7 @@ async function executeGuard(ctx, invocation) {
           continue;
         }
         const t = (e.ts || "").replace("T", " ").slice(0, 19);
-        parts.push(`  [${t}] ${e.kind || "?"}｜规则 ${e.rule || "?"}｜${e.name || ""}`);
+        parts.push(`  [${t}] ${e.kind || "?"}｜规则 ${e.rule || "?"}｜${e.name || ""}${e.eventId ? `（${e.eventId}）` : ""}`);
         if (e.reason) parts.push(`      原因：${e.reason}`);
         if (e.tool) parts.push(`      工具：${e.tool}｜参数：${e.args || ""}`);
       }
@@ -540,6 +639,42 @@ async function executeGuard(ctx, invocation) {
           (saved.ok ? `\n理解产物已写入：${saved.path}` : `\n理解产物写入失败：${saved.error}`)
       };
     }
+    case "mode": {
+      if (!state.taskContract?.taskContractEnabled) return { kind: "error", text: "任务契约未启用：请先在规则引擎设置页开启总开关。" };
+      const sid = invocation?.session?.id || "global";
+      const s = getSessionState(state, sid);
+      const res = applyContract(s.contract, { mode: command.mode, level: command.level, source: "guard-command" });
+      if (res.changed) {
+        s.contract = res.contract;
+        audit({ kind: "task-contract", rule: "__task-contract", name: "任务契约更新", event: "command", reason: `/guard mode: ${contractSummary(s.contract)}`, session: sid });
+      }
+      return { kind: "success", text: `任务契约：${contractSummary(s.contract)}` };
+    }
+    case "budget": {
+      if (!state.taskContract?.taskContractEnabled) return { kind: "error", text: "任务契约未启用：请先在规则引擎设置页开启总开关。" };
+      const sid = invocation?.session?.id || "global";
+      const s = getSessionState(state, sid);
+      const res = applyContract(s.contract, { ...command.patch, source: "guard-command" });
+      if (res.changed) {
+        s.contract = res.contract;
+        audit({ kind: "task-contract", rule: "__task-contract", name: "任务预算更新", event: "command", reason: `/guard budget: ${contractSummary(s.contract)}`, session: sid });
+      }
+      return { kind: "success", text: `任务契约：${contractSummary(s.contract)}` };
+    }
+    case "contract": {
+      const sid = invocation?.session?.id || "global";
+      const s = getSessionState(state, sid);
+      const enabled = state.taskContract?.taskContractEnabled ? "开启" : "关闭（总开关未开启，命令不生效）";
+      return { kind: "success", text: `任务契约（总开关：${enabled}）\n${contractSummary(s.contract)}` };
+    }
+    case "label": {
+      const entries = readAuditLog(500);
+      const found = entries.find((e) => e.eventId === command.eventId);
+      if (!found) return { kind: "error", text: `未找到审计事件：${command.eventId}` };
+      state.labels.set(command.eventId, command.label);
+      audit({ kind: "task-label", rule: "__task-contract", name: "审计人工标注", event: "command", reason: `${command.eventId} = ${command.label}`, session: invocation?.session?.id || "global" });
+      return { kind: "success", text: `已标注 ${command.eventId} = ${command.label}` };
+    }
     default:
       return { kind: "error", text: USAGE };
   }
@@ -614,6 +749,35 @@ export function apply(ctx) {
     "dsh-rule-engine guard"
   );
 
+  // 1.1 任务契约 ask 通道：仅在总开关 + askEnabled 时对“应询问”动作返回 ask
+  ctx.on("tools/pre-execute", async (exec, next) => {
+    try {
+      if (!state.taskContract?.taskContractEnabled || !state.taskContract?.askEnabled) return next();
+      const sid = sessionIdOfExec(exec);
+      const s = getSessionState(state, sid);
+      if (!isArmed(s.contract, state.taskContract)) return next();
+      const action = classifyAction(exec?.name, exec?.arguments);
+      const dec = decideContractAction({ contract: s.contract, action, config: state.taskContract });
+      if (dec.outcome === "ask") {
+        audit({
+          kind: "task-ask",
+          rule: "__task-contract",
+          name: "任务契约询问",
+          event: "tools/pre-execute",
+          tool: exec?.name,
+          args: summarizeArgs(exec?.arguments),
+          reason: dec.reason,
+          session: sid
+        });
+        return { kind: "ask", reason: `${dec.reason}（任务契约｜${dec.nextStep || "请确认或使用放行词"}）` };
+      }
+      return next();
+    } catch (error) {
+      ctx.logger?.warn?.("[dsh-rule-engine] tools/pre-execute error", error);
+      return next();
+    }
+  });
+
   // 2. session/event 监听：文本纠察 + 时序状态
   ctx.on("session/event", (session, event) => {
     try {

package/lib/service.js

@@ -5,7 +5,8 @@ import { readFileSync } from "node:fs";
 import { Remote, TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 import { state } from "./core/runtime.js";
 import { readAuditLog } from "./core/audit.js";
-import { loadPluginConfig } from "./core/config.js";
+import { loadPluginConfig, savePluginConfig } from "./core/config.js";
+import { applyTaskContractConfig } from "./core/state.js";
 import { agentsFilePath, auditFilePath } from "./core/paths.js";
 
 const REMOTE_METHODS = [
@@ -13,7 +14,9 @@ const REMOTE_METHODS = [
   "getVersion",
   "checkUpdate",
   "getAuditLog",
-  "getUnderstanding"
+  "getUnderstanding",
+  "getTaskContractConfig",
+  "setTaskContractConfig"
 ];
 
 function currentVersion() {
@@ -170,6 +173,43 @@ class RuleEngineService extends TypertRemoteService {
       return { ok: false, error: error instanceof Error ? error.message : String(error) };
     }
   }
+
+  /** 读取任务契约配置（设置页） */
+  async getTaskContractConfig() {
+    try {
+      const conf = loadPluginConfig();
+      return {
+        ok: true,
+        config: {
+          taskContractEnabled: conf.taskContractEnabled === true,
+          askEnabled: conf.askEnabled === true,
+          taskContractMode: conf.taskContractMode === "armed" ? "armed" : "observe",
+          taskContractDefaults: conf.taskContractDefaults || {}
+        }
+      };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
+  /** 保存任务契约配置（设置页；写入 rule-engine.json 并热同步 state） */
+  async setTaskContractConfig(partial) {
+    try {
+      const conf = savePluginConfig(partial || {});
+      applyTaskContractConfig(state, conf);
+      return {
+        ok: true,
+        config: {
+          taskContractEnabled: conf.taskContractEnabled === true,
+          askEnabled: conf.askEnabled === true,
+          taskContractMode: conf.taskContractMode === "armed" ? "armed" : "observe",
+          taskContractDefaults: conf.taskContractDefaults || {}
+        }
+      };
+    } catch (error) {
+      return { ok: false, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
 }
 
 export { RuleEngineService, RuleEngineService as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-rule-engine",
-  "version": "0.4.3",
+  "version": "0.5.1",
   "description": "DSH 规则执行引擎 v3：容器解析 AGENTS.md + 理解器 + 匹配机 + 执行框架",
   "type": "module",
   "main": "lib/index.js",
@@ -32,14 +32,22 @@
     "type": "git",
     "url": "https://github.com/jilian-dsh/dsh-rule-engine.git"
   },
+  "homepage": "https://github.com/jilian-dsh/dsh-rule-engine",
+  "engines": {
+    "node": ">=22"
+  },
+  "dshCompat": {
+    "min": "0.1.0-rc.3",
+    "max": "0.2.0"
+  },
   "scripts": {
-    "test": "node test/run-all.js",
+    "test": "node test/run-all.mjs",
     "check": "node --check lib/index.js",
     "audit:mount": "node scripts/audit-mount-consistency.mjs --profile web"
   },
   "peerDependencies": {
-    "@deepseek-ai/dsh-home-paths": ">=0.1.0-rc.3",
-    "@deepseek-ai/dsh-typert-protocol": ">=0.1.0-rc.3"
+    "@deepseek-ai/dsh-home-paths": ">=0.1.0-rc.3 <0.2",
+    "@deepseek-ai/dsh-typert-protocol": ">=0.1.0-rc.3 <0.2"
   },
   "dsh": {
     "bundle": {