dsh-config-manager 0.1.78 → 0.1.80

package/src/profiles/dsh-profile-launcher.ts

@@ -9,6 +9,9 @@
  * 生态里的做法同样如此（dsh-profile-manager 的 `dshm start`、DSH Launcher 的桌面启动器），
  * 都是「由启动器 spawn 一个实例」；本模块把这件事做进插件：
  * web 形态档案 → detached 子进程 + 自动挑空闲端口 + 从启动日志里抓认证 URL + HTTP 探活。
+ * 子进程必须**直启**（node/Electron-as-node 跑 `bin.js`）：Windows 上经 `.cmd` 包装脚本
+ * （`shell: true` 或中间 cmd 层）再 `detached: true` 会丢掉孙进程的 stdout/stderr，
+ * 日志文件恒 0 字节 ⇒ 永远抓不到 `dsh web: <带 token 的 URL>`（真机实测，见 findCliEntryForShim）。
  *
  * 设计约束：
  *  - 只消费 DSH 的稳定表面（启动参数 + 启动日志里的 `dsh web:` 行），不 import 任何
@@ -173,7 +176,18 @@ export function defaultResolveCli(): DshCliCommand | null {
     }
     return null
   }
-  return { command: fromPath, prefixArgs: [], shell: /\.(cmd|bat)$/i.test(fromPath) }
+  const needsShell = /\.(cmd|bat)$/i.test(fromPath)
+  // Windows 的 .cmd/.bat 只能经 shell 起，而「中间 cmd 层 + detached」会吞掉孙进程的
+  // stdio（日志恒 0 字节 ⇒ 永远抓不到带 token 的 URL）。能反解出真入口就直接跑，
+  // 只有反解不出来时才退回包装脚本（那时日志里没有 URL，UI 会如实报 urlNotFound）。
+  if (needsShell) {
+    const entry = findCliEntryForShim(fromPath)
+    if (entry !== null) {
+      const runner = resolveDirectCliRunner()
+      return { command: runner.command, prefixArgs: [entry], shell: false, env: runner.env }
+    }
+  }
+  return { command: fromPath, prefixArgs: [], shell: needsShell }
 }
 
 /** bin.js 是否属于 @deepseek-ai/dsh（读上一级的 package.json.name）。 */
@@ -199,6 +213,47 @@ function findOnPath(names: readonly string[]): string | null {
   return null
 }
 
+/**
+ * 直启 bin.js 用的运行时：宿主是 Electron 时必须以 `ELECTRON_RUN_AS_NODE=1` 当 node 用
+ * （桌面端宿主 `process.execPath` 是 DeepSeek Harness.exe，真机实测可正常跑 CLI）。
+ */
+export function resolveDirectCliRunner(versions: Readonly<Record<string, string | undefined>> = process.versions): { command: string; env?: Readonly<Record<string, string>> } {
+  if (versions['electron'] !== undefined) return { command: process.execPath, env: { ELECTRON_RUN_AS_NODE: '1' } }
+  return { command: process.execPath }
+}
+
+/**
+ * 从 PATH 上的 dsh 包装脚本反解真正的 CLI 入口（`.../@deepseek-ai/dsh/lib/bin.js`）。
+ *
+ * 为什么必须反解（真机实测根因）：Windows 上 `.cmd/.bat` 只能经 shell 起，而
+ * **中间 cmd 层 + `detached: true` 会丢掉孙进程的 stdout/stderr** ——
+ * `dsh.cmd --version` 经 detached 起时日志恒 0 字节（非 detached 正常），
+ * 于是启动器永远读不到 `dsh web: <带 token 的 URL>` 那行，用户只看到
+ * 「20 秒内未确认就绪 / 没能抓到带 token 的 URL」。直启 bin.js 则正常（约 8 秒出 URL）。
+ *
+ * 先按 npm/pnpm 的常见布局找同目录 `node_modules`，再退回脚本内嵌的入口路径。
+ */
+export function findCliEntryForShim(shimPath: string): string | null {
+  const dir = dirname(shimPath)
+  const candidates = [
+    join(dir, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js'),      // npm 全局前缀（dsh.cmd 同目录）
+    join(dir, '..', 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js'), // <prefix>/bin/dsh.cmd
+    join(dir, '..', '..', 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js'),
+    join(dir, '..', '@deepseek-ai', 'dsh', 'lib', 'bin.js'),                // pnpm <store>/.bin/dsh.cmd
+  ]
+  for (const candidate of candidates) {
+    if (isDshBinPath(candidate)) return candidate
+  }
+  const text = readTextSafe(shimPath)
+  if (text === null) return null
+  // 脚本内嵌路径可能是相对当前目录的（`%dp0%\node_modules\…`）也可能是 `..\node_modules\…`，
+  // 故把可选的前导相对段一起抓下来，再按 shim 所在目录解析。
+  const embedded = /(?:\.\.[\\/]|[.][\\/])?node_modules[\\/]+@deepseek-ai[\\/]+dsh[\\/]+lib[\\/]+bin\.js/iu.exec(text)
+  if (embedded === null) return null
+  const resolved = join(dir, embedded[0])
+  return isDshBinPath(resolved) ? resolved : null
+}
+
 /** 档案 → 是否可启动（唯一判据在 shared，UI 与本模块共用）。 */
 export { isLaunchableShape }
 

package/src/profiles/dsh-profile-shared.ts

@@ -144,8 +144,14 @@ export type DshProfileStopOutcome = 'graceful' | 'killed' | 'already-stopped'
 /** 启动回执里的非致命告警码。 */
 export type DshProfileLaunchWarning = 'notReady' | 'urlNotFound'
 
-/** 等待新实例就绪的上限（宿主探活默认值；UI 文案引用同一常量，避免两处各写一个数字）。 */
-export const DSH_PROFILE_LAUNCH_TIMEOUT_MS = 20_000
+/**
+ * 等待新实例就绪的上限（宿主探活默认值；UI 文案引用同一常量，避免两处各写一个数字）。
+ *
+ * 真机口径（web 档案）：端口约 3 秒就 LISTENING，但带 token 的 URL 要等 dsh 把整棵插件树
+ * settle 完 + startup audit 走完才打印，实测 8–10 秒，插件多的档案会更久（有过 >20 秒的样本）。
+ * 20 秒会把「慢但成功」误判成未就绪，故放宽到 30 秒。
+ */
+export const DSH_PROFILE_LAUNCH_TIMEOUT_MS = 30_000
 
 /** GET /profiles 的响应负载（列表 + 当前运行 + 运行中实例 + 模板清单）。 */
 export interface DshProfilesSnapshot {

package/src/routes/foreign.ts

@@ -17,7 +17,8 @@
  *  ② **不做导入**：本路由只产包，**绝不**触碰 $DSH_HOME 下的配置。导入仍由既有
  *     /analyze → /plan → /execute 完成（导入前快照、冲突判定、dry-run 全部自动生效）；
  *  ③ **凭据值绝不进响应**：只回 skipped 机器码 + 凭据**引用名**（值在转换层就已被剥离，
- *     见 src/foreign/types.ts 的不变量①）；
+ *     见 src/foreign/types.ts 的不变量①）；溯源块（origin：来源标识 / 位置 / 项目根 / 插件元数据 /
+ *     跳过聚合 / 凭据引用名）同样**只含标识与计数**，绝无任何配置值；
  *  ④ **空结果不静默成功**：一个分区都产不出来 → 400 + 稳定码（与 CLI 的退出码 1 同口径），
  *     否则用户会拿到一个自检通过却什么都没有的包。
  *
@@ -217,6 +218,12 @@ export function foreignRoutes(env: RoutesEnv): WebRoute[] {
         skipped: result.skipped,
         // 凭据只给**引用名**（形如 mcp:gitnexus:GITHUB_TOKEN）：导入后由用户在 DSH 里补录
         credentialRefs: result.credentialRefs,
+        /**
+         * 溯源块（**additive**）：来源标识 / 读取位置 / 项目根 / 插件元数据 / 跳过聚合 /
+         * 凭据引用名 —— 界面据此让用户核对「这包从哪来」（同一位也写进 manifest.foreign）。
+         * 翻译层没给 origin 时该键**不出现**（JSON.stringify 丢弃 undefined）⇒ 旧响应逐字不变。
+         */
+        origin: result.origin,
         /** 检测到的本机位置（相对 home），供界面显示「从哪儿读的」 */
         detectedPaths: detection.paths,
         conflictPolicy: FOREIGN_CONFLICT_POLICY,

package/src/routes/index.ts

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

package/src/routes/kit.ts

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

package/src/routes/sync.ts

@@ -45,12 +45,13 @@ import { REVIEW_KINDS, ROUTE_TIMEOUT_MS, SYNC_CREDENTIAL_REF, SYNC_WEBDAV_CREDEN
 import { GitHubApiError } from '../market/github-repos.ts'
 import type { SectionId } from '../schema/types.ts'
 import { redact } from '../security/redaction.ts'
-import { readAutosyncConfig, writeAutosyncConfig } from '../sync/autosync-config.ts'
+import { shouldRunOnEnable, readAutosyncConfig, writeAutosyncConfig, clampRemoteCheckMs, clearLastRunResult } from '../sync/autosync-config.ts'
 import { isValidExportFileName } from '../sync/backup-files.ts'
 import { DeviceFlowStore } from '../sync/github-auth.ts'
 import { channelOf, clearSyncChannel, isWebDavConfig, listCloudConfiguredProviders, parseSyncChannel, readFullSyncConfig, writeSyncConfig, gistChannelView, s3ChannelView, cloudSecretRef, S3_COMPAT_PROVIDERS, GIST_PROVIDER } from '../sync/sync-config.ts'
 import type { CloudS3ChannelView, CloudGistChannelView, CloudSecretWriter, FullSyncConfig, SyncConfig, SyncTransportType } from '../sync/sync-config.ts'
 import { SyncEngine } from '../sync/sync-engine.ts'
+import { isProbeUnsupported } from '../sync/transport.ts'
 import type { ApplyItemsReport } from '../sync/sync-engine.ts'
 import { readSyncHistory } from '../sync/sync-history.ts'
 import { SYNC_SELECTION_SCHEMA_VERSION, normalizeSessionsInclude, normalizeSessionsLimit, writeSyncSelection } from '../sync/sync-selection.ts'
@@ -137,6 +138,50 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
     set: async (ref, value) => { await credentials.set(credentialRef(ref), value) },
     has: async (ref) => (await credentials.describe(credentialRef(ref))).configured,
   }
+  /**
+   * T-ui-merge：合并预览 / 合并执行共用的引擎选项。
+   *
+   * 解密密码口径与 /sync/sync 完全一致：请求体优先，其次已保存的 DECRYPT 凭据
+   * （syncPasswordRef('DECRYPT', channel)）。密码只存在于内存，绝不写进响应 / 日志 / 同步文件；
+   * 明文快照根本不会被解密（引擎只在 manifest.encrypted 时才用密码）。
+   */
+  const mergeEngineOptions = async (
+    body: Record<string, unknown>,
+    syncCfg: SyncConfig,
+  ): Promise<{ snapshotId?: string; password?: string; pathMappings?: PathMapping[] }> => {
+    const snapshotId = typeof body['snapshotId'] === 'string' && body['snapshotId'] !== '' ? body['snapshotId'] : undefined
+    const savedDecryptPassword = await resolveSyncPassword(syncPasswordRef('DECRYPT', channelOf(syncCfg)))
+    const decryptPassword = typeof body['decryptPassword'] === 'string' && body['decryptPassword'] !== ''
+      ? body['decryptPassword']
+      : savedDecryptPassword
+    const pathMappings = extractPathMappings(body)
+    return {
+      ...(snapshotId === undefined ? {} : { snapshotId }),
+      ...(decryptPassword === undefined ? {} : { password: decryptPassword }),
+      ...(pathMappings.length === 0 ? {} : { pathMappings }),
+    }
+  }
+  /**
+   * 合并裁决清单解析（T-ui-merge）。**粒度 = 分区 id**（冻结口径，不做 'id::path' 复合 id）。
+   *
+   * 非法条目直接丢弃 —— 引擎按「未裁决」处理，该分区进 pendingConflicts，界面会如实显示；
+   * 这样既不需要新增宿主文案键，也不会因为客户端字段拼错而静默写坏别的分区。
+   */
+  const extractMergeResolutions = (body: Record<string, unknown>): Array<{ id: SectionId; action: 'keepLocal' | 'useRemote' | 'useMerged' | 'skip' }> => {
+    const raw = body['resolutions']
+    if (!Array.isArray(raw)) return []
+    const out: Array<{ id: SectionId; action: 'keepLocal' | 'useRemote' | 'useMerged' | 'skip' }> = []
+    for (const entry of raw) {
+      if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) continue
+      const rec = entry as Record<string, unknown>
+      const id = rec['id']
+      const action = rec['action']
+      if (typeof id !== 'string' || id === '') continue
+      if (action !== 'keepLocal' && action !== 'useRemote' && action !== 'useMerged' && action !== 'skip') continue
+      out.push({ id: id as SectionId, action })
+    }
+    return out
+  }
   return [
     // ------------------------------------------------------ sync/status
     // m-sync-ui：同步状态（通道配置 / 凭据状态 / 上次同步 / 分区数）。只读，无 secret 值。
@@ -165,7 +210,8 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           : undefined
         // 云端点配置视图（只回 secretStored 布尔；与当前通道无关，配置过即回填）
         const cloud = await cloudChannelViews(full, credentials)
-        // issue #79：git 工作副本是否已跟随 repoUrl（只读自检，2 条本地只读 git 命令）。
+        // issue #79 / #104 建议 3：git 工作副本是否已跟随 repoUrl，外加「领先远端提交数 /
+        // 远端快照数」（只读自检；后者是「本地一直没真正备份」的预警依据）。
         // 读不出来时**如实回传错误**（workDirError），不让状态接口静默少一块信息。
         const gitRepoUrl = full?.git?.repoUrl ?? ''
         let workDir: Awaited<ReturnType<typeof syncWorkDir.inspect>> | null = null
@@ -185,6 +231,9 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
           // 已保存的云端点 provider 清单（切换 provider 时回填用；只有名字，无任何值）
           cloudSavedProviders: await listCloudConfiguredProviders(syncDir),
           lastSyncAt: state.lastSyncAt === '' ? undefined : state.lastSyncAt,
+          // 方案 A（同步页按钮瘦身）：是否存在同步基线（本地祖先指针）。**只回布尔，绝不回快照 id** ——
+          // 界面据此在「有基线 → 三方裁决视图 / 无基线 → 导入确认」之间分派；缺省 undefined 按无基线处理。
+          hasBaseline: state.lastSnapshotId !== '',
           sectionCount: Object.keys(state.sections).length,
           lastTransport: state.transport,
           // 上次选择的同步通道（磁盘 ui-prefs；UI 回填优先于此，localStorage 仅兜底）
@@ -209,9 +258,11 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
       }
     }),
     // ------------------------------------------------------ sync/workdir/reset
-    // issue #79：工作副本的自救入口（改造前 App 内完全没有 —— 改了仓库地址只能手工
-    // git remote set-url，或删掉 <dataDir>/sync/work 重来）。两种模式，破坏性清清楚楚：
+    // issue #79 / #104：工作副本的自救入口（改造前 App 内完全没有 —— 改了仓库地址只能手工
+    // git remote set-url，或删掉 <dataDir>/sync/work 重来）。三种模式，破坏性清清楚楚：
     //   relink  = 只把 origin / push URL 重指向当前配置地址（非破坏性：不碰工作树与本地提交）；
+    //   adopt   = 把远端分支合并进现有工作副本（issue #104：换成另一个仓库、或远端历史被重写后
+    //             两条历史不相交，pull --ff-only 永远失败）；不改写任何本地提交，可 revert；
     //   reclone = 删除工作副本目录后重新 clone（**丢弃未上行的本地提交**）→ 必须显式 confirm。
     // 写动作 → 过 mutation gate（SAFE MODE / 环境锁）；删除边界见 GitTransport.rebuildWorkDir
     // （目录非空且无 .git 一律拒绝，绝不删来路不明的目录）。
@@ -219,8 +270,10 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
       try {
         const body = await requireJsonObject(req)
         const mode = body['mode'] === undefined ? 'relink' : body['mode']
-        if (mode !== 'relink' && mode !== 'reclone') {
-          writeJson(res, 400, { error: msg('sync.workdirModeInvalid', { mode: JSON.stringify(body['mode']) }) })
+        if (mode !== 'relink' && mode !== 'adopt' && mode !== 'reclone') {
+          // 用追加键（含三种模式）而不是既有的 sync.workdirModeInvalid：后者有冻结指纹，
+          // 只列出了两种模式，继续用会把「adopt 也合法」说反。
+          writeJson(res, 400, { error: msg('sync.workdirModeInvalidFull', { mode: JSON.stringify(body['mode']) }) })
           return
         }
         if (mode === 'reclone' && body['confirm'] !== true) {
@@ -657,6 +710,39 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
         writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
       }
     }),
+    // ------------------------------------------------------ sync/probe
+    // cloud-sync 借鉴项 ②：**只读**连通性自检（凭据 / 端点 / 目标容器 / 目录可达），
+    // 供 UI「测试连接」按钮拿到可直接展示的结论（例如 S3 兼容端点该把 region 填成哪个值）。
+    // 只探**已保存**的通道配置（走与 push/pull 同一条配置路径，绝不拿表单里未保存的值去发请求）。
+    // 远端唯一写副作用 = webdav 幂等 MKCOL 补齐上级目录（那正是它要修的故障：目录不存在）。
+    // 失败一律 200 + ok:false —— 「测试连接」是**预期会失败**的诊断动作，用 5xx 表达会被 UI
+    // 当成基础设施故障；文案由通道层本地化并脱敏后原样带回。
+    endpoint({ path: '/api/dsh-config-manager/sync/probe', methods: ['POST'] }, async (req, res) => {
+      const body = await requireJsonObject(req)
+      try {
+        const syncCfg = await prepareSync(body)
+        const engine = makeSyncEngine(syncCfg, { optInSections: selectionOptInSections(channelOf(syncCfg)) })
+        const result = await engine.probe()
+        writeJson(res, 200, {
+          ok: true,
+          transport: channelOf(syncCfg),
+          message: result.message,
+          ...(result.hint !== undefined ? { hint: result.hint } : {}),
+          ...(result.snapshotCount !== undefined ? { snapshotCount: result.snapshotCount } : {}),
+          ...(result.createdCollections !== undefined && result.createdCollections.length > 0
+            ? { createdCollections: result.createdCollections }
+            : {}),
+        })
+      } catch (error) {
+        // 「该通道不提供自检」是**能力边界**（git 通道按 fast-forward 语义自证），不是故障：
+        // 用稳定错误码标记，界面据此按中性提示渲染，绝不显示成「操作失败」。
+        writeJson(res, 200, {
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+          ...(isProbeUnsupported(error) ? { unsupported: true } : {}),
+        })
+      }
+    }),
     // ------------------------------------------------------ sync/download
     // 「拉取即导入」：把远端快照**落地成本机 ZIP** 并返回路径，供导入向导消费。
     // 与 /sync/pull 的分工：pull 只做只读差异预览（临时 ZIP 用完即删）；
@@ -741,6 +827,15 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
             sectionCount: m.manifest.sectionIds.length,
             platform: m.manifest.platform,
             dshVersion: m.manifest.dshVersion,
+            // cloud-sync 借鉴项 ⑥：**推送方设备身份**（写在快照 manifest 里；旧快照没有 → 字段不出现）。
+            // 只回名字与稳定 id（都是本机自己写上去的展示信息，非秘密）；缺字段时绝不回空串占位，
+            // 让界面能如实区分「旧快照没有这个字段」与「设备名是空的」。
+            ...(typeof m.manifest.deviceName === 'string' && m.manifest.deviceName !== ''
+              ? { deviceName: m.manifest.deviceName }
+              : {}),
+            ...(typeof m.manifest.deviceId === 'string' && m.manifest.deviceId !== ''
+              ? { deviceId: m.manifest.deviceId }
+              : {}),
           }))
         const state = await loadSyncState(syncDir)
         // issue #59：把「远端有但读不出来」的快照如实回传（绝不静默跳过）——
@@ -965,7 +1060,8 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
       }
     }),
     // ------------------------------------------------------ sync/autosync
-    // m-sync-v2：自动同步配置读写（按通道：git/webdav 各自的开关 + 间隔 + 启动阈值 + 状态）。
+    // m-sync-v2：自动同步配置读写（按通道：开关 + 兜底间隔 + 启动阈值 + realtime 监听/远端轮询
+    // + 自动应用等级 + 冲突策略 + 运行状态）。
     // GET = 读全部通道状态（{ git, webdav }）；POST = 写指定通道（body.transport，缺省 git）。
     // 同一路径注册为一个 exact 路由（方法内部分发），避免 webserver 对重复 exact 路径报错。
     endpoint({ path: '/api/dsh-config-manager/sync/autosync', methods: ['GET', 'POST'] }, async (req, res) => {
@@ -982,13 +1078,41 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
         // 按通道读写：git/webdav 各自的自动同步配置与运行状态独立（缺省 git 兜底）
         const channel: SyncTransportType = parseSyncChannel(body['transport']) ?? 'git'
         const cfg = await readAutosyncConfig(syncDir, channel)
+        // 「这次 POST 是不是把开关从关拨到开」必须在覆盖字段之前拍下来（issue #105 建议 4）
+        const wasEnabled = cfg.enabled
         if (typeof body['enabled'] === 'boolean') cfg.enabled = body['enabled']
         if (typeof body['interval'] === 'string' && isAutosyncInterval(body['interval'])) cfg.interval = body['interval']
         if (typeof body['startupMinIntervalMs'] === 'number' && Number.isFinite(body['startupMinIntervalMs']) && body['startupMinIntervalMs'] > 0) {
           cfg.startupMinIntervalMs = body['startupMinIntervalMs']
         }
-        await writeAutosyncConfig(syncDir, channel, cfg)
-        if (scheduler) scheduler.reload().catch(() => { /* 尽力而为 */ })
+        // 真·自动同步：本地改动即时触发开关 + 远端轮询节奏（非法值一律忽略，绝不写 NaN）
+        if (typeof body['realtime'] === 'boolean') cfg.realtime = body['realtime']
+        if (typeof body['remoteCheckMs'] === 'number' && Number.isFinite(body['remoteCheckMs'])) {
+          cfg.remoteCheckMs = clampRemoteCheckMs(body['remoteCheckMs'])
+        }
+        // 自动应用等级：low = 只自动落低风险分区；medium = plugins/mcp 也自动落盘
+        if (body['autoApplyTier'] === 'low' || body['autoApplyTier'] === 'medium') {
+          cfg.autoApplyTier = body['autoApplyTier']
+        }
+        // 冲突策略：ask = 保留冲突待人工裁决；local = 保留本机并推上去（缺省）
+        if (body['conflictPolicy'] === 'ask' || body['conflictPolicy'] === 'local') {
+          cfg.conflictPolicy = body['conflictPolicy']
+        }
+        // issue #105：这里写的是**配置**，不是一轮运行结果。此前 readAutosyncConfig 读到的
+        // 上一轮 lastRunMessage/lastRunSkipReason 会被原样写回（"坐实"），于是十天前那次失败的
+        // 错误原文会被一次纯改间隔的保存续命，卡片上继续挂着早已不成立的故障。
+        // 现在：配置落盘前清空上一轮结论 —— 配置变更 ≠ 本轮结论。
+        // issue #105 建议 4：勾选开关是「用户刚刚要求它开始工作」，不该只重排定时器、让卡片
+        // 继续显示上一轮（甚至是十天前）的结论。若距上次运行已超过启动阈值，立刻跑一轮。
+        const runNow = shouldRunOnEnable({ enabled: wasEnabled }, cfg)
+        await writeAutosyncConfig(syncDir, channel, clearLastRunResult(cfg))
+        if (scheduler) {
+          scheduler.reload().catch(() => { /* 尽力而为 */ })
+          // 不 await：POST 是配置保存，不能让页面等一次网络同步；结果由调度器自己写进
+          // sync-autosync.json / sync-history.json。并发由 runOnce 的 running 与 runs 全局防重
+          // 挡住（在跑时返回 skipped 而不是排队），所以这里不需要额外门控。
+          if (runNow) void scheduler.runOnce(channel, { reason: 'enable-toggle' }).catch(() => { /* 结果已落状态 */ })
+        }
         writeJson(res, 200, await buildAutosyncStatus(syncDir, channel))
       } catch (error) {
         writeSyncRouteError(res, error)
@@ -1091,5 +1215,48 @@ export function syncRoutes(env: RoutesEnv): WebRoute[] {
         writeJson(res, 500, { error: error instanceof Error ? error.message : String(error) })
       }
     })),
+    // ------------------------------------------------------ sync/merge-preview
+    // T-ui-merge：远程合并**只读**预览（三方合并 + 冲突清单 + 摘要）。
+    // 零写入 ⇒ 不过 mutation gate、也不登记同步会话（临时 ZIP 由引擎内部用完即清）；
+    // 解密密码只走内存，响应体不含任何凭据值。
+    endpoint({ path: '/api/dsh-config-manager/sync/merge-preview', methods: ['POST'] }, async (req, res) => {
+      const body = await requireJsonObject(req)
+      try {
+        const syncCfg = await prepareSync(body)
+        const engine = makeSyncEngine(syncCfg, { optInSections: selectionOptInSections(channelOf(syncCfg)) })
+        const opts = await mergeEngineOptions(body, syncCfg)
+        const preview = await withTimeout(
+          engine.previewMerge(opts),
+          ROUTE_TIMEOUT_MS,
+          msg('host.syncPullTimeout'),
+        )
+        writeJson(res, 200, preview)
+      } catch (error) {
+        writeSyncRouteError(res, error)
+      }
+    }),
+    // ------------------------------------------------------ sync/apply-merge
+    // T-ui-merge：按**分区级**裁决执行合并（写动作 ⇒ mutation gate 'sync-merge-apply'）。
+    // 响应直接透传引擎报告（字段与 /sync/apply-items 同风格）：其中 pendingConflicts =
+    // 执行后仍待裁决的分区 —— skip 不推进同步基线，界面必须如实说明「下次同步仍会出现」。
+    endpoint({ path: '/api/dsh-config-manager/sync/apply-merge', methods: ['POST'] }, withMutationGate('sync-merge-apply', async (req, res, _lockCtx, journalCtx) => {
+      const body = await requireJsonObject(req)
+      try {
+        const syncCfg = await prepareSync(body)
+        const engine = makeSyncEngine(syncCfg, { optInSections: selectionOptInSections(channelOf(syncCfg)) })
+        const resolutions = extractMergeResolutions(body)
+        const opts = await mergeEngineOptions(body, syncCfg)
+        // snapshotBinding：与 /sync/apply-items 同口径把 journal 绑定面交给引擎（审计 P0-23），
+        // restoreId 与事务日志因此同源，异常路径下回滚入口拿到的也是同一份快照。
+        const report = await withTimeout(
+          engine.applyMergeResolutions(resolutions, { ...opts, ...(journalCtx !== undefined ? { snapshotBinding: journalCtx } : {}) }),
+          ROUTE_TIMEOUT_MS,
+          msg('host.syncPullTimeout'),
+        )
+        writeJson(res, 200, report)
+      } catch (error) {
+        writeSyncRouteError(res, error)
+      }
+    })),
   ]
 }

package/src/schema/manifest-schema.test.ts

@@ -13,7 +13,8 @@
  *      发布出去的那份文件；schema 一旦用上未支持的关键字，K-03 会立刻红灯。
  *
  * 覆盖：K-* schema 自身健全性 / S-* 真实 buildManifest 产物契约 / R-* 拒绝路径与
- * validateManifest 逐条一致 / C-* 已知兼容语义（未知分区只 warning）与已记录的语义落差。
+ * validateManifest 逐条一致 / C-* 已知兼容语义（未知分区只 warning）与已记录的语义落差 /
+ * F-* manifest.foreign（外部来源溯源块）的宽容契约（旧包缺省合法、形状不对只 warning）。
  */
 import test from 'node:test';
 import assert from 'node:assert/strict';
@@ -25,7 +26,7 @@ import {
 } from './manifest.ts';
 import { SECTION_IDS } from './config.ts';
 import { CURRENT_SCHEMA_VERSION } from './versions.ts';
-import type { Manifest } from './types.ts';
+import type { Manifest, ManifestForeignOrigin } from './types.ts';
 
 /* ============================================================================
  * (a) 最小 JSON Schema 校验器 —— 只覆盖本 schema 使用的关键字集合
@@ -517,3 +518,87 @@ test('C-07 schemaVersion 的「是否受支持」不属结构校验：schemaVers
   assert.deepEqual(errorPaths(m), [], '实现同样只在版本协商阶段拒绝（规格 §6.2）');
   assert.doesNotThrow(() => parseManifest(JSON.stringify(m)), 'parseManifest 不做版本协商');
 });
+
+/* ============================================================================
+ * F-*：manifest.foreign（外部来源溯源块，2026-10-18 新增）
+ *
+ * 契约：**只允许加严为 warning，绝不拒绝**。
+ *  - 旧包没有该字段 ⇒ 合法（向后兼容是本次改动的第一约束）；
+ *  - 形状/内部字段类型不对 ⇒ 仅 warning，且 parseManifest 不得抛错（否则畸形元数据会
+ *    把一个**内容完全可导入**的包整体挡在门外 —— 元数据永远不该有这种权力）。
+ * ==========================================================================*/
+
+/** 一个字段齐备的合法溯源块（夹具里只有标识与计数，无任何配置值） */
+function validForeign(): Record<string, unknown> {
+  return {
+    agent: 'claude-code',
+    locations: ['.claude.json', '.claude/CLAUDE.md'],
+    sourceVersion: '1.2.3',
+    projects: ['D:/proj/app'],
+    plugins: [
+      { name: 'demo-plugin', version: '1.0.0', marketplace: 'demo-mkt', repo: 'owner/repo', ref: 'main', components: ['skills'] },
+    ],
+    skipped: [{ code: 'unsupported-hooks', count: 2 }],
+    credentialRefs: ['mcp:svc:GITHUB_TOKEN'],
+  };
+}
+
+test('F-01 旧包（无 foreign 键）仍合法：buildManifest 缺省不写该键、零 issue', () => {
+  const m = baselineManifest();
+  assert.equal(
+    Object.prototype.hasOwnProperty.call(m, 'foreign'), false,
+    '未传 foreign 时该键不得出现（DSH 自产备份逐字不变）',
+  );
+  assert.deepEqual(validateManifest(m), [], '无 foreign 的旧 manifest 必须零 issue');
+  assert.deepEqual(validateAgainstSchema(SCHEMA, m), [], 'schema 也不得因此拒绝');
+  assert.doesNotThrow(() => parseManifest(serializeManifest(m)), '旧包解析照旧');
+});
+
+test('F-02 传了 foreign 才写入：原样进 manifest，serialize → parse 往返保留', () => {
+  const foreign = validForeign() as unknown as ManifestForeignOrigin;
+  const m = buildManifest({
+    exporterVersion: '0.1.59',
+    dshVersion: '0.1.0-rc.6',
+    platform: 'win32',
+    arch: 'x64',
+    sections: sectionsAllFalse() as unknown as Manifest['sections'],
+    containsSecrets: false,
+    encrypted: false,
+    encryption: null,
+    exportedAt: '2026-08-14T12:00:00.000Z',
+    foreign,
+  });
+  assert.deepEqual(m.foreign, validForeign(), 'buildManifest 必须原样写入（不裁剪、不补默认值）');
+  assert.deepEqual(validateManifest(m), [], '合法 foreign 不得产生任何 issue');
+  const reparsed = parseManifest(serializeManifest(m));
+  assert.deepEqual(reparsed.foreign, validForeign(), '往返后溯源块逐字保留');
+});
+
+test('F-03 foreign 合法 → 通过（零 error 零 warning），且 schema 不得拒绝该顶层字段', () => {
+  const m = mutate({ foreign: validForeign() });
+  assert.deepEqual(errorPaths(m), [], '合法 foreign 不得有 error');
+  assert.deepEqual(validateManifest(m), [], '合法 foreign 不得有 warning');
+  assert.deepEqual(schemaPaths(m), [], 'schema 对未声明的顶层字段保持开放（不得因此拒绝）');
+});
+
+test('F-04 foreign 存在但形状/字段类型不对 → 只 warning、绝不 error、parseManifest 不抛错', () => {
+  const cases: [string, unknown][] = [
+    ['不是对象（字符串）', 'claude-code'],
+    ['null', null],
+    ['数组', []],
+    ['缺 agent', { locations: ['.claude.json'] }],
+    ['agent 类型错', { agent: 42 }],
+    ['locations 元素非字符串', { agent: 'x', locations: ['.a', 7] }],
+    ['sourceVersion 类型错', { agent: 'x', sourceVersion: 1 }],
+    ['projects 不是数组', { agent: 'x', projects: 'D:/proj' }],
+    ['credentialRefs 元素非字符串', { agent: 'x', credentialRefs: [{ ref: 'a' }] }],
+    ['skipped 缺 count', { agent: 'x', skipped: [{ code: 'unsupported-hooks' }] }],
+    ['plugins 元素缺 name', { agent: 'x', plugins: [{ version: '1.0.0' }] }],
+  ];
+  for (const [name, value] of cases) {
+    const m = mutate({ foreign: value });
+    assert.deepEqual(errorPaths(m), [], `[${name}] foreign 绝不允许产生 error`);
+    assert.deepEqual(warningPaths(m), ['foreign'], `[${name}] 必须恰好一条 foreign warning（不逐字段刷屏）`);
+    assert.doesNotThrow(() => parseManifest(JSON.stringify(m)), `[${name}] 畸形容器不得阻断解析`);
+  }
+});

package/src/schema/manifest.ts

@@ -4,7 +4,7 @@
  */
 import { parseJsonSafe } from '../utils/json.ts';
 import { CURRENT_SCHEMA_VERSION } from './versions.ts';
-import type { Manifest, Platform, SectionId } from './types.ts';
+import type { Manifest, ManifestForeignOrigin, Platform, SectionId } from './types.ts';
 import { SECTION_IDS } from './config.ts';
 import { schemaMsg } from './messages.ts';
 
@@ -24,6 +24,11 @@ export interface BuildManifestInput {
   exportedAt?: string; // 测试可注入固定时间
   /** 导出机的 DSH home（可选；见 Manifest.sourceHome，用于跨机基础路径重定基） */
   sourceHome?: string;
+  /**
+   * 外部来源包的溯源块（可选；见 Manifest.foreign）。
+   * **只有显式传入时才写入** —— 缺省不产生该键，DSH 自产备份与旧包逐字不变。
+   */
+  foreign?: ManifestForeignOrigin;
 }
 
 /** 构造 manifest（schemaVersion 恒为当前版本，集中于此） */
@@ -38,6 +43,7 @@ export function buildManifest(input: BuildManifestInput): Manifest {
     },
     exportedAt: input.exportedAt ?? new Date().toISOString(),
     ...(input.sourceHome !== undefined && input.sourceHome !== '' ? { sourceHome: input.sourceHome } : {}),
+    ...(input.foreign !== undefined ? { foreign: input.foreign } : {}),
     sections: input.sections,
     security: {
       containsSecrets: input.containsSecrets,
@@ -65,6 +71,53 @@ export function parseManifest(raw: string): Manifest {
 
 export interface ManifestIssue { path: string; message: string; severity: 'error' | 'warning'; }
 
+/**
+ * `manifest.foreign`（外部来源溯源块）的**宽容校验**。
+ *
+ * 铁律：本字段**绝不允许**成为拒绝一个包的理由 —— 旧包没有它、新包可能带畸形值，
+ * 两者都必须能继续导入。因此这里只产出 `warning`，且**只落一条**汇总（路径恒为 `foreign`），
+ * 出错字段名以机器码形式列在文案参数里（不逐字段刷屏、不新增用户可见文案）。
+ */
+function validateForeignOrigin(value: unknown): ManifestIssue[] {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return [{
+      path: 'foreign',
+      message: schemaMsg('schema.sectionDataInvalid', { section: 'manifest.foreign', issues: 'not-an-object' }),
+      severity: 'warning',
+    }];
+  }
+  const f = value as Record<string, unknown>;
+  const bad: string[] = [];
+  if (typeof f['agent'] !== 'string') bad.push('agent');
+  if (f['locations'] !== undefined && !isStringArray(f['locations'])) bad.push('locations');
+  if (f['sourceVersion'] !== undefined && typeof f['sourceVersion'] !== 'string') bad.push('sourceVersion');
+  if (f['projects'] !== undefined && !isStringArray(f['projects'])) bad.push('projects');
+  if (f['credentialRefs'] !== undefined && !isStringArray(f['credentialRefs'])) bad.push('credentialRefs');
+  if (f['skipped'] !== undefined && !isSkippedAggregates(f['skipped'])) bad.push('skipped');
+  if (f['plugins'] !== undefined && !isPluginSummaries(f['plugins'])) bad.push('plugins');
+  if (bad.length === 0) return [];
+  return [{
+    path: 'foreign',
+    message: schemaMsg('schema.sectionDataInvalid', { section: 'manifest.foreign', issues: bad.join(',') }),
+    severity: 'warning',
+  }];
+}
+
+function isStringArray(value: unknown): boolean {
+  return Array.isArray(value) && value.every((v) => typeof v === 'string');
+}
+
+function isSkippedAggregates(value: unknown): boolean {
+  return Array.isArray(value) && value.every((v) => v !== null && typeof v === 'object'
+    && typeof (v as Record<string, unknown>)['code'] === 'string'
+    && typeof (v as Record<string, unknown>)['count'] === 'number');
+}
+
+function isPluginSummaries(value: unknown): boolean {
+  return Array.isArray(value) && value.every((v) => v !== null && typeof v === 'object'
+    && typeof (v as Record<string, unknown>)['name'] === 'string');
+}
+
 /** 结构校验：字段类型 / sections 键集合 / security 形状 */
 export function validateManifest(m: unknown): ManifestIssue[] {
   const issues: ManifestIssue[] = [];
@@ -124,5 +177,8 @@ export function validateManifest(m: unknown): ManifestIssue[] {
     }
   }
 
+  // foreign 是**外部来源包**的溯源块：缺省 = 旧包（合法）；形状/字段类型不对 = 仅 warning（绝不拒绝）。
+  if (obj['foreign'] !== undefined) issues.push(...validateForeignOrigin(obj['foreign']));
+
   return issues;
 }