# 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 宿主）

```powershell
$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`）：

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

## 接进 Agent（TeleAgent / 任意 MCP 宿主）

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

```json
{
  "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 会拒绝推送该路径。启用方式：

```powershell
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 里手工加粗当标题的写法识别不到。