feat: refactor sgclaw around zeroclaw compat runtime

2026-03-26 16:23:31 +08:00
parent bca5b75801
commit ff0771a83f
1059 changed files with 409460 additions and 23 deletions
--- a/docs/plans/2026-03-26-zeroclaw-core-refactor-plan.md
+++ b/docs/plans/2026-03-26-zeroclaw-core-refactor-plan.md
@@ -0,0 +1,274 @@
+# ZeroClaw Core Refactor Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Rebuild `sgClaw` on top of vendored ZeroClaw core while preserving the existing SuperRPA browser pipe protocol, `FunctionsUI` bridge names, and `sgclaw` binary contract.
+
+**Architecture:** Keep `sgclaw` as the compatibility shell and replace its current minimal runtime with a ZeroClaw-based core adapter. Vendor the upstream ZeroClaw workspace into this repository for reproducible builds, then build a `compat` layer that translates `submit_task` / `task_complete` / log events to and from ZeroClaw agent, memory, cron, and tool abstractions. Do not integrate the upstream ZeroClaw gateway in this phase; the future standalone gateway will reuse the same vendored core through a separate entrypoint.
+
+**Tech Stack:** Rust workspace, vendored upstream ZeroClaw (`zeroclawlabs`), current sgClaw pipe protocol and browser tool, DeepSeek via ZeroClaw provider routing, SQLite memory backends, Chromium `run_cargo.py` build flow.
+
+### Task 1: Vendor ZeroClaw Upstream Snapshot
+
+**Files:**
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/third_party/zeroclaw/**`
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/third_party/zeroclaw/VENDORED_FROM.md`
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/.gitignore`
+
+**Step 1: Copy the upstream snapshot into the repo**
+
+Source:
+```bash
+/home/zyl/Downloads/zeroclaw-master.zip
+```
+
+Destination:
+```bash
+/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/third_party/zeroclaw
+```
+
+Strip the top-level `zeroclaw-master/` folder so the vendored directory itself is the workspace root.
+
+**Step 2: Record provenance**
+
+Write `third_party/zeroclaw/VENDORED_FROM.md` with:
+- upstream repo URL
+- upstream default branch (`master`)
+- source ZIP filename
+- vendoring date
+- a note that this copy is used to guarantee offline/reproducible browser builds
+
+**Step 3: Verify the vendor tree exists**
+
+Run:
+```bash
+find third_party/zeroclaw -maxdepth 2 -name Cargo.toml -o -name README.md
+```
+
+Expected: upstream workspace files are present.
+
+### Task 2: Convert sgClaw into a ZeroClaw-Backed Workspace Shell
+
+**Files:**
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/Cargo.toml`
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/lib.rs`
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/main.rs`
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/mod.rs`
+
+**Step 1: Add the vendored ZeroClaw dependency**
+
+Use a local path dependency:
+```toml
+zeroclaw = { package = "zeroclawlabs", path = "third_party/zeroclaw" }
+tokio = { version = "1", features = ["rt-multi-thread", "macros"] }
+```
+
+Do not use a git dependency. Browser builds must not depend on network access.
+
+**Step 2: Preserve the root crate identity**
+
+Keep:
+- package name `sgclaw`
+- binary name `sgclaw`
+- current manifest path used by SuperRPA browser build scripts
+
+This avoids breaking `/home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/build_sgclaw.py`.
+
+**Step 3: Route the process entrypoint through the compatibility layer**
+
+`src/lib.rs` should keep:
+- current handshake
+- current `BrowserPipeTool`
+- current message loop
+
+But delegate task execution to `compat::runtime`, not directly to the current thin planner/runtime path.
+
+### Task 3: Introduce the sgClaw Compatibility Layer
+
+**Files:**
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/runtime.rs`
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/browser_tool_adapter.rs`
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/config_adapter.rs`
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/event_bridge.rs`
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/memory_adapter.rs`
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/agent/mod.rs`
+
+**Step 1: Define the boundary**
+
+`compat::runtime` owns:
+- creating the ZeroClaw config/provider/runtime/memory/tool registry
+- executing a task from a browser `submit_task`
+- translating ZeroClaw progress into current `AgentMessage::LogEntry`
+- returning the final summary string for current `task_complete`
+
+`compat::event_bridge` owns all formatting decisions for:
+- `[info] ...`
+- `[error] ...`
+- final summary propagation
+
+**Step 2: Keep the browser protocol unchanged**
+
+Do not change these wire-level contracts:
+- `BrowserMessage::SubmitTask`
+- `AgentMessage::TaskComplete`
+- `AgentMessage::LogEntry`
+- `init/init_ack`
+
+The browser side must not need a corresponding protocol change.
+
+**Step 3: Retire direct planner ownership from the main path**
+
+`src/agent/mod.rs` should stop owning the main task intelligence flow. The current rule-based planner can remain only as:
+- transitional fallback, or
+- deterministic test fixture
+
+It must no longer be the primary execution engine.
+
+### Task 4: Adapt BrowserPipeTool into a ZeroClaw Tool
+
+**Files:**
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/browser_tool_adapter.rs`
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/pipe/browser_tool.rs`
+- Test: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/tests/compat_browser_tool_test.rs`
+
+**Step 1: Write the failing adapter test**
+
+Add a focused test that proves:
+- a ZeroClaw tool invocation can issue `navigate`, `type`, `click`, `getText`
+- domain validation still flows through current MAC/rules enforcement
+- returned observation data includes browser response payload and AOM snapshot
+
+**Step 2: Verify RED**
+
+Run:
+```bash
+python3 /home/zyl/projects/superRpa/src/tools/crates/run_cargo.py test \
+  --manifest-path /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/Cargo.toml \
+  --test compat_browser_tool_test
+```
+
+Expected: fail because the adapter does not exist yet.
+
+**Step 3: Implement the adapter**
+
+Wrap current `BrowserPipeTool` behind ZeroClaw’s async `Tool` trait:
+- tool name should stay stable and sgClaw-specific, for example `browser_action`
+- schema should only expose the currently supported safe actions
+- `ToolResult` should include serialized `data`, `aom_snapshot`, `timing`
+
+### Task 5: Build the DeepSeek-Backed ZeroClaw Runtime Path
+
+**Files:**
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/tests/compat_runtime_test.rs`
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/runtime.rs`
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/config_adapter.rs`
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/config/settings.rs`
+
+**Step 1: Write the failing runtime test**
+
+Add a compatibility runtime test that proves:
+- when `DEEPSEEK_API_KEY` is configured, sgClaw uses the ZeroClaw provider path
+- the runtime can execute a simple mocked `browser_action` sequence
+- the final result is returned as current sgClaw `task_complete`
+
+Use a fake provider or deterministic ZeroClaw test seam for RED/GREEN speed.
+
+**Step 2: Verify RED**
+
+Run:
+```bash
+python3 /home/zyl/projects/superRpa/src/tools/crates/run_cargo.py test \
+  --manifest-path /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/Cargo.toml \
+  --test compat_runtime_test
+```
+
+Expected: fail because the compatibility runtime is not wired yet.
+
+**Step 3: Implement DeepSeek mapping**
+
+Map current sgClaw env/config into ZeroClaw provider config:
+- `DEEPSEEK_API_KEY`
+- `DEEPSEEK_BASE_URL`
+- `DEEPSEEK_MODEL`
+
+DeepSeek should be treated as OpenAI-compatible routing under ZeroClaw, not via the old local `DeepSeekProvider`.
+
+### Task 6: Introduce Memory and Cron Through the Compatibility Core
+
+**Files:**
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/config_adapter.rs`
+- Modify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/src/compat/memory_adapter.rs`
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/tests/compat_memory_test.rs`
+- Create: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/tests/compat_cron_test.rs`
+
+**Step 1: Memory**
+
+Configure a workspace-local ZeroClaw memory backend suitable for browser embedding:
+- default to SQLite
+- keep storage under sgClaw-owned data path
+- avoid enabling unrelated gateway/channel storage
+
+**Step 2: Cron**
+
+Expose ZeroClaw cron internally, but do not yet bind it to browser UI.
+This phase only requires:
+- creating validated agent jobs
+- listing/running due jobs in tests
+
+The future standalone gateway will surface management UI for cron.
+
+### Task 7: Verification and Browser Integration
+
+**Files:**
+- Verify: `/home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/tests/*.rs`
+- Verify: `/home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/build_sgclaw.py`
+- Verify: `/home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/sgclaw_chat_smoke.mjs`
+
+**Step 1: Run the full Rust test baseline**
+
+Run:
+```bash
+python3 /home/zyl/projects/superRpa/src/tools/crates/run_cargo.py test \
+  --manifest-path /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/Cargo.toml \
+  --tests
+```
+
+Expected: current protocol/tool/planner compatibility tests still pass or are consciously replaced with equivalent compat tests.
+
+**Step 2: Build the browser-delivered binary from the worktree**
+
+Run:
+```bash
+python3 /home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/build_sgclaw.py \
+  --manifest-path /home/zyl/projects/sgClaw/claw/.worktrees/zeroclaw-core-refactor/Cargo.toml \
+  --out /home/zyl/projects/superRpa/src/out/KylinRelease/sgclaw
+```
+
+Expected: the compatibility-shell binary is produced at the same output path as today.
+
+**Step 3: Run browser smoke**
+
+Run:
+```bash
+node /home/zyl/projects/superRpa/src/chrome/browser/superrpa/sgclaw/sgclaw_chat_smoke.mjs
+```
+
+Expected:
+- browser protocol still starts and stops correctly
+- Baidu task still succeeds
+- Zhihu task still succeeds
+- no browser-side API/bridge changes are required
+
+### Non-Goals for This Refactor
+
+- Do not replace the current SuperRPA browser protocol with ZeroClaw gateway protocols.
+- Do not expose the upstream ZeroClaw web dashboard inside FunctionsUI.
+- Do not ship the standalone gateway in this phase.
+- Do not migrate browser-side code to a new transport.
+
+### Phase 2 After This Refactor
+
+After this compatibility refactor is stable:
+- add a separate `gateway` crate or binary that uses the same vendored ZeroClaw core
+- expose memory/cron/agent management there
+- keep browser-side `sgclaw` as a thin local execution shell