@noob-stupid/dsh-plugin-console 0.5.17 → 0.5.18

package/README.md

@@ -236,6 +236,22 @@ Requires: DSH ≥ 0.1.0-rc.6 (web profile, with `dsh-client-modules` / `dsh-host
   with a client-side fallback;
 - **Type badges**: 官方 / 聚合 / 技能 (repo contains SKILL.md) recognized automatically.
 
+> **Network environment notes (why a multi-source setup can look "all dead")**
+> - **Accelerators/proxies that rewrite hosts kill the direct sources**: tools like Steam++ often point
+>   `github.com` at `127.0.0.1`, so the GitHub direct source, `raw.githubusercontent.com` and
+>   `api.github.com` all become unreachable — the plugin is not broken. The console now reports this
+>   honestly as "local proxy / certificate interception (…) — an accelerator or proxy was detected,
+>   turn it off and retry" instead of a vague "network unreachable".
+> - **Free mirrors are unreliable for the git protocol on large packs, while archive/raw are usually
+>   fast**: measured on the same ghproxy.net host, archive (plain HTTP) ran at **4 MB/s** while the git
+>   protocol moved **0 B/s**. Since this version the git channel has a stall criterion (switch source
+>   after 20 s below 1 B/s) plus its own budget, and falls back to the **archive channel** (download the
+>   tarball, extract, create the repo — equivalent to a clone) when all git sources fail. No manual
+>   source switching needed.
+> - To reorder transports, use **Source Manager**: **git sources**, **archive sources** and **index
+>   sources** all support primary→backup plus self-hosted mirrors (internal Gitea/GitLab, local
+>   `file://` bare repos).
+
 ### Static index market (plugin & skill tabs)
 
 > **Hybrid architecture**: browsing uses the static index (instant, zero GitHub API calls),

package/README.zh.md

@@ -180,6 +180,18 @@ git clone https://github.com/Noob-stupid/dsh-plugin-hub /tmp/dsh-plugin-console
 - **类型徽标**：官方 / 聚合 / 技能（仓库含 SKILL.md）自动识别；
 - 「添加到本地」= 按当前源安装（registry 失败自动回退 git 通道）+ 写入启用条目，HMR 生效。
 
+> **网络环境提醒（多源为什么有时"看起来都失效"）**
+> - **加速器/代理改 hosts 会让"直连源"失效**：Steam++ 这类工具常把 `github.com` 指到 `127.0.0.1`，
+>   于是 GitHub 直连源、`raw.githubusercontent.com`、`api.github.com` 全部不可达 —— 这不是插件坏了。
+>   本控制台会把这类失败**如实报成**「本地代理/证书拦截（…）—— 检测到本机加速器/代理，建议关闭后重试」，
+>   而不是笼统的"网络不可达"。
+> - **免费镜像的 git 协议对大 pack 不可靠，archive / raw 通常很快**：真机实测同一个 ghproxy.net 域名下
+>   archive（普通 HTTP 下载）**4 MB/s**、git 协议 **0 B/s**。所以本版起 git 通道有停滞判据
+>   （连续 20 秒 <1 B/s 就换源）与独立预算，并在 git 全部失败后**自动改走 archive 通道**
+>   （下载压缩包再解压建仓，结果与 clone 等价）—— 你不需要手动换源。
+> - 想让某条通道优先，去「软件源」里调整顺序：**Git 源**、**archive 源**、**索引源** 都支持主→备与
+>   自建镜像（内网 Gitea/GitLab、本地 `file://` 裸仓库均可）。
+
 ### 静态索引市场（插件 / 技能双 tab）
 
 > **混合架构**：浏览走静态索引（秒开、零 API 调用），搜索走实时通道（GitHub 搜索 API / 多源并行）——

package/lib/client.js

@@ -453,6 +453,10 @@ window.__ModuleLoader__.load({
 			addIndexSource: "添加索引源",
 			indexUrlPlaceholder: "索引 JSON 地址（https:// 或本机/私网 http://）",
 			gitSourcesTitle: "Git 源",
+			archiveSourcesTitle: "archive 源（HTTP 压缩包）",
+			archiveSourcesDesc: "git 协议拉不动时的替代通道：直接用 HTTP 下载仓库压缩包再解压建仓（真机实测同一镜像下 archive 4 MB/s、git 协议 0 B/s）。模板用 {owner}/{repo} 占位符，可选 {branch}；主源优先，失败自动回退下一个。示例：https://ghproxy.net/https://github.com/{owner}/{repo}/archive/refs/heads/{branch}.tar.gz",
+			archiveUrlPlaceholder: "https://ghproxy.net/https://github.com/{owner}/{repo}/archive/refs/heads/{branch}.tar.gz",
+			addArchiveSource: "添加 archive 源",
 			gitSourcesDesc: "克隆仓库时用的地址模板（{owner}/{repo} 占位符）。下面这个列表就是「自定义 Git 源」——内置两条是默认值，点「添加 Git 源」即可换成你自己的：Gitee = https://gitee.com/{owner}/{repo}.git；GitLab = https://gitlab.com/{owner}/{repo}.git；自建 Gitea = https://你的域名/{owner}/{repo}.git；镜像代理 = https://镜像站/https://github.com/{owner}/{repo}.git；本地裸仓库 = file:///D:/repos/{owner}/{repo}.git。主源优先，失败自动回退下一个",
 			addGitSource: "添加 Git 源",
 			gitUrlPlaceholder: "如 https://gitee.com/{owner}/{repo}.git",
@@ -963,6 +967,10 @@ window.__ModuleLoader__.load({
 			addIndexSource: "Add index source",
 			indexUrlPlaceholder: "Index JSON URL (https:// or local/intranet http://)",
 			gitSourcesTitle: "Git sources",
+			archiveSourcesTitle: "Archive sources (HTTP tarball)",
+			archiveSourcesDesc: "Fallback transport when the git protocol cannot move data: download the repo tarball over plain HTTP, extract, and create a repo from it (measured: on the same mirror archive ran at 4 MB/s while git moved 0 B/s). Templates use {owner}/{repo}, optionally {branch}; primary first, falls back on failure.",
+			archiveUrlPlaceholder: "https://ghproxy.net/https://github.com/{owner}/{repo}/archive/refs/heads/{branch}.tar.gz",
+			addArchiveSource: "Add archive source",
 			gitSourcesDesc: "URL template for cloning ({owner}/{repo} placeholders). This list IS the custom git-source list — the two built-ins are just defaults; click Add git source to swap in your own: Gitee = https://gitee.com/{owner}/{repo}.git; GitLab = https://gitlab.com/{owner}/{repo}.git; self-hosted Gitea = https://your-domain/{owner}/{repo}.git; mirror proxy = https://mirror/https://github.com/{owner}/{repo}.git; local bare repo = file:///D:/repos/{owner}/{repo}.git. Primary first, falls back on failure",
 			addGitSource: "Add Git source",
 			gitUrlPlaceholder: "e.g. https://gitee.com/{owner}/{repo}.git",
@@ -2007,8 +2015,12 @@ window.__ModuleLoader__.load({
 			const [gitSourceName, setGitSourceName] = react.useState("");
 			const [gitSourceUrl, setGitSourceUrl] = react.useState("");
 			const [editGit, setEditGit] = react.useState(null);
+			// archive 源（批次 C-⑨）：git 协议拉不动时改走普通 HTTP 下载压缩包；模板与 git 源同形
+			const [archiveSourceName, setArchiveSourceName] = react.useState("");
+			const [archiveSourceUrl, setArchiveSourceUrl] = react.useState("");
+			const [editArchive, setEditArchive] = react.useState(null);
 			// 软件源弹窗折叠分区：软件源默认展开，其余收起（避免弹窗过长）
-			const [openSections, setOpenSections] = react.useState({ registries: true, index: false, git: false, search: false, gitee: false });
+			const [openSections, setOpenSections] = react.useState({ registries: true, index: false, git: false, archive: false, search: false, gitee: false });
 			// 官方风格入口（新 tab）传入 section 时就地展开对应功能。
 			// 不传 section 时（= 原有 tab 的调用方式）行为与改动前**完全一致** —— 纯加法。
 			react.useEffect(() => {
@@ -2024,6 +2036,8 @@ window.__ModuleLoader__.load({
 			const [searchSourcesList, setSearchSourcesList] = react.useState(null);
 			// Git 源列表（「仓库落地」提示动态显示当前主源，避免写死 GitHub）
 			const [gitSourcesList, setGitSourcesList] = react.useState(null);
+			// archive 源列表（「软件源 → archive 源」）
+			const [archiveSourcesList, setArchiveSourcesList] = react.useState(null);
 			// 自定义搜索源添加表单
 			const [searchSourceName, setSearchSourceName] = react.useState("");
 			const [searchSourceUrl, setSearchSourceUrl] = react.useState("");
@@ -2074,6 +2088,7 @@ window.__ModuleLoader__.load({
 						setSourcesData((prev) => (prev === null ? data.sources : prev));
 						setSearchSourcesList(data.sources.searchSources ?? []);
 						setGitSourcesList(data.sources.gitSources ?? []);
+						setArchiveSourcesList(data.sources.archiveSources ?? []);
 					},
 					() => {},
 				);
@@ -3060,6 +3075,17 @@ window.__ModuleLoader__.load({
 				if (editIndex === null) return;
 				sourcesAction({ action: "edit-index", id: editIndex.id, name: editIndex.name, url: editIndex.url }, () => setEditIndex(null));
 			};
+			/** archive 源（批次 C-⑨）：与 git 源同一套操作语义（添加 / 编辑 / 设主源 / 删除）。 */
+			const addArchiveSource = () => {
+				const tpl2 = archiveSourceUrl.trim();
+				if (!tpl2.includes("{owner}") || !tpl2.includes("{repo}")) { setMessage(t("archiveUrlPlaceholder")); return; }
+				sourcesAction({ action: "add-archive", name: archiveSourceName.trim(), urlTemplate: tpl2 }, () => { setArchiveSourceName(""); setArchiveSourceUrl(""); });
+			};
+			const saveEditArchive = () => {
+				if (editArchive === null) return;
+				sourcesAction({ action: "edit-archive", id: editArchive.id, name: editArchive.name, urlTemplate: editArchive.urlTemplate }, () => setEditArchive(null));
+			};
+
 			const addGitSource = () => {
 				const tpl = gitSourceUrl.trim();
 				if (!tpl.includes("{owner}") || !tpl.includes("{repo}")) {
@@ -5035,6 +5061,28 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 										el("input", { type: "text", placeholder: t("gitUrlPlaceholder"), value: gitSourceUrl, onChange: (event) => setGitSourceUrl(event.currentTarget.value), style: { flex: 2, minWidth: 0 } }),
 										el("button", { type: "button", className: styles.toggle, disabled: sourcesBusy, onClick: addGitSource }, t("addGitSource"))),
 									]),
+									accSection("archive", t("archiveSourcesTitle"), [
+									el("p", { className: styles.message }, t("archiveSourcesDesc")),
+									(sourcesData.archiveSources ?? []).map((s) =>
+										editArchive !== null && editArchive.id === s.id
+											? el("div", { key: s.id, className: styles.rowTop, style: { justifyContent: "space-between" } },
+												el("input", { type: "text", value: editArchive.name, onChange: (event) => setEditArchive({ ...editArchive, name: event.currentTarget.value }), style: { flex: 1, minWidth: 80 } }),
+												el("input", { type: "text", value: editArchive.urlTemplate, onChange: (event) => setEditArchive({ ...editArchive, urlTemplate: event.currentTarget.value }), style: { flex: 2, minWidth: 120 } }),
+												el("button", { type: "button", className: styles.toggle, disabled: sourcesBusy, onClick: saveEditArchive }, t("saveSource")),
+												el("button", { type: "button", className: styles.toggle, onClick: () => setEditArchive(null) }, t("cancelEdit")))
+											: el("div", { key: s.id, className: styles.rowTop, style: { justifyContent: "space-between" } },
+												el("div", { className: styles.rowTop, style: { flex: 1, minWidth: 0 } },
+													el("strong", { className: styles.name, style: { flex: "none", maxWidth: "35%" } }, s.name + (s.primary ? "（" + t("sourcePrimary") + "）" : "")),
+													el("code", { className: styles.srcUrl }, s.urlTemplate)),
+												el("div", { className: styles.rowTop },
+													s.primary ? null : el("button", { type: "button", className: styles.toggle, title: t("setPrimaryHint"), disabled: sourcesBusy, onClick: () => sourcesAction({ action: "set-archive-primary", id: s.id }) }, t("setPrimary")),
+													el("button", { type: "button", className: styles.toggle, title: t("editSourceHint"), disabled: sourcesBusy, onClick: () => setEditArchive({ id: s.id, name: s.name, urlTemplate: s.urlTemplate }) }, t("editSource")),
+													el("button", { type: "button", className: styles.toggle, title: t("removeSourceHint"), disabled: sourcesBusy, onClick: () => sourcesAction({ action: "remove-archive", id: s.id }) }, t("removeSource"))))),
+									el("div", { className: styles.rowTop },
+										el("input", { type: "text", placeholder: t("sourceName"), value: archiveSourceName, onChange: (event) => setArchiveSourceName(event.currentTarget.value), style: { flex: 1, minWidth: 0 } }),
+										el("input", { type: "text", placeholder: t("archiveUrlPlaceholder"), value: archiveSourceUrl, onChange: (event) => setArchiveSourceUrl(event.currentTarget.value), style: { flex: 2, minWidth: 0 } }),
+										el("button", { type: "button", className: styles.toggle, disabled: sourcesBusy, onClick: addArchiveSource }, t("addArchiveSource"))),
+									]),
 									accSection("search", t("searchSourcesTitle"), [
 									el("p", { className: styles.message }, t("searchSourcesDesc")),
 									(sourcesData.searchSources ?? []).map((s) =>

package/lib/server/domain/archive-source.js

@@ -0,0 +1,209 @@
+// L1 · domain —— archive-source.js（archive 通道：用 HTTP 下载仓库压缩包替代 git 协议取仓库内容）
+//
+// 为什么需要它（2026-09-27 真机实测）：**同一个 ghproxy.net 域名**
+//   · archive（普通 HTTP GET）能跑到 4 MB/s —— 429 MB / 105 秒下完；
+//   · git 协议 0 B/s —— `git clone` 挂到停滞判据判死为止，一个字节都没有。
+// 于是"git 拉不动"不该等于"这个仓库装不上"：下载 tar.gz → 解压 → 建仓，得到与 clone **等价的结果**，
+// 让上层（套装装配 / 仓库落地）无感。
+//
+// 设计（沿用既有工程约定）：
+//   · 源模板与 gitSources **同形**（{owner}/{repo} 占位符 + 主→备 + 可在「软件源」里配置），
+//     另支持 {branch} 占位符；默认两条：ghproxy 镜像 / GitHub codeload 官方。
+//   · 超时/杀树/等退出一律复用 infra 的 execFileWithKillTree（它超时会杀整棵进程树并等它退出）；
+//   · 半成品目录清理一律复用 infra 的 disposeDir（删不掉就改名降级成 .trash-*）；
+//   · 失败记录带上"本次已下载多少字节"（与 git 通道同一套事实口径，见 repoland.js 的 measureProgressBytes）。
+
+import { existsSync, mkdirSync, statSync, renameSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { execFileWithKillTree, gitEnv } from '../infra/exec.js'
+import { disposeDir, disposeNote } from '../infra/fsx.js'
+import { readSources, DEFAULT_SOURCES } from './sources.js'
+
+/** 单次 archive 下载的超时（默认 180 秒）：真机 429 MB / 4 MB/s ≈ 105 秒，留出余量。
+ * 比 git 通道的 60 秒宽 —— archive 是"能跑满带宽"的传输，用 git 的短超时反而会误杀大仓库。 */
+const ARCHIVE_TIMEOUT_MS = 180000
+
+/** 解压 + `git init/add/commit` 的超时（大仓库的首个 commit 会慢，但失败不致命，见 archiveRepo）。 */
+const ARCHIVE_COMMIT_TIMEOUT_MS = 120000
+
+/** 分支候选顺序：调用方给的分支打头，再回退 main / master / dev，最多试 3 条
+ * （真机 dsh-web 的默认分支就是 dev；分支不对时 archive 会 404，必须能自己找回来）。 */
+function archiveBranchOrder(branch, defaults = ['main', 'master', 'dev']) {
+  const list = Array.isArray(branch) ? branch : [branch]
+  const merged = [...list, ...defaults].filter((b) => typeof b === 'string' && b.trim() !== '')
+  return [...new Set(merged.map((b) => b.trim()))].slice(0, 3)
+}
+
+/** archive 候选（带源 id/名称/模板/最终 URL）：与 gitCloneCandidates 同形的排序逻辑。
+ * 模板里没有 {branch} 时照旧替换（同一 URL 对任何分支都成立，由站点自己决定）。 */
+function archiveCandidates(repo, branch = 'main', sources = null) {
+  const full = String(repo ?? '')
+  const parts = full.split('/')
+  const owner = parts[0] ?? ''
+  const repoName = parts[1] ?? ''
+  let list = []
+  try {
+    list = (sources ?? readSources().archiveSources) ?? DEFAULT_SOURCES.archiveSources
+  } catch {
+    list = DEFAULT_SOURCES.archiveSources
+  }
+  const ordered = [...list].sort((a, b) => (b.primary === true ? 1 : 0) - (a.primary === true ? 1 : 0))
+  const out = []
+  for (const s of ordered) {
+    const tpl = typeof s?.urlTemplate === 'string' ? s.urlTemplate : ''
+    if (tpl === '') continue
+    const url = tpl
+      .replace(/\{owner\}/gu, owner)
+      .replace(/\{repo\}/gu, repoName)
+      .replace(/\{branch\}/gu, String(branch ?? 'main'))
+    if (url === '') continue
+    out.push({ id: typeof s.id === 'string' ? s.id : '', name: typeof s.name === 'string' ? s.name : '', urlTemplate: tpl, url })
+  }
+  if (out.length === 0) {
+    out.push({
+      id: 'codeload-archive',
+      name: 'GitHub codeload',
+      urlTemplate: 'https://codeload.github.com/{owner}/{repo}/tar.gz/refs/heads/{branch}',
+      url: `https://codeload.github.com/${full}/tar.gz/refs/heads/${String(branch ?? 'main')}`,
+    })
+  }
+  return out
+}
+
+/** 解压出来的顶层目录名不可预测（GitHub 的 tar.gz 顶层是 `{repo}-{branch}/`），
+ * 统一用 `--strip-components=1` 摊平；万一某天的 tar 不认这个选项，这里再兜一层：
+ * 若目标目录里只有一个子目录且没有 package.json，就把它的内容提上来。 */
+function flattenSingleDir(part, deps = {}) {
+  const readdir = deps.readdir ?? readdirSync
+  const exists = deps.exists ?? existsSync
+  const rename = deps.rename ?? renameSync
+  if (exists(join(part, 'package.json'))) return false
+  let entries = []
+  try { entries = readdir(part, { withFileTypes: true }) } catch { return false }
+  const dirs = entries.filter((e) => e.isDirectory())
+  if (dirs.length !== 1) return false
+  const inner = join(part, dirs[0].name)
+  let innerEntries = []
+  try { innerEntries = readdir(inner, { withFileTypes: true }) } catch { return false }
+  for (const entry of innerEntries) {
+    try { rename(join(inner, entry.name), join(part, entry.name)) } catch { return false }
+  }
+  try { disposeDir(inner) } catch {}
+  return true
+}
+
+/** 下载 + 解压 + 建仓，把结果落到 dest。成功返回
+ * `{ url, dir, source, archive: true, branch, bytes, gitNote }`，全部候选失败则抛错。
+ * deps（exec/removeDir/renameDir/exists/now/branch/timeoutMs/sources/curlBin/tarBin/gitInit）只为注入。 */
+async function archiveRepo(repo, dest, { branch = 'main', timeoutMs = ARCHIVE_TIMEOUT_MS, deps = {} } = {}) {
+  const {
+    exec = execFileWithKillTree,
+    removeDir = disposeDir,
+    renameDir = renameSync,
+    exists = existsSync,
+    now = Date.now,
+    curlBin = process.platform === 'win32' ? 'curl.exe' : 'curl',
+    tarBin = 'tar',
+    gitBinName = process.platform === 'win32' ? 'git.exe' : 'git',
+    sources = null,
+    gitInit = true,
+    commitTimeoutMs = ARCHIVE_COMMIT_TIMEOUT_MS,
+  } = deps
+  const errors = []
+  const branches = archiveBranchOrder(branch)
+  const candidates = archiveCandidates(repo, branches[0], sources)
+  const workRoot = join(tmpdir(), `pc-archive-${now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`)
+  mkdirSync(workRoot, { recursive: true })
+  let seq = 0
+  for (const cand of candidates) {
+    for (const br of branches) {
+      seq += 1
+      const part = `${dest}.archive${seq}`
+      const url = cand.urlTemplate.includes('{branch}')
+        ? cand.urlTemplate.replace(/\{owner\}/gu, String(repo).split('/')[0] ?? '').replace(/\{repo\}/gu, String(repo).split('/')[1] ?? '').replace(/\{branch\}/gu, br)
+        : cand.url
+      const tgz = join(workRoot, `repo-${seq}.tar.gz`)
+      const startedAt = now()
+      try { removeDir(part) } catch {}
+      mkdirSync(part, { recursive: true })
+      try {
+        // ① 下载（curl：-f 让 HTTP 错误码直接失败；--max-time 与 exec 超时双保险）
+        // eslint-disable-next-line no-await-in-loop
+        await exec(curlBin, ['-f', '-L', '-sS', '--max-time', String(Math.max(5, Math.round(timeoutMs / 1000))), '-o', tgz, url], {
+          timeout: timeoutMs + 5000,
+          windowsHide: true,
+          maxBuffer: 4 * 1024 * 1024,
+        })
+        // ② 解压（--strip-components=1 摊平 {repo}-{branch}/ 顶层目录）
+        // eslint-disable-next-line no-await-in-loop
+        await exec(tarBin, ['-xzf', tgz, '-C', part, '--strip-components=1'], { timeout: 120000, windowsHide: true, maxBuffer: 4 * 1024 * 1024 })
+        flattenSingleDir(part, { readdir: readdirSync, exists, rename: renameDir })
+        // 判据是"解压出来有没有东西"，**不是**"有没有 package.json"：
+        // 套装仓库、纯技能仓库、示例仓库（真机验收用的 octocat/Hello-World）都没有根 package.json，
+        // 拿它当成功判据会把它们全部误判成失败。分支不对时站点回 404（curl -f 直接失败），
+        // 若站点对不存在的路径回 200 + 错误页，tar 解压会自己报错 —— 两条都在下面被如实记录。
+        let extracted = 0
+        try { extracted = readdirSync(part).length } catch {}
+        if (extracted === 0) {
+          errors.push({ url, message: `archive 解压后目录为空（可能分支 ${br} 不存在或仓库为空）`, branch: br, bytes: 0 })
+          continue
+        }
+        // ③ 建仓：让"下载来的目录"与 `git clone` 的结果等价（有 .git、有首个 commit）
+        let gitNote = null
+        if (gitInit) {
+          try {
+            // eslint-disable-next-line no-await-in-loop
+            await exec(gitBinName, ['init', '-q'], { cwd: part, timeout: commitTimeoutMs, windowsHide: true, env: gitEnv() })
+            // eslint-disable-next-line no-await-in-loop
+            await exec(gitBinName, ['add', '-A'], { cwd: part, timeout: commitTimeoutMs, windowsHide: true, env: gitEnv() })
+            // eslint-disable-next-line no-await-in-loop
+            await exec(gitBinName, ['-c', 'user.email=plugin-console@local', '-c', 'user.name=plugin-console', 'commit', '-qm', `archive ${repo}@${br}`], { cwd: part, timeout: commitTimeoutMs, windowsHide: true, env: gitEnv() })
+          } catch (error) {
+            // 内容已经拿到手了：建仓失败只记 note，绝不因此让"仓库内容可用"这件事失败
+            gitNote = `已下载并解压，但建仓（git init/add/commit）失败：${error instanceof Error ? error.message : String(error)}`.slice(0, 300)
+          }
+        }
+        let bytes = 0
+        try { bytes = statSync(tgz).size } catch {}
+        try {
+          removeDir(dest)
+          renameDir(part, dest)
+        } catch (error) {
+          errors.push({ url, message: `archive 内容就绪但落地失败（${error instanceof Error ? error.message : String(error)}）`, branch: br, bytes })
+          continue
+        }
+        return { url, dir: dest, source: 'archive', archive: true, branch: br, sourceId: cand.id, bytes, gitNote, extracted, tries: seq, ms: now() - startedAt }
+      } catch (error) {
+        let bytes = 0
+        try { bytes = exists(tgz) ? statSync(tgz).size : 0 } catch {}
+        const cleared = removeDir(part)
+        const trashNote = cleared && typeof cleared.trashPath === 'string' && cleared.trashPath !== '' ? disposeNote(cleared) : ''
+        // 超时有两种来源，都要认：① 我们自己的 exec 超时（error.timedOut = 杀树收尾）
+        // ② curl 自己的 --max-time（`curl: (28) Operation timed out`）—— 后者不带 timedOut 字段，
+        // 只按字段判会把"超时"误报成普通失败，用户就看不出"镜像卡住了"。
+        const raw = String(error?.message ?? error)
+        const timedOut = error?.timedOut === true || /timed out|timeout|超时/iu.test(raw)
+        errors.push({
+          url,
+          branch: br,
+          bytes,
+          bytesReceived: bytes, // 与 git 通道同一字段名：汇总文案（summarizeCloneErrors）直接复用
+          timedOut,
+          message: timedOut
+            ? `archive 下载超时（${bytes > 0 ? `本次已下载 ${bytes} B` : '本次仅收到 0 B'}）`
+            : `archive 通道失败：${raw.split(/\r?\n/u)[0].slice(0, 200)}`,
+          ...(trashNote === '' ? {} : { trashed: cleared.trashPath, trashNote }),
+        })
+      } finally {
+        try { removeDir(tgz) } catch {}
+      }
+    }
+  }
+  try { removeDir(workRoot) } catch {}
+  const first = errors[0]
+  const triedList = errors.map((e) => `${e.url}（${e.timedOut === true ? (e.bytes > 0 ? `超时，已下载 ${e.bytes} B` : '超时，仅收到 0 B') : (e.bytes > 0 ? `失败，已下载 ${e.bytes} B` : '失败')}）`).join('；')
+  throw new Error(`archive 通道失败（首个错误：${first?.message ?? '未知'}）；已尝试 ${errors.length} 次：${triedList}`)
+}
+
+export { ARCHIVE_TIMEOUT_MS, ARCHIVE_COMMIT_TIMEOUT_MS, archiveBranchOrder, archiveCandidates, archiveRepo, flattenSingleDir }

package/lib/server/domain/git-channel.js

@@ -0,0 +1,91 @@
+// L1 · domain —— git-channel.js（git 通道的独立预算与尝试顺序；通道备注的统一样子）
+// 2026-09-27 抽出：install-job.js 已到 600 行硬顶（测试 test-architecture-guard.mjs 的行数棘轮），
+// 而"git 通道怎么用预算"本来就是一块自洽的策略，独立成模块后 install-job 只留一行调用。
+// 抽出只搬移 + 收窄形参，**语义一字未改**（原实现见 commit 8deb112 之前的 tryCandidateChannels 尾段）。
+
+import { gitCloneUrls } from './sources.js'
+
+/** git 通道的**独立预算**（2026-09-27 加法）：默认 120 秒，可用环境变量
+ * `DSH_GIT_CHANNEL_BUDGET_MS` 配置（夹在 15 秒 ~ 8 分钟之间，避免被写成 0 或无穷大）。
+ * 为什么必须独立封顶：真机实测 git 协议在镜像上可能是 **0 B/s**，一个 git 源就能把 8 分钟的作业预算
+ * 吃光 —— 后面的候选与本该可用的通道再没机会试（用户看到的是"卡了 8 分钟然后失败"）。
+ * 调用点还有一条硬约束：**不得超过作业剩余预算**（见 tryGitChannel 的 deadline）。
+ * 纯函数 + env 注入，便于离线断言。 */
+const GIT_CHANNEL_BUDGET_MS = 120000
+function gitChannelBudgetMs(env = process.env) {
+  const raw = Number.parseInt(String(env?.DSH_GIT_CHANNEL_BUDGET_MS ?? ''), 10)
+  if (!Number.isFinite(raw)) return GIT_CHANNEL_BUDGET_MS
+  return Math.min(8 * 60 * 1000, Math.max(15000, raw))
+}
+
+/** git 通道里**单个** git 规格的 pnpm 超时上限（与旧代码的 60000 一致；预算更少时取剩余预算）。 */
+const GIT_SPEC_TIMEOUT_MS = 60000
+
+/** 剩余预算低于这个值就不必再起一个 git 规格了（起也来不及握手，只是白占一个进程位）。 */
+const GIT_MIN_ATTEMPT_MS = 250
+
+/** 通道备注（2026-09-27 加法，面板可见）：通道为什么没试/为什么被跳过，必须留在 job 上。
+ * 旧代码只在"没有任何更具体错误"时才写原因，用户什么都看不到。 */
+function noteChannel(job, text) {
+  if (job === null || job === undefined || typeof text !== 'string' || text === '') return
+  if (!Array.isArray(job.channelNotes)) job.channelNotes = []
+  if (!job.channelNotes.includes(text)) job.channelNotes.push(text)
+}
+
+/** 预算时长的可读写法（≥10 秒按秒、否则按毫秒）——只服务面板文案。 */
+function formatBudgetMs(ms) {
+  const n = Math.max(0, Number(ms) || 0)
+  return n >= 10000 ? `${Math.round(n / 1000)} 秒` : `${Math.round(n)} 毫秒`
+}
+
+/** git 通道（守卫③）：只对**请求里那个仓库**试 git 规格，且只在"同一作业第一次"试。
+ * 返回 { installedName, lastError }（与 tryCandidateChannels 的返回同形，便于原地替换）。
+ * 预算规则（2026-09-27）：
+ *   · 通道自己的预算与**作业剩余预算**取小（deadline 为 null 时只有通道预算）；
+ *   · 单个规格的 pnpm 超时 = min(60 秒, 剩余)；
+ *   · 预算耗尽就停手，并在 job 上留一条面板可见的原因（不静默跳过）。
+ * 依赖注入：ch（通道实现）与 budget 由调用方传入 —— 与 install-job 的注入缝同一套语义。 */
+async function tryGitChannel({ job, ch, name, profileDir, repoChannelAllowed, expanded = false, budget = {}, deadline = null }) {
+  let installedName = null
+  let lastError = null
+  // gitChannelBlocked：作业层面已判定"这个仓库不该走 git"（根包未发布 / 首选候选来自市场索引）。
+  // 调用方算的 repoChannelAllowed 已经含它，这里再独立判一次 —— 语义写在离执行最近的地方，
+  // 单测注入 job 时也不会因为漏算一个布尔量而意外去 clone 一个几百 MB 的仓库。
+  if (!repoChannelAllowed || expanded || job?.gitChannelBlocked === true) return { installedName, lastError }
+  // 独立预算：同一作业里 git 通道只进一次，budget.git/gitDeadline 就是全局那份
+  if (budget.git === undefined) {
+    const cap = Math.max(0, gitChannelBudgetMs())
+    const remain = deadline === null ? cap : Math.max(0, deadline - Date.now())
+    budget.git = Math.min(cap, remain)
+    budget.gitDeadline = Date.now() + budget.git
+    if (budget.git <= 0) noteChannel(job, 'git 通道因预算不足被跳过（作业剩余时间已不足）')
+  }
+  const gitDeadline = budget.gitDeadline ?? (Date.now() + (budget.git ?? 0))
+  const gitSpecs = job.source === 'gitee'
+    ? [`git+https://gitee.com/${job.repo}.git`]
+    : [
+        ...gitCloneUrls(job.repo).map((u) => `git+${u}`),
+        `github:${job.repo}`,
+      ]
+  let gitTried = 0
+  let gitBudgetHit = false
+  for (const spec of gitSpecs) {
+    const remain = gitDeadline - Date.now()
+    if (remain <= GIT_MIN_ATTEMPT_MS) { gitBudgetHit = true; break }
+    gitTried += 1
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      await ch.pnpmInstall(profileDir, spec, undefined, Math.min(GIT_SPEC_TIMEOUT_MS, remain))
+      installedName = name
+      break
+    } catch (gitError) {
+      lastError = gitError
+    }
+  }
+  if (installedName === null && gitBudgetHit && gitTried > 0) {
+    noteChannel(job, `git 通道预算（${formatBudgetMs(budget.git ?? 0)}）已用尽，剩余的 git 源不再尝试`)
+  }
+  return { installedName, lastError }
+}
+
+export { GIT_CHANNEL_BUDGET_MS, GIT_SPEC_TIMEOUT_MS, GIT_MIN_ATTEMPT_MS, gitChannelBudgetMs, noteChannel, formatBudgetMs, tryGitChannel }

package/lib/server/domain/install-cleanup.js

@@ -0,0 +1,62 @@
+// L1 · domain —— install-cleanup.js（安装失败清场 + 授权被拒/超时后的失败文案）
+// 2026-09-27 从 install-job.js 原样搬出（install-job.js 触到 600 行硬顶，见 test-architecture-guard.mjs）。
+// 只搬移、未改逻辑；install-job.js 继续 re-export 这两个名字，调用点与测试的 import 面一个字都没变。
+
+import { existsSync, readdirSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { AI_CONSENT_TIMEOUT_MS } from './install.js'
+import { disposeDir, disposeNote } from '../infra/fsx.js'
+
+/** 安装失败清场：把本次尝试过的候选包目录与 pnpm `_tmp_` 半成品一起清掉，并**如实汇报**清了什么、什么没清掉
+ * （2026-09-20 真装演练：聚合仓库跑 19 分钟后失败，node_modules 留着 `…_tmp_56272_2` 半成品，面板只说"安装失败"）。
+ * 2026-09-26（改错）：删除一律走 disposeDir（本机 C 盘/`%TEMP%` 下 rmSync 会静默落空，不核实就会谎报干净）；
+ * 删不掉时它**改名降级成同父目录的 `.trash-<ts>`**（做法借自 2BingLing/dsh-market 的 `.bak-<ts>` + renameSync）。 */
+function cleanupAttemptedCandidates(profileDir, candidates) {
+  const cleaned = []
+  const failed = []
+  const trashed = []
+  const dispose = (label, dir) => {
+    const result = disposeDir(dir)
+    if (result.trashed === true) trashed.push({ name: label, path: dir, trashPath: result.trashPath, note: disposeNote(result) })
+    if (result.ok === true) return 1
+    failed.push({ name: label, path: dir, error: result.reason, note: disposeNote(result) })
+    return 0
+  }
+  for (const name of candidates) {
+    const dir = join(profileDir, 'node_modules', ...String(name).split('/'))
+    const parent = dirname(dir)
+    const base = basename(dir)
+    let touched = 0
+    if (existsSync(dir)) touched += dispose(name, dir)
+    try {
+      for (const entry of readdirSync(parent)) {
+        if (!entry.startsWith(`${base}_tmp_`)) continue
+        touched += dispose(`${name}（临时目录）`, join(parent, entry))
+      }
+    } catch {}
+    if (touched > 0) cleaned.push(name)
+  }
+  return { cleaned, failed, trashed }
+}
+
+/** 授权被拒/超时后的失败文案（纯函数，单测覆盖）：说清为什么失败、清理了什么、什么没清掉。
+ * 时长取自 AI_CONSENT_TIMEOUT_MS —— 文案里的"10 分钟"不能与实际等待时间脱节。
+ * 2026-09-26（改错）：**不再出现「请手动删除」**——降级成 `.trash-*` 的项由后台清理接手。 */
+function aiConsentFailureText(decision, leftovers, timeoutMs = AI_CONSENT_TIMEOUT_MS) {
+  const waitMinutes = Math.max(1, Math.round((Number(timeoutMs) || AI_CONSENT_TIMEOUT_MS) / 60000))
+  const base = decision?.timeout === true
+    ? `等待授权超时（${waitMinutes} 分钟），已取消本地 AI 兜底（该操作会调用模型 API 产生费用）`
+    : '用户取消本地 AI 兜底（该操作会调用模型 API 产生费用）'
+  const cleaned = leftovers?.cleaned ?? []
+  const failed = leftovers?.failed ?? []
+  const trashed = leftovers?.trashed ?? []
+  const noteOf = (item) => (typeof item?.note === 'string' && item.note !== '' ? `（${item.note}）` : (item?.error != null ? `（${item.error}）` : ''))
+  const cleanedNote = cleaned.length > 0 ? `；已清理本次落盘残留：${cleaned.join('、')}` : ''
+  const trashedNote = trashed.length > 0
+    ? `；有 ${trashed.length} 项正被占用、已改名降级为 .trash-*（${trashed.map((t) => (typeof t?.note === 'string' && t.note !== '' ? t.note : basename(String(t?.trashPath ?? '')))).join('、')}）`
+    : ''
+  const failedNote = failed.length > 0 ? `；**有 ${failed.length} 项没能清理**：${failed.map((f) => `${f.path}${noteOf(f)}`).join('、')}` : ''
+  return `${base}${cleanedNote}${trashedNote}${failedNote}`
+}
+
+export { cleanupAttemptedCandidates, aiConsentFailureText }