dsh-config-manager 0.1.69 → 0.1.71

package/src/client/about/ReleaseBody.tsx

@@ -0,0 +1,144 @@
+/**
+ * ReleaseBody —— GitHub Release 正文的结构化安全渲染（**共享原语**）。
+ *
+ * 为什么抽出来：「更新内容」浏览弹窗（ReleaseNotesDialog）与新版本弹窗（PluginUpdateDialog）
+ * 都要渲染 release 正文 —— 渲染规则必须只有一份：纯文本分块解析 + 行内格式
+ * （`code` / **bold** / [link](url)），**零 dangerouslySetInnerHTML**（杜绝 XSS）。
+ * 本组件从 ReleaseNotesDialog 原样搬出（含内联样式），视觉与行为逐字不变。
+ */
+import type { TranslateNS } from '../client-types.ts'
+import { parseMarkdownBlocks, type MarkdownBlock } from './release-notes-view.ts'
+import css from '../config-manager.module.css'
+
+/**
+ * 纯 React 安全渲染 Markdown 文本行中的行内格式（粗体、行内代码、链接）。
+ */
+function renderInlineMarkdown(text: string) {
+  // 简单行内解析：`code`, **bold**, [link](url)
+  // 分割正则
+  const regex = /(`[^`]+`|\*\*[^*]+\*\*|\[[^\]]+\]\([^)]+\))/g
+  const parts = text.split(regex)
+
+  return parts.map((part, idx) => {
+    if (!part) return null
+    // 行内代码 `...`
+    if (part.startsWith('`') && part.endsWith('`') && part.length >= 2) {
+      return (
+        <code key={idx} className={css.cliName}>
+          {part.slice(1, -1)}
+        </code>
+      )
+    }
+    // 粗体 **...**
+    if (part.startsWith('**') && part.endsWith('**') && part.length >= 4) {
+      return <strong key={idx}>{part.slice(2, -2)}</strong>
+    }
+    // 链接 [text](url)
+    const linkMatch = part.match(/^\[([^\]]+)\]\(([^)]+)\)$/)
+    if (linkMatch && linkMatch[1] && linkMatch[2]) {
+      return (
+        <a
+          key={idx}
+          href={linkMatch[2]}
+          target="_blank"
+          rel="noreferrer"
+          className={css.aboutAuthor}
+        >
+          {linkMatch[1]}
+        </a>
+      )
+    }
+    return <span key={idx}>{part}</span>
+  })
+}
+
+/**
+ * 渲染单个结构化 Markdown 块。
+ */
+function MarkdownBlockView({ block }: { block: MarkdownBlock }) {
+  switch (block.type) {
+    case 'heading': {
+      const headingStyle = {
+        fontWeight: 600,
+        color: 'var(--dsw-alias-label-primary)',
+        marginTop: block.level === 1 ? '12px' : '8px',
+        marginBottom: '4px',
+        fontSize: block.level === 1 ? '15px' : block.level === 2 ? '14px' : '13px',
+      }
+      return <div style={headingStyle}>{block.text}</div>
+    }
+    case 'list-item': {
+      return (
+        <div style={{ display: 'flex', gap: '6px', alignItems: 'flex-start', paddingLeft: '4px' }}>
+          <span style={{ color: 'var(--dsw-alias-label-tertiary)', userSelect: 'none' }}>
+            {block.ordered ? (block.index ?? 1) + '.' : '•'}
+          </span>
+          <div style={{ flex: 1 }}>{renderInlineMarkdown(block.text)}</div>
+        </div>
+      )
+    }
+    case 'quote': {
+      return (
+        <div
+          style={{
+            borderLeft: '3px solid var(--dsw-alias-border-l1)',
+            paddingLeft: '8px',
+            color: 'var(--dsw-alias-label-secondary)',
+            fontStyle: 'italic',
+          }}
+        >
+          {renderInlineMarkdown(block.text)}
+        </div>
+      )
+    }
+    case 'code-block': {
+      return (
+        <pre
+          className={css.cliCommand}
+          style={{ margin: '4px 0', padding: '8px', fontSize: '12px' }}
+        >
+          {block.code}
+        </pre>
+      )
+    }
+    case 'hr': {
+      return (
+        <div
+          style={{
+            borderBottom: '1px solid var(--dsw-alias-border-l2)',
+            margin: '8px 0',
+          }}
+        />
+      )
+    }
+    case 'paragraph':
+    default: {
+      return <div>{renderInlineMarkdown(block.text)}</div>
+    }
+  }
+}
+
+/** release 正文：结构化块渲染；空正文显示「暂无详细说明」。 */
+export function ReleaseBody({ body, t }: { body: string; t: TranslateNS<'config-manager'> }) {
+  const blocks = parseMarkdownBlocks(body)
+  return (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: '6px',
+        fontSize: '13px',
+        lineHeight: '1.6',
+        color: 'var(--dsw-alias-label-primary)',
+      }}
+    >
+      {blocks.length > 0 ? (
+        blocks.map((block, idx) => <MarkdownBlockView key={idx} block={block} />)
+      ) : (
+        <div style={{ color: 'var(--dsw-alias-label-tertiary)', fontStyle: 'italic' }}>
+          {t('about.releaseNotes.noBody')}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/client/about/ReleaseNotesDialog.tsx

@@ -17,10 +17,9 @@ import { ABOUT_META } from './about-view.ts'
 import {
   deriveReleasesUrl,
   fetchReleases,
-  parseMarkdownBlocks,
   type FormattedRelease,
-  type MarkdownBlock,
 } from './release-notes-view.ts'
+import { ReleaseBody } from './ReleaseBody.tsx'
 import css from '../config-manager.module.css'
 
 export interface ReleaseNotesDialogProps {
@@ -34,113 +33,6 @@ export interface ReleaseNotesDialogProps {
 
 const PAGE_SIZE = 5
 
-/**
- * 纯 React 安全渲染 Markdown 文本行中的行内格式（粗体、行内代码、链接）。
- */
-function renderInlineMarkdown(text: string) {
-  // 简单行内解析：`code`, **bold**, [link](url)
-  // 分割正则
-  const regex = /(`[^`]+`|\*\*[^*]+\*\*|\[[^\]]+\]\([^)]+\))/g
-  const parts = text.split(regex)
-
-  return parts.map((part, idx) => {
-    if (!part) return null
-    // 行内代码 `...`
-    if (part.startsWith('`') && part.endsWith('`') && part.length >= 2) {
-      return (
-        <code key={idx} className={css.cliName}>
-          {part.slice(1, -1)}
-        </code>
-      )
-    }
-    // 粗体 **...**
-    if (part.startsWith('**') && part.endsWith('**') && part.length >= 4) {
-      return <strong key={idx}>{part.slice(2, -2)}</strong>
-    }
-    // 链接 [text](url)
-    const linkMatch = part.match(/^\[([^\]]+)\]\(([^)]+)\)$/)
-    if (linkMatch && linkMatch[1] && linkMatch[2]) {
-      return (
-        <a
-          key={idx}
-          href={linkMatch[2]}
-          target="_blank"
-          rel="noreferrer"
-          className={css.aboutAuthor}
-        >
-          {linkMatch[1]}
-        </a>
-      )
-    }
-    return <span key={idx}>{part}</span>
-  })
-}
-
-/**
- * 渲染单个结构化 Markdown 块。
- */
-function MarkdownBlockView({ block }: { block: MarkdownBlock }) {
-  switch (block.type) {
-    case 'heading': {
-      const headingStyle = {
-        fontWeight: 600,
-        color: 'var(--dsw-alias-label-primary)',
-        marginTop: block.level === 1 ? '12px' : '8px',
-        marginBottom: '4px',
-        fontSize: block.level === 1 ? '15px' : block.level === 2 ? '14px' : '13px',
-      }
-      return <div style={headingStyle}>{block.text}</div>
-    }
-    case 'list-item': {
-      return (
-        <div style={{ display: 'flex', gap: '6px', alignItems: 'flex-start', paddingLeft: '4px' }}>
-          <span style={{ color: 'var(--dsw-alias-label-tertiary)', userSelect: 'none' }}>
-            {block.ordered ? `${block.index ?? 1}.` : '•'}
-          </span>
-          <div style={{ flex: 1 }}>{renderInlineMarkdown(block.text)}</div>
-        </div>
-      )
-    }
-    case 'quote': {
-      return (
-        <div
-          style={{
-            borderLeft: '3px solid var(--dsw-alias-border-l1)',
-            paddingLeft: '8px',
-            color: 'var(--dsw-alias-label-secondary)',
-            fontStyle: 'italic',
-          }}
-        >
-          {renderInlineMarkdown(block.text)}
-        </div>
-      )
-    }
-    case 'code-block': {
-      return (
-        <pre
-          className={css.cliCommand}
-          style={{ margin: '4px 0', padding: '8px', fontSize: '12px' }}
-        >
-          {block.code}
-        </pre>
-      )
-    }
-    case 'hr': {
-      return (
-        <div
-          style={{
-            borderBottom: '1px solid var(--dsw-alias-border-l2)',
-            margin: '8px 0',
-          }}
-        />
-      )
-    }
-    case 'paragraph':
-    default: {
-      return <div>{renderInlineMarkdown(block.text)}</div>
-    }
-  }
-}
 
 /**
  * 单个版本的卡片视图。
@@ -154,8 +46,6 @@ function ReleaseCardView({
   isFirst: boolean
   t: TranslateNS<'config-manager'>
 }) {
-  const blocks = parseMarkdownBlocks(release.body)
-
   return (
     <div
       style={{
@@ -215,25 +105,8 @@ function ReleaseCardView({
         </Button>
       </div>
 
-      {/* 正文：结构化 Markdown 块渲染 */}
-      <div
-        style={{
-          display: 'flex',
-          flexDirection: 'column',
-          gap: '6px',
-          fontSize: '13px',
-          lineHeight: '1.6',
-          color: 'var(--dsw-alias-label-primary)',
-        }}
-      >
-        {blocks.length > 0 ? (
-          blocks.map((block, idx) => <MarkdownBlockView key={idx} block={block} />)
-        ) : (
-          <div style={{ color: 'var(--dsw-alias-label-tertiary)', fontStyle: 'italic' }}>
-            {t('about.releaseNotes.noBody')}
-          </div>
-        )}
-      </div>
+      {/* 正文：结构化 Markdown 块渲染（共享原语 ReleaseBody，渲染规则只有一份） */}
+      <ReleaseBody body={release.body} t={t} />
     </div>
   )
 }

package/src/client/about/about-view.ts

@@ -15,6 +15,7 @@
  * 判定（是否真的有新版本、给不给终端命令）全在这里，面板只映射 kind → 文案与 Badge。
  */
 import type { PluginUpdateCheckResult } from '../../ui/types.ts';
+import type { ConfigManagerKey } from '../locales.ts';
 
 /** 插件的公开元数据（静态常量，来源见设计文档 §3 信息表） */
 export interface AboutMeta {
@@ -183,15 +184,16 @@ export const ABOUT_LINKS: AboutLinks = deriveAboutLinks(ABOUT_META.repoUrl);
  *  DSH 挂了也能用；文案与命令见 README.md「CLI — the first line of defense」。 */
 export const ABOUT_CLI: {
   installCommand: string;
-  commands: { command: string; description: string }[];
+  /** client-F5：说明文案走字典键（此前硬编码中文，英文界面恒为中文） */
+  commands: { command: string; descriptionKey: ConfigManagerKey }[];
   docsUrl: string;
 } = {
   installCommand: 'npm install -g dsh-config-manager@latest --omit=peer',
   commands: [
-    { command: 'dsh-config-manager help', description: '列出全部 CLI 命令与用法（离线可用）' },
-    { command: 'dsh-config-manager snapshots', description: '列出本机回滚快照（无需 DSH 运行）' },
-    { command: 'dsh-config-manager restore [--id <id>] [--dry-run]', description: '恢复到导入前状态（离线）' },
-    { command: 'dsh-config-manager reinstall [--yes] [--wipe-config]', description: '一键重装 DSH（救援）' },
+    { command: 'dsh-config-manager help', descriptionKey: 'about.cli.help' },
+    { command: 'dsh-config-manager snapshots', descriptionKey: 'about.cli.snapshots' },
+    { command: 'dsh-config-manager restore [--id <id>] [--dry-run]', descriptionKey: 'about.cli.restore' },
+    { command: 'dsh-config-manager reinstall [--yes] [--wipe-config]', descriptionKey: 'about.cli.reinstall' },
   ],
   docsUrl: 'https://github.com/xiajiajun516/dsh-config-manager#-cli--the-first-line-of-defense-when-dsh-is-broken',
 };

package/src/client/about/plugin-update-view.test.ts

@@ -0,0 +1,25 @@
+/**
+ * plugin-update-view 测试：失败码 → 文案键的映射必须覆盖共享失败码清单，
+ * 且这些键在 zh/en 两本字典里都存在（穷尽映射的运行时兜底 —— 编译期由 Record 类型保证）。
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { UPDATE_FAILURE_KEYS, updateFailureKey } from './plugin-update-view.ts';
+import { SELF_UPDATE_FAILURE_CODES } from '../../utils/shared-constants.ts';
+import { en, zh } from '../locales.ts';
+
+test('每个失败码都有专属文案键，且 zh/en 字典都有该键', () => {
+  for (const code of SELF_UPDATE_FAILURE_CODES) {
+    const key = UPDATE_FAILURE_KEYS[code];
+    assert.ok(typeof key === 'string' && key.length > 0, '缺少映射: ' + code);
+    assert.equal(typeof zh[key], 'string', 'zh 缺键: ' + key);
+    assert.equal(typeof en[key], 'string', 'en 缺键: ' + key);
+  }
+});
+
+test('updateFailureKey：已知码查表，未知码回 null（调用方回落宿主原始文本）', () => {
+  assert.equal(updateFailureKey('install-failed'), 'about.update.code.installFailed');
+  assert.equal(updateFailureKey('non-registry-install'), 'about.update.code.nonRegistryInstall');
+  assert.equal(updateFailureKey('boom'), null);
+  assert.equal(updateFailureKey(''), null);
+});

package/src/client/about/plugin-update-view.ts

@@ -0,0 +1,26 @@
+/**
+ * 插件自更新弹窗的纯函数模型（node 可测，无 React / 无 DOM）。
+ *
+ * 只有一件事：把宿主返回的**失败码**映射到本地化文案键。
+ *
+ * 为什么不让组件直接渲染 host 的 error：那是英文技术细节（还可能带路径），界面必须给用户
+ * 可读的中文/英文文案；只有**未知码**才回落到宿主原始文本（此时至少不隐藏真实原因）。
+ */
+import type { ConfigManagerKey } from '../locales.ts';
+import type { SelfUpdateFailureCode } from '../../utils/shared-constants.ts';
+
+/** 失败码 → 文案键（穷尽映射：共享常量新增码时这里编译报错，逼着同时补 zh/en 字典）。 */
+export const UPDATE_FAILURE_KEYS: Readonly<Record<SelfUpdateFailureCode, ConfigManagerKey>> = {
+  'invalid-version': 'about.update.code.invalidVersion',
+  'profile-unknown': 'about.update.code.profileUnknown',
+  'unsupported-profile': 'about.update.code.unsupportedProfile',
+  'non-registry-install': 'about.update.code.nonRegistryInstall',
+  'not-newer': 'about.update.code.notNewer',
+  'install-failed': 'about.update.code.installFailed',
+};
+
+/** 失败码 → 文案键；未知码回 null（调用方回落宿主原始文本）。 */
+export function updateFailureKey(code: string): ConfigManagerKey | null {
+  const table: Record<string, ConfigManagerKey | undefined> = UPDATE_FAILURE_KEYS;
+  return table[code] ?? null;
+}

package/src/client/about/release-notes-view.test.ts

@@ -12,6 +12,8 @@ import {
   parseMarkdownBlocks,
   parseReleaseItem,
   parseReleasesResponse,
+  findReleaseForVersion,
+  normalizeReleaseVersion,
 } from './release-notes-view.ts';
 
 test('parseGitHubRepo: 正确解析 GitHub 仓库 URL', () => {
@@ -172,3 +174,34 @@ test('parseMarkdownBlocks: 解析标题、列表、引用、代码块与段落',
   assert.equal((blocks[8] as { code: string }).code, 'const a = 1;');
   assert.equal(blocks[9]!.type, 'paragraph');
 });
+
+test('normalizeReleaseVersion: 去空白与前导 v/V', () => {
+  assert.equal(normalizeReleaseVersion('v0.1.70'), '0.1.70');
+  assert.equal(normalizeReleaseVersion('V0.1.70'), '0.1.70');
+  assert.equal(normalizeReleaseVersion(' 0.1.70 '), '0.1.70');
+  assert.equal(normalizeReleaseVersion(''), '');
+});
+
+test('findReleaseForVersion: 按归一化 tag 精确匹配（v 前缀 / 大小写 / 空格）', () => {
+  const releases = [
+    parseReleaseItem({ id: 2, tag_name: 'v0.1.70', body: 'new' })!,
+    parseReleaseItem({ id: 1, tag_name: 'v0.1.69', body: 'old' })!,
+  ];
+  assert.equal(findReleaseForVersion(releases, '0.1.70').release?.tag, 'v0.1.70');
+  assert.equal(findReleaseForVersion(releases, '0.1.70').exact, true);
+  assert.equal(findReleaseForVersion(releases, 'V0.1.69').release?.tag, 'v0.1.69');
+  assert.equal(findReleaseForVersion(releases, ' 0.1.70 ').exact, true);
+});
+
+test('findReleaseForVersion: 匹配不到时回退第一条并标记 exact=false（不假装是目标版本）', () => {
+  const releases = [parseReleaseItem({ id: 2, tag_name: 'v0.2.0', body: 'newest' })!];
+  const miss = findReleaseForVersion(releases, '0.3.0');
+  assert.equal(miss.release?.tag, 'v0.2.0');
+  assert.equal(miss.exact, false);
+});
+
+test('findReleaseForVersion: 空列表 / 空版本不抛错', () => {
+  assert.deepEqual(findReleaseForVersion([], '0.1.70'), { release: null, exact: false });
+  const releases = [parseReleaseItem({ id: 1, tag_name: 'v0.1.70', body: '' })!];
+  assert.equal(findReleaseForVersion(releases, '').exact, false);
+});

package/src/client/about/release-notes-view.ts

@@ -308,3 +308,37 @@ export function parseMarkdownBlocks(text: string): MarkdownBlock[] {
 
   return blocks;
 }
+
+/* ---------------- 版本匹配（「新版本」弹窗用） ---------------- */
+
+/**
+ * 版本 / tag 归一化：去掉空白与前导 v/V。
+ *
+ * 为什么需要：npm 版本是 `0.1.70`，而 GitHub release tag 是 `v0.1.70`（本仓打 tag 即触发发布），
+ * 两边直接比较永远不相等。
+ */
+export function normalizeReleaseVersion(value: string): string {
+  return value.trim().replace(/^[vV]/, '');
+}
+
+/** 目标版本 → release 的匹配结果：exact=false 表示回退到了最新一条（tag 没对上）。 */
+export interface ReleaseMatch {
+  release: FormattedRelease | null;
+  exact: boolean;
+}
+
+/**
+ * 找目标版本对应的 release：先按归一化 tag 精确匹配；匹配不到时**回退到第一条**并标记
+ * exact=false —— npm 已发布但 GitHub release 尚未生成时界面仍要显示一段说明，同时如实标注
+ * 这是「最新一条发布内容」，绝不假装它就是目标版本。
+ */
+export function findReleaseForVersion(releases: readonly FormattedRelease[], version: string): ReleaseMatch {
+  const want = normalizeReleaseVersion(version);
+  const first = releases.length > 0 ? releases[0] : undefined;
+  const fallback = first === undefined ? null : first;
+  if (want === '') return { release: fallback, exact: false };
+  for (const release of releases) {
+    if (normalizeReleaseVersion(release.tag) === want) return { release, exact: true };
+  }
+  return { release: fallback, exact: false };
+}

package/src/client/api.ts

@@ -37,7 +37,10 @@ import type { ConsultReport } from '../core/migration-consult.ts';
 import type { Manifest, SectionId } from '../schema/types.ts';
 import type { BackupScheduleStatus, BackupRunResult, BackupScheduleDraft } from '../ui/backup-schedule.ts';
 import type { BackupFileMeta } from '../sync/backup-files.ts';
-import type { DiskUsageCleanupResult, PluginUpdateCheckResult } from '../ui/types.ts';
+import type { DiskUsageCleanupResult, PluginUpdateApplyResult, PluginUpdateCheckResult } from '../ui/types.ts';
+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 { zhUiT, type UiT } from '../ui/i18n.ts';
 import { failedSectionsFromResponse } from '../ui/export-flow.ts';
@@ -75,6 +78,42 @@ export interface ServiceStatus {
   bundles?: string[];
 }
 
+/**
+ * 外部 agent 来源发现响应（`GET /foreign-sources`）。
+ *
+ * 复用 `src/ui/foreign-view.ts` 的输入类型 —— 响应形状的**唯一权威**在那边（视图模型只读它）。
+ * 路径刻意在本文件重导出，避免组件同时 import 两处（同 `UploadResponse` 的做法）。
+ */
+export type ForeignSourcesResponse = ForeignSourcesViewInput
+
+/**
+ * 外部来源 → bundle 的响应（`POST /foreign-import`）。
+ *
+ * `zipPath`：受控临时目录里的标准 bundle v1 ZIP，直接喂给既有导入向导的 `analyzeImport`。
+ * `skipped` / `credentialRefs` **绝不含凭据值**（值在转换层已被剥离）。
+ */
+export interface ForeignImportResponse {
+  zipPath: string
+  name: string
+  /** 来源 id（六来源之一） */
+  source: string
+  /** 来源显示名的字典键（如 foreign.source.hermes） */
+  labelKey: string
+  /** 产物字节数（读不到时为 0，界面按「未知」处理） */
+  sizeBytes: number
+  /** 本次产出包内的分区（空分区不会被写入，也不出现在这里） */
+  sections: SectionId[]
+  /** 各分区的条目计数（机器可读；键形如 `mcp.servers`） */
+  counts: Record<string, number>
+  /** 未迁移项（只有机器码 + 位置名 + 条数） */
+  skipped: ForeignSkip[]
+  /** 凭据**引用名**（形如 `mcp:gitnexus:GITHUB_TOKEN`）；导入后由用户补录值 */
+  credentialRefs: string[]
+  /** 检测到的本机位置（相对 home；绝不回传绝对路径） */
+  detectedPaths: string[]
+  /** 冲突策略（用户决策：同 id 不覆盖、跳过并报码） */
+  conflictPolicy: string
+}
 /** export 端点响应（对齐 ExportFlow 的 ExportRunResult 前半部分；runId 为 m1 run 注册表标识） */
 export interface ExportResponse {
   zipPath: string;
@@ -248,6 +287,9 @@ export { ConfigManagerApiError } from './common/http.ts';
 /** 长操作请求选项（5 分钟；超时文案走默认键 `error.requestTimeout`，导出族另有专属键）。 */
 const LONG_OPTS: RequestOptions = { timeoutMs: LONG_REQUEST_TIMEOUT_MS };
 
+/** 插件自更新请求的超时：宿主侧安装上限 15 分钟，客户端留出余量（16 分钟）避免误报「请求超时」。 */
+const SELF_UPDATE_OPTS: RequestOptions = { timeoutMs: 16 * 60 * 1000 };
+
 /** query-string 辅助（跳过 undefined/空串，与 dsh-ssh 一致） */
 function query(params: Record<string, string | number | undefined>): string {
   const search = new URLSearchParams();
@@ -778,6 +820,16 @@ export class ConfigManagerApi {
     return getJson<PluginUpdateCheckResult>(url, this.t);
   }
 
+  /**
+   * 执行插件自更新（POST /update-apply）—— **只在用户显式点「立即更新」后**调用。
+   *
+   * 宿主经官方 dsh plugin 通道安装钉住的精确版本（见 core/self-update.ts）；成功后必须
+   * 重启 DSH 才生效。安装可能较慢（慢网络下分钟级），故用独立的长超时档位。
+   */
+  async applyUpdate(version: string): Promise<PluginUpdateApplyResult> {
+    return postJson<PluginUpdateApplyResult>(CONFIG_MANAGER_API.updateApply, { version }, this.t, SELF_UPDATE_OPTS);
+  }
+
   // ------------------------------------------------- Phase 7 迁移前咨询
   /** 迁移前咨询（只读健康评分 + 建议）：对 4 种可迁移源生成统一咨询报告。 */
   async consult(input: { type: 'export-zip' | 'local-snapshot' | 'remote-snapshot' | 'profile'; id: string; snapshotId?: string }): Promise<ConsultReport> {
@@ -785,6 +837,98 @@ export class ConfigManagerApi {
     return postJson<ConsultReport>(CONFIG_MANAGER_API.consult, input, this.t, LONG_OPTS);
   }
 
+  // ------------------------------------------------- 外部 agent 来源（t17）
+  /**
+   * GET /foreign-sources：六来源的本机检测结果（**只读**，零写入）。
+   *
+   * 未安装是正常状态（found=false），不是错误 —— 界面照常列出全部六条，
+   * 用户才知道「哪些查过了、本机确实没有」。
+   */
+  async foreignSources(opts: { projectDir?: string } = {}): Promise<ForeignSourcesResponse> {
+    const q = opts.projectDir !== undefined && opts.projectDir !== ''
+      ? query({ projectDir: opts.projectDir })
+      : ''
+    return getJson<ForeignSourcesResponse>(CONFIG_MANAGER_API.foreignSources + q, this.t, LONG_OPTS);
+  }
+
+  /**
+   * POST /foreign-import：把本机某个外部 agent 的配置翻译成标准 bundle v1 ZIP，
+   * 落到宿主受控临时目录并返回 zipPath —— 之后**完全复用既有导入向导**
+   * （analyzeImport → createImportPlan → executeImportPlan），不新建第二套向导。
+   *
+   * 为什么必须由宿主产包：转换要读本机文件系统并写 ZIP，浏览器半做不了
+   * （此前该能力只在 CLI 里，GUI 会在「点导入」之后断链）。
+   *
+   * `projectDir`：项目级真值位置（Cursor/Codex 的 <项目>/.cursor/**）。**缺省不传 = 不扫项目级** ——
+   * 宿主进程的 cwd 不是用户的项目，绝不猜。
+   *
+   * 响应**绝不含凭据值**：只有 skipped 机器码与凭据**引用名**（值在转换层已被剥离）。
+   */
+  async foreignImport(source: string, opts: { projectDir?: string } = {}): Promise<ForeignImportResponse> {
+    return postJson<ForeignImportResponse>(
+      CONFIG_MANAGER_API.foreignImport,
+      {
+        source,
+        ...(opts.projectDir !== undefined && opts.projectDir !== '' ? { projectDir: opts.projectDir } : {}),
+      },
+      this.t,
+      LONG_OPTS,
+    );
+  }
+
+  // ------------------------------------------------- F-2 官方 session.export 通道
+  /**
+   * GET /session-export（**只读**）：探测 DSH 官方 session.export 端的可用性。
+   *
+   * 为什么由宿主代探而不是浏览器直接打 DSH：见 src/routes/session-export.ts 的文件头 ——
+   * 该端点挂在带浏览器认证的 `/api` 前缀下，浏览器侧「401 / 404 / 连不上」分不开，
+   * 而「路由没注册」与「持久化后端缺服务」的处理方式**完全不同**（前者保守显示、后者隐藏入口）。
+   *
+   * 返回三态（**绝不二值化**）：`available` 显示 / `unavailable` 禁用并说明原因 / `unknown` 保守显示。
+   */
+  async sessionExportProbe(): Promise<SessionExportProbe> {
+    const body = await getJson<{ ok: boolean } & SessionExportProbe>(CONFIG_MANAGER_API.sessionExport, this.t);
+    return {
+      availability: body.availability,
+      ...(body.reason === undefined ? {} : { reason: body.reason }),
+      status: body.status,
+      path: body.path,
+      checkedAt: body.checkedAt,
+    };
+  }
+
+  /** F-2：原始日志 ZIP 的代理下载地址（探测与下载同一条路由，query 决定形态）。 */
+  sessionExportUrl(sessionId: string, opts: { includeDescendants?: boolean } = {}): string {
+    const descendants = opts.includeDescendants !== false ? 'true' : 'false';
+    return `${CONFIG_MANAGER_API.sessionExport}?sessionId=${encodeURIComponent(sessionId)}&includeDescendants=${descendants}`;
+  }
+
+  /**
+   * F-2：把某条会话的原始日志 ZIP 下载到本机（由 DSH 自己打包，含子会话与附件）。
+   *
+   * 复用**既有**的流式下载链路（openStream + saveDownloaded，与导出产物同一条）：
+   *  - 大 ZIP 不整本驻留内存（流式写优先，不可用时才 Blob 兜底）；
+   *  - 正文阶段是**空闲超时**（每读一块重置）—— 宿主卡死时明确失败而非永久转圈；
+   *  - 失败时把上游（DSH）的状态码与正文如实抛出（代理路由原样透传，见 src/routes/session-export.ts）。
+   *
+   * 为什么走本插件的代理而不是直连 DSH 的 `/api/session.export`：`openStream` 认得本插件的
+   * 错误信封；直连 DSH 时 401/404 只是一次没有解释的失败（而 404 也可能是「拼错路径」）。
+   */
+  async downloadSessionExport(
+    sessionId: string,
+    opts?: DownloadOptions,
+    onProgress?: (received: number, total: number) => void,
+  ): Promise<DownloadResult> {
+    const stream = await openStream(this.sessionExportUrl(sessionId), this.t);
+    try {
+      return await this.saveDownloaded(stream, 'dsh-session-' + sessionId + '.zip', opts, onProgress);
+    } catch (err) {
+      throw stream.mapTimeout(err);
+    } finally {
+      stream.close();
+    }
+  }
+
   // ------------------------------------------------- P1-⑦/P2-⑬ 备份内容查看 / 差异对比
   /** 「查看备份内容」：对 exports 目录内的备份文件做只读分析（reuse /analyze，零写入）。
    *  返回分析 + 与当前配置的差异计划摘要（"装/导这个备份会动你什么"）。 */

package/src/client/common/Icon.tsx

@@ -31,6 +31,7 @@ import Download from 'lucide-react/dist/esm/icons/download.mjs'
 import Eye from 'lucide-react/dist/esm/icons/eye.mjs'
 import FolderInput from 'lucide-react/dist/esm/icons/folder-input.mjs'
 import HardDriveDownload from 'lucide-react/dist/esm/icons/hard-drive-download.mjs'
+import History from 'lucide-react/dist/esm/icons/history.mjs'
 import Info from 'lucide-react/dist/esm/icons/info.mjs'
 import Lock from 'lucide-react/dist/esm/icons/lock.mjs'
 import MessageSquare from 'lucide-react/dist/esm/icons/message-square.mjs'
@@ -57,6 +58,7 @@ const ICONS = {
   refresh: RotateCw,
   activity: Clock,
   clock: Clock,
+  history: History,
   about: Info,
   info: Info,
   lock: Lock,
@@ -226,6 +228,7 @@ export const SyncIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name=
 export const RefreshIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="refresh" {...p} />
 export const ActivityIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="activity" {...p} />
 export const ClockIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="clock" {...p} />
+export const HistoryIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="history" {...p} />
 export const AboutIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="about" {...p} />
 export const MessageIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="message" {...p} />
 export const PencilIcon = (p: Omit<IconProps, 'name'>): JSX.Element => <Icon name="pencil" {...p} />