mocode-ai 1.2.6 → 1.2.7

package/dist/agent/core.js

@@ -6,7 +6,7 @@
 // spawn.ts 的 spawnAgent = runAgentCore + 静默 hooks(子 agent)。
 import { readFileSync } from 'node:fs';
 import { getNotesMtime } from '../session/notes.js';
-import { chat, estimatePromptTokens, planChatTools, chatTools, } from '../llm/index.js';
+import { chat, estimatePromptTokens, estimateTokens, planChatTools, chatTools, } from '../llm/index.js';
 import { executeToolOutcome, findTool, getToolCapabilities, isFileMutationTool, } from '../tools/registry.js';
 import { checkPermission } from '../permissions/index.js';
 import { validateToolArguments } from '../tools/validation.js';
@@ -15,10 +15,10 @@ import { getAgentMode, setAgentMode } from './mode.js';
 import { maybeCompact, contextState, createTraceEvent, summarizeToolArguments, safeProviderId, } from '../session/index.js';
 import { capToolResultForHistory } from '../session/compact.js';
 import { createBudgetScheduler } from '../session/scheduler.js';
-import { recordArtifact, invalidateArtifacts, rehydrateArtifacts, } from '../context/index.js';
+import { recordArtifact, invalidateArtifacts, rehydrateArtifacts, knownEditTargets, } from '../context/index.js';
 import { createRelevancePruner } from '../context/relevance.js';
 import { isToolResultSuccess } from '../context/utils.js';
-import { config, extractActivePlanSection, reinjectSessionStateIntoSystem } from '../config/index.js';
+import { config, getActiveModel, extractActivePlanSection, buildSessionStateReminder } from '../config/index.js';
 import { t } from '../i18n/index.js';
 import { jailResolve } from '../sandbox/index.js';
 import { createLifecycleEngine } from '../context/lifecycle.js';
@@ -40,6 +40,27 @@ function parseArgs(raw) {
         return null;
     }
 }
+/** 需要「已知编辑目标」恢复提示的文件编辑工具;其余工具的参数报错不注入该提示。 */
+const EDIT_HINT_TOOLS = new Set(['edit_file', 'write_file']);
+/** 文件编辑工具参数校验失败时的恢复提示:把系统已知仍新鲜的「最近 read_file 的
+ *  path + hash」直接递给模型照抄,替代其在长上下文里凭记忆复述。
+ *  只展示事实、不替模型填值;没有候选(从未 read_file / 全部已失效)返 undefined。 */
+function argumentErrorHint(name, state) {
+    if (!EDIT_HINT_TOOLS.has(name))
+        return undefined;
+    const targets = knownEditTargets(state);
+    if (targets.length === 0)
+        return undefined;
+    const lines = targets.map((target) => `  path=${target.path}  expected_hash=${target.hash}`).join('\n');
+    return ('系统已知最近 read_file 且尚未被修改的文件(直接复制下面的 path / expected_hash,勿凭记忆复述):\n' +
+        `${lines}\n如目标文件不在其中,先 read_file 该文件再发起编辑。`);
+}
+/** 判定 assistant content 是否只是 "Tool results:" 这类工具结果前缀噪声。
+ *  部分模型(如 Claude)会在 tool_calls 前输出此种无意义过渡文本，写入 history
+ *  会污染后续轮次上下文并在 TUI 上泄露为孤立行。 */
+function isToolResultsNoise(content) {
+    return /^(?:\s*Tool results:\s*)+$/i.test(content.trim());
+}
 /** 只有显式声明 parallel 且无需权限确认的工具才进入普通并发组。 */
 function isParallelTool(name) {
     const tool = findTool(name);
@@ -203,6 +224,7 @@ export async function runAgentCore(opts) {
                 completionTokens: turnUsage.completionTokens + u.completionTokens,
                 totalTokens: turnUsage.totalTokens + u.totalTokens,
                 cachedTokens: turnUsage.cachedTokens + u.cachedTokens,
+                cacheCreationTokens: (turnUsage.cacheCreationTokens ?? 0) + (u.cacheCreationTokens ?? 0),
                 reasoningTokens: turnUsage.reasoningTokens + u.reasoningTokens,
             }
             : u;
@@ -283,10 +305,16 @@ export async function runAgentCore(opts) {
                 const activeTools = opts.toolsOverride
                     ?? (getAgentMode() === 'plan' ? planChatTools : chatTools);
                 const requestBaseURL = config.baseURL;
-                const requestModel = config.model;
+                const requestModel = getActiveModel();
                 const storedCalibration = getTokenCalibration(requestBaseURL, requestModel, activeTools);
                 runtimeContextState.correction = storedCalibration.correction;
                 runtimeContextState.calibrationSamples = storedCalibration.samples;
+                // 会话状态(活跃 plan + 笔记正文)在调度器**之前**取一次:
+                //  ① 它会被追加到本次请求末尾(见下方 ephemeralReminder),属于本步固定开销,
+                //     必须计入压力线——它不在 history 里,调度器只能由此入参看见(否则最多 5k
+                //     的笔记 + plan 段对 80% 触发线完全不可见,小窗口模型会压不住);
+                //  ② 同一份字符串复用到下方 reminder,避免每步重复读 notes.md。
+                const sessionStateText = opts.suppressSessionState ? '' : buildSessionStateReminder();
                 // The scheduler is the only automatic path that may compress old evidence.
                 // Normal tool pushes and lifecycle tracking remain metadata-only.
                 // 步前:五区 Budget Scheduler 在当前完整 history 上决策；开关关闭时退化回 maybeCompact 路径。
@@ -294,7 +322,7 @@ export async function runAgentCore(opts) {
                 let historyRebuilt = false;
                 const compactStartedAt = Date.now();
                 if (scheduler) {
-                    historyRebuilt = await scheduler.runStep(history, step, activeTools);
+                    historyRebuilt = await scheduler.runStep(history, step, activeTools, sessionStateText ? estimateTokens(sessionStateText) : 0);
                     if (scheduler.lastRunLog?.compactHistoryCalled) {
                         emitTrace('compact', {
                             source: 'automatic',
@@ -326,8 +354,8 @@ export async function runAgentCore(opts) {
                         runtimeContextState.lifecycleStats = lifecycle.stats();
                     }
                     rehydrateArtifacts(runtimeContextState, history);
-                    // ② compact 后把会话状态(活跃 plan + 笔记段)重注入系统提示，避免 agent 因上下文压缩丢失计划与笔记。
-                    reinjectSessionStateIntoSystem(history);
+                    // 会话状态(活跃 plan + 笔记段)不再回写 history[0]:每步都会在 requestHistory
+                    // 末尾注入最新副本(见下方 ephemeralReminder),compact 后自然恢复。
                 }
                 hooks.onStepStart?.(); // 主 agent:spinner.start('思考中')
                 mode = 'idle';
@@ -337,31 +365,29 @@ export async function runAgentCore(opts) {
                 const modelStartedAt = Date.now();
                 const provider = safeProviderId(requestBaseURL);
                 emitTrace('model_start', { model: requestModel, provider });
-                // 动态注入(仅追加到 system 末尾,不触碰 staticBody 前缀 → 不破坏 prompt 缓存):
-                //  - 开场分析:仅主线(step===0 且 !suppressOpeningAnalysis)注入——即"用户发一个任务后,
-                //    agent 第一次模型调用"。子代理经 spawn.ts 传 suppressOpeningAnalysis:true 排除。
-                //  - historyRebuilt:compact 恢复步;要求重新锚定目标。两者可叠加但互不串扰。
-                //  .filter(Boolean) 保证空段不产生多余空行;后续 step 均为空串 → system 前缀稳定命中缓存。
-                //  安全保证:此段只拼进 requestHistory(新建对象),绝不回写 history[0],故不会跨 step/跨 turn 残留。
-                const dynamicSystemSuffix = [
+                // 动态注入(prompt 缓存关键):所有随步/随文件变化的提示统一拼成**历史末尾**一条
+                // ephemeral system 消息,不再改写 history[0]。这样系统提示 + 已有对话逐字节稳定,
+                // 支持自动前缀缓存的后端(OpenAI / DeepSeek / GLM / Qwen)可从头命中,只有尾部这
+                // 一小条随内容变化;若改写 history[0],单次 plan_update 就会让 6-8k 的系统提示
+                // 在本轮后续每步全价重算。
+                //  - 开场分析:仅主线(step===0 且 !suppressOpeningAnalysis)——用户发任务后 agent
+                //    的第一次模型调用。子代理经 spawn.ts 传 suppressOpeningAnalysis:true 排除。
+                //    放在尾部还有额外好处:step 0 与 step 1 的前缀不再因这段的出现/消失而错位。
+                //  - historyRebuilt:compact 恢复步,要求重新锚定目标。
+                //  - 会话状态:notes.md 的活跃 plan + 笔记正文(纯读,每步重取,始终最新)。
+                //  .filter(Boolean) 保证空段不产生多余空行;三段全空时不追加任何消息(requestHistory === history)。
+                //  安全保证:只拼进 requestHistory(新建数组),绝不写回 history,故不会跨 step/跨 turn 残留。
+                const ephemeralReminder = [
                     (!opts.suppressOpeningAnalysis && step === 0)
                         ? '## Opening analysis\nBegin your FIRST response of this turn with a brief analysis of the request and your planned approach (1-3 sentences, no filler), THEN start tool calls. This opening is the only place where pre-tool prose is expected; after it, work quietly with no narration between tool calls.'
                         : '',
                     historyRebuilt
                         ? '## Post-compaction recovery\nContext was compacted before this request. Re-establish the current objective and unresolved work from retained evidence or the session note, avoid repeating completed investigation, and re-read exact file context before any dependent edit.'
                         : '',
+                    sessionStateText, // 调度器之前已取(并计入压力线),此处复用同一份,不重复读文件
                 ].filter(Boolean).join('\n\n');
-                const systemMessage = history[0];
-                const requestHistory = dynamicSystemSuffix
-                    && systemMessage?.role === 'system'
-                    && typeof systemMessage.content === 'string'
-                    ? [
-                        {
-                            ...systemMessage,
-                            content: `${systemMessage.content}\n\n${dynamicSystemSuffix}`,
-                        },
-                        ...history.slice(1),
-                    ]
+                const requestHistory = ephemeralReminder
+                    ? [...history, { role: 'system', content: ephemeralReminder }]
                     : history;
                 // 实时用量:当前步 prompt 估算(含校准系数)+ 流式累计 completion 估算,
                 // 叠上已完成步的实测 turnUsage,经 onLiveUsage 推给底栏实时 chip。
@@ -461,6 +487,14 @@ export async function runAgentCore(opts) {
                 onContextUpdate?.();
                 if (result.toolCalls.length > 0) {
                     toolCallCount += result.toolCalls.length;
+                    // 若 content 只是 Claude 式 "Tool results:" 噪声，清空它：不补换行、不写入 history，
+                    // 避免污染后续轮次上下文并在 TUI 泄露为孤立行。
+                    if (result.content && isToolResultsNoise(result.content)) {
+                        result.content = null;
+                        mode = 'idle';
+                        gotText = false;
+                        lastChar = '';
+                    }
                     // 流式正文末尾补换行(若 onToolCall 已补则 lastChar='\n',此处 no-op);防 ● 行黏在正文行尾
                     if (mode !== 'idle' && lastChar !== '\n')
                         hooks.onTextEnd?.();
@@ -635,14 +669,18 @@ export async function runAgentCore(opts) {
                             const firstAllowed = entries.find((entry) => !entry.denied);
                             if (firstAllowed)
                                 hooks.onToolStart?.(firstAllowed.tc.name);
-                            const started = entries.map((entry) => entry.denied
-                                ? Promise.resolve(entry.denied)
-                                : executeToolOutcome(entry.tc.name, entry.tc.arguments, signal, {
+                            const started = entries.map((entry) => {
+                                if (entry.denied)
+                                    return Promise.resolve(entry.denied);
+                                const hint = argumentErrorHint(entry.tc.name, runtimeContextState);
+                                return executeToolOutcome(entry.tc.name, entry.tc.arguments, signal, {
                                     callId: entry.tc.id,
+                                    ...(hint ? { argumentErrorHint: hint } : {}),
                                     onLockAcquired: (lockedArgs) => {
                                         entry.diff = readDiffContext(entry.tc, lockedArgs);
                                     },
-                                }));
+                                });
+                            });
                             for (let k = 0; k < entries.length; k++) {
                                 const entry = entries[k];
                                 const outcome = await started[k];
@@ -726,8 +764,10 @@ export async function runAgentCore(opts) {
                                 : null;
                             let diff = readDiffContext(tc, mutationParsed);
                             hooks.onToolStart?.(tc.name);
+                            const serialHint = argumentErrorHint(tc.name, runtimeContextState);
                             const outcome = await executeToolOutcome(tc.name, tc.arguments, signal, {
                                 callId: tc.id,
+                                ...(serialHint ? { argumentErrorHint: serialHint } : {}),
                                 onLockAcquired: (lockedArgs) => {
                                     if (mutationParsed)
                                         diff = readDiffContext(tc, lockedArgs);
@@ -763,12 +803,12 @@ export async function runAgentCore(opts) {
                             i++;
                         }
                     }
-                    // A(事件驱动重同步):本步若改动了 notes.md,把最新 plan 块刷回 history[0],
-                    // 让模型上下文镜像当前勾选态(不再停留在轮首的旧副本)。只在 mtime 变化时触发,零额外 churn。
+                    // A(计划触碰计数):本步若改动了 notes.md 则清零计数。会话状态本身无需在此重注入——
+                    // 每步都会由 buildSessionStateReminder() 在 requestHistory 末尾重建最新副本(见上方注入点),
+                    // 所以模型下一步看到的必然是当前勾选态。只保留计数,避免多余的 history 改写(prompt 缓存)。
                     // B(nag 提醒):连续 N 步有工具活动但没更新 plan,在当前步第一条 tool_result 前注入提醒。
                     const notesMtimeAfter = getNotesMtime();
                     if (notesMtimeAfter !== notesMtimeBefore) {
-                        reinjectSessionStateIntoSystem(history);
                         stepsSincePlanTouch = 0;
                     }
                     else {

package/dist/agent/index.js

@@ -7,7 +7,6 @@ import { Spinner } from '../ui/spinner.js';
 import { summarizeToolCall, summarizeToolResult, truncateDisplay, fmtElapsed, } from '../ui/render.js';
 import { renderFileChange } from '../ui/diff.js';
 import * as layout from '../ui/layout.js';
-import * as content from '../ui/content.js';
 import * as batch from '../ui/batch.js';
 import { beginTurn } from '../rollback/index.js';
 import { config } from '../config/index.js';
@@ -27,17 +26,10 @@ let subAgentGroupPendingSeparator = false;
 /** 派生子 agent 的工具名。它的调用要独占一批:子 agent 的实时工具明细会挂到这一行下面,
  *  并行派发多个子 agent 时,每个子 agent 才有自己可归属的摘要行。 */
 const SUB_AGENT_TOOL = 'sub-agent';
-/** 缓冲尾部是否已经是空白行(去掉 ANSI 后无可见字符)。用于避免 sub-agent 分隔空行叠成两行。 */
+/** 缓冲尾部是否已经是空白行(去掉 ANSI 后无可见字符)。用于避免 sub-agent 分隔空行叠成两行。
+ *  实现委托 layout.isLastContentRowBlank(compact 等模块共用同一判断)。 */
 function isLastContentRowBlank() {
-    // 用 committedRows 而不是 totalRows：hasCurrent 那行是未提交的光标等待位，
-    // 永远空白，不能把它当作“已经有一条空行分隔”。
-    const committed = content.committedRows();
-    if (committed === 0)
-        return false;
-    const line = content.lineAt(committed - 1);
-    if (line === null)
-        return false;
-    return line.replace(/\x1b\[[0-9;]*m/g, '').trim().length === 0;
+    return layout.isLastContentRowBlank();
 }
 let turnFileChanges = [];
 function lineDelta(oldText, newText) {
@@ -274,33 +266,73 @@ onContextUpdate) {
     let textBoundaryNewlines = 0;
     let hasPendingTextBoundary = false;
     let toolBatchFollowsText = false;
+    // Claude 等模型在 tool_calls 前常输出 "Tool results:" 这类无意义叙述。
+    // 它违反 silent execution，会在正文区泄露成孤立行。这里先缓冲，若累积内容
+    // 只是该噪声则抑制；一旦后面跟了实质正文，再丢弃噪声前缀并 flush。
+    let pendingNarration = '';
+    let narrationIsNoise = false;
+    const TOOL_RESULTS_NOISE_RE = /^(?:\s*Tool results:\s*)+$/i;
+    function writeAssistantText(s) {
+        const inToolBlock = currentBatchId !== null || subAgentGroupId !== null || subAgentGroupPendingSeparator;
+        if (inToolBlock && s.trim().length === 0)
+            return;
+        const followsToolBatch = inToolBlock;
+        // batch 收尾已经统一留了一条空白行。部分后端会把下一段正文以 \n / \n\n
+        // 开头发来；去掉这些“边界换行”，避免与 UI 分隔叠成两条空白行。
+        const visible = followsToolBatch ? s.replace(/^(?:[ \t]*\r?\n)+/, '') : s;
+        // 正文是工具批次边界：只有“连续且中间没有正文”的工具调用才合并。
+        // 一旦模型开始解释阶段结果，立即收尾当前摘要；后续工具重新建立批次。
+        if (visible)
+            flushToolBatch();
+        spinner.stop(); // 任何正文 token 都停 spinner(首 token 停「思考中」;onToolCall 重启后若又来文本则停「生成中」)。未旋转时 stop 为 no-op。
+        layout.contentWriteMd(visible); // 正文走 markdown 渲染(代码块高亮 / 标题 / 列表 / 行内 …),见 ui/markdown.ts
+        if (visible) {
+            lastChar = visible[visible.length - 1];
+            if (visible.trim().length > 0) {
+                hasPendingTextBoundary = true;
+                textBoundaryNewlines = 0;
+            }
+        }
+    }
+    function trySuppressNoise(s) {
+        pendingNarration += s;
+        const stripped = pendingNarration.replace(/\s+/g, ' ').trim();
+        if (TOOL_RESULTS_NOISE_RE.test(stripped)) {
+            narrationIsNoise = true;
+            return null;
+        }
+        let visible = pendingNarration;
+        if (narrationIsNoise) {
+            visible = pendingNarration.replace(/^(?:\s*Tool results:\s*)+/i, '');
+            narrationIsNoise = false;
+        }
+        pendingNarration = '';
+        return visible;
+    }
+    function flushPendingNarrationIfAny() {
+        if (!pendingNarration)
+            return;
+        const stripped = pendingNarration.replace(/\s+/g, ' ').trim();
+        if (TOOL_RESULTS_NOISE_RE.test(stripped)) {
+            pendingNarration = '';
+            narrationIsNoise = false;
+            return;
+        }
+        const visible = pendingNarration;
+        pendingNarration = '';
+        narrationIsNoise = false;
+        writeAssistantText(visible);
+    }
     const hooks = {
         onText: (s) => {
-            // 纯空白 chunk 在视觉上不是正文：既不切 batch，也不写入 markdown 缓冲。
-            // 部分兼容后端会在连续工具轮次间流出 " " / "\n"，若据此切批会漏掉首个工具。
-            // sub-agent 独占批不占 currentBatchId，但同样处在“工具块刚结束”的边界上。
-            const inToolBlock = currentBatchId !== null || subAgentGroupId !== null || subAgentGroupPendingSeparator;
-            if (inToolBlock && s.trim().length === 0)
-                return;
-            const followsToolBatch = inToolBlock;
-            // batch 收尾已经统一留了一条空白行。部分后端会把下一段正文以 \n / \n\n
-            // 开头发来；去掉这些“边界换行”，避免与 UI 分隔叠成两条空白行。
-            const visible = followsToolBatch ? s.replace(/^(?:[ \t]*\r?\n)+/, '') : s;
-            // 正文是工具批次边界：只有“连续且中间没有正文”的工具调用才合并。
-            // 一旦模型开始解释阶段结果，立即收尾当前摘要；后续工具重新建立批次。
-            if (s)
-                flushToolBatch();
-            spinner.stop(); // 任何正文 token 都停 spinner(首 token 停「思考中」;onToolCall 重启后若又来文本则停「生成中」)。未旋转时 stop 为 no-op。
-            layout.contentWriteMd(visible); // 正文走 markdown 渲染(代码块高亮 / 标题 / 列表 / 行内 …),见 ui/markdown.ts
-            if (visible) {
-                lastChar = visible[visible.length - 1];
-                if (visible.trim().length > 0) {
-                    hasPendingTextBoundary = true;
-                    textBoundaryNewlines = 0;
-                }
-            }
+            const visible = trySuppressNoise(s);
+            if (visible === null)
+                return; // 纯噪声，抑制
+            writeAssistantText(visible);
         },
         onToolCall: (name) => {
+            // 工具调用开始前，先 flush 被抑制的叙述缓冲（若是纯噪声则丢弃）。
+            flushPendingNarrationIfAny();
             // 文本/思考已流完,模型转而生成 tool_call 参数(可能很长,如 write_file 整篇内容):
             // 补换行(让随后的 ● 行与 diff 不黏在正文末尾)+ 启「生成中」内联 spinner,内容区不再干等。
             if (hasPendingTextBoundary) {
@@ -358,6 +390,7 @@ onContextUpdate) {
             layout.contentWrite(`${ui.dim}${t('agent.aborted')}${ui.reset}\n`);
         },
         onDone: (elapsedMs, usage) => {
+            flushPendingNarrationIfAny();
             flushToolBatch();
             writeChangeOverview();
             const tok = formatTurnTokens(usage);
@@ -427,9 +460,12 @@ function formatTurnTokens(usage) {
         return '';
     const fmt = (n) => (n < 1000 ? `${n}` : `${(n / 1000).toFixed(total >= 10000 ? 0 : 1)}k`);
     const cached = usage.cachedTokens;
+    const cacheCreated = usage.cacheCreationTokens ?? 0;
     const reasoning = usage.reasoningTokens;
     const billablePrompt = usage.promptTokens - cached;
     const extras = [];
+    if (cacheCreated > 0)
+        extras.push(`cache created ${fmt(cacheCreated)}`);
     if (cached > 0)
         extras.push(`${Math.round((cached / Math.max(1, usage.promptTokens)) * 100)}% cached`);
     if (reasoning > 0)

package/dist/agent/spawn.js

@@ -250,6 +250,10 @@ export async function spawnAgent(opts) {
         toolsOverride,
         contextState: localContextState,
         suppressOpeningAnalysis: true, // 子代理不注入「开场分析」:仅主线面对用户的首次响应用
+        // 子代理不注入主会话「会话状态」(plan + 笔记):systemPrompt 已用
+        // buildMocodeCorePrompt() 切掉会话私有尾段,工具表也排除了 plan_update——
+        // 灌主计划只会干扰窄 worker 并白付 token。
+        suppressSessionState: true,
         onToolOutcome: (tool, args) => {
             if (tool === 'read_file' && typeof args.path === 'string')
                 readSet.add(args.path);

package/dist/commands/skill.js

@@ -0,0 +1,230 @@
+// `mocode skill` CLI 子命令(skill 自进化 Phase 0/1 的用户入口)。
+//
+//   mocode skill eval <name> [--runs N] [--threshold x] [--timeout ms]
+//       触发评测:对 <skill-dir>/evals/trigger.json 的每条 query 跑单轮 agent,
+//       统计 use_skill/run_skill 触发率,输出 PASS/FAIL 报告并落盘 JSON。
+//
+//   mocode skill improve <name> [--runs N] [--threshold x] [--iterations N]
+//                     [--holdout x] [--timeout ms] [--apply]
+//       description 进化循环:train/holdout 切分 + LLM 提案 + 接受门,默认 dry-run
+//       只打印最佳 description;--apply 才写回 SKILL.md(写前显式确认;非 TTY 拒绝)。
+//
+//   mocode skill usage [name]
+//       展示使用台账(Phase 0):按 skill 的调用次数/成功率/最近失败。
+//
+// 由 index.ts 在 `mocode skill …` 时动态加载(与 mocode config 同模式):
+// 此时才引入 config 单例(LLM 配置)+ agent 依赖图,缺 LLM 配置时给友好报错而非崩。
+// 纯打印/非 TUI:本进程不进 alt screen,输出走 stdout。
+import * as readline from 'node:readline';
+import path from 'node:path';
+import { config, isModelConfigured } from '../config/index.js';
+import { listSkills } from '../skills/index.js';
+import { loadSkillForEval, loadTriggerEvalSet, triggerEvalTemplate, triggerEvalPath, runTriggerEval, renderTriggerReport, saveTriggerReport, validateEvalParams, } from '../skills/skill-eval.js';
+import { runImproveLoop, applyImprovedDescription } from '../skills/skill-improve.js';
+import { loadSkillUsage, aggregateSkillStats, skillStatsPath } from '../skills/stats.js';
+function usage() {
+    console.log(`mocode skill — skill 自进化(触发评测 / description 进化 / 使用台账)
+
+用法:
+  mocode skill eval <name> [选项]        触发评测(需要 <skill-dir>/evals/trigger.json)
+  mocode skill improve <name> [选项]     description 进化循环(默认 dry-run)
+  mocode skill usage [name]              展示使用台账
+
+eval 选项:
+  --runs <n>          每 query 运行次数(默认 3;1..10)
+  --threshold <x>     触发率判定阈值(默认 0.5;>0 且 ≤1)
+  --timeout <ms>      单 query 超时(默认 60000)
+
+improve 选项:
+  --runs <n>          同 eval(默认 3)
+  --threshold <x>     同 eval(默认 0.5)
+  --iterations <n>    迭代上限(默认 5)
+  --holdout <x>       holdout 比例(默认 0.4;0 禁用)
+  --timeout <ms>      单 query 超时(默认 60000)
+  --apply             把最佳 description 写回 SKILL.md(默认 dry-run,仅打印)
+
+eval 集格式(<skill-dir>/evals/trigger.json,非空数组):
+  [
+    { "query": "应该触发该 skill 的真实请求", "should_trigger": true },
+    { "query": "不应触发的相近请求", "should_trigger": false }
+  ]
+
+注: 进化对象仅限 ~/.mocode/skills 与 <cwd>/.mocode/skills 下的 skill(内置 skill 不可进化)。
+    没有 evals/trigger.json 的 skill 只能 eval 前手工补建,improve 一律拒绝(没验证门不优化)。`);
+}
+function numArg(args, name, fallback) {
+    const i = args.indexOf(name);
+    if (i === -1 || i + 1 >= args.length)
+        return fallback;
+    const v = Number(args[i + 1]);
+    if (!Number.isFinite(v) || v <= 0) {
+        throw new Error(`${name} 需要正数: ${args[i + 1]}`);
+    }
+    return v;
+}
+function parseCommon(args) {
+    const runs = Math.round(numArg(args, '--runs', 3));
+    const threshold = numArg(args, '--threshold', 0.5);
+    const timeoutMs = Math.round(numArg(args, '--timeout', 60_000));
+    const err = validateEvalParams(runs, threshold);
+    if (err)
+        throw new Error(err);
+    return { runs, threshold, timeoutMs };
+}
+function requireModel() {
+    if (!isModelConfigured()) {
+        console.error('未配置 LLM(缺 LLM_BASE_URL / LLM_API_KEY)。先运行 `mocode config` 或设置环境变量。');
+        process.exit(1);
+    }
+}
+/** 定位 eval 集;缺失时打印模板并退出(不猜、不自动建)。 */
+function requireEvalSet(skillName) {
+    const skill = loadSkillForEval(skillName);
+    const cases = loadTriggerEvalSet(skill);
+    if (!cases) {
+        console.error(`未找到触发评测集: ${path.relative(process.cwd(), triggerEvalPath(skill))}`);
+        console.error('手工创建该文件(格式):');
+        console.error(triggerEvalTemplate(skill));
+        process.exit(1);
+    }
+    return { skill, cases };
+}
+async function evalCommand(args) {
+    const rest = args.slice();
+    const name = rest.find((a) => !a.startsWith('--'));
+    if (!name)
+        throw new Error('缺少 skill 名。见: mocode skill eval --help');
+    requireModel();
+    const { skill, cases } = requireEvalSet(name);
+    const { runs, threshold, timeoutMs } = parseCommon(rest);
+    console.log(`评测 skill "${skill.name}" — ${cases.length} 条 query × ${runs} 次,模型 ${config.model}\n`);
+    const startedAt = Date.now();
+    const report = await runTriggerEval(skill, skill.description, cases, runs, threshold, {
+        timeoutMs,
+        onProgress: (_d, _t, line) => process.stdout.write(line + '\n'),
+    });
+    const saved = saveTriggerReport(report);
+    console.log(`\n${renderTriggerReport(report, { runsPerQuery: runs, threshold })}`);
+    console.log(`\n耗时 ${((Date.now() - startedAt) / 1000).toFixed(1)}s,结果已存: ${path.relative(process.cwd(), saved)}`);
+    if (report.summary.passed < report.summary.total) {
+        console.log('存在失败项。可用 `mocode skill improve ' + skill.name + '` 尝试自动优化 description(dry-run)。');
+        process.exitCode = 1;
+    }
+}
+function confirmApply(skillName) {
+    if (!process.stdin.isTTY) {
+        // 非 TTY fail closed:自动落盘必须有人在场。
+        console.error('非 TTY 环境拒绝 --apply 自动落盘。请在终端运行,或手工编辑 SKILL.md 的 description。');
+        process.exit(1);
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(`确认把新 description 写回 skill "${skillName}" 的 SKILL.md?(y/N) `, (ans) => {
+            rl.close();
+            resolve(ans.trim().toLowerCase() === 'y' || ans.trim().toLowerCase() === 'yes');
+        });
+    });
+}
+async function improveCommand(args) {
+    const rest = args.slice();
+    const name = rest.find((a) => !a.startsWith('--'));
+    if (!name)
+        throw new Error('缺少 skill 名。见: mocode skill improve --help');
+    requireModel();
+    const { skill, cases } = requireEvalSet(name);
+    const { runs, threshold, timeoutMs } = parseCommon(rest);
+    const iterations = Math.round(numArg(rest, '--iterations', 5));
+    const holdout = (() => {
+        const i = rest.indexOf('--holdout');
+        const v = i === -1 ? 0.4 : Number(rest[i + 1]);
+        if (i !== -1 && (!Number.isFinite(v) || v < 0 || v > 0.9))
+            throw new Error('--holdout 需要 0..0.9 的数');
+        return v;
+    })();
+    const apply = rest.includes('--apply');
+    console.log(`进化 skill "${skill.name}" — ${cases.length} 条 query,train/holdout=${1 - holdout}/${holdout},${apply ? '将写回(--apply)' : 'dry-run(不落盘)'}\n`);
+    const result = await runImproveLoop(skill, cases, {
+        maxIterations: iterations,
+        runsPerQuery: runs,
+        threshold,
+        holdout,
+        timeoutMs,
+        onIteration: (_i, _max, line) => console.log(line),
+    });
+    console.log('');
+    if (!result.improved) {
+        console.log(`没有更优的 description(原 description 已是最佳或循环未产出改进)。`);
+        console.log(`原: ${result.originalDescription}`);
+        return;
+    }
+    console.log(`原 description: ${result.originalDescription}`);
+    console.log(`新 description: ${result.bestDescription}`);
+    if (apply) {
+        const ok = await confirmApply(skill.name);
+        if (!ok) {
+            console.log('已取消写回(dry-run 结果见上,可手工应用)。');
+            return;
+        }
+        applyImprovedDescription(skill, result.bestDescription);
+        console.log(`已写回: ${skill.skillMdPath}`);
+        console.log('提示: 内容哈希已变更,project 级 skill 下次 run_skill 会重新要求信任确认。');
+    }
+    else {
+        console.log('dry-run:未写文件。确认满意后加 --apply 重跑,或直接手工把新 description 写进 SKILL.md。');
+    }
+}
+function usageCommand(args) {
+    const filter = args.find((a) => !a.startsWith('--'));
+    const records = loadSkillUsage();
+    const summaries = aggregateSkillStats(records);
+    const list = filter ? summaries.filter((s) => s.skill === filter) : summaries;
+    if (list.length === 0) {
+        console.log(`(台账为空: ${path.relative(process.cwd(), skillStatsPath())})`);
+        console.log('台账在模型调用 use_skill / run_skill 时自动记录,跑几个会话后这里有数。');
+        return;
+    }
+    for (const s of list) {
+        const rate = s.runSuccessRate === null ? '' : ` run 成功率 ${(s.runSuccessRate * 100).toFixed(0)}%`;
+        console.log(`${s.skill}  ×${s.total}(use ${s.uses} / run ${s.runs})${rate}  最近 ${s.lastUsedAt}`);
+        if (s.lastFailure) {
+            console.log(`  最近失败: ${s.lastFailure.status}${s.lastFailure.code ? ` (${s.lastFailure.code})` : ''} @ ${s.lastFailure.ts}`);
+        }
+    }
+}
+export async function runSkillCommand(args) {
+    const sub = args[0];
+    if (!sub || sub === '--help' || sub === '-h' || sub === 'help') {
+        usage();
+        return;
+    }
+    try {
+        if (sub === 'eval')
+            await evalCommand(args.slice(1));
+        else if (sub === 'improve')
+            await improveCommand(args.slice(1));
+        else if (sub === 'usage')
+            usageCommand(args.slice(1));
+        else {
+            console.error(`未知子命令 "${sub}"。`);
+            usage();
+            process.exitCode = 1;
+        }
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (/aborted/i.test(msg)) {
+            console.error('\n已中断。');
+            process.exitCode = 130;
+        }
+        else {
+            console.error(`错误: ${msg}`);
+            process.exitCode = 1;
+        }
+    }
+}
+// 供 index.ts 判断子命令名集合(避免它 parse 我们的参数)。
+export const SKILL_SUBCOMMANDS = ['eval', 'improve', 'usage', 'help', '--help', '-h'];
+// listSkills 在 eval/improve 未命中时供报错文案复用(保持与 /skills 一致的名字集)。
+export function listSkillNames() {
+    return listSkills().map((s) => s.name);
+}