From 3844f2c34cb4ef07d30356abb925494fef75d3e0 Mon Sep 17 00:00:00 2001
From: zyl <zyl@local>
Date: Sun, 29 Mar 2026 21:24:33 +0800
Subject: [PATCH] docs: define superrpa sgclaw runtime boundary

---
 docs/L1-系统架构与安全模型层.md               |  76 ++++++++--
 docs/L2-核心模块与接口契约层.md               |  82 ++++++++++-
 docs/L4-工程实现与部署拓扑层.md               |  62 +++++++-
 ...9-sgclaw-superrpa-runtime-config-design.md | 137 ++++++++++++++++++
 4 files changed, 330 insertions(+), 27 deletions(-)
 create mode 100644 docs/plans/2026-03-29-sgclaw-superrpa-runtime-config-design.md

diff --git a/docs/L1-系统架构与安全模型层.md b/docs/L1-系统架构与安全模型层.md
index e11c0a1..c7dbe3b 100644
--- a/docs/L1-系统架构与安全模型层.md
+++ b/docs/L1-系统架构与安全模型层.md
@@ -1,22 +1,24 @@
 # L1 — 系统架构与安全模型层
 
-**文档版本**: 2.0  
-**适用项目**: sgClaw（ZeroClaw 重构版）  
-**编制日期**: 2026-03-26
+**文档版本**: 2.1<br>
+**适用项目**: sgClaw（ZeroClaw 重构版）<br>
+**编制日期**: 2026-03-29
 
 ---
 
 ## 1. 架构总览
 
-重构后的 sgClaw 架构要点应当这样理解：zeroclaw 是能力本体，sgClaw 是安全封装层，浏览器宿主是一个受保护的特权执行面。当前代码尚未完全落到这个目标结构，但主线架构口径必须先统一。
+重构后的 sgClaw 架构要点应当这样理解：`host`（SuperRPA）是受保护的宿主安全边界，`sgClaw` 是运行时能力编排层，`zeroclaw` 是 planner / model / skill 的能力本体，`frontend bundle` 只是展示面。当前代码尚未完全落到这个目标结构，但主线架构口径必须先统一。
 
 ```
 ┌──────────────────────────────┐
 │ Browser Host / Chromium Side │
+│ - 读取 launch config          │
 │ - 启动 sgClaw 子进程          │
 │ - 发送 init / submit_task     │
 │ - 复检 HMAC / domain / params │
 │ - 执行 browser command 并回包 │
+│ - 选择 frontend bundle        │
 └──────────────┬───────────────┘
                │ STDIO + JSON Line
 ┌──────────────▼───────────────┐
@@ -43,21 +45,23 @@
 └──────────────────────────────┘
 ```
 
-架构上最重要的变化是：sgClaw 不应被定义为“浏览器专用 agent”，而应被定义为“保留现有浏览器协议前提下，对 zeroclaw 做安全化封装的运行时分发”。
+架构上最重要的变化是：sgClaw 不应被定义为“浏览器专用 agent”，而应被定义为“保留现有浏览器协议前提下，对 zeroclaw 做安全化封装的运行时分发”。同时 `host` 不再持有高频变化的业务策略，`launch config`、`runtime config` 和 `frontend bundle` 应成为运行时可替换对象。
 
 ---
 
 ## 2. 运行时分层
 
-### 2.1 浏览器宿主层
+### 2.1 host（浏览器宿主）层
 
-宿主负责三类职责：
+`host` 负责受保护边界内的四类职责：
 
+- 读取并校验 `launch config`，决定进程如何被拉起。
 - 启动和托管 sgClaw Rust 子进程。
 - 按协议发送 `init`、`submit_task`、`response`。
 - 执行 Rust 发来的浏览器命令并回包。
+- 选择外部 `frontend bundle` 或内置资源作为展示面。
 
-sgClaw 仓库本身不包含 Chromium/C++ 实现代码，因此 L1 只定义宿主责任边界，不再把外部仓库中的假定文件结构写成“当前仓库现状”。
+`host` 不拥有 planner、模型路由、skills 编排或业务策略定义。sgClaw 仓库本身不包含 Chromium/C++ 实现代码，因此 L1 只定义宿主责任边界，不再把外部仓库中的假定文件结构写成“当前仓库现状”。
 
 ### 2.2 sgClaw 安全/控制层
 
@@ -67,18 +71,38 @@ Rust 侧是当前仓库的事实主体，职责包括：
 - 完成握手、加载 `rules.json`、创建 `BrowserPipeTool`。
 - 在消息循环中接收浏览器消息并分发到执行层。
 - 把执行日志和任务结果回传给宿主。
+- 读取 `runtime config`，决定 planner、provider、skills prompt mode、backend 选择等运行时行为。
 - 决定哪些 zeroclaw 能力能够暴露给当前运行环境。
 
 ### 2.3 zeroclaw 核心层
 
 主线目标中，zeroclaw 应承担：
 
+- planner / executor 决策
 - prompt/system sections 组装
 - skills / memory / routing
 - tool loop 与 provider 协调
 - 通用 agent 能力而非仅浏览器能力
 
-### 2.4 当前实现的过渡态
+也就是说，`planner-first` 是 sgClaw / zeroclaw 运行时行为，不是 `frontend bundle` 或 `host` 页面逻辑。
+
+### 2.4 展示层（frontend bundle）
+
+前端展示层只拥有显示权，不拥有执行权。其职责应被限制为：
+
+- 展示会话状态、日志、消息、验收结果。
+- 将用户输入转成宿主可接受的事件。
+- 呈现 `planner-first` 的可视化状态，例如“先展示计划，再执行”。
+
+前端不应决定：
+
+- 是否调用 planner
+- 是否切换 provider / model
+- 是否绕过 sgClaw / zeroclaw 执行
+
+这些决策必须留在 sgClaw / zeroclaw 运行时。
+
+### 2.5 当前实现的过渡态
 
 当前执行层仍有两条路径：
 
@@ -90,6 +114,19 @@ Rust 侧是当前仓库的事实主体，职责包括：
 
 这两条路径是当前代码现实，但都不应被写成长期产品定义。长期目标是“zeroclaw-first runtime + sgClaw security layer”，而不是 browser-only compat。
 
+### 2.6 运行时配置边界
+
+本轮架构冻结后，必须使用以下统一术语：
+
+- `launch config`
+  由 `host` 读取，描述 `binary`、`args`、`env`、`working_dir`、`runtime_config_path`、`frontend_bundle_dir` 等启动时边界。
+- `runtime config`
+  由 sgClaw 读取，描述 provider、model、planner mode、backend 选择、skills 策略等运行时行为。
+- `frontend bundle`
+  由 `host` 装载的展示资源目录，允许外部 bundle 优先、内置资源兜底。
+
+这三类对象都应支持运行期调整；只有安全边界和能力暴露由 `host` 固化。
+
 ---
 
 ## 3. ZeroClaw 重构的架构意义
@@ -174,10 +211,27 @@ ZeroClaw 在本项目中的角色不是“大而全框架接管一切”，也
 - 动作越多，宿主和 runtime 之间的契约越难稳定。
 - 在规则文件仍只开放 4 个动作的前提下，文档不应提前放大能力范围。
 
+### 5.4 启动策略配置化，而不是编译期写死
+
+原因：
+
+- 更换 sgClaw binary 不应要求重编 Chromium。
+- 切换 `runtime config` 不应要求重编 Chromium。
+- 更换 `frontend bundle` 不应要求重编 Chromium。
+- 安全边界仍由 `host` 控制，配置化不等于放弃校验。
+
+### 5.5 planner-first 只属于运行时，不属于展示层
+
+原因：
+
+- “先展示计划，再执行”是执行引擎行为，不是前端动画效果。
+- 前端只能显示 planner 状态，不能私自触发或跳过 planner。
+- 验收必须同时覆盖视觉呈现和功能执行两个维度。
+
 ---
 
 ## 6. 架构结论
 
-L1 层面可以把 sgClaw 定义为：一个通过固定浏览器协议接入宿主、以 Rust 为安全与控制层、以 zeroclaw 为能力核心、以 MAC Policy 与宿主复检为受保护执行边界的安全加固运行时分发。
+L1 层面可以把 sgClaw 定义为：一个通过固定浏览器协议接入 `host`、以 Rust 为安全与控制层、以 zeroclaw 为能力核心、以 `runtime config` 驱动执行行为、以 `frontend bundle` 作为仅展示界面、以 MAC Policy 与宿主复检为受保护执行边界的安全加固运行时分发。
 
-这一定义既承认当前仓库仍存在 browser-first compat 的过渡实现，也为后续把 runtime 真正收口到 zeroclaw-first 主线保留了清晰边界。
+这一定义既承认当前仓库仍存在 browser-first compat 的过渡实现，也为后续把 runtime 真正收口到 zeroclaw-first、planner-first 主线保留了清晰边界。
diff --git a/docs/L2-核心模块与接口契约层.md b/docs/L2-核心模块与接口契约层.md
index 9e1ceee..1d5ae6a 100644
--- a/docs/L2-核心模块与接口契约层.md
+++ b/docs/L2-核心模块与接口契约层.md
@@ -1,8 +1,8 @@
 # L2 — 核心模块与接口契约层
 
-**文档版本**: 2.0  
-**适用项目**: sgClaw（ZeroClaw 重构版）  
-**编制日期**: 2026-03-26
+**文档版本**: 2.1<br>
+**适用项目**: sgClaw（ZeroClaw 重构版）<br>
+**编制日期**: 2026-03-29
 
 **读者**: 架构工程师、实现工程师、联调工程师
 
@@ -34,6 +34,19 @@ src/
 | 适配层 | `compat`、`config` | 把 sgClaw 宿主环境映射到 zeroclaw 运行时；当前仍带有过渡性限制 |
 | 核心能力层 | `third_party/zeroclaw` | prompt、skills、memory、tool loop、provider 抽象 |
 
+本轮冻结后还需要一组跨仓统一术语：
+
+- `host`
+  指 SuperRPA 浏览器宿主，只拥有安全边界、进程托管和展示装配权。
+- `launch config`
+  指由 `host` 读取的启动描述文件。
+- `runtime config`
+  指由 sgClaw 读取的运行时策略文件。
+- `frontend bundle`
+  指由 `host` 装载的前端展示资源。
+- `planner-first`
+  指 sgClaw / zeroclaw 先产生计划、前端先展示计划、随后再执行的运行时行为。
+
 ---
 
 ## 2. 核心模块职责
@@ -54,20 +67,21 @@ src/
 
 [`src/agent/mod.rs`](/home/zyl/projects/sgClaw/claw/src/agent/mod.rs) 当前决定执行路径：
 
-- 收到 `BrowserMessage::SubmitTask` 时优先尝试读取 `DeepSeekSettings`。
-- 环境配置存在，则走 `compat::runtime::execute_task`。
-- 环境配置不存在，则走内置 planner fallback。
+- 收到 `BrowserMessage::SubmitTask` 时优先尝试读取 `SgClawSettings`。
+- 环境配置存在，则走 `compat::runtime::execute_task_with_sgclaw_settings`。
+- 环境配置不存在，则直接返回“未配置大语言模型”，而不是再把生产 submit 流量导回旧 planner。
 
-这就是当前系统的“路由器”。但文档上应把它理解为过渡性 runtime selector，而不是最终产品架构中心。
+这就是当前系统的“路由器”。但文档上应把它理解为过渡性 runtime selector，而不是最终产品架构中心。长期看，`planner-first`、provider 选择与 backend 选择都应由 `runtime config` 显式驱动。
 
 ### 2.3 `src/agent/runtime.rs`
 
-该文件保留了仓库内的轻量 LLM/tool 调用逻辑，核心特点：
+该文件现在应被视为 `legacy/dev-only` 模块，只保留仓库内的轻量 LLM/tool 调用逻辑用于局部验证，核心特点：
 
 - 工具名固定为 `browser_action`。
 - schema 只允许 `click/type/navigate/getText`。
 - 每次工具调用前后发送 `log_entry`。
 - 结果失败时直接返回 `PipeError::Protocol`。
+- 不参与当前生产浏览器 submit 路由。
 
 ### 2.4 `src/compat/runtime.rs`
 
@@ -85,6 +99,58 @@ src/
 - 这意味着当前代码还没有把 sgClaw 做成 zeroclaw-first runtime。
 - 这是一种实现限制，不应被文档提升为产品原则。
 
+### 2.7 host / launch config / runtime config 契约
+
+跨仓接口收口后，`host` 与 sgClaw 的最小契约应为：
+
+| 对象 | 读取方 | 责任 | 失败时兜底 |
+|---|---|---|---|
+| `launch config` | `host` | 解析 `binary`、`args`、`env`、`working_dir`、`runtime_config_path`、`frontend_bundle_dir` | 回退到浏览器内置默认启动策略 |
+| `runtime config` | sgClaw | 解析 provider、model、planner mode、backend、skills policy | 回退到 sgClaw 默认运行时配置 |
+| `frontend bundle` | `host` | 提供浮窗/面板展示资源 | 回退到浏览器内置 WebUI 资源 |
+
+这里的关键点是：`host` 只负责校验和装配，不负责决定 planner、model routing 或 business behavior。
+
+### 2.8 launch config 文件路径与回退规则
+
+设计冻结口径如下：
+
+- profile-local `launch config` 路径：`<profile>/superrpa/sgclaw_launch_config.json`
+- profile-local `runtime config` 路径：`<profile>/superrpa/sgclaw_config.json`
+- profile-local hooks / rules 仍沿用：
+  - `<profile>/superrpa/hooks.json`
+  - `<profile>/superrpa/rules.json`
+
+`launch config` 的回退规则必须保持稳定：
+
+1. 优先读取 `<profile>/superrpa/sgclaw_launch_config.json`
+2. 缺失或解析失败时，回退到当前浏览器内置默认启动参数
+3. `runtime_config_path` 缺失时，回退到 `<profile>/superrpa/sgclaw_config.json`
+4. `frontend_bundle_dir` 缺失、无效或校验失败时，回退到 bundled frontend resources
+
+### 2.9 frontend bundle 与 planner-first 契约
+
+`frontend bundle` 只能消费这些由 `host` 转发的运行时状态：
+
+- 当前状态与日志
+- planner 输出
+- 会话消息
+- 最终执行结果
+
+`frontend bundle` 不能直接拥有：
+
+- provider 切换决策权
+- planner 开关控制权
+- executor 旁路能力
+
+因此 `planner-first` 的契约应是：
+
+1. sgClaw / zeroclaw 产生计划
+2. `frontend bundle` 先展示计划
+3. 经运行时确认后再执行
+
+这是一条 runtime contract，不是一条前端内部约定。
+
 ### 2.5 `src/pipe/browser_tool.rs`
 
 该模块承担真实浏览器命令发送职责，也是当前系统中最重要的特权工具面桥接层：
diff --git a/docs/L4-工程实现与部署拓扑层.md b/docs/L4-工程实现与部署拓扑层.md
index c0c0872..47c0dc5 100644
--- a/docs/L4-工程实现与部署拓扑层.md
+++ b/docs/L4-工程实现与部署拓扑层.md
@@ -1,8 +1,8 @@
 # L4 — 工程实现与部署拓扑层
 
-**文档版本**: 2.0  
-**适用项目**: sgClaw（ZeroClaw 重构版）  
-**编制日期**: 2026-03-26
+**文档版本**: 2.1<br>
+**适用项目**: sgClaw（ZeroClaw 重构版）<br>
+**编制日期**: 2026-03-29
 
 **读者**: 开发者、测试工程师、联调工程师
 
@@ -145,9 +145,9 @@ DEEPSEEK_MODEL=...
 
 若这些变量不存在或不完整，系统会退回 planner fallback。这个行为是当前实现状态，不是长期架构推荐。
 
-### 3.4 浏览器配置文件
+### 3.4 runtime config 文件
 
-当宿主以 `--config-path=<workspace_root>/sgclaw_config.json` 拉起 `sgclaw` 时，`sgclaw` 会自己读取该 JSON 文件，而不是要求宿主额外复制 skills。
+当 `host` 以 `--config-path=<workspace_root>/sgclaw_config.json` 拉起 `sgclaw` 时，`sgclaw` 会自己读取该 JSON 文件，而不是要求宿主额外复制 skills。
 
 当前支持的关键字段：
 
@@ -166,8 +166,47 @@ DEEPSEEK_MODEL=...
 - 若省略，则默认使用 `<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。
+- 因此 `host` 只需要负责传递 `runtime config` 路径，skill 查找策略由 `sgclaw` 自己控制。
+- 长期看，这个文件应表达 zeroclaw-first、`planner-first` 的 runtime/profile/tool policy 配置，而不仅是 provider shim。
+
+### 3.5 launch config 文件与 fallback
+
+`launch config` 由 `host` 读取，不由 sgClaw 自己解析。设计冻结后的推荐路径为：
+
+```text
+<profile>/superrpa/sgclaw_launch_config.json
+```
+
+该文件承载的字段应包括：
+
+- `binary`
+- `args`
+- `env`
+- `working_dir`
+- `runtime_config_path`
+- `frontend_bundle_dir`
+
+加载规则必须保持稳定：
+
+1. `host` 优先读取 profile-local `launch config`
+2. 若 `binary` 缺失或无效，则回退到浏览器已知可启动的默认 sgClaw 路径
+3. 若 `runtime_config_path` 缺失，则回退到 `<profile>/superrpa/sgclaw_config.json`
+4. 若 `frontend_bundle_dir` 缺失或无效，则回退到 bundled frontend resources
+
+这样做的目的不是削弱宿主管控，而是把高频变化项从编译期常量改成运行期可替换对象。
+
+### 3.6 frontend bundle 装载拓扑
+
+`frontend bundle` 的部署方式应当是“外部 bundle 优先，内置资源兜底”：
+
+```text
+host
+  ├─ validate frontend_bundle_dir
+  ├─ if valid: load external frontend bundle
+  └─ else: load bundled frontend resources
+```
+
+这意味着后续改浮窗 UI、验收页面或 planner 展示逻辑，不应再默认要求重编 Chromium。
 
 ---
 
@@ -208,9 +247,11 @@ cargo test
 
 ### 5.2 外部宿主负责什么
 
+- 读取并校验 `launch config`。
 - 拉起并托管 sgClaw 进程。
 - 提供页面执行能力。
 - 实现命令落地、响应回传和宿主侧校验。
+- 装载 `frontend bundle`，并在无效时回退到内置资源。
 
 ### 5.3 不在本仓库内交付的内容
 
@@ -228,13 +269,17 @@ L4 的工程边界必须按仓库现实写清楚，否则会把“外部依赖
 
 ```
 Browser Host Process
+  ├─ reads launch config
   ├─ launches sgclaw binary
   ├─ writes init / submit_task to stdin
   ├─ reads command / log / task_complete from stdout
-  └─ executes page actions in host environment
+  ├─ executes page actions in host environment
+  └─ loads external frontend bundle or bundled resources
 
 sgclaw binary
+  ├─ loads runtime config
   ├─ loads resources/rules.json
+  ├─ runs planner-first execution
   ├─ verifies action/domain
   ├─ optionally calls provider API
   └─ waits for browser response
@@ -250,3 +295,4 @@ L4 层面的核心结论只有两点：
 
 1. 本仓库已经从“带演示页的杂糅目录”收敛为“Rust Runtime + 协议文档 + 测试”的内核仓库。
 2. ZeroClaw 重构后的工程重点，是把工程形态从“browser-first compat”收口为“zeroclaw-first runtime + sgClaw security envelope”，同时保持浏览器协议稳定。
+3. `host`、`launch config`、`runtime config`、`frontend bundle`、`planner-first` 必须在文档、代码和验收中使用同一套术语，避免再次把前端逻辑上移到 sgClaw 之外。
diff --git a/docs/plans/2026-03-29-sgclaw-superrpa-runtime-config-design.md b/docs/plans/2026-03-29-sgclaw-superrpa-runtime-config-design.md
new file mode 100644
index 0000000..480ec93
--- /dev/null
+++ b/docs/plans/2026-03-29-sgclaw-superrpa-runtime-config-design.md
@@ -0,0 +1,137 @@
+# sgClaw SuperRPA Runtime Config Design
+
+**Status**: Draft frozen before implementation  
+**Date**: 2026-03-29
+
+## 1. Goal
+
+Freeze the runtime-boundary design before further implementation so Task 2+ do not drift back into browser-compiled behavior.
+
+The design line is fixed:
+
+- `host` keeps the security boundary.
+- sgClaw keeps runtime behavior.
+- `frontend bundle` keeps display rights only.
+- High-frequency changes move to runtime-managed files whenever possible.
+
+## 2. Ownership Split
+
+### 2.1 host
+
+SuperRPA as `host` owns only the trusted boundary:
+
+- process spawning
+- pipe lifecycle and session security
+- browser / office capability exposure
+- path validation for runtime-managed files
+- fallback to bundled defaults when external files are missing or unsafe
+
+`host` does not own planner policy, model routing, provider selection, skill orchestration, or business behavior.
+
+### 2.2 sgClaw runtime
+
+sgClaw owns runtime behavior:
+
+- planner / executor orchestration
+- provider list and active provider selection
+- skill loading and prompt mode
+- browser / office backend selection
+- runtime profile behavior
+- planner-first execution sequencing
+
+### 2.3 frontend bundle
+
+`frontend bundle` owns presentation only:
+
+- render runtime state, logs, and conversation
+- render planner output before execution
+- collect user input and forward it through host events
+
+`frontend bundle` must not:
+
+- decide whether planner runs
+- directly select provider/backend outside runtime contract
+- bypass sgClaw / zeroclaw execution
+
+## 3. Runtime-Managed Files
+
+### 3.1 launch config
+
+Owned by `host`, preferred path:
+
+```text
+<profile>/superrpa/sgclaw_launch_config.json
+```
+
+Fields:
+
+- `binary`
+- `args`
+- `env`
+- `working_dir`
+- `runtime_config_path`
+- `frontend_bundle_dir`
+
+Fallback rules:
+
+1. Prefer external `launch config`
+2. Fall back to bundled browser defaults when file is missing or invalid
+3. Fall back to profile-local `runtime config` if `runtime_config_path` is absent
+4. Fall back to bundled frontend resources if `frontend_bundle_dir` is absent or invalid
+
+### 3.2 runtime config
+
+Owned by sgClaw, current default path:
+
+```text
+<profile>/superrpa/sgclaw_config.json
+```
+
+This file should carry runtime behavior instead of browser compile-time constants, including:
+
+- planner mode
+- providers and active provider
+- browser backend
+- office backend
+- skills prompt mode
+- runtime profile
+
+### 3.3 frontend bundle
+
+Owned by `host` for loading, but externally replaceable at runtime:
+
+- prefer `frontend_bundle_dir`
+- validate path and allowed loading rules
+- fall back to bundled resources if invalid
+
+## 4. Planner-First Rule
+
+`planner-first` is a runtime contract, not a frontend trick.
+
+The sequence must be:
+
+1. sgClaw / zeroclaw produces a plan
+2. `frontend bundle` displays the plan
+3. runtime continues into execution
+4. acceptance verifies both visible plan rendering and actual execution ordering
+
+## 5. Failing Checklist
+
+The following questions remain intentionally unresolved at design-freeze time and must be closed by implementation plus verification:
+
+- [ ] Can browser startup switch sgClaw binary without rebuilding Chromium?
+- [ ] Can model/provider selection change without rebuilding Chromium?
+- [ ] Can floating UI be replaced without rebuilding Chromium?
+- [ ] Can acceptance flows prove planner-first behavior visually and functionally?
+
+## 6. Terminology Guardrail
+
+All related docs and code reviews must use the same terms:
+
+- `host`
+- `launch config`
+- `runtime config`
+- `frontend bundle`
+- `planner-first`
+
+Any proposal that moves planner or executor logic back into browser-side presentation code is out of bounds for this design.