feat(cli): 沙箱剪贴板图片粘贴桥接补齐 Linux/Windows 支持

[CodeCasterX]

功能摘要 / Feature Summary

为沙箱「宿主剪贴板图片 → 容器内 Ctrl+V 粘贴」桥接补齐 Linux 与 Windows 平台支持（首版仅 macOS/darwin）。

问题描述 / Problem Description

沙箱图片粘贴桥接的首版（#381 / PR #384）只实现了 macOS/darwin。当前非 macOS 进沙箱走原样裸 docker exec -it 交互、不启用桥接（零行为变化、零副作用），因此 Linux 与 Windows 用户无法在容器内 TUI 中用 Ctrl+V 粘贴宿主剪贴板里的图片。

架构 A 的通用部分（宿主 node-pty PTY 中继、Ctrl+V 识别、PNG 落盘/命名/清理、终端恢复/退出码/stdin.pause 清理、optional node-pty 动态加载与回退）均平台无关、可直接复用；createClipboardAdapter 已按 process.platform 分派，只缺 Linux / Windows 两个 adapter 实现。

建议的解决方案 / Proposed Solution

• 新增 lib/sandbox/clipboard/linux.ts：X11（xclip -selection clipboard -t image/png -o，hasImage 走 TARGETS 探测）+ Wayland（$WAYLAND_DISPLAY 时 wl-paste -t image/png / wl-paste --list-types）；沿用 darwin 的二进制安全读图范式（写临时 PNG → fs 二进制读 + PNG magic 校验 + timeout + 失败透传不吞键）；工具缺失时 available() 给可执行报错（提示装 xclip / wl-clipboard）。
• 新增 lib/sandbox/clipboard/win32.ts：PowerShell Get-Clipboard -Format Image（WSL2 经 powershell.exe）；二进制安全读图同上；注意 node-pty 走 ConPTY、commandForEngine 会把命令包成 wsl.exe --。
• index.ts 接入 linux / win32 分派；bridge 平台门槛从「仅 darwin」放宽为「存在可用 adapter 即启用」，各平台失败回退路径与 macOS 保持一致。
• node-pty optionalDependencies 预编译矩阵覆盖 linux-x64/linux-arm64、win32-x64。
• 各平台真机验证矩阵（env-blocked）：Linux(X11/Wayland) + Windows(WSL2) 上 4 个 TUI 的 Ctrl+V 贴图、退出/终端恢复、降级与负向用例。

替代方案 / Alternative Solutions

不做架构 B（容器内 xclip/wl-paste shim）——保留为未来高保真升级；本任务延续架构 A 的宿主中继思路。

---

跟进 #381（macOS 首版需求）/ PR #384（macOS 首版实现）。内部追踪：TASK-20260602-151139。

[CodeCasterX]

任务文件

claude · TASK-20260602-151139

元数据 (frontmatter)

---
id: TASK-20260602-151139
type: feature
branch: agent-infra-feature-clipboard-bridge-linux-windows
workflow: feature-development
status: active
created_at: 2026-06-02 23:11:39+08:00
updated_at: 2026-06-10 14:46:16+08:00
agent_infra_version: v0.7.1-alpha.0
created_by: human
priority: Medium
effort: Medium
start_date: 2026-06-10
target_date: 2026-06-17
current_step: technical-design
assigned_to: claude
issue_number: 385
---

任务：沙箱剪贴板图片粘贴桥接补齐 Linux/Windows 支持

描述

为沙箱「宿主剪贴板图片 → 容器内 Ctrl+V 粘贴」桥接补齐 Linux 与 Windows 平台支持。首版（TASK-20260531-220334 / PR #384）仅实现了 macOS/darwin；当前非 macOS 进沙箱走原样裸 docker exec -it 交互、不启用桥接（零行为变化、零副作用）。本任务在已落地的「架构 A」之上，复用通用中继逻辑，新增 Linux / Windows 两个剪贴板 adapter。

现状（可直接复用的基础）

• 架构 A 已落地：宿主侧 node-pty PTY 中继拦截 Ctrl+V；剪贴板有图时读图转 PNG 落 ~/.agent-infra/clipboard/<hash>.png（只读宿主剪贴板、绝不改写），以 bracketed paste 注入容器 /clipboard/<hash>.png 路径，TUI 当图片附件读取。
• 跨平台抽象已就位：lib/sandbox/clipboard/index.ts 的 createClipboardAdapter 按 process.platform 分派；目前仅 darwin.ts 实现，非 darwin 返回 null → bridge 第一道门槛即回退裸交互。
• 平台无关、可直接复用：bridge.ts（PTY 中继 / 终端恢复 / 退出码 / stdin.pause 清理 / 失败回退）、keys.ts（Ctrl+V 序列识别）、paths.ts（落盘/命名/清理）、node-pty.ts（optional 动态加载）。

上下文

• 关联 Issue：feat(cli): 沙箱剪贴板图片粘贴桥接补齐 Linux/Windows 支持 #385
• 关联 PR：#XXX
• 分支：agent-infra-feature-clipboard-bridge-linux-windows
• 前置任务：TASK-20260531-220334（macOS 首版，Issue feat(cli): 在 macOS Docker 沙箱中支持 AI TUI 粘贴宿主剪贴板图片 #381 / PR feat(cli): 在 macOS Docker 沙箱中支持 AI TUI 粘贴宿主剪贴板图片 #384）

需求

1. 新增 lib/sandbox/clipboard/linux.ts：
   • X11：读图 xclip -selection clipboard -t image/png -o；hasImage 走 xclip -selection clipboard -t TARGETS -o 探测是否含 image/png。
   • Wayland（$WAYLAND_DISPLAY 存在时）：读图 wl-paste -t image/png；hasImage 走 wl-paste --list-types。
   • 沿用 darwin 的二进制安全读图范式：写临时 PNG 文件 → fs 二进制读 → PNG magic 校验 + timeout + 失败透传不吞键。
   • 工具缺失时 available() 返回可执行报错（提示安装 xclip / wl-clipboard）。
2. 新增 lib/sandbox/clipboard/win32.ts：
   • PowerShell Get-Clipboard -Format Image（WSL2 经 powershell.exe）；二进制安全读图同上。
   • 注意：node-pty 在 Windows 走 ConPTY；commandForEngine 会把命令包成 wsl.exe --。
3. index.ts 分派接入 linux / win32；bridge 平台门槛从「仅 darwin」放宽为「存在可用 adapter 即启用」，并确保各平台失败回退路径与 macOS 一致。
4. node-pty optionalDependencies 预编译矩阵覆盖 linux-x64/linux-arm64、win32-x64（首版已覆盖 darwin-arm64/darwin-x64）。
5. 各平台真机验证矩阵（env-blocked，需对应 OS）：Linux(X11/Wayland) + Windows(WSL2) 上 4 个 TUI 的 Ctrl+V 贴图、退出/终端恢复、降级与负向用例。

分析

• Round 1: analysis.md
• Round 2: analysis-r2.md

设计

• Round 1: plan.md

实现备注

审查反馈

• Round 1: review-analysis.md — Approved with 1 major and 1 minor finding.
• Round 2: review-analysis-r2.md — Approved with no findings.

活动日志

• 2026-06-02 23:11:39+08:00 — Task Created by claude — Task created from description (follow-up to TASK-20260531-220334 / PR feat(cli): 在 macOS Docker 沙箱中支持 AI TUI 粘贴宿主剪贴板图片 #384, macOS first version)
• 2026-06-10 14:18:55+08:00 — Task Restored by claude — Restored from GitHub Issue feat(cli): 沙箱剪贴板图片粘贴桥接补齐 Linux/Windows 支持 #385 sync comment (only task.md present on platform)
• 2026-06-10 14:21:16+08:00 — Requirement Analysis (Round 1) by claude — Analysis completed → analysis.md
• 2026-06-10 14:33:06+08:00 — Analysis Review (Round 1) by codex — Verdict: Approved, blockers: 0, major: 1, minor: 1 → review-analysis.md
• 2026-06-10 14:37:31+08:00 — Requirement Analysis (Round 2) by claude — Analysis completed → analysis-r2.md
• 2026-06-10 14:43:08+08:00 — Analysis Review (Round 2) by codex — Verdict: Approved, blockers: 0, major: 0, minor: 0 → review-analysis-r2.md
• 2026-06-10 14:46:16+08:00 — Technical Design (Round 1) by claude — Plan completed, awaiting human review → plan.md

完成检查清单

• 所有需求已满足
• 测试已编写并通过
• 代码已审查
• 文档已更新（如适用）
• PR 已创建

不在本任务范围

• 不改 macOS 既有实现（darwin adapter 已在前置任务交付）。
• 不做架构 B（容器内 xclip/wl-paste shim）。
• 不修改任何 TUI 源代码。
• 不做 Ctrl+V 读图链路同步 shell-out 异步化（前置任务遗留的独立 follow-up）。

---

由 claude 自动生成 · 内部追踪：TASK-20260602-151139

[CodeCasterX]

需求分析报告

claude · TASK-20260602-151139

需求分析报告

• 分析轮次：Round 1
• 产物文件：analysis.md

状态核对

$ git status -s
$ ls -la .agents/workspace/active/TASK-20260602-151139/
total 8
drwxr-xr-x 1 devuser dialout   96 Jun 10 14:19 .
drwxr-xr-x 1 devuser dialout  224 Jun 10 14:18 ..
-rw-r--r-- 1 devuser dialout 4536 Jun 10 14:19 task.md
$ tail .agents/workspace/active/TASK-20260602-151139/task.md
- [ ] 文档已更新（如适用）
- [ ] PR 已创建
<!-- 由 complete-task 勾选 -->

## 不在本任务范围

- **不改 macOS 既有实现**（darwin adapter 已在前置任务交付）。
- **不做架构 B**（容器内 `xclip`/`wl-paste` shim）。
- **不修改任何 TUI 源代码**。
- **不做 Ctrl+V 读图链路同步 shell-out 异步化**（前置任务遗留的独立 follow-up）。

工作树洁净；workspace 仅 task.md，不存在历史分析产物 → 本轮为 Round 1。

需求来源

来源类型：用户描述 + Issue #385（关联 macOS 首版 #381 / PR #384，前置任务 TASK-20260531-220334）

来源摘要：

沙箱「宿主剪贴板图片 → 容器内 Ctrl+V 粘贴」桥接首版仅交付 macOS/darwin；当前非 darwin 平台 createClipboardAdapter 返回 null → bridge 即回退裸 docker exec -it，Linux / Windows 用户在容器内 TUI 中无法用 Ctrl+V 粘贴宿主剪贴板图片。本任务在已落地的「架构 A（宿主侧 node-pty PTY 中继 + bracketed paste 注入 /clipboard/<hash>.png）」之上，新增 lib/sandbox/clipboard/linux.ts（X11 xclip + Wayland wl-paste）与 lib/sandbox/clipboard/win32.ts（PowerShell Get-Clipboard -Format Image，WSL2 经 powershell.exe），放宽 bridge 平台门槛为「存在可用 adapter 即启用」，并扩展 node-pty optionalDependencies 预编译矩阵到 linux-x64 / linux-arm64 / win32-x64。

需求理解

用一段话复述

在保持 macOS 已有行为零变更的前提下，给 lib/sandbox/clipboard/ 补两个平台 adapter（Linux、Windows），让 createClipboardAdapter 在这两个平台上返回非 null 的 adapter；bridge 的现有平台门槛（目前虽然写成「adapter 非 null 即启用」，但实际上仅 darwin 返回非 null）由 adapter 实现的接入自然解锁；其余复用已平台无关的中继 / 落盘 / 失败回退逻辑。各平台只读宿主剪贴板、绝不改写；工具缺失 / 读图失败 → adapter 返回 null（或 available() 返回带可读 reason 的 { ok: false }），bridge 退回裸 docker exec -it 并打印一行 Warning，TUI 体感与今天非 darwin 一致。

拆解为可验证的小需求

#	需求	验证标准（先写失败用例 → 再让它通过）
R1	新增 lib/sandbox/clipboard/linux.ts，导出 createLinuxClipboardAdapter，实现 available() + readImagePng()	单测：注入 execFn 模拟 X11 xclip 与 Wayland wl-paste 成功路径 → 返回 PNG buffer；非 PNG / 空输出 → 返回 null；工具缺失 → available() 返回 { ok: false, reason: …安装提示… }
R2	Linux adapter 按 $WAYLAND_DISPLAY 存在与否分派 X11 / Wayland 两种工具链	单测：注入 env 变量分别覆盖两条路径，校验调用的命令与参数
R3	新增 lib/sandbox/clipboard/win32.ts，导出 createWin32ClipboardAdapter	单测：注入 execFn 模拟 PowerShell Get-Clipboard -Format Image 写文件成功 / 无图片 / 失败三种路径，断言与 darwin 相同的 PNG magic + timeout + 临时目录 finally rmSync 行为
R4	lib/sandbox/clipboard/index.ts 分派接入 linux / win32	现有失败用例（tests/e2e/cli/sandbox-clipboard.test.ts:152-162 「disables linux」「disables win32」）需要更新为「returns adapter」；新增对应正向断言
R5	bridge 平台门槛已是「adapter 非 null 即启用」（bridge.ts:83-89），R4 接入后非 darwin 路径自然解锁；显式回归一遍既有 fallback 链	现有 fallback 链路单测保持绿（host TTY、no adapter、no node-pty、spawn 失败、/clipboard 缺失、AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1）
R6	bridge 在新平台保持「失败 → 透传原始 Ctrl+V，且每会话最多一条 Warning」语义	单测：在 linux / win32 platformName 下，adapter.readImagePng() 抛错 → child.write 收到原始 0x16，stderr 出现一次 clipboard image paste failed
R7	node-pty optional 预编译矩阵覆盖 linux-x64 / linux-arm64 / win32-x64	package.json 与上游 @lydell/node-pty 已发布平台对齐；本地装载在 CI Linux runner 上 loadNodePty() 不返回 null
R8	真机验证矩阵 env-blocked：Linux(X11 + Wayland) + Windows(WSL2) 上 4 个 TUI（claude-code、codex、gemini、opencode）的 Ctrl+V 贴图、退出/终端恢复、降级与负向用例	验证记录由人工在 PR 描述附实机截图或终端录像（env-blocked，不在自动化范围）

目标驱动（外科手术 = 每行改动都能直接追溯到上述 R1-R7 之一）

• 不修改 darwin.ts、不修改 keys.ts、不修改 paths.ts、不修改 node-pty.ts、不修改 shell.ts、不修改 enter.ts；
• bridge.ts 只在不影响 macOS 链路、且必要时才微调（首选不动）。

相关文件

直接复用（只读，不改）

• lib/sandbox/clipboard/bridge.ts:56-123 - runInteractiveWithClipboardBridge，平台门槛与失败回退已平台无关
• lib/sandbox/clipboard/keys.ts - Ctrl+V 三种序列识别（0x16 / CSI-u / modifyOtherKeys）
• lib/sandbox/clipboard/paths.ts - clipboardHostDir(home) → hostJoin(home, '.agent-infra', 'clipboard')、writeClipboardPngAtomic、pruneClipboardDir、CONTAINER_CLIPBOARD_MOUNT = '/clipboard'
• lib/sandbox/clipboard/node-pty.ts - optional @lydell/node-pty 动态加载
• lib/sandbox/clipboard/darwin.ts - 范式参考：PNG_MAGIC 常量、OSASCRIPT_PROBE_TIMEOUT_MS = 2000、READ_IMAGE_TIMEOUT_MS = 5000、临时目录 finally rmSync、available() / readImagePng() 接口
• lib/sandbox/shell.ts:140-147 - commandForEngine：在 engine === 'wsl2' 时把命令包成 wsl.exe -- <cmd> <args>
• lib/sandbox/commands/enter.ts:52-81 - clipboardBridgeDisabled env 开关 + runSandboxInteractive 入口

需要新增 / 修改

• lib/sandbox/clipboard/linux.ts:新文件 - 新增 X11 + Wayland 实现
• lib/sandbox/clipboard/win32.ts:新文件 - 新增 PowerShell 实现
• lib/sandbox/clipboard/index.ts:1-22 - ClipboardAdapter 联合类型扩展 + linux / win32 case 返回真实 adapter
• tests/e2e/cli/sandbox-clipboard.test.ts:152-167 - 现有 "disables linux"/"disables win32" 用例需改写为正向；新增 Linux X11 / Wayland 与 Windows 三组 adapter 行为单测（参照 darwin 单测 94-141 行结构）
• tests/e2e/cli/sandbox-clipboard.test.ts:170-308 - 新增 platformName=linux / win32 下的 bridge 启用 + 失败回退用例
• package.json:69-71 - 若 @lydell/node-pty 预编译矩阵不覆盖目标三元组，需评估是否需要 cpu / os 限制；首版无改动则在分析中明确

影响评估

直接影响

• lib/sandbox/clipboard/ 新增 2 个文件 + 修改 1 个文件
• tests/e2e/cli/sandbox-clipboard.test.ts 新增 / 改写若干测试用例
• 非 darwin 平台 ai sandbox exec 在交互式 TTY + 有可用 adapter 时，行为从「裸 docker exec -it」切换为「PTY 中继 + Ctrl+V 截获」
• 非 darwin 平台首次进入 sandbox 时，多一次 adapter 可用性探测（X11 xclip --version / Wayland wl-paste --version / Windows powershell.exe -NoProfile -Command exit），失败即降级，整体时间预算与 darwin 持平（≤ 2s）

间接影响

• 用户侧需要在 Linux 装 xclip / wl-clipboard 才能用图片粘贴；缺失时 adapter available() 返回带安装提示的 reason，bridge 走 fallback 链，与今天体验等价（裸 docker exec）
• Windows / WSL2 路径需要走 powershell.exe（不能用 wsl.exe -- powershell.exe），且 node-pty 在 Windows 上走 ConPTY；commandForEngine(engine='wsl2', 'docker', args) 已经处理了 docker 侧的 wsl.exe --，clipboard 侧的 powershell.exe 调用是宿主直发，不走 commandForEngine
• 若 @lydell/node-pty 在 linux-arm64 或 win32-x64 未预编译，loadNodePty() 会返回 null → bridge 走「node-pty 缺失 → 裸 docker exec」回退，与首版语义一致；不是回归
• lib/cp.ts 的 createClipboardAdapter 调用方（ssh 远程剪贴板拷贝）在 Linux/Windows 宿主侧会得到非 null adapter，能使 ai cp 在更多宿主上可用；这是顺带收益，不在本任务的强制需求里，需在 PR 描述里点名以便审查者确认行为变化

不在本任务范围（与 task.md 一致）

• 不改 macOS 既有实现
• 不做架构 B（容器内 shim）
• 不修改任何 TUI 源代码
• 不做 Ctrl+V 读图链路同步 shell-out 异步化（前置任务遗留的独立 follow-up）

技术风险

风险	影响	缓解思路
X11 / Wayland 双轨：$WAYLAND_DISPLAY 存在但用户实际跑 XWayland，或反过来	探测命令选错 → adapter 永久判 unavailable	以 $WAYLAND_DISPLAY 为「首选 Wayland」分派，工具缺失时回退另一路；available() 给出哪条路失败的可读 reason
xclip -t TARGETS -o 在某些剪贴板内容下会阻塞等待 selection owner	bridge 入口探测挂住 → 用户进沙箱明显卡顿	与 darwin 一致使用 READ_IMAGE_TIMEOUT_MS = 5000 上限；OSASCRIPT_PROBE_TIMEOUT_MS = 2000 等价物用 xclip -selection clipboard -t TARGETS -o 探测时间限制为 2 s
wl-paste 在 GNOME Mutter 上对二进制 PNG 偶发输出截断	PNG magic 校验失败 → 失败透传，但用户看到「贴不上图」	校验 PNG magic 失败时返回 null（与 darwin 一致），bridge 透传原始 Ctrl+V，最多打印一行 Warning；不在自动化测试范围
PowerShell Get-Clipboard -Format Image 输出 BMP/HBITMAP 而非 PNG	必须二次转码 → 复杂度上升	在脚本里显式 $img.Save($out, [System.Drawing.Imaging.ImageFormat]::Png)；失败则按 darwin 范式返回 null
node-pty 在 WSL2 子系统内运行而非原生 Win32	ConPTY 路径错位 → spawn 失败	bridge.ts:99-112 已有「spawn 失败 → fallback」防护；任务范围内不补救 ConPTY 行为，留作 follow-up
@lydell/node-pty 上游预编译矩阵实际未覆盖某些三元组	用户安装报错或运行时 loadNodePty() 返回 null	在 plan-task 阶段核对上游 release 真实覆盖情况；本任务 R7 是「评估并对齐」，不是强行新增预编译，缺失部分写到「Open Questions」并在 PR 描述里点名
本地无 Linux/Windows 真机环境 → R7、R8 无法在 CI / 本地自动化验证	「能跑」要靠人工验证	task.md 已声明 env-blocked；plan-task 阶段明确 PR 描述附实机记录；自动化测试覆盖到「依赖注入下的纯逻辑路径」
改写既有 "disables linux" / "disables win32" 测试有遗漏 → 默默允许 null	bridge 行为漂移	改测同时新增正向断言「returns adapter on linux/win32」并加冒烟测试覆盖 R1-R6

依赖关系

• 运行时依赖：@lydell/node-pty 已是 optional；本任务依赖其上游预编译矩阵在 linux-x64 / linux-arm64 / win32-x64 提供二进制（已是 v1.2.0-beta.12 默认覆盖范围，plan-task 阶段需核对）
• 宿主工具依赖：xclip（X11）/ wl-clipboard 提供的 wl-paste（Wayland）/ powershell.exe（WSL2）—— 这些是用户侧前置条件，缺失时 adapter available() 给出可执行的安装提示，bridge 自然降级
• 测试依赖：tests/helpers.ts 的 loadFreshEsm + onPlatforms()（如 .agents/rules/cross-platform-tests.md 所述）
• 协调点：
  • 与 macOS 首版 PR feat(cli): 在 macOS Docker 沙箱中支持 AI TUI 粘贴宿主剪贴板图片 #384 的回归约束：bridge.ts / darwin.ts / paths.ts / keys.ts / node-pty.ts 默认不动；如需动 bridge.ts 必须在 plan.md 明示「为什么不能只改 index.ts + 两个新文件」
  • 与 lib/cp.ts 调用方（ssh 远程剪贴板）的语义协调点：本任务令 Linux / Windows 宿主侧 createClipboardAdapter 返回非 null，会使 ai cp 在这些宿主上可读宿主剪贴板；远端 set 仍仅 macOS 支持（lib/cp.ts:127-130），属顺带启用，需在 PR 描述里点名

假设

• A1：用户侧在 X11 路径上已具备或愿意安装 xclip；在 Wayland 路径上已具备或愿意安装 wl-clipboard。缺失时 adapter available() 给可读 reason，bridge fallback。
• A2：Windows 用户通过 WSL2 引擎使用 sandbox；纯 Win32 原生宿主（无 WSL2）暂未声明支持（与 lib/sandbox/engine.ts:18：win32 → WSL2 一致）。
• A3：@lydell/node-pty@^1.2.0-beta.12 上游预编译已覆盖 linux-x64 / linux-arm64 / win32-x64；若任一未覆盖，对应平台用户会落到「node-pty 缺失 → 裸 docker exec」降级路径，行为与今天的非 darwin 一致，不算回归。
• A4：宿主时序——adapter available() 探测预算 2 s（与 darwin osascript probe 对齐）、readImagePng() 预算 5 s（与 darwin 对齐），可保证「进沙箱不卡顿」。
• A5：Wayland 二进制 PNG 偶发截断（GNOME Mutter）通过 PNG magic 校验拦截，作为「失败透传」处理，不在本任务范围内修这条上游路径。
• A6：本任务的所有 Linux / Windows 单测均使用注入式 execFn / readFileFn / mkdtempFn 等依赖，沿用 darwin 现行模式；真机端到端验证 env-blocked，由 PR 描述附记录。

未决问题

• Q1：@lydell/node-pty@^1.2.0-beta.12 上游预编译矩阵的真实覆盖（plan-task 阶段需要 npm view @lydell/node-pty 核对）。如发现 linux-arm64 或 win32-x64 未覆盖：是仅在 PR 描述中点名「该三元组用户降级到裸 docker exec」，还是同步评估升级到更新版本？建议默认采取前者，由审查阶段裁定。
• Q2：Linux adapter 在 $WAYLAND_DISPLAY 与 $DISPLAY 同时存在（XWayland）时的分派优先级——首选 Wayland 还是 X11？建议默认「首选 Wayland」（与社区惯例一致），并把降级路径写明：Wayland 工具缺失时尝试 X11；plan-task 阶段最终确认。
• Q3：Win32 PowerShell 脚本中是否需要显式处理「剪贴板含图片但 .NET System.Drawing 在 PowerShell Core (pwsh) 上不可用」的情况？老版 Windows 默认 powershell.exe（Windows PowerShell 5.1）携带 System.Drawing；新版 PowerShell 7+（pwsh.exe）需要额外引用。建议默认调用 powershell.exe（WSL2 实际可达的就是它），并在缺失时 available() 给可读 reason。
• Q4：是否要把 ai cp 在 Linux/Windows 宿主上「读宿主剪贴板能力」纳入测试？建议默认仅在 PR 描述里点名，不新增 ai cp 侧的测试，避免越界。

工作量和复杂度评估

• 复杂度：中

  • 平台抽象 + 中继 + 失败回退骨架已落地，新增 2 个 adapter 是「外科手术式」扩展
  • 单测注入模式已有 darwin 范式可参考，重复度高
  • 真机验证 env-blocked，自动化只覆盖逻辑路径

• 风险等级：中

  • 主要风险集中在 Wayland 工具链的真实行为（偶发截断、X11 vs Wayland 分派）与 PowerShell 输出格式
  • 全部失败路径都有「透传原始 Ctrl+V + 一次性 Warning」兜底，最差情况下也只是回退到今天的非 darwin 体验，不会产生回归
  • 缓解：单测覆盖到的逻辑路径全部走依赖注入；真机验证由 PR 描述补齐

• 预估工作量：

  • 编码：linux.ts (~140 行) + win32.ts (~120 行) + index.ts (~10 行) ≈ 实现层 ~270 行
  • 测试：tests/e2e/cli/sandbox-clipboard.test.ts 新增 ~300-400 行
  • 文档：README / CHANGELOG 在 plan-task 阶段确认是否需要更新
  • 真机验证：人工 ~1-2 h（Linux X11 + Linux Wayland + Windows WSL2 × 4 个 TUI 抽样）

---

由 claude 自动生成 · 内部追踪：TASK-20260602-151139

[CodeCasterX]

需求分析审查报告

codex · TASK-20260602-151139

需求分析审查报告

• 审查轮次：第 1 轮
• 产物文件：review-analysis.md
• 审查输入：
  • .agents/workspace/active/TASK-20260602-151139/analysis.md
  • .agents/workspace/active/TASK-20260602-151139/task.md
  • GitHub Issue feat(cli): 沙箱剪贴板图片粘贴桥接补齐 Linux/Windows 支持 #385

状态核对

$ git status -s
$ ls -la .agents/workspace/active/TASK-20260602-151139/
total 24
drwxr-xr-x 1 devuser dialout   128 Jun 10 14:26 .
drwxr-xr-x 1 devuser dialout   224 Jun 10 14:18 ..
-rw-r--r-- 1 devuser dialout 16119 Jun 10 14:26 analysis.md
-rw-r--r-- 1 devuser dialout  4678 Jun 10 14:26 task.md
$ tail .agents/workspace/active/TASK-20260602-151139/task.md
- [ ] 文档已更新（如适用）
- [ ] PR 已创建
<!-- 由 complete-task 勾选 -->

## 不在本任务范围

- **不改 macOS 既有实现**（darwin adapter 已在前置任务交付）。
- **不做架构 B**（容器内 `xclip`/`wl-paste` shim）。
- **不修改任何 TUI 源代码**。
- **不做 Ctrl+V 读图链路同步 shell-out 异步化**（前置任务遗留的独立 follow-up）。

审查摘要

• 审查者：codex
• 审查时间：2026-06-10 14:33:06+08:00
• 审查范围：需求分析产物、任务文件、Issue feat(cli): 沙箱剪贴板图片粘贴桥接补齐 Linux/Windows 支持 #385、clipboard bridge 相关代码与测试、node-pty npm 元数据
• 总体结论：通过，但建议修订分析后再进入方案设计
• 发现（AI 可处理）：0 阻塞项，1 主要，1 次要 / env-blocked：0

问题清单

阻塞项（必须修复）

（无）

主要问题（建议修复）

1. Linux 图像类型探测没有形成可验证验收项

文件：.agents/workspace/active/TASK-20260602-151139/analysis.md:47
说明：任务来源要求 Linux adapter 对 X11 使用 xclip -selection clipboard -t TARGETS -o、对 Wayland 使用 wl-paste --list-types 判断剪贴板是否含 image/png（见 task.md:41 和 task.md:43）。当前分析的 R1/R2 只要求模拟读图成功、非 PNG、工具缺失和环境分派，未把 TARGETS / --list-types 探测本身写成验收项；后文风险又在 analysis.md:110 把 xclip TARGETS 描述为 bridge 入口探测，但 analysis.md:89 同时说入口探测是工具版本检查，语义不一致。由于现有 adapter 接口没有单独 hasImage()，如果不在分析阶段明确“新增接口”还是“在 readImagePng() 内部做 MIME 探测”，后续设计可能跳过原始需求中的类型探测，或引入与 darwin adapter 不一致的 API。
修复建议：在分析中新增可验证需求：X11 TARGETS 输出含 / 不含 image/png、Wayland --list-types 输出含 / 不含 image/png 的单测覆盖；同时明确实现边界是添加 hasImage()、添加 Linux 内部 helper，还是有意改为直接读取并说明为何偏离 Issue 文案。同步更新风险段，避免把工具可用性探测和剪贴板内容探测混在一起。

次要问题（可选改进）

1. node-pty 预编译矩阵未决问题已可在分析阶段收敛

文件：.agents/workspace/active/TASK-20260602-151139/analysis.md:138
建议：分析在 analysis.md:120 写明 @lydell/node-pty@^1.2.0-beta.12 已覆盖目标平台，但又在 Q1 把真实覆盖留给 plan-task 核对。npm view @lydell/node-pty@1.2.0-beta.12 optionalDependencies --json 已确认包含 @lydell/node-pty-linux-x64、@lydell/node-pty-linux-arm64、@lydell/node-pty-win32-x64，还包含 win32-arm64。建议修订分析时关闭 Q1，或改成“已验证覆盖，plan-task 仅需决定是否补充运行时 smoke 测试”。

环境性遗留

（无）

证据原文

• 断言：本轮审查前工作区状态核对已完成，任务目录存在 analysis.md 与 task.md。

$ git status -s
$ ls -la .agents/workspace/active/TASK-20260602-151139/
total 24
drwxr-xr-x 1 devuser dialout   128 Jun 10 14:26 .
drwxr-xr-x 1 devuser dialout   224 Jun 10 14:18 ..
-rw-r--r-- 1 devuser dialout 16119 Jun 10 14:26 analysis.md
-rw-r--r-- 1 devuser dialout  4678 Jun 10 14:26 task.md
$ tail .agents/workspace/active/TASK-20260602-151139/task.md
- [ ] 文档已更新（如适用）
- [ ] PR 已创建
<!-- 由 complete-task 勾选 -->

## 不在本任务范围

- **不改 macOS 既有实现**（darwin adapter 已在前置任务交付）。
- **不做架构 B**（容器内 `xclip`/`wl-paste` shim）。
- **不修改任何 TUI 源代码**。
- **不做 Ctrl+V 读图链路同步 shell-out 异步化**（前置任务遗留的独立 follow-up）。

• 断言：Issue feat(cli): 沙箱剪贴板图片粘贴桥接补齐 Linux/Windows 支持 #385 要求 Linux X11 / Wayland 路径包含图像类型探测。

$ gh issue view 385 --json number,title,state,body,labels,url --jq '{number,title,state,url,labels:[.labels[].name],body}' 2>/dev/null
{"body":"## 功能摘要 / Feature Summary\n\n为沙箱「宿主剪贴板图片 → 容器内 Ctrl+V 粘贴」桥接补齐 Linux 与 Windows 平台支持（首版仅 macOS/darwin）。\n\n## 问题描述 / Problem Description\n\n沙箱图片粘贴桥接的首版（#381 / PR #384）只实现了 macOS/darwin。当前非 macOS 进沙箱走原样裸 `docker exec -it` 交互、不启用桥接（零行为变化、零副作用），因此 Linux 与 Windows 用户无法在容器内 TUI 中用 Ctrl+V 粘贴宿主剪贴板里的图片。\n\n架构 A 的通用部分（宿主 node-pty PTY 中继、Ctrl+V 识别、PNG 落盘/命名/清理、终端恢复/退出码/`stdin.pause` 清理、optional node-pty 动态加载与回退）均平台无关、可直接复用；`createClipboardAdapter` 已按 `process.platform` 分派，只缺 Linux / Windows 两个 adapter 实现。\n\n## 建议的解决方案 / Proposed Solution\n\n- 新增 `lib/sandbox/clipboard/linux.ts`：X11（`xclip -selection clipboard -t image/png -o`，`hasImage` 走 TARGETS 探测）+ Wayland（`$WAYLAND_DISPLAY` 时 `wl-paste -t image/png` / `wl-paste --list-types`）；沿用 darwin 的二进制安全读图范式（写临时 PNG → fs 二进制读 + PNG magic 校验 + timeout + 失败透传不吞键）；工具缺失时 `available()` 给可执行报错（提示装 `xclip` / `wl-clipboard`）。\n- 新增 `lib/sandbox/clipboard/win32.ts`：PowerShell `Get-Clipboard -Format Image`（WSL2 经 `powershell.exe`）；二进制安全读图同上；注意 node-pty 走 ConPTY、`commandForEngine` 会把命令包成 `wsl.exe --`。\n- `index.ts` 接入 linux / win32 分派；bridge 平台门槛从「仅 darwin」放宽为「存在可用 adapter 即启用」，各平台失败回退路径与 macOS 保持一致。\n- node-pty `optionalDependencies` 预编译矩阵覆盖 `linux-x64`/`linux-arm64`、`win32-x64`。\n- 各平台真机验证矩阵（env-blocked）：Linux(X11/Wayland) + Windows(WSL2) 上 4 个 TUI 的 Ctrl+V 贴图、退出/终端恢复、降级与负向用例。\n\n## 替代方案 / Alternative Solutions\n\n不做架构 B（容器内 `xclip`/`wl-paste` shim）——保留为未来高保真升级；本任务延续架构 A 的宿主中继思路。\n\n---\n\n跟进 #381（macOS 首版需求）/ PR #384（macOS 首版实现）。内部追踪：TASK-20260602-151139。\n","labels":["type: feature","status: pending-design-work","in: cli"],"number":385,"state":"OPEN","title":"feat(cli): 沙箱剪贴板图片粘贴桥接补齐 Linux/Windows 支持","url":"https://github.com/fitlab-ai/agent-infra/issues/385"}

• 断言：现有 clipboard adapter 接口只有 available() 与 readImagePng()，没有 hasImage()。

$ nl -ba lib/sandbox/clipboard/darwin.ts | sed -n '18,29p'
    18	export type DarwinClipboardAdapter = {
    19	  available(): { ok: true } | { ok: false; reason: string };
    20	  // Returns PNG bytes when the clipboard holds (or can synthesize) an image,
    21	  // null otherwise. No separate hasImage(): a probing `clipboard info` call
    22	  // forces NSPasteboard to materialize TIFF/BMP/8BPS representations to
    23	  // report their sizes, which can take seconds when the clipboard holds a
    24	  // Retina screenshot. Letting AppleScript's `as «class PNGf»` either succeed
    25	  // (image present, possibly auto-converted from TIFF/JPEG/GIF) or error
    26	  // (nothing PNG-coercible) keeps the path O(PNG size) regardless of how
    27	  // many other representations the source declared.
    28	  readImagePng(): Buffer | null;
    29	};

• 断言：@lydell/node-pty@1.2.0-beta.12 的 npm 元数据已覆盖本任务目标预编译包。

$ npm view @lydell/node-pty@1.2.0-beta.12 optionalDependencies --json
{
  "@lydell/node-pty-linux-x64": "1.2.0-beta.12",
  "@lydell/node-pty-win32-x64": "1.2.0-beta.12",
  "@lydell/node-pty-darwin-x64": "1.2.0-beta.12",
  "@lydell/node-pty-linux-arm64": "1.2.0-beta.12",
  "@lydell/node-pty-win32-arm64": "1.2.0-beta.12",
  "@lydell/node-pty-darwin-arm64": "1.2.0-beta.12"
}

亮点

• 分析范围清楚，明确了不改 macOS、不做容器内 shim、不碰 TUI 源码等非目标。
• 风险识别较完整，覆盖 X11/Wayland 分派、PowerShell 转 PNG、node-pty 回退、真机验证 env-blocked。
• 验收标准总体可执行，能为后续 plan-task 提供文件级和测试级输入。

与需求一致性

• 分析与 Issue feat(cli): 沙箱剪贴板图片粘贴桥接补齐 Linux/Windows 支持 #385 的主体目标一致
• 没有意外的范围扩张
• Linux 图像类型探测验收边界需补充

结论与建议

审查决定

• 通过
• 需要修改
• 拒绝

下一步

建议先执行 /analyze-task TASK-20260602-151139 修订分析，补齐 Linux TARGETS / --list-types 探测验收项，并关闭或改写 node-pty 矩阵未决问题；也可由 plan-task 明确承接上述两点后继续设计。

---

由 codex 自动生成 · 内部追踪：TASK-20260602-151139

[CodeCasterX]

需求分析报告

claude · TASK-20260602-151139

需求分析报告

• 分析轮次：Round 2
• 产物文件：analysis-r2.md
• 修订依据：review-analysis.md（codex，2026-06-10 14:33:06+08:00）—— 主要问题 1 项 + 次要问题 1 项
• 关系：本轮在 Round 1（analysis.md）基础上做外科手术式修订；未提及的章节继续以 Round 1 为准

状态核对

$ git status -s
$ ls -la .agents/workspace/active/TASK-20260602-151139/
total 36
drwxr-xr-x 1 devuser dialout   160 Jun 10 14:35 .
drwxr-xr-x 1 devuser dialout   224 Jun 10 14:18 ..
-rw-r--r-- 1 devuser dialout 16119 Jun 10 14:26 analysis.md
-rw-r--r-- 1 devuser dialout  9660 Jun 10 14:35 review-analysis.md
-rw-r--r-- 1 devuser dialout  4895 Jun 10 14:35 task.md
$ tail .agents/workspace/active/TASK-20260602-151139/task.md
- [ ] 文档已更新（如适用）
- [ ] PR 已创建
<!-- 由 complete-task 勾选 -->

## 不在本任务范围

- **不改 macOS 既有实现**（darwin adapter 已在前置任务交付）。
- **不做架构 B**（容器内 `xclip`/`wl-paste` shim）。
- **不修改任何 TUI 源代码**。
- **不做 Ctrl+V 读图链路同步 shell-out 异步化**（前置任务遗留的独立 follow-up）。

工作树洁净；已有 analysis.md + review-analysis.md → 本轮为 Round 2，产出 analysis-r2.md。

需求来源

来源类型：审查反馈修订 + 原 Issue #385（与 Round 1 一致）

来源摘要：

Round 1 analysis.md 通过审查（无阻塞项），审查者提出 1 个主要问题（Linux 图像类型探测的验收边界）和 1 个次要问题（node-pty 预编译矩阵已可在分析阶段收敛）。本轮针对这两项做出修订。需求本身（Issue #385 全文）相对 Round 1 没有变化。

修订摘要（相对 Round 1 的差异）

区域	Round 1 表述	Round 2 修订	触发原因
接口定义	隐含「沿用 darwin available() + readImagePng() 二接口」，但未声明是否新增 hasImage()	明确决定不新增 hasImage()，沿用 darwin 注释中给出的「内部直接读图、PNG magic 校验」范式；MIME 类型探测在 Linux readImagePng() 内部作为「读图前的轻量短路 + 工具是否可达的副产物」执行	review-analysis 主要问题 1
Linux 验收项	仅覆盖「读图成功 / 非 PNG / 工具缺失 / X11-vs-Wayland 分派」	显式新增 4 个验收项：xclip -t TARGETS -o 含/不含 image/png 两个用例；wl-paste --list-types 含/不含 image/png 两个用例	review-analysis 主要问题 1
风险段语义	把「xclip TARGETS 阻塞」与「xclip --version」探测描述混在一起	拆分为「工具可用性探测」（available() 用 --version）和「剪贴板内容探测」（readImagePng() 内部用 TARGETS / --list-types）两条独立风险	review-analysis 主要问题 1（语义不一致）
node-pty 矩阵未决问题 Q1	留作 plan-task 核对	关闭 Q1：已通过 npm view @lydell/node-pty@1.2.0-beta.12 optionalDependencies --json 验证覆盖 linux-x64 / linux-arm64 / win32-x64（+ darwin-x64 / darwin-arm64 / win32-arm64 额外收益），plan-task 仅需决定是否补充运行时 smoke 测试	review-analysis 次要问题 1

需求理解

整体语义与 Round 1 一致：在保持 macOS 已有行为零变更的前提下，给 lib/sandbox/clipboard/ 补两个平台 adapter（Linux、Windows）。本轮增量约束如下：

• 接口边界：两个新 adapter 的对外接口必须与 darwin 完全一致，即 available() + readImagePng()。不引入 hasImage()，与 darwin.ts:18-29 注释中的设计意图（避免 NSPasteboard 类型探测引入的慢路径，让「读图本身」充当 hasImage 探测）保持一致；Linux 侧把 MIME 类型探测作为 readImagePng() 的内部步骤，对外不可见。
• Linux 内部探测的角色：MIME 类型探测（X11 TARGETS / Wayland --list-types）不是 hasImage 接口的实现，而是 Linux readImagePng() 内部为避免对非图剪贴板做 image/png 读取而引入的「轻量短路」。失败处理统一为「返回 null，bridge 透传原始 Ctrl+V」，与 darwin 失败语义同构。
• node-pty 预编译矩阵：已知 @lydell/node-pty@^1.2.0-beta.12 覆盖目标平台，本任务实现侧不修改 package.json 的 optionalDependencies；plan-task 可选地补充「Linux/Windows CI 上 loadNodePty() 非 null」的 smoke 断言。

拆解为可验证的小需求（在 Round 1 基础上扩展，标注 ▲ 表示本轮新增/修订）

#	需求	验证标准（先写失败用例 → 再让它通过）
R1	新增 lib/sandbox/clipboard/linux.ts，导出 createLinuxClipboardAdapter，实现 available() + readImagePng()	单测：注入 execFn 模拟 X11 xclip 与 Wayland wl-paste 成功路径 → 返回 PNG buffer；非 PNG / 空输出 → 返回 null；工具缺失 → available() 返回 { ok: false, reason: …安装提示… }
R2	Linux adapter 按 $WAYLAND_DISPLAY 存在与否分派 X11 / Wayland 两种工具链	单测：注入 env 变量分别覆盖两条路径，校验调用的命令与参数
▲ R2a	Linux X11 路径在调用 xclip -selection clipboard -t image/png -o 前，先用 xclip -selection clipboard -t TARGETS -o 探测 image/png 是否在 TARGETS 集合中	单测：注入 execFn 模拟 TARGETS 输出含 image/png → 继续读图并返回 PNG buffer；模拟 TARGETS 输出不含 image/png → 直接返回 null，且不调用 -t image/png -o（用调用计数断言）
▲ R2b	Linux Wayland 路径在调用 wl-paste -t image/png 前，先用 wl-paste --list-types 探测剪贴板 MIME 列表	单测：注入 execFn 模拟 --list-types 输出含 image/png → 继续读图并返回 PNG buffer；模拟 --list-types 输出不含 image/png → 直接返回 null，且不调用 -t image/png（用调用计数断言）
▲ R2c	Linux adapter 对外接口与 darwin 一致：仅 available() + readImagePng()，无 hasImage()	类型测试：createLinuxClipboardAdapter() 返回值与 DarwinClipboardAdapter 结构兼容（同一 ClipboardAdapter 联合类型可正常归一）
▲ R2d	Linux available() 用「轻量工具版本探测」实现，不调用 TARGETS / --list-types；目的是把「工具可达」与「剪贴板内容形态」彻底解耦	单测：available() 路径下的 execFn 调用集合不包含 TARGETS / --list-types；只包含 xclip --version / wl-paste --version（或等价探测）
R3	新增 lib/sandbox/clipboard/win32.ts，导出 createWin32ClipboardAdapter	单测：注入 execFn 模拟 PowerShell Get-Clipboard -Format Image 写文件成功 / 无图片 / 失败三种路径，断言与 darwin 相同的 PNG magic + timeout + 临时目录 finally rmSync 行为
R4	lib/sandbox/clipboard/index.ts 分派接入 linux / win32	现有失败用例（tests/e2e/cli/sandbox-clipboard.test.ts:152-162 「disables linux」「disables win32」）需要改写为「returns adapter」
R5	bridge 平台门槛已是「adapter 非 null 即启用」（bridge.ts:83-89），R4 接入后非 darwin 路径自然解锁；显式回归一遍既有 fallback 链	现有 fallback 链路单测保持绿（host TTY、no adapter、no node-pty、spawn 失败、/clipboard 缺失、AI_SANDBOX_NO_CLIPBOARD_BRIDGE=1）
R6	bridge 在新平台保持「失败 → 透传原始 Ctrl+V，且每会话最多一条 Warning」语义	单测：在 linux / win32 platformName 下，adapter.readImagePng() 抛错 → child.write 收到原始 0x16，stderr 出现一次 clipboard image paste failed
▲ R7	node-pty optional 预编译矩阵覆盖 linux-x64 / linux-arm64 / win32-x64	已通过 npm view 静态验证，本任务实现侧不修改 package.json；plan-task 可选地补充 CI smoke：loadNodePty() 在 Linux / Windows runner 上返回非 null 而非进入回退路径
R8	真机验证矩阵 env-blocked：Linux(X11 + Wayland) + Windows(WSL2) 上 4 个 TUI 的 Ctrl+V 贴图、退出/终端恢复、降级与负向用例	验证记录由人工在 PR 描述附实机截图或终端录像（env-blocked，不在自动化范围）

相关文件

与 Round 1 一致，无新增引用。重点指针重申：

• lib/sandbox/clipboard/darwin.ts:18-29 — adapter 接口的「不引入 hasImage()」设计理由注释，本轮以此为决策依据
• lib/sandbox/clipboard/index.ts:1-22 — 联合类型 ClipboardAdapter 需扩展为 DarwinClipboardAdapter | LinuxClipboardAdapter | Win32ClipboardAdapter（三者结构同构，仍可在 bridge 上无差别调用）
• tests/e2e/cli/sandbox-clipboard.test.ts:152-167 — 「disables linux」「disables win32」既有用例需改写为正向

影响评估

直接影响

• 在 Round 1 之上新增：Linux readImagePng() 内部多两次 execFn 调用（探测 + 读图），探测预算与读图预算共用 READ_IMAGE_TIMEOUT_MS = 5000（与 darwin 对齐）
• 接口形状不变（仍仅两方法），意味着 bridge.ts 和现有调用方零改动
• 测试代码量较 Round 1 估算多 ~80-120 行（R2a / R2b / R2c / R2d 共 4 组用例 × 平均 20-30 行 / 组）

间接影响（相对 Round 1 无新增）

仍以 Round 1 「影响评估」段为准。

不在本任务范围（与 Round 1、与 task.md 一致）

• 不改 macOS 既有实现
• 不做架构 B
• 不修改任何 TUI 源代码
• 不做 Ctrl+V 读图链路同步 shell-out 异步化

技术风险

风险	影响	缓解思路
▲（修订）工具可用性探测 ≠ 剪贴板内容探测：Round 1 把两者混在了同一段，存在语义漂移	设计阶段可能把 --version 与 TARGETS 混用，导致 available() 路径耗时不可控	本轮 R2d 显式约束：available() 仅做工具版本探测（xclip --version / wl-paste --version），预算 2 s（与 darwin OSASCRIPT_PROBE_TIMEOUT_MS 对齐）；TARGETS / --list-types 只出现在 readImagePng() 内部的「读图前短路」，与读图共用 READ_IMAGE_TIMEOUT_MS = 5000
X11 / Wayland 双轨：$WAYLAND_DISPLAY 存在但用户实际跑 XWayland，或反过来	探测命令选错 → adapter 永久判 unavailable	以 $WAYLAND_DISPLAY 为「首选 Wayland」分派，工具缺失时回退另一路；available() 给出哪条路失败的可读 reason
xclip -t TARGETS -o 在某些剪贴板内容下可能阻塞等待 selection owner	读图前短路挂住 → 用户首个 Ctrl+V 后明显卡顿	把 TARGETS 短路调用同样套用 READ_IMAGE_TIMEOUT_MS = 5000；超时即按「TARGETS 不可读」处理（返回 null，bridge 透传原始 Ctrl+V）
wl-paste 在 GNOME Mutter 上对二进制 PNG 偶发输出截断	PNG magic 校验失败 → 失败透传，但用户看到「贴不上图」	校验 PNG magic 失败时返回 null（与 darwin 一致），bridge 透传原始 Ctrl+V，最多打印一行 Warning
PowerShell Get-Clipboard -Format Image 输出 BMP/HBITMAP 而非 PNG	必须二次转码 → 复杂度上升	在脚本里显式 $img.Save($out, [System.Drawing.Imaging.ImageFormat]::Png)；失败则按 darwin 范式返回 null
node-pty 在 WSL2 子系统内运行而非原生 Win32	ConPTY 路径错位 → spawn 失败	bridge.ts:99-112 已有「spawn 失败 → fallback」防护；任务范围内不补救 ConPTY 行为，留作 follow-up
本地无 Linux/Windows 真机环境 → R7、R8 无法在 CI / 本地自动化验证	「能跑」要靠人工验证	task.md 已声明 env-blocked；plan-task 阶段明确 PR 描述附实机记录；自动化测试覆盖到「依赖注入下的纯逻辑路径」

（▲ 已删除原 Round 1 风险条目：「@lydell/node-pty 上游预编译矩阵实际未覆盖某些三元组」—— 已经 npm view 静态验证全覆盖，移出风险段，剩余只是「CI smoke 可选补充」的次要事项。）

依赖关系

与 Round 1 一致，只更新一条：

• 运行时依赖：@lydell/node-pty@^1.2.0-beta.12 已确认上游 optionalDependencies 覆盖 linux-x64 / linux-arm64 / win32-x64（+ darwin-x64 / darwin-arm64 / win32-arm64 额外收益）。本任务实现侧不修改 package.json，R7 由「待评估」收敛为「已验证 + 可选 CI smoke」

其他依赖（宿主工具 / 测试 helper / 与首版 PR #384 协调点 / 与 lib/cp.ts 顺带启用）见 Round 1。

假设

• A1：用户侧在 X11 路径上已具备或愿意安装 xclip；在 Wayland 路径上已具备或愿意安装 wl-clipboard。缺失时 adapter available() 给可读 reason，bridge fallback。
• A2：Windows 用户通过 WSL2 引擎使用 sandbox；纯 Win32 原生宿主（无 WSL2）暂未声明支持。
• ▲ A3（已升级为事实）：@lydell/node-pty@^1.2.0-beta.12 optionalDependencies 覆盖目标平台 —— 已经 npm view 验证，不再作为假设保留。
• A4：宿主时序 —— available() 预算 2 s（与 darwin osascript probe 对齐）、readImagePng()（含读图前短路）预算 5 s（与 darwin 对齐）。
• A5：Wayland 二进制 PNG 偶发截断（GNOME Mutter）通过 PNG magic 校验拦截，作为「失败透传」处理。
• A6：本任务的所有 Linux / Windows 单测均使用注入式 execFn / readFileFn / mkdtempFn 等依赖，沿用 darwin 现行模式；真机端到端验证 env-blocked。
• ▲ A7（本轮新增）：Linux adapter 对外接口与 darwin 完全同构（available() + readImagePng()），MIME 类型探测在 readImagePng() 内部完成；这是基于 darwin.ts:18-29 注释中已声明的设计意图（不引入 hasImage() 以避免 NSPasteboard 慢路径），同时也避免 ClipboardAdapter 联合类型对方法集做参差。

未决问题

• ▲ Q1（已关闭）：node-pty 上游预编译矩阵覆盖问题 —— 已通过 npm view @lydell/node-pty@1.2.0-beta.12 optionalDependencies --json 验证，包含 linux-x64 / linux-arm64 / win32-x64（+ darwin-x64 / darwin-arm64 / win32-arm64）。plan-task 仅需决定是否补充运行时 smoke 测试，不再作为未决问题。
• Q2：Linux adapter 在 $WAYLAND_DISPLAY 与 $DISPLAY 同时存在（XWayland）时的分派优先级 —— 首选 Wayland 还是 X11？建议默认「首选 Wayland」并把降级路径写明：Wayland 工具缺失时尝试 X11；plan-task 阶段最终确认。
• Q3：Win32 PowerShell 脚本中是否需要显式处理「剪贴板含图片但 .NET System.Drawing 在 PowerShell Core (pwsh) 上不可用」的情况？建议默认调用 powershell.exe（WSL2 实际可达的就是 Windows PowerShell 5.1），并在失败时 available() 给可读 reason；plan-task 阶段最终确认。
• Q4：是否要把 ai cp 在 Linux/Windows 宿主上「读宿主剪贴板能力」纳入测试？建议默认仅在 PR 描述里点名，不新增 ai cp 侧的测试，避免越界。

工作量和复杂度评估

• 复杂度：中（与 Round 1 一致；本轮微增量来自 R2a/R2b/R2c/R2d 四组单测，约 80-120 行）
• 风险等级：中（与 Round 1 一致；风险段经语义拆分后更清晰，但风险分布未变）
• 预估工作量（在 Round 1 基础上微调）：
  • 编码：linux.ts (~150 行) + win32.ts (~120 行) + index.ts (~10 行) ≈ 实现层 ~280 行（linux.ts 较 Round 1 估算 +10 行用于 MIME 探测短路 helper）
  • 测试：tests/e2e/cli/sandbox-clipboard.test.ts 新增 ~400-500 行（较 Round 1 估算 +100 行用于 R2a / R2b / R2c / R2d）
  • 文档：plan-task 阶段确认 README / CHANGELOG 是否需要更新
  • 真机验证：人工 ~1-2 h（不变）

---

由 claude 自动生成 · 内部追踪：TASK-20260602-151139