dsh-config-manager 0.1.68 → 0.1.70

package/src/foreign/hermes.test.ts

@@ -0,0 +1,545 @@
+/**
+ * Hermes 来源（读盘 + 翻译 + 端到端）的回归护栏。
+ *
+ * 三层各测一层（与 claude-code.test.ts 同构）：
+ *  ① 位置真值：%LOCALAPPDATA%\Hermes / ~/.hermes / HERMES_HOME 覆盖
+ *  ② 翻译与安全不变量：MCP 口径、技能压平、SOUL.md 导入、**MEMORY.md 与 .env 只报告不导入**
+ *  ③ 端到端：产物是合法 bundle v1 分区，且**整份 ZIP 字节**里不含记忆正文与凭据值
+ *
+ * 真机取样（t8）只读 %LOCALAPPDATA%\Hermes，且**只断言键名与计数**，绝不把配置值写进断言。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import type { McpSection } from '../schema/types.ts';
+import { writeForeignBundle } from './bundle.ts';
+import { convertClaudeCode } from './claude-code.ts';
+import { convertHermes } from './hermes.ts';
+import { isRecord } from '../utils/guards.ts';
+import { readHermes, resolveHermesHome } from './read-hermes.ts';
+
+const enc = new TextEncoder();
+const NL = String.fromCharCode(10);
+
+function skillMd(name: string, description: string): Uint8Array {
+  return enc.encode('---' + NL + 'name: ' + name + NL + 'description: ' + description + NL + '---' + NL + NL + 'body' + NL);
+}
+
+/* ---------------- ① 位置真值 ---------------- */
+
+test('t1 位置：HERMES_HOME 覆盖 > Windows %LOCALAPPDATA%\Hermes > ~/.hermes', () => {
+  const win = resolveHermesHome({ homeDir: 'C:/Users/u', env: { LOCALAPPDATA: 'C:/Users/u/AppData/Local' }, platform: 'win32' });
+  assert.equal(win.home, path.join('C:/Users/u/AppData/Local', 'Hermes'));
+  assert.equal(win.overridden, false);
+
+  // 契约 §8.2 的冻结真值：Windows 就是 %LOCALAPPDATA%\Hermes
+  const winNoEnv = resolveHermesHome({ homeDir: 'C:/Users/u', env: {}, platform: 'win32' });
+  assert.equal(winNoEnv.home, path.join('C:/Users/u', 'AppData', 'Local', 'Hermes'));
+
+  assert.equal(resolveHermesHome({ homeDir: '/home/u', env: {}, platform: 'darwin' }).home, path.join('/home/u', '.hermes'));
+  assert.equal(resolveHermesHome({ homeDir: '/home/u', env: {}, platform: 'linux' }).home, path.join('/home/u', '.hermes'));
+
+  const over = resolveHermesHome({ homeDir: 'C:/Users/u', env: { HERMES_HOME: 'D:/hermes-home' }, platform: 'win32' });
+  assert.equal(over.home, 'D:/hermes-home');
+  assert.equal(over.overridden, true, 'HERMES_HOME 生效必须可被上报（绝不静默换目录）');
+});
+
+/* ---------------- ② 翻译 ---------------- */
+
+test('t2 MCP：stdio 与 url 两类同口径映射；凭据剥离且只留引用名；非映射形态如实报码', () => {
+  const result = convertHermes({
+    config: {
+      mcp_servers: {
+        svc: { command: 'npx', args: ['-y', 'svc'], env: { GITHUB_TOKEN: 'ghp_SUPERSECRET', PLAIN: 'ok' }, enabled: true },
+        web: { url: 'https://user:pw@mcp.example.com/mcp', headers: { Authorization: 'Bearer t' } },
+        sse: { url: 'https://sse.example.com', type: 'sse' },
+        disabled: { command: 'npx', args: ['-y', 'disabled-svc'], enabled: false },
+        empty: { enabled: false },
+      },
+    },
+  });
+  const mcp = result.sections.find((s) => s.sectionId === 'mcp')?.data as McpSection;
+  assert.equal(mcp.servers.length, 4, '既无 command 也无 url 的条目不产出；enabled:false 但有 command 的照常导入');
+  assert.equal(mcp.servers.find((s) => s.serverName === 'svc')?.type, 'stdio');
+  assert.equal(mcp.servers.find((s) => s.serverName === 'web')?.type, 'streamable-http');
+  assert.equal(mcp.servers.find((s) => s.serverName === 'web')?.url, 'https://mcp.example.com/mcp', 'URL userinfo 必须剥离');
+  assert.equal(mcp.servers.find((s) => s.serverName === 'svc')?.env?.['GITHUB_TOKEN'], '', '命中凭据的字段值置空、字段名保留');
+  assert.equal(mcp.servers.find((s) => s.serverName === 'svc')?.env?.['PLAIN'], 'ok');
+  assert.ok(result.credentialRefs.includes('mcp:svc:GITHUB_TOKEN'));
+  assert.ok(result.credentialRefs.includes('mcp:web:url'));
+  assert.equal(mcp.servers.find((s) => s.serverName === 'disabled')?.type, 'stdio', 'enabled:false 不是丢弃理由：DSH 无对等字段，原样导入由计划逐条取消');
+  assert.ok(!result.skipped.some((s) => s.origin === 'disabled'), 'enabled 字段绝不导致静默丢弃');
+  assert.ok(result.skipped.some((s) => s.code === 'mcp-server-empty' && s.origin === 'empty'));
+  assert.ok(result.skipped.some((s) => s.code === 'mcp-type-sse-coerced' && s.origin === 'sse'));
+  assert.ok(!JSON.stringify(result).includes('ghp_SUPERSECRET'), '结果对象里不得出现凭据明文');
+  assert.ok(!JSON.stringify(result).includes('pw@'), 'URL userinfo 也必须剥离');
+
+  const odd = convertHermes({ config: { mcp_servers: ['not', 'a', 'mapping'] } });
+  assert.ok(odd.skipped.some((s) => s.code === 'mcp-server-empty' && s.detail === 'not-a-mapping'), '形态对不上必须报码，绝不静默');
+  assert.ok(!odd.sections.some((s) => s.sectionId === 'mcp'), '不产出空 mcp 分区');
+});
+
+test('t2b 与 Claude 同口径：同一份 MCP 定义在两来源产出逐字相同的条目、引用名与机器码', () => {
+  const defs = {
+    svc: { command: 'npx', args: ['-y', 'svc'], env: { GITHUB_TOKEN: 'ghp_PARITY_SECRET' }, enabled: true },
+    web: { url: 'https://user:pw@mcp.example.com/mcp' },
+    sse: { url: 'https://sse.example.com/sse', type: 'sse' },
+    empty: { enabled: false },
+  };
+  const hermes = convertHermes({ config: { mcp_servers: defs } });
+  const claude = convertClaudeCode({ claudeJson: { mcpServers: defs } });
+  const mcpOf = (r: typeof hermes) => r.sections.find((s) => s.sectionId === 'mcp')?.data as McpSection;
+  assert.deepEqual(mcpOf(hermes), mcpOf(claude), '两来源的 mcp 分区必须逐字相同（同一内核实现，口径不可能分叉）');
+  assert.deepEqual(hermes.credentialRefs, claude.credentialRefs);
+  const codes = (r: typeof hermes) => r.skipped.map((s) => s.code + ':' + (s.origin ?? '')).sort();
+  assert.deepEqual(codes(hermes), codes(claude), 'transport 判定与 sse/空条目报码必须同口径');
+  assert.equal(mcpOf(hermes).servers.find((s) => s.serverName === 'sse')?.type, 'streamable-http');
+});
+
+test('t3 技能：两层分类被压平为叶子名并报码；同名先到先得；非法 frontmatter 整体跳过', () => {
+  const broken = enc.encode('---' + NL + 'description: great DX: intuitive' + NL + '---' + NL);
+  const result = convertHermes({
+    skills: [
+      { name: 'dogfood', category: 'software-development', files: [{ relativePath: 'SKILL.md', data: skillMd('dogfood', 'dogfood skill') }] },
+      { name: 'direct', files: [{ relativePath: 'SKILL.md', data: skillMd('direct', 'own skill') }] },
+      { name: 'dogfood', category: 'other-category', files: [{ relativePath: 'SKILL.md', data: skillMd('dogfood', 'duplicate') }] },
+      { name: 'broken', category: 'x', files: [{ relativePath: 'SKILL.md', data: broken }] },
+    ],
+  });
+  const files = result.sections.find((s) => s.sectionId === 'skills')?.files ?? [];
+  assert.deepEqual(files.map((f) => f.relativePath).sort(), ['direct/SKILL.md', 'dogfood/SKILL.md'], '压平后是单层 <技能>/SKILL.md');
+  assert.ok(result.skipped.some((s) => s.code === 'skill-category-flattened' && s.origin === 'software-development/dogfood'));
+  assert.ok(result.skipped.some((s) => s.code === 'skill-id-conflict' && s.origin === 'dogfood'), '同名先到先得，后者跳过并报码');
+  assert.ok(result.skipped.some((s) => s.code === 'skill-invalid-frontmatter' && s.origin === 'broken'));
+});
+
+test('t4 SOUL.md 进 agentInstructions；MEMORY.md 只报告且正文绝不进结果', () => {
+  const result = convertHermes({
+    soul: '# 我的主身份' + NL,
+    memoryFiles: ['MEMORY.md', 'USER.md'],
+  });
+  const ins = result.sections.find((s) => s.sectionId === 'agentInstructions');
+  const md = ins?.files?.find((f) => f.relativePath === 'AGENTS.md');
+  assert.ok(md !== undefined, 'SOUL.md 必须以 AGENTS.md 进 agentInstructions');
+  assert.equal(new TextDecoder().decode(md?.data), '# 我的主身份' + NL);
+  assert.equal(result.counts['agentInstructions.files'], 1);
+  assert.ok(result.skipped.some((s) => s.code === 'memory-report-only' && s.origin === 'MEMORY.md'));
+  assert.ok(result.skipped.some((s) => s.code === 'memory-report-only' && s.origin === 'USER.md'));
+
+  // 空 SOUL.md 不产出分区（不生成空载荷）
+  assert.ok(!convertHermes({ soul: '   ' }).sections.some((s) => s.sectionId === 'agentInstructions'));
+});
+
+test('t5 .env 只报告：值不读、不进结果、不进包', () => {
+  const result = convertHermes({ dotEnvPresent: true });
+  assert.ok(result.skipped.some((s) => s.code === 'credentials-not-migrated' && s.origin === '.env'));
+  assert.deepEqual(result.credentialRefs, [], '连凭据名都没有（.env 根本没被读）');
+  assert.deepEqual(result.sections, []);
+});
+
+test('t6 会话：读得出就迁移；读不出（能力缺失 / 打不开 / 表不符）才如实报码', () => {
+  // ① 库在、却一条都没读出来（例如宿主缺 node:sqlite）→ 必须报码且不产出空分区
+  const none = convertHermes({ config: {}, sessionStore: { present: true, detail: 'state.db' }, soul: 'x' });
+  assert.ok(none.skipped.some((s) => s.code === 'sessions-not-migrated' && s.origin === 'state.db'));
+  assert.ok(!none.sections.some((s) => s.sectionId === 'sessions'));
+  assert.ok(!none.sections.some((s) => s.sectionId === 'workspaces'));
+
+  // ② 读出来了（哪怕只有部分）→ 绝不再报 sessions-not-migrated
+  const parsed = {
+    records: [{ role: 'user' as const, blocks: [{ type: 'text' as const, text: '你好' }], time: 1700000001000 }],
+    cwd: 'D:/proj',
+    createdAt: 1700000001000,
+    title: '标题',
+    raw: 1,
+    bad: 0,
+    ignored: {},
+  };
+  const some = convertHermes({
+    config: {},
+    sessionStore: { present: true, detail: 'state.db' },
+    sessions: [{ id: 's1', parsed }],
+    targetSessionFormatVersion: 3,
+  });
+  assert.ok(some.sections.some((s) => s.sectionId === 'sessions'), '读出的会话必须产出 sessions 分区');
+  assert.ok(some.sections.some((s) => s.sectionId === 'workspaces'), '会话必须连工作区一起产出');
+  assert.ok(!some.skipped.some((s) => s.code === 'sessions-not-migrated'), '读出来了就不该再报不迁移');
+  assert.equal(some.counts['sessions.files'], 1);
+});
+
+/** node:sqlite 能力探测（宿主没有就 skip；降级路径由 t6 覆盖） */
+type DbCtor = new (p: string, o?: { readOnly?: boolean }) => {
+  exec(sql: string): void;
+  close(): void;
+};
+async function sqliteCtor(): Promise<DbCtor | null> {
+  try {
+    const mod = (await import('node:sqlite')) as { DatabaseSync?: DbCtor };
+    return typeof mod.DatabaseSync === 'function' ? mod.DatabaseSync : null;
+  } catch {
+    return null;
+  }
+}
+
+test('t6b state.db 读盘：sessions + messages 两表 → 归一记录、工具结果带正文、cwd/标题取库里的', async () => {
+  const Ctor = await sqliteCtor();
+  if (Ctor === null) return; // 无 node:sqlite：能力缺失下的降级由 t6 覆盖
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-hermes-db-'));
+  const db = new Ctor(path.join(home, 'state.db'));
+  try {
+    db.exec('CREATE TABLE sessions (id TEXT PRIMARY KEY, title TEXT, cwd TEXT, started_at REAL)');
+    db.exec('CREATE TABLE messages (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, role TEXT, content TEXT, tool_calls TEXT, tool_call_id TEXT, tool_name TEXT, timestamp REAL)');
+    db.exec("INSERT INTO sessions VALUES ('s1','会话标题','D:/proj', 1700000000.5)");
+    db.exec("INSERT INTO messages (session_id,role,content,timestamp) VALUES ('s1','user','你好',1700000001)");
+    db.exec(
+      "INSERT INTO messages (session_id,role,content,tool_calls,timestamp) VALUES ('s1','assistant',''," +
+      "'[{\"id\":\"c1\",\"type\":\"function\",\"function\":{\"name\":\"terminal\",\"arguments\":\"{\\\"command\\\":\\\"ls\\\"}\"}}]'," +
+      '1700000002)',
+    );
+    db.exec("INSERT INTO messages (session_id,role,content,tool_call_id,tool_name,timestamp) VALUES ('s1','tool','{\"output\":\"file.txt\"}','c1','terminal',1700000003)");
+    // 第二会话：只有 session_meta 行 + 没有 cwd → 必须如实报 session-missing-cwd（绝不猜）
+    db.exec("INSERT INTO sessions VALUES ('s2',NULL,NULL,1700000004)");
+    db.exec("INSERT INTO messages (session_id,role,content,timestamp) VALUES ('s2','session_meta','{}',1700000005)");
+  } finally {
+    db.close();
+  }
+
+  const read = await readHermes({ homeDir: 'C:/u', env: { HERMES_HOME: home }, platform: 'win32' });
+  assert.equal(read.found, true);
+  assert.equal(read.input.sessions?.length, 2, '两个会话都要读出来（能不能迁移由转码期判定）');
+  const s1 = (read.input.sessions ?? []).find((s) => s.id === 's1');
+  assert.ok(s1 !== undefined);
+  assert.equal(s1.parsed.cwd, 'D:/proj');
+  assert.equal(s1.parsed.title, '会话标题');
+  assert.equal(s1.parsed.records.length, 3, 'user + assistant(工具调用) + tool(结果) 三条都要归一');
+  const assistant = s1.parsed.records[1];
+  assert.ok(assistant?.blocks.some((b) => b.type === 'tool_call' && b.name === 'terminal'));
+  const toolResult = s1.parsed.records[2];
+  assert.ok(
+    toolResult?.blocks.some((b) => b.type === 'tool_result' && b.id === 'c1' && b.text.includes('file.txt')),
+    '工具结果必须带正文且按 callId 配对（异构 JSON 信封不能变空串）',
+  );
+  assert.deepEqual(s1.parsed.ignored, {}, '不认识的记录类型必须逐类计数，这里应为空');
+
+  read.input.targetSessionFormatVersion = 3;
+  const result = convertHermes(read.input);
+  assert.equal(result.counts['sessions.files'], 1, 's1 转码成功');
+  assert.ok(result.skipped.some((s) => s.code === 'session-missing-cwd' && s.origin === 's2'), 's2 缺 cwd 必须如实报码');
+  const sessionSection = result.sections.find((s) => s.sectionId === 'sessions');
+  assert.ok(sessionSection?.files !== undefined && sessionSection.files.length === 1);
+  // 会话日志是压缩编码的，**不断言字面正文**；只断言真的产出了非空字节与合法相对路径
+  assert.ok((sessionSection.files[0]?.data.length ?? 0) > 0, '会话必须真的产出字节');
+  assert.match(sessionSection.files[0]?.relativePath ?? '', /^--D-proj--\/s1\/session\.v3\.jsonl\.zstd$/);
+});
+
+test('t6c 回退：state.db 读不出来时不静默 —— 走 sessions/*.jsonl 且只认 .jsonl', async () => {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-hermes-fb-'));
+  await fs.mkdir(path.join(home, 'sessions'), { recursive: true });
+  // 真机同目录的 request_dump_*.json 是请求转储，绝不能被当会话读
+  await fs.writeFile(path.join(home, 'sessions', 'request_dump_20260101_000000_aaaa.json'), JSON.stringify({ messages: [{ role: 'user', content: 'DUMP_SENTINEL_DO_NOT_SHIP' }] }));
+  await fs.writeFile(
+    path.join(home, 'sessions', 'legacy.jsonl'),
+    JSON.stringify({ role: 'user', content: '回退会话' }) + NL,
+  );
+  const read = await readHermes({ homeDir: 'C:/u', env: { HERMES_HOME: home }, platform: 'win32' });
+  assert.equal(read.input.sessions?.length, 1, '只认 .jsonl');
+  assert.equal(read.input.sessions?.[0]?.id, 'legacy');
+  const raw = JSON.stringify(read.input);
+  assert.ok(!raw.includes('DUMP_SENTINEL_DO_NOT_SHIP'), 'request_dump 的内容绝不进输入结构');
+});
+
+/* ---------------- ③ 读盘 + 端到端 ---------------- */
+
+const MEMORY_SENTINEL = 'MEMORY_SENTINEL_BODY_DO_NOT_SHIP';
+const DOTENV_SENTINEL = 'DOTENV_SENTINEL_VALUE_DO_NOT_SHIP';
+
+async function makeHermesHome(): Promise<string> {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-hermes-home-'));
+  await fs.writeFile(path.join(home, 'config.yaml'), [
+    'model: gpt-x',
+    'mcp_servers:',
+    '  svc:',
+    '    command: npx',
+    '    args:',
+    '      - -y',
+    '      - svc',
+    '    env:',
+    '      GITHUB_TOKEN: ghp_FIXTURE_LEAK',
+    '    enabled: true',
+    '  web:',
+    "    url: 'https://user:pw@mcp.example.com/mcp'",
+    '',
+  ].join(NL));
+  await fs.writeFile(path.join(home, 'SOUL.md'), '# 主身份' + NL);
+  await fs.mkdir(path.join(home, 'memories'), { recursive: true });
+  await fs.writeFile(path.join(home, 'memories', 'MEMORY.md'), MEMORY_SENTINEL + NL);
+  await fs.writeFile(path.join(home, 'memories', 'USER.md'), 'user profile' + NL);
+  await fs.writeFile(path.join(home, '.env'), 'DOTENV_SENTINEL=' + DOTENV_SENTINEL + NL);
+  await fs.writeFile(path.join(home, 'state.db'), 'SQLite format 3' + String.fromCharCode(0));
+  await fs.mkdir(path.join(home, 'skills', 'software-development', 'dogfood'), { recursive: true });
+  await fs.writeFile(path.join(home, 'skills', 'software-development', 'dogfood', 'SKILL.md'), skillMd('dogfood', 'flattened skill'));
+  await fs.writeFile(path.join(home, 'skills', 'software-development', 'dogfood', 'ref.md'), 'ref');
+  await fs.mkdir(path.join(home, 'skills', 'se-team-design'), { recursive: true });
+  await fs.writeFile(path.join(home, 'skills', 'se-team-design', 'SKILL.md'), skillMd('se-team-design', 'category level skill'));
+  await fs.mkdir(path.join(home, 'skills', '.hub'), { recursive: true });
+  await fs.writeFile(path.join(home, 'skills', '.hub', 'lock.json'), '{}');
+  return home;
+}
+
+test('t7 端到端：读盘 → 翻译 → 标准 bundle v1；整份 ZIP 字节不含 MEMORY.md 正文与 .env 值', async () => {
+  const home = await makeHermesHome();
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-hermes-zip-'));
+  try {
+    const read = await readHermes({ homeDir: 'C:/Users/u', env: { HERMES_HOME: home }, platform: 'win32' });
+    assert.equal(read.found, true);
+    assert.equal(read.locationOverridden, true);
+    assert.ok(read.input.readFindings?.some((s) => s.code === 'source-location-overridden'), 'HERMES_HOME 生效必须可上报');
+    assert.deepEqual(read.input.memoryFiles, ['MEMORY.md', 'USER.md']);
+    assert.equal(read.input.dotEnvPresent, true);
+    assert.deepEqual(read.input.sessionStore, { present: true, detail: 'state.db' });
+    const inputJson = JSON.stringify(read.input);
+    assert.ok(!inputJson.includes(DOTENV_SENTINEL), '.env 只 stat 不读：其值连读盘结果对象都不许进');
+    assert.ok(!inputJson.includes(MEMORY_SENTINEL), '记忆只列名不读内容：正文连读盘结果对象都不许进');
+    assert.deepEqual(
+      (read.input.skills ?? []).map((s) => s.name + '@' + (s.category ?? '-')).sort(),
+      ['dogfood@software-development', 'se-team-design@-'],
+      '两层分类的技能取叶子名；分类目录自己带 SKILL.md 时它自己就是技能',
+    );
+
+    const result = convertHermes(read.input);
+    const zipPath = path.join(tmp, 'hermes.zip');
+    const written = await writeForeignBundle({
+      result,
+      outPath: zipPath,
+      exporterVersion: '0.0.0-test',
+      dshVersion: '0.1.0',
+      platform: 'win32',
+      arch: 'x64',
+      exportedAt: '2026-10-04T00:00:00.000Z',
+    });
+    assert.deepEqual([...written.sections].sort(), ['agentInstructions', 'mcp', 'skills']);
+    assert.deepEqual([...written.entryNames].sort(), [
+      'custom/agent-instructions/AGENTS.md',
+      'custom/skills/dogfood/SKILL.md',
+      'custom/skills/dogfood/ref.md',
+      'custom/skills/se-team-design/SKILL.md',
+      'mcp/servers.json',
+    ], '包内路径不得含分类目录（压平），也不得含任何记忆/凭据文件');
+
+    const buf = await fs.readFile(zipPath);
+    assert.ok(!buf.includes(Buffer.from(MEMORY_SENTINEL, 'utf8')), 'ZIP 字节里不得出现 MEMORY.md 正文');
+    assert.ok(!buf.includes(Buffer.from(DOTENV_SENTINEL, 'utf8')), 'ZIP 字节里不得出现 .env 的值');
+    assert.ok(!buf.includes(Buffer.from('ghp_FIXTURE_LEAK', 'utf8')), 'ZIP 字节里不得出现 MCP env 的凭据值');
+    assert.ok(!buf.includes(Buffer.from('pw@', 'utf8')), 'ZIP 字节里不得出现 URL userinfo');
+  } finally {
+    await fs.rm(home, { recursive: true, force: true });
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('t7b 0 字节 config.yaml：报 source-empty-file，绝不抛、绝不产出空分区', async () => {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-hermes-empty-'));
+  try {
+    await fs.writeFile(path.join(home, 'config.yaml'), '');
+    const read = await readHermes({ homeDir: 'C:/Users/u', env: { HERMES_HOME: home }, platform: 'win32' });
+    assert.equal(read.found, true);
+    assert.ok(read.input.readFindings?.some((s) => s.code === 'source-empty-file' && s.origin === 'config.yaml'));
+    assert.deepEqual(convertHermes(read.input).sections, []);
+  } finally {
+    await fs.rm(home, { recursive: true, force: true });
+  }
+});
+
+/* ---------------- ④ 入库 fixture（形态取自真机；不依赖本机是否装了 Hermes） ---------------- */
+
+const FIXTURE_ROOT = path.resolve(import.meta.dirname, 'fixtures', 'hermes');
+
+/**
+ * 真机 config.yaml 的**顶层键名**（2026-10-04 本机只读取样；键名不是配置值，可以入库）。
+ * 值一律不进断言：配置值可能含 token/路径/账号，写进测试就等于把机器身份写进仓库。
+ */
+const REAL_TOP_LEVEL_KEYS = [
+  '_config_version', 'agent', 'approvals', 'auxiliary', 'browser', 'code_execution', 'compression',
+  'custom_providers', 'delegation', 'display', 'group_sessions_per_user', 'mcp_servers', 'memory', 'moa',
+  'model',
+  'platform_toolsets', 'platforms', 'plugins', 'prompt_caching', 'providers', 'session_reset', 'skills',
+  'streaming', 'stt', 'telemetry', 'terminal', 'tool_loop_guardrails', 'updates', 'voice',
+];
+
+test('t9 fixture：真机键名形态 + 两层技能压平 + 记忆与凭据零进包（整份 ZIP 字节断言）', async () => {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-hermes-fixture-'));
+  const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-hermes-fixture-zip-'));
+  try {
+    await fs.cp(path.join(FIXTURE_ROOT, 'basic'), home, { recursive: true });
+    // .env 被仓库 .gitignore 排除 → fixture 里叫 dotenv.fixture，读之前改回真名
+    await fs.rename(path.join(home, 'dotenv.fixture'), path.join(home, '.env'));
+
+    const read = await readHermes({ homeDir: 'C:/Users/u', env: { HERMES_HOME: home }, platform: 'win32' });
+    assert.equal(read.found, true);
+    const cfg = read.input.config;
+    assert.ok(isRecord(cfg), 'fixture 的 config.yaml 必须能解析出结构');
+    assert.deepEqual(Object.keys(cfg).sort(), REAL_TOP_LEVEL_KEYS, '只断言顶层键名（真机实测形态），不含任何配置值');
+    assert.deepEqual(
+      (read.input.skills ?? []).map((s) => s.name + '@' + (s.category ?? '-')).sort(),
+      ['dogfood@software-development', 'se-team-design@-'],
+      '叶子名成技能；分类目录自带 SKILL.md 时它自己就是技能',
+    );
+    const catSkill = (read.input.skills ?? []).find((s) => s.name === 'se-team-design');
+    assert.ok(
+      catSkill?.files.some((f) => f.relativePath === 'examples/usage.md'),
+      '分类级别技能（分类目录自带 SKILL.md）的子目录只作资产，随该技能进包、不另成技能',
+    );
+    assert.deepEqual(read.input.memoryFiles, ['MEMORY.md', 'USER.md']);
+    assert.equal(read.input.dotEnvPresent, true);
+    assert.deepEqual(read.input.sessionStore, { present: true, detail: 'state.db' });
+
+    const result = convertHermes(read.input);
+    const mcp = result.sections.find((s) => s.sectionId === 'mcp')?.data as McpSection;
+    assert.equal(mcp.servers.length, 3, '既无 command 也无 url 的条目绝不产出');
+    assert.equal(mcp.servers.find((s) => s.serverName === 'svc')?.type, 'stdio');
+    assert.equal(mcp.servers.find((s) => s.serverName === 'web')?.type, 'streamable-http');
+    assert.equal(mcp.servers.find((s) => s.serverName === 'legacy-sse')?.type, 'streamable-http');
+    assert.ok(result.skipped.some((s) => s.code === 'mcp-type-sse-coerced'));
+    assert.ok(result.skipped.some((s) => s.code === 'mcp-server-empty' && s.origin === 'empty'));
+    assert.ok(result.skipped.some((s) => s.code === 'sessions-not-migrated' && s.origin === 'state.db'));
+    assert.ok(result.skipped.some((s) => s.code === 'memory-report-only' && s.origin === 'MEMORY.md'));
+    assert.ok(!result.sections.some((s) => s.sectionId === 'sessions' || s.sectionId === 'workspaces'));
+
+    const zipPath = path.join(tmp, 'fixture.zip');
+    const written = await writeForeignBundle({
+      result,
+      outPath: zipPath,
+      exporterVersion: '0.0.0-test',
+      dshVersion: '0.1.0',
+      platform: 'win32',
+      arch: 'x64',
+      exportedAt: '2026-10-04T00:00:00.000Z',
+    });
+    assert.deepEqual([...written.sections].sort(), ['agentInstructions', 'mcp', 'skills']);
+    assert.ok(!written.entryNames.some((n) => n.includes('memories')), '记忆目录绝不进包');
+    assert.ok(!written.entryNames.some((n) => n.endsWith('/.env')), '.env 绝不进包');
+    assert.ok(
+      !written.entryNames.some((n) => n.startsWith('custom/skills/software-development/')),
+      '压平后包内路径不得出现分类目录',
+    );
+    assert.ok(written.entryNames.includes('custom/skills/se-team-design/examples/usage.md'), '资产子目录随技能进包');
+    assert.ok(
+      !written.entryNames.some((n) => n.includes('/examples/usage.md') && !n.startsWith('custom/skills/se-team-design/')),
+      '资产子目录绝不自成技能',
+    );
+    const buf = await fs.readFile(zipPath);
+    for (const sentinel of [
+      'MEMORY_SENTINEL_BODY_DO_NOT_SHIP',
+      'DOTENV_SENTINEL_VALUE_DO_NOT_SHIP',
+      'ghp_FIXTURE_TOKEN_DO_NOT_SHIP',
+      'pw@',
+    ]) {
+      assert.ok(!buf.includes(Buffer.from(sentinel, 'utf8')), 'ZIP 字节里不得出现：' + sentinel);
+    }
+  } finally {
+    await fs.rm(home, { recursive: true, force: true });
+    await fs.rm(tmp, { recursive: true, force: true });
+  }
+});
+
+test('t9b fixture：0 字节 config.yaml 用例只报码、绝不抛（空分区也不产出）', async () => {
+  const home = await fs.mkdtemp(path.join(os.tmpdir(), 'dsh-hermes-empty-fixture-'));
+  try {
+    await fs.cp(path.join(FIXTURE_ROOT, 'empty'), home, { recursive: true });
+    const read = await readHermes({ homeDir: 'C:/Users/u', env: { HERMES_HOME: home }, platform: 'win32' });
+    assert.equal(read.found, true);
+    assert.ok(
+      read.input.readFindings?.some((s) => s.code === 'source-empty-file' && s.origin === 'config.yaml'),
+      '0 字节必须报 source-empty-file',
+    );
+    assert.deepEqual(convertHermes(read.input).sections, []);
+  } finally {
+    await fs.rm(home, { recursive: true, force: true });
+  }
+});
+
+/* ---------------- 真机取样（只读；本机没有就 skip） ---------------- */
+
+const REAL_HOME = resolveHermesHome({ homeDir: os.homedir(), env: process.env, platform: process.platform });
+const realStat = await fs.stat(REAL_HOME.home).catch(() => null);
+const REAL_SKIP = realStat === null ? '本机无 Hermes 数据目录' : false;
+
+test('t8 真机取样：读得动本机 Hermes 数据目录（只断言键名与计数，不含任何配置值）', { skip: REAL_SKIP }, async () => {
+  const read = await readHermes({
+    homeDir: os.homedir(),
+    env: process.env,
+    platform: process.platform,
+    maxSkills: 5,
+    maxSkillFiles: 20,
+  });
+  assert.equal(read.found, true);
+  assert.ok(Array.isArray(read.input.memoryFiles));
+  assert.ok((read.input.skills ?? []).length > 0, '本机 skills/ 应能读出技能单元');
+  for (const s of read.input.skills ?? []) {
+    assert.ok(s.files.some((f) => f.relativePath === 'SKILL.md'), '每个技能单元必须自带 SKILL.md：' + s.name);
+  }
+  // 结构性断言（不读任何配置值）：记忆正文根本没有承载字段
+  assert.deepEqual(Object.keys(read.input).filter((k) => /memory/i.test(k)), ['memoryFiles']);
+
+  // 真机只做结构性断言：会话要么迁移成功（sessions + workspaces 同源产出），要么逐条报码解释
+  read.input.targetSessionFormatVersion = 3;
+  const result = convertHermes(read.input);
+  assert.ok(result.sections.length > 0, '真机产物必须至少有一个分区');
+  const sessionCount = (result.sections.find((s) => s.sectionId === 'sessions')?.files ?? []).length;
+  if (sessionCount > 0) {
+    assert.ok(result.sections.some((s) => s.sectionId === 'workspaces'), '有会话就必须有工作区');
+    assert.ok(!result.skipped.some((s) => s.code === 'sessions-not-migrated'), '读出来了就不该再报不迁移');
+  } else {
+    assert.ok(
+      result.skipped.some((s) => s.code === 'sessions-not-migrated' || s.code.split('-')[0] === 'session'),
+      '一条都没迁移时必须能解释（能力缺失 / 缺 cwd / 空库）',
+    );
+  }
+});
+
+
+test('t8c 真机取样：config.yaml 只做「键名 + 计数」断言（绝不落任何配置值）', { skip: REAL_SKIP }, async () => {
+  // 只为取 config.yaml 的结构：技能侧给很小的上限（本用例不断言技能，只省读盘时间）
+  const read = await readHermes({ homeDir: os.homedir(), env: process.env, platform: process.platform, maxSkills: 2, maxSkillFiles: 4 });
+  assert.equal(read.found, true);
+  const cfgStat = await fs.stat(path.join(read.home, 'config.yaml')).catch(() => null);
+  if (cfgStat === null) return; // 本机没有 config.yaml：结构无从取样（不是失败）
+  if (cfgStat.size === 0) {
+    assert.ok(
+      read.input.readFindings?.some((s) => s.code === 'source-empty-file' && s.origin === 'config.yaml'),
+      '0 字节必须报 source-empty-file',
+    );
+    return;
+  }
+  const cfg = read.input.config;
+  if (!isRecord(cfg)) {
+    assert.ok(
+      read.input.readFindings?.some((s) => s.code === 'source-unreadable' && s.origin === 'config.yaml'),
+      '解析不出结构就必须报码，绝不静默',
+    );
+    return;
+  }
+  const keys = Object.keys(cfg);
+  assert.ok(keys.length > 0, '真实 config.yaml 应能解析出至少一个顶层键');
+  for (const key of keys) {
+    assert.equal(key.trim(), key, '顶层键名不得带首尾空白');
+    assert.ok(key !== '' && !key.includes('/') && key.includes('\\') === false, '顶层键名必须是单个段');
+  }
+  // 计数口径：mcp_servers 若存在必须是「名字 → 定义」映射，产出条目不得多于外部条目
+  const mcpRaw = cfg['mcp_servers'];
+  const result = convertHermes(read.input);
+  if (mcpRaw !== undefined) {
+    assert.ok(isRecord(mcpRaw), 'mcp_servers 必须是映射形态');
+    const names = Object.keys(mcpRaw);
+    const mcp = result.sections.find((s) => s.sectionId === 'mcp')?.data as McpSection | undefined;
+    assert.ok(mcp === undefined || mcp.servers.length <= names.length, '产出条目数不得超过外部条目数');
+    for (const s of mcp?.servers ?? []) {
+      assert.ok(names.includes(s.serverName), 'serverName 必须来自外部键名');
+      assert.ok(s.type === 'stdio' || s.type === 'streamable-http', 'transport 只有两种合法取值');
+    }
+  }
+  assert.ok(!result.sections.some((s) => s.sectionId === 'sessions'), '真机取样也不得产出 sessions 分区');
+  assert.ok(!result.sections.some((s) => s.sectionId === 'workspaces'), '真机取样也不得产出 workspaces 分区');
+});

package/src/foreign/hermes.ts

@@ -0,0 +1,86 @@
+/**
+ * Hermes（NousResearch/hermes-agent）→ DSH bundle 分区的**纯**翻译层。
+ *
+ * 输入 = 已经读好的 Hermes 数据（读盘层 read-hermes.ts，纯数据、不含任何凭据值与记忆正文）；
+ * 输出 = ForeignImportResult（分区载荷 + 未迁移项 + 凭据引用名）。
+ *
+ * 位置与结构真值见契约 §8.2（本机实测）：
+ *  - config.yaml 顶层含 mcp_servers（名字 → 定义；有非空 url → streamable-http，否则 stdio）
+ *  - skills/<分类>/<技能>/SKILL.md（**两层**），也有 <分类>/SKILL.md（分类自己就是技能）
+ *  - SOUL.md = 主身份 → agentInstructions（用户决策：**导入**）
+ *  - memories/{MEMORY.md,USER.md} → 只报告不导入（用户决策；正文根本不在输入结构里）
+ *  - .env → 只报告（值绝不读、绝不进包）
+ *  - 对话在 SQLite（state.db）里 → **读盘层读出归一记录后在这里装配成 sessions + workspaces**
+ *    （2026-10-06 起；公共出口 = kernel.collectSessionSections，与 Claude Code 同一份实现）。
+ *    state.db 打不开 / 宿主缺 node:sqlite 时才回落到 sessions-not-migrated 这条如实报码。
+ *
+ * 公共口径（MCP 映射与凭据剥离、SKILL.md frontmatter 校验、路径/名字安全、技能装配）全部走
+ * 共享内核 kernel.ts —— 与 Claude Code 同一份实现，口径不可能分叉。
+ */
+import { collectSessionSections, collectSkills, instructionsSection, mcpSectionFromEntries, serverEntriesOf } from './kernel.ts';
+import { draftFromTranscript, transcodeSessionDraft } from './session-source.ts';
+import { isRecord } from '../utils/guards.ts';
+import type { ForeignImportResult, ForeignSectionOut, ForeignSkip, HermesInput, HermesSessionInput } from './types.ts';
+
+export function convertHermes(input: HermesInput): ForeignImportResult {
+  // 读盘层的发现（0 字节 / 位置被 HERMES_HOME 覆盖 / 读不到）排在前面：它们解释「为什么读到的少了」
+  const skipped: ForeignSkip[] = [...(input.readFindings ?? [])];
+  const sections: ForeignSectionOut[] = [];
+  const credentialRefs: string[] = [];
+  const counts: Record<string, number> = {};
+
+  const rawMcp = isRecord(input.config) ? input.config['mcp_servers'] : undefined;
+  if (rawMcp !== undefined && !isRecord(rawMcp)) {
+    // 形态对不上就如实报（绝不静默少一片）：Hermes 的真值形态是「名字 → 定义」映射
+    skipped.push({ code: 'mcp-server-empty', origin: 'mcp_servers', detail: 'not-a-mapping' });
+  }
+  const mcp = mcpSectionFromEntries(serverEntriesOf(input.config, 'mcp_servers'), credentialRefs, skipped);
+  if (mcp !== null) {
+    sections.push({ sectionId: 'mcp', data: mcp });
+    counts['mcp.servers'] = mcp.servers.length;
+  }
+
+  const skillFiles: { relativePath: string; data: Uint8Array }[] = [];
+  collectSkills(input.skills ?? [], skillFiles, skipped);
+  if (skillFiles.length > 0) {
+    sections.push({ sectionId: 'skills', files: skillFiles });
+    counts['skills.files'] = skillFiles.length;
+  }
+
+  const instructions = instructionsSection(typeof input.soul === 'string' ? input.soul : '');
+  if (instructions !== null) {
+    sections.push(instructions);
+    counts['agentInstructions.files'] = 1;
+  }
+
+  // 记忆：只报告不导入（用户决策）。这里只有文件名，正文根本没有进入过本进程的输入结构。
+  for (const rel of input.memoryFiles ?? []) {
+    skipped.push({ code: 'memory-report-only', origin: rel, count: 1 });
+  }
+
+  // 凭据文件：只报告（值连内存都不进）。导入后由用户在 DSH 里自行补录。
+  if (input.dotEnvPresent === true) {
+    skipped.push({ code: 'credentials-not-migrated', origin: '.env', count: 1 });
+  }
+
+  // 对话：state.db（SQLite）读出的**归一记录** → DSH 会话 + 工作区。
+  // 必须走 kernel.collectSessionSections（唯一出口）：冲突语义（同 id 只允许一条）与
+  // 「只给会话不给工作区 = 目标机一条对话都看不见」这两条硬不变量只有那一处实现。
+  const formatVersion = input.targetSessionFormatVersion ?? -1;
+  collectSessionSections<HermesSessionInput>({
+    files: input.sessions ?? [],
+    targetFormatVersion: input.targetSessionFormatVersion,
+    transcode: (file) => transcodeSessionDraft(draftFromTranscript(file.id, file.parsed, 'hermes'), { formatVersion }),
+    workspaceIdPrefix: 'hermes',
+    sections,
+    skipped,
+    counts,
+  });
+  // 库确实在、却**一条都没读出来**（宿主缺 node:sqlite / 打不开 / 表结构不符）→ 如实报。
+  // 读出来了（哪怕只有一部分）就绝不再报这条 —— 逐条失败已由 session-* 码单独可见。
+  if (input.sessionStore?.present === true && (input.sessions?.length ?? 0) === 0) {
+    skipped.push({ code: 'sessions-not-migrated', origin: input.sessionStore.detail ?? 'state.db', count: 1 });
+  }
+
+  return { source: 'hermes', sections, skipped, credentialRefs, counts };
+}