docs: add prompt distribution and security hardening notes

docs/L5-提示词分布与安全改造方案.md

@@ -0,0 +1,164 @@
+# L5-提示词分布与安全改造方案
+
+- 记录时间：2026-03-26
+- 场景：回答“项目里有没有提示词？如何改造更安全？提示词放在哪，什么时候调用？”
+- 目标：给出可执行的工程改造路径与落地记录
+
+## 1. 结论（先说结论）
+项目存在至少两条主要提示词构造链路：
+
+1) **轻量运行时链路**（`src/agent/runtime.rs`）
+- 仅有非常基础的固定 system 提示。
+- 适用于非完整流程的本地/最小执行场景。
+
+2) **ZeroClaw 主链路**（`third_party/zeroclaw/*`）
+- 这条链路是“系统提示”主体，分为：
+  - `Agent` 内部结构化构建器（`SystemPromptBuilder`）
+  - `channels` 侧统一字符串拼装
+  - `skills / personality / identity / bootstrap 文件 / 工具说明` 等多个注入源
+- 这也是你要关注的主要安全面。
+
+---
+
+## 2. 提示词分布结构（按文件/模块）
+
+### 2.1 固定系统提示（轻量链路）
+- `src/agent/runtime.rs`
+  - `execute_task_with_provider` 的 `ChatMessage { role: "system" ... }`
+  - 当前内容：`You are sgClaw. Use browser_action to complete the browser task.`
+
+### 2.2 ZeroClaw `Agent` 内构建的提示词
+- `third_party/zeroclaw/src/agent/prompt.rs`
+  - `SystemPromptBuilder`（默认 sections）
+  - Sections：`ToolHonesty / Tools / Safety / Skills / Workspace / Runtime / ChannelMedia / DateTime`
+  - `identity_config`、`skills_prompt_mode`、`security_summary`、`autonomy_level` 会影响注入内容。
+- `third_party/zeroclaw/src/agent/agent.rs`
+  - `Agent::from_config` 组装 `prompt_builder(SystemPromptBuilder::with_defaults())` 与 `security.prompt_summary()`。
+  - `Agent::build_system_prompt` 每次首次 turn 缓存/重构系统提示。
+  - `seed_history` 处理恢复会话时避免系统提示重复。
+
+### 2.3 通道侧（channel）系统提示拼装器
+- `third_party/zeroclaw/src/channels/mod.rs`
+  - `build_system_prompt` / `build_system_prompt_with_mode_and_autonomy`
+  - 负责 workspace bootstrap 文件注入、技能注入、工具列表、硬件说明、channel 能力、时区与runtime信息。
+  - 会触发 `load_openclaw_bootstrap_files()`（`AGENTS.md/SOUL.md/IDENTITY.md/USER.md/TOOLS.md/MEMORY.md` 等）
+  - compact 模式下会传递 `bootstrap_max_chars`（默认压缩上下文）。
+
+### 2.4 技能提示词注入
+- `third_party/zeroclaw/src/skills/mod.rs`
+  - `skills_to_prompt_with_mode`：
+    - `Full`：inline 注入完整 `instructions`
+    - `Compact`：只注入摘要+工具清单，完整内容通过工具读取。
+- `third_party/zeroclaw/src/tools/read_skill.rs`
+  - `read_skill(name)` 负责 compact 模式下按需读取技能全文。
+
+### 2.5 人格/身份上下文注入
+- `third_party/zeroclaw/src/agent/personality.rs`
+  - 读取 `SOUL.md/IDENTITY.md/USER.md/AGENTS.md/TOOLS.md/HEARTBEAT.md/BOOTSTRAP.md/MEMORY.md`
+  - `load_personality` + `render` 组成身份上下文片段。
+- `third_party/zeroclaw/src/channels/mod.rs`
+  - `load_openclaw_bootstrap_files()` 读取 `AGENTS.md` 等工作区文件。
+
+### 2.6 子代理提示词（可单独注入）
+- `third_party/zeroclaw/src/tools/delegate.rs`
+  - `build_enriched_system_prompt` 组合 `ToolsSection / SafetySection / SkillsSection / WorkspaceSection / DateTimeSection`
+  - 叠加 `agent_config.system_prompt`（可选）
+
+### 2.7 安全模块相关（目前与 prompt 解耦）
+- `third_party/zeroclaw/src/security/policy.rs`
+  - 安全策略、命令校验、`prompt_summary()`。
+- `third_party/zeroclaw/src/security/prompt_guard.rs`
+  - 已有 prompt 注入检测能力，但当前代码链上未见到统一接入点（需要补齐）。
+
+---
+
+## 3. 提示词何时调用（触发场景）
+
+### 3.1 WS 网关（持久会话）
+- `third_party/zeroclaw/src/gateway/ws.rs`
+  - 连接建立后 `Agent::from_config`。
+  - 若后端有历史消息：`agent.seed_history(&messages)`。
+  - 每条用户消息执行 `agent.turn_streamed`。
+  - `turn_streamed`：若历史空则调用 `build_system_prompt()`。
+
+### 3.2 gateway 简版 webhook
+- `third_party/zeroclaw/src/gateway/mod.rs`（`run_gateway_chat_simple`）
+  - 通过 `channels::build_system_prompt(...)` 构造简版系统提示。
+
+### 3.3 gateway 全功能通道
+- `third_party/zeroclaw/src/gateway/mod.rs`（`run_gateway_chat_with_tools`）
+  - 走 `agent::process_message`。
+  - `process_message` 中每次请求构建一次通道 system prompt。
+
+### 3.4 CLI 主入口（daemon / interactive）
+- `third_party/zeroclaw/src/agent/loop_.rs`
+  - CLI run 或交互会初始化工具/skills/系统提示后，`agent_turn` 执行。
+  - 命令行消息与 tool_loop 共用通道侧 build path。
+
+### 3.5 每轮 Agent 恢复与续接
+- `Agent::seed_history()`（持久化会话恢复）
+  - 首次首轮会确保系统提示存在；历史中的旧系统提示会被过滤并重建。
+
+### 3.6 交互历史恢复
+- `agent/loop_.rs:load_interactive_session_history`
+  - 历史文件缺失或首条非系统时，补系统提示。
+
+---
+
+## 4. 安全改造建议（按优先级）
+
+### P0（建议立即做）
+1) 接入 `PromptGuard`
+- 目前已有 `third_party/zeroclaw/src/security/prompt_guard.rs`
+- 在以下入口加扫描并截断/告警：
+  - `Agent::turn` / `turn_streamed`
+  - `agent::process_message`
+  - `gateway simple chat` 和 ws/process path 的入口
+- 对注入风险高命令（ignore previous/system override/role confusion）直接 block 或标记高风险。
+
+2) 统一把工作区文件内容做“可注入净化”
+- 在注入前清洗 `AGENTS.md`/`SOUL.md` 等：
+  - 去控制字符、长度限制、拒绝危险模板片段（如“you are now…”、“ignore previous instructions”）
+  - 记录清洗与截断明细（便于审计）。
+
+### P1（1-2次迭代内）
+3) 将安全摘要作为结构化 section 强约束
+- 在 `SafetySection`/`build_system_prompt_with_mode...` 中统一注入 `security.prompt_summary()`。
+- 保证“允许命令/禁用命令/路径/审批要求/速率限制”同步显示，降低模型 trial-and-error。
+
+4) 对 compact/full 模式加分流控制
+- 将 `skills prompt mode` 默认由 full 改为 compact。
+- full 模式仅在受信任场景启用；compact 场景默认使用 `read_skill`。
+
+5) 工具调用策略在提示词中与执行层双向一致
+- 当前提示词有“Do not ask, execute directly”等语义，与执行层策略一致，但对 high-risk 仍需更硬约束。
+- 与 `tools::shell` 参数、`security.validate_command_execution`、`tool approval` 形成统一 policy 文档化。
+
+### P2（优化）
+6) 统一系统提示模板
+- `channels::build_system_prompt_*` 与 `SystemPromptBuilder` 逻辑有重叠。
+- 建议抽取公共 section（日期、安全、技能、工具）并做一次性组装，减少版本漂移导致的绕过面。
+
+7) 增加会话级审计
+- 当检测到提示词注入高分时：记录原始用户输入哈希、触发规则、决策（block/warn/sanitize）。
+- 与工具执行失败（rate limit / blocked path）打通到同一告警链。
+
+---
+
+## 5. 本次已确认的“关键风险”
+- `PromptGuard` 尚未在主入口统一挂载（存在检测能力，但未形成强制拦截链）。
+- workspace/skills 内容可直接进入 prompt，注入面较宽。
+- 两套系统提示构建链路（agent builder 与 channel builder）存在口径差异，需要统一。
+
+---
+
+## 6. 建议的落地顺序（两周内可完成）
+1. 统一入口加 `PromptGuard.scan` + deny/block 映射（最小改动）。
+2. 在 `channels` + `personality` 的文件注入点加净化和长度守卫。
+3. 安全摘要 section 作为每条提示词的必含块。
+4. compact 模式默认开启并补充 `read_skill` 受控流程。
+5. 增加一组回归用例：
+   - 复现提示词覆盖攻击
+   - 系统提示重复/续接场景（seed/reseed）
+   - compact/full 两种技能注入对比
+

docs/README.md

@@ -6,6 +6,7 @@
 - `浏览器对接标准.md`：Chromium ↔ sgClaw 联调接口标准（P1a/P2 必读）。
 - `L0-产品白皮书与能力全景层.md` ~ `L4-工程实现与部署拓扑层.md`：架构分层文档。
 - `团队分工.md`、`协作时间表.md`、`协作甘特图.md`：协作计划源文档。
+- `L5-提示词分布与安全改造方案.md`：提示词注入来源与调用时机、安全加固优先级建议。
 
 ## 归档文档（领导演示素材）