@migor/cli 0.10.3 → 0.10.5

package/dist/cli.js

@@ -1,7 +1,5 @@
 #!/usr/bin/env node
 /** agentia CLI 入口：手写参数解析 + 命令分发（零依赖） */
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
 import { createProject } from './create.js';
 import { generateCapability } from './generate.js';
 import { isCapabilityType, isValidName, CAPABILITY_TYPES } from './templates.js';
@@ -13,22 +11,35 @@ 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';
 import { exportCommand, USAGE as EXPORT_USAGE } from './export.js';
+import { viewCommand, USAGE as VIEW_USAGE } from './view.js';
+import { manifestCommand } from './manifest.js';
+import { readCliVersion } from './version.js';
 const USAGE = `agentia —— Agentia 框架命令行工具
 
-用法：
-  agentia create <name> [--dir <parent>]   创建项目脚手架（目录 <parent|当前目录>/<name>/）
+核心工作流：
+  agentia create <name> [--dir <parent>] [--minimal]
+                                           创建项目（默认完整服务；--minimal = 单文件 + 裸工具）
   agentia g <type> <name>                  在当前目录生成能力（别名：generate）
                                            type: ${CAPABILITY_TYPES.join(' | ')}
   agentia dev [-- "问题"]                   启动开发模式（常驻 runner + 本地 inspector 面板：
                                            在面板里选能力/工作目录、输入 prompt 驱动一次 run，
                                            并看它的调用树；改代码或 .md 自动重启）
   agentia doctor [--json]                  装配体检（未登记/悬空能力/命名规范/重复条目）
-  agentia report <trace.jsonl> [--json]    从 trace 落盘文件生成调优报告（能力耗时/成本/错误率排行）
+  agentia manifest                         真实装配 app → 能力契约 JSON（schema/owner/风险/审批/hash）
+
+观测与调优：
+  agentia view <trace.jsonl>               落盘 trace → 单文件自包含 HTML（离线可开、可转发）
+                                           （[-o <out.html>] [--open] [--raw] [--limit N] [--trace-id <id>]）
+  agentia report <trace.jsonl> [--json]    生成调优报告（能力耗时/成本/错误率排行）
+  agentia diff <a.jsonl> <b.jsonl> [--json] 两条 trace 的调用树 A/B 比对（有差异时退出码 1）
+
+评测与数据：
   agentia harvest <trace.jsonl>            把线上 trace 翻成 eval 用例骨架
                                            （[--out <file.ts>] [--force] [--failed] [--limit N]）
-  agentia diff <a.jsonl> <b.jsonl> [--json] 两条 trace 的调用树 A/B 比对（有差异时退出码 1）
   agentia export <trace.jsonl>             trace 落盘文件 → 训练数据集（JSONL，一行一份 messages）
                                            （[--out <file>] [--ok-only] [--min-score n]）
+
+能力包与其他：
   agentia add <pkg>                        安装第三方能力包并登记到 src/registry.ts
   agentia --help                           显示本帮助
   agentia --version                        显示版本（等价 -v）
@@ -40,7 +51,7 @@ name 规则：小写字母开头的小写 kebab-case（如 hello、doc-reviewer
 `;
 // 各子命令自己的用法串 —— 同时供 fail() 与「子命令级 --help」使用（单源，不写两遍）。
 // report / harvest / diff 的用法串在各自模块里（那里本来就有），此处 import 复用。
-const CREATE_USAGE = '用法：agentia create <name> [--dir <parent>]';
+const CREATE_USAGE = '用法：agentia create <name> [--dir <parent>] [--minimal]';
 const G_USAGE = `用法：agentia g <type> <name>（type: ${CAPABILITY_TYPES.join(' | ')}）`;
 const ADD_USAGE = '用法：agentia add <pkg>（npm 包名或本地包路径）';
 /** 子命令 → 自己的用法串。`--help` 落在子命令上时打它。 */
@@ -50,10 +61,12 @@ const SUB_USAGE = {
     generate: G_USAGE,
     dev: '用法：agentia dev [-- "首次 run 的 prompt"]',
     doctor: '用法：agentia doctor [--json]',
+    manifest: '用法：agentia manifest（真实装配 src/app.ts，不调用模型）',
     report: REPORT_USAGE,
     harvest: HARVEST_USAGE,
     diff: DIFF_USAGE,
     export: EXPORT_USAGE,
+    view: VIEW_USAGE,
     add: ADD_USAGE,
 };
 function fail(message) {
@@ -61,20 +74,6 @@ function fail(message) {
     process.exitCode = 1;
     return 1;
 }
-/**
- * CLI 版本 = 本包 package.json 的 `version`（**单源**：`scripts/check-release.mjs` 已保证它
- * 与根包一致，所以这里不另存一份常量 —— 常量会漂，读到的文件不会）。
- * 源码直跑（`src/cli.ts`）与发布物（`dist/cli.js`）的 `../package.json` 都是包根那一份。
- */
-function readCliVersion() {
-    try {
-        const pkg = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'));
-        return pkg.version ?? 'unknown';
-    }
-    catch {
-        return 'unknown';
-    }
-}
 function checkName(name) {
     if (name === undefined)
         return false;
@@ -103,6 +102,7 @@ function main(argv) {
     if (command === 'create') {
         const name = rest[0];
         let parent;
+        let minimal = false;
         for (let i = 1; i < rest.length; i += 1) {
             if (rest[i] === '--dir') {
                 parent = rest[i + 1];
@@ -110,6 +110,9 @@ function main(argv) {
                     return fail('--dir 需要一个目录参数');
                 i += 1;
             }
+            else if (rest[i] === '--minimal') {
+                minimal = true;
+            }
             else {
                 return fail(`未知参数：${rest[i]}`);
             }
@@ -119,7 +122,7 @@ function main(argv) {
         if (!checkName(name)) {
             return fail(`非法项目名「${name}」：需匹配小写 kebab-case（如 my-app）`);
         }
-        return createProject(name, parent);
+        return createProject(name, parent, { minimal });
     }
     if (command === 'g' || command === 'generate') {
         const [type, name, ...extra] = rest;
@@ -152,6 +155,11 @@ function main(argv) {
             return fail(`未知参数：${extra[0]}`);
         return doctor({ json: rest.includes('--json') });
     }
+    if (command === 'manifest') {
+        if (rest.length > 0)
+            return fail(`未知参数：${rest[0]}`);
+        return manifestCommand();
+    }
     if (command === 'report') {
         // 异步命令（要 dynamic import 构建期拷进来的聚合实现）：自己设 exitCode，
         // 返回值仅表示「已受理」—— 挂着的 Promise 会让 Node 等到它 settle 再退出。
@@ -185,6 +193,14 @@ function main(argv) {
         });
         return 0;
     }
+    if (command === 'view') {
+        // 异步命令（读文件/读构建期资源/写文件）：同 report 的受理模式
+        void viewCommand(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) {

package/dist/create-minimal.js

@@ -0,0 +1,46 @@
+/** create --minimal：单文件 + 裸工具的项目生成（与完整服务模板分文件，避免 create.ts 继续膨胀）。 */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { minimalMainTs, minimalReadme, projectDotEnv, projectDotEnvExample, projectGitignore, projectPackageJson, projectTsconfig, } from './templates.js';
+import { GUIDE_VERSION_MARKER, readCliVersion } from './version.js';
+/** 与完整模板共享依赖和版本 pin，只收敛 scripts。 */
+export function minimalPackageJson(name) {
+    const pkg = JSON.parse(projectPackageJson(name));
+    pkg.scripts = {
+        ...pkg.scripts,
+        dev: 'tsx src/main.ts',
+        build: 'tsc -p tsconfig.json',
+        start: 'node dist/main.js',
+    };
+    delete pkg.scripts['start:prod'];
+    delete pkg.scripts['start:batch'];
+    return `${JSON.stringify(pkg, null, 2)}\n`;
+}
+function write(dir, rel, content) {
+    const file = join(dir, rel);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, content, 'utf8');
+}
+export function createMinimalProject(dir, name, guide) {
+    write(dir, 'package.json', minimalPackageJson(name));
+    write(dir, 'tsconfig.json', projectTsconfig());
+    write(dir, 'src/main.ts', minimalMainTs(name));
+    write(dir, 'README.md', minimalReadme(name));
+    write(dir, '.gitignore', projectGitignore());
+    write(dir, '.env', projectDotEnv());
+    write(dir, '.env.example', projectDotEnvExample());
+    write(dir, 'AGENTS.md', `${GUIDE_VERSION_MARKER(readCliVersion())}\n${guide}`);
+    console.log(`已创建最小项目 ${dir}
+
+后续步骤：
+  cd ${dir}
+  npm install
+  把 API key 填进 .env（已生成，且已被 .gitignore 忽略）
+  npm run dev -- "你的问题"   # 一个入口文件 + 一个裸工具，跑一次并退出
+
+构建后运行：npm run typecheck && npm run build && npm start -- "你的问题"
+
+需要 inspector、能力目录/registry 或 HTTP 服务时，用默认完整模板另建项目：
+  npx @migor/cli create my-service`);
+    return 0;
+}

package/dist/create.js

@@ -4,6 +4,8 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { appTs, batchTs, CAPABILITY_DIR_LIST, cleanMjs, copyAssetsMjs, devConfigTs, emptyRegistryTemplate, mainTs, projectDotEnv, projectDotEnvExample, projectGitignore, projectPackageJson, projectReadme, projectTsconfig, readFileToolIndexTs, REGISTRY_PATH, sessionStoreTs, toolIndexTs, } from './templates.js';
 import { registerCapability } from './registry.js';
+import { GUIDE_VERSION_MARKER, readCliVersion } from './version.js';
+import { createMinimalProject } from './create-minimal.js';
 function write(dir, rel, content) {
     const file = join(dir, rel);
     mkdirSync(dirname(file), { recursive: true });
@@ -27,7 +29,7 @@ function readUsageGuide() {
     }
     throw new Error(`找不到 AI 使用说明（docs/usage-guide.md）。查找过：\n  ${candidates.join('\n  ')}`);
 }
-export function createProject(name, parent) {
+export function createProject(name, parent, options = {}) {
     const dir = resolve(parent ?? process.cwd(), name);
     let guide;
     try {
@@ -52,6 +54,8 @@ export function createProject(name, parent) {
         return 1;
     }
     mkdirSync(dir, { recursive: true });
+    if (options.minimal === true)
+        return createMinimalProject(dir, name, guide);
     write(dir, 'package.json', projectPackageJson(name));
     write(dir, 'tsconfig.json', projectTsconfig());
     // 装配（app.ts）与启动分离：dev 环要复用 app.ts 的工厂，
@@ -88,12 +92,18 @@ export function createProject(name, parent) {
     // 生成 .env 却不忽略它，等于把 key 直接送进用户的第一个 commit。
     write(dir, '.env', projectDotEnv());
     write(dir, '.env.example', projectDotEnvExample());
-    // AI 使用说明：让 Claude Code / Cursor / Copilot 等一进项目就拿到权威 API 速查
-    write(dir, 'AGENTS.md', guide);
+    // AI 使用说明：让 Claude Code / Cursor / Copilot 等一进项目就拿到权威 API 速查。
+    // ⚠️ 头部带一行**版本标记**（2026-10-16 ref-scaffold-observability-gap）：这份说明是
+    // `docs/usage-guide.md` 的**快照**，而 CLI **没有任何命令会更新它** —— 升级框架后它会
+    // 静默过期，偏偏 AI 就是照它写代码的。有了标记，`agentia doctor` 才能把
+    // 「说明是 vX 写的、当前 CLI 是 vY」说出口（此前只能靠人记得对拍）。
+    write(dir, 'AGENTS.md', `${GUIDE_VERSION_MARKER(readCliVersion())}\n${guide}`);
     registerCapability(dir, 'hello', 'tool');
-    // read-file 的构造器要一个工作目录（DI 注入），而 discover 自动注册的 provider
-    // **没有 deps** ⇒ 它必须走显式注册（registry.ts 的 providers 里那个 WORKDIR 是它的依赖）。
-    // 不登记的话 `agentia doctor` 会报「存在但未登记」—— 新生成的工程不该自带一条警告。
+    // read-file 的构造器要一个工作目录（DI 注入）。它的依赖声明**写在能力类上**
+    //（`static readonly deps = ['WORKDIR']`，discover 会带上），所以默认路由（discover）
+    // 下 `app.ts` 不必为它再注册一遍 —— 这里登记是给**显式装配路线**（registry.ts）
+    // 用的：那份 providers 里要带上 deps，顺带也让 `agentia doctor` 不报「存在但未登记」
+    //（新生成的工程不该自带一条警告）。
     registerCapability(dir, 'read-file', 'tool', ['WORKDIR']);
     console.log(`已创建项目 ${dir}
 

package/dist/doctor.js

@@ -3,6 +3,7 @@ import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { CAPABILITY_DIRS, CAPABILITY_DIR_LIST, REGISTRY_PATH, isValidName } from './templates.js';
 import { legacyLayout, legacyMigrationHint } from './layout.js';
+import { GUIDE_VERSION_RE, readCliVersion } from './version.js';
 /** 能力入口候选（须与框架 src/toolkit/discover.ts 的 ENTRY_CANDIDATES 一致） */
 const ENTRY_CANDIDATES = ['index.ts', 'index.mts', 'index.js', 'index.mjs'];
 /**
@@ -153,6 +154,45 @@ export function doctor(opts = {}) {
             warnings.push(`${REGISTRY_PATH} 条目 { provide: '${e.token}' } 指向 ${source}，但该目录已不存在（悬空条目，请删除条目或恢复目录）`);
         }
     }
+    // trace 出口未接 → 警告（2026-10-16 ref-scaffold-observability-gap）。
+    // 框架**刻意不内建**任何出口（spec §9.3，出口只有 `sinks` 这条缝），所以「缝在那儿、
+    // 没人接」不会有任何报错：同步 `/run` 的 trace 随响应回去了，而异步 `/tasks` 的 trace
+    // 落进任务库里**没人导出** —— 等你要查「这个任务为什么慢」时它正好不在。
+    // 判据只认**代码里的** `sinks:`：整行注释掉的不算（那种情况下出口确实没接上）。
+    const appPath = join(cwd, 'src', 'app.ts');
+    if (existsSync(appPath)) {
+        const code = readFileSync(appPath, 'utf8')
+            .split('\n')
+            .filter((l) => !l.trimStart().startsWith('//'))
+            .join('\n');
+        if (/sinks\s*:/.test(code)) {
+            oks.push('src/app.ts：已配 trace 出口（sinks）');
+        }
+        else {
+            warnings.push('src/app.ts 未配 sinks ⇒ trace 没有任何出口（异步 /tasks 的 trace 只会躺在任务库里、没人导出）；' +
+                '接一行 jsonlTraceSink 即可，配方见框架 docs/observability.md');
+        }
+    }
+    // 项目内 AGENTS.md 的版本漂移（2026-10-16 ref-scaffold-observability-gap）：它是 `create` 时
+    // 拷进来的一份**快照**，之后没有任何命令更新它，而 AI 正是照它写代码 ⇒ 框架升级后
+    // 「权威入口」静默过期。有版本标记才对得出来；没标记（旧版脚手架 / 手写）也要说一声。
+    const agentsFile = join(cwd, 'AGENTS.md');
+    if (existsSync(agentsFile)) {
+        const agentsSrc = readFileSync(agentsFile, 'utf8');
+        const marker = agentsSrc.match(GUIDE_VERSION_RE);
+        const current = readCliVersion();
+        if (marker === null) {
+            warnings.push(`AGENTS.md 没有版本标记（旧版脚手架生成或手写）⇒ 无法判断它与当前 CLI（v${current}）` +
+                '是否同一版；升级后它可能与框架 API 已经不一致');
+        }
+        else if (marker[1] !== current) {
+            warnings.push(`AGENTS.md 是 v${marker[1]} 写的，当前 CLI 是 v${current} ⇒ 说明可能已过期` +
+                '（AI 照它写代码）：重新 create 一份，或对照 docs/usage-guide.md 手工更新');
+        }
+        else {
+            oks.push(`AGENTS.md：版本标记与 CLI 一致（v${current}）`);
+        }
+    }
     if (json) {
         const payload = {
             ok: oks,

package/dist/harvest.js

@@ -13,8 +13,13 @@
 import { existsSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { extractTrace } from './report.js';
-/** trace 不记 assistant 文本 —— 脚本 text 块的统一占位（与框架侧同一个词） */
+/** trace 没开 `traceContent`（或该回合确实没说话）时，脚本 text 块的统一占位（与框架侧同一个词） */
 const ASSISTANT_TEXT_PLACEHOLDER = '[harvest] assistant 文本未入 trace';
+/** 取本回合的真实 assistant 文本 —— 只认 opt-in 的 `output.text`（与框架侧逐字同形） */
+function assistantTextOf(turn) {
+    const text = turn.attributes?.['output.text'];
+    return typeof text === 'string' && text !== '' ? text : null;
+}
 /** 任意值 → 字符串（core/json.ts stringifySafe 的移植） */
 function stringifySafe(x) {
     if (typeof x === 'string')
@@ -96,9 +101,15 @@ export function harvestEvalCase(input) {
     let tuSeq = 0;
     const steps = mainTurns.map((turn, i) => {
         const inputs = toolInputsOf(turn);
-        const content = [
-            { type: 'text', text: ASSISTANT_TEXT_PLACEHOLDER },
-        ];
+        const text = assistantTextOf(turn);
+        const content = [];
+        if (text !== null) {
+            content.push({ type: 'text', text });
+        }
+        else if (inputs.length === 0) {
+            // 只有「既没文本又没工具」的终端回合才放占位（与框架侧逐字同步）
+            content.push({ type: 'text', text: ASSISTANT_TEXT_PLACEHOLDER });
+        }
         for (const e of inputs) {
             content.push({
                 type: 'tool_use',
@@ -117,11 +128,20 @@ export function harvestEvalCase(input) {
     });
     const toolSeq = mainTurns.flatMap((t) => toolInputsOf(t).map((e) => e.tool));
     const userText = lastUserText(input.messages);
+    const textTurns = mainTurns.filter((t) => assistantTextOf(t) !== null).length;
     const head = [
         `// ┄┄ harvest 用例骨架：${name}（trace ${oneLine(trace.traceId ?? '')}${input.source ? `，来源 ${oneLine(input.source)}` : ''}）┄┄`,
         '// ⚠️ 脚手架，不是成品 —— 人工核对后再进 CI：',
-        '//   · trace 不记 assistant 文本（llm.turn 只记 usage/事件），脚本里的 text 块是占位；',
     ];
+    if (textTurns > 0) {
+        head.push(`//   · assistant 文本取自 trace 的 output.text（该 run 开了 traceContent: 'full'）` +
+            (textTurns < mainTurns.length
+                ? `；${mainTurns.length - textTurns} 个回合没有文本（纯 tool_use 回合本来就没文本）；`
+                : '；'));
+    }
+    else {
+        head.push("//   · trace 里没有 assistant 文本（该 run 未开 traceContent: 'full'）—— 脚本只含工具调用，", '//     终端回合的 text 是占位；要真文本请在 app 里开 traceContent 后重跑再 harvest；');
+    }
     if (nestedCount > 0) {
         head.push(`//   · 只含主循环 ${mainTurns.length} 个回合；${nestedCount} 个子 agent 嵌套回合已略去`, '//     （嵌套回合不走主循环脚本，scriptedClient 驱动不了它们；要覆盖子 agent 请单独写 eval）；');
     }
@@ -175,8 +195,9 @@ function renderEvalFile(opts) {
         (opts.badLines > 0 ? `，跳过无法解析 ${opts.badLines} 行` : '');
     const cases = opts.cases.map((c) => c.replace(/\n$/, '').replace(/^/gm, '  ')).join(',\n');
     return `// 由 \`agentia harvest\` 生成的 eval 用例脚手架（${note}）
-// ⚠️ 这是脚手架：assistant 文本为占位（trace 不记文本）；每个用例里的 expect 是
-//    从原 trace 抄录的「实际轨迹」—— 发生过 ≠ 应该发生，人工核对后再进 CI。
+// ⚠️ 这是脚手架：assistant 文本视 trace 而定（run 开了 traceContent: 'full' 则取自
+//     output.text，否则只含工具调用）；每个用例里的 expect 是
+//     从原 trace 抄录的「实际轨迹」—— 发生过 ≠ 应该发生，人工核对后再进 CI。
 import assert from 'node:assert/strict';
 import { defineEval, scriptedClient } from '@migor/agentia';
 

package/dist/inspector/fromTrace.js

@@ -93,7 +93,15 @@ function eventFull(ev) {
  */
 export function playTrace(view, trace) {
   const spans = Array.isArray(trace?.spans) ? trace.spans : [];
-  if (!spans.length) return false;
+  // ⚠️ 空 spans 也**必须 reset**：playTrace 的契约是「把这个 view 变成这棵树」——
+  // 直接 return 会把**上一条 trace 的树**留在页面上，而下拉里选中的是这一条
+  // （切换后看到别人的数据，比看到空白更坏；2026-10-21 在 `agentia view` 的多 trace
+  // 下拉里实测到：先选一个正常 trace，再选一个 0 spans 的，树原样不动）。
+  if (!spans.length) {
+    const label = trace?.traceId ? String(trace.traceId) : '空 trace';
+    view.reset(`run · ${label}（无 spans）`);
+    return false;
+  }
 
   const byId = new Map(spans.map((s) => [s.spanId, s]));
   const root = spans.find((s) => s.kind === 'run') || spans[0];