dsh-data-domain-knowledge 0.1.0-alpha.9 → 0.1.1-alpha.2

package/src/environment/install.ts

@@ -0,0 +1,244 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { chmod, copyFile, mkdir, open, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { modelsForSelection, UV_VERSION } from './manifest.js'
+import { DEFAULT_MODEL_SELECTION, type ModelSelection } from './model-catalog.js'
+import { writeModelSelection } from './selection.js'
+import { runProcess, type ProcessOptions } from './process.js'
+import { hasHardenedRuntime, needsManagedInterpreter, pickBasePython, pythonSourceLabel } from './dsh-python.js'
+
+export const requirementsFile = fileURLToPath(new URL('../../../python/requirements.txt', import.meta.url))
+export const setupScript = fileURLToPath(new URL('../../../python/prepare-models.py', import.meta.url))
+export function managedPython(root: string): string { return process.platform === 'win32' ? join(root, 'python', 'Scripts', 'python.exe') : join(root, 'python', 'bin', 'python') }
+
+/** 只问次版本：判断的是「能不能装这套依赖」，不是补丁号。 */
+const PYTHON_VERSION_SCRIPT = 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")'
+/** 推理依赖支持的解释器区间（torch 的 wheel 覆盖到 3.13）。 */
+const SUPPORTED_PYTHON = /^3\.(10|11|12|13)$/
+/** 走 uv 管理解释器时请求的版本：与桌面端自带的那份对齐，避免两套行为。 */
+const MANAGED_PYTHON = '3.12'
+
+async function download(url: string, signal: AbortSignal): Promise<Buffer> {
+  const response = await fetch(url, { signal: AbortSignal.any([signal, AbortSignal.timeout(120_000)]) })
+  if (!response.ok) throw new Error(`下载失败（HTTP ${response.status}）：${url}`)
+  return Buffer.from(await response.arrayBuffer())
+}
+
+async function findExecutable(root: string, name: string): Promise<string | undefined> {
+  for (const entry of await readdir(root, { withFileTypes: true })) {
+    const path = join(root, entry.name)
+    if (entry.isFile() && entry.name === name) return path
+    if (entry.isDirectory()) { const found = await findExecutable(path, name); if (found) return found }
+  }
+  return undefined
+}
+
+/** Prefer existing uv; otherwise install a checksummed release in this resource root. */
+async function ensureUv(root: string, signal: AbortSignal, log: (line: string) => void, run: typeof runProcess): Promise<string> {
+  const name = process.platform === 'win32' ? 'uv.exe' : 'uv'
+  for (const candidate of [join(root, 'tools', name), 'uv', join(homedir(), '.local', 'bin', name), join(homedir(), '.cargo', 'bin', name)]) {
+    try { await run(candidate, ['--version'], { signal }); return candidate } catch { if (signal.aborted) throw new Error('ENVIRONMENT_CANCELLED') }
+  }
+  const arch = process.arch === 'arm64' ? 'aarch64' : process.arch === 'x64' ? 'x86_64' : undefined
+  const target = process.platform === 'darwin' ? 'apple-darwin' : process.platform === 'linux' ? 'unknown-linux-gnu' : process.platform === 'win32' ? 'pc-windows-msvc' : undefined
+  if (!arch || !target) throw new Error(`暂不支持自动安装：${process.platform}/${process.arch}，请手动安装 uv 后重试`)
+  const extension = process.platform === 'win32' ? 'zip' : 'tar.gz'
+  const asset = `uv-${arch}-${target}.${extension}`
+  const url = `https://github.com/astral-sh/uv/releases/download/${UV_VERSION}/${asset}`
+  log('正在下载 Python 安装工具 uv')
+  const checksum = (await download(`${url}.sha256`, signal)).toString().match(/[a-f0-9]{64}/i)?.[0]
+  const archive = await download(url, signal)
+  if (!checksum || createHash('sha256').update(archive).digest('hex') !== checksum.toLowerCase()) throw new Error('uv 下载文件校验失败，请重试')
+  const scratch = join(root, `.setup-uv-${randomUUID()}`)
+  await mkdir(scratch, { recursive: true })
+  try {
+    const path = join(scratch, asset)
+    await writeFile(path, archive)
+    if (process.platform === 'win32') {
+      const script = join(scratch, 'expand.ps1')
+      await writeFile(script, 'param([string]$Archive,[string]$Destination)\nExpand-Archive -LiteralPath $Archive -DestinationPath $Destination\n')
+      await run('powershell.exe', ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', script, path, join(scratch, 'expanded')], { signal })
+    } else await run('tar', ['-xzf', path, '-C', scratch], { signal })
+    const binary = await findExecutable(scratch, name)
+    if (!binary) throw new Error('uv 安装包缺少可执行文件')
+    const destination = join(root, 'tools', name)
+    await mkdir(dirname(destination), { recursive: true })
+    await copyFile(binary, destination)
+    if (process.platform !== 'win32') await chmod(destination, 0o755)
+    return destination
+  } finally { await rm(scratch, { recursive: true, force: true }) }
+}
+
+/**
+ * 一把「陈旧」锁可以被接管的时限。
+ *
+ * 单步安装超时是 30 分钟，整轮远小于这个上限，所以 6 小时之后还在的锁一定是崩溃残留。
+ * 有了它，「持锁进程已死但 PID 被系统复用」才不会让用户永久卡在「另一个进程正在准备环境」上。
+ */
+const STALE_LOCK_MS = 6 * 60 * 60 * 1000
+
+async function installLock(root: string): Promise<() => Promise<void>> {
+  const path = join(root, 'environment-install.lock')
+  /** 这一把锁的归属凭据。释放时靠它判断「这份文件还是不是我的」。 */
+  const token = randomUUID()
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      const file = await open(path, 'wx')
+      try { await file.writeFile(JSON.stringify({ token, pid: process.pid, at: new Date().toISOString() })) }
+      catch (cause) { await rm(path, { force: true }); throw cause }
+      finally { await file.close() }
+      return async () => {
+        /**
+         * 只删**自己那一把**。判据是 token，不是「路径上有没有文件」：锁可能已被另一个
+         * 进程按陈旧接管过，那时这份文件是它的 —— 删掉就等于让两个安装并发写同一个 venv。
+         */
+        try {
+          const current = JSON.parse(await readFile(path, 'utf8')) as { token?: unknown }
+          if (current.token === token) await rm(path, { force: true })
+        } catch { /* 已被接管或已不存在：不是自己的锁就不动 */ }
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+      let holder: { token?: unknown; pid?: unknown; at?: unknown } | undefined
+      try { holder = JSON.parse(await readFile(path, 'utf8')) as { token?: unknown; pid?: unknown; at?: unknown } } catch { holder = undefined }
+      if (holder === undefined) {
+        /**
+         * 解析不了（0 字节、半截 JSON、磁盘满）也要能自愈。
+         *
+         * 锁是「`open('wx')` 建文件 → 再写内容」两步，中间被杀就会留下这种文件；
+         * 原来这里直接抛「安装锁异常」，于是**每一次**安装尝试都失败，只能人工删锁。
+         * 判据换成文件的 mtime：与「持锁进程还活着」同一套时限，超时就接管。
+         */
+        const info = await stat(path).catch(() => undefined)
+        const aged = info !== undefined && Date.now() - info.mtimeMs > STALE_LOCK_MS
+        if (!aged) throw new Error('安装锁异常，请检查 resource/environment-install.lock')
+        await rm(path, { force: true })
+        continue
+      }
+      const pid = Number(holder.pid)
+      const at = Date.parse(String(holder.at ?? ''))
+      const aged = Number.isFinite(at) && Date.now() - at > STALE_LOCK_MS
+      if (!Number.isInteger(pid) || pid <= 0) {
+        // 内容不成立：没到期就如实报出来让人看一眼，到期了才当陈旧处理。
+        if (!aged) throw new Error('安装锁异常，请检查 resource/environment-install.lock')
+      } else {
+        let dead = false
+        try { process.kill(pid, 0) } catch (cause) { dead = (cause as NodeJS.ErrnoException).code === 'ESRCH' }
+        // `dead`（进程真的没了）或 `aged`（号码可能已被别人复用）任一成立都算陈旧。
+        if (!dead && !aged) throw new Error('另一个进程正在准备环境，请等待完成后重试')
+      }
+      /**
+       * 接管之前**再读一次**并确认还是刚才那一把。读完到删之间仍有一个极窄的窗口，
+       * 但「先删后判」会让两个进程同时接管同一把锁 —— 那才是真正的并发安装。
+       */
+      try {
+        const again = JSON.parse(await readFile(path, 'utf8')) as { token?: unknown }
+        if (again.token !== holder.token) continue
+      } catch { continue }
+      await rm(path, { force: true })
+    }
+  }
+  throw new Error('无法获取环境安装锁')
+}
+
+/**
+ * 准备这个库的推理运行时。
+ *
+ * `basePython` 省略时按 `pickBasePython()` 找：`DSH_PYTHON` → DSH 自带运行时 → PATH 上的
+ * `python3`。**默认值不能再写死 `python3`**：macOS 命令行工具自带的是 3.9，而桌面端明明把
+ * 3.12 打在了自己的运行时里 —— 写死默认值会让「一键准备」在任何没配 `DSH_PYTHON` 的机器上
+ * 第一步就失败（见 `dsh-python.ts` 的注释）。
+ */
+export async function installRequiredEnvironment(root: string, signal: AbortSignal, stage: (label: string) => void, log: (line: string) => void, runner: typeof runProcess = runProcess, selection: ModelSelection = DEFAULT_MODEL_SELECTION, basePython?: string, hardened: (path: string) => Promise<boolean> = path => hasHardenedRuntime(path, runner)): Promise<void> {
+  await mkdir(root, { recursive: true })
+  const picked = basePython === undefined ? pickBasePython() : { path: basePython, source: 'override' as const }
+  const unlock = await installLock(root)
+  const env = {
+    ...process.env,
+    UV_CACHE_DIR: join(root, 'cache', 'uv'),
+    /**
+     * uv 自己管理的解释器也落在资源目录里：它和依赖、模型一样属于「这个 Agent 的家当」，
+     * 备份 / 迁移 / 删除该一起走，而不是散到 `~/.local/share/uv/python`。
+     */
+    UV_PYTHON_INSTALL_DIR: join(root, 'tools', 'python'),
+    HF_HOME: join(root, 'cache', 'huggingface'),
+    PIP_DISABLE_PIP_VERSION_CHECK: '1',
+  }
+  const run = (command: string, args: string[], extra: ProcessOptions = {}): Promise<string> => runner(command, args, { env, signal, timeoutMs: 30 * 60_000, onLine: log, ...extra })
+  try {
+    stage('准备模型运行时')
+    const uv = await ensureUv(root, signal, log, runner)
+    log(`基础 Python：${picked.path}（${pythonSourceLabel(picked.source)}）`)
+    /**
+     * 自带运行时那份 Python 带 hardened runtime，**装不了 torch**（见 `hasHardenedRuntime`）：
+     * 库校验只喂它自己 Team ID 签的 dylib，而 pip 上的原生轮子是 ad-hoc 签名的。
+     * 这时改用 uv 管的独立 CPython（不带 hardened runtime），装到 `<resource>/tools/python`。
+     *
+     * 显式给了 `DSH_PYTHON` 就不改道 —— 那是用户的选择，只把风险写进日志。
+     */
+    const isHardened = await hardened(picked.path)
+    const managed = needsManagedInterpreter(picked, isHardened)
+    if (isHardened && picked.source === 'override') {
+      log(`注意：${picked.path} 带 hardened runtime，第三方原生扩展（torch 等）可能加载不了。`)
+    }
+    let baseVersion: string | undefined
+    if (managed) {
+      log('基础 Python：由 uv 管理的独立 CPython 3.12（自带的那份带 hardened runtime，加载不了第三方原生扩展）')
+    } else {
+      log(`基础 Python：${picked.path}（${pythonSourceLabel(picked.source)}）`)
+      const versionOutput = await run(picked.path, ['-c', PYTHON_VERSION_SCRIPT], { timeoutMs: 15_000 })
+      baseVersion = versionOutput.trim().split(/\r?\n/).at(-1)
+      if (!baseVersion || !SUPPORTED_PYTHON.test(baseVersion)) {
+        /**
+         * 这句要能直接照着做。原来只说「版本不受支持」，而人看到的是自己机器上
+         * `python3 --version` 报 3.9 —— 会以为插件在挑刺，不知道桌面端本身带了 3.12。
+         */
+        throw new Error([
+          `DSH Python 版本不受支持：${baseVersion || '无法读取'}（${picked.path}，来自${pythonSourceLabel(picked.source)}）；需要 Python 3.10–3.13。`,
+          picked.source === 'path'
+            ? '没有找到 DSH 自带的 Python（桌面端运行时里应有一份 3.12）。请安装 Python 3.10–3.13，再用环境变量 DSH_PYTHON 指向它。'
+            : `请把 DSH_PYTHON 指向一个 3.10–3.13 的解释器后重试。`,
+        ].join(' '))
+      }
+    }
+    const python = managedPython(root)
+    let compatible = false
+    if (existsSync(python)) {
+      try {
+        const current = (await run(python, ['-c', PYTHON_VERSION_SCRIPT], { timeoutMs: 15_000 })).trim().split(/\r?\n/).at(-1)
+        // 管好的解释器只要求落在支持区间（它的次版本会随 uv 走），其余必须与基础解释器同一个次版本。
+        const versionOk = managed ? SUPPORTED_PYTHON.test(current ?? '') : current === baseVersion
+        /**
+         * 还要**真的**确认这个环境不带 hardened runtime。
+         *
+         * 只比版本的话，一个用自带 Python 建出来的 3.12 环境会被判成「兼容」，于是「修复」
+         * 不重建 —— 而它正是装不了 torch 的那一个。`codesign` 跟着符号链接走，
+         * 所以这里量的是它最终指向的那个解释器。
+         */
+        compatible = versionOk && (!managed || !(await hardened(python)))
+      } catch { if (signal.aborted) throw new Error('ENVIRONMENT_CANCELLED') }
+    }
+    if (!compatible) {
+      if (existsSync(join(root, 'python'))) {
+        const backup = join(root, `python-backup-${randomUUID()}`)
+        await rename(join(root, 'python'), backup)
+        log(`原模型运行环境不可用，已保留备份：${backup}`)
+      }
+      await run(uv, ['venv',
+        ...(managed ? ['--python', MANAGED_PYTHON, '--python-preference', 'only-managed'] : ['--python', picked.path, '--python-preference', 'only-system']),
+        join(root, 'python')])
+      if (managed) log(`基础 Python：${(await run(python, ['-c', PYTHON_VERSION_SCRIPT], { timeoutMs: 15_000 })).trim()}（uv 管理的独立 CPython）`)
+    }
+    stage('安装推理依赖')
+    await run(uv, ['pip', 'install', '--reinstall', '--python', python, '-r', requirementsFile])
+    const selectedModels = modelsForSelection(selection)
+    for (const model of selectedModels) {
+      stage(model.kind === 'embedding' ? '下载向量模型' : '下载重排模型')
+      await run(python, [setupScript, '--repo', model.repo, '--revision', model.revision, '--destination', join(root, 'models', model.directory)])
+    }
+    await writeModelSelection(root, selection)
+  } finally { await unlock() }
+}

package/src/environment/manifest.ts

@@ -0,0 +1,28 @@
+import { DEFAULT_MODEL_SELECTION, embeddingModel, rerankModel } from './model-catalog.js'
+
+/** Revisions are immutable Hub commit IDs, not a moving main branch. */
+export const MODEL_REVISIONS = {
+  'bge-small-zh-v1.5': '7999e1d3359715c523056ef9478215996d62a620',
+  'bge-base-zh-v1.5': 'f03589ceff5aac7111bd60cfc7d497ca17ecac65',
+  'bge-large-zh-v1.5': '79e7739b6ab944e86d6171e44d24c997fc1e0116',
+  'wemm-embedding-2b-quantized': '524bbe61e1b8ce4673e4e17dcf6a8694a3c45993',
+  'wemm-embedding-2b': 'bbd6cd4bf52cfc6716f752a2df80b2706720bd95',
+  'bge-reranker-base': '2cfc18c9415c912f9d8155881c133215df768a70',
+  'bge-reranker-large': '55611d7bca2a7133960a6d3b71e083071bbfc312',
+  'qwen3-reranker-0.6b': 'e61197ed45024b0ed8a2d74b80b4d909f1255473',
+  'qwen3-reranker-4b': '22e683669bc0f0bd69640a1354a6d0aebcfeede5',
+  'qwen3-reranker-8b': '77d193c791ed757ca307ee72715aa132723da912',
+} as const
+
+export function modelsForSelection(selection = DEFAULT_MODEL_SELECTION) {
+  const embedding = embeddingModel(selection.embedding)
+  const rerank = rerankModel(selection.rerank)
+  return [
+    { ...embedding, kind: 'embedding' as const, revision: MODEL_REVISIONS[embedding.id] },
+    { ...rerank, kind: 'rerank' as const, revision: MODEL_REVISIONS[rerank.id] },
+  ]
+}
+
+export const REQUIRED_MODELS = modelsForSelection()
+export const UV_VERSION = '0.13.1'
+export const ENVIRONMENT_PROBE_VERSION = 3

package/src/environment/model-catalog.ts

@@ -0,0 +1,147 @@
+/**
+ * Models supported by the local embedding and reranking workers. Revisions are pinned in manifest.ts.
+ *
+ * 这一份是**纯数据**：客户端也要 import 它（模型选项、下载量的文案），所以这里不能出现
+ * `node:*`。磁盘上有没有那份模型由服务端判（`modelOptionsView(root)`）。
+ */
+export const EMBEDDING_MODELS = [
+  {
+    id: 'bge-small-zh-v1.5', repo: 'BAAI/bge-small-zh-v1.5', directory: 'bge-small-zh-v1.5',
+    label: 'BGE Small 中文', dimension: 512, download: '约 96 MB',
+    description: '资源占用最低，适合先跑通本地知识检索。',
+  },
+  {
+    id: 'bge-base-zh-v1.5', repo: 'BAAI/bge-base-zh-v1.5', directory: 'bge-base-zh-v1.5',
+    label: 'BGE Base 中文', dimension: 768, download: '约 409 MB',
+    description: '效果与资源占用较均衡。',
+  },
+  {
+    id: 'bge-large-zh-v1.5', repo: 'BAAI/bge-large-zh-v1.5', directory: 'bge-large-zh-v1.5',
+    label: 'BGE Large 中文', dimension: 1024, download: '约 1.3 GB',
+    description: '中文向量效果优先，需要更多内存与磁盘。',
+  },
+  {
+    id: 'wemm-embedding-2b-quantized', repo: 'ewin-reg/WeMM-Embedding-2B-Quantized', directory: 'WeMM-Embedding-2B-Quantized',
+    label: 'WeMM Embedding 2B 社区量化版', dimension: 2048, download: '约 1.8 GB',
+    description: '社区维护的 INT4 / FP8 量化模型，非腾讯官方发布；模型卡标注 license: other，请查看协议。',
+  },
+  {
+    id: 'wemm-embedding-2b', repo: 'tencent/WeMM-Embedding-2B', directory: 'WeMM-Embedding-2B',
+    label: '腾讯 WeMM Embedding 2B（BF16）', dimension: 2048, download: '约 5.5 GB',
+    description: '多模态向量模型，支持文本和图片；下载与推理资源占用较高。',
+  },
+] as const
+
+export const RERANK_MODELS = [
+  {
+    id: 'bge-reranker-base', repo: 'BAAI/bge-reranker-base', directory: 'bge-reranker-base',
+    label: 'BGE Reranker Base', download: '约 1.1 GB',
+    description: '中文重排的轻量选项。',
+  },
+  {
+    id: 'qwen3-reranker-0.6b', repo: 'Qwen/Qwen3-Reranker-0.6B', directory: 'Qwen3-Reranker-0.6B',
+    label: 'Qwen3 Reranker 0.6B', download: '约 1.2 GB',
+    description: '支持 100 多种语言，适合先试用 Qwen 重排。',
+  },
+  {
+    id: 'bge-reranker-large', repo: 'BAAI/bge-reranker-large', directory: 'bge-reranker-large',
+    label: 'BGE Reranker Large', download: '约 2.2 GB',
+    description: '中文和英文重排效果优先，推理速度较慢。',
+  },
+  {
+    id: 'qwen3-reranker-4b', repo: 'Qwen/Qwen3-Reranker-4B', directory: 'Qwen3-Reranker-4B',
+    label: 'Qwen3 Reranker 4B', download: '约 8.1 GB',
+    description: 'Qwen 中档重排模型；请先确认磁盘与内存充足。',
+  },
+  {
+    id: 'qwen3-reranker-8b', repo: 'Qwen/Qwen3-Reranker-8B', directory: 'Qwen3-Reranker-8B',
+    label: 'Qwen3 Reranker 8B', download: '约 16.4 GB',
+    description: '资源占用最高；下载前请确认有足够磁盘与内存。',
+  },
+] as const
+
+export type EmbeddingModelId = (typeof EMBEDDING_MODELS)[number]['id']
+export type RerankModelId = (typeof RERANK_MODELS)[number]['id']
+export interface ModelSelection { embedding: EmbeddingModelId; rerank: RerankModelId }
+export interface ModelOptionView {
+  id: string
+  label: string
+  dimension?: number
+  download: string
+  description: string
+  modelCardUrl?: string
+  /**
+   * 这份模型在资源目录里是否**完整**（有 config、有权重、有分词器词表）。
+   * 省略 = 服务端没给资源目录，不知道 —— 不知道就不显示徽标，不猜。
+   */
+  installed?: boolean
+}
+export const DEFAULT_MODEL_SELECTION: ModelSelection = {
+  embedding: 'bge-small-zh-v1.5',
+  rerank: 'bge-reranker-base',
+}
+
+export function isModelSelection(value: unknown): value is ModelSelection {
+  if (!value || typeof value !== 'object') return false
+  const selection = value as Record<string, unknown>
+  return EMBEDDING_MODELS.some(model => model.id === selection.embedding)
+    && RERANK_MODELS.some(model => model.id === selection.rerank)
+}
+
+export function parseModelSelection(value: unknown, fallback = DEFAULT_MODEL_SELECTION): ModelSelection {
+  if (value === undefined || value === null) return { ...fallback }
+  if (!isModelSelection(value)) throw new Error('模型选择无效，请重新选择向量模型和重排模型')
+  return { embedding: value.embedding, rerank: value.rerank }
+}
+
+export function embeddingModel(id: EmbeddingModelId) {
+  return EMBEDDING_MODELS.find(model => model.id === id)!
+}
+
+export function rerankModel(id: RerankModelId) {
+  return RERANK_MODELS.find(model => model.id === id)!
+}
+
+/**
+ * 把「约 1.1 GB」这样的文案换回字节数。
+ *
+ * 判据只留一份：**目录里写的就是那句文案**（顺序与大小都在那里定），再写一份数字字段迟早
+ * 会和它对不上。格式是我们自己定的（`约 <数字> MB|GB`），认不出来就返回 undefined ——
+ * 算不出总数时宁可不显示总数，也不编一个。
+ */
+export function downloadBytes(text: string): number | undefined {
+  const matched = /约\s*([\d.]+)\s*(MB|GB)/i.exec(text)
+  if (!matched) return undefined
+  const value = Number(matched[1])
+  if (!Number.isFinite(value)) return undefined
+  return Math.round(value * (matched[2].toUpperCase() === 'GB' ? 1024 ** 3 : 1024 ** 2))
+}
+
+/** 字节数 → 「约 1.2 GB / 约 96 MB」。用于把几个模型加起来报一个总数。 */
+export function formatBytes(bytes: number): string {
+  if (bytes >= 1024 ** 3) return `约 ${(bytes / 1024 ** 3).toFixed(1)} GB`
+  return `约 ${Math.max(1, Math.round(bytes / 1024 ** 2))} MB`
+}
+
+/**
+ * 模型选项。
+ *
+ * `installed` 是一个**回调**而不是路径：这一份是纯数据模块（客户端也 import 它），
+ * 而「磁盘上有没有、完不完整」要用 `node:fs` 判。服务端把判据传进来，顺便也就把它
+ * 与自检那一栏的「模型结构」检查绑成了**同一个函数** —— 否则会出现「选项说已下载、
+ * 自检说文件不全」这种同一件事两种说法。
+ *
+ * 不传回调就省略 `installed`：不知道就别猜，客户端也就不显示徽标。
+ */
+export function modelOptionsView(installed?: (directory: string) => boolean) {
+  const present = <T extends { id: string; label: string; download: string; description: string; repo: string; directory: string }>(model: T) => ({
+    id: model.id, label: model.label, download: model.download, description: model.description,
+    modelCardUrl: `https://huggingface.co/${model.repo}`,
+    ...(installed === undefined ? {} : { installed: installed(model.directory) }),
+    ...('dimension' in model ? { dimension: model.dimension as number } : {}),
+  })
+  return {
+    embedding: EMBEDDING_MODELS.map(present),
+    rerank: RERANK_MODELS.map(present),
+  }
+}

package/src/environment/process.ts

@@ -0,0 +1,54 @@
+import { spawn } from 'node:child_process'
+
+export interface ProcessOptions {
+  cwd?: string
+  env?: NodeJS.ProcessEnv
+  signal?: AbortSignal
+  timeoutMs?: number
+  onLine?: (line: string) => void
+}
+
+/** No shell, bounded output, and only this child PID is stopped. */
+export function runProcess(command: string, args: string[], options: ProcessOptions = {}): Promise<string> {
+  return new Promise((resolve, reject) => {
+    if (options.signal?.aborted) return reject(new Error('ENVIRONMENT_CANCELLED'))
+    const child = spawn(command, args, { cwd: options.cwd, env: options.env ?? process.env, stdio: ['ignore', 'pipe', 'pipe'] })
+    let output = '', tail = '', settled = false, stopError: Error | undefined
+    let killTimer: ReturnType<typeof setTimeout> | undefined
+    const end = (error?: Error): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      clearTimeout(killTimer)
+      options.signal?.removeEventListener('abort', cancel)
+      if (error) reject(error)
+      else resolve(output)
+    }
+    // Keep the install lock until this owned child has actually exited.
+    const stop = (error: Error): void => {
+      if (settled || stopError) return
+      stopError = error
+      clearTimeout(timer)
+      child.kill('SIGTERM')
+      killTimer = setTimeout(() => child.kill('SIGKILL'), 1500)
+    }
+    const cancel = (): void => stop(new Error('ENVIRONMENT_CANCELLED'))
+    const timer = setTimeout(() => stop(new Error(`环境步骤超时：${command}`)), options.timeoutMs ?? 30_000)
+    options.signal?.addEventListener('abort', cancel, { once: true })
+    const receive = (data: Buffer): void => {
+      const text = data.toString()
+      output = (output + text).slice(-128_000)
+      tail = (tail + text).slice(-16_000)
+      const lines = tail.split(/[\r\n]+/)
+      tail = lines.pop() ?? ''
+      for (const line of lines) if (line.trim()) options.onLine?.(line.trim())
+    }
+    child.stdout.on('data', receive)
+    child.stderr.on('data', receive)
+    child.once('error', error => end(error))
+    child.once('close', code => {
+      if (tail.trim()) options.onLine?.(tail.trim())
+      end(stopError ?? (code === 0 ? undefined : new Error(`环境步骤失败（${code ?? '已停止'}）：${output.slice(-3000).trim() || command}`)))
+    })
+  })
+}

package/src/environment/selection.ts

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { DEFAULT_MODEL_SELECTION, embeddingModel, isModelSelection, type ModelSelection } from './model-catalog.js'
+
+export const MODEL_SELECTION_FILE = 'environment-model-selection.json'
+
+export function readModelSelection(resourceRoot: string): ModelSelection {
+  try {
+    const value: unknown = JSON.parse(readFileSync(join(resourceRoot, MODEL_SELECTION_FILE), 'utf8'))
+    if (isModelSelection(value)) return { embedding: value.embedding, rerank: value.rerank }
+  } catch { /* first install or damaged selection: use the shipped defaults */ }
+  return { ...DEFAULT_MODEL_SELECTION }
+}
+
+export function selectedEmbedding(resourceRoot: string | undefined): { path?: string; dimension?: number } {
+  if (!resourceRoot) return {}
+  const model = embeddingModel(readModelSelection(resourceRoot).embedding)
+  const path = join(resourceRoot, 'models', model.directory)
+  return existsSync(path) ? { path, dimension: model.dimension } : {}
+}
+
+export async function writeModelSelection(resourceRoot: string, selection: ModelSelection): Promise<void> {
+  await mkdir(resourceRoot, { recursive: true })
+  const destination = join(resourceRoot, MODEL_SELECTION_FILE)
+  const temporary = `${destination}.${process.pid}.tmp`
+  await writeFile(temporary, `${JSON.stringify(selection, null, 2)}\n`, 'utf8')
+  await rename(temporary, destination)
+}