madeinplutofabio/pic-standard
GitHub: madeinplutofabio/pic-standard
一个面向 AI agent 的开源本地优先动作门控协议，在高影响工具调用执行前强制验证意图、来源和证据，防止 prompt 注入和幻觉转化为实际损害。
Stars: 21 | Forks: 5
#
PIC Standard: Provenance & Intent Contracts
**面向 AI agent 的 Local-first 动作门控。在任何高影响力工具调用执行之前，验证 intent、provenance 和 evidence。**
[](https://pypi.org/project/pic-standard/)
[](https://pypi.org/project/pic-standard/)
[](https://github.com/madeinplutofabio/pic-standard/actions/workflows/ci.yml)
[](https://github.com/madeinplutofabio/pic-standard/commits/main)
[](https://github.com/madeinplutofabio/pic-standard)
[](https://doi.org/10.5281/zenodo.18725562)
[](https://github.com/madeinplutofabio/pic-standard/blob/main/LICENSE)
PIC 是一个轻量级的 local-first 协议，它强制 AI agent 在执行每个重要动作之前必须**证明**其合理性。Agent 必须声明 intent（意图）、impact（影响）、provenance（来源）和 evidence（证据）；PIC 会验证一切，并在出现任何问题时**判定为失败并阻断**。
PIC 不是 agent 身份或授权委托基础设施；PIC 是一个与动作绑定的验证契约，用于决定某个高影响的工具调用现在执行是否正当。
*不再让幻觉变成实际的转账。不再让 prompt 注入触发数据导出。*
**示例 —— 当 PIC 阻断时：** 一条 Slack 消息要求 LLM agent 发送一笔 500 美元的付款。PIC 要求 agent 证明：*这个指令从何而来？来源是否受信任？是否有证据证明发票是真实的？* Slack 消息不包含受信任的 provenance，声明也没有支撑 evidence —— PIC 返回 `block`。支付工具永远不会执行。
## 目录
- [为什么选择 PIC？](#why-pic)
- [快速开始](#quickstart)
- [PIC 契约](#the-pic-contract)
- [工作原理](#how-it-works)
- [Evidence 验证](#evidence-verification)
- [Keyring（受信任的签名者）](#keyring-trusted-signers)
- [集成](#integrations)
- [RFC 与现有技术](#rfc--prior-art)
- [路线图](#roadmap)
- [贡献](#contributing)
## 为什么选择 PIC？
PIC 专为 agent 框架、内部工具网关和生产系统而构建，在这些系统中，必须在执行前证明高影响动作的合理性。
- 在动作边界**阻止 prompt 注入和盲目的工具调用**
- **100% 本地运行**：零云端，零数据离开您的机器
- **几分钟内即可接入您的技术栈**：LangGraph, MCP, OpenClaw, Cordum
- **开源**：审查它，fork 它，拥有它
## 快速开始
不到一分钟，即可在本地针对样本高影响 proposal 尝试验证器。
```
pip install pic-standard
# 验证示例 proposal
pic-cli verify examples/financial_irreversible.json
# 感知 Evidence 的验证 (hash)
pic-cli verify examples/financial_hash_ok.json --verify-evidence
# 感知 Evidence 的验证 (signature — 需要 example keyring)
# macOS / Linux
PIC_KEYS_PATH=pic_keys.example.json pic-cli verify examples/financial_sig_ok.json --verify-evidence
# PowerShell
# $env:PIC_KEYS_PATH="pic_keys.example.json"
# pic-cli verify examples/financial_sig_ok.json --verify-evidence
```
**可选的扩展组件：**
```
pip install "pic-standard[langgraph]" # LangGraph PICToolNode
pip install "pic-standard[mcp]" # MCP tool guarding
pip install "pic-standard[crypto]" # Ed25519 signature evidence
```
**从源码安装（贡献者）：**
```
git clone https://github.com/madeinplutofabio/pic-standard.git
cd pic-standard && pip install -e ".[langgraph,mcp,crypto]"
pytest -q
```
## PIC 契约
PIC 在工具执行前的那一刻强制执行。Agent 必须发出一个结构化的 Action Proposal（动作提案），该提案可以被验证、核实，并绑定到预期的工具。
| 字段 | 目的 |
|-------|---------|
| `intent` | Agent 试图做什么 |
| `impact` | 风险类别：`money`、`privacy`、`irreversible`、`compute` 等 |
| `provenance` | 哪些输入影响了决策（带有信任级别） |
| `claims` + `evidence` | Agent 的断言以及支持它的 evidence |
| `action` | 实际的工具调用（工具绑定） |
**规则：** 对于高影响的 proposal，至少有一个 claim 必须引用来自**受信任** provenance 的 evidence。否则判定为失败并阻断。
## 工作原理
```
graph TD
A[Untrusted Input] --> B{AI Agent / Planner}
C[Trusted Data/DB] --> B
B --> D[Action Proposal JSON]
D --> E[PIC Verifier]
E --> F{Valid Contract?}
F -- Yes --> G[Tool Executor]
F -- No --> H[Blocked / Alert Log]
```
## Evidence 验证
PIC 支持确定性的 evidence 验证，该验证可在内存中提升 provenance 信任级别。
| 类型 | 描述 |
|------|-------------|
| `hash` | 文件产物的 SHA-256 验证 (`file://...`) |
| `sig` | 通过受信任的 keyring 进行 Ed25519 签名验证 |
Ed25519 签名验证需要 `pip install "pic-standard[crypto]"`。
```
# 验证 hash evidence
pic-cli verify examples/financial_hash_ok.json --verify-evidence
# 验证 signature evidence (需要 keyring)
# macOS / Linux
PIC_KEYS_PATH=pic_keys.example.json pic-cli verify examples/financial_sig_ok.json --verify-evidence
# PowerShell
# $env:PIC_KEYS_PATH="pic_keys.example.json"
# pic-cli verify examples/financial_sig_ok.json --verify-evidence
```
完整指南：[docs/evidence.md](docs/evidence.md)
**规范化 (v0.8.0+)：** PIC Canonical JSON v1 (PIC-CJSON/1.0) 定义了 PIC 在对 JSON 值进行哈希或签名时使用的逐字节精确序列化规则。规范性规范见 [`docs/canonicalization.md`](docs/canonicalization.md)；一个纯标准库的参考实现位于 `pic_standard.canonical` (`canonicalize()`, `sha256_hex()`, `intent_digest_hex()`)。在 v0.8.0 中，这是一项附加功能——现有的签名验证路径继续像 v0.7.x 中那样工作；将规范化接入由 attestation 对象支持的签名计划在后续版本中发布。一致性测试向量位于 [`conformance/canonicalization/`](conformance/canonicalization/) 下，并在每次 PR 时通过 `PIC Conformance` CI 作业执行。
## Keyring（受信任的签名者）
签名 evidence 需要一个包含受信任公钥的 keyring，并支持过期和撤销功能。
```
pic-cli keys # Inspect current keyring
pic-cli keys --write-example # Generate starter keyring
```
**自定义解析器 (v0.7+)：** 从 v0.7 开始，信任解析是可注入的且为 local-first。PIC 不再为每个签名重新加载默认 keyring，自定义解析器可以直接插入验证器和流水线中。实现 `KeyResolver` 协议以使用您自己的信任后端或预加载的信任源（HSM 支持的服务、Vault 管理的密钥、缓存的远程 keyring 等）：
```
from pic_standard import KeyResolver, StaticKeyRingResolver
```
**信任控制 (v0.7.5+)：** PIC v0.7.5 引入了 `strict_trust` 模式——启用后，所有入站 provenance 信任都会被清理为“untrusted”，只有 evidence 验证才能提升它。有关迁移指南，请参阅 [docs/migration-trust-sanitization.md](docs/migration-trust-sanitization.md)。
完整指南：[docs/keyring.md](docs/keyring.md)
## 集成
### LangGraph
使用 `PICToolNode` 保护任何工具节点：
```
pip install "pic-standard[langgraph]"
```
`PICToolNode` 现在支持 `verify_evidence`、`strict_trust`、`policy` 和 `key_resolver`，以实现完整的流水线配置 (v0.7.5+)。
### MCP (Model Context Protocol)
具有判定失败并阻断默认设置、请求关联、DoS 限制和 evidence 沙箱的企业级工具保护：
```
pip install "pic-standard[mcp]"
```
完整指南：[docs/mcp-integration.md](docs/mcp-integration.md)
### OpenClaw
适用于 OpenClaw AI agent 的 TypeScript 插件 (`pic-gate`、`pic-init`、`pic-audit` hooks)：
```
pic-cli serve --port 7580
cd integrations/openclaw && npm install && npm run build
```
完整指南：[docs/openclaw-integration.md](docs/openclaw-integration.md)
### Cordum
Go Pack，将 PIC 验证作为 Cordum workflow 的门控步骤提供，具有判定失败并阻断的三向路由功能。
完整指南：[docs/cordum-integration.md](docs/cordum-integration.md)
### HTTP Bridge (任何语言)
对于非 Python 集成，PIC 提供了一个 HTTP bridge：
```
pic-cli serve --port 3100
# POST /verify — 验证 action proposal
# GET /health — 存活检查
# GET /v1/version — 包 + 协议版本
```
## RFC 与现有技术
[**RFC-0001: PIC/1.0 — Provenance & Intent Contracts for AI Agent Action Safety**](docs/RFC-0001-pic-standard.md)
涵盖范围、威胁模型、安全属性、一致性级别和现有技术差异的正式规范。作为防御性公开文献发布，并带有 SHA-256 指纹清单：[`docs/RFC-0001.SHA256`](docs/RFC-0001.SHA256)。
本地验证：`sha256sum -c docs/RFC-0001.SHA256`
[**Canonical Vocabulary**](docs/vocabulary.md) —— 被外部交叉引用和注册表引用的 PIC 术语权威词汇表。
## 路线图
- [x] 核心验证器、CLI、schema、策略系统
- [x] Evidence 验证（SHA-256 哈希 + Ed25519 签名）
- [x] 锚点集成（LangGraph, MCP, OpenClaw, Cordum）
- [x] 可注入的密钥解析 + 热路径修复 (v0.7)
- [x] 信任加固 + attestation 对象草案 (v0.7.5)
- [x] 规范化规范 (PIC Canonical JSON v1) + 参考实现 (v0.8.0)
- [x] 初始一致性测试套件（规范化 + 核心模式）及 CI 运行器 (v0.8.0)
- [ ] 跨实现的一致性（TypeScript/Go 验证器对等性）
- [ ] 规范性语义（MUST/SHOULD 规范文档）
- [ ] OpenAPI 规范 + 保护硬化（结构化审计日志、请求关联）
- [ ] TypeScript 本地验证器（第二个独立实现）
标签：AI安全, AI智能体, Chat Copilot, CISA项目, LLM代理安全, Python, Streamlit, 合约验证, 大模型安全, 工具调用安全, 开源标准, 意图验证, 提示注入防护, 无后门, 本地优先协议, 溯源合约, 知识图谱, 系统防护, 访问控制, 越权防护, 逆向工具, 防幻觉, 防注入攻击, 高影响操作拦截