@dsh-workbench/shared 0.3.3 → 0.3.5

package/src/components/SelectField.tsx

@@ -7,6 +7,7 @@ import { Field } from './Field.js';
 import { TextField } from './TextField.js';
 import './SelectField.css';
 
+/** 一个候选项：值、人看的标签，可带搜索词、图标、分组与禁用标记。 */
 export interface SelectFieldOption {
   readonly value: string;
   readonly label: ReactNode;
@@ -16,16 +17,19 @@ export interface SelectFieldOption {
   readonly disabled?: boolean | undefined;
 }
 
+/** 名单读不到时的退路：值 + 变更回调，`SelectField` 会由下拉改成手填输入框。 */
 export interface SelectFieldFallback {
   readonly value: string;
   readonly onChange: (next: string) => void;
 }
 
+/** 列表底部固定那一条（如"添加工作区"）：文案 + 可选图标。 */
 export interface SelectFieldFooter {
   readonly label: ReactNode;
   readonly icon?: ReactNode | undefined;
 }
 
+/** `SelectField` 的契约：值、候选、变更回调，外加搜索 / 分组 / 加载 / 空态 / 页脚那一整套开关。 */
 export interface SelectFieldProps {
   readonly value: string;
   readonly options: readonly SelectFieldOption[];
@@ -205,17 +209,20 @@ function framed(
   return className === undefined ? inner : <div className={className}>{inner}</div>;
 }
 
+/** 算候选项用来匹配搜索的文本：有 `searchText` 就用它，否则取字符串标签；标签不是字符串又没给它是空串（这项搜不到）。 */
 export function searchTextOf(option: SelectFieldOption): string {
   if (option.searchText !== undefined) return option.searchText;
   return typeof option.label === 'string' ? option.label : '';
 }
 
+/** 默认匹配：查询去空白折成小写后看它是不是 `searchTextOf` 的子串；查询为空或纯空白时一律命中（留在列表里）。 */
 export function defaultSelectFilter(option: SelectFieldOption, query: string): boolean {
   const needle = query.trim().toLowerCase();
   if (needle === '') return true;
   return searchTextOf(option).toLowerCase().includes(needle);
 }
 
+/** 按查询过滤候选 —— 组件与模块自己算列表都用它，好让同一份口径管两处：`filter` 不给就用 `defaultSelectFilter`，顺序不变。 */
 export function filterSelectOptions(
   options: readonly SelectFieldOption[],
   query: string,
@@ -224,6 +231,7 @@ export function filterSelectOptions(
   return options.filter((option) => filter(option, query));
 }
 
+/** 把键盘游标换算成当前该高亮那项的 value：游标 `null`（还没动过键盘）或列表为空时没有高亮；太大的游标收到最后一项，负游标取不到项也回 `null`。 */
 export function selectCursorValue(
   shown: readonly SelectFieldOption[],
   cursor: number | null,
@@ -232,6 +240,7 @@ export function selectCursorValue(
   return shown[Math.min(cursor, shown.length - 1)]?.value ?? null;
 }
 
+/** 按上下键移动游标（两头环绕）：还没选过时向下取第一项、向上取最后一项；列表为空回 `null`（一步都动不了）。`step` 1 向下、-1 向上。 */
 export function stepSelectCursor(
   shown: readonly SelectFieldOption[],
   cursor: number | null,
@@ -242,6 +251,7 @@ export function stepSelectCursor(
   return (cursor + step + shown.length) % shown.length;
 }
 
+/** 把候选排成 `Menu` 要的条目表：按 `group` 插分组标题；一项都没有时退回 `emptyText` 那一行（不给就是空表）。`revealId` 是开列表时要滚进可视区的那个 value。 */
 export function selectEntries(
   shown: readonly SelectFieldOption[],
   emptyText: string | undefined,
@@ -323,6 +333,22 @@ function useSelectState(props: SelectFieldProps) {
   };
 }
 
+/**
+ * 下拉选择：默认是跟 `TextField` 一套的常规下拉框（不是原生 `<select>`），无边框那种给 `variant: 'ghost'`。
+ * `open` 不给就内部自己管（两种接法下 `onOpenChange` 都会通知），`loading` 把触发器换成转圈 + `loadingText`（默认 `…`），
+ * `selection` 选选中行标记（`fill` 整行底色 / `check` 行尾勾），`footer` 是列表底部那一条（点它走 `onFooter`，不改当前值）。
+ * @param props.value - 当前值；在 `options` 里找不到就按"没选"画 `placeholder`。
+ * @param props.options - 全量候选；空数组且给了 `fallback` 时改画手填输入框。
+ * @param props.onChange - 选中一项后的回调，回的是那一项的 `value`。
+ * @param props.label - 没进 `FormRow` 时的标签兜底；进了那一行就别再给它和 `hint`，否则会多一个标签。
+ * @param props.renderValue - 自己渲染触发器上那份当前值；不给就用候选项的 `label`。
+ * @param props.placeholder - 没选中时那句话；不给是 `—`。
+ * @param props.search - 是否可搜（默认 true）；`false` 时不画搜索框、也不自动聚焦。
+ * @param props.filter - 自定义匹配；不给用 `defaultSelectFilter`（空白查询一律命中）。
+ * @param props.emptyText - 无匹配时的文案，或按查询生成文案的函数（能说"没有匹配 X 的项"）。
+ * @param props.fallback - 退路：`options` 为空时改成手填（`value` + `onChange`）。
+ * @returns 触发器，以及打开时的搜索框与列表。
+ */
 export function SelectField(props: SelectFieldProps) {
   const {
     value,

package/src/components/SelectFieldNodes.tsx

@@ -6,6 +6,21 @@ import {
 } from '@deepseek-ai/dsh-client-ui-primitives';
 import { Spinner } from './Spinner.js';
 
+/**
+ * 下拉触发器那颗按钮：图标 + 当前值 + 箭头，交给 `Menu` 当 anchor；宽窄两档共用一个形状。
+ * @param args.id - 触发器 id。
+ * @param args.className - 触发器类名（已含 variant 与 iconOnly 的档）。
+ * @param args.disabled - 是否禁用。
+ * @param args.invalid - 置真写 `aria-invalid`。
+ * @param args.open - 列表是否开着，写进 `aria-expanded`。
+ * @param args.ariaLabel - 读屏名。
+ * @param args.title - 原生提示。
+ * @param args.icon - 值左边那枚图标；不给不占位。
+ * @param args.value - 已渲染好的当前值节点（文本或占位）。
+ * @param args.iconOnly - 只画图标（窄栏那颗切换钮），值与箭头都不画。
+ * @param args.onOpen - 点它做什么，通常是把列表打开。
+ * @returns 一颗 `<button>`。
+ */
 export function selectTriggerNode(args: {
   readonly id: string | undefined;
   readonly className: string;
@@ -47,6 +62,15 @@ export function selectTriggerNode(args: {
   );
 }
 
+/**
+ * 名单还没读到时的触发器：禁用 + `aria-busy` 的按钮，`SelectField` 在 `loading` 那档画它。
+ * @param args.id - 触发器 id。
+ * @param args.className - 触发器类名；它后面会接上 loading 那档的类。
+ * @param args.invalid - 置真写 `aria-invalid`。
+ * @param args.ariaLabel - 读屏名。
+ * @param args.loadingText - 占位文案；不给就是 `…`。
+ * @returns 一颗禁用且 `aria-busy` 的按钮。
+ */
 export function selectLoadingNode(args: {
   readonly id: string | undefined;
   readonly className: string;

package/src/components/SettingsSection.tsx

@@ -2,6 +2,9 @@ import type { ReactNode } from '../lib/react.js';
 import { h } from '../lib/react.js';
 import './SettingsSection.css';
 
+/**
+ * `SettingsSection` 的契约：一节的读屏名、标题、右上动作与内容。
+ */
 export interface SettingsSectionProps {
   readonly label: string;
   readonly title: ReactNode;
@@ -9,6 +12,14 @@ export interface SettingsSectionProps {
   readonly children?: ReactNode | undefined;
 }
 
+/**
+ * 设置面里的一节：标题 + 右上那颗动作 + 一节内容，把一屏设置分组。
+ * @param props.label - 只给读屏的组名（`aria-label`），不是标题。
+ * @param props.title - 人看的标题。
+ * @param props.action - 标题右侧的动作（如"添加"）；不给不占位。
+ * @param props.children - 这一节的内容。
+ * @returns 一个 `role="group"` 的 section。
+ */
 export function SettingsSection({ label, title, action, children }: SettingsSectionProps) {
   return (
     <section className="wb-settings" role="group" aria-label={label}>

package/src/components/Spinner.tsx

@@ -2,11 +2,20 @@ import { StateDot } from '@deepseek-ai/dsh-client-ui-primitives';
 import { h } from '../lib/react.js';
 import './Spinner.css';
 
+/**
+ * `Spinner` 的契约：直径像素与可选的读屏标签。
+ */
 export interface SpinnerProps {
   readonly size?: number;
   readonly label?: string | undefined;
 }
 
+/**
+ * 转圈：加载态一律用它（`FormActions` 与 `ChoiceGroup` 内部也是它），别自己写动画。
+ * @param props.size - 直径像素（默认 14，与 dsh 紧凑控件同高）。
+ * @param props.label - 给了才读屏可见（`role="status"`）；不给整颗 `aria-hidden`，此时旁边必须有文字。
+ * @returns 一枚 `StateDot state="ongoing"`，自身不带文字。
+ */
 export function Spinner({ size = 14, label }: SpinnerProps) {
   return (
     <span

package/src/components/Stack.tsx

@@ -2,10 +2,18 @@ import type { ReactNode } from '../lib/react.js';
 import { h } from '../lib/react.js';
 import './Stack.css';
 
+/**
+ * `Stack` 的契约：只带一个竖排内容槽。
+ */
 export interface StackProps {
   readonly children?: ReactNode | undefined;
 }
 
+/**
+ * 竖排容器：把相邻内容按统一间距摞起来，懒得自己分组时的默认外包装。
+ * @param props.children - 要竖排的内容；不给就渲染一个空容器。
+ * @returns 竖排的 div。
+ */
 export function Stack({ children }: StackProps) {
   return <div className="wb-stack">{children}</div>;
 }

package/src/components/StateBlock.tsx

@@ -2,6 +2,9 @@ import type { ReactNode } from '../lib/react.js';
 import { h } from '../lib/react.js';
 import './StateBlock.css';
 
+/**
+ * `StateBlock` 的契约：标题、状态点、提示、正文与行尾动作。
+ */
 export interface StateBlockProps {
   readonly title?: ReactNode | undefined;
   readonly dot?: ReactNode | undefined;
@@ -11,6 +14,16 @@ export interface StateBlockProps {
   readonly children?: ReactNode | undefined;
 }
 
+/**
+ * 有内容那一段：一个标题 + 一行提示 + 正文，卡里已经读到东西时用它开头。
+ * @param props.title - 标题那行；它与 `dot` 都不给时整行不画。
+ * @param props.dot - 标题前那枚状态点。
+ * @param props.hint - 标题下那行小字（如"3 条 · 刚刚"）；不给不画。
+ * @param props.resolving - "正在读"那行，读数期间挂上去；不给不画。
+ * @param props.actions - 底部动作区；给了才画那一条。
+ * @param props.children - 正文。
+ * @returns 一个 div。
+ */
 export function StateBlock({ title, dot, hint, actions, resolving, children }: StateBlockProps) {
   return (
     <div className="wb-stateBlock">

package/src/components/TextField.tsx

@@ -2,10 +2,18 @@ import type { InputHTMLAttributes } from 'react';
 import './TextField.css';
 import { h } from '../lib/react.js';
 
+/**
+ * `TextField` 的契约：原生 input 属性，外加一个标红开关。
+ */
 export interface TextFieldProps extends InputHTMLAttributes<HTMLInputElement> {
   readonly invalid?: boolean;
 }
 
+/**
+ * 单行文本输入：设置面与筛选框都用它，`invalid` 之外的属性全部透传给原生 `<input>`。
+ * @param props.invalid - 置真标红并写 `aria-invalid`（默认 false）；错在哪一句归 `FormRow.problem`。
+ * @returns 输入框元素；`className` 是追加在基础类名之后，而不是替换它。
+ */
 export function TextField({ invalid = false, className, ...rest }: TextFieldProps) {
   return (
     <input

package/src/components/board-module.ts

@@ -4,10 +4,16 @@ import type { UnitManifest } from '../api/unit.js';
 import type { CapabilityPayload } from '../api/workbench-contract.js';
 import type { Dictionaries } from '../i18n/index.js';
 
+/**
+ * 面板要跳去的一格：只用 `kind` 说去哪，具体负载由各 unit 自己约定。
+ */
 export interface PanelStep {
   readonly kind: string;
 }
 
+/**
+ * 交给面板渲染的宿主世界：工作区与会话快照、装着的 unit、面板开关、能力表与当前选中。
+ */
 export interface SuiteWorld {
   readonly workspaces: WorkspaceSnapshot;
   readonly sessions: SessionsSnapshot;
@@ -20,6 +26,9 @@ export interface SuiteWorld {
   };
 }
 
+/**
+ * 面板视图的统一 prop：一份世界快照 + 刷新令牌 + 四个通知回调 + 翻译函数。
+ */
 export interface BoardModuleProps {
   readonly world: SuiteWorld;
   readonly refreshToken: number;
@@ -30,16 +39,25 @@ export interface BoardModuleProps {
   readonly t: Translate;
 }
 
+/**
+ * 一张卡报给宿主的摘要：此刻在不在刷新、上次读到是哪个时刻。
+ */
 export interface ModuleSummary {
   readonly refreshing: boolean;
   readonly at: number | null;
 }
 
+/**
+ * unit 的一个子步骤：标题文案键 + 渲染这件视图的组件。
+ */
 export interface UnitStep {
   readonly titleKey: string;
   readonly View: (props: BoardModuleProps) => ReactNode;
 }
 
+/**
+ * 一个面板单元的注册面：id、标题键、排序、视图，可带一组子步骤。
+ */
 export interface BoardModule {
   readonly id: string;
   readonly titleKey: string;
@@ -48,6 +66,9 @@ export interface BoardModule {
   readonly steps?: Readonly<Record<string, UnitStep>>;
 }
 
+/**
+ * 模块在浏览器侧交出来的那份面：卡片、子步骤、自己的字典，以及审批渲染。
+ */
 export interface UnitClientFace {
   readonly unit: string;
   readonly card?: (props: BoardModuleProps) => ReactNode;
@@ -61,15 +82,24 @@ export interface UnitClientFace {
     | undefined;
 }
 
+/**
+ * 带着自己 manifest 的模块面（外壳按 unit 认领时用）。
+ */
 export interface UnitOwnedClientFace extends UnitClientFace {
   readonly manifest: UnitManifest;
 }
 
+/**
+ * 一次审批要看的输入：工具名，与它这次收到的参数。
+ */
 export interface ApprovalInput {
   readonly tool: string;
   readonly args: Readonly<Record<string, unknown>>;
 }
 
+/**
+ * 模块注册进外壳的那个口：注册一份面（拿回注销函数）、列出已装 unit。
+ */
 export interface UnitClientApi {
   registerUnit(face: UnitClientFace): () => void;
   manifests(): readonly UnitManifest[];

package/src/components/icons.tsx

@@ -1,5 +1,8 @@
 import { h, type ReactNode } from '../lib/react.js';
 
+/**
+ * 自绘图标的契约：只给边长像素。
+ */
 export interface IconProps {
   size?: number;
 }
@@ -31,6 +34,11 @@ function Shell({
   );
 }
 
+/**
+ * 会话图标：一枚对话气泡，dsh 的图标表里没有，留给我们自己用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconConversation({ size = 16 }: IconProps) {
   return (
     <Shell size={size} strokeWidth={1.3}>
@@ -43,6 +51,11 @@ export function IconConversation({ size = 16 }: IconProps) {
   );
 }
 
+/**
+ * 品牌标：侧栏顶上那枚工作台方块标；默认 24px（它是品牌物，别拿它当通用图标）。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconBrandMark({ size = 24 }: IconProps) {
   return (
     <Shell size={size} strokeWidth={1.6} viewBox="0 0 24 24">
@@ -56,6 +69,11 @@ export function IconBrandMark({ size = 24 }: IconProps) {
   );
 }
 
+/**
+ * opencli 的标：包类型那一格用它；颜色写死的品牌物，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconOpencli({ size = 16 }: IconProps) {
   return (
     <Shell size={size} viewBox="0 0 64 64">
@@ -83,6 +101,11 @@ export function IconOpencli({ size = 16 }: IconProps) {
   );
 }
 
+/**
+ * npm 的标：包类型那一格用它；保留品牌红，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconNpm({ size = 16 }: IconProps) {
   return (
     <Shell size={size} viewBox="0 0 1024 1024">
@@ -94,6 +117,11 @@ export function IconNpm({ size = 16 }: IconProps) {
   );
 }
 
+/**
+ * 四宫格："模块"这个概念的通用单色图标（侧栏、面板那颗钮、市场节的标题）；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconModules({ size = 16 }: IconProps) {
   return (
     <svg width={size} height={size} viewBox="0 0 16 16" fill="none" aria-hidden="true">
@@ -105,6 +133,11 @@ export function IconModules({ size = 16 }: IconProps) {
   );
 }
 
+/**
+ * 模块类型标：渐变方块 + 白四宫格，用在"这是个模块"的行首；品牌物，颜色不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconModuleMark({ size = 16 }: IconProps) {
   return (
     <Shell size={size} viewBox="0 0 24 24">
@@ -124,6 +157,11 @@ export function IconModuleMark({ size = 16 }: IconProps) {
   );
 }
 
+/**
+ * 面板 / 卡片那类的图标：整屏与柱状那种形状，给"面板"这一档用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconPanelScreen({ size = 16 }: IconProps) {
   return (
     <svg

package/src/config/constants.ts

@@ -1,74 +1,122 @@
+/** 外壳插件的包名：浏览器模块表与宿主按它注册、认领这枚插件。 */
 export const PLUGIN_ID = "@dsh-workbench/core";
 
+/** 与外壳同批发布的兄弟包名：`release.ts` 用它判一版三包是否都已在源上。 */
 export const RELEASE_SIBLINGS = [
   "@dsh-workbench/shared",
   "@dsh-workbench/module-tools",
 ] as const;
 
+/** 外壳宿主 HTTP API 的根前缀；prefs / actions / provision 等路由都挂在它下面。 */
 export const API_PREFIX = "/workbench/api";
 
+/** 模块偏好读写的路由前缀，挂在外壳 API 下：走写通道，拒写回 write-refused。 */
 export const PREFS_PREFIX = `${API_PREFIX}/prefs`;
 
+/** 事实（facts）SSE 事件流的端点路径；前端 `EventSource` 按它带 `since` 游标续传。 */
 export const EVENTS_PATH = "/workbench/events";
+/** 写动作的路由前缀，挂在外壳 API 下：模块的写通道 POST 到这里。 */
 export const ACTIONS_PREFIX = `${API_PREFIX}/actions`;
 
+/** 机器供给（provision）的路由前缀：只收 POST，装机时用它铺一份运行环境。 */
 export const PROVISION_PREFIX = `${API_PREFIX}/provision`;
 
+/** 面板运行态上报的路径段：崩溃与卡片收尾分别 POST 到 `panel-state/crash`、`panel-state/cards`。 */
 export const PANEL_STATE_PATH = "panel-state";
 
+/** DIY 调试动作的路径段；宿主按它登记 `/workbench/api/diy-debug` 前缀。 */
 export const DIY_DEBUG_PATH = "diy-debug";
+/** 调试动作的子路径（`diy-debug/act`）；仓内暂无调用点，动作现走 `DIY_DEBUG_SERVICE`。 */
 export const DIY_DEBUG_ACT_PATH = `${DIY_DEBUG_PATH}/act`;
 
+/** DIY 录制交接的路径段；宿主按它登记 `/workbench/api/diy-record` 前缀。 */
+export const DIY_RECORD_PATH = "diy-record";
+/** 录制动作的子路径（`diy-record/act`）；仓内暂无调用点，录制现走 `DIY_RECORD_SERVICE`。 */
+export const DIY_RECORD_ACT_PATH = `${DIY_RECORD_PATH}/act`;
+
+/** 面板运行态的路由前缀，挂在外壳 API 下：上报口用它，拒报回 report-refused。 */
 export const PANEL_STATE_PREFIX = `${API_PREFIX}/${PANEL_STATE_PATH}`;
 
+/** 钉住的 opencli 插件版本：`opencli-runtime` 按它校验、取那一份。 */
 export const OPENCLI_PIN = "1.8.8";
 
+/** 缺陷看板套件的 dsh 服务名（`workbenchCodingIssues`）：套件照它登记自己那份服务。 */
 export const CODING_ISSUES_SERVICE = "workbenchCodingIssues";
 
+/** 面板套件的 dsh 服务名（`workbenchPanels`）：宿主经它取套件公布的清单与订阅。 */
 export const PANELS_SERVICE = "workbenchPanels";
 
+/** 单元花名册服务的 dsh 服务名（`workbenchUnits`）：模块经它认领自己的单元。 */
 export const UNITS_SERVICE = "workbenchUnits";
 
+/** 面板运行态服务的 dsh 服务名（`workbenchPanelState`）：宿主注册，读口按它取。 */
 export const PANEL_STATE_SERVICE = "workbenchPanelState";
 
+/** DIY 调试约定服务的 dsh 服务名（`workbenchDiyDebug`）：调试动作走它，不走 HTTP。 */
 export const DIY_DEBUG_SERVICE = "workbenchDiyDebug";
 
+/** DIY 录制交接服务的 dsh 服务名（`workbenchDiyRecord`）：`diy-acts.ts` 经它收发录制三拍。 */
+export const DIY_RECORD_SERVICE = "workbenchDiyRecord";
+
+/** 会话投影服务的 dsh 服务名（`sessionProjections`）：宿主经 `stateOf(session, 'agentPreset')` 读那一档。 */
+export const SESSION_PROJECTIONS_SERVICE = "sessionProjections";
+
+/** 面板清单一次取回的行数上限（条）：外部模块拿它当 opencli `--pageSize`。 */
 export const PANEL_LIST_LIMIT = 50;
 
+/** 单次 opencli 调用的默认超时（毫秒）；调用点没传 `timeoutMs` 时按它算。 */
 export const OPENCLI_TIMEOUT_MS = 120_000;
 
+/** 同时最多几条 opencli 在跑（条）：`opencli.ts` 超出就排队。 */
 export const OPENCLI_MAX_CONCURRENT = 4;
 
+/** 启动预热站点那一跳的超时（毫秒）；超时按未热对待，不挡面板。 */
 export const WARM_TIMEOUT_MS = 20_000;
 
+/** 装 / 卸模块包的超时（毫秒）：pnpm 与取包内容都按它算。 */
 export const INSTALL_TIMEOUT_MS = 300_000;
 
+/** 查 registry 版本那一次请求的超时（毫秒）。 */
 export const VERSION_CHECK_TIMEOUT_MS = 10_000;
 
+/** 版本查询结果的缓存有效期（毫秒）：期内不发第二次请求。 */
 export const VERSION_CHECK_TTL_MS = 600_000;
 
+/** 单元探测结果的缓存有效期（毫秒）。 */
 export const PROBE_TTL_MS = 30_000;
 
+/** 加载态至少显示多久（毫秒）：一瞬完成的读写也得让用户看见那一下。 */
 export const MIN_BUSY_MS = 500;
 
+/** 工具读出来的值交给面板后的保留时长（毫秒）：过期就不再算这一拍。 */
 export const HANDOFF_TTL_MS = 15_000;
 
+/** 跑本地 git 命令的超时（毫秒）；短于对外的 `OPENCLI_TIMEOUT_MS`。 */
 export const GIT_TIMEOUT_MS = 10_000;
 
+/** 面板轮询事实的间隔（毫秒）：SSE 断了走这条兜底轮询。 */
 export const PANEL_POLL_MS = 2000;
 
+/** 没起中文名的工作区默认标题：左栏按它分组、显示。 */
 export const DEFAULT_WORKSPACE_TITLE = "default-workspace";
 
+/** 记住当前项目的 localStorage 键。 */
 export const STORAGE_KEY_PROJECT = "dsh-workbench.project";
 
+/** 记住右栏展开与否的 localStorage 键。 */
 export const STORAGE_KEY_RIGHTBAR = "dsh-workbench.rightbar.expanded";
 
+/** 记住右栏当前列的 localStorage 键。 */
 export const STORAGE_KEY_RIGHTBAR_COLUMN = "dsh-workbench.rightbar.column";
 
+/** 记住右栏宽度（像素数字的字符串）的 localStorage 键。 */
 export const STORAGE_KEY_RIGHTBAR_WIDTH = "dsh-workbench.rightbar.width";
 
+/** 右栏宽度达到或超过多少像素就按全屏对待（阈值，像素）。 */
 export const RIGHTBAR_FULLSCREEN_WIDTH = 768;
 
+/** dsh i18n 的命名空间：词表都注册在它下面，`ctx.locale.register` / `bind` 按它取。 */
 export const LOCALE_NS = "workbench";
 
+/** 外壳支持的语言标识，顺序即回退顺序：首项是基准，其余词表必须与它逐键同构。 */
 export const LOCALES = ["zh", "en"] as const;

package/src/config/storage.ts

@@ -1,3 +1,4 @@
+/** 读 localStorage 里的一段文本；没有这个键、或存储不可用（隐私模式）时返回 null。 */
 export function readText(key: string): string | null {
   try {
     return window.localStorage.getItem(key);
@@ -6,6 +7,7 @@ export function readText(key: string): string | null {
   }
 }
 
+/** 写一段文本进 localStorage；`value` 为 null 时删掉这个键，写不进去就静默作罢。 */
 export function writeText(key: string, value: string | null): void {
   try {
     if (value === null) window.localStorage.removeItem(key);
@@ -14,12 +16,14 @@ export function writeText(key: string, value: string | null): void {
   }
 }
 
+/** 读一个布尔开关：键不存在时返回 `fallback`，只有存进去的 `'true'` 算真。 */
 export function readFlag(key: string, fallback: boolean): boolean {
   const raw = readText(key);
   if (raw === null) return fallback;
   return raw === 'true';
 }
 
+/** 把一个布尔开关写进 localStorage（存 `'true'` / `'false'`）；失败静默。 */
 export function writeFlag(key: string, value: boolean): void {
   writeText(key, value ? 'true' : 'false');
 }

package/src/host/browser-read.ts

@@ -5,6 +5,7 @@ import { runShell } from './shell.js';
 
 export const BROWSER_SCREEN_SESSION = 'workbench';
 export const BROWSER_READ_SESSION = 'workbench-read';
+export const BROWSER_RECORD_SESSION = 'workbench-rec';
 
 const DEFAULT_TIMEOUT_MS = 25000;
 const DEFAULT_RETRY_MS = 1200;

package/src/host/http.ts

@@ -1,7 +1,7 @@
 import type { DshHostContext, DshRequest, DshResponse } from '../api/dsh.js';
 import { unitFactScope } from '../api/facts.js';
 import { parseCardsReport, parseCrashReport, type PanelStateStore } from '../lib/panel-state.js';
-import { ACTIONS_PREFIX, API_PREFIX, DIY_DEBUG_PATH, PANEL_STATE_PREFIX, PLUGIN_ID, PREFS_PREFIX, PROVISION_PREFIX } from '../config/constants.js';
+import { ACTIONS_PREFIX, API_PREFIX, DIY_DEBUG_PATH, DIY_RECORD_PATH, PANEL_STATE_PREFIX, PLUGIN_ID, PREFS_PREFIX, PROVISION_PREFIX } from '../config/constants.js';
 import {
   parseProvisionBody,
   type ProvisionHandler,
@@ -340,3 +340,17 @@ export function registerDiyDebugAct(
     wrote: () => log?.bump(['diy-debug']),
   });
 }
+
+export function registerDiyRecordAct(
+  ctx: DshHostContext,
+  resource: PostResource,
+  log?: { bump(facts: readonly string[]): unknown } | undefined,
+): () => void {
+  return registerPost(ctx, {
+    prefix: `${API_PREFIX}/${DIY_RECORD_PATH}`,
+    what: '工作台 DIY 录制交接动作',
+    refusedCode: 'action-refused',
+    resources: [resource],
+    wrote: () => log?.bump(['diy-record']),
+  });
+}

package/src/host/tool-approval.ts

@@ -20,6 +20,15 @@ export const APPROVAL_NOTE_ARG = 'approval_note';
 
 export const APPROVAL_NOTE_LIMIT = 40;
 
+export const APPROVAL_DETAIL_LIMIT = 20;
+
+export const APPROVAL_QUESTION_LIMIT = 40;
+
+export const APPROVAL_SEPARATOR_LIMIT = 8;
+
+export const APPROVAL_HEADLINE_LIMIT =
+  APPROVAL_DETAIL_LIMIT + APPROVAL_QUESTION_LIMIT + APPROVAL_NOTE_LIMIT + APPROVAL_SEPARATOR_LIMIT;
+
 const NOTE_SCHEMA: Readonly<Record<string, unknown>> = {
   type: 'string',
   description: '一句话说明你这次想拿它干什么（要点头时显示在审批屏上；40 字以内）。',
@@ -45,12 +54,16 @@ export function withApprovalNote(
   };
 }
 
+function oneLine(text: string): string {
+  return text.replace(/\s+/g, ' ').trim();
+}
+
 function approvalNoteOf(call: ApprovalCall): string | undefined {
   const raw = call.arguments;
   const value =
     typeof raw === 'object' && raw !== null ? (raw as Record<string, unknown>)[APPROVAL_NOTE_ARG] : undefined;
   if (typeof value !== 'string') return undefined;
-  const line = value.replace(/\s+/g, ' ').trim();
+  const line = oneLine(value);
   if (line === '') return undefined;
   return line.length > APPROVAL_NOTE_LIMIT ? `${line.slice(0, APPROVAL_NOTE_LIMIT)}…` : line;
 }
@@ -76,6 +89,7 @@ export type ApprovalPolicy = (call: ApprovalCall) => ApprovalVerdict | undefined
 export interface ApprovalContext {
   readonly writes?: boolean | undefined;
   readonly policy?: ApprovalPolicy | undefined;
+  readonly declaredNote?: boolean | undefined;
   readonly detailOf?:
     | ((call: ApprovalCall) => ApprovalFacts | undefined | Promise<ApprovalFacts | undefined>)
     | undefined;
@@ -97,8 +111,8 @@ function compose(
           en: `${detail.en} — ${verdict.question.en}`,
           zh: `${detail.zh} —— ${verdict.question.zh}`,
         };
-  if (note === undefined) return base;
-  return { en: `${base.en} — ${note}`, zh: `${base.zh} —— ${note}` };
+  const line = note === undefined ? base : { en: `${base.en} — ${note}`, zh: `${base.zh} —— ${note}` };
+  return { en: oneLine(line.en), zh: oneLine(line.zh) };
 }
 
 export async function approvalFor(
@@ -139,6 +153,6 @@ export async function approvalFor(
   return {
     kind: 'ask',
     reason: verdict.reason,
-    displayReason: compose(facts, verdict, approvalNoteOf(call)),
+    displayReason: compose(facts, verdict, context.declaredNote === true ? approvalNoteOf(call) : undefined),
   };
 }