@migor/cli 0.10.2 → 0.10.4

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,33 @@ 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 { 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 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 +49,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` 落在子命令上时打它。 */
@@ -54,6 +63,7 @@ const SUB_USAGE = {
     harvest: HARVEST_USAGE,
     diff: DIFF_USAGE,
     export: EXPORT_USAGE,
+    view: VIEW_USAGE,
     add: ADD_USAGE,
 };
 function fail(message) {
@@ -61,20 +71,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 +99,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 +107,9 @@ function main(argv) {
                     return fail('--dir 需要一个目录参数');
                 i += 1;
             }
+            else if (rest[i] === '--minimal') {
+                minimal = true;
+            }
             else {
                 return fail(`未知参数：${rest[i]}`);
             }
@@ -119,7 +119,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;
@@ -185,6 +185,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/export.js

@@ -130,7 +130,7 @@ export function exportRun(trace) {
             messages.push({ role: 'user', content: results });
         }
     }
-    // 收尾判定（2026-09-27 ⑪）：整棵 trace 一行正文都没有、且本 run 没开 traceContent
+    // 收尾判定（2026-09-27 ref-export-training-data）：整棵 trace 一行正文都没有、且本 run 没开 traceContent
     // ⇒ 缺的不只是「终端回合那句话」：**混合回合**（模型先说一句再调工具）的真实正文同样
     // 不在 trace 里，而只看「本回合有没有 tool_use」是判不出来的（那种回合按定义就是
     // 「本来没文本」）。两条合取才成立：有正文就不标（合成 / 老 trace 也照顾到），
@@ -138,7 +138,7 @@ export function exportRun(trace) {
     if (!anyTextRecorded && !textRecorded && !incomplete.includes('assistant-text')) {
         incomplete.push('assistant-text');
     }
-    // SFT 形状（2026-09-27 ⑫）：末条是 user ⇒ 这条样本**没有 loss 目标**（训练器会静默
+    // SFT 形状（2026-09-27 ref-export-training-data）：末条是 user ⇒ 这条样本**没有 loss 目标**（训练器会静默
     // 丢掉它），而它恰恰是「run 没有终答」的形状（半截 run / 只剩工具往返）。标注出来，
     // 别让下游以为每条都能直接用：`--ok-only` 挡不住它 —— status ok ≠ 有终答。
     if (messages[messages.length - 1]?.role === 'user' &&

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';
 
@@ -276,9 +297,11 @@ export async function harvestCommand(args) {
             (badLines > 0 ? `；另有 ${badLines} 行无法解析` : ''));
     }
     const picked = rows.filter((r) => !onlyFailed || r.failed).slice(0, limit ?? rows.length);
-    const cases = picked.map((r) => harvestEvalCase({
+    const cases = picked.map((r) => 
+    // messages 是 harvestEvalCase 的公共入参（签名不动）⇒ 调用点条件展开，不把 undefined 传进去
+    harvestEvalCase({
         trace: r.trace,
-        messages: r.messages,
+        ...(r.messages !== undefined ? { messages: r.messages } : {}),
         name: `harvest-${r.label}`,
         source: file,
     }));

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];

package/dist/inspector/summary.js

@@ -4,9 +4,22 @@
  * CLI inspector 与官网 playground 共用同一份实现，避免两处聚合口径漂移。
  *
  * 数据来源（与框架侧的具名约定一致）：
- * - `capability` span（skill / subagent）→ 调用耗时与子孙 usage 聚合（tokens / costUsd）；
+ * - `capability` span（skill / subagent）→ 调用耗时与子孙 usage 聚合（tokens / costUsd）。
+ *   ⚠️ **usage 只认顶层 capability**（没有 capability 祖先的）：框架侧 capability.usage
+ *   是其**子孙 llm.turn 的聚合**（`src/engine/tracer.ts`），嵌套时（`@SubAgent` 套
+ *   `@Skill`）外层与内层带着同一批 token ⇒ 逐行累加会重复计数。嵌套行仍计
+ *   calls / errors / 耗时（那是它自己这次调用的真账，不重复），tokens / costUsd
+ *   留给顶层行 —— 各行可加总，与 `src/core/trace.ts`「capability 聚合不进
+ *   totalUsage（避免重复计数）」同一条纪律。没选「从 llm.turn 重新归账」：
+ *   手写 / 外来的 trace 可能只在 capability span 上带 usage（没有嵌套的 llm.turn
+ *   子孙），重算会把这类成本静默清零。
  * - `llm.turn` span 上的 `tool.output` 事件（普通工具不建 span）→ 工具耗时与成败，
- *   读 `body.durationMs` / `body.ok`。
+ *   读 `body.durationMs` / `body.ok`；
+ * - `approval.decided` 事件（**审批不建 span**，G7 护栏）→ `guardrail:<工具名>` 一类的
+ *   等审批时长与被拒次数，读 `body.tool` / `body.approved` / `body.waitedMs`。
+ *   扫面**不限 span kind**：落点因段而异（首段 llm.turn、恢复段 run 根 —— 续跑入口把
+ *   run 根 id 当 turnId），限 kind = 真实 HITL 主流程（挂起 → 人批 → 恢复）零产出；
+ *   不双计：记账点只有一处（executeOneTool），一次决定只记一笔。
  *
  * ⚠️ 单条 run 内样本常 < 5，分位没有意义 —— 排行以 total/max 为主，不给 p50/p95
  * （要看分位请用框架的 `buildRunReport` + `mergeRunReports`）。
@@ -41,6 +54,21 @@ export function summarizeTrace(trace) {
   };
 
   const spans = trace?.spans || [];
+  const byId = new Map();
+  for (const s of spans) if (s && s.spanId != null) byId.set(s.spanId, s);
+  // 该 span 是否嵌套在另一个 capability 之下（沿 parentSpanId 上爬；seen 防手写 trace 的环）
+  const hasCapabilityAncestor = (span) => {
+    let p = span.parentSpanId;
+    const seen = new Set();
+    while (p != null && !seen.has(p)) {
+      seen.add(p);
+      const ps = byId.get(p);
+      if (!ps) return false;
+      if (ps.kind === 'capability') return true;
+      p = ps.parentSpanId;
+    }
+    return false;
+  };
   for (const span of spans) {
     if (span.kind === 'capability') {
       const a = get(`${kindOf(span)}:${span.name}`);
@@ -48,7 +76,7 @@ export function summarizeTrace(trace) {
       if (span.status === 'error') a.errors += 1;
       if (span.endedAt != null) addMs(a, span.endedAt - span.startedAt);
       const u = span.usage;
-      if (u) {
+      if (u && !hasCapabilityAncestor(span)) {
         a.tokens =
           (a.tokens || 0) +
           (u.inputTokens || 0) +
@@ -59,9 +87,28 @@ export function summarizeTrace(trace) {
       }
       continue;
     }
-    if (span.kind !== 'llm.turn') continue;
+    // approval.decided **不限 span kind**（落点因段而异：首段 llm.turn、恢复段 run 根 ——
+    // 续跑入口把 run 根 id 当 turnId，见头注）；tool.output 只在 llm.turn 上。
+    const isTurn = span.kind === 'llm.turn';
     for (const e of span.events || []) {
-      if (e.name !== 'tool.output') continue;
+      if (e.name === 'approval.decided') {
+        // G7 护栏 —— 审批**只是事件**（刻意不建 span），所以它天然不在任何 span 聚合里，
+        // 此前「哪个工具卡在审批上、被拒了几次」在排行上完全看不见。这一类补上它：
+        //   calls     = 走到「决定」这一步的次数（批准或被拒都算）；
+        //   errors    = **被拒**次数（护栏真挡下了几次 —— 它不是系统错误，但那次工具确实没跑）；
+        //   total/max = 等审批时长（事件的 `waitedMs`）。⚠️ 只有宿主回填了 `requestedAt`
+        //               才有这个数 ⇒ 缺就记 0，**不编造**（框架侧刻意不记「没数据」的 0）。
+        // ⚠️ 口径边界：只聚 `approval.decided`。只有 `approval.requested` 而始终没恢复的
+        //   挂起**不产出** guardrail 行 —— 它没有结论、也没有时长，硬记一格等于编账。
+        const b = e.body;
+        if (!b || typeof b !== 'object' || typeof b.tool !== 'string') continue;
+        const ga = get(`guardrail:${b.tool}`);
+        ga.calls += 1;
+        if (b.approved === false) ga.errors += 1;
+        addMs(ga, typeof b.waitedMs === 'number' ? b.waitedMs : 0);
+        continue;
+      }
+      if (!isTurn || e.name !== 'tool.output') continue;
       const b = e.body;
       if (!b || typeof b !== 'object' || typeof b.tool !== 'string') continue;
       const a = get(`tool:${b.tool}`);