@armadra/agent 0.8.0 → 0.8.1

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

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.8.1",
   "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"
 }