# 2026-05-28 Agent健身房复盘 一句话概括：**这次发现的不是已经自动修复的问题，而是 5 类以后会反复浪费时间的操作摩擦 / 工具缺口。** | 优先级 | 发现的问题 | 真实含义 | 计划怎么解决 | | --- | --- | --- | --- | | 1 | 批量打标先卡在模型后端，而不是业务逻辑 | Ark endpoint、API key、Safe Experience Mode、Fornax payload/JWT 会把整批结果污染成失败行 | 做 `model_batch_backend_doctor.py`：启动前 smoke、运行中熔断、401 刷新、后端自动切换 | | 2 | 知识召回治理链路太长，靠临时脚本串起来 | TopN、历史库反查、母表补齐、来源字段、解决率、Pareto 图每一步都可复用，但现在分散在 adhoc 脚本里 | 做 `knowledge_recall_governance.py` + sources YAML，一键生成写入计划、图表和验收报告 | | 3 | 飞书 Base 大批量写入缺少稳定同步器 | 13,102 行写入、4,705 条新增、6,616 条回填都需要批大小、超时、重试和最终对账；人工盯日志很浪费 | 做 `lark_base_bulk_sync.py`：profile 预检、自适应分批、断点续跑、reconcile 报告 | | 4 | 本地 HTML 复核页验收不稳定 | 有时 Playwright 可渲染，有时 `file://` 被内嵌浏览器拦截，只靠静态检查无法证明页面真的可用 | 做 `review_html_smoke.py`：临时 localhost 打开、DOM 计数、截图、jsdom/minimal DOM fallback | | 5 | 网页不可用排障需要同时看地区、账号和代理配置 | Gemini 是地区/账号限制，Surge 是 `[Rule]` 缺 `FINAL`，单凭截图容易只解决一半 | 做 `web_access_proxy_doctor.py` + `surge_lint.py`，按页面文案、出口地区、规则覆盖和配置语法定位根因 | ## 下一步 | 顺序 | 先做什么 | 为什么 | | --- | --- | --- | | 1 | 先做 `model_batch_backend_doctor.py` | 它直接影响 4,986 / 5,279 这类长跑任务，失败会污染全量结果，收益最大 | | 2 | 再做 `lark_base_bulk_sync.py` | 飞书 Base 批量写入是多个数据分析交付的底座，先稳定底座再做业务流水线 | | 3 | 把知识召回治理流水线接到同步器上 | 这样 TopN、来源、解决率、图表和母表回填可以一次完成 | | 4 | 补 HTML smoke 和网页代理 doctor | 这两个是低风险小工具，适合并行补齐日常验收和排障体验 | ## 一、候选详情 ### 1.1 批量打标后端预检与自动切换 - 类型：`diagnostic-tool`；风险：`medium`；价值：`high` - 摘要：这个主题有明确价值：多个失败片段都不是标注语义问题，而是模型后端、认证、端点或协议层问题。批量任务如果缺少预检和运行中熔断，会把 401、404、Safe Experience Mode、payload schema 错误批量写入结果，直接污染交付 CSV。建议沉淀成独立 doctor 工具，并接入批量打标 runner 的启动前预检与失败后自动切换。 - 关键证据： - `019e69b2-aea1-76a0-821f-5e3c3905a691`：100 条都失败了，说明不是标注分布问题，而是接口调用层问题。我先看错误类型，优先确认 endpoint 与 key 是否匹配。 - `019e69b2-aea1-76a0-821f-5e3c3905a691`：错误不是普通限流，是账号触发了 `Safe Experience Mode` 的推理上限，模型服务已暂停。当前继续跑只会增加失败行，我会先中断全量进程，保留已经成功的少量结果，后面改用不受这个限制的方案。 - 示例文件：`examples/model-batch-backend-doctor.md` ### 1.2 知识召回治理一键流水线 - 类型：`tool-upgrade`；风险：`medium`；价值：`high` - 摘要：这个主题不是噪音：片段里反复出现从 session 召回明细、知识 ID TopN、历史库反查、母表补齐到 Lark Base 批量写入的完整链路。当前流程已经能完成单次交付，但多处依赖人工拼接、兜底判断和补字段，适合沉淀成可复用的一键治理流水线。 - 关键证据： - `019e69b2-aea1-76a0-821f-5e3c3905a691`：在 `商品域相关` 的 4986 个主标签 session 里，按 `top1知识id/top2知识id/top3知识id` 任一命中做 session 去重计数，取 Top 123 知识 ID。 - `019e69b2-aea1-76a0-821f-5e3c3905a691`：表和字段已建好，Base token 是 `JKLqbcQi5alxVWswTlQcBdjdnSd`，数据表 ID 是 `tblynvs3wXJyEQYV`。现在开始准备分批写入 13,102 行，先用 1 行 dry-run 验证批量接口的 JSON 结构。 - 示例文件：`examples/knowledge-recall-governance-pipeline.md` ### 1.3 飞书多维表格批量同步器 - 类型：`tool-upgrade`；风险：`medium`；价值：`high` - 摘要：这个主题有明确价值，不是噪音：片段里连续出现了飞书 Base 大批量写入、账号配置预检、批大小超时、CLI 输出缓冲、单条 upsert 性能退化和最终对账等问题。当前做法依赖临时脚本和人工观察，适合沉淀成一个带 preflight、批量能力探测、自适应分批、断点续跑和对账报告的同步器。 - 关键证据： - `019e69b2-aea1-76a0-821f-5e3c3905a691`：本机 skill 里写的字节配置路径有点旧，实际没有 `config.bytedance.json`。我先读取当前 lark-cli 登录状态和 profile，确认现在就是工作账号后继续。 - `019e69b2-aea1-76a0-821f-5e3c3905a691`：第一批还没返回，说明 500 行批次对 Base 接口/CLI 可能太重。脚本里单批有 120 秒超时；我等它触发一次结果，然后决定是否切到更小批次。 - 示例文件：`examples/lark-base-bulk-sync-diagnostics.md` ### 1.4 本地复核页渲染检查工具 - 类型：`diagnostic-tool`；风险：`low`；价值：`high` - 摘要：这个主题有效，不是噪音：片段里出现了两条稳定需求，一条是静态 review HTML 需要首屏真实渲染验收，另一条是 file:// 被内嵌浏览器拦截时需要可靠 fallback。它适合沉淀成只读诊断工具，把 HTML payload 解析、DOM 渲染、截图/计数校验和失败原因归因合成一个固定 smoke harness。 - 关键证据： - `019e69b2-aea1-76a0-821f-5e3c3905a691`：页面骨架看起来符合你的要求：左侧知识 ID、中央 session、右侧微信式对话气泡。下一步我用本地浏览器能力打开一下静态页，确认首屏能渲染，不只停留在文件级校验。 - `019e69b2-aea1-76a0-821f-5e3c3905a691`：浏览器渲染通过了：首屏 123 个知识 ID 列表、默认知识 ID 下 630 个 session、右侧 8 轮对话都正常加载。我再看一眼截图确认视觉上没有明显挤压或空白。 - 示例文件：`examples/review-html-smoke-harness.md` ### 1.5 网页地区与 Surge 配置诊断器 - 类型：`diagnostic-tool`；风险：`low`；价值：`high` - 摘要：该主题有效：片段里同一天连续出现了 Gemini 地区拦截和 Surge 配置校验失败，说明用户遇到的不是单一网页问题，而是一类“网页访问失败时需要同时判断地区、账号、缓存、代理规则和配置语法”的诊断场景。沉淀成诊断器可以避免每次只凭截图给建议，改为用可复现检查链路定位根因。 - 关键证据： - `019e6d70-108e-7680-a5d7-393a43143426`：用户问“为啥进去不能聊天”，截图对应 Gemini 页面提示 “Gemini isn’t currently supported in your country.” - `019e6d70-108e-7680-a5d7-393a43143426`：回答里将根因定位为 Gemini 地区拦截页，并指出 Mainland China 对个人账号通常不可用，需要换到支持地区出口或检查账号类型。 - 示例文件：`examples/web-access-proxy-doctor.md`