ArtifactDiff

面向人类与 AI 代理的合同变更验证门禁。

在文档交付之前，证明 AI 代理仅修改了你授权的 Office/PDF 合同条款——无论是语义、视觉还是密码学层面。

ArtifactDiff 以本地优先、离线运行为设计原则。它将诸如“将付款窗口从 30 天改为 45 天”的请求编辑转化为冻结的策略，验证候选文档，并生成不可变的 Review Bundle，供人类和代理共同检查。

项目状态：0.1.0 alpha。合同安全核心与签名 Golden Path 已实现，并覆盖超过 900 项自动化测试。打包与公开发布自动化仍在进行中。

它能捕获什么

ArtifactDiff 刻意采用失败即关闭的策略。审查默认保持阻塞，且 FAIL 发现无法被批准绕过。

Related MCP server: Proof Layer MCP

三分钟 Golden Path

前提条件：Python 3.11+ 以及本仓库的本地检出。演示仅使用合成合同，依赖安装后不发起任何网络请求。

python -m venv .venv
# Activate .venv using your shell, then:
python -m pip install -e ".[dev]"
python scripts/run_contract_golden_path.py --output build/contract-golden-path
python -m json.tool build/contract-golden-path/summary.json

运行将生成三个独立验证、Ed25519 签名的 Review Bundle：

authorized    raw=pass    effective=pass
review        raw=review  effective=review
unauthorized  raw=fail    effective=fail

review 案例保持阻塞。要演示带显式模拟合成人类审查者的签名事件链转换，请使用不同的输出目录：

python scripts/run_contract_golden_path.py --output build/contract-golden-path-approved --approve-review

--approve-review 仅用于演示。真实批准仍是通过 artifactdiff review 或 artifactdiff approve 进行的交互式人类操作；代理无法批准自己的发现。有关生成的文件和隐私边界，请参阅 Golden Path 演练。

工作流程

Human instruction
      │
      ▼
contract-safe policy ── freeze + optional Ed25519 authorization
      │
      ▼
controlled agent edit session
      │
      ▼
semantic rules + protected entities + visual envelope
      │
      ├── PASS ───────────────────────────────► deliver
      ├── REVIEW ─► signed per-finding review ─► deliver or reject
      └── FAIL ───────────────────────────────► reject
                          │
                          ▼
                 immutable Review Bundle

Review Bundle 是系统记录。本地审查台只是该 bundle 之上的经过身份验证的回环接口。

人类与自动化接口

相同的应用边界驱动所有接口：

• CLI： 创建/验证/密封策略、打开受控会话、验证变更、检查发现、批准发现，以及验证或打包 bundle。

• 本地审查台： 检查 bundle 并一次签署一个发现，而无需将合同或私钥发送到浏览器 JavaScript。

• MCP： 为 AI 代理提供受限的检查/草拟/验证/本地验证工具，具有独立的输入和输出根，且不具备批准或验证签名能力。

• 离线 HTML： 与已验证事实关联的可移植人类审查报告。

artifactdiff --help
artifactdiff policy --help
artifactdiff verify --help
artifactdiff review path/to/review-bundle

对于 MCP 主机，在启动 stdio 服务器之前，请配置以路径分隔符分隔的绝对根目录：

ARTIFACTDIFF_MCP_INPUT_ROOTS=/absolute/contracts
ARTIFACTDIFF_MCP_OUTPUT_ROOTS=/absolute/artifactdiff-output
artifactdiff-mcp

MCP 有意无法批准发现或执行验证签名。

为什么这不是另一个 PDF 差异工具

安全与隐私模型

• 本地优先且离线；无需账户或云服务。

• contract-safe 默认启用，且无隐式授权。

• 精确的预期编辑绑定到其条款和出现位置。

• 各方、金额、货币、日期、持续时间、百分比、页眉、页脚、签名、印章和附件默认受保护。

• 离线 Ed25519 是核心信任机制；企业身份可通过适配器后续添加。

• 证据默认 minimal；full 为显式，sealed 为对指定接收者加密。

• MCP 响应受限，不返回完整合同、页面图像或密钥材料。

阅读已批准的 验证门禁设计 和 Plan 4.5 验收记录 以了解完整的信任与判定模型。

当前格式支持

• PDF → PDF

• DOCX → DOCX

• DOCX → PDF

• 英文、中文及双语合同结构

• 可选通过 LibreOffice 渲染 DOCX；PDF 渲染为本地进行

开发

python -m pip install -e ".[dev]"
python -m pytest -q

仓库目前包含单元、集成、篡改、CLI、MCP、审查台、跨格式以及签名 Golden Path 验收覆盖。

后续里程碑

• 可复现的公开合成语料库和零误通过门禁

• 用于二进制文档拉取请求审查的 GitHub Action

• 演示媒体和可下载的示例 Review Bundle

• 模式、威胁模型、SBOM、来源和签名 alpha 发布

• 面向企业解析器、渲染器、签名、加密和存储的插件边界

ArtifactDiff 围绕一个狭窄的承诺构建：当代理编辑合同时，你可以精确证明它被允许更改的内容——以及它没有更改其他任何内容。