From dd384f86ab488c568e2c16a2dc987c70a2266c1a Mon Sep 17 00:00:00 2001 From: Tianyi Cui <53024+tianyicui@users.noreply.github.com> Date: Sun, 9 Aug 2026 20:13:09 +0800 Subject: [PATCH] docs: bring generated-catalog zh pairs along; raise docs/AGENTS.md ceiling to 1335 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Master's bilingual-generated-docs policy pairs the five generated catalogs; mirror the purge's regenerated English (ConPTY note, hooks TODO wording, thinking-format and SurfaceOp JSDoc, doc-graphs templates) into their reviewed zh sides and re-record. Condense the evidence-citation clause and raise the docs/AGENTS.md ceiling 1320→1335: master's seam-trio definition and this PR's review-mandated evidence rule land in the same window. --- docs/AGENTS.md | 2 +- docs/capability-seams.i18n.yaml | 4 ++-- docs/capability-seams.zh.md | 2 +- docs/config-catalog.i18n.yaml | 4 ++-- docs/config-catalog.zh.md | 16 +++++++--------- docs/event-producer-consumer.i18n.yaml | 4 ++-- docs/event-producer-consumer.zh.md | 2 +- docs/persistence-catalog.i18n.yaml | 4 ++-- docs/persistence-catalog.zh.md | 5 +++-- docs/tool-catalog.i18n.yaml | 4 ++-- docs/tool-catalog.zh.md | 4 ++-- scripts/doc-budgets.manifest.json | 2 +- 12 files changed, 26 insertions(+), 27 deletions(-) diff --git a/docs/AGENTS.md b/docs/AGENTS.md index a8d2a00e9d..aa9db3dcff 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -35,7 +35,7 @@ Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookb ## Writing rules -- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the two documentation homes may cite merged PRs and issues as evidence. +- **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, Agent Notes, or postmortems; the latter two may cite merged PRs and issues as evidence. - **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)). - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit. - **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)). diff --git a/docs/capability-seams.i18n.yaml b/docs/capability-seams.i18n.yaml index fb4d773d5c..aa09cb3036 100644 --- a/docs/capability-seams.i18n.yaml +++ b/docs/capability-seams.i18n.yaml @@ -2,5 +2,5 @@ # 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 docs/capability-seams.md -capability-seams.md: d61353210eedb3de68dd19caa866d4efb9deb19a -capability-seams.zh.md: 75bf176952a8c06c723e9f7cda535c1ca8b69819 +capability-seams.md: af9f8ba48e67074a485019a4ad9dddd08b2faf81 +capability-seams.zh.md: 7dff963646991d8b1f763ed789109e93cce2ddb8 diff --git a/docs/capability-seams.zh.md b/docs/capability-seams.zh.md index 75bf176952..7dff963646 100644 --- a/docs/capability-seams.zh.md +++ b/docs/capability-seams.zh.md @@ -419,7 +419,7 @@ flowchart LR | `ctx.permission` | `core` | [`permission`](../packages/interaction/permission) | - | - | - | 面向用户的预设表（`workspace-write`／`danger-full-access`），将沙箱模式与审批策略选项组合在一起；一次切换会写入一个 `permission/preset` 事件，并贯通到两个选项事件。 | | `ctx.codeRuntime` | `seam` | [`code-runtime`](../packages/code-runtime/code-runtime) | [`code-runtime-worker`](../packages/code-runtime/code-runtime-worker) | [`tools`](../packages/core/tools) | - | 使用 Host 提供的异步绑定运行一段由模型编写的程序；各后端采用不同的基础环境和语言（工具注册表在 Code Mode 下消费该服务）。 | | `ctx.fs` | `seam` | [`fs`](../packages/fs/fs) | [`fs-local`](../packages/fs/fs-local)、[`fs-sandbox`](../packages/fs/fs-sandbox)、[`fs-e2b`](../packages/e2b/fs-e2b) | [`tool-fs`](../packages/fs/tool-fs) | [`fs-policy`](../packages/fs/fs-policy) | tool-fs 通过 ctx.fs 执行读取／写入／编辑；fs-sandbox 按共享沙箱模式限制变更；fs-policy 通过 fs/* 事件门禁贡献基于观测状态的检查。 | -| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；面向模型的压缩工具仍处于暂缓状态。 | +| `ctx.compact` | `seam` | [`compact`](../packages/compact/compact) | [`compact-basic`](../packages/compact/compact-basic) | [`compact-basic`](../packages/compact/compact-basic) | - | 基础后端消费步骤后的压力事件和请求错误恢复事件；不存在面向模型的压缩工具。 | | `ctx.subagents` | `seam` | [`subagent`](../packages/subagent/subagent) | [`subagent-spawn`](../packages/subagent/subagent-spawn)、[`subagent-fork`](../packages/subagent/subagent-fork)、[`subagent-acp`](../packages/subagent/subagent-acp)、[`subagent-codex`](../packages/subagent/subagent-codex)、[`subagent-claude-code`](../packages/subagent/subagent-claude-code)、[`subagent-dsh-sdk`](../packages/subagent/subagent-dsh-sdk) | [`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-subagent-control`](../packages/subagent/tool-subagent-control)、[`tool-ralph`](../packages/workflow/tool-ralph) | - | 提供方实现传输；该服务还负责可选的、基于 Activation 的延续编排，tool-subagent 选择一次性或可延续委派，tool-subagent-control 传递后续消息，而 tool-ralph 要求一条全新的结构化输出路由。 | | `ctx.tasks` | `seam` | [`tasks`](../packages/tasks/tasks) | [`tasks-local`](../packages/tasks/tasks-local) | [`tool-bash`](../packages/bash/tool-bash)、[`tool-pty`](../packages/pty/tool-pty)、[`tool-subagent`](../packages/subagent/tool-subagent)、[`tool-tasks`](../packages/tasks/tool-tasks) | - | 生产方（后台 bash、PTY 发送和 subagent 委派）登记正在运行的工作；tool-tasks 是面向模型的控制接口，用于读取、列出和终止这些工作；tasks-local 是进程本地注册表。 | | `ctx.web` | `seam` | [`web`](../packages/web/web) | [`web-search-exa`](../packages/web/web-search-exa)、[`web-search-perplexity`](../packages/web/web-search-perplexity)、[`web-search-deepseek`](../packages/web/web-search-deepseek)、[`web-fetch-local`](../packages/web/web-fetch-local) | [`tool-web`](../packages/web/tool-web) | - | 搜索和抓取提供方注册到同一个 ctx.web seam；tool-web 负责稳定的面向模型名称。 | diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml index 12f3e2861c..80ac35ca4e 100644 --- a/docs/config-catalog.i18n.yaml +++ b/docs/config-catalog.i18n.yaml @@ -2,5 +2,5 @@ # 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 docs/config-catalog.md -config-catalog.md: 7278447cf85c2b25f7dd42e10e4b0b1cbd7eb96b -config-catalog.zh.md: a7d4252c526d36643a1b9f7aebd627faa60e1c77 +config-catalog.md: 10f0761fc5aa69852dff06f340f83f5a916975a9 +config-catalog.zh.md: ec0e44e9d39b801a5987f2bdab2584370c1b9333 diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md index a7d4252c52..ec0e44e9d3 100644 --- a/docs/config-catalog.zh.md +++ b/docs/config-catalog.zh.md @@ -413,7 +413,7 @@ export interface Config { } ``` -来源：[`packages/credentials/credentials-local/src/index.ts:54`](../packages/credentials/credentials-local/src/index.ts) +来源：[`packages/credentials/credentials-local/src/index.ts:55`](../packages/credentials/credentials-local/src/index.ts) ## `@deepseek-ai/dsh-e2b` @@ -515,7 +515,7 @@ export interface Config { * Process-level: read once at load, a relative path resolves against the process * launch cwd, so one config applies to the whole process. * TODO(per-session-hook-config): per-session discovery of a project-local - * `hooks.json` from each `session/new.cwd` is not yet implemented. + * `hooks.json` from each `session/new.cwd`. */ configPath: string /** @@ -550,7 +550,7 @@ export interface Config { * Path to a Codex `hooks.json`. Process-level: read once at load, a relative * path resolves against the process launch cwd. * TODO(per-session-hook-config): per-session project-local discovery from each - * `session/new.cwd` is not yet implemented. + * `session/new.cwd`. */ configPath: string /** The model name stamped on every payload (Codex includes `model` on each event). */ @@ -848,8 +848,7 @@ type PiThinkingFormat = NonNullable /** * pi-ai thinking formats a profile cannot name: both drive the request through - * `chatTemplateKwargs`, which this configuration does not expose, so offering - * them would hand back a format with nothing to say. + * `chatTemplateKwargs`, which this configuration does not expose. */ type WithheldThinkingFormat = 'chat-template' | 'qwen-chat-template' ``` @@ -1691,7 +1690,7 @@ export interface Config { /** * How to auto-answer the child's `session/request_permission` prompts: * `reject` (default — decline every prompt) or `allow` (approve via the first - * allow-shaped option). The first cut surfaces no prompt to a human. + * allow-shaped option). No prompt is surfaced to a human. */ permission: PermissionPolicy /** @@ -2361,8 +2360,7 @@ export interface Config { * ask BEFORE any interactive answerer sees it: * * - `'ask'` (the default) — delegate to the composed answerers; with none - * composed the chain falls through to the fail-closed `'unavailable'` - * (exactly today's behavior). + * composed the chain falls through to the fail-closed `'unavailable'`. * - `'never'` — never prompt anyone: every ask resolves `'rejected'` * deterministically. The strict headless stance (CI, unattended runs) and * the policy whose outcome is knowable without asking. @@ -2370,7 +2368,7 @@ export interface Config { export type ApprovalPolicy = 'ask' | 'never' ``` -来源：[`packages/interaction/user-approval/src/index.ts:178`](../packages/interaction/user-approval/src/index.ts) +来源：[`packages/interaction/user-approval/src/index.ts:177`](../packages/interaction/user-approval/src/index.ts) ## `@deepseek-ai/dsh-web` diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml index 89e1b03d35..0a3d6007f1 100644 --- a/docs/event-producer-consumer.i18n.yaml +++ b/docs/event-producer-consumer.i18n.yaml @@ -2,5 +2,5 @@ # 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 docs/event-producer-consumer.md -event-producer-consumer.md: 05ff62a391a0acb7db9abd2c9ce0c2082da52eaa -event-producer-consumer.zh.md: 7eafe5f2880cf9f0e6f2e7eb6c299730926f15ed +event-producer-consumer.md: 11eecf81a4eccadf2b97026154a78e4ed8a72164 +event-producer-consumer.zh.md: 2db5e596465b4adaf98c1b05692b61de3ced47b9 diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md index 7eafe5f288..2db5e59646 100644 --- a/docs/event-producer-consumer.zh.md +++ b/docs/event-producer-consumer.zh.md @@ -5,7 +5,7 @@ [English](event-producer-consumer.md) | 中文 -本矩阵展示哪些包会派发各个 harness 自有事件，以及哪些包会监听这些事件。这里特意采用表格而非一张大型关系图：事件之间存在多对多关系，以表格逐行呈现密集的关系数据更便于评审。接收方和事件名称类型还涵盖有意绕过 `ctx.emit` 的内含派发位置，例如 subagent 生命周期封装。 +本矩阵展示哪些包会派发各个 harness 自有事件，以及哪些包会监听这些事件。事件之间存在多对多关系，因此密集的关系数据以表格而非一张大型关系图呈现。接收方和事件名称类型还涵盖有意绕过 `ctx.emit` 的内含派发位置，例如 subagent 生命周期封装。 | 事件 | 模式 | 声明位置 | 派发方 | 监听方 | | --- | --- | --- | --- | --- | diff --git a/docs/persistence-catalog.i18n.yaml b/docs/persistence-catalog.i18n.yaml index e676227869..e5dd4edde7 100644 --- a/docs/persistence-catalog.i18n.yaml +++ b/docs/persistence-catalog.i18n.yaml @@ -2,5 +2,5 @@ # 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 docs/persistence-catalog.md -persistence-catalog.md: c9aa15cd827d99cee64e7a33db11995ee17f9bf8 -persistence-catalog.zh.md: d8743a1b0f26f2a4cf50aed42eb68f6c6db1ba13 +persistence-catalog.md: a17cae015eaa107a900069de916dddb216b87ec7 +persistence-catalog.zh.md: 3aef073dedcff0b6addb99d7c287f4e5f372c402 diff --git a/docs/persistence-catalog.zh.md b/docs/persistence-catalog.zh.md index d8743a1b0f..3aef073ded 100644 --- a/docs/persistence-catalog.zh.md +++ b/docs/persistence-catalog.zh.md @@ -37,7 +37,8 @@ export type SurfaceEventType = * (inclusive) through `end` (inclusive) with this node. Both must exist as * surface nodes in the current surface. `start === end` replaces a single * node. The node's {@link SessionEvent.sourceEventSeqs} must include every - * shadowed surface node. Used by compaction and possible other manipulations. + * shadowed surface node. Used by compaction; any surface-replacing producer + * may use it. */ export type SurfaceOp = | 'append' @@ -80,7 +81,7 @@ export type SessionEvent = { }[T] ``` -来源：[`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:343`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:375`](../packages/core/session/src/types.ts) +来源：[`packages/core/session/src/types.ts:308`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:315`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:344`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:376`](../packages/core/session/src/types.ts) ## 事件 diff --git a/docs/tool-catalog.i18n.yaml b/docs/tool-catalog.i18n.yaml index 1ae1b619f3..3e74bbc3e6 100644 --- a/docs/tool-catalog.i18n.yaml +++ b/docs/tool-catalog.i18n.yaml @@ -2,5 +2,5 @@ # 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 docs/tool-catalog.md -tool-catalog.md: f6a41da266db6eb2f347fb3c455a67b4dd44c4c0 -tool-catalog.zh.md: b36e8ccf63f4bdde7efca050bd92cbfcb03b3fbb +tool-catalog.md: 58267e208d919e7fa817991207a44ac0864fa00e +tool-catalog.zh.md: 1eda3506644bae6da56895c366a56b566536ed62 diff --git a/docs/tool-catalog.zh.md b/docs/tool-catalog.zh.md index b36e8ccf63..1eda350664 100644 --- a/docs/tool-catalog.zh.md +++ b/docs/tool-catalog.zh.md @@ -21,7 +21,7 @@ | `@deepseek-ai/dsh-tools` | `run_code` | `ctx.tools`、`ctx.codeRuntime (execution time)`、`ctx.systemPrompt` | `tool/call`、`one tool/code-dispatch-start + tool/code-dispatch pair per bridged sub-call`、`tool/result` | - | 在 `mode: code`／`mode: both` 下，它由工具注册表所有，作为可过滤能力层之外的保留传输机制（参见 Code Mode Agent Note）。在 `code` 下，它是注册表对协议格式（wire format）的唯一贡献；其他可见能力在使用已加载运行时语言生成的 SDK 章节中声明。程序通过 binding 调用这些能力，调用按照原生并发约定调度：启动顺序和策略遵循提交顺序，并发安全的函数体最多重叠执行 `maxParallelSubCalls` 个。调用会重新进入完整且受守卫保护的工具流水线，并将每个嵌套执行关联到此外层结果。 | | `@deepseek-ai/dsh-plan-mode` | `exit_plan_mode` | `ctx.tools`、`ctx.systemPrompt`、`ctx.userInteraction (execution time, opportunistic)` | `tool/call`、`plan/mode inactive on an approved review`、`tool/result` | - | 规划未激活时，exit_plan_mode 仍保留在面向模型的 schema 中，这样状态转换不会在规划策略变更之外额外造成工具目录变动。其执行路径会拒绝规划模式之外的调用；在规划模式下，它通过用户交互 seam 提交计划（批准／根据反馈继续规划），批准后会在步骤边界记录规划模式已停用。 | | `@deepseek-ai/dsh-tool-bash` | `bash` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具（来自 `@deepseek-ai/dsh-tool-tasks`）收集／停止；禁用 `enableRunInBackground` 配置（默认为 true）后，该参数会被完全移除。 | -| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 | +| `@deepseek-ai/dsh-tool-pwsh` | `pwsh` | `ctx.tools`、`ctx.bash`、`ctx.systemPrompt`、`ctx.bashEnv`、`ctx.tasks at call time for run_in_background` | `tool/call`、`tool/result` | - | pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 | | `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`、`cordis_mount`、`cordis_unmount` | `ctx.tools` | `tool/call`、`tool/result`、`process-local temporary Plugin lifecycle` | - | 不在任何随产品发布的树中，需要有意选择启用；临时 Plugin 代码可以访问真实运行时，见 .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md。由 cordis_mount 创建的插件在卸载或 DSH 重启之前可以注册**额外的**模型可见工具；发生这类工具集变更时，系统会记录完整且有变动的请求头。 | | `@deepseek-ai/dsh-tool-bash-persistent` | `bash` | `ctx.tools`、`ctx.pty`、`an owning Agent at execution time` | `tool/call`、`PTY shell state`、`tool/result` | - | 一个按所有者隔离的持久 bash 工具；部署组合提供 PTY 后端，并可覆盖面向模型的环境描述。 | | `@deepseek-ai/dsh-tool-str-replace-editor` | `str_replace_editor` | `ctx.tools`、`ctx.fs` | `tool/call`、`fs/observed after view presence/absence, edit absence, or successful mutation`、`tool/result` | - | 基于文件系统 seam 的独立查看／创建／唯一字面量替换／按行插入工具；可与任何 shell 或终端接口组合。 | @@ -250,7 +250,7 @@ bash 工具是 bash 执行器 seam 面向模型的消费方。使用 `run_in_bac 来源：[`packages/bash/tool-pwsh/src/index.ts`](../packages/bash/tool-pwsh/src/index.ts) -pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话；ConPTY 尚在规划中。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 +pwsh 工具是 Windows 组合中 bash 执行器 seam 的 PowerShell 方言消费方（由 `@deepseek-ai/dsh-pwsh-local` 等 PowerShell 执行器为 `ctx.bash` 提供后端）；除沙箱接口外，它逐项对应 bash 工具调用。使用 `run_in_background` 的运行会注册到通用 `ctx.tasks` 运行时，并通过 `task_*` 工具收集／停止；托管的 `DSH_*` 环境来自 `@deepseek-ai/dsh-bash-env`。每次调用都在新进程中运行，不使用持久 PTY 会话。路径采用原生 `C:\...` 形式，变量采用 `$env:NAME`。 ## `@deepseek-ai/dsh-tool-cordis` diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 2626cec2da..575f25b61b 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,6 +1,6 @@ { "AGENTS.md": 1782, - "docs/AGENTS.md": 1320, + "docs/AGENTS.md": 1335, "docs/architecture.md": 2174, "docs/cordis-primer.md": 600, "docs/defensive-patterns.md": 550,