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

# L5-提示词分布与安全改造方案

- 记录时间：2026-03-26
- 场景：回答“项目里有没有提示词？如何改造更安全？提示词放在哪，什么时候调用？”
- 目标：给出可执行的工程改造路径与落地记录

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

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（建议立即做）
0) 收口双主链路
- `sgclaw` 不应长期同时维护一条轻量自定义 prompt 链和一条 zeroclaw 主链。
- 目标是：保留 zeroclaw 主链，sgClaw 仅增加安全摘要、浏览器上下文和受控工具面说明。

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，注入面较宽。
- 两套系统提示构建链路（轻量链路与 zeroclaw 主链）同时存在，容易造成安全策略漂移。
- `sgclaw` 如果继续把浏览器专用提示补丁放在主链外侧，会重新制造第三条 prompt source。

---

## 6. 建议的落地顺序（两周内可完成）
1. 统一入口加 `PromptGuard.scan` + deny/block 映射（最小改动）。
2. 在 `channels` + `personality` 的文件注入点加净化和长度守卫。
3. 安全摘要 section 作为每条提示词的必含块。
4. compact 模式默认开启并补充 `read_skill` 受控流程。
5. 增加一组回归用例：
   - 复现提示词覆盖攻击
   - 系统提示重复/续接场景（seed/reseed）
   - compact/full 两种技能注入对比