@dsh-workbench/shared 0.3.4 → 0.3.6

package/src/api/__tests__/long-task.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, it } from 'vitest';
-import { longTaskDot, longTaskPollMs, longTaskRunsOf, runsRouteOf } from '../long-task.js';
+import {
+  longTaskDot,
+  longTaskPollMs,
+  longTaskRunsOf,
+  longTaskStopPress,
+  longTaskStopStage,
+  LONG_TASK_STOP_ARM_MS,
+  runsRouteOf,
+  stopRouteOf,
+} from '../long-task.js';
 
 describe('runsRouteOf', () => {
   it('★ 事实名 = 路由名（三处同一个来源，改一处不可能漏另一处）', () => {
@@ -8,6 +17,14 @@ describe('runsRouteOf', () => {
   });
 });
 
+describe('stopRouteOf（停止那条写路由）', () => {
+  it('★ 就是读路由 + `/stop`（读口与写口同一个单元名，不另造一套命名）', () => {
+    expect(stopRouteOf('cmdb')).toBe('cmdb/runs/stop');
+    expect(stopRouteOf('issues')).toBe('issues/runs/stop');
+    expect(stopRouteOf('cmdb')).toBe(`${runsRouteOf('cmdb')}/stop`);
+  });
+});
+
 describe('longTaskDot', () => {
   it('★ 两个"还在等"的状态都转圈：等编排与等你登录是同一个信号', () => {
     expect(longTaskDot('running')).toBe('ongoing');
@@ -15,6 +32,29 @@ describe('longTaskDot', () => {
     expect(longTaskDot('ok')).toBe('done');
     expect(longTaskDot('failed')).toBe('error');
   });
+
+  it('★ 用户按停的那一趟是灰点：不是成功、不是出错，落进 idle', () => {
+    expect(longTaskDot('stopped')).toBe('idle');
+  });
+});
+
+describe('longTaskStopStage / longTaskStopPress（两按：第一次上膛，第二次才真发）', () => {
+  it('★ 三档：没上膛 / 上了膛 / 请求在飞；在飞压过一切', () => {
+    expect(longTaskStopStage({ armed: false, busy: false })).toBe('idle');
+    expect(longTaskStopStage({ armed: true, busy: false })).toBe('armed');
+    expect(longTaskStopStage({ armed: false, busy: true })).toBe('busy');
+    expect(longTaskStopStage({ armed: true, busy: true })).toBe('busy');
+  });
+
+  it('★ 按一下该干什么：idle → arm、armed → fire、busy → ignore（在飞时按不动）', () => {
+    expect(longTaskStopPress('idle')).toBe('arm');
+    expect(longTaskStopPress('armed')).toBe('fire');
+    expect(longTaskStopPress('busy')).toBe('ignore');
+  });
+
+  it('★ 上膛时限照 dsh：3 秒自己落膛', () => {
+    expect(LONG_TASK_STOP_ARM_MS).toBe(3000);
+  });
 });
 
 describe('longTaskRunsOf（这一读交回的"当前那些趟"）', () => {

package/src/api/blocker-table.ts

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

package/src/api/blocker.ts

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

package/src/api/context-ref.ts

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

package/src/api/dsh-client.ts

@@ -1,5 +1,8 @@
 import type { ReactNode } from 'react';
 
+/**
+ * 左栏一行的来源：dsh workspaces.list 快照里的一项，两个时间戳都是毫秒。
+ */
 export interface WorkspaceView {
   readonly workspaceId: string;
   readonly path: string;
@@ -9,12 +12,18 @@ export interface WorkspaceView {
   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;
@@ -25,10 +34,16 @@ export interface SessionSummary {
   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<
@@ -36,34 +51,58 @@ export interface SessionsSnapshot {
   >;
 }
 
+/**
+ * 一个会话的三个状态位（在跑 / 有未读完成 / 等着用户交互）；字段缺省就是这一位不知道。
+ */
 export interface SessionStatus {
   readonly running?: boolean;
   readonly completionUnread?: boolean;
   readonly pendingInteraction?: { 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;
@@ -76,6 +115,9 @@ export interface SlotRegisterOptions {
   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;
@@ -85,11 +127,17 @@ export interface DshSlots {
   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;
@@ -98,18 +146,30 @@ export interface DshLayout {
   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;
@@ -117,17 +177,26 @@ export interface DshUiWorkspace {
   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: { path: string }): Promise<DshWorkspaceWritten | undefined>;
   rename(workspaceId: string, title: string): Promise<DshWorkspaceWritten>;
 }
 
+/**
+ * 往输入框插一条引用时要给的载荷：来源、引用文本、显示文案与剪贴板文本。
+ */
 export interface DshReferenceInsert {
   readonly source: string;
   readonly ref: string;
@@ -136,12 +205,18 @@ export interface DshReferenceInsert {
   readonly clipboardText: string;
 }
 
+/**
+ * 输入框里一段 token 的区间；draftRev 用来确认还是同一版草稿，插入引用时用它定位。
+ */
 export interface DshTokenSpan {
   readonly start: number;
   readonly end: number;
   readonly draftRev: number;
 }
 
+/**
+ * 某一个会话的输入框句柄；外壳借它插引用与弹提示，state 用来核对草稿版本。
+ */
 export interface DshSessionInput {
   caretSpan?: () => { start: number; end: number };
   readonly state: { getSnapshot(): { draftRev: number } | undefined };
@@ -149,6 +224,9 @@ export interface DshSessionInput {
   notify(level: 'info' | 'error', text: string): void;
 }
 
+/**
+ * 注册 @ 触发源的口子：候选由外壳现取，选中后的动作也归外壳，dsh 只负责触发。
+ */
 export interface DshInputTriggers {
   registerSource(source: {
     readonly trigger: '@';
@@ -165,10 +243,16 @@ export interface DshInputTriggers {
   }): () => void;
 }
 
+/**
+ * dsh 的对话服务；外壳只用它按会话取输入框句柄。
+ */
 export interface DshConversationService {
   readonly input: { for(actx: unknown): DshSessionInput };
 }
 
+/**
+ * 浏览器侧的会话服务：快照加按 id 取作用域；create 是可选写口，不是每个 dsh 版本都有。
+ */
 export interface DshSessionsService {
   readonly list: { getSnapshot(): SessionsSnapshot };
   scope(sessionId: string): unknown | undefined;
@@ -180,11 +264,17 @@ export interface DshSessionsService {
   }): 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;
@@ -193,6 +283,9 @@ export interface DshSidebarRight {
   openTab(kind: string, options?: unknown): void;
 }
 
+/**
+ * remote.sessions 写口：在宿主侧建会话并回会话 id。
+ */
 export interface DshSessionsRemote {
   create(request: {
     readonly workspaceId?: string;
@@ -201,10 +294,16 @@ export interface DshSessionsRemote {
   }): Promise<{ 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/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;
 }