dsh-config-manager 0.1.69 → 0.1.71

package/lib/cli/import-source.js

@@ -0,0 +1,178 @@
+/**
+ * `dcm import --from <来源> [--dry-run]` —— 把**本机已装的外部 agent 配置**翻译成标准 bundle v1 ZIP。
+ *
+ * 为什么是「翻译成标准 bundle」而不是自己写导入：读侧只需要实现一次（Importer/analyzer）——
+ * 校验和、schema 版本协商、Zip Slip 拒绝、冲突判定、导入前强制快照、dry-run 全部自动生效，
+ * 不为外部来源另开一条写入通道（见 src/foreign/bundle.ts 的文件头）。
+ *
+ * 四条纪律：
+ *  ① **--dry-run 零写入**：只跑检测 + 构建并打印分区摘要，连导出目录都不 mkdir；
+ *  ② **绝不覆盖既有文件**：--out 命中已有文件时自动加 -1/-2 后缀（与 backup 同语义）；
+ *     一个分区都产不出来时退出码 1（空的 bundle 会「自检通过」却什么都没有，绝不静默成功）；
+ *  ③ **凭据值绝不出现**：摘要只打印 skipped 机器码与**凭据引用名**（形如 mcp:svc:GITHUB_TOKEN）；
+ *  ④ **未知来源不猜**：打印可用来源清单并退出码 1（绝不回退到某个默认来源）。
+ *
+ * 本模块不 import ./index.ts（避免运行时循环）：所有需要由 CLI 解析的东西
+ * （导出目录、版本号、--data-dir 语义）都由调用方作为参数传入。
+ */
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { verifyBackupZip } from '../core/backup-verify.js';
+import { writeForeignBundle } from '../foreign/bundle.js';
+import { FOREIGN_CONFLICT_POLICY, ForeignSourceError, createBuiltinForeignSourceRegistry, } from '../foreign/registry.js';
+import { foreignSourceContext } from '../routes/foreign-context.js';
+/** 分区摘要的一行：文件类给文件数，JSON 类给该分区的计数键（全部是机器可读的条目数） */
+function sectionLine(section, result) {
+    if (section.files !== undefined)
+        return `  ${section.sectionId}: ${section.files.length} 个文件`;
+    const counters = Object.entries(result.counts)
+        .filter(([key]) => key.startsWith(section.sectionId + '.'))
+        .map(([key, value]) => key + '=' + String(value));
+    return `  ${section.sectionId}: JSON${counters.length > 0 ? '（' + counters.join(', ') + '）' : '（无条目计数）'}`;
+}
+function printSkipped(result, io) {
+    if (result.skipped.length === 0) {
+        io.log('未迁移项 / skipped: 无');
+        return;
+    }
+    io.log(`未迁移项 / skipped（${result.skipped.length}）:`);
+    for (const s of result.skipped) {
+        const origin = s.origin !== undefined ? s.origin : '';
+        const detail = s.detail !== undefined ? '（' + s.detail + '）' : '';
+        const count = s.count !== undefined ? ' ×' + String(s.count) : '';
+        io.log(`  [${s.code}] ${origin}${detail}${count}`);
+    }
+}
+/** 打印摘要：**只有路径/机器码/引用名，绝无任何配置值** */
+function printImportSummary(sourceId, detection, result, io) {
+    io.log(`来源 / source: ${sourceId}`);
+    io.log(`本机检测 / detection: ${detection.found ? '已找到 / found' : '未找到本机痕迹 / not found'}`);
+    if (detection.paths.length > 0)
+        io.log(`  位置 /${' '}paths: ${detection.paths.join(', ')}`);
+    for (const s of detection.skipped ?? []) {
+        io.log(`  检测提示 / detection note: [${s.code}]${s.origin !== undefined ? ' ' + s.origin : ''}`);
+    }
+    io.log(`待导入分区 / sections（${result.sections.length}）:`);
+    if (result.sections.length === 0)
+        io.log('  （无可导入内容）/ nothing to import');
+    for (const section of result.sections)
+        io.log(sectionLine(section, result));
+    printSkipped(result, io);
+    io.log(result.credentialRefs.length > 0
+        ? `需在 DSH 补录的凭据引用 / credential refs（${result.credentialRefs.length}）: ${result.credentialRefs.join(', ')}`
+        : '需在 DSH 补录的凭据引用 / credential refs: 无');
+    io.log(`冲突策略 / conflict policy: ${FOREIGN_CONFLICT_POLICY}（不覆盖目标机既有同 id；跳过并报码）`);
+}
+/** 目标 ZIP：--out 优先；命中既有文件时自动加后缀，**绝不覆盖** */
+async function resolveOutPath(options, sourceId) {
+    const desired = options.out !== undefined && options.out !== ''
+        ? path.resolve(options.out)
+        : path.join(options.exportsDir, 'foreign-' + sourceId + '-' + stamp() + '-' + randomHex4() + '.zip');
+    if (!(await pathExists(desired)))
+        return desired;
+    const base = desired.endsWith('.zip') ? desired.slice(0, -4) : desired;
+    for (let i = 1;; i += 1) {
+        const candidate = base + '-' + String(i) + '.zip';
+        if (!(await pathExists(candidate)))
+            return candidate;
+    }
+}
+function stamp() {
+    const now = new Date();
+    return `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, '0')}${String(now.getDate()).padStart(2, '0')}`
+        + `-${String(now.getHours()).padStart(2, '0')}${String(now.getMinutes()).padStart(2, '0')}${String(now.getSeconds()).padStart(2, '0')}`;
+}
+function randomHex4() {
+    // 用全局 crypto（Node ≥ 19）；零额外依赖
+    const bytes = new Uint8Array(4);
+    globalThis.crypto.getRandomValues(bytes);
+    return [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+async function pathExists(p) {
+    try {
+        await fsp.stat(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 执行 `import --from`。
+ *
+ * `projectDir` 语义：`--cwd` 显式给出时用它；缺省 = 进程 cwd（「我现在在哪个项目里」就是
+ * Cursor/Codex 项目级配置的含义）。宿主路由走 `?projectDir=`，缺省不猜（不扫 DSH 自己的 cwd）。
+ */
+export async function runImportSource(options, io, env = process.env, deps = {}) {
+    const registry = createBuiltinForeignSourceRegistry();
+    let source;
+    try {
+        source = registry.get(options.from);
+    }
+    catch (error) {
+        if (error instanceof ForeignSourceError) {
+            io.error('未知外部来源 / unknown foreign source: ' + options.from);
+            io.error('可用来源 / available sources: ' + (error.available.length > 0 ? error.available.join(', ') : '(空)'));
+            return 1;
+        }
+        throw error;
+    }
+    /**
+     * 来源上下文**经唯一构造点**（src/routes/foreign-context.ts）——宿主 GET/POST 与 CLI 三处
+     * 必须同源，否则会出现「界面上找得到、命令行读不到」这类只在某一入口复现的怪事。
+     *
+     * 注意 projectDir 的缺省语义**在 CLI 侧不同**：CLI 的「我现在在哪个项目里」就是进程 cwd
+     * （用户显式在项目目录下敲命令），所以这里缺省传 process.cwd()；宿主侧则**绝不猜**
+     * （宿主进程的 cwd 不是用户的项目，缺省不传 = 不扫项目级）。这是刻意的入口语义差异，
+     * 不是分叉 —— 传什么由调用方决定，怎么拼只有一处实现。
+     */
+    const ctx = foreignSourceContext({
+        userHome: deps.userHome,
+        env,
+        projectDir: options.cwd !== undefined && options.cwd !== '' ? options.cwd : process.cwd(),
+    });
+    const detection = await source.detect(ctx);
+    const result = await source.build(ctx);
+    printImportSummary(source.id, detection, result, io);
+    // 一个分区都产不出来时**必须失败**：空的 bundle 会自检通过，用户却拿到什么都没有的包
+    //（与 backup「没有可打包的内容」同口径）。读盘层的 skipped 已经在上面如实打印了原因。
+    if (result.sections.length === 0) {
+        io.error('没有可导入的内容 / nothing to import（' + source.id + '：本机没有可转换的配置）');
+        return 1;
+    }
+    if (options.dryRun) {
+        io.log('（dry-run：零写入，未生成任何 ZIP）/ dry-run: nothing written');
+        return 0;
+    }
+    const outPath = await resolveOutPath(options, source.id);
+    try {
+        // 真正落盘前才创建目录（dry-run 已提前返回，不产生任何写入）
+        await fsp.mkdir(path.dirname(outPath), { recursive: true });
+        await writeForeignBundle({
+            result,
+            outPath,
+            exporterVersion: options.exporterVersion ?? '0.0.0-unknown',
+            // 离线 CLI 探测不到真实 DSH 版本：如实标注（与 backup 同口径，绝不谎报）
+            dshVersion: options.dshVersion ?? 'cli-offline',
+            platform: process.platform,
+            arch: process.arch,
+        });
+    }
+    catch (error) {
+        io.error('生成 bundle 失败 / failed to write bundle: ' + (error instanceof Error ? error.message : String(error)));
+        return 1;
+    }
+    io.log('已生成 bundle / bundle written: ' + outPath);
+    // 落盘后立即自检（与 verify 同一引擎）：只有自检通过才返回 0
+    const check = await verifyBackupZip(outPath);
+    io.log(`[${check.verdict}] ${path.basename(outPath)}`);
+    for (const e of check.errors)
+        io.error('    ! ' + e);
+    if (check.verdict !== 'OK') {
+        io.error('自检未通过（文件已保留，请复核）/ self-verification failed（file kept）');
+        return 1;
+    }
+    io.log('自检通过 / self-verification OK');
+    return 0;
+}
+//# sourceMappingURL=import-source.js.map

package/lib/cli/index.d.ts

@@ -1,9 +1,14 @@
 #!/usr/bin/env node
 import { type SnapshotMeta } from '../core/restore.ts';
 import { type ReinstallItemId } from '../core/reinstall.ts';
-export type CliCommand = 'snapshots' | 'restore' | 'reinstall' | 'recover-stale-lock' | 'verify' | 'backup' | 'sessions' | 'web' | 'help';
+export type CliCommand = 'snapshots' | 'restore' | 'reinstall' | 'recover-stale-lock' | 'verify' | 'backup' | 'import' | 'sessions' | 'web' | 'help';
 export interface CliOptions {
     command: CliCommand;
+    /**
+     * 详情页主题（`dcm help <命令>` / `dcm <命令> --help`）。
+     * 只在 command === 'help' 时有意义；认不认识由运行层判定（解析器不重复维护一份命令表）。
+     */
+    helpTopic?: string;
     /** --data-dir：快照数据目录（verify/backup 下为导出目录）覆盖 */
     dataDir?: string;
     /**
@@ -31,8 +36,12 @@ export interface CliOptions {
     json: boolean;
     /** --sections <a,b,c>：backup 要打包的离线分区白名单（缺省取默认分区） */
     sections?: string;
-    /** --out <path>：backup 输出 ZIP 路径（缺省写入导出目录，自动去重不覆盖） */
+    /** --out <path>：backup / import 输出 ZIP 路径（缺省写入导出目录，自动去重不覆盖） */
     out?: string;
+    /** --from <source>：import 的外部来源 id（30 个之一） */
+    from?: string;
+    /** --cwd <dir>：import 的项目目录（契约 §8.2 的项目级路径；缺省 = 进程 cwd） */
+    cwd?: string;
     /** --home <dir>：sessions repair 要修复的 DSH home（缺省 $DSH_HOME） */
     home?: string;
     /** --fix：sessions repair 真的落盘（缺省只报告） */
@@ -107,6 +116,13 @@ export interface CliIo {
     error: (s: string) => void;
 }
 export declare function printUsage(io?: CliIo): void;
+/**
+ * 打印单命令详情页（`dcm <命令> --help` / `dcm help <命令>`）。
+ *
+ * 返回 false 表示不认识该命令名（调用方决定报错文案）；成功时已写完输出。
+ * 文案与退出码都在 ./help.ts，本函数只做「渲染 → 输出」。
+ */
+export declare function printCommandUsage(name: string, io?: CliIo): boolean;
 export interface CliDeps {
     /** 交互提问（缺省用真实 stdin/stdout readline） */
     ask?: (prompt: string) => Promise<string>;

package/lib/cli/index.js

@@ -4,19 +4,11 @@
  * 离线快照列表/恢复 + 一键重装 DSH 命令，零 DSH 运行时依赖（仅 node 内置 + 本项目
  * core 引擎；绝不 import @deepseek-ai/*，peerDependencies 缺失也能跑）。
  *
- * 子命令：
- *   snapshots [--data-dir <dir>]         列出快照（listSnapshots）
- *   restore [--id <uuid>] [--dry-run]    恢复到导入前状态（planRestore 预览 / restore 执行）
- *           [--data-dir <dir>] [--data-root <dir>] [--profile <name>] [--settings <path>]
- *   reinstall [--version <v>] [--yes] [--list] [--wipe-config] [--dry-run] [--data-root <dir>]
- *             一键重装 DSH 程序（交互多选 + 二次确认 / 跨平台执行）
- *   verify [--id <file|path>] [--json] [--data-dir <dir>]
- *             离线只读自检备份 ZIP（结构 + integrity/checksums 完整性；不改一个字节）
- *   backup [--sections <a,b,c>] [--out <path>] [--dry-run] [--data-dir <dir>]
- *             离线文件级备份（导出目录内生成与 GUI 同结构的 ZIP，落盘后自检）
- *   web [--port <n>] [--no-open] [--home <dir>] [--data-root <dir>] [--idle-timeout <分钟>]
- *             离线只读救急台（本机网页：实例/SafeMode/锁/快照/备份自检/磁盘/会话体检）
- *   help | --help | -h                    显示全部命令与说明
+ * 子命令一览、选项、退出码的**唯一事实源是 ./help.ts**（速查页 + 每命令详情页）：
+ * 本文件只负责解析参数与执行，不再散写文案。
+ *   dcm help                  速查页（按风险分组的命令表 + 通用选项）
+ *   dcm <命令> --help         单命令详情页（说明 / 选项 / 退出码 / 示例）
+ *   dcm help <命令>           同上
  *
  * 缺省数据目录 = $DSH_HOME/dsh-config-manager/snapshots（$DSH_HOME 缺省 ~/.dsh）。
  * 破坏性命令（restore / reinstall）的 SAFE MODE 门按「控制面根」定位标记：
@@ -36,10 +28,12 @@ import { REINSTALL_ITEMS, buildReinstallPlan, isWindows, detectInstalledDshVersi
 import { EnvironmentLockManager, runWithMutationLock, EnvironmentLockUnavailableError, OWNERSHIP_FILE } from '../utils/env-lock.js';
 import { runSessionsRepair } from './sessions-repair.js';
 import { runSessionsInspect } from './sessions-inspect.js';
+import { runImportSource } from './import-source.js';
+import { renderCommandHelp, renderOverview } from './help.js';
 import { collectVerifyResults, readRunningInstances } from './actions.js';
 import { Phase3Recovery, readSafeModeMarkerSync, safeModeMarkerPath } from '../core/phase3-host.js';
 import { verifyBackupZip, } from '../core/backup-verify.js';
-import { collectBackupEntries, buildSectionFlags, parseSectionsArg, DEFAULT_BACKUP_SECTIONS, OFFLINE_UNAVAILABLE_SECTIONS, } from '../core/backup-plan.js';
+import { collectBackupEntries, buildSectionFlags, parseSectionsArg, OFFLINE_UNAVAILABLE_SECTIONS, } from '../core/backup-plan.js';
 import { buildChecksums } from '../utils/hashing.js';
 import { stringifyJsonSafe } from '../utils/json.js';
 import { buildManifest, CHECKSUMS_FILE, MANIFEST_FILE } from '../schema/manifest.js';
@@ -63,6 +57,8 @@ const BACKUP_REJECTED_FLAGS = new Set(['--id', '--profile', '--settings']);
 const RESTORE_ONLY_FLAGS = new Set(['--id', '--dry-run', '--profile', '--settings']);
 /** 仅 reinstall 子命令允许的参数 */
 const REINSTALL_ONLY_FLAGS = new Set(['--yes', '--list', '--wipe-config', '--version']);
+/** 仅 import 允许的参数（--out/--dry-run 与 backup/restore 共用，故不在此表） */
+const IMPORT_ONLY_FLAGS = new Set(['--from', '--cwd']);
 /** 仅 web（离线救急台）允许的参数 */
 const WEB_ONLY_FLAGS = new Set(['--port', '--no-open', '--idle-timeout']);
 /** web 明确不支持的参数：宁可报错，也不悄悄忽略（它们属于读写命令，不属于只读台） */
@@ -75,6 +71,9 @@ function parseCliDataDir(argv) {
     const options = { command: 'recover-stale-lock', dryRun: false, profile: 'web', yes: false, list: false, wipeConfig: false, json: false, positionals: [] };
     for (let i = 1; i < argv.length; i += 1) {
         const flag = argv[i];
+        if (flag === '--help' || flag === '-h') {
+            return { ok: true, options: { ...options, command: 'help', helpTopic: 'recover-stale-lock' } };
+        }
         if (flag === '--data-dir') {
             const value = argv[i + 1];
             if (value === undefined || value === '' || value.startsWith('-')) {
@@ -113,6 +112,9 @@ function parseCliSessions(argv) {
     const action = rest[0];
     if (action === undefined)
         return { ok: false, error: 'sessions 需要子动作 / missing action: sessions repair' };
+    if (action === '--help' || action === '-h') {
+        return { ok: true, options: { ...options, command: 'help', helpTopic: 'sessions' } };
+    }
     // T6：三个只读/安全动作 —— list（列出会话）/ doctor（体检）/ repair（预览或 --fix 执行）
     if (action !== 'repair' && action !== 'list' && action !== 'doctor') {
         return { ok: false, error: 'sessions 只支持 list / doctor / repair / unsupported action: ' + action };
@@ -120,6 +122,9 @@ function parseCliSessions(argv) {
     options.positionals.push(action);
     for (let i = 1; i < rest.length; i += 1) {
         const flag = rest[i];
+        if (flag === '--help' || flag === '-h') {
+            return { ok: true, options: { ...options, command: 'help', helpTopic: 'sessions' } };
+        }
         if (flag === '--fix') {
             options.fix = true;
             continue;
@@ -164,20 +169,77 @@ function parseCliSessions(argv) {
     }
     return { ok: true, options };
 }
+/**
+ * import 专用解析：`import --from <source> [--dry-run] [--out <path>] [--cwd <dir>] [--data-dir <dir>]`
+ *
+ * 与 sessions / recover-stale-lock 同样的姿态：只接受本动作真正有意义的参数（绝不悄悄忽略）。
+ * `--from` 的值在这里**不做词表校验**：未知来源要由运行层给出「可用来源清单」——
+ * 那需要真实注册表（CLI 与宿主共用同一份装配，见 src/foreign/registry.ts）。
+ */
+function parseCliImport(argv) {
+    const options = {
+        command: 'import', dryRun: false, profile: 'web', yes: false, list: false,
+        wipeConfig: false, json: false, positionals: [],
+    };
+    const rest = argv.slice(1);
+    for (let i = 0; i < rest.length; i += 1) {
+        const flag = rest[i];
+        if (flag === '--help' || flag === '-h')
+            return { ok: true, options: { ...options, command: 'help', helpTopic: 'import' } };
+        if (flag === '--dry-run') {
+            options.dryRun = true;
+            continue;
+        }
+        const at = flag.indexOf('=');
+        const name = at >= 0 ? flag.slice(0, at) : flag;
+        const isValueFlag = name === '--from' || name === '--cwd' || name === '--out' || name === '--data-dir';
+        if (isValueFlag) {
+            const value = at >= 0 ? flag.slice(at + 1) : rest[i + 1];
+            if (value === undefined || value === '' || value.startsWith('-')) {
+                return { ok: false, error: '参数 ' + name + ' 缺少值 / missing value for ' + name };
+            }
+            if (name === '--from')
+                options.from = value;
+            else if (name === '--cwd')
+                options.cwd = value;
+            else if (name === '--out')
+                options.out = value;
+            else
+                options.dataDir = value;
+            if (at < 0)
+                i += 1;
+            continue;
+        }
+        return { ok: false, error: '未知参数 / unknown flag: ' + flag };
+    }
+    if (options.from === undefined || options.from === '') {
+        return { ok: false, error: 'import 需要 --from <来源> / import requires --from <source>' };
+    }
+    return { ok: true, options };
+}
 /** 解析 CLI 参数（纯函数；help 返回 command:'help'，未知/缺值返回错误） */
 export function parseCli(argv) {
     const command = argv[0];
     if (command === undefined)
         return { ok: false, error: '缺少子命令 / missing subcommand' };
     if (command === '--help' || command === '-h' || command === 'help') {
-        return { ok: true, options: { command: 'help', dryRun: false, profile: 'web', yes: false, list: false, wipeConfig: false, json: false, positionals: [] } };
+        const base = { command: 'help', dryRun: false, profile: 'web', yes: false, list: false, wipeConfig: false, json: false, positionals: [] };
+        // `dcm help <命令>`：把主题带下去（认不认识由运行层判定，解析器不重复维护一份命令表）
+        const topic = argv[1];
+        if (command === 'help' && topic !== undefined && topic !== '' && !topic.startsWith('-')) {
+            return { ok: true, options: { ...base, helpTopic: topic } };
+        }
+        return { ok: true, options: base };
     }
     if (command !== 'snapshots' && command !== 'restore' && command !== 'reinstall' && command !== 'sessions'
-        && command !== 'recover-stale-lock' && command !== 'verify' && command !== 'backup' && command !== 'web') {
+        && command !== 'recover-stale-lock' && command !== 'verify' && command !== 'backup' && command !== 'web'
+        && command !== 'import') {
         return { ok: false, error: `未知子命令 / unknown subcommand: ${command}` };
     }
     if (command === 'sessions')
         return parseCliSessions(argv);
+    if (command === 'import')
+        return parseCliImport(argv);
     if (command === 'recover-stale-lock') {
         // recover-stale-lock：独立显式 recovery，不接受 destructive 执行参数（只能 --data-dir 定位锁目录）。
         // 只需 parseCliDataDir —— 它自己就会拒绝任何未知 flag。此前这里还有一道「逐 token 只许 --data-dir」的
@@ -190,7 +252,7 @@ export function parseCli(argv) {
     for (let i = 0; i < rest.length; i += 1) {
         const flag = rest[i];
         if (flag === '--help' || flag === '-h') {
-            return { ok: true, options: { ...options, command: 'help' } };
+            return { ok: true, options: { ...options, command: 'help', helpTopic: command } };
         }
         // 位置参数：仅 verify 接受（文件名或路径），其余子命令沿用「未知参数」拒绝
         if (!flag.startsWith('-')) {
@@ -206,6 +268,9 @@ export function parseCli(argv) {
         if (command !== 'verify' && VERIFY_ONLY_FLAGS.has(flag)) {
             return { ok: false, error: `${command} 子命令不支持参数 / flag not allowed here: ${flag}` };
         }
+        if (IMPORT_ONLY_FLAGS.has(flag)) {
+            return { ok: false, error: `${command} 子命令不支持参数 / flag not allowed here: ${flag}` };
+        }
         if (command !== 'backup' && BACKUP_ONLY_FLAGS.has(flag)) {
             return { ok: false, error: `${command} 子命令不支持参数 / flag not allowed here: ${flag}` };
         }
@@ -443,78 +508,20 @@ function resolveCliVersion() {
 /** 进程内缓存（每次 CLI 运行只读一次 package.json） */
 const CLI_EXPORTER_VERSION = resolveCliVersion();
 export function printUsage(io = defaultIo) {
-    io.log([
-        'dsh-config-manager（简写 dcm）— DSH Config Manager CLI（离线救急 / snapshot restore + 一键重装）',
-        '',
-        '用法 / Usage:',
-        '  dsh-config-manager snapshots [--data-dir <dir>]',
-        '      列出快照 / list snapshots',
-        '  dsh-config-manager restore [--id <uuid>] [--dry-run] [--data-dir <dir>]',
-        '                            [--data-root <dir>] [--profile <name>] [--settings <path>]',
-        '      恢复到导入前状态 / restore to pre-import state（--dry-run 只打印计划）',
-        '  dsh-config-manager reinstall [--version <v>] [--yes] [--list] [--wipe-config] [--dry-run]',
-        '                            [--data-root <dir>]',
-        '      一键重装 DSH 程序（交互多选 + 二次确认），DSH 损坏时救急 / reinstall DSH',
-        '  dsh-config-manager recover-stale-lock [--data-dir <dir>]',
-        '      回收残留的环境锁（上次进程被强制结束留下的死锁）',
-        '      / recover a stale environment lock left by a killed process',
-        '      仅当持有者已确证死亡才回收；活锁一律拒绝。GUI 操作报「操作暂时无法执行」',
-        '      且重试无效时使用（另有 GUI「事故恢复」入口）。',
-        '      Refuses unless the owner is proven dead; never touches a live lock.',
-        '  dsh-config-manager verify [--id <file|path>] [--json] [--data-dir <dir>]',
-        '      离线只读自检备份 ZIP（结构 + integrity/checksums 完整性；不改一个字节）',
-        '      / read-only integrity check of backup ZIPs（零写入）',
-        '      无参校验导出目录下全部 *.zip；也可用位置参数指定单个文件或路径。',
-        '      退出码：全部 OK → 0，任一非 OK → 1（便于 CI / 定时任务断言）。',
-        '      Exit code: 0 only when every checked backup is OK.',
-        '  dsh-config-manager backup [--sections <a,b,c>] [--out <path>] [--dry-run]',
-        '                            [--data-dir <dir>]',
-        '      离线文件级备份（导出目录内生成与 GUI 同结构的 ZIP，落盘后自动自检）',
-        '      / offline file-level backup（dropped ZIP is self-verified）',
-        '      只打包离线可直读的分区；凭据类文件（凭据文件名 / .env / *.pem）永不进入备份。',
-        '  dsh-config-manager web [--port <n>] [--no-open] [--home <dir>] [--data-root <dir>]',
-        '                        [--idle-timeout <分钟>]',
-        '      启动离线只读救急台（本机网页）：实例心跳 / SAFE MODE / 残留锁 / 快照 / 备份产物',
-        '      （可一键自检）/ 磁盘占用 / 会话体检，全部只读 / offline read-only rescue console',
-        '      只绑 127.0.0.1，端口缺省 0（内核分配）；启动后打印带一次性 token 的 URL 并打开浏览器。',
-        '      Ctrl+C 或空闲超时即退出；等价简写：dcm web',
-        '  dsh-config-manager sessions list   [--home <dir>] [--json]        # 只读：列出本机会话',
-        '  dsh-config-manager sessions doctor [--home <dir>] [--json]        # 只读：体检并给处置建议',
-        '  dsh-config-manager sessions repair [--home <dir>] [--apply] [--keep <dir>] [--map old=new]...',
-        '      离线修复会话日志布局（DSH 已起不来时的唯一通道）/ offline session layout repair',
-        '      按每条会话 header 的 cwd 把目录归位到 projectKeyOf(cwd)；缺省只报告，--fix 才落盘。',
-        '      --map 用于跨机恢复：old=new 前缀映射会先改写会话日志第 1 帧 header（其余帧逐字节保留）。',
-        '      重复 id（同一会话出现在多个 projectKey 目录）只在 --keep <目录> 点名保留谁时，',
-        '      才把其它副本移进 sessions/.cm-repair-quarantine-<时间戳>/（只搬不删）。',
-        '      Exit code: dry-run 恒 0；--fix 有失败/冲突/回滚 → 1。',
-        '  dsh-config-manager help',
-        '      显示全部命令与说明 / show all commands',
-        '',
-        '选项 / Options:',
-        '  --data-dir <dir>   快照数据目录（缺省 $DSH_HOME/dsh-config-manager/snapshots；verify/backup',
-        '                     下为导出目录；recover-stale-lock 用它定位环境锁所在的数据目录）',
-        '  --data-root <dir>  插件数据根 dataDir（宿主 config.dataDir；SAFE MODE / 环境锁 / journal 所在根）',
-        '                     缺省 $DSH_HOME/dsh-config-manager。插件配置了自定义 dataDir 时，破坏性命令',
-        '                     （restore / reinstall）必须显式传它，否则安全门只按候选位置保守检查。',
-        '  --id <uuid>        目标快照 id（缺省取最近一个非 rolled-back 快照）',
-        '  --dry-run          只打印计划，不执行 / print plan only',
-        '  --profile <name>   管理的 DSH profile（缺省 web）',
-        '  --settings <path>  覆盖 settings 文件路径',
-        '  --version <v>      要安装的 DSH 版本（缺省 latest）',
-        '  --yes              非交互：全选并跳过二次确认 / non-interactive',
-        '  --list             只列出 reinstall 可选清理项 / list selectable items only',
-        '  --wipe-config      一并勾选数据类（settings/plugins/data）/ also wipe ~/.dsh data',
-        '  --json             verify 输出机器可读 JSON / machine-readable output',
-        '  --sections <list>  backup 分区白名单（逗号分隔；缺省 ' + DEFAULT_BACKUP_SECTIONS.join(',') + '）',
-        '  --out <path>       backup 输出 ZIP 路径（缺省自动命名，绝不覆盖既有文件）',
-        '  --home <dir>       sessions repair / web 的 DSH home（缺省 $DSH_HOME，即 ~/.dsh）',
-        '  --port <n>         web：监听端口（缺省 0 = 内核随机分配；恒只绑 127.0.0.1）',
-        '  --no-open          web：启动后不自动打开浏览器 / do not open the browser',
-        '  --idle-timeout <m> web：空闲多少分钟自动退出（0 = 不自动退出；缺省 30）',
-        '  --fix / --apply    sessions repair 真的落盘（缺省只打印计划；写前会检查 DSH 是否在跑）',
-        '  --keep <dir>       重复 id 时保留哪一份会话目录（其余移入隔离目录，不删除）',
-        '  --map old=new      路径前缀映射（可重复；命中即改写会话首帧 cwd）',
-    ].join('\n'));
+    io.log(renderOverview(CLI_EXPORTER_VERSION).join('\n'));
+}
+/**
+ * 打印单命令详情页（`dcm <命令> --help` / `dcm help <命令>`）。
+ *
+ * 返回 false 表示不认识该命令名（调用方决定报错文案）；成功时已写完输出。
+ * 文案与退出码都在 ./help.ts，本函数只做「渲染 → 输出」。
+ */
+export function printCommandUsage(name, io = defaultIo) {
+    const lines = renderCommandHelp(name, CLI_EXPORTER_VERSION);
+    if (lines === null)
+        return false;
+    io.log(lines.join('\n'));
+    return true;
 }
 function printSnapshots(metas, io) {
     if (metas.length === 0) {
@@ -790,7 +797,17 @@ export async function runCli(argv, io = defaultIo, env = process.env, deps = {})
     }
     const { options } = parsed;
     if (options.command === 'help') {
-        printUsage(io);
+        const topic = options.helpTopic;
+        if (topic === undefined) {
+            printUsage(io);
+            return 0;
+        }
+        // 认不出的主题不静默回落：先说出来，再给速查页（否则用户以为拼错的名字是有效的）
+        if (!printCommandUsage(topic, io)) {
+            io.error('未知命令 / unknown command: ' + topic);
+            printUsage(io);
+            return 1;
+        }
         return 0;
     }
     if (options.command === 'reinstall') {
@@ -807,6 +824,17 @@ export async function runCli(argv, io = defaultIo, env = process.env, deps = {})
     if (options.command === 'backup') {
         return runBackup(options, io, env);
     }
+    // import：把外部 agent 配置翻译成标准 bundle（dry-run 零写入；只可能写导出目录，不碰 $DSH_HOME 配置）
+    if (options.command === 'import') {
+        return runImportSource({
+            from: options.from ?? '',
+            dryRun: options.dryRun,
+            exportsDir: resolveExportsDir(options.dataDir, env),
+            exporterVersion: CLI_EXPORTER_VERSION,
+            ...(options.out !== undefined ? { out: options.out } : {}),
+            ...(options.cwd !== undefined ? { cwd: options.cwd } : {}),
+        }, io, env);
+    }
     if (options.command === 'sessions') {
         // 离线修复：不碰 $DSH_HOME 的其它部分、不需要环境锁（只读写会话目录，且默认 dry-run）
         const home = options.home ?? resolveDshHome(env);

package/lib/cli/web/client-script.d.ts

@@ -1,4 +1,12 @@
 /** 客户端脚本原文（page.ts 内联进 <script>；不得含字面量 </script 或 <!--）。 */
 export declare const CONSOLE_SCRIPT = "(function () {\n  'use strict';\n\n  // ---- \u4E09\u6001\u4E3B\u9898\uFF1A\u81EA\u52A8 / \u6D45\u8272 / \u6DF1\u8272 ----\n  // \u4E3A\u4EC0\u4E48\u653E\u5728\u6700\u524D\u9762\uFF1A\u5B83\u8981\u5728**\u9996\u5E27\u4E4B\u524D**\u628A data-theme \u843D\u5230 <html> \u4E0A\uFF0C\u5426\u5219\u5F3A\u5236\u4E3B\u9898\u4F1A\u5148\u95EA\u4E00\u4E0B\u3002\n  // \u4E3A\u4EC0\u4E48\u7528 cookie \u800C\u4E0D\u662F storage\uFF1Acookie \u4E0D\u533A\u5206\u7AEF\u53E3\uFF0C\u800C\u6551\u6025\u53F0\u6BCF\u6B21\u542F\u52A8\u6362\u968F\u673A\u7AEF\u53E3 \u2014\u2014 \u53EA\u6709 cookie \u80FD\u8DE8\u6B21\u8BB0\u4F4F\u3002\n  var THEME_KEY = 'dcm-theme';\n  var THEME_MODES = ['auto', 'light', 'dark'];\n  function readTheme() {\n    var parts = ('; ' + document.cookie).split('; ' + THEME_KEY + '=');\n    if (parts.length < 2) return 'auto';\n    var value = String(parts[1]).split(';')[0];\n    return THEME_MODES.indexOf(value) === -1 ? 'auto' : value;\n  }\n  function applyTheme(mode, persist) {\n    var next = THEME_MODES.indexOf(mode) === -1 ? 'auto' : mode;\n    document.documentElement.setAttribute('data-theme', next);\n    var list = document.querySelectorAll('[data-dcm-theme]');\n    for (var i = 0; i < list.length; i++) {\n      list[i].setAttribute('aria-pressed', list[i].getAttribute('data-dcm-theme') === next ? 'true' : 'false');\n    }\n    if (persist === true) {\n      // \u975E\u654F\u611F\u504F\u597D\uFF08\u4E0D\u542B\u4EFB\u4F55\u5BC6\u94A5/\u8DEF\u5F84\uFF09\uFF1Bcookie \u88AB\u7981\u7528\u65F6\u9759\u9ED8\u964D\u7EA7\u4E3A\u300C\u672C\u6B21\u6709\u6548\u300D\n      document.cookie = THEME_KEY + '=' + next + '; path=/; max-age=31536000; SameSite=Lax';\n    }\n  }\n  // \u6709\u811A\u672C = \u5F00\u5173\u53EF\u7528\uFF1B\u65E0\u811A\u672C\u65F6\u5B83\u88AB CSS \u9690\u85CF\uFF0C\u9875\u9762\u56DE\u843D\u5230 prefers-color-scheme \u7684\u81EA\u52A8\u6A21\u5F0F\n  document.documentElement.setAttribute('data-dcm-js', '1');\n  applyTheme(readTheme(), false);\n  document.addEventListener('click', function (event) {\n    var node = event.target;\n    while (node !== null && node !== document) {\n      if (typeof node.hasAttribute === 'function' && node.hasAttribute('data-dcm-theme')) {\n        applyTheme(String(node.getAttribute('data-dcm-theme')), true);\n        return;\n      }\n      node = node.parentNode;\n    }\n  });\n  // \u79BB\u7EBF\u6551\u6025\u53F0\u7684**\u552F\u4E00**\u5BA2\u6237\u7AEF\u811A\u672C\uFF1A\u53EA\u505A\u4E24\u4EF6\u4E8B \u2014\u2014 \u2460 \u4F1A\u8BDD\u5185\u72B6\u6001\u6062\u590D\uFF08sessionStorage\uFF0Cdcm: \u524D\u7F00\uFF09\n  // \u2461 \u628A\u786E\u8BA4\u8868\u5355\u4ECE details \u5347\u7EA7\u6210\u539F\u751F dialog \u5143\u7D20\u3002\u7981\u7528 JS \u65F6\u4E24\u8005\u90FD\u4E0D\u53C2\u4E0E\uFF0C\u9875\u9762\u56DE\u843D\u5230\u7EAF HTML\u3002\n  var PREFIX = 'dcm:';\n  // \u663E\u5F0F\u9ED1\u540D\u5355\uFF08\u4E0D\u662F\u300C\u9760\u6CA1\u5199\u8FDB\u53BB\u300D\uFF09\uFF1A\u8FD9\u4E9B type \u4E00\u5F8B\u4E0D\u843D storage\n  var BLOCKED_TYPES = { password: 1, hidden: 1, file: 1, submit: 1, button: 1, reset: 1, image: 1 };\n  // \u663E\u5F0F\u9ED1\u540D\u5355\uFF08\u6309\u5B57\u6BB5\u540D\uFF09\uFF1Atoken / \u5BC6\u7801 / \u673A\u5BC6 / \u51ED\u636E / \u91CD\u88C5\u786E\u8BA4\u7801 / cookie \u4E00\u5F8B\u4E0D\u843D storage\n  var BLOCKED_NAMES = /(token|password|passwd|secret|credential|phrase|cookie|apikey|authorization)/i;\n  var store = null;\n  try {\n    store = window.sessionStorage;\n    store.setItem(PREFIX + 'probe', '1');\n    store.removeItem(PREFIX + 'probe');\n  } catch (error) {\n    store = null;\n  }\n  function readJson(key) {\n    if (store === null) return null;\n    try {\n      var raw = store.getItem(key);\n      return raw === null ? null : JSON.parse(raw);\n    } catch (error) {\n      return null;\n    }\n  }\n  function writeJson(key, value) {\n    if (store === null) return;\n    try {\n      store.setItem(key, JSON.stringify(value));\n    } catch (error) {\n      // \u914D\u989D\u5DF2\u6EE1 / \u9690\u79C1\u6A21\u5F0F\uFF1A\u9759\u9ED8\u964D\u7EA7\uFF0C\u9875\u9762\u7167\u5E38\u53EF\u7528\n    }\n  }\n  function pageKey() {\n    return location.pathname + location.search;\n  }\n  function persistable(el) {\n    if (!el || typeof el.name !== 'string' || el.name === '') return false;\n    var type = (el.type || '').toLowerCase();\n    if (BLOCKED_TYPES[type] === 1) return false;\n    if (BLOCKED_NAMES.test(el.name)) return false;\n    if (typeof el.id === 'string' && el.id !== '' && BLOCKED_NAMES.test(el.id)) return false;\n    return true;\n  }\n  function fieldKey(el) {\n    var scope = el.form ? String(el.form.getAttribute('action') || '') : '';\n    return PREFIX + 'field:' + pageKey() + ':' + scope + ':' + el.name + (el.type === 'radio' ? '=' + String(el.value) : '');\n  }\n  function restoreFields() {\n    var list = document.querySelectorAll('input, select, textarea');\n    for (var i = 0; i < list.length; i++) {\n      var el = list[i];\n      if (!persistable(el)) continue;\n      var saved = readJson(fieldKey(el));\n      if (saved === null) continue;\n      if (el.type === 'checkbox' || el.type === 'radio') {\n        if (typeof saved.checked === 'boolean') el.checked = saved.checked;\n      } else if (typeof saved.value === 'string') {\n        el.value = saved.value;\n      }\n    }\n  }\n  function onField(event) {\n    var el = event.target;\n    if (!persistable(el)) return;\n    if (el.type === 'checkbox' || el.type === 'radio') writeJson(fieldKey(el), { checked: el.checked === true });\n    else writeJson(fieldKey(el), { value: String(el.value) });\n  }\n  document.addEventListener('change', onField, true);\n  document.addEventListener('input', onField, true);\n  function detailsState() {\n    var list = document.querySelectorAll('details[data-dcm-persist]');\n    for (var i = 0; i < list.length; i++) {\n      var details = list[i];\n      var id = details.getAttribute('data-dcm-persist') || String(i);\n      var saved = readJson(PREFIX + 'open:' + pageKey() + ':' + id);\n      if (typeof saved === 'boolean') details.open = saved;\n    }\n  }\n  document.addEventListener('toggle', function (event) {\n    var details = event.target;\n    if (!details || details.tagName !== 'DETAILS') return;\n    var id = details.getAttribute('data-dcm-persist');\n    if (id === null) return;\n    writeJson(PREFIX + 'open:' + pageKey() + ':' + id, details.open === true);\n  }, true);\n  function scrollKey() {\n    return PREFIX + 'scroll:' + pageKey();\n  }\n  var navType = '';\n  try {\n    var entries = performance.getEntriesByType('navigation');\n    if (entries.length > 0) navType = String(entries[0].type || '');\n  } catch (error) {\n    navType = '';\n  }\n  function currentScroll() {\n    return window.pageYOffset || document.documentElement.scrollTop || 0;\n  }\n  var scrollTimer = null;\n  function saveScroll() {\n    writeJson(scrollKey(), { y: Math.round(currentScroll()), t: Date.now() });\n  }\n  window.addEventListener('scroll', function () {\n    if (scrollTimer !== null) return;\n    scrollTimer = window.setTimeout(function () {\n      scrollTimer = null;\n      saveScroll();\n    }, 150);\n  }, { passive: true });\n  window.addEventListener('pagehide', saveScroll);\n  document.addEventListener('visibilitychange', function () {\n    if (document.visibilityState === 'hidden') saveScroll();\n  });\n  function restoreScroll() {\n    var saved = readJson(scrollKey());\n    if (saved === null || typeof saved.y !== 'number' || saved.y <= 0) return;\n    window.scrollTo(0, saved.y);\n  }\n  // \u53EA\u5728\u300C\u5237\u65B0\u300D\u4E0E\u300C\u540E\u9000/\u524D\u8FDB\u300D\u6062\u590D\uFF1A\u666E\u901A\u65B0\u5BFC\u822A\uFF08type=navigate\uFF09\u4ECE\u9876\u90E8\u5F00\u59CB\n  if (navType === '' || navType === 'reload' || navType === 'back_forward') {\n    window.requestAnimationFrame(function () {\n      window.requestAnimationFrame(restoreScroll);\n    });\n  }\n  function enhanceOne(details) {\n    var form = details.querySelector('form');\n    if (form === null) return;\n    var summary = details.querySelector('summary');\n    var dialog = document.createElement('dialog');\n    dialog.className = 'dcmDialog';\n    var body = details.querySelector('.confirmBody');\n    if (body !== null) {\n      while (body.firstChild !== null) dialog.appendChild(body.firstChild);\n    } else {\n      dialog.appendChild(form);\n    }\n    var footer = document.createElement('div');\n    footer.className = 'dialogFooter';\n    var cancel = document.createElement('button');\n    cancel.type = 'button';\n    cancel.className = 'btnPlain';\n    cancel.textContent = '\u53D6\u6D88';\n    cancel.addEventListener('click', function () { dialog.close(); });\n    footer.appendChild(cancel);\n    dialog.appendChild(footer);\n    dialog.addEventListener('click', function (event) {\n      if (event.target === dialog) dialog.close();\n    });\n    document.body.appendChild(dialog);\n    var trigger = document.createElement('button');\n    trigger.type = 'button';\n    trigger.setAttribute('data-dcm-trigger', '');\n    trigger.className = summary === null ? 'btnPrimary' : summary.className;\n    trigger.textContent = summary === null ? '\u786E\u8BA4\u6267\u884C' : String(summary.textContent || '\u786E\u8BA4\u6267\u884C');\n    trigger.addEventListener('click', function () {\n      if (dialog.open) dialog.close();\n      else dialog.showModal();\n    });\n    if (details.parentNode !== null) details.parentNode.replaceChild(trigger, details);\n  }\n  function enhanceDialogs() {\n    if (typeof document.createElement('dialog').showModal !== 'function') return;\n    var list = document.querySelectorAll('details[data-dcm-confirm]');\n    for (var i = 0; i < list.length; i++) enhanceOne(list[i]);\n  }\n  document.addEventListener('click', function (event) {\n    var node = event.target;\n    while (node !== null && node !== document) {\n      if (typeof node.hasAttribute === 'function' && node.hasAttribute('data-dcm-back')) {\n        if (window.history.length > 1) {\n          event.preventDefault();\n          window.history.back();\n        }\n        return;\n      }\n      node = node.parentNode;\n    }\n  });\n  function boot() {\n    applyTheme(readTheme(), false); // DOM \u5230\u4F4D\u540E\u628A\u5F00\u5173\u7684\u9009\u4E2D\u6001\u5BF9\u9F50\uFF08\u9996\u5E27\u90A3\u6761\u5DF2\u7ECF\u8BBE\u8FC7 data-theme\uFF09\n    detailsState();\n    enhanceDialogs();\n    restoreFields();\n  }\n  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot);\n  else boot();\n})();";
+/**
+ * 从本文件的**源码文本**里抽出 CONSOLE_SCRIPT 模板串（测试用；**唯一实现**）。
+ *
+ * 为什么要归一化换行（cli-F5）：Windows 上 `core.autocrlf=true` 的检出会让闭引号后面是
+ * `\r\n`，只认 `\n` 的正则失配 → 测试在自己的检出上假红（R3-04）。抽取逻辑收在这里，
+ * web.test.ts 与 script-anchor.test.ts 共用，避免第二份口径再次漂移。
+ */
+export declare function extractConsoleScriptSource(source: string): string | undefined;
 /** 该脚本的 CSP hash-source（含引号，可直接拼进 script-src）。 */
 export declare function consoleScriptCspHash(): string;

package/lib/cli/web/client-script.js

@@ -237,6 +237,17 @@ export const CONSOLE_SCRIPT = `(function () {
   if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', boot);
   else boot();
 })();`;
+/**
+ * 从本文件的**源码文本**里抽出 CONSOLE_SCRIPT 模板串（测试用；**唯一实现**）。
+ *
+ * 为什么要归一化换行（cli-F5）：Windows 上 `core.autocrlf=true` 的检出会让闭引号后面是
+ * `\r\n`，只认 `\n` 的正则失配 → 测试在自己的检出上假红（R3-04）。抽取逻辑收在这里，
+ * web.test.ts 与 script-anchor.test.ts 共用，避免第二份口径再次漂移。
+ */
+export function extractConsoleScriptSource(source) {
+    const lf = source.split('\r\n').join('\n');
+    return /export const CONSOLE_SCRIPT = `([\s\S]*?)`\n/.exec(lf)?.[1];
+}
 const SCRIPT_HASH = "'sha256-" + createHash('sha256').update(CONSOLE_SCRIPT, 'utf8').digest('base64') + "'";
 /** 该脚本的 CSP hash-source（含引号，可直接拼进 script-src）。 */
 export function consoleScriptCspHash() {

package/lib/cli/web/http.d.ts

@@ -13,6 +13,11 @@
  * 全部 403**（实测 Chrome 154：no-referrer → null；same-origin/strict-origin/默认策略 → 正常）。
  * same-origin 的强度并不降低：跨源请求仍然一个字节的 Referer 都不带（第三方零泄漏），
  * 而带一次性 token 的启动地址走 server.ts 的 302，那一步单独保持 `no-referrer`。
+ *
+ * `frame-ancestors 'none'` **必须显式写**（cli-F3）：它**不被** `default-src` 覆盖 —— 只写
+ * `default-src 'none'` 时页面仍可被 iframe。SameSite=Strict 的判据是 **site**（忽略端口），
+ * 本机另一个 127.0.0.1:<其它端口> 的页面同 site，iframe 里 cookie 照送 → 可点劫写动作。
+ * 一并给 `X-Frame-Options: DENY`（老浏览器）。
  */
 import type { ServerResponse } from 'node:http';
 /** HTML 响应（content-type + no-store + referrer-policy + CSP 只在这一处维护）。 */

package/lib/cli/web/http.js

@@ -5,8 +5,9 @@ export function writeHtml(res, status, html) {
         'content-type': 'text/html; charset=utf-8',
         'referrer-policy': 'same-origin',
         'cache-control': 'no-store',
+        'x-frame-options': 'DENY',
         'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; img-src data:; "
-            + "script-src " + consoleScriptCspHash() + "; base-uri 'none'; form-action 'self'",
+            + "script-src " + consoleScriptCspHash() + "; base-uri 'none'; form-action 'self'; frame-ancestors 'none'",
     });
     res.end(html);
 }