@stardustlc/dsh-dream 0.5.0 → 0.6.0

package/lib/knowledge.d.ts

@@ -4,6 +4,15 @@ export type LessonKind = 'preference' | 'procedure' | 'pitfall' | 'fact';
 export type LessonState = 'candidate' | 'usable' | 'disputed' | 'stale' | 'rejected';
 /** 审阅结论。 */
 export type ReviewDecision = 'unreviewed' | 'accepted' | 'rejected';
+/** 解析 / 冲突处理的可选痕迹（事件与经验都带得下；旧数据没有也合法）。 */
+export interface LessonReviewResolution {
+    /** prefer | drop | merge 等；不强制枚举，由 tools 层约定。 */
+    kind: string;
+    targetId?: string;
+    affectedIds?: string[];
+}
+/** 审阅备注最大长度；超出截断而不是报错。 */
+export declare const REVIEW_NOTE_MAX_LENGTH = 500;
 /** 一条可复用经验。 */
 export interface Lesson {
     schemaVersion: 1;
@@ -36,6 +45,8 @@ export interface Lesson {
         decision: ReviewDecision;
         actor?: string;
         at?: string;
+        note?: string;
+        resolution?: LessonReviewResolution;
     };
     createdAt: string;
     updatedAt: string;
@@ -58,6 +69,8 @@ export interface Evidence {
     /** read=插件读到原记录；claimed=仅模型声称。 */
     verification: 'read' | 'claimed';
     sourceHash?: string;
+    /** 插件生成的核验结果；不是模型给出的保证。 */
+    verificationReason?: string;
 }
 /** dream_learn / 迁移的输入。 */
 export interface LessonInput {
@@ -85,6 +98,7 @@ export type KnowledgeEvent = {
     kind: 'lesson.create';
     lessonId: string;
     idempotencyKey: string;
+    requestHash?: string;
     payload: Lesson;
 } | {
     schemaVersion: 1;
@@ -94,6 +108,7 @@ export type KnowledgeEvent = {
     lessonId: string;
     revision: number;
     idempotencyKey: string;
+    requestHash?: string;
     payload: Partial<Lesson>;
 } | {
     schemaVersion: 1;
@@ -103,10 +118,13 @@ export type KnowledgeEvent = {
     lessonId: string;
     revision: number;
     idempotencyKey: string;
+    requestHash?: string;
     payload: {
         decision: ReviewDecision;
         actor?: string;
         state: LessonState;
+        note?: string;
+        resolution?: LessonReviewResolution;
     };
 } | {
     schemaVersion: 1;
@@ -114,15 +132,49 @@ export type KnowledgeEvent = {
     at: string;
     kind: 'evidence.add';
     idempotencyKey: string;
+    requestHash?: string;
     payload: Evidence;
+} | {
+    schemaVersion: 1;
+    id: string;
+    at: string;
+    kind: 'lesson.batch';
+    idempotencyKey: string;
+    requestHash?: string;
+    payload: {
+        updates: Array<{
+            lessonId: string;
+            revision: number;
+            patch: Partial<Lesson>;
+        }>;
+    };
 };
 /** 知识层错误码：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>);
+}
+/** 当前内存模型 / 写盘的 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')。未知字段会被丢弃。 */
-export declare function validateLesson(value: unknown): Lesson;
+/**
+ * 校验并归一化一条经验；失败抛 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

@@ -7,13 +7,19 @@
  * @module dsh-dream/knowledge
  */
 import { createHash } from 'node:crypto';
+/** 审阅备注最大长度；超出截断而不是报错。 */
+export const REVIEW_NOTE_MAX_LENGTH = 500;
 /** 知识层错误码：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'];
@@ -114,6 +120,21 @@ function readApplicability(value) {
     }
     return out;
 }
+function readResolution(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (!isRecord(value))
+        fail('review.resolution', '必须是对象');
+    const kind = readString(value.kind, 'review.resolution.kind', { required: true, nonEmpty: true });
+    const targetId = readString(value.targetId, 'review.resolution.targetId', { nonEmpty: true });
+    const affectedIds = readStringArray(value.affectedIds, 'review.resolution.affectedIds');
+    const resolution = { kind };
+    if (targetId !== undefined)
+        resolution.targetId = targetId;
+    if (affectedIds !== undefined)
+        resolution.affectedIds = affectedIds;
+    return resolution;
+}
 function readReview(value) {
     if (value === undefined || value === null)
         return { decision: 'unreviewed' };
@@ -129,14 +150,50 @@ function readReview(value) {
         review.actor = actor;
     if (at !== undefined)
         review.at = at;
+    const noteRaw = readString(value.note, 'review.note');
+    if (noteRaw !== undefined) {
+        const trimmed = noteRaw.trim();
+        if (trimmed !== '')
+            review.note = trimmed.length > REVIEW_NOTE_MAX_LENGTH ? trimmed.slice(0, REVIEW_NOTE_MAX_LENGTH) : trimmed;
+    }
+    const resolution = readResolution(value.resolution);
+    if (resolution !== undefined)
+        review.resolution = resolution;
     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)
@@ -210,6 +267,7 @@ export function validateEvidence(value) {
     const sessionId = readString(value.sessionId, 'evidence.sessionId', { nonEmpty: true });
     const projectId = readString(value.projectId, 'evidence.projectId', { nonEmpty: true });
     const sourceHash = readString(value.sourceHash, 'evidence.sourceHash', { nonEmpty: true });
+    const verificationReason = readString(value.verificationReason, 'evidence.verificationReason', { nonEmpty: true });
     const recordSeqRaw = value.recordSeq;
     let recordSeq;
     if (recordSeqRaw !== undefined && recordSeqRaw !== null) {
@@ -236,6 +294,8 @@ export function validateEvidence(value) {
         evidence.projectId = projectId;
     if (sourceHash !== undefined)
         evidence.sourceHash = sourceHash;
+    if (verificationReason !== undefined)
+        evidence.verificationReason = verificationReason;
     return evidence;
 }
 /**

package/lib/mask.d.ts

@@ -10,4 +10,6 @@ export declare const SECRET_PATTERNS: Array<{
     label: string;
 }>;
 /** 对文本做脱敏；无命中时原样返回。 */
-export declare function maskSecrets(text: string): string;
+export declare function maskSecrets(text: string, publicReferences?: readonly string[]): string;
+/** 只认可插件生成的引用形状；不得把任意 *Id / *Hash 字段当作脱敏豁免。 */
+export declare function isDreamReference(value: string): boolean;

package/lib/mask.js

@@ -22,12 +22,18 @@ function looksHighEntropy(text) {
     return /[a-z]/.test(text) && (/[A-Z]/.test(text) || /[0-9]/.test(text));
 }
 /** 对文本做脱敏；无命中时原样返回。 */
-export function maskSecrets(text) {
+export function maskSecrets(text, publicReferences = []) {
     let out = text;
     for (const { re, label } of SECRET_PATTERNS) {
         out = out.replace(re, '[已脱敏·' + label + ']');
     }
     out = out.replace(CRED_ASSIGN, (_m, key, sep) => key + sep + '[已脱敏·凭据]');
-    out = out.replace(LONG_TOKEN, (m) => (looksHighEntropy(m) ? '[已脱敏·长令牌]' : m));
+    const references = new Set(publicReferences.filter(isDreamReference));
+    out = out.replace(LONG_TOKEN, (m) => (references.has(m) || !looksHighEntropy(m) ? m : '[已脱敏·长令牌]'));
     return out;
 }
+/** 只认可插件生成的引用形状；不得把任意 *Id / *Hash 字段当作脱敏豁免。 */
+export function isDreamReference(value) {
+    return /^(?:lsn|evd|evt|brg)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value)
+        || /^pvw_[0-9a-f]{24}$/i.test(value);
+}

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,21 @@ export interface RetrievalQuery {
     limit?: number;
     /** 默认 3000，硬上限 20000。 */
     maxChars?: number;
-    /** 当前任务相关依赖的版本，用于匹配 applicability.versions。 */
+    /** 当前任务相关依赖的版本，用于匹配 applicability.versions（R3：必须先识别包名）。 */
     packageVersion?: string;
+    /** 显式包名上下文；与 query 文本一起用于识别 applicability[].package（R3）。 */
+    packageName?: string;
+    /** 任务目标平台；宿主工具缺省使用当前系统，跨平台任务可显式指定。 */
+    platform?: 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 +58,30 @@ 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;
+/** skipped.reason 的中文标签（面板与工具共用；未知 reason 原样返回）。 */
+export declare function skippedReasonLabel(reason: string): string;
+/**
+ * 浏览态（无 query 上下文）下一条经验的确定性扣留原因；usable 返回 undefined。
+ * 与 retrieveLessons 的优先级一致：no-evidence 先于 candidate-hold；version-mismatch 需 query/包名，不适用。
+ */
+export declare function deterministicHoldReason(lesson: Pick<Lesson, 'state' | 'independentSupportCount'>): string | undefined;
 /** 解析 limit/maxChars，套用默认值与硬上限。 */
 export declare function resolveRetrievalBudget(q: Pick<RetrievalQuery, 'limit' | 'maxChars'>): {
     limit: number;
@@ -57,9 +89,17 @@ export declare function resolveRetrievalBudget(q: Pick<RetrievalQuery, 'limit' |
 };
 /** 简单 semver 条件匹配：支持 = / > / >= / < / <= / ^ / ~、逗号或空格 AND、|| OR、x/* 通配。 */
 export declare function versionSatisfies(versionText: string, rangeText: string): boolean;
+export declare function normalizePlatform(value: string): string;
+/** 显式任务平台优先，其次无歧义的任务文本，最后宿主平台。 */
+export declare function taskPlatform(query: string, explicit?: string, fallback?: string): string | undefined;
 /**
  * 任务相关经验检索。只返回 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,79 @@ 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;
+}
+const SKIPPED_REASON_LABELS = {
+    'state:rejected': '已驳回',
+    'state:stale': '已过期（待复核）',
+    'state:disputed': '冲突未解决',
+    'candidate-hold': '候选未审阅（默认不注入）',
+    'no-evidence': '无独立证据',
+    'version-mismatch': '版本条件不匹配',
+    'platform-mismatch': '平台条件不匹配',
+    limit: '超出条数上限',
+    'budget-stop': '预算放不下',
+    budget: '预算放不下（旧值）',
+};
+/** skipped.reason 的中文标签（面板与工具共用；未知 reason 原样返回）。 */
+export function skippedReasonLabel(reason) {
+    return SKIPPED_REASON_LABELS[reason] ?? reason;
+}
+/**
+ * 浏览态（无 query 上下文）下一条经验的确定性扣留原因；usable 返回 undefined。
+ * 与 retrieveLessons 的优先级一致：no-evidence 先于 candidate-hold；version-mismatch 需 query/包名，不适用。
+ */
+export function deterministicHoldReason(lesson) {
+    if (lesson.state === 'rejected')
+        return 'state:rejected';
+    if (lesson.state === 'stale')
+        return 'state:stale';
+    if (lesson.state === 'disputed')
+        return 'state:disputed';
+    if (lesson.state !== 'usable')
+        return lesson.independentSupportCount === 0 ? 'no-evidence' : 'candidate-hold';
+    return undefined;
+}
 /** 解析 limit/maxChars，套用默认值与硬上限。 */
 export function resolveRetrievalBudget(q) {
     const rawLimit = q.limit;
@@ -203,21 +278,68 @@ 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);
+}
+export function normalizePlatform(value) {
+    const key = value.trim().toLowerCase();
+    if (['win32', 'win64', 'windows', 'win', '微软windows'].includes(key))
+        return 'windows';
+    if (['darwin', 'macos', 'mac', 'osx', 'os x'].includes(key))
+        return 'macos';
+    if (['linux', 'gnu/linux'].includes(key))
+        return 'linux';
+    return key;
+}
+/** 显式任务平台优先，其次无歧义的任务文本，最后宿主平台。 */
+export function taskPlatform(query, explicit, fallback) {
+    if (trimmed(explicit))
+        return normalizePlatform(explicit);
+    const platforms = [];
+    if (/\b(?:windows|win32|win64)\b/i.test(query))
+        platforms.push('windows');
+    if (/\b(?:linux|ubuntu|debian|fedora)\b/i.test(query))
+        platforms.push('linux');
+    if (/\b(?:macos|darwin|osx)\b/i.test(query))
+        platforms.push('macos');
+    return platforms.length === 1 ? platforms[0] : fallback ? normalizePlatform(fallback) : undefined;
+}
 function matchApplicability(lesson, q, queryText) {
-    const out = { packages: [], versions: [], platforms: [] };
+    const out = { packages: [], versions: [], platforms: [], versionMismatch: false, platformMismatch: false };
     const packageVersion = trimmed(q.packageVersion);
+    const currentPlatform = taskPlatform(q.query, q.platform);
+    const platformChecks = [];
+    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))
-            out.platforms.push(platform);
+        if (currentPlatform !== undefined) {
+            const ok = platform === undefined || ['*', 'any', 'all'].includes(normalizePlatform(platform))
+                || platform.split(/[,|/]/).some(item => normalizePlatform(item) === currentPlatform);
+            platformChecks.push(ok);
+            if (ok && platform !== undefined && !out.platforms.includes(platform))
+                out.platforms.push(platform);
+        }
     }
+    out.versionMismatch = identifiedVersionChecks.length > 0 && identifiedVersionChecks.every((ok) => !ok);
+    out.platformMismatch = platformChecks.length > 0 && platformChecks.every((ok) => !ok);
     return out;
 }
 function queryTerms(query) {
@@ -308,6 +430,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 +461,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 +483,25 @@ 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.platformMismatch) {
+            skipped.push({ lessonId: lesson.id, reason: 'platform-mismatch' });
+            continue;
+        }
+        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 +532,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 };
+}