企业官网建设流程全解析

last30days Amazon 评论抽取预算修复实战：把富化车道从收尾阶段提前到检索时刻的完整实现解析

【免费下载链接】last30days-skillAI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary项目地址: https://gitcode.com/GitHub_Trending/la/last30days-skill

关联实现计划：docs/plans/2026-08-14-fix-amazon-review-budget-plan.md（2026-08-14，状态 Implemented）

导读

本文深入解析 last30days 技能中一次典型的多源研究引擎预算修复：在一次实测的 Bentgo 主题全源运行里，Amazon 评论富化车道因在管线收尾阶段才启动，只剩 11 秒"面包屑"预算，导致 3 次 Bright Data 拉取全部超时、积分被消耗却拿不到一条评论文本。修复方案没有采用看似合理的"把剩余预算垫高到下限"策略，而是从根上改变了评审富化的启动时机——在 Amazon 搜索返回后立刻并行拉起评论，并引入"低于有效下限即整条跳过"的预算语义与PARTIAL状态上报。读完本文，你将掌握这套可量化的墙钟预算公式、调度位点改造、降级状态契约，以及对应的回归测试设计。

一、问题现场：一次实测运行暴露的预算数学错误

该计划记录的问题来自 2026-08-14 的一次 Bentgo 主题运行，症状链路非常清晰：

1. 搜索阶段正常：多源全量运行里，Amazon 搜索列表正常返回（12 个产品，含星级与评分数量）；
2. 富化车道几乎空转：日志显示pulling up to 50 reviews for 3 products (budget 11s)，随后lane deadline 11s hit; dropped 3 straggling pull(s)；
3. 积分被白白烧掉：Bright Data 三次都以 11s 超时告终，零条评论文本返回，但信用点数照扣；
4. 对照实验证明问题不在拉取质量：单独只跑 Amazon 的重跑拿到了完整的 180s 预算，124s 内完成，评论正常落地。

根因被定位到预算计算公式（见 amazon.py 中的_remaining_lane_budget）：

remaining = FOREGROUND_CONTRACT - elapsed - RENDER_MARGIN

即评审车道的可用预算为min(LANE_DEADLINE=180, max(0, FOREGROUND_CONTRACT=300 - elapsed - RENDER_MARGIN=20))。问题在于富化排在所有其他源之后执行：当检索阶段累计耗掉约 269s 后才轮到 Amazon 富化时，300 - 269 - 20 = 11，预算只剩 11 秒——一个注定失败的数字。

二、为什么"下限垫高"的修法是错的

第一直觉是给公式加一个下限：max(120, leftover)。计划文档明确否决了这条路，理由非常硬核——它会杀死整份报告而非单单一个源：

• 若在 elapsed=269 时把预算垫高到 120s，本次运行总时长会涨到约 389–449 秒；
• 宿主（host）对 Bash 调用的前台合约是300 秒（见 SKILL.md 中约定的timeout 300000，即 300000ms = 5 分钟）；
• 超时会让整份研究简报失败，损失远大于丢失一个源的评论富化。

因此正确的判断是：这次实测失败的本质是评论车道何时启动，而不是拉取质量。既然 Amazon 单独运行时 124s 内就能完成全部拉取，那么在完整运行中，搜索早就返回了产品列表，评论却要干等所有其他源以及 Phase 2/2b 跑完，最后才拿到 11 秒。修复应当让富化尽早并行启动，而不是在收尾处与整个 300s 合约做无谓搏斗。

三、修复设计：五条原则

计划给出了五条互相咬合的构建原则：

1. 在搜索返回后立刻启动富化：enrich_with_reviews从收尾阶段挪进_retrieve_stream的 Amazon 分支内，与其他源的 future 并行执行；传入真实的elapsed = time.monotonic() - run_started（把run_started线程化传入 retrieve）。30–90s 的搜索结束后，剩余预算为 190–250s，再钳制到 180s；Amazon 单独运行时行为保持不变。
2. finalize 只做"缺失才补"：_finalize_items_by_source保持仅当top_comments未设置时才补拉（enrich_source_items在top_comments已设置时是 no-op）。不要把 finalize 变成唯一启动点，也不要在 collect 循环内联富化——那会把其他源串行阻塞 124s。
3. 低于有效下限 → 预算记 0，整条跳过：不要发起注定失败的 11s 拉取。Bright Data 侧cli_timeout = max(5, timeout-10)，预算 11s 会变成 CLI 超时 1s，却仍花 3 个积分。建议常量MIN_USEFUL_REVIEW_BUDGET = 90。面包屑时间意味着跳过，而不是用极短超时硬试。
4. 跳过或全掉时上报PARTIAL：Amazonsource_status记为 PARTIAL，detail 为review lane timed out/review lane skipped (budget 0s)；搜索成功的产品列表保留，不把整个源翻成timeout。页脚（footer）已能在 state != ok 时显示 ⚠，不要改 render.py。
5. 边界保持：depth=quick仍然零拉取；mock=True仍然跳过；不加环境变量旋钮；不抬高LANE_DEADLINE或FOREGROUND_CONTRACT。

四、amazon.py 实现：预算数学与降级状态

4.1 关键常量一览

实现落在 amazon.py，这些常量共同决定了预算语义：

4.2 核心函数_remaining_lane_budget

新版预算函数（amazon.py L534-L545）在剩余时间低于下限时直接返回 0：

def _remaining_lane_budget(elapsed: float) -> int: remaining = FOREGROUND_CONTRACT - elapsed - RENDER_MARGIN if remaining < MIN_USEFUL_REVIEW_BUDGET: return 0 return int(min(LANE_DEADLINE, remaining))

对照实测数字：elapsed=269 →300-269-20=11 < 90→ 返回 0，车道直接跳过；elapsed=40 → 剩余 240，钳制到LANE_DEADLINE=180；elapsed=100 → 剩余 180，同样拿到满额预算。

4.3enrich_with_reviews改为返回状态明细

enrich_with_reviews（amazon.py L548）签名改为返回(products, status_detail)二元组，status_detail 三态：

• None—— 正常成功；
• "review lane skipped (budget 0s)"—— 预算低于下限，车道未运行；
• "review lane timed out"—— 所有并行拉取都被截止时间丢弃。

值得注意的一个细节是线程池不使用with上下文管理：每个 future 提交后已经在跑，future.cancel()永远不可能成功，而shutdown(wait=True)会阻塞在刚刚被截止时间宣判"丢弃"的那个慢拉取上，让截止时间形同虚设。代码用pool.shutdown(wait=False, cancel_futures=True)（amazon.py L633）让被丢弃的线程在后台自行结束，主运行继续前进。被丢弃的产品仍保留搜索记录的统计值、以quiet状态渲染而不是从报告中消失——丢失一个头部产品的近窗口读数，比把它整个删掉更好。

4.4 为什么放弃"原地补拉"

enrich_source_items（amazon.py L645）保留为收尾补缺函数，但它具备幂等性：当metadata["top_comments"]已存在时直接 no-op。这使它既可以服务于旧路径兼容，又不会在检索阶段已经富化过的情况下重复烧 Bright Data 积分。

五、pipeline.py 实现：调度位点与时钟穿透

5.1run_started作为墙钟原点

在 pipeline.py L2014-L2017，主运行函数创建墙钟原点：

run_started = time.monotonic()

run_started被新增为_retrieve_stream、_retrieve_stream_impl、_retry_thin_sources的参数并透传（_retrieve_stream包装层不消费它，仅转发到 impl，见 pipeline.py L4209），所有调用点均传入该值。这样才能在每个子查询流内部、任何一个源成功返回时，都能计算出相对整次运行的真实 elapsed。

5.2 Amazon 分支：搜索后立即富化

在_retrieve_stream_impl的 Amazon 分支（pipeline.py L4775-L4819）中，行为序列是：

1. 确定 keyword 与 domain（支持LAST30DAYS_AMAZON_DOMAIN配置与_amazon_query内部参数）；
2. search_products搜索并parse_search_response解析产品；
3. 若来自 thin retry 则直接返回（见下）；
4. 计算elapsed = time.monotonic() - run_started，立即调用amazon.enrich_with_reviews(...)，此时其他源的 future 仍在并行执行；
5. 若富化返回降级状态（review_status非空），则在该源的 artifact 上附加_source_outcome = {state: PARTIAL, detail: ..., attempted: True}（pipeline.py L4810-L4817）。

该 artifact 随后由_retrieve_stream中的_resolve_stream_outcome和主循环的 outcome 消费逻辑（pipeline.py L2460-L2478）转换为source_status上的正式SourceOutcome，保留 PARTIAL 状态与 detail 文案。

5.3 薄结果重试不重复富化

_retry_thin_sources（pipeline.py L3991）在 Phase 2b 薄源重试时传递skip_amazon_enrichment=True（pipeline.py L4082），避免对 Phase 1 已富化过的 ASIN 产生重复的 Bright Data 拉取。finalize 会对真正的新产品补拉，而已有top_comments的产品被enrich_source_items自动跳过，两层幂等互相兜底。

5.4 finalize 退化为 attach-if-missing

_finalize_items_by_source的 Amazon 分支（pipeline.py L3099-L3116）在注释中明确了新角色：评论富化现在在检索阶段就已发生，到达这里的条目应当已经带top_comments；finalize 路径（含 fixture 回放合并）只为 fixture replay、run_started未传入等边缘情况补缺。

六、状态契约与"不改页脚"的边界纪律

降级状态通过既有机制向上暴露：

• PARTIAL定义于 schema.py，引用自 health 模块的常量体系；
• artifact 上的_source_outcome是引擎内既有的 typed outcome 契约（_outcome_artifact、_legacy_artifact_outcome同款），finalize 时由_finalize_source_status（pipeline.py L3497）与最终证据集同步；
• 渲染层的_render_source_outcome_note（render.py L2553）已能对 state != ok 的源输出诊断说明，因此本修复刻意不改 render.py / 页脚。

计划文档还划定了严格的 out-of-scope：不改页脚、不动 X 搜索与 Grok 鉴权、不加 env 旋钮、不重排整张源调度表（延后处理）。这是典型的"修一处、保全局"纪律——Amazon 的评论预算问题是调度时序问题，不是全局调度重构问题。

七、测试验证：针对 Bentgo 回归的测试网

计划将既有测试重新定向，并新增了针对性的回归测试（全部位于 tests/test_amazon.py，无网络、无子进程）：

既有测试重定向：

• test_lane_budget_shrinks_as_the_run_clock_advances—— 现在验证下限行为（elapsed=200 及以后返回 0，而非原来的小数值）；
• test_dropped_straggler_keeps_its_product_with_search_stats—— 改用 patch 过的短LANE_DEADLINE触发丢弃场景，不再依赖面包屑预算；
• test_exhausted_wall_clock_skips_the_lane_entirely—— 不变。

新增回归测试：

• test_lane_budget_floor_prevents_doomed_pulls—— 断言 elapsed=269 返回 0；elapsed=190（恰好 90）返回 90；elapsed=191（89）返回 0（test_amazon.py L836-L848）；
• test_lane_budget_constants_are_sane—— 守卫常量漂移：MIN_USEFUL_REVIEW_BUDGET==90、LANE_DEADLINE==180、下限必须小于车道截止（test_amazon.py L850-L854）；
• test_crumb_budget_skips_not_fires_doomed_pulls——Bentgo bug 的直接回归测试：elapsed=269 时 fetcher 绝不被调用、产品保留搜索统计、状态为"review lane skipped (budget 0s)"（test_amazon.py L397-L421）；
• test_early_elapsed_gets_full_budget—— elapsed=40 时fetch_reviews收到 180s 超时（test_amazon.py L423-L450）；
• test_all_pulls_dropped_reports_timed_out_status—— 全部拉取被丢弃时返回"review lane timed out"状态（test_amazon.py L452-L472）。

八、从这次修复可迁移的经验

1. 预算的下限要么"有效"，要么干脆为零：对按时长计费的拉取型后端，极小超时（如 1s CLI timeout）与不发起是等价成本、不等价收益——前者烧积分且必然失败。低于业务有效阈值时"跳过并显式降级"，远胜"硬试一把"。
2. 富化预算应花在能并行的最早时刻：把 enrich 塞到依赖数据（搜索结果）就绪的瞬间，与其他源重叠执行，而不是排队等全量检索完成后再串行跑。其前提是能把真实 elapsed 穿透到该位点——这正是run_started参数化的价值。
3. 不要用"垫高单源预算"对抗宿主级合约：300s 的 Bash 合约约束的是整次运行；单源超预算的后果是整份报告的失败，优先级高于任何单个源的完整性。
4. 降级要精确：搜索成功只富化失败，应报PARTIAL且保留 listings，而不是把整个源翻成timeout；可操作的 detail 文案（review lane skipped (budget 0s)）让用户与doctor都能看懂发生了什么。

以上修复的全部设计意图、边界与验证均已落在 docs/plans/2026-08-14-fix-amazon-review-budget-plan.md，实现以 amazon.py、pipeline.py 为落地载体，行为契约由 test_amazon.py 固化——任何后续修改若让"11s 打火"或"0 预算强试"回归，都会立刻被测试网拦截。

【免费下载链接】last30days-skillAI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary项目地址: https://gitcode.com/GitHub_Trending/la/last30days-skill