@stardustlc/dsh-dream 0.5.0 → 0.5.1

package/lib/knowledge.d.ts

@@ -85,6 +85,7 @@ export type KnowledgeEvent = {
     kind: 'lesson.create';
     lessonId: string;
     idempotencyKey: string;
+    requestHash?: string;
     payload: Lesson;
 } | {
     schemaVersion: 1;
@@ -94,6 +95,7 @@ export type KnowledgeEvent = {
     lessonId: string;
     revision: number;
     idempotencyKey: string;
+    requestHash?: string;
     payload: Partial<Lesson>;
 } | {
     schemaVersion: 1;
@@ -103,6 +105,7 @@ export type KnowledgeEvent = {
     lessonId: string;
     revision: number;
     idempotencyKey: string;
+    requestHash?: string;
     payload: {
         decision: ReviewDecision;
         actor?: string;
@@ -114,15 +117,35 @@ export type KnowledgeEvent = {
     at: string;
     kind: 'evidence.add';
     idempotencyKey: string;
+    requestHash?: string;
     payload: Evidence;
 };
 /** 知识层错误码：invalid=数据不合法；revision=乐观锁不符；duplicate=重复；io=读写/锁失败。 */
 export declare class KnowledgeError extends Error {
     code: 'invalid' | 'revision' | 'duplicate' | 'io';
-    constructor(code: 'invalid' | 'revision' | 'duplicate' | 'io', message: string);
+    /** 可选结构化上下文（脱敏后给工具/面板用；字段不承诺长期稳定）。 */
+    details?: Record<string, unknown>;
+    constructor(code: 'invalid' | 'revision' | 'duplicate' | 'io', message: string, details?: Record<string, unknown>);
 }
-/** 校验并归一化一条经验；失败抛 KnowledgeError('invalid')。未知字段会被丢弃。 */
-export declare function validateLesson(value: unknown): Lesson;
+/** 当前内存模型 / 写盘的 lesson schemaVersion。 */
+export declare const LESSON_SCHEMA_VERSION = 1;
+/** 迁移函数：把 from 版本的原始记录纯函数地转换成 to 版本的原始记录；必须幂等、不得写盘。 */
+export type LessonSchemaMigration = (from: number, raw: unknown, to: number) => unknown;
+/** 已知迁移链占位：v2 落地时在此登记；存储层默认只识别不自动迁移。 */
+export declare const LESSON_MIGRATIONS: Record<number, LessonSchemaMigration>;
+/** validateLesson 的可选前向兼容参数；旧调用签名（单参）保持不变。 */
+export interface ValidateLessonOptions {
+    /** 允许直接按当前形状读取的 schemaVersion 列表；默认 [1]。 */
+    accept?: number[];
+    /** 显式迁移函数：对非当前版本优先生效，返回值必须能通过 v1 校验。 */
+    migrate?: LessonSchemaMigration;
+}
+/**
+ * 校验并归一化一条经验；失败抛 KnowledgeError('invalid')。未知字段会被丢弃。
+ * 前向兼容：schemaVersion 非当前版本时，先尝试 options.migrate / LESSON_MIGRATIONS；
+ * 否则仅当版本在 options.accept 内才按当前形状读取，返回内存模型 v1。
+ */
+export declare function validateLesson(value: unknown, options?: ValidateLessonOptions): Lesson;
 /** 校验并归一化一条证据；失败抛 KnowledgeError('invalid')。未知字段会被丢弃。 */
 export declare function validateEvidence(value: unknown): Evidence;
 /**

package/lib/knowledge.js

@@ -10,10 +10,14 @@ import { createHash } from 'node:crypto';
 /** 知识层错误码：invalid=数据不合法；revision=乐观锁不符；duplicate=重复；io=读写/锁失败。 */
 export class KnowledgeError extends Error {
     code;
-    constructor(code, message) {
+    /** 可选结构化上下文（脱敏后给工具/面板用；字段不承诺长期稳定）。 */
+    details;
+    constructor(code, message, details) {
         super(message);
         this.name = 'KnowledgeError';
         this.code = code;
+        if (details !== undefined)
+            this.details = details;
     }
 }
 const LESSON_KINDS = ['preference', 'procedure', 'pitfall', 'fact'];
@@ -131,12 +135,39 @@ function readReview(value) {
         review.at = at;
     return review;
 }
-/** 校验并归一化一条经验；失败抛 KnowledgeError('invalid')。未知字段会被丢弃。 */
-export function validateLesson(value) {
+/** 当前内存模型 / 写盘的 lesson schemaVersion。 */
+export const LESSON_SCHEMA_VERSION = 1;
+/** 已知迁移链占位：v2 落地时在此登记；存储层默认只识别不自动迁移。 */
+export const LESSON_MIGRATIONS = {};
+/**
+ * 校验并归一化一条经验；失败抛 KnowledgeError('invalid')。未知字段会被丢弃。
+ * 前向兼容：schemaVersion 非当前版本时，先尝试 options.migrate / LESSON_MIGRATIONS；
+ * 否则仅当版本在 options.accept 内才按当前形状读取，返回内存模型 v1。
+ */
+export function validateLesson(value, options = {}) {
     if (!isRecord(value))
         fail('lesson', '必须是对象');
-    if (value.schemaVersion !== 1)
-        fail('schemaVersion', '只支持 1');
+    const version = value.schemaVersion;
+    if (version !== LESSON_SCHEMA_VERSION) {
+        const accept = options.accept === undefined ? [LESSON_SCHEMA_VERSION] : options.accept;
+        const migration = options.migrate !== undefined
+            ? options.migrate
+            : (typeof version === 'number' ? LESSON_MIGRATIONS[version] : undefined);
+        if (migration !== undefined) {
+            let migrated;
+            try {
+                migrated = migration(version, value, LESSON_SCHEMA_VERSION);
+            }
+            catch (error) {
+                fail('schemaVersion', '迁移失败：' + (error instanceof Error ? error.message : String(error)));
+            }
+            return validateLesson(migrated, { accept: [LESSON_SCHEMA_VERSION] });
+        }
+        if (typeof version !== 'number' || !accept.includes(version)) {
+            fail('schemaVersion', '不支持 ' + String(version) + '（只识别 ' + accept.join(', ') + '）');
+        }
+        return validateLesson({ ...value, schemaVersion: LESSON_SCHEMA_VERSION }, { accept: [LESSON_SCHEMA_VERSION] });
+    }
     const id = readString(value.id, 'id', { required: true, nonEmpty: true });
     const revision = value.revision;
     if (typeof revision !== 'number' || !Number.isInteger(revision) || revision < 1)

package/lib/retrieval.d.ts

@@ -1,9 +1,10 @@
 /**
- * 任务相关经验检索（FREEZE §3）。
+ * 任务相关经验检索（FREEZE v1 + v1.1 增补 R1/R3/R4）。
  *
- * 顺序：范围过滤 → 排除 rejected/stale/disputed → 确定性排序 → 字符预算。
- * 条件（when）与例外（exceptions）不可截断：整条放不下时跳过并记 skipped.budget，
- * 绝不返回半条经验。
+ * 顺序：范围过滤 → 排除 rejected/stale/disputed → 候选/无证据策略过滤 → 版本包名上下文 →
+ * 确定性排序 → 按排名整条装入的字符预算（遇第一条放不下即停，rankInversionCount===0）。
+ * essential（title/when/action/exceptions，含 scopeLabel）永不截断；metadata（whyRelevant/
+ * evidenceSummary）放不下时可截断并置 truncated:true。
  *
  * @module dsh-dream/retrieval
  */
@@ -17,12 +18,19 @@ export interface RetrievalQuery {
     limit?: number;
     /** 默认 3000，硬上限 20000。 */
     maxChars?: number;
-    /** 当前任务相关依赖的版本，用于匹配 applicability.versions。 */
+    /** 当前任务相关依赖的版本，用于匹配 applicability.versions（R3：必须先识别包名）。 */
     packageVersion?: string;
+    /** 显式包名上下文；与 query 文本一起用于识别 applicability[].package（R3）。 */
+    packageName?: string;
+    /** 是否返回 candidate；默认 true（面板/审计需要）。dream_context 默认传 false（R1）。 */
+    includeCandidates?: boolean;
+    /** 是否保留 independentSupportCount===0 且非 usable 的条目；默认 true。dream_context 传 false（R1）。 */
+    includeNoEvidence?: boolean;
 }
-/** 检索结果中的单条经验（已完整保留 when/exceptions）。 */
+/** 检索结果中的单条经验（when/exceptions 永不截断）。 */
 export interface RetrievedLesson {
     lessonId: string;
+    revision: number;
     title: string;
     when: string;
     action: string;
@@ -48,8 +56,23 @@ export declare function queryScopeLabel(q: Pick<RetrievalQuery, 'projectId' | 'w
 export declare function lessonScopeLabel(scope: Lesson['scope']): string;
 /** 证据摘要（面板与 dream_context 共用）：独立支持数 + 已读/仅声明 + 脱敏摘要片段。 */
 export declare function buildEvidenceSummary(lesson: Lesson, evidence: Evidence[]): string;
-/** 单条结果的字符成本（与 dream_context.budget.usedChars 同口径）。 */
+/** essential 成本：title/when/action/exceptions/scopeLabel，永不截断（R4）。 */
+export declare function essentialLessonChars(item: Pick<RetrievedLesson, 'title' | 'when' | 'action' | 'exceptions' | 'scopeLabel'>): number;
+/** metadata 成本：whyRelevant/evidenceSummary，预算紧时可截断（R4）。 */
+export declare function metadataLessonChars(item: Pick<RetrievedLesson, 'whyRelevant' | 'evidenceSummary'>): number;
+/** 单条结果的完整字符成本（与 dream_context.budget.usedChars 同口径）。 */
 export declare function retrievedLessonChars(item: RetrievedLesson): number;
+/**
+ * rank inversion 指标（R4）：被 budget-stop 跳过、且排在某个已返回条目之前的条目数。
+ * 按排名整条装入的预算策略必须让它恒为 0。
+ */
+export declare function rankInversionCount(rankedLessonIds: string[], result: {
+    items: Array<Pick<RetrievedLesson, 'lessonId'>>;
+    skipped: Array<{
+        lessonId: string;
+        reason: string;
+    }>;
+}): number;
 /** 解析 limit/maxChars，套用默认值与硬上限。 */
 export declare function resolveRetrievalBudget(q: Pick<RetrievalQuery, 'limit' | 'maxChars'>): {
     limit: number;
@@ -60,6 +83,11 @@ export declare function versionSatisfies(versionText: string, rangeText: string)
 /**
  * 任务相关经验检索。只返回 global 或与查询项目/工作区精确匹配的记录；
  * 未知项目（未给 projectId/workspaceRoot）时只返回 global，绝不跨项目扫描。
+ *
+ * R1：includeCandidates=false 时 candidate 记 skipped:candidate-hold；includeNoEvidence=false 时
+ * independentSupportCount===0 且非 usable 记 skipped:no-evidence（优先于 candidate-hold）。
+ * R3：applicability.versions 仅在包名被识别时参与；包名识别但版本不满足 → skipped:version-mismatch。
+ * R4：预算按排名整条装入，第一条 essential 放不下即停（budget-stop）；metadata 可截断。
  */
 export declare function retrieveLessons(lessons: Lesson[], evidence: Evidence[], q: RetrievalQuery): {
     items: RetrievedLesson[];

package/lib/retrieval.js

@@ -24,6 +24,16 @@ function oneLine(value) {
 function clip(value, max) {
     return value.length > max ? value.slice(0, max) + '…' : value;
 }
+/** 在预算内截断（含省略号占用）；conditions/exceptions 不走这里。 */
+function clipTo(text, max) {
+    if (max <= 0)
+        return '';
+    if (text.length <= max)
+        return text;
+    if (max === 1)
+        return '…';
+    return text.slice(0, max - 1) + '…';
+}
 function pathKey(value) {
     return value.trim().replace(/\\/g, '/').replace(/\/+$/, '');
 }
@@ -90,14 +100,48 @@ export function buildEvidenceSummary(lesson, evidence) {
         return head;
     return head + '：' + snippets.join('；') + (linked.length > 2 ? ' 等' : '');
 }
-/** 单条结果的字符成本（与 dream_context.budget.usedChars 同口径）。 */
-export function retrievedLessonChars(item) {
-    let total = item.title.length + item.when.length + item.action.length
-        + item.scopeLabel.length + item.whyRelevant.length + item.evidenceSummary.length;
+/** essential 成本：title/when/action/exceptions/scopeLabel，永不截断（R4）。 */
+export function essentialLessonChars(item) {
+    let total = item.title.length + item.when.length + item.action.length + item.scopeLabel.length;
     for (const exception of item.exceptions)
         total += exception.length;
     return total;
 }
+/** metadata 成本：whyRelevant/evidenceSummary，预算紧时可截断（R4）。 */
+export function metadataLessonChars(item) {
+    return item.whyRelevant.length + item.evidenceSummary.length;
+}
+/** 单条结果的完整字符成本（与 dream_context.budget.usedChars 同口径）。 */
+export function retrievedLessonChars(item) {
+    return essentialLessonChars(item) + metadataLessonChars(item);
+}
+/**
+ * rank inversion 指标（R4）：被 budget-stop 跳过、且排在某个已返回条目之前的条目数。
+ * 按排名整条装入的预算策略必须让它恒为 0。
+ */
+export function rankInversionCount(rankedLessonIds, result) {
+    const rank = new Map();
+    rankedLessonIds.forEach((id, index) => { if (!rank.has(id))
+        rank.set(id, index); });
+    const returnedRanks = [];
+    for (const item of result.items) {
+        const index = rank.get(item.lessonId);
+        if (index !== undefined)
+            returnedRanks.push(index);
+    }
+    if (returnedRanks.length === 0)
+        return 0;
+    const lastReturned = Math.max(...returnedRanks);
+    let inversions = 0;
+    for (const entry of result.skipped) {
+        if (entry.reason !== 'budget-stop' && entry.reason !== 'budget')
+            continue;
+        const index = rank.get(entry.lessonId);
+        if (index !== undefined && index < lastReturned)
+            inversions += 1;
+    }
+    return inversions;
+}
 /** 解析 limit/maxChars，套用默认值与硬上限。 */
 export function resolveRetrievalBudget(q) {
     const rawLimit = q.limit;
@@ -203,21 +247,38 @@ export function versionSatisfies(versionText, rangeText) {
         return clauses.every((clause) => satisfiesClause(version, clause));
     });
 }
+/** R3：只有显式 packageName 一致，或 query 文本出现该包名，才认为包名被识别。 */
+function packageIdentified(pkg, q, queryText) {
+    const normalizedPkg = normalizeText(pkg);
+    if (normalizedPkg === '')
+        return false;
+    const explicit = trimmed(q.packageName);
+    if (explicit !== undefined && normalizeText(explicit) === normalizedPkg)
+        return true;
+    return queryText.includes(normalizedPkg);
+}
 function matchApplicability(lesson, q, queryText) {
-    const out = { packages: [], versions: [], platforms: [] };
+    const out = { packages: [], versions: [], platforms: [], versionMismatch: false };
     const packageVersion = trimmed(q.packageVersion);
+    const identifiedVersionChecks = [];
     for (const entry of lesson.applicability) {
         const pkg = trimmed(entry.package);
-        if (pkg !== undefined && queryText.includes(normalizeText(pkg)) && !out.packages.includes(pkg))
+        const identified = pkg !== undefined && packageIdentified(pkg, q, queryText);
+        if (identified && pkg !== undefined && !out.packages.includes(pkg))
             out.packages.push(pkg);
         const versions = trimmed(entry.versions);
-        if (packageVersion !== undefined && versions !== undefined && versionSatisfies(packageVersion, versions) && !out.versions.includes(versions)) {
-            out.versions.push(versions);
+        if (identified && versions !== undefined && packageVersion !== undefined) {
+            const ok = versionSatisfies(packageVersion, versions);
+            identifiedVersionChecks.push(ok);
+            if (ok && !out.versions.includes(versions))
+                out.versions.push(versions);
         }
         const platform = trimmed(entry.platform);
-        if (platform !== undefined && queryText.includes(normalizeText(platform)) && !out.platforms.includes(platform))
+        if (platform !== undefined && queryText.includes(normalizeText(platform)) && !out.platforms.includes(platform)) {
             out.platforms.push(platform);
+        }
     }
+    out.versionMismatch = identifiedVersionChecks.length > 0 && identifiedVersionChecks.every((ok) => !ok);
     return out;
 }
 function queryTerms(query) {
@@ -308,6 +369,7 @@ function toRetrievedLesson(entry, evidence, q) {
     const lesson = entry.lesson;
     const item = {
         lessonId: lesson.id,
+        revision: lesson.revision,
         title: lesson.title,
         when: lesson.when,
         action: lesson.action,
@@ -338,11 +400,18 @@ function stateRank(state) {
 /**
  * 任务相关经验检索。只返回 global 或与查询项目/工作区精确匹配的记录；
  * 未知项目（未给 projectId/workspaceRoot）时只返回 global，绝不跨项目扫描。
+ *
+ * R1：includeCandidates=false 时 candidate 记 skipped:candidate-hold；includeNoEvidence=false 时
+ * independentSupportCount===0 且非 usable 记 skipped:no-evidence（优先于 candidate-hold）。
+ * R3：applicability.versions 仅在包名被识别时参与；包名识别但版本不满足 → skipped:version-mismatch。
+ * R4：预算按排名整条装入，第一条 essential 放不下即停（budget-stop）；metadata 可截断。
  */
 export function retrieveLessons(lessons, evidence, q) {
     const { limit, maxChars } = resolveRetrievalBudget(q);
     const terms = queryTerms(q.query ?? '');
     const queryText = normalizeText(q.query ?? '');
+    const includeCandidates = q.includeCandidates !== false;
+    const includeNoEvidence = q.includeNoEvidence !== false;
     const skipped = [];
     const candidates = [];
     for (const lesson of lessons) {
@@ -353,8 +422,21 @@ export function retrieveLessons(lessons, evidence, q) {
             skipped.push({ lessonId: lesson.id, reason: excludedReason });
             continue;
         }
-        const hits = keywordHits(lesson, terms);
+        // R3 优先于 R1 的候选扣留：包名已识别但版本不满足时，reason 必须是 version-mismatch。
         const applicability = matchApplicability(lesson, q, queryText);
+        if (applicability.versionMismatch) {
+            skipped.push({ lessonId: lesson.id, reason: 'version-mismatch' });
+            continue;
+        }
+        if (!includeNoEvidence && lesson.state !== 'usable' && lesson.independentSupportCount === 0) {
+            skipped.push({ lessonId: lesson.id, reason: 'no-evidence' });
+            continue;
+        }
+        if (!includeCandidates && lesson.state === 'candidate') {
+            skipped.push({ lessonId: lesson.id, reason: 'candidate-hold' });
+            continue;
+        }
+        const hits = keywordHits(lesson, terms);
         const applicabilityCount = applicability.packages.length + applicability.versions.length + applicability.platforms.length;
         if (hits.length === 0 && applicabilityCount === 0)
             continue;
@@ -385,19 +467,49 @@ export function retrieveLessons(lessons, evidence, q) {
     });
     const items = [];
     let usedChars = 0;
-    for (const candidate of candidates) {
+    for (let index = 0; index < candidates.length; index += 1) {
         if (items.length >= limit) {
-            skipped.push({ lessonId: candidate.lesson.id, reason: 'limit' });
-            continue;
+            for (let rest = index; rest < candidates.length; rest += 1) {
+                skipped.push({ lessonId: candidates[rest].lesson.id, reason: 'limit' });
+            }
+            break;
         }
+        const candidate = candidates[index];
         const item = toRetrievedLesson(candidate, evidence, q);
-        const cost = retrievedLessonChars(item);
-        if (usedChars + cost > maxChars) {
-            skipped.push({ lessonId: candidate.lesson.id, reason: 'budget' });
+        const remaining = maxChars - usedChars;
+        const essential = essentialLessonChars(item);
+        if (essential > remaining) {
+            for (let rest = index; rest < candidates.length; rest += 1) {
+                skipped.push({ lessonId: candidates[rest].lesson.id, reason: 'budget-stop' });
+            }
+            break;
+        }
+        const fullCost = retrievedLessonChars(item);
+        if (fullCost <= remaining) {
+            items.push(item);
+            usedChars += fullCost;
             continue;
         }
-        items.push(item);
-        usedChars += cost;
+        const trimmed = truncateMetadata(item, remaining - essential);
+        const trimmedCost = retrievedLessonChars(trimmed);
+        if (trimmedCost > remaining) {
+            for (let rest = index; rest < candidates.length; rest += 1) {
+                skipped.push({ lessonId: candidates[rest].lesson.id, reason: 'budget-stop' });
+            }
+            break;
+        }
+        items.push(trimmed);
+        usedChars += trimmedCost;
     }
     return { items, skipped };
 }
+/** metadata（whyRelevant/evidenceSummary）按预算截断，essential 保持不变。 */
+function truncateMetadata(item, metadataBudget) {
+    const budget = Math.max(0, metadataBudget);
+    const whyBudget = Math.min(item.whyRelevant.length, Math.ceil(budget / 2));
+    const whyRelevant = clipTo(item.whyRelevant, whyBudget);
+    const evidenceSummary = clipTo(item.evidenceSummary, Math.max(0, budget - whyRelevant.length));
+    if (whyRelevant === item.whyRelevant && evidenceSummary === item.evidenceSummary)
+        return item;
+    return { ...item, whyRelevant, evidenceSummary, truncated: true };
+}

package/lib/tools.js

@@ -456,7 +456,7 @@ export function buildDreamTools(config) {
                 },
                 description: '适用范围（可选）。',
             },
-            evidence: { type: 'array', required: true, items: evidenceItemsSpec(), description: '证据数组，必填；可为空数组（此时只能保存为 candidate）。' },
+            evidence: { type: 'array', items: evidenceItemsSpec(), description: '证据数组（可选，缺省为空数组；无证据时只能保存为 candidate）。' },
         }),
         output: {
             schema: baseSchema,
@@ -521,7 +521,17 @@ export function buildDreamTools(config) {
                 })),
             }));
             const store = knowledgeStoreOf(cfg);
-            const { lesson, created } = store.createLesson(lessonInput, idempotencyKey);
+            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 byId = new Map(store.listEvidence().map((item) => [item.id, item]));
             const evidence = lesson.evidenceIds
                 .map((id) => byId.get(id))
@@ -536,6 +546,14 @@ 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 (!created)
                 notes.push('已存在同指纹经验（' + lesson.id + '）：复用既有记录并合并新证据，未新增经验。');
             if (!isGlobal && projectId === undefined && workspaceRoot === undefined) {
@@ -559,14 +577,16 @@ export function buildDreamTools(config) {
     };
     const dreamContext = {
         name: 'dream_context',
-        description: '取梦：按当前任务返回少量真正适用的经验（只读，默认最多 5 条 / 3000 字符）。只返回 global 或与 projectId/workspaceRoot 精确匹配的经验；未知项目只返回 global，绝不跨项目扫描。rejected/stale/disputed 默认排除并在 skipped 说明原因；条件与例外完整返回，放不下整条跳过；没有相关经验时返回空数组。',
+        description: '取梦：按当前任务返回少量真正适用的经验（只读，默认最多 5 条 / 3000 字符）。只返回 global 或与 projectId/workspaceRoot 精确匹配的经验；未知项目只返回 global，绝不跨项目扫描。rejected/stale/disputed 默认排除；候选默认不注入（candidate-hold），无独立证据且非 usable 不注入（no-evidence），版本条件与包名不符不注入（version-mismatch），skipped 均给原因。未审阅候选不得当作已证实结论；只有明确审阅候选时才传 includeCandidates=true。when/exceptions 完整保留，元数据可按预算截断，预算放不下即停。',
         parameters: compileParameters({
             query: { type: 'string', required: true, description: '当前任务描述或检索关键词。' },
             projectId: { type: 'string', description: '当前项目 ID（可选；未知时只返回 global）。' },
             workspaceRoot: { type: 'string', description: '当前工作区根目录（可选）。' },
             limit: { type: 'integer', description: '条数上限 1-20（默认 5）。' },
             maxChars: { type: 'integer', description: '字符预算 1-20000（默认 3000）。' },
-            packageVersion: { type: 'string', description: '当前相关依赖版本（可选）。' },
+            packageVersion: { type: 'string', description: '当前相关依赖版本（可选；需配合包名被识别才参与版本判定）。' },
+            packageName: { type: 'string', description: '当前相关依赖包名（可选；与 query 文本一起识别 applicability.package）。' },
+            includeCandidates: { type: 'boolean', description: '是否把候选经验纳入任务建议（默认 false；仅明确审阅候选时传 true，无证据候选仍不注入）。' },
         }),
         output: {
             schema: baseSchema,
@@ -575,12 +595,26 @@ export function buildDreamTools(config) {
                 const items = Array.isArray(rec.items) ? rec.items : [];
                 const budget = asRecord(rec.budget);
                 if (items.length === 0) {
-                    return [{ type: 'text', text: '没有与当前任务相关的经验（范围：' + rec.scopeLabel + '）。' }];
+                    const skipped = Array.isArray(rec.skipped) ? rec.skipped : [];
+                    const countReason = (reason) => skipped.filter((entry) => asRecord(entry).reason === reason).length;
+                    const hints = [];
+                    const held = countReason('candidate-hold');
+                    const noEvidence = countReason('no-evidence');
+                    const mismatched = countReason('version-mismatch');
+                    if (held > 0)
+                        hints.push(held + ' 条候选待审阅（要审阅候选时显式传 includeCandidates=true）');
+                    if (noEvidence > 0)
+                        hints.push(noEvidence + ' 条无独立证据不注入');
+                    if (mismatched > 0)
+                        hints.push(mismatched + ' 条版本条件不匹配不注入');
+                    const suffix = hints.length > 0 ? '；' + hints.join('；') : '';
+                    return [{ type: 'text', text: '没有可注入的适用经验（范围：' + rec.scopeLabel + suffix + '）。' }];
                 }
                 const lines = ['适用经验 ' + items.length + ' 条（范围：' + rec.scopeLabel + '，字符 ' + budget.usedChars + '/' + budget.maxChars + '）：'];
                 for (const item of items) {
                     const lesson = asRecord(item);
-                    lines.push('- [' + lesson.state + '｜' + lesson.scopeLabel + '] ' + lesson.title);
+                    const truncation = lesson.truncated === true ? '｜元数据截断' : '';
+                    lines.push('- [' + lesson.state + '｜' + lesson.scopeLabel + '｜rev ' + lesson.revision + truncation + '] ' + lesson.title);
                     lines.push('  何时：' + lesson.when);
                     lines.push('  行动：' + lesson.action);
                     const exceptions = Array.isArray(lesson.exceptions) ? lesson.exceptions : [];
@@ -598,6 +632,7 @@ export function buildDreamTools(config) {
             const projectId = optionalString(args, 'projectId');
             const workspaceRoot = optionalString(args, 'workspaceRoot');
             const packageVersion = optionalString(args, 'packageVersion');
+            const packageName = optionalString(args, 'packageName');
             const { limit, maxChars } = resolveRetrievalBudget({
                 limit: typeof args.limit === 'number' ? args.limit : undefined,
                 maxChars: typeof args.maxChars === 'number' ? args.maxChars : undefined,
@@ -606,9 +641,13 @@ export function buildDreamTools(config) {
                 query,
                 limit,
                 maxChars,
+                // R1：默认不注入候选；claimed-only / 无证据且非 usable 的条目也不注入（R1 附带规则）。
+                includeCandidates: args.includeCandidates === true,
+                includeNoEvidence: false,
                 ...(projectId !== undefined ? { projectId } : {}),
                 ...(workspaceRoot !== undefined ? { workspaceRoot } : {}),
                 ...(packageVersion !== undefined ? { packageVersion } : {}),
+                ...(packageName !== undefined ? { packageName } : {}),
             };
             const scopeLabel = queryScopeLabel(retrievalQuery);
             const dir = knowledgeDirOf(cfg);
@@ -661,7 +700,10 @@ export function buildDreamTools(config) {
             if (before === undefined)
                 throw new KnowledgeError('invalid', '经验不存在：' + lessonId);
             if (before.revision !== expectedRevision) {
-                throw new KnowledgeError('revision', '经验 ' + lessonId + ' 期望 revision ' + expectedRevision + '，实际 ' + before.revision);
+                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');

package/lib/web.d.ts

@@ -24,13 +24,16 @@ export interface DreamWebPayload {
     /** 本次生效的条数上限。 */
     limit: number;
 }
-/** 知识路由的统计形状（与 FREEZE §2 的 stats() 对齐）。 */
+/** 知识路由的统计形状（与 FREEZE §2 的 stats() 对齐；v1.1 R8 透传 badLines）。 */
 export interface KnowledgeWebStats {
     lessons: number;
     evidence: number;
     events: number;
     byState: Record<string, number>;
+    /** 有界回放被截断时为 true（面板据此显示提示行）。 */
     truncated?: boolean;
+    /** 事件 / 证据流中被跳过的坏行数（面板据此显示提示行）。 */
+    badLines: number;
 }
 /** 知识路由的 JSON 形状：脱敏后的经验 / 证据 / 统计。 */
 export interface KnowledgeWebPayload {

package/lib/web.js

@@ -139,7 +139,7 @@ function maskDeep(value) {
     }
     return value;
 }
-/** 统计归一化：数字字段兜底为 0，byState 五个键齐全，truncated 只在为 true 时保留。 */
+/** 统计归一化：数字字段兜底为 0，byState 五个键齐全，truncated 只在为 true 时保留，badLines 始终透传。 */
 function normalizeKnowledgeStats(value) {
     const source = value !== null && typeof value === 'object' ? value : {};
     const rawByState = source.byState !== null && typeof source.byState === 'object'
@@ -159,6 +159,7 @@ function normalizeKnowledgeStats(value) {
         evidence: numberAt('evidence'),
         events: numberAt('events'),
         byState,
+        badLines: Math.floor(numberAt('badLines')),
     };
     if (source.truncated === true)
         stats.truncated = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stardustlc/dsh-dream",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "DSH 做梦插件：会话间隙回放近期对话、反思写入梦境日记，并把高频教训幂等桥接进 AGENTS.md；默认隐私脱敏，零运行时依赖。",
   "type": "module",
   "main": "lib/index.js",

package/skills/dream-protocol/SKILL.md

@@ -20,10 +20,10 @@ description: 做梦协议：任务开始取回适用经验，长任务收尾沉
 
 ## 一、任务前：取回上下文（dream_context）
 
-- 任务涉及过往代码、用户偏好或踩过的坑时，先调 `dream_context`：给 `query`，能给就给 `projectId` / `workspaceRoot` / `packageVersion`。
+- 任务涉及过往代码、用户偏好或踩过的坑时，先调 `dream_context`：给 `query`，能给就给 `projectId` / `workspaceRoot`，以及 `packageName` + `packageVersion`（`applicability.versions` 只在该包名被识别时参与判定）。审阅候选时显式传 `includeCandidates: true`。
 - **预算：默认 5 条 / 3000 字符**（工具硬上限 20 条 / 20000 字符）。取回少量真正适用的即可；没有相关经验就接受空结果，不要为了「显得有记忆」硬塞。
 - `dream_context` 是只读的：不写盘，只返回标题、适用条件、行动建议、证据摘要与「为什么与当前任务相关」。
-- 未知当前项目时只会返回全局经验；不会跨项目扫描。候选（candidate）默认不作为任务建议注入。
+- 未知当前项目时只会返回全局经验；不会跨项目扫描。候选（candidate）**可被检索到**（显式 `includeCandidates: true`，用于审阅候选），但**默认不注入任务建议**（`includeCandidates: false` 时记 `skipped: candidate-hold`；`independentSupportCount === 0` 且非 `usable` 的记 `no-evidence`），且排在可用经验之后——未经审阅不得当作已证实结论。
 
 ## 二、任务中：先把真实任务做完
 
@@ -38,7 +38,9 @@ description: 做梦协议：任务开始取回适用经验，长任务收尾沉
   - 能定位就填 `sessionId` / `recordSeq`；
   - `summary` 只写脱敏后的一句话，不搬原文；
   - `verification`：`read` = 你或插件读到了原记录；`claimed` = 仅模型声称。**claimed 只计入证据列表，不计入独立支持数。**
+- **只有真的读到来源（会话记录 / 本地验证产物 / 用户明确纠正）才能标 read，自我判断一律 claimed**（"我记得""应该是"都算 claimed）；标错 read 等于自我提权，禁止。
 - 没有证据的观察只能是 candidate，不能写成确定事实，也不能说成「已验证」。
+- 例外：证据为 `kind: "user-correction"` 且 `verification: "read"`（读到用户纠正原文）时，该经验初始状态直接是 `usable`，`review` 记 `actor: "user"`、`decision: "accepted"`——用户决定优先于模型推测；其余证据一律从 `candidate` 起，claimed 不计独立支持、也不能覆盖用户纠正。
 - 用户明确采纳/驳回、发现经验互相冲突、依赖升级后旧经验需要复核 → 用 `dream_review`（必须带 `expectedRevision`）。
 - 用户采纳必须来自真实用户指令；模型自己不能冒充 `actor: user`。
 - 同一证据重复提交是幂等的，不会增加独立支持数。**禁止靠反复调用 `dream_save` 或 `dream_learn` 刷次数**——次数不等于正确，也不等于重要。
@@ -81,10 +83,10 @@ Dreams and **lessons** are two separate pipelines: a **first-person reflection**
 
 ## 1. Before the task: retrieve context (dream_context)
 
-- When a task touches past code, user preferences or known pitfalls, call `dream_context` first with `query`, plus `projectId` / `workspaceRoot` / `packageVersion` when available.
+- When a task touches past code, user preferences or known pitfalls, call `dream_context` first with `query`, plus `projectId` / `workspaceRoot` and `packageName` + `packageVersion` when available (`applicability.versions` only counts when that package is identified). Pass `includeCandidates: true` explicitly when reviewing candidates.
 - **Budget: 5 items / 3000 characters by default** (hard caps 20 items / 20000 characters). Take only what is relevant; an empty result is acceptable — never stuff memories in to look useful.
 - `dream_context` is read-only: it writes nothing and returns title, applicability, action, evidence summary and why it is relevant.
-- With an unknown project it returns global lessons only; it never scans across projects. Candidates are not injected as task advice by default.
+- With an unknown project it returns global lessons only and never scans across projects. Candidates **can be retrieved** (`includeCandidates: true`, for candidate review) but are **held out of default task advice** (`includeCandidates: false` reports `skipped: candidate-hold`; evidence-free non-usable items report `no-evidence`), and they rank after usable lessons — never treat one as a verified conclusion before review.
 
 ## 2. During the task: do the real work first
 
@@ -99,7 +101,9 @@ Dreams and **lessons** are two separate pipelines: a **first-person reflection**
   - fill `sessionId` / `recordSeq` when the source can be located;
   - keep `summary` to one masked sentence — never copy the raw record;
   - `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.
 - 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.