@dsh-workbench/shared 1.1.4 → 1.1.6

package/dist/i18n/zh.js

@@ -129,11 +129,14 @@ export const zh = {
     'panels.market.update': '更新',
     'panels.market.swapSlow': '还没换上：可能网慢或没装上。再点一次「更新」；一直这样就把 dsh 重启一遍。',
     'panels.market.removeSlow': '还没卸掉：可能网慢或卸载没走完。等一下再看；一直这样就把 dsh 重启一遍。',
-    'panels.market.updateNoChange': '更新失败：还是 {from}；源上最新是 {latest}，可以再点一次「更新」。',
+    'panels.market.updateNoChange': '更新没换上：还是 {from}；源上最新是 {latest}。',
     'panels.market.updateUnknownVersion': '（问不到）',
     'panels.market.updateGone': '更新失败：更新后找不到这个模块。',
     'panels.market.updateRestored': '更新失败：更新后找不到新版本，已把 {version} 装回去。',
-    'panels.market.updateBehind': '装上了 {installed}，但源上最新是 {latest} —— 没更到最新，可以再点一次。',
+    'panels.market.updateBehind': '装上了 {installed}，但源上最新是 {latest}。',
+    'panels.market.updateStuck.title': '更新没换上',
+    'panels.market.updateStuck.factNoChange': '盘上还是 {from}；源上最新是 {latest}。',
+    'panels.market.updateStuck.copiedHint': '粘到终端跑一次，跑完重启一次工作台。',
     'panels.market.selfUpdateFailed': '工作台更新失败：{reason}',
     'panels.market.selfUpdateUnknown': '外部进程没留下原因（看 ~/.dsh/workbench/self-update.log）',
     'panels.market.selfUpdateRolledBack': '工作台更新失败，已回滚到 {version}。',
@@ -149,6 +152,40 @@ export const zh = {
     'panels.market.confirmNo': '取消',
     'panels.market.noMarketSource': '索引里没有这个模块的新版本（刷新一次索引再试）',
     'panels.market.failed': '没成功：{reason}',
+    'panels.market.askAgent': '问 agent',
+    'panels.market.askAgentCopied': '已复制',
+    'panels.market.askAgentText': '工作台里「{name}」（单元 {unit}）用不了：{reason}。帮我查清缺什么、怎么补，补完确认真能用。',
+    'panels.market.failure.permission': '没装上：没有写入权限',
+    'panels.market.failure.diskFull': '没装上：磁盘满了',
+    'panels.market.failure.sandbox': '没装上：被系统拦住了',
+    'panels.market.failure.unknown': '没装上：原因没认出来',
+    'panels.market.failure.factOwner': '{path} 属于 {owner}，当前账号（{me}）写不进去。把它还给自己就行（会要开机密码）。',
+    'panels.market.failure.factMode': '{path} 的权限是 {mode}，当前账号没有写权限。',
+    'panels.market.failure.factSpace': '{path} 所在的磁盘满了。',
+    'panels.market.failure.factStuck': '这条命令跑在受限环境里，写不进 {path}。',
+    'panels.market.failure.nowhere': '（没认出是哪个目录）',
+    'panels.market.failure.copyFix': '复制修复命令',
+    'panels.market.failure.copied': '已复制',
+    'panels.market.failure.copiedHint': '粘到终端跑一次，回来点「再检测」。',
+    'panels.market.failure.askAgent': '复制给 agent',
+    'panels.market.failure.askAgentText': '装这个模块时写不进去：`{command}` 退出码 {code}，卡在 {path}。帮我看看是被沙箱拦的还是权限问题，换一条能写进去的路再装。',
+    'panels.market.failure.askAgentHint': '粘到对话里，让 agent 接着弄。',
+    'panels.market.failure.recheck': '再检测',
+    'panels.market.failure.showOutput': '查看安装输出',
+    'panels.market.failure.hideOutput': '收起安装输出',
+    'panels.market.failure.term.commandLine': '第 {line} 行的命令',
+    'panels.market.failure.term.signal': '被 {signal} 终止',
+    'panels.market.failure.term.exitCode': '退出码 {exitCode}',
+    'panels.market.failure.term.noExitCode': '没有退出码',
+    'panels.market.failure.term.running': '在跑',
+    'panels.market.failure.term.failed': '没跑通',
+    'panels.market.failure.term.done': '跑完了',
+    'panels.market.failure.term.copy': '复制',
+    'panels.market.failure.term.copied': '已复制',
+    'panels.market.failure.term.noOutput': '没有输出',
+    'panels.market.failure.term.collapse': '收起',
+    'panels.market.failure.term.expandAria': '展开剩下的 {hidden} 行',
+    'panels.market.failure.term.expand': '展开 {hidden} 行',
     'panels.market.needEnv': '先在启动工作台的终端里设 {env}',
     'panels.market.needCommands': '缺这几条命令：{commands}',
     'panels.market.needBinary': '先装 {command} 命令',
@@ -185,9 +222,13 @@ export const zh = {
     'panels.market.restartNeeded': '新版装好了，重启一次才生效。',
     'panels.market.foot': '装好后到那个项目的面板页勾选它，模块才会出现。',
     'panels.market.checkUpdates': '检查更新',
+    'panels.market.checkAll': '检查全部更新',
     'panels.market.checkingNow': '正在检查…',
     'panels.market.checkFailed': '最近一次没查到，检查网络后重试',
     'panels.market.checkedAt': '最近检查：{time}',
+    'panels.market.latestPartial': '{n} 个模块没查成',
+    'panels.market.latestNoRegistry': '没配来源，未检查新版',
+    'panels.market.latestProbeFailed': '问不到源，稍后重试',
     'panels.market.justNow': '刚刚',
     'panels.market.minutesAgo': '{n} 分钟前',
     'panels.market.hoursAgo': '{n} 小时前',
@@ -246,6 +287,8 @@ export const zh = {
     'panels.market.add.failurePermission': '没有写入权限，无法安装',
     'panels.market.add.failureBuildBlocked': '有依赖的安装脚本需要你允许后才能继续',
     'panels.market.add.failureIntegrity': '下载的安装包校验失败',
+    'panels.market.add.failureStopProfile': '旧版还在用着（工作台正加载这个模块），这一版 dsh 不肯就地覆盖。',
+    'panels.market.add.failureCancelled': '这次操作被取消了，什么都没动。',
     'panels.market.add.failureTimeout': '安装超时',
     'panels.market.add.failurePnpmMissing': '没有找到 pnpm，无法安装',
     'panels.market.add.failureInstalled': '它已经装在这份工作台里了。同一个包不能就地覆盖，得先卸载再装；这次卸载也没成功。',
@@ -329,7 +372,7 @@ export const zh = {
     'panels.discover.missingIndex': '仓库里还没有索引文件 {path}',
     'panels.discover.initTitle': '把这个仓库初始化成模块市场索引？',
     'panels.discover.initCta': '初始化成市场索引',
-    'panels.discover.initWhat': '会在 {branch} 分支写 market.json 与 README.md，提交一次并推上去；之后从这个工作台发布的模块会把打包好的文件提交到按包名分的 packages/<包名>/。仓库的写权限归它的所有者。',
+    'panels.discover.initWhat': '会在 {branch} 分支写索引目录 market/ 与 README.md，提交一次并推上去；之后从这个工作台发布的模块会把打包好的文件提交到 artifacts/<包名>/<版本>/，条目写到 market/<包名>/<版本>.json。仓库的写权限归它的所有者。',
     'panels.discover.initBranch': '分支',
     'panels.discover.initBranchHint': '索引和打包文件都发到这个分支；空仓库会新建它。',
     'panels.discover.initBranchBad': '分支名只能用字母、数字、点、下划线、斜杠或短横线',
@@ -652,6 +695,9 @@ export const zh = {
     'approval.record.noSwitch': '录完不会替你切回来（左栏底部会亮一条状态）',
     'approval.longTask.what': '要停的那次任务',
     'approval.longTask.signal': '停了只是让工作台发出中断信号 —— 这次任务怎么收尾由模块自己负责',
+    'approval.plugin.name': '插件',
+    'approval.plugin.command': '命令',
+    'approval.plugin.note': 'agent 说',
     'approval.publish.module': '模块',
     'approval.publish.target': '目标',
     'approval.publish.version': '版本',
@@ -671,7 +717,7 @@ export const zh = {
     'approval.publish.artifacts': '打包文件',
     'approval.publish.index': '索引',
     'approval.publish.commits': '提交',
-    'approval.publish.twoCommits': '打包文件 + market.json 两次提交，一次推送',
+    'approval.publish.twoCommits': '打包文件 + 条目文件两次提交，一次推送',
     'approval.publish.reading': '读取中…',
     'approval.publish.changelog': '{version} 的更新日志',
     'approval.publish.changelogPending': '{version} 这一版会写进更新日志，随包发布',

package/dist/index.d.ts

@@ -35,6 +35,7 @@ export * from './components/board-module.js';
 export * from './components/icons.js';
 export * from './config/constants.js';
 export * from './config/storage.js';
+export * from './contract/approval.js';
 export * from './contract/blocker.js';
 export * from './contract/data.js';
 export * from './contract/extension.js';

package/dist/index.js

@@ -35,6 +35,7 @@ export * from './components/board-module.js';
 export * from './components/icons.js';
 export * from './config/constants.js';
 export * from './config/storage.js';
+export * from './contract/approval.js';
 export * from './contract/blocker.js';
 export * from './contract/data.js';
 export * from './contract/extension.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-workbench/shared",
-  "version": "1.1.4",
+  "version": "1.1.6",
   "description": "工作台与模块共享的纯代码与契约类型：类型、纯逻辑、哑组件、平台解析。宿主侧的东西从 /host 进（不影响浏览器产物）。",
   "license": "MIT",
   "type": "module",

package/src/api/host-write.ts

@@ -1,3 +1,5 @@
+import type { InstallFailure } from '../contract/command.js';
+
 /**
  * 宿主写口的五条通道（偏好、动作、供给、工坊调试、工坊录制），是写路由的第一段。
  */
@@ -9,7 +11,8 @@ export type WriteChannel =
   | 'diy-record';
 
 /**
- * 写通道统一的结果：成了带值，没成带一句能给人看的话（可选明细与帮助链接）。
+ * 写通道统一的结果：成了带值，没成带一句能给人看的话（可选明细与帮助链接）；
+ * 安装类的失败多带一份结构化现场，界面据此给修法。
  */
 export type WriteOutcome<T> =
   | { readonly ok: true; readonly value: T }
@@ -18,4 +21,5 @@ export type WriteOutcome<T> =
       readonly message: string;
       readonly detail?: string;
       readonly helpUrl?: string;
+      readonly failure?: InstallFailure;
     };

package/src/api/workbench-client.ts

@@ -1,4 +1,5 @@
 import { API_PREFIX } from '../config/constants.js';
+import type { InstallFailure } from '../contract/command.js';
 
 /**
  * 宿主读口 / 写口回的错误：code 给判据分档，message 给人看，helpUrl 有就去点。
@@ -9,6 +10,7 @@ export interface ApiError {
   readonly detail?: string;
   readonly hint?: string;
   readonly helpUrl?: string;
+  readonly failure?: InstallFailure;
 }
 
 /**

package/src/components/ApprovalPlan.css

@@ -10,22 +10,21 @@
   color: var(--dsw-alias-label-secondary);
 }
 .wb-approvalRows {
-  display: flex;
-  flex-direction: column;
-  gap: var(--wb-len-2);
+  display: grid;
+  grid-template-columns: minmax(var(--wb-len-56), auto) minmax(0, 1fr);
+  column-gap: var(--wb-len-8);
+  row-gap: var(--wb-len-2);
+  align-items: baseline;
   margin: 0;
 }
 .wb-approvalRow {
-  display: flex;
-  align-items: baseline;
-  gap: var(--wb-len-8);
+  display: contents;
 }
 .wb-approvalLabel {
-  flex: none;
-  width: var(--wb-len-56);
   font-size: var(--dsw-font-xxs-12-font-size);
   line-height: var(--wb-line-18);
   color: var(--dsw-alias-label-tertiary);
+  overflow-wrap: anywhere;
 }
 .wb-approvalValue {
   margin: 0;

package/src/config/constants.ts

@@ -109,6 +109,12 @@ export const STORAGE_KEY_RIGHTBAR_COLUMN = "dsh-workbench.rightbar.column";
 /** 记住右栏宽度（像素数字的字符串）的 localStorage 键。 */
 export const STORAGE_KEY_RIGHTBAR_WIDTH = "dsh-workbench.rightbar.width";
 
+/** 记住「添加模块」浮层选过的安装源的 localStorage 键。 */
+export const STORAGE_KEY_MARKET_REGISTRY = "dsh-workbench.market.registry";
+
+/** 记住「添加模块」浮层上次填过的自定义源地址的 localStorage 键。 */
+export const STORAGE_KEY_MARKET_REGISTRY_CUSTOM = "dsh-workbench.market.registry.custom";
+
 /** 右栏宽度达到或超过多少像素就按全屏对待（阈值，像素）。 */
 export const RIGHTBAR_FULLSCREEN_WIDTH = 768;
 

package/src/contract/__tests__/needs.test.ts

@@ -37,6 +37,59 @@ describe('needs 校验矩阵', () => {
     );
   });
 
+  it('bin 声明 install → 过；install 写歪了要判红并点名', () => {
+    expect(
+      errorsOf({
+        kind: 'bin',
+        name: 'gitops',
+        purpose: '平台命令',
+        install: { kind: 'command', line: 'brew install pagoda/tap/gitops', platforms: ['darwin'] },
+        docs: 'https://internal/gitops',
+      }),
+    ).toEqual([]);
+
+    expect(errorsOf({ kind: 'bin', name: 'x', purpose: 'p', install: { kind: 'brew', line: 'x' } }).join(' ')).toContain(
+      'install.kind 只认 command',
+    );
+    expect(errorsOf({ kind: 'bin', name: 'x', purpose: 'p', install: { kind: 'command', line: '' } }).join(' ')).toContain(
+      'install.line 没写',
+    );
+    expect(
+      errorsOf({ kind: 'bin', name: 'x', purpose: 'p', install: { kind: 'command', line: 'x', platforms: ['mac'] } }).join(' '),
+    ).toContain('darwin / linux / win32');
+    expect(errorsOf({ kind: 'bin', name: 'x', purpose: 'p', install: { kind: 'command', line: 'x', url: 'y' } }).join(' ')).toContain(
+      'install 有不认识的字段 url',
+    );
+  });
+
+  it('bin 的 install 也可以是一个 npm 包（命令由包提供，装进隔离运行时）', () => {
+    expect(
+      errorsOf({
+        kind: 'bin',
+        name: 'gitops',
+        purpose: '平台命令',
+        install: {
+          kind: 'npm',
+          package: 'opencli-workflow',
+          registryEnv: 'ACME_REGISTRY',
+          registryDefault: 'https://registry.test/',
+        },
+      }),
+    ).toEqual([]);
+
+    expect(errorsOf({ kind: 'bin', name: 'x', purpose: 'p', install: { kind: 'npm' } }).join(' ')).toContain(
+      'install.package 没写',
+    );
+    expect(
+      errorsOf({
+        kind: 'bin',
+        name: 'x',
+        purpose: 'p',
+        install: { kind: 'npm', package: 'x', registryDefault: 'ftp://x' },
+      }).join(' '),
+    ).toContain('registryDefault 要是 http(s):// 或 file:// 的源地址');
+  });
+
   it('bin / env 写了 sources → 红（没有安装路径）', () => {
     expect(errorsOf({ kind: 'bin', name: 'x', purpose: '测试', sources: [npm] }).join(' ')).toContain(
       '不支持 sources',

package/src/contract/approval.ts

@@ -0,0 +1,4 @@
+/**
+ * agent 自己那句"这次想干什么"的参数名：插件命令族必填，审批屏把它画在详情座里，不进标题。
+ */
+export const APPROVAL_NOTE_ARG = 'approval_note';

package/src/contract/command.ts

@@ -23,3 +23,25 @@ export interface CommandResult {
 export interface CommandReader {
   run(request: CommandRequest): Promise<CommandResult>;
 }
+
+export const INSTALL_FAILURE_KINDS = ['permission', 'disk-full', 'sandbox', 'unknown'] as const;
+
+export type InstallFailureKind = (typeof INSTALL_FAILURE_KINDS)[number];
+
+export type InstallFix =
+  | { readonly kind: 'chown'; readonly path: string; readonly uid: number; readonly gid: number }
+  | { readonly kind: 'chmod'; readonly path: string }
+  | { readonly kind: 'space'; readonly path: string }
+  | { readonly kind: 'handoff' };
+
+export interface InstallFailure {
+  readonly kind: InstallFailureKind;
+  readonly command: string;
+  readonly exitCode: number | null;
+  readonly output: string;
+  readonly path?: string | undefined;
+  readonly mode?: string | undefined;
+  readonly owner?: { readonly uid: number; readonly gid: number } | undefined;
+  readonly current: { readonly uid: number; readonly gid: number };
+  readonly fix: InstallFix;
+}

package/src/contract/needs.ts

@@ -41,12 +41,31 @@ export interface NeedCommon {
   readonly id?: string;
 }
 
+/**
+ * 一条装这个可执行文件的命令；模块作者写，工作台照抄执行。
+ */
+export type BinInstall =
+  | {
+      readonly kind: 'command';
+      readonly line: string;
+      readonly platforms?: readonly string[] | undefined;
+    }
+  | {
+      readonly kind: 'npm';
+      readonly package: string;
+      readonly registryEnv?: string | undefined;
+      readonly registryDefault?: string | undefined;
+      readonly platforms?: readonly string[] | undefined;
+    };
+
 /**
  * 机器上要有一个可执行文件；探法是 `command -v` / `where`。
  */
 export interface BinNeed extends NeedCommon {
   readonly kind: 'bin';
   readonly name: string;
+  readonly install?: BinInstall | undefined;
+  readonly docs?: string | undefined;
 }
 
 /**
@@ -107,6 +126,8 @@ export const NEED_KEYS: readonly string[] = [
   'version',
   'sources',
   'secret',
+  'install',
+  'docs',
 ];
 
 /**
@@ -188,7 +209,7 @@ function sourcesProblemsOf(
   if (!Array.isArray(raw)) return [`${at}.sources 要是数组`];
   if (raw.length === 0) return [`${at}.sources 是空数组 —— 不代装就整条删掉`];
   if (allowed.length === 0) {
-    return [`${at} 这种需要不支持 sources —— 它没有「从哪装」这回事`];
+    return [`${at} 这种需要不支持 sources —— 要代装就写 install（一条命令）`];
   }
   const errors: string[] = [];
   raw.forEach((source, index) => {
@@ -214,6 +235,38 @@ function commonProblemsOf(raw: Readonly<Record<string, unknown>>, at: string): r
   return errors;
 }
 
+export function binInstallProblemsOf(raw: unknown, at: string): readonly string[] {
+  if (raw === undefined) return [];
+  if (!isRecord(raw)) return [`${at}.install 要是对象`];
+  const errors: string[] = [];
+  for (const key of Object.keys(raw)) {
+    if (!['kind', 'line', 'platforms', 'package', 'registryEnv', 'registryDefault'].includes(key)) {
+      errors.push(`${at}.install 有不认识的字段 ${key}`);
+    }
+  }
+  const kind = text(raw['kind']);
+  if (kind !== 'command' && kind !== 'npm') {
+    errors.push(`${at}.install.kind 只认 command（一条命令）或 npm（一个包，装进隔离运行时）`);
+  }
+  if (kind === 'command' && text(raw['line']) === '') {
+    errors.push(`${at}.install.line 没写 —— 要一条能直接粘进终端的命令`);
+  }
+  if (kind === 'npm' && text(raw['package']) === '') {
+    errors.push(`${at}.install.package 没写 —— 这个命令由哪个 npm 包提供`);
+  }
+  if (raw['registryDefault'] !== undefined && !REGISTRY_PATTERN.test(text(raw['registryDefault']))) {
+    errors.push(`${at}.install.registryDefault 要是 http(s):// 或 file:// 的源地址`);
+  }
+  if (raw['platforms'] !== undefined) {
+    if (!Array.isArray(raw['platforms']) || raw['platforms'].length === 0) {
+      errors.push(`${at}.install.platforms 要是非空数组`);
+    } else if (raw['platforms'].some((one) => !['darwin', 'linux', 'win32'].includes(text(one)))) {
+      errors.push(`${at}.install.platforms 只认 darwin / linux / win32`);
+    }
+  }
+  return errors;
+}
+
 function perKindProblemsOf(
   kind: NeedKind,
   raw: Readonly<Record<string, unknown>>,
@@ -223,6 +276,8 @@ function perKindProblemsOf(
   if (kind === 'bin' || kind === 'lib' || kind === 'env') {
     if (text(raw['name']) === '') errors.push(`${at}.name 没写`);
   }
+  if (kind === 'bin') errors.push(...binInstallProblemsOf(raw['install'], at));
+  if (raw['docs'] !== undefined && text(raw['docs']) === '') errors.push(`${at}.docs 是空串`);
   if (kind === 'extension') {
     if (text(raw['runtime']) === '') errors.push(`${at}.runtime 没写 —— 扩展属于哪个运行时（如 opencli）`);
     if (text(raw['name']) === '') errors.push(`${at}.name 没写`);

package/src/contract/protocol/bundle-install.ts

@@ -179,6 +179,8 @@ export interface BundleCancellationPayload {
 
 export type ModuleUpdateBlock = 'needs-workbench' | 'incompatible';
 
+export type LatestUnavailable = 'local' | 'no-registry' | 'not-registry' | 'probe-failed';
+
 export interface ModuleVersion {
   readonly unit: string;
   readonly pkg: string;
@@ -186,6 +188,7 @@ export interface ModuleVersion {
   readonly title?: UnitTitle;
   readonly latest?: string;
   readonly latestBlocked?: ModuleUpdateBlock;
+  readonly latestUnavailable?: LatestUnavailable;
   readonly local?: boolean;
   readonly refused?: readonly string[];
   readonly market?: MarketInstalledModule;

package/src/contract/protocol/market-index.ts

@@ -1,4 +1,6 @@
 export const MARKET_INDEX_FORMAT = 1;
+export const MARKET_INDEX_DIR = 'market';
+export const MARKET_ARTIFACTS_DIR = 'artifacts';
 export const MARKET_INDEX_PATH = 'market.json';
 export const MARKET_DISCOVER_ROUTE = 'panels/market-discover';
 export const MARKET_DOC_ROUTE = 'panels/market-doc';
@@ -127,11 +129,13 @@ export type MarketIndexProblemKind =
   | 'format'
   | 'plugins'
   | 'plugin'
+  | 'entry'
   | 'name'
   | 'duplicate-name'
   | 'versions'
   | 'version'
   | 'version-order'
+  | 'duplicate-version'
   | 'source'
   | 'git-commit'
   | 'timestamp'

package/src/contract/unit.ts

@@ -24,12 +24,23 @@ export interface UnitCard {
   readonly order: number;
 }
 
+/**
+ * 合成工具背后那条 opencli 命令：插件名与命令名都是 opencli 那边的原名，`args` 是命令自己声明的参数名（按声明顺序）。
+ */
+export interface UnitToolOpencli {
+  readonly plugin: string;
+  readonly command: string;
+  readonly args: readonly string[];
+}
+
 /**
  * 一条工具在清单里的样子：全名加会不会写；审批按 writes 认领。
+ * `opencli` 只有「按已装插件合成」的单元写，手写模块的工具没有这一格。
  */
 export interface UnitTool {
   readonly name: string;
   readonly writes: boolean;
+  readonly opencli?: UnitToolOpencli;
 }
 
 /**

package/src/host/__tests__/market-index.test.ts

@@ -2,14 +2,23 @@ import { describe, expect, it } from 'vitest';
 import type { MarketIndex, MarketIndexEntry } from '../../contract/protocol/market-index.js';
 import { claimOf, claimOfEntry, entryOwnerOf, entryUnitOf, marketArtifactPath, samePublisher } from '../market-index-claim.js';
 import {
+  assembleMarketIndex,
+  collectMarketEntryFiles,
   filterMarketIndex,
+  marketEntryFilesOf,
+  marketEntryPath,
   marketInstallTarget,
+  marketMetaPath,
   marketSourceKey,
+  parseMarketEntryDoc,
   parseMarketIndex,
   parseMarketIndexJson,
   parseSourceConfig,
   upsertMarketEntry,
 } from '../market-index.js';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 
 function entry(change: Partial<MarketIndexEntry> = {}): MarketIndexEntry {
   return {
@@ -343,3 +352,108 @@ describe('索引源与安装目标', () => {
     ).toBe(false);
   });
 });
+
+describe('条目文件：一个版本一个文件', () => {
+  const versionDoc = (version: string, timestamp: number, title: string) => ({
+    name: '@scope/module-x',
+    version,
+    source: { type: 'npm' },
+    publishTimestamp: timestamp,
+    title: { zh: title },
+  });
+
+  it('路径按包名分层，meta 文件带 epoch 与随机后缀', () => {
+    expect(marketEntryPath('market', '@scope/module-x', '0.1.0')).toBe('market/@scope/module-x/0.1.0.json');
+    expect(marketMetaPath('market', '@scope/module-x', 3, 'a1b2c3')).toBe(
+      'market/@scope/module-x/meta-3-a1b2c3.json',
+    );
+    expect(marketEntryPath('market', 'plain', '1.0.0')).toBe('market/plain/1.0.0.json');
+  });
+
+  it('包名/版本号不合法就不给路径（防止写出目录外）', () => {
+    expect(() => marketEntryPath('market', '../escape', '1.0.0')).toThrow();
+    expect(() => marketEntryPath('market', 'ok', '../1.0.0')).toThrow();
+  });
+
+  it('单条文档能解析，坏文档整条拒', () => {
+    const good = parseMarketEntryDoc(versionDoc('0.1.0', 1_760_000_000, '探针'));
+    expect(good.ok).toBe(true);
+    if (!good.ok) return;
+    expect(good.doc.name).toBe('@scope/module-x');
+    const bad = parseMarketEntryDoc({ name: 'Bad Name', version: '0.1.0', source: { type: 'npm' } });
+    expect(bad.ok).toBe(false);
+    const noSource = parseMarketEntryDoc({ name: '@scope/x', version: '0.1.0' });
+    expect(noSource.ok).toBe(false);
+  });
+
+  it('组装：版本全收并按 SemVer 降序，元数据取最新那份', () => {
+    const files = [
+      { path: 'market/@scope/module-x/0.1.0.json', text: JSON.stringify(versionDoc('0.1.0', 1_760_000_000, '旧标题')) },
+      { path: 'market/@scope/module-x/0.2.0.json', text: JSON.stringify(versionDoc('0.2.0', 1_760_000_100, '新标题')) },
+      { path: 'market/@scope/module-x/meta-1760000200000.json', text: JSON.stringify({
+        name: '@scope/module-x',
+        publishTimestamp: 1_760_000_200,
+        title: { zh: '最新标题' },
+      }) },
+    ];
+    const assembled = assembleMarketIndex(files);
+    expect(assembled.ok).toBe(true);
+    if (!assembled.ok) return;
+    const entry = assembled.index.plugins[0];
+    expect(entry?.versions.map((one) => one.version)).toEqual(['0.2.0', '0.1.0']);
+    expect(entry?.title?.zh).toBe('最新标题');
+  });
+
+  it('组装：同一个版本出现两次就整份拒（那是真重复发布）', () => {
+    const assembled = assembleMarketIndex([
+      { path: 'a/0.1.0.json', text: JSON.stringify(versionDoc('0.1.0', 1_760_000_000, '甲')) },
+      { path: 'b/0.1.0.json', text: JSON.stringify(versionDoc('0.1.0', 1_760_000_100, '乙')) },
+    ]);
+    expect(assembled.ok).toBe(false);
+    if (assembled.ok) return;
+    expect(assembled.problems.some((one) => one.kind === 'duplicate-version')).toBe(true);
+  });
+
+  it('从目录读只收 .json，README 不当条目', () => {
+    const dir = mkdtempSync(join(tmpdir(), 'wb-entry-'));
+    try {
+      mkdirSync(join(dir, '@scope/module-x'), { recursive: true });
+      writeFileSync(join(dir, 'README.md'), 'index');
+      writeFileSync(join(dir, '@scope/module-x', '0.1.0.json'), JSON.stringify(versionDoc('0.1.0', 1_760_000_000, '探针')));
+      const files = collectMarketEntryFiles(dir);
+      expect(files.map((one) => one.path)).toEqual(['@scope/module-x/0.1.0.json']);
+      const assembled = assembleMarketIndex(files);
+      expect(assembled.ok).toBe(true);
+      if (!assembled.ok) return;
+      expect(assembled.index.plugins[0]?.name).toBe('@scope/module-x');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it('迁移：一份 format 1 能拆成条目文件，再组装回来一模一样', () => {
+    const legacy: MarketIndex = {
+      format: 1,
+      plugins: [
+        {
+          name: '@scope/module-x',
+          owner: '甲',
+          metadata: { workbench: true, unit: 'x' },
+          versions: [
+            { version: '0.2.0', source: { type: 'npm' }, publishTimestamp: 1_760_000_100 },
+            { version: '0.1.0', source: { type: 'npm' }, publishTimestamp: 1_760_000_000 },
+          ],
+        },
+      ],
+    };
+    const files = marketEntryFilesOf(legacy, 'market');
+    expect(files.map((one) => one.path)).toEqual([
+      'market/@scope/module-x/0.2.0.json',
+      'market/@scope/module-x/0.1.0.json',
+    ]);
+    const assembled = assembleMarketIndex(files);
+    expect(assembled.ok).toBe(true);
+    if (!assembled.ok) return;
+    expect(assembled.index.plugins).toEqual(legacy.plugins);
+  });
+});

package/src/host/adapter-types.ts

@@ -25,6 +25,7 @@ export interface ProfileModule {
   readonly version: string;
   readonly registry?: string;
   readonly local?: boolean;
+  readonly fromRegistry?: boolean;
 }
 
 export interface ProfilePackage {
@@ -51,6 +52,7 @@ export interface RegistryEntry {
 export interface RegistryNotebook {
   sources(): readonly RegistryEntry[];
   remember(entries: readonly RegistryEntry[]): readonly string[];
+  swapScope?(scope: string, registry: string): () => void;
 }
 
 export interface SelfUpdatePaths {

package/src/host/data-error.ts

@@ -4,11 +4,12 @@ export class WorkbenchDataError extends Error {
   readonly hint?: string;
   readonly project?: unknown;
   readonly helpUrl?: string;
+  readonly failure?: unknown;
 
   constructor(
     code: string,
     message: string,
-    extra: { detail?: string; hint?: string; project?: unknown; helpUrl?: string } = {},
+    extra: { detail?: string; hint?: string; project?: unknown; helpUrl?: string; failure?: unknown } = {},
   ) {
     super(message);
     this.name = 'WorkbenchDataError';
@@ -17,5 +18,6 @@ export class WorkbenchDataError extends Error {
     if (extra.hint !== undefined) this.hint = extra.hint;
     if (extra.project !== undefined) this.project = extra.project;
     if (extra.helpUrl !== undefined) this.helpUrl = extra.helpUrl;
+    if (extra.failure !== undefined) this.failure = extra.failure;
   }
 }

package/src/host/http.ts

@@ -49,6 +49,7 @@ function toErrorPayload(error: unknown): Record<string, unknown> {
       ...(data.hint === undefined ? {} : { hint: data.hint }),
       ...(data.helpUrl === undefined ? {} : { helpUrl: data.helpUrl }),
       ...(data.project === undefined ? {} : { project: data.project }),
+      ...(data.failure === undefined ? {} : { failure: data.failure }),
     };
   }
   return { code: 'internal', message: error instanceof Error ? error.message : String(error) };