@armadra/agent 0.7.6 → 0.8.1

package/dist/session/migrate.d.ts

@@ -8,7 +8,7 @@
  * - [W3-C1b] `leaf` 行（`/tree` 位置，第三波 A7）不是条目：不进 entries；最后一条 leaf 行若在
  *   最后一条条目之后，作为 `leafId` 返回（之后又追加了条目则作废）。id 须为字符串或 null。
  * 将来格式升级时在这里加「旧版本 → 当前」的内存迁移（文件只追加，不回写）；`list.ts` 不经本函数、
- * 自己按 v1 规则流式统计，升级格式时要同时改它（docs/memory-plan.md R6）。
+ * 自己按 v1 规则流式统计，升级格式时要同时改它（docs/history/memory-plan.md R6）。
  */
 import type { SessionEntry, SessionHeader, SessionLine } from "./types.js";
 export interface MigratedSession {

package/dist/session/migrate.js

@@ -8,7 +8,7 @@
  * - [W3-C1b] `leaf` 行（`/tree` 位置，第三波 A7）不是条目：不进 entries；最后一条 leaf 行若在
  *   最后一条条目之后，作为 `leafId` 返回（之后又追加了条目则作废）。id 须为字符串或 null。
  * 将来格式升级时在这里加「旧版本 → 当前」的内存迁移（文件只追加，不回写）；`list.ts` 不经本函数、
- * 自己按 v1 规则流式统计，升级格式时要同时改它（docs/memory-plan.md R6）。
+ * 自己按 v1 规则流式统计，升级格式时要同时改它（docs/history/memory-plan.md R6）。
  */
 import { AmaError } from "../errors.js";
 import { SESSION_FORMAT_VERSION } from "./types.js";

package/dist/session/store.d.ts

@@ -30,7 +30,7 @@ export interface ReadResult {
 export declare function isBlankLine(line: Buffer): boolean;
 /**
  * 读并解析 JSONL。`repair: true` 时把末尾半行从文件里截掉（只截最后一行，且只在它无法解析时）。
- * 按块逐行读（line-reader.ts，docs/memory-plan.md §2.4）：不生成全文字符串与 split 数组。
+ * 按块逐行读（line-reader.ts，docs/history/memory-plan.md §2.4）：不生成全文字符串与 split 数组。
  */
 export declare function readSessionLines(file: string, options?: {
     repair?: boolean;

package/dist/session/store.js

@@ -45,7 +45,7 @@ export function isBlankLine(line) {
 }
 /**
  * 读并解析 JSONL。`repair: true` 时把末尾半行从文件里截掉（只截最后一行，且只在它无法解析时）。
- * 按块逐行读（line-reader.ts，docs/memory-plan.md §2.4）：不生成全文字符串与 split 数组。
+ * 按块逐行读（line-reader.ts，docs/history/memory-plan.md §2.4）：不生成全文字符串与 split 数组。
  */
 export function readSessionLines(file, options = {}) {
     const lines = [];

package/dist/skills/builtin.js

@@ -14,7 +14,7 @@ import { dirname, join } from "node:path";
 export const BUILTIN_SKILLS_DIR = "builtin";
 const AMA_DOCS_BODY = `# ama quick reference
 
-ama is the coding agent running this session. Docs: https://github.com/Owlbay/armadra-agent (README.md, docs/).
+ama is the coding agent running this session. Docs: https://github.com/AMA-Link/armadra-agent (README.md, docs/).
 
 ## Files
 - User config dir \`~/.config/ama/\` (\`AMA_CONFIG_DIR\`; Windows \`%APPDATA%\\ama\`): \`config.json\`, \`auth.json\` (keys, 0600), \`hooks.json\`, \`keybindings.json\`, \`trust.json\`, \`AGENTS.md\`, \`skills/\`, \`prompts/\`.
@@ -93,7 +93,7 @@ export async function withBuiltinSkills(skills, dataDir, builtins = BUILTIN_SKIL
             await ensureFile(location, builtinSkillText(builtin));
         }
         catch (error) {
-            // 与 skills/ 其它加载告警一样固定英文（模型侧模块不 import i18n，见 docs/i18n.md）
+            // 与 skills/ 其它加载告警一样固定英文（模型侧模块不 import i18n，见 docs/guides/i18n.md）
             warnings.push(`built-in skill ${builtin.name} could not be written: ${error.message}`);
             continue;
         }

package/dist/tools/background-jobs.d.ts

@@ -1,5 +1,5 @@
 /**
- * 后台命令（docs/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
+ * 后台命令（docs/history/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
  *
  * - `start`：调用方（bash.ts）给出 `spawn(stdout)`——**进程只在 bash.ts 的 `spawnShell` 里创建**，
  *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不

package/dist/tools/background-jobs.js

@@ -1,5 +1,5 @@
 /**
- * 后台命令（docs/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
+ * 后台命令（docs/history/wave5-plan.md §8.3 H6，D29：不加新工具，`bash{background}` + `bash{job, action}`）。[W5-H2]
  *
  * - `start`：调用方（bash.ts）给出 `spawn(stdout)`——**进程只在 bash.ts 的 `spawnShell` 里创建**，
  *   这里只拿到 ChildProcess；stdout / stderr 直接写进 `outputPath`（文件描述符交给子进程，ama 退出也不

package/dist/tools/clipboard-image.d.ts

@@ -1,5 +1,5 @@
 /**
- * 剪贴板图片（docs/wave5-plan.md §4、D12）。[W5-I] 界面接线（`Ctrl+V`、`/paste`）归 W5-U。
+ * 剪贴板图片（docs/history/wave5-plan.md §4、D12）。[W5-I] 界面接线（`Ctrl+V`、`/paste`）归 W5-U。
  *
  * 零依赖读不了剪贴板位图，按平台依次调系统命令，成功写 `<dataDir>/clipboard/<时间戳>.png` 并返回
  * 路径（编辑器插入 `@<路径>`，之后走 loadImageFile）；没有工具或剪贴板里没有图返回 undefined：

package/dist/tools/clipboard-image.js

@@ -1,5 +1,5 @@
 /**
- * 剪贴板图片（docs/wave5-plan.md §4、D12）。[W5-I] 界面接线（`Ctrl+V`、`/paste`）归 W5-U。
+ * 剪贴板图片（docs/history/wave5-plan.md §4、D12）。[W5-I] 界面接线（`Ctrl+V`、`/paste`）归 W5-U。
  *
  * 零依赖读不了剪贴板位图，按平台依次调系统命令，成功写 `<dataDir>/clipboard/<时间戳>.png` 并返回
  * 路径（编辑器插入 `@<路径>`，之后走 loadImageFile）；没有工具或剪贴板里没有图返回 undefined：

package/dist/tools/edit.d.ts

@@ -38,7 +38,7 @@ export declare function planEdits(content: string, edits: readonly EditOp[], rep
 export declare function unifiedDiff(oldText: string, newText: string, path: string, context?: number): string;
 /** 改前 / 改后全文（[ACP-C] D6）：任一侧超过 {@link FILE_CHANGE_TEXT_LIMIT} 返回 undefined。 */
 export declare function fileChangeOf(path: string, oldText: string | null, newText: string, firstChangedLine?: number): FileChange | undefined;
-/** 检查点：写前备份（docs/rewind-plan.md §2）；钩子按约定不抛，这里再兜一层，不让编辑失败。 */
+/** 检查点：写前备份（docs/history/rewind-plan.md §2）；钩子按约定不抛，这里再兜一层，不让编辑失败。 */
 export declare function beforeWrite(ctx: ToolContext, abs: string): Promise<void>;
 export declare function executeEdit(input: EditInput, ctx: ToolContext): Promise<ToolResult>;
 export declare function createEditTool(): ToolDefinition<EditInput>;

package/dist/tools/edit.js

@@ -177,7 +177,7 @@ export function fileChangeOf(path, oldText, newText, firstChangedLine) {
 // ---------------------------------------------------------------------------
 // 工具
 // ---------------------------------------------------------------------------
-/** 检查点：写前备份（docs/rewind-plan.md §2）；钩子按约定不抛，这里再兜一层，不让编辑失败。 */
+/** 检查点：写前备份（docs/history/rewind-plan.md §2）；钩子按约定不抛，这里再兜一层，不让编辑失败。 */
 export async function beforeWrite(ctx, abs) {
     if (ctx.checkpoint === undefined)
         return;

package/dist/tools/grep.d.ts

@@ -6,7 +6,7 @@
  *   不相邻的组之间 `--`；匹配行截 500 字符；
  * - 匹配数到 limit（缺省 100）即停并提示；整体输出再按 50 KB 头截断。
  * - [S-A] `filesOnly`：只列命中文件（去重、按路径排序，每个文件命中一行即停），limit 按文件数计；
- *   给模型在大仓库里先缩范围（docs/search-plan.md §4.2）。
+ *   给模型在大仓库里先缩范围（docs/design/search-plan.md §4.2）。
  */
 import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
 export interface GrepInput {

package/dist/tools/grep.js

@@ -6,7 +6,7 @@
  *   不相邻的组之间 `--`；匹配行截 500 字符；
  * - 匹配数到 limit（缺省 100）即停并提示；整体输出再按 50 KB 头截断。
  * - [S-A] `filesOnly`：只列命中文件（去重、按路径排序，每个文件命中一行即停），limit 按文件数计；
- *   给模型在大仓库里先缩范围（docs/search-plan.md §4.2）。
+ *   给模型在大仓库里先缩范围（docs/design/search-plan.md §4.2）。
  */
 import { readFile, stat } from "node:fs/promises";
 import { displayPath, resolvePath } from "./paths.js";

package/dist/tools/image-resize.d.ts

@@ -1,5 +1,5 @@
 /**
- * 可选的图片缩放（docs/wave5-plan.md §4、D12）。[W5-I]
+ * 可选的图片缩放（docs/history/wave5-plan.md §4、D12）。[W5-I]
  *
  * 零依赖不能解码像素，只能调系统工具：macOS 依次试 `sips`、`magick`、`convert`；Linux 试
  * `magick`、`convert`；Windows 只试 `magick`（`convert.exe` 是系统的磁盘转换工具）。都没有就返回

package/dist/tools/image-resize.js

@@ -1,5 +1,5 @@
 /**
- * 可选的图片缩放（docs/wave5-plan.md §4、D12）。[W5-I]
+ * 可选的图片缩放（docs/history/wave5-plan.md §4、D12）。[W5-I]
  *
  * 零依赖不能解码像素，只能调系统工具：macOS 依次试 `sips`、`magick`、`convert`；Linux 试
  * `magick`、`convert`；Windows 只试 `magick`（`convert.exe` 是系统的磁盘转换工具）。都没有就返回

package/dist/tools/read-lines.d.ts

@@ -1,5 +1,5 @@
 /**
- * `read` 大文件的字节窗口读取（docs/memory-plan.md D1、§2.1）。[M-E]
+ * `read` 大文件的字节窗口读取（docs/history/memory-plan.md D1、§2.1）。[M-E]
  *
  * fd + 64 KiB 块顺序扫描，只解码 `[offset, offset + limit)` 内且累计不超过 `maxBytes`（多收一行）
  * 的行，其余行只计数；口径与小文件路径（`splitBom` + `normalizeToLF` + 去末尾一个换行再 `split`）

package/dist/tools/read-lines.js

@@ -1,5 +1,5 @@
 /**
- * `read` 大文件的字节窗口读取（docs/memory-plan.md D1、§2.1）。[M-E]
+ * `read` 大文件的字节窗口读取（docs/history/memory-plan.md D1、§2.1）。[M-E]
  *
  * fd + 64 KiB 块顺序扫描，只解码 `[offset, offset + limit)` 内且累计不超过 `maxBytes`（多收一行）
  * 的行，其余行只计数；口径与小文件路径（`splitBom` + `normalizeToLF` + 去末尾一个换行再 `split`）

package/dist/tools/read.d.ts

@@ -26,7 +26,7 @@ export interface ReadToolOptions {
 }
 export declare function isBinary(buf: Buffer): boolean;
 /**
- * [S-A] read 收到目录时的下一步提示：只指向模型当前真能调用的工具（docs/search-plan.md §4.2）。
+ * [S-A] read 收到目录时的下一步提示：只指向模型当前真能调用的工具（docs/design/search-plan.md §4.2）。
  * 活动集未知（宿主自建上下文）时沿用旧文案。
  */
 export declare function directoryHint(shown: string, ctx: Pick<ToolContext, "activeTools">): string;

package/dist/tools/read.js

@@ -29,7 +29,7 @@ function error(message) {
     return { content: message, isError: true };
 }
 /**
- * [S-A] read 收到目录时的下一步提示：只指向模型当前真能调用的工具（docs/search-plan.md §4.2）。
+ * [S-A] read 收到目录时的下一步提示：只指向模型当前真能调用的工具（docs/design/search-plan.md §4.2）。
  * 活动集未知（宿主自建上下文）时沿用旧文案。
  */
 export function directoryHint(shown, ctx) {

package/dist/tools/task-ctl.d.ts

@@ -1,6 +1,6 @@
 /**
  * `task_ctl` 工具：查看 / 等待 / 停止后台子 Agent 任务，读输出，向任务追加消息
- * （docs/wave5-plan.md §7.3，D13）。[W5-C0 桩 → W5-G]
+ * （docs/history/wave5-plan.md §7.3，D13）。[W5-C0 桩 → W5-G]
  *
  * - 与 `task` 同进退（预设、`--tools`、`disable("task")`，见 registry.ts 的 `TOOL_COMPANIONS`）；
  * - 控制面按会话 id 取（agents/task-control.ts，注册表登记）；子会话里（depth ≥ 1）不可用——工具表

package/dist/tools/task-ctl.js

@@ -1,6 +1,6 @@
 /**
  * `task_ctl` 工具：查看 / 等待 / 停止后台子 Agent 任务，读输出，向任务追加消息
- * （docs/wave5-plan.md §7.3，D13）。[W5-C0 桩 → W5-G]
+ * （docs/history/wave5-plan.md §7.3，D13）。[W5-C0 桩 → W5-G]
  *
  * - 与 `task` 同进退（预设、`--tools`、`disable("task")`，见 registry.ts 的 `TOOL_COMPANIONS`）；
  * - 控制面按会话 id 取（agents/task-control.ts，注册表登记）；子会话里（depth ≥ 1）不可用——工具表

package/dist/tools/task.d.ts

@@ -1,5 +1,5 @@
 /**
- * `task` 工具：子 Agent 的统一入口（设计 §5.2、D14；第五波 docs/wave5-plan.md §7.3，D13、D23）。
+ * `task` 工具：子 Agent 的统一入口（设计 §5.2、D14；第五波 docs/history/wave5-plan.md §7.3，D13、D23）。
  * [B3 → W5-G]
  *
  * - `agent`：子 Agent 类型（内置 general / explore / plan、`.ama/agents/*.md`）或外部 Agent；缺省
@@ -55,7 +55,7 @@ export interface TaskToolOptions {
 export declare const TASK_CONTEXT_LEAD: string;
 /** 缺省前台（`-p`、`subagents.background: never`）时的描述。 */
 export declare const FOREGROUND_DESCRIPTION: string;
-/** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/agents-concurrency-plan.md §2.6）时的描述。 */
+/** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/history/agents-concurrency-plan.md §2.6）时的描述。 */
 export declare const BACKGROUND_DESCRIPTION: string;
 /** 描述里类型清单的标题（清单本身另有 400 token 预算，见 agents/catalog.ts）。 */
 export declare const TASK_AGENTS_HEADING = "\nAgents:\n";

package/dist/tools/task.js

@@ -1,5 +1,5 @@
 /**
- * `task` 工具：子 Agent 的统一入口（设计 §5.2、D14；第五波 docs/wave5-plan.md §7.3，D13、D23）。
+ * `task` 工具：子 Agent 的统一入口（设计 §5.2、D14；第五波 docs/history/wave5-plan.md §7.3，D13、D23）。
  * [B3 → W5-G]
  *
  * - `agent`：子 Agent 类型（内置 general / explore / plan、`.ama/agents/*.md`）或外部 Agent；缺省
@@ -64,7 +64,7 @@ export const TASK_CONTEXT_LEAD = "Delegate to a sub-agent (fresh context: give f
 /** 缺省前台（`-p`、`subagents.background: never`）时的描述。 */
 export const FOREGROUND_DESCRIPTION = `${TASK_CONTEXT_LEAD} Returns its final report. Parallel in one reply; writers use isolation ` +
     "worktree. background: returns a taskId (see task_ctl); taskId: continue it.";
-/** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/agents-concurrency-plan.md §2.6）时的描述。 */
+/** [W7-B1] 缺省后台（交互 / RPC / ACP，docs/history/agents-concurrency-plan.md §2.6）时的描述。 */
 export const BACKGROUND_DESCRIPTION = `${TASK_CONTEXT_LEAD} Runs in the background by default: returns a taskId; a ` +
     "<task-notification> follows; keep working. background:false waits for the result. " +
     "taskId: continue it. Parallel in one reply; writers use isolation worktree.";

package/dist/tools/types.d.ts

@@ -12,7 +12,7 @@
  * - `defineTool()` 是恒等函数，只为推断 `I`；放在契约文件里供 SDK 再导出。
  * - `ToolRegistryApi` 是 Runtime 需要的最小接口，B3 的 `ToolRegistry` 实现它。
  * - （W3-C0）`SubagentResult.cache` 可选：子会话的命中率与重计费 token。
- * - （W5-C0）第五波（docs/wave5-plan.md §7.3–§7.6、§8.2 C4、§8.3 H1）：`annotations.pollable /
+ * - （W5-C0）第五波（docs/history/wave5-plan.md §7.3–§7.6、§8.2 C4、§8.3 H1）：`annotations.pollable /
  *   keepInContext`；`SubagentRequest` 加 `agent / background / taskId / isolation / budgetUsd`；
  *   `SubagentResult` 加 `taskId / status / outputFile / sessionRef`（契约要求向后兼容，全部可选）；
  *   统一入口 `SubagentRunner / RunnerHandle / SubagentEvent`（ama 子会话、外部 CLI、宿主 runner）；
@@ -158,7 +158,7 @@ export type SubagentEvent = {
     turn: number;
 }
 /**
- * [W6-C0] 外部 Agent 一个回合结束时的骨架（docs/wave6-plan.md §2.2）：任务注册表写成父会话的
+ * [W6-C0] 外部 Agent 一个回合结束时的骨架（docs/history/wave6-plan.md §2.2）：任务注册表写成父会话的
  * `ama.trace{kind:"external_turn"}`。只有种类、状态、时间与计数——不含工具标题、命令行、路径。
  */
  | {
@@ -281,7 +281,7 @@ export interface ToolContext {
         /** 活动分支上最近一条该类型 custom 条目的 data。 */
         lastCustom(customType: string): unknown;
     };
-    /** 检查点（docs/rewind-plan.md §2）：edit / write 写文件前后调用；未启用时为 undefined。 */
+    /** 检查点（docs/history/rewind-plan.md §2）：edit / write 写文件前后调用；未启用时为 undefined。 */
     readonly checkpoint?: CheckpointHooks;
     /** 仅 depth 0 且 task 可用时存在。 */
     readonly spawnSubagent?: (request: SubagentRequest) => Promise<SubagentResult>;

package/dist/tools/types.js

@@ -12,7 +12,7 @@
  * - `defineTool()` 是恒等函数，只为推断 `I`；放在契约文件里供 SDK 再导出。
  * - `ToolRegistryApi` 是 Runtime 需要的最小接口，B3 的 `ToolRegistry` 实现它。
  * - （W3-C0）`SubagentResult.cache` 可选：子会话的命中率与重计费 token。
- * - （W5-C0）第五波（docs/wave5-plan.md §7.3–§7.6、§8.2 C4、§8.3 H1）：`annotations.pollable /
+ * - （W5-C0）第五波（docs/history/wave5-plan.md §7.3–§7.6、§8.2 C4、§8.3 H1）：`annotations.pollable /
  *   keepInContext`；`SubagentRequest` 加 `agent / background / taskId / isolation / budgetUsd`；
  *   `SubagentResult` 加 `taskId / status / outputFile / sessionRef`（契约要求向后兼容，全部可选）；
  *   统一入口 `SubagentRunner / RunnerHandle / SubagentEvent`（ama 子会话、外部 CLI、宿主 runner）；

package/dist/trace/build.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹构建器（docs/wave6-plan.md §2.3、D6）。[W6-T1]
+ * 轨迹构建器（docs/history/wave6-plan.md §2.3、D6）。[W6-T1]
  *
  * `buildTrace(input, opts)` 把会话条目重建成 `Trace`（Turn → Step → Tool → Subcall / Subagent）：
  * TUI `/trace`、`ama sessions trace`、RPC `get_trace` 三方共用同一棵树。

package/dist/trace/build.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹构建器（docs/wave6-plan.md §2.3、D6）。[W6-T1]
+ * 轨迹构建器（docs/history/wave6-plan.md §2.3、D6）。[W6-T1]
  *
  * `buildTrace(input, opts)` 把会话条目重建成 `Trace`（Turn → Step → Tool → Subcall / Subagent）：
  * TUI `/trace`、`ama sessions trace`、RPC `get_trace` 三方共用同一棵树。

package/dist/trace/detail.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹节点的正文预览与详情卡片（docs/wave6-plan.md §2.4：Enter 详情——概要 / 用量与缓存 / 参数与结果预览）。
+ * 轨迹节点的正文预览与详情卡片（docs/history/wave6-plan.md §2.4：Enter 详情——概要 / 用量与缓存 / 参数与结果预览）。
  * [W6-T1]
  *
  * 轨迹树不含正文；这里按节点的 `entryIds` 回会话条目取：回合 → 用户提示，请求 → 助手文字，工具 → 参数

package/dist/trace/detail.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹节点的正文预览与详情卡片（docs/wave6-plan.md §2.4：Enter 详情——概要 / 用量与缓存 / 参数与结果预览）。
+ * 轨迹节点的正文预览与详情卡片（docs/history/wave6-plan.md §2.4：Enter 详情——概要 / 用量与缓存 / 参数与结果预览）。
  * [W6-T1]
  *
  * 轨迹树不含正文；这里按节点的 `entryIds` 回会话条目取：回合 → 用户提示，请求 → 助手文字，工具 → 参数

package/dist/trace/flatten.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹树扁平化（docs/wave6-plan.md §2.4）。[W6-T1]
+ * 轨迹树扁平化（docs/history/wave6-plan.md §2.4）。[W6-T1]
  *
  * 把 `Trace` 按展开状态摊成行数组（列表模型），TUI 只渲染可见窗口、line 模式整表输出。
  * - 行 key 是从根开始的路径（`t:<turnId>/s:<stepId>/x:<toolCallId>/a:<taskId>/…`），刷新后仍稳定，

package/dist/trace/flatten.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹树扁平化（docs/wave6-plan.md §2.4）。[W6-T1]
+ * 轨迹树扁平化（docs/history/wave6-plan.md §2.4）。[W6-T1]
  *
  * 把 `Trace` 按展开状态摊成行数组（列表模型），TUI 只渲染可见窗口、line 模式整表输出。
  * - 行 key 是从根开始的路径（`t:<turnId>/s:<stepId>/x:<toolCallId>/a:<taskId>/…`），刷新后仍稳定，

package/dist/trace/format.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹行的文本格式（docs/wave6-plan.md §2.4）。[W6-T1]
+ * 轨迹行的文本格式（docs/history/wave6-plan.md §2.4）。[W6-T1]
  *
  * 一行：`光标 缩进 折叠符 状态 标签   耗时  ▕████▒▒▒░░▏  ↑in ↓out  缓存%`
  * - 条形是所在回合的相对时间轴：`▒` = TTFT、`█` = 解码、`░` = 工具、`│` = 进行中节点的起点（不编造时长）；

package/dist/trace/format.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹行的文本格式（docs/wave6-plan.md §2.4）。[W6-T1]
+ * 轨迹行的文本格式（docs/history/wave6-plan.md §2.4）。[W6-T1]
  *
  * 一行：`光标 缩进 折叠符 状态 标签   耗时  ▕████▒▒▒░░▏  ↑in ↓out  缓存%`
  * - 条形是所在回合的相对时间轴：`▒` = TTFT、`█` = 解码、`░` = 工具、`│` = 进行中节点的起点（不编造时长）；

package/dist/trace/html-template.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹 HTML 的页面骨架、样式与脚本（docs/wave6-plan.md §2.5）。[W6-T2]
+ * 轨迹 HTML 的页面骨架、样式与脚本（docs/history/wave6-plan.md §2.5）。[W6-T2]
  *
  * 全部静态：页面只插入三样东西——`lang`、转义过的 `<title>`、已做脚本安全转义的 JSON（`html.ts`）。
  * 脚本只用 `textContent` / `createElement` 写 DOM，不用 `innerHTML`；没有任何外部资源（CSP 见 `CSP`）。

package/dist/trace/html-template.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹 HTML 的页面骨架、样式与脚本（docs/wave6-plan.md §2.5）。[W6-T2]
+ * 轨迹 HTML 的页面骨架、样式与脚本（docs/history/wave6-plan.md §2.5）。[W6-T2]
  *
  * 全部静态：页面只插入三样东西——`lang`、转义过的 `<title>`、已做脚本安全转义的 JSON（`html.ts`）。
  * 脚本只用 `textContent` / `createElement` 写 DOM，不用 `innerHTML`；没有任何外部资源（CSP 见 `CSP`）。

package/dist/trace/html.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹 HTML 导出：`ama sessions trace --html`（docs/wave6-plan.md §2.5、D7）。[W6-T2]
+ * 轨迹 HTML 导出：`ama sessions trace --html`（docs/history/wave6-plan.md §2.5、D7）。[W6-T2]
  *
  * 产物是**单文件、零依赖**的页面：样式与脚本内联（`html-template.ts`），数据放
  * `<script type="application/json">`，`<meta>` CSP 禁止一切外联。页面在浏览器里只用 `textContent` 写字，

package/dist/trace/html.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹 HTML 导出：`ama sessions trace --html`（docs/wave6-plan.md §2.5、D7）。[W6-T2]
+ * 轨迹 HTML 导出：`ama sessions trace --html`（docs/history/wave6-plan.md §2.5、D7）。[W6-T2]
  *
  * 产物是**单文件、零依赖**的页面：样式与脚本内联（`html-template.ts`），数据放
  * `<script type="application/json">`，`<meta>` CSP 禁止一切外联。页面在浏览器里只用 `textContent` 写字，

package/dist/trace/query-session.d.ts

@@ -1,5 +1,5 @@
 /**
- * 运行中会话的轨迹查询：RPC `get_trace` 与 SDK `session.trace()`（docs/wave6-plan.md §2.6、D29）。[W6-T2]
+ * 运行中会话的轨迹查询：RPC `get_trace` 与 SDK `session.trace()`（docs/history/wave6-plan.md §2.6、D29）。[W6-T2]
  *
  * 构建器输入取自会话（`traceInputOf`）；运行中时叠一层 `{ running: true }`（没有结果的工具算 running 而不是
  * interrupted，不编造时长）；子会话读取按会话缓存（mtime + 大小没变就不重读）。

package/dist/trace/query-session.js

@@ -1,5 +1,5 @@
 /**
- * 运行中会话的轨迹查询：RPC `get_trace` 与 SDK `session.trace()`（docs/wave6-plan.md §2.6、D29）。[W6-T2]
+ * 运行中会话的轨迹查询：RPC `get_trace` 与 SDK `session.trace()`（docs/history/wave6-plan.md §2.6、D29）。[W6-T2]
  *
  * 构建器输入取自会话（`traceInputOf`）；运行中时叠一层 `{ running: true }`（没有结果的工具算 running 而不是
  * interrupted，不编造时长）；子会话读取按会话缓存（mtime + 大小没变就不重读）。

package/dist/trace/query.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹查询：RPC `get_trace`、SDK `session.trace()`、`ama sessions trace --json` 共用（docs/wave6-plan.md §2.6）。
+ * 轨迹查询：RPC `get_trace`、SDK `session.trace()`、`ama sessions trace --json` 共用（docs/history/wave6-plan.md §2.6）。
  * [W6-T2]
  *
  * - **窗口**：在 `Trace.turns` 上切。缺省尾部 `turnLimit`（50，上限 500）个回合；`before`（回合 id）向前翻页；

package/dist/trace/query.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹查询：RPC `get_trace`、SDK `session.trace()`、`ama sessions trace --json` 共用（docs/wave6-plan.md §2.6）。
+ * 轨迹查询：RPC `get_trace`、SDK `session.trace()`、`ama sessions trace --json` 共用（docs/history/wave6-plan.md §2.6）。
  * [W6-T2]
  *
  * - **窗口**：在 `Trace.turns` 上切。缺省尾部 `turnLimit`（50，上限 500）个回合；`before`（回合 id）向前翻页；

package/dist/trace/types.d.ts

@@ -1,5 +1,5 @@
 /**
- * 轨迹（docs/wave6-plan.md §2.1、§2.2、D5、D6）。[W6-C0] 纯类型，经 `@armadra/agent` 导出。
+ * 轨迹（docs/history/wave6-plan.md §2.1、§2.2、D5、D6）。[W6-C0] 纯类型，经 `@armadra/agent` 导出。
  *
  * 两部分：
  * - **持久化**：`custom{customType:"ama.trace"}` 条目的 `data`（`TraceEntryData`），由

package/dist/trace/types.js

@@ -1,5 +1,5 @@
 /**
- * 轨迹（docs/wave6-plan.md §2.1、§2.2、D5、D6）。[W6-C0] 纯类型，经 `@armadra/agent` 导出。
+ * 轨迹（docs/history/wave6-plan.md §2.1、§2.2、D5、D6）。[W6-C0] 纯类型，经 `@armadra/agent` 导出。
  *
  * 两部分：
  * - **持久化**：`custom{customType:"ama.trace"}` 条目的 `data`（`TraceEntryData`），由

package/dist/tui/components/settings-list.d.ts

@@ -1,5 +1,5 @@
 /**
- * Grouped settings list (docs/wave6-plan.md §6.3). [W6-S]
+ * Grouped settings list (docs/history/wave6-plan.md §6.3). [W6-S]
  *
  * Rows `› label  value  tag  note` under muted group headers; the selected row uses the prompt glyph,
  * accent + bold and the `selection` background (same look as ChoiceDialog). A query filters rows by id,

package/dist/tui/components/settings-list.js

@@ -1,5 +1,5 @@
 /**
- * Grouped settings list (docs/wave6-plan.md §6.3). [W6-S]
+ * Grouped settings list (docs/history/wave6-plan.md §6.3). [W6-S]
  *
  * Rows `› label  value  tag  note` under muted group headers; the selected row uses the prompt glyph,
  * accent + bold and the `selection` background (same look as ChoiceDialog). A query filters rows by id,

package/docs/README.md

@@ -0,0 +1,85 @@
+# 文档索引
+
+[English](en/README.md) · 简体中文
+
+本文件是 `docs/` 的入口，新增文档登记在这里。仓库内的相对链接与源码注释里的 `docs/…md` 路径由
+`pnpm check:docs`（`scripts/check-doc-links.mjs`）校验。
+
+| 目录          | 内容                                                          |
+| ------------- | ------------------------------------------------------------- |
+| `guides/`     | 使用说明与现行行为，与代码同步维护                            |
+| `reference/`  | 协议与文件格式，形状改动必须同步（见 `AGENTS.md`「协议面」）  |
+| `design/`     | 目标设计与视觉规范；首段写明状态，现状以代码与 `guides/` 为准 |
+| `history/`    | 已完成的实施计划与审计，只用于追溯，不作为实施要求            |
+| `research/`   | 调研报告，只用于追溯                                          |
+| `benchmarks/` | 实测记录与原始数据                                            |
+| `en/`         | 英文译本，按同样的分层放；中英不一致时以中文版为准            |
+| `assets/`     | README 用的字标等图片                                         |
+
+## guides/ 使用与现状
+
+| 文档                                      | 内容                                                                        |
+| ----------------------------------------- | --------------------------------------------------------------------------- |
+| [终端界面](guides/tui.md)                 | 布局、状态栏、按键、命令、回滚、审批、Agent 栏、轨迹、`/config`；组件库 API |
+| [供应商与模型](guides/providers.md)       | 内置供应商、渠道、API Key、ChatGPT 登录、中转、models.dev、图像、缓存       |
+| [权限](guides/permissions.md)             | 六种模式、判定顺序、`auto` 的三层判定                                       |
+| [Plan 模式](guides/plan.md)               | 只读调研、计划格式、审批入口与持久化                                        |
+| [会话](guides/sessions.md)                | 统计、检索、`--from` 复用、导出、轨迹、检查点                               |
+| [子 Agent 与外部 Agent](guides/agents.md) | `task` / `task_ctl`、fork、worktree 隔离、外部 Agent 驱动与能力矩阵         |
+| [记忆](guides/memory.md)                  | 跨会话笔记，缺省关闭                                                        |
+| [命令式 Hook](guides/hooks.md)            | `hooks.json` 的事件、退出码与 stdout JSON                                   |
+| [codemode](guides/codemode.md)            | 模型写脚本批量调用工具，子进程与权限                                        |
+| [操作系统级沙箱](guides/sandbox.md)       | macOS `sandbox-exec` 与 Linux bubblewrap，codemode 与 bash 接入             |
+| [界面语言](guides/i18n.md)                | 中英双语的选择规则与开发约定                                                |
+
+## reference/ 协议与格式
+
+| 文档                                        | 内容                                                     |
+| ------------------------------------------- | -------------------------------------------------------- |
+| [RPC 协议](reference/rpc.md)                | `ama --mode rpc` 的 stdio JSONL 命令、响应与事件         |
+| [ACP](reference/acp.md)                     | `ama --mode acp` 服务端、登录方法、偏差，以及 ACP 客户端 |
+| [宿主适配器 API](reference/host-api.md)     | `@armadra/agent/host`：注册工具、审批、注入消息、状态    |
+| [会话文件格式](reference/session-format.md) | JSONL 条目树、头、条目类型与版本                         |
+
+## design/ 目标设计
+
+| 文档                                     | 状态与内容                                                                 |
+| ---------------------------------------- | -------------------------------------------------------------------------- |
+| [总体设计](design/design.md)             | 架构、工程约定、缓存保证与决定表；硬约束仍以此为准，细节现状见 `guides/`   |
+| [终端界面视觉规范](design/tui-design.md) | 主题、逐屏样稿与交互细节；已按此实现，作为界面改动的规范                   |
+| [检索与网络搜索](design/search-plan.md)  | 只实施了本地检索增强；`web_fetch`、`web_search` 与引用呈现保留为将来的设计 |
+| [本地扩展](design/extensions.md)         | 设计草案，尚未实现                                                         |
+
+## history/ 已完成的计划与审计
+
+| 文档                                                       | 内容                                                         |
+| ---------------------------------------------------------- | ------------------------------------------------------------ |
+| [第二、三波实施设计](history/implementation-plan.md)       | 组装根、RPC / SDK、交互模式、codemode 各批次                 |
+| [第三波计划](history/wave3-plan.md)                        | 缓存设计与验收、其余批次编排                                 |
+| [第五波计划](history/wave5-plan.md)                        | 状态栏、模型元数据、渠道、外部 Agent、Plan、子 Agent、压缩   |
+| [第六波计划](history/wave6-plan.md)                        | Agent 栏、轨迹、记忆、ChatGPT 登录、双语、`/config`          |
+| [检查点与回滚](history/rewind-plan.md)                     | 检查点、回滚与影子 git                                       |
+| [ACP 补全](history/acp-plan.md)                            | 对照 ACP v1 schema 的补全                                    |
+| [Agent 切换与并行交流](history/agents-concurrency-plan.md) | Agent 栏进入方式、后台审批停靠                               |
+| [内存占用优化](history/memory-plan.md)                     | read 流式、ACP 释放、图片驻留                                |
+| [模型调用效率](history/model-efficiency-plan.md)           | 缓存、用量、重试与元数据                                     |
+| [未关闭 Issue 设计与分批](history/open-issues-plan.md)     | #149–#156、#183：fork 缺省、子会话防串台、取样、上限持久化等 |
+| [内存优化遗留项](history/memory-residue-plan.md)           | #165–#173：常驻会话、通知回合、图片释放、读窗口等            |
+| [缺口与默认值审计](history/gap-audit-2026-10.md)           | 2026-10-02 的只读审计                                        |
+
+## research/ 与 benchmarks/
+
+- [调研报告](research/README.md)：第五波 R1–R5、第六波 R6–R10、ACP 差距审计、模型调用效率与内存占用审计。
+- 实测记录：
+  - [外部 Agent 驱动实测](benchmarks/external-agents-2026-10.md)
+  - [模型调用效率实测](benchmarks/efficiency-2026-10.md)
+  - [内存占用实测](benchmarks/memory-2026-10.md)
+  - [缓存验收实验](benchmarks/cache-2026-10-02.md)、[自动压缩 E6](benchmarks/cache-e6-2026-10-02.md)、[对话中途的 system 消息](benchmarks/cache-midconvo-2026-10-09.md)
+  - [三预设基准](benchmarks/presets-2026-10-02.md)、[todo 进 default](benchmarks/presets-todo-2026-10-02.md)、[多步长任务复测](benchmarks/presets-todo-2026-10-03.md)
+
+## en/ 英文译本
+
+[终端界面](en/guides/tui.md)、[供应商与模型](en/guides/providers.md)、[权限](en/guides/permissions.md)、
+[会话](en/guides/sessions.md)、[RPC 协议](en/reference/rpc.md)、[ACP](en/reference/acp.md)、
+[宿主适配器 API](en/reference/host-api.md)。译本头部记着翻译时的中文版提交，`pnpm release:check` 在中文版
+之后改动较多时提示同步。

package/docs/assets/ama-wordmark-dark.svg

@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="216" height="96" viewBox="0 0 216 96" shape-rendering="crispEdges" role="img" aria-label="ama">
+  <title>ama</title>
+  <g fill="#5fafff">
+    <rect x="24" y="8" width="24" height="8"/>
+    <rect x="16" y="16" width="40" height="8"/>
+    <rect x="8" y="24" width="24" height="8"/>
+    <rect x="40" y="24" width="24" height="8"/>
+    <rect x="8" y="32" width="16" height="8"/>
+    <rect x="48" y="32" width="16" height="8"/>
+    <rect x="8" y="40" width="56" height="16"/>
+    <rect x="8" y="56" width="16" height="24"/>
+    <rect x="48" y="56" width="16" height="24"/>
+  </g>
+  <g fill="#87afff">
+    <rect x="72" y="8" width="16" height="8"/>
+    <rect x="128" y="8" width="16" height="8"/>
+    <rect x="72" y="16" width="24" height="16"/>
+    <rect x="120" y="16" width="24" height="16"/>
+    <rect x="72" y="32" width="32" height="8"/>
+    <rect x="112" y="32" width="32" height="8"/>
+    <rect x="72" y="40" width="16" height="40"/>
+    <rect x="96" y="40" width="24" height="8"/>
+    <rect x="128" y="40" width="16" height="40"/>
+    <rect x="104" y="48" width="8" height="8"/>
+  </g>
+  <g fill="#af87ff">
+    <rect x="168" y="8" width="24" height="8"/>
+    <rect x="160" y="16" width="40" height="8"/>
+    <rect x="152" y="24" width="24" height="8"/>
+    <rect x="184" y="24" width="24" height="8"/>
+    <rect x="152" y="32" width="16" height="8"/>
+    <rect x="192" y="32" width="16" height="8"/>
+    <rect x="152" y="40" width="56" height="16"/>
+    <rect x="152" y="56" width="16" height="24"/>
+    <rect x="192" y="56" width="16" height="24"/>
+  </g>
+</svg>