@migor/agentia 0.9.4 → 0.10.0

package/README.en.md

@@ -8,6 +8,11 @@
 with decorators + DI and a main agent orchestrates them; every run yields structured output and an
 observable call tree (trace, cost, metrics).
 
+**1 package · ≈2 MB · 0 runtime dependencies · 90+ guards** — the answer to the first question when
+choosing a library (how big is the install?): `npm i @migor/agentia` puts exactly **one** package into
+`node_modules` and pulls in no vendor SDK. These numbers are recomputed by
+`tests/docs/scoreboard.test.ts` on every run; hand-written figures rot.
+
 > 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
@@ -15,9 +20,11 @@ observable call tree (trace, cost, metrics).
 
 ## 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.
+Node.js **≥ 18** (the only `engines` requirement). CI covers **18 / 20 / 24** — the `import-floor`
+matrix pins the floor declared in `engines`, every other job follows the current LTS. 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
 
@@ -143,6 +150,57 @@ One run == one trace (`traceId === runId`), **built in from turn 0** — not a b
 | 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) |
 
+## Stability & versioning
+
+**What `0.x` means here:** versions follow SemVer, but during `0.x` a **minor release may contain a
+breaking change**. There is exactly one rule — **a breaking change must leave a trace**: that version's
+`CHANGELOG.md` entry carries a dedicated section (its heading contains 「迁移」 or 「破坏性变更」)
+stating what **you** have to change.
+
+```bash
+grep -nE '^#{3,4} .*(迁移|破坏性)' CHANGELOG.md    # every "you must act" section
+```
+
+> Honest caveat: this discipline was **tightened over time** — early versions (`0.7.1`, a type-level
+> change) put the action in the entry's leading blockquote instead of its own section. The command
+> above is a **lower bound**, not the whole set. And this README deliberately prints **no**
+> "N releases / M migrations" count: hand-written counts rot, so we ship the command instead.
+
+**What is covered by the compatibility promise:** the **named exports** of `@migor/agentia`
+(`src/index.ts` is the source of truth) and the `@migor/cli` command surface, plus the Node range in
+`engines.node` — CI runs the full chain on every version in that range. **Not covered:** deep imports
+(`dist/**`) — **sealed by the `exports` field** in `package.json` (guarded by
+`tests/architecture/package-exports.test.ts`; before `exports` existed they really did resolve) —
+internal module paths, `packages/*`, `examples/*`, Deno / Bun / edge runtimes (unvalidated),
+and anything a release does not spell out in its migration note. Runtime third-party dependencies are
+**zero** — enforced by `tests/architecture/no-runtime-deps.test.ts`, not by promise.
+
+**What 1.0 waits for** (all three are checkable): every open item in `docs/spec.md` §11 is either
+shipped or explicitly struck out; `docs/guards.md` §2 ("awaiting a guard") is empty; and the public
+export surface has gone **three consecutive minors with no breaking change**.
+
+## Performance order of magnitude
+
+Five benchmarks ship with the repo (`scripts/bench-*.ts`). They answer **shape** questions — which
+cost you pay under which condition, and what a different implementation could remove — not an SLA:
+
+| Question | Local reading (macOS / Node 24 — **order of magnitude**) | Shape (the part that **does not** move with the machine) | Re-run |
+| --- | --- | --- | --- |
+| Cost of assembling an app | pure assembly `0.4 ms`; discover + assemble `8.1 ms`; whole-process boot + assemble `4040 ms` (of which cold assembly ≈2963 ms; the bare process boot alone is 1077 ms) | Swapping capability selection in a **resident runner** pays only `S2` (≈8 ms), not `S6b` (≈4 s) ⇒ **~500×**. ~1.1 s of that 4 s is the `tsx` interpreter booting — nothing to do with the framework | `npm run bench:assembly` |
+| When an MCP connector costs you | cold (spawn + initialize + list) `279.5 ms`; warm (reused connector, one `tools/list` round trip) `0.3 ms` | Only **rebuilding** the connector pays the cold one ⇒ **~900×**. So whether "rebuilding the app includes an MCP handshake" is true **depends on what the connector's lifetime is** | `npm run bench:assembly` |
+| What recording trace content costs | large tool output (≈37 KB/call), 5 calls: default `17.2 KB` / untruncated `233.9 KB` (**13.6×**) / truncate-200 `6.2 KB`; 20 calls: `65 KB → 932 KB` (14.3×) | The default **already truncates** (the ≈14× gap comes from turning truncation off). `traceContent:'full'` is priced **per output byte** — at small output size the measured gap is 1.0× | `PAYLOAD_ROWS=1000 CALLS='[5,20]' npm run bench:trace` |
+| Cost of a metrics snapshot / OTLP flush | `snapshot()` `6.56 ms` (30 series × 2 percentiles); `buildOtlpPayload()` `0.073 ms` | Flush cost is **almost entirely `snapshot()`** ⇒ skipping it saves ≈6.5 ms per flush, **proportional to flush frequency**, unrelated to whether OTLP is consumed | `npm run bench:otlp` |
+| Scanning suspended tasks for due time | sqlite N=10000: full `list()` `61.9 ms` / due index `listDue` `0.1 ms`; file store N=10000: `load` `69.5 ms`, `list` `0.0 ms` | **Having an index** is structural (**~600×**), not a tuning knob. The file store keeps records in memory ⇒ its expensive pass is the **full `load` at construction** | `npx tsx scripts/bench-resume-scan.ts 10000` |
+| Shape of the redis store's `list()` | N=10000: **10001** round trips, **42.1 MB** parsed, `104.1 ms` pure CPU; with a helper ZSET (`score = wakeAt`) ⇒ **1001** round trips | Round-trip count is **structural** (that is what another implementation can remove); no local redis here, so latency is extrapolated only (RTT 0.2 ms ⇒ 2 s) | `npx tsx scripts/bench-redis-due.ts 10000` |
+
+> ⚠️ **The milliseconds are not a promise** — they move with the machine, the Node version and the
+> load; copying them as an SLA will be wrong. What is actually constant is the **shape** (how many
+> times larger, how many round trips, what scales with what).
+>
+> The five benchmarks are **deliberately not in CI** (timing benchmarks only add noise on CI machines;
+> `docs/plans/2026-09-22-dev-debug-loop.md` settled on "run them when you want to look") ⇒ nothing
+> guards the numbers below — re-run the command in the last column.
+
 ## Contributing
 
 See [`CONTRIBUTING.md`](./CONTRIBUTING.md) — and note that [`AGENTS.md`](./AGENTS.md) is the single

package/README.md

@@ -6,6 +6,10 @@
 
 面向应用开发的声明式 agent 服务开发框架：装饰器 + DI 声明四类能力，主 agent 编排执行；每次 run 产出结构化结果与可观测调用树（trace、成本、指标），交付可直接上线的服务。
 
+**1 个包 · ≈2 MB · 0 运行时依赖 · 90+ 条守卫** —— 这一组数是选型第一个问题（安装面有多大）的答案：
+`npm i @migor/agentia` 只往 `node_modules` 放**一个**包，不装任何厂商 SDK。
+数字由 `tests/docs/scoreboard.test.ts` 每次现场复算，**手写的读数会腐烂**（本仓的老病）。
+
 - [安装与配置](#安装与配置)
 - [快速开始](#快速开始)
 - [四类能力](#四类能力)
@@ -13,6 +17,8 @@
 - [可观测性与成本](#可观测性与成本)
 - [集成](#集成)
 - [API 速查](#api-速查)
+- [稳定性与版本策略](#稳定性与版本策略)
+- [性能量级](#性能量级)
 - [开发本仓库](#开发本仓库)
 - [延伸阅读](#延伸阅读)
 
@@ -36,11 +42,12 @@ npm run dev                          # = agentia dev：本地 inspector 面板
 > 从不执行 main.ts —— 写错一侧会让 `npm run dev` 静默读不到 `.env` 而 `npm start` 读得到。
 > 真实环境变量优先（CI / docker / 命令行永远赢过文件），`loadEnvFile({ override: true })` 才反过来。
 
-> **版本**：`0.9.4`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
+> **版本**：`0.10.0`（`@migor/agentia` 与 `@migor/cli` 均已发布到 npm）。`examples/` **刻意**用
 > `file:../..` 指向本仓库而不是 npm 版本 —— 跑的是**工作区代码**，理由见
 > [`examples/README.md`](examples/README.md) 的「依赖说明」。
 
-> **运行时**：Node ≥ 18（`engines` 唯一要求，CI 在 18/20/22 上守）。按 Node 设计并测试，
+> **运行时**：Node ≥ 18（`engines` 唯一要求）。CI 覆盖 **18 / 20 / 24** —— `import-floor` 矩阵跑
+> `engines` 声明的**下限**，其余 job 跟**当前 LTS** 走。按 Node 设计并测试，
 > **未对 Deno / edge 做验证**。唯一碰内置模块的 store 是 `SqliteTaskStore`（需 Node ≥ 22.5 的
 > `node:sqlite`）—— 未提供时**构造期给可读报错**，不影响包本身被导入。
 
@@ -200,7 +207,7 @@ await runner.awaitTask(task.taskId);
 
 // 定时
 const scheduler = new Scheduler(runner);
-scheduler.every(60_000, '巡检一次', { idempotencyKey: 'patrol' });
+scheduler.every(60_000, '巡检一次', { idempotencyPrefix: 'patrol' });
 ```
 
 ### 长上下文预算
@@ -359,6 +366,60 @@ const { result } = await app.run(messages, {
 | `fromZod` | zod schema 接入（peer 可选） |
 | `runAgent` / `executeRun` | 裸引擎入口（不走装配） |
 
+## 稳定性与版本策略
+
+**`0.x` 的含义**：版本号按 SemVer，但 `0.x` 期间 **minor 版本可以包含破坏性变更**。
+规矩只有一条 —— **破坏性变更必须留痕**：`CHANGELOG.md` 对应的那个版本里要有一段专门写它
+（小节标题含「迁移」或「破坏性变更」），写清「**你要改什么**」。
+
+```bash
+grep -nE '^#{3,4} .*(迁移|破坏性)' CHANGELOG.md    # 列出所有「要你做动作」的小节
+```
+
+> ⚠️ **如实标注**：这条纪律是**逐步收紧**的 —— 早期的 `0.7.1`（类型面变更）把动作写在版本条目
+> 开头的引用块里、没有独立小节，`0.8.1`~`0.8.3` 用一行「**迁移**：无」表态。⇒ 上面那条命令是
+> **下限**而非全集，要读全就通读该版本的条目。
+> **「N 个版本 / M 次迁移」这类读数本 README 刻意不写死** —— 写死的读数会腐烂（本仓为此吃过教训），
+> 所以给命令、不给数字。
+
+**承诺的范围**：
+
+| 面 | 承诺 | **不**承诺 |
+|---|---|---|
+| 公共 API | `@migor/agentia` 的**具名导出**（真源 `src/index.ts`；官网 API 页有反向全覆盖守卫）+ `@migor/cli` 的命令行面 | 深路径导入（`dist/**`）、`src/**` 内部模块路径、`packages/*`、`examples/*` —— 这条边界**由 `package.json` 的 `exports` 字段封着**（`tests/architecture/package-exports.test.ts` 守；加 `exports` 之前 `dist/**` 真的导得进来） |
+| 行为 | 该版本条目里写明的**迁移动作** | 没写进迁移说明的任何行为变化 |
+| 运行环境 | `engines.node` 声明的区间；CI 在**该区间内每个版本**上跑完整条链 | Deno / Bun / edge runtime（**未验证**）；已 EOL 的 Node（会随 minor 去掉） |
+| 依赖 | **运行时零第三方依赖**（`tests/architecture/no-runtime-deps.test.ts` 守着，非口头承诺） | `devDependencies` 与 `examples/*` 的依赖面 |
+
+**1.0 的门槛**（三条都是可核验的，不是口号）：
+
+1. `docs/spec.md` §11「开放项」里每一条要么落地、要么被**明确划掉**（写清为什么不阻塞）；
+2. `docs/guards.md` §2「待守」为空 —— 已声明的边界都由机器守着，而不是靠人记得；
+3. 公共导出面**连续 3 个 minor 无破坏性变更**。
+
+在此之前，请把每个 minor 当成「**这次修的可能是某个承诺没兑现的地方**」——这正是 `0.x` 的含义，
+也是 `CHANGELOG.md` 每条都写「为什么」而不是「做了什么」的原因。
+
+## 性能量级
+
+框架自带五个基准（`scripts/bench-*.ts`）。它们要回答的是**形状**问题（哪笔钱在什么条件下付、
+换实现能省掉的是什么），不是给你一个 SLA：
+
+| 你想问的 | 本机读数（macOS / Node 24，**量级**） | 形状结论（**不会随机器变**的那部分） | 复跑 |
+| --- | --- | --- | --- |
+| 装配一次 app 多贵 | 纯装配 `0.4 ms`；发现+装配 `8.1 ms`；整进程启动+装配 `4040 ms`（其中「冷装配」≈2963 ms，整进程启动本身就 1077 ms） | 「换一次能力选择」在**常驻 runner** 里只付 `S2`（≈8 ms），**不需要**付 `S6b`（≈4 s）⇒ 差 **~500×**。那 4 s 里 ~1.1 s 是 `tsx` 解释器启动，与框架无关 | `npm run bench:assembly` |
+| MCP 连接器什么时候付钱 | 冷（spawn + initialize + list）`279.5 ms`；热（复用连接器，仅一次 `tools/list`）`0.3 ms` | 只有**重建连接器**才付冷的那一笔 ⇒ 差 **~900×**。所以「重建 app 含 MCP 握手」成不成立，**取决于连接器跟谁同寿** | `npm run bench:assembly` |
+| trace 记不记内容，差多少 | 大出参（≈37 KB/次）5 次调用：缺省 `17.2 KB` / 不截断 `233.9 KB`（**13.6×**）/ 截断 200 `6.2 KB`；20 次：`65 KB → 932 KB`（14.3×） | 缺省**已经截断**（≈14× 的量级差来自关掉截断）。`traceContent:'full'` 是**按出参字节付费**的开关 —— 小出参档实测只差 1.0× ⇒ 代价与你的出参多大成正比 | `PAYLOAD_ROWS=1000 CALLS='[5,20]' npm run bench:trace` |
+| 指标快照 / OTLP flush 的成本 | `snapshot()` `6.56 ms`（30 个组合 × 2 次分位）；`buildOtlpPayload()` `0.073 ms` | flush 的成本**几乎全在 `snapshot()`** ⇒ 省掉它 ≈ 每次 flush 省 6.5 ms，**与 flush 频率成正比**，与 OTLP 是否被消费无关 | `npm run bench:otlp` |
+| 挂起任务的到期扫描 | sqlite N=10000：全表 `list()` `61.9 ms` / 走到期索引 `listDue` `0.1 ms`；file store N=10000：`load` `69.5 ms`、`list` `0.0 ms` | **有没有索引**是结构性的（差 **~600×**），不是调优问题。file store 的记录在内存里 ⇒ 它贵的那笔是**构造期的全表 `load`** | `npx tsx scripts/bench-resume-scan.ts 10000` |
+| redis store 的 `list()` 形状 | N=10000：往返 **10001** 次、解析 **42.1 MB**、纯 CPU `104.1 ms`；有辅助 ZSET（`score = wakeAt`）⇒ 往返 **1001** | 往返次数是**结构量**（换实现能省掉的就是它）；本机无 redis 实例，延迟只做外推（RTT 0.2ms ⇒ 2 s） | `npx tsx scripts/bench-redis-due.ts 10000` |
+
+> ⚠️ **毫秒数不是承诺**：它们随机器 / Node 版本 / 负载而变，抄走当 SLA 会错。
+> 真正恒定的是**形状**（差多少倍、往返几次、哪一笔跟什么成正比）—— 那才是这五个基准要说的东西。
+>
+> 五个基准**刻意不进 CI**（计时类基准在 CI 机器上只会制造抖动；`docs/plans/2026-09-22-dev-debug-loop.md`
+> 定下的处置是「要看时跑」）⇒ 上表的数**没有守卫帮你盯着**，要看就按「复跑」那一列自己跑一遍。
+
 ## 开发本仓库
 
 ```bash
@@ -379,6 +440,7 @@ npm run e2e          # 端到端：CLI 脚手架 → 装配 mock run；再真跑
 - 完整导出清单：[`src/index.ts`](src/index.ts)
 - 设计规格：[`docs/spec.md`](docs/spec.md)
 - 生产可观测配方（落库检索 / 日志关联 / 采样 / 脱敏）：[`docs/observability.md`](docs/observability.md)
+- 上线清单（store 选型 / 鉴权边界 / 优雅停机 / 预算 / 回滚 / 上线自检）：[`docs/deployment.md`](docs/deployment.md)
 - 完整示例（四类能力 + 三种触发 + 全观测栈）：[`examples/complete/`](examples/complete/)
 - 最小部署示例：[`examples/deploy/`](examples/deploy/)
-- 官网：[agentia-web.pages.dev](https://agentia-web.pages.dev)（[在线 Playground](https://agentia-web.pages.dev/playground) · [文档](https://agentia-web.pages.dev/docs)）
+- 官网：[agentia-web.pages.dev](https://agentia-web.pages.dev)（[在线 Playground](https://agentia-web.pages.dev/playground) · [文档](https://agentia-web.pages.dev/docs) · [取舍对照：不做什么 / 什么场景该选别人](https://agentia-web.pages.dev/tradeoffs)）