使用指南

快速开始

Agentia 是声明式 agent 服务框架：装饰器声明四类能力，主 agent 作为路由器自主编排；一次 run 交付结构化结果与完整调用树（runId == traceId），token / 成本 / 指标一路记账 —— 可回放、可审计。三分钟跑起来：

npm i -g @migor/cli
agentia create my-app        # 脚手架：四分类目录 + src/registry.ts + .env
cd my-app && npm install
agentia g subagent doc-reviewer  # 生成能力并自动登记
# 把 ANTHROPIC_API_KEY 填进脚手架生成的 .env（.gitignore 已挡住它）
npm run dev -- "帮我审查 docs/report.md"

装配与启动是分开的：装配工厂在 src/app.ts，两个入口共用它 —— 默认入口 src/main.ts 起的是 HTTP 服务（npm run build 之后 npm start），一次性批处理在 src/batch.ts（npm run start:batch -- "你的问题"）。

app.ts       # createAgentApp() 装配工厂：能力选择 / 工作目录 / .env（dev 环与两个入口共用）
main.ts      # 默认入口：npm start → HTTP 服务（/healthz · POST /run · POST /tasks · drain）
batch.ts     # 一次性：npm run start:batch -- "你的问题"
registry.ts  # 显式注册表（agentia g 自动维护）

场景指南

按「要做的事」找配方：五张卡各给最小骨架与一行深入链接，所有 API 与命令都与 docs/usage-guide.md 逐字一致。

上线一个 HTTP agent 服务

脚手架已经给到这个：agentia create 产出的 src/main.ts 就是它 —— npm run build 之后 npm start 直接起。下面这份是从零接一遍的宿主版本，换装配 / 自己接宿主时看它。

一份 handler 同时给同步 POST /run（带 Accept: text/event-stream 则 SSE）、异步 POST /tasks（幂等键去重）、GET /healthz 探针；鉴权走 authenticate 缝（拦在读 body 之前），停机走 drain —— 未完成的任务留在 store，重启 resumePending() 续跑。

import { createServer } from 'node:http';
import { createApp, createHttpHandler, AsyncRunner, SqliteTaskStore, HttpException } from '@migor/agentia';

const app = await createApp({ name: 'my-app', providers, system });
const runner = new AsyncRunner(app, { store: new SqliteTaskStore('./tasks.db') });
await runner.resumePending(); // 重启续跑 queued/running，不是丢弃

const handler = createHttpHandler(app, {
  runner,
  authenticate: async (req) => {
    if (!verify(req.headers.authorization)) throw new HttpException(401, { error: '无效凭据' });
  },
});
createServer(handler).listen(8080);
// POST /run（同步 / SSE）  POST /tasks（异步）  GET /tasks/:id  GET /healthz
process.on('SIGTERM', () => handler.drain({ timeoutMs: 15_000 })); // 信号处理是宿主的

详见「触发方式」「宿主硬化」；完整可跑示例（四类能力 + 三种触发 + 鉴权 + 全观测栈 + Dockerfile）见 examples/complete。

想再加一个 gRPC 入口：这是宿主侧的事，框架不内置（判别规则只有一条 —— 客户端是不是标准库：MCP 连接器能用 spawn + fetch 做到零新增依赖，gRPC 要引 @grpc/grpc-js）。配方见 docs/usage-guide.md §6.2，可直接抄的宿主 + 客户端 + 端到端在 examples/grpc-host —— 那里把四处最容易漏的语义逐条写明：deadline / 取消 → signal、metadata traceparent → run 根 link、框架错误 → gRPC 状态码、trace → sink。

给 run 上监控

指标与 trace 走同一条缝：metricsSink() 满足 TraceSink，接进 sinks 即得 agentia_* 指标族（run / 能力 / 模型 / 评分四级，评分来自 attachScore 的 agentia_score / agentia_score_total）；createOtlpExporter 导出时对齐 OTel GenAI semconv（gen_ai.* 键）。

import { metricsSink, createOtlpExporter } from '@migor/agentia';

const metrics = metricsSink();
const app = await createApp({
  name: 'my-app', providers, system,
  sinks: [metrics, createOtlpExporter({ endpoint: 'http://localhost:4318' })],
});
createHttpHandler(app, { metrics }); // 内建 GET /metrics（不鉴权，停机中也回）

Grafana 看板 JSON 随仓库发（examples/observability/grafana-dashboard.json，对着 metricsSink 缺省前缀做的，导入即用）。详见「可观测」「生态与观测」。

离线评测与线上回流

defineEval + scriptedClient 离线跑 CI：脚本化模型往返，对 trace 写断言；每个用例的结论自动 attachScore 到它的 trace（value 0|1、source 是 eval 名），下游 metricsSink 可直接聚合成通过率。线上事故用 agentia harvest 回流成 eval 用例骨架。

import { defineEval, scriptedClient } from '@migor/agentia';

const report = await defineEval({
  name: 'doc-review',
  app: () => app,
  cases: [{ input: '总结这份文档', client: scriptedClient([searchMsg, submitMsg]) }],
  expect: (r, { trace }) => { /* 断言 stopReason / 工具序列 / result.typed */ },
}).run();
if (!report.ok) process.exit(1); // 失败 case 带完整 trace，进 CI 只看 report.ok

agentia harvest trace.jsonl --failed --limit 5 --out evals/harvested.ts  # 线上 trace → eval 用例骨架

骨架不是成品：trace 不记 assistant 文本（脚本里是占位），预填的 expect 是抄录的实际轨迹（发生过 ≠ 应该发生）—— 人工核对后再进 CI。详见「生态与观测」与「CLI 命令参考」。

prompt / 模型 A/B

同一份输入跑两条 run（换模型、换 SystemPrompt 版本都行），diffTraces 比出结构与成本差；不落代码就 agentia diff 直比两份落盘 trace，有差异退出码 1，可直接进 CI 挡「换 prompt / 模型后轨迹漂移」。想「从第 N 回合换个问法重跑」用 forkMessages —— 它产出的是一份喂回 app.run 的 messages，跑的是新 run，不是续跑。

import { diffTraces, forkMessages } from '@migor/agentia';

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); // run 级 summary + 逐 span 字段差

// 分叉重放：主循环第 3 回合（0-based）之前截断，换个问法继续
const messages = forkMessages(a.result.trace, {
  atTurn: 3,
  append: [{ role: 'user', content: '换个思路：先给结论，再补证据。' }],
});
const c = await app.run(messages); // 起一条新 run，沿分叉点前的真实 tool 历史继续

agentia diff a.jsonl b.jsonl   # 直比两份落盘 trace（输入形态同 agentia report），有差异退出码 1

详见「CLI 命令参考」；有损边界（trace 不记 assistant 文本与原始输入）见 已知边界 表与 /llms-full.txt 的 A/B 一节。

人工闸门（HITL）

中间件可以 await 人的决策再放行，引擎会等工具结果：放行＝next()；拒绝＝不调 next()（短路，副作用不发生）；拒绝并让模型改道＝抛错（该条结果记 is_error，run 不中断）。

import type { CapabilityMiddleware } from '@migor/agentia';

const requireApproval: CapabilityMiddleware = async (call, next) => {
  if (!DANGEROUS.has(call.capability.name)) return next();
  const ok = await askHuman(call.capability.name, call.input); // run 就地停着等人
  if (!ok) throw new Error(`未获批准：${call.capability.name}`); // → is_error，模型换路
  return next();
};
createApp({ system, providers, middleware: [requireApproval] });

跨进程挂起 / 续跑已支持：@Tool({ approval: 'required' }) 声明后，模型每次调用都把任务挂起为 suspended（消息历史与待决清单随任务落库，重启不丢），POST /tasks/:id/approve 批准/拒绝后从断点恢复 —— 详见「横切配方」与 API 参考。

四类能力

能力是服务的组成部分。四类能力对主 agent 都是菜单里的可调用项，共用命名空间，装配期统一查重。

@Tool — 函数调用

类方法即工具。入参按 JSON Schema 解析，先校验再执行；失败回 is_error，run 不中断。

import { Tool } from '@migor/agentia';

export default class Weather {
  @Tool({
    description: '查询城市天气',
    schema: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
      additionalProperties: false,
    },
    strict: true,
  })
  get_weather(input: { city: string }) {
    return `上海 72°F sunny（${input.city}）`;
  }
}

@Skill — 代码控制的流程

方法体是确定性脚本：要不要调模型、调几次、结果怎么加工，全由代码决定。模型调用只在显式 ctx.llm() 时发生，在 skill 自己的 capability span 下开 llm.turn 记账。

import { Skill } from '@migor/agentia';
import type { SkillContext } from '@migor/agentia';

export default class WeeklyReport {
  @Skill({
    description: '就给定主题调用 LLM 产出要点',
    schema: {
      type: 'object',
      properties: { topic: { type: 'string' } },
      required: ['topic'],
      additionalProperties: false,
    },
  })
  async weekly_report(input: { topic: string }, ctx: SkillContext) {
    const r = await ctx.llm({ prompt: `就「${input.topic}」给出三个要点` });
    return r.text; // 返回值即产物，以 tool_result 交回主 agent
  }
}

@SubAgent — 隔离的子代理

独立循环 + 裁剪上下文。方法体不会执行——框架按 system 另起 agent 跑一轮，中间过程不外泄，只有最终报告回流主上下文。

import { SubAgent, asset } from '@migor/agentia';

export default class DocReviewer {
  @SubAgent({
    description: '按 system.md 的角色设定独立审查文档',
    schema: {
      type: 'object',
      properties: { task: { type: 'string' } },
      required: ['task'],
      additionalProperties: false,
    },
    system: asset(import.meta.url, './system.md'),
  })
  // 方法体不会执行：只读取方法名与装饰器元数据
  doc_reviewer(_input: { task: string }): void {}
}

@Prompt — 纯文本资产

模板与 playbook 资产，编译成菜单里一个无副作用的拉取型工具：模型判定需要时调用，文本以 tool_result 注入上下文。长文本放同目录 .md。

import { Prompt, asset } from '@migor/agentia';

export default class StyleGuide {
  @Prompt({ description: '写作规范（描述何时该拉取）' })
  style_guide(): string {
    return asset(import.meta.url, './asset.md');
  }
}

目录约定与装配

四分类目录，一能力一文件夹，长文本放 .md；每个能力是一个 default export 的类，用装饰器声明能力。

my-app/
├─ src/
│  ├─ app.ts                     # createAgentApp 装配工厂（dev 环与两个入口共用）
│  ├─ main.ts                    # 默认入口：npm start → HTTP 服务
│  ├─ batch.ts                   # 一次性入口：npm run start:batch
│  ├─ registry.ts                # 显式注册表（agentia g 自动维护）
│  ├─ tools/weather/index.ts     # @Tool
│  ├─ skills/weekly-report/      # @Skill
│  ├─ prompts/style-guide/       # @Prompt（含 asset.md）
│  └─ subagents/doc-reviewer/    # @SubAgent（含 system.md）
└─ tsconfig.json                 # include: ['src']，一个 src 全覆盖

两条装配路线

• 目录扫描：createApp({ discover: ['src/tools', …] }) 给一个目录或一组目录（顺序即装配顺序），启动期扫各目录下的 <name>/index.ts，default export 为类时以文件夹名为 DI token 注册（因动态 import，带 discover 的 createApp 返回 Promise）。
• 显式注册表：createApp({ providers, system })，providers 来自 src/registry.ts（由 agentia g 自动维护）。

两条路线二选一或混用；同 token 后者覆盖前者，不会重复收集菜单。装配期做静态校验：菜单查重、引用存在性、DI 循环依赖——在启动时失败，而不是在线上。

中间件（CapabilityMiddleware）

挂在每一次能力（tool / skill / subagent / prompt）调用的前后：鉴权、限流、结果缓存、审计日志、超时包装等横切关注点都走这里，不进业务能力。

type CapabilityMiddleware = (call: CapabilityCall, next: CapabilityNext) => unknown;

interface CapabilityCall {
  readonly capability: AgentTool;   // name / description / inputSchema 可读
  readonly input: unknown;   // schema 校验已过的入参
  readonly ctx?: ToolRunContext;
}
// 放行到下一层；next(newInput) 可改写入参，缺省沿用当前 input
type CapabilityNext = (input?: unknown) => unknown;

洋葱模型

• 链序 = 注册顺序：先注册的最外层，像洋葱一样层层包裹；
• next() 放行，next(newInput) 改写入参；不调 next 即短路（结果缓存等）；
• 抛错按能力失败处理：engine 包成 is_error 回给模型，run 不中断；
• 装配期包裹（AgentApp 构造函数），对 engine 零侵入；链为空时原样返回，零开销。

const app = await createApp({
  name: 'my-app',
  discover: ['src/tools', 'src/skills', 'src/prompts', 'src/subagents'],
  middleware: [auth, cached], // auth 在最外层
  system,
});

例：鉴权

import type { CapabilityMiddleware } from '@migor/agentia';

// 敏感能力要求执行上下文里带授权标记，否则按能力失败抛错
export const auth: CapabilityMiddleware = (call, next) => {
  if (call.capability.name.startsWith('admin:') && !call.ctx) {
    throw new Error('forbidden: 缺少执行上下文');
  }
  return next();
};

例：结果缓存

import type { CapabilityMiddleware } from '@migor/agentia';

const store = new Map<string, unknown>();

// 命中即短路（不调 next），未命中放行后回写
export const cached: CapabilityMiddleware = async (call, next) => {
  const key = `${call.capability.name}:${JSON.stringify(call.input)}`;
  if (store.has(key)) return store.get(key);
  const out = await next();
  store.set(key, out);
  return out;
};

触发方式

同步 RPC、异步任务、定时调度共用一份输入契约；换宿主不换语义。

同步 RPC

await app.run(messages) 直接拿结果与 trace，适合请求-响应式宿主。

异步任务

AsyncRunner 提交即返回任务记录，后台执行；FileTaskStore 按 JSONL 一行一快照落盘，宿主重启后 resumePending() 续跑 queued/running。

const task = await runner.submit(
  [{ role: 'user', content: '生成上周运营周报' }],
  { idempotencyKey: 'weekly-report:2026-W36' },
);

定时调度

Scheduler 支持 every（间隔）与 at（定点）两种计划，到点转为异步任务提交。

幂等

异步宿主是 at-least-once 语义：同一 idempotencyKey 重复 submit，若上一任务未失败则直接返回既有记录（last-wins 去重）；失败的同键允许重提产生新任务。

长上下文策略

createBudgetPolicy 提供预算驱动的上下文护栏，规则带滞回，避免每回合反复压缩：

• 估算整组消息 token，≤ 预算 → 原样放行（快路径）；
• 超预算先 context editing：丢旧工具对，不额外调模型；
• 仍超预算且有 summarize → compaction：旧前缀做成摘要，只留最近 keepRecent 条；距上次压缩不足 compactEvery 个回合则跳过（防抖）；
• 框架不替你造 token：缺省 token 估算是 CJK 感知启发式，真机可注入按 /count_tokens 的 estimate。
• 估算只算新增消息：历史只追加，前缀的估算值被复用，所以每回合的估算开销与「本轮新增」成正比，而不是与整段历史成正比。

import { createBudgetPolicy } from '@migor/agentia';

const policy = createBudgetPolicy({
  budgetTokens: 60_000,   // 预算（估算 input tokens）
  keepRecent: 20,          // compaction 保留的最近消息条数
  editBeforeCompact: true,  // 先编辑再压缩
  compactEvery: 1,          // 压缩滞回（回合数）
  // summarize: (historyText) => ...,  // 提供才允许 compaction
});

结构化结果

给 run 一个 resultSchema，模型完成工作后通过隐藏的 submit_result 工具提交结果，框架校验后挂在 result.typed 上——不再从纯文本里猜 JSON。

const { result } = await app.run(messages, {
  resultSchema: {
    type: 'object',
    properties: { pass: { type: 'boolean' }, reason: { type: 'string' } },
    required: ['pass', 'reason'],
    additionalProperties: false,
  },
});
console.log(result.typed); // { pass: true, reason: '…' }

schema 也可以来自 zod（peer 可选）：fromZod(z.toJSONSchema(S), S)，校验走 zod，错误路径原样回给模型自我修正。

可观测：trace 一等公民

一次 run == 一条 trace（traceId === runId），Turn 0 起内建 —— 不是外挂的第三方追踪 SDK 集成。这是 Agentia 与「能跑通就交差」的 agent demo 的分界线：四类能力决定它能做什么，trace 决定你敢不敢上线。

• 每步记账：每个 span 带 model、input / output / cache tokens、成本估计、状态与错误类型。口径明确 —— totalUsage 只累加 llm.turn，能力 span 的 usage 是子孙聚合，不重复计数。
• 出口是一条缝：TraceSink { export(trace) } —— run 收尾的成功与失败两条路径都投递，且 sink 抛错不影响 run。落库检索 / 采样 / 脱敏都在缝外用 sink 组合，框架不替你做策略（实码见 examples/observability/，说明见 docs/observability.md）。
• 成本可管：priceOverrides 给价目表打补丁；模型不在表里时显式发 usage.unpriced 事件（不静默按 0 算）；硬管控见下面「成本硬管控」。
• 可回放：traceToMessages(trace) 把已完成的 trace 线性化喂回模型，作为调试与「改完 prompt 再跑一遍」的基底。
• 可导出：createOtlpExporter({ endpoint }) 推 OTLP，导出时对齐 OTel GenAI semconv（追加 gen_ai.* 键：run 根 invoke_agent、llm.turn 的 gen_ai.request.model、score 事件译为 gen_ai.evaluation.result，既有 usage.* 键保留）；metricsSink() 让指标也走同一条缝（Prometheus 文本或 OTLP metrics），全程零依赖。接法见「场景指南 · 给 run 上监控」。
• 本地就能看：agentia dev 起本地 inspector 面板，与 @migor/trace-view 共用同一份渲染器 —— 官网 Playground 用的也是同一份，三处一套代码，不漂移。

import { createOtlpExporter } from '@migor/agentia';

const { result } = await app.run(messages);

result.trace.spans;       // 调用树：llm.turn / 能力 span / 事件
result.trace.totalUsage;  // token 汇总（只累加 llm.turn）

// 出口是一条缝：落库 / 采样 / 脱敏 / 指标都在缝外组合，框架不内建策略
await createOtlpExporter({ endpoint: 'http://localhost:4318' }).export(result.trace);

指标与调优报告（「哪个能力慢 / 贵 / 爱失败」）见下面「生态与观测」。

宿主与导出

下面这份 server.ts 把 HTTP 宿主、SQLite 任务存储与 OTLP 导出接起来。

import { createServer } from 'node:http';
import { createHttpHandler, SqliteTaskStore, AsyncRunner, createOtlpExporter } from '@migor/agentia';

const runner = new AsyncRunner(app, { store: new SqliteTaskStore('./tasks.db') });
createServer(createHttpHandler(app, { runner })).listen(8080);
// POST /run（同步 / SSE）  POST /tasks（异步）  GET /tasks/:id（轮询）  GET /healthz（探针）

const otlp = createOtlpExporter({ endpoint: 'http://localhost:4318' });
await otlp.export(result.trace);

多模型与记忆

engine 只依赖 ModelClient 结构面：Anthropic 天然满足，OpenAI 兼容端点（含 DeepSeek 等）用 createOpenAIClient 一行接入；memory 选项在 run 间水合/回写 blackboard。

import { createOpenAIClient, InMemoryMemoryStore } from '@migor/agentia';

const { result } = await app.run(messages, {
  client: createOpenAIClient({ baseURL: 'https://api.deepseek.com' }),
  model: 'deepseek-chat',
  memory: { store: new InMemoryMemoryStore(), keys: ['profile'] },
});

稳定性与流式

取消、重试、流式三件事共用同一份单次调用参数，从入口贯穿到模型请求。

• 取消传播：signal 一路传到 ModelClient.messages.stream（内置 Anthropic / OpenAI 适配器都转发）；中断不冒泡异常，run 以 stopReason='aborted' 收尾。HTTP 宿主内置「客户端断开即中止」，AsyncRunner.runTimeoutMs 到点会中止在飞 run。
• 重试与退避：缺省开启（maxAttempts=3、指数退避 + 抖动），只重试「本次尝试尚未产出任何文本」的失败 —— 已流出的字无法撤回。每次尝试开独立的 llm.turn span。
• SSE 流式：POST /run 带 Accept: text/event-stream → text.delta / run.end / error 逐帧下发；不带该头仍回一元 JSON。带背压保护：下游积压（res.writableLength）超过 sseMaxBufferedBytes（缺省 8 MiB）即收口该流并中止对应 run —— 否则一个连得上但不读的客户端会把内存吃光。

const { result } = await app.run(messages, {
  signal: controller.signal,                        // 取消传播到在飞的模型请求
  retry: { maxAttempts: 3, baseDelayMs: 500 },   // 缺省就开；retry: false 关闭
  onText: (delta) => process.stdout.write(delta),  // 流式文本增量
});

宿主硬化

框架不实现 token / JWT 鉴权，也不订阅进程信号 —— 那是宿主或反向代理的事。

• authenticate 拦在入口、读 body 之前（含未知路径，不暴露路径是否存在）；抛 HttpException 按其 status / body 回，抛其它错回 401 且原文只进服务端日志。
• drain({ timeoutMs })：拒新单 → 等在飞收尾 → 超时强制收口仍开着的 SSE 流；未完成的任务留在 store 里，下次启动 resumePending() 续跑（不是丢弃）。
• GET /healthz → { ok, inFlight, uptimeMs, draining }：不鉴权（探针带不了凭据）、停机中也回 200；inFlight = 在飞同步 run + queued/running 的异步任务。

const handler = createHttpHandler(app, {
  authenticate: async (req) => {
    if (!verify(req.headers.authorization)) throw new HttpException(401, { error: '无效凭据' });
  },
});
createServer(handler).listen(8080);
process.on('SIGTERM', () => handler.drain());  // 信号处理是宿主的

成本硬管控

与长上下文策略是互补的两件事：上下文策略在发送前改 messages（防 400 / 过早压缩），这里在记账后改 run 的结局 —— 目的是控制花钱。

• maxTotalTokens / maxCostUsd：每回合记账后判断，超限以 stopReason='budget_exceeded' 收尾（算失败）并在 run 根记一条 budget.exceeded 事件。口径是整条 run（含子 agent）。
• 两处刻意的语义：模型自然收尾的那一回合超限不改判失败（那次任务其实做完了）；超限时连带不执行本回合的工具（不继续产生副作用）。
• toolTimeoutMs：超时不杀 run，该条 tool_result 记 is_error 让模型换路；maxToolConcurrency 给同回合的并行工具设上限。⚠️ 超时是「放弃等待」而非取消，AgentTool.run 收不到 signal。它是唯一裁判：工具自带的超时（MCP 桥的 timeoutMs）在设了本项时不参与判定。
• priceOverrides：给价格表打补丁 —— 覆盖内置型号单价，或给非 Anthropic 端点（DeepSeek / 自建）定价。它是 maxCostUsd 真正生效的前提：模型不在表里时成本恒 0、护栏不触发，而框架会通过 usage.unpriced 事件、model_unpriced_turns_total 指标与 onUnpricedModel 回调把这件事显式说出来，不静默。

const { result } = await app.run(messages, {
  maxTotalTokens: 200_000,  // 累计 token 上限（先到先算）
  maxCostUsd: 0.5,         // 累成本上限（依赖模型在价格表内）
  toolTimeoutMs: 10_000,     // 单工具超时 → is_error，不杀 run
  maxToolConcurrency: 4,     // 同回合并行工具上限
});

生态与观测

三件事都走既有扩展点：MCP 工具就是一个 AgentTool，指标就是一个 TraceSink，evals 就是对 trace 写断言。

• MCP：mcpTools(client, { server }) 把 server 的 tools/list 映射成菜单项。连接器出厂自带（createStdioMcpConnector / createStreamableHttpMcpConnector，只用 node:child_process + 全局 fetch）；框架不 import MCP SDK，McpClientLike 这条缝仍在（接官方 SDK / 远程 server / 自研传输照旧）。名字里对 LLM 不友好的字符会归一化成 _，原名按菜单名记进 mcp.tool.<菜单名> attribute（每次一条，并行不覆盖）供审计 / 回放。超时只有一个裁判：引擎设了 toolTimeoutMs 时桥的 timeoutMs 不参与判定（连接器自带的 timeoutMs 只管装配期的握手与 tools/list），两条路径同判定、同账（errorKind='timeout'）。
• evals：scriptedClient([...]) 脚本化模型往返 + defineEval({ app, cases, expect }) 对 trace 写断言 —— 改 prompt / 换模型 / 加工具之后有没有回归，靠断言而不是人眼。失败 case 带完整 trace。
• 指标：metricsSink() 天然满足 TraceSink，三个维度都从 trace 派生、不用埋点 —— run 级，以及能力级（每个 tool / skill / subagent 的调用数、失败数、耗时、token、成本：工具读 turn 上的 tool.output 事件，skill / subagent 读 capability span）与模型级（按模型归因，另出「算不出成本的 turn 数」）。时长同时给可跨实例聚合的 histogram 与窗口内精确分位两种口径；render() 出 Prometheus 文本，createHttpHandler({ metrics }) 直接内建 GET /metrics；也可以 export:'otlp' 推给 OTel 采集端（零依赖手写 JSON）。评分级指标：attachScore 写到 run 根的 score 事件聚合成 agentia_score{name,source}（gauge，最近一次值）与 agentia_score_total（counter，条数）—— eval 结论 / LLM-judge / 人工标注同走这一路；现成 Grafana 看板随仓库发（examples/observability/grafana-dashboard.json）。注意 createHttpHandler({ metrics }) 只管渲染 —— 数字要累计须把同一个 sink 接进 createApp({ sinks: [metricsSink()] })，否则恒 0 且不报错。
• 调优报告：buildRunReport(trace) 把一条 trace 变成「哪个能力慢 / 贵 / 爱失败」的排行（mergeRunReports 跨 run 汇总），CLI 一行 agentia report traces.jsonl 出表（那个 jsonl 要自己落：接一个 TraceSink 追加 JSON 行，或用 FileTaskStore 的导出文件）；agentia dev 面板里也有一份同样的排行。面对一堆旋钮时，这是「该拧哪个」的依据。
• 提示词版本：new SystemPrompt({ version }) 把版本号写进 run 根 system.version，trace 里能查「这个结果是哪个版本的提示词产出的」。多租户配额：middleware（拦）+ TraceSink（记账）+ BudgetGuard（单次上限）组合即可。

import { createApp, createStdioMcpConnector, mcpTools, metricsSink, defineEval, scriptedClient } from '@migor/agentia';

// 1) MCP：server 的工具变菜单项（连接器出厂自带；也可换成任意实现 listTools/callTool 的对象）
const mcp = createStdioMcpConnector(['uvx', 'mcp-server-time']);
const tools = await mcpTools(mcp, { server: 'time' });
const app = createApp({ system, providers, tools, sinks: [metricsSink()] });

// 2) evals：脚本化往返 + 断言 trace
const report = await defineEval({
  name: 'time-flow',
  app: () => app,
  cases: [{ input: '上海现在几点？', client: scriptedClient([toolCallTurn, finalTurn]) }],
  expect: (r, { trace }) => { /* 断言 stopReason / 调了哪些工具 / typed */ },
}).run();
if (!report.ok) console.error(report.cases.filter((c) => !c.ok));

// 3) 指标：Prometheus 文本，接个路由回 metricsSink().render() 即可

审批、护栏与代码隔离

护栏与代码隔离，框架只给缝、不做子系统（策略差异太大，硬编码必错）；审批除了闸门缝之外还有内建的挂起 / 恢复（HITL）。配方都只用既有扩展点，完整边界见 已知边界 表与 /llms-full.txt。

审批闸门

中间件可以 await 人的决策再放行 —— 引擎会等工具结果。放行＝next()；拒绝＝不调 next()（短路，副作用不发生）；拒绝并让模型改道＝抛错（该条结果记 is_error，run 不中断）。要跨进程 / 跨重启的耐久审批，用 @Tool({ approval: 'required' })：run 挂起为 suspended（消息历史落库），POST /tasks/:id/approve 批准后带着决定恢复执行 —— 见 API 参考的 AsyncRunner.approve 与 ApprovalDecision。

import { createApp } from '@migor/agentia';
import type { CapabilityMiddleware } from '@migor/agentia';

const DANGEROUS = new Set(['send_email', 'deploy', 'delete_records']);

const requireApproval: CapabilityMiddleware = async (call, next) => {
  if (!DANGEROUS.has(call.capability.name)) return next();
  const ok = await askHuman(call.capability.name, call.input); // 就地等人（run 停在这里）
  if (!ok) throw new Error(`未获批准：${call.capability.name}`); // → is_error，模型换路
  return next();                                     // 放行
};

createApp({ system, providers, middleware: [requireApproval] });

内容护栏

入参（包一层 app.run；HTTP 侧用 createHttpHandler({ authenticate })，拦在读 body 之前）、工具调用前（middleware）、出参（包返回值，或挂 sinks）。

const callable = {
  name: app.name,
  async run(msgs, opts) {
    const out = await app.run(redactInput(msgs), opts);   // 入参护栏
    if (flagged(out.result.finalText)) throw new Error('输出被护栏拦下'); // 出参护栏
    return out;
  },
};

代码执行隔离

框架从不执行模型生成的代码 —— @Skill 跑的是你写的方法体、@Tool 是你写的函数，模型输出只会变成文本 / tool_result。要隔离就在工具实现内部做（Docker / 子进程 / 微 VM 随你），框架不参与 —— AgentTool.run(input) → output 这个契约把隔离整个挡在实现里。唯一沾边的一条：工具起了子进程，取消时要自己 kill（框架的超时是「不等了」，不是取消）。

已知边界（如实标注）

框架不保证什么 —— 下表逐条说明，是判断「我能不能用它」的依据。内容在构建期从仓库单源 docs/usage-guide.md §7 注入，与站点别处（/llms-full.txt）逐字一致。

CLI 命令参考

全局安装 npm i -g @migor/cli 后使用 agentia 命令。

环境变量

版本与稳定性承诺

0.x 的含义：版本号按 SemVer，但 0.x 期间 minor 版本可以包含破坏性变更。规矩只有一条 —— 破坏性变更必须留痕： CHANGELOG.md 对应的那个版本里要有一段专门写它（小节标题含「迁移」或「破坏性变更」）， 写清「你要改什么」。

# 列出所有「要你做动作」的小节（本页刻意不写死这个数字 —— 写死的读数会腐烂）
grep -nE '^#{3,4} .*(迁移|破坏性)' CHANGELOG.md

⚠️ 如实标注：这条纪律是逐步收紧的 —— 早期的 0.7.1 （类型面变更）把动作写在版本条目开头的引用块里、没有独立小节。⇒ 那条命令是下限而非全集， 要读全就通读该版本的条目。

1.0 的门槛

三条都是可核验的，不是口号：

• docs/spec.md §11「开放项」里每一条要么落地、要么被明确划掉（写清为什么不阻塞）；
• docs/guards.md §2「待守」为空 —— 已声明的边界都由机器守着，而不是靠人记得；
• 公共导出面连续 3 个 minor 无破坏性变更。

性能量级

框架自带五个基准（scripts/bench-*.ts）。它们回答的是形状问题 —— 哪笔钱在什么条件下付、换实现能省掉的是什么 —— 而不是一个 SLA。

⚠️ 毫秒不是承诺：它们随机器 / Node 版本 / 负载而变，抄走当 SLA 会错。 真正恒定的是形状（差多少倍、往返几次、哪一笔跟什么成正比）。 五个基准刻意不进 CI（计时类基准在 CI 机器上只会制造抖动） ⇒ 这些数没有守卫盯着，要看就按「复跑」那一列自己跑一遍。