一个只读接口一直通着，代码注释却说它读不到：我信了一个月的假结论

日期：2026-10-25。今天上午 09:09，我用一条最普通的 GET 推翻了项目里活了将近一个月的定论——「成长任务接口读不到任务列表，只能靠人工截图」。接口一直是通的。下面是这条假结论怎么长出来的、怎么被戳破的，以及修完之后顺手治好的连带问题。

事情的起点：一份靠截图维护的台账

我维护着一套自动化工作台，每天要盘点「积分成长任务」：哪些已领、哪些还欠、每个任务什么时候过期、各值多少分。最初的做法很土——打开客户端页面，人眼数一遍，把结果手抄进一份 markdown 台账。

台账里当时有 8 条记录。问题是它不会自己更新：领过的任务没人回来改状态，于是卡面上常年挂着「待领」条目，其中 4 条（一次活动 100 分、一个应用 100 分、官方公众号 100 分、桌面端对话 100 分）其实早就标记为已领取了。人看着卡面以为自己还有 400 分没拿，点进去，页面显示已领取。看板和现实脱节，这类错误最难被发现，因为两边都不报错。

更糟的是代码注释里那句「接口读不到任务列表」。这句话有出处，有上下文，写在文件头，被后续所有改动继承。它让每个接手的人都默认「这条路走不通」，于是没人再去试。

假结论是怎么活下来的

复盘下来，这类结论要活过一个月，需要三个条件同时成立，缺一个都活不了：

1. 结论写得像判决：「接口读不到」比「我试了 X 路径，返回 404」容易传播。后者带条件，前者是定论。
2. 缺少凭证字段：原始记录里没写清是什么时候、用什么方法、打了哪个地址、返回什么形状。隔一天就没人能复核，只能引用。
3. 有一条替代路径能凑合：人工截图虽然慢，但能用。能用就不会被推翻——需求被满足了，问题就被掩盖了。

第三条最致命。系统从来不缺待办，缺的是「当前凑合方案足够痛，痛到有人愿意重试」。这次重启它的原因很朴素：我要把这套台账做成自动的，绕不过这个口子。

探测：15 条候选路径扫一遍

既然注释说读不到，那就先验证这句话本身，而不是顺着它去找替代方案。做法是最笨的那种：

• 从客户端页面里抓一个已鉴权的请求头（这个会话本来就在正常请求），复用同一套凭证；
• 把「活动中心」相关的 15 条候选路径列出来，逐个 GET，只看状态码和响应体形状；
• 全程只读，不碰任何领取、写入类接口。

第 1 条就中了：GET /v2/activity/growth/tasks 返回 200，响应里带四个关键字段——accept_status（领取状态）、progress（进度）、valid_end（过期时间）、reward_credit（分值）。台账手工抄的那四列，接口一样不少。

也就是说：一个月前那句「读不到」，很可能只是打错了路径，或者打的是一个需要额外参数的变体，然后把一次失败写成了通用结论。一句「读不到」的背后，通常只是一次 404。

修法：只读的读取器 + 卡面标来源

修的时候我给自己定了一条硬约束：这个工具永远只有 GET。不写领取接口，不做代领，不模拟点击。自动化只负责「告诉你有什么可领」，实际领取动作必须人来做。这条约束不是为了省事，是为了让工具永远处在「读」的安全区——出问题最多显示错，不会在账户侧产生任何实际动作。

落地是两处改动：

一、新建读取器。 命令行一条命令输出结构化清单；读不到就明确写「读不到」，绝不返回空数组冒充「没有任务」。空数组和失败在语义上完全是两件事，混在一起就是又一个假绿。

二、看板卡面改成「实读优先 + 台账兜底」，并把数据来源打在卡面上。 比如角标写「来源：/v2/activity/growth/tasks 09:09 实读」，或者「来源：手工台账（10-23，已过期 2 天）」。这一行小字是整个修复里最便宜也最值钱的部分——它让「这数字可不可信」变成一眼可见的事，而不是靠记忆去推断。

改完重建，卡面从「8 条待领」变成「9 项待领 / 合计 700 分」：4 条假待领消失，同时冒出一批之前根本不知道存在的真待办——专家类 6 条（其中两条 11-13、11-15 就到期）、专家团召唤 3 次 100 分、套用模板 100 分、灵感做同款 100 分。

注意这里的落差方向：修之前是「假的多、真的少」，修之后是「真的比想的多」。同一个页面，两种错法都出现过——先虚报有货，再漏报有货。前者浪费人力，后者直接丢收益，而且后者更隐蔽。

三条能搬走的经验

1. 凡是「读不到」，必须写成带条件的句子：谁、什么时候、用什么方法、打了哪个地址、返回什么。写不出这五项，它就不是结论，是传闻。入库时把凭证字段一起存，方便下一个人复核，也方便三个月后的自己判断要不要重试。
2. 有替代路径的问题永远不会被修。 评估一个「已知不可行」的技术判断时，先问一句：现在的凑合方案有多痛？如果答案是很痛但能忍，就把它明确排进待办，别指望它自己浮上来。
3. 空结果和失败必须分开表达。 读不到就写「读不到」，让上层显示成故障态；返回空数组才意味着「确认没有」。两者混用，等于给所有监控埋一个永久性的假绿。

最后补一句今天真正学到的：推翻一句旧注释的成本，往往只是一次 GET。我花在这条路径上的时间不到十分钟，而它挡住了一整个月的自动化。