@migor/cli 0.7.2 → 0.8.1

package/CHANGELOG.md

@@ -5,6 +5,109 @@
 （0.x 阶段：minor 可含破坏性变更，每个破坏性变更都在对应版本的「迁移」小节里写明）。
 决策的完整证据链在 `docs/spec.md` §10（带时间线的决策日志）。
 
+## [0.8.1] - 2026-09-21
+
+### 变更
+
+> 本版主题（窗口 `0.8.0 → 0.8.1`，含 #107–#110）：**出站链路传播** —— spec §9.2 那条
+> 「出站传播仍开放」的项收口。**无破坏性变更**：只新增一个公开函数；既有 API、trace 形状、
+> OTLP 导出值与 id 生成本身全部逐字不变（id 投影只是从 `integrations/otlp.ts` 的私有函数
+> **上移到** `core/trace.ts` 成为单一真源，取值一字未改）。
+
+### 新增
+
+- **`currentTraceparent(): string | undefined`**（出站链路传播）：给出**当前调用期** span 的
+  W3C `traceparent`（`00-<32位trace>-<16位span>-00`），自己带在出站请求上（`fetch` 头 / gRPC
+  metadata）。下游若也是 agentia（或任何认 `traceparent` 的服务），就能把「谁触发了这次调用」
+  关联到**具体 span**，而不是只到 run 粒度：
+
+  ```ts
+  import { currentTraceparent } from '@migor/agentia';
+
+  const tp = currentTraceparent();
+  await fetch(url, { headers: { ...(tp ? { traceparent: tp } : {}) } });
+  ```
+
+  粒度：普通工具与 `@Prompt` **不建 span**，取到的是发起它们的那次 `llm.turn`；`@Skill` /
+  `@SubAgent` 方法体内取到的是自己的 `capability` span（内层覆盖外层）。入站那一半
+  （`traceparent` 头 → run 根 `links`）已随 0.6.2 落地，本版把出站补上，跨服务关联从此双向。
+
+### 已知边界（同时写进 `usage-guide` §7）
+
+- **只给读取器，不替你做注入** —— 框架不创建出站请求，注入那一行是宿主的（与「webhook 用
+  sink + 你自己的 `fetch`」同一条既有决策）。
+- `run` 根 span 由 `runAgent` 打开 ⇒ 更早的 `contextInit` / 记忆水合取到 `undefined` —— 那时
+  确实还没有 span 可指，不编造。
+- flags 位恒 `00`：本框架不采样（每次 run 全量记账），不替下游声明「已采样」。
+- id 宽度：内部 id 是 UUID，出站与 OTLP 共用**同一份**投影（trace 去横线 32-hex、span 截
+  16-hex）⇒ 下游收到的 span id 与 collector 里那个**是同一个数**（各写一份会让同一次调用在
+  两个系统里出现两个 span id）。
+
+### 仓库自身（不面向使用者）
+
+- 第七 / 第八轮复审散件沉淀进 `docs/guards.md` 附录 B，并立「多 agent 同仓作业」三条纪律
+  （结论钉 commit / 门禁跑隔离导出树 / 不碰别人的未提交改动）。
+- 出处链更正：spec §10 的「132 条直接用例」→ **127**（逐文件计数，独立复核不可复现 132），
+  全仓口径改引「+140 条（`tests/` 增量）」；覆盖率棘轮分支 85→88 / 函数 92→95。
+- 新增两条守卫并入册：id 投影**单源**（OTLP 与出站必须同一个数）、出站**调用期作用域**
+  （并行不串 / 内层不外泄），两条都做过承重性反向验证。
+- 发布面清单的 lock 项改为**按包名锚定**：裸 `"version"` 计数会被**恰好同版本号的第三方
+  依赖**撞网（本次真发生：`@grpc/proto-loader` 恰好 @0.8.1 ⇒ 闸门报「4 处应为 0.8.1，实际
+  命中 5 处」，读起来像漏项）。夹具同步加了同版本诱饵，断言它既不被替换、也不进网。
+
+**迁移**：无。既有代码不需要任何改动；要开始用出站传播，就在出站请求上加一行 `traceparent`。
+
+## [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 +779,9 @@
 首个公开发布：`@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.1...HEAD
+[0.8.1]: https://github.com/retrychx/agentia/releases/tag/v0.8.1
+[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` 里只依赖一份框架即可。
 
 ---
@@ -666,8 +678,34 @@ runner.submit(msg.value, {
 换宿主这条缝不变：gRPC 宿主把 metadata 的 `traceparent` 翻进 `options.traceContext`，
 见 §6.2「gRPC 宿主」。
 
-> **只做入站**：框架**不生成**出站 `traceparent`（运行中没有「当前 span」这个概念，硬造一个会是假的
-> spanId，比不做更糟）。要从 run 往外传，用结果里的 `runId`（== `traceId`）拼你自己的头，见 §7 已知边界。
+**出站（反过来：你调别人）**：在 run 内用 `currentTraceparent()` 取当前 span 的 W3C 头，
+自己带在出站请求上 —— 下游若也是 agentia（或任何认 `traceparent` 的服务），接到的就是一条指向
+**具体 span**（回合 / 能力调用）的 link，而不是只到 run 粒度：
+
+```ts
+import { currentTraceparent } from '@migor/agentia';
+
+@Tool({ description: '把工单交给订单服务' })
+async placeOrder(input: { sku: string }) {
+  const tp = currentTraceparent();          // 不在 run 内 → undefined（那时不该编一个）
+  const res = await fetch(orderSvc, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...(tp ? { traceparent: tp } : {}) },
+    body: JSON.stringify(input),
+  });
+  return res.json();
+}
+```
+
+- **粒度**：普通工具与 `@Prompt` **不建 span**，它们的「当前 span」就是发起它们的那次 `llm.turn`；
+  `@Skill` / `@SubAgent` 的方法体内则是它自己的 `capability` span。内层覆盖外层。
+- **不自动注入**：框架不创建出站请求，注入那一行是你自己的（同上 `fetch`；gRPC 宿主塞进 metadata）。
+- 与入站同一个格式、同一份 id 投影：`currentTraceparent()` 的输出喂回 `parseTraceparent()` 逐字还原，
+  下游 OTLP 里看到的 span id 与本地 collector 里的是**同一个数**（见 §7 已知边界）。
+
+> **出站的边界（如实）**：`run` 根 span 由 `runAgent` 打开，所以比它更早的环节 ——
+> `contextInit`、记忆水合（`MemoryStore.load`）—— `currentTraceparent()` 返回 `undefined`：
+> 那时确实还没有 span 可指。flags 位恒 `00`（本框架**不采样**，不替下游声明「已采样」）。
 
 #### 指标（从 trace 派生）
 
@@ -772,6 +810,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 +1017,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 报成缺失；
@@ -1230,7 +1276,7 @@ const callable = {
 | `agentia harvest` 的产物是轨迹骨架 | trace **不记 assistant 文本**（llm.turn 只记 usage/事件），故 harvest 用例脚本里的 text 块是占位、预填 `expect` 是从原 trace 抄录的实际轨迹 —— 脚手架不是成品，人工核对后再进 CI（见 §6「线上 trace 回流」） |
 | 分叉重放不是续跑 | `forkMessages` 与 `traceToMessages` / harvest **同源有损**：trace 不记 assistant 文本与 run 原始输入（重放里 assistant 是标注占位、首尾 user 是合成），也不记 blackboard（分叉种子经 `RunInvocationOptions.blackboard` 自带）；它产出喂回 `app.run` 的 messages、起的是**新 run**，不是接着原 run 的循环位置跑 |
 | 评分来自 run 之外 | `Score` 走 run 根 `score` **事件**而非 span 字段（评分通常在 run 跑完后才产生）；`attachScore` 找不到根 span 时静默忽略，多次调用即多条事件（不同维度各记各的） |
-| 链路关联只做**入站** | `traceContext` / `traceparent` 头只把**上游**接进来（run 根的 `links`）；框架**不生成**出站 `traceparent` —— 运行中没有「当前 span」可导出，硬造会给出假 spanId。要从 run 往外传，用 `result.trace.traceId`（== `runId`）自行拼头。另：link 只落在 run 根（子 span 不散），且**一进程内**不跨进程自动传播 —— 队列场景要自己把 `traceContext` 传下去（HTTP 头带走，或随 `TaskRecord.spec.options` 落库） |
+| 链路关联：入站自动、**出站只给读取器** | `traceContext` / `traceparent` 头把**上游**接进来（run 根的 `links`）；出站方向给 `currentTraceparent()`（当前 span 的 W3C 串，回合 / 能力调用粒度），但框架**不替你做注入** —— 它不创建出站请求，那一行由宿主的 `fetch` / metadata 自己写。两个边界：① `run` 根 span 由 `runAgent` 打开 ⇒ 更早的 `contextInit` / 记忆水合取到 `undefined`（那时确实没有 span）；② flags 恒 `00`（本框架不采样）。id 宽度经**同一份投影**压到 16 位（与 OTLP 导出共用，单一真源）—— 故下游收到的 span id 与 collector 里的是同一个数。另：link 只落在 run 根（子 span 不散），且**一进程内**不跨进程自动传播 —— 队列场景要自己把 `traceContext` 传下去（HTTP 头带走，或随 `TaskRecord.spec.options` 落库） |
 | 配额不是框架子系统 | 只给缝（middleware + TraceSink + BudgetGuard），计数放哪（内存 / Redis / DB）与超限怎么办都是你的策略 |
 | 人工审批两种形态 | 进程内闸门用 `middleware`（`await` 决策再放行）；跨进程耐久审批用 `@Tool({ approval: 'required' })` + `POST /tasks/:id/approve`（挂起/恢复，见 §6.6「人工审批」） |
 | 审批超时是**惰性**判定 | `approvalTimeoutMs` 不起定时器：`approve` / `poll` / `resumePending` 读到过期挂起任务时才自动全拒并重派 —— 没人读的任务不会自己超时（要定期扫就调 `resumePending()`） |

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,