@stardustlc/dsh-dream 0.8.1 → 0.9.0

package/lib/knowledge-store.d.ts

@@ -1,4 +1,11 @@
 import { type Evidence, type EvidenceInput, type Lesson, type LessonInput, type LessonReviewResolution, type LessonState, type ReviewDecision } from './knowledge.js';
+type MemorySnapshot = {
+    sourceKey: string;
+    lessons: Lesson[];
+    evidence: Evidence[];
+    badLines: number;
+    complete: boolean;
+};
 /** events.jsonl 默认最多回放的行数（有界读取）。 */
 export declare const MAX_REPLAY_EVENTS = 200000;
 /** KnowledgeStore 构造选项（都可省略，保持 FREEZE 的 constructor(knowledgeDir) 可用）。 */
@@ -37,6 +44,9 @@ export declare class KnowledgeStore {
     listLessons(): Lesson[];
     /** 全部证据，按 observedAt 升序（同刻按 id 稳定排序）。 */
     listEvidence(): Evidence[];
+    /** Content-addressed, immutable snapshot. Hashes also detect same-size, same-mtime writes. */
+    readSnapshot(): MemorySnapshot;
+    private sourceFingerprint;
     /** 按 id 取经验；不存在返回 undefined。 */
     getLesson(id: string): Lesson | undefined;
     /** 追加证据；同 sessionId+recordSeq 或同 sourceHash 视为重复，返回已有记录且不写。 */
@@ -71,7 +81,7 @@ export declare class KnowledgeStore {
         id: string;
         patch: Partial<Lesson>;
         expectedRevision: number;
-    }>, idempotencyKey: string): Lesson[];
+    }>, idempotencyKey: string, candidateReview?: 'accepted' | 'rejected'): Lesson[];
     /** 状态迁移；不允许的迁移抛 KnowledgeError('invalid') 且不写。 */
     applyTransition(id: string, to: LessonState, expectedRevision: number, idempotencyKey: string): Lesson;
     /** 从事件完整重建派生索引与 checkpoint；不删除、不改写 events.jsonl / evidence.jsonl。 */
@@ -188,3 +198,4 @@ export declare class KnowledgeStore {
     private writeIndex;
     private writeIndexStrict;
 }
+export {};

package/lib/knowledge-store.js

@@ -22,6 +22,16 @@ import { join } from 'node:path';
 import { StringDecoder } from 'node:string_decoder';
 import { KnowledgeError, canTransition, evidenceNaturalKey, evidenceSessionKey, lessonFingerprint, mergeEvidenceSupport, validateEvidence, validateLesson, } from './knowledge.js';
 import { maskSecrets } from './mask.js';
+import { memoryDirectory } from './memory.js';
+const snapshots = new Map();
+function freezeTree(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const child of Object.values(value))
+            freezeTree(child);
+        Object.freeze(value);
+    }
+    return value;
+}
 /** events.jsonl 默认最多回放的行数（有界读取）。 */
 export const MAX_REPLAY_EVENTS = 200000;
 const PREFIX_HASH_BYTES = 64 * 1024;
@@ -336,6 +346,53 @@ export class KnowledgeStore {
             .map((item) => clone(item))
             .sort((a, b) => (a.observedAt === b.observedAt ? a.id.localeCompare(b.id) : a.observedAt.localeCompare(b.observedAt)));
     }
+    /** Content-addressed, immutable snapshot. Hashes also detect same-size, same-mtime writes. */
+    readSnapshot() {
+        const key = this.sourceFingerprint();
+        const cacheKey = this.dir + ':' + this.maxReplayEvents;
+        const cached = snapshots.get(cacheKey);
+        if (cached?.sourceKey === key)
+            return cached;
+        snapshots.delete(cacheKey);
+        // Cold reads verify the authority, including edits in the middle of a
+        // legacy checkpoint's prefix/tail guards. Warm reads only hash the files.
+        const state = this.mergeEvidenceFile(this.loadEventsBounded(0));
+        if (this.sourceFingerprint() !== key)
+            throw new KnowledgeError('io', '记忆正在更新，请稍后重试');
+        const snapshot = freezeTree({ sourceKey: key, lessons: [...state.lessons.values()], evidence: [...state.evidence.values()], badLines: state.badLines,
+            complete: state.idempotencyComplete && state.orphanEvents === 0 && state.unsupportedVersions === 0 && state.skippedEvents === 0 });
+        if (snapshots.size >= 16)
+            snapshots.delete(snapshots.keys().next().value);
+        snapshots.set(cacheKey, snapshot);
+        return snapshot;
+    }
+    sourceFingerprint() {
+        const digest = createHash('sha256'), buffer = Buffer.allocUnsafe(64 * 1024);
+        for (const file of [this.eventsPath, this.evidencePath, this.indexPath]) {
+            digest.update(file);
+            let fd;
+            try {
+                fd = openSync(file, 'r');
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    digest.update(':missing');
+                    continue;
+                }
+                throw error;
+            }
+            try {
+                let count;
+                while ((count = readSync(fd, buffer, 0, buffer.length, null)) > 0)
+                    digest.update(buffer.subarray(0, count));
+                digest.update(':end');
+            }
+            finally {
+                closeSync(fd);
+            }
+        }
+        return digest.digest('hex');
+    }
     /** 按 id 取经验；不存在返回 undefined。 */
     getLesson(id) {
         const state = this.loadEvents();
@@ -693,7 +750,7 @@ export class KnowledgeStore {
      * 批量原子更新（M2-②）：一个事件承载全部变更；先统一校验，
      * 任一条不通过 → 零写入并抛 KnowledgeError（details.failedId）。
      */
-    updateLessonsBatch(updates, idempotencyKey) {
+    updateLessonsBatch(updates, idempotencyKey, candidateReview) {
         assertIdempotencyKey(idempotencyKey);
         if (!Array.isArray(updates) || updates.length === 0)
             throw new KnowledgeError('invalid', 'updates 必须是非空数组');
@@ -707,6 +764,7 @@ export class KnowledgeStore {
         }
         const requestHash = this.hashRequest({
             operation: 'lesson.batch',
+            ...(candidateReview === undefined ? {} : { candidateReview }),
             updates: updates.map((update) => ({ id: update.id, expectedRevision: update.expectedRevision, patch: this.hashablePatch(update.patch) })),
         });
         return this.withLock((touch) => {
@@ -721,6 +779,7 @@ export class KnowledgeStore {
             }
             const now = new Date().toISOString();
             const planned = [];
+            let reviewGroup;
             for (const update of updates) {
                 const previous = state.lessons.get(update.id);
                 if (previous === undefined)
@@ -733,6 +792,18 @@ export class KnowledgeStore {
                     });
                 }
                 const clean = this.cleanPatch(update.patch);
+                if (candidateReview !== undefined) {
+                    if (previous.state !== 'candidate' || previous.conflictIds.length)
+                        throw new KnowledgeError('invalid', '批量审阅只接受没有冲突的候选，请逐条核对其他记录');
+                    const group = JSON.stringify([previous.kind, previous.scope.global === true, previous.scope.projectId, previous.scope.workspaceRoot]);
+                    reviewGroup ??= group;
+                    if (group !== reviewGroup)
+                        throw new KnowledgeError('invalid', '批量审阅需要相同项目、范围和主题');
+                    if (candidateReview === 'accepted' && !previous.evidenceIds.some(id => state.evidence.get(id)?.verification === 'read'))
+                        throw new KnowledgeError('invalid', '请先核对候选的实际来源');
+                    clean.state = candidateReview === 'accepted' ? 'usable' : 'rejected';
+                    clean.review = { decision: candidateReview, actor: 'human', at: now };
+                }
                 if (clean.state !== undefined && clean.state !== previous.state && !canTransition(previous.state, clean.state)) {
                     throw new KnowledgeError('invalid', '不允许的状态迁移：' + previous.state + ' → ' + clean.state, { failedId: update.id });
                 }
@@ -1678,6 +1749,7 @@ export class KnowledgeStore {
             lessons,
             stateCounts,
             byState: stateCounts,
+            memory: memoryDirectory([...state.lessons.values()], [...state.evidence.values()]),
         };
         const checkpoint = this.buildCheckpoint(state);
         if (checkpoint !== undefined)

package/lib/memory.d.ts

@@ -0,0 +1,36 @@
+import type { Evidence, Lesson } from './knowledge.js';
+/** A retrieval deadline is not a verification result; feedback never renews it. */
+export declare function reviewDeadline(lesson: Lesson): number | undefined;
+export declare function needsMemoryReview(lesson: Lesson, now?: number): boolean;
+/** Derived layers contain pointers; authoritative lessons and evidence remain untouched. */
+export declare function memoryDirectory(lessons: Lesson[], evidence: Evidence[], now?: number): {
+    summary: {
+        lessonId: string;
+        title: string;
+        scope: {
+            projectId?: string;
+            workspaceRoot?: string;
+            global: boolean;
+        };
+    }[];
+    entries: {
+        lessonId: string;
+        revision: number;
+        title: string;
+        topic: import("./knowledge.js").LessonKind;
+        scope: {
+            projectId?: string;
+            workspaceRoot?: string;
+            global: boolean;
+        };
+        state: import("./knowledge.js").LessonState;
+        reviewDue: boolean;
+        reviewAfter: string | null;
+        sources: {
+            evidenceId: string;
+            sessionId: string | undefined;
+            recordSeq: string | number | undefined;
+            verification: "read" | "claimed";
+        }[];
+    }[];
+};

package/lib/memory.js

@@ -0,0 +1,35 @@
+/** A retrieval deadline is not a verification result; feedback never renews it. */
+export function reviewDeadline(lesson) {
+    const explicit = lesson.reviewAfter ? Date.parse(lesson.reviewAfter) : NaN;
+    const reviewed = Date.parse(lesson.review.at ?? lesson.lastValidatedAt ?? lesson.createdAt);
+    const renewed = lesson.review.at ? Date.parse(lesson.review.at) : NaN;
+    if (Number.isFinite(explicit) && (!Number.isFinite(renewed) || renewed <= explicit))
+        return explicit;
+    if (lesson.kind !== 'fact')
+        return undefined;
+    return Number.isFinite(reviewed) ? reviewed + 30 * 86400000 : undefined;
+}
+export function needsMemoryReview(lesson, now = Date.now()) {
+    const deadline = reviewDeadline(lesson);
+    return lesson.state === 'usable' && deadline !== undefined && deadline <= now;
+}
+/** Derived layers contain pointers; authoritative lessons and evidence remain untouched. */
+export function memoryDirectory(lessons, evidence, now = Date.now()) {
+    const byId = new Map(evidence.map(item => [item.id, item]));
+    const accepted = new Set(lessons.filter(item => item.review.decision === 'accepted').map(item => item.id));
+    const entries = lessons.filter(item => item.state !== 'rejected').map(item => ({
+        lessonId: item.id, revision: item.revision, title: item.title, topic: item.kind, scope: item.scope,
+        state: item.state, reviewDue: needsMemoryReview(item, now),
+        reviewAfter: reviewDeadline(item) === undefined ? null : new Date(reviewDeadline(item)).toISOString(),
+        sources: item.evidenceIds.slice(0, 3).flatMap(id => {
+            const source = byId.get(id);
+            return source ? [{ evidenceId: id, sessionId: source.sessionId, recordSeq: source.recordSeq, verification: source.verification }] : [];
+        }),
+    }));
+    let chars = 0;
+    const summary = entries.filter(item => item.state === 'usable' && !item.reviewDue
+        && accepted.has(item.lessonId))
+        .slice(0, 12).filter(item => { chars += item.title.length; return chars <= 2400; })
+        .map(({ lessonId, title, scope }) => ({ lessonId, title, scope }));
+    return { summary, entries };
+}

package/lib/retrieval.d.ts

@@ -28,6 +28,7 @@ export interface RetrievalQuery {
     includeCandidates?: boolean;
     /** 是否保留 independentSupportCount===0 且非 usable 的条目；默认 true。dream_context 传 false（R1）。 */
     includeNoEvidence?: boolean;
+    now?: number;
 }
 /** 检索结果中的单条经验（when/exceptions 永不截断）。 */
 export interface RetrievedLesson {

package/lib/retrieval.js

@@ -1,4 +1,5 @@
 import { normalizeLessonText } from './knowledge.js';
+import { needsMemoryReview } from './memory.js';
 /** 默认条数。 */
 export const DEFAULT_RETRIEVAL_LIMIT = 5;
 /** 条数硬上限。 */
@@ -150,6 +151,7 @@ const SKIPPED_REASON_LABELS = {
     'no-evidence': '无独立证据',
     'version-mismatch': '版本条件不匹配',
     'platform-mismatch': '平台条件不匹配',
+    'review-due': '已到复核时间',
     limit: '超出条数上限',
     'budget-stop': '预算放不下',
     budget: '预算放不下（旧值）',
@@ -478,6 +480,10 @@ export function retrieveLessons(lessons, evidence, q) {
     for (const lesson of lessons) {
         if (!scopeMatches(lesson, q))
             continue;
+        if (needsMemoryReview(lesson, q.now ?? Date.now())) {
+            skipped.push({ lessonId: lesson.id, reason: 'review-due' });
+            continue;
+        }
         const excludedReason = EXCLUDED_STATE_REASONS[lesson.state];
         if (excludedReason !== undefined) {
             skipped.push({ lessonId: lesson.id, reason: excludedReason });

package/lib/web-actions.js

@@ -104,6 +104,36 @@ export function createDreamActionHandler(options = {}) {
             if (request.signal.aborted)
                 return fail(409, 'cancelled', '操作已取消');
             const operation = text(body, 'operation');
+            if (operation === 'automatic-chat' || operation === 'automatic-flush') {
+                const runtime = automaticRuntime(cfg);
+                if (!runtime)
+                    return fail(503, 'unavailable', '自动功能尚未就绪');
+                if (operation === 'automatic-flush')
+                    runtime.flush();
+                else {
+                    if (['use', 'contribute'].some(key => body[key] !== undefined && body[key] !== null && typeof body[key] !== 'boolean')
+                        || (body.use === undefined && body.contribute === undefined))
+                        throw new KnowledgeError('invalid', '聊天记忆开关需要布尔值或跟随全局');
+                    runtime.controlSession(text(body, 'sessionId'), { use: body.use, contribute: body.contribute });
+                }
+                return json(200, { ok: true, automatic: runtime.status() });
+            }
+            if (operation === 'review-batch') {
+                if (!['accept', 'reject'].includes(String(body.action)) || !Array.isArray(body.items) || body.items.length < 1 || body.items.length > 20)
+                    throw new KnowledgeError('invalid', '批量审阅每次选择 1 到 20 条候选');
+                const key = text(body, 'requestId');
+                if (!/^[a-zA-Z0-9_-]{8,100}$/.test(key))
+                    throw new KnowledgeError('invalid', '审阅请求标识无效');
+                const seen = new Set();
+                const updates = body.items.map(item => {
+                    if (!item || typeof item.lessonId !== 'string' || seen.has(item.lessonId) || !Number.isSafeInteger(item.expectedRevision) || item.expectedRevision < 1)
+                        throw new KnowledgeError('invalid', '候选及版本无效或重复');
+                    seen.add(item.lessonId);
+                    return { id: item.lessonId, expectedRevision: item.expectedRevision, patch: {} };
+                });
+                const lessons = store.updateLessonsBatch(updates, 'web-review-batch:' + key, body.action === 'accept' ? 'accepted' : 'rejected');
+                return json(200, maskDeep({ ok: true, lessons, message: '已完成所选候选的审阅' }));
+            }
             if (operation === 'automatic') {
                 if ((body.enabled !== undefined && typeof body.enabled !== 'boolean') || (body.retrievalEnabled !== undefined && typeof body.retrievalEnabled !== 'boolean') || (body.enabled === undefined && body.retrievalEnabled === undefined))
                     throw new KnowledgeError('invalid', '自动功能开关必须是布尔值');
@@ -169,6 +199,8 @@ export function createDreamActionHandler(options = {}) {
             throw new KnowledgeError('invalid', '不支持此操作');
         }
         catch (error) {
+            if (error instanceof Error && error.message.startsWith('automatic-'))
+                return fail(409, 'invalid', error.message === 'automatic-main-task-active' ? '主任务进行中，请等待完成后整理' : '聊天状态已变化或正在写入，请刷新后重试');
             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)));

package/lib/web.d.ts

@@ -1,6 +1,7 @@
 import { type ResolvedDreamConfig } from './config.js';
 import { type DreamEntry, type DreamStats } from './journal.js';
 import type { Evidence, Lesson } from './knowledge.js';
+import { memoryDirectory } from './memory.js';
 /** 面板与浏览器说话的同源路由。 */
 export declare const DREAM_ROUTE = "/_dsh/dsh-dream/journal";
 /** M1 经验面板的只读路由。 */
@@ -43,7 +44,11 @@ export interface KnowledgeWebPayload {
     lessons: Array<Lesson & {
         scopeLabel: string;
         evidenceSummary: string;
+        reviewDue?: boolean;
+        nextReviewAt?: string;
+        lastRetrievedAt?: string;
     }>;
+    memory?: ReturnType<typeof memoryDirectory>;
     /** 脱敏后的证据记录。 */
     evidence: Evidence[];
     /** 全量统计（不受条数影响）。 */

package/lib/web.js

@@ -22,6 +22,8 @@ import { dreamStats, readDreams, searchDreams } from './journal.js';
 import { KnowledgeStore } from './knowledge-store.js';
 import { isDreamReference, maskSecrets } from './mask.js';
 import { buildEvidenceSummary, lessonScopeLabel } from './retrieval.js';
+import { memoryDirectory, needsMemoryReview, reviewDeadline } from './memory.js';
+import { readAutomaticState } from './automatic-state.js';
 /** 面板与浏览器说话的同源路由。 */
 export const DREAM_ROUTE = '/_dsh/dsh-dream/journal';
 /** M1 经验面板的只读路由。 */
@@ -343,14 +345,23 @@ export function createKnowledgeWebHandler(options = {}) {
             const lessons = reader.listLessons();
             const evidence = reader.listEvidence();
             const stats = normalizeKnowledgeStats(reader.stats());
+            let retrieved = {};
+            try {
+                retrieved = readAutomaticState({ ...resolveConfig(options.config), journalDir: journalDirOf(options) }).retrieved ?? {};
+            }
+            catch { /* read-only panel still reports knowledge */ }
             const payload = {
                 lessons: lessons.map((lesson) => maskDeep({
                     ...lesson,
                     scopeLabel: lessonScopeLabel(lesson.scope),
                     evidenceSummary: buildEvidenceSummary(lesson, evidence),
+                    reviewDue: needsMemoryReview(lesson),
+                    ...(reviewDeadline(lesson) === undefined ? {} : { nextReviewAt: new Date(reviewDeadline(lesson)).toISOString() }),
+                    ...(retrieved[lesson.id] ? { lastRetrievedAt: new Date(retrieved[lesson.id].at).toISOString() } : {}),
                 })),
                 evidence: evidence.map((item) => maskDeep(item)),
                 stats,
+                memory: maskDeep(memoryDirectory(lessons, evidence)),
             };
             responseJson(res, 200, payload);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardustlc/dsh-dream",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "回顾会话、保存反思，并把经过核验和审阅的经验用于后续任务。",
   "type": "module",
   "main": "lib/index.js",