docs(subprocess): bring the zh side of the consumer-migration pairs along

The parent branch's zh translations were recorded against its pre-reshape
en text; this PR's Node-ward en deltas get minimal zh updates across the
subprocess catalog and the subprocess/lsp-local/subagent READMEs (all
type-equiv blocks byte-identical), with pairing records re-recorded.
This commit is contained in:
Tianyi Cui
2026-07-26 22:54:44 +08:00
parent 1b9d66eaac
commit d404609e19
14 files changed
+209 -86

No files matched your search

@@ -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
README.md: 126f0fd6863739563b8d3cb5b4b958cee47dfb3d
README.zh.md: fdd5035867316349a91d1700cbf3f521a2bac117
README.md: 73e0a4abe49e8d3060f246218694faee127668e9
README.zh.md: c38a1dd7c15e7d1c0f3139f8942911a4cd9f23fe
+9 -8
View File
@@ -6,13 +6,14 @@
## 契约
- `spawn(spec)` 立即返回一个实时句柄;`done` 在进程关闭时 resolve,仅在 spawn 层面失败时 reject。
- spec 完全显式(argv、cwd、按流划分的字节上限、spill 上限、宽限期),因为随部署变化的默认值属于调用方 seam 的配置,而不属于某个隐藏的进程管理器默认值(`dsh-bash` 的 request/spec 拆分是这条规则的所属模板)。`argv` 在这里绝不经过 shell 解释;需要 shell 的消费方自行传入 `['bash', '-c', command]`
- 输出读取器接受全流字节偏移量且从不消费独立的读取器不会抢走彼此的增量偏移量滑出内存尾部窗口的读取标记为 `lossy`,并在完整流 spill 文件存在时指向它。
- `kill()` 与 spec 的 abort 信号对整个 detached 进程组执行 SIGTERM→宽限期→SIGKILL 升级;服务响应中止但绝不判定原因(deadline 与原因分类归调用方所有)。
- dispose(资源释放)会终止所有仍在运行的受管进程并等待其退出
- `spawn(spec)` 立即返回一个实时句柄;`done` 在进程关闭时以退出事实 resolve`SubprocessOutcome` 不携带输出,也不携带原因分类),仅在 spawn 层面失败时 reject。
- spec 完全显式(argv、cwd、按流划分的 stdio 处置方式(disposition、宽限期),因为随部署变化的默认值属于调用方 seam 的配置,而不属于某个隐藏的进程管理器默认值(`dsh-bash` 的 request/spec 拆分是这条规则的所属模板)。`argv` 绝不经过 shell 解释;需要 shell 的消费方自行传入 `['bash', '-c', command]`
- stdio 按流采用 Node 形状:`'pipe'` 把原始流交给调用方做自己的协议分帧(LSP 的 JSON-RPC、ACPAgent Client Protocol)的 ndjson),`'inherit'` 直通父进程描述符以承载诊断输出,收集模式(collect)`{ maxBytes, spill? }` 则缓冲一段有界尾部,外加可选的完整流 spill 文件。收集模式的读取器接受全流字节偏移量且从不消费,因此独立的读取器不会抢走彼此的增量偏移量滑出内存尾部窗口的读取标记为 `lossy`,并在 spill 文件存在时指向它。收集到的输出在结算后仍可读取。
- 终止在每个平台上都以进程树为范围(POSIX 用 detached 进程组并以直接子进程回退;Windows 用 `taskkill /T`):`kill(signal)` 以 Node 风格只发送一个信号,结算后为空操作;`terminate()`(以及 spec 的 abort 信号)执行 SIGTERM→宽限期→SIGKILL 升级;`waitForExit()` 观察整棵进程树;`dispose(graces)` 运行进程外子进程所需的协作式 stdin EOF→SIGTERM→SIGKILL 阶梯。管理器只响应中止但绝不判定原因(deadline 与原因分类归调用方所有)。
- `scrubbedParentEnv()` / `SENSITIVE_ENV_PATTERN` 是唯一一份共享的凭据清除定义:环境中形似凭据的名称与 `DSH_*` 名称都会被丢弃,显式 `env` 在清除之后合并(有意转发的键会保留下来),`dshEnv` 则经由自身带校验的通道携带当前 harness 事实。无法把 spawn 路由到该服务的调用点(node-pty 后端、由 SDK 管理的传输层)改为导入该函数
- 服务自身的 dispose(资源释放)会终止所有仍在运行的受管进程并等待其退出。
参见[进程数据结构目录](../../../docs/core-data-structures/subprocess.md)与 [seam Agent Noteagent 决策记录)](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
参见[进程管理器数据结构目录](../../../docs/core-data-structures/subprocess.md)与 [seam Agent Noteagent 决策记录)](../../../.agents/notes/implemented/architecture/2026-07-26-subprocess-seam.md)。
## 模型体验
@@ -24,5 +25,5 @@
## 已知限制与暂缓事项
- **目前只有一个消费方家族**:该 seam 的形状仅在 bash 执行器上得到验证;仓库内其他 spawn 调用点(LSP 服务器、PTY 后端、subagent 传输层)继续保留各自专属的进程处理,直到它们的流与生命周期需求对照本契约得到重新审视
- **假定 POSIX 进程组语义**:句柄词汇(作为组长的 `pid`、进程组终止、SIGTERM/SIGKILL 升级)没有 Windows 方案
- **node-pty 与由 SDK 管理的 spawn 只共享凭据清除**:PTY 后端的终端 fork 与 MCP SDK 自己的 stdio 传输层无法把 spawn 路由到这道 seamfork/spawn 调用归库所有);它们改为导入 `scrubbedParentEnv`,使环境策略保持单一来源
- **dispose 阶梯假定子进程配合 stdin EOF**:依赖其他信号(SIGHUP 惯例、控制 socket)才能完全停稳的子进程,需要自己的第一阶,通用阶梯才适用