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

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 两种技能注入对比