@dsh-workbench/shared 0.3.4 → 0.3.6

package/dist/components/board-module.d.ts

@@ -3,9 +3,15 @@ import type { SessionsSnapshot, Translate, WorkspaceSnapshot, WorkspaceView } fr
 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;
@@ -19,6 +25,9 @@ export interface SuiteWorld {
         readonly workspace: WorkspaceView | null;
     };
 }
+/**
+ * 面板视图的统一 prop：一份世界快照 + 刷新令牌 + 四个通知回调 + 翻译函数。
+ */
 export interface BoardModuleProps {
     readonly world: SuiteWorld;
     readonly refreshToken: number;
@@ -28,14 +37,23 @@ export interface BoardModuleProps {
     readonly onSummary: (summary: ModuleSummary) => void;
     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;
@@ -43,6 +61,9 @@ export interface BoardModule {
     readonly View: (props: BoardModuleProps) => ReactNode;
     readonly steps?: Readonly<Record<string, UnitStep>>;
 }
+/**
+ * 模块在浏览器侧交出来的那份面：卡片、子步骤、自己的字典，以及审批渲染。
+ */
 export interface UnitClientFace {
     readonly unit: string;
     readonly card?: (props: BoardModuleProps) => ReactNode;
@@ -56,13 +77,22 @@ export interface UnitClientFace {
         }) => ReactNode;
     } | 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/dist/components/icons.d.ts

@@ -1,10 +1,48 @@
+/**
+ * 自绘图标的契约：只给边长像素。
+ */
 export interface IconProps {
     size?: number;
 }
+/**
+ * 会话图标：一枚对话气泡，dsh 的图标表里没有，留给我们自己用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconConversation({ size }: IconProps): JSX.Element;
+/**
+ * 品牌标：侧栏顶上那枚工作台方块标；默认 24px（它是品牌物，别拿它当通用图标）。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconBrandMark({ size }: IconProps): JSX.Element;
+/**
+ * opencli 的标：包类型那一格用它；颜色写死的品牌物，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconOpencli({ size }: IconProps): JSX.Element;
+/**
+ * npm 的标：包类型那一格用它；保留品牌红，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconNpm({ size }: IconProps): JSX.Element;
+/**
+ * 四宫格："模块"这个概念的通用单色图标（侧栏、面板那颗钮、市场节的标题）；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconModules({ size }: IconProps): JSX.Element;
+/**
+ * 模块类型标：渐变方块 + 白四宫格，用在"这是个模块"的行首；品牌物，颜色不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconModuleMark({ size }: IconProps): JSX.Element;
+/**
+ * 面板 / 卡片那类的图标：整屏与柱状那种形状，给"面板"这一档用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export declare function IconPanelScreen({ size }: IconProps): JSX.Element;

package/dist/components/icons.js

@@ -2,15 +2,30 @@ import { h } from '../lib/react.js';
 function Shell({ size, strokeWidth = 1, viewBox = '0 0 16 16', children, }) {
     return (h("svg", { width: size, height: size, viewBox: viewBox, fill: "none", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", strokeWidth: strokeWidth, style: { display: 'block' } }, children));
 }
+/**
+ * 会话图标：一枚对话气泡，dsh 的图标表里没有，留给我们自己用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconConversation({ size = 16 }) {
     return (h(Shell, { size: size, strokeWidth: 1.3 },
         h("path", { d: "M2.5 7.2c0-2.3 2.1-4.2 4.8-4.2h1.4c2.7 0 4.8 1.9 4.8 4.2s-2.1 4.2-4.8 4.2H7.5l-3.2 2v-2.3c-1.1-.8-1.8-2-1.8-3.9Z", stroke: "currentColor", strokeLinejoin: "round" })));
 }
+/**
+ * 品牌标：侧栏顶上那枚工作台方块标；默认 24px（它是品牌物，别拿它当通用图标）。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconBrandMark({ size = 24 }) {
     return (h(Shell, { size: size, strokeWidth: 1.6, viewBox: "0 0 24 24" },
         h("rect", { x: 3, y: 3, width: 18, height: 18, rx: 5, stroke: "currentColor" }),
         h("path", { d: "M8 9.5h8M8 12.5h8M8 15.5h5", stroke: "currentColor", strokeLinecap: "round" })));
 }
+/**
+ * opencli 的标：包类型那一格用它；颜色写死的品牌物，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconOpencli({ size = 16 }) {
     return (h(Shell, { size: size, viewBox: "0 0 64 64" },
         h("defs", null,
@@ -21,10 +36,20 @@ export function IconOpencli({ size = 16 }) {
         h("rect", { width: 64, height: 64, rx: 14, fill: "#0a0a0f" }),
         h("text", { x: "50%", y: "54%", dominantBaseline: "middle", textAnchor: "middle", fontFamily: "monospace", fontWeight: 700, fontSize: 28, fill: "url(#opencli-mark)" }, ">_")));
 }
+/**
+ * npm 的标：包类型那一格用它；保留品牌红，不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconNpm({ size = 16 }) {
     return (h(Shell, { size: size, viewBox: "0 0 1024 1024" },
         h("path", { d: "M64 337.76h896v298.72H512v49.792H312.896v-49.824H64z m49.792 248.928h99.552v-149.376h49.76v149.344h49.792v-199.104H113.792z m248.896-199.136v248.928h99.552v-49.792h99.552v-199.136z m99.552 49.792H512v99.584h-49.792z m149.344-49.792v199.136h99.552v-149.376h49.792v149.344h49.792v-149.344h49.792v149.344h49.792v-199.104z", fill: "#CB3837" })));
 }
+/**
+ * 四宫格："模块"这个概念的通用单色图标（侧栏、面板那颗钮、市场节的标题）；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconModules({ size = 16 }) {
     return (h("svg", { width: size, height: size, viewBox: "0 0 16 16", fill: "none", "aria-hidden": "true" },
         h("rect", { x: "2.5", y: "2.5", width: "4.6", height: "4.6", rx: "1.2", stroke: "currentColor", strokeWidth: "1.2" }),
@@ -32,6 +57,11 @@ export function IconModules({ size = 16 }) {
         h("rect", { x: "2.5", y: "8.9", width: "4.6", height: "4.6", rx: "1.2", stroke: "currentColor", strokeWidth: "1.2" }),
         h("rect", { x: "8.9", y: "8.9", width: "4.6", height: "4.6", rx: "1.2", stroke: "currentColor", strokeWidth: "1.2" })));
 }
+/**
+ * 模块类型标：渐变方块 + 白四宫格，用在"这是个模块"的行首；品牌物，颜色不跟主题走。默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconModuleMark({ size = 16 }) {
     return (h(Shell, { size: size, viewBox: "0 0 24 24" },
         h("defs", null,
@@ -45,6 +75,11 @@ export function IconModuleMark({ size = 16 }) {
         h("rect", { x: "4.6", y: "13.2", width: "6.2", height: "6.2", rx: "1.9", fill: "#ffffff", fillOpacity: 0.78 }),
         h("rect", { x: "13.2", y: "13.2", width: "6.2", height: "6.2", rx: "1.9", fill: "#ffffff" })));
 }
+/**
+ * 面板 / 卡片那类的图标：整屏与柱状那种形状，给"面板"这一档用；默认 16px。
+ * @param props.size - 边长像素，同时给 `width` 与 `height`。
+ * @returns 一枚 `aria-hidden` 的 svg。
+ */
 export function IconPanelScreen({ size = 16 }) {
     return (h("svg", { width: size, height: size, viewBox: "0 0 1024 1024", fill: "currentColor", xmlns: "http://www.w3.org/2000/svg", "aria-hidden": "true", style: { display: 'block', overflow: 'hidden' } },
         h("path", { d: "M939 112c17.673 0 32 14.327 32 32v554.667c0 17.673-14.327 32-32 32l-394.5-0.001v96c0 3.74-0.642 7.331-1.82 10.668H768.4c17.673 0 32 14.326 32 32 0 17.496-14.042 31.712-31.47 31.995l-0.53 0.004H256.6c-17.673 0-32-14.327-32-32 0-17.496 14.042-31.713 31.47-31.995l0.53-0.005h225.721a31.923 31.923 0 0 1-1.817-10.137l-0.004-0.53v-96H86c-17.496 0-31.713-14.041-31.996-31.47l-0.004-0.53V144c0-17.673 14.327-32 32-32z m-32 64H118v490.666h789V176zM341.9 432c17.496 0 31.713 14.042 31.996 31.47l0.004 0.53v85.333c0 17.673-14.327 32-32 32-17.496 0-31.713-14.041-31.996-31.47l-0.004-0.53V464c0-17.673 14.327-32 32-32z m170.6-85.333c17.496 0 31.713 14.041 31.996 31.47l0.004 0.53v170.666c0 17.673-14.327 32-32 32-17.496 0-31.713-14.041-31.996-31.47l-0.004-0.53V378.667c0-17.673 14.327-32 32-32z m170.6-85.334c17.496 0 31.713 14.042 31.996 31.471l0.004 0.53v256c0 17.672-14.327 32-32 32-17.496 0-31.713-14.042-31.996-31.471l-0.004-0.53v-256c0-17.673 14.327-32 32-32z" })));

package/dist/config/constants.d.ts

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

package/dist/config/constants.js

@@ -1,43 +1,85 @@
+/** 外壳插件的包名：浏览器模块表与宿主按它注册、认领这枚插件。 */
 export const PLUGIN_ID = "@dsh-workbench/core";
+/** 与外壳同批发布的兄弟包名：`release.ts` 用它判一版三包是否都已在源上。 */
 export const RELEASE_SIBLINGS = [
     "@dsh-workbench/shared",
     "@dsh-workbench/module-tools",
 ];
+/** 外壳宿主 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"];

package/dist/config/storage.d.ts

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

package/dist/config/storage.js

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

package/dist/host/long-task.d.ts

@@ -10,24 +10,29 @@ export interface LongTaskBase {
     readonly why?: string | undefined;
     readonly startedAt: string;
     readonly at: string;
+    readonly session?: string | undefined;
 }
 export interface LongTaskStart {
     readonly workspace: string;
     readonly target: string;
     readonly payload?: unknown;
+    readonly session?: string | undefined;
 }
 export interface LongTaskChange<S extends LongTaskBase> {
     readonly kind: 'start' | 'step' | 'settle';
     readonly snapshot: S;
     readonly step?: LongTaskStep | undefined;
+    readonly by?: string | undefined;
 }
 export interface LongTaskDeps<S extends LongTaskBase> {
     readonly run: (options: {
         readonly payload: unknown;
         readonly onStep: (step: LongTaskStep) => void;
+        readonly signal: AbortSignal;
     }) => Promise<unknown>;
     readonly step?: ((step: LongTaskStep, current: S) => Partial<S>) | undefined;
     readonly outcome?: ((result: unknown, current: S) => Partial<S>) | undefined;
+    readonly stopped?: ((current: S) => Partial<S>) | undefined;
     readonly view: (snapshot: S) => Readonly<Record<string, unknown>>;
     readonly now?: (() => string) | undefined;
     readonly nextId?: (() => string) | undefined;
@@ -39,6 +44,7 @@ export interface LongTaskRegistry<S extends LongTaskBase> {
     snapshot(id: string): S | null;
     active(workspace: string, target: string): S | null;
     current(workspace: string): readonly Readonly<Record<string, unknown>>[];
+    stop(id: string, by?: string): boolean;
     onChange(listener: (change: LongTaskChange<S>) => void): () => void;
 }
 export declare function createLongTaskRegistry<S extends LongTaskBase>(deps: LongTaskDeps<S>): LongTaskRegistry<S>;
@@ -52,6 +58,7 @@ export declare function createLongTaskHost(options: {
     readonly scope: string;
     readonly unit: string;
     readonly bump: (facts: readonly string[]) => void;
+    readonly notify?: ((change: LongTaskChange<LongTaskBase>) => void) | undefined;
 }): {
     readonly host: LongTaskHost;
     dispose(): void;

package/dist/host/long-task.js

@@ -3,11 +3,18 @@ const LIVE = new Set(['running', 'needs-login']);
 const RECENT_MS = 10 * 60 * 1000;
 export function createLongTaskRegistry(deps) {
     const runs = new Map();
+    const controls = new Map();
     const now = deps.now ?? (() => new Date().toISOString());
     let counter = 0;
     const nextId = deps.nextId ?? (() => `run-${Date.now()}-${(counter += 1)}`);
     const recentMs = deps.recentMs ?? RECENT_MS;
     const listeners = new Set();
+    const live = (id) => {
+        const current = runs.get(id);
+        if (current === undefined || !LIVE.has(current.status))
+            return null;
+        return current;
+    };
     const notify = (change) => {
         for (const listener of [...listeners]) {
             try {
@@ -46,7 +53,7 @@ export function createLongTaskRegistry(deps) {
             return [...newest.values()]
                 .filter((snapshot) => LIVE.has(snapshot.status) || Date.parse(snapshot.at) >= floor)
                 .reverse()
-                .map((snapshot) => deps.view(snapshot));
+                .map((snapshot) => ({ ...deps.view(snapshot), id: snapshot.id }));
         },
         start(options) {
             const running = this.active(options.workspace, options.target);
@@ -63,11 +70,12 @@ export function createLongTaskRegistry(deps) {
                 steps: [],
                 startedAt,
                 at: startedAt,
+                ...(options.session === undefined ? {} : { session: options.session }),
             });
             notify({ kind: 'start', snapshot: runs.get(id) });
             const onStep = (step) => {
-                const current = runs.get(id);
-                if (current === undefined)
+                const current = live(id);
+                if (current === null)
                     return;
                 const steps = [...current.steps, `${step.kind === 'fail' ? '✗ ' : ''}${step.text}`].slice(-20);
                 const extra = deps.step?.(step, current) ?? {};
@@ -83,13 +91,21 @@ export function createLongTaskRegistry(deps) {
                     ...(current.status === 'needs-login' ? { loginUrl: undefined } : {}),
                 }, { kind: 'step', step });
             };
+            const control = new AbortController();
+            controls.set(id, control);
             void deps
-                .run({ payload: options.payload, onStep })
+                .run({ payload: options.payload, onStep, signal: control.signal })
                 .then((result) => {
-                const current = runs.get(id);
+                const current = live(id);
+                if (current === null)
+                    return;
+                controls.delete(id);
                 patch(id, { status: 'ok', ...(deps.outcome?.(result, current) ?? {}), loginUrl: undefined }, { kind: 'settle' });
             })
                 .catch((error) => {
+                if (live(id) === null)
+                    return;
+                controls.delete(id);
                 patch(id, {
                     status: 'failed',
                     why: error instanceof Error ? error.message : String(error),
@@ -98,6 +114,15 @@ export function createLongTaskRegistry(deps) {
             });
             return runs.get(id);
         },
+        stop(id, by) {
+            const current = live(id);
+            if (current === null)
+                return false;
+            controls.get(id)?.abort();
+            controls.delete(id);
+            patch(id, { ...(deps.stopped?.(current) ?? {}), status: 'stopped', loginUrl: undefined }, { kind: 'settle', by });
+            return true;
+        },
         snapshot(id) {
             return runs.get(id) ?? null;
         },
@@ -136,6 +161,7 @@ export function createLongTaskHost(options) {
                 offs.push(registry.onChange((change) => {
                     const named = [runsRouteOf(options.unit), ...(facts?.(change) ?? [])];
                     options.bump([...new Set(named)]);
+                    options.notify?.(change);
                 }));
                 return registry;
             },

package/dist/host/tool-approval.d.ts

@@ -29,6 +29,7 @@ export interface ApprovalCall {
     readonly name?: string | undefined;
     readonly arguments?: unknown;
     readonly workspace?: string | undefined;
+    readonly session?: string | undefined;
 }
 export type ApprovalVerdict = {
     readonly kind: 'read';

package/dist/host/unit-face.d.ts

@@ -7,6 +7,10 @@ import type { UnitCapability } from './unit-libs.js';
 import type { ApprovalCall, ApprovalFacts, ApprovalPolicy } from '../host/tool-approval.js';
 import type { ValueHandoff } from '../host/value-handoff.js';
 import type { WorkspaceStore } from '../host/workspace-store.js';
+export interface ToolScopeContext {
+    readonly workspace: string | null;
+    readonly preset: string | null;
+}
 export interface UnitMountDeps {
     readonly manifest: UnitManifest;
     readonly ctx: DshHostContext;
@@ -24,6 +28,7 @@ export interface UnitMountDeps {
         readonly force?: boolean;
     }) => Promise<UnitCapability | undefined>;
     readonly longTasks?: LongTaskHost | undefined;
+    readonly longTaskRuns?: (() => ReadonlyMap<string, LongTaskRegistry<LongTaskBase>>) | undefined;
 }
 export type ContextRenderer = (ref: {
     readonly kind: string;
@@ -40,7 +45,7 @@ export interface UnitMountResult {
     registerTools(): Array<() => void>;
     readonly factsOf?: ((call: UnitCall) => readonly string[] | undefined) | undefined;
     readonly gate?: {
-        deniedTools(workspace: string | null): readonly string[];
+        deniedTools(context: ToolScopeContext): readonly string[];
         subscribe(listener: () => void): () => void;
     };
     readonly context?: {

package/dist/i18n/en.d.ts

@@ -1,2 +1,3 @@
 import type { WorkbenchMessages } from './zh.js';
+/** 外壳自带的英文词表：键必须与 `zh` 逐一对应，值不许为空串。 */
 export declare const en: Record<keyof WorkbenchMessages, string>;

package/dist/i18n/en.js

@@ -1,3 +1,4 @@
+/** 外壳自带的英文词表：键必须与 `zh` 逐一对应，值不许为空串。 */
 export const en = {
     'brand.name': 'Workbench',
     'toggle.open': 'Open sidebar',
@@ -408,20 +409,19 @@ export const en = {
     'configSync.noSource': 'This machine has no other profile to sync from',
     'configSync.emptyProviders': 'The workbench has no model provider yet — sync the llm- rows from some profile, or configure one under Models.',
     'configSync.failed': 'The sync did not go through; try again.',
-    'debug.status': 'Workbench DIY debugging',
-    'debug.status.trouble': 'Workbench DIY debugging needs attention',
-    'debug.stalled': 'Workbench DIY debugging paused',
+    'debug.workspace': 'this workspace',
+    'debug.status': 'Debugging “{title}”',
+    'debug.status.trouble': 'Debugging needs your attention ({title})',
+    'debug.stalled': 'Debugging paused ({title})',
     'debug.act.pause': 'Pause debugging',
     'debug.act.resume': 'Resume debugging',
     'debug.act.stop': 'Stop debugging',
     'debug.act.stop.ask': 'Confirm stop',
-    'debug.card.here.title': 'Workbench DIY debugging is on',
+    'debug.card.here.title': 'Debugging “{title}”',
     'debug.card.here.note': 'Do not switch workspaces or touch the panel',
-    'debug.card.away.title': 'Workbench DIY debugging is on',
-    'debug.card.away.note': 'Switch to the Workbench DIY workspace',
+    'debug.card.away.note': 'Switch back to “{title}”',
     'debug.card.paused.note': 'Paused',
-    'debug.card.hidden.note': 'Switch to the Workbench panel',
-    'debug.back': 'Back to the workshop screen',
+    'debug.card.hidden.note': 'Switch back to the Workbench panel',
     'record.waiting': 'Recording handoff · your turn',
     'record.waiting.note': 'Press "Start recording" on that page, then "Stop recording" when done (it will not switch you back)',
     'record.recording': 'Recording',
@@ -436,4 +436,6 @@ export const en = {
     'approval.record.noUrl': 'no site given (this call gets refused)',
     'approval.record.oneAction': 'one action',
     'approval.record.noSwitch': 'it will not switch you back (the leftbar footer shows the state)',
+    'approval.longTask.what': 'Stops',
+    'approval.longTask.signal': 'stopping only sends an interrupt signal — how the platform-side run finishes is up to the module',
 };