@migor/cli 0.5.0 → 0.6.1

package/dist/add.js

@@ -3,7 +3,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { registerPackage } from './registry.js';
-import { npmBin } from './npm-bin.js';
+import { npmSpawn } from './npm-bin.js';
 /** 从 add 参数解析真实包名：支持 name[@version]、@scope/name[@version]、本地路径（. / 前缀，或 file: 协议） */
 export function resolvePackageName(arg) {
     // file: 协议（npm install file:./pkg 的写法）先剥前缀，再按本地路径处理
@@ -34,7 +34,10 @@ export function packageNameToToken(pkgName) {
 }
 export function addPackage(arg) {
     const cwd = process.cwd();
-    const r = spawnSync(npmBin('npm'), ['install', arg], { cwd, stdio: 'inherit' });
+    // arg 是用户输入（包名 / 本地路径，可能含空格与 cmd 元字符）——
+    // 必须走 npmSpawn 的逐参数脱敏，不能用 shell:true（Node 对 shell 命令行不做任何转义）
+    const spec = npmSpawn('npm', ['install', arg]);
+    const r = spawnSync(spec.command, spec.args, { cwd, stdio: 'inherit', ...spec.options });
     if (r.error || r.status !== 0) {
         console.error(`错误：npm install ${arg} 失败，src/registry.ts 未改动`);
         process.exitCode = 1;

package/dist/cli.js

@@ -7,8 +7,9 @@ import { RegistryError } from './registry.js';
 import { devServer } from './dev.js';
 import { doctor } from './doctor.js';
 import { addPackage } from './add.js';
-import { reportCommand } from './report.js';
-import { harvestCommand } from './harvest.js';
+import { reportCommand, USAGE as REPORT_USAGE } from './report.js';
+import { harvestCommand, USAGE as HARVEST_USAGE } from './harvest.js';
+import { diffCommand, USAGE as DIFF_USAGE } from './diff.js';
 const USAGE = `agentia —— Agentia 框架命令行工具
 
 用法：
@@ -20,11 +21,29 @@ const USAGE = `agentia —— Agentia 框架命令行工具
   agentia report <trace.jsonl>             从 trace 落盘文件生成调优报告（能力耗时/成本/错误率排行）
   agentia harvest <trace.jsonl>            把线上 trace 翻成 eval 用例骨架
                                            （[--out <file.ts>] [--failed] [--limit N]）
+  agentia diff <a.jsonl> <b.jsonl>         两条 trace 的调用树 A/B 比对（有差异时退出码 1）
   agentia add <pkg>                        安装第三方能力包并登记到 src/registry.ts
   agentia --help                           显示本帮助
 
 name 规则：小写字母开头的小写 kebab-case（如 hello、doc-reviewer）
 `;
+// 各子命令自己的用法串 —— 同时供 fail() 与「子命令级 --help」使用（单源，不写两遍）。
+// report / harvest / diff 的用法串在各自模块里（那里本来就有），此处 import 复用。
+const CREATE_USAGE = '用法：agentia create <name> [--dir <parent>]';
+const G_USAGE = `用法：agentia g <type> <name>（type: ${CAPABILITY_TYPES.join(' | ')}）`;
+const ADD_USAGE = '用法：agentia add <pkg>（npm 包名或本地包路径）';
+/** 子命令 → 自己的用法串。`--help` 落在子命令上时打它。 */
+const SUB_USAGE = {
+    create: CREATE_USAGE,
+    g: G_USAGE,
+    generate: G_USAGE,
+    dev: '用法：agentia dev',
+    doctor: '用法：agentia doctor',
+    report: REPORT_USAGE,
+    harvest: HARVEST_USAGE,
+    diff: DIFF_USAGE,
+    add: ADD_USAGE,
+};
 function fail(message) {
     console.error(`错误：${message}`);
     process.exitCode = 1;
@@ -41,6 +60,13 @@ function main(argv) {
         console.log(USAGE);
         return 0;
     }
+    // 子命令级 --help：此前 `agentia report --help` 会把 --help 当成「要读的文件名」，
+    // 用户拿到的是 ENOENT 而不是该命令的用法（report / harvest / diff 尤其需要）。
+    const subUsage = SUB_USAGE[command];
+    if (subUsage !== undefined && (rest[0] === '--help' || rest[0] === '-h')) {
+        console.log(subUsage);
+        return 0;
+    }
     if (command === 'create') {
         const name = rest[0];
         let parent;
@@ -56,7 +82,7 @@ function main(argv) {
             }
         }
         if (name === undefined)
-            return fail('缺少项目名，用法：agentia create <name> [--dir <parent>]');
+            return fail(`缺少项目名，${CREATE_USAGE}`);
         if (!checkName(name)) {
             return fail(`非法项目名「${name}」：需匹配小写 kebab-case（如 my-app）`);
         }
@@ -65,7 +91,7 @@ function main(argv) {
     if (command === 'g' || command === 'generate') {
         const [type, name, ...extra] = rest;
         if (type === undefined || name === undefined || extra.length > 0) {
-            return fail(`用法：agentia g <type> <name>（type: ${CAPABILITY_TYPES.join(' | ')}）`);
+            return fail(G_USAGE);
         }
         if (!isCapabilityType(type)) {
             return fail(`未知能力类型「${type}」，可选：${CAPABILITY_TYPES.join(' | ')}`);
@@ -109,10 +135,18 @@ function main(argv) {
         });
         return 0;
     }
+    if (command === 'diff') {
+        // 异步命令（读文件）：同 report 的受理模式
+        void diffCommand(rest).catch((e) => {
+            console.error(`错误：${e.message}`);
+            process.exitCode = 1;
+        });
+        return 0;
+    }
     if (command === 'add') {
         const [pkg, ...extra] = rest;
         if (pkg === undefined || extra.length > 0) {
-            return fail('用法：agentia add <pkg>（npm 包名或本地包路径）');
+            return fail(ADD_USAGE);
         }
         try {
             return addPackage(pkg);

package/dist/create.js

@@ -1,8 +1,8 @@
 /** create 命令：生成 Agentia 项目脚手架 */
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { CAPABILITY_DIR_LIST, emptyRegistryTemplate, mainTs, projectDotEnv, projectDotEnvExample, projectGitignore, projectPackageJson, projectReadme, projectTsconfig, REGISTRY_PATH, toolIndexTs, } from './templates.js';
+import { CAPABILITY_DIR_LIST, copyAssetsMjs, emptyRegistryTemplate, mainTs, projectDotEnv, projectDotEnvExample, projectGitignore, projectPackageJson, projectReadme, projectTsconfig, REGISTRY_PATH, toolIndexTs, } from './templates.js';
 import { registerCapability } from './registry.js';
 function write(dir, rel, content) {
     const file = join(dir, rel);
@@ -38,6 +38,14 @@ export function createProject(name, parent) {
         process.exitCode = 1;
         return 1;
     }
+    // 路径存在但不是目录时 readdirSync 会抛原始 ENOTDIR（栈里全是 node:fs 内部帧），
+    // 下面那句友好文案根本轮不到 —— 先判类型（`agentia create my-app` 而 my-app 是
+    // 个文件是常见手误）。
+    if (existsSync(dir) && !statSync(dir).isDirectory()) {
+        console.error(`错误：${dir} 已存在且不是目录`);
+        process.exitCode = 1;
+        return 1;
+    }
     if (existsSync(dir) && readdirSync(dir).length > 0) {
         console.error(`错误：目录 ${dir} 已存在且非空`);
         process.exitCode = 1;
@@ -48,6 +56,7 @@ export function createProject(name, parent) {
     write(dir, 'tsconfig.json', projectTsconfig());
     write(dir, 'src/main.ts', mainTs(name));
     write(dir, 'src/tools/hello/index.ts', toolIndexTs('hello'));
+    write(dir, 'scripts/copy-assets.mjs', copyAssetsMjs());
     write(dir, REGISTRY_PATH, emptyRegistryTemplate());
     write(dir, 'README.md', projectReadme(name));
     write(dir, '.gitignore', projectGitignore());
@@ -72,6 +81,8 @@ export function createProject(name, parent) {
   把 API key 填进 .env（已生成，且已被 .gitignore 忽略）
   npm run dev
 
+生产构建：npm run build && npm start（tsc → dist/，.md 资产由 scripts/copy-assets.mjs 跟随拷贝）
+
 目录约定：src/tools/ · src/skills/ · src/prompts/ · src/subagents/（一能力一文件夹）
 
 提示：项目内 AGENTS.md 是本框架的使用说明（API 速查 + 已知边界），

package/dist/dev.js

@@ -14,7 +14,7 @@ import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { startInspector } from './inspector.js';
-import { npmBin } from './npm-bin.js';
+import { npmSpawn } from './npm-bin.js';
 /** --import 可用性：Node ≥20.6（≥18.19 已回移植） */
 function supportsImport() {
     const [major, minor] = process.versions.node.split('.').map(Number);
@@ -44,7 +44,9 @@ export function devServer() {
     process.on('SIGINT', forward('SIGINT'));
     process.on('SIGTERM', forward('SIGTERM'));
     const startChild = (env) => {
-        child = spawn(npmBin('npx'), ['tsx', 'watch', 'src/main.ts'], { cwd, stdio: 'inherit', env });
+        // 参数全是静态字面量（无用户输入）；win32 下经 npmSpawn 走 cmd.exe 包装（见 npm-bin.ts）
+        const spec = npmSpawn('npx', ['tsx', 'watch', 'src/main.ts']);
+        child = spawn(spec.command, spec.args, { cwd, stdio: 'inherit', env, ...spec.options });
         child.on('error', (err) => {
             console.error(`错误：启动 dev 失败：${err.message}`);
             process.exitCode = 1;

package/dist/diff.js

@@ -0,0 +1,301 @@
+/**
+ * `agentia diff <a.jsonl> <b.jsonl>` —— 两条 trace 的调用树 A/B 比对。
+ *
+ * 两个文件各取第一条可提取的 trace（裸 Trace 或含 result.trace / trace 的记录，
+ * 同 `agentia report` 的输入），跑 diffTraces 后人读输出：run 级 summary + 按 span
+ * 分组的字段级差异。diff(1) 语义：**有差异时退出码 1**（等价 0），便于脚本串接；
+ * 用法/文件错误照旧抛错走受理模式。
+ *
+ * ⚠️ 本文件是 src/engine/trace-diff.ts 的**去类型移植副本** —— CLI 零运行时依赖、
+ * 不能 import 框架，此处是逐行移植（本地保留同名 interface 使函数体逐字同形）；
+ * 逐字对拍守护在 packages/cli/test/diff.test.mjs，**改算法必须两边同步**。
+ */
+import { readFile } from 'node:fs/promises';
+import { extractTrace } from './report.js';
+/* ── 以下是 src/engine/trace-diff.ts 的去类型移植（保持逐字同形）────────────────── */
+/* core/json.ts 两个小工具的移植（diff 依赖它们） */
+/** 任意值 → 字符串：string 原样，其余 JSON.stringify，循环引用等异常回落 String()。 */
+function stringifySafe(x) {
+    if (typeof x === 'string')
+        return x;
+    try {
+        return JSON.stringify(x) ?? String(x);
+    }
+    catch {
+        return String(x);
+    }
+}
+/** 截断到上限字符、超长加省略标记 `…(+N)`。trace 展示（engine/loop）与 replay 共用同一格式。 */
+function truncateWithMark(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…(+${s.length - n})` : s;
+}
+const USAGE_FIELDS = [
+    'inputTokens',
+    'outputTokens',
+    'cacheReadTokens',
+    'cacheCreationTokens',
+    'costEstimate',
+];
+/** 每个 span 的事件差异最多报 20 条，超出记一条 `events` 截断说明 */
+const EVENT_DIFF_LIMIT = 20;
+/** 事件 body 差异值截断上限（body 可能很大，防爆） */
+const DIFF_VALUE_CHARS = 200;
+export function diffTraces(a, b, opts = {}) {
+    const ignoreTiming = opts.ignoreTiming ?? true;
+    const summary = [];
+    if (a.status !== b.status)
+        summary.push({ field: 'status', a: a.status, b: b.status });
+    pushUsageDiffs(summary, 'totalUsage', a.totalUsage, b.totalUsage);
+    const aRoot = a.spans.find((s) => s.spanId === a.rootSpanId);
+    const bRoot = b.spans.find((s) => s.spanId === b.rootSpanId);
+    if (aRoot && bRoot)
+        pushAttrDiffs(summary, aRoot.attributes, bRoot.attributes);
+    const spans = [];
+    const ctx = {
+        aChildren: childrenMap(a),
+        bChildren: childrenMap(b),
+        ignoreTiming,
+        out: spans,
+    };
+    // 根与根无条件配对（一侧连根都没有时记缺侧）
+    if (aRoot || bRoot) {
+        walk(aRoot, bRoot, `run:${(aRoot ?? bRoot).name}`, ctx);
+    }
+    return { equal: summary.length === 0 && spans.length === 0, summary, spans };
+}
+/** parentSpanId → 直接子 span（保 spans 数组插入序，供稳定排序前的同刻次序） */
+function childrenMap(trace) {
+    const map = new Map();
+    for (const s of trace.spans) {
+        if (s.parentSpanId === null)
+            continue;
+        const kids = map.get(s.parentSpanId);
+        if (kids)
+            kids.push(s);
+        else
+            map.set(s.parentSpanId, [s]);
+    }
+    return map;
+}
+function walk(aSpan, bSpan, path, ctx) {
+    const fields = aSpan && bSpan ? diffSpanFields(aSpan, bSpan, ctx.ignoreTiming) : [];
+    // 只收有差异的节点：字段差，或缺侧（整棵子树缺失，一条记录代表整支，不再下钻）
+    if (fields.length > 0 || !aSpan || !bSpan) {
+        ctx.out.push({ path, a: aSpan, b: bSpan, fields });
+    }
+    if (!aSpan || !bSpan)
+        return;
+    const aKids = ctx.aChildren.get(aSpan.spanId) ?? [];
+    const bKids = ctx.bChildren.get(bSpan.spanId) ?? [];
+    for (const pair of pairChildren(aKids, bKids)) {
+        walk(pair.a, pair.b, `${path}/${pair.seg}`, ctx);
+    }
+}
+/**
+ * 配对键：llm.turn 只有 kind（忽略 name —— name 是模型 id，「换模型重跑」是 A/B 主用例，
+ * 按 name 配对会把两侧 turn 全报成缺失；模型差异降格为配对 turn 的 name 字段差）；
+ * 其余 span 按 `kind:name`（skill:foo vs skill:bar 是不同能力，不该配上）。
+ */
+function pairKey(s) {
+    return s.kind === 'llm.turn' ? 'llm.turn' : `${s.kind}:${s.name}`;
+}
+function pairChildren(aKids, bKids) {
+    const keys = [];
+    const seen = new Set();
+    for (const s of [...aKids, ...bKids]) {
+        const k = pairKey(s);
+        if (!seen.has(k)) {
+            seen.add(k);
+            keys.push(k);
+        }
+    }
+    const pairs = [];
+    for (const key of keys) {
+        // 同键孩子按 startedAt 稳定排序（同刻保插入序）后按下标一一配对
+        const as = aKids.filter((s) => pairKey(s) === key).sort((x, y) => x.startedAt - y.startedAt);
+        const bs = bKids.filter((s) => pairKey(s) === key).sort((x, y) => x.startedAt - y.startedAt);
+        const n = Math.max(as.length, bs.length);
+        for (let i = 0; i < n; i++) {
+            const sample = as[i] ?? bs[i];
+            let seg;
+            if (sample.kind === 'llm.turn') {
+                seg = `llm.turn#${i}`;
+            }
+            else {
+                seg = `${sample.kind}:${sample.name}`;
+                if (n > 1)
+                    seg += `#${i}`; // 同键重复时加下标区分
+            }
+            pairs.push({ a: as[i], b: bs[i], seg });
+        }
+    }
+    return pairs;
+}
+/** 两侧都在时的字段级差异（顺序：status / name / error / usage.* / attributes.* / duration / events） */
+function diffSpanFields(a, b, ignoreTiming) {
+    const fields = [];
+    if (a.status !== b.status)
+        fields.push({ field: 'status', a: a.status, b: b.status });
+    if (a.name !== b.name)
+        fields.push({ field: 'name', a: a.name, b: b.name });
+    if (!errorEqual(a.error, b.error))
+        fields.push({ field: 'error', a: a.error, b: b.error });
+    pushUsageDiffs(fields, 'usage', a.usage, b.usage);
+    pushAttrDiffs(fields, a.attributes, b.attributes);
+    if (!ignoreTiming) {
+        // 比时长而非绝对时间戳（未结束为 undefined，与已结束也是差异）
+        const da = a.endedAt === undefined ? undefined : a.endedAt - a.startedAt;
+        const db = b.endedAt === undefined ? undefined : b.endedAt - b.startedAt;
+        if (da !== db)
+            fields.push({ field: 'duration', a: da, b: db });
+    }
+    pushEventDiffs(fields, a.events, b.events);
+    return fields;
+}
+/** error 比 type + message + retryable 三元组 */
+function errorEqual(x, y) {
+    if (!x || !y)
+        return x === y;
+    return x.type === y.type && x.message === y.message && x.retryable === y.retryable;
+}
+/** usage 逐字段比；缺省（undefined）与 0 是不同语义 —— 一侧有一侧无也是差异 */
+function pushUsageDiffs(out, prefix, x, y) {
+    for (const f of USAGE_FIELDS) {
+        const xv = x?.[f];
+        const yv = y?.[f];
+        if (xv !== yv)
+            out.push({ field: `${prefix}.${f}`, a: xv, b: yv });
+    }
+}
+/** attributes 并集逐键比（键序排序，输出确定） */
+function pushAttrDiffs(out, x, y) {
+    const keys = [...new Set([...Object.keys(x), ...Object.keys(y)])].sort();
+    for (const k of keys) {
+        if (x[k] !== y[k])
+            out.push({ field: `attributes.${k}`, a: x[k], b: y[k] });
+    }
+}
+/**
+ * events 序列比：长度不等记一条 `events` 计数差；逐下标比 name 与 body
+ * （body 用 stringifySafe 序列化后比字符串，差异值截断到 200 字符防爆）。
+ * 每个 span 最多报 EVENT_DIFF_LIMIT 条，超出记一条 `events` 截断说明。
+ * event.time 是墙钟字段，永不比。
+ */
+function pushEventDiffs(out, x, y) {
+    let budget = EVENT_DIFF_LIMIT;
+    let omitted = 0;
+    const push = (entry) => {
+        if (budget > 0) {
+            out.push(entry);
+            budget--;
+        }
+        else {
+            omitted++;
+        }
+    };
+    if (x.length !== y.length)
+        push({ field: 'events', a: x.length, b: y.length });
+    const n = Math.min(x.length, y.length);
+    for (let i = 0; i < n; i++) {
+        if (x[i].name !== y[i].name) {
+            push({ field: `events[${i}].name`, a: x[i].name, b: y[i].name });
+        }
+        const bx = stringifySafe(x[i].body);
+        const by = stringifySafe(y[i].body);
+        if (bx !== by) {
+            push({
+                field: `events[${i}].body`,
+                a: truncateWithMark(bx, DIFF_VALUE_CHARS),
+                b: truncateWithMark(by, DIFF_VALUE_CHARS),
+            });
+        }
+    }
+    if (omitted > 0) {
+        const note = `（事件差异超过 ${EVENT_DIFF_LIMIT} 条，另有 ${omitted} 条未列出）`;
+        out.push({ field: 'events', a: note, b: note });
+    }
+}
+/* ── 命令本体：两个 JSONL 各取第一条 trace → diff → 人读输出 ──────────────────── */
+/** 用法串（cli.ts 的子命令 `--help` 也从这里取，避免两处各写一份） */
+export const USAGE = '用法：agentia diff <a.jsonl> <b.jsonl>';
+/** 逐行 JSON.parse + extractTrace（同 harvest），取第一条可提取的 trace；坏行跳过计数 */
+async function readFirstTrace(file) {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch (e) {
+        throw new Error(`读不到文件 ${file}（${e.message}）`);
+    }
+    let badLines = 0;
+    for (const line of raw.split('\n')) {
+        const s = line.trim();
+        if (!s)
+            continue;
+        try {
+            const t = extractTrace(JSON.parse(s));
+            if (t)
+                return { trace: t, badLines };
+            badLines += 1;
+        }
+        catch {
+            badLines += 1;
+        }
+    }
+    throw new Error(`${file} 里没有可识别的 trace（支持裸 Trace 或含 result.trace / trace 的记录）` +
+        (badLines > 0 ? `；另有 ${badLines} 行无法解析` : ''));
+}
+/** 差异值 → 展示串：stringifySafe 序列化（短串直接放），长串截断 200 字符（同 DIFF_VALUE_CHARS） */
+function fmtValue(v) {
+    return truncateWithMark(stringifySafe(v), DIFF_VALUE_CHARS);
+}
+function fmtEntry(e) {
+    return `  ${e.field}: ${fmtValue(e.a)} → ${fmtValue(e.b)}`;
+}
+/** 失败一律**抛错**（同 report/harvest 的受理模式）；「有差异」不是错误，就地设 exitCode = 1 */
+export async function diffCommand(args) {
+    const files = [];
+    for (const a of args) {
+        if (a.startsWith('--'))
+            throw new Error(`未知参数：${a}\n${USAGE}`);
+        files.push(a);
+    }
+    if (files.length !== 2)
+        throw new Error(USAGE);
+    const [fileA, fileB] = files;
+    const ra = await readFirstTrace(fileA);
+    const rb = await readFirstTrace(fileB);
+    const d = diffTraces(ra.trace, rb.trace);
+    const badNote = (n) => (n > 0 ? `（跳过无法解析 ${n} 行）` : '');
+    const lines = [
+        `trace a  ${fileA}（${ra.trace.traceId ?? '(无 traceId)'}）${badNote(ra.badLines)}`,
+        `trace b  ${fileB}（${rb.trace.traceId ?? '(无 traceId)'}）${badNote(rb.badLines)}`,
+    ];
+    if (d.equal) {
+        lines.push('两条 trace 等价（无结构与字段差异）');
+        process.stdout.write(`${lines.join('\n')}\n`);
+        return 0;
+    }
+    lines.push('');
+    if (d.summary.length > 0) {
+        lines.push('run 级差异：');
+        for (const e of d.summary)
+            lines.push(fmtEntry(e));
+    }
+    if (d.spans.length > 0) {
+        if (d.summary.length > 0)
+            lines.push('');
+        lines.push('span 差异：');
+        for (const s of d.spans) {
+            const side = s.a === undefined ? ' (仅存在于 b)' : s.b === undefined ? ' (仅存在于 a)' : '';
+            lines.push(`${s.path}${side}`);
+            for (const e of s.fields)
+                lines.push(fmtEntry(e));
+        }
+    }
+    process.stdout.write(`${lines.join('\n')}\n`);
+    // diff(1) 语义：不同即 1。此刻 cli.ts 末尾的 `process.exitCode = main(...)` 已同步执行完，
+    // 这里的赋值在其后（await 之后），不会被覆盖。
+    process.exitCode = 1;
+    return 0;
+}

package/dist/doctor.js

@@ -5,11 +5,48 @@ import { CAPABILITY_DIRS, CAPABILITY_DIR_LIST, REGISTRY_PATH, isValidName } from
 import { legacyLayout, legacyMigrationHint } from './layout.js';
 /** 能力入口候选（须与框架 src/toolkit/discover.ts 的 ENTRY_CANDIDATES 一致） */
 const ENTRY_CANDIDATES = ['index.ts', 'index.mts', 'index.js', 'index.mjs'];
+/**
+ * 解析 import 绑定子句，产出本文件内可见的标识符。
+ * 覆盖 default / named（含 `as` 别名与 `type` 修饰）/ namespace / 混合形态；
+ * 注册表由 codemod 与人工共同维护，named import 等形态此前被静默跳过（悬空条目漏检）。
+ */
+function boundIdents(clause) {
+    const idents = [];
+    const brace = clause.match(/\{([\s\S]*)\}/);
+    const head = brace ? clause.replace(brace[0], '') : clause;
+    // 括号外部分：default 标识符和/或 `* as Ns`
+    for (const part of head.split(',')) {
+        const p = part.trim().replace(/^type\s+/, '');
+        if (!p)
+            continue;
+        const ns = p.match(/^\*\s+as\s+(\w+)$/);
+        if (ns)
+            idents.push(ns[1]);
+        else if (/^\w+$/.test(p))
+            idents.push(p);
+    }
+    // 括号内 named 列表：`A`、`A as B`、`type A`
+    if (brace) {
+        for (const item of brace[1].split(',')) {
+            const p = item.trim().replace(/^type\s+/, '');
+            if (!p)
+                continue;
+            const as = p.match(/^\w+\s+as\s+(\w+)$/);
+            if (as)
+                idents.push(as[1]);
+            else if (/^\w+$/.test(p))
+                idents.push(p);
+        }
+    }
+    return idents;
+}
 /** 解析 src/registry.ts：imports（标识符 → 来源）+ entries（provide token → useClass 标识符） */
 function parseRegistry(content) {
     const imports = new Map();
-    for (const m of content.matchAll(/^import\s+(\w+)\s+from\s+'([^']+)'/gm)) {
-        imports.set(m[1], m[2]);
+    // 单/双引号、type 修饰、跨行 named 列表都认；副作用 import（无绑定子句）不产生标识符
+    for (const m of content.matchAll(/^import\s+(?:type\s+)?([\s\S]*?)\s+from\s+(['"])([^'"]+)\2/gm)) {
+        for (const ident of boundIdents(m[1]))
+            imports.set(ident, m[3]);
     }
     const entries = [];
     for (const m of content.matchAll(/\{\s*provide:\s*'([^']+)'\s*,\s*useClass:\s*(\w+)/g)) {

package/dist/harvest.js

@@ -6,9 +6,11 @@
  * trace 的 llm.turn 重建），汇总成一个 eval TS 脚手架写到 --out（缺省 stdout）。
  *
  * ⚠️ 用例骨架生成器与框架侧 `src/eval/harvest.ts` 的 `harvestEvalCase` **同源同形** ——
- * CLI 零运行时依赖、不能 import 框架，此处是逐行移植（packages/cli/test/harvest.test.mjs
- * 里有一条「与框架产物逐字一致」的对拍，改生成格式必须两边同步）。
+ * CLI 零运行时依赖、不能 import 框架，此处是去类型移植（正文逐行相同，另有 3 处空值兜底：
+ * `trace.spans ?? []`、`startedAt ?? 0` ×2）。**产物**逐字一致由
+ * packages/cli/test/harvest.test.mjs 的对拍守着（改生成格式必须两边同步）。
  */
+import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { extractTrace } from './report.js';
 /** trace 不记 assistant 文本 —— 脚本 text 块的统一占位（与框架侧同一个词） */
@@ -25,16 +27,26 @@ function stringifySafe(x) {
     }
 }
 function toolInputsOf(turn) {
-    return (turn.events ?? [])
-        .filter((e) => e.name === 'tool.input')
-        .map((e) => {
+    const out = [];
+    for (const e of turn.events ?? []) {
+        if (e.name !== 'tool.input')
+            continue;
         const b = (e.body ?? {});
-        return {
-            tool: typeof b.tool === 'string' ? b.tool : 'unknown',
+        // 缺 `tool` 的事件**跳过**，不回填占位名（与框架侧 src/eval/harvest.ts 逐字同步）：
+        // 伪造的 'unknown' 会在生成的脚本里变成一个真的（且断言必然通过的）工具调用。
+        if (typeof b.tool !== 'string')
+            continue;
+        out.push({
+            tool: b.tool,
             toolUseId: typeof b.tool_use_id === 'string' ? b.tool_use_id : undefined,
             input: b.input === undefined ? undefined : stringifySafe(b.input),
-        };
-    });
+        });
+    }
+    return out;
+}
+/** 注释里只放单行：外来 trace 的 name/source/traceId 含换行会击穿生成物的注释语法 */
+function oneLine(s) {
+    return s.replace(/[\r\n]+/g, ' ');
 }
 function parseToolInput(raw) {
     const s = raw ?? '';
@@ -75,7 +87,7 @@ function lastUserText(messages) {
 /** 与框架侧 harvestEvalCase 逐字同形的生成器（见文件头注释的对拍测试） */
 export function harvestEvalCase(input) {
     const { trace } = input;
-    const name = input.name ?? `harvest-${trace.traceId}`;
+    const name = oneLine(input.name ?? `harvest-${trace.traceId}`);
     const spans = trace.spans ?? [];
     const mainTurns = spans
         .filter((s) => s.kind === 'llm.turn' && s.parentSpanId === trace.rootSpanId)
@@ -106,7 +118,7 @@ export function harvestEvalCase(input) {
     const toolSeq = mainTurns.flatMap((t) => toolInputsOf(t).map((e) => e.tool));
     const userText = lastUserText(input.messages);
     const head = [
-        `// ┄┄ harvest 用例骨架：${name}（trace ${trace.traceId}${input.source ? `，来源 ${input.source}` : ''}）┄┄`,
+        `// ┄┄ harvest 用例骨架：${name}（trace ${oneLine(trace.traceId ?? '')}${input.source ? `，来源 ${oneLine(input.source)}` : ''}）┄┄`,
         '// ⚠️ 脚手架，不是成品 —— 人工核对后再进 CI：',
         '//   · trace 不记 assistant 文本（llm.turn 只记 usage/事件），脚本里的 text 块是占位；',
     ];
@@ -156,7 +168,8 @@ function toRow(v, index) {
         label: t.traceId ?? `row-${index + 1}`,
     };
 }
-const USAGE = '用法：agentia harvest <trace.jsonl> [--out <file.ts>] [--failed] [--limit N]';
+/** 用法串（cli.ts 的子命令 `--help` 也从这里取，避免两处各写一份） */
+export const USAGE = '用法：agentia harvest <trace.jsonl> [--out <file.ts>] [--force] [--failed] [--limit N]';
 function renderEvalFile(opts) {
     const note = `来源：${opts.file}，${opts.cases.length} 条记录${opts.onlyFailed ? '（仅失败）' : ''}` +
         (opts.badLines > 0 ? `，跳过无法解析 ${opts.badLines} 行` : '');
@@ -196,12 +209,16 @@ export async function harvestCommand(args) {
     let file;
     let out;
     let onlyFailed = false;
+    let force = false;
     let limit;
     for (let i = 0; i < args.length; i += 1) {
         const a = args[i];
         if (a === '--failed') {
             onlyFailed = true;
         }
+        else if (a === '--force') {
+            force = true;
+        }
         else if (a === '--out') {
             out = args[i + 1];
             if (out === undefined)
@@ -270,6 +287,11 @@ export async function harvestCommand(args) {
         process.stdout.write(content);
     }
     else {
+        // 产物是「人工核对后再进 CI」的脚手架，它的价值恰恰在用户手改过的断言与 input 上：
+        // 重跑一次就静默抹掉等于毁掉那份人工成果，所以默认拒绝覆盖（要覆盖显式 --force）。
+        if (!force && existsSync(out)) {
+            throw new Error(`${out} 已存在（产物需人工核对，默认不覆盖）；要覆盖请加 --force\n${USAGE}`);
+        }
         await writeFile(out, content, 'utf8');
         console.log(`已写出 ${out}：${picked.length} 个用例骨架` +
             (onlyFailed ? '（仅失败记录）' : '') +