@migor/cli 0.7.1 → 0.8.0

package/dist/report.js

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

package/dist/templates/README.md

@@ -0,0 +1,62 @@
+# __PROJECT_NAME__
+
+基于 [Agentia](https://github.com/retrychx/agentia) 框架的 agent 应用。
+
+## 目录约定
+
+四分类目录，一能力一文件夹，每个能力是一个 default export 的类，用装饰器声明：
+
+- `src/tools/<name>/` —— `@Tool` 工具：主 agent 可调用（input → value）
+- `src/skills/<name>/` —— `@Skill` 技能：方法体内通过 `ctx.llm()` 调 LLM
+- `src/subagents/<name>/` —— `@SubAgent` 子代理：按 system 角色设定独立跑一轮
+- `src/prompts/<name>/` —— `@Prompt` 文本资产：.md 文件，按需拉取进上下文
+
+目录名就是类型，不用记别名。
+
+## 两条装配路线
+
+1. **目录扫描**：`createApp({ discover: [...] })` 启动期按给定顺序扫各目录下的 `<name>/index.ts`，default export 为类时以文件夹名为 DI token 注册（见 `src/main.ts`）。
+2. **显式装配**：`createApp({ providers, system })`，providers 来自 `src/registry.ts` 注册表（由 `agentia g` 自动维护，也可手工编辑）。
+
+两者二选一或混用。
+
+## 生成能力
+
+```bash
+agentia g tool my-tool        # → src/tools/my-tool/
+agentia g skill my-skill      # → src/skills/my-skill/
+agentia g prompt my-prompt    # → src/prompts/my-prompt/（含 asset.md）
+agentia g subagent my-agent   # → src/subagents/my-agent/（含 system.md）
+```
+
+生成的能力自动登记到 `src/registry.ts`。
+
+## 运行
+
+需要 Anthropic API key —— 填进脚手架已生成的 `.env` 即可（本文件在 `.gitignore` 里）：
+
+```bash
+# .env
+ANTHROPIC_API_KEY=sk-ant-...
+```
+
+```bash
+npm run dev -- "你的问题"
+```
+
+## 构建与生产运行
+
+```bash
+npm run build   # tsc → dist/ + .md 文本资产跟随拷贝（asset() 按文件位置解析，必须跟着 .js 走）
+npm start -- "你的问题"   # 跑编译产物 dist/main.js（部署/Docker 用这条）
+```
+
+也可以用环境变量（适合 CI / 容器）——**真实环境变量优先，不会被 `.env` 覆盖**：
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+npm run dev -- "你的问题"
+```
+
+`.env` 由 `src/main.ts` 首行的 `loadEnvFile()` 读取。框架**不会自动读**它 ——
+读哪个文件、什么时候读由你的启动代码决定（这样「换目录跑」不会悄悄改变行为）。

package/dist/templates/capabilities/prompt/asset.md

@@ -0,0 +1,3 @@
+# __NAME__
+
+在此编写提示文本资产（按需被主 agent 拉取进上下文）。

package/dist/templates/capabilities/prompt/index.ts

@@ -0,0 +1,9 @@
+import { Prompt, asset } from '@migor/agentia';
+
+/** __NAME__ 文本资产能力 */
+export default class __CLASS_NAME__ {
+  @Prompt({ description: '__NAME__ 文本资产（描述何时该拉取）' })
+  __METHOD_NAME__(): string {
+    return asset(import.meta.url, './asset.md');
+  }
+}

package/dist/templates/capabilities/skill/index.ts

@@ -0,0 +1,19 @@
+import { Skill } from '@migor/agentia';
+import type { SkillContext } from '@migor/agentia';
+
+/** __NAME__ 技能能力 */
+export default class __CLASS_NAME__ {
+  @Skill({
+    description: '示例技能：就给定主题调用 LLM 产出要点',
+    schema: {
+      type: 'object',
+      properties: { topic: { type: 'string' } },
+      required: ['topic'],
+      additionalProperties: false,
+    },
+  })
+  async __METHOD_NAME__(input: { topic: string }, ctx: SkillContext): Promise<string> {
+    const r = await ctx.llm({ prompt: `就「${input.topic}」给出三个要点` });
+    return r.text;
+  }
+}

package/dist/templates/capabilities/subagent/index.ts

@@ -0,0 +1,17 @@
+import { SubAgent, asset } from '@migor/agentia';
+
+/** __NAME__ 子代理能力 */
+export default class __CLASS_NAME__ {
+  @SubAgent({
+    description: '示例子代理：按 system.md 的角色设定独立处理任务',
+    schema: {
+      type: 'object',
+      properties: { task: { type: 'string' } },
+      required: ['task'],
+      additionalProperties: false,
+    },
+    system: asset(import.meta.url, './system.md'),
+  })
+  // 方法体不会执行：@SubAgent 只读取方法名与装饰器元数据，调用时由框架按 system 另起 agent 执行
+  __METHOD_NAME__(_input: { task: string }): void {}
+}

package/dist/templates/capabilities/subagent/system.md

@@ -0,0 +1,3 @@
+# __NAME__
+
+在此编写子代理的角色描述（作为其子 agent 的 system prompt）。

package/dist/templates/capabilities/tool/index.ts

@@ -0,0 +1,18 @@
+import { Tool } from '@migor/agentia';
+
+/** __NAME__ 工具能力 */
+export default class __CLASS_NAME__ {
+  @Tool({
+    description: '示例工具：回显输入',
+    schema: {
+      type: 'object',
+      properties: { text: { type: 'string' } },
+      required: ['text'],
+      additionalProperties: false,
+    },
+    strict: true,
+  })
+  __METHOD_NAME__(input: { text: string }): string {
+    return `echo: ${input.text}`;
+  }
+}

package/dist/templates/env

@@ -0,0 +1,3 @@
+# 模型 API key —— 填上后 npm run dev / npm start 直接可用
+# 本文件已被 .gitignore 忽略：不要提交，也不要把 key 写进 README / AGENTS.md
+ANTHROPIC_API_KEY=

package/dist/templates/env.example

@@ -0,0 +1,6 @@
+# 复制成 .env 再填值（.env 已 gitignore，不要提交）
+ANTHROPIC_API_KEY=
+
+# 可选
+# ANTHROPIC_BASE_URL=https://api.anthropic.com
+# AGENTIA_MODEL=claude-opus-5

package/dist/templates/gitignore

@@ -0,0 +1,6 @@
+node_modules
+dist
+
+# 本地环境变量（可能含 key）—— 绝不提交
+.env
+.env.local

package/dist/templates/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "__PROJECT_NAME__",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "agentia dev",
+    "build": "tsc -p tsconfig.json && node scripts/copy-assets.mjs",
+    "start": "node dist/main.js",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@migor/agentia": "^0.8.0"
+  },
+  "devDependencies": {
+    "@migor/cli": "^0.8.0",
+    "tsx": "^4.19.0",
+    "typescript": "^7.0.2",
+    "@types/node": "^22.0.0"
+  }
+}

package/dist/templates/scripts/copy-assets.mjs

@@ -0,0 +1,26 @@
+// 把能力文件夹里的 .md 文本资产拷进 dist/（与编译产物同相对路径）。
+// asset(import.meta.url, './x.md') 按**文件位置**解析，所以 .md 必须跟着 .js 走。
+import { cpSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = fileURLToPath(new URL('.', import.meta.url));
+const srcDir = join(here, '..', 'src');
+const outDir = join(here, '..', 'dist');
+
+function walk(dir) {
+  const out = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...walk(p));
+    else if (e.name.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+let n = 0;
+for (const f of walk(srcDir)) {
+  cpSync(f, join(outDir, f.slice(srcDir.length + 1)));
+  n++;
+}
+console.log(`[copy-assets] ${n} 个 .md 资产 → dist/`);

package/dist/templates/src/main.ts

@@ -0,0 +1,37 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createApp, loadEnvFile, SystemPrompt } from '@migor/agentia';
+
+// 读同目录的 .env（key 写文件里即可，不必每次 export）。框架**不自动**读 .env ——
+// 读哪个文件、什么时候读由这里决定；已存在的真实环境变量优先，不会被文件覆盖。
+// 想换路径/顺序：loadEnvFile({ path: '.env.local' }) 或直接删掉这一行改用自己的加载器。
+loadEnvFile();
+
+// 能力目录按**本文件位置**解析，不是 cwd：开发态（src/main.ts）解析到 src/<分类>/，
+// 构建后（dist/main.js）解析到 dist/<分类>/ —— 从任何目录启动都成立。
+// ⚠️ 别改回 cwd 相对写法（形如 src/tools 的字符串）：那样 `node dist/main.js` 会去加载 src 下的
+// .ts 源码，而装饰器不是可擦除的类型语法，Node 直接跑不了（"Invalid or unexpected token"）。
+// filter：空分类目录在构建后不存在（tsc 不为空目录产出 dist/<分类>/），而 discover 对
+// 显式给出的不存在路径是报错的 —— 「这类暂时没有能力」不该让启动失败。
+const CAPABILITY_DIRS = ['tools', 'skills', 'prompts', 'subagents'];
+const app = await createApp({
+  name: '__PROJECT_NAME__',
+  discover: CAPABILITY_DIRS.map((d) => fileURLToPath(new URL(d + '/', import.meta.url))).filter(
+    (dir) => existsSync(dir),
+  ),
+  system: new SystemPrompt().add('role', '你是 __PROJECT_NAME__ 的主 agent，按任务自主调度菜单里的能力。', true),
+});
+
+const { result } = await app.run(
+  [{ role: 'user', content: process.argv[2] ?? '介绍一下你自己' }],
+);
+
+// 注意：run 失败**不会抛**（硬失败被记进 result.error 与 trace 后正常返回）—— 不显式检查就会
+// 「打印一行空白 + 退出 0」，让首次运行（比如忘了配 ANTHROPIC_API_KEY）看起来像成功。
+if (result.error) {
+  console.error(`run 失败（stopReason=${result.stopReason}）：${result.error.message}`);
+  console.error('提示：模型调用读 ANTHROPIC_API_KEY —— 填进 .env（首行 loadEnvFile() 会读）或 export 均可；');
+  console.error('      换端点 / 注入自定义 client 见项目内 AGENTS.md。');
+  process.exitCode = 1;
+}
+if (result.finalText) console.log(result.finalText);

package/dist/templates/src/registry.ts

@@ -0,0 +1,10 @@
+// Agentia 能力注册表 —— 由 agentia CLI 维护（agentia g 自动更新，也可手工编辑）
+// @agentia:imports
+// @agentia:imports-end
+import type { Provider } from '@migor/agentia';
+
+/** 显式装配路线：createApp({ providers, system: ... })（与 discover 目录扫描二选一或混用） */
+export const providers: Provider[] = [
+  // @agentia:entries
+  // @agentia:entries-end
+];

package/dist/templates/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": [
+      "ES2022"
+    ],
+    "strict": true,
+    "rootDir": "src",
+    "outDir": "dist",
+    "types": [
+      "node"
+    ],
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": [
+    "src"
+  ]
+}