@epoch-agent/tui 4.0.0 → 4.1.0

package/dist/index.d.ts

@@ -271,18 +271,16 @@ type TuiHistoryItem = TuiHistoryItemWithoutId & {
  *
  * 命令拿到的是一组回调（`SlashCommandContext`），自己不碰 React 状态，
  * 也不 import 任何 core 的东西 —— tui 只依赖 protocol，凡是需要引擎能力的
- * （切权限级别、列工具、读启动诊断）都由宿主在 `renderApp({ host })` 时注入。
- *
- * 这样命令实现是纯函数式的，可以直接对着一个假的 context 单测，
- * 不用把整个 Ink 树跑起来。
+ * 都由宿主在 `renderApp({ host })` 时注入。于是命令是纯函数式的，对着一个假的
+ * context 就能单测，不用把整棵 Ink 树跑起来。
  */
 
 /**
- * `/goal` 一次子命令的结果（方案 52 PR-1）。
+ * `/goal` 一次子命令的结果。
  *
  * `message` 是**宿主已经渲染好的一句话**，TUI 原样印出来 —— 判据见
  * {@link HostActions.goals} 上那段 ⚠️。`ok` 只决定印成 info 还是 warning：
- * 拒绝的理由本身在 `message` 里，因为「下一步该敲什么」逐条不同
+ * 拒绝的理由在 `message` 里，因为「下一步该敲什么」逐条不同
  * （`busy` 要先 `/goal clear`，`no-goal` 要先建一个）。
  */
 interface GoalActionResult {
@@ -290,14 +288,13 @@ interface GoalActionResult {
     message: string;
 }
 /**
- * 这个进程记下的**一条弹窗答案**（审批缓存，2026-08-28）。
+ * 这个进程记下的**一条弹窗答案**（审批缓存）。
  *
- * core 的 `CachedApproval` 的**结构性镜像**（`tui` 不许 import core），
- * 判据同 {@link HostActions.checkpoints} 那三个方法：直接把 core 的类型绑上来
- * 等于让两边偷偷连在一起，而这一份的作用正是让漂移在编译期就红。
+ * core 的 `CachedApproval` 的**结构性镜像**：`tui` 不许 import core，直接绑
+ * core 的类型等于让两边偷偷连在一起，而抄这一份的作用正是让漂移在编译期就红。
  *
  * ⚠️ **`decision` 只有三档，没有 `allow-once`** —— 那一档压根不入缓存
- * （判据在 core 的 `CachedDecision` 上）。写成联合而不是 `string`，是为了让
+ * （真源是 core 的 `CachedDecision`）。写成联合而不是 `string`，是为了让
  * 「三档各印一句人话」那张表在漏一档时当场红，而不是在屏幕上留一个空白格。
  */
 interface CachedApprovalInfo {
@@ -317,15 +314,13 @@ interface CachedApprovalInfo {
     createdAt: number;
 }
 /**
- * 一次撤销为什么没成。**刻意不收成一个布尔**：两者在屏幕上是两句完全不同的话，
- * 而且只有一种算错 ——
+ * 一次撤销为什么没成。**刻意不收成一个布尔**：两者在屏幕上是两句完全不同的话。
  *
- * - `no-permission-layer`：这一节压根不适用（权限层没起来），下一步是 `/diagnostics`；
+ * - `no-permission-layer`：权限层没起来，这一节压根不适用，下一步是 `/diagnostics`；
  * - `unknown-id`：那条决定已经不在表里了。**不当错误报** —— 用户要的结果已经成立
  *   （同 web 那一侧的判据）。
  *
- * 回的是**码而不是句子**：这两句话落在 `tui.permissions.*` 里，由 TUI 挑，
- * 宿主那一层不该替它决定措辞。
+ * 回的是**码而不是句子**：措辞在 `tui.permissions.*` 里由 TUI 挑，宿主不该替它决定。
  */
 type ApprovalRevokeReason = 'no-permission-layer' | 'unknown-id';
 /** 宿主（tui-entry）注入的引擎能力。全部可选：缺哪个对应命令就报「不可用」而不是崩 */
@@ -354,25 +349,22 @@ interface HostActions {
      * provider 类型 / API key 提示，用于 /model。
      *
      * 回 `null` = provider 没起来。**每次调都要重新问宿主**，别缓存：
-     * 方案 26 之后 `/model` 能换 provider，缓存下来就会显示启动时那家。
+     * `/model` 能换 provider，缓存下来就会显示启动时那家。
      */
     getProviderInfo?: () => {
         provider: string;
         apiKeyHint: string;
     } | null;
     /**
-     * 换模型（方案 26）。`'reset'` = 回到配置里那个。
+     * 换模型。`'reset'` = 回到配置里那个。
      *
-     * 返回的是 core 的判定结果原样透传，**不在这里翻译成 boolean**：
-     * 三种拒绝（没凭据 / 不认图片 / 窗口装不下）各有各的下一步动作，
-     * 收成一个 false 之后 UI 只能编一句笼统的话。
-     * 判据全在 core，这里只负责把结果显示出来 —— 少一处会和引擎漂移的地方。
+     * 返回的是 core 的判定结果原样透传，**不在这里翻译成 boolean**：三种拒绝
+     * （没凭据 / 不认图片 / 窗口装不下）各有各的下一步，收成一个 false 之后
+     * UI 只能编一句笼统的话。
      *
-     * `ctx` 是**两边各知道一半**的会话事实，所以两边都填、在宿主那侧合并：
-     *   - `usedTokens` —— TUI 有（`SessionStats.lastInputTokens`），引擎侧没有
-     *     一个「上一次请求送进去多少」的现成读点
-     *   - `hasImages` —— 宿主有（会话历史里的 image part），TUI 只看得见
-     *     还没发出去的那几张
+     * `ctx` 是**两边各知道一半**的会话事实，两边都填、在宿主那侧合并：
+     * `usedTokens` 只有 TUI 有（`SessionStats.lastInputTokens`），`hasImages`
+     * 只有宿主有（会话历史里的 image part，TUI 只看得见还没发出去的那几张）。
      */
     setModel?: (ref: ModelRef | 'reset', ctx?: SelectionContext) => SetSelectionResult;
     /**
@@ -386,7 +378,7 @@ interface HostActions {
         contextLength: number;
     };
     /**
-     * 取走引擎在这一轮里攒下的模型提示，取完即清（方案 26 验收 #8）。
+     * 取走引擎在这一轮里攒下的模型提示，取完即清。
      *
      * 目前只有一句：某个模型连续失败到了阈值，本会话不再自动降级重试它。
      * 这件事必须**说出来**，否则用户看到的只是「回答忽然换了个味道」，
@@ -418,24 +410,23 @@ interface HostActions {
      */
     supportsImages?: () => boolean;
     /**
-     * 把一条自定义斜杠命令展开成一次 turn 的输入（方案 23）。
+     * 把一条自定义斜杠命令展开成一次 turn 的输入。
      *
-     * 插值（`$ARGUMENTS` / `$1`）要用方案 21 的 tokenizer，而那住在 infra ——
+     * 插值（`$ARGUMENTS` / `$1`）要用 tokenizer，而那住在 infra ——
      * tui 只依赖 protocol，够不着。所以展开在宿主侧做，TUI 拿到的是结果。
      *
-     * 认不出这个命令名时回 `undefined`（正常情况下不会：命令表本来就是宿主给的，
-     * 除非表在这中间被换掉了）。
+     * 认不出这个命令名时回 `undefined`（命令表本来就是宿主给的，除非中途被换掉）。
      */
     expandCommand?: (name: string, args: string) => ExpandedCommand | undefined;
     /**
-     * 工作区文件清单，`@` 补全的候选（方案 25）。
+     * 工作区文件清单，`@` 补全的候选。
      *
      * 由宿主提供：它要跑 `git ls-files` / 走目录，而 tui 只依赖 protocol。
      * 异步是因为第一次可能要几十毫秒 —— 不该阻塞首帧。
      */
     listWorkspaceFiles?: () => Promise<readonly string[]>;
     /**
-     * 把 `@路径` 解析成带内容的附件部件（方案 25 §2.2 的选项 B）。
+     * 把 `@路径` 解析成带内容的附件部件。
      *
      * **必须由宿主做**，不只是因为 tui 读不了文件：这条路要过工作区边界判定和
      * 权限判定，而两者都在引擎那一侧。TUI 自己 `readFileSync` 等于给 `@`
@@ -447,43 +438,39 @@ interface HostActions {
         notices: string[];
     };
     /**
-     * `@:` 补全面板里的会话候选（方案 53 PR-2）。
+     * `@:` 补全面板里的会话候选。
      *
      * ## ⚠️ 这个形状里**没有转录文本，而且不许加**
      *
-     * §5.2 那条边界（面板只按 id / cwd / 标题匹配，永远不搜转录文本）**是安全边界
-     * 不是性能考虑**：面板边打边显示，如果它搜正文，那么打 `@:密码` 就会在屏幕上
-     * 列出所有提到过密码的会话 —— 而当前这块屏幕可能正在被别人看着（结对、录屏、
-     * 演示）。
+     * 面板只按 id / cwd / 标题匹配、永远不搜转录文本，**这是安全边界不是性能考虑**：
+     * 面板边打边显示，搜正文的话打 `@:密码` 就会在屏幕上列出所有提到过密码的会话
+     * —— 而这块屏幕可能正被别人看着（结对、录屏、演示）。
      *
-     * 落地上这条边界之所以是**结构性**的，就是因为这一层：转录文本一个字都不会
-     * 到达 TUI，所以 TUI 里再怎么改过滤也搜不出正文来。`sessions.preview` 那一列
-     * （首条消息的前几十字）同理不许出现在这里。
+     * 因为转录文本一个字都不会到达 TUI，这条边界是**结构性**的：TUI 里再怎么改
+     * 过滤也搜不出正文。`sessions.preview` 那一列同理不许出现在这里。
      *
-     * 异步 + 带 query：候选要过可读性判定（那在引擎侧），而过滤本身在宿主的
-     * SQL 里做 —— TUI 拿到的已经是「这次能看的这几条」。
+     * 异步 + 带 query：可读性判定在引擎侧，过滤本身在宿主的 SQL 里做 ——
+     * TUI 拿到的已经是「这次能看的这几条」。
      */
     listSessionCandidates?: (query: string, limit: number) => Promise<readonly SessionCandidateView[]>;
     /**
-     * 当前的后台任务表（方案 36 PR-2）。
+     * 当前的后台任务表。
      *
      * 同步返回：它只是读一张内存里的表，而状态栏每两秒要问一次 —— 异步的话
      * 每次都要过一遍微任务队列，还得处理「上一次还没回来」的竞态。
      */
     listBackgroundTasks?: () => readonly BackgroundTaskInfo[];
     /**
-     * 用户自配的状态栏那一段（方案 29 §2.6）。没配时**宿主不注入这一项**，
-     * 状态栏据此决定画不画 —— 而不是画一段空的、留个洞。
+     * 用户自配的状态栏那一段。没配时**宿主不注入这一项**，状态栏据此决定画不画
+     * —— 而不是画一段空的、留个洞。
      *
-     * 同步返回、且**不保证是最新的**：宿主给的是上一次跑完的值，顺便判断要不要
-     * 在后台再跑一次。这是刻意的，两个理由都写在
-     * [cli/src/statusline.ts](../../../cli/src/statusline.ts) 的文件头：
-     * 状态栏是装饰，不能因为一条命令卡住就让整个 UI 等；也不该由 TUI 来管
-     * 「谁去关那个定时器」。
+     * 同步返回、且**不保证是最新的**（宿主给上一次跑完的值，顺便判断要不要在后台
+     * 再跑一次）。理由写在 [cli/src/statusline.ts](../../../cli/src/statusline.ts)
+     * 的文件头：状态栏是装饰，不能因为一条命令卡住就让整个 UI 等。
      */
     readStatusLine?: () => string | null;
     /**
-     * 跑一条**用户手打**的命令（`!ls -la`，方案 25 §2.3）。
+     * 跑一条**用户手打**的命令（`!ls -la`）。
      *
      * `approve` 由 TUI 提供：宿主判定要确认时回调它，TUI 弹出和模型那条路
      * **完全相同**的确认框。判定本身在引擎侧 —— `!` 不是免检通道。
@@ -493,28 +480,28 @@ interface HostActions {
         ok: boolean;
         blocked?: boolean;
     }>;
-    /** 写一条记忆（`#记一下`，方案 25 §2.4）。`target` 决定用户级还是项目级 */
+    /** 写一条记忆（`#记一下`）。`target` 决定用户级还是项目级 */
     writeMemory?: (content: string, target: 'user' | 'memory', approve: (request: ApprovalRequest) => Promise<ApprovalOutcome>) => Promise<{
         output: string;
         ok: boolean;
         blocked?: boolean;
     }>;
     /**
-     * 把 `!` 跑出来的输出记进**模型的**上下文（方案 25 §2.3）。
+     * 把 `!` 跑出来的输出记进**模型的**上下文。
      *
      * TUI 自己的历史不是模型的上下文 —— 不接这一条的话，用户看得见输出而模型
      * 看不见，而「你看一下这个命令的输出」正是 `!` 存在的意义。
      */
     noteToSession?: (text: string) => void;
     /**
-     * 当前上下文预算的构成（方案 25 §2.5）。
+     * 当前上下文预算的构成。
      *
      * **每次调都要重新问**：历史每轮都在长。缓存下来 `/context` 会一直显示
      * 第一次看的那个数。
      */
     getContextBreakdown?: () => ContextBreakdown | null;
     /**
-     * 已加载的技能（方案 23 §2.5）。
+     * 已加载的技能。
      *
      * `scope` 要露出来：用户看见一条不认识的技能，第一个问题是「这哪来的」——
      * 同 `/help` 把内置命令和自定义命令分两段列的理由。
@@ -524,17 +511,16 @@ interface HostActions {
         description: string;
         category: string;
         /**
-         * `plugin` 是方案 32 加的第三种来源，它带的技能名一律是 `<插件名>:<名字>`；
-         * `host` 是方案 44 加的第四种（嵌入宿主 ship 的目录），同样一律带前缀。
+         * 后两种来源的技能名一律带前缀：`plugin` 是 `<插件名>:<名字>`，`host` 是
+         * 嵌入宿主 ship 的目录。
          *
-         * ⚠️ 这个联合是**抄**的（tui 不许 import core），所以它靠 `cli/src/tui-host.ts`
+         * ⚠️ 这个联合是**抄**的（tui 不许 import core），靠 `cli/src/tui-host.ts`
          * 那一行装配去撞真源 —— 真源加一格而这里不加，那一行当场编译不过。
-         * 方案 44 就是这么被逮到的。
          */
         scope: 'user' | 'project' | 'plugin' | 'host';
     }>;
     /**
-     * 可派给子 agent 的角色表（方案 18）。
+     * 可派给子 agent 的角色表。
      *
      * `tools` 是**声明值**，实际生效的还要和当时的工具表取交集 ——
      * 显示时要说明这一点，否则用户会以为角色能用一个已经被卸载的工具。
@@ -558,7 +544,7 @@ interface HostActions {
         error?: string;
     }>;
     /**
-     * 已装插件一览（方案 32）。
+     * 已装插件一览。
      *
      * **停用的和加载失败的都要在里面** —— 这条命令一半的价值就在那儿：
      * 一个因为 `epochVersion` 不满足而没加载的插件，在别处的唯一痕迹是启动时
@@ -611,12 +597,11 @@ interface HostActions {
         message?: string;
     }>;
     /**
-     * 工作区**有没有**未提交的改动（方案 27 §2.5 那句 `git stash` 提示）。
+     * 工作区**有没有**未提交的改动（回退面板那句 `git stash` 提示）。
      *
-     * 和 `gitDiff` 分开而不是拿它的 `text` 判空：回退面板要的只是一个布尔和一个
-     * 计数，而 `git diff HEAD` 在大仓库上会把几 MB 的补丁读进内存 —— 为了一行提示
-     * 付这个代价不划算。口径也不同：这里走 `git status --porcelain`，**未跟踪的
-     * 新文件也算**，而 `git diff HEAD` 看不见它们。
+     * 和 `gitDiff` 分开而不是拿它的 `text` 判空：这里要的只是一个布尔和一个计数，
+     * 而 `git diff HEAD` 在大仓库上会把几 MB 补丁读进内存。口径也不同：这里走
+     * `git status --porcelain`，**未跟踪的新文件也算**，而 `git diff HEAD` 看不见。
      *
      * 不是 git 仓库、git 不在 PATH 时回 `ok: false` —— 那时**什么都不提示**，
      * 而不是提示「工作区是干净的」：我们只是不知道。
@@ -627,34 +612,32 @@ interface HostActions {
         count: number;
     }>;
     /**
-     * 检查点与回退（方案 27）。`/rewind` 和 Esc Esc 共用这一份能力。
+     * 检查点与回退。`/rewind` 和 Esc Esc 共用这一份能力。
      *
      * 缺它时那条命令不注册、那个键位不武装 —— 判据见 {@link CheckpointActions}。
      */
     checkpoints?: CheckpointActions;
     /**
-     * 当前生效的键位一览（`/keybindings`，方案 31 PR-2 §2.5）。
+     * 当前生效的键位一览（`/keybindings`）。
      *
      * ## ⚠️ 回的是**渲染好的一整块文本**，不是结构
      *
-     * 判据逐字同下面 {@link HostActions.goals} 那一段：`tui` 只依赖 protocol，够不着
-     * `t()`，所以这里每写一句中文就是往 i18n 那条棘轮上添一笔债。而这条命令**通篇
-     * 都是文案** —— 分组标题、来源标注、被拒绝的理由各一句。
+     * 判据同 {@link HostActions.goals}：`tui` 够不着 `t()`，写进来的中文永远是中文，
+     * 而这条命令**通篇都是文案**（分组标题、来源标注、被拒绝的理由各一句）。
      *
-     * 另一半理由是这块内容的**事实来源全在宿主那边**：哪条是用户改的、哪条被保留键
-     * 拒了、哪条撞了谁，只有加载期（`core/src/config/keybindings.ts` 的
-     * `KeybindingReport`）知道。TUI 手上那张 `KeybindingTable` 是消解完冲突之后的
-     * 结果，从它反推来源只能靠猜。
+     * 另一半理由是**事实来源全在宿主那边**：哪条是用户改的、哪条被保留键拒了、
+     * 哪条撞了谁，只有加载期（`core/src/config/keybindings.ts` 的
+     * `KeybindingReport`）知道；TUI 手上那张表是消解完冲突之后的结果，反推只能靠猜。
      *
      * 宿主没接就**压根不注册**这条命令（同 `/rewind` 的判据）—— 一条只会回
      * 「不可用」的键位清单没有存在的意义。
      */
     keybindings?: () => string;
     /**
-     * 让这台终端能发 Shift+Enter（`/terminal-setup`，方案 31 §4.4 #24~#27）。
+     * 让这台终端能发 Shift+Enter（`/terminal-setup`）。
      *
      * 和 {@link HostActions.goals} 同一类：回的是**宿主渲染好的一整块文本**，
-     * `ok: false` 只是「这次没写成」（认不出的终端、备份失败……），理由本身在
+     * `ok: false` 只是「这次没写成」（认不出的终端、备份失败……），理由在
      * `message` 里。TUI 只负责把 `args` 原样带过去、把结果印出来。
      *
      * 宿主没接就**压根不注册**这条命令（同 `/keybindings` 的判据）。
@@ -675,7 +658,7 @@ interface HostActions {
         messages: number;
     }>;
     /**
-     * 手动压一次上下文（`/compact`，方案 25 §2.6）。
+     * 手动压一次上下文（`/compact`）。
      *
      * `instruction` 是「这次帮我留住什么」。**压缩是一次真实的 LLM 请求**，
      * 所以这条命令会花钱 —— 结果里带上压缩前后的条数，让用户看得见换来了什么。
@@ -716,7 +699,7 @@ interface HostActions {
         snippet: string;
     }>;
     /**
-     * 当前生效的权限规则 + 遮蔽情况（`/permissions`，方案 22 §2.7）。
+     * 当前生效的权限规则 + 遮蔽情况（`/permissions`）。
      *
      * `layer` 是**来源层**，这条命令存在的一半意义就在它身上 —— 用户查权限问题时
      * 的第一个问题永远是「这条 deny 是谁加的、我该去改哪个文件」。
@@ -732,44 +715,41 @@ interface HostActions {
             kind: string;
             message: string;
         }>;
-        /** 企业托管策略（方案 22 §2.6）。这台机器上没有托管文件时 `present: false` */
+        /** 企业托管策略。这台机器上没有托管文件时 `present: false` */
         managed: ManagedInfo;
         /**
-         * 这个进程记下的弹窗答案（审批缓存，2026-08-28）。**和 `rules` 不是一回事**：
-         * 那一张是配置文件里写下来的策略（能提交进 git），这一张是本机这一程的记忆。
-         * 判定时**规则的 deny 排在缓存前面**，所以屏幕上这两者必须分得开。
+         * 这个进程记下的弹窗答案（审批缓存）。**和 `rules` 不是一回事**：那一张是
+         * 配置文件里的策略（能提交进 git），这一张是本机这一程的记忆；判定时**规则的
+         * deny 排在缓存前面**，所以屏幕上这两者必须分得开。
          *
-         * ⚠️ **必填，不是可选。** 这一格和 {@link HostActions.revokeApproval} 是
-         * 同一条纵线的两头，而「列得出来、撤不掉」和「宿主忘了接」在屏幕上长得一样
-         * （都是那一节不出现）。必填让漏接的宿主在**编译期**就红，
-         * 而不是等用户敲 `/permissions` 时才发现少了一节。
+         * ⚠️ **必填，不是可选。** 它和 {@link HostActions.revokeApproval} 是一条纵线
+         * 的两头，而「列得出来、撤不掉」和「宿主忘了接」在屏幕上长得一样（都是那一节
+         * 不出现）—— 必填让漏接的宿主在**编译期**就红。
          *
          * 权限层没起来时是**空表**而不是抛错：没有权限层就等于什么都没记过。
          */
         approvals: readonly CachedApprovalInfo[];
     };
     /**
-     * 撤销**一条**缓存的审批决定（2026-08-28）。
+     * 撤销**一条**缓存的审批决定。
      *
-     * ⚠️ **它撤的只是缓存那一层。** 两张规则表的 `deny` 排在缓存**前面**
-     * （core 的 `checkRulesAndCache`），这一发一个字都不动它们 ——
-     * 撤销缓存的 deny ≠ 撤销规则的 deny，界面上必须说得清这一点，
+     * ⚠️ **它撤的只是缓存那一层**：两张规则表的 `deny` 排在缓存**前面**
+     * （core 的 `checkRulesAndCache`），这一发一个字都不动它们 —— 界面上必须说清，
      * 不然用户点了「撤销」发现还是被拦，比压根没有这个入口更坏。
      *
      * ⚠️ **撤销是把那道题还给用户，不是替他答成「允许」**：撤完之后同一个操作会
      * 重新弹窗。撤成放行的话，一次误点的代价会从「这个工具问不到」变成
-     * 「这个目标以后都不问了」—— 那个方向比原来的缺陷坏得多。
+     * 「这个目标以后都不问了」。
      *
-     * ⚠️ **没有「全清」那一档**（core 那边 `ApprovalCache.clear()` 一直都在，
-     * 刻意不转出来）：那一下会把用户攒了一整程的「总是允许」一起清掉，
-     * 于是「收回一个误点」的代价变成「后面每一次都重新问一遍」。
+     * ⚠️ **没有「全清」那一档**（core 的 `ApprovalCache.clear()` 一直都在，刻意
+     * 不转出来）：那一下会连用户攒了一整程的「总是允许」一起清掉。
      */
     revokeApproval?: (id: string) => {
         ok: boolean;
         reason?: ApprovalRevokeReason;
     };
     /**
-     * Plan 模式（方案 35）—— 用户主动那一半。
+     * Plan 模式 —— 用户主动那一半。
      *
      * **出口处那次审批不在这里**：它走的是既有的 `approval-request` 链
      * （`exit_plan_mode` 工具发起），TUI 接的还是 `run.requestApproval` 那一个队列。
@@ -787,33 +767,28 @@ interface HostActions {
         /** 主动退出，返回恢复到的级别；本来就不在模式里时回 null */
         leave: () => string | null;
         /**
-         * 当前生效的那份**已批准**计划；没有就是 null（方案 35 PR-2）。
+         * 当前生效的那份**已批准**计划；没有就是 null。
          *
-         * `/plan` 拿它回答「我刚才批的那份计划是什么」。这条在 `--resume` 之后
-         * 尤其要紧：屏幕上是空的（那张卡片是上一个进程画的），而模型手上那份还在
-         * —— 没有这个出口，用户无从知道自己接回来的会话正照着哪份纲跑。
+         * `/plan` 拿它回答「我刚才批的那份计划是什么」。`--resume` 之后尤其要紧：
+         * 屏幕上是空的（卡片是上一个进程画的），而模型手上那份还在 —— 没有这个出口，
+         * 用户无从知道自己接回来的会话正照着哪份纲跑。
          *
          * 可选：老宿主没实现时 `/plan` 少说一段，不该因此报「不可用」。
          */
         approvedPlan?: () => string | null;
     };
     /**
-     * 长任务的目标（方案 52）—— `/goal` 命令族的全部数据源。
-     *
-     * ## ⚠️ 为什么这一组回的是**渲染好的字符串**，而别的能力回结构
+     * 长任务的目标 —— `/goal` 命令族的全部数据源。
      *
-     * `checkpoints` 那一组回的是数据（TUI 自己画面板），这一组不是 —— 每个方法
-     * 回一句已经拼好的话。判据是 **i18n**：
+     * ## ⚠️ 这一组回的是**渲染好的字符串**，不是结构
      *
-     * `tui` 只依赖 protocol（见 `packages/tui/README.md` 的依赖表），够不着
-     * `@epoch-agent/infra` 的 `t()`，所以 TUI 里写的每一句中文都是硬编码的、
-     * 也就永远只有中文。这一片是**新增**的用户可见文案，把它硬编码进来等于给
-     * i18n 那条棘轮（`scripts/i18n-scan.mjs`，只许降不许升）再添一笔债。
+     * 判据是 **i18n**：`tui` 只依赖 protocol（见 `packages/tui/README.md` 的依赖表），
+     * 够不着 `@epoch-agent/infra` 的 `t()`，写进来的中文永远只有中文，而这一片
+     * 全是新增的用户可见文案，硬编码等于给 i18n 那条棘轮
+     * （`scripts/i18n-scan.mjs`，只许降不许升）再添一笔债。
      *
      * 所以措辞归宿主：cli 那侧用 `t()` 从 `locales/{zh,en}.yaml` 的 `goal.*` 取，
-     * TUI 只负责**解析子命令**和**把结果印出来**。这不是新发明的形状 ——
-     * `listPlugins` / `ManagedInfo` 早就是「宿主算好的展示形状」（见本文件
-     * import 那几行上的注释）。
+     * TUI 只负责**解析子命令**和**把结果印出来**。
      *
      * 整组可选：宿主没接（会话库起不来）时 `/goal` 压根不注册。
      */
@@ -844,18 +819,18 @@ interface HostActions {
         /**
          * 卡住时那一行开机提示；没卡住（或没有目标）时 null。
          *
-         * 宿主（`tui-entry`）把它接在 `startupNotices` 后面 —— 这是验收 8：
-         * 一个无人值守跑到一半卡住的任务，人回来打开 TUI 时**第一屏就该看见**
-         * 卡在哪，而不是要先想起来敲一条命令。
+         * 宿主（`tui-entry`）把它接在 `startupNotices` 后面：一个无人值守跑到一半
+         * 卡住的任务，人回来打开 TUI 时**第一屏就该看见**卡在哪，而不是要先想起来
+         * 敲一条命令。
          */
         blockedNotice: () => string | null;
     };
     /**
-     * 把一次「永久允许」渲染成可提交进 git 的规则字符串（方案 22 §2.7）。
+     * 把一次「永久允许」渲染成可提交进 git 的规则字符串。
      *
-     * 审批缓存是**本机的**、不进 git、换台机器就没了；规则是能提交的。
-     * 两者今天完全没有桥，用户想让规则生效只能自己去读文档猜语法。
-     * 反推不出有意义的规则时回 `null`（宿主据此不显示提示，而不是显示一条死规则）。
+     * 审批缓存是**本机的**、换台机器就没了；规则是能提交、全队生效的 —— 这一条
+     * 就是两者之间那座桥。反推不出有意义的规则时回 `null`（宿主据此不显示提示，
+     * 而不是显示一条死规则）。
      */
     suggestRule?: (request: ApprovalRequest) => {
         rule: string;
@@ -866,7 +841,7 @@ interface HostActions {
 interface PickerBase {
     title: string;
     /**
-     * 副标题。结构化提问（方案 34）拿它放「第 2/4 问 · 缓存后端」——
+     * 副标题。结构化提问拿它放「第 2/4 问 · 缓存后端」——
      * 四个问题逐个走完时，用户必须看得出「还有几个」，否则第二个弹窗出现的那一刻
      * 他会以为自己刚才点错了。
      */
@@ -874,7 +849,7 @@ interface PickerBase {
     options: Array<SelectOption<string>>;
     initialIndex?: number;
     /**
-     * 在列表末尾自动追加一个「其他…」，选中后就地敲字（方案 34 验收 3）。
+     * 在列表末尾自动追加一个「其他…」，选中后就地敲字。
      *
      * **由宿主提供而不是让调用方自己加一个选项**：那样每个调用方都得记得加，
      * 忘了的表现是用户答不上来只能按 Esc —— 而 Esc 的语义是「跳过」，
@@ -890,7 +865,7 @@ interface SinglePickerRequest extends PickerBase {
     /** 选中的 label；用户走自由输入时是他打的原文 */
     onPick: (value: string) => void;
 }
-/** 多选（方案 34 验收 2）。答案是数组，一项都没勾时是空数组 —— 那也是个合法答案 */
+/** 多选。答案是数组，一项都没勾时是空数组 —— 那也是个合法答案 */
 interface MultiPickerRequest extends PickerBase {
     multiSelect: true;
     onPick: (values: string[]) => void;
@@ -899,12 +874,11 @@ interface MultiPickerRequest extends PickerBase {
  * 选择框请求。
  *
  * 做成判别联合而不是「`onPick: (v: string | string[]) => void` 一把抓」：
- * 后者会让每个既有调用方（`/permission`、`/plugin`、`/resume`）都得在回调里
- * 先 `Array.isArray` 一次，而它们压根不可能收到数组。判别符让「这个框是几选」
- * 这件事在**声明处**就定死，回调的入参类型跟着自动收窄。
+ * 后者会让每个既有调用方都得在回调里先 `Array.isArray` 一次，而它们压根不可能
+ * 收到数组。判别符让「这个框是几选」在**声明处**就定死，回调入参跟着自动收窄。
  */
 type PickerRequest = SinglePickerRequest | MultiPickerRequest;
-/** 提交一条消息时的额外约束（方案 23：自定义命令可以收窄这一轮的工具表） */
+/** 提交一条消息时的额外约束：自定义命令可以收窄这一轮的工具表 */
 interface SubmitOptions {
     /**
      * 这一轮对模型可见的工具白名单。不给 = 不收窄。
@@ -914,7 +888,7 @@ interface SubmitOptions {
      */
     allowedTools?: readonly string[];
     /**
-     * 只在这一轮生效的模型（命令 frontmatter 的 `model:`，方案 26 验收 #9）。
+     * 只在这一轮生效的模型（命令 frontmatter 的 `model:`）。
      *
      * 和 `allowedTools` 同一个形状、同一条理由：解析（含 `utility` 关键字）在
      * 引擎侧做完了，TUI 只负责把它原样带到 `onRun`，还原也在那一侧无条件发生。
@@ -939,15 +913,15 @@ interface SlashCommandContext {
     /** 弹选择框 */
     pick: (req: PickerRequest) => void;
     /**
-     * 打开回退面板（方案 27 PR-3）。
+     * 打开回退面板。
      *
      * **没有走 `pick`**：那个是「从一组固定选项里选一个」，而回退是一台状态机 ——
      * 选检查点 → 逐个勾要覆盖的冲突文件 → 选范围 → 对话那半再确认一次不可撤销。
      * 用一串嵌套的 `pick` 拼出来，等于把「默认一个冲突都不覆盖」这条安全判定
      * 摊在四层回调里。
      *
-     * 和 `clear` / `exit` 同一个形状：面板的开关状态住在 `App`，命令只按门铃。
-     * Esc Esc 按的是同一个门铃 —— **一个面板，两个入口**。
+     * 面板的开关状态住在 `App`，命令只按门铃；Esc Esc 按的是同一个门铃 ——
+     * **一个面板，两个入口**。
      */
     openRewind: () => void;
     /**
@@ -959,11 +933,11 @@ interface SlashCommandContext {
      */
     approve: (request: ApprovalRequest) => Promise<ApprovalOutcome>;
     /**
-     * 把一段文本当成用户消息发出去（方案 23 的自定义命令走这条）。
+     * 把一段文本当成用户消息发出去（自定义命令走这条）。
      *
      * 内置命令一个都不用它 —— 它们是「在 TUI 里做一件事」，而自定义命令是
-     * 「替用户敲一段话」。两者共用同一个注册表但走不同的出口，这是刻意的：
-     * 命令**不是**新的 agent 类型，就是一次预置的 turn。
+     * 「替用户敲一段话」。两者共用同一个注册表但走不同的出口：命令**不是**新的
+     * agent 类型，就是一次预置的 turn。
      */
     submitPrompt: (text: string, opts?: SubmitOptions) => void;
     /** 宿主能力 */
@@ -998,7 +972,7 @@ interface SlashCommand {
     /** 别名，同样不带斜杠 */
     aliases?: string[];
     /**
-     * 给人看的称呼（自定义命令 frontmatter 的 `displayName`，2026-10-10）。
+     * 给人看的称呼（自定义命令 frontmatter 的 `displayName`）。
      * 内置命令不写。
      *
      * ⚠️ 终端里**左列照旧印 `/name`** —— 那是用户真要敲的东西，换成称呼等于让他
@@ -1023,8 +997,8 @@ interface SlashCommand {
      * 判据只看**宿主注入了哪些能力**，因为那是唯一「这台机器上到底有没有这个东西」
      * 的真源。缺能力时报一句「不可用」和压根不出现，是两件不同的事：
      * 前者适合「本该有、这次没起来」（`/tools` 在 provider 挂掉时仍该在），
-     * 后者适合「这个版本就没有这个功能」（方案 22 PR-4 之前的 `/permissions`）。
-     * 后者要是注册了，它会出现在 `/help` 和补全面板里 —— 那是在承诺一个不存在的功能。
+     * 后者适合「这个版本就没有这个功能」—— 注册了它就会出现在 `/help` 和补全
+     * 面板里，那是在承诺一个不存在的功能。
      */
     available?: (host: HostActions) => boolean;
     /**
@@ -1074,9 +1048,9 @@ interface ConfirmationRequest {
  * 跑一轮的入口。
  *
  * 入参是 `EpochUserContent`（`string | 部件数组`）而不是 `string`：Ctrl+V 粘进来的
- * 图片必须跟着这一次提交走到引擎。**不放宽成联合类型**是不行的 —— 历史项、
- * 队列、debug 日志全都只要文本，它们统一走 `contentToDisplayText()` 取投影
- * （**宿主那一份**，走 catalog；protocol 的 `contentToText()` 是给模型的，见 §14）。
+ * 图片必须跟着这一次提交走到引擎。历史项、队列、debug 日志全都只要文本，它们统一走
+ * `contentToDisplayText()` 取投影（**宿主那一份**，走 catalog；protocol 的
+ * `contentToText()` 是给模型的）。
  */
 type RunFn = (message: EpochUserContent, opts: {
     signal: AbortSignal;
@@ -1090,26 +1064,20 @@ interface AppProps {
     onExit?: () => void;
     /** 宿主注入的引擎能力，供斜杠命令使用 */
     host?: HostActions;
-    /** 宿主加载好的自定义斜杠命令（方案 23）。不给就只有内置那几条 */
+    /** 宿主加载好的自定义斜杠命令。不给就只有内置那几条 */
     customCommands?: readonly CustomCommandDef[];
     /**
-     * 生效的键位表（方案 31）。**必须是已经校验过的那一份** ——
-     * 读盘 / zod / 保留键 / 冲突检测都在宿主那一侧（`core/src/config/keybindings.ts`，
-     * 由 `cli/src/tui-entry.ts` 调），tui 只消费。
+     * 生效的键位表。**必须是已经校验过的那一份** —— 读盘 / zod / 保留键 / 冲突检测都在宿主
+     * 那一侧（`core/src/config/keybindings.ts`，由 `cli/src/tui-entry.ts` 调），tui 只消费。
      *
-     * 不给就是默认表，也就是「用户没配过」和「宿主不支持配」走同一条路 ——
-     * 行为与今天逐键一致。
+     * 不给就是默认表，也就是「用户没配过」和「宿主不支持配」走同一条路。
      */
     keybindings?: KeybindingTable;
     /**
-     * Vim 模式（方案 31 §2.6 / §4.3）。**默认关** —— 关着时输入框的行为与 PR-3
-     * 之前逐字节一致（#13）。
+     * Vim 模式。**默认关** —— 关着时输入框的行为与引入之前逐字节一致。
      *
-     * ⚠️ **今天没有任何宿主传它。** 开关的家按方案 §2.2 该在
-     * `~/.epoch/keybindings.json`（键位是个人偏好，只有用户级），而读那份文件的是
-     * `core/src/config/keybindings.ts`、把结果递进来的是 `cli/src/tui-entry.ts` ——
-     * PR-3 这一轮两个文件都归别的分支，所以只留了这个入口。接上那半只有两处一行的
-     * 改动，交接写在 `docs/verify/VERIFY_RECORD-31-keybindings.md` 的 PR-3 那一章。
+     * 开关的家在 `~/.epoch/keybindings.json`（键位是个人偏好，只有用户级），读它的是
+     * `core/src/config/keybindings.ts`，递进来的是 `cli/src/tui-entry.ts`。
      */
     vimMode?: boolean;
 }
@@ -1375,12 +1343,11 @@ declare function Banner({ width }: BannerProps): React__default.ReactElement;
  * 注册表。顺序即 /help 和补全面板的展示顺序。
  *
  * 按用途分了段：会话 → 引擎内省 → 仓库 → 回退 → 开关。后面几个分组住在各自的
- * 文件里（方案 25 PR-4 起），因为这个文件加完九条命令就会破 500 行的硬线。
+ * 文件里 —— 这个文件再加几条就会破行数硬线。
  *
- * ⚠️ 这份表是**全集**，不是「这台机器上能用的」。按宿主能力过滤发生在
- * `useSlashCommands` 合并那一步 —— 见 `availableCommands()`。
- * 保留名检查（方案 23）要的正是全集：一条命令这次没注册，
- * 不代表自定义命令就可以占用它的名字，否则升个版就撞名了。
+ * ⚠️ 这份表是**全集**，不是「这台机器上能用的」：按宿主能力过滤发生在
+ * `useSlashCommands` 合并那一步（`availableCommands()`）。而保留名检查要的正是全集
+ * —— 一条命令这次没注册，不代表自定义命令就可以占用它的名字，否则升个版就撞名了。
  */
 declare const BUILTIN_COMMANDS: readonly SlashCommand[];
 
@@ -1413,7 +1380,7 @@ declare function findCommand(commands: readonly SlashCommand[], name: string): S
  * `/` 单独一个字符时列出全部命令（用户刚敲下斜杠，正等着看有什么可用）。
  * 已经带了参数（有空格）时不再补全 —— 那时候用户在填参数，不该再弹列表。
  *
- * 称呼（`displayName`）也按前缀认（2026-10-10）：插件命令的名字是
+ * 称呼（`displayName`）也按前缀认：插件命令的名字是
  * `aione:bailing_daily_report` 这种，用户记得住的是「百灵投放日报」，打 `/百灵`
  * 该找得到它。⚠️ 同样是**前缀**不是子串，判据和名字那一支一致 —— 子串的话
  * `/c` 会捞出所有称呼里带个 c 的命令。web 那一份（`composer/commands.tsx`）逐字镜像。

package/dist/index.js

@@ -6733,17 +6733,13 @@ export {
 /**
  * InputBox — 自绘多行输入框，code-point 级光标，带斜杠命令补全。
  *
- * 光标是自绘的反色块，不是终端硬件光标：
- * ink 7 的 <Text> 没有 terminalCursorPosition 这类 prop（只有 useCursor() hook），
- * 之前用的那两个 prop 被 ink 静默忽略，所以输入框根本看不到光标。
- *
- * 这里用 Ink 原生的 <Text inverse>（而不是 chalk.inverse 拼 ANSI 字符串）：
- * chalk 有自己一套颜色能力探测，在非交互/被重定向的环境里会直接不输出转义序列，
- * 光标就又没了；走 Ink 的着色管线则和其余 UI 保持一致。
+ * 光标是自绘的反色块，不是终端硬件光标：ink 7 的 <Text> 没有 terminalCursorPosition
+ * 这类 prop，写上去会被静默忽略。而用 <Text inverse> 而不是 chalk.inverse 拼 ANSI
+ * 字符串，是因为 chalk 自己有颜色能力探测，非交互 / 被重定向的环境里不输出转义序列。
  *
  * 补全面板的键盘状态**必须**长在这里，不能提到 App：面板可见时 ↑↓ 要用来选命令，
- * 不可见时才是翻输入历史。这个判断只有握着 text buffer 的一方做得对，
- * 拆两处就会出现「两个 useInput 各消费一次同一个按键」。
+ * 不可见时才是翻输入历史。只有握着 text buffer 的一方判得对，拆两处就会出现
+ * 「两个 useInput 各消费一次同一个按键」。
  *
  * @license Apache-2.0 (adapted from google-gemini/gemini-cli)
  * Copyright 2025 Google LLC
@@ -6780,29 +6776,20 @@ export {
 /**
  * App — Ink TUI 根组件，状态来自 Context。
  *
- * 布局的关键约束（这也是之前花屏的根因）：
- * Ink 的 log-update 只能擦除它上一帧写过的行数。一旦动态帧比终端还高、内容滚出
- * 屏幕，擦除范围就对不上，屏幕上会残留重复行。所以：
+ * 布局的关键约束（花屏的根因）：Ink 的 log-update 只能擦除它上一帧写过的行数，一旦动态帧
+ * 比终端还高、内容滚出屏幕，擦除范围就对不上，屏幕上会残留重复行。所以：
  *   - Banner 和已完成历史必须放进 <Static>（只打印一次、向上滚走、不参与重绘）；
  *   - 只有 pending 区留在动态帧里，且必须按 availableHeight 限高。
  * 对齐 Gemini CLI 的 MainContent / DefaultAppLayout。
  *
  * 这个文件只做**装配和键位**：一轮对话怎么跑在 useAgentRun，斜杠命令怎么执行在
- * useSlashCommands。原来这三件事挤在一个 handleSubmit 里，改一处必然碰另两处。
- *
- * ## ⚠️ 这个文件大 —— **往这儿加东西之前先问一句能不能摘成 hook**
+ * useSlashCommands —— 两件事挤回一个 handleSubmit 的话，改一处必然碰另一处。
  *
- * 历次改动一直照这条走，而它确实压得住：方案 27 PR-3 把回退的状态机摘进
- * `hooks/use-rewind.ts`（形状同 `use-slash-commands`），净增收到 52 行；
- * 方案 31 PR-2 加序列时净增 **14 行**（状态机整台在
- * `keybindings/use-key-sequences.ts`，而 Esc Esc 那段特例反而删掉了）。
- * 真要把它拆小得动键位和布局那两块，那是独立的一件事，别顺手夹在别的 PR 里做。
- * 这条判据原来只写在方案 27 的 md 里，随那份 md 删除搬来。
+ * ## ⚠️ 往这儿加东西之前先问一句能不能摘成 hook
  *
- * ⚠️ **这一节原来的抬头是「破着铁律 3 的『单文件 ≤500 行』，而且是存量债」——
- * 2026-09-02 起那是假话，别再照它当欠账办。** 铁律 3 改成量**代码行**、线是 800，
- * 而这一份代码 635 行（`node scripts/code-lines.mjs`），**没过线**。
- * 上面那条「先摘 hook」是这个文件自己的纪律，不是在还谁的债。
+ * 「先摘 hook」是这个文件自己的纪律，不是在还债：摘出去净增的行数比塞进来少得多（回退那台
+ * 状态机在 `hooks/use-rewind.ts`，序列整台在 `keybindings/use-key-sequences.ts`）。真要把它
+ * 拆小得动键位和布局那两块，那是独立的一件事，别顺手夹在别的 PR 里做。
  *
  * @license Apache-2.0 (adapted from google-gemini/gemini-cli DefaultAppLayout)
  * Copyright 2025 Google LLC

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@epoch-agent/tui",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "private": false,
   "description": "epoch-agent Ink TUI 界面",
   "repository": {
@@ -29,8 +29,8 @@
     "mnemonist": "0",
     "string-width": "8",
     "strip-ansi": "7",
-    "@epoch-agent/protocol": "4.0.0",
-    "@epoch-agent/view": "4.0.0"
+    "@epoch-agent/protocol": "4.1.0",
+    "@epoch-agent/view": "4.1.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",