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

package/lib/server/domain/market.js

@@ -0,0 +1,409 @@
+// L1 · domain —— market.js（分层 Step 从 lib/index.js 搬出，只搬移未改逻辑）
+// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md §三
+
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { detectSkillRepo } from './skills.js'
+import { FETCH_OK, FETCH_UNREACHABLE, GITHUB_API, curlJson, curlText, fetchJsonUrl, githubJson, looksLikeGitmodules, rawTextFetch, rawTextWithFallback } from '../infra/http.js'
+import { ENRICH_CACHE_FILE, baseDirOf, resolvePackageJson } from '../infra/paths.js'
+
+function readEnrichCache() {
+  try {
+    const j = JSON.parse(readFileSync(ENRICH_CACHE_FILE(), 'utf8'))
+    return j !== null && typeof j === 'object' ? j : {}
+  } catch { return {} }
+}
+
+function writeEnrichCache(cache) {
+  try {
+    mkdirSync(dirname(ENRICH_CACHE_FILE()), { recursive: true })
+    const entries = Object.entries(cache).sort((a, b) => (b[1]?.at ?? 0) - (a[1]?.at ?? 0)).slice(0, 2000)
+    writeFileSync(ENRICH_CACHE_FILE(), JSON.stringify(Object.fromEntries(entries), null, 2), 'utf8')
+  } catch {}
+}
+
+/** 单项识别：官方通道 / 聚合仓库 / 技能 / 套装（失败返回 official=null）。 */
+async function enrichItemOne(item) {
+  let official = /^deepseek-ai\//u.test(item.fullName ?? '') ? true : null
+  let aggregate = false
+  let aggregateInstallable = false
+  let hasSkill = false
+  let hasSuite = false
+  try {
+    const branch = item.defaultBranch ?? 'main'
+    const base = `https://raw.githubusercontent.com/${item.fullName}/${encodeURIComponent(branch)}/package.json`
+    const [pkgResult, skillResult, suiteResult] = await Promise.allSettled([
+      Promise.any([
+        curlText(base, 4000),
+        curlText(`https://ghproxy.net/${base}`, 4000),
+      ]),
+      detectSkillRepo(item.fullName, branch),
+      rawTextWithFallback(item.fullName, branch, '.gitmodules'),
+    ])
+    // 套装判定必须过内容校验：代理/CDN 对不存在的 .gitmodules 也可能回 2xx 空 body，
+    // 只判"探测非 null"会把普通插件标成套装置仓库（2026-09-19 事故）。
+    if (suiteResult.status === 'fulfilled' && looksLikeGitmodules(suiteResult.value)) {
+      hasSuite = true
+    }
+    if (pkgResult.status === 'fulfilled') {
+      const pkg = JSON.parse(pkgResult.value)
+      if (typeof pkg.dsh?.bundle?.patch === 'string') {
+        official = true
+      } else {
+        // 成功读到 package.json 且没有 dsh.bundle.patch → 确定「非官方」。
+        // 必须落成 false（而不是留 null），否则缓存条件 official !== null 永不成立，
+        // 每个非官方插件每次打开都重新请求 → /enrich 缓存命中也要十几秒。
+        official = false
+        if (pkg.private === true && (Array.isArray(pkg.workspaces) || /(^|-)dsh[-/]/u.test(String(pkg.name ?? '')))) {
+          aggregate = true
+          try {
+            const tree = await curlJson(`https://api.github.com/repos/${item.fullName}/git/trees/${encodeURIComponent(branch)}?recursive=1`, 6000)
+            const pkgPaths = (tree.tree ?? [])
+              .filter((n) => n.type === 'blob' && /^packages\/[^/]+\/package\.json$/u.test(n.path))
+              .map((n) => n.path)
+              .slice(0, 12)
+            if (pkgPaths.length > 0) {
+              const subs = await Promise.all(pkgPaths.map((p) => curlText(`https://raw.githubusercontent.com/${item.fullName}/${encodeURIComponent(branch)}/${p}`, 4000)
+                .then((t) => { try { return JSON.parse(t) } catch { return null } })
+                .catch(() => null)))
+              if (subs.some((sp) => sp && typeof sp.dsh?.bundle?.patch === 'string')) {
+                aggregateInstallable = true
+              }
+            }
+          } catch {}
+        }
+      }
+    }
+    if (skillResult.status === 'fulfilled' && skillResult.value?.hasSkill === true) {
+      hasSkill = true
+    }
+  } catch {}
+  return { ...item, official, aggregate, aggregateInstallable, hasSkill, hasSuite }
+}
+
+/**
+ * 批量识别（★ 筛选数据源）：并发限流 + 24h 结果缓存。
+ * 网络黑洞期（raw.githubusercontent 大部分拉取失败）自动回退缓存中的上次判定，
+ * 保证「只看官方」不因瞬时网络而坍缩成 0/1 条。
+ */
+async function enrichItems(items) {
+  const cache = readEnrichCache()
+  const out = new Array(items.length)
+  let next = 0
+  let cacheDirty = false
+  async function worker() {
+    while (true) {
+      const i = next
+      next += 1
+      if (i >= items.length) return
+      const item = items[i]
+      const key = `${item.fullName}@${item.defaultBranch ?? 'main'}`
+      const cached = cache[key]
+      try {
+        // official 已判定（true/false）→ 24h 缓存；判定失败（null）→ 1h 短缓存，减少无谓重试
+        if (cached !== undefined && typeof cached?.at === 'number' && cached.data) {
+          const ttl = cached.data.official === null ? 60 * 60 * 1000 : ENRICH_CACHE_TTL
+          if (Date.now() - cached.at < ttl) {
+            out[i] = { ...item, ...cached.data }
+            continue
+          }
+        }
+        let result = await enrichItemOne(item)
+        // 本次失败 → 回退缓存（哪怕已过期），避免「看天吃饭」
+        if ((result.official === null && !/^deepseek-ai\//u.test(item.fullName ?? '')) && cached?.data) {
+          result = { ...item, ...cached.data }
+        } else {
+          cache[key] = { at: Date.now(), data: { official: result.official, aggregate: result.aggregate, aggregateInstallable: result.aggregateInstallable, hasSkill: result.hasSkill, hasSuite: result.hasSuite } }
+          cacheDirty = true
+        }
+        out[i] = result
+      } catch {
+        // 抛错的条目也必须写缓存（null 结果 + 1h 短 TTL），否则每次打开都重试同一批，
+        // /enrich 即使「命中缓存」也要等十几秒。
+        if (cached?.data) {
+          out[i] = { ...item, ...cached.data }
+        } else {
+          const miss = { official: null, aggregate: false, aggregateInstallable: false, hasSkill: false, hasSuite: false }
+          cache[key] = { at: Date.now(), data: miss }
+          cacheDirty = true
+          out[i] = { ...item, ...miss }
+        }
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(12, items.length) }, worker))
+  if (cacheDirty) writeEnrichCache(cache)
+  return out
+}
+
+/** 平台搜索返回归一化（数组或 {items} 均可；兼容 GitHub/Gitee/自定义源字段）。 */
+function normalizePlatformItems(data, fallbackBranch = 'main') {
+  const list = Array.isArray(data) ? data : (data && Array.isArray(data.items) ? data.items : [])
+  return list
+    .filter((item) => item && typeof item === 'object')
+    .map((item) => ({
+      fullName: String(item.full_name ?? item.path_with_namespace ?? item.name ?? '').trim(),
+      description: item.description ?? '',
+      htmlUrl: item.html_url ?? item.web_url ?? '',
+      stars: item.stargazers_count ?? item.star_count ?? 0,
+      updatedAt: item.updated_at ?? item.last_activity_at ?? '',
+      defaultBranch: item.default_branch ?? fallbackBranch,
+      topics: Array.isArray(item.topics) ? item.topics : [],
+    }))
+    .filter((item) => item.fullName !== '')
+}
+
+function githubRepoInfo(repo) {
+  const match = String(repo).trim().match(/^(?:https:\/\/github\.com\/|https:\/\/gitee\.com\/|git@github\.com:|git@gitee\.com:)?([^\s\/?#]+)\/([^\s\/?#]+?)(?:\.git)?$/u)
+  if (!match) throw new Error('仓库名格式应为 owner/name（支持完整仓库 URL 与中文路径）')
+  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]}`
+}
+
+/** 结果里是否已有"名字逐词命中查询词"的条目——决定要不要再加 `in:readme` 重查一次。
+ * （仓库搜索的检索面只有 名字/描述/topics；README 里的词必须显式 in:readme 才查得到） */
+function hasDirectNameHit(items, query) {
+  const tokens = String(query ?? '').toLowerCase().split(/[\s\-_/.]+/u).filter((tk) => tk.length >= 3)
+  if (tokens.length === 0) return true // 查询太短/太泛：不做二次查询，避免把结果冲稀
+  return items.some((it) => {
+    const name = String(it?.fullName ?? '').toLowerCase()
+    return tokens.every((tk) => name.includes(tk))
+  })
+}
+
+/** npm 包名搜索：registry 搜索接口 → 候选包 → 读 packument 的 repository.url → 映射回 GitHub 仓库。
+ * 背景（2026-09-20）：用户搜 `web-all`（= npm 包 `@linxin666/dsh-web-all`）搜不到，因为 `web-all`
+ * 只存在于 npm 包名、仓库文件与 README 里，而 GitHub 仓库搜索的检索面只有 名字/描述/topics。
+ * 这条通道不依赖静态索引、也不依赖 GitHub 登录，且命中后可按包名直接安装。 */
+async function searchNpmPackages(query, registries, limit = 3, token = null) {
+  const q = String(query ?? '').trim().toLowerCase()
+  if (q.length < 2) return []
+  let hits = null
+  let registry = null
+  for (const reg of (registries ?? []).slice(0, 3)) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const data = await fetchJsonUrl(`${reg}/-/v1/search?text=${encodeURIComponent(q)}&size=10`, 8000)
+      if (data && Array.isArray(data.objects)) { hits = data.objects; registry = reg; break }
+    } catch {}
+  }
+  if (hits === null) return []
+  const candidates = hits
+    .map((o) => o?.package)
+    .filter((p) => p && typeof p.name === 'string' && p.name.toLowerCase().includes(q))
+    .slice(0, limit)
+  const out = []
+  for (const cand of candidates) {
+    try {
+      const encoded = cand.name.startsWith('@')
+        ? `@${encodeURIComponent(cand.name.slice(1).split('/')[0])}%2f${encodeURIComponent(cand.name.split('/').slice(1).join('/'))}`
+        : encodeURIComponent(cand.name)
+      // eslint-disable-next-line no-await-in-loop
+      const meta = await fetchJsonUrl(`${registry}/${encoded}`, 8000)
+      const repo = parseRepoFromUrl(meta?.repository?.url ?? meta?.repository ?? cand.links?.repository ?? '')
+      if (repo === null) continue
+      // 顺带补仓库真实元数据（星数/描述/默认分支）——npm 里的信息不足，且默认分支可能是 dev
+      let info = null
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        info = await githubJson(`${GITHUB_API}/repos/${repo}`, null, token)
+      } catch {}
+      out.push({
+        fullName: repo,
+        description: `${info?.description ?? cand.description ?? ''}（npm 包：${cand.name}@${cand.version ?? '?'}）`.trim(),
+        htmlUrl: info?.html_url ?? `https://github.com/${repo}`,
+        stars: typeof info?.stargazers_count === 'number' ? info.stargazers_count : 0,
+        updatedAt: info?.updated_at ?? '',
+        defaultBranch: info?.default_branch ?? null,
+        topics: Array.isArray(info?.topics) ? info.topics : [],
+        source: 'npm',
+        sourceName: 'npm',
+        packageName: cand.name,
+        npmVersion: cand.version ?? null,
+        npmPackage: true,
+      })
+    } catch {}
+  }
+  return out
+}
+
+/** monorepo 子包增强：GitHub 代码搜索（`<词> filename:package.json`）→ 命中 `packages/<包>/package.json`
+ * → 读该 package.json 取真实包名 → 作为子包条目返回（这样 `dsh-web-all`、OpenViking 这类
+ * 「只存在于仓库文件里的包名」也能被搜到，且带 packageName 可直接按包名安装）。
+ * ⚠️ GitHub **代码搜索 API 强制要求登录**（未登录实测 401 Requires authentication），未登录时返回空。 */
+async function searchSubpackageItems(query, token = null, signal = null) {
+  const subItems = []
+  try {
+    const codeData = await githubJson(
+      `${GITHUB_API}/search/code?q=${encodeURIComponent(`${query} filename:package.json`)}`,
+      signal,
+      token,
+    )
+    for (const hit of (codeData.items ?? []).slice(0, 10)) {
+      const hitPath = typeof hit.path === 'string' ? hit.path : ''
+      if (!/^(?!node_modules\/)[^/]+(?:\/[^/]+)?\/package\.json$/u.test(hitPath)) continue
+      const repoName = hit.repository?.full_name ?? ''
+      if (!repoName) continue
+      const dir = hitPath.split('/').slice(0, -1).join('/')
+      let packageName = dir.split('/').slice(-1)[0]
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const pkgText = await rawTextWithFallback(repoName, 'main', hitPath)
+        if (pkgText !== null) {
+          const pkg = JSON.parse(pkgText)
+          if (pkg && typeof pkg.name === 'string') packageName = pkg.name
+        }
+      } catch {}
+      subItems.push({
+        fullName: repoName,
+        description: `子包：${dir}`,
+        htmlUrl: `https://github.com/${repoName}/tree/main/${dir}`,
+        stars: 0,
+        updatedAt: '',
+        defaultBranch: 'main',
+        topics: [],
+        source: 'github',
+        subpackagePath: dir,
+        packageName,
+      })
+      if (subItems.length >= 5) break
+    }
+  } catch {}
+  return subItems
+}
+
+/** 包探测（带失败原因）：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 }
+  try {
+    const pkg = JSON.parse(body)
+    if (pkg !== null && typeof pkg === 'object' && typeof pkg.name === 'string') return { pkg, reason: 'ok' }
+  } catch {}
+  return { pkg: null, reason: 'invalid' }
+}
+
+async function fetchRepoPackage(repo, branch) {
+  return (await fetchRepoPackageEx(repo, branch)).pkg
+}
+
+/** 探测失败时的用户可读文案：「抓取超时/不可达」与「真的没有」必须区分开。 */
+function packageProbeErrorText(repo, branch, reason) {
+  if (reason === FETCH_UNREACHABLE) {
+    return `抓取超时/网络不可达：没能读到 ${repo}（${branch} 分支）的 package.json —— 通常是网络到 GitHub 太慢（例如解析出 IPv6 却无 IPv6 路由）。请重试；若持续失败，可先用「仓库落地」克隆到本地目录。`
+  }
+  if (reason === 'invalid') {
+    return `仓库 ${repo} 的 package.json 不是合法的包描述（缺少 name 字段），无法作为插件安装——可改用「仓库落地」克隆到本地目录。`
+  }
+  return `仓库 ${repo} 没有 package.json（也不是技能仓库），无法作为插件安装——可改用「仓库落地」克隆到本地目录。`
+}
+
+/** 提取 README 的标题与开篇段落摘要（首个二级标题之前的正文）。 */
+function summarizeReadme(text) {
+  const lines = text.split(/\r?\n/u)
+  let title = ''
+  const intro = []
+  for (const line of lines) {
+    const heading = line.match(/^(#{1,3})\s+(.+)$/u)
+    if (heading) {
+      if (title === '') {
+        title = heading[2].trim()
+        continue
+      }
+      break
+    }
+    if (title === '' && /^[-=]{3,}$/u.test(line.trim()) && line.trim() !== '') continue
+    if (title === '') continue
+    const cleaned = line
+      .replace(/!\[[^\]]*\]\([^)]*\)/gu, '')
+      .replace(/\[([^\]]+)\]\([^)]*\)/gu, '$1')
+      .replace(/[`*_~]/gu, '')
+      .trim()
+    if (cleaned) intro.push(cleaned)
+    if (intro.join(' ').length > 700) break
+  }
+  return { title, summary: intro.join(' ').trim().slice(0, 900) }
+}
+
+/** 读取一个已加载插件的 package.json 元信息与 README 摘要。 */
+async function readPluginDetails(moduleName, baseUrl, profileDir) {
+  if (typeof moduleName !== 'string' || moduleName.startsWith('cordis:')) return { meta: null, readme: null }
+  try {
+    const pkgPath = resolvePackageJson(moduleName, baseDirOf(baseUrl), profileDir ?? null)
+    if (pkgPath === null) throw new Error('not found')
+    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'))
+    const meta = {
+      name: moduleName,
+      version: pkg.version ?? null,
+      description: pkg.description ?? null,
+      homepage: pkg.homepage ?? null,
+      repository: typeof pkg.repository === 'string' ? pkg.repository : (pkg.repository?.url ?? null),
+    }
+    let readme = null
+    for (const candidate of ['README.zh.md', 'README.md']) {
+      try {
+        const text = await readFile(join(dirname(pkgPath), candidate), 'utf8')
+        readme = summarizeReadme(text)
+        break
+      } catch {}
+    }
+    return { meta, readme }
+  } catch {
+    return { meta: null, readme: null }
+  }
+}
+
+/** 服务端列出仓库子包（git trees 递归 + 并行读 package.json 的 name）。 */
+async function fetchSubpackageNames(repo, branch, auth) {
+  try {
+    const data = await githubJson(`${GITHUB_API}/repos/${repo}/git/trees/${encodeURIComponent(branch)}?recursive=1`, undefined, auth)
+    const paths = (data.tree ?? [])
+      .filter((node) => node.type === 'blob' && /^(?!node_modules\/)[^/]+(?:\/[^/]+)?\/package\.json$/u.test(node.path))
+      .map((node) => node.path)
+    // 并行读取：黑洞期单条最坏 40s，24 条串行会拖到十几分钟
+    const results = await Promise.all(paths.slice(0, 24).map(async (path) => {
+      const bodyText = await rawTextWithFallback(repo, branch, path)
+      if (bodyText === null) return null
+      try {
+        const pkg = JSON.parse(bodyText)
+        if (pkg && typeof pkg.name === 'string') return { dir: path.split('/')[1], path: path.split('/').slice(0, -1).join('/'), name: pkg.name }
+      } catch {}
+      return null
+    }))
+    return results.filter((item) => item !== null)
+  } catch {
+    return []
+  }
+}
+
+/** 子包候选：聚合包（名字带 all）优先，上限 8 个。
+ * 2026-09-20 真装演练：`@dsh-suite/all` 这种 **scope 根形式**（`/all` 结尾）不被
+ * `(^|-)all$` 命中，聚合包没能排到最前（那次纯属仓库目录顺序碰巧第一）。补上 `/all$`。 */
+async function subpackageCandidates(repo, branch, auth) {
+  const isAll = (name) => /(^|-)all$/u.test(name) || /-all-/u.test(name) || /\/all$/u.test(name)
+  const subs = await fetchSubpackageNames(repo, branch, auth)
+  return subs
+    .slice()
+    .sort((a, b) => Number(isAll(b.name)) - Number(isAll(a.name)))
+    .map((sub) => sub.name)
+    .slice(0, 8)
+}
+
+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, subpackageCandidates, ENRICH_CACHE_TTL }

package/lib/server/domain/patch.js

@@ -0,0 +1,203 @@
+// L1 · domain —— patch.js（由 Step 2 从 lib/index.js 原样切出，只搬移未改逻辑）
+// 分组见 D:\dsh\dsh-plugin-hub-plan\architecture.zh.md §三 L1 · domain
+
+import { readFile, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { queuedWrite } from '../infra/fsx.js'
+import { escapeRegExp } from '../infra/mask.js'
+import { resolvePackageJson } from '../infra/paths.js'
+
+/** 读取补丁文件并扫描：停用块与 insert 行的 id。 */
+async function readPatchState(patchPath) {
+  let text = ''
+  try {
+    text = await readFile(patchPath, 'utf8')
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error
+  }
+  const disables = []
+  const forced = []
+  const inserts = []
+  const lines = text.split(/\r?\n/u)
+  let inInsert = false
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]
+    if (/^- insert:\s*$/u.test(line)) {
+      inInsert = true
+      continue
+    }
+    if (/^- /u.test(line)) inInsert = false
+    if (inInsert) {
+      const insertRow = line.match(/^ {4}- id: ([A-Za-z0-9_.-]+)/u)
+      if (insertRow) inserts.push(insertRow[1])
+      continue
+    }
+    const disableRow = line.match(/^- id: ([A-Za-z0-9_.-]+)\s*$/u)
+    if (!disableRow) continue
+    const next = lines[index + 1] ?? ''
+    if (/^ {2}disabled: true\s*$/u.test(next)) disables.push(disableRow[1])
+    else if (/^ {2}disabled: false\s*$/u.test(next)) forced.push(disableRow[1])
+  }
+  return { disables, forced, inserts, text }
+}
+
+/** 停用：追加 disabled:true 块（已存在则不动）。 */
+async function disableEntry(patchPath, id) {
+  return queuedWrite(async () => {
+    const { disables, text } = await readPatchState(patchPath)
+    if (disables.includes(id)) return { changed: false }
+    const clean = sanitizePatchText(text)
+    const next = clean.length === 0 || clean.endsWith('\n') ? clean : `${clean}\n`
+    await writeFile(patchPath, `${next}${disableBlock(id)}`, 'utf8')
+    return { changed: true }
+  })
+}
+
+/** 启用：移除 disabled:true 块；若仍被 bundle 停用则追加 disabled:false 覆盖。 */
+async function enableEntry(patchPath, id) {
+  return queuedWrite(async () => {
+    const { disables, forced, text } = await readPatchState(patchPath)
+    const blockRe = new RegExp(`^- id: ${escapeRegExp(id)}\\r?\\n  disabled: true\\r?\\n`, 'mu')
+    if (blockRe.test(text)) {
+      await writeFile(patchPath, sanitizePatchText(text.replace(blockRe, '')), 'utf8')
+      return { changed: true }
+    }
+    if (forced.includes(id)) return { changed: false }
+    const clean = sanitizePatchText(text)
+    const next = clean.length === 0 || clean.endsWith('\n') ? clean : `${clean}\n`
+    await writeFile(patchPath, `${next}- id: ${id}\n  disabled: false\n`, 'utf8')
+    return { changed: true }
+  })
+}
+
+/** 追加一条 insert 启用行（插件包需已安装到 profile）。 */
+async function appendInsert(patchPath, entryId, packageName) {
+  return queuedWrite(async () => {
+    const { inserts, text } = await readPatchState(patchPath)
+    if (inserts.includes(entryId)) return { changed: false }
+    const clean = sanitizePatchText(text)
+    const next = clean.length === 0 || clean.endsWith('\n') ? clean : `${clean}\n`
+    const block = `- insert:\n    - id: ${entryId}\n      name: '${packageName}'\n`
+    await writeFile(patchPath, `${next}${block}`, 'utf8')
+    return { changed: true }
+  })
+}
+
+/** 从补丁文件移除某行的 insert 块与 disabled/forced 覆盖块。 */
+async function removeInsertRow(patchPath, rowId) {
+  return queuedWrite(async () => {
+    const { text } = await readPatchState(patchPath)
+    const blockRe = new RegExp(`^- insert:\\s*\\r?\\n {4}- id: ${escapeRegExp(rowId)}\\s*\\r?\\n( {6}name: [^\\r\\n]*\\r?\\n)?`, 'mu')
+    let next = text.replace(blockRe, '')
+    const overrideRe = new RegExp(`^- id: ${escapeRegExp(rowId)}\\s*\\r?\\n {2}disabled: (true|false)\\s*\\r?\\n`, 'mu')
+    next = next.replace(overrideRe, '')
+    if (next !== text) await writeFile(patchPath, sanitizePatchText(next), 'utf8')
+  })
+}
+
+/** 移除补丁中的单行 disabled/forced 覆盖块（兼容门解锁用）。 */
+function removeDisableBlock(patchPath, rowId) {
+  return queuedWrite(async () => {
+    const { text } = await readPatchState(patchPath)
+    const overrideRe = new RegExp(`^- id: ${escapeRegExp(rowId)}\\s*\\r?\\n {2}disabled: (true|false)\\s*\\r?\\n`, 'mu')
+    const next = text.replace(overrideRe, '')
+    if (next !== text) await writeFile(patchPath, sanitizePatchText(next), 'utf8')
+  })
+}
+
+/**
+ * 清理补丁文件中的顶层空数组占位符（issue #7 事故教训）：
+ * DSH profile 模板的 cordis.patch.yml 以注释 + 顶层 `[]` 占位符初始化（如 `# ...\n[]`）。
+ * 直接追加条目会生成 `[]` 后又跟 `- id: xxx` 的非法 YAML（同文档流里数组结束符 + 后续项），
+ * 导致 dsh 启动解析崩溃。写入前必须移除顶层独立的 `[]` / `[ ]` 占位行。
+ * 仅处理"整行就是空数组"的占位符；合法内容（如 `- insert:` 列表）不受影响。
+ */
+function sanitizePatchText(text) {
+  return text
+    .split(/\r?\n/u)
+    .filter((line) => !/^\s*\[\s*\]\s*$/u.test(line))
+    .join('\n')
+    .replace(/\n{3,}/gu, '\n\n')
+    .replace(/\s+$/u, '') + '\n'
+}
+
+/** 解析用户补丁中 insert 块的 id → moduleName（name 字段）。 */
+function parseInsertNames(text) {
+  const map = new Map()
+  const lines = text.split(/\r?\n/u)
+  let inInsert = false
+  let curId = null
+  for (const line of lines) {
+    if (/^- insert:\s*$/u.test(line)) { inInsert = true; curId = null; continue }
+    if (inInsert && /^- /u.test(line)) inInsert = false
+    if (inInsert) {
+      const idMatch = line.match(/^\s+- id: ([A-Za-z0-9_.-]+)/u)
+      if (idMatch) { curId = idMatch[1]; continue }
+      if (curId !== null) {
+        const nameMatch = line.match(/^\s+name: ['"]([^'"]+)['"]/u)
+        if (nameMatch) { map.set(curId, nameMatch[1]); curId = null }
+      }
+    }
+  }
+  return map
+}
+
+/**
+ * 补丁安全自愈（服务永不崩机制）：
+ * ① 核心行被误禁用 → 自动移除禁用块恢复；
+ * ② 启用态用户 insert 行的模块缺失（如引用未安装包的行）→ 自动禁用（loader 对缺失模块会致命崩溃）。
+ * return { healed:[], autoDisabled:[], healedAt } —— healedAt=0 表示本次无修改。
+ */
+async function healPatchSafety(patchPath) {
+  const profileDir = dirname(patchPath)
+  const { text } = await readPatchState(patchPath)
+  let next = text
+  const healed = []
+  const autoDisabled = []
+  for (const id of CORE_PATCH_ROW_IDS) {
+    const re = new RegExp(`^- id: ${escapeRegExp(id)}\\s*\\r?\\n {2}disabled: true\\s*\\r?\\n`, 'mu')
+    if (re.test(next)) {
+      next = next.replace(re, '')
+      healed.push(id)
+    }
+  }
+  if (healed.length === 0) {
+    const insertNames = parseInsertNames(next)
+    let require = null
+    for (const [id, moduleName] of insertNames) {
+      if (!moduleName || moduleName.startsWith('cordis:')) continue
+      let ok = true
+      try { ok = resolvePackageJson(moduleName, profileDir) !== null } catch { ok = false }
+      if (!ok && !new RegExp(`^- id: ${escapeRegExp(id)}\\s*\\r?\\n {2}disabled: true\\s*\\r?\\n`, 'mu').test(next)) {
+        next = `${next.trimEnd()}\n- id: ${id}\n  disabled: true\n`
+        autoDisabled.push(id)
+      }
+    }
+  }
+  if (next !== text) {
+    await writeFile(patchPath, sanitizePatchText(next), 'utf8')
+  }
+  return { healed, autoDisabled, healedAt: next !== text ? Date.now() : 0 }
+}
+
+/** 从「子包版本对齐」记录解析纯包名（如 '@linxin666/dsh-pet@0.2.1（新装）'）。 */
+function syncNameFromNote(note) {
+  const m = String(note ?? '').match(/^((?:@[^/]+\/)?[^@]+)/u)
+  return m ? m[1] : null
+}
+
+/** 框架核心行：误禁用会导致启动失败（2026-09-04 session-persistence-jsonl 事故：6 行 pending、
+ * 启动断言失败）。任何补丁写入（适配门/脚本/工具）都禁止禁用这些行；自愈机制自动恢复误禁。 */
+const CORE_PATCH_ROW_IDS = new Set([
+  'session-persistence-jsonl', 'webserver', 'timer', 'hmr', 'session', 'session-checkpoint-policy',
+  'message-feedback', 'workspace', 'storage', 'storage-json', 'storage-domain', 'api-gateway',
+  'api-session-controller', 'api-workspace-controller', 'credentials', 'settings', 'attachment-local',
+  'subprocess', 'sandbox', 'sandbox-policy', 'shell-env', 'agent', 'agent-loop', 'llm', 'web-runtime', 'web-startup',
+])
+
+function disableBlock(id) {
+  return `- id: ${id}\n  disabled: true\n`
+}
+
+export { readPatchState, disableEntry, enableEntry, appendInsert, removeInsertRow, removeDisableBlock, sanitizePatchText, parseInsertNames, healPatchSafety, syncNameFromNote, CORE_PATCH_ROW_IDS, disableBlock }
+