@noob-stupid/dsh-plugin-console 0.5.46 → 0.5.47

package/lib/server/domain/market.js

@@ -6,7 +6,12 @@ import { readFile } from 'node:fs/promises'
 import { dirname, join } from 'node:path'
 import { detectSkillRepo } from './skills.js'
 import { dshMarkersOf } from './subdir-detect.js'
-import { FETCH_OK, FETCH_UNREACHABLE, GITHUB_API, curlJson, curlText, fetchJsonUrl, githubJson, looksLikeGitmodules, rawTextFetch, rawTextWithFallback } from '../infra/http.js'
+// 0.5.47 接线：仓库引用 → 仓库标识的解析切到叶子模块（两个方向都要用，见 repo-url.js 顶部）
+import { parseRepoFromUrl } from './repo-url.js'
+import { landedManifestText, landedRepoDir } from './landed-source.js'
+import { repoMatchedRegistryChannels } from './repo-package-match.js'
+import { probeChannelLine, probeFailureLines, composeProbeFailureText } from './probe-outcome.js'
+import { FETCH_OK, FETCH_UNREACHABLE, GITHUB_API, channelLabel, channelFailureSummary, curlJson, curlText, fetchJsonUrl, githubJson, looksLikeGitmodules, rawTextFetch, rawTextWithFallback } from '../infra/http.js'
 import { ENRICH_CACHE_FILE, baseDirOf, marketIndexCacheFile, resolvePackageJson } from '../infra/paths.js'
 
 function readEnrichCache() {
@@ -161,17 +166,8 @@ function githubRepoInfo(repo) {
   return `${match[1]}/${match[2]}`
 }
 
-/** 从 npm 的 repository 字段解析出 GitHub/Gitee 仓库标识（纯函数，单测覆盖）。
- * 支持 `https://github.com/o/r.git`、`git+https://…`、`git://…`、带 `#path` 的 monorepo 写法。 */
-function parseRepoFromUrl(url) {
-  const raw = String(url ?? '').trim()
-  // npm 老式简写：`github:owner/repo` / `gitee:owner/repo`
-  const shorthand = raw.match(/^(?:github|gitee):([^/\s]+)\/([^/\s#?]+?)(?:\.git)?(?:[#?].*)?$/u)
-  if (shorthand !== null) return `${shorthand[1]}/${shorthand[2]}`
-  const m = raw.match(/(?:github\.com|gitee\.com)[/:]([^/\s]+)\/([^/\s#?]+?)(?:\.git)?(?:[#?].*)?$/u)
-  if (m === null) return null
-  return `${m[1]}/${m[2]}`
-}
+// `parseRepoFromUrl` 已切到叶子模块 domain/repo-url.js（0.5.47）：repo-package-match.js 也要用它，
+// 而那个模块被本文件 import —— 留在本文件就会成环。这里只 import + re-export，导出名与语义一字未变。
 
 /** 结果里是否已有"名字逐词命中查询词"的条目——决定要不要再加 `in:readme` 重查一次。
  * （仓库搜索的检索面只有 名字/描述/topics；README 里的词必须显式 in:readme 才查得到） */
@@ -285,24 +281,72 @@ async function searchSubpackageItems(query, token = null, signal = null) {
   return subItems
 }
 
-/** 包探测（带失败原因）：reason ∈ ok / not-found / unreachable / invalid。
+/** 包探测（带失败原因 + **通道身份** + 逐条失败原因）：reason ∈ ok / not-found / unreachable / invalid。
  * 事故（2026-09-20，另一位用户：Android + proot Ubuntu，容器无 IPv6 路由）：
  * 抓取超时与真 404 都让上层拿到同一个 null，于是「网络太慢」被报成「仓库没有 package.json」，
- * 用户与日志都被误导。现在把两种结局分开，文案也分开。 */
-async function fetchRepoPackageEx(repo, branch) {
-  const { state, body } = await rawTextFetch(repo, branch, 'package.json')
-  if (state !== FETCH_OK) return { pkg: null, reason: state }
+ * 用户与日志都被误导。现在把两种结局分开，文案也分开。
+ *
+ * ★ 0.5.47 接线（**上一批的错就在这一行**：`rawTextFetch(repo, branch, 'package.json')` 一个 deps
+ * 都没传，于是 http.js 里那段 extraChannels 注入缝**根本不可达**）—— 现在真正接上两条额外通道：
+ *   ① 本地落地（domain/landed-source.js）：命中 ⇒ 零网络、零超时地读到清单，并带出本地目录
+ *      （"一键从本地安装"要用的是**目录**）；
+ *   ② npm registry（domain/repo-package-match.js）：按 `repository` 字段把仓库引用匹配到包，
+ *      匹配上 ⇒ 读该包在 registry 上的清单；镜像优先（npmmirror）→ 官方兜底，各带上限。
+ * 返回里多几项（**纯加法**，老调用点解构 `{ pkg, reason }` 一字不用改）：
+ *   `channel`/`label`（胜出通道）、`failures`/`summary`（逐条原因）、`registryNotes`（匹配过程）、
+ *   `localDir`（本地落地命中目录）、`packageName`（清单里的包名）。
+ * `deps.roots` = 「仓库落地」目录候选根（调用方传 `getReposDir()`）；`deps.packageNames` = 首选包名
+ * 提示（市场索引 npmName）；其余 deps 原样透传给 registry 通道（单测注入用）。 */
+async function fetchRepoPackageEx(repo, branch, deps = {}) {
+  const roots = deps.roots ?? []
+  const packageNames = Array.isArray(deps.packageNames) ? deps.packageNames : []
+  const extraChannels = []
+  const localDir = landedRepoDir(repo, roots, deps)
+  if (localDir !== null) extraChannels.push({ id: 'local', label: channelLabel('local'), run: () => landedManifestText(repo, roots, deps) })
+  const registryChannels = deps.registryChannels ?? repoMatchedRegistryChannels(repo, { packageNames, deps })
+  for (const ch of registryChannels) extraChannels.push(ch)
+  const { state, body, channel, failures } = await rawTextFetch(repo, branch, 'package.json', deps.budgetMs, { ...deps, extraChannels })
+  const info = {
+    channel: channel ?? null, label: channel === null ? null : channelLabel(channel),
+    failures: Array.isArray(failures) ? failures : [], summary: channelFailureSummary(failures),
+    packageName: null, localDir: null, registryNotes: Array.isArray(deps.registryNotes) ? deps.registryNotes : [],
+  }
+  if (state !== FETCH_OK) return { pkg: null, reason: state, ...info }
   try {
     const pkg = JSON.parse(body)
-    if (pkg !== null && typeof pkg === 'object' && typeof pkg.name === 'string') return { pkg, reason: 'ok' }
+    if (pkg !== null && typeof pkg === 'object' && typeof pkg.name === 'string') {
+      info.packageName = pkg.name
+      if (channel === 'local') info.localDir = localDir
+      return { pkg, reason: 'ok', ...info }
+    }
   } catch {}
-  return { pkg: null, reason: 'invalid' }
+  return { pkg: null, reason: 'invalid', ...info }
 }
 
 async function fetchRepoPackage(repo, branch) {
   return (await fetchRepoPackageEx(repo, branch)).pkg
 }
 
+/** 读仓库里**指定路径**的文件文本（2026-10-13 加法，子目录插件安装用）：`<子目录>/package.json`。
+ *
+ * 为什么要单开一个入口：子目录安装必须先**核实那份清单**（是不是 DSH 插件、包名是什么），
+ * 而这条路此前只能读仓库根（fetchRepoPackageEx 写死 'package.json'）。判据刻意与根探测同一把尺子。
+ *
+ * 出网收口（与单测红线同一条缝）：走 `__setSubpkgProbeDefaults({ rawText })` ——
+ * 单测把回落值换成**会抛的 tripwire** ⇒ 真有代码走到真实出网会当场红、且一个请求都发不出去
+ * （与 routes/components.js 的 `__setOpenFolderSpawn` 同一套做法：进程与出网各收一个可注入单点；
+ * 测试**不许**给 node:child_process / 任何 ESM 命名空间打补丁）。生产不注入 ⇒ 回落真实现。
+ * 返回文本；404 / 超时 / 不可达 / 空 body 一律 null —— 调用方负责把"没读到"与"没有"分开表达。 */
+async function fetchRepoPathText(repo, branch, path, deps = {}) {
+  const read = typeof deps.rawText === 'function' ? deps.rawText : probeEgressDefaults?.rawText
+  if (typeof read === 'function') {
+    const text = await read(repo, branch, path)
+    return typeof text === 'string' && text.trim() !== '' ? text : null
+  }
+  const { state, body } = await rawTextFetch(repo, branch, path)
+  return state === FETCH_OK ? body : null
+}
+
 /** 探测失败时的用户可读文案：「抓取超时/不可达」与「真的没有」必须区分开。 */
 function packageProbeErrorText(repo, branch, reason) {
   if (reason === FETCH_UNREACHABLE) {
@@ -538,4 +582,4 @@ async function subpackageCandidates(repo, branch, auth) {
 
 const ENRICH_CACHE_TTL = 24 * 60 * 60 * 1000
 
-export { readEnrichCache, writeEnrichCache, enrichItemOne, enrichItems, normalizePlatformItems, githubRepoInfo, fetchRepoPackage, fetchRepoPackageEx, packageProbeErrorText, searchNpmPackages, searchSubpackageItems, parseRepoFromUrl, hasDirectNameHit, summarizeReadme, readPluginDetails, fetchSubpackageNames, fetchSubpackageNamesOnBranch, fetchSubdirPlugins, subpackageBranchOrder, subpackageCandidates, expandSubpackageCandidates, npmNameHintForRepo, applyNpmNameHint, ENRICH_CACHE_TTL, __setSubpkgProbeDefaults }
+export { readEnrichCache, writeEnrichCache, enrichItemOne, enrichItems, normalizePlatformItems, githubRepoInfo, fetchRepoPackage, fetchRepoPackageEx, fetchRepoPathText, packageProbeErrorText, searchNpmPackages, searchSubpackageItems, parseRepoFromUrl, hasDirectNameHit, summarizeReadme, readPluginDetails, fetchSubpackageNames, fetchSubpackageNamesOnBranch, fetchSubdirPlugins, subpackageBranchOrder, subpackageCandidates, expandSubpackageCandidates, npmNameHintForRepo, applyNpmNameHint, ENRICH_CACHE_TTL, probeChannelLine, probeFailureLines, composeProbeFailureText, __setSubpkgProbeDefaults }

package/lib/server/domain/presence-check.js

@@ -0,0 +1,121 @@
+// L1 · domain —— presence-check.js（"它其实已经装上了"的只读核实）
+//
+// 缺口（2026-10-13 用户实测 `corrinehu/dsh-workbuddy-connect`，报「抓取超时」）：
+// 那个插件**当时其实已经装好了**（profile dependencies 里有 `^0.7.2`、`dsh.profile.bundles`
+// 里有它、node_modules 下也有实体目录），可面板给的是一句网络失败 —— 用户以为没装上，
+// 于是反复重装。**报"安装失败"之前必须先核实"是不是已经装上了"**。
+//
+// 判据（三处独立事实，全部只读，零网络）：
+//   ① `<profile>/node_modules/<name>/package.json` 能解析且 name 完全相等 → 物在盘上（最硬的一条）
+//   ② `<profile>/package.json` 的 dependencies / devDependencies 里有这个 name（装过并钉住的痕迹）
+//   ③ `<profile>/package.json` 的 `dsh.profile.bundles` 里有这个 name（装配链已认它）
+// 三者**分开如实汇报**：只有 ① 能说"已安装"；只有 ②③ 而没有 ①，说明"声明在、物不在"
+// （正是 0.4.x 那类"装了没钉住 / 删了目录没删声明"的现场）—— 那种情况必须说清缺什么，
+// 不能跟着报成功（与 manifest.js#fallbackNoteOf 的诚实口径一致）。
+//
+// 分层：本文件属 L1 · domain —— 不得出现 cordis ctx（test-architecture-guard 断言⑤）。
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** 读 profile 根 package.json（解析失败/不存在一律 null，绝不抛）。 */
+function readProfilePkg(profileDir, deps = {}) {
+  const exists = deps.exists ?? existsSync
+  const read = deps.read ?? ((file) => readFileSync(file, 'utf8'))
+  try {
+    const file = join(String(profileDir ?? ''), 'package.json')
+    if (!exists(file)) return null
+    const parsed = JSON.parse(read(file))
+    return parsed !== null && typeof parsed === 'object' ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/** 核实一个包是否已在某个 profile 里（三处事实分开返回）。`pkgName` 为空/非法 → installed=false。
+ * 返回 `{ installed, packageName, version, sources, missing, message }`：
+ *   · installed=true  → ① 命中（物在盘上），可直接对用户说"已安装 vX（无需重装）"
+ *   · installed=false → `missing` 列出"有声明没实体"的那些痕迹，供上层拼诚实文案 */
+function checkPluginPresence(profileDir, pkgName, deps = {}) {
+  const name = typeof pkgName === 'string' ? pkgName.trim() : ''
+  const out = { installed: false, packageName: name, version: null, sources: [], missing: [], message: '' }
+  if (name === '') return out
+  const exists = deps.exists ?? existsSync
+  const read = deps.read ?? ((file) => readFileSync(file, 'utf8'))
+  const nodeModulesDir = join(String(profileDir ?? ''), 'node_modules')
+  // ① 物在盘上（最硬的一条）
+  try {
+    const manifest = join(nodeModulesDir, name, 'package.json')
+    if (exists(manifest)) {
+      let parsed = null
+      try { parsed = JSON.parse(read(manifest)) } catch { parsed = null }
+      if (parsed !== null && typeof parsed === 'object' && parsed.name === name) {
+        out.installed = true
+        out.version = typeof parsed.version === 'string' ? parsed.version : null
+        out.sources.push('node_modules')
+        out.message = `已安装 ${name}${out.version === null ? '' : ` v${out.version}`}（无需重装）`
+        return out
+      }
+      // 目录在但清单读不出来/名字对不上：不算已安装，但值得如实说明（半成品目录）
+      out.missing.push(`node_modules/${name}（清单读不出来或 name 不匹配）`)
+    }
+  } catch {}
+  // ② / ③ 声明层痕迹（agent 面板与官方插件页看见的就是它们）
+  const pkg = readProfilePkg(profileDir, deps)
+  try {
+    const depsObj = pkg?.dependencies
+    const devDepsObj = pkg?.devDependencies
+    if (depsObj !== null && typeof depsObj === 'object' && typeof depsObj[name] === 'string') out.sources.push('dependencies')
+    if (devDepsObj !== null && typeof devDepsObj === 'object' && typeof devDepsObj[name] === 'string') out.sources.push('devDependencies')
+    const bundles = pkg?.dsh?.profile?.bundles
+    if (Array.isArray(bundles) && bundles.includes(name)) out.sources.push('dsh.profile.bundles')
+  } catch {}
+  if (out.sources.length > 0) {
+    out.missing.push(`node_modules/${name}（物不在盘上）`)
+    out.message = `声明里有 ${name}（${out.sources.join('、')}），但 ${out.missing.join('、')} —— 这是"装了没装完整"，需要重装一次`
+  }
+  return out
+}
+
+/** 从仓库名猜包名候选（`owner/dsh-foo` → `dsh-foo`）。
+ * 只用于**兜底核实**（市场索引的 npmNameHint 才是首选口径）：用户点的是仓库，
+ * 而插件包名多半就是仓库名去掉 owner（实测 `corrinehu/dsh-workbuddy-connect` → `dsh-workbuddy-connect`）。
+ * 猜错无害：核实失败就照旧报网络错误，绝不会因为"猜中"而谎报已安装（名字必须完全相等）。 */
+function packageNameCandidates(repo, extra = []) {
+  const out = []
+  const push = (value) => {
+    const text = typeof value === 'string' ? value.trim() : ''
+    if (text !== '' && !out.includes(text)) out.push(text)
+  }
+  for (const value of extra) push(value)
+  const full = String(repo ?? '').trim().replace(/\.git$/u, '')
+  if (full.includes('/')) push(full.split('/').pop())
+  return out
+}
+
+/** 在候选名里找**第一个**真的已装上的（物在盘上）。
+ * 返回 checkPluginPresence 的结果或 null。多个候选只回报第一次命中 —— 不猜、不合并。 */
+function firstInstalledPresence(profileDir, names, deps = {}) {
+  for (const name of Array.isArray(names) ? names : [names]) {
+    const res = checkPluginPresence(profileDir, name, deps)
+    if (res.installed) return res
+  }
+  return null
+}
+
+/** 本地落地命中时给用户的"一键从本地安装"落点：目录 + 既有本地目录来源的规格。
+ * 规格用 `link:` —— 与仓库既有约定一致（source-spec.js 判据 C / subdir-install.js：
+ * `pnpm add link:<目录>` 就是本地目录的正常形态，依赖由 link 自足性补齐），不另发明协议。 */
+function localInstallHint({ dir, packageName = null } = {}) {
+  const text = typeof dir === 'string' ? dir.trim() : ''
+  if (text === '') return null
+  const spec = `link:${text.replace(/\\/gu, '/')}`
+  return {
+    dir: text,
+    spec,
+    packageName: typeof packageName === 'string' && packageName !== '' ? packageName : null,
+    note: `已从「仓库落地」本地目录读到清单：${text} —— 可按本地目录安装（${spec}），无需等网络`,
+  }
+}
+
+export { readProfilePkg, checkPluginPresence, packageNameCandidates, firstInstalledPresence, localInstallHint }

package/lib/server/domain/probe-outcome.js

@@ -0,0 +1,58 @@
+// L1 · domain —— probe-outcome.js（探测结果的**通道身份 / 逐条失败原因 / 已装核实**收口；0.5.47 加法）
+//
+// 为什么单开一个模块：install-job.js 贴着 600 行架构硬顶（test-architecture-guard 断言①），
+// 而"清单是怎么读到的、失败了都试过谁、其实是不是已经装上了"这三件事本身就是一段有判据、
+// 可离线测的纯逻辑；放在 market.js 里还会把它顶过 600 行（本轮就撞上了）。
+//
+// 三层内容：
+//   ① 通道身份：成功时如实说"经哪条通道读到的"（本地落地 / npm 镜像 / …），不再只说失败；
+//   ② 逐条失败原因：全失败时**逐条**列出"通道 + 各自为什么没成"（用户红线：不许一句 unreachable 带过）；
+//   ③ 已装核实：报"失败"之前先核实"是不是其实已经装上了"（判据在 domain/presence-check.js，只读零网络）。
+//
+// 分层：本文件属 L1 · domain —— 不得出现 cordis ctx（test-architecture-guard 断言⑤）。
+
+import { channelFailureSummary, channelLabel } from '../infra/http.js'
+/** ★胜出通道身份（0.5.47）：成功时如实告诉用户"清单是**经哪条通道**读到的"
+ * （本地落地 / npm 镜像 / npm 官方源 / https / gh CLI / curl 直连 / jsDelivr）。
+ * 为什么必须带出来：用户被"抓取超时"误导过一次 —— 面板只说失败、不说试过什么，
+ * 于是既不知道能不能换源、也不知道其实本地就有。 */
+function probeChannelLine(probe) {
+  if (probe === null || typeof probe !== 'object') return null
+  const channel = typeof probe.channel === 'string' && probe.channel !== '' ? probe.channel : null
+  if (channel === null) return null
+  const name = typeof probe.packageName === 'string' && probe.packageName !== '' ? `（${probe.packageName}）` : ''
+  if (channel === 'local') {
+    const dir = typeof probe.localDir === 'string' && probe.localDir !== '' ? `：${probe.localDir}` : ''
+    return `清单来自「仓库落地」本地目录${dir}${name}`
+  }
+  return `清单经 ${channelLabel(channel)} 读到${name}`
+}
+
+/** 失败时的逐条原因清单（字符串行数组；空 = 一个原因都没收到）。
+ * 收 `summary`（已经拼好的文本）与 `failures`（结构化数组）两种形态：install-job 下发的
+ * `job.probe` 是前者，`fetchRepoPackageEx` 的返回是后者，两条路都要能出清单。 */
+function probeFailureLines(probe) {
+  if (probe === null || typeof probe !== 'object') return []
+  const summary = typeof probe.summary === 'string' && probe.summary !== ''
+    ? probe.summary
+    : channelFailureSummary(probe.failures)
+  return summary === '' ? [] : summary.split('\n')
+}
+
+/** ★全通道失败时的诚实文案：既有 baseText（**保留现文案**）+ 逐条「通道：原因」+ registry 匹配备注。
+ * 用户红线：**不许一句 unreachable 带过** —— 每条通道各自为什么没成都要看得见。 */
+function composeProbeFailureText(probe, baseText) {
+  const base = typeof baseText === 'string' && baseText !== '' ? baseText : '抓取仓库清单失败'
+  const lines = probeFailureLines(probe)
+  const notes = Array.isArray(probe?.registryNotes) ? probe.registryNotes.filter((n) => typeof n === 'string' && n !== '') : []
+  const parts = [base]
+  if (lines.length > 0) parts.push(`各通道的失败原因：\n${lines.join('\n')}`)
+  if (notes.length > 0) parts.push(`npm registry 核对（按 repository 字段匹配，不靠猜名）：\n${notes.map((n) => `· ${n}`).join('\n')}`)
+  return parts.join('\n')
+}
+
+// 「报失败之前先核实其实已经装上了」的**实现归属**：domain/install-verify.js 的
+// installedEvidence / failedJobEvidence（0.5.47 那批已接在 routes/install-status 与 routes/state 两处）。
+// 本模块只管"这次探测是怎么读到的 / 为什么没读到"，不重复实现核实 —— 同一件事只留一个承担者。
+
+export { probeChannelLine, probeFailureLines, composeProbeFailureText }

package/lib/server/domain/registry-manifest.js

@@ -0,0 +1,102 @@
+// L1 · domain —— registry-manifest.js（npm registry 上的**包清单**通道：packument 元数据）
+//
+// 缺口（2026-10-13 用户实测 `corrinehu/dsh-workbuddy-connect` 报「抓取超时」）：
+// 「抓仓库清单」这一步的 4 条通道**全部指向 GitHub**（raw / api / gh CLI / jsDelivr CDN）——
+// GitHub 一挂，整个探测就完；而**同一个包在 npm 上好好的**（该插件确实已发布：name
+// `dsh-workbuddy-connect`、version 0.7.3）。registry 是另一条完全独立的网络路径
+// （国内还有 npmmirror 镜像），把它接进探测链就能救回这一整类"GitHub 不通但 npm 通"的失败。
+//
+// 取的是 registry 的 **packument /latest 文档**：它本身就是这个包的 package.json 清单
+// （name / version / private / dsh 标记 / repository …），无需下载 tarball 再解压 —— 一次 GET，
+// 与"读仓库清单"的产物同构，因此可以直接进同一条竞速链。
+//
+// 顺序（按可达性）：npmmirror 镜像优先 → 官方 registry 兜底；各带上限（见 REGISTRY_TIMEOUT_MS）。
+// **安全**：镜像与官方一视同仁 —— 拿回来的文本照样过上游的 JSON 解析 + name 字段校验，
+// 回退通道不降低任何校验标准。
+//
+// 分层：本文件属 L1 · domain —— 不得出现 cordis ctx（test-architecture-guard 断言⑤）。
+
+import { curlText } from '../infra/http.js'
+
+/** 单条 registry 通道的请求上限。两条串行（镜像→官方）最坏 ≈2×8s，与既有 4 条通道并行，
+ * 不额外拉长整体等待（外层还有 FETCH_BUDGET_MS 兜底）。 */
+const REGISTRY_TIMEOUT_MS = 8000
+const NPM_MIRROR = 'https://registry.npmmirror.com'
+const NPM_OFFICIAL = 'https://registry.npmjs.org'
+
+/** 只接受合法 npm 包名（外部索引/环境给的名字不得拿去拼 URL 路径）。
+ * 与 market.js#npmNameHintForRepo 同一判据（那里也在拦外部数据）。 */
+function isSafePackageName(name) {
+  return /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/u.test(String(name ?? ''))
+}
+
+/** scoped 包名的路径形式：`@scope/name` → `@scope%2Fname`（registry 也接受未编码的 `/`，
+ * 但编码后对镜像更稳）。非 scoped 原样返回。 */
+function registryPathOf(name) {
+  const text = String(name ?? '')
+  return text.startsWith('@') ? text.replace('/', '%2F') : text
+}
+
+/** 读一个包在某个 registry 上的清单**文本**（`<registry>/<name>/latest`）。
+ * 返回 string = 读到了；返回 null = 这个 registry 上**确定没有**这个包（404）
+ *   —— 或（0.5.47 加法）文档的 `repository` 字段**指向的不是调用方要的那个仓库**：
+ *   本模块只负责"取回来"，"是不是本仓库的包"由 repo-package-match.js 判；
+ *   但一旦调用方给了 `expectedRepo`，不匹配就必须当成"没读到"（**不猜名**：名字像不算命中）。
+ * 抛异常 = 通道本身失败（网络/超时/5xx），由竞速记录成"这条通道为什么没成"。
+ * deps.text 只为单测注入（生产走 curlText，绕开 node:https 的 TLS 指纹拦截）。 */
+async function registryManifestText(name, registry = NPM_MIRROR, deps = {}) {
+  if (!isSafePackageName(name)) throw new Error('包名不合法，拒绝请求 registry')
+  const text = deps.text ?? curlText
+  const url = `${String(registry).replace(/\/+$/u, '')}/${registryPathOf(name)}/latest`
+  const timeout = Number.isFinite(deps.timeoutMs) && deps.timeoutMs > 0 ? deps.timeoutMs : REGISTRY_TIMEOUT_MS
+  try {
+    const body = await text(url, timeout, { ipv4: true })
+    const trimmed = typeof body === 'string' ? body.trim() : ''
+    if (trimmed === '') throw new Error('registry 返回空响应')
+    if (typeof deps.expectedRepo === 'string' && deps.expectedRepo !== '' && !repoFieldMatches(trimmed, deps.expectedRepo)) return null
+    return trimmed
+  } catch (error) {
+    // 404 = 该源上没有这个包（确定性结论，交回上层按 not-found 处理，不再上升为通道失败）
+    if (error instanceof Error && /HTTP 404|404/u.test(error.message)) return null
+    throw error
+  }
+}
+
+/** 文档的 `repository` 字段是否指向这个仓库（归一化比较：忽略大小写 / `.git` / `git+` / `#path`）。
+ * 这里做**宽松**判定（只回答"像不像同一个仓库"），严格判定在 repo-package-match.js。
+ * 拿不到 repository 字段 ⇒ 一律不匹配（没有证据就不认账）。 */
+function repoFieldMatches(manifestText, repo) {
+  let parsed = null
+  try { parsed = JSON.parse(manifestText) } catch { return false }
+  const raw = parsed?.repository ?? parsed?.latest?.repository ?? null
+  const url = typeof raw === 'string' ? raw : (raw !== null && typeof raw === 'object' ? raw.url : null)
+  const norm = (value) => String(value ?? '').trim().toLowerCase()
+    .replace(/^git\+/u, '').replace(/\.git(?=$|[#?])/u, '').replace(/^\/+|\/+$/gu, '')
+  const want = norm(repo)
+  if (want === '' || typeof url !== 'string' || url === '') return false
+  const text = norm(url)
+  // 认 https://github.com/o/r、git://github.com/o/r、github:o/r、ssh://git@github.com/o/r 这些写法
+  const tail = text.replace(/^[a-z+]+:\/\//u, '').replace(/^[^@/]*@/u, '').replace(/^[a-z]+:/u, '')
+  const path = tail.replace(/^[^/]+\//u, '')
+  return tail === want || path === want || tail.endsWith(`/${want}`) || text.includes(want)
+}
+
+/** 探测链的 registry 通道描述列表（顺序即优先级：npmmirror → 官方）。
+ * `deps.text` 注入后两条通道共用（单测离线用）；生产不传。 */
+function registryManifestChannels(name, deps = {}) {
+  if (!isSafePackageName(name)) return []
+  return [
+    {
+      id: 'npm-mirror',
+      label: 'npm 镜像',
+      run: () => registryManifestText(name, NPM_MIRROR, deps),
+    },
+    {
+      id: 'npm-official',
+      label: 'npm 官方源',
+      run: () => registryManifestText(name, NPM_OFFICIAL, deps),
+    },
+  ]
+}
+
+export { REGISTRY_TIMEOUT_MS, NPM_MIRROR, NPM_OFFICIAL, isSafePackageName, registryPathOf, registryManifestText, registryManifestChannels, repoFieldMatches }

package/lib/server/domain/repo-package-match.js

@@ -0,0 +1,135 @@
+// L1 · domain —— repo-package-match.js（**按 `repository` 字段把仓库引用匹配到 npm 包**；0.5.47 加法）
+//
+// 缺口（与 0.5.46 同源的真机现场）：用户按**仓库引用**（`corrinehu/dsh-workbuddy-connect`）安装时，
+// 「抓仓库清单」这一步四条通道全指向 GitHub，GitHub 一挂整条路就断；而同一个包在 npm 上好好的。
+// 要把 registry 接进回退链，先得回答"这个仓库**对应哪个 npm 包**"。
+//
+// 判据（用户红线）：**不靠猜名** —— 名字只是候选，命中的唯一凭据是 registry 文档里
+// `repository` 字段**逐字符指向这个仓库**（归一化后相等：忽略大小写、忽略 `.git` 后缀，
+// 认 `git+https://` / `git://` / `github:o/r` / `#path` 这些写法，见 market.js#parseRepoFromUrl）。
+// 名字猜错无害（匹配不上就当作"没这条通道"）；名字猜对也**不会**因为"名字像"就认账。
+//
+// 数据结构（registry `<name>/latest` 文档 = 该版本的 package.json）：
+//   `{ name, version, repository: "https://github.com/o/r" | { url } | "github:o/r", … }`
+// 取 `repository` 时两处都看：`latest.repository` 与顶层 `repository`（历史包两种都出现过）。
+//
+// 分层：本文件属 L1 · domain —— 不得出现 cordis ctx（test-architecture-guard 断言⑤）。
+
+import { parseRepoFromUrl } from './repo-url.js'
+import { isSafePackageName, registryManifestText, NPM_MIRROR, NPM_OFFICIAL } from './registry-manifest.js'
+
+/** 仓库引用归一化：去空白、去 `git+`、去 `.git` 后缀、去首尾斜杠、统一小写。 */
+function normalizeRepoRef(repo) {
+  return String(repo ?? '')
+    .trim()
+    .replace(/^git\+/u, '')
+    .replace(/\.git$/u, '')
+    .replace(/^\/+|\/+$/gu, '')
+    .toLowerCase()
+}
+
+/** 从 registry 文档里取 `repository` 的仓库标识（认字符串 / `{ url }` / 老式简写）。
+ * 取不到 → null（**不猜**：没有 `repository` 字段的包不参与按仓库匹配）。 */
+function repositoryRefOf(manifest) {
+  if (manifest === null || typeof manifest !== 'object') return null
+  const raw = manifest.repository ?? manifest.latest?.repository ?? null
+  const url = typeof raw === 'string' ? raw : (raw !== null && typeof raw === 'object' ? raw.url : null)
+  const parsed = parseRepoFromUrl(url)
+  return parsed === null ? null : normalizeRepoRef(parsed)
+}
+
+/** 这份 registry 文档指向哪个仓库（解析不出 ⇒ null）。 */
+function manifestRepoRef(manifestText) {
+  let parsed = null
+  try { parsed = JSON.parse(String(manifestText)) } catch { return null }
+  return repositoryRefOf(parsed)
+}
+
+/** 候选包名：显式给的首选（市场索引 npmName / 调用方）在前，其次**仓库名本身**去 owner。
+ * 只保留合法 npm 包名（外部数据不拿去拼 URL）。**不生成 scoped 变体**：那是猜名，本模块口径是不猜。 */
+function candidatePackageNames(repo, extra = []) {
+  const out = []
+  const push = (value) => {
+    const text = typeof value === 'string' ? value.trim() : ''
+    if (text !== '' && isSafePackageName(text) && !out.includes(text)) out.push(text)
+  }
+  for (const value of Array.isArray(extra) ? extra : [extra]) push(value)
+  const full = String(repo ?? '').trim().replace(/\.git$/u, '')
+  if (full.includes('/')) push(full.split('/').filter((p) => p !== '').pop())
+  return out
+}
+
+/** registry 源的候选（顺序即优先级：npmmirror 镜像优先 → 官方兜底）。 */
+function registrySources(deps = {}) {
+  const given = Array.isArray(deps.registries) ? deps.registries.filter((r) => r !== null && typeof r?.url === 'string' && r.url !== '') : []
+  if (given.length > 0) return given
+  return [
+    { id: 'npm-mirror', label: 'npm 镜像', url: NPM_MIRROR },
+    { id: 'npm-official', label: 'npm 官方源', url: NPM_OFFICIAL },
+  ]
+}
+
+/** 按仓库引用在 registry 上找包：返回 `{ hit, packageName, text, registry, channel, label, notes }`。
+ *   · hit=true  ⇒ `repository` 字段逐字符指向本仓库（证据来自 registry 文档本身，不是名字像）
+ *   · hit=false ⇒ notes 里逐条写明"哪个候选在哪个源上：没有这个包 / 不是这个仓库 / 通道失败"
+ * 每个源上逐个候选试（候选很少，且每步都有上限）；deps.text/registries/timeoutMs 只为单测注入。 */
+async function resolvePackageByRepo(repo, { packageNames = [], deps = {} } = {}) {
+  const notes = []
+  const want = normalizeRepoRef(repo)
+  if (want === '') return { hit: false, packageName: null, text: null, registry: null, channel: null, label: null, notes: ['仓库引用为空，未查 registry'] }
+  const names = candidatePackageNames(repo, packageNames)
+  if (names.length === 0) return { hit: false, packageName: null, text: null, registry: null, channel: null, label: null, notes: ['没有可用作候选的合法 npm 包名（不猜名，跳过 registry 通道）'] }
+  for (const source of registrySources(deps)) {
+    for (const name of names) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const text = await registryManifestText(name, source.url, deps)
+        if (text === null) {
+          notes.push(`${name} @ ${source.label}：registry 上没有这个包（404）`)
+          continue
+        }
+        const ref = manifestRepoRef(text)
+        if (ref === null) {
+          notes.push(`${name} @ ${source.label}：文档里没有可解析的 repository 字段，无法证明它就是这个仓库`)
+          continue
+        }
+        if (ref !== want) {
+          notes.push(`${name} @ ${source.label}：仓库字段指向 ${ref}，不是 ${want}`)
+          continue
+        }
+        return { hit: true, packageName: name, text, registry: source.url, channel: source.id, label: source.label, notes }
+      } catch (error) {
+        notes.push(`${name} @ ${source.label}：通道失败（${error instanceof Error ? error.message : String(error)}）`)
+      }
+    }
+  }
+  return { hit: false, packageName: null, text: null, registry: null, channel: null, label: null, notes }
+}
+
+/** 把"按仓库匹配"接上既有 registry 探测链：返回**带 repository 校验**的通道（顺序同 registrySources）。
+ * 未命中 ⇒ null（"这个候选不是本仓库的包"，与 404 同一出口；**不冒充**"这个包不存在"）；
+ * 命中 ⇒ 该包在 registry 上的清单文本（与"读仓库里的 package.json"同构，直接进同一条竞速链）。
+ * 回退不降低校验标准：镜像与官方一视同仁，都过 `repository` 字段这一关。 */
+function repoMatchedRegistryChannels(repo, { packageNames = [], deps = {} } = {}) {
+  const want = normalizeRepoRef(repo)
+  const names = candidatePackageNames(repo, packageNames)
+  if (want === '' || names.length === 0) return []
+  return registrySources(deps).map((source) => ({
+    id: source.id,
+    label: `${source.label}（按 repository 字段核对）`,
+    run: async () => {
+      for (const name of names) {
+        // eslint-disable-next-line no-await-in-loop
+        const text = await registryManifestText(name, source.url, deps)
+        if (text === null) continue
+        if (manifestRepoRef(text) === want) return text
+      }
+      return null
+    },
+  }))
+}
+
+export {
+  normalizeRepoRef, repositoryRefOf, manifestRepoRef, candidatePackageNames,
+  registrySources, resolvePackageByRepo, repoMatchedRegistryChannels,
+}

package/lib/server/domain/repo-url.js

@@ -0,0 +1,23 @@
+// L1 · domain —— repo-url.js（仓库引用 ↔ 仓库 URL 的归一与解析；0.5.47 从 market.js 切出）
+//
+// 为什么单开一个叶子模块：`parseRepoFromUrl` **两个方向都要用** —— market.js 的 npm 包名搜索
+// （packument 的 repository.url → 仓库标识）与 repo-package-match.js 的"按 repository 字段匹配仓库"。
+// 后者被 market.js import，若它还回头 import market.js 就成环（ESM 环里 TDZ 会让其中一个拿到 undefined）。
+// 放到叶子模块后两边都只向下依赖，方向单向、可静态断言。
+//
+// 分层：本文件属 L1 · domain —— 不得出现 cordis ctx（test-architecture-guard 断言⑤）。
+
+/** 从 npm 的 repository 字段解析出 GitHub/Gitee 仓库标识（纯函数，单测覆盖）。
+ * 支持 `https://github.com/o/r.git`、`git+https://…`、`git://…`、`ssh://git@github.com/o/r`、
+ * `github:o/r` / `gitee:o/r` 简写、带 `#path` 的 monorepo 写法。 */
+function parseRepoFromUrl(url) {
+  const raw = String(url ?? '').trim()
+  // npm 老式简写：`github:owner/repo` / `gitee:owner/repo`
+  const shorthand = raw.match(/^(?:github|gitee):([^/\s]+)\/([^/\s#?]+?)(?:\.git)?(?:[#?].*)?$/u)
+  if (shorthand !== null) return `${shorthand[1]}/${shorthand[2]}`
+  const m = raw.match(/(?:github\.com|gitee\.com)[/:]([^/\s]+)\/([^/\s#?]+?)(?:\.git)?(?:[#?].*)?$/u)
+  if (m === null) return null
+  return `${m[1]}/${m[2]}`
+}
+
+export { parseRepoFromUrl }

package/lib/server/domain/subdir-detect.js

@@ -70,12 +70,39 @@ function pickSubdirPlugin(subs) {
   }
 }
 
+/** 命中子目录插件时的**可安装下一步**（纯函数，单测覆盖）。
+ *
+ * 0.5.47 改错（用户实测）：0.5.46 只做到"认出来了 + 给一段可复制的文字"，**装不了** ——
+ * 用户拿到一句"插件在 ds-bot/ 下"之后还得自己想办法。现在把结构化的可执行计划一并带出：
+ * `{ action: 'install-subdir', repo, branch, dir, packageName, markers }`。
+ * 面板据此渲染一个**按钮**（而不是让用户从报错里抄路径），点下去就是把 `subdir` 交给既有的
+ * `/plugin-console/install` —— 由 domain/subdir-install.js 先落地该子目录、再按既有**本地目录来源**
+ * （`link:`，见 source-spec.js 的判据 C）装进 profile。
+ * 判据不放松：到服务端那一步仍要重新读 `<dir>/package.json` 并按同一把尺子核实（名字 + dsh 标记），
+ * 前端传什么都不算数。`markers` 只为展示判据来源；`repo`/`branch` 由**识别当时**的事实给出，
+ * 免得面板再猜一次。 */
+function subdirInstallPlan(repo, branch, pick) {
+  const dir = String(pick?.dir ?? '')
+  const packageName = String(pick?.packageName ?? '')
+  if (dir === '' || packageName === '') return null
+  return {
+    action: 'install-subdir',
+    repo: String(repo ?? ''),
+    branch: String(branch ?? ''),
+    dir,
+    packageName,
+    markers: Array.isArray(pick?.markers) ? [...pick.markers] : [],
+  }
+}
+
 /** 命中子目录插件时的用户可读结论（纯函数，单测覆盖）。
  * 要点（对应用户实测的质疑"它不是 DSH 插件吗"）：
  *   ① 先**纠正结论** —— 这不是"不是插件"，而是"插件不在根目录"；
  *   ② 给出**子目录路径**与**包名**，以及标记来源（dsh.bundle.patch / dsh.client）—— 判据可核验；
- *   ③ 给出**可复制的下一步**（按包名安装）；并**如实说明**"从子目录直接装"当前不支持
- *      （git 通道只装仓库根包，见 domain/git-channel.js 的核实逻辑）—— 不假装支持。 */
+ *   ③ 给出**可安装的下一步**（0.5.47 改错）：控制台自己能从这个子目录装 —— 面板上的按钮走
+ *      `/plugin-console/install` + `subdir`，服务端先稀疏取该子目录源码到本地、再按既有
+ *      **本地目录来源**（`link:`）装进 profile；清单校验 / 来源校验与别的安装路径**同一套**。
+ *      npm 上若已发布该包，另给一条可直接照抄的命令（两条路都要说清，不二选一藏起来）。 */
 function subdirPluginText(repo, branch, pick, source = 'github') {
   const dir = String(pick?.dir ?? '')
   const pkgName = String(pick?.packageName ?? '')
@@ -83,9 +110,10 @@ function subdirPluginText(repo, branch, pick, source = 'github') {
   return `仓库 ${repo}（${branch} 分支）根目录没有 package.json，但**插件在子目录 ${dir}/ 下**`
     + `（${dir}/package.json 声明了 DSH 标记：${markers}）。`
     + `它就是 DSH 插件，只是清单不在仓库根——${pkgName === '' ? '该子包的包名没能读到' : `包名是 ${pkgName}`}。`
-    + `下一步：${pkgName === '' ? '先按「仓库落地」克隆到本地查看该子目录，' : `该包若已发布到 npm，可直接安装：dsh plugin --profile <你的 profile> add ${pkgName}；否则`}`
-    + `本控制台暂不支持"从子目录直接安装"（git 通道只装仓库根包，装了也是根包而不是 ${dir}/），`
-    + `可把该子目录并进一个独立仓库或等作者发布 npm 包后再装。`
+    + `下一步：点下面的「从这个子目录安装」即可 —— 控制台会先把 ${dir}/ 的源码取到本地，`
+    + `再按既有**本地目录来源**（link:）装进 profile（清单校验与来源校验与其它安装路径同一套，`
+    + `装完照样收口：清单 + lock + 挂载行）。`
+    + `${pkgName === '' ? '' : `该包若已发布到 npm，也可以直接安装：dsh plugin --profile <你的 profile> add ${pkgName}。`}`
 }
 
 /** 扫完根目录与子目录都没找到插件时的用户可读结论（纯函数，单测覆盖）。
@@ -138,7 +166,8 @@ async function decideNoRootManifest({ repo, branch, reason, subScan = null, prob
   if (pick.found === true) {
     return {
       hint: 'subdir-plugin',
-      subplugin: { dir: pick.dir, packageName: pick.packageName, markers: pick.markers, checkedDirs: pick.checkedDirs },
+      // 0.5.47：`install` 是**可执行**的下一步（面板据此渲染按钮）；老客户端忽略该字段（纯加法）。
+      subplugin: { dir: pick.dir, packageName: pick.packageName, markers: pick.markers, checkedDirs: pick.checkedDirs, install: subdirInstallPlan(repo, branch, pick) },
       error: subdirPluginText(repo, branch, pick, source),
     }
   }
@@ -149,4 +178,4 @@ async function decideNoRootManifest({ repo, branch, reason, subScan = null, prob
   }
 }
 
-export { dshMarkersOf, describeDshManifest, pickSubdirPlugin, subdirPluginText, notPluginText, decideNoRootManifest }
+export { dshMarkersOf, describeDshManifest, pickSubdirPlugin, subdirInstallPlan, subdirPluginText, notPluginText, decideNoRootManifest }