@dsh-workbench/core 0.3.4 → 0.3.5

package/dist/types/modules/panels/model/diy-context.d.ts

@@ -1,5 +1,4 @@
 import type { DshHostContext, DshToolRunContext } from '@dsh-workbench/shared';
-import { type BrowserFindResult, type BrowserReadResult } from '@dsh-workbench/shared/host';
 import type { BundleChange } from '../../../shared/api/bundle-install';
 import type { PanelsService } from './service';
 export declare const OUTPUT_SCHEMA: {
@@ -85,18 +84,18 @@ export declare function asNumber(value: unknown): number | undefined;
 export declare function asText(value: unknown): string;
 export declare function plainJson<T>(value: T): T;
 export declare function verdictOf(change: BundleChange): string;
-export declare function renderProbe(out: BrowserReadResult): string;
-export declare function renderFind(out: BrowserFindResult): string;
 export declare function showOrReason(panels: PanelsService, unit: string, workspace: string | null): {
     readonly ok: boolean;
     readonly reason?: string;
 };
-export declare function workshopOf(ctx: DshHostContext, exec: DshToolRunContext): {
+export declare function workshopOf(ctx: DshHostContext, exec: DshToolRunContext): Promise<{
     readonly packagesDir: string;
     readonly workspace: string | null;
-};
+    readonly title: string;
+}>;
 export declare function modulesOf(ctx: DshHostContext, packagesDir: string): {
     installed: string[];
     modules: readonly import("@/shared/api/host/diy-workshop").WorkshopModule[];
 };
+export declare function moduleDirsOf(packagesDir: string): readonly string[];
 export declare function panelEntriesOf(panels: PanelsService, workspace: string | null): import("./config").PanelEntry[];

package/dist/types/modules/panels/model/diy-observers.d.ts

@@ -7,5 +7,5 @@ export interface ObserverCleanup {
 export interface CleanupLog {
     warn?(message: string): void;
 }
-export declare function stopObservers(ctx: DshHostContext, session?: string): Promise<ObserverCleanup>;
-export declare function withObserverCleanup(store: DebugStore, cleanup: () => Promise<ObserverCleanup>, logger?: CleanupLog | undefined): DebugStore;
+export declare function stopObservers(ctx: DshHostContext, workspace: string | null | undefined, session?: string): Promise<ObserverCleanup>;
+export declare function withObserverCleanup(store: DebugStore, cleanup: (workspace: string | null) => Promise<ObserverCleanup>, logger?: CleanupLog | undefined): DebugStore;

package/dist/types/modules/panels/model/diy-page.d.ts

@@ -26,5 +26,5 @@ export declare function debugForeignPactText(held: DebugState): string;
 export declare function debugOffBoardText(held: DebugState, situation?: BoardSituation): string;
 export declare function boardProbeOf(page: WorkbenchPage): BoardProbe;
 export declare function boardStateOf(page: WorkbenchPage, workshop: string | null): BoardState;
-export declare function boardGateText(situation: BoardSituation, unit: string, page: WorkbenchPage): string;
+export declare function boardGateText(situation: BoardSituation, unit: string, page: WorkbenchPage, title?: string): string;
 export declare function pageAt(ctx: DshHostContext, exec: DshToolRunContext, raw: unknown, options?: PageOptions): Promise<PageHandle>;

package/dist/types/modules/panels/unit.d.ts

@@ -20,7 +20,6 @@ export declare const DIY_PANEL_TOOL = "workbench_diy_panel";
 export declare const DIY_COMPONENTS_TOOL = "workbench_diy_components";
 export declare const DIY_RECON_TOOL = "workbench_diy_recon";
 export declare const DIY_SPEC_TOOL = "workbench_diy_spec";
-export declare const DIY_PROBE_TOOL = "workbench_diy_probe";
 export declare const DIY_INSTALL_TOOL = "workbench_diy_install";
 export declare const DIY_SHOW_TOOL = "workbench_diy_show";
 export declare const DIY_STATE_TOOL = "workbench_diy_state";
@@ -48,11 +47,11 @@ export declare const DIY_DEBUG_START_TOOL = "workbench_diy_debug_start";
 export declare const DIY_DEBUG_PAUSE_TOOL = "workbench_diy_debug_pause";
 export declare const DIY_DEBUG_RESUME_TOOL = "workbench_diy_debug_resume";
 export declare const DIY_DEBUG_STOP_TOOL = "workbench_diy_debug_stop";
-export declare const ALL_TOOLS: readonly ["workbench_panels_list", "workbench_panels_show", "workbench_panels_hide", "workbench_panels_move", "workbench_panels_reset", "workbench_panels_follow", "workbench_modules_list", "workbench_modules_install", "workbench_modules_update", "workbench_modules_uninstall", "workbench_modules_install_bundle", "workbench_modules_update_dependency", "workbench_modules_update_plugin", "workbench_modules_uninstall_plugin", "workbench_modules_update_workbench", "workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_probe", "workbench_diy_install", "workbench_diy_show", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop", "workbench_diy_record_prepare", "workbench_diy_record_read", "workbench_diy_record_detail", "workbench_diy_record_stop", "workbench_diy_debug_start", "workbench_diy_debug_pause", "workbench_diy_debug_resume", "workbench_diy_debug_stop"];
+export declare const ALL_TOOLS: readonly ["workbench_panels_list", "workbench_panels_show", "workbench_panels_hide", "workbench_panels_move", "workbench_panels_reset", "workbench_panels_follow", "workbench_modules_list", "workbench_modules_install", "workbench_modules_update", "workbench_modules_uninstall", "workbench_modules_install_bundle", "workbench_modules_update_dependency", "workbench_modules_update_plugin", "workbench_modules_uninstall_plugin", "workbench_modules_update_workbench", "workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_install", "workbench_diy_show", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop", "workbench_diy_record_prepare", "workbench_diy_record_read", "workbench_diy_record_detail", "workbench_diy_record_stop", "workbench_diy_debug_start", "workbench_diy_debug_pause", "workbench_diy_debug_resume", "workbench_diy_debug_stop"];
 export type PanelsToolName = (typeof ALL_TOOLS)[number];
-export declare const READ_TOOLS: readonly ["workbench_panels_list", "workbench_modules_list", "workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_probe", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop", "workbench_diy_record_read", "workbench_diy_record_detail", "workbench_diy_record_stop"];
+export declare const READ_TOOLS: readonly ["workbench_panels_list", "workbench_modules_list", "workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop", "workbench_diy_record_read", "workbench_diy_record_detail", "workbench_diy_record_stop"];
 export declare const WRITE_TOOLS: readonly ["workbench_panels_show", "workbench_panels_hide", "workbench_panels_move", "workbench_panels_reset", "workbench_panels_follow", "workbench_modules_install", "workbench_modules_update", "workbench_modules_uninstall", "workbench_modules_install_bundle", "workbench_modules_update_dependency", "workbench_modules_update_plugin", "workbench_modules_uninstall_plugin", "workbench_modules_update_workbench", "workbench_diy_install", "workbench_diy_show", "workbench_diy_record_prepare", "workbench_diy_debug_start", "workbench_diy_debug_pause", "workbench_diy_debug_resume", "workbench_diy_debug_stop"];
-export declare const DIY_TOOLS: readonly ["workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_probe", "workbench_diy_install", "workbench_diy_show", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop"];
+export declare const DIY_TOOLS: readonly ["workbench_diy_list", "workbench_diy_status", "workbench_diy_panel", "workbench_diy_components", "workbench_diy_recon", "workbench_diy_spec", "workbench_diy_install", "workbench_diy_show", "workbench_diy_state", "workbench_diy_html", "workbench_diy_find", "workbench_diy_click", "workbench_diy_hover", "workbench_diy_type", "workbench_diy_fill", "workbench_diy_keys", "workbench_diy_scroll", "workbench_diy_wait", "workbench_diy_eval", "workbench_diy_screenshot", "workbench_diy_network", "workbench_diy_dialog", "workbench_diy_logs_watch", "workbench_diy_logs_read", "workbench_diy_logs_stop"];
 export declare const DIY_RECORD_TOOLS: readonly ["workbench_diy_record_prepare", "workbench_diy_record_read", "workbench_diy_record_detail", "workbench_diy_record_stop"];
 export declare const DIY_DEBUG_TOOLS: readonly ["workbench_diy_debug_start", "workbench_diy_debug_pause", "workbench_diy_debug_resume", "workbench_diy_debug_stop"];
 export declare const panelsUnit: UnitManifest;

package/dist/types/shared/api/context-chips.d.ts

@@ -1,10 +1,30 @@
 import type { DshClientContext } from '@dsh-workbench/shared';
 import { type ContextRef } from '@dsh-workbench/shared';
+/**
+ * 对话 `@` 引用源报名用的名字：引用、lexicon 与编解码都挂在这个 source 名下。
+ */
 export declare const CONTEXT_SOURCE = "workbench";
+/**
+ * `addContextChip` 的结果：`inserted` 真插进输入框了、`unavailable` 这台 dsh 缺服务或当时插不进去。
+ */
 export type ChipResult = 'inserted' | 'unavailable';
+/**
+ * 装引用源要的外壳依赖：现在这个会话是哪一个 —— 拿不到 session id 就插不了。
+ */
 export interface ContextChipsDeps {
     currentSessionId(): string | undefined;
 }
+/**
+ * 外壳启动、拿到 dsh 的 client context 之后调一次：把 `@` 引用源注册进对话输入框；
+ * dsh 没给 `inputTriggers` 时不装、也不报错。
+ */
 export declare function installContextChips(ctx: DshClientContext, deps: ContextChipsDeps): void;
+/**
+ * 要往当前对话输入框插一条 `@` 引用时调用（卡片上“发到对话”那类动作）：同步返回，只反映当场这一拍 ——
+ * 没插进去会自己再试几拍，后面成功了也不会回头改这个返回值。没装过 / 没会话 / 拿不到输入框都回 `unavailable`。
+ */
 export declare function addContextChip(ref: ContextRef, label: string): ChipResult;
+/**
+ * 把编好的引用串码成带 `@` 的标记文本（输入框里显示与复制到剪贴板都是这一份）；认不出的串原样加个 `@`。
+ */
 export declare function serializeChipRef(encoded: string): string;

package/dist/types/shared/api/host/diy-components.d.ts

@@ -18,8 +18,9 @@ export declare function scopeOf(raw: string): SurfaceScope;
 export declare function wantsPrimitives(scope: SurfaceScope): boolean;
 export declare function wantsKit(scope: SurfaceScope): boolean;
 export declare function toolchainBinOf(root: string): string | null;
+export declare function toolchainBinAmong(root: string, dirs: readonly string[]): string | null;
 export declare function queryCommandOf(bin: string, only: 'kit' | 'primitives'): string;
-export declare function runSurfaceQuery(shell: DshShell, bin: string, only: 'kit' | 'primitives', root: string): Promise<SurfacePayload>;
+export declare function runSurfaceQuery(shell: DshShell, bin: string, only: 'kit' | 'primitives', root: string, fallbackBin?: string): Promise<SurfacePayload>;
 export declare function filesOf(payload: SurfacePayload | undefined): Record<string, string>;
 export declare function rootsOf(payload: SurfacePayload | undefined): Record<string, string>;
 export declare function countsOf(payload: SurfacePayload | undefined): Record<string, number>;
@@ -31,19 +32,29 @@ export declare function findFileOf(name: string, query: SurfaceQuery): {
 } | null;
 export declare function excerptOf(text: string, maxLines?: number): string;
 export declare function excerptAt(file: string, maxLines?: number): string;
+/** 指引目录：从宿主产物往上找 `skills/workbench-module-diy`（找不到回 `null`）。 */
 export declare function skillDirOf(from: string): string | null;
-export declare function symbolsIn(heading: string): readonly string[];
-export declare function docSectionOf(name: string, dir: string | null): {
-    readonly file: string;
-    readonly lines: string;
-} | null;
 export declare function byLocationOf(payload: SurfacePayload): readonly {
     readonly where: string;
     readonly names: readonly string[];
 }[];
+export interface SurfaceBucket {
+    readonly label: string;
+    readonly key: string;
+    readonly names: readonly string[];
+}
+export declare function kitBucketsOf(payload: SurfacePayload): readonly SurfaceBucket[];
+export declare function matchesBucket(where: string, bucket: string): boolean;
+export declare function bucketNamesOf(query: SurfaceQuery): readonly {
+    readonly face: 'kit' | 'primitives';
+    readonly keys: readonly string[];
+}[];
+export declare const TWO_FACE_ALL = "\u26A0\uFE0F \u4E24\u4E2A\u9762\u4E00\u8D77\u4E0D\u7ED9\u5168\u8868 \u2014\u2014 \u8981\u5168\u8868\u5C31\u6307\u540D\u4E00\u9762\uFF1Ascope=kit \u6216 scope=primitives\u3002";
+export declare function refusesEvery(scope: SurfaceScope, all: boolean, focused: boolean): boolean;
 export declare function renderSurfaceText(query: SurfaceQuery, options: {
     scope: SurfaceScope;
     all: boolean;
+    bucket?: string;
 }): string;
 export declare function listedNamesOf(query: SurfaceQuery): readonly string[];
 export type FaceState = 'not-queried' | 'ok' | 'unreadable';

package/dist/types/shared/api/host/diy-workshop.d.ts

@@ -1,4 +1,3 @@
-import type { DshHostContext } from '@dsh-workbench/shared';
 export interface WorkshopModule {
     readonly unit: string;
     readonly name: string;
@@ -6,11 +5,9 @@ export interface WorkshopModule {
     readonly dir: string;
     readonly installed: boolean;
 }
-export declare function workshopPackagesDir(ctx: DshHostContext): string | null;
 export declare function insideWorkshop(root: string, target: string): boolean;
 export declare function workshopModules(packagesDir: string, installed?: readonly string[]): readonly WorkshopModule[];
 export declare function readDesignOfModule(dir: string): unknown;
-export declare function inWorkshopSession(ctx: DshHostContext, workspace: string | null): boolean;
 export interface WorkshopSync {
     readonly state: 'ok' | 'syncing' | 'failed';
     readonly version: string;

package/dist/types/shared/api/host/preset-scope.d.ts

@@ -0,0 +1,16 @@
+import type { DshHostContext } from '@dsh-workbench/shared';
+import { type ToolScopeContext } from '@dsh-workbench/shared/host';
+import { type ToolScope } from './tool-scope';
+export interface SessionProjections {
+    stateOf(session: unknown, key: string): unknown;
+    onChanged(listener: (session: unknown, key: string, value: unknown, seq: unknown) => void): () => void;
+}
+export interface PresetScopeOptions {
+    readonly ctx: DshHostContext;
+    readonly deniedTools: (context: ToolScopeContext) => readonly string[];
+    readonly logger?: {
+        info?(message: string): void;
+        warn?(message: string): void;
+    } | undefined;
+}
+export declare function createPresetScope(options: PresetScopeOptions): ToolScope;

package/dist/types/shared/api/host/tool-scope.d.ts

@@ -1,4 +1,5 @@
 import type { DshPromptAssembly } from '@dsh-workbench/shared';
+import type { ToolScopeContext } from '@dsh-workbench/shared/host';
 export interface ScopedToolRegistry {
     restrict(filter: {
         readonly allow?: readonly string[];
@@ -11,13 +12,16 @@ export interface ToolScopeAgent {
         get?<T = unknown>(name: string): T | undefined;
     } | undefined;
     readonly session?: {
+        readonly id?: string | undefined;
         readonly header?: {
-            readonly cwd?: string;
+            readonly cwd?: string | undefined;
+            readonly agentPreset?: string | undefined;
         } | undefined;
     } | undefined;
 }
 export interface ToolScopeOptions {
-    deniedTools(workspace: string | null): readonly string[];
+    deniedTools(context: ToolScopeContext): readonly string[];
+    presetOf?: ((handle: ToolScopeAgent) => string | null) | undefined;
     logger?: {
         info?(message: string): void;
         warn?(message: string): void;

package/dist/types/shared/api/host/workshop-root.d.ts

@@ -0,0 +1,7 @@
+import type { DshHostContext } from '@dsh-workbench/shared';
+export interface WorkshopRoot {
+    readonly root: string;
+    readonly packagesDir: string;
+    readonly title: string;
+}
+export declare function workshopRootOf(ctx: DshHostContext, workspace: string | null): Promise<WorkshopRoot | null>;

package/dist/types/shared/components/BlockerState.d.ts

@@ -1,5 +1,8 @@
 import type { ModuleBlocker } from '@dsh-workbench/shared';
 import type { Translate } from '@dsh-workbench/shared';
+/**
+ * `<BlockerState>` 的 prop：一份 blocker 加几个回调。
+ */
 export interface BlockerStateProps {
     readonly blocker: ModuleBlocker;
     readonly t: Translate;
@@ -8,4 +11,13 @@ export interface BlockerStateProps {
     readonly flush?: boolean;
     readonly onOpenMarket?: () => void;
 }
+/**
+ * 卡片被挡住（或要给一句 notice）时渲染的那一块：按 `blocker.severity` 出块状或一行提示，动作接重试 / 跑修复 / 复制。
+ * @param props.blocker - 要显示的那份 blocker：`title` / `hint` / `detail` / `actions` / `severity`。
+ * @param props.t - 翻译函数，这一块出现的每句话都从它来。
+ * @param props.onRetry - `retry` 动作与修复成功后的重试回调。
+ * @param props.onOpenMarket - `open-market` 动作；没给就退回 `onRetry`。
+ * @param props.busy - 外层是不是在忙（默认 `false`）；为真时动作一并禁用。
+ * @param props.flush - 是否贴着容器边（默认 `false`）：去掉图标、收窄留白，给卡片内嵌用。
+ */
 export declare function BlockerState({ blocker, t, onRetry, busy, flush, onOpenMarket, }: BlockerStateProps): JSX.Element;

package/dist/types/shared/components/PanelFoot.d.ts

@@ -1,7 +1,16 @@
 import type { ReactNode } from '@dsh-workbench/shared';
+/**
+ * `<PanelFoot>` 的 prop：左边一句脚注，右边一格内容。
+ */
 export interface PanelFootProps {
     readonly text?: string;
     readonly size?: 'sm' | 'md';
     readonly children?: ReactNode;
 }
+/**
+ * 面板底部那行脚注：左侧一句 `text`，右侧放 `children`，两样都不给就是一个空的页脚壳。
+ * @param props.text - 左侧那句说明文字；不传时左侧什么都不渲染。
+ * @param props.size - 文字档（默认 `'sm'`，11px 三级色；`'md'` 是 14px 二级色，给更宽的面板用）。
+ * @param props.children - 右侧那一格内容（一般是按钮或状态），可省略。
+ */
 export declare function PanelFoot({ text, size, children }: PanelFootProps): JSX.Element;

package/dist/types/shared/components/Tip.d.ts

@@ -1,4 +1,12 @@
 import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives';
 type TooltipProps = Parameters<typeof Tooltip>[0];
+/**
+ * dsh `Tooltip` 的外壳默认值版：说明统一按右栏习惯（`bottom` / `end` / `gap 6` / 挂 body）来，其余 prop 原样转给 `Tooltip`。
+ * @param props.side - 气泡出现在锚点哪一侧（默认 `'bottom'`）。
+ * @param props.align - 底 / 顶气泡贴锚点哪条边（默认 `'end'`）。
+ * @param props.gap - 锚点到气泡的间距（默认 `6`）。
+ * @param props.portal - 是否挂到 `document.body`，以逃出裁剪容器与层叠上下文（默认 `true`）。
+ * @param props.children - 单个锚点元素；`label` / `shortcutKeys` / `openOnClick` 等其余 prop 与 dsh 同形。
+ */
 export declare function Tip({ side, align, gap, portal, ...rest }: TooltipProps): JSX.Element;
 export {};

package/dist/types/shared/hooks/bundle-queries.d.ts

@@ -1,7 +1,19 @@
 import type { ApiResponse } from '@dsh-workbench/shared';
 import { type BundleInspectionPayload, type BundleRegistriesPayload, type ModuleVersionsPayload } from '../api/bundle-install';
 import { type InstalledPluginsPayload } from '../api/installed-plugins';
+/**
+ * 读模块源注册表：装模块时能从哪些源取、当前解析到哪一个。
+ */
 export declare function readBundleRegistries(): Promise<ApiResponse<BundleRegistriesPayload>>;
+/**
+ * 装之前先看清一个 spec 是什么（收了 / 拒了 / 是个插件）；`registry` 省略或空就按默认源解析。
+ */
 export declare function readBundleInspection(spec: string, registry?: string): Promise<ApiResponse<BundleInspectionPayload>>;
+/**
+ * 问模块有没有新版；`force: true` 绕过缓存重新问源（“更新”那条路用）。
+ */
 export declare function readModuleVersions(force?: boolean): Promise<ApiResponse<ModuleVersionsPayload>>;
+/**
+ * 读已装的 opencli 插件台账；`force: true` 绕过缓存重新问一遍。
+ */
 export declare function readInstalledPlugins(force?: boolean): Promise<ApiResponse<InstalledPluginsPayload>>;

package/dist/types/shared/hooks/fact-transports.d.ts

@@ -1,2 +1,6 @@
 import { type FactTransport } from '@dsh-workbench/shared';
+/**
+ * 事实通道的传输选择：有 `EventSource` 就先用 SSE，连不上（重试一拍仍失败）自动降级成长轮询；
+ * 没有 `EventSource` 的运行时直接轮询。返回值是停掉当前这条传输的函数。
+ */
 export declare function createAdaptiveTransport(): FactTransport;

package/dist/types/shared/hooks/panel-state-report.d.ts

@@ -1,12 +1,24 @@
 import type { PanelCardError, PanelCardPhase } from '@dsh-workbench/shared';
+/**
+ * 从路由里切出单元 id（`cmdb/runs` → `cmdb`）；切不出来（没有前缀）回 `null`。
+ */
 export declare function unitOfRoute(route: string): string | null;
+/**
+ * 告诉上报这沓“现在的工作区是哪个”；换工作区会丢掉还没冲出去的待报读数。
+ */
 export declare function setPanelWorkspace(path: string | null): void;
+/**
+ * 卡片读数落地时调它（`useApiResource` 已经接好）：同一单元同一条路由只留最新一条，攒一拍再一起冲给宿主。
+ */
 export declare function reportPanelRead(input: {
     readonly unit: string;
     readonly route: string;
     readonly phase: PanelCardPhase;
     readonly error?: PanelCardError | undefined;
 }): void;
+/**
+ * 卡片崩了时调它：`unit` 与原因立刻报给宿主（不攒）；还不知道工作区时不报。
+ */
 export declare function reportPanelCrash(input: {
     readonly unit: string;
     readonly reason: string;

package/dist/types/shared/hooks/use-api-resource.d.ts

@@ -1,16 +1,38 @@
 import type { ApiError, ApiResponse, Query } from '@dsh-workbench/shared';
+/**
+ * 一次读的状态：`idle` 没开读 · `loading` 在飞 · `ready` 有值 · `error` 失败；`value` 是 `ApiResponse<T>`、
+ * `at` 是拿到这个值的时间戳。**身份没变的重取（如点刷新）进 `loading` 时上一次的 `value` 与 `at` 会留着**
+ * —— 界面照旧有得画；身份变了、本来就没值、或读到 `error` 时才没有（那时两者都是 `undefined`）。
+ */
 export interface ResourceState<T> {
     readonly phase: 'idle' | 'loading' | 'ready' | 'error';
     readonly value?: T;
     readonly error?: ApiError;
     readonly at?: number;
 }
+/**
+ * 这次读的身份：`route` 加排好序的 `query`（排序是为了同一次读只有一个 key）；给了 `override` 就用它。
+ */
 export declare function resourceIdentity(route: string, query: Query, override?: string | undefined): string;
+/**
+ * 把身份与两个版本号拼成合流用的 key：同一个 key 的并发读共享同一条请求。
+ */
 export declare function readKeyOf(identity: string, refreshToken: number, factRev: number): string;
+/**
+ * 非 hook 的取数本体（要自己管缓存时才直接调）：同一个 `key` 只发一次，并发调用共享同一个 `task`；
+ * 用它就一定要 `release`（一般放 `finally`），最后一个 `release` 才 abort，否则那条请求永不取消。
+ */
 export declare function requestResource<T>(route: string, query: Query, key: string): {
     task: Promise<ApiResponse<T>>;
     release: () => void;
 };
+/**
+ * 卡片里所有的读都走它：按身份发一次 `apiGet`，同 key 合流、订阅事实通道（这条变了自动重取）、
+ * 并把读数上报面板（`workbench_diy_panel` 看的就是它）；身份或版本号一变就换一条读，旧的当场取消。
+ * `options.enabled` 为 `false` 时不发请求、相位恒为 `idle`；`key` 覆盖身份、`fact` 换订阅哪条事实
+ * （默认 `factOfRoute(route)`）、`report: false` 不上报（夹具与后台探针用）。身份没变的重取会留住上一格
+ * 的 `value`，相位降到 `loading`。
+ */
 export declare function useApiResource<T>(route: string, query: Query, refreshToken: number, options?: {
     enabled?: boolean;
     key?: string;

package/dist/types/shared/hooks/use-blocker-actions.d.ts

@@ -1,4 +1,7 @@
 import type { BlockerAction } from '@dsh-workbench/shared';
+/**
+ * blocker 那几个动作的句柄：`run(action)` 执行、`copied` 刚复制走的文本、`running` 正在跑的修复标签、`failure` 失败信息。
+ */
 export interface BlockerActions {
     run(action: BlockerAction): void;
     copied: string | null;
@@ -8,4 +11,9 @@ export interface BlockerActions {
         detail?: string;
     } | null;
 }
+/**
+ * `<BlockerState>` 用它把 blocker 的动作接到实处：`retry` 与修复成功后的重试走 `onRetry`、`run-fix` 走 provision
+ * 写通道、`copy` 写剪贴板、`open-url` 开新窗；`open-market` 没给 `onOpenMarket` 时退回 `onRetry`。
+ * 自己画 blocker 那一块才直接用。
+ */
 export declare function useBlockerActions(onRetry: () => void, onOpenMarket?: () => void): BlockerActions;

package/dist/types/shared/hooks/use-capabilities.d.ts

@@ -1,25 +1,80 @@
 import type { CapabilityPayload } from '@dsh-workbench/shared';
+/**
+ * 纯函数：`refreshToken` 与上一次不同，这一次就该强制重探。
+ */
 export declare function shouldForce(refreshToken: number, previousToken: number): boolean;
+/**
+ * 整张能力表：单元 id → 那一格声明的能力（`design.json` 里那份）。
+ */
 export type CapabilityMap = Record<string, CapabilityPayload>;
+/**
+ * 探针状态：`checkedAt` 上一次探完的时刻（没探过是 `null`）、`checking` 是不是正在探。
+ */
 export interface CapabilityProbeState {
     readonly checkedAt: number | null;
     readonly checking: boolean;
 }
+/**
+ * 让下一次强探静默（不点亮 `checking`）—— 装机预检那类不该惊动界面的探用。
+ */
 export declare function markNextProbeSilent(): void;
+/**
+ * 探针状态的取值口，给 `useSyncExternalStore` 用；渲染里要状态请用 `useCapabilityProbe`。
+ */
 export declare function probeValue(): CapabilityProbeState;
+/**
+ * 探针状态的订阅口，返回退订函数；渲染里要状态请用 `useCapabilityProbe`。
+ */
 export declare function subscribeProbe(listener: () => void): () => void;
+/**
+ * 能力表那条事实的名字：写完之后 `useFactInvalidate(CAPABILITY_FACT)` 标它，读者自动重取。
+ */
 export declare const CAPABILITY_FACT = "capability";
+/**
+ * 当前整张能力表的取值口（没探过是 `null`），给 `useSyncExternalStore` 用；渲染里请用 `useCapabilities`。
+ */
 export declare function capabilityValue(): CapabilityMap | null;
+/**
+ * 能力表的订阅口，返回退订函数；渲染里请用 `useCapabilities`。
+ */
 export declare function subscribeCapabilities(listener: () => void): () => void;
+/**
+ * 写入口：换整张表并通知订阅者（同值不通知）；传 `null` 清探针状态，`rechecked: true` 时顺手记下 `checkedAt`。
+ */
 export declare function setCapabilities(next: CapabilityMap | null, rechecked?: boolean): void;
+/**
+ * 一次强探开始：点亮“正在探”；已经在探就跳过。
+ */
 export declare function beginProbe(): void;
+/**
+ * 一次强探收尾：熄灭“正在探”。
+ */
 export declare function endProbe(): void;
+/**
+ * 把一次探测的结果发布出去：读到了就广播并回 `true`；没读到（`null`）时已有结论就留着回 `false`，
+ * 从来没有过结论才落一张空表回 `true`（“探不动”不等于“还没探”）。
+ */
 export declare function publishCapability(result: CapabilityMap | null, rechecked?: boolean): boolean;
+/**
+ * 同一语义（同一个 `force`）的在飞探测搭车：并发调用共享同一个 promise；落地或失败就清掉，
+ * 下一次强探会真的再跑一遍；`force` 不同不搭车。
+ */
 export declare function shareCapabilityFetch(force: boolean, load: (force: boolean) => Promise<CapabilityMap | null>): Promise<CapabilityMap | null>;
+/**
+ * 探一次能力表并发布：`force` 决定这是“重探”还是顺带读 —— 只有重探负责点亮 / 熄灭探针（`silent` 时连点亮都不做），
+ * 被更新的一次重探盖过的非强制结果会丢掉。
+ */
 export declare function runCapabilityRead(options: {
     readonly force: boolean;
     readonly silent?: boolean;
     readonly load?: (force: boolean) => Promise<CapabilityMap | null>;
 }): Promise<void>;
+/**
+ * 渲染里要整张能力表时调用：所有读者共享同一份结论，没探过是 `null`。
+ * `refreshToken` 变化算一次强制重探，事实版本（`CAPABILITY_FACT`）与 `reloadToken` 变化各触发一次重读。
+ */
 export declare function useCapabilities(refreshToken: number, reloadToken?: number): CapabilityMap | null;
+/**
+ * 渲染里要探针状态（`checking` / `checkedAt`）时调用，比如“最近检查”那一行。
+ */
 export declare function useCapabilityProbe(): CapabilityProbeState;

package/dist/types/shared/hooks/use-capability-gate.d.ts

@@ -1,15 +1,27 @@
 import type { CapabilityPayload } from '@dsh-workbench/shared';
 import { type GateMode } from '@dsh-workbench/shared';
 import { type CapabilityMap } from './use-capabilities';
+/**
+ * 一格的能力门：`capability` 是这一格声明的能力（没读到是 `null`）、`gated` 放行没（为真 = 这一格能画）、
+ * `forceProbe()` 现在就去探一次。
+ */
 export interface CapabilityGate {
     readonly capability: CapabilityPayload | null;
     readonly gated: boolean;
     forceProbe(): void;
 }
+/**
+ * 卡片里判断“这一格现在能不能画”时调用：`refreshToken` 变化触发一次重探。
+ * `options.mode` 换门的口径（默认 `'capability'`）、`options.fixture` 给夹具一份假能力；
+ * `gated` 按口径算 —— 读数还没到先放行（让它去读），读到明确不通过才拦；`forceProbe()` 是“现在就去探一次”。
+ */
 export declare function useCapabilityGate(unit: string, refreshToken: number, options?: {
     readonly mode?: GateMode | undefined;
     readonly fixture?: CapabilityPayload | undefined;
 }): CapabilityGate;
+/**
+ * 整张能力表的视图：表本体加探针的 `checkedAt` / `checking`，以及 `forceProbe()` 与 `reload()`。
+ */
 export interface CapabilityMapView {
     readonly capabilities: CapabilityMap | null;
     readonly checkedAt: number | null;
@@ -17,4 +29,8 @@ export interface CapabilityMapView {
     forceProbe(): void;
     reload(): void;
 }
+/**
+ * 设置页 / 体检那类“要全部单元的能力表”时调用：`reload()` 重取整张表、`forceProbe()` 立刻探一次、
+ * `checking` 是探针在跑；没探过时 `capabilities` 是 `null`。
+ */
 export declare function useCapabilityMap(refreshToken: number): CapabilityMapView;

package/dist/types/shared/hooks/use-card-summary.d.ts

@@ -1,7 +1,14 @@
+/**
+ * 卡片报给面板那一格的两个数：`refreshing` 还在不在忙、`at` 最近一次读到值的时间（没有是 `null`）。
+ */
 export interface CardSummary {
     readonly refreshing: boolean;
     readonly at: number | null;
 }
+/**
+ * 自己搭卡片、要把 `{ refreshing, at }` 在变化时交给调用点上报面板时调用；`onSummary` 要稳定引用
+ * （一般 `useCallback`），否则每次渲染都会上报一次。`useUnitBoard` 已经把这条接好。
+ */
 export declare function useCardSummary(onSummary: (summary: CardSummary) => void, summary: {
     readonly refreshing: boolean;
     readonly at: number | null | undefined;

package/dist/types/shared/hooks/use-diy-debug.d.ts

@@ -1,8 +1,21 @@
 import type { DebugState } from '@dsh-workbench/shared';
 import type { HostWrite } from './use-host-write';
+/**
+ * 调试约定的读路由（宿主侧那半同名）。
+ */
 export declare const DIY_DEBUG_ROUTE = "panels/diy-debug";
+/**
+ * 调试约定那条事实的名字：写完调 `useFactInvalidate(DIY_DEBUG_FACT)`，读者自动重取。
+ */
 export declare const DIY_DEBUG_FACT = "diy-debug";
+/**
+ * 要读“现在的调试约定是什么”时调用（左栏底部那枚状态）；跟着事实变化自动重取，不上报面板；
+ * 还没读到或后端说没有约定时都是 `null`。
+ */
 export declare function useDiyDebugState(): DebugState | null;
+/**
+ * 要发“开始 / 暂停 / 继续 / 结束调试”那几把动作时调用；写走 `diy-debug/act` 通道。
+ */
 export declare function useDiyDebugAct(): HostWrite<{
     text?: string;
 }>;

package/dist/types/shared/hooks/use-diy-record.d.ts

@@ -1,8 +1,21 @@
 import type { RecordState } from '@dsh-workbench/shared';
 import type { HostWrite } from './use-host-write';
+/**
+ * 录制交接的读路由（宿主侧那半同名）。
+ */
 export declare const DIY_RECORD_ROUTE = "panels/diy-record";
+/**
+ * 录制交接那条事实的名字：写完调 `useFactInvalidate(DIY_RECORD_FACT)`，读者自动重取。
+ */
 export declare const DIY_RECORD_FACT = "diy-record";
+/**
+ * 要读“这一段录制交接进行到哪了”时调用（左栏底部那枚状态）；跟着事实变化自动重取，不上报面板；
+ * 还没读到或后端说没有交接时都是 `null`。
+ */
 export declare function useDiyRecordState(): RecordState | null;
+/**
+ * 要发录制交接那几把动作（准备 / 读回 / 收尾）时调用；写走 `diy-record/act` 通道。
+ */
 export declare function useDiyRecordAct(): HostWrite<{
     text?: string;
 }>;

package/dist/types/shared/hooks/use-facts.d.ts

@@ -1,3 +1,13 @@
+/**
+ * 渲染里要“这条事实的版本号”时调用：版本一变，喂给 `useApiResource` 的 key 就变、读自动重来。
+ * 卡片读数默认订的 `factOfRoute(route)` 已经接好，只有要订别的事实才显式传 `fact`。
+ */
 export declare function useFactRevision(fact: string): number;
+/**
+ * 不在渲染里的地方（宿主事件、定时器里看到的旧值）要听事实变化时用它；返回值就是退订函数，用完记得退。
+ */
 export declare function subscribeFactRevision(fact: string, listener: () => void): () => void;
+/**
+ * 写完之后把这条事实标脏时调用：不标，面板就停在旧值；不传 `fact` 是把所有事实一起标脏。
+ */
 export declare function useFactInvalidate(): (fact?: string) => void;

package/dist/types/shared/hooks/use-host-write.d.ts

@@ -1,4 +1,8 @@
 import { type WriteChannel, type WriteOutcome } from '@dsh-workbench/shared';
+/**
+ * 一个写通道的句柄：`busy` 在发、`failed` / `detail` 上一条人话失败（没有是 `null`）、
+ * `send(body, { silent })` 回 `WriteOutcome`、`fail(message, detail?)` 本地就知道不行时自己塞一条、`clear()` 清掉。
+ */
 export interface HostWrite<T> {
     readonly busy: boolean;
     readonly failed: string | null;
@@ -9,9 +13,17 @@ export interface HostWrite<T> {
     fail(message: string, detail?: string): void;
     clear(): void;
 }
+/**
+ * 写通道的配置：`channel` 用哪个前缀、`resource` 挂在它的哪一格（多数通道留空）、`networkText` 网络不通时那句人话。
+ */
 export interface HostWriteOptions {
     readonly channel: WriteChannel;
     readonly resource?: string | undefined;
     readonly networkText: string;
 }
+/**
+ * 组件里要写（发 POST）时调用 —— 写只走这条，别在组件里自己 `fetch`。
+ * `send` 失败自动落到 `failed` + `detail`（界面直接显示，别自己拼）；`silent: true` 是不打扰：不动 `busy` / `failed`，
+ * 结果只从返回值拿。返回的 `busy` 是这一路写有没有在飞。
+ */
 export declare function useHostWrite<T>(options: HostWriteOptions): HostWrite<T>;