@dsh-workbench/shared 0.1.0

package/src/api/__tests__/unit-board.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+import type { ModuleBlocker } from '../blocker';
+import type { CapabilityPayload } from '../workbench-contract';
+import { gateOf, probeKeyOf, splitBlocker } from '../unit-board';
+
+function capability(status: CapabilityPayload['status']): CapabilityPayload {
+  return { unit: 'issues', status, required: [], missing: [], detail: '测试用的结论' };
+}
+
+function blocker(id: string, severity: ModuleBlocker['severity']): ModuleBlocker {
+  return { id, severity, title: id, actions: [] };
+}
+
+describe('gateOf（能力门）', () => {
+  it('★ 还没探到（null）→ 照常取数：探测只是个前置检查，不许把卡片按住', () => {
+    expect(gateOf(null, 'capability')).toEqual({ gated: true });
+  });
+
+  it('ok → 取数；缺插件/缺命令 → 不取（那次平台读注定失败）', () => {
+    expect(gateOf(capability('ok'), 'capability')).toEqual({ gated: true });
+    expect(gateOf(capability('missing-plugin'), 'capability')).toEqual({ gated: false });
+    expect(gateOf(capability('missing-commands'), 'capability')).toEqual({ gated: false });
+  });
+
+  it('★ 探不动（unchecked）→ **照常取数**：那是"问不到"，不是"没装"（ADR-0016）', () => {
+    expect(gateOf(capability('unchecked'), 'capability')).toEqual({ gated: true });
+  });
+
+  it("mode: 'none' → 永远取数（套件自己决定不要这道门）", () => {
+    expect(gateOf(capability('missing-plugin'), 'none')).toEqual({ gated: true });
+    expect(gateOf(null, 'none')).toEqual({ gated: true });
+  });
+});
+
+describe('splitBlocker（一条阻断 + 至多一条提示）', () => {
+  it('没有候选 → 两条都没有', () => {
+    expect(splitBlocker([])).toEqual({});
+    expect(splitBlocker([undefined, undefined])).toEqual({});
+  });
+
+  it('★ 第一条 block 赢（一张卡上压两条阻断，用户不知道该按哪个）', () => {
+    const first = blocker('一', 'block');
+    const second = blocker('二', 'block');
+
+    expect(splitBlocker([first, second])).toEqual({ blocker: first });
+  });
+
+  it('只有 notice → 就是 notice（不拦人）', () => {
+    const notice = blocker('降级', 'notice');
+
+    expect(splitBlocker([undefined, notice])).toEqual({ notice });
+  });
+
+  it('★ 有阻断时丢掉提示：那一刻提示只是噪声', () => {
+    const block = blocker('缺插件', 'block');
+    const notice = blocker('降级', 'notice');
+
+    expect(splitBlocker([notice, block])).toEqual({ blocker: block });
+  });
+});
+
+describe('probeKeyOf（出错搭车强探的防抖键）', () => {
+  it('没有错误 → null（调用方据此不探）', () => {
+    expect(probeKeyOf(undefined)).toBeNull();
+  });
+
+  it('★ 键就是错误码：码没变就不再探（否则"错误 → 强探 → 仍然错误"会转圈）', () => {
+    expect(probeKeyOf({ code: 'auth-required', message: '未登录' })).toBe('auth-required');
+    expect(probeKeyOf({ code: 'auth-required', message: '未登录（另一个环境）' })).toBe('auth-required');
+    expect(probeKeyOf({ code: 'missing-plugin', message: '缺插件' })).toBe('missing-plugin');
+  });
+
+  it('空码给一个稳定的兜底键（不许变成"每次都算新错误"）', () => {
+    expect(probeKeyOf({ code: '', message: '没说什么' })).toBe('unknown');
+  });
+});

package/src/api/blocker-table.ts

@@ -0,0 +1,155 @@
+import type { Translate } from './dsh-client';
+import type { CapabilityPayload } from './workbench-contract';
+import type { ApiError } from './workbench-client';
+import type { BlockerAction, ModuleBlocker } from './blocker';
+import { shortenPath } from '../lib/ui.js';
+
+function retryAction(t: Translate): BlockerAction {
+  return { kind: 'retry', label: t('blocker.retry') };
+}
+
+function copyAction(t: Translate, text: string): BlockerAction {
+  return { kind: 'copy', label: t('blocker.copy'), text };
+}
+
+export function blockerOfError(
+  error: ApiError | undefined,
+  t: Translate,
+  context: { path?: string | null; platform?: string } = {},
+): ModuleBlocker {
+  if (error === undefined) {
+    return {
+      id: 'unknown',
+      severity: 'block',
+      title: t('blocker.unknown.title'),
+      actions: [retryAction(t)],
+    };
+  }
+
+  switch (error.code) {
+    case 'auth-required': {
+      const path = shortenPath(context.path ?? '');
+      void path;
+      const actions: BlockerAction[] =
+        error.helpUrl === undefined
+          ? [retryAction(t)]
+          : [
+              { kind: 'open-url', label: t('blocker.login.go'), url: error.helpUrl, inline: true },
+              retryAction(t),
+            ];
+      return {
+        id: 'auth-required',
+        severity: 'block',
+        title:
+          context.platform === undefined
+            ? t('blocker.login.titleGeneric')
+            : t('blocker.login.title', { platform: context.platform }),
+        hint: error.helpUrl === undefined ? t('blocker.login.manual') : t('blocker.login.hint'),
+        ...(error.detail === undefined ? {} : { detail: error.detail }),
+        actions,
+      };
+    }
+
+    case 'permission-denied': {
+      const actions: BlockerAction[] =
+        error.helpUrl === undefined
+          ? [retryAction(t)]
+          : [
+              { kind: 'open-url', label: t('blocker.forbidden.open'), url: error.helpUrl },
+              { kind: 'retry', label: t('blocker.retry') },
+            ];
+      return {
+        id: 'permission-denied',
+        severity: 'block',
+        title:
+          context.platform === undefined
+            ? t('blocker.forbidden.titleGeneric')
+            : t('blocker.forbidden.title', { platform: context.platform }),
+        hint: t('blocker.forbidden.hint'),
+        ...(error.detail === undefined ? {} : { detail: error.detail }),
+        actions,
+      };
+    }
+
+    case 'cli-timeout':
+      return {
+        id: 'cli-timeout',
+        severity: 'notice',
+        title: error.message,
+        hint: error.hint ?? t('blocker.timeout.hint'),
+        ...(error.detail === undefined ? {} : { detail: error.detail }),
+        actions: [retryAction(t)],
+      };
+
+    case 'cli-exec-failed':
+      return {
+        id: 'cli-exec-failed',
+        severity: 'block',
+        title: error.message,
+        hint: error.hint ?? t('blocker.exec.hint'),
+        ...(error.detail === undefined ? {} : { detail: error.detail }),
+        actions: [retryAction(t)],
+      };
+
+    default:
+      return {
+        id: error.code,
+        severity: 'block',
+        title: error.message,
+        ...(error.hint === undefined ? {} : { hint: error.hint }),
+        ...(error.detail === undefined ? {} : { detail: error.detail }),
+        actions: [retryAction(t)],
+      };
+  }
+}
+
+export function blockerOfCapability(capability: CapabilityPayload, t: Translate): ModuleBlocker | undefined {
+  if (capability.status === 'ok') return undefined;
+
+  const fixAction: BlockerAction | undefined =
+    capability.fix === undefined
+      ? undefined
+      : {
+          kind: 'run-fix',
+          label: capability.fix === 'install' ? t('blocker.fix.install') : t('blocker.fix.update'),
+          unit: capability.unit,
+          fix: capability.fix,
+        };
+  const sourceUnknown = capability.fix === undefined && capability.install !== undefined && capability.install !== 'ready';
+  const install: readonly BlockerAction[] = [
+    ...(fixAction === undefined ? [] : [fixAction]),
+    ...(sourceUnknown ? [{ kind: 'open-market' as const, label: t('blocker.market.open'), unit: capability.unit }] : []),
+    ...(capability.command === undefined || sourceUnknown ? [] : [copyAction(t, capability.command)]),
+  ];
+
+  if (capability.status === 'missing-plugin') {
+    return {
+      id: 'unit-missing-plugin',
+      severity: 'block',
+      title: t('env.unit.missingPlugin'),
+      hint: t('env.unit.hint'),
+      ...(capability.detail === undefined ? {} : { detail: capability.detail }),
+      actions: [...install, retryAction(t)],
+    };
+  }
+
+  if (capability.status === 'missing-commands') {
+    return {
+      id: 'unit-missing-commands',
+      severity: 'block',
+      title: t('env.unit.missingCommands'),
+      hint: t('env.unit.missingCommandsHint'),
+      ...(capability.detail === undefined ? {} : { detail: capability.detail }),
+      actions: [...install, retryAction(t)],
+    };
+  }
+
+  return {
+    id: 'unit-unchecked',
+    severity: 'notice',
+    title: t('env.unit.unchecked'),
+    hint: t('env.unit.uncheckedHint'),
+    ...(capability.detail === undefined ? {} : { detail: capability.detail }),
+    actions: [retryAction(t)],
+  };
+}

package/src/api/blocker.ts

@@ -0,0 +1,25 @@
+export type BlockerAction =
+  | {
+      readonly kind: 'open-url';
+      readonly label: string;
+      readonly url: string;
+      readonly inline?: boolean;
+    }
+  | { readonly kind: 'copy'; readonly label: string; readonly text: string }
+  | { readonly kind: 'retry'; readonly label: string }
+  | {
+      readonly kind: 'run-fix';
+      readonly label: string;
+      readonly unit: string;
+      readonly fix: 'install' | 'update';
+    }
+  | { readonly kind: 'open-market'; readonly label: string; readonly unit: string };
+
+export interface ModuleBlocker {
+  readonly id: string;
+  readonly severity: 'block' | 'notice';
+  readonly title: string;
+  readonly hint?: string;
+  readonly detail?: string;
+  readonly actions: readonly BlockerAction[];
+}

package/src/api/context-ref.ts

@@ -0,0 +1,47 @@
+export const CONTEXT_MARKER_NAME = '工作台';
+
+export interface ContextRef {
+  readonly kind: string;
+  readonly parts: readonly string[];
+}
+
+const MARKER = new RegExp(`@${CONTEXT_MARKER_NAME}:([a-z][a-z0-9-]*:[A-Za-z0-9._~%#/-]+)`, 'g');
+
+const TRAILING_PUNCTUATION = /[.,;:!?]+$/;
+
+export function encodeRef(ref: ContextRef): string {
+  return `${ref.kind}:${ref.parts.join('/')}`;
+}
+
+export function decodeRef(text: string): ContextRef | undefined {
+  const at = text.indexOf(':');
+  if (at <= 0 || at === text.length - 1) return undefined;
+  const kind = text.slice(0, at);
+  if (!/^[a-z][a-z0-9-]*$/.test(kind)) return undefined;
+  const parts = text.slice(at + 1).split('/').filter((part) => part !== '');
+  if (parts.length === 0) return undefined;
+  return { kind, parts };
+}
+
+export function markerBody(encoded: string): string {
+  return `${CONTEXT_MARKER_NAME}:${encoded}`;
+}
+
+export function buildMarker(ref: ContextRef): string {
+  return `@${markerBody(encodeRef(ref))}`;
+}
+
+export function parseMarkers(text: string): ContextRef[] {
+  const seen = new Set<string>();
+  const refs: ContextRef[] = [];
+  for (const match of String(text ?? '').matchAll(MARKER)) {
+    const raw = match[1].replace(TRAILING_PUNCTUATION, '');
+    const ref = decodeRef(raw);
+    if (ref === undefined) continue;
+    const key = encodeRef(ref);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    refs.push(ref);
+  }
+  return refs;
+}

package/src/api/dsh-client.ts

@@ -0,0 +1,176 @@
+import type { ReactNode } from 'react';
+
+export interface WorkspaceView {
+  readonly workspaceId: string;
+  readonly path: string;
+  readonly title: string;
+  readonly sessionIds: readonly string[];
+  readonly createdAt: number;
+  readonly updatedAt: number;
+}
+
+export interface WorkspaceSnapshot {
+  readonly items: readonly WorkspaceView[];
+  readonly archivedSessionIds: readonly string[];
+  readonly pinnedSessionIds: readonly string[];
+}
+
+export interface SessionSummary {
+  readonly id: string;
+  readonly displayTitle: string;
+  readonly blank: boolean;
+  readonly running: boolean;
+  readonly updatedAt: number;
+  readonly origin?: string;
+  readonly retainedBy: Readonly<Partial<Record<string, number>>>;
+}
+
+export interface SubagentCatalogEntry {
+  readonly id: string;
+}
+
+export interface SessionsSnapshot {
+  readonly byId: Readonly<Record<string, SessionSummary>>;
+  readonly projectionsBySession: Readonly<
+    Record<string, { values?: { subagentCatalog?: readonly SubagentCatalogEntry[] } } | undefined>
+  >;
+}
+
+export interface SessionStatus {
+  readonly running?: boolean;
+  readonly completionUnread?: boolean;
+  readonly pendingInteraction?: { readonly kind?: string };
+}
+
+export type SessionStatusSnapshot = ReadonlyMap<string, SessionStatus>;
+
+export interface PanelInfo {
+  readonly activePanelId: string | null;
+}
+
+export interface PanelEntry {
+  readonly id: string;
+  readonly order: number;
+  readonly label: string | (() => string);
+}
+
+export type SnapshotSelectorHook<T> = <R>(selector: (state: T) => R) => R;
+
+export type RenderSlot = (
+  key: string,
+  owner?: Record<string, unknown>,
+  options?: { fallback?: ReactNode; hookContext?: unknown; only?: string },
+) => ReactNode;
+
+export type Translate = (key: string, params?: Record<string, unknown>) => string;
+
+export interface SlotRegisterOptions {
+  name: string;
+  priority?: number;
+  key?: string;
+  id?: string;
+  order?: number;
+  locale?: string;
+  label?: string | (() => string);
+  children?: Record<string, unknown>;
+  inject?: (scope?: unknown) => Record<string, unknown>;
+}
+
+export interface DshSlots {
+  inject(name: string, callback: () => void | (() => void) | Iterable<() => void>): () => void;
+  register(options: SlotRegisterOptions, component: unknown): () => void;
+  entriesOfSlot(name: string): Array<{ options: SlotRegisterOptions }>;
+  subscribe(name: string, callback: () => void): () => void;
+  specDynamic?(name: string): unknown;
+  onMutate?(callback: (name: string) => void): () => void;
+}
+
+export interface DshLocale {
+  register(namespace: string, dictionaries: Record<string, Record<string, string>>): () => void;
+  bind(namespace: string): Translate;
+}
+
+export interface DshLayout {
+  selectPanel(panelId: string | null): void;
+  toggleSidebar(): void;
+  openRightbar(track: boolean, fullscreen: boolean): void;
+  closeRightbar(): void;
+  readonly panels?: DshLayoutPanels;
+}
+
+export interface DshLayoutPanels {
+  setRightbar?(px: number): void;
+}
+
+export interface DshShortcutCatalog {
+  readonly catalog: unknown;
+}
+
+export interface DshUiWorkspace {
+  openWorkspace(workspaceId: string): Promise<unknown>;
+  openSession(sessionId: string): void;
+  startSession(workspaceId: string): void;
+  pickDirectory(): Promise<string | null>;
+}
+
+export interface DshWorkspaces {
+  create(request: { path: string }): Promise<{ workspaceId?: string } | undefined>;
+}
+
+export interface DshReferenceInsert {
+  readonly source: string;
+  readonly ref: string;
+  readonly label: string;
+  readonly appearance?: 'session' | 'file' | 'folder';
+  readonly clipboardText: string;
+}
+
+export interface DshTokenSpan {
+  readonly start: number;
+  readonly end: number;
+  readonly draftRev: number;
+}
+
+export interface DshSessionInput {
+  caretSpan?: () => { start: number; end: number };
+  readonly state: { getSnapshot(): { draftRev: number } | undefined };
+  insertReference(ref: DshReferenceInsert, span: DshTokenSpan): boolean;
+  notify(level: 'info' | 'error', text: string): void;
+}
+
+export interface DshInputTriggers {
+  registerSource(source: {
+    readonly trigger: '@';
+    readonly name: string;
+    readonly order?: number;
+    candidates: () => Promise<readonly unknown[]>;
+    onPick: () => undefined;
+    lexicon?: (session: unknown) => readonly string[] | undefined;
+    subscribeLexicon?: (session: unknown, listener: () => void) => () => void;
+    readonly codec?: {
+      clipboardText(ref: string): string;
+      serialize(ref: string, signal?: AbortSignal): Promise<string>;
+    };
+  }): () => void;
+}
+
+export interface DshConversationService {
+  readonly input: { for(actx: unknown): DshSessionInput };
+}
+
+export interface DshSessionsService {
+  readonly list: { getSnapshot(): SessionsSnapshot };
+  scope(sessionId: string): unknown | undefined;
+}
+
+export interface DshClientContext {
+  get<T = unknown>(name: string): T | undefined;
+  provide(name: string, value: unknown): void;
+  effect(effect: () => void | (() => void), label?: string): () => void;
+  readonly slots: DshSlots;
+  readonly locale: DshLocale;
+  readonly layout: DshLayout;
+  readonly uiWorkspace: DshUiWorkspace;
+  readonly workspaces: DshWorkspaces;
+  readonly shortcuts: DshShortcutCatalog;
+}

package/src/api/dsh.ts

@@ -0,0 +1,156 @@
+export interface DshLogger {
+  info?(message: string): void;
+  warn?(message: string): void;
+}
+
+export interface DshRequest {
+  readonly method?: string;
+  readonly url?: string;
+  [Symbol.asyncIterator]?(): AsyncIterator<Uint8Array>;
+}
+
+export interface DshResponse {
+  statusCode: number;
+  setHeader(name: string, value: string): void;
+  end(body?: string): void;
+  writeHead?(status: number, headers: Record<string, string>): void;
+  write?(chunk: string): void;
+  on?(event: 'close', listener: () => void): void;
+}
+
+export interface DshWebRoute {
+  readonly kind: 'prefix' | 'exact';
+  readonly path: string;
+  readonly handler: (req: DshRequest, res: DshResponse) => void | Promise<void>;
+}
+
+export interface DshProfileContext {
+  readonly dir?: string;
+}
+
+export interface DshToolSchema {
+  readonly name: string;
+  readonly [key: string]: unknown;
+}
+
+export interface DshPromptAssembly {
+  readonly tools?: readonly DshToolSchema[] | undefined;
+  readonly [key: string]: unknown;
+}
+
+export interface DshAssemblyContext {
+  readonly agent?: unknown;
+  readonly scope?: unknown;
+  readonly [key: string]: unknown;
+}
+
+export interface DshHostContext {
+  on?: {
+    (
+      event: 'system-prompt/assemble',
+      listener: (
+        assembly: DshPromptAssembly,
+        context: DshAssemblyContext,
+        next: () => Promise<DshPromptAssembly>,
+      ) => Promise<DshPromptAssembly>,
+    ): (() => void) | undefined;
+  } & {
+    (
+      event: 'tools/pre-execute',
+      listener: (
+        exec: {
+          name?: string;
+          arguments?: unknown;
+          readonly agent?: DshToolRunContext['agent'];
+        },
+        next: () => Promise<
+          | { kind: 'allow' }
+          | { kind: 'deny'; reason: string }
+          | { kind: 'cancel' }
+          | { kind: 'ask'; reason?: string; displayReason?: Record<string, string> }
+        >,
+      ) => Promise<
+        | { kind: 'allow' }
+        | { kind: 'deny'; reason: string }
+        | { kind: 'cancel' }
+        | { kind: 'ask'; reason?: string; displayReason?: Record<string, string> }
+      >,
+    ): (() => void) | undefined;
+  } & {
+    (
+      event: 'tools/post-execute',
+      listener: (
+        exec: { name?: string; arguments?: unknown },
+        result: unknown,
+        next: () => unknown,
+      ) => unknown,
+    ): (() => void) | undefined;
+  } & {
+    (
+      event: 'agent/created',
+      listener: (payload: { agent?: unknown }) => void,
+    ): (() => void) | undefined;
+  } & {
+    (
+      event: 'agent/pre-step',
+      listener: (
+        payload: { agent?: unknown; messages?: readonly unknown[] },
+        next: () => Promise<{ kind: string; messages?: readonly unknown[] }>,
+      ) => Promise<{ kind: string; messages?: readonly unknown[] }>,
+    ): (() => void) | undefined;
+  };
+  get<T = unknown>(name: string): T | undefined;
+  provide(name: string, value: unknown): () => void;
+  effect(effect: () => void | (() => void), label?: string): () => void;
+  readonly logger?: DshLogger;
+  readonly webServer: { register(route: DshWebRoute): () => void };
+}
+
+export interface DshShellExecution {
+  result(): Promise<{
+    exitCode: number | null;
+    timedOut: boolean;
+    aborted: boolean;
+    stdout: { text: string; truncated: boolean };
+    stderr: { text: string; truncated: boolean };
+  }>;
+}
+
+export interface DshShell {
+  resolve(request: {
+    command: string;
+    workdir?: string;
+    timeoutMs?: number;
+    onExpiry?: 'kill' | 'none';
+    stdoutMaxBytes?: number;
+    signal?: AbortSignal;
+  }): unknown;
+  execute(spec: unknown): Promise<DshShellExecution>;
+}
+
+export interface DshWorkspaceRegistry {
+  get(id: string): { id: string; path?: string; title?: string } | undefined;
+}
+
+export interface DshToolDefinition {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  output: {
+    schema: Record<string, unknown>;
+    render(args: unknown, value: unknown): Array<Record<string, unknown>>;
+  };
+  execute(args: any, exec: DshToolRunContext): Promise<unknown>;
+}
+
+export interface DshToolRunContext {
+  readonly agent?:
+    | {
+        readonly session?: { readonly header?: { readonly cwd?: string } | undefined } | undefined;
+      }
+    | undefined;
+}
+
+export interface DshToolRegistry {
+  register(definition: DshToolDefinition): () => void;
+}