docs: translate remaining READMEs

2026-07-26 05:03:53 +08:00
parent 37bfac749b
commit 226dc7a249
559 changed files with 11227 additions and 1 deletions
@@ -0,0 +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
+README.md: 2270a65d9270e1549a9e48d6a36b821e48c29070
+README.zh.md: 2c5cd901d5a35e2129b7908082b6bc5e2b53be64
@@ -1,5 +1,7 @@
 # @deepseek-ai/dsh-spill-local

+English | [中文](README.zh.md)
+
 The **local-filesystem** implementation of the [`@deepseek-ai/dsh-spill`](../spill) storage seam. Registers as `ctx.spillStore` and persists a tool's oversized text to a private, session-scoped file; its locator is the file path and its retrieval hint tells the model to use `read` or `grep` on that path.

 ## Storage layout
@@ -0,0 +1,34 @@
+# @deepseek-ai/dsh-spill-local
+
+[English](README.md) | 中文
+
+[`@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` | 私有 0700 临时目录 | spill 文件的根目录。进行设置可将它们保存在已知位置。 |
+
+`saveText` 在发生真实存储故障（权限、ENOSPC）时拒绝；spill 策略会将该拒绝作为尽力而为的失败，并保留内联结果。词汇见 seam README，设计见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md)。
+
+## 模型体验
+
+通过渲染本地路径以及 `read`/`grep` 取回指引的 spill 消费方间接影响模型。
+
+#### KV 缓存影响
+
+不直接导致失效；指定的消费方负责其引起的任何请求前缀变更。
+
+## 已知限制与待完成工作
+
+- **本地 spill 文件会持续存在，直到外部清理为止**：该后端不提供会话生命周期删除或按时间保留的策略，因为已持久化、已恢复和 fork 后的会话可能仍在引用某个路径。
+- **定位信息需要与其位于同一文件系统的消费方**：远程或虚拟部署需要另一个 `SpillStore` 后端，其定位信息和取回指引在该环境中有明确含义。