@armadra/agent 0.8.0 → 0.9.0

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

@@ -1,11 +1,11 @@
 # RPC protocol (stdio JSONL)
 
-English · [简体中文](../rpc.md)
+English · [简体中文](../../reference/rpc.md)
 
-> Translated from the Chinese [docs/rpc.md](../rpc.md) as of commit `a567833`. When the two differ, the Chinese version is
+> Translated from the Chinese [docs/reference/rpc.md](../../reference/rpc.md) as of commit `a567833`. When the two differ, the Chinese version is
 > authoritative.
 
-`ama --mode rpc` reads commands from stdin and writes responses and events to stdout, one JSON value per line. The types are defined in `@armadra/agent/rpc` (`src/rpc.ts`) and implemented in `src/modes/rpc/`. The events printed by `ama -p --output-format stream-json` have the same shapes. The design rationale is in [design.md](../design.md) §13.2 (Chinese).
+`ama --mode rpc` reads commands from stdin and writes responses and events to stdout, one JSON value per line. The types are defined in `@armadra/agent/rpc` (`src/rpc.ts`) and implemented in `src/modes/rpc/`. The events printed by `ama -p --output-format stream-json` have the same shapes. The design rationale is in [design.md](../../design/design.md) §13.2 (Chinese).
 
 ## Wire
 
@@ -35,7 +35,7 @@ A command has the shape `{ "id"?: string, "type": <command name>, ...parameters
 
 - A response carries the request's `id` back (only string ids). Commands are processed concurrently: `prompt` does not block later commands, so responses may arrive in a different order than requests; match them by `id`.
 - On failure `error` is human-readable text and `code` is the `AmaError.code` (when there is one). Unknown commands → `code: "invalid_arguments"`.
-  **Hosts must decide by `code` and never parse `error` / `message`**: human-readable text follows the interface language (`AMA_LANG`, `--lang`, `ui.language`; bilingual since wave 6, see [i18n.md](../i18n.md), Chinese). The same holds for the `message` of `notification` events.
+  **Hosts must decide by `code` and never parse `error` / `message`**: human-readable text follows the interface language (`AMA_LANG`, `--lang`, `ui.language`; bilingual since wave 6, see [i18n.md](../../guides/i18n.md), Chinese). The same holds for the `message` of `notification` events.
 - A line that is not valid JSON or lacks `type` → `{ "type": "response", "command": "parse", "success": false, "error": … }`, without `id`.
 - Commands that need extension methods of the session implementation (marked † below) return `code: "not_implemented"` on sessions that are not `AgentSessionImpl`; sessions created by the CLI and the SDK are all `AgentSessionImpl`.
 
@@ -100,7 +100,7 @@ Prompt commands **do not wait for the run to finish**: they are answered as soon
 
 ### Rewind
 
-Details in [rewind-plan.md](../rewind-plan.md) §3 (Chinese). Rewind points are the user messages on the active path that start new turns (steers and queued messages belong to the current turn and are not listed). Calling while running returns `busy`.
+Details in [rewind-plan.md](../../history/rewind-plan.md) §3 (Chinese). Rewind points are the user messages on the active path that start new turns (steers and queued messages belong to the current turn and are not listed). Calling while running returns `busy`.
 
 | Command             | Parameters                                                                                                | `data`                                                                                                                                                                                            |
 | ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -111,7 +111,7 @@ Details in [rewind-plan.md](../rewind-plan.md) §3 (Chinese). Rewind points are
 
 `CodeRestoreResult`: `restored` / `deleted` / `conflicts` (left untouched with `skip`, overwritten with `overwrite`) / `skipped: { path, reason }[]` (`symlink` / `hardlink` / `not_regular` / `parent_moved` / `too_large` / `backup_missing`) / `failed: { path, message }[]` / `insertions` / `deletions`; paths inside cwd are relative (`/`-separated). Error codes: restoring code without a checkpoint → `no_checkpoint`; everything failed and nothing was restored → `rewind_failed` (the conversation is left alone); the entry is not a rewind point on the active path → `invalid_arguments`. For conversation-only or code-only rewinds, a `custom_message{customType: "ama.rewind-note"}` is appended to the end of the context before the next prompt, telling the model which files disagree with the conversation.
 
-After a session switch the server re-subscribes to events and sends `session_start` for the new session (`reason` `new` / `resume` / `fork`). `new_session` does not use the `parentSession` parameter yet. Entry shapes are in [session-format.md](../session-format.md) (Chinese).
+After a session switch the server re-subscribes to events and sends `session_start` for the new session (`reason` `new` / `resume` / `fork`). `new_session` does not use the `parentSession` parameter yet. Entry shapes are in [session-format.md](../../reference/session-format.md) (Chinese).
 
 ### Approvals
 
@@ -120,7 +120,7 @@ After a session switch the server re-subscribes to events and sends `session_sta
 | `set_client_capabilities` | `capabilities: ("approvals" \| "images" \| "hooks" \| "plans" \| "compact_events")[]` | `{ capabilities }`                                                                                               |
 | `permission_response`     | `requestId: string`, `decision: "allow" \| "deny" \| "allow_session"`                 | `{ accepted: boolean }` (false = not currently waiting for this id; kept and applied when that request is asked) |
 
-`compact_events` (docs/memory-plan.md D9, Chinese): once declared, `turn_end.toolResults`, `message_start` and `entry_appended` no longer repeat the body of tool results and of user messages with images (marked `contentOmitted: true`); the body is sent only in `message_end` and `tool_execution_end`. Without it the event shapes are byte-for-byte unchanged. Shapes are in [Compact events](#compact-events-compact_events). `stream-json` has no such switch and always emits the full shapes.
+`compact_events` (docs/history/memory-plan.md D9, Chinese): once declared, `turn_end.toolResults`, `message_start` and `entry_appended` no longer repeat the body of tool results and of user messages with images (marked `contentOmitted: true`); the body is sent only in `message_end` and `tool_execution_end`. Without it the event shapes are byte-for-byte unchanged. Shapes are in [Compact events](#compact-events-compact_events). `stream-json` has no such switch and always emits the full shapes.
 
 ### Tools, permissions, discovery
 
@@ -144,7 +144,7 @@ After a session switch the server re-subscribes to events and sends `session_sta
 
 ### Traces (wave 6)
 
-`get_trace` returns the session trace (the same tree as the TUI `/trace` and `ama sessions trace`, see [tui.md](tui.md)
+`get_trace` returns the session trace (the same tree as the TUI `/trace` and `ama sessions trace`, see [tui.md](../guides/tui.md)
 "Traces"). There is no new event: after `entry_appended`, fetch again with the previous `cursor.since` to refresh incrementally.
 
 | Parameter    | Meaning                                                                                                                                                                                   |
@@ -227,7 +227,7 @@ There is also the non-session event `{"type":"notification","level":"info"|"warn
 
 `parentToolCallId` appears only on inner calls made through `tools.*` inside codemode scripts; its value is the id of the outer `codemode` call, which clients use to fold the display. Inner calls do not enter the transcript.
 
-Assistant messages in `message_end`, `turn_end`, `done` / `error` and in replays (`get_messages`, `get_entries`) may carry two optional fields (model efficiency batch, docs/model-efficiency-plan.md §1.10, Chinese): `retryAfterMs` on failed messages (`Retry-After`, in ms) and `rawArguments` on tool-call blocks (the raw argument string the model produced). `subagent_*` events are unchanged; `TaskInfo` from `get_tasks` may carry `context?: "fork" | "fresh"` (the sub-session's actual context mode). All are new optional fields, `RPC_PROTOCOL_VERSION` is unchanged, and clients can ignore fields they do not know.
+Assistant messages in `message_end`, `turn_end`, `done` / `error` and in replays (`get_messages`, `get_entries`) may carry two optional fields (model efficiency batch, docs/history/model-efficiency-plan.md §1.10, Chinese): `retryAfterMs` on failed messages (`Retry-After`, in ms) and `rawArguments` on tool-call blocks (the raw argument string the model produced). `subagent_*` events are unchanged; `TaskInfo` from `get_tasks` may carry `context?: "fork" | "fresh"` (the sub-session's actual context mode). All are new optional fields, `RPC_PROTOCOL_VERSION` is unchanged, and clients can ignore fields they do not know.
 
 ### Compact events (`compact_events`)
 
@@ -243,7 +243,7 @@ In the full shapes, the result of one tool call appears once each in `message_st
 
 ### Sub-agent events (wave 5)
 
-Sub-agents started by `task` / `task_ctl` (ama sub-sessions and external agents share the same events, see [agents.md](../agents.md), Chinese):
+Sub-agents started by `task` / `task_ctl` (ama sub-sessions and external agents share the same events, see [agents.md](../../guides/agents.md), Chinese):
 
 | Event                 | Fields                                                                                                                                                                                                                      |
 | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -349,7 +349,7 @@ The `data` of `get_session_stats` is `SessionStats`:
 {"type":"context_pressure","percent":71,"threshold":70,"remainingTokens":57990,"estimatedTurnsLeft":6}
 ```
 
-`cache_miss` gives `detail` only for `prefix_changed` (`tools`, `system`, or `system:<section,…>` naming the changed sections, such as `system:hooks,memory`). The values and meanings of `reason` for `cache_warm{stopped}` are in [tui.md](tui.md) "Cache and context". The result object of `ama -p --output-format json` also has a `cache` field of the same shape.
+`cache_miss` gives `detail` only for `prefix_changed` (`tools`, `system`, or `system:<section,…>` naming the changed sections, such as `system:hooks,memory`). The values and meanings of `reason` for `cache_warm{stopped}` are in [tui.md](../guides/tui.md) "Cache and context". The result object of `ama -p --output-format json` also has a `cache` field of the same shape.
 
 It also carries `context: { tokens, window, percent }` (context used, window size and usage 0–100, defined like `contextTokens` / `contextWindow` / `contextPercent` in the table above); an unknown item is omitted (for a model without a window only `tokens` is present), and when all are unknown there is no `context`.
 
@@ -363,7 +363,7 @@ It also carries `context: { tokens, window, percent }` (context used, window siz
 
 ## Plan approval
 
-Plan mode and the plan format are described in [plan.md](../plan.md) (Chinese).
+Plan mode and the plan format are described in [plan.md](../../guides/plan.md) (Chinese).
 
 1. When a turn ends in plan mode with plain text and the reply contains a `<proposed_plan>` block, the server saves the plan and sends `plan_proposed{ planId, version, markdown, steps, filePath? }` (`steps[]`: `{ id, text, dependsOn?, agent? }`), followed by `agent_settled` as usual.
 2. The client answers only if it declared `set_client_capabilities{capabilities:["plans"]}`; otherwise the config `plan.unattended` applies: `stop` by default (the plan stays proposed, no mode switch, no execution; the client can still answer later with `plan_response`), and `approve` approves and executes within the same run.
@@ -381,7 +381,7 @@ Plan mode and the plan format are described in [plan.md](../plan.md) (Chinese).
 
 - stdin closed: no more commands are accepted and approvals are withdrawn (later asks resolve as unanswered → deny); in-flight commands and started runs finish and their responses are written, then the exit code is 0. So `printf '{"type":"prompt","message":"hi"}\n' | ama --mode rpc` gets a complete reply; to stop early, send `abort` first.
 - SIGINT / SIGTERM: the current run is interrupted and the process exits in order, with exit code 130 / 143.
-- Startup failures use the CLI exit codes ([design.md](../design.md) §11.3, Chinese): config error 3, no model or key 4, session error 5, host / hook startup failure 6, host API version mismatch 78.
+- Startup failures use the CLI exit codes ([design.md](../../design/design.md) §11.3, Chinese): config error 3, no model or key 4, session error 5, host / hook startup failure 6, host API version mismatch 78.
 
 ## Examples
 

package/docs/{agents.md → guides/agents.md}

@@ -1,7 +1,7 @@
 # Agent：子 Agent 与外部 Agent
 
 模型只认识两个工具：`task`（委派）与 `task_ctl`（管理后台任务）。`task(agent=…)` 的 `agent` 既可以是 ama 自己的子 Agent
-类型，也可以是外部 CLI Agent（外部部分见下文「外部 Agent」节）。设计依据：[wave5-plan.md](wave5-plan.md) §7、D13、D22–D24。
+类型，也可以是外部 CLI Agent（外部部分见下文「外部 Agent」节）。设计依据：[wave5-plan.md](../history/wave5-plan.md) §7、D13、D22–D24。
 
 ## 子 Agent
 
@@ -92,7 +92,7 @@ ama 再跑一轮、在消息里要求「不要调用工具、直接给最终报
 `<task-notification>`：
 
 - 交互界面：`Ctrl+B` / `/tasks bg [id]` / Agent 栏里按 `b`（见 [tui.md](tui.md)「子 Agent」）；
-- RPC：`background_task { taskId? }`（[rpc.md](rpc.md)），SDK：`session.backgroundTask(taskId?)`，返回实际转了的 `taskId`；
+- RPC：`background_task { taskId? }`（[rpc.md](../reference/rpc.md)），SDK：`session.backgroundTask(taskId?)`，返回实际转了的 `taskId`；
   不给 `taskId` 时转全部前台运行中任务，正在 `task_ctl wait` 的等待也一并打断；
 - 自动：`subagents.autoBackgroundAfterMs` 大于 0 时，前台任务运行超过该毫秒数自动转后台（缺省 0 关闭）。
 
@@ -133,7 +133,7 @@ ama 再跑一轮、在消息里要求「不要调用工具、直接给最终报
 每个任务有会话内唯一的 `taskId`（`t1`、`t2` …）。子会话结束后不立即释放，最多保留 4 个（`subagents.retainSessions`；
 最久未用的先释放内存，JSONL 一直在）。`task{taskId}` / `task_ctl send` 续聊时，保留中的直接追加消息，已释放的按会话文件重新打开再追加——
 同一个任务始终写同一个 JSONL。父会话在任务开始、每次续聊与结束时写一条 `custom{ama.task}`
-（[session-format.md](session-format.md)）；`--resume` 时据此重建任务列表，当时还在运行的标 `interrupted`，仍可续聊。
+（[session-format.md](../reference/session-format.md)）；`--resume` 时据此重建任务列表，当时还在运行的标 `interrupted`，仍可续聊。
 内存会话（`--no-session`）的任务被释放后不能续聊。子会话转录常达数十 MB，保留得越多常驻内存越大；频繁轮换续聊
 5 个以上任务时可调大保留数，代价只是被释放的任务续聊时多一次从磁盘重开。
 
@@ -159,7 +159,7 @@ worktree 里与父 cwd 对应的目录。结束时没有改动（工作区干净
 - 类型声明了 `tools` / `disallowed-tools`（或参数给了 `tools`）时，工具表不变，不可用的工具在执行层拒绝
   （`Tool "X" is not available in this session.`），并在 `<task>` 里列出。只读类型照旧走只读管线。
 - `<task>` 同时列出按深度拒绝的 `task` / `task_ctl` 并要求不要调用它们（执行层仍是深度拒绝的文案）。实测仍有模型把父消息里
-  「调用 task」的指令当成自己的：调一次被拒，多一轮请求，有时随后只回报失败、不做子任务（见 [benchmarks](benchmarks/efficiency-2026-10.md)「F2」）。
+  「调用 task」的指令当成自己的：调一次被拒，多一轮请求，有时随后只回报失败、不做子任务（见 [benchmarks](../benchmarks/efficiency-2026-10.md)「F2」）。
 - `isolation: "worktree"` 时子会话的 cwd 是 worktree，`<task>` 里说明上文的相对路径指父目录；cwd 节变化以尾部补丁发送，
   不影响已缓存的前缀。
 
@@ -171,12 +171,12 @@ worktree 里与父 cwd 对应的目录。结束时没有改动（工作区干净
 何时用 fork：子任务需要你已经读过、讨论过的内容时。fork 的首个请求把父上下文整段带上，按命中价计费；fresh 只发系统提示、
 工具表与任务说明，但你得在 `prompt` 里写清全部背景，子 Agent 往往还要重新读文件。
 
-| 供应商（命中价 / 未命中价）     | 8k 父上下文 fork 一次（实测，见 [benchmarks](benchmarks/efficiency-2026-10.md)「F」） | 适合                         |
-| ------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------- |
-| DeepSeek（约 1/50）             | 命中 77%，与父自己的下一回合相同；折合约 1.9k 全价 token                              | 需要父上下文时几乎总划算     |
-| Kimi（约 1/4–1/10）             | 命中 97.5%                                                                            | 需要父上下文、且要重读较多时 |
-| OpenAI 系（经中转，不发路由键） | 两次分别 0% 与 85%，取决于中转把请求路由到哪个上游                                    | 视中转而定                   |
-| Anthropic（1/10，写入 1.25×）   | 未实测；前缀相同，命中应与父的下一回合相同                                            | 需要父上下文时               |
+| 供应商（命中价 / 未命中价）     | 8k 父上下文 fork 一次（实测，见 [benchmarks](../benchmarks/efficiency-2026-10.md)「F」） | 适合                         |
+| ------------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------- |
+| DeepSeek（约 1/50）             | 命中 77%，与父自己的下一回合相同；折合约 1.9k 全价 token                                 | 需要父上下文时几乎总划算     |
+| Kimi（约 1/4–1/10）             | 命中 97.5%                                                                               | 需要父上下文、且要重读较多时 |
+| OpenAI 系（经中转，不发路由键） | 两次分别 0% 与 85%，取决于中转把请求路由到哪个上游                                       | 视中转而定                   |
+| Anthropic（1/10，写入 1.25×）   | 未实测；前缀相同，命中应与父的下一回合相同                                               | 需要父上下文时               |
 
 fork 的成本不止首请求：子会话**每一回合**都重读整段父前缀。按命中价折算，8k 父上下文 × 30 回合在 DeepSeek（1/50）上约
 4.8k 全价 token，在 Kimi / Anthropic（1/4–1/10）上约 24k–60k，中转落空时全价。所以 DeepSeek 上子任务只要重读 ≥ 1 份
@@ -189,7 +189,7 @@ fork 的成本不止首请求：子会话**每一回合**都重读整段父前
 
 ### 事件与统计
 
-RPC / SDK 事件 `subagent_start` / `subagent_update` / `subagent_background` / `subagent_end` 见 [rpc.md](rpc.md)「子 Agent 事件」。
+RPC / SDK 事件 `subagent_start` / `subagent_update` / `subagent_background` / `subagent_end` 见 [rpc.md](../reference/rpc.md)「子 Agent 事件」。
 `getStats().tasks` 给出任务总数、运行中数量与按状态的计数；子会话的缓存命中与重计费仍汇总在 `cache.subagents`。
 RPC `get_tasks` / `get_agents` 返回任务快照与可用类型（来源、定义文件路径）。交互界面的 `/tasks`、`/agents` 与 task 工具行的折叠显示见 [tui.md](tui.md)「子 Agent」。
 
@@ -245,7 +245,7 @@ ama 改为直接驱动 `pi --mode rpc`，并以 `-e` 给这一次运行加载一
 
 每条路径在临时目录各跑两个会话：非 git 目录里两轮「只回 OK」+ 一次触发审批的写文件（`default` 模式）；git 目录里长输出时中断，再续一轮。
 模型用各家最便宜的：Claude `haiku`、Codex `gpt-6-luna`、Copilot `gpt-5-mini`、OpenCode `opencode/mimo-v2.6-flash-free`、pi `openai-codex/gpt-6-luna`。
-记录与原始数字见 [benchmarks/external-agents-2026-10.md](benchmarks/external-agents-2026-10.md)。
+记录与原始数字见 [benchmarks/external-agents-2026-10.md](../benchmarks/external-agents-2026-10.md)。
 
 | 路径                       | 两轮续聊 | 审批写文件                                        | 中断后续聊    | 用量 / 上下文                     | 非 git 目录    |
 | -------------------------- | -------- | ------------------------------------------------- | ------------- | --------------------------------- | -------------- |
@@ -313,7 +313,7 @@ ama 改为直接驱动 `pi --mode rpc`，并以 `-e` 给这一次运行加载一
 | `full-auto` | `auto`（从不给 `bypassPermissions`） | `never` / `workspace-write`（从不给 `danger-full-access`） | 同上                                                     |
 
 上表 ACP 一列是缺省规则；模式 id 与 ama 不同名的 Agent 在驱动表里有显式映射（见上文「实测能力矩阵」后的说明）。
-ACP Agent 不给 `modes`、改用 category `mode` 的配置项表达模式时，按上表同一映射在配置项的可选值里找，经 `session/set_config_option` 设置（见 [acp.md](acp.md)「作为客户端」）。
+ACP Agent 不给 `modes`、改用 category `mode` 的配置项表达模式时，按上表同一映射在配置项的可选值里找，经 `session/set_config_option` 设置（见 [acp.md](../reference/acp.md)「作为客户端」）。
 
 一次性打印模式不能审批，只在只读任务下用。
 

package/docs/{codemode.md → guides/codemode.md}

@@ -1,6 +1,6 @@
 # codemode
 
-设计依据见 [design.md](design.md) §5.5、§5.6、§9.1。
+设计依据见 [design.md](../design/design.md) §5.5、§5.6、§9.1。
 
 `codemode` 工具让模型写一段 JavaScript，在脚本里经 `tools.*` 编排多次工具调用，只有脚本输出回到模型。长流程、工具密集的任务里，它把多次往返合成一次，减少往返次数与缓存读取；短任务里模型照常直接调用工具，codemode 只多占约 400 token 前缀，所以 `default` 预设在网络隔离的运行时上缺省开着它。
 
@@ -24,7 +24,7 @@
 
 缺省配置里不写 `codemode.mode`（`ama init` 生成的 `config.json` 也不写），所以这张映射以后调整时老用户同样生效。`ama config show` / `ama doctor` 显示生效模式与原因（跟随哪个预设、网络由 Node 还是操作系统沙箱隔离）；`ama doctor` 另列操作系统沙箱能力。
 
-`minimal` / `coordinator` 预设缺省不带 codemode，也没有 grep / glob：模型找代码只能用 bash（`default` 权限模式下每次审批、`-p` 下被拒）。要检索就 `tools.default: ["+grep","+glob"]` 直接加上，比为了检索打开 codemode 便宜（见 [design.md](design.md) §5.6）；`codemode-only` 的脚本里 `tools.grep()` / `tools.glob()` / `tools.ls()` 都可调用。
+`minimal` / `coordinator` 预设缺省不带 codemode，也没有 grep / glob：模型找代码只能用 bash（`default` 权限模式下每次审批、`-p` 下被拒）。要检索就 `tools.default: ["+grep","+glob"]` 直接加上，比为了检索打开 codemode 便宜（见 [design.md](../design/design.md) §5.6）；`codemode-only` 的脚本里 `tools.grep()` / `tools.glob()` / `tools.ls()` 都可调用。
 
 `coordinator` 预设即使显式 `on`，脚本里能调用的工具也只限它的活动集（read 与宿主工具）：`tools.bash`、`tools.write` 在脚本里同样不存在，协调者「不写文件、不跑 bash」的约定不能经 codemode 绕过。
 
@@ -87,7 +87,7 @@
 
 - `codemode` 本身作为一次工具调用经过 PreToolUse、权限与 PostToolUse。
 - 脚本里的每次 `tools.*` 再各自经过完整流程，Hook 按**真实工具名**匹配（`bash`，不是 `codemode`）；Hook 输入多两个字段：`viaCodemode: true` 与 `parentToolCallId`（外层 `codemode` 调用的 id）。
-- 事件：`tool_execution_update` 透传脚本输出（最近 4000 字符）；内层调用发 `tool_execution_start / end`，带 `parentToolCallId`，不进转录、不进模型上下文。`ama --mode acp` 把每次内层调用单列为一条 `tool_call`（标题前缀 `codemode › `，`_meta.ama.parentToolCallId` 指向外层），其权限请求关联到这条内层调用（见 [acp.md](acp.md)）。
+- 事件：`tool_execution_update` 透传脚本输出（最近 4000 字符）；内层调用发 `tool_execution_start / end`，带 `parentToolCallId`，不进转录、不进模型上下文。`ama --mode acp` 把每次内层调用单列为一条 `tool_call`（标题前缀 `codemode › `，`_meta.ama.parentToolCallId` 指向外层），其权限请求关联到这条内层调用（见 [acp.md](../reference/acp.md)）。
 
 ## 沙箱
 

package/docs/{hooks.md → guides/hooks.md}

@@ -1,6 +1,6 @@
 # 命令式 Hook（hooks.json）
 
-命令式 Hook 是在固定时机运行的 shell 命令：ama 把事件写成 JSON 交给命令的 stdin，按退出码与 stdout JSON 决定放行、阻止或改写。它是**用户策略**层——可以改工具输入、一票否决工具调用、给提示追加上下文、让运行再跑一轮。类型定义在 `src/hooks/types.ts`（经 `@armadra/agent` 导出 `HookInput`、`HookOutput`、`HookConfig` 等）。设计依据见 [design.md](design.md) §6.1、§6.3、§7.3。
+命令式 Hook 是在固定时机运行的 shell 命令：ama 把事件写成 JSON 交给命令的 stdin，按退出码与 stdout JSON 决定放行、阻止或改写。它是**用户策略**层——可以改工具输入、一票否决工具调用、给提示追加上下文、让运行再跑一轮。类型定义在 `src/hooks/types.ts`（经 `@armadra/agent` 导出 `HookInput`、`HookOutput`、`HookConfig` 等）。设计依据见 [design.md](../design/design.md) §6.1、§6.3、§7.3。
 
 ## 配置
 
@@ -125,7 +125,7 @@ interface HookOutput {
 - `additionalContext` / `customInstructions` 按配置顺序拼接。
 - 任一 Hook 返回 `continue: false` 即请求结束运行。
 
-一次工具调用的完整顺序（[design.md](design.md) §6.3）：
+一次工具调用的完整顺序（[design.md](../design/design.md) §6.3）：
 
 ```text
 模型产出工具调用

package/docs/guides/i18n.md

@@ -0,0 +1,93 @@
+# 界面语言（中英双语）
+
+> 第六波（docs/history/wave6-plan.md §5、D18–D23）。本文是开发约定：怎么选语言、文案放哪、键怎么起名、怎么测。
+> 调研依据见 [research/wave6/R8-i18n.md](../research/wave6/R8-i18n.md)。
+
+## 语言怎么定
+
+优先级从高到低，**进程启动时定一次**，不做运行中切换：
+
+1. 环境变量 `AMA_LANG`（`zh` / `en`，`zh_CN` 之类也认；写错的值忽略）；
+2. 命令行 `--lang zh|en`（也可写在子命令前：`ama --lang en doctor`）；SDK `createRuntime({ language })` / `createAgentSession({ language })` 等价；
+3. profile 的 `language`（嵌入宿主跟随画布界面语言）；
+4. 配置 `ui.language`（`auto` / `zh` / `en`，缺省 `auto`；用户级 / 项目级都可设）；
+5. `LC_ALL` → `LC_MESSAGES` → `LANG` 第一个非空值：`zh*` 为中文，其余（含 `C`、`POSIX`、`en_*`）为英文；
+6. 都没有：英文。
+
+`cli/main.ts` 在解析参数后、任何输出前按 1、2、用户级 `ui.language`、5 定语言；bootstrap 合并 profile 与项目级后，若它们给了 `ui.language` / `language`，再补定一次（仍以 1、2 为准）。`ama doctor` 显示「界面语言：zh（来源 LANG=zh_CN.UTF-8）」（`resolveLocaleWithSource`）。
+
+**界面语言只影响给人看的文字。** 发给模型的一切（系统提示、工具描述、工具结果里的标记、截断 / 裁剪占位、外部 Agent 报告、Hook 阻止理由、拒绝理由）固定英文，两种语言下请求逐字节相同。想让模型用某种语言回复，用 `ui.replyLanguage`（在 `rules` 节末尾追加一句英文规则，不设时零字节变化）。
+
+## 文案放哪
+
+```text
+src/i18n/
+  index.ts      Locale、resolveLocale / resolveLocaleWithSource、setLocale / getLocale、msg()、messagesFor()
+  types.ts      Messages<T>
+  format.ts     plural()、formatDuration()
+  catalog.ts    汇总全部领域（第六波 C0 一次登记，之后无人再改）
+  messages/<领域>.ts
+```
+
+| 领域文件                                                                    | 归属批次                              |
+| --------------------------------------------------------------------------- | ------------------------------------- |
+| `cli`、`subcommands`                                                        | W6-I1                                 |
+| `interactive`、`approval`、`plan`、`rewind`、`panels`、`permissions`        | W6-I2                                 |
+| `report`、`print`、`drivers`、`session`、`errors`                           | W6-I3                                 |
+| `config`                                                                    | W6-I4                                 |
+| `agents` / `trace` / `memory` / `auth` / `settings`                         | W6-A / W6-T1、T2 / W6-M / W6-O / W6-S |
+| `acp`（子对象 `core` / `auth` / `session` / `tools` / `config` / `client`） | ACP-C0 建，各子对象归 ACP 补全的批次  |
+
+每个领域文件同时导出 `en`（形状源）与 `zh`：
+
+```ts
+import { plural } from "../format.js";
+import type { Messages } from "../types.js";
+
+export const en = {
+  limitTurns: (limit: number) => `ama: reached the turn limit ${limit}; run ended early`,
+  dirSummary: (files: number, size: string) => `directory, ${plural(files, "file")}, ${size}`,
+  approval: { title: "Approve tool call", keys: { allow: "allow", deny: "deny" } },
+};
+
+export const zh = {
+  limitTurns: (limit) => `ama: 已达到回合上限 ${limit}，运行在完成前结束`,
+  dirSummary: (files, size) => `目录，${files} 个文件，${size}`,
+  approval: { title: "Approve tool call", keys: { allow: "allow", deny: "deny" } },
+} satisfies Messages<typeof en>;
+```
+
+`satisfies Messages<typeof en>` 让缺键、多键、参数个数 / 类型不符都在 `tsc` 期报错——两种语言必须同时给。
+
+取用：`const m = msg().print; io.stderr(m.limitTurns(limit))`。用嵌套属性访问，不用字符串键。
+
+## 键名规范
+
+- 领域文件名即一级命名空间（`msg().approval…`）；
+- 叶子 camelCase，按「组件.用途」分组：`approval.title`、`approval.keys.allow`、`rewind.skip.failed`；
+- 不以文案内容命名（`notInstalled` 可以，`weiAnZhuang` 不行）；
+- **整句一个键，禁止片段拼接**：英文语序不同，`"追加写入" + 词 + 路径` 这种要写成一个函数，条件分支写进函数体；
+- 插值写成箭头函数，参数类型写在 en 上；复数只英文需要，用 `plural(n, "file")`（不规则词给第三参数）；
+- 紧凑时长 `formatDuration(ms)`（`45s` / `2m 10s` / `1h24m`）两种语言共用；`formatTokens` / `formatUsd` / `formatPercent`、日期（ISO）与 compact 状态行记号（`ctx`、`cache`、`$`、`↑ ↓`、`⎇`、`·`）不译；
+- 枚举值、命令名、配置键、动作 id、错误码不译。
+
+## 不要这样做
+
+- **模块顶层求值**：`const HELP = msg().cli.help` 会按 import 时的语言定死（SDK / 嵌入场景显示错语言）。改成函数或 getter；`scripts/check-i18n.mjs` 会拦。
+- **按文案判断逻辑**：`text === "未安装"`、`reason.startsWith("失败")`。界面文案会随语言变，逻辑用枚举 / 码（第六波 C0 已把三处改掉）。用户**输入**的别名（`批准`、`步骤`、粘贴标记 `[粘贴 #` / `[paste #`）两种语言同时识别，与界面语言无关。
+- **模型侧模块 import `src/i18n`**：系统提示、工具（`src/tools/**`）、Plan 提示、内置子 Agent、Skill、压缩、codemode 声明、Memory 工具不得 import——`src/i18n/guard.test.ts` 守着。这些模块需要给人看的错误时抛 `AmaError(code, englishMessage, { detail })`，由界面层按 `detail` 渲染（例：`tools/image-file.ts` → `modes/image-input.ts` 的 `msg().errors.imageFile(detail)`）。
+- **宿主解析 `message`**：RPC / ACP 的 `error.message`、`-p` 的 stderr 是人读文本，会随语言变；宿主按 `code` 判断。
+
+## 测试
+
+- 测试缺省钉 zh：`test/helpers/setup.ts` 设 `AMA_LANG=zh` 并 `setLocale("zh")`，子进程也是 zh。迁移批次的验收是现有 zh 帧黄金与断言**字节不变**。
+- en 用例自己 `setLocale("en")`（或传 `AMA_LANG=en`），用完在 `afterEach` 里 `setLocale("zh")`；en 帧黄金放 `test/fixtures/tui/en/`。
+- `src/cli/lang-independence.test.ts`：同一脚本在 zh / en 下各跑一遍，发给供应商的请求逐字节相同。
+- `scripts/check-i18n.mjs`（`pnpm check:i18n`，在 `pnpm ci` 里）：
+  1. 严格（W6-I5 起，基线已清零删除）：`src/**` 源码里含汉字的代码行（注释不算）**出现即失败**。不扫的文件（测试、测试支撑、`src/i18n/`、models.dev 上游快照）在脚本的 `SKIPPED`，允许的行（用户输入别名、粘贴标记识别、价格覆盖数据的 `_reason`）在 `ALLOWED_LINES`，每条都写了理由；新增条目要在 PR 里说明；
+  2. `en` 目录里不得有汉字，`zh` 目录里不得留 `TODO`；
+  3. 顶层常量不得立即调用 `msg()`。
+
+## 体积
+
+bundle 用 `charset: "utf8"` 输出（中文按 UTF-8 原样，不转 `\uXXXX`），抵消英文目录带来的增量。

package/docs/{memory.md → guides/memory.md}

@@ -1,6 +1,6 @@
 # 记忆（Memory）
 
-> 第六波 W6-M（设计见 [wave6-plan.md](wave6-plan.md) §3、D8–D12；调研 [research/wave6/R7-memory.md](research/wave6/R7-memory.md)）。
+> 第六波 W6-M（设计见 [wave6-plan.md](../history/wave6-plan.md) §3、D8–D12；调研 [research/wave6/R7-memory.md](../research/wave6/R7-memory.md)）。
 
 跨会话的个人笔记：你说「记住……」，模型把它写成一条 Markdown，下次会话开始时索引进系统提示，正文按需读取。
 **缺省关闭**；关闭时不读盘、不注册工具、不渲染节，发给模型的请求与没有这个功能时逐字节相同。

package/docs/{permissions.md → guides/permissions.md}

@@ -1,6 +1,6 @@
 # 权限模式与 auto 判定
 
-本文写 ama 的六种权限模式、每次工具调用的判定顺序，以及 `auto` 模式「规则层 → 静态判定 → 模型分类器」三层怎样决定放行还是询问。总体设计见 [design.md](design.md) §6.3、§7；Hook 的输入输出见 [hooks.md](hooks.md)。
+本文写 ama 的六种权限模式、每次工具调用的判定顺序，以及 `auto` 模式「规则层 → 静态判定 → 模型分类器」三层怎样决定放行还是询问。总体设计见 [design.md](../design/design.md) §6.3、§7；Hook 的输入输出见 [hooks.md](hooks.md)。
 
 ## 模式
 
@@ -42,7 +42,7 @@
 | 外部 Agent（claude / codex / ACP）请求权限 | `[claude · 会话 abc12345]`                | 外部 Agent 给的标题、种类、涉及路径与输入摘要 | 只交给人：宿主 → 界面 → 无人值守拒绝，auto 分类器与模型不参与              |
 | 外部 Agent 本会话首次运行                  | 标题「首次运行外部 Agent」                | 说明（以你在该 CLI 的登录运行）与模式         | allow / deny 规则 `task(<id>)`、`full-auto` 放行，其余交给人（不经分类器） |
 
-外部 Agent 的「本会话允许」由它自己记住。Manual 模式下 `task(agent=…)` 的 task 调用审批与首次运行确认合并为一次（见 [agents.md](agents.md)「在 task 里使用」）。RPC 的 `context` 是 `{ depth, taskId, origin }`（[rpc.md](rpc.md)「审批」）。
+外部 Agent 的「本会话允许」由它自己记住。Manual 模式下 `task(agent=…)` 的 task 调用审批与首次运行确认合并为一次（见 [agents.md](agents.md)「在 task 里使用」）。RPC 的 `context` 是 `{ depth, taskId, origin }`（[rpc.md](../reference/rpc.md)「审批」）。
 
 ## plan 模式与只读命令
 

package/docs/{plan.md → guides/plan.md}

@@ -1,6 +1,6 @@
 # Plan 模式
 
-plan 模式让 ama 先只读调研、写出一份结构化的计划，经人批准后再切回执行模式按计划推进。本文写流程、计划格式、审批的几种入口、配置与持久化；权限细节见 [permissions.md](permissions.md)「plan 模式与只读命令」，设计依据见 [wave5-plan.md](wave5-plan.md) §6。
+plan 模式让 ama 先只读调研、写出一份结构化的计划，经人批准后再切回执行模式按计划推进。本文写流程、计划格式、审批的几种入口、配置与持久化；权限细节见 [permissions.md](permissions.md)「plan 模式与只读命令」，设计依据见 [wave5-plan.md](../history/wave5-plan.md) §6。
 
 ## 流程
 
@@ -54,7 +54,7 @@ plan 模式让 ama 先只读调研、写出一份结构化的计划，经人批
 | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | 交互（TUI）                          | 用户在底部审批框里选：批准并执行 / 批准，在新上下文执行（两者接着选执行模式：回到进入前的模式 / Accept edits / Auto）/ 继续修改（框内或外部编辑器写意见）/ 放弃并退出 Plan；`e` 在 `$VISUAL` / `$EDITOR` 里改计划，Esc 放弃但留在 Plan。见 [tui.md](tui.md)「Plan 审批」 |
 | 交互（line，`--no-tui`）             | `/plan approve [模式\|fresh]`、`/plan reject`；回复 `1` / `2` / `3` 也能批准（进入前的模式 / Accept edits / Auto），其它内容作为修改意见、留在 plan                                                                                                                      |
-| RPC，声明了 `plans` 能力             | 客户端：`plan_proposed` → `plan_response`（见 [rpc.md](rpc.md)「计划审批」）                                                                                                                                                                                             |
+| RPC，声明了 `plans` 能力             | 客户端：`plan_proposed` → `plan_response`（见 [rpc.md](../reference/rpc.md)「计划审批」）                                                                                                                                                                                |
 | SDK，给了 `plan.onProposed`          | 回调：运行结束后调用，返回 `{ decision, mode?, feedback?, editedMarkdown? }`；返回 undefined 留待 `session.plan.respond()`                                                                                                                                               |
 | `-p`、未声明能力的 RPC、无回调的 SDK | 配置 `plan.unattended`：`stop`（缺省）落盘计划后停下，不切模式、不执行；`approve` 在同一次运行里自动批准并执行                                                                                                                                                           |
 
@@ -65,7 +65,7 @@ plan 模式让 ama 先只读调研、写出一份结构化的计划，经人批
 - **revise**：留在 plan；`feedback` 作为普通用户消息开回合，模型整份重写计划，新版本号 +1，旧版标 superseded。
 - **reject**：计划标 rejected，留在 plan。交互界面的「放弃，退出 Plan 模式」在 reject 之后切回进入前的模式；审批框里按 Esc 是 reject 但留在 plan。
 
-**进度记法**：活动工具集里有 `todo`（`tools.default: ["+todo"]`、`--tools …,todo`）时，交接消息请模型「按 todo 推进，每完成一步 todo update」；没有时（`default` 预设缺省不含 todo，见 D20 与 [docs/benchmarks/](https://github.com/Owlbay/armadra-agent/tree/main/docs/benchmarks)）请模型每完成一步在回复里**单独一行**写 `[DONE:<步骤 id>]`（如 `[DONE:S1]`），ama 在回合结束时读这些标记：对应的计划待办标 done，没有进行中的项时下一个 pending 转 in_progress，照常落 `ama.todo`、发 `todo_updated`，界面与 RPC 的进度显示不受影响。「在新上下文执行」的首条消息用同样的规则。
+**进度记法**：活动工具集里有 `todo`（`tools.default: ["+todo"]`、`--tools …,todo`）时，交接消息请模型「按 todo 推进，每完成一步 todo update」；没有时（`default` 预设缺省不含 todo，见 D20 与 [docs/benchmarks/](https://github.com/AMA-Link/armadra-agent/tree/main/docs/benchmarks)）请模型每完成一步在回复里**单独一行**写 `[DONE:<步骤 id>]`（如 `[DONE:S1]`），ama 在回合结束时读这些标记：对应的计划待办标 done，没有进行中的项时下一个 pending 转 in_progress，照常落 `ama.todo`、发 `todo_updated`，界面与 RPC 的进度显示不受影响。「在新上下文执行」的首条消息用同样的规则。
 
 客户端改过的全文（`editedMarkdown`，界面里「在外部编辑器里改」）先落一份新版本，交接消息用改后的全文。
 
@@ -100,7 +100,7 @@ plan 模式让 ama 先只读调研、写出一份结构化的计划，经人批
 
 ## 接口
 
-- RPC：命令 `plan_response` / `get_plan` / `get_todos`，能力 `plans`，事件 `plan_proposed` / `plan_resolved` / `todo_updated`，见 [rpc.md](rpc.md)。
+- RPC：命令 `plan_response` / `get_plan` / `get_todos`，能力 `plans`，事件 `plan_proposed` / `plan_resolved` / `todo_updated`，见 [rpc.md](../reference/rpc.md)。
 - SDK：`createAgentSession({ plan: { bash?, directory?, unattended?, model?, thinkingLevel?, onProposed? } })`；返回的会话有 `session.plan.current()`、`session.plan.respond(response)`、`session.plan.todos()`。
 - 进程内：`planController(session)`（`src/agent/session-plan.ts`）给界面用——`pending()`、`respond()`、`proposeFromLastReply()`、`adopt()`、`setAttendance()`。
 - 交互界面：底部审批框（四个选项 + 执行模式、`e` 编辑计划、Esc 留在 Plan）、`/plan` 面板，`/plan <目标>` 进入 Plan 并发出目标，`/plan approve [模式|fresh]` / `/plan reject` 不开对话框直接作答；见 [tui.md](tui.md)「Plan 审批」。

package/docs/{providers.md → guides/providers.md}

@@ -1,6 +1,6 @@
 # 供应商与模型
 
-内置供应商、模型引用、API Key、自定义供应商与中转站、各协议的 compat 开关，以及缓存。设计依据见 [design.md](design.md) §3、§9.1。
+内置供应商、模型引用、API Key、自定义供应商与中转站、各协议的 compat 开关，以及缓存。设计依据见 [design.md](../design/design.md) §3、§9.1。
 
 ## 配置目录
 
@@ -629,9 +629,9 @@ OpenRouter 的 Messages 接口只在 `message_delta` 里给缓存 usage，解析
 
 长任务的主要用量是缓存读取：前缀一旦变化，此后每次请求都要按全价重读。ama 分三层处理缓存：**协议层**按各家写法打断点、发缓存键与保留层级，并标记响应里有没有缓存字段；**会话层**记录每次请求的前缀指纹，检测未命中、判定端点报不报缓存、在长工具运行期间保温；**展示层**是状态栏、`/session`、RPC 统计与 `ama models cache-probe`（界面怎么读见 [tui.md](tui.md)「缓存与上下文」）。
 
-前缀稳定由组装保证：系统提示节顺序固定、不含时间戳，工具按名排序，会话中途的变化只以 system 补丁追加在末尾（[session-format.md](session-format.md)「消息」）。
+前缀稳定由组装保证：系统提示节顺序固定、不含时间戳，工具按名排序，会话中途的变化只以 system 补丁追加在末尾（[session-format.md](../reference/session-format.md)「消息」）。
 
-**开头的 system 与工具声明在会话内只写一次。** 对话开始之后的节补丁（resume 时 AGENTS.md、Skills 或 SessionStart Hook 输出变了，宿主 instructions 刷新，压缩后记忆节重新渲染）不改写开头：没有打开 `supportsMidConvoSystemMessages` 的协议把它渲染成 `<system-reminder>` 包裹的 user 消息，插在补丁所在的位置，之前的请求仍是逐字节前缀。实测 DeepSeek 接受对话中途的 system 消息、前缀缓存也保持，但模型仍按开头那条回答，所以 DeepSeek 不打开这个开关（[cache-midconvo-2026-10-09](benchmarks/cache-midconvo-2026-10-09.md)）。
+**开头的 system 与工具声明在会话内只写一次。** 对话开始之后的节补丁（resume 时 AGENTS.md、Skills 或 SessionStart Hook 输出变了，宿主 instructions 刷新，压缩后记忆节重新渲染）不改写开头：没有打开 `supportsMidConvoSystemMessages` 的协议把它渲染成 `<system-reminder>` 包裹的 user 消息，插在补丁所在的位置，之前的请求仍是逐字节前缀。实测 DeepSeek 接受对话中途的 system 消息、前缀缓存也保持，但模型仍按开头那条回答，所以 DeepSeek 不打开这个开关（[cache-midconvo-2026-10-09](../benchmarks/cache-midconvo-2026-10-09.md)）。
 
 工具表同理：对话开始后新加的工具追加在工具表末尾；**移除工具不删声明**，提醒里写一句 `Tool "X" is no longer available in this session; calls to it are rejected.`，模型仍去调用时执行层拒绝（`Tool "X" is not available in this session.`）；再加回只提醒 `Tool "X" is available again.`，声明沿用第一次发送的版本。系统提示的 `tools` / `rules` 两节在对话开始后也冻结为已发送的文本。
 
@@ -748,7 +748,7 @@ xAI、Mistral、OpenRouter、Google 没有承诺的 TTL，留空：不保温、
 | 取消   | 换模型、换思考级别、压缩、`/tree`、退出时取消，下一次真实请求再开始                                                                                                                        |
 | 记账   | 成功的保温追加 `usage{kind:"cache_warm"}` 条目（不进上下文），计入 `/session` 费用与 RPC 统计；事件 `cache_warm{scheduled｜sent｜stopped}`                                                 |
 
-宿主可以经 `api.cache.onWarmingDecision` 否决或强制每一次保温（[host-api.md](host-api.md)「缓存保温」）。子会话缺省不保温（`cache.warmSubagents: true` 打开）。按目录价格估算，长工具运行期间几乎总是划算；空闲保温只对贵模型、长前缀划算。
+宿主可以经 `api.cache.onWarmingDecision` 否决或强制每一次保温（[host-api.md](../reference/host-api.md)「缓存保温」）。子会话缺省不保温（`cache.warmSubagents: true` 打开）。按目录价格估算，长工具运行期间几乎总是划算；空闲保温只对贵模型、长前缀划算。
 
 ### 压缩摘要续写
 

package/docs/{sessions.md → guides/sessions.md}

@@ -1,6 +1,6 @@
 # 会话统计、检索、复用、导出与检查点
 
-这几条命令都只读会话目录（`<数据目录>/sessions`，`--session-dir` 可改；文件格式见 [session-format.md](session-format.md)）：不加锁、不修复半行、不改文件，正在运行的会话也能读。会话文件按块逐行读取，不整份读进内存：`ama sessions list` 只解析每个文件的头、首条条目、改名与首条提示，其余行只看类型，几十 MB 的会话也不会让内存随文件大小上涨；`--resume` 打开会话同样逐行解析。范围缺省是**当前目录**的会话，`--all` 看全部。
+这几条命令都只读会话目录（`<数据目录>/sessions`，`--session-dir` 可改；文件格式见 [session-format.md](../reference/session-format.md)）：不加锁、不修复半行、不改文件，正在运行的会话也能读。会话文件按块逐行读取，不整份读进内存：`ama sessions list` 只解析每个文件的头、首条条目、改名与首条提示，其余行只看类型，几十 MB 的会话也不会让内存随文件大小上涨；`--resume` 打开会话同样逐行解析。范围缺省是**当前目录**的会话，`--all` 看全部。
 
 ## 统计：`ama stats`
 
@@ -154,7 +154,7 @@ ama sessions trace <id|文件> [--html [文件]] [--json] [--output <文件>] [-
 - `--no-content`：只留结构、时间与数字（没有提示、参数、结果，也没有错误原文），适合只想分享性能问题时。
 - `--children`：内嵌 ama 子 Agent 子会话里节点的预览；缺省只嵌它们的结构与数字。外部 Agent 本来就只有骨架。
 - 预览按条截断（参数 500、其余 2000 字符），整份预览上限 4 MB 字符，超出后更早的预览置空并在详情里注明。
-- `--json`（或 `--format json`）：与 RPC `get_trace` 同形的 JSON（[rpc.md](rpc.md)「轨迹」），包含全部回合、已加载的子会话轨迹与本会话节点的 `previews`
+- `--json`（或 `--format json`）：与 RPC `get_trace` 同形的 JSON（[rpc.md](../reference/rpc.md)「轨迹」），包含全部回合、已加载的子会话轨迹与本会话节点的 `previews`
   （`--no-content` 时没有）。
 - 输出：`--html <文件>`（文件名以 `.html` / `.htm` 结尾时才当作值，否则用 `--output`）或 `--output <文件>` 写文件（0600），否则写 stdout。
   `--open` 写好后用系统浏览器打开（没给文件时写到临时目录）。
@@ -163,7 +163,7 @@ ama sessions trace <id|文件> [--html [文件]] [--json] [--output <文件>] [-
 
 ## 检查点与文件备份
 
-回滚代码（`/rewind`，设计见 [rewind-plan.md](rewind-plan.md)）依赖检查点：每个新回合开始时，ama 记下 edit / write 改过的文件当时的内容。
+回滚代码（`/rewind`，设计见 [rewind-plan.md](../history/rewind-plan.md)）依赖检查点：每个新回合开始时，ama 记下 edit / write 改过的文件当时的内容。
 
 - **存储位置**：备份按内容 sha256 存在 `<数据目录>/file-history/blobs/<前 2 位>/<sha256>`，原字节、不压缩；多个会话、多个检查点共用，同内容只存一份。会话文件里只有 `ama.checkpoint` / `ama.checkpoint-track` 两类 `custom` 条目（记哈希，不进上下文）。会话目录不在缺省位置时（`--session-dir`、宿主 profile 的 `sessionDir`），目录登记在 `file-history/roots.json`，清理时一并扫描。
 - **跟踪范围**：edit / write（含 codemode 内层调用与 task 子会话）第一次写某文件之前备份它；之后每个新回合按当前磁盘内容重拍已跟踪的文件，所以 bash 或手动对这些文件的改动也会进下一个检查点。bash 新建或改动的其它文件不跟踪。
@@ -192,7 +192,7 @@ ama sessions trace <id|文件> [--html [文件]] [--json] [--output <文件>] [-
 
 ## 回滚（会话内）
 
-`/rewind`、RPC `rewind`、SDK `session.rewind()` 回到某条用户消息之前（设计见 [rewind-plan.md](rewind-plan.md)）：
+`/rewind`、RPC `rewind`、SDK `session.rewind()` 回到某条用户消息之前（设计见 [rewind-plan.md](../history/rewind-plan.md)）：
 
 - 回滚点是活动路径上开启新回合的用户消息，从旧到新；运行中插话、排队消息与 Stop Hook 续跑的消息并入当前回合，不单列。运行中回滚报 `busy`。
 - 对话回滚复用 `/tree` 换叶子：离开的分支留在文件里，可以再从 `/tree` 回去；模型、思考级别与权限模式保持当前，不随回滚改变。之后第一次请求的 system、工具表与落点之前的消息和回滚前逐字节相同，提示缓存照常命中。
@@ -200,7 +200,7 @@ ama sessions trace <id|文件> [--html [文件]] [--json] [--output <文件>] [-
 - 仅对话或仅代码时，下一次提示前在末尾追加一条 `ama.rewind-note` 告诉模型哪些文件与对话不一致；对话 + 代码不追加。
 - 内存会话与 `checkpoints.mode: "off"` 不建检查点，只能仅对话。
 - 运行中 Esc 中断、本回合还没有任何回复或工具调用时，撤回该回合并回填原消息（`ui.restoreOnCancel`，缺省 true）。
-- 回到图片被降级之前时图片从会话文件回读；文件已被外部改写、读不回时图片保留为空，并告警一次（`AMA_LOG`，TUI 显示在通知区；见 [session-format.md](session-format.md)「内存表示」）。
+- 回到图片被降级之前时图片从会话文件回读；文件已被外部改写、读不回时图片保留为空，并告警一次（`AMA_LOG`，TUI 显示在通知区；见 [session-format.md](../reference/session-format.md)「内存表示」）。
 
 ## 请求明细（设计，未实现）
 

package/docs/{tui.md → guides/tui.md}

@@ -1,12 +1,12 @@
 # 终端界面
 
-交互模式的使用说明，以及终端组件库 `@armadra/agent/tui` 的 API。设计依据见 [design.md](design.md) §12。
+交互模式的使用说明，以及终端组件库 `@armadra/agent/tui` 的 API。设计依据见 [design.md](../design/design.md) §12。
 
 `ama` 在终端里直接运行（stdin / stdout 都是 TTY、`TERM` 不是 `dumb`、没有 `--no-tui`）时进入交互模式。界面只用**主屏**：对话历史滚进终端回滚，不切备用屏，所以在 tmux 里 `capture-pane` 能读到完整对话，退出后对话也留在屏幕上。
 
 ## 布局
 
-视觉规格（配色、字形、逐屏样稿）见 [tui-design.md](tui-design.md)。层级用缩进表达：第 0 列是用户 `›`、工具 `⏺` 与提示符号，第 2 列是结果连接符 `⎿`，第 4 列是工具输出；去掉颜色（`NO_COLOR`、`capture-pane` 不带 `-e`）也读得出结构。
+视觉规格（配色、字形、逐屏样稿）见 [tui-design.md](../design/tui-design.md)。层级用缩进表达：第 0 列是用户 `›`、工具 `⏺` 与提示符号，第 2 列是结果连接符 `⎿`，第 4 列是工具输出；去掉颜色（`NO_COLOR`、`capture-pane` 不带 `-e`）也读得出结构。
 
 ```
  ▄███▄  ██▄   ▄██  ▄███▄    ama 0.6.2                     ← 启动头（normal 档）
@@ -148,11 +148,11 @@ Accept edits | shift+tab 切换    claude-opus-5-5 medium | Ctx 3.0% 8.2k/272k a
 
 缺省键选 `Ctrl+X` 的原因：macOS Terminal、iTerm2、tmux、Windows Terminal 都原样送达，且没有别的绑定；`Ctrl+Enter` 不开 kitty 键盘协议时与 Enter 无法区分，`Ctrl+S` 可能被 XOFF 流控吃掉，`Alt+Enter` 已是 followUp，`Alt+字母` 在 macOS 缺省不送 Meta，`Ctrl+]` 在非美式键盘上难按。可在 `keybindings.json` 改。
 
-line 模式（`--no-tui`）运行中输入 `/interrupt <文本>` 效果相同（空闲时就是普通提示）；交互界面里也认这条命令。RPC 是 `prompt` / `steer` 的 `interrupt: true`，见 [rpc.md](rpc.md)。
+line 模式（`--no-tui`）运行中输入 `/interrupt <文本>` 效果相同（空闲时就是普通提示）；交互界面里也认这条命令。RPC 是 `prompt` / `steer` 的 `interrupt: true`，见 [rpc.md](../reference/rpc.md)。
 
 ## 回滚
 
-设计见 [rewind-plan.md](rewind-plan.md)。每条开启新回合的用户消息都是一个回滚点；edit / write 改过的文件在消息发出前有检查点（`checkpoints.mode`，bash 改动只在下一回合重拍已跟踪文件时收进来）。
+设计见 [rewind-plan.md](../history/rewind-plan.md)。每条开启新回合的用户消息都是一个回滚点；edit / write 改过的文件在消息发出前有检查点（`checkpoints.mode`，bash 改动只在下一回合重拍已跟踪文件时收进来）。
 
 - **入口**：`/rewind`，或空闲且输入框为空时双击 Esc——第一次底部提示「再按 Esc 回滚」（1 秒消失），800 ms 内再按打开列表。输入框有字时双击 Esc 是清空（提示「再按 Esc 清空」），文字存进输入历史，↑ 取回。运行中 Esc 仍是中断；审批对话框、选择器打开时 Esc 归它们。
 - **中断即撤回**：运行中按 Esc 中断，若这一回合还没有任何回复文字或工具调用、输入框为空（`ui.restoreOnCancel`，缺省 true），自动撤回这条消息并把原文放回输入框，消息区一行「已撤回被中断的消息」。
@@ -319,7 +319,7 @@ CLI 子命令（`ama providers add` / `refresh` 的写入与 `--probe` 计费确
 - write：目标是否存在、现有行数与大小 → 新内容；覆盖本会话没读过的文件标黄。
 - edit：对原文干跑一遍，列出每处 −n/+m 行与总变化；匹配不到或不唯一时提前说明。
 
-预览按严重度着色（危险红、警告黄、其余暗色），只读、有上限：每个目录最多计 2000 项，整次预览 200 ms 预算，超出只给提示、不降低严重度；超过 2 MiB 的文件只报大小。预览失败不影响审批。line 模式在问句之前逐行打印同样的预览；RPC 客户端从 `permission_request.preview` 拿到它（[rpc.md](rpc.md)「审批」）。
+预览按严重度着色（危险红、警告黄、其余暗色），只读、有上限：每个目录最多计 2000 项，整次预览 200 ms 预算，超出只给提示、不降低严重度；超过 2 MiB 的文件只报大小。预览失败不影响审批。line 模式在问句之前逐行打印同样的预览；RPC 客户端从 `permission_request.preview` 拿到它（[rpc.md](../reference/rpc.md)「审批」）。
 
 ## Plan 审批
 
@@ -389,7 +389,7 @@ Plan 模式（Shift+Tab、`/permission plan`、`/plan <目标>`、`--permission-
 - 按了没进去时底部提示一行（3 秒）：输入框有字——「输入框有字；清空后再按 ↓ 进 Agent 栏」（每段草稿一次，光标在末行时；`↓` 照常下移）；栏关闭——「Agent 栏已关闭（ui.agentBar），用 /tasks」；没有任务——「还没有子 Agent 任务」。在用 `↑` `↓` 浏览输入历史时 `↓` 只翻历史。
 - `Ctrl+B` 不进栏，是「前台任务转后台」（见上）。想要原来的「`Ctrl+B` 进栏」可在 `keybindings.json` 写 `"app.agents.focus": ["down", "ctrl+b"]` 并把 `app.tasks.background` 改成别的键。
 - 栏里：`↑` `↓` 选（列出本会话全部任务，窗口跟着滚；在第一项再按 `↑` 回到输入框），Enter 打开子 Agent 视图（选中的任务有停靠的审批时随即弹出），`b` / `Ctrl+B` 把选中的前台任务转后台（不是前台运行中的给一行提示），`x` 停止选中的任务（第一次提示「再按 x 停止 t2」，1.5 秒内再按才停），Esc 回到输入框；其它字母回到输入框并把字填进去。末行是按键提示 `↑↓ 选择 · Enter 打开 · b 转后台 · x 停止 · Esc 返回`，窄屏丢掉 `b` / `x` 两项。
-- 嵌入宿主（有 profile）不再缺省关闭栏；宿主自己展示子任务、不要栏时在 profile 里写 `ui.agentBar: "off"`（见 [host-api.md](host-api.md)「嵌入 Armadra」）。关闭后栏不显示，`↓` 在有任务时提示改用 `/tasks`。
+- 嵌入宿主（有 profile）不再缺省关闭栏；宿主自己展示子任务、不要栏时在 profile 里写 `ui.agentBar: "off"`（见 [host-api.md](../reference/host-api.md)「嵌入 Armadra」）。关闭后栏不显示，`↓` 在有任务时提示改用 `/tasks`。
 
 ### 子 Agent 视图
 
@@ -409,7 +409,7 @@ t2 explore · 运行中 1m05s · 3 轮 · ↑12k ↓3.4k · Esc 返回 · /tasks
 
 - 正文实时跟随：ama 子 Agent 显示子会话的全部消息与工具调用（与消息区同样的渲染）；子会话句柄已被释放（保留上限 16 个）或会话是 resume 进来的，就只读加载子会话文件，任务再次运行时接上实时事件。外部 Agent（claude / codex / ACP）显示本进程内存里的实时输出（文本、思考、工具起止、回合、提示；最多 2000 条 / 1 MB，不落盘）；ama 重启后只剩一行说明「用原 CLI resume <会话 id> 查看全文」。
 - 输入框为空时：`↑` / PgUp 上翻（暂停跟随，底部提示「已暂停跟随 · End 继续」），`↓` / PgDn 下翻，End（暂停时也可按 `f`）回到跟随；`←` `→` 切到上一个 / 下一个任务；Esc 返回主界面。输入框有字时 Esc 先清空。
-- Enter 把输入发给这个子 Agent（会话里记为 `origin: "direct"` 的 user 消息，见 [session-format.md](session-format.md)）：ama 子 Agent 运行中 → 排到它本轮结束时送达；外部 Agent 运行中或任务还在排队 → 等本次运行结束后续聊；已结束 → 后台续聊（同 `task_ctl send`，完成后主会话照常收到 `<task-notification>`）。底部一行提示发送结果。父会话的模型不知道你直接和子 Agent 说过话，结果经结束通知自然带回。
+- Enter 把输入发给这个子 Agent（会话里记为 `origin: "direct"` 的 user 消息，见 [session-format.md](../reference/session-format.md)）：ama 子 Agent 运行中 → 排到它本轮结束时送达；外部 Agent 运行中或任务还在排队 → 等本次运行结束后续聊；已结束 → 后台续聊（同 `task_ctl send`，完成后主会话照常收到 `<task-notification>`）。底部一行提示发送结果。父会话的模型不知道你直接和子 Agent 说过话，结果经结束通知自然带回。
 - `Ctrl+X` 打断并发送给这个子 Agent：ama 子 Agent 运行中 → 中止它当前这一轮（工具按中断收尾）并立即以这条消息开新一轮，任务照常完成、照常通知主会话；外部 Agent 的驱动能中断单个回合（ACP `session/cancel`、Claude stream-json interrupt、Codex `turn/interrupt`）→ 中断后立即以它（连同之前排着的消息）开下一回合；不能（oneshot、宿主驱动）或任务还在并发池排队 → 退回排队并提示「不支持打断，已排队」；已结束 → 同 Enter 的后台续聊。`ui.enterWhileRunning: "interrupt"` 时与 Enter 互换。主会话不受影响。
 - 视图里 Esc 不中断任何东西：Esc 只是返回。停止子任务用 `/tasks stop <id>`，转后台用 `Ctrl+B` 或 `/tasks bg [id]`——在视图输入框里也能用（视图里只认这两条命令）。
 - 正在看的任务等审批时标题显示「等待审批」，审批框照常弹在视图上面（带 `[task:<类型>]` 来源）；它的审批停靠在栏里时，打开视图即弹出。
@@ -467,7 +467,7 @@ t2 explore · 运行中 1m05s · 3 轮 · ↑12k ↓3.4k · Esc 返回 · /tasks
 - 保温与权限分类等辅助请求收在末尾「辅助请求 N 次」一组，缺省折叠。
 - line 模式（`--ui line`、管道）里 `/trace [任务 id]` 打印同一棵树的文本（全部展开、不画条形）。
 
-计时来自会话文件里的 `custom{customType:"ama.trace"}` 条目（[session-format.md](session-format.md)），只有 id、时间与计数；
+计时来自会话文件里的 `custom{customType:"ama.trace"}` 条目（[session-format.md](../reference/session-format.md)），只有 id、时间与计数；
 提示、参数、结果的预览从会话条目按需读取，不进轨迹本身。
 
 ## Memory