Skip to content

feat: auto-surfacing 对齐 Claude Code(prefetch、工具读取去重、compaction 复位) - #30

Merged
yandy merged 15 commits into
mainfrom
feat/surfacing-cc-align
Nov 18, 2026
Merged

yandy merged 15 commits into
mainfrom
feat/surfacing-cc-align

Conversation

@yandy

@yandy yandy commented Nov 18, 2026

Copy link
Copy Markdown
Owner

动机

auto-surfacing 的侧查询一直阻塞在注入路径上,且 dsh 的去重状态在 compaction 后不复位;工具读取过的记忆也不会被去重。本次对齐 Claude Code 的 findRelevantMemories 行为(prefetch、readFileState、compaction 语义),保持「持久注入 + session 去重」,不做再提醒。

设计文档:docs/superpowers/specs/2026-11-19-surfacing-cc-align-design.md(随本 PR 入库)

变更

core(纯加法)

  • createMemoryActionHandler 新增可选 onContentSeen:add/replace 成功、memory-scope search 命中时上报文件;search details 增加 files。
  • MemoryStore.generation:写操作成功递增,供宿主在消费 prefetch 前判断记忆是否已被修改。

pi-memory

  • 主 session memory 工具读取计入同一 injectedFiles 去重集合(headless dream/extract 不标记)。
  • surfacing 改 prefetch:before_agent_start 启动侧查询后立即返回;turn_end(completed + 有工具结果 + 归属校验通过)才以 custom_message 持久化并标去重;零工具单请求轮作废;消费前校验 store generation 与去重交集(同轮工具写入竞态);agent_settled 兜底清 pending。

dsh-memory

  • 主 session 工具读取计入 injected;worker(extract/dream)不标记。
  • agent/created 的 compact/clear 重建时清空 injected 与 pendingRecalls。
  • handoff:step 1 启动侧查询不等待、同轮 step≥2 消费;新 turn / abort / reject / 不同真人输入作废;同 turn 重复 step 1 不误删合法 pending;agent/status→idle 清 pending。

文档与工具文案

  • reference(中文)召回章节改写为 prefetch 时序与去重口径;工具 guidelines 改为宿主中立表述。

验证

  • npm run typecheck / npm run lint(3 条既有 pi warning)/ npm run build -w memory-core -w dsh-memory 通过
  • npm test:memory-core 847 passed(5 skipped)、pi-memory 324 passed(1 skipped)、dsh-memory 346 passed
  • 关键门做过变异验证(去门 → 对应用例转红)

已知差异(刻意)

  • pi 的 turn_end 在「工具批 terminate / finishTurn end」导致提前结束时仍会持久化召回(下轮历史可见);dsh 无后续 step 时作废。两侧语义分叉已写入 reference。
  • 同文本重复 prompt 允许消费(检索 query 相同,召回同样适用)。

yandy added 15 commits November 19, 2026 01:14
- 新增 input 作废入口:run 进行中排队的用户输入由同一低层 run drain,
  不发 before_agent_start,旧 prompt 的召回会被 follow-up 的 turn_end 误持久化
- 侧查询改收 injectedFiles 快照,避免在飞期间被 turn_end 的标记改写
- 缓存回归改为「宿主投影重放 + 独立未注入基线」对比
- 补 surfacingStatusFor 的旧收尾不清新状态行用例
- pi wiring:经真实 headless 端口建 dream 工具并执行 search,主 session 去重集合仍为空
- dsh assembly:extract worker 工具读过正文不标 injected;compact/clear 用例补 startup 保留断言
- pi memory-tool:未命中 / scope=sessions 的 search 不触发 onContentSeen
- pi index:registerTool 的 as any 与 biome-ignore 恢复相邻,lint 回到 3 条既有 warning
同轮工具写入与在飞的召回侧查询之间原本没有同步:prefetch 选中 Alpha.md 后,主 agent
在同一轮里 `memory search` 到它的正文(进去重集合)或 `memory remove` 掉它(store 变了),
`turn_end` / 同轮 step 2 仍然把 Alpha 的正文持久化 —— 同一份正文在工具结果与召回块里各出现
一次,或者把已删 / 已改的正文写进会话。

- core:`MemoryStore.generation` 只读写入代数,每次成功的写原语(add / replace / remove /
  rename / applyEntryFiles / rebuildIndex)递增,读与失败不动。纯加法,覆盖主工具、headless
  worker 与同步写入。
- pi / dsh:prefetch 启动时记录 `store` 与 `generation`;消费前两道同步门 —— 代数变了,或选中
  的文件里已有一个进了去重集合 → 整份作废(不持久化、不标去重、下一轮重检)。
- pi:补 `agent_settled` 销账点(零工具轮/未就绪/被门挡回都不在 `turn_end` 清 pending)。
- dsh:`agent/status` 转 `idle` 时作废在途召回。
- pi 的「有工具结果 ≠ 必有下一请求」按刻意语义固定:提前终止时召回仍持久化、去重仍标记,
  两侧文档记录该已知分叉。
- 工具 guidelines 改为宿主中立措辞(首个请求可能无召回、零工具轮可能完全没有)。

变异验证:分别去掉两道门、`agent_settled` 与 `agent/status` 销账,对应回归用例逐条转红。
- pi 参考:`session_compact` 的「已注入集合」改为「去重集合」,与同页口径一致;
- 拆开「渲染」与「消费」两步:截断 / 净化发生在预取阶段(`runTask` 内),`turn_end` 只做持久化
  与标记去重;
- 去重口径补一句:侧查询按本轮开始时的已见集合(轮首快照)筛选,消费点再按当时集合复检;
- dsh 参考:`Recalled N memories` 的摘要补单数形态(`Recalled 1 memory`);
- dsh 差异清单补第 7 条:召回消费点不同(`pre-step` 两段式 vs pi 的 `turn_end` 边界),以及随之而来的
  「提前终止的轮」语义分叉。
@yandy
yandy merged commit ccd0a0a into main Nov 18, 2026
8 checks passed
@yandy
yandy deleted the feat/surfacing-cc-align branch November 18, 2026 23:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant