dsh-config-manager 0.1.86 → 0.2.0

package/lib/core/path-browse.js

@@ -0,0 +1,134 @@
+/**
+ * 本机目录列举（宿主半）—— 「路径映射 → 选择本机路径」弹窗的唯一数据源。
+ *
+ * 为什么要有它
+ * ------------
+ * 导入向导的路径映射要求用户为一堆**绝对路径**指定本机新位置，而此前只能凭记忆手打
+ * （浏览器拿不到真实路径：File System Access API 只给 handle，`<input type="file">` 只给文件名）。
+ * 于是「路径选不对 = 导不进」全落在用户的打字准确性上。这里把「列目录」做成宿主能力，
+ * 浏览器只负责画界面。
+ *
+ * 边界
+ * ----
+ * - **只读**：只 readdir/stat，绝不创建、改写、删除任何东西；
+ * - **不产出文案**：`error` 是枚举码（not-found / denied / failed / not-absolute），
+ *   用户可见句子由客户端按字典解析（i18n 硬规则：引擎不写中文）；
+ * - 有界：单次列举最多 {@link BROWSE_ENTRY_LIMIT} 条并回报 `truncated`，盘符探测逐根带硬超时
+ *   （离线光驱/断开的网络盘 stat 会挂住，路由不许被一个 panic 盘符拖死）。
+ */
+import { readdir, stat } from 'node:fs/promises';
+import { dirname, join, parse } from 'node:path';
+import { homedir } from 'node:os';
+/** 单次列举上限：够翻一个源码目录，又不至于把响应体撑成几 MB。 */
+export const BROWSE_ENTRY_LIMIT = 500;
+/** 盘符/根探测的单项硬超时（ms）：断开的网络盘 stat 会长时间不返回。 */
+export const ROOT_PROBE_TIMEOUT_MS = 400;
+/** 带硬超时的 Promise（只为本模块的盘符探测服务；超时后原 promise 的迟到结果被丢弃）。 */
+function withDeadline(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { reject(new Error('timeout')); }, ms);
+        promise.then((value) => { clearTimeout(timer); resolve(value); }, (error) => { clearTimeout(timer); reject(error); });
+    });
+}
+/** 一个路径是不是「根」（Windows 盘符根 / POSIX 的 `/`）。 */
+function isRoot(target) {
+    return parse(target).root === target;
+}
+/**
+ * 本机根列表：Windows 上是**探测得到的**盘符根（不硬编码 C:），其余平台是 `/`。
+ * 探测逐根 400ms 超时；全部失败时至少给出 `parse(process.cwd()).root`，界面不至于空成白板。
+ */
+export async function listRoots() {
+    if (process.platform !== 'win32') {
+        return [{ name: '/', path: '/', kind: 'dir' }];
+    }
+    const letters = 'CDEFGHIJKLMNOPQRSTUVWXYZAB'.split('');
+    const probed = await Promise.all(letters.map(async (letter) => {
+        const root = `${letter}:\\`;
+        try {
+            const info = await withDeadline(stat(root), ROOT_PROBE_TIMEOUT_MS);
+            return info.isDirectory() ? root : null;
+        }
+        catch {
+            return null;
+        }
+    }));
+    const roots = probed.filter((root) => root !== null);
+    const fallback = parse(process.cwd()).root;
+    const ordered = roots.length > 0 ? roots : (fallback === '' ? [] : [fallback]);
+    return ordered.map((root) => ({ name: root, path: root, kind: 'dir' }));
+}
+/** 文件系统错误 → 原因码（只有 ENOENT 才叫「不存在」）。 */
+function errorCodeOf(error) {
+    const code = error?.code;
+    if (code === 'ENOENT' || code === 'ENOTDIR')
+        return 'not-found';
+    if (code === 'EACCES' || code === 'EPERM')
+        return 'denied';
+    return 'failed';
+}
+/** 名字排序：目录在前、同类按名字字典序（不依赖 locale，测试可复现）。 */
+function compareEntries(a, b) {
+    if (a.kind !== b.kind)
+        return a.kind === 'dir' ? -1 : 1;
+    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+/**
+ * 列出一个目录（缺省 = 根列表）。
+ *
+ * `target` 缺省或空串 = 根列表；凡不是绝对路径一律 `not-absolute`（不猜基准目录 —— 猜错就列出别人的东西）。
+ * @param options.limit 覆盖 {@link BROWSE_ENTRY_LIMIT}。
+ */
+export async function browseDirectory(target, options) {
+    const limit = Math.max(1, Math.trunc(options?.limit ?? BROWSE_ENTRY_LIMIT));
+    const home = homedir();
+    const wanted = (target ?? '').trim();
+    if (wanted === '') {
+        const roots = await listRoots();
+        return { path: '', parent: null, home, entries: roots.slice(0, limit), truncated: roots.length > limit, error: null };
+    }
+    if (!parse(wanted).root) {
+        return { path: wanted, parent: null, home, entries: [], truncated: false, error: 'not-absolute' };
+    }
+    const current = parse(wanted).root === wanted ? wanted : wanted.replace(/[\\/]+$/, '');
+    let dirents;
+    try {
+        dirents = await readdir(current, { withFileTypes: true });
+    }
+    catch (error) {
+        return { path: current, parent: isRoot(current) ? null : dirname(current), home, entries: [], truncated: false, error: errorCodeOf(error) };
+    }
+    const entries = [];
+    for (const dirent of dirents) {
+        const entryPath = join(current, dirent.name);
+        if (dirent.isDirectory()) {
+            entries.push({ name: dirent.name, path: entryPath, kind: 'dir' });
+            continue;
+        }
+        if (dirent.isFile()) {
+            entries.push({ name: dirent.name, path: entryPath, kind: 'file' });
+            continue;
+        }
+        // 符号链接 / junction / 其它特殊项：跟随一次（读不到就整条丢掉，绝不猜类型）
+        try {
+            const info = await stat(entryPath);
+            if (info.isDirectory())
+                entries.push({ name: dirent.name, path: entryPath, kind: 'dir' });
+            else if (info.isFile())
+                entries.push({ name: dirent.name, path: entryPath, kind: 'file' });
+        }
+        catch {
+            // 断链：不展示（点了也进不去）
+        }
+    }
+    entries.sort(compareEntries);
+    return {
+        path: current,
+        parent: isRoot(current) ? null : dirname(current),
+        home,
+        entries: entries.slice(0, limit),
+        truncated: entries.length > limit,
+        error: null,
+    };
+}
+//# sourceMappingURL=path-browse.js.map

package/lib/foreign/claude-sessions.d.ts

@@ -37,7 +37,7 @@
  *  ③ **sessionId 不一致**：`input.recordSessionId` 存在且 ≠ `input.id` → 非致命发现
  *     `session-id-mismatch`（会话 id 仍以文件名 stem 为准，见 `TranscodeResult.findings`）。
  *  ④ **推理块**（Claude Code 的 `thinking` / `redacted_thinking`）：共享 IR 没有 reasoning
- *     承载位（docs/spec/known-gaps.md F-01）→ 计报 `thinking`，**绝不伪装成正文**；非 Claude 原生的
+ *     承载位（docs/maintenance/known-gaps.md F-01）→ 计报 `thinking`，**绝不伪装成正文**；非 Claude 原生的
  *     `{type:'reasoning',text:…}` 刻意保持既有口径（理由与切换方式见 `REASONING_BLOCK_TYPES`）。
  */
 import type { Stats } from 'node:fs';

package/lib/foreign/claude-sessions.js

@@ -28,7 +28,7 @@ function usageField(usage, key) {
  * 沿「对象带 text 才算文本」的兜底把它变成一个**空文本块** —— 内容静默丢失，且那个空块还会多插入
  * 一个换行。本仓其余 20+ 来源一律「推理不伪装成正文、只计数」（read-crush / read-opencode /
  * read-qwen / read-pi / read-openclaw …），这里对齐同一口径；共享 IR 无 reasoning 承载位这件事
- * 记在 docs/spec/known-gaps.md 的 F-01。
+ * 记在 docs/maintenance/known-gaps.md 的 F-01。
  *
  * **为什么不把 `{type:'reasoning', text:'…'}` 一并纳入**（如实记明，别当成漏掉）：
  *  ① Claude Code 不写这种块（它是别的导出器的归一命名，各来源自己的解析器已各自计报）；

package/lib/index.d.ts

@@ -77,7 +77,7 @@ export declare const name = "config-manager";
 /** Services required before the engine can mount (present in every profile). */
 export declare const inject: string[];
 /** Plugin version, kept in sync with package.json ("version"). */
-export declare const PLUGIN_VERSION = "0.1.86";
+export declare const PLUGIN_VERSION = "0.2.0";
 /**
  * Star 引导弹窗指向的 GitHub 仓库（用户引导点 Star 的目标）。
  * 与 package.json 的 repository 字段保持一致；界面不可改（硬编码，参照
@@ -130,7 +130,7 @@ export interface Config {
 /**
  * 本文件保留的 7 条路由的路径（被源码级守卫按文件窗口钉住，见下方 routesList 注释）。
  *
- * 其余 75 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
+ * 其余 76 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
  * 新增一条 API 只需那一条声明，不再有「常量表 + 路由对象」两处要同步。
  */
 export declare const API: {

package/lib/index.js

@@ -136,7 +136,7 @@ export const name = 'config-manager';
 /** Services required before the engine can mount (present in every profile). */
 export const inject = ['settings', 'credentials'];
 /** Plugin version, kept in sync with package.json ("version"). */
-export const PLUGIN_VERSION = '0.1.86';
+export const PLUGIN_VERSION = '0.2.0';
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager';
 /**
@@ -158,7 +158,7 @@ export const DEFAULT_GITHUB_CLIENT_ID = 'Ov23liq4i7n8UsylGRfb';
 /**
  * 本文件保留的 7 条路由的路径（被源码级守卫按文件窗口钉住，见下方 routesList 注释）。
  *
- * 其余 75 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
+ * 其余 76 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
  * 新增一条 API 只需那一条声明，不再有「常量表 + 路由对象」两处要同步。
  */
 export const API = {
@@ -3027,7 +3027,7 @@ function makeRoutes(deps) {
     /**
      * 路由表：本文件只保留被源码级守卫按**文件窗口**钉住的 7 条（host-entry 审计 F-04 记录的
      * tests/host/**、src/core/model-tools.test.ts、src/core/phase1-wiring.test.ts 的窗口断言）。
-     * 其余 75 条已按域拆到 src/routes/*.ts，由 buildRoutes 组装。
+     * 其余 76 条已按域拆到 src/routes/*.ts，由 buildRoutes 组装。
      * 注册顺序不影响匹配：命名路由必须互不相同（webServer 契约）。
      */
     const routeEnv = makeRouteEnv();

package/lib/market/security.js

@@ -102,7 +102,7 @@ export function validateMarketItem(itemId, manifestRaw, zipBytes) {
         if (!enabled)
             continue;
         // 市场条目禁止分区（BANNED_MARKET_SECTIONS：sessions 历史会话 / pluginFiles 任意文件 / self 本地环境）：
-        // 与 secrets 同级硬约束（产品决策 2026-08-19，guide docs/design/2026-08-19-market-repo-setup-guide.md）。
+        // 与 secrets 同级硬约束（产品决策 2026-08-19，guide docs/spec/market-index-v1.md）。
         if (BANNED_MARKET_SECTIONS.includes(sectionId)) {
             return { status: 'invalid', errors: [marketMsg('market.security.bannedSection', { section: sectionId })], warnings, manifest, internalManifest, sections: [], checksumsOk: true };
         }

package/lib/market/types.d.ts

@@ -26,7 +26,7 @@ export type MarketPublishMode = 'migrate' | 'share';
  */
 export declare const MAX_MARKET_ZIP_BYTES: number;
 /**
- * 市场条目禁止携带的分区（产品决策 2026-08-19，guide docs/design/2026-08-19-market-repo-setup-guide.md）：
+ * 市场条目禁止携带的分区（产品决策 2026-08-19，guide docs/spec/market-index-v1.md）：
  *  - sessions：历史会话，含个人交互记录/上下文；
  *  - pluginFiles：任意文件直通（目录放啥带啥），无内容过滤，最易泄漏 token/密钥文件；
  *  - self：本地环境专属（sync 通道 URL / WebDAV 地址 / 市场配置 / UI 偏好），无分享价值且泄漏环境信息。

package/lib/market/types.js

@@ -8,7 +8,7 @@ export const MARKET_ITEM_SCHEMA_VERSION = 1;
  */
 export const MAX_MARKET_ZIP_BYTES = 64 * 1024 * 1024;
 /**
- * 市场条目禁止携带的分区（产品决策 2026-08-19，guide docs/design/2026-08-19-market-repo-setup-guide.md）：
+ * 市场条目禁止携带的分区（产品决策 2026-08-19，guide docs/spec/market-index-v1.md）：
  *  - sessions：历史会话，含个人交互记录/上下文；
  *  - pluginFiles：任意文件直通（目录放啥带啥），无内容过滤，最易泄漏 token/密钥文件；
  *  - self：本地环境专属（sync 通道 URL / WebDAV 地址 / 市场配置 / UI 偏好），无分享价值且泄漏环境信息。

package/lib/routes/index.d.ts

@@ -3,7 +3,7 @@
  *
  * 顺序对匹配无影响：DSH webServer 的契约是「命名路由必须互不相同，注册顺序不影响请求」
  * （见 @deepseek-ai/dsh-host-webserver 的 WebServer 文档）。src/index.ts 保留的 7 条被源码级
- * 守卫按文件窗口钉住，其余 75 条在这里组装。
+ * 守卫按文件窗口钉住，其余 76 条在这里组装（总数 83：含 path-browse）。
  */
 import type { WebRoute } from './kit.ts';
 import type { RoutesEnv } from './context.ts';

package/lib/routes/index.js

@@ -11,6 +11,7 @@ import { meRoutes } from './me.js';
 import { historyRoutes } from './history.js';
 import { recoveryRoutes } from './recovery.js';
 import { sessionExportRoutes } from './session-export.js';
+import { pathBrowseRoutes } from './path-browse.js';
 export function buildRoutes(env) {
     return [
         ...importRoutes(env),
@@ -26,6 +27,7 @@ export function buildRoutes(env) {
         ...historyRoutes(env),
         ...recoveryRoutes(env),
         ...sessionExportRoutes(env),
+        ...pathBrowseRoutes(env),
     ];
 }
 //# sourceMappingURL=index.js.map

package/lib/routes/kit.d.ts

@@ -8,8 +8,8 @@
  * - 「每条路由首行 guard」这条安全不变量此前**只写在注释里**，零测试覆盖；
  * - 3 条 prefix 路由自造围栏（裸 isLoopbackRequest + 自判方法）。
  *
- * 计数口径（三路一致 = 82，勿再照抄旧审计初稿的计数 —— 那是计数口径 overcount）：
- *   路由快照 82 条 ＝ 现行 `endpoint()` 声明 82 条 ＝ 运行期 `buildRoutes()` 75 条 + `src/index.ts` 保留的 7 条。
+ * 计数口径（三路一致 = 83，勿再照抄旧审计初稿的计数 —— 那是计数口径 overcount）：
+ *   路由快照 83 条 ＝ 现行 `endpoint()` 声明 83 条 ＝ 运行期 `buildRoutes()` 76 条 + `src/index.ts` 保留的 7 条。
  * 增删路由后必须同步这段计数、`src/routes/index.ts` 的头注释与 parity 快照清单；`tests/route/route-parity.test.ts`
  * 的「路由计数散文」守卫会拿真实声明数逐条对账（写错即红灯）。
  *

package/lib/routes/path-browse.d.ts

@@ -0,0 +1,3 @@
+import type { WebRoute } from './kit.ts';
+import type { RoutesEnv } from './context.ts';
+export declare function pathBrowseRoutes(_env: RoutesEnv): WebRoute[];

package/lib/routes/path-browse.js

@@ -0,0 +1,63 @@
+/**
+ * 路由组：本机路径浏览（导入向导「路径映射」→ 选择本机路径弹窗的唯一数据源）。
+ *
+ * 为什么需要一条宿主路由：浏览器拿不到用户机器的真实目录树（File System Access API 只给 handle、
+ * `<input type="file">` 只给文件名），而路径映射要求为一堆绝对路径逐个指定本机新位置。
+ * 没有这条路由，用户只能凭记忆手打，打错就是「导不进」。
+ *
+ * 语义与边界
+ * ----------
+ * - **只读**：readdir/stat，绝不创建/改写/删除；不读文件内容；
+ * - POST 形态只**弹系统对话框**（core/native-path-picker.ts），同样不碰盘面；不可用时回
+ *   `reason:'unsupported'|'failed'`，客户端回落 GET 的内置浏览器 —— 对话框不是用户的操作死路；
+ * - 空 `path` = 「此电脑」根列表（Windows 盘符探测，见 core/path-browse.ts）；
+ * - 失败用枚举码回报（`error: 'not-found'|'denied'|'failed'|'not-absolute'`，成功为 null），
+ *   用户可见句子由客户端按字典解析 —— 引擎不写中文；
+ * - 有界：单次列举 500 条上限 + truncated 标记；整体套 withTimeout，不让一个 panic 盘符拖住请求。
+ */
+import { endpoint, errorMessage, queryParam, readJsonBody, writeJson } from './kit.js';
+import { browseDirectory } from '../core/path-browse.js';
+import { pickNativeDirectory } from '../core/native-path-picker.js';
+import { withTimeout } from './route-support.js';
+/** 单次列举的整体时限：正常目录远快于此；网络盘悬挂时宁可报错也不让请求挂着。 */
+const BROWSE_TIMEOUT_MS = 10_000;
+/** POST 可透传文本的长度上限：只用来当对话框的**起点**与**标题**，都不该是长文本。 */
+const PICK_TEXT_MAX = 512;
+/** 取请求体里的短文本字段：非字符串/空串/超长一律视为未提供（对话框走缺省值，不报错）。 */
+function pickText(body, key) {
+    const value = body?.[key];
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' || trimmed.length > PICK_TEXT_MAX ? undefined : trimmed;
+}
+export function pathBrowseRoutes(_env) {
+    return [
+        // ---------------------------------------------------- path-browse
+        // GET  ?path=<绝对路径>：列一层目录（目录在前）。path 缺省 = 根列表。
+        // POST { startPath?, title? }：弹**系统原生**目录选择器（Windows IFileOpenDialog / macOS
+        //      choose folder / Linux zenity·kdialog）。回 `{ ok:false, reason:'unsupported'|'failed' }`
+        //      时客户端回落到 GET 的内置浏览器 —— 同一条路径承载两种能力，避免为一个对话框新开一条路由。
+        //      标题由客户端按当前语言传进来（引擎不产中文）。
+        endpoint({ path: '/api/dsh-config-manager/path-browse', methods: ['GET', 'POST'] }, async (req, res) => {
+            if (req.method === 'POST') {
+                // 用户可能在系统对话框里逛几分钟 —— 时限由 core 的口子兜（10 分钟），此处不再叠加。
+                const body = await readJsonBody(req);
+                writeJson(res, 200, await pickNativeDirectory({
+                    startPath: pickText(body, 'startPath'),
+                    title: pickText(body, 'title'),
+                }));
+                return;
+            }
+            const url = new URL(req.url ?? '/', 'http://localhost');
+            try {
+                const result = await withTimeout(browseDirectory(queryParam(url, 'path')), BROWSE_TIMEOUT_MS, 'path browse timed out');
+                writeJson(res, 200, result);
+            }
+            catch (error) {
+                writeJson(res, 500, { error: errorMessage(error) });
+            }
+        }),
+    ];
+}
+//# sourceMappingURL=path-browse.js.map

package/lib/security/secret-scanner.js

@@ -72,7 +72,7 @@ const BEARER_TOKEN_CHARS = '[A-Za-z0-9._~+/=-]';
  * 于是 `bearer credentials are required` / `bearer authentication failed` / `BEARER HEADER NOT SET`
  * 这类纯小写或纯大写的英文词**不命中**；而 `bearer abc12345`、`BEARER AbCdEfGh`、`bearer <24+ 字符>` 命中。
  *
- * 已知残余（登记在 `docs/spec/known-gaps.md` G-36）：scheme 用非规范大小写**且** token 是 8–23 个**纯字母、
+ * 已知残余（登记在 `docs/maintenance/known-gaps.md` G-36）：scheme 用非规范大小写**且** token 是 8–23 个**纯字母、
  * 单一大小写**时本条不命中；规范 `Bearer …` 形态不受此限（上面那条 `bearer-token` 只要求 8+ 字符，行为不变）。
  */
 const BEARER_TOKEN_ANY_CASE = new RegExp(BEARER_SCHEME_ANY_CASE +

package/lib/ui/sync-settings-view.d.ts

@@ -511,4 +511,22 @@ export declare function workdirBacklog(workDir: {
     };
     error?: string;
 } | undefined): WorkdirBacklog;
+/**
+ * 「这一步该按哪个方向」—— 动作行只留一个 primary（issue 115：两个按钮并排、首次使用看不出该按哪个）。
+ *
+ * 判定只用**已确证**的远端事实，没证据就回落下行：一键同步先拉远端再三方合并、逐项确认，
+ * 不会拿本机默认值覆盖远端历史；上行推送才是产生新快照、改写远端历史的那个动作。
+ * 唯一让上行成为 primary 的情形是「远端确证零快照」（git 工作副本自检 remoteSnapshots === 0）：
+ * 此时同步无事可做，用户要的就是第一次备份。判定入口收在本函数里（channel 一并传入），
+ * 组件不用在调用点再判一次通道 —— 判据只有一处。
+ */
+export declare function pickSyncPrimary(statusInfo: {
+    workDir?: {
+        facts?: {
+            ahead?: number | null;
+            remoteSnapshots?: number | null;
+        };
+        error?: string;
+    };
+} | null | undefined, channel: string): 'push' | 'sync';
 export declare function formatSyncUrlPreview(url: string, max?: number): string;

package/lib/ui/sync-settings-view.js

@@ -562,6 +562,26 @@ export function workdirBacklog(workDir) {
         return { kind: 'never-synced', ahead };
     return { kind: 'ahead', ahead, remoteSnapshots };
 }
+/**
+ * 「这一步该按哪个方向」—— 动作行只留一个 primary（issue 115：两个按钮并排、首次使用看不出该按哪个）。
+ *
+ * 判定只用**已确证**的远端事实，没证据就回落下行：一键同步先拉远端再三方合并、逐项确认，
+ * 不会拿本机默认值覆盖远端历史；上行推送才是产生新快照、改写远端历史的那个动作。
+ * 唯一让上行成为 primary 的情形是「远端确证零快照」（git 工作副本自检 remoteSnapshots === 0）：
+ * 此时同步无事可做，用户要的就是第一次备份。判定入口收在本函数里（channel 一并传入），
+ * 组件不用在调用点再判一次通道 —— 判据只有一处。
+ */
+export function pickSyncPrimary(statusInfo, channel) {
+    // 只有 git 通道会做工作副本自检；别的通道没有这份事实，一律回落下行。
+    if (channel !== 'git')
+        return 'sync';
+    const backlog = workdirBacklog(statusInfo?.workDir);
+    if (backlog.kind === 'never-synced')
+        return 'push';
+    if (backlog.kind === 'clean' && backlog.remoteSnapshots === 0)
+        return 'push';
+    return 'sync';
+}
 export function formatSyncUrlPreview(url, max = 60) {
     return url.slice(0, max);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-config-manager",
-  "version": "0.1.86",
+  "version": "0.2.0",
   "license": "MIT",
   "description": "Backup, restore, export, import, migrate and sync your DeepSeek Harness (DSH) configuration: settings, plugins, MCP servers, skills, agent presets and workspaces. One-click migration to another machine. DSH 配置一键备份、恢复、导出、导入、迁移与同步插件。",
   "icon": "./icon.svg",
@@ -199,7 +199,7 @@
     "lightningcss": "1.33.0",
     "lucide": "^1.61.0",
     "lucide-react": "^1.61.0",
-    "morphicons": "^1.7.1",
+    "morphicons": "^2.0.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
     "schemastery": "^3.18.0",

package/src/cli/web/page.ts

@@ -5,7 +5,7 @@
  * HTML：**零脚本、零外部资源、零构建产物**，配合 http.ts 里收紧的 CSP。
  * 样式内联在 <style> 里（独立于插件 UI 的 CSS Modules；该新 pattern 已登记进 DESIGN.md）。
  * 这套样式表**有一份外部出处**（亮色 IBM Carbon / 暗色 Raycast 阶梯）与逐条对照表：
- * docs/design/2026-10-04-cli-rescue-console-carbon.md —— 改 STYLE 前先读它，改完跑 web.test.ts 的 R3-02。
+ * docs/components/cli-rescue-console.md —— 改 STYLE 前先读它，改完跑 web.test.ts 的 R3-02。
  *
  * 呈现纪律：每个数字都要能回答「你怎么知道的」—— 离线拿不到的（结构化分区/凭据/同步令牌）
  * 一律显式列出并说明原因，绝不显示为 0 或留空。
@@ -32,7 +32,7 @@ export interface PageChrome {
 
 const STYLE = [
   // ---- 设计 token：IBM Carbon（亮色语义四色）+ Raycast（暗色 surface 阶梯）----
-  // 映射表、取的章节与全部偏离记录：docs/design/2026-10-04-cli-rescue-console-carbon.md
+  // 映射表、取的章节与全部偏离记录：docs/components/cli-rescue-console.md
   // 文字色一律取「能读」的那一档：Carbon 的 #24a148 / #f1c21b 只做填充，正文用 #198038 / #8e6a00
   // （AA 对比度由 web.test.ts 的 R3-02 逐对钉住，改色先过那条测试）。
 ':root{color-scheme:light dark;--font:system-ui,-apple-system,"Segoe UI",Roboto,"PingFang SC","Hiragino Sans GB","Microsoft YaHei","Noto Sans SC",sans-serif;--mono:ui-monospace,SFMono-Regular,Menlo,Consolas,"Liberation Mono",monospace;--fg:#161616;--muted:#525252;--bg:#f4f4f4;--card:#fff;--surface:#f4f4f4;--line:#e0e0e0;--accent:#0f62fe;--accent-hover:#0043ce;--on-accent:#fff;--ok:#198038;--warn:#8e6a00;--bad:#da1e28;--scrim:rgba(22,22,22,.45)}',

package/src/client/ConfigManagerSection.tsx

@@ -165,15 +165,6 @@ const navLayoutResult = navWidths === null
    */
   const [libraryPending, setLibraryPending] = useState<ArtifactPendingAction | null>(null)
 
-  /**
-   * 导入面板当前是否停在「从其它 agent 导入」这一页（t17）。
-   *
-   * 为什么是壳层 state 而不是 runStore：它与「导入面板」同生命周期，且**不该被持久化** ——
-   * 刷新后重放一个「正在选来源」的界面只会骗人（来源检测结果要重新拉）。
-   * 关面板 / 切走即随组件卸载归零，与 libraryAction 同一档语义。
-   */
-  const [foreignImportOpen, setForeignImportOpen] = useState(false)
-
   /* ---------------- m-star-prompt：Star 引导弹窗（保持既有能力） ---------------- */
   const [starPromptOpen, setStarPromptOpen] = useState(false)
   /** 弹窗展示的 GitHub 仓库地址（GET /star-prompt 返回；不落 store） */
@@ -441,7 +432,7 @@ const navLayoutResult = navWidths === null
       case 'market.publish.open': openTask('market', { subView: 'myconfigs' }); return
       // 维护与诊断是全屏子视图：命令直达它，而不是只把用户送到环境页
       // 从其它 agent 导入：开导入面板并停在来源选择（与首页工具栏同一路径）
-      case 'import.foreign': openTask('import'); setForeignImportOpen(true); return
+      case 'import.foreign': openTask('import', { foreign: true }); return
       case 'maintenance.open': openMaintenance(); return
       case 'activity.open': openTask('runs'); return
       case 'history.open': openTask('history'); return
@@ -468,10 +459,7 @@ const navLayoutResult = navWidths === null
           t={t}
           syncT={syncT}
           // 直达来源选择：开导入面板 + 把面板切到「从其它 agent 导入」那一步
-          openForeignImport={() => {
-            openTask('import')
-            setForeignImportOpen(true)
-          }}
+          openForeignImport={() => { openTask('import', { foreign: true }) }}
         />
       )
       break
@@ -638,7 +626,7 @@ const navLayoutResult = navWidths === null
             {/* 导入与逛市场都是多阶段流程（§1），同样由本面板承载。
                 此前只渲染了 export / runs / history / about —— 从产物库点「导入」会开到**一个空面板**，
                 而导入其实在页面那条路径里跑（返回后正好看到它），两处状态分叉。 */}
-            {activeTask.kind === 'import' && (foreignImportOpen ? (
+            {activeTask.kind === 'import' && (importTaskForeign(activeTask.payload) ? (
               /* 「从其它 agent 导入」（t17）：页面级步骤，复用同一块面板 ——
                  与既有导入向导并列，避免「弹窗套向导」。产包成功后把 zipPath 写进
                  runStore.library.pendingZip（产物库「一键导入」那条已验证的通道），
@@ -648,8 +636,9 @@ const navLayoutResult = navWidths === null
                 t={t}
                 uiT={uiT}
                 onReady={(result) => {
-                  setForeignImportOpen(false)
+                  // 产包成功 = 这一页的使命结束：入参改回「向导」，并把 zipPath 交给既有导入通道
                   runStore.patch({
+                    task: { ...activeTask, payload: { foreign: false } },
                     library: {
                       pendingZip: { zipPath: result.zipPath, name: result.name },
                     },
@@ -661,7 +650,8 @@ const navLayoutResult = navWidths === null
                 api={api}
                 t={t}
                 uiT={uiT}
-                onOpenForeignImport={() => { setForeignImportOpen(true) }}
+                // 向导 → 来源选择：同样是改 Task 入参（面板状态只有一个事实源）
+                onOpenForeignImport={() => { runStore.patch({ task: { ...activeTask, payload: { foreign: true } } }) }}
               />
             ))}
             {activeTask.kind === 'market' && (
@@ -783,6 +773,19 @@ function marketTaskSubView(payload: unknown): 'browse' | 'myconfigs' | undefined
   return v === 'myconfigs' || v === 'browse' ? v : undefined
 }
 
+/**
+ * Task 入参里取「导入面板停在来源选择」（t17「从其它 agent 导入」）。
+ *
+ * 为什么放进 Task 入参而不是壳层 useState（原 bug 的根因）：壳层 state 与「导入面板」**不同**
+ * 生命周期 —— 关面板只是 `task: null`，壳层不重挂，于是「先点从其它 agent 导入 → 关掉 → 再点导入」
+ * 会带着旧的 true 进来，看到的是来源选择页而不是导入向导。入参随 Task 一起生灭（且 Task 本身
+ * 不持久化，见 run-store 的 `task: null`），开一个**新的**导入面板自然就是向导。
+ */
+function importTaskForeign(payload: unknown): boolean {
+  if (typeof payload !== 'object' || payload === null) return false
+  return (payload as { foreign?: unknown }).foreign === true
+}
+
 function marketTaskItemId(payload: unknown): string | undefined {
   if (typeof payload !== 'object' || payload === null) return undefined
   const id: unknown = (payload as { marketId?: unknown }).marketId

package/src/client/api.ts

@@ -42,6 +42,8 @@ import type { SessionExportProbe } from './session-export/session-export-view.ts
 import type { ForeignSkip } from '../foreign/types.ts';
 import type { ForeignSourcesResponse as ForeignSourcesViewInput } from '../ui/foreign-view.ts';
 import type { DiskUsageReport } from '../core/disk-usage.ts';
+import type { BrowseResult } from '../core/path-browse.ts';
+import type { NativePickResult } from '../core/native-path-picker.ts';
 import type { UiT } from '../ui/i18n.ts';
 import { failedSectionsFromResponse } from '../ui/export-flow.ts';
 import type { SessionFormatDisposition } from '../ui/session-format-disposition.ts';
@@ -291,6 +293,8 @@ const LONG_OPTS: RequestOptions = { timeoutMs: LONG_REQUEST_TIMEOUT_MS };
 
 /** 插件自更新请求的超时：宿主侧安装上限 15 分钟，客户端留出余量（16 分钟）避免误报「请求超时」。 */
 const SELF_UPDATE_OPTS: RequestOptions = { timeoutMs: 16 * 60 * 1000 };
+/** 原生目录选择器：宿主侧 10 分钟上限，这里留出传输余量。 */
+const NATIVE_PICK_OPTS: RequestOptions = { timeoutMs: 11 * 60 * 1000 };
 
 /** query-string 辅助（跳过 undefined/空串，与 dsh-ssh 一致） */
 function query(params: Record<string, string | number | undefined>): string {
@@ -337,6 +341,14 @@ function triggerBlobDownload(blob: Blob, filename: string): void {
   setTimeout(() => { URL.revokeObjectURL(url) }, 15_000)
 }
 
+/**
+ * DSH 宿主自带目录选择器的结果。
+ *  - `ok`：用户选中（`path` 非空）；
+ *  - `canceled`：用户点了取消，调用方静默收手；
+ *  - `unavailable`：宿主没有这个能力（非桌面宿主 / 版本较旧 / 调用抛错），调用方回落下一层。
+ */
+export type DshPickResult = { ok: true; path: string } | { ok: false; reason: 'canceled' | 'unavailable' }
+
 /**
  * Config Manager 浏览器半的唯一数据入口。
  * 同时实现 `ExportPort`（export-flow 用）与 `ImportPort`（import-wizard 用）。
@@ -350,9 +362,16 @@ export class ConfigManagerApi {
   exportPassword: string | null = null
   /** 客户端展示层翻译器（zh 源 / en 镜像，见 ui/i18n.ts）。 */
   readonly t: UiT
+  /**
+   * DSH 自带目录选择器（桌面壳全局 `__DSH_DIRECTORY_PICKER__.pick` 或客户端服务 `ctx.get('uiWorkspace').pickDirectory`），
+   * 由 `apply(ctx)` 注入的**惰取** thunk（解析顺序见 `import/dsh-directory-pick.ts`）。
+   * 宿主没提供该能力时保持 `undefined`。
+   */
+  private readonly dshDirectoryPicker: (() => Promise<string | null>) | undefined
 
-  constructor(t: UiT) {
+  constructor(t: UiT, dshDirectoryPicker?: () => Promise<string | null>) {
     this.t = t
+    this.dshDirectoryPicker = dshDirectoryPicker
   }
 
   // ------------------------------------------------------------- status
@@ -575,6 +594,46 @@ export class ConfigManagerApi {
     );
   }
 
+  /**
+   * 列出一层本机目录（只读；路径映射「选本机路径」弹窗的数据源）。
+   * `target` 缺省或空串 = 「此电脑」根列表（Windows 盘符 / POSIX `/`）。
+   * 失败不抛异常：宿主回 `error: 'not-found'|'denied'|'failed'|'not-absolute'`，弹窗照常可用。
+   */
+  async browsePath(target?: string): Promise<BrowseResult> {
+    const suffix = target === undefined || target === '' ? '' : query({ path: target });
+    return getJson<BrowseResult>(CONFIG_MANAGER_API.pathBrowse + suffix, this.t);
+  }
+
+  /**
+   * 弹**系统原生**目录选择器（同一端点的 POST 形态）。
+   *
+   * 用户可能在系统对话框里逛几分钟，所以超时必须远大于常规请求：内核侧 10 分钟兜底，这里再加一道。
+   * 回 `reason: 'unsupported' | 'failed'` 时调用方回落到内置目录浏览器，不当错误处理。
+   */
+  async pickNativePath(startPath?: string, title?: string): Promise<NativePickResult> {
+    const body: Record<string, string> = {};
+    if (startPath !== undefined && startPath !== '') body.startPath = startPath;
+    if (title !== undefined && title !== '') body.title = title;
+    return postJson<NativePickResult>(CONFIG_MANAGER_API.pathBrowse, body, this.t, NATIVE_PICK_OPTS);
+  }
+
+  /**
+   * 复用 **DSH 宿主自带**的原生目录选择器（就是「选择工作区目录」那个窗口）。
+   *
+   * 比插件自己起系统对话框更稳：窗口由 DSH 主进程弹，跟着宿主走，不受插件宿主的进程形态限制。
+   * 完全不设客户端超时 —— 用户可能在原生窗口里逛几分钟，宿主侧 `host.pickDirectory` 也是 caller-signal-only。
+   * 宿主没有该能力或调用抛错一律归成 `unavailable`，由调用方回落插件自己的原生对话框，不当错误处理。
+   */
+  async pickDshPath(): Promise<DshPickResult> {
+    if (this.dshDirectoryPicker === undefined) return { ok: false, reason: 'unavailable' }
+    try {
+      const path = await this.dshDirectoryPicker()
+      return typeof path === 'string' && path !== '' ? { ok: true, path } : { ok: false, reason: 'canceled' }
+    } catch {
+      return { ok: false, reason: 'unavailable' }
+    }
+  }
+
   /** ImportPort.decryptArchive：解锁整体加密备份容器 → 明文 ZIP 路径 + 解密覆盖的凭据 ref 名 */
   async decryptArchive(zipPath: string, password: string): Promise<DecryptArchiveResponse> {
     return postJson<DecryptArchiveResponse>(CONFIG_MANAGER_API.decryptArchive, { zipPath, password }, this.t, LONG_OPTS);

package/src/client/bundle-selfcontained.test.ts

@@ -73,6 +73,15 @@ test('lib/client.js 自包含：只 require 运行时白名单内的外部包',
       `修复方向：把该依赖加回 tsdown.config.ts 的 deps.alwaysBundle（并保留在 devDependencies）。`,
   )
 
+  // 相对 require = 依赖同目录 chunk：loader 只取 lib/client.js，不会请求 ./client2.js。
+  const relativeSpecifiers = result.specifiers.filter((s) => s.startsWith('.'))
+  assert.deepEqual(
+    relativeSpecifiers,
+    [],
+    `lib/client.js 依赖了同目录 chunk（loader 不会请求它们）：${relativeSpecifiers.join(', ')}\n` +
+      '修复方向：tsdown.config.ts 的 outputOptions.inlineDynamicImports = true。',
+  )
+
   // node:* 内置模块不属于本护栏判定范围（浏览器半不应依赖它们，但那是另一条不变量）。
   if (result.nodeBuiltins.length > 0) {
     t.diagnostic(`注意：bundle 内出现 Node 内置 require：${result.nodeBuiltins.join(', ')}`)