zen-gitsync 2.17.12 → 2.17.14

package/src/ui/public/index.html

@@ -10,37 +10,36 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Plus+Jakarta+Sans:ital,wght@0,300;0,400;0,500;0,600;0,700;0,800;1,400&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-DGHrUfrh.js"></script>
+    <script type="module" crossorigin src="/assets/index-qAmzFO10.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-C0FnF6B9.js">
-    <link rel="modulepreload" crossorigin href="/assets/element-plus-IG-bwpR5.js">
+    <link rel="modulepreload" crossorigin href="/assets/element-plus-CMSkP_w2.js">
     <link rel="modulepreload" crossorigin href="/assets/monaco-DkJuNcCr.js">
-    <link rel="modulepreload" crossorigin href="/assets/vendor-DcK6TCKZ.js">
-    <link rel="modulepreload" crossorigin href="/assets/_plugin-vue_export-helper-Dcylt9fO.js">
-    <link rel="modulepreload" crossorigin href="/assets/SvgIcon-VCh_kGGV.js">
-    <link rel="modulepreload" crossorigin href="/assets/IconButton-BxRsG5E1.js">
-    <link rel="modulepreload" crossorigin href="/assets/configStore-BlqdtNUA.js">
-    <link rel="modulepreload" crossorigin href="/assets/socket-io-TBtw0msS.js">
-    <link rel="modulepreload" crossorigin href="/assets/gitStore-BKkZm2m3.js">
-    <link rel="modulepreload" crossorigin href="/assets/useThemeObserver-DAWKXvWv.js">
-    <link rel="modulepreload" crossorigin href="/assets/flow-mindmap-C_w8GJXm.js">
-    <link rel="modulepreload" crossorigin href="/assets/previewSandbox-DYMhXJ91.js">
-    <link rel="modulepreload" crossorigin href="/assets/FileDiffViewer-ZD705xXx.js">
-    <link rel="modulepreload" crossorigin href="/assets/toolsStore-BlRHNqXl.js">
-    <link rel="modulepreload" crossorigin href="/assets/CommonDialog-DNnN70HC.js">
-    <link rel="modulepreload" crossorigin href="/assets/TemplateManager-C4go4RZu.js">
-    <link rel="modulepreload" crossorigin href="/assets/vue-flow-B3gZmkCI.js">
-    <link rel="stylesheet" crossorigin href="/assets/element-plus-C1PloHQu.css">
+    <link rel="modulepreload" crossorigin href="/assets/vendor-CZnXb2r9.js">
+    <link rel="modulepreload" crossorigin href="/assets/_plugin-vue_export-helper-BdTxl34g.js">
+    <link rel="modulepreload" crossorigin href="/assets/SvgIcon-CvtoU5yo.js">
+    <link rel="modulepreload" crossorigin href="/assets/IconButton-DysyaC1j.js">
+    <link rel="modulepreload" crossorigin href="/assets/configStore-AQMSazCM.js">
+    <link rel="modulepreload" crossorigin href="/assets/socket-io-BFqQXqAp.js">
+    <link rel="modulepreload" crossorigin href="/assets/gitStore-BgC8OY0k.js">
+    <link rel="modulepreload" crossorigin href="/assets/useThemeObserver-DhCU3SIo.js">
+    <link rel="modulepreload" crossorigin href="/assets/flow-mindmap-CHxAWdLw.js">
+    <link rel="modulepreload" crossorigin href="/assets/previewSandbox-CyuMMYaq.js">
+    <link rel="modulepreload" crossorigin href="/assets/FileDiffViewer-Yas2nO2U.js">
+    <link rel="modulepreload" crossorigin href="/assets/CommonDialog-BiNTGpA-.js">
+    <link rel="modulepreload" crossorigin href="/assets/TemplateManager-saqC9kdQ.js">
+    <link rel="modulepreload" crossorigin href="/assets/vue-flow-7_n4vJqi.js">
+    <link rel="stylesheet" crossorigin href="/assets/element-plus-Dc1iTOWq.css">
     <link rel="stylesheet" crossorigin href="/assets/monaco-B2lPvkrc.css">
     <link rel="stylesheet" crossorigin href="/assets/vendor-4ojsjDYc.css">
-    <link rel="stylesheet" crossorigin href="/assets/SvgIcon-BQ6bR7l0.css">
-    <link rel="stylesheet" crossorigin href="/assets/IconButton-CTwyZrv2.css">
+    <link rel="stylesheet" crossorigin href="/assets/SvgIcon-CDNsk4-Q.css">
+    <link rel="stylesheet" crossorigin href="/assets/IconButton-tjkOjzkC.css">
     <link rel="stylesheet" crossorigin href="/assets/flow-mindmap-DnzM9SlK.css">
-    <link rel="stylesheet" crossorigin href="/assets/previewSandbox-B6Ud9g6a.css">
-    <link rel="stylesheet" crossorigin href="/assets/FileDiffViewer-B2_ghtbv.css">
-    <link rel="stylesheet" crossorigin href="/assets/CommonDialog-C_RjF9Mp.css">
-    <link rel="stylesheet" crossorigin href="/assets/TemplateManager-C0rm8xfC.css">
+    <link rel="stylesheet" crossorigin href="/assets/previewSandbox-CgdwPcuW.css">
+    <link rel="stylesheet" crossorigin href="/assets/FileDiffViewer-B9EkuKdF.css">
+    <link rel="stylesheet" crossorigin href="/assets/CommonDialog-jP0E9mco.css">
+    <link rel="stylesheet" crossorigin href="/assets/TemplateManager-DMuG4i3G.css">
     <link rel="stylesheet" crossorigin href="/assets/vue-flow-CavUTEzp.css">
-    <link rel="stylesheet" crossorigin href="/assets/index-Bq7iCtof.css">
+    <link rel="stylesheet" crossorigin href="/assets/index-Dpx9Bcqn.css">
   </head>
   <body>
     <div id="app"></div>

package/src/ui/server/index.js

@@ -42,6 +42,7 @@ import { registerFsRoutes } from './routes/fs.js';
 import { registerRecentDirectoriesSummaryRoutes } from './routes/recentDirectoriesAiSummary.js';
 import { registerNpmRoutes } from './routes/npm.js';
 import { registerFileOpenRoutes } from './routes/fileOpen.js';
+import { registerLocalReposRoutes } from './routes/localRepos.js';
 import { registerRemoteReposRoutes } from './routes/remoteRepos.js';
 import { registerWorkbenchRoutes } from './routes/workbench.js';
 import { registerGitOpsRoutes } from './routes/gitOps.js';
@@ -416,6 +417,9 @@ async function startUIServer(noOpen = false, savePort = false) {
   // 远程托管平台仓库列表(GitHub / Gitee 两个 Tab 的数据源)
   registerRemoteReposRoutes({ app });
 
+  // 本机 Git 仓库清单 —— 仓库卡片上「已克隆」徽标的判据(全盘扫描 + 落盘缓存)
+  registerLocalReposRoutes({ app });
+
   registerWorkbenchRoutes({
     app,
     getCurrentProjectPath: () => currentProjectPath,

package/src/ui/server/routes/fs.js

@@ -616,7 +616,9 @@ export function registerFsRoutes({
 
         res.json({ success: true });
       } catch (error) {
-        res.status(400).json({ success: false, error: `无法打开: ${'$'}{error.message}` });
+        // 注意别把 ${error.message} 写成字符串字面量 —— 之前这里多包了一层引号，
+        // 用户看到的就是"无法打开: ${error.message}"这种原文
+        res.status(400).json({ success: false, error: `无法在 "${directoryPath}" 中启动 g ui: ${error.message}` });
       }
     } catch (error) {
       res.status(500).json({ success: false, error: error.message });

package/src/ui/server/routes/git/clone.js

@@ -0,0 +1,166 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// 把远程仓库克隆到用户指定的文件夹(远程仓库列表卡片上的「克隆到文件夹」)。
+//
+// 与同目录其它 git 路由的关键差别:clone 的 cwd **不是当前工作目录**,而是用户
+// 刚在文件选择器里选的那个父目录。所以这里不能复用 execGitCommand —— 它固定用
+// getCwd(),而且会把命令塞进"当前项目"的命令历史里,那条记录里的 cwd 是错的,
+// 事后回看会误导。这里自己 spawn,也不碰命令历史。
+//
+// 用哪个协议(SSH / HTTPS)由调用方决定:前端传什么就 clone 什么,服务端只做
+// 地址合法性校验。推导逻辑只留一份在前端(utils/remoteUrl.ts),免得两边各写
+// 一套规则、哪天规则变了只改了一边。
+
+import path from 'path'
+import fs from 'fs/promises'
+import { execFile } from 'child_process'
+import { promisify } from 'util'
+
+import logger from '../../utils/logger.js'
+import { HttpError } from '../../utils/asyncRoute.js'
+import { assertGitRemoteUrl } from '../../utils/gitArgs.js'
+import { rememberRepo } from '../../utils/localRepoScan.js'
+import { augmentEnvPath } from '../../../../utils/shellPath.js'
+
+const execFileAsync = promisify(execFile)
+
+/** 大仓库 clone 可能好几分钟;与 agentMarketplace 的 CLONE_TIMEOUT_MS 取齐 */
+const CLONE_TIMEOUT_MS = 180_000
+const MAX_BUFFER = 10 * 1024 * 1024
+
+/**
+ * 从远程地址里取出仓库目录名(clone 出来的子目录就用它)。
+ *   git@github.com:owner/repo.git     → repo
+ *   https://gitee.com/owner/repo.git  → repo
+ *   https://github.com/owner/repo/    → repo
+ * 取不出来返回空串,调用方兜底成 repository。
+ */
+export function repoNameFromUrl(url) {
+  const s = String(url || '').trim().replace(/\/+$/, '')
+  if (!s) return ''
+  const tail = s.split(/[/:]/).filter(Boolean).pop() || ''
+  return tail.replace(/\.git$/i, '')
+}
+
+/**
+ * 校验父目录:必须是**已存在的目录**的绝对路径。
+ *
+ * 这里刻意不用 assertGitPath —— 那个函数要求"仓库内的相对路径",而用户在文件
+ * 选择器里选出来的必然是绝对路径。反过来也不能拿它当安全边界:clone 的落点
+ * 本来就允许在工作区之外(用户装项目的盘符通常不是当前项目所在盘)。
+ */
+async function assertCloneParentDir(value) {
+  const s = String(value ?? '').trim()
+  if (!s) throw new HttpError(400, '缺少目标文件夹')
+  if (/[\x00-\x1f\x7f]/.test(s)) throw new HttpError(400, '目标文件夹含有非法字符')
+  if (!path.isAbsolute(s)) throw new HttpError(400, '目标文件夹必须是绝对路径')
+
+  let stat
+  try {
+    stat = await fs.stat(s)
+  } catch {
+    throw new HttpError(400, `目标文件夹不存在：${s}`)
+  }
+  if (!stat.isDirectory()) throw new HttpError(400, `目标不是文件夹：${s}`)
+  return path.resolve(s)
+}
+
+async function pathExists(target) {
+  try {
+    await fs.stat(target)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** 取 stderr / message 里最后一行非空文本 —— git 把结论放在最后一行(fatal: ...) */
+function lastErrorLine(text) {
+  const lines = String(text || '')
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+  return lines[lines.length - 1] || ''
+}
+
+/** 把子进程错误压成一句能直接给用户看的话 */
+export function describeCloneError(error, timeoutMs = CLONE_TIMEOUT_MS) {
+  if (error?.killed || error?.signal) {
+    return `克隆超时（超过 ${Math.round(timeoutMs / 1000)} 秒），仓库可能过大或网络不通`
+  }
+  return lastErrorLine(error?.stderr) || lastErrorLine(error?.message) || '克隆失败'
+}
+
+/** 真正跑一次 git clone。抽出来是为了让路由能被单测注入替身(不联网)。 */
+async function runClone({ url, parentDir, target }) {
+  const env = await augmentEnvPath({
+    ...process.env,
+    GIT_CONFIG_PARAMETERS: "'core.quotepath=false'",
+    // 子进程没有 TTY,交互式提示只会把 clone 挂到超时。让它在需要凭据时
+    // 立刻失败并把原因写在 stderr 里(与 directoryFetch.js 同一取舍)。
+    GIT_TERMINAL_PROMPT: '0'
+  })
+  if (!env.GIT_SSH_COMMAND && !env.GIT_SSH) env.GIT_SSH_COMMAND = 'ssh -oBatchMode=yes'
+
+  try {
+    await execFileAsync('git', ['clone', url, target], {
+      cwd: parentDir,
+      timeout: CLONE_TIMEOUT_MS,
+      maxBuffer: MAX_BUFFER,
+      windowsHide: true,
+      env
+    })
+  } catch (error) {
+    logger.error('克隆仓库失败:', error?.stderr || error?.message || error)
+    throw new HttpError(500, describeCloneError(error))
+  }
+}
+
+/**
+ * 注册克隆路由。
+ *
+ * @param {object} deps
+ * @param {import('express').Express} deps.app
+ * @param {typeof runClone} [deps.runCloneImpl] 单测注入点:默认实现会真跑 git clone
+ */
+export function registerGitCloneRoutes({ app, runCloneImpl = runClone }) {
+  app.post('/api/clone', async (req, res) => {
+    try {
+      const url = assertGitRemoteUrl(req.body?.url)
+      const parentDir = await assertCloneParentDir(req.body?.parentDir)
+      const target = path.join(parentDir, repoNameFromUrl(url) || 'repository')
+
+      // 目标已存在就先拦下:git 自己也会拒绝,但它那句
+      // "destination path already exists and is not an empty directory"
+      // 既没说是哪个目录,也没给下一步怎么办
+      if (await pathExists(target)) {
+        return res.json({ success: false, error: `目标文件夹已存在：${target}` })
+      }
+
+      await runCloneImpl({ url, parentDir, target })
+      // 就地登记到本机仓库清单：远程仓库列表的「已克隆」徽标要立刻亮起来，
+      // 不能等下一次全盘重扫（十几秒）。登记用的是服务端刚算出的**真实落点**，
+      // 不依赖前端回传 —— 前端只知道"选了哪个父目录"，仓库名是服务端推的。
+      await rememberRepo(target, url)
+      res.json({ success: true, path: target })
+    } catch (error) {
+      logger.error('克隆仓库失败:', error?.message || error)
+      res.status(error?.statusCode || 200).json({
+        success: false,
+        error: error?.message || '克隆仓库失败'
+      })
+    }
+  })
+}

package/src/ui/server/routes/git/clone.test.js

@@ -0,0 +1,253 @@
+// clone.js 单元测试
+// 模式参照 remotes.test.js:node:test + 假 app 捕获 handler + 注入 runCloneImpl 替身。
+// 关键:所有用例都不联网、不真跑 git —— runCloneImpl 一律换成计数用的替身,
+// 唯一的"真实"依赖是本地文件系统(校验父目录要用 fs.stat)。
+//
+// 克隆成功后路由会调 rememberRepo() 把落点登记进本机仓库清单(「已克隆」徽标用),
+// 那一步会**写盘** —— 必须先把缓存路径指到临时文件,否则测试会往用户真实的
+// ~/.zen-gitsync/local-repos.json 里塞一堆 os.tmpdir() 下的假记录。
+import { test, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+import { registerGitCloneRoutes, repoNameFromUrl, describeCloneError } from './clone.js';
+import { resetLocalRepoScan } from '../../utils/localRepoScan.js';
+import { HttpError } from '../../utils/asyncRoute.js';
+
+// 缓存路径必须在**任何用例跑起来之前**指到临时文件。写在 import 之间没用
+// (ESM 的 import 全部提升),好在 cacheFilePath() 是每次调用才读 env,
+// 所以放在这里同样生效 —— 真正要防的是"用例跑的时候还指着家目录"。
+const CACHE_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'zen-clone-cache-'));
+process.env.ZEN_LOCAL_REPOS_CACHE = path.join(CACHE_DIR, 'local-repos.json');
+
+after(() => {
+  fs.rmSync(CACHE_DIR, { recursive: true, force: true });
+});
+
+// ── 测试工具 ─────────────────────────────────────────────────────────────
+
+function makeApp() {
+  const handlers = {};
+  const app = {
+    get(p, ...hs) { handlers[`GET ${p}`] = hs.at(-1); },
+    post(p, ...hs) { handlers[`POST ${p}`] = hs.at(-1); }
+  };
+  return { app, handlers };
+}
+
+async function invoke(handler, body = {}) {
+  let statusCode = 200;
+  let payload;
+  const req = { body, method: 'POST', path: '/api/clone' };
+  const res = {
+    status(code) { statusCode = code; return this; },
+    json(data) { payload = data; return this; }
+  };
+  await handler(req, res, () => {});
+  return { statusCode, payload };
+}
+
+/** 注册路由并返回 handler;runCloneImpl 默认是个永远不该被调到的替身 */
+function register(runCloneImpl = async () => { throw new Error('不该真的跑 git clone'); }) {
+  const { app, handlers } = makeApp();
+  registerGitCloneRoutes({ app, runCloneImpl });
+  return handlers['POST /api/clone'];
+}
+
+/** 建一个临时父目录,返回路径(用例结束自己删) */
+function tmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'zen-clone-test-'));
+}
+
+function cleanup(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// ── repoNameFromUrl ─────────────────────────────────────────────────────
+
+test('repoNameFromUrl:从各种地址形态里取出仓库名', () => {
+  assert.equal(repoNameFromUrl('git@github.com:xz333221/zen-gitsync.git'), 'zen-gitsync');
+  assert.equal(repoNameFromUrl('https://gitee.com/xz_web/xiangyu-sites'), 'xiangyu-sites');
+  // 尾斜杠 + .git 同时出现
+  assert.equal(repoNameFromUrl('https://github.com/a/b.git/'), 'b');
+  // ssh:// 形式(带端口)也走同一条路径
+  assert.equal(repoNameFromUrl('ssh://git@github.com:22/a/b.git'), 'b');
+  // 取不出来 → 空串,由调用方兜底成 repository
+  assert.equal(repoNameFromUrl(''), '');
+  assert.equal(repoNameFromUrl('   '), '');
+  // 只有纯路径分隔符才真的取不出东西;根地址(没有仓库段)会退化成 host,
+  // 不是空串 —— 钉住这个行为,免得以后误以为它一定是"干净"的仓库名
+  assert.equal(repoNameFromUrl('/'), '');
+  assert.equal(repoNameFromUrl('https://github.com/'), 'github.com');
+});
+
+// ── describeCloneError ──────────────────────────────────────────────────
+
+test('describeCloneError:超时说人话,其余透出 git 的最后一行', () => {
+  assert.match(describeCloneError({ killed: true }), /超时/);
+  assert.match(describeCloneError({ signal: 'SIGTERM' }), /超时/);
+  assert.equal(
+    describeCloneError({ stderr: 'Cloning into...\nwarning: 一些警告\nfatal: repository not found\n' }),
+    'fatal: repository not found'
+  );
+  assert.equal(describeCloneError({ message: 'spawn git ENOENT' }), 'spawn git ENOENT');
+  assert.equal(describeCloneError({}), '克隆失败');
+});
+
+// ── 正常路径 ────────────────────────────────────────────────────────────
+
+test('克隆成功:在父目录下建出以仓库名命名的子目录', async () => {
+  const parent = tmpDir();
+  const seen = [];
+  const handler = register(async (args) => { seen.push(args); });
+
+  const { payload } = await invoke(handler, {
+    url: 'git@github.com:xz333221/zen-gitsync.git',
+    parentDir: parent
+  });
+
+  assert.equal(payload.success, true);
+  assert.equal(payload.path, path.join(path.resolve(parent), 'zen-gitsync'));
+  assert.equal(seen.length, 1);
+  assert.deepEqual(seen[0], {
+    url: 'git@github.com:xz333221/zen-gitsync.git',
+    parentDir: path.resolve(parent),
+    target: path.join(path.resolve(parent), 'zen-gitsync')
+  });
+
+  cleanup(parent);
+});
+
+test('地址取不出仓库名时,兜底成 repository 而不是拼出一个父目录本身', async () => {
+  const parent = tmpDir();
+  const seen = [];
+  const handler = register(async (args) => { seen.push(args); });
+
+  // '/' 这种地址 assertGitRemoteUrl 放行(本地路径形态),但取不出仓库名
+  const { payload } = await invoke(handler, { url: '/', parentDir: parent });
+
+  assert.equal(payload.success, true);
+  assert.equal(seen[0].target, path.join(path.resolve(parent), 'repository'));
+
+  cleanup(parent);
+});
+
+// ── 拒绝的入参 ──────────────────────────────────────────────────────────
+
+test('地址非法:空 / ext:: / 把"远程名 + 地址"一起粘进来 —— 一律拒绝且不跑 git', async () => {
+  const parent = tmpDir();
+  let called = 0;
+  const handler = register(async () => { called += 1; });
+
+  for (const url of ['', '   ', 'ext::sh -c whoami', 'origin git@gitee.com:x/y.git']) {
+    const { payload } = await invoke(handler, { url, parentDir: parent });
+    assert.equal(payload.success, false, `url=${JSON.stringify(url)}`);
+    assert.ok(payload.error, `url=${JSON.stringify(url)} 应带错误说明`);
+  }
+  assert.equal(called, 0, '入参不合法时一次都不该执行 git clone');
+
+  cleanup(parent);
+});
+
+test('父目录：不存在 / 不是目录 / 相对路径 —— 一律拒绝且不跑 git', async () => {
+  const parent = tmpDir();
+  const filePath = path.join(parent, 'a-file.txt');
+  fs.writeFileSync(filePath, 'x');
+  let called = 0;
+  const handler = register(async () => { called += 1; });
+
+  const cases = [
+    [path.join(parent, 'not-exist'), /不存在/],
+    [filePath, /不是文件夹/],
+    ['relative/dir', /绝对路径/],
+    ['', /缺少目标文件夹/]
+  ];
+  for (const [parentDir, pattern] of cases) {
+    const { payload } = await invoke(handler, {
+      url: 'git@github.com:a/b.git',
+      parentDir
+    });
+    assert.equal(payload.success, false, `parentDir=${parentDir}`);
+    assert.match(payload.error, pattern);
+  }
+  assert.equal(called, 0);
+
+  cleanup(parent);
+});
+
+test('目标子目录已存在：先拦下,把路径说清楚,不去撞 git 那句英文报错', async () => {
+  const parent = tmpDir();
+  fs.mkdirSync(path.join(parent, 'zen-gitsync'));
+  let called = 0;
+  const handler = register(async () => { called += 1; });
+
+  const { payload } = await invoke(handler, {
+    url: 'git@github.com:xz333221/zen-gitsync.git',
+    parentDir: parent
+  });
+
+  assert.equal(payload.success, false);
+  assert.match(payload.error, /已存在/);
+  assert.match(payload.error, /zen-gitsync/);
+  assert.equal(called, 0);
+
+  cleanup(parent);
+});
+
+// ── 失败透传 ────────────────────────────────────────────────────────────
+
+test('git 失败:状态码与错误原文透给前端', async () => {
+  const parent = tmpDir();
+  const handler = register(async () => {
+    throw new HttpError(500, 'fatal: could not read from remote repository');
+  });
+
+  const { statusCode, payload } = await invoke(handler, {
+    url: 'git@github.com:a/b.git',
+    parentDir: parent
+  });
+
+  assert.equal(statusCode, 500);
+  assert.equal(payload.success, false);
+  assert.match(payload.error, /could not read from remote repository/);
+
+  cleanup(parent);
+});
+
+// ── 克隆成功后登记本机仓库清单 ──────────────────────────────────────────
+
+test('克隆成功:落点被登记进本机仓库清单,徽标不必等下一次全盘重扫', async () => {
+  const parent = tmpDir();
+  const cachePath = process.env.ZEN_LOCAL_REPOS_CACHE;
+  const prevRepo = path.join(parent, 'already-known');
+
+  // 造一份"上次全盘扫的结果":登记只该往里加一条,不能把整份盖掉
+  fs.writeFileSync(
+    cachePath,
+    JSON.stringify({
+      scannedAt: 1,
+      scannedDirs: 2,
+      roots: ['X:/'],
+      repos: { [prevRepo]: 'https://gitee.com/xz_web/xiangqi.git' }
+    }),
+    'utf8'
+  );
+  resetLocalRepoScan();
+
+  const handler = register(async () => {});
+  const { payload } = await invoke(handler, {
+    url: 'git@github.com:xz333221/zen-gitsync.git',
+    parentDir: parent
+  });
+  assert.equal(payload.success, true);
+
+  const raw = JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+  assert.equal(raw.repos[payload.path], 'git@github.com:xz333221/zen-gitsync.git');
+  assert.equal(raw.repos[prevRepo], 'https://gitee.com/xz_web/xiangqi.git', '旧记录必须还在');
+  // 登记 ≠ 重扫:时间戳保持原样,否则前端会以为"刚扫过"
+  assert.equal(raw.scannedAt, 1);
+
+  cleanup(parent);
+});

package/src/ui/server/routes/gitOps.js

@@ -25,6 +25,7 @@ import { createDiffHelpers } from './git/diffUtils.js';
 import { registerGitStashRoutes } from './git/stash.js';
 import { registerGitTagRoutes } from './git/tags.js';
 import { registerGitRemoteRoutes, __testables as remoteTestables } from './git/remotes.js';
+import { registerGitCloneRoutes } from './git/clone.js';
 import {
   assertGitRef,
   assertGitHash,
@@ -1016,6 +1017,10 @@ export function registerGitOpsRoutes({
     setRecentPushStatus
   });
 
+  // 克隆到指定文件夹:远程仓库列表卡片上的「克隆到文件夹」。
+  // 注意它不接 execGitCommand —— clone 的 cwd 是用户选的那个目录,不是当前工作目录。
+  registerGitCloneRoutes({ app });
+
   // 重置暂存区 (git reset HEAD)
   app.post('/api/reset-head', async (req, res) => {
     try {

package/src/ui/server/routes/localRepos.js

@@ -0,0 +1,60 @@
+// Copyright 2026 xz333221
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// 本机 Git 仓库清单（远程仓库列表的「已克隆」徽标用）。
+//
+//   GET  /api/local-repos        取快照 —— 不阻塞：首次运行没有缓存时立刻回
+//                                { scanning: true, repos: {} }，调用方过几秒再问
+//   POST /api/local-repos/scan   强制重扫（"我刚才在别处克隆了个仓库"）
+//
+// 为什么 GET 不 await 扫描：全盘扫一次十几秒（见 utils/localRepoScan.js 的文件头），
+// 把它挂在 HTTP 请求上会让仓库列表首屏跟着卡十几秒。宁可先给一份可能过期的，
+// 也不要让用户对着转圈等。
+//
+// 安全口径：**不接受任何客户端传入的路径**。扫描根固定是"本机存在的盘符"，
+// 跳过名单是模块里的常量 —— 没有任何参数能把它变成"遍历你指定的目录"。
+// 所以它不需要像 /api/recent_directories/git-state 那样做白名单校验。
+import { asyncRoute } from '../utils/asyncRoute.js'
+import logger from '../utils/logger.js'
+import { getLocalRepos, refreshLocalRepos } from '../utils/localRepoScan.js'
+
+/**
+ * 注册本机仓库清单路由。
+ *
+ * *Impl 参数是给单测留的注入口（与 registerRemoteReposRoutes 同一套做法）：
+ * 默认实现会真去遍历磁盘，单测换成假实现就不必扫一遍真实文件系统。
+ */
+export function registerLocalReposRoutes({
+  app,
+  getLocalReposImpl = getLocalRepos,
+  refreshReposImpl = refreshLocalRepos,
+}) {
+  app.get('/api/local-repos', asyncRoute(async (req, res) => {
+    const snapshot = await getLocalReposImpl()
+    res.json({ success: true, ...snapshot })
+  }))
+
+  app.post('/api/local-repos/scan', asyncRoute(async (req, res) => {
+    // 刻意不 await 扫描本身（要十几秒）：这里只负责"开始"，结果由前端轮询 GET 拿。
+    // refreshLocalRepos 会把状态同步置成 scanning，随后回来的 GET 就能看到。
+    //
+    // 必须显式 .catch：这是"发射后不管"的 promise，一旦 reject 就是**进程级**
+    // unhandled rejection（Node 15+ 默认直接崩服务）。默认实现内部 try/catch 过、
+    // 不会 reject，但注入口的存在意味着将来可能换实现，别把崩溃留成隐患。
+    void Promise.resolve(refreshReposImpl()).catch((error) => {
+      logger.warn('[local-repos] 手动重扫失败:', error?.message || error)
+    })
+    res.json({ success: true, started: true })
+  }))
+}