ClawTeams 里的运营数据对不上——是 Agent 读错了表还是同步延迟？

ClawTeams 里 Agent 报出的销量、库存跟后台对不上，先别急着改取数代码。常见原因就两类：一是数据还没同步完，Agent 读到的还是上一批快照；二是两边口径不一致，比如 Agent 取的是“已支付金额”，后台看的是“下单金额”。这两类问题的处理方向完全不同，所以第一步不是修，而是把两组数字固定到同一个时间点，让它们具备可比性，再决定往哪条路查。

先固定时间点，把两边数字写成一条可回看的记录，再比对数据源的更新时间和 Agent 的读取时间戳。间隔小于一个完整同步周期，通常属于正常延迟，等下一轮同步复测即可；间隔明显超出周期，才算真正的同步问题。时间戳对得上但数字仍然不一致，就转到字段映射核对，重点排查已支付金额与下单金额、可售库存与总库存这类近似字段。两步走完仍有差额，再把它固化成对账检查项。

固定一个时间点，同时记录后台与 Agent 侧的数字

对账顺序建议按下面的步骤走，每一步都要留下可验证的记录，不要跳过第一步直接去看取数配置或 SQL。

步骤	动作	取数入口	判定结果
1	固定时间点，两边各记一行数字	后台报表页 / Agent 对话返回	两组数字可比
2	比对源更新时间与读取时间戳	数据表 updated_at / Agent 日志中的 fetched_at	间隔超出周期则为延迟
3	核对字段映射与口径	Agent 配置 / 取数 SQL / 视图定义	确认是否同一口径指标
4	同一时间点重跑一次	重跑命令 / 手动触发	差异消失或可解释
5	写成对账检查项	巡检脚本或监控任务	下次提前发现

记录时至少写清四件事：记录时间点（精确到分钟即可）、指标名、数值、取数入口。同一条记录要标明是谁取的——后台报表还是 Agent 返回，避免事后回看时分不清来源。两边取数时间错开是最常见的坑：先看后台、再问 Agent，中间隔了几分钟，期间有新订单进来，数字天然对不上，这时得出的差额没有任何意义。

时间点: YYYY-MM-DD HH:MM
指标: 当日已支付销售额
后台侧: 数值 X，入口=报表页/销售日报
Agent 侧: 数值 Y，入口=对话提问“今天卖了多少钱”
备注: 两次取数间隔约 40 秒

比对数据源更新时间与 Agent 读取时间

第二步只做一件事：找出数据源的最近更新时间，再找出 Agent 这次读取的时间戳，两者相减就是这批数据的新鲜度。常见的数据源时间字段有 updated_at、modified_at、etl_batch_time、sync_time 或日期分区字段；Agent 侧的时间戳一般在返回体的 meta 里，例如 fetched_at、read_at、query_time，也可能只落在日志中，需要先确认它到底取的是哪一层的时间。

ClawTeams 里的运营数据对不上——是 Agent 读错了表还是同步延迟？

-- 通用骨架，表名与字段名按实际环境替换；以下是 MySQL 语法
SELECT
  MAX(updated_at) AS source_updated_at,
  NOW()           AS queried_at,
  TIMESTAMPDIFF(SECOND, MAX(updated_at), NOW()) AS lag_seconds
FROM orders
WHERE updated_at >= CURDATE();

如果算出的间隔小于一个完整同步周期，通常属于正常延迟，等下一轮同步后再复测；如果连续多轮都明显超过同步周期且数值一直不动，就应该去看同步任务的调度状态和日志，而不是继续在 Agent 侧找原因。同步周期本身要去配置里确认，是分钟级任务还是小时级任务，判定阈值按这个周期来定，不要凭感觉设一个固定秒数。还要注意更新时间为空的情况：有的表只在有变更时更新，空值不代表没有数据，需要结合批次表或分区信息确认。

核对字段映射，确认取的是同一口径指标

时间戳对得上、数字还是不一致，问题基本落在字段口径上。这时候要把 Agent 的取数定义和后台报表的统计口径逐项摆在一起看。

后台字段名	Agent 侧字段名	口径说明	易混淆点
order_amount	sales_amount	下单金额 vs 已支付金额	是否包含未支付、已退款订单
paid_amount	gmv	实付金额	是否扣退款、是否含运费
stock_qty	available_stock	总库存 vs 可售库存	是否扣减锁定库存与在途库存
created_at	pay_time	下单时间 vs 支付时间	跨天订单归属日期不同
order_count	paid_order_count	订单数统计口径	是否拆分或合并子订单

表中字段名是通用示例，实际以你环境里的配置为准。核对顺序是：先看 Agent 的取数定义（SQL、视图或指标配置），再对后台报表的统计口径，最后确认两边的时间过滤条件是否一致——同样是“今天”，一边按创建时间过滤，一边按支付时间过滤，跨天时就会差出一截。

用同一时间点的数据重跑一次

重跑的目的不是让数字变小，而是验证差异是否只由取数时间错开造成。做法是固定同一个时间窗口和同一组过滤条件，两边各取一次，再比较结果。

# 通用接入骨架，按实际接口、命令与参数替换
START=YYYY-MM-DD_HH:MM
END=YYYY-MM-DD_HH:MM

# 1. Agent 侧重跑，显式指定时间窗口与时间字段
clawteam agent query \
  `--metric` paid_sales_amount \
  `--from` $START `--to` $END \
  `--time-field` pay_time \
  `--json`

# 2. 后台侧导出同一窗口数据
#    报表页选择相同的起止时间与统计口径后导出

观察三样东西：数值本身、返回 meta 里的读取时间戳、以及两边的记录条数。判定差异消失的条件是：同一时间窗口、同一统计口径、同一时间字段下，两边数值一致；或者差额能对应到可解释的部分，例如未支付订单、已退款订单、尚未同步的批次。如果差额仍然是随机的、无法归因的量，说明不只是时间错开的问题，需要回到字段映射那一节继续查。

把对不上的情况写成对账检查项

把这次的排查结论固化成检查项，下一次同类问题就能在用户反馈之前被发现。检查项至少包含指标、频率、判定阈值、发现不符后的处理顺序四列。

指标	频率	判定阈值	发现不符后的处理顺序
当日已支付销售额	每小时	超出常规波动范围，或连续两轮数值不变	先看源更新时间 → 再看 Agent 读取时间戳 → 最后核字段口径
可售库存	每小时	与后台差值持续不收敛	确认库存口径 → 确认锁定与在途是否计入
订单数	每日	跨天统计口径不一致	对齐时间字段 → 对齐子订单拆分规则
同步任务状态	每轮同步	超过一个同步周期未成功	查调度日志 → 补跑 → 复测并记录

阈值不要照搬别人的数字，按自己环境的同步周期和业务波动来定；一时定不下来，就先连续记录几轮正常值，再取一个能覆盖正常波动的区间。