@dsh-workbench/shared 0.3.4 → 0.3.6

package/dist/api/blocker-table.d.ts

@@ -2,8 +2,21 @@ import type { Translate } from './dsh-client.js';
 import type { CapabilityPayload } from './workbench-contract.js';
 import type { ApiError } from './workbench-client.js';
 import type { ModuleBlocker } from './blocker.js';
+/**
+ * 把一次读失败翻成一张卡住态，交给卡片直接渲染。
+ * @param error 读口回的错误；undefined 表示连错误都没拿到（多半是网络断，回「原因未知」）。
+ * @param t 文案函数，只取 blocker.* 命名空间的键。
+ * @param context 判定现场；platform 缺省时标题不带平台名。
+ * @returns 一定有一张卡，actions 至少一颗「重试」。
+ */
 export declare function blockerOfError(error: ApiError | undefined, t: Translate, context?: {
     path?: string | null;
     platform?: string;
 }): ModuleBlocker;
+/**
+ * 把宿主回的环境读数翻成卡住态：探针没查过（unchecked）只算提示，不挡卡片。
+ * @param capability 宿主回的单元环境读数。
+ * @param t 文案函数，键都在 env.unit.* / blocker.* 下。
+ * @returns status 为 'ok' 时给 undefined（没有卡住态），其余状态一律给一张。
+ */
 export declare function blockerOfCapability(capability: CapabilityPayload, t: Translate): ModuleBlocker | undefined;

package/dist/api/blocker-table.js

@@ -5,6 +5,13 @@ function retryAction(t) {
 function copyAction(t, text) {
     return { kind: 'copy', label: t('blocker.copy'), text };
 }
+/**
+ * 把一次读失败翻成一张卡住态，交给卡片直接渲染。
+ * @param error 读口回的错误；undefined 表示连错误都没拿到（多半是网络断，回「原因未知」）。
+ * @param t 文案函数，只取 blocker.* 命名空间的键。
+ * @param context 判定现场；platform 缺省时标题不带平台名。
+ * @returns 一定有一张卡，actions 至少一颗「重试」。
+ */
 export function blockerOfError(error, t, context = {}) {
     if (error === undefined) {
         return {
@@ -82,6 +89,12 @@ export function blockerOfError(error, t, context = {}) {
             };
     }
 }
+/**
+ * 把宿主回的环境读数翻成卡住态：探针没查过（unchecked）只算提示，不挡卡片。
+ * @param capability 宿主回的单元环境读数。
+ * @param t 文案函数，键都在 env.unit.* / blocker.* 下。
+ * @returns status 为 'ok' 时给 undefined（没有卡住态），其余状态一律给一张。
+ */
 export function blockerOfCapability(capability, t) {
     if (capability.status === 'ok')
         return undefined;

package/dist/api/blocker.d.ts

@@ -1,3 +1,6 @@
+/**
+ * 卡住时用户能点的那一下（开链接 / 复制命令 / 重试 / 装或升模块）：由判据产出，卡片照原样渲染。
+ */
 export type BlockerAction = {
     readonly kind: 'open-url';
     readonly label: string;
@@ -20,6 +23,9 @@ export type BlockerAction = {
     readonly label: string;
     readonly unit: string;
 };
+/**
+ * 一个单元此刻的卡住态：block 顶掉整张卡片，notice 只在角上提示一句；读口与探针产出，卡片消费。
+ */
 export interface ModuleBlocker {
     readonly id: string;
     readonly severity: 'block' | 'notice';

package/dist/api/context-ref.d.ts

@@ -1,10 +1,41 @@
+/**
+ * 引用标记的固定名字；完整标记是 @<这个名字>:<编码文本>，改它等于作废历史会话里已写下的引用。
+ */
 export declare const CONTEXT_MARKER_NAME = "\u5DE5\u4F5C\u53F0";
+/**
+ * 一条解析后的引用（种类加路径分段）：输入框写标记时产出，跳转与展示时消费。
+ */
 export interface ContextRef {
     readonly kind: string;
     readonly parts: readonly string[];
 }
+/**
+ * 把引用拼回标记体里的那一段文本（不含 @ 与标记名）。
+ * @param ref 要拼的引用。
+ * @returns 形如 kind:part/part；分段里的 / 不转义，所以分段名本身不能含 /。
+ */
 export declare function encodeRef(ref: ContextRef): string;
+/**
+ * 把 kind:part/part 文本读回引用。
+ * @param text 待解析文本。
+ * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
+ */
 export declare function decodeRef(text: string): ContextRef | undefined;
+/**
+ * 拼出 @ 后面那半截（标记名加已编码文本），比较与拼接都用它。
+ * @param encoded encodeRef 的结果。
+ * @returns 形如 工作台:file:src/a.ts。
+ */
 export declare function markerBody(encoded: string): string;
+/**
+ * 把一条引用拼成能写进对话文本的完整标记。
+ * @param ref 要标记的引用。
+ * @returns 形如 @工作台:file:src/a.ts 的一段文本。
+ */
 export declare function buildMarker(ref: ContextRef): string;
+/**
+ * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
+ * @param text 任意文本；null / undefined 当空串。
+ * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
+ */
 export declare function parseMarkers(text: string): ContextRef[];

package/dist/api/context-ref.js

@@ -1,9 +1,22 @@
+/**
+ * 引用标记的固定名字；完整标记是 @<这个名字>:<编码文本>，改它等于作废历史会话里已写下的引用。
+ */
 export const CONTEXT_MARKER_NAME = '工作台';
 const MARKER = new RegExp(`@${CONTEXT_MARKER_NAME}:([a-z][a-z0-9-]*:[A-Za-z0-9._~%#/-]+)`, 'g');
 const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
+/**
+ * 把引用拼回标记体里的那一段文本（不含 @ 与标记名）。
+ * @param ref 要拼的引用。
+ * @returns 形如 kind:part/part；分段里的 / 不转义，所以分段名本身不能含 /。
+ */
 export function encodeRef(ref) {
     return `${ref.kind}:${ref.parts.join('/')}`;
 }
+/**
+ * 把 kind:part/part 文本读回引用。
+ * @param text 待解析文本。
+ * @returns 没冒号、冒号在首尾、种类不是小写字母开头、或冒号后为空时给 undefined；不抛异常。
+ */
 export function decodeRef(text) {
     const at = text.indexOf(':');
     if (at <= 0 || at === text.length - 1)
@@ -16,12 +29,27 @@ export function decodeRef(text) {
         return undefined;
     return { kind, parts };
 }
+/**
+ * 拼出 @ 后面那半截（标记名加已编码文本），比较与拼接都用它。
+ * @param encoded encodeRef 的结果。
+ * @returns 形如 工作台:file:src/a.ts。
+ */
 export function markerBody(encoded) {
     return `${CONTEXT_MARKER_NAME}:${encoded}`;
 }
+/**
+ * 把一条引用拼成能写进对话文本的完整标记。
+ * @param ref 要标记的引用。
+ * @returns 形如 @工作台:file:src/a.ts 的一段文本。
+ */
 export function buildMarker(ref) {
     return `@${markerBody(encodeRef(ref))}`;
 }
+/**
+ * 从一段文本里按出现顺序捞出所有标记引用，同一个引用只留第一次。
+ * @param text 任意文本；null / undefined 当空串。
+ * @returns 解析不出来的标记会被丢掉，所以结果只含合法引用，可能为空数组。
+ */
 export function parseMarkers(text) {
     const seen = new Set();
     const refs = [];

package/dist/api/dsh-client.d.ts

@@ -1,4 +1,7 @@
 import type { ReactNode } from 'react';
+/**
+ * 左栏一行的来源：dsh workspaces.list 快照里的一项，两个时间戳都是毫秒。
+ */
 export interface WorkspaceView {
     readonly workspaceId: string;
     readonly path: string;
@@ -7,11 +10,17 @@ export interface WorkspaceView {
     readonly createdAt: number;
     readonly updatedAt: number;
 }
+/**
+ * workspaces.list 的整份快照：可见工作区，加上归档与置顶的会话 id；外壳只读不改。
+ */
 export interface WorkspaceSnapshot {
     readonly items: readonly WorkspaceView[];
     readonly archivedSessionIds: readonly string[];
     readonly pinnedSessionIds: readonly string[];
 }
+/**
+ * 会话一行的来源（标题、空会话、在跑与否、被谁留住）；retainedBy 按视图名记留住它的份数，mainView 大于 0 即正被主视图占着。
+ */
 export interface SessionSummary {
     readonly id: string;
     readonly displayTitle: string;
@@ -21,9 +30,15 @@ export interface SessionSummary {
     readonly origin?: string;
     readonly retainedBy: Readonly<Partial<Record<string, number>>>;
 }
+/**
+ * 会话投影里的一条子代理目录项；外壳只认 id，其余字段随 dsh 变。
+ */
 export interface SubagentCatalogEntry {
     readonly id: string;
 }
+/**
+ * dsh sessions.list 的快照：按 id 找会话，投影里可能挂着一串子代理目录。
+ */
 export interface SessionsSnapshot {
     readonly byId: Readonly<Record<string, SessionSummary>>;
     readonly projectionsBySession: Readonly<Record<string, {
@@ -32,6 +47,9 @@ export interface SessionsSnapshot {
         };
     } | undefined>>;
 }
+/**
+ * 一个会话的三个状态位（在跑 / 有未读完成 / 等着用户交互）；字段缺省就是这一位不知道。
+ */
 export interface SessionStatus {
     readonly running?: boolean;
     readonly completionUnread?: boolean;
@@ -39,22 +57,43 @@ export interface SessionStatus {
         readonly kind?: string;
     };
 }
+/**
+ * 会话 id 到状态位的只读表；查不到的 id 就是没有这一条状态。
+ */
 export type SessionStatusSnapshot = ReadonlyMap<string, SessionStatus>;
+/**
+ * dsh layout 的面板选择位；activePanelId 为 null 表示用户把面板关了。
+ */
 export interface PanelInfo {
     readonly activePanelId: string | null;
 }
+/**
+ * 某个插槽上注册着的一项（id、顺序、文案）；label 允许是函数，因为文案要跟语言走。
+ */
 export interface PanelEntry {
     readonly id: string;
     readonly order: number;
     readonly label: string | (() => string);
 }
+/**
+ * 选择器 hook 的形状（dsh 那套 useSyncExternalStore）：外壳拿它从快照里取一小块并在变更时重取。
+ */
 export type SnapshotSelectorHook<T> = <R>(selector: (state: T) => R) => R;
+/**
+ * 渲染 dsh 某个插槽的函数；key 定插槽，fallback 是空槽兜底，only 用来只渲染其中一个注册项。
+ */
 export type RenderSlot = (key: string, owner?: Record<string, unknown>, options?: {
     fallback?: ReactNode;
     hookContext?: unknown;
     only?: string;
 }) => ReactNode;
+/**
+ * 文案函数：给键（可带参数）回一句当前语言的文本；缺键时由 dsh 决定回什么，调用点不兜。
+ */
 export type Translate = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * 往 dsh 插槽注册一项要给的参数；priority 与 order 小者靠前，inject 声明这一项要用到的作用域。
+ */
 export interface SlotRegisterOptions {
     name: string;
     priority?: number;
@@ -66,6 +105,9 @@ export interface SlotRegisterOptions {
     children?: Record<string, unknown>;
     inject?: (scope?: unknown) => Record<string, unknown>;
 }
+/**
+ * dsh 的插槽服务：注册一项、注入作用域、订阅变更，以及按名取已注册项。
+ */
 export interface DshSlots {
     inject(name: string, callback: () => void | (() => void) | Iterable<() => void>): () => void;
     register(options: SlotRegisterOptions, component: unknown): () => void;
@@ -76,10 +118,16 @@ export interface DshSlots {
     specDynamic?(name: string): unknown;
     onMutate?(callback: (name: string) => void): () => void;
 }
+/**
+ * dsh 的语言服务：按命名空间注册字典，再取回那个命名空间的文案函数。
+ */
 export interface DshLocale {
     register(namespace: string, dictionaries: Record<string, Record<string, string>>): () => void;
     bind(namespace: string): Translate;
 }
+/**
+ * dsh 的布局服务：选面板、开关左栏、开合右栏；右栏宽度经可选的 panels 写。
+ */
 export interface DshLayout {
     selectPanel(panelId: string | null): void;
     toggleSidebar(): void;
@@ -87,25 +135,43 @@ export interface DshLayout {
     closeRightbar(): void;
     readonly panels?: DshLayoutPanels;
 }
+/**
+ * layout 上那个可选的右栏宽度写口；dsh 没给这一位时右栏宽度就只是内存态。
+ */
 export interface DshLayoutPanels {
     setRightbar?(px: number): void;
 }
+/**
+ * 快捷键目录的口子；外壳只把它透出去，形状与内容随 dsh。
+ */
 export interface DshShortcutCatalog {
     readonly catalog: unknown;
 }
+/**
+ * 起一个新会话时能带的选项；目前只有 agent 预设这一项。
+ */
 export interface DshSessionStartOptions {
     readonly agentPreset?: string;
 }
+/**
+ * dsh 的工作区与会话动作：开工作区、开会话、起会话、挑目录。
+ */
 export interface DshUiWorkspace {
     openWorkspace(workspaceId: string): Promise<unknown>;
     openSession(sessionId: string): void;
     startSession(workspaceId: string, options?: DshSessionStartOptions): void;
     pickDirectory(): Promise<string | null>;
 }
+/**
+ * 工作区写口回的那点事实（新 id 或新标题）；字段都可能缺，缺了按「没写回」算。
+ */
 export interface DshWorkspaceWritten {
     readonly workspaceId?: string;
     readonly title?: string;
 }
+/**
+ * dsh 的工作区服务：list 是可订阅快照，create 与 rename 是写口。
+ */
 export interface DshWorkspaces {
     readonly list: DshObservable<WorkspaceSnapshot>;
     create(request: {
@@ -113,6 +179,9 @@ export interface DshWorkspaces {
     }): Promise<DshWorkspaceWritten | undefined>;
     rename(workspaceId: string, title: string): Promise<DshWorkspaceWritten>;
 }
+/**
+ * 往输入框插一条引用时要给的载荷：来源、引用文本、显示文案与剪贴板文本。
+ */
 export interface DshReferenceInsert {
     readonly source: string;
     readonly ref: string;
@@ -120,11 +189,17 @@ export interface DshReferenceInsert {
     readonly appearance?: 'session' | 'file' | 'folder';
     readonly clipboardText: string;
 }
+/**
+ * 输入框里一段 token 的区间；draftRev 用来确认还是同一版草稿，插入引用时用它定位。
+ */
 export interface DshTokenSpan {
     readonly start: number;
     readonly end: number;
     readonly draftRev: number;
 }
+/**
+ * 某一个会话的输入框句柄；外壳借它插引用与弹提示，state 用来核对草稿版本。
+ */
 export interface DshSessionInput {
     caretSpan?: () => {
         start: number;
@@ -138,6 +213,9 @@ export interface DshSessionInput {
     insertReference(ref: DshReferenceInsert, span: DshTokenSpan): boolean;
     notify(level: 'info' | 'error', text: string): void;
 }
+/**
+ * 注册 @ 触发源的口子：候选由外壳现取，选中后的动作也归外壳，dsh 只负责触发。
+ */
 export interface DshInputTriggers {
     registerSource(source: {
         readonly trigger: '@';
@@ -153,11 +231,17 @@ export interface DshInputTriggers {
         };
     }): () => void;
 }
+/**
+ * dsh 的对话服务；外壳只用它按会话取输入框句柄。
+ */
 export interface DshConversationService {
     readonly input: {
         for(actx: unknown): DshSessionInput;
     };
 }
+/**
+ * 浏览器侧的会话服务：快照加按 id 取作用域；create 是可选写口，不是每个 dsh 版本都有。
+ */
 export interface DshSessionsService {
     readonly list: {
         getSnapshot(): SessionsSnapshot;
@@ -170,10 +254,16 @@ export interface DshSessionsService {
         readonly agentPreset?: string;
     }): Promise<unknown>;
 }
+/**
+ * dsh 侧最小的可订阅值：取当前快照加订阅变更，外壳用它接进 React。
+ */
 export interface DshObservable<T> {
     getSnapshot(): T;
     subscribe(listener: () => void): () => void;
 }
+/**
+ * dsh 的右栏服务：mounted 是在场与否的可订阅值，展开与开资源另走方法。
+ */
 export interface DshSidebarRight {
     readonly mounted: DshObservable<string | undefined>;
     isExpanded(): boolean;
@@ -181,6 +271,9 @@ export interface DshSidebarRight {
     openResource(address: string, options?: unknown): void;
     openTab(kind: string, options?: unknown): void;
 }
+/**
+ * remote.sessions 写口：在宿主侧建会话并回会话 id。
+ */
 export interface DshSessionsRemote {
     create(request: {
         readonly workspaceId?: string;
@@ -190,9 +283,15 @@ export interface DshSessionsRemote {
         readonly sessionId: string;
     }>;
 }
+/**
+ * dsh 客户端的远端写口集合；目前只有会话一家。
+ */
 export interface DshClientRemote {
     readonly sessions: DshSessionsRemote;
 }
+/**
+ * 客户端插件拿到的上下文：所有服务从它取，effect 注册的清理随插件卸载跑。
+ */
 export interface DshClientContext {
     get<T = unknown>(name: string): T | undefined;
     provide(name: string, value: unknown): void;

package/dist/api/dsh.d.ts

@@ -1,12 +1,21 @@
+/**
+ * 宿主侧的日志口；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;
@@ -15,27 +24,45 @@ export interface DshResponse {
     write?(chunk: string): void;
     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?: {
         (event: 'system-prompt/assemble', listener: (assembly: DshPromptAssembly, context: DshAssemblyContext, next: () => Promise<DshPromptAssembly>) => Promise<DshPromptAssembly>): (() => void) | undefined;
@@ -97,6 +124,9 @@ export interface DshHostContext {
         register(route: DshWebRoute): () => void;
     };
 }
+/**
+ * 一次 shell 执行的结果口：result() 给退出码、超时与中断标志，以及截断过的 stdout / stderr。
+ */
 export interface DshShellExecution {
     result(): Promise<{
         exitCode: number | null;
@@ -112,6 +142,9 @@ export interface DshShellExecution {
         };
     }>;
 }
+/**
+ * dsh 的 shell 服务：先 resolve 出执行规格，再把它原样喂给 execute。
+ */
 export interface DshShell {
     resolve(request: {
         command: string;
@@ -123,22 +156,35 @@ export interface DshShell {
     }): unknown;
     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;
@@ -149,6 +195,9 @@ export interface DshToolDefinition {
     };
     execute(args: unknown, exec: DshToolRunContext): Promise<unknown>;
 }
+/**
+ * 工具执行时给的那点现场（会话 id 与 cwd）；层级都可能缺，缺了就当不知道。
+ */
 export interface DshToolRunContext {
     readonly agent?: {
         readonly session?: {
@@ -159,6 +208,9 @@ export interface DshToolRunContext {
         } | undefined;
     } | undefined;
 }
+/**
+ * dsh 的工具表；register 回的清理函数负责在插件卸载时摘掉这条工具。
+ */
 export interface DshToolRegistry {
     register(definition: DshToolDefinition): () => void;
 }

package/dist/api/facts.d.ts

@@ -1,18 +1,45 @@
+/**
+ * 宿主推来的一帧事实变更：rev 在同一纪元里单调，facts 是这一帧动过的名字。
+ */
 export interface FactFrame {
     readonly epoch?: string;
     readonly rev: number;
     readonly facts: readonly string[];
 }
+/**
+ * 范围查法的后缀：cmdb/* 这类名字表示「这个前缀下的一族」，不是一条事实。
+ */
 export declare const FACT_SCOPE_SUFFIX = "*";
+/**
+ * 由单元 id 拼出它那一族事实的范围名。
+ * @param unit 单元 id，不带后缀。
+ * @returns <unit>* —— 永远是范围名，不是某一条事实。
+ */
 export declare function unitFactScope(unit: string): string;
+/**
+ * 判一个名字是不是范围查法，不是问这条事实存不存在。
+ * @param name 事实名或范围名。
+ * @returns 单字符 * 不算范围；只有「至少一个字符加 *」才算。
+ */
 export declare function isFactScope(name: string): boolean;
+/**
+ * 取范围名对应的前缀，普通事实名原样返回。
+ * @param name 事实名或范围名。
+ * @returns 去掉末尾 * 的前缀；本来不是范围就给原值。
+ */
 export declare function scopePrefixOf(name: string): string;
+/**
+ * 事实的来路：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;
@@ -20,8 +47,23 @@ export interface FactChannel {
     applyFrame(frame: FactFrame): void;
     subscriberCount(): number;
 }
+/**
+ * 造一条事实通道：第一次订阅时才连传输层，最后一个订阅者走掉就断开。
+ * @param options 传输层，用来连宿主。
+ * @returns 通道句柄；没记录过的事实版本给 0，refresh() 不带事实名时刷新全部并逐个通知。
+ */
 export declare function createFactChannel(options: {
     readonly transport: FactTransport;
 }): FactChannel;
+/**
+ * 把传输层收到的原始数据读成一帧；坏数据当没收到。
+ * @param data 帧的原始数据，期望是 JSON 字符串。
+ * @returns 合法帧；不是字符串、JSON 坏了、或 rev 不是数字都给 null。
+ */
 export declare function parseFactFrame(data: unknown): FactFrame | null;
+/**
+ * 读口路由到事实名的映射，当前一对一。
+ * @param route 读口路由。
+ * @returns 该路由对应的事实名（就是路由本身）。
+ */
 export declare function factOfRoute(route: string): string;