Skip to main content
Glama

AgentProof Phase 0 / MVP 骨架

对应《Agent 交付质检工具产品规划文档》:9.2 Phase 0(协议 + 骨架)与 9.3 Phase 1 的前半(MVP 三工具)。 当前版本 0.1.0:schema_check / format_check / qc_report 可用,其余四个工具按 V1/V2 排期、返回明确的"未实现"而不是假装通过。

agentproof-phase0/
├─ agentproof/                 Python 包
│  ├─ server.py                MCP 适配层(兼容 mcp 2.x MCPServer 与 1.x FastMCP)
│  ├─ dispatch.py              工具注册表 + 每次调用后校验输出是否符合 Schema
│  ├─ store.py                 本地结果档案(~/.agentproof/runs/*.json)
│  ├─ checks/
│  │  ├─ schema_check.py       结构校验(JSON/JSONL/CSV、主键、空答案、表格形状)
│  │  ├─ format_check.py       格式校验(命名/层级/占位符/空章节/编号)
│  │  ├─ qc_report.py          双格式报告(JSON + Markdown,支持 run_ids)
│  │  └─ stubs.py              V1/V2 工具占位,如实返回 error
│  ├─ artifact.py              内容加载:内联文本 / 本地文件 / docx→文本(按 body 顺序)
│  ├─ jsonvalidate.py          JSON Schema 子集校验器(计数断言,供 pass_rate 用)
│  ├─ schemas.py               协议 Schema 注册表 + 内联 schema 的本地 $ref 解析
│  ├─ issues.py / report.py    问题构造、信封组装、verdict 判定
│  ├─ rules.py                 profile 与默认规则参数
│  ├─ cli.py                   本地 CLI(无 MCP 也能跑)
│  ├─ schemas/*.json           16 个协议 Schema(包内,随 wheel 分发)
│  └─ templates/               内置校验模板(competition_submission)
├─ tests/
│  ├─ run_tests.py             16 个用例,无 pytest 依赖
│  └─ mcp_smoke.py             真起 stdio server,验证握手 / 工具列表 / 两次调用
├─ tools/
│  ├─ qc_gate.py               流水线闸门:跑一组检查,失败则退出码 1
│  └─ build_schemas.py / build_examples.py / validate.py
├─ gates/competition-example.json   闸门配置示例
├─ samples/                    故意做坏的样例 + demo-report.md
├─ examples/                   15 个协议示例实例
├─ protocol-v0.1.md            接口协议(含设计决策与待决项)
└─ market-signals-verification.md  第三章市场信号核实报告

快速开始(不需要 MCP 宿主)

$py = "C:\Users\ZERO\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\python\python.exe"
cd agentproof-phase0

& $py -m agentproof list                  # 列出工具与阶段
& $py -m agentproof demo                  # 跑一遍样例,输出 Markdown 报告
& $py -m agentproof runs                  # 列出本地结果档案
& $py -m agentproof call format_check --args args.json
& $py tests\run_tests.py                  # 16 passed
& $py tools\qc_gate.py --config gates\competition-example.json   # 流水线闸门

单次调用示例(args.json):

{
  "artifact": {
    "content_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "path": "C:\\Users\\ZERO\\Desktop\\某交付物.docx"
  },
  "profile": "business_delivery"
}

Related MCP server: golden-flow-mcp

接进 Agent(TeleAgent / 任意 MCP 宿主)

服务端是标准 MCP stdio server。宿主配置形如:

{
  "mcpServers": {
    "agentproof": {
      "command": "<python.exe 绝对路径>",
      "args": ["-m", "agentproof.server"],
      "env": { "PYTHONPATH": "<本目录绝对路径>" }
    }
  }
}

需要 mcp SDK:pip install mcp(2.x 用 MCPServer,1.x 自动回落到 FastMCP)。

已验证:tests/mcp_smoke.py 真起 stdio server,握手成功、列出 7 个工具、schema_check 与 format_check 各调用一次并校验结构化返回(mcp 2.3.0 / Python 3.15)。

接进 Agent 之后的推荐用法

交付物 → schema_check(结构)→ format_check(格式)→ Agent 按 issues[].fix 修复
      → 复检 → qc_report(汇总,给人看的 Markdown)

verdict=error 时不要改交付物——那是工具没跑完。fix.kind=manual 表示这条只能人改。

设计要点

  • 一个共享信封:七工具输出都 allOf report_envelope,所以 qc_report 能吃任何工具的结果,零适配。

  • 每次调用后自校验:dispatch.call() 会把输出与 *.output.json 比对,不符就挂 protocol_warnings——协议不会悄悄漂移。

  • 入参封闭、出参开放:入参打错字立刻失败;出参加字段不破坏旧 Agent。

  • info 不影响 verdict:否则每次交付都是黄色,两周后用户就学会无视 warn。

  • 截断可见:summary.truncated 为真时统计值仍是全量。

  • 工具故障 ≠ 交付物缺陷:error 与 fail 分离。

当前状态

项

状态

16 个协议 Schema + 15 个示例

通过(tools/validate.py)

16 个行为/契约用例

通过(tests/run_tests.py)

MCP stdio 握手

通过(tests/mcp_smoke.py,mcp 2.3.0)

MVP 三工具

可用

本地结果档案 + run_ids

可用(~/.agentproof/runs/)

真实文档 dogfooding

本产品规划文档(1.17 万字 docx):183 项检查全过,0 误报

真实竞赛 dogfooding

知乎表格赛 2026(309 + 39 题):抓到 5 类真实问题,误报 5→0

流水线闸门

tools/qc_gate.py,退出码 0/1/2

FastMCP / MCPServer 骨架

已写,握手已验证;TeleAgent 注册待人工在 App 内完成

badcase 库

V1

link_check / cross_verify / regression_check

V1,占位返回 error

consistency_check

V2,占位返回 error

CI

docs/ci.yml 是现成的 GitHub Actions 配置(Ubuntu/Windows × Python 3.11/3.12 跑协议校验与用例,另有一个 MCP 握手 job)。 它没有直接放在 .github/workflows/:当前 gh token 缺少 workflow 作用域,GitHub 会拒绝推送该路径。启用方式:

New-Item -ItemType Directory -Force .github\workflows
Copy-Item docs\ci.yml .github\workflows\ci.yml
# 或者先 gh auth refresh -s workflow 再移动

已知边界

  • CSV 以字符串读入,类型断言会按字符串判定(已给出 protocol_warnings 提示)。

  • YAML 需 pyyaml,当前未启用。

  • 内联 schema 只解析本地 #/... 引用,外部 $ref 明确报错而非静默跳过。

  • format_check 只认 Markdown 标题与 docx 的 Heading 样式;Word 里手工加粗当标题的写法识别不到。

Related MCP Connectors

Related MCP Servers