diff --git a/docs/L0-产品白皮书与能力全景层.md b/docs/L0-产品白皮书与能力全景层.md index ce9bd9c..fb21e54 100644 --- 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 与外部受控执行面连接起来。 --- diff --git a/docs/L1-系统架构与安全模型层.md b/docs/L1-系统架构与安全模型层.md index df94d5d..e11c0a1 100644 --- 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 主线保留了清晰边界。 diff --git a/docs/L2-核心模块与接口契约层.md b/docs/L2-核心模块与接口契约层.md index 4d4f3b7..9e1ceee 100644 --- 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` 工具契约 diff --git a/docs/L3-数据流与Skill体系层.md b/docs/L3-数据流与Skill体系层.md index fc14f11..4b755ac 100644 --- 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。 +- 特权工具面可替换，但协议和安全边界不变。 diff --git a/docs/L4-工程实现与部署拓扑层.md b/docs/L4-工程实现与部署拓扑层.md index 8492097..c0c0872 100644 --- 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=/sgclaw_config.json` 拉起 `sgclaw` 时，`sgclaw` 会自己读取该 JSON 文件，而不是要求宿主额外复制 skills。 + +当前支持的关键字段： + +```json +{ + "apiKey": "sk-...", + "baseUrl": "https://api.deepseek.com", + "model": "deepseek-chat", + "skillsDir": "skill_lib" +} +``` + +说明： + +- `skillsDir` 可省略。 +- 若省略，则默认使用 `/.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”，同时保持浏览器协议稳定。 diff --git a/docs/L5-提示词分布与安全改造方案.md b/docs/L5-提示词分布与安全改造方案.md index 24a7fc2..1695220 100644 --- 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 两种技能注入对比 - diff --git a/docs/README.md b/docs/README.md index 1d2f093..04ab941 100644 --- 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` 未设置时，默认回退到 `/.sgclaw-zeroclaw-workspace/skills`。 +- `skillsDir` 已设置时，支持直接指向 skills 目录，也支持指向包含 `skills/` 子目录的 skill repo 根目录。 + ## 归档文档 ### 项目管理与排期（已归档） diff --git a/docs/plans/2026-03-28-sgclaw-zeroclaw-core-realignment-plan.md b/docs/plans/2026-03-28-sgclaw-zeroclaw-core-realignment-plan.md new file mode 100644 index 0000000..1a2ac4e --- /dev/null +++ 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, +} +``` + +**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, + 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. diff --git a/docs/浏览器对接标准.md b/docs/浏览器对接标准.md index 94e155e..6239d7a 100644 --- 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