@stardustlc/dsh-dream 0.6.0 → 0.7.1

package/lib/index.js

@@ -9,6 +9,7 @@ import { join } from 'node:path';
 import { resolveConfig } from './config.js';
 import { buildDreamTools } from './tools.js';
 import { installDreamWeb } from './web.js';
+import { installDreamActions } from './web-actions.js';
 /** cordis 服务注入：要用 ctx.tools 与 ctx.skills。 */
 export const name = 'dream';
 export const inject = ['tools', 'skills'];
@@ -56,7 +57,8 @@ export function apply(ctx, config) {
     }
     // 面板同源路由：宿主有 webServer 才由 web.ts 用 ctx.inject 挂上；headless 夹具没有 inject 就跳过。
     if (typeof ctx.inject === 'function') {
-        installDreamWeb(ctx, { journalDir: cfg.journalDir });
+        installDreamWeb(ctx, { journalDir: cfg.journalDir, config: cfg });
+        installDreamActions(ctx, { config: cfg });
     }
     if (typeof ctx.on === 'function') {
         ctx.on('dispose', () => {

package/lib/knowledge-store.d.ts

@@ -59,6 +59,8 @@ export declare class KnowledgeStore {
     attachEvidence(id: string, inputs: EvidenceInput[], expectedRevision: number, idempotencyKey: string): Lesson;
     /** 按 patch 更新经验；revision 不符抛 KnowledgeError('revision')（details 带 currentRevision）且不写。 */
     updateLesson(id: string, patch: Partial<Lesson>, expectedRevision: number, idempotencyKey: string): Lesson;
+    /** 记录一次使用反馈，不改变审阅、状态、证据和最后核验时间。 */
+    recordFeedback(id: string, vote: 'useful' | 'not-applicable', note: string | undefined, expectedRevision: number, idempotencyKey: string): Lesson;
     /** 审阅经验：accepted → usable，rejected → rejected，unreviewed → candidate。 */
     reviewLesson(id: string, decision: ReviewDecision, expectedRevision: number, idempotencyKey: string, actor?: string, note?: string, resolution?: LessonReviewResolution): Lesson;
     /**

package/lib/knowledge-store.js

@@ -573,6 +573,41 @@ export class KnowledgeStore {
             return clone(this.appendLessonUpdate(state, lesson, clean, idempotencyKey, requestHash, touch));
         });
     }
+    /** 记录一次使用反馈，不改变审阅、状态、证据和最后核验时间。 */
+    recordFeedback(id, vote, note, expectedRevision, idempotencyKey) {
+        assertIdempotencyKey(idempotencyKey);
+        if (vote !== 'useful' && vote !== 'not-applicable')
+            throw new KnowledgeError('invalid', '反馈必须是 useful / not-applicable');
+        if (!Number.isInteger(expectedRevision) || expectedRevision < 1)
+            throw new KnowledgeError('invalid', '反馈必须带有效的经验版本');
+        if (note !== undefined && (typeof note !== 'string' || note.length > 500))
+            throw new KnowledgeError('invalid', '反馈备注最多 500 字符');
+        const cleanNote = note === undefined || note.trim() === '' ? undefined : this.mask ? maskSecrets(note.trim()) : note.trim();
+        const requestHash = this.hashRequest({ operation: 'lesson.feedback', id, vote, note: cleanNote ?? null, expectedRevision });
+        return this.withLock((touch) => {
+            const state = this.loadCompleteState(touch);
+            const cached = state.idempotency.get(idempotencyKey);
+            if (cached !== undefined) {
+                this.assertSameRequest(cached, requestHash, idempotencyKey);
+                const result = this.resolveIdempotentLesson(state, idempotencyKey);
+                if (result === undefined)
+                    throw new KnowledgeError('io', '无法恢复反馈结果');
+                return result;
+            }
+            const previous = state.lessons.get(id);
+            if (previous === undefined)
+                throw new KnowledgeError('invalid', '经验不存在：' + id);
+            if (previous.revision !== expectedRevision)
+                throw new KnowledgeError('revision', '经验已更新，请刷新后再反馈', { currentRevision: previous.revision });
+            const old = previous.feedback ?? { useful: 0, notApplicable: 0, recent: [] };
+            const feedback = {
+                useful: old.useful + (vote === 'useful' ? 1 : 0),
+                notApplicable: old.notApplicable + (vote === 'not-applicable' ? 1 : 0),
+                recent: [...old.recent, { vote, at: new Date().toISOString(), ...(cleanNote === undefined ? {} : { note: cleanNote }) }].slice(-20),
+            };
+            return clone(this.appendLessonUpdate(state, previous, { feedback }, idempotencyKey, requestHash, touch));
+        });
+    }
     /** 审阅经验：accepted → usable，rejected → rejected，unreviewed → candidate。 */
     reviewLesson(id, decision, expectedRevision, idempotencyKey, actor, note, resolution) {
         assertIdempotencyKey(idempotencyKey);
@@ -1419,6 +1454,11 @@ export class KnowledgeStore {
             const refs = [lesson.id, ...(lesson.review.resolution?.affectedIds ?? []), ...(lesson.review.resolution?.targetId ? [lesson.review.resolution.targetId] : [])];
             masked.review = { ...lesson.review, note: maskSecrets(lesson.review.note, refs) };
         }
+        if (lesson.feedback !== undefined)
+            masked.feedback = {
+                ...lesson.feedback,
+                recent: lesson.feedback.recent.map(item => ({ ...item, ...(item.note === undefined ? {} : { note: maskSecrets(item.note) }) })),
+            };
         return masked;
     }
     maskEvidence(evidence) {

package/lib/knowledge.d.ts

@@ -48,6 +48,8 @@ export interface Lesson {
         note?: string;
         resolution?: LessonReviewResolution;
     };
+    /** 使用反馈独立于审阅和证据；只保留最近 20 次明细，事件流保留历史。 */
+    feedback?: LessonFeedback;
     createdAt: string;
     updatedAt: string;
     lastValidatedAt?: string;
@@ -55,6 +57,15 @@ export interface Lesson {
     supersedes?: string[];
     conflictIds: string[];
 }
+export interface LessonFeedback {
+    useful: number;
+    notApplicable: number;
+    recent: Array<{
+        vote: 'useful' | 'not-applicable';
+        at: string;
+        note?: string;
+    }>;
+}
 /** 一条证据：只存脱敏摘要 + 定位信息。 */
 export interface Evidence {
     schemaVersion: 1;

package/lib/knowledge.js

@@ -161,6 +161,28 @@ function readReview(value) {
         review.resolution = resolution;
     return review;
 }
+function readFeedback(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value))
+        fail('feedback', '必须是对象');
+    for (const key of ['useful', 'notApplicable']) {
+        if (!Number.isSafeInteger(value[key]) || value[key] < 0)
+            fail('feedback.' + key, '必须是非负安全整数');
+    }
+    if (!Array.isArray(value.recent) || value.recent.length > 20)
+        fail('feedback.recent', '最多 20 条');
+    const recent = value.recent.map((item) => {
+        if (!isRecord(item) || (item.vote !== 'useful' && item.vote !== 'not-applicable'))
+            fail('feedback.recent.vote', '取值不合法');
+        const at = readIsoDate(item.at, 'feedback.recent.at', true);
+        const note = readString(item.note, 'feedback.recent.note');
+        if (note !== undefined && note.length > REVIEW_NOTE_MAX_LENGTH)
+            fail('feedback.recent.note', '超过长度上限');
+        return { vote: item.vote, at, ...(note === undefined ? {} : { note }) };
+    });
+    return { useful: value.useful, notApplicable: value.notApplicable, recent };
+}
 /** 当前内存模型 / 写盘的 lesson schemaVersion。 */
 export const LESSON_SCHEMA_VERSION = 1;
 /** 已知迁移链占位：v2 落地时在此登记；存储层默认只识别不自动迁移。 */
@@ -247,6 +269,9 @@ export function validateLesson(value, options = {}) {
         lesson.reviewAfter = reviewAfter;
     if (supersedes !== undefined)
         lesson.supersedes = supersedes;
+    const feedback = readFeedback(value.feedback);
+    if (feedback !== undefined)
+        lesson.feedback = feedback;
     return lesson;
 }
 /** 校验并归一化一条证据；失败抛 KnowledgeError('invalid')。未知字段会被丢弃。 */

package/lib/tools.d.ts

@@ -25,3 +25,5 @@ export interface DreamToolDefinition {
 export declare function buildDreamTools(config: ResolvedDreamConfig): DreamToolDefinition[];
 /** 把会话摘要拼成一段可读文本（供模型一次性阅读）。 */
 export declare function buildDigestText(digest: SessionDigest): string;
+/** actor comes from the trusted caller, never from tool or browser arguments. */
+export declare function executeDreamReview(cfg: ResolvedDreamConfig, rawArgs: unknown, exec: unknown, actor?: 'model' | 'human'): Promise<unknown>;

package/lib/tools.js

@@ -844,7 +844,6 @@ export function buildDreamTools(config) {
         },
         timeoutMs: 15000,
     };
-    const REVIEW_ACTIONS = ['accept', 'reject', 'reopen', 'mark-stale', 'mark-disputed', 'resolve-conflict', 'attach-evidence'];
     const dreamReview = {
         name: 'dream_review',
         description: '审梦：采纳/驳回/标记冲突或过期/追加验证证据，必须带 expectedRevision（revision 不符会拒绝且不写入）。模型调用 actor 一律记为 model，不得冒充用户采纳；attach-evidence 只追加证据，不自动改变 state。',
@@ -870,210 +869,7 @@ export function buildDreamTools(config) {
             },
         },
         async execute(rawArgs, exec) {
-            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({
-                action, lessonId, expectedRevision, conflictWith, resolution: resolutionArg ?? null, note: maskedNote ?? null,
-                evidence: evidenceInputs,
-            }));
-            // 模型调用永远记为 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 'reopen':
-                    if (before.state !== 'rejected')
-                        throw new KnowledgeError('invalid', 'reopen 只用于把已驳回经验重新送审。');
-                    lesson = store.reviewLesson(lessonId, 'unreviewed', expectedRevision, idempotencyKey, actor);
-                    break;
-                case 'mark-stale':
-                    lesson = 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, at: now, note: maskedNote, resolution: resolutionPayload };
-                                }
-                                else {
-                                    patch.state = 'rejected';
-                                    patch.review = { decision: 'rejected', actor: 'model', at: now, note: '冲突解析：败给 ' + lessonId, resolution: resolutionPayload };
-                                }
-                            }
-                            else if (isPrimary) {
-                                patch.state = 'rejected';
-                                patch.review = { decision: 'rejected', actor: 'model', at: now, note: '冲突解析：放弃本条目', resolution: resolutionPayload };
-                            }
-                            else {
-                                if (remainingOf(member).length === 0)
-                                    patch.state = 'usable';
-                                patch.review = { ...member.lesson.review, 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, at: now, note: '冲突解析：并入 ' + affectedIds.join('、'), resolution: resolutionPayload };
-                            }
-                            else {
-                                patch.state = 'stale';
-                                patch.review = { ...member.lesson.review, 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 };
+            return executeDreamReview(cfg, rawArgs, exec, 'model');
         },
         timeoutMs: 15000,
     };
@@ -1102,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 };
+}

package/lib/web-actions.d.ts

@@ -0,0 +1,11 @@
+import { type ResolvedDreamConfig } from './config.js';
+export declare const DREAM_ACTION_ROUTE = "/api/dsh-dream/actions";
+type Options = {
+    journalDir?: string;
+    config?: Record<string, unknown> | ResolvedDreamConfig | null;
+};
+/** Connection has authenticated the operator before this handler is called. */
+export declare function createDreamActionHandler(options?: Options): (request: Request) => Promise<Response>;
+/** No unauthenticated webServer fallback: old hosts keep their read-only panel. */
+export declare function installDreamActions(ctx: any, options?: Options): void;
+export {};