Day 4：CLI 打通企业系统，Agent 通过命令行连接启衡 ERP

Day 4 关键词：CLI 封装、deskclaw 工具、ERP 真实读写、幂等写回、Mock 降级赛道：启衡精密・AI 财务提效 POC

Day 4 交付总览

Day 3 结束时，系统还跑在 200 条 CSV 模拟数据上。今天课程后我才理解，原来我做是传统方式，CLI 才是进阶的目标。Day 4 的核心任务：让 Agent 通过 CLI 打通企业 ERP 系统，用 deskclaw 命令行工具封装 ERP 接口，实现读取待审单据、执行 AI 预审、将审核意见写回 ERP 的完整闭环。

今日交付物清单：

一、今天解决了什么问题

问题描述

Day 3 的 erp_client.py 存在两个严重问题：

1. API 路径完全不匹配：代码写的是 /v1/expense-reports，但真实 ERP 的路由是 /v1/expense-claims。从未连上过真实系统。

2. 导入但从未调用：app.py 第 25 行 from erp_client import ERPClient，但整个应用没有任何地方实际使用这个客户端。200 条报销数据全部来自 CSV。

这意味着系统一直在 "假装" 连了 ERP。

Day 4 做了什么

二、真实 ERP 数据长什么样

BX-005693・沈文玲・昆山出差

总金额 ¥2,041，审批链只有 1 步（SUBMIT）。

AI 引擎应该检出两个问题：

1. L3 发票抬头错误："机械" vs "制造"（R4 发票抬头检查）

2. 金额 ≥ 2,000 但只有 SUBMIT，缺部门负责人审批（R3 审批链完整性）

这就是真实数据的价值：CSV 模拟数据里，这些业务问题是随机生成的。真实 ERP 里的每一个问题都有业务背景 ——"启衡精密机械有限公司" 可能是供应商曾经用过的旧名称，或者供应商开错了抬头。

审批链数据来自独立端点

ERP 的报销单详情不包含审批链。审批记录在 /v1/approvals 独立表中，通过 refId 关联。这个发现让我们调整了 get_claim_detail() 的实现：先拉详情，再拉审批链，合并返回。

发票嵌套在费用行内

真实 ERP 没有独立的 /invoices 端点。每条费用行 lines[].invoice 内嵌完整的发票信息（抬头、税号、金额、税率、附件）。我们写了 _extract_invoices() 把嵌套结构展平为引擎需要的格式。

三、API Key 权限的坑

第一把钥匙打不开所有的门

第一次创建的 API Key（qh_live_fde4day4000000000000000001）标注了 expense:write scope，但实际上：

学习要点：Scope 命名容易误解。expense:write 是修改报销单本身（如改金额、改状态），而 expense:review 才是提交审核意见。这种权限分离本身就是安全设计 —— 即使 AI 系统被入侵，也无法修改单据金额或强制审批通过。

创建全权限 Key

重新创建了 AK-FDE-DAY4-FULL Key，包含 7 个 scope：

复制["expense:read", "expense:review", "approval:read",  "master-data:read", "master-data:write", "invoice:read", "attachment:read"]

注意：故意不申请expense:write（改单据）、approval:write（执行审批）、payment:*（付款）。这是四条红线的技术落地。

四、幂等：同一个问题不要写两遍

问题

ERP 的 POST /review 端点每次都创建新记录。如果批量审核运行两次，同一张单据就会有两条一模一样的审核意见。运行十次就有十条。

我们的方案

ERP 服务端不支持幂等，所以在客户端做：

复制cache_key = f"{claim_id}:{input_hash}"if cache_key in self._write_cache:    return {"action": "SKIPPED"}  # 内容没变，跳过# POST to ERP...self._write_cache [cache_key] = review_id

input_hash 是单据 ID + 关键字段（金额、问题数）的 MD5。内容变化时 hash 变化 → 重新写入。内容不变 → 跳过。

验证

生产环境的改进方向

POC 阶段用内存缓存，重启后丢失。生产环境应该：

1. 在 ERP 服务端实现基于 ruleVersion + inputHash 的唯一约束

2. 或在 reviews 表增加 input_hash 列，INSERT 前 SELECT 检查

五、接入方式选择：为什么选 CLI

Day 4 课程讲的三种接入方式 ——CLI、API、MCP—— 我们最终选了 CLI 作为 POC 阶段的接入方式，底层复用 REST API。

MCP 更适合 Phase 2：当 Agent 需要自主发现 ERP 能力（"看看 ERP 还能做什么"）时，MCP 的 list_tools 动态发现机制更有优势。但 POC 阶段，CLI 的 --help 已经够用。

deskclaw CLI 工具

用 Click 封装 erp_client.py，暴露 5 个命令：

复制deskclaw status                          # 连接状态deskclaw expense list [--limit N]        # 拉取待审列表deskclaw expense detail <id>             # 单据详情deskclaw expense review <id> --result REVIEW --summary "..." --issue "..."deskclaw expense batch-review [--limit N] # 批量审核

Agent 通过 Shell 调用 CLI，CLI 调用 ERPClient，ERPClient 调用 ERP API。三层分离，各司其职。

六、关键代码结构

erp_client.py v2 的设计

复制class ERPClient:    # 初始化：尝试连接 ERP → 失败则 Mock    def __init__(self, base_url, api_key): ...    # 读取流（4 个方法）    def list_pending_claims (self): ...      # GET 列表    def get_claim_detail (self, id): ...     # GET 详情 + 合并审批链    def get_approvals (self, id): ...        # GET 审批链    def get_fee_standards (self): ...        # GET 差旅标准    # 写回流（1 个方法，含幂等）    def write_review (self, id, result, ...): ...    # 格式适配（独立函数）    def adapt_claim_for_engine (detail): ... # ERP 格式 → 引擎格式

适配层做了什么

ERP 返回 employeeName、jobLevel、expenseType（camelCase + 英文枚举）。引擎期望 employee_name、job_level、category（snake_case + 中文）。adapt_claim_for_engine() 做了一层翻译：

复制{    "employeeName": "沈文玲",      → "employee_name": "沈文玲",    "jobLevel": "STAFF",          → "job_level": "STAFF",    "lines [].expenseType": "HOTEL" → "expense_lines [].category": "住宿",    "trip.city": "昆山",           → "destination": "昆山",    "trip.startOn / endOn": "..."   → "trip_days": 2,}

这层适配的意义：引擎不关心数据来自 ERP 还是 CSV 还是 API。只要输入格式统一，规则检查结果就一致。这让引擎可以在 Mock 和真实数据之间无缝切换。

七、当前进度

ERP 对接状态：真实 API 读取 + 审核意见写回 + Mock 降级 + 幂等机制，全部验证通过。

下一步（Day 5 硬目标）

1. 用真实 ERP 数据跑一轮 Evals：把 Round 1 的测试集换成真实单据，看 Recall / Precision 是否依然达标

2. 用加权公式重算综合准确度：补算规则命中率 (0.5) 和状态正确率 (0.3)

3. 跑 RULE_ONLY vs DUAL 双模式对比

4. UI 打磨 + Demo 预演

Day 4 感悟

1. "假装连了" 比 "没连" 更危险

from erp_client import ERPClient 这行代码在 app.py 里躺了三天。如果不走到真实 ERP 面前，你永远不会发现 API 路径不对、字段名不对、scope 不够、审批链在另一个端点。代码能跑通和系统能交付之间，隔着真实数据这一整面墙。

2. 权限分离本身就是安全声明

expense:write 和 expense:review 是不同的 scope。这意味着即使我们的 API Key 被泄露，攻击者也无法修改报销单金额或强制审批。好的系统设计让 "做不到坏事" 成为默认状态，而不是依赖使用者的自律。

3. 幂等不是 ERP 的责任

ERP 的 POST /review 每次都创建新记录 —— 这是合理的服务端设计（无状态、可审计）。幂等是调用方的责任。如果你的 Agent 重复运行后产生了 100 条重复审核意见，问题不在 ERP，而在你没有做客户端幂等。

FDE 共学营 Day 4 打卡赛道：启衡精密・AI 财务提效 POC今日交付：deskclaw CLI 工具（Click 封装）+ 五层架构数据流图 + 系统接入说明 + 真实 ERP 运行证据今日感悟：CLI 的自描述能力（--help）让 Agent 能自主发现系统能力，这是 CLI 相比 API 的核心优势。