mocode-ai 1.0.2 → 1.0.4

package/README.md

@@ -279,6 +279,19 @@ Control via environment variables:
 
 See [docs/USAGE_SNAPSHOT_SKILL.md](./docs/USAGE_SNAPSHOT_SKILL.md) for detailed usage.
 
+## Working discipline (Build-and-Self-Verify)
+
+Every coding task runs through four sequential phases. Skipping or merging them is a failure mode — the system prompt injects this discipline on every turn (see `src/agent/work-discipline.ts`):
+
+1. **Plan & Discover** — restate the goal, identify the acceptance signal, read the relevant code, and surface ambiguities via `ask_human` before implementing.
+2. **Build** — make the smallest change that satisfies the spec; tests for new/changed behavior are an obligation, not a "should" aspiration.
+3. **Verify** — run a real, executable verification (typecheck, the project's test command, or a focused reproducer). Read the full output. Compare the result to the **spec**, not to your own diff.
+4. **Fix** — any failure → return to the spec, not to the diff. Re-derive what the spec requires; after a fix, re-run Phase 3 end-to-end. Cap blind retries at three identical failed attempts before changing approach.
+
+Hard rule: *"I read the code and it looks right" is not a completion signal.* A task is complete only when executable verification against the spec has run, its full output has been read, and the result matches the spec — and the final reply names the command, the output, and the spec line it satisfied.
+
+The section adapts lightly per `model_family` (anthropic / openai / qwen) so the wording matches each base model's instruction-following style. All four variants share the same 4-phase English body; only the opener sentence and the `[model: X]` tag differ. User language preference is handled by the existing i18n block.
+
 ## Project memory (MOCODE.md)
 
 MoCode has a **two-tier memory** model distinct from skills:

package/README.zh-CN.md

@@ -260,6 +260,19 @@ mocode 自动扫描以下目录的 skill(每个 skill 是 `<name>/SKILL.md`,带
 
 skill 的 `description` 注入系统提示(渐进式披露第①层),模型只在任务相关时调 `use_skill` 加载完整正文(第②层)。用 `/skills` 查看已发现的 skill。
 
+## 工作纪律(4 阶段 — Build-and-Self-Verify)
+
+每个 coding 任务必须按顺序走完 4 个阶段。跳过/合并 = 失败模式 —— system prompt 每轮注入这段纪律(见 `src/agent/work-discipline.ts`):
+
+1. **Plan & Discover** — 用一句话复述目标,明确验收信号(测试名/命令输出/文件存在/行为变化);写代码前先读相关代码;不可逆选择(删除/公开 API/权限)用 `ask_human` 主动澄清。
+2. **Build** — 用最小改动满足 spec,不夹带无关重构;新/改行为必须有对应测试 —— 目标里的 "should" 是义务。
+3. **Verify** — 跑**真实**可执行验证(typecheck/项目 test 命令/聚焦 reproducer),读完整输出,与 **spec** 对比,不是与自己的 diff 对比。
+4. **Fix** — 任何失败 → 回 spec,不是回 diff;修完重跑 Phase 3 全程;同工具同参数 3 次连续失败后**换思路**(换工具/换不变量/`ask_human`)。
+
+**硬规则:** "我读代码觉得对"不是完成信号。任务完成的唯一判据:对 spec 的可执行验证已跑过、完整输出已读、结果与 spec 匹配 —— 最终回复里**显式给出证据**(哪个命令、哪段输出、对应 spec 哪一行)。
+
+段内措辞按 `model_family`(anthropic / openai / qwen)轻量适配,贴合各 base model 的指令遵从习惯。4 份共用同一套 4 阶段结构 + 英文纪律文本,只在首句与 `[model: X]` 标签上区分;用户语言偏好由现有 i18n 段负责。
+
 ## 项目记忆(MOCODE.md)
 
 mocode 的**双层记忆**模型,跟 Skills 是两件事:

package/dist/agent/core.js

@@ -10,6 +10,9 @@ import { executeToolOutcome, getToolCapabilities, isFileMutationTool, tools, } f
 import { checkPermission } from '../permissions/index.js';
 import { validateToolArguments } from '../tools/validation.js';
 import { getPlanDisabledTools, getRuntimeDisabledTools } from '../tools/constants.js';
+import { createPreCompletionChecklistMiddleware, } from './middleware/checklist.js';
+import { inferModelFamily } from './work-discipline.js';
+import { reflectionHint, classifyError } from './retry-classifier.js';
 import { getAgentMode, setAgentMode } from './mode.js';
 import { maybeCompact, contextState, dropContextFromHistory, createTraceEvent, summarizeToolArguments, safeProviderId, } from '../session/index.js';
 import { createBudgetScheduler } from '../session/scheduler.js';
@@ -165,6 +168,39 @@ function readDiffContext(tc, parsed) {
  *  - lifecycle 也在每个 runAgentCore 实例化一次,登记 grep/glob/codegraph 等 producer
  *    与 read/edit/write 的 consumer 关系;孤立+老化自动 STUB(观察类工具永不到 STUB)。
  *  - 开关关闭时 lifecycle=null 完全跳过。 */
+/** RETRY-01: 把 thrash hint + 反思指针一次性拼到 output 尾部。
+ *  - thrash hint 永远可能存在(连续失败才出现);
+ *  - 反思指针仅在 error/denied 状态追加,success 跳过避免噪声。
+ *  抽出 helper 是为了 sequential + parallel 两处共用,避免拼装逻辑漂移。
+ *  返回追加后的字符串 + 反思 category(用于 QUAL-01 trace 硬事件),
+ *  success / aborted 时 category === null,调用方据此决定是否 emit 'retry_reflection' 事件。 */
+function appendRetryAnnotations(output, status, code, thrashHint) {
+    let result = thrashHint ? `${output}${thrashHint}` : output;
+    let reflectionCategory = null;
+    if (status !== 'success' && status !== 'aborted') {
+        reflectionCategory = classifyError(code);
+        const reflection = reflectionHint(reflectionCategory);
+        result = `${result}\n\n[retry reflection: ${reflectionCategory}]\n${reflection}`;
+    }
+    return { output: result, reflectionCategory };
+}
+/** ASK-01: ask_human 工具调用本 turn 计数器。纯函数无副作用,
+ * 计数规则简单:1-based(本 turn 第 1 次 = 1, 第 2 次 = 2, 第 3+ 次 = exceeded)。
+ * 预算上限常量与工作纪律段 "Budget: at most 2 ask_human calls per turn" 保持一致;
+ * 改这里时,fixture 与纪律段都要同步。 */
+export const ASK_HUMAN_PER_TURN_BUDGET = 2;
+export function askHumanBudgetAnnotation(askHumanCountThisTurn, status) {
+    // 工具失败 / aborted 不追加(避免噪声;模型已被错误消息告知失败)。
+    if (status !== 'success')
+        return null;
+    if (askHumanCountThisTurn < ASK_HUMAN_PER_TURN_BUDGET)
+        return null;
+    if (askHumanCountThisTurn === ASK_HUMAN_PER_TURN_BUDGET) {
+        return `\n\n[ask budget] This was your ${askHumanCountThisTurn}nd ask_human call this turn (budget = ${ASK_HUMAN_PER_TURN_BUDGET}). For the rest of this turn, prefer the safer default and disclose the choice in your final reply — do not silently guess.`;
+    }
+    // 第 3+ 次(超过预算):强硬提示,鼓励模型停下问自己是否还有意义。
+    return `\n\n[ask budget EXCEEDED] This is ask_human call #${askHumanCountThisTurn} this turn (budget = ${ASK_HUMAN_PER_TURN_BUDGET}). Stop asking; choose a default, implement, and disclose the choice in your final reply. Continuing to ask is more harmful than a documented guess.`;
+}
 function pushToolResult(history, tc, output, pruner, lifecycle, _scheduler, runtimeContextState = contextState, succeededOverride) {
     const succeeded = succeededOverride ?? isToolResultSuccess(output);
     const ageAware = config.contextOptimize ? ageAwareStateFor(history) : null;
@@ -203,6 +239,16 @@ function pushToolResult(history, tc, output, pruner, lifecycle, _scheduler, runt
 export async function runAgentCore(opts) {
     const { history, userInput, signal, onContextUpdate, hooks } = opts;
     const runtimeContextState = opts.contextState ?? contextState;
+    // ASK-01: 本 turn 已使用的 ask_human 次数(每次 tool call 后递增)。
+    // 预算超过时,工具结果尾部追加 ask budget 提示,不直接拒绝调用(更轻量,
+    // 也避免和现有 permission 系统的"拒绝"语义重叠)。
+    let askHumanCountThisTurn = 0;
+    // PROMPT-02: 解析 preCompletionChecklist 选项。undefined = 启用默认 middleware;
+    // false = opt-out(checklist 自身调试用);function = 调用方自定义。
+    const _checklistMiddleware = createPreCompletionChecklistMiddleware();
+    const preCompletionChecklistHandler = opts.preCompletionChecklist === false
+        ? null
+        : (opts.preCompletionChecklist ?? _checklistMiddleware.handler);
     const maxSteps = opts.maxSteps ?? config.maxSteps;
     // 中断还原:LLM 中途可能调 switch_mode 切了模式,abort 时连同模式一起还原回轮首。
     const savedMode = getAgentMode();
@@ -598,7 +644,30 @@ export async function runAgentCore(opts) {
                                 hooks.onToolResult?.(tc, output, null, null, 1); // 并行工具无 diff
                                 // Thrashing:history 里附 hint(UI 已用干净 output 渲染,避免屏幕噪声)
                                 const hint = recordAndHint(tc.name, tc.arguments, outcome.status === 'success');
-                                pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
+                                const { output: annotated, reflectionCategory } = appendRetryAnnotations(output, outcome.status, outcome.code, hint);
+                                // QUAL-01 trace 硬事件:反思指针注入计数(history 文本扫描会因 LLM 在
+                                // 正文里提一句 "[retry reflection]" 而误算,改用 core 接缝处显式 emit)。
+                                if (reflectionCategory !== null) {
+                                    emitTrace('retry_reflection', {
+                                        tool: tc.name,
+                                        code: outcome.code,
+                                        category: reflectionCategory,
+                                        attempt: outcome.attempts ?? 1,
+                                    }, tc.id ? { providerToolCallId: tc.id } : {});
+                                }
+                                // ASK-01: 计数 + 预算提示
+                                if (tc.name === 'ask_human' && outcome.status === 'success') {
+                                    askHumanCountThisTurn += 1;
+                                    // QUAL-01 trace 硬事件:ask_human 真实调用计数(取代 tool_call_end.name 推断)。
+                                    emitTrace('ask_human_call', {
+                                        tool: tc.name,
+                                        status: outcome.status,
+                                        perTurnCount: askHumanCountThisTurn,
+                                    }, tc.id ? { providerToolCallId: tc.id } : {});
+                                }
+                                const askBudget = askHumanBudgetAnnotation(askHumanCountThisTurn, outcome.status);
+                                const finalOutput = askBudget ? `${annotated}${askBudget}` : annotated;
+                                pushToolResult(history, tc, finalOutput, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
                             }
                             hooks.onToolDone?.();
                             i = j;
@@ -759,7 +828,31 @@ export async function runAgentCore(opts) {
                             hooks.onToolResult?.(tc, output, mutationParsed, diff.preWriteOld, diff.editStartLine);
                             // Thrashing:同上(history 附 hint,UI 干净)
                             const hint = recordAndHint(tc.name, tc.arguments, outcome.status === 'success');
-                            pushToolResult(history, tc, hint ? `${output}${hint}` : output, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
+                            // RETRY-01: 同 parallel 路径,在非成功状态追加反思指针。
+                            const { output: annotated, reflectionCategory } = appendRetryAnnotations(output, outcome.status, outcome.code, hint);
+                            // QUAL-01 trace 硬事件:反思指针注入计数(history 文本扫描会因 LLM 在
+                            // 正文里提一句 "[retry reflection]" 而误算,改用 core 接缝处显式 emit)。
+                            if (reflectionCategory !== null) {
+                                emitTrace('retry_reflection', {
+                                    tool: tc.name,
+                                    code: outcome.code,
+                                    category: reflectionCategory,
+                                    attempt: outcome.attempts ?? 1,
+                                }, tc.id ? { providerToolCallId: tc.id } : {});
+                            }
+                            // ASK-01: ask_human 计数 + 预算提示(同 parallel 路径)。
+                            if (tc.name === 'ask_human' && outcome.status === 'success') {
+                                askHumanCountThisTurn += 1;
+                                // QUAL-01 trace 硬事件:ask_human 真实调用计数(取代 tool_call_end.name 推断)。
+                                emitTrace('ask_human_call', {
+                                    tool: tc.name,
+                                    status: outcome.status,
+                                    perTurnCount: askHumanCountThisTurn,
+                                }, tc.id ? { providerToolCallId: tc.id } : {});
+                            }
+                            const askBudget = askHumanBudgetAnnotation(askHumanCountThisTurn, outcome.status);
+                            const finalOutput = askBudget ? `${annotated}${askBudget}` : annotated;
+                            pushToolResult(history, tc, finalOutput, relprune, lifecycle, scheduler, runtimeContextState, outcome.status === 'success');
                             const invalidatedFiles = [...new Set([
                                     ...(outcome.changedFiles ?? []),
                                     ...(outcome.staleFiles ?? []),
@@ -899,6 +992,41 @@ export async function runAgentCore(opts) {
                     }
                 }
                 else {
+                    // PROMPT-02: 硬关卡 — 收尾路径上,如果本 turn 有 mutation 且未通过
+                    // validation(autoValidate=false / 验证已 passed 但 LLM 又宣称完成),
+                    // 推一条 [checklist] user 消息,强制模型再走一轮显式确认。
+                    // 防死循环:checklist 已推过 2 次仍无新工具调用 → 放行(走原本的 push)。
+                    const finalMutationForChecklist = getCurrentTurnMutationState();
+                    const checklistCtx = {
+                        hadMutation: finalMutationForChecklist.version > 0,
+                        lastValidationStatus: (latestValidation?.status === 'failed' || latestValidation?.status === 'passed')
+                            ? latestValidation.status
+                            : 'none',
+                        mode: getAgentMode(),
+                        modelFamily: inferModelFamily(config.model),
+                    };
+                    const checklistRetryCount = history.__checklistStreak ?? 0;
+                    const shouldFireChecklist = preCompletionChecklistHandler !== null
+                        && preCompletionChecklistHandler(checklistCtx)
+                        && checklistRetryCount < 2;
+                    if (shouldFireChecklist) {
+                        history.push(candidate);
+                        history.push({
+                            role: 'user',
+                            content: _checklistMiddleware.buildUserMessage(checklistCtx.modelFamily),
+                        });
+                        history.__checklistStreak = checklistRetryCount + 1;
+                        // QUAL-01 trace 硬事件:PROMPT-02 触发计数(取代 history 文本扫描
+                        // [checklist] marker — LLM 在正文里提一句 "[checklist]" 也会被误算)。
+                        emitTrace('checklist_triggered', {
+                            streak: checklistRetryCount + 1,
+                            validationStatus: checklistCtx.lastValidationStatus,
+                            hadMutation: checklistCtx.hadMutation,
+                            modelFamily: checklistCtx.modelFamily ?? 'other',
+                        });
+                        // 重要: 不置 done,让主循环继续下一轮(模型被迫用工具或写出可验证声明)。
+                        continue;
+                    }
                     history.push(candidate);
                 }
                 const finalMutation = getCurrentTurnMutationState();
@@ -912,6 +1040,7 @@ export async function runAgentCore(opts) {
                     usage: turnUsage,
                     validation: latestValidation,
                     changedFiles: finalMutation.changedFiles.map((item) => item.path),
+                    history: history.slice(),
                 };
             }
             finally {
@@ -933,6 +1062,7 @@ export async function runAgentCore(opts) {
             usage: turnUsage,
             validation: latestValidation,
             changedFiles: finalMutation.changedFiles.map((item) => item.path),
+            history: history.slice(),
         };
     }
     finally {

package/dist/agent/index.js

@@ -50,10 +50,12 @@ function writeChangeOverview() {
     const changes = [...merged.values()];
     const added = changes.reduce((n, c) => n + c.added, 0);
     const removed = changes.reduce((n, c) => n + c.removed, 0);
-    layout.contentWrite(`  ${ui.dim}├─${ui.reset} ${ui.bold}${ui.green}◆${ui.reset} ${t('agent.changes')}  ${t('agent.files', { count: changes.length })}  ${ui.green}+${added}${ui.reset} ${ui.red}−${removed}${ui.reset}\n`);
+    layout.contentWrite(`  ${ui.bold}${ui.accent}●${ui.reset} ${t('agent.changes')}  ${t('agent.files', { count: changes.length })}  ${ui.green}+${added}${ui.reset} ${ui.red}−${removed}${ui.reset}\n`);
     for (const change of changes) {
-        layout.contentWrite(`  ${ui.dim}│   ${change.kind}${ui.reset}  ${change.path}  ${ui.green}+${change.added}${ui.reset} ${ui.red}−${change.removed}${ui.reset}\n`);
+        const kindLabel = change.kind === 'A' ? t('agent.changeAdded') : t('agent.changeModified');
+        layout.contentWrite(`  ${kindLabel}  ${change.path}  ${ui.green}+${change.added}${ui.reset} ${ui.red}−${change.removed}${ui.reset}\n`);
     }
+    layout.contentWrite('\n');
 }
 /** 取 userInput 的首行:字符串直接 split;多模态 parts 找首个 text part 再 split。 */
 function firstLineOf(ui) {
@@ -228,7 +230,7 @@ onContextUpdate) {
         },
         onMaxSteps: () => {
             flushToolBatch();
-            layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}${t('agent.maxSteps', { count: config.maxSteps })}${ui.reset}\n`);
+            layout.contentWrite(`  ${ui.accent}●${ui.reset} ${ui.yellow}${t('agent.maxSteps', { count: config.maxSteps })}${ui.reset}\n`);
         },
         onAbort: () => {
             spinner.stop();
@@ -252,14 +254,14 @@ onContextUpdate) {
             const detail = validation.status === 'skipped' && validation.skipReason
                 ? `${validation.status}: ${validation.skipReason}`
                 : validation.status;
-            const symbol = validation.status === 'passed' ? '◆' : validation.status === 'failed' ? '×' : '!';
-            layout.contentWrite(`  ${ui.dim}├─${ui.reset} ${color}${symbol}${ui.reset} ${t('agent.validationResult', { command, status: detail })}\n\n`);
+            const symbol = validation.status === 'passed' ? '●' : validation.status === 'failed' ? '×' : '!';
+            layout.contentWrite(`  ${color}${symbol}${ui.reset} ${t('agent.validationResult', { command, status: detail })}\n\n`);
         },
         onDone: (elapsedMs, usage) => {
             flushToolBatch();
             writeChangeOverview();
             const tok = formatTurnTokens(usage);
-            layout.contentWrite(`  ${ui.bold}${ui.green}◆${ui.reset} ${t('agent.complete')}  ${fmtElapsed(elapsedMs)}${tok}\n`);
+            layout.contentWrite(`  ${ui.bold}${ui.accent}●${ui.reset} ${t('agent.complete')}  ${fmtElapsed(elapsedMs)}${tok}\n`);
             // 内容区触底时，DECSTBM 增量滚屏可能只推进物理终端，未把 Worked 前已在
             // buffer 中的空行完整画出来；用户滚动/点击触发 repaint 后才“突然”出现。
             // 轮次收尾立即按 buffer 原子重画，使未满屏与触底滚屏的布局一致。

package/dist/agent/middleware/checklist.js

@@ -0,0 +1,59 @@
+// PROMPT-02: PreCompletionChecklistMiddleware.
+//
+// 在 agent 宣告完成(no tool calls + 有 candidate 正文)的那一刻,向 history
+// 推一条 user 消息,让模型再走一轮对 5 项 checklist 做显式确认 —— 这是
+// "硬关卡",与 PROMPT-01 的 4 阶段"软纪律"叠加。
+//
+// 关键约束:
+// - 纯函数(handler / buildUserMessage) → 易测、易 opt-out。
+// - 5 项 checklist 是稳定的字符串数组,fixture 可直接断言关键词。
+// - 复用 PROMPT-01 核心文本中的 "verification is a hard prerequisite" 锚点
+//   风格(不另起炉灶),但用单数第一人称直白的 checklist 措辞。
+// - 与 thrash-tracker 风格正交:trash 是 hint(LLM 仍可继续 retry),checklist
+//   是 gate(LLM 必须覆盖才能 done)。
+// - opt-out 显式:plan 模式 / 调用方传 `preCompletionChecklist: false`。
+/** 5 项 checklist 内容(稳定,fixture 直接断言)。措辞对齐 LangChain 实证。 */
+export const CHECKLIST_ITEMS = [
+    'Did I actually run a command/test/compile, or did I just re-read my own code?',
+    'Does the output match the original spec, not "what I thought I wrote"?',
+    'Did I exercise the boundary I claim to have covered (not just the happy path)?',
+    'Does the existing test suite still pass?',
+    'If I cannot verify, did I tell the user explicitly instead of pretending to be done?',
+];
+/**
+ * 拼出 checklist user 消息。固定 5 项 + 硬规则;以 `[checklist]` 起头
+ * 便于 LLM 识别为强制二次确认(也便于 eval fixture 关键字定位)。
+ */
+export function buildChecklistUserMessage(modelFamily) {
+    const opener = modelFamily === 'anthropic'
+        ? 'Verification gate — you have not actually run a command that exercises the change against the spec. Before declaring done, answer each item below explicitly:'
+        : modelFamily === 'openai'
+            ? 'MANDATORY pre-completion checklist. You MUST address every item below before your final reply:'
+            : 'Pre-completion checklist — answer each item explicitly before declaring done:';
+    const items = CHECKLIST_ITEMS.map((item, i) => `${i + 1}. ${item}`).join('\n');
+    return `[checklist] ${opener}
+
+${items}
+
+Hard rule: "I read the code and it looks right" is not a completion signal. If you cannot run a verification, say so explicitly in your final reply. Do not paraphrase this checklist back as the answer — provide the actual evidence (which command, which output, which spec line it satisfied).
+
+Bonus (ASK-01): Before declaring done, also answer: am I guessing any fact the user did not state? If yes, surface the guess to the user in your final reply or call \`ask_human\` (within the per-turn budget) — never silently guess on a non-reversible choice.`;
+}
+/** 默认 trigger 条件:有 mutation + 没工具调用 + 验证未通过或没跑过 + 非 plan。 */
+export const defaultChecklistHandler = (ctx) => {
+    if (ctx.mode === 'plan')
+        return false;
+    if (!ctx.hadMutation)
+        return false;
+    // 已经通过验证:放行,不再二次确认(避免噪声)。
+    if (ctx.lastValidationStatus === 'passed')
+        return false;
+    return true;
+};
+export function createPreCompletionChecklistMiddleware() {
+    return {
+        handler: defaultChecklistHandler,
+        buildUserMessage: buildChecklistUserMessage,
+        items: CHECKLIST_ITEMS,
+    };
+}

package/dist/agent/retry-classifier.js

@@ -0,0 +1,64 @@
+// RETRY-01: 错误反思分类器。
+//
+// 在 tools/retry.ts 之上叠加一层"反思"语义:把每个 ToolOutcomeCode 映射到
+// 一个 ErrorCategory,供 (a) PROMPT 反思 prompt 注入、(b) QUAL-01 trace 指标。
+//
+// 设计要点:
+// - 纯映射函数,无副作用 → 易测,易扩展(新 code → 改一处)。
+// - 6 类对齐路线图 L163:`TRANSIENT_RATE_LIMIT` / `TRANSIENT_TIMEOUT` /
+//   `INVALID_ARGUMENTS` / `PERMISSION_DENIED` / `CONFLICT` / `UNKNOWN_FAILURE`。
+// - 提供"反思指针"模板(reflectionHint),与 PROMPT-01 hard rule
+//   / PROMPT-02 checklist 共用同一套"先想清楚再动"语言,避免新造话。
+// - 不**决策**重试与否(`shouldRetry` 在 tools/retry.ts 已经稳定;本次不动),
+//   只**注解**每个错误"该反思什么"。
+/** code → category 的稳定映射。fixture 直接断言(避免漏改)。 */
+const CODE_TO_CATEGORY = {
+    OK: 'UNKNOWN_FAILURE', // OK 不该走到这里;归 UNKNOWN 是为了编译期不漏。
+    // rate-limit / timeout / network
+    TIMEOUT: 'TRANSIENT_TIMEOUT',
+    HTTP_ERROR: 'TRANSIENT_RATE_LIMIT', // 4xx/5xx 中除 408/429 之外的 5xx 视为 rate-limit 语义
+    NETWORK_ERROR: 'TRANSIENT_TIMEOUT', // 网络层错(ECONNRESET 等)→ 与 timeout 同类反思
+    // 参数 / schema(模型自己改,不是 retry 自己改)
+    INVALID_JSON: 'INVALID_ARGUMENTS',
+    INVALID_ARGUMENTS: 'INVALID_ARGUMENTS',
+    INVALID_TOOL_SCHEMA: 'INVALID_ARGUMENTS',
+    UNKNOWN_TOOL: 'INVALID_ARGUMENTS', // 调用了不存在的工具 → 模型改 tool name
+    // 权限 / 沙箱 / 模式(永久拒绝)
+    SANDBOX_DENIED: 'PERMISSION_DENIED',
+    PERMISSION_DENIED: 'PERMISSION_DENIED',
+    TOOL_DISABLED: 'PERMISSION_DENIED',
+    MODE_DENIED: 'PERMISSION_DENIED',
+    ABORTED: 'PERMISSION_DENIED', // 用户主动 abort,与 permission 同类(无 retry 价值)
+    // 冲突 / 写失败(retry 之前必须重新读)
+    EDIT_CONFLICT: 'CONFLICT',
+    CHANGE_CONFLICT: 'CONFLICT',
+    PATCH_INVALID: 'CONFLICT',
+    POSTCONDITION_FAILED: 'CONFLICT',
+    PROCESS_FAILED: 'CONFLICT',
+    // 兜底
+    EXECUTION_ERROR: 'UNKNOWN_FAILURE',
+    MCP_ERROR: 'UNKNOWN_FAILURE',
+};
+export function classifyError(code) {
+    return CODE_TO_CATEGORY[code];
+}
+/** 反思指针:每类错误给 LLM 一句"反思什么"的话。 */
+const REFLECTION_HINTS = {
+    TRANSIENT_RATE_LIMIT: 'The remote is throttling or returned 5xx. Re-running the same call with identical arguments is unlikely to help — wait, downgrade call frequency, or reduce request size; do not retry the same args in tight loop.',
+    TRANSIENT_TIMEOUT: 'A network or process timeout occurred. Re-running the same call may help once, but if it fails again with identical args, the path/host/argument is wrong; switch tool, reduce scope, or ask the user.',
+    INVALID_ARGUMENTS: 'The tool rejected the call shape (JSON / schema / unknown tool). Read the tool description again and fix the arguments yourself; do not resend the same call and do not retry automatically — only the model can fix argument shape.',
+    PERMISSION_DENIED: 'The call was denied (sandbox / permission / disabled / mode). Retry will not help; surface the constraint to the user and ask for guidance or a permission grant.',
+    CONFLICT: 'A write/patch conflicted with the on-disk state. Do not resend the same args; re-read the file or change target, then re-derive the diff. If the conflict is structural, the plan itself is wrong — go back to the spec.',
+    UNKNOWN_FAILURE: 'An unclassified error occurred. Do not retry blindly; capture the message, re-read the tool description, and decide whether the same call with a smaller scope or a different tool is appropriate. If unsure, ask the user.',
+};
+export function reflectionHint(category) {
+    return REFLECTION_HINTS[category];
+}
+/**
+ * 一站式:对 ToolOutcome 给出"反思 category + 反思 hint"。
+ * 调用方一般是 tools/retry.ts 的 onRetry hook,把 hint 注入 retry 提示尾部。
+ */
+export function reflectOn(code) {
+    const category = classifyError(code);
+    return { category, hint: reflectionHint(category) };
+}

package/dist/agent/work-discipline.js

@@ -0,0 +1,108 @@
+// PROMPT-01: Build-and-Self-Verify working discipline.
+//
+// 把"完成必须验证"作为 system prompt 的一等公民,而不是事后选项。注入一段
+// 4 阶段纪律(Plan & Discover → Build → Verify → Fix),并提供 per-model
+// 措辞(anthropic / openai / qwen)让 base model 拿到最适合自己的表述。
+//
+// 关键约束:
+// - 纯函数,无副作用,无 config 依赖 → 不踩 TDZ,易测,易回滚。
+// - 段标题在 buildMocodeCorePrompt 之外,不会被 `## Project context` 索引
+//   切片误伤;且 buildBasePrompt 注入位置在 ## Workflow 之前,确保 LLM
+//   先看到纪律再看工具/平台细节。
+// - per-model 措辞是"轻量"差异:3 个家族共享 4 阶段结构,只在首句/标签
+//   上贴近该家族的指令遵从习惯;真正的 prompt 反演化交给 AHE。
+// - 语种统一英文:4 份都用同一份核心纪律文本,避免多语种漂移;用户语言
+//   偏好由现有 i18n 段(assistant.languageInstruction)负责。
+/**
+ * 从 config.model 字符串里嗅探 model family。匹配规则尽量宽松,够用即可。
+ * 未来 AHE 闭环后可以换成 config.modelFamily 字段。
+ */
+export function inferModelFamily(model) {
+    if (!model)
+        return 'other';
+    const m = model.toLowerCase();
+    if (m.includes('claude') || m.includes('anthropic'))
+        return 'anthropic';
+    if (m.includes('gpt') || m.includes('o1') || m.includes('o3') || m.includes('openai'))
+        return 'openai';
+    if (m.includes('qwen') || m.includes('qwq') || m.includes('tongyi'))
+        return 'qwen';
+    return 'other';
+}
+/**
+ * 4 阶段核心纪律(英文)。4 个 model family 共用此文本,只在首句与标题
+ * 标签上做轻量变体。长度 ~380 词,确保不显著抬升 token 预算。
+ */
+const CORE_SECTION = `## Working discipline — coding tasks (Build-and-Self-Verify)
+
+Treat "verification" as a first-class part of the task, not an afterthought. Every coding task runs through four sequential phases; skipping or merging phases is a failure mode.
+
+### Phase 1 — Plan & Discover
+- Restate the goal in one sentence; identify the acceptance signal (test name, command output, file presence, behavior change).
+- Read the relevant code BEFORE writing anything; record assumptions you cannot verify (write them down, do not silently assume).
+- If the spec is ambiguous, surface the ambiguity to the user via \`ask_human\` before implementing — do not guess on irreversible choices (deletions, public API changes, schema/permission boundaries).
+
+### Phase 2 — Build
+- Make the smallest change that satisfies the spec. Do not bundle unrelated refactors.
+- If the project has tests, your change is incomplete without a test for the new/changed behavior. "Should" clauses in the goal are obligations, not aspirations.
+- After every mutation, re-read the relevant region (snapshot drift is real — your memory of the file is stale after the previous edit).
+
+### Phase 3 — Verify
+- Run a real, executable verification: typecheck, the project's test command, a focused command that exercises the change, or a smoke script. Read the full output, not just the last line.
+- Compare the result to the SPEC, not to your own diff. A diff that "looks right" against itself is not evidence.
+- If the project has no test infra you can use, build the smallest possible reproducer (a script, a focused command) that exercises the change. "I read the code and it looks correct" is not verification.
+
+### Phase 4 — Fix
+- Any failure → go back to the spec, not to the diff. Re-derive what the spec requires; do not "tweak" the implementation to silence the failing test.
+- After a fix, re-run Phase 3 end-to-end. Do not declare done on a single passing run after multiple failed ones unless you understand and can name the root cause of every previous failure.
+- Cap blind retries: after three identical failed attempts on the same tool with the same arguments, change the approach (different tool, different invariant, or \`ask_human\`) instead of retrying.
+
+**Hard rule (non-negotiable):** "I read the code and it looks right" is not a completion signal. A task is complete only when an executable verification against the spec has actually run, its full output has been read, and the result matches the spec. Report this evidence explicitly in your final reply (which command, which output, which spec line it satisfied).`;
+/**
+ * 把核心段适配到指定 model family:只改首行(语序 / 强动词)与段标题
+ * 末尾的 [model: X] 标签。Phase 内容保持原样,4 份共享同一份结构化文本。
+ */
+function adapt(model, opener) {
+    return CORE_SECTION
+        .replace('## Working discipline — coding tasks (Build-and-Self-Verify)', `## Working discipline — coding tasks (Build-and-Self-Verify) [model: ${model}]`)
+        .replace('Treat "verification" as a first-class part of the task, not an afterthought.', opener);
+}
+/** ASK-01: 卡点白名单段。PROMPT-01 4 阶段纪律之后追加,告诉模型在哪些
+ * 边界情形应当优先调 `ask_human`,而不是猜测。语种统一英文(与 PROMPT-01
+ * 保持一致,避免多语种漂移);5 个固定条目,与 checklist 第 6 项耦合。
+ */
+const ASK_WHITELIST_SECTION = `## When to ask instead of guess
+
+The following situations are not guessable. When you encounter any of them, call \`ask_human\` BEFORE writing code; do not silently pick one option and proceed.
+
+1. **Cross-package impact** — the change touches public APIs, exports, or interfaces of other packages/modules; the user must confirm the blast radius.
+2. **Naming conventions** — the project has no obvious style for this artifact (e.g. new file in a folder with no precedent); naming is cheap to fix and expensive to mass-rename later.
+3. **Keep or remove old API** — the change deprecates, renames, or removes a function/type; the user must decide.
+4. **Test expectations** — the spec says "should work" or "should handle" but does not pin down the input/output contract; ask for a concrete example or assertion.
+5. **Implicit success criteria** — the user described intent but not the verification signal (which command, which output, which line of the spec). Without this, you cannot run Phase 3 honestly.
+
+Budget: at most 2 \`ask_human\` calls per turn. If you would exceed the budget, prefer the safer default (e.g. "preserve old behavior" / "add a test, do not change behavior") and explicitly disclose the choice in your final reply — do not silently guess without disclosure. The disclosure is what the checklist item 6 is about.`;
+/**
+ * 拼出纪律段 + ASK-01 卡点白名单。返回完整段(两段用 \`\\n\\n\` 隔开);
+ * 工厂之前只返回纪律段,ASK-01 落地后变成纪律 + 白名单两段;
+ * ASK-01 段是固定英文,不参与 per-model 适配(避免 4 份变体维护成本)。
+ */
+export function buildWorkDisciplineSection(modelFamily) {
+    let section;
+    switch (modelFamily) {
+        case 'anthropic':
+            section = adapt('anthropic', 'Verification is a hard prerequisite for completion, not a courtesy.');
+            break;
+        case 'openai':
+            section = adapt('openai', 'Every coding task MUST complete these four phases in order. Skipping or merging phases is treated as a failure.');
+            break;
+        case 'qwen':
+            section = adapt('qwen', 'Verification is a hard prerequisite for completion; "I wrote the code" is not evidence the code works.');
+            break;
+        case 'other':
+        case undefined:
+        default:
+            section = CORE_SECTION;
+    }
+    return `${section}\n\n${ASK_WHITELIST_SECTION}`;
+}

package/dist/config/index.js

@@ -6,6 +6,7 @@ import { loadSnapshot } from '../project-snapshot/index.js';
 import { buildProjectSkillSection } from '../project-skill/index.js';
 import { getSandboxRoot } from '../sandbox/root.js';
 import { getCurrentSessionId } from '../session/state.js';
+import { buildWorkDisciplineSection, inferModelFamily } from '../agent/work-discipline.js';
 import { detectLanguage, setLanguage, t, } from '../i18n/index.js';
 /**
  * 按优先级加载配置文件并回填 process.env:
@@ -209,6 +210,8 @@ ${planLine}
 
 ${PLATFORM_NOTE}
 
+${buildWorkDisciplineSection(inferModelFamily(config.model))}
+
 ## Tool details
 ### Token-efficient execution
 - First check whether the answer is already in this conversation or a previous tool result. If yes, answer directly; do not re-run tools "to be safe".
@@ -228,7 +231,7 @@ ${PLATFORM_NOTE}
 
 ## Tool rules
 - Precise path/symbol → go directly to \`read_file\` or \`codegraph node\`; use \`glob\`/\`grep\` only for discovery.
-- Before editing, read the exact target region and copy both its artifact \`hash\` and verbatim text. Use \`edit_file\` with \`expected_hash\` for unique local replacements, and \`write_file\` with the latest hash for replacement (or null only for creation).
+- Before editing, read the exact target region and copy both its artifact \`hash\` and verbatim text. Use \`edit_file\` with \`expected_hash\` for unique local replacements, and \`write_file\` with the latest hash for replacement (or null only for creation).
 - Local edits require an exact unique match; use \`write_file\` for new/full files.
 - Use \`glob\`/\`grep\` for discovery and \`run_command\` for execution or verification, not file existence checks. State intent before side effects.
 - Call \`ask_human\` only when a real user decision is required; otherwise decide and proceed.
@@ -251,7 +254,7 @@ ${PLATFORM_NOTE}
 - Operate only within authorized scope; when unsure, ask — don't guess.
 
 ## Project context (dynamic reference)
-${buildSnapshotSection()}${config.projectSkillEnabled ? buildProjectSkillSection() : ''}${memorySection}${buildNotepadSection(sessionId)}
+${buildSnapshotSection()}${config.projectSkillEnabled ? buildProjectSkillSection() : ''}${memorySection}${buildNotepadSection(sessionId)}
 
 ## Session Notepad — working notes file
 ${sessionId

package/dist/foo.js

@@ -0,0 +1,28 @@
+/**
+ * Parse a semver string into its numeric major/minor/patch triple.
+ *
+ * Accepts the two shapes the caller asked about:
+ *   - "1.2.3"
+ *   - "v2.0.0-rc.1"
+ *
+ * Prerelease / build metadata are accepted after the patch number, but only
+ * the three numeric core components are returned. Anything that does not
+ * match `^v?MAJOR.MINOR.PATCH(-prerelease)?(+build)?` raises an Error whose
+ * message contains "invalid semver".
+ */
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+export function parseSemver(input) {
+    if (typeof input !== 'string') {
+        throw new Error(`invalid semver: not a string: ${String(input)}`);
+    }
+    const m = SEMVER_RE.exec(input);
+    if (!m) {
+        throw new Error(`invalid semver: ${JSON.stringify(input)}`);
+    }
+    // Numeric groups are guaranteed by the \d+ pattern; Number() won't produce NaN.
+    return {
+        major: Number(m[1]),
+        minor: Number(m[2]),
+        patch: Number(m[3]),
+    };
+}

package/dist/foo.test.js

@@ -0,0 +1,12 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { parseSemver } from './foo.js';
+test('parseSemver parses plain x.y.z', () => {
+    assert.deepEqual(parseSemver('1.2.3'), { major: 1, minor: 2, patch: 3 });
+});
+test('parseSemver parses v-prefixed prerelease', () => {
+    assert.deepEqual(parseSemver('v2.0.0-rc.1'), { major: 2, minor: 0, patch: 0 });
+});
+test('parseSemver throws "invalid semver" on garbage input', () => {
+    assert.throws(() => parseSemver('not-a-version'), /invalid semver/);
+});

package/dist/i18n/index.js

@@ -174,6 +174,8 @@ const zhCN = {
     'agent.toolsFailed': '探索失败',
     'agent.changes': '文件变更',
     'agent.files': '{count} 个文件',
+    'agent.changeAdded': '  新增',
+    'agent.changeModified': '  修改',
     'agent.complete': '完成',
     'toolSummary.lines': '{count} 行',
     'toolSummary.files': '{count} 个文件',
@@ -406,6 +408,8 @@ const en = {
     'agent.toolsFailed': 'Exploration failed',
     'agent.changes': 'Changes',
     'agent.files': '{count} file(s)',
+    'agent.changeAdded': '  Added',
+    'agent.changeModified': '  Modified',
     'agent.complete': 'Complete',
     'toolSummary.lines': '{count} lines',
     'toolSummary.files': '{count} files',

package/dist/repl/index.js

@@ -2055,7 +2055,7 @@ export async function startRepl(initialHistory, sessionId, updateNotice = null,
                     const initPrompt = `请直接初始化或优化当前项目的 Project Skill，并完成写入。
 
 要求：
-1. 直接由你完成，禁止调用 sub-agent 工具或派生任何子 agent。
+1. 直接由你完成，禁止调用 sub-agent 工具或派生任何子 agent。
 2. 优先利用系统提示中已有的 Project Snapshot 和 Project Skill；不要重复扫描其中已有的目录、依赖、命令和模块清单。
 3. 最多进行 1 次 codegraph 探索；只有缺少关键依据时，才额外进行少量定点 read_file/grep。禁止全仓 glob 和逐文件扫描。
 4. Skill 只记录 Snapshot 无法提供的 WHY/HOW/GOTCHAS/CONVENTIONS：设计取舍、关键调用链、非直觉边界、项目约定和可操作坑点。使用具体路径和例子，删除重复或过时内容。

package/dist/session/scheduler.js

@@ -39,7 +39,7 @@ export function createBudgetScheduler(state = contextState) {
             for (const a of actions) {
                 if (a.kind === 'warn') {
                     // system 超:写一行提示(配置漂移应由用户处理,不是调度器压)
-                    layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}调度器警告 [${a.layer}] ${a.reason}${ui.reset}\n`);
+                    layout.contentWrite(`  ${ui.accent}●${ui.reset} ${ui.yellow}调度器警告 [${a.layer}] ${a.reason}${ui.reset}\n`);
                 }
                 else if (a.kind === 'compact_history') {
                     // 路由到 maybeCompact；把结构重建信号传回 core，使 lifecycle 按新 index 恢复。

package/dist/session/trace-metrics.js

@@ -1,5 +1,88 @@
 import { readFileSync } from 'node:fs';
-export function reduceTraceMetrics(events) {
+/** 把 history 中所有 user/tool/assistant 消息的文本/参数汇总到一个大字符串,便于
+ * 用单一正则扫描多个 marker。比逐条消息 join 更稳:LLM 流式 contentPart 数组
+ * 与多模态混合时,joinStringField 内部把每个 part 展平成字符串。 */
+function joinHistoryForMarkerScan(history) {
+    if (!history)
+        return '';
+    const parts = [];
+    for (const message of history) {
+        if (typeof message.content === 'string') {
+            parts.push(message.content);
+        }
+        else if (Array.isArray(message.content)) {
+            for (const part of message.content) {
+                if (typeof part === 'string')
+                    parts.push(part);
+                else if (part && typeof part === 'object' && 'text' in part && typeof part.text === 'string') {
+                    parts.push(part.text);
+                }
+            }
+        }
+        if ('tool_call_id' in message && typeof message.tool_call_id === 'string') {
+            parts.push(message.tool_call_id);
+        }
+    }
+    return parts.join('\n');
+}
+/** QUAL-01 质量维度。
+ *
+ * 优先用硬事件(retry_reflection / checklist_triggered / ask_human_call),
+ * 这是 core.ts 在接缝处显式 emit 的,可信度高。
+ * 如果 events 里没有对应硬事件(老 trace / 旧 fixture 走 history 文本回放),fallback
+ * 到 history 文本扫描 + tool_call_end(name === 'ask_human', status === 'success')。
+ *
+ * - `retry_reflection` → 反思重试注入次数(RETRY-01)
+ * - `checklist_triggered` → PROMPT-02 触发次数
+ * - `ask_human_call` (status === 'success') → ASK-01 触发次数
+ *
+ * 三类都给出 fallback 0,确保报告维度永远是 number,不会被 NaN 污染。 */
+function reduceQualityDimensions(events, history) {
+    // 1. 硬事件计数(优先级最高)。
+    let reflectionRounds = 0;
+    let checklistTriggered = 0;
+    let askHumanCount = 0;
+    let hasHardReflection = false;
+    let hasHardChecklist = false;
+    let hasHardAskHuman = false;
+    for (const event of events) {
+        if (event.type === 'retry_reflection') {
+            reflectionRounds += 1;
+            hasHardReflection = true;
+        }
+        else if (event.type === 'checklist_triggered') {
+            checklistTriggered += 1;
+            hasHardChecklist = true;
+        }
+        else if (event.type === 'ask_human_call' && event.data.status === 'success') {
+            askHumanCount += 1;
+            hasHardAskHuman = true;
+        }
+    }
+    // 2. fallback: 历史事件没有硬信号时,从 history 文本 + tool_call_end 推断。
+    //    保留旧 fixture / 回放 JSONL 的兼容能力。
+    if (!hasHardReflection || !hasHardChecklist || !hasHardAskHuman) {
+        if (!hasHardReflection) {
+            const historyText = joinHistoryForMarkerScan(history);
+            reflectionRounds += (historyText.match(/\[retry reflection:/g) ?? []).length;
+        }
+        if (!hasHardChecklist) {
+            const historyText = joinHistoryForMarkerScan(history);
+            checklistTriggered += (historyText.match(/\[checklist\]/g) ?? []).length;
+        }
+        if (!hasHardAskHuman) {
+            for (const event of events) {
+                if (event.type !== 'tool_call_end')
+                    continue;
+                if (event.data.name === 'ask_human' && event.data.status === 'success') {
+                    askHumanCount += 1;
+                }
+            }
+        }
+    }
+    return { reflectionRounds, askHumanCount, checklistTriggered };
+}
+export function reduceTraceMetrics(events, history) {
     const ends = events.filter((event) => event.type === 'tool_call_end');
     let recovered = false;
     let hadFailure = false;
@@ -32,6 +115,7 @@ export function reduceTraceMetrics(events) {
     const modelRetries = events.filter((event) => event.type === 'model_retry').length;
     const firstValidation = events.find((event) => event.type === 'validation_end');
     const turnEnd = [...events].reverse().find((event) => event.type === 'turn_end');
+    const quality = reduceQualityDimensions(events, history);
     return {
         toolCalls: events.filter((event) => event.type === 'tool_call_start').length,
         toolFailures: ends.length - successes,
@@ -43,6 +127,7 @@ export function reduceTraceMetrics(events) {
         tokens: hasTokens ? tokens : null,
         durationMs: Number(turnEnd?.data.durationMs ?? 0),
         firstValidationPassed: firstValidation?.data.status === 'passed',
+        ...quality,
     };
 }
 /** Reads event JSONL; malformed/legacy summary lines are ignored. */

package/dist/tools/builtins/ask-human.js

@@ -6,7 +6,7 @@ function optionToChoice(o) {
     if (o === null || o === undefined)
         return { label: '' };
     if (typeof o === 'string')
-        return { label: o };
+        return { label: o.trim() };
     if (typeof o === 'number' || typeof o === 'boolean')
         return { label: String(o) };
     if (typeof o === 'object') {
@@ -89,14 +89,31 @@ export function coerceOptions(raw) {
     }
     return [];
 }
+/**
+ * 在通用 JSON Schema 校验前统一模型的常见错参。
+ * - 兼容历史字符串选项和 description/detail 等别名；
+ * - 丢弃 `{}` 等无可读内容的项；
+ * - 少于两个有效选项时统一为 `options: []`，明确表示自由文本面板。
+ */
+export function normalizeAskHumanArguments(args) {
+    const options = coerceOptions(args.options);
+    if (options.length < 2) {
+        args.options = [];
+        return;
+    }
+    args.options = options.slice(0, 4).map((option) => ({
+        label: option.label,
+        ...(option.detail ? { description: option.detail } : {}),
+    }));
+}
 // ---------- ask_human ----------
 export const askHumanTool = {
     name: 'ask_human',
     description: [
-        'Present the user with a menu of choices to pick from.',
-        ' DEFAULT: pass 2-4 concrete options via `options`; each is a string, or { label, description } when the choice has a non-obvious tradeoff.',
-        ' STRICT: object form requires a non-empty `label` — never emit {} or omit label (renders as a literal "{}" menu item). Only `label` and `description` are recognized — no extra fields.',
-        ' FREE-TEXT (omit `options`): only when the answer truly cannot be reduced to a few choices (e.g. "paste the error message").',
+        'Ask the user a question and wait for their response.',
+        ' CHOICES: pass 2-4 concrete options via `options`, each as { label, description? }.',
+        ' FREE-TEXT: pass `options: []` when the answer cannot be reduced to choices (e.g. "paste the error message").',
+        ' Every non-empty option requires a non-empty `label`; never emit [{}], omit label, or omit `options`.',
         ' DO NOT call when the task is clear and you can pick a sensible default.',
     ].join(' '),
     parameters: {
@@ -104,39 +121,39 @@ export const askHumanTool = {
         properties: {
             question: {
                 type: 'string',
+                minLength: 1,
                 description: 'The question to ask the user; keep it concise (shown as the panel title)',
             },
             options: {
                 type: 'array',
+                minItems: 0,
+                maxItems: 4,
                 items: {
-                    anyOf: [
-                        { type: 'string' },
-                        {
-                            type: 'object',
-                            properties: {
-                                label: {
-                                    type: 'string',
-                                    minLength: 1,
-                                    description: 'Short option title (1-5 words), shown as the choice itself.',
-                                },
-                                description: {
-                                    type: 'string',
-                                    description: 'What picking this option means or implies; explain the tradeoff when the label alone leaves the user unsure.',
-                                },
-                            },
-                            required: ['label'],
+                    type: 'object',
+                    properties: {
+                        label: {
+                            type: 'string',
+                            minLength: 1,
+                            description: 'Short option title (1-5 words), shown as the choice itself.',
+                        },
+                        description: {
+                            type: 'string',
+                            description: 'What picking this option means or implies; explain the tradeoff when the label alone leaves the user unsure.',
                         },
-                    ],
+                    },
+                    required: ['label'],
+                    additionalProperties: false,
                 },
-                description: '2-4 concrete choices. Each is a plain string, or { label, description } when the tradeoff is non-obvious. Required in most cases; omit only for free-form input.',
+                description: 'Pass [] for free-text input, or 2-4 concrete choices with non-empty labels.',
             },
             context: {
                 type: 'string',
                 description: 'Background explanation shown under the title; may be multiline.',
             },
         },
-        required: ['question'],
+        required: ['question', 'options'],
     },
+    normalizeArguments: normalizeAskHumanArguments,
     async execute(args) {
         const question = String(args.question ?? '');
         const options = coerceOptions(args.options);

package/dist/tools/retry.js

@@ -1,3 +1,4 @@
+import { reflectOn } from '../agent/retry-classifier.js';
 export const TOOL_RETRY_MAX_ATTEMPTS = 3;
 export const TOOL_RETRY_BASE_MS = 250;
 export const TOOL_RETRY_MAX_MS = 1_000;
@@ -68,11 +69,13 @@ function sleep(ms, signal) {
     });
 }
 /** Retry safe/idempotent transient outcomes; each execute call owns one complete lock attempt. */
-export async function executeWithToolRetry(capabilities, fingerprint, signal, execute, onRetry) {
+export async function executeWithToolRetry(capabilities, fingerprint, signal, execute, onRetry, onFailedAttempt) {
     const startedAt = Date.now();
     let retryDelayMs = 0;
+    let lastOutcome = null;
     for (let attempt = 1; attempt <= TOOL_RETRY_MAX_ATTEMPTS; attempt++) {
         const outcome = await execute(attempt);
+        lastOutcome = outcome;
         const elapsed = Date.now() - startedAt;
         const waitMs = backoff(attempt);
         const canRetry = attempt < TOOL_RETRY_MAX_ATTEMPTS &&
@@ -81,6 +84,25 @@ export async function executeWithToolRetry(capabilities, fingerprint, signal, ex
             !signal?.aborted &&
             reserveFingerprintRetry(fingerprint, Date.now());
         if (!canRetry) {
+            // RETRY-02 接缝:所有 attempt 用尽时,如果调用方启用了 onFailedAttempt,
+            // 通知一次(用于 history 裁剪 / 等)。只在**真**失败(not success)时通知,
+            // success 路径不需要裁剪任何东西。
+            if (onFailedAttempt && outcome.status !== 'success') {
+                try {
+                    const reflection = reflectOn(outcome.code);
+                    onFailedAttempt({
+                        fingerprint,
+                        status: outcome.status,
+                        code: outcome.code,
+                        category: reflection.category,
+                        attempts: attempt,
+                        reflectionHint: reflection.hint,
+                    });
+                }
+                catch {
+                    // 钩子失败不影响主流程。
+                }
+            }
             return {
                 ...outcome,
                 durationMs: elapsed,
@@ -89,7 +111,15 @@ export async function executeWithToolRetry(capabilities, fingerprint, signal, ex
             };
         }
         try {
-            onRetry?.({ attempt, nextAttempt: attempt + 1, waitMs, code: outcome.code });
+            const reflection = reflectOn(outcome.code);
+            onRetry?.({
+                attempt,
+                nextAttempt: attempt + 1,
+                waitMs,
+                code: outcome.code,
+                category: reflection.category,
+                reflectionHint: reflection.hint,
+            });
         }
         catch {
             // Retry telemetry is best-effort and must never change tool execution.
@@ -97,6 +127,8 @@ export async function executeWithToolRetry(capabilities, fingerprint, signal, ex
         await sleep(waitMs, signal);
         retryDelayMs += waitMs;
     }
+    // 不可达路径:循环要么 return,要么最后一次 attempt 也 shouldRetry=false(走 return)。
+    // 留 throw 是为了编译期穷尽性检查(TypeScript 期望函数末尾 return)。
     throw new Error('unreachable tool retry state');
 }
 /** Test/session reset seam; production never needs to clear the bounded TTL map. */

package/dist/tools/validation.js

@@ -53,7 +53,7 @@ function formatErrors(errors) {
         return `${location} ${error.message ?? error.keyword}`;
     }).join('; ');
 }
-/** Validate without coercing, defaulting, removing, or otherwise mutating model arguments. */
+/** Validate after tool-local normalization; AJV itself never coerces or mutates arguments. */
 export function validateToolArguments(tool, args) {
     if (!args || typeof args !== 'object' || Array.isArray(args)) {
         return {
@@ -62,6 +62,16 @@ export function validateToolArguments(tool, args) {
             message: '参数根节点必须是 JSON object',
         };
     }
+    try {
+        tool.normalizeArguments?.(args);
+    }
+    catch (error) {
+        return {
+            valid: false,
+            code: 'INVALID_ARGUMENTS',
+            message: `参数规范化失败: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
     const compiled = compile(tool.parameters);
     if (!compiled.valid) {
         return {

package/dist/ui/batch.js

@@ -93,16 +93,19 @@ function buildSummaryLine(record, live = false) {
     for (const [n, c] of counts)
         parts.push(`${n} ${c}`);
     const completed = entries.filter((e) => e.resultSummary || e.diffBlock || e.failed).length;
-    const failed = entries.some((e) => e.failed);
+    const failedCount = entries.filter((e) => e.failed).length;
     // 工具本身完成就立即显示完成态，不等待整轮正文流完/onDone。
+    // 单项失败不代表整批失败：执行中优先展示进度；完成后区分部分失败与全部失败。
     const finished = completed >= entries.length;
-    const symbol = failed ? '×' : finished ? '◆' : '◇';
-    const color = failed ? ui.red : finished ? ui.green : ui.accent;
-    const label = failed
-        ? t('agent.toolsFailed')
-        : finished
-            ? t('agent.toolsComplete')
-            : t('agent.toolsRunning');
+    const allFailed = finished && failedCount === entries.length;
+    const partiallyFailed = finished && failedCount > 0 && !allFailed;
+    const symbol = !finished ? '◇' : allFailed ? '×' : partiallyFailed ? '!' : '●';
+    const color = !finished ? ui.accent : allFailed ? ui.red : partiallyFailed ? ui.yellow : ui.green;
+    const label = !finished
+        ? t('agent.toolsRunning')
+        : allFailed
+            ? t('agent.toolsFailed')
+            : t('agent.toolsComplete');
     const progress = live && !finished ? `  ${completed}/${entries.length}` : `  ${entries.length}`;
     const elapsedMs = record.finishedAt ? record.finishedAt - record.startedAt : 0;
     const elapsed = record.finishedAt

package/dist/ui/layout.js

@@ -28,7 +28,7 @@ let turnStart = null; // RUNNING 态起点(Date.now());INPUT 态为 null。compo
 let turnTimer = null; // 走时刷新计时器(独立于 spinner):流式期间 spinner 停转,由它续刷状态行。
 // 运行态状态行 chip 心跳帧(♥/♡ 明灭)。turnTimer 每 tick 推进一帧,让状态行前导符在 agent
 // 运行时跳动——agent 的 spinner 走内容区续写位(paintLiveAtCursor),不调 setStatus,
-// 故状态行 chip 靠 turnTimer 独立驱动。INPUT 态 runningFrame=-1,composeStatus 退回静态 ◆。
+// 故状态行 chip 靠 turnTimer 独立驱动。INPUT 态 runningFrame=-1,composeStatus 退回静态 ●。
 const RUNNING_FRAMES = ['♥', '♡'];
 let runningFrame = -1;
 // 运行态用户打字时暂停流式物理写:流式每个 token 要 cup 到 contentRow 写入,IME 候选窗逐光标移动跟踪会跟过去;
@@ -1245,10 +1245,10 @@ function twoColumn(leftStr, leftW, rightStr, rightW, cols) {
 /** 上线之上那行(spinner 行):左段 = spinner 帧 + 状态文字 + 走时(全部左对齐,紧跟不分离)。
  *  右段仅在滚动回看时显历史指示(右端对齐)。
  *  示例:
- *    INPUT:     ◆ 空闲
+ *    INPUT:     ● 空闲
  *    思考中:    ⠹ 思考中… 0.5s
  *    运行心跳:  ♥ 0.5s
- *    滚动回看:  ◆ 空闲                  历史 ↑3 (PgDn 回底)  */
+ *    滚动回看:  ● 空闲                  历史 ↑3 (PgDn 回底)  */
 function composeSpinnerLine(status, cols) {
     const spinning = mode === 'running' && runningFrame >= 0;
     const hasSpinner = !!status.spinnerFrame;
@@ -1261,11 +1261,11 @@ function composeSpinnerLine(status, cols) {
     let lead;
     let leadW;
     if (scrolled) {
-        // 滚动回看:左段 = 符号(◆ 或 心跳帧) + 状态名(灰,无走时);右段 = 历史指示。
-        // 跟非回看的 INPUT/RUNNING 态保持一致——避免「◆ 留下、状态字蒸发」的视觉错觉。
+        // 滚动回看:左段 = 符号(● 或 心跳帧) + 状态名(灰,无走时);右段 = 历史指示。
+        // 跟非回看的 INPUT/RUNNING 态保持一致——避免「● 留下、状态字蒸发」的视觉错觉。
         const symbol = spinning
             ? `${ui.bold}${ui.accent}${RUNNING_FRAMES[runningFrame]}${ui.reset}`
-            : `${ui.accent}◆${ui.reset}`;
+            : `${ui.accent}●${ui.reset}`;
         lead = `${symbol} ${ui.dim}${status.status}${ui.reset}`;
         leadW = 1 + 1 + displayWidth(status.status);
     }
@@ -1282,8 +1282,8 @@ function composeSpinnerLine(status, cols) {
         leadW = 1 + (elapsed ? 1 + displayWidth(elapsed) : 0);
     }
     else {
-        // INPUT 态:◆ + 状态文字(无走时)
-        lead = `${ui.accent}◆${ui.reset} ${ui.dim}${status.status}${ui.reset}`;
+        // INPUT 态:● + 状态文字(无走时)
+        lead = `${ui.accent}●${ui.reset} ${ui.dim}${status.status}${ui.reset}`;
         leadW = 1 + 1 + displayWidth(status.status);
     }
     // ── 右段:仅滚动回看时显历史指示 ──
@@ -1378,7 +1378,7 @@ function composePlanLine(status, cols) {
 /** 画状态行(plan 行 + spinner 行 + model 行,三行)。RUNNING 态 spinner 频繁调。
  *  行号(footerH=6):
  *    plan 行     = contentBottom+1  (活跃 plan 时显 chip;无则空)
- *    spinner 行  = contentBottom+2  (◆ 空闲 / ⠹ 思考中… / etc)
+ *    spinner 行  = contentBottom+2  (● 空闲 / ⠹ 思考中… / etc)
  *    上线        = contentBottom+3  (画在 paintInput)
  *    输入行      = contentBottom+4
  *    下线        = contentBottom+5
@@ -1832,7 +1832,7 @@ export function enterInputMode(status = t('repl.idle')) {
     mode = 'input';
     statusText = status;
     spinnerFrame = undefined;
-    runningFrame = -1; // 回 INPUT 态:停状态行 chip 旋转,composeStatus 退回静态 ◆
+    runningFrame = -1; // 回 INPUT 态:停状态行 chip 旋转,composeStatus 退回静态 ●
     turnStart = null; // 停走时
     stopTurnTimer();
     scrollLockUntil = 0; // 轮末:清轮首滚动锁,INPUT 态可自由滚动

package/dist/ui/render.js

@@ -261,7 +261,7 @@ function memoryValue(on) {
 /** 横幅纯文本(带 ANSI 颜色,不写出)——供 TUI 经 contentWrite 写入内容区以跟踪续写位。
  *  布局:大字 logo(4 行,块字符)左对齐,右侧并排放标题/信息(neofetch 风)。 */
 export function bannerString(info) {
-    const title = `${ui.bold}${ui.accent}◆  MoCode${ui.reset}  ${ui.dim}v${VERSION}${ui.reset}`;
+    const title = `${ui.bold}${ui.accent}●  MoCode${ui.reset}  ${ui.dim}v${VERSION}${ui.reset}`;
     const labels = [t('banner.model'), t('banner.directory'), t('banner.memory')];
     // 标签列按当前语言最长文本动态定宽，并至少留两个空格；中文保持原 6 列，英文扩至 11 列。
     const labelWidth = Math.max(...labels.map(displayWidth)) + 2;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mocode-ai",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "终端编码 agent:LLM + tool-call 循环 + 流式输出(含思考)+ 16 个工具,接任意 OpenAI 兼容后端。",
   "type": "module",
   "bin": {