mocode-ai 1.2.6 → 1.2.7

package/dist/session/compact.js

@@ -292,10 +292,22 @@ export async function compactHistory(history, opts) {
     let oldGroups = groups.slice(0, groups.length - kept.length);
     // force(硬闸/手动强压):保护区不豁免——常规切分无旧区时只保最后一组,
     // 其余全部进可压区(首轮/当前轮也一样)。仍按 group 边界切,不破坏 tool_call 配对。
+    // **必须保留最早 user 所在 group**:LLM API(OpenAI / Anthropic)要求 messages 至少
+    //  含一条非空 user 消息,否则 400。force 旧实现把所有 user 丢进摘要 → 重建后 history
+    //  无 user → 下一轮 chat() 被后端拒绝。保最早 user(而非最后一个)因为它是最原始的
+    //  请求上下文,摘要器已覆盖后续交互。
     if (oldGroups.length === 0 && opts.force && groups.length >= 2) {
         kept.length = 0;
-        kept.push(groups[groups.length - 1]);
-        oldGroups = groups.slice(0, groups.length - 1);
+        const lastIdx = groups.length - 1;
+        const firstUserIdx = groups.findIndex((g) => g.assistant?.role === 'user');
+        if (firstUserIdx >= 0 && firstUserIdx !== lastIdx) {
+            kept.push(groups[firstUserIdx], groups[lastIdx]);
+            oldGroups = groups.filter((_, i) => i !== firstUserIdx && i !== lastIdx);
+        }
+        else {
+            kept.push(groups[lastIdx]);
+            oldGroups = groups.slice(0, groups.length - 1);
+        }
     }
     const noop = {
         compacted: false,
@@ -319,6 +331,8 @@ export async function compactHistory(history, opts) {
                 const estimateAfter = estimatePromptTokens(history, activeTools, state.correction);
                 state.lastEstimate = estimateAfter;
                 state.lastUsage = undefined;
+                if (!layout.isLastContentRowBlank())
+                    layout.contentWrite('\n');
                 layout.contentWrite(`  ${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}强制微压缩(单组)${ui.reset}  ${ui.dim}${estimateBefore} → ${estimateAfter} tokens${ui.reset}\n`);
                 return {
                     compacted: true,
@@ -339,6 +353,8 @@ export async function compactHistory(history, opts) {
         }
         // history 有内容但全在保护区(系统 + 当前轮)
         if (estimateBefore >= opts.threshold * opts.window) {
+            if (!layout.isLastContentRowBlank())
+                layout.contentWrite('\n');
             layout.contentWrite(`  ${ui.yellow}●${ui.reset} ${ui.yellow}上下文已超阈但无可压缩项(全在保护区),建议 /clear 或缩短输入。${ui.reset}\n`);
             return { ...noop, reason: 'noop-shrunk-too-large', protectedRatio };
         }
@@ -383,6 +399,10 @@ export async function compactHistory(history, opts) {
         const estimateAfter = estimatePromptTokens(history, activeTools, state.correction);
         state.lastEstimate = estimateAfter;
         state.lastUsage = undefined; // 压缩后旧 usage 失效,/context 改用校正估算
+        // 压缩行与上一个工具批次摘要行之间补空行分隔(compact 在 core step 循环顶部触发,
+        // 上一步的 batch 可能尚未 flush,缓冲末行仍是 ● 工具摘要行 → 两行黏在一起)。
+        if (!layout.isLastContentRowBlank())
+            layout.contentWrite('\n');
         layout.contentWrite(`  ${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}压缩上下文${ui.reset}  ${ui.dim}${estimateBefore} → ${estimateAfter} tokens${ui.reset}\n`);
         // 抖动保护:压缩后仍超阈 → 提示 /clear,不死循环
         if (estimateAfter >= opts.threshold * opts.window) {
@@ -402,6 +422,8 @@ export async function compactHistory(history, opts) {
     state.lastEstimate = estimateAfter;
     state.lastUsage = undefined; // token 数已变,旧 usage 失效
     if (microcompactDone) {
+        if (!layout.isLastContentRowBlank())
+            layout.contentWrite('\n');
         layout.contentWrite(`  ${ui.bold}${ui.accent}●${ui.reset} ${ui.accent}微压缩旧工具结果${ui.reset}  ${ui.dim}${estimateBefore} → ${estimateAfter} tokens${ui.reset}\n`);
         return {
             compacted: true,

package/dist/session/persist.js

@@ -1,6 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync, } from 'node:fs';
 import path from 'node:path';
-import { config } from '../config/index.js';
+import { config, getActiveModel } from '../config/index.js';
 import { truncateDisplay } from '../ui/render.js';
 /** 会话目录(确保存在)。 */
 export function sessionDir() {
@@ -49,7 +49,7 @@ export function saveSession(history, id, queryHistory = []) {
     const meta = {
         id,
         createdAt: idToIso(id),
-        model: config.model,
+        model: getActiveModel(),
         firstUser: history.length > 1
             ? firstUserOf(history)
             : truncateDisplay((queryHistory[0] ?? '').replace(/\n/g, ' ').trim(), 40),

package/dist/session/scheduler.js

@@ -25,13 +25,13 @@ function emptyPressure(report) {
 }
 /** One scheduler instance is owned by one agent run. */
 export function createBudgetScheduler(state = contextState) {
-    const evaluate = (history, step, activeTools) => evaluateBudget(history, config.contextWindowTokens, step, state.correction, activeTools);
+    const evaluate = (history, step, activeTools, ephemeralTokens) => evaluateBudget(history, config.contextWindowTokens, step, state.correction, activeTools, ephemeralTokens);
     const scheduler = {
         lastRunLog: null,
-        async runStep(history, step, activeTools = chatTools) {
+        async runStep(history, step, activeTools = chatTools, ephemeralTokens = 0) {
             // External file changes and mutations only update artifact metadata here.
             refreshArtifactFreshness(state, history);
-            const report = evaluate(history, step, activeTools);
+            const report = evaluate(history, step, activeTools, ephemeralTokens);
             const pressure = emptyPressure(report);
             pressure.triggered = atPressure(report);
             if (pressure.triggered) {
@@ -46,7 +46,7 @@ export function createBudgetScheduler(state = contextState) {
                     const ageAware = createAgeAwareEncodingState(history);
                     pressure.encodedLogsAndSearches = ageAware.sweepPressure(history, report.hotBoundary);
                 }
-                pressure.after = evaluate(history, step, activeTools).total;
+                pressure.after = evaluate(history, step, activeTools, ephemeralTokens).total;
             }
             // Use the trigger report intentionally: cleanup may reduce the current estimate,
             // but crossing 80% commits this step to compacting for maximum token savings.

package/dist/skills/skill-eval.js

@@ -0,0 +1,345 @@
+// skill 触发评测引擎(自进化 Phase 1a)。
+//
+// 设计(docs/skill-self-evolution-research.md Part 3 Phase 1):
+//  - 评测对象是 skill 的 description(触发器),不是正文——触发不准是最常见痛点。
+//  - 载体:<skill-dir>/evals/trigger.json = [{ "query": "...", "should_trigger": true|false }, ...]
+//  - 判定:mocode 没有 Claude Code 的原生 Skill 触发事件,等价信号 = 该 query 的单轮运行里
+//    模型是否调用了 use_skill(name) / run_skill(name)。用 onToolOutcome hook 判定(拿完整 args)。
+//  - 隔离:系统提示只含该 skill 的 L0 行(name + description),工具表只给这两个工具,
+//    排除其他 skill / 工具干扰。保真度折扣(无历史上下文)在报告里如实标注(见调研 Q1)。
+//  - 噪声处理(调研共识):runs-per-query 多次运行取触发率,禁止单次跑分定生死。
+//
+// 依赖 runAgentCore:与 evals/coding/runner.ts 同构(隔离状态 + 临时沙箱 + 限步 + 超时)。
+// 纯函数(splitTriggerSet / scoreTriggerResults / applyDescription / parseTriggerEvalSet)
+// 与执行解耦,可单测。
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runAgentCore } from '../agent/core.js';
+import { config } from '../config/index.js';
+import { beginTurn, resetState } from '../rollback/index.js';
+import { setSandboxRoot } from '../sandbox/root.js';
+import { createContextState } from '../session/compact.js';
+import { tools } from '../tools/registry.js';
+import { findSkill, buildSkillSectionFor } from './index.js';
+/** eval 集路径(与 skill 同目录,随 skill 分发;trust hash 不覆盖它——evals 不是执行面)。 */
+export function triggerEvalPath(skill) {
+    return path.join(skill.dir, 'evals', 'trigger.json');
+}
+/** 解析并校验 eval 集;文件不存在返 null;格式错误抛 Error(带诊断信息)。 */
+export function parseTriggerEvalSet(skill) {
+    const p = triggerEvalPath(skill);
+    if (!existsSync(p))
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(p, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`evals/trigger.json 不是合法 JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!Array.isArray(raw) || raw.length === 0) {
+        throw new Error('evals/trigger.json 必须是非空数组: [{ "query": "...", "should_trigger": true|false }, ...]');
+    }
+    const out = [];
+    for (let i = 0; i < raw.length; i++) {
+        const item = raw[i];
+        if (typeof item?.query !== 'string' || !item.query.trim()) {
+            throw new Error(`evals/trigger.json 第 ${i + 1} 项缺 "query"(非空字符串)`);
+        }
+        if (typeof item?.should_trigger !== 'boolean') {
+            throw new Error(`evals/trigger.json 第 ${i + 1} 项缺 "should_trigger"(true/false)`);
+        }
+        out.push({ query: item.query, should_trigger: item.should_trigger });
+    }
+    return out;
+}
+/**
+ * 分层切 train/holdout(按 should_trigger 分组各切,防过拟合)。
+ * holdout ∈ (0,1);0 表示禁用(全 train)。seeded Fisher-Yates,结果可复现。
+ */
+export function splitTriggerSet(evalSet, holdout, seed = 42) {
+    if (holdout <= 0)
+        return { train: evalSet, holdout: [] };
+    const frac = Math.min(Math.max(holdout, 0), 0.9);
+    const trigger = shuffleSeeded(evalSet.filter((e) => e.should_trigger), seed);
+    const noTrigger = shuffleSeeded(evalSet.filter((e) => !e.should_trigger), seed + 1);
+    const nT = Math.max(1, Math.round(trigger.length * frac));
+    const nN = Math.max(1, Math.round(noTrigger.length * frac));
+    return {
+        train: [
+            ...trigger.slice(nT, trigger.length),
+            ...noTrigger.slice(nN, noTrigger.length),
+        ],
+        holdout: [...trigger.slice(0, nT), ...noTrigger.slice(0, nN)],
+    };
+}
+function shuffleSeeded(arr, seed) {
+    const a = [...arr];
+    let s = seed >>> 0;
+    const rand = () => {
+        // mulberry32:小而确定,跨平台一致
+        s = (s + 0x6d2b79f5) >>> 0;
+        let t = s;
+        t = Math.imul(t ^ (t >>> 15), t | 1);
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+    for (let i = a.length - 1; i > 0; i--) {
+        const j = Math.floor(rand() * (i + 1));
+        const tmp = a[i];
+        a[i] = a[j];
+        a[j] = tmp;
+    }
+    return a;
+}
+/**
+ * 纯评分:每 query 触发率 vs 阈值。should_trigger 需 rate ≥ threshold;
+ * 否则需 rate < threshold(边界 < 而非 ≤:恰在阈值上视为误触发,保守)。
+ */
+export function scoreTriggerResults(evalSet, runResults, threshold) {
+    return evalSet.map((e) => {
+        const triggers = runResults.get(e.query) ?? [];
+        const rate = triggers.length ? triggers.filter(Boolean).length / triggers.length : 0;
+        const pass = e.should_trigger ? rate >= threshold : rate < threshold;
+        return {
+            query: e.query,
+            should_trigger: e.should_trigger,
+            triggers: triggers.filter(Boolean).length,
+            runs: triggers.length,
+            trigger_rate: rate,
+            pass,
+        };
+    });
+}
+export function summarizeTriggerResults(results) {
+    const passed = results.filter((r) => r.pass).length;
+    return { total: results.length, passed, failed: results.length - passed, passRate: results.length ? passed / results.length : 0 };
+}
+/** 描述长度上限(开放标准:与 when_to_use 合并 1536 字;单字段取同值,保守)。 */
+export const MAX_DESCRIPTION_CHARS = 1536;
+/**
+ * 把新 description 写进 SKILL.md 的 frontmatter(纯函数,不落盘)。
+ * 支持:标量 `key: value` / 引号标量 / 块标量 `key: |`(多行)三种现状形态,
+ * 统一替换为单行标量(前提:新值不含换行与 `: `,由调用方校验)。
+ * 找不到 frontmatter 或 description 键 → 返 null(调用方生成诊断)。
+ */
+export function applyDescription(content, newDescription) {
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    let i = 0;
+    while (i < lines.length && lines[i].trim() === '')
+        i++;
+    if (i >= lines.length || lines[i].trim() !== '---')
+        return null;
+    const start = i;
+    i++;
+    let end = -1;
+    let descLine = -1;
+    let blockEnd = -1;
+    while (i < lines.length) {
+        if (lines[i].trim() === '---') {
+            end = i;
+            break;
+        }
+        const trimmed = lines[i].trim();
+        if (trimmed.startsWith('description:') && descLine === -1) {
+            descLine = i;
+            const value = lines[i].slice(lines[i].indexOf(':') + 1).trim();
+            if (value === '|' || value === '|-' || value === '>' || value === '>-') {
+                let j = i + 1;
+                while (j < lines.length && (lines[j].trim() === '' || /^\s+/.test(lines[j])) && lines[j].trim() !== '---') {
+                    j++;
+                }
+                blockEnd = j; // 块标量消费到块结束(不含)
+            }
+        }
+        i++;
+    }
+    if (end === -1 || descLine === -1)
+        return null;
+    const next = lines.slice();
+    next[descLine] = `description: ${newDescription}`;
+    // 原为块标量:删除被消费的块行(倒序删避免位移)
+    if (blockEnd !== -1) {
+        next.splice(descLine + 1, blockEnd - (descLine + 1));
+    }
+    void start;
+    return next.join('\n');
+}
+// ── 执行:单 query 触发探测 + 批量评测 ─────────────────────────────────────
+const TRIGGER_SESSION_ID = 'skill-trigger-eval';
+/** 隔离评测系统提示:身份 + 该 skill 的唯一 L0 行。确定性模板(不用 t(),保证跨语言可比)。 */
+function buildHarnessPrompt(skill, description) {
+    const section = buildSkillSectionFor([
+        { ...skill, description, modelInvocable: true },
+    ]);
+    return ('You are mocode, a terminal coding agent.\n' +
+        'A user request follows. Decide whether the single skill below is relevant to it.\n' +
+        '- If it is relevant, you MUST call use_skill with exactly this skill name, then stop and briefly say the skill instructions are loaded.\n' +
+        '- If it is not relevant, answer the request normally with plain text; do NOT call any tool.\n' +
+        '- Do not use any tool other than use_skill / run_skill.\n' +
+        section);
+}
+/**
+ * 单 query 跑一轮:返回是否触发(该轮内出现 use_skill/run_skill 且 name 匹配)。
+ * 隔离:临时沙箱根、禁权限、独立 contextState、限步、超时 abort。状态在 finally 复原。
+ * fork skill 归一为 inline 形态评测:harness 只测「模型据 description 选不选这个 skill」,
+ * 与 use_skill 返回引导语还是正文无关,归一保证评测语义一致且判定路径唯一。
+ */
+async function runSingleQuery(skill, description, query, opts) {
+    const root = mkdtempSync(path.join(tmpdir(), `mocode-skill-eval-${skill.name}-`));
+    const previousCwd = process.cwd();
+    const previousRoot = setSandboxRoot(root);
+    const previousPermission = config.permissionEnabled;
+    const previousEvalFlag = process.env.MOCODE_SKILL_EVAL;
+    process.env.MOCODE_SKILL_EVAL = '1'; // 评测内的人工调用不记使用台账(见 stats.ts)
+    config.permissionEnabled = false; // 隔离评测:run_skill 等 confirm 工具不弹面板(非 TTY fail-closed 会全拒)
+    resetState();
+    const turnId = beginTurn(query);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 60_000);
+    // 外部中断透传(AbortSignal.any 需 Node ≥20,这里手动桥接,兼容 engines>=18)
+    const externalAbort = () => controller.abort();
+    if (opts.signal) {
+        if (opts.signal.aborted)
+            controller.abort();
+        else
+            opts.signal.addEventListener('abort', externalAbort, { once: true });
+    }
+    let triggered = false;
+    try {
+        const systemPrompt = buildHarnessPrompt({ ...skill, context: 'inline' }, description);
+        const history = [{ role: 'system', content: systemPrompt }];
+        const isTriggerCall = (tool, args) => (tool === 'use_skill' || tool === 'run_skill') &&
+            String(args?.name ?? '').trim() === skill.name;
+        await runAgentCore({
+            history,
+            userInput: query,
+            signal: controller.signal,
+            hooks: {},
+            maxSteps: opts.maxSteps ?? 4,
+            contextState: createContextState(),
+            // 工具面收窄到两个 skill 入口:排除其余工具对触发的干扰,也避免误触发的副作用面。
+            toolsOverride: tools
+                .filter((t) => t.name === 'use_skill' || t.name === 'run_skill')
+                .map((t) => ({
+                type: 'function',
+                function: {
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                },
+            })),
+            onTrace: () => { },
+            onToolOutcome: (tool, args) => {
+                if (isTriggerCall(tool, args)) {
+                    triggered = true;
+                    // 触发已判定:立即终止,不再跑后续步(省 token;工具执行本身被 abort 取消)。
+                    controller.abort();
+                }
+            },
+            traceContext: { sessionId: TRIGGER_SESSION_ID, turnId },
+            suppressOpeningAnalysis: true,
+        });
+    }
+    catch (e) {
+        // abort(超时/外部中断/触发后早停)或 LLM 失败:未触发即未触发,不改变判定。
+        void e;
+    }
+    finally {
+        clearTimeout(timer);
+        opts.signal?.removeEventListener('abort', externalAbort);
+        process.chdir(previousCwd);
+        setSandboxRoot(previousRoot);
+        if (previousEvalFlag === undefined)
+            delete process.env.MOCODE_SKILL_EVAL;
+        else
+            process.env.MOCODE_SKILL_EVAL = previousEvalFlag;
+        config.permissionEnabled = previousPermission;
+        resetState();
+        rmSync(root, { recursive: true, force: true });
+    }
+    return triggered;
+}
+/**
+ * 对 eval 集批量评测一个 description:每条 query 跑 runsPerQuery 次(串行;
+ * 触发评测单轮短小,并行收益小且会放大 LLM 限流面),输出 TriggerReport。
+ */
+export async function runTriggerEval(skill, description, evalSet, runsPerQuery, threshold, opts = {}) {
+    const runResults = new Map();
+    let done = 0;
+    const total = evalSet.length * runsPerQuery;
+    for (const e of evalSet) {
+        const bools = [];
+        for (let r = 0; r < runsPerQuery; r++) {
+            if (opts.signal?.aborted)
+                throw new Error('评测被中断');
+            const hit = await runSingleQuery(skill, description, e.query, opts);
+            bools.push(hit ? 1 : 0);
+            done++;
+            opts.onProgress?.(done, total, `  [${done}/${total}] ${hit ? '✓ 触发' : '· 未触发'} ${e.query.slice(0, 60)}`);
+        }
+        runResults.set(e.query, bools);
+    }
+    const results = scoreTriggerResults(evalSet, runResults, threshold);
+    return { skill: skill.name, description, results, summary: summarizeTriggerResults(results) };
+}
+// ── CLI 输出渲染 ───────────────────────────────────────────────────────────
+/** 终端报告(人类可读)。 */
+export function renderTriggerReport(report, extra) {
+    const lines = [];
+    lines.push(`skill: ${report.skill}`);
+    lines.push(`description: ${report.description}`);
+    lines.push('');
+    for (const r of report.results) {
+        const status = r.pass ? 'PASS' : 'FAIL';
+        const expect = r.should_trigger ? '期望触发' : '期望不触发';
+        lines.push(`  [${status}] ${r.triggers}/${r.runs} (${expect}) ${r.query.slice(0, 70)}`);
+    }
+    const s = report.summary;
+    lines.push('');
+    lines.push(`汇总: ${s.passed}/${s.total} 通过 (阈值 ${extra.threshold}, 每 query ${extra.runsPerQuery} 次)`);
+    lines.push('注: 隔离评测(单轮 + 仅该 skill 的 L0 行),与完整生产上下文的触发保真度存在已知折扣。');
+    return lines.join('\n');
+}
+// ── 便捷入口:按 skill 名定位 + 读取 eval 集(带诊断)────────────────────
+export function loadSkillForEval(name) {
+    const skill = findSkill(name);
+    if (!skill)
+        throw new Error(`未找到 skill "${name}"(用 /skills 或 mocode skill eval 的帮助查看列表)`);
+    if (skill.dir === 'builtin') {
+        throw new Error(`内置 skill "${name}" 没有磁盘载体,无法做触发评测(进化对象仅限 ~/.mocode/skills 与 <cwd>/.mocode/skills)`);
+    }
+    return skill;
+}
+/** 读 eval 集;不存在时返回 null(调用方按「缺文件」处理:打印模板 + 退出)。 */
+export function loadTriggerEvalSet(skill) {
+    return parseTriggerEvalSet(skill);
+}
+/** 生成 trigger.json 模板内容(供 CLI 提示)。 */
+export function triggerEvalTemplate(skill) {
+    const cases = [
+        { query: `TODO: 一条应该触发 "${skill.name}" 的真实请求`, should_trigger: true },
+        { query: 'TODO: 一条不应触发的相近请求', should_trigger: false },
+    ];
+    return JSON.stringify(cases, null, 2);
+}
+/** 评测结果落盘目录(<cwd>/.mocode/skill-eval/);返回写入路径。 */
+export function saveTriggerReport(report) {
+    const dir = path.join(process.cwd(), '.mocode', 'skill-eval');
+    mkdirSync(dir, { recursive: true });
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const p = path.join(dir, `${report.skill}-${stamp}.json`);
+    writeFileSync(p, JSON.stringify(report, null, 2), 'utf8');
+    return p;
+}
+/** 供 CLI 校验 runsPerQuery / threshold 参数(纯函数,单测覆盖)。 */
+export function validateEvalParams(runsPerQuery, threshold) {
+    if (!Number.isInteger(runsPerQuery) || runsPerQuery < 1 || runsPerQuery > 10) {
+        return 'runsPerQuery 必须是 1..10 的整数';
+    }
+    if (!(threshold > 0 && threshold <= 1)) {
+        return 'threshold 必须是 (0, 1] 的数';
+    }
+    return null;
+}

package/dist/skills/skill-improve.js

@@ -0,0 +1,221 @@
+// skill description 进化循环(自进化 Phase 1b)。
+//
+// 协议移植自 skill-creator 的 run_loop.py(调研见 docs/skill-self-evolution-research.md Part 1.2):
+//  - 分层切 train/holdout(默认 0.4)防过拟合
+//  - 每轮:LLM 读失败案例 → 提案新 description → 评测 → 接受门
+//  - 接受门(保守双条件):train 严格提升 且 holdout 不降;holdout 为空时退化为全集严格提升
+//  - 拒绝缓冲:被拒的候选记下来,后续提案明确告知「这些已试过且更差」,防重复打转
+//  - 迭代上限(默认 5);全程记录 history,返回最佳 description
+//
+// 安全边界(调研 Part 3):
+//  - 默认 dry-run(只打印不落盘);--apply 才写回 SKILL.md,且写前再显式确认一次
+//  - builtin skill 无磁盘载体,拒绝(入口在 skill-eval.loadSkillForEval)
+//  - 进化对象仅 description 一行;正文/脚本/执行面字段不在自动编辑范围
+//
+// 依赖:skill-eval.ts(评测引擎 + 纯函数)+ llm.chat(提案,单轮无工具)。
+import { readFileSync, writeFileSync } from 'node:fs';
+import { chat } from '../llm/index.js';
+import { runTriggerEval, splitTriggerSet, applyDescription, MAX_DESCRIPTION_CHARS, } from './skill-eval.js';
+/** 提案 LLM 的系统指令:确定性模板(不用 t(),保证跨语言可比、可单测断言)。 */
+export function buildImprovePrompt(skill, currentDescription, failingCases, rejected) {
+    const body = (skill.body ?? '').slice(0, 1500);
+    const failLines = failingCases
+        .map((c) => {
+        const expect = c.should_trigger ? 'SHOULD trigger' : 'should NOT trigger';
+        return `- "${c.query}" → ${expect}, actual trigger rate ${c.trigger_rate.toFixed(2)}`;
+    })
+        .join('\n');
+    const rejectedBlock = rejected.length
+        ? `\nThese descriptions were already tried and performed WORSE. Do not propose any of them or near-duplicates:\n${rejected
+            .map((d) => `- ${d}`)
+            .join('\n')}\n`
+        : '';
+    return [
+        `You are optimizing the frontmatter "description" field of an agent skill named "${skill.name}".`,
+        'The description is the ONLY text the model sees when deciding whether to trigger the skill.',
+        `The skill body (what it actually does) begins with:\n---\n${body}\n---`,
+        `Current description:\n${currentDescription}`,
+        'Test results with the current description (failures to fix):',
+        failLines,
+        rejectedBlock,
+        'Propose ONE improved description that makes the skill trigger for the SHOULD-trigger cases and stay silent for the should-NOT-trigger cases.',
+        'Rules:',
+        '- Output ONLY the description text, nothing else (no quotes, no "description:", no markdown).',
+        '- One line only, 100-400 characters.',
+        '- Write it as a routing rule: state WHAT it does and WHEN to use it (concrete triggers/phrases), not as documentation.',
+        '- Preserve the language of the current description (English stays English, Chinese stays Chinese).',
+    ].join('\n');
+}
+/**
+ * 从 LLM 输出里提取候选 description(纯函数):
+ * 去首尾空白 → 若以 "description:" 开头则剥掉 → 只取第一行 → 去配对引号 → 校验长度。
+ * 非法(空 / 超长)返 null。
+ */
+export function extractDescriptionProposal(text, maxChars = MAX_DESCRIPTION_CHARS) {
+    let t = (text ?? '').trim();
+    if (!t)
+        return null;
+    t = t.replace(/^description\s*[:：]\s*/i, '');
+    let first = t.split(/\r?\n/)[0].trim();
+    if (!first)
+        return null;
+    if (first.length >= 2 && (first[0] === '"' || first[0] === "'") && first[first.length - 1] === first[0]) {
+        first = first.slice(1, -1).trim();
+    }
+    if (!first || first.length > maxChars)
+        return null;
+    return first;
+}
+/** 接受门(纯函数):train 严格提升 且 holdout 不降;holdout 为空时全集严格提升。 */
+export function shouldAcceptCandidate(base, cand) {
+    const trainUp = cand.trainPass > base.trainPass;
+    if (!trainUp) {
+        return { accept: false, reason: `train 未提升 (${cand.trainPass}/${cand.trainTotal} ≤ ${base.trainPass}/${base.trainTotal})` };
+    }
+    if (base.holdoutPass === null || cand.holdoutPass === null) {
+        return { accept: true, reason: `train 提升且无 holdout(${base.trainPass}→${cand.trainPass})` };
+    }
+    if (cand.holdoutPass < base.holdoutPass) {
+        return { accept: false, reason: `holdout 回退 (${cand.holdoutPass} < ${base.holdoutPass}),过拟合 train` };
+    }
+    return { accept: true, reason: `train ${base.trainPass}→${cand.trainPass},holdout ${base.holdoutPass}→${cand.holdoutPass}(不降)` };
+}
+/** 把报告按 query 集合拆成 train / holdout 的分项(纯函数)。 */
+function partitionReport(report, trainQueries) {
+    const train = report.results.filter((r) => trainQueries.has(r.query));
+    const holdout = report.results.filter((r) => !trainQueries.has(r.query));
+    return {
+        trainPass: train.filter((r) => r.pass).length,
+        trainTotal: train.length,
+        holdoutPass: holdout.length ? holdout.filter((r) => r.pass).length : null,
+        holdoutTotal: holdout.length,
+    };
+}
+function failingCases(report) {
+    return report.results
+        .filter((r) => !r.pass)
+        .map((r) => ({ query: r.query, should_trigger: r.should_trigger, trigger_rate: r.trigger_rate }));
+}
+/** 调 LLM 提案一次(单轮、无工具、超时 abort)。失败抛错由调用方捕获。 */
+async function proposeDescription(prompt, timeoutMs, signal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    // AbortSignal.any 需 Node ≥20;engines>=18,手动桥接外部 signal。
+    const externalAbort = () => controller.abort();
+    if (signal) {
+        if (signal.aborted)
+            controller.abort();
+        else
+            signal.addEventListener('abort', externalAbort, { once: true });
+    }
+    try {
+        const messages = [{ role: 'user', content: prompt }];
+        const res = await chat(messages, {}, controller.signal);
+        return extractDescriptionProposal(res.content ?? '');
+    }
+    finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', externalAbort);
+    }
+}
+/**
+ * 进化主循环。evalSet 必须非空(调用方保证;无 evals 的 skill 在 CLI 层拒绝——
+ * 「没验证门的 skill 禁止自动落盘」,调研共识 1)。
+ */
+export async function runImproveLoop(skill, evalSet, opts = {}) {
+    const maxIterations = opts.maxIterations ?? 5;
+    const runsPerQuery = opts.runsPerQuery ?? 3;
+    const threshold = opts.threshold ?? 0.5;
+    const { train, holdout } = splitTriggerSet(evalSet, opts.holdout ?? 0.4, opts.seed ?? 42);
+    if (train.length === 0)
+        throw new Error('train 集为空:eval 集太小,无法进化(至少需要 2 条且覆盖触发/不触发)');
+    const trainQueries = new Set(train.map((t) => t.query));
+    const evalOpts = { runsPerQuery, threshold, timeoutMs: opts.timeoutMs, signal: opts.signal };
+    let baseDescription = skill.description;
+    let baseReport = await runTriggerEval(skill, baseDescription, evalSet, runsPerQuery, threshold, evalOpts);
+    let baseParts = partitionReport(baseReport, trainQueries);
+    const iterations = [];
+    const rejected = [];
+    let bestDescription = baseDescription;
+    let bestKey = [baseParts.trainPass, baseParts.holdoutPass ?? 0];
+    const earlyExit = () => baseParts.trainTotal > 0 &&
+        baseParts.trainPass === baseParts.trainTotal &&
+        (baseParts.holdoutPass === null || (baseParts.holdoutTotal > 0 && baseParts.holdoutPass === baseParts.holdoutTotal));
+    if (earlyExit()) {
+        opts.onIteration?.(0, maxIterations, '当前 description 在 train + holdout 全通过,无需进化。');
+    }
+    for (let iter = 1; iter <= maxIterations && !earlyExit(); iter++) {
+        opts.onIteration?.(iter, maxIterations, `第 ${iter}/${maxIterations} 轮:提案新 description…`);
+        const prompt = buildImprovePrompt(skill, baseDescription, failingCases(baseReport), rejected);
+        let candidate;
+        try {
+            candidate = await proposeDescription(prompt, opts.proposeTimeoutMs ?? 120_000, opts.signal);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            opts.onIteration?.(iter, maxIterations, `提案失败(${msg.slice(0, 120)}),终止。`);
+            break;
+        }
+        if (!candidate || candidate === baseDescription) {
+            opts.onIteration?.(iter, maxIterations, '提案无效(空/超长/与当前相同),终止。');
+            break;
+        }
+        const candReport = await runTriggerEval(skill, candidate, evalSet, runsPerQuery, threshold, evalOpts);
+        const candParts = partitionReport(candReport, trainQueries);
+        const gate = shouldAcceptCandidate(baseParts, candParts);
+        const iteration = {
+            iteration: iter,
+            description: candidate,
+            trainPass: candParts.trainPass,
+            trainTotal: candParts.trainTotal,
+            holdoutPass: candParts.holdoutPass,
+            holdoutTotal: candParts.holdoutTotal,
+            accepted: gate.accept,
+            reason: gate.reason,
+        };
+        iterations.push(iteration);
+        opts.onIteration?.(iter, maxIterations, `${gate.accept ? '✓ 接受' : '· 拒绝'}: train ${candParts.trainPass}/${candParts.trainTotal}, holdout ${candParts.holdoutPass ?? '-'}/${candParts.holdoutTotal} — ${gate.reason}`);
+        if (gate.accept) {
+            baseDescription = candidate;
+            baseReport = candReport;
+            baseParts = candParts;
+            const key = [candParts.trainPass, candParts.holdoutPass ?? 0];
+            if (key[0] > bestKey[0] || (key[0] === bestKey[0] && key[1] > bestKey[1])) {
+                bestKey = key;
+                bestDescription = candidate;
+            }
+        }
+        else {
+            rejected.push(candidate);
+            if (rejected.length > 5)
+                rejected.shift();
+        }
+    }
+    return {
+        skill: skill.name,
+        originalDescription: skill.description,
+        bestDescription,
+        improved: bestDescription !== skill.description,
+        iterations,
+    };
+}
+/**
+ * 把进化结果写回 SKILL.md 的 description(唯一的落盘点;CLI --apply 时才调)。
+ * 返回写后的文件内容;frontmatter 无法安全替换时抛错(不落盘)。
+ */
+export function applyImprovedDescription(skill, description) {
+    if (skill.dir === 'builtin')
+        throw new Error('内置 skill 不可修改');
+    if (description.length > MAX_DESCRIPTION_CHARS)
+        throw new Error(`description 超长(>${MAX_DESCRIPTION_CHARS})`);
+    const original = readFileSync(skill.skillMdPath, 'utf8');
+    const next = applyDescription(original, description);
+    if (next === null) {
+        throw new Error('无法定位 SKILL.md frontmatter 的 description 字段,拒绝写回(请手工编辑)');
+    }
+    if (next === original) {
+        throw new Error('写回无变化(description 与当前一致)');
+    }
+    writeFileSync(skill.skillMdPath, next, 'utf8');
+    return next;
+}