dsh-plugin-manager-companion 0.1.0

package/dist/qualityGate.js

@@ -0,0 +1,247 @@
+/**
+ * 安装前质量门 — 对**已经装进 profile 的包**做静态体检（不写文件、不调 pnpm）。
+ *
+ * 归属：A 类·重写（旧 src/installFlow.ts#qualityIssues 只作检查面意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/installFlow.ts#qualityIssues（约 1422 行起）与
+ *   docs/private/audit/correctness.md 的 C-1/C-2 记录。旧实现的两个 Critical 缺陷在这里被正面修掉：
+ *   C-1 只扫 exports["."] 一个入口 → 现在扫全部导出子路径 + 相对 import 可达文件（有界 BFS）；
+ *   C-2 对 scoped 子路径假阳性（只要 @scope/pkg 目录存在就判"可解析"）→ 现在用
+ *   diagnostics.ts 的 specifierResolves：Node 真实解析（只用于判真）与文件/exports 探测两把尺子，
+ *   判定"不可解析"时必须两者都不成立。
+ * 官方复用：安装流程本身由官方 Remote 编排（inspect → installBundle(enabled:false) → 本门 →
+ *   removeBundle / setBundleEnabled），本模块只提供第 3 步的静态判定，不参与写路径。
+ *   包入口解析、import 扫描、行号定位与 diagnostics.ts 共用同一套实现，避免两处口径漂移。
+ * 解析根：与诊断同源——profile 层 → 共享兜底层 → **安装锚点**（官方包与 bundle 本体由安装侧
+ *   提供，只看 profile 会把 peer 与 bundle 行全判成缺包）。installAnchor 省略时退回 profile 解析，
+ *   调用方应当把 ctx.get('profileContext').installAnchor 递进来。
+ * 前提检查：旧前提是"装完只看一个入口就够"——实测不够（C-1）；旧实现还用自建 bash 探测
+ *   patch 行名，现在改为读原始 patch 文本定位行 + Node 侧解析，不再自建第二套解析器。
+ *
+ * 调用契约：config.qualityGate 的 enabled/mode 是**调用方**（安装流程包装器）的事——
+ * enabled=false 时调用方不该调用本函数，mode='warn' 时调用方只展示不过滤。
+ * 本函数只消费 allowlist（命中即跳过全部检查，用户显式承担风险）。
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { isBuiltin } from 'node:module';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { OFFICIAL_DEP_ALLOWED, installedPackageDir, isLoaderProvided, locatePatchRows, packageEntryFiles, readInstallAnchor, scanPackage, specifierResolves, } from "./diagnostics.js";
+/** 质量门单包扫描的文件预算（覆盖整条加载链，同时保证响应有界）。 */
+const GATE_FILE_BUDGET = 400;
+/**
+ * 体检一个已安装的包。
+ *
+ * 检查三件事：
+ *  1. 未声明的 import（loader/平台提供项与 Node 内置模块豁免）——挂载后必 ERR_MODULE_NOT_FOUND；
+ *  2. 声明了但没装（peer 或普通依赖落不下来）；
+ *  3. @deepseek-ai/* 被声明成普通 dependencies —— 模块身份分裂会劫持官方 loader 行（豁免见
+ *     diagnostics.ts 的 OFFICIAL_DEP_ALLOWED）。
+ * 另外检查包自己的 bundle patch 行名是否解析得到（该行解析失败会让整个 profile 起不来）。
+ *
+ * @param envDir - profile 环境目录（解析锚点，也是包所在 node_modules 的父目录）。
+ * @param packageName - 已安装的包名。
+ * @param config - 本插件配置；同时接受 CompanionConfig 与单独的 qualityGate 段。
+ * @param ctxOrAnchor - host Context（从 ctx.get('profileContext') 取安装锚点），
+ *   或直接给 dsh 应用包的 package.json 路径；都不给时只按 profile 与共享兜底层解析，
+ *   安装侧提供的包会被判成缺包。
+ * @returns 判定结果；问题为空即 ok。
+ */
+export async function inspectPackage(envDir, packageName, config, ctxOrAnchor) {
+    const installAnchor = typeof ctxOrAnchor === 'string'
+        ? ctxOrAnchor
+        : ctxOrAnchor === undefined ? undefined : readInstallAnchor(ctxOrAnchor);
+    const gate = normalizeQualityGateConfig(config);
+    const issues = [];
+    const notes = [];
+    if (gate.allowlist.includes(packageName)) {
+        return {
+            ok: true,
+            issues,
+            notes: ['包名在质量门豁免名单里：跳过全部检查（这是用户显式承担风险的选择）'],
+        };
+    }
+    if (!isSafePackageName(packageName)) {
+        return { ok: false, issues: ['包名不合法：' + JSON.stringify(packageName)], notes };
+    }
+    const pkgDir = installedPackageDir(envDir, packageName, installAnchor);
+    if (pkgDir === undefined) {
+        return {
+            ok: false,
+            issues: ['在 ' + envDir + ' 下的 node_modules 里找不到这个包：质量门要求包先落地再体检'],
+            notes,
+        };
+    }
+    const manifest = readManifest(join(pkgDir, 'package.json'));
+    if (manifest === undefined) {
+        return { ok: false, issues: ['读不到该包的 package.json（缺失或不是 JSON 对象）'], notes };
+    }
+    const declared = declaredDependencyNames(manifest);
+    const regular = Object.keys(asRecord(manifest['dependencies']) ?? {});
+    for (const dep of regular) {
+        if (!dep.startsWith('@deepseek-ai/'))
+            continue;
+        if (OFFICIAL_DEP_ALLOWED.has(dep)) {
+            notes.push(dep + ' 属于模块身份不敏感的官方包，普通依赖声明按豁免处理');
+            continue;
+        }
+        issues.push('把官方包 ' + dep + ' 声明成了普通 dependencies：pnpm 会在 profile 里装出第二份拷贝，'
+            + 'loader 解析官方行时用到它，唯一符号与类身份分裂（典型症状是 '
+            + 'Cannot read properties of undefined (reading \'prepare\')）。'
+            + '请改成 peerDependencies（peer 由安装兜底层满足），或删掉这条声明。');
+    }
+    const entries = packageEntryFiles(pkgDir, manifest);
+    if (entries.length === 0) {
+        issues.push('没有可解析的入口文件（exports / main / module / index.js 都没有命中）：'
+            + '任何挂载它的 loader 行都会失败。');
+    }
+    const scan = scanPackage(pkgDir, manifest, GATE_FILE_BUDGET);
+    if (scan.reason !== undefined && entries.length > 0)
+        notes.push('扫描未完成：' + scan.reason);
+    if (scan.truncated) {
+        notes.push('扫描在 ' + scan.filesScanned + ' 个文件处到达上限（单包预算 ' + GATE_FILE_BUDGET
+            + ' 个文件），更深处的 import 未覆盖：标为通过不代表已证全善。');
+    }
+    const at = (file, line) => relativeTo(envDir, file) + ':' + line;
+    for (const hit of scan.imports) {
+        const spec = hit.spec;
+        if (isBuiltinSpecifier(spec))
+            continue;
+        if (isLoaderProvided(spec))
+            continue;
+        if (spec === packageName || spec.startsWith(packageName + '/'))
+            continue;
+        const covered = [...declared].some(name => spec === name || spec.startsWith(name + '/'));
+        if (!covered) {
+            issues.push('未声明的 import：' + at(hit.file, hit.line) + ' 导入 ' + spec
+                + '，但本包的 dependencies / peerDependencies 都没有声明它，profile 里也不会装它——'
+                + '挂载后必然 ERR_MODULE_NOT_FOUND（未声明依赖 pnpm 根本不会安装）。');
+            continue;
+        }
+        if (!specifierResolves(pkgDir, spec, installAnchor) && !specifierResolves(envDir, spec, installAnchor)) {
+            issues.push('声明了但没装：' + spec + '（声明于本包 package.json），'
+                + '在 ' + at(hit.file, hit.line) + ' 被导入，但 profile 与共享兜底层里都解析不到它——'
+                + '挂载后必然 ERR_MODULE_NOT_FOUND。');
+        }
+    }
+    issues.push(...bundleRowIssues(envDir, pkgDir, packageName, installAnchor));
+    return { ok: issues.length === 0, issues, notes };
+}
+/**
+ * 包自带 bundle patch 的行名检查。
+ *
+ * 一行 name 解析不到，挂载时就是 ERR_MODULE_NOT_FOUND，而且会让**整个 profile** 起不来
+ * （bundle 的行是启动路径的一部分）。这里用 diagnostics 的行定位器读原始 patch 文本，
+ * 解析判定与诊断层完全同源。
+ *
+ * @param envDir - profile 环境目录（解析锚点）。
+ * @param pkgDir - 包目录。
+ * @param packageName - 包名。
+ * @param installAnchor - dsh 应用包的 package.json（解析根，见 inspectPackage）。
+ * @returns 面向用户的问题清单（可能为空）。
+ */
+function bundleRowIssues(envDir, pkgDir, packageName, installAnchor) {
+    const issues = [];
+    const manifest = readManifest(join(pkgDir, 'package.json'));
+    const bundle = asRecord(manifest?.['dsh'])?.['bundle'];
+    const declared = asRecord(bundle)?.['patch'];
+    if (typeof declared !== 'string' || declared.length === 0)
+        return issues;
+    const patchPath = resolve(pkgDir, declared);
+    const patchLabel = relativeTo(envDir, patchPath);
+    if (!existsSync(patchPath)) {
+        issues.push('声明了 dsh.bundle.patch=' + declared + '，但 ' + patchLabel
+            + ' 不存在：profile 启动时读不到这一层 patch。');
+        return issues;
+    }
+    for (const row of locatePatchRows(patchPath)) {
+        const name = row.name;
+        if (name === undefined || name.length === 0)
+            continue;
+        const at = patchLabel + ':' + row.line;
+        if (name.startsWith('cordis:'))
+            continue;
+        if (name === packageName || name.startsWith(packageName + '/')) {
+            if (!specifierResolves(envDir, name, installAnchor)) {
+                issues.push('bundle patch 行指向自身子路径 ' + name + '（' + at + '），但该子路径解析不到：'
+                    + '要么文件不存在，要么没写进 exports。挂载这一行会让 profile 起不来。');
+            }
+            continue;
+        }
+        if (name.startsWith('.') || isAbsolute(name)) {
+            if (!existsSync(resolve(dirname(patchPath), name))) {
+                issues.push('bundle patch 行 ' + at + ' 的相对模块名 ' + name + ' 解析不到文件'
+                    + '（相对路径按 patch 文件所在目录解析）。');
+            }
+            continue;
+        }
+        if (isLoaderProvided(name))
+            continue;
+        if (!specifierResolves(envDir, name, installAnchor)) {
+            issues.push('bundle patch 行 ' + at + ' 挂载 ' + name + '，但它在 profile、共享兜底层与安装锚点下都'
+                + '解析不到：挂载这一行会让整个 profile 起不来（这也是本地安装的 bundle 依赖漏装时的典型症状）。');
+        }
+    }
+    return issues;
+}
+/** 组装 CompanionConfig 与单独 qualityGate 段的差异。 */
+function normalizeQualityGateConfig(config) {
+    const candidate = config.qualityGate;
+    return candidate ?? {
+        enabled: true,
+        mode: 'block',
+        allowlist: config.allowlist ?? [],
+    };
+}
+/**
+ * 包名安全校验：质量门要把包名拼进路径，必须挡住路径穿越
+ * （与 paths.ts 的 isSafeEnvironmentName 同样的纵深防御思路）。
+ */
+export function isSafePackageName(name) {
+    if (name.length === 0 || name.length > 214)
+        return false;
+    if (name.startsWith('.') || name.startsWith('/') || name.startsWith('\\'))
+        return false;
+    if (name.includes('..') || name.includes('\\'))
+        return false;
+    return /^(@[a-z0-9._-]+\/)?[a-z0-9._-]+$/i.test(name);
+}
+/** Node 内置模块说明符：crypto 与 node:crypto 等价，fs/promises 这类子路径同样豁免。 */
+export function isBuiltinSpecifier(spec) {
+    if (spec.startsWith('node:'))
+        return true;
+    return isBuiltin(spec);
+}
+/** 一个包声明的全部依赖名（dependencies + peerDependencies + optionalDependencies）。 */
+function declaredDependencyNames(manifest) {
+    const names = new Set();
+    for (const section of ['dependencies', 'peerDependencies', 'optionalDependencies']) {
+        const record = asRecord(manifest[section]);
+        if (record === undefined)
+            continue;
+        for (const name of Object.keys(record))
+            names.add(name);
+    }
+    return names;
+}
+/** 读一个包 manifest；读不到或不是 JSON 对象时 undefined。 */
+function readManifest(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf8'));
+        if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+            return undefined;
+        return parsed;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 取对象字段（非对象返回 undefined）。 */
+function asRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    return value;
+}
+/** 相对路径（不在目录内时返回绝对路径）。 */
+function relativeTo(base, file) {
+    const rel = relative(base, file);
+    return rel.length === 0 || rel.startsWith('..') ? file : rel;
+}

package/dist/rank.d.ts

@@ -0,0 +1,88 @@
+/**
+ * rank.ts — 名称模糊打分：字符掩码预筛 + 有序子序列对齐（纯函数，无 fs / 无 ctx / 无网络）。
+ *
+ * 归属：B 类·参考重写（旧 src/rank.ts 只作意图参考，未复制代码；算法按官方 rankByName 的语义重写并做长名适配）。
+ * 旧实现参考：dsh-web-plugin-manager/src/rank.ts（理解意图用，未复制代码）——它解决的问题是：
+ *   市场的搜索框需要一个**可预测**的模糊匹配（官方设计记录明确否决了无序字符匹配与第三方
+ *   fuzzy 依赖），并且 host 单测与 client bundle 必须共用同一实现，两处行为一致。
+ * 官方复用：**已核查，结论是不能直接复用**。官方 @deepseek-ai/dsh-client-ui-primitives
+ *   0.1.6-alpha.2 确实导出了 rankByName（lib/types/index.d.ts 有声明），但：
+ *   1) 它的运行时入口 lib/index.js 在顶层 import `./Tag.module.css` 之类的 CSS Modules 与
+ *      react/react-dom，从 host 进程 import 直接失败（实测 `node -e "import('@deepseek-ai/dsh-client-ui-primitives')"`
+ *      → `Cannot find package 'clsx' imported from .../lib/index.js`）。本模块的目标编译位
+ *      （tsconfig.host.json 的 src/*.ts）与 node 单测都在 host 侧，因此"直接复用"不可行。
+ *   2) 即便在 client 侧能 import（它是平台模块），也没法两边共用：host 侧仍需要同一套打分
+ *      （plugin_search 的排序与页面必须一致）。两套实现必然漂移，所以统一走本模块。
+ *   3) 语义上它面向**短命令名**（首字符用全局 -index 惩罚晚起始），套到长仓库名上会累计成大负分：
+ *      旧仓库实测 trmnl → dsh-terminal-panel 得 -14，反而输给 1 分的描述兜底命中。故本模块对它
+ *      做了长名适配（见 fuzzyScoreLowered 的注释），这也是任务里"长名适配版"的含义。
+ * 前提检查：旧实现的两条打分规则仍然成立（边界加分、连续命中加分），适配的三条被保留并显式化：
+ *   首字符晚起始**有界**扣分、间隔按实际间距扣分、总分下限 1。
+ *   旧 perf 审计（docs/private/audit/perf.md §8）量化了预筛收益（13k 键击 24–33ms → 1.0–9.6ms），
+ *   并**实测否决**了 DP 数组缓冲复用（更慢且引入模块级可变状态），所以这里保持每次新分配的纯函数实现。
+ */
+/** 26 位 ASCII 字母掩码（a–z）。 */
+export type CharMask = number;
+/** 命中（含稳定排序键）。 */
+export interface FuzzyHit<T> {
+    readonly item: T;
+    /** 输入中的原始下标：同分时按它排序，使顺序不依赖 Array.sort 的稳定性。 */
+    readonly index: number;
+    /** 对齐分（越大越好，恒 ≥ 1）。 */
+    readonly score: number;
+    /** 前缀命中；排序时优先于对齐分。 */
+    readonly prefix: boolean;
+}
+/**
+ * 计算字符掩码：a–z 映射到 26 个 bit。
+ *
+ * 只覆盖 ASCII 字母，且大小写都置位（调用方通常传小写串，兼容大写是为了防误用）。
+ * 非 ASCII 字符（CJK / emoji）**不进掩码**，因此掩码只会"放过"而绝不会误杀——
+ * 这是它能当预筛用的前提：子序列的必要条件是字符集合的超集关系。
+ *
+ * @param value - 待测字符串。
+ * @returns 26 位掩码。
+ */
+export declare function charMask(value: string): CharMask;
+/**
+ * 模糊打分（大小写不敏感）。
+ *
+ * @param name - 候选名。
+ * @param query - 用户输入。
+ * @returns 对齐分（≥1）；query 不是 name 的有序子序列时返回 null（淘汰）。
+ */
+export declare function fuzzyScore(name: string, query: string): number | null;
+/**
+ * 预筛版打分（调用方已把小写串与掩码算好的快路径）。
+ *
+ * 语义：整条 needle 必须作为 haystack 的**有序子序列**出现（不分词），取最优对齐分。
+ * 打分规则（对官方的长名适配）：
+ * - 每个命中位给 `1 + 边界加分`；
+ * - 上一个 needle 字符恰好在前一位时额外 +4（连续命中强加分）；
+ * - 间隔命中按实际间距扣分（`-(间距-1)`）；
+ * - 首字符晚起始的扣分**有界**（`-min(i, 6)`）——官方用无界的 `-index`，在长仓库名上会
+ *   把"散落在后半段的合法命中"压成大负分，反而输给 1 分的兜底命中；
+ * - 总分下限 1：名称命中恒不低于兜底命中（调用方用"描述子串 = 1 分"兜底）。
+ *
+ * 时间 O(n·m)，空间 O(n)；不做缓冲复用（旧 perf 审计实测复用更慢，且会引入模块级可变状态）。
+ *
+ * @param haystack - 候选名（调用方保证已小写）。
+ * @param needle - 查询串（调用方保证已小写）。
+ * @param hayMask - 可选的 {@link charMask}(haystack)：与 needleMask 同时给出时启用 O(1) 预筛。
+ * @param needleMask - 可选的 {@link charMask}(needle)。掩码只做**拒绝**、不参与打分，
+ *   因此传与不传的命中集合与分数逐条相同（tests/rank.test.mjs 有等价性断言）。
+ * @returns 最优对齐分；不是子序列时返回 null。
+ */
+export declare function fuzzyScoreLowered(haystack: string, needle: string, hayMask?: CharMask, needleMask?: CharMask): number | null;
+/**
+ * 过滤 + 排序（前缀命中 → 对齐分 → 原始下标）。
+ *
+ * 排序键里带 `index`，所以同分条目的顺序由输入顺序唯一决定，不依赖引擎的排序稳定性——
+ * 这是"稳定全序"要求的直接落实。
+ *
+ * @param items - 候选条目（保持调用方给的顺序）。
+ * @param nameOf - 取名称的函数（例如 `item => item.name`）。
+ * @param query - 用户输入；**空白查询返回 null**（调用方走自己的默认路径，不要在这里猜测默认顺序）。
+ * @returns 命中列表；查询为空时 null。
+ */
+export declare function fuzzyFilter<T>(items: readonly T[], nameOf: (item: T) => string, query: string): FuzzyHit<T>[] | null;

package/dist/rank.js

@@ -0,0 +1,164 @@
+/**
+ * rank.ts — 名称模糊打分：字符掩码预筛 + 有序子序列对齐（纯函数，无 fs / 无 ctx / 无网络）。
+ *
+ * 归属：B 类·参考重写（旧 src/rank.ts 只作意图参考，未复制代码；算法按官方 rankByName 的语义重写并做长名适配）。
+ * 旧实现参考：dsh-web-plugin-manager/src/rank.ts（理解意图用，未复制代码）——它解决的问题是：
+ *   市场的搜索框需要一个**可预测**的模糊匹配（官方设计记录明确否决了无序字符匹配与第三方
+ *   fuzzy 依赖），并且 host 单测与 client bundle 必须共用同一实现，两处行为一致。
+ * 官方复用：**已核查，结论是不能直接复用**。官方 @deepseek-ai/dsh-client-ui-primitives
+ *   0.1.6-alpha.2 确实导出了 rankByName（lib/types/index.d.ts 有声明），但：
+ *   1) 它的运行时入口 lib/index.js 在顶层 import `./Tag.module.css` 之类的 CSS Modules 与
+ *      react/react-dom，从 host 进程 import 直接失败（实测 `node -e "import('@deepseek-ai/dsh-client-ui-primitives')"`
+ *      → `Cannot find package 'clsx' imported from .../lib/index.js`）。本模块的目标编译位
+ *      （tsconfig.host.json 的 src/*.ts）与 node 单测都在 host 侧，因此"直接复用"不可行。
+ *   2) 即便在 client 侧能 import（它是平台模块），也没法两边共用：host 侧仍需要同一套打分
+ *      （plugin_search 的排序与页面必须一致）。两套实现必然漂移，所以统一走本模块。
+ *   3) 语义上它面向**短命令名**（首字符用全局 -index 惩罚晚起始），套到长仓库名上会累计成大负分：
+ *      旧仓库实测 trmnl → dsh-terminal-panel 得 -14，反而输给 1 分的描述兜底命中。故本模块对它
+ *      做了长名适配（见 fuzzyScoreLowered 的注释），这也是任务里"长名适配版"的含义。
+ * 前提检查：旧实现的两条打分规则仍然成立（边界加分、连续命中加分），适配的三条被保留并显式化：
+ *   首字符晚起始**有界**扣分、间隔按实际间距扣分、总分下限 1。
+ *   旧 perf 审计（docs/private/audit/perf.md §8）量化了预筛收益（13k 键击 24–33ms → 1.0–9.6ms），
+ *   并**实测否决**了 DP 数组缓冲复用（更慢且引入模块级可变状态），所以这里保持每次新分配的纯函数实现。
+ */
+/**
+ * 计算字符掩码：a–z 映射到 26 个 bit。
+ *
+ * 只覆盖 ASCII 字母，且大小写都置位（调用方通常传小写串，兼容大写是为了防误用）。
+ * 非 ASCII 字符（CJK / emoji）**不进掩码**，因此掩码只会"放过"而绝不会误杀——
+ * 这是它能当预筛用的前提：子序列的必要条件是字符集合的超集关系。
+ *
+ * @param value - 待测字符串。
+ * @returns 26 位掩码。
+ */
+export function charMask(value) {
+    let mask = 0;
+    for (let i = 0; i < value.length; i += 1) {
+        const code = value.charCodeAt(i);
+        if (code >= 97 && code <= 122)
+            mask |= 1 << (code - 97);
+        else if (code >= 65 && code <= 90)
+            mask |= 1 << (code - 65);
+    }
+    return mask;
+}
+/** 边界加分：命中位是名字首位，或前一个字符是分隔符（- / _）。 */
+function boundaryBonus(name, index) {
+    if (index === 0)
+        return 8;
+    const previous = name.charAt(index - 1);
+    return previous === '-' || previous === '_' ? 8 : 0;
+}
+/**
+ * 模糊打分（大小写不敏感）。
+ *
+ * @param name - 候选名。
+ * @param query - 用户输入。
+ * @returns 对齐分（≥1）；query 不是 name 的有序子序列时返回 null（淘汰）。
+ */
+export function fuzzyScore(name, query) {
+    return fuzzyScoreLowered(name.toLowerCase(), query.toLowerCase());
+}
+/**
+ * 预筛版打分（调用方已把小写串与掩码算好的快路径）。
+ *
+ * 语义：整条 needle 必须作为 haystack 的**有序子序列**出现（不分词），取最优对齐分。
+ * 打分规则（对官方的长名适配）：
+ * - 每个命中位给 `1 + 边界加分`；
+ * - 上一个 needle 字符恰好在前一位时额外 +4（连续命中强加分）；
+ * - 间隔命中按实际间距扣分（`-(间距-1)`）；
+ * - 首字符晚起始的扣分**有界**（`-min(i, 6)`）——官方用无界的 `-index`，在长仓库名上会
+ *   把"散落在后半段的合法命中"压成大负分，反而输给 1 分的兜底命中；
+ * - 总分下限 1：名称命中恒不低于兜底命中（调用方用"描述子串 = 1 分"兜底）。
+ *
+ * 时间 O(n·m)，空间 O(n)；不做缓冲复用（旧 perf 审计实测复用更慢，且会引入模块级可变状态）。
+ *
+ * @param haystack - 候选名（调用方保证已小写）。
+ * @param needle - 查询串（调用方保证已小写）。
+ * @param hayMask - 可选的 {@link charMask}(haystack)：与 needleMask 同时给出时启用 O(1) 预筛。
+ * @param needleMask - 可选的 {@link charMask}(needle)。掩码只做**拒绝**、不参与打分，
+ *   因此传与不传的命中集合与分数逐条相同（tests/rank.test.mjs 有等价性断言）。
+ * @returns 最优对齐分；不是子序列时返回 null。
+ */
+export function fuzzyScoreLowered(haystack, needle, hayMask, needleMask) {
+    const m = needle.length;
+    if (m === 0)
+        return 0;
+    const n = haystack.length;
+    if (m > n)
+        return null;
+    if (hayMask !== undefined && needleMask !== undefined && (hayMask & needleMask) !== needleMask)
+        return null;
+    const none = Number.NEGATIVE_INFINITY;
+    /** 匹配到 needle 第 j 个字符、且**恰好落在**位置 i 的最优分。 */
+    let previous = new Float64Array(n).fill(none);
+    for (let i = 0; i < n; i += 1) {
+        if (haystack.charCodeAt(i) === needle.charCodeAt(0)) {
+            previous[i] = 1 + boundaryBonus(haystack, i) - Math.min(i, 6);
+        }
+    }
+    for (let j = 1; j < m; j += 1) {
+        const needleCode = needle.charCodeAt(j);
+        const current = new Float64Array(n).fill(none);
+        // bestGapped = max over i' < i of (previous[i'] + i')：间隔命中的来源。
+        let bestGapped = none;
+        for (let i = 0; i < n; i += 1) {
+            if (haystack.charCodeAt(i) === needleCode) {
+                let score = none;
+                const adjacent = i > 0 ? previous[i - 1] : none;
+                if (adjacent !== none)
+                    score = adjacent + 4;
+                if (bestGapped !== none) {
+                    const gapped = bestGapped - (i - 1);
+                    if (gapped > score)
+                        score = gapped;
+                }
+                if (score !== none)
+                    current[i] = score + 1 + boundaryBonus(haystack, i);
+            }
+            const prior = previous[i];
+            if (prior !== none) {
+                const shifted = prior + i;
+                if (shifted > bestGapped)
+                    bestGapped = shifted;
+            }
+        }
+        previous = current;
+    }
+    let best = none;
+    for (let i = 0; i < n; i += 1) {
+        const value = previous[i];
+        if (value > best)
+            best = value;
+    }
+    return best === none ? null : Math.max(best, 1);
+}
+/**
+ * 过滤 + 排序（前缀命中 → 对齐分 → 原始下标）。
+ *
+ * 排序键里带 `index`，所以同分条目的顺序由输入顺序唯一决定，不依赖引擎的排序稳定性——
+ * 这是"稳定全序"要求的直接落实。
+ *
+ * @param items - 候选条目（保持调用方给的顺序）。
+ * @param nameOf - 取名称的函数（例如 `item => item.name`）。
+ * @param query - 用户输入；**空白查询返回 null**（调用方走自己的默认路径，不要在这里猜测默认顺序）。
+ * @returns 命中列表；查询为空时 null。
+ */
+export function fuzzyFilter(items, nameOf, query) {
+    const trimmed = query.trim();
+    if (trimmed.length === 0)
+        return null;
+    const needle = trimmed.toLowerCase();
+    const needleMask = charMask(needle);
+    const hits = [];
+    for (let index = 0; index < items.length; index += 1) {
+        const item = items[index];
+        const lowered = nameOf(item).toLowerCase();
+        const score = fuzzyScoreLowered(lowered, needle, charMask(lowered), needleMask);
+        if (score === null)
+            continue;
+        hits.push({ item, index, score, prefix: lowered.startsWith(needle) });
+    }
+    hits.sort((left, right) => Number(right.prefix) - Number(left.prefix) || right.score - left.score || left.index - right.index);
+    return hits;
+}