@migor/cli 0.7.1 → 0.8.0

package/CHANGELOG.md

@@ -5,6 +5,118 @@
 （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
+
+### 变更
+
+> 本版主题（窗口 `0.7.1 → 0.7.2`，含 #77–#81）：**第九轮评审收口** —— 一条高优先级的
+> **HITL × `sessionStore` 组合破口**（挂起任务恢复后历史翻倍、成功后又把坏会话写回去），
+> 外加六条中/低优先级的静默失效修复；其余是纯结构重构、回归测试补课与依赖升级。
+> **无破坏性变更，不需要改代码**：所有修复都是「旧行为本来就不该那样」。
+> **两处错误归类收紧（记账口径，不是行为变更）**：Anthropic 流内 4xx 不再落成可重试的
+> `server`，异步宿主的 `runTimeoutMs` 超时不再落 `unknown`。宿主若按 `error.type` /
+> `errorKind` / `retryable` 分支（重试、告警、看板），取值会更准 —— 见下方两条。
+> 本条目的多数内容**是在本次发版时回填的**：窗口内 5 个 PR 都没写 CHANGELOG，
+> 条目按各提交正文重建。
+
+### 修复（第九轮评审收口）
+
+- **HITL × `sessionStore`：挂起任务恢复后会话历史翻倍 + 成功后毒化会话**（本版最高优先级）：
+  恢复段曾把 session 再注入 `app.run`，而挂起段落库的 `suspendedMessages` 已含完整历史 ⇒
+  run 层 `loadSession` 又 prepend 一遍（历史翻倍、token 复利）；且成功后 `appendSession`
+  会把含未决 `tool_use` 的整段扩展历史写回会话 —— 该会话**下一轮直接撞 API 400**
+  （孤立 `tool_use` + 连续 assistant）。现在恢复段不再注入 session，会话回写改由
+  `AsyncRunner` 按「本轮用户输入 + 最终回复」补，口径与 `run.ts` 的三条不变量一致。
+- **惰性审批超时 `#expireAndResume` 补重入闸 + 进闸后重读 store**：异步 store 下两个并发
+  `poll` 各拿到一份 `awaiting` 副本 ⇒ 双双填超时拒绝、**双双派发**（同一任务跑两遍）。
+  现在与 `approve` 共用同一把 per-taskId 在飞闸。
+- **MCP StreamableHTTP 连接器不再丢弃 `abandoned`**：`tools/call` 把引擎的「放弃等待」
+  信号透传到在飞 `fetch`（含会话 404 自愈那次重试）—— 裁判放弃后真能掐掉请求，
+  而不是继续在后台烧。stdio 侧 #75 的 `pending` 出簿修复这次补上了回归用例。
+- **Anthropic 流内 `error` 事件的 status 反推补 4xx 档**：`invalid_request_error` /
+  `authentication_error` / `permission_error` / `not_found_error` → 400（归 `api`、
+  **不可重试**），与 `openai.ts` 同口径。此前这些确定性病因落 500 + `retryable:true`，
+  引擎会白重试 3 次（3 次网络请求 + 3 倍等待）。
+- **异步宿主 `runTimeoutMs` 的超时错误不再落 `unknown`**：改用 `core/timeout.ts` 的
+  `TimeoutError`（`code='timeout'`），与引擎工具超时 / MCP 桥兜底同口径。归类由
+  `unknown`（`retryable:false`）变为 `timeout`（`retryable:true`）—— 这只是**记账口径**：
+  超时按定义属可重试故障，框架**不会**因此自动重跑整个 run，要不要重试仍由宿主决定。
+- **`FileTaskStore.save` 改为先落盘、成功后再更新内存**：落盘失败时内存不再推进，
+  避免内存与磁盘两本账、重启后静默回退（`get` / `byIdempotency` 查不到未落盘的记录）。
+- **Anthropic SSE 组装拦畸形 `content_block_start.index`**：超大 index（如 `1e9`）会造出
+  稀疏数组、后续 `for...of` / `reduce` 按 `length` 空转；现在畸形 index（负数 / 非整数 /
+  超上限）响亮抛 `AnthropicApiError(500)`。
+
+### 重构（纯结构，零行为变化）
+
+- `integrations/metrics.ts`（1050 行）→ `metrics-state.ts` / `metrics-render.ts` /
+  `metrics-otlp.ts` / `metrics.ts`（只留选项校验、定时器与组装）；
+  `integrations/mcp.ts`（897 行）→ `mcp-stdio.ts` / `mcp-http.ts` / `mcp.ts`
+  （桥 + 共享 helper + re-export 两个连接器工厂）。**公共面与运行时行为不变**。
+
+### 测试
+
+- 补上 #75 遗留的回归用例：stdio MCP 连接器「裁判放弃等待 ⇒ `pending` 记账出簿」的防泄漏
+  修复此前**没有任何用例守着**（夹具新增 `silentcall` 模式：握手 / `tools/list` 正常、
+  `tools/call` 永不回包）。
+
+### 依赖
+
+- 开发依赖：`@anthropic-ai/sdk` → 0.126.0、`@biomejs/biome` → 2.5.14、
+  `@types/node` → 26.6.1、`zod` → 4.6.5（均不影响运行时面）。
+- 官网（不随包发布）：`astro` → 7.3.3。
+
 ## [0.7.1] - 2026-09-19
 
 ### 变更
@@ -615,7 +727,9 @@
 首个公开发布：`@migor/agentia` + `@migor/cli`（scope `@migor/*`），两包版本同步。
 框架本体单包；CLI 独立成包（workspaces）。
 
-[Unreleased]: https://github.com/retrychx/agentia/compare/v0.7.1...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
 [0.6.3]: https://github.com/retrychx/agentia/releases/tag/v0.6.3

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 报成缺失；
@@ -1237,6 +1257,7 @@ const callable = {
 | 挂起段与恢复段是两棵 trace | 每段执行一棵独立的树（`traceId == runId`），恢复段经根 span 的 `links` 挂到上一段；指标按段计（挂起段算一次 ok 的 run —— 「等人」不算失败，区分看 `stop_reason` attribute） |
 | 审批是 at-least-once | 崩溃发生在「批准后、恢复执行中」时，副作用工具会重执行（与 `resumePending` 续跑同口径）—— 副作用工具自己保证幂等 |
 | 挂起/恢复间预算重新起算 | `maxTotalTokens` / `maxCostUsd` 在恢复段从 0 重新计（新树新账，与 `resumePending` 续跑同口径） |
+| 恢复段的会话回写是进程内快照 | 带 `sessionId` 的任务挂起时，「本轮用户输入」快照只存进程内存（恢复段由 AsyncRunner 自己补写「用户输入 + 最终回复」，不再经 run 层重复拼历史）—— 进程崩在「挂起 → 重启 → approve」之间会**丢这一次会话回写**（会话少一轮，但绝不写进坏历史；审批决定本身已落库） |
 | 嵌套能力内的审批不支持挂起 | @SubAgent / @Skill 子循环里的 `approval: 'required'` 工具无法把整个 run 挂起 —— 子循环挂起会以 `is_error` 交回主 agent（要审批的能力请放主菜单） |
 | 同步 `/run` 撞上审批没人可批 | 同步 RPC 会带着 `stopReason: 'awaiting_approval'` 收尾返回 —— 但响应体（`toHttpBody`）**不含** `suspendedMessages`，也没有任务记录可审批（待决清单只能去 trace 的 `approval.requested` 事件里看）。**要审批请走 `POST /tasks` 异步宿主** |
 | Scheduler 调度表不落库 | `every` / `at` 的调度本身只在内存：已 submit 的任务记录能经 `resumePending` 续跑，但「未来某刻再触发」的调度在重启后不存在（远期单发由宿主自己的 cron 驱动）。另：`drain()` 不停 Scheduler —— 停机窗口内到点的 tick 会打一条触发失败日志（无害但吵），介意就 `scheduler.stop()` 先行 |

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,