docs: define superrpa sgclaw runtime boundary

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