docs(i18n): proofread README translations 121-140

2026-07-29 15:29:38 +08:00
parent f6c8fe4dcb
commit 57b01e68d3
20 changed files with 193 additions and 193 deletions
@@ -1,15 +1,15 @@
-# spill/ - spill 存储功能家族
+# spill/ - spill 存储能力家族

 [English](README.md) | 中文

-工具输出 spill 的功能 seam：一个抽象存储接口、一个本地文件系统实现，以及一个使用该实现的工具结果策略。全部都是**产品** 包。
+工具输出 spill 的能力 seam：一个抽象存储接口、一个本地文件系统实现，以及一个使用该实现的工具结果策略。全部均为**产品**包（package）。

 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | `spill/` | 抽象 spill 存储 seam（`saveText`：持久化过大的工具文本，返回定位信息与取回指引） | `ctx.spillStore` |
-| `spill-local/` | 本地文件系统后端：使用防路径遍历名称的私有会话级文件 | （注册到 `ctx.spillStore`） |
+| `spill-local/` | 本地文件系统后端：名称可防止路径遍历的私有会话级文件 | （注册到 `ctx.spillStore`） |
 | `spill-policy/` | `tools/post-execute` 策略：将过大的纯文本结果替换为预览和 spill 定位信息 | （无服务接口） |

 接口位于 `spill/spill/`。这种拆分方式与 bash/fs 相同：seam 只负责存储，`spill-local` 负责文件系统机制，`spill-policy` 负责决定何时 spill 以及面向模型的通知。预览机制位于 [`util/retention`](../util/README.md)；策略只组合两者，不会让任何一方承担对方的职责。

-设计原理见[工具输出 spill Agent Note](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中说明了为什么最终结果 spill 要与工具自行提前 spill（bash 流、subagent rollout）分离，以及为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。
+设计原理见[工具输出 spill Agent Note（agent 决策记录）](../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中说明了为什么最终结果 spill 要与工具自行提前 spill（bash 流、subagent rollout）分离，以及为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。
@@ -2,33 +2,33 @@

 [English](README.md) | 中文

-[`@deepseek-ai/dsh-spill`](../spill) 存储 seam 的**本地文件系统** 实现。它注册为 `ctx.spillStore`，将工具过大的文本持久化到私有的会话级文件；定位信息是文件路径，取回指引会告诉模型对该路径使用 `read` 或 `grep`。
+[`@deepseek-ai/dsh-spill`](../spill) 存储 seam 的**本地文件系统**实现。它注册为 `ctx.spillStore`，将工具产生的过大文本持久化到私有的会话级文件；定位信息是文件路径，取回指引会告诉模型对该路径使用 `read` 或 `grep`。

 ## 存储布局

 文件存放在 `<root>/session-<hash>/<random>-<safeName>`：

- **`root`**：使用配置中的 `root`（解析为绝对路径）；如果省略，则在操作系统临时目录下延迟创建每进程私有（0700）目录。可预测且全球可读的根目录会让其他本地用户读取 spill 工具输出，或在其中预置符号链接。
- **`session-<hash>`**：短 `sha256(sessionId)` 前缀，用于将一个会话的 spill 文件归组，以便未来的清理操作可按会话删除。
- **`<random>-<safeName>`**：不可预测的十六进制前缀（防止在共享根目录中预置符号链接），加上经过清理的调用方 `suggestedName`，使其成为单个安全路径段（防路径遍历；与 JSONL 持久化后端的 `encodeSegment` 一致）。写入操作为排他且仅所有者可读写（`open(path, 'wx', 0o600)`）：如果路径已经存在，无论是否为符号链接，操作都会失败，因此预置的目标无法重定向写入。
+- **`root`**：使用配置中的 `root`（解析为绝对路径）；如果省略，则在操作系统临时目录下延迟创建每进程私有（0700）目录。可预测且任何用户均可读取的根目录会让其他本地用户读取 spill 工具输出，或在其中预置符号链接。
+- **`session-<hash>`**：截短的 `sha256(sessionId)` 前缀，用于将同一会话的 spill 文件归在一起，以便未来的清理操作可按会话删除。
+- **`<random>-<safeName>`**：不可预测的十六进制前缀（防止在共享根目录中预置符号链接），加上经过清理的调用方 `suggestedName`，使其成为单个安全路径段（防路径遍历；与 JSONL 持久化后端的 `encodeSegment` 一致）。写入操作采用排他方式，且权限仅限所有者（`open(path, 'wx', 0o600)`）：如果路径已经存在，无论是否为符号链接，操作都会失败，因此预置的目标无法重定向写入。

 ## 配置

 | 键 | 默认值 | 含义 |
 |---|---|---|
-| `root` | 私有 0700 临时目录 | spill 文件的根目录。进行设置可将它们保存在已知位置。 |
+| `root` | 私有 0700 临时目录 | spill 文件的根目录。设置后可将这些文件保存在已知位置。 |

-`saveText` 在发生真实存储故障（权限、ENOSPC）时拒绝；spill 策略会将该拒绝作为尽力而为的失败，并保留内联结果。词汇见 seam README，设计见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
+`saveText` 在发生真实存储故障（权限、ENOSPC）时返回拒绝；spill 策略会按尽力而为原则处理该拒绝，并保留内联结果。词汇见 seam README，设计见[工具输出 spill Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。

 ## 模型体验

 通过渲染本地路径以及 `read`/`grep` 取回指引的 spill 消费方间接影响模型。

-#### KV 缓存影响
+#### KV Cache 影响

-不直接导致失效；指定的消费方负责其引起的任何请求前缀变更。
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。

-## 已知限制与待完成工作
+## 已知限制与暂缓事项

 - **本地 spill 文件会持续存在，直到外部清理为止**：该后端不提供会话生命周期删除或按时间保留的策略，因为已持久化、已恢复和 fork 后的会话可能仍在引用某个路径。
 - **定位信息需要与其位于同一文件系统的消费方**：远程或虚拟部署需要另一个 `SpillStore` 后端，其定位信息和取回指引在该环境中有明确含义。
@@ -4,18 +4,18 @@

 **工具结果 spill 策略**：一个 `tools/post-execute` 转换器，用于防止过大的纯文本工具结果进入模型上下文。当最终结果超过 `maxInlineBytes` 时，它会通过 [`ctx.spillStore`](../spill) 保存完整文本，并将面向模型的结果替换为有界的首尾预览、后端定位信息与取回指引。

-该插件**不注册任何服务**，也不负责存储或预览机制：预览由 [`@deepseek-ai/dsh-retention`](../../util/retention) （`TextRetainer`）负责，存储由 `ctx.spillStore` 负责。它只决定何时 spill，并组合通知。
+该插件**不注册任何服务**，也不负责存储或预览机制：预览由 [`@deepseek-ai/dsh-retention`](../../util/retention)（`TextRetainer`）负责，存储由 `ctx.spillStore` 负责。它只决定何时 spill，并组合通知。

 ## 配置

 | 键 | 默认值 | 含义 |
 |---|---|---|
-| `maxInlineBytes` | *（省略）* | 面向模型的纯文本结果上下文上限，以 UTF-8 字节数计（在加载时验证为非负整数）。**省略时完全禁用该策略**（插件不注册任何内容）。设置后，较大的结果会被 spill，并替换为从同一预算派生的预览（首尾拆分）。 |
+| `maxInlineBytes` | *（省略）* | 面向模型的纯文本结果上下文上限，以 UTF-8 字节数计（在加载时验证为非负整数）。**省略时完全禁用该策略**（插件不注册任何内容）。设置后，超过该上限的结果会被 spill，并替换为从同一预算派生的预览（首尾拆分）。 |

 ## 行为

-1. 允许工具运行（通过 `next()` 委托，因此可以限制任何下游钩子接受的内容）。
-2. 跳过嵌套执行（存在 `exec.parent`——其持久副本由下方的 dispatch-log 分支设界）、已接受的值替换（注册表必须重新验证并渲染它们）、`read`（避免 `read → spill → read again` 循环）以及任何非 `accept` 决定（`block` 的纠正反馈会原样通过）。
+1. 允许工具运行（通过 `next()` 委托，因此可以限制任何下游钩子接受的结果）。
+2. 跳过嵌套执行（存在 `exec.parent`——其持久化副本由下方的 dispatch-log 分支设界）、已接受的值替换（注册表必须重新验证并重新渲染它们）、`read`（避免 `read → spill → read again` 循环）以及任何非 `accept` 决策（`block` 的纠正反馈会原样通过）。
 3. 仅在已接受的内容为**纯文本**（全部都是 `text` 块）时才将其展平；包含任何非文本块的结果都保持不变。
 4. 如果 UTF-8 大小为 `≤ maxInlineBytes`，则保持不变。
 5. 否则，保存完整文本，并将结果替换为预览和以下通知。系统会调整大小，使整个替换内容（预览、空行和通知）不超过 `maxInlineBytes`：先从预算中保留通知所需字节，再缩小预览以适配剩余空间，因此面向模型的结果绝不会超过上限：
@@ -28,13 +28,13 @@

   当通知本身已占满预算时（上限极小或定位信息很长），预览为空，只返回通知。如果仅通知的替换内容仍会超过 `maxInlineBytes`，策略将保留内联结果；它绝不会发出超过上限的替换内容（而且上限内的替换内容总比原结果更小，因此这也意味着 spill 绝不会增加字节数）。

-**尽力而为**：没有会话 owner、没有 `ctx.spillStore` 后端，或 `saveText` 拒绝 ⇒ 策略记录警告并返回原始结果。spill 失败绝不会将成功调用变为 `isError`，也不会隐藏内联结果。成功替换时只会更改 `content`；规范程序值保持不变。
+**尽力而为**：没有会话所有者、没有 `ctx.spillStore` 后端，或 `saveText` 返回拒绝 ⇒ 策略记录警告并返回原始结果。spill 失败绝不会将成功调用变为 `isError`，也不会隐藏内联结果。成功替换时只会更改 `content`；规范的程序化值保持不变。

-**dispatch-log 分支：**注册在 `tools/code-dispatch-log` 上的第二个监听器，把同一套上限、替换流水线与尽力而为的回退应用到每个 `run_code` 子调用结果的持久副本上（工件标签为 `dispatch`，按子调用 id 归档）。程序取得的值不受影响——它早已完整跨过 worker 边界；`read` 子调用同样设界：日志副本不是模型上下文，因此不会发生 read-again 循环，而 `read` 恰恰是最容易产生巨型日志的工具（[原理](../../../.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md)）。
+**dispatch-log 分支：**注册在 `tools/code-dispatch-log` 上的第二个监听器，把同一套上限、替换流水线与尽力而为的回退应用到每个 `run_code` 子调用结果的持久化副本上（产物标签为 `dispatch`，按子调用 id 归档）。程序的值不受影响，因为它早已完整跨过 worker 边界；`read` 子调用同样设界：日志副本不是模型上下文，因此不会发生 read-again 循环，而 `read` 恰恰是最容易产生巨型日志的工具（[原理](../../../.agents/notes/implemented/feature/2026-07-26-code-dispatch-log-spill.md)）。

 ## 范围

-该策略只能看到最终格式化接口结果，看不到工具的内部资源或规范值。如果提供方已经截断内容（例如 `web-fetch-local.maxBodyChars`），spill 产物保存的是工具返回的完整格式化结果，而非完整原始源。提供方/资源上限仍必须存在，并且与该策略分离。`glob`/`grep` 负责对项级接口结果执行 spill，因为渲染前仍然存在完整的已获取值；bash 流负责在获取时 spill。通用策略预先注册自己的 waterfall 监听器，然后再委托，因此无论插件加载顺序如何，普通工具拥有的异步投影都会在通用字节限制之前完成。详见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
+该策略只能看到最终格式化的呈现结果，看不到工具的内部资源或规范值。如果提供方已经截断内容（例如 `web-fetch-local.maxBodyChars`），spill 产物保存的是工具返回的完整格式化结果，而非完整原始源。提供方／资源上限仍然是必需的，并且与该策略相互独立。`glob`/`grep` 负责对项级呈现结果执行 spill，因为渲染前仍然存在完整的已获取值；bash 流负责在获取时 spill。通用策略预先注册自己的 waterfall（瀑布式事件）监听器，然后再委托，因此无论插件加载顺序如何，普通工具自身的异步投影都会在通用字节限制之前完成。详见[工具输出 spill Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。

 ## 模型体验

@@ -42,17 +42,17 @@

 #### 模型所见

-大小不超过 `maxInlineBytes` 的结果、嵌套结果、`read` 结果、已阻止的决定和包含非文本块的结果都保持不变。过大的纯文本接口结果会变为有界的首尾预览，后面附加 `(Omitted <bytes> bytes. Full formatted result stored at: <locator>. <retrievalHint>)`；存储或 owner 失败时，原始结果仍然可见。
+大小不超过 `maxInlineBytes` 的结果、嵌套结果、`read` 结果、被阻止的决策和包含非文本块的结果都保持不变。过大的纯文本呈现结果会变为有界的首尾预览，后面附加 `(Omitted <bytes> bytes. Full formatted result stored at: <locator>. <retrievalHint>)`；存储失败或没有会话所有者时，原始结果仍然可见。

 #### Token 影响

-成功替换后的内容最多为 `maxInlineBytes` 个 UTF-8 字节，并会保留在历史中直到压缩；完整 spill 文本不会重新发送给模型。
+成功替换后的内容最多为 `maxInlineBytes` 个 UTF-8 字节，并会保留在历史中直到压缩（compaction）；完整 spill 文本不会重新发送给模型。

-#### KV 缓存影响
+#### KV Cache 影响

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

-## 已知限制与待完成工作
+## 已知限制与暂缓事项

- **只能对最终纯文本结果执行 spill**：混合内容结果、阻止反馈和 `read` 会原样通过；无法在此恢复先前已经发生的提供方截断或工具自有保留。
+- **只能对最终纯文本结果执行 spill**：混合内容结果、阻止反馈和 `read` 会原样通过；无法在此恢复先前已经发生的提供方截断或工具自身执行的保留处理。
 - **通知无法容纳时，该次调用的替换功能会禁用**：当上限极小或定位信息很长时，后端已经保存了无引用的 spill，但过大的原始结果仍会保留在内联位置。
@@ -4,11 +4,11 @@

 **spill 存储 seam**：抽象的 `SpillStore` 服务（`ctx.spillStore`）定义 spill 后端做什么，即持久化某个工具过大的文本，并返回面向模型的定位信息与取回指引；它不规定如何实现。

-该包是 spill 功能的三个组成部分之一。拆分后，各项关注点可独立演进和替换：
+该包（package）是 spill 能力的三个组成部分之一。拆分后，各项关注点可独立演进和替换：

 | 包 | 职责 |
 |---|---|
-| `@deepseek-ai/dsh-spill` （本包） | 接口：抽象服务与词汇类型 |
+| `@deepseek-ai/dsh-spill`（本包） | 接口：抽象服务与词汇类型 |
 | `@deepseek-ai/dsh-spill-local` | 实现：位于宿主文件系统中的私有会话级文件 |
 | `@deepseek-ai/dsh-spill-policy` | 对过大最终结果执行 spill 的工具结果策略 |

@@ -18,25 +18,25 @@

 | 成员 | 语义 |
 |---|---|
-| `saveText(input)` | 逐字保存 `input.content`；解析并返回 `SpillRef`（不透明定位信息、写入的精确字节数和取回指引）。如果出现真实存储故障（权限、ENOSPC、后端不可用），则**拒绝**；由调用方决定如何降级。 |
+| `saveText(input)` | 逐字保存 `input.content`；成功时返回 `SpillRef`（不透明定位信息、写入的精确字节数和取回指引）。**如果出现真实存储故障，则返回拒绝**（权限、ENOSPC、后端不可用）；由调用方决定如何降级。 |

 存储操作以请求的 `owner` 会话作为保存时命名空间进行分组；后端自行选择私有表示，并可以从调用方的 `suggestedName` 派生名称，但绝不能将其当作可信路径。该 seam 只负责存储：不提供保留策略（由 [`@deepseek-ai/dsh-retention`](../../util/retention) 负责），不替换工具结果（由 `@deepseek-ai/dsh-spill-policy` 负责），也不提供取回/搜索 API（后端的 `retrievalHint` 会告诉模型如何使用定位信息）。

 ## 词汇

-`SaveTextSpill` （owner、source、suggestedName、content）是请求；`SpillRef` （locator、bytes、retrievalHint）是结果。`SpillLocator` 已经[品牌化](../../util/brand)，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略/工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource` （toolName、callId、label）是供后端命名和检查使用的描述性来源信息，而非访问控制信息。完整契约见 `src/types.ts`。
+`SaveTextSpill`（owner、source、suggestedName、content）是请求；`SpillRef`（locator、bytes、retrievalHint）是结果。`SpillLocator` 是[带品牌类型](../../util/brand)的值，并以不透明字符串的形式呈现给模型；对 `dsh-spill-local` 而言它是本地路径，但未来的后端可以返回 URI、键或命令 token，无需修改策略／工具消费方。`SpillOwner.sessionId` 是保存时存储命名空间：fork 后的会话会从种子日志继承现有定位信息，无需复制文件或更改其归属；fork 后新产生的 spill 使用子会话 id。`SpillSource`（toolName、callId、label）是供后端命名和检查使用的描述性来源信息，而非访问控制信息。完整契约见 `src/types.ts`。

-设计原理见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中说明了为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。
+设计原理见[工具输出 spill Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)，其中说明了为什么创建操作应由运行时 spill seam 而非面向模型的 `write` 工具承担。

 ## 模型体验

 通过渲染后端定位信息和取回指引的 spill 消费方间接影响模型。

-#### KV 缓存影响
+#### KV Cache 影响

-不直接导致失效；指定的消费方负责其引起的任何请求前缀变更。
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。

-## 已知限制与待完成工作
+## 已知限制与暂缓事项

 - **该 seam 没有取回或删除 API**：消费方只能渲染后端的定位信息与指引；生命周期和访问语义仍由后端自行决定。
 - **存储不等于访问控制**：`SpillOwner` 会区分写入命名空间，但不会授予定位信息的读取权限；每个后端和取回消费方都必须自行强制执行访问边界。