@migor/cli 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,57 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [0.8.0] - 2026-09-21
+
+### 变更
+
+> 本版主题（窗口 `0.7.2 → 0.8.0`，含 #83–#105）：**CLI 机器可读面 + 脚手架生产路径修复**。
+> 框架运行时 API 零变化；窗口内 23 个提交里 13 个是纯结构拆分（AsyncRunner / turn / loop /
+> http 外移判定面，零行为变化），其余大多是仓库自身的门禁与测试加固。
+> **一条必须看的修复**：用 ≤0.7.2 的 `agentia create` 生成过工程的，
+> `npm run build && npm start` 一跑就崩（discover 目录是 cwd 相对写法，生产形态下会去加载
+> `src/` 的 `.ts` 源码）。缺陷在**生成出来的工程里**，升级 CLI 不会自动修好已有工程 ——
+> 迁移办法见下方「迁移」。
+
+### 新增（CLI）
+
+- **`agentia --version` / `-v`**：打印 CLI 版本（读包自身 `package.json`）。
+- **`report` / `diff` / `doctor` 支持 `--json`**：stdout 只输出一个 JSON 文档，可直接进
+  管道与 CI；出错仍走 stderr + 退出码 1，且 stdout 保持空。`harvest` 刻意不加
+  （它的 stdout 本身就是产物）；`dev` 额外参数原样透传给用户脚本。
+- **脚手架把 `@migor/cli` 写进生成工程的 devDependencies**（与框架同 `^` 版本），`dev`
+  script 改为 `agentia dev`：`npx agentia …` 走本地 bin —— 离线可用，且版本被 pin 住与
+  框架同批（不 pin 的话老工程会被 npx 拉到最新 CLI）。
+
+### 修复
+
+- **脚手架生成工程的 discover 目录按本文件位置解析，不再是 cwd 相对字符串**（本版最高
+  优先级）：旧模板生成的工程 `npm run build && npm start` 必崩
+  "Invalid or unexpected token"（生产形态下去加载 `src/` 的 `.ts` 源码，而装饰器不是
+  可擦除语法），换个 cwd 启动连目录都找不到。**0.7.2 及之前所有版本生成的工程都带此
+  缺陷。** 新写法按 `import.meta.url` 相对本文件解析（开发态 `src/`、构建后 `dist/` 都
+  成立），并过滤不存在的分类目录（空分类 tsc 不产出 `dist/<分类>/`，「这类暂时没有能力」
+  不该让启动失败）。
+
+### 迁移
+
+- **用 ≤0.7.2 的 `agentia create` 生成过工程的**：把工程 `src/main.ts` 的 discover 段
+  换成新模板的写法（重新 `agentia create` 一个同名工程对照抄过来即可 —— 核心是目录按
+  `new URL(d + '/', import.meta.url)` 解析 + `existsSync` 过滤这两处）。
+  框架 API 本身无破坏性变更，`@migor/agentia` 与 `@migor/cli` 升到 `^0.8.0` 即可。
+
+### 内部（不影响使用者）
+
+- 纯结构拆分 13 件：AsyncRunner 五步（SlotPool / approval-policy / DrainGate /
+  resume-policy / TaskWaiters）、`turn.ts` 四步、`loop.ts` 三步、`http.ts` 两步 ——
+  判定面有名字、编排留在原处，零行为变化（#85–#100）。
+- Biome 零告警闸门：93 warnings + 12 infos → 0，verify-all 第 1 步与 CI lint job 翻
+  `--error-on-warnings`（#84）。
+- 计时断言不再卡预算边界、改用单调时钟量（#102 / #103）。
+- 覆盖率棘轮门禁（c8：行 95 / 分支 85 / 函数 92）+ e2e-cli 折入「npm pack → 离线安装 →
+  装出来的包真跑最小 run」（#104）。
+- CLI 模板从字符串升级为真文件（`packages/cli/templates/`，生成产物逐字节不变）（#105）。
+
 ## [0.7.2] - 2026-09-20
 
 ### 变更
@@ -676,7 +727,8 @@
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/retrychx/agentia/compare/v0.7.2...HEAD
+[Unreleased]: https://github.com/retrychx/agentia/compare/v0.8.0...HEAD
+[0.8.0]: https://github.com/retrychx/agentia/releases/tag/v0.8.0
 [0.7.2]: https://github.com/retrychx/agentia/releases/tag/v0.7.2
 [0.7.1]: https://github.com/retrychx/agentia/releases/tag/v0.7.1
 [0.7.0]: https://github.com/retrychx/agentia/releases/tag/v0.7.0

package/README.md

@@ -3,26 +3,32 @@
 Agentia 框架的命令行工具：脚手架、能力生成、本地调试与 **trace 观测**。
 
 ```bash
-npm i -g @migor/cli
-
-agentia create my-app          # 脚手架：四分类目录 + src/registry.ts + src/main.ts
-cd my-app && npm install
-agentia g subagent doc-reviewer # 生成能力并自动登记到注册表
-agentia dev                    # tsx watch + 本地 inspector 面板
-agentia doctor                 # 装配体检：未登记 / 悬空能力、命名规范、重复条目
-agentia add <pkg>              # 安装第三方能力包并登记
+npx @migor/cli create my-app       # 脚手架：四分类目录 + src/registry.ts + src/main.ts
+cd my-app && npm install           # 框架与 CLI 都进工程（CLI 在 devDependencies）
+npx agentia g subagent doc-reviewer # 生成能力并自动登记到注册表
+npm run dev                        # = agentia dev：tsx watch + 本地 inspector 面板
+npx agentia doctor                 # 装配体检：未登记 / 悬空能力、命名规范、重复条目
+npx agentia add <pkg>              # 安装第三方能力包并登记
+npx agentia --version              # 版本（= -v）
 ```
 
+> 首次创建必须带 scope（`npx @migor/cli`）—— npm 上另有一个别人的 `agentia` 包。
+> 工程内用短名 `npx agentia` 走的是本地 bin（CLI 已进 `devDependencies`：离线可用、版本与框架同批 pin）。
+> 想全局装：`npm i -g @migor/cli`。
+
 ## 命令
 
 | 命令 | 作用 |
 |---|---|
-| `agentia create <name>` | 脚手架新项目：`src/tools` · `src/skills` · `src/prompts` · `src/subagents` 四分类目录、`src/registry.ts` 注册表、`src/main.ts` 入口、tsconfig |
+| `agentia create <name>` | 脚手架新项目：`src/tools` · `src/skills` · `src/prompts` · `src/subagents` 四分类目录、`src/registry.ts` 注册表、`src/main.ts` 入口、tsconfig。CLI 本身也装进工程的 `devDependencies` |
 | `agentia g <type> <name>` | 生成能力（`tool` / `skill` / `subagent` / `prompt`）到对应分类目录 `src/<分类>/<name>/` 并登记注册表；长文本资产（`system.md` / `asset.md`）一并生成 |
-| `agentia dev` | `tsx watch` 启动 `src/main.ts`，改能力文件自动重启；内建 inspector 面板查看 trace |
-| `agentia doctor` | 纯静态体检，不加载用户代码 |
-| `agentia report <trace.jsonl>` | 从 trace 落盘文件生成调优报告（能力耗时 / 成本 / 错误率排行） |
+| `agentia dev [-- <脚本参数…>]` | `tsx watch` 启动 `src/main.ts`，改能力文件自动重启；内建 inspector 面板查看 trace。额外参数原样透传给脚本（`npm run dev -- "问题"` 就是这么走的） |
+| `agentia doctor [--json]` | 纯静态体检，不加载用户代码。`--json` 出结构化结果（有错误仍退出 1） |
+| `agentia report <trace.jsonl> [--json]` | 从 trace 落盘文件生成调优报告（能力耗时 / 成本 / 错误率排行）。`--json` 出单个 JSON 文档，便于 CI 断言 |
+| `agentia harvest <trace.jsonl>` | trace → eval 用例骨架（`--out` / `--force` / `--failed` / `--limit`）。**无 `--json`**：它的 stdout 本身就是产物 |
+| `agentia diff <a.jsonl> <b.jsonl> [--json]` | 两条 trace 的调用树 A/B 比对（有差异时退出码 1）。`--json` 出结构化差异，退出码语义不变 |
 | `agentia add <pkg>` | 安装第三方能力包（`defineModule` 能力包）并登记到注册表 |
+| `agentia --version` / `-v` | 报出 CLI 版本（读包自身 `package.json`，不另存常量） |
 
 ## 可观测（trace）
 

package/dist/AGENTS.md

@@ -80,16 +80,28 @@ console.log(result.finalText, result.stopReason, result.trace.totalUsage);
 ## 2. 项目结构（CLI 约定）
 
 ```bash
-npx @migor/cli create my-app     # 脚手架（含 .env / .env.example）
-cd my-app && npm install
+npx @migor/cli create my-app     # 首次创建：必须带 scope（短名 agentia 在 npm 上是别人的包）
+cd my-app && npm install         # 框架与 CLI 都装进工程
 $EDITOR .env                     # 填 ANTHROPIC_API_KEY（脚手架已生成，且已被 .gitignore 挡住）
-npx @migor/cli dev               # tsx watch + 本地 inspector 面板
-npx @migor/cli g tool fetch-weather   # 生成到 src/tools/fetch-weather/（skill/prompt/subagent 同理）
-npx @migor/cli doctor            # 静态体检（未登记/悬空/命名/重复）
+npm run dev                      # = agentia dev：tsx watch + 本地 inspector 面板
+npx agentia g tool fetch-weather   # 生成到 src/tools/fetch-weather/（skill/prompt/subagent 同理）
+npx agentia doctor               # 静态体检（未登记/悬空/命名/重复）
+npx agentia --version            # CLI 版本（= -v）
 ```
 
+> **命令从哪来**：脚手架把 `@migor/cli` 装进工程的 `devDependencies`，所以**工程内**用短名
+> `npx agentia …` 即可（走本地 bin：离线可用、版本与工程一同 pin）。**首次创建**必须用带 scope 的
+> `npx @migor/cli create` —— npm 上另有一个别人的 `agentia` 包，短名会装错东西。
+> 想全局装上（到处都能敲 `agentia`）：`npm i -g @migor/cli`。
+
 四分类目录，一能力一文件夹：`src/tools/` · `src/skills/` · `src/prompts/` · `src/subagents/` —— **目录名就是类型**，不用记别名。每个文件夹的 `index.ts` 是入口，`default export` 支持三种形态：**类**（token = 文件夹名）、**Provider 对象**、**Provider 数组**。显式注册表在 `src/registry.ts`（`agentia g` 自动维护，也可手改）。
 
+> **脚手架 `src/main.ts` 怎么找这些目录**：按**本文件位置**解析（`fileURLToPath(new URL('tools/', import.meta.url))`），
+> 所以 dev 解析到 `src/`、`npm run build` 之后解析到 `dist/` —— 从任何目录启动都成立，也不受 cwd 影响。
+> 别改成 cwd 相对写法（形如 `src/tools` 的字符串）：那样 `node dist/main.js` 会去加载 `src/` 下的 `.ts`
+> 源码，而装饰器不是可擦除的类型语法，Node 直接跑不了。空分类目录（还没有该类型的能力 ⇒ 构建后没有
+> 对应 `dist/<分类>/`）要过滤掉，否则 `discover` 会因「显式给出的路径不存在」而报错。
+
 > **陷阱**：装饰器注册表是模块级 `WeakMap`。框架必须是**单一模块实例** —— 混用 `src` 与 `dist`、或在一个仓库里装两份 agentia，会让能力收集为空。让 CLI 生成的 `package.json` 里只依赖一份框架即可。
 
 ---
@@ -772,6 +784,9 @@ console.log(renderRunReport(report));
 
 CLI 侧有薄壳：`agentia report <trace.jsonl>` —— 每行一个 JSON（裸 Trace，或含 `result.trace` /
 `trace` 的 TaskRecord，如 `FileTaskStore` 的导出），跨行按能力合并后打印排行。
+加 `--json` 得到机器可读输出：stdout 只有一个 JSON 文档（`{ file, runs, failed, skippedLines,
+failures, capabilities, totals }`）、没有人类装饰，适合脚本与 CI 断言；出错仍走 stderr
+（`错误：…`）并把退出码置 1、stdout 保持为空 —— 脚本据此区分「有结果」与「没跑成」。
 
 > ⚠️ **单条 run 内样本常 < 5，分位没有意义** —— 所以报告以 `total` / `max` 为主；
 > 要看分位请用 `mergeRunReports` 汇总多条，或用 `metricsSink` 的直方图。
@@ -976,7 +991,12 @@ const c = await app.run(messages); // 起一条新 run，沿着分叉点前的
 
 不落代码也可以直比两份 trace 导出：`agentia diff a.jsonl b.jsonl`（输入形态同 `agentia report`），
 打印 run 级 summary + 逐 span 差异，**有差异时退出码 1**（diff(1) 语义）——可直接进 CI 挡
-「换 prompt / 模型后轨迹漂移」。
+「换 prompt / 模型后轨迹漂移」。`--json` 给出结构化差异（`{ a, b, equal, summary, spans }`，
+每个 span 带 `path` / `missing` / `fields`），**退出码语义不变**（有差异仍为 1）—— 门禁照旧可用，
+只是「差在哪」也能被读。`agentia doctor --json` 同理（体检结果结构化，有错误仍退出 1）。
+
+> `report` / `diff` / `doctor` 支持 `--json`；`harvest` **没有**：它的 stdout 本身就是产物
+> （生成的 eval 文件源码），加 `--json` 会自相矛盾。
 
 - **配对语义**（结构性配对，字段差异不影响配对）：llm.turn 按回合序配对、**忽略 span name** ——
   name 是模型 id，而「换模型重跑」正是 A/B 主用例，按 name 配对会把两侧所有 turn 报成缺失；

package/dist/cli.js

@@ -1,5 +1,7 @@
 #!/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';
@@ -17,14 +19,18 @@ const USAGE = `agentia —— Agentia 框架命令行工具
   agentia g <type> <name>                  在当前目录生成能力（别名：generate）
                                            type: ${CAPABILITY_TYPES.join(' | ')}
   agentia dev                              启动开发模式（tsx watch 热重载 + 本地 inspector 面板）
-  agentia doctor                           装配体检（未登记/悬空能力/命名规范/重复条目）
-  agentia report <trace.jsonl>             从 trace 落盘文件生成调优报告（能力耗时/成本/错误率排行）
+  agentia doctor [--json]                  装配体检（未登记/悬空能力/命名规范/重复条目）
+  agentia report <trace.jsonl> [--json]    从 trace 落盘文件生成调优报告（能力耗时/成本/错误率排行）
   agentia harvest <trace.jsonl>            把线上 trace 翻成 eval 用例骨架
-                                           （[--out <file.ts>] [--failed] [--limit N]）
-  agentia diff <a.jsonl> <b.jsonl>         两条 trace 的调用树 A/B 比对（有差异时退出码 1）
+                                           （[--out <file.ts>] [--force] [--failed] [--limit N]）
+  agentia diff <a.jsonl> <b.jsonl> [--json] 两条 trace 的调用树 A/B 比对（有差异时退出码 1）
   agentia add <pkg>                        安装第三方能力包并登记到 src/registry.ts
   agentia --help                           显示本帮助
+  agentia --version                        显示版本（等价 -v）
 
+--json：report / diff / doctor 的机器可读输出 —— stdout 只有一个 JSON 文档、无人类装饰，
+        便于脚本与 CI 串接；出错仍走 stderr + 退出码 1。（harvest 没有 --json：它的 stdout
+        本身就是产物，即生成的 eval 文件源码。）
 name 规则：小写字母开头的小写 kebab-case（如 hello、doc-reviewer）
 `;
 // 各子命令自己的用法串 —— 同时供 fail() 与「子命令级 --help」使用（单源，不写两遍）。
@@ -38,7 +44,7 @@ const SUB_USAGE = {
     g: G_USAGE,
     generate: G_USAGE,
     dev: '用法：agentia dev',
-    doctor: '用法：agentia doctor',
+    doctor: '用法：agentia doctor [--json]',
     report: REPORT_USAGE,
     harvest: HARVEST_USAGE,
     diff: DIFF_USAGE,
@@ -49,6 +55,20 @@ 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;
@@ -60,6 +80,13 @@ function main(argv) {
         console.log(USAGE);
         return 0;
     }
+    // 版本：`--version` / `-v`。此前只有 `--help`，用户问不出自己装的是哪一版 —— 而本仓库
+    // 把版本纪律做到了发布面+闸门，CLI 却报不出自己的版本，是个说不通的缺口（bug 报告第一句
+    // 就是「你装的哪一版」）。
+    if (command === '--version' || command === '-v') {
+        console.log(readCliVersion());
+        return 0;
+    }
     // 子命令级 --help：此前 `agentia report --help` 会把 --help 当成「要读的文件名」，
     // 用户拿到的是 ENOENT 而不是该命令的用法（report / harvest / diff 尤其需要）。
     const subUsage = SUB_USAGE[command];
@@ -109,14 +136,15 @@ function main(argv) {
         }
     }
     if (command === 'dev') {
-        if (rest.length > 0)
-            return fail(`未知参数：${rest[0]}`);
-        return devServer();
+        // 额外参数透传给用户脚本：脚手架把 `npm run dev` 指向本命令，而工程 README 文档化的
+        // 用法是 `npm run dev -- "你的问题"` —— 参数必须原样传下去，不能当未知参数拒掉。
+        return devServer(rest);
     }
     if (command === 'doctor') {
-        if (rest.length > 0)
-            return fail(`未知参数：${rest[0]}`);
-        return doctor();
+        const extra = rest.filter((a) => a !== '--json');
+        if (extra.length > 0)
+            return fail(`未知参数：${extra[0]}`);
+        return doctor({ json: rest.includes('--json') });
     }
     if (command === 'report') {
         // 异步命令（要 dynamic import 构建期拷进来的聚合实现）：自己设 exitCode，

package/dist/create.js

@@ -79,12 +79,17 @@ export function createProject(name, parent) {
   cd ${dir}
   npm install
   把 API key 填进 .env（已生成，且已被 .gitignore 忽略）
-  npm run dev
+  npm run dev                  # = agentia dev：tsx watch + 本地 inspector 面板
 
 生产构建：npm run build && npm start（tsc → dist/，.md 资产由 scripts/copy-assets.mjs 跟随拷贝）
+          dev 跑 src/、start 跑 dist/ —— 能力目录按文件位置解析，两边都成立。
 
 目录约定：src/tools/ · src/skills/ · src/prompts/ · src/subagents/（一能力一文件夹）
 
+CLI 已装进本工程（devDependencies），所以在工程内直接 npx agentia g / doctor / dev 即可
+（走本地 bin，离线可用、版本与工程一同 pin）。注意创建时要用带 scope 的 npx @migor/cli create
+—— 短名 agentia 在 npm 上是别人的包。
+
 提示：项目内 AGENTS.md 是本框架的使用说明（API 速查 + 已知边界），
       交给 AI 辅助编码时会自动被读，能显著减少猜 API 的错。`);
     return 0;

package/dist/dev.js

@@ -26,7 +26,11 @@ function supportsImport() {
         return minor >= 19;
     return false;
 }
-export function devServer() {
+/**
+ * @param argv 透传给用户脚本的参数（`agentia dev -- "问题"`）。脚手架把 `npm run dev` 指到本
+ *   命令，而工程 README 文档化的用法正是 `npm run dev -- "你的问题"` —— 不能把参数吃掉。
+ */
+export function devServer(argv = []) {
     const cwd = process.cwd();
     const entry = join(cwd, 'src', 'main.ts');
     if (!existsSync(entry)) {
@@ -44,8 +48,9 @@ export function devServer() {
     process.on('SIGINT', forward('SIGINT'));
     process.on('SIGTERM', forward('SIGTERM'));
     const startChild = (env) => {
-        // 参数全是静态字面量（无用户输入）；win32 下经 npmSpawn 走 cmd.exe 包装（见 npm-bin.ts）
-        const spec = npmSpawn('npx', ['tsx', 'watch', 'src/main.ts']);
+        // argv 是用户输入（`npm run dev -- "问题"`）⇒ 正是 npmSpawn 逐参数脱敏的存在理由：
+        // win32 下走 cmd.exe 包装并转义（shell:true 不转义参数，见 npm-bin.ts）
+        const spec = npmSpawn('npx', ['tsx', 'watch', 'src/main.ts', ...argv]);
         child = spawn(spec.command, spec.args, { cwd, stdio: 'inherit', env, ...spec.options });
         child.on('error', (err) => {
             console.error(`错误：启动 dev 失败：${err.message}`);

package/dist/diff.js

@@ -217,7 +217,7 @@ function pushEventDiffs(out, x, y) {
 }
 /* ── 命令本体：两个 JSONL 各取第一条 trace → diff → 人读输出 ──────────────────── */
 /** 用法串（cli.ts 的子命令 `--help` 也从这里取，避免两处各写一份） */
-export const USAGE = '用法：agentia diff <a.jsonl> <b.jsonl>';
+export const USAGE = '用法：agentia diff <a.jsonl> <b.jsonl> [--json]';
 /** 逐行 JSON.parse + extractTrace（同 harvest），取第一条可提取的 trace；坏行跳过计数 */
 async function readFirstTrace(file) {
     let raw;
@@ -254,8 +254,13 @@ function fmtEntry(e) {
 }
 /** 失败一律**抛错**（同 report/harvest 的受理模式）；「有差异」不是错误，就地设 exitCode = 1 */
 export async function diffCommand(args) {
+    // `--json`：机器可读输出（stdout 只有一个 JSON 文档，无任何人类装饰）；退出码语义不变 ——
+    // 有差异仍退出 1（脚本照旧可拿退出码当门禁，`--json` 只是让「差在哪」也能被读）。
+    const json = args.includes('--json');
     const files = [];
     for (const a of args) {
+        if (a === '--json')
+            continue;
         if (a.startsWith('--'))
             throw new Error(`未知参数：${a}\n${USAGE}`);
         files.push(a);
@@ -266,6 +271,23 @@ export async function diffCommand(args) {
     const ra = await readFirstTrace(fileA);
     const rb = await readFirstTrace(fileB);
     const d = diffTraces(ra.trace, rb.trace);
+    if (json) {
+        const payload = {
+            a: { file: fileA, traceId: ra.trace.traceId ?? null, skippedLines: ra.badLines },
+            b: { file: fileB, traceId: rb.trace.traceId ?? null, skippedLines: rb.badLines },
+            equal: d.equal,
+            summary: d.summary,
+            spans: d.spans.map((s) => ({
+                path: s.path,
+                missing: s.a === undefined ? 'a' : s.b === undefined ? 'b' : null,
+                fields: s.fields,
+            })),
+        };
+        process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+        if (!d.equal)
+            process.exitCode = 1;
+        return 0;
+    }
     const badNote = (n) => (n > 0 ? `（跳过无法解析 ${n} 行）` : '');
     const lines = [
         `trace a  ${fileA}（${ra.trace.traceId ?? '(无 traceId)'}）${badNote(ra.badLines)}`,

package/dist/doctor.js

@@ -56,13 +56,30 @@ function parseRegistry(content) {
 }
 /** 分类目录相对注册表的 import 前缀：./tools 等（悬空条目判定用） */
 const LOCAL_PREFIXES = CAPABILITY_DIR_LIST.map((p) => './' + p.replace(/^src\//, '') + '/');
-export function doctor() {
+/**
+ * @param opts.json `--json`：机器可读输出（stdout 只有一个 JSON 文档，无人类横幅）。
+ *   退出码语义不变 —— 有错误仍退出 1。
+ */
+export function doctor(opts = {}) {
+    const json = opts.json === true;
     const cwd = process.cwd();
     // 老布局：先给迁移提示再收工 —— 去扫一个还不存在的新布局只会刷一屏无关警告
     const legacy = legacyLayout(cwd);
     if (legacy) {
+        const hint = legacyMigrationHint(legacy);
+        if (json) {
+            const payload = {
+                ok: [],
+                warnings: [hint],
+                errors: [],
+                legacyLayoutHint: hint,
+                summary: { errors: 0, warnings: 1 },
+            };
+            console.log(JSON.stringify(payload, null, 2));
+            return 0;
+        }
         console.log('agentia doctor —— 装配体检\n');
-        console.log(`  警告：${legacyMigrationHint(legacy)}`);
+        console.log(`  警告：${hint}`);
         console.log('\n体检结果：0 错误，1 警告');
         return 0;
     }
@@ -136,6 +153,20 @@ export function doctor() {
             warnings.push(`${REGISTRY_PATH} 条目 { provide: '${e.token}' } 指向 ${source}，但该目录已不存在（悬空条目，请删除条目或恢复目录）`);
         }
     }
+    if (json) {
+        const payload = {
+            ok: oks,
+            warnings,
+            errors,
+            summary: { errors: errors.length, warnings: warnings.length },
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        if (errors.length > 0) {
+            process.exitCode = 1;
+            return 1;
+        }
+        return 0;
+    }
     console.log('agentia doctor —— 装配体检\n');
     for (const msg of oks)
         console.log(`  ✓ ${msg}`);

package/dist/inspector/fromTrace.js

@@ -59,9 +59,9 @@ function eventToolName(evName, bodyTool, typeMap) {
 /** 事件摘要：input 走 fmtArg（与 span 入参同一形态），output 走文本内容 */
 function eventText(ev) {
   const body = ev.body;
-  if (ev.name === 'tool.input') return fmtArg(body && body.input);
+  if (ev.name === 'tool.input') return fmtArg(body?.input);
   if (ev.name === 'tool.output') {
-    const c = body && body.content;
+    const c = body?.content;
     return typeof c === 'string' ? c : c == null ? '' : JSON.stringify(c);
   }
   return body == null ? '' : typeof body === 'string' ? body : JSON.stringify(body);
@@ -76,7 +76,7 @@ function eventText(ev) {
  * 原文口径统一在 view.js 的 `rawArg`：官网 playground 的模拟回放也要用它，两处一处定义。
  */
 function eventFull(ev) {
-  if (ev.name === 'tool.input') return rawArg(ev.body && ev.body.input);
+  if (ev.name === 'tool.input') return rawArg(ev.body?.input);
   return eventText(ev);
 }
 
@@ -85,7 +85,7 @@ function eventFull(ev) {
  * 返回 false 表示 trace 空、未做任何渲染。
  */
 export function playTrace(view, trace) {
-  const spans = Array.isArray(trace && trace.spans) ? trace.spans : [];
+  const spans = Array.isArray(trace?.spans) ? trace.spans : [];
   if (!spans.length) return false;
 
   const byId = new Map(spans.map((s) => [s.spanId, s]));
@@ -102,7 +102,7 @@ export function playTrace(view, trace) {
     let d = 0;
     let cur = s;
     const seen = new Set();
-    while (cur && cur.parentSpanId && byId.has(cur.parentSpanId) && !seen.has(cur.spanId)) {
+    while (cur?.parentSpanId && byId.has(cur.parentSpanId) && !seen.has(cur.spanId)) {
       seen.add(cur.spanId);
       d += 1;
       cur = byId.get(cur.parentSpanId);
@@ -141,9 +141,9 @@ export function playTrace(view, trace) {
       view.event(
         it.s.spanId,
         it.ev.name,
-        eventToolName(it.ev.name, it.ev.body && it.ev.body.tool, typeMap),
+        eventToolName(it.ev.name, it.ev.body?.tool, typeMap),
         eventText(it.ev),
-        !it.ev.body || it.ev.body.ok !== false,
+        it.ev.body?.ok !== false,
         eventFull(it.ev),
       );
     } else {

package/dist/inspector/summary.js

@@ -40,7 +40,7 @@ export function summarizeTrace(trace) {
     if (v > a.maxMs) a.maxMs = v;
   };
 
-  const spans = (trace && trace.spans) || [];
+  const spans = trace?.spans || [];
   for (const span of spans) {
     if (span.kind === 'capability') {
       const a = get(`${kindOf(span)}:${span.name}`);

package/dist/inspector/trace-view.css

@@ -1,3 +1,5 @@
+/* biome-ignore-all lint/style/noDescendingSpecificity: 同上：规则只比末段标签，.tr-meta / .tr-ev .tr-name 与 .tr-row.error .tr-meta 等的对手选择器结构上不相交（清单见 PR #84） */
+
 /* Agentia trace 调用树样式 —— 从 packages/website/src/styles/global.css 的 .tr-* 段原样抽出。
  * 宿主需提供这些 CSS 变量：--ice（accent）--faint（次要文本）--text（主文本）。
  * 官网用站点调色板；CLI inspector 页面自带同名变量，视觉一致。 */

package/dist/inspector/view.js

@@ -176,16 +176,16 @@ export function createTraceView(rootEl, opts = {}) {
           const cc = node.usage.cacheCreation || 0;
           if (cr || cc) parts.push('cache ↑' + fmtNum(cr) + ' ↓' + fmtNum(cc));
         }
-        if (bad) parts.push((node.error && node.error.type) || 'error');
+        if (bad) parts.push(node.error?.type || 'error');
         meta = parts.join(' · ');
       } else meta = '…';
       const metaEl = el('span', 'tr-meta', meta);
-      if (bad && node.error && node.error.message) metaEl.title = node.error.message;
+      if (bad && node.error?.message) metaEl.title = node.error.message;
       row.appendChild(metaEl);
       rootEl.appendChild(row);
       // 失败原文必须**看得见** —— 只塞进 title（hover 才显）等于没显示。首次运行最常见的失败
       // （没配 API key）就靠这一行定位；单起一行，不去挤占 nowrap 的 span 行。
-      if (bad && node.error && node.error.message) {
+      if (bad && node.error?.message) {
         const errLine = el('div', 'tr-errm');
         errLine.appendChild(el('span', 'tr-pre', branch + '  '));
         errLine.appendChild(el('span', 'tr-errm-msg', node.error.message));

package/dist/inspector-page.html

@@ -52,6 +52,7 @@
       .empty { color: var(--faint); padding: 16px; }
       #ttl { color: var(--faint); margin-bottom: 10px; font-family: var(--mono); font-size: 11.5px; }
       .usage { display: flex; gap: 16px; margin-top: 12px; color: var(--muted); font-family: var(--mono); font-size: 12px; }
+      /* biome-ignore lint/style/noDescendingSpecificity: 本行只颜色/字重，对手是 33 行的 header .live b —— 两者祖先容器不同（.usage 在面板区、.live 在 header），结构上不可能命中同一元素，是规则「只比末段标签」的误报。 */
       .usage b { color: var(--text); font-weight: 500; }
     </style>
   </head>

package/dist/inspector.js

@@ -59,7 +59,7 @@ function summarize(t) {
     const startedAt = root ? root.startedAt : 0;
     const endedAt = root && root.endedAt != null ? root.endedAt : startedAt;
     const u = t.totalUsage || {};
-    const status = t.status || (root && root.status) || 'ok';
+    const status = t.status || root?.status || 'ok';
     return {
         traceId: t.traceId,
         status,

package/dist/report.js

@@ -31,12 +31,16 @@ export function extractTrace(v) {
 }
 /** 打印一张按总耗时降序的能力排行（跨多行记录时按能力合并） */
 /** 用法串（cli.ts 的子命令 `--help` 也从这里取，避免两处各写一份） */
-export const USAGE = '用法：agentia report <trace.jsonl>';
+export const USAGE = '用法：agentia report <trace.jsonl> [--json]';
 export async function reportCommand(args) {
-    const file = args[0];
+    // `--json`：机器可读输出（stdout 只有一个 JSON 文档，无任何人类装饰）—— 便于脚本/CI 串接。
+    // 出错仍走 stderr 的 `错误：…` + 退出码 1、stdout 为空，脚本据此区分「有结果」与「没跑成」。
+    const json = args.includes('--json');
+    const positional = args.filter((a) => a !== '--json');
+    const file = positional[0];
     // 失败一律**抛错**（而不是就地设 process.exitCode）—— 本命令是异步的，
     // 就地设的 exitCode 会被 cli.ts 末尾那句 `process.exitCode = main(...)` 覆盖成 0。
-    if (file === undefined || args.length > 1) {
+    if (file === undefined || positional.length > 1 || file.startsWith('--')) {
         throw new Error(USAGE);
     }
     let raw;
@@ -101,37 +105,54 @@ export async function reportCommand(args) {
         }
     }
     const rows = [...merged.values()].sort((a, b) => b.totalMs - a.totalMs || b.calls - a.calls);
+    const failRows = traces
+        .filter((t) => t.status === 'error')
+        .map((t) => {
+        const spans = (t.spans ?? []);
+        return {
+            traceId: t.traceId ?? null,
+            message: spans.find((s) => s?.error?.message)?.error?.message ?? null,
+        };
+    });
+    const totalMs = rows.reduce((n, r) => n + r.totalMs, 0);
+    const errTotal = rows.reduce((n, r) => n + r.errors, 0);
+    if (json) {
+        const payload = {
+            file,
+            runs: traces.length,
+            failed: traces.length - okRuns,
+            skippedLines: badLines,
+            failures: failRows,
+            capabilities: rows,
+            totals: { totalMs, errors: errTotal, capabilities: rows.length },
+        };
+        console.log(JSON.stringify(payload, null, 2));
+        return 0;
+    }
     const pad = (s, n) => (s.length >= n ? s : s + ' '.repeat(n - s.length));
     const fmtMs = (ms) => (ms >= 1000 ? `${(ms / 1000).toFixed(2)}s` : `${ms}ms`);
     console.log(`trace 文件  ${file}`);
     console.log(`runs       ${traces.length}（失败 ${traces.length - okRuns}）${badLines > 0 ? `  ·  跳过无法解析 ${badLines} 行` : ''}`);
     // 失败 run 要说清原因：只报「失败 N」而不给理由，对调优没用。而且首次运行最常见的失败
     // （没配 API key）恰恰不产出任何 capability 行 —— 会走到下面「没有可归因的能力」提前返回。
-    const failed = traces.filter((t) => t.status === 'error');
-    for (const t of failed.slice(0, 3)) {
-        const spans = (t.spans ?? []);
-        const msg = spans.find((s) => s?.error?.message)?.error?.message;
-        console.log(`  ✗ ${t.traceId ?? '(无 traceId)'}${msg ? `  ${msg}` : ''}`);
+    for (const f of failRows.slice(0, 3)) {
+        console.log(`  ✗ ${f.traceId ?? '(无 traceId)'}${f.message ? `  ${f.message}` : ''}`);
     }
-    if (failed.length > 3)
-        console.log(`  …另有 ${failed.length - 3} 条失败 run`);
+    if (failRows.length > 3)
+        console.log(`  …另有 ${failRows.length - 3} 条失败 run`);
     console.log('');
     if (rows.length === 0) {
         console.log('（没有可归因的能力：这些 trace 里既没有 capability span，也没有 tool.output 事件）');
         return 0;
     }
     console.log(`${pad('capability', 34)} ${pad('calls', 6)} ${pad('err', 5)} ${pad('total', 9)} ${pad('max', 9)} ${pad('tokens', 9)} ${pad('cost', 12)}`);
-    let total = 0;
-    let errs = 0;
     for (const r of rows) {
-        total += r.totalMs;
-        errs += r.errors;
         console.log(`${pad(r.capability, 34)} ${pad(String(r.calls), 6)} ${pad(String(r.errors), 5)} ` +
             `${pad(fmtMs(r.totalMs), 9)} ${pad(fmtMs(r.maxMs), 9)} ` +
             `${pad(r.tokens != null ? String(r.tokens) : '-', 9)} ` +
             `${pad(r.costUsd != null ? r.costUsd.toFixed(6) : '-', 12)}`);
     }
     console.log('');
-    console.log(`合计耗时 ${fmtMs(total)}  ·  失败 ${errs} 次  ·  能力 ${rows.length} 个`);
+    console.log(`合计耗时 ${fmtMs(totalMs)}  ·  失败 ${errTotal} 次  ·  能力 ${rows.length} 个`);
     return 0;
 }