Merge remote-tracking branch 'origin/worktree/ci-native-windows-20260808' into worktree/ci-native-windows-coverage-20260808
# Conflicts: # packages/subagent/subagent-codex/README.i18n.yaml # packages/subagent/subagent-codex/README.zh.md
This commit is contained in:
Tianyi Cui
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/pty/README.md
|
||||
README.md: 2afb3cd61ef4bfba460716549d41f799e419ff46
|
||||
README.zh.md: 57a5c93047ccb970f499f02c0168db7e9f71b622
|
||||
README.zh.md: e0871e23b954b5e611670d0519b938c9fcb28e43
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
`PTY` 的全称是 **Pseudo-Terminal（伪终端）**。这项能力提供持久且限定所有者范围的终端会话，适用于需要跨工具调用保留状态或使用交互式 stdin 的工作流。PTY 是单次 bash 与文件系统工具的补充，不会取代后两者更严格的逐操作契约。
|
||||
`PTY` 的全称是 **Pseudo-Terminal（伪终端）**。这项能力提供持久且限定所有者范围的终端会话，适用于需要跨工具调用保留状态或使用交互式 stdin 的工作流。PTY 是单次 bash 与文件系统工具的补充，不会取代后两者更严格的逐操作约定。
|
||||
|
||||
| 包 | 职责 | ctx 键 |
|
||||
|---|---|---|
|
||||
@@ -12,4 +12,4 @@
|
||||
|
||||
设计与暂缓边界记录在[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md) 中。
|
||||
|
||||
子系统参考——id、后端/会话契约、发送就绪、有界读取——见 [docs/subsystems/pty.md](../../docs/subsystems/pty.md)；设计与延后边界见[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)。
|
||||
子系统参考——id、后端/会话约定、发送就绪、有界读取——见 [docs/subsystems/pty.md](../../docs/subsystems/pty.md)；设计与暂缓边界见[持久 PTY Agent Note](../../.agents/notes/implemented/feature/2026-07-16-persistent-pty-sessions.md)。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/pty/pty-local/README.md
|
||||
README.md: 5acc92853e6e8fcb8938c48e391559bf4a28fb75
|
||||
README.zh.md: 353c2a4bdac7e8402fc63071dfb6fb85dcff66d5
|
||||
README.zh.md: 7d070a9a4aceab921264f020716fbdf16fdd57ff
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
|
||||
## 插件（`pty-local`）
|
||||
|
||||
该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。Spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
|
||||
该插件注入 `pty`、`sandboxPolicy` 和 `subprocess`，然后注册所配置的后端类型（`shell`）。`danger-full-access` 无需沙箱提供方即可直接启动 shell；受限模式要求同一执行世界中存在 `ctx.sandbox`，并通过它包装确切的 shell argv，未挂载时会在 spawn 前失败。spawn 时，一次 `ctx.sandboxPolicy.resolve({ session })` 调用会同时给出实际模式与会话工作区根目录；调用方省略 cwd 时，同一根目录也是 shell 的默认 cwd。当某个所有者存在开放的 PTY 或正在进行 spawn 时，如果配置变更会得到不同的实际模式，系统会在对应 `sandbox/mode` 事件提交前拒绝该变更。该限制绑定到确切所有者，因此即使提供方重新加载并保留现有会话，它仍然有效。更改模式前，请等待创建完成并关闭会话，避免以更宽权限打开的终端在权限降级后继续存在。
|
||||
|
||||
就绪检测结合以下机制：由前台状态验证的私有 bash 提示符标记、提供方报告的前台 stdin 等待事实、静默回退和绝对超时。只有最新自有标记之后的可打印尾部与受控 `PS1` 完全相等，标记才算就绪；即使 OSC 标记和提示符被拆到多个数据回调中也一样。因此，较早提示符之后的回显输入或输出无法使当前 send 完成。提供方写入前收集的提示符与静默证据，包括写入前前台检查仍在等待时收集的证据，都会在写入边界丢弃。如果 bash 在终端提供方发布其重新取得前台进程组的状态前打印标记，轮询会在普通静默上限之后再保留该候选状态 `handoffGraceMs`，使恰好同时发生的前台交接有机会胜出。因此，继承 `PROMPT_COMMAND` 的交互式子进程无法一直抑制推断空闲就绪直至绝对超时。未知的前台状态绝不会作为精确空闲的正向信号。同样，一次 send 之前就已存在的前台进程组 stdin 等待并不代表写入后就绪：必须先观察到同一进程组脱离该等待，之后再次进入等待才能使该次 send 完成；前台进程组发生变化则构成新的证据。尚未发布的启动过程中，回退路径要求已经观察到输出；零输出静默不能发布空会话，超时则拒绝 spawn。取消操作会关闭尚未发布的 shell，并以调用方提供的确切中止原因拒绝；`PtyBackendCleanupError` 会单独保留清理失败。调用方的 signal 会转发给终端分配与就绪初始化；发布后，句柄负责其生命周期。未完成的终端控制序列受 `maxReadBytes` 限制；超过上限后，系统会丢弃内容直到其终止符。格式错误的 UTF-8 终端输出使用替换字符；末尾的回车会跨回调保留，使拆分的 CRLF 合并为一个换行。
|
||||
|
||||
@@ -32,5 +32,5 @@
|
||||
|
||||
- 输出按行规范化；不支持全屏备用缓冲区交互。
|
||||
- 精确 stdin 等待检测取决于已挂载的进程管理提供方；无法证明该状态的提供方使用提示符标记和静默／超时就绪机制。
|
||||
- 清理保证以 `SubprocessTerminalHandle` 的保证为准；提供方特定的缺口属于该实现的契约，而非这个 PTY 消费方。
|
||||
- 清理保证以 `SubprocessTerminalHandle` 的保证为准；提供方特定的缺口属于该实现的约定，而非这个 PTY 消费方。
|
||||
- harness 进程退出后，会话无法继续存在。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/pty/pty/README.md
|
||||
README.md: 0f8b8e499dc81ce91e249f44bb38c8cc1af89d3f
|
||||
README.zh.md: b0c2e21a2bd5fca1088908bdde76ff1eb2ee8bfd
|
||||
README.zh.md: c1062de5f06cfbebbd10200ed5a835b1ab93b8a0
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
限定所有者范围的持久 PTY seam。`PtyService` 注册为 `ctx.pty`，生成不透明的会话 id，通过具名后端路由创建操作，将每个操作限制在完全相同的活跃 `Agent` 内，并在该 agent（智能体）或服务 dispose（资源释放）时等待后端完全停稳。
|
||||
|
||||
## 契约
|
||||
## 约定
|
||||
|
||||
- 后端注册一个稳定的 `type`，并返回尚未发布的 `PtyBackendSession`；失败或取消的设置过程必须清理部分资源。若清理失败，则以 `PtyBackendCleanupError` 拒绝，使注册表能在取消后继续保留该清理失败。
|
||||
- spawn 取消会保留调用方提供的确切中止原因。后端设置完成后，服务 dispose 与所有者消失仍分别对应可供机器路由的不同失败。
|
||||
@@ -38,4 +38,4 @@
|
||||
## 已知限制与暂缓事项
|
||||
|
||||
- 会话只存在于进程本地，harness 重启后不会恢复。
|
||||
- 系统有意不支持跨 agent 共享；未来的共享会话设计需要独立的权限契约。
|
||||
- 系统有意不支持跨 agent 共享；未来的共享会话设计需要独立的权限约定。
|
||||
|
||||
@@ -3,4 +3,4 @@
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write packages/pty/tool-bash-persistent/README.md
|
||||
README.md: cfb3acf41803f5b06ecb3f56ee8ffc29ce9147b1
|
||||
README.zh.md: a525485933344a8f9bc218456c099efdef572902
|
||||
README.zh.md: cf35a212159e7d12e1bdaa146b32b397d916a912
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
[English](README.md) | 中文
|
||||
|
||||
模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包拥有工具契约和 shell 复用；PTY 后端与沙箱策略由部署选择。
|
||||
模型可见的 `bash(command)`，底层复用一个按所有者隔离的 `ctx.pty` shell。该包拥有工具约定和 shell 复用；PTY 后端与沙箱策略由部署选择。
|
||||
|
||||
## 配置
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
| `backendType` | `shell` | 每个 Agent shell 使用的已注册 PTY 后端。 |
|
||||
| `timeoutMs` | `300000` | 单条命令的墙钟时间上限；超时会关闭 shell。 |
|
||||
| `maxOutputChars` | `16000` | 命令输出最多保留的字符数；固定诊断会在此后追加。 |
|
||||
| `description` | 持久 shell 描述 | 面向模型的环境契约。 |
|
||||
| `description` | 持久 shell 描述 | 面向模型的环境约定。 |
|
||||
|
||||
## 模型体验
|
||||
|
||||
|
||||
Reference in New Issue
Block a user