# 2026-05-18 Agent健身房复盘 一句话概括：**这次发现的不是已经自动修复的问题，而是 5 类以后会反复浪费时间的操作摩擦 / 工具缺口。** | 优先级 | 发现的问题 | 真实含义 | 计划怎么解决 | | --- | --- | --- | --- | | 1 | 飞书文档写回前缺少目标预检 | 容易把“补第一列日期”误解成补表头，或把用户给的数据页当成真正要写的 PRD 页；一旦误改 docx/画板/图片区域，回滚成本高。 | 做 `lark_docx_writeback_preflight.py` 和验收脚本：写前 resolve wiki/docx、列出 block/表格/画板 token 和 patch plan，写后回读校验目标文本与非目标 token。 | | 2 | 客服知识场景挖掘还是临时脚本拼装 | 同一篇文档从 10 个 skill 数纠偏到 123 个原文场景，又补来源列、背景、一线/二线、SQLite 全量回灌，说明口径和字段契约还没沉淀。 | 把 `客服知识skill化` 项目的场景挖掘收敛成稳定入口、contract YAML 和校验脚本，固定 123/143 回归样例与全量 44 篇/1314 条验收。 | | 3 | 本地复核页保存链路没有一键健康检查 | 页面能打开不代表能保存；这次暴露了 file:// 与 localhost 的差异、端口没监听、前后端标签 schema 不一致、下拉残留旧值等问题。 | 做 `review_page_edit_healthcheck.py`：检查端口、`/api/health`、HTML 保存 API、前后端 schema diff，并跑一次浏览器保存 smoke。 | | 4 | Obsidian 图片上传排障链路可复用但未工具化 | 失败点可能在 Obsidian 插件、PicGo 端口、PicGo 图床、OSS 权限或账务；这次最后定位到欠费 UserDisable，路径清晰但手工步骤多。 | 做 `check_picgo_oss.py` 和对应 skill：按层检查 vault 配置、PicGo localhost、日志、测试上传、OSS/RAM/账务只读探针，并隐藏密钥。 | | 5 | Anki 翻译审校需要从聊天解释升级成可回滚写入流程 | 用户不只是要解释截图，而是要直接改 Anki，并能扩展到 82 张卡的批量审校；关键是备份、字段级 diff、标签和复核。 | 做 `anki_translation_review.py` 或 skill：AnkiConnect 查询、备份、只改 `Translation`、加标签、抽样复核、生成审校报告。 | ## 一、下一步 | 顺序 | 先做什么 | 为什么 | | --- | --- | --- | | 1 | 先做飞书写回预检器 | 它直接防止误写在线文档，是当天唯一发生“用户没看到预期结果”的返工点。 | | 2 | 把客服场景挖掘管线固化 | 这是 job-bu 当天最大块的高频分析资产，后续会持续迭代。 | | 3 | 给复核页生成流程加保存链路 smoke | 能把“给用户一个 URL 后打不开/不能保存”的问题提前拦截。 | | 4 | 沉淀 PicGo/OSS 上传诊断器 | 这是典型本机工具链问题，未来再次失败时应直接给分层根因。 | | 5 | 补 Anki 翻译审校约定和脚本 | 学习系统会继续出现“从单卡解释到整 deck 修订”的同类需求。 | ## 二、候选详情 ### 2.1 飞书文档写回预检与验收 - 类型：`diagnostic-tool` - 风险：`medium` - 摘要：这个主题有明确价值：多个飞书写回任务的风险不在 API 调用本身，而在写之前没有确认真实目标、块级位置和用户意图。失败案例体现为把“补第一列日期”误解成“补表头”，成功案例则说明 block 级定位、最小 patch 和回读验收可以显著降低误改文档、画板、图片或嵌入对象的风险。 - 关键改动： - 新增 skill：`/Users/bytedance/.codex/skills/lark-docx-writeback-preflight/SKILL.md`，规定凡是飞书 wiki/docx 写回都先执行 preflight：resolve wiki/doc token、拉 `docs +fetch` markdown、拉 docx blocks、列出目标块/表格/画板/图片/嵌入 sheet token，并在写前输出 patch plan。 - 新增工具入口：`/Users/bytedance/Documents/job-bu/tools/lark_docx_writeback_preflight.py`，输入来源为用户给的飞书 URL、自然语言修改指令、可选日期/目标章节/目标列名；核心检查为 URL 是否指向真实目标文档、目标章节是否存在、目标块是否唯一、表格行列和空单元格是否匹配、将被保留的图片/画板/sheet token 是否在 patch 范围外。 - 新增验收脚本：`/Users/bytedance/Documents/job-bu/tools/lark_docx_writeback_verify.py`，写后回读 markdown 与 blocks，成功信号包括目标文本/日期/行数命中、block revision 更新、非目标 token 数量和 ID 不变；失败信号包括目标章节缺失、多候选 block、patch 计划覆盖整表或包含画板/图片 token、写后缺少预期文本。 - 证据： - `019e39d9-023c-75e3-b8de-8641c41157c1`（~/Documents/job-bu）：用户原话：“第一列把工作日期补上”；assistant 先判断“只把左上角表头补成「工作日期」”，随后用户追问“没看到里面加比如5月18日这种啊”。 - `019e39d9-023c-75e3-b8de-8641c41157c1`（~/Documents/job-bu）：assistant 第二轮承认：“刚才把‘第一列’理解成表头了；你要的是把下面每一行的工作日期补齐到类似 `5月18日`。” - `019e3a71-629b-7172-b2b5-b96c92f3fb23`（~/Documents/job-bu）：给定“用户需求明细”链接后，assistant 发现“API 读到的文档内容比你描述的少：它只暴露了两个嵌入 sheet，没有‘4. 需求详述’”。 ### 2.2 客服知识场景挖掘管线化 - 类型：`tool-upgrade` - 风险：`medium` - 摘要：这个主题有效，问题不是单次抽取偏差，而是同一项目里反复出现“计数口径、来源列、背景字段、文档层级、SQLite 回灌”的链路升级需求。现有结果已经从单篇 123 个原文问题场景推广到 44 篇文档 1314 条场景，说明应把临时脚本固化成可复跑、可校验、可解释的场景挖掘管线。 - 关键改动： - 把 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/projects/2026-05-15-客服知识skill化/scripts/build_product_wiki_doc_scene_sqlite_2026_05_18_v2.py` 重构为稳定入口 `scripts/build_product_wiki_doc_scene_sqlite.py`：支持 `--doc-list`、`--knowledge-id`、`--output-db`、`--version-tag`，日期版脚本只保留为兼容 wrapper。 - 新增 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/projects/2026-05-15-客服知识skill化/config/scene_mining_contract.yml`：固化场景来源列候选、拆合规则、背景回填优先级、文档层级判定词、必填输出字段和禁止把 skill 数当场景数的口径说明。 - 新增 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/projects/2026-05-15-客服知识skill化/scripts/validate_scene_mining_outputs.py`：校验单篇 `knowledgeId=7403295431490324518` 必须产出 123 个原文问题场景和 143 条来源记录，全量 44 篇必须写入 `documents/scenes/scene_mining_strategy/scenes_fts`，并检查 `scene_source_column/background/document_level` 非空率。 - 证据： - `019e39f5-9b43-7740-a245-0e1a277836a1`（~/Documents/job-bu）：用户先问这篇文档有多少个场景，随后纠正要和“窄口径商品主类目22篇_skill抽取清单_2026-05-15_v1.csv”一样，并要求重新挖掘和明确策略规范。 - `019e39f5-9b43-7740-a245-0e1a277836a1`（~/Documents/job-bu）：assistant 发现旧清单里的 10 是已复用/已产出 skill 数，不是正文场景数；重挖后给出 123 个原文问题场景、143 条来源记录。 - `019e39f5-9b43-7740-a245-0e1a277836a1`（~/Documents/job-bu）：用户继续补口径：“场景是从表格中的某一列挖下来的”，并要求新增“背景”字段；之后又要求加一文档一值的“一线文档还是二线文档”。 ### 2.3 复核页保存服务健康检查 - 类型：`diagnostic-tool` - 风险：`low` - 摘要：这个主题有明确价值，不是噪音：问题不是单点前端 bug，而是本地 HTML、edit API、标签 schema、持久服务和浏览器回归验证之间的链路健康问题。适合沉淀成一个可重复运行的健康检查工具，在用户打开复核页前先确认服务可达、保存 schema 对齐、下拉联动正确，并给出明确的操作 URL。 - 关键改动： - 新增 `tools/review_page_edit_healthcheck.py`。工具入口：`python tools/review_page_edit_healthcheck.py --root <review_dir> --html <review.html> --csv <source.csv> --url http://127.0.0.1:18765/`；输入来源：生成出的复核 HTML、原始 CSV、标签 schema 常量、本地 edit server `/api/health`；核心检查：确认不是 `file://` 操作、端口监听、health 返回 ok、HTML 中保存 API 指向当前服务、前端可选标签与服务端允许字段一致、父标签切换后子标签会清空或重算；成功信号：输出可操作 URL、health ok、schema diff 为空、浏览器 smoke 保存成功；失败信号：端口未监听、health 非 2xx、前后端枚举不一致、保存请求 4xx 或 CSV 未变更；建议落地路径：放在复核页生成器同级工具目录，并在每次生成 HTML 后自动运行一次。 - 在复核页生成脚本中增加 `--healthcheck` 或默认 post-generate preflight，把 `generator patch anchor`、HTML 文件路径、CSV copy 路径和服务 URL 写入 `out/review_healthcheck_report.json`，避免用户拿到一个看似能打开但保存不可用的页面。 - 为本地 edit server 增加 `GET /api/health` 与 `GET /api/schema` 两个稳定接口；`/api/schema` 返回服务端允许保存的一级/二级/三级字段、枚举值和版本号，前端启动时比对自身常量，发现不一致就在页面顶部显示不可保存状态。 - 证据： - `019e39d3-a3ba-7fe3-bcba-9dce5d0c37e4`（~/Documents/product-bu）：用户要求把本地 HTML 复核页“case从一个标签移动到另一个标签”的功能做健壮。assistant 发现 v31 页面保存依赖本地 edit API，不能直接用 file:// 打开。 - `019e39d3-a3ba-7fe3-bcba-9dce5d0c37e4`（~/Documents/product-bu）：根因包括：页面发的是二级/三级分类，服务端只允许生命周期状态/子领域；前端下拉沿用旧生命周期常量；切换父标签时子标签可能残留旧值。 - `019e39d3-a3ba-7fe3-bcba-9dce5d0c37e4`（~/Documents/product-bu）：用户问“我去哪个url做操作”后，assistant 给出 http://127.0.0.1:18765/；随后截图显示打不开，assistant 才确认端口没有监听、一次性后台进程没留住。 ### 2.4 Obsidian 图片上传链路诊断器 - 类型：`diagnostic-tool` - 风险：`medium` - 摘要：这个主题有明确复用价值：一次 Obsidian 图片上传失败最终被定位为阿里云 OSS 账号欠费禁用，而不是插件配置、PicGo 端口或 AK 删除。它沉淀出的诊断链路覆盖本地插件配置、PicGo localhost 服务、真实上传接口、OSS/RAM/账务只读探针，适合做成一键或半自动的本机故障定位工具。 - 关键改动： - 新增 skill：`/Users/bytedance/.codex/skills/picgo-oss-upload-diagnostic/SKILL.md`。工具入口写成“当用户说 Obsidian/PicGo/图片上传失败/upload failed 时触发”，输入来源包括 Obsidian vault 的 `.obsidian/plugins/*picgo*` 配置、PicGo 配置与日志、localhost 上传接口、系统端口监听、阿里云 OSS/RAM/账务只读 API。 - 新增脚本：`/Users/bytedance/Documents/info-bu/tools/picgo-oss-diagnostic/check_picgo_oss.py`，入口示例 `python check_picgo_oss.py --vault <vault_path> --probe-upload --aliyun-readonly`。核心检查步骤：读取插件 uploadUrl 和当前图床；检查 127.0.0.1:36677 或配置端口监听；发起最小测试上传或 dry-run；解析 PicGo 日志中的 HTTP status/errorCode；用本机 PicGo 凭证只读查询 AK 身份、RAM LastUsed、OSS bucket Head/List、账户余额状态。 - 在脚本输出中定义成功/失败信号：成功为 Obsidian 指向可达 PicGo endpoint、PicGo 返回 2xx 或明确 URL、OSS bucket 可访问且账户正常；失败按层级归因到 `obsidian_config_mismatch`、`picgo_port_down`、`picgo_upload_error`、`oss_user_disable_or_arrears`、`ak_permission_or_deleted`。输出必须隐藏 AK/secret，只保留 masked id、endpoint、bucket、errorCode 和建议下一步。 - 证据： - `019e39fb-a9ac-7e50-9bf5-ba2f8965eb3c`（~/Documents/info-bu）：用户问“为啥我obsidian上传图片失败，排查一下”，报错是“upload failed, check dev console”。assistant 先检查 Obsidian/PicGo 插件配置、PicGo 监听端口、日志和真实上传接口。 - `019e39fb-a9ac-7e50-9bf5-ba2f8965eb3c`（~/Documents/info-bu）：本次端口 127.0.0.1:36677 正常，两个 vault 都指向同一个 upload 接口；真实失败点是 PicGo 到阿里云 OSS，返回 403 UserDisable。 - `019e39fb-a9ac-7e50-9bf5-ba2f8965eb3c`（~/Documents/info-bu）：用户要求“帮我去确认一下”。assistant 尝试内嵌浏览器和 Chrome 控制台登录态均失败后，改用本机 PicGo 凭证做只读 API 探针。 ### 2.5 Anki翻译审校工作流 - 类型：`workflow-pattern` - 风险：`low` - 摘要：这个主题有效：片段显示用户的真实需求不是停留在歌词解释，而是要求 agent 直接修改 Anki 卡片，并能扩展到整副牌审校。最有价值的模式是把“截图/单卡解释”快速升级为“可回滚、可筛选、只改目标字段”的 Anki 批量改写流程。 - 关键改动： - 在 `/Users/bytedance/Documents/learning-bu/AGENTS.md` 增加 Anki 翻译审校约定：当用户说“改anki”“整体review翻译”“不好理解都解释清楚”时，默认进入 AnkiConnect 写入流程，而不是只在聊天里解释。 - 新增 skill `anki-translation-review`：入口为 AnkiConnect；输入来源包括截图识别出的歌词行、deck 名、note 标题/序号、用户指定的审校范围；流程固定为 findNotes -> notesInfo -> 导出备份 -> 只更新 `Translation` 字段 -> addTags -> 抽样复核写入结果。 - 在 `/Users/bytedance/Documents/learning-bu/tools/` 下沉淀脚本 `anki_translation_review.py`：支持 dry-run、deck 级 JSON 备份、按 note/tag 筛选、字段级 diff、批量写入和失败重试，避免每次手写 AnkiConnect 请求。 - 证据： - `019e3939-2969-7c52-b6d1-965217416825`（~/Documents/learning-bu）：用户先基于截图问歌词里 line 的意思，再要求把翻译改得通俗一些；assistant 给出解释后，用户纠正“我意思还你直接去改anki”。 - `019e3939-2969-7c52-b6d1-965217416825`（~/Documents/learning-bu）：assistant 通过 AnkiConnect 定位到 `英文歌词` deck 中 `See You Again` 的 L27，只改 `Translation` 字段，并复核字段写入成功。 - `019e3939-2969-7c52-b6d1-965217416825`（~/Documents/learning-bu）：用户进一步要求“整体review一下所有歌词的翻译，不好理解都解释清楚”。assistant 对 82 张歌词卡做 deck 级备份，只更新 Translation 字段，并加标签 `translation_review_20260518`。