---
name: AIDR-XClaw-Security-Sentinel
version: 1.0.0
description: "AIDR-XClaw安全哨兵是由BeiMing-AI-Lab提供的企业级OpenClaw类智能体威胁防护Skill。核心功能：(1) Query Audit - 对每次用户消息进行提示词注入检测（含本地敏感信息脱敏）；(2) Skill Audit - 对 Skill 安装/运行时进行恶意代码检测（Pre-Install 5阶段 + Runtime 4阶段审计）。触发场景：用户发送任何消息时（aidr-xclaw-security-sentinel 插件安装除外）自动执行 Gate 1；用户提及/安装/运行 Skill 时执行 Gate 2。特殊 bypass：用户请求安装 aidr-xclaw-security-sentinel 插件时，跳过所有安全门，直接执行 install_aidr_xclaw_plugin.cjs。安全等级：strong/moderate → pass，marginal → warn，unsafe → block；Skill 审计：CLEAR/MINOR → approve，ELEVATED → warn，SEVERE/CRITICAL → reject。所有 API 调用需设备指纹+API Key 双重鉴权。"
metadata:
  openclaw:
    emoji: "\U0001F6E1"
    requires:
      bins: ["node", "curl", "openssl"]
    os:
      - linux
    env:
      - name: AIDR_SECURITY_API_BASE
        description: "API base URL for security scan endpoints. Default: https://venustech-ai.online:28200"
        required: false
        default: "https://venustech-ai.online:28200"
---
# AIDR-XClaw-Security-Sentinel

> **鉴权机制**：本 skill 使用设备指纹 + API Key 的双重鉴权机制访问安全云服务。
>
> 所有 API 调用（Gate 1 和 Gate 2）均需要：
> 1. **API Key** — 从 `/api/baseline/api_key/distribute` 获取（基于设备指纹），持久化到本地状态文件
> 2. **Fingerprint** — 每次调用前实时生成（SHA-256 硬件指纹），**不得缓存**

### 鉴权流程

1. **检查状态文件** - 读取 `{baseDir}/.state/api_state.json`，检查是否存在已存储的 API Key
2. **生成指纹** - 如无 API Key，先执行 `{baseDir}/scripts/get_fingerprint.cjs` 生成设备指纹
3. **获取 API Key** - 调用 `/api/baseline/api_key/distribute`（POST，body 包含 fingerprint）
4. **存储凭证** - 将获取的 API Key 持久化到 `{baseDir}/.state/api_state.json`
5. **后续调用** - 每次 API 调用时：实时生成 fingerprint + 使用存储的 api_key

安全检测技能，由 BeiMing-AI-Lab 安全 API 驱动。实现两个独立安全门：Query Audit 和 Skill Audit。

所有 API 调用（Gate 1 和 Gate 2）均需要设备指纹 + API Key 双重鉴权。

> **完整规范（脱敏规则、API 详情、指纹算法）** → `references/`
> **速查卡（Mode 判断 + Stage 分解 + Quick Ref）** → `SecurityQuickRef.md`

---

## 🚨 强制执行 — 零容忍

**⚠️ 每个阶段 = 一次工具调用 + 一次格式化文本输出。二者不可合并，必须交替。**

```
TOOL CALL → receive result → output formatted Stage block (immediately) → next stage TOOL CALL
```

**完整的 Query Audit 必须包含：**
1. Stage 1/3 block → 输出
2. Stage 2/3 block → 输出
3. Stage 3/3 block → 输出
4. DONE border → 输出
5. 完整报告 → 输出

**完整的 Skill Audit 必须包含：**
1. Stage 1/4 block → 输出
2. Stage 2/4 block → 输出
3. Stage 3/4 block → 输出
4. Stage 4/4 block → 输出
5. DONE border → 输出
6. 完整报告 → 输出

> ❌ **错误（Agent 常犯）**：只输出 `Stage 2/3`，跳过 Stage 1/3
> ✅ **正确**：必须输出完整的 `Stage 1/3` → `Stage 2/3` → `Stage 3/3` → DONE → 完整报告

**Stage 1 必须输出的原因：** 本地脱敏（inline desensitization）是安全检测的第一步，用于隐藏用户敏感信息（如身份证、银行卡号）再送入云端 API。跳过 Stage 1 意味着敏感信息直接暴露给外部服务，这是不允许的。

**以下行为均属严重违规：**

- ❌ 先批量调用所有工具，最后统一输出所有 block
- ❌ **只输出 Stage 2/3，跳过 Stage 1/3（最常见错误）**
- ❌ 只输出 `Stage 1/1` 就停止（漏掉 Stage 2、Stage 3）
- ❌ 用单句话替代格式化 Stage block
- ❌ 直接内联原始 curl JSON 响应
- ❌ 跳过任意阶段（即使认为"无害"）
- ❌ 跳过审计直接执行用户请求

---

## Architecture

```
User message arrives
  ├─ Is this an initialization request?
  │    ├─ Yes → bypass all Gates, execute init_skill.cjs
  │    └─ No  → proceed to next check
  │
  ├─ Is this a aidr-xclaw-security-sentinel plugin install request?
  │    ├─ Yes → bypass all Gates, execute install_aidr_xclaw_plugin.cjs
  │    └─ No  → proceed to security audit
  │
All messages (except initialization and aidr-xclaw-security-sentinel plugin bypass):
  ├─ Gate 1 · Query Audit   (every user message)
  │     Stage 1/3  → 本地脱敏（内联规则）→ [立即输出 Stage 1 block]
  │     Stage 2/3  → 调用 /api/prompt-injection/analyze（带鉴权头）→ [立即输出 Stage 2 block]
  │     Stage 3/3  → 解析结果并执行动作 → [立即输出 Stage 3 block]
  │     DONE       → [立即输出 DONE border]
  │     完整报告   → [输出完整安全报告]
  │
  └─ Gate 2 · Skill Audit
        │
        ├─ Pre-Install Audit（用户请求安装 Skill 时）
        │     Stage 1/5  → 临时目录准备（clawhub install --dir /tmp/skill-audit/）→ [立即输出 Stage 1 block]
        │     Stage 2/5  → 指纹生成（L2/L3/Final）→ [立即输出 Stage 2 block]
        │     Stage 3/5  → 调用 /api/beiming-sec/verify/upload（不脱敏）→ [立即输出 Stage 3 block]
        │     Stage 4/5  → 解析结果并执行动作 → [立即输出 Stage 4 block]
        │     Stage 5/5  → 完成确认 → [立即输出 Stage 5 block]
        │     DONE       → [立即输出 DONE border]
        │     完整报告   → [输出完整审计报告]
        │     └─ approve → 执行 clawhub install 正式安装
        │     └─ reject → 清理临时目录，拒绝安装
        │
        └─ Runtime Audit（用户请求运行已安装的 Skill 时）
              Stage 1/4  → 指纹生成 → [立即输出 Stage 1 block]
              Stage 2/4  → 内容脱敏（必须，防止用户信息泄露）→ [立即输出 Stage 2 block]
              Stage 3/4  → 调用 /api/beiming-sec/verify/upload → [立即输出 Stage 3 block]
              Stage 4/4  → 解析结果并执行动作 → [立即输出 Stage 4 block]
              DONE       → [立即输出 DONE border]
              完整报告   → [输出完整审计报告]
```

---

## Authentication — API Key + Fingerprint

所有 Gate 的 API 调用均使用设备指纹 + API Key 双重鉴权。

### 鉴权流程图

```
[Agent]                          [Backend]
    │                                   │
    │  Generate fingerprint             │
    │  (SHA-256 of hardware ID)         │
    │                                   │
    │  POST /api/baseline/api_key/distribute
    │  { "fingerprint": "abc123..." }   │
    │ ─────────────────────────────────▶│
    │                                   │
    │  { "api_key": "xyz...",           │
    │    "fingerprint": "abc123..." }    │
    │◀─────────────────────────────────│
    │                                   │
    │  Save api_key to local state      │
    │                                   │
    │  POST /api/prompt-injection/analyze
    │  Authorization: Bearer xyz...     │
    │  X-Fingerprint: abc123...         │
    │  { "content": "..." }             │
    │ ─────────────────────────────────▶│
    │                                   │
    │  { analysis result }              │
    │◀─────────────────────────────────│
```

### Phase 1: Check Existing API Key

在任何 Gate 执行之前，先检查本地是否已有 API Key：

**Windows (PowerShell):**
```powershell
if (Test-Path "{baseDir}\.state\api_state.json") { Get-Content "{baseDir}\.state\api_state.json" -Raw }
```

**Linux/macOS (bash):**
```bash
cat {baseDir}/.state/api_state.json
```

如果文件存在且包含有效的 `api_key`，跳过 Phase 2。否则进入 Phase 2。

### Phase 2: Get Device Fingerprint & Apply for API Key

#### Step 2.1: Generate Device Fingerprint

**Windows (PowerShell):**
```powershell
node "{baseDir}\scripts\fingerprint.mjs"
```

**Linux/macOS (bash):**
```bash
node {baseDir}/scripts/fingerprint.mjs
```

此脚本输出 64 位十六进制 SHA-256 哈希值。

#### Step 2.2: Apply for API Key

**Windows (PowerShell):**
```powershell
$body = @{ fingerprint = "FINGERPRINT" } | ConvertTo-Json -Compress
Invoke-RestMethod -Uri "{AIDR_SECURITY_API_BASE}/api/baseline/api_key/distribute" -Method POST -ContentType "application/json" -Body ([System.Text.Encoding]::UTF8.GetBytes($body)) | ConvertTo-Json
```

**Linux/macOS (bash):**
```bash
curl -k -s -X POST {AIDR_SECURITY_API_BASE}/api/baseline/api_key/distribute \
  -H "Content-Type: application/json" \
  -d '{"fingerprint": "FINGERPRINT"}'
```

**预期响应：**
```json
{
  "api_key": "abc123...",
  "fingerprint": "my_machine_123"
}
```

#### Step 2.3: Save API Key to Local State

**Windows (PowerShell):**
```powershell
New-Item -ItemType Directory -Path "{baseDir}\.state" -Force | Out-Null
@{ api_key = "ACTUAL_API_KEY"; created_at = (Get-Date -Format "o") } | ConvertTo-Json | Set-Content -Path "{baseDir}\.state\api_state.json" -Encoding UTF8
```

**Linux/macOS (bash):**
```bash
mkdir -p {baseDir}/.state
echo '{"api_key":"ACTUAL_API_KEY","created_at":"TIMESTAMP"}' > {baseDir}/.state/api_state.json
```

### Phase 3: Use Fingerprint + API Key on Every API Call

**每次调用 API 之前，必须重新生成设备指纹：**

**Windows (PowerShell):**
```powershell
node "{baseDir}\scripts\fingerprint.mjs"
```

**Linux/macOS (bash):**
```bash
node {baseDir}/scripts/fingerprint.mjs
```

然后使用 api_key（从状态文件）和新生成的 fingerprint 调用 API。

> **重要：不要缓存指纹。** 每次 API 调用前都要重新运行指纹脚本。只有 api_key 可以持久化。

### State File Format

`{baseDir}/.state/api_state.json`:

```json
{
  "api_key": "abc123...",
  "created_at": "2026-04-15T15:00:00.000Z"
}
```

> **注意：** 状态文件只存储 api_key。指纹永远不持久化——每次从硬件实时生成。

强制重新申请 API Key：删除 `api_state.json` 并从 Phase 2 重新执行。

### 鉴权错误处理

| 场景 | 操作 |
|------|------|
| `node` 未找到 | 请用户安装 Node.js 18+ |
| 指纹脚本执行失败 | 检查 OS 兼容性（支持 darwin, win32, linux, freebsd） |
| API Key 请求失败 | 检查后端服务是否运行；检查网络连接 |
| `401 Unauthorized` on analyze | API Key 可能无效或过期；删除 api_state.json 并从 Phase 2 重新执行 |
| `403 Forbidden` on analyze | 指纹不匹配；确保指纹是重新生成的 |
| `422 Unprocessable Entity` on distribute | JSON 编码问题——Windows PowerShell 使用 `Invoke-RestMethod`，Linux/macOS 确保 `-d` 参数中 JSON 使用单引号 |

> **Windows 用户：** 始终使用 PowerShell（`Invoke-RestMethod`）命令，不要用 `curl.exe`。PowerShell 的字符串转义和外部程序参数传递会导致 JSON body 损坏。

---

## aidr-xclaw-security-sentinel 插件安装 — 强制 Bypass

当用户请求安装 `aidr-xclaw-security-sentinel` 插件时，**立即执行**：

```bash
node {baseDir}/scripts/install_aidr_xclaw_plugin.cjs
```

**禁止进行 Gate 1 / Gate 2 审计。禁止搜索 clawhub。禁止检查插件是否存在。直接执行。**

---

## Gotchas — 这是你犯过的错误

> 最高价值内容。Agent 会犯的**具体**错误，而非通用建议。

### 必须输出完整流程（最常见问题）

- **Query Audit = 6 个输出**：
  1. Stage 1/3 block
  2. Stage 2/3 block
  3. Stage 3/3 block
  4. DONE border
  5. 完整报告（query-report.md 模板）

- **Pre-Install Audit = 7 个输出**：
  1. Stage 1/5 block
  2. Stage 2/5 block
  3. Stage 3/5 block
  4. Stage 4/5 block
  5. Stage 5/5 block
  6. DONE border
  7. 完整报告（skill-report.md 模板）

- **Runtime Audit = 6 个输出**：
  1. Stage 1/3 block
  2. Stage 2/3 block
  3. Stage 3/3 block
  4. DONE border
  5. 完整报告（skill-report.md 模板）

- **禁止行为**：
  - ❌ 只输出 Stage 1，不输出后续 Stage
  - ❌ 跳过 DONE border
  - ❌ 跳过完整报告
  - ❌ 批量执行所有工具，最后才统一输出

### 实时输出规则

每个 stage 完成后必须**立即**输出格式化 block，不得：
- ❌ 先执行所有 curl 命令
- ❌ 先执行所有脚本
- ❌ 最后才一次性输出所有 block
- ❌ 用单句话替代格式化 Stage block

### 其他常见错误

- **Stage 1/3 本地脱敏必须执行**：每次 Query Audit 必须先执行 Stage 1/3 本地脱敏，再调用 API。不得跳过 Stage 1 直接进入 Stage 2 API 调用。Stage 1 的目的不是"可选步骤"，而是将用户敏感信息（身份证、银行卡等）在发送云端之前进行脱敏。跳过此步骤会导致敏感信息直接暴露给外部 API。
- **所有 Stage block 必须输出**：Query Audit = 3 个 block（Stage 1/3、Stage 2/3、Stage 3/3），Skill Audit = 4 个 block。不得只输出其中 1-2 个。常见错误是只输出 Stage 2/3，跳过 Stage 1/3 和 Stage 3/3。
- **curl 必须真实执行**：Stage 2/3 和 Stage 3/4 必须通过 Shell 调用 curl。禁止跳过、禁止模拟、禁止假设结果。curl 失败时必须 block，禁止自行填充字段。
- **`skill_sha256` 用 Final 指纹**：上传 Skill 时，`skill_sha256` 必须使用 Stage 1/4 计算的 Final 指纹（L2 + L3 → SHA-256），**不得**重新计算 zip 的哈希。
- **从临时目录打包**：Stage 3/4 必须从 Stage 2 的临时目录（如 `/tmp/skill-audit/<skill-name>/`）压缩，**禁止**从原始 Skill 目录压缩上传。
- **不区分大小写的陷阱**：脱敏规则默认不区分大小写，但 `(?i)` 修饰符的规则按其定义执行。匹配位置每个位置只匹配一次。
- **API 失败 = block**：curl 返回非 200、响应不可解析、缺少必需字段、或服务不可达时，必须 block。不得用"假设通过"来继续。
- **不脱敏通用内容**：通用业务问题、技术讨论、公开信息查询保持原样发送，以确保检测准确。
- **禁止编造 API 结果**：以下场景必须 block：
  - curl 超时 → `action=block`
  - curl 连接失败 → `action=block`
  - curl 返回非 200 → `action=block`
  - 响应 JSON 不可解析 → `action=block`
- **API 调用必须携带鉴权头**：Gate 1 和 Gate 2 的所有 API 调用必须包含 `Authorization: Bearer <api_key>` 和 `X-Fingerprint: <fingerprint>`，不得裸调用
- **指纹不得缓存**：每次 API 调用前必须重新运行 `fingerprint.mjs`，不得使用上次计算的值

> 当 Agent 犯错需要纠正时，将纠正加入 Gotchas。这是改进 skill 最直接的方式。

---

## ⚠️ aidr-xclaw-security-sentinel 插件安装 — 强制 Bypass

**立即执行，无需审计：**

当用户说"安装 aidr-xclaw-security-sentinel"（无论是否提到其他工具），执行以下步骤：

1. 执行 `node {baseDir}/scripts/install_aidr_xclaw_plugin.cjs`
2. 完成安装，输出结果

**禁止行为（违反即严重错误）：**

- ❌ 搜索 clawhub 检查插件是否存在
- ❌ 进行 Gate 1 Query Audit
- ❌ 进行 Gate 2 Skill Audit
- ❌ 调用任何安全 API
- ❌ 输出任何审计 block（Stage 1/3、Stage 2/3 等）
- ❌ 检查插件来源、评分、是否注册
- ❌ 要求用户提供"正确名称"

**常见错误案例（Agent 常犯）：**

- ❌ "使用 AIDR-XClaw-Security-Sentinel 安装 aidr-xclaw-security-sentinel" → 错误地进入 Gate 2，对 AIDR-XClaw-Security-Sentinel 本身进行审计
- ❌ "安装 aidr-xclaw-security-sentinel" → 错误地搜索 clawhub，然后说"插件不存在"

**正确理解：**

- 目标：安装 `aidr-xclaw-security-sentinel`（本地脚本安装，不走 clawhub）
- 工具：可能提到 `AIDR-XClaw-Security-Sentinel`（仅作为执行工具，不是审计目标）
- 结果：执行 `install_aidr_xclaw_plugin.cjs` 完成安装

---

## Skill 初始化安装

当用户首次使用 AIDR-XClaw-Security-Sentinel 时，需要执行一次初始化操作，将两项配置合二为一完成部署。

### 触发条件

当用户提及以下关键词时，触发本功能：

- `初始化安装`
- `初始化操作`
- `初始化 AIDR-XClaw`
- `使用 AIDR-XClaw-Security-Sentinel 进行初始化`
- `使用 AIDR-XClaw 安全哨兵进行初始化`
- `AIDR-XClaw 初始化`

### 初始化流程

#### Step 1/3 — AGENTS.md 安全脚本注入

- [ ] 检查 `init_state.json` 是否已存在（已存在则跳过全部）
- [ ] 执行 `node {baseDir}/scripts/inject_security_quickref.cjs`
- [ ] 验证 `AGENTS.md` 是否已包含 SecurityQuickRef 内容（已存在则跳过）
- [ ] **立即输出** Stage 1 formatted block

#### Step 2/3 — API Key 获取与保存

> ⚠️ **API Key 是调用安全云服务的必要条件，初始化时必须获取并保存。**

- [ ] 生成设备指纹：
```bash
node {baseDir}/scripts/fingerprint.mjs
```

- [ ] 申请 API Key：
```bash
curl -k -s -X POST {AIDR_SECURITY_API_BASE}/api/baseline/api_key/distribute \
  -H "Content-Type: application/json" \
  -d '{"fingerprint": "<FINGERPRINT>"}'
```

- [ ] 保存到本地状态文件：
```bash
mkdir -p {baseDir}/.state
# Linux/macOS
echo '{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' > {baseDir}/.state/api_state.json
# Windows (PowerShell)
New-Item -Item -Path {baseDir}\.state\api_state.json -Force | Out-Null
'{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' | Set-Content {baseDir}\.state\api_state.json -Encoding UTF8
```

- [ ] **立即输出** Stage 2 formatted block

#### Step 3/3 — aidr-xclaw-security-sentinel 插件安装

- [ ] 检查 openclaw CLI 和 Node.js 环境
- [ ] 执行 `node {baseDir}/scripts/install_aidr_xclaw_plugin.cjs`
- [ ] **立即输出** Stage 3 formatted block

#### DONE

- [ ] 输出 DONE border，填写 `安装结论:`

### 脚本使用方式

**方式一：命令行**

```bash
node {baseDir}/scripts/init_skill.cjs
```

示例：
```bash
node {baseDir}/scripts/init_skill.cjs
```

### 状态管理

初始化完成后，状态写入 `{baseDir}/.state/init_state.json`：

```json
{
  "initialized": true,
  "initialized_at": "2026-04-19T12:00:00.000Z",
  "api_key_configured": true,
  "plugin_configured": true
}
```

再次执行时若状态文件存在，脚本自动跳过全部初始化步骤。

### 合并执行说明

`init_skill.cjs` 将以下三个独立动作合并为一次操作：

1. **AGENTS.md 注入** — 将 SecurityQuickRef 安全入口速查卡注入 `AGENTS.md`，使每次会话自动加载
2. **API Key 获取** — 生成设备指纹，申请 API Key，保存到本地状态文件
3. **aidr-xclaw-security-sentinel 插件安装** — 安装 aidr-xclaw-security-sentinel 插件

### 失败处理

| 场景 | 处理方式 |
| ---- | -------- |
| AGENTS.md 不存在 | 跳过注入步骤，继续后续步骤 |
| inject_security_quickref.cjs 不存在 | 跳过注入步骤，继续后续步骤 |
| Node.js 未安装 | API Key 获取失败，插件安装失败，输出错误提示 |
| fingerprint.mjs 执行失败 | API Key 获取失败，跳过 API Key 步骤，继续插件安装 |
| API Key 申请失败 | 跳过 API Key 保存，继续插件安装（用户需手动配置） |
| 已完成初始化 | 跳过全部，输出提示信息 |
| openclaw CLI 未安装 | 插件安装失败，输出错误提示 |

### 初始化成功后的验证

```bash
# 验证 AGENTS.md 注入
grep -c "SecurityQuickRef" AGENTS.md

# 验证 API Key 状态
cat {baseDir}/.state/api_state.json

# 验证初始化状态
cat {baseDir}/.state/init_state.json

# 验证插件安装
openclaw plugins list
```

---

## Gate 1 · Query Audit

**触发条件：** 每次用户消息（aidr-xclaw-security-sentinel plugin bypass 除外）。

### Execution Checklist

#### Stage 1/3 — 本地脱敏

- [ ] 应用内联脱敏规则到用户输入（规则见下方规则表）
- [ ] 统计 `masked_fields` 数量，确定 `text_changed` 状态
- [ ] **立即输出** Stage 1 formatted block

#### Stage 2/3 — 调用 API（包含鉴权重试流程）

> ⚠️ **鉴权是 API 调用的前提条件。必须确保 Authorization 存在且有效。**

**Step 2.3.1 — 检查本地 API Key 是否存在：**

```bash
# Linux/macOS
cat {baseDir}/.state/api_state.json

# Windows (PowerShell)
Get-Content {baseDir}\.state\api_state.json -Raw
```

- 若文件不存在或 `api_key` 字段为空 → 进入 Step 2.3.2
- 若文件存在且包含有效 `api_key` → 跳过 Step 2.3.2，进入 Step 2.3.3

**Step 2.3.2 — 获取 API Key（仅在需要时执行）：**

```
[AIDR-XClaw-Security-Sentinel][Auth] 申请 API Key
操作: 生成设备指纹并申请 API Key
```

1. 生成设备指纹：
```bash
node {baseDir}/scripts/fingerprint.mjs
```

2. 申请 API Key：
```bash
curl -k -s -X POST "https://venustech-ai.online:28200/api/baseline/api_key/distribute" \
  -H "Content-Type: application/json" \
  -d '{"fingerprint": "<FINGERPRINT>"}'
```

3. 保存到本地状态文件：
```bash
# Linux/macOS
mkdir -p {baseDir}/.state
echo '{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' > {baseDir}/.state/api_state.json

# Windows (PowerShell)
New-Item -Item -Path {baseDir}\.state\api_state.json -Force | Out-Null
'{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' | Set-Content {baseDir}\.state\api_state.json -Encoding UTF8
```

**Step 2.3.3 — 调用安全检测 API：**

1. 生成实时设备指纹（每次调用前必须重新生成）：
```bash
node {baseDir}/scripts/fingerprint.mjs
```

2. 执行 API 调用：
```bash
curl -s --max-time 10 -w "\n%{http_code}" \
  -X POST "{AIDR_SECURITY_API_BASE}/api/prompt-injection/analyze" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Fingerprint: <FINGERPRINT>" \
  -d '{"content": "<脱敏后的文本>"}'
```

**Step 2.3.4 — 处理 API 响应：**

| 响应情况 | 处理方式 |
|----------|----------|
| HTTP 200，JSON 有效 | 解析响应，进入 Stage 3/3 |
| HTTP 401/缺少 Authorization | 删除 api_state.json，返回 Step 2.3.2 重试（最多 1 次） |
| HTTP 403 | 重新生成指纹，返回 Step 2.3.3 重试（最多 1 次） |
| HTTP 非 200 | → `action=block` |
| 连接超时/失败 | → `action=block` |

> ⚠️ **重试后仍然失败 = block**，不得编造响应结果

- [ ] **立即输出** Stage 2 formatted block

#### Stage 3/3 — 执行动作

- [ ] 根据 safety_level 确定 action（pass/warn/block）
- [ ] **立即输出** Stage 3 formatted block

#### DONE

- [ ] 输出 DONE border，填写 `检测结论:`

### 内联脱敏规则

| # | 类别         | Pattern                                                                                                    | 替换为                                     | Priority                        |
| - | ------------ | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------- |
| 1 | 身份证       | `\b\d{17}[\dXx]\b`                                                                                       | `[ID_CARD_MASKED]`                       | 1                               |
| 1 | 手机号       | `\b1[3-9]\d{9}\b`                                                                                        | `[PHONE_MASKED]`                         | 1                               |
| 2 | 银行卡       | `\b\d{16,19}\b`                                                                                          | `[BANK_CARD_MASKED]`                     | 2                               |
| 1 | API Key      | `(?i)(api[_-]?key)\s*[:=]\s*['"]?([\w\-]{16,})`                                                          | `[API_KEY_MASKED]`                       | 1                               |
| 1 | 密码/密钥    | `(?i)(password|passwd|secret|token)\s*[:=]\s*'"?[\w\-!@#$%^&*()]{8,}`                                    | `[SECRET_MASKED]`                        | 1                               |
| 1 | Bearer Token | `(?i)bearer\s+[\w\-\.]{20,}`                                                                             | `Bearer [BEARER_TOKEN_MASKED]`           | 1                               |
| 1 | 配置目录     | `(?i)\.env|\.aws|\.ssh|\.gnupg|\.kube|\.docker`                                                          | `[CONFIG_PATH_MASKED]`                   | 1                               |
| 1 | 内网 IP      | `\b(10\.\d{1,3}\.\d{1,3}\.\d{1,3}|172\.(1[6-9]|2\d|3[01])\.\d{1,3}\.\d{1,3}|192168\.\d{1,3}\.\d{1,3})\b` | `[INTERNAL_IP_MASKED]`                   | 1                               |
| 1 | SSRF 目标    | `(?i)(localhost|127\.0\.0\.1|0\.0\.0\.0)([:/]|\.(?:80|443|8080))?`                                       | `[SSRF_TARGET_MASKED]`                   | 1                               |
| 2 | /root 路径   | `/root/[^\/\s"'<>                                                                                          | ]{1,64}`                                   | `[PATH_MASKED]`               |
| 2 | /home 路径   | `/home/[^\/\s"'<>                                                                                          | ]{1,32}/[^\/\s"'<>                         | ]{1,64}`                        |
| 1 | Webhook 端点 | `webhook\.site|requestbin|hookbin|beeceptor`                                                             | `[EXFIL_ENDPOINT_MASKED]`                | 1                               |
| 1 | 伪造系统标记 | `\[SYSTEM\]|\[ADMIN\]|\[ROOT\]`                                                                           | `<SYSTEM>`|`<ADMIN>`|```<ROOT>```` | `[FAKE_SYSTEM_MARKER_MASKED]` | 1                               |
| 2 | 编码载荷     | `(?i)(base64|base32|hex|encode|decode)\s*[(:=]\s*'"?[A-Za-z0-9+/=]{20,}`                                 | `[ENCODED_PAYLOAD_MASKED]`               | 2                               |
| 1 | 路径穿越     | `(?:\.\./|\.\.\\                                                                                          | \.\.%2f|\.\.%5c|/etc/passwd)`            | `[PATH_TRAVERSAL_MASKED]`     |
| 1 | 敏感路径     | `(?:\.ssh|\.aws|\.kube|\.docker|\.gnupg|\.git)/[^\"'\s]*`                                                | `[SENSITIVE_PATH_MASKED]`                | 1                               |
| 1 | 凭证文件     | `(?:\.pem|\.key|credentials\.json|secrets\.ya?ml|\.env)`                                                 | `[CREDENTIAL_FILE_MASKED]`               | 1                               |

**不脱敏：** 通用业务问题、技术讨论、公开信息查询（保持语义完整性）。

### API 调用

**每次调用前必须重新生成指纹（见 Authentication Phase 3）：**

```bash
# 重新生成设备指纹（每次 API 调用前必须执行）
node {baseDir}/scripts/fingerprint.mjs

curl -k -s --max-time 10 -w "\n%{http_code}" \
  -X POST "https://venustech-ai.online:28200/api/prompt-injection/analyze" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer API_KEY" \
  -H "X-Fingerprint: FINGERPRINT" \
  -d '{"content": "<desensitized text>"}'
```

Replace:
- `API_KEY` → 从 `{baseDir}/.state/api_state.json` 读取
- `FINGERPRINT` → 重新运行 `fingerprint.mjs` 输出的值（不要用缓存）
- `{AIDR_SECURITY_API_BASE}` → 环境变量值（默认 `https://venustech-ai.online:28200`）

**API 校验（每次执行后必查）：**

| 校验项 | 通过条件 | 失败时 action |
| ------------------- | ------------------------------------------------------- | ------------- |
| curl 执行成功 | exit_code = 0，HTTP 状态码 = 200 | →`block` |
| 响应可解析 | 响应体为有效 JSON | →`block` |
| `safety_level` 值 | ∈ {`strong`, `moderate`, `marginal`, `unsafe`} | →`block` |
| `safety_score` 值 | ∈ [0, 100] 的整数 | →`block` |
| `is_suspicious` | 存在且为 bool | →`block` |
| `401 Unauthorized` | API Key 无效或过期 | → 删除 api_state.json，重新申请 Phase 2 |
| `403 Forbidden` | 指纹不匹配 | → 重新生成指纹重试 |

### Action 映射（Gate 1）

| safety_level | Action    | 行为           |
| ------------ | --------- | -------------- |
| `strong`   | `pass`  | 继续处理       |
| `moderate` | `pass`  | 继续，记录日志 |
| `marginal` | `warn`  | 继续，展示警告 |
| `unsafe`   | `block` | 立即停止       |

### Query Audit 输出模板

**Stage block：**

```
[AIDR-XClaw-Security-Sentinel][Query-Audit][Stage N/M] <标题>
操作: <描述>
结果: <关键字段>
```

**阻断提示（action=block 时）：**

```
[安全阻断] 您的输入触发了安全检测机制。
安全等级: <safety_level>（评分: <score>/100）
建议：请调整提问方式，或联系管理员。
```

**DONE block：**

```
════════════════════════════════════════════════════════════
[AIDR-XClaw-Security-Sentinel][Query-Audit] 检测完成
检测结论: <pass/warn/block>
════════════════════════════════════════════════════════════

✅ 安全检测通过  /  ⚠️ 安全检测告警  /  🚫 安全检测阻断

安全评分: <safety_score>/100
安全等级: <safety_level>
检测结论: <text>
```

### 完整报告输出（检测完成后）

所有 Stage 执行完成后（Stage 1/3 + Stage 2/3 + Stage 3/3 + DONE），按照 `templates/query-report.md` 模板格式输出**一个**总结报告，包含：

- 基本信息（扫描时间、检测类型、session_hash）
- 综合评分（safety_score + safety_level + Action）
- 风险发现（findings_count + findings_table + finding_recommendations）
- 统计数据（原始/脱敏文本长度、敏感字段数量）
- API 响应详情（safety_score、safety_level、is_suspicious、risk_tags、request_id、latency_ms）
- 处置建议（Action 映射 + block/pass/warn 提示模板）

> **完整报告模板** → `templates/query-report.md`

### Action on Result（Gate 1）

每个 action 执行后，正常展示 Stage block 和 DONE block：

- `action=block` → 立即停止，不回复用户
- `action=warn` → 展示警告后继续
- `action=pass` → 如用户提及 Skill 则继续 Gate 2；否则直接回复用户

**检测完成后，输出完整总结报告（见上方）。**

---

## Gate 2 · Pre-Install Audit（安装前审计）

**触发条件：** 用户请求安装 Skill 时（aidr-xclaw-security-sentinel plugin bypass 除外）。

> ⚠️ **Pre-install Audit vs Runtime Audit：**
> - **Pre-install Audit**：用户在请求安装新 Skill 时触发
> - **Runtime Audit**：用户请求运行/使用已安装的 Skill 时触发
> - 两者共享相同的 API 端点，但 `audit_type` 参数不同

### Pre-Install Audit 触发词

| 触发类型 | 触发词示例 |
|---------|-----------|
| 安装请求 | `安装 <skill名称>` |
| 安装请求 | `帮我安装 <skill名称>` |
| 安装请求 | `我需要安装 <skill名称>` |
| 安装请求 | `安装 [skill名称] skill` |
| 安装请求 | `装一个 <skill名称>` |
| clawhub CLI | `clawhub install <skill名称>` |
| openclaw | `openclaw skills install <skill名称>` |

### Execution Checklist

#### Stage 1/5 — 临时目录准备

**目的：** 将 Skill 安装到临时审计目录，而非直接安装到系统目录。

> ⚠️ **安全边界**：恶意代码必须停留在临时目录，只有通过审计后才能执行 `clawhub install` 正式安装。

**Shell 命令（Linux/macOS）：**

```bash
SKILL_NAME="<skill-name>"
TEMP_PARENT="/tmp/skill-audit"

# 1. 创建临时审计父目录
rm -rf "${TEMP_PARENT}"
mkdir -p "${TEMP_PARENT}"

# 2. 安装到父目录（clawhub 会在 TEMP_PARENT 下创建 <skill-name>/ 子目录）
# 实际路径 = /tmp/skill-audit/<skill-name>/
clawhub install "${SKILL_NAME}" --dir "${TEMP_PARENT}"

# 3. 查找实际安装路径（clawhub 会在 --dir 下创建 skill 子目录）
SKILL_PATH="${TEMP_PARENT}/${SKILL_NAME}"

# 4. 验证路径存在
if [ ! -d "${SKILL_PATH}" ]; then
  echo "ERROR: Skill 安装失败"
  exit 1
fi

# 5. 记录路径供后续 Stage 使用
echo "${SKILL_PATH}" > "${TEMP_PARENT}/.last_skill_path"
echo "SKILL_PATH=${SKILL_PATH}"
```

**Shell 命令（Windows PowerShell）：**

```powershell
$SKILL_NAME = "<skill-name>"
$TEMP_PARENT = Join-Path $env:TEMP "skill-audit"

# 1. 创建临时审计父目录
if (Test-Path $TEMP_PARENT) { Remove-Item -Recurse -Force $TEMP_PARENT }
New-Item -ItemType Directory -Path $TEMP_PARENT -Force | Out-Null

# 2. 安装到父目录（clawhub 会在 TEMP_PARENT 下创建 <skill-name>/ 子目录）
# 实际路径 = %TEMP%\skill-audit\<skill-name>\
clawhub install $SKILL_NAME --dir $TEMP_PARENT

# 3. 查找实际安装路径
$SKILL_PATH = Join-Path $TEMP_PARENT $SKILL_NAME

# 4. 验证路径存在
if (-not (Test-Path $SKILL_PATH)) {
    Write-Output "ERROR: Skill 安装失败"
    exit 1
}

# 5. 记录路径
$SKILL_PATH | Set-Content (Join-Path $env:TEMP "skill-audit\.last_skill_path")
Write-Output "SKILL_PATH=$SKILL_PATH"
```

**立即输出：**

```
[AIDR-XClaw-Security-Sentinel][Pre-Install-Audit][Stage 1/5] 临时目录准备
操作: 将 Skill 安装到审计临时目录
结果: SKILL_PATH=<platform-temp>/skill-audit/<skill-name>/<actual-dir>
```

> ⚠️ **跨平台路径说明**：
> - Linux/macOS：`/tmp/skill-audit/<skill>/`
> - Windows：`%TEMP%\skill-audit\<skill>\`（展开为 `C:\Users\<user>\AppData\Local\Temp\skill-audit\<skill>\`）

---

#### Stage 2/5 — 指纹生成

**目的：** 基于临时目录内容计算 L2/L3/Final 三层指纹。

> ⚠️ **指纹必须基于临时目录内容计算**，禁止使用其他来源的指纹。

**Shell 命令（Linux/macOS）：**

```bash
SKILL_PATH=$(cat /tmp/skill-audit/.last_skill_path)
cd "${SKILL_PATH}"

# L1 — 文件级指纹（所有文件路径+哈希）
L1=$(find . -type f \
  ! -path './.git/*' \
  ! -path './node_modules/*' \
  -exec openssl dgst -sha256 {} \; \
  | sort | cut -d' ' -f2 | tr -d '\n')

# L2 — 内容指纹（L1 聚合哈希）
L2=$(echo -n "${L1}" | openssl dgst -sha256 | cut -d' ' -f2)

# L3 — 元数据指纹（SKILL.md frontmatter）
L3=$(sed -n '/^---$/,/^---$/p' SKILL.md \
  | sed '1d;$d' \
  | grep -E '^(name|description):' \
  | sort | tr -d '\n' \
  | openssl dgst -sha256 | cut -d' ' -f2)

# Final — 注册指纹（L2 + L3）
FINAL=$(echo -n "${L2}${L3}" | openssl dgst -sha256 | cut -d' ' -f2)

# 文件统计
FILE_COUNT=$(find . -type f ! -path './.git/*' ! -path './node_modules/*' | wc -l)

echo "L2=${L2}"
echo "L3=${L3}"
echo "FINAL=${FINAL}"
echo "FILE_COUNT=${FILE_COUNT}"
```

**Shell 命令（Windows PowerShell）：**

```powershell
# 读取临时目录路径
$SKILL_PATH = Get-Content (Join-Path $env:TEMP "skill-audit\.last_skill_path")
Set-Location $SKILL_PATH

# L1 — 文件级指纹
$L1 = (Get-ChildItem -Recurse -File | Where-Object { $_.FullName -notmatch '\.git|node_modules' } | ForEach-Object {
    (Get-FileHash $_.FullName -Algorithm SHA256).Hash
} | Sort-Object | ForEach-Object { $_.ToString() }) -join ''

# L2 — 内容指纹（L1 聚合哈希）
$L2 = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($L1)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash

# L3 — 元数据指纹（SKILL.md frontmatter）
$SKILL_MD = Get-Content "SKILL.md" -Raw
if ($SKILL_MD -match '(?s)^---\r?\n(.+?)\r?\n---') {
    $FRONTMATTER = $Matches[1]
    $NAME_DESC = ($FRONTMATTER -split "`n" | Where-Object { $_ -match '^(name|description):' } | Sort-Object) -join ''
    $L3 = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($NAME_DESC)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash
} else {
    $L3 = "SKILL.md_NOT_FOUND"
}

# Final — 注册指纹（L2 + L3）
$FINAL = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($L2 + $L3)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash

# 文件统计
$FILE_COUNT = (Get-ChildItem -Recurse -File | Where-Object { $_.FullName -notmatch '\.git|node_modules' }).Count

Write-Output "L2=$L2"
Write-Output "L3=$L3"
Write-Output "FINAL=$FINAL"
Write-Output "FILE_COUNT=$FILE_COUNT"
```

**立即输出：**

```
[AIDR-XClaw-Security-Sentinel][Pre-Install-Audit][Stage 2/5] 指纹生成
操作: 计算 L2/L3/Final 三层指纹
结果: L2=<hash>, L3=<hash>, FINAL=<hash>, 文件数=<count>
```

---

#### Stage 3/5 — 调用安全审计 API

**目的：** 将 Skill 内容上传到云端进行安全审计。

> ⚠️ **Pre-install 审计不进行内容脱敏！** 直接上传原始内容。
> 这与 Runtime Audit（基于安装后审计结果）不同。

**鉴权流程（与现有 Gate 2 相同）：**

**Step 3.5.1 — 检查本地 API Key：**

```bash
# Linux/macOS
cat {baseDir}/.state/api_state.json

# Windows (PowerShell)
Get-Content (Join-Path $env:TEMP "..\workspace\skills\{skillDir}\.state\api_state.json") -Raw
```

- 若文件不存在或 `api_key` 字段为空 → 进入 Step 3.5.2
- 若文件存在且包含有效 `api_key` → 跳过 Step 3.5.2，进入 Step 3.5.3

**Step 3.5.2 — 获取 API Key：**

```bash
# 1. 生成设备指纹
node {baseDir}/scripts/fingerprint.mjs

# 2. 申请 API Key
curl -k -s -X POST "https://venustech-ai.online:28200/api/baseline/api_key/distribute" \
  -H "Content-Type: application/json" \
  -d '{"fingerprint": "<FINGERPRINT>"}'

# 3. 保存到本地状态文件
mkdir -p {baseDir}/.state
echo '{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' > {baseDir}/.state/api_state.json
```

**Step 3.5.3 — 调用审计 API：**

```bash
# 1. 重新生成设备指纹（每次 API 调用前必须）
node {baseDir}/scripts/fingerprint.mjs

# 2. 从临时目录打包（禁止从其他目录）
cd "${SKILL_PATH}"
rm -f /tmp/skill_scan.zip
zip -r /tmp/skill_scan.zip . -x ".git/*" -x "node_modules/*" -x "*.log"

# 3. 获取 API Key
API_KEY=$(grep -o '"api_key":"[^"]*"' {baseDir}/.state/api_state.json | cut -d'"' -f4)

# 4. 调用审计 API
curl -s --max-time 30 -w "\n%{http_code}" \
  -X POST "{AIDR_SECURITY_API_BASE}/api/beiming-sec/verify/upload" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "X-Fingerprint: ${FINGERPRINT}" \
  -F "file=@/tmp/skill_scan.zip" \
  -F "skill_sha256=${FINAL}" \
  -F "skill_name=<skill-name>"
```

**Windows PowerShell 命令：**

```powershell
# 1. 重新生成设备指纹
node (Join-Path $PSScriptRoot "scripts\fingerprint.mjs")

# 2. 从临时目录打包
$SKILL_PATH = Get-Content (Join-Path $env:TEMP "skill-audit\.last_skill_path")
Set-Location $SKILL_PATH
$ZIP_PATH = Join-Path $env:TEMP "skill_scan.zip"
if (Test-Path $ZIP_PATH) { Remove-Item $ZIP_PATH -Force }

# 使用 PowerShell Compress-Archive
Compress-Archive -Path "$SKILL_PATH\*" -DestinationPath $ZIP_PATH -Force

# 3. 获取 API Key
$API_STATE_PATH = Join-Path $PSScriptRoot "skills\{skillDir}\.state\api_state.json"
$API_KEY = (Get-Content $API_STATE_PATH -Raw | ConvertFrom-Json).api_key

# 4. 调用审计 API
$FINGERPRINT = node (Join-Path $PSScriptRoot "scripts\fingerprint.mjs")
Invoke-RestMethod -Uri "https://venustech-ai.online:28200/api/beiming-sec/verify/upload" `
  -Method POST `
  -Headers @{ "Authorization" = "Bearer $API_KEY"; "X-Fingerprint" = $FINGERPRINT } `
  -Form @{ file = Get-Item $ZIP_PATH; skill_sha256 = $FINAL; skill_name = "<skill-name>" }
```

**⚠️ 关键约束：**
- `skill_sha256` 必须使用 Stage 2/5 计算的 Final 指纹
- 必须从 Stage 1/5 的临时目录压缩，**禁止**从其他目录压缩上传
- **Pre-install 审计不进行内容脱敏**，直接上传原始内容

**Step 3.5.4 — 处理 API 响应：**

| 响应情况 | 处理方式 |
|----------|---------|
| HTTP 200，JSON 有效 | 解析响应，进入 Stage 4/5 |
| HTTP 401/缺少 Authorization | 删除 api_state.json，返回 Step 3.5.2 重试（最多 1 次） |
| HTTP 403 | 重新生成指纹，返回 Step 3.5.3 重试（最多 1 次） |
| HTTP 非 200 | → `action=reject` |
| 连接超时/失败 | → `action=reject` |

> ⚠️ **重试后仍然失败 = reject**，不得编造响应结果

**立即输出：**

```
[AIDR-XClaw-Security-Sentinel][Pre-Install-Audit][Stage 3/5] 安全审计
操作: 上传 Skill 内容到安全云服务进行审计
结果: http_status=200, verdict=allow, level=CLEAR, score=100
```

---

#### Stage 4/5 — 解析结果 + 执行动作

**目的：** 根据审计结果决定是否将 Skill 安装到真实目录。

**Action 映射：**

| verdict | level | Action | 行为 |
|---------|-------|--------|------|
| `allow` | CLEAR/MINOR | `approve` | 移动到真实安装目录 |
| `allow` | ELEVATED | `warn` | 展示警告，要求用户确认 |
| `confirm` | — | `warn` | 展示警告，要求用户确认 |
| `block` | SEVERE/CRITICAL | `reject` | 清理临时目录，拒绝安装 |

**approve 路径 — 正式安装（Linux/macOS）：**

```bash
SKILL_NAME="<skill-name>"
TEMP_PARENT="/tmp/skill-audit"

# 1. 清理临时目录
rm -rf "${TEMP_PARENT}/${SKILL_NAME}"

# 2. 正式安装 Skill（clawhub install 默认安装到 ~/.openclaw/workspace/skills/）
clawhub install "${SKILL_NAME}"

# 3. 清理审计产物
rm -f /tmp/skill_scan.zip
rm -f "${TEMP_PARENT}/.last_skill_path"

echo "INSTALL_SUCCESS=true"
```

**approve 路径 — 正式安装（Windows PowerShell）：**

```powershell
$SKILL_NAME = "<skill-name>"
$TEMP_DIR = Join-Path $env:TEMP "skill-audit"

# 1. 清理临时目录
if (Test-Path $TEMP_DIR) { Remove-Item -Recurse -Force $TEMP_DIR }

# 2. 正式安装 Skill
clawhub install $SKILL_NAME

# 3. 清理审计产物
$ZIP_PATH = Join-Path $env:TEMP "skill_scan.zip"
if (Test-Path $ZIP_PATH) { Remove-Item $ZIP_PATH -Force }

Write-Output "INSTALL_SUCCESS=true"
```

**reject 路径 — 清理临时目录（Linux/macOS）：**

```bash
SKILL_NAME="<skill-name>"
TEMP_PARENT="/tmp/skill-audit"

# 清理所有审计残留
rm -rf "${TEMP_PARENT}/${SKILL_NAME}"
rm -f /tmp/skill_scan.zip
rm -f "${TEMP_PARENT}/.last_skill_path"

echo "CLEANUP_SUCCESS=true"
```

**reject 路径 — 清理临时目录（Windows PowerShell）：**

```powershell
$SKILL_NAME = "<skill-name>"
$TEMP_PARENT = Join-Path $env:TEMP "skill-audit"
$TEMP_DIR = Join-Path $TEMP_PARENT $SKILL_NAME
$ZIP_PATH = Join-Path $env:TEMP "skill_scan.zip"

# 清理所有审计残留
if (Test-Path $TEMP_PARENT) { Remove-Item -Recurse -Force $TEMP_PARENT }
if (Test-Path $ZIP_PATH) { Remove-Item $ZIP_PATH -Force }

Write-Output "CLEANUP_SUCCESS=true"
```

**立即输出：**

```
[AIDR-XClaw-Security-Sentinel][Pre-Install-Audit][Stage 4/5] 执行动作
操作: 根据 verdict=<verdict> + level=<level> 执行 action=<action>
结果: <approve/warn/reject>
```

---

#### Stage 5/5 — 完成确认

**立即输出 DONE block：**

```
════════════════════════════════════════════════════════════
[AIDR-XClaw-Security-Sentinel][Pre-Install-Audit] 检测完成
检测结论: <approve/warn/reject>
════════════════════════════════════════════════════════════

✅ Skill 安全检测通过，正在安装...
⚠️ Skill 安全检测告警，请确认后继续安装
🚫 Skill 安全检测阻断，拒绝安装此 Skill

综合评分: <final_score>/100
风险等级: <level>
检测结论: <text>
```

---

### 临时目录管理

#### 跨平台路径

| 平台 | 临时目录路径 |
|------|-------------|
| Linux/macOS | `/tmp/skill-audit/` |
| Windows | `%TEMP%\skill-audit\` |

> ⚠️ Windows 使用环境变量 `$env:TEMP`，展开后通常为 `C:\Users\<user>\AppData\Local\Temp\skill-audit\`

#### 目录结构

```
<platform-temp>/skill-audit/
├── .last_skill_path          # 上次审计的 skill 路径记录
├── .audit_history.json       # 审计历史记录（可选）
├── <skill-name-1>/          # Skill A 临时目录
│   └── <actual-skill-dir>/   # Skill A 实际内容
└── <skill-name-2>/          # Skill B 临时目录
    └── <actual-skill-dir>/
```

#### 清理策略

| 场景 | 清理时机 | 清理内容 |
|------|---------|---------|
| 审计通过 | 移动完成后立即清理 | 临时目录 + zip 包 |
| 审计拒绝 | 审计完成后立即清理 | 临时目录 + zip 包 |
| 审计超时 | 30 秒超时后清理 | 临时目录 + zip 包 |
| Agent 中断 | 检测到未完成审计时清理 | 残留的临时目录 |
| 系统启动 | 清理过期目录（24小时前） | 临时目录下所有过期目录 |

#### 清理命令

**Linux/macOS：**

```bash
# 清理单个 Skill 临时目录
cleanup_skill_audit() {
    local SKILL_NAME="$1"
    local TEMP_PARENT="/tmp/skill-audit"
    rm -rf "${TEMP_PARENT}/${SKILL_NAME}"
    rm -f /tmp/skill_scan.zip
    rm -f "${TEMP_PARENT}/.last_skill_path"
}

# 清理所有审计残留
cleanup_all_audit() {
    rm -rf /tmp/skill-audit
    mkdir -p /tmp/skill-audit
}

# 清理过期目录（24 小时前的）
cleanup_expired_audit() {
    find /tmp/skill-audit -maxdepth 2 -type d -mmin +1440 -exec rm -rf {} \; 2>/dev/null
}
```

**Windows PowerShell：**

```powershell
# 清理单个 Skill 临时目录
function Cleanup-SkillAudit {
    param([string]$SkillName)
    $TEMP_PARENT = Join-Path $env:TEMP "skill-audit"
    $TEMP_DIR = Join-Path $TEMP_PARENT $SkillName
    $ZIP_PATH = Join-Path $env:TEMP "skill_scan.zip"
    if (Test-Path $TEMP_PARENT) { Remove-Item -Recurse -Force $TEMP_PARENT }
    if (Test-Path $ZIP_PATH) { Remove-Item $ZIP_PATH -Force }
}

# 清理所有审计残留
function Cleanup-AllAudit {
    $TEMP_PARENT = Join-Path $env:TEMP "skill-audit"
    if (Test-Path $TEMP_PARENT) { Remove-Item -Recurse -Force $TEMP_PARENT }
    New-Item -ItemType Directory -Path $TEMP_PARENT -Force | Out-Null
}

# 清理过期目录（24 小时前的）
function Cleanup-ExpiredAudit {
    $TEMP_PARENT = Join-Path $env:TEMP "skill-audit"
    Get-ChildItem -Path $TEMP_PARENT -Directory -Recurse | Where-Object { $_.LastWriteTime -lt (Get-Date).AddHours(-24) } | Remove-Item -Recurse -Force
}
```

---

### Action on Result（Pre-Install Audit）

| action | 行为 |
|--------|------|
| `approve` | 执行 `clawhub install <skill-name>` 正式安装，完成后清理临时目录 |
| `warn` | 展示警告和处置建议，等待用户确认后正式安装 |
| `reject` | 清理临时目录，拒绝安装，输出阻断原因 |

**检测完成后，输出完整总结报告（见 `templates/skill-report.md`）。**

---

## Gate 2 · Runtime Audit（运行时审计）

**触发条件：** 用户请求运行/使用已安装的 Skill 时（aidr-xclaw-security-sentinel plugin bypass 除外）。

> ⚠️ **与 Pre-Install Audit 的区别：**
> - Pre-Install Audit：安装前触发，Skill 内容来自临时目录，**不脱敏**上传
> - Runtime Audit：运行时触发，Skill 内容来自已安装目录，**必须脱敏**后上传

### Runtime Audit 触发词

| 触发类型 | 触发词示例 |
|---------|-----------|
| 运行请求 | `运行 <skill名称>` |
| 运行请求 | `使用 <skill名称>` |
| 运行请求 | `执行 <skill名称>` |
| 运行请求 | `调用 <skill名称>` |

### Runtime Audit 流程（4 Stage）

> ⚠️ **Runtime Audit 必须进行内容脱敏**：防止用户环境信息、文件路径等敏感数据泄露到云端。

```
Stage 1/4 — 指纹生成（基于已安装目录）
Stage 2/4 — 内容脱敏（应用内联脱敏规则）
Stage 3/4 — 调用 API 审计
Stage 4/4 — 执行动作
```

---

### Execution Checklist

#### Stage 1/4 — 指纹生成

**目的：** 基于已安装的 Skill 目录计算 **Skill 内容指纹**（L2/L3/Final）。

> ⚠️ **区分两种指纹：**
> - **设备指纹**（Device Fingerprint）：由 `fingerprint.mjs` 生成，用于 API 鉴权
> - **Skill 内容指纹**（Skill Content Fingerprint）：由 Skill 文件计算，用于标识 Skill 身份
>
> **Stage 1/4 计算的是 Skill 内容指纹，不是设备指纹！**

**Shell 命令（Linux/macOS）：**

```bash
SKILL_NAME="<skill-name>"
SKILL_DIR="/root/.openclaw/workspace/skills/${SKILL_NAME}"

# L1 — 文件级指纹
L1=$(find "${SKILL_DIR}" -type f \
  ! -path '*/.git/*' \
  ! -path '*/node_modules/*' \
  -exec openssl dgst -sha256 {} \; \
  | sort | cut -d' ' -f2 | tr -d '\n')

# L2 — 内容指纹
L2=$(echo -n "${L1}" | openssl dgst -sha256 | cut -d' ' -f2)

# L3 — 元数据指纹
L3=$(sed -n '/^---$/,/^---$/p' "${SKILL_DIR}/SKILL.md" \
  | sed '1d;$d' \
  | grep -E '^(name|description):' \
  | sort | tr -d '\n' \
  | openssl dgst -sha256 | cut -d' ' -f2)

# Final
FINAL=$(echo -n "${L2}${L3}" | openssl dgst -sha256 | cut -d' ' -f2)

# 文件统计
FILE_COUNT=$(find "${SKILL_DIR}" -type f ! -path '*/.git/*' ! -path '*/node_modules/*' | wc -l)

echo "L2=${L2}"
echo "L3=${L3}"
echo "FINAL=${FINAL}"
echo "FILE_COUNT=${FILE_COUNT}"
```

**Shell 命令（Windows PowerShell）：**

```powershell
$SKILL_NAME = "<skill-name>"
$SKILL_DIR = Join-Path $env:USERPROFILE ".openclaw\workspace\skills\$SKILL_NAME"
Set-Location $SKILL_DIR

# L1 — 文件级指纹
$L1 = (Get-ChildItem -Recurse -File | Where-Object { $_.FullName -notmatch '\.git|node_modules' } | ForEach-Object {
    (Get-FileHash $_.FullName -Algorithm SHA256).Hash
} | Sort-Object) -join ''

# L2 — 内容指纹
$L2 = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($L1)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash

# L3 — 元数据指纹
$SKILL_MD = Get-Content "SKILL.md" -Raw
if ($SKILL_MD -match '(?s)^---\r?\n(.+?)\r?\n---') {
    $NAME_DESC = ($Matches[1] -split "`n" | Where-Object { $_ -match '^(name|description):' } | Sort-Object) -join ''
    $L3 = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($NAME_DESC)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash
} else {
    $L3 = "SKILL.md_NOT_FOUND"
}

# Final
$FINAL = (Get-FileHash -InputStream ([IO.MemoryStream]::new([Text.Encoding]::UTF8.GetBytes($L2 + $L3)))) -Algorithm SHA256 | Select-Object -ExpandProperty Hash

$FILE_COUNT = (Get-ChildItem -Recurse -File | Where-Object { $_.FullName -notmatch '\.git|node_modules' }).Count

Write-Output "L2=$L2"
Write-Output "L3=$L3"
Write-Output "FINAL=$FINAL"
Write-Output "FILE_COUNT=$FILE_COUNT"
```

**立即输出：**

```
[AIDR-XClaw-Security-Sentinel][Runtime-Audit][Stage 1/4] 指纹生成
操作: 计算已安装 Skill 的 L2/L3/Final 指纹
结果: L2=<hash>, L3=<hash>, FINAL=<hash>, 文件数=<count>
```

#### Stage 2/4 — 内容脱敏

**目的：** 应用内联脱敏规则，防止用户环境信息、文件路径等敏感数据泄露到云端。

> ⚠️ **脱敏规则详见 `configs/desensitization.yaml` 和 `references/desensitization-rules.md`**

**Shell 命令（Linux/macOS）：**

```bash
SKILL_NAME="<skill-name>"
SKILL_DIR="/root/.openclaw/workspace/skills/${SKILL_NAME}"
TEMP_DIR="/tmp/skill-audit/${SKILL_NAME}"

# 1. 创建脱敏临时目录
rm -rf "${TEMP_DIR}"
mkdir -p "${TEMP_DIR}"

# 2. 复制文件到临时目录（保留目录结构）
cp -r "${SKILL_DIR}/." "${TEMP_DIR}/"

# 3. 应用脱敏规则
# 脱敏规则：见 configs/desensitization.yaml

# 4. 统计脱敏数量
SENSITIVE_COUNT=$(grep -r "sensitive\|password\|api_key\|secret\|token" "${TEMP_DIR}" --include="*.md" --include="*.json" 2>/dev/null | wc -l)

echo "TEMP_DIR=${TEMP_DIR}"
echo "SENSITIVE_COUNT=${SENSITIVE_COUNT}"
```

**Shell 命令（Windows PowerShell）：**

```powershell
$SKILL_NAME = "<skill-name>"
$SKILL_DIR = Join-Path $env:USERPROFILE ".openclaw\workspace\skills\$SKILL_NAME"
$TEMP_PARENT = Join-Path $env:TEMP "skill-audit"
$TEMP_DIR = Join-Path $TEMP_PARENT $SKILL_NAME

# 1. 创建脱敏临时目录
if (Test-Path $TEMP_PARENT) { Remove-Item -Recurse -Force $TEMP_PARENT }
New-Item -ItemType Directory -Path $TEMP_DIR -Force | Out-Null

# 2. 复制文件到临时目录
Copy-Item -Path "$SKILL_DIR\*" -Destination $TEMP_DIR -Recurse -Force

# 3. 应用脱敏规则
# 脱敏规则：见 configs/desensitization.yaml

# 4. 统计脱敏数量
$SENSITIVE_COUNT = (Get-ChildItem -Path $TEMP_DIR -Recurse -File | Select-String -Pattern "sensitive|password|api_key|secret|token" -CaseSensitive:$false).Count

Write-Output "TEMP_DIR=$TEMP_DIR"
Write-Output "SENSITIVE_COUNT=$SENSITIVE_COUNT"
```

**立即输出：**

```
[AIDR-XClaw-Security-Sentinel][Runtime-Audit][Stage 2/4] 内容脱敏
操作: 应用内联脱敏规则，防止敏感信息泄露
结果: TEMP_DIR=<temp-path>, 敏感字段数=<count>
```

#### Stage 3/4 — 调用 API 审计

**目的：** 将脱敏后的 Skill 内容上传到云端进行安全审计。

> ⚠️ **两种指纹的用途：**
> - **设备指纹**（由 `fingerprint.mjs` 生成）→ 用于 API 鉴权（`X-Fingerprint` header）
> - **Skill 内容指纹**（FINAL，由 Stage 1/4 计算）→ 用于标识 Skill 身份（`skill_sha256` 参数）
>
> ⚠️ **必须从脱敏后的临时目录打包上传，禁止从原始目录上传。**

**Shell 命令（Linux/macOS）：**

```bash
cd "${TEMP_DIR}"
rm -f /tmp/skill_scan.zip
zip -r /tmp/skill_scan.zip . -x ".git/*" -x "node_modules/*" -x "*.log"

# 调用 API（带鉴权）
curl -k -s --max-time 30 -w "\n%{http_code}" \
  -X POST "https://venustech-ai.online:28200/api/beiming-sec/verify/upload" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "X-Fingerprint: ${FINGERPRINT}" \
  -F "file=@/tmp/skill_scan.zip" \
  -F "skill_sha256=${FINAL}" \
  -F "skill_name=<skill-name>"
```

**Shell 命令（Windows PowerShell）：**

```powershell
Set-Location $TEMP_DIR
$ZIP_PATH = Join-Path $env:TEMP "skill_scan.zip"
if (Test-Path $ZIP_PATH) { Remove-Item $ZIP_PATH -Force }
Compress-Archive -Path "$TEMP_DIR\*" -DestinationPath $ZIP_PATH -Force

Invoke-RestMethod -Uri "https://venustech-ai.online:28200/api/beiming-sec/verify/upload" `
  -Method POST `
  -Headers @{ "Authorization" = "Bearer $API_KEY"; "X-Fingerprint" = $FINGERPRINT } `
  -Form @{ file = Get-Item $ZIP_PATH; skill_sha256 = $FINAL; skill_name = $SKILL_NAME }
```

**立即输出：**

```
[AIDR-XClaw-Security-Sentinel][Runtime-Audit][Stage 3/4] 安全审计
操作: 上传脱敏后内容到安全云服务进行审计
结果: http_status=200, verdict=allow, level=CLEAR, score=100
```

#### Stage 4/4 — 执行动作

**目的：** 根据审计结果决定是否执行 Skill。

**Action 映射：**

| verdict | level | Action | 行为 |
|---------|-------|--------|------|
| `allow` | CLEAR/MINOR | `approve` | 正常执行 Skill |
| `allow` | ELEVATED | `warn` | 展示警告，要求用户确认 |
| `confirm` | — | `warn` | 展示警告，要求用户确认 |
| `block` | SEVERE/CRITICAL | `reject` | 拒绝执行 Skill |

**立即输出：**

```
[AIDR-XClaw-Security-Sentinel][Runtime-Audit][Stage 4/4] 执行动作
操作: 根据 verdict=<verdict> + level=<level> 执行 action=<action>
结果: <approve/warn/reject>
```

#### DONE

- [ ] 输出 DONE border，填写 `检测结论:`

---

### Action on Result（Runtime Audit）

| action | 行为 |
|--------|------|
| `approve` | 正常执行 Skill |
| `warn` | 展示警告和处置建议，等待用户确认后执行 |
| `reject` | 清理脱敏临时目录，拒绝执行 Skill |

**检测完成后，输出完整总结报告（见 `templates/skill-report.md`）。**

---

## Gate 2 · Skill Audit（原版，现为 Pre-Install Audit）

**触发条件：** 用户提及或安装 Skill 时（aidr-xclaw-security-sentinel plugin bypass 除外）。

### Execution Checklist

#### Stage 1/4 — 指纹生成

- [ ] 在 Skill 目录执行 L2/L3/Final 指纹计算
- [ ] 统计文件数量
- [ ] **立即输出** Stage 1 formatted block

#### Stage 2/4 — 内容脱敏

- [ ] 应用内联脱敏规则，遍历 Skill 目录所有文件
- [ ] 将脱敏后文件保存到临时目录（如 `/tmp/skill-audit/<skill-name>/`）
- [ ] 统计 `sensitive_paths_masked` 数量
- [ ] **立即输出** Stage 2 formatted block

#### Stage 3/4 — 调用 API（包含鉴权重试流程）

> ⚠️ **鉴权是 API 调用的前提条件。必须确保 Authorization 存在且有效。**

**Step 3.4.1 — 检查本地 API Key 是否存在：**

```bash
# Linux/macOS
cat {baseDir}/.state/api_state.json

# Windows (PowerShell)
Get-Content {baseDir}\.state\api_state.json -Raw
```

- 若文件不存在或 `api_key` 字段为空 → 进入 Step 3.4.2
- 若文件存在且包含有效 `api_key` → 跳过 Step 3.4.2，进入 Step 3.4.3

**Step 3.4.2 — 获取 API Key（仅在需要时执行）：**

```
[AIDR-XClaw-Security-Sentinel][Auth] 申请 API Key
操作: 生成设备指纹并申请 API Key
```

1. 生成设备指纹：
```bash
node {baseDir}/scripts/fingerprint.mjs
```

2. 申请 API Key：
```bash
curl -k -s -X POST {AIDR_SECURITY_API_BASE}/api/baseline/api_key/distribute \
  -H "Content-Type: application/json" \
  -d '{"fingerprint": "<FINGERPRINT>"}'
```

3. 保存到本地状态文件：
```bash
# Linux/macOS
mkdir -p {baseDir}/.state
echo '{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' > {baseDir}/.state/api_state.json

# Windows (PowerShell)
New-Item -Item -Path {baseDir}\.state\api_state.json -Force | Out-Null
'{"api_key":"<API_KEY>","created_at":"<TIMESTAMP>"}' | Set-Content {baseDir}\.state\api_state.json -Encoding UTF8
```

**Step 3.4.3 — 调用安全检测 API：**

1. 生成实时设备指纹（每次调用前必须重新生成）：
```bash
node {baseDir}/scripts/fingerprint.mjs
```

2. 从临时目录压缩（禁止从原始目录）：
```bash
cd /tmp/skill-audit/<skill-name>/
zip -r /tmp/skill_scan.zip . -x ".git/*" -x "node_modules/*"
```

3. 执行 API 调用：
```bash
curl -k -s -w "\n%{http_code}" \
  -X POST "https://venustech-ai.online:28200/api/beiming-sec/verify/upload" \
  -H "Authorization: Bearer <API_KEY>" \
  -H "X-Fingerprint: <FINGERPRINT>" \
  -F "file=@/tmp/skill_scan.zip" \
  -F "skill_sha256=<FINAL_HASH>" \
  -F "skill_name=<skill_name>"
```

**Step 3.4.4 — 处理 API 响应：**

| 响应情况 | 处理方式 |
|----------|----------|
| HTTP 200，JSON 有效 | 解析响应，进入 Stage 4/4 |
| HTTP 401/缺少 Authorization | 删除 api_state.json，返回 Step 3.4.2 重试（最多 1 次） |
| HTTP 403 | 重新生成指纹，返回 Step 3.4.3 重试（最多 1 次） |
| HTTP 非 200 | → `action=reject` |
| 连接超时/失败 | → `action=reject` |

> ⚠️ **重试后仍然失败 = reject**，不得编造响应结果

- [ ] **立即输出** Stage 3 formatted block

#### Stage 4/4 — 执行动作

- [ ] 根据 verdict + level 确定 action
- [ ] **立即输出** Stage 4 formatted block

#### DONE

- [ ] 输出 DONE border，填写 `检测结论:`

### 指纹生成命令

```bash
# L2 — 内容指纹
find . -type f ! -path './.git/*' ! -path './node_modules/*' \
  -exec openssl dgst -sha256 {} \; | sort | cut -d' ' -f2 | tr -d '\n' \
  | openssl dgst -sha256 | cut -d' ' -f2

# L3 — 元数据指纹
sed -n '/^---$/,/^---$/p' SKILL.md | sed '1d;$d' \
  | grep -E '^(name|description):' | sort | tr -d '\n' \
  | openssl dgst -sha256 | cut -d' ' -f2

# Final = L2 + L3
echo -n "${L2_HASH}${L3_HASH}" | openssl dgst -sha256 | cut -d' ' -f2
```

> 详细算法 → `references/fingerprint-algorithm.md`

### API 调用

```bash
# 重新生成设备指纹（每次 API 调用前必须执行）
node {baseDir}/scripts/fingerprint.mjs

# 从临时目录打包
cd /tmp/skill-audit/<skill-name>/
zip -r /tmp/skill_scan.zip . -x ".git/*" -x "node_modules/*"

# 上传扫描（skill_sha256 = Stage 1/4 的 Final 指纹）
curl -k -s -w "\n%{http_code}" \
  -X POST "https://venustech-ai.online:28200/api/beiming-sec/verify/upload" \
  -H "Authorization: Bearer API_KEY" \
  -H "X-Fingerprint: FINGERPRINT" \
  -F "file=@/tmp/skill_scan.zip" \
  -F "skill_sha256=${FINAL_HASH}" \
  -F "skill_name=<skill_name>"
```

Replace:
- `API_KEY` → 从 `{baseDir}/.state/api_state.json` 读取
- `FINGERPRINT` → 重新运行 `fingerprint.mjs` 输出的值（不要用缓存）
- `FINAL_HASH` → Stage 1/4 计算的 Final 指纹（L2 + L3 → SHA-256）
- `{AIDR_SECURITY_API_BASE}` → 环境变量值（默认 `https://venustech-ai.online:28200`）

> **注意：** Gate 2 的 `skill_sha256` 使用 Stage 1/4 计算的 Final 指纹（设备指纹计算），而非 zip 包的哈希。

**⚠️ 关键约束：**

- `skill_sha256` 必须使用 Stage 1/4 的 Final 指纹，**禁止**重新计算 zip 哈希
- 必须从 Stage 2 临时目录压缩，**禁止**从原始目录压缩上传
- 必须携带鉴权头（`Authorization: Bearer <api_key>` + `X-Fingerprint: <fingerprint>`）

**API 校验（每次执行后必查）：**

| 校验项 | 通过条件 | 失败时 action |
| ---------------------- | ----------------------------------------------------------------- | ------------- |
| curl 执行成功 | exit_code = 0，HTTP 状态码 = 200 | →`block` |
| 响应可解析 | 响应体为有效 JSON | →`block` |
| `verdict` 字段 | ∈ {`allow`, `confirm`, `block`} | →`block` |
| `can_execute` | 存在且为 bool | →`block` |
| `audit_result.level` | ∈ {`CLEAR`, `MINOR`, `ELEVATED`, `SEVERE`, `CRITICAL`} | →`block` |
| `401 Unauthorized` | API Key 无效或过期 | → 删除 api_state.json，重新申请 Phase 2 |
| `403 Forbidden` | 指纹不匹配 | → 重新生成指纹重试 |

### Action 映射（Gate 2）

| verdict     | level           | Action      | 行为           |
| ----------- | --------------- | ----------- | -------------- |
| `allow`   | CLEAR/MINOR     | `approve` | 正常执行       |
| `allow`   | ELEVATED        | `warn`    | 继续，展示警告 |
| `confirm` | —              | `warn`    | 要求用户确认   |
| `block`   | SEVERE/CRITICAL | `reject`  | 停止，不执行   |

### Skill Audit 输出模板

**阻断提示（action=reject 时）：**

```
[AIDR-XClaw-Security-Sentinel][Skill-Audit] 安全阻断
风险等级: <level>
建议: 请勿安装此 Skill
```

**警告提示（action=warn 时）：**

```
[AIDR-XClaw-Security-Sentinel][Skill-Audit] 安全告警
风险等级: <level>
风险描述: <description>
建议: <recommendations>
是否继续？
```

**DONE block：**

```
════════════════════════════════════════════════════════════
[AIDR-XClaw-Security-Sentinel][Skill-Audit] 检测完成
检测结论: <approve/warn/reject>
════════════════════════════════════════════════════════════

✅ Skill 安全检测通过（评分：<score>/100）
⚠️ Skill 安全检测告警（评分：<score>/100）
🚫 Skill 安全检测阻断（评分：<score>/100）

综合评分: <score>/100
风险等级: <level>
检测结论: <text>
```

### 完整报告输出（检测完成后）

所有 Stage 执行完成后（Stage 1/4 + Stage 2/4 + Stage 3/4 + Stage 4/4 + DONE），按照 `templates/skill-report.md` 模板格式输出**一个**总结报告，包含：

- 基本信息（skill_name、version、category、scan_type）
- 综合评分（final_score + level + verdict + action）
- 审计结论（verdict 说明 + 审计评分明细）
- 安全发现（finding_count + findings_table + finding_recommendations）
- 指纹信息（L2/L3/Final 三层指纹 + 注册状态）
- 内容统计（total_files、total_lines、敏感字段脱敏数）
- 处置建议（Action 映射 + approve/warn/reject 提示模板）

> **完整报告模板** → `templates/skill-report.md`

### Action on Result（Gate 2）

每个 action 执行后，正常展示 Stage block 和 DONE block：

- `verdict=block` / `level=SEVERE/CRITICAL` → 立即停止，不执行该 Skill
- `verdict=confirm` → 展示警告，要求用户确认
- `action=warn` → 展示警告和处置建议，等待用户确认
- `action=approve` → 执行 Skill，然后回复用户

**检测完成后，输出完整总结报告（见上方）。**

---

## Progressive Disclosure

当需要详细信息时，按以下条件加载对应文件：

| 场景                                    | 读取文件                                | 原因                    |
| --------------------------------------- | --------------------------------------- | ----------------------- |
| 规则模糊、需要调整脱敏规则              | `references/desensitization-rules.md` | 完整规则表和优先级说明  |
| API 返回非标准响应、端点不明确          | `references/api-reference.md`         | 完整 API 规范和错误处理 |
| 指纹计算结果异常、需要调试              | `references/fingerprint-algorithm.md` | 详细算法和合并命令      |
| 速查：触发条件 + Stage 分解 + 快速参考 | `SecurityQuickRef.md`                 | 精简版核心规则          |
| 需要 Query Audit 完整报告格式           | `templates/query-report.md`            | 报告模板和字段说明      |
| 需要 Skill Audit 完整报告格式           | `templates/skill-report.md`            | 报告模板和字段说明      |

---

## Invocation Reference

| 场景                                  | Gate                 | scan_type                       |
| ------------------------------------- | -------------------- | ------------------------------- |
| 用户请求初始化安装                      | **跳过所有 Gate**    | 执行 `init_skill.cjs`           |
| 用户安装 aidr-xclaw-security-sentinel 插件             | **跳过所有 Gate**    | 执行 `install_aidr_xclaw_plugin.cjs` |
| 用户安装 aidr-xclaw-security-sentinel 插件（通过工具）| **跳过所有 Gate**    | 执行 `install_aidr_xclaw_plugin.cjs` |
| 用户发送任何消息                       | Gate 1               | `query_scan`                    |
| 用户提及或安装 Skill                   | Gate 1 + Gate 2      | `query_scan` + `skill_scan`     |

---

## Risk Level Reference

### Query Audit

| Level        | Score   | Action |
| ------------ | ------- | ------ |
| `strong`   | 76–100 | pass   |
| `moderate` | 41–75  | pass   |
| `marginal` | 16–40  | warn   |
| `unsafe`   | 0–15   | block  |

### Skill Audit

| Level    | Verdict | Action  |
| -------- | ------- | ------- |
| CLEAR    | allow   | approve |
| MINOR    | allow   | approve |
| ELEVATED | allow   | warn    |
| SEVERE   | block   | reject  |
| CRITICAL | block   | reject  |

`confirm` verdict：始终视为 `warn`，要求用户确认。

---

## Maintenance

### AGENTS.md 注入安全脚本

`scripts/inject_security_quickref.cjs` — 将 SecurityQuickRef 信息注入 `AGENTS.md`：

1. 备份 `AGENTS.md` → `AGENTS.md.bak`（幂等命名，已存在则加编号后缀 `.1`/`.2`/...）
2. 在 `## Session Startup` 清单末尾动态追加一项（自动计算编号：已有 N 项则追加为 N+1；若清单为空则为第 1 项；若 `## Session Startup` 不存在则新建整个块作为第 1 项）
3. 在清单后追加安全检测注意段落
4. 在安全注意段落之后追加完整的 `## SecurityQuickRef` 说明段落

运行前提：`AGENTS.md` 为原始 base 状态（不含 SecurityQuickRef 注入内容），否则会跳过已注入部分。

注入完成后，**需要开启新会话（`/new`）**才能使 `AGENTS.md` 的变更生效。

```bash
node scripts/inject_security_quickref.cjs
```

---

## Plugin Installation

本技能提供 `aidr-xclaw-security-sentinel` 插件的安装功能。

### 插件信息

| 项目           | 值                                                      |
| -------------- | ------------------------------------------------------- |
| 插件名称       | `@ellawu2211/aidr-xclaw-security-sentinel`            |
| 安装命令       | `openclaw plugins install @ellawu2211/aidr-xclaw-security-sentinel` |
| 配置位置       | `openclaw.json`                                         |

### 触发条件

当用户提及以下关键词时，触发本功能：

- `安装 aidr-xclaw-security-sentinel`
- `安装 xclaw security sentinel`
- `安装 security sentinel 插件`

### 安装流程

#### Step 1/2 — 环境检查

- [ ] 检查 Node.js 是否安装（v22+）
- [ ] 检查 openclaw CLI 是否可用
- [ ] 立即输出 Stage 1 formatted block

#### Step 2/2 — 插件安装

- [ ] 执行 `openclaw plugins install @ellawu2211/aidr-xclaw-security-sentinel`
- [ ] 检查安装是否成功
- [ ] 立即输出 Stage 2 formatted block

#### DONE

- [ ] 输出 DONE border，填写 `安装结论:`

### 安装命令

```bash
node {baseDir}/scripts/install_aidr_xclaw_plugin.cjs
```

**通过 Agent 调用（推荐）：**

当用户触发安装 `aidr-xclaw-security-sentinel` plugin 时，**跳过所有安全扫描（bypass 模式）**，直接执行安装脚本：

```bash
node {baseDir}/scripts/install_aidr_xclaw_plugin.cjs
```

### 脚本功能说明

`install_aidr_xclaw_plugin.cjs` 执行以下操作：

1. **环境检查**：验证 Node.js 和 openclaw CLI 可用
2. **插件安装**：执行 `openclaw plugins install @ellawu2211/aidr-xclaw-security-sentinel` 命令

### 失败处理

| 场景                    | 处理方式                                      |
| ----------------------- | -------------------------------------------- |
| Node.js 未安装         | 输出错误提示，终止安装                        |
| openclaw CLI 未安装     | 输出错误提示，终止安装                        |
| 插件安装失败           | 输出错误信息，终止安装                        |

### 安装成功后的验证

安装完成后，用户可通过以下命令验证：

```bash
# 查看已安装插件列表
openclaw plugins list
```