@stardustlc/dsh-dream 0.5.1 → 0.7.0

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 {};

package/lib/web-actions.js

@@ -0,0 +1,175 @@
+/** Mutations are mounted exclusively on Connection's authenticated Fetch carrier. */
+import { randomUUID } from 'node:crypto';
+import { realpathSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { resolveConfig } from './config.js';
+import { KnowledgeError } from './knowledge.js';
+import { KnowledgeStore } from './knowledge-store.js';
+import { maskSecrets } from './mask.js';
+import { buildDreamTools, executeDreamReview } from './tools.js';
+import { rollbackBridge } from './bridge.js';
+import { maskDeep } from './web.js';
+export const DREAM_ACTION_ROUTE = '/api/dsh-dream/actions';
+const BODY_LIMIT = 64 * 1024;
+const PREVIEW_LIFETIME = 10 * 60 * 1000;
+const MAX_PREVIEWS = 100;
+function json(status, value) {
+    return new Response(JSON.stringify(value), { status, headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' } });
+}
+function fail(status, code, message) {
+    return json(status, { ok: false, error: { code, message: maskSecrets(message) } });
+}
+function text(body, key) {
+    const value = body[key];
+    if (typeof value !== 'string' || value.trim() === '' || value.length > 2000)
+        throw new KnowledgeError('invalid', key + ' 必须是非空文本，最多 2000 字符');
+    return value.trim();
+}
+function checkRevision(store, body) {
+    const id = text(body, 'lessonId');
+    const lesson = store.getLesson(id);
+    if (lesson === undefined)
+        throw new KnowledgeError('invalid', '经验不存在，请刷新列表');
+    if (typeof body.expectedRevision !== 'number' || !Number.isInteger(body.expectedRevision) || body.expectedRevision < 1)
+        throw new KnowledgeError('invalid', '缺少有效的经验版本');
+    if (lesson.revision !== body.expectedRevision)
+        throw new KnowledgeError('revision', '经验已更新，请刷新后重新操作');
+    return lesson;
+}
+/** Connection has authenticated the operator before this handler is called. */
+export function createDreamActionHandler(options = {}) {
+    const cfg = { ...resolveConfig(options.config), ...(options.journalDir === undefined ? {} : { journalDir: options.journalDir }) };
+    const store = new KnowledgeStore(join(cfg.journalDir, 'knowledge'), { maskSecrets: cfg.maskSecrets });
+    const bridge = buildDreamTools(cfg).find(tool => tool.name === 'dream_bridge');
+    const previews = new Map();
+    return async (request) => {
+        if (request.method !== 'POST')
+            return fail(405, 'method', '请使用 POST');
+        if (request.headers.get('content-type')?.split(';', 1)[0]?.trim().toLowerCase() !== 'application/json')
+            return fail(415, 'content-type', '需要 application/json');
+        // A web form or cross-origin simple request cannot supply this header.
+        if (request.headers.get('x-dsh-dream-action') !== '1')
+            return fail(403, 'forbidden', '请从 Dream 面板操作');
+        const site = request.headers.get('sec-fetch-site');
+        if (site !== null && site !== 'same-origin' && site !== 'none')
+            return fail(403, 'forbidden', '拒绝跨站操作');
+        const origin = request.headers.get('origin');
+        if (origin !== null && /^https?:/i.test(origin)) {
+            try {
+                // The official node:http bridge intentionally uses http://dsh.internal
+                // as its Fetch URL base; the preserved Host is the original authority.
+                const host = request.headers.get('host');
+                const authority = host === null ? new URL(request.url).host : new URL('http://' + host).host;
+                if (new URL(origin).host !== authority)
+                    return fail(403, 'forbidden', '拒绝跨源操作');
+            }
+            catch {
+                return fail(403, 'forbidden', '无效来源');
+            }
+        }
+        try {
+            const reader = request.body?.getReader();
+            if (reader === undefined)
+                return fail(400, 'invalid', '缺少请求内容');
+            const chunks = [];
+            let size = 0;
+            try {
+                for (;;) {
+                    const part = await reader.read();
+                    if (part.done)
+                        break;
+                    size += part.value.byteLength;
+                    if (size > BODY_LIMIT) {
+                        await reader.cancel();
+                        return fail(413, 'too-large', '请求内容超过 64 KB');
+                    }
+                    chunks.push(part.value);
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+            let raw;
+            try {
+                raw = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            }
+            catch {
+                return fail(400, 'invalid', '请求不是有效 JSON');
+            }
+            if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+                return fail(400, 'invalid', '请求必须是对象');
+            const body = raw;
+            if (request.signal.aborted)
+                return fail(409, 'cancelled', '操作已取消');
+            const operation = text(body, 'operation');
+            if (operation === 'review') {
+                if (!['accept', 'reject', 'reopen', 'mark-stale', 'resolve-conflict'].includes(String(body.action)))
+                    throw new KnowledgeError('invalid', '不支持此页面审阅动作');
+                checkRevision(store, body);
+                const result = await executeDreamReview(cfg, body, undefined, 'human');
+                return json(200, maskDeep(result));
+            }
+            if (operation === 'feedback') {
+                // The store checks revision inside its lock and keeps retry keys idempotent.
+                const id = text(body, 'lessonId');
+                const key = text(body, 'requestId');
+                if (!/^[a-zA-Z0-9_-]{8,100}$/.test(key))
+                    throw new KnowledgeError('invalid', '反馈请求标识无效');
+                const note = body.note === undefined ? undefined : text(body, 'note');
+                const lesson = store.recordFeedback(id, body.vote, note, body.expectedRevision, 'web-feedback:' + key);
+                return json(200, maskDeep({ ok: true, lesson, message: '已记录使用反馈，审阅状态保持原样' }));
+            }
+            for (const [key, value] of previews)
+                if (value.expires < Date.now())
+                    previews.delete(key);
+            if (operation === 'preview') {
+                const lesson = checkRevision(store, body);
+                const root = lesson.scope.workspaceRoot;
+                if (root === undefined || !isAbsolute(root))
+                    throw new KnowledgeError('invalid', '这条经验没有项目目录，请在对应项目的对话中预览规则');
+                const canonicalRoot = realpathSync(root);
+                const result = await bridge.execute({ mode: 'preview', lessonIds: [lesson.id], path: 'AGENTS.md', projectId: lesson.scope.projectId }, { cwd: canonicalRoot });
+                if (result.ok !== true)
+                    return json(409, maskDeep(result));
+                if (result.lessons.length === 0)
+                    return fail(409, 'ineligible', '当前经验不满足写入资格，请先查看适用范围与审阅状态');
+                while (previews.size >= MAX_PREVIEWS)
+                    previews.delete(previews.keys().next().value);
+                const token = randomUUID();
+                previews.set(token, { expires: Date.now() + PREVIEW_LIFETIME, root: canonicalRoot, lessonId: lesson.id, revision: lesson.revision, projectId: lesson.scope.projectId, sha: result.expected.sha256, previewId: result.previewId });
+                return json(200, { ...maskDeep(result), token });
+            }
+            if (operation === 'apply') {
+                const token = text(body, 'token');
+                const preview = previews.get(token);
+                if (preview === undefined)
+                    return fail(409, 'preview-expired', '预览已过期，请重新预览');
+                const lesson = checkRevision(store, { lessonId: preview.lessonId, expectedRevision: preview.revision });
+                if (realpathSync(lesson.scope.workspaceRoot) !== preview.root)
+                    return fail(409, 'revision', '项目目录已变化，请重新预览');
+                const result = await bridge.execute({ mode: 'apply', lessonIds: [preview.lessonId], path: 'AGENTS.md', projectId: preview.projectId, expectedSha256: preview.sha, previewId: preview.previewId }, { cwd: preview.root });
+                previews.delete(token);
+                return json(result.ok === true ? 200 : 409, maskDeep(result));
+            }
+            if (operation === 'rollback') {
+                const result = rollbackBridge({ journalDir: cfg.journalDir, projectRoot: '', backupId: text(body, 'backupId') });
+                return json(result.ok === true ? 200 : 409, maskDeep(result));
+            }
+            throw new KnowledgeError('invalid', '不支持此操作');
+        }
+        catch (error) {
+            if (error instanceof KnowledgeError)
+                return fail(error.code === 'revision' || error.code === 'duplicate' ? 409 : error.code === 'io' ? 500 : 400, error.code, error.message);
+            return fail(500, 'io', '操作失败：' + (error instanceof Error ? error.message : String(error)));
+        }
+    };
+}
+/** No unauthenticated webServer fallback: old hosts keep their read-only panel. */
+export function installDreamActions(ctx, options = {}) {
+    const fetch = createDreamActionHandler(options);
+    ctx.inject(['connection'], (host) => {
+        if (typeof host.connection?.fetch?.register !== 'function')
+            return;
+        host.connection.fetch.register({ path: DREAM_ACTION_ROUTE, methods: ['POST'], requestBody: 'buffered', fetch });
+    });
+}

package/lib/web.d.ts

@@ -5,6 +5,8 @@ import type { Evidence, Lesson } from './knowledge.js';
 export declare const DREAM_ROUTE = "/_dsh/dsh-dream/journal";
 /** M1 经验面板的只读路由。 */
 export declare const DREAM_KNOWLEDGE_ROUTE = "/_dsh/dsh-dream/knowledge";
+/** M2 写入记录面板的只读路由。 */
+export declare const DREAM_BRIDGE_ROUTE = "/_dsh/dsh-dream/bridge";
 /** ?limit 的默认值与上下界。 */
 export declare const DREAM_LIMIT_DEFAULT = 50;
 export declare const DREAM_LIMIT_MIN = 1;
@@ -53,30 +55,77 @@ export interface KnowledgeReader {
     listEvidence(): Evidence[];
     stats(): KnowledgeWebStats;
 }
+/** 写入记录的单条视图（展示用；字段缺失时按空字符串 / false 归一化）。 */
+export interface BridgeWebLessonRef {
+    lessonId: string;
+    revision: number;
+}
+export interface BridgeWebRecord {
+    backupId: string;
+    at: string;
+    target: string;
+    action: string;
+    lessons: BridgeWebLessonRef[];
+    beforeSha256: string;
+    afterSha256: string;
+    rollbackable: boolean;
+    rollbackReason?: string;
+}
+/** 写入记录路由的 JSON 形状：脱敏后的应用记录 + 汇总。 */
+export interface BridgeWebPayload {
+    records: BridgeWebRecord[];
+    stats: {
+        total: number;
+        rollbackable: number;
+    };
+}
+/** 桥接存储层返回的原始记录形状（字段由 src/bridge.ts 负责）。 */
+export type BridgeApplicationView = Record<string, unknown>;
+/** 只读桥接记录源的最小接口：方便测试注入假数据。 */
+export interface BridgeReader {
+    listApplications(): BridgeApplicationView[];
+}
 /** 安装参数；journalDir 缺省时从 config 解析。 */
 export interface DreamWebOptions {
     /** 梦境日记目录（优先）。 */
     journalDir?: string;
     /** 知识目录（优先；缺省 = <journalDir>/knowledge）。 */
     knowledgeDir?: string;
+    /** 桥接记录目录（优先；缺省 = <journalDir>/bridge）。 */
+    bridgeDir?: string;
     /** 插件配置，用来兜底 journalDir（resolveConfig 的入参）。 */
     config?: Record<string, unknown> | ResolvedDreamConfig | null;
     /** 测试注入：返回只读知识源；提供时不做目录存在性检查。 */
     knowledgeStoreFactory?: (knowledgeDir: string) => KnowledgeReader;
+    /** 测试注入：返回只读桥接记录源；提供时不做目录存在性检查。 */
+    bridgeStoreFactory?: (bridgeDir: string) => BridgeReader;
 }
 /** ?limit 解析：缺省/非数字 → fallback；越界钳制到 [1, 500]。 */
 export declare function limitFromQuery(raw: unknown, fallback?: number): number;
 /** 解析后的 knowledgeDir：显式路径优先，否则 = <journalDir>/knowledge。 */
 export declare function knowledgeDirOf(options: DreamWebOptions, journalDir?: string): string;
+/** 解析后的 bridgeDir：显式路径优先，否则 = <journalDir>/bridge。 */
+export declare function bridgeDirOf(options: DreamWebOptions, journalDir?: string): string;
+/** 递归脱敏；结构化绝对路径按目录分段，避免 Unix 分隔符把正常路径连成长令牌。 */
+export declare function maskDeep<T>(value: T, key?: string): T;
 /** 知识目录不存在（或尚未建立）时的空载荷：不写盘、不报 404。 */
 export declare function emptyKnowledgePayload(): KnowledgeWebPayload;
+/**
+ * 归一化桥接应用记录：只保留展示需要的字段，坏形状跳过。
+ * 数据源由 src/bridge.ts 负责（本层不做 IO、不重算可否回滚）。
+ */
+export declare function normalizeBridgeApplications(value: unknown): BridgeWebRecord[];
+/** 写入记录目录不存在时的空载荷。 */
+export declare function emptyBridgePayload(): BridgeWebPayload;
 /** 组装梦境日记路由处理器；journalDir 在这一刻定下来（与插件的配置生命周期一致）。 */
 export declare function createDreamWebHandler(options?: DreamWebOptions): (req: any, res: any) => Promise<void>;
+/** 组装只读写入记录路由处理器；零写盘：目录不存在就直接返回空结果。 */
+export declare function createBridgeWebHandler(options?: DreamWebOptions): (req: any, res: any) => Promise<void>;
 /** 组装只读经验路由处理器；零写盘：目录不存在就直接返回空结果。 */
 export declare function createKnowledgeWebHandler(options?: DreamWebOptions): (req: any, res: any) => Promise<void>;
 /**
  * 把只读路由挂到宿主 webserver 上。
  * 与 dsh-calendar 相同：ctx.inject(['webServer']) + effect 注册，插件卸载即摘掉路由；
- * 同一个 effect 里注册日记与知识两条 exact 路由，卸载时一起释放。
+ * 同一个 effect 里注册日记 / 知识 / 写入记录三条 exact 路由，卸载时一起释放。
  */
 export declare function installDreamWeb(ctx: any, options?: DreamWebOptions): void;

package/lib/web.js

@@ -6,25 +6,28 @@
  * 三道门缺一不可 ——
  *   1. remoteAddress 若是明确的非回环地址则拒绝（局域网不可达）；
  *   2. Host 头必须是 localhost 名（挡 DNS rebinding：恶意域名解析到 127.0.0.1）；
- *   3. 只接受 GET：两条路由都没有任何写路径，所以不需要 CSRF 那一套。
+ *   3. 只接受 GET：三条路由都没有任何写路径，所以不需要 CSRF 那一套。
  *
- * 零写盘纪律（M1）：知识路由只读 <journalDir>/knowledge/。目录不存在时直接返回
- * 空 lessons/evidence + 全零 stats，绝不为了读去 mkdir 或 rebuildIndex；重建索引
- * 只发生在写路径或显式维护操作里。
+ * 零写盘纪律（M1/M2）：知识路由只读 <journalDir>/knowledge/，写入记录路由只读
+ * <journalDir>/bridge/。目录不存在时直接返回空结果，绝不为了读去 mkdir 或 rebuildIndex；
+ * 重建索引只发生在写路径或显式维护操作里。
  *
  * @module dsh-dream/web
  */
 import { existsSync } from 'node:fs';
-import { join } from 'node:path';
+import { isAbsolute, join, win32 } from 'node:path';
+import * as bridgeModule from './bridge.js';
 import { resolveConfig } from './config.js';
 import { dreamStats, readDreams, searchDreams } from './journal.js';
 import { KnowledgeStore } from './knowledge-store.js';
-import { maskSecrets } from './mask.js';
+import { isDreamReference, maskSecrets } from './mask.js';
 import { buildEvidenceSummary, lessonScopeLabel } from './retrieval.js';
 /** 面板与浏览器说话的同源路由。 */
 export const DREAM_ROUTE = '/_dsh/dsh-dream/journal';
 /** M1 经验面板的只读路由。 */
 export const DREAM_KNOWLEDGE_ROUTE = '/_dsh/dsh-dream/knowledge';
+/** M2 写入记录面板的只读路由。 */
+export const DREAM_BRIDGE_ROUTE = '/_dsh/dsh-dream/bridge';
 /** ?limit 的默认值与上下界。 */
 export const DREAM_LIMIT_DEFAULT = 50;
 export const DREAM_LIMIT_MIN = 1;
@@ -71,6 +74,12 @@ export function knowledgeDirOf(options, journalDir = journalDirOf(options)) {
         return options.knowledgeDir;
     return join(journalDir, 'knowledge');
 }
+/** 解析后的 bridgeDir：显式路径优先，否则 = <journalDir>/bridge。 */
+export function bridgeDirOf(options, journalDir = journalDirOf(options)) {
+    if (typeof options.bridgeDir === 'string' && options.bridgeDir.trim() !== '')
+        return options.bridgeDir;
+    return join(journalDir, 'bridge');
+}
 /** 解析请求 URL；非法或缺失时退回路由本身（等价于没有查询参数）。 */
 function requestUrl(raw, fallback = DREAM_ROUTE) {
     const text = typeof raw === 'string' && raw !== '' ? raw : fallback;
@@ -125,16 +134,28 @@ function requestGate(req, res, readOnlyMessage) {
     }
     return false;
 }
-/** 递归脱敏所有字符串叶子；数字 / 布尔 / null 原样保留。 */
-function maskDeep(value) {
-    if (typeof value === 'string')
+/** 哈希字段不做二次脱敏：它们是校验值，不是密钥（面板要展示前 12 位）。 */
+const HASH_KEY_RE = /^(?:sourceHash|beforeSha256|afterSha256|afterBlockSha256|afterFileSha256|sha256)$/;
+const REFERENCE_KEYS = new Set(['id', 'lessonId', 'lessonIds', 'evidenceIds', 'conflictIds', 'supersedes', 'targetId', 'affectedIds', 'backupId', 'previewId']);
+const PATH_KEYS = new Set(['target', 'path', 'resolvedPath', 'workspaceRoot']);
+/** 递归脱敏；结构化绝对路径按目录分段，避免 Unix 分隔符把正常路径连成长令牌。 */
+export function maskDeep(value, key) {
+    if (typeof value === 'string') {
+        if (key !== undefined && HASH_KEY_RE.test(key) && /^[0-9a-f]{64}$/i.test(value))
+            return value;
+        if (key !== undefined && REFERENCE_KEYS.has(key) && isDreamReference(value))
+            return value;
+        if (key !== undefined && PATH_KEYS.has(key) && (isAbsolute(value) || win32.isAbsolute(value)) && !/[\x00-\x1f]/.test(value)) {
+            return value.split(/([\\/]+)/).map((part) => maskSecrets(part)).join('');
+        }
         return maskSecrets(value);
+    }
     if (Array.isArray(value))
-        return value.map((item) => maskDeep(item));
+        return value.map((item) => maskDeep(item, key));
     if (value !== null && typeof value === 'object') {
         const out = {};
-        for (const [key, item] of Object.entries(value))
-            out[key] = maskDeep(item);
+        for (const [entryKey, item] of Object.entries(value))
+            out[entryKey] = maskDeep(item, entryKey);
         return out;
     }
     return value;
@@ -173,6 +194,86 @@ export function emptyKnowledgePayload() {
         stats: normalizeKnowledgeStats(null),
     };
 }
+function asDisplayString(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function asDisplayRevision(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? Math.floor(value) : 0;
+}
+/**
+ * 归一化桥接应用记录：只保留展示需要的字段，坏形状跳过。
+ * 数据源由 src/bridge.ts 负责（本层不做 IO、不重算可否回滚）。
+ */
+export function normalizeBridgeApplications(value) {
+    if (!Array.isArray(value))
+        return [];
+    const records = [];
+    for (const raw of value) {
+        if (raw === null || typeof raw !== 'object')
+            continue;
+        const item = raw;
+        const backupId = asDisplayString(item.backupId);
+        const target = asDisplayString(item.target);
+        if (backupId === '' && target === '')
+            continue;
+        const lessons = [];
+        if (Array.isArray(item.lessons)) {
+            for (const entry of item.lessons) {
+                if (entry !== null && typeof entry === 'object') {
+                    const ref = entry;
+                    const lessonId = asDisplayString(ref.lessonId);
+                    if (lessonId === '')
+                        continue;
+                    lessons.push({ lessonId, revision: asDisplayRevision(ref.revision) });
+                }
+                else {
+                    const text = asDisplayString(entry);
+                    if (text === '')
+                        continue;
+                    const match = /^(.*)@(\d+)$/.exec(text);
+                    if (match !== null)
+                        lessons.push({ lessonId: match[1], revision: Number(match[2]) });
+                    else
+                        lessons.push({ lessonId: text, revision: 0 });
+                }
+            }
+        }
+        const record = {
+            backupId,
+            at: asDisplayString(item.at),
+            target,
+            action: asDisplayString(item.action),
+            lessons,
+            beforeSha256: asDisplayString(item.beforeSha256),
+            afterSha256: asDisplayString(item.afterSha256),
+            rollbackable: item.rollbackable === true,
+        };
+        const reason = asDisplayString(item.rollbackReason);
+        if (reason !== '')
+            record.rollbackReason = reason;
+        records.push(record);
+    }
+    return records;
+}
+/** 写入记录目录不存在时的空载荷。 */
+export function emptyBridgePayload() {
+    return {
+        records: [],
+        stats: { total: 0, rollbackable: 0 },
+    };
+}
+/**
+ * 从桥接存储层取原始记录（按 at 降序，只读零写盘）。
+ * 契约来源：M2-A，`listBridgeApplications(journalDir): BridgeApplicationView[]`；
+ * 未落地 / 未导出时安全返回空，路由不受影响。
+ */
+function readBridgeApplicationsFromStore(journalDir) {
+    const candidate = bridgeModule.listBridgeApplications;
+    if (typeof candidate !== 'function')
+        return [];
+    const result = candidate(journalDir);
+    return Array.isArray(result) ? result : [];
+}
 /** 组装梦境日记路由处理器；journalDir 在这一刻定下来（与插件的配置生命周期一致）。 */
 export function createDreamWebHandler(options = {}) {
     const journalDir = journalDirOf(options);
@@ -192,6 +293,39 @@ export function createDreamWebHandler(options = {}) {
         }
     };
 }
+/** 组装只读写入记录路由处理器；零写盘：目录不存在就直接返回空结果。 */
+export function createBridgeWebHandler(options = {}) {
+    const journalDir = journalDirOf(options);
+    const bridgeDir = bridgeDirOf(options, journalDir);
+    return async (req, res) => {
+        if (requestGate(req, res, 'dsh-dream bridge route is read-only; use GET'))
+            return;
+        try {
+            let raw;
+            if (options.bridgeStoreFactory !== undefined) {
+                raw = options.bridgeStoreFactory(bridgeDir).listApplications();
+            }
+            else if (existsSync(bridgeDir)) {
+                raw = readBridgeApplicationsFromStore(journalDir);
+            }
+            else {
+                raw = [];
+            }
+            const records = normalizeBridgeApplications(raw).map((record) => maskDeep(record));
+            const payload = {
+                records,
+                stats: {
+                    total: records.length,
+                    rollbackable: records.filter((record) => record.rollbackable).length,
+                },
+            };
+            responseJson(res, 200, payload);
+        }
+        catch (error) {
+            internalError(res, error);
+        }
+    };
+}
 /** 组装只读经验路由处理器；零写盘：目录不存在就直接返回空结果。 */
 export function createKnowledgeWebHandler(options = {}) {
     const knowledgeDir = knowledgeDirOf(options);
@@ -228,7 +362,7 @@ export function createKnowledgeWebHandler(options = {}) {
 /**
  * 把只读路由挂到宿主 webserver 上。
  * 与 dsh-calendar 相同：ctx.inject(['webServer']) + effect 注册，插件卸载即摘掉路由；
- * 同一个 effect 里注册日记与知识两条 exact 路由，卸载时一起释放。
+ * 同一个 effect 里注册日记 / 知识 / 写入记录三条 exact 路由，卸载时一起释放。
  */
 export function installDreamWeb(ctx, options = {}) {
     if (ctx === null || ctx === undefined || typeof ctx.inject !== 'function') {
@@ -236,6 +370,7 @@ export function installDreamWeb(ctx, options = {}) {
     }
     const journalHandler = createDreamWebHandler(options);
     const knowledgeHandler = createKnowledgeWebHandler(options);
+    const bridgeHandler = createBridgeWebHandler(options);
     ctx.inject(['webServer'], (webCtx) => {
         webCtx.effect(() => {
             const disposers = [
@@ -249,6 +384,11 @@ export function installDreamWeb(ctx, options = {}) {
                     path: DREAM_KNOWLEDGE_ROUTE,
                     handler: (req, res) => knowledgeHandler(req, res),
                 }, 'dsh-dream: knowledge route'),
+                webCtx.webServer.register({
+                    kind: 'exact',
+                    path: DREAM_BRIDGE_ROUTE,
+                    handler: (req, res) => bridgeHandler(req, res),
+                }, 'dsh-dream: bridge log route'),
             ];
             return () => {
                 for (const dispose of disposers) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stardustlc/dsh-dream",
-  "version": "0.5.1",
-  "description": "DSH 做梦插件：会话间隙回放近期对话、反思写入梦境日记，并把高频教训幂等桥接进 AGENTS.md；默认隐私脱敏，零运行时依赖。",
+  "version": "0.7.0",
+  "description": "DSH 做梦与经验记忆：核验来源、审阅经验，预览写入 AGENTS.md 并支持回滚；附梦境日记面板，默认隐私脱敏，零运行时依赖。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/skills/dream-protocol/SKILL.md

@@ -40,7 +40,7 @@ description: 做梦协议：任务开始取回适用经验，长任务收尾沉
   - `verification`：`read` = 你或插件读到了原记录；`claimed` = 仅模型声称。**claimed 只计入证据列表，不计入独立支持数。**
 - **只有真的读到来源（会话记录 / 本地验证产物 / 用户明确纠正）才能标 read，自我判断一律 claimed**（"我记得""应该是"都算 claimed）；标错 read 等于自我提权，禁止。
 - 没有证据的观察只能是 candidate，不能写成确定事实，也不能说成「已验证」。
-- 例外：证据为 `kind: "user-correction"` 且 `verification: "read"`（读到用户纠正原文）时，该经验初始状态直接是 `usable`，`review` 记 `actor: "user"`、`decision: "accepted"`——用户决定优先于模型推测；其余证据一律从 `candidate` 起，claimed 不计独立支持、也不能覆盖用户纠正。
+- 所有新经验都先进入 candidate，包括已读到的用户纠正。read 只表示插件成功核对来源，不表示用户采纳；工具审阅记录 actor:model，不能冒充真人。会话证据须给 sessionId、recordSeq、可匹配 quote（缺省使用 summary）；本地产物须给工作目录内的 artifactPath。插件独立核对项目、角色和原文，计算 sourceHash；失败降为 claimed 并给 verificationReason。
 - 用户明确采纳/驳回、发现经验互相冲突、依赖升级后旧经验需要复核 → 用 `dream_review`（必须带 `expectedRevision`）。
 - 用户采纳必须来自真实用户指令；模型自己不能冒充 `actor: user`。
 - 同一证据重复提交是幂等的，不会增加独立支持数。**禁止靠反复调用 `dream_save` 或 `dream_learn` 刷次数**——次数不等于正确，也不等于重要。
@@ -49,7 +49,8 @@ description: 做梦协议：任务开始取回适用经验，长任务收尾沉
 
 - 只沉淀规律与偏好，不复述流水账；`reflection` 用第一人称写你的观察与感受；
 - `lessons` 是 1–5 条可执行教训，每条以动词开头；拿不准就标注「存疑」；
-- **不得把主观反思升级成 AGENTS.md 指令**：不要用 `dream_bridge` 把未经审阅的感悟写成项目规则。桥接只能用于已采纳、当前项目范围、附证据的经验。
+- **不得把主观反思升级成 AGENTS.md 指令**：不要用 `dream_bridge` 把未经审阅的感悟写成项目规则。桥接只能用于 `usable`、当前项目范围（或显式 global 且 review.decision 为 accepted）、附证据的经验；频次不再作为准入条件。
+- **桥接三步（M2）**：`mode:"preview"` 只读返回 diff / 参与经验 / skipped 原因（零写入）→ 人工复核 → `mode:"apply"` 必须带预览的 `expectedSha256`（新文件为 null），建议同时带 `previewId`（文件被并发修改则 `conflict` 且零写入）；`mode:"rollback"` 只在当前管理块仍等于该次 apply 结果时回滚。缺省不传 `mode` 仍是 0.5.x 直写并返回弃用提示；新流程一律显式 preview → apply。写入内容统一过 `mask.ts`。
 
 ## 何时做梦
 
@@ -62,6 +63,8 @@ description: 做梦协议：任务开始取回适用经验，长任务收尾沉
 - 想在日记里找原话 → `dream_recall`；
 - 想取少量可复用经验 → `dream_context`（带范围与预算，只读）；
 - 想查看/审阅候选、处理冲突 → `dream_review`；
+- attach-evidence 只补充核验后的证据，不自动采纳；resolve-conflict 必须给 resolution、affectedIds、note，整组原子更新；reopen 将驳回经验重新送审。
+
 - 面板查看：「设置 → 梦境日记」里有只读的梦境时间线与「经验」区块（状态、适用条件、证据摘要、最近核验时间），面板不提供任何写操作。
 
 ---
@@ -103,7 +106,7 @@ Dreams and **lessons** are two separate pipelines: a **first-person reflection**
   - `verification`: `read` = the record was actually read; `claimed` = the model merely asserts it. **Claimed evidence does not count toward independent support.**
 - **Only mark read when the source was actually read (session record / local artifact / explicit user correction); anything self-asserted is claimed.** Marking read without a source is self-promotion and is forbidden.
 - An observation without evidence stays a candidate: do not present it as a fact, and never call it "verified".
-- Exception: when the evidence is `kind: "user-correction"` with `verification: "read"` (the user's correction was actually read), the lesson starts as `usable` and `review` records `actor: "user"` / `decision: "accepted"` — a user decision outranks model inference. All other evidence starts as `candidate`; claimed evidence does not count toward independent support and cannot override a user correction.
+- Every new lesson starts as a candidate, including verified user corrections. Read means the plugin checked the source, not that a user accepted the lesson; tool review records actor:model. Session evidence needs sessionId, recordSeq and a matching quote (summary if omitted). Artifacts need artifactPath inside the working directory. The plugin checks project, role and text and computes sourceHash; failures become claimed with verificationReason.
 - For explicit acceptance/rejection, conflicts between lessons, or re-validation after dependency upgrades → call `dream_review` with an `expectedRevision`.
 - User acceptance must come from a real user instruction; the model must not impersonate `actor: user`.
 - Submitting the same evidence twice is idempotent and does not increase independent support. **Never grind counts by calling `dream_save` or `dream_learn` repeatedly** — frequency is neither correctness nor importance.
@@ -112,7 +115,8 @@ Dreams and **lessons** are two separate pipelines: a **first-person reflection**
 
 - Consolidate patterns and preferences only — never a running transcript. Write `reflection` in the first person.
 - `lessons` are 1–5 actionable items; mark uncertain ones as "tentative".
-- **Never promote a subjective reflection into an AGENTS.md instruction**: do not use `dream_bridge` to write unreviewed reflections into project rules. Bridging is for accepted, project-scoped, evidence-backed lessons only.
+- **Never promote a subjective reflection into an AGENTS.md instruction**: do not use `dream_bridge` to write unreviewed reflections into project rules. Bridging is for `usable`, project-scoped (or explicit global with review.decision accepted), evidence-backed lessons only; frequency is no longer an admission criterion.
+- **Bridge in three steps (M2)**: `mode:"preview"` returns the diff / selected lessons / skipped reasons read-only (zero writes) → human review → `mode:"apply"` with the preview’s required `expectedSha256` (null for a new file); include `previewId` to bind the preview (a concurrent edit yields `conflict` and zero writes); `mode:"rollback"` only rolls back while the current managed block still equals that apply result. Omitting `mode` keeps the 0.5.x direct write and returns a deprecation notice; new flows should always use preview → apply. Everything written is masked via `mask.ts`.
 
 ## When to dream
 
@@ -125,4 +129,5 @@ Dreams and **lessons** are two separate pipelines: a **first-person reflection**
 - Looking for exact words in the journal → `dream_recall`;
 - Retrieving a few reusable lessons → `dream_context` (scoped, budgeted, read-only);
 - Browsing or reviewing candidates and conflicts → `dream_review`;
+- attach-evidence adds verified sources without promoting state. resolve-conflict requires resolution, affectedIds and note and updates the group atomically. reopen sends a rejected lesson back for review.
 - To browse: **Settings → Dream journal** shows the read-only dream timeline and a **Lessons** block (state, applicability, evidence summary, last validated time). The panel has no write actions.