@migor/cli 0.6.0 → 0.6.1

package/dist/cli.js

@@ -7,9 +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 { diffCommand } from './diff.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 框架命令行工具
 
 用法：
@@ -27,6 +27,23 @@ const USAGE = `agentia —— Agentia 框架命令行工具
 
 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;
@@ -43,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;
@@ -58,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）`);
         }
@@ -67,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(' | ')}`);
@@ -122,7 +146,7 @@ function main(argv) {
     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/diff.js

@@ -216,7 +216,8 @@ function pushEventDiffs(out, x, y) {
     }
 }
 /* ── 命令本体：两个 JSONL 各取第一条 trace → diff → 人读输出 ──────────────────── */
-const USAGE = '用法：agentia diff <a.jsonl> <b.jsonl>';
+/** 用法串（cli.ts 的子命令 `--help` 也从这里取，避免两处各写一份） */
+export const USAGE = '用法：agentia diff <a.jsonl> <b.jsonl>';
 /** 逐行 JSON.parse + extractTrace（同 harvest），取第一条可提取的 trace；坏行跳过计数 */
 async function readFirstTrace(file) {
     let raw;

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 ? '（仅失败记录）' : '') +

package/dist/report.js

@@ -30,12 +30,14 @@ export function extractTrace(v) {
     return null;
 }
 /** 打印一张按总耗时降序的能力排行（跨多行记录时按能力合并） */
+/** 用法串（cli.ts 的子命令 `--help` 也从这里取，避免两处各写一份） */
+export const USAGE = '用法：agentia report <trace.jsonl>';
 export async function reportCommand(args) {
     const file = args[0];
     // 失败一律**抛错**（而不是就地设 process.exitCode）—— 本命令是异步的，
     // 就地设的 exitCode 会被 cli.ts 末尾那句 `process.exitCode = main(...)` 覆盖成 0。
     if (file === undefined || args.length > 1) {
-        throw new Error('用法：agentia report <trace.jsonl>');
+        throw new Error(USAGE);
     }
     let raw;
     try {
@@ -66,7 +68,17 @@ export async function reportCommand(args) {
             (badLines > 0 ? `；另有 ${badLines} 行无法解析` : ''));
     }
     // 聚合口径与 inspector 面板 / 官网 playground 同源（构建期拷进来的 trace-view 产物）
-    const { summarizeTrace } = (await import(new URL('./inspector/summary.js', import.meta.url).href));
+    // 这份聚合实现由 packages/cli/scripts/copy-assets.mjs 在构建期从 trace-view 产物拷进来。
+    // 缺它只可能是「装坏了」或「直接跑未构建的源码」—— 原始 ERR_MODULE_NOT_FOUND 里全是
+    // dist 内部路径，用户读不出该做什么，故换成带补救动作的报错。
+    let summarizeTrace;
+    try {
+        ({ summarizeTrace } = (await import(new URL('./inspector/summary.js', import.meta.url).href)));
+    }
+    catch (e) {
+        throw new Error(`缺少 CLI 资源（inspector/summary.js）：${e.message}；` +
+            '请重装 @migor/cli 或重新构建（npm run build:cli）');
+    }
     const merged = new Map();
     let okRuns = 0;
     for (const t of traces) {

package/dist/templates.js

@@ -58,9 +58,11 @@ export function projectPackageJson(name) {
         type: 'module',
         scripts: {
             dev: 'tsx src/main.ts',
+            build: 'tsc -p tsconfig.json && node scripts/copy-assets.mjs',
+            start: 'node dist/main.js',
             typecheck: 'tsc --noEmit -p tsconfig.json',
         },
-        dependencies: { '@migor/agentia': '^0.6.0' },
+        dependencies: { '@migor/agentia': '^0.6.1' },
         devDependencies: {
             tsx: '^4.19.0',
             typescript: '^7.0.2',
@@ -76,6 +78,11 @@ export function projectTsconfig() {
             moduleResolution: 'NodeNext',
             lib: ['ES2022'],
             strict: true,
+            // 编译产物落 dist/（npm run build → npm start 跑 dist/main.js）；
+            // .md 文本资产由 scripts/copy-assets.mjs 跟随同相对路径拷过去
+            // （asset(import.meta.url, './x.md') 按**文件位置**解析，.md 必须跟着 .js 走）
+            rootDir: 'src',
+            outDir: 'dist',
             // 框架零运行时依赖（不再有厂商 SDK 经传递链把 @types/node 带进编译程序），
             // node 全局类型必须显式声明
             types: ['node'],
@@ -161,6 +168,13 @@ ANTHROPIC_API_KEY=sk-ant-...
 npm run dev -- "你的问题"
 \`\`\`
 
+## 构建与生产运行
+
+\`\`\`bash
+npm run build   # tsc → dist/ + .md 文本资产跟随拷贝（asset() 按文件位置解析，必须跟着 .js 走）
+npm start -- "你的问题"   # 跑编译产物 dist/main.js（部署/Docker 用这条）
+\`\`\`
+
 也可以用环境变量（适合 CI / 容器）——**真实环境变量优先，不会被 \`.env\` 覆盖**：
 
 \`\`\`bash
@@ -198,6 +212,36 @@ ANTHROPIC_API_KEY=
 # AGENTIA_MODEL=claude-opus-5
 `;
 }
+/** 脚手架的 scripts/copy-assets.mjs：把 src 下的 .md 文本资产拷进 dist/（同相对路径） */
+export function copyAssetsMjs() {
+    return `// 把能力文件夹里的 .md 文本资产拷进 dist/（与编译产物同相对路径）。
+// asset(import.meta.url, './x.md') 按**文件位置**解析，所以 .md 必须跟着 .js 走。
+import { cpSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = fileURLToPath(new URL('.', import.meta.url));
+const srcDir = join(here, '..', 'src');
+const outDir = join(here, '..', 'dist');
+
+function walk(dir) {
+  const out = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...walk(p));
+    else if (e.name.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+let n = 0;
+for (const f of walk(srcDir)) {
+  cpSync(f, join(outDir, f.slice(srcDir.length + 1)));
+  n++;
+}
+console.log(\`[copy-assets] \${n} 个 .md 资产 → dist/\`);
+`;
+}
 // ---------- g 命令能力模板 ----------
 export function toolIndexTs(name) {
     const cls = kebabToPascal(name);

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@migor/cli",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Agentia 框架命令行工具：create 脚手架 + g 能力生成 + dev 本地可观测面板（trace inspector）",
   "type": "module",
   "bin": {
     "agentia": "./dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "CHANGELOG.md"
   ],
   "repository": "retrychx/agentia",
   "homepage": "https://agentia-web.pages.dev",