PIPL Guardrail

SKILL.md

---
name: pipl-guard
description: |
  PIPL 运行时护栏 (pipl-guard) v1.0.0。
  在 AI 应用的输入/输出链路中实时检测个人信息，按风险分级
  执行脱敏或阻断，供 Agent 主动调用。区别于事后审计，这是事中防护。

  Use when: 需要在 Agent 处理用户输入或返回结果前，实时拦截/脱敏
  个人信息；防止敏感数据流入大模型或被输出泄露；为 AI 应用加装
  符合《个人信息保护法》的运行时护栏。

  核心能力：
  - 🛡️ 实时检测中国大陆身份证、手机号、银行卡、护照、车牌、
    邮箱、IP/MAC 等结构化个人信息（含 Luhn / 身份证校验位校验）
  - 🧩 关键词线索识别（生物识别、医疗健康、行踪轨迹、未成年人等
    敏感个人信息类别）
  - 🎭 三种动作：detect（仅检测）/ mask（脱敏放行）/ block（高危阻断）
  - 📊 风险分级（high / medium / low）与结构化裁决结果（JSON）
  - 🧱 内核与规则分离：换规则包即得行业版（金融版规划中）

  触发关键词：护栏、guardrail、运行时防护、实时脱敏、输入输出过滤、
  个人信息拦截、PIPL 护栏、AI 合规护栏、敏感信息阻断
  适用范围：AI 应用输入/输出文本的运行时防护
  运行模式：纯本地，零网络请求，零动态执行 ❎
  外部依赖：Python 标准库（无需额外安装）
---

# 🛡️ PIPL 运行时护栏 (pipl-guard) v1.0.0

## 概述

pipl-guard 是面向 AI 应用的**运行时合规护栏**。它在 Agent 处理用户输入、
或向用户返回输出之前，实时检测其中的个人信息，并按风险等级执行脱敏或阻断。

与"事后审计"类工具（如合规自查、文件扫描）不同，护栏解决的是**事中**问题：
每一次调用能不能放行、要不要脱敏、是否必须阻断。二者互补，共同覆盖
AI 应用"事前自查 + 事中防护"的合规链路。

## 为什么是本地护栏

护栏是低延迟、高频的运行时组件，且处理的正是最敏感的数据。因此
pipl-guard 坚持**纯本地运行**：检测在本机完成，敏感数据不出机器，
无任何网络请求，无 `eval` / `exec` / 动态 import。这既满足运行时性能，
本身也是最强的 PIPL 友好特性。

## 快速开始

```bash
# 检测并脱敏（默认动作 mask）
python3 scripts/guard.py --text "我的身份证是110101199003074477"

# 从标准输入读取（适合管道 / Agent 调用）
echo "手机号13800138000" | python3 scripts/guard.py --stdin

# 高危阻断模式：命中 high 级敏感信息则拦截，不放行
python3 scripts/guard.py --text "身份证110101199003074477" --action block

# 结构化 JSON 输出（Agent 消费）
python3 scripts/guard.py --text "邮箱 a@b.com" --action detect --format json

# 列出可用规则包
python3 scripts/guard.py --list-profiles
```

## Agent 调用约定

护栏设计为 Agent 主动调用的检测工具，典型接法有两处：

**入口护栏（用户输入 → 模型）**：把用户输入交给护栏，`mask` 后再送入大模型，
防止敏感个人信息流入外部模型或日志。

**出口护栏（模型输出 → 用户）**：把模型输出交给护栏，`mask` 或 `block` 后
再返回用户，防止生成结果泄露个人信息。

护栏返回结构化裁决（`--format json`），关键字段：

| 字段 | 含义 |
|------|------|
| `decision` | `pass` / `masked` / `blocked` / `inspect_only` |
| `risk_level` | 本次最高风险等级 `high/medium/low/none` |
| `finding_count` | 命中条数（已去重） |
| `findings[]` | 每条命中的类别、等级、位置与脱敏预览（不含原文明文） |
| `output` | 处理后的文本；`blocked` 时为 `null` |

> 注意：`findings` 中仅提供脱敏预览（`preview`），不回传敏感原文，
> 避免护栏结果本身成为新的泄露面。

## 三种动作

| 动作 | 行为 | 适用 |
|------|------|------|
| `detect` | 仅检测并报告，不改动文本 | 审计、观察、灰度 |
| `mask` | 脱敏后放行（默认） | 大多数输入/输出防护 |
| `block` | 命中达阈值则阻断，否则脱敏 | 高敏场景、强合规要求 |

阻断阈值由 `--block-on` 控制（`high` / `medium` / `low`），默认 `high`：
默认脱敏放行、仅高危阻断，兼顾可用性与安全。

## 检测范围（common 规则包 v1.0.0）

结构化模式：身份证号、护照号、港澳通行证、统一社会信用代码、手机号、
固定电话、邮箱、银行卡号（Luhn）、IPv4、MAC 地址、车牌号。

关键词线索：生物识别（人脸/指纹/声纹/虹膜）、医疗健康（基因/病历/诊断）、
特定身份（宗教信仰）、行踪轨迹、家庭住址、未成年人/儿童。

身份证与银行卡均带校验位/Luhn 校验，重叠命中自动去重，只报最高风险项，
尽量降低误报——对合规护栏而言，误报与漏报同样损害可信度。

## 规则与内核分离

检测内核（`scripts/guard.py`）不含任何行业规则；规则集中在
`scripts/rules/` 下的规则包。通用版用 `common`，未来的金融版
（`pipl-guard-finance`）只需新增一个规则包并在 `PROFILES` 中登记，
内核逻辑完全复用。

## 安全与约束

- 纯本地运行，无任何网络请求、遥测或回调
- 无 `eval` / `exec` / 动态 import；规则通过显式映射加载，便于审计
- 不写入用户指定之外的文件；不修改自身代码
- 检测结果不回传敏感原文，仅提供脱敏预览
- 全部为可读 Python，无混淆、无二进制依赖

## ⚠️ 法律声明

### 免责条款

**使用本 pipl-guard 运行时护栏前请仔细阅读以下条款：**

1. **非法律建议**：本工具提供的检测、脱敏与拦截结果仅供参考，
   **不构成法律建议或合规证明**，不具备法律效力。
2. **无绝对保证**：个人信息形态多样，基于正则与关键词的检测
   **无法保证 100% 识别**，可能存在漏报或误报。用户不应将其作为
   唯一或最终的合规保障手段。
3. **按原样提供**：本工具按"原样"（AS IS）提供，不作任何明示或
   暗示的保证，包括适销性、特定用途适用性或检测完整性。
4. **责任限制**：在法律允许的最大范围内，开发者对使用或无法使用
   本工具产生的任何损失不承担责任。
5. **用户责任**：用户对其 AI 应用的合规性负全责，重大合规决策
   应咨询专业法律顾问，并结合组织制度、技术措施综合落实。
6. **数据安全**：本工具本地运行，处理数据留在用户设备上；
   用户应自行负责数据的备份与安全。

### 知识产权

本工具基于 MIT 许可证开源。所引用的法律法规原文（如《个人信息保护法》）
属政府公开信息，版权归原制定机关，用户应以官方发布版本为准。

### 使用限制

- ✅ 允许：作为 AI 应用运行时防护的辅助手段、脱敏预处理、合规体系的一环
- ❌ 禁止：作为法律证据或合规证明提交监管部门、替代专业法律咨询、
  用于规避法律义务、移除本声明后分发

### 管辖法律

本声明受中华人民共和国法律管辖。因本工具引发的争议，应先友好协商；
协商不成的，提交开发者所在地有管辖权的法院解决。

---

**PIPL 护栏系列 · 通用版**　为 AI 应用装上实时合规护栏