@carfiedli/runtime-guardrail 0.1.19

package/README.hooks-security.md

@@ -0,0 +1,1017 @@
+# Hook 安全检测接口数据格式定义
+
+> 目标读者：安全策略/风控服务开发同学  
+> 目标：明确 **OpenClaw 每个 hook 向安全检测服务发送的数据格式**，便于对接专业安全服务  
+> 文档更新时间：2026-03-13
+
+---
+
+## 1. 概述
+
+本文档定义了 OpenClaw Runtime Guardrail 中所有 hook 向远端安全检测服务发送数据时使用的**统一接口格式**。
+
+**设计目标：**
+1. 所有 hook 共用同一个接口，数据格式一致
+2. 提取关键检测字段，省略过长的数据（如历史消息、系统提示词等）
+3. 按 hook 类型分组，events 中只有当前 hook 对应的字段有值
+4. 清晰标识当前触发的 hook 类型
+
+---
+
+## 2. 数据结构定义
+
+### TypeScript 类型定义
+
+```typescript
+/** 安全检测请求（顶层结构） */
+interface SecurityCheckRequest {
+  /** 应用 ID（必须） */
+  Appid: string;
+  
+  /** 服务 ID（必须） */
+  ServiceId: string;
+  
+  /** 类型（必须），固定为 1 */
+  Type: number;
+  
+  /** Agent ID（必须） */
+  AgentId: string;
+  
+  /** 设备 ID（必须） */
+  DeviceId: string;
+  
+  /** 检测数据（必须） */
+  Data: SecurityCheckData;
+}
+
+/** 安全检测数据 */
+interface SecurityCheckData {
+  /** Hook 名称（必须），标识当前触发的 hook */
+  hook: HookType;
+  
+  /** 时间戳，毫秒（必须） */
+  timestamp: number;
+  
+  /** 事件数据，按 hook 类型分组（只有当前 hook 对应的字段有值，其他为空对象） */
+  events: EventsData;
+  
+  /** 上下文数据 */
+  ctx: ContextData;
+}
+
+type HookType = 
+  | "message_received"      // 用户消息到达
+  | "before_prompt_build"   // 提示词构建前
+  | "llm_input"             // LLM 请求发送前
+  | "before_tool_call"      // 工具调用前
+  | "tool_result_persist"   // 工具结果持久化前
+  | "before_message_write"  // 消息写入存储前
+  | "message_sending";      // 向外部渠道发送前
+
+interface EventsData {
+  /** 用户消息到达事件数据 */
+  message_received: MessageReceivedEvents | {};
+  
+  /** 提示词构建前事件数据 */
+  before_prompt_build: BeforePromptBuildEvents | {};
+  
+  /** LLM 请求发送前事件数据 */
+  llm_input: LlmInputEvents | {};
+  
+  /** 工具调用前事件数据 */
+  before_tool_call: BeforeToolCallEvents | {};
+  
+  /** 工具结果持久化前事件数据 */
+  tool_result_persist: ToolResultPersistEvents | {};
+  
+  /** 消息写入存储前事件数据 */
+  before_message_write: BeforeMessageWriteEvents | {};
+  
+  /** 向外部渠道发送前事件数据 */
+  message_sending: MessageSendingEvents | {};
+}
+
+// ========== 各 Hook 事件数据结构 ==========
+
+/** message_received 事件数据 */
+interface MessageReceivedEvents {
+  from?: string;
+  content: string;
+  metadata: {
+    provider: string;
+    surface: string;
+    originatingChannel: string;
+    messageId: string;
+    senderId: string;
+  };
+}
+
+/** before_prompt_build 事件数据 */
+interface BeforePromptBuildEvents {
+  prompt: string;
+  // 注意：messages 数组因数据量过大，不包含在送检数据中
+}
+
+/** llm_input 事件数据 */
+interface LlmInputEvents {
+  runId: string;
+  sessionId: string;
+  provider: string;
+  model: string;
+  prompt: string;
+  imagesCount: number;
+  // 注意：以下字段因数据量过大，不包含在送检数据中：
+  // - systemPrompt: 系统提示词（可能非常长）
+  // - historyMessages: 历史消息数组
+}
+
+/** before_tool_call 事件数据 */
+interface BeforeToolCallEvents {
+  toolName: string;
+  params: Record<string, unknown>;
+  runId: string;
+  toolCallId: string;
+  /** Skill 名称（当检测到读取 SKILL.md 时填充，否则为空字符串） */
+  skillName: string;
+}
+
+/** tool_result_persist 事件数据 */
+interface ToolResultPersistEvents {
+  toolName: string;
+  toolCallId: string;
+  content: string;       // 提取后的工具输出内容
+  isError: boolean;
+  isSynthetic: boolean;
+  // 注意：原始 message 对象因结构复杂且数据量大，已简化为 content 字符串
+}
+
+/** before_message_write 事件数据 */
+interface BeforeMessageWriteEvents {
+  role: "user" | "assistant" | "toolResult";
+  content: string;       // 提取后的消息内容
+  stopReason?: string;   // assistant 角色特有
+  usage?: UsageInfo;     // assistant 角色特有
+  toolName?: string;     // toolResult 角色特有
+  isError?: boolean;     // toolResult 角色特有
+  // 注意：原始 message 对象因结构复杂，已简化为扁平结构
+}
+
+/** message_sending 事件数据 */
+interface MessageSendingEvents {
+  to: string;
+  content: string;
+  metadata?: Record<string, unknown>;
+}
+
+// ========== 辅助类型定义 ==========
+
+/** Token 使用统计 */
+interface UsageInfo {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+}
+
+// ========== 上下文数据结构 ==========
+
+interface ContextData {
+  /** Agent ID */
+  agentId?: string;
+  
+  /** 会话 ID（UUID 格式） */
+  sessionId?: string;
+  
+  /** 运行 ID（单次 LLM 调用追踪） */
+  runId?: string;
+  
+  /** 工具名称（工具相关 hook） */
+  toolName?: string;
+}
+```
+
+---
+
+## 3. 字段详解
+
+### 3.1 请求包装字段
+
+| 字段 | 类型 | 必须 | 说明 |
+|------|------|:----:|------|
+| `Appid` | string | ✅ | 应用 ID，用于标识调用方应用 |
+| `ServiceId` | string | ✅ | 服务 ID，用于标识安全检测服务 |
+| `Type` | number | ✅ | 请求类型，固定为 1 |
+| `AgentId` | string | ✅ | Agent ID，用于标识 Agent 实例 |
+| `DeviceId` | string | ✅ | 设备 ID，用于标识设备实例 |
+| `Data` | object | ✅ | 安全检测数据，包含 hook、timestamp、events、ctx |
+
+### 3.2 Data 内部字段
+
+| 字段 | 类型 | 必须 | 说明 |
+|------|------|:----:|------|
+| `Data.hook` | string | ✅ | Hook 名称，标识当前触发的 hook 类型 |
+| `Data.timestamp` | number | ✅ | 事件时间戳（毫秒） |
+| `Data.events` | object | ✅ | 事件数据，按 hook 类型分组，只有当前 hook 对应的字段有值 |
+| `Data.ctx` | object | ✅ | 上下文数据，来源于 rawContext |
+
+### 3.3 events 字段组
+
+`events` 对象包含 7 个子字段，分别对应 7 种 hook 类型。**当某个 hook 触发时，只有对应的子字段有值，其他均为空对象 `{}`**。
+
+| 子字段 | 对应 Hook | 说明 |
+|--------|-----------|------|
+| `message_received` | message_received | 用户消息数据 |
+| `before_prompt_build` | before_prompt_build | 提示词构建数据 |
+| `llm_input` | llm_input | LLM 请求数据 |
+| `before_tool_call` | before_tool_call | 工具调用数据 |
+| `tool_result_persist` | tool_result_persist | 工具结果数据 |
+| `before_message_write` | before_message_write | 消息写入数据 |
+| `message_sending` | message_sending | 出站消息数据 |
+
+### 3.4 ctx 字段组
+
+| 字段 | 类型 | 说明 | 使用的 Hook |
+|------|------|------|-------------|
+| `agentId` | string | Agent 实例 ID | 全部 |
+| `sessionId` | string | 会话 ID（UUID 格式） | llm_input, before_tool_call |
+| `runId` | string | 单次 LLM 调用的运行 ID | llm_input, before_tool_call |
+| `toolName` | string | 工具名称 | before_tool_call, tool_result_persist |
+
+---
+
+## 4. 各 Hook 事件数据详解
+
+### 4.1 message_received
+
+用户消息到达时的原始数据。
+
+**触发时机**：收到用户消息时  
+**返回语义**：观察型，返回 `void`
+
+#### events.message_received 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `from` | string | 发送者标识（可能为空） |
+| `content` | string | 用户消息内容 |
+| `metadata.provider` | string | 消息提供者（如 "openclaw"） |
+| `metadata.surface` | string | 消息表面（如 "ingress"） |
+| `metadata.originatingChannel` | string | 来源渠道 |
+| `metadata.messageId` | string | 消息唯一ID |
+| `metadata.senderId` | string | 发送者ID |
+
+#### ctx 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `agentId` | string | Agent 标识 |
+| `sessionId` | string | 会话ID |
+| `runId` | string | 运行ID |
+| `toolName` | string | 工具名称（如有） |
+
+---
+
+### 4.2 before_prompt_build
+
+提示词构建前的原始数据。
+
+**触发时机**：构建最终 prompt 前  
+**返回语义**：观察型，返回 `void`
+
+#### events.before_prompt_build 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `prompt` | string | 格式化后的提示词 |
+
+> ⚠️ **省略字段**：`messages` 数组（历史消息）因数据量过大，不包含在送检数据中
+
+#### ctx 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `agentId` | string | Agent 标识 |
+| `sessionId` | string | 会话ID |
+| `runId` | string | 运行ID |
+| `toolName` | string | 工具名称（如有） |
+
+---
+
+### 4.3 llm_input
+
+LLM 请求发送前的原始数据。
+
+**触发时机**：LLM 输入组装完成时  
+**返回语义**：观察型（OpenClaw 当前不消费返回值做阻断）
+
+#### events.llm_input 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `runId` | string | 运行ID |
+| `sessionId` | string | 会话ID |
+| `provider` | string | LLM 提供者（如 "custom-hunyuanapi-woa-com"） |
+| `model` | string | 模型名称（如 "hunyuan-2.0-instruct-20251111"） |
+| `prompt` | string | 用户提示词（格式化后） |
+| `imagesCount` | number | 图片数量 |
+
+> ⚠️ **省略字段**：
+> - `systemPrompt`：系统提示词（可能非常长，通常数万字符）
+> - `historyMessages`：历史消息数组（数据量过大）
+
+#### ctx 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `agentId` | string | Agent 标识 |
+| `sessionId` | string | 会话ID |
+| `runId` | string | 运行ID |
+| `toolName` | string | 工具名称（如有） |
+
+---
+
+### 4.4 before_tool_call
+
+工具调用执行前的原始数据。
+
+**触发时机**：工具执行前  
+**返回语义**：可返回 `{ block?: boolean; blockReason?: string }`
+
+#### events.before_tool_call 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `toolName` | string | 工具名称（如 "exec"、"read"） |
+| `params` | object | 工具参数对象（如 `{"command": "ls -la"}`） |
+| `runId` | string | 运行ID |
+| `toolCallId` | string | 工具调用ID |
+| `skillName` | string | Skill 名称（当检测到读取 SKILL.md 时填充，否则为空字符串） |
+
+> **Skill 名称识别逻辑**：
+> - 当 `toolName` 为 `"read"` 且 `params.path` 以 `SKILL.md` 结尾时，会尝试识别 skill 名称
+> - 优先从 SKILL.md 文件内容的 YAML frontmatter 中解析 `name` 字段
+> - 如果解析失败，则从路径中提取（SKILL.md 的上一级目录名）
+> - 如果不是读取 SKILL.md 的操作，`skillName` 为空字符串
+
+#### ctx 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `agentId` | string | Agent 标识 |
+| `sessionId` | string | 会话ID |
+| `runId` | string | 运行ID |
+| `toolName` | string | 工具名称 |
+
+---
+
+### 4.5 tool_result_persist
+
+工具结果持久化前的原始数据。
+
+**触发时机**：工具结果持久化前  
+**返回语义**：同步 hook，可返回 `{ message?: unknown }`
+
+#### events.tool_result_persist 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `toolName` | string | 工具名称 |
+| `toolCallId` | string | 工具调用ID |
+| `content` | string | 工具输出内容（已提取为字符串） |
+| `isError` | boolean | 是否错误 |
+| `isSynthetic` | boolean | 是否合成结果 |
+
+> ⚠️ **简化说明**：原始 `message` 对象包含复杂的嵌套结构（如 `content` 数组、`details` 对象等），已简化为 `content` 字符串以减少数据量
+
+#### ctx 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `agentId` | string | Agent 标识 |
+| `sessionId` | string | 会话ID |
+| `runId` | string | 运行ID |
+| `toolName` | string | 工具名称 |
+
+---
+
+### 4.6 before_message_write
+
+消息写入存储前的原始数据。根据 `role` 不同，字段有所差异。
+
+**触发时机**：消息写库前  
+**返回语义**：同步 hook，可返回 `{ block?: boolean; message?: unknown }`
+
+#### events.before_message_write 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `role` | string | 消息角色："user" / "assistant" / "toolResult" |
+| `content` | string | 消息内容（已提取为字符串） |
+| `stopReason` | string | 停止原因（仅 assistant 角色，如 "stop" 或 "toolUse"） |
+| `usage` | object | Token 使用统计（仅 assistant 角色，包含 input, output, totalTokens, cost 等） |
+| `toolName` | string | 工具名称（仅 toolResult 角色） |
+| `isError` | boolean | 是否错误（仅 toolResult 角色） |
+
+> ⚠️ **简化说明**：原始 `message` 对象包含复杂的嵌套结构（如 `content` 数组、`timestamp` 等），已简化为扁平结构以减少数据量
+
+#### ctx 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `agentId` | string | Agent 标识 |
+| `sessionId` | string | 会话ID |
+| `runId` | string | 运行ID |
+| `toolName` | string | 工具名称（如有） |
+
+---
+
+### 4.7 message_sending
+
+向外部渠道发送前的原始数据。
+
+**触发时机**：消息发送给用户前  
+**返回语义**：可返回 `{ content?: string; cancel?: boolean }`
+
+#### events.message_sending 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `to` | string | 消息接收者标识 |
+| `content` | string | 发送的消息内容 |
+| `metadata` | object | 附加元数据（可选） |
+
+#### ctx 字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `agentId` | string | Agent 标识 |
+| `sessionId` | string | 会话ID |
+| `runId` | string | 运行ID |
+| `toolName` | string | 工具名称（如有） |
+
+---
+
+## 5. 示例数据
+
+### 5.1 message_received
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "message_received",
+    "timestamp": 1741750768766,
+    "events": {
+      "message_received": {
+        "from": "",
+        "content": "帮我查看 /tmp 目录下有哪些文件",
+        "metadata": {
+          "provider": "openclaw",
+          "surface": "ingress",
+          "originatingChannel": "unknown",
+          "messageId": "msg_1741750768766",
+          "senderId": "main"
+        }
+      },
+      "before_prompt_build": {},
+      "llm_input": {},
+      "before_tool_call": {},
+      "tool_result_persist": {},
+      "before_message_write": {},
+      "message_sending": {}
+    },
+    "ctx": {
+      "agentId": "main",
+      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "runId": "run_xyz789",
+      "toolName": ""
+    }
+  }
+}
+```
+
+### 5.2 before_prompt_build
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "before_prompt_build",
+    "timestamp": 1741750768800,
+    "events": {
+      "message_received": {},
+      "before_prompt_build": {
+        "prompt": "帮我查看 /tmp 目录下有哪些文件"
+      },
+      "llm_input": {},
+      "before_tool_call": {},
+      "tool_result_persist": {},
+      "before_message_write": {},
+      "message_sending": {}
+    },
+    "ctx": {
+      "agentId": "main",
+      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "runId": "run_xyz789",
+      "toolName": ""
+    }
+  }
+}
+```
+
+> 注意：`messages` 数组（历史消息）因数据量过大，不包含在送检数据中
+
+### 5.3 llm_input
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "llm_input",
+    "timestamp": 1741750768949,
+    "events": {
+      "message_received": {},
+      "before_prompt_build": {},
+      "llm_input": {
+        "runId": "run_xyz789",
+        "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+        "provider": "custom-hunyuanapi-woa-com",
+        "model": "hunyuan-2.0-instruct-20251111",
+        "prompt": "帮我查看 /tmp 目录下有哪些文件",
+        "imagesCount": 0
+      },
+      "before_tool_call": {},
+      "tool_result_persist": {},
+      "before_message_write": {},
+      "message_sending": {}
+    },
+    "ctx": {
+      "agentId": "main",
+      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "runId": "run_xyz789",
+      "toolName": ""
+    }
+  }
+}
+```
+
+> 注意：以下字段因数据量过大，不包含在送检数据中：
+> - `systemPrompt`：系统提示词（可能非常长）
+> - `historyMessages`：历史消息数组
+
+### 5.4 before_tool_call
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "before_tool_call",
+    "timestamp": 1741750772191,
+    "events": {
+      "message_received": {},
+      "before_prompt_build": {},
+      "llm_input": {},
+      "before_tool_call": {
+        "toolName": "exec",
+        "params": {
+          "command": "ls -la /tmp"
+        },
+        "runId": "run_xyz789",
+        "toolCallId": "call_1741750772191",
+        "skillName": ""
+      },
+      "tool_result_persist": {},
+      "before_message_write": {},
+      "message_sending": {}
+    },
+    "ctx": {
+      "agentId": "main",
+      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "runId": "run_xyz789",
+      "toolName": "exec"
+    }
+  }
+}
+```
+
+### 5.4.1 before_tool_call（读取 SKILL.md 场景）
+
+当检测到正在读取 Skill 说明文档时，`skillName` 字段会自动填充：
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "before_tool_call",
+    "timestamp": 1741750772191,
+    "events": {
+      "message_received": {},
+      "before_prompt_build": {},
+      "llm_input": {},
+      "before_tool_call": {
+        "toolName": "read",
+        "params": {
+          "path": "~/.nvm/versions/node/v22.22.1/lib/node_modules/openclaw/skills/healthcheck/SKILL.md"
+        },
+        "runId": "run_xyz789",
+        "toolCallId": "call_1741750772191",
+        "skillName": "healthcheck"
+      },
+      "tool_result_persist": {},
+      "before_message_write": {},
+      "message_sending": {}
+    },
+    "ctx": {
+      "agentId": "main",
+      "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+      "runId": "run_xyz789",
+      "toolName": "read"
+    }
+  }
+}
+```
+
+> **说明**：`skillName` 的值优先从 SKILL.md 文件内容的 YAML frontmatter 中解析（格式如 `name: healthcheck`），解析失败则从路径中提取（SKILL.md 的上一级目录名）。
+
+### 5.5 tool_result_persist
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "tool_result_persist",
+    "timestamp": 1741750773781,
+    "events": {
+      "message_received": {},
+      "before_prompt_build": {},
+      "llm_input": {},
+      "before_tool_call": {},
+      "tool_result_persist": {
+        "toolName": "exec",
+        "toolCallId": "call_1741750773781",
+        "content": "total 4\ndrwxrwxrwt 2 root root 4096 Mar 12 03:26 .\ndrwxr-xr-x 1 root root 4096 Mar 12 03:25 ..",
+        "isError": false,
+        "isSynthetic": false
+      },
+      "before_message_write": {},
+      "message_sending": {}
+    },
+    "ctx": {
+      "agentId": "main",
+      "sessionId": "",
+      "runId": "",
+      "toolName": "exec"
+    }
+  }
+}
+```
+
+> 注意：原始 `message` 对象包含复杂的嵌套结构，已简化为 `content` 字符串
+
+### 5.6 before_message_write (role=user)
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "before_message_write",
+    "timestamp": 1741750768770,
+    "events": {
+      "message_received": {},
+      "before_prompt_build": {},
+      "llm_input": {},
+      "before_tool_call": {},
+      "tool_result_persist": {},
+      "before_message_write": {
+        "role": "user",
+        "content": "帮我查看 /tmp 目录下有哪些文件"
+      },
+      "message_sending": {}
+    },
+    "ctx": {
+      "agentId": "main",
+      "sessionId": "",
+      "runId": "",
+      "toolName": ""
+    }
+  }
+}
+```
+
+### 5.7 before_message_write (role=assistant)
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "before_message_write",
+    "timestamp": 1741750782718,
+    "events": {
+      "message_received": {},
+      "before_prompt_build": {},
+      "llm_input": {},
+      "before_tool_call": {},
+      "tool_result_persist": {},
+      "before_message_write": {
+        "role": "assistant",
+        "content": "/tmp 目录下当前没有用户文件，只有标准的 . 和 .. 目录项。"
+      },
+      "message_sending": {}
+    },
+    "ctx": {
+      "agentId": "main",
+      "sessionId": "",
+      "runId": "",
+      "toolName": ""
+    }
+  }
+}
+```
+
+> 注意：原始 `message` 对象包含 `usage`、`stopReason` 等字段，已简化
+
+### 5.8 before_message_write (role=toolResult)
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "before_message_write",
+    "timestamp": 1741750773784,
+    "events": {
+      "message_received": {},
+      "before_prompt_build": {},
+      "llm_input": {},
+      "before_tool_call": {},
+      "tool_result_persist": {},
+      "before_message_write": {
+        "role": "toolResult",
+        "content": "total 4\ndrwxrwxrwt 2 root root 4096 Mar 12 03:26 .",
+        "toolName": "exec",
+        "isError": false
+      },
+      "message_sending": {}
+    },
+    "ctx": {
+      "agentId": "main",
+      "sessionId": "",
+      "runId": "",
+      "toolName": "exec"
+    }
+  }
+}
+```
+
+> 注意：原始 `message` 对象包含复杂的嵌套结构，已简化为扁平结构
+
+### 5.9 message_sending
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "message_sending",
+    "timestamp": 1741750782900,
+    "events": {
+      "message_received": {},
+      "before_prompt_build": {},
+      "llm_input": {},
+      "before_tool_call": {},
+      "tool_result_persist": {},
+      "before_message_write": {},
+      "message_sending": {
+        "to": "unknown",
+        "content": "/tmp 目录下当前没有用户文件，只有标准的 . 和 .. 目录项。",
+        "metadata": {}
+      }
+    },
+    "ctx": {
+      "agentId": "main",
+      "sessionId": "",
+      "runId": "",
+      "toolName": ""
+    }
+  }
+}
+```
+
+---
+
+## 6. 安全检测服务建议
+
+### 6.1 按 Hook 类型的检测重点
+
+| Hook | events 子字段 | 检测重点 |
+|------|---------------|----------|
+| `message_received` | `message_received` | 用户输入恶意内容检测、注入攻击检测、敏感词过滤 |
+| `before_prompt_build` | `before_prompt_build` | 提示词注入检测、上下文污染检测 |
+| `llm_input` | `llm_input` | 模型滥用检测 |
+| `before_tool_call` | `before_tool_call` | 危险命令拦截、敏感文件访问检测、权限越界检测 |
+| `tool_result_persist` | `tool_result_persist` | 敏感输出检测、数据泄露检测 |
+| `before_message_write` | `before_message_write` | 敏感信息脱敏、内容合规检查 |
+| `message_sending` | `message_sending` | 出站敏感信息检测、合规审查 |
+
+### 6.2 字段优先级
+
+安全检测时建议优先关注的字段：
+
+**高优先级**：
+- `message_received.content` - 用户原始输入
+- `before_tool_call.toolName` + `before_tool_call.params` - 工具调用
+- `llm_input.prompt` - LLM 请求内容
+
+**中优先级**：
+- `tool_result_persist.content` - 工具输出
+- `before_message_write.content` - 写入消息内容
+- `message_received.metadata.senderId` - 发送者身份
+
+**低优先级**：
+- `llm_input.provider` / `model` - LLM 提供者信息
+- `ctx.*` - 上下文信息
+
+### 6.3 建议响应格式
+
+```json
+{
+  "action": "allow",
+  "reason": "no-risk-detected",
+  "reasonCodes": ["SAFE"],
+  "mutations": {}
+}
+```
+
+```json
+{
+  "action": "block",
+  "reason": "high-risk-command",
+  "reasonCodes": ["RISK_EXEC_COMMAND"],
+  "mutations": {
+    "blockReason": "命令存在高风险，已拦截"
+  }
+}
+```
+
+---
+
+## 7. 重要设计说明
+
+### 7.1 设计原则
+
+1. **精简数据结构**：events 中的数据提取关键检测字段，省略过长的数据（如历史消息、系统提示词等），以减少网络传输和处理开销
+2. **按 hook 分组**：events 对象包含所有 7 种 hook 的子字段，但只有当前触发的 hook 对应的字段有值
+3. **统一接口**：所有 hook 共用同一个接口格式，便于安全检测服务统一处理
+
+### 7.2 数据处理流程
+
+1. 安全检测服务收到请求后，首先检查 `hook` 字段确定当前触发的 hook 类型
+2. 根据 hook 类型，从 `events` 对象中提取对应的子字段数据
+3. 其他子字段均为空对象 `{}`，可以忽略
+
+### 7.3 省略字段说明
+
+为了减少网络传输和处理开销，以下字段因数据量过大而不包含在送检数据中：
+
+| Hook | 省略字段 | 说明 |
+|------|---------|------|
+| `before_prompt_build` | `messages` | 历史消息数组，可能包含大量历史对话 |
+| `llm_input` | `systemPrompt` | 系统提示词，通常数万字符 |
+| `llm_input` | `historyMessages` | 历史消息数组 |
+| `tool_result_persist` | 完整 `message` 对象 | 简化为 `content` 字符串 |
+| `before_message_write` | 完整 `message` 对象 | 简化为扁平结构 |
+
+### 7.4 ctx 字段来源
+
+`ctx` 字段包含当前请求的上下文信息，不同 hook 可能包含不同的字段组合：
+
+| Hook | ctx 包含的主要字段 |
+|------|-------------------|
+| message_received | agentId, sessionId, runId, toolName |
+| before_prompt_build | agentId, sessionId, runId, toolName |
+| llm_input | agentId, sessionId, runId, toolName |
+| before_tool_call | agentId, sessionId, runId, toolName |
+| tool_result_persist | agentId, sessionId, runId, toolName |
+| before_message_write | agentId, sessionId, runId, toolName |
+| message_sending | agentId, sessionId, runId, toolName |
+
+---
+
+## 8. 通用数据模板
+
+以下是一个包含所有可能字段的通用模板，实际数据只有当前 hook 对应的 events 子字段有值：
+
+```json
+{
+  "Appid": "100001",
+  "ServiceId": "your_service_id",
+  "Type": 1,
+  "AgentId": "main",
+  "DeviceId": "openclaw_device_001",
+  "Data": {
+    "hook": "message_received | before_prompt_build | llm_input | before_tool_call | tool_result_persist | before_message_write | message_sending",
+    "timestamp": 1741750768766,
+    "events": {
+      "message_received": {
+        "from": "发送者标识",
+        "content": "用户消息内容",
+        "metadata": {
+          "provider": "openclaw",
+          "surface": "ingress",
+          "originatingChannel": "unknown",
+          "messageId": "消息唯一ID",
+          "senderId": "发送者ID"
+        }
+      },
+      "before_prompt_build": {
+        "prompt": "格式化后的提示词"
+      },
+      "llm_input": {
+        "runId": "运行ID",
+        "sessionId": "会话ID",
+        "provider": "LLM提供者",
+        "model": "模型名称",
+        "prompt": "用户提示词",
+        "imagesCount": 0
+      },
+      "before_tool_call": {
+        "toolName": "工具名称",
+        "params": {},
+        "runId": "运行ID",
+        "toolCallId": "工具调用ID",
+        "skillName": "Skill名称（读取SKILL.md时填充）"
+      },
+      "tool_result_persist": {
+        "toolName": "工具名称",
+        "toolCallId": "工具调用ID",
+        "content": "工具输出内容",
+        "isError": false,
+        "isSynthetic": false
+      },
+      "before_message_write": {
+        "role": "user | assistant | toolResult",
+        "content": "消息内容"
+      },
+      "message_sending": {
+        "to": "接收者ID",
+        "content": "发送内容",
+        "metadata": {}
+      }
+    },
+    "ctx": {
+      "agentId": "Agent ID",
+      "sessionId": "会话ID (UUID)",
+      "runId": "运行ID",
+      "toolName": "工具名称"
+    }
+  }
+}
+```
+
+> **说明**：实际调用时，根据 `Data.hook` 字段的值，只有对应的 `events` 子字段有数据，其他均为空对象 `{}`。