@armadra/agent 0.2.1 → 0.4.0

package/docs/tui.md

@@ -6,26 +6,52 @@
 
 ## 布局
 
+视觉规格（配色、字形、逐屏样稿）见 [tui-design.md](tui-design.md)。层级用缩进表达：第 0 列是用户 `›`、工具 `⏺` 与提示符号，第 2 列是结果连接符 `⎿`，第 4 列是工具输出；去掉颜色（`NO_COLOR`、`capture-pane` 不带 `-e`）也读得出结构。
+
 ```
-ama 0.1.0 · Enter 发送 · Esc 中断 · Ctrl+C 两次退出 · /help 命令    ← 启动画面
-› 读一下 README                                                    ← 用户消息
-思考 · 120 token                                                    ← 思考块（折叠）
-● read  README.md                                                   ← 工具调用
-  …前 3 行结果…
-回答正文（Markdown）
-↳ followUp  之后再提交                                               ← 排队消息
-⠋ 工作中 · Esc 中断 (12s)                                            ← 运行中
-──────────────────────────────────
-输入框
-──────────────────────────────────
-anthropic/claude-sonnet · think:medium · ↑12k ↓1.2k · cache 80% ♨ · $0.12 · rebill $0.11 · ctx 34% · mode:default · preset:default
+╭──────────────────────────────────────────────────────────────╮
+│ ✻ ama 0.3.0                                                  │   ← 启动头（normal 档）
+│                                                              │
+│ 模型   anthropic/claude-sonnet-4-5 · 思考 medium             │
+│ 目录   ~/Projects/demo · 已信任（trust.json）                │
+│ 模式   Accept edits · 预设 default                           │
+│ 已加载 AGENTS.md · 2 Skill                                   │
+│                                                              │
+│ /help 命令 · Shift+Tab 切模式 · Ctrl+O 展开工具输出          │
+╰──────────────────────────────────────────────────────────────╯
+
+› 读一下 README                                    ← 用户消息（续行缩进 2 列）
+
+✻ 思考 · 120 token                                 ← 思考块（折叠；Ctrl+O 展开）
+
+⏺ read README.md                                   ← 工具调用：⏺ 工具名 摘要
+  ⎿ 读取 5 行                                       ← 一行结果摘要
+      1  # Demo                                     ← 输出正文（缩进 4 列）
+    … 另 2 行（Ctrl+O 展开）
+⏺ bash pnpm test                                   ← 相邻工具调用之间不空行
+  ⎿ ⠋ 运行中 · 4s
+
+  ↳ 之后  顺便更新文档                              ← 排队消息
+    Alt+↑ 取回 · Esc 回填并中断
+⠋ 运行 bash · 4s · Esc 中断                         ← 运行中动词
+────────────────────────────────────────────────
+› 输入消息，/ 命令，@ 文件，Shift+Enter 换行        ← 输入框（占位）
+────────────────────────────────────────────────
+Accept edits · shift+tab 切换     sonnet-4-5 · medium · ↑12k ↓1.2k · cache 80% ♨ · $0.12 · ctx 34%
 ```
 
-- **用户消息**：`›` 开头；运行中插话标 `↳ steer`，排到本轮之后的标 `↳ followUp`，宿主（Armadra 画布）注入的标 `↳ host`。
-- **思考块**：`ui.showThinking` = `collapsed`（缺省，一行计数）/ `full`（全文）/ `hidden`。
-- **工具调用**：一行标题，圆点运行中为强调色、成功绿、失败红；折叠显示结果前 3 行，`edit` 显示 diff（前 12 行），`bash` 运行中滚动显示最后 8 行。`Ctrl+O` 展开 / 折叠全部。codemode 脚本里的内层调用挂在外层调用下面。
-- **提示**：压缩摘要卡、`↻ 重试 n/m`、`⛔ Hook 阻止`、宿主通知、审批被拒或超时的说明都进消息区。
-- **状态栏**：模型 · 思考级别 · `↑` 输入（含缓存读写）`↓` 输出 · 缓存 · 费用 · 重计费 · 上下文占用 · 排队数 · 权限模式 · codemode · 工具预设 · 宿主状态。终端太窄时依次丢弃宿主状态、预设、重计费、费用、缓存、token、思考级别、排队数、codemode，模型、上下文与权限模式最后丢。
+- **用户消息**：`›` 开头，续行缩进 2 列；运行中插话标 `↳ 插话`，排到本轮之后的标 `↳ 之后`，宿主（Armadra 画布）注入的标 `↳ 宿主`（会话文件里的 `origin` 不变：steer / followUp / host）。
+- **思考块**：`ui.showThinking` = `collapsed`（缺省，`✻ 思考中…` → `✻ 思考 · 1.2k token`，`Ctrl+O` 展开为缩进的正文，最多 60 行）/ `full`（总是展开）/ `hidden`。
+- **工具调用**：标题 `⏺ 工具名 摘要`，`⏺` 运行中为强调色、成功绿、失败红；第二行 `⎿` 后是结果摘要——`读取 N 行`、`N 处修改 · +a −b`、`退出 0 · 2.1s · 48 行`、`14 处匹配 · 6 个文件`、`N 个内层调用 · 脚本输出 M 行`、`子 Agent · 运行中 1m05s` / `完成 · 1m42s · ↑28k ↓4.1k`；运行中摘要行带与底部同帧的 spinner 与秒数。正文折叠显示前 3 行，`edit` 显示 diff（前 12 行，≥ 60 列带行号），`bash` 运行中滚动显示最后 8 行。`Ctrl+O` 展开 / 折叠全部（含思考块）。codemode 脚本里的内层调用挂在外层调用下面（折叠时只列最近 5 个的标题与摘要）。
+- **提示**：`✗` 错误、`↻ 重试 n/m`、`!` 警告（缓存未命中、上下文余量）、`⛔ Hook 阻止`、宿主通知、审批被拒或超时的说明；压缩 / 分支摘要是左竖条卡片（`▎ 上下文已压缩  128k → 24k token`）。
+- **运行中**：`⠋ 动词 · 已用时 · …`，动词按当前最深状态取：`等待确认`（审批打开）、`运行 bash` / `运行 3 个工具`、`重试 2/3 · 2s 后`、`压缩上下文`、`回复中 · ↓≈1.2k`（本条输出的估算 token）、`思考中`。
+- **状态栏**：永远是最后一行。左区权限模式与 `shift+tab 切换` 提示，右区按固定顺序：模型 · 思考级别 · `↑` 输入（含缓存读写）`↓` 输出 · 缓存 · 费用 · 重计费 · 上下文占用 · 排队数 · codemode · 工具预设（非 default 时）· 宿主状态；分隔符固定为 `·`，宿主可按此解析。模型名随宽度缩写（< 100 列去供应商、< 60 去渠道、< 48 去版本后缀）。终端太窄时依次丢弃切换提示、宿主状态、预设、重计费、费用、缓存、token、思考级别、排队数、codemode、上下文、模型；权限模式永不丢。≥ 110 列时上下文显示为余量表 `ctx ▮▮▮▯▯▯▯▯▯▯ 34%`。
+- **退出**：消息区最后追加一行会话摘要与恢复命令，留在终端回滚里：
+
+```
+─ 会话 3f2a9c1e · 12 分钟 · 7 回合 · ↑128k ↓9.4k · cache 81% · $0.42（重计费 $0.03）
+  恢复：ama --resume 3f2a9c1e
+```
 
 ## 缓存与上下文
 
@@ -38,8 +64,8 @@ anthropic/claude-sonnet · think:medium · ↑12k ↓1.2k · cache 80% ♨ · $0
 | `cache 未报告`  | 端点不报缓存（`silent`：连续 3 个可比请求读写都是 0，或 `compat.cacheReporting: "silent"`）；这类请求不进命中率分母 |
 | `♨`             | 保温计时中（工具长时间运行时按 TTL 重放前缀，`/cache warm` 可切换）                                                 |
 | `rebill $0.11`  | 本会话缓存未命中导致的重计费金额；模型没有价格时显示 token 数；为 0 不显示                                          |
-| `ctx 72%`       | 上下文占用，≥ 70% 黄色、≥ 90% 红色；`ctx ?` 表示模型没有窗口信息                                                    |
-| `codemode:only` | codemode 生效（`on` / `only`）；运行时 Node 的权限模型不隔离网络（Node 22 / 24）时追加红色 `net!`                   |
+| `ctx 72%`       | 上下文占用，< 70% 绿色、≥ 70% 黄色、≥ 90% 红色；`ctx ?` 表示模型没有窗口信息                                        |
+| `codemode only` | codemode 生效（`on` / `only`）；运行时 Node 的权限模型不隔离网络（Node 22 / 24）时追加红色 `net!`                   |
 
 消息区（line 模式写 stderr，前缀 `ama: `）只在两种情况下提示一行，`cache.missNotices: false` 可关：
 
@@ -47,16 +73,22 @@ anthropic/claude-sonnet · think:medium · ↑12k ↓1.2k · cache 80% ♨ · $0
 - 上下文占用跨过 70% / 90%（各一次）：`上下文已用 72%，约剩 9 回合（按最近 5 回合均值）`；回合数估不出时给余量 token。
 - line 模式在 `AMA_LOG=info` 时另写保温成功：`缓存保温已刷新（读 12k token，$0.001）`。
 
-`/session` 在会话信息之后有「缓存」段，`/cache` 只显示这一段：
+`/session` 在消息区画一张左竖条面板，会话信息之后是「缓存」段，`/cache` 只显示这一段（line 模式与 RPC 是同样内容的纯文本）：
 
 ```
-缓存
-  输入      3.4k = 缓存读 2.2k（65%）+ 未缓存 1.2k
-  报告状态  reported
-  命中率    最近 84% · 会话 65%
-  未命中    0 次
-  保温      streaming · 已停止：模型目录没有缓存 TTL
-  上下文    1%，余量 ≈ 127k token ≈ 2443 回合
+▎ 会话 3f2a9c1e  ~/.local/share/ama/sessions/…/3f2a9c1e.jsonl
+▎ 模型    anthropic/claude-sonnet-4-5 · 思考 medium · 权限 Accept edits
+▎ 消息    用户 7 · 助手 9 · 工具调用 23
+▎ 用量    输入 3.4k · 输出 9.4k · 缓存读 118k · 缓存写 6.2k · $0.42
+▎ 上下文  ▮▮▮▯▯▯▯▯▯▯ 34% · 68k / 200k
+▎
+▎ 缓存
+▎   输入      3.4k = 缓存读 2.2k（65%）+ 未缓存 1.2k
+▎   报告状态  reported
+▎   命中率    最近 84% · 会话 65%
+▎   未命中    0 次
+▎   保温      streaming · 已停止：模型目录没有缓存 TTL
+▎   上下文    1%，余量 ≈ 127k token ≈ 2443 回合
 ```
 
 未命中行按原因分列（`3 次，重计费 61k token ≈ $0.18（空闲超时 2 · 前缀变化 1）`）；保温行在计时中显示 `streaming · 下次 2m 10s · 期望节省 $0.18 ≥ $0.05`，停止时给原因；有 task 子会话时另有「子任务」行。
@@ -70,20 +102,20 @@ anthropic/claude-sonnet · think:medium · ↑12k ↓1.2k · cache 80% ♨ · $0
 
 ## 按键
 
-| 按键                 | 作用                                                               |
-| -------------------- | ------------------------------------------------------------------ |
-| Enter                | 发送；运行中 = steer（插到当前轮）                                 |
-| Alt+Enter            | 运行中排到本轮之后（followUp）；空闲时等同 Enter                   |
-| Shift+Enter / Ctrl+J | 换行                                                               |
-| Esc                  | 中断：排队的消息回填到输入框，然后停止当前运行；补全打开时先关补全 |
-| Alt+↑                | 取回最后一条排队消息                                               |
-| Shift+Tab            | 循环权限模式 plan → default → auto-edit → full-auto                |
-| Ctrl+O               | 展开 / 折叠工具输出                                                |
-| Ctrl+L / Ctrl+T      | 选择模型 / 思考级别                                                |
-| Ctrl+C               | 清空输入；输入为空时 1.5 秒内再按一次退出（退出码 130）            |
-| Ctrl+D               | 输入为空时退出                                                     |
-| Tab                  | 补全                                                               |
-| ↑ / ↓                | 单行时浏览历史（`<数据目录>/history`，500 条）                     |
+| 按键                 | 作用                                                                  |
+| -------------------- | --------------------------------------------------------------------- |
+| Enter                | 发送；运行中 = steer（插到当前轮）                                    |
+| Alt+Enter            | 运行中排到本轮之后（followUp）；空闲时等同 Enter                      |
+| Shift+Enter / Ctrl+J | 换行                                                                  |
+| Esc                  | 中断：排队的消息回填到输入框，然后停止当前运行；补全打开时先关补全    |
+| Alt+↑                | 取回最后一条排队消息                                                  |
+| Shift+Tab            | 循环权限模式 Manual → Accept edits → Plan → Auto → Bypass permissions |
+| Ctrl+O               | 展开 / 折叠工具输出与思考块                                           |
+| Ctrl+L / Ctrl+T      | 选择模型 / 思考级别                                                   |
+| Ctrl+C               | 清空输入；输入为空时 1.5 秒内再按一次退出（退出码 130）               |
+| Ctrl+D               | 输入为空时退出                                                        |
+| Tab                  | 补全                                                                  |
+| ↑ / ↓                | 单行时浏览历史（`<数据目录>/history`，500 条）                        |
 
 按键可在 `~/.config/ama/keybindings.json` 覆盖，键是动作 id（`app.interrupt`、`app.message.followUp`、`tui.editor.newLine` ……），值是按键或按键数组，空数组表示禁用。
 
@@ -93,8 +125,11 @@ anthropic/claude-sonnet · think:medium · ↑12k ↓1.2k · cache 80% ♨ · $0
 
 - `/tree`：列出会话里的全部用户消息（分叉处缩进，`●` 是当前分支）；选中一条后回到它之前，原文回填输入框，修改后发送就形成新分支。
 - `/fork`（无参数）：同样选一条用户消息，从它之前复制出新会话。
-- `/model`、`/resume`、`/permission`、`/thinking` 不带参数时打开选择器；`/permissions` 显示权限判定顺序与已加载规则。
-- `/session`、`/cache`：会话用量与缓存统计（见下文「缓存与上下文」）。
+- `/model`、`/resume`、`/permission`、`/thinking` 不带参数时打开选择器；`/permissions` 显示权限判定顺序、已加载规则与最近 20 条 auto 判定（层、结果、原因）。
+- `/permission` 选择器标题「权限模式」：Manual / Accept edits / Plan / Auto / Bypass permissions / Allowlist only，每项一行说明，右侧数字 1–6 直接选；当前模式打 `✓`，配置里的缺省模式标 `Default`，Auto 标 `Recommended`，底部一行按键提示。`/permission auto`、`/permission Accept edits` 直接切换。状态栏最左是模式的显示名。auto 模式下需要确认时，审批对话框多一行「Auto 规则层 / 分类器：原因」。详见 [permissions.md](permissions.md)。
+- 选择器底部一行按键提示（`↑↓ 选择 · Enter 确认 · Esc 取消`），选中行有底色（≥ 256 色；更少时强调色粗体）。`/model` 选择器给当前模型打 `✓`，并带 `(i/n)` 计数；按「供应商 · 渠道」分组（多渠道模型在每个渠道下各一项，非首选渠道带 `@渠道`），说明里有上下文与 `img`（收图片）；`/model packy/kimi-k2.5@messages` 直接切到指定渠道。
+- 输入里的 `@图片路径`（可加引号，Tab 补全路径）或粘贴 / 拖入的图片文件路径作为图片附件随消息发送；当前模型不收图片时 `@` 附件报错、不发送，未加 `@` 的路径忽略（见 [providers.md](providers.md)「图像输入」）。
+- `/session`、`/cache`：会话用量与缓存统计面板（见上文「缓存与上下文」）；`/permissions` 同样是面板，allow 绿、deny 红，判定顺序折行对齐。
 
 ## 补全
 
@@ -103,7 +138,25 @@ anthropic/claude-sonnet · think:medium · ↑12k ↓1.2k · cache 80% ♨ · $0
 
 ## 审批
 
-工具调用需要确认时，底部弹出对话框：bash 显示完整命令，write 显示路径与行数，edit 显示每处修改的 −/+ 摘要；子 Agent 发起的请求标 `[task]`。`y` 允许、`n` / Esc 拒绝、`a` 本会话内同类不再询问、`v` 查看完整输入。10 分钟不作答按拒绝处理（`AMA_APPROVAL_TIMEOUT_MS` 可改）。
+工具调用需要确认时，底部弹出对话框：标题是原因（`需要确认` / `危险命令` / `Hook 要求确认`，子 Agent 发起的加 `[task]`），边框随预览严重度变红 / 黄；bash 显示完整命令，write 显示路径与行数，edit 显示每处修改的 −/+ 摘要。下面是编号选项：
+
+```
+╭─ 危险命令 ─────────────────────────────────────────────╮
+│ bash  危险命令                                          │
+│ $ rm -rf build dist/*.map > out.log                     │
+│                                                         │
+│ 删除 build/：目录，132 个文件，1.2 MB                   │
+│ 这条命令可能有破坏性，请确认                            │
+│                                                         │
+│   1. 允许                                         y     │
+│   2. 本会话允许同类                               a     │
+│ › 3. 拒绝                                         n Esc │
+│                                                         │
+│ ↑↓ 选择 · Enter 确认 · v 完整输入                       │
+╰─────────────────────────────────────────────────────────╯
+```
+
+`1`–`3` 或 `↑↓` + Enter 选择，`y` 允许、`a` 本会话内同类不再询问、`n` / Esc / Ctrl+C 拒绝、`v` 查看完整输入。缺省选中项：危险命令是「拒绝」，其余是「允许」。窄于 56 列时紧凑显示（工具名单独一行、不留空行）。10 分钟不作答按拒绝处理（`AMA_APPROVAL_TIMEOUT_MS` 可改）。
 
 输入摘要之后是**执行前预览**：这一步会碰到什么。
 
@@ -115,15 +168,33 @@ anthropic/claude-sonnet · think:medium · ↑12k ↓1.2k · cache 80% ♨ · $0
 
 ## 启动画面
 
-`ui.quietStartup` / `--quiet-startup`：`normal` 显示标题、模型、目录与信任状态、已加载的上下文文件 / Skill / 提示模板 / Hook；`header` 只有标题行（profile 缺省）；`silent` 不显示。`--resume` 不带 id、模型没有 key、会话目录不存在、项目资源需要信任时，界面启动前会先出现一个小的选择 / 输入提示，答完收成一行留在屏幕上。
+`ui.quietStartup` / `--quiet-startup`：`normal` 显示带框的启动头——标题、模型与思考级别、目录（`~` 缩写）与信任状态、权限模式 / 预设 / codemode、已加载的上下文文件 / Skill / 提示模板 / Hook、警告数与常用按键；窄于 56 列或 `ui.compact` 时去框、每项一行。`header` 只有一行 `✻ ama 版本 · 模型 · 模式 · /help`（profile 缺省）；`silent` 不显示。`--resume` 不带 id、模型没有 key、会话目录不存在、项目资源需要信任时，界面启动前会先出现一个小的选择 / 输入提示，答完收成一行留在屏幕上。
 
 ## 在 tmux / Armadra 终端节点里
 
-- 括号粘贴：启动时开启；粘贴的多行内容整体进入输入框（超过 10 行或 1 000 字符折叠为 `[paste #N +M lines]`），粘贴后紧跟的回车直接发送，适合由外部程序写入。
+- 括号粘贴：启动时开启；粘贴的多行内容整体进入输入框（超过 10 行或 1 000 字符折叠为 `[粘贴 #N · M 行]`），粘贴后紧跟的回车直接发送，适合由外部程序写入。
 - 不查询终端能力、不开鼠标与 Kitty 键盘协议，避免回包混进输入；tmux ≥ 3.4 透传同步输出，旧版本也能正常显示。
 - 窗口尺寸变化时整屏重画最后一屏，回滚里的历史不受影响。
 - 自动降级：非 TTY、`TERM=dumb`、`--no-tui` 或终端初始化失败时使用行式界面，命令与审批问答相同。
 
+## 配置与排错
+
+`config.json` 的 `ui` 段（项目级也可设）：
+
+| 键                | 缺省        | 作用                                                                                          |
+| ----------------- | ----------- | --------------------------------------------------------------------------------------------- |
+| `ui.theme`        | `dark`      | `dark` / `light` / `auto`；auto 只看 `COLORFGBG`（不发终端查询），猜不出用 dark，建议显式配置 |
+| `ui.ascii`        | 自动检测    | ASCII 字形（`›` → `>`、`⏺` → `*`、`⎿` → `L`、框线 → `+ - \|`、spinner 4 帧）                  |
+| `ui.compact`      | `false`     | 消息区块间不空行、启动头无框                                                                  |
+| `ui.animation`    | `true`      | `false`：运行中 spinner 静止为 `·`，只在秒数变化时重绘                                        |
+| `ui.markdown`     | `true`      | `false`：助手正文不做 Markdown 渲染                                                           |
+| `ui.showThinking` | `collapsed` | 见「布局」                                                                                    |
+| `ui.quietStartup` | `normal`    | 见「启动画面」                                                                                |
+
+- **ASCII 模式**：`AMA_ASCII=1`（或 `ui.ascii: true`）强制开启，`AMA_ASCII=0` 强制关闭；自动检测在区域设置（`LC_ALL` > `LC_CTYPE` > `LANG`）已设置但不含 UTF-8、`TERM=linux`、Windows 上既没有 `WT_SESSION` 也没有 `TERM_PROGRAM`（旧 conhost）时开启。Windows Terminal 走 Unicode。
+- **字符错位**：`⏺`（U+23FA）、`⎿`、`▎` 在个别字体（尤其 emoji 回退字体）下画成两格，宽度计算按 wcwidth（一格），会出现列错位或残影——换等宽字体或设 `AMA_ASCII=1`。
+- **颜色**：`NO_COLOR` 或 `TERM=dumb` 无色；16 色终端按内置表取近，选中行不用底色而用强调色粗体；浅色终端设 `ui.theme: "light"`。
+
 ## 组件库（`@armadra/agent/tui`）
 
 交互模式用的终端组件单独导出，零依赖，宿主或其它 Node 程序可以直接用来画主屏界面。
@@ -148,21 +219,29 @@ tui.setFocus(editor);
 tui.start();
 ```
 
-| 导出                                                                        | 作用                                                                                                                                 |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `Component`、`Focusable`、`CURSOR_MARKER`                                   | 组件契约：`render(width)` 返回各行（每行可见宽 ≤ width）、`handleInput?(data)`、`invalidate()`；获焦组件在光标处输出 `CURSOR_MARKER` |
-| `TUI`                                                                       | 根容器与差分渲染（主屏、同步输出）：`addChild`、`start` / `stop`、`requestRender`、`setFocus`、`addInputListener`、`showOverlay`     |
-| `ProcessTerminal`、`MemoryTerminal`、`VirtualScreen`                        | 真实终端（raw 模式、括号粘贴）；内存终端与 VT 屏幕（测试、帧黄金）                                                                   |
-| `Container`、`Text`、`TruncatedText`、`Markdown`、`Box`、`Spacer`、`Loader` | 基础组件                                                                                                                             |
-| `Editor`、`EditorBuffer`、`PasteStore`                                      | 多行编辑器（历史、补全接口 `AutocompleteProvider`、粘贴折叠）                                                                        |
-| `SelectList`                                                                | 可过滤的选择列表                                                                                                                     |
-| `KeyValue`、`Meter`                                                         | 两列对齐的键值表；进度条                                                                                                             |
-| `compositeOverlays`、`OverlayOptions`                                       | 覆盖层合成（居中 / 底部锚定）                                                                                                        |
-| `createTheme`、`plainTheme`、`detectCapabilities`、`Theme`                  | 主题与颜色能力探测（`NO_COLOR`、16 / 256 / truecolor）；11 个语义色                                                                  |
-| `Keybindings`、`DEFAULT_KEYBINDINGS`、`loadKeybindingsFile`                 | 动作 id → 按键，`keybindings.json` 覆盖                                                                                              |
-| `parseKey`、`matchesKey`、`StdinBuffer`                                     | 键序列解析与 Esc 超时切分（`AMA_TUI_ESC_TIMEOUT`）                                                                                   |
-| `visibleWidth`、`truncateToWidth`、`wrapTextWithAnsi`、`sliceByColumn` 等   | 带 ANSI 与宽字符的宽度计算与截断                                                                                                     |
+| 导出                                                                      | 作用                                                                                                                                 |
+| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `Component`、`Focusable`、`CURSOR_MARKER`                                 | 组件契约：`render(width)` 返回各行（每行可见宽 ≤ width）、`handleInput?(data)`、`invalidate()`；获焦组件在光标处输出 `CURSOR_MARKER` |
+| `TUI`                                                                     | 根容器与差分渲染（主屏、同步输出）：`addChild`、`start` / `stop`、`requestRender`、`setFocus`、`addInputListener`、`showOverlay`     |
+| `ProcessTerminal`、`MemoryTerminal`、`VirtualScreen`                      | 真实终端（raw 模式、括号粘贴）；内存终端与 VT 屏幕（测试、帧黄金）                                                                   |
+| `Container`、`Text`、`TruncatedText`、`Markdown`、`Box`、`Card`、`Spacer` | 基础组件；`Card` 是左竖条卡片，`Box` 可设 `borderColor`                                                                              |
+| `Loader`                                                                  | 运行指示：`setVerb(动词, 附加项, { elapsed })`、`frame` / `onFrame`（与别的组件同帧换字）、`animation: false`                        |
+| `Editor`、`EditorBuffer`、`PasteStore`                                    | 多行编辑器（历史、补全接口 `AutocompleteProvider`、粘贴折叠）                                                                        |
+| `SelectList`                                                              | 可过滤的选择列表：分组、徽标、数字键、`stacked`、`currentValue`（✓）、`footer` 按键提示                                              |
+| `KeyValue`、`Meter`                                                       | 两列对齐的键值表（`wrap` 折行对齐值列）；余量表（`levelColor` 阈值着色）                                                             |
+| `compositeOverlays`、`OverlayOptions`                                     | 覆盖层合成（居中 / 底部锚定）                                                                                                        |
+| `createTheme`、`plainTheme`、`detectCapabilities`、`Theme`                | 主题与颜色能力探测（`NO_COLOR`、16 / 256 / truecolor）；14 个语义色，`resolveThemeName("auto")`                                      |
+| `Theme.glyphs`、`UNICODE_GLYPHS`、`ASCII_GLYPHS`、`detectAscii`           | 字形表（`›` `⏺` `⎿` `✻` `▎`、框线、spinner 帧……）与 ASCII 回退；`createTheme(name, { ascii })`                                       |
+| `Keybindings`、`DEFAULT_KEYBINDINGS`、`loadKeybindingsFile`               | 动作 id → 按键，`keybindings.json` 覆盖                                                                                              |
+| `parseKey`、`matchesKey`、`StdinBuffer`                                   | 键序列解析与 Esc 超时切分（`AMA_TUI_ESC_TIMEOUT`）                                                                                   |
+| `visibleWidth`、`truncateToWidth`、`wrapTextWithAnsi`、`sliceByColumn` 等 | 带 ANSI 与宽字符的宽度计算与截断                                                                                                     |
 
 ## 测试
 
-`src/modes/interactive/interactive-mode.test.ts` 用 `MemoryTerminal`（80x24、40x24）+ fake 供应商跑一次完整的读文件 run，把启动、输入、工具运行中、结束、`Ctrl+O` 展开、退出各帧写进 `test/fixtures/tui/run-*.txt`。改界面后用 `AMA_UPDATE_GOLDEN=1 pnpm vitest run src/modes/interactive` 更新并审阅差异。
+帧黄金都在 `test/fixtures/tui/`，`MemoryTerminal` 还原屏幕（无色，只验布局与字形）：
+
+- `src/modes/interactive/interactive-mode.test.ts`：80x24、40x24 跑一次完整的读文件 run（启动、输入、工具运行中、结束、`Ctrl+O` 展开、退出摘要）→ `run-*.txt`；审批、缓存提示等。
+- `src/modes/interactive/interactive-frames.test.ts`：启动头（`startup-normal-*`、`header-quiet-*`）、工具层级（`tools-*`）、提示（`notices-*`）、运行中动词（`loader-verbs-*`）、`/session` 面板（`panel-session-*`）、ASCII 模式整条 run（`ascii-run-*`）。
+- `src/tui/tui-frames.test.ts`：组件级（对话、Markdown、编辑器占位 / 多行 / 粘贴 / 补全）；`status-bar.test.ts` 的 `status-widths.txt`；`approval-dialog.test.ts`、`pickers.test.ts` 的审批与模式选择器。
+
+改界面后用 `AMA_UPDATE_GOLDEN=1 pnpm vitest run src/modes/interactive src/tui` 更新，并逐个审阅 `git diff test/fixtures/tui`。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@armadra/agent",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "可独立使用、可嵌入 Armadra 的编码 / 协调 Agent",
   "type": "module",
   "keywords": [
@@ -57,10 +57,12 @@
     "docs/rpc.md",
     "docs/host-api.md",
     "docs/hooks.md",
+    "docs/permissions.md",
     "docs/providers.md",
     "docs/codemode.md",
     "docs/tui.md",
     "docs/session-format.md",
+    "docs/sessions.md",
     "CHANGELOG.md"
   ],
   "sideEffects": [