dsh-plugin-manager-companion 0.1.0

package/dist/match.js

@@ -0,0 +1,203 @@
+/**
+ * match.ts — plugin_search 的匹配纯函数：分词、加权打分、版本比较（无 fs / 无 ctx / 无网络）。
+ *
+ * 归属：B 类·参考重写（旧 src/match.ts 仅作意图参考，未复制代码；用例语义在 tests/marketplace.test.mjs 重写）。
+ * 旧实现参考：dsh-web-plugin-manager/src/match.ts（理解意图用，未复制代码）——它解决的问题是：
+ *   模型侧的自然语言查询（"帮我找记住上下文的插件"）需要一个不看 UI 的纯函数打分器，
+ *   并且要能回答"这个装好的包是不是该更新了"（版本比较）。
+ * 官方复用：无。官方没有市场/搜索概念；版本比较也不能用官方 plugin_manager 工具代替
+ *   （它做安装，不做"哪个更新"的判断）。
+ * 前提检查：旧实现的两条权重（名称 3 / 主题 2 / 描述 1）仍然成立，但旧审计 m-1
+ *   （docs/private/audit/correctness.md）指出 compareVersions 对**非法 semver 宽容解析**：
+ *   `1.0.0-01`（数字标识符前导零）、`1.0.0-`（空 pre）在语义上非法，旧实现却当成合法版本走
+ *   数值比较，得到 `compareVersions('1.0.0-','1.0.0') === 0` 这种"非法输入等于合法版本"的结论。
+ *   本实现改为：**解析失败即回退字符串比较**（结果确定、可预期，且绝不把非法输入当合法）。
+ *   主题命中沿用旧实现修过的规则：短 token（≤3）只做精确匹配——旧的"反向子串"
+ *   （token.includes(topic)）会让每个 2–3 字母主题命中一大堆无关条目。
+ */
+/**
+ * 把查询切成小写 token（字母数字 + CJK 连续段）。
+ *
+ * 标点/空白都当分隔符：查询是自然语言，不该要求用户记住连字符位置。
+ *
+ * @param query - 用户/模型输入。
+ * @returns 小写 token 列表；空查询返回空数组。
+ */
+export function tokenize(query) {
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9\u4e00-\u9fa5]+/)
+        .filter((token) => token.length > 0);
+}
+/**
+ * 一个条目对一组 token 的加权分。
+ *
+ * 权重：名称（display name 或 owner/repo，命中一次只计一次 3 分）/ 主题 2 分 / 描述 1 分，
+ * 逐 token 累加。名称与 repo 合并计分是有意的：owner 段（如 `termanli`）也是有效信号，
+ * 但同一个 token 同时命中两者不该被算成 6 分（那会让"名字里出现两次"压过真正的相关性）。
+ *
+ * @param item - 市场条目。
+ * @param tokens - {@link tokenize} 的结果。
+ * @returns 分数；0 表示不相关。
+ */
+export function scoreItem(item, tokens) {
+    const name = item.name.toLowerCase();
+    const repo = item.repo.toLowerCase();
+    const description = item.description.toLowerCase();
+    const topics = item.topics.map((topic) => topic.toLowerCase());
+    let score = 0;
+    for (const token of tokens) {
+        if (name.includes(token) || repo.includes(token))
+            score += 3;
+        if (token.length <= 3
+            ? topics.includes(token)
+            : topics.some((topic) => topic.includes(token)))
+            score += 2;
+        if (description.includes(token))
+            score += 1;
+    }
+    return score;
+}
+/** 星数排序键：未知按 0 计（"无星"与"未知"在这里是同一个展示位置）。 */
+function starsOf(item) {
+    return item.stars ?? 0;
+}
+/** 名称 → repo 的两级升序比较，保证任何排序都是确定的全序。 */
+function compareNames(left, right) {
+    if (left.name !== right.name)
+        return left.name < right.name ? -1 : 1;
+    if (left.repo !== right.repo)
+        return left.repo < right.repo ? -1 : 1;
+    return 0;
+}
+/**
+ * plugin_search 的排序：分数降序 → 星数降序 → 名称升序。
+ *
+ * 空查询返回**星数最高的前 limit 条**（旧行为保留：模型常问"有什么好用的插件"）。
+ * 星数相同时按名称升序而不是保持输入顺序：输入顺序来自上游索引，可能与调用方无关，
+ * 显式 tie-break 让同样的输入永远给出同样的答案。
+ *
+ * @param items - 市场条目。
+ * @param query - 查询串。
+ * @param limit - 返回条数上限（负数/0 视为 0）。
+ * @returns 排好序的前 limit 条（不修改入参）。
+ */
+export function findPluginMatches(items, query, limit) {
+    const size = Math.max(0, Math.trunc(limit));
+    if (size === 0)
+        return [];
+    const tokens = tokenize(query);
+    if (tokens.length === 0) {
+        return [...items]
+            .sort((left, right) => starsOf(right) - starsOf(left) || compareNames(left, right))
+            .slice(0, size);
+    }
+    const scored = [];
+    for (const item of items) {
+        const score = scoreItem(item, tokens);
+        if (score > 0)
+            scored.push({ item, score });
+    }
+    scored.sort((left, right) => right.score - left.score || starsOf(right.item) - starsOf(left.item) || compareNames(left.item, right.item));
+    return scored.slice(0, size).map((entry) => entry.item);
+}
+/**
+ * 严格解析（v1.2.3-rc.1 的宽松处只有"允许省略 minor/patch"和"允许 v 前缀"）。
+ *
+ * @param value - 版本串。
+ * @returns 解析结果；不符合 semver 时 null（调用方回退字符串比较）。
+ */
+function parseVersion(value) {
+    const text = value.trim().replace(/^v/i, '');
+    const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(text);
+    if (match === null)
+        return null;
+    const core = [match[1], match[2] ?? '0', match[3] ?? '0'];
+    for (const part of core) {
+        // 前导零在 semver 里非法（"0" 本身合法）。
+        if (part.length > 1 && part.startsWith('0'))
+            return null;
+    }
+    let pre = null;
+    if (match[4] !== undefined) {
+        pre = match[4].split('.');
+        for (const identifier of pre) {
+            if (identifier.length === 0)
+                return null;
+            if (!/^[0-9A-Za-z-]+$/.test(identifier))
+                return null;
+            if (/^\d+$/.test(identifier) && identifier.length > 1 && identifier.startsWith('0'))
+                return null;
+        }
+    }
+    return { core, pre };
+}
+/**
+ * 数字标识符比较（逐位精确，不经过 Number）。
+ *
+ * 输入已保证无前导零，所以"位数多的更大，位数相同按字典序"就是数值序；
+ * 这个做法同时避开了超长数字标识符（如 20 位 build 号）被 Number 截断精度的问题。
+ */
+function compareNumericIdentifier(left, right) {
+    if (left.length !== right.length)
+        return left.length < right.length ? -1 : 1;
+    if (left === right)
+        return 0;
+    return left < right ? -1 : 1;
+}
+/** 版本串的字典序回退（确定、可预期，绝不返回 NaN）。 */
+function compareStrings(left, right) {
+    return left === right ? 0 : left < right ? -1 : 1;
+}
+/**
+ * 轻量 semver 比较。
+ *
+ * 语义（semver §11）：`1.2.3-rc.1 < 1.2.3`；`rc.10 > rc.9`；`1.0` / `1` 视作 `1.0.0`；
+ * 预发布标识符逐个比较，**数字标识符的优先级低于字母数字**，共享前缀相同时字段少的更小
+ * （alpha < alpha.1）；build metadata 不参与优先级。
+ *
+ * 任一侧非法（`1.0.0-01`、`1.0.0-`、`abc`）时**回退原始串比较**：
+ * 非法输入不能被当成合法版本参与数值比较（旧审计 m-1）。
+ *
+ * @param left - 版本串。
+ * @param right - 版本串。
+ * @returns -1 / 0 / 1。
+ */
+export function compareVersions(left, right) {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    if (a === null || b === null)
+        return compareStrings(left, right);
+    for (let index = 0; index < 3; index += 1) {
+        const order = compareNumericIdentifier(a.core[index], b.core[index]);
+        if (order !== 0)
+            return order;
+    }
+    if (a.pre === null && b.pre === null)
+        return 0;
+    if (a.pre === null)
+        return 1;
+    if (b.pre === null)
+        return -1;
+    const length = Math.max(a.pre.length, b.pre.length);
+    for (let index = 0; index < length; index += 1) {
+        const x = a.pre[index];
+        const y = b.pre[index];
+        if (x === undefined)
+            return -1;
+        if (y === undefined)
+            return 1;
+        if (x === y)
+            continue;
+        const xNumeric = /^\d+$/.test(x);
+        const yNumeric = /^\d+$/.test(y);
+        if (xNumeric && yNumeric)
+            return compareNumericIdentifier(x, y);
+        if (xNumeric)
+            return -1;
+        if (yNumeric)
+            return 1;
+        return x < y ? -1 : 1;
+    }
+    return 0;
+}

package/dist/net.d.ts

@@ -0,0 +1,108 @@
+/**
+ * net.ts — 市场索引的出网层：超时、代理（HTTP_PROXY/HTTPS_PROXY/NO_PROXY）与可注入的抓取器。
+ *
+ * 归属：A 类·重写（旧 src/net.ts 仅作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/net.ts（理解意图用，未复制代码）——它解决了两个
+ *   真实问题：Node 全局 fetch 不认识 undici 的 dispatcher（要带代理就必须直接调 undici），
+ *   以及"只设超时会覆盖调用方传入的 signal"导致取消请求失效。
+ * 官方复用：无。官方 host 面不提供通用出网抓取（ctx.* 里没有这类能力），社区索引只能自己直连；
+ *   本模块只依赖 package.json 已声明的 undici。
+ * 前提检查：旧实现有三个隐含前提，重推后都改了：
+ *   1) 超时写死 15s —— 本插件把它做成**用户配置**（settings.marketplace.timeoutMs），故改为入参；
+ *   2) 代理 agent 缓存曾经无上限（旧代码后补 MAX_AGENTS，说明当初确实泄漏）——这里从一开始就有
+ *      上界，并提供显式关闭（测试与插件卸载用）；
+ *   3) NO_PROXY 的匹配规则（通配 / 后缀 / 端口 / IPv6 字面量）从未被单测覆盖——抽成纯函数
+ *      noProxyMatches()，由 tests/marketplace.test.mjs 直接断言。
+ *
+ * 本模块是**唯一**允许 import undici 的地方；其余模块只依赖这里导出的 `Fetcher` 契约，
+ * 因此整条市场管道可以在无网络、无代理的环境里用假 fetcher 完整驱动（tests 就是这么做的）。
+ */
+import { ProxyAgent } from 'undici';
+/** 默认请求超时；调用方通常传 settings.marketplace.timeoutMs。 */
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+/** 缓存的代理 agent 上界（代理环境变量变化很少，越界时关闭最旧的一个）。 */
+export declare const MAX_PROXY_AGENTS = 8;
+/**
+ * 响应侧的最小结构契约。
+ *
+ * 不直接用 undici 的 Response 类型当签名：测试里的假 fetcher 只需要实现这几个方法，
+ * 而结构式契约把"我们真正用到的东西"写清楚（也避免把 undici 类型扩散到别的模块）。
+ */
+export interface HttpResponseLike {
+    readonly ok: boolean;
+    readonly status: number;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+}
+/** 一次抓取的入参。 */
+export interface FetchOptions {
+    /** 单次请求超时（毫秒）。 */
+    readonly timeoutMs?: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** 调用方的取消信号；与超时信号**合并**，不互相覆盖。 */
+    readonly signal?: AbortSignal;
+}
+/**
+ * 抓取器签名：市场管道唯一的外部依赖。
+ *
+ * 默认实现是本模块的 {@link fetchWithProxy}；测试可注入假实现，
+ * 于是"五级索引兜底链 + 磁盘缓存回退"能在无网络条件下逐跳断言。
+ */
+export type Fetcher = (url: string, options: FetchOptions) => Promise<HttpResponseLike>;
+/**
+ * NO_PROXY 是否覆盖该主机（纯函数，便于单测）。
+ *
+ * 规则与 curl/undici 生态一致：
+ * - `*` 匹配一切；
+ * - 逗号分隔，逐项去空白，空项忽略；
+ * - 每一项可带端口（`host:port`），端口被忽略（我们只按主机名判断）；
+ * - IPv6 字面量写作 `[::1]:port`，取方括号内内容；
+ * - 支持前导点（`.example.com`）与裸域名的后缀匹配，以及完全相等匹配。
+ *
+ * 注意：不做通配符（`*.example.com` 里的 `*`）展开——NO_PROXY 的通行约定里
+ * 只有单独的 `*` 是通配；把它当通配前缀会让 `*.corp` 静默变成后缀匹配，
+ * 看起来"能用"，实际覆盖范围与用户预期不同。这里选择只认精确后缀，宁可少放过。
+ *
+ * @param hostname - 目标主机名（`new URL(url).hostname`，IPv6 自带方括号）。
+ * @param raw - NO_PROXY 原始值；undefined 表示未设置。
+ * @returns 命中即 true（该请求绕过代理）。
+ */
+export declare function noProxyMatches(hostname: string, raw: string | undefined): boolean;
+/**
+ * 该 URL 应使用的代理地址，null 表示直连。
+ *
+ * 大小写两种环境变量名都认（`HTTPS_PROXY` 优先于 `https_proxy`），与旧实现一致；
+ * ALL_PROXY 故意不支持——本插件的配置面只承诺这两个（见 settings.ts）。
+ *
+ * @param url - 目标 URL。
+ * @param env - 环境变量来源，默认 process.env（测试可注入）。
+ * @returns 代理 URL 原文；URL 非法、无代理或 NO_PROXY 命中时返回 null。
+ */
+export declare function proxyUrlFor(url: string, env?: Readonly<Record<string, string | undefined>>): string | null;
+/**
+ * 取（或建）一个代理 agent。
+ *
+ * 上界 {@link MAX_PROXY_AGENTS}：越界时关闭并丢弃最旧的一个。旧实现没有上界，
+ * 是后来补的——这里把它当成初始约束而不是补丁。
+ *
+ * @param proxyUrl - 代理地址（来自 {@link proxyUrlFor}）。
+ * @returns 该代理对应的 agent。
+ */
+export declare function proxyAgentFor(proxyUrl: string): ProxyAgent;
+/**
+ * 关闭并清空所有缓存的代理 agent（测试收尾 / 插件卸载）。
+ *
+ * 不关会留下占着 socket 的 agent：Cordis 热重载时旧实例的 agent 不会被 GC 回收。
+ */
+export declare function closeProxyAgents(): void;
+/**
+ * 带超时与代理的抓取。
+ *
+ * 超时通过 `AbortSignal.timeout` 实现，并与调用方 signal **合并**（`AbortSignal.any`）：
+ * 旧实现用赋值覆盖，导致调用方一旦传了 signal，超时保护就完全消失。
+ *
+ * @param url - 目标 URL。
+ * @param options - 超时 / 头部 / 取消信号。
+ * @returns 响应（结构式契约）。
+ */
+export declare function fetchWithProxy(url: string, options?: FetchOptions): Promise<HttpResponseLike>;

package/dist/net.js

@@ -0,0 +1,163 @@
+/**
+ * net.ts — 市场索引的出网层：超时、代理（HTTP_PROXY/HTTPS_PROXY/NO_PROXY）与可注入的抓取器。
+ *
+ * 归属：A 类·重写（旧 src/net.ts 仅作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/net.ts（理解意图用，未复制代码）——它解决了两个
+ *   真实问题：Node 全局 fetch 不认识 undici 的 dispatcher（要带代理就必须直接调 undici），
+ *   以及"只设超时会覆盖调用方传入的 signal"导致取消请求失效。
+ * 官方复用：无。官方 host 面不提供通用出网抓取（ctx.* 里没有这类能力），社区索引只能自己直连；
+ *   本模块只依赖 package.json 已声明的 undici。
+ * 前提检查：旧实现有三个隐含前提，重推后都改了：
+ *   1) 超时写死 15s —— 本插件把它做成**用户配置**（settings.marketplace.timeoutMs），故改为入参；
+ *   2) 代理 agent 缓存曾经无上限（旧代码后补 MAX_AGENTS，说明当初确实泄漏）——这里从一开始就有
+ *      上界，并提供显式关闭（测试与插件卸载用）；
+ *   3) NO_PROXY 的匹配规则（通配 / 后缀 / 端口 / IPv6 字面量）从未被单测覆盖——抽成纯函数
+ *      noProxyMatches()，由 tests/marketplace.test.mjs 直接断言。
+ *
+ * 本模块是**唯一**允许 import undici 的地方；其余模块只依赖这里导出的 `Fetcher` 契约，
+ * 因此整条市场管道可以在无网络、无代理的环境里用假 fetcher 完整驱动（tests 就是这么做的）。
+ */
+import { ProxyAgent, fetch as undiciFetch } from 'undici';
+/** 默认请求超时；调用方通常传 settings.marketplace.timeoutMs。 */
+export const DEFAULT_TIMEOUT_MS = 15_000;
+/** 缓存的代理 agent 上界（代理环境变量变化很少，越界时关闭最旧的一个）。 */
+export const MAX_PROXY_AGENTS = 8;
+/**
+ * NO_PROXY 是否覆盖该主机（纯函数，便于单测）。
+ *
+ * 规则与 curl/undici 生态一致：
+ * - `*` 匹配一切；
+ * - 逗号分隔，逐项去空白，空项忽略；
+ * - 每一项可带端口（`host:port`），端口被忽略（我们只按主机名判断）；
+ * - IPv6 字面量写作 `[::1]:port`，取方括号内内容；
+ * - 支持前导点（`.example.com`）与裸域名的后缀匹配，以及完全相等匹配。
+ *
+ * 注意：不做通配符（`*.example.com` 里的 `*`）展开——NO_PROXY 的通行约定里
+ * 只有单独的 `*` 是通配；把它当通配前缀会让 `*.corp` 静默变成后缀匹配，
+ * 看起来"能用"，实际覆盖范围与用户预期不同。这里选择只认精确后缀，宁可少放过。
+ *
+ * @param hostname - 目标主机名（`new URL(url).hostname`，IPv6 自带方括号）。
+ * @param raw - NO_PROXY 原始值；undefined 表示未设置。
+ * @returns 命中即 true（该请求绕过代理）。
+ */
+export function noProxyMatches(hostname, raw) {
+    if (raw === undefined || raw.length === 0)
+        return false;
+    // 两侧都剥掉 IPv6 的方括号：`new URL('http://[::1]/').hostname` 带括号，而 NO_PROXY 里
+    // 通常不写；只剥一侧会让 IPv6 的 NO_PROXY 配置静默失效。
+    const host = stripBrackets(hostname.trim().toLowerCase());
+    if (host.length === 0)
+        return false;
+    for (const entry of raw.split(',')) {
+        const token = entry.trim().toLowerCase();
+        if (token.length === 0)
+            continue;
+        if (token === '*')
+            return true;
+        const bare = stripBrackets(token.startsWith('[')
+            ? token.slice(1, token.indexOf(']') === -1 ? undefined : token.indexOf(']'))
+            : token.split(':')[0]);
+        const suffix = bare.startsWith('.') ? bare.slice(1) : bare;
+        if (suffix.length === 0)
+            continue;
+        if (host === suffix || host.endsWith('.' + suffix))
+            return true;
+    }
+    return false;
+}
+/** 剥掉 IPv6 字面量的方括号（`[::1]` → `::1`；非方括号输入原样返回）。 */
+function stripBrackets(value) {
+    return value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value;
+}
+/**
+ * 该 URL 应使用的代理地址，null 表示直连。
+ *
+ * 大小写两种环境变量名都认（`HTTPS_PROXY` 优先于 `https_proxy`），与旧实现一致；
+ * ALL_PROXY 故意不支持——本插件的配置面只承诺这两个（见 settings.ts）。
+ *
+ * @param url - 目标 URL。
+ * @param env - 环境变量来源，默认 process.env（测试可注入）。
+ * @returns 代理 URL 原文；URL 非法、无代理或 NO_PROXY 命中时返回 null。
+ */
+export function proxyUrlFor(url, env = process.env) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const secure = parsed.protocol === 'https:';
+    const raw = secure
+        ? env['HTTPS_PROXY'] ?? env['https_proxy']
+        : env['HTTP_PROXY'] ?? env['http_proxy'];
+    if (raw === undefined || raw.trim().length === 0)
+        return null;
+    if (noProxyMatches(parsed.hostname, env['NO_PROXY'] ?? env['no_proxy']))
+        return null;
+    return raw;
+}
+/** 缓存的代理 agent：key 是代理 URL。 */
+const agents = new Map();
+/**
+ * 取（或建）一个代理 agent。
+ *
+ * 上界 {@link MAX_PROXY_AGENTS}：越界时关闭并丢弃最旧的一个。旧实现没有上界，
+ * 是后来补的——这里把它当成初始约束而不是补丁。
+ *
+ * @param proxyUrl - 代理地址（来自 {@link proxyUrlFor}）。
+ * @returns 该代理对应的 agent。
+ */
+export function proxyAgentFor(proxyUrl) {
+    let agent = agents.get(proxyUrl);
+    if (agent === undefined) {
+        agent = new ProxyAgent(proxyUrl);
+        agents.set(proxyUrl, agent);
+    }
+    while (agents.size > MAX_PROXY_AGENTS) {
+        const oldest = agents.keys().next().value;
+        if (oldest === undefined)
+            break;
+        if (oldest === proxyUrl)
+            break; // 极端情况下别把刚建的关掉
+        agents.get(oldest)?.close();
+        agents.delete(oldest);
+    }
+    return agent;
+}
+/**
+ * 关闭并清空所有缓存的代理 agent（测试收尾 / 插件卸载）。
+ *
+ * 不关会留下占着 socket 的 agent：Cordis 热重载时旧实例的 agent 不会被 GC 回收。
+ */
+export function closeProxyAgents() {
+    for (const agent of agents.values())
+        agent.close();
+    agents.clear();
+}
+/**
+ * 带超时与代理的抓取。
+ *
+ * 超时通过 `AbortSignal.timeout` 实现，并与调用方 signal **合并**（`AbortSignal.any`）：
+ * 旧实现用赋值覆盖，导致调用方一旦传了 signal，超时保护就完全消失。
+ *
+ * @param url - 目标 URL。
+ * @param options - 超时 / 头部 / 取消信号。
+ * @returns 响应（结构式契约）。
+ */
+export async function fetchWithProxy(url, options = {}) {
+    const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const timeoutSignal = AbortSignal.timeout(timeout);
+    const signal = options.signal === undefined
+        ? timeoutSignal
+        : AbortSignal.any([options.signal, timeoutSignal]);
+    const proxy = proxyUrlFor(url);
+    const response = await undiciFetch(url, {
+        method: 'GET',
+        headers: options.headers === undefined ? undefined : { ...options.headers },
+        signal,
+        redirect: 'follow',
+        ...(proxy === null ? {} : { dispatcher: proxyAgentFor(proxy) }),
+    });
+    return response;
+}

package/dist/official.d.ts

@@ -0,0 +1,145 @@
+/**
+ * 官方适配层：本插件与 DSH 官方能力之间的**唯一**接口。
+ *
+ * 归属：A 类·重写（新代码；旧仓库没有这一层，它直接自建了 REST + patch 写入）。
+ * 官方复用：pluginManager 服务（当前环境写操作）、host-plugin-inventory
+ *   （运行时事实）、app-boot 的 profile 读取与 operations 的 pnpm 通道。
+ * 前提检查：旧仓库假设"官方只有只读清单，所以必须自建写路径"。0.1.6 之后
+ *   该前提消失——官方提供了完整的当前环境写面。本层的职责就是让其余模块
+ *   **不必知道**官方长什么样，同时把"官方不可用"如实降级而不是崩溃。
+ *
+ * 三条硬约束（写在类型与运行时里，不靠约定）：
+ *   1. 当前环境的写操作只走官方 —— 本模块不实现任何文件写入。
+ *   2. 服务名绝不用 'pluginManager' —— 官方已占用，同名注册会让整个
+ *      profile 起不来（旧仓库实测踩过）。
+ *   3. 任何官方能力缺失都降级为"能力不可用 + 原因"，绝不静默假装成功。
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { BundleInfo, ChangeResult, PluginEntryId, PluginInfo, PluginInventorySnapshot, PluginSpecInspection } from './types.ts';
+/**
+ * 官方能力的可用性快照。
+ *
+ * 设计意图：把"官方在不在、给不给这个能力"变成**可展示的事实**，而不是
+ * 让调用方在一堆 try/catch 里猜。诊断页会把 unavailable 的原因直接呈现给
+ * 用户（"这个环境没有装配官方插件管理器，以下检查已跳过"），而不是把
+ * 缺失伪装成健康。
+ */
+export interface OfficialCapabilities {
+    /** 当前环境是否由 dsh 以 profile 方式启动（决定 profileContext 是否存在）。 */
+    readonly profileBacked: boolean;
+    /** 官方 pluginManager 服务是否可用（当前环境的管理能力）。 */
+    readonly manager: boolean;
+    /** 官方 pluginInventory 是否可用（运行时事实）。 */
+    readonly inventory: boolean;
+    /** 当前环境名；未知时为 null。 */
+    readonly environmentName: string | null;
+    /** 缺失能力的说明，直接面向用户展示。 */
+    readonly missing: readonly string[];
+}
+/**
+ * 官方能力的探针。
+ *
+ * 为什么用 `ctx.get(name)` 而不是声明式 `inject`：
+ * 官方 pluginManager 行在 base bundle 里带
+ * `disabled: !!js "!ctx.get('profileContext')"`，即**没有 profile 时它不装配**。
+ * 若我们声明式 inject 它，本插件会永远停在 PENDING 而不做任何事——用户看到
+ * 一个"装了但没反应"的插件，且没有任何可读的错误。探针 + 降级让插件在
+ * 任何宿主上都能加载并如实说明自己不能做什么。
+ *
+ * @param ctx - 本插件的 host 上下文。
+ * @returns 当前可用能力；缺失原因在 `missing` 里逐条列出。
+ */
+export declare function probeOfficialCapabilities(ctx: Context): OfficialCapabilities;
+/**
+ * 官方 pluginManager 服务的**结构式**视图。
+ *
+ * 类型面保留官方管理的完整可读面；**运行时校验**只覆盖我们真正调用的方法
+ * （见 REQUIRED_MANAGER_METHODS）。两者刻意分开：
+ *   · listPlugins / listBundles 在本仓库 0 处调用（2026-09-19 核过），所以不进必需清单——
+ *     官方改它们时不该让我们报"能力不可用"（那是误报）；
+ *   · 但它们留在类型面里，谁以后要用就有现成的类型，也不必现在顺手收紧类型面。
+ *
+ * 不 import 官方类：官方包是 peer，小版本之间可能有增减；结构式引用让"官方少了一个
+ * 方法"变成一次运行时可读的降级，而不是调用点的 TypeError。
+ */
+interface OfficialManagerLike {
+    listPlugins(): Promise<PluginInfo[]>;
+    listBundles(): Promise<BundleInfo[]>;
+    inspect(spec: string, signal?: AbortSignal): Promise<PluginSpecInspection>;
+    setPluginEnabled(id: PluginEntryId, enabled: boolean): Promise<ChangeResult>;
+    setBundleEnabled(name: string, enabled: boolean): Promise<ChangeResult>;
+    installBundle(spec: string, options?: {
+        enabled?: boolean;
+        requestId?: string;
+        approvedBuilds?: readonly string[];
+    }): Promise<ChangeResult>;
+    removeBundle(name: string): Promise<ChangeResult>;
+}
+/** 官方能力调用失败的统一错误。 */
+export declare class OfficialUnavailableError extends Error {
+    readonly capability: string;
+    /**
+     * @param capability - 缺失的能力名（用于 UI 分组）。
+     * @param reason - 面向用户的原因说明。
+     */
+    constructor(capability: string, reason: string);
+}
+/**
+ * 取官方 pluginManager，缺失时抛出可读错误。
+ *
+ * 每个调用点都必须经过它——这样"官方不可用"永远以一个**具名错误**出现，
+ * 而不是 `undefined.listBundles is not a function`。
+ *
+ * 两层校验：服务存在（ctx.get）与**我们用到的方法存在**。第二层是 2026-09-19 补的：
+ * 官方改/删一个 Remote 方法时，用户原本看到调用点的 TypeError（读不懂）；现在得到的是
+ * "缺哪个方法"+"所以这项能力不可用"。
+ *
+ * @param ctx - 本插件的 host 上下文。
+ * @returns 官方管理器（结构式视图）。
+ * @throws {OfficialUnavailableError} 官方管理器未装配，或缺少我们调用到的方法时。
+ */
+export declare function requireManager(ctx: Context): OfficialManagerLike;
+/**
+ * 读运行时事实。
+ *
+ * 优先走官方 `readPluginInventory`（它对 Loader 的投影有自己的一致性保证），
+ * 拿不到时退回直接读 `ctx.loader.entries()`——用户明确要求"最大化利用能力，
+ * 但同时保证不出错"，所以两条路都要有，且**降级是显式的**。
+ *
+ * 返回的 `source` 让诊断页能如实标注数据来源：官方投影口径与直接读 Loader
+ * 口径在字段上一致，但前者会跳过 group 行，后者不会。
+ *
+ * @param ctx - 本插件的 host 上下文。
+ * @returns 运行时条目与数据来源；两者都不可用时 `entries` 为空且给出原因。
+ */
+export declare function readRuntimeInventory(ctx: Context): Promise<{
+    readonly entries: PluginInventorySnapshot['entries'];
+    readonly agentPresets: PluginInventorySnapshot['agentPresets'];
+    readonly source: 'official' | 'loader' | 'unavailable';
+    readonly reason?: string;
+}>;
+/**
+ * Cordis FiberState 到官方相位标签的映射。
+ *
+ * 数值取自 `@deepseek-ai/cordis` 的 `FiberState` 枚举（PENDING=0 …
+ * UNLOADING=5）。旧仓库自己定义了一套映射且与本表不一致，是实际缺陷；
+ * 这里逐项对齐官方 `plugin-inventory` 的 `FIBER_PHASE`。
+ *
+ * @param state - fiber.state 的原始数值；undefined 表示无存活 fiber。
+ * @returns 官方相位标签，或 null。
+ */
+export declare function fiberPhaseOf(state: unknown): PluginInventorySnapshot['entries'][number]['fiberPhase'];
+/**
+ * 官方能力缺失时是否应该继续。
+ *
+ * 只读检查（诊断、盘点）在能力缺失时**继续**，但把缺失记进报告的 `skipped`；
+ * 写操作必须**失败**，因为静默跳过写会让用户以为改了而实际没改。
+ *
+ * @param capabilities - 探针结果。
+ * @returns 可执行的只读检查项与不可执行的原因。
+ */
+export declare function readOnlyAvailability(capabilities: OfficialCapabilities): {
+    readonly canReadRuntime: boolean;
+    readonly reason?: string;
+};
+export {};