@dsh-workbench/shared 1.0.0 → 1.1.0

package/dist/i18n/zh.js

@@ -129,14 +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.updateGone': '更新失败：更新后找不到这个模块。',
+    'panels.market.updateRestored': '更新失败：更新后找不到新版本，已把 {version} 装回去。',
     'panels.market.updateBehind': '装上了 {installed}，但源上最新是 {latest} —— 没更到最新，可以再点一次。',
-    'panels.market.selfUpdateFailed': '自更新没成：{reason}',
+    'panels.market.selfUpdateFailed': '工作台更新失败：{reason}',
     'panels.market.selfUpdateUnknown': '外部进程没留下原因（看 ~/.dsh/workbench/self-update.log）',
-    'panels.market.selfUpdateRolledBack': '没换成，已回滚到 {version}。',
+    'panels.market.selfUpdateRolledBack': '工作台更新失败，已回滚到 {version}。',
     'panels.market.uninstall': '卸载',
     'panels.market.uninstallLabel': '卸载 {name}',
     'panels.market.installing': '正在安装…',
@@ -158,9 +158,27 @@ export const zh = {
     'panels.market.empty': '暂无可用模块',
     'panels.market.sectionPlugins': '已安装 opencli 插件',
     'panels.market.moduleOutdated': '有新版',
+    'panels.market.updateNeedsWorkbench': '新版本要先把工作台升级才能用',
+    'panels.market.updateIncompatible': '新版本和当前的工作台不匹配，暂时不能更新',
     'panels.market.moduleRefused': '模块版本与工作台不匹配，暂时无法使用',
     'panels.market.moduleRestartHint': '重启后生效',
     'panels.market.pendingRestart': '重启后生效',
+    'panels.market.pendingFollowUp': '旧数据待迁移',
+    'panels.market.migrationHint': '旧会话和项目还没搬过来',
+    'panels.market.migrateAction': '迁移旧数据',
+    'panels.market.migrating': '正在迁移…',
+    'panels.market.migrateConfirmTitle': '迁移旧数据？',
+    'panels.market.migrateConfirmDetail': '先退出 dsh web / Desktop。迁移只补缺、不覆盖；旧目录保留。',
+    'panels.market.migrateConfirmAck': '我已经退出 dsh web / Desktop',
+    'panels.market.migrateConfirmYes': '开始迁移',
+    'panels.market.migrateDone': '迁移完成：补了 {added} 个项目；重启工作台和 dsh web 后出现。',
+    'panels.market.dismissFollowUp': '不再提醒',
+    'panels.market.dismissing': '正在收起…',
+    'panels.market.dismissFollowUpTitle': '不再提醒这件事？',
+    'panels.market.dismissFollowUpDetail': '提示会从模块市场收起，但不会迁移或删除旧数据。旧会话和项目仍留在旧目录，新版本里看不到；以后需要时仍可运行 dsh-workbench migrate。',
+    'panels.market.dismissFollowUpAck': '我知道旧数据不会自动出现',
+    'panels.market.dismissFollowUpYes': '不再提醒',
+    'panels.market.dismissed': '已不再提醒；旧数据仍在旧目录，需要时仍可运行 dsh-workbench migrate。',
     'panels.market.workbenchName': '工作台',
     'panels.market.pluginBroken': '这份插件装坏了：认不出它是什么。可以先卸载，再让 agent 按包名重装一次。',
     'panels.market.restartNeeded': '新版装好了，重启一次才生效。',
@@ -244,7 +262,7 @@ export const zh = {
     'panels.market.add.exampleTitle': '示例',
     'panels.market.add.exampleFill': '填入示例',
     'panels.market.add.registryLabel': '安装源',
-    'panels.market.add.registryProfile': '这个 profile 配的源',
+    'panels.market.add.registryProfile': '这份工作台配的源',
     'panels.market.add.registryPnpm': 'pnpm 自己配的源',
     'panels.market.add.check': '预检',
     'panels.market.add.checking': '正在预检…',
@@ -265,12 +283,16 @@ export const zh = {
     'panels.market.tabs': '模块市场的两个面',
     'panels.tab.discover': '发现',
     'panels.discover.loading': '正在读取索引',
+    'panels.discover.slowHint': '读取较慢：如有授权提示，先完成它，或换一个索引源。',
     'panels.discover.lead': '从索引源浏览模块；装上就能用。',
     'panels.discover.addSource': '添加',
     'panels.discover.addingSource': '正在添加…',
     'panels.discover.addFirstSource': '添加索引源',
     'panels.discover.removeSource': '移除',
     'panels.discover.removeSourceNamed': '移除 {url}',
+    'panels.discover.useSource': '使用',
+    'panels.discover.useSourceNamed': '使用 {label}',
+    'panels.discover.sourceCurrent': '当前使用',
     'panels.discover.refresh': '刷新',
     'panels.discover.search': '搜索模块',
     'panels.discover.all': '全部',
@@ -282,8 +304,8 @@ export const zh = {
     'panels.discover.sourcePlaceholder': 'https://example.com/index.json 或 git@git.example.com:wb/market.git',
     'panels.discover.sourceRef': '分支',
     'panels.discover.sourcePath': '索引文件',
-    'panels.discover.sourceLocal': '本地 clone（可选）',
-    'panels.discover.sourceLocalHint': '不填就 clone 到 ~/.dsh/workbench/market-index/。',
+    'panels.discover.sourceLocal': '本地副本目录（可选）',
+    'panels.discover.sourceLocalHint': '不填就放到 ~/.dsh/workbench/market-index/。',
     'panels.discover.save': '保存并刷新',
     'panels.discover.cancel': '取消',
     'panels.discover.retry': '重试',
@@ -296,9 +318,9 @@ export const zh = {
     'panels.discover.missingIndex': '仓库里还没有索引文件 {path}',
     'panels.discover.initTitle': '把这个仓库初始化成模块市场索引？',
     'panels.discover.initCta': '初始化成市场索引',
-    'panels.discover.initWhat': '会在 {branch} 分支写 market.json 与 README.md，提交一次并推上去；之后从这个工作台发布的模块会把产物提交到 packages/<unit>/。仓库的写权限归它的所有者。',
+    'panels.discover.initWhat': '会在 {branch} 分支写 market.json 与 README.md，提交一次并推上去；之后从这个工作台发布的模块会把打包好的文件提交到 packages/<unit>/。仓库的写权限归它的所有者。',
     'panels.discover.initBranch': '分支',
-    'panels.discover.initBranchHint': '索引与产物都发到这个分支；空仓库会新建它。',
+    'panels.discover.initBranchHint': '索引和打包文件都发到这个分支；空仓库会新建它。',
     'panels.discover.initBranchBad': '分支名只能用字母、数字、点、下划线、斜杠或短横线',
     'panels.discover.initOk': '初始化',
     'panels.discover.initBusy': '正在初始化…',
@@ -402,11 +424,11 @@ export const zh = {
     'panels.market.add.doneApplied': '装好了，已经生效。',
     'panels.market.add.doneRestart': '装好了，重启一次才生效。',
     'panels.market.add.restartWhy': '为什么这一版要重启：{reason}',
-    'panels.market.add.restartWhy.no-hmr': '这个配置只在启动时应用改动（没开热更新）',
+    'panels.market.add.restartWhy.no-hmr': '这份配置只在启动时读一次，改了得重启',
     'panels.market.add.restartWhy.package-moved': '某个已经装着的包换到了新的目录，或者这一下换掉了 dsh 自己提供的那份',
     'panels.market.add.restartWhy.host-module': '这一下动到了 dsh 自己加载的模块',
-    'panels.market.add.restartWhy.unmanaged-plugin': '这一下动到了插件清单之外正在跑的插件',
-    'panels.market.add.restartWhy.module-comparison': 'dsh 没能把已加载的插件与盘上的文件对上',
+    'panels.market.add.restartWhy.unmanaged-plugin': '这一下动到了没登记过、正在运行的插件',
+    'panels.market.add.restartWhy.module-comparison': 'dsh 没法确认正在跑的插件就是这台机器上装好的那一份',
     'panels.market.add.cancelled': '已取消。',
     'panels.market.add.failed': '没成功：{reason}',
     'panels.market.add.removed': '已经移除了。',
@@ -416,10 +438,10 @@ export const zh = {
     'panels.market.add.removedRestart': '卸掉了，重启一次才彻底生效。',
     'panels.market.add.remove': '移除它',
     'panels.market.add.problem.invalidSpec': '这个写法不认：不能是空的，也不能以横杠开头。',
-    'panels.market.add.problem.alreadyInstalled': '这个包已经在 profile 里了（要换版本请带上 @版本）。',
+    'panels.market.add.problem.alreadyInstalled': '这个包已经在这份工作台里了（要换版本请带上 @版本）。',
     'panels.market.add.problem.notFound': '源上没有这个包。换个包名或版本再试。',
     'panels.market.add.problem.notAPackage': '这个位置没有包。选一个包含 package.json 的目录。',
-    'panels.market.add.problem.notABundle': '它是一个 npm 包，但不是 dsh 插件包（缺 dsh 的接线声明）。',
+    'panels.market.add.problem.notABundle': '它是一个 npm 包，但不是 dsh 插件包（dsh 在里面找不到该加载什么）。',
     'panels.market.add.problem.network': '源连不上。检查网络后重试。',
     'panels.market.add.problem.unknown': '预检没通过（原因未知）。展开安装详情看原始输出，或重试。',
     'panels.market.add.reason.invalidSpec': '写法不认',
@@ -427,7 +449,7 @@ export const zh = {
     'panels.market.add.reason.notBundle': '它不是一个 dsh 插件包',
     'panels.market.add.reason.notRemovable': '它是安装自带的组合包，不能卸',
     'panels.market.add.reason.bundleInUse': '还有东西在用它，卸不掉',
-    'panels.market.add.reason.stopProfile': '这个配置没开热更新，得先停掉进程',
+    'panels.market.add.reason.stopProfile': '这份配置改了要重启，得先停掉工作台',
     'panels.market.add.reason.staleApproval': '要允许的安装脚本已经变了，重新来一次',
     'panels.market.add.reason.operationError': 'pnpm 执行出错（详情见安装输出）',
     'panels.market.add.reason.buildBlocked': 'pnpm 拦下了安装脚本',
@@ -450,15 +472,15 @@ export const zh = {
     'blocker.market.open': '去模块市场',
     'blocker.login.title': '需要登录 {platform}',
     'blocker.login.titleGeneric': '需要登录',
-    'blocker.login.hint': '工作台用你的浏览器登录态；登录一次就行，之后不用再登。',
+    'blocker.login.hint': '工作台借你浏览器里的登录状态；登录一次就行，之后不用再登。',
     'blocker.login.go': '去登录',
     'blocker.login.manual': '在终端执行该插件的登录命令（见插件的文档），按提示完成登录后重试。',
     'blocker.forbidden.title': '没有权限访问 {platform}',
     'blocker.forbidden.titleGeneric': '没有权限',
     'blocker.forbidden.hint': '账号已登录，但没有这个项目/仓库的权限；申请之后再试。',
     'blocker.forbidden.open': '打开权限页',
-    'blocker.timeout.hint': '无头浏览器可能没起来，重试一次通常就好。',
-    'blocker.exec.hint': '确认 opencli 已安装且在 PATH 里（which opencli）。',
+    'blocker.timeout.hint': '后台浏览器没起来，重试一次通常就好。',
+    'blocker.exec.hint': '确认 opencli 已经装好、在终端里能直接运行（which opencli）。',
     'blocker.unknown.title': '出了点问题',
     'panels.reading': '正在读取面板配置…',
     'panels.cardBroken': '这个模块起不来：{unit}（{reason}）',
@@ -472,7 +494,7 @@ export const zh = {
     'env.elapsed': '已等待 {seconds} 秒',
     'env.stepFailed.install': '装不上',
     'env.stepFailed.path': '装了但还找不到',
-    'env.stepFailed.shell': '执行通道不可用',
+    'env.stepFailed.shell': '连不上命令行',
     'env.toolchain.ok': '正常',
     'env.toolchain.warn': '还没完全准备好',
     'env.opencli.ok': '已就绪',
@@ -489,10 +511,10 @@ export const zh = {
     'env.fix.title': '怎么解决',
     'env.fix.why': '工作台用它自己那份后台工具（与你在终端里那套分开装，互不影响），这台机器上还没装好它。',
     'env.fix.whyPath': '后台工具装上了，但当前环境还找不到它 —— 通常是 PATH 或终端会话的问题。',
-    'env.fix.whyShell': '工作台拿不到执行命令的通道，所以取不了数据 —— 这一步你装不了，需要有人处理后台环境。',
+    'env.fix.whyShell': '工作台拿不到这台机器的命令行，所以取不了数据 —— 这一步你装不了，需要有人处理后台环境。',
     'env.fix.step': '在终端里运行下面这条命令，装好之后点「重试」：',
     'env.fix.stepPath': '新开一个终端窗口（或确认 npm 的全局 bin 目录在 PATH 里），然后点「重试」。',
-    'env.fix.stepShell': '重启一次工作台（或 dsh）；如果反复出现，说明执行通道没配好。',
+    'env.fix.stepShell': '重启一次工作台（或 dsh）；如果反复出现，说明工作台还是拿不到命令行。',
     'env.fix.permission': '权限不够：在命令前加 sudo 重跑，或先把 npm 的全局目录配到你的用户目录。',
     'env.fix.network': '网络不通：检查网络或代理设置后重试。',
     'env.fix.details': '详细输出（排障用）',
@@ -521,9 +543,9 @@ export const zh = {
     'env.warm.done': '已就绪（{n} 个站点）',
     'env.warm.short': '这次没提前连上 —— 不影响用，第一次取数会自己补',
     'env.unit.failed': '这个模块起不来',
-    'env.unit.failedHint': '它自己装配时报了错，别的模块不受影响。',
-    'env.unit.unchecked': '检测不了：拿不到执行通道',
-    'env.unit.uncheckedHint': '不是这个模块的问题，是执行通道不可用 —— 重启一次工作台再试。',
+    'env.unit.failedHint': '它自己启动时报了错，别的模块不受影响。',
+    'env.unit.unchecked': '检测不了：拿不到命令行',
+    'env.unit.uncheckedHint': '不是这个模块的问题，是工作台拿不到命令行 —— 重启一次工作台再试。',
     'adapterSet.not-configured': '没配置适配器集合，用默认的。',
     'adapterSet.no-profile': '找不到 profile，没法加载适配器集合；先用默认的。',
     'adapterSet.malformed': '适配器集合要写包名（如 @acme/adapters-set）；先用默认的。',
@@ -566,7 +588,7 @@ export const zh = {
     'sidebarEdition.official': '官方',
     'sidebarEdition.officialHint': '跟 dsh 官方一致、最稳：搜索、视图选项、显示更多、归档、添加工作区都齐，升级也不等我们适配。想省心就选它。',
     'sidebarEdition.custom': '自定义',
-    'sidebarEdition.customHint': '为多项目工作流做的：项目下拉一屏一个项目，会话按最近更新排，两端淡出、跑马灯、工坊 DIY 新会话。项目多时更顺手。',
+    'sidebarEdition.customHint': '为多项目工作流做的：项目下拉一屏一个项目，会话按最近更新排，名字自动滚动、两侧渐隐，工坊 DIY 新会话。项目多时更顺手。',
     'sidebarEdition.saving': '配置中…',
     'sidebarEdition.reloadRequired': '已写入。刷新页面后生效（不用重启工作台）。',
     'sidebarEdition.reload': '刷新页面',
@@ -595,25 +617,25 @@ export const zh = {
     'record.act.halt': '停',
     'approval.record.site': '站点',
     'approval.record.what': '录制功能',
-    'approval.record.lands': '落点',
+    'approval.record.lands': '保存到',
     'approval.record.noUrl': '没给站点地址（这次会被当场拒）',
     'approval.record.oneAction': '一次操作',
     'approval.record.noSwitch': '录完不会替你切回来（左栏底部会亮一条状态）',
-    'approval.longTask.what': '要停的那一趟',
-    'approval.longTask.signal': '停了只是让工作台发出中断信号 —— 平台侧那趟活儿的收尾看模块自己',
+    'approval.longTask.what': '要停的那次任务',
+    'approval.longTask.signal': '停了只是让工作台发出中断信号 —— 这次任务怎么收尾由模块自己负责',
     'approval.publish.module': '模块',
     'approval.publish.target': '目标',
     'approval.publish.version': '版本',
     'approval.publish.author': '作者',
-    'approval.publish.authorMissing': '未署名（提交用本机 git 身份）',
+    'approval.publish.authorMissing': '未署名',
     'approval.publish.registry': '源',
     'approval.publish.repo': '仓库',
     'approval.publish.branch': '分支',
     'approval.publish.defaultBranch': '默认分支',
-    'approval.publish.artifacts': '产物',
+    'approval.publish.artifacts': '打包文件',
     'approval.publish.index': '索引',
     'approval.publish.commits': '提交',
-    'approval.publish.twoCommits': '产物 + market.json 两个 commit，一次 push',
+    'approval.publish.twoCommits': '打包文件 + market.json 两次提交，一次推送',
     'approval.publish.reading': '读取中…',
     'approval.publish.changelog': '{version} 的更新日志',
     'approval.publish.changelogMissing': '这一版还没有更新日志（{version}），发布会被拦下',

package/dist/lib/dsh-client.d.ts

@@ -121,11 +121,13 @@ export interface DshSlots {
     onMutate?(callback: (name: string) => void): () => void;
 }
 /**
- * dsh 的语言服务：按命名空间注册字典，再取回那个命名空间的文案函数。
+ * dsh 的语言服务：按命名空间注册字典，再取回那个命名空间的文案函数；
+ * `resolveText` 按当前语言取一份字面量（字符串原样返回，映射按语言回退链取）。
  */
 export interface DshLocale {
     register(namespace: string, dictionaries: Record<string, Record<string, string>>): () => void;
     bind(namespace: string): Translate;
+    resolveText?(text: string | Readonly<Record<string, string | undefined>>): string;
 }
 /**
  * dsh 的布局服务：选面板、开关左栏、开合右栏；右栏宽度经可选的 panels 写。

package/package.json

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

package/src/contract/__tests__/unit-declaration.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, it } from 'vitest';
+import { unitTitleKey } from '../unit.js';
 import { declarationProblemsOf, readDeclaration } from '../unit-declaration.js';
 
 const declared = (tools: unknown) => ({
-  apiVersion: 2,
+  apiVersion: 3,
   unit: 'demo',
+  title: { zh: '演示', en: 'Demo' },
   card: null,
   tools,
   host: { inject: [] },
@@ -50,3 +52,33 @@ describe('清单里的工具声明', () => {
     expect(read.manifest?.tools).toEqual([{ name: 'workbench_demo_sync', writes: true }]);
   });
 });
+
+describe('清单里的名字（v3 起名字在顶层，是字面量）', () => {
+  it('中英各一份，都有就过', () => {
+    expect(declarationProblemsOf('@t/demo', declared([]))).toEqual([]);
+  });
+
+  it('少一门 / 空串 → 红，点名那一门', () => {
+    expect(declarationProblemsOf('@t/demo', { ...declared([]), title: { zh: '演示' } }).join('\n')).toMatch(
+      /title\.en/,
+    );
+    expect(
+      declarationProblemsOf('@t/demo', { ...declared([]), title: { zh: '演示', en: '  ' } }).join('\n'),
+    ).toMatch(/title\.en 要是非空字符串/);
+  });
+
+  it('★ v2 的老写法（card.titleKey）被点名，并给出迁移提示', () => {
+    const v2 = { ...declared([]), apiVersion: 2, card: { titleKey: 'demo.cardTitle', order: 7 } };
+    expect(declarationProblemsOf('@t/demo', v2).join('\n')).toMatch(/v3 把卡片标题挪成了顶层/);
+    const keyOnly = { ...declared([]), card: { titleKey: 'demo.cardTitle', order: 7 } };
+    expect(declarationProblemsOf('@t/demo', keyOnly).join('\n')).toMatch(/不认的键/);
+  });
+
+  it('★ 清单里的名字键由外壳合成：模块不用写、也别想写', () => {
+    const read = readDeclaration('@t/demo', { ...declared([]), card: { order: 7 } });
+
+    expect(read.problems).toEqual([]);
+    expect(read.manifest?.title).toEqual({ zh: '演示', en: 'Demo' });
+    expect(read.manifest?.card).toEqual({ titleKey: unitTitleKey('demo'), order: 7 });
+  });
+});

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

@@ -1,3 +1,5 @@
+import type { UnitTitle } from '../unit.js';
+
 export const BUNDLE_REGISTRIES_ROUTE = 'bundle-registries';
 
 export const BUNDLE_INSPECT_ROUTE = 'bundle-inspect';
@@ -174,11 +176,15 @@ export interface BundleCancellationPayload {
   readonly cancellation: BundleCancellation | null;
 }
 
+export type ModuleUpdateBlock = 'needs-workbench' | 'incompatible';
+
 export interface ModuleVersion {
   readonly unit: string;
   readonly pkg: string;
   readonly installed: string;
+  readonly title?: UnitTitle;
   readonly latest?: string;
+  readonly latestBlocked?: ModuleUpdateBlock;
   readonly local?: boolean;
   readonly refused?: readonly string[];
 }
@@ -189,6 +195,11 @@ export interface WorkbenchVersion {
   readonly latest?: string;
   readonly running?: string;
   readonly local?: boolean;
+  readonly followUp?: {
+    readonly id: string;
+    readonly kind: 'data-migration';
+    readonly hard: boolean;
+  };
 }
 
 export interface ModuleVersionsPayload {

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

@@ -4,6 +4,7 @@ export const MARKET_DISCOVER_ROUTE = 'panels/market-discover';
 export const MARKET_DOC_ROUTE = 'panels/market-doc';
 export const MARKET_PUBLISH_PREVIEW_ROUTE = 'panels/market-publish-preview';
 export const MARKET_SOURCES_RESOURCE = 'market-sources';
+export const MARKET_SOURCES_ROUTE = 'panels/market-sources';
 export const MARKET_WORKBENCH_LABEL = 'workbench';
 
 export type MarketSourceKind = 'http' | 'git';

package/src/contract/unit-declaration.ts

@@ -1,10 +1,11 @@
-import type { UnitHostNeeds, UnitManifest } from '../contract/unit.js';
+import type { UnitHostNeeds, UnitManifest, UnitTitle } from '../contract/unit.js';
+import { unitTitleKey } from '../contract/unit.js';
 import { needsProblemsOf, type Need } from './needs.js';
 
 /**
  * 声明协议当前版本；模块清单的 dsh.workbench.apiVersion 要写这个整数。
  */
-export const WORKBENCH_API_VERSION = 2;
+export const WORKBENCH_API_VERSION = 3;
 
 /**
  * 外壳愿意认的协议版本；不在表里的模块当场被拒，不猜语义。
@@ -12,10 +13,9 @@ export const WORKBENCH_API_VERSION = 2;
 export const SUPPORTED_API_VERSIONS: readonly number[] = [WORKBENCH_API_VERSION];
 
 /**
- * 清单里那半张卡片声明：文案键加排序位；卡片默认显不显示不在这里（那是运行期面板配置的事）。
+ * 清单里那半张卡片声明：只剩排序位；卡片默认显不显示不在这里（那是运行期面板配置的事）。
  */
 export interface UnitCardDeclaration {
-  readonly titleKey: string;
   readonly order: number;
 }
 
@@ -29,11 +29,12 @@ export interface UnitToolDeclaration {
 }
 
 /**
- * 模块清单里 dsh.workbench 那一段的完整形状（协议版本、单元 id、卡片、工具、宿主与环境需要）。
+ * 模块清单里 dsh.workbench 那一段的完整形状（协议版本、单元 id、名字、卡片、工具、宿主与环境需要）。
  */
 export interface UnitDeclaration {
   readonly apiVersion: number;
   readonly unit: string;
+  readonly title: UnitTitle;
   readonly card: UnitCardDeclaration | null;
   readonly tools: readonly UnitToolDeclaration[];
   readonly host: UnitHostNeeds;
@@ -46,6 +47,7 @@ export interface UnitDeclaration {
 export const DECLARATION_KEYS: readonly string[] = [
   'apiVersion',
   'unit',
+  'title',
   'card',
   'tools',
   'host',
@@ -58,12 +60,14 @@ export const DECLARATION_KEYS: readonly string[] = [
 export const DECLARATION_REQUIRED_KEYS: readonly string[] = [
   'apiVersion',
   'unit',
+  'title',
   'card',
   'tools',
   'host',
 ];
 
-const CARD_KEYS = ['titleKey', 'order'];
+const CARD_KEYS = ['order'];
+const TITLE_KEYS = ['zh', 'en'];
 const TOOL_KEYS = ['name', 'writes', 'key'];
 
 const TOOL_KEY_SHAPE = /^[a-z][a-zA-Z0-9]*$/;
@@ -77,6 +81,17 @@ function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/**
+ * 读一份声明里的协议版本；不是对象或 apiVersion 不是整数时给 undefined。
+ * @param raw 清单里 dsh.workbench 那段原始值。
+ * @returns 声明声明的协议版本，读不出来时 undefined。
+ */
+export function declarationApiVersionOf(raw: unknown): number | undefined {
+  if (!isRecord(raw)) return undefined;
+  const version = raw.apiVersion;
+  return Number.isInteger(version) ? (version as number) : undefined;
+}
+
 function outsideKeys(value: Readonly<Record<string, unknown>>, allowed: readonly string[]): string[] {
   return Object.keys(value).filter((key) => !allowed.includes(key));
 }
@@ -110,10 +125,9 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
   }
   if (!Number.isInteger(version) || !SUPPORTED_API_VERSIONS.includes(version as number)) {
     const hint =
-      version === 1
-        ? ` —— v2 把 \`env\` 的三张表（command / plugins / libs）换成了 \`needs\`：` +
-          '把外部需要逐条写成 `{ kind, name, purpose, ... }`（kind 是 bin / extension / lib / env），' +
-          '再把 apiVersion 改成 2'
+      version === 2
+        ? ' —— v3 把卡片标题挪成了顶层 `title`（`{ "zh": "…", "en": "…" }` 字面量）：' +
+          '把 `card.titleKey` 删掉、在顶层写 title，再把 apiVersion 改成 3'
         : '';
     return [
       `${subject}: dsh.workbench.apiVersion 是 ${JSON.stringify(version)}，这里只认 ` +
@@ -140,6 +154,29 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
     }
   }
 
+  const title = raw.title;
+  if (title !== undefined) {
+    if (!isRecord(title)) {
+      problems.push(
+        `${subject}: dsh.workbench.title 要是对象（中英各一份），现在是 ${JSON.stringify(title)}`,
+      );
+    } else {
+      const extra = outsideKeys(title, TITLE_KEYS);
+      if (extra.length > 0) {
+        problems.push(
+          `${subject}: dsh.workbench.title 里有不认的键 ${listOf(extra)} —— title 只有 ${listOf(TITLE_KEYS)}`,
+        );
+      }
+      for (const language of TITLE_KEYS) {
+        if (text(title[language]) === '') {
+          problems.push(
+            `${subject}: dsh.workbench.title.${language} 要是非空字符串（市场和面板里显示的名字）`,
+          );
+        }
+      }
+    }
+  }
+
   const card = raw.card;
   if (card !== undefined && card !== null) {
     if (!isRecord(card)) {
@@ -149,12 +186,9 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
       if (extra.length > 0) {
         problems.push(
           `${subject}: dsh.workbench.card 里有不认的键 ${listOf(extra)} —— card 只有 ${listOf(CARD_KEYS)}` +
-            `（卡片默认显不显示由运行期的面板配置决定，清单里没有这一位）`,
+            `（名字写在顶层的 title 里；卡片默认显不显示由运行期的面板配置决定，清单里没有这一位）`,
         );
       }
-      if (text(card.titleKey) === '') {
-        problems.push(`${subject}: dsh.workbench.card.titleKey 要是非空字符串（面板那一格的文案键）`);
-      }
       if (typeof card.order !== 'number' || !Number.isFinite(card.order)) {
         problems.push(`${subject}: dsh.workbench.card.order 要是数字，现在是 ${JSON.stringify(card.order)}`);
       }
@@ -257,16 +291,18 @@ export function readDeclaration(subject: string, raw: unknown): DeclarationRead
   const needsRead = needsProblemsOf(subject, declaration.needs);
   if (needsRead.errors.length > 0) return { problems: needsRead.errors, warnings: needsRead.warnings };
   const card = declaration.card;
+  const id = text(declaration.unit);
   return {
     declaration,
     problems: [],
     manifest: {
-      id: text(declaration.unit),
+      id,
+      title: { zh: text(declaration.title.zh), en: text(declaration.title.en) },
       card:
         card === null
           ? null
           : {
-              titleKey: text(card.titleKey),
+              titleKey: unitTitleKey(id),
               order: card.order,
             },
       tools: declaration.tools.map((tool) => ({

package/src/contract/unit.ts

@@ -1,5 +1,22 @@
 import type { ExtensionNeed, LibNeed, Need } from './needs.js';
 
+/**
+ * 模块的人类可读名字：中英各一份，写在 package.json 的 dsh.workbench.title 里。
+ */
+export interface UnitTitle {
+  readonly zh: string;
+  readonly en: string;
+}
+
+/**
+ * 外壳替模块名合成的词表键：模块自己不必写名字键，名字直接从清单里的 title 注册进来。
+ * @param unit 单元 id。
+ * @returns 该单元名字在词表里的键。
+ */
+export function unitTitleKey(unit: string): string {
+  return `dsh-workbench.unit.${unit}.title`;
+}
+
 /**
  * 一张卡片在清单里的静态声明（文案键加排序位）；默认显不显示由运行期面板配置定。
  */
@@ -33,10 +50,11 @@ export interface PluginRelease {
 }
 
 /**
- * 装配期用的模块清单：单元 id、卡片、工具、宿主服务与环境需要，比声明少一层协议包装。
+ * 装配期用的模块清单：单元 id、名字、卡片、工具、宿主服务与环境需要，比声明少一层协议包装。
  */
 export interface UnitManifest {
   readonly id: string;
+  readonly title?: UnitTitle;
   readonly card: UnitCard | null;
   readonly tools: readonly UnitTool[];
   readonly host: UnitHostNeeds;

package/src/contract/workbench-contract.ts

@@ -15,7 +15,9 @@ export type ProvisionAction =
   | 'cancel-install'
   | 'update-plugin'
   | 'uninstall-plugin'
-  | 'update-workbench';
+  | 'update-workbench'
+  | 'migrate-workbench'
+  | 'dismiss-followup';
 
 /**
  * 宿主对「这个单元现在能不能用」的那份读数：状态汇总加逐条 need 的细节。

package/src/host/__tests__/provision.test.ts

@@ -16,6 +16,8 @@ describe('provision 请求体：每类动作各有各的目标字段', () => {
       ['update-plugin', 'name'],
       ['uninstall-plugin', 'name'],
       ['update-workbench', 'name'],
+      ['migrate-workbench', 'name'],
+      ['dismiss-followup', 'id'],
     ]);
   });
 

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

@@ -2,12 +2,16 @@ import { describe, expect, it } from 'vitest';
 import type { ExtensionNeed, LibNeed, SupplySource } from '../../contract/needs.js';
 import { buildSupplyIndex, type SupplyDeclaration } from '../supply-index.js';
 
-function npm(pkg?: string, registryEnv = 'DSH_WB_REGISTRY'): SupplySource {
+function npm(
+  pkg?: string,
+  registryEnv = 'DSH_WB_REGISTRY',
+  registryDefault = 'https://registry.invalid/',
+): SupplySource {
   return {
     kind: 'npm',
     ...(pkg === undefined ? {} : { package: pkg }),
     registryEnv,
-    registryDefault: 'https://registry.invalid/',
+    registryDefault,
   };
 }
 
@@ -77,23 +81,55 @@ describe('供给索引：一个包只有一个来源', () => {
     expect(index.sourcesOf('extension', 'coding')).toEqual([npm('opencli-plugin-coding')]);
   });
 
-  it('★★ 共用库两家用不同的 registryEnv：判冲突，即使地址相同', () => {
+  it('★★ 共用库两家用不同的 registryEnv、解析到同一个地址：收成一家，不算冲突', () => {
     const index = buildSupplyIndex([
       manifest('argocd', [lib('opencli-workflow', [npm(undefined, 'DSH_WORKBENCH_ARGOCD_REGISTRY')])]),
       manifest('cmdb', [lib('opencli-workflow', [npm(undefined, 'DSH_WORKBENCH_CMDB_REGISTRY')])]),
     ]);
 
+    expect(index.conflicts).toEqual([]);
+    expect(index.entryOf('lib', 'opencli-workflow')?.conflicted).toBe(false);
+    expect(index.entryOf('lib', 'opencli-workflow')?.declarers).toEqual(['argocd', 'cmdb']);
+    expect(index.sourcesOf('lib', 'opencli-workflow')).toHaveLength(1);
+  });
+
+  it('★★ registryEnv 名不同、其中一家被环境变量指到别处：判冲突', () => {
+    const index = buildSupplyIndex(
+      [
+        manifest('jenkins', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_JENKINS_REGISTRY')])]),
+        manifest('argocd', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_ARGOCD_REGISTRY')])]),
+      ],
+      { env: { DSH_WB_JENKINS_REGISTRY: 'https://mirror.invalid/' } },
+    );
+
+    expect(index.conflicts.map((item) => item.kind)).toEqual(['source-mismatch']);
+    expect(index.sourcesOf('lib', 'opencli-workflow')).toEqual([]);
+  });
+
+  it('★★ 两家默认源就不同：判冲突，哪怕 registryEnv 同名', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_REGISTRY', 'https://r-a.invalid/')])]),
+      manifest('b', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_REGISTRY', 'https://r-b.invalid/')])]),
+    ]);
+
     expect(index.conflicts).toHaveLength(1);
-    expect(index.conflicts[0]?.kind).toBe('source-mismatch');
     expect(index.entryOf('lib', 'opencli-workflow')?.conflicted).toBe(true);
-    expect(index.sourcesOf('lib', 'opencli-workflow')).toEqual([]);
+  });
+
+  it('★ 两家都没写默认源、registryEnv 又不同：解析不出地址，按名字判冲突', () => {
+    const index = buildSupplyIndex([
+      manifest('a', [lib('opencli-workflow', [{ kind: 'npm', registryEnv: 'DSH_WB_A_REGISTRY' }])]),
+      manifest('b', [lib('opencli-workflow', [{ kind: 'npm', registryEnv: 'DSH_WB_B_REGISTRY' }])]),
+    ]);
+
+    expect(index.conflicts).toHaveLength(1);
   });
 
   it('★★ 三家三个源：同一个包只报一条冲突，declarers 合并齐', () => {
     const index = buildSupplyIndex([
       manifest('a', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_A_REGISTRY')])]),
       manifest('b', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_B_REGISTRY')])]),
-      manifest('c', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_C_REGISTRY')])]),
+      manifest('c', [lib('opencli-workflow', [npm(undefined, 'DSH_WB_C_REGISTRY', 'https://mirror.invalid/')])]),
     ]);
 
     expect(index.conflicts).toHaveLength(1);