# 2026-05-27 Agent健身房复盘 一句话概括：**这次发现的不是已经自动修复的问题，而是 4 类以后会反复浪费时间的操作摩擦 / 工具缺口。** | 优先级 | 发现的问题 | 真实含义 | 计划怎么解决 | | --- | --- | --- | --- | | 1 | 批量标注后端在全量前才暴露权限、配额、JWT 和入参问题 | 5279 条 session 标注过程中，Ark endpoint、Safe Experience Mode、Fornax evaluator 入参、JWT 失效轮番成为阻塞；没有预检时，全量跑批本身被迫承担诊断职责。 | 新增 `tools/fornax_ark_preflight.py` 和后端适配层，先用 1-3 条样本验 key、endpoint、quota、JWT、schema，失败就不进入全量。 | | 2 | 多维表格标签回写缺少 dry-run 审计层 | 7000 条 FAQ 回写同时涉及单选枚举、view/全表范围、record_id 单批 200 条上限、规则优先级覆盖；任何误判都会直接污染线上表。 | 新增 `tools/bitable_label_writeback_auditor.py`，先验证字段/枚举/范围/规则冲突并生成 update plan，真实写回只消费通过审计的 plan。 | | 3 | Review HTML 关键词统计被临时脚本反复解析 | 同一个 9335 session HTML 被连续用于关键词占比、解决率、sessionId 导出和口径洞察；全字段、对话正文、用户原话命中混在一起会误导结论。 | 新增 `tools/review_html_keyword_metrics.py`，固定 `const DATA.records` 解析、scope、分母、解决率和 ID 导出格式。 | | 4 | LLM Wiki 到 Obsidian 图谱流程已经跑通但还没沉淀成稳定流水线 | 这次有效经验包括复用 570 篇 clean index、自包含 vault、raw 链接校验、名词图谱降噪；继续用日期脚本会让下次子集重做。 | 把日期脚本抽成参数化 pipeline，并沉淀 `kefu-llm-wiki-obsidian-pipeline` skill，验收项固定为范围清单、missing_links=0、图谱降噪报告。 | ## 一、下一步 | 顺序 | 先做什么 | 为什么 | | --- | --- | --- | | 1 | 先做 Fornax/Ark 标注后端预检 | 它直接节省最长跑批时间，能把 key/endpoint/quota/JWT/入参错误提前到 1-3 条样本阶段暴露。 | | 2 | 再做多维表格标签回写审计器 | 这是线上数据写回前的保护层，能防止枚举名、规则覆盖、视图范围错误造成批量污染。 | | 3 | 补 Review HTML 关键词统计器 | 低风险、高复用，能立刻服务商品域 HTML 复核页的占比、解决率、导出清单类追问。 | | 4 | 把 LLM Wiki/Obsidian 流水线 skill 化 | 现有流程已经验证有效，适合在前三个诊断工具之后沉淀成复用模板。 | ## 二、候选详情 反思字段里只有一条 rubrics 概念研究，没有指向具体执行瓶颈；本轮候选主要来自用户实际任务中反复出现的工具摩擦。 ### 2.1 Fornax/Ark 标注后端预检与自愈 - 类型：`diagnostic-tool`；风险：`medium`；价值：`high` - 摘要：这个主题有效，且不是单点故障复盘：同一批标注链路连续踩到了 Ark endpoint/key、Safe Experience Mode 上限、Fornax evaluator 入参协议、JWT 过期和 prompt 资产/推理能力混淆。它适合沉淀成批量标注前的 preflight 工具，先用极小样本验证后端可用性，再决定是否进入长跑。 - 关键证据：019e69b2-aea1-76a0-821f-5e3c3905a691：批量标注 5279 个 session 前，100 条 sample 全失败；错误从 InvalidEndpointOrModel.NotFound 变成 endpoint 无权限/不存在，随后又发现 ARK_API_KEY 与当前 Ark 项目 active API key 不一致。；019e69b2-aea1-76a0-821f-5e3c3905a691：全量首段出现错误后定位为 Safe Experience Mode 推理上限，模型服务已暂停；继续跑只会增加失败行，因此中断并寻找内部 Fornax 通道。 - 落地动作：在 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/tools/fornax_ark_preflight.py` 新增诊断入口：`python tools/fornax_ark_preflight.py --backend ark|fornax --config <yaml> --sample <jsonl|csv> --limit 3`；输入来源包括批处理脚本同款配置、`.env`/环境变量里的 `ARK_API_KEY`、Ark endpoint/model/project、Fornax prompt/evaluator id、待标注样本的字段名；核心检查依次跑 key/endpoint 可见性、1 条最小 dry-run、Safe Experience/quota 错误识别、Fornax 登录态、prompt get-by-id 与 evaluator 执行能力区分、`input_data.input_fields.<key>` 入参协议；成功信号是返回可解析 JSON 且 schema 命中，失败信号是把 NotFound/unauthorized/quota/401/schema 包装错误分类输出；落地路径是所有批量标注 runner 在全量前强制调用该 preflight。；把现有批量标注 runner 抽出后端适配层，例如 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/lib/label_backends.py`：实现 `ArkBackend.preflight()` 和 `FornaxEvaluatorBackend.preflight()`，并在 Fornax 执行时统一封装 `input_data: {input_fields: ...}`；成功/失败信号写入 run manifest，只有 `status=ok` 进入断点完成集，401/5xx/限流都保留为可重试状态。 ### 2.2 多维表格标签回写审计器 - 类型：`diagnostic-tool`；风险：`medium`；价值：`high` - 摘要：这个主题有明确价值：相关片段显示标签回写失败并不是单点问题，而是由批量 API 限制、单选枚举不匹配、规则优先级覆盖、视图过滤口径共同造成。应在真实 update 之前增加一个审计器，把待回写数据、Base 字段结构、视图范围和标签规则先跑通，提前输出可执行的分组、风险和失败原因。 - 关键证据：019e68c9-c2a5-7061-8fa1-3f2b1011d6e3：创建 7000 条 FAQ Base 后，批量回写接口不支持一条请求里每行不同字段值，只能按 129 个唯一标签组合分组回写；单次 record_id_list 还最多 200 条且有频控。；019e68c9-c2a5-7061-8fa1-3f2b1011d6e3：PM 一级标签规则被用户逐步追加和覆盖：违规/处置/核销先归治理，随后审核归审核，核销/退款又改成交易，需要明确优先级并回放覆盖。 - 落地动作：新增工具入口：在 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/tools/bitable_label_writeback_auditor.py` 增加 CLI，建议参数为 `--base-url/--app-token --table-id --view-id --record-csv --label-fields --rule-file --dry-run-plan out/...json`；输入来源包括 Base 链接或 token、待回写 CSV/JSONL、标签规则 YAML/JSON、通过 lark-cli/API 读取的字段元数据和可选视图记录列表。；核心检查步骤：先解析 Base 链接并显式标记是否带 view；读取表列表、字段结构、单选/多选枚举；对待写标签逐条校验枚举值；按规则文件顺序回放标签覆盖，输出每条记录最终标签和命中规则；按字段值组合分组，再按 `record_id_list <= 200` 切片，估算请求数和频控等待时间。 ### 2.3 Review HTML 关键词口径统计器 - 类型：`tool-upgrade`；风险：`low`；价值：`high` - 摘要：这个主题有效，不是噪音：多个相邻 session 都围绕同一类 review HTML 反复做 const DATA 解析、关键词命中、sessionId 导出和分母校验。真正的问题不是单次统计，而是缺少一个稳定工具来固定解析方式、字段口径和输出指标，导致 JSON extra data、sessid/sessionId 字段误判、全文命中与用户真实诉求混淆等返工。 - 关键证据：019e6861-d74a-7930-9221-89ce145d2a1b：同一个 v31 review HTML 需要解析 const DATA.records，分母 total=9335；第一次截取 DATA 把后续脚本带进来导致 JSON extra data，需要按对象边界解析。；019e6861-d74a-7930-9221-89ce145d2a1b：用户连续追问关键词占比、解决率、再加占整个商品领域百分比；最终需要输出 case 数、已解决、未解决、解决率、全量占比。 - 落地动作：在 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/tools/review_html_keyword_metrics.py` 新增 CLI：输入 review HTML 路径和关键词，使用括号/对象边界解析 `<script>const DATA = ...</script>`，读取 `DATA.records`，并校验 `DATA.total == len(records) == unique(sessid)`；失败时明确报 `DATA_PARSE_ERROR`、`TOTAL_MISMATCH` 或 `ID_FIELD_MISSING`。；在同一 CLI 内置字段口径：`all_fields` 扫记录序列化文本，`messages_readable` 只扫对话正文，`user_text` 只扫用户原话/用户问题摘要，`metadata` 扫 label/reason/命中客服Skill 等辅助字段；每个 scope 输出 case 数、已解决、未解决、解决率、HTML 全量占比、商品域大盘占比。 ### 2.4 客服文档 LLM Wiki 到 Obsidian 图谱流水线 - 类型：`workflow-pattern`；风险：`medium`；价值：`high` - 摘要：这个主题不是噪音：它覆盖了从客服知识库筛选、LLM Wiki 编译、自包含 Obsidian vault 打包，到核心名词图谱清洗的一整条可复用流水线。片段显示，本轮不只是生成文档，而是在范围裁剪、raw provenance、链接完整性、图谱降噪上形成了明确的工程约束。它适合沉淀成 Night Gym 的知识库图谱交付模式，价值主要在减少一次性脚本和避免图谱误连。 - 关键证据：019e682f-1489-7fe0-bc75-6e006cbbd3f9：用户从 客服文档中商品相关有哪些 开始，最终要求把 top500 直接相关 45 篇中排除审核/治理的文档做成 Karpathy 式 LLM Wiki。；019e682f-1489-7fe0-bc75-6e006cbbd3f9：现有工程已有 570 篇 LLM Wiki 编译脚本和文章页格式；本轮复用结构，只新增 商品非审核治理 子集，最终 19 篇保留、26 篇排除。 - 落地动作：把 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/projects/2026-04-29-人工客服知识库llm-wiki/scripts/build_product_top500_non_audit_governance_llm_wiki_2026_05_27_v1.py` 抽成参数化入口：支持 `--input-csv`、`--scope-filter`、`--exclude-primary-buckets`、`--unmatched-exclude-terms`、`--run-name`、`--make-vault`，避免以后每个子集都复制一份日期脚本。；新增 vault 校验脚本 `/Users/bytedance/Documents/job-bu/obsidian-vaults/商品top500非审核治理LLMWiki/scripts/validate_vault_links.py`：检查 `articles/`、`raw/`、`domains/`、`categories/`、`core_terms/` 的相对链接可解析，并输出 `missing_links=0`、raw source 覆盖率、孤立 article 数。 ## 三、产物 | 文件 | 内容 | | --- | --- | | `out/manifest.json` | 候选列表、证据、建议改动和审批状态 | | `out/examples/` | 每个候选的 before/after 或诊断流程样例 | | `out/approve.sh` | 通过候选审批的本地脚本 |