@jun133/athlete 0.0.2

package/spec/implementation//347/233/256/345/275/225/347/273/223/346/236/204/345/210/260/344/273/243/347/240/201/346/226/207/344/273/266/346/230/240/345/260/204/350/241/250.md

@@ -0,0 +1,101 @@
+# 目录结构到代码文件映射表
+
+## 当前主要目录
+
+- `src/agent/`: 主循环、prompt、continuation、verification、closeout
+- `src/agent/checkpoint/`: checkpoint 归一化、推导、resume 输入、prompt block
+- `src/agent/runtimeMetrics/`: runtime metrics 累积与 runtime summary
+- `src/tools/`: 模型可见工具与 handler
+- `src/skills/`: skill schema、discovery、matching、loading、workflow guard
+- `src/mcp/`: MCP 总接入层
+- `src/mcp/playwright/`: Playwright MCP 配置、路径、artifact、调用归一化
+- `src/context/`: repo root、state root、AGENTS、skills、ignore 发现
+- `src/config/`: 配置读取、环境变量、runtime config、app paths
+- `src/tasks/`: 持久化 task 真相源
+- `src/team/`: teammate、消息、协议、policy
+- `src/background/`: 后台任务
+- `src/worktrees/`: 目录隔离
+- `src/subagent/`: 一次性子智能体
+- `src/interaction/`: 共享交互控制层与 shell 契约
+- `src/shell/cli/`: CLI shell 输入、输出、turn 展示、intro
+- `src/ui/`: CLI 文本格式化、runtime summary 和兼容导出
+- `src/telegram/`: Telegram 私聊通道、delivery、附件、CLI、process lock
+- `src/weixin/`: Weixin 私聊通道、OpeniLink client、delivery、context_token、CLI、process lock
+
+## 当前 lightweight context 对应代码
+
+- `src/agent/promptSections.ts`: static / dynamic prompt layer
+- `src/agent/toolResultStorage.ts`: externalized tool result 落盘
+- `src/agent/toolResultPreview.ts`: tool payload 预览与 transport 压缩
+- `src/tools/files/toolResultArtifact.ts`: `.athlete/tool-results/...` 的紧凑 artifact read
+- `src/agent/contextBuilder.ts`: 使用轻量 payload 的请求上下文构建
+
+## 当前 checkpoint / continuation 对应代码
+
+- `src/agent/checkpoint.ts`: checkpoint 对外导出面
+- `src/agent/checkpoint/base.ts`: checkpoint 默认结构与从 session 派生
+- `src/agent/checkpoint/state.ts`: checkpoint 归一化与生命周期更新
+- `src/agent/checkpoint/derivation.ts`: completedSteps / nextStep / artifact 推导
+- `src/agent/checkpoint/prompt.ts`: checkpoint 恢复输入与 prompt block
+- `src/agent/turnPersistence.ts`: turn 开始、yield、recovery、tool batch 的 session 持久化接线
+- `src/agent/managedTurn.ts`: continuation 输入通过 checkpoint 生成
+
+## 当前 runtime metrics / 仪表盘 对应代码
+
+- `src/agent/runtimeMetrics.ts`: runtime metrics 对外导出面
+- `src/agent/runtimeMetrics/state.ts`: `runtimeStats` 归一化与事件累积
+- `src/agent/runtimeMetrics/summary.ts`: session runtime summary 生成
+- `src/agent/api.ts`: provider request timing 与 provider usage 采集
+- `src/agent/runTurn.ts`: tool execution、compression、recovery 等运行事件统计接线
+- `src/ui/runtimeSummary.ts`: 交互态 runtime summary 文本格式化
+- `src/interaction/localCommands.ts`: 共享本地命令语义与 `/runtime` / `/stats` / `/仪表盘` 路由
+- `src/ui/localCommands.ts`: CLI 默认输出适配与兼容导出
+
+## 当前交互 shell 对应代码
+
+- `src/interaction/sessionDriver.ts`: 共享交互 session loop、multiline、interrupt、turn 生命周期
+- `src/interaction/shell.ts`: `InteractionShell` / `ShellInputPort` / `ShellOutputPort` / `InteractionTurnDisplay`
+- `src/shell/cli/readlineInput.ts`: CLI 输入适配
+- `src/shell/cli/output.ts`: CLI 文本输出适配
+- `src/shell/cli/turnDisplay.ts`: CLI spinner + stream renderer 适配
+- `src/shell/cli/intro.ts`: CLI banner 与 launch hints
+- `src/shell/cli/shell.ts`: CLI shell 组装
+- `src/ui/interactive.ts`: CLI 入口薄壳，组装 shell 并启动共享 driver
+
+## 当前 Playwright MCP 对应代码
+
+- `src/mcp/config.ts`: MCP 配置归一化
+- `src/mcp/playwright/config.ts`: Playwright MCP 配置归一化与 server args
+- `src/mcp/playwright/paths.ts`: `.athlete/playwright-mcp/` 路径约定
+- `src/mcp/playwright/artifacts.ts`: artifact 目录准备、迁移、生成配置
+- `src/mcp/playwright/invoke.ts`: relative filename 归一化
+- `src/mcp/stdioClient.ts`: 真实 stdio MCP client
+- `src/mcp/toolAdapter.ts`: MCP tool 适配进 Athlete registry
+- `src/tools/runtimeRegistry.ts`: runtime registry 组装 built-in tools 与 MCP tools
+
+## 当前 closeout / verification 对应代码
+
+- `src/agent/finalize.ts`: tool-less turn 的最终收口与 verification / pause 行为
+- `src/agent/closeout.ts`: closeout 阶段的工具过滤与 stale todo 容忍规则
+- `src/agent/verificationState.ts`: verification 真相源
+- `src/agent/verificationSignals.ts`: lightweight verification signals 与 auto-readback
+- `src/agent/runTurn.ts`: 调度这些规则，但不持有它们的内部实现细节
+
+## 当前文档 / 验证位置
+
+- `skills/web-research/SKILL.md`
+- `skills/browser-automation/SKILL.md`
+- `spec/modules/lightweight-context-runtime.md`
+- `spec/modules/session-resume-compact.md`
+- `spec/modules/runtime-metrics.md`
+- `tests/playwright-mcp.test.ts`
+- `tests/browser-tool-priority.test.ts`
+- `tests/playwright-workflow-guard.test.ts`
+- `tests/agent-closeout.test.ts`
+- `tests/runtime-lightweight-context.test.ts`
+- `tests/runtime-checkpoint-resume.test.ts`
+- `tests/runtime-observability.test.ts`
+- `scripts/verify-runtime-lightweight-context-api.mjs`
+- `scripts/verify-runtime-checkpoint-api.mjs`
+- `scripts/verify-runtime-observability-api.mjs`
+- `validation/`

package/spec/interfaces/InteractionShell.md

@@ -0,0 +1,85 @@
+# InteractionShell
+
+## 作用
+
+`InteractionShell` 是共享交互控制层和具体外壳之间的正式边界。
+
+它让 Athlete 的交互 session loop 可以复用同一个大脑，同时替换 CLI、桌面等不同壳。
+
+## 当前真实能力
+
+### 参与者
+
+- `InteractiveSessionDriver`: 共享交互控制器
+- `InteractionShell`: 壳总接口
+- `ShellInputPort`: 输入端口
+- `ShellOutputPort`: 输出端口
+- `InteractionTurnDisplay`: turn 展示端口
+
+### 当前契约语义
+
+#### `ShellInputPort`
+
+负责：
+
+- 读取普通输入
+- 读取 multiline 输入
+- 绑定 interrupt 事件
+
+不负责：
+
+- 决定 task / runtime 真相
+- 自己执行 agent turn
+
+#### `ShellOutputPort`
+
+负责：
+
+- 输出 `plain / info / warn / error / dim / heading / tool / interrupt`
+- 保持壳自己的展示风格
+
+不负责：
+
+- 修改 session 真相
+- 决定本地命令语义
+
+#### `InteractionTurnDisplay`
+
+负责：
+
+- 接收 turn 生命周期内的 `AgentCallbacks`
+- 展示流式 assistant / reasoning / tool 状态
+- 在 turn 结束或中断时 flush / dispose
+
+#### `InteractionShell`
+
+负责把上面三部分组装给共享 driver 使用。
+
+## 当前 CLI 实现
+
+- `src/shell/cli/readlineInput.ts`
+- `src/shell/cli/output.ts`
+- `src/shell/cli/turnDisplay.ts`
+- `src/shell/cli/shell.ts`
+
+CLI 当前通过这些适配器接入：
+
+- `readline`
+- `process.stdin` / `process.stdout`
+- `chalk`
+- spinner / stream renderer
+
+这些都必须留在 CLI shell 内，不进入共享 driver。
+
+## 规则
+
+1. `InteractiveSessionDriver` 不能依赖 `readline`、stdio、`chalk`。
+2. shell 只能提供输入、输出和 turn 展示适配，不能把控制面状态偷搬到壳里。
+3. 本地命令的语义应落在共享交互层，shell 只负责把结果显示出来。
+4. interrupt 的来源可以因壳不同而不同，但共享 driver 的 abort 语义必须一致。
+
+## 未来方向
+
+- 桌面壳可以实现自己的 `ShellInputPort`，例如输入框提交、多行编辑器、停止按钮。
+- 桌面壳可以实现自己的 `ShellOutputPort` / `InteractionTurnDisplay`，例如富文本消息区和状态面板。
+- 未来如果出现 web / mobile 壳，也应优先复用这组契约，而不是复制一套 session loop。

package/spec/interfaces/ProviderAdapter.md

@@ -0,0 +1,23 @@
+# ProviderAdapter
+
+## 作用
+
+ProviderAdapter 把 Athlete 的请求发送到具体模型服务，并返回统一结果。
+
+## 最小职责
+
+- 接收消息数组
+- 接收模型名
+- 接收工具定义
+- 返回 assistant 文本、reasoning、tool calls
+- 对常见 provider 错误提供可恢复语义
+
+## 不负责
+
+- 任务拆分
+- 控制面状态判断
+- 工具执行
+
+## 稳定边界
+
+只要 adapter 还能提供统一输出，底层 provider 可以继续替换。

package/spec/interfaces/README.md

@@ -0,0 +1,17 @@
+# 接口契约
+
+这一组文档不追求把所有 TypeScript 细节抄一遍。
+
+它们只说明 Athlete 内核最关键的抽象边界：
+
+- provider adapter
+- runtime loop
+- session store
+- tool registry
+- interaction shell
+
+## 使用规则
+
+1. 接口文档写稳定边界，不写瞬时实现细节。
+2. 新能力优先问“该落在哪个接口”，再问“该落在哪个文件”。
+3. 如果某个改动让接口职责明显变混，优先拆接口。

package/spec/interfaces/RuntimeLoop.md

@@ -0,0 +1,28 @@
+# RuntimeLoop
+
+## 作用
+
+RuntimeLoop 负责驱动一个 turn，直到：
+
+- 完成
+- 暂停
+- yield
+- 报错
+
+## 最小职责
+
+- 组装请求上下文
+- 读运行时状态
+- 调模型
+- 执行工具
+- 处理 continuation / compact / verification
+
+## 不负责
+
+- 保存长期任务真相
+- 发明新工具
+- 实现具体业务流程
+
+## 下一阶段要求
+
+总指挥层可以成为 loop 的上游决策来源，但不能把 RuntimeLoop 变成一个巨大的业务文件。

package/spec/interfaces/SessionStore.md

@@ -0,0 +1,22 @@
+# SessionStore
+
+## 作用
+
+SessionStore 负责保存和恢复任务现场。
+
+## 最小职责
+
+- 创建 session
+- 追加消息
+- 保存 todo / verification / taskState
+- 加载既有 session
+
+## 不负责
+
+- 任务板真相
+- teammate roster
+- worktree 生命周期
+
+## 关键要求
+
+session 恢复不能破坏 Athlete 的耐跑能力。

package/spec/interfaces/ToolRegistry.md

@@ -0,0 +1,21 @@
+# ToolRegistry
+
+## 作用
+
+ToolRegistry 负责统一管理模型可见工具。
+
+## 最小职责
+
+- 返回工具定义
+- 按名称执行工具
+- 根据 mode / runtime 过滤工具集
+
+## 不负责
+
+- provider 请求
+- session 存储
+- 任务真相维护
+
+## 关键要求
+
+无论未来 tools、skills、MCP 怎么扩，模型看到的动作入口都要保持统一。

package/spec/modules/config-system.md

@@ -0,0 +1,51 @@
+# config system
+
+## 作用
+
+配置系统负责统一读取 Athlete 的运行参数，并把项目级默认值、用户配置和环境变量合并成最终 runtime config。
+
+## 当前范围
+
+- API key / base URL / model
+- mode
+- paths
+- MCP 总开关与 server 配置
+- Playwright MCP repo 级默认值
+- context / continuation / read limits 等运行阈值
+
+## 当前规则
+
+1. 配置入口统一。
+2. 业务模块不直接散读环境变量。
+3. 用户能从 runtime config 理解当前行为从哪来。
+4. 项目级默认值允许放在 `.athlete/.env`，但仍由统一配置入口解析。
+
+## Playwright MCP 当前事实
+
+当前支持的 repo 级 Playwright MCP 环境变量：
+
+- `ATHLETE_MCP_ENABLED`
+- `ATHLETE_MCP_PLAYWRIGHT_ENABLED`
+- `ATHLETE_MCP_PLAYWRIGHT_BROWSER`
+- `ATHLETE_MCP_PLAYWRIGHT_HEADLESS`
+- `ATHLETE_MCP_PLAYWRIGHT_OUTPUT_MODE`
+- `ATHLETE_MCP_PLAYWRIGHT_SAVE_SESSION`
+
+当前仓库默认行为：
+
+- Playwright MCP 在项目级 `.athlete/.env` 中默认启用
+- 默认浏览器为 `chrome`
+- 默认不是 headless
+- 默认 output mode 为 `file`
+- 默认 save session 为开启
+
+## 路径约定
+
+当前 Playwright MCP 状态目录：
+
+- `.athlete/playwright-mcp/config.json`
+- `.athlete/playwright-mcp/profile/`
+- `.athlete/playwright-mcp/output/`
+- `.athlete/playwright-mcp/legacy-root-artifacts/`
+
+这些路径由配置系统和 `src/mcp/playwright/` 统一导出，不允许在调用侧随意拼接。

package/spec/modules/interactive-terminal.md

@@ -0,0 +1,112 @@
+# interactive terminal
+
+## 作用
+
+交互终端是 Athlete 的表现层外壳，不是控制面真相源。
+
+## 当前真实能力
+
+### 当前分层
+
+- `src/interaction/`: 共享交互控制层
+- `src/shell/cli/`: CLI shell 适配层
+- `src/ui/`: CLI 文本格式化、runtime summary 和兼容导出
+
+### 共享交互控制层职责
+
+- 驱动交互 session loop
+- 处理普通输入和 multiline 分支
+- 处理本地命令路由
+- 管理 turn in-flight 状态与 abort controller 生命周期
+- 接线 `runManagedAgentTurn`
+- 维护当前 session 的内存态，并在 turn 完成后接收最新 session
+
+### 当前 CLI shell 职责
+
+- 提供 persistent input / multiline input
+- 绑定终端 interrupt
+- 展示 assistant 流式输出
+- 展示 tool 调用和状态消息
+- 展示 banner、launch hints、dim/warn/plain/stderr 风格
+- 展示当前 session 的 runtime summary
+
+## 规则
+
+1. UI 不能反向定义 task、protocol、worktree、checkpoint、runtimeStats 等控制面事实。
+2. spinner、stream renderer、本地命令格式化都只属于表现层。
+3. Athlete 可以替换 UI，但不能因此破坏 runtime kernel。
+4. `/runtime`、`/stats`、`/仪表盘` 只是 `SessionRecord.runtimeStats` 的只读 summary 视图。
+5. UI 可以读取并展示真相源，但不能绕过真相源另造状态。
+6. 交互 session loop 不能直接绑死 `readline`、`process.stdin/stdout`、`chalk` 这类 CLI 细节。
+7. shell 只能提供输入、输出和 turn 展示适配，不能自己发明 task / protocol / runtime 真相。
+## 当前本地命令入口
+
+- `/session`
+- `/config`
+- `/todos`
+- `/tasks`
+- `/team`
+- `/background`
+- `/worktrees`
+- `/inbox`
+- `/runtime`
+- `/stats`
+- `/仪表盘`
+- `/reset`
+
+## Runtime Summary 展示范围
+
+当前交互态最小 runtime summary 包含：
+
+- session health
+- model request count
+- model wait total
+- tool call count
+- tool duration total
+- yield / continuation / recovery / compression count
+- externalized result count / bytes
+- top tools
+
+## Reset Boundary
+
+- `/reset` 是显式 destructive local command，不是普通的窗口关闭动作。
+- `/reset` 清空当前项目 `.athlete/` 下的运行时状态，但保留 `.athlete/.env` 和 `.athlete/.env.example`。
+- `/reset` 还会删除当前项目相关的持久化 session，因此 `resume` 不应恢复已经 reset 掉的运行时。
+- `/reset` 会尽量先通过正式 worktree / process 清理路径收尾，再删除状态目录。
+- reset 行为必须落在 runtime / project state 层，UI 只能触发它，不能自己维护一套平行 reset 状态。
+
+## 当前边界
+
+### 共享边界
+
+- `InteractiveSessionDriver`: 共享交互控制器
+- `InteractionShell`: 壳适配接口
+- `ShellInputPort`: 普通输入 / multiline 输入 / interrupt 订阅
+- `ShellOutputPort`: info / warn / plain / dim / interrupt 等展示输出
+- `InteractionTurnDisplay`: turn 期间的流式展示适配
+
+### 当前 CLI 接线
+
+- `src/ui/interactive.ts`: CLI 入口薄壳，只负责组装 shell、打印 intro、启动 driver
+- `src/shell/cli/readlineInput.ts`: CLI 输入适配
+- `src/shell/cli/output.ts`: `chalk` + stdio 输出适配
+- `src/shell/cli/turnDisplay.ts`: spinner + stream renderer 适配
+- `src/interaction/localCommands.ts`: 共享本地命令语义
+
+## 当前展示边界
+
+交互终端当前只负责把这些状态展示清楚：
+
+- task board
+- teammate 状态
+- background 状态
+- skill load 状态
+- runtime summary
+
+但它不负责发明这些状态。
+
+## 未来方向
+
+- 桌面壳应直接实现 `InteractionShell` 契约，而不是复用 CLI 的 `readline` / stdio 细节。
+- 桌面壳可以自己提供输入框、停止按钮、流式消息区和状态面板。
+- 只要继续复用 `InteractiveSessionDriver`，桌面壳与 CLI 壳就应共享同一套本地命令、turn 驱动和中断语义。

package/spec/modules/lightweight-context-runtime.md

@@ -0,0 +1,63 @@
+# lightweight context runtime
+
+## 目标
+
+这一层负责让 Athlete 在长任务里继续跑，但不要把 prompt 和 session 越跑越重。
+
+## 运行时约定
+
+1. system prompt 按两层正式组装：
+   - `Static operating layer`
+   - `Dynamic runtime layer`
+2. 静态层放稳定规则、模式规则、身份规则、项目说明。
+3. 动态层放 cwd / root / date / taskState / todo / verification / task board / team / worktree / protocol / background / skill runtime。
+4. 压缩后的会话总结不再直接拼回静态层，而是追加为 `Compressed conversation memory`。
+
+## 大 tool result 外置化
+
+1. 当 tool output 超过约 `12,000` chars 或 `16 KB` 时，进入外置化路径。
+2. 原始 output 落盘到项目 state root 下：
+   - `.athlete/tool-results/<sessionId>/<timestamp>-<tool>-<hash>.json|txt`
+3. session 里保留的 tool message 只存轻量引用：
+   - `externalized: true`
+   - `storagePath`
+   - `summary`
+   - `preview`
+   - `byteLength`
+   - `charLength`
+4. 小结果继续走原来的 inline message 路径，不做无差别外置化。
+5. 当 agent 读取 `.athlete/tool-results/...` 中的 artifact 文件时，`read_file` 默认返回紧凑摘要视图；只有显式 line range 读取才继续走原始逐行查看路径。
+
+## 闭环要求
+
+1. continuation 继续使用 session 中的轻量 tool message，而不是重新塞回原始大正文。
+2. contextBuilder 在压缩历史时继续保留 `storagePath` 和预览信息。
+3. recovery 的 context shrink 也要保住结构化引用，不能把它打回不可追踪的大字符串。
+4. session 保存和加载后，外置化引用仍然可以恢复到落盘文件。
+5. 已通过 streaming delta 发出的 assistant 文本不会在 finalize 阶段再次整段重放。
+
+## 验证方式
+
+1. fail-first 测试：
+   - `tests/runtime-lightweight-context.test.ts`
+2. 核心回归：
+   - `npm run test:build`
+   - `npm run test:core`
+3. 真实 API：
+   - `npm run verify:runtime-context-api`
+## Checkpoint Runtime Contract
+
+- `SessionRecord` now persists a structured `checkpoint` inside the existing session truth source.
+- `checkpoint` is a runtime summary, not a transcript dump. It carries:
+  - objective
+  - completedSteps
+  - currentStep
+  - nextStep
+  - recentToolBatch
+  - flow phase (`active / continuation / resume / recovery`)
+  - priorityArtifacts (externalized tool-result refs, previews, pending paths)
+- continuation, reload/resume, and dynamic prompt rendering must all consume the same checkpoint instead of inventing separate recovery hints.
+- objective changes reset checkpoint progress so old work does not pollute the new task.
+- externalized tool results remain the preferred recoverable context, and checkpoint keeps the references lightweight.
+- fail-first test for this layer: `tests/runtime-checkpoint-resume.test.ts`
+- real API verification entry for this layer: `npm run verify:runtime-checkpoint-api`

package/spec/modules/provider-adapter.md

@@ -0,0 +1,20 @@
+# provider adapter
+
+## 作用
+
+provider adapter 负责把 Athlete 的请求发送到具体模型服务。
+
+## 当前策略
+
+- 优先 OpenAI-compatible
+- 运行时对网络错误、超时、上下文过长有恢复策略
+
+## 规则
+
+1. provider 能换，主循环不跟着重写。
+2. provider 问题先在 adapter 层处理，不外溢到任务语义层。
+3. 模型 fallback 属于运行时策略，不属于业务模块。
+
+## 下一阶段要求
+
+总指挥层不依赖某一家 provider 特性。

package/spec/modules/runtime-metrics.md

@@ -0,0 +1,132 @@
+# runtime metrics
+
+## 作用
+
+这一层开始，Athlete 的 session 会持久化结构化 `runtimeStats`，
+作为正式运行态仪表盘的真相源。
+
+它回答的是：
+
+- 这次 session 一共发了多少次 provider request
+- 模型等待总耗时是多少
+- tool 一共调用了多少次、各自累计耗时多少
+- yield / continuation / recovery / compression 各发生了多少次
+- 有多少 tool result 被 externalize，以及累计字节数是多少
+- provider usage 是 available、partial 还是 unavailable
+
+## 真相源位置
+
+- `SessionRecord.runtimeStats`
+- 仍然持久化在既有 session JSON 文件里
+- 不新建平行 JSON 真相源
+
+## 当前结构
+
+`runtimeStats` 当前包含：
+
+- `version`
+- `model.requestCount`
+- `model.waitDurationMsTotal`
+- `model.usage.requestsWithUsage`
+- `model.usage.requestsWithoutUsage`
+- `model.usage.inputTokensTotal`
+- `model.usage.outputTokensTotal`
+- `model.usage.totalTokensTotal`
+- `model.usage.reasoningTokensTotal`
+- `tools.callCount`
+- `tools.durationMsTotal`
+- `tools.byName`
+- `events.continuationCount`
+- `events.yieldCount`
+- `events.recoveryCount`
+- `events.compressionCount`
+- `externalizedToolResults.count`
+- `externalizedToolResults.byteLengthTotal`
+- `updatedAt`
+
+## 来源
+
+### model request
+
+- 来源：`src/agent/api.ts`
+- 统计粒度：真实 provider request attempt
+- 包括 streaming、non-streaming fallback、retry、retry fallback
+
+### tool execution
+
+- 来源：`src/agent/runTurn.ts`
+- 统计粒度：真实 runtime tool execution
+- `tools.byName` 记录每个 tool 的调用次数、累计耗时、成功次数、失败次数
+
+### yield / continuation / recovery
+
+- 来源：`src/agent/turnPersistence.ts`
+- continuation 包括：
+  - managed continuation 的内部续跑输入
+  - 用户显式 `continue` / `resume` 这类恢复输入
+
+### compression
+
+- 来源：`src/agent/runTurn.ts`
+- 当 `buildRequestContext(...)` 返回 `compressed = true` 时记一次
+
+### externalized tool results
+
+- 来源：`src/agent/runTurn.ts` + `src/agent/toolResultStorage.ts`
+- 只在 tool result 实际被 externalize 时累计
+
+## 用户入口
+
+当前最小仪表盘入口：
+
+- `/runtime`
+- `/stats`
+- `/仪表盘`
+
+这些命令只读取并格式化当前 session summary，
+不发明新的运行态事实。
+
+## 当前 summary 最少包含
+
+- model request 次数
+- model wait 总耗时
+- tool call 次数
+- tool 总耗时
+- yields / continuations / recoveries / compressions
+- externalized result count / bytes
+- top tools
+- slowest step
+- usage availability
+- session health
+
+## usage 规则
+
+- 只有 provider 明确返回 usage 时才记录 usage
+- 如果 provider 没返回 usage，summary 必须显示 `unavailable` 或 `partial`
+- 不根据字符数、消息数、模型名去估算 token
+
+## 健康状态
+
+当前 summary 会给出：
+
+- `healthy`
+- `warning`
+- `recovering`
+
+它来自 checkpoint phase、verification state、recovery 事件等正式状态的推导视图，
+不是另一份单独持久化的状态。
+
+## 真实验证
+
+当前真实 API 验证入口：
+
+- `npm run verify:runtime-observability-api`
+
+它至少要确认：
+
+- `runtimeStats` 已写进 session
+- reload session 后 `runtimeStats` 仍然存在
+- 真实 model request 被统计
+- 真实 tool call 被统计
+- 用户可读的 runtime summary 路径可用
+- lightweight context 与 checkpoint runtime 没被打坏