Merge remote-tracking branch 'origin/master' into xjt/generated-docs-zh-translation-apply
# Conflicts: # .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.i18n.yaml # .agents/notes/implemented/architecture/2026-07-12-agent-scope-runtime-design.zh.md # .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml # .agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md # .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml # .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md # .agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.i18n.yaml # .agents/notes/implemented/architecture/2026-07-27-compiler-independent-typert-model.zh.md # .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.i18n.yaml # .agents/notes/implemented/architecture/2026-07-28-directory-picker-capability-seam.zh.md # .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.i18n.yaml # .agents/notes/implemented/architecture/2026-07-30-static-repository-plugin-format.zh.md # .agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml # .agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md # .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.i18n.yaml # .agents/notes/implemented/architecture/2026-07-31-code-runtime-portable-identifier-seam.zh.md # .agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.i18n.yaml # .agents/notes/implemented/architecture/2026-08-01-packaged-ripgrep-search.zh.md # .agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.i18n.yaml # .agents/notes/implemented/architecture/2026-08-04-websocket-downlink-carrier.zh.md # .agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.i18n.yaml # .agents/notes/implemented/architecture/2026-08-05-large-session-jsonl-restore-pipeline.zh.md # .agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.i18n.yaml # .agents/notes/implemented/architecture/2026-08-06-agent-event-payload-objects.zh.md # .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.i18n.yaml # .agents/notes/implemented/architecture/2026-08-06-subagent-list-identity-projection.zh.md # .agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.i18n.yaml # .agents/notes/implemented/architecture/2026-08-06-web-markdown-incremental-ast-renderer.zh.md # .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.i18n.yaml # .agents/notes/implemented/architecture/2026-08-08-client-tool-presentation-ownership.zh.md # .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-27-glob-sampling.zh.md # .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.zh.md # .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-28-web-gui-feedback-loop.zh.md # .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-29-human-transcript-append-origin.zh.md # .agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-29-web-details-session-lifecycle.zh.md # .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-30-web-transcript-log-ordered-projection.zh.md # .agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-31-fork-anchor-floors-to-event-seq.zh.md # .agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.i18n.yaml # .agents/notes/implemented/bug-fix/2026-07-31-web-stop-preserves-queue.zh.md # .agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.i18n.yaml # .agents/notes/implemented/bug-fix/2026-08-02-goal-round-wrapup-message.zh.md # .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.i18n.yaml # .agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.zh.md # .agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.i18n.yaml # .agents/notes/implemented/bug-fix/2026-08-06-onboarding-step-owned-takeover-chrome.zh.md # .agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.i18n.yaml # .agents/notes/implemented/bug-fix/2026-08-06-provider-credential-lifecycle.zh.md # .agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.i18n.yaml # .agents/notes/implemented/bug-fix/2026-08-06-token-surface-unpriced-replace-compatibility.zh.md # .agents/notes/implemented/feature/2026-07-05-skill-system.i18n.yaml # .agents/notes/implemented/feature/2026-07-05-skill-system.zh.md # .agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.i18n.yaml # .agents/notes/implemented/feature/2026-07-08-background-subagent-tasks.zh.md # .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.i18n.yaml # .agents/notes/implemented/feature/2026-07-20-dsh-cli-personal-config.zh.md # .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.i18n.yaml # .agents/notes/implemented/feature/2026-07-21-continuable-background-subagents.zh.md # .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.i18n.yaml # .agents/notes/implemented/feature/2026-07-22-durable-subagent-catalog-and-list-agents.zh.md # .agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.i18n.yaml # .agents/notes/implemented/feature/2026-07-23-web-assistant-markdown.zh.md # .agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.i18n.yaml # .agents/notes/implemented/feature/2026-07-23-web-permission-and-approval.zh.md # .agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.i18n.yaml # .agents/notes/implemented/feature/2026-07-25-session-list-browsing-and-manual-order.zh.md # .agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.i18n.yaml # .agents/notes/implemented/feature/2026-07-27-skill-catalog-hot-refresh.zh.md # .agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.i18n.yaml # .agents/notes/implemented/feature/2026-07-27-web-session-fork-actions.zh.md # .agents/notes/implemented/feature/2026-07-27-web-session-search.i18n.yaml # .agents/notes/implemented/feature/2026-07-27-web-session-search.zh.md # .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml # .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md # .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.i18n.yaml # .agents/notes/implemented/feature/2026-07-28-continuable-subagent-conversations.zh.md # .agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.i18n.yaml # .agents/notes/implemented/feature/2026-07-28-skill-invocation-policy.zh.md # .agents/notes/implemented/feature/2026-07-28-web-terminal-card.i18n.yaml # .agents/notes/implemented/feature/2026-07-28-web-terminal-card.zh.md # .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.i18n.yaml # .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md # .agents/notes/implemented/feature/2026-07-30-search-render-card.i18n.yaml # .agents/notes/implemented/feature/2026-07-30-search-render-card.zh.md # .agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml # .agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md # .agents/notes/implemented/feature/2026-07-30-web-read-card.i18n.yaml # .agents/notes/implemented/feature/2026-07-30-web-read-card.zh.md # .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.i18n.yaml # .agents/notes/implemented/feature/2026-07-30-web-result-card-frontend.zh.md # .agents/notes/implemented/feature/2026-07-30-web-result-card.i18n.yaml # .agents/notes/implemented/feature/2026-07-30-web-result-card.zh.md # .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.i18n.yaml # .agents/notes/implemented/feature/2026-07-31-code-mode-language-dispatch.zh.md # .agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.i18n.yaml # .agents/notes/implemented/feature/2026-07-31-telemetry-anonymous-user-id.zh.md # .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.i18n.yaml # .agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md # .agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.i18n.yaml # .agents/notes/implemented/feature/2026-08-01-pwsh-tool-and-executor.zh.md # .agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.i18n.yaml # .agents/notes/implemented/feature/2026-08-02-pwsh-tool-bash-parity.zh.md # .agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.i18n.yaml # .agents/notes/implemented/feature/2026-08-02-web-thinking-tail-scroll.zh.md # .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.i18n.yaml # .agents/notes/implemented/feature/2026-08-05-pwsh-ui-bash-parity.zh.md # .agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.i18n.yaml # .agents/notes/implemented/feature/2026-08-06-resolved-theme-color-metadata.zh.md # .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.i18n.yaml # .agents/notes/implemented/feature/2026-08-06-web-skill-tool-row.zh.md # .agents/notes/implemented/process/2026-06-17-ts-build-config.i18n.yaml # .agents/notes/implemented/process/2026-06-17-ts-build-config.zh.md # .agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.i18n.yaml # .agents/notes/implemented/process/2026-07-22-tsconfig-solution-root-two-aggregates.zh.md # .agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.i18n.yaml # .agents/notes/implemented/process/2026-07-31-installer-adopts-existing-checkout.zh.md # .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.i18n.yaml # .agents/notes/implemented/process/2026-08-08-api-remotes-generated-contract-build.zh.md # .agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.i18n.yaml # .agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md # .agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.i18n.yaml # .agents/notes/implemented/simplification/2026-07-26-merge-subagent-control-service.zh.md # .agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.i18n.yaml # .agents/notes/implemented/simplification/2026-07-31-one-route-to-add-a-workspace.zh.md # .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.i18n.yaml # .agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.zh.md # .agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.i18n.yaml # .agents/notes/proposed/architecture/2026-07-29-durable-last-activity-index.zh.md # .agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.i18n.yaml # .agents/notes/proposed/architecture/2026-08-08-semantic-composer-chain-phases.zh.md # .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.i18n.yaml # .agents/notes/proposed/feature/2026-07-17-sdk-follow-up-capabilities.zh.md # apps/cli/reference/README.i18n.yaml # apps/cli/reference/README.zh.md # docs/api-gateway.i18n.yaml # docs/api-gateway.zh.md # docs/cookbook/adding-a-package.i18n.yaml # docs/cookbook/adding-a-package.zh.md # docs/cookbook/adding-a-tool.i18n.yaml # docs/cookbook/adding-a-tool.zh.md # docs/development.i18n.yaml # docs/development.zh.md # docs/i18n/README.i18n.yaml # docs/i18n/README.zh.md # docs/i18n/style-samples.md # docs/i18n/terminology.md # docs/testing.i18n.yaml # docs/testing.zh.md # examples/web-cordis/README.i18n.yaml # examples/web-cordis/README.zh.md # packages/api/gateway/README.i18n.yaml # packages/api/gateway/README.zh.md # packages/bash/bash-env/README.i18n.yaml # packages/bash/bash-env/README.zh.md # packages/bash/tool-bash/README.i18n.yaml # packages/bash/tool-bash/README.zh.md # packages/bash/tool-pwsh/README.i18n.yaml # packages/bash/tool-pwsh/README.zh.md # packages/client/ui-conversation/README.i18n.yaml # packages/client/ui-conversation/README.zh.md # packages/client/ui-tool/README.i18n.yaml # packages/client/ui-tool/README.zh.md # packages/feedback/command-feedback/README.i18n.yaml # packages/feedback/command-feedback/README.zh.md # packages/host/webserver/README.i18n.yaml # packages/host/webserver/README.zh.md # packages/pty/tool-bash-persistent/README.i18n.yaml # packages/pty/tool-bash-persistent/README.zh.md # packages/subagent/subagent-claude-code/README.i18n.yaml # packages/subagent/subagent-claude-code/README.zh.md # packages/subagent/subagent-codex/README.i18n.yaml # packages/subagent/subagent-codex/README.zh.md # packages/typert/type-meta/README.i18n.yaml # packages/typert/type-meta/README.zh.md # packages/util/atomic-write/README.i18n.yaml # packages/util/atomic-write/README.zh.md # scripts/snapshots/translation-prompt-v4/request-response.expected.json
This commit is contained in:
xjt
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/fs/README.md
|
||||
README.md: 162e2c75e92bc4ea6aba377c14db62e8ce83fbb9
|
||||
README.zh.md: b2929b17be6ce90051f0808c2cdf4bbf643f8f13
|
||||
README.zh.md: 196a2aad89203905148581d6364be7f02e2f4e35
|
||||
|
||||
@@ -2,22 +2,22 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、政策门禁插件（已观察状态、编辑前读取、版本防护的写入/编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品** 包。
|
||||
文件系统栈包括：提供方 seam（执行世界路径、有界文本 I/O 与带可选版本防护的原子变更）、本地实现、策略门禁插件（已观察状态、编辑前读取、版本防护的写入／编辑）、面向模型的文件工具与执行器，以及基于 bash 的发现工具。全部都是**产品**包。
|
||||
|
||||
| 包 | 角色 | ctx 键 |
|
||||
|---|---|---|
|
||||
| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 政策事件 | `ctx.fs` |
|
||||
| `fs/` | 提供方 seam：规范化进程路径、文件 URI 与包含关系、文本 I/O 和原子变更原语；拥有 `fs/*` 策略事件 | `ctx.fs` |
|
||||
| `fs-local/` | 本地文件系统 `FileSystem` 实现 | （注册 `ctx.fs`） |
|
||||
| [`e2b/fs-e2b`](../e2b/fs-e2b/README.md) | 以 E2B 为后端的 `FileSystem` 实现，共享由 `ctx.e2b` 拥有的远程运行时 | （注册 `ctx.fs`） |
|
||||
| `fs-sandbox/` | 强制沙箱的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根政策约束写入/编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
|
||||
| `fs-policy/` | 政策门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
|
||||
| `fs-sandbox/` | 强制实施沙箱约束的 `FileSystem`：扩展 `fs-local`，并按每次调用的模式与工作区根策略约束写入／编辑（只读模式拒绝，工作区写入模式限制在会话工作区与临时根目录内）；读取直接通过 | （注册 `ctx.fs`） |
|
||||
| `fs-policy/` | 策略门禁插件：通过 `fs/*` 事件门禁提供已观察状态、编辑前读取和版本防护的写入/编辑 | （无服务，仅有 `fs/*` 监听器） |
|
||||
| `tool-fs/` | 面向模型的 `read`/`write`/`edit` 工具以及执行器（通过 `ctx.fs` 读取，拥有读取窗口逻辑，分派 `fs/*`）；为会话 cwd 相对路径保留文件系统语义，并在已挂载的 `ctx.fs` 实施约束时声明沙箱升级字段 | （注册到 `ctx.tools`） |
|
||||
| `tool-fs-search/` | 面向模型的 `glob`/`grep` 发现工具；当 `rg` 位于 bash 执行器 `PATH` 上时注册，通过 `ctx.bash` 运行固定 ripgrep 命令，而不是使用 `ctx.fs` 提供方方法 | （注册到 `ctx.tools`） |
|
||||
|
||||
接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、政策门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。政策（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去政策，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索契约；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
|
||||
接口位于 `fs/fs/`。沙箱化、远程或限定项目作用域的文件系统后端可以替换 `fs-local`，而无需更改 seam、策略门禁或面向模型的工具 schema：`fs-sandbox` 基于共享沙箱模式提供进程内路径围栏（[决策](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)），而 `fs-e2b` 则把文件状态置于与 E2B 进程管理提供方共享的远程执行世界中（[决策](../../.agents/notes/implemented/architecture/2026-07-28-portable-execution-world-consumers.md)）。策略（`fs-policy/`）是一个只通过 `fs/*` 事件门禁参与的插件，不是工具注入的服务；因此移除它会平稳失去策略，留下不受约束的裸提供方，而不会破坏工具。加载 `tool-fs/` 的部署也应加载该插件。模式围栏与编辑前读取门禁彼此正交，可以组合。发现（`tool-fs-search/`）有意不扩展提供方 seam：搜索是在 bash 执行器上运行 `rg`、由进程支持的工作流，因此文件系统后端无需承担通用搜索约定；只有当执行器能找到 `rg` 时，其工具才会注册。如果 bash 工作目录与 `read` 根目录是同一工作区，结果就能继续读取，这也是其 README 所述的共置部署。
|
||||
|
||||
## 文件 I/O 不设超时
|
||||
|
||||
`read`/`write`/`edit` **不** 接受 `timeoutMs`，提供方 seam 也不启动 deadline。这与 bash 和 web（两者使用 [`@deepseek-ai/dsh-timeout`](../util/timeout/README.md)）及基于 bash 的 `glob`/`grep` 不同（它们声明的 `timeoutMs` 由 `@deepseek-ai/dsh-timeout-policy` 强制执行）：这些工作由进程支持，deadline 可以实际终止工作。本地系统调用至多只能尽力中止：超时无法强制正在进行的 `fsync`/`rename` 停止，因此这里的 deadline 会成为无法兑现承诺的配置项。在此添加 deadline 还会在「显式优于隐式」明确禁止的地方引入隐式默认值。两个参考 agent（Claude Code、Codex）出于同一原因都不为文件 I/O 计时；取消仍通过工具执行信号传播，在系统调用边界尽力中止。
|
||||
|
||||
子系统参考——目标、结果、防护、策略事件、错误分类体系，以及文件 IO 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
|
||||
子系统参考——目标、结果、守卫、策略事件、错误分类体系，以及文件 I/O 为何不设超时——见 [docs/subsystems/filesystem.md](../../docs/subsystems/filesystem.md)；沙箱围栏见[跨家族 fs 沙箱 Agent Note](../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/fs/fs/README.md
|
||||
README.md: 5c58fc476b9b11a83bbe0d6c33ac782d94d6ffbc
|
||||
README.zh.md: 97d7104f3c4c0beca408397f9cb1cead39b0a76e
|
||||
README.zh.md: 8eb2634df2754cdcada4e48046e19eb32b1cf3af
|
||||
|
||||
@@ -2,18 +2,18 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选** 接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、政策插件监听的 `fs/*` 政策事件词汇。
|
||||
**文件系统提供方 seam**：抽象 `FileSystem` 服务（`ctx.fs`），定义同一个执行世界中的存储原语，包括解析路径、公开规范化进程路径与文件 URI、检查包含关系、完整或流式读取文本、检查／列出元数据、原子写入和应用字面量编辑，但不规定实现方式。两个变更操作都**可选**接收版本防护，因此 `ctx.fs` 本身就是完整且不受约束的文本存储 seam。本包还拥有由工具分派、策略插件监听的 `fs/*` 策略事件词汇。
|
||||
|
||||
本包是四层文件系统栈中的提供方 seam 层；该拆分使每个关注点可以独立演进和替换（见[能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)、[文件系统能力 seam Agent Note](../../../.agents/notes/implemented/architecture/2026-06-17-filesystem-capability-seam.md)、[拆分文件系统 seam Agent Note](../../../.agents/notes/implemented/simplification/2026-06-26-fsspec-style-fs-seam.md)和[文件上下文事件门禁 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-26-file-context-as-event-gate.md)）：
|
||||
|
||||
| 层 | 包 | 角色 |
|
||||
|---|---|---|
|
||||
| 工具/执行器 | `@deepseek-ai/dsh-tool-fs` | 面向模型的 `read`/`write`/`edit` schema、读取窗口和文本渲染；通过 `ctx.fs` 读取/写入/编辑，并分派 `fs/*` 事件 |
|
||||
| 政策 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
|
||||
| 策略 | `@deepseek-ai/dsh-fs-policy` | 已观察状态、编辑前读取和版本防护的写入/编辑，通过 `fs/*` 事件门禁贡献（无服务） |
|
||||
| 提供方 seam | `@deepseek-ai/dsh-fs`（本包） | `ctx.fs`：执行世界路径、文本 I/O 与原子变更原语（可选版本防护）；拥有 `fs/*` 事件词汇 |
|
||||
| 提供方 | `@deepseek-ai/dsh-fs-local` | 宿主文件系统实现 |
|
||||
|
||||
未来的沙箱化、虚拟或远程后端只需实现该接口，政策层和工具层无需改变。
|
||||
未来的沙箱化、虚拟或远程后端只需实现该接口，策略层和工具层无需改变。
|
||||
|
||||
## 服务 API（`ctx.fs`）
|
||||
|
||||
@@ -26,7 +26,7 @@
|
||||
| `fileUrl(target)` | 返回采用执行世界平台语法的规范化 `file:` URI。编码由后端而非宿主进程负责。 |
|
||||
| `contains(parent, child)` | 在不公开或解析目标 key 的情况下，检查规范化身份相等或后代包含关系。两个目标都来自该提供方。 |
|
||||
| `stat(target, signal?)` | 返回 `FsInfo` 元数据（`version`、`type`、可选 `size`）；目标不存在时返回 `undefined`。绝不返回内容。 |
|
||||
| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库所有的符号链接进入目标前拒绝它。 |
|
||||
| `lstat(path, opts?, signal?)` | 当最后一个路径组件是符号链接时，不跟随该组件，返回 `FsPathInfo` 元数据。该方法采用路径形态，使消费方能在 `resolve` 跟随仓库自有的符号链接进入目标前拒绝它。 |
|
||||
| `readText(target, signal?)` | 把整个普通文本文件读取为一个解码后的字符串。负责普通文件检查、UTF-8 解码和二进制/NUL 拒绝（`FS_NOT_TEXT`）。 |
|
||||
| `streamText(target, signal?)` | 为大文件按解码后的分片流式读取相同文本（跨分片 UTF-8 解码仍由此处负责）；需要字节上限的消费方在消费流时执行该上限。 |
|
||||
| `listDir(target, signal?)` | 按稳定名称顺序列出直接子项。返回条目名称、条目类型、解析后的子目标和低成本元数据（若可用则包括 `version`/文件 `size`）；绝不读取文件内容。缺失目标抛出 `FS_NOT_FOUND`，非目录抛出 `FS_NOT_DIRECTORY`，权限失败抛出 `FS_PERMISSION_DENIED`，其他后端 I/O 失败抛出 `FS_IO_ERROR`。损坏/消失的子项可以作为无元数据的 `other` 返回；子项权限/I/O 失败会使用相同结构化代码使整个列表失败。 |
|
||||
@@ -35,19 +35,19 @@
|
||||
|
||||
无论是否有版本防护，变更都在后端的每目标锁内运行，因此无条件写入/编辑仍是原子的；「无条件」只移除*版本*前置条件，不移除原子性。
|
||||
|
||||
## `fs/*` 政策事件
|
||||
## `fs/*` 策略事件
|
||||
|
||||
本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和政策监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖政策插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
|
||||
本包声明三个事件（见 [filesystem.md](../../../docs/subsystems/filesystem.md#cordis-surface) 的生成区块），使发出方（`@deepseek-ai/dsh-tool-fs`）和策略监听器（`@deepseek-ai/dsh-fs-policy`）共享词汇，而无需让发出方依赖策略插件。`fs/write-intent` 和 `fs/edit-intent` 是单槽决策 waterfall（监听器完整决策，绝不调用 `next()`）；`fs/observed` 是发后即忘的记录事件。它们只携带 `dsh-fs` 词汇和一个不透明 `object` 参与者，不含面向模型的概念或 agent（智能体）/会话所有者结构。
|
||||
|
||||
## 提供方 seam，不是政策层
|
||||
## 提供方 seam，不是策略层
|
||||
|
||||
`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使政策层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不** 负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的政策，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察政策。
|
||||
`ctx.fs` 有意接近 fsspec 风格的存储原语，比字节级 `cat`/`open` 高半层，因为它会解码文本并拒绝二进制，使策略层绝不接触原始字节。它负责 UTF-8 解码、二进制拒绝、原子写入和字面量编辑临界区。它**不**负责行窗口、编号行、渲染 footer 或已观察状态。已观察状态、编辑前读取和版本防护的写入/编辑属于插件（`@deepseek-ai/dsh-fs-policy`）通过提供可选防护而添加的策略，并非提供方行为，因此沙箱化/远程后端不会继承任何面向模型的观察策略。
|
||||
|
||||
`editText` 留在该 seam 上，不由政策层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
|
||||
`editText` 留在该 seam 上，不由策略层通过读取加写入组合，因为版本防护、字面量匹配和原子重写必须处于同一临界区内，才能正确归因错误并实现一方胜出/一方陈旧的并发；远程后端也可以将其实现为原生比较并编辑操作。
|
||||
|
||||
## 词汇
|
||||
|
||||
`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整契约见 `src/types.ts`。
|
||||
`FsTargetKey` / `FsVersion` 是带品牌的不透明 id（见[品牌 id Agent Note](../../../.agents/notes/implemented/architecture/2026-06-20-branded-ids.md)）；消费方不得解析 `targetKey` 或解释 `version`，只有 `displayPath` 用于模型/UI 输出。`FsWriteIntent` 是显式的防护写入意图（`createIfAbsent` 创建缺失目标，并以 `FS_NOT_OBSERVED` 拒绝现有目标；`replaceIfVersion` 只在观察版本上替换，否则为 `FS_STALE_VERSION`）；从 `writeText` 中省略该值就是第三种无条件状态。`FsPathInfo` 是可报告 `symlink` 的不跟随链接元数据形态，区别于目标级 `FsInfo`。失败会抛出 `FsError`（继承 `HarnessError`；见[结构化错误分类 Agent Note](../../../.agents/notes/implemented/architecture/2026-06-11-structured-error-taxonomy.md)），并携带稳定的 `FsErrorCode`（`FS_NOT_FOUND`、`FS_NOT_DIRECTORY`、`FS_NOT_TEXT`、`FS_NOT_REGULAR_FILE`、`FS_PERMISSION_DENIED`、`FS_IO_ERROR`、`FS_STALE_VERSION`、`FS_NOT_OBSERVED`、`FS_AMBIGUOUS_EDIT`、`FS_EDIT_NOT_FOUND`、`FS_ABORTED`）；工具注册表公开 `{ name, code }`，并将其附在 `isError` 结果上。完整约定见 `src/types.ts`。
|
||||
|
||||
## 模型体验
|
||||
|
||||
@@ -55,11 +55,11 @@
|
||||
|
||||
#### KV Cache 影响
|
||||
|
||||
不会直接使缓存失效；具名消费方负责请求前缀的任何变化。
|
||||
不会直接使缓存失效；上述消费方负责请求前缀的任何变化。
|
||||
|
||||
## 已知限制与延期工作
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- **契约只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
|
||||
- **约定只支持文本**：后端以 `FS_NOT_TEXT` 拒绝二进制/非 UTF-8 内容；二进制安全操作是[工具 schema Agent Note](../../../.agents/notes/implemented/feature/2026-06-17-filesystem-tool-schemas.md)有意延期的工作。
|
||||
- **只有十一个原语**：没有删除、重命名/移动、复制或监视；`listDir` 只支持一层，递归、glob、分页和搜索不在范围内，见[目录列出 Agent Note](../../../.agents/notes/archived/architecture/2026-07-03-filesystem-directory-listing-seam.md)。
|
||||
- **没有 I/O deadline**：该 seam 不启动超时；取消只是每个原语上尽力而为的可选 `AbortSignal`（见有意采用的 [fs 能力族立场](../README.md)）。
|
||||
- **先解析后操作使远程后端每次工具调用需要两次往返**：折叠或缓存解析由这种后端自行决定。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/fs/tool-fs-search/README.md
|
||||
README.md: 32fa61e3bb09b2166499003953a5631a93baf73b
|
||||
README.zh.md: bf2eac320bf3dc0811ec8e3747487b4f3ce634b7
|
||||
README.zh.md: 34ffcdc9f64daba7350e4581b35e694213f24214
|
||||
|
||||
@@ -16,11 +16,11 @@ await ctx.plugin(LocalSpillStore) // @deepseek-ai/dsh-
|
||||
|
||||
## 部署要求：无需宿主 rg，但工作目录与文件系统需共置
|
||||
|
||||
二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。v1 只记录这项共置要求，不执行运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区契约或特定提供方的搜索后端。
|
||||
二进制随包交付，覆盖所有受支持平台（macOS/Linux/Windows，x64/arm64），因此无需宿主 `rg` 安装，工具在每个部署上都注册。返回路径会相对于解析后的工作目录显示（调用方 agent（智能体）有会话 cwd 时使用该 cwd，否则使用 `process.cwd()`）；只有该工作目录与文件系统根目录是同一工作区时，才能用 `read` 继续读取。v1 只记录这项共置要求，不执行运行时跨服务校验；远程或虚拟文件系统搜索需等待共享工作区约定或特定提供方的搜索后端。
|
||||
|
||||
## 配置
|
||||
|
||||
`sampleOverCapGlobResults` 是必填项且没有回退值；部署必须显式选择超过上限时的排序契约。其余配置键是可选的搜索上限，默认值如下。
|
||||
`sampleOverCapGlobResults` 是必填项且没有回退值；部署必须显式选择超过上限时的排序约定。其余配置键是可选的搜索上限，默认值如下。
|
||||
|
||||
| 配置键 | 默认值 | 含义 |
|
||||
|---|---|---|
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/fs/tool-fs/README.md
|
||||
README.md: 6f96970d8194c0992f9b955b95aec092185054b2
|
||||
README.zh.md: 2de8b02cd47f07af5a04a85694aec05214772a7f
|
||||
README.zh.md: 6cc8ebfe3ca4fc4e7c016aab64a0136cf4a07f14
|
||||
|
||||
@@ -50,11 +50,11 @@ await ctx.plugin(ToolFs) // this package — re
|
||||
|
||||
## `fs/observed` 发后即忘
|
||||
|
||||
`fs/observed` 在读取/写入/编辑已经成功之后，通过普通 `ctx.emit` 发出。监听器的契约是同步且只有副作用的记录器（`@deepseek-ai/dsh-fs-policy` 使用 `WeakMap.set`）；工具不保护这次发出，因此监听器抛出会作为工具的 `isError` 结果出现。异步或可能失败的观察不属于该事件。
|
||||
`fs/observed` 在读取/写入/编辑已经成功之后，通过普通 `ctx.emit` 发出。监听器的约定是同步且只有副作用的记录器（`@deepseek-ai/dsh-fs-policy` 使用 `WeakMap.set`）；工具不保护这次发出，因此监听器抛出会作为工具的 `isError` 结果出现。异步或可能失败的观察不属于该事件。
|
||||
|
||||
`read` 允许并发调度，因为其唯一变更是同步版本记录器。稍后的 `write` 或 `edit` 会在目标锁内重新检查版本，因此记录器竞态会以拒绝方式关闭；两个变更工具仍保持互斥。见[并行工具调用 Agent Note](../../../.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md)。
|
||||
|
||||
包根目录只导出 Cordis 插件契约（`name`、`inject`、`Config` 和 `apply`）。读取渲染（行窗口与输出格式化）位于 `src/read-render.ts`（不依赖 Cordis，单独进行单元测试）；`src/read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。
|
||||
包根目录只导出 Cordis 插件约定（`name`、`inject`、`Config` 和 `apply`）。读取渲染（行窗口与输出格式化）位于 `src/read-render.ts`（不依赖 Cordis，单独进行单元测试）；`src/read.ts`/`write.ts`/`edit.ts` 是工具执行器，`src/index.ts` 负责组合。
|
||||
|
||||
## 模型体验
|
||||
|
||||
|
||||
Reference in New Issue
Block a user