dsh-config-manager 0.1.78 → 0.1.80

package/src/foreign/read-claude-plugins.ts

@@ -0,0 +1,465 @@
+/**
+ * Claude Code **插件**目录的读盘层（宿主侧只读；2026-10-18 补）。
+ *
+ * 真实布局（本机实测取证；只记录键名，绝不过问值）：
+ *  - `plugins/known_marketplaces.json`：`{ "<市场名>": { source: { source, repo }, installLocation, lastUpdated } }`；
+ *  - `plugins/marketplaces/<市场>/.claude-plugin/marketplace.json`：`{ name, description, owner, plugins: [...] }`；
+ *  - `plugins/marketplaces/<市场>/plugins/<插件>/`（或 `external_plugins/<插件>/`）；
+ *  - 插件目录：`.claude-plugin/plugin.json`、commands/、skills/、agents/、hooks/、.mcp.json
+ *    （`.mcp.json` 形如 `{ "<server>": { type, url, headers } }` —— **headers 里可能是真凭据**）。
+ *
+ * 三条结构性纪律：
+ *  ① **绝不执行、绝不读取插件里的可执行代码内容**：commands/agents/hooks 只做「文件名 / 文件数」
+ *     统计；允许进包的只有技能文本与 `.mcp.json`（且 .mcp.json 原样交给翻译层，凭据剥离在
+ *     kernel 的剥离器里做 —— 本层不复制、不改写凭据，只保证「不额外扩散」）；
+ *  ② **不猜**：启用清单只认两个有形状可自证的位置（settings.enabledPlugins 与 plugins/config.json
+ *     的可识别形状），认不出来就报 plugins-config-unknown-shape，绝不把任意 JSON 当插件清单；
+ *  ③ **不静默**：市场和插件都读不到 / 找不到安装目录 / 触顶（插件数、单插件文件数）一律报稳定机器码。
+ *
+ * 归属规则（与 read-claude-code 一致）：能落到某个插件上的发现写进该插件的 readFindings（由翻译层
+ * 原样带出）；落不到插件上的（市场清单、启用清单、找不到安装目录、插件数触顶）进顶层 skipped。
+ *
+ * 为什么本文件不 import `node:fs`：`src/foreign/file-budget.test.ts` 的 B 档要求 import fs 的模块
+ * **恰好**等于白名单。这里复用 `session-read.ts`（共享只读内核）的原语，实现同样「只读、不跟随
+ * 符号链接、有上限」的行为，而不新增一个 fs 入口。
+ */
+import path from 'node:path';
+
+import { isRecord } from '../utils/guards.ts';
+import { stripUserInfo } from './kernel.ts';
+import { listDirSafe, readJsonSafe, statOrNull, toPosixPath, walkFiles } from './session-read.ts';
+import { readSkillUnits } from './read-claude-code.ts';
+import type { ClaudePluginInput, ClaudeSkillInput, ForeignSkip } from './types.ts';
+
+/** 插件数上限触顶（count = 上限） */
+export const MAX_PLUGINS_REACHED = 'max-plugins-reached';
+/** 单插件文件数上限触顶（count = 上限） */
+export const MAX_PLUGIN_FILES_REACHED = 'max-plugin-files-reached';
+/** plugins/config.json 存在但形状认不出来（**绝不猜**） */
+export const PLUGINS_CONFIG_UNKNOWN_SHAPE = 'plugins-config-unknown-shape';
+
+const DEFAULT_MAX_FILE_BYTES = 8 * 1024 * 1024;
+const DEFAULT_MAX_PLUGINS = 50;
+const DEFAULT_MAX_PLUGIN_FILES = 200;
+/** 目录走盘深度（与 session-read 的 WalkOptions 缺省一致） */
+const WALK_MAX_DEPTH = 8;
+/** 跳过原因：符号链接（与 read-claude-code 同码同义） */
+const DETAIL_SYMLINK = 'symlink-skipped';
+
+export interface ClaudePluginReadLimits {
+  /** 启用的插件数上限（默认 50） */
+  readonly maxPlugins?: number;
+  /** 单个插件的文件数上限（默认 200；触顶报 max-plugin-files-reached） */
+  readonly maxPluginFiles?: number;
+}
+
+export interface ClaudePluginReadOptions {
+  /** Claude 配置目录（`<home>/.claude` 或 CLAUDE_CONFIG_DIR 覆盖值） */
+  readonly claudeDir: string;
+  /** settings.json 的已解析值（enabledPlugins 的权威来源） */
+  readonly settings: unknown;
+  readonly limits?: ClaudePluginReadLimits;
+  /** 单文件读取上限（默认 8 MiB；与同域读盘层同口径） */
+  readonly maxFileBytes?: number;
+}
+
+export interface ClaudePluginReadResult {
+  /** 读到的插件（只含有安装目录、能自证的最小元数据与组件） */
+  plugins: ClaudePluginInput[];
+  /** 已登记的市场（name + 来源仓库；URL 的 userinfo 已剥离） */
+  marketplaces: { name: string; repo?: string }[];
+  /** 落不到具体插件上的发现（市场清单 / 启用清单 / 找不到安装目录 / 插件数触顶） */
+  skipped: ForeignSkip[];
+  /** 计数（marketplaces / enabledPlugins / plugins / pluginSkills / pluginCommands / pluginAgents / pluginHooks） */
+  counts: Record<string, number>;
+}
+
+interface MarketplaceRecord {
+  name: string;
+  repo?: string;
+  /** 市场安装位置（绝对路径；**只用于定位插件目录**，绝不进返回值） */
+  installLocation?: string;
+}
+
+/** 有上限的整数解析：只用安全正整数（脏值一律回落缺省） */
+function positiveLimit(value: number | undefined, fallback: number): number {
+  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+
+/** source.repo 或 source.url（两者都可能带 userinfo；剥离在调用处统一做） */
+function repoOfSource(source: Record<string, unknown>): string | undefined {
+  const repo = source['repo'];
+  if (typeof repo === 'string' && repo.trim() !== '') return repo.trim();
+  const url = source['url'];
+  if (typeof url === 'string' && url.trim() !== '') return url.trim();
+  return undefined;
+}
+
+/**
+ * 读 `plugins/known_marketplaces.json`。
+ * 文件不存在 = 没有登记任何市场（正常状态，不报码）；存在但读不出来 / 形状不对 = source-unreadable。
+ */
+async function readKnownMarketplaces(
+  pluginsDir: string,
+  maxFileBytes: number,
+  skipped: ForeignSkip[],
+): Promise<MarketplaceRecord[]> {
+  const file = path.join(pluginsDir, 'known_marketplaces.json');
+  const jr = await readJsonSafe(file, maxFileBytes);
+  if (!jr.ok) {
+    if (jr.problem !== 'missing') {
+      skipped.push({ code: 'source-unreadable', origin: 'plugins/known_marketplaces.json', detail: jr.problem });
+    }
+    return [];
+  }
+  if (!isRecord(jr.value)) {
+    skipped.push({
+      code: 'source-unreadable',
+      origin: 'plugins/known_marketplaces.json',
+      detail: 'not-mapping',
+    });
+    return [];
+  }
+  const out: MarketplaceRecord[] = [];
+  for (const name of Object.keys(jr.value).sort()) {
+    const raw = jr.value[name];
+    const record: MarketplaceRecord = { name };
+    if (isRecord(raw)) {
+      const source = raw['source'];
+      if (isRecord(source)) {
+        const repo = repoOfSource(source);
+        // **userinfo 绝不进包**：https://user:token@host/x.git → https://host/x.git
+        if (repo !== undefined) record.repo = stripUserInfo(repo).url;
+      }
+      const installLocation = raw['installLocation'];
+      if (typeof installLocation === 'string' && installLocation.trim() !== '') {
+        record.installLocation = path.resolve(installLocation.trim());
+      }
+    }
+    out.push(record);
+  }
+  return out;
+}
+
+/** settings.enabledPlugins 的启用键（**真值才算启用**；非对象 = 没有这份清单） */
+function enabledSpecsFromSettings(settings: unknown): string[] {
+  if (!isRecord(settings)) return [];
+  const enabled = settings['enabledPlugins'];
+  if (!isRecord(enabled)) return [];
+  return Object.keys(enabled)
+    .filter((key) => Boolean(enabled[key]))
+    .sort();
+}
+
+/**
+ * 按**形状自证**识别 plugins/config.json（认不出来返回 null，绝不猜）：
+ *  - `{ plugins: string[] }`：插件名清单；
+ *  - `{ plugins: { [name@market]: boolean } }`：启用表；
+ *  - `{ enabledPlugins: { ... } }`：与 settings 同形的启用表；
+ *  - 顶层直接就是 `{ "name@market": true }`（键必须都带 @）。
+ */
+function recognizePluginsConfig(value: unknown): string[] | null {
+  if (!isRecord(value)) return null;
+  const plugins = value['plugins'];
+  if (Array.isArray(plugins)) {
+    if (plugins.length === 0) return [];
+    if (!plugins.every((item) => typeof item === 'string' && item.trim() !== '')) return null;
+    return [...new Set(plugins.map((item) => (item as string).trim()))].sort();
+  }
+  if (isRecord(plugins)) {
+    if (!Object.values(plugins).every((item) => typeof item === 'boolean')) return null;
+    return Object.keys(plugins).filter((key) => plugins[key] === true).sort();
+  }
+  const enabled = value['enabledPlugins'];
+  if (isRecord(enabled)) {
+    if (!Object.values(enabled).every((item) => typeof item === 'boolean')) return null;
+    return Object.keys(enabled).filter((key) => enabled[key] === true).sort();
+  }
+  const keys = Object.keys(value);
+  if (keys.length > 0 && keys.every((key) => key.includes('@')) && keys.every((key) => typeof value[key] === 'boolean')) {
+    return keys.filter((key) => value[key] === true).sort();
+  }
+  return null;
+}
+
+/**
+ * 启用插件清单：settings.enabledPlugins 优先（有内容就用它），否则按形状读 plugins/config.json。
+ * 两者都没有 → 空数组、不报码（诚实：没有启用的插件）。
+ */
+async function enabledPluginSpecs(
+  pluginsDir: string,
+  settings: unknown,
+  maxFileBytes: number,
+  skipped: ForeignSkip[],
+): Promise<string[]> {
+  const fromSettings = enabledSpecsFromSettings(settings);
+  if (fromSettings.length > 0) return fromSettings;
+  const configPath = path.join(pluginsDir, 'config.json');
+  const jr = await readJsonSafe(configPath, maxFileBytes);
+  if (!jr.ok) {
+    if (jr.problem !== 'missing') {
+      skipped.push({ code: 'source-unreadable', origin: 'plugins/config.json', detail: jr.problem });
+    }
+    return [];
+  }
+  const recognized = recognizePluginsConfig(jr.value);
+  if (recognized === null) {
+    skipped.push({ code: 'source-unreadable', origin: 'plugins/config.json', detail: PLUGINS_CONFIG_UNKNOWN_SHAPE });
+    return [];
+  }
+  return recognized;
+}
+
+/** `name@marketplace` → { name, marketplace }；没有 @ 或 @ 在边界上 = 只有名字 */
+function splitPluginSpec(spec: string): { name: string; marketplace?: string } {
+  const at = spec.lastIndexOf('@');
+  if (at <= 0 || at === spec.length - 1) return { name: spec };
+  return { name: spec.slice(0, at), marketplace: spec.slice(at + 1) };
+}
+
+/** dirent 的最小形状（刻意不 import node:fs：B 档白名单要求 import fs 的模块恰好等于白名单） */
+interface DirEntryLike {
+  isDirectory: () => boolean;
+  isSymbolicLink: () => boolean;
+}
+
+/** 某个父目录下名为 name 的条目（**不跟链接**：dirent 自带 isSymbolicLink） */
+async function direntOf(target: string): Promise<DirEntryLike | null> {
+  const parent = path.dirname(target);
+  const base = path.basename(target);
+  for (const entry of await listDirSafe(parent)) {
+    if (entry.name === base) return entry;
+  }
+  return null;
+}
+
+type Located =
+  | { kind: 'dir'; dir: string }
+  | { kind: 'symlink' }
+  | { kind: 'missing' };
+
+/**
+ * 定位插件安装目录（顺序：市场下 plugins/ → external_plugins/ → 市场 installLocation 的同名目录及其
+ * 两种标准子目录）。命中符号链接 → symlink（不跟随）；都不在 → missing（由调用方报码）。
+ */
+async function locatePluginDir(
+  pluginsDir: string,
+  name: string,
+  marketplace: string | undefined,
+  market: MarketplaceRecord | undefined,
+): Promise<Located> {
+  const candidates: string[] = [];
+  if (marketplace !== undefined) {
+    const marketDir = path.join(pluginsDir, 'marketplaces', marketplace);
+    candidates.push(path.join(marketDir, 'plugins', name));
+    candidates.push(path.join(marketDir, 'external_plugins', name));
+  } else {
+    candidates.push(path.join(pluginsDir, name));
+  }
+  if (market?.installLocation !== undefined) {
+    candidates.push(path.join(market.installLocation, name));
+    candidates.push(path.join(market.installLocation, 'plugins', name));
+    candidates.push(path.join(market.installLocation, 'external_plugins', name));
+  }
+  let symlinkHit = false;
+  for (const candidate of candidates) {
+    const entry = await direntOf(candidate);
+    if (entry === null) continue;
+    if (entry.isSymbolicLink()) { symlinkHit = true; continue; }
+    if (entry.isDirectory()) return { kind: 'dir', dir: candidate };
+  }
+  return symlinkHit ? { kind: 'symlink' } : { kind: 'missing' };
+}
+
+/** 插件自述（.claude-plugin/plugin.json）：解析失败用目录名并报码，绝不猜 */
+async function readPluginManifest(
+  pluginDir: string,
+  fallbackName: string,
+  maxFileBytes: number,
+  findings: ForeignSkip[],
+): Promise<{ name: string; version?: string }> {
+  const out: { name: string; version?: string } = { name: fallbackName };
+  const manifestPath = path.join(pluginDir, '.claude-plugin', 'plugin.json');
+  const jr = await readJsonSafe(manifestPath, maxFileBytes);
+  if (!jr.ok) {
+    if (jr.problem !== 'missing') {
+      findings.push({ code: 'source-unreadable', origin: 'plugin:' + fallbackName + '/plugin.json', detail: jr.problem });
+    }
+    return out;
+  }
+  if (!isRecord(jr.value)) {
+    findings.push({ code: 'source-unreadable', origin: 'plugin:' + fallbackName + '/plugin.json', detail: 'not-mapping' });
+    return out;
+  }
+  const name = jr.value['name'];
+  if (typeof name === 'string' && name.trim() !== '') out.name = name.trim();
+  const version = jr.value['version'];
+  if (typeof version === 'string' && version.trim() !== '') out.version = version.trim();
+  return out;
+}
+
+/**
+ * 读一个已定位的插件目录。**只读元数据与组件清单**：
+ *  - skills：技能文本（唯一允许进包的文件内容，凭据扫描在翻译层）；
+ *  - .mcp.json：原样交翻译层（凭据剥离在 kernel）；
+ *  - commands / agents / hooks：**只数文件 / 只取文件名**，内容一个字节都不读。
+ */
+async function readPluginAt(
+  pluginDir: string,
+  specName: string,
+  marketplace: string | undefined,
+  market: MarketplaceRecord | undefined,
+  options: { maxPluginFiles: number; maxFileBytes: number; installRel?: string },
+): Promise<ClaudePluginInput> {
+  const findings: ForeignSkip[] = [];
+  const manifest = await readPluginManifest(pluginDir, specName, options.maxFileBytes, findings);
+  const plugin: ClaudePluginInput = { name: manifest.name, components: [] };
+  if (manifest.version !== undefined) plugin.version = manifest.version;
+  if (options.installRel !== undefined) plugin.installRel = options.installRel;
+  if (marketplace !== undefined) plugin.marketplace = marketplace;
+  if (market?.repo !== undefined) plugin.repo = market.repo;
+
+  /* skills（有总量上限：跨技能累计，触顶报 max-plugin-files-reached） */
+  const skills: ClaudeSkillInput[] = [];
+  let filesUsed = 0;
+  let filesTruncated = false;
+  const units = await readSkillUnits(path.join(pluginDir, 'skills'), {
+    maxFiles: options.maxPluginFiles,
+    maxBytes: options.maxFileBytes,
+    origin: 'plugin:' + specName + '/skills',
+    skips: findings,
+  });
+  for (const unit of units) {
+    if (filesUsed >= options.maxPluginFiles) { filesTruncated = true; break; }
+    const room = options.maxPluginFiles - filesUsed;
+    const files = unit.files.slice(0, room);
+    if (files.length < unit.files.length) filesTruncated = true;
+    if (files.length === 0) continue;
+    skills.push({ name: unit.name, files });
+    filesUsed += files.length;
+  }
+  if (skills.length > 0) {
+    plugin.skills = skills;
+    plugin.components.push('skills');
+  }
+
+  /* .mcp.json：原始 JSON 交给翻译层（本层不读 headers 的值语义，也不改写） */
+  const mcp = await readJsonSafe(path.join(pluginDir, '.mcp.json'), options.maxFileBytes);
+  if (mcp.ok) {
+    plugin.mcpJson = mcp.value;
+    plugin.components.push('mcp');
+  } else if (mcp.problem !== 'missing') {
+    findings.push({ code: 'source-unreadable', origin: 'plugin:' + specName + '/.mcp.json', detail: mcp.problem });
+  }
+
+  /* commands/**：递归计数（只数，不读内容） */
+  const commandFiles = await walkFiles(path.join(pluginDir, 'commands'), {
+    maxDepth: WALK_MAX_DEPTH,
+    maxFiles: options.maxPluginFiles,
+  });
+  if (commandFiles.length > 0) {
+    plugin.commandCount = commandFiles.length;
+    plugin.components.push('commands');
+  }
+  if (commandFiles.length >= options.maxPluginFiles) filesTruncated = true;
+
+  /* agents/*.md：只取文件名（不读内容） */
+  const agentFiles = await walkFiles(path.join(pluginDir, 'agents'), {
+    maxDepth: 0,
+    maxFiles: options.maxPluginFiles,
+    match: (name) => name.endsWith('.md'),
+  });
+  if (agentFiles.length > 0) {
+    plugin.agents = agentFiles.map((file) => file.name).sort();
+    plugin.components.push('agents');
+  }
+  if (agentFiles.length >= options.maxPluginFiles) filesTruncated = true;
+
+  /* hooks/ 与 hooks.json：**只数文件数**（hooks 是执行面，内容一律不读） */
+  const hookFiles = await walkFiles(path.join(pluginDir, 'hooks'), {
+    maxDepth: WALK_MAX_DEPTH,
+    maxFiles: options.maxPluginFiles,
+  });
+  let hookCount = hookFiles.length;
+  if (hookCount >= options.maxPluginFiles) filesTruncated = true;
+  const hooksJson = await statOrNull(path.join(pluginDir, 'hooks.json'));
+  if (hooksJson !== null && hooksJson.isFile()) hookCount += 1;
+  if (hookCount > 0) {
+    plugin.hookFiles = hookCount;
+    plugin.components.push('hooks');
+  }
+
+  if (filesTruncated) {
+    findings.push({
+      code: 'source-unreadable',
+      origin: 'plugin:' + specName,
+      detail: MAX_PLUGIN_FILES_REACHED,
+      count: options.maxPluginFiles,
+    });
+  }
+  if (findings.length > 0) plugin.readFindings = findings;
+  return plugin;
+}
+
+export async function readClaudePlugins(opts: ClaudePluginReadOptions): Promise<ClaudePluginReadResult> {
+  const skipped: ForeignSkip[] = [];
+  const plugins: ClaudePluginInput[] = [];
+  const counts: Record<string, number> = {};
+  const maxFileBytes = positiveLimit(opts.maxFileBytes, DEFAULT_MAX_FILE_BYTES);
+  const maxPlugins = positiveLimit(opts.limits?.maxPlugins, DEFAULT_MAX_PLUGINS);
+  const maxPluginFiles = positiveLimit(opts.limits?.maxPluginFiles, DEFAULT_MAX_PLUGIN_FILES);
+  const pluginsDir = path.join(opts.claudeDir, 'plugins');
+
+  const markets = await readKnownMarketplaces(pluginsDir, maxFileBytes, skipped);
+  const marketByName = new Map(markets.map((market) => [market.name, market]));
+  const specs = await enabledPluginSpecs(pluginsDir, opts.settings, maxFileBytes, skipped);
+
+  counts['marketplaces'] = markets.length;
+  // 「启用条数」：值为真值的键（含找不到安装目录的那些，它们会在 skipped 里各留一条）
+  counts['enabledPlugins'] = specs.length;
+
+  const limited = specs.slice(0, maxPlugins);
+  if (specs.length > maxPlugins) {
+    skipped.push({ code: 'source-unreadable', origin: 'plugins', detail: MAX_PLUGINS_REACHED, count: maxPlugins });
+  }
+
+  let pluginSkills = 0;
+  let pluginCommands = 0;
+  let pluginAgents = 0;
+  let pluginHooks = 0;
+  for (const spec of limited) {
+    const { name, marketplace } = splitPluginSpec(spec);
+    const market = marketplace !== undefined ? marketByName.get(marketplace) : undefined;
+    const located = await locatePluginDir(pluginsDir, name, marketplace, market);
+    if (located.kind === 'missing') {
+      // 有启用记录但找不到安装目录：如实报码（不产出半成品条目）
+      skipped.push({ code: 'source-unreadable', origin: 'plugin:' + name });
+      continue;
+    }
+    if (located.kind === 'symlink') {
+      skipped.push({ code: 'source-unreadable', origin: 'plugin:' + name, detail: DETAIL_SYMLINK });
+      continue;
+    }
+    // 安装位置只进溯源元数据（相对 plugins 目录的 POSIX 路径；逃出该目录时**省略**而不是回传机器路径）
+    const rel = toPosixPath(path.relative(pluginsDir, located.dir));
+    const installRel = rel !== '' && !rel.startsWith('..') ? rel : undefined;
+    const plugin = await readPluginAt(located.dir, name, marketplace, market, {
+      maxPluginFiles,
+      maxFileBytes,
+      ...(installRel !== undefined ? { installRel } : {}),
+    });
+    plugins.push(plugin);
+    pluginSkills += plugin.skills?.length ?? 0;
+    pluginCommands += plugin.commandCount ?? 0;
+    pluginAgents += plugin.agents?.length ?? 0;
+    pluginHooks += plugin.hookFiles ?? 0;
+  }
+
+  counts['plugins'] = plugins.length;
+  counts['pluginSkills'] = pluginSkills;
+  counts['pluginCommands'] = pluginCommands;
+  counts['pluginAgents'] = pluginAgents;
+  counts['pluginHooks'] = pluginHooks;
+
+  return { plugins, marketplaces: markets.map((market) => (market.repo !== undefined ? { name: market.name, repo: market.repo } : { name: market.name })), skipped, counts };
+}

package/src/foreign/registry.ts

@@ -480,11 +480,34 @@ export function builtinForeignSources(): readonly ForeignSource[] {
           { rel: '.claude/skills', dir: true },
           { rel: '.claude/commands', dir: true },
           { rel: '.claude/projects', dir: true },
+          // 2026-10-18 补齐：插件目录 / 子代理定义 / 规则目录（本机实测存在 .claude/plugins 与 .claude/hooks）
+          { rel: '.claude/plugins', dir: true },
+          { rel: '.claude/agents', dir: true },
+          { rel: '.claude/rules', dir: true },
         ]);
-        return { found: probed.paths.length > 0, paths: probed.paths, skipped: probed.skipped };
+        const paths: string[] = [...probed.paths];
+        const skipped: ForeignSkip[] = [...probed.skipped];
+        // CLAUDE_CONFIG_DIR 整体替换配置目录（文档取证：code.claude.com/docs/en/settings）。
+        // **不改既有 home 相对标签**（那会动 UI 文案与既有断言），只在覆盖生效时**追加**一组
+        // 带前缀的标签；真正的读取与 source-location-overridden 报码由读盘层负责。
+        const override = ctx.env['CLAUDE_CONFIG_DIR'];
+        if (override !== undefined && override.trim() !== '') {
+          const alt = await probeTree(override, [
+            { rel: 'settings.json' },
+            { rel: 'CLAUDE.md' },
+            { rel: 'skills', dir: true },
+          ], 'CLAUDE_CONFIG_DIR/');
+          paths.push(...alt.paths);
+          skipped.push(...alt.skipped);
+        }
+        return { found: paths.length > 0, paths, skipped };
       },
       async build(ctx) {
-        const read = await readClaudeCode({ homeDir: ctx.homeDir, ...(ctx.limits !== undefined ? { limits: ctx.limits } : {}) });
+        const read = await readClaudeCode({
+          homeDir: ctx.homeDir,
+          env: ctx.env,
+          ...(ctx.limits !== undefined ? { limits: ctx.limits } : {}),
+        });
         // 会话转码版本必须由宿主解析后传入（绝不猜）；缺省 = 一条都不转并整批报码
         if (ctx.targetSessionFormatVersion !== undefined) {
           read.input.targetSessionFormatVersion = ctx.targetSessionFormatVersion;

package/src/foreign/session-ir.test.ts

@@ -187,3 +187,68 @@ test('标题行：非 user 来源且整场没有人类 user/message → 不产
   assert.equal(rows.some((r) => r.type === 'session/title'), false);
   assert.ok(rows.length > 0, '助手消息本身仍要产出（标题只是装饰）');
 });
+/* ---------------- 未闭合的工具调用（DSH 的 interrupted-turn 修复，形状前提） ---------------- */
+
+/**
+ * 形状护栏（2026-10-18，task-4）：**tool/call 没有 tool/result 时不得伪造任何结算行**。
+ *
+ * 为什么必须钉住：DSH 自己的修复逻辑（interrupted-turn）只认两样东西 —— ① assistant/message
+ * 的 message.content 里有 tool-call 块（它据此知道「这个调用被广告过」）、② 这段流里
+ * **没有**对应的 tool/result。若为了「看起来完整」补一条空 result，DSH 会认为调用已结算，
+ * 中断状态反而丢失；若 content 里没有 tool-call 块，DSH 连「这里有未决调用」都看不到
+ * （deriveEventMessage 对空 content 返回 null）。
+ *
+ * 本用例刻意**只断言形状**（不引入 DSH 在场依赖）：产物必须保持可读、seq 连续、后续事件照常。
+ */
+test('未闭合工具调用：不伪造 result、callId 非空、后续事件与 seq 仍合法（中断由 DSH 修复）', () => {
+  const s = stats();
+  const rows = synthesizeDshRows(
+    {
+      id: 's2',
+      cwd: 'D:/proj',
+      createdAt: NOW,
+      records: 3,
+      messages: [
+        irMessage(irFallbackMessageId(0), 'user', [irTextBlock('开始')], { time: NOW }),
+        // 只有工具调用、没有正文：content 仍必须携带 tool-call 块（否则整条助手消息会消失）
+        irMessage(irFallbackMessageId(1), 'assistant', [irToolCallBlock('c9', 'terminal', { command: 'sleep 100' })], {
+          time: NOW + 1,
+          source: { model: 'claude-sonnet-4' },
+        }),
+        // 中断之后用户继续说话：后续事件不得因为未闭合调用而错乱
+        irMessage(irFallbackMessageId(2), 'user', [irTextBlock('中断后我打字')], { time: NOW + 2 }),
+      ],
+    },
+    { title: 't', titleSource: { kind: 'fallback' }, emptyBlocks: [], provider: 'claude-code', reasoningEffort: 'medium', maxTokens: 8192 },
+    s,
+    NOW + 3,
+  );
+
+  assert.deepEqual(
+    rows.map((r) => r.type),
+    [
+      'user/message', 'session/title', 'turn/start', 'request/header', 'step/start',
+      'assistant/message', 'tool/call', 'step/end', 'turn/end', 'user/message',
+    ],
+    '未闭合调用不改变事件序列形状：只在 step 里留下一条 tool/call，随后照常收尾并继续下一轮',
+  );
+
+  const calls = rows.filter((r) => r.type === 'tool/call');
+  assert.equal(calls.length, 1);
+  const callId = (calls[0]?.data as { callId: string }).callId;
+  assert.ok(typeof callId === 'string' && callId !== '', 'callId 必须非空（空 callId 会被 DSH 前台拒读）');
+  assert.equal(rows.some((r) => r.type === 'tool/result'), false, '绝不伪造空 result：伪造等于替 DSH 结掉这笔中断');
+  assert.equal(s.toolResults, 0, 'toolResults 计数保持 0（没有结果就是没有）');
+  assert.equal(s.toolCalls, 1);
+
+  // DSH interrupted-turn 修复的**唯一依据**：content 里的 tool-call 块必须与事件逐字同 id
+  const assistant = rows.find((r) => r.type === 'assistant/message');
+  const content = (assistant?.data as { message: { content: { type: string; id?: string }[] } }).message.content;
+  assert.deepEqual(content.map((b) => b.type), ['tool-call'], '没有正文的助手消息也必须携带 tool-call 块');
+  assert.equal(content[0]?.id, callId, 'content 块 id 与 tool/call 的 callId 必须逐字相同');
+
+  // 日志本身仍合法：seq 从 0 连续递增，中断之后的用户消息照常产出
+  assert.deepEqual(rows.map((r) => r.seq), rows.map((_, i) => i), 'seq 必须仍连续递增');
+  assert.equal(rows.filter((r) => r.type === 'user/message').length, 2, '中断之后的消息不得被吞掉');
+  assert.equal(rows[rows.length - 1]?.type, 'user/message');
+});

package/src/foreign/truth-table.test.ts

@@ -0,0 +1,81 @@
+/**
+ * 真值表护栏（design doc §8.2 与 truth-table.ts 文件头都声称有「truth-table.test.ts」做
+ * 「真值表 ↔ 各来源 probePaths 逐平台交叉核对」——审计发现**这个文件此前并不存在**，
+ * 6 个配置类来源的 probePaths 因此没有任何交叉核对。本文件补齐它。
+ *
+ * 三条断言（都是源码级真值，不读真机 home）：
+ *  ① 真值表与来源词表**同序同集合**（顺序 = UI/CLI 列表顺序的事实源）；
+ *  ② 配置类来源的 probePaths 必须逐条等于真值表条目按平台展开的结果（未识别令牌原样保留 ⇒ 立刻红）；
+ *  ③ 来源的 evidence 必须逐条等于真值表里的 evidence（**不得在来源定义里自己填更好看的一档**）。
+ *
+ * 会话类 24 个来源的 probePaths 由各自 wiring 提供（session-source.ts 装配），
+ * 本文件只核对它们的真值表条目存在且取证强度一致。
+ */
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { builtinForeignSources, FOREIGN_SOURCE_IDS } from './registry.ts';
+import { FOREIGN_SOURCE_IDS_FROM_SHAPES } from './source-modules.ts';
+import { FOREIGN_TRUTH_TABLES, expandTruthList, TRUTH_PROBES } from './truth-table.ts';
+import type { ForeignPlatform } from './platform-paths.ts';
+
+const PLATFORMS: readonly ForeignPlatform[] = ['win32', 'darwin', 'linux'];
+
+/** 配置类来源（其余 24 个是会话类，probePaths 由各自 wiring 提供） */
+const CONFIG_CLASS: ReadonlySet<string> = new Set([
+  'claude-code', 'hermes', 'cursor', 'codex', 'copilot', 'antigravity',
+]);
+
+test('V1 真值表与来源词表同序同集合（不得漂移）', () => {
+  const tableIds = FOREIGN_TRUTH_TABLES.map((e) => e.id);
+  assert.equal(new Set(tableIds).size, tableIds.length, '真值表 id 必须唯一');
+  assert.deepEqual(tableIds, [...FOREIGN_SOURCE_IDS], '真值表顺序必须等于来源词表顺序');
+  assert.deepEqual(tableIds, [...FOREIGN_SOURCE_IDS_FROM_SHAPES], '真值表顺序必须等于形状表顺序');
+});
+
+test('V2 每个条目三平台都有非空默认位置，且没有未展开令牌', () => {
+  for (const entry of FOREIGN_TRUTH_TABLES) {
+    for (const p of PLATFORMS) {
+      const list = entry.defaults[p];
+      assert.ok(Array.isArray(list), entry.id + ' ' + p + ' 默认位置不是数组');
+      // autoRoots:false = 该来源**没有**自动根（如 chatgpt 只能由用户显式给路径）——空表是刻意的
+      if (entry.autoRoots) {
+        assert.ok(list.length > 0, entry.id + ' ' + p + ' 声明有自动根却没有任何默认位置');
+      }
+      for (const expanded of expandTruthList(p, list)) {
+        assert.ok(!expanded.includes('<'), entry.id + ' ' + p + ' 存在未展开令牌：' + expanded);
+      }
+    }
+    assert.equal(typeof entry.autoRoots, 'boolean', entry.id + ' autoRoots 必须是布尔');
+    assert.ok(entry.refs.length > 0, entry.id + ' refs 必须写明依据');
+  }
+});
+
+test('V3 配置类来源 probePaths 必须逐条等于真值表展开结果', () => {
+  const sources = builtinForeignSources().filter((s) => CONFIG_CLASS.has(s.id));
+  assert.equal(sources.length, CONFIG_CLASS.size, '配置类来源个数与常量表不一致');
+  for (const source of sources) {
+    const entry = FOREIGN_TRUTH_TABLES.find((e) => e.id === source.id);
+    assert.ok(entry !== undefined, source.id + ' 缺真值表条目');
+    for (const p of PLATFORMS) {
+      const probe = TRUTH_PROBES[p];
+      const actual = source.probePaths({ homeDir: probe.homeDir, env: {}, platform: p });
+      assert.deepEqual([...actual], expandTruthList(p, entry.defaults[p]), source.id + ' ' + p + ' probePaths 与真值表不一致');
+    }
+  }
+});
+
+test('V4 来源的 evidence 必须逐条等于真值表（不得美化取证强度）', () => {
+  for (const source of builtinForeignSources()) {
+    const entry = FOREIGN_TRUTH_TABLES.find((e) => e.id === source.id);
+    assert.ok(entry !== undefined, source.id + ' 缺真值表条目');
+    assert.equal(source.evidence, entry.evidence, source.id + ' evidence 与真值表不一致');
+  }
+});
+
+test('V5 CLAUDE_CONFIG_DIR 是 claude-code 的真值表 envKeys（文档取证必须落到数据里）', () => {
+  const entry = FOREIGN_TRUTH_TABLES.find((e) => e.id === 'claude-code');
+  assert.ok(entry !== undefined);
+  const keys = (entry.envKeys ?? []).map((k) => k.key);
+  assert.ok(keys.includes('CLAUDE_CONFIG_DIR'), 'claude-code 必须登记 CLAUDE_CONFIG_DIR');
+});

package/src/foreign/truth-table.ts

@@ -119,12 +119,15 @@ export const FOREIGN_TRUTH_TABLES: readonly ForeignTruthTableEntry[] = [
     defaults: all3(
       '<home>/.claude', '<home>/.claude.json', '<home>/.claude/settings.json',
       '<home>/.claude/CLAUDE.md', '<home>/.claude/skills', '<home>/.claude/commands', '<home>/.claude/projects',
+      // 2026-10-18 实测补齐：插件注册表（known_marketplaces.json）/ 子代理定义 / 规则目录
+      '<home>/.claude/plugins', '<home>/.claude/plugins/known_marketplaces.json',
+      '<home>/.claude/agents', '<home>/.claude/rules',
     ),
-    envKeys: [],
+    envKeys: [{ key: 'CLAUDE_CONFIG_DIR', mode: 'replace', note: '整体替换配置目录（命中即报 source-location-overridden）' }],
     autoRoots: true,
     evidence: 'measured',
-    refs: 'chat-import §3.1 claude 行（projects + Claude-3p 第二根）；本仓本机实测（~/.claude、~/.claude.json 存在）',
-    dynamic: '会话在 ~/.claude/projects/<slug>/<uuid>.jsonl（v1 已实现会话转码）',
+    refs: 'chat-import §3.1 claude 行（projects + Claude-3p 第二根）；本仓本机实测（~/.claude、~/.claude.json 存在）；2026-10-18 本机实测 plugins/known_marketplaces.json 与 marketplaces/<市场>/.claude-plugin/{marketplace,plugin}.json 结构',
+    dynamic: '会话在 ~/.claude/projects/<slug>/<uuid>.jsonl（v1 已实现会话转码）；项目级配置根来自 ~/.claude.json 的 projects 键（**只取真实存在的目录，绝不猜路径**）；插件启用清单来自 settings.json 的 enabledPlugins（本机缺省为空 = 没有启用的插件，不报码）',
   },
   {
     id: 'hermes',