ProofFlow

ProofFlow

English | 简体中文

面向 AI 编码的 Agent 工作账本。

氛围编码很快，但盲目信任远远不够。

ProofFlow 让 AI 生成的工作可供审查、可追溯、可撤销：它会记录从工作约定到证明包的完整链路——先制定约定，记录算法决策，声明成本预算，快照代码状态，将主张与证据绑定，评估完成标准，然后导出可审计的数据包。

最新版本： v0.1.8 - 面向 AI 编码的 Agent 工作账本

▶ 观看 72 秒演示： 从 AI Agent 的主张到可验证的证明包

演示素材（延期）： 端到端的内部试用 Demo_Asset GIF，以及 v0.1.x 内部试用与渠道打磨里程碑中的 VSCode_Channel 内联审计 / Approve Gate 截图， 将推迟到下一个内部试用周期（本里程碑期间无法捕获 VS Code 窗口）。相关事项记录于 PLANS.md#vscode-channel-screenshots-deferred-from-v0-1-x-dogfood。

📦 证明包示例： 代码审查 · 问题分诊 · Agent 工作账本 · 账本内部试用

维护者工作流： docs/maintainer_evidence_workflow.md

Agent 工作账本指南： docs/agent_work_ledger.md

账本风险提示： docs/ledger_risk_hints.md

5 分钟 MCP 快速入门： docs/ledger_quickstart_mcp.md

账本 PR 评论模板： docs/examples/pr_comment_agent_work_ledger.md

AgentGuard 语义规则： docs/agentguard_semantic_rules.md

Agent 工作台账

ProofFlow 不只是 PR 审查助手。它是一个本地优先的 AI 编码工作台账。Ledger Case 会记录 Agent 修改代码之前、期间和之后的工作流：

1. 工作约定 - 记录目标、仓库路径、允许的范围、禁止的操作、必需的测试、完成标准、证据要求、算法要求和成本预算。
2. 算法决策 - 在实现之前记录选定的方法、理由、备选方案、不变量和禁止采用的方法。
3. 成本预算 - 在开始高成本工作之前，声明令牌、API、GPU、CPU、运行时间或迭代次数限制。
4. 快照 - 捕获 git diff、已更改的文件、HEAD SHA、基础引用和 diff 哈希，让审查者确切了解所检查的代码状态。
5. 证据 - 将命令输出、测试输出、差异、备注、屏幕截图或其他材料存储为可搜索的证据。
6. 声明 - 要求每条 Agent 声明都必须关联证据，才能获得信任。
7. 评估 - 确定性地检查必需的测试、算法决策、成本预算、范围边界、缺失证据、未接受的风险，以及针对可疑路线的非阻断性 Risk Hints。
8. 证明包 - 将约定、算法决策、成本预算、时间线、快照、声明、证据、评估、决策和剩余风险导出为 Markdown。

主链：工作约定 -> 算法决策 -> 成本预算 -> 快照 -> 证据 -> 声明 -> 评估 -> 证明包。这让核心产品不变量保持明确：没有 Case，就没有工作流；没有证据，就没有可信的声明；未评估完成标准，就不能悄然宣告成功。

Risk Hints 会扩展证据流程，但不会让 ProofFlow 变成自动算法评判工具。它们会在记录的路线可能有误或成本过高时提醒维护者，例如本应采用映射却进行了重新生成、预算超支元数据，或只能证明输出而不能证明方法的测试。

完整架构和评估模型请参阅 docs/agent_work_ledger.md，如需运行完整的 MCP 流程，请参阅 docs/ledger_quickstart_mcp.md。

ProofFlow 已通过审查

ProofFlow v0.1.6 已在一个真实的仓库 PR 中进行实测。GitHub Actions 工作流运行了 AgentGuard，发布了一条稳定的 PR 摘要评论，上传了 summary.json，并导出了可下载的 Proof Packet。

• 真实 PR： #94 Dogfood v0.1.6 CI 审查体验
• 审查运行：ProofFlow PR Review #25953071865
• 根据实测反馈发布的补丁版本：v0.1.6.1
• 结果：每次推送都会更新同一条稳定评论；一个构件包含 Proof Packet 和 summary.json；不会阻止合并。

问题

AI 编码 Agent（Claude Code、Codex、Copilot Workspace）可以修改文件、运行命令并自主做出决策。但目前没有标准方式来：

• 审计 Agent 做了什么以及原因
• 拦截 高风险操作，在执行前进行把关
• 证明 代码审查确实检查了其声称检查的内容
• 撤销 Agent 发起的更改，并确保操作可靠

ProofFlow 通过在 Agent 与文件系统之间运行来解决这个问题，创建证据图，将每项操作与其依据关联起来。

快速入门

Docker（推荐）

从刚克隆的仓库的上级目录运行。Push-Location / Pop-Location 配对使用，可确保运行 docker compose up 命令时工作目录位于 仓库根目录，并在代码块结束后恢复原目录，因此可以在单个 PowerShell 会话中安全地复制粘贴这段代码。

git clone https://github.com/Hyperion-GPU/ProofFlow-v0.1.git
Push-Location ProofFlow-v0.1
docker compose up
Pop-Location

后端：http://localhost:8787 | 前端：http://localhost:5173

默认情况下，Docker 会将两个端口都发布到 127.0.0.1，以保留 ProofFlow 的 localhost 信任边界。若要增强本地保护，请在启动前设置 API 密钥：

PROOFFLOW_API_KEY=change-me docker compose up

如果为 Docker 前端启用了后端身份验证，请在构建时使用相同的 PROOFFLOW_API_KEY 值，以便 Vite 能将 VITE_PROOFFLOW_API_KEY 嵌入静态前端包中。AgentGuard 默认禁用 test_command 执行；仅当你明确希望后端在审查期间运行本地测试命令时，才设置 PROOFFLOW_ENABLE_TEST_COMMANDS=true。

手动运行

在单个 PowerShell 会话中，从仓库根目录启动各个组件。 Push-Location / Pop-Location 可确保在后端和前端代码块之间工作目录保持可预测； 后端端口固定为 8787，以匹配 make dev-backend 的基准配置。npm run dev 是一个长期运行的进程——如果你希望在第一个会话中看到后端 uvicorn 进程，请在第二个 PowerShell 会话中运行前端代码块。

# Backend
Push-Location backend
pip install -r requirements.txt
python -m uvicorn proofflow.main:app --port 8787
Pop-Location

# Frontend (long-running; recommended in a second PowerShell session)
Push-Location frontend
npm ci
npm run dev
Pop-Location

MCP 集成（Claude Code / Codex）

pip install proofflow-mcp

添加到项目的 .mcp.json：

{
  "mcpServers": {
    "proofflow": {
      "command": "proofflow-mcp",
      "env": { "PROOFFLOW_BASE_URL": "http://127.0.0.1:8787" }
    }
  }
}

现在，AI Agent 可以维护 Agent 工作台账、扫描文件、审查代码、分流问题、建议操作并导出审计报告，同时受到强制安全门禁的保护。

Codex 维护者插件

ProofFlow 还提供了一个仓库本地的 Codex 插件，位于 plugins/proofflow-maintainer。它提供 入门提示词和一个面向维护者的技能，用于：

• 使用 ProofFlow 审查当前差异，
• 为 PR 创建 Proof Packet，
• 将问题文本分流为 ProofFlow Case，
• 为复杂编码任务维护 Agent 工作台账。

该插件使用相同的本地 proofflow-mcp 服务，并将后端信任边界设为 http://127.0.0.1:8787。 有关预期交接形式，请参阅公开安全的 Agent 工作台账 示例。

架构

AI Agent (Claude Code / Codex / Custom)
    |
    | MCP Protocol (stdio)
    v
ProofFlow MCP Server (23 tools)
    |
    | HTTP REST API
    v
ProofFlow Backend (FastAPI + SQLite)
    |
    |--- Agent Work Ledger: Contract > Algorithm > Budget > Snapshot > Evidence > Claim > Evaluation > Packet
    |--- Evidence Graph: Cases > Artifacts > Claims > Evidence
    |--- Action Pipeline: Preview > Approve > Execute > Undo
    |--- Policy Gates: Risk classification > Owner decision
    |--- Proof Packets: Exportable markdown audit reports
    v
Local Filesystem (scanned files, git repos)

核心功能

Agent 工作台账

将复杂的 AI 编码工作记录为一等 Case。主要流程为 Work Contract -> Algorithm Decision -> Cost Budget -> Snapshot -> Evidence -> Claim -> Evaluation -> Proof Packet，使维护者能够了解 Agent 的承诺、所选方案、 接受的成本限制、所做的更改、支撑其声明的证据、是否满足完成标准，以及哪些 Risk Hints 值得人工审查。

基于证据的代码审查（AgentGuard）

分析 git 差异，生成带风险评分的声明，并将每项声明关联到具体证据（更改的行、测试结果）。没有支持证据的声明不会存在。

文件审计与整理（LocalProof）

扫描目录，使用 SHA-256 哈希为文件建立索引，提取文本以支持全文搜索，并建议整理操作——所有操作都会记录在可审计的 Case 中。

问题分流

将问题文本作为一等 Case 保存，并附带来源 Artifact、确定性分流 Claims、组件推断、标签建议和 Proof Packet 导出功能。

策略门禁执行

高风险文件系统操作（移动到系统路径、批量操作）会自动暂停，并设为 pending_decision 状态。执行前需要所有者明确批准。

安全不变量

• 没有 Contract，就没有 Ledger - AI 编码工作从明确的范围和完成标准开始
• 没有 Algorithm Decision，就没有可信策略 - 重要方案必须在实施前记录
• 没有 Cost Budget，就没有高成本工作流 - 高成本操作需要先声明限制
• 没有最终 Snapshot，就不能 Finish - 已完成的 Ledger 必须证明经过审查的仓库状态
• 没有 Preview，就没有 Action — 破坏性操作需要两阶段确认
• 没有 Evidence，就没有 Claim — 每项断言都关联到可验证数据
• 没有 Ready Evaluation，就没有悄然成功 - 未通过的 Ledger 将以 finished_with_risks 状态结束
• 没有 Undo，就没有破坏性操作 — 已执行的操作会附带回滚元数据
• 没有 Case，就没有工作流 — 所有工作都在可审计的容器中跟踪

MCP 工具套件（23 个工具）

health · scan · suggest · review · triage_issue · start_work_contract · record_algorithm_decision · record_cost_budget · capture_snapshot · record_evidence · record_claim · evaluate_contract · finish_work_ledger · status · approve_execute · export_packet · search · list_cases · list_actions · undo · decide

explain_risk_hint 会为 Ledger Risk Hint 记录有证据支撑的 Decision， 但不会隐藏该提示。

技术栈

层	技术	测试
后端	Python 3.12、FastAPI、SQLite	311
前端	React 19、TypeScript、Vite	25
MCP 服务	Python、MCP SDK、httpx	44
CI	GitHub Actions（PR 审查 + 发布门禁）	审计产物 + PR 评论

安全功能

• 可选的 API 密钥身份验证（PROOFFLOW_API_KEY）
• 速率限制（PROOFFLOW_RATE_LIMIT）
• AgentGuard 测试命令执行为选择启用（PROOFFLOW_ENABLE_TEST_COMMANDS）
• MCP 并发保护（PROOFFLOW_MCP_MAX_CONCURRENT）
• 文件系统操作范围限制（allowed_roots）
• CORS 限定为 localhost 来源

项目状态

v0.1.0 — 稳定版本。 所有核心工作流均已实现、测试并编写文档。

里程碑	状态
核心证据图（Case/Artifact/Claim/Evidence）	已完成
LocalProof 文件审计工作流	已完成
AgentGuard 代码审查工作流	已完成
问题分类工作流	已完成
策略门禁实施	已完成
面向 Claude Code/Codex 的 MCP 服务	已完成
带安全预览的备份/恢复	已完成
Docker 部署	已完成
PyPI 软件包（proofflow-mcp）	已完成

路线图

• 多 Agent 协同（跨 Agent 共享 Cases）
• 用于语义证据检索的向量 RAG
• GitHub Actions 集成（由 CI 触发审查）
• VS Code 扩展（Marketplace）
• 面向团队工作流的云同步选项
• 策略门禁决策的 Webhook 通知

开发

在同一个 PowerShell 会话中，从仓库根目录运行。每个 Push-Location / Pop-Location 代码块都会将工作目录恢复到 仓库根目录，因此下面的 python scripts/... 冒烟测试和 scripts/demo_workflow.py 可以在同一个会话中粘贴执行。

# Run all tests
Push-Location backend
python -m pytest          # 311 tests
Pop-Location

Push-Location frontend
npm run test              # 29 tests
Pop-Location

Push-Location mcp-server
pip install -e ".[dev]"
python -m pytest          # 44 tests
Pop-Location

# End-to-end smoke test (cwd: repository root)
python scripts/mcp_smoke.py --cleanup
python scripts/ledger_mcp_smoke.py --cleanup
python scripts/ledger_risk_hints_smoke.py --cleanup
python scripts/ledger_risk_hints_dogfood_matrix.py --cleanup

# Demo workflow (cwd: repository root)
python scripts/demo_workflow.py

本地后端数据默认存放在 backend/data/。对于不应触及仓库本地状态的 dogfood 运行，请在启动后端前，将 PROOFFLOW_DB_PATH 和 PROOFFLOW_DATA_DIR 设置为临时目录。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

• 行为准则
• 安全策略

许可证

MIT

---

由 Hyperion-GPU 构建 — 让 AI Agent 工作流可审计、安全且可验证。