@stardustlc/dsh-dream 0.5.1 → 0.7.0

package/lib/tools.js

@@ -5,15 +5,16 @@
  * @module dsh-dream/tools
  */
 import { createHash } from 'node:crypto';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { existsSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { maskSecrets } from './mask.js';
 import { dreamStats, readDreams, saveDream, searchDreams } from './journal.js';
-import { bridgeDreams } from './bridge.js';
+import { applyBridge, bridgeDreams, previewBridge, rollbackBridge, selectBridgeLessons, } from './bridge.js';
 import { digestSessionFile, listSessionFiles } from './sessions.js';
 import { KnowledgeError, lessonFingerprint, } from './knowledge.js';
 import { KnowledgeStore } from './knowledge-store.js';
-import { queryScopeLabel, resolveRetrievalBudget, retrieveLessons, retrievedLessonChars, } from './retrieval.js';
+import { verifyEvidence } from './evidence.js';
+import { queryScopeLabel, resolveRetrievalBudget, retrieveLessons, retrievedLessonChars, taskPlatform, } from './retrieval.js';
 /** 编译一个值 schema 节点；支持 enum、对象数组 items 与嵌套对象（宿主 schema 子集要求对象显式 additionalProperties）。 */
 function compileValueNode(prop) {
     const node = {};
@@ -129,6 +130,40 @@ function knowledgeDirOf(cfg) {
 function knowledgeStoreOf(cfg) {
     return new KnowledgeStore(knowledgeDirOf(cfg), { maskSecrets: cfg.maskSecrets });
 }
+function execCwdOf(exec) {
+    const root = asRecord(exec);
+    const candidates = [asRecord(asRecord(root.agent).session), asRecord(root.session), root];
+    for (const candidate of candidates) {
+        const cwd = candidate.cwd;
+        if (typeof cwd === 'string' && cwd.trim() !== '')
+            return cwd.trim();
+    }
+    return undefined;
+}
+/** 软链/junction 场景：跟随链接后的真实写入路径（与 bridge resolveBridgeTarget 同口径）。 */
+function resolvedBridgePath(projectRoot, explicitPath) {
+    try {
+        const lexical = explicitPath !== undefined ? resolve(projectRoot, explicitPath) : join(projectRoot, 'AGENTS.md');
+        if (existsSync(lexical))
+            return realpathSync(lexical);
+        return join(realpathSync(dirname(lexical)), basename(lexical));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 合并 bridge 自身 skipped 与工具层前置校验 skipped（按 lessonId 去重，bridge 结果优先）。 */
+function mergeSkipped(primary, extra) {
+    const out = [...primary];
+    const seen = new Set(primary.map((entry) => entry.lessonId));
+    for (const entry of extra) {
+        if (seen.has(entry.lessonId))
+            continue;
+        seen.add(entry.lessonId);
+        out.push(entry);
+    }
+    return out;
+}
 function sha256Short(value) {
     return createHash('sha256').update(value, 'utf8').digest('hex').slice(0, 32);
 }
@@ -173,6 +208,11 @@ function parseEvidenceArgs(args, key, projectId) {
             entry.recordSeq = recordSeq;
         if (projectId !== undefined)
             entry.projectId = projectId;
+        for (const key of ['quote', 'sourceHash', 'artifactPath']) {
+            const value = optionalString(item, key);
+            if (value !== undefined)
+                entry[key] = value;
+        }
         out.push(entry);
     });
     return out;
@@ -210,11 +250,31 @@ function evidenceItemsSpec() {
             sessionId: { type: 'string', description: '会话 ID（session 证据建议提供）。' },
             recordSeq: { oneOf: [{ type: 'string' }, { type: 'integer' }], description: '记录序号（数字或字符串）。' },
             summary: { type: 'string', description: '已脱敏的一句话摘要。' },
-            verification: { type: 'string', enum: ['read', 'claimed'], description: 'read=插件读到原记录；claimed=仅模型声称。' },
+            quote: { type: 'string', description: '来源可见正文中的原文片段；摘要为转述时必填。引用原文只用于核验，不持久化。' },
+            sourceHash: { type: 'string', description: '可选的来源 SHA-256；插件自行计算并核对，不能只凭此值证明来源。' },
+            artifactPath: { type: 'string', description: 'local-artifact 的文本路径；只能读取宿主当前工作区内文件。' },
+            verification: { type: 'string', enum: ['read', 'claimed'], description: 'read=请求插件核验引用；找不到或不匹配自动降为 claimed。读取不代表用户采纳。' },
         },
         required: ['kind', 'summary', 'verification'],
     };
 }
+/** 冲突组校验：primary + conflictWith 全部存在、无自身/重复；任何写前完成。 */
+function requireConflictGroup(store, lessonId, primary, conflictWith) {
+    const group = [lessonId];
+    for (const id of conflictWith) {
+        if (id === lessonId)
+            throw new KnowledgeError('invalid', 'conflictWith 不得包含 lessonId 自身：' + id);
+        if (group.includes(id))
+            throw new KnowledgeError('invalid', 'conflictWith 存在重复 id：' + id);
+        group.push(id);
+    }
+    return group.map((id) => {
+        const lesson = id === lessonId ? primary : store.getLesson(id);
+        if (lesson === undefined)
+            throw new KnowledgeError('invalid', '冲突对象不存在：' + id);
+        return { id, lesson };
+    });
+}
 const baseSchema = { type: 'object', additionalProperties: true };
 /** 构建六个做梦工具。 */
 export function buildDreamTools(config) {
@@ -378,28 +438,161 @@ export function buildDreamTools(config) {
     };
     const dreamBridge = {
         name: 'dream_bridge',
-        description: '渡梦：把梦境日记里的高频教训合并进目标 AGENTS.md（幂等，带标记块，重复执行只更新块内内容）。让梦真正变成长期记忆。没有梦时会拒绝并提示先做梦。',
+        description: '渡梦（M2）：把已采纳且适用的经验桥接进项目 AGENTS.md 的 Dream 管理块（<!-- dsh-dream:start -->…<!-- dsh-dream:end -->），块外内容原样保留。mode:"preview" 只读看 diff；复核后 mode:"apply" 必须带 preview.expected.sha256（文件变了会 conflict 零写入）；mode:"rollback" 带 backupId 恢复。缺省 mode 为 legacy 直写（已弃用，响应含 deprecation 提示）。资格：经验 state=usable，且 scope 与当前项目匹配（目标目录 realpath / 显式 projectId / global 且已采纳），频次不作准入。',
         parameters: compileParameters({
-            path: { type: 'string', required: true, description: '目标文件路径（必填，通常是项目根 AGENTS.md）。' },
-            maxLessons: { type: 'integer', description: '最多桥接教训条数 1-30（默认 10）。' },
+            mode: { type: 'string', enum: ['preview', 'apply', 'rollback'], description: 'preview=只读预览；apply=带 expectedSha256 落盘；rollback=按 backupId 恢复。缺省=legacy 直写（弃用）。' },
+            path: { type: 'string', description: '目标文件（可选；缺省为执行上下文 cwd 下的 AGENTS.md，取不到 cwd 会报错不猜）。' },
+            lessonIds: { type: 'array', items: { type: 'string' }, description: '参与桥接的经验 id（必须 usable 且 scope 匹配；缺省=按 store 顺序自动选取资格通过者）。' },
+            maxLessons: { type: 'integer', description: '经验上限：M2 模式默认 5、硬上限 20；legacy 模式默认 10、上限 30。' },
+            expectedSha256: { oneOf: [{ type: 'string' }, { type: 'null' }], description: 'apply 必填：preview.expected.sha256 原样回传；新文件用 null；不符则 conflict 零写入。' },
+            previewId: { type: 'string', description: 'apply 可带：preview.previewId，用于校验是同一份预览；块内容不一致 → preview-mismatch，需重新 preview。' },
+            backupId: { type: 'string', description: 'rollback 必填：apply 成功返回的 backupId。' },
+            projectId: { type: 'string', description: '当前项目 id（可选；用于匹配只带 projectId 的经验，纯增量）。' },
         }),
         output: {
             schema: baseSchema,
             render: (_args, value) => {
                 const rec = asRecord(value);
+                const mode = rec.mode;
+                if (rec.ok === false) {
+                    const failure = asRecord(rec.error);
+                    return [{ type: 'text', text: '桥接失败（' + (typeof mode === 'string' ? mode : 'legacy') + '）：' + failure.code + ' ' + failure.message }];
+                }
+                if (mode === 'preview') {
+                    const lessons = Array.isArray(rec.lessons) ? rec.lessons : [];
+                    const skipped = Array.isArray(rec.skipped) ? rec.skipped : [];
+                    const expected = asRecord(rec.expected);
+                    const lines = ['桥接预览（' + rec.action + '）：' + lessons.length + ' 条经验，当前 sha256=' + expected.sha256 + '，previewId=' + rec.previewId];
+                    for (const item of lessons) {
+                        const lesson = asRecord(item);
+                        lines.push('- [' + lesson.lessonId + '@' + lesson.revision + '] ' + lesson.title);
+                    }
+                    for (const item of skipped) {
+                        const entry = asRecord(item);
+                        lines.push('· 跳过 ' + entry.lessonId + '：' + entry.reason);
+                    }
+                    const diff = typeof rec.diff === 'string' ? rec.diff : '';
+                    if (diff !== '')
+                        lines.push('', clip(diff, 2000));
+                    return [{ type: 'text', text: lines.join('\n') }];
+                }
+                if (mode === 'apply') {
+                    if (rec.unchanged === true)
+                        return [{ type: 'text', text: '桥接未变更：管理块内容已一致，字节未写。' }];
+                    return [{ type: 'text', text: '桥接已应用：' + rec.path + '，backupId=' + rec.backupId + '。' + (typeof rec.warning === 'string' ? '\n' + rec.warning : '') }];
+                }
+                if (mode === 'rollback') {
+                    return [{ type: 'text', text: '桥接已回滚：' + rec.path + '，backupId=' + rec.backupId + '。' }];
+                }
                 const actionText = rec.action === 'created' ? '新建了' : rec.action === 'replaced' ? '更新了' : '追加到了';
-                return [{ type: 'text', text: '已把 ' + rec.lessonsCount + ' 条梦境教训桥接：' + actionText + ' ' + rec.path + '。梦醒之后，教训长存。' }];
+                const deprecation = asRecord(rec.deprecation);
+                const deprecationText = typeof deprecation.message === 'string' && deprecation.message !== '' ? '（' + deprecation.message + '）' : '';
+                return [{ type: 'text', text: '已把 ' + rec.lessonsCount + ' 条梦境教训桥接：' + actionText + ' ' + rec.path + '。' + deprecationText }];
             },
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
-            const targetPath = requiredString(args, 'path', '目标文件路径');
+            const mode = optionalString(args, 'mode');
+            if (mode !== undefined && mode !== 'preview' && mode !== 'apply' && mode !== 'rollback') {
+                throw new Error('mode 必须是 preview / apply / rollback（缺省为 legacy 直写）。');
+            }
+            const explicitPath = optionalString(args, 'path');
+            const cwd = execCwdOf(exec);
+            let projectRoot;
+            if (explicitPath !== undefined) {
+                projectRoot = cwd ?? dirname(resolve(explicitPath));
+            }
+            else {
+                if (cwd === undefined) {
+                    throw new Error('未提供 path 且无法从执行上下文取得 cwd：无法定位项目内 AGENTS.md，请显式传 path。');
+                }
+                projectRoot = cwd;
+            }
+            const resolvedPath = resolvedBridgePath(projectRoot, explicitPath);
             const maxRaw = args.maxLessons;
-            const maxLessons = typeof maxRaw === 'number' && Number.isInteger(maxRaw) ? Math.min(30, Math.max(1, maxRaw)) : 10;
-            const result = bridgeDreams(cfg.journalDir, targetPath, maxLessons);
-            return { ok: true, path: targetPath, ...result };
+            const legacyMax = typeof maxRaw === 'number' && Number.isInteger(maxRaw) ? Math.min(30, Math.max(1, maxRaw)) : 10;
+            if (mode === undefined) {
+                const legacyTarget = explicitPath !== undefined ? resolve(explicitPath) : join(projectRoot, 'AGENTS.md');
+                const legacyResult = bridgeDreams(cfg.journalDir, legacyTarget, legacyMax);
+                return {
+                    ok: true,
+                    path: legacyTarget,
+                    ...(resolvedPath !== undefined ? { resolvedPath } : {}),
+                    ...legacyResult,
+                    deprecation: {
+                        code: 'legacy-write',
+                        message: '缺省 mode 为 legacy 直写（已弃用）；建议改用 mode:"preview" → 复核 diff → mode:"apply" + expectedSha256（并带同一 previewId）。',
+                    },
+                };
+            }
+            const maxLessons = typeof maxRaw === 'number' && Number.isInteger(maxRaw) ? maxRaw : undefined;
+            const lessonIds = stringArray(args, 'lessonIds');
+            const projectId = optionalString(args, 'projectId');
+            const store = knowledgeStoreOf(cfg);
+            const lessons = store.listLessons();
+            if (mode === 'rollback') {
+                const backupId = requiredString(args, 'backupId', 'backupId');
+                const result = rollbackBridge({
+                    journalDir: cfg.journalDir,
+                    projectRoot,
+                    ...(explicitPath !== undefined ? { path: explicitPath } : {}),
+                    backupId,
+                });
+                if (result.ok === true)
+                    return { mode, ...result, resolvedPath: result.path };
+                return { mode, ...result, ...(resolvedPath !== undefined ? { resolvedPath } : {}) };
+            }
+            // 工具层前置资格校验 + 合并 skipped（bridge 层会再兜一次）。
+            const preSelection = selectBridgeLessons(lessons, { projectId, workspaceRoot: projectRoot }, {
+                ...(lessonIds.length > 0 ? { lessonIds } : {}),
+                ...(maxLessons !== undefined ? { maxLessons } : {}),
+            });
+            const bridgeOptions = {
+                journalDir: cfg.journalDir,
+                projectRoot,
+                ...(explicitPath !== undefined ? { path: explicitPath } : {}),
+                lessons,
+                ...(projectId !== undefined ? { projectId } : {}),
+                workspaceRoot: projectRoot,
+                ...(lessonIds.length > 0 ? { lessonIds } : {}),
+                ...(maxLessons !== undefined ? { maxLessons } : {}),
+                maskSecrets: cfg.maskSecrets,
+            };
+            if (mode === 'preview') {
+                const result = previewBridge(bridgeOptions);
+                return {
+                    mode,
+                    ...result,
+                    ...(resolvedPath !== undefined ? { resolvedPath } : {}),
+                    skipped: mergeSkipped(result.ok === true ? result.skipped : [], preSelection.skipped),
+                };
+            }
+            if (!Object.hasOwn(args, 'expectedSha256') || (args.expectedSha256 !== null && (typeof args.expectedSha256 !== 'string' || args.expectedSha256.trim() === ''))) {
+                throw new Error('apply 必须提供 expectedSha256：原样回传 preview.expected.sha256（文件不存在时为 null）。');
+            }
+            const expectedSha256 = args.expectedSha256;
+            const previewId = optionalString(args, 'previewId');
+            const result = applyBridge({
+                ...bridgeOptions,
+                expectedSha256,
+                ...(previewId !== undefined ? { previewId } : {}),
+            });
+            if (result.ok === true) {
+                return {
+                    mode,
+                    ...result,
+                    resolvedPath: result.path,
+                    skipped: mergeSkipped(result.skipped, preSelection.skipped),
+                };
+            }
+            return {
+                mode,
+                ...result,
+                ...(resolvedPath !== undefined ? { resolvedPath } : {}),
+                skipped: mergeSkipped([], preSelection.skipped),
+            };
         },
-        timeoutMs: 15000,
+        timeoutMs: 30000,
     };
     const dreamHealth = {
         name: 'dream_health',
@@ -434,7 +627,7 @@ export function buildDreamTools(config) {
     };
     const dreamLearn = {
         name: 'dream_learn',
-        description: '学梦：把一条可复用经验连同证据提交为候选。必须写清 title（一句话结论）、action（可执行动作）、when（适用条件）与 exceptions（例外）；evidence 用 sessionId+recordSeq 或 sourceHash 定位来源，verification=read 表示插件读到原记录、claimed 表示仅模型声称（不计入独立支持）。无证据的经验只以 candidate 保存，不会当作已证实结论注入。模型不得伪造用户采纳。',
+        description: '学梦：把一条可复用经验连同证据提交为候选。写清 title（一句话结论）、action（可执行动作）、when（适用条件）与 exceptions（例外）；会话证据需 sessionId+recordSeq 和可匹配的 quote（省略时用 summary），本地产物需当前工作目录内的 artifactPath。verification=read 必须通过插件实际核验；失败降为 claimed 并说明原因，不计独立支持。新经验均先留在 candidate，读到来源不代表用户采纳。',
         parameters: compileParameters({
             kind: { type: 'string', required: true, enum: ['preference', 'procedure', 'pitfall', 'fact'], description: '经验类别。' },
             title: { type: 'string', required: true, description: '一句话结论；脱离 when 不得单独使用。' },
@@ -471,7 +664,7 @@ export function buildDreamTools(config) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
             const args = asRecord(rawArgs);
             const kind = parseLessonKind(args);
             const title = maskIfNeeded(cfg, requiredString(args, 'title', '经验结论'));
@@ -488,6 +681,7 @@ export function buildDreamTools(config) {
                 ...(entry.platform !== undefined ? { platform: maskIfNeeded(cfg, entry.platform) } : {}),
             }));
             const evidenceInputs = parseEvidenceArgs(args, 'evidence', projectId)
+                .map((entry) => verifyEvidence(entry, { sessionsRoot: cfg.sessionsRoot, projectId, workspaceRoot, cwd: execCwdOf(exec) }))
                 .map((entry) => ({ ...entry, summary: maskIfNeeded(cfg, entry.summary) }));
             const scope = {
                 global: isGlobal,
@@ -518,25 +712,16 @@ export function buildDreamTools(config) {
                     recordSeq: entry.recordSeq ?? null,
                     summary: entry.summary,
                     verification: entry.verification,
+                    sourceHash: entry.sourceHash ?? null,
                 })),
             }));
             const store = knowledgeStoreOf(cfg);
-            let { lesson, created } = store.createLesson(lessonInput, idempotencyKey);
-            // R2：user-correction + read 证据视为用户已采纳；初始 candidate 经验直接进入 usable，
-            // 并在 review 记 actor=user。若存储层未来也实现 R2，这里会因 state 已 usable 而跳过（兼容）。
-            const hasUserCorrectionRead = evidenceInputs.some((entry) => entry.kind === 'user-correction' && entry.verification === 'read');
-            const reviewIsUserAccepted = lesson.review.decision === 'accepted' && lesson.review.actor === 'user';
-            const userReviewAllowed = lesson.state === 'candidate' || lesson.state === 'usable';
-            // 兼容两种时序：R2′ 未落盘时 createLesson 返回 candidate；已落盘时返回 usable（review 未必带 actor）。
-            // user-correction + read 一律记为用户已采纳；rejected/disputed/stale 不覆盖既有审阅结论。
-            if (hasUserCorrectionRead && !reviewIsUserAccepted && userReviewAllowed) {
-                lesson = store.reviewLesson(lesson.id, 'accepted', lesson.revision, 'dream_learn:user-correction:' + lesson.id + ':' + lesson.revision, 'user');
-            }
+            const { lesson, created } = store.createLesson(lessonInput, idempotencyKey, { requireReview: true });
             const byId = new Map(store.listEvidence().map((item) => [item.id, item]));
             const evidence = lesson.evidenceIds
                 .map((id) => byId.get(id))
                 .filter((item) => item !== undefined)
-                .map((item) => ({ id: item.id, verification: item.verification }));
+                .map((item) => ({ id: item.id, verification: item.verification, ...(item.verificationReason ? { verificationReason: item.verificationReason } : {}) }));
             const notes = [];
             if (evidenceInputs.length === 0) {
                 notes.push('无证据：仅保存为 candidate，不会作为已证实结论注入任务建议。');
@@ -546,14 +731,10 @@ export function buildDreamTools(config) {
                 const claimedCount = evidence.filter((item) => item.verification === 'claimed').length;
                 notes.push('证据：' + readCount + ' 条已读（计入独立支持），' + claimedCount + ' 条仅声明（不计入独立支持）。');
             }
-            if (hasUserCorrectionRead) {
-                if (lesson.state === 'usable' && lesson.review.decision === 'accepted' && lesson.review.actor === 'user') {
-                    notes.push('检测到 user-correction + read 证据：按 R2 视为用户已采纳（state=usable，review.actor=user）。');
-                }
-                else {
-                    notes.push('检测到 user-correction + read 证据，但经验当前状态为 ' + lesson.state + '：不覆盖既有审阅结论。');
-                }
-            }
+            if (evidenceInputs.some((item) => item.verification === 'claimed' && item.verificationReason !== 'model-claimed'))
+                notes.push('部分来源未能核验，已保留为仅声明；请补充真实 sessionId/recordSeq、原文 quote 或当前工作区内 artifactPath。');
+            if (created)
+                notes.push('来源读取不等于结论成立或用户采纳；新经验仍需审阅。');
             if (!created)
                 notes.push('已存在同指纹经验（' + lesson.id + '）：复用既有记录并合并新证据，未新增经验。');
             if (!isGlobal && projectId === undefined && workspaceRoot === undefined) {
@@ -586,6 +767,7 @@ export function buildDreamTools(config) {
             maxChars: { type: 'integer', description: '字符预算 1-20000（默认 3000）。' },
             packageVersion: { type: 'string', description: '当前相关依赖版本（可选；需配合包名被识别才参与版本判定）。' },
             packageName: { type: 'string', description: '当前相关依赖包名（可选；与 query 文本一起识别 applicability.package）。' },
+            platform: { type: 'string', description: '任务目标平台（windows / linux / macos 等）；缺省从任务文本识别，否则使用宿主系统。平台不符的经验不注入。' },
             includeCandidates: { type: 'boolean', description: '是否把候选经验纳入任务建议（默认 false；仅明确审阅候选时传 true，无证据候选仍不注入）。' },
         }),
         output: {
@@ -639,6 +821,7 @@ export function buildDreamTools(config) {
             });
             const retrievalQuery = {
                 query,
+                platform: taskPlatform(query, optionalString(args, 'platform'), process.platform),
                 limit,
                 maxChars,
                 // R1：默认不注入候选；claimed-only / 无证据且非 usable 的条目也不注入（R1 附带规则）。
@@ -661,17 +844,19 @@ export function buildDreamTools(config) {
         },
         timeoutMs: 15000,
     };
-    const REVIEW_ACTIONS = ['accept', 'reject', 'mark-stale', 'mark-disputed', 'resolve-conflict', 'attach-evidence'];
     const dreamReview = {
         name: 'dream_review',
         description: '审梦：采纳/驳回/标记冲突或过期/追加验证证据，必须带 expectedRevision（revision 不符会拒绝且不写入）。模型调用 actor 一律记为 model，不得冒充用户采纳；attach-evidence 只追加证据，不自动改变 state。',
         parameters: compileParameters({
             action: { type: 'string', required: true, enum: [...REVIEW_ACTIONS], description: '审阅动作。' },
-            lessonId: { type: 'string', required: true, description: '经验 ID。' },
+            lessonId: { type: 'string', description: '经验 ID（accept/reject/mark-*/attach-evidence 必填；resolve-conflict 可用 targetId 替代）。' },
+            targetId: { type: 'string', description: 'resolve-conflict：目标经验 ID（优先于 lessonId）。' },
+            affectedIds: { type: 'array', items: { type: 'string' }, description: 'resolve-conflict：受影响/对方经验 ID（缺省则用 conflictWith）。' },
             expectedRevision: { type: 'integer', required: true, description: '期望 revision（乐观锁，必须与当前一致）。' },
             evidence: { type: 'array', items: evidenceItemsSpec(), description: 'attach-evidence 时使用的证据数组。' },
-            conflictWith: { type: 'array', items: { type: 'string' }, description: 'mark-disputed 记录冲突对象；resolve-conflict 时解除这些冲突 ID。' },
-            note: { type: 'string', description: '备注（仅用于幂等键，不落盘为正文）。' },
+            conflictWith: { type: 'array', items: { type: 'string' }, description: 'mark-disputed：冲突对方 id 列表（双方互相登记且全部置 disputed）；resolve-conflict：要一起解析的对方 id（必须与之互为 conflictIds）。' },
+            resolution: { type: 'string', enum: ['prefer', 'drop', 'merge'], description: 'resolve-conflict 必填：prefer=以 lessonId 为准；drop=放弃 lessonId；merge=并入 lessonId（对方 stale）。' },
+            note: { type: 'string', description: 'resolve-conflict 必填的解析依据；mark-disputed 可选。' },
         }),
         output: {
             schema: baseSchema,
@@ -683,93 +868,8 @@ export function buildDreamTools(config) {
                     }];
             },
         },
-        async execute(rawArgs) {
-            const args = asRecord(rawArgs);
-            const action = optionalString(args, 'action');
-            if (action === undefined || !REVIEW_ACTIONS.includes(action)) {
-                throw new Error('action 必须是 ' + REVIEW_ACTIONS.join(' / ') + '。');
-            }
-            const lessonId = requiredString(args, 'lessonId', '经验 ID');
-            const revisionRaw = args.expectedRevision;
-            if (typeof revisionRaw !== 'number' || !Number.isInteger(revisionRaw) || revisionRaw < 1) {
-                throw new Error('expectedRevision 必须是 >= 1 的整数。');
-            }
-            const expectedRevision = revisionRaw;
-            const store = knowledgeStoreOf(cfg);
-            const before = store.getLesson(lessonId);
-            if (before === undefined)
-                throw new KnowledgeError('invalid', '经验不存在：' + lessonId);
-            if (before.revision !== expectedRevision) {
-                const error = new KnowledgeError('revision', '经验 ' + lessonId + ' 期望 revision ' + expectedRevision + '，实际 ' + before.revision);
-                error.currentRevision = before.revision;
-                error.details = { currentRevision: before.revision };
-                throw error;
-            }
-            const conflictWith = stringArray(args, 'conflictWith');
-            const note = optionalString(args, 'note');
-            const idempotencyKey = 'dream_review:' + sha256Short(JSON.stringify({
-                action, lessonId, expectedRevision, conflictWith, note: note ?? null,
-            }));
-            // 模型调用永远记为 model；入参里的 actor 一律忽略（用户采纳只能来自宿主授权的真实用户指令）。
-            const actor = 'model';
-            let lesson;
-            switch (action) {
-                case 'accept':
-                    lesson = store.reviewLesson(lessonId, 'accepted', expectedRevision, idempotencyKey, actor);
-                    break;
-                case 'reject':
-                    lesson = store.reviewLesson(lessonId, 'rejected', expectedRevision, idempotencyKey, actor);
-                    break;
-                case 'mark-stale':
-                    lesson = store.applyTransition(lessonId, 'stale', expectedRevision, idempotencyKey);
-                    break;
-                case 'mark-disputed': {
-                    if (conflictWith.length === 0) {
-                        lesson = store.applyTransition(lessonId, 'disputed', expectedRevision, idempotencyKey);
-                    }
-                    else {
-                        const conflictIds = [...before.conflictIds];
-                        for (const id of conflictWith) {
-                            if (!conflictIds.includes(id))
-                                conflictIds.push(id);
-                        }
-                        lesson = store.updateLesson(lessonId, { state: 'disputed', conflictIds }, expectedRevision, idempotencyKey);
-                    }
-                    break;
-                }
-                case 'resolve-conflict': {
-                    if (conflictWith.length === 0) {
-                        lesson = store.applyTransition(lessonId, 'usable', expectedRevision, idempotencyKey);
-                    }
-                    else {
-                        const conflictIds = before.conflictIds.filter((id) => !conflictWith.includes(id));
-                        lesson = store.updateLesson(lessonId, { state: 'usable', conflictIds }, expectedRevision, idempotencyKey);
-                    }
-                    break;
-                }
-                case 'attach-evidence': {
-                    const inputs = parseEvidenceArgs(args, 'evidence', before.scope.projectId);
-                    if (inputs.length === 0)
-                        throw new Error('attach-evidence 需要至少一条 evidence。');
-                    const masked = inputs.map((entry) => ({ ...entry, summary: maskIfNeeded(cfg, entry.summary) }));
-                    const appended = masked.map((entry) => store.appendEvidence(entry));
-                    const evidenceIds = [...before.evidenceIds];
-                    for (const item of appended) {
-                        if (!evidenceIds.includes(item.evidence.id))
-                            evidenceIds.push(item.evidence.id);
-                    }
-                    if (evidenceIds.length === before.evidenceIds.length) {
-                        lesson = before;
-                    }
-                    else {
-                        lesson = store.updateLesson(lessonId, { evidenceIds }, expectedRevision, idempotencyKey);
-                    }
-                    break;
-                }
-                default:
-                    throw new Error('不支持的动作：' + action);
-            }
-            return { ok: true, lesson, previousState: before.state, state: lesson.state, revision: lesson.revision };
+        async execute(rawArgs, exec) {
+            return executeDreamReview(cfg, rawArgs, exec, 'model');
         },
         timeoutMs: 15000,
     };
@@ -798,3 +898,211 @@ export function buildDigestText(digest) {
     }
     return lines.join('\n');
 }
+const REVIEW_ACTIONS = ['accept', 'reject', 'reopen', 'mark-stale', 'mark-disputed', 'resolve-conflict', 'attach-evidence'];
+/** actor comes from the trusted caller, never from tool or browser arguments. */
+export async function executeDreamReview(cfg, rawArgs, exec, actor = 'model') {
+    const args = asRecord(rawArgs);
+    const action = optionalString(args, 'action');
+    if (action === undefined || !REVIEW_ACTIONS.includes(action)) {
+        throw new Error('action 必须是 ' + REVIEW_ACTIONS.join(' / ') + '。');
+    }
+    const targetId = optionalString(args, 'targetId');
+    const lessonIdArg = optionalString(args, 'lessonId');
+    const lessonId = targetId ?? lessonIdArg;
+    if (lessonId === undefined) {
+        throw new KnowledgeError('invalid', '缺少 lessonId（resolve-conflict 可用 targetId）。');
+    }
+    const revisionRaw = args.expectedRevision;
+    if (typeof revisionRaw !== 'number' || !Number.isInteger(revisionRaw) || revisionRaw < 1) {
+        throw new Error('expectedRevision 必须是 >= 1 的整数。');
+    }
+    const expectedRevision = revisionRaw;
+    const store = knowledgeStoreOf(cfg);
+    const before = store.getLesson(lessonId);
+    if (before === undefined)
+        throw new KnowledgeError('invalid', '经验不存在：' + lessonId);
+    if (before.revision !== expectedRevision) {
+        const error = new KnowledgeError('revision', '经验 ' + lessonId + ' 期望 revision ' + expectedRevision + '，实际 ' + before.revision);
+        error.currentRevision = before.revision;
+        error.details = { currentRevision: before.revision };
+        throw error;
+    }
+    const affectedIdsArg = stringArray(args, 'affectedIds');
+    const conflictWith = affectedIdsArg.length > 0 ? affectedIdsArg : stringArray(args, 'conflictWith');
+    const note = optionalString(args, 'note');
+    const maskedNote = note === undefined ? undefined : maskIfNeeded(cfg, note);
+    const resolutionArg = optionalString(args, 'resolution');
+    const evidenceInputs = action === 'attach-evidence'
+        ? parseEvidenceArgs(args, 'evidence', before.scope.projectId).map(entry => verifyEvidence(entry, {
+            sessionsRoot: cfg.sessionsRoot, projectId: before.scope.projectId, workspaceRoot: before.scope.workspaceRoot, cwd: execCwdOf(exec),
+        })).map(entry => ({ ...entry, summary: maskIfNeeded(cfg, entry.summary) }))
+        : [];
+    const idempotencyKey = 'dream_review:' + sha256Short(JSON.stringify({
+        actor, action, lessonId, expectedRevision, conflictWith, resolution: resolutionArg ?? null, note: maskedNote ?? null,
+        evidence: evidenceInputs,
+    }));
+    let lesson;
+    switch (action) {
+        case 'accept':
+            lesson = store.reviewLesson(lessonId, 'accepted', expectedRevision, idempotencyKey, actor);
+            break;
+        case 'reject':
+            lesson = store.reviewLesson(lessonId, 'rejected', expectedRevision, idempotencyKey, actor);
+            break;
+        case 'reopen':
+            if (before.state !== 'rejected')
+                throw new KnowledgeError('invalid', 'reopen 只用于把已驳回经验重新送审。');
+            lesson = store.reviewLesson(lessonId, 'unreviewed', expectedRevision, idempotencyKey, actor);
+            break;
+        case 'mark-stale':
+            lesson = actor === 'human'
+                ? store.updateLesson(lessonId, { state: 'stale', review: { ...before.review, actor, at: new Date().toISOString(), ...(maskedNote === undefined ? {} : { note: maskedNote }) } }, expectedRevision, idempotencyKey)
+                : store.applyTransition(lessonId, 'stale', expectedRevision, idempotencyKey);
+            break;
+        case 'attach-evidence':
+            lesson = store.attachEvidence(lessonId, evidenceInputs, expectedRevision, idempotencyKey);
+            break;
+        case 'mark-disputed': {
+            // M2：primary 与所有 conflictWith 一律置 disputed，双方 conflictIds 互相登记（去重、可多对多）。
+            const members = requireConflictGroup(store, lessonId, before, conflictWith);
+            const group = members.map((member) => member.id);
+            const updates = [];
+            for (const member of members) {
+                const others = group.filter((id) => id !== member.id);
+                const conflictIds = [...member.lesson.conflictIds];
+                for (const id of others) {
+                    if (!conflictIds.includes(id))
+                        conflictIds.push(id);
+                }
+                const noteSatisfied = maskedNote === undefined || member.lesson.review.note === maskedNote;
+                const alreadyDisputed = member.lesson.state === 'disputed'
+                    && conflictIds.length === member.lesson.conflictIds.length
+                    && conflictIds.every((id) => member.lesson.conflictIds.includes(id))
+                    && noteSatisfied;
+                if (alreadyDisputed)
+                    continue;
+                const patch = { state: 'disputed', conflictIds };
+                if (maskedNote !== undefined)
+                    patch.review = { ...member.lesson.review, note: maskedNote };
+                updates.push({ id: member.id, patch, expectedRevision: member.lesson.revision });
+            }
+            lesson = updates.length === 0 ? before : store.updateLessonsBatch(updates, idempotencyKey).find(item => item.id === lessonId) ?? before;
+            break;
+        }
+        case 'resolve-conflict': {
+            const resolution = optionalString(args, 'resolution');
+            if (resolution !== 'prefer' && resolution !== 'drop' && resolution !== 'merge') {
+                throw new KnowledgeError('invalid', 'resolution 必须是 prefer / drop / merge。');
+            }
+            if (maskedNote === undefined) {
+                throw new KnowledgeError('invalid', 'resolve-conflict 必须带 note（解析依据），以便事件可回溯。');
+            }
+            if (conflictWith.length === 0) {
+                throw new KnowledgeError('invalid', 'resolve-conflict 必须带至少一个 affectedIds/conflictWith 目标 id。');
+            }
+            const members = requireConflictGroup(store, lessonId, before, conflictWith);
+            const group = members.map((member) => member.id);
+            // 校验：所有当事方必须 disputed，且互相登记 conflictIds；否则零写入。
+            for (const member of members) {
+                if (member.lesson.state !== 'disputed') {
+                    throw new KnowledgeError('invalid', '冲突解析要求 ' + member.id + ' 处于 disputed（实际 ' + member.lesson.state + '）');
+                }
+                for (const other of group) {
+                    if (other !== member.id && !member.lesson.conflictIds.includes(other)) {
+                        throw new KnowledgeError('invalid', '冲突未双向登记：' + member.id + ' 的 conflictIds 缺少 ' + other);
+                    }
+                }
+            }
+            const now = new Date().toISOString();
+            const affectedIds = group.filter((id) => id !== lessonId);
+            const resolutionPayload = { kind: resolution, targetId: lessonId, affectedIds };
+            const remainingOf = (member) => member.lesson.conflictIds.filter((id) => !group.includes(id));
+            const planned = [];
+            if (resolution === 'prefer' || resolution === 'drop') {
+                for (const member of members) {
+                    const isPrimary = member.id === lessonId;
+                    const patch = { conflictIds: remainingOf(member) };
+                    if (resolution === 'prefer') {
+                        if (isPrimary) {
+                            if (remainingOf(member).length === 0)
+                                patch.state = 'usable';
+                            patch.review = { ...member.lesson.review, ...(actor === 'human' ? { actor, decision: 'accepted' } : {}), at: now, note: maskedNote, resolution: resolutionPayload };
+                        }
+                        else {
+                            patch.state = 'rejected';
+                            patch.review = { decision: 'rejected', actor, at: now, note: '冲突解析：败给 ' + lessonId, resolution: resolutionPayload };
+                        }
+                    }
+                    else if (isPrimary) {
+                        patch.state = 'rejected';
+                        patch.review = { decision: 'rejected', actor, at: now, note: '冲突解析：放弃本条目', resolution: resolutionPayload };
+                    }
+                    else {
+                        if (remainingOf(member).length === 0)
+                            patch.state = 'usable';
+                        patch.review = { ...member.lesson.review, ...(actor === 'human' ? { actor, decision: 'accepted' } : {}), at: now, note: maskedNote, resolution: resolutionPayload };
+                    }
+                    planned.push({ id: member.id, isPrimary, patch });
+                }
+            }
+            else {
+                const primaryMember = members.find((member) => member.id === lessonId);
+                const mergedEvidence = [...(primaryMember?.lesson.evidenceIds ?? [])];
+                for (const member of members) {
+                    if (member.id === lessonId)
+                        continue;
+                    for (const id of member.lesson.evidenceIds) {
+                        if (!mergedEvidence.includes(id))
+                            mergedEvidence.push(id);
+                    }
+                }
+                for (const member of members) {
+                    const isPrimary = member.id === lessonId;
+                    const patch = { conflictIds: remainingOf(member) };
+                    if (isPrimary) {
+                        const supersedes = [...(member.lesson.supersedes ?? [])];
+                        for (const id of group) {
+                            if (id !== member.id && !supersedes.includes(id))
+                                supersedes.push(id);
+                        }
+                        if (remainingOf(member).length === 0)
+                            patch.state = 'usable';
+                        patch.supersedes = supersedes;
+                        patch.evidenceIds = mergedEvidence;
+                        patch.review = { ...member.lesson.review, ...(actor === 'human' ? { actor, decision: 'accepted' } : {}), at: now, note: '冲突解析：并入 ' + affectedIds.join('、'), resolution: resolutionPayload };
+                    }
+                    else {
+                        patch.state = 'stale';
+                        patch.review = { ...member.lesson.review, ...(actor === 'human' ? { actor } : {}), at: now, note: maskedNote, resolution: resolutionPayload };
+                    }
+                    planned.push({ id: member.id, isPrimary, patch });
+                }
+            }
+            const updates = [];
+            for (const item of planned) {
+                const member = members.find((entry) => entry.id === item.id);
+                if (member === undefined)
+                    continue;
+                const current = member.lesson;
+                const desiredConflictIds = item.patch.conflictIds ?? [];
+                const reviewPatch = item.patch.review;
+                const evidencePatch = item.patch.evidenceIds;
+                const desiredState = item.patch.state;
+                const noOp = desiredState === current.state
+                    && desiredConflictIds.length === current.conflictIds.length
+                    && desiredConflictIds.every((id) => current.conflictIds.includes(id))
+                    && (reviewPatch === undefined || (current.review.decision === reviewPatch.decision && current.review.note === reviewPatch.note))
+                    && (evidencePatch === undefined
+                        || (evidencePatch.length === current.evidenceIds.length && evidencePatch.every((id) => current.evidenceIds.includes(id))));
+                if (noOp)
+                    continue;
+                updates.push({ id: item.id, patch: item.patch, expectedRevision: current.revision });
+            }
+            lesson = updates.length === 0 ? before : store.updateLessonsBatch(updates, idempotencyKey).find(item => item.id === lessonId) ?? before;
+            break;
+        }
+        default:
+            throw new Error('不支持的动作：' + action);
+    }
+    return { ok: true, lesson, previousState: before.state, state: lesson.state, revision: lesson.revision };
+}