dsh-config-manager 0.1.86 → 0.2.1

package/src/core/path-browse.ts

@@ -0,0 +1,166 @@
+/**
+ * 本机目录列举（宿主半）—— 「路径映射 → 选择本机路径」弹窗的唯一数据源。
+ *
+ * 为什么要有它
+ * ------------
+ * 导入向导的路径映射要求用户为一堆**绝对路径**指定本机新位置，而此前只能凭记忆手打
+ * （浏览器拿不到真实路径：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
+
+/** 列举失败的原因码（客户端按它选字典键）。 */
+export type BrowseErrorCode = 'not-found' | 'denied' | 'failed' | 'not-absolute'
+
+/** 一条条目：目录（可进入）或文件（可选中）。 */
+export interface BrowseEntry {
+  /** 末段名字（驱动器根即盘符本身，如 `D:\\`）。 */
+  name: string
+  /** 绝对路径（客户端原样回填输入框）。 */
+  path: string
+  kind: 'dir' | 'file'
+}
+
+/** 列举结果。 */
+export interface BrowseResult {
+  /** 当前列出的目录；空串 = 「此电脑」（Windows 的盘符根列表）。 */
+  path: string
+  /** 上一级；已是根时为 null。 */
+  parent: string | null
+  /** 用户主目录（界面上的快捷入口；不随 path 变化）。 */
+  home: string
+  entries: BrowseEntry[]
+  /** 命中 {@link BROWSE_ENTRY_LIMIT} 被截断。 */
+  truncated: boolean
+  /** 失败原因码；成功为 null。 */
+  error: BrowseErrorCode | null
+}
+
+/** 带硬超时的 Promise（只为本模块的盘符探测服务；超时后原 promise 的迟到结果被丢弃）。 */
+function withDeadline<T>(promise: Promise<T>, ms: number): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => { reject(new Error('timeout')) }, ms)
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value) },
+      (error: unknown) => { clearTimeout(timer); reject(error) },
+    )
+  })
+}
+
+/** 一个路径是不是「根」（Windows 盘符根 / POSIX 的 `/`）。 */
+function isRoot(target: string): boolean {
+  return parse(target).root === target
+}
+
+/**
+ * 本机根列表：Windows 上是**探测得到的**盘符根（不硬编码 C:），其余平台是 `/`。
+ * 探测逐根 400ms 超时；全部失败时至少给出 `parse(process.cwd()).root`，界面不至于空成白板。
+ */
+export async function listRoots(): Promise<BrowseEntry[]> {
+  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 is string => 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: unknown): BrowseErrorCode {
+  const code = (error as { code?: unknown } | null)?.code
+  if (code === 'ENOENT' || code === 'ENOTDIR') return 'not-found'
+  if (code === 'EACCES' || code === 'EPERM') return 'denied'
+  return 'failed'
+}
+
+/** 名字排序：目录在前、同类按名字字典序（不依赖 locale，测试可复现）。 */
+function compareEntries(a: BrowseEntry, b: BrowseEntry): number {
+  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: string | undefined,
+  options?: { limit?: number },
+): Promise<BrowseResult> {
+  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: BrowseEntry[] = []
+  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,
+  }
+}

package/src/foreign/claude-sessions.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';
@@ -195,7 +195,7 @@ export interface TranscodeResult {
 interface ParsedBlock {
   /**
    * `thinking` = 推理块（Claude Code 的 `thinking` / `redacted_thinking`）：共享 IR 的 `IrBlock`
-   * **没有 reasoning 承载位**（docs/spec/known-gaps.md F-01），所以它既不进 IR 也不伪装成正文，
+   * **没有 reasoning 承载位**（docs/maintenance/known-gaps.md F-01），所以它既不进 IR 也不伪装成正文，
    * 只**逐条计数**（ignored['thinking']）。判定口径与「`reasoning` 为何不在此列」见
    * `REASONING_BLOCK_TYPES` 的注释。
    */
@@ -219,7 +219,7 @@ function usageField(usage: unknown, key: string): unknown {
  * 沿「对象带 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/src/index.ts

@@ -180,7 +180,7 @@ export const name = 'config-manager'
 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.1'
 
 /** Plugin own package name — excluded from its own exported plugins list. */
 const PLUGIN_NAME = 'dsh-config-manager'
@@ -245,7 +245,7 @@ export interface Config {
 /**
  * 本文件保留的 7 条路由的路径（被源码级守卫按文件窗口钉住，见下方 routesList 注释）。
  *
- * 其余 75 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
+ * 其余 76 条路由的路径**声明在各自的组文件里**（src/routes/*.ts 的 endpoint({ path, methods })）——
  * 新增一条 API 只需那一条声明，不再有「常量表 + 路由对象」两处要同步。
  */
 export const API = {
@@ -3350,7 +3350,7 @@ function makeRoutes(deps: RoutesDeps): { routes: WebRoute[]; scheduler: AutoSync
   /**
    * 路由表：本文件只保留被源码级守卫按**文件窗口**钉住的 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: RouteEnvInferred = makeRouteEnv()

package/src/market/security.ts

@@ -128,7 +128,7 @@ export function validateMarketItem(
   for (const [sectionId, enabled] of Object.entries(internalManifest.sections) as [SectionId, boolean][]) {
     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/src/market/types.ts

@@ -31,7 +31,7 @@ export type MarketPublishMode = 'migrate' | 'share';
 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/src/routes/index.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'
@@ -20,6 +20,7 @@ import { meRoutes } from './me.ts'
 import { historyRoutes } from './history.ts'
 import { recoveryRoutes } from './recovery.ts'
 import { sessionExportRoutes } from './session-export.ts'
+import { pathBrowseRoutes } from './path-browse.ts'
 
 export function buildRoutes(env: RoutesEnv): WebRoute[] {
   return [
@@ -36,5 +37,6 @@ export function buildRoutes(env: RoutesEnv): WebRoute[] {
     ...historyRoutes(env),
     ...recoveryRoutes(env),
     ...sessionExportRoutes(env),
+    ...pathBrowseRoutes(env),
   ]
 }

package/src/routes/kit.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/src/routes/path-browse.ts

@@ -0,0 +1,70 @@
+/**
+ * 路由组：本机路径浏览（导入向导「路径映射」→ 选择本机路径弹窗的唯一数据源）。
+ *
+ * 为什么需要一条宿主路由：浏览器拿不到用户机器的真实目录树（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.ts'
+import type { WebRoute } from './kit.ts'
+import type { RoutesEnv } from './context.ts'
+import { browseDirectory } from '../core/path-browse.ts'
+import { pickNativeDirectory } from '../core/native-path-picker.ts'
+import { withTimeout } from './route-support.ts'
+
+/** 单次列举的整体时限：正常目录远快于此；网络盘悬挂时宁可报错也不让请求挂着。 */
+const BROWSE_TIMEOUT_MS = 10_000
+
+/** POST 可透传文本的长度上限：只用来当对话框的**起点**与**标题**，都不该是长文本。 */
+const PICK_TEXT_MAX = 512
+
+/** 取请求体里的短文本字段：非字符串/空串/超长一律视为未提供（对话框走缺省值，不报错）。 */
+function pickText(body: Record<string, unknown> | undefined, key: string): string | undefined {
+  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: RoutesEnv): WebRoute[] {
+  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) })
+      }
+    }),
+  ]
+}

package/src/security/secret-scanner.test.ts

@@ -5,7 +5,7 @@
  * 这类**合法**（RFC 7235 / 6750：auth-scheme 名大小写不敏感）的授权头在 env / headers / url 通道上
  * 明文进包且**完全不可见**（refs / skipped 皆空）。
  *
- * 两条口径（改这条判定的任何人先读 `docs/spec/known-gaps.md` **G-36**）：
+ * 两条口径（改这条判定的任何人先读 `docs/maintenance/known-gaps.md` **G-36**）：
  *  ① 规范形态 `Bearer …` 的**行为与历史逐字一致**（命中名仍是 `bearer-token`）：本模块只**补**非规范大小写；
  *  ② 厂商前缀（`sk-` / `AKIA` / `ghp_` / `github_pat_`）**刻意保持大小写敏感** —— `SK-…` 不是真实厂商形态，
  *     全改 `i` 会连带放宽整个脱敏面（日志 / 导出 / 界面渲染前 redact），代价大于收益 ⇒ 登记为**已知边界**

package/src/security/secret-scanner.ts

@@ -81,7 +81,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(

package/src/ui/session-issue-labels.ts

@@ -4,7 +4,7 @@
  * 为什么需要它：体检列表此前把内部机器码直接拼上屏（location-mismatch / duplicate-id /
  * missing-message-id / format-newer …），中英用户看到的都是英文枚举 —— 既违反
  * AGENTS.md「禁止硬编码用户可见字符串」，也让用户无法判断这一行到底出了什么问题
- * （已知缺口登记：docs/spec/known-gaps.md 的 G-24 剩余未做项 ③）。
+ * （已知缺口登记：docs/maintenance/known-gaps.md 的 G-24 剩余未做项 ③）。
  *
  * 口径与既有的 sessionLayoutReasonKey / 同步页的 cloudIssueKey 完全一致：
  * **未知码回落 sessions.issue.unknown，绝不裸渲染机器码**。

package/src/ui/sync-settings-view.test.ts

@@ -12,7 +12,7 @@ import test from 'node:test'
 import assert from 'node:assert/strict'
 
 import {
-  workdirBacklog,
+  workdirBacklog, pickSyncPrimary,
   autosyncIntervalKey, buildSelectionRequest, buildSyncChannelBody, buildSyncConfigBody, buildSyncPushBody,
   channelBackfillFromStatus, computeEncryptInvalid, encryptToggle, formatSyncStatusTimestamp,
   formatSyncUrlPreview, githubPollDecision, hasSelectedSections, includeSecretsToggle,
@@ -575,3 +575,20 @@ test('issue #104 建议 3：workdirBacklog —— 本地领先且远端零快照
   // 远端有过快照 ⇒ 只是没推完，语气不同
   assert.deepEqual(workdirBacklog({ facts: { ahead: 3, remoteSnapshots: 5 } }), { kind: 'ahead', ahead: 3, remoteSnapshots: 5 });
 });
+
+test('issue #115：pickSyncPrimary —— 只有远端确证零快照才让「推送到远端」当主按钮', () => {
+  // 远端确实空（自检给出 0）→ 同步无事可做，第一次备份就是上传
+  assert.equal(pickSyncPrimary({ workDir: { facts: { ahead: 0, remoteSnapshots: 0 } } }, 'git'), 'push');
+  assert.equal(pickSyncPrimary({ workDir: { facts: { ahead: 14, remoteSnapshots: 0 } } }, 'git'), 'push', '本地攒着提交 + 远端零快照同样是首次备份');
+  // 远端有快照（哪怕本地领先）→ 回落下行：同步会先合并，不覆盖远端历史
+  assert.equal(pickSyncPrimary({ workDir: { facts: { ahead: 0, remoteSnapshots: 14 } } }, 'git'), 'sync');
+  assert.equal(pickSyncPrimary({ workDir: { facts: { ahead: 3, remoteSnapshots: 5 } } }, 'git'), 'sync');
+  // 没有事实（没走 detail 自检 / 自检失败 / 无状态）→ 一律回落下行，绝不把用户推向推送
+  assert.equal(pickSyncPrimary(undefined, 'git'), 'sync');
+  assert.equal(pickSyncPrimary(null, 'git'), 'sync');
+  assert.equal(pickSyncPrimary({ workDir: { error: 'git not found' } }, 'git'), 'sync');
+  assert.equal(pickSyncPrimary({ workDir: { facts: { ahead: null, remoteSnapshots: null } } }, 'git'), 'sync');
+  // 非 git 通道没有工作副本自检事实 ⇒ 即使 statusInfo 里带了别人的 workDir 也一律下行
+  assert.equal(pickSyncPrimary({ workDir: { facts: { ahead: 0, remoteSnapshots: 0 } } }, 'webdav'), 'sync');
+  assert.equal(pickSyncPrimary({ workDir: { facts: { ahead: 0, remoteSnapshots: 0 } } }, 's3'), 'sync');
+});

package/src/ui/sync-settings-view.ts

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