@migor/cli 0.2.1 → 0.2.2

package/dist/add.js

@@ -1,18 +1,20 @@
-/** add 命令：npm install 第三方单元包并登记进 units.ts 注册表 */
+/** add 命令：npm install 第三方能力包并登记进 src/registry.ts 注册表 */
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { registerPackage } from './registry.js';
-/** 从 add 参数解析真实包名：支持 name[@version]、@scope/name[@version]、本地路径（file:） */
-function resolvePackageName(arg) {
-    if (arg.startsWith('.') || arg.startsWith('/')) {
-        const pkgFile = join(resolve(arg), 'package.json');
+/** 从 add 参数解析真实包名：支持 name[@version]、@scope/name[@version]、本地路径（. / 前缀，或 file: 协议） */
+export function resolvePackageName(arg) {
+    // file: 协议（npm install file:./pkg 的写法）先剥前缀，再按本地路径处理
+    const local = arg.startsWith('file:') ? arg.slice('file:'.length) : arg;
+    if (local.startsWith('.') || local.startsWith('/')) {
+        const pkgFile = join(resolve(local), 'package.json');
         if (!existsSync(pkgFile)) {
-            throw new Error(`本地包 ${arg} 缺少 package.json`);
+            throw new Error(`本地包 ${local} 缺少 package.json`);
         }
         const name = JSON.parse(readFileSync(pkgFile, 'utf8')).name;
         if (typeof name !== 'string' || name.length === 0) {
-            throw new Error(`本地包 ${arg} 的 package.json 缺少 name 字段`);
+            throw new Error(`本地包 ${local} 的 package.json 缺少 name 字段`);
         }
         return name;
     }
@@ -33,7 +35,7 @@ export function addPackage(arg) {
     const cwd = process.cwd();
     const r = spawnSync('npm', ['install', arg], { cwd, stdio: 'inherit' });
     if (r.error || r.status !== 0) {
-        console.error(`错误：npm install ${arg} 失败，units.ts 未改动`);
+        console.error(`错误：npm install ${arg} 失败，src/registry.ts 未改动`);
         process.exitCode = 1;
         return 1;
     }
@@ -49,12 +51,12 @@ export function addPackage(arg) {
     const token = packageNameToToken(pkgName);
     const result = registerPackage(cwd, token, pkgName);
     if (result === 'registered') {
-        console.log(`已登记到 units.ts：import ${pkgName} → { provide: '${token}' }`);
+        console.log(`已登记到 src/registry.ts：import ${pkgName} → { provide: '${token}' }`);
     }
     else {
-        console.log(`units.ts 中「${token}」已注册，跳过登记`);
+        console.log(`src/registry.ts 中「${token}」已注册，跳过登记`);
     }
-    console.log('约定提示：第三方单元包应 default export 一个 provider 类（或 Provider 对象）；' +
-        '若该包不符合约定，请手工调整 units.ts 中的 import 与条目');
+    console.log('约定提示：第三方能力包应 default export 一个 provider 类（或 Provider 对象）；' +
+        '若该包不符合约定，请手工调整 src/registry.ts 中的 import 与条目');
     return 0;
 }

package/dist/cli.js

@@ -1,21 +1,23 @@
 #!/usr/bin/env node
 /** agentia CLI 入口：手写参数解析 + 命令分发（零依赖） */
 import { createProject } from './create.js';
-import { generateUnit } from './generate.js';
-import { isUnitType, isValidName, UNIT_TYPES } from './templates.js';
+import { generateCapability } from './generate.js';
+import { isCapabilityType, isValidName, CAPABILITY_TYPES } from './templates.js';
 import { RegistryError } from './registry.js';
 import { devServer } from './dev.js';
 import { doctor } from './doctor.js';
 import { addPackage } from './add.js';
+import { reportCommand } from './report.js';
 const USAGE = `agentia —— Agentia 框架命令行工具
 
 用法：
   agentia create <name> [--dir <parent>]   创建项目脚手架（目录 <parent|当前目录>/<name>/）
-  agentia g <type> <name>                  在当前目录生成单元（别名：generate）
-                                           type: ${UNIT_TYPES.join(' | ')}
-  agentia dev                              启动开发模式（tsx watch src/main.ts，热重载）
-  agentia doctor                           装配体检（未登记/悬空单板/命名规范/重复条目）
-  agentia add <pkg>                        安装第三方单元包并登记到 units.ts
+  agentia g <type> <name>                  在当前目录生成能力（别名：generate）
+                                           type: ${CAPABILITY_TYPES.join(' | ')}
+  agentia dev                              启动开发模式（tsx watch 热重载 + 本地 inspector 面板）
+  agentia doctor                           装配体检（未登记/悬空能力/命名规范/重复条目）
+  agentia report <trace.jsonl>             从 trace 落盘文件生成调优报告（能力耗时/成本/错误率排行）
+  agentia add <pkg>                        安装第三方能力包并登记到 src/registry.ts
   agentia --help                           显示本帮助
 
 name 规则：小写字母开头的小写 kebab-case（如 hello、doc-reviewer）
@@ -60,16 +62,16 @@ function main(argv) {
     if (command === 'g' || command === 'generate') {
         const [type, name, ...extra] = rest;
         if (type === undefined || name === undefined || extra.length > 0) {
-            return fail('用法：agentia g <type> <name>（type: tool | skill | prompt | subagent）');
+            return fail(`用法：agentia g <type> <name>（type: ${CAPABILITY_TYPES.join(' | ')}）`);
         }
-        if (!isUnitType(type)) {
-            return fail(`未知单元类型「${type}」，可选：${UNIT_TYPES.join(' | ')}`);
+        if (!isCapabilityType(type)) {
+            return fail(`未知能力类型「${type}」，可选：${CAPABILITY_TYPES.join(' | ')}`);
         }
         if (!checkName(name)) {
-            return fail(`非法单元名「${name}」：需匹配小写 kebab-case（如 doc-reviewer）`);
+            return fail(`非法能力名「${name}」：需匹配小写 kebab-case（如 doc-reviewer）`);
         }
         try {
-            return generateUnit(type, name);
+            return generateCapability(type, name);
         }
         catch (err) {
             if (err instanceof RegistryError)
@@ -87,6 +89,15 @@ function main(argv) {
             return fail(`未知参数：${rest[0]}`);
         return doctor();
     }
+    if (command === 'report') {
+        // 异步命令（要 dynamic import 构建期拷进来的聚合实现）：自己设 exitCode，
+        // 返回值仅表示「已受理」—— 挂着的 Promise 会让 Node 等到它 settle 再退出。
+        void reportCommand(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) {
@@ -101,9 +112,8 @@ function main(argv) {
             throw err;
         }
     }
-    console.error(`错误：未知命令「${command}」\n`);
+    const code = fail(`未知命令「${command}」\n`);
     console.error(USAGE);
-    process.exitCode = 1;
-    return 1;
+    return code;
 }
 process.exitCode = main(process.argv.slice(2));

package/dist/create.js

@@ -1,15 +1,43 @@
 /** create 命令：生成 Agentia 项目脚手架 */
-import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { mainTs, projectGitignore, projectPackageJson, projectReadme, projectTsconfig, toolIndexTs, emptyRegistryTemplate, } from './templates.js';
-import { registerUnit } from './registry.js';
+import { fileURLToPath } from 'node:url';
+import { CAPABILITY_DIR_LIST, emptyRegistryTemplate, mainTs, projectGitignore, projectPackageJson, projectReadme, projectTsconfig, REGISTRY_PATH, toolIndexTs, } from './templates.js';
+import { registerCapability } from './registry.js';
 function write(dir, rel, content) {
     const file = join(dir, rel);
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, content, 'utf8');
 }
+/**
+ * 使用者向 AI 说明（项目里的 AGENTS.md）的单源 = 仓库根 `docs/usage-guide.md`。
+ * - 发布物：构建时由 `scripts/copy-assets.mjs` 拷成 `dist/AGENTS.md`（here = dist）；
+ * - 源码直跑（tsx）：here = src，回退三级到仓库根。
+ * 找不到就**明确失败**（不生成缺说明的项目）—— 说明是 AI 写对代码的前提。
+ */
+function readUsageGuide() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, 'AGENTS.md'), // 发布物：dist/AGENTS.md
+        join(here, '..', '..', '..', 'docs', 'usage-guide.md'), // 源码直跑：packages/cli/src → 仓库根
+    ];
+    for (const p of candidates) {
+        if (existsSync(p))
+            return readFileSync(p, 'utf8');
+    }
+    throw new Error(`找不到 AI 使用说明（docs/usage-guide.md）。查找过：\n  ${candidates.join('\n  ')}`);
+}
 export function createProject(name, parent) {
     const dir = resolve(parent ?? process.cwd(), name);
+    let guide;
+    try {
+        guide = readUsageGuide();
+    }
+    catch (e) {
+        console.error(`错误：${e instanceof Error ? e.message : String(e)}`);
+        process.exitCode = 1;
+        return 1;
+    }
     if (existsSync(dir) && readdirSync(dir).length > 0) {
         console.error(`错误：目录 ${dir} 已存在且非空`);
         process.exitCode = 1;
@@ -19,17 +47,29 @@ export function createProject(name, parent) {
     write(dir, 'package.json', projectPackageJson(name));
     write(dir, 'tsconfig.json', projectTsconfig());
     write(dir, 'src/main.ts', mainTs(name));
-    write(dir, 'units/hello/index.ts', toolIndexTs('hello'));
-    write(dir, 'units.ts', emptyRegistryTemplate());
+    write(dir, 'src/tools/hello/index.ts', toolIndexTs('hello'));
+    write(dir, REGISTRY_PATH, emptyRegistryTemplate());
     write(dir, 'README.md', projectReadme(name));
     write(dir, '.gitignore', projectGitignore());
-    registerUnit(dir, 'hello');
+    // 把四个分类目录都建出来：目录名自解释，用户一眼知道「新能力往哪放」
+    // （.gitkeep 让空目录能进版本库；discover 只认目录，会忽略它）
+    for (const relDir of CAPABILITY_DIR_LIST) {
+        write(dir, `${relDir}/.gitkeep`, '');
+    }
+    // AI 使用说明：让 Claude Code / Cursor / Copilot 等一进项目就拿到权威 API 速查
+    write(dir, 'AGENTS.md', guide);
+    registerCapability(dir, 'hello', 'tool');
     console.log(`已创建项目 ${dir}
 
 后续步骤：
   cd ${dir}
   npm install
   export ANTHROPIC_API_KEY=sk-ant-...
-  npm run dev`);
+  npm run dev
+
+目录约定：src/tools/ · src/skills/ · src/prompts/ · src/subagents/（一能力一文件夹）
+
+提示：项目内 AGENTS.md 是本框架的使用说明（API 速查 + 已知边界），
+      交给 AI 辅助编码时会自动被读，能显著减少猜 API 的错。`);
     return 0;
 }

package/dist/dev.js

@@ -1,7 +1,30 @@
-/** dev 命令：在项目根目录启动 tsx watch src/main.ts（热重载开发模式） */
+/**
+ * dev 命令：热重载开发模式（tsx watch src/main.ts）+ 本地 inspector 面板。
+ *
+ * inspector 的 trace 从哪来 —— dev 起的是【子进程】，而框架的 trace sink 必须是
+ * 进程内注册（registerDefaultTraceSink 是进程级注册表）。所以：
+ *   dev 侧起 inspector 服务 → 用 NODE_OPTIONS=--import 把 inspector-preload 注入子进程 →
+ *   preload 从【用户项目】解析 @migor/agentia 并注册 dev sink（POST /ingest）。
+ * 框架侧完全不感知 dev：不读 env、不含 dev 逻辑（决策见 spec §10）。
+ *
+ * 面板是增强项，任何一步失败都只告警、不阻断 dev。
+ */
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { startInspector } from './inspector.js';
+/** --import 可用性：Node ≥20.6（≥18.19 已回移植） */
+function supportsImport() {
+    const [major, minor] = process.versions.node.split('.').map(Number);
+    if (major > 20)
+        return true;
+    if (major === 20)
+        return minor >= 6;
+    if (major === 18)
+        return minor >= 19;
+    return false;
+}
 export function devServer() {
     const cwd = process.cwd();
     const entry = join(cwd, 'src', 'main.ts');
@@ -10,21 +33,47 @@ export function devServer() {
         process.exitCode = 1;
         return 1;
     }
-    const child = spawn('npx', ['tsx', 'watch', 'src/main.ts'], { cwd, stdio: 'inherit' });
-    // 把终端信号转发给子进程（tsx watch 需要收到 SIGINT 才能干净退出）
+    let child = null;
+    let inspector = null;
+    let closing = false;
     const forward = (sig) => () => {
-        if (!child.killed)
+        if (child && !child.killed)
             child.kill(sig);
     };
     process.on('SIGINT', forward('SIGINT'));
     process.on('SIGTERM', forward('SIGTERM'));
-    child.on('error', (err) => {
-        console.error(`错误：启动 dev 失败：${err.message}`);
-        process.exitCode = 1;
-    });
-    child.on('exit', (code, sig) => {
-        // 子进程退出后同步退出码；被信号杀死视为正常（用户 Ctrl+C）
-        process.exitCode = sig ? 0 : (code ?? 0);
+    const startChild = (env) => {
+        child = spawn('npx', ['tsx', 'watch', 'src/main.ts'], { cwd, stdio: 'inherit', env });
+        child.on('error', (err) => {
+            console.error(`错误：启动 dev 失败：${err.message}`);
+            process.exitCode = 1;
+        });
+        child.on('exit', (code, sig) => {
+            // 子进程退出后同步退出码；被信号杀死视为正常（用户 Ctrl+C）
+            process.exitCode = sig ? 0 : (code ?? 0);
+            if (inspector && !closing) {
+                closing = true;
+                void inspector.close();
+            }
+        });
+    };
+    if (!supportsImport()) {
+        console.warn(`[agentia] Node ${process.versions.node} 不支持 --import（需 ≥20.6 或 ≥18.19），inspector 面板不可用，dev 照常`);
+        startChild(process.env);
+        return 0;
+    }
+    startInspector()
+        .then((srv) => {
+        inspector = srv;
+        const here = dirname(fileURLToPath(import.meta.url));
+        const preload = pathToFileURL(join(here, 'inspector-preload.js')).href;
+        const merged = `${process.env.NODE_OPTIONS ? process.env.NODE_OPTIONS + ' ' : ''}--import "${preload}"`;
+        console.log(`Inspector: http://127.0.0.1:${srv.port}  （看每次 run 的调用树与能力执行）`);
+        startChild({ ...process.env, NODE_OPTIONS: merged, AGENTIA_INSPECT_PORT: String(srv.port) });
+    })
+        .catch((err) => {
+        console.warn(`[agentia] inspector 起不来（${err.message}），dev 照常运行`);
+        startChild(process.env);
     });
     return 0;
 }

package/dist/doctor.js

@@ -1,8 +1,11 @@
-/** doctor 命令：静态体检装配健康度（只读文件系统 + units.ts 文本，不 import 用户代码） */
+/** doctor 命令：静态体检装配健康度（只读文件系统 + src/registry.ts 文本，不 import 用户代码） */
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { isValidName } from './templates.js';
-/** 解析 units.ts：imports（标识符 → 来源）+ entries（provide token → useClass 标识符） */
+import { CAPABILITY_DIRS, CAPABILITY_DIR_LIST, REGISTRY_PATH, isValidName } from './templates.js';
+import { legacyLayout, legacyMigrationHint } from './layout.js';
+/** 能力入口候选（须与框架 src/toolkit/discover.ts 的 ENTRY_CANDIDATES 一致） */
+const ENTRY_CANDIDATES = ['index.ts', 'index.mts', 'index.js', 'index.mjs'];
+/** 解析 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)) {
@@ -14,15 +17,19 @@ function parseRegistry(content) {
     }
     return { imports, entries };
 }
+/** 分类目录相对注册表的 import 前缀：./tools 等（悬空条目判定用） */
+const LOCAL_PREFIXES = CAPABILITY_DIR_LIST.map((p) => './' + p.replace(/^src\//, '') + '/');
 export function doctor() {
     const cwd = process.cwd();
-    const unitsDir = join(cwd, 'units');
-    const registryFile = join(cwd, 'units.ts');
-    const folders = existsSync(unitsDir)
-        ? readdirSync(unitsDir, { withFileTypes: true })
-            .filter((d) => d.isDirectory())
-            .map((d) => d.name)
-        : [];
+    // 老布局：先给迁移提示再收工 —— 去扫一个还不存在的新布局只会刷一屏无关警告
+    const legacy = legacyLayout(cwd);
+    if (legacy) {
+        console.log('agentia doctor —— 装配体检\n');
+        console.log(`  警告：${legacyMigrationHint(legacy)}`);
+        console.log('\n体检结果：0 错误，1 警告');
+        return 0;
+    }
+    const registryFile = join(cwd, REGISTRY_PATH);
     const content = existsSync(registryFile) ? readFileSync(registryFile, 'utf8') : '';
     const { imports, entries } = parseRegistry(content);
     const warnings = [];
@@ -34,29 +41,49 @@ export function doctor() {
         seen.set(e.token, (seen.get(e.token) ?? 0) + 1);
     for (const [token, n] of seen) {
         if (n > 1)
-            errors.push(`units.ts 存在 ${n} 条重复 provide: '${token}'，请保留一条`);
+            errors.push(`${REGISTRY_PATH} 存在 ${n} 条重复 provide: '${token}'，请保留一条`);
     }
-    const folderSet = new Set(folders);
     const registeredTokens = new Set(entries.map((e) => e.token));
-    // 文件夹视角：命名规范 / 入口文件 / 是否登记
-    for (const name of folders) {
-        let broken = false;
-        if (!isValidName(name)) {
-            errors.push(`单元名「${name}」不符合 kebab-case 规范（units/${name}/）`);
-            broken = true;
-        }
-        if (!existsSync(join(unitsDir, name, 'index.ts'))) {
-            errors.push(`单元 units/${name}/ 缺少入口文件 index.ts`);
-            broken = true;
+    /** 文件夹名 → 出现的分类目录列表（跨类型同名会让装配期静默覆盖一个） */
+    const whereByName = new Map();
+    const allFolders = new Set();
+    // 逐个分类目录体检：命名规范 / 入口文件 / 是否登记
+    for (const [type, relDir] of Object.entries(CAPABILITY_DIRS)) {
+        const dir = join(cwd, relDir);
+        if (!existsSync(dir)) {
+            warnings.push(`${relDir}/ 不存在（该类型暂时没有能力；discover 里若仍列着这个路径会启动即报错）`);
+            continue;
         }
-        if (!registeredTokens.has(name)) {
-            warnings.push(`units/${name}/ 存在但 units.ts 未登记（运行 agentia g <type> ${name} 或手工登记）`);
+        const folders = readdirSync(dir, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+        for (const name of folders) {
+            allFolders.add(name);
+            whereByName.set(name, [...(whereByName.get(name) ?? []), relDir]);
+            let broken = false;
+            if (!isValidName(name)) {
+                errors.push(`能力名「${name}」不符合 kebab-case 规范（${relDir}/${name}/）`);
+                broken = true;
+            }
+            if (!ENTRY_CANDIDATES.some((f) => existsSync(join(dir, name, f)))) {
+                errors.push(`能力 ${relDir}/${name}/ 缺少入口文件（${ENTRY_CANDIDATES.join(' / ')}）`);
+                broken = true;
+            }
+            if (!registeredTokens.has(name)) {
+                warnings.push(`${relDir}/${name}/ 存在但未登记（运行 agentia g ${type} ${name} 或手工登记）`);
+            }
+            else if (!broken) {
+                oks.push(`${relDir}/${name}：已登记且入口齐全`);
+            }
         }
-        else if (!broken) {
-            oks.push(`units/${name}：已登记且入口齐全`);
+    }
+    // 跨分类目录同名 → 错误（四个目录共用一套 token，装配期后者覆盖，菜单只会剩一个）
+    for (const [name, dirs] of whereByName) {
+        if (dirs.length > 1) {
+            errors.push(`能力名「${name}」在多个分类目录重复（${dirs.join('、')}）—— DI token 共用，装配期只会保留一个；请改名`);
         }
     }
-    // 注册表视角：悬空单板（import 指向 ./units/ 但文件夹已不存在；add 引入的包无本地文件夹属正常）
+    // 注册表视角：悬空条目（import 指向本地分类目录但文件夹已不存在；add 引入的包无本地文件夹属正常）
     for (const e of entries) {
         if (!isValidName(e.token)) {
             errors.push(`provide token「${e.token}」不符合 kebab-case 规范`);
@@ -64,11 +91,12 @@ export function doctor() {
         const source = imports.get(e.ident);
         if (source === undefined)
             continue; // 无法定位 import（可能手工编写），跳过
-        if (source.startsWith('./units/')) {
-            const folder = source.split('/')[2];
-            if (folder !== undefined && !folderSet.has(folder)) {
-                warnings.push(`units.ts 条目 { provide: '${e.token}' } 指向 ${source}，但 units/${folder}/ 不存在（悬空单板，请删除条目或恢复目录）`);
-            }
+        const prefix = LOCAL_PREFIXES.find((p) => source.startsWith(p));
+        if (prefix === undefined)
+            continue;
+        const folder = source.slice(prefix.length).split('/')[0];
+        if (folder !== undefined && !allFolders.has(folder)) {
+            warnings.push(`${REGISTRY_PATH} 条目 { provide: '${e.token}' } 指向 ${source}，但该目录已不存在（悬空条目，请删除条目或恢复目录）`);
         }
     }
     console.log('agentia doctor —— 装配体检\n');

package/dist/generate.js

@@ -1,21 +1,33 @@
-/** g / generate 命令：在 cwd 生成 units/<name>/ 单元并登记注册表 */
+/** g / generate 命令：在 cwd 生成 src/<分类>/<name>/ 能力并登记注册表 */
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { promptAssetMd, promptIndexTs, skillIndexTs, subagentIndexTs, subagentSystemMd, toolIndexTs, } from './templates.js';
-import { ensureRegistry, registerUnit } from './registry.js';
-export function generateUnit(type, name) {
+import { CAPABILITY_DIRS, promptAssetMd, promptIndexTs, skillIndexTs, subagentIndexTs, subagentSystemMd, toolIndexTs, } from './templates.js';
+import { ensureRegistry, registerCapability } from './registry.js';
+import { legacyLayout, legacyMigrationHint } from './layout.js';
+export function generateCapability(type, name) {
     const cwd = process.cwd();
-    const unitDir = join(cwd, 'units', name);
-    if (existsSync(unitDir)) {
-        console.error(`错误：units/${name}/ 已存在`);
+    // 老布局：绝不悄悄在旁边新建一棵新目录（会让项目里长出两套能力目录）
+    const legacy = legacyLayout(cwd);
+    if (legacy) {
+        console.error(`错误：${legacyMigrationHint(legacy)}`);
         process.exitCode = 1;
         return 1;
     }
-    mkdirSync(unitDir, { recursive: true });
+    const relDir = CAPABILITY_DIRS[type];
+    const capabilityDir = join(cwd, relDir, name);
+    // 四个分类目录共用一套 DI token（缺省 = 文件夹名），跨目录同名会让装配期静默覆盖掉一个。
+    // 生成期直接拦住（doctor 另做兜底体检），而不是等运行时菜单少一项才发现。
+    const clash = Object.entries(CAPABILITY_DIRS).find(([, d]) => existsSync(join(cwd, d, name)));
+    if (clash) {
+        console.error(`错误：能力名「${name}」已存在于 ${clash[1]}/${name}/ —— 四个分类目录共用同一套 DI token（缺省取文件夹名），不能重名`);
+        process.exitCode = 1;
+        return 1;
+    }
+    mkdirSync(capabilityDir, { recursive: true });
     const files = [];
     const put = (rel, content) => {
-        writeFileSync(join(unitDir, rel), content, 'utf8');
-        files.push(`units/${name}/${rel}`);
+        writeFileSync(join(capabilityDir, rel), content, 'utf8');
+        files.push(`${relDir}/${name}/${rel}`);
     };
     switch (type) {
         case 'tool':
@@ -34,16 +46,16 @@ export function generateUnit(type, name) {
             break;
     }
     ensureRegistry(cwd);
-    const result = registerUnit(cwd, name);
-    console.log(`已生成 ${type} 单元：`);
+    const result = registerCapability(cwd, name, type);
+    console.log(`已生成 ${type} 能力：`);
     for (const f of files)
         console.log(`  ${f}`);
     if (result === 'registered') {
-        console.log(`已登记到 units.ts：{ provide: '${name}' }`);
+        console.log(`已登记到 src/registry.ts：{ provide: '${name}' }`);
     }
     else {
-        console.log(`units.ts 中「${name}」已注册，跳过登记`);
+        console.log(`src/registry.ts 中「${name}」已注册，跳过登记`);
     }
-    console.log('提示：discover 目录扫描路线下无需登记即可生效；显式装配路线从 units.ts 引入 providers');
+    console.log('提示：discover 目录扫描路线下无需登记即可生效；显式装配路线从 src/registry.ts 引入 providers');
     return 0;
 }

package/dist/inspector/fromTrace.js

@@ -0,0 +1,144 @@
+/* 把框架的 Trace.spans[] 归一成渲染动作，喂给 createTraceView 建出的视图。
+ *
+ * 框架的 trace 是【扁平 spans[] + parentSpanId】，渲染器要的是【嵌套树 + 每个节点内
+ * 事件与子 span 按发生顺序混排的 order】。本文件就是那座桥 —— 同一份渲染器因此
+ * 既能吃官网的模拟回放，也能吃真实 run 的 trace。
+ *
+ * 归一规则：
+ *   1. 全局时间线：每个 span 的 start / end 与它的每个 event 汇到一起，按时间排序。
+ *      tie-break：同一毫秒 start(0) → event(1) → end(2)，且 start 按深度浅的在前 ——
+ *      保证父 span 先于子 span 打开、tool.input 落在它所属 turn 打开之后。
+ *   2. 显示名合成：框架的 capability span 名是【裸名】（类型记在 attributes，如 {subagent:'x'}），
+ *      这里补成 `type:name`，与渲染器的四类标识符对齐；事件里的工具名若是某个 capability span
+ *      的裸名，同样补前缀（否则回落 tool:）。
+ *   3. usage 只由 llm.turn 累计（capability span 的 usage 是子 span 聚合，计入会双算）。
+ */
+
+import { fmtArg, capabilityTypeOf, CAP_ICO } from './view.js';
+
+/** 从 span.attributes 认能力类型（框架用 `setAttribute(capabilityId, 'subagent', name)` 记类型） */
+function spanType(s) {
+  const attrs = s.attributes || {};
+  for (const t of Object.keys(CAP_ICO)) {
+    if (attrs[t] != null) return t;
+  }
+  return '';
+}
+
+/** 显示名：capability span 补 `type:` 前缀（已是 type:name 形态则原样保留） */
+function displayName(s) {
+  const raw = String(s.name || '');
+  const t = spanType(s);
+  if (!raw) return t || s.kind || '';
+  if (capabilityTypeOf(raw)) return raw; // 已带前缀
+  return t ? `${t}:${raw}` : raw;
+}
+
+function usageOf(s) {
+  if (!s.usage) return null;
+  return {
+    input: s.usage.inputTokens || 0,
+    output: s.usage.outputTokens || 0,
+    cacheRead: s.usage.cacheReadTokens || 0,
+    cacheCreation: s.usage.cacheCreationTokens || 0,
+  };
+}
+
+/** 事件工具名：**只有 `tool.*` 事件带工具名**。
+ *  框架的事件里 `usage.unpriced` / `llm.retry` / `budget.exceeded` / `context.budget` 的事件体
+ *  根本没有 `tool` 字段 —— 一律套前缀只会得到 `tool:?` 这种把「无工具」显示成「名字叫 ? 的工具」
+ *  的误导标签（面板与官网 playground 共用本渲染器，等于把假工具摆给使用者看）。
+ *  工具裸名靠兄弟 capability span 反查类型，找不到按 tool 算。 */
+function eventToolName(evName, bodyTool, typeMap) {
+  if (!String(evName || '').startsWith('tool.')) return '';
+  const raw = String(bodyTool || '?');
+  if (capabilityTypeOf(raw)) return raw;
+  return `${typeMap.get(raw) || 'tool'}:${raw}`;
+}
+
+/** 事件摘要：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.output') {
+    const c = body && body.content;
+    return typeof c === 'string' ? c : c == null ? '' : JSON.stringify(c);
+  }
+  return body == null ? '' : typeof body === 'string' ? body : JSON.stringify(body);
+}
+
+/**
+ * 把真实 Trace 线性回放给视图（同步、一次性；用于 run 结束后的静态展示）。
+ * 返回 false 表示 trace 空、未做任何渲染。
+ */
+export function playTrace(view, trace) {
+  const spans = Array.isArray(trace && trace.spans) ? trace.spans : [];
+  if (!spans.length) return false;
+
+  const byId = new Map(spans.map((s) => [s.spanId, s]));
+  const root = spans.find((s) => s.kind === 'run') || spans[0];
+
+  // 裸名 → 能力类型（供事件补前缀）
+  const typeMap = new Map();
+  for (const s of spans) {
+    const t = spanType(s);
+    if (s.kind === 'capability' && t) typeMap.set(String(s.name || ''), t);
+  }
+
+  const depthOf = (s) => {
+    let d = 0;
+    let cur = s;
+    const seen = new Set();
+    while (cur && cur.parentSpanId && byId.has(cur.parentSpanId) && !seen.has(cur.spanId)) {
+      seen.add(cur.spanId);
+      d += 1;
+      cur = byId.get(cur.parentSpanId);
+    }
+    return d;
+  };
+
+  const items = [];
+  for (const s of spans) {
+    items.push({ t: s.startedAt, ord: 0, d: depthOf(s), s, kind: 'start' });
+    if (s.endedAt != null) items.push({ t: s.endedAt, ord: 2, d: 0, s, kind: 'end' });
+    for (const ev of s.events || []) items.push({ t: ev.time, ord: 1, d: 0, s, kind: 'event', ev });
+  }
+  items.sort((a, b) => a.t - b.t || a.ord - b.ord || a.d - b.d);
+
+  const rootRaw = String(root.name || 'run');
+  // 框架的 run 根名可能是 runName（如 'app'）或已是 'run · x' 形态，避免重复前缀
+  view.reset(rootRaw.startsWith('run') ? rootRaw : 'run · ' + rootRaw);
+
+  for (const it of items) {
+    if (it.kind === 'start') {
+      if (it.s === root) continue; // 根由 reset 建，不重复开
+      view.start({
+        id: it.s.spanId,
+        parent: it.s.parentSpanId,
+        kind: it.s.kind,
+        name: displayName(it.s),
+        arg: '',
+      });
+    } else if (it.kind === 'event') {
+      view.event(
+        it.s.spanId,
+        it.ev.name,
+        eventToolName(it.ev.name, it.ev.body && it.ev.body.tool, typeMap),
+        eventText(it.ev),
+        !it.ev.body || it.ev.body.ok !== false,
+      );
+    } else {
+      view.end({
+        id: it.s.spanId,
+        ms: it.s.endedAt - it.s.startedAt,
+        usage: usageOf(it.s),
+        status: it.s.status,
+        error: it.s.error,
+        arg: '',
+      });
+    }
+  }
+
+  view.finish(root.endedAt != null ? root.endedAt - root.startedAt : 0, root.status, root.error);
+  return true;
+}