Agent Safety v1.1.0

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

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

架构总览

┌─────────────────────────────────────────────────────────────────┐
│                        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 事件类型

1.2 规则引擎

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

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

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

---
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 中！

操作符：regex_match | contains | equals | not_contains | starts_with | ends_with

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

1.3 动作类型

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

1.4 Hook 脚本规范

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

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

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

1.5 与 daily-agent 集成

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

1.6 审计日志

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

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

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

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

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

集成代码示例：

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 注入模式（中英文）：

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

2.2 工具护栏 (ToolGuard)

2.3 输出护栏 (OutputGuard)

2.4 使用方法

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

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 核心概念

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

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

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

3.2 使用方法

# 启动循环
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：迭代循环模式：

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

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

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

3.4 安全机制

3.5 状态文件

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

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

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

4.1 追踪内容

4.2 核心 API

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 集成

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

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

4.5 数据导出

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

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

4.6 性能分析

# 获取慢操作（> 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%}")

文件结构

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 新增）

测试

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

版本历史

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