一个月从零到生产：我做了一套对接巨量引擎的千川 AI 投流系统，这些坑都是真金白银换来的

1. 追投接口的实测契约——平台的回显不能照抄进创建请求#

素材追投走 uni_promotion/ad/control_task/create/。这个接口我前后失败了 21 次才拼出完整契约（台账里 21 次创建失败全是参数问题）：

• 预算：必须是 100 的整数倍，且不超过原计划预算的 50%（2026-09-24 实测定论，前端校验文案里就写着这两条）。
• duration（控成本追投）：任务回显里 duration 是 87672（约十年，等于「长期有效」），但你创建时传 87672 会被 schema 拒（“must be most 24”），传自定义值又被语义拒（「不支持自定义时长」）——正确做法是完全不传，平台自动落默认。放量追投才传 0.5~24 小时、0.5 步进。
• audience（定向人群）：回显是全 null 的完整对象，但创建时数组型键不接受 null（平台报 “Value is not nullable”）——正确做法是把值为 null 的键整个去掉，没设置定向就传空对象 {}。读取侧的形态不能照抄进写入侧，这是这次学到的最反直觉的一课。
• 400154 排查：平台只回笼统的 400154「请求参数设置错误」，不指名字段。我的办法是给每个写入请求落一份截断的请求体快照进台账，事后能对照；后来定位到一次 400154 的真实原因是把直播间画面素材 ID 塞进了 material_ids 却没带 material_type，平台按视频素材查这个 ID 查不到。画面追投要走独立的 room_material_id 字段，单一固定目标，不能和视频混投。
• SYSTEM_DISABLE 是常态：全域直播计划未开播时常驻「系统暂停」状态。早期我把它当「平台可能拒单」的预警条件，属于错误归因——修正参数后，同状态计划连续 12 次创建成功。所以现在只对真正的终态（已删除/已冻结/余额、预算下线）提示，常规暂停态不拦。
• 19 位 ID 精度：素材/任务/评论 ID 是 19 位整数，超出 JS 安全整数范围，Number() 一转末位就舍入——追投会打到另一个素材上。读路径在 JSON.parse 前对长整数做正则引号化保真；写路径用哨兵法：序列化时先包 @@id@@ 再正则还原成裸数字。

2. 直播大屏接口：fields 必填、时间必须带秒#

today_live/room/get 必须带 advertiser_id + aweme_id + date_time（北京日期），fields 是 JSON 数组查询参数；today_live/room/product_list/get 的 fields 同样必填且 productId 是驼峰；report/live/get 的 start_time/end_time 必须是 yyyy-MM-dd HH:mm:ss 带秒格式。少了 fields 或只传到日期位，接口直接报参数错误。这些是 10-03 拿线上凭证逐个直调核验后写进 oceanengine.mjs 注释的。

3. 考核 ROI 的口径是算出来的，不是读出来的#

页面上有好几个 ROI 字段，到底哪个和 roi2_goal 同口径？我用一个生产计划做了代数实证：平台返回考核 ROI 2.06，当日含券成交 4881、消耗 2367.49，4881 ÷ 2367.49 = 2.062，吻合；换实付口径算是 1.377，不吻合；stat_cost_for_overall_roi2 字段恒为 0，不可用。结论：考核 ROI = 含券 GMV ÷ stat_cost（对应平台字段 total_prepay_and_pay_order_roi2，分子用 total_pay_order_gmv_include_coupon_for_roi2）。这条口径后来直接写进了 AI 提示词和引擎数据门，是整个调价引擎的度量基石。

4. 评论归属：反查接口有上限，第 11 个抖音号被截掉了#

评价管理要做「每条评论归属到哪个授权抖音号」。平台评论接口 tools/comment/get 没有「视频归属抖音号」字段；aweme/video/get 和 tools/aweme_auth_list/ 实测都返回 40002「advertiser does not grant you permission」，此路不通。实测可用的路径是：tools/comment/get 的 filtering={"author_ids":[数字uid]} 支持按视频作者抖音 id 过滤，且账号间评论天然隔离——某账号能扫到的 item_id 就归属该账号。于是反查变成「逐授权号带 author_ids 扫评论建映射」。

两个细节坑：一是 author_ids 必须传数字 uid，超出 JS 安全整数范围的 uid 我宁可 422 拒绝（错误码 AWEME_ID_INVALID）也不能四舍五入后扫错账号——那等于把归属安到别人头上，是伪造数据；二是反查有预算上限，最初只扫前 10 个授权号，10-06 生产上授权号涨到 11 个，第 11 个号（某位主播）的评论归属恒为空，用户报「抖音号·本账号列全是空的」。根因就是这个 10 的上限把人截掉了。修复：上限放宽到 20、时间预算放宽到 20 秒、逐号 250ms 错峰。当晚生产真数据自验：20 个授权号、20/20 条评论全部归属成功。另外审计日志的实现是新记录 unshift 插在数组头，最新事件永远在第一位，和界面上「最新在前」的直觉一致。

5. OAuth token 自动刷新#

access_token 有效期 24 小时，不能让人每天重新授权。实现是 ensureAccessToken：过期前 5 分钟自动轮换；用 Promise 单飞防止并发请求同时刷；平台轮换 refresh_token 后立即把新 token 对落盘回 grants 文件，否则下次重启就丢刷新链；重启恢复时 accessToken 为空，按用过的 refresh_token 反查同一条授权补写。服务重启不掉线，这条在生产跑了三周没出过事。

6. 部署工程化：rsync 要护住 data/#

部署流程写在 DEPLOY_SERVER.md：本地 VITE_API_BASE=<生产域名> npm run build，前端产物先 rsync 到服务器 /tmp/dist-new/ 暂存，再 sudo rsync 进 nginx 静态目录并 chown www-data；后端只同步 server/ shared/，必须加 --exclude data/——server/data/ 里有线上真实授权凭证与快照，一次手滑同步就等于覆盖生产授权。动任何东西之前先做带校验和的全量备份（9-16 那次连数据文件记的是 MD5，9-22 那次是 SHA256SUMS，都留了恢复演练命令）。CORS 默认只放行 127.0.0.1:5173/4173 这几个开发端口，线上站点通过 ALLOWED_ORIGIN 显式指定。还有一个反直觉的点：systemd 服务不能设 NODE_ENV=production——代码里的租户熔断会在这种状态下把所有业务接口 503 掉，线上安全靠的是登录门禁 + 关闭自助注册，和本地同构。

7. AI 调价引擎：建议振荡与数据门#

这个单独立一节讲，因为它是整个系统最有意思的部分。

架构决策的来龙去脉#

最早的引擎是纯规则的：实际 ROI 高于目标就降标放量、低于目标就升标收紧，固定 15% 步长。跑起来发现规则引擎有个天花板——它只会看「偏差方向」，不会看「量级和节奏」。偏差 12% 和偏差 40% 用同一个步长，消耗在萎缩和消耗在爆发用同一个动作，这不叫调控，叫条件反射。

10-05 深夜我定下架构：规则只做约束，判断归 AI。规则层保留全部硬约束——目标上下限、单次幅度、15 分钟节流、每日 8 次上限、日累计幅度 40% 封顶、观察期、熔断；「加多少减多少」由 AI 每轮拿整场直播数据判断，输出 {action, suggestedRoiTarget, risk, note} 的严格 JSON。AI 的提议回来还要再过一遍服务端硬约束（clamp 到上下限、升标 ≤5%、降标 ≤20%，超限自动收敛不拒绝）。

配套的安全策略是：AI 欠费、超时或未配置时，不产出任何 RAISE/LOWER 建议——引擎的跳过计数器记 SKIP_AI_NOT_CONFIGURED，数据照读、审计照记、熔断保护（PAUSE_SUGGEST）照常，但宁可不动也不乱动。规则引擎的原始决策不再作为建议输出（启动时还会清理历史纯规则遗留建议）。唯一例外是熔断：连续烧钱零成交（自上次出单花费 ≥ 3 × 推导成交成本）时的暂停建议保留，因为这是保护性止血，不是调价判断。

数据门：修掉建议振荡#

AI 上线第一晚就暴露新问题：小样本窗口的 ROI 剧烈虚高——一个 15 分钟窗口只有 1 单、几块钱消耗，ROI 能飙到 15+，AI 一看「远超目标」就建议降标，下一个窗口数据回落又建议升标，两小时 5 次反转。

10-06 加了两道数据充分性硬约束（在 mergeAiAdvice 里，AI 提议也必须过）：

• 门 D1 累计死区：主口径改为「当日累计考核 ROI」（优先平台返回值），距目标偏差不足 ±10% 直接 HOLD——短窗口波动不构成调价理由；
• 门 D2 降标样本门：LOWER（降标放量）要求最近窗口成交 ≥3 单，样本不足不许降。

同时给 AI 的上下文做了两件事：一是所有比率引擎先算好，不让模型自己做除法（它会算错，而且不可复现）；二是口径写进字段名——当日累计_考核口径、前15分钟窗口_引擎估算、本场直播实时_大屏支付口径，提示词里明确「窗口成交单数 <3 时不得作为下调目标的依据」「大屏支付口径天然低于考核口径，仅作参照」。修完之后振荡消失，建议节奏稳定在「调一次→观察四个窗口→再评估」。

两个生产细节#

模型延迟：生产接的是火山方舟 doubao-seed 系列，默认开深度思考，一次判断 25 秒起步，超出引擎等待窗口。实测给请求体加 thinking:{type:"disabled"} 后 1~2 秒返回且质量不受影响——现在代码里对 doubao-seed 前缀的模型自动带这个参数。Key 存 ai-config.json（0600 权限，页面只回显掩码），页面保存即时生效不用重启。

误删事故与恢复：10-05 定架构那晚，我在重构引擎代码时误删了文件——好在编辑器的文件状态快照（readFileState）里存着被删文件的内容，从快照里把代码恢复了出来，损失了半小时而不是一晚上。这次之后我给「大改先全量备份」这条纪律又加了一层保险，也顺手把备份目录的恢复演练写成了文档。

交互形态#

绑定流程做成向导（账户→计划→参数），绑定后进入计划列表页（状态筛选 + 搜索 + 详情钻取），每个计划有独立详情页：建议卡显示当前目标/建议目标/目标区间/AI 判断与理由（AI 原提议和硬约束收敛后的采纳值不一致时会标注「已按上下限/幅度约束收敛」）。计划列表专门加了「实际 ROI」列，展示的就是第三节实证出来的考核口径，旁边才是出价目标 ROI——投手一眼能分清「跑出来的」和「设进去的」。