minimal-agent 0.13.0 → 0.15.0

package/src/tools/shared/fileUtils.ts

@@ -152,7 +152,7 @@ export function applyLineEnding(content: string, ending: LineEndingType): string
 
 // 上游 D:\code\kakadeai\constants\files.ts:5-112 BINARY_EXTENSIONS Set 的裁剪版：
 // 故意剔除 .log / .csv / .tsv / .dat / .data / .lock —— 这些经常被人当文本读。
-// 保留纯二进制：图片 / 文档 / 可执行 / 编译产物 / 压缩包 / 多媒体 / 字体 / 数据库 / wasm。
+// 保留纯二进制：图片 / 文档 / 可执行 / 编译产物 / 压缩包 / 多媒体 / 字体 / wasm。
 export const BINARY_EXTENSIONS = new Set<string>([
   '.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.ico', '.tiff', '.tif',
   '.pdf', '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx',
@@ -161,7 +161,6 @@ export const BINARY_EXTENSIONS = new Set<string>([
   '.zip', '.tar', '.gz', '.bz2', '.7z', '.rar', '.iso',
   '.mp3', '.mp4', '.mov', '.avi', '.mkv', '.wav', '.flac', '.ogg',
   '.ttf', '.otf', '.woff', '.woff2',
-  '.sqlite', '.sqlite3', '.db',
   '.psd', '.ai', '.bin', '.wasm',
 ]);
 

package/src/tools/shared/toolOutputStore.js

@@ -15,6 +15,10 @@ export class ToolOutputStore {
     diskBytes = 0;
     bytes = 0;
     complete = true;
+    /** finish() 已调用：hash 已 digest，此后不能再 update（见 append 头注）。 */
+    sealed = false;
+    /** finish() 的结果缓存 —— digest 只能算一次，二次调用必须拿到同一份。 */
+    settled;
     path;
     constructor(identity) {
         const dir = join(sessionRuntimeDir(identity), 'outputs');
@@ -22,6 +26,18 @@ export class ToolOutputStore {
         this.path = join(dir, `procout_${randomUUID()}.log`);
     }
     append(source, value) {
+        // ⚠️ finish() 之后到达的迟到数据：**绝不能抛**。
+        //
+        // `bash.ts` 的 spawnRunner 按 `'exit'` 结算（不能等 `'close'`，否则被 daemon
+        // 继承的 pipe 会把它拖成无限挂），代价就是 exit 之后仍可能有 chunk 到达。
+        // 那时 hash 已经 digest 过，`hash.update()` 会抛 ERR_CRYPTO_HASH_FINALIZED，
+        // 而这个抛错发生在 stdout 的 'data' 回调里 —— 没有任何人接得住。
+        //
+        // 正确做法是如实记成不完整（数据确实没被算进已报出的结果），然后安静返回。
+        if (this.sealed) {
+            this.complete = false;
+            return true;
+        }
         const raw = Buffer.from(value);
         if (this.bytes >= MAX_BYTES) {
             this.complete = false;
@@ -70,6 +86,11 @@ export class ToolOutputStore {
         this.stream?.once('drain', callback);
     }
     async finish() {
+        // 幂等：digest 只能算一次。二次调用返回同一份快照，但 `complete` 取最新值 ——
+        // 如果之间来过迟到数据，调用方有权知道这份输出其实不完整了。
+        if (this.settled)
+            return { ...this.settled, complete: this.complete };
+        this.sealed = true;
         if (this.stream) {
             try {
                 await new Promise((resolve, reject) => {
@@ -85,7 +106,7 @@ export class ToolOutputStore {
         const preview = (head, tail) => this.stream && tail && !head.endsWith(tail)
             ? `${head}\n... [middle stored on disk] ...\n${tail}`
             : head;
-        return {
+        this.settled = {
             stdout: preview(this.stdout, this.stdoutTail),
             stderr: preview(this.stderr, this.stderrTail),
             ...(this.stream ? { path: this.path } : {}),
@@ -93,5 +114,6 @@ export class ToolOutputStore {
             sha256: this.stream ? this.diskHash.digest('hex') : this.hash.digest('hex'),
             complete: this.complete,
         };
+        return this.settled;
     }
 }

package/src/tools/shared/toolOutputStore.ts

@@ -32,6 +32,10 @@ export class ToolOutputStore {
   private diskBytes = 0;
   private bytes = 0;
   private complete = true;
+  /** finish() 已调用：hash 已 digest，此后不能再 update（见 append 头注）。 */
+  private sealed = false;
+  /** finish() 的结果缓存 —— digest 只能算一次，二次调用必须拿到同一份。 */
+  private settled?: StoredOutput;
   readonly path: string;
   constructor(identity: RuntimeIdentity) {
     const dir = join(sessionRuntimeDir(identity), 'outputs');
@@ -39,6 +43,18 @@ export class ToolOutputStore {
     this.path = join(dir, `procout_${randomUUID()}.log`);
   }
   append(source: 'stdout' | 'stderr', value: Buffer | string): boolean {
+    // ⚠️ finish() 之后到达的迟到数据：**绝不能抛**。
+    //
+    // `bash.ts` 的 spawnRunner 按 `'exit'` 结算（不能等 `'close'`，否则被 daemon
+    // 继承的 pipe 会把它拖成无限挂），代价就是 exit 之后仍可能有 chunk 到达。
+    // 那时 hash 已经 digest 过，`hash.update()` 会抛 ERR_CRYPTO_HASH_FINALIZED，
+    // 而这个抛错发生在 stdout 的 'data' 回调里 —— 没有任何人接得住。
+    //
+    // 正确做法是如实记成不完整（数据确实没被算进已报出的结果），然后安静返回。
+    if (this.sealed) {
+      this.complete = false;
+      return true;
+    }
     const raw = Buffer.from(value);
     if (this.bytes >= MAX_BYTES) {
       this.complete = false;
@@ -83,6 +99,10 @@ export class ToolOutputStore {
     this.stream?.once('drain', callback);
   }
   async finish(): Promise<StoredOutput> {
+    // 幂等：digest 只能算一次。二次调用返回同一份快照，但 `complete` 取最新值 ——
+    // 如果之间来过迟到数据，调用方有权知道这份输出其实不完整了。
+    if (this.settled) return { ...this.settled, complete: this.complete };
+    this.sealed = true;
     if (this.stream) {
       try {
         await new Promise<void>((resolve, reject) => {
@@ -98,7 +118,7 @@ export class ToolOutputStore {
       this.stream && tail && !head.endsWith(tail)
         ? `${head}\n... [middle stored on disk] ...\n${tail}`
         : head;
-    return {
+    this.settled = {
       stdout: preview(this.stdout, this.stdoutTail),
       stderr: preview(this.stderr, this.stderrTail),
       ...(this.stream ? { path: this.path } : {}),
@@ -106,5 +126,6 @@ export class ToolOutputStore {
       sha256: this.stream ? this.diskHash!.digest('hex') : this.hash.digest('hex'),
       complete: this.complete,
     };
+    return this.settled;
   }
 }

package/src/tools/skill/skill.js

@@ -15,9 +15,9 @@ const schema = z.object({
     arguments: z.string().max(20_000).optional(),
 });
 const activated = new Map();
-async function candidates(name, cwd) {
+async function candidates(name, context) {
     const exact = [];
-    for (const root of getResourceSearchPaths('skills', import.meta.url, cwd)) {
+    for (const root of getResourceSearchPaths('skills', import.meta.url, context.cwd)) {
         let entries;
         try {
             entries = await readdir(root, { withFileTypes: true });
@@ -35,6 +35,12 @@ async function candidates(name, cwd) {
                 const metadata = frontmatter
                     ? parseYaml(frontmatter[1])
                     : undefined;
+                const modes = Array.isArray(metadata?.metadata?.modes) ? metadata.metadata.modes : [];
+                const surfaces = Array.isArray(metadata?.metadata?.surfaces) ? metadata.metadata.surfaces : [];
+                if (modes.length > 0 && !modes.includes(context.conversationMode ?? 'private'))
+                    continue;
+                if (surfaces.length > 0 && !surfaces.includes(context.surface))
+                    continue;
                 const declared = typeof metadata?.name === 'string' ? metadata.name.trim() : undefined;
                 if (entry.name === name || declared === name)
                     exact.push(path);
@@ -45,7 +51,7 @@ async function candidates(name, cwd) {
     return [...new Set(exact)];
 }
 async function call(input, context) {
-    const found = await candidates(input.name, context.cwd);
+    const found = await candidates(input.name, context);
     if (!found.length)
         return { ok: false, error: `没有找到名称精确匹配的 Skill：${input.name}` };
     // Search roots are ordered: project skill intentionally overrides the bundled skill.

package/src/tools/skill/skill.ts

@@ -20,9 +20,9 @@ const schema = z.object({
 type Input = z.infer<typeof schema>;
 const activated = new Map<string, string>();
 
-async function candidates(name: string, cwd?: string): Promise<string[]> {
+async function candidates(name: string, context: ToolCallContext): Promise<string[]> {
   const exact: string[] = [];
-  for (const root of getResourceSearchPaths('skills', import.meta.url, cwd)) {
+  for (const root of getResourceSearchPaths('skills', import.meta.url, context.cwd)) {
     let entries;
     try {
       entries = await readdir(root, { withFileTypes: true });
@@ -36,8 +36,12 @@ async function candidates(name: string, cwd?: string): Promise<string[]> {
         const text = await readFile(path, 'utf8');
         const frontmatter = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
         const metadata = frontmatter
-          ? (parseYaml(frontmatter[1]!) as { name?: unknown })
+          ? (parseYaml(frontmatter[1]!) as { name?: unknown; metadata?: { modes?: unknown; surfaces?: unknown } })
           : undefined;
+        const modes = Array.isArray(metadata?.metadata?.modes) ? metadata.metadata.modes : [];
+        const surfaces = Array.isArray(metadata?.metadata?.surfaces) ? metadata.metadata.surfaces : [];
+        if (modes.length > 0 && !modes.includes(context.conversationMode ?? 'private')) continue;
+        if (surfaces.length > 0 && !surfaces.includes(context.surface)) continue;
         const declared =
           typeof metadata?.name === 'string' ? metadata.name.trim() : undefined;
         if (entry.name === name || declared === name) exact.push(path);
@@ -51,7 +55,7 @@ async function call(
   input: Input,
   context: ToolCallContext,
 ): Promise<ToolResult> {
-  const found = await candidates(input.name, context.cwd);
+  const found = await candidates(input.name, context);
   if (!found.length)
     return { ok: false, error: `没有找到名称精确匹配的 Skill：${input.name}` };
   // Search roots are ordered: project skill intentionally overrides the bundled skill.

package/src/tools/toolPromptGuides.js

@@ -0,0 +1,125 @@
+import { bashShellNotice } from './bash/bash.js';
+import { COMPUTER_USE_TOOL_ACTIONS } from './computeruse/protocol.js';
+export const TOOL_CATEGORY_LABELS = {
+    files: '文件与代码',
+    shell: 'Shell 与后台任务',
+    web: 'Web 与浏览器',
+    desktop: '桌面自动化',
+    agents: 'Agent、任务与协作',
+    memory: '记忆、Skill 与顾问',
+    media: '媒体与成果交付',
+};
+const g = (category, useWhen, method, avoidWhen, priority = 'normal') => ({ category, useWhen, method, ...(avoidWhen ? { avoidWhen } : {}), priority });
+/** Single source of truth for built-in tool selection and first-step guidance. */
+export const BUILTIN_TOOL_PROMPT_GUIDES = {
+    Read: g('files', '读取已知本机文本、图片、Notebook 或 PDF', '按明确路径和必要范围读取', '通过桌面图片查看器重新打开静态图片', 'preferred'),
+    Edit: g('files', '精确替换既有文件中的一处内容', '先 Read 最新内容，再提供唯一 old/new 文本', '不要用于创建文件或大范围机械改写'),
+    MultiEdit: g('files', '同一文件需要多处有序精确替换', '先 Read，一次提交互不冲突的 edits', '跨文件修改使用 ApplyPatch'),
+    Write: g('files', '创建新文件或完整覆盖明确的小文件', '写入完整最终内容并随后验证', '修改既有文件优先 Edit/ApplyPatch'),
+    NotebookEdit: g('files', '按 cell 修改 Jupyter Notebook', '按 cell id 或位置做插入、替换、删除', '不要把 ipynb 当普通 JSON 整体改写'),
+    Glob: g('files', '按路径模式查找候选文件', '使用尽量具体的 glob，再 Read 命中项', '已知精确路径时直接 Read'),
+    Grep: g('files', '搜索字面量或正则文本', '限制目录和文件类型，再读取命中上下文', '定义、引用和类型关系优先 LSP'),
+    LSP: g('files', '获取代码的语义关系和诊断', '定位后读取相关源码确认', '不要把 LSP 摘要当作文件正文'),
+    ApplyPatch: g('files', '以统一 diff 原子修改一个或多个文件', '提交标准补丁并处理精确失败位置', '简单单点替换可用 Edit', 'preferred'),
+    Trash: g('files', '可恢复地删除文件或清理 Git 未跟踪项', '先确认目标，再移入回收站', '不要用 shell 永久删除代替'),
+    Snip: g('files', '截取或压缩当前上下文中的冗长内容', '只移除可恢复或不再需要的片段', '不要删掉当前任务所需证据'),
+    Bash: g('shell', '运行构建、测试、Git、安装及确需 shell 的命令', '执行后检查退出状态和输出', '文件读取编辑优先专用工具'),
+    PowerShell: g('shell', '运行 Windows 原生脚本和管理命令', '使用结构化参数并检查退出状态', '非 Windows 或普通文件操作不要使用'),
+    TaskOutput: g('shell', '读取后台任务增量输出或等待完成', '持有 task_id 后阻塞等待新输出', '高频轮询'),
+    TaskStop: g('shell', '停止不再需要或失控的后台任务', '传入准确 task_id 并确认终止结果', '任务仍有价值时不要提前停止'),
+    TerminalCapture: g('shell', '查看当前 TUI 终端屏幕状态', '仅在需要屏幕呈现而非命令输出时截取', '项目命令输出用 Bash/TaskOutput'),
+    WebSearch: g('web', '发现来源、查询当前信息或做多来源核实', '用短查询和明确时间范围，再打开高价值来源', '已知 URL 正文直接用 WebFetch', 'preferred'),
+    WebFetch: g('web', '读取已知 URL 的静态正文', '抓取正文后核对来源与发布时间', '需要登录态、点击或动态交互时用 WebBrowser'),
+    WebBrowser: g('web', '操作登录态网页、动态页面、表单或做网页视觉验收', '先观察，单步操作，再验证页面状态', '普通搜索、静态阅读和原生应用不要使用'),
+    BrowserBatch: g('web', '同一标签内执行可预期的多步网页流程', '一次提交有条件、失败即停的 steps，并取最终快照', '探索性或单步操作使用 WebBrowser'),
+    BrowserCDP: g('web', '需要现有浏览器工具未覆盖的原始 CDP 能力', '发送精确方法并按事件序列读取结果', '常规网页自动化优先 WebBrowser/BrowserBatch', 'last-resort'),
+    Download: g('web', '把已知 URL 的原始资源保存到本机', '给出目标路径并校验下载结果', '只阅读正文时用 WebFetch'),
+    ComputerUse: g('desktop', '用户明确要求观察或操作原生应用、系统窗口或桌面界面', '观察当前界面，执行一个动作，再验证结果', '文件、静态图片、Shell 和网页任务优先专用工具', 'last-resort'),
+    Agent: g('agents', '派生独立且边界清晰的子任务', '给出自包含任务书并在返回后核验整合', '不要拆分琐碎或强顺序工作'),
+    AgentMessage: g('agents', '向运行中的子 Agent 补充非触发消息', '按稳定 agent id 发送必要上下文', '需要追加新工作使用 AgentFollowup'),
+    AgentList: g('agents', '查看子 Agent 状态和稳定 ID', '按任务路径列出后选择目标', '已知目标 ID 时无需调用'),
+    AgentWait: g('agents', '等待指定子 Agent 进展或结果', '优先长等待，收到更新后再整合', '忙轮询'),
+    AgentInterrupt: g('agents', '当前子任务方向错误或必须立即停止', '按稳定 ID 中断并保留已有结果', '可用补充指令修正时优先 AgentFollowup'),
+    AgentFollowup: g('agents', '给既有子 Agent 追加任务并触发继续运行', '发送范围明确的后续任务', '仅传递信息使用 AgentMessage'),
+    TaskCreate: g('agents', '建立跨阶段、有依赖或需验收的正式任务', '写清目标、范围和验收标准', '简单问答和单步工作不建任务'),
+    TaskGet: g('agents', '读取一个正式任务的详情', '用稳定 task id 获取最新状态', '需要总览时使用 TaskList'),
+    TaskUpdate: g('agents', '更新正式任务状态、依赖或交付信息', '基于真实进展更新并保留因果关系', '未验证完成时不要标记完成'),
+    TaskList: g('agents', '查看当前会话任务图和阻塞关系', '先识别可执行项再行动', '已知单个 task id 时用 TaskGet'),
+    AskUserQuestion: g('agents', '关键输入无法推断或存在影响方向的真实选择', '一次提出少量互斥选项并给出推荐', '可安全推断或能继续调查时不要打断用户'),
+    EnterWorktree: g('agents', '为主任务创建隔离工作区', '创建后记录工作树基线', '只读调查或无需隔离时不要使用'),
+    ExitWorktree: g('agents', '收口当前隔离工作树', '核对 diff 后选择 apply、keep 或 discard', '未检查成果前不要丢弃'),
+    RecallMemory: g('memory', '当前回答依赖跨会话稳定偏好、决定或背景', '按主题召回并核对证据', '当前消息已足够时不要装饰性召回'),
+    RememberMemory: g('memory', '用户明确给出长期有效事实、偏好或决定', '保存原话证据和适用范围', '必须有用户明确依据'),
+    UpdateMemory: g('memory', '当前用户陈述纠正一条已有记忆', '先 Recall 定位版本，再完整替换', '不要创建冲突副本'),
+    ListMemories: g('memory', '用户要查看已保存记忆或需要管理总览', '按范围列出后再决定操作', '正常任务无需全量列出'),
+    ForgetMemory: g('memory', '用户明确要求忘记某条记忆', '定位准确 ID 后删除', '不得主动清理'),
+    SetPersona: g('memory', '用户明确要求改变长期角色或协作风格', '写入清晰、稳定的人格要求', '一次性语气请求不要持久化'),
+    ClearPersona: g('memory', '用户明确要求恢复默认角色或风格', '清除持久 Persona 并说明下回合生效', '不要自行重置'),
+    ConfirmMemory: g('memory', '用户重新确认已有同一事实', '更新目标记录的确认状态', '内容变化时使用 UpdateMemory'),
+    ReviewMemories: g('memory', '检查到期或待复核的记忆', '列出需要确认的记录', '不要自动删除'),
+    SearchConversations: g('memory', '用户提到之前、上次或既有方案', '用少量内容关键词检索', '不要提交整段问题或元词'),
+    Skill: g('memory', '加载已安装的专门工作流程', '按精确名称读取并遵循 SKILL.md', '没有匹配 Skill 时不要调用'),
+    Advisor: g('memory', '方案定型、高风险、执行不收敛或交付前需要独立复核', '提供目标、证据和分歧点，再核验建议', '不要把顾问当事实来源或权限授予者'),
+    AdvisorDecision: g('memory', '已收到 Advisor 建议，需要记录采纳结论', '按证据记录 accept、partial 或 reject', '未咨询 Advisor 时不要调用'),
+    GenerateImage: g('media', '用户要求生成或编辑图片', '给出成品目标和输出位置并检查结果', '分析已有图片不使用'),
+    GenerateSpeech: g('media', '用户要求生成语音或音频', '提供文本、声音要求和输出位置', '普通文字回答不使用'),
+    PresentResult: g('media', '向用户正式交付生成或修改后的文件', '提交真实最终文件并附简短说明', '只提交面向用户的最终产物', 'preferred'),
+};
+// ⚠️ 覆写会整体替换 tool.description 发给模型的内容——只准放"压缩后仍然完整"的
+// 摘要，不能是与原描述脱节的一句话简介。两类内容绝不能在压缩时被静默丢弃：
+//   ① 运行时探测结果（Bash 的 shell 方言警告——机器不同结果不同，覆写必须调用
+//      源头的探测函数重新拼接）——K1 事故（win32 无 bash 时 description 仍声称
+//      bash 可用，模型写出的 `mkdir -p` 必挂）的复现路径。
+//   ② 从唯一真值动态生成、或带安全相关行为引导的内容（ComputerUse 的动作枚举
+//      来自 `COMPUTER_USE_TOOL_ACTIONS`，WebBrowser 的"坐标点击只是没有选择器
+//      时的兜底、不是默认路径"）——一刀切替换成静态简介曾经真的把这两类内容
+//      压没了，`test/computerUseActionDispatch.test.ts`、
+//      `test/computerUseRepeat.test.ts`、`test/webbrowserPointer.test.ts` 三个
+//      测试就是从这次真实回归里补的，锁住"压缩后仍要包含这些内容"而不是简单地
+//      锁住某个具体的压缩产物。
+export const CONTRACT_DESCRIPTION_OVERRIDES = {
+    ComputerUse: () => `调用宿主原生桌面自动化协议观察或操作原生应用/系统窗口；仅在宿主按当前用户意图动态暴露时可用。` +
+        `动作：${COMPUTER_USE_TOOL_ACTIONS.join('、')}。` +
+        `遍历可滚动区域（长列表/文档/邮件/diff）优先用 repeat 参数一轮内连续翻页，到边界自动停且如实报告停在第几次，不要每翻一页都单独调用一次。`,
+    WebBrowser: '调用受监督真实浏览器执行单步导航、观察或 DOM 交互；定位优先级 @eN 快照引用 > CSS 选择器 > 坐标——坐标点击只是选择器确实拿不到时的兜底，不是默认路径。',
+    BrowserBatch: '在同一受监督浏览器标签和锁内执行一组结构化网页步骤。',
+    Bash: () => {
+        const base = '在当前工作目录启动一个 shell 命令，返回输出或后台任务标识。';
+        const notice = bashShellNotice();
+        return notice ? `${base}\n\n${notice}` : base;
+    },
+    Advisor: '向无工具权限的顾问模型请求一次结构化第二意见。',
+    // 通用兜底截断逻辑会在 280 字符处硬切原始 description，此前把"partial/reject
+    // 必须列出被拒绝的意见点并给出一手证据"这条唯一的自然语言说明整句吞掉（schema
+    // 的 superRefine 仍会强制校验字段，但模型看不到为什么）。用覆写绕开截断。
+    AdvisorDecision: '记录主 Agent 在一次成功的 Advisor 咨询后对其意见作出的证据判断。' +
+        '应在恢复被暂缓的写入、不可逆操作或最终交付之前调用。' +
+        '顾问只是第二意见，不是权威结论——判断必须基于代码、测试或用户约束等一手证据，不能默认采纳顾问结论。' +
+        '选择 partial 或 reject 时必须明确列出被拒绝的意见点（rejectedPoints）并说明支持该判断的一手证据；' +
+        '未经过一次成功的 Advisor 咨询时不要调用本工具。',
+    Agent: '启动一个具有明确任务书和隔离边界的子 Agent。',
+};
+function compactContractDescription(tool) {
+    const override = CONTRACT_DESCRIPTION_OVERRIDES[tool.name];
+    if (override)
+        return typeof override === 'function' ? override() : override;
+    const raw = typeof tool.description === 'function' ? tool.description() : tool.description;
+    return raw.split('\n').map((line) => line.trim()).find(Boolean)?.slice(0, 280)
+        ?? `${tool.name} 工具调用契约。`;
+}
+export function attachBuiltinPromptGuides(tools) {
+    return tools.map((tool) => {
+        const promptGuide = BUILTIN_TOOL_PROMPT_GUIDES[tool.name];
+        return promptGuide
+            ? Object.assign(tool, {
+                promptGuide,
+                description: compactContractDescription(tool),
+            })
+            : tool;
+    });
+}
+export function fallbackPromptGuide(tool) {
+    const description = typeof tool.description === 'function' ? tool.description() : tool.description;
+    const first = description.split(/(?<=[。.!?])\s+|\n/, 1)[0]?.trim() || `调用 ${tool.name}`;
+    return g('agents', first, '按工具参数契约调用并核对结构化结果');
+}

package/src/tools/toolPromptGuides.ts

@@ -0,0 +1,146 @@
+import type { Tool, ToolCategory, ToolPromptGuide } from '../types.js';
+import { bashShellNotice } from './bash/bash.js';
+import { COMPUTER_USE_TOOL_ACTIONS } from './computeruse/protocol.js';
+
+export const TOOL_CATEGORY_LABELS: Record<ToolCategory, string> = {
+  files: '文件与代码',
+  shell: 'Shell 与后台任务',
+  web: 'Web 与浏览器',
+  desktop: '桌面自动化',
+  agents: 'Agent、任务与协作',
+  memory: '记忆、Skill 与顾问',
+  media: '媒体与成果交付',
+};
+
+const g = (
+  category: ToolCategory,
+  useWhen: string,
+  method: string,
+  avoidWhen?: string,
+  priority: ToolPromptGuide['priority'] = 'normal',
+): ToolPromptGuide => ({ category, useWhen, method, ...(avoidWhen ? { avoidWhen } : {}), priority });
+
+/** Single source of truth for built-in tool selection and first-step guidance. */
+export const BUILTIN_TOOL_PROMPT_GUIDES: Readonly<Record<string, ToolPromptGuide>> = {
+  Read: g('files', '读取已知本机文本、图片、Notebook 或 PDF', '按明确路径和必要范围读取', '通过桌面图片查看器重新打开静态图片', 'preferred'),
+  Edit: g('files', '精确替换既有文件中的一处内容', '先 Read 最新内容，再提供唯一 old/new 文本', '不要用于创建文件或大范围机械改写'),
+  MultiEdit: g('files', '同一文件需要多处有序精确替换', '先 Read，一次提交互不冲突的 edits', '跨文件修改使用 ApplyPatch'),
+  Write: g('files', '创建新文件或完整覆盖明确的小文件', '写入完整最终内容并随后验证', '修改既有文件优先 Edit/ApplyPatch'),
+  NotebookEdit: g('files', '按 cell 修改 Jupyter Notebook', '按 cell id 或位置做插入、替换、删除', '不要把 ipynb 当普通 JSON 整体改写'),
+  Glob: g('files', '按路径模式查找候选文件', '使用尽量具体的 glob，再 Read 命中项', '已知精确路径时直接 Read'),
+  Grep: g('files', '搜索字面量或正则文本', '限制目录和文件类型，再读取命中上下文', '定义、引用和类型关系优先 LSP'),
+  LSP: g('files', '获取代码的语义关系和诊断', '定位后读取相关源码确认', '不要把 LSP 摘要当作文件正文'),
+  ApplyPatch: g('files', '以统一 diff 原子修改一个或多个文件', '提交标准补丁并处理精确失败位置', '简单单点替换可用 Edit', 'preferred'),
+  Trash: g('files', '可恢复地删除文件或清理 Git 未跟踪项', '先确认目标，再移入回收站', '不要用 shell 永久删除代替'),
+  Snip: g('files', '截取或压缩当前上下文中的冗长内容', '只移除可恢复或不再需要的片段', '不要删掉当前任务所需证据'),
+
+  Bash: g('shell', '运行构建、测试、Git、安装及确需 shell 的命令', '执行后检查退出状态和输出', '文件读取编辑优先专用工具'),
+  PowerShell: g('shell', '运行 Windows 原生脚本和管理命令', '使用结构化参数并检查退出状态', '非 Windows 或普通文件操作不要使用'),
+  TaskOutput: g('shell', '读取后台任务增量输出或等待完成', '持有 task_id 后阻塞等待新输出', '高频轮询'),
+  TaskStop: g('shell', '停止不再需要或失控的后台任务', '传入准确 task_id 并确认终止结果', '任务仍有价值时不要提前停止'),
+  TerminalCapture: g('shell', '查看当前 TUI 终端屏幕状态', '仅在需要屏幕呈现而非命令输出时截取', '项目命令输出用 Bash/TaskOutput'),
+
+  WebSearch: g('web', '发现来源、查询当前信息或做多来源核实', '用短查询和明确时间范围，再打开高价值来源', '已知 URL 正文直接用 WebFetch', 'preferred'),
+  WebFetch: g('web', '读取已知 URL 的静态正文', '抓取正文后核对来源与发布时间', '需要登录态、点击或动态交互时用 WebBrowser'),
+  WebBrowser: g('web', '操作登录态网页、动态页面、表单或做网页视觉验收', '先观察，单步操作，再验证页面状态', '普通搜索、静态阅读和原生应用不要使用'),
+  BrowserBatch: g('web', '同一标签内执行可预期的多步网页流程', '一次提交有条件、失败即停的 steps，并取最终快照', '探索性或单步操作使用 WebBrowser'),
+  BrowserCDP: g('web', '需要现有浏览器工具未覆盖的原始 CDP 能力', '发送精确方法并按事件序列读取结果', '常规网页自动化优先 WebBrowser/BrowserBatch', 'last-resort'),
+  Download: g('web', '把已知 URL 的原始资源保存到本机', '给出目标路径并校验下载结果', '只阅读正文时用 WebFetch'),
+
+  ComputerUse: g('desktop', '用户明确要求观察或操作原生应用、系统窗口或桌面界面', '观察当前界面，执行一个动作，再验证结果', '文件、静态图片、Shell 和网页任务优先专用工具', 'last-resort'),
+
+  Agent: g('agents', '派生独立且边界清晰的子任务', '给出自包含任务书并在返回后核验整合', '不要拆分琐碎或强顺序工作'),
+  AgentMessage: g('agents', '向运行中的子 Agent 补充非触发消息', '按稳定 agent id 发送必要上下文', '需要追加新工作使用 AgentFollowup'),
+  AgentList: g('agents', '查看子 Agent 状态和稳定 ID', '按任务路径列出后选择目标', '已知目标 ID 时无需调用'),
+  AgentWait: g('agents', '等待指定子 Agent 进展或结果', '优先长等待，收到更新后再整合', '忙轮询'),
+  AgentInterrupt: g('agents', '当前子任务方向错误或必须立即停止', '按稳定 ID 中断并保留已有结果', '可用补充指令修正时优先 AgentFollowup'),
+  AgentFollowup: g('agents', '给既有子 Agent 追加任务并触发继续运行', '发送范围明确的后续任务', '仅传递信息使用 AgentMessage'),
+  TaskCreate: g('agents', '建立跨阶段、有依赖或需验收的正式任务', '写清目标、范围和验收标准', '简单问答和单步工作不建任务'),
+  TaskGet: g('agents', '读取一个正式任务的详情', '用稳定 task id 获取最新状态', '需要总览时使用 TaskList'),
+  TaskUpdate: g('agents', '更新正式任务状态、依赖或交付信息', '基于真实进展更新并保留因果关系', '未验证完成时不要标记完成'),
+  TaskList: g('agents', '查看当前会话任务图和阻塞关系', '先识别可执行项再行动', '已知单个 task id 时用 TaskGet'),
+  AskUserQuestion: g('agents', '关键输入无法推断或存在影响方向的真实选择', '一次提出少量互斥选项并给出推荐', '可安全推断或能继续调查时不要打断用户'),
+  EnterWorktree: g('agents', '为主任务创建隔离工作区', '创建后记录工作树基线', '只读调查或无需隔离时不要使用'),
+  ExitWorktree: g('agents', '收口当前隔离工作树', '核对 diff 后选择 apply、keep 或 discard', '未检查成果前不要丢弃'),
+
+  RecallMemory: g('memory', '当前回答依赖跨会话稳定偏好、决定或背景', '按主题召回并核对证据', '当前消息已足够时不要装饰性召回'),
+  RememberMemory: g('memory', '用户明确给出长期有效事实、偏好或决定', '保存原话证据和适用范围', '必须有用户明确依据'),
+  UpdateMemory: g('memory', '当前用户陈述纠正一条已有记忆', '先 Recall 定位版本，再完整替换', '不要创建冲突副本'),
+  ListMemories: g('memory', '用户要查看已保存记忆或需要管理总览', '按范围列出后再决定操作', '正常任务无需全量列出'),
+  ForgetMemory: g('memory', '用户明确要求忘记某条记忆', '定位准确 ID 后删除', '不得主动清理'),
+  SetPersona: g('memory', '用户明确要求改变长期角色或协作风格', '写入清晰、稳定的人格要求', '一次性语气请求不要持久化'),
+  ClearPersona: g('memory', '用户明确要求恢复默认角色或风格', '清除持久 Persona 并说明下回合生效', '不要自行重置'),
+  ConfirmMemory: g('memory', '用户重新确认已有同一事实', '更新目标记录的确认状态', '内容变化时使用 UpdateMemory'),
+  ReviewMemories: g('memory', '检查到期或待复核的记忆', '列出需要确认的记录', '不要自动删除'),
+  SearchConversations: g('memory', '用户提到之前、上次或既有方案', '用少量内容关键词检索', '不要提交整段问题或元词'),
+  Skill: g('memory', '加载已安装的专门工作流程', '按精确名称读取并遵循 SKILL.md', '没有匹配 Skill 时不要调用'),
+  Advisor: g('memory', '方案定型、高风险、执行不收敛或交付前需要独立复核', '提供目标、证据和分歧点，再核验建议', '不要把顾问当事实来源或权限授予者'),
+  AdvisorDecision: g('memory', '已收到 Advisor 建议，需要记录采纳结论', '按证据记录 accept、partial 或 reject', '未咨询 Advisor 时不要调用'),
+
+  GenerateImage: g('media', '用户要求生成或编辑图片', '给出成品目标和输出位置并检查结果', '分析已有图片不使用'),
+  GenerateSpeech: g('media', '用户要求生成语音或音频', '提供文本、声音要求和输出位置', '普通文字回答不使用'),
+  PresentResult: g('media', '向用户正式交付生成或修改后的文件', '提交真实最终文件并附简短说明', '只提交面向用户的最终产物', 'preferred'),
+};
+
+// ⚠️ 覆写会整体替换 tool.description 发给模型的内容——只准放"压缩后仍然完整"的
+// 摘要，不能是与原描述脱节的一句话简介。两类内容绝不能在压缩时被静默丢弃：
+//   ① 运行时探测结果（Bash 的 shell 方言警告——机器不同结果不同，覆写必须调用
+//      源头的探测函数重新拼接）——K1 事故（win32 无 bash 时 description 仍声称
+//      bash 可用，模型写出的 `mkdir -p` 必挂）的复现路径。
+//   ② 从唯一真值动态生成、或带安全相关行为引导的内容（ComputerUse 的动作枚举
+//      来自 `COMPUTER_USE_TOOL_ACTIONS`，WebBrowser 的"坐标点击只是没有选择器
+//      时的兜底、不是默认路径"）——一刀切替换成静态简介曾经真的把这两类内容
+//      压没了，`test/computerUseActionDispatch.test.ts`、
+//      `test/computerUseRepeat.test.ts`、`test/webbrowserPointer.test.ts` 三个
+//      测试就是从这次真实回归里补的，锁住"压缩后仍要包含这些内容"而不是简单地
+//      锁住某个具体的压缩产物。
+export const CONTRACT_DESCRIPTION_OVERRIDES: Readonly<Record<string, string | (() => string)>> = {
+  ComputerUse: () =>
+    `调用宿主原生桌面自动化协议观察或操作原生应用/系统窗口；仅在宿主按当前用户意图动态暴露时可用。` +
+    `动作：${COMPUTER_USE_TOOL_ACTIONS.join('、')}。` +
+    `遍历可滚动区域（长列表/文档/邮件/diff）优先用 repeat 参数一轮内连续翻页，到边界自动停且如实报告停在第几次，不要每翻一页都单独调用一次。`,
+  WebBrowser: '调用受监督真实浏览器执行单步导航、观察或 DOM 交互；定位优先级 @eN 快照引用 > CSS 选择器 > 坐标——坐标点击只是选择器确实拿不到时的兜底，不是默认路径。',
+  BrowserBatch: '在同一受监督浏览器标签和锁内执行一组结构化网页步骤。',
+  Bash: () => {
+    const base = '在当前工作目录启动一个 shell 命令，返回输出或后台任务标识。';
+    const notice = bashShellNotice();
+    return notice ? `${base}\n\n${notice}` : base;
+  },
+  Advisor: '向无工具权限的顾问模型请求一次结构化第二意见。',
+  // 通用兜底截断逻辑会在 280 字符处硬切原始 description，此前把"partial/reject
+  // 必须列出被拒绝的意见点并给出一手证据"这条唯一的自然语言说明整句吞掉（schema
+  // 的 superRefine 仍会强制校验字段，但模型看不到为什么）。用覆写绕开截断。
+  AdvisorDecision:
+    '记录主 Agent 在一次成功的 Advisor 咨询后对其意见作出的证据判断。' +
+    '应在恢复被暂缓的写入、不可逆操作或最终交付之前调用。' +
+    '顾问只是第二意见，不是权威结论——判断必须基于代码、测试或用户约束等一手证据，不能默认采纳顾问结论。' +
+    '选择 partial 或 reject 时必须明确列出被拒绝的意见点（rejectedPoints）并说明支持该判断的一手证据；' +
+    '未经过一次成功的 Advisor 咨询时不要调用本工具。',
+  Agent: '启动一个具有明确任务书和隔离边界的子 Agent。',
+};
+
+function compactContractDescription(tool: Tool): string {
+  const override = CONTRACT_DESCRIPTION_OVERRIDES[tool.name];
+  if (override) return typeof override === 'function' ? override() : override;
+  const raw = typeof tool.description === 'function' ? tool.description() : tool.description;
+  return raw.split('\n').map((line) => line.trim()).find(Boolean)?.slice(0, 280)
+    ?? `${tool.name} 工具调用契约。`;
+}
+
+export function attachBuiltinPromptGuides<T extends Tool>(tools: readonly T[]): T[] {
+  return tools.map((tool) => {
+    const promptGuide = BUILTIN_TOOL_PROMPT_GUIDES[tool.name];
+    return promptGuide
+      ? Object.assign(tool, {
+          promptGuide,
+          description: compactContractDescription(tool),
+        })
+      : tool;
+  });
+}
+
+export function fallbackPromptGuide(tool: Tool): ToolPromptGuide {
+  const description = typeof tool.description === 'function' ? tool.description() : tool.description;
+  const first = description.split(/(?<=[。.!?])\s+|\n/, 1)[0]?.trim() || `调用 ${tool.name}`;
+  return g('agents', first, '按工具参数契约调用并核对结构化结果');
+}

package/src/tools/webbrowser/agentBrowserPath.js

@@ -37,9 +37,9 @@
 import { spawn } from 'node:child_process';
 import { chmodSync, existsSync } from 'node:fs';
 import { dirname, isAbsolute, resolve, win32 } from 'node:path';
+import { sanitizeCredentialEnv } from '../../config/configService.js';
 import { execSiblingDir } from '../../utils/greenRoot.js';
 import { findPackageRoot } from '../../utils/packageRoot.js';
-import { sanitizeCredentialEnv } from '../../config/configService.js';
 function realDeps() {
     return {
         env: process.env,
@@ -138,7 +138,9 @@ export async function detectAgentBrowser(deps) {
  */
 export function resolveBundledChromium(deps = realDeps()) {
     const sub = subdir(deps);
-    const roots = [resolve(deps.siblingDir(), 'vendor', 'chromium', sub)];
+    const roots = [
+        resolve(deps.siblingDir(), 'vendor', 'chromium', sub),
+    ];
     const root = deps.packageRoot();
     if (root)
         roots.push(resolve(root, 'vendor', 'chromium', sub));
@@ -159,8 +161,8 @@ export function resolveBundledChromium(deps = realDeps()) {
  * the user's normal Chrome profile or attempting fingerprint evasion.
  */
 export function resolveSystemBrowser(deps = realDeps()) {
-    const explicit = deps.env.MINIMAL_AGENT_BROWSER_EXECUTABLE_PATH
-        ?? deps.env.AGENT_BROWSER_EXECUTABLE_PATH;
+    const explicit = deps.env.MINIMAL_AGENT_BROWSER_EXECUTABLE_PATH ??
+        deps.env.AGENT_BROWSER_EXECUTABLE_PATH;
     if (explicit && deps.exists(explicit))
         return explicit;
     const home = deps.env.HOME ?? deps.env.USERPROFILE ?? '';
@@ -169,13 +171,21 @@ export function resolveSystemBrowser(deps = realDeps()) {
             '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
             '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
             '/Applications/Chromium.app/Contents/MacOS/Chromium',
-            home ? resolve(home, 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome') : '',
+            home
+                ? resolve(home, 'Applications/Google Chrome.app/Contents/MacOS/Google Chrome')
+                : '',
         ]
         : deps.platform === 'win32'
             ? [
-                deps.env.PROGRAMFILES ? resolve(deps.env.PROGRAMFILES, 'Google/Chrome/Application/chrome.exe') : '',
-                deps.env['PROGRAMFILES(X86)'] ? resolve(deps.env['PROGRAMFILES(X86)'], 'Microsoft/Edge/Application/msedge.exe') : '',
-                deps.env.LOCALAPPDATA ? resolve(deps.env.LOCALAPPDATA, 'Google/Chrome/Application/chrome.exe') : '',
+                deps.env.PROGRAMFILES
+                    ? resolve(deps.env.PROGRAMFILES, 'Google/Chrome/Application/chrome.exe')
+                    : '',
+                deps.env['PROGRAMFILES(X86)']
+                    ? resolve(deps.env['PROGRAMFILES(X86)'], 'Microsoft/Edge/Application/msedge.exe')
+                    : '',
+                deps.env.LOCALAPPDATA
+                    ? resolve(deps.env.LOCALAPPDATA, 'Google/Chrome/Application/chrome.exe')
+                    : '',
             ]
             : [
                 '/usr/bin/google-chrome-stable',
@@ -184,7 +194,7 @@ export function resolveSystemBrowser(deps = realDeps()) {
                 '/usr/bin/chromium',
                 '/usr/bin/chromium-browser',
             ];
-    return candidates.find((candidate) => candidate && deps.exists(candidate)) ?? null;
+    return (candidates.find((candidate) => candidate && deps.exists(candidate)) ?? null);
 }
 /** vendor 子目录名 = <arch>-<platform>（对齐 rgPath.ts / build-green.ts 的 vendor 约定）。 */
 function subdir(deps) {