dsh-config-manager 0.1.78 → 0.1.80

package/lib/foreign/read-claude-plugins.js

@@ -0,0 +1,403 @@
+/**
+ * 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.js';
+import { stripUserInfo } from './kernel.js';
+import { listDirSafe, readJsonSafe, statOrNull, toPosixPath, walkFiles } from './session-read.js';
+import { readSkillUnits } from './read-claude-code.js';
+/** 插件数上限触顶（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';
+/** 有上限的整数解析：只用安全正整数（脏值一律回落缺省） */
+function positiveLimit(value, fallback) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? value : fallback;
+}
+/** source.repo 或 source.url（两者都可能带 userinfo；剥离在调用处统一做） */
+function repoOfSource(source) {
+    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, maxFileBytes, skipped) {
+    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 = [];
+    for (const name of Object.keys(jr.value).sort()) {
+        const raw = jr.value[name];
+        const record = { 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) {
+    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) {
+    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.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, settings, maxFileBytes, skipped) {
+    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) {
+    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) };
+}
+/** 某个父目录下名为 name 的条目（**不跟链接**：dirent 自带 isSymbolicLink） */
+async function direntOf(target) {
+    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;
+}
+/**
+ * 定位插件安装目录（顺序：市场下 plugins/ → external_plugins/ → 市场 installLocation 的同名目录及其
+ * 两种标准子目录）。命中符号链接 → symlink（不跟随）；都不在 → missing（由调用方报码）。
+ */
+async function locatePluginDir(pluginsDir, name, marketplace, market) {
+    const candidates = [];
+    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, fallbackName, maxFileBytes, findings) {
+    const out = { 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, specName, marketplace, market, options) {
+    const findings = [];
+    const manifest = await readPluginManifest(pluginDir, specName, options.maxFileBytes, findings);
+    const plugin = { 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 = [];
+    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) {
+    const skipped = [];
+    const plugins = [];
+    const counts = {};
+    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 };
+}
+//# sourceMappingURL=read-claude-plugins.js.map

package/lib/foreign/registry.js

@@ -310,11 +310,34 @@ export function builtinForeignSources() {
                     { 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 = [...probed.paths];
+                const skipped = [...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/lib/foreign/truth-table.js

@@ -43,12 +43,14 @@ export const FOREIGN_TRUTH_TABLES = [
     /* ============ 配置类（v1 既有六个；本次**只补 probePaths/evidence**，路径表不动） ============ */
     {
         id: 'claude-code',
-        defaults: all3('<home>/.claude', '<home>/.claude.json', '<home>/.claude/settings.json', '<home>/.claude/CLAUDE.md', '<home>/.claude/skills', '<home>/.claude/commands', '<home>/.claude/projects'),
-        envKeys: [],
+        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: [{ 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',

package/lib/foreign/types.d.ts

@@ -127,7 +127,23 @@ export type ForeignSkipCode =
  * 该来源**没有自动根**（竞品 `defaultRoots.chatgpt = null`）—— 必须由用户显式给出导出文件
  * 路径；本机自动探测永远不会命中，如实报码而不是假装「未安装」。
  */
- | 'source-needs-explicit-path';
+ | 'source-needs-explicit-path'
+/** settings.json 的 permissions（allow/ask/deny）：DSH 无权限规则文件对等结构，只报告条数 */
+ | 'unsupported-permissions'
+/** settings.json 里其余未迁移的顶层键（只记键名与条数，**值一律不读**） */
+ | 'unsupported-settings-keys'
+/** .claude/agents/*.md 子代理定义：DSH 的 subagent 是运行时 provider 注册制，无文件级对等结构 */
+ | 'unsupported-agents'
+/** .claude/rules/*.md 带 frontmatter 作用域：合并进全局指令会丢作用域，故只报告 */
+ | 'unsupported-rules'
+/** Claude Code 插件本体（插件 API / hooks / commands 的执行面）：DSH 无法加载，**绝不复制其代码** */
+ | 'unsupported-plugins'
+/** 会话记录里的 sessionId 与文件名 stem 不一致（DSH 以目录/文件名定位会话，故以文件名为准并如实报码） */
+ | 'session-id-mismatch'
+/** 同名 MCP server 在多处出现（全局 / 项目级 / 插件）：先到先得，其余只报告 */
+ | 'mcp-server-id-conflict'
+/** 项目级扫描触顶（maxProjects）：**不静默**，如实报码 */
+ | 'project-scan-truncated';
 /**
  * 冲突语义（**契约冻结**，§8.4）：同 id 会话恒「不覆盖、跳过并报码」。
  *
@@ -163,7 +179,7 @@ export interface ClaudeCodeInput {
     skills?: ClaudeSkillInput[];
     /** ~/.claude/CLAUDE.md 原文（全局指令） */
     memory?: string;
-    /** ~/.claude/commands/* 的普通文件数（本期只报不搬） */
+    /** ~/.claude/commands/** 的普通文件数（**递归**；只报不搬） */
     commandCount?: number;
     /** ~/.claude/projects/<项目>/<uuid>.jsonl 的原文（转码在翻译层做） */
     sessions?: ClaudeSessionInput[];
@@ -172,12 +188,120 @@ export interface ClaudeCodeInput {
      * 缺省 = 不转码任何会话并逐条报 session-format-version-unknown，绝不猜版本。
      */
     targetSessionFormatVersion?: number;
+    /**
+     * 实际使用的 Claude 配置目录绝对路径（CLAUDE_CONFIG_DIR 覆盖时为该值，否则 <home>/.claude）。
+     * **只进溯源元数据**，不进任何分区载荷。
+     */
+    configDir?: string;
+    /** 位置被 CLAUDE_CONFIG_DIR 覆盖（命中即报 source-location-overridden） */
+    configDirOverridden?: boolean;
+    /** 来源侧版本标记（~/.claude.json 的 lastVersionBase 等；拿不到即省略） */
+    sourceVersion?: string;
+    /** 项目级配置的已读形态（项目根来自 ~/.claude.json 的 projects 键；**不猜路径**） */
+    projects?: ClaudeProjectInput[];
+    /** 用户级 Claude Code 插件的已读形态（只读元数据与组件，**绝不执行插件代码**） */
+    plugins?: ClaudePluginInput[];
+    /** 已登记的市场（name + 来源仓库；URL 的 userinfo 已剥离） */
+    marketplaces?: {
+        name: string;
+        repo?: string;
+    }[];
+}
+/**
+ * 一个 Claude Code **项目级**配置目录的已读形态（纯数据；翻译层不做任何 fs 访问）。
+ *
+ * 位置口径（实测取证 2026-10-18，本机 ~/.claude.json 的 projects 键）：项目根来自
+ * `~/.claude.json` 的 `projects` 键（绝对路径，Claude Code 自己写的权威清单）——
+ * **不按目录名猜项目路径**（猜 = 把会话归到不存在的目录）。
+ */
+export interface ClaudeProjectInput {
+    /** 项目根绝对路径（**仅进溯源元数据与报码，不进任何分区载荷**） */
+    root: string;
+    /** `<root>/.claude` 是否存在（false = 该项目没有 Claude 配置，读盘层不产出任何 finding） */
+    hasClaudeDir?: boolean;
+    /** `<root>/.claude/settings.json`（已解析） */
+    settings?: unknown;
+    /** `<root>/.claude/settings.local.json`（已解析；值一律不读，只做诊断） */
+    settingsLocal?: unknown;
+    /** `<root>/CLAUDE.md` 原文（项目级指令） */
+    memory?: string;
+    /** `<root>/CLAUDE.local.md` 原文（本地覆盖指令） */
+    memoryLocal?: string;
+    /** `<root>/.claude/rules/*.md`：文件名 + 原文（带 frontmatter 的按 unsupported-rules 只报告） */
+    rules?: {
+        name: string;
+        text: string;
+    }[];
+    /** `<root>/.mcp.json`（已解析；Claude Code 的项目级 MCP 载体） */
+    mcpJson?: unknown;
+    /** `~/.claude.json` → `projects[<root>].mcpServers`（已解析） */
+    projectMcp?: unknown;
+    /** `<root>/.claude/skills/*` 的单元 */
+    skills?: ClaudeSkillInput[];
+    /** `<root>/.claude/commands/**` 的普通文件数（**递归**；只报不搬） */
+    commandCount?: number;
+    /** `<root>/.claude/agents/*.md`：名字 + 文件名（只报告，无文件级对等结构） */
+    agents?: {
+        name: string;
+        file: string;
+    }[];
+    /** 读盘层发现的问题（读不到 / 超限 / 非法）——由翻译层原样带出 */
+    readFindings?: ForeignSkip[];
+}
+/**
+ * 一个 Claude Code **插件**的已读形态（纯数据）。
+ *
+ * 三条结构性保证：
+ *  ① **只读元数据与组件，绝不执行插件代码**（Claude 插件的 hooks/commands 是 JS 执行面）；
+ *  ② 安装位置/来源只进**溯源元数据**（bundle 的 foreign 块），不由本层写进任何分区；
+ *  ③ 能无损复用的组件只有 skills 与 .mcp.json 里的 MCP 定义（凭据先剥离），其余一律报码。
+ */
+export interface ClaudePluginInput {
+    /** 插件名（plugin.json 的 name；缺失时回落目录名） */
+    name: string;
+    /** 插件版本（plugin.json 的 version；缺失即省略） */
+    version?: string;
+    /** 来源市场名（known_marketplaces.json / marketplace.json 的键） */
+    marketplace?: string;
+    /** 来源仓库（owner/repo 或 URL；**已剥离 userinfo，绝不含凭据**） */
+    repo?: string;
+    /** 来源 ref / sha（若有） */
+    ref?: string;
+    /** 安装位置（相对 ~/.claude/plugins 的 POSIX 相对路径；进溯源用） */
+    installRel?: string;
+    /** 实际存在的组件种类（skills / commands / agents / hooks / mcp），供诊断文案用 */
+    components: string[];
+    /** 插件自带的 skills（name = 压平后的技能名） */
+    skills?: ClaudeSkillInput[];
+    /** 插件自带 `.mcp.json`（已解析） */
+    mcpJson?: unknown;
+    /** 插件自带 commands 的文件数（**递归**；只报不搬） */
+    commandCount?: number;
+    /** 插件自带 agents 的文件名（只报告） */
+    agents?: string[];
+    /** 插件自带 hooks 的文件数（只报告；绝不只是不执行） */
+    hookFiles?: number;
+    /** 读盘层发现的问题 */
+    readFindings?: ForeignSkip[];
 }
 /** 一个待转码的 Claude Code 会话文件 */
 export interface ClaudeSessionInput {
     /** 文件名（不含 .jsonl）；同时作为 DSH 侧会话 id */
     id: string;
     text: string;
+    /**
+     * 记录里首个出现的 sessionId。与 id（文件名 stem）不一致时由翻译层报 session-id-mismatch：
+     * DSH 以「目录名/文件名」定位会话，故仍以文件名为准，但**不静默**。
+     */
+    recordSessionId?: string;
+    /**
+     * 确定性 createdAt 回落值（毫秒）：读盘层给「最早可解析记录时间」，没有时间戳时给文件 mtime。
+     *
+     * 为什么必须由读盘层给：DSH 侧「同内容 → Skip」的判定是**逐字节**的，而会话产物里带着
+     * createdAt/updatedAt；若回落用 Date.now()，同一来源转码两次字节必然不同 ⇒ 重复导入恒判
+     * Conflict 而不是 Skip（实测缺陷）。由文件自身 mtime 回落即可让转码**幂等**。
+     */
+    createdAtMs?: number;
 }
 /** 一个 Hermes skill 单元：**已压平**的叶子技能名 + 目录内文件（category 只用于报告，不参与命名） */
 export interface HermesSkillInput {
@@ -269,4 +393,48 @@ export interface ForeignImportResult {
      */
     credentialRefs: string[];
     counts: Record<string, number>;
+    /**
+     * 溯源块（进 bundle 的 manifest.foreign；缺省 = 不写 —— 旧行为逐字不变）。
+     * 由**翻译层**装配（只有它同时看得到位置、项目根与插件清单）。
+     */
+    origin?: ForeignOrigin;
+}
+/**
+ * 外部来源的**溯源块**（进 bundle 的 manifest.foreign，见 src/schema/types.ts）。
+ *
+ * 为什么必须有：标准 bundle v1 的 manifest 原本没有任何「这包从哪来」的字段，落盘后
+ * 包与 DSH 自产备份**逐字同构**（实测缺陷）—— 事后无法复核来源、兼容性评分也因
+ * source.dshVersion 被填成目标机版本而被构造性拉满。
+ *
+ * 三条纪律：
+ *  ① **只放标识与计数，绝不放值**（凭据引用只有名字；错误只有机器码）；
+ *  ② 绝对路径只允许出现在 projects[] 与 installPath 这类「用户自己机器的来源位置」上，
+ *     且**不得**写进任何分区载荷；
+ *  ③ 缺字段即「不知道」，绝不填默认值假装知道。
+ */
+export interface ForeignOrigin {
+    /** 来源 agent id（ForeignSourceId 的运行期字面量） */
+    source: string;
+    /** 实际读取的位置（相对 home 的 POSIX 路径；不含任何值） */
+    locations: string[];
+    /** 来源侧版本标记（如 Claude Code `~/.claude.json` 的 lastVersionBase；读不到即省略） */
+    sourceVersion?: string;
+    /** 被扫描的项目根绝对路径（仅溯源，供用户核对） */
+    projects?: string[];
+    /** 插件清单（名称 / 版本 / 市场 / 来源仓库 / ref / 组件种类；**不含凭据**） */
+    plugins?: {
+        name: string;
+        version?: string;
+        marketplace?: string;
+        repo?: string;
+        ref?: string;
+        components?: string[];
+    }[];
+    /** 跳过与诊断汇总（机器码 + 条数，**不含任何值**） */
+    skipped?: {
+        code: string;
+        count: number;
+    }[];
+    /** 需要用户在目标机补录的凭据引用名（只有名字） */
+    credentialRefs?: string[];
 }