跨工作区坑点库会话助手
目的
内部 Web 应用在多个互不共享记忆的工作区并行开发（web-app / 网页迭代对话 / web_skill_src / 技能转网页测试 / 平台规划 / 公众号思路）。各 workspace 的 .workbuddy/memory/ 独立、不互通，踩坑难同步。本技能让会话具备四项能力：
1. 启动载入 —— 进入相关工作区即读坑点库与 L1 指针状态并呈现；
2. 展示历史 —— 随时按工作区/标签过滤查已有坑；
3. 追加新坑 —— 会话中踩坑即时按模板写入并呈现；
4. 指针追踪 —— 校验 6 个工作区 L1 指针覆盖、追踪本次会话新增。
数据底座（勿改路径）—— 三源结构（2026-08-24 拆库后现状）
- 主表（机器权威）：
~/.workbuddy/lessons/pitfalls.md—— 规则头 + 完整索引表（每行| PF-NNN |）。三源自检脚本比对它；新增坑时在此追加索引行。aggregate/reconcile 脚本读详情目录pitfalls/PF-*.md（拆库适配 2026-09-02）。 - 详情文件：
~/.workbuddy/lessons/pitfalls/PF-NNN.md—— 每条坑的字段详情（日期/工作区/标签/坑/根因/解决/预防/关联）。条目格式见跨工作区知识共享方案.md§1.2。 - 人类副本：
~/.workbuddy/lessons/pitfalls/INDEX.md—— 人类阅读索引（编号卫生规则 + 完整索引表，链接为同目录相对(PF-NNN.md)）。 - L1 指针：各工作区
.workbuddy/memory/MEMORY.md顶部一行> ⚠️ 跨工作区坑点库：...，进工作区必看。 - 完整方案：
~/.workbuddy/lessons/跨工作区知识共享方案.md。 - 跨电脑同步：
zfl-sync-suite把lessons/同步到乐享/IMA（不新建）。 - 已拆分（2026-08-24）：详情从主表外置到
pitfalls/PF-NNN.md；主表改为纯索引。拆分触发阈值（>80 条或 >60KB）仅为历史背景，当前已拆分态运行。
会话操作流程
0. 启动载入（进入相关工作区时自动做）
Read ~/.workbuddy/lessons/pitfalls.md头部规则 + 索引表，统计| PF-NNN |行数得总条数；若不存在/为空，提示先创建并附格式模板。Read当前 workspace.workbuddy/memory/MEMORY.md顶部，确认 L1 指针段存在。- 首条回复简短呈现：已载入 N 条坑点（PF-001…PF-XXX） + 最近 1–3 条（日期/工作区/一句话）+ 提示「说『记坑』可追加新坑」。
1. 展示历史（指令：查坑 / 坑点库 / list）
- 解析 pitfalls.md 索引表的
| PF-NNN | ... |行（编号/日期/标签/摘要）；要读某条全文时Read对应pitfalls/PF-NNN.md详情文件。 - 支持过滤：
查坑 web-app/查坑 #git→ 按「工作区:」或「标签:」字段筛。 - 输出表格：
PF-ID | 日期 | 工作区 | 标签 | 坑(截断40字) | 关联；用户点某条则复述完整根因/解决/预防。
2. 追加新坑（指令：记坑 / 踩坑了 / add）
交互收集（能从上下文推断的字段直接填，不全问）：
- 坑(现象)、根因、解决、预防、工作区（必填，跨区检索锚点）、标签、关联。
- ① 写前查重（2026-09-17 新增，必须先于取号）：草稿落成文件后跑 --dedup-draft <草稿.md>（标题+正文双路；只定标题时可退化为 --dedup-check "候选标题"），命中「疑似重复」则禁止新建编号——是同一坑就补进主条目，根因不同才新建且标题写明差异点。详见 §7。
- ② 序号：必须跑 check_index_consistency.py --next-id 取号（输出下一个可用编号 = 三源并集最大号+1，含"仅存在于详情文件"的孤儿号）——禁止凭记忆/凭 grep 印象写号；旧法 grep 主表会漏号，2026-09-10 一天内三次撞号（PF-392）。写库脚本落盘前加 --assert-next N 作前置断言，不符即中止。
- 写入（三处缺一不可，2026-08-31 铁律，PF-249/250/252~256 曾各漏一张表）：
1. 新建详情文件 ~/.workbuddy/lessons/pitfalls/PF-NNN.md（按 §模板，字段齐全）；
2. 主表 ~/.workbuddy/lessons/pitfalls.md 追加索引行（链接 (pitfalls/PF-NNN.md)）；
3. 人类副本 ~/.workbuddy/lessons/pitfalls/INDEX.md 追加索引行（链接 (PF-NNN.md)）。
> 首选 add_pitfall.py 一步到位（取号 → 写前断言 → 落事务日志 → 写详情 → 写主表+INDEX → 自跑机检）：手工分三次写极易漏表（本条铁律就是漏出来的）。用法 add_pitfall.py --title … --tags … --desc … --body-file …，--dry-run 可先看计划。
> 事务日志 .tx_PF-NNN.json：写入前落、写完删（对三源机检不可见）。看到它残留 = 上一次写入异常退出（崩溃/被 kill/断电）→ 跑 add_pitfall.py --recover 按日志幂等补齐（判据是"成品是否就位"，重复执行安全）；写入流程启动时也会先自动处置陈旧日志（阈值 --recover-after，很新的日志视为另一写方在写、不抢）。
> 两道自愈（无人值守，2026-09-18）：写入流程取号时若发现库 FAIL，会 ① 先按日志补齐（有日志）；② 再用 check_index_consistency.py --fix 自动补「可机械推导」的残局（无日志也救得回来），然后复取号；补不动（疑似活跃写方／属需人裁定类别）即中止且零写入。排障时可用 --no-autofix 关掉 ② 观察原始状态。
> check_index_consistency.py --fix 修另一类残局（主表有行/INDEX 缺行、计数行不符），写前自动备份、静默期内拒绝介入、--dry-run 可先看计划。两者都只做「可机械推导」的修复；需人裁定的（INDEX 多余行 / 孤儿详情 / Drift / 重复行）只报不改——替人裁定或创作的自动修复比不修复更危险。
- 写完必跑三源自检脚本（详情/主表/INDEX 编号集合 + 链接格 + 行列数 + 编号唯一性 + 反向覆盖，零依赖），必须 --strict 且 exit 0 才算完成（普通模式只判 problems、告警放行；--strict 连告警也判失败，杜绝"有告警但放行"的长期漂移）：
"~/.workbuddy/binaries/python/versions/3.13.12/python.exe" "~/.workbuddy/lessons/pitfalls/check_index_consistency.py" --strict
- ⚠️ 改了两张表的表头/列数时，须同时确认三件事：① 两表各自的表头分隔行列数与行格数一致（GFM 下"行格数 > 表头列数"的多余格会被静默丢弃，实测曾致 191 行详情链接不可见）；② 格内正文的
|一律转义为\|（否则被当分隔符切开）；③ 两个自检脚本仍全绿（改机检/写入端后必跑，PF-364 纪律）。勿把用例数字写死在文档里——用例数会随加固增长，"31/31"这类硬编码计数本身就是一处会漂的声明。 - ⚠️ 不要用
Path.write_text()写库：Windows 上它会做 universal-newline 转换，改一行即把整个文件变 CRLF（机检项 ⑫ 会 FAIL，PF-391）→ 用write_bytes(text.encode("utf-8"))或newline=""。 - 发版侧另有硬门禁：
zfl-skill-governance/scripts/release_pipeline.py的 Stage 4pitfalls_integrity在每次技能发布前会用同一脚本--strict复检本库，不一致即软阻断发布（--skip-pitfalls可逃生）。故本库漂移会在下一次发布时被拦，不再靠人记得跑。 - 写入后立即在会话呈现新增条目（PF-ID + 标题），并记入会话追踪列表（见 §4）。
- 约束：不编造；工作区字段必填；按主表行号排序插入（编号不连续不乱序）。
3. 指针校验（指令：指针状态 / sync-check）
- 遍历 6 个工作区
.workbuddy/memory/MEMORY.md，grep跨工作区坑点库。 - 输出覆盖矩阵：
工作区 | 指针OK?；缺失的给出补挂原文一行。 - 6 工作区路径：
D:\<app>\{<迭代对话目录>, web-app, web_skill_src, 技能转网页测试, 平台规划, 公众号思路}。
4. 状态追踪（指令：坑点状态 / status）
- 文件态：pitfalls.md 现有 N 条、最新 PF-ID、下一个可用编号（
check_index_consistency.py --next-id）。 - 会话态：本次会话已追加（未关闭）的条目列表，避免重复写、确保随时可读（追加后回复即保留摘要，不依赖重读文件）。
- 跨指令一致：任何查/展/加操作后，若用户问「现在坑点怎么样」，先报会话态再报文件态。
5. 聚合概览（指令：概览 / overview / 坑点统计）—— 对照 AIHOT 信息架构范式
- 调用：
python scripts/aggregate_pitfalls.py [--days 30] [--top 10] [--out 概览.md]（零依赖标准库，只读pitfalls/PF-*.md详情目录）。 - 输出五块：① 总条数 / 近 N 天新增 / 本月新增（近期焦点信号）；② 工作区分布（计数即信号）；③ 标签高频 Top N（脚本层已归一：#编辑/#Edit 合并、工作区名标签丢弃）；④ 严重度分布（需条目填「严重度：」字段，未填归"未标"）；⑤ 近期焦点表（近 N 天按日期降序）。
- 三轴维度：工作区（已有枚举）× 坑类别（标签归一）× 严重度（新增可选）。脏数据在脚本层清洗，不动历史条目（向后兼容）。
- 可挂到周度 automation「跨工作区知识同步巡检」自动生成概览复盘。
6. 对账查漏（指令：对账 / 查漏 / reconcile / 漏记）—— 回应"漏记怎么补"
双写纪律 C 要求"收尾/发版/大任务结束做一次项目 MEMORY 踩坑段 vs 本库索引对账，漏则补"。本子命令把这一步半自动化：
- 调用：
python scripts/reconcile_pitfalls.py [--pitfalls PATH] [--root DIR ...] [--discover BASE ...] [--days N] [--out REPORT.md] [--json]（--days N：日log 只取近 N 天，0=全取，默认 365） - 零依赖标准库，只读不写 pitfalls.md 与各项目 MEMORY。
- 流程：① 发现各项目
.workbuddy/memory/（MEMORY.md + 日log）；② 剔除 L1 指针占位脚手架；③ 用强/弱标记词筛 footgun 叙述，剔除已带PF-xxx指针的块；④ 与坑点库详情目录pitfalls/PF-NNN.md（编号取文件名）交叉比对（规范化标签 + 别名词典）——--pitfalls传主表文件时会自动落到姊妹详情目录。 - 判定三档：
- 已覆盖 —— 命中任一 PF 工程维度（如 #Grep、发布闸门、safe-delete…），建议核对是否完全等价；
- 疑似漏记 —— 强标记（踩坑/footgun/陷阱/反模式/假阴性/假一致/静默降级/误判）且无任何维度命中，交人审；
- 建议核对 —— 弱标记（铁律/教训/坑）无维度命中，多为管理纪律/方法论，确认无通用工具陷阱则跳过。
- 反向校验：PF 的「关联」指向某项目但该项目 MEMORY 无反向 PF 指针时提示补指针。
- 查重列（2026-09-14 新增，报告「最相似(查重)」列）：对维度未命中的候选块，用字符 3-gram overlap 系数（
|A∩B|/min(|A|,|B|)，不用 Jaccard——候选块几十字 vs PF 详情数百字，Jaccard 会被长度差压平而失效）给出最相似已有 PF 编号+分数（阈值 0.12，取 top2）。判"疑似漏记"前必看此列：维度是粗粒度标签、词面不同就会漏匹配，直接按缺号补 PF 会造成重复入库。实测标尺：真重复 PF-304=0.67、PF-315=0.13（两条均经人工确认当天已入库），噪音次名 ≤0.15。 - 已否决项：对「已覆盖」也做反向查重（2026-09-14 实测否决，PF-411，勿重复立项）：曾计划"已覆盖候选相似度低 ⇒ 可能其实是新坑被误判"，实测两组分布几近重叠（已覆盖 n=120 中位 0.15 / 未命中 n=10 中位 0.15），该分数对两类无区分力，卡 0.20 会把 73% 的正常条目误报为"弱覆盖"。源码中已留注释防线。
- 输出 md 报告（摘要+候选明细表+建议动作）+ 可选
--json（便于挂 automation 消费）。
最终判断权在人：脚本只"揪候选 + 标维度命中"，不自动写 pitfalls。疑似漏记确认为通用 footgun 后，按 §2 模板补 PF 并回写项目指针（双写）。
可挂进周度 automation「跨工作区知识同步巡检」作为收尾对账环节（与 §5 概览并列）。
7. 写前查重（指令：查重 / dedup / 重复了吗）—— 2026-09-17 新增，09-18 加正文级
推荐用法（一次做双路）：把草稿写成文件（首行标题、其余正文），然后
python ~/.workbuddy/lessons/pitfalls/check_index_consistency.py --dedup-draft <草稿.md>
| 入口 | 用途 |
|---|---|
--dedup-check "标题" |
只查标题（旧用法，仍可用） |
--dedup-draft <file> |
推荐：草稿文件 → 标题 + 正文双路查重 |
--dedup-body-file <file> |
只补正文（与 --dedup-check 配合） |
--dedup-body "文本" |
内联正文（有 shell 转义风险，见 PF-405，优先用文件） |
- 标题路：中文 bigram + 英文 token 去泛词，
0.5×Jaccard + 0.5×Containment，阈值 0.34。 - 正文路（2026-09-18）：sublinear tf-idf 余弦，阈值 0.15（
--dedup-body-threshold）。
标定：9 对已知重复 / 8 对同族负样本 / 3000 随机对 → 召回 5/9（纯标题仅 2/9），随机误报 0.033%。
已证伪两条路，勿重试：纯词袋 jac/cont/cos 对长正文无效（正样本中位 0.09 ≈ 随机 p99 0.067）；句级 top3 更糟（随机 p99 = 0.778）。 - 任一路命中即
exit 1拦截；都无高相似 →exit 0放行。正文语料构建约 1.2s。 - 与 §6 对账查重列的区别（勿混用）：
- 本指令 = 标题 vs 标题（长度相当）→ 可用 Jaccard 加权；
- §6 对账列 = 候选块（几十字）vs PF 详情全文（数百字） → 只能用 overlap，Jaccard 被长度差压平（PF-411 已实证否决）。
- 族谱：
~/.workbuddy/lessons/pitfalls/CLUSTERS.md—— 已归并 7 组 15 条 / 同族 24 族 91 条 / 误报 4 例 + 漏报 1 例。判"疑似重复"后先查它，能少读一轮详情。 - 合并判据：根因 + 解法是否同一，不是标题是否像。同族（根因不同）禁止合并——合并即丢信息。
- 归并采取软合并：从条目加「已归并至 PF-xxx」、主条目加「## 归并来源」、索引两表摘要加
⟲→PF-xxx；编号不回收、不重排（外部引用不断裂）。
8. 季度收敛 SOP（指令：收敛 / 整库去重 / converge）—— 整库重复扫描 + 聚类刷新
触发：库规模越过记忆容量后必然出现"换个说法重复入库"（PF-471），或每季度 / 每次批量写库后。本流程把"整库扫一遍、该合的合、该归族的归族、门禁刷新"固化下来，避免每次重新发明。
> 先备份再动：cp pitfalls/PF-*.md _bak_converge_YYYYMMDD/ + 备份 pitfalls.md/INDEX.md。任一改动都可从备份回滚。
- 全量扫重复候选：用关键词倒排 / bigram 相似度建候选对（参考
pf_dedup_scan.py思路）。阈值宁高勿低——多报人工读一遍优于漏报；候选对先按"共享关键词数"降序，高分组必读原文。 - 逐对核原文裁定（核心，不可跳）：读每条「根因 / 正解」段，判三类：
- 硬重复（根因+解法同一）→ 软合并（见 §7 软合并三处：从条目标「已归并至」+ 主条目加「## 归并来源」+ 索引两表摘要加⟲→PF-xxx）；
- 同族（根因不同）→ 只加标签、不合并（合并即丢信息；PF-194/230 同叫"门禁漂移"但根因无关，是误报）；
- 误报 → 记入 CLUSTERS.md 第三节"勿合并"判据，防下次重判。 - 刷新族谱
CLUSTERS.md：补锚点 + 反向「同族成员」段 +#PF-xxx同族标签；跑python pitfalls/check_clusters.py（校验：各族声明条数 vs 实际成员 / 引用编号是否存在于库 / 编号是否跨族重复登记），数字错用--fix-counts自动修。语义层（谁是重复、谁是同族）只能人工判，机检只管计数与引用。 - 新门禁须先标定（纪律，见 PF-475）：凡相似度 / 阈值类判据，上线前用已知正样本测召回，勿直接拍阈值交付——"能跑通不报错" ≠ "有效"。本次正文查重标定结论：纯词袋与句级匹配对长正文已证伪（正样本分数 ≈ 随机），采用 sublinear tf-idf 余弦（阈值 0.15，召回 5/9）。
- 全部门禁复跑（改完必跑，全绿才算完）：
bash "<PY>" "~/.workbuddy/lessons/pitfalls/check_index_consistency.py" --strict "<PY>" "~/.workbuddy/lessons/pitfalls/check_clusters.py" "<PY>" "~/.workbuddy/lessons/pitfalls/self_test_negative.py" "<PY>" "~/.workbuddy/lessons/pitfalls/self_test_add_pitfall.py"
（<PY>= 托管 Python 绝对路径；机检改过必跑负向自测，PF-364 纪律。） - 升版：技能六源升版 + 跑
five_source_check.py <skill_dir>校验（勿只改顶层version:漏内嵌metadata.version，那次是假绿；PF-301）。
写库铁律回顾：用 write_bytes(text.encode("utf-8")) 或 newline=""，勿 Path.write_text()（Windows 会整片转 CRLF，且防 CRLF 的 corrective 会反向转 LF——行尾污染双向，PF-474）。
约束
- 追加前必
Readpitfalls.md（Edit 前置）；插入位置正确（注释前）。 - 用户级目录写入，跨 workspace 共享，勿改路径、勿删条目。
- 不替各 workspace 编造详细内容；只挂指针、只记真实坑。
- 本技能只追加不删，与 safe-delete 删除钩子禁区无交集。
关联
zfl-sync-suite（云端同步）、周度 automation跨工作区知识同步巡检（id=automation-1786246143799，每周一复习+查漏）。- 对账脚本
scripts/reconcile_pitfalls.py（§6），概览脚本scripts/aggregate_pitfalls.py（§5）。 - 本库一致性机检：
lessons/pitfalls/check_index_consistency.py（三源 + 链接 + 行列数 + 编号唯一性 + 反向覆盖 + 行尾风格；--strict供硬门禁；--next-id取号 /--assert-next N写前断言 /--fix修可机械推导的中断残局）。负向自测lessons/pitfalls/self_test_negative.py（含缺陷注入/豁免 + 正文级查重 +--fix修复与边界，改机检后必跑）。 - 写入端：
lessons/pitfalls/add_pitfall.py（一步到位写三源；事务日志 + 原子替换 + 启动自愈；--recover补残局 /--dry-run看计划 /--base指定库根供测试）。崩溃恢复自测lessons/pitfalls/self_test_add_pitfall.py（故障注入真的把进程崩在每一步，逐例验证能站起来；改写入端后必跑）。 - 族谱机检：
lessons/pitfalls/check_clusters.py（校验CLUSTERS.md：各族声明条数 vs 实际成员、引用编号是否存在于库、编号是否跨族重复登记；--fix-counts自动修数字）。任何改族谱（加成员/建新族/归并）的动作后必跑——手填计数随增删漂移是复发过的坑（PF-194 同构）。 - 族谱文件：
lessons/pitfalls/CLUSTERS.md（一、已归并 7 组；二、同族 24 族 91 条；三、查重误报观察；四、维护约定）。语义判定人工做，计数引用靠上面脚本。改此文件用编辑工具，勿用 shell 内联写（反引号会被命令替换吞掉，PF-405）。 - 发版侧门禁：
zfl-skill-governance/scripts/release_pipeline.pyStage 4pitfalls_integrity（发布前--strict复检本库，不一致软阻断）。 - 完整设计与切换清单见
~/.workbuddy/lessons/跨工作区知识共享方案.md。
