mocode-ai 1.6.9 → 1.6.10

package/dist/repl/commands/diff.js

@@ -0,0 +1,189 @@
+/**
+ * 工作区命令组:/diff
+ *
+ * `/diff` = 最近一轮 agent turn 的快照(before) vs 工作区当前内容(after),
+ * 逐文件渲染 unified diff 到内容区;`/diff <N>` 选第 N 轮(1-based,与 /rollback
+ * 轮次口径一致);`/diff all` = 全部轮次的累计改动(最早的 before vs 现在)。
+ *
+ * 数据源:rollback 快照(每轮文件修改前捕获,不依赖 git)——好处是「没有 git 的目录」
+ * 也能看 agent 改了什么,且口径与 /rollback 完全一致(所见即可撤)。
+ * 限制:run_command 等不透明工具的工作区扫描快照在文件超 CAPTURE_FILE_LIMIT 时只留
+ * 指纹(contentUnavailable),这些文件显示「快照不可用」而非 diff。
+ *
+ * diff 算法:前后缀等行消除 + 单 hunk 输出,不引依赖(与 agent/index.ts lineDelta
+ * 同思路)。文件较少、行数中等的会话内 diff 足够快。
+ */
+import { readFileSync } from 'node:fs';
+import * as layout from '../../ui/layout.js';
+import { ui } from '../../ui/theme.js';
+import { getActiveRollbackStore } from '../../rollback/index.js';
+import { unhandled, next } from './types.js';
+const MAX_DIFF_LINES = 400; // 单文件输出上限:防止把万行生成文件刷满内容区
+const MAX_FILES = 60; // 单次命令最多渲染文件数(超出提示收窄)
+const CONTEXT = 3; // hunk 上下文行数
+/** 快照 before 内容 → 文本(null → 无内容/不可用;base64 解码失败按 null)。 */
+function snapshotText(snapshot) {
+    if (snapshot.before === null)
+        return null;
+    if (snapshot.encoding === 'base64') {
+        try {
+            return Buffer.from(snapshot.before, 'base64').toString('utf8');
+        }
+        catch {
+            return null;
+        }
+    }
+    return snapshot.before; // v1 快照:UTF-8 原文
+}
+/** 是否可当文本 diff:kind=file 且非 contentUnavailable(目录/软链/超预算跳过)。 */
+function diffable(snapshot) {
+    return snapshot.kind === 'file' && snapshot.contentUnavailable !== true;
+}
+/** 按行求公共前缀/后缀长度(与 lineDelta 同思路,但这里要保留行号做 hunk)。 */
+function hunkBoundaries(before, after) {
+    let head = 0;
+    while (head < before.length && head < after.length && before[head] === after[head])
+        head++;
+    let tail = 0;
+    while (tail < before.length - head &&
+        tail < after.length - head &&
+        before[before.length - 1 - tail] === after[after.length - 1 - tail])
+        tail++;
+    return { head, tail };
+}
+/**
+ * 行级 unified diff 单文件段(纯文本,颜色渲染层加)。
+ * 策略:前后缀等行消除后,中间区整段输出为「先删后加」的单 hunk。对单文件一次
+ * 编辑(agent 编辑的绝大多数形态:改一处/几处)等价于标准 diff;全文重写时输出
+ * 体积与正确 diff 同量级,只是 hunk 划分更粗。无变化返回 ''(指纹差异但文本相同)。
+ */
+export function unifiedFileDiff(pathRel, beforeText, afterText) {
+    const before = beforeText === null ? [] : beforeText.split('\n');
+    const after = afterText === null ? [] : afterText.split('\n');
+    const { head, tail } = hunkBoundaries(before, after);
+    const midBefore = before.slice(head, before.length - tail);
+    const midAfter = after.slice(head, after.length - tail);
+    if (midBefore.length === 0 && midAfter.length === 0)
+        return '';
+    const contextStart = Math.max(0, head - CONTEXT);
+    const tailStartBefore = before.length - tail;
+    const tailStartAfter = after.length - tail;
+    const contextEndBefore = Math.min(before.length, tailStartBefore + CONTEXT);
+    const contextEndAfter = Math.min(after.length, tailStartAfter + CONTEXT);
+    const lines = [];
+    lines.push(`--- a/${pathRel}`);
+    lines.push(`+++ b/${pathRel}`);
+    lines.push(`@@ -${contextStart + 1},${contextEndBefore - contextStart} +${contextStart + 1},${contextEndAfter - contextStart} @@`);
+    for (let i = contextStart; i < head; i++)
+        lines.push(` ${before[i]}`);
+    for (const line of midBefore)
+        lines.push(`-${line}`);
+    for (const line of midAfter)
+        lines.push(`+${line}`);
+    for (let i = tailStartBefore; i < contextEndBefore; i++)
+        lines.push(` ${before[i]}`);
+    return lines.join('\n');
+}
+/** 渲染一条 diff 行:加绿/删红/hunk 头青/上下文 dim。 */
+function writeDiffLine(line) {
+    if (line.startsWith('+'))
+        layout.contentWrite(`${ui.green}${line}${ui.reset}\n`);
+    else if (line.startsWith('-'))
+        layout.contentWrite(`${ui.red}${line}${ui.reset}\n`);
+    else if (line.startsWith('@@'))
+        layout.contentWrite(`${ui.cyan}${line}${ui.reset}\n`);
+    else
+        layout.contentWrite(`${ui.dim}${line}${ui.reset}\n`);
+}
+/** 读当前文件(不存在→null=「删除」;读失败→null)。 */
+function readCurrent(full) {
+    try {
+        return readFileSync(full, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+export const diffCommands = [
+    (ctx) => {
+        if (ctx.line !== '/diff' && !ctx.line.startsWith('/diff '))
+            return unhandled();
+        const arg = ctx.line === '/diff' ? '' : ctx.line.slice('/diff '.length).trim();
+        const store = getActiveRollbackStore();
+        const turns = store.listTurns();
+        if (turns.length === 0) {
+            layout.contentWrite(`${ui.dim}(本会话尚无文件改动记录——rollback 快照为空)${ui.reset}\n`);
+            return next();
+        }
+        // 轮次选择:/diff = 最近一轮;/diff N = 第 N 轮(1-based,与 /rollback 同口径);/diff all = 全部累计。
+        let label;
+        let minTurnIdExclusive; // 只统计 turnId > 此值的快照
+        if (arg === '') {
+            const last = turns[turns.length - 1];
+            minTurnIdExclusive = last.turnId - 1;
+            label = `第 ${turns.length} 轮(最近)`;
+        }
+        else if (arg === 'all') {
+            minTurnIdExclusive = 0;
+            label = '全部轮次累计';
+        }
+        else {
+            const n = Number(arg);
+            if (!Number.isInteger(n) || n < 1 || n > turns.length) {
+                layout.contentWrite(`${ui.yellow}(轮次无效:本会话共 ${turns.length} 轮,可用 /diff 1..${turns.length} 或 /diff all)${ui.reset}\n`);
+                return next();
+            }
+            minTurnIdExclusive = (turns[n - 1].turnId ?? 0) - 1;
+            label = `第 ${n} 轮`;
+        }
+        const byPath = new Map();
+        for (const snapshot of store.snapshotsSince(minTurnIdExclusive)) {
+            const existing = byPath.get(snapshot.path);
+            if (!existing || snapshot.turnId < existing.snapshot.turnId) {
+                byPath.set(snapshot.path, {
+                    snapshot,
+                    unavailable: (existing?.unavailable ?? false) || !diffable(snapshot),
+                });
+            }
+            else if (!diffable(snapshot)) {
+                existing.unavailable = true;
+            }
+        }
+        if (byPath.size === 0) {
+            layout.contentWrite(`${ui.dim}(${label}:无文件改动记录)${ui.reset}\n`);
+            return next();
+        }
+        const root = process.cwd();
+        const files = [...byPath.entries()].sort(([a], [b]) => a.localeCompare(b));
+        const shown = files.slice(0, MAX_FILES);
+        layout.contentWrite(`${ui.bold}${ui.accent}● ${label} 文件改动${ui.reset}  ${ui.dim}${shown.length}/${files.length} 文件${ui.reset}\n`);
+        for (const [rel, entry] of shown) {
+            if (entry.unavailable) {
+                layout.contentWrite(`${ui.yellow}  ⚠ ${rel}(快照不可用:超出捕获预算或非文本,无法展示 diff)${ui.reset}\n`);
+                continue;
+            }
+            const beforeText = snapshotText(entry.snapshot);
+            const afterText = readCurrent(`${root}${rel.startsWith('/') || rel.startsWith('\\') ? '' : '/'}${rel}`);
+            const diffText = unifiedFileDiff(rel, beforeText, afterText);
+            if (!diffText) {
+                // 快照记录了变更但当前内容已与 before 相同(后续轮改回/用户手改回):
+                // 仍列文件名,让用户知道它被动过,只是无净变化。
+                layout.contentWrite(`${ui.dim}  = ${rel}(已与轮前状态一致,无净变化)${ui.reset}\n`);
+                continue;
+            }
+            layout.contentWrite(`\n${ui.bold}${rel}${ui.reset}\n`);
+            const lines = diffText.split('\n');
+            const truncated = lines.length > MAX_DIFF_LINES;
+            for (const line of lines.slice(0, MAX_DIFF_LINES))
+                writeDiffLine(line);
+            if (truncated) {
+                layout.contentWrite(`${ui.dim}  …(diff 超过 ${MAX_DIFF_LINES} 行已截断,如需完整内容请直接 read_file)${ui.reset}\n`);
+            }
+        }
+        if (files.length > MAX_FILES) {
+            layout.contentWrite(`${ui.dim}  …(${files.length - MAX_FILES} 个文件未展示;改动面过大,建议 /diff <N> 收窄到单轮)${ui.reset}\n`);
+        }
+        layout.contentWrite('\n');
+        return next();
+    },
+];

package/dist/repl/commands/jobs.js

@@ -62,7 +62,7 @@ export const jobsCommands = [
         return next();
     },
     // /jobs kill [id前缀]
-    (ctx) => {
+    async (ctx) => {
         if (ctx.cmd !== '/jobs')
             return unhandled();
         const parts = ctx.line.split(/\s+/);
@@ -77,7 +77,7 @@ export const jobsCommands = [
             layout.contentWrite(`${ui.dim}任务 ${job.id} 已是 ${job.status}，无需 kill${ui.reset}\n`);
             return next();
         }
-        const ok = killBackgroundJob(job);
+        const ok = await killBackgroundJob(job);
         layout.contentWrite(ok
             ? `${ui.yellow}已 kill 任务 ${job.id}${ui.reset}\n`
             : `${ui.red}kill 失败（进程可能已退出；PID=${job.pid ?? '?'})${ui.reset}\n`);

package/dist/repl/commands/registry.js

@@ -17,6 +17,7 @@ import { effortCommands } from './effort.js';
 import { routerCommands } from './router.js';
 import { toolGroupCommands } from './tool-group.js';
 import { jobsCommands } from './jobs.js';
+import { diffCommands } from './diff.js';
 import { scheduleCommands } from './schedule.js';
 import { botsCommands } from './bots.js';
 /**
@@ -44,6 +45,7 @@ export const commandHandlers = [
     ...routerCommands,
     ...toolGroupCommands,
     ...jobsCommands,
+    ...diffCommands,
     ...scheduleCommands,
     ...botsCommands,
 ];

package/dist/repl/commands.js

@@ -29,6 +29,7 @@ export function buildSlashCommands() {
         { name: '/resume', desc: d('commands.sessionResume') },
         { name: '/sessions', desc: d('commands.sessionBrowse') },
         { name: '/rollback', desc: d('commands.sessionRollback') },
+        { name: '/diff', desc: '查看 agent 文件改动 diff(/diff [N]|all,快照 vs 工作区)' },
         { name: '/ssearch <关键词>', value: '/ssearch ', submit: false, desc: '跨会话搜索归档会话' },
         { name: '/jobs', desc: '后台任务列表(/jobs log/kill <id前缀>)' },
         { name: '/schedules', desc: '查看定时计划与调度守护状态' },

package/dist/repl/runtime.js

@@ -173,10 +173,17 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
     const runtime = defaultRuntime;
     await runtime.start();
     const runtimeContext = runtime.context;
-    // MCP 在工具表和 LLM schema 创建前连接；失败的单个 server 只给提示，不阻断 REPL。
-    const mcpReport = await initializeAllMcp();
-    registerToolsExtension('mcp', getMcpTools());
-    refreshChatTools();
+    // MCP 异步并行连接(不阻塞首帧):旧序「await initializeAllMcp() → banner」在
+    // npx/stdio 类 server 上把 REPL 首屏卡住数秒(黑屏等待)。现在 banner/欢迎块先画,
+    // MCP 在后台连;完成后注册工具 + refreshChatTools + 在内容区补连接结果行。
+    // runTurn 前 mcpReady barrier 兜底:用户在连接完成前就发消息时等它就绪(见 runTurn)。
+    const mcpReady = (async () => {
+        const report = await initializeAllMcp();
+        registerToolsExtension('mcp', getMcpTools());
+        refreshChatTools();
+        return report;
+    })();
+    void mcpReady.catch(() => undefined); // 连接失败不产生 unhandledRejection;报告行由 then 写
     // --resume:读回该会话的轮次/快照;无文件则从 history 重建 turns(无快照→旧轮次文件改动不可撤销)
     let currentSessionId = sessionId;
     if (!currentSessionId)
@@ -270,12 +277,16 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
     else {
         layout.writeBanner(bannerLines(banner()));
     }
-    if (mcpReport.connected.length > 0) {
-        layout.contentWrite(`${ui.dim}  ↳ 已连接 MCP: ${mcpReport.connected.join(', ')} (${getMcpTools().length} 个工具;外部工具每次均需授权)${ui.reset}\n`);
-    }
-    for (const warning of mcpReport.warnings) {
-        layout.contentWrite(`${ui.yellow}  ⚠ ${warning}${ui.reset}\n`);
-    }
+    // MCP 连接结果在就绪后补写(后台并行连接,不再阻塞上方首帧);用户已滚动时仍
+    // 落在内容区尾部,与启动期其它提示行为一致。
+    void mcpReady.then((mcpReport) => {
+        if (mcpReport.connected.length > 0) {
+            layout.contentWrite(`${ui.dim}  ↳ 已连接 MCP: ${mcpReport.connected.join(', ')} (${getMcpTools().length} 个工具;外部工具每次均需授权)${ui.reset}\n`);
+        }
+        for (const warning of mcpReport.warnings) {
+            layout.contentWrite(`${ui.yellow}  ⚠ ${warning}${ui.reset}\n`);
+        }
+    });
     if (!isModelConfigured()) {
         // 未配置 baseURL/apiKey:醒目提示引导 /model(不退出,REPL 仍可用;发消息会失败但不崩)。
         layout.contentWrite(`${ui.yellow}  ⚠ 未配置大模型。输入 ${ui.cyan}/model${ui.yellow} 配置 baseURL / apiKey / model(即时生效),或退出后运行 ${ui.cyan}mocode config${ui.yellow} 走向导。${ui.reset}\n`);
@@ -456,6 +467,9 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
         let routingDone = toolPolicy != null;
         try {
             signal = startRunningListener(placeholder);
+            // MCP 后台连接兜底:启动后在连接完成前就发消息的极端窗口,先等就绪再路由,
+            // 保证路由看到的工具表含 MCP 工具(否则本 turn 工具簇不含 mcp__,模型路由失真)。
+            await mcpReady.catch(() => undefined);
             // 入口设定本轮初始模式（合成执行轮传 false→auto；用户轮传当前 mode）。
             // setAgentMode 触发 listener 重写 history[0]；模式只由用户面切换，runAgent 每步读取当前值。
             setAgentMode(planMode ? 'plan' : 'auto');
@@ -533,6 +547,11 @@ export async function startRepl(initialHistory, sessionId, sandboxRootOverride,
                 refreshStatusBase(history);
                 layout.drawStatusBar();
             }, toolPolicy, initialToolRoute, runtime);
+            // 撞限 salvage 摘要要在 TUI 落地:runAgent 只把 finalText 带回不渲染,主线撞限的
+            // 收尾摘要若不打印,这笔收尾请求的 token 就白花(用户只看到「达到最大步数」一行)。
+            if (result.terminationReason === 'max_steps' && result.finalText) {
+                layout.contentWrite(result.finalText.endsWith('\n') ? result.finalText : `${result.finalText}\n`);
+            }
             if (toolPolicy)
                 lastToolGroups = toolPolicy.groupNames;
             // 本轮 token 累计(底栏模式 chip 右边显示)。undefined = 后端不开 include_usage。

package/dist/rollback/store.js

@@ -392,6 +392,13 @@ export class RollbackStore {
     listTurns() {
         return this.turns.slice();
     }
+    /**
+     * 只读侧门(供 /diff 渲染):返回 turnId > sinceTurnId 的全部快照,浅拷贝数组。
+     * 快照内容含 before 原文,调用方不得 mutate 返回值;用于展示,不影响回滚语义。
+     */
+    snapshotsSince(sinceTurnId) {
+        return this.snapshots.filter((snapshot) => snapshot.turnId > sinceTurnId);
+    }
     findCutoffIndex(n, history) {
         let seen = 0;
         for (let i = 0; i < history.length; i++) {

package/dist/runtime/dev-server-manager.js

@@ -127,7 +127,29 @@ async function probeReady(url) {
         clearTimeout(timer);
     }
 }
-function killTree(pid) {
+/**
+ * 异步树杀(运行期路径):spawnSync('taskkill') 会同步阻塞事件循环(扫树期间流式渲染/
+ * 并行工具停摆)。发出 kill 后等 taskkill 退出,不牺牲「进程已终止」语义。
+ * 退出路径(stopAllDevServersSync)必须同步,用 killTreeSync 保留原行为。
+ */
+async function killTree(pid) {
+    if (!IS_WINDOWS) {
+        try {
+            process.kill(pid, 'SIGTERM');
+        }
+        catch {
+            // 已退出或无权限:best-effort。
+        }
+        return;
+    }
+    await new Promise((resolve) => {
+        const killer = spawn('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
+        killer.on('close', () => resolve());
+        killer.on('error', () => resolve());
+    });
+}
+/** 同步树杀:仅供进程退出钩子(stopAllDevServersSync)使用,运行期请走异步版。 */
+function killTreeSync(pid) {
     try {
         if (IS_WINDOWS) {
             spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore' });
@@ -266,13 +288,13 @@ export async function startDevServer(opts) {
     catch (error) {
         // 启动失败 / 被中断:不留孤儿进程。
         record.stopRequested = true;
-        killTree(record.pid);
+        await killTree(record.pid);
         finalizeExit(record, record.child.exitCode, record.child.signalCode);
         throw error;
     }
     if (wantsReadySignal && !ready) {
         record.stopRequested = true;
-        killTree(record.pid);
+        await killTree(record.pid);
         finalizeExit(record, record.child.exitCode, record.child.signalCode);
         throw new DevServerManagerError('TIMEOUT', `Dev server did not become ready within ${timeoutMs}ms and was stopped. Recent output:\n${record.recentLog.trim() || '(no output)'}`);
     }
@@ -328,7 +350,7 @@ export async function stopDevServer(id) {
         return { ...snapshot(record), alreadyStopped: true };
     }
     record.stopRequested = true;
-    killTree(record.pid);
+    await killTree(record.pid);
     const deadline = Date.now() + STOP_GRACE_MS;
     while (Date.now() < deadline && isAlive(record.pid)) {
         await sleep(50);
@@ -350,7 +372,7 @@ export function stopAllDevServersSync() {
         if (record.state !== 'running')
             continue;
         record.stopRequested = true;
-        killTree(record.pid);
+        killTreeSync(record.pid);
         finalizeExit(record, record.child.exitCode, record.child.signalCode);
     }
 }

package/dist/schedule/cli.js

@@ -83,7 +83,7 @@ export async function runScheduleCli(rawArgs) {
             return 0;
         }
         case 'stop':
-            process.stdout.write(stopDaemon() ? 'Scheduler stopped\n' : 'Scheduler was not running\n');
+            process.stdout.write((await stopDaemon()) ? 'Scheduler stopped\n' : 'Scheduler was not running\n');
             return 0;
         case 'status': {
             const state = getDaemonState();

package/dist/schedule/daemon.js

@@ -150,12 +150,12 @@ export function startDaemon(port = DEFAULT_PORT) {
     fs.writeFileSync(daemonStatePath(), `${JSON.stringify(state, null, 2)}\n`);
     return { started: true, state };
 }
-/** 停止守护进程并清状态。 */
-export function stopDaemon() {
+/** 停止守护进程并清状态。异步:树杀不再阻塞事件循环(见 jobs/launch.ts killTree)。 */
+export async function stopDaemon() {
     const state = getDaemonState();
     if (!state)
         return false;
-    const ok = killTree(state.pid);
+    const ok = await killTree(state.pid);
     try {
         fs.rmSync(daemonStatePath());
     }

package/dist/skills/builtin-skills.js

@@ -42,94 +42,135 @@ CLI dump 一般是 \`path/to/file.ts:line:col  symbol\` 形式,与 grep 一样
 `;
 const BRAINSTORM_BODY = `# Brainstorming(需求澄清)
 
-开工前的需求澄清流程:当需求可能被理解错、或信息不足以决定交付物时,先用对话把需求问清楚,再动手。
+开工前的需求澄清:当需求可能被理解错、信息不足或只给了粗略想法时,先用对话把需求收敛成用户认可的设计,再动手。
 
-## 何时进入
+## 铁律
 
-- 用户的需求存在两种以上实质不同的理解,会导致不同交付物;
-- 缺少关键信息(目标、范围、约束、输入输出、验收标准),且靠仓库证据无法补全;
-- 改动涉及不可逆操作 / 公共 API / 多个会实质改变产品行为的方案;
-- 用户只给了粗略想法(如「帮我做个 X」),期望先讨论。
+开始写产品代码之前,必须完成所选路径对应的确认门。**批准是分阶段的**:用户认可想法 ≠ 批准写代码;对方案的口头认可只推进到下一步,不越级。
 
-## 何时不要进入
+## 第一步:分级(说出来,让用户可纠正)
 
-- 任务清晰且存在合理默认做法 → 直接干,在最终回复中披露假设;
-- 只是命名或实现细节 → 遵循仓库惯例自主决定;
-- 用户已明确表示「直接做 / 别问我」。
+对需求先分类并明说——「这个需求看起来是有界改动,我会先在聊天里给短设计」:
 
-## 流程
+- **探针(Spike)**:可行性问题(「能不能…」「先快速试试」),产出是结论不是保留的代码。2-3 句说清要验证什么,口头确认即可动手;产出物明确标注一次性。
+- **有界(Bounded)**:改动仓库里**已存在**的流程(新 flag、小端点、单文件修复)。问关键问题后,在聊天里给出几段短设计,停下等确认;不写 spec 文件。
+- **架构级(Architectural)**:新项目、新子系统、改变组件间接口。走完整流程:澄清问题 → 分节设计 → 落盘 spec 文档 → 用户审阅 spec → 再谈实施计划。
+
+判断不了时取更重的级别。**棘轮单向**:任务中途发现隐藏复杂度 → 停下明说,升级路径;永不中途降级。
+
+## 澄清阶段怎么问
+
+1. **最小探查**:只读提出好问题所必需的代码(有 .codegraph/ 时优先 codegraph skill),不做大范围调研。
+2. **复述理解**:一两句复述你对需求的理解,区分「用户说的」和「我假设的」,邀请纠正。
+3. **一次一个问题**:每轮 ask_human 只问当前最关键的一个,自由文本优先(options: []);仅当答案能收敛为少量明确选项时才给 2-4 项。回答引出新歧义时先澄清新歧义,不重复问已回答的。
+
+## 收敛确认
 
-1. **最小探查**:只读取提出好问题所必需的代码和上下文(有 .codegraph/ 时优先 codegraph skill),不要在澄清阶段做大范围调研。
-2. **复述理解**:用一两句向用户复述你对需求的理解,并点出关键分歧或未知点。
-3. **一次只问一个问题**:每轮 \`ask_human\` 只问当前最关键的一个问题,自由文本优先(\`options: []\`);仅当答案能收敛为少量明确选项时才给 2-4 个选项。不要一次甩多个问题。
-4. **据回答继续**:必要时追问下一个最关键的问题;回答引出新歧义时先澄清新歧义。不要重复问已回答的内容。
-5. **收敛确认**:需求清晰后,用一次 \`ask_human\` 分节呈现方案——目标 / 范围 / 做法与受影响文件 / 不做什么 / 验证方式,选项固定为「确认,开始做」「再调整」「取消」。
-6. **转入执行**:用户确认后再开始改动。
+需求清晰后,用一次 ask_human 分节呈现方案——目标 / 范围 / 做法与受影响文件 / 不做什么 / 验证方式,选项固定为「确认,开始做」「再调整」「取消」。
+
+**呈现前自查一遍(静默)**:有没有 TBD 或模糊措辞?各节是否互相矛盾?有没有可双解的需求点(有则当场选定并写明)?修完再呈现,自查过程不必展示。
 
 ## 边界
 
-- 澄清阶段的 \`ask_human\` 不计入「执行阶段每轮最多 2 次」的预算,但仍要克制:每个问题都必须实质推进理解。用户表现出不耐烦或说「你决定」时,采用最安全的可逆默认做法并说明。
+- 澄清期 ask_human 不计入「执行阶段每轮最多 2 次」的预算,但每个问题必须实质推进理解;用户不耐烦或说「你决定」时,取最安全的可逆默认并说明。
 - 用户取消:停止,不要按自己的猜测继续。
-- 问题与方案用用户的语言表述。
+- 问题与方案用用户的语言。
 - 澄清期间保持只读:不改文件、不跑有副作用的命令。
 `;
 const DEBUGGING_BODY = `# Systematic Debugging(系统化调试)
 
-遇到 bug、测试失败或报错时,用「先理解再修」的流程,禁止靠猜测随机改动。
+遇到 bug、测试失败或报错时,用「先理解再修」的流程。**违反本流程的字面,就是违反调试的精神。**
+
+## 铁律
+
+> 未定位根因,不得提出修复。
 
-## 核心原则
+症状不是原因。「让报错消失」和「修好」是两回事——说不清为什么有效,就只是掩盖。
 
-- 没有找到根因之前,不要改代码。症状不是原因。
-- 一次只改一处;改完无法解释为什么有效,就不算修好。
-- 不要用「删掉重试 / 换个写法试试 / 加个 await 碰碰运气」这类无假设的尝试。
+## 最容易跳过的时刻(恰恰必须用本流程)
+
+- 时间紧、线上着急、「就改一行」;
+- 已经连试 2 次以上修复仍失败——这不是「再试一次」的信号,是前提或架构有问题的信号,回到第 1 步质疑假设;
+- 感觉「我大概知道问题在哪」;
+- 报错看起来很简单——简单 bug 也有根因。
 
 ## 流程
 
-1. **复现**:先稳定复现问题。复现不了,先弄清楚触发条件(输入、环境、顺序),必要时向用户索取复现步骤或报错全文。
-2. **收集证据**:读完整报错和堆栈,定位到具体文件/行;用日志或最小用例确认数据在**哪一步**开始出错。有 .codegraph/ 时用它追调用链。
-3. **形成根因假设**:用一句话说明「为什么当前行为会必然产生这个症状」,并指出能证伪它的检查点。
-4. **验证假设**:先做最小检查确认假设成立,再动手。如果证据与假设矛盾,回到第 2 步,不要硬修。
-5. **最小修复**:只改根因,不动无关代码;避免为绕过症状而加补丁、吞异常、放宽校验。
-6. **验证修复**:复现用例通过;补一个能覆盖该 bug 的回归测试(成本合理时);检查同类路径是否也受影响。
+1. **复现**:先稳定复现。复现不了就先弄清触发条件(输入、环境、顺序),必要时向用户索取复现步骤或报错全文。
+2. **收集证据**:读完整报错和堆栈,定位到具体文件/行;用日志或最小用例确认数据在**哪一步**开始出错。多组件系统(如 CI→构建→签名、API→DB)先在组件边界加诊断输出,跑一次看断在哪一层,再深入该层。有 .codegraph/ 时用它追调用链。
+3. **形成单一假设**:一句话说清「X 是根因,因为 Y」,并指出能证伪它的检查点。同时只验证这一个假设,不许一次改多处。
+4. **最小验证**:先做最小检查确认假设成立;证据与假设矛盾 → 回到第 2 步,不要硬修。承认「我没看懂这段」比假装看懂更好。
+5. **最小修复**:只改根因,不动无关代码;不加吞异常、放宽校验这类绕症状的补丁。
+6. **回归验证**:复现用例通过;按红绿法补回归测试(见 verification-before-completion skill);检查同类路径是否同样受影响。
 7. **复盘**:说明根因、改动、验证方式;仍有不确定就如实说。
 
-## 反模式
+## 合理化借口对照
+
+| 借口 | 现实 |
+|------|------|
+| 「问题很简单,不用走流程」 | 简单问题也有根因;流程对简单问题很快 |
+| 「紧急,没时间走流程」 | 系统化比反复乱改快 |
+| 「先随手修一下再查原因」 | 第一次随手修会定下错误方向 |
+| 「多改几处一起试,省时间」 | 无法隔离哪个改动起效,还引入新变量 |
+| 「我知道问题在哪,直接修」 | 看到症状 ≠ 理解根因 |
+| 「再试一次就好了」 | 3+ 次失败说明该质疑前提,不是再试 |
 
-- 报错还没看完就开始改;
-- 同一处反复改了 3 次仍失败却不换思路;
-- 修复让错误「消失」但说不清机制(往往只是被掩盖);
-- 顺手重构与 bug 无关的代码。
+如果系统化调查后确认问题确实源于环境/时序/外部依赖、没有代码层根因:记录调查过程,实现恰当处理(重试、超时、报错信息)——这本身是完成流程,不是失败。
 `;
 const CODE_REVIEW_BODY = `# Code Review(自审 diff)
 
 提交/收尾前,对**自己本次的改动**做一遍审查。改动越多越要做;几行的机械改动可快速过。
 
-## 流程
+## 独立视角优先
+
+自审最大的敌人是实现思维惯性——评估和实现在同一个上下文里互相污染。**若工具面可用 sub-agent,优先派子代理审查**:给它精心构造的上下文(任务目标、验收要求、diff 范围),不要给它你的会话历史;只收回结论。sub-agent 不可用或改动很小时自查,按清单逐项过,不要凭整体印象。
+
+## 清单
 
-1. **拿到完整 diff**:只审本次相关改动(\`git diff\` / 未提交改动),不要凭记忆。
-2. **意图对齐**:每处改动是否都服务于任务?有没有夹带无关重构、调试残留(console.log、注释掉的代码、临时文件)?
-3. **正确性**:逻辑分支是否完整;边界(空值、空数组、并发/重复调用、错误路径);条件取反、off-by-one;异步是否有未 await 或未处理的 rejection。
-4. **错误处理**:失败时是否给出有用信息而非静默吞掉;资源(文件句柄、锁、子进程)是否正确释放。
-5. **兼容与契约**:公共 API、类型、配置键、默认值是否保持兼容;是否违背仓库既有约定(如纯 ESM 的 .js 扩展名、工具契约)。
-6. **安全与副作用**:是否引入不可逆操作、权限绕过、注入面;写入/执行是否走了既有护栏。
-7. **完整性**:文档、调用方、测试是否需要同步;用户要求的场景是否都覆盖。
-8. **修复后复审**:发现问题就改,改完重新看那部分 diff,确认没有引入新问题。
+1. **意图对齐**:每处改动是否都服务于任务?有没有夹带无关重构、调试残留(console.log、注释掉的代码、临时文件)?
+2. **正确性**:逻辑分支是否完整;边界(空值、空数组、并发/重复调用、错误路径);条件取反、off-by-one;异步是否有未 await 或未处理的 rejection。
+3. **错误处理**:失败时是否给出有用信息而非静默吞掉;资源(文件句柄、锁、子进程)是否正确释放。
+4. **兼容与契约**:公共 API、类型、配置键、默认值是否保持兼容;是否违背仓库既有约定(如纯 ESM 的 .js 扩展名、工具契约)。
+5. **安全与副作用**:是否引入不可逆操作、权限绕过、注入面;写入/执行是否走了既有护栏。
+6. **完整性**:文档、调用方、测试是否需要同步;用户要求的场景是否都覆盖。
 
-## 输出
+## 处理与输出
 
-如实质问题:直接修复,最终回复中列出发现并修复了什么。
-如无问题:简要说明审过哪些点。不要为了凑数报无关紧要的风格问题——格式交给 Prettier。
+- 重要问题:立即修复,修完重看那部分 diff,确认没有引入新问题;
+- 次要问题:记录,不阻塞收尾;
+- 无实质问题:简要说明审过哪些点。
+- 不要为了凑数报风格问题——格式交给 Prettier。
 `;
 const VERIFICATION_BODY = `# Verification Before Completion(完成前证据验证)
 
 宣布任务「完成」之前,必须用实际运行的证据确认改动真的生效。禁止把「代码看起来对 / 应该能跑」当作完成。
 
-## 硬性规则
+## 铁律
+
+**没有本次修改之后产生的运行证据,不得做任何完成/成功/通过类声称。**上一次运行的旧结果、部分检查、别的检查碰巧通过,都不算证据。
+
+## 声称 → 必须的证据 → 不算数
+
+| 声称 | 必须有 | 不算数 |
+|------|--------|--------|
+| 测试通过 | 测试命令输出 0 failures | 上次运行、「应该通过」 |
+| 构建成功 | build 命令 exit 0 | lint 通过、日志看着没报错 |
+| bug 已修 | 用能复现该 bug 的输入跑过且通过 | 改完代码就当修好 |
+| 回归测试有效 | 红绿循环验证过(见下) | 测试只绿过一次 |
+| 子 agent 完成 | 核查其落盘的改动 | 子 agent 自报 success |
+| 需求全部满足 | 逐条对照用户的验收要求 | 相关测试都绿 |
+
+## 红绿回归验证
+
+补回归测试时,只绿过一次不算数:写测试 → 确认它在修复前的代码上会红(临时回滚修复,或注入原触发输入) → 恢复修复 → 确认转绿。这样才能证明测试测的就是这个 bug,而不是碰巧通过。
+
+## 红旗(出现即停)
 
-1. **先验证,再宣称完成**:任何「已修复 / 已完成 / 能用了」的结论,前面必须有一次实际执行及其真实输出。
-2. **验证必须对得上声称**:改了行为就跑能体现该行为的场景;修了 bug 就用能复现该 bug 的输入确认;不能用「编译通过」代替「功能正确」。
-3. **看完整结果**:确认退出码、断言/测试通过数、关键输出行;有 warning 或失败项要逐条判断,不能只看最后一行没报错。
-4. **验证不了就如实说**:环境缺失、需要用户凭据/设备、或验证成本明显不合理时,说明已验证到哪一步、什么没验证、用户可以怎么验证。不要假称已验证。
+- 「应该没问题」「大概可以」「看起来对」;
+- 还没跑验证就表达满意(「搞定」「完美」);
+- 引用改动前的旧运行结果;
+- 拿与改动无关的检查冒充验证;
+- 测试失败或被跳过,却报告成功。
 
 ## 怎么选验证(按成本,够小即可)
 
@@ -138,12 +179,9 @@ const VERIFICATION_BODY = `# Verification Before Completion(完成前证据验
 - UI/交互类改动:能自动化就自动化(浏览器工具/webapp 测试),否则明确告知未做可视化验证;
 - 纯文档、注释等零行为改动:可不跑验证。
 
-## 反模式
+## 验证不了就如实说
 
-- 「理论上没问题」「逻辑上应该可以」——没有运行证据就不算完成;
-- 测试其实失败/被跳过,却报告成功;
-- 跑了一个与改动无关的检查,用它冒充验证;
-- 改完代码不重新运行,沿用改动前的旧结果。
+环境缺失、需要用户凭据/设备、或验证成本明显不合理时:说明已验证到哪一步、什么没验证、用户可以怎么验证。如实报告未验证项不是失败;假称验证才是。
 `;
 /** 单一事实源:加新内置 skill 在此数组加一条。 */
 export const builtinSkills = [
@@ -175,14 +213,16 @@ export const builtinSkills = [
     },
     {
         name: 'systematic-debugging',
-        description: '系统化调试:遇到 bug、测试失败或报错时,先稳定复现并定位根因(读完堆栈、用证据验证假设),再做最小修复并回归验证。' +
-            '禁止没找到根因就靠猜测反复改代码。',
+        description: '系统化调试:遇到 bug、测试失败或报错时,在提出任何修复之前先稳定复现并定位根因(读完堆栈、用证据验证假设),' +
+            '再做最小修复并回归验证。禁止没找到根因就靠猜测反复改代码。',
         body: DEBUGGING_BODY,
         dir: 'builtin',
         skillMdPath: 'builtin',
         context: 'inline',
         modelInvocable: true,
         origin: 'builtin',
+        // debug 需要深度推理:激活期把 effort 提到 high(仅未显式设置时生效)。
+        effort: 'high',
         warnings: [],
     },
     {