@armadra/agent 0.8.0 → 0.9.0

package/docs/{acp.md → reference/acp.md}

@@ -1,13 +1,13 @@
 # ACP（Agent Client Protocol）
 
-[English](en/acp.md) · 简体中文
+[English](../en/reference/acp.md) · 简体中文
 
 ama 在 ACP 两侧都能用：
 
 - **服务端**：`ama --mode acp` 把 ama 暴露为 ACP Agent，供 Zed、JetBrains、Armadra 的 ACP 节点驱动；
-- **客户端**：ama 经 ACP 驱动外部 Agent（Gemini CLI、OpenCode、Kimi、Copilot 等原生 ACP，或装了适配器的 Claude Code / Codex），见 [agents.md](agents.md)。
+- **客户端**：ama 经 ACP 驱动外部 Agent（Gemini CLI、OpenCode、Kimi、Copilot 等原生 ACP，或装了适配器的 Claude Code / Codex），见 [agents.md](../guides/agents.md)。
 
-协议栈零依赖、手写，只维护一份：`@armadra/agent/acp` 导出类型、分帧、客户端与假 Agent，Armadra 直接复用。设计依据见 [wave5-plan.md](wave5-plan.md) §5（D14）。
+协议栈零依赖、手写，只维护一份：`@armadra/agent/acp` 导出类型、分帧、客户端与假 Agent，Armadra 直接复用。设计依据见 [wave5-plan.md](../history/wave5-plan.md) §5（D14）。
 
 ## 线路
 
@@ -79,7 +79,7 @@ diff 的改前 / 改后全文只随实时事件走，不写进会话文件：任
 
 ### 审批
 
-ama 需要询问的调用经 `session/request_permission` 交给客户端，三个选项：`allow_once`（允许）、`allow_always`（本会话允许）、`reject_once`（拒绝）。`toolCall.toolCallId` 关联到先前 `tool_call` 的 id——codemode 内层调用也是，指向那条内层 `tool_call`，不是外层 `codemode`。询问期间该调用的状态回到 `pending`，允许后再 `in_progress`（所以有审批的调用依次是 `pending → in_progress → pending → in_progress → completed`）；拒绝时直接 `failed`。客户端回 `cancelled`、连接断开或回合被中断时，按无人作答处理（拒绝）。ama 这边不再需要答复时（回合被 `session/cancel` / `$/cancel_request` 中断、审批 10 分钟超时），以 `$/cancel_request { requestId }` 撤回挂起的 `session/request_permission`，客户端可以关掉对话框。auto 模式下 ama 自己的分类器照常工作——这只影响 ama 自己的工具；ama 驱动的外部 Agent 发来的请求只交给人（见 [agents.md](agents.md)）。
+ama 需要询问的调用经 `session/request_permission` 交给客户端，三个选项：`allow_once`（允许）、`allow_always`（本会话允许）、`reject_once`（拒绝）。`toolCall.toolCallId` 关联到先前 `tool_call` 的 id——codemode 内层调用也是，指向那条内层 `tool_call`，不是外层 `codemode`。询问期间该调用的状态回到 `pending`，允许后再 `in_progress`（所以有审批的调用依次是 `pending → in_progress → pending → in_progress → completed`）；拒绝时直接 `failed`。客户端回 `cancelled`、连接断开或回合被中断时，按无人作答处理（拒绝）。ama 这边不再需要答复时（回合被 `session/cancel` / `$/cancel_request` 中断、审批 10 分钟超时），以 `$/cancel_request { requestId }` 撤回挂起的 `session/request_permission`，客户端可以关掉对话框。auto 模式下 ama 自己的分类器照常工作——这只影响 ama 自己的工具；ama 驱动的外部 Agent 发来的请求只交给人（见 [agents.md](../guides/agents.md)）。
 
 ### 无模型时
 
@@ -151,7 +151,7 @@ stdin 关闭后等已开始的运行结束再退出（0）；`ama` 进程的 std
 
 ## 作为客户端
 
-模型经 `task(agent="acp:<程序>")` 使用 ACP Agent（ama 自己是 `task(agent="acp:ama")`，见 [agents.md](agents.md)「在 task 里使用」）。
+模型经 `task(agent="acp:<程序>")` 使用 ACP Agent（ama 自己是 `task(agent="acp:ama")`，见 [agents.md](../guides/agents.md)「在 task 里使用」）。
 
 `AcpClient`（`@armadra/agent/acp`）：`initialize`、`newSession`、`resumeSession`（优先，不回放）、`loadSession`、`listSessions`、`closeSession`、`prompt`、`setMode`、`cancel`。
 

package/docs/{host-api.md → reference/host-api.md}

@@ -1,6 +1,6 @@
 # 宿主适配器 API（@armadra/agent/host）
 
-宿主适配器是一个本地 JS 模块，ama 启动时加载它并交给它一个 `HostApi`：它可以注册工具、追加系统提示、观察事件、回答审批、注入用户消息、在界面上显示通知与状态。Armadra 画布就是以宿主适配器的形式接入的（画布工具 `canvas_*` / `context_*` 都由适配器注册）。类型定义在 `src/host/types.ts`，从 `@armadra/agent/host` 导出，`HOST_API_VERSION = 1`。设计依据见 [design.md](design.md) §6.2、§6.3、§11.1 第 13 步。
+宿主适配器是一个本地 JS 模块，ama 启动时加载它并交给它一个 `HostApi`：它可以注册工具、追加系统提示、观察事件、回答审批、注入用户消息、在界面上显示通知与状态。Armadra 画布就是以宿主适配器的形式接入的（画布工具 `canvas_*` / `context_*` 都由适配器注册）。类型定义在 `src/host/types.ts`，从 `@armadra/agent/host` 导出，`HOST_API_VERSION = 1`。设计依据见 [design.md](../design/design.md) §6.2、§6.3、§11.1 第 13 步。
 
 ## 模块形状
 
@@ -132,7 +132,7 @@ interface ToolResult {
 - `request`：`requestId`、`toolName`、`input`、`reason: "mode" | "dangerous" | "hook"`、`hookReason?`、`preview?`（执行前预览，见 [rpc.md](rpc.md)「审批」）、`context?`（`depth > 0` 表示来自 `task` 子 Agent；codemode 内层调用带 `parentToolCallId`）。
 - 超时（缺省 10 分钟，`AMA_APPROVAL_TIMEOUT_MS`）或运行被中断时 `signal` abort，结论为 deny。审批串行，同一时刻只有一个请求在等。
 - 时机：broker 每次审批时现取，可以在 `create()` 里设，也可以之后任何时候设或替换；最后一次 `setBroker` 生效。
-- 宿主 broker 只决定「谁来回答 ask」，不能放宽 deny 规则、命令式 Hook 的 deny 与危险命令识别（[design.md](design.md) §6.3）。
+- 宿主 broker 只决定「谁来回答 ask」，不能放宽 deny 规则、命令式 Hook 的 deny 与危险命令识别（[design.md](../design/design.md) §6.3）。
 
 ## 缓存保温
 
@@ -150,7 +150,7 @@ interface WarmDecision {
 }
 ```
 
-返回 `"warm"` / `"stop"`（可以是 Promise）。返回 `"stop"` 即不发并停止本轮保温（内置决策本是 warm 时，停止原因记为 `declined`）；返回 `"warm"` 可以覆盖内置的 stop。处理器出错回落内置决策。注册多个时最后注册且未注销的那个生效；返回值是注销函数。保温机制本身见 [providers.md](providers.md)「缓存」。
+返回 `"warm"` / `"stop"`（可以是 Promise）。返回 `"stop"` 即不发并停止本轮保温（内置决策本是 warm 时，停止原因记为 `declined`）；返回 `"warm"` 可以覆盖内置的 stop。处理器出错回落内置决策。注册多个时最后注册且未注销的那个生效；返回值是注销函数。保温机制本身见 [providers.md](../guides/providers.md)「缓存」。
 
 ## 退出
 
@@ -163,4 +163,4 @@ Armadra 用 profile 启动 ama：`ama --profile <path>`，profile 的 `host` 指
 
 有 profile 时的界面缺省：`ui.quietStartup: "header"`、`ui.statusLine: "compact"`（最后一行是状态栏，宿主按 `·` 解析）。Agent 栏（`ui.agentBar`）不再缺省关闭，与独立终端一样是 `auto`；宿主自己展示子任务、不要栏时在 profile 的 `config` 指向的配置文件里写 `{ "ui": { "agentBar": "off" } }`。
 
-契约细节见 Armadra 仓库 [docs/design/coordinator-agent.md](https://github.com/yovinchen/Armadra/blob/main/docs/design/coordinator-agent.md)。
+契约细节见 Armadra 仓库 [docs/design/coordinator-agent.md](https://github.com/AMA-Link/Armadra/blob/main/docs/design/coordinator-agent.md)。

package/docs/{rpc.md → reference/rpc.md}

@@ -1,6 +1,6 @@
 # RPC 协议（stdio JSONL）
 
-`ama --mode rpc` 从 stdin 读命令、向 stdout 写响应与事件，每行一个 JSON。类型定义在 `@armadra/agent/rpc`（`src/rpc.ts`），实现在 `src/modes/rpc/`。`ama -p --output-format stream-json` 输出的事件与这里同形状。设计依据见 [design.md](design.md) §13.2。
+`ama --mode rpc` 从 stdin 读命令、向 stdout 写响应与事件，每行一个 JSON。类型定义在 `@armadra/agent/rpc`（`src/rpc.ts`），实现在 `src/modes/rpc/`。`ama -p --output-format stream-json` 输出的事件与这里同形状。设计依据见 [design.md](../design/design.md) §13.2。
 
 ## 线路
 
@@ -30,7 +30,7 @@
 
 - 响应带回请求的 `id`（字符串才带）。命令并发处理：`prompt` 不阻塞后续命令，所以响应顺序不一定与请求顺序相同，用 `id` 对应。
 - 失败时 `error` 是人读文本，`code` 是 `AmaError.code`（若有）。未知命令 → `code: "invalid_arguments"`。
-  **宿主按 `code` 判断，不得解析 `error` / `message`**：人读文本随界面语言（`AMA_LANG`、`--lang`、`ui.language`）变化（第六波起中英双语，见 [i18n.md](i18n.md)）；`notification` 事件的 `message` 同理。
+  **宿主按 `code` 判断，不得解析 `error` / `message`**：人读文本随界面语言（`AMA_LANG`、`--lang`、`ui.language`）变化（第六波起中英双语，见 [i18n.md](../guides/i18n.md)）；`notification` 事件的 `message` 同理。
 - 一行不是合法 JSON 或缺 `type` → `{ "type": "response", "command": "parse", "success": false, "error": … }`，没有 `id`。
 - 需要会话实现扩展方法的命令（下表标 †）在非 `AgentSessionImpl` 会话上返回 `code: "not_implemented"`；CLI 与 SDK 建出的会话都是 `AgentSessionImpl`。
 
@@ -95,7 +95,7 @@
 
 ### 回滚
 
-详见 [rewind-plan.md](rewind-plan.md) §3。回滚点是活动路径上开启新回合的用户消息（运行中插话、排队消息并入当前回合，不单列）。运行中调用回 `busy`。
+详见 [rewind-plan.md](../history/rewind-plan.md) §3。回滚点是活动路径上开启新回合的用户消息（运行中插话、排队消息并入当前回合，不单列）。运行中调用回 `busy`。
 
 | 命令                | 参数                                                                                                      | `data`                                                                                                                                                                          |
 | ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -115,7 +115,7 @@
 | `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks" \| "plans" \| "compact_events")[]` | `{ capabilities }`                                                             |
 | `permission_response`     | `requestId: string`、`decision: "allow" \| "deny" \| "allow_session"`                 | `{ accepted: boolean }`（false = 当前没在等这个 id，已暂存，稍后被问到时生效） |
 
-`compact_events`（docs/memory-plan.md D9）：声明后，`turn_end.toolResults`、`message_start` 与 `entry_appended` 不再重复携带工具结果与带图用户消息的正文（以 `contentOmitted: true` 标记），正文只在 `message_end` 与 `tool_execution_end` 里发；不声明时事件形状逐字节不变。形状见「[精简事件](#精简事件compact_events)」。`stream-json` 没有这个开关，输出始终是全量形状。
+`compact_events`（docs/history/memory-plan.md D9）：声明后，`turn_end.toolResults`、`message_start` 与 `entry_appended` 不再重复携带工具结果与带图用户消息的正文（以 `contentOmitted: true` 标记），正文只在 `message_end` 与 `tool_execution_end` 里发；不声明时事件形状逐字节不变。形状见「[精简事件](#精简事件compact_events)」。`stream-json` 没有这个开关，输出始终是全量形状。
 
 ### 工具、权限、发现
 
@@ -139,7 +139,7 @@
 
 ### 轨迹（第六波）
 
-`get_trace` 返回会话轨迹（与 TUI `/trace`、`ama sessions trace` 同一棵树，见 [tui.md](tui.md)「轨迹」）。不新增事件：客户端收到
+`get_trace` 返回会话轨迹（与 TUI `/trace`、`ama sessions trace` 同一棵树，见 [tui.md](../guides/tui.md)「轨迹」）。不新增事件：客户端收到
 `entry_appended` 后用上次的 `cursor.since` 再取一次即可增量刷新。
 
 | 参数         | 说明                                                                                                                       |
@@ -171,7 +171,7 @@
 
 被转的前台任务不中断，其 `task` 调用立即以 `tool_execution_end` 返回（结果文本以 `[task tN] Moved to the background` 开头，
 `details.status: "running"`），随后发 `subagent_background`；任务结束时照常 `subagent_end`，父会话空闲后收到 `origin: "task"`
-的通知消息。语义与交互界面的 `Ctrl+B` 相同，见 [agents.md](agents.md)「前台与后台」。
+的通知消息。语义与交互界面的 `Ctrl+B` 相同，见 [agents.md](../guides/agents.md)「前台与后台」。
 
 合计 44 条命令，名字即 `RpcCommandMap` 的键。
 
@@ -214,7 +214,7 @@
 
 `parentToolCallId` 只出现在 codemode 脚本里经 `tools.*` 发起的内层调用上，值是外层 `codemode` 调用的 id；客户端据此折叠显示。内层调用不进转录。
 
-`message_end`、`turn_end`、`done` / `error` 与回放（`get_messages`、`get_entries`）里的助手消息可能带两个可选字段（模型调用效率批次，docs/model-efficiency-plan.md §1.10）：失败消息的 `retryAfterMs`（`Retry-After`，毫秒），工具调用块的 `rawArguments`（模型输出的原始参数字符串）。`subagent_*` 事件不变；`get_tasks` 的 `TaskInfo` 可带 `context?: "fork" | "fresh"`（子会话的实际上下文模式）。都是新增的可选字段，`RPC_PROTOCOL_VERSION` 不变，客户端忽略不认识的字段即可。
+`message_end`、`turn_end`、`done` / `error` 与回放（`get_messages`、`get_entries`）里的助手消息可能带两个可选字段（模型调用效率批次，docs/history/model-efficiency-plan.md §1.10）：失败消息的 `retryAfterMs`（`Retry-After`，毫秒），工具调用块的 `rawArguments`（模型输出的原始参数字符串）。`subagent_*` 事件不变；`get_tasks` 的 `TaskInfo` 可带 `context?: "fork" | "fresh"`（子会话的实际上下文模式）。都是新增的可选字段，`RPC_PROTOCOL_VERSION` 不变，客户端忽略不认识的字段即可。
 
 ### 精简事件（`compact_events`）
 
@@ -230,7 +230,7 @@
 
 ### 子 Agent 事件（第五波）
 
-`task` / `task_ctl` 起的子 Agent（ama 子会话与外部 Agent 同一组事件，见 [agents.md](agents.md)「子 Agent」）：
+`task` / `task_ctl` 起的子 Agent（ama 子会话与外部 Agent 同一组事件，见 [agents.md](../guides/agents.md)「子 Agent」）：
 
 | 事件                  | 字段                                                                                                                                                                                     |
 | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -356,7 +356,7 @@
 {"type":"context_pressure","percent":71,"threshold":70,"remainingTokens":57990,"estimatedTurnsLeft":6}
 ```
 
-`cache_miss` 的 `detail` 只在 `prefix_changed` 时给出（`tools`、`system`，或带变化节名的 `system:<节名,…>`，如 `system:hooks,memory`）。`cache_warm{stopped}` 的 `reason` 取值与含义见 [tui.md](tui.md)「缓存与上下文」。`ama -p --output-format json` 的结果对象另有 `cache` 字段，形状同上。
+`cache_miss` 的 `detail` 只在 `prefix_changed` 时给出（`tools`、`system`，或带变化节名的 `system:<节名,…>`，如 `system:hooks,memory`）。`cache_warm{stopped}` 的 `reason` 取值与含义见 [tui.md](../guides/tui.md)「缓存与上下文」。`ama -p --output-format json` 的结果对象另有 `cache` 字段，形状同上。
 
 ## 审批
 
@@ -368,7 +368,7 @@
 
 ## 计划审批
 
-plan 模式与计划的格式见 [plan.md](plan.md)。
+plan 模式与计划的格式见 [plan.md](../guides/plan.md)。
 
 1. 回合在 plan 模式下以纯文本结束、回复里有 `<proposed_plan>` 块时，服务端落盘计划并发 `plan_proposed{ planId, version, markdown, steps, filePath? }`（`steps[]`：`{ id, text, dependsOn?, agent? }`），随后照常 `agent_settled`。
 2. 客户端声明过 `set_client_capabilities{capabilities:["plans"]}` 才由它回答；没声明时按配置 `plan.unattended`：缺省 `stop`（计划留在 proposed，不切模式、不执行，客户端之后仍可用 `plan_response` 作答），`approve` 时同一次运行里自动批准并执行。
@@ -386,7 +386,7 @@ plan 模式与计划的格式见 [plan.md](plan.md)。
 
 - stdin 关闭：不再接收命令，撤下审批（之后的 ask 按无人作答 deny），等在途命令与已开始的运行结束、响应写完，退出码 0。所以 `printf '{"type":"prompt","message":"hi"}\n' | ama --mode rpc` 能拿到完整回复；要提前停止，先发 `abort`。
 - SIGINT / SIGTERM：中断当前运行后有序退出，退出码 130 / 143。
-- 启动阶段的失败按 CLI 退出码（[design.md](design.md) §11.3）：配置错误 3、无模型或 key 4、会话错误 5、宿主 / Hook 启动失败 6、宿主 API 版本不匹配 78。
+- 启动阶段的失败按 CLI 退出码（[design.md](../design/design.md) §11.3）：配置错误 3、无模型或 key 4、会话错误 5、宿主 / Hook 启动失败 6、宿主 API 版本不匹配 78。
 
 ## 示例
 

package/docs/{session-format.md → reference/session-format.md}

@@ -1,6 +1,6 @@
 # 会话文件格式（JSONL 条目树）
 
-会话是一个只追加的 JSONL 文件：首行是头，其后每行一个条目（以及可选的 `leaf` 行）。条目经 `parentId` 连成树，「当前分支」是从根到叶子的一条路径；发给模型的上下文由当前分支**投影**得到。类型定义在 `src/session/types.ts`（经 `@armadra/agent` 导出），格式版本 `SESSION_FORMAT_VERSION = 1`。设计依据见 [design.md](design.md) §8、§9。
+会话是一个只追加的 JSONL 文件：首行是头，其后每行一个条目（以及可选的 `leaf` 行）。条目经 `parentId` 连成树，「当前分支」是从根到叶子的一条路径；发给模型的上下文由当前分支**投影**得到。类型定义在 `src/session/types.ts`（经 `@armadra/agent` 导出），格式版本 `SESSION_FORMAT_VERSION = 1`。设计依据见 [design.md](../design/design.md) §8、§9。
 
 ## 位置与文件
 
@@ -47,14 +47,14 @@
 
 ### 消息
 
-- `system`：`{ role: "system", sections, toolsAdded?, toolsRemoved?, timestamp }`。首条是全量：系统提示的命名节（固定顺序 `preamble → tools → rules → project_context → skills → memory → hooks → cwd → host → role`；`memory` 是第六波的记忆索引节，未开启记忆时不出现）与工具声明表；之后只落**补丁**——节名级替换、值为 `null` 表示删除该节，`toolsAdded` / `toolsRemoved` 增删工具。依次重放得到当前系统提示；请求时由协议层重装：首条非 system 消息之前的部分折进开头，之后的节补丁作为尾部上下文送达、不改写开头（移除工具的补丁除外，见 [providers.md](providers.md)「缓存」）。首条 system 消息在首次请求前落盘，也就是建文件的时刻。
+- `system`：`{ role: "system", sections, toolsAdded?, toolsRemoved?, timestamp }`。首条是全量：系统提示的命名节（固定顺序 `preamble → tools → rules → project_context → skills → memory → hooks → cwd → host → role`；`memory` 是第六波的记忆索引节，未开启记忆时不出现）与工具声明表；之后只落**补丁**——节名级替换、值为 `null` 表示删除该节，`toolsAdded` / `toolsRemoved` 增删工具。依次重放得到当前系统提示；请求时由协议层重装：首条非 system 消息之前的部分折进开头，之后的节补丁作为尾部上下文送达、不改写开头（移除工具的补丁除外，见 [providers.md](../guides/providers.md)「缓存」）。首条 system 消息在首次请求前落盘，也就是建文件的时刻。
 - `user`：`content`、`origin?`（缺省 = 普通用户输入；`steer` / `followUp` 是运行中插话与排队，`host` 是宿主 `sendUser` 注入，`interrupt` 是打断并立即发送开的新回合（TUI `Ctrl+X`、line 模式 `/interrupt`、RPC / SDK 的 `interrupt: true`；投影与普通 user 消息相同），`direct` 是用户在子 Agent 视图里直接发给该子 Agent 的消息（第六波 W6-A，写在子会话里；投影与普通 user 消息相同），其它字符串原样记录）。
 - `assistant`：`content`（文本 / 思考 / 工具调用块）、`api`、`provider`、`model`、`usage`、`stopReason`，以及可选的 `responseId`、`thinkingLevel`、`providerThinkingLevel`、`rawStopReason`、`errorMessage`、`retryAfterMs`（失败响应的 `Retry-After`，毫秒；会话层退避取它与指数退避中的较大值）。工具调用块是 `{ type: "toolCall", id, name, arguments, thoughtSignature?, rawArguments? }`：`rawArguments` 是模型输出的原始参数字符串（能严格解析为 JSON 时才记），同协议回放时原样发回，没有时回落 `JSON.stringify(arguments)`。两者都是可选字段，格式版本不变，旧文件照常读取。`usage` 是 `{ input, output, cacheRead, cacheWrite, cacheWrite1h?, reasoning?, totalTokens, cost?, cacheReported? }`：`input` 不含缓存部分，`cost` 是 `{ input, output, cacheRead, cacheWrite, total }`（美元，模型无价格时缺省），`cacheReported` 表示原始响应里出现过缓存字段。
 - `toolResult`：对应工具调用的结果（`toolCallId`、`toolName`、`content`、`isError`、`details?`）。
 
 ### `usage` 条目
 
-不进上下文的请求用量，计入 `/session` 费用与 RPC 统计，投影时跳过。`kind` 目前有 `"cache_warm"`（缓存保温请求，见 [providers.md](providers.md)「缓存」）与 `"permission_classify"`（auto 权限模式的分类请求，见 [permissions.md](permissions.md)）：
+不进上下文的请求用量，计入 `/session` 费用与 RPC 统计，投影时跳过。`kind` 目前有 `"cache_warm"`（缓存保温请求，见 [providers.md](../guides/providers.md)「缓存」）与 `"permission_classify"`（auto 权限模式的分类请求，见 [permissions.md](../guides/permissions.md)）：
 
 ```json
 {
@@ -127,9 +127,9 @@
 `data` = `TaskInfo`（`taskId, agent, runner, description, background, status, startedAt, endedAt?, turns?, usage?, costUsd?,
 contextTokens?, contextWindow?, outputFile?, sessionRef?`；`contextTokens / contextWindow` 只有外部 Agent 报告时才有）+ `parentToolCallId`、`cwd`。同一 `taskId` 取分支上最后一条；resume 时据此重建任务注册表，
 `status: "running"` 视为 `interrupted`（`taskId` 续聊重开 `sessionRef.sessionFile`）。没有 `status` 的是子会话自己的首条。
-模型调用效率批次（docs/model-efficiency-plan.md）起，两处的 `data` 可带 `context?: "fork" | "fresh"`（子会话的实际上下文模式，fork 回落为 fresh 时记 `fresh`；缺省即 `fresh`），子会话首条另可带 `forkedFrom?`（fork 点的父条目 id）。都是可选字段，格式版本不变。
+模型调用效率批次（docs/history/model-efficiency-plan.md）起，两处的 `data` 可带 `context?: "fork" | "fresh"`（子会话的实际上下文模式，fork 回落为 fresh 时记 `fresh`；缺省即 `fresh`），子会话首条另可带 `forkedFrom?`（fork 点的父条目 id）。都是可选字段，格式版本不变。
 
-第五波登记的类型（docs/wave5-plan.md；括号里是开始写入的批次，之前的版本不会产生，读到未知 `customType` 一律忽略）。`custom_message` 类都是 `display: false`，经扩展点 `beforePrompts` 追加在末尾，不改缓存前缀：
+第五波登记的类型（docs/history/wave5-plan.md；括号里是开始写入的批次，之前的版本不会产生，读到未知 `customType` 一律忽略）。`custom_message` 类都是 `display: false`，经扩展点 `beforePrompts` 追加在末尾，不改缓存前缀：
 
 | `customType`         | 条目类型         | 内容                                                                                                                                     | 写入时机                                                                                                                        |
 | -------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
@@ -143,7 +143,7 @@ contextTokens?, contextWindow?, outputFile?, sessionRef?`；`contextTokens / con
 | `ama.agent-session`  | `custom`         | `data: { agent, runner, sessionId, cwd?, taskId? }`：外部 Agent 自己的会话引用（不含原始事件与转录）                                     | 外部 Agent 会话建立 / 续聊时（W5-E）                                                                                            |
 | `ama.agent-usage`    | `custom`         | `data: { agent, sessionId, unit: usd \| tokens \| requests, amount, tokens?, contextTokens?, contextWindow? }`（上下文只记数字）         | 外部 Agent 每个回合结束（W5-E）；`SessionStats.external` 据此汇总                                                               |
 
-第六波登记的类型（docs/wave6-plan.md §2.2；之前的版本不会产生）：
+第六波登记的类型（docs/history/wave6-plan.md §2.2；之前的版本不会产生）：
 
 | `customType` | 条目类型 | 内容                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | 写入时机                                                                                                                                                                                                                                              |
 | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -154,5 +154,5 @@ contextTokens?, contextWindow?, outputFile?, sessionRef?`；`contextTokens / con
 ## 读取方
 
 - `ama sessions list|show`、交互模式 `/resume`、RPC `get_entries{since}`（以 entry id 为游标返回 `{ entries, leafId }`）、`get_tree`。
-- 只读扫描（不加锁、不修复）：`ama stats`、`ama sessions search|export`、`--from`，见 [sessions.md](sessions.md)。
+- 只读扫描（不加锁、不修复）：`ama stats`、`ama sessions search|export`、`--from`，见 [sessions.md](../guides/sessions.md)。
 - 嵌入方可以直接读文件：按行解析，首行为头，跳过 `type: "leaf"` 的行后按 `parentId` 建树；遇到不认识的条目类型保留但不进上下文。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armadra/agent",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "A coding and coordination agent that runs standalone or embedded in Armadra",
   "type": "module",
   "keywords": [
@@ -19,15 +19,15 @@
     "sdk",
     "armadra"
   ],
-  "homepage": "https://github.com/Owlbay/armadra-agent#readme",
+  "homepage": "https://github.com/AMA-Link/armadra-agent#readme",
   "bugs": {
-    "url": "https://github.com/Owlbay/armadra-agent/issues"
+    "url": "https://github.com/AMA-Link/armadra-agent/issues"
   },
   "author": "YoVinchen",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Owlbay/armadra-agent.git"
+    "url": "git+https://github.com/AMA-Link/armadra-agent.git"
   },
   "bin": {
     "ama": "dist/bundle/ama.cjs"
@@ -58,23 +58,11 @@
   },
   "files": [
     "dist",
-    "docs/rpc.md",
-    "docs/host-api.md",
-    "docs/hooks.md",
-    "docs/permissions.md",
-    "docs/providers.md",
-    "docs/codemode.md",
-    "docs/sandbox.md",
-    "docs/plan.md",
-    "docs/agents.md",
-    "docs/acp.md",
-    "docs/rewind-plan.md",
-    "docs/tui.md",
-    "docs/tui-design.md",
-    "docs/session-format.md",
-    "docs/sessions.md",
-    "docs/memory.md",
-    "docs/en/*.md",
+    "docs/README.md",
+    "docs/guides/*.md",
+    "docs/reference/*.md",
+    "docs/en/**/*.md",
+    "docs/assets/*.svg",
     "README.zh-CN.md",
     "CHANGELOG.md",
     "CHANGELOG.zh-CN.md",
@@ -104,10 +92,11 @@
     "fmt:check": "prettier --check .",
     "check:deps": "node scripts/check-no-deps.mjs",
     "check:i18n": "node scripts/check-i18n.mjs",
+    "check:docs": "node scripts/check-doc-links.mjs",
     "release:check": "node scripts/release-check.mjs",
     "bench:presets": "node scripts/bench-presets.mjs",
     "bench:cache": "node scripts/cache-experiment.mjs",
-    "ci": "pnpm typecheck && pnpm fmt:check && pnpm check:deps && pnpm check:i18n && pnpm release:check && pnpm test && pnpm build && node dist/bundle/ama.cjs --version"
+    "ci": "pnpm typecheck && pnpm fmt:check && pnpm check:deps && pnpm check:i18n && pnpm check:docs && pnpm release:check && pnpm test && pnpm build && node dist/bundle/ama.cjs --version"
   },
   "dependencies": {},
   "devDependencies": {
@@ -117,5 +106,5 @@
     "typescript": "~5.9.3",
     "vitest": "^4.1.11"
   },
-  "packageManager": "pnpm@11.18.0"
+  "packageManager": "pnpm@12.8.1"
 }

package/docs/rewind-plan.md

@@ -1,181 +0,0 @@
-# 检查点与回滚：设计与实施计划
-
-> 状态：实施设计（2026-10-02）。基线：`main` = `95c0435`（0.4.0）。
-> 设计依据：`docs/design.md` §8 会话树、§9 压缩、§9.1 缓存保证、§13 SDK / RPC；对照同类终端 Agent 的检查点实现（只借鉴行为与边界，不复制代码）。
-> 路径相对仓库根；`[RW-x]` 为本计划的批次编号（§6）。
-
-## §0 结论
-
-| #   | 决定                                                                                                                                                                         | 理由                                                             |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
-| D1  | 回滚 = 「对话」与「代码」两件事，入口 `/rewind` 与空闲时双击 Esc；选项：对话 + 代码 / 仅对话 / 仅代码 / 从这里摘要 / 摘要到这里 / 取消                                       | 两者独立才能覆盖「代码写坏了但对话想留」「对话跑偏了但代码要留」 |
-| D2  | 检查点粒度 = 开启新回合的用户消息；运行中插话（steer）与排队消息并入当前回合，不单独建                                                                                       | 回合是用户能理解的最小单位                                       |
-| D3  | 代码跟踪 edit / write（含 codemode 内层调用、task 子会话）改过的文件；每次发新回合按**当前磁盘状态**重拍已跟踪文件，所以 bash 或手动对已跟踪文件的改动也会被收进下一个检查点 | bash 任意改动不可完整追踪；已跟踪文件这样处理就不会漏            |
-| D4  | 备份按内容 sha256 存全局目录，多会话、多检查点共用；会话文件只记哈希                                                                                                         | 同内容只存一份；fork 不用迁移备份                                |
-| D5  | 恢复前做冲突检测：磁盘内容既不等于 ama 最后写入的、也不等于最近检查点的 → 冲突，缺省跳过并列出，`onConflict: "overwrite"` 才覆盖                                             | 不冲掉用户在回合外的手动修改                                     |
-| D6  | git 状态不动；检查点记 HEAD，回滚时 HEAD 变了只提示并给命令                                                                                                                  | `reset` 类操作风险高，交给用户                                   |
-| D7  | 对话回滚复用会话树（`navigate` 换叶子），被离开的分支留在文件里                                                                                                              | 现有能力，零迁移                                                 |
-| D8  | 回滚后上下文只发新路径，前缀逐字节不变，缓存照常命中；需要告诉模型的事（文件与对话不一致）以 `custom_message` 追加在末尾                                                     | §9.1 前缀稳定                                                    |
-| D9  | `影子 git` 模式（能覆盖 bash 改动）作为可选 `checkpoints.mode: "shadow-git"`，缺省关，最后一批做                                                                             | 大仓库慢、依赖 git，不适合作缺省                                 |
-
-## §1 数据模型
-
-### §1.1 备份存储
-
-- 目录：`<dataDir>/file-history/blobs/<sha256 前 2 位>/<sha256 全长>`，内容为文件原字节（不压缩、不改换行与 BOM）；先写 `<name>.tmp-<pid>` 再 rename，已存在即跳过。
-- 不备份：超过 `checkpoints.maxFileBytes`（缺省 5 MiB）的文件、非普通文件。记录里标 `skipped: "too_large" | "not_regular"`，回滚时报告「无法恢复」。
-- 内存会话（无会话文件）不建检查点，`/rewind` 只提供「仅对话」。
-
-### §1.2 会话条目（均为 `custom`，不进上下文，不影响前缀）
-
-```ts
-// customType "ama.checkpoint"：新回合的用户消息条目追加之后立即追加
-interface CheckpointData {
-  v: 1;
-  userEntryId: string; // 这个检查点属于哪条用户消息（「这条消息发出前」的状态）
-  files: Record<string, FileRecord>; // 全部已跟踪文件；键 = cwd 内相对路径（/ 分隔），cwd 外为绝对路径
-  git?: { head: string; branch?: string }; // 直接读 .git/HEAD（含 worktree 的 gitdir 文件），不起 git 进程
-}
-
-// customType "ama.checkpoint-track"：回合中途第一次碰某文件时追加，补进本回合的检查点
-interface CheckpointTrackData {
-  v: 1;
-  userEntryId: string;
-  path: string;
-  record: FileRecord;
-}
-
-interface FileRecord {
-  blob: string | null; // sha256；null = 当时文件不存在（回滚时删除）
-  mode?: number; // 普通文件的权限位
-  size?: number;
-  realParentDir?: string; // 记录时父目录的 realpath（恢复时校验没被移动）
-  skipped?: "too_large" | "not_regular";
-}
-```
-
-- 读取：按文件顺序重放全会话（不限活动分支）的两类条目，得到 `Map<userEntryId, CheckpointData>`；`checkpoint-track` 并入对应检查点。
-- 每个文件的第一条记录（最早的 `blob`）永久保留，作为「找不到更近记录时」的回退。
-
-### §1.3 运行时状态（`src/checkpoints/tracker.ts`）
-
-- `trackedFiles: Set<string>`、最近检查点、`lastWritten: Map<路径, sha256>`（ama 最后一次写入后的内容哈希，用于冲突检测；只在内存，恢复会话后以最近检查点为准）。
-- 检查点上限 `checkpoints.keep`（缺省 100）：超出时较早检查点不再列为回滚点；备份由 GC 清理（§1.4）。
-
-### §1.4 清理
-
-- `ama sessions prune` 与删除会话时：标记 —— 扫描所有会话文件里的 `ama.checkpoint*` 引用；清除 —— 删除未被引用且 mtime 超过 1 天的 blob。
-- `ama doctor` 显示 file-history 占用。
-
-## §2 时机
-
-| 时机                                                                    | 动作                                                                                                                                                                               |
-| ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 新回合用户消息落盘后（`runPrompt`，steer / 排队并入的不算）             | 对每个已跟踪文件：lstat → 不存在记 `null`；size / mode 与上一条记录一致且 mtime 不晚于记录时间 → 沿用；否则读内容算 sha256，等于上一条则沿用，不等则写 blob。追加 `ama.checkpoint` |
-| edit / write 写文件**之前**（`ctx.checkpoint?.beforeWrite(abs)`）       | 文件在任何检查点里都没出现过 → 备份当前内容（不存在记 `null`），追加 `ama.checkpoint-track`，加入 `trackedFiles`；出现过则什么都不做                                               |
-| edit / write 写文件**之后**（`ctx.checkpoint?.afterWrite(abs, bytes)`） | 记 `lastWritten`                                                                                                                                                                   |
-| task 子会话                                                             | 子会话的 `ctx.checkpoint` 指向父会话的 tracker，记到父会话当前回合                                                                                                                 |
-| codemode 内层调用                                                       | 走同一工具上下文，天然覆盖                                                                                                                                                         |
-
-`beforeWrite` 失败（磁盘满、权限）只记 warn，不阻止写入（与对照实现一致：检查点是辅助，不能让编辑失败）。
-
-## §3 回滚
-
-### §3.1 API（`AgentSession`，SDK 同名，RPC 见 §5）
-
-类型见 `src/checkpoints/types.ts`（`RewindPoint`、`RewindRequest`、`RewindResult`、`CodeRestoreResult`）：
-
-```ts
-rewindPoints(): RewindPoint[];               // 活动路径上的新回合用户消息，从旧到新
-rewind(request: RewindRequest): Promise<RewindResult>;
-```
-
-`dryRun` 的 `code` 字段给出将恢复的文件与 `insertions / deletions`，界面的每行统计与确认预览都用它（懒计算，只对选中项）。
-
-- 运行中调用抛 `AmaError("busy")`。全部失败且无一恢复 → `AmaError("rewind_failed", "没有文件被恢复…")`。
-
-### §3.2 恢复代码（`src/checkpoints/restore.ts`）
-
-对每个已跟踪文件，取目标检查点里的记录，没有则取该文件最早的记录：
-
-1. 记录 `skipped` → 报告 `too_large` / `not_regular`。
-2. 当前内容与记录相同 → 跳过（不计入）。
-3. 冲突检测：当前 sha256 ∉ {`lastWritten`，最近检查点的记录} → 冲突；`skip` 时列入 `conflicts` 不动。
-4. 安全检查（不通过 → `skipped`）：目标是符号链接 / 非普通文件 / `nlink > 1`；父目录 realpath ≠ `realParentDir`。
-5. `blob: null` → 删除文件（只删普通文件）。
-6. 否则写回：Windows 以外用 `O_NOFOLLOW` 打开目标，`fstat` 与路径 `lstat` 的 dev / ino 一致才写；清空后写入 blob 内容，恢复 `mode`；目标不存在时按需创建父目录（再次校验父目录）。
-7. 被恢复 / 删除的文件从 `readFiles` 移除（模型再改前必须重新 read）。
-
-`dryRun` 只做 1–4 并用行级 diff 计 `insertions / deletions`（复用 `tools/edit` 的 diff 实现）。
-
-### §3.3 回滚对话（`src/agent/session-rewind.ts`）
-
-1. `navigate(userEntry.parentId)`（已有：换叶子、重载消息、`cache.onContextChanged()`）。
-2. `readFiles` 按新路径重算：路径上成功的 read 工具调用的绝对路径（不跨分支保留）。
-3. 返回 `draft`：原消息文本与图片，交互界面回填输入框。
-4. 模型、思考级别、权限模式保持当前（文档写明）。
-
-### §3.4 文件与对话不一致时告诉模型
-
-- 仅对话：若有已跟踪文件当前内容 ≠ 目标检查点 → 下一次提示前追加 `custom_message{customType:"ama.rewind-note"}`：「回滚到较早的对话，但以下文件保留了之后的修改：…（最多 20 个，其余计数）」。
-- 仅代码：追加「以下文件已恢复到第 N 条消息之前的状态：…」。
-- 对话 + 代码：两边一致，不追加。
-- 该条目在回滚落点之后、下一条用户消息之前，只追加在末尾，不改前缀。
-
-### §3.5 摘要两项
-
-- 「从这里摘要」= `navigate(parentId, { summarize: true })`（已有 `branch_summary`，走会话前缀续写），并回填原消息。
-- 「摘要到这里」= 以所选用户消息为切点做一次档二压缩（`compaction` 条目的 `firstKeptEntryId` = 该消息），之后的消息原样保留，停在末尾。可附说明（`instructions`）。
-
-### §3.6 中断即撤回
-
-运行中 Esc 中断，且本回合还没有任何 assistant 文本 / 工具调用、输入框为空 → 自动 `rewind(当前回合, "conversation")` 并回填原消息（配置 `ui.restoreOnCancel`，缺省 true）。
-
-## §4 交互
-
-- 空闲且输入框为空：双击 Esc（间隔 ≤ 800 ms，第一次提示「再按 Esc 回滚」）打开回滚列表；输入框有字：双击 Esc 清空输入并存进输入历史（↑ 可取回），第一次提示「再按 Esc 清空」。运行中 Esc 仍为中断。
-- 列表：活动路径上的用户消息，最近在下、缺省选中最后一条；高亮行右侧显示 `N 文件 +x −y` / `无代码改动`（对高亮项做 dryRun，结果缓存）。
-- 选中后：确认面板（左竖条样式，复用 `/session` 面板），显示消息原文与时间、选项（有代码改动才出现两个「恢复代码」项；两个摘要项可在行内输入说明）、预览（「将恢复 N 个文件 +x −y」/「代码不变」/ 冲突与跳过清单）、git HEAD 变化提示（附 `git log --oneline <记录>..HEAD` 与 `git reset --soft <记录>` 两条命令，不执行）。
-- 结果通知：`已恢复 N 个文件，跳过 M 个（原因…）`。
-- line 模式：`/rewind` 列编号；`/rewind <n> [both|conversation|code]`。
-- 文案进 i18n 风格的现有中文常量；字形走主题 glyphs（ASCII 可用）。
-
-## §5 RPC / SDK / Hook / 配置
-
-- RPC：`get_rewind_points` → `{ points }`；`rewind { entryId, mode, dryRun?, onConflict? }` → `RewindResult`；事件 `session_rewound { entryId, mode, restored, deleted, conflicts, skipped }`。写进 `docs/rpc.md`。
-- SDK：`session.rewindPoints()`、`session.rewind()`。
-- Hook：新增命令式事件 `PostRewind`（payload `{ entryId, mode, files }`，不可阻止）；`docs/hooks.md` 同步。
-- 配置（`key-docs.ts` 每项要说明与缺省值）：
-  - `checkpoints.mode`: `"tools"`（缺省）/ `"shadow-git"` / `"off"`；`AMA_CHECKPOINTS=off` 覆盖。
-  - `checkpoints.maxFileBytes`: 5 242 880。
-  - `checkpoints.keep`: 100。
-  - `ui.restoreOnCancel`: true。
-
-## §6 影子 git（`checkpoints.mode: "shadow-git"`）[RW-D]
-
-- 仓库：`<dataDir>/file-history/shadow/<sha256(cwd) 前 16>/`（`--git-dir`），`--work-tree=cwd`；尊重 cwd 的 `.gitignore` 与 `info/exclude`，额外排除 `.git`。
-- 每个新回合：`git add -A` + `write-tree` + `commit-tree`，提交 id 记进 `CheckpointData.shadowCommit`（契约里预留可选字段）。
-- 护栏：cwd 下文件数 > 20 000 或单次快照 > 3 s → 本会话降级为 `tools` 并提示；需要 `git` 在 PATH。
-- 恢复：只处理目标提交与「当前工作区快照」之间的差异文件，逐个按 §3.2 的冲突与安全检查写回或删除；不碰 `.gitignore` 掉的文件。
-- 与 `tools` 模式并存：edit / write 的跟踪照常（冲突检测仍以它为准）。
-
-## §7 缓存与上下文
-
-- 回滚后第一次请求：system + tools + 落点之前的消息与回滚前发过的请求逐字节相同 → 有效期内命中；`onContextChanged()` 使这次请求成为重置点（不做未命中归因、保温作废），与现状一致。
-- `ama.checkpoint*` 是 `custom`，不进上下文；`ama.rewind-note` 是 `custom_message`，只出现在新落点之后。
-- 测试：回滚前后请求体前缀逐字节比较（`src/agent/session-rewind.test.ts`）。
-
-## §8 批次与文件所有权
-
-契约 PR（本计划所在 PR）先合入：`src/checkpoints/types.ts`、`ToolContext.checkpoint?`。配置 `checkpoints.*` 归 RW-A，`ui.restoreOnCancel` 与 `PostRewind` 归 RW-B（各自同步 `config/{types,schema,json-schema,key-docs}.ts` 与 `hooks/types.ts`）。之后：
-
-| 批次            | 内容                                                                                                                                                                      | 文件所有权                                                                                                                                                                                               | 依赖                                          | 验收                                                                                                                                                                              |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| RW-A 检查点核心 | blob 存储、tracker、条目重放、恢复与安全检查、冲突检测、dry-run diff、GC、doctor 占用；edit / write 调 `ctx.checkpoint`                                                   | `src/checkpoints/**`（除 types.ts）、`src/tools/{edit,write}.ts` 的两处调用、`src/cli/subcommands/{sessions,doctor}.ts` 的 GC / 占用                                                                     | 契约                                          | 单测覆盖 §3.2 每条分支（符号链接、硬链接、父目录移动、删除、新建、冲突 skip / overwrite、too_large）；三平台 CI 绿（Windows 无 O_NOFOLLOW 分支）                                  |
-| RW-B 会话与接口 | `session-rewind.ts`（编排、readFiles 重算、rewind-note、摘要两项、中断即撤回）、检查点接线（runPrompt 后建检查点、子会话指向父 tracker）、RPC / SDK / `PostRewind` / 文档 | `src/agent/session-rewind.ts`（新）、`src/agent/{session,session-run,session-tools,session-subagent}.ts` 的接线、`src/modes/rpc/**`、`src/sdk.ts`、`src/hooks/**` 的事件、`docs/{rpc,hooks,sessions}.md` | 契约；RW-A 的实现可先用内存桩，合入顺序 A → B | fake 供应商端到端：edit 两个文件 → rewind both → 文件与对话都回到之前、readFiles 不含被恢复文件、下一请求前缀逐字节不变；仅对话 / 仅代码各自的 note；子会话编辑可回滚；中断即撤回 |
-| RW-C 交互界面   | 双击 Esc、回滚列表、确认面板、预览、git 提示、结果通知、line 模式 `/rewind`                                                                                               | `src/modes/interactive/**`、`src/modes/commands-core.ts`、`docs/tui.md`                                                                                                                                  | RW-B                                          | 帧黄金：列表、面板（有 / 无代码改动、冲突、git 提示）、ASCII；tmux 手测双击 Esc 两种行为                                                                                          |
-| RW-D 影子 git   | §6                                                                                                                                                                        | `src/checkpoints/shadow-git.ts`（新）及其测试                                                                                                                                                            | RW-A                                          | 临时 git 仓库里 bash 改动可回滚；护栏降级；无 git 时提示                                                                                                                          |
-
-- A 与 B 并行开发（B 用桩），A 先合；C 与 D 在 B / A 合入后并行。
-- 每个文件 ≤ 600 行（`src/agent/session.ts` 已 600 行，新逻辑放 `session-rewind.ts`）。
-- 每批次细粒度提交、一个 PR、CI 绿后由主会话合并（merge commit）；不发版。