@stardustlc/dsh-dream 0.5.1 → 0.7.0

package/lib/knowledge.js

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

@@ -22,6 +22,8 @@ export interface RetrievalQuery {
     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）。 */
@@ -73,6 +75,13 @@ export declare function rankInversionCount(rankedLessonIds: string[], result: {
         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;
@@ -80,6 +89,9 @@ 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，绝不跨项目扫描。

package/lib/retrieval.js

@@ -142,6 +142,37 @@ export function rankInversionCount(rankedLessonIds, result) {
     }
     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;
@@ -257,9 +288,34 @@ function packageIdentified(pkg, q, queryText) {
         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: [], versionMismatch: false };
+    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);
@@ -274,11 +330,16 @@ function matchApplicability(lesson, q, queryText) {
                 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) {
@@ -424,6 +485,10 @@ export function retrieveLessons(lessons, evidence, q) {
         }
         // 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;

package/lib/tools.d.ts

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