[Feature] agent 主动整理接口：dryRun 比对报告 → agent 判断 → apply，全留审计

[modusensus]

背景

讨论 #164 的「第三腿触发」：dream 自动整理与查询按需综合之外，缺一个 agent 自己决定调用的整理入口——长段工作收尾时，agent 发起「整理当前上下文、与已有记忆比对去重、沉淀 document」（document 型见姊妹 issue）。

形态（#164 已对齐）

1. dryRun：返回比对报告（候选新条 vs 库内相似条），不写库；
2. agent 判断报告后调 apply 落库；筛除项进归档不删；
3. 调用全程留审计回执——复用 dream_runs 的 receipt 语义，不新建审计面。

边界

• 现有 9 工具与命令面均无此入口，不重复造：新工具一个（dryRun/apply 两档）或一个工具带 mode 参数，倾向后者；
• opt-in 默认关（新行为开关惯例），settings.js 白名单注册 + lightMode 考虑；
• 上下文大幅精简前的「关键连续性」整理是其主场景（对照 2608.22752 压缩悬崖：任务状态是蒸馏管线覆盖不到的部分）。

[heptaspirit]

对照 #249 的提案时意识到一个问题：单独实现该主动整理接口依然不能解决“AI为什么什么时候调用它”的问题，至少需要在 #249 中的能力说明完善后，通过注入形式教会 AI 使用。
所以对该 Feature 提出几个新建议：

1. 接口实现后暂不对 agent 暴露，暂不进入工具列表
2. 暂不对其单独实现 opt-in，默认不显示
3. 具体的注入和对 agent 暴露的形式与 [Feature] 注入形态：能力说明 + 指针 + 分时机注入（设计提案） #249 一同实现，本 Feature 仅实现功能本身并为后续开发铺路

[modusensus]

@heptaspirit 顺着 #230 问一句 #231（agent 主动整理接口：dryRun 比对报告 → agent 判断 → apply）的归属。

这两条是你在 #164 里提的同一份设计的两个半边——「产物分两型」与「触发加第三条腿」。你认领了 #230，所以想确认 #231 是你打算一起做，还是留给我们这边接？

如果由我们接，会按你在 #164 里定的口径走（先 dryRun 出比对报告、agent 判断后再 apply、调用全留审计），实现前把接口形态贴上来给你过一遍。如果由你一起做，我们就不动，只在 review 时配合。

[heptaspirit]

@modusensus 本 Issue 我们认领，接在 #230 之后开发。
需要对的一个口径是，我们目前的开发是打算为 #249 铺路，如果你对 #249 还有什么建议或者方向调整也请提出，这样在本 Issue 开发前能有一个比较清晰的路径。

对照 #249 的提案时意识到一个问题：单独实现该主动整理接口依然不能解决“AI为什么什么时候调用它”的问题，至少需要在 #249 中的能力说明完善后，通过注入形式教会 AI 使用。 所以对该 Feature 提出几个新建议：

1. 接口实现后暂不对 agent 暴露，暂不进入工具列表

2. 暂不对其单独实现 opt-in，默认不显示

3. 具体的注入和对 agent 暴露的形式与 [[Feature] 注入形态：能力说明 + 指针 + 分时机注入（设计提案） #249](https://github.com/slow-stack/dsh-mneme/issues/249) 一同实现，本 Feature 仅实现功能本身并为后续开发铺路

[modusensus]

@heptaspirit #231 归你们，欢迎 —— 三条建议我这边都同意，补一句实施口径：

• 功能本体做在 service 层并带测试（不进工具列表、不加独立 opt-in 开关），这样 [Feature] 注入形态：能力说明 + 指针 + 分时机注入（设计提案） #249 到位时只差「注册工具 + 注入指引」一步；验证走测试 / 面板 / CLI，不需要靠暴露给 agent 来实现可测。
• 排在 [Feature] document 型记忆：agent 产出的长文档入库——注册校验、摘要+指针落库、supersede 记账 #230 之后、与 [Feature] 注入形态：能力说明 + 指针 + 分时机注入（设计提案） #249 同批暴露，这个顺序我们同意。

关于 #249，先说结论：方向同意，P0 + P1 先做（能力说明进工具描述是纯加法零成本；分池是全篇证据最强的一条）。逐条给几条调整，都带核对过的依据：

1. §10 的父开关默认关会翻掉现有默认

src/config.js 现在是 autoInject: z.boolean().default(true)。如果新的「自动注入总闸」默认关，存量用户升级后会静默失去注入——这与仓库纪律的方向相反：那条纪律是「新功能不打扰老用户」，不是「把老功能关掉」。

建议：autoInject 保留原语义与 default(true)；分组只在面板呈现层做（把现有开关与新子项放进同一组），不引入第二个总闸。这样「父关 = 全不生效」的语义由既有的 autoInject 天然承担，验收里的「父关零注入」也随之成立。

2. B2「摘要 + 指针」目前没有摘要可读

service.toApiList 产出的 DTO 是 id / type / title / content / tags / importance / source / created_at / updated_at（外加条件展开的 scope 三键与 occurred_at/sensitivity）——没有摘要字段。现有注入本来就是「截断头（injectContentMaxChars，默认 300 字）+ id」。

建议第一版把 B2 明确写成「截断头 + 显式 id 指针」：零新增字段、零新增 LLM 调用，与 §3 的非目标一致。真正的「摘要」留给 #230 / document 那条线，避免 B2 偷偷长出一条摘要管线。

3. §7 那条「需确认追加 API 形态」已核实：可用

宿主 dsh-agent 自己的实现就是范例（lib/index.js:160）：agent/pre-step 回调签名是 async ({ agent, messages, signal, step }, next)，await next() 拿到 decision，返回 { ...decision, messages: [...decision.messages, notice] } 即可追加；还支持 { prepend: true } 控制顺序。agent/turn-stopping、agent/request-error、agent/session-start 也都存在。

所以 N3 的「写库 + 末尾注入」双落点不必先降级为持久规则，可以直接按主路径实现；「宿主不提供压缩前时机」的降级分支保留着即可（§4.4 的写法没问题）。

4. 分池默认开：建议第一版仍默认关

你的论证我认同（默认配置不该保留一个已实测的缺陷）。但本项目的行为变更纪律是「先能回滚、再谈默认」：建议第一版仍 opt-in 默认关，同时在 README 与面板文案里给出推荐配置（甚至一键套用），等真实负载数据到位再单独一次「翻默认」的提交。这样把「我们相信这个修正」与「我们替你改行为」分成两步。

5. 面板分组不要挤进 P0/P1

lib/client.js 是 4300+ 行手写、无构建步骤的文件，改它本身要单独排期。P0/P1 新增的配置键会自动出现在现有 flag 列表里（无需改面板即可用），所以建议：P0 → P1 → 面板分组 → P2 → P3（只计量），分组 UI 作为独立 PR。

6. 一处分工确认

P0（工具描述文案 + 库可见性行）与 P1（分池）我们这边可以直接接；你们手上是 #230 + #231。如果你们想连 P1 一起做（它动的是注入排序与轮换的既有契约，与你们 #230/#231 的注入形态同源），我们就不动，只在 review 配合——你们定。

[modusensus]

@heptaspirit 认领与三条口径（不进工具列表、不做独立 opt-in、注入形式与 #249 同批实现）都同意，按此开工。#249 的方向表态见那边的回复——第一批（能力说明 + constraint/preference 分池保真）与 #231 并行不冲突，你说的「为 #249 铺路」的路径成立。

[heptaspirit]

@modusensus

CodeRabbit 在 #267 上把「报告判定与落库判定是两套实现」标成了 Major。这条我在 9-19 的 PR 评论（#267 comment）里已经交底过它的 A.1 与 A.3，当时问的是「放这个 PR 还是单独一个改动」。PR 评论你多半看不到，所以搬到这里问一句。

分歧有三处，都在 src/organize.js 的 dryRun 与 src/service.js 的 saveWithDedupe 之间：

1. 标题口径：dryRun 归一后比较（去空白与标点），写路径是 title.trim() 全等 → 标题只差标点时，报告 exact、apply 新建。
2. 两条特殊键没实现：写路径对 type === "summary" && source === "dream" 按来源去重、对 narrative 按 tags[0] 去重；dryRun 只比标题 → 报告 new、apply 并入既有行并改写它的标题。
3. 扫描窗口：dryRun limit: null（全量），写路径 limit: 100 → 同类型超过 100 行且重复行排在窗口外时，报告 exact、apply 新建。

后果是报告会领先于写路径，而 agent 是照着报告的 match.id 去归档旧行的，库里可能留下一条没合并的新行。

根因是 organize 自己重写了一遍写路径的匹配逻辑。收口办法是从 saveWithDedupe 里把「这个候选会并进哪一行」提成一个导出函数（写路径行为不变），dryRun 直接调它——这样这类分歧在结构上不会再出现。

要不要做、放 #267 还是后续单独一个 PR，你说一句我照办。#267 那边我不再推代码，只加评论。

另外补一句配套的：organize 现在只有 service 层入口（src/tools.js 的 10 个工具里没有它），这是照你定的口径留在「与 #249 同批暴露」。等下一步定了，把「注册工具 + 注入指引」接上，这套整理能力就能交给 AI 调用。在那之前只需要收口一处：dryRun 的 scope 默认值来自调用方 payload（src/organize.js:130），当它变成模型可调用的工具时，这个值应当改由 tools 层注入当前 scope——与 register_document 的 strictScope 同口径（src/document.js:87-88：调用者 scope 看不见的行按「不存在」处理，不得为跨 scope id 建立引用）。

[modusensus]

@heptaspirit 三处分歧我逐条对过 main 上的代码，全部属实，且根因正如你说的：organize 自己重写了一遍写路径的匹配逻辑。

分歧	dryRun（organize.js）	写路径（saveWithDedupe）	后果
标题口径	归一化（去空白/标点，小写）	title.trim() 全等	报告 exact、apply 新建
特殊键	无	summary+dream 按 source、narrative 按 tags[0]	报告 new、apply 并入并改写标题
扫描窗口	limit: null 全量	limit: 100	窗口外重复：报告 exact、apply 新建

报告领先于写路径的后果链也成立：agent 照报告的 match.id 归档旧行，库里留一条没合并的新行——这正是 CodeRabbit 那个 Major 的真实危害，不是纸面分歧。

拍板：收口单独一个 PR，不进 #267。

理由三条：

1. feat(organize): agent 主动整理接口 dryRun -> apply（issue #231） #267 已过 @Anans-Ivresse 复审，你现在又承诺不再推代码——把核心写路径的重构塞进 feat(organize): agent 主动整理接口 dryRun -> apply（issue #231） #267，等于让复审作废重来，也违背你自己刚立的规矩；
2. 按仓库纪律，动 service.js 核心路径要独立评审 + 带回归测试（AGENTS.md 自查清单 4）；
3. CodeRabbit 的 Major 由收口 PR 解决后，在 feat(organize): agent 主动整理接口 dryRun -> apply（issue #231） #267 合并说明里引用即可，不阻塞 feat(organize): agent 主动整理接口 dryRun -> apply（issue #231） #267 本身。

收口办法本身赞成：从 saveWithDedupe 把「这个候选会并进哪一行」提成导出函数，dryRun 直接调它——匹配逻辑单一来源，这类分歧在结构上不会再出现，这是根治不是补丁。谁来写：你提的方案、你更熟 organize 侧，你来开，我们 review。

scope 注入点（organize.js:130）——同意，记入工具化批次。 与 #249 同批暴露时，「dryRun 默认 scope 改由 tools 层注入当前 scope」与 register_document 的 strictScope 同口径（document.js:87-88：调用者 scope 看不见的行按「不存在」处理）。这条我认领进批次清单，不是现在改。

关键判断：#231 拍板 = 收口单独 PR 由你开（不进 #267），scope 注入点随工具化批次处理；三处分歧核实全部属实。