@noob-stupid/dsh-plugin-console 0.3.67 → 0.4.1

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

@@ -0,0 +1,122 @@
+// L1 · domain —— dep-source.js（依赖**来源**判定与写回：registry 探测 / plugin-src 物化 / link: 规格）
+//
+// 为什么单开一个模块：install.js 有 600 行棘轮（test-architecture-guard.mjs），而这块逻辑既被
+// install.js 家族用，也被 selfupdate.js 的 lock 对账用——放在自己这里两边都能引，且互不牵连。
+//
+// 缺陷②修复（0.3.63 / 0.4.0-beta.16）背景（用户 issue 草案「缺陷②」，2026-09-22 实测）：
+//   release 通道装的包只存在于 GitHub release，npm registry 里查无此包；而 0.3.57 起的 lock 对账
+//   一律 `pnpm add <name>@<installed>` —— pnpm 看到「已装版本满足新 spec」就**静默**把 profile
+//   package.json 的 dependencies 改写为裸版本号（输出 `Already up to date`、EXIT=0，面板显示成功），
+//   同时把 lock 的 specifier 也改成版本号、却保留旧的 tarball 解析。装完一切正常，直到有人重建
+//   lock（删 lock / 清 node_modules / 换机 / CI）→ `ERR_PNPM_FETCH_404`，而报错指向 npm registry，
+//   用户根本联想不到是几周前面板安装改写造成的。
+//
+// 两条硬约束（本机真 pnpm 10.34.5 实测矩阵见 D:\dsh\dsh-plugin-hub-plan\refactor-bugs.zh.md 第 23 节）：
+//   ① 写回前必须确认「这个包的**这个版本**」在 registry 可解析，否则**绝不**写裸版本号；
+//   ② 不可解析时**也不能**写 tarball URL：pnpm 10 对 direct-URL 依赖只在冷缓存真下载时记 integrity，
+//      命中缓存重写 lock 时 resolution 里没有 integrity → `ERR_PNPM_MISSING_TARBALL_INTEGRITY`，
+//      而且 pnpm 会把 lock 文件直接删掉，形成「删 lock 修不好、不删 lock 装不动」的死循环。
+//      改用 `link:<DSH_HOME>/plugin-src/<包名>`：pnpm 的 link 协议只建符号链接，不经 registry 解析、
+//      不经 tarball 完整性校验，lock 删掉重建、node_modules 清空重装都稳定通过。
+
+import { existsSync, rmSync, mkdirSync, realpathSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { copyTree } from '../infra/fsx.js'
+import { fetchJsonUrl } from '../infra/http.js'
+import { dshHome } from '../infra/paths.js'
+
+/** 物化目录的根（与用户 issue 里手工规避用的 `/root/.dsh/plugin-src/...` 同一位置）。 */
+const PLUGIN_SRC_DIR = 'plugin-src'
+
+/**
+ * registry 能否解析该包的指定版本（按顺序多源尝试，任一源可解析即通过）。
+ * 404 / 网络失败都归为「不可解析」——调用方据此决定**绝不写裸版本号**。
+ * `version` 为 null 时只判包是否存在；`hasVersion` 表示指定版本是否在 versions 里
+ * （release 通道装的版本可能比 registry 上的 latest 还新，只判包名存在是不够的）。
+ */
+async function probeRegistryPackage(packageName, registries = [], options = {}) {
+  const fetchJson = typeof options.fetchJson === 'function' ? options.fetchJson : fetchJsonUrl
+  const version = typeof options.version === 'string' && options.version !== '' ? options.version : null
+  const timeoutMs = Number.isFinite(options.timeoutMs) ? options.timeoutMs : 8000
+  const list = (Array.isArray(registries) ? registries : []).filter((r) => typeof r === 'string' && r.trim() !== '')
+  const tries = list.length > 0 ? list : ['https://registry.npmmirror.com']
+  const encoded = packageName.startsWith('@')
+    ? `@${encodeURIComponent(packageName.slice(1).split('/')[0])}%2f${encodeURIComponent(packageName.split('/').slice(1).join('/'))}`
+    : encodeURIComponent(packageName)
+  const tried = []
+  for (const reg of tries) {
+    const base = String(reg).replace(/\/+$/u, '')
+    try {
+      const meta = await fetchJson(`${base}/${encoded}`, timeoutMs)
+      const versions = meta && typeof meta === 'object' && meta.versions && typeof meta.versions === 'object' ? meta.versions : null
+      if (versions === null) {
+        tried.push(`${base}：返回体没有 versions 字段`)
+        continue
+      }
+      const latest = typeof meta['dist-tags']?.latest === 'string' ? meta['dist-tags'].latest : null
+      return {
+        resolvable: true,
+        hasVersion: version === null || Object.prototype.hasOwnProperty.call(versions, version),
+        latest,
+        registry: base,
+        tried,
+      }
+    } catch (error) {
+      tried.push(`${base}：${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+  return { resolvable: false, hasVersion: false, latest: null, registry: null, tried }
+}
+
+/**
+ * 把 profile 里**已装好的**包物化一份到 `<DSH_HOME>/plugin-src/<包名>`，返回该绝对路径。
+ * 为什么必须另存一份而不是直接 link node_modules 里的目录：pnpm 重建 node_modules 时会先删掉
+ * 整个目录，link 目标随即消失；plugin-src 是 pnpm 不管理的独立目录，跨 lock 重建、
+ * 跨 node_modules 清空都稳定存在（这也是用户手工规避时选的位置）。
+ * 返回 null 表示源目录不存在或复制失败 —— 调用方必须**跳过对齐**并如实记 note，绝不改 package.json。
+ */
+function materializePackageForLink(profileDir, packageName, options = {}) {
+  const home = typeof options.home === 'string' && options.home !== '' ? options.home : dshHome()
+  const src = join(profileDir, 'node_modules', ...packageName.split('/'))
+  if (!existsSync(join(src, 'package.json'))) return null
+  const dest = join(home, PLUGIN_SRC_DIR, ...packageName.split('/'))
+  // 已经是指向 plugin-src 的链接（重复对账）→ 不能先删再复制：那样源就成了悬空链接
+  try {
+    if (existsSync(dest) && realpathSync(src) === realpathSync(dest)) return dest
+  } catch {}
+  try {
+    mkdirSync(dirname(dest), { recursive: true })
+    if (existsSync(dest)) rmSync(dest, { recursive: true, force: true })
+    copyTree(src, dest)
+  } catch {
+    return null
+  }
+  return existsSync(join(dest, 'package.json')) ? dest : null
+}
+
+/** pnpm 的 `link:` 规格：写绝对路径（反斜杠转正斜杠，跨平台且 lock 可读）。 */
+function linkSpecFor(dir) {
+  return `link:${String(dir).replace(/\\/gu, '/')}`
+}
+
+/**
+ * manifest 里的 `link:` 规格当前是否**真的**还生效（`node_modules/<包名>` 就是指向它的那个链接）。
+ * 为什么必须查：release / curl 通道更新包时是「先 rmSync 再 copyTree」，会把 `node_modules/<包名>`
+ * 从"链接"换成"真实目录"，而 manifest 与 lock 里仍写着 `link:<plugin-src/…>` —— 光看版本号看不出来
+ * （lock 里本来就是 `link:`），但**之后任何一次 pnpm 操作都会按 lock 重建链接**，把刚更新上去的版本
+ * 还原成 `plugin-src` 里的旧副本（与 0.3.56 修过的「自更新被 lock 还原」同族）。
+ * 返回 false 时调用方会重新物化（把新副本刷进 plugin-src）并重放 `link:`，实测能把链接与版本一起恢复。
+ */
+function linkSpecIsIntact(profileDir, packageName, spec) {
+  if (typeof spec !== 'string' || !spec.startsWith('link:')) return false
+  const target = spec.slice('link:'.length)
+  const src = join(profileDir, 'node_modules', ...packageName.split('/'))
+  try {
+    if (!existsSync(src) || !existsSync(target)) return false
+    return realpathSync(src) === realpathSync(target)
+  } catch {
+    return false
+  }
+}
+
+export { PLUGIN_SRC_DIR, probeRegistryPackage, materializePackageForLink, linkSpecFor, linkSpecIsIntact }

package/lib/server/domain/format-contract.js

@@ -0,0 +1,265 @@
+// L1 · domain —— format-contract.js：会话格式契约预检（Step 1 · 契约抓取）
+//
+// 背景（2026-09-24 真机事故）：框架 0.1.5-rc.2 → 0.1.7-rc.1 把会话消息格式升到 V4，
+// 要求每条被解释的消息 source 带「producer-owned kind」（非空、且不等于字面量 'plugin'）。
+// 框架自带的 @deepseek-ai/dsh-session-format-v3-to-v4 只迁移**磁盘上的历史会话**；
+// 运行期新产生的消息由本地生产方（agent-presets + 插件运行时代码）自己构造——它们仍写
+// V3 老形状 `{ kind: 'plugin', plugin: X }`，于是「一发消息就报错、整个会话不可用」。
+// 现有的包级适配门（peerDependencies / 版本号）**看不到**这类运行期契约破坏 ——
+// 生产方（预设文件、插件 runtime）根本没有版本元数据。
+//
+// 发现路径（实网探明，2026-09-24）：顶层 @deepseek-ai/dsh 只挂中间包，**迁移边全集挂在
+// @deepseek-ai/dsh-session-format-catalog 的 dependencies 上**——所以先问 catalog（一次请求拿到
+// 该版本的全部边），catalog 缺失时退回扫顶层 dsh 依赖。核心信号：
+//   **目标版本的迁移边集合 比 当前已装版本的 多出一条** ⇒ 这就是一次会打在运行期生产方身上的契约变更。
+//
+// 本模块全部网络 I/O 可注入（离线可测）：抓取失败不抛，返回 error 让上层降级成「只用内置规则扫描」。
+
+import { parseFrameworkVersion } from '../infra/semver.js'
+
+/** 会话格式迁移边包名：@deepseek-ai/dsh-session-format-v3-to-v4。 */
+const FORMAT_EDGE_RE = /^@deepseek-ai\/dsh-session-format-v(\d+)-to-v(\d+)$/u
+
+/** 迁移边全集的权威载体（实网确认：0.1.7-rc.1 的 catalog 依赖里含 v0→v1…v3→v4 四条）。 */
+const CATALOG_PKG = '@deepseek-ai/dsh-session-format-catalog'
+
+/** 一次预检最多为几条边拉 README（按 to 从高到低，最高那条才带准入规则）。 */
+const README_BUDGET = 3
+
+/** npm 源上的包名编码（scope 斜杠要转义，npmmirror 与 registry.npmjs.org 都吃 %2f）。 */
+function encodePkgName(name) {
+  return String(name).replace('/', '%2f')
+}
+
+/** 解析一条迁移边包名；不是迁移边返回 null。 */
+function parseFormatEdge(pkgName) {
+  const m = FORMAT_EDGE_RE.exec(String(pkgName))
+  if (m === null) return null
+  return { name: pkgName, from: Number(m[1]), to: Number(m[2]) }
+}
+
+/** 从依赖表里挑出全部迁移边（按 to 升序；同一 from/to 只留一条）。 */
+function formatEdgesFromDependencies(dependencies) {
+  const edges = []
+  for (const name of Object.keys(dependencies ?? {})) {
+    const edge = parseFormatEdge(name)
+    if (edge !== null) edges.push(edge)
+  }
+  return edges.sort((a, b) => (a.to - b.to) || (a.from - b.from))
+}
+
+/** 依赖里的版本区间（`^0.1.7-rc.1` / `~1.2.3`）→ 具体版本字符串。 */
+function concreteVersionOf(range) {
+  const m = /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/u.exec(String(range ?? ''))
+  return m === null ? null : m[1]
+}
+
+/**
+ * 取 README 里某个小节（到下一个二级/三级标题或锚点为止）；找不到返回 null。
+ * ★ 必须锚定「标题行」而不是 `indexOf`：README 顶部的目录（ToC）里也会出现同样的小节名，
+ *   用 indexOf 会命中目录那一行，切出来的段落里没有表格 → 规则静默丢失（实网复验抓到过）。
+ */
+function sectionOf(readme, heading) {
+  const escaped = String(heading).replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')
+  const m = new RegExp(`^#{2,3}\\s+${escaped}\\s*$`, 'mu').exec(readme)
+  if (m === null) return null
+  const rest = readme.slice(m.index + m[0].length)
+  const end = rest.search(/^#{2,3}\s|\n<a id=/mu)
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+/**
+ * 取小节里「V3 plugin → V4 kind」那张映射表的行。
+ * 同一个小节内还有别的表（事件位置表 `| \`user/message\` | \`data\` |` 等），形状一模一样，
+ * 所以必须先认表头（同时含 `plugin` 与 `kind` 的那一行），只吃它下面连续的行。
+ */
+function mappingRowsFromSection(section) {
+  const rows = []
+  let inTable = false
+  for (const line of section.split(/\r?\n/u)) {
+    if (!inTable) {
+      if (/^\|/u.test(line) && /`plugin`/u.test(line) && /`kind`/u.test(line)) inTable = true
+      continue
+    }
+    if (!/^\|/u.test(line)) break
+    if (/^\|\s*:?-{2,}/u.test(line)) continue
+    rows.push(line)
+  }
+  return rows
+}
+
+/**
+ * 从迁移包 README 抽规则。只认语义明确的两处，抽不到就如实留空（宁可少报，不乱报）：
+ *   · `| Producer attribution | … a nonempty, non-`plugin` kind … |`
+ *   · `| Any other plugin name | `plugin:` followed by the complete original name |`
+ *   · 重命名表**只在「Message-source conversion」小节、且只在认得出表头的那张表里**解析 ——
+ *     README 里表格形状高度雷同，全局解析会混进 `user/message → data` 这类噪音（实网抓到过）。
+ */
+function extractContractRules(readme) {
+  const rules = {
+    producerKindRequired: false,
+    forbiddenKinds: ['plugin'],
+    pluginPrefix: null,
+    renames: {},
+    attributionExcerpt: null,
+  }
+  if (typeof readme !== 'string' || readme === '') return rules
+  const attribution = /\|\s*Producer attribution\s*\|([^|]*)\|/u.exec(readme)
+  if (attribution !== null) {
+    // 注意要去掉反引号之后再判断：原文是 non-`plugin`
+    const cleaned = attribution[1].replace(/`/gu, '').replace(/\s+/gu, ' ').trim()
+    rules.attributionExcerpt = cleaned
+    rules.producerKindRequired = /non-?plugin/u.test(cleaned) || /producer-owned/u.test(cleaned)
+  }
+  const prefix = /Any other plugin name\s*\|\s*`([^`]+)`/u.exec(readme)
+  if (prefix !== null) rules.pluginPrefix = prefix[1].trim()
+  const sourceSection = sectionOf(readme, 'Message-source conversion')
+  if (sourceSection !== null) {
+    // 只收「首列是单个代码片段」的行（跳过 `x, on a system-role message` 这类角色敏感行）
+    for (const row of mappingRowsFromSection(sourceSection)) {
+      const m = /^\|\s*`([^`]+)`\s*\|\s*`([^`]+)`\s*\|/u.exec(row)
+      if (m !== null && !m[1].includes(',')) rules.renames[m[1]] = m[2]
+    }
+  }
+  return rules
+}
+
+/**
+ * 纯函数：把「目标版本依赖表 + 各迁移边 README」组装成契约对象。
+ * @param dependencies        目标版本的依赖表（来自 catalog 或顶层 dsh manifest）
+ * @param currentDependencies 当前已装版本的依赖表（用于算「新增了哪条边」）
+ */
+function buildContract({ targetVersion = null, currentVersion = null, dependencies = {}, currentDependencies = {}, edgeSource = 'dsh', edgeReadmes = {}, now = () => Date.now() } = {}) {
+  const edges = formatEdgesFromDependencies(dependencies).map((edge) => {
+    const readme = typeof edgeReadmes[edge.name] === 'string' ? edgeReadmes[edge.name] : null
+    return {
+      name: edge.name,
+      from: edge.from,
+      to: edge.to,
+      version: concreteVersionOf(dependencies[edge.name]),
+      readme: { available: readme !== null },
+      rules: readme === null ? null : extractContractRules(readme),
+    }
+  })
+  const sessionFormatVersion = edges.reduce((max, edge) => (edge.to > max ? edge.to : max), 0) || null
+  const currentKeys = new Set(formatEdgesFromDependencies(currentDependencies).map((e) => `${e.from}->${e.to}`))
+  const edgesAdded = currentVersion === null || currentVersion === targetVersion
+    ? []
+    : edges.filter((e) => !currentKeys.has(`${e.from}->${e.to}`)).map((e) => ({ name: e.name, from: e.from, to: e.to }))
+  // 规则取「最高那条边」（最新格式的准入规则才是要适配的目标）
+  const latest = edges.filter((e) => e.to === sessionFormatVersion).pop() ?? null
+  const rules = latest?.rules ?? { producerKindRequired: false, forbiddenKinds: ['plugin'], pluginPrefix: null, renames: {}, attributionExcerpt: null }
+  return {
+    targetVersion,
+    currentVersion,
+    sessionFormatVersion,
+    edgeSource,
+    edges,
+    edgesAdded,
+    rules,
+    fetchedAt: now(),
+  }
+}
+
+/** README 文本的多通道候选（jsDelivr npm CDN 优先，npmmirror files API 兜底）。 */
+function readmeUrls(name, version, registry) {
+  const urls = []
+  if (typeof version === 'string' && version !== '') {
+    urls.push(`https://cdn.jsdelivr.net/npm/${name}@${version}/README.md`)
+    urls.push(`${registry}/${encodePkgName(name)}/${version}/files/README.md`)
+  }
+  urls.push(`${registry}/${encodePkgName(name)}/files/README.md`)
+  return urls
+}
+
+/**
+ * 问一个版本「它带哪些会话格式迁移边」：catalog 优先（一次拿全），缺失则退回顶层 dsh 依赖。
+ * @returns { dependencies, edgeSource }；版本不存在时抛错（由上层兜住）。
+ */
+async function edgesForVersion({ version, fetchJson, registry }) {
+  const catalogUrl = `${registry}/${encodePkgName(CATALOG_PKG)}/${version}`
+  try {
+    const catalog = await fetchJson(catalogUrl)
+    const fromCatalog = formatEdgesFromDependencies(catalog?.dependencies)
+    if (fromCatalog.length > 0) return { dependencies: catalog.dependencies ?? {}, edgeSource: 'catalog', manifest: catalog }
+  } catch {}
+  const manifest = await fetchJson(`${registry}/${encodePkgName('@deepseek-ai/dsh')}/${version}`)
+  return { dependencies: manifest?.dependencies ?? {}, edgeSource: 'dsh', manifest }
+}
+
+/**
+ * 抓取目标版本的会话格式契约。
+ * 任何一步失败都不抛出：返回 { contract, error }，让上层降级成「只看内置规则」的扫描。
+ */
+async function discoverFormatContract({ targetVersion, currentVersion = null, fetchJson, fetchText, registry = 'https://registry.npmmirror.com', now = () => Date.now() } = {}) {
+  if (typeof targetVersion !== 'string' || targetVersion === '') return { contract: null, error: '缺少目标版本' }
+  if (typeof fetchJson !== 'function') return { contract: null, error: '缺少 fetchJson 注入' }
+  let target = null
+  try {
+    target = await edgesForVersion({ version: targetVersion, fetchJson, registry })
+  } catch (error) {
+    return { contract: null, error: `拉取目标版本信息失败：${error instanceof Error ? error.message : String(error)}` }
+  }
+  let currentDependencies = {}
+  if (typeof currentVersion === 'string' && currentVersion !== '' && currentVersion !== targetVersion) {
+    try {
+      currentDependencies = (await edgesForVersion({ version: currentVersion, fetchJson, registry })).dependencies
+    } catch {}
+  }
+  // README 只拉「最高 to 的几条边」（准入规则在高位边里；低位边规则对本次适配没有指导意义）
+  const edges = formatEdgesFromDependencies(target.dependencies)
+  const edgeReadmes = {}
+  const warnings = []
+  if (typeof fetchText === 'function') {
+    for (const edge of [...edges].sort((a, b) => b.to - a.to).slice(0, README_BUDGET)) {
+      const version = concreteVersionOf(target.dependencies[edge.name])
+      let got = null
+      for (const url of readmeUrls(edge.name, version, registry)) {
+        try {
+          const text = await fetchText(url)
+          if (typeof text === 'string' && text.trim() !== '') { got = text; break }
+        } catch {}
+      }
+      if (got === null) warnings.push(`${edge.name}: README 拉取失败（契约规则未知）`)
+      else edgeReadmes[edge.name] = got
+    }
+  }
+  const contract = buildContract({
+    targetVersion,
+    currentVersion,
+    dependencies: target.dependencies,
+    currentDependencies,
+    edgeSource: target.edgeSource,
+    edgeReadmes,
+    now,
+  })
+  return { contract, error: null, warnings }
+}
+
+/** 契约摘要（面板/日志用的一句话）。 */
+function summarizeContract(contract) {
+  if (contract === null || contract === undefined) return '契约未知'
+  if (contract.sessionFormatVersion === null) return '目标版本没有会话格式迁移包（格式未变更）'
+  const all = contract.edges.map((e) => `v${e.from}→v${e.to}`).join('、')
+  if ((contract.edgesAdded ?? []).length > 0) {
+    const added = contract.edgesAdded.map((e) => `v${e.from}→v${e.to}`).join('、')
+    return `会话格式 v${contract.sessionFormatVersion}，本次新增迁移边 ${added} —— 契约变更，必须先预检本地生产方（全部边：${all}）`
+  }
+  return `会话格式 v${contract.sessionFormatVersion}（迁移边：${all}；相比当前版本无新增）`
+}
+
+export {
+  FORMAT_EDGE_RE,
+  CATALOG_PKG,
+  README_BUDGET,
+  encodePkgName,
+  parseFormatEdge,
+  formatEdgesFromDependencies,
+  concreteVersionOf,
+  extractContractRules,
+  buildContract,
+  readmeUrls,
+  edgesForVersion,
+  discoverFormatContract,
+  summarizeContract,
+}