bdf8e12246
Consolidate the browser task runtime around the callback path, add safer artifact opening for Zhihu exports, and cover the new service/browser flows with focused tests and supporting docs. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
426 lines
9.8 KiB
Markdown
426 lines
9.8 KiB
Markdown
# Claw-WS 开发执行顺序卡片
|
||
|
||
> 配套计划：[`2026-04-01-claw-ws-parallel-transport.md`](./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
|
||
|
||
**本卡测试命令**
|
||
|
||
```bash
|
||
cargo test --test runtime_task_flow_test --test task_runner_test
|
||
```
|
||
|
||
**通过标准**
|
||
- 老的 `runtime_task_flow_test` 继续绿
|
||
- 新的 `task_runner_test` 通过
|
||
- pipe 行为无变化
|
||
|
||
**完成后提交**
|
||
|
||
```bash
|
||
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 协议
|
||
|
||
**本卡测试命令**
|
||
|
||
```bash
|
||
cargo test --test browser_tool_test --test compat_browser_tool_test --test browser_backend_capability_test
|
||
```
|
||
|
||
**通过标准**
|
||
- 现有 browser tool 相关测试不回归
|
||
- 新 capability test 通过
|
||
- 上层逻辑已脱离 `BrowserPipeTool<T>` 的硬耦合
|
||
|
||
**完成后提交**
|
||
|
||
```bash
|
||
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
|
||
|
||
**本卡测试命令**
|
||
|
||
```bash
|
||
cargo test --test browser_ws_protocol_test
|
||
```
|
||
|
||
**通过标准**
|
||
- codec 单测全绿
|
||
- 无网络依赖
|
||
- 已能作为 backend 的纯协议层基础
|
||
|
||
**完成后提交**
|
||
|
||
```bash
|
||
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
|
||
|
||
**本卡测试命令**
|
||
|
||
```bash
|
||
cargo test --test browser_ws_backend_test
|
||
```
|
||
|
||
**通过标准**
|
||
- backend 在 mocks/fakes 下稳定通过
|
||
- invoke 语义与 pipe backend 接近
|
||
- 可供上层 runtime 直接替换使用
|
||
|
||
**完成后提交**
|
||
|
||
```bash
|
||
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 交互体验优化
|
||
- 不要加任务队列
|
||
- 不要支持多客户端并发
|
||
|
||
**本卡测试命令**
|
||
|
||
```bash
|
||
cargo test --test service_ws_session_test
|
||
```
|
||
|
||
**通过标准**
|
||
- 服务端会话锁生效
|
||
- 共享 runner 可被 service 复用
|
||
- pipe 模式入口未受影响
|
||
|
||
**完成后提交**
|
||
|
||
```bash
|
||
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 承担业务逻辑
|
||
|
||
**本卡测试命令**
|
||
|
||
```bash
|
||
cargo test --test service_task_flow_test
|
||
cargo build --bin sg_claw --bin sg_claw_client
|
||
```
|
||
|
||
**通过标准**
|
||
- client 是薄壳
|
||
- task flow 正常
|
||
- 两个新 binary 可编译
|
||
|
||
**完成后提交**
|
||
|
||
```bash
|
||
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 回归命令**
|
||
|
||
```bash
|
||
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 测试命令**
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
**本卡全量命令**
|
||
|
||
```bash
|
||
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 模式可独立工作
|
||
- 两套模式并行存在
|
||
|
||
**完成后提交**
|
||
|
||
```bash
|
||
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 提前写完后又被迫重构
|