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/L0-产品白皮书与能力全景层.md
+++ b/docs/L0-产品白皮书与能力全景层.md
@@ -8,15 +8,15 @@

 ## 1. 产品定义

-sgClaw 是一个嵌入企业浏览器运行环境中的浏览器智能体执行内核。它的职责不是替代整个平台，也不是承诺“全自动数字员工”，而是把自然语言任务转换成受控的浏览器操作，并通过既有浏览器宿主完成页面执行。
+sgClaw 不是“浏览器智能体执行内核”意义上的 browser-only 产品。更准确地说，它是一个嵌入企业浏览器运行环境中的、安全加固后的 zeroclaw runtime：zeroclaw 负责智能体能力本体，sgClaw 负责把这些能力包裹进受控的执行边界中。

-ZeroClaw 重构之后，sgClaw 的产品形态可以概括为三件事：
+它的职责不是替代整个平台，也不是承诺“全自动数字员工”，而是：

-1. 把用户任务接入统一的 Agent 执行入口。
-2. 通过固定的 `browser_action` 工具把意图翻译为浏览器命令。
-3. 在协议、域名和动作白名单的约束下完成可审计的页面操作。
+1. 以 zeroclaw 为核心提供统一的 Agent 执行入口、prompt/skills/memory/tool routing 能力。
+2. 通过 sgClaw 的 pipe、HMAC、MAC Policy 和宿主二次校验，把高风险执行面收敛成受保护的工具表面。
+3. 在浏览器场景下，把页面操作能力作为特权工具面暴露给 runtime，而不是让浏览器反过来定义整个 runtime。

-当前仓库中的 sgClaw 不是一个完整前端产品，也不是浏览器发行版本身，而是“浏览器 Agent Runtime + Pipe 协议 + ZeroClaw 兼容层”的产品核心。
+当前仓库中的 sgClaw 不是一个完整前端产品，也不是浏览器发行版本身，而是“vendored zeroclaw core + sgClaw 安全封装层 + browser host integration”的产品核心。

 ---

@@ -24,17 +24,20 @@ ZeroClaw 重构之后，sgClaw 的产品形态可以概括为三件事：

 ### 2.1 当前已经落地的能力

+- 已 vendored `zeroclaw`，并通过 Rust 运行时接入 provider、skills、memory 等核心能力入口。
 - 浏览器侧通过 STDIO JSON Line 协议与 Rust 进程通信。
 - 启动时执行 `init -> init_ack` 握手，并建立会话级 HMAC 密钥。
 - 任务输入统一走 `submit_task` 消息。
 - Rust 侧支持两条执行路径：
  - 未配置大模型时，使用仓库内置 planner/fallback 逻辑。
  - 配置 `DEEPSEEK_*` 环境变量时，切换到 ZeroClaw compatibility runtime。
- 当前有效工具面收敛为一个工具：`browser_action`。
+- 当前真正稳定落地的特权执行面收敛为一个工具：`browser_action`。
 - 当前真正开放给模型的动作仅 4 个：`click`、`type`、`navigate`、`getText`。
 - 所有浏览器动作都受 `resources/rules.json` 中的域名和动作白名单约束。
 - 执行过程中会向宿主发送结构化日志和最终任务结果。

+注意：上述“browser-first + compat-only”是当前实现状态，不是目标产品定义。主线目标仍然是“安全加固后的 zeroclaw runtime”，而不是“只会操作浏览器的 agent”。
+
 ### 2.2 当前明确不宣称的能力

 以下内容在旧文档中存在较多规划性描述，但并非当前仓库中的已实现事实：
@@ -45,6 +48,7 @@ ZeroClaw 重构之后，sgClaw 的产品形态可以概括为三件事：
 - 完整的浏览器 Side Panel 产品界面。
 - 40+ 页面动作在 Agent 侧全部开放。
 - 真实生产级多租户、审计后台、任务编排中心。
+- “浏览器是 sgClaw 的全部 runtime” 这种定义。

 这些能力可以保留为后续扩展方向，但不应继续写入 L0-L4 作为现状描述。

@@ -52,7 +56,7 @@ ZeroClaw 重构之后，sgClaw 的产品形态可以概括为三件事：

 ## 3. 产品价值主张

-ZeroClaw 重构后的 sgClaw，核心价值不在“功能堆叠”，而在于把原本分散的浏览器自动化能力收敛成一个可控、可替换、可验证的智能体执行底座。
+ZeroClaw 重构后的 sgClaw，核心价值不在“功能堆叠”，也不在“单纯浏览器自动化”，而在于把 zeroclaw 的智能体能力放进一个可控、可替换、可验证的安全执行底座里。

 ### 3.1 对业务侧

@@ -62,15 +66,15 @@ ZeroClaw 重构后的 sgClaw，核心价值不在“功能堆叠”，而在于

 ### 3.2 对集成侧

- 浏览器宿主只需实现固定协议，不必理解模型内部细节。
- Agent Runtime 可以在保留宿主协议的前提下切换实现策略。
- ZeroClaw 兼容层把未来模型、记忆、工具调度的升级入口预留在 Rust 侧。
+- 浏览器宿主只需实现固定协议和宿主侧安全复检，不必理解模型内部细节。
+- sgClaw Runtime 可以在保留宿主协议的前提下演进 zeroclaw 配置、skills 和工具策略。
+- 浏览器只是一个受保护执行面；未来其它客户端也应复用同一 runtime，而不是另起一套架构。

 ### 3.3 对安全侧

- 不是“模型可任意操作浏览器”，而是“模型只能调用被允许的动作”。
- 安全边界前置到协议和 MAC Policy，而不是把约束留给提示词。
- 域名、动作、HMAC 三类控制共同组成最小可信执行面。
+- 不是“模型可任意操作浏览器”，而是“runtime 只能通过被授权的特权工具面触发高风险动作”。
+- 安全边界前置到协议、MAC Policy、宿主二次校验和运行时工具策略，而不是把约束留给提示词。
+- 域名、动作、HMAC 与工具暴露策略共同组成最小可信执行面。

 ---

@@ -80,15 +84,16 @@ ZeroClaw 重构后的 sgClaw，核心价值不在“功能堆叠”，而在于
 |---|---|---|
 | 任务接入 | 已实现 | 接收浏览器宿主发来的 `submit_task` 指令 |
 | 协议握手 | 已实现 | 统一版本、会话标识、HMAC 种子交换 |
-| Agent 执行 | 已实现 | planner fallback 与 ZeroClaw compat 共存 |
-| 浏览器工具 | 已实现 | 单一 `browser_action` 工具 |
+| zeroclaw Core | 已接入但未充分释放 | prompt、skills、memory、provider routing 的能力本体已经在仓库中 |
+| Agent 执行 | 已实现但仍处过渡态 | planner fallback 与 browser-first ZeroClaw compat 共存 |
+| 浏览器特权工具面 | 已实现 | 通过 `browser_action` 暴露受保护的浏览器执行能力 |
 | 核心动作 | 已实现 | `click/type/navigate/getText` |
 | 域名白名单 | 已实现 | 仅允许规则文件中的域名 |
 | 动作白名单 | 已实现 | 仅允许规则文件中的动作 |
 | 结构化日志 | 已实现 | `log_entry` 与 `task_complete` 回传 |
 | 扩展动作枚举 | 已预留 | 协议枚举已定义，但默认未开放 |
-| Skill 引擎 | 未独立实现 | 当前仅保留“可被工具和提示词扩展”的语义入口 |
-| MCP 生态 | 未在主链路启用 | ZeroClaw 兼容层为后续保留位置 |
+| Skill 体系 | 已 vendored 但运行时只部分使用 | 应复用 zeroclaw 原生机制，而不是另起一套浏览器专用技能系统 |
+| MCP 生态 | 未在主链路启用 | 未来可接入，但仍应服从 sgClaw 安全封装 |

 ---

@@ -109,13 +114,13 @@ ZeroClaw 重构后的 sgClaw，核心价值不在“功能堆叠”，而在于
 当页面元素定位规则明确时，系统可用 `click` 和 `type` 组合完成表单录入、按钮点击、简单提交等动作。  
 是否能覆盖完整业务流程，取决于浏览器宿主是否提供对应页面、选择器和回包信息，而不是文档层面预设“所有流程都能端到端执行”。

-### 5.3 作为更大产品中的 Agent 执行核
+### 5.3 作为更大产品中的安全执行核

 sgClaw 更适合被理解为产品底座中的一个执行核：

 - 上层可以接入任务输入框、审批入口或业务编排器。
- 下层通过既有浏览器控制面执行。
- 中间由 sgClaw 把自然语言与浏览器动作连接起来。
+- 下层可以通过既有浏览器控制面执行，也可以在未来接入其它受保护工具面。
+- 中间由 sgClaw 把 zeroclaw runtime 与外部受控执行面连接起来。

 ---

--- a/docs/L1-系统架构与安全模型层.md
+++ b/docs/L1-系统架构与安全模型层.md
@@ -8,25 +8,34 @@

 ## 1. 架构总览

-重构后的 sgClaw 架构要点很简单：浏览器宿主负责页面执行，Rust 进程负责任务解释与协议编排，ZeroClaw 作为兼容运行时被接入到 Rust 侧，而不是直接替代整个系统。
+重构后的 sgClaw 架构要点应当这样理解：zeroclaw 是能力本体，sgClaw 是安全封装层，浏览器宿主是一个受保护的特权执行面。当前代码尚未完全落到这个目标结构，但主线架构口径必须先统一。

 ```
 ┌──────────────────────────────┐
 │ Browser Host / Chromium Side │
 │ - 启动 sgClaw 子进程          │
 │ - 发送 init / submit_task     │
-│ - 执行 command 并回 response  │
+│ - 复检 HMAC / domain / params │
+│ - 执行 browser command 并回包 │
 └──────────────┬───────────────┘
               │ STDIO + JSON Line
 ┌──────────────▼───────────────┐
-│ sgClaw Rust Runtime          │
+│ sgClaw Security Envelope     │
 │ - 握手与消息循环              │
 │ - MAC Policy                 │
 │ - BrowserPipeTool            │
-│ - Planner fallback           │
-│ - ZeroClaw compat runtime    │
+│ - Runtime / Tool Policy      │
+│ - Config Adaptation          │
 └──────────────┬───────────────┘
-               │ Provider API / Local Config
+               │ zeroclaw APIs / Local Config
+┌──────────────▼───────────────┐
+│ ZeroClaw Core Runtime        │
+│ - Prompt Builder             │
+│ - Skills / Memory            │
+│ - Tool Loop / Routing        │
+│ - Provider Dispatch          │
+└──────────────┬───────────────┘
+               │ Provider API / Optional Tools
 ┌──────────────▼───────────────┐
 │ Model Provider               │
 │ - DeepSeek/OpenAI-compatible │
@@ -34,7 +43,7 @@
 └──────────────────────────────┘
 ```

-架构上最重要的变化是：当前系统不是“完整 ZeroClaw 产品”，而是“保留现有浏览器协议的前提下，把 ZeroClaw 作为兼容执行内核引入”。
+架构上最重要的变化是：sgClaw 不应被定义为“浏览器专用 agent”，而应被定义为“保留现有浏览器协议前提下，对 zeroclaw 做安全化封装的运行时分发”。

 ---

@@ -50,7 +59,7 @@

 sgClaw 仓库本身不包含 Chromium/C++ 实现代码，因此 L1 只定义宿主责任边界，不再把外部仓库中的假定文件结构写成“当前仓库现状”。

-### 2.2 Rust 控制层
+### 2.2 sgClaw 安全/控制层

 Rust 侧是当前仓库的事实主体，职责包括：

@@ -58,10 +67,20 @@ Rust 侧是当前仓库的事实主体，职责包括：
 - 完成握手、加载 `rules.json`、创建 `BrowserPipeTool`。
 - 在消息循环中接收浏览器消息并分发到执行层。
 - 把执行日志和任务结果回传给宿主。
+- 决定哪些 zeroclaw 能力能够暴露给当前运行环境。

-### 2.3 执行层
+### 2.3 zeroclaw 核心层

-执行层当前有两条路径：
+主线目标中，zeroclaw 应承担：
+
+- prompt/system sections 组装
+- skills / memory / routing
+- tool loop 与 provider 协调
+- 通用 agent 能力而非仅浏览器能力
+
+### 2.4 当前实现的过渡态
+
+当前执行层仍有两条路径：

 1. `planner fallback`  
 说明：当未配置 `DEEPSEEK_API_KEY` 等环境变量时，使用仓库内置的轻量 planner 执行。
@@ -69,23 +88,25 @@ Rust 侧是当前仓库的事实主体，职责包括：
 2. `ZeroClaw compat runtime`  
 说明：当提供模型配置后，通过 [`src/compat/runtime.rs`](/home/zyl/projects/sgClaw/claw/src/compat/runtime.rs) 构造 provider、memory 和 `browser_action` 工具，把任务交给 vendored ZeroClaw Agent。

-这两条路径共存，是当前重构期的核心现实。文档必须保留这一点，否则会误导实现和联调。
+这两条路径是当前代码现实，但都不应被写成长期产品定义。长期目标是“zeroclaw-first runtime + sgClaw security layer”，而不是 browser-only compat。

 ---

 ## 3. ZeroClaw 重构的架构意义

-ZeroClaw 在本项目中的角色不是“大而全框架接管一切”，而是解决三个具体问题：
+ZeroClaw 在本项目中的角色不是“大而全框架接管一切”，也不是“被 sgClaw 套壳后只剩一个 browser_action 工具”，而是系统能力本体。sgClaw 应该在它上面解决三个具体问题：

- 统一模型 Provider 抽象。
- 为后续记忆、工具调度、可观测性留出标准扩展位。
- 在不改浏览器协议的前提下，替换任务执行内核。
+- 统一模型 Provider 抽象、skills、memory 和 tool loop。
+- 在不改浏览器协议的前提下，把高风险执行约束到受保护的工具面。
+- 让浏览器成为特权执行面，而不是反过来让浏览器定义整个 runtime。

 当前兼容层的限制也必须明确：

 - 只注册一个工具：`browser_action`。
 - 只开放 4 个动作：`click/type/navigate/getText`。
- 不以 ZeroClaw 的全量工具生态作为对外能力宣称。
+- 不以 ZeroClaw 的全量工具生态作为当前对外能力宣称。
+
+这些限制是当前实现状态，不是目标架构原则。

 ---

@@ -142,21 +163,21 @@ ZeroClaw 在本项目中的角色不是“大而全框架接管一切”，而
 原因：

 - 浏览器宿主联调成本最低。
- Rust 侧可以独立迭代 planner 和 ZeroClaw 路径。
+- Rust 侧可以独立演进 zeroclaw runtime 与安全策略，而不破坏宿主联调。
 - 产品文档、测试和协议标准可以围绕同一条 contract 收敛。

-### 5.3 先做最小工具面，再扩动作
+### 5.3 先做最小特权工具面，再扩动作

 原因：

 - 当前最稳定的是 `click/type/navigate/getText`。
- 动作越多，宿主和模型之间的契约越难稳定。
+- 动作越多，宿主和 runtime 之间的契约越难稳定。
 - 在规则文件仍只开放 4 个动作的前提下，文档不应提前放大能力范围。

 ---

 ## 6. 架构结论

-L1 层面可以把 sgClaw 定义为：一个通过固定浏览器协议接入宿主、以 Rust 为控制层、以 ZeroClaw 为兼容执行核、以 MAC Policy 为最小安全边界的浏览器智能体运行时。
+L1 层面可以把 sgClaw 定义为：一个通过固定浏览器协议接入宿主、以 Rust 为安全与控制层、以 zeroclaw 为能力核心、以 MAC Policy 与宿主复检为受保护执行边界的安全加固运行时分发。

-这一定义与当前仓库实现保持一致，也为后续继续扩展动作、工具和记忆系统保留了清晰边界。
+这一定义既承认当前仓库仍存在 browser-first compat 的过渡实现，也为后续把 runtime 真正收口到 zeroclaw-first 主线保留了清晰边界。
--- a/docs/L2-核心模块与接口契约层.md
+++ b/docs/L2-核心模块与接口契约层.md
@@ -24,14 +24,15 @@ src/
 └── security/
 ```

-模块边界按职责划分为四层：
+模块边界按职责划分为五层：

 | 层级 | 模块 | 责任 |
 |---|---|---|
 | 传输层 | `pipe` | 定义消息、握手、序列号、收发与命令等待 |
-| 控制层 | `lib.rs`、`agent` | 接收任务、选择执行路径、回传日志与结果 |
-| 兼容层 | `compat` | 对接 vendored ZeroClaw，暴露单一 `browser_action` |
-| 安全层 | `security`、`resources/rules.json` | 域名与动作白名单控制 |
+| 安全层 | `security`、`resources/rules.json` | 域名、动作与 pipe 命令边界控制 |
+| 运行时入口层 | `lib.rs`、`agent` | 接收任务、选择执行路径、回传日志与结果 |
+| 适配层 | `compat`、`config` | 把 sgClaw 宿主环境映射到 zeroclaw 运行时；当前仍带有过渡性限制 |
+| 核心能力层 | `third_party/zeroclaw` | prompt、skills、memory、tool loop、provider 抽象 |

 ---

@@ -51,13 +52,13 @@ src/

 ### 2.2 `src/agent/mod.rs`

-[`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs) 决定执行路径：
+[`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs) 当前决定执行路径：

 - 收到 `BrowserMessage::SubmitTask` 时优先尝试读取 `DeepSeekSettings`。
 - 环境配置存在，则走 `compat::runtime::execute_task`。
 - 环境配置不存在，则走内置 planner fallback。

-这就是当前系统的“路由器”。
+这就是当前系统的“路由器”。但文档上应把它理解为过渡性 runtime selector，而不是最终产品架构中心。

 ### 2.3 `src/agent/runtime.rs`

@@ -70,7 +71,7 @@ src/

 ### 2.4 `src/compat/runtime.rs`

-[`src/compat/runtime.rs`](/home/zyl/projects/sgClaw/claw/src/compat/runtime.rs) 是 ZeroClaw 重构的关键模块：
+[`src/compat/runtime.rs`](/home/zyl/projects/sgClaw/claw/src/compat/runtime.rs) 是当前 ZeroClaw 接入的关键模块：

 - 负责构造 ZeroClaw config。
 - 负责创建 provider。
@@ -81,11 +82,12 @@ src/

 - 当前 compat 层只向 ZeroClaw 注册一个工具。
 - `allowed_tools` 被收敛到 `browser_action`。
- 这意味着 ZeroClaw 在本项目中是“兼容执行器”，不是“多工具平台”。
+- 这意味着当前代码还没有把 sgClaw 做成 zeroclaw-first runtime。
+- 这是一种实现限制，不应被文档提升为产品原则。

 ### 2.5 `src/pipe/browser_tool.rs`

-该模块承担真实浏览器命令发送职责：
+该模块承担真实浏览器命令发送职责，也是当前系统中最重要的特权工具面桥接层：

 - 为每个命令分配 `seq`。
 - 计算 HMAC。
@@ -93,11 +95,11 @@ src/
 - 阻塞等待对应 `BrowserMessage::Response`。
 - 在超时、响应错配、校验失败时返回错误。

-它是 Rust 侧最重要的协议执行点。
+它是 Rust 侧最重要的协议执行点。架构上应把它理解为“privileged browser surface adapter”，而不是“整个 runtime 本体”。

 ### 2.6 `src/security/mac_policy.rs`

-安全策略只认规则文件，不认模型意图。  
+安全策略只认规则文件与 pipe contract，不认模型意图。
 规则来源为 [`resources/rules.json`](/home/zyl/projects/sgClaw/claw/resources/rules.json)，当前默认约束是：

 - 允许域名：`oa.example.com`、`erp.example.com`、`hr.example.com` 及 demo 域名。
@@ -235,6 +237,8 @@ L2 是产品内核视角的契约说明。两者关系如下：
 2. `src/agent/runtime.rs` 的 tool definition
 3. `src/compat/browser_tool_adapter.rs` 的 `parameters_schema` 与 `parse_action`

+这三者表达的是“当前特权浏览器工具面”的开放范围，而不是 sgClaw 整体 runtime 的长期能力上限。
+
 ---

 ## 5. `browser_action` 工具契约
--- a/docs/L3-数据流与Skill体系层.md
+++ b/docs/L3-数据流与Skill体系层.md
@@ -10,32 +10,32 @@

 ## 1. 端到端数据流

-当前主链路的数据流如下：
+主线目标中的数据流应当如下：

 ```
-Browser Host
-  └─ submit_task
+Client Surface
+  └─ submit_task (+ optional browser context)
       ↓
 sgClaw Transport / Handshake
-  └─ handle_browser_message
+  └─ sgClaw security envelope
       ↓
-Execution Path Select
-  ├─ planner fallback
-  └─ zeroclaw compat runtime
+ZeroClaw-first runtime
+  └─ runtime profile / tool policy
       ↓
-browser_action
-       ↓
-AgentMessage::Command
-       ↓
-Browser executes action
-       ↓
-BrowserMessage::Response
+Tool execution
+  ├─ browser_action -> pipe -> browser host -> response
+  └─ non-browser-safe future surfaces only when policy allows
       ↓
 log_entry / task_complete
 ```

-这条链路里没有独立 Skill 执行器，也没有独立任务编排数据库。  
-因此 L3 的重点不再是“描述一个理想化智能体平台”，而是说明当前仓库里真实存在的数据流状态机。
+当前代码与上述目标之间仍有过渡态偏差：
+
+- 浏览器是当前唯一成熟的特权工具面。
+- `planner fallback` 与 browser-first `compat runtime` 仍然并存。
+- `zeroclaw` 已 vendored，但运行时还没有完全按 zeroclaw-first 方式释放能力。
+
+因此 L3 既要说明目标数据流，也要明确指出当前代码仍处于过渡收口阶段。

 ---

@@ -52,15 +52,15 @@ log_entry / task_complete

 ### 2.2 任务接收阶段

-宿主发送：
+浏览器宿主当前发送：

 ```json
 { "type": "submit_task", "instruction": "..." }
 ```

-Rust 侧在 [`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs) 中接收后，不直接执行页面命令，而是先决定走哪条执行路径。
+Rust 侧在 [`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs) 中接收后，不应被理解为“直接开始网页自动化”，而是先决定当前任务使用什么 runtime/profile，并判断浏览器上下文是否真的必要。

-### 2.3 执行路径选择
+### 2.3 当前执行路径选择（过渡态）

 #### 路径 A：planner fallback

@@ -108,7 +108,7 @@ Rust 侧在 [`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs
 6. 形成观察结果  
 说明：根据 `success`、`data`、`aom_snapshot` 和 `timing` 形成下一步输入或最终结果。

-这意味着“智能体行为”和“浏览器动作执行”之间的接口已经被压缩到非常薄的一层，这是 ZeroClaw 重构最有价值的结构变化。
+这意味着“runtime 决策”和“浏览器动作执行”之间的接口已经被压缩到非常薄的一层，这是 sgClaw 作为 zeroclaw 安全封装层最有价值的结构变化。

 ---

@@ -144,26 +144,28 @@ Rust 侧在 [`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs

 “L3 是灵魂”的前提，不是把 Skill 写得越来越玄，而是把 Skill 在当前阶段的真实语义说清楚。

-### 5.1 当前不存在独立 Skill 引擎
+### 5.1 当前不应再设计独立于 zeroclaw 的 Skill 引擎

-当前仓库中没有独立的：
+当前仓库中不应再把 Skill 理解为浏览器专用外挂子系统。sgClaw 已经 vendored zeroclaw，自带的 skill 体系才是主线。需要注意的是，当前运行时对它的使用仍不充分。
+
+当前代码仍缺少或未完全释放的部分包括：

 - Skill 脚本目录加载流程
 - Skill 注册表
 - Skill 沙箱执行器
 - Skill 版本与签名校验主链路

-因此不能再把 Skill 描述为已落地子系统。
+因此文档上不能再把 Skill 描述为“浏览器侧另起一套引擎”，而应描述为“应复用 zeroclaw-native 机制的能力层，当前实现仍在收口”。

 ### 5.2 当前可以保留的 Skill 语义

-在 ZeroClaw 重构版里，Skill 更准确的含义是：
+在 sgClaw 的主线架构里，Skill 更准确的含义是：

- 面向未来的“可复用任务模式”抽象。
- 可能由提示词、模板、预设工具组合或 planner 规则来承载。
- 最终仍要落到统一的 `browser_action` 契约。
+- 由 zeroclaw 管理的可复用任务模式、提示规范和可调用工具组合。
+- 在 compact/full 模式下进入 system prompt 或按需通过 `read_skill` 读取。
+- 当任务需要浏览器时，最终可落到统一的 `browser_action` 契约；当任务不需要浏览器时，不应强行绕浏览器一圈。

-换句话说，当前 Skill 不是一个运行时目录，而是一种产品与执行层之间的抽象语言。
+换句话说，Skill 不是“浏览器脚本目录”的别名，而是 zeroclaw runtime 的一部分。

 ### 5.3 Skill 演进约束

@@ -185,7 +187,7 @@ Rust 侧在 [`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs
 - `DEEPSEEK_BASE_URL`
 - `DEEPSEEK_MODEL`

-这些配置决定是否启用 compat runtime，以及模型请求如何路由。
+这些配置当前决定是否启用 compat runtime，以及模型请求如何路由。长期看，它们应收敛为 zeroclaw-first 的 sgClaw runtime 配置，而不是永远停留在 DeepSeek shim。

 ### 6.2 记忆

@@ -199,10 +201,10 @@ ZeroClaw compat 路径中已经接入 memory adapter，但在产品能力层面

 ## 7. L3 结论

-L3 的核心不是“把所有未来能力都放进一个宏大数据流图”，而是说明当前系统如何把自然语言任务压缩成可验证、可回包、可受控的浏览器动作。
+L3 的核心不是“把所有未来能力都放进一个宏大数据流图”，也不是“把所有任务都解释成浏览器动作”，而是说明 sgClaw 如何把任务先交给 zeroclaw runtime，再把其中需要高风险外部执行的部分压缩成可验证、可回包、可受控的浏览器动作。

 重构后的灵魂有三点：

 - 任务入口统一。
- 动作契约统一。
- 执行路径可替换，但协议和安全边界不变。
+- runtime 核心统一到 zeroclaw。
+- 特权工具面可替换，但协议和安全边界不变。
--- a/docs/L4-工程实现与部署拓扑层.md
+++ b/docs/L4-工程实现与部署拓扑层.md
@@ -44,7 +44,7 @@ claw/
    └── archive/
 ```

-工程上应把 `third_party/zeroclaw` 理解为“已 vendored 的兼容依赖”，而不是单独维护的兄弟项目。
+工程上应把 `third_party/zeroclaw` 理解为“已 vendored 的能力核心”，而不是单独维护的兄弟项目，也不是只用于兼容的附属依赖。

 ---

@@ -83,10 +83,15 @@ claw/

 职责：

- 决定 fallback 或 compat 执行。
- 把统一工具契约映射到浏览器协议。
+- 当前决定 fallback 或 compat 执行。
+- 把受保护的浏览器工具契约映射到浏览器协议。
 - 在 ZeroClaw turn 事件与宿主日志之间做桥接。

+说明：
+
+- `src/agent/runtime.rs` 与 `src/agent/planner.rs` 属于过渡性轻量路径，不应再被写成长期产品主线。
+- 主线目标应是“sgClaw security layer + zeroclaw core runtime”，而不是长期保留 browser-only compat 分叉。
+
 ### 2.4 安全与配置

 - [`src/security/mac_policy.rs`](/home/zyl/projects/sgClaw/claw/src/security/mac_policy.rs)
@@ -96,7 +101,7 @@ claw/
 职责：

 - 维护运行时安全边界。
- 从环境变量读取 provider 配置。
+- 读取 provider / skills 等运行时配置，并逐步向 zeroclaw-first 配置模型收敛。

 ---

@@ -130,7 +135,7 @@ sgClaw 不是独立交互式 CLI 产品，正常运行前提是：

 ### 3.3 模型配置

-启用 ZeroClaw compat runtime 的关键环境变量：
+当前启用 ZeroClaw compat runtime 的关键环境变量：

 ```bash
 DEEPSEEK_API_KEY=...
@@ -138,7 +143,31 @@ DEEPSEEK_BASE_URL=...
 DEEPSEEK_MODEL=...
 ```

-若这些变量不存在或不完整，系统会退回 planner fallback。
+若这些变量不存在或不完整，系统会退回 planner fallback。这个行为是当前实现状态，不是长期架构推荐。
+
+### 3.4 浏览器配置文件
+
+当宿主以 `--config-path=<workspace_root>/sgclaw_config.json` 拉起 `sgclaw` 时，`sgclaw` 会自己读取该 JSON 文件，而不是要求宿主额外复制 skills。
+
+当前支持的关键字段：
+
+```json
+{
+  "apiKey": "sk-...",
+  "baseUrl": "https://api.deepseek.com",
+  "model": "deepseek-chat",
+  "skillsDir": "skill_lib"
+}
+```
+
+说明：
+
+- `skillsDir` 可省略。
+- 若省略，则默认使用 `<workspace_root>/.sgclaw-zeroclaw-workspace/skills`。
+- 若为相对路径，则相对于 `sgclaw_config.json` 所在目录解析。
+- 若指向某个 skill repo 根目录，且其下存在 `skills/` 子目录，运行时会自动落到该 `skills/` 目录。
+- 因此 SuperRPA 侧只需要负责传递 `--config-path`，skill 查找策略由 `sgclaw` 自己控制。
+- 长期看，这个文件应表达 zeroclaw-first 的 runtime/profile/tool policy 配置，而不仅是 provider shim。

 ---

@@ -165,7 +194,7 @@ DEEPSEEK_MODEL=...
 cargo test
 ```

-这组测试表达了一个重要工程事实：当前系统的稳定核心是协议、runtime 选择和 compat 适配，而不是旧版前端验证页。
+这组测试表达了一个重要工程事实：当前系统的稳定核心是协议、安全边界、runtime 选择和 zeroclaw 接入，而不是旧版前端验证页。

 ---

@@ -220,4 +249,4 @@ sgclaw binary
 L4 层面的核心结论只有两点：

 1. 本仓库已经从“带演示页的杂糅目录”收敛为“Rust Runtime + 协议文档 + 测试”的内核仓库。
-2. ZeroClaw 重构后的工程重点，是保证 compat runtime、fallback runtime、浏览器协议三者在同一 contract 上工作。
+2. ZeroClaw 重构后的工程重点，是把工程形态从“browser-first compat”收口为“zeroclaw-first runtime + sgClaw security envelope”，同时保持浏览器协议稳定。
--- a/docs/L5-提示词分布与安全改造方案.md
+++ b/docs/L5-提示词分布与安全改造方案.md
@@ -5,24 +5,25 @@
 - 目标：给出可执行的工程改造路径与落地记录

 ## 1. 结论（先说结论）
-项目存在至少两条主要提示词构造链路：
+项目当前存在至少两条主要提示词构造链路，但长期主线只能保留一条 authoritative chain：

-1) **轻量运行时链路**（`src/agent/runtime.rs`）
+1) **轻量运行时链路**（`src/agent/runtime.rs`，过渡态）
 - 仅有非常基础的固定 system 提示。
 - 适用于非完整流程的本地/最小执行场景。
+- 不应继续被扩展成主线产品提示词体系。

 2) **ZeroClaw 主链路**（`third_party/zeroclaw/*`）
 - 这条链路是“系统提示”主体，分为：
  - `Agent` 内部结构化构建器（`SystemPromptBuilder`）
  - `channels` 侧统一字符串拼装
  - `skills / personality / identity / bootstrap 文件 / 工具说明` 等多个注入源
- 这也是你要关注的主要安全面。
+- 这也是你要关注的主要安全面，也是未来应保留的唯一主线。

 ---

 ## 2. 提示词分布结构（按文件/模块）

-### 2.1 固定系统提示（轻量链路）
+### 2.1 固定系统提示（轻量链路，待收口）
 - `src/agent/runtime.rs`
  - `execute_task_with_provider` 的 `ChatMessage { role: "system" ... }`
  - 当前内容：`You are sgClaw. Use browser_action to complete the browser task.`
@@ -108,6 +109,10 @@
 ## 4. 安全改造建议（按优先级）

 ### P0（建议立即做）
+0) 收口双主链路
+- `sgclaw` 不应长期同时维护一条轻量自定义 prompt 链和一条 zeroclaw 主链。
+- 目标是：保留 zeroclaw 主链，sgClaw 仅增加安全摘要、浏览器上下文和受控工具面说明。
+
 1) 接入 `PromptGuard`
 - 目前已有 `third_party/zeroclaw/src/security/prompt_guard.rs`
 - 在以下入口加扫描并截断/告警：
@@ -148,7 +153,8 @@
 ## 5. 本次已确认的“关键风险”
 - `PromptGuard` 尚未在主入口统一挂载（存在检测能力，但未形成强制拦截链）。
 - workspace/skills 内容可直接进入 prompt，注入面较宽。
- 两套系统提示构建链路（agent builder 与 channel builder）存在口径差异，需要统一。
+- 两套系统提示构建链路（轻量链路与 zeroclaw 主链）同时存在，容易造成安全策略漂移。
+- `sgclaw` 如果继续把浏览器专用提示补丁放在主链外侧，会重新制造第三条 prompt source。

 ---

@@ -161,4 +167,3 @@
   - 复现提示词覆盖攻击
   - 系统提示重复/续接场景（seed/reseed）
   - compact/full 两种技能注入对比
-
--- a/docs/README.md
+++ b/docs/README.md
@@ -10,6 +10,16 @@
 - `L5-提示词分布与安全改造方案.md`：提示词治理与风控增强策略。
 - `浏览器对接标准.md`：Rust 与 Chromium 对接的协议基线。

+当前运行时补充约定：
+
+- `sgclaw` 在主线口径上应理解为“安全加固后的 zeroclaw runtime”，而不是浏览器侧 UI 产品，也不是 browser-only agent。
+- 浏览器宿主与 pipe 协议提供的是受保护执行面；浏览器是重要工具与前端载体，但不是整个 runtime 的定义。
+- 文档中提到 `planner fallback`、`compat runtime`、`browser_action only` 时，应优先理解为“当前实现状态/过渡态”，而不是长期产品边界。
+- `sgclaw` 的浏览器侧配置文件为 `sgclaw_config.json`。
+- `sgclaw` 负责解析模型配置与可选的 `skillsDir`。
+- `skillsDir` 未设置时，默认回退到 `<workspace_root>/.sgclaw-zeroclaw-workspace/skills`。
+- `skillsDir` 已设置时，支持直接指向 skills 目录，也支持指向包含 `skills/` 子目录的 skill repo 根目录。
+
 ## 归档文档

 ### 项目管理与排期（已归档）
--- 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.
--- a/docs/浏览器对接标准.md
+++ b/docs/浏览器对接标准.md
@@ -3,12 +3,16 @@
 > 适用范围：P1a（Rust）与 P2（Chromium C++）联调开发。
 > 目标：双方只要严格按本文档实现，即可稳定联调。

+附加口径：
+- 浏览器宿主是 sgClaw/zeroclaw runtime 的一个特权执行面，不是整个 runtime 的定义。
+- 只有真正需要浏览器执行的动作才应该跨过这条 pipe；不要把所有任务都假定为浏览器任务。
+
 ## 1. 协议边界与责任

 - 单一事实来源：`docs/L2-核心模块与接口契约层.md` 第 5 章（5.1~5.4）。
 - 协议版本冻结：`1.0`；字段、action、错误码变更均视为协议变更。
- P1a 负责：`seq` 生成、command 组包、HMAC 计算、response 关联。
- P2 负责：message 解析、Schema 校验、MAC 检查、CommandRouter 执行、结构化回包。
+- P1a 负责：zeroclaw-first runtime、任务解释、tool policy、`seq` 生成、command 组包、HMAC 计算、response 关联。
+- P2 负责：process host、message 解析、Schema 校验、MAC 检查、CommandRouter 执行、结构化回包。

 ## 2. Wire Contract（双方 MUST）

@@ -36,6 +40,10 @@
 - 失败 response 必填：`error.code`、`error.message`（禁止纯文本错误）。
 - `action` 与 `params` 必须通过 L2 的枚举和 Schema 校验。

+说明：
+- 这份标准约束的是“浏览器特权工具面”的 wire contract。
+- 它不定义 sgClaw/zeroclaw 整体任务语义，也不意味着所有任务都必须变成 browser command。
+
 **标准 command 示例**：

 ```json