minimal-agent 0.10.0 → 0.12.0

package/src/irreversible/rules.js

@@ -0,0 +1,216 @@
+/**
+ * ============================================================
+ *  src/irreversible/rules.ts —— 不可逆动作分级（内核通用）
+ * ------------------------------------------------------------
+ *  这里只回答一个问题：**这一步做下去，还救得回来吗？**
+ *
+ *  判据是「**是否毁掉最后一份副本**」，不是「动词听着吓不吓人」。
+ *  这条判据很重要，因为选错方向会两头落空：
+ *    · 拦得太宽（把 `git reset --hard` 也拦下来）→ 用户每天被问十几次，
+ *      很快学会闭眼点「同意」，闸门等于不存在；
+ *    · 拦得太窄 → 真出事时没人拦。
+ *  所以 `git reset --hard` **不拦**（reflog 能捞回来），而 `git push --force`
+ *  **要拦**（远端那段历史可能是唯一副本，别人本地未必有）。
+ *
+ *  为什么住在内核而不是某个工具里：这套语义天然**跨工具**。
+ *  「格式化硬盘 / 删库 / 汇款 / 毁 git 历史」主要发生在 Bash，
+ *  「点确认转账 / 永久删除」发生在 ComputerUse。两边共用同一套词汇表，
+ *  才不会各写一份、各自漂移。工具依赖内核，不是内核依赖工具。
+ *
+ *  ⚠️ 两条路的可靠性**根本不同**，不要混为一谈：
+ *    · `classifyCommand()` —— 读**真实命令文本**，确定性匹配。
+ *    · `classifyIntent()`  —— 读**模型自报的 intent**。模型不报就不命中。
+ *      这是 ComputerUse 侧的固有局限（GUI 上没有"命令文本"可读），
+ *      它先于本模块存在，搬过来时**不会**因此变可靠，别被"进了内核"迷惑。
+ *
+ *  与 Bash 现有两层的分工（三层各司其职，同一条模式只住一处）：
+ *    1. `bash.ts::FORBIDDEN_PATTERNS` —— 灾难且无正当用途（`rm -rf /`、mkfs、
+ *       fork bomb）：**直接拒绝**，不问人。
+ *    2. 本模块 `classifyCommand()` —— 不可逆但**有正当用途**（force push、
+ *       删库、毁 reflog）：**停下来问人**；无人可问 = 拒绝。
+ *    3. `bash/warnings.ts` —— 危险但可回滚（reset --hard、clean -f、stash drop）：
+ *       **只提示**，不阻塞。
+ * ============================================================
+ */
+/**
+ * 「毁掉最后一份副本」的命令。命中 = 停下来问人。
+ *
+ * 收录标准（三条全中才进来）：
+ *   ① 结果不可逆 —— 没有 reflog / 回收站 / 事务能捞回来
+ *   ② 有正当用途 —— 否则该进 `FORBIDDEN_PATTERNS` 直接拒，不该浪费一次提问
+ *   ③ 不在其它两层里 —— 同一条模式只住一处，避免漂移
+ */
+const COMMAND_RULES = [
+    // ---- git：毁掉远端/历史的最后一份副本 ----
+    // 注意只拦 --force / -f。`--force-with-lease` 在远端有未见提交时会**拒绝执行**，
+    // 正是为了防经典事故而设计的安全形式，拦它只会逼用户改用更危险的 --force。
+    // 它仍留在 warnings.ts 的提示层。
+    {
+        id: 'git-push-force',
+        pattern: /\bgit\b[^;&|\n]*\bpush\b(?![^;&|\n]*--force-with-lease)[^;&|\n]*(?:\s--force(?:=\S*)?\b|\s-[a-zA-Z]*f\b)/,
+        why: '强制推送会覆盖远端历史；被覆盖的提交可能只存在于远端，其他人本地也未必有',
+    },
+    {
+        // `git push origin +main` —— refspec 前缀 `+` 等价于强推，容易被漏看
+        id: 'git-push-plus-refspec',
+        pattern: /\bgit\b[^;&|\n]*\bpush\b[^;&|\n]*\s\+[\w./-]+:[\w./-]+/,
+        why: 'refspec 前的 `+` 等同强制推送，会覆盖远端历史',
+    },
+    {
+        id: 'git-push-delete-branch',
+        pattern: /\bgit\b[^;&|\n]*\bpush\b[^;&|\n]*(?:\s--delete\b|\s:[\w./-]+(?:\s|$))/,
+        why: '删除远端分支；若该分支未被其它引用包含，提交将无处可寻',
+    },
+    {
+        id: 'git-history-rewrite',
+        pattern: /\bgit\b[^;&|\n]*\b(?:filter-branch|filter-repo)\b/,
+        why: '重写整条提交历史，所有旧提交哈希失效且原历史不再可达',
+    },
+    {
+        // reflog 是本仓库大多数"手滑"的救命稻草；主动过期 + 立刻 gc 就是把它烧掉
+        id: 'git-destroy-reflog',
+        pattern: /\bgit\b[^;&|\n]*\b(?:reflog\s+expire\b[^;&|\n]*--expire(?:-unreachable)?=(?:now|all)|gc\b[^;&|\n]*--prune=(?:now|all))/,
+        why: '销毁 reflog / 立即清理不可达对象，等于拆掉本地误操作的最后一道保险',
+    },
+    // ---- 数据库：删库 ----
+    {
+        id: 'sql-drop-database',
+        pattern: /\bDROP\s+(?:DATABASE|SCHEMA)\b/i,
+        why: '删库；除非另有备份，库内全部数据不可恢复',
+    },
+    {
+        id: 'sql-drop-or-truncate-table',
+        pattern: /\b(?:DROP\s+TABLE|TRUNCATE\s+(?:TABLE\s+)?)\b/i,
+        why: '删表 / 清空表；TRUNCATE 通常不写 undo 日志，删掉即没了',
+    },
+    // ---- 绕过回收站的永久删除 ----
+    // 「一般删除进回收站、永久删除要拦」这条判据的落点。注意 shell 里的 `rm`
+    // **本来就不进回收站**，但逐个 `rm` 都拦会让 agent 没法干活；
+    // 灾难范围的 rm 已由 FORBIDDEN_PATTERNS 直接拒。这里只收「明确表达
+    // 要抹掉到不可恢复」的那几个。
+    {
+        id: 'shred-file',
+        pattern: /\bshred\b[^;&|\n]*-[a-zA-Z]*u|\bshred\s+--remove\b/,
+        why: '覆写并删除文件内容，磁盘取证也无法恢复',
+    },
+    {
+        id: 'empty-recycle-bin',
+        pattern: /\bClear-RecycleBin\b/i,
+        why: '清空回收站；里面原本还能还原的文件将彻底消失',
+    },
+    {
+        id: 'rm-no-preserve-root',
+        pattern: /--no-preserve-root\b/,
+        why: '显式解除根目录保护，是在主动拆掉系统自带的最后一道防线',
+    },
+];
+/**
+ * 归一化命令后逐段匹配。
+ *
+ * 归一化做两件事：剥掉 `sudo` / 环境变量前缀，并按 `&& || ; | 换行` 切段 ——
+ * 否则 `cd /x && git push --force` 这类连写会漏判。
+ *
+ * ⚠️ **这是黑名单，不是沙盒，必然有绕过**：shell 是图灵完备的，
+ * `bash -c "$(echo Z2l0IHB1c2g... | base64 -d)"`、alias、变量拼接都能躲开。
+ * `test/irreversible.test.ts` 里有一组**明确列出、明确不修**的已知绕过用例，
+ * 那是诚实声明；把这层当成"拦住手滑与顺手误操作"，不要当成对抗恶意输入。
+ */
+export function classifyCommand(command) {
+    for (const segment of splitCommandSegments(command)) {
+        for (const rule of COMMAND_RULES) {
+            if (rule.pattern.test(segment)) {
+                return {
+                    entry: rule.id,
+                    riskLevel: 'critical',
+                    checkable: true,
+                    why: rule.why,
+                    source: 'command',
+                };
+            }
+        }
+    }
+    return null;
+}
+/** 按 shell 的连接符切段，并剥掉 `sudo` / `VAR=x` 前缀。 */
+function splitCommandSegments(command) {
+    return command
+        .split(/&&|\|\||[;|\n]/)
+        .map((part) => part.trim().replace(/^(?:sudo\s+|[A-Za-z_][A-Za-z0-9_]*=\S*\s+)+/, ''))
+        .filter((part) => part.length > 0);
+}
+/** 供文档/测试枚举当前规则（不暴露 RegExp，避免调用方自行匹配绕过本函数）。 */
+export function commandRuleIds() {
+    return COMMAND_RULES.map((rule) => rule.id);
+}
+// ============================================================
+//  二、意图路（ComputerUse）—— 依赖模型自报，可靠性天然弱一档
+// ============================================================
+/**
+ * 全局高危意图黑名单：任何应用命中都按 critical。
+ *
+ * ⚠️ 这些条目形如 `intent:payment`，来源是**模型在工具入参里自报的 intent**。
+ * 模型不报、或报成别的词，就不会命中 —— GUI 上没有"命令文本"可供确定性匹配，
+ * 这是该路径的固有上限。真正的兜底是宿主侧的人工监督，不是这张表。
+ */
+const GLOBAL_CRITICAL_INTENTS = [
+    // 财产类
+    'intent:payment',
+    'intent:payment-or-transfer',
+    'intent:transfer',
+    'intent:pay',
+    'intent:withdraw',
+    // 数据销毁类
+    'intent:permanent-delete',
+    'intent:format-disk',
+    'intent:rm-rf',
+    'intent:wipe-data',
+    'intent:clear-chat-history',
+    // 账号/关系类（不可逆且有社交成本）
+    'intent:remove-contact',
+    'intent:block-user',
+    'intent:leave-group-permanently',
+    'intent:dissolve-group',
+    'intent:delete-account',
+    // 关窗：按同一条判据（毁掉最后一份副本）——未保存的内容没有回收站也没有
+    // reflog，窗口一关就没了。它不是 `intent:` 形状，因为不靠模型自报：
+    // `action:'window' + windowOperation:'close'` 是引擎能自己看出来的确定事实。
+    // 触发频率也不高：agent 主动去关用户桌面上的窗口本就罕见且后果明确。
+    'window:close',
+];
+/**
+ * 判断一个不可逆条目是否在全局高危黑名单中。
+ *
+ * 匹配规则：完全相等，或 pattern 是 entry 的前缀且在分隔符处断开
+ * （`payment-or-transfer` 命中 `payment`；但 `send-message` 不会误命中 `send`）。
+ */
+export function isGlobalCriticalIntent(entry) {
+    const normalized = entry.toLowerCase();
+    return GLOBAL_CRITICAL_INTENTS.some((pattern) => {
+        if (normalized === pattern)
+            return true;
+        return (normalized.startsWith(`${pattern}-`) ||
+            normalized.startsWith(`${pattern}_`) ||
+            normalized.startsWith(`${pattern}:`));
+    });
+}
+export function globalCriticalIntentEntries() {
+    return [...GLOBAL_CRITICAL_INTENTS];
+}
+/**
+ * 综合判定一个不可逆意图条目的风险级别。
+ *
+ * 优先级：全局黑名单 > 应用级 critical > 其余（normal）。
+ * **黑名单制**：只有明确列进 critical 的才拦，其余放行 —— 这是产品决定，
+ * 见本文件头注对「拦太宽等于没拦」的说明。全局黑名单不可被应用级降级。
+ */
+export function classifyIntent(params) {
+    const { entry, guideCritical, why, checkable = false } = params;
+    if (isGlobalCriticalIntent(entry)) {
+        return { entry, riskLevel: 'critical', checkable, why, source: 'global' };
+    }
+    const normalized = entry.toLowerCase();
+    if (guideCritical.some((c) => c.toLowerCase() === normalized)) {
+        return { entry, riskLevel: 'critical', checkable, why, source: 'app-critical' };
+    }
+    return { entry, riskLevel: 'normal', checkable, why, source: 'app-normal' };
+}

package/src/irreversible/rules.ts

@@ -0,0 +1,261 @@
+/**
+ * ============================================================
+ *  src/irreversible/rules.ts —— 不可逆动作分级（内核通用）
+ * ------------------------------------------------------------
+ *  这里只回答一个问题：**这一步做下去，还救得回来吗？**
+ *
+ *  判据是「**是否毁掉最后一份副本**」，不是「动词听着吓不吓人」。
+ *  这条判据很重要，因为选错方向会两头落空：
+ *    · 拦得太宽（把 `git reset --hard` 也拦下来）→ 用户每天被问十几次，
+ *      很快学会闭眼点「同意」，闸门等于不存在；
+ *    · 拦得太窄 → 真出事时没人拦。
+ *  所以 `git reset --hard` **不拦**（reflog 能捞回来），而 `git push --force`
+ *  **要拦**（远端那段历史可能是唯一副本，别人本地未必有）。
+ *
+ *  为什么住在内核而不是某个工具里：这套语义天然**跨工具**。
+ *  「格式化硬盘 / 删库 / 汇款 / 毁 git 历史」主要发生在 Bash，
+ *  「点确认转账 / 永久删除」发生在 ComputerUse。两边共用同一套词汇表，
+ *  才不会各写一份、各自漂移。工具依赖内核，不是内核依赖工具。
+ *
+ *  ⚠️ 两条路的可靠性**根本不同**，不要混为一谈：
+ *    · `classifyCommand()` —— 读**真实命令文本**，确定性匹配。
+ *    · `classifyIntent()`  —— 读**模型自报的 intent**。模型不报就不命中。
+ *      这是 ComputerUse 侧的固有局限（GUI 上没有"命令文本"可读），
+ *      它先于本模块存在，搬过来时**不会**因此变可靠，别被"进了内核"迷惑。
+ *
+ *  与 Bash 现有两层的分工（三层各司其职，同一条模式只住一处）：
+ *    1. `bash.ts::FORBIDDEN_PATTERNS` —— 灾难且无正当用途（`rm -rf /`、mkfs、
+ *       fork bomb）：**直接拒绝**，不问人。
+ *    2. 本模块 `classifyCommand()` —— 不可逆但**有正当用途**（force push、
+ *       删库、毁 reflog）：**停下来问人**；无人可问 = 拒绝。
+ *    3. `bash/warnings.ts` —— 危险但可回滚（reset --hard、clean -f、stash drop）：
+ *       **只提示**，不阻塞。
+ * ============================================================
+ */
+
+/** 风险级别。保持两档：只有 critical 会改变执行路径，别加没人消费的第三档。 */
+export type RiskLevel = 'critical' | 'normal';
+
+export interface RiskHit {
+  /** 命中的条目（intent 路是 `intent:xxx`，命令路是规则 id） */
+  entry: string;
+  riskLevel: RiskLevel;
+  /** 引擎能独立验证（命令文本 / key / region），还是只能信模型自报（intent） */
+  checkable: boolean;
+  /** 人话后果，直接展示给用户，必须说清「丢什么、能不能找回」 */
+  why: string;
+  /** 命中来自哪一层，便于审计与排错 */
+  source: 'command' | 'global' | 'app-critical' | 'app-normal';
+}
+
+// ============================================================
+//  一、命令文本路（Bash）—— 确定性，不依赖模型自报
+// ============================================================
+
+interface CommandRule {
+  id: string;
+  pattern: RegExp;
+  why: string;
+}
+
+/**
+ * 「毁掉最后一份副本」的命令。命中 = 停下来问人。
+ *
+ * 收录标准（三条全中才进来）：
+ *   ① 结果不可逆 —— 没有 reflog / 回收站 / 事务能捞回来
+ *   ② 有正当用途 —— 否则该进 `FORBIDDEN_PATTERNS` 直接拒，不该浪费一次提问
+ *   ③ 不在其它两层里 —— 同一条模式只住一处，避免漂移
+ */
+const COMMAND_RULES: CommandRule[] = [
+  // ---- git：毁掉远端/历史的最后一份副本 ----
+  // 注意只拦 --force / -f。`--force-with-lease` 在远端有未见提交时会**拒绝执行**，
+  // 正是为了防经典事故而设计的安全形式，拦它只会逼用户改用更危险的 --force。
+  // 它仍留在 warnings.ts 的提示层。
+  {
+    id: 'git-push-force',
+    pattern: /\bgit\b[^;&|\n]*\bpush\b(?![^;&|\n]*--force-with-lease)[^;&|\n]*(?:\s--force(?:=\S*)?\b|\s-[a-zA-Z]*f\b)/,
+    why: '强制推送会覆盖远端历史；被覆盖的提交可能只存在于远端，其他人本地也未必有',
+  },
+  {
+    // `git push origin +main` —— refspec 前缀 `+` 等价于强推，容易被漏看
+    id: 'git-push-plus-refspec',
+    pattern: /\bgit\b[^;&|\n]*\bpush\b[^;&|\n]*\s\+[\w./-]+:[\w./-]+/,
+    why: 'refspec 前的 `+` 等同强制推送，会覆盖远端历史',
+  },
+  {
+    id: 'git-push-delete-branch',
+    pattern: /\bgit\b[^;&|\n]*\bpush\b[^;&|\n]*(?:\s--delete\b|\s:[\w./-]+(?:\s|$))/,
+    why: '删除远端分支；若该分支未被其它引用包含，提交将无处可寻',
+  },
+  {
+    id: 'git-history-rewrite',
+    pattern: /\bgit\b[^;&|\n]*\b(?:filter-branch|filter-repo)\b/,
+    why: '重写整条提交历史，所有旧提交哈希失效且原历史不再可达',
+  },
+  {
+    // reflog 是本仓库大多数"手滑"的救命稻草；主动过期 + 立刻 gc 就是把它烧掉
+    id: 'git-destroy-reflog',
+    pattern: /\bgit\b[^;&|\n]*\b(?:reflog\s+expire\b[^;&|\n]*--expire(?:-unreachable)?=(?:now|all)|gc\b[^;&|\n]*--prune=(?:now|all))/,
+    why: '销毁 reflog / 立即清理不可达对象，等于拆掉本地误操作的最后一道保险',
+  },
+
+  // ---- 数据库：删库 ----
+  {
+    id: 'sql-drop-database',
+    pattern: /\bDROP\s+(?:DATABASE|SCHEMA)\b/i,
+    why: '删库；除非另有备份，库内全部数据不可恢复',
+  },
+  {
+    id: 'sql-drop-or-truncate-table',
+    pattern: /\b(?:DROP\s+TABLE|TRUNCATE\s+(?:TABLE\s+)?)\b/i,
+    why: '删表 / 清空表；TRUNCATE 通常不写 undo 日志，删掉即没了',
+  },
+
+  // ---- 绕过回收站的永久删除 ----
+  // 「一般删除进回收站、永久删除要拦」这条判据的落点。注意 shell 里的 `rm`
+  // **本来就不进回收站**，但逐个 `rm` 都拦会让 agent 没法干活；
+  // 灾难范围的 rm 已由 FORBIDDEN_PATTERNS 直接拒。这里只收「明确表达
+  // 要抹掉到不可恢复」的那几个。
+  {
+    id: 'shred-file',
+    pattern: /\bshred\b[^;&|\n]*-[a-zA-Z]*u|\bshred\s+--remove\b/,
+    why: '覆写并删除文件内容，磁盘取证也无法恢复',
+  },
+  {
+    id: 'empty-recycle-bin',
+    pattern: /\bClear-RecycleBin\b/i,
+    why: '清空回收站；里面原本还能还原的文件将彻底消失',
+  },
+  {
+    id: 'rm-no-preserve-root',
+    pattern: /--no-preserve-root\b/,
+    why: '显式解除根目录保护，是在主动拆掉系统自带的最后一道防线',
+  },
+];
+
+/**
+ * 归一化命令后逐段匹配。
+ *
+ * 归一化做两件事：剥掉 `sudo` / 环境变量前缀，并按 `&& || ; | 换行` 切段 ——
+ * 否则 `cd /x && git push --force` 这类连写会漏判。
+ *
+ * ⚠️ **这是黑名单，不是沙盒，必然有绕过**：shell 是图灵完备的，
+ * `bash -c "$(echo Z2l0IHB1c2g... | base64 -d)"`、alias、变量拼接都能躲开。
+ * `test/irreversible.test.ts` 里有一组**明确列出、明确不修**的已知绕过用例，
+ * 那是诚实声明；把这层当成"拦住手滑与顺手误操作"，不要当成对抗恶意输入。
+ */
+export function classifyCommand(command: string): RiskHit | null {
+  for (const segment of splitCommandSegments(command)) {
+    for (const rule of COMMAND_RULES) {
+      if (rule.pattern.test(segment)) {
+        return {
+          entry: rule.id,
+          riskLevel: 'critical',
+          checkable: true,
+          why: rule.why,
+          source: 'command',
+        };
+      }
+    }
+  }
+  return null;
+}
+
+/** 按 shell 的连接符切段，并剥掉 `sudo` / `VAR=x` 前缀。 */
+function splitCommandSegments(command: string): string[] {
+  return command
+    .split(/&&|\|\||[;|\n]/)
+    .map((part) => part.trim().replace(/^(?:sudo\s+|[A-Za-z_][A-Za-z0-9_]*=\S*\s+)+/, ''))
+    .filter((part) => part.length > 0);
+}
+
+/** 供文档/测试枚举当前规则（不暴露 RegExp，避免调用方自行匹配绕过本函数）。 */
+export function commandRuleIds(): string[] {
+  return COMMAND_RULES.map((rule) => rule.id);
+}
+
+// ============================================================
+//  二、意图路（ComputerUse）—— 依赖模型自报，可靠性天然弱一档
+// ============================================================
+
+/**
+ * 全局高危意图黑名单：任何应用命中都按 critical。
+ *
+ * ⚠️ 这些条目形如 `intent:payment`，来源是**模型在工具入参里自报的 intent**。
+ * 模型不报、或报成别的词，就不会命中 —— GUI 上没有"命令文本"可供确定性匹配，
+ * 这是该路径的固有上限。真正的兜底是宿主侧的人工监督，不是这张表。
+ */
+const GLOBAL_CRITICAL_INTENTS: readonly string[] = [
+  // 财产类
+  'intent:payment',
+  'intent:payment-or-transfer',
+  'intent:transfer',
+  'intent:pay',
+  'intent:withdraw',
+  // 数据销毁类
+  'intent:permanent-delete',
+  'intent:format-disk',
+  'intent:rm-rf',
+  'intent:wipe-data',
+  'intent:clear-chat-history',
+  // 账号/关系类（不可逆且有社交成本）
+  'intent:remove-contact',
+  'intent:block-user',
+  'intent:leave-group-permanently',
+  'intent:dissolve-group',
+  'intent:delete-account',
+  // 关窗：按同一条判据（毁掉最后一份副本）——未保存的内容没有回收站也没有
+  // reflog，窗口一关就没了。它不是 `intent:` 形状，因为不靠模型自报：
+  // `action:'window' + windowOperation:'close'` 是引擎能自己看出来的确定事实。
+  // 触发频率也不高：agent 主动去关用户桌面上的窗口本就罕见且后果明确。
+  'window:close',
+];
+
+/**
+ * 判断一个不可逆条目是否在全局高危黑名单中。
+ *
+ * 匹配规则：完全相等，或 pattern 是 entry 的前缀且在分隔符处断开
+ * （`payment-or-transfer` 命中 `payment`；但 `send-message` 不会误命中 `send`）。
+ */
+export function isGlobalCriticalIntent(entry: string): boolean {
+  const normalized = entry.toLowerCase();
+  return GLOBAL_CRITICAL_INTENTS.some((pattern) => {
+    if (normalized === pattern) return true;
+    return (
+      normalized.startsWith(`${pattern}-`) ||
+      normalized.startsWith(`${pattern}_`) ||
+      normalized.startsWith(`${pattern}:`)
+    );
+  });
+}
+
+export function globalCriticalIntentEntries(): string[] {
+  return [...GLOBAL_CRITICAL_INTENTS];
+}
+
+/**
+ * 综合判定一个不可逆意图条目的风险级别。
+ *
+ * 优先级：全局黑名单 > 应用级 critical > 其余（normal）。
+ * **黑名单制**：只有明确列进 critical 的才拦，其余放行 —— 这是产品决定，
+ * 见本文件头注对「拦太宽等于没拦」的说明。全局黑名单不可被应用级降级。
+ */
+export function classifyIntent(params: {
+  entry: string;
+  guideCritical: readonly string[];
+  why: string;
+  checkable?: boolean;
+}): RiskHit {
+  const { entry, guideCritical, why, checkable = false } = params;
+
+  if (isGlobalCriticalIntent(entry)) {
+    return { entry, riskLevel: 'critical', checkable, why, source: 'global' };
+  }
+
+  const normalized = entry.toLowerCase();
+  if (guideCritical.some((c) => c.toLowerCase() === normalized)) {
+    return { entry, riskLevel: 'critical', checkable, why, source: 'app-critical' };
+  }
+
+  return { entry, riskLevel: 'normal', checkable, why, source: 'app-normal' };
+}

package/src/llm/client.js

@@ -24,7 +24,8 @@
  * ============================================================
  */
 import { dlog } from '../utils/debugLog.js';
-import { buildOpenAIRequest, createOpenAISSEParser, isImageInputRejected, isMaxTokensRejected, isResponseFormatUnsupported, } from './providers/openaiFormat.js';
+import { buildOpenAIRequest, createOpenAISSEParser, isImageInputRejected, isMaxTokensRejected, isPromptCacheKeyRejected, isResponseFormatUnsupported, } from './providers/openaiFormat.js';
+import { promptMaterialHash, shortCacheScope } from './promptCache.js';
 import { buildAnthropicRequest, createAnthropicSSEParser } from './providers/anthropicFormat.js';
 /**
  * 记住"这个 baseURL::model 不支持 response_format.json_schema"，避免每次都先撞 400。
@@ -38,6 +39,7 @@ const rfUnsupported = new Set();
  * ≥131072 仍正常），这只是给个别挑剔 provider 的兜底，命中后该进程不再发 max_tokens。
  */
 const maxTokensUnsupported = new Set();
+const promptCacheKeyUnsupported = new Set();
 /** 调试日志用的请求自增号（vote 并发多 voter 时靠它在日志里区分是哪一路）。 */
 let reqCounter = 0;
 // ============================================================
@@ -239,7 +241,7 @@ export function createIdleWatchdog(userSignal, timeoutMs = IDLE_TIMEOUT_MS) {
  * ```
  */
 export async function* chat(args) {
-    const { provider, messages, tools, signal, responseFormat } = args;
+    const { provider, messages, tools, signal, responseFormat, promptCache } = args;
     const format = provider.apiFormat === 'anthropic' ? 'anthropic' : 'openai';
     if (format === 'anthropic' && responseFormat) {
         throw new Error('output_schema 结构化输出目前不支持 Anthropic Messages 格式的 provider' +
@@ -252,7 +254,7 @@ export async function* chat(args) {
     let cleanedMessages = messages
         .filter((m) => !(m.role === 'system' && m._ephemeral === true))
         .map((m) => {
-        const { id, timestamp, attachments, display_metadata, ...rest } = m;
+        const { id, timestamp, attachments, browserReferences, display_metadata, ...rest } = m;
         return rest;
     });
     const includeUsage = process.env.MINIMAL_AGENT_DISABLE_USAGE !== '1';
@@ -265,6 +267,10 @@ export async function* chat(args) {
         provider.maxTokens > 0 &&
         !maxTokensUnsupported.has(rfKey);
     let imagesStripped = false;
+    let wantPromptCacheKey = format === 'openai' &&
+        provider.promptCache?.mode === 'session-key' &&
+        !!promptCache?.scopeKey &&
+        !promptCacheKeyUnsupported.has(rfKey);
     const stripImagesFromMessages = (msgs) => msgs.map((m) => {
         const c = m.content;
         if (!Array.isArray(c))
@@ -288,6 +294,8 @@ export async function* chat(args) {
                 withResponseFormat: wantResponseFormat,
                 withMaxTokens: wantMaxTokens,
                 includeUsage,
+                promptCache,
+                withPromptCacheKey: wantPromptCacheKey,
                 responseFormat,
             });
         return fetch(req.url, { method: 'POST', headers: req.headers, body: req.body, signal: watchdog.signal });
@@ -300,6 +308,16 @@ export async function* chat(args) {
         maxTokens: wantMaxTokens ? provider.maxTokens : undefined,
         msgs: cleanedMessages.length,
         tools: tools.length,
+        promptCacheMode: provider.promptCache?.mode ?? 'auto',
+        promptCacheScope: shortCacheScope(promptCache?.scopeKey),
+        systemPromptHash: promptMaterialHash(cleanedMessages
+            .filter((message) => message.role === 'system')
+            .map((message) => message.content)),
+        toolSchemaHash: promptMaterialHash(tools.map((tool) => ({
+            name: tool.name,
+            description: typeof tool.description === 'function' ? tool.description() : tool.description,
+            parameters: tool.parameters,
+        }))),
     });
     // 重试循环：每个 attempt 内部可能触发"response_format 不支持 → 去掉"的本地退化
     //     （本地退化不算重试，仍属同一 attempt 的"拿到 200"路径的一部分；只 openai 分支会真的
@@ -348,6 +366,25 @@ export async function* chat(args) {
         // resp !ok：本地退化路径（response_format / max_tokens 不被支持 → 去掉重发，不算重试；
         // 仅 openai 分支——wantResponseFormat/wantMaxTokens 在 anthropic 分支恒为 false）
         let errText = await resp.text().catch(() => '');
+        if (wantPromptCacheKey && isPromptCacheKeyRejected(resp.status, errText)) {
+            promptCacheKeyUnsupported.add(rfKey);
+            wantPromptCacheKey = false;
+            dlog('llm', `req#${reqId} prompt_cache_key unsupported; downgraded`, {
+                model: provider.model,
+            });
+            try {
+                resp = await postChat();
+                watchdog.kick();
+            }
+            catch (e) {
+                if ((await handleNetworkError(e, attempt, 'cache-key fallback fetch failed')) === 'break')
+                    break;
+                continue;
+            }
+            if (resp.ok)
+                break;
+            errText = await resp.text().catch(() => '');
+        }
         // 退化①：response_format.json_schema 不支持
         if (wantResponseFormat && isResponseFormatUnsupported(resp.status, errText)) {
             // 记住该 model 不支持，单进程内后续结构化调用直接跳过 response_format（不再撞 400）。