# 2026-05-09 Agent健身房复盘 一句话概括：**这次发现的不是已经自动修复的问题，而是 4 类以后会反复浪费时间的操作摩擦 / 工具缺口。** | 优先级 | 发现的问题 | 真实含义 | 计划怎么解决 | | --- | --- | --- | --- | | 1 | 复核页数字一致性靠人工发现 | 同一套复核包一边迭代一边产出 CSV、HTML、Excel，任何一个环节沿用旧 payload 或空值口径不一致，都会让用户在页面上继续质疑数字。 | 做 `audit_lifecycle_review_pack.py`，每次生成 vN 后自动校验行数、父子加总、空值桶、HTML payload 和 Excel 汇总。 | | 2 | 飞书带图复制链路缺一键验收 | 这不是普通 Word 导出，而是 GUI 原生复制、剪贴板 HTML、图片下载与 docx 包结构共同决定成败；没有诊断器就会反复从空白 Word/丢图开始试。 | 补 `lark-docx-image-copy doctor`，固定复制前后检查、docx media inspect、外链图片数和 bundled Python 运行时检查。 | | 3 | Anki 真实牌组迁移缺统一护栏 | 歌词和钢琴卡都已经直接改真实 Anki collection，靠临场判断备份和验数风险偏高；后续需要统一 dry-run、备份、计数和模板变更校验。 | 做 `anki_migration_guard.py`，把备份、dry-run diff、期望卡数、tag 计数、模板变更和执行后验证合成一个入口。 | | 4 | 长链路数据任务升格太晚 | 当天同一个数据任务从 v4 走到 v20，最后才被用户提醒是连续项目；这个触发点应该更早识别，避免主线资产散在 adhoc。 | 给 data-analysis-workspace 增加 `promote_adhoc_to_project.py` 和项目模板，检测连续 vN/多交付物时自动建议升格。 | ## 下一步 | 顺序 | 先做什么 | 为什么 | | --- | --- | --- | | 1 | 先做商品域复核包一致性诊断器 | 昨天用户多次直接指出数字不等，且它会影响所有后续 taxonomy 版本交付。 | | 2 | 补飞书带图复制 doctor | 这是 reflection 明确指向的高成本瓶颈，成功判据也清晰：图片占位、内嵌媒体数、外链数。 | | 3 | 抽 Anki 迁移护栏 | 真实 Anki collection 修改有误删和模板污染风险，统一 guard 后再继续扩展歌词/音乐学习卡。 | | 4 | 加 adhoc 升格项目模板 | 它不是单点修 bug，但能减少后续数据分析资产散落和版本链断裂。 | ## 一、候选详情 ### 1.1 商品域复核包一致性诊断器 - 类型：`diagnostic-tool` - 风险：`low` - 摘要：这个主题有明确价值，不是噪音：同一条商品域生命周期复核链路里，用户多次指出页面数目不等，后续修复也反复围绕 CSV 明细、HTML payload、Excel 汇总、父子桶加总和空值规范。适合沉淀成发布前诊断器，把口径错误、多标签误加总、空白子类和旧 payload 汇总偏差提前拦住。 - 建议变更： - 新增 `projects/2026-05-09-商品领域意图体系迭代/scripts/audit_lifecycle_review_pack.py`。工具入口：`python scripts/audit_lifecycle_review_pack.py --version v20 --csv clean/lifecycle_sessions_v20.csv --html output/review_pages/...v20.html --excel output/生命周期汇总_标签拆列_2026-05-09_v20.xlsx --out analysis/audits/v20_consistency_audit.json`；输入来源是同版本 CSV 明细、HTML 内嵌 payload、Excel 汇总。 - 核心检查步骤：从 CSV 明细重算顶层、子领域、下一级标签 summary；抽取 HTML payload 并校验 `payload_rows == csv_rows`；读取 Excel 汇总并校验各层分母；逐父桶检查 `parent_total == child_sum`；扫描空字符串/NaN/`未归类` 是否被拆成多个空白桶；标记多标签统计表和互斥主标签表是否被混用。 - 成功/失败信号：成功输出 `remaining_mismatches=[]`、`row_count_match=true`、`blank_bucket_collisions=[]`、`multi_label_overcount_explained=true`；失败时输出具体父桶、CSV 计数、HTML 计数、Excel 计数、差值、疑似原因和受影响文件路径，命令以非 0 状态退出。 - 建议落地路径：把诊断器接入每次生成 vN 复核包后的 `make audit VERSION=vN` 或脚本尾部；同时在项目 `AGENTS.md` 增加规则：发布 HTML/CSV/Excel 前必须跑 audit，不能沿用旧 HTML payload summary，所有汇总都从当前 CSV 明细重算。 - 证据： - `019e0b70-ac42-75b3-9679-2df044f645fa`：用户在 v7 复核页截图后直接指出：总和感觉不等啊。 - `019e0b70-ac42-75b3-9679-2df044f645fa`：校验时发现旧 v3 的 HTML payload 里汇总层本来就有 1 条左右的历史偏差，CSV 明细是 207/121，Excel 从旧 payload 读成 208/122。 - `019e0b70-ac42-75b3-9679-2df044f645fa`：v7 里有空的 `下一级标签`，所以父类总数和展示出来的子类加总不一致。 我已生成 v8，补齐了所有不等的父桶。 ### 1.2 飞书带图复制诊断器 - 类型：`diagnostic-tool` - 风险：`medium` - 摘要：这个主题有效：片段里既有反复失败模式（空白 Word、纯文本丢图、插件路径不可接受），也有一次成功闭环（1037 个图片位置全部内嵌、外链为 0）。当前已有 workspace skill 雏形，但仍需要把“复制前/复制后/生成后”的检查固化成一键诊断入口，避免下次重新试错。 - 建议变更： - 在 `/Users/bytedance/Documents/job-bu/.agents/skills/lark-docx-image-copy/SKILL.md` 增加 `doctor` 入口说明：工具入口为 `scripts/doctor_lark_docx_image_copy.py`；输入来源包括目标飞书/客服知识库 URL、Computer Use 原生复制后的剪贴板快照目录、可选的既有 docx/report；默认运行时写明优先使用 Codex bundled Python。 - 新增 `/Users/bytedance/Documents/job-bu/.agents/skills/lark-docx-image-copy/scripts/doctor_lark_docx_image_copy.py`：串联 `capture_macos_clipboard.py`、`build_docx_from_clipboards.py --strict`、`inspect_docx_media.py`，核心检查步骤为纯文本长度、`[图片]` 占位数、rich HTML `<img>` 数、build failures、`drawing_count`、`total_embedded_images`、`external_image_relationships`。 - 为诊断器定义成功/失败信号并输出机器可读报告：成功信号是 `total_text_image_markers == total_html_images == total_embedded_images == drawing_count` 且 `external_image_relationships == 0`、`failures=[]`；失败信号按 `focus_wrong`、`plain_text_only`、`range_incomplete`、`decorative_images`、`external_images`、`runtime_missing_deps` 分类，并给出下一步动作。 - 建议落地路径：把 2026-05-08 的 1037 图样本作为回归 fixture/inspect 样本，补 `scripts/run_smoke.py` 或 `tests/test_lark_docx_image_copy_doctor.py`，同时在 `/Users/bytedance/Documents/job-bu/.agents/skills/lark-docx-image-copy/agents/openai.yaml` 增加“空白 Word/丢图/1037 张图/飞书带图复制”等触发词。 - 证据： - `019e0ad9-b807-7281-8839-f0cbea10b4ee`：从空白 Word、纯文本丢图、插件路径不可接受到 1037 张图嵌入，说明这不是普通导出任务，而是需要一条可诊断的原生复制流水线。 - `019e0ad9-b807-7281-8839-f0cbea10b4ee`：最终产物是 `商品四篇知识库全文_ComputerUse复制_2026-05-08_v3_带图片版.docx`。关键结果是 1,037 个图片位置全部内嵌，`external_image_relationships=0`。 - `019e0ad9-b807-7281-8839-f0cbea10b4ee`：保留“原生复制 -> 抓取剪贴板纯文本和 HTML -> 下载并内嵌图片 -> Word 包结构验收”的链路，同时补三个诊断脚本。 ### 1.3 Anki牌组迁移护栏 - 类型：`tool-upgrade` - 风险：`medium` - 摘要：这个主题有效，而且不是噪音：相关片段里连续出现了对真实 Anki 牌组的覆盖导入、模板拆分、保留复习进度和备份需求。当前流程已经靠临场判断做了若干保护动作，但这些护栏还没有沉淀成统一工具，后续每次改牌组仍容易误删手工新增卡、破坏 note type 模板或丢失复习历史。 - 建议变更： - 新增 `learning-bu/tools/anki_migration_guard.py`：统一封装 AnkiConnect + collection API 的迁移前检查、备份、dry-run diff、执行、执行后验证。入口参数至少包含 `--deck`、`--mode replace-deck|add-template|update-template`、`--expected-old-count`、`--expected-new-count`、`--old-tag`、`--new-tag`、`--backup-dir`、`--apkg`。 - 在歌词项目的 `english/04-projects/lyrics-cloze-2026-05-09/build_deck.py` 或后续生成脚本里接入 guard：生成 `.apkg` 后不直接删除/导入，而是先调用 guard 校验 `deck:"歌词"`、旧 tag 数、目标导入数和手工新增卡差异；只有 dry-run 显示安全时才执行覆盖。 - 在钢琴闪卡项目 `piano/04-projects/flashcards/` 增加 `migrations/` 目录和迁移记录模板：每次 note type/card template 变更记录原始 deck count、目标 count、受影响 note ids、备份 apkg 路径、保留复习进度的模板映射关系。 - 补一个 `Anki deck migration` skill 或 playbook：定义什么时候用 AnkiConnect、什么时候必须用 Anki 官方 Python API；把失败信号写清楚，例如模板新增被 AnkiConnect 静默忽略、deck count/tag count 不一致、note type 被多个 deck 共用。 - 证据： - `019e0ad7-e976-7f01-a4c7-05c309ec7c2a`：用 AnkiConnect 覆盖导入：先导出当前 `歌词` 牌组备份。只有当当前 `deck:"歌词"` 卡数等于旧 tag 卡数 `43` 时才删除旧牌组，避免误删你后来手动加的卡。 - `019e0ade-9ae3-7dc2-b6d7-c76b3829d6b4`：我会先导出一份当前 `钢琴 基础` deck 备份，然后再改模板；这是对 Anki 里的学习进度更稳妥的做法。 - `019e0ade-9ae3-7dc2-b6d7-c76b3829d6b4`：AnkiConnect 接受了原模板更新，但没有把新模板加进去；这说明这个接口只改已有模板。我会切到 Anki 官方 Python API，在本机 collection 里直接给这两个 note type 增加第二张 card template。 ### 1.4 一次性探查自动升格项目 - 类型：`workflow-pattern` - 风险：`low` - 摘要：这个主题有效：片段显示用户明确纠正“这其实是一个连续性的项目”，随后 agent 把临时 adhoc 产物提升为正式项目目录，并补齐 README、AGENTS、canonical 数据和版本链路。该模式的价值在于防止长期数据分析任务继续散落在临时目录里，同时保留原 adhoc 路径避免破坏历史链接。 - 建议变更： - 在 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/AGENTS.md` 增加“adhoc 升级项目”规则：当用户说连续性项目、后续迭代、vN/vN+1、整理目录、不要散在临时目录时，默认从 `adhoc/` 升级到 `projects/YYYY-MM-DD-主题/`。 - 新增项目模板目录 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/templates/data_project/`，包含 `README.md`、`AGENTS.md`、`raw/`、`clean/`、`analysis/`、`output/`、`scripts/`、`docs/`，并在 README 模板里固定写入口径、版本链、legacy adhoc 路径和关键交付物索引。 - 增加脚本 `/Users/bytedance/Documents/job-bu/data-analysis-workspace/scripts/promote_adhoc_to_project.py`：输入 adhoc 路径、项目名、当前版本号，复制 canonical 文件和交付物到正式项目目录，生成迁移清单，不删除原 adhoc。 - 在 Night Gym 复盘规则里加入检测项：如果某个数据分析任务出现 3 次以上版本迭代、多个输出文件或用户明确命名为项目，就把“项目化归档”作为下一步建议，而不是继续临时探查。 - 证据： - `019e0b70-ac42-75b3-9679-2df044f645fa`：这个其实是一个连续性的项目，叫做商品领域意图体系迭代，帮我整理下文件目录 - `019e0b70-ac42-75b3-9679-2df044f645fa`：我会把它从 adhoc 里提升成正式项目目录：保留原 adhoc 作为历史工作区，同时在 `projects/商品领域意图体系迭代` 下整理 canonical 数据、过程明细、脚本和交付物 - `019e0b70-ac42-75b3-9679-2df044f645fa`：我会不直接搬空原 adhoc 目录，避免破坏已有链接；正式项目目录里放“可继续迭代的主线文件”，原 adhoc 作为 legacy/staging 入口在 README 里记录。