@stardustlc/dsh-dream 0.4.1 → 0.5.1

package/lib/retrieval.js

@@ -0,0 +1,515 @@
+import { normalizeLessonText } from './knowledge.js';
+/** 默认条数。 */
+export const DEFAULT_RETRIEVAL_LIMIT = 5;
+/** 条数硬上限。 */
+export const MAX_RETRIEVAL_LIMIT = 20;
+/** 默认字符预算。 */
+export const DEFAULT_RETRIEVAL_MAX_CHARS = 3000;
+/** 字符预算硬上限。 */
+export const MAX_RETRIEVAL_MAX_CHARS = 20000;
+const EXCLUDED_STATE_REASONS = {
+    rejected: 'state:rejected',
+    stale: 'state:stale',
+    disputed: 'state:disputed',
+};
+function trimmed(value) {
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function normalizeText(value) {
+    return normalizeLessonText(value).toLowerCase();
+}
+function oneLine(value) {
+    return value.replace(/\s+/g, ' ').trim();
+}
+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(/\/+$/, '');
+}
+function samePath(a, b) {
+    const ka = pathKey(a);
+    const kb = pathKey(b);
+    if (ka === '' || kb === '')
+        return false;
+    const windowsLike = /^[a-zA-Z]:/.test(ka) || /^[a-zA-Z]:/.test(kb) || a.includes('\\') || b.includes('\\');
+    return windowsLike ? ka.toLowerCase() === kb.toLowerCase() : ka === kb;
+}
+/** 查询侧范围文案（面板与 dream_context 共用）。 */
+export function queryScopeLabel(q) {
+    const project = trimmed(q.projectId);
+    const workspace = trimmed(q.workspaceRoot);
+    if (project !== undefined && workspace !== undefined)
+        return '项目 ' + project + '（工作区 ' + workspace + '）';
+    if (project !== undefined)
+        return '项目 ' + project;
+    if (workspace !== undefined)
+        return '工作区 ' + workspace;
+    return '全局';
+}
+/** 经验范围文案（面板与 dream_context 共用）。 */
+export function lessonScopeLabel(scope) {
+    const project = trimmed(scope.projectId);
+    const workspace = trimmed(scope.workspaceRoot);
+    if (project !== undefined && workspace !== undefined)
+        return '项目 ' + project + '（工作区 ' + workspace + '）';
+    if (project !== undefined)
+        return '项目 ' + project;
+    if (workspace !== undefined)
+        return '工作区 ' + workspace;
+    if (scope.global === true)
+        return '全局';
+    return '未限定范围';
+}
+/** 证据摘要（面板与 dream_context 共用）：独立支持数 + 已读/仅声明 + 脱敏摘要片段。 */
+export function buildEvidenceSummary(lesson, evidence) {
+    const byId = new Map();
+    for (const item of evidence) {
+        if (item !== null && typeof item === 'object' && typeof item.id === 'string')
+            byId.set(item.id, item);
+    }
+    const linked = [];
+    for (const id of lesson.evidenceIds) {
+        const found = byId.get(id);
+        if (found !== undefined)
+            linked.push(found);
+    }
+    if (linked.length === 0) {
+        if (lesson.evidenceIds.length > 0)
+            return '证据暂不可核对（' + lesson.evidenceIds.length + ' 条引用缺失）';
+        return '无证据（仅候选，不可作为已证实结论）';
+    }
+    const read = linked.filter((e) => e.verification === 'read').length;
+    const claimed = linked.filter((e) => e.verification === 'claimed').length;
+    const head = '独立证据 ' + lesson.independentSupportCount + ' 条（已读 ' + read + ' / 仅声明 ' + claimed + '）';
+    const snippets = linked
+        .slice(0, 2)
+        .map((e) => clip(oneLine(String(e.summary ?? '')), 80))
+        .filter((s) => s !== '');
+    if (snippets.length === 0)
+        return head;
+    return head + '：' + snippets.join('；') + (linked.length > 2 ? ' 等' : '');
+}
+/** 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;
+    const rawMax = q.maxChars;
+    const limit = typeof rawLimit === 'number' && Number.isInteger(rawLimit) && rawLimit > 0
+        ? Math.min(MAX_RETRIEVAL_LIMIT, rawLimit)
+        : DEFAULT_RETRIEVAL_LIMIT;
+    const maxChars = typeof rawMax === 'number' && Number.isInteger(rawMax) && rawMax > 0
+        ? Math.min(MAX_RETRIEVAL_MAX_CHARS, rawMax)
+        : DEFAULT_RETRIEVAL_MAX_CHARS;
+    return { limit, maxChars };
+}
+function parseVersion(text) {
+    const match = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(text.trim());
+    if (match === null)
+        return null;
+    return [Number(match[1]), Number(match[2] ?? 0), Number(match[3] ?? 0)];
+}
+function compareVersion(a, b) {
+    for (let i = 0; i < 3; i += 1) {
+        if (a[i] !== b[i])
+            return a[i] < b[i] ? -1 : 1;
+    }
+    return 0;
+}
+function parseStarBase(text) {
+    const match = /^v?(\d+)(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?$/.exec(text.trim());
+    if (match === null)
+        return null;
+    const parts = [match[1], match[2], match[3]];
+    const numbers = [];
+    let wildcard = 3;
+    for (let i = 0; i < 3; i += 1) {
+        const part = parts[i];
+        if (part === undefined || part === 'x' || part === 'X' || part === '*') {
+            if (wildcard === 3)
+                wildcard = i === 0 ? 1 : i;
+            numbers.push(0);
+            continue;
+        }
+        if (wildcard !== 3)
+            return null;
+        numbers.push(Number(part));
+    }
+    return { base: [numbers[0], numbers[1], numbers[2]], wildcard };
+}
+function satisfiesClause(version, clauseText) {
+    const clause = clauseText.trim();
+    if (clause === '')
+        return false;
+    const lowered = clause.toLowerCase();
+    if (lowered === '*' || lowered === 'x' || lowered === 'any' || lowered === 'latest')
+        return true;
+    const operatorMatch = /^(>=|<=|>|<|=|\^|~)/.exec(clause);
+    const operator = operatorMatch === null ? '=' : operatorMatch[1];
+    const rest = operatorMatch === null ? clause : clause.slice(operatorMatch[1].length).trim();
+    if (rest === '')
+        return false;
+    const star = parseStarBase(rest);
+    const base = star === null ? parseVersion(rest) : star.base;
+    if (base === null)
+        return false;
+    const wildcard = star === null ? 3 : star.wildcard;
+    const cmp = compareVersion(version, base);
+    switch (operator) {
+        case '>=': return cmp >= 0;
+        case '<=': return cmp <= 0;
+        case '>': return cmp > 0;
+        case '<': return cmp < 0;
+        case '^': {
+            if (cmp < 0)
+                return false;
+            const upper = base[0] > 0
+                ? [base[0] + 1, 0, 0]
+                : base[1] > 0 ? [0, base[1] + 1, 0] : [0, 0, base[2] + 1];
+            return compareVersion(version, upper) < 0;
+        }
+        case '~': {
+            if (cmp < 0)
+                return false;
+            return compareVersion(version, [base[0], base[1] + 1, 0]) < 0;
+        }
+        default: {
+            if (wildcard >= 3)
+                return cmp === 0;
+            if (wildcard === 2)
+                return version[0] === base[0] && version[1] === base[1];
+            return version[0] === base[0];
+        }
+    }
+}
+/** 简单 semver 条件匹配：支持 = / > / >= / < / <= / ^ / ~、逗号或空格 AND、|| OR、x/* 通配。 */
+export function versionSatisfies(versionText, rangeText) {
+    const version = parseVersion(versionText);
+    if (version === null)
+        return false;
+    if (rangeText.trim() === '')
+        return false;
+    return rangeText.split('||').some((part) => {
+        const clauses = part.split(/[\s,]+/).filter((c) => c !== '');
+        if (clauses.length === 0)
+            return false;
+        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: [], versionMismatch: false };
+    const packageVersion = trimmed(q.packageVersion);
+    const identifiedVersionChecks = [];
+    for (const entry of lesson.applicability) {
+        const pkg = trimmed(entry.package);
+        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 (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);
+        }
+    }
+    out.versionMismatch = identifiedVersionChecks.length > 0 && identifiedVersionChecks.every((ok) => !ok);
+    return out;
+}
+function queryTerms(query) {
+    const normalized = normalizeText(query);
+    const terms = new Set();
+    const rawTokens = normalized.split(/[^\p{L}\p{N}+#._-]+/u);
+    for (const token of rawTokens) {
+        if (token === '')
+            continue;
+        if (token.length >= 2)
+            terms.add(token);
+        const cjkRuns = token.match(/\p{Script=Han}+/gu);
+        if (cjkRuns === null)
+            continue;
+        for (const run of cjkRuns) {
+            if (run.length === 1)
+                terms.add(run);
+            for (let i = 0; i + 1 < run.length; i += 1)
+                terms.add(run.slice(i, i + 2));
+            for (let i = 0; i + 2 < run.length; i += 1)
+                terms.add(run.slice(i, i + 3));
+        }
+    }
+    return [...terms];
+}
+function keywordHits(lesson, terms) {
+    if (terms.length === 0)
+        return [];
+    const fields = [normalizeText(lesson.title), normalizeText(lesson.action), normalizeText(lesson.when)];
+    const hits = [];
+    for (const term of terms) {
+        if (fields.some((field) => field.includes(term)))
+            hits.push(term);
+    }
+    return hits;
+}
+function scopeMatches(lesson, q) {
+    if (lesson.scope.global === true)
+        return true;
+    const queryProject = trimmed(q.projectId);
+    const queryWorkspace = trimmed(q.workspaceRoot);
+    const lessonProject = trimmed(lesson.scope.projectId);
+    const lessonWorkspace = trimmed(lesson.scope.workspaceRoot);
+    if (queryProject !== undefined && lessonProject === queryProject)
+        return true;
+    if (queryWorkspace !== undefined && lessonWorkspace !== undefined && samePath(lessonWorkspace, queryWorkspace))
+        return true;
+    return false;
+}
+function buildWhyRelevant(entry, q) {
+    const lesson = entry.lesson;
+    const parts = [];
+    if (entry.keywordHits.length > 0) {
+        const shown = entry.keywordHits.slice(0, 3).map((term) => '「' + term + '」').join('、');
+        parts.push('命中关键词' + shown + (entry.keywordHits.length > 3 ? ' 等' : ''));
+    }
+    if (entry.applicability.packages.length > 0) {
+        parts.push('适用包「' + entry.applicability.packages.slice(0, 2).join('、') + '」');
+    }
+    if (entry.applicability.versions.length > 0) {
+        const current = trimmed(q.packageVersion);
+        parts.push('适用版本「' + entry.applicability.versions.slice(0, 2).join('、') + '」' + (current !== undefined ? '（当前 ' + current + '）' : ''));
+    }
+    if (entry.applicability.platforms.length > 0) {
+        parts.push('适用平台「' + entry.applicability.platforms.slice(0, 2).join('、') + '」');
+    }
+    const queryProject = trimmed(q.projectId);
+    const queryWorkspace = trimmed(q.workspaceRoot);
+    const lessonProject = trimmed(lesson.scope.projectId);
+    const lessonWorkspace = trimmed(lesson.scope.workspaceRoot);
+    if (lesson.scope.global === true && lessonProject === undefined && lessonWorkspace === undefined) {
+        parts.push('全局经验');
+    }
+    else if (queryProject !== undefined && lessonProject === queryProject) {
+        parts.push('项目匹配（' + lessonProject + '）');
+    }
+    else if (queryWorkspace !== undefined && lessonWorkspace !== undefined && samePath(lessonWorkspace, queryWorkspace)) {
+        parts.push('工作区匹配（' + lessonWorkspace + '）');
+    }
+    else if (lesson.scope.global === true) {
+        parts.push('全局经验');
+    }
+    if (parts.length === 0)
+        parts.push('范围匹配（' + lessonScopeLabel(lesson.scope) + '）');
+    return parts.join('；');
+}
+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,
+        exceptions: [...lesson.exceptions],
+        state: lesson.state,
+        scopeLabel: lessonScopeLabel(lesson.scope),
+        whyRelevant: buildWhyRelevant(entry, q),
+        evidenceSummary: buildEvidenceSummary(lesson, evidence),
+        truncated: false,
+    };
+    if (lesson.lastValidatedAt !== undefined)
+        item.lastValidatedAt = lesson.lastValidatedAt;
+    return item;
+}
+function validatedAtValue(lesson) {
+    if (lesson.lastValidatedAt === undefined)
+        return 0;
+    const parsed = Date.parse(lesson.lastValidatedAt);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+function stateRank(state) {
+    if (state === 'usable')
+        return 2;
+    if (state === 'candidate')
+        return 1;
+    return 0;
+}
+/**
+ * 任务相关经验检索。只返回 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) {
+        if (!scopeMatches(lesson, q))
+            continue;
+        const excludedReason = EXCLUDED_STATE_REASONS[lesson.state];
+        if (excludedReason !== undefined) {
+            skipped.push({ lessonId: lesson.id, reason: excludedReason });
+            continue;
+        }
+        // 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;
+        candidates.push({ lesson, keywordHits: hits, applicability });
+    }
+    candidates.sort((a, b) => {
+        const aKeyword = a.keywordHits.length > 0 ? 1 : 0;
+        const bKeyword = b.keywordHits.length > 0 ? 1 : 0;
+        if (aKeyword !== bKeyword)
+            return bKeyword - aKeyword;
+        if (a.keywordHits.length !== b.keywordHits.length)
+            return b.keywordHits.length - a.keywordHits.length;
+        const aApp = a.applicability.packages.length + a.applicability.versions.length + a.applicability.platforms.length;
+        const bApp = b.applicability.packages.length + b.applicability.versions.length + b.applicability.platforms.length;
+        if (aApp !== bApp)
+            return bApp - aApp;
+        const aRank = stateRank(a.lesson.state);
+        const bRank = stateRank(b.lesson.state);
+        if (aRank !== bRank)
+            return bRank - aRank;
+        const aTime = validatedAtValue(a.lesson);
+        const bTime = validatedAtValue(b.lesson);
+        if (aTime !== bTime)
+            return bTime - aTime;
+        if (a.lesson.id === b.lesson.id)
+            return 0;
+        return a.lesson.id < b.lesson.id ? -1 : 1;
+    });
+    const items = [];
+    let usedChars = 0;
+    for (let index = 0; index < candidates.length; index += 1) {
+        if (items.length >= limit) {
+            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 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;
+        }
+        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 };
+}