dsh-plugin-manager-companion 0.1.0

package/dist/client/shared.d.ts

@@ -0,0 +1,928 @@
+/**
+ * 客户端共享层 — 自有 REST 调用面、状态控制器与官方插件页 slot 契约的镜像。
+ *
+ * 归属：A 类·重写（旧仓库 src/client/api.ts 与 store.ts 只作意图参考，未复制代码）。
+ * 旧实现参考：dsh-web-plugin-manager/src/client/*（理解"客户端要读什么、什么时候刷新"的意图）。
+ * 官方复用：@deepseek-ai/dsh-client-store 的 createSnapshotStore（状态容器）、
+ *   @deepseek-ai/dsh-client-ui-slots 的 ComposedProps/EntryKeyOf（组件 props 的组合别名）、
+ *   @deepseek-ai/dsh-client-ui-settings/client 的 ctx.settingsScope（配置读写，不碰 YAML）。
+ * 前提检查：旧实现自带 27 个 op 的客户端 SDK + 乐观更新 + 自建 job 轮询。0.1.6 之后
+ *   官方能力（插件启停/安装/清单）客户端直连官方 Remote，本插件的自有能力按
+ *   docs/REST-CONTRACT.md 走 /api2/companion；乐观更新被取消（变更必须等 job 落定）。
+ *
+ * 四条纪律：
+ *   1. 变更类请求不带 AbortSignal（中止只杀传输，会留下"改了但没反馈"的状态），
+ *      只有加载类请求可以带。
+ *   2. 组件不订阅任何外部源：控制器持有 SnapshotStore，经 inject 的 hooks 隔间
+ *      合成 use<Name> 选择器 Hook。
+ *   3. 这一层不认识 React，也不认识 ctx；它只做数据与动作。
+ *   4. **外来数据在这里归一**：REST 与官方 settings 的返回值先过 wire.ts 的归一函数，
+ *      再进 SnapshotStore。组件因此可以按类型直接读字段——这一步是实测驱动的：不归一
+ *      时，一个缺字段的载荷会让官方 SlotErrorBoundary 把整个 settings.section 渲染成空 div。
+ */
+import { type SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import { type RelativeTimeUnit, type TagTone } from '@deepseek-ai/dsh-client-ui-primitives';
+import type { ComposedProps, EntryKeyOf, SlotMap, TranslateNS } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import { type MarketLabelKey } from '../marketView.ts';
+import type { OfficialCapabilities } from '../official.ts';
+import type { CompanionConfig } from '../settings.ts';
+import type { DiagnosticGroup, DiagnosticIssue, DiagnosticLayer, DiagnosticReport, DiagnosticSeverity, EnvironmentBackup, EnvironmentBackupDiff, EnvironmentInfo, InstalledKind, MarketItemKind, MarketplaceResult } from '../types.ts';
+import { NS, type CompanionLocaleKey } from './locales.ts';
+import { type AboutFactsView, type ClientConfig, type TrialDisclosureView, type TrialEnvironmentsView, type TrialOutcomeView, type UpgradeCheckView } from './wire.ts';
+import { type UpgradeOutcomeKind } from '../upgradeView.ts';
+/**
+ * 官方 settings 服务上本插件的命名空间。
+ *
+ * 与 host 侧 src/settings.ts 的 SETTINGS_NAMESPACE 必须一致；这里刻意不 import 那个
+ * 模块的值：它是一个 host 模块（值会拉进 schemastery 与整套 host 代码），客户端只
+ * 认这个字符串。改名时必须两处同改（settings.ts 的 schema 注册会拒绝未知命名空间）。
+ */
+export declare const SETTINGS_NAMESPACE = "plugin-manager-companion";
+/** 自有 REST 的路由前缀（host 侧 src/rest.ts 的 ROUTE_PREFIX）。 */
+export declare const REST_PREFIX = "/api2/companion";
+/**
+ * REST 调用失败。code 是稳定机器码（见 REST-CONTRACT 的错误码表），
+ * message 面向用户，可直接展示。
+ */
+export declare class CompanionError extends Error {
+    readonly code: string;
+    /**
+     * @param code - 稳定机器码。
+     * @param message - 面向用户的说明。
+     */
+    constructor(code: string, message: string);
+}
+/**
+ * 调用一个自有 op。
+ *
+ * @param op - 操作名。
+ * @param body - 请求体（JSON-safe）。
+ * @param signal - 仅加载类请求可传；变更类一律不传。
+ * @returns 信封里的 value。
+ * @throws {CompanionError} 信封为失败，或 HTTP 层失败时。
+ */
+export declare function callOp<T>(op: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+/** 可注入的等待实现，测试可替换。 */
+export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+/**
+ * 跑一个被 job 化的长操作：POST 拿 jobId，再轮询 job 直到落定。
+ *
+ * 为什么必须等：变更类操作在服务端推进，HTTP 超时与服务端状态会脱节；乐观更新
+ * 会让 UI 显示一个并未发生的成功（REST-CONTRACT 明确禁止）。
+ *
+ * @param op - 操作名。
+ * @param body - 请求体。
+ * @param signal - 加载类长操作可传，用于中止轮询。
+ * @returns job 的最终结果。
+ * @throws {CompanionError} job 失败、结果丢失或轮询被中止时。
+ */
+export declare function runJob<T>(op: string, body?: unknown, signal?: AbortSignal): Promise<T>;
+/**
+ * 官方 `plugins.*` 配置面的 owner props（镜像官方
+ * packages/client/ui-plugin-manager/src/client/slot-contract.ts 的
+ * PluginConfigViewProps；官方包不在本仓库的安装集里，所以这里按逐字镜像声明）。
+ *
+ * 漂移风险：官方若改这个契约，必须同步这里——注册面本身是编译期检查的，
+ * 运行期由官方页面渲染，类型对不上就是渲染出错的第一个信号。
+ */
+export interface PluginConfigViewProps {
+    /** summary 只渲染标题下的一句话；page 渲染带自己保存控件的表单。 */
+    readonly view: 'summary' | 'page';
+}
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface SlotMap {
+        /** 官方插件页的官方插件卡片（list）。 */
+        'plugins.item': {
+            kind: 'list';
+            scope: 'root';
+            owner: PluginConfigViewProps;
+        };
+        /** 一个组合包自己的配置，key 是包名（keyed）。 */
+        'plugins.bundle.config': {
+            kind: 'keyed';
+            scope: 'root';
+            owner: PluginConfigViewProps;
+        };
+        /** 一行自己的配置，key 是 `<包名>#<行 id>`（keyed）。 */
+        'plugins.row.config': {
+            kind: 'keyed';
+            scope: 'root';
+            owner: PluginConfigViewProps;
+        };
+    }
+}
+/**
+ * 一个本插件注册项的完整组件 props：官方组合别名 + 本插件字典命名空间的 t 座位。
+ * 直接用官方 ComposedProps，绝不手写派生成员（packages/client/AGENTS.md 的 slot 纪律）。
+ */
+export type CompanionSlotProps<K extends keyof SlotMap & string, I extends object> = ComposedProps<K, EntryKeyOf<K>, never, undefined, I, never, typeof NS>;
+/** 诊断层的展示顺序与字典键。 */
+export declare const LAYER_ORDER: readonly DiagnosticLayer[];
+/** 层 → 字典键。 */
+export declare const LAYER_LABEL: Readonly<Record<DiagnosticLayer, CompanionLocaleKey>>;
+/** 诊断层 → 配置表单里的标签键（与体检页的层名分开：一处是报告，一处是开关）。 */
+export declare const DIAGNOSTIC_LABEL: Readonly<Record<DiagnosticLayer, CompanionLocaleKey>>;
+/** 处置等级 → 字典键。 */
+export declare const SEVERITY_LABEL: Readonly<Record<DiagnosticSeverity, CompanionLocaleKey>>;
+/** 处置等级 → Tag 色调（可自动修复是好消息，只报告才是需要读者注意的）。 */
+export declare const SEVERITY_TONE: Readonly<Record<DiagnosticSeverity, TagTone>>;
+/** 市场条目类型 → 字典键。 */
+export declare const KIND_LABEL: Readonly<Record<MarketItemKind, CompanionLocaleKey>>;
+/**
+ * 市场纯函数模块给出的字典键 → 本插件字典键。
+ *
+ * 市场管道（src/marketView.ts）只产出**键名**，文案归字典所有；这里做一次映射，
+ * 类型上要求 MarketLabelKey 全集，少一个键就编译失败。
+ */
+export declare const MARKET_LABEL: Readonly<Record<MarketLabelKey, CompanionLocaleKey>>;
+/**
+ * 健康分：满分 100，按最严重的处置等级扣分。
+ *
+ * 旧实现按问题条数线性扣分，一个 C 级问题就能把分数打到 0，读数失去意义；
+ * 这里改成按等级加权——可自动修复扣 5、需确认扣 10、只报告扣 20，下限 0。
+ *
+ * @param issues - 报告里的发现。
+ * @returns 0..100 的整数。
+ */
+export declare function healthScore(issues: readonly DiagnosticIssue[]): number;
+/** 相对时间的桶 → 字典键（词条归字典所有，分桶由官方 relativeTime 给出）。 */
+export declare const RELATIVE_LABEL: Readonly<Record<RelativeTimeUnit, CompanionLocaleKey>>;
+/**
+ * 把 ISO 时间渲染成"刚刚 / 5 分钟前…"。
+ *
+ * 分桶用官方 relativeTime（两个界面说同一时刻必须用同一个桶），词条来自本插件字典。
+ * now 取调用时刻：这是展示函数，不参与纯计算，也不需要 uSES 语义。
+ *
+ * @param t - 本插件字典的翻译函数。
+ * @param iso - ISO 8601 时间串；无法解析时原样返回。
+ * @returns 已本地化的相对时间文本。
+ */
+export declare function formatRelative(t: TranslateNS<typeof NS>, iso: string): string;
+/**
+ * 一个层值 → 字典键。
+ *
+ * 报告来自外部（host），所以层值可能是本客户端不认识的字符串；此时返回 undefined，
+ * 由组件回退成显示原始 id。直接 `t(LAYER_LABEL[layer])` 会把未知值渲染成 undefined。
+ *
+ * @param layer - 报告里的层值。
+ * @returns 字典键；未知层值时 undefined。
+ */
+export declare function layerLabelKey(layer: string): CompanionLocaleKey | undefined;
+/**
+ * 处置等级 → 字典键。
+ * @param severity - 报告里的等级值。
+ * @returns 字典键；未知等级时 undefined。
+ */
+export declare function severityLabelKey(severity: string): CompanionLocaleKey | undefined;
+/**
+ * 处置等级 → Tag 色调。
+ * @param severity - 报告里的等级值。
+ * @returns 色调；未知等级按"需注意"显示（绝不把未知降级成好色调）。
+ */
+export declare function severityToneOf(severity: string): TagTone;
+/**
+ * 证据类型 → 展示用标识。
+ * @param kind - 证据里的类型值。
+ * @returns 展示标识；未知类型原样显示（技术标识不做翻译）。
+ */
+export declare function evidenceKindOf(kind: string): string;
+/**
+ * 一条发现是否属于某个分组。
+ *
+ * 判据只用 wire 上真实存在的字段（层 / 类别 / 等级 + 作用域清单），**不重算 host 的组键格式**：
+ * 键是实现细节，而"这一组包含哪些发现"必须能从契约字段推出来。发现自身没有 scope 时按
+ * 空串对待（与 host 的"无法归属即空串"一致）；组没有作用域清单时，层+类别+等级相同即同组。
+ *
+ * @param issue - 一条发现。
+ * @param group - 报告里的一个分组。
+ * @returns 属于该组时为 true。
+ */
+export declare function issueInGroup(issue: DiagnosticIssue, group: DiagnosticGroup): boolean;
+/** 证据类型 → 展示用前缀（不做翻译：文件/运行时/官方是技术标识）。 */
+export declare const EVIDENCE_KIND: Readonly<Record<'file' | 'runtime' | 'official', string>>;
+/**
+ * 体检子页的状态。
+ *
+ * 字段刻意**不是** readonly：这是 SnapshotStore 的 draft，控制器通过 update 就地改它。
+ */
+export interface HealthState {
+    report: DiagnosticReport | undefined;
+    running: boolean;
+    error: string | undefined;
+    /** 客户端自己判定的失败（载荷残缺等）；文案归字典，控制层只给键。 */
+    errorKey?: CompanionLocaleKey;
+    /**
+     * 当前这条失败**来自哪个动作**：诊断还是修复。
+     *
+     * 为什么必须是显式字段：靠"notice 写过没有"这种间接线索归因时不成立——修复走 callOp 抛异常
+     * 的那条路径只写 error、不写 notice，界面于是把"修复失败"说成"体检失败"（真机实测的 P1）。
+     * 写入规则：谁写下当前这条失败，谁就写这里；它描述的失败被清掉时同步清成 undefined。
+     */
+    failureFrom?: 'diagnose' | 'fix' | undefined;
+    /**
+     * 诊断目标环境名；undefined 表示当前环境。
+     *
+     * 为什么保留 undefined 而不是在控制器里解析成当前环境名：控制器不认识 profile 列表
+     * （那是 host 的事实）。界面把"用户选的就是当前环境"折回 undefined，语义只有两个：
+     * "当前环境"与"某个具名环境"。
+     */
+    target: string | undefined;
+    /** 正在执行修复的 issue id。 */
+    fixingId: string | undefined;
+    /** 最近一次修复的输出。 */
+    notice: string | undefined;
+    /** 官方能力探针：哪里能力缺失要如实告诉用户，而不是把缺失伪装成健康。 */
+    capabilities: OfficialCapabilities | undefined;
+}
+/** 体检子页的注入面：hooks 隔间合成 useHealth 选择器 Hook。 */
+export interface HealthFace {
+    hooks: {
+        health: SnapshotStore<HealthState>;
+    };
+    /** 跑一次全量（或指定层）诊断。 */
+    diagnose(layers?: readonly DiagnosticLayer[]): void;
+    /** 执行一条发现的修复动作。 */
+    fix(issue: DiagnosticIssue): void;
+    /**
+     * 切换诊断目标环境；undefined 表示当前环境。
+     *
+     * 切换会**立刻丢弃**上一份报告（报告属于某个环境，跨环境复用它的展开状态与修复按钮
+     * 就是事故），并立即重跑诊断；在途的那次响应按代号作废。
+     */
+    setDiagnosticTarget(environment: string | undefined): void;
+}
+/** 体检控制器：持有报告状态，动作全部走自有 REST。 */
+export declare class HealthController {
+    private readonly store;
+    /**
+     * 诊断代号：每次目标切换或重新诊断自增。
+     *
+     * 用途唯一——作废在途的响应。用户在诊断跑到一半时切了环境，旧环境的报告绝不能
+     * 落进新目标的状态里（那会让"报告属于哪个环境"变成一个谎言）。
+     */
+    private generation;
+    /**
+     * 诊断与修复**各记各的失败**：诊断成功只清自己写下的那条，修复失败不会被顺手抹掉
+     * （与 client-dev 在 task-18 修的 ReadFailureLedger 同一思路——读的成功不该清掉操作的失败）。
+     */
+    private readonly diagnoseFailure;
+    private readonly fixFailure;
+    constructor();
+    /** 供注册项使用的注入面。 */
+    inject(): HealthFace;
+    /**
+     * 切换诊断目标环境。
+     * @param environment - 目标环境名；undefined 表示当前环境。
+     */
+    setTarget(environment: string | undefined): void;
+    /**
+     * 跑一次诊断（用户动作）。
+     *
+     * 会清掉上一条**动作结果**（notice）：用户主动体检即"处置"了上一次动作留下的提示。
+     * @param layers - 只诊断这些层；省略即按配置全量。
+     */
+    diagnose(layers?: readonly DiagnosticLayer[]): Promise<void>;
+    /**
+     * 修复之后的自动刷新：报告必须更新，但修复的结果提示要留着。
+     *
+     * 为什么不能直接用 diagnose()：那是"用户主动体检"，开头会清 notice；而这条 notice 是用户
+     * 刚点的那个修复动作的产物（成功与失败都一样），在同一个 0ms 内被清掉等于用户什么都没看到
+     * （真机实测时间线：+0ms 写 notice → +0ms 被自动刷新清掉）。
+     */
+    private refreshAfterFix;
+    /**
+     * 诊断主体：两条入口（用户体检 / 修复后的自动刷新）只差"要不要保留上一条动作结果"。
+     * @param layers - 只诊断这些层；省略即按配置全量。
+     * @param options - keepNotice 为真时保留上一条动作结果（修复的产物）。
+     */
+    private runDiagnosis;
+    /**
+     * 执行一条修复动作。
+     * @param issue - 带 fix 的发现。
+     */
+    fix(issue: DiagnosticIssue): Promise<void>;
+}
+/** 环境子页的状态。 */
+export interface EnvironmentsState {
+    environments: readonly EnvironmentInfo[];
+    loading: boolean;
+    /** 正在执行的操作名（用于按钮禁用与提示）。 */
+    busy: string | undefined;
+    error: string | undefined;
+    /** 客户端自己判定的失败（载荷残缺、备份文件格式不对）；文案归字典。 */
+    errorKey?: CompanionLocaleKey;
+    notice: string | undefined;
+    /** 已读入内存的备份文档。 */
+    backup: EnvironmentBackup | undefined;
+    /** 最近一次差异对比结果。 */
+    diff: EnvironmentBackupDiff | undefined;
+}
+/** 环境子页的注入面。 */
+export interface EnvironmentsFace {
+    hooks: {
+        environments: SnapshotStore<EnvironmentsState>;
+    };
+    refreshEnvironments(): void;
+    /** 启动一个环境；background 为真时不占用前台终端。 */
+    startEnvironment(name: string, background: boolean): void;
+    stopEnvironment(name: string): void;
+    createEnvironment(name: string, template?: string): void;
+    renameEnvironment(from: string, to: string): void;
+    removeEnvironment(name: string): void;
+    copyPlugins(from: string, to: string, names: readonly string[]): void;
+    /** 导出备份：结果同时下载成文件并留在状态里供对比。 */
+    exportBackup(name: string): void;
+    /** 读入一个备份文件（浏览器 File，由 UI 的 file input 提供）。 */
+    loadBackup(file: File): void;
+    /** 对比已读入的备份与目标环境。 */
+    diffBackup(target: string): void;
+    /** 用已读入的备份恢复目标环境。 */
+    restoreBackup(target: string): void;
+    /** 清掉上一次操作的通知与错误。 */
+    dismissEnvironmentNotice(): void;
+}
+/** 环境控制器。 */
+export declare class EnvironmentsController {
+    private readonly store;
+    /** "读列表"写下的失败；只有它能被下一次成功的读取清掉（见 ReadFailureLedger）。 */
+    private readonly readFailure;
+    constructor();
+    /** 供注册项使用的注入面。 */
+    inject(): EnvironmentsFace;
+    /**
+     * 重新读环境列表。
+     *
+     * **只动 loading**：`notice` / `error` 描述的是"上一次操作"，刷新列表是另一回事，
+     * 无权替操作宣布结果。这里曾经先清 error/errorKey，而 act() 是"先落结果、再 refresh"——
+     * 于是写操作失败后马上被这一行抹掉，结果块的 exitCode 恒为 0、界面上呈现成"完成"
+     * （真机复现：复制插件填一个不存在的包 → 结果块「完成」，输出却是失败文本）。
+     *
+     * 为什么不改成"把落定挪到 refresh 之后"：那要求每个新操作都记得排序，本 bug 正是
+     * 这种调用顺序约定失效的产物；而"刷新列表不碰操作结果"是一条不依赖调用方记性的规则。
+     * 失败态由操作自身清零（每个操作开始时清）与 dismissEnvironmentNotice 负责。
+     */
+    refresh(): Promise<void>;
+    /**
+     * 跑一个变更类操作：写 busy → 执行 → 记结果 → 刷新列表。
+     *
+     * 变更一律不带 AbortSignal：中止只杀传输，服务端仍会推进。
+     *
+     * @param label - 操作标签，用于 UI 的忙碌提示。
+     * @param task - 具体调用（返回值一律过归一，形状不对时如实报失败而不是当成功）。
+     */
+    private act;
+    /**
+     * 导出备份。
+     * @param name - 被备份的环境名。
+     */
+    exportBackup(name: string): Promise<void>;
+    /**
+     * 读入备份文件。
+     * @param file - 浏览器 File 对象。
+     */
+    loadBackup(file: File): Promise<void>;
+    /**
+     * 差异对比。
+     * @param target - 目标环境名。
+     */
+    diffBackup(target: string): Promise<void>;
+    /**
+     * 用已读入的备份恢复目标环境。
+     * @param target - 目标环境名。
+     */
+    restoreBackup(target: string): Promise<void>;
+}
+/** 市场子页的状态。 */
+export interface MarketplaceState {
+    result: MarketplaceResult | undefined;
+    loading: boolean;
+    error: string | undefined;
+    /** 客户端自己判定的失败（索引载荷残缺）；文案归字典。 */
+    errorKey?: CompanionLocaleKey;
+    query: string;
+    /** 选中的分类 id；空串表示全部。 */
+    category: string;
+    /** 选中的类型；空串表示全部。 */
+    kind: MarketItemKind | '';
+    /** 正在安装的条目 repo。 */
+    installing: string | undefined;
+    installError: string | undefined;
+    /** 质量门发现的问题（安装未通过时保留，供用户追责）。 */
+    gateIssues: readonly string[];
+    rolledBack: boolean;
+    /**
+     * 这次安装的试装结论（质量门第二步）。undefined = 宿主没给这个字段，
+     * 而不是"试装通过"——界面据此区分"没试装"与"试装通过"。
+     */
+    trial: TrialOutcomeView | undefined;
+}
+/** 市场子页的注入面。 */
+export interface MarketplaceFace {
+    hooks: {
+        marketplace: SnapshotStore<MarketplaceState>;
+    };
+    loadMarketplace(refresh: boolean): void;
+    setMarketQuery(query: string): void;
+    setMarketCategory(category: string): void;
+    setMarketKind(kind: MarketItemKind | ''): void;
+    installMarketItem(item: MarketItemView): void;
+    dismissInstallNotice(): void;
+}
+/** 市场条目在 UI 侧的稳定视图（只带渲染与安装需要的字段）。 */
+export interface MarketItemView {
+    readonly repo: string;
+    readonly name: string;
+    /**
+     * 安装 spec —— **host 侧给的**（MarketItem.installSpec），客户端只负责原样转发。
+     *
+     * 不在这里拼字符串是有意的：官方 parseInstallSpec 只认 registry 名 / 绝对路径 / git URL /
+     * tarball 四种形态，而市场条目的天然键是 owner/repo（不在其中，官方直接判 invalid-spec）。
+     * 那套规则若在客户端再实现一份，索引字段一变就要改两处，且必然漂移。
+     * 契约上可选：老载荷没有这个字段时不猜——送空串，由 host 的字段校验如实报错。
+     */
+    readonly installSpec?: string;
+}
+/** 市场控制器。 */
+export declare class MarketplaceController {
+    private readonly store;
+    /** "读索引"写下的失败；只有它能被下一次成功的读取清掉（见 ReadFailureLedger）。 */
+    private readonly readFailure;
+    constructor();
+    /** 供注册项使用的注入面。 */
+    inject(): MarketplaceFace;
+    /**
+     * 读市场索引。
+     * @param refresh - 是否强制绕过缓存。
+     */
+    load(refresh: boolean): Promise<void>;
+    /**
+     * 经质量门安装一个市场条目。
+     *
+     * spec 由 host 决定（MarketItem.installSpec），本方法**只转发**；缺失时送空串，
+     * 让 host 的字段校验给出可读错误，而不是在这里编一个 spec 出来。
+     *
+     * @param item - 要安装的条目。
+     */
+    install(item: MarketItemView): Promise<void>;
+}
+/** 技能与预设子页的状态。 */
+export interface KindsState {
+    records: readonly InstalledKind[];
+    orphans: readonly string[];
+    loading: boolean;
+    error: string | undefined;
+    /** 客户端自己判定的失败（载荷残缺）；文案归字典。 */
+    errorKey?: CompanionLocaleKey;
+    busy: string | undefined;
+    notice: string | undefined;
+}
+/** 技能与预设子页的注入面。 */
+export interface KindsFace {
+    hooks: {
+        kinds: SnapshotStore<KindsState>;
+    };
+    loadKinds(): void;
+    uninstallKind(repo: string): void;
+}
+/** 技能与预设控制器。 */
+export declare class KindsController {
+    private readonly store;
+    /** "读记录"写下的失败；只有它能被下一次成功的读取清掉（见 ReadFailureLedger）。 */
+    private readonly readFailure;
+    constructor();
+    /** 供注册项使用的注入面。 */
+    inject(): KindsFace;
+    /** 读技能与预设记录。 */
+    load(): Promise<void>;
+    /**
+     * 卸载一个已安装的技能或预设。
+     * @param repo - owner/repo。
+     */
+    uninstall(repo: string): Promise<void>;
+}
+/** 设置子页的状态：官方 settings 的镜像 + 本地草稿。 */
+export interface ConfigState {
+    status: 'loading' | 'ready' | 'unavailable';
+    writable: boolean;
+    /** 官方已解析的当前值（原样保留：保存时的"前后对比"和写盘路径都以它为准）。 */
+    value: CompanionConfig | undefined;
+    /**
+     * 渲染用草稿：已过 wire 归一（缺字段按客户端默认值补齐）再叠加本地编辑。
+     *
+     * 类型是 {@link ClientConfig} 而不是 host 的 CompanionConfig：host 侧 `trial` 是可选字段，
+     * 归一后它一定存在——组件因此不需要（也不许）在读取处替它兜默认值。
+     */
+    draft: ClientConfig | undefined;
+    /** 宿主给的文档缺字段（draft 里有默认值补出来的部分）——界面要如实说明。 */
+    incomplete: boolean;
+    dirty: boolean;
+    saving: boolean;
+    failed: boolean;
+    saved: boolean;
+}
+/** 设置子页的注入面。 */
+export interface ConfigFace {
+    hooks: {
+        config: SnapshotStore<ConfigState>;
+    };
+    /** 改一个字段（路径是命名空间内的嵌套路径）。 */
+    editConfigField(path: readonly string[], value: unknown): void;
+    saveConfig(): void;
+    discardConfig(): void;
+}
+/** 设置控制器：草稿 + 一次保存写全部改动（与官方插件配置页同一交互模型）。 */
+export declare class ConfigController {
+    private readonly scope;
+    private readonly store;
+    private staged;
+    /**
+     * @param scope - 官方 settings 服务上本插件命名空间的句柄。
+     */
+    constructor(scope: SettingsScope<CompanionConfig>);
+    /** 供注册项使用的注入面。 */
+    inject(): ConfigFace;
+    /** 把官方快照与本地草稿合成一份状态。 */
+    private publish;
+    /**
+     * 暂存一个字段编辑（不写盘；保存时才写）。
+     * @param path - 命名空间内的路径。
+     * @param value - 新值。
+     */
+    edit(path: readonly string[], value: unknown): void;
+    /** 丢弃所有暂存编辑。 */
+    discard(): void;
+    /** 保存全部暂存编辑（一次 mutate，天然共用同一个修订栅栏）。 */
+    save(): Promise<void>;
+}
+/** 上一次试装环境变更的结果（结构化：界面按 kind 选文案，不把整句拼进状态）。 */
+export interface TrialActionState {
+    readonly kind: 'remove' | 'cleanup';
+    readonly ok: boolean;
+    readonly removed: readonly string[];
+    readonly output: string;
+    readonly code?: string;
+}
+/** 「设置」子页里试装那一节的状态。 */
+export interface TrialState {
+    /** 披露事实（capabilities op 的 trialDisclosure）；undefined = 还没读到或读不到。 */
+    disclosure: TrialDisclosureView | undefined;
+    /** 披露读不到的原因（宿主消息）。 */
+    disclosureError: string | undefined;
+    /** 披露读不到的原因（我们自己的判定，文案归字典）。 */
+    disclosureErrorKey?: CompanionLocaleKey;
+    /** 测试环境报告；undefined = 还没读到或读失败（界面据此显示加载中/失败，不显示"没有测试环境"）。 */
+    report: TrialEnvironmentsView | undefined;
+    loading: boolean;
+    /** 正在执行的动作标签（与官方页一致的 动词+名字 形态）。 */
+    busy: string | undefined;
+    /** 读列表自己写下的失败（只有它能被下一次成功的读取清掉）。 */
+    error: string | undefined;
+    errorKey?: CompanionLocaleKey;
+    /** 上一次变更操作的结果（成功也留，直到用户处置）。 */
+    action: TrialActionState | undefined;
+}
+/** 试装管理面的注入面。 */
+export interface TrialFace {
+    hooks: {
+        trial: SnapshotStore<TrialState>;
+    };
+    loadTrial(): void;
+    removeTrialEnvironment(name: string): void;
+    cleanupTrialEnvironments(): void;
+}
+/**
+ * 试装控制器：读披露事实与测试环境列表，执行"删除一个"与"清理过期"。
+ *
+ * 披露事实走 capabilities op 而不是在客户端抄一份数字：数字与口径由 host 给；
+ * 抄一份就会在下次实测后漂移，而漂移的是"用户以为自己承担了什么风险"。
+ */
+export declare class TrialController {
+    private readonly store;
+    /** "读列表"写下的失败；只有它能被下一次成功的读取清掉（见 ReadFailureLedger）。 */
+    private readonly readFailure;
+    constructor();
+    /** 供注册项使用的注入面。 */
+    inject(): TrialFace;
+    /**
+     * 读披露事实 + 测试环境列表。
+     *
+     * 只动 loading / 自己写下的读失败：action 描述的是"上一次操作"，刷新无权替它宣布结果
+     * （task-18 的真机 P1：读操作清掉写操作的结果，失败就被渲染成完成）。披露读不到时也只记原因，
+     * 不让整节变成不可用——用户仍能改配置，只是看不到"会发生什么"。
+     */
+    load(): Promise<void>;
+    /**
+     * 删除一个测试环境。
+     * @param name - 测试环境名。
+     */
+    remove(name: string): Promise<void>;
+    /** 清理过期的测试环境（走 job：可能跨多个目录）。 */
+    cleanup(): Promise<void>;
+    /**
+     * 跑一个变更类操作：写 busy → 执行 → 落结果 → 刷新列表。
+     *
+     * 结果必须先落定再刷新：反过来会让刚写下的失败被 refresh 抹掉（task-18 的 P1 就是这个顺序）。
+     *
+     * @param kind - 操作种类（界面按它选文案）。
+     * @param label - 忙碌提示用的标签。
+     * @param task - 具体调用（返回值一律过归一，形状不对时如实报失败而不是当成功）。
+     */
+    private act;
+}
+/**
+ * 升级那一块的状态。
+ *
+ * 三块事实各自独立，**不合并**：
+ *   · check：最近一次 upgradeCheck 的结果（四态就在这里）；
+ *   · busy：正在跑的包名（升级是长操作，界面据此禁用入口）；
+ *   · action：最近一次升级/回滚的结果 —— 它必须活到用户处置为止，
+ *     不能被任何一次刷新抹掉（task-18 的真机 P1：读操作清掉写操作的结果，失败被渲染成完成）。
+ */
+export interface UpgradeState {
+    /** 检查结果；undefined = 还没查过（界面据此显示"还没检查"，不是"已是最新"）。 */
+    check: UpgradeCheckView | undefined;
+    loading: boolean;
+    /** 读检查结果自己写下的失败（只有它能被下一次成功的读取清掉）。 */
+    error: string | undefined;
+    /** 客户端自己判定的失败（载荷残缺）；文案归字典。 */
+    errorKey?: CompanionLocaleKey;
+    /** 正在升级的包名。 */
+    busy: string | undefined;
+    /** 最近一次升级的结果（成功也留，直到用户处置或下一次升级开始）。 */
+    action: UpgradeActionResultState | undefined;
+    /** 最近一次回滚的结果。 */
+    rollback: UpgradeRollbackResultState | undefined;
+}
+/** 一次升级的结果（结构化：界面按 outcome 选文案，不把整句拼进状态）。 */
+export interface UpgradeActionResultState {
+    /** 诚实分类：done / rolled-back / failed / unverified（见 upgradeView.upgradeOutcome）。 */
+    readonly outcome: UpgradeOutcomeKind;
+    readonly name: string;
+    readonly fromVersion: string | null;
+    readonly toVersion: string;
+    readonly ok: boolean;
+    readonly output: string;
+    readonly code?: string;
+    /** 金丝雀的读法：passed / failed / not-run / absent（没验证 ≠ 验证失败 ≠ 通过）。 */
+    readonly canary: 'passed' | 'failed' | 'not-run' | 'absent';
+    /** 没跑金丝雀的原因（ran===false 时才有）。 */
+    readonly canaryNote?: string;
+    /**
+     * 金丝雀的**完整结论原文**（含根因链）。
+     *
+     * 为什么必须带出来：顶层的 output 是"结论与后果"那一层，而用户追责要看的是
+     * 根因链（例如 duplicate loader entry id）。丢掉它，界面只能说"没通过"，
+     * 用户拿不到任何可查的东西——task-78/80 的验收明确要求根因链可见。
+     */
+    readonly canaryOutput?: string;
+    /** 金丝雀的激活证据：候选有没有真的进测试环境的层栈。 */
+    readonly canaryActivated?: boolean;
+    readonly restartRequired: boolean;
+    readonly diskFacts: readonly string[];
+    /**
+     * 本次升级用的 spec（host 的官方 add 收到的那个）。
+     *
+     * 为什么结果态要带它：回滚入口就长在这个块里，而回滚需要它来判断"原来是不是本地来源"。
+     * 缺了它，回滚会把 link: 装的包换成 registry 版本——那不是回滚，是换来源。
+     */
+    readonly spec?: string;
+}
+/** 一次回滚的结果。 */
+export interface UpgradeRollbackResultState {
+    readonly name: string;
+    readonly ok: boolean;
+    readonly output: string;
+    readonly code?: string;
+    readonly fromVersion: string | null;
+    readonly toVersion: string;
+    /** 盘上核对是否一致；undefined = 读不出来（不是"不干净"）。 */
+    readonly clean: boolean | undefined;
+    readonly diskFacts: readonly string[];
+}
+/** 升级动作的注入面（官方插件页的升级行与市场页卡片共用同一份）。 */
+export interface UpgradeFace {
+    hooks: {
+        upgrade: SnapshotStore<UpgradeState>;
+    };
+    /**
+     * 进入即查：**同一会话内只发一次**（TTL / 开关 / 负缓存判定都在 host 侧，客户端不重复实现）。
+     *
+     * 为什么需要这个去重口："进入即查"的触发点在**渲染期**（官方插件页/市场页挂载时的 effect），
+     * 而这两个面会被反复挂载。没有去重就会变成"每开一次页面出一趟网"，
+     * 而 TTL 的语义是"距上次成功检查超过间隔才查"——去重的依据在 host，触发次数得由客户端收住。
+     */
+    ensureUpgrades(): void;
+    /** 手动检查（无视开关、TTL 与负缓存）；refresh=true 是用户点的重试。 */
+    loadUpgrades(refresh: boolean): void;
+    /** 升级一个包到指定版本（长操作，走 job）。 */
+    upgradePackage(name: string, version: string, spec?: string): void;
+    /** 回滚一个包到指定版本。 */
+    rollbackPackage(name: string, version: string, spec?: string): void;
+    /** 处置（清掉）最近一次升级结果。 */
+    dismissUpgradeNotice(): void;
+}
+/**
+ * 本页只列"这套软件本身"的单元（DESIGN §5.5 的用户裁决）。
+ *
+ * 三类都在，但**第三方插件一律不出现在这一页**——它们的升级入口是官方插件页里该包自己的页面
+ * 与市场页卡片。所以这里不能简单地"把 units 全画出来"，必须筛。
+ *
+ * 判据用 **host 已经分好的 `kind`**，不自己按包名猜：
+ *   · `installation-provided` → ① 官方运行时（全局安装的那份）；
+ *   · `profile-dependency`    → ② 官方自带实验包（与第三方在**同一类**里，靠包名分）；
+ *   · `self`                  → ③ 本插件自身。
+ * ②与第三方同 kind，所以还需要一条"是不是官方的"判据，见 {@link isOfficialPackage}。
+ */
+export declare const SOFTWARE_UNIT_KINDS: readonly string[];
+/**
+ * 一个包名是否属于官方（`@deepseek-ai/` 作用域）。
+ *
+ * 为什么用作用域而不是维护一张白名单：官方包名会随版本增删（`dsh-experimental-*` 尤其），
+ * 白名单一过期就会**静默漏掉一个该显示的单元**；作用域是发布方自己定的、稳定的。
+ * 与仓库既有判据同源（`src/diagnostics.ts` 的 `name.startsWith('@deepseek-ai/')`）。
+ *
+ * 注意：本插件自身（`dsh-plugin-manager-companion`）**不在**这个作用域里，
+ * 但它必须显示——所以判据是"官方 或 本插件自身"，见 {@link isSoftwareUnit}。
+ *
+ * @param name - 包名。
+ * @returns 是否官方作用域。
+ */
+export declare function isOfficialPackage(name: string): boolean;
+/**
+ * 一个升级单元是否属于"这套软件本身"（本页要显示的）。
+ *
+ * @param unit - 单元视图（只要有 name / kind 两个字段）。
+ * @returns 是否显示在这一页。
+ */
+export declare function isSoftwareUnit(unit: {
+    readonly name: string;
+    readonly kind: string;
+}): boolean;
+/**
+ * 从全部单元里挑出本页要显示的，并按三类排好（① → ② → ③，类内按包名）。
+ *
+ * 为什么固定顺序：用户来这一页是依次看"官方运行时能不能升 / 实验包能不能升 / 我自己能不能升"，
+ * 顺序随检查结果的返回次序变会让每次打开都长得不一样。
+ *
+ * @param units - 检查结果里的全部单元。
+ * @returns 本页要显示的单元（已排序）。
+ */
+export declare function softwareUnits<T extends {
+    readonly name: string;
+    readonly kind: string;
+}>(units: readonly T[]): readonly T[];
+/** 「关于」页的状态。 */
+export interface AboutState {
+    /** 事实集合；undefined = 还没读到（界面显示"还没读到"，不是一张空表）。 */
+    facts: AboutFactsView | undefined;
+    loading: boolean;
+    /** 读失败的原因（op 挂了）；文案归字典。 */
+    error: string | undefined;
+    errorKey?: CompanionLocaleKey;
+}
+/** 「关于」页的注入面。 */
+export interface AboutFace {
+    hooks: {
+        about: SnapshotStore<AboutState>;
+    };
+    /**
+     * 读一次事实。
+     *
+     * 与升级面的"进入即查"不同，这里**不去重**：关于页读的是本地事实（无网络、无副作用），
+     * 每次进入重读一遍反而更准（缓存年龄会随时间变、用户可能刚删了缓存文件）。
+     * 去重那一套是为"出网"设计的，套在这里只会让数字变旧。
+     *
+     * @param refresh - 用户点的重试（与首次进入走同一条路，保留参数是为了接口一致）。
+     */
+    loadAbout(refresh: boolean): void;
+}
+/**
+ * 「关于」页的控制器。
+ *
+ * 与 UpgradeController 同一形状（store + 读失败账本），但**没有** busy / 动作结果——
+ * 这一页纯读，没有任何写动作，所以不需要那些字段。
+ */
+export declare class AboutController {
+    private readonly store;
+    /** "读事实"写下的失败；只有它能被下一次成功的读取清掉（见 ReadFailureLedger）。 */
+    private readonly readFailure;
+    constructor();
+    /** 供注册项使用的注入面。 */
+    inject(): AboutFace;
+    /** 当前快照。 */
+    snapshot(): AboutState;
+    /**
+     * 读一次事实。
+     *
+     * 只动 loading / 自己写下的读失败——与升级面同一条纪律：
+     * 一次刷新无权替上一次的失败宣布结果。
+     *
+     * @param _refresh - 用户点的重试（本 op 无缓存，参数不影响读法）。
+     */
+    load(_refresh: boolean): Promise<void>;
+}
+/**
+ * 市场页的注入面：市场自己的面 + 升级面。
+ *
+ * 为什么写成一个显式接口（而不是 `MarketplaceFace & UpgradeFace`）：两边的 hooks 记录
+ * 用交叉类型表达时，官方 `PropsHooks` 的映射类型在交叉上**推导不出** useMarketplace /
+ * useUpgrade 两个成员（实测编译报"Property 'useMarketplace' is missing"）。
+ * 一个显式的 hooks 记录把两件事说清楚，也省掉一处会被读错的类型体操。
+ */
+export interface MarketplaceConsoleFace {
+    hooks: {
+        marketplace: SnapshotStore<MarketplaceState>;
+        upgrade: SnapshotStore<UpgradeState>;
+    };
+    loadMarketplace(refresh: boolean): void;
+    setMarketQuery(query: string): void;
+    setMarketCategory(category: string): void;
+    setMarketKind(kind: MarketItemKind | ''): void;
+    installMarketItem(item: MarketItemView): void;
+    dismissInstallNotice(): void;
+    ensureUpgrades(): void;
+    loadUpgrades(refresh: boolean): void;
+    upgradePackage(name: string, version: string, spec?: string): void;
+    rollbackPackage(name: string, version: string, spec?: string): void;
+    dismissUpgradeNotice(): void;
+}
+/**
+ * 升级控制器。
+ *
+ * 两条纪律与其它控制器一致，另加一条本块特有的：
+ *   · **不做乐观更新**：升级结果只由 job 的落定结果写入（REST-CONTRACT 明确禁止）；
+ *   · **失败不吞**：载荷残缺记 errorKey，host 报错记 error，两者都不写进 action；
+ *   · **升级成功后立刻重查**（版本事实过期了），但重查**不许**清掉刚写下的结果
+ *     —— 顺序必须是"先落结果、再刷新"（task-18 的 P1 就是这个顺序）。
+ */
+export declare class UpgradeController {
+    private readonly store;
+    /** "读检查结果"写下的失败；只有它能被下一次成功的读取清掉（见 ReadFailureLedger）。 */
+    private readonly readFailure;
+    /** 进入即查是否已经发过（一次会话一次；见 ensureLoaded）。 */
+    private kicked;
+    constructor();
+    /** 供注册项使用的注入面。 */
+    inject(): UpgradeFace;
+    /** 当前快照（index.ts 的注册对账要读它）。 */
+    snapshot(): UpgradeState;
+    /**
+     * 进入即查的**去重口**：一次会话只发一次（见 {@link UpgradeFace.ensureUpgrades}）。
+     *
+     * 已经查过（成功或失败）就不再发；手动检查与台账变化走 {@link load}，绕过这个闸门。
+     */
+    ensureLoaded(): Promise<void>;
+    /**
+     * 读一次升级检查结果。
+     *
+     * 只动 loading / 自己写下的读失败：action 描述的是"上一次操作"，刷新无权替它宣布结果。
+     *
+     * @param refresh - 手动检查（无视开关、TTL 与负缓存）。
+     */
+    load(refresh: boolean): Promise<void>;
+    /**
+     * 升级一个包（长操作：走 job + 轮询）。
+     *
+     * 结果落定后**先写 action，再重查**——顺序反过来，重查会清掉刚写下的失败。
+     *
+     * @param name - 包名。
+     * @param version - 目标版本。
+     * @param spec - 当前来源（host 据此判断"升级会改变来源"与回滚目标）。
+     */
+    upgrade(name: string, version: string, spec?: string): Promise<void>;
+    /**
+     * 回滚一个包到指定版本。
+     *
+     * @param name - 包名。
+     * @param version - 回滚目标版本。
+     * @param spec - 原来源（本地来源时回滚装回那个来源）。
+     */
+    rollback(name: string, version: string, spec?: string): Promise<void>;
+}
+/**
+ * 把字节数格式化成紧凑文本。
+ *
+ * 单位是量纲不是文案，两种语言共用，因此不进字典。
+ *
+ * @param bytes - 字节数。
+ * @returns 形如 12.3 MiB 的文本。
+ */
+export declare function formatBytes(bytes: number): string;
+/**
+ * 环境控制台注册项的组合注入面：体检、环境、设置三块能力共用一个注册项
+ * （一个入口 + 本地子页面，所以只声明一份 face）。
+ *
+ * 试装（质量门第二步）的字段与测试环境管理都在「设置」子页里，所以它的面也挂在这一份上。
+ */
+export type ConsoleFace = HealthFace & EnvironmentsFace & ConfigFace & TrialFace;
+/**
+ * 把一份 JSON 触发成浏览器下载。
+ *
+ * 只在浏览器里执行：非浏览器渲染环境（测试）下 document 不存在，此时静默跳过——
+ * 备份内容已留在状态里，UI 仍可对比与恢复。
+ *
+ * @param fileName - 建议的文件名。
+ * @param payload - 要写进文件的内容。
+ */
+export declare function downloadJson(fileName: string, payload: unknown): void;