@dsh-workbench/shared 0.1.0

package/src/host/tool-kit.ts

@@ -0,0 +1,56 @@
+import type { DshToolRunContext } from '../api/dsh.js';
+import { WorkbenchDataError } from './opencli';
+
+export function sessionWorkspace(exec: DshToolRunContext | undefined): string | null {
+  const cwd = exec?.agent?.session?.header?.cwd;
+  return typeof cwd === 'string' && cwd.trim() !== '' ? cwd.trim() : null;
+}
+
+export function textOutput(text: string): Array<Record<string, unknown>> {
+  return [{ type: 'text', text }];
+}
+
+export function textRender(_args: unknown, value: unknown): Array<Record<string, unknown>> {
+  const text = (value as { text?: unknown } | null)?.text;
+  return textOutput(typeof text === 'string' ? text : JSON.stringify(value));
+}
+
+export const TEXT_OUTPUT = { schema: { type: 'object', properties: {}, additionalProperties: true }, render: textRender };
+
+export function jsonText(value: unknown): string {
+  return JSON.stringify(value);
+}
+
+const UNCLASSIFIED = 'cli-unclassified';
+
+export interface CommandHintNames {
+  readonly plugin: string;
+  readonly suiteId: string;
+}
+
+export type CommandHint = <T>(command: string, run: () => Promise<T>) => Promise<T>;
+
+export function commandHintFor(names: CommandHintNames): CommandHint {
+  return async (command, run) => {
+    try {
+      return await run();
+    } catch (error) {
+      if (!(error instanceof WorkbenchDataError) || error.code !== UNCLASSIFIED) throw error;
+
+      const advice =
+        `这条命令（${command}）在这份 ${names.plugin} 插件里可能不存在（插件版本旧就会缺）：` +
+        `用 workbench_modules（action=update, id=${names.suiteId}）升级插件，或在面板的模块状态里点更新，再重试。`;
+
+      throw new WorkbenchDataError(error.code, `${error.message}。${advice}`, {
+        ...(error.detail === undefined ? {} : { detail: error.detail }),
+        hint:
+          `升级：workbench_modules（action=update, id=${names.suiteId}）。` +
+          `终端确认：opencli ${names.plugin} ${command} --help${
+            error.hint === undefined ? '' : `\n${error.hint}`
+          }`,
+        ...(error.helpUrl === undefined ? {} : { helpUrl: error.helpUrl }),
+        ...(error.project === undefined ? {} : { project: error.project }),
+      });
+    }
+  };
+}

package/src/host/unit-face.ts

@@ -0,0 +1,65 @@
+import type { DshHostContext } from '../api/dsh.js';
+import type { UnitManifest } from '../api/unit.js';
+import type { RouteTable } from '../host/http.js';
+import type { LongTaskBase, LongTaskHost, LongTaskRegistry } from '../host/long-task.js';
+import type { ProvisionHandler } from '../host/provision.js';
+import type { UnitCapability } from './unit-libs';
+import type { ApprovalCall, ApprovalFacts } from '../host/tool-approval.js';
+import type { ValueHandoff } from '../host/value-handoff.js';
+import type { WorkspaceStore } from '../host/workspace-store.js';
+
+export interface UnitMountDeps {
+  readonly ctx: DshHostContext;
+  readonly logger?: { info?(message: string): void; warn?(message: string): void } | undefined;
+  readonly manifests: () => readonly UnitManifest[];
+  readonly opencliCommand?: string;
+  readonly store: WorkspaceStore;
+  readonly values?: ValueHandoff | undefined;
+  readonly probe?: (
+    unit: string,
+    options?: { readonly force?: boolean },
+  ) => Promise<UnitCapability | undefined>;
+  readonly longTasks?: LongTaskHost | undefined;
+}
+
+export type ContextRenderer = (ref: {
+  readonly kind: string;
+  readonly parts: readonly string[];
+}) => Promise<string> | string;
+
+export type UnitWarmRead = readonly string[];
+
+export interface UnitCall {
+  readonly source: string;
+  readonly args: Readonly<Record<string, unknown>>;
+  readonly result: unknown;
+}
+
+export interface UnitMountResult {
+  readonly routes: RouteTable;
+  registerTools(): Array<() => void>;
+  readonly factsOf?: ((call: UnitCall) => readonly string[] | undefined) | undefined;
+  readonly gate?: {
+    deniedTools(workspace: string | null): readonly string[];
+    subscribe(listener: () => void): () => void;
+  };
+  readonly context?: {
+    readonly kinds: readonly string[];
+    render(ref: { readonly kind: string; readonly parts: readonly string[] }): Promise<string> | string;
+  };
+
+  readonly warmReads?: (() => readonly UnitWarmRead[]) | undefined;
+
+  readonly prefs?: { readonly resource: string; handle(payload: unknown): unknown };
+  readonly actions?: readonly { readonly resource: string; handle(payload: unknown): unknown }[];
+  readonly provision?: ProvisionHandler;
+  readonly longTasks?: LongTaskRegistry<LongTaskBase> | undefined;
+  readonly approvalDetail?:
+    | ((call: ApprovalCall) => ApprovalFacts | undefined | Promise<ApprovalFacts | undefined>)
+    | undefined;
+}
+
+export interface UnitHostFace {
+  readonly manifest: UnitManifest;
+  mount(deps: UnitMountDeps): UnitMountResult;
+}

package/src/host/unit-libs.ts

@@ -0,0 +1,41 @@
+import type { PluginSourceProblem } from './plugin-source';
+import type { PluginRelease, UnitLibNeed, UnitPluginNeed } from '../api/unit';
+
+export interface UnitLibState {
+  readonly name: string;
+  readonly purpose: string;
+  readonly status: 'ok' | 'outdated' | 'missing' | 'unsatisfied';
+  readonly installed?: string;
+  readonly latest?: string;
+  readonly command?: string;
+}
+
+export interface UnitCommands {
+  readonly unit: string;
+  readonly plugins?: readonly UnitPluginNeed[];
+  readonly libs?: readonly UnitLibNeed[];
+}
+
+export interface UnitPluginState {
+  readonly name: string;
+  readonly status: "ok" | "outdated" | "missing";
+  readonly missing: readonly string[];
+  readonly install?: "ready" | PluginSourceProblem;
+  readonly command?: string;
+  readonly release?: PluginRelease;
+}
+
+export interface UnitCapability {
+  readonly unit: string;
+  readonly status: "ok" | "missing-commands" | "missing-plugin" | "unchecked";
+  readonly plugin?: string;
+  readonly required: readonly string[];
+  readonly missing: readonly string[];
+  readonly detail: string;
+  readonly command?: string;
+  readonly fix?: "install" | "update";
+  readonly install?: "ready" | PluginSourceProblem;
+  readonly plugins?: readonly UnitPluginState[];
+  readonly libs?: readonly UnitLibState[];
+  readonly released?: boolean;
+}

package/src/host/value-handoff.ts

@@ -0,0 +1,38 @@
+import { HANDOFF_TTL_MS } from '../config/constants.js';
+
+export interface HandoffEntry {
+  readonly fact: string;
+  readonly key: string;
+}
+
+export interface HandoffValue {
+  readonly value: unknown;
+  readonly at: number;
+}
+
+export interface ValueHandoff {
+  hand(entry: HandoffEntry, value: unknown, now?: number): void;
+  take(entry: HandoffEntry, now?: number): HandoffValue | undefined;
+}
+
+export function handoffId(entry: HandoffEntry): string {
+  return `${String(entry.fact.length)}:${entry.fact}${entry.key}`;
+}
+
+export function createValueHandoff(options: { ttlMs?: number } = {}): ValueHandoff {
+  const ttlMs = options.ttlMs ?? HANDOFF_TTL_MS;
+  const held = new Map<string, HandoffValue>();
+
+  return {
+    hand(entry, value, now = Date.now()) {
+      held.set(handoffId(entry), { value, at: now });
+    },
+    take(entry, now = Date.now()) {
+      const id = handoffId(entry);
+      const hit = held.get(id);
+      if (hit === undefined) return undefined;
+      held.delete(id);
+      return now - hit.at >= ttlMs ? undefined : hit;
+    },
+  };
+}

package/src/host/workspace-store.ts

@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { workspacesRoot } from '../host/data-root.js';
+
+export interface ModuleStore {
+  readonly dir: string;
+  read(name: string): unknown | null;
+  write(name: string, value: unknown): void;
+  remove(name: string): void;
+  list(): string[];
+}
+
+export interface WorkspaceStore {
+  for(unitId: string, workspace: string | null): ModuleStore;
+  machine(unitId: string): ModuleStore;
+  scan(unitId: string): ModuleStore[];
+}
+
+function slug(raw: string, max = 40): string {
+  const cleaned = raw
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '')
+    .slice(0, max);
+  return cleaned === '' ? 'workspace' : cleaned;
+}
+
+export function workspaceKey(workspace: string): string {
+  const abs = path.resolve(workspace);
+  return `${slug(path.basename(abs))}-${createHash('sha1').update(abs).digest('hex').slice(0, 8)}`;
+}
+
+function inside(dir: string, name: string): string {
+  const trimmed = name.trim();
+  if (trimmed === '' || trimmed === '.' || trimmed === '..') {
+    throw new Error(`模块文件夹里只接受相对文件名，收到的是「${name}」`);
+  }
+  if (trimmed.includes('\0') || path.isAbsolute(trimmed)) {
+    throw new Error(`模块只能写自己的文件夹：不接受绝对路径「${name}」`);
+  }
+  const full = path.resolve(dir, trimmed);
+  if (full !== dir && !full.startsWith(dir + path.sep)) {
+    throw new Error(`模块只能写自己的文件夹：路径越界「${name}」`);
+  }
+  return full;
+}
+
+function memoryStore(dir: string): ModuleStore {
+  const files = new Map<string, unknown>();
+  return {
+    dir,
+    read: (name) => {
+      inside(dir, name);
+      return files.get(name) ?? null;
+    },
+    write: (name, value) => {
+      inside(dir, name);
+      files.set(name, value);
+    },
+    remove: (name) => {
+      inside(dir, name);
+      files.delete(name);
+    },
+    list: () => [...files.keys()].sort(),
+  };
+}
+
+function fileStore(dir: string): ModuleStore {
+  const ensureFor = (file: string): void => {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+  };
+  return {
+    dir,
+    read: (name) => {
+      const file = inside(dir, name);
+      try {
+        return JSON.parse(fs.readFileSync(file, 'utf8')) as unknown;
+      } catch {
+        return null;
+      }
+    },
+    write: (name, value) => {
+      const file = inside(dir, name);
+      ensureFor(file);
+      const tmp = `${file}.tmp`;
+      fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+      fs.renameSync(tmp, file);
+    },
+    remove: (name) => {
+      const file = inside(dir, name);
+      try {
+        fs.unlinkSync(file);
+      } catch {
+      }
+    },
+    list: () => {
+      try {
+        return fs
+          .readdirSync(dir, { withFileTypes: true })
+          .filter((entry) => entry.isFile())
+          .map((entry) => entry.name)
+          .sort();
+      } catch {
+        return [];
+      }
+    },
+  };
+}
+
+export function createWorkspaceStore(options: {
+  readonly root?: string | null | undefined;
+  readonly logger?: { warn?(message: string): void } | undefined;
+}): WorkspaceStore {
+  const root = options.root === null ? null : options.root ?? workspacesRoot();
+  let warned = false;
+  const memory = new Map<string, ModuleStore>();
+  const fallback = (dir: string): ModuleStore => {
+    if (!warned) {
+      warned = true;
+      options.logger?.warn?.(
+        '[dsh-workbench] 没有可写的数据根：模块配置只在本进程内生效（见 shared/api/host/data-root.ts）',
+      );
+    }
+    const hit = memory.get(dir);
+    if (hit !== undefined) return hit;
+    const created = memoryStore(dir);
+    memory.set(dir, created);
+    return created;
+  };
+
+  const open = (parts: readonly string[]): ModuleStore =>
+    root === null
+      ? fallback(path.join('/_memory', ...parts))
+      : fileStore(
+          path.join(
+            root,
+            ...parts.map((part) => slug(part)),
+          ),
+        );
+
+  return {
+    for: (unitId, workspace) =>
+      workspace === null || workspace.trim() === ''
+        ? fallback(path.join('/_memory', slug(unitId)))
+        : open([workspaceKey(workspace), unitId]),
+    machine: (unitId) => open(['_machine', unitId]),
+    scan: (unitId) => {
+      if (root === null) return [];
+      let entries: string[];
+      try {
+        entries = fs.readdirSync(root, { withFileTypes: true })
+          .filter((entry) => entry.isDirectory() && !entry.name.startsWith('_'))
+          .map((entry) => entry.name)
+          .sort();
+      } catch {
+        return [];
+      }
+      return entries.map((key) => fileStore(path.join(root, key, slug(unitId))));
+    },
+  };
+}

package/src/host/write-result.ts

@@ -0,0 +1,16 @@
+export function writeResultForClient(value: unknown, code: string): unknown {
+  if (typeof value !== 'object' || value === null) return value;
+  const box = value as Record<string, unknown>;
+  const existing = box['error'];
+  if (box['ok'] !== false || (typeof existing === 'object' && existing !== null)) return value;
+  const text = box['text'];
+  const detail = box['detail'];
+  return {
+    ok: false,
+    error: {
+      code,
+      message: typeof text === 'string' && text.trim() !== '' ? text : '这一步没有成功，也没说为什么',
+      ...(typeof detail === 'string' ? { detail } : {}),
+    },
+  };
+}

package/src/host.ts

@@ -0,0 +1,19 @@
+export * from './host/__tests__/fakes';
+export * from './host/cli-error';
+export * from './host/data-root';
+export * from './host/facts';
+export * from './host/git';
+export * from './host/http';
+export * from './host/long-task';
+export * from './host/opencli-runtime';
+export * from './host/opencli';
+export * from './host/plugin-source';
+export * from './host/provision';
+export * from './host/shell';
+export * from './host/tool-approval';
+export * from './host/tool-kit';
+export * from './host/unit-face';
+export * from './host/unit-libs';
+export * from './host/value-handoff';
+export * from './host/workspace-store';
+export * from './host/write-result';

package/src/i18n/en.ts

@@ -0,0 +1,170 @@
+import type { WorkbenchMessages } from './zh';
+
+export const en: Record<keyof WorkbenchMessages, string> = {
+  'brand.name': 'Workbench',
+
+  'toggle.open': 'Open sidebar',
+  'toggle.collapse': 'Collapse sidebar',
+  'project.label': 'Switch project',
+  'workspace.section': 'Workspaces',
+  'project.none': 'No project',
+  'project.empty': 'No projects yet. Use “Add project” below.',
+  'project.add': 'Add project…',
+  'session.new': 'New session',
+  'session.new.label': 'Start a session in the current project',
+  'session.empty': 'No sessions in this project yet.',
+  'session.noProject': 'Add a project first.',
+  'session.pinned': 'Pinned',
+  'session.actions': 'Actions for {name}',
+  'status.idle': 'Idle',
+  'status.running': 'Running',
+  'status.waitingApproval': 'Waiting for approval',
+  'status.planReview': 'Waiting for plan review',
+  'status.waitingAnswer': 'Waiting for your answer',
+  'status.completed': 'Completed',
+  'status.subagentsRunning.one': '{n} subagent running',
+  'status.subagentsRunning.other': '{n} subagents running',
+
+  'time.now': 'just now',
+  'time.minutes': '{n} min ago',
+  'time.hours': '{n} h ago',
+  'time.days': '{n} d ago',
+
+  'panels.title': 'Panel modules',
+  'panels.reset': 'Reset',
+  'panels.enabled': 'enabled in this project',
+  'panels.disabled': 'not enabled in this project',
+  'panels.choose': 'Choose modules',
+  'panels.failed': 'Could not save the change. Try again.',
+  'panels.hintEffect': 'Disabling = the agent cannot reach that data',
+  'panels.dragHint': 'Drag to reorder',
+  'panels.unknownStep': 'No suite provides this view',
+  'panels.labelWithHint': '{label} ({hint})',
+  'panels.dep.missingPlugin': '⚠ not ready yet',
+  'panels.dep.missingCommands': '⚠ needs an update',
+  'panels.dep.unchecked': '⚠ cannot check',
+  'panels.tab.modules': 'Panel setup',
+  'panels.tab.market': 'Workbench module market',
+  'panels.browseMarket': 'Browse the module market',
+  'panels.noneInstalled': 'None of these modules has its plugin installed yet',
+  'panels.noneInstalledHint': 'Once installed they come back here, and you pick which go on the panel.',
+  'panels.market.installed': 'installed',
+  'panels.market.outdated': 'needs update',
+  'panels.market.hasNew': 'New version',
+  'panels.market.missing': 'not installed',
+  'panels.market.unchecked': 'unknown',
+  'panels.market.checking': 'checking',
+  'panels.market.sectionInstalled': 'Installed',
+  'panels.market.sectionPending': 'Not installed',
+  'panels.market.sectionShared': 'Shared dependencies',
+  'panels.market.sharedUsedBy': 'Used by {modules}',
+  'panels.market.listSeparator': ', ',
+  'panels.market.sharedMissing': 'not installed',
+  'panels.market.sharedOutdated': 'update available',
+  'panels.market.sharedUnsatisfied': 'wrong version',
+  'panels.market.sharedOk': 'installed',
+  'panels.market.versionArrow': '{from} → {to}',
+  'panels.market.lead': 'Installed on this machine, shared by every project.',
+  'panels.market.install': 'Install',
+  'panels.market.update': 'Update',
+  'panels.market.uninstall': 'Uninstall',
+  'panels.market.installing': 'Installing…',
+  'panels.market.updating': 'Updating…',
+  'panels.market.uninstalling': 'Uninstalling…',
+  'panels.market.confirmUninstall': 'Uninstall?',
+  'panels.market.confirmUninstallDetail':
+    'It will be gone from this machine, and removed from every project panel (bindings and settings are kept).',
+  'panels.market.confirmYes': 'Uninstall',
+  'panels.market.confirmNo': 'Cancel',
+  'panels.market.failed': 'Failed: {reason}',
+  'panels.market.needEnv': 'Set {env} in the terminal that started the workbench first',
+  'panels.market.noSource': 'This module declares no install method — install it yourself',
+  'panels.market.badSource': 'The install method is incomplete — install it yourself',
+  'panels.market.empty': 'No modules available',
+  'panels.market.foot': 'After installing, enable it in the panel page of that project.',
+  'panels.market.recheck': 'Check for updates',
+  'panels.market.checkUpdates': 'Check for updates',
+  'panels.market.checkedAt': 'Last checked: {time}',
+  'panels.market.justNow': 'just now',
+  'panels.market.minutesAgo': '{n} min ago',
+  'panels.market.hoursAgo': '{n} h ago',
+  'blocker.fix.install': 'Install for me',
+  'blocker.fix.update': 'Upgrade for me',
+  'blocker.fix.running': 'Running…',
+  'blocker.fix.failed': 'Failed: ',
+  'blocker.retry': 'Retry',
+  'blocker.retry.running': 'Retrying…',
+  'blocker.copy': 'Copy command',
+  'blocker.market.open': 'Open the module market',
+  'blocker.login.title': 'Sign in to {platform}',
+  'blocker.login.titleGeneric': 'Sign-in required',
+  'blocker.login.hint': 'The workbench uses your browser session; sign in once and you are done.',
+  'blocker.login.go': 'Go sign in',
+  'blocker.login.manual': 'Run `opencli coding team-current` in a terminal, finish signing in, then retry.',
+  'blocker.forbidden.title': 'No access to {platform}',
+  'blocker.forbidden.titleGeneric': 'No access',
+  'blocker.forbidden.hint': 'You are signed in, but this project/repo is not permitted for your account.',
+  'blocker.forbidden.open': 'Open permissions page',
+  'blocker.timeout.hint': 'The headless browser may not have started; retrying usually helps.',
+  'blocker.exec.hint': 'Make sure opencli is installed and on PATH (which opencli).',
+  'blocker.unknown.title': 'Something went wrong',
+  'panels.reading': 'Reading the panel setup…',
+  'panels.empty': 'No modules on the panel yet',
+  'panels.emptyHint': 'You can also just tell the agent: “add a module to the panel”.',
+  'env.title': 'Preparing the workbench',
+  'env.checking': 'Checking the runtime environment…',
+  'env.installing': 'Installing the missing dependency…',
+  'env.failed': 'One step away',
+  'env.elapsed': 'Waiting {seconds}s',
+  'env.stepFailed.install': 'install failed',
+  'env.stepFailed.path': 'installed but not found',
+  'env.stepFailed.shell': 'no shell channel',
+  'env.bridge.ok': 'Connected',
+  'env.bridge.short': 'Not connected',
+  'env.bridge.why': 'Panel data goes through the login state in your browser: with this channel down, modules cannot fetch data. It does not block startup, but fix it first.',
+  'env.bridge.daemon': 'The background service is not running. It usually starts by itself \u2014 run the command below in your terminal first.',
+  'env.bridge.extension': 'The browser extension is not connected. Install it once from the Chrome Web Store (then hit Retry here). If it is already installed, run the command below first.',
+  'env.bridge.extensionLink': 'Get the extension in the Chrome Web Store',
+  'env.bridge.profile': 'Several browser profiles are connected but none is the default: list them (command below), then pick one.',
+  'env.bridge.stale': 'The default browser profile is stale (it names an extension instance that no longer exists): pick one again.',
+  'env.bridge.unknown': 'Could not tell what went wrong: the raw output below has the steps opencli itself suggests.',
+  'env.fix.title': 'How to fix it',
+  'env.fix.why': 'The workbench uses its own opencli (installed separately from the one in your terminal), and it is not set up on this machine yet.',
+  'env.fix.whyPath': 'opencli is installed, but this environment cannot find it \u2014 usually a PATH or shell-session issue.',
+  'env.fix.whyShell': 'The workbench has no shell channel, so it cannot fetch data \u2014 nothing the user can install.',
+  'env.fix.step': 'Run this in a terminal, then hit Retry:',
+  'env.fix.stepPath': 'Open a new terminal window (or make sure npm\u2019s global bin directory is on PATH), then hit Retry.',
+  'env.fix.stepShell': 'Restart the workbench (or dsh); if it keeps happening, the shell channel is not wired up.',
+  'env.fix.permission': 'Permission denied: rerun with sudo, or point npm\u2019s global directory at your home.',
+  'env.fix.network': 'Network unreachable: check your network or proxy, then retry.',
+  'env.fix.details': 'Details (for troubleshooting)',
+  'env.retry': 'Retry',
+  'env.copyCommand': 'Copy command',
+  'env.copied': 'Copied',
+  'env.step.opencli': 'Checking the workbench opencli',
+  'env.step.codingPlugin': 'Checking the coding plugin',
+  'env.step.bridge': 'Checking the browser bridge',
+  'env.step.warm': 'Warming up site sessions',
+  'env.warm.done': '{n} site(s) warmed up',
+  'env.warm.short': 'Not warmed this time — harmless; the panel heals on first read',
+  'env.unit.missingPlugin': 'This module is not ready yet',
+  'env.unit.missingCommandsHint': 'Updating it should fix this.',
+  'env.unit.unchecked': 'Cannot check: no shell channel',
+  'env.unit.uncheckedHint': 'The module is not the problem \u2014 the shell channel is unavailable. Restart the workbench.',
+  'env.unit.missingCommands': 'This module is out of date',
+  'env.unit.hint': 'Retry after installing; other modules are unaffected.',
+  'rightbar.label': 'Data panels',
+  'rightbar.expand': 'Expand the data panel',
+  'rightbar.collapse': 'Collapse the data panel',
+  'rightbar.refresh': 'Refresh',
+  'rightbar.refreshing': 'Refreshing…',
+  'rightbar.updatedAt': 'updated {time}',
+  'rightbar.noProject': 'The current session has no workspace',
+  'coding.notARepo.title': 'This workspace is not a Coding repository',
+  'error.unknown': 'Something went wrong',
+
+  'board.title': 'Board',
+
+  'panel.conversation': 'Conversation',
+  'panels.label': 'Global panels',
+};

package/src/i18n/index.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest';
+import { en } from './en';
+import { dictionaries } from './index';
+import { zh } from './zh';
+
+describe('dictionaries', () => {
+  it('同时导出两种语言，且就是那两份字典', () => {
+    expect(dictionaries.zh).toBe(zh);
+    expect(dictionaries.en).toBe(en);
+  });
+
+  it('只有这两种语言（多出来的键会被 locale 服务忽略，属于死代码）', () => {
+    expect(Object.keys(dictionaries).sort()).toEqual(['en', 'zh']);
+  });
+});

package/src/i18n/index.ts

@@ -0,0 +1,12 @@
+import { en } from './en';
+import { zh, type WorkbenchMessages } from './zh';
+
+export const dictionaries = { zh, en };
+
+export type { WorkbenchMessages };
+
+export interface Dictionaries {
+  readonly zh: Readonly<Record<string, string>>;
+  readonly en: Readonly<Record<string, string>>;
+  readonly [language: string]: Readonly<Record<string, string>>;
+}

package/src/i18n/merge.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest';
+import { mergeMessages } from './merge';
+
+const base = { zh: { 'board.title': '看板' }, en: { 'board.title': 'Board' } };
+
+describe('mergeMessages', () => {
+  it('把套件的键并进来；外壳原有的键不动', () => {
+    const merged = mergeMessages(base, [
+      {
+        unit: 'issues',
+        messages: { zh: { 'issues.mine': '我的缺陷' }, en: { 'issues.mine': 'My defects' } },
+      },
+    ]);
+
+    expect(merged.zh).toEqual({ 'board.title': '看板', 'issues.mine': '我的缺陷' });
+    expect(merged.en).toEqual({ 'board.title': 'Board', 'issues.mine': 'My defects' });
+    expect(base.zh).toEqual({ 'board.title': '看板' });
+  });
+
+  it('没贡献文案的套件直接跳过', () => {
+    expect(mergeMessages(base, [{ unit: 'nothing' }])).toEqual(base);
+  });
+
+  it('★ 键前缀必须等于套件 id（否则"这个键是谁的"说不清）', () => {
+    expect(() =>
+      mergeMessages(base, [
+        { unit: 'issues', messages: { zh: { 'builds.title': '构建' }, en: { 'builds.title': 'Builds' } } },
+      ]),
+    ).toThrow(/必须以 "issues\." 开头/);
+  });
+
+  it('★ 与外壳自己的键撞名 → 抛，并报出双方是谁', () => {
+    const legacy = { zh: { 'issues.title': '缺陷' }, en: { 'issues.title': 'Defects' } };
+
+    expect(() =>
+      mergeMessages(legacy, [
+        { unit: 'issues', messages: { zh: { 'issues.title': '缺陷' }, en: { 'issues.title': 'Defects' } } },
+      ]),
+    ).toThrow(/文案键冲突：issues\.title 由 外壳 与 issues/);
+  });
+
+  it('★ 套件自己的两语言不同构 → 抛（外壳的类型管不到别的套件）', () => {
+    expect(() =>
+      mergeMessages(base, [
+        {
+          unit: 'issues',
+          messages: { zh: { 'issues.a': '甲', 'issues.b': '乙' }, en: { 'issues.a': 'A' } },
+        },
+      ]),
+    ).toThrow(/两语言不同构/);
+  });
+
+  it('★ 空文案 → 抛（空值会静默显示成空白）', () => {
+    expect(() =>
+      mergeMessages(base, [
+        { unit: 'issues', messages: { zh: { 'issues.a': '   ' }, en: { 'issues.a': 'A' } } },
+      ]),
+    ).toThrow(/是空的/);
+  });
+});