@dsh-workbench/core 0.1.0

package/dist/types/shared/api/host/probe-units.d.ts

@@ -0,0 +1,17 @@
+import type { DshShell } from '@dsh-workbench/shared';
+import type { UnitCapability, UnitCommands } from "@dsh-workbench/shared/host";
+export type { UnitCapability, UnitCommands, UnitLibState, UnitPluginState } from "@dsh-workbench/shared/host";
+export declare function parsePluginList(stdout: string): unknown[] | undefined;
+export declare function probeUnitCommands(options: {
+    shell: DshShell;
+    command?: string;
+    unit: UnitCommands;
+    force?: boolean;
+}): Promise<UnitCapability>;
+export declare function probeUnits(options: {
+    shell: DshShell;
+    command?: string;
+    units: readonly UnitCommands[];
+    force?: boolean;
+}): Promise<UnitCapability[]>;
+export declare const resetProbeCache: () => void;

package/dist/types/shared/api/host/probe-verdict.d.ts

@@ -0,0 +1,7 @@
+import type { PluginRelease, UnitPluginNeed } from '@dsh-workbench/shared';
+import type { UnitCapability, UnitCommands, UnitLibState } from "./probe-libs";
+export declare function evaluateUnit(list: readonly unknown[] | undefined, unit: UnitCommands, failure: string | undefined, command?: string, releases?: ReadonlyMap<string, PluginRelease>, libs?: readonly UnitLibState[]): UnitCapability;
+export declare function gapsText(gaps: readonly string[]): string;
+export declare function pluginUpdateCommand(plugin: string | undefined): string | undefined;
+export declare function pluginInstallCommand(plugin: string | undefined): string;
+export declare function upgradeLine(need: UnitPluginNeed, command: string, latest: string): string | undefined;

package/dist/types/shared/api/host/release.d.ts

@@ -0,0 +1,18 @@
+import type { DshShell } from '@dsh-workbench/shared';
+import type { PluginRelease } from '@dsh-workbench/shared';
+export declare function parseLedgerVersion(stdout: string, name: string): string | undefined;
+export declare function compareVersions(a: string, b: string): number | undefined;
+export declare function isNewerVersion(latest: string, installed: string): boolean;
+export declare function latestVersion(options: {
+    shell: DshShell;
+    name: string;
+    registry: string;
+    force?: boolean;
+}): Promise<string | undefined>;
+export declare function probeRelease(options: {
+    shell: DshShell;
+    package: string;
+    registry?: string | undefined;
+    force?: boolean;
+}): Promise<PluginRelease | undefined>;
+export declare function resetReleaseCache(): void;

package/dist/types/shared/api/host/shell.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/api/host/tool-scope.d.ts

@@ -0,0 +1,32 @@
+import type { DshPromptAssembly } from '@dsh-workbench/shared';
+export interface ScopedToolRegistry {
+    restrict(filter: {
+        readonly allow?: readonly string[];
+        readonly deny?: readonly string[];
+    }): () => void;
+}
+export interface ToolScopeAgent {
+    readonly ctx?: {
+        readonly tools?: ScopedToolRegistry | undefined;
+        get?<T = unknown>(name: string): T | undefined;
+    } | undefined;
+    readonly session?: {
+        readonly header?: {
+            readonly cwd?: string;
+        } | undefined;
+    } | undefined;
+}
+export interface ToolScopeOptions {
+    deniedTools(workspace: string | null): readonly string[];
+    logger?: {
+        info?(message: string): void;
+        warn?(message: string): void;
+    } | undefined;
+}
+export interface ToolScope {
+    apply(agent: unknown): void;
+    narrow(assembly: DshPromptAssembly, agent: unknown): DshPromptAssembly;
+    reapply(): void;
+    disposeAll(): void;
+}
+export declare function createToolScope(options: ToolScopeOptions): ToolScope;

package/dist/types/shared/api/host/unit-readiness.d.ts

@@ -0,0 +1,7 @@
+import type { UnitManifest } from '@dsh-workbench/shared';
+export interface UnitReadiness {
+    readonly canMount: boolean;
+    readonly missingHard: readonly string[];
+    readonly missingSoft: readonly string[];
+}
+export declare function unitReadiness(manifest: UnitManifest, lookup: (name: string) => unknown): UnitReadiness;

package/dist/types/shared/api/host/unit-registry.d.ts

@@ -0,0 +1,9 @@
+import type { UnitManifest } from '@dsh-workbench/shared';
+import type { UnitHostFace } from '@dsh-workbench/shared/host';
+export interface UnitRegistry {
+    register(face: UnitHostFace): () => void;
+    all(): readonly UnitHostFace[];
+    manifests(): readonly UnitManifest[];
+    subscribe(listener: () => void): () => void;
+}
+export declare function createUnitRegistry(): UnitRegistry;

package/dist/types/shared/api/host/version-range.d.ts

@@ -0,0 +1,2 @@
+export type VersionVerdict = 'satisfied' | 'unsatisfied' | 'malformed';
+export declare function checkVersionRange(contract: string | undefined, version: string): VersionVerdict;

package/dist/types/shared/components/BlockerState.d.ts

@@ -0,0 +1,11 @@
+import type { ModuleBlocker } from '@dsh-workbench/shared';
+import type { Translate } from '@dsh-workbench/shared';
+export interface BlockerStateProps {
+    readonly blocker: ModuleBlocker;
+    readonly t: Translate;
+    readonly onRetry: () => void;
+    readonly busy?: boolean;
+    readonly flush?: boolean;
+    readonly onOpenMarket?: () => void;
+}
+export declare function BlockerState({ blocker, t, onRetry, busy, flush, onOpenMarket, }: BlockerStateProps): JSX.Element;

package/dist/types/shared/hooks/__tests__/mock-mode.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/hooks/__tests__/use-api-resource.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/hooks/__tests__/use-capabilities.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/hooks/__tests__/use-visible-busy.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/shared/hooks/fact-transports.d.ts

@@ -0,0 +1,2 @@
+import { type FactTransport } from '@dsh-workbench/shared';
+export declare function createAdaptiveTransport(): FactTransport;

package/dist/types/shared/hooks/mock-mode.d.ts

@@ -0,0 +1 @@
+export declare function mockModeOn(search: string): boolean;

package/dist/types/shared/hooks/use-api-resource.d.ts

@@ -0,0 +1,18 @@
+import type { ApiError, ApiResponse, Query } from '@dsh-workbench/shared';
+export interface ResourceState<T> {
+    readonly phase: 'idle' | 'loading' | 'ready' | 'error';
+    readonly value?: T;
+    readonly error?: ApiError;
+    readonly at?: number;
+}
+export declare function resourceIdentity(route: string, query: Query, override?: string | undefined): string;
+export declare function readKeyOf(identity: string, refreshToken: number, factRev: number): string;
+export declare function requestResource<T>(route: string, query: Query, key: string): {
+    task: Promise<ApiResponse<T>>;
+    release: () => void;
+};
+export declare function useApiResource<T>(route: string, query: Query, refreshToken: number, options?: {
+    enabled?: boolean;
+    key?: string;
+    fact?: string;
+}): ResourceState<T>;

package/dist/types/shared/hooks/use-blocker-actions.d.ts

@@ -0,0 +1,11 @@
+import type { BlockerAction } from '@dsh-workbench/shared';
+export interface BlockerActions {
+    run(action: BlockerAction): void;
+    copied: string | null;
+    running: string | null;
+    failure: {
+        message: string;
+        detail?: string;
+    } | null;
+}
+export declare function useBlockerActions(onRetry: () => void, onOpenMarket?: () => void): BlockerActions;

package/dist/types/shared/hooks/use-capabilities.d.ts

@@ -0,0 +1,25 @@
+import type { CapabilityPayload } from '@dsh-workbench/shared';
+export declare function shouldForce(refreshToken: number, previousToken: number): boolean;
+export type CapabilityMap = Record<string, CapabilityPayload>;
+export interface CapabilityProbeState {
+    readonly checkedAt: number | null;
+    readonly checking: boolean;
+}
+export declare function markNextProbeSilent(): void;
+export declare function probeValue(): CapabilityProbeState;
+export declare function subscribeProbe(listener: () => void): () => void;
+export declare const CAPABILITY_FACT = "capability";
+export declare function capabilityValue(): CapabilityMap | null;
+export declare function subscribeCapabilities(listener: () => void): () => void;
+export declare function setCapabilities(next: CapabilityMap | null, rechecked?: boolean): void;
+export declare function beginProbe(): void;
+export declare function endProbe(): void;
+export declare function publishCapability(result: CapabilityMap | null, rechecked?: boolean): boolean;
+export declare function shareCapabilityFetch(force: boolean, load: (force: boolean) => Promise<CapabilityMap | null>): Promise<CapabilityMap | null>;
+export declare function runCapabilityRead(options: {
+    readonly force: boolean;
+    readonly silent?: boolean;
+    readonly load?: (force: boolean) => Promise<CapabilityMap | null>;
+}): Promise<void>;
+export declare function useCapabilities(refreshToken: number, reloadToken?: number): CapabilityMap | null;
+export declare function useCapabilityProbe(): CapabilityProbeState;

package/dist/types/shared/hooks/use-capability-gate.d.ts

@@ -0,0 +1,20 @@
+import type { CapabilityPayload } from '@dsh-workbench/shared';
+import { type GateMode } from '@dsh-workbench/shared';
+import { type CapabilityMap } from './use-capabilities';
+export interface CapabilityGate {
+    readonly capability: CapabilityPayload | null;
+    readonly gated: boolean;
+    forceProbe(): void;
+}
+export declare function useCapabilityGate(unit: string, refreshToken: number, options?: {
+    readonly mode?: GateMode | undefined;
+    readonly fixture?: CapabilityPayload | undefined;
+}): CapabilityGate;
+export interface CapabilityMapView {
+    readonly capabilities: CapabilityMap | null;
+    readonly checkedAt: number | null;
+    readonly checking: boolean;
+    forceProbe(): void;
+    reload(): void;
+}
+export declare function useCapabilityMap(refreshToken: number): CapabilityMapView;

package/dist/types/shared/hooks/use-card-summary.d.ts

@@ -0,0 +1,8 @@
+export interface CardSummary {
+    readonly refreshing: boolean;
+    readonly at: number | null;
+}
+export declare function useCardSummary(onSummary: (summary: CardSummary) => void, summary: {
+    readonly refreshing: boolean;
+    readonly at: number | null | undefined;
+}): void;

package/dist/types/shared/hooks/use-facts.d.ts

@@ -0,0 +1,2 @@
+export declare function useFactRevision(fact: string): number;
+export declare function useFactInvalidate(): (fact?: string) => void;

package/dist/types/shared/hooks/use-fixture-pick.d.ts

@@ -0,0 +1,20 @@
+export interface PickableFixture {
+    readonly id: string;
+    readonly label: string;
+}
+export interface FixturePickOptions<T extends PickableFixture> {
+    readonly fixtures: readonly T[];
+    readonly selected?: string | null | undefined;
+    readonly onSelect?: ((id: string | null) => void) | undefined;
+    readonly enabled?: boolean | undefined;
+    readonly initial?: string | null | undefined;
+}
+export interface FixturePick<T extends PickableFixture> {
+    readonly enabled: boolean;
+    readonly active: string | null;
+    readonly current: T | undefined;
+    pick(id: string | null): void;
+    readonly nonce: number;
+    readonly index: number;
+}
+export declare function useFixturePick<T extends PickableFixture>(options: FixturePickOptions<T>): FixturePick<T>;

package/dist/types/shared/hooks/use-host-write.d.ts

@@ -0,0 +1,17 @@
+import { type WriteChannel, type WriteOutcome } from '@dsh-workbench/shared';
+export interface HostWrite<T> {
+    readonly busy: boolean;
+    readonly failed: string | null;
+    readonly detail: string | null;
+    send(body: Record<string, unknown>, options?: {
+        readonly silent?: boolean;
+    }): Promise<WriteOutcome<T>>;
+    fail(message: string, detail?: string): void;
+    clear(): void;
+}
+export interface HostWriteOptions {
+    readonly channel: WriteChannel;
+    readonly resource?: string | undefined;
+    readonly networkText: string;
+}
+export declare function useHostWrite<T>(options: HostWriteOptions): HostWrite<T>;

package/dist/types/shared/hooks/use-long-task.d.ts

@@ -0,0 +1,14 @@
+import { type LongTaskStatus } from '@dsh-workbench/shared';
+export interface LongTaskFeed<T> {
+    readonly runs: readonly T[];
+}
+export declare function useLongTask<T extends {
+    readonly id: string;
+    readonly status: LongTaskStatus;
+}>(options: {
+    readonly unit: string;
+    readonly workspace: string | null;
+    readonly mocked?: boolean | undefined;
+    readonly enabled?: boolean | undefined;
+    readonly pollMs?: number | undefined;
+}): LongTaskFeed<T>;

package/dist/types/shared/hooks/use-unit-board.d.ts

@@ -0,0 +1,32 @@
+import type { Translate } from '@dsh-workbench/shared';
+import type { ModuleBlocker } from '@dsh-workbench/shared';
+import { type UnitBlockers } from '@dsh-workbench/shared';
+import type { CapabilityPayload } from '@dsh-workbench/shared';
+import type { ApiError } from '@dsh-workbench/shared';
+import type { ResourceState } from './use-api-resource';
+import type { CapabilityGate } from './use-capability-gate';
+import { type CardSummary } from './use-card-summary';
+export interface CardFeed extends CardSummary {
+    readonly state: ResourceState<unknown>;
+    readonly settling?: boolean | undefined;
+}
+export interface UnitBoardOptions<TFeed extends CardFeed> {
+    readonly unit: string;
+    readonly gate: CapabilityGate;
+    readonly refreshToken: number;
+    readonly onRefresh: () => void;
+    readonly onSummary: (summary: CardSummary) => void;
+    readonly read: (gated: boolean) => TFeed;
+    readonly t: Translate;
+    readonly enabled?: boolean | undefined;
+    readonly platformBlocker?: ((error: ApiError, t: Translate) => ModuleBlocker | undefined) | undefined;
+}
+export interface UnitBoard<TFeed extends CardFeed> extends UnitBlockers {
+    readonly feed: TFeed;
+    readonly capability: CapabilityPayload | null;
+    readonly gated: boolean;
+    readonly refresh: () => void;
+    readonly forceProbe: () => void;
+    readonly summary: CardSummary;
+}
+export declare function useUnitBoard<TFeed extends CardFeed>(options: UnitBoardOptions<TFeed>): UnitBoard<TFeed>;

package/dist/types/shared/hooks/use-visible-busy.d.ts

@@ -0,0 +1,8 @@
+export type HeldPhase = 'idle' | 'loading' | 'ready' | 'error';
+export interface BusyView {
+    readonly busy: boolean;
+    readonly settling: boolean;
+}
+export declare function heldPhase(phase: HeldPhase, refreshing: boolean): HeldPhase;
+export declare function busyView(active: boolean, visible: boolean): BusyView;
+export declare function useVisibleBusy(active: boolean, floorMs: number): BusyView;

package/docs/HANDOFF.md

@@ -0,0 +1,207 @@
+# 把工作台给别人用
+
+工作台是一个 **dsh 插件包**，发在内网源上（地址只写在 `package.json` 的
+`publishConfig.registry` 一处）。别人装的是**独立 profile**（`workbench`）——
+他自己那份 `dsh web` 一行不改，两边可以同时开着。
+
+一句话：**登录内网源 → `setup` → 起**。
+
+## 一、对方机器上要有的
+
+| #   | 东西                         | 为什么                                                                                                                               | 怎么有                                       |
+| --- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
+| 1   | `dsh`                        | 本体。本仓库在 `0.1.7-rc.2` 上验过                                                                                                   | `npm i -g @deepseek-ai/dsh`（公网 npm 上有） |
+| 2   | `node` + **`pnpm`**          | dsh 的 `plugin` 子命令是**转发给 pnpm** 的；没有 pnpm 会直接报 `dsh: pnpm was not found`                                             | 各自装                                       |
+| 3   | 跑过一次 `dsh web`           | `setup` 拿 `~/.dsh/profiles/web` 当模板（bundle 清单 + 设置快照 + patch 点名的依赖）。没有它会**明确报错**，不会静默建出半个 profile | `dsh web`                                    |
+| 4   | 内网源登录                   | 包带 `@pagoda` scope，公网上没有它                                                                                                   | 见第二节                                     |
+| 5   | Coding 账号 + opencli 登录态 | 面板的数据来自 opencli 的 coding 插件                                                                                                | 见第四节                                     |
+
+## 二、两步装
+
+```bash
+# ① 让 pnpm/npx 知道 @pagoda 这个 scope 在哪个源，并登录（各一次）
+npm config set @pagoda:registry "$NPM_REGISTRY"
+npm login --registry=$NPM_REGISTRY
+
+# ② 建 profile + 把工作台装进去，然后起（占 :3081，dsh web 继续用 :3080）
+npx --yes @dsh-workbench/core@latest setup
+npx @dsh-workbench/core
+```
+
+**为什么必须有 `@pagoda:registry` 那一行**：不带 scope 的 `dsh-workbench`
+公网上已经有别人的一个（`lee259/dsh-workbench`），所以我们的包必须带 scope；
+而带 scope 的包，pnpm / npx 只会去 `.npmrc` 里**给这个 scope 指的那个源**找它 ——
+不设这一行，症状是 `404 Not Found - GET https://registry.npmjs.org/@pagoda%2fdsh-workbench`。
+
+### 设置从哪来：**两边都要的在 `dsh web` 里配**（单向、实时）
+
+工作台启动时会用 `--patch` 把 `profiles/web/cordis.patch.yml` 叠在自己的差异层之上
+（`bin/dsh-workbench` 里就在做这件事）。所以：
+
+- **模型供应商 / API key / 搜索源 / MCP** 这类"机器级、两边都要"的设置 ⇒ **在 `:3080` 的 Settings 里配一次**，工作台自动同源；
+- **只有工作台要的**（面板显示哪些模块、会话隔离）⇒ 在 `:3081` 里配，落在它自己的 profile patch，web 看不到；
+- 被 web 声明过的行，在工作台的 Settings 页里会显示 `overridden by a home patch or command-line overlay` —— 那是"这行由 web 管"的**提示**，不是故障。
+
+（这是 `--patch` 单向叠加，不是双向同步：工作台里配的**不会**流回 web。）
+
+### 一条"看起来坏了、其实没坏"的情况
+
+Settings → 插件里把 `@dsh-workbench/core` 关掉后，工作台会**退化成原版 dsh web**：
+左栏回到出厂样式、右侧数据面板消失。这是**设计内的降级**（关掉 = 它那份 bundle patch
+整份不再应用，连里面的"禁用出厂左栏"也一并失效），**会话 / 面板配置 / 工作区数据都不丢**。
+恢复：插件页把开关拨回来（或按 `Meta+,` 打开设置）。别把它当成故障去重建 profile。
+
+顺带一条：即使关掉工作台，profile 里剩下那层差异（会话/存储/附件隔离）**仍然生效**
+—— 那是无害且想要的（数据继续分开）。另外启动器每次都会叠一层 `sandbox-policy`，把执行缝的
+可写根指到 `$DSH_HOME/workbench`（`profile/sandbox.patch.yml`）—— 少了它，工作台自己跑 npm
+（自动装 opencli、市场装插件）会被沙箱拒写。它在 Settings 里显示为
+`overridden by a ... command-line overlay`，**属正常**。
+
+### `setup` 到底做了什么（幂等，可以重复跑）
+
+1. 拿 `~/.dsh/profiles/web` 当模板建 `workbench` profile；
+2. 继承 web 的 bundle 清单 + 设置快照 + patch 点名的依赖；
+3. 追加**数据隔离层**（会话 / 存储 / 附件各走 `~/.dsh/workbench/**`）；
+4. `dsh plugin --profile workbench add @dsh-workbench/core` —— 走 **dsh 自己的**
+   安装通路（兼容性预检、profile 写锁、装完自动把 bundle 登记进 profile 清单）。
+
+继承是**一次性快照**，不是订阅：web 之后改设置不会流过来（这正是"互不影响"的实现方式），
+要重新同步得重跑 `setup`。有意共享的只有两样：**API 凭据**（`~/.dsh/.credentials.yaml`，
+一机一把 key）和 `$DSH_HOME/cordis.patch.yml`（机器公共层，对所有 profile 实时生效）。
+
+## 三、不想用 npx？仓库副本也可以
+
+`bin/dsh-workbench` 认得出自己是不是仓库副本（看有没有 `.git`）：
+
+```bash
+git clone <仓库> && cd dsh-workbench && pnpm install
+./bin/dsh-workbench setup     # 仓库副本：以 link 方式装本目录，改源码立刻生效
+./bin/dsh-workbench
+```
+
+两种身份装出来的东西**同一个包名**，所以对方以后换成正装也不会打架。
+
+## 四、数据通路（面板要有数据）
+
+1. **opencli 隔离运行时**。第一次打开工作台，启动体检会**自己装**它（`@jackwener/opencli`，
+   公网包），落在 `$DSH_HOME/workbench/opencli/toolchain/`，**与对方本机的 `opencli` 完全隔离**
+   —— 插件目录靠改 `HOME` 分开（见 `bin/opencli-isolated` 开头），所以这里装/卸插件
+   不碰他本机的 `~/.opencli`。
+
+   装不上时（没网、源不通）失败态里有一条能照抄到终端的命令。**那条得在终端跑**：工作台
+   自己发起的命令走 dsh 的执行缝、带文件沙箱，终端没有 —— 沙箱放行的可写根由启动器声明
+   （`profile/sandbox.patch.yml` → `$DSH_HOME/workbench`），少了它"自己装"会死在 EPERM。
+
+2. **交叉依赖**（opencli 生态的 npm 包，例如 cmdb 发布流程用的 `opencli-workflow`）。
+   它**不是 opencli 插件**（不在 `plugin list` 里、没有子命令），所以单独一类：
+   装在**共享**的 `$DSH_HOME/workbench/opencli/libs/`（多模块声明同一份只装一次），
+   版本与源由**用到它的模块**在清单里声明（`env.libs`），工作台据此在体检/市场里说"缺了 / 有新版"，
+   并给一条能照抄的命令：
+
+   ```bash
+   npm i --prefix "$HOME/.dsh/workbench/opencli/libs" opencli-workflow@latest \
+     --registry "$NPM_REGISTRY" \
+     --cache "$HOME/.dsh/workbench/opencli/npm-cache"
+   ```
+
+   缺它的时候，发布那条流程（`workbench_cmdb_release`）会**明说**"还没装 + 上面这条命令"，
+   而不是抛一句 `Cannot find module`。理由与边界见
+   [ADR-0015](../../../docs/adr/0015-cross-dependency-vs-opencli-plugin.md)。
+
+   ⚠️ 清单里那个 `version` 是**版本契约**（`^1.1.23` 这种范围；留空 = 任意版本都满足）：
+   共享件只装一份，"装了但不是这个模块声明要的那一支"同样算**没装好**——
+   模块在市场上报「未装」、面板上也不画那张卡（见
+   [ADR-0016](../../../docs/adr/0016-installed-means-usable.md)）。
+
+3. **登录 Coding**。面板报"未登录"时，卡片上有「去登录 ↗」——在新标签里登完**切回来按
+   卡片上那颗「重试」**（刻意不做自动重试：登录什么时候完成我们不知道）。若仍是未登录，
+   就在终端用**隔离运行时那条**跑一次：
+
+   ```bash
+   $HOME/.dsh/workbench/opencli/bin/opencli coding team-current
+   ```
+
+   ⚠️ 是**这条**，不是 `which opencli` 那条 —— 两条的插件目录不同，登错了面板还是空的。
+
+4. **coding 插件**（私有包，在内网源上）。**不用配任何东西**：那个源由模块自己带着
+   （清单里的 `installSource.registryDefault`），市场页那一行直接给「安装」。
+
+   只有插件**不在默认那个源**上时，才用环境变量覆盖：
+
+   ```bash
+   export DSH_WORKBENCH_CODING_REGISTRY=<那个源>
+   ```
+
+   装的时候 `bin/opencli-isolated` 会把 `~/.npmrc` 指回去，就为了拿到源的 token；
+   npm 缓存则一律落在那台机器自己的隔离运行时里（**不碰** `~/.npm`）。
+
+## 五、不用管的
+
+- **`dsh web` 一行不改**：`./scripts/verify.sh` 是外部证据 —— 比对 web 的 profile 哈希、
+  两个 profile 的组合树差异、数据是否分家，而不是自证。
+- 会话 / 存储 / 附件各自独立；工作台是**另一个端口、另一个进程**，可与 `dsh web` 同开。
+- 改工作台设置只落在 `profiles/workbench/cordis.patch.yml`。
+
+## 六、发版（发起人）
+
+```bash
+cd <仓库根>
+pnpm release:dry   # 门禁 + 发布计划 + 打包清单校验，不联网、不真发
+pnpm release             # 真发（发前会再跑一次门禁）
+```
+
+提版本号之后再发：`npm version patch`。脚本把三个坑写成了**硬失败**：
+
+- **`dist/` 在 `.gitignore` 里**：npm 打包的兜底就是 `.gitignore`，不在 `files` 里显式列出
+  就会漏掉构建产物 —— 症状不是报错，而是"别人装上后宿主侧起不来"；
+- 版本号在源上已被占（pnpm 到最后一步才报，白等一轮门禁）；
+- `private: true` 没摘。
+
+## 七、版本与兼容（实话）
+
+`package.json` 的 `peerDependencies` 里**没有** `@deepseek-ai/dsh`，这是有意的：
+dsh 目前是 `0.1.7-rc.2`（预发布），声明范围会让版本不一致的人**装不上**；不声明则是
+"谁都能装，坏了当场知道"。
+
+代价要清楚：工作台依赖 dsh 的两个注入面（`@deepseek-ai/dsh-client-ui-slots`、
+`@deepseek-ai/dsh-client-locale`，见 `dsh.client.inject`），这两个面在 dsh 升级时会动。
+对方的 dsh 版本和上面验过的差得远时，**先在一台上验一次**再铺开。
+
+想改成"装的时候就拦住"，在 `package.json` 里声明：
+
+```json
+"peerDependencies": { "@deepseek-ai/dsh": "^0.1.7" }
+```
+
+dsh 会用这条做**安装预检**（`evaluatePluginCompatibility`），不满足就拒绝安装，
+可用 `dsh plugin --profile workbench allow-version <包@版本> --dsh-version <版本> --accept-risk` 豁免。
+
+> `NPM_REGISTRY` 是**你们自己的**内网 npm 源地址（形如 `https://<源主机>/<路径>/`）。
+> 本仓不写它：开源包里不该出现任何内网地址。
+
+## 发布（一个脚本，一条命令）
+
+```bash
+pnpm release            # 门禁 → 计划 → 逐包：登录 → 版本没被占 → 打包清单 → 发
+pnpm release:dry        # 不联网：门禁 → 计划 → 打包清单校验
+```
+
+`scripts/release.mjs` 是**唯一**的发布入口（曾经的 `publish.sh` + `release-plan.mjs` 已合并进来）。
+谁要发、发到哪、要发什么，全部从各包自述清单读，不写死名单：
+
+- **发不发** = 有 `publishConfig.registry`，或 `publishConfig.access === 'public'`（默认 npmjs）；`private: true` 一律不发；
+- **发什么** = 包自己声明的 `exports` / `bin` / `dsh.bundle.patch` 那几份文件必须在（`dist/`、`client.js` 在 `.gitignore` 里，漏了 `files` 的症状是"装上后宿主侧起不来"，不是报错）；
+- **什么顺序** = 依赖优先（`shared` → `core` → 用到它们的模块）；依赖的包这次不发就报错；
+- **公网包**用 `--access public`，内网源不加这个参数。
+
+它替你把四件事变成硬失败：**门禁绿 · 计划成立 · 打包清单真的有产物 · 这个版本号在源上还没人占**。
+发布用 `pnpm publish`（不是 `npm publish`）：只有 pnpm 会把 `workspace:*` 改写成真实版本，
+`npm pack` / `npm publish` 不会 —— 直接发别人装不上。
+
+### 版本同步规则（脚本会替你拦）
+
+| 关系 | 规则 |
+| --- | --- |
+| 模块 ↔ 外壳 | 模块 `peerDependencies['@dsh-workbench/core'] = ^0.1.0`。**`^0.x` 锁次版本**：外壳升到 `0.2.0` 时 `^0.1.0` 不再满足，脚本当场报 —— 要把每个模块的范围一起改（或一起升） |
+| `shared` ↔ 外壳/模块 | 依赖写的是 `workspace:*`，发布时会被改写成**当时那个版本号** → `shared` 必须先发；`shared` 升版后，用到它的包要重新发一次才会带上新范围 |
+| `module-tools` ↔ `init` 模板 | 模板里 `@dsh-workbench/core` / `module-tools` 的范围要跟着本仓版本走，否则 `init` 生成的是过期范围（脚本已检查这一条） |