Merge origin/master at ecbf75a5e7 into skill catalog hot refresh

2026-07-29 21:42:18 +08:00
parent 52d68a5383 e10bf246fb
commit 502e64c00d
422 changed files with 5585 additions and 2063 deletions
--- a/packages/ui/README.i18n.yaml
+++ b/packages/ui/README.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
+#   pnpm run verify-translation-pairing --write packages/ui/README.md
 README.md: f08157d411a018141cdc21c487f81ae198f4de56
-README.zh.md: d321ee9a181eb27ccecb143d3733ee46e417b27f
+README.zh.md: ed4fbf576224a61e680fca337ac5e60829f8a90e
--- a/packages/ui/README.zh.md
+++ b/packages/ui/README.zh.md
@@ -2,21 +2,21 @@

 [English](README.md) | 中文

-面向用户的交互通道和进程外 SDK 服务器。这些是**产品** 包（package）：由用户或 SDK 客户端直接操作的真实接口。
+面向用户的交互通道和进程外 SDK 服务器。这些是**产品**包（package）：由用户或 SDK 客户端直接操作的真实接口。

 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | `commands/` | 用户命令注册表：共享发现元数据、作用域遮蔽、取消以及 UI 直接分派 | `ctx.commands` |
 | `user-approval/` | 一次性用户审批机制、封闭的结果词汇、审计事件和逐会话审批策略 | `ctx.approval` |
-| `permission/` | 面向用户的权限预设（`workspace-write`/`danger-full-access`）：用一个产品级选择器组合沙箱模式与审批策略两个调节项，并写入各自的会话事件 | `ctx.permission` |
+| `permission/` | 面向用户的权限预设（`workspace-write`/`danger-full-access`）：通过一项产品级选择组合沙箱模式与审批策略两个可调参数，并写入各自的会话事件 | `ctx.permission` |
 | `user-interaction/` | UI 支持的确认工具所使用的抽象用户问答 seam | `ctx.userInteraction` |
 | `tool-ask-user/` | 模型侧 `ask_user_question` 工具，基于 `ctx.userInteraction` 实现 | （注册到 `ctx.tools`） |
 | `tui/` | 交互式 pi-tui 终端通道：渲染会话标题、事件和工具意图，响应 `ctx.userInteraction`，并托管由 effect 持有的插件浮层 | `ctx.tui`（驱动 `ctx.agents`） |
 | `jsonrpc/` | 面向进程外 SDK 客户端的 stdio JSON-RPC 服务器 | （驱动 `ctx.agents`） |
-| `app-boot/` | app bin 的共享启动粘合层：加载 `.env`、Loader 快速失败保护、感知快照的配置解析，以及等待整棵树停稳的启动序列 | （供各 bin 使用的库） |
+| `app-boot/` | app bin 的共享启动粘合层：加载 `.env`、会明确报错的 Loader 保护机制、感知快照的配置解析，以及等待整棵树停稳的启动序列 | （供各 bin 使用的库） |

-UI 集成属于客户端驱动插件，而非对循环的修改：它使用现有的 `agent/*` 事件分类和 `dsh-agent` 工厂。[`tui`](tui/README.md) 是交互式终端入口，并提供终端本地的 `ctx.tui` 扩展服务；[`jsonrpc`](jsonrpc/README.md) 为进程外 SDK 客户端提供服务，而非交互式单次任务使用 `cli-demo`。[`commands`](commands/README.md) 是 TUI 使用的纯用户发现与分派通道；命令输入和输出不会成为模型消息。
+UI 集成属于由客户端驱动的插件，而非对循环的修改：它使用现有的 `agent/*` 事件分类和 `dsh-agent` 工厂。[`tui`](tui/README.md) 是交互式终端入口，并提供终端本地的 `ctx.tui` 扩展服务；[`jsonrpc`](jsonrpc/README.md) 为进程外 SDK 客户端提供服务，非交互式的一次性任务则使用 `cli-demo`。[`commands`](commands/README.md) 是 TUI 使用的仅面向用户的发现与分派通道；命令输入和输出不会成为模型消息。

-`user-approval`、`user-interaction` 和 `tool-ask-user` 位于此处，因为向用户提问是由 UI 支持的产品功能，并不属于提供方无关的核心主干。`user-approval` 持有一次性的 `ctx.approval` 决策机制及其策略层级；应答方仍归拥有 agent（智能体）的通道或自动化传输层所有。`user-interaction` 保持提供方无关（`ctx.userInteraction`），`tool-ask-user` 是其模型侧消费方，而交互式 app 包提供具体实现。
+`user-approval`、`user-interaction` 和 `tool-ask-user` 位于此处，因为向用户提问是由 UI 支持的产品功能，并不属于无提供方的核心主干。`user-approval` 负责一次性的 `ctx.approval` 决策机制及其策略层级；应答逻辑仍由负责 agent（智能体）的通道或自动化传输层提供。`user-interaction` 保持提供方无关（`ctx.userInteraction`），`tool-ask-user` 是其模型侧消费方，而交互式 app 包提供具体的提供方。

-基于 [`agent-spine-demo`](../examples/agent-spine-demo/README.md) 组合的可运行 app bundle 位于 [`examples/`](../examples/README.md)（`tui-demo`、`acp-demo`、`jsonrpc-demo`）。`acp-demo` 和 `jsonrpc-demo` 持有启动 bin；`tui-demo` bundle 则由产品 [`dsh`](../../apps/cli/README.md) CLI 启动。`ui/` 保留可复用的用户／SDK 通道插件和共享 `app-boot` 粘合层；仅供自动化使用的 ACP 传输层位于 [`acp/`](../acp/README.md)。每个入口都持有自己的 stdout 策略，叶子 `cordis.yml` 则提供后端与可选工具。
+基于 [`agent-spine-demo`](../examples/agent-spine-demo/README.md) 组合的可运行 app bundle 位于 [`examples/`](../examples/README.md)（`tui-demo`、`acp-demo`、`jsonrpc-demo`）。`acp-demo` 和 `jsonrpc-demo` 各自提供启动 bin；`tui-demo` bundle 则由产品 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）启动。`ui/` 保留可复用的用户／SDK 通道插件和共享 `app-boot` 粘合层；仅供自动化使用的 ACP（Agent Client Protocol）传输层位于 [`acp/`](../acp/README.md)。每个入口都负责自己的 stdout 策略，叶子 `cordis.yml` 则提供后端与可选工具。
--- a/packages/ui/commands/README.i18n.yaml
+++ b/packages/ui/commands/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/ui/commands/README.md
 README.md: 4ad72cf9e232c8d41e525f42eecde5637032a391
-README.zh.md: bace8f6346ac737a838d802dfc5c6ffe52c56edd
+README.zh.md: 9cc6a3f31e55da5d56c5b49ba78fbd66381ed680
--- a/packages/ui/commands/README.zh.md
+++ b/packages/ui/commands/README.zh.md
@@ -2,17 +2,17 @@

 [English](README.md) | 中文

-由插件拥有、供交互式 UI 适配器使用的面向用户命令注册表。[插件命令注册 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md)定义了其边界与分发契约。
+由插件负责、供交互式 UI 适配器使用的面向用户命令注册表。[插件命令注册 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/feature/2026-07-19-plugin-command-registration.md)定义了其边界与分发契约。

 ## 服务契约

-`ctx.commands.register(definition)` 注册一个小写命令名称、描述、可选的非结构化输入提示，以及可中止的处理器。每个已注册命令都可供所有已组合的命令适配器使用；与某项部署不兼容的插件不会在此注册。普通上下文中的注册全局生效。在 `agent.ctx` 下挂载的命令生产插件会声明自身的 `commands` 注入，并创建精确限定到该 agent 的定义；该定义会遮蔽同名的全局定义。这种子级注入形态保留了 agent 作用域，同时不会让核心 agent loop 依赖 UI 服务。同一层中的名称重复会在注册时失败。每个 disposer 都是 Cordis effect 返回的确切 disposer；注册或移除命令时，系统会通知每个 `commands/change` 观察者，使实时适配器能够刷新发现结果。观察者失败会写入日志，既不能否决注册表变更，也不能阻止后续观察者运行。
+`ctx.commands.register(definition)` 注册一个小写命令名称、描述、可选的非结构化输入提示，以及可中止的处理器。每个已注册命令都可供所有已组合的命令适配器使用；与某项部署不兼容的插件不会在此注册。普通上下文中的注册全局生效。在 `agent.ctx` 下挂载的命令生产插件会声明自身的 `commands` 注入，并创建精确限定到该 agent（智能体）的定义；该定义会遮蔽同名的全局定义。这种子级注入形态保留了 agent 作用域，同时不会让核心 agent loop（智能体循环）依赖 UI 服务。同一层中的名称重复会在注册时失败。每个 disposer 都是 Cordis effect 返回的确切 disposer；注册或移除命令时，系统会通知每个 `commands/change` 观察者，使运行中的适配器能够刷新发现结果。观察者失败会写入日志，既不能否决注册表变更，也不能阻止后续观察者运行。

-`list(agent)` 在应用作用域遮蔽后，返回按名称排序的不可变描述符。`find(agent, name)` 返回相应定义。`execute(agent, line, signal)` 使用 `parseCommand()`，且只运行已知命令，返回已结算的 `CommandExecution`（规范化结果加生命周期配对 `commandId`）；语法无效或名称未知时返回 `undefined`。已解析命令的生命周期会以 log-only 事件对的形式记录在接收 agent 的会话日志中：`command/run`（进入处理器前记录，携带铸造的 `commandId`、解析器的结构化 `name`/`args` 切分和发起方 `CommandSource`）与 `command/done`（结算时记录，携带结局种类与原样文本；处理器抛出或被中止时以 `kind: 'error'` 结算）。未通过准入的输入不记录任何事件。两者都是直接独立追加：没有轮次包裹它们，持久化在常规检查点与 teardown 时排空它们。
+`list(agent)` 在应用作用域遮蔽后，返回按名称排序的不可变描述符。`find(agent, name)` 返回相应定义。`execute(agent, line, signal)` 使用 `parseCommand()`，且只运行已知命令，返回已结算的 `CommandExecution`（规范化结果加生命周期配对 `commandId`）；语法无效或名称未知时返回 `undefined`。已解析命令的生命周期会以 log-only 事件对的形式记录在接收 agent 的会话日志中：`command/run`（进入处理器前记录，携带新生成的 `commandId`、解析器的结构化 `name`/`args` 切分和发起方 `CommandSource`）与 `command/done`（结算时记录，携带结果类型与原样文本；处理器抛出或被中止时以 `kind: 'error'` 结算）。未通过准入的输入不记录任何事件。两者都直接独立追加到接收 agent 的会话中：没有轮次包裹它们，持久化机制会在常规检查点和销毁期间排空这些事件。

-`parseCommand()` 识别位于字节零位置的斜杠、由小写字母、数字、`_` 或 `-` 构成的名称，以及名称后紧接输入末尾或空白的形式。它将名称后的每个字节作为 `rawInput` 返回，其中包括分隔空白；消费方拥有各命令专用的语法，只能执行该语法允许的规范化。
+`parseCommand()` 识别位于第 0 字节的斜杠、由小写字母、数字、`_` 或 `-` 构成的名称，以及名称后紧接输入末尾或空白的形式。它将名称后的每个字节作为 `rawInput` 返回，其中包括分隔空白；消费方负责各命令专用的语法，只能执行该语法允许的规范化。

-处理器返回 `success` 或 `error`，并可附带 UI 文本。适配器直接渲染结果，结果绝不进入模型历史。注册表绝不会隐式地把 `rawInput` 提交给 agent；命令生产方可以通过接收命令的 `Agent` 显式安排模型可见工作，此时该生产方拥有由此产生的消息契约。注册表会让处理器完成与所提供的中止信号竞速，但不协作的处理器可能在调用方停止等待后继续产生自身的外部副作用。
+处理器返回 `success` 或 `error`，并可附带 UI 文本。适配器直接渲染结果，结果绝不进入模型历史。注册表绝不会隐式地把 `rawInput` 提交给 agent；命令生产方可以通过接收命令的 `Agent` 显式安排模型可见工作，此时该生产方负责由此产生的消息契约。注册表会同时等待处理器完成和所提供的中止信号，以先发生者为准，但不响应中止的处理器可能在调用方停止等待后继续产生自身的外部副作用。

 ## 组合

@@ -32,9 +32,9 @@

 #### KV Cache 影响

-注册表元数据、命令输入和直接输出绝不会进入模型请求，也不会影响其缓存。被命令变更的领域拥有之后产生的所有缓存影响。
+注册表元数据、命令输入和直接输出绝不会进入模型请求，也不会影响其缓存。发生变更的领域负责之后产生的所有缓存影响。

-## 已知限制与延期工作
+## 已知限制与暂缓事项

 - **仅支持非结构化文本输入**：表单、补全 schema 和类型化参数仍由各命令自行解析。
 - **副作用采用协作式取消**：中止后，分发会停止等待；处理器必须遵循信号，才能停止已经进入外部系统的工作。
--- a/packages/ui/jsonrpc/README.i18n.yaml
+++ b/packages/ui/jsonrpc/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/ui/jsonrpc/README.md
 README.md: b1219ba10269fc7d046da22c280ff1b91424a5ae
-README.zh.md: 63615654769bf4ed7a69c09dc818af034c3a3c3c
+README.zh.md: 1c27f5edf2f1f172aa6303697b17e2e77a65842a
--- a/packages/ui/jsonrpc/README.zh.md
+++ b/packages/ui/jsonrpc/README.zh.md
@@ -2,11 +2,11 @@

 [English](README.md) | 中文

-`jsonrpc` 插件通过 stdio 提供以换行符分隔的 JSON-RPC，使进程外 SDK 客户端能够驱动 harness agent（智能体）。[`HarnessSdkServer`](src/server.ts) 持有协议方法和通知；传输与具名线类型位于 [`dsh-sdk-protocol`](../../sdk/sdk-protocol/README.md)，与客户端 SDK 共享；[`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) 提供外围的 `cordis.yml` 应用。
+`jsonrpc` 插件通过 stdio 提供以换行符分隔的 JSON-RPC，使进程外 SDK 客户端能够驱动 harness agent（智能体）。[`HarnessSdkServer`](src/server.ts) 负责协议方法和通知；传输与具名协议类型位于 [`dsh-sdk-protocol`](../../sdk/sdk-protocol/README.md)，与客户端 SDK 共享；[`jsonrpc-demo`](../../examples/jsonrpc-demo/README.md) 提供外围的 `cordis.yml` 应用。

 ## 组装

-`inject: ['agents']`。服务器按 `sessionId` 获取或创建一个 agent。只有服务建立快照时的生命周期 `local` 标志为 true，服务器才会转发 subagent 完成事件；提供方名称、子级 id 和持久化谱系均不能证明本地性。已注册的适配器优先；未被持有的 `deepseek` 路由会挂载 `dsh-llm-deepseek`，任何其他未被持有的提供方都会导致初始化失败。其他功能由外围 `cordis.yml` 提供。
+`inject: ['agents']`。服务器按 `sessionId` 获取或创建一个 agent。只有服务对生命周期建立快照时记录的 `local` 标志为 true，服务器才会转发 subagent 完成事件；提供方名称、子级 id 和持久化谱系均不能证明本地性。已注册的适配器优先；尚无适配器负责的 `deepseek` 路由会挂载 `dsh-llm-deepseek`，任何其他尚无适配器负责的提供方都会导致初始化失败。其他功能由外围 `cordis.yml` 提供。

 ## 配置

@@ -40,7 +40,7 @@ Stdout 只承载 JSON-RPC 帧。部署不得组合 stdout logger；诊断应写

 仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。

-## 已知限制与延期工作
+## 已知限制与暂缓事项

 - **协议没有逐会话关闭或提示词取消方法**：SDK 创建的 agent 会一直存活到进程关闭；一条已接受的提示词必须运行到 agent 空闲，该会话才能接受下一条。
 - **stdout 纯净性由部署保证**：外围配置仍可能加载 stdout logger 并破坏 JSON-RPC 通道；此插件不会检查或否决同级 logger。
--- a/packages/ui/tool-ask-user/README.i18n.yaml
+++ b/packages/ui/tool-ask-user/README.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
+#   pnpm run verify-translation-pairing --write packages/ui/tool-ask-user/README.md
 README.md: 8e779f4025c20cd200344efb7cb8cd6bc09ba64d
-README.zh.md: fe1dc5559882532c4f44e705cc6daa2c7f4f8905
+README.zh.md: acaffec0764404a0e0e842ffc2b4efdee8869c4f
--- a/packages/ui/tool-ask-user/README.zh.md
+++ b/packages/ui/tool-ask-user/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-模型侧 `ask_user_question` 工具，基于 `ctx.userInteraction` 实现。当模型需要确认、选择或缺失信息才能继续时，它可以借此向用户提出简明问题。
+模型侧 `ask_user_question` 工具，基于 `ctx.userInteraction` 实现。当模型需要确认、选择结果或缺失的信息才能继续时，它可以借此向用户提出简明问题。

 ## 工具

@@ -15,7 +15,7 @@
 - `options`：可选选项，包含 `label` 和 `description`。如需推荐某个选项，请将其置于首位，并在该标签末尾追加 `(Recommended)`。
 - `multi_select`：该问题是否可以返回多个选中的选项。

-工具调用 `ctx.userInteraction.ask()`，并返回规范的 `{ answers: [{ id, selected, custom? }] }`。`selected` 包含选项标签；仅当用户自由填写回答时才会出现 `custom`，并覆盖选中的选项。Native renderer 会保留紧凑的 JSON 文本形式 `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`。
+工具调用 `ctx.userInteraction.ask()`，并返回规范的 `{ answers: [{ id, selected, custom? }] }`。`selected` 包含选项标签；仅当用户自由填写回答时才会出现 `custom`，并覆盖选中的选项。Native 渲染器会保留紧凑的 JSON 文本形式 `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`。

 ## 职责

@@ -31,17 +31,17 @@

 #### Token 影响

-工具可见的每个请求都会产生固定的 schema 开销。
+工具可见时，每个请求都会产生固定的 schema token 开销。

 #### KV Cache 影响

-只要定义和可见性保持不变，前缀即可稳定复用。插件生命周期变化或作用域限制可能从此 schema 开始使复用失效。
+只要定义和可见性保持不变，前缀即可稳定复用。插件生命周期变化或作用域限制可能会使从此 schema 起的缓存复用失效。

 ### 工具调用历史与结果

 #### 模型看到的内容

-模型提出的完整问题保留在 assistant 工具调用参数中。用户回答后，下一步骤会看到精确采用 `{"answers":[{"id":"<id>","selected":["<label>"],"custom":"<text>"}]}` 形式的紧凑 JSON；不使用 `custom` 时会省略该字段，`selected` 可以包含零个、一个或多个标签。调用等待期间的 UI 交互不属于模型上下文。
+模型提出的完整问题保留在 assistant 工具调用参数中。用户回答后，下一步会看到精确采用 `{"answers":[{"id":"<id>","selected":["<label>"],"custom":"<text>"}]}` 形式的紧凑 JSON；不使用 `custom` 时会省略该字段，`selected` 可以包含零个、一个或多个标签。调用等待期间的 UI 交互不属于模型上下文。

 #### Token 影响

@@ -51,7 +51,7 @@

 仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。

-## 已知限制与延期工作
+## 已知限制与暂缓事项

 - **待处理问题会阻塞工具调用，直至用户作答**：该工具未声明 `timeout-policy` 预算；取消仅沿用当前轮次的 `exec.signal`。
 - **Native 回答渲染为 JSON 文本**：规范值仍为结构化数据，但模型侧结果使用紧凑 JSON，而非更丰富的内容块词汇。
--- a/packages/ui/user-approval/README.i18n.yaml
+++ b/packages/ui/user-approval/README.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
+#   pnpm run verify-translation-pairing --write packages/ui/user-approval/README.md
 README.md: 38bcfbfe81c3ff5f16d1835259bd4c35a06dcb64
-README.zh.md: 2a3a6d08d66c70a22b3a23a2341efc0452b8a782
+README.zh.md: 7f2678d8572b191ec88a326374420dde7deed3dc
--- a/packages/ui/user-approval/README.zh.md
+++ b/packages/ui/user-approval/README.zh.md
@@ -4,9 +4,9 @@

 与通道无关的一次性审批 seam。`ctx.approval.request(req)` 返回 `allowed-once`、`rejected`、`cancelled` 或 `unavailable`；应答者缺失或失败时会以拒绝方式关闭，授权也只适用于所请求的操作。确切事件签名见生成的 [Cordis 目录](../../../docs/cordis-catalog/events.md)。

-每个请求都必须属于一个打开的 agent（智能体）轮次。服务会追加一对 `approval/asked` 与 `approval/decided` 审计记录，而模型只会看到由此产生且已写入日志的工具结果。已中止的请求会 resolve 为 `cancelled`；如果审计追加在提交前失败，请求会被拒绝，而不会返回一项未记录的决定。
+每个请求都必须属于一个尚未结束的 agent（智能体）轮次。服务会追加一对 `approval/asked` 与 `approval/decided` 审计记录，而模型只会看到由此产生且已写入日志的工具结果。已中止的请求会解析为 `cancelled`；如果审计记录的追加在提交前失败，Promise 会被拒绝，而不会返回一项未记录的决定。

-应答者是 `approval/request` waterfall（瀑布式事件）监听器。要回答所拥有 agent 的请求，请返回一个结果；否则调用 `next()` 委托。限定到 agent 的监听器只接收该 agent 的请求；每项部署应当组合一个终端应答者，因为同级监听器的顺序不是策略优先级机制。ACP（Agent Client Protocol）自动化桥接层为其拥有的会话提供一次性机器决定。
+应答者是 `approval/request` waterfall（瀑布式事件）监听器。要回答其负责的 agent 请求，请返回一个结果；否则调用 `next()` 委托。限定到 agent 的监听器只接收该 agent 的请求；每项部署应当组合一个最终应答者，因为同级监听器的顺序不是策略优先级机制。ACP（Agent Client Protocol）自动化桥接层为其负责的会话提供一次性机器决定。

 `ApprovalPolicy` 为 `'ask'` 或 `'never'`。实际值取最后一条 `approval/policy` 事件，并回退到配置；`setApprovalPolicy()` 是写入路径。`'never'` 会在交互式分发之前拒绝请求，也是提示词中唯一声明的策略。切换最多产生一条合并通知：如果覆盖发生在最后一个 `request/header` 之后，则归因于用户；否则归因于操作方／配置。

@@ -49,15 +49,15 @@ Approval prompts are disabled in this session: actions that require approval are

 #### Token 影响

-不会产生重复的审计 token。拒绝可能以一条少量且保留的错误替换正常工具结果，而允许会保留消费方的普通结果。
+不会产生重复的审计 token。拒绝可能以一条简短且会保留的错误信息替换正常工具结果，而允许会保留消费方的普通结果。

 #### KV Cache 影响

 仅追加；新出现的可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。

-## 已知限制与延期工作
+## 已知限制与暂缓事项

- **请求只在打开的轮次内有效**：空闲时或轮次之间的调用方会在审计前抛出异常；持久化的轮次外审批工作流仍属延期事项。
- **仅存在一次性授权**：结果词汇包含 `allowed-once`，但不含 `allow-always`、记忆规则、撤销或授权存储；会话策略只有 `ask`／`never`。
+- **请求只在尚未结束的轮次内有效**：在空闲时或轮次之间发起调用，会在审计前抛出异常；持久化的轮次外审批工作流仍属暂缓事项。
+- **仅存在一次性授权**：结果词汇包含 `allowed-once`，但不含 `allow-always`、已记住的规则、撤销或授权存储；会话策略只有 `ask`／`never`。
 - **请求不携带工具参数**：应答者会看到工具名称、原因和可选调用 id；ACP 机器通道要求调用 id，并会委托不含 id 的请求。
 - **没有内置应答者**：无头或组合不完整的部署会 resolve 为 `unavailable` 并以拒绝方式关闭；服务自身绝不会提示人类。
--- a/packages/ui/user-interaction/README.i18n.yaml
+++ b/packages/ui/user-interaction/README.i18n.yaml
@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
+#   pnpm run verify-translation-pairing --write packages/ui/user-interaction/README.md
 README.md: d234d6677bdd772f1bbd2c979c0d41f90aef5c32
-README.zh.md: b70a61d6491e0bb0e52215cdeaeea3d728f7f153
+README.zh.md: c89210b6955a661313ca9e0e82e43da5a4d1db79
--- a/packages/ui/user-interaction/README.zh.md
+++ b/packages/ui/user-interaction/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-抽象用户交互 seam。它拥有 `ctx.userInteraction`：当面向模型的工具或权限插件需要暂停工作并询问人类决定时所使用的服务。
+抽象用户交互 seam。它定义 `ctx.userInteraction`，供面向模型的工具或权限插件在需要暂停工作并询问人类决定时使用。

 ## 服务：`UserInteractionService`（ctx 键：`userInteraction`）

@@ -19,7 +19,7 @@
 - `UserInteractionProvider`：包含 `ask(request)` 的 UI 实现。
 - `UserInteractionError`：`HarnessError` 的子类，包含 `EMPTY_QUESTIONS`、`NO_PROVIDER`、`DUPLICATE_PROVIDER` 和 `ASK_ABORTED` 等代码。

-当回答包含 `custom` 时，`selected` 为空；自定义文本会覆盖所选选项，而不是补充它们。UI 可以把跳过的条目保留为 `{ id, selected: [] }`，既维持现有回答形态，也保留该批次中的其他回答。
+当回答包含 `custom` 时，`selected` 为空；自定义文本是所选选项的替代，而不是补充。UI 可以把跳过的条目保留为 `{ id, selected: [] }`，既维持现有回答形态，也保留该批次中的其他回答。

 ## 职责

@@ -31,9 +31,9 @@

 #### KV Cache 影响

-不会直接使缓存失效；具名消费方拥有所有请求前缀变更。
+不会直接使 KV Cache 失效；请求前缀的任何变更均由上述消费方负责。

-## 已知限制与延期工作
+## 已知限制与暂缓事项

 - **每个上下文只能有一个提供方**：不支持路由或扇出到多个 UI；第二次注册会抛出 `DUPLICATE_PROVIDER`，未注册任何提供方时，`ask()` 会抛出 `NO_PROVIDER`，而不会降级。
- **词汇仅包含问题表单形态**：可选选项加可选自定义文本；更丰富的交互形态（文件选择器、diff 预览确认）尚无 seam 词汇。
+- **词汇仅包含问题表单形态**：可供选择的选项加可选的自定义文本；更丰富的交互形态（文件选择器、diff 预览确认）尚无 seam 词汇。