claude-mem Phase 01 Triage 报告：15 个 PR 的批量评审、合并与回归验证全流程复盘

本文基于 claude-mem 仓库中存档的 Phase 01 Triage 报告（phase-01-triage-report.md），完整复盘一轮面向 Issues/PRs 的集中清理行动：15 个 PR 分 5 个批次评审、14 个合并、16 个 Issue 关闭，并以 1135 个测试全部通过作为收尾验证。读完本文，你将掌握一套可复用的「按批次分层的 PR 合并策略」——从数据正确性缺陷、Hook 生命周期修复到功能型 PR 的质量门槛，以及如何处理合并冲突跳过、死代码返工这两类典型情况。

一、Triage 目标与整体结果

本次 Phase 01 的定位在配套 playbook TRIAGE-01-PR-Review-And-Merge.md 中写得很明确：优先处理「已经有对应 PR 等待评审」的存量 Issue，因为这是单次收益最高的清理——每一个合并都能用已写好的代码关掉 1~3 个 Issue。

整体结果如下（源自 triage 报告 Summary）：

• 评审 15 个 PR，分 5 个批次
• 14 个 PR 合并，1 个因被取代而关闭
• 16 个 Issue 关闭（6 个重复项 + 10 个由合并 PR 解决）
• 3 个 PR 跳过（合并冲突，需要 rebase）
• 1 个 PR 标记返工（存在死代码、未接入运行时）
• 测试套件验证通过：1135 通过、3 跳过、0 失败

值得注意的是批次划分本身就是方法论：批次不是按时间或 PR 号切分的，而是按「缺陷影响面」分层——先修数据正确性，再修生命周期，然后数据完整性与基础设施，接着独立修复，最后才是功能型 PR。这一顺序保证了后续批次的合并冲突面尽量小，也保证了核心数据路径先于外围功能稳定下来。

二、Triage 工作流：评审、合并与收尾

playbook 规定了统一的执行流程，每个 PR 的处理步骤一致：

1. 用 gh pr diff <number> 阅读完整 diff，检查是否存在明显问题；
2. 无问题则以 gh pr merge <number> --squash --delete-branch 合并；
3. 若合并失败（冲突），跳过并在报告中记录，留给后续 rebase；
4. 重复 Issue 在合并前先行关闭：对每个重复对，用带交叉引用说明的评论关闭第二个 Issue（指向保留的那个，即带跟踪 PR 的那个）；
5. 全部合并完成后执行收尾验证：

git checkout main && git pull
npm test                          # 全部测试必须通过
npm run build-and-sync            # 构建必须成功

playbook 对失败的处理原则值得注意：测试失败时不执行回滚，只记录哪个测试坏了、哪个 PR 最可能引入回归，写进 triage 报告。这把「验证」与「回滚决策」解耦，避免批量合并场景下反复 revert 造成的额外冲突。

最终验证结果为：1135 个测试通过、3 个跳过、0 失败，覆盖 66 个测试文件（耗时 19.48 秒）；构建成功生成全部产物（worker-service.cjs、mcp-server.cjs、context-generator.cjs、smart-install.js、viewer.html、viewer-bundle.js），并同步到 marketplace。

三、批次 1：数据正确性（Critical Bug Fixes）

第一批修复的是会直接污染记忆数据的路径，全部 MERGED：

PR	标题	修复 Issue	状态
#1345	阻止 LLM 在 summary 响应中使用 <observation> 标签	#1312	MERGED
#1344	DATA_DIR 解析遵循环境变量与 settings.json	#1303	MERGED
#1343	Chroma 搜索路径遵循 dateStart/dateEnd 过滤器	#1324	MERGED
#1337	smart-install.js 输出符合 Hook 契约的合法 JSON	#1253	MERGED
#1336	Chroma 禁用时对 getChromaSync() 做空值保护	#1294	MERGED

DATA_DIR 解析：两级 fallback 的落地

#1344 修复的 Issue 是「paths.ts 忽略 settings.json 和环境变量解析 DATA_DIR」。对照当前仓库的 src/shared/paths.ts 可以看到修复后的 resolveDataDir() 实现了清晰的优先级链：

export function resolveDataDir(): string {
  // 第一优先级：环境变量 CLAUDE_MEM_DATA_DIR（支持 ~ 展开）
  if (process.env.CLAUDE_MEM_DATA_DIR) {
    return expandHome(process.env.CLAUDE_MEM_DATA_DIR);
  }
  // 第二优先级：默认目录下 settings.json 中的 CLAUDE_MEM_DATA_DIR
  // （兼容 env 子对象或顶层两种写法；文件缺失/损坏时静默降级）
  // 第三优先级：默认目录 ~/.claude-mem
}

该函数还通过 expandHome 展开用户手写的 ~ 前缀——注释中解释了原因：程序化传给 existsSync/posix_spawn 的 ~ 不会被 shell 展开，会带着字面量到达系统调用并报 ENOENT。DATA_DIR 随后派生出 DB_PATH、日志目录、observer 会话目录等全部存储位置，因此这个解析逻辑的正确性直接影响所有数据的落盘位置。

Chroma 搜索的时间过滤

#1343 让 MCP 搜索路径遵循 dateStart/dateEnd。当前源码中该参数贯穿搜索链路，见 SearchManager.ts 与 SearchOrchestrator.ts——Chroma 向量路径与 SQLite 路径都必须应用同一时间窗口，否则搜索结果会出现「一条路径带过滤、另一条不带」的口径分裂。

getChromaSync() 的空值契约

#1336 的空值保护对应 DatabaseManager.ts 的接口签名：

getChromaSync(): ChromaSync | null {
  return this.chromaSync;
}

返回类型显式标注为 ChromaSync | null：当 Chroma 被禁用时该句柄为 null，任何调用方（worker 内路由、SyncApply.ts、ResponseProcessor.ts 等）都必须在解引用前判空。这正是 Issue #1294 崩溃的根因——调用方默认了非空假设。

四、批次 2：生命周期与 Hook 修复

PR	标题	修复 Issue	状态
#1330	session-complete 从 Stop 迁移到 SessionEnd Hook	#1314	MERGED
#1325	阻止僵尸子进程累积	#1226、#1296	MERGED
#1291	从 Stop Hook 输出中移除未识别字段	#1288、#1290	MERGED
#1326	worktree 会话优雅处理缺失的 transcript 文件	#1234、#1235	MERGED
#1264	旧版 worktree transcript 修复（被 #1326 取代）	—	CLOSED (superseded)

这批修复集中在 claude-mem 的 Hook 层（Hook 配置见 plugin/hooks/hooks.json），三个代表性问题的机理：

• Stop 与 SessionEnd 的职责错位（#1330）：Issue #1314 描述 session-complete 逻辑放在 Stop Hook 中会「杀死 SDK agent」。从 hooks.json 的结构看，SessionStart/Stop/SessionEnd 是并列的 Hook 事件，summary 生成与 agent 回收应发生在会话真正结束的 SessionEnd 时机，而非仍可能被复用的 Stop 时机。
• 僵尸子进程（#1325）：worker 进程树中的 subagent 进程从未被终止，导致进程泄漏（#1226）及其衍生问题（#1296 被作为重复项关闭）。
• Hook 输出契约（#1291）：Stop Hook 输出中携带未识别字段，既触发 JSON 校验失败（#1290），其中的 {"continue":true} 又导致无限循环（#1288）——一个字段错误同时造成两个 Issue，这正是重复项关闭表中这两条被合并处理的原因。

#1264 的关闭体现了「superseded」处理规范：#1326 包含相同的优雅处理逻辑，并额外增加了 worktree 路径解析，因此旧 PR 整体关闭而非部分合并。

五、批次 3：数据完整性与基础设施

PR	标题	修复 Issue	状态
#1315	project filter 激活时包含 SSE 实时数据	#1313	MERGED
#1308	自动修复跨版本同步导致的畸形数据库 schema	#1307	MERGED
#1302	批量 observation 存储方法引入内容哈希去重	#1260	MERGED
#1301	加固 Hook fallback 与 MCP node 解析	#1242、#1289	SKIPPED（合并冲突，需 rebase）

其中内容哈希去重（#1302）直接对应 SessionStore.ts 中批量 observation 写入路径：并发 Hook 触发会让同一条 observation 走多次入队，只有以内容哈希为准的幂等去重才能保证最终存储的唯一性。对应 Issue #1260 在剩余列表中仍标注「PR #1302 merged, may need verification」，说明合并完成不等于验证完成——这一状态标注本身是 triage 报告诚实性的体现。

#1301 是本阶段第一个被跳过的 PR：代码本身没有质量问题，但前面批次合并后产生了冲突，正确动作是记录「needs rebase」而不是强行解决冲突引入回归。

六、批次 4：独立修复 PR

PR	标题	修复 Issue	状态
#1341	合并 SessionStart Hook 为顺序执行	#1346	MERGED
#1334	阻止 FK 约束错误引发的无限重启循环	—	MERGED
#1306	Cursor 运行 Hook 时处理缺失的 session_id	—	SKIPPED（合并冲突，需 rebase）
#1286	remote 模式下始终向 chroma-mcp 传 --ssl 标志	—	MERGED

#1341 解决的是多会话并发下的端口竞争：多个 SessionStart Hook 并发争用共享端口 37777（Issue #1346），合并为顺序执行后竞争消除。#1334 则封堵了一个进程稳定性缺陷——FK 约束错误触发重启、重启再次触发同一错误，形成死循环；这类「错误 → 重启 → 同一错误」的反馈环在长期运行的 worker 服务中是典型的资源黑洞。

七、批次 5：功能型 PR 与质量门槛

PR	标题	修复 Issue	状态
#1321	按项目禁用/排除功能	#1320	SKIPPED（合并冲突，需 rebase）。代码评审：APPROVED
#1319	基于 workspace 的记忆隔离	#1318	NEEDS REWORK——死代码未接入运行时，存在 DRY 违规

功能型 PR 的评审标准明显比 bugfix 更严格（playbook 原文：「Review more carefully for scope and quality」），两个 PR 恰好构成了正反两个案例：

• #1321（APPROVED 但跳过）：实现方案是 .claude-mem-disable touch 文件 + settings 配置排除，在全部 4 个 Hook handler 中提前退出，附带 CLI 命令与测试，评审结论是「范围清晰、实现干净」。仅因前面批次合并产生冲突而跳过，属于纯粹的时序问题。

• #1319（NEEDS REWORK）：代码评审识别出三个关键问题：

  1. 死代码：新增 7 个文件但没有任何现有文件被修改——handler 未接入 hooks.json，WorkspaceDatabaseManager 未被 worker-service.ts 使用，功能在运行时完全不生效；
  2. DRY 违规：session-init-workspace.ts 是 session-init.ts 的近似复制；
  3. 双路径系统：paths-workspace.ts 用 @deprecated 标签重复导出 paths.ts 中已有的内容。

  评审建议是「把 workspace 支持集成进现有 handler/服务，而非创建平行的代码路径」。这条经验对 Agent 驱动的批量修复场景尤为关键：LLM 生成的 PR 倾向于「新增文件而不改接线」，评审必须检查新代码是否被运行时实际引用。

八、Issue 关闭治理：重复项与解决项

关闭的重复 Issue（6 个）

被关闭	重复自	主题
#1250	#1248	Chroma-mcp 在 Apple Silicon 上 CPU 失控
#1235	#1234	Stop Hook 在 git worktree 中崩溃
#1290	#1288	Stop Hook 输出格式 / JSON 校验
#1317	#1256	basename(cwd) 项目检测碎片化
#1232	#1261	Chroma 连接/配置失败
#1296	#1226	孤儿/僵尸进程累积

由合并 PR 解决的 Issue（10 个）

Issue	标题	解决者
#1312	summarize 产出 <observation> 而非 <summary>	PR #1345
#1303	paths.ts 忽略 settings.json 与环境变量的 DATA_DIR	PR #1344
#1324	MCP 搜索忽略 dateStart/dateEnd 过滤	PR #1343
#1253	smart-install 输出非 JSON 导致 SessionStart Hook 报错	PR #1337
#1294	Chroma 禁用时 getChromaSync() 空指针崩溃	PR #1336
#1314	Stop Hook 中的 session-complete 杀死 SDK agent	PR #1330
#1226	进程泄漏：worker 从不终止 subagent 进程	PR #1325
#1288	{"continue":true} 导致 Stop Hook 无限循环	PR #1291
#1313	project filter 激活时 SSE 实时数据被丢弃	PR #1315
#1307	跨版本 DB 同步的 schema 迁移失败	PR #1308

重复项的关闭规则统一为：保留「带跟踪 PR 的那个」，关闭另一个并附上交叉引用评论（例如「Closing as duplicate of #1248, identical root cause: HNSW index reconstruction」）。这条规则保证了 Issue 追踪器中每个根因只有一个权威跟踪点。

九、测试结果与构建验证

• 1135 个测试通过、3 跳过、0 失败，覆盖 66 个测试文件（19.48 秒）
• 构建成功——全部产物生成
• 未发现由合并 PR 引入的回归

当前仓库 tests/ 目录下与本报告修复点直接相关的测试文件均可作为回归防线参考，例如 SessionStore 系列测试 覆盖 observation 存储路径，paths.test.ts 覆盖 DATA_DIR 解析，kill-process-tree 系列测试 覆盖进程树终止语义（对应 #1325 的僵尸进程修复）。

十、遗留工作：Rebase、返工与后续 Phase 输入

需要 Rebase 的 PR（3 个）

这些 PR 已评审通过，仅因前面批次合并产生冲突：

PR	标题	需要的动作
#1301	加固 Hook fallback 与 MCP node 解析	Rebase onto main
#1306	处理缺失的 session_id（Cursor 兼容）	Rebase onto main
#1321	按项目禁用/排除功能	Rebase onto main

需要返工的 PR（1 个）

PR	标题	问题
#1319	基于 workspace 的记忆隔离	死代码——新文件未接入 hooks.json 或 worker-service.ts，与现有并行代码路径存在 DRY 违规，需集成进现有 handler

剩余开放 Issue（42 个，Phase 01 未处理）

这 42 个开放 Issue 不在 Phase 01 范围内，作为后续 triage phase 的输入（对应 TRIAGE-02 至 TRIAGE-10 等 playbook）：

Issue	标题
#1346	SessionStart Hook 在共享端口 37777 上报错（已被 #1341 部分解决）
#1342	mcp-server.cjs 为 CRLF 行尾——macOS/Linux 上 shebang 失败
#1340	Setup Hook 引用 v10.5.5 中不存在的 scripts/setup.sh
#1339	Web UI 的 #ID 编号与 MCP get_observations 的 ID 不匹配
#1335	Observer 会话触发 ECC 的 observe.sh Hook——双重 Haiku 循环
#1332	OpenClaw 插件配置：observationFeed 被阻断
#1331	SSE new_prompt 广播在 /reload-plugins 后停止
#1323	竞态条件：session-init 时报 Database not initialized
#1322	恢复手动 save_memory MCP 工具用于显式创建记忆
#1320	按项目禁用/排除功能（PR #1321 需 rebase）
#1318	基于 workspace 的记忆隔离（PR #1319 需返工）
#1299	context-reinjection-guard 测试中 mock.module() 泄漏
#1297	CWD 含 .env.local 时 chroma-mcp 崩溃
#1289	PATH 中无 'node' 时 worker 静默初始化失败（PR #1301 需 rebase）
#1285	GitHub Actions workflow 中可能的命令注入
#1284	集成设想：claude-brain 跨机器同步
#1281	Windows：Stop Hook 因 MODULE_NOT_FOUND（反斜杠路径）失败
#1274	上下文压缩后 Stop Hook 报 'Transcript path missing' 崩溃
#1273	多机同步/合并的 UUID observation ID
#1272	增加禁用子目录 CLAUDE.md 生成的选项
#1269	session 文件中的 saved_hook_context 导致 CPU 100%
#1268	Claude code 更新破坏 claude-mem
#1266	localhost:37777 活跃时仍丢失 MCP 连接
#1265	Web UI 的 observation/summary 卡片显示模型名称
#1263	search (MCP) Worker API 报错 (500)
#1262	pending_messages 队列无界增长，启动时 CPU 100%+
#1261	MCP Search 报 "Collection setup failed"
#1260	重复 observation——并发 Hook 触发绕过去重（PR #1302 已合并，待验证）
#1259	Gemini Flash Lite 产生幻觉 observation
#1256	monorepo 中 basename(cwd) 项目检测碎片化
#1255	Worker 端口冲突导致跨账号数据泄漏
#1252	OpenClaw 插件的嵌入/进程内模式
#1251	安全审计：全面代码评审
#1249	node→bun 孙进程在 sandbox 中被 SIGKILL
#1248	chroma-mcp 在 macOS 上 250-360% CPU
#1247	smart-explore 在 Windows 失败（tree-sitter 需要 C 编译器）
#1245	systemd 下 worker-service.cjs start 触发 SIGKILL
#1242	Hook fallback 路径指向 marketplace 源码（PR #1301 需 rebase）
#1234	Stop Hook 在 git worktree 中崩溃（PR #1326 已合并——待确认关闭）
#1231	Worker 启动在陈旧 PID 文件下报告成功
#1225	Windows：chroma-mcp "Received request before initialization"
#1219	将 plugin.json 版本升至 10.4.1
#1218	卡死处理消息的运行时自愈
#1204	watch.context.path 可向任意路径写 AGENTS.md
#1163	API 代理后 Claude provider 失败
#1156	np 应为 devDependency 而非运行时依赖
#1137	Plan 模式触发过多 pending 消息累积
#943	支持自定义 API endpoint / LiteLLM 代理

剩余开放 PR（45 个，不属于 Phase 01）

这些开放 PR 未在本阶段评审——它们多为功能型 PR、陈旧 PR，或处理 Phase 01 范围之外的问题：

PR	标题	状态
#1348	Feat/factory ai	Open
#1347	添加全面代码分析与优化报告	Open
#1338	feat: 添加 MiniMax M2.5 作为 provider 选项	Open
#1333	feat: 添加 Codex CLI 集成	Open
#1311	feat: cowork 模式——非编码工作的持久记忆	Open
#1310	fix(openclaw): 避免 --non-interactive 下的 /dev/tty 崩溃	Open
#1304	feat: 带 partner agent 支持的 VS Code MCP 集成	Open
#1298	feat: 使用 git root 做一致的项目名检测	Open
#1295	fix(openclaw): 修复 installer 中 worker 启动竞态	Open
#1283	feat(cli): 添加含 11 个命令的全面 CLI	Open
#1258	feat: npx claude-mem——带 13 个 IDE 集成的统一 CLI	Open
#1257	feat: 时间评分、陈旧度追踪、漂移检测	Open
#1254	fix: smart-install.js 非 JSON stdout 导致 SessionStart 报错	Open
#1246	feat: 基于 git 祖先过滤的分支级记忆	Open
#1233	feat: 添加 OpenCode 平台集成	Conflicting
#1230	feat(session-registry): 注册表 UI 与原始会话浏览	Open
#1207	feat: 添加 GitHub Copilot provider	Open
#1198	fix: 从 bun:sqlite 迁移到 better-sqlite3	Open
#1191	fix: Windows 上使用 'uvx' 而非 'uvx.cmd'	Open
#1189	feat: installer 添加 Claude 模型选择	Open
#1186	feat: Litestream 云备份集成	Open
#1180	fix: 检测认证错误并阻止无限重试循环	Open
#1177	feat(provider): 添加 OpenAI Codex OAuth provider	Open
#1169	fix: 去重 session-init 防止冗余重初始化	Open
#1164	perf(memory): 约束会话历史 + 降低 Chroma 占用	Conflicting
#1151	fix: privacy 标签剥离改为大小写不敏感	Open
#1150	fix: promptNumber 使用空值合并	Open
#1142	subagent 运行跳过 summary 生成	Open
#1129	feat: 添加通用 session 回填脚本	Open
#1127	feat: 实现 5 阶段 observation 处理流水线	Open
#1102	fix: 关键 bug 修复、snap sandbox 支持、资源监控	Open
#1101	feat: 交互式 feed 配置向导与独立 daemon	Open
#1092	fix: 加固 OpenClaw 集成、认证链、SSE 稳定性	Open
#1088	fix: 使用持久 venv 替代 uvx	Open
#1085	fix: 四层防御消除无界进程派生	Open
#1083	添加 thoughts 时间线	Open
#1078	添加西班牙语翻译与 Windows 改进	Open
#1072	fix: 为 Stop Hook 的 package.json 读取错误添加处理	Open
#1064	feat: 将导入的 observation 同步到 Chroma 向量库	Open
#996	fix: 为 stateless provider 保留合成 memorySessionId	Open
#854	feat: Pro 云同步集成（Supabase + Pinecone）	Open
#474	fix(windows): 防止 smart-install.js 中 libuv 断言失败	Open

十一、方法论总结：从一份 triage 报告能学到什么

回顾整个 Phase 01，有几个可迁移的工程决策模式值得提炼：

1. 按影响面分批次而非按时间分批次：数据正确性缺陷先于生命周期缺陷、后者先于功能 PR。批次顺序决定了冲突面与回归风险，也决定了「先跳过的 PR 重新 rebase 时基线更干净」。
2. 跳过即记录，失败不回滚：合并冲突的 PR 直接标注 SKIPPED + needs rebase 进入遗留清单，不强行解冲突；测试失败只记录归因不 revert。批量场景下「保持前进 + 完整记录」比「局部止损」更可控。
3. 重复项关闭要保留权威跟踪点：重复 Issue 对关闭时保留带跟踪 PR 的那个，附交叉引用评论说明根因。
4. 功能 PR 评审要看「接线」而非只看代码：#1319 的 7 个新文件因未接入 hooks.json 与 worker-service.ts 而被判死代码——代码质量良好但运行时零效果。这条判据（新代码是否被运行路径引用）是评审 Agent 批量生成的 PR 时的第一检查项。
5. triage 报告本身就是交接文档：剩余 rebase 清单、返工清单、42 个开放 Issue 与 45 个开放 PR 的完整枚举，构成了 Phase 02-10 的直接输入，使多 phase 的自动化 triage 可以无状态接力。