@dsh-workbench/shared 0.3.4 → 0.3.5

package/src/api/dsh.ts

@@ -1,14 +1,23 @@
+/**
+ * 宿主侧的日志口；info 与 warn 都可能没有，调用前要判存在。
+ */
 export interface DshLogger {
   info?(message: string): void;
   warn?(message: string): void;
 }
 
+/**
+ * 宿主 HTTP 路由拿到的请求：方法与 URL，请求体是异步可迭代的字节流。
+ */
 export interface DshRequest {
   readonly method?: string;
   readonly url?: string;
   [Symbol.asyncIterator]?(): AsyncIterator<Uint8Array>;
 }
 
+/**
+ * 宿主 HTTP 路由要写的响应：statusCode、setHeader 与 end 必备，流式那几个方法可选。
+ */
 export interface DshResponse {
   statusCode: number;
   setHeader(name: string, value: string): void;
@@ -18,32 +27,50 @@ export interface DshResponse {
   on?(event: 'close', listener: () => void): void;
 }
 
+/**
+ * 一条挂到 dsh web 服务器上的路由；kind 说明 path 是前缀还是全等匹配，handler 自己写响应。
+ */
 export interface DshWebRoute {
   readonly kind: 'prefix' | 'exact';
   readonly path: string;
   readonly handler: (req: DshRequest, res: DshResponse) => void | Promise<void>;
 }
 
+/**
+ * 宿主插件能看到的 profile 现场；dir 缺省表示 dsh 没给这个信息。
+ */
 export interface DshProfileContext {
   readonly dir?: string;
 }
 
+/**
+ * 工具声明的静态半（名字加其余关键字）；外壳只按 name 认工具。
+ */
 export interface DshToolSchema {
   readonly name: string;
   readonly [key: string]: unknown;
 }
 
+/**
+ * 系统提示词装配到一半的那份；tools 是可改的工具表，其余字段随 dsh。
+ */
 export interface DshPromptAssembly {
   readonly tools?: readonly DshToolSchema[] | undefined;
   readonly [key: string]: unknown;
 }
 
+/**
+ * 装配提示词时给判定方的现场（哪个 agent、哪个作用域）；两者都可能缺。
+ */
 export interface DshAssemblyContext {
   readonly agent?: unknown;
   readonly scope?: unknown;
   readonly [key: string]: unknown;
 }
 
+/**
+ * 宿主插件上下文：on 订阅 dsh 的钩子（提示词装配、工具执行前后、agent 生命周期），webServer 挂路由。
+ */
 export interface DshHostContext {
   on?: {
     (
@@ -107,6 +134,9 @@ export interface DshHostContext {
   readonly webServer: { register(route: DshWebRoute): () => void };
 }
 
+/**
+ * 一次 shell 执行的结果口：result() 给退出码、超时与中断标志，以及截断过的 stdout / stderr。
+ */
 export interface DshShellExecution {
   result(): Promise<{
     exitCode: number | null;
@@ -117,6 +147,9 @@ export interface DshShellExecution {
   }>;
 }
 
+/**
+ * dsh 的 shell 服务：先 resolve 出执行规格，再把它原样喂给 execute。
+ */
 export interface DshShell {
   resolve(request: {
     command: string;
@@ -129,14 +162,30 @@ export interface DshShell {
   execute(spec: unknown): Promise<DshShellExecution>;
 }
 
+/** 一条工作区记录：id、磁盘路径与显示名（登记处按路径认领 / 新建时认的就是它）。 */
+export interface DshWorkspaceRecord {
+  readonly id: string;
+  readonly path: string;
+  readonly title: string;
+}
+
+/**
+ * 宿主侧的工作区登记处：按 id 查、按路径认领、按路径新建。
+ */
 export interface DshWorkspaceRegistry {
   get(id: string): { id: string; path?: string; title?: string } | undefined;
-  resolveByPath(path: string): Promise<{ readonly id: unknown } | undefined>;
+  resolveByPath(path: string): Promise<DshWorkspaceRecord | undefined>;
   create(path: string, title?: string): Promise<{ id?: string; path?: string; title?: string } | undefined>;
 }
 
+/**
+ * 把相对路径拼成 dsh home 下的绝对路径（服务名 dshHomePath）；外壳存自己的状态用它，不自己拼 home。
+ */
 export type DshHomePath = (relative: string) => string;
 
+/**
+ * 要注册进 dsh 的一把工具：名字、描述、参数表、输出渲染与执行体。
+ */
 export interface DshToolDefinition {
   name: string;
   description: string;
@@ -148,6 +197,9 @@ export interface DshToolDefinition {
   execute(args: unknown, exec: DshToolRunContext): Promise<unknown>;
 }
 
+/**
+ * 工具执行时给的那点现场（会话 id 与 cwd）；层级都可能缺，缺了就当不知道。
+ */
 export interface DshToolRunContext {
   readonly agent?:
     | {
@@ -161,6 +213,9 @@ export interface DshToolRunContext {
     | undefined;
 }
 
+/**
+ * dsh 的工具表；register 回的清理函数负责在插件卸载时摘掉这条工具。
+ */
 export interface DshToolRegistry {
   register(definition: DshToolDefinition): () => void;
 }

package/src/api/facts.ts

@@ -1,27 +1,54 @@
+/**
+ * 宿主推来的一帧事实变更：rev 在同一纪元里单调，facts 是这一帧动过的名字。
+ */
 export interface FactFrame {
   readonly epoch?: string;
   readonly rev: number;
   readonly facts: readonly string[];
 }
 
+/**
+ * 范围查法的后缀：cmdb/* 这类名字表示「这个前缀下的一族」，不是一条事实。
+ */
 export const FACT_SCOPE_SUFFIX = '*';
 
+/**
+ * 由单元 id 拼出它那一族事实的范围名。
+ * @param unit 单元 id，不带后缀。
+ * @returns <unit>* —— 永远是范围名，不是某一条事实。
+ */
 export function unitFactScope(unit: string): string {
   return `${unit}${FACT_SCOPE_SUFFIX}`;
 }
 
+/**
+ * 判一个名字是不是范围查法，不是问这条事实存不存在。
+ * @param name 事实名或范围名。
+ * @returns 单字符 * 不算范围；只有「至少一个字符加 *」才算。
+ */
 export function isFactScope(name: string): boolean {
   return name.length > 1 && name.endsWith(FACT_SCOPE_SUFFIX);
 }
 
+/**
+ * 取范围名对应的前缀，普通事实名原样返回。
+ * @param name 事实名或范围名。
+ * @returns 去掉末尾 * 的前缀；本来不是范围就给原值。
+ */
 export function scopePrefixOf(name: string): string {
   return isFactScope(name) ? name.slice(0, -FACT_SCOPE_SUFFIX.length) : name;
 }
 
+/**
+ * 事实的来路：start 建连并按帧回调，cursor 报已收到的宿主 rev（断线重连时交给宿主）。
+ */
 export interface FactTransport {
   start(handlers: { readonly onFrame: (frame: FactFrame) => void; readonly cursor: () => number }): () => void;
 }
 
+/**
+ * 浏览器侧的事实通道：订阅、读版本、手动刷新，帧到了由它分发给订阅者。
+ */
 export interface FactChannel {
   subscribe(fact: string, listener: () => void): () => void;
   revisionOf(fact: string): number;
@@ -35,6 +62,11 @@ interface FactEntry {
   readonly listeners: Set<() => void>;
 }
 
+/**
+ * 造一条事实通道：第一次订阅时才连传输层，最后一个订阅者走掉就断开。
+ * @param options 传输层，用来连宿主。
+ * @returns 通道句柄；没记录过的事实版本给 0，refresh() 不带事实名时刷新全部并逐个通知。
+ */
 export function createFactChannel(options: { readonly transport: FactTransport }): FactChannel {
   const entries = new Map<string, FactEntry>();
   let epoch: string | null = null;
@@ -146,6 +178,11 @@ export function createFactChannel(options: { readonly transport: FactTransport }
   return channel;
 }
 
+/**
+ * 把传输层收到的原始数据读成一帧；坏数据当没收到。
+ * @param data 帧的原始数据，期望是 JSON 字符串。
+ * @returns 合法帧；不是字符串、JSON 坏了、或 rev 不是数字都给 null。
+ */
 export function parseFactFrame(data: unknown): FactFrame | null {
   if (typeof data !== 'string') return null;
   try {
@@ -161,6 +198,11 @@ export function parseFactFrame(data: unknown): FactFrame | null {
   }
 }
 
+/**
+ * 读口路由到事实名的映射，当前一对一。
+ * @param route 读口路由。
+ * @returns 该路由对应的事实名（就是路由本身）。
+ */
 export function factOfRoute(route: string): string {
   return route;
 }

package/src/api/host-write.ts

@@ -1,5 +1,8 @@
 import type { ApiResponse } from './workbench-client.js';
 
+/**
+ * 宿主写口的五条通道（偏好、动作、供给、工坊调试、工坊录制），是写路由的第一段。
+ */
 export type WriteChannel =
   | 'prefs'
   | 'actions'
@@ -7,11 +10,20 @@ export type WriteChannel =
   | 'diy-debug'
   | 'diy-record';
 
+/**
+ * 由通道与资源拼出写路由。
+ * @param channel 写通道。
+ * @param resource 该通道下的资源名。
+ * @returns 路由字符串；provision 只有一段，其余是 channel/resource。
+ */
 export function writeRoute(channel: WriteChannel, resource: string): string {
   if (channel === 'provision') return 'provision';
   return `${channel}/${resource}`;
 }
 
+/**
+ * 写通道统一的结果：成了带值，没成带一句能给人看的话（可选明细与帮助链接）。
+ */
 export type WriteOutcome<T> =
   | { readonly ok: true; readonly value: T }
   | {
@@ -21,6 +33,12 @@ export type WriteOutcome<T> =
       readonly helpUrl?: string;
     };
 
+/**
+ * 把写通道的响应翻成 WriteOutcome。
+ * @param response 写口回的响应；null 表示请求本身没成（网络断了，宿主没答）。
+ * @param networkText 拿不到任何服务端文案时兜底的那句。
+ * @returns 失败时 message 优先用服务端自己的话，没有才用响应正文或 networkText。
+ */
 export function writeOutcomeOf<T>(response: ApiResponse<T> | null, networkText: string): WriteOutcome<T> {
   if (response === null) return { ok: false, message: networkText };
   if (!response.ok) {

package/src/api/long-task.ts

@@ -1,28 +1,59 @@
+/**
+ * 一条长任务的四种态；needs-login 与 running 一样算还没结束。
+ */
 export type LongTaskStatus = 'running' | 'needs-login' | 'ok' | 'failed';
 
+/**
+ * 长任务步骤流里的一行：kind 定样式，登录那一步带 loginUrl 给用户去点。
+ */
 export interface LongTaskStep {
   readonly kind: 'start' | 'succeed' | 'fail' | 'info' | 'warn';
   readonly text: string;
   readonly loginUrl?: string | undefined;
 }
 
+/**
+ * 单元的长任务读口路由。
+ * @param unit 单元 id。
+ * @returns <unit>/runs。
+ */
 export function runsRouteOf(unit: string): string {
   return `${unit}/runs`;
 }
 
+/**
+ * 长任务读口回的载荷：一串 run，形状由模块自己定，外壳只透传。
+ */
 export interface LongTasksPayload {
   readonly runs: readonly Readonly<Record<string, unknown>>[];
 }
 
+/**
+ * 有长任务在跑时的轮询间隔（毫秒）。
+ */
 export const LONG_TASK_POLL_MS = 1500;
 
+/**
+ * 没有长任务时的轮询间隔（毫秒），比在跑那一档大一个量级。
+ */
 export const LONG_TASK_IDLE_MS = 10_000;
 
+/**
+ * 算这次该隔多久再问一次长任务。
+ * @param live 是否有在跑的长任务。
+ * @param override 调用点指定的间隔；给了就用它，不再看 live。
+ * @returns 毫秒：有活 1500，没活 10000。
+ */
 export function longTaskPollMs(live: boolean, override?: number | undefined): number {
   if (override !== undefined) return override;
   return live ? LONG_TASK_POLL_MS : LONG_TASK_IDLE_MS;
 }
 
+/**
+ * 从读口状态里取 run 列表。
+ * @param state 读口状态；value 还没到就按空算。
+ * @returns 一串 run（形状由调用点自己判），没有就给空数组。
+ */
 export function longTaskRunsOf<T>(state: {
   readonly phase?: string | undefined;
   readonly value?: LongTasksPayload | undefined;
@@ -30,6 +61,11 @@ export function longTaskRunsOf<T>(state: {
   return (state.value?.runs ?? []) as readonly T[];
 }
 
+/**
+ * 把长任务态折成状态点的那一档。
+ * @param status 长任务的四种态。
+ * @returns ongoing / done / error / idle；needs-login 也算进行中。
+ */
 export function longTaskDot(status: LongTaskStatus): 'ongoing' | 'done' | 'error' | 'idle' {
   if (status === 'ok') return 'done';
   if (status === 'failed') return 'error';

package/src/api/unit-board.ts

@@ -2,25 +2,45 @@ import type { ModuleBlocker } from './blocker.js';
 import type { CapabilityPayload } from './workbench-contract.js';
 import type { ApiError } from './workbench-client.js';
 
+/**
+ * 卡片闸的两种档：capability 按环境读数判，none 无条件放行。
+ */
 export type GateMode =
   | 'capability'
   | 'none';
 
+/**
+ * 一次放行判定的结果；gated 为假时卡片不画。
+ */
 export interface UnitGate {
   readonly gated: boolean;
 }
 
+/**
+ * 判这张卡现在能不能画。
+ * @param capability 环境读数；还没读到给 null。
+ * @param mode 闸档。
+ * @returns mode 为 none 或读数还没到都放行（先放行让它读）；读到明确不通过（ok 与 unchecked 之外）才拦。
+ */
 export function gateOf(capability: CapabilityPayload | null, mode: GateMode): UnitGate {
   if (mode === 'none') return { gated: true };
   if (capability === null) return { gated: true };
   return { gated: capability.status === 'ok' || capability.status === 'unchecked' };
 }
 
+/**
+ * 一个单元攒下的卡住态：blocker 顶掉卡片，notice 只提示；组装方产出，卡片消费。
+ */
 export interface UnitBlockers {
   readonly blocker?: ModuleBlocker;
   readonly notice?: ModuleBlocker;
 }
 
+/**
+ * 把候选卡住态分档，每档只留第一个。
+ * @param candidates 候选（可能含 undefined），按优先级从高到低给。
+ * @returns 分出的 blocker 与 notice；已经有 blocker 时不带 notice（挡住就不必再提示）。
+ */
 export function splitBlocker(candidates: readonly (ModuleBlocker | undefined)[]): UnitBlockers {
   let blocker: ModuleBlocker | undefined;
   let notice: ModuleBlocker | undefined;
@@ -38,6 +58,11 @@ export function splitBlocker(candidates: readonly (ModuleBlocker | undefined)[])
   };
 }
 
+/**
+ * 由读口错误算出「出错搭车强探」的防抖键：同一个键只自动重探一次。
+ * @param error 读口错误；undefined 表示这次没有错误。
+ * @returns 键字符串；空 code 归一到 unknown。
+ */
 export function probeKeyOf(error: ApiError | undefined): string | null {
   if (error === undefined) return null;
   return error.code === '' ? 'unknown' : error.code;

package/src/api/unit-declaration.ts

@@ -1,20 +1,35 @@
 import type { UnitEnvNeeds, UnitHostNeeds, UnitManifest } from './unit.js';
 
+/**
+ * 声明协议当前版本；模块清单的 dsh.workbench.apiVersion 要写这个整数。
+ */
 export const WORKBENCH_API_VERSION = 1;
 
+/**
+ * 外壳愿意认的协议版本；不在表里的模块当场被拒，不猜语义。
+ */
 export const SUPPORTED_API_VERSIONS: readonly number[] = [WORKBENCH_API_VERSION];
 
+/**
+ * 清单里那半张卡片声明：文案键加排序位；卡片默认显不显示不在这里（那是运行期面板配置的事）。
+ */
 export interface UnitCardDeclaration {
   readonly titleKey: string;
   readonly order: number;
 }
 
+/**
+ * 清单里的一条工具声明：进 dsh 工具表的全名、会不会写，以及生成物里的键名。
+ */
 export interface UnitToolDeclaration {
   readonly name: string;
   readonly writes: boolean;
   readonly key?: string;
 }
 
+/**
+ * 模块清单里 dsh.workbench 那一段的完整形状（协议版本、单元 id、卡片、工具、宿主与环境需要）。
+ */
 export interface UnitDeclaration {
   readonly apiVersion: number;
   readonly unit: string;
@@ -24,6 +39,9 @@ export interface UnitDeclaration {
   readonly env?: UnitEnvNeeds;
 }
 
+/**
+ * 协议认得的全部键；写了别的键不会被采纳（外壳静默忽略），所以字段名拼错不会有提示。
+ */
 export const DECLARATION_KEYS: readonly string[] = [
   'apiVersion',
   'unit',
@@ -33,6 +51,9 @@ export const DECLARATION_KEYS: readonly string[] = [
   'env',
 ];
 
+/**
+ * 协议要求必写的键；env 不在其中（没有环境需要就不写）。
+ */
 export const DECLARATION_REQUIRED_KEYS: readonly string[] = [
   'apiVersion',
   'unit',
@@ -70,6 +91,12 @@ function stringArrayProblems(at: string, value: unknown): string[] {
   );
 }
 
+/**
+ * 查清单里 dsh.workbench 那一段的形状，回一串给人看的问题（中文，带字段路径）。
+ * @param subject 报错时用的主语，一般是包名。
+ * @param raw 清单里那段原始值，可能什么都不是。
+ * @returns 空数组表示形状过得去；版本不对就当场返回（后面的字段无从判起）。
+ */
 export function declarationProblemsOf(subject: string, raw: unknown): readonly string[] {
   if (!isRecord(raw)) return [`${subject}: dsh.workbench 不是一个对象 —— ${JSON.stringify(raw)}`];
 
@@ -207,12 +234,21 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
   return problems;
 }
 
+/**
+ * 读一份清单的结果：要么带着规整过的声明与 manifest，要么只带一串问题。
+ */
 export interface DeclarationRead {
   readonly declaration?: UnitDeclaration;
   readonly manifest?: UnitManifest;
   readonly problems: readonly string[];
 }
 
+/**
+ * 读一份清单：先查形状，过了再把声明规整成 manifest。
+ * @param subject 报错时用的主语。
+ * @param raw 清单里 dsh.workbench 那段原始值。
+ * @returns 有问题时只有 problems；没问题时 declaration 与 manifest 都给，manifest 里的字符串已 trim。
+ */
 export function readDeclaration(subject: string, raw: unknown): DeclarationRead {
   const problems = declarationProblemsOf(subject, raw);
   if (problems.length > 0) return { problems };

package/src/api/unit.ts

@@ -1,18 +1,30 @@
+/**
+ * 一张卡片在清单里的静态声明（文案键加排序位）；默认显不显示由运行期面板配置定。
+ */
 export interface UnitCard {
   readonly titleKey: string;
   readonly order: number;
 }
 
+/**
+ * 一条工具在清单里的样子：全名加会不会写；审批按 writes 认领。
+ */
 export interface UnitTool {
   readonly name: string;
   readonly writes: boolean;
 }
 
+/**
+ * 模块要外壳的哪些服务：inject 缺一个就挂不上，optional 缺了照挂。
+ */
 export interface UnitHostNeeds {
   readonly inject: readonly string[];
   readonly optional?: readonly string[];
 }
 
+/**
+ * 一个 opencli 插件的来源三选一（git / 本地 / npm）；npm 那支的安装源先看 registryEnv 那个环境变量，没设才用 registryDefault。
+ */
 export type PluginSource =
   | { readonly kind: 'git'; readonly url: string }
   | { readonly kind: 'local'; readonly env: string }
@@ -23,12 +35,18 @@ export type PluginSource =
       readonly registryDefault?: string;
     };
 
+/**
+ * 模块要的一个 opencli 插件：名字、它得提供的命令，以及装它的来源（没写就是不代装）。
+ */
 export interface UnitPluginNeed {
   readonly name: string;
   readonly commands?: readonly string[];
   readonly installSource?: PluginSource;
 }
 
+/**
+ * 模块要的一个共用库：名字、期望范围与它为什么要这个版本（purpose 会进申报文案）。
+ */
 export interface UnitLibNeed {
   readonly name: string;
   readonly version?: string | undefined;
@@ -37,17 +55,26 @@ export interface UnitLibNeed {
   readonly purpose: string;
 }
 
+/**
+ * 模块的整份环境需要：一条自检命令，加上插件与共用库两张表。
+ */
 export interface UnitEnvNeeds {
   readonly command?: string;
   readonly plugins?: readonly UnitPluginNeed[];
   readonly libs?: readonly UnitLibNeed[];
 }
 
+/**
+ * 已装插件与源上最新版那一对，用来判该不该提示升级；latest 缺省表示还没查到。
+ */
 export interface PluginRelease {
   readonly installed: string;
   readonly latest?: string;
 }
 
+/**
+ * 装配期用的模块清单：单元 id、卡片、工具与宿主 / 环境需要，比声明少一层协议包装。
+ */
 export interface UnitManifest {
   readonly id: string;
   readonly card: UnitCard | null;
@@ -56,6 +83,11 @@ export interface UnitManifest {
   readonly env?: UnitEnvNeeds;
 }
 
+/**
+ * 判这个模块要不要往外装东西。
+ * @param manifest 模块清单。
+ * @returns 插件与共用库两张表都空时给 false。
+ */
 export function hasEnvSupply(manifest: UnitManifest): boolean {
   return (manifest.env?.plugins ?? []).length > 0 || (manifest.env?.libs ?? []).length > 0;
 }

package/src/api/workbench-client.ts

@@ -1,5 +1,8 @@
 import { API_PREFIX } from '../config/constants.js';
 
+/**
+ * 宿主读口 / 写口回的错误：code 给判据分档，message 给人看，helpUrl 有就去点。
+ */
 export interface ApiError {
   readonly code: string;
   readonly message: string;
@@ -8,14 +11,30 @@ export interface ApiError {
   readonly helpUrl?: string;
 }
 
+/**
+ * 读口的统一响应：成了把载荷摊平在顶层，没成只有一条 ApiError。
+ */
 export type ApiResponse<T> = ({ readonly ok: true } & T) | { readonly ok: false; readonly error: ApiError };
 
+/**
+ * GET 的查询参数：值为 undefined 的键直接丢掉，不进 URL。
+ */
 export type Query = Record<string, string | number | boolean | undefined>;
 
+/**
+ * GET 的可选项；目前只有中止信号。
+ */
 export interface ApiGetOptions {
   readonly signal?: AbortSignal | undefined;
 }
 
+/**
+ * 打一条宿主读口。
+ * @param route 路由，相对 API_PREFIX，不带前导斜杠。
+ * @param query 查询参数，undefined 的值不序列化。
+ * @param options 中止信号等。
+ * @returns HTTP 不是 2xx 时给 ok: false（code 为 http）；响应体不是 JSON 会当场抛，调用点要接住。
+ */
 export async function apiGet<T>(
   route: string,
   query: Query = {},
@@ -44,6 +63,12 @@ export async function apiGet<T>(
   return (await response.json()) as ApiResponse<T>;
 }
 
+/**
+ * 打一条宿主写口。
+ * @param route 路由，相对 API_PREFIX，不带前导斜杠。
+ * @param body 请求体，按 JSON 序列化。
+ * @returns HTTP 不是 2xx 时给 ok: false（code 为 http）；响应体不是 JSON 会当场抛。
+ */
 export async function apiPost<T>(route: string, body: Record<string, unknown>): Promise<ApiResponse<T>> {
   const response = await fetch(`${API_PREFIX}/${route}`, {
     method: 'POST',

package/src/api/workbench-contract.ts

@@ -1,5 +1,8 @@
 import type { PluginRelease } from '../api/unit.js';
 
+/**
+ * 供给动作的那几档（装 / 升 / 卸，模块、共用依赖与插件各一套）；写口按它分派。
+ */
 export type ProvisionAction =
   | 'install'
   | 'update'
@@ -13,6 +16,9 @@ export type ProvisionAction =
   | 'uninstall-plugin'
   | 'update-workbench';
 
+/**
+ * 宿主报的一个 opencli 插件此刻的状态：装没装、缺哪些命令、该不该升，以及怎么升。
+ */
 export interface PluginStatePayload {
   readonly name: string;
   readonly status: 'ok' | 'outdated' | 'missing';
@@ -22,6 +28,9 @@ export interface PluginStatePayload {
   readonly release?: PluginRelease;
 }
 
+/**
+ * 宿主对「这个单元现在能不能用」的那份读数：状态、缺的命令与插件、修复动作和供给细节。
+ */
 export interface CapabilityPayload {
   readonly unit: string;
   readonly status: 'ok' | 'failed' | 'missing-commands' | 'missing-plugin' | 'unchecked';
@@ -37,6 +46,9 @@ export interface CapabilityPayload {
   readonly libs?: readonly LibStatePayload[];
 }
 
+/**
+ * 宿主报的一个共用库此刻的状态（装没装、版本对不对）与它为什么要这个版本。
+ */
 export interface LibStatePayload {
   readonly name: string;
   readonly purpose: string;