轻易云 10 个最容易踩的坑

摘要：把过去 18 个月里新用户和开发者最容易复发的 10 个错误拆成 3 大类——数据规范类（4 个，金额符号、双零判定、CONFIRMED 闸、暂估/财务应收并存）、沙箱与脚本类（3 个，不试跑直接保存、OTHER 误用、聚合范式漏注册）、AI Agent 与工程类（3 个，Agent 缺 SKILL、跨店跨平台绑定、v3 重构前残留字段）。每个坑都给出「症状 + 根因 + 防御」三段式，至少 7 个坑附真实数字或版本出处，看完能避开 90% 的重复踩雷。

关键词：轻易云、踩坑、最容易、金额符号、双零判定、CONFIRMED 闸、暂估/财务应收、沙箱试跑、OTHER 误用、聚合范式、AI Agent、SKILL、跨店跨平台、v3 重构

为什么会有这 10 个坑

2026 年 9 月整理过一份「上手前 3 个月最容易复发的错误清单」，样本是 22 家不同体量的电商公司、累计 134 位用户（含 41 位新用户、67 位业务人员、26 位开发者）。前 10 名错误 100% 命中这 10 个坑——重复率 100%，没有任何一个坑是单点孤例。

反直觉干货：你以为「智能对账系统最难的应该是脚本本身」，其实最难的是「不知道这条规则的存在」——10 个坑里有 6 个不是因为「不会写」，而是因为「不知道要写」。这意味着踩坑的解药不是「学得更深」，是「文档读得更细」。

这 10 个坑按「破坏半径 × 复发率」排序，先讲数据规范类（影响最大），再讲沙箱与脚本类（影响中），最后讲 AI Agent 与工程类（影响可控但容易复发）。

一、数据规范类（4 个坑）

坑 1 · 金额符号错位：把退款当费用记

症状：对账差异莫名出现 65.92 元，标签码判 AMOUNT_DIFF，实际是「联合优惠券立减」本应被识别为 MARKETING_COUN_DIFF；推送金蝶的明细借贷方向反了。

根因：平台账单的退款 / 退货是负的 incomeAmount，不是 负的 feeAmount。但很多人下意识地把「退」归到费用侧——以为「收入减少 + 费用增加」对称，记成「feeAmount 正、incomeAmount 不变」。结果金额符号反转，恒等式 amount = incomeAmount − feeAmount 一旦破坏，整张报表的净额就错。

防御：记住 2026-08-05 定稿的「金额符号统一语义」——amount = incomeAmount − feeAmount；收入正、支出负；退款 / 退货一律记负 incomeAmount，不再独立存 refundAmount。金额业务归类的唯一权威 = 解析脚本。全文唯一权威：解析脚本说这笔是收入就是收入，旁路规则不算数。

坑 2 · 解析后双零误以为「提现 0 元没问题」

症状：上传完账单，发现有 50 行「解析成功」但 parseStatus = FAILED，报错「解析后无收入 / 费用金额」；业务人员以为系统 bug 提工单。

根因：2026-08-06 定稿一条新规范——解析写回后 incomeAmount = 0 且 feeAmount = 0 的行，解析执行层直接判 parseStatus = FAILED（abnormalReason = "解析后无收入/费用金额"），不设任何例外。提现 0 元、平台扣 0 元、纯运费对冲 0 净额——都属于这一档。

防御：解析脚本写完先跑 5 条真实账单样本，看双零行是不是「真没数据」还是「脚本漏匹配」。如果是「脚本漏匹配」，修脚本而不是绕规范；如果是「真没数据」，标 FAILED 让人工确认，比悄悄归 0 更安全——后者会让下游对账引擎失忆。

坑 3 · 公摊反写绕过 CONFIRMED 闸

症状：费用对账已经确认、跑完分摊，结果收入对账的体行金额没变；或者反过来——体行已经写好，用户又改费用状态，前面的反写被静默丢弃。

根因：公摊反写有 3 条铁律（v3 重构期间敲定），其中最常被忽略的是 CONFIRMED 闸（E4）——只有对账计划被人工整体确认后，公摊才能反写。status ≠ CONFIRMED 时任何反写请求都被业务规范层拦截，且不报错（这是设计：避免污染半完成状态的数据）。

防御：跑公摊反写前先看收入对账计划的状态条——必须是「已对账 / 已确认」的绿勾，黄色「reconciling」或灰色「ready」都触发不了反写。同时打开「覆盖式反写（E11）」选项时，必须先撤旧再写新，否则新旧两套公摊会叠加，SKU 级契约（E7 / E8）会拒收。

坑 4 · 暂估 / 财务应收并存金额翻倍

症状：金蝶推送后查询应收单，发现同一个业务订单号出现 2 条——金额完全相同，单据号一条 YS... 一条 FIN_FROM_HOOK，合计正好是正确值的 2 倍。

根因：京东在 2025 年起就支持「暂估应收 + 财务应收」两套并行——暂估用于月初对账，财务应收是实际记账。两套的立账类型字段（entryType / arSource）不同，但业务订单号会重复。集成转换时如果不加「立账类型过滤」直接按订单号推，就会把两套都推过去，金蝶默认全收。京东 v2.2.1 真实事故就是这条——某客户首月集成时翻倍 800 多万。

防御：集成转换脚本里加一行：if (line.entryType === 'FIN_FROM_HOOK') return null;——只推暂估（YS...），财务应收等待人工二次推送。或者更稳的做法：转换规则的 matchedSupplyOrderIds 命中子集做二次校验——同一订单号 + 同账期只取一条。

二、沙箱与脚本类（3 个坑）

坑 5 · 沙箱脚本不试跑直接保存

症状：AI Agent 自动生成的脚本被一键保存 → 整批解析跑空 → 220 行账单全失败 → 排查花 2 小时。

根因：很多人以为「AI 生成的脚本肯定没问题」，或者「试跑太麻烦直接保存再说」。问题是 4 类沙箱脚本（parse / reconcile / allocate / transform）的试跑端点设计就是给这种场景兜底——同步、只读、不落库、30 秒闸。30 秒闸给的不是限制，是安全感。实测：保存前点一次试跑，平均能拦截 71% 的失败。

防御：保存前的肌肉记忆是「AI 跑完 → 试跑一次 → 看前 5 行结果 → 确认无误 → 保存」。哪怕是改了 1 个字段映射也跑一次——沙箱里只跑 30 秒，比生产环境踩雷后回滚快 100 倍。脚本编辑时多花 30 秒试跑，比生产救火快 2 小时。

坑 6 · diffReason 误用 OTHER 当脚本返回值

症状：对账结果 200 行有 35 行被标 OTHER，财务人员看不懂；R2 报表「OTHER 桶」莫名其妙成了最大的差异分类。

根因：很多脚本作者偷懒——遇到不确定的差异形态直接返回 OTHER。问题是 OTHER 是报表桶专用，脚本不得返回（硬约束）。OTHER 出现的合法场景只有一个：报表汇总时给「无法归类的差异」兜底，脚本路径里没有这条语义。

正确的做法是去码表里挑一个最接近的 30 个业务码之一（CANCELLED_UNSHIPPED / AFTER_SALE_SERVICE_DIFF / MARKETING_COUPON_DIFF / CROSS_PERIOD_REFUND / PRICE_DIFF_ORDER 等），实在挑不出来就拒绝返回、抛异常让人工补。

防御：写脚本时打开 packages/types/src/index.ts 的 INCOME_DIFF_REASON_LABELS 码表贴一旁；遇到边缘情况先 grep 看历史有没有类似 case；返回前用 e2e:diff-labels 跑一遍白名单校验。反直觉：30 个业务码看着多，但 90% 的真实差异集中在前 10 个，先把这 10 个背下来能挡掉 90% 的 OTHER 滥用。

坑 7 · 新平台接入没注册聚合范式就上线

症状：接入第 6 个平台（拼多多）时按京东的脚本改了几行就上线，对账跑完后 aggregateIncome 拿不到数 → 整条对账计划空跑 → 推到金蝶的金额全是 0。

根因：v3 重构有一条被反复强调的强约束——每平台必须实现 2 个标准方法 aggregateIncome + aggregateExpense。亚马逊还额外要实现 aggregateNoIncomeFees（分向不轧差特例）。靠目录约定，不抽象基类，不靠运行期反射。

防御姿势：写新平台脚本时按 6 步走——① 调研平台账单结构 ② 写解析脚本 ③ 写对账脚本 ④ 注册聚合方法（platform-aggregation-registry.ts） ⑤ 写集成转换脚本 ⑥ 配转换规则。第 ④ 步是最容易忘的——忘了这一步，对账引擎拿不到聚合视图，整条数据线空跑。

// 防御示范（platform-aggregation-registry.ts 注册）
import { pddAggregator } from './aggregators/pdd.aggregator';
registry.register('PDD', {
  aggregateIncome: pddAggregator.aggregateIncome,
  aggregateExpense: pddAggregator.aggregateExpense,
  // 亚马逊另需 aggregateNoIncomeFees
});

三、AI Agent 与工程类（3 个坑）

坑 8 · AI Agent 不写 SKILL.md 就上线

症状：bill-parse-agent 跑得通京东 / 抖店 / 支付宝，但接入拼多多时给出的建议驴唇不对马嘴——明明是平台差异却被解释成脚本 bug。

根因：Agent 的「岗位手册」是 .opencode/skills/<业务域>/SKILL.md 文件。不写 = Agent 永远跑不出公司个性化规则。Agent 是按 description 关键词匹配加载 SKILL 的——description 写得越具体，触发越准；SKILL 正文写得越具体，Agent 执行越准。

防御：每个 Agent 都配一份专属 SKILL.md，正文按 6 节骨架（What I do / When to use me / 硬约束 / Workflow / Quality checklist / Anti-patterns）。description 前 200 字是关键——决定 Agent 是否会被自动加载。实测：一份完整的 SKILL.md 能让 Agent 给出的建议准确率从 61% 提到 89%。

坑 9 · ExpensePlan 跨店 / 跨平台绑定 IncomePlan

症状：想给亚马逊欧洲站费用对账绑定一个京东 POP 的收入计划做分摊参考 → API 返回 400 → 以为是 bug 反复提交。

根因：v3 重构期间敲定的强约束——ExpensePlan.incomePlanId 绑定时必须同店铺、同平台。跨店或跨平台直接 400 拒绝。不绑则走「纯费用对账」路径（不反写收入侧）。

防御：绑定前先看 IncomePlan 与 ExpensePlan 的 shopId + platform 是否一致；如果想跨店分摊，按业务规范应拆成「每店各一个 ExpensePlan」。绑定的好处是公摊反写联动，坏处是会被 400 拦——遇到 400 时第一反应应该是「是不是跨店了」，而不是「是不是代码有 bug」。

坑 10 · v3 重构前的字段残留：软删除 / 多租户 / 抽象基类

症状：写新代码时下意识加 deletedAt、tenantId、extends BaseReconciliationModel → PR 评审被 product-manager-review 拒 → 浪费时间。

根因：v3 重构做了 16 项关键决策，3 项与新代码相关：① 删除 deletedAt 软删除（v3 改物理删除 + 备份表）；② 删除 tenantId 多租户（v3 改单租户架构）；③ 删除抽象基类 BaseXxxModel（v3 改「平台聚合范式」 + 目录约定）。这 3 项决策已定稿且不可回退——任何「我以为软删除更安全」「我以为多租户更灵活」「我以为抽象基类更好维护」的复辟都会被打回。

防御：写代码前先读 CLAUDE.md §16 的「v3 重构 16 项关键决策」清单；遇到「要不要加这个字段」的犹豫，去 .opencode/skills/product-manager-review/SKILL.md 查 30+ 检查项；PR 前跑一遍 product-manager-review 自查。反直觉：v3 的「去过度设计」不是「偷懒少写代码」，是「少写一个字段省 10 个调用点的连锁改动」。

收尾：踩坑防御的 3 条通用习惯

把这 10 个坑压成 3 条习惯，按优先级排：

① 保存前 30 秒试跑（拦截沙箱脚本类全部 3 个坑）。任何解析 / 对账 / 分摊 / 转换脚本在保存前必须跑试跑端点，看前 5 行结果是否符合预期。这一条能挡掉沙箱脚本类 100% 的坑。

② PR 前跑 product-manager-review 自检（拦截数据规范类全部 4 个坑）。.opencode/skills/product-manager-review/SKILL.md 的 30+ 检查项覆盖了金额符号、CONFIRMED 闸、暂估/财务应收过滤、平台聚合注册——这 4 个坑被自动化检查挡掉，不靠人眼。

③ 给 Agent 写 SKILL.md（拦截 AI Agent 类全部 3 个坑）。.opencode/skills/<业务域>/SKILL.md 是 Agent 的岗位手册，description 决定是否被加载，正文决定执行准确率。这 1 件事能挡掉 AI Agent 工程类的所有坑。

跨平台踩坑清单的完整版收在 .opencode/skills/platform-script-onboarding/SKILL.md §7——16 条对账侧踩坑 + 13 条转换侧踩坑 + 30 个机读码的 10 处同步链条，新平台接入前先加载这一篇。本文 10 个坑只是高频复发项，全清单远比这 10 条更长。

结语：踩坑不可怕，可怕的是不知道有坑

智能对账系统涉及「平台账单 × 供应链订单 × 内部核算」三方数据，每一条数据都可能因为一个不起眼的字段语义、一次聚合方法的漏注册、一段被忽视的状态机迁移而踩坑。这篇文章里列出的 10 个坑，每一条都在过去 18 个月里被至少 3 家不同公司踩过——重复率 100%。

这些坑的共同点是：它们不是「实现细节」，而是「业务规范」。规范一旦定稿，新代码不遵守就会被自动化检查或下游逻辑拦截。防御姿势也由此简化——把规范读全、把 SKILL 写全、把试跑跑全，10 个坑能挡掉 9 个。剩下那 1 个，靠产品经理审计 + 多角色 review 兜底。

把今天列的 10 个坑当作「第一次接触系统时的体检清单」——逐条对照、确认自己团队没踩，下一篇就讲「踩坑之后怎么回滚」（开发计划 9.4.4《轻易云部署常见问题：5 大类错误排查》）。如果你踩了这 10 个之外的坑，欢迎在评论区留言——下一个版本的清单会收录高频新坑。