RevGuard 是面向企业渠道佣金等高风险资金业务的多 Agent 治理控制面：确定性金额内核、审批参数承诺、执行引用监视器、真人审批门禁、Executor / Verifier 分离、写结果未知后的权威查询与恢复，全部证据链可审计、可复算、可复现。
架构原则一句话：确定性控制面与 LLM 语义面强制切分——金额、政策版本、权限与状态迁移全部由确定性代码决定，模型只负责理解、检索、解释与协作。
渠道等级在合同期内升级、政策版本跨季切换、回款与订单时点交错——人工核对慢、口径不一致，多付收不回、少付引纠纷，而事后冲销一旦写错账，代价成倍放大。
代理商等级以订单创建时点还是回款时点为准？政策版本按哪个时间生效？口径不清即错付。
ERP 内观察佣金与政策应得佣金不一致时，缺少可复算、可审计的自动对账与调整机制。
写错账不能"再试一次"：重复提交、盲目重试、伪装成功都会扩大资金风险，必须可控恢复。
两个案件使用不同订单（EZ202608001 / EZ202608008）、不同任务、不同审批与 Trace，不共享任何运行记录。
从 ERPNext 真实取证 → 按订单时点匹配政策版本 → Decimal 确定性复算佣金 32,400.00 KES → 真人批准 → 范围受限的能力令牌执行 → 独立复核 → 终态 CLOSED / PASSED。
受控写入发生 1 KES 偏差 → 独立验证失败 → 系统禁止盲目重试，冻结通道并查询权威账务 → 按原操作 ID 创建关联反向冲销 → 恢复后净影响归零 → 终态 ROLLED_BACK / PASSED。
金额、政策选择、状态迁移全部由确定性代码（Decimal + 显式状态机）决定，模型只负责调查与解释，不碰数字。
批准时对规范化参数求 SHA-256，摘要同时落审批单与能力令牌；执行前重新计算并三方比对，金额或组件额度被改动即拒绝写入。
没有实际读取过订单、合同与佣金台账，就不允许执行；资金分录携带事实引用与折叠锚点，第三方可用同一份回执复核依据。
L2 级调整必须真人批准，身份绑定 Matrix 用户与事件；执行使用范围受限、短时、一次性的能力令牌，超范围即拒绝。
Executor 写入后由独立 Verifier 重新查询权威账务核对，读取偏差与真实错记分别处置，不允许自证成功。
写入结果未知时冻结自动重试、按原操作 ID 查询权威状态，已提交补齐结果、未提交在隔离旧执行者后继续，绝不新建伪装成功的运行。
10 个职能 Agent 在 AgentTeams（Matrix 房间）中按阶段交接任务，每步携带上一步任务 ID、证据摘要、产物哈希与案件版本；资金效果经过真人审批门禁后继续执行。
模型调用受预算约束（每阶段最大调用次数、Token 上限、超时与终态清理），金额与权限由确定性代码决定。
ERPNext v16（Token 鉴权 REST、分页、超时、错误语义）；AgentTeams / Matrix 真实任务与事件；PostgreSQL 资金写入与审计链；Higress 网关 + Prometheus / Grafana / OTel / Tempo / Loki 可观测栈。
ERPNext 不可用时生成 Evidence Gap 并进入人工处理，从不静默回退 Mock——一条运行记录里不混合真假来源。
| 证据分级 | 含义 | 本项目对应 |
|---|---|---|
| LIVE_SYSTEM | 真实运行系统产生的单据与回执 | ERPNext 单据、API 回执、审批事件、PostgreSQL 账务 |
| PUBLIC_REAL | 公开真实数据 | Olist 巴西电商真实交易（10,000 笔抽样） |
| SYNTHETIC_DOMAIN | 合成业务规则 | 佣金政策、渠道等级、合同与案件原因 |
| SYSTEM_GENERATED | 系统自身产物 | 执行分录、审计哈希链、Trace、恢复记录 |
Docker 隔离验证套件：287 项默认执行 + 83 项 PostgreSQL/Matrix 集成用例（带 DSN 全绿），覆盖率门禁 90%。
8 个合成 Golden Case 全量回放，金额与状态基线逐项比对，双案例 GOLDEN_MATCH。
Olist 实验确定性抽样（seed 202609），源档案 SHA-256 与规则哈希入清单，10 类异常 × 80 例。
数据库故障后按原操作 ID 恢复、旧 Worker 隔离、迟到回调拒绝、净影响归零。
审计事件 append-only 哈希链，部署前后案件 / 执行 / 审计快照一致性校验。
全新 Compose 项目从零部署并运行 Golden Case，附 SBOM、依赖锁定与镜像摘要。
仓库提供源码、Adapter SDK、JSON Schema、Golden Case、部署指南、CONTRIBUTING 与 SECURITY 流程；企业接入只需实现 Provider 接口并注册。
# 一键清洁部署（Docker Compose） git clone https://github.com/ld0574/revguard.git cd revguard && cp config/erpnext.env.example config/erpnext.env docker compose -f docker-compose.yml up -d bash scripts/verify_docker.sh # 完整发布门禁 python3 scripts/run_case_e2e.py CASE-2026-0001 # 真实链路回放
| 扩展点 | 说明 | 状态 |
|---|---|---|
| ERPNext Provider | Frappe REST 只读适配，契约测试覆盖鉴权 / 超时 / 分页 / 缺字段 / 不可用 | 已验收 |
| 金蝶 / 用友 / SAP | 统一配置 Schema、对象映射清单、契约测试入口与骨架 | NOT_VALIDATED |
迁移分三层：直接复用领域无关的治理骨架、替换 Adapter 对接外部系统、重写领域规则 适配业务口径。下表为迁移示意，不等于“零成本支持”；现有业务运行证据属于渠道佣金合成案例。
| 行业 / 场景 | 直接复用 | 替换 Adapter | 重写领域规则 |
|---|---|---|---|
| 渠道佣金争议（现有运行证据） | StageTask、审批、能力令牌、幂等、Trace/Audit、执行/验证分离 | CRM、合同、政策、财务接口 | 佣金组件、政策时点、L0–L3 阈值 |
| 保险理赔复核 | ＋证据缺口与人工升级 | 保单、理赔、查勘、支付接口 | 责任范围、免赔额、赔付公式、反欺诈阈值 |
| 供应商对账 | ＋版本匹配与差异解释 | 采购、收货、发票、付款接口 | 三单匹配、税额/账期、容差规则 |
| 电商售后退款 | ＋一次性写能力与回滚验证 | 订单、物流、支付、库存接口 | 退款资格、折损、运费与时效规则 |
| SaaS 计费申诉 | ＋确定性金额内核 | 订阅、用量、定价、账单接口 | 计量窗口、阶梯价格、Credit 规则 |
| 员工费用报销 | ＋Principal/RBAC 与审批链 | HR、差旅、发票、支付接口 | 费用标准、城市等级、票据与税务规则 |
16 个 Skill 的迁移分层（直接复用 / 主要替换 Adapter / 必须重写领域规则）见 docs/industry-migration.md。
主视频（4:04，真实运行栈逐帧录制）与 90 秒故障备用片段（偏差、冲销与恢复复核）。两条轨道都来自 2026-09-18 的真实运行代次 REC-36B14AC3 / REC-63A0C9EC，无音轨、旁白待后期；成片时间轴为展示加速，真实墙钟与逐帧时间戳见证据目录。
12 页：概览 / 问题 / 两个案例 / 架构 / 多 Agent / 确定性计算 / 真人审批与参数承诺 / Case1 / Case8 / 真实系统 / 成果与边界 / 开源与迁移。
RevGuard 将企业渠道佣金结算中的多 Agent 协作与资金安全约束结合：调查、政策匹配与根因解释交给 Agent；金额计算、状态迁移与资金执行由确定性内核完成；L2 调整需真人批准并以能力令牌受控执行，批准参数以摘要承诺锁定；没有实际读取过的事实不得作为执行依据；独立复核失败或结果未知时，系统冻结重试、按原操作 ID 恢复，全程生成可验证审计证据。
RevGuard is a multi-agent control plane for high-stakes money movement such as channel commissions. Agents investigate, explain and collaborate; a deterministic kernel computes amounts and enforces the state machine; L2 adjustments require human approval and scoped, one-time capability tokens whose parameters are committed as a canonical digest; execution references must point at facts actually read; an independent verifier re-checks authoritative state, and unknown outcomes freeze retries and recover by original operation ID — with a verifiable audit trail throughout.