@dsh-workbench/shared 0.3.4 → 0.3.5

package/dist/lib/react.js

@@ -1,13 +1,49 @@
 const react = require('react');
+/**
+ * React 的 `createElement` 换个短名字再导出 —— 这套代码用 `h(...)` 写元素。
+ */
 export const h = react.createElement;
+/**
+ * React 的 `Fragment` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const Fragment = react.Fragment;
+/**
+ * React 的 `Component` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const Component = react.Component;
+/**
+ * React 的 `createContext` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const createContext = react.createContext;
+/**
+ * React 的 `useContext` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useContext = react.useContext;
+/**
+ * React 的 `useState` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useState = react.useState;
+/**
+ * React 的 `useEffect` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useEffect = react.useEffect;
+/**
+ * React 的 `useLayoutEffect` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useLayoutEffect = react.useLayoutEffect;
+/**
+ * React 的 `useMemo` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useMemo = react.useMemo;
+/**
+ * React 的 `useCallback` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useCallback = react.useCallback;
+/**
+ * React 的 `useRef` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useRef = react.useRef;
+/**
+ * React 的 `useSyncExternalStore` 原样再导出 —— 模块从这里拿，就不必自己直接依赖 react。
+ */
 export const useSyncExternalStore = react.useSyncExternalStore;

package/dist/lib/text.d.ts

@@ -1,4 +1,26 @@
+/**
+ * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
+ * @param value - 任意值；不是字符串的先 `String()`。
+ * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
+ */
 export declare function quoteShellArg(value: unknown): string;
+/**
+ * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
+ * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
+ */
 export declare function tailLines(text: string | null | undefined, lines?: number): string;
+/**
+ * 宽松解析一段前后可能夹着人话的 JSON：整段不通就从行首的 `[` / `{` 起、截到最后一个闭合符再试。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @returns 解析出的值（对象 / 数组 / 标量都原样）；空输入或怎么都解析不出给 `undefined`，调用方据此报「输出认不出」。
+ */
 export declare function parseJsonLoose(text: string | null | undefined): unknown;
+/**
+ * 把一段 Markdown 压成一行纯文本摘要：图片剥掉、链接只留可见文字、标记符号压成空格，超长按字符截断。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param limit - 摘要最多多少字符，默认 80。
+ * @returns 单行摘要；没超限原样给，超了截到 `limit` 并补省略号（总长 `limit + 1`；第 `limit` 个字符是空白时会被 `trimEnd` 去掉、略短），空输入给空串。
+ */
 export declare function excerpt(text: string | null | undefined, limit?: number): string;

package/dist/lib/text.js

@@ -1,6 +1,17 @@
+/**
+ * 把一个值裹成 shell 里的单引号字面量（值里的单引号一并转义），保证元字符按字面量传递。
+ * @param value - 任意值；不是字符串的先 `String()`。
+ * @returns 可安全拼进 `/bin/sh -c` 的一段文本 —— 含空格 / `$()` / `;` / 通配符的值都不会被当成语法。
+ */
 export function quoteShellArg(value) {
     return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
+/**
+ * 取一段文本的末尾若干行（如命令输出），顺带去掉首尾空白。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param lines - 最多留几行，默认 6；0 给全篇、负数从开头砍掉那么多行（都是 `slice` 语义），调用方传正数。
+ * @returns 末尾若干行、去首尾空行后的文本；原文行数不够就全给，空输入给空串。
+ */
 export function tailLines(text, lines = 6) {
     const all = String(text ?? '')
         .trim()
@@ -24,6 +35,11 @@ function candidateStarts(raw) {
     }
     return starts;
 }
+/**
+ * 宽松解析一段前后可能夹着人话的 JSON：整段不通就从行首的 `[` / `{` 起、截到最后一个闭合符再试。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @returns 解析出的值（对象 / 数组 / 标量都原样）；空输入或怎么都解析不出给 `undefined`，调用方据此报「输出认不出」。
+ */
 export function parseJsonLoose(text) {
     const raw = String(text ?? '').trim();
     if (!raw)
@@ -50,6 +66,12 @@ export function parseJsonLoose(text) {
 const MARKDOWN_IMAGE = /!\[[^\]]*\]\([^)]*\)/g;
 const MARKDOWN_LINK = /\[([^\]]*)\]\([^)]*\)/g;
 const MARKDOWN_MARKS = /[*`_>#]/g;
+/**
+ * 把一段 Markdown 压成一行纯文本摘要：图片剥掉、链接只留可见文字、标记符号压成空格，超长按字符截断。
+ * @param text - 原文；`null` / `undefined` 当空串。
+ * @param limit - 摘要最多多少字符，默认 80。
+ * @returns 单行摘要；没超限原样给，超了截到 `limit` 并补省略号（总长 `limit + 1`；第 `limit` 个字符是空白时会被 `trimEnd` 去掉、略短），空输入给空串。
+ */
 export function excerpt(text, limit = 80) {
     const flat = String(text ?? '')
         .replace(MARKDOWN_IMAGE, ' ')

package/dist/lib/ui.d.ts

@@ -1,13 +1,63 @@
+/**
+ * 拼类名：只留真值、用空格连接（`false` / `null` / `undefined` / 空串都丢掉）。
+ * @param parts - 若干类名或条件值。
+ * @returns 拼好的类字符串；一个真值都没有给空串。
+ */
 export declare function cx(...parts: Array<string | false | null | undefined>): string;
+/**
+ * 时间文案取词：i18n 的 `(key, params) => 文案`；相对时间那几件都从它拿词。
+ */
 export type TimeTranslate = (key: string, params?: Record<string, unknown>) => string;
+/**
+ * 相对时间的档位名，对应词表里的 `time.short.*`。
+ */
 export type RelativeTimeUnit = 'now' | 'minutes' | 'hours' | 'days' | 'months' | 'years';
+/**
+ * 相对时间的一档：`unit` 是档位，`n` 是这一档的数量（单位随档位，见 `relativeTimeBucket`）。
+ */
 export interface RelativeTimeBucket {
     readonly unit: RelativeTimeUnit;
     readonly n: number;
 }
+/**
+ * 把时间戳按 dsh 的分档切成「刚刚 / N 分钟 / N 小时 / N 天 / N 月 / N 年」—— 30 天进月、365 天进年。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 档位与数量；时间戳或基准不是有限数给 `null`，未来时间钳到「刚刚」（`now` / 0）。
+ */
 export declare function relativeTimeBucket(epochMs: number, now?: number): RelativeTimeBucket | null;
+/**
+ * 行内用的紧凑相对时间（「3 分钟」这种，不带「前」）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 紧凑文案；时间戳非法给空串。
+ */
 export declare function relativeTimeCompact(epochMs: number, t: TimeTranslate, now?: number): string;
+/**
+ * 悬停卡里用的相对时间（「3 分钟前」）；「刚刚」那一档不加「前」。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 带「前」的文案；时间戳非法给空串。
+ */
 export declare function relativeTimeAgo(epochMs: number, t: TimeTranslate, now?: number): string;
+/**
+ * 会话行那一版相对时间：一小时内按分钟、一天内按小时、七天内按天，再久直接给绝对时间（到秒）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @returns 文案；时间戳不是有限数给空串，未来时间落「刚刚」，七天及以上给本地化的年月日时分秒。
+ */
 export declare function relativeTime(epochMs: number, t: TimeTranslate): string;
+/**
+ * 把 `/Users/<用户名>/…` 缩成 `~/…`，免得会话行里全是一样的长前缀。
+ * @param path - 任意值。
+ * @returns 缩好的路径；不在用户主目录下原样返回，不是字符串给空串。
+ */
 export declare function shortenPath(path: unknown): string;
+/**
+ * 解析不带时区的本地时间戳（`YYYY-MM-DD HH:mm:ss`，也接受 `T` 分隔），按本机时区换算。
+ * @param text - 原文；`null` / `undefined` 当空串；首尾空白容忍。
+ * @returns 毫秒时间戳；形态不认识给 `NaN`（调用方据此回退到原始字符串，宁可不换算也不显示错时间）。
+ */
 export declare function parseLocalTimestamp(text: string | null | undefined): number;

package/dist/lib/ui.js

@@ -1,3 +1,8 @@
+/**
+ * 拼类名：只留真值、用空格连接（`false` / `null` / `undefined` / 空串都丢掉）。
+ * @param parts - 若干类名或条件值。
+ * @returns 拼好的类字符串；一个真值都没有给空串。
+ */
 export function cx(...parts) {
     return parts.filter(Boolean).join(' ');
 }
@@ -6,6 +11,12 @@ const HOUR = 60 * MINUTE;
 const DAY = 24 * HOUR;
 const MONTH = 30 * DAY;
 const YEAR = 365 * DAY;
+/**
+ * 把时间戳按 dsh 的分档切成「刚刚 / N 分钟 / N 小时 / N 天 / N 月 / N 年」—— 30 天进月、365 天进年。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 档位与数量；时间戳或基准不是有限数给 `null`，未来时间钳到「刚刚」（`now` / 0）。
+ */
 export function relativeTimeBucket(epochMs, now = Date.now()) {
     if (!Number.isFinite(epochMs) || !Number.isFinite(now))
         return null;
@@ -25,10 +36,24 @@ export function relativeTimeBucket(epochMs, now = Date.now()) {
 function bucketLabel(bucket, t) {
     return bucket.unit === 'now' ? t('time.now') : t(`time.short.${bucket.unit}`, { n: bucket.n });
 }
+/**
+ * 行内用的紧凑相对时间（「3 分钟」这种，不带「前」）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 紧凑文案；时间戳非法给空串。
+ */
 export function relativeTimeCompact(epochMs, t, now) {
     const bucket = relativeTimeBucket(epochMs, now);
     return bucket === null ? '' : bucketLabel(bucket, t);
 }
+/**
+ * 悬停卡里用的相对时间（「3 分钟前」）；「刚刚」那一档不加「前」。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @param now - 基准时间，默认 `Date.now()`。
+ * @returns 带「前」的文案；时间戳非法给空串。
+ */
 export function relativeTimeAgo(epochMs, t, now) {
     const bucket = relativeTimeBucket(epochMs, now);
     if (bucket === null)
@@ -36,6 +61,12 @@ export function relativeTimeAgo(epochMs, t, now) {
     const label = bucketLabel(bucket, t);
     return bucket.unit === 'now' ? label : t('time.ago', { t: label });
 }
+/**
+ * 会话行那一版相对时间：一小时内按分钟、一天内按小时、七天内按天，再久直接给绝对时间（到秒）。
+ * @param epochMs - 要换算的时间戳（毫秒）。
+ * @param t - 词表取词函数。
+ * @returns 文案；时间戳不是有限数给空串，未来时间落「刚刚」，七天及以上给本地化的年月日时分秒。
+ */
 export function relativeTime(epochMs, t) {
     if (!Number.isFinite(epochMs))
         return '';
@@ -57,6 +88,11 @@ export function relativeTime(epochMs, t) {
         second: '2-digit',
     });
 }
+/**
+ * 把 `/Users/<用户名>/…` 缩成 `~/…`，免得会话行里全是一样的长前缀。
+ * @param path - 任意值。
+ * @returns 缩好的路径；不在用户主目录下原样返回，不是字符串给空串。
+ */
 export function shortenPath(path) {
     if (typeof path !== 'string')
         return '';
@@ -64,6 +100,11 @@ export function shortenPath(path) {
     return hit === null ? path : path.replace(hit[0], '~');
 }
 const LOCAL_TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{2}):(\d{2}):(\d{2})$/;
+/**
+ * 解析不带时区的本地时间戳（`YYYY-MM-DD HH:mm:ss`，也接受 `T` 分隔），按本机时区换算。
+ * @param text - 原文；`null` / `undefined` 当空串；首尾空白容忍。
+ * @returns 毫秒时间戳；形态不认识给 `NaN`（调用方据此回退到原始字符串，宁可不换算也不显示错时间）。
+ */
 export function parseLocalTimestamp(text) {
     const raw = String(text ?? '').trim();
     if (!LOCAL_TIMESTAMP.test(raw))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/shared",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "工作台与模块共享的纯代码与契约类型：类型、纯逻辑、哑组件、平台解析。宿主侧的东西从 /host 进（不影响浏览器产物）。",
   "license": "MIT",
   "type": "module",

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;