@dsh-workbench/shared 0.3.4 → 0.3.6

package/src/host/__tests__/long-task.test.ts

@@ -0,0 +1,264 @@
+import { describe, expect, it } from 'vitest';
+import type { LongTaskStep } from '../../api/long-task.js';
+import {
+  createLongTaskHost,
+  createLongTaskRegistry,
+  sharedLongTaskRegistry,
+  type LongTaskBase,
+  type LongTaskDeps,
+} from '../long-task.js';
+
+interface Probe extends LongTaskBase {
+  readonly note?: string | undefined;
+}
+
+function harness(over: Partial<LongTaskDeps<Probe>> = {}) {
+  let signal: AbortSignal | undefined;
+  let step: ((step: LongTaskStep) => void) | undefined;
+  let settle: ((result: unknown) => void) | undefined;
+  let fail: ((error: unknown) => void) | undefined;
+  const base: LongTaskDeps<Probe> = {
+    now: () => '2026-10-21T02:00:00.000Z',
+    run: (options) =>
+      new Promise((resolve, reject) => {
+        signal = options.signal;
+        step = options.onStep;
+        settle = resolve as (result: unknown) => void;
+        fail = reject as (error: unknown) => void;
+      }),
+    view: (snapshot) => ({ target: snapshot.target, status: snapshot.status, note: snapshot.note }),
+  };
+  return {
+    deps: { ...base, ...over },
+    signal: () => signal,
+    step: (one: LongTaskStep) => step?.(one),
+    done: (result: unknown) => settle?.(result),
+    boom: (error: unknown) => fail?.(error),
+  };
+}
+
+const flush = async (): Promise<void> => {
+  await Promise.resolve();
+  await Promise.resolve();
+};
+
+describe('createLongTaskRegistry.stop（停止只是转发给生产方，认不认 signal 是模块的事）', () => {
+  it('★★ stop：run 拿到的 signal 被 abort，这一趟变 stopped，回 true', () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    const started = runs.start({ workspace: '/w/a', target: 'release' });
+
+    expect(h.signal()?.aborted).toBe(false);
+    expect(runs.stop(started.id)).toBe(true);
+    expect(h.signal()?.aborted).toBe(true);
+    expect(runs.snapshot(started.id)?.status).toBe('stopped');
+  });
+
+  it('★★ 结算首胜：停过之后 run 再 resolve 也不许翻案（还是 stopped，不是 ok）', async () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    const started = runs.start({ workspace: '/w/a', target: 'release' });
+
+    runs.stop(started.id);
+    h.done({ anything: true });
+    await flush();
+
+    expect(runs.snapshot(started.id)?.status).toBe('stopped');
+  });
+
+  it('★★ 被 abort 的 run 常常 reject（AbortError）：那一趟不许变成 failed', async () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    const started = runs.start({ workspace: '/w/a', target: 'release' });
+
+    runs.stop(started.id);
+    h.boom(new Error('This operation was aborted'));
+    await flush();
+
+    expect(runs.snapshot(started.id)?.status).toBe('stopped');
+    expect(runs.snapshot(started.id)?.why).toBeUndefined();
+  });
+
+  it('★★ 不是活的：已收尾 / 不认识的 id ⇒ 回 false，什么都没变', async () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    const started = runs.start({ workspace: '/w/a', target: 'release' });
+
+    h.done({});
+    await flush();
+
+    expect(runs.stop(started.id)).toBe(false);
+    expect(runs.snapshot(started.id)?.status).toBe('ok');
+    expect(runs.stop('run-nope')).toBe(false);
+    expect(runs.current('/w/a')).toHaveLength(1);
+  });
+
+  it('★★ 停这一下走 deps.stopped（与 outcome 之于 ok 同形：停在哪、文案怎么写是模块的知识）', () => {
+    const h = harness({ stopped: () => ({ note: '用户按停的' }) });
+    const runs = createLongTaskRegistry(h.deps);
+    const started = runs.start({ workspace: '/w/a', target: 'release' });
+
+    runs.stop(started.id);
+
+    expect(runs.snapshot(started.id)?.note).toBe('用户按停的');
+  });
+
+  it('★ 等你登录时也能停：登录地址跟着清掉', () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    const started = runs.start({ workspace: '/w/a', target: 'release' });
+
+    h.step({ kind: 'start', text: '未登录', loginUrl: 'https://x/login' });
+    expect(runs.snapshot(started.id)?.status).toBe('needs-login');
+
+    expect(runs.stop(started.id)).toBe(true);
+    expect(runs.snapshot(started.id)?.status).toBe('stopped');
+    expect(runs.snapshot(started.id)?.loginUrl).toBeUndefined();
+  });
+
+  it('★ 停过之后迟到的步骤也不进这一趟（结算首胜）', () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    const started = runs.start({ workspace: '/w/a', target: 'release' });
+
+    runs.stop(started.id);
+    h.step({ kind: 'info', text: '迟到一步' });
+
+    expect(runs.snapshot(started.id)?.steps).toEqual([]);
+    expect(runs.snapshot(started.id)?.status).toBe('stopped');
+  });
+
+  it('★★ current() 每条都带 id（浏览器按 id 点那颗钮），view 覆盖不了', () => {
+    const h = harness({ view: (snapshot) => ({ id: 'spoofed', status: snapshot.status }) });
+    const runs = createLongTaskRegistry({ ...h.deps, nextId: () => 'run-1' });
+    const started = runs.start({ workspace: '/w/a', target: 'release' });
+
+    const [row] = runs.current('/w/a');
+
+    expect(started.id).toBe('run-1');
+    expect(row?.['id']).toBe('run-1');
+  });
+});
+
+describe('sharedLongTaskRegistry（那一份跨热重载存活）', () => {
+  it('★★ 槽里那份**上一版的注册表**（四个方法、没有 stop）仍被认回：升级那次重载不重建空表', () => {
+    const scope = `test-${String(Date.now())}-${Math.random()}`;
+    const slot = Symbol.for(`dsh-workbench:long-task:${scope}:demo`);
+    const stale = {
+      start: () => undefined,
+      snapshot: () => null,
+      active: () => null,
+      current: () => [],
+      onChange: () => () => {},
+    };
+    (globalThis as unknown as Record<symbol, unknown>)[slot] = stale;
+
+    const again = sharedLongTaskRegistry(scope, 'demo', harness().deps);
+
+    expect(again).toBe(stale);
+    expect(Object.hasOwn(again, 'stop')).toBe(false);
+  });
+
+  it('★ 认不出（热重载换了接口）⇒ 重造，槽里换成新表', () => {
+    const scope = `test-${String(Date.now())}-${Math.random()}`;
+    const slot = Symbol.for(`dsh-workbench:long-task:${scope}:demo`);
+    const stale = {
+      start: () => undefined,
+      snapshot: () => null,
+      active: () => null,
+    };
+    (globalThis as unknown as Record<symbol, unknown>)[slot] = stale;
+
+    const fresh = sharedLongTaskRegistry(scope, 'demo', harness().deps);
+
+    expect(fresh).not.toBe(stale);
+    expect((globalThis as unknown as Record<symbol, unknown>)[slot]).toBe(fresh);
+    expect(typeof fresh.stop).toBe('function');
+  });
+});
+
+describe('来源会话（谁的这一趟，决定停它要不要审批）', () => {
+  it('★★ start 把来源会话记进快照', () => {
+    const h = harness();
+    const runs = createLongTaskRegistry({ ...h.deps, nextId: () => 'run-1' });
+    const started = runs.start({ workspace: '/w/a', target: 'release', session: 's-1' });
+
+    expect(started.session).toBe('s-1');
+    expect(runs.snapshot('run-1')?.session).toBe('s-1');
+  });
+
+  it('★★ 不给来源 ⇒ 快照里连 session 这个键都没有（别把 undefined 塞进去）', () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    const started = runs.start({ workspace: '/w/a', target: 'release' });
+
+    expect(started.session).toBeUndefined();
+    expect(Object.keys(runs.snapshot(started.id) ?? {})).not.toContain('session');
+  });
+
+  it('★★ stop(id, by)：谁按的落在那条 settle 通知上', () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    const seen: Array<{ kind: string; by: string | undefined; status: string }> = [];
+    runs.onChange((change) => {
+      seen.push({ kind: change.kind, by: change.by, status: change.snapshot.status });
+    });
+    const started = runs.start({ workspace: '/w/a', target: 'release', session: 's-1' });
+
+    expect(runs.stop(started.id, 's-2')).toBe(true);
+
+    expect(seen).toEqual([
+      { kind: 'start', by: undefined, status: 'running' },
+      { kind: 'settle', by: 's-2', status: 'stopped' },
+    ]);
+  });
+
+  it('★★ stop(id) 不给 by ⇒ 通知里的 by 是 undefined（界面上按的用户）', () => {
+    const h = harness();
+    const runs = createLongTaskRegistry(h.deps);
+    let settleBy: string | undefined = 'sentinel';
+    runs.onChange((change) => {
+      if (change.kind === 'settle') settleBy = change.by;
+    });
+    const started = runs.start({ workspace: '/w/a', target: 'release' });
+
+    expect(runs.stop(started.id)).toBe(true);
+    expect(settleBy).toBeUndefined();
+  });
+});
+
+describe('createLongTaskHost 的 notify（每次变更都叫一下，bump 那半照旧）', () => {
+  it('★★ 起 / 走一步 / 被停 三次都叫 notify；停那笔带着谁按的', () => {
+    const bumps: string[][] = [];
+    const seen: string[] = [];
+    const box = createLongTaskHost({
+      scope: `test-${String(Date.now())}-${Math.random()}`,
+      unit: 'demo',
+      bump: (facts) => bumps.push([...facts]),
+      notify: (change) => seen.push(`${change.kind}:${change.snapshot.status}:${change.by ?? '-'}`),
+    });
+    const h = harness();
+    const runs = box.host.create({ key: 'release', ...h.deps, nextId: () => 'run-1' });
+
+    runs.start({ workspace: '/w/a', target: 'release', session: 's-1' });
+    h.step({ kind: 'start', text: '走一步' });
+
+    expect(runs.stop('run-1', 's-1')).toBe(true);
+    expect(seen).toEqual(['start:running:-', 'step:running:-', 'settle:stopped:s-1']);
+    expect(bumps).toEqual([['demo/runs'], ['demo/runs'], ['demo/runs']]);
+  });
+
+  it('★ 没给 notify 也照常跑（老调用点不受影响）', () => {
+    const bumps: string[][] = [];
+    const box = createLongTaskHost({
+      scope: `test-${String(Date.now())}-${Math.random()}`,
+      unit: 'demo',
+      bump: (facts) => bumps.push([...facts]),
+    });
+    const h = harness();
+
+    box.host.create({ key: 'release', ...h.deps }).start({ workspace: '/w/a', target: 'release' });
+
+    expect(bumps).toEqual([['demo/runs']]);
+  });
+});

package/src/host/long-task.ts

@@ -15,27 +15,32 @@ 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;
@@ -48,17 +53,25 @@ 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 function createLongTaskRegistry<S extends LongTaskBase>(deps: LongTaskDeps<S>): LongTaskRegistry<S> {
   const runs = new Map<string, LongTaskBase>();
+  const controls = new Map<string, AbortController>();
   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<(change: LongTaskChange<S>) => void>();
 
+  const live = (id: string): S | null => {
+    const current = runs.get(id);
+    if (current === undefined || !LIVE.has(current.status)) return null;
+    return current as S;
+  };
+
   const notify = (change: LongTaskChange<S>): void => {
     for (const listener of [...listeners]) {
       try {
@@ -97,7 +110,7 @@ export function createLongTaskRegistry<S extends LongTaskBase>(deps: LongTaskDep
           (snapshot) => LIVE.has(snapshot.status) || Date.parse(snapshot.at) >= floor,
         )
         .reverse()
-        .map((snapshot) => deps.view(snapshot as S));
+        .map((snapshot) => ({ ...deps.view(snapshot as S), id: snapshot.id }));
     },
 
     start(options) {
@@ -114,14 +127,15 @@ export function createLongTaskRegistry<S extends LongTaskBase>(deps: LongTaskDep
         steps: [],
         startedAt,
         at: startedAt,
+        ...(options.session === undefined ? {} : { session: options.session }),
       });
       notify({ kind: 'start', snapshot: runs.get(id) as S });
 
       const onStep = (step: LongTaskStep): void => {
-        const current = runs.get(id);
-        if (current === undefined) return;
+        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 as S) ?? {};
+        const extra = deps.step?.(step, current) ?? {};
         if (step.loginUrl !== undefined) {
           patch(
             id,
@@ -143,17 +157,24 @@ export function createLongTaskRegistry<S extends LongTaskBase>(deps: LongTaskDep
         );
       };
 
+      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 as S) ?? {}), loginUrl: undefined },
+            { status: 'ok', ...(deps.outcome?.(result, current) ?? {}), loginUrl: undefined },
             { kind: 'settle' },
           );
         })
         .catch((error: unknown) => {
+          if (live(id) === null) return;
+          controls.delete(id);
           patch(
             id,
             {
@@ -168,6 +189,19 @@ export function createLongTaskRegistry<S extends LongTaskBase>(deps: LongTaskDep
       return runs.get(id) as S;
     },
 
+    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) as S | undefined) ?? null;
     },
@@ -212,6 +246,7 @@ export 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 } {
   const offs: Array<() => void> = [];
   return {
@@ -223,6 +258,7 @@ export function createLongTaskHost(options: {
           registry.onChange((change) => {
             const named = [runsRouteOf(options.unit), ...(facts?.(change) ?? [])];
             options.bump([...new Set(named)]);
+            options.notify?.(change);
           }),
         );
         return registry;

package/src/host/tool-approval.ts

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

package/src/host/unit-face.ts

@@ -8,6 +8,11 @@ import type { ApprovalCall, ApprovalFacts, ApprovalPolicy } from '../host/tool-a
 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;
@@ -23,6 +28,7 @@ export interface UnitMountDeps {
     options?: { readonly force?: boolean },
   ) => Promise<UnitCapability | undefined>;
   readonly longTasks?: LongTaskHost | undefined;
+  readonly longTaskRuns?: (() => ReadonlyMap<string, LongTaskRegistry<LongTaskBase>>) | undefined;
 }
 
 export type ContextRenderer = (ref: {
@@ -43,7 +49,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/src/i18n/en.ts

@@ -1,5 +1,6 @@
 import type { WorkbenchMessages } from './zh.js';
 
+/** 外壳自带的英文词表：键必须与 `zh` 逐一对应，值不许为空串。 */
 export const en: Record<keyof WorkbenchMessages, string> = {
   'brand.name': 'Workbench',
 
@@ -423,20 +424,19 @@ export const en: Record<keyof WorkbenchMessages, string> = {
   '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',
@@ -451,4 +451,7 @@ export const en: Record<keyof WorkbenchMessages, string> = {
   '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',
 };

package/src/i18n/index.ts

@@ -1,10 +1,13 @@
 import { en } from './en.js';
 import { zh, type WorkbenchMessages } from './zh.js';
 
+/** 外壳自带的两份词表（`zh` 为基准、`en` 同构）：`client.tsx` 拿它当合并各套件词表的底座。 */
 export const dictionaries = { zh, en };
 
+/** 中文词表的键类型（从 `zh.ts` 转出）：`en` 与模块词表都得覆盖同一批键。 */
 export type { WorkbenchMessages };
 
+/** 一份按语言分的词表：`zh` / `en` 必须同键，另可带模块自己那份语言。 */
 export interface Dictionaries {
   readonly zh: Readonly<Record<string, string>>;
   readonly en: Readonly<Record<string, string>>;

package/src/i18n/merge.ts

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

package/src/i18n/zh.ts

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

package/src/index.ts

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

package/src/lib/blocker-action.ts

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