docs: redefine sgclaw as hardened zeroclaw runtime

2026-03-28 02:27:24 +08:00
parent b87968632a
commit 5ed81e5f0c
9 changed files with 783 additions and 101 deletions
--- a/docs/plans/2026-03-28-sgclaw-zeroclaw-core-realignment-plan.md
+++ b/docs/plans/2026-03-28-sgclaw-zeroclaw-core-realignment-plan.md
@@ -0,0 +1,598 @@
+# SGClaw ZeroClaw Core Realignment Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Rebuild `sgclaw` as a security-hardened zeroclaw runtime where the browser is a privileged tool surface and client host, not the product's defining execution model.
+
+**Architecture:** `zeroclaw` remains the real agent core for prompt building, skills, memory, tool routing, autonomy, and execution loops. `sgclaw` adds a security envelope around zeroclaw: hardened configuration defaults, MAC-validated pipe communication, browser-host revalidation, and constrained exposure of privileged tools. The browser stays important, but only as one protected execution surface.
+
+**Tech Stack:** Rust, vendored `zeroclaw`, SuperRPA browser pipe protocol, Chromium WebUI/overlay, JSON config, HMAC/MAC policy rules.
+
+## Scope Guard
+
+- In scope:
+  - zeroclaw-first runtime restructuring
+  - security and tool policy layering
+  - browser pipe re-framing as privileged tool surface
+  - documentation correction before code changes
+  - browser UI wording and observability alignment
+- Out of scope:
+  - broad UI redesign before the runtime contract is fixed
+  - indiscriminately enabling every zeroclaw built-in tool
+  - keeping parallel browser-only and zeroclaw-first runtime stacks long-term
+
+## Task 1: Rewrite The Product Docs Before Touching Runtime Code
+
+**Files:**
+- Modify: `docs/README.md`
+- Modify: `docs/L0-产品白皮书与能力全景层.md`
+- Modify: `docs/L1-系统架构与安全模型层.md`
+- Modify: `docs/L2-核心模块与接口契约层.md`
+- Modify: `docs/L3-数据流与Skill体系层.md`
+- Modify: `docs/L4-工程实现与部署拓扑层.md`
+- Modify: `docs/L5-提示词分布与安全改造方案.md`
+- Modify: `docs/浏览器对接标准.md`
+
+**Intent:**
+- Make the docs the single source of truth before implementation starts.
+- Remove the misleading framing that `sgclaw` is fundamentally a browser execution core.
+- Replace it with the correct framing: `sgclaw` is a security-hardened zeroclaw distribution with a privileged browser execution surface.
+
+**Step 1: Add a docs checklist in the plan branch**
+
+Checklist to apply consistently across the docs:
+
+```text
+1. zeroclaw is the runtime core
+2. sgclaw adds security policy and protected execution surfaces
+3. browser pipe is one privileged tool surface, not the whole runtime
+4. docs must distinguish current implementation gaps from target architecture
+5. no doc may imply that browser-only compat is the desired end state
+```
+
+**Step 2: Update the architecture docs**
+
+Required wording changes:
+
+- Replace phrases equivalent to “浏览器智能体执行内核” with wording equivalent to “安全加固后的 zeroclaw runtime”.
+- Reframe `compat` as a temporary adaptation layer, not the final product identity.
+- Clarify that `browser_action` is a protected tool contract, not the only capability sgClaw should ever have.
+- Clarify that prompt治理、安全摘要、skills、memory、routing should stay aligned with zeroclaw-native mechanisms.
+
+**Step 3: Run doc consistency checks**
+
+Run:
+
+```bash
+rg -n "浏览器智能体执行内核|单一 `browser_action` 工具|兼容执行器" docs
+rg -n "zeroclaw.*核心|特权工具面|安全加固" docs
+```
+
+Expected:
+- The first command should only return historical or explicitly marked current-state references.
+- The second command should show the new target framing in the mainline docs.
+
+**Step 4: Commit**
+
+```bash
+git add docs/README.md docs/L0-产品白皮书与能力全景层.md docs/L1-系统架构与安全模型层.md docs/L2-核心模块与接口契约层.md docs/L3-数据流与Skill体系层.md docs/L4-工程实现与部署拓扑层.md docs/L5-提示词分布与安全改造方案.md docs/浏览器对接标准.md
+git commit -m "docs: redefine sgclaw as hardened zeroclaw runtime"
+```
+
+## Task 2: Introduce A Zeroclaw-First Runtime Module
+
+**Files:**
+- Create: `src/runtime/mod.rs`
+- Create: `src/runtime/profile.rs`
+- Create: `src/runtime/tool_policy.rs`
+- Create: `src/runtime/engine.rs`
+- Modify: `src/lib.rs`
+- Test: `tests/runtime_profile_test.rs`
+
+**Intent:**
+- Create a real runtime namespace that represents sgClaw’s zeroclaw-first architecture.
+- Stop letting `compat/runtime.rs` be the place where product architecture is defined.
+
+**Step 1: Write the failing tests**
+
+Create `tests/runtime_profile_test.rs` with at least:
+
+```rust
+#[test]
+fn browser_attached_profile_exposes_browser_surface_without_becoming_browser_only() {
+    let profile = RuntimeProfile::BrowserAttached;
+    let policy = ToolPolicy::for_profile(profile);
+
+    assert!(policy.allowed_tools.contains("browser_action"));
+    assert!(policy.may_use_non_browser_tools);
+}
+
+#[test]
+fn general_assistant_profile_does_not_require_browser_surface() {
+    let profile = RuntimeProfile::GeneralAssistant;
+    let policy = ToolPolicy::for_profile(profile);
+
+    assert!(!policy.requires_browser_surface);
+}
+```
+
+**Step 2: Run the tests to confirm failure**
+
+Run:
+
+```bash
+cargo test --test runtime_profile_test -- --nocapture
+```
+
+Expected:
+- Fail with unresolved imports or missing types for `RuntimeProfile` and `ToolPolicy`.
+
+**Step 3: Add the minimal runtime module**
+
+Implement the first-pass skeleton:
+
+```rust
+pub enum RuntimeProfile {
+    BrowserAttached,
+    BrowserHeavy,
+    GeneralAssistant,
+}
+
+pub struct ToolPolicy {
+    pub requires_browser_surface: bool,
+    pub may_use_non_browser_tools: bool,
+    pub allowed_tools: Vec<String>,
+}
+```
+
+**Step 4: Re-run the focused tests**
+
+Run:
+
+```bash
+cargo test --test runtime_profile_test -- --nocapture
+```
+
+Expected:
+- Both new tests pass.
+
+**Step 5: Commit**
+
+```bash
+git add src/runtime/mod.rs src/runtime/profile.rs src/runtime/tool_policy.rs src/runtime/engine.rs src/lib.rs tests/runtime_profile_test.rs
+git commit -m "feat: add zeroclaw-first runtime module skeleton"
+```
+
+## Task 3: Replace DeepSeek-Only Settings With Zeroclaw-First SGClaw Settings
+
+**Files:**
+- Modify: `src/config/settings.rs`
+- Modify: `src/config/mod.rs`
+- Modify: `src/compat/config_adapter.rs`
+- Test: `tests/compat_config_test.rs`
+- Test: `tests/compat_memory_test.rs`
+- Test: `tests/compat_cron_test.rs`
+
+**Intent:**
+- Stop treating browser config as only a DeepSeek shim.
+- Introduce sgClaw settings that can express zeroclaw-first runtime behavior while staying backward-compatible with the existing `sgclaw_config.json`.
+
+**Step 1: Add the failing config tests**
+
+Add tests beside the existing ones in `tests/compat_config_test.rs`:
+
+```rust
+#[test]
+fn sgclaw_settings_default_to_compact_skills_and_browser_attached_profile() {
+    let settings = SgClawSettings::from_legacy_deepseek_fields(
+        "sk-test".into(),
+        "https://api.deepseek.com".into(),
+        "deepseek-chat".into(),
+        None,
+    ).unwrap();
+
+    assert_eq!(settings.runtime_profile, RuntimeProfile::BrowserAttached);
+    assert_eq!(settings.skills_prompt_mode, SkillsPromptMode::Compact);
+}
+
+#[test]
+fn sgclaw_settings_load_new_runtime_fields_from_browser_config() {
+    // write config with runtimeProfile / skillsPromptMode / allowedToolProfiles
+}
+```
+
+**Step 2: Run the focused tests**
+
+Run:
+
+```bash
+cargo test --test compat_config_test -- --nocapture
+```
+
+Expected:
+- Fail because `SgClawSettings`, `RuntimeProfile`, or new parsing fields do not exist yet.
+
+**Step 3: Implement backward-compatible settings expansion**
+
+Minimal target shape:
+
+```rust
+pub struct SgClawSettings {
+    pub provider_api_key: String,
+    pub provider_base_url: String,
+    pub provider_model: String,
+    pub skills_dir: Option<PathBuf>,
+    pub skills_prompt_mode: SkillsPromptMode,
+    pub runtime_profile: RuntimeProfile,
+}
+```
+
+Compatibility rules:
+- Existing `apiKey/baseUrl/model/skillsDir` continue to load.
+- New fields such as `skillsPromptMode` and `runtimeProfile` are optional.
+- Defaults should be hardened, not legacy-full-prompt by accident.
+
+**Step 4: Run the config and adapter tests**
+
+Run:
+
+```bash
+cargo test --test compat_config_test -- --nocapture
+cargo test --test compat_memory_test -- --nocapture
+cargo test --test compat_cron_test -- --nocapture
+```
+
+Expected:
+- All pass.
+
+**Step 5: Commit**
+
+```bash
+git add src/config/settings.rs src/config/mod.rs src/compat/config_adapter.rs tests/compat_config_test.rs tests/compat_memory_test.rs tests/compat_cron_test.rs
+git commit -m "feat: add zeroclaw-first sgclaw settings model"
+```
+
+## Task 4: Rebuild The Execution Path Around The New Runtime Engine
+
+**Files:**
+- Modify: `src/compat/runtime.rs`
+- Modify: `src/agent/mod.rs`
+- Modify: `src/compat/event_bridge.rs`
+- Test: `tests/compat_runtime_test.rs`
+
+**Intent:**
+- Make `compat/runtime.rs` a thin bridge into the new runtime engine instead of the place where the product’s core execution policy lives.
+- Keep browser-originated tasks attached to a browser surface, but do not collapse the runtime into a browser-only tool list.
+
+**Step 1: Add the failing runtime tests**
+
+Extend `tests/compat_runtime_test.rs` with at least:
+
+```rust
+#[test]
+fn compat_runtime_can_complete_a_text_only_turn_without_browser_tool_calls() {
+    // provider returns direct assistant content
+    // no BrowserMessage::Response is queued
+    // summary should still succeed
+}
+
+#[test]
+fn compat_runtime_allows_read_skill_under_compact_mode_policy() {
+    // configure compact skills mode
+    // verify the runtime tool policy includes read_skill
+}
+```
+
+**Step 2: Run the focused runtime test file**
+
+Run:
+
+```bash
+cargo test --test compat_runtime_test -- --nocapture
+```
+
+Expected:
+- Fail because the current runtime still hardcodes browser-only exposure or cannot express the new policy.
+
+**Step 3: Refactor the runtime path**
+
+Implementation target:
+
+- `src/agent/mod.rs` decides the runtime profile and passes browser context into the runtime engine.
+- `src/compat/runtime.rs` becomes a compatibility bridge, not the architecture center.
+- `src/runtime/engine.rs` owns:
+  - zeroclaw agent creation
+  - tool registration
+  - skill loading
+  - runtime profile application
+  - browser contract prompt injection only when browser surface is actually present
+
+**Step 4: Re-run the focused runtime tests**
+
+Run:
+
+```bash
+cargo test --test compat_runtime_test -- --nocapture
+```
+
+Expected:
+- Existing compat runtime tests still pass.
+- New text-only / compact-skill tests pass.
+
+**Step 5: Commit**
+
+```bash
+git add src/compat/runtime.rs src/agent/mod.rs src/compat/event_bridge.rs tests/compat_runtime_test.rs
+git commit -m "refactor: route browser requests through zeroclaw-first runtime engine"
+```
+
+## Task 5: Treat The Browser Pipe As A Privileged Tool Surface
+
+**Files:**
+- Modify: `src/compat/browser_tool_adapter.rs`
+- Modify: `src/pipe/protocol.rs`
+- Modify: `src/pipe/browser_tool.rs`
+- Modify: `src/security/mac_policy.rs`
+- Test: `tests/compat_browser_tool_test.rs`
+- Test: `tests/browser_tool_test.rs`
+- Test: `tests/pipe_protocol_test.rs`
+- Test: `tests/pipe_handshake_test.rs`
+
+**Intent:**
+- Keep the browser powerful, but explicitly as a protected external execution surface.
+- Preserve the current HMAC/MAC/rules boundary while making it obvious in code that browser execution is not synonymous with runtime execution.
+
+**Step 1: Add the failing tests**
+
+Examples:
+
+```rust
+#[test]
+fn browser_tool_contract_is_marked_as_privileged_surface_in_policy_metadata() {
+    // assert runtime metadata treats browser tool separately from generic tools
+}
+
+#[test]
+fn browser_submit_task_can_carry_browser_context_without_forcing_browser_only_execution() {
+    // protocol/adapter level test
+}
+```
+
+**Step 2: Run the safety-related tests**
+
+Run:
+
+```bash
+cargo test --test compat_browser_tool_test -- --nocapture
+cargo test --test browser_tool_test -- --nocapture
+cargo test --test pipe_protocol_test -- --nocapture
+cargo test --test pipe_handshake_test -- --nocapture
+```
+
+Expected:
+- Fail on new privilege/metadata expectations before implementation.
+
+**Step 3: Implement the policy split**
+
+Implementation target:
+- keep `browser_action` schema constrained
+- keep `MacPolicy` as the final guard on outbound browser commands
+- annotate browser surface metadata in the runtime/tool policy layer
+- avoid leaking browser-only assumptions into generic runtime config
+
+**Step 4: Re-run the focused browser safety tests**
+
+Run the same four commands from Step 2.
+
+Expected:
+- All pass.
+
+**Step 5: Commit**
+
+```bash
+git add src/compat/browser_tool_adapter.rs src/pipe/protocol.rs src/pipe/browser_tool.rs src/security/mac_policy.rs tests/compat_browser_tool_test.rs tests/browser_tool_test.rs tests/pipe_protocol_test.rs tests/pipe_handshake_test.rs
+git commit -m "feat: model browser pipe as privileged runtime surface"
+```
+
+## Task 6: Restore Zeroclaw-Native Skills Instead Of Browser-Specific Skill Prompt Hacks
+
+**Files:**
+- Modify: `src/runtime/engine.rs`
+- Modify: `src/compat/event_bridge.rs`
+- Modify: `src/agent/mod.rs`
+- Test: `tests/compat_runtime_test.rs`
+- Test: `tests/skill_lib_validation_test.py`
+
+**Intent:**
+- Make skill loading and skill usage follow zeroclaw-native behavior first.
+- Prefer compact mode plus `read_skill` when safe.
+- Make skill usage observable in runtime logs so the browser UI can explain what happened.
+
+**Step 1: Add the failing skill-observability tests**
+
+Add tests for:
+- compact mode includes `read_skill`
+- runtime logs show when `read_skill` or skill-defined tools are invoked
+- configured `skillsDir` still resolves both repo-root and nested `skills/` layouts
+
+**Step 2: Run the skill-related tests**
+
+Run:
+
+```bash
+cargo test --test compat_runtime_test -- --nocapture
+python3 tests/skill_lib_validation_test.py
+```
+
+Expected:
+- New observability assertions fail before implementation.
+
+**Step 3: Implement the minimal skill-first runtime behavior**
+
+Implementation target:
+- compact skills mode becomes the sgClaw default unless explicitly overridden
+- `read_skill` is allowed when the active tool policy permits it
+- runtime logs include loaded skill names and actual skill/tool usage
+
+**Step 4: Re-run the skill tests**
+
+Run the same two commands from Step 2.
+
+Expected:
+- Both pass.
+
+**Step 5: Commit**
+
+```bash
+git add src/runtime/engine.rs src/compat/event_bridge.rs src/agent/mod.rs tests/compat_runtime_test.rs tests/skill_lib_validation_test.py
+git commit -m "feat: restore zeroclaw-native skill flow and observability"
+```
+
+## Task 7: Remove Or Quarantine The Legacy Parallel Runtime Paths
+
+**Files:**
+- Modify or delete: `src/agent/runtime.rs`
+- Modify or delete: `src/agent/planner.rs`
+- Modify: `tests/agent_runtime_test.rs`
+- Modify: `tests/planner_test.rs`
+- Modify: `docs/L2-核心模块与接口契约层.md`
+- Modify: `docs/L3-数据流与Skill体系层.md`
+
+**Intent:**
+- Stop shipping multiple conceptual runtimes.
+- If the light runtime/planner path still has value, mark it as legacy/dev-only.
+- If it has no production value, remove it after the zeroclaw-first runtime is stable.
+
+**Step 1: Decide the disposition**
+
+Choose one:
+
+```text
+A. delete planner/runtime legacy path
+B. keep as explicit legacy/dev-only module with zero production routing
+```
+
+Recommendation: `B` first, then `A` after one clean release cycle.
+
+**Step 2: Add the failing cleanup tests**
+
+Examples:
+- production browser path never routes into planner fallback
+- docs no longer describe planner fallback as the primary model-enabled path
+
+**Step 3: Run the legacy-path tests**
+
+Run:
+
+```bash
+cargo test --test agent_runtime_test -- --nocapture
+cargo test --test planner_test -- --nocapture
+```
+
+Expected:
+- Fail once the cleanup assertions are added.
+
+**Step 4: Apply the cleanup**
+
+Implementation target:
+- remove production routing dependency
+- rename or mark legacy modules clearly
+- update docs to match the new reality
+
+**Step 5: Re-run the legacy-path tests and commit**
+
+Run the same two commands, then:
+
+```bash
+git add src/agent/runtime.rs src/agent/planner.rs tests/agent_runtime_test.rs tests/planner_test.rs docs/L2-核心模块与接口契约层.md docs/L3-数据流与Skill体系层.md
+git commit -m "refactor: quarantine legacy browser-only runtime paths"
+```
+
+## Task 8: Align The Browser UI With The New Runtime Truth
+
+**Files:**
+- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js`
+- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts`
+- Modify: `/home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts`
+- Modify: `/home/zyl/projects/superRpa/src/AGENTS.md`
+
+**Intent:**
+- Make the browser UI an honest client of the runtime.
+- Stop labeling all tasks as “网页执行” when the runtime may have solved them through non-browser zeroclaw capabilities.
+
+**Step 1: Add the UI contract checklist**
+
+Checklist:
+
+```text
+1. UI shows runtime profile or capability mode
+2. UI can show whether browser tools were actually used
+3. UI can show when skills were read or invoked
+4. wording does not imply browser is the whole runtime
+```
+
+**Step 2: Implement the label and observability changes**
+
+Examples:
+- replace fixed “网页执行” copy with runtime-derived capability wording
+- add a compact “本轮调用”/“能力来源” section
+- avoid implying every successful task came from page automation
+
+**Step 3: Verify browser resources**
+
+Run:
+
+```bash
+node --check /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js
+/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests
+autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome
+```
+
+Expected:
+- All pass.
+
+**Step 4: Commit**
+
+```bash
+git -C /home/zyl/projects/superRpa/src add chrome/browser/resources/superrpa/sgclaw_overlay.js chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.html.ts chrome/browser/resources/superrpa/devtools/functions/sgclaw-chat/sgclaw-chat.css.ts AGENTS.md
+git -C /home/zyl/projects/superRpa/src commit -m "feat: align browser ui with zeroclaw-first runtime"
+```
+
+## Final Verification Matrix
+
+Run, in order:
+
+```bash
+cargo test --test runtime_profile_test -- --nocapture
+cargo test --test compat_config_test -- --nocapture
+cargo test --test compat_runtime_test -- --nocapture
+cargo test --test compat_browser_tool_test -- --nocapture
+cargo test --test browser_tool_test -- --nocapture
+cargo test --test pipe_protocol_test -- --nocapture
+cargo test --test pipe_handshake_test -- --nocapture
+cargo test --test agent_runtime_test -- --nocapture
+cargo test --test planner_test -- --nocapture
+python3 tests/skill_lib_validation_test.py
+```
+
+If local Cargo registry state is unstable, use the Chromium hermetic wrapper instead:
+
+```bash
+python3 /home/zyl/projects/superRpa/src/tools/crates/run_cargo.py test --manifest-path /home/zyl/projects/sgClaw/claw/Cargo.toml -- --nocapture
+```
+
+Then verify browser integration:
+
+```bash
+node --check /home/zyl/projects/superRpa/src/chrome/browser/resources/superrpa/sgclaw_overlay.js
+/home/zyl/projects/superRpa/src/out/KylinRelease/functions_ui_mainline_unittests
+autoninja -C /home/zyl/projects/superRpa/src/out/KylinRelease chrome
+```
+
+## Success Criteria
+
+- The docs say the right thing before the code change begins.
+- `sgclaw` behaves like a security-hardened zeroclaw runtime, not a browser-only compat shell.
+- The browser pipe remains central for protected execution, but it is no longer mistaken for the whole product architecture.
+- Skills, prompt building, memory, routing, and tool policy all flow through zeroclaw-native mechanisms first.
+- The UI becomes a thin, honest client of the shared runtime.