@dsh-workbench/shared 0.3.4 → 0.3.5

package/src/i18n/merge.ts

@@ -1,5 +1,6 @@
 import type { Dictionaries } from './index.js';
 
+/** 一个套件交上来的词表：`unit` 是套件 id（也是键前缀），`messages` 缺省表示这次不参与合并。 */
 export interface MessagesContribution {
   readonly unit: string;
   readonly messages?: Dictionaries | undefined;
@@ -23,6 +24,7 @@ function assertSelfConsistent(unit: string, messages: Dictionaries): void {
   }
 }
 
+/** 把各套件的词表合到外壳底座上：键必须以 `<unit>.` 开头、不许撞已有键，违规当场抛错。 */
 export function mergeMessages(
   base: Dictionaries,
   contributions: readonly MessagesContribution[],
@@ -53,11 +55,13 @@ export function mergeMessages(
   return { zh, en };
 }
 
+/** 一条没合进去的贡献：哪个套件 + 为什么被拒（人话原因）。 */
 export interface MessagesProblem {
   readonly unit: string;
   readonly reason: string;
 }
 
+/** 合并结果：合出来的词表 + 被跳过的贡献；`problems` 为空即全部合上了。 */
 export interface MessagesMerge {
   readonly dictionaries: Dictionaries;
   readonly problems: readonly MessagesProblem[];
@@ -68,6 +72,7 @@ function reasonOf(error: unknown): string {
   return typeof error === 'string' ? error : String(error);
 }
 
+/** 逐份试合、坏的跳过：一份贡献不合规只记进 `problems`，不影响其余套件与已有词表。 */
 export function mergeMessagesSkipping(
   base: Dictionaries,
   contributions: readonly MessagesContribution[],

package/src/i18n/zh.ts

@@ -1,3 +1,4 @@
+/** 外壳自带的中文词表（命名空间 `workbench`）：`en` 与它逐键对齐，模块那份在它之上合并。 */
 export const zh = {
   'brand.name': '工作台',
 
@@ -418,20 +419,19 @@ export const zh = {
   'configSync.emptyProviders': '工作台还没有任何模型供应商 —— 去「配置同步」从某个 profile 把 llm- 那几行搬过来，或自己去「模型」里配。',
   'configSync.failed': '同步没成功，再试一次。',
 
-  'debug.status': '工作台 DIY 开发调试中',
-  'debug.status.trouble': '工作台 DIY 开发调试异常',
-  'debug.stalled': '工作台 DIY 调试暂停',
+  'debug.workspace': '这个工作区',
+  'debug.status': '「{title}」调试中',
+  'debug.status.trouble': '调试要你看一眼（{title}）',
+  'debug.stalled': '调试已暂停（{title}）',
   'debug.act.pause': '暂停调试',
   'debug.act.resume': '继续调试',
   'debug.act.stop': '结束调试',
   'debug.act.stop.ask': '确认结束',
-  'debug.card.here.title': '当前工作台 DIY 开发调试中',
+  'debug.card.here.title': '正在调试「{title}」',
   'debug.card.here.note': '请勿切换工作区和操作面板',
-  'debug.card.away.title': '工作台 DIY 开发调试中',
-  'debug.card.away.note': '请切换到工作台 DIY 工作区',
+  'debug.card.away.note': '请切回「{title}」那一屏',
   'debug.card.paused.note': '已暂停',
-  'debug.card.hidden.note': '请切换到工作台面板',
-  'debug.back': '回到工坊那一屏',
+  'debug.card.hidden.note': '请切回工作台面板',
   'record.waiting': '取证交接 · 等你出手',
   'record.waiting.note': '请在那一页按「开始录制」，做完按「结束录制」（录完不替你切回来）',
   'record.recording': '录制中',
@@ -448,4 +448,5 @@ export const zh = {
   'approval.record.noSwitch': '录完不会替你切回来（左栏底部会亮一条状态）',
 } as const;
 
+/** 中文词表的键类型：`en` 与模块词表都得覆盖同一批键。 */
 export type WorkbenchMessages = typeof zh;

package/src/index.ts

@@ -20,8 +20,11 @@ export * from './components/CardBoundary.js';
 export * from './components/CardHead.js';
 export * from './components/ChoiceGroup.js';
 export * from './components/Field.js';
+export * from './components/Form.js';
 export * from './components/FormActions.js';
+export * from './components/FormNodes.js';
 export * from './components/FormRows.js';
+export * from './components/FormTypes.js';
 export * from './components/Link.js';
 export * from './components/LongTaskRow.js';
 export * from './components/Note.js';
@@ -29,6 +32,7 @@ export * from './components/ResourceStates.js';
 export * from './components/Rows.js';
 export * from './components/SaveBar.js';
 export * from './components/SelectField.js';
+export * from './components/SelectFieldNodes.js';
 export * from './components/SettingsSection.js';
 export * from './components/Spinner.js';
 export * from './components/Stack.js';
@@ -43,11 +47,11 @@ export * from './i18n/index.js';
 export * from './i18n/merge.js';
 export * from './i18n/zh.js';
 export * from './lib/blocker-action.js';
-export * from './lib/busy.js';
-export * from './lib/form-problem.js';
 export * from './lib/board-fact.js';
+export * from './lib/busy.js';
 export * from './lib/diy-debug.js';
 export * from './lib/diy-record.js';
+export * from './lib/form-problem.js';
 export * from './lib/panel-state.js';
 export * from './lib/react.js';
 export * from './lib/text.js';

package/src/lib/blocker-action.ts

@@ -1,21 +1,43 @@
+/**
+ * 阻断态取词：i18n 的 `(key) => 文案` 那一半；那几颗钮的「重试中…」等临时说法都从它来。
+ */
 export type BlockerLabelTranslate = (key: string) => string;
 
+/**
+ * 阻断态上一颗钮的形状：`kind` 定行为（`retry` / `copy` 等），`label` 是它平时的文案。
+ */
 export interface BlockerActionShape {
   readonly kind: string;
   readonly label: string;
   readonly text?: string | undefined;
 }
 
+/**
+ * 这颗钮此刻的运行态：是否正在重试、哪一支正在跑（按 label 认）、刚复制过哪段文本。
+ */
 export interface BlockerLabelState {
   readonly retrying: boolean;
   readonly running: string | null;
   readonly copied: string | null;
 }
 
+/**
+ * 这颗钮此刻该不该按成等待态：这一轮忙还没收，或有一支正在跑。
+ * @param busy - 这一轮忙是不是还在。
+ * @param running - 正在跑的那一支的 label；没有就给 `null`。
+ * @returns 该等待给 `true`，否则 `false`。
+ */
 export function blockerPending(busy: boolean, running: string | null): boolean {
   return busy || running !== null;
 }
 
+/**
+ * 这颗钮此刻该显示什么字：正在重试说「重试中…」，正在跑的那一支说「修复中…」，刚复制过的说「已复制」，其余原样。
+ * @param action - 这颗钮的形状（行为 + 平时文案）。
+ * @param state - 此刻的运行态。
+ * @param t - i18n 取词函数。
+ * @returns 要显示的文案；三种临时态都不成立时就是 `action.label`。
+ */
 export function blockerActionLabel(
   action: BlockerActionShape,
   state: BlockerLabelState,

package/src/lib/board-fact.ts

@@ -1,9 +1,15 @@
+/**
+ * 椅面（右栏那块画板）此刻归属哪一类：`workshop` 本工坊、`other` 别家、`hidden` 没画出来、`unknown` 探不到。
+ */
 export type BoardFactState =
   | 'workshop'
   | 'other'
   | 'hidden'
   | 'unknown';
 
+/**
+ * 左栏底部「调试」那条状态要说的档位：`ok` 在板上、`off-workspace` 切去了别的项目、`panel-closed` 面板没开、`other-board` 画的是别家的板、`unknown` 探不到。
+ */
 export type BoardSituation =
   | 'ok'
   | 'off-workspace'
@@ -11,6 +17,9 @@ export type BoardSituation =
   | 'other-board'
   | 'unknown';
 
+/**
+ * 一次页面探针的读数：外壳在不在、探的是哪个工作区、右栏开没开、板上挂的路径、椅面画出来没有。
+ */
 export interface BoardProbe {
   readonly workbench: boolean;
   readonly where: string;
@@ -20,12 +29,24 @@ export interface BoardProbe {
   readonly drawn: boolean;
 }
 
+/**
+ * 判一个路径落不落在这个工作区里（按路径前缀比，不是字符串包含）。
+ * @param root - 工作区根路径。
+ * @param target - 要判的路径。
+ * @returns 同一个路径或在其下给 `true`；`root` 末尾带不带斜杠都认（`/a` 不匹配 `/ab`）。
+ */
 export function insideWorkshop(root: string, target: string): boolean {
   if (target === root) return true;
   const base = root.endsWith('/') ? root : `${root}/`;
   return target.startsWith(base);
 }
 
+/**
+ * 把一次探针读数归成椅面归属。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 表示还不知道当前是哪个工作区。
+ * @returns 外壳不在、或板路径与工作区缺一 → `unknown`；右栏没开或没画出来 → `hidden`；板在本工作区 → `workshop`，否则 `other`。
+ */
 export function boardFactOf(probe: BoardProbe, workshop: string | null): BoardFactState {
   if (!probe.workbench) return 'unknown';
   if (!probe.bar || !probe.open || !probe.drawn) return 'hidden';
@@ -33,6 +54,12 @@ export function boardFactOf(probe: BoardProbe, workshop: string | null): BoardFa
   return insideWorkshop(workshop, probe.board) ? 'workshop' : 'other';
 }
 
+/**
+ * 把探针读数归成左栏那句人话的档位。
+ * @param probe - 探针读数。
+ * @param workshop - 当前工作区根路径；`null` 一律 `unknown`。
+ * @returns 椅面画着 → 本板 `ok` / 别板 `other-board`；没画着 → 页面已走 `off-workspace`，否则 `panel-closed`。
+ */
 export function boardSituation(probe: BoardProbe, workshop: string | null): BoardSituation {
   if (!probe.workbench || workshop === null) return 'unknown';
   const drawn = probe.bar && probe.open && probe.drawn;

package/src/lib/busy.ts

@@ -1,8 +1,18 @@
+/**
+ * 忙态按下限收尾的判据结果：还该不该显示（`visible`），以及还要按住多少毫秒（`releaseInMs`，0 = 立刻可收）。
+ */
 export interface BusyHold {
   readonly visible: boolean;
   readonly releaseInMs: number;
 }
 
+/**
+ * 按「至少显示 floorMs」算这一轮忙此刻该不该收：没到下限就继续显示，并给出剩余时长供调用方起定时器。
+ * @param since - 这一轮忙开始的时间戳；`null`（没开过这一轮）一律不显示。
+ * @param now - 当前时间戳。
+ * @param floorMs - 至少显示的时长（毫秒）。
+ * @returns 还该不该显示 + 剩余毫秒；到点或已过下限给不显示，时钟倒退按「刚开头」算（剩余 = 下限，不给负数）。
+ */
 export function holdBusy(since: number | null, now: number, floorMs: number): BusyHold {
   if (since === null) return { visible: false, releaseInMs: 0 };
   const elapsed = Math.max(0, now - since);

package/src/lib/diy-debug.test.ts

@@ -3,7 +3,8 @@ import { DEBUG_STALE_MS, createDebugStore, parseDebugIntent, type DebugPact } fr
 
 const pact = (sessionId: string, now = 1000, unit = 'demo'): DebugPact => ({
   sessionId,
-  workspace: '/w/diy',
+  workspacePath: '/w/diy',
+  title: '演示工作区',
   board: '/w/diy',
   unit,
   name: unit,

package/src/lib/diy-debug.ts

@@ -1,17 +1,35 @@
+/**
+ * 调试约定的两个相位：`debugging` 正占着用户的屏，`paused` 已暂停但仍持着约定。
+ */
 export type DebugPhase = 'debugging' | 'paused';
 
+/**
+ * 调试约定收得下的三个人话动作：暂停 / 继续 / 结束。
+ */
 export type DebugIntent = 'pause' | 'resume' | 'stop';
 
+/**
+ * 把工具入参收成人话动作。
+ * @param value - 任意入参值。
+ * @returns `'pause'` / `'resume'` / `'stop'` 原样；别的值（含 `undefined`、多余空白、大小写不同）给 `null`，由调用方拒。
+ */
 export function parseDebugIntent(value: unknown): DebugIntent | null {
   return value === 'pause' || value === 'resume' || value === 'stop' ? value : null;
 }
 
+/**
+ * 调试约定的有效期（4 小时，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
 export const DEBUG_STALE_MS = 4 * 60 * 60 * 1000;
 
+/**
+ * 一份活着的调试约定：相位 + 谁的会话 + 哪个工作区 / 板 / 单元 + 起于何时（`at` 是最后一次动作）。
+ */
 export interface DebugState {
   readonly phase: DebugPhase;
   readonly sessionId: string;
-  readonly workspace: string;
+  readonly workspacePath: string;
+  readonly title: string;
   readonly board: string;
   readonly unit: string;
   readonly name: string;
@@ -19,15 +37,22 @@ export interface DebugState {
   readonly at: number;
 }
 
+/**
+ * 建立约定要交的那几件：会话、工作区、板、单元、名字，以及此刻的时间戳。
+ */
 export interface DebugPact {
   readonly sessionId: string;
-  readonly workspace: string;
+  readonly workspacePath: string;
+  readonly title: string;
   readonly board: string;
   readonly unit: string;
   readonly name: string;
   readonly now: number;
 }
 
+/**
+ * 约定被拒的原因码：自己已持有 / 别人持着 / 不是持有者 / 没有约定 / 已暂停 / 已在调试。
+ */
 export type DebugRefusal =
   | 'already-held'
   | 'held-by-other'
@@ -36,10 +61,16 @@ export type DebugRefusal =
   | 'already-paused'
   | 'already-debugging';
 
+/**
+ * 一次约定动作的结果：成功带新状态，失败带拒绝码。
+ */
 export type DebugMove =
   | { readonly ok: true; readonly state: DebugState }
   | { readonly ok: false; readonly code: DebugRefusal };
 
+/**
+ * 调试约定的存取口（外壳持有一份）：`live` 取当前有效的约定，`begin` / `pause` / `resume` / `stop` 推相位。
+ */
 export interface DebugStore {
   live(now: number): DebugState | null;
   begin(pact: DebugPact): DebugMove;
@@ -60,6 +91,10 @@ function ownerOf(state: DebugState | null, sessionId: string, now: number): Debu
   return held.sessionId === sessionId ? held : 'not-owner';
 }
 
+/**
+ * 造一份新的调试约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `DebugMove` 里，不抛异常。
+ */
 export function createDebugStore(): DebugStore {
   let held: DebugState | null = null;
 
@@ -76,7 +111,8 @@ export function createDebugStore(): DebugStore {
       const state: DebugState = {
         phase: 'debugging',
         sessionId: pact.sessionId,
-        workspace: pact.workspace,
+        workspacePath: pact.workspacePath,
+        title: pact.title,
         board: pact.board,
         unit: pact.unit,
         name: pact.name,
@@ -114,6 +150,11 @@ export function createDebugStore(): DebugStore {
   };
 }
 
+/**
+ * 「谁还占着」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在调试 y）」的中文串。
+ */
 export function debugOwnerText(state: DebugState): string {
   return `会话 ${state.sessionId}（自 ${new Date(state.startedAt).toISOString().slice(11, 19)}Z 起在调试 ${state.unit}）`;
 }

package/src/lib/diy-record.ts

@@ -1,12 +1,24 @@
+/**
+ * 录制交接的三个相位：`armed` 等用户在外站页面上动手，`recording` 正在录，`finished` 录完待取。
+ */
 export type RecordPhase = 'armed' | 'recording' | 'finished';
 
+/**
+ * 录制约定的有效期（15 分钟，毫秒）：超过它没动静的约定算过期、当场让人。
+ */
 export const RECORD_STALE_MS = 15 * 60 * 1000;
 
+/**
+ * 这次录制要找的那一次写：HTTP 方法 + URL 里必须含的一段（不填就是只认方法）。
+ */
 export interface RecordExpect {
   readonly method: string;
   readonly urlContains: string;
 }
 
+/**
+ * 一份活着的录制约定：相位 + 谁的会话 + 哪个工作区 / 单元 + 页面 URL 与标题 + 要找的那一次写 + 落盘文件 + 三个时间戳。
+ */
 export interface RecordState {
   readonly phase: RecordPhase;
   readonly sessionId: string;
@@ -24,6 +36,9 @@ export interface RecordState {
   readonly at: number;
 }
 
+/**
+ * 开一次录制要交的那几件：会话、工作区、单元、名字、页面 URL 与标题、动作名、期望、落盘文件，以及此刻时间。
+ */
 export interface RecordPact {
   readonly sessionId: string;
   readonly workspace: string;
@@ -37,6 +52,9 @@ export interface RecordPact {
   readonly now: number;
 }
 
+/**
+ * 录制被拒的原因码：自己已持有 / 别人持着 / 不是持有者 / 没有约定 / 已在录 / 还没 arm / 不在录 / 还没录完。
+ */
 export type RecordRefusal =
   | 'already-held'
   | 'held-by-other'
@@ -47,16 +65,30 @@ export type RecordRefusal =
   | 'not-recording'
   | 'not-finished';
 
+/**
+ * 一次录制动作的结果：成功带新状态，失败带拒绝码。
+ */
 export type RecordMove =
   | { readonly ok: true; readonly state: RecordState }
   | { readonly ok: false; readonly code: RecordRefusal };
 
+/**
+ * 录制约定收得下的三个人话动作：看看进度 / 停手 / 结束并取回。
+ */
 export type RecordIntent = 'peek' | 'halt' | 'stop';
 
+/**
+ * 把工具入参收成人话动作。
+ * @param raw - 任意入参值。
+ * @returns `'peek'` / `'halt'` / `'stop'` 原样；别的值（含 `undefined`、多余空白）给 `null`，由调用方拒。
+ */
 export function parseRecordIntent(raw: unknown): RecordIntent | null {
   return raw === 'peek' || raw === 'halt' || raw === 'stop' ? raw : null;
 }
 
+/**
+ * 录制约定的存取口（外壳持有一份）：相位随 `begin → started → finished` 推进，`release` 是收尾时放掉浏览器那一跳。
+ */
 export interface RecordStore {
   readonly release?: ((state: RecordState) => Promise<{ readonly tab: boolean; readonly capture: boolean }>) | undefined;
   live(now: number): RecordState | null;
@@ -77,6 +109,10 @@ function ownerOf(state: RecordState | null, sessionId: string, now: number): Rec
   return held.sessionId === sessionId ? held : 'not-owner';
 }
 
+/**
+ * 造一份新的录制约定存储（进程内存，同一时刻只可能有一份有效约定）。
+ * @returns 存取口；动作成不成都在返回的 `RecordMove` 里，不抛异常。
+ */
 export function createRecordStore(): RecordStore {
   let held: RecordState | null = null;
 
@@ -138,6 +174,11 @@ export function createRecordStore(): RecordStore {
   };
 }
 
+/**
+ * 「谁还占着、在录哪个动作」的一句话，用于别人来抢时说清现况。
+ * @param state - 当前有效的那份约定。
+ * @returns 形如「会话 x（自 HH:mm:ssZ 起在录 y 的「动作」）」的中文串。
+ */
 export function recordOwnerText(state: RecordState): string {
   const at = new Date(state.startedAt).toISOString().slice(11, 19);
   return `会话 ${state.sessionId}（自 ${at}Z 起在录 ${state.unit} 的「${state.action}」）`;

package/src/lib/form-problem.ts

@@ -9,10 +9,20 @@ const FOCUSABLE_SELECTOR = [
   '[tabindex]:not([tabindex="-1"])',
 ].join(', ');
 
+/**
+ * 找 `root` 里第一个带 `[data-wb-problem]` 标记的元素 —— 表单校验失败时，调用方拿它定位「哪一格错了」。
+ * @param root - 要搜的范围（表单容器，或 document）。
+ * @returns 第一个出问题的元素；一个标记都没有就给 `null`。
+ */
 export function firstProblemOf(root: ParentNode): Element | null {
   return root.querySelector(PROBLEM_SELECTOR);
 }
 
+/**
+ * 把第一个出问题的元素滚进视野、并把焦点交给它里面第一个可聚焦控件（输入框 / 按钮 / 链接等）。
+ * @param root - 要搜的范围。
+ * @returns 找到并滚过给 `true`；没有问题给 `false`（不滚、不抢焦点）；元素不可滚或没有可聚焦控件也不报错，只是少做一步。
+ */
 export function revealFirstProblem(root: ParentNode): boolean {
   const problem = firstProblemOf(root);
   if (problem === null) return false;

package/src/lib/panel-state.ts

@@ -1,10 +1,19 @@
+/**
+ * 一张面板卡片取数走到哪一步：`idle` 还没取、`loading` 取着、`ready` 拿到了、`error` 失败了。
+ */
 export type PanelCardPhase = 'idle' | 'loading' | 'ready' | 'error';
 
+/**
+ * 一次取数失败：机器码 + 给人看的一句话。
+ */
 export interface PanelCardError {
   readonly code: string;
   readonly message: string;
 }
 
+/**
+ * 一张卡片最近一次取数的读数：哪个单元、哪条路由、什么相位、什么时候、失败原因。
+ */
 export interface PanelCardRead {
   readonly unit: string;
   readonly route: string;
@@ -13,6 +22,9 @@ export interface PanelCardRead {
   readonly error?: PanelCardError;
 }
 
+/**
+ * 一张卡片崩了的读数：单元、原因、时间，以及同一原因连着崩了几次（窗口见 `PANEL_STATE_CRASH_WINDOW_MS`）。
+ */
 export interface PanelCardCrash {
   readonly unit: string;
   readonly reason: string;
@@ -20,6 +32,9 @@ export interface PanelCardCrash {
   readonly count: number;
 }
 
+/**
+ * 一个单元此刻的读数：它的卡片、最近一次读成的时间（`okAt`，没成过给 `null`），以及崩了的那一条。
+ */
 export interface PanelUnitReport {
   readonly unit: string;
   readonly at: number;
@@ -28,17 +43,26 @@ export interface PanelUnitReport {
   readonly crash?: PanelCardCrash;
 }
 
+/**
+ * 一个工作区此刻的全量读数（面板按工作区存）：所有单元的读数 + 整块最近动过的时间。
+ */
 export interface PanelWorkspaceReport {
   readonly workspace: string | null;
   readonly at: number;
   readonly units: readonly PanelUnitReport[];
 }
 
+/**
+ * 客户端往上报的一批卡片读数（`POST` 请求体的形状）。
+ */
 export interface PanelCardsReport {
   readonly workspace: string;
   readonly cards: readonly PanelCardRead[];
 }
 
+/**
+ * 客户端往上报的一次卡片崩溃（`POST` 请求体的形状）。
+ */
 export interface PanelCrashReport {
   readonly workspace: string;
   readonly unit: string;
@@ -46,16 +70,34 @@ export interface PanelCrashReport {
   readonly at: number;
 }
 
+/**
+ * 面板运行态的留存口（宿主持有一份）：收卡片读数与崩溃，按工作区取快照。
+ */
 export interface PanelStateStore {
   cards(report: PanelCardsReport): void;
   crash(report: PanelCrashReport): void;
   snapshot(workspace: string | null): PanelWorkspaceReport;
 }
 
+/**
+ * 留存的工作区上限（LRU，满 64 个丢最旧的）。
+ */
 export const PANEL_STATE_MAX_UNITS = 64;
+/**
+ * 每个单元留存的卡片上限（按路由 LRU，满 12 张丢最旧的）。
+ */
 export const PANEL_STATE_MAX_CARDS = 12;
+/**
+ * 一次上报最多读入的卡片条数（32 条之后的丢掉）。
+ */
 export const PANEL_STATE_MAX_REPORTS = 32;
+/**
+ * 同一原因的连续崩溃算进同一次计数的窗口（10 分钟，毫秒）。
+ */
 export const PANEL_STATE_CRASH_WINDOW_MS = 600000;
+/**
+ * 上报文本字段的截断长度（2000 字符；workspace / reason / message 共用）。
+ */
 export const PANEL_STATE_MAX_TEXT = 2000;
 
 const PHASES: readonly PanelCardPhase[] = ['idle', 'loading', 'ready', 'error'];
@@ -71,6 +113,9 @@ interface WorkspaceEntry {
   units: Map<string, UnitEntry>;
 }
 
+/**
+ * 上报解析的结果：`ok: true` 带收好的值，`ok: false` 带一句中文原因（直接回给上报方）。
+ */
 export type PanelParse<T> =
   | { readonly ok: true; readonly value: T }
   | { readonly ok: false; readonly message: string };
@@ -100,6 +145,12 @@ function errorOf(raw: unknown): PanelCardError | undefined {
   return { code: code === '' ? 'unknown' : code, message };
 }
 
+/**
+ * 收一批卡片读数上报。
+ * @param payload - `POST` 的请求体。
+ * @returns 至少收到一条能认的卡片才 `ok: true`；请求体不是对象、`workspace` 为空、`cards` 不是数组，
+ *   或一条都认不出（`unit` / `route` / `phase` / `at` 缺一）时 `ok: false` + 中文原因；认不出的单条静默跳过。
+ */
 export function parseCardsReport(payload: unknown): PanelParse<PanelCardsReport> {
   const record = asRecord(payload);
   if (record === undefined) return { ok: false, message: '请求体要是一个对象' };
@@ -123,6 +174,11 @@ export function parseCardsReport(payload: unknown): PanelParse<PanelCardsReport>
   return { ok: true, value: { workspace, cards } };
 }
 
+/**
+ * 收一次卡片崩溃上报。
+ * @param payload - `POST` 的请求体。
+ * @returns `workspace` / `unit` / `reason` 都不能空，缺一给 `ok: false` + 中文原因；`at` 缺省或不合法时取当前时间。
+ */
 export function parseCrashReport(payload: unknown): PanelParse<PanelCrashReport> {
   const record = asRecord(payload);
   if (record === undefined) return { ok: false, message: '请求体要是一个对象' };
@@ -135,6 +191,10 @@ export function parseCrashReport(payload: unknown): PanelParse<PanelCrashReport>
   return { ok: true, value: { workspace, unit, reason, at: atOf(record['at']) ?? Date.now() } };
 }
 
+/**
+ * 造一份面板运行态的留存（进程内存、按工作区分桶，带上面那几条上限的 LRU）。
+ * @returns 留存口：`cards` / `crash` 收上报，`snapshot(workspace)` 取全量；没存过的工作区（含 `null`）给一份空的。
+ */
 export function createPanelStateStore(): PanelStateStore {
   const workspaces = new Map<string, WorkspaceEntry>();