用已知问题家族图谱做 bug 分类核验（Family Triage）

适用：想给 dsh 社区做贡献的任何人——遇到新 bug 帖时，先查家族图谱再开口。本文的图谱与方法均来自 2026-08-19 的实测运营（30+ 条核验回复沉淀）。

1. 为什么要"家族化"

dsh 讨论区里，同一个根因往往散在多帖：用户环境不同、症状不同、帖主互相不知道对方的存在。三个坏处：

• 维护者要跨帖拼图才知道问题的真实影响面；
• 每个新帖都从零解释一遍，浪费所有人的时间；
• 修复时只修了"这一帖"，没堵住"这一类"。

家族化就是把散帖按根因归并：新帖先对照家族，命中就引用根因帖 + 补增量证据，而不是重新开一个平行宇宙。

2. 家族图谱是什么

dsh-ecosystem/docs/bug-families.md（已知问题家族图谱）目前收录 13 个已核验家族，每个家族包含：

字段	含义
触发模型	什么情况下会中招
代表帖	该家族的 canonical 帖子编号
已验证根因	官方源码 file:line，直接可查
修复建议	最小补丁 + 回归测试惯例
状态	官方是否已修

13 个家族一览：

1. npm dist-tag 发布族（#2763：latest 卡 0.0.1-rc.1，160/325 插件被命中）

2. %TEMP% 清理族（#1961/#3190/#3203：运行期私有目录被删 → 崩溃或 fail-closed）

3. 坏工件隔离族（#675/#1047/#3173：一个坏文件拖垮列表/启动）

4. 模块双实例符号分裂族（#1697/#2660/#3033：undefined.prepare 全家桶）

5. 推理字段别名族（#199：vLLM 发 delta.reasoning，adapter 只读 reasoning_content）

6. Windows 令牌/ACL 沙箱族（#3207/#3216/#3195）

7. 远程部署信任边界族（#3209/#3210/#3211）

8. 插件加载/回滚族（#3173/#3213）

9. 检索/渲染/元数据族（#3202/#3206/#3177/#3111）

10. 工具结果可信度族（#3182：ok 字段不可信、归档≠删除）

11. out-of-tree 会话事件信封族（#3191/#1538/#1584/#1619/#2778：ignorable 写侧缺口，读侧已就绪，实现已验证）

12. sandbox 同模式升级误报族（#3219：full-access 请求 full-access 报 not strictly wider，补丁分支就绪）

13. 无约束执行面绕过沙箱族（#3245：run_code worker-thread 无文件效应约束 → 沙箱逃逸，fail-closed 补丁就绪）

3. 命中家族后怎么做

1. 引用根因帖编号，别重复贴分析——"这与 #2660 同根因（双实例 symbol 分裂）"；

2. 补增量证据：新环境（macOS/WSL/Windows 10 vs 11）、新触发路径、新字段名、新测量数据；

3. 给出与你环境匹配的最小复现（命令 + 期望/实际），让维护者能直接验证；

4. 如果有新修复角度才写建议；只是又一个 me too 就一句"复现 +1 + 环境"足够。

示例（#3033 的贡献方式）：帖主在 macOS 上装 dsh-computer-use 后复现 undefined.prepare，argszero 把它挂到 #2660 家族并指出"触发模型扩展为任何第二物理副本"——这就是标准的家族贡献：一次增量，全家族受益。

4. 没命中家族怎么办

先按 zh-25 的核验三件套确认是真 bug：

git clone --depth 1 https://github.com/deepseek-ai/deepseek-harness work/src   # 浅克隆
git log -1 --format="%H"                                                       # 记录核验基线
node work/dsh-ecosystem/scripts/verify-citation.mjs <repo> <file:line>         # 行号校验

确认后：新根因 = 新家族。在自己的回复里给出 file:line 证据，然后把图谱加一个新条目（README 指引见图谱文件头）。图谱是活的，靠社区回填。

5. 家族修复的测试惯例

每个家族都有配套的回归测试形状，别用孤立单测糊弄：

家族	测试惯例
坏工件隔离	[valid, bad, valid] 三段流：坏记录不吞合法记录、不被当作最新覆盖
%TEMP% 清理	删除运行期目录后下一次调用自动重建（provider 侧），runner 边界仍 fail-loud
符号分裂	双副本加载 → 调度器同一实例；孤儿 tool_calls 不再回放成 400
推理别名	三测试：别名接收 / 官方字段优先 / reasoning-only 不再映射 EMPTY_RESPONSE
Windows 令牌	curl.exe 回归（沙箱内 TLS 握手成功）+ 事件日志定位被拒对象

6. 我们的实测案例

• #199 → 家族 5：两帖（DiGuStudent / dietmarscharf）各自报 vLLM 推理字段被丢。核验 translate.ts:132 后把"EMPTY_RESPONSE → retry-policy 重试风暴"机械链补齐，建议两份分支合并成一个 PR——两帖合成一份维护者可直接用的 PR 描述。
• #3182 → 家族 9/10：帖主五发现里，归档≠删除、ok 字段不可信、node_modules 被扫分别命中"工具结果可信度"与"检索语义不一致"，用 file:line 逐条确认后回帖。
• #2011 → 图谱外新条目：host.describe 硬编码 0.0.1（api-proxy.ts:2863-2868）是新根因，回复里给了契约对照与修复路径，后续可回填图谱。

7. 一句话总结

先查图谱，命中挂增量，未命中立新族——社区贡献不是比谁回复多，而是让每个新帖都朝"维护者能一次修完一类"的方向移动。