claw/docs/superpowers/plans/2026-04-01-claw-ws-execution-cards.md

Claw-WS 开发执行顺序卡片

配套计划：2026-04-01-claw-ws-parallel-transport.md

使用方式：严格按卡片顺序执行。每张卡片完成后先跑卡片内测试，再进入下一张。不要跳卡，不要提前接线，不要先写 service/client 再回头抽象底层。

---

卡片 0：执行前约束

目标 先锁定边界，避免实现过程中把 pipe 模式改坏。

必须遵守

• 现有 pipe 模式必须保持可用
• 新增的是并行 claw-ws 模式，不是替换 pipe
• v1 只做单客户端、单任务串行
• browser_action / superrpa_browser 外部命名保持稳定
• 如果 WS Eval 不完整，先禁用相关 browser-script skill 暴露
• 不要提前做多客户端、任务队列、管理接口

完成标准

• 开发者明确后续所有改动都围绕“抽象复用 + 并行新增”进行

---

卡片 1：抽共享 SubmitTask Runner

目标 把当前 BrowserMessage::SubmitTask 的主执行逻辑从 pipe 入口里抽出来，变成共享执行器。

先做什么

1. 新增 tests/task_runner_test.rs
2. 先写失败用例：
   • 空 instruction
   • 无 LLM 配置
   • 日志顺序仍然是 LogEntry -> TaskComplete

要改哪些文件

• src/agent/mod.rs
• src/lib.rs
• src/agent/task_runner.rs
• tests/task_runner_test.rs

实现动作

1. 建 SubmitTaskRequest
2. 建 AgentEventSink
3. 建 run_submit_task(...)
4. 让 pipe 入口只做：
   • 解包 BrowserMessage::SubmitTask
   • 转成 SubmitTaskRequest
   • 调共享 runner

绝对不要做

• 不要在这一张卡里引入 ws backend
• 不要改 tool adapter
• 不要碰 service/client

本卡测试命令

cargo test --test runtime_task_flow_test --test task_runner_test

通过标准

• 老的 runtime_task_flow_test 继续绿
• 新的 task_runner_test 通过
• pipe 行为无变化

完成后提交

git commit -m "refactor: extract shared submit-task runner"

---

卡片 2：抽 BrowserBackend 抽象

目标 把上层 runtime / orchestration / tool adapter 从 BrowserPipeTool<T> 解耦，统一依赖浏览器后端接口。

先做什么

1. 新增 tests/browser_backend_capability_test.rs
2. 先写失败用例：
   • pipe backend 元数据不变
   • pipe backend 支持 Eval
   • supports_eval() == false 时不暴露 browser-script tools

要改哪些文件

• src/browser/mod.rs
• src/browser/backend.rs
• src/browser/pipe_backend.rs
• src/compat/browser_tool_adapter.rs
• src/compat/browser_script_skill_tool.rs
• src/compat/runtime.rs
• src/compat/orchestration.rs
• src/compat/workflow_executor.rs
• src/lib.rs
• tests/browser_backend_capability_test.rs

实现动作

1. 定义 BrowserBackend
2. 写 pipe_backend 包装当前 BrowserPipeTool
3. 把上层签名改成 Arc<dyn BrowserBackend>
4. 保持工具名不变：
   • browser_action
   • superrpa_browser
5. 增加 supports_eval() gating

绝对不要做

• 不要在这一张卡里接浏览器 ws 协议
• 不要建 service
• 不要加 client 协议

本卡测试命令

cargo test --test browser_tool_test --test compat_browser_tool_test --test browser_backend_capability_test

通过标准

• 现有 browser tool 相关测试不回归
• 新 capability test 通过
• 上层逻辑已脱离 BrowserPipeTool<T> 的硬耦合

完成后提交

git commit -m "refactor: abstract browser backend from pipe transport"

---

卡片 3：写死浏览器 WS 协议 Codec

目标 单独做浏览器固定 WebSocket 协议编解码层，不把协议细节散落到 backend 和 service 里。

先做什么

1. 新增 tests/browser_ws_protocol_test.rs
2. 先写失败用例：
   • outbound frame 精确编码
   • callback payload 解析
   • 异常格式拒绝
   • v1 action 覆盖完整

要改哪些文件

• src/browser/ws_protocol.rs
• tests/browser_ws_protocol_test.rs

实现动作

1. 按浏览器文档编码数组消息
2. 只支持 v1 必需动作：
   • Navigate
   • GetText
   • Click
   • Type
   • Eval
3. 定义 callback 解析和关联规则
4. 对 unsupported / malformed 早失败

绝对不要做

• 不要在这张卡里连真实浏览器
• 不要写 service 协议
• 不要把网络连接逻辑塞进 codec

本卡测试命令

cargo test --test browser_ws_protocol_test

通过标准

• codec 单测全绿
• 无网络依赖
• 已能作为 backend 的纯协议层基础

完成后提交

git commit -m "test: codify fixed browser websocket protocol"

---

卡片 4：实现 Browser WS Backend

目标 在 codec 之上提供和 pipe backend 类似的阻塞式 invoke(...) 能力。

先做什么

1. 新增 tests/browser_ws_backend_test.rs
2. 先写失败用例：
   • 0 + 无 callback 成功
   • 非 0 失败
   • 0 + callback 成功
   • callback timeout
   • socket drop

要改哪些文件

• src/browser/mod.rs
• src/browser/ws_backend.rs
• tests/browser_ws_backend_test.rs

实现动作

1. 建长连接管理器
2. 先做串行单飞请求
3. 发送前过 MacPolicy
4. 统一即时返回和 callback 返回
5. 输出统一 CommandOutput

绝对不要做

• 不要在这一张卡里接 service 层
• 不要做多并发 browser request
• 不要直接把浏览器 ws 代码散进 runtime

本卡测试命令

cargo test --test browser_ws_backend_test

通过标准

• backend 在 mocks/fakes 下稳定通过
• invoke 语义与 pipe backend 接近
• 可供上层 runtime 直接替换使用

完成后提交

git commit -m "feat: add browser websocket backend"

---

卡片 5：实现 sg_claw Service

目标 新增本地长驻服务端，承接 client 请求并复用共享 task runner。

先做什么

1. 新增 tests/service_ws_session_test.rs
2. 先写失败用例：
   • 首个客户端接入成功
   • 第二个客户端收到 busy
   • 断开后状态释放
   • 任务重入被拒绝

要改哪些文件

• src/service/mod.rs
• src/service/protocol.rs
• src/service/server.rs
• src/bin/sg_claw.rs
• src/lib.rs
• Cargo.toml
• tests/service_ws_session_test.rs

实现动作

1. 定义 client/service 协议
2. 实现 service 端事件 sink
3. 建单活 session 状态机：
   • Idle
   • ClientAttached
   • TaskRunning
4. 路由 SubmitTask 到共享 runner
5. 保持 pipe 入口不变

绝对不要做

• 不要在这一张卡里做 client 交互体验优化
• 不要加任务队列
• 不要支持多客户端并发

本卡测试命令

cargo test --test service_ws_session_test

通过标准

• 服务端会话锁生效
• 共享 runner 可被 service 复用
• pipe 模式入口未受影响

完成后提交

git commit -m "feat: add claw-ws service entrypoint"

---

卡片 6：实现 sg_claw_client

目标 新增一个薄客户端，提供类似 claude/codex 的交互式命令行体验。

先做什么

1. 新增 tests/service_task_flow_test.rs
2. 先写失败用例：
   • submit-task 送达 service
   • 日志按顺序流回
   • completion 只到一次
   • 完成后断开处理清晰

要改哪些文件

• src/bin/sg_claw_client.rs
• Cargo.toml
• tests/service_task_flow_test.rs

实现动作

1. 建立到本地 service 的 ws 连接
2. 读取用户输入
3. 发送 SubmitTask
4. 实时打印日志
5. 收到 TaskComplete 结束本轮

绝对不要做

• 不要把 runtime、skills、browser backend 复制进 client
• 不要让 client 直接连浏览器
• 不要让 client 承担业务逻辑

本卡测试命令

cargo test --test service_task_flow_test
cargo build --bin sg_claw --bin sg_claw_client

通过标准

• client 是薄壳
• task flow 正常
• 两个新 binary 可编译

完成后提交

git commit -m "feat: add interactive claw-ws client"

---

卡片 7：最终接线与回归验证

目标 把 ws 路径接起来，同时确认 pipe 路径零回归。

先做什么

1. 只增加最小配置项：
   • browser_ws_url
   • service_ws_listen_addr
2. 检查外部工具命名保持稳定

要改哪些文件

• Cargo.toml
• src/lib.rs
• src/config/settings.rs
• src/runtime/engine.rs（如确有必要）

实现动作

1. 接入最小配置面
2. 确保 pipe / ws 下工具命名一致
3. 跑旧 pipe 回归
4. 跑新 ws 测试
5. 跑全量 Rust tests
6. 编译所有 binary
7. 做一次真实本地 smoke test

本卡 pipe 回归命令

cargo test --test browser_tool_test --test compat_browser_tool_test --test runtime_task_flow_test --test pipe_handshake_test --test pipe_protocol_test --test task_protocol_test

本卡 ws 测试命令

cargo test --test task_runner_test --test browser_ws_protocol_test --test browser_ws_backend_test --test browser_backend_capability_test --test service_ws_session_test --test service_task_flow_test

本卡全量命令

cargo test --tests
cargo build --bin sgclaw --bin sg_claw --bin sg_claw_client

手工验证

1. 启动浏览器，确认 ws://127.0.0.1:12345 可用
2. cargo run --bin sg_claw
3. 新终端运行 cargo run --bin sg_claw_client
4. 发一个简单浏览器任务
5. 确认日志流和单次 completion
6. 确认旧 cargo run pipe 入口仍可启动

通过标准

• pipe 模式零回归
• ws 模式可独立工作
• 两套模式并行存在

完成后提交

git commit -m "feat: wire parallel claw-ws transport"

---

一句话执行顺序

严格按下面顺序做：

1. 共享 runner
2. browser backend 抽象
3. ws 协议 codec
4. ws backend
5. service
6. client
7. 配置接线 + 回归

如果顺序乱了，最容易出现的问题是：

• 上层重复实现
• pipe 被误伤
• ws 协议细节扩散到整个工程
• service/client 提前写完后又被迫重构