@migor/agentia 0.2.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 retrychx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -0,0 +1,151 @@
+# Agentia
+
+[![CI](https://github.com/retrychx/agentia/actions/workflows/ci.yml/badge.svg)](https://github.com/retrychx/agentia/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@migor/agentia)](https://www.npmjs.com/package/@migor/agentia) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+[中文 README](./README.md) · **English**
+
+**A declarative framework for building production agent services.** You declare four kinds of capability
+with decorators + DI and a main agent orchestrates them; every run yields structured output and an
+observable call tree (trace, cost, metrics).
+
+> This is a **summary**. The authoritative and always-current documentation is Chinese:
+> [`docs/usage-guide.md`](./docs/usage-guide.md) (API reference, type wiring, known limits) and the
+> [website](https://agentia-web.pages.dev). We keep this file short on purpose — a hand-maintained
+> full translation drifts.
+
+## Requirements
+
+Node.js **≥ 18** (the only `engines` requirement; CI runs 18 / 20 / 22). Deno and edge runtimes are
+**not** validated. The only store touching a Node builtin is `SqliteTaskStore` (needs Node ≥ 22.5 for
+`node:sqlite`) — it fails with a readable error at construction time, and never breaks importing the package.
+
+## Install
+
+```bash
+npm i @migor/agentia          # the framework
+npm i -g @migor/cli           # CLI: scaffold / generate / dev inspector
+
+agentia create my-app         # scaffold ships .env / .env.example
+$EDITOR my-app/.env           # put ANTHROPIC_API_KEY here (export works too — real env wins)
+# optional: ANTHROPIC_BASE_URL (compatible gateways), AGENTIA_MODEL (default claude-opus-5)
+```
+
+> The framework does **not** read `.env` on its own: the scaffolded `src/main.ts` calls
+> `loadEnvFile()` on its first line. Real environment variables always win over the file
+> (CI / docker / command line), unless you pass `loadEnvFile({ override: true })`.
+
+## Quick start
+
+### A. CLI
+
+```bash
+agentia create my-app
+cd my-app && npm install
+agentia g tool weather          # create src/tools/weather/index.ts and register it
+agentia dev                     # tsx watch + local inspector panel
+```
+
+Four self-describing directories hold capabilities — the directory name **is** the kind:
+`src/tools/` · `src/skills/` · `src/prompts/` · `src/subagents/`; the registry is `src/registry.ts`.
+
+### B. By hand
+
+```ts
+import { Tool, createApp, SystemPrompt } from '@migor/agentia';
+
+class WeatherTools {
+  @Tool({
+    description: 'Look up the weather for a city',
+    schema: {
+      type: 'object',
+      properties: { city: { type: 'string' } },
+      required: ['city'],
+      additionalProperties: false,
+    },
+  })
+  get_weather(input: { city: string }): string {
+    return `city=${input.city}`;
+  }
+}
+
+const app = createApp({
+  name: 'weather-app',
+  providers: [{ provide: 'weather', useClass: WeatherTools }],
+  system: new SystemPrompt().add('role', 'You are a helpful weather assistant.', true),
+});
+
+const { result } = await app.run([{ role: 'user', content: 'Weather in Shanghai?' }]);
+console.log(result.finalText); // final text
+console.log(result.trace);     // call tree + per-step tokens/cost (traceId === runId)
+```
+
+Or point `createApp` at the directories instead of passing providers:
+`createApp({ discover: ['src/tools', 'src/skills', 'src/prompts', 'src/subagents'], system })`.
+
+## The four capability kinds
+
+The model picks from one shared "menu" by `description`; the decorator decides **who controls the flow**:
+
+| Kind | Decorator | Who controls the flow | Typical use |
+|---|---|---|---|
+| Tool | `@Tool` | your code (one call = one function) | deterministic work: DB, math, HTTP |
+| Skill | `@Skill` | your code (scripted; model calls only at explicit `ctx.llm()`) | fixed "fetch → let the model write → post-process" pipelines |
+| Sub-agent | `@SubAgent` | **the model** (own loop, trimmed context) | multi-step autonomy without polluting the main context |
+| Prompt asset | `@Prompt` | pulled by the model on demand | long specs/templates that shouldn't sit in context by default |
+
+## Runtime features
+
+- **Triggering** — `app.run()` (sync RPC) · `AsyncRunner` (idempotency-keyed, retryable, resumable via a
+  store) · `Scheduler` (cron-like) · `createHttpHandler` (`POST /run`, `POST /tasks`, `GET /tasks/:id`,
+  `GET /healthz`, optional `GET /metrics`, graceful `drain()`)
+- **Context budget** — `createBudgetPolicy({ budgetTokens, summarize })`
+- **Hard cost caps** — `maxTotalTokens` / `maxCostUsd` (+ `priceOverrides` to price non-Anthropic models)
+- **Structured output** — `resultSchema`; `result.typed` is validated, or use `fromZod<T>()` for full type inference
+- **Middleware** — an onion chain around every capability call (auth, rate limiting, caching, audit)
+- **Cancellation / retries / streaming / tool concurrency** — `signal`, retry policy, `onText`, `maxToolConcurrency`
+
+## Observability & cost
+
+One run == one trace (`traceId === runId`), **built in from turn 0** — not a bolt-on third-party tracing SDK:
+
+- **Per-step accounting** — every span carries model, input/output/cache tokens, cost estimate, status and error type
+- **One seam out** — `TraceSink { export(trace) }`, delivered on **both** the success and failure paths; a throwing
+  sink never breaks the run. Persistence / sampling / redaction are composed outside the seam
+  (`examples/observability/`, [`docs/observability.md`](./docs/observability.md))
+- **Cost you can cap** — `priceOverrides` patches the price table; unpriced models emit an explicit
+  `usage.unpriced` event (never a silent zero); `maxCostUsd` / `maxTotalTokens` stop the run
+- **Replay** — `traceToMessages(trace)` linearises a finished trace back into model messages
+- **Export** — `createOtlpExporter({ endpoint })`; `metricsSink()` (Prometheus text or OTLP metrics), zero dependency
+- **Locally visible** — `agentia dev` opens an inspector panel sharing one renderer with the website Playground;
+  `agentia report <trace.jsonl>` ranks which capability is slow / expensive / error-prone
+
+## Integrations
+
+- **Models** — `createAnthropicClient()` (default) and `createOpenAIClient()` for any OpenAI-compatible
+  endpoint (DeepSeek, **Ollama**, gateways). You never need to touch a vendor SDK: pass
+  `createAnthropicClient({ baseURL })` / `createOpenAIClient({ baseURL })`.
+- **MCP** — `mcpTools()` bridges an MCP server's tools into the menu (duck-typed, zero dependency)
+- **Memory** — `memory: { store, keys }` for cross-run state; task stores: memory / JSONL / SQLite / Redis
+- **Evals** — `scriptedClient` + `defineEval` turn mocked runs into a first-class diagnostic loop
+- **Platforms** — send traces to Langfuse / Phoenix / etc. via OTLP or a tiny custom `TraceSink`
+  (see [`docs/observability.md`](./docs/observability.md) §2.6)
+
+## Documentation
+
+| | |
+|---|---|
+| Usage guide (authoritative, zh) | [`docs/usage-guide.md`](./docs/usage-guide.md) |
+| Production observability recipes | [`docs/observability.md`](./docs/observability.md) |
+| Examples (complete app / minimal deploy / observability) | [`examples/`](./examples/) |
+| Design spec & roadmap | [`docs/spec.md`](./docs/spec.md) · [`docs/roadmap.md`](./docs/roadmap.md) |
+| Website · Playground | [agentia-web.pages.dev](https://agentia-web.pages.dev) · [playground](https://agentia-web.pages.dev/playground.html) |
+
+## Contributing
+
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md) — and note that [`AGENTS.md`](./AGENTS.md) is the single
+source for this repo's engineering conventions. Security issues: [`SECURITY.md`](./SECURITY.md)
+(please don't open a public issue).
+
+## License
+
+[MIT](./LICENSE)

package/README.md

@@ -1,44 +1,70 @@
 # Agentia
 
-声明式 agent 服务开发框架：TS 装饰器 + DI，主 agent 调度 `@Tool` / `@Skill` / `@SubAgent` / `@Prompt` 单元执行任务，产出结构化结果与调用树（trace）。
+[中文](./README.md) · [English](./README.en.md)
 
-## 环境准备
+[![CI](https://github.com/retrychx/agentia/actions/workflows/ci.yml/badge.svg)](https://github.com/retrychx/agentia/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/@migor/agentia)](https://www.npmjs.com/package/@migor/agentia) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+面向应用开发的声明式 agent 服务开发框架：装饰器 + DI 声明四类能力，主 agent 编排执行；每次 run 产出结构化结果与可观测调用树（trace、成本、指标），交付可直接上线的服务。
+
+- [安装与配置](#安装与配置)
+- [快速开始](#快速开始)
+- [四类能力](#四类能力)
+- [运行时特性](#运行时特性)
+- [可观测性与成本](#可观测性与成本)
+- [集成](#集成)
+- [API 速查](#api-速查)
+- [开发本仓库](#开发本仓库)
+- [延伸阅读](#延伸阅读)
+
+## 安装与配置
 
 ```bash
-export ANTHROPIC_API_KEY=sk-...        # 或 ANTHROPIC_AUTH_TOKEN
+npm i @migor/agentia                 # 框架（项目依赖）
+npm i -g @migor/cli                  # 命令行工具（脚手架 / 生成 / 调试）
+
+agentia create my-app                # 脚手架（含 .env / .env.example）
+$EDITOR my-app/.env                  # 填 ANTHROPIC_API_KEY（也可直接 export，真实环境变量优先）
 # 可选：ANTHROPIC_BASE_URL（兼容端点）、AGENTIA_MODEL（缺省 claude-opus-5）
 ```
 
-## 快速开始（CLI）
+> 框架**不自动**读 `.env`：脚手架 `src/main.ts` 首行的 `loadEnvFile()` 负责把它读进 `process.env`。
+> 真实环境变量优先（CI / docker / 命令行永远赢过文件），`loadEnvFile({ override: true })` 才反过来。
+
+> **版本**：`0.3.0`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
+> `file:../..` 指向本仓库而不是 npm 版本 —— 跑的是**工作区代码**，理由见
+> [`examples/README.md`](examples/README.md) 的「依赖说明」。
+
+> **运行时**：Node ≥ 18（`engines` 唯一要求，CI 在 18/20/22 上守）。按 Node 设计并测试，
+> **未对 Deno / edge 做验证**。唯一碰内置模块的 store 是 `SqliteTaskStore`（需 Node ≥ 22.5 的
+> `node:sqlite`）—— 未提供时**构造期给可读报错**，不影响包本身被导入。
+
+
+## 快速开始
+
+两条路线，按需选一即可（也可混用）。
+
+### 路线 A：CLI 脚手架
 
 ```bash
-npm i -g @migor/cli                 # 安装 CLI（提供 agentia 命令）
 agentia create my-app                  # 脚手架新项目（依赖 @migor/agentia）
 cd my-app && npm install
-agentia g tool weather                 # 生成 units/weather/index.ts 并登记 units.ts
-agentia g subagent doc-reviewer        # 生成 units/doc-reviewer/{index.ts,system.md}
-agentia g skill note-writer            # 生成 units/note-writer/index.ts
-agentia g prompt style-guide           # 生成 units/style-guide/{index.ts,asset.md}
-npm run dev                            # 运行 src/main.ts
+agentia g tool weather                 # 生成 src/tools/weather/index.ts 并登记 src/registry.ts
+agentia g subagent doc-reviewer        # 生成 src/subagents/doc-reviewer/{index.ts,system.md}
+agentia g skill note-writer            # 生成 src/skills/note-writer/index.ts
+agentia g prompt style-guide           # 生成 src/prompts/style-guide/{index.ts,asset.md}
+agentia dev                            # tsx watch + 本地 inspector 面板
 ```
 
-**目录约定**：`units/<name>/` 一单元一文件夹，`index.ts` default export 一个 provider 类，DI token 缺省 = 文件夹名；长文本放文件夹内 `.md`，代码里用 `asset(import.meta.url, './system.md')` 读取。
+**目录约定**：四分类目录，一能力一文件夹 —— `src/tools/` · `src/skills/` · `src/prompts/` · `src/subagents/`。
+目录名就是类型，不用记别名。每个文件夹的 `index.ts` default export 一个 provider 类，DI token 缺省 = 文件夹名；
+长文本放文件夹内 `.md`，代码里用 `asset(import.meta.url, './system.md')` 读取。
 
-**装配两条路（可混用）**：
+### 路线 B：手写装配
 
-```ts
-// 1) 目录扫描：启动期扫描 units/*/ 自动装配（返回 Promise）
-const app = await createApp({ name: 'my-app', discover: 'units', system });
-
-// 2) 显式注册表：units.ts 由 CLI 自动维护
-import { providers } from './units.js';
-const app = createApp({ name: 'my-app', providers, system });
-```
-
-## 手写单元
+不依赖 CLI，直接声明能力并装配成应用：
 
 ```ts
-import { Tool, SubAgent, createApp, SystemPrompt, RunContext } from '@migor/agentia';
+import { Tool, createApp, SystemPrompt, RunContext } from '@migor/agentia';
 
 class WeatherTools {
   // 工具名缺省取方法名（建议 snake_case）；入参 = 模型按 schema 解析的结构化 input
@@ -53,30 +79,17 @@ class WeatherTools {
     strict: true,
   })
   get_weather(input: { city: string }): string {
-    // 方法体内随时可读本次 run 的上下文（blackboard）
-    const token = RunContext.current()?.get<string>('authToken');
+    // 方法体内随时可读本次 run 的上下文（blackboard）。
+    // 想让键有补全/校验：在一次 declare module 里合并 Blackboard（见 docs/usage-guide.md §5.1）；
+    // 未声明时键为 string、值为 unknown，这里按需断言。
+    const token = RunContext.current()?.get('authToken') as string | undefined;
     return `city=${input.city};token=${token ?? 'none'}`;
   }
 }
 
-class Pipeline {
-  // 子 agent：独立循环 + 裁剪上下文，只有最终报告回流主上下文（方法体不执行）
-  @SubAgent({
-    name: 'reviewer',
-    description: '审查给定文档并输出书面评审意见',
-    schema: { type: 'object', properties: { doc: { type: 'string' } }, required: ['doc'], additionalProperties: false },
-    system: '你是评审 agent。结论必须以“审查通过/不通过”开头。',
-    tools: ['weather'], // 子 agent 自己的工具菜单（provider token）
-  })
-  reviewer(_input: { doc: string }): void {}
-}
-
 const app = createApp({
   name: 'weather-app',
-  providers: [
-    { provide: 'weather', useClass: WeatherTools },
-    { provide: 'pipeline', useClass: Pipeline },
-  ],
+  providers: [{ provide: 'weather', useClass: WeatherTools }],
   system: new SystemPrompt().add('role', '你是天气助手。', true),
 });
 
@@ -88,9 +101,33 @@ console.log(result.finalText); // 最终文本
 console.log(result.trace);     // 调用树 + 每步 token/成本（traceId == runId）
 ```
 
-另外两类单元：
+装配还有**目录扫描**这条路（与显式注册表可混用）：
 
 ```ts
+// 按给定顺序扫各目录（返回 Promise）；也可用 CLI 维护的 src/registry.ts 显式注册
+const app = await createApp({
+  name: 'my-app',
+  discover: ['src/tools', 'src/skills', 'src/prompts', 'src/subagents'],
+  system,
+});
+```
+
+## 四类能力
+
+主 agent 按 `description` 从同一张「能力菜单」自选；装饰器只决定**谁控制流程**：
+
+| 能力 | 装饰器 | 谁决定流程 | 典型用途 |
+|---|---|---|---|
+| 工具 | `@Tool` | 你的代码（一次调用 = 一个函数） | 确定性操作：查库、算数、调 API |
+| 技能 | `@Skill` | 你的代码（脚本式，显式 `ctx.llm()`） | 「先取数 → 再让模型写 → 再加工」的固定流程 |
+| 子 agent | `@SubAgent` | **模型自己**（独立循环 + 裁剪上下文） | 自主多步、且中间过程不该污染主上下文 |
+| 提示资产 | `@Prompt` | 模型拉取（按需注入的文本） | 长文规范/模板，平时不进上下文 |
+
+`@Tool` 的写法见上方路线 B；其余三类：
+
+```ts
+import { Skill, SubAgent, Prompt, asset, type SkillContext } from '@migor/agentia';
+
 // @Skill：代码控制的流程，模型调用只发生在显式 ctx.llm()
 class Notes {
   @Skill({ description: '按主题整理要点' })
@@ -100,20 +137,53 @@ class Notes {
   }
 }
 
+// @SubAgent：独立循环 + 裁剪上下文，只有最终报告回流主上下文（方法体不执行）
+class Pipeline {
+  @SubAgent({
+    name: 'reviewer',
+    description: '审查给定文档并输出书面评审意见',
+    schema: { type: 'object', properties: { doc: { type: 'string' } }, required: ['doc'], additionalProperties: false },
+    system: '你是评审 agent。结论必须以“审查通过/不通过”开头。',
+    tools: ['weather'], // 子 agent 自己的工具菜单（provider token）
+  })
+  reviewer(_input: { doc: string }): void {}
+}
+
 // @Prompt：纯文本资产，模型判定需要时拉取进上下文
 class Assets {
   @Prompt({ description: '品牌基调文案规范' })
   style_guide(): string {
-    return asset(import.meta.url, './asset.md'); // 从单元文件夹读 .md
+    return asset(import.meta.url, './asset.md'); // 从能力文件夹读 .md
   }
 }
 ```
 
-## 触发方式
+四类一起装配（`providers` 里逐个登记；token 即子 agent / 技能引用工具的菜单名）：
+
+```ts
+import { createApp, SystemPrompt } from '@migor/agentia';
+
+const app = createApp({
+  name: 'weather-app',
+  providers: [
+    { provide: 'weather', useClass: WeatherTools },
+    { provide: 'notes', useClass: Notes },
+    { provide: 'pipeline', useClass: Pipeline },
+    { provide: 'assets', useClass: Assets },
+  ],
+  system: new SystemPrompt().add('role', '你是天气助手。', true),
+});
+```
+
+## 运行时特性
+
+### 触发方式
 
 同一份应用，三种触发任选：
 
 ```ts
+import { AsyncRunner, FileTaskStore, Scheduler } from '@migor/agentia';
+
 // 同步 RPC
 const { run, result } = await app.run(messages);
 
@@ -127,7 +197,7 @@ const scheduler = new Scheduler(runner);
 scheduler.every(60_000, '巡检一次', { idempotencyKey: 'patrol' });
 ```
 
-## 长上下文预算
+### 长上下文预算
 
 ```ts
 import { createBudgetPolicy } from '@migor/agentia';
@@ -135,22 +205,37 @@ import { createBudgetPolicy } from '@migor/agentia';
 const app = createApp({
   // ...
   contextPolicy: createBudgetPolicy({
-    budgetTokens: 60_000,   // 超预算先丢旧工具对，仍超且有 summarize 才压缩
+    budgetTokens: 60_000,    // 超预算先丢旧工具对，仍超且有 summarize 才压缩
     summarize: (text) => mySummarizer(text), // 可选，框架不替你调模型
   }),
 });
 ```
 
-## 中间件
+### 结构化结果
 
-挂在每一次单元调用前后的洋葱链——鉴权、限流、缓存、审计都走这里：
+```ts
+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); // 校验过的结构化结果，不再从文本里猜 JSON
+// schema 也可来自 zod（peer 可选）：fromZod(z.toJSONSchema(S), S)
+```
+
+### 中间件
+
+挂在每一次能力调用前后的洋葱链——鉴权、限流、缓存、审计都走这里：
 
 ```ts
 const app = createApp({
   // ...
   middleware: [
     async (call, next) => {
-      if (call.unit.name === 'danger_op' && !RunContext.current()?.get('isAdmin')) {
+      if (call.capability.name === 'danger_op' && !RunContext.current()?.get('isAdmin')) {
         return 'forbidden'; // 短路，不调 next 即拦截
       }
       return next(); // next(newInput) 还可改写入参
@@ -159,52 +244,86 @@ const app = createApp({
 });
 ```
 
-## 结构化结果
+## 可观测性与成本
+
+一次 run == 一条 trace（`traceId === runId`），**Turn 0 起内建** —— 不是外挂的第三方追踪 SDK 集成：
 
 ```ts
-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); // 校验过的结构化结果，不再从文本里猜 JSON
-// schema 也可来自 zod（peer 可选）：fromZod(z.toJSONSchema(S), S)
+const { run, result } = await app.run(messages);
+result.trace.spans;       // 调用树：llm.turn / 能力 span / 事件
+result.trace.totalUsage;  // token 汇总（只累加 llm.turn；能力 span 是子孙聚合，不参与求和）
 ```
 
-## 宿主、多模型与记忆
+- **每步记账**：span 属性带 model、input/output/cache tokens、成本估计、状态、错误类型
+- **出口是一条缝**：`TraceSink { export(trace) }` —— run 收尾（成功/失败两条路径）都投递，sink 抛错不影响 run。落库 / 采样 / 脱敏都在缝外用 sink 组合（实码见 `examples/observability/`，说明见 `docs/observability.md`）
+- **指标**：`metricsSink` 满足 `TraceSink` 即可接入（Prometheus 文本 / OTLP metrics），零依赖
+- **成本**：`priceOverrides` 注入价目表；未定价模型显式发 `usage.unpriced` 事件；`createBudgetGuard` 做**硬管控**（超限 run 以 `budget_exceeded` 收尾、算失败）
+- **调优闭环**：`buildRunReport` 出「能力 / 模型的耗时·token·成本·错误率排行」，CLI `agentia report <trace.jsonl>` 直接渲染
+- **回放**：`traceToMessages` 把已完成的 trace 线性化喂回模型（调试基底）
+- **本地开发**：`agentia dev` 的 inspector 面板与 `@migor/trace-view` 共用同一份渲染器（避免两处漂移）
+- **导出 OTLP**：
 
 ```ts
-// HTTP 宿主：POST /run（同步） POST /tasks（异步） GET /tasks/:id（轮询）
+import { createOtlpExporter } from '@migor/agentia';
+
+await createOtlpExporter({ endpoint: 'http://localhost:4318' }).export(result.trace);
+```
+
+> 权威口径见 `docs/usage-guide.md` 的「观测」与「成本硬管控」两节。
+
+## 集成
+
+### HTTP 宿主
+
+```ts
+import { createServer } from 'node:http';
+import { createHttpHandler } from '@migor/agentia';
+
+// POST /run（同步） POST /tasks（异步） GET /tasks/:id（轮询）
 createServer(createHttpHandler(app, { runner })).listen(8080);
+```
+
+### 多模型（OpenAI 兼容端点）
+
+```ts
+import { createOpenAIClient } from '@migor/agentia';
 
-// OpenAI 兼容端点（DeepSeek 等）+ 跨 run 记忆
 const { result } = await app.run(messages, {
   client: createOpenAIClient({ baseURL: 'https://api.deepseek.com' }),
   model: 'deepseek-chat',
-  memory: { store: new InMemoryMemoryStore(), keys: ['profile'] },
 });
+```
 
-// trace 导出到 OTLP 收集器
-await createOtlpExporter({ endpoint: 'http://localhost:4318' }).export(result.trace);
+> **本地模型（Ollama 等）**：Ollama 暴露 OpenAI 兼容端点，用同一个适配器即可 ——
+> `createOpenAIClient({ baseURL: 'http://localhost:11434/v1' })` + `model: 'qwen3'`，
+> **不需要任何新代码或新依赖**。
+
+
+### 跨 run 记忆
+
+```ts
+import { InMemoryMemoryStore } from '@migor/agentia';
+
+const { result } = await app.run(messages, {
+  memory: { store: new InMemoryMemoryStore(), keys: ['profile'] },
+});
 ```
 
-## 常用 API
+## API 速查
 
 | 导出 | 用途 |
 |---|---|
-| `createApp` / `discoverProviders` | 装配应用 / 扫描单元目录 |
+| `createApp` / `discoverProviders` | 装配应用 / 扫描能力目录 |
 | `defineModule` | 能力包（providers + middleware 打包分发） |
-| `Tool` / `Skill` / `SubAgent` / `Prompt` | 四类单元装饰器 |
-| `UnitMiddleware`（`middleware` 选项） | 单元调用拦截器链 |
-| `asset` | 读单元文件夹内的文本资产 |
+| `Tool` / `Skill` / `SubAgent` / `Prompt` | 四类能力装饰器 |
+| `CapabilityMiddleware`（`middleware` 选项） | 能力调用拦截器链 |
+| `asset` | 读能力文件夹内的文本资产 |
 | `SystemPrompt` | 拼装系统提示（自动打缓存 breakpoint） |
 | `RunContext.current()` | 取本次 run 的 blackboard / runId |
 | `AsyncRunner` / `Scheduler` / `runSync` / `createHttpHandler` | 异步 / 定时 / 同步 / HTTP 触发 |
 | `FileTaskStore` / `SqliteTaskStore` / `RedisTaskStore` / `InMemoryTaskStore` | 任务记录存储 |
 | `createBudgetPolicy` | 长上下文预算护栏 |
+| `createAnthropicClient` | 默认 ModelClient（Anthropic）：自定义只传 `apiKey` / `baseURL`，不必直接依赖厂商 SDK |
 | `createOpenAIClient` | OpenAI 兼容端点适配（多模型） |
 | `InMemoryMemoryStore`（`memory` 选项） | 跨 run 记忆水合/回写 |
 | `createOtlpExporter` | trace 导出 OTLP |
@@ -212,16 +331,27 @@ await createOtlpExporter({ endpoint: 'http://localhost:4318' }).export(result.tr
 | `fromZod` | zod schema 接入（peer 可选） |
 | `runAgent` / `executeRun` | 裸引擎入口（不走装配） |
 
-完整导出见 [`src/index.ts`](src/index.ts)，设计规格见 [`docs/spec.md`](docs/spec.md)，roadmap 见 [`docs/roadmap.md`](docs/roadmap.md)，官网见 [agentia-web.pages.dev](https://agentia-web.pages.dev)（含[在线 Playground](https://agentia-web.pages.dev/playground.html) 与[文档](https://agentia-web.pages.dev/docs.html)）。
-
-## 本仓库脚本
+## 开发本仓库
 
 ```bash
 npm install
 npm run build        # 编译框架（dist/）
 npm run typecheck    # 类型检查
+npm run lint         # lint + 格式检查（Biome）
 npm test             # 单元测试（node:test）
-npm run e2e          # 端到端：CLI 脚手架 → 目录发现/注册表装配 → mock run
+npm run e2e          # 端到端：CLI 脚手架 → 装配 mock run；再真跑 examples/complete 的完整服务
 ```
 
-> 注：`npm run dev`（tsx）前需先 `npm approve-scripts` 批准 esbuild/tsx 的 postinstall。
+> 注：本仓库的 `npm run dev`（tsx）前需先 `npm approve-scripts` 批准 esbuild/tsx 的 postinstall；
+> 脚手架项目里的 `agentia dev` 不受此限。
+
+## 延伸阅读
+
+- **使用者向完整说明**（API 速查 / 类型链路 / 已知边界 / 反例）：[`docs/usage-guide.md`](docs/usage-guide.md)
+- 完整导出清单：[`src/index.ts`](src/index.ts)
+- 设计规格：[`docs/spec.md`](docs/spec.md)
+- 生产可观测配方（落库检索 / 日志关联 / 采样 / 脱敏）：[`docs/observability.md`](docs/observability.md)
+- 完整示例（四类能力 + 三种触发 + 全观测栈）：[`examples/complete/`](examples/complete/)
+- 最小部署示例：[`examples/deploy/`](examples/deploy/)
+- 方向与状态：[`docs/roadmap.md`](docs/roadmap.md)
+- 官网：[agentia-web.pages.dev](https://agentia-web.pages.dev)（[在线 Playground](https://agentia-web.pages.dev/playground.html) · [文档](https://agentia-web.pages.dev/docs.html)）