# claim-reconciliation-agent

> **AI + MCP + Skill 的 ToB 内部效率产品**：把「平台账单 → 企业 OA 回款拆分」这条纯人工财务认领链路，做成只读核验 + 可解释候选生成的自动化工具。
>
> 6 角色多 Agent 协作 ｜ 文件单写者锁 ｜ 全链路零写操作安全边界

[![tests](https://img.shields.io/badge/tests-synthetic_fixtures_only-informational)]() [![boundary](https://img.shields.io/badge/write_actions-0-blue)]() [![python](https://img.shields.io/badge/python-3.11%2B-informational)]()

---

## 它解决什么问题

平台按账期给商家打款，财务需要把「一笔到账流水」拆分到多个商家/酒店，再在 OA 里逐行认领。人工做这件事的痛点：流水号要从 OA 页面逐条抄、金额要按商家拆分对账、合同责任人要逐个查、抄错一个号就导入失败。

本项目的做法：**本地 MCP Server（只读）+ 编排 Skill**——用户人工登录 OA 并导出账单后，系统只读采集合同与银行流水、按商家精确拆分金额、生成可解释的认领候选，最后填入固定 13 列模板供人工复核导入。

**产品边界（硬约束）**：不保存账号密码，不自动登录，不绕过验证码，不自动导入 OA，不执行财务核销。全程 `write_actions=0`。

## 一真源 + 看板机制

- `collaboration 台账` 思想落地的「一真源」原则：同一份数据只允许一个权威出处，其余全部是脚本自动生成的派生物——**手改派生物会被单测拦下**。
- `scripts/build_dashboard.py` 解析台账生成 `state.json` + 看板页；`serve_dashboard.py` 本机起一个小站（3 秒轮询刷新）；`watch_dashboard.py` 纯标准库守护自动重建。
- 看板含每个阶段的 owner、verifier、phase、next_action（演示图见 `docs/preview.html`，数据为脱敏重绘的演示数据）。

## 6 角色多 Agent 协作 + 单写者锁

`AGENTS.md` 治理 6 个角色：产品规划 / 项目经理 / 产品开发 / QA / Debug / 发布运营，每个角色绑定专属 Skill（grill-me、to-spec、implement、code-review、debug-agent 等）。

协作纪律踩过的坑，做成了机器可检查的机制：

- **文件单写者锁**（`scripts/agent_file_lock.py`）：改共享文件前必须抢锁，抢不到必须 PAUSE，**不许硬破别人的锁**；30 分钟过期自动释放，PM 是唯一仲裁者。缘起是实测两个 Agent 并发改写同一文件导致提交覆盖。
- **验收闭环**：开发完成只能提交 REVIEW、不得自验；失败走 QA → Debug → QA 独立回归；失败/非唯一统一返回 `PAUSED`，**永不出 `PASS`**。

## 零写边界与门禁

- MCP 工具白名单只有 4 个只读能力（状态检查 / 就绪检测 / 流水号证据 / 模板生成到本地），禁登录、禁上传、禁导入、禁核销。
- 结构化阻塞协议 `TASK_BLOCKED`：失败/非唯一时返回 `run_id` + `blocker_fingerprint` + 证据摘要 + 允许动作，从最近安全阶段恢复。
- 浏览器授权弹窗从「每步一次」压缩到「全程一次」（一次性授权 + 会话复用 + 闲置回收）。
- 生成侧门禁：酒店代码逐行稽核（错/空即非 0 退出）、模板缺号硬门禁、来源门禁（见下）。

## 反事故案例：8 个伪造流水号

一次交付中，交叉取证发现 8 个流水号是**伪造**的——与实际抽样交集为空、账期错位。处置：落地来源门禁脚本（`scripts/verify_flow_provenance.py`），把已交付物全部标记为不可用并撤回，之后每一笔流水号都必须带可回溯的来源证据。

这件事沉淀成一条原则：**数据运营里，口径错误的代价远大于效率损失。**

**量化口径**（均为项目真实记录）：

- 单账期逐日对账 **diff = 0.0**
- 变异测试 **18/18 全捕获**（验证门禁真的有效，不是摆设）
- 交付治理 **Issue DONE 24/31（≈77%）**
- 累计 **48 张**已导入领款表（脱敏统计口径）
- 浏览器授权弹窗「每步一次 → 全程一次」
- **write_actions = 0** 零写操作

## 快速开始

```bash
# 1) 安装依赖（Python 3.11+）
pip install -e .
pip install pytest

# 2) 跑测试（仓库内全部为合成假数据，无任何真实业务数据）
set PYTHONPATH=src        # Windows
export PYTHONPATH=src     # macOS / Linux
pytest

# 3) 从模板复制运行时配置（流水号留空即可体验解析路径）
cp scripts/_flow_numbers.json.template outputs/_flow_numbers.json

# 4) 重建看板（解析台账 → state.json + HTML）
python scripts/build_dashboard.py
```

仓库内的 `data/claiming_store.db`、`outputs/_flow_numbers.json`、`平台账单/*.xlsx` 均为**合成演示数据**（纯假酒店/假商家/假金额），可安全运行。

## 仓库导航

| 路径 | 内容 |
|---|---|
| `src/claim_reconciliation_agent/` | MCP Server 本体（合同读取、流水证据、模板生成、存储） |
| `workbuddy-skill/payment-claiming/` | 编排入口 Skill（SKILL.md + 运行时契约） |
| `scripts/` | 门禁、看板、单写者锁、模板生成等 26 个工具脚本 |
| `tests/` | 合成 fixture 支撑的完整测试套件 |
| `docs/` | 产品规格、技术设计、各环节 SOP |
| `AGENTS.md` | 6 角色协作协议与锁协议 |

## 免责与脱敏声明

- 本仓库是内部项目的**脱敏发布副本**：真实公司名、酒店名、商家名、人名、流水号、金额、账期一律未随仓发布；仓库内出现的示例数据全部为合成假数据。
- 原始台账、真实领款表与运行数据库仅保留在本地，永不推送。
- 已知债务如实登记：原内部仓的 xlutils 兼容问题在本副本中通过重建模板与合成 fixture 解决；依赖真实 OA 页面快照的回归测试以合成 fixture 等价覆盖。
- 本项目与任何平台/企业无隶属关系；模板格式仅用于演示「回款拆分」这一通用财务场景。

## License

MIT