@migor/cli 0.5.0 → 0.6.0

package/dist/AGENTS.md

@@ -105,7 +105,7 @@ npx @migor/cli doctor            # 静态体检（未登记/悬空/命名/重复
 | `model` | `ctx.llm()` 的缺省模型 |
 | `maxTokens` | 同上 |
 | `maxIterations` | 同上 |
-| `tools` | `ctx.llm()` 可调工具：**provider token 列表**（复用该 provider 的 `@Tool` 菜单） |
+| `tools` | `ctx.llm()` 可调工具：**provider token 列表**（复用该 provider 的能力菜单），或 `'<token>/<能力名>'` 能力级路径（只引菜单里的单个能力） |
 
 技能方法体拿到的第二参是 `SkillContext`：`ctx.llm({ prompt })` 才会真正调模型（脚本式，调几次由你写死）。
 
@@ -117,7 +117,7 @@ npx @migor/cli doctor            # 静态体检（未登记/悬空/命名/重复
 | `schema` | 主 agent 填给子 agent 的任务入参 schema |
 | `name` | 缺省取方法名 |
 | `system` | 子 agent 的角色提示：`string` / `SystemPrompt` / `(task) => SystemParam` |
-| `tools` | 子 agent 可调工具：**provider token 列表** |
+| `tools` | 子 agent 可调工具：**provider token 列表**，或 `'<token>/<能力名>'` 能力级路径 |
 | `model` | 子 agent 自己的模型 |
 | `maxTokens` | 同上 |
 | `maxIterations` | 同上 |
@@ -251,6 +251,25 @@ result.typed;   // { answer: string } | undefined
 
 模型没提交就是 `undefined`（不是失败）。`stopReason` 仍以 `end_turn` 正常收尾。
 
+### 5.4 消息类型族（自有公共类型，与厂商 SDK 结构兼容）
+
+`messages` 与模型响应的类型是框架**自有定义**（不从 `@anthropic-ai/sdk` 引类型），字段口径与
+Anthropic Messages API 逐字对齐（snake_case），并与 SDK 的对应类型**结构兼容**：
+手里的 `Anthropic.MessageParam[]` 可以直接喂给 `app.run` / `executeRun`；装框架**不会**连带安装厂商 SDK。
+
+| 类型 | 说明 |
+|---|---|
+| `MessageParam` | 请求消息 `{ role, content: string \| ContentBlockParam[] }`（`Role` 含 `'system'`，与 SDK 逐字对齐；发给端点仍是 user/assistant 语义） |
+| `ContentBlockParam` | 请求块联合：text / image / tool_use / tool_result + `{ type: string }` 兜底成员（厂商新块型原样携带，读字段先按 `type` 收窄） |
+| `Message` | 模型响应（`finalMessage()` 的产物）：`{ id, type, role, content, model, stop_reason, stop_sequence, usage }` |
+| `ContentBlock` | 响应块联合：text / tool_use / thinking + `{ type: string }` 兜底成员 |
+| `ToolParam` | 发给模型的工具定义（**避让 @Tool 装饰器**，故不叫 Tool） |
+| `MessageUsage` | 响应的 token 计量（**避让 trace 的 `Usage`**，故不叫 Usage） |
+| `TextBlockParam` / `ImageBlockParam` / `ToolUseBlockParam` / `ToolResultBlockParam` | 请求侧具体块（与 SDK 同名类型逐字对齐） |
+| `TextBlock` / `ToolUseBlock` / `ThinkingBlock` / `CacheControl` / `Role` | 响应侧具体块 / cache 断点标记 / 角色联合 |
+
+注意命名避让：`Tool` 是装饰器、`Usage` 是 trace 的聚合用量（camelCase）—— 消息侧对应物分别是 `ToolParam` 与 `MessageUsage`（snake_case）。
+
 ---
 
 ## 6. 运行时 API
@@ -410,7 +429,7 @@ process.on('SIGTERM', async () => {
 | `mapWithConcurrency` | 有界并发 map（结果保序）；`maxToolConcurrency` 的底座，也可自用 |
 
 - **取消**：`app.run(messages, { signal })` 传 `AbortSignal` —— 框架会 abort 在飞请求（内置 Anthropic / OpenAI 适配器都转发 `signal`），run 以 `stopReason='aborted'` 收尾（算失败）。`createHttpHandler` 已内置「客户端断开即中止」；`AsyncRunner.runTimeoutMs` 到点同样是**真中止**（构造期校验：必须 ≥ 0 的**有限**数 —— NaN/Infinity 会被 `setTimeout` 钳到 1ms，等于每个任务立即超时，故直接抛错；要「不限」传 0 或不设）。
-- **重试**：缺省自动重试可重试失败（429 / 5xx / 连接失败），指数退避 + 抖动。`retry: false` 关闭，或 `retry: { maxAttempts, baseDelayMs, maxDelayMs, jitter, onRetry }` 调参。**只在本次尝试尚未产出任何文本时重试**（已吐出的字无法撤回）。⚠️ 与 SDK 内置重试叠加 —— 建议二选一调（这里 `maxAttempts: 1` 或把 SDK 的 `maxRetries` 调小）。
+- **重试**：缺省自动重试可重试失败（429 / 5xx / 连接失败），指数退避 + 抖动。`retry: false` 关闭，或 `retry: { maxAttempts, baseDelayMs, maxDelayMs, jitter, onRetry }` 调参。**只在本次尝试尚未产出任何文本时重试**（已吐出的字无法撤回）。⚠️ 与底层 client 的内置重试叠加（默认 client 的 `maxRetries` 缺省 2）—— 建议二选一调（这里 `maxAttempts: 1`，或 `createAnthropicClient({ maxRetries: 0 })`）。
 - **流式**：`POST /run` 带 `Accept: text/event-stream` → SSE 逐帧下发（`text.delta` / `run.end` / `error`）；不带该头仍回一元 JSON。
 - **工具超时 / 并发闸门**：`toolTimeoutMs` 超时**不杀 run**（该条 tool_result 记 `is_error`，模型可换路）；`maxToolConcurrency` 给同回合的并行工具设上限（默认全并行）。⚠️ 超时 = **放弃等待**，`AgentTool.run` 没有 signal 参数，**副作用可能已发生** —— 想真停的工具请自行读 `ToolRunContext.signal`。
 
@@ -516,11 +535,13 @@ if (result.stopReason === 'budget_exceeded') console.warn('这次 run 被预算
 
 | API | 说明 |
 |---|---|
-| `createAnthropicClient` | 默认 ModelClient（Anthropic）：自定义只传 `apiKey` / `baseURL`，不必直接依赖厂商 SDK |
+| `createAnthropicClient` | 默认 ModelClient（Anthropic）：自定义只传 `apiKey` / `baseURL`；框架**零运行时依赖**，不装厂商 SDK |
 | `createOpenAIClient` | OpenAI 兼容端点适配（DeepSeek 等；**真流式**、图片块转 `image_url`、cache token 恒 0） |
 | `InMemoryMemoryStore` | 跨 run 的**键值黑板**记忆（`{ store, keys }` 配 `executeRun`） |
 | `InMemorySessionStore` | 跨 run 的**对话历史**（`{ store, id }` 配 `executeRun` / `app.run`）；与前者正交，可同时用 |
 | `traceToMessages` | 把 trace 还原成 messages（重放基底） |
+| `forkMessages` | 分叉重放：在主循环第 `atTurn` 回合之前截断重放历史、拼上 `append` 新消息喂回 `app.run`（「从第 N 回合换个问法重跑」的基底，**不是续跑**） |
+| `diffTraces` | 两条 trace 的 A/B 比对（prompt / 模型实验）：run 级 summary + 逐 span 字段差；纯函数，llm.turn 配对**忽略模型名**，缺省忽略墙钟 |
 | `applyMiddleware` | 手动包裹配置菜单（装配层已自动做） |
 
 ### MCP 桥（MCP 是「工具来源」，不是新机制）
@@ -602,6 +623,48 @@ agentia harvest trace.jsonl --failed --limit 5 --out evals/harvested.ts
   - 预填的 `expect` 是从原 trace **抄录的实际轨迹** —— 发生过 ≠ 应该发生；
   - `EvalCase` 没有 `expect` 字段，粘贴时把断言搬进 `defineEval({ expect })`（脚手架注释会教）。
 
+### prompt / 模型 A/B（trace diff 与分叉重放）
+
+同一份输入跑两条 run（换模型、换 `SystemPrompt` 版本、换 prompt 都行），用 `diffTraces` 比出**结构与成本差**；
+想「从第 3 回合换个问法重跑」，用 `forkMessages` 在分叉点截断、拼上新消息喂回 `app.run`：
+
+```ts
+import { diffTraces, forkMessages } from '@migor/agentia';
+
+// A/B：同输入，只换模型（或换 system 版本），各跑一条
+const a = await app.run(input, { model: 'claude-sonnet-5' });
+const b = await app.run(input, { model: 'claude-opus-5' });
+
+const diff = diffTraces(a.result.trace, b.result.trace);
+// diff.summary：status / totalUsage.* / 根 attributes 差 —— A/B 模型第一眼就看 attributes.model
+// diff.spans：逐 span 字段级差异，path 形如 run:main/llm.turn#0/capability:search
+if (!diff.equal) console.log(diff.summary, diff.spans);
+
+// 分叉重放：在主循环第 3 回合（0-based）之前截断，该回合及其后丢弃，换个问法继续
+const messages = forkMessages(a.result.trace, {
+  atTurn: 3, // 合法范围 0..主循环回合数-1，越界抛可读错误
+  append: [{ role: 'user', content: '换个思路：先给结论，再补证据。' }],
+});
+const c = await app.run(messages); // 起一条新 run，沿着分叉点前的真实 tool 历史继续
+```
+
+不落代码也可以直比两份 trace 导出：`agentia diff a.jsonl b.jsonl`（输入形态同 `agentia report`），
+打印 run 级 summary + 逐 span 差异，**有差异时退出码 1**（diff(1) 语义）——可直接进 CI 挡
+「换 prompt / 模型后轨迹漂移」。
+
+- **配对语义**（结构性配对，字段差异不影响配对）：llm.turn 按回合序配对、**忽略 span name** ——
+  name 是模型 id，而「换模型重跑」正是 A/B 主用例，按 name 配对会把两侧所有 turn 报成缺失；
+  模型差异降格为配对 turn 的 `name` 字段差。capability span 按 `kind:name` 配对
+  （`skill:foo` vs `skill:bar` 是不同能力，不该配上）。一侧多出的调用树记**一条缺侧记录**
+  （`SpanDiff.fields` 为空、`path` 照给），整支子树不再下钻。
+- **墙钟缺省不比**：`ignoreTiming` 缺省 true（A/B 不关心时序）；传 `false` 改比 span 时长
+  （`duration`），绝对时间戳永不比；`traceId` 是身份不是行为，同样永不比。
+- ⚠️ **有损边界（与 `traceToMessages` / harvest 同源）**：trace **不记 assistant 文本与 run 的
+  原始输入** —— 重放里 assistant 是标注占位（非逐字原文）、首尾说明性 user 是合成。
+  因此 `forkMessages` **不是「续跑」**：它产出的是一份喂回 `app.run` / `runAgent` 的 messages，
+  跑的是一条**新 run**，不是接着原 run 的循环位置。分叉的 blackboard 种子由调用方自带
+  （`app.run(messages, { blackboard: {…} })` —— trace 不记 blackboard）。
+
 ### 指标（从 trace 派生）
 
 | API | 说明 |
@@ -878,11 +941,13 @@ const callable = {
 | schema 校验是**子集** | 只覆盖 `type/properties/required/additionalProperties/enum/items`；`format`/`minimum`/`oneOf` 一律放行 |
 | 历史畸形就放弃裁剪 | `trimToolPairs` 遇到非严格交替历史会整体放弃（宁可少裁，也不切出孤立 tool_use 让请求 400） |
 | 缺省内存 store 不淘汰 | 长跑宿主请设 `InMemoryTaskStore({ maxRecords })` 或换 `FileTaskStore` / `SqliteTaskStore` |
-| 能力引用是 provider 粒度 | 子 agent / skill 的 `tools` 写的是 **provider token**，不是单个工具名 |
+| 能力引用两种粒度 | `tools` 写 **provider token** = 整片能力菜单；写 `'<token>/<能力名>'` = 只引单个能力（@Tool/@Skill/@SubAgent/@Prompt 都可点名，装配期校验，名字不存在即抛错并列出可用名单） |
 | 能力名有格式校验 | 装饰器能力名（`name` 或缺省的方法名）必须匹配 `^[A-Za-z0-9_-]{1,64}$`（与 MCP 桥同口径），非法名在 `createApp` **装配期即抛错** —— 含空格/点/中文的名字会让模型 API 400，宁可在启动期拦住 |
 | `discover` 入口会回落 | 能力目录里源码与编译产物并存（`index.ts` + `index.js`）时，首选 `.ts` 加载失败会**回落 `.js` 并 warn** —— 命中的可能是**陈旧编译产物**（刚改过源码时注意）；全部候选都失败才抛错并列出各自原因 |
 | `asset()` 的 rel 必须是相对路径 | 带 scheme（`file:` / `https:` …）的 rel 会让 `new URL(rel, base)` 整个忽略 base（「以为读了能力目录、实际读了别处」），显式抛错；`../` 越出能力目录是**有意放行**（共享资产如 `../../shared/x.md` 是合法用法） |
 | 取消要传进客户端才有效 | 传 `signal` 后框架会 abort 在飞请求（内置 Anthropic / OpenAI 适配器都转发）；不转发 `signal` 的自定义 `ModelClient` 只能「放弃等待」（请求在后台跑完、产物丢弃） |
+| 默认 client 的真端点验证范围 | `e2e:live` 跑在 DeepSeek 的 Anthropic **兼容**端点上；官方 Anthropic 端点的行为差异（thinking 细节、cache TTL 语义、新块型）目前只有本地假端点测试在守 —— 「mock 全绿发现不了厂商真实行为」是本框架自己记过的教训，接入官方端点前自己跑一遍 `npm run e2e:live` |
+| thinking 块「能收、不主动请求」 | 框架**从不**在请求里开 extended thinking；默认 client 能收拼 thinking 块（`signature_delta` 会累积），`redacted_thinking` 与未知块型**原样透传**不丢 —— 但官方 API 的 thinking 回灌要求带合法 `signature`，自定义 client 开 thinking 时自己验证这条链 |
 | 工具阶段的 abort 有盲区 | abort 只在三处被观察：**回合边界 / 在飞模型请求 / 重试退避 sleep**。没设 `toolTimeoutMs` 且工具挂死时，abort 之后 run 也不会返回（工具的 Promise 永不 settle）—— 挂死的工具要么设超时，要么自己读 `ToolRunContext.signal` |
 | 观测失败被吞 | sink 抛错不影响 run（观测是辅助动作）；同理记忆水合/回写失败也不击穿 run |
 | 框架不自动读 .env | 除 `AGENTIA_MODEL`（缺省模型覆盖）与 `OPENAI_API_KEY`（OpenAI 适配器）外，框架自己不去翻环境变量，也不读 `.env`；要读就在启动代码里调 `loadEnvFile()`（脚手架已内置那行），**真实环境变量优先**于文件 |
@@ -902,7 +967,7 @@ const callable = {
 | MCP 的协议层错误框架看不见 | `isError: true` 只有连接器能看见 —— 它必须转成抛错，否则模型收到的是一条「成功」的结果 |
 | MCP 超时同样是「不等了」 | 桥自带的 `timeoutMs` 取消不了 server 侧执行（拿不到取消句柄）；它与 engine 的 `toolTimeoutMs` **双重计时**，谁短谁生效 |
 | MCP 名字可能被归一化 | 原名含 `-` / `.` / 空格 → 进菜单时变成 `_`；回调 server 用的仍是原名（`mcp.tool` attribute 里查得到） |
-| MCP 工具不能进 DI 容器 | 它没有 provider token，也不能被别的能力的 `tools` 引用 —— 引用是 provider 粒度 |
+| MCP 工具不能进 DI 容器 | 它没有 provider token，也不能被别的能力的 `tools` 引用（两种引用粒度都要先有 token） |
 | 指标分位是窗口内精确值 | `*_last{quantile=...}` 只反映最近 `windowSize`（缺省 1024）条样本；要跨实例聚合请用直方图（`*_bucket` / `_sum` / `_count`，累积语义） |
 | 指标是**进程内**累加 | 不做分布式聚合与持久化：多实例各算各的（直方图可相加），重启即清零。要长期保留请把 `render()` 抓走或用 `export:'otlp'` 推给采集端 |
 | OTLP metrics 只推当前累计 | 按 `intervalMs` 周期导出**累积值**（CUMULATIVE），不做增量/背压；导出失败按 `onExportError` 处理（缺省吞掉，不重试、不阻塞 run） |
@@ -912,6 +977,7 @@ const callable = {
 | 能力标签有基数上限 | `labelMode:'capability'`（缺省）+ `maxCapabilities`（缺省 200），超出的能力归入 `capability="__other__"`；`snapshot().droppedCapabilities` 给出被归并的能力个数。要完整明细请用 `buildRunReport`（不设上限） |
 | 提示词版本只是标记 | 框架不存版本库、不回滚：`version` 只落 run 根 attribute；`system` 传已拼好的 `SystemParam` 时无版本可记 |
 | `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 时静默忽略，多次调用即多条事件（不同维度各记各的） |
 | 配额不是框架子系统 | 只给缝（middleware + TraceSink + BudgetGuard），计数放哪（内存 / Redis / DB）与超限怎么办都是你的策略 |
 | 人工介入只到「闸门」 | `middleware` 能 `await` 审批决策再放行；**跨进程挂起/续跑框架不做** —— `RunStatus` 无「待批准」态、循环位置不落库，`traceToMessages` 重放有损，不能拿它假装续跑（要跨重启审批请上工作流引擎）|
@@ -931,7 +997,7 @@ const callable = {
 | `ctx.get('k')` 没有类型 | 没做 `Blackboard` 声明合并（见 5.1） |
 | `result.typed` 是 `unknown` | `resultSchema` 用的是裸 JsonSchema；改 `fromZod<T>`（见 5.3） |
 | TS 里想 `app.my_tool(...)` | 不要这样写：能力由模型选择，不是你的方法。要确定性调用就**直接调类方法** |
-| 子 agent 调不到工具 | `tools` 是 **provider token**（文件夹名）列表，不是工具名 |
+| 子 agent 调不到工具 | `tools` 的元素是 **provider token** 或 `'<token>/<能力名>'` 路径，不是裸工具名（裸名字会按「未注册 provider」在装配期抛错） |
 | 长跑内存涨 | 缺省内存 store 不淘汰；设 `InMemoryTaskStore({ maxRecords })` 或换耐久 store |
 | 鉴权钩子抛错，客户端只看到「未通过鉴权」 | 这是设计：非 `HttpException` 的错误原文只进服务端日志（要回给调用方就抛 `HttpException(status, body)`） |
 | 停机后 `POST /tasks` 回 503 | `drain()` 已被调用（或注入的 runner 已 drain）—— 这是「拒新单」的正常行为，任务没丢 |

package/dist/add.js

@@ -3,7 +3,7 @@ import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { registerPackage } from './registry.js';
-import { npmBin } from './npm-bin.js';
+import { npmSpawn } from './npm-bin.js';
 /** 从 add 参数解析真实包名：支持 name[@version]、@scope/name[@version]、本地路径（. / 前缀，或 file: 协议） */
 export function resolvePackageName(arg) {
     // file: 协议（npm install file:./pkg 的写法）先剥前缀，再按本地路径处理
@@ -34,7 +34,10 @@ export function packageNameToToken(pkgName) {
 }
 export function addPackage(arg) {
     const cwd = process.cwd();
-    const r = spawnSync(npmBin('npm'), ['install', arg], { cwd, stdio: 'inherit' });
+    // arg 是用户输入（包名 / 本地路径，可能含空格与 cmd 元字符）——
+    // 必须走 npmSpawn 的逐参数脱敏，不能用 shell:true（Node 对 shell 命令行不做任何转义）
+    const spec = npmSpawn('npm', ['install', arg]);
+    const r = spawnSync(spec.command, spec.args, { cwd, stdio: 'inherit', ...spec.options });
     if (r.error || r.status !== 0) {
         console.error(`错误：npm install ${arg} 失败，src/registry.ts 未改动`);
         process.exitCode = 1;

package/dist/cli.js

@@ -9,6 +9,7 @@ import { doctor } from './doctor.js';
 import { addPackage } from './add.js';
 import { reportCommand } from './report.js';
 import { harvestCommand } from './harvest.js';
+import { diffCommand } from './diff.js';
 const USAGE = `agentia —— Agentia 框架命令行工具
 
 用法：
@@ -20,6 +21,7 @@ const USAGE = `agentia —— Agentia 框架命令行工具
   agentia report <trace.jsonl>             从 trace 落盘文件生成调优报告（能力耗时/成本/错误率排行）
   agentia harvest <trace.jsonl>            把线上 trace 翻成 eval 用例骨架
                                            （[--out <file.ts>] [--failed] [--limit N]）
+  agentia diff <a.jsonl> <b.jsonl>         两条 trace 的调用树 A/B 比对（有差异时退出码 1）
   agentia add <pkg>                        安装第三方能力包并登记到 src/registry.ts
   agentia --help                           显示本帮助
 
@@ -109,6 +111,14 @@ function main(argv) {
         });
         return 0;
     }
+    if (command === 'diff') {
+        // 异步命令（读文件）：同 report 的受理模式
+        void diffCommand(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/dev.js

@@ -14,7 +14,7 @@ import { existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { startInspector } from './inspector.js';
-import { npmBin } from './npm-bin.js';
+import { npmSpawn } from './npm-bin.js';
 /** --import 可用性：Node ≥20.6（≥18.19 已回移植） */
 function supportsImport() {
     const [major, minor] = process.versions.node.split('.').map(Number);
@@ -44,7 +44,9 @@ export function devServer() {
     process.on('SIGINT', forward('SIGINT'));
     process.on('SIGTERM', forward('SIGTERM'));
     const startChild = (env) => {
-        child = spawn(npmBin('npx'), ['tsx', 'watch', 'src/main.ts'], { cwd, stdio: 'inherit', env });
+        // 参数全是静态字面量（无用户输入）；win32 下经 npmSpawn 走 cmd.exe 包装（见 npm-bin.ts）
+        const spec = npmSpawn('npx', ['tsx', 'watch', 'src/main.ts']);
+        child = spawn(spec.command, spec.args, { cwd, stdio: 'inherit', env, ...spec.options });
         child.on('error', (err) => {
             console.error(`错误：启动 dev 失败：${err.message}`);
             process.exitCode = 1;

package/dist/diff.js

@@ -0,0 +1,300 @@
+/**
+ * `agentia diff <a.jsonl> <b.jsonl>` —— 两条 trace 的调用树 A/B 比对。
+ *
+ * 两个文件各取第一条可提取的 trace（裸 Trace 或含 result.trace / trace 的记录，
+ * 同 `agentia report` 的输入），跑 diffTraces 后人读输出：run 级 summary + 按 span
+ * 分组的字段级差异。diff(1) 语义：**有差异时退出码 1**（等价 0），便于脚本串接；
+ * 用法/文件错误照旧抛错走受理模式。
+ *
+ * ⚠️ 本文件是 src/engine/trace-diff.ts 的**去类型移植副本** —— CLI 零运行时依赖、
+ * 不能 import 框架，此处是逐行移植（本地保留同名 interface 使函数体逐字同形）；
+ * 逐字对拍守护在 packages/cli/test/diff.test.mjs，**改算法必须两边同步**。
+ */
+import { readFile } from 'node:fs/promises';
+import { extractTrace } from './report.js';
+/* ── 以下是 src/engine/trace-diff.ts 的去类型移植（保持逐字同形）────────────────── */
+/* core/json.ts 两个小工具的移植（diff 依赖它们） */
+/** 任意值 → 字符串：string 原样，其余 JSON.stringify，循环引用等异常回落 String()。 */
+function stringifySafe(x) {
+    if (typeof x === 'string')
+        return x;
+    try {
+        return JSON.stringify(x) ?? String(x);
+    }
+    catch {
+        return String(x);
+    }
+}
+/** 截断到上限字符、超长加省略标记 `…(+N)`。trace 展示（engine/loop）与 replay 共用同一格式。 */
+function truncateWithMark(s, n) {
+    return s.length > n ? `${s.slice(0, n)}…(+${s.length - n})` : s;
+}
+const USAGE_FIELDS = [
+    'inputTokens',
+    'outputTokens',
+    'cacheReadTokens',
+    'cacheCreationTokens',
+    'costEstimate',
+];
+/** 每个 span 的事件差异最多报 20 条，超出记一条 `events` 截断说明 */
+const EVENT_DIFF_LIMIT = 20;
+/** 事件 body 差异值截断上限（body 可能很大，防爆） */
+const DIFF_VALUE_CHARS = 200;
+export function diffTraces(a, b, opts = {}) {
+    const ignoreTiming = opts.ignoreTiming ?? true;
+    const summary = [];
+    if (a.status !== b.status)
+        summary.push({ field: 'status', a: a.status, b: b.status });
+    pushUsageDiffs(summary, 'totalUsage', a.totalUsage, b.totalUsage);
+    const aRoot = a.spans.find((s) => s.spanId === a.rootSpanId);
+    const bRoot = b.spans.find((s) => s.spanId === b.rootSpanId);
+    if (aRoot && bRoot)
+        pushAttrDiffs(summary, aRoot.attributes, bRoot.attributes);
+    const spans = [];
+    const ctx = {
+        aChildren: childrenMap(a),
+        bChildren: childrenMap(b),
+        ignoreTiming,
+        out: spans,
+    };
+    // 根与根无条件配对（一侧连根都没有时记缺侧）
+    if (aRoot || bRoot) {
+        walk(aRoot, bRoot, `run:${(aRoot ?? bRoot).name}`, ctx);
+    }
+    return { equal: summary.length === 0 && spans.length === 0, summary, spans };
+}
+/** parentSpanId → 直接子 span（保 spans 数组插入序，供稳定排序前的同刻次序） */
+function childrenMap(trace) {
+    const map = new Map();
+    for (const s of trace.spans) {
+        if (s.parentSpanId === null)
+            continue;
+        const kids = map.get(s.parentSpanId);
+        if (kids)
+            kids.push(s);
+        else
+            map.set(s.parentSpanId, [s]);
+    }
+    return map;
+}
+function walk(aSpan, bSpan, path, ctx) {
+    const fields = aSpan && bSpan ? diffSpanFields(aSpan, bSpan, ctx.ignoreTiming) : [];
+    // 只收有差异的节点：字段差，或缺侧（整棵子树缺失，一条记录代表整支，不再下钻）
+    if (fields.length > 0 || !aSpan || !bSpan) {
+        ctx.out.push({ path, a: aSpan, b: bSpan, fields });
+    }
+    if (!aSpan || !bSpan)
+        return;
+    const aKids = ctx.aChildren.get(aSpan.spanId) ?? [];
+    const bKids = ctx.bChildren.get(bSpan.spanId) ?? [];
+    for (const pair of pairChildren(aKids, bKids)) {
+        walk(pair.a, pair.b, `${path}/${pair.seg}`, ctx);
+    }
+}
+/**
+ * 配对键：llm.turn 只有 kind（忽略 name —— name 是模型 id，「换模型重跑」是 A/B 主用例，
+ * 按 name 配对会把两侧 turn 全报成缺失；模型差异降格为配对 turn 的 name 字段差）；
+ * 其余 span 按 `kind:name`（skill:foo vs skill:bar 是不同能力，不该配上）。
+ */
+function pairKey(s) {
+    return s.kind === 'llm.turn' ? 'llm.turn' : `${s.kind}:${s.name}`;
+}
+function pairChildren(aKids, bKids) {
+    const keys = [];
+    const seen = new Set();
+    for (const s of [...aKids, ...bKids]) {
+        const k = pairKey(s);
+        if (!seen.has(k)) {
+            seen.add(k);
+            keys.push(k);
+        }
+    }
+    const pairs = [];
+    for (const key of keys) {
+        // 同键孩子按 startedAt 稳定排序（同刻保插入序）后按下标一一配对
+        const as = aKids.filter((s) => pairKey(s) === key).sort((x, y) => x.startedAt - y.startedAt);
+        const bs = bKids.filter((s) => pairKey(s) === key).sort((x, y) => x.startedAt - y.startedAt);
+        const n = Math.max(as.length, bs.length);
+        for (let i = 0; i < n; i++) {
+            const sample = as[i] ?? bs[i];
+            let seg;
+            if (sample.kind === 'llm.turn') {
+                seg = `llm.turn#${i}`;
+            }
+            else {
+                seg = `${sample.kind}:${sample.name}`;
+                if (n > 1)
+                    seg += `#${i}`; // 同键重复时加下标区分
+            }
+            pairs.push({ a: as[i], b: bs[i], seg });
+        }
+    }
+    return pairs;
+}
+/** 两侧都在时的字段级差异（顺序：status / name / error / usage.* / attributes.* / duration / events） */
+function diffSpanFields(a, b, ignoreTiming) {
+    const fields = [];
+    if (a.status !== b.status)
+        fields.push({ field: 'status', a: a.status, b: b.status });
+    if (a.name !== b.name)
+        fields.push({ field: 'name', a: a.name, b: b.name });
+    if (!errorEqual(a.error, b.error))
+        fields.push({ field: 'error', a: a.error, b: b.error });
+    pushUsageDiffs(fields, 'usage', a.usage, b.usage);
+    pushAttrDiffs(fields, a.attributes, b.attributes);
+    if (!ignoreTiming) {
+        // 比时长而非绝对时间戳（未结束为 undefined，与已结束也是差异）
+        const da = a.endedAt === undefined ? undefined : a.endedAt - a.startedAt;
+        const db = b.endedAt === undefined ? undefined : b.endedAt - b.startedAt;
+        if (da !== db)
+            fields.push({ field: 'duration', a: da, b: db });
+    }
+    pushEventDiffs(fields, a.events, b.events);
+    return fields;
+}
+/** error 比 type + message + retryable 三元组 */
+function errorEqual(x, y) {
+    if (!x || !y)
+        return x === y;
+    return x.type === y.type && x.message === y.message && x.retryable === y.retryable;
+}
+/** usage 逐字段比；缺省（undefined）与 0 是不同语义 —— 一侧有一侧无也是差异 */
+function pushUsageDiffs(out, prefix, x, y) {
+    for (const f of USAGE_FIELDS) {
+        const xv = x?.[f];
+        const yv = y?.[f];
+        if (xv !== yv)
+            out.push({ field: `${prefix}.${f}`, a: xv, b: yv });
+    }
+}
+/** attributes 并集逐键比（键序排序，输出确定） */
+function pushAttrDiffs(out, x, y) {
+    const keys = [...new Set([...Object.keys(x), ...Object.keys(y)])].sort();
+    for (const k of keys) {
+        if (x[k] !== y[k])
+            out.push({ field: `attributes.${k}`, a: x[k], b: y[k] });
+    }
+}
+/**
+ * events 序列比：长度不等记一条 `events` 计数差；逐下标比 name 与 body
+ * （body 用 stringifySafe 序列化后比字符串，差异值截断到 200 字符防爆）。
+ * 每个 span 最多报 EVENT_DIFF_LIMIT 条，超出记一条 `events` 截断说明。
+ * event.time 是墙钟字段，永不比。
+ */
+function pushEventDiffs(out, x, y) {
+    let budget = EVENT_DIFF_LIMIT;
+    let omitted = 0;
+    const push = (entry) => {
+        if (budget > 0) {
+            out.push(entry);
+            budget--;
+        }
+        else {
+            omitted++;
+        }
+    };
+    if (x.length !== y.length)
+        push({ field: 'events', a: x.length, b: y.length });
+    const n = Math.min(x.length, y.length);
+    for (let i = 0; i < n; i++) {
+        if (x[i].name !== y[i].name) {
+            push({ field: `events[${i}].name`, a: x[i].name, b: y[i].name });
+        }
+        const bx = stringifySafe(x[i].body);
+        const by = stringifySafe(y[i].body);
+        if (bx !== by) {
+            push({
+                field: `events[${i}].body`,
+                a: truncateWithMark(bx, DIFF_VALUE_CHARS),
+                b: truncateWithMark(by, DIFF_VALUE_CHARS),
+            });
+        }
+    }
+    if (omitted > 0) {
+        const note = `（事件差异超过 ${EVENT_DIFF_LIMIT} 条，另有 ${omitted} 条未列出）`;
+        out.push({ field: 'events', a: note, b: note });
+    }
+}
+/* ── 命令本体：两个 JSONL 各取第一条 trace → diff → 人读输出 ──────────────────── */
+const USAGE = '用法：agentia diff <a.jsonl> <b.jsonl>';
+/** 逐行 JSON.parse + extractTrace（同 harvest），取第一条可提取的 trace；坏行跳过计数 */
+async function readFirstTrace(file) {
+    let raw;
+    try {
+        raw = await readFile(file, 'utf8');
+    }
+    catch (e) {
+        throw new Error(`读不到文件 ${file}（${e.message}）`);
+    }
+    let badLines = 0;
+    for (const line of raw.split('\n')) {
+        const s = line.trim();
+        if (!s)
+            continue;
+        try {
+            const t = extractTrace(JSON.parse(s));
+            if (t)
+                return { trace: t, badLines };
+            badLines += 1;
+        }
+        catch {
+            badLines += 1;
+        }
+    }
+    throw new Error(`${file} 里没有可识别的 trace（支持裸 Trace 或含 result.trace / trace 的记录）` +
+        (badLines > 0 ? `；另有 ${badLines} 行无法解析` : ''));
+}
+/** 差异值 → 展示串：stringifySafe 序列化（短串直接放），长串截断 200 字符（同 DIFF_VALUE_CHARS） */
+function fmtValue(v) {
+    return truncateWithMark(stringifySafe(v), DIFF_VALUE_CHARS);
+}
+function fmtEntry(e) {
+    return `  ${e.field}: ${fmtValue(e.a)} → ${fmtValue(e.b)}`;
+}
+/** 失败一律**抛错**（同 report/harvest 的受理模式）；「有差异」不是错误，就地设 exitCode = 1 */
+export async function diffCommand(args) {
+    const files = [];
+    for (const a of args) {
+        if (a.startsWith('--'))
+            throw new Error(`未知参数：${a}\n${USAGE}`);
+        files.push(a);
+    }
+    if (files.length !== 2)
+        throw new Error(USAGE);
+    const [fileA, fileB] = files;
+    const ra = await readFirstTrace(fileA);
+    const rb = await readFirstTrace(fileB);
+    const d = diffTraces(ra.trace, rb.trace);
+    const badNote = (n) => (n > 0 ? `（跳过无法解析 ${n} 行）` : '');
+    const lines = [
+        `trace a  ${fileA}（${ra.trace.traceId ?? '(无 traceId)'}）${badNote(ra.badLines)}`,
+        `trace b  ${fileB}（${rb.trace.traceId ?? '(无 traceId)'}）${badNote(rb.badLines)}`,
+    ];
+    if (d.equal) {
+        lines.push('两条 trace 等价（无结构与字段差异）');
+        process.stdout.write(`${lines.join('\n')}\n`);
+        return 0;
+    }
+    lines.push('');
+    if (d.summary.length > 0) {
+        lines.push('run 级差异：');
+        for (const e of d.summary)
+            lines.push(fmtEntry(e));
+    }
+    if (d.spans.length > 0) {
+        if (d.summary.length > 0)
+            lines.push('');
+        lines.push('span 差异：');
+        for (const s of d.spans) {
+            const side = s.a === undefined ? ' (仅存在于 b)' : s.b === undefined ? ' (仅存在于 a)' : '';
+            lines.push(`${s.path}${side}`);
+            for (const e of s.fields)
+                lines.push(fmtEntry(e));
+        }
+    }
+    process.stdout.write(`${lines.join('\n')}\n`);
+    // diff(1) 语义：不同即 1。此刻 cli.ts 末尾的 `process.exitCode = main(...)` 已同步执行完，
+    // 这里的赋值在其后（await 之后），不会被覆盖。
+    process.exitCode = 1;
+    return 0;
+}

package/dist/doctor.js

@@ -5,11 +5,48 @@ import { CAPABILITY_DIRS, CAPABILITY_DIR_LIST, REGISTRY_PATH, isValidName } from
 import { legacyLayout, legacyMigrationHint } from './layout.js';
 /** 能力入口候选（须与框架 src/toolkit/discover.ts 的 ENTRY_CANDIDATES 一致） */
 const ENTRY_CANDIDATES = ['index.ts', 'index.mts', 'index.js', 'index.mjs'];
+/**
+ * 解析 import 绑定子句，产出本文件内可见的标识符。
+ * 覆盖 default / named（含 `as` 别名与 `type` 修饰）/ namespace / 混合形态；
+ * 注册表由 codemod 与人工共同维护，named import 等形态此前被静默跳过（悬空条目漏检）。
+ */
+function boundIdents(clause) {
+    const idents = [];
+    const brace = clause.match(/\{([\s\S]*)\}/);
+    const head = brace ? clause.replace(brace[0], '') : clause;
+    // 括号外部分：default 标识符和/或 `* as Ns`
+    for (const part of head.split(',')) {
+        const p = part.trim().replace(/^type\s+/, '');
+        if (!p)
+            continue;
+        const ns = p.match(/^\*\s+as\s+(\w+)$/);
+        if (ns)
+            idents.push(ns[1]);
+        else if (/^\w+$/.test(p))
+            idents.push(p);
+    }
+    // 括号内 named 列表：`A`、`A as B`、`type A`
+    if (brace) {
+        for (const item of brace[1].split(',')) {
+            const p = item.trim().replace(/^type\s+/, '');
+            if (!p)
+                continue;
+            const as = p.match(/^\w+\s+as\s+(\w+)$/);
+            if (as)
+                idents.push(as[1]);
+            else if (/^\w+$/.test(p))
+                idents.push(p);
+        }
+    }
+    return idents;
+}
 /** 解析 src/registry.ts：imports（标识符 → 来源）+ entries（provide token → useClass 标识符） */
 function parseRegistry(content) {
     const imports = new Map();
-    for (const m of content.matchAll(/^import\s+(\w+)\s+from\s+'([^']+)'/gm)) {
-        imports.set(m[1], m[2]);
+    // 单/双引号、type 修饰、跨行 named 列表都认；副作用 import（无绑定子句）不产生标识符
+    for (const m of content.matchAll(/^import\s+(?:type\s+)?([\s\S]*?)\s+from\s+(['"])([^'"]+)\2/gm)) {
+        for (const ident of boundIdents(m[1]))
+            imports.set(ident, m[3]);
     }
     const entries = [];
     for (const m of content.matchAll(/\{\s*provide:\s*'([^']+)'\s*,\s*useClass:\s*(\w+)/g)) {

package/dist/npm-bin.js

@@ -1,7 +1,44 @@
 /**
- * Windows 上 npm / npx 是 .cmd shim：不带 shell 的 spawn / spawnSync 无法直接执行
- * （ENOENT）。统一在这里按平台点名 —— 保持 CLI 零依赖（不引 cross-spawn）。
+ * Windows 上 npm / npx 是 .cmd shim：Node 修补 CVE-2024-27980（18.20.2 / 20.12.2 / 21.7.3+）后，
+ * 不带 shell 直接 spawn .cmd 会 EINVAL。统一在这里产出 spawn 描述（cross-spawn 同思路，
+ * 保持零依赖）：win32 走 cmd.exe 包装 + 逐参数脱敏，其余平台原样直 spawn。
+ *
+ * 为什么不用 options.shell:true —— shell:true 时 Node 把「命令 + 参数」用空格 join 后
+ * 整体塞给 cmd.exe，参数**不做任何转义**；而 add 的参数是用户输入的包名/本地路径，
+ * 含 `&` / `|` / `%` 即成命令注入。所以这里走 cmd.exe 包装并逐参数脱敏
+ * （算法取自 cross-spawn lib/util/escape.js，https://qntm.org/cmd）。
  */
-export function npmBin(bin, platform = process.platform) {
-    return platform === 'win32' ? `${bin}.cmd` : bin;
+// cmd.exe 元字符（见 http://www.robvanderwoude.com/escapechars.php）
+const CMD_META_CHARS = /([()\][%!^"`<>&|;, *?])/g;
+/** 命令名脱敏（npm.cmd 本身）：不加引号，只 ^ 脱敏元字符 */
+function escapeCmdCommand(command) {
+    return command.replace(CMD_META_CHARS, '^$1');
+}
+/**
+ * 参数脱敏：反斜杠+引号序列按 CreateProcess 规则翻倍转义，整体加双引号，
+ * 再对 cmd 元字符加 ^（`^` 落在引号外才生效，所以先加引号后脱敏）。
+ */
+function escapeCmdArg(arg) {
+    let out = arg
+        // 反斜杠序列 + 引号：反斜杠翻倍，引号加反斜杠
+        .replace(/(?=(\\+?)?)\1"/g, '$1$1\\"')
+        // 末尾反斜杠序列翻倍（随后会拼上收尾引号）
+        .replace(/(?=(\\+?)?)\1$/, '$1$1');
+    out = `"${out}"`;
+    return out.replace(CMD_META_CHARS, '^$1');
+}
+/**
+ * npm / npx 的 spawn 描述：win32 返回 cmd.exe 包装（参数已脱敏，
+ * 全局安装的 npm.cmd 非 node_modules/.bin 代理 shim，单层 ^ 脱敏即可）；
+ * 其余平台原样返回（直接 spawn 可执行文件）。
+ */
+export function npmSpawn(bin, args, platform = process.platform, comspec = process.env.comspec) {
+    if (platform !== 'win32')
+        return { command: bin, args, options: {} };
+    const shellCommand = [escapeCmdCommand(`${bin}.cmd`), ...args.map(escapeCmdArg)].join(' ');
+    return {
+        command: comspec ?? 'cmd.exe',
+        args: ['/d', '/s', '/c', `"${shellCommand}"`],
+        options: { windowsVerbatimArguments: true },
+    };
 }

package/dist/templates.js

@@ -60,7 +60,7 @@ export function projectPackageJson(name) {
             dev: 'tsx src/main.ts',
             typecheck: 'tsc --noEmit -p tsconfig.json',
         },
-        dependencies: { '@migor/agentia': '^0.5.0' },
+        dependencies: { '@migor/agentia': '^0.6.0' },
         devDependencies: {
             tsx: '^4.19.0',
             typescript: '^7.0.2',
@@ -76,6 +76,9 @@ export function projectTsconfig() {
             moduleResolution: 'NodeNext',
             lib: ['ES2022'],
             strict: true,
+            // 框架零运行时依赖（不再有厂商 SDK 经传递链把 @types/node 带进编译程序），
+            // node 全局类型必须显式声明
+            types: ['node'],
             esModuleInterop: true,
             skipLibCheck: true,
         },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@migor/cli",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Agentia 框架命令行工具：create 脚手架 + g 能力生成 + dev 本地可观测面板（trace inspector）",
   "type": "module",
   "bin": {
@@ -33,7 +33,7 @@
     "prepublishOnly": "node ../../scripts/check-release.mjs && npm run build"
   },
   "devDependencies": {
-    "@types/node": "^22.0.2",
+    "@types/node": "^26.5.1",
     "typescript": "^7.0.2"
   }
 }