@dsh-workbench/shared 0.3.11 → 1.0.0-beta.1

package/src/contract/unit-capability.ts

@@ -0,0 +1,37 @@
+import type { Need, NeedKind } from './needs.js';
+import type { ProvisionProblem } from './plugin-source.js';
+
+/**
+ * 一条 need 探出来的样子：状态、给人看的一句、以及能照做的修法。
+ */
+export interface NeedState {
+  readonly id: string;
+  readonly kind: NeedKind;
+  readonly name: string;
+  readonly status: 'ok' | 'missing' | 'outdated' | 'unsatisfied' | 'unchecked';
+  readonly detail: string;
+  readonly command?: string;
+  readonly missing?: readonly string[];
+  readonly installed?: string;
+  readonly latest?: string;
+  readonly provision?: 'ready' | ProvisionProblem;
+}
+
+/**
+ * 一个单元的能力结论：unit 一级只做汇总，缺什么逐条看 needs。
+ */
+export interface UnitCapability {
+  readonly unit: string;
+  readonly status: 'ok' | 'degraded' | 'missing' | 'outdated' | 'unchecked' | 'unsupported' | 'failed';
+  readonly needs: readonly NeedState[];
+  readonly detail?: string;
+  readonly released?: boolean;
+}
+
+/**
+ * 探一个单元的输入：单元 id 加它声明的 need 列表。
+ */
+export interface NeedProbeInput {
+  readonly unit: string;
+  readonly needs: readonly Need[];
+}

package/src/{host → contract}/unit-declaration.ts

@@ -1,9 +1,10 @@
-import type { UnitEnvNeeds, UnitHostNeeds, UnitManifest } from '../api/unit.js';
+import type { UnitHostNeeds, UnitManifest } from '../contract/unit.js';
+import { needsProblemsOf, type Need } from './needs.js';
 
 /**
  * 声明协议当前版本；模块清单的 dsh.workbench.apiVersion 要写这个整数。
  */
-export const WORKBENCH_API_VERSION = 1;
+export const WORKBENCH_API_VERSION = 2;
 
 /**
  * 外壳愿意认的协议版本；不在表里的模块当场被拒，不猜语义。
@@ -36,11 +37,11 @@ export interface UnitDeclaration {
   readonly card: UnitCardDeclaration | null;
   readonly tools: readonly UnitToolDeclaration[];
   readonly host: UnitHostNeeds;
-  readonly env?: UnitEnvNeeds;
+  readonly needs?: readonly Need[];
 }
 
 /**
- * 协议认得的全部键；写了别的键不会被采纳（外壳静默忽略），所以字段名拼错不会有提示。
+ * 协议认得的全部键；写了别的键这份清单会被拒（`protocol` 判据与运行时同一套），拼错当场报出来。
  */
 export const DECLARATION_KEYS: readonly string[] = [
   'apiVersion',
@@ -48,11 +49,11 @@ export const DECLARATION_KEYS: readonly string[] = [
   'card',
   'tools',
   'host',
-  'env',
+  'needs',
 ];
 
 /**
- * 协议要求必写的键；env 不在其中（没有环境需要就不写）。
+ * 协议要求必写的键；needs 不在其中（没有环境需要就不写）。
  */
 export const DECLARATION_REQUIRED_KEYS: readonly string[] = [
   'apiVersion',
@@ -104,13 +105,19 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
   if (version === undefined) {
     return [
       `${subject}: dsh.workbench 没有 apiVersion —— 协议从 v${WORKBENCH_API_VERSION} 起，` +
-        `写 \`"apiVersion": ${WORKBENCH_API_VERSION}\`。缺它 = 外壳不认这个模块（ADR-0038 §2.3）`,
+        `写 \`"apiVersion": ${WORKBENCH_API_VERSION}\`。缺它 = 外壳不认这个模块`,
     ];
   }
   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'
+        : '';
     return [
       `${subject}: dsh.workbench.apiVersion 是 ${JSON.stringify(version)}，这里只认 ` +
-        `${SUPPORTED_API_VERSIONS.join(' / ')}（要整数）`,
+        `${SUPPORTED_API_VERSIONS.join(' / ')}（要整数）${hint}`,
     ];
   }
 
@@ -120,7 +127,7 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
   if (unknown.length > 0) {
     problems.push(
       `${subject}: dsh.workbench 里有协议 v${WORKBENCH_API_VERSION} 不认识的键 ${listOf(unknown)} —— ` +
-        `只有 ${listOf(DECLARATION_KEYS)}。（拼错的键会被外壳**静默忽略**：那句声明等于没写）`,
+        `只有 ${listOf(DECLARATION_KEYS)}。（协议外的键会让这份清单被拒：那句声明等于没写）`,
     );
   }
 
@@ -224,13 +231,6 @@ export function declarationProblemsOf(subject: string, raw: unknown): readonly s
     }
   }
 
-  if (raw.env !== undefined && !isRecord(raw.env)) {
-    problems.push(
-      `${subject}: dsh.workbench.env 要是对象（command / plugins / libs）—— ` +
-        `语义由门禁的 env 判据查，这里只查形状`,
-    );
-  }
-
   return problems;
 }
 
@@ -241,6 +241,7 @@ export interface DeclarationRead {
   readonly declaration?: UnitDeclaration;
   readonly manifest?: UnitManifest;
   readonly problems: readonly string[];
+  readonly warnings: readonly string[];
 }
 
 /**
@@ -251,8 +252,10 @@ export interface DeclarationRead {
  */
 export function readDeclaration(subject: string, raw: unknown): DeclarationRead {
   const problems = declarationProblemsOf(subject, raw);
-  if (problems.length > 0) return { problems };
+  if (problems.length > 0) return { problems, warnings: [] };
   const declaration = raw as UnitDeclaration;
+  const needsRead = needsProblemsOf(subject, declaration.needs);
+  if (needsRead.errors.length > 0) return { problems: needsRead.errors, warnings: needsRead.warnings };
   const card = declaration.card;
   return {
     declaration,
@@ -274,7 +277,8 @@ export function readDeclaration(subject: string, raw: unknown): DeclarationRead
         inject: [...(declaration.host.inject ?? [])],
         ...(declaration.host.optional === undefined ? {} : { optional: [...declaration.host.optional] }),
       },
-      ...(declaration.env === undefined ? {} : { env: declaration.env }),
+      ...(declaration.needs === undefined ? {} : { needs: declaration.needs }),
     },
+    warnings: needsRead.warnings,
   };
 }

package/src/contract/unit.ts

@@ -0,0 +1,76 @@
+import type { ExtensionNeed, LibNeed, Need } from './needs.js';
+
+/**
+ * 一张卡片在清单里的静态声明（文案键加排序位）；默认显不显示由运行期面板配置定。
+ */
+export interface UnitCard {
+  readonly titleKey: string;
+  readonly order: number;
+}
+
+/**
+ * 一条工具在清单里的样子：全名加会不会写；审批按 writes 认领。
+ */
+export interface UnitTool {
+  readonly name: string;
+  readonly writes: boolean;
+}
+
+/**
+ * 模块要外壳的哪些服务：inject 缺一个就挂不上，optional 缺了照挂。
+ */
+export interface UnitHostNeeds {
+  readonly inject: readonly string[];
+  readonly optional?: readonly string[];
+}
+
+/**
+ * 已装插件与源上最新版那一对，用来判该不该提示升级；latest 缺省表示还没查到。
+ */
+export interface PluginRelease {
+  readonly installed: string;
+  readonly latest?: string;
+}
+
+/**
+ * 装配期用的模块清单：单元 id、卡片、工具、宿主服务与环境需要，比声明少一层协议包装。
+ */
+export interface UnitManifest {
+  readonly id: string;
+  readonly card: UnitCard | null;
+  readonly tools: readonly UnitTool[];
+  readonly host: UnitHostNeeds;
+  readonly needs?: readonly Need[];
+}
+
+/**
+ * 模块声明的全部环境需要（没写就是空表）。
+ * @param manifest 模块清单。
+ * @returns need 列表。
+ */
+export function needsOf(manifest: UnitManifest): readonly Need[] {
+  return manifest.needs ?? [];
+}
+
+/**
+ * 宿主能代装的那些需要：只有写了 `sources` 的 extension / lib 算。
+ * @param manifest 模块清单。
+ * @returns 可代装的 need 列表。
+ */
+export function provisionableNeedsOf(manifest: UnitManifest): readonly (ExtensionNeed | LibNeed)[] {
+  return needsOf(manifest).filter(
+    (need): need is ExtensionNeed | LibNeed =>
+      (need.kind === 'extension' || need.kind === 'lib') && (need.sources ?? []).length > 0,
+  );
+}
+
+/**
+ * 市场门槛要看的那些需要：声明了 extension / lib 就算（不要求写了来源）。
+ * @param manifest 模块清单。
+ * @returns extension / lib 的 need 列表。
+ */
+export function supplyNeedsOf(manifest: UnitManifest): readonly (ExtensionNeed | LibNeed)[] {
+  return needsOf(manifest).filter(
+    (need): need is ExtensionNeed | LibNeed => need.kind === 'extension' || need.kind === 'lib',
+  );
+}

package/src/contract/workbench-contract.ts

@@ -0,0 +1,30 @@
+import type { NeedState } from '../contract/unit-capability.js';
+
+/**
+ * 供给动作的那几档（装 / 升 / 卸，模块、共用依赖与插件各一套）；写口按它分派。
+ */
+export type ProvisionAction =
+  | 'install'
+  | 'update'
+  | 'uninstall'
+  | 'update-dependency'
+  | 'install-bundle'
+  | 'install-version'
+  | 'update-bundle'
+  | 'remove-bundle'
+  | 'cancel-install'
+  | 'update-plugin'
+  | 'uninstall-plugin'
+  | 'update-workbench';
+
+/**
+ * 宿主对「这个单元现在能不能用」的那份读数：状态汇总加逐条 need 的细节。
+ */
+export interface CapabilityPayload {
+  readonly unit: string;
+  readonly status: 'ok' | 'degraded' | 'missing' | 'outdated' | 'unchecked' | 'unsupported' | 'failed';
+  readonly needs: readonly NeedState[];
+  readonly detail?: string;
+  readonly released?: boolean;
+}
+

package/src/host/__tests__/adapter-set.test.ts

@@ -0,0 +1,228 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { DshHostContext } from '../../api/dsh.js';
+import { loadAdapterSet, resolveAdapterSet } from '../adapter-set.js';
+
+const dirs: string[] = [];
+
+function profileOf(): string {
+  const dir = mkdtempSync(join(tmpdir(), 'wb-adapter-set-'));
+  dirs.push(dir);
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({ name: 'fixture-profile', private: true, type: 'module' }));
+  return dir;
+}
+
+function install(dir: string, name: string, source: string): void {
+  const pkg = join(dir, 'node_modules', name);
+  mkdirSync(pkg, { recursive: true });
+  writeFileSync(
+    join(pkg, 'package.json'),
+    JSON.stringify({ name, version: '1.0.0', type: 'module', exports: { '.': './index.js' } }),
+  );
+  writeFileSync(join(pkg, 'index.js'), source);
+}
+
+function installEsmOnly(dir: string, name: string, source: string): void {
+  const pkg = join(dir, 'node_modules', name);
+  mkdirSync(pkg, { recursive: true });
+  writeFileSync(
+    join(pkg, 'package.json'),
+    JSON.stringify({ name, version: '1.0.0', type: 'module', exports: { '.': { import: './index.js' } } }),
+  );
+  writeFileSync(join(pkg, 'index.js'), source);
+}
+
+function installDual(dir: string, name: string, esmSource: string, cjsSource: string): void {
+  const pkg = join(dir, 'node_modules', name);
+  mkdirSync(pkg, { recursive: true });
+  writeFileSync(
+    join(pkg, 'package.json'),
+    JSON.stringify({
+      name,
+      version: '1.0.0',
+      exports: { '.': { import: './index.mjs', require: './index.cjs' } },
+    }),
+  );
+  writeFileSync(join(pkg, 'index.mjs'), esmSource);
+  writeFileSync(join(pkg, 'index.cjs'), cjsSource);
+}
+
+function ctxOf(dir: string | null): DshHostContext {
+  return {
+    get: (key: string) => (key === 'profileContext' && dir !== null ? { dir } : undefined),
+  } as unknown as DshHostContext;
+}
+
+const FULL = `{
+  apiVersion: 1,
+  id: 'fixture',
+  version: '1.0.0',
+  data: {
+    read: async () => ({ ok: true, data: {} }),
+    request: async () => ({ ok: true, data: {} }),
+    requestMany: async () => ({}),
+    submit: async () => ({ ok: true, data: {} }),
+  },
+  supply: {
+    resolvePluginSource: () => ({ ok: false, problem: 'not-declared' }),
+    libInstallCommand: () => '',
+    pluginInstallPlan: () => ({ ok: false, problem: 'not-declared' }),
+    latestVersion: async () => undefined,
+    missingReleaseParts: async () => [],
+    probeRelease: async () => undefined,
+    splitNpmSpec: () => undefined,
+  },
+  profile: {
+    dirOf: () => null,
+    dshPlugins: () => () => ({ ok: true, plugins: [] }),
+    selfUpdateView: () => undefined,
+  },
+  probe: {
+    probeUnits: async () => [],
+    registerPreflight: () => {},
+    declaredPluginCommands: () => new Map(),
+  },
+}`;
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+describe('loadAdapterSet：从 profile 解析 set，失败不抛', () => {
+  it('没配置 → not-configured（不是错误）', async () => {
+    const loaded = await loadAdapterSet(ctxOf(profileOf()), undefined);
+    expect(loaded).toMatchObject({ ok: false, failure: 'not-configured' });
+  });
+
+  it('不是包名 → malformed', async () => {
+    const loaded = await loadAdapterSet(ctxOf(profileOf()), './local-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'malformed' });
+  });
+
+  it('没有 profile → no-profile', async () => {
+    const loaded = await loadAdapterSet(ctxOf(null), 'fixture-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'no-profile' });
+  });
+
+  it('没有 profile 时先报 no-profile，不先纠结包名', async () => {
+    const loaded = await loadAdapterSet(ctxOf(null), './local-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'no-profile' });
+  });
+
+  it('profile 里没装 → not-resolvable', async () => {
+    const loaded = await loadAdapterSet(ctxOf(profileOf()), 'fixture-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'not-resolvable' });
+  });
+
+  it('只导出 import 条件的 ESM 包也能从 profile 解析', async () => {
+    const dir = profileOf();
+    installEsmOnly(dir, 'esm-set', `export function createAdapterSet() { return ${FULL}; }`);
+    const loaded = await loadAdapterSet(ctxOf(dir), 'esm-set');
+    expect(loaded.ok).toBe(true);
+  });
+
+  it('双条件包走 import 那一份入口，不是 require 的 CJS 面', async () => {
+    const dir = profileOf();
+    installDual(
+      dir,
+      'dual-set',
+      `export function createAdapterSet() { return ${FULL}; }`,
+      'module.exports = { notTheFactory: 1 };',
+    );
+    const loaded = await loadAdapterSet(ctxOf(dir), 'dual-set');
+    expect(loaded.ok).toBe(true);
+  });
+
+  it('正常 set → ok，返回 core 成员', async () => {
+    const dir = profileOf();
+    install(dir, 'fixture-set', `export function createAdapterSet() { return ${FULL}; }`);
+    const loaded = await loadAdapterSet(ctxOf(dir), 'fixture-set');
+    expect(loaded.ok).toBe(true);
+    if (loaded.ok) {
+      expect(loaded.spec).toBe('fixture-set');
+      expect(loaded.set.data).toBeDefined();
+      expect(loaded.set.probe).toBeDefined();
+    }
+  });
+
+  it('没有工厂 → bad-export', async () => {
+    const dir = profileOf();
+    install(dir, 'fixture-set', 'export const nope = 1;');
+    const loaded = await loadAdapterSet(ctxOf(dir), 'fixture-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'bad-export' });
+  });
+
+  it('工厂抛错 → factory-failed', async () => {
+    const dir = profileOf();
+    install(dir, 'fixture-set', 'export function createAdapterSet() { throw new Error("boom"); }');
+    const loaded = await loadAdapterSet(ctxOf(dir), 'fixture-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'factory-failed' });
+  });
+
+  it('协议版本不对 → incompatible-version', async () => {
+    const dir = profileOf();
+    install(dir, 'fixture-set', `export function createAdapterSet() { return { ...${FULL}, apiVersion: 2 }; }`);
+    const loaded = await loadAdapterSet(ctxOf(dir), 'fixture-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'incompatible-version' });
+  });
+
+  it('少成员 → missing-member，点名缺哪个', async () => {
+    const dir = profileOf();
+    install(
+      dir,
+      'fixture-set',
+      'export function createAdapterSet() { return { apiVersion: 1, id: "fixture", version: "1.0.0", data: { read: async () => ({ ok: true, data: {} }) }, profile: { dirOf: () => null }, probe: { probeUnits: async () => [] } }; }',
+    );
+    const loaded = await loadAdapterSet(ctxOf(dir), 'fixture-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'missing-member' });
+    if (!loaded.ok) expect(loaded.detail).toContain('supply');
+  });
+
+  it('缺 id / version → missing-member，点名', async () => {
+    const dir = profileOf();
+    install(
+      dir,
+      'fixture-set',
+      'export function createAdapterSet() { return { apiVersion: 1, data: { read: async () => ({ ok: true, data: {} }) }, supply: { resolvePluginSource: () => ({ ok: false, problem: "not-declared" }) }, profile: { dirOf: () => null }, probe: { probeUnits: async () => [] } }; }',
+    );
+    const loaded = await loadAdapterSet(ctxOf(dir), 'fixture-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'missing-member' });
+    if (!loaded.ok) expect(loaded.detail).toContain('id');
+  });
+
+  it('关键方法不是函数 → missing-member', async () => {
+    const dir = profileOf();
+    install(
+      dir,
+      'fixture-set',
+      'export function createAdapterSet() { return { apiVersion: 1, id: "fixture", version: "1.0.0", data: {}, supply: { resolvePluginSource: () => ({ ok: false, problem: "not-declared" }) }, profile: { dirOf: () => null }, probe: { probeUnits: async () => [] } }; }',
+    );
+    const loaded = await loadAdapterSet(ctxOf(dir), 'fixture-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'missing-member' });
+    if (!loaded.ok) expect(loaded.detail).toContain('data.read');
+  });
+
+  it('完整 set → 不建、不 seed 默认集合', async () => {
+    const dir = profileOf();
+    install(
+      dir,
+      'full-set',
+      `export function createAdapterSet() { return ${FULL.replace('  probe: {', '  modules: new Proxy({}, { get: () => () => undefined }), runtime: new Proxy({}, { get: () => () => undefined }), plugins: new Proxy({}, { get: () => () => undefined }), actions: new Proxy({}, { get: () => () => undefined }),\n  probe: {')}; }`,
+    );
+    const resolved = await resolveAdapterSet(ctxOf(dir), 'full-set', async () => {
+      throw new Error('完整 set 不该建默认');
+    });
+    expect(resolved.load.ok).toBe(true);
+    expect(resolved.usedDefaults).toBe(false);
+    expect(resolved.set.id).toBe('fixture');
+  });
+
+  it('入口加载失败 → import-failed', async () => {
+    const dir = profileOf();
+    install(dir, 'fixture-set', 'export function createAdapterSet( {');
+    const loaded = await loadAdapterSet(ctxOf(dir), 'fixture-set');
+    expect(loaded).toMatchObject({ ok: false, failure: 'import-failed' });
+  });
+});

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

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import type { DshHostContext } from '../../api/dsh.js';
+import type { WorkbenchAdapters } from '../adapters.js';
+import { adaptersOf, WORKBENCH_ADAPTERS } from '../adapters.js';
+
+describe('适配器端口：apply 期读自己刚 provide 的服务', () => {
+  it('严格 get 还看不见时，按非严格读得到', () => {
+    const adapters = {} as WorkbenchAdapters;
+    const seen: Array<boolean | undefined> = [];
+    const ctx = {
+      get: (name: string, strict?: boolean) => {
+        if (name !== WORKBENCH_ADAPTERS) return undefined;
+        seen.push(strict);
+        return strict === false ? adapters : undefined;
+      },
+    } as unknown as DshHostContext;
+
+    expect(adaptersOf(ctx)).toBe(adapters);
+    expect(seen).toEqual([false]);
+  });
+
+  it('真的没有 provide 时照旧抛', () => {
+    const ctx = { get: () => undefined } as unknown as DshHostContext;
+
+    expect(() => adaptersOf(ctx)).toThrow('workbenchAdapters 未提供');
+  });
+});

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

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'vitest';
+import {
+  CHANGELOG_FILE,
+  appendChangelogEntry,
+  changelogHasEntry,
+  changelogSectionOf,
+  changelogSkeleton,
+  parseChangelog,
+} from '../changelog.js';
+
+const SAMPLE = [
+  '# 更新日志',
+  '',
+  '## v1.2.0',
+  '',
+  '`2026-10-26`',
+  '',
+  '### ✨ 新增',
+  '',
+  '- 模块详情能看说明与更新日志',
+  '',
+  '### 🐛 修复',
+  '',
+  '- 发布审批会显示这一版的更新日志',
+  '',
+  '## v1.1.0',
+  '',
+  '`2026-10-01`',
+  '',
+  '- 旧版本的一条',
+  '',
+].join('\n');
+
+describe('parseChangelog', () => {
+  it('按 v 前缀的版本标题切段，正文保留分类与列表', () => {
+    const sections = parseChangelog(SAMPLE);
+    expect(sections.map((one) => one.version)).toEqual(['1.2.0', '1.1.0']);
+    expect(sections[0]?.body).toContain('`2026-10-26`');
+    expect(sections[0]?.body).toContain('### ✨ 新增');
+    expect(sections[0]?.body).toContain('- 模块详情能看说明与更新日志');
+    expect(sections[1]?.body).toContain('- 旧版本的一条');
+  });
+
+  it('文件名常量是 CHANGELOG.md', () => {
+    expect(CHANGELOG_FILE).toBe('CHANGELOG.md');
+  });
+});
+
+describe('changelogSectionOf / changelogHasEntry', () => {
+  it('认 v 前缀、方括号与不带方括号的版本标题', () => {
+    expect(changelogSectionOf(SAMPLE, 'v1.2.0')).toContain('更新日志');
+    expect(changelogSectionOf(SAMPLE, '1.1.0')).toContain('旧版本的一条');
+    expect(changelogSectionOf('# 更新日志\n\n## [1.0.0] - 2026-10-01\n\n- 一条\n', '1.0.0')).toBe('- 一条');
+  });
+
+  it('只有版本标题和日期不算一条记录', () => {
+    const empty = '# 更新日志\n\n## v1.0.0\n\n`2026-10-26`\n\n### ✨ 新增\n';
+    expect(changelogHasEntry(empty, '1.0.0')).toBe(false);
+    expect(changelogHasEntry(SAMPLE, '1.2.0')).toBe(true);
+    expect(changelogHasEntry(SAMPLE, '9.9.9')).toBe(false);
+  });
+});
+
+describe('appendChangelogEntry', () => {
+  it('新版本插在最前面，带日期行与 emoji 分类', () => {
+    const next = appendChangelogEntry(SAMPLE, { version: '1.3.0', kind: 'added', note: '新的东西', date: '2026-10-27' });
+    expect(parseChangelog(next).map((one) => one.version)).toEqual(['1.3.0', '1.2.0', '1.1.0']);
+    expect(next).toContain('## v1.3.0');
+    expect(next).toContain('`2026-10-27`');
+    expect(next).toContain('### ✨ 新增');
+    expect(changelogHasEntry(next, '1.3.0')).toBe(true);
+  });
+
+  it('已有版本号往对应分类下追加，不新建一段', () => {
+    const next = appendChangelogEntry(SAMPLE, { version: '1.2.0', kind: 'fixed', note: '又修了一条' });
+    const sections = parseChangelog(next);
+    expect(sections.filter((one) => one.version === '1.2.0')).toHaveLength(1);
+    expect(sections[0]?.body).toContain('- 又修了一条');
+    expect(sections[0]?.body.indexOf('- 又修了一条')).toBeGreaterThan(
+      sections[0]?.body.indexOf('- 发布审批会显示这一版的更新日志') ?? 0,
+    );
+  });
+
+  it('空文件从骨架起，只留标题', () => {
+    const next = appendChangelogEntry('', { version: '0.1.0', kind: 'added', note: '第一次发布' });
+    expect(next.startsWith('# 更新日志')).toBe(true);
+    expect(next).not.toContain('Unreleased');
+    expect(parseChangelog(next).map((one) => one.version)).toEqual(['0.1.0']);
+  });
+
+  it('这一版还没有该分类时补一个小节', () => {
+    const next = appendChangelogEntry(SAMPLE, { version: '1.2.0', kind: 'removed', note: '删掉旧入口' });
+    expect(changelogSectionOf(next, '1.2.0')).toContain('### 🗑️ 移除');
+    expect(changelogHasEntry(next, '1.2.0')).toBe(true);
+  });
+});
+
+describe('changelogSkeleton', () => {
+  it('只有标题，不给假条目', () => {
+    expect(changelogSkeleton()).toBe('# 更新日志\n');
+  });
+});

package/src/host/__tests__/command-name.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'vitest';
+import { commandNamesMatch } from '../command-name.js';
+
+describe('commandNamesMatch：声明的命令名与解析出来的命令路径', () => {
+  it('缺省 opencli 不管写成名字还是绝对路径都算同一个', () => {
+    expect(commandNamesMatch('opencli', '/Users/me/.dsh/workbench/opencli/bin/opencli')).toBe(true);
+    expect(commandNamesMatch('opencli.cmd', 'C:\\dsh\\opencli.cmd')).toBe(true);
+    expect(commandNamesMatch('opencli.exe', 'C:\\dsh\\opencli.exe')).toBe(true);
+    expect(commandNamesMatch('gitops', '/usr/local/bin/gitops')).toBe(true);
+  });
+
+  it('不同的命令不算同一个', () => {
+    expect(commandNamesMatch('gitops', '/usr/local/bin/opencli')).toBe(false);
+    expect(commandNamesMatch('', 'opencli')).toBe(false);
+  });
+});

package/src/host/__tests__/diy-record.test.ts

@@ -14,8 +14,8 @@ const pact = (sessionId: string, now = 1000, unit = 'demo'): RecordPact => ({
   workspace: '/w/diy',
   unit,
   name: unit,
-  url: 'https://cmdb.example.com/env',
-  title: '环境 · CMDB',
+  url: 'https://inventory.example.com/env',
+  title: '环境 · Inventory',
   action: '发布',
   expect: { method: 'POST', urlContains: '/api/publish' },
   captureFile: '/w/diy/shots/rec-demo.jsonl',
@@ -34,7 +34,7 @@ describe('录制交接：一台机器一次一场，谁开谁收工', () => {
 
     expect(state.phase).toBe('armed');
     expect(state.unit).toBe('demo');
-    expect(state.url).toBe('https://cmdb.example.com/env');
+    expect(state.url).toBe('https://inventory.example.com/env');
     expect(state.action).toBe('发布');
     expect(state.expect).toEqual({ method: 'POST', urlContains: '/api/publish' });
     expect(state.captureFile).toBe('/w/diy/shots/rec-demo.jsonl');

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

@@ -1,13 +1,13 @@
 import { describe, expect, it } from 'vitest';
-import { isFactScope, scopePrefixOf } from '../../api/facts.js';
+import { isFactScope, scopePrefixOf } from '../../contract/facts.js';
 import { unitFactScope } from '../facts.js';
 
 describe('unitFactScope', () => {
   it('命名空间 = 模块 id + `*`（"这个模块的数据全作废"只写一个字符串）', () => {
-    expect(unitFactScope('cmdb')).toBe('cmdb*');
-    expect(isFactScope('cmdb*')).toBe(true);
+    expect(unitFactScope('inventory')).toBe('inventory*');
+    expect(isFactScope('inventory*')).toBe(true);
     expect(isFactScope('*')).toBe(false);
-    expect(isFactScope('cmdb/summary')).toBe(false);
-    expect(scopePrefixOf('cmdb*')).toBe('cmdb');
+    expect(isFactScope('inventory/summary')).toBe(false);
+    expect(scopePrefixOf('inventory*')).toBe('inventory');
   });
 });