claude-mem 问题分诊实战：重复 Issue 关闭与根因分类工作流（Phase 01）

本文为 claude-mem 项目 2026-03-29 问题分诊（Issues Triage）系列的第一阶段（Phase 01）技术指南，完整还原了如何用 gh CLI 对 GitHub issue 积压进行"零代码改动"的即时清理：创建 10 个根因分类标签、以带解释性评论的方式关闭 18 个重复/模糊/过期 issue、将剩余开放 issue 按根因分组打标，并产出结构化分诊报告。读完本文，你可以掌握一套可直接复用于其他开源仓库的 issue 分诊方法论，并理解 claude-mem 最被集中报告的 __dirname 打包缺陷的仓库内源码证据。

一、阶段定位：只做 gh 操作，不改一行代码

本阶段对应的 playbook 位于 Phase-01-Close-Duplicates-And-Stale-Issues.md，目标是清理 claude-mem（thedotmack/claude-mem）的 issue 积压。阶段设计上有两个关键约束：

1. 不改代码：本阶段只允许对 GitHub API 执行 gh CLI 操作。所有代码级修复留给后续的 Phase 02～07；
2. 关单必须带解释性评论：每个被关闭的 issue 都要附上一句可操作的关闭理由（重复于哪个 issue、缺什么信息、为何过期），并保留"如问题仍存在请重新打开"的出口，避免把真实 bug 误杀。

阶段完成后的整体效果：分诊前共 112 个 issue，关闭 18 个（8 个重复、7 个模糊、3 个过期），剩余 94 个开放 issue 全部按 9 个根因标签归类（另有约 15 个 feature request/杂项保留原有 enhancement 标签，不打根因标签）。

二、创建 10 个根因分类标签

第一步是在仓库上建立统一的根因标签体系。操作前先执行 gh label list 检查是否已存在，已存在的跳过，缺失的逐个执行 gh label create 补建：

标签	颜色	覆盖范围
root:worker-lifecycle	#d73a4a	Worker 启动、关停、僵尸进程
root:windows	#0075ca	Windows 平台特定缺陷
root:chromadb	#7057ff	ChromaDB/MCP 子进程问题
root:project-scoping	#008672	项目身份、隔离、命名空间冲突
root:session-integrity	#e4e669	会话数据、pending 队列、finalization
root:security	#b60205	安全漏洞
root:installer	#fbca04	安装、setup、marketplace 路径问题
root:mcp-schema	#1d76db	MCP 工具注册、schema 问题
root:aws-bedrock	#5319e7	AWS Bedrock 集成
triage:closable	#cccccc	标记为分诊期间可关闭

这套标签不是随意命名的，它直接对应了后续 6 个代码修复阶段各自要攻克的根因域——分诊阶段打上的标签，就是后续修复阶段的"任务清单索引"。

三、关闭重复 issue：以 #1410 为规范的 __dirname 簇

本批次中规模最大的一组重复 issue 是 6 个 __dirname 硬编码问题，统一保留 #1410 作为规范（canonical）issue，其余 6 个（#1419、#1428、#1433、#1434、#1437、#1438）逐个执行：

gh issue close <NUMBER> -R thedotmack/claude-mem \
  -c "Closing as duplicate of #1410. All 7 reports trace to the same root cause: hardcoded __dirname in the esbuild bundle output (worker-service.cjs). Fix will be tracked in #1410."

随后为 #1410 追加 root:worker-lifecycle 标签，让规范 issue 直接挂上根因分类。

这个根因在仓库里可以追溯到确凿的源码证据：esbuild 在把 src/services/worker-service.ts 等源码打包为 plugin/scripts/worker-service.cjs 这类 CJS 产物时，若构建机器的绝对路径被内联进 __dirname，最终用户机器上的 worker 就会去找开发者本地的 mcp-server.cjs 路径，导致 worker 无法初始化、数据库初始化失败等一系列表现各异的报错——这正是 7 份报告措辞不同却同根同源的机制。仓库中 scripts/build-hooks.js 体现了两层防御：

• 构建后剥离产物中被内联的硬编码 __dirname/__filename 路径（scripts/build-hooks.js#L41）；
• 通过 banner 注入运行时 polyfill，让 __dirname 在运行期基于 process.argv[1] 重新解析而不是依赖构建时冻结的值（scripts/build-hooks.js#L360-L362）。打包产物 plugin/scripts/worker-service.cjs 首行即可看到该 polyfill 的落地形态（var __dirname = __dirname || require("node:path").dirname(__filename);）。

另外还关闭了两对小型重复：

# 安装类重复：#1396 重复于 #1340（同一缺失 scripts/setup.sh 问题）
gh issue close 1396 -R thedotmack/claude-mem \
  -c "Duplicate of #1340 — both report the same missing scripts/setup.sh issue."
# 为 #1340 追加 root:installer 标签

# 安全类重复：#1521 重复于 #1285（GitHub Actions 工作流命令注入）
gh issue close 1521 -R thedotmack/claude-mem \
  -c "Duplicate of #1285 — both report command injection in GitHub Actions workflow."
# 为 #1285 追加 root:security 标签

四、关闭模糊与不可执行 issue

以下 7 个 issue 因缺少复现步骤、错误日志或版本信息而无法定位，全部以礼貌性解释评论关闭，并明确告知"补充信息后可重新打开"：

Issue	标题	关闭评论（英文原文）
#1492	"Bug Report"	Closing: this issue has only a generic title with no reproduction steps, error logs, or version info. Please reopen with specific details if the issue persists.
#1436	"bug"	Closing: no description, steps to reproduce, or error output provided. Please reopen with details if still relevant.
#1362	（中文，无复现步骤）	Closing: unable to action without reproduction steps or error details. If you can provide steps to reproduce (in any language), please reopen.
#1385	"mem still not save"	Closing: insufficient details to diagnose. If you can share your OS, claude-mem version, and error logs, please reopen a new issue.
#1488	"Consumed 25% of my tokens"	Closing: this appears to be a usage concern rather than a bug. Token consumption depends on context window size and session length. If you believe there is a specific bug causing excessive token usage, please open a new issue with reproduction steps.
#1459	"Featured in awesome-claude-code-workflows"	Closing: this is a community celebration rather than an actionable issue. Thank you for the recognition! 🎉
#1378	"Test failure: test run failed"	Closing: no test output, stack trace, or version info provided. This may have been fixed in later releases. Please reopen with details if still occurring.

值得注意的是 #1362 的处理方式：语言不构成关闭理由，"任何语言，只要给出复现步骤即可重开"的措辞避免了国际化协作中的沟通摩擦；而 #1488 则示范了如何把"使用方式疑问"与"产品缺陷"区分开——token 消耗量取决于上下文窗口大小与会话长度，这类反馈应引导到用法讨论而非 bug 跟踪流。

五、关闭已修复与被取代的 issue

3 个 issue 属于"时间性失效"，逐一带理由关闭：

# #1268：回归问题已在后续版本修复
gh issue close 1268 -R thedotmack/claude-mem \
  -c "This regression appears to have been fixed in subsequent releases (10.6.x+). If you're still experiencing this on the latest version, please reopen with your version number and error details."

# #1137：被范围更完整的 #1262 取代
gh issue close 1137 -R thedotmack/claude-mem \
  -c "Superseded by #1262 which covers the broader plan mode pending messages issue. Closing to consolidate tracking."

# #1219：版本升级请求（10.4.1）早已过期
gh issue close 1219 -R thedotmack/claude-mem \
  -c "This version has long since been superseded. The current version is well past 10.4.1. Closing as stale."

这里的判断依据是仓库版本线：当 playbook 中所有 issue 标题普遍指向 10.5.x / 10.6.x 时，一个要求"bump 到 10.4.1"的 issue 显然已失去时效。

六、为全部剩余开放 issue 打根因标签

关闭动作完成后，对剩余开放 issue 逐条打根因标签。标准操作流是：

# 1. 先拉取当前开放列表（最多 200 条）
gh issue list -R thedotmack/claude-mem --state open --limit 200 --json number,title,labels
# 2. 逐条追加标签
gh issue edit <NUMBER> -R thedotmack/claude-mem --add-label <LABEL>

各分组的判定规则（关键词即归类依据）：

• root:worker-lifecycle：#1410，以及凡提及 worker 启动失败、冷启动、僵尸进程、版本不匹配、daemon spawn、"worker not running"、ECONNREFUSED、端口绑定、健康检查失败或 ensureWorkerRunning 的 issue。这一函数真实存在于 src/shared/worker-utils.ts#L454，是 hook 侧探测/拉起 worker 的入口；
• root:windows：提及 Windows、PowerShell、CRLF、win32、Windows 僵尸 socket、.exe、taskkill 或 Windows Terminal 的 issue；
• root:chromadb：提及 ChromaDB、chroma-mcp、uvx、向量检索失败、chroma CPU 空转或 embedding 错误的 issue；
• root:project-scoping：提及项目名冲突、basename、monorepo 隔离、工作区数据串扰（workspace bleed）或"取到错误项目数据"的 issue；
• root:session-integrity：提及过早 finalization、observation 重复、空 summary、pending 队列膨胀或数据丢失的 issue；
• root:security：#1285、#1204，以及提及命令注入、文件写入漏洞、端口冲突导致数据泄漏、权限绕过的 issue；
• root:installer：#1340，以及提及 setup、install、marketplace 路径、allowlist、plugin.json、MCP 注册失败的 issue；
• root:mcp-schema：提及空 inputSchema、MCP 工具 ID 不匹配或 SSE 广播的 issue；
• root:aws-bedrock：提及 Bedrock、AWS SDK 或 Bedrock 环境变量的 issue。

两条归类纪律：

1. 多标签允许：同时命中多个分类的 issue 应打多个标签。例如 #1489（windows+chromadb）、#1225（windows+chromadb）、#1234（worker-lifecycle+session-integrity）；
2. feature request 保留原标签：若已有 enhancement 标签则保留，不强行套根因标签。

实际执行结果为 9 个根因组共约 76 次标签应用（worker-lifecycle 21、windows 13、chromadb 9、session-integrity 13、project-scoping 6、installer 7、security 4、mcp-schema 4、aws-bedrock 2），另有约 16 个 feature request/杂项保留无根因标签状态。

七、生成结构化分诊报告

playbook 要求最终产出一份带 YAML front matter 的 Markdown 报告（写入 Working/triage-report.md，仓库内即 Working/triage-report.md）：

---
type: report
title: "Issues Triage Report — 2026-03-29"
created: 2026-03-29
tags:
  - triage
  - issues
  - claude-mem
---

报告必须包含五部分：

1. 分诊前后总量对比（含关闭数量）：分诊前 112，关闭 18（8 重复 + 7 模糊 + 3 过期），剩余 94；
2. 已关闭 issue 表格：编号、标题、关闭原因（duplicate/stale/vague）；
3. 剩余开放 issue 表格：按根因标签分组，每条列出编号、标题与优先级；
4. 优先级判定标准：
   • P0 = 阻塞全体用户，或安全漏洞；
   • P1 = 影响大批用户群体；
   • P2 = 锦上添花或单一用户报告；
5. Next Steps：列出后续 6 个修复阶段及简述。

实际产出报告的核对数据：优先级分布为 P0 × 15、P1 × 54、P2 × 25，合计 94。其中 P0 清单高度聚焦，包括 __dirname 硬编码（#1410）、版本不匹配导致的无限重启循环（#1435）、冷启动 hook 竞态（#1505）、WSL/WSL2 下 worker 直接退出（#1420）、pending 队列无界增长导致 CPU 100%（#1262、#1269）、chroma-mcp 无限空转 250~360% CPU（#1248），以及 5 个安全 P0：watch.context.path 可写入任意路径（#1204）、worker 端口冲突跨账户数据泄漏（#1255）、GitHub Actions 命令注入（#1285）、子代理绕过用户权限设置（#1493）、全量安全审计（#1251）。

多标签 issue 在报告中有专表登记，例如：

#	标签组合
#1420	root:worker-lifecycle, root:windows
#1399 / #1392	root:worker-lifecycle, root:windows
#1489 / #1225	root:windows, root:chromadb
#1342	root:windows, root:mcp-schema
#1269 / #1234	root:worker-lifecycle, root:session-integrity

这类跨域 issue（如 #1420 "worker-service.cjs 在 WSL 下直接退出"）正是必须先完成根因归类、再谈修复排期的原因——它同时阻塞 worker 生命周期和 Windows 平台两条修复线。

八、报告如何驱动后续修复阶段

分诊报告的 Next Steps 部分把 94 个开放 issue 直接映射到 6 个代码修复阶段（同目录下的 Phase-02～Phase-07 playbook）：

1. Phase 02：修复 __dirname 与 worker 启动——替换 esbuild 产物中硬编码的 __dirname，为冷启动 worker 初始化加入重试循环，用原子重启锁文件防止"启动踩踏"，并输出结构化失败诊断。从 Phase-02 playbook 的完成记录看，其做法是在 scripts/build-hooks.js 的三处 CJS esbuild 配置中显式加入 define: { '__dirname': '__dirname', '__filename': '__filename' } 作为防御，并在 ensureWorkerRunning() 中实现预算感知的重试（最多 3 次、1 秒间隔），且以 0 处硬编码 /Users/ 路径、13/13 新测试通过验收；
2. Phase 03：Windows 平台加固——hook 超时/挂起、僵尸端口时序、PowerShell 转义工具、CRLF .gitattributes、WQL 进程枚举边界、isProcessAlive() 工具；
3. Phase 04：ChromaDB 子进程生命周期——60 秒健康监控、CPU 空转检测、进程组 kill、chromaPid 写入 worker.pid、chromaAvailable 标志与 SQLite 优雅降级；
4. Phase 05：项目作用域与会话完整性——项目身份统一为 parent/basename 口径、migrateProjectNames()（legacy/ 前缀）、过早 finalization 防护、会话级去重唯一索引、队列大小限制；
5. Phase 06：安全修复——GitHub Actions env 块注入、isPathSafe() 白名单工具、端口冲突项目身份告警、hook 输入校验审计；
6. Phase 07：安装器、MCP 与剩余修复——setup.sh/smart-install.js 对齐、MCP 工具显式 property schema、AWS Bedrock 环境透传、安装幂等性、SSE 心跳/清理，以及带 commit 引用的 issue 评论回填。

九、可复用的分诊要点总结

从这套 Phase 01 工作流中，可以提炼出对任意开源仓库都有参考价值的四条纪律：

1. 先建标签体系，再动 issue：根因标签的粒度应贴合后续修复阶段的划分，使"分类"和"排期"共用同一套词汇；
2. 关单必留痕：关闭评论要写明根因归属（重复于谁/缺什么/被谁取代），并给出明确的重新打开条件，让 issue 生命周期对贡献者透明；
3. 模糊 issue 不是敌人，信息缺失才是：对无复现步骤的 issue 用"补充 OS、版本、错误日志后可重开"的标准话术，兼顾清理效率与用户体感；
4. 分诊报告是交接物：前后数量对比、分组表格、P0/P1/P2 标准、下一步阶段清单四要素齐全，后续阶段的执行者（人或 Agent）无需回翻任何 issue 即可开工。

对 claude-mem 本身而言，这次分诊把 112 个混杂 issue 收敛为"94 个已按根因索引的开放 issue + 18 条带理由的关闭记录"，直接支撑了此后 6 个修复阶段按 worker 生命周期 → Windows → ChromaDB → 项目/会话完整性 → 安全 → 安装/MCP 的顺序推进。