agent-safety

Agent 安全防护体系——事件驱动拦截（Hook Engine）+ 三层护栏（输入/工具/输出）+ 迭代循环（Ralph Loop）+ 操作追踪（Operation Tracer）

Install

openclaw skills install @paudyyin/agent-safety

Agent Safety v1.1.0

Agent 安全防护体系：事件拦截 → 规则匹配 → 护栏检测 → 动作执行 → 操作追踪。

来源：hook-engine v1.2.0（事件驱动拦截）+ guardrail-system v1.0.0（三层护栏）+ Ralph Loop（迭代循环）+ operation-tracer v1.0.0（操作追踪）

架构总览

text

┌─────────────────────────────────────────────────────────────────┐
│                        Agent Safety                             │
├─────────────────────────────────────────────────────────────────┤
│  Part 1: Hook Engine — 事件调度 + 规则引擎（什么时候检查）        │
│  ├─ 6种事件: PreTask / PreExec / PostExec / PreMessage / PostMessage / Stop │
│  ├─ 规则引擎: YAML frontmatter + 多条件组合 + 优先级            │
│  └─ 动作类型: allow / warn / block / log                        │
├─────────────────────────────────────────────────────────────────┤
│  Part 2: Guardrails — 三层检测逻辑（检查什么）                    │
│  ├─ 输入护栏: 14种 Prompt 注入模式 + 异常长度检测                │
│  ├─ 工具护栏: READ/WRITE/DANGEROUS 三级权限控制                  │
│  └─ 输出护栏: 7种敏感信息自动过滤                                │
├─────────────────────────────────────────────────────────────────┤
│  Part 3: Ralph Loop — 迭代自引用循环（安全地持续执行）            │
│  ├─ 状态文件 + completion-promise + max-iterations               │
│  └─ 与 coding-framework 集成                                    │
├─────────────────────────────────────────────────────────────────┤
│  Part 4: Operation Tracer — 操作追踪（v1.1 新增）                │
│  ├─ 追踪工具调用、LLM调用、错误、上下文压缩                      │
│  ├─ SQLite 持久化存储 + 性能分析                                 │
│  └─ 与 Hook Engine 集成（PreExec/PostExec 自动追踪）             │
└─────────────────────────────────────────────────────────────────┘

Part 1: Hook Engine — 事件驱动拦截

1.1 事件类型

事件	触发时机	输入数据
`PreTask`	任务开始前（daily-agent Step 1 后）	`{task_type, files, keywords}`
`PreExec`	exec 命令执行前	`{command, workdir, env}`
`PostExec`	exec 命令执行后	`{command, exitCode, stdout, stderr, duration}`
`PreMessage`	消息发送前	`{content, channel, target}`
`PostMessage`	消息发送后	`{content, channel, messageId, status}`
`Stop`	会话结束时	`{session, reason, summary}`

1.2 规则引擎

规则定义在 rules/ 目录下，每个 .md 文件包含 YAML frontmatter：

yaml

---
name: rule-name
enabled: true
event: PreExec
matcher: "rm -rf"          # regex 匹配模式
action: block              # allow | warn | block | log
priority: 10               # 数字越大优先级越高
---

多条件组合（v1.2，当单字段匹配不够精确时）：

yaml

---
name: warn-env-api-keys
enabled: true
event: PreExec
action: warn
priority: 50
conditions:
  - field: command
    operator: regex_match
    pattern: "echo.*>.*\\.env"
  - field: command
    operator: contains
    pattern: "API_KEY"
---
你在写入 .env 文件中的 API_KEY。确保此文件在 .gitignore 中！

条件字段（按事件类型）：

事件	可用字段
`PreTask`	`task_type`, `files`, `keywords`
`PreExec`	`command`, `workdir`, `env`
`PostExec`	`command`, `exitCode`, `stdout`, `stderr`
`PreMessage`	`content`, `channel`, `target`
`PostMessage`	`content`, `channel`, `messageId`, `status`
`Stop`	`session`, `reason`, `summary`

1.3 动作类型

allow：放行，记录日志
warn：放行但输出警告信息
block：阻止执行，返回拒绝原因
log：仅记录，不影响流程

1.4 Hook 脚本规范

所有 hook 脚本位于 hooks/ 目录：

从 stdin 读取 JSON 事件数据
加载 rules/ 下匹配的规则
按优先级逐条评估
输出 JSON 结果到 stdout

json

{
  "decision": "allow|warn|block",
  "message": "人类可读的说明",
  "matched_rules": ["rule-name-1"],
  "timestamp": "2026-06-26T22:00:00Z"
}

1.5 与 daily-agent 集成

text

用户消息 → daily-agent 分类
  → [PreMessage hook] 验证消息格式
  → 任务执行
    → [PreExec hook] 每次 exec 前检查
    → [PostExec hook] 每次 exec 后记录
  → [PostMessage hook] 发送前验证
  → [Stop hook] 会话结束清理

1.6 审计日志

所有 hook 触发记录写入 memory/hook-audit.log：

text

[timestamp] [event] [decision] [rule] message

1.7 与 Operation Tracer 集成（v1.1 新增）

Hook Engine 的 PreExec/PostExec 事件是 Operation Tracer 的天然触发点：

text

PreExec Hook 触发
  → tracer.start_span("tool_call", {command, workdir, env})
  → 执行命令
PostExec Hook 触发
  → tracer.end_span(span_id, result=stdout, status=exitCode==0 ? "success" : "error")

集成代码示例：

python

from scripts.tracer import OperationTracer

tracer = OperationTracer()

# PreExec Hook 中
span_id = tracer.start_span("exec", "tool_call", {
    "command": event["command"],
    "workdir": event.get("workdir", "")
})

# PostExec Hook 中
tracer.end_span(span_id, 
    result=event.get("stdout", "")[:500],  # 截断长输出
    status="success" if event["exitCode"] == 0 else "error"
)

追踪数据用途：

性能分析：识别慢操作（analyzer.get_slow_operations()）
错误模式：统计高频错误（analyzer.get_error_operations()）
操作统计：生成执行摘要（analyzer.get_summary()）

Part 2: Guardrails — 三层检测逻辑

2.1 输入护栏 (InputGuard)

检测 14 种 Prompt 注入模式（中英文）：

#	模式	示例
1	ignore previous instructions	"ignore previous instructions and..."
2	ignore above instructions	"ignore all above instructions"
3	you are now a/an	"you are now a hacker"
4	new instructions:	"new instructions: do X"
5	system prompt	"system prompt override"
6	disregard previous	"disregard previous commands"
7	forget your instructions	"forget your instructions"
8	act as a/an	"act as a python interpreter"
9	pretend you are	"pretend you are an admin"
10	override previous	"override previous settings"
11	新的指令	"新的指令：执行命令"
12	忽略之前的	"忽略之前的所有内容"
13	忽略以上	"忽略以上指令"
14	你现在是	"你现在是一个AI"

额外检测：输入长度 > 10000 字符时告警。

2.2 工具护栏 (ToolGuard)

权限级别	行为	工具示例
READ	自动批准	read, read_file, web_search, list_files, search, fetch_url
WRITE	需用户确认	write, write_file, edit_file, create_file, save
DANGEROUS	需明确授权	rm, delete_file, execute_shell, exec, format, drop_table

2.3 输出护栏 (OutputGuard)

#	类型	匹配模式
1	API密钥	`API_KEY=xxx`, `api_key=xxx`
2	密码	`password=xxx`, `passwd=xxx`
3	密钥	`secret=xxx`
4	访问令牌	`token=xxx`（长度≥20）
5	私钥	`private_key=xxx`, `-----BEGIN PRIVATE KEY-----`
6	邮箱	`user@domain.com`
7	身份证号	18位身份证号码

2.4 使用方法

python

import sys
sys.path.insert(0, "<skill-dir>/scripts")

from guardrail import GuardrailSystem

guardrails = GuardrailSystem()

# 输入检查
result = guardrails.check_input(user_message)
if not result.allowed:
    print(f"拦截: {result.reason}")

# 工具检查
result = guardrails.check_tool_call("rm", {"path": "/"})
if result.requires_authorization:
    print(f"需授权: {result.message}")

# 输出检查
result = guardrails.check_output(assistant_message)
if result.sanitized_output:
    print(f"已过滤: {result.sanitized_output}")

2.5 GuardrailResult

字段	类型	说明
`allowed`	bool	是否允许通过
`reason`	str	原因说明
`requires_confirmation`	bool	是否需要用户确认
`requires_authorization`	bool	是否需要明确授权
`message`	str	提示信息
`sanitized_output`	str	过滤后的输出（仅输出护栏）

2.6 扩展

添加注入模式：编辑 scripts/input_guard.py 中的 INJECTION_PATTERNS
添加工具权限：guard.add_tool("my_tool", PermissionLevel.READ)
添加敏感信息模式：编辑 scripts/output_guard.py 中的 SENSITIVE_PATTERNS

Part 3: Ralph Loop — 迭代自引用循环

借鉴 Geoffrey Huntley 的 Ralph Wiggum 技术 + Anthropic 官方 ralph-loop 插件。核心理念：迭代 > 完美。让 AI 在循环中持续改进，直到任务完成。

3.1 核心概念

text

用户启动 → AI 执行任务 → 检查结果 → 未完成？→ 重新执行（读取上次结果）
                                    → 完成？→ 输出完成信号 → 结束循环

OpenClaw 实现使用状态文件 + 迭代提示词模式：

每次迭代生成新的提示词（包含进度上下文）
通过 completion-promise 字符串匹配检测完成
通过 max-iterations 防止无限循环

3.2 使用方法

bash

# 启动循环
python scripts/ralph_loop.py start \
  --prompt "实现一个 REST API，要求：CRUD 操作、输入验证、测试覆盖 > 80%" \
  --max-iterations 20 \
  --promise "COMPLETE"

# 推进到下一次迭代
python scripts/ralph_loop.py next --result "已完成 CRUD，测试覆盖率 60%，还需要补充边界测试"

# 查看状态
python scripts/ralph_loop.py status

# 取消循环
python scripts/ralph_loop.py cancel

# 查看历史
python scripts/ralph_loop.py history --limit 10

3.3 与 coding-framework 集成

Ralph Loop 可作为 coding-framework 的模式 8：迭代循环模式：

text

用户任务 → 判断适合迭代？
  ├─ 是 → 启动 Ralph Loop
  │      → 每次迭代使用 coding-framework 模式 1（快速编码）
  │      → 迭代间通过 git commit 保存进度
  │      → 检测到 <promise>COMPLETE</promise> 则结束循环
  └─ 否 → 使用标准模式 1-7

适合 Ralph Loop 的任务：有明确完成标准 / 需要反复试错 / 可自动验证 / 绿地项目

不适合的任务：需要人类判断的设计决策 / 一次性操作 / 完成标准模糊 / 生产环境调试

3.4 安全机制

机制	说明
`--max-iterations`	硬性限制，防止无限循环
`--escape-plan`	达到上限时的处理策略
`cancel` 命令	随时手动终止循环
状态持久化	重启后可恢复/检查状态
历史记录	可追溯每次迭代的进展

3.5 状态文件

状态保存在 memory/ralph/state.json，历史追加到 memory/ralph/history.jsonl。

Part 4: Operation Tracer — 操作追踪（v1.1 新增）

来源：operation-tracer v1.0.0 核心理念：追踪所有操作，为性能分析和错误诊断提供数据基础。

4.1 追踪内容

类型	说明	元数据示例
tool_call	工具调用	名称、参数、耗时、结果、状态
llm_call	LLM调用	token消耗、响应时间
error	错误和重试	错误类型、重试次数
compression	上下文压缩	压缩前后token数

4.2 核心 API

python

from scripts.tracer import OperationTracer
from scripts.analyzer import TraceAnalyzer

# 追踪操作
tracer = OperationTracer()
span_id = tracer.start_span("read_file", "tool_call", {"path": "/tmp/test"})
# ... 执行操作 ...
tracer.end_span(span_id, result="success", status="success")

# 分析数据
analyzer = TraceAnalyzer()
summary = analyzer.get_summary()           # 操作统计
slow_ops = analyzer.get_slow_operations(threshold_ms=1000)  # 慢操作识别
errors = analyzer.get_error_operations()   # 错误模式

4.3 与 Hook Engine 集成

text

PreExec Hook → tracer.start_span("exec", "tool_call", {command, workdir})
PostExec Hook → tracer.end_span(span_id, result=stdout, status=exitCode==0)

4.4 存储

SQLite数据库：traces/agent_traces.db

表	字段
spans	id, name, type, parent_id, start_time, end_time, duration_ms, status, metadata
errors	id, span_id, error_type, message, retry_count, timestamp

自动清理：保留最近7天数据，可通过配置调整。

4.5 数据导出

python

# 导出为 JSON
analyzer.export_json("traces/export.json")

# 导出为 CSV
analyzer.export_csv("traces/export.csv")

4.6 性能分析

python

# 获取慢操作（> 1秒）
slow = analyzer.get_slow_operations(threshold_ms=1000)
for op in slow:
    print(f"{op['name']}: {op['duration_ms']}ms")

# 获取错误统计
errors = analyzer.get_error_operations()
print(f"错误总数: {len(errors)}")

# 获取操作摘要
summary = analyzer.get_summary()
print(f"总操作数: {summary['total_spans']}")
print(f"成功率: {summary['success_rate']:.1%}")

文件结构

text

agent-safety/
├── SKILL.md                          # 本文档
├── hooks/
│   ├── pre-exec-check.sh             # 执行前安全检查
│   ├── post-exec-log.sh              # 执行后日志记录
│   ├── pre-message-format.sh         # 消息格式验证
│   └── pre-task-check.sh             # 任务前技能触发检查
├── rules/
│   ├── security-rules.md             # 安全规则集
│   ├── security-patterns.md          # 安全模式详细规则
│   ├── format-rules.md               # 格式规则集
│   ├── coding-skill-check.md         # 编码技能触发规则
│   └── skill-triggers.md             # 技能触发规则定义
├── scripts/
│   ├── ralph_loop.py                 # Ralph Loop 迭代循环管理器
│   ├── guardrail.py                  # 护栏统一接口
│   ├── input_guard.py                # 输入护栏（注入检测）
│   ├── tool_guard.py                 # 工具护栏（权限控制）
│   ├── output_guard.py               # 输出护栏（敏感信息过滤）
│   ├── test_guardrails.py            # 护栏测试用例
│   ├── tracer.py                     # 操作追踪器（v1.1 新增）
│   ├── analyzer.py                   # 追踪数据分析器（v1.1 新增）
│   └── test_tracer.py                # 追踪器测试用例（v1.1 新增）
├── traces/                           # 追踪数据存储（v1.1 新增）
│   └── agent_traces.db               # SQLite 数据库
└── references/
    ├── hook-api.md                    # Hook API 完整文档
    ├── injection_patterns.md          # 注入模式参考
    ├── permission_levels.md           # 权限分级参考
    └── trace_schema.md               # 追踪数据表结构（v1.1 新增）

测试

bash

cd <skill-dir>
python scripts/test_guardrails.py
python scripts/test_tracer.py

版本历史

版本	日期	变更
v1.1.0	2026-08-01	合并 operation-tracer：新增 Part 4 操作追踪（SQLite持久化 + 性能分析 + Hook Engine集成）
v1.0.0	2026-07-31	合并 hook-engine v1.2.0 + guardrail-system v1.0.0 + Ralph Loop

Version 1.1.0 — 合并自 hook-engine v1.2.0 + guardrail-system v1.0.0 + operation-tracer v1.0.0