Skip to main content
Glama
claim-reconciliation-agent

claim-reconciliation-agent

claim-reconciliation-agent

AI + MCP + Skill 的 ToB 内部效率产品:把「平台账单 → 企业 OA 回款拆分」这条纯人工财务认领链路,做成只读核验 + 可解释候选生成的自动化工具。

6 角色多 Agent 协作 | 文件单写者锁 | 全链路零写操作安全边界

tests boundary python


它解决什么问题

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

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

产品边界(硬约束):不保存账号密码,不自动登录,不绕过验证码,不自动导入 OA,不执行财务核销。全程 write_actions=0。

Related MCP server: maxed-mcp

一真源 + 看板机制

  • 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 零写操作

快速开始

# 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

Available Tools

5 tools
check_oa_readonly_readinessC

判断人工登录后的三项只读检查;全部通过才创建本次任务编号。

Inputs: bill_readable (required), left_login_page (required), connection_healthy (required), bank_flow_accessible (required). Returns: object

confirm_oa_flow_numbersC

生成列表查重校验号;不打开详情,发现冲突就暂停。

Inputs: rows (required), historical_keys. Returns: object

generate_claim_templateA

生成可导入 OA 的本地模板副本。

消费编排传入的结构化候选(每条含完整 32 位 hex 流水号、公司、账户、单位名称、责任人、认领状态),复用阶段一模板生成能力写出本地 XLS。完整流水号缺失或截断即结构化暂停;不连接/读取/写入/上传/导入真实 OA,不自行计算或回显完整流水号,不覆盖内置源模板。

Inputs: rows (required), output_path (required), source_template (required). Returns: object

open_greencloud_oa_commandB

返回让浏览器操作能力打开固定 OA 登录页的指令。

Inputs: no named parameters. Returns: object

startup_statusC

返回两个准备项,并说明是否可以开始只读检测。

Inputs: bill_readable (required), oa_window_opened (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 5 tools

    Disambiguation4/5

    The five tools target distinct workflow steps: opening OA login, startup readiness summary, post-login read-only checks, duplicate verification, and local template generation. Startup_status and check_oa_readonly_readiness both relate to readiness and could cause minor confusion about ordering, but descriptions clarify their different phases.

    Naming Consistency4/5

    Four tools follow a clear verb_noun snake_case pattern (open_..., confirm_..., check_..., generate_...). startup_status is noun_noun and lacks a verb, which is a minor deviation but still readable and consistent in casing.

    Tool Count5/5

    Five tools is well-scoped for a narrow claim-preparation workflow. Each tool covers a distinct preparation or validation step without redundancy, and the set is neither bloated nor thin.

    Completeness3/5

    The tools cover OA login, readiness checks, duplicate validation, and template generation, but there is no tool to perform actual claim matching, read OA claim data, or update/submit reconciliation results. These are notable gaps for a claim-reconciliation domain, though the agent explicitly avoids real OA writes.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Read-only MCP server for reconciling SimpleFIN bank data against Firefly III ledger, enabling audit and review workflows without mutation.
      19
      14 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server providing deterministic accounting tools for AI agents, including bank statement parsing, document classification, money math, and webhook verification.
      2
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      MCP server for deterministic numeric verification and spreadsheet auditing. Enables AI agents to verify math/finance claims, audit rows, and evaluate covenant rules with signed, independently checkable receipts.
      4
      MIT
    • F
      license
      B
      quality
      D
      maintenance
      A secure, read-only MCP server that enables AI assistants to inspect transactions, vendor performance, wallet balances, and analytics through validated REST API calls.
      19
      -