dsh-data-domain-knowledge 0.1.0-alpha.13 → 0.1.0-alpha.15

package/src/environment/install.ts

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto'
 import { existsSync } from 'node:fs'
-import { chmod, copyFile, mkdir, open, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
+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'
@@ -8,11 +8,19 @@ 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}`)
@@ -64,49 +72,153 @@ async function ensureUv(root: string, signal: AbortSignal, log: (line: string) =
   } 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')
-  for (let attempt = 0; attempt < 2; attempt++) {
+  /** 这一把锁的归属凭据。释放时靠它判断「这份文件还是不是我的」。 */
+  const token = randomUUID()
+  for (let attempt = 0; attempt < 3; attempt++) {
     try {
       const file = await open(path, 'wx')
-      try { await file.writeFile(JSON.stringify({ pid: process.pid, at: new Date().toISOString() })) }
+      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 () => rm(path, { force: true })
+      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 pid = 0
-      try { pid = Number(JSON.parse(await readFile(path, 'utf8')).pid) } catch { throw new Error('安装锁异常，请检查 resource/environment-install.lock') }
-      if (!Number.isInteger(pid) || pid <= 0) throw new Error('安装锁异常，请检查 resource/environment-install.lock')
-      try { process.kill(pid, 0); throw new Error('另一个进程正在准备环境，请等待完成后重试') }
-      catch (cause) {
-        if ((cause as NodeJS.ErrnoException).code !== 'ESRCH') throw cause
+      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('无法获取环境安装锁')
 }
 
-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 = process.env.DSH_PYTHON || 'python3'): Promise<void> {
+/**
+ * 准备这个库的推理运行时。
+ *
+ * `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'), HF_HOME: join(root, 'cache', 'huggingface'), PIP_DISABLE_PIP_VERSION_CHECK: '1' }
+  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)
-    const versionOutput = await run(basePython, ['-c', 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")'], { timeoutMs: 15_000 })
-    const baseVersion = versionOutput.trim().split(/\r?\n/).at(-1)
-    if (!baseVersion || !/^3\.(10|11|12|13)$/.test(baseVersion)) {
-      throw new Error(`DSH Python 版本不受支持：${baseVersion || '无法读取'}；需要 Python 3.10–3.13`)
+    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 output = await run(python, ['-c', 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")'], { timeoutMs: 15_000 })
-        compatible = output.trim().split(/\r?\n/).at(-1) === baseVersion
+        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) {
@@ -115,7 +227,10 @@ export async function installRequiredEnvironment(root: string, signal: AbortSign
         await rename(join(root, 'python'), backup)
         log(`原模型运行环境不可用，已保留备份：${backup}`)
       }
-      await run(uv, ['venv', '--python', basePython, '--python-preference', 'only-system', join(root, 'python')])
+      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])

package/src/environment/model-catalog.ts

@@ -1,4 +1,9 @@
-/** Models supported by the local embedding and reranking workers. Revisions are pinned in manifest.ts. */
+/**
+ * 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',
@@ -65,6 +70,11 @@ export interface ModelOptionView {
   download: string
   description: string
   modelCardUrl?: string
+  /**
+   * 这份模型在资源目录里是否**完整**（有 config、有权重、有分词器词表）。
+   * 省略 = 服务端没给资源目录，不知道 —— 不知道就不显示徽标，不猜。
+   */
+  installed?: boolean
 }
 export const DEFAULT_MODEL_SELECTION: ModelSelection = {
   embedding: 'bge-small-zh-v1.5',
@@ -92,10 +102,42 @@ export function rerankModel(id: RerankModelId) {
   return RERANK_MODELS.find(model => model.id === id)!
 }
 
-export function modelOptionsView() {
-  const present = <T extends { id: string; label: string; download: string; description: string; repo: string }>(model: T) => ({
+/**
+ * 把「约 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 {

package/src/environment/service.ts

@@ -1,28 +1,59 @@
 import { createHash, randomUUID } from 'node:crypto'
-import { readdirSync, statSync } from 'node:fs'
+import { readFileSync, readdirSync, statSync } from 'node:fs'
 import { mkdir, writeFile } from 'node:fs/promises'
-import { dirname, isAbsolute, join } from 'node:path'
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path'
 import { embeddingFingerprint } from '../compiler/embedding-identity.js'
 import type { RuntimeKnowledgeConfig } from '../types.js'
+import { hasHardenedRuntime } from './dsh-python.js'
 import { installRequiredEnvironment, requirementsFile } from './install.js'
-import { modelOptionsView, parseModelSelection, type ModelSelection } from './model-catalog.js'
+import { EMBEDDING_MODELS, modelOptionsView, parseModelSelection, RERANK_MODELS, type ModelSelection } from './model-catalog.js'
 import { ENVIRONMENT_PROBE_VERSION } from './manifest.js'
 import { runProcess } from './process.js'
 import { readModelSelection, writeModelSelection } from './selection.js'
-import type { EnvironmentItem, EnvironmentItemId, EnvironmentReport, EnvironmentView } from './types.js'
+import type { EnvironmentCurrentModel, EnvironmentItem, EnvironmentItemId, EnvironmentReport, EnvironmentView } from './types.js'
 
 export interface EnvironmentOptions {
   resourceRoot: string
   snapshot: () => { config: RuntimeKnowledgeConfig; paths: { python: string; embeddingModel: string; rerankModel: string } }
   probe: (kind: 'embedding' | 'rerank') => Promise<{ ok: boolean; message: string }>
   reload: () => void
+  activateSelection?: () => Promise<() => Promise<void>>
   run?: typeof runProcess
   install?: typeof installRequiredEnvironment
 }
 
 const labels = { embedding: '向量模型', rerank: '重排模型' }
+const CHECK_FILE = 'environment-last-check.json'
+type ModelCatalogEntry = { id: string; label: string; directory: string; repo: string }
+function currentModel(root: string, path: string, catalog: readonly ModelCatalogEntry[], disabled: boolean, provider?: string): EnvironmentCurrentModel {
+  if (disabled) return { state: 'disabled', label: '未启用' }
+  if (provider) return { state: 'active', label: `${provider} · ${basename(path) || path || '未指定模型'}` }
+  const option = catalog.find(model => isAbsolute(path)
+    ? resolve(path) === resolve(join(root, 'models', model.directory))
+    : path === model.repo)
+  if (option) return { state: 'active', id: option.id, label: option.label }
+  const name = isAbsolute(path) ? basename(path) : basename(path.replaceAll('\\', '/'))
+  return { state: 'active', label: `自定义模型 · ${name || '未指定模型'}` }
+}
 function blankReport(): EnvironmentReport {
-  return { state: 'unchecked', required: true, items: (['embedding', 'rerank'] as const).map(id => ({ id, label: labels[id], state: 'unchecked', message: '首次使用前必须完成模型推理自检' })) }
+  return { state: 'unchecked', required: true, items: (['embedding', 'rerank'] as const).map(id => ({ id, label: labels[id], state: 'unchecked', message: '尚未完成模型推理自检' })) }
+}
+function readCachedReport(resourceRoot: string, fingerprint: string): EnvironmentReport | undefined {
+  try {
+    const cached = JSON.parse(readFileSync(join(resourceRoot, CHECK_FILE), 'utf8')) as Record<string, unknown>
+    if (cached.required !== true || cached.fingerprint !== fingerprint || typeof cached.checkedAt !== 'string'
+      || !Number.isFinite(Date.parse(cached.checkedAt)) || !Array.isArray(cached.items)) return undefined
+    const items: EnvironmentReport['items'] = []
+    for (const id of ['embedding', 'rerank'] as const) {
+      const item = cached.items.find((value): value is Record<string, unknown> => Boolean(value && typeof value === 'object' && (value as Record<string, unknown>).id === id))
+      if (!item || item.label !== labels[id] || typeof item.message !== 'string'
+        || !['unchecked', 'ready', 'missing', 'failed'].includes(String(item.state))) return undefined
+      items.push({ id, label: labels[id], state: item.state as EnvironmentReport['items'][number]['state'], message: item.message,
+        ...(typeof item.path === 'string' ? { path: item.path } : {}) })
+    }
+    return { state: items.every(item => item.state === 'ready') ? 'ready' : 'blocked', required: true,
+      checkedAt: cached.checkedAt, fingerprint, items }
+  } catch { return undefined }
 }
 function stamp(path: string): unknown { try { const value = statSync(path); return [value.size, value.mtimeMs] } catch { return null } }
 function sitePackagesPath(pythonPath: string): string {
@@ -52,14 +83,16 @@ export function modelFilesProblem(path: string): string | undefined {
 
 /** Preparation and readiness are shared by all bases in one deployment. */
 export class KnowledgeEnvironment {
-  private report = blankReport()
+  private report: EnvironmentReport
   private job?: EnvironmentView['job']
   private checkPending?: Promise<EnvironmentReport>
   private work?: Promise<void>
   private controller?: AbortController
   private checkController?: AbortController
   private disposed = false
-  constructor(private readonly options: EnvironmentOptions) {}
+  constructor(private readonly options: EnvironmentOptions) {
+    this.report = readCachedReport(options.resourceRoot, this.fingerprint()) ?? blankReport()
+  }
 
   private fingerprint(): string {
     const { config, paths } = this.options.snapshot()
@@ -73,24 +106,39 @@ export class KnowledgeEnvironment {
   }
 
   view(): EnvironmentView {
-    if (!this.checkPending && this.report.state === 'ready' && this.report.fingerprint !== this.fingerprint()) this.report = blankReport()
+    if (!this.checkPending && this.report.fingerprint && this.report.fingerprint !== this.fingerprint()) {
+      if (this.report.state === 'ready') this.report.state = 'unchecked'
+      this.report.items = this.report.items.map(item => item.state === 'ready' ? { ...item, state: 'unchecked', message: '自检后配置或资源发生变化，请重新自检' } : item)
+    }
+    const { config, paths } = this.options.snapshot()
     const selection = readModelSelection(this.options.resourceRoot)
-    return structuredClone({ report: this.report, selection, models: modelOptionsView(), ...(this.job ? { job: this.job } : {}) })
+    const current = {
+      embedding: currentModel(this.options.resourceRoot, paths.embeddingModel, EMBEDDING_MODELS, config.embeddingProvider === 'none', config.embeddingProvider === 'ollama' ? 'Ollama' : undefined),
+      rerank: currentModel(this.options.resourceRoot, paths.rerankModel, RERANK_MODELS, config.rerankProvider === 'none'),
+    }
+    return structuredClone({
+      report: this.report, selection, current,
+      // 「已下载 / 需下载」的判据与自检的「模型结构」那一项是同一个函数。
+      models: modelOptionsView(directory => modelFilesProblem(join(this.options.resourceRoot, 'models', directory)) === undefined),
+      ...(this.job ? { job: this.job } : {}),
+    })
   }
   invalidate(): void { if (!this.checkPending) this.report = blankReport() }
 
-  async requireReady(): Promise<void> {
+  async requireReady(kind?: EnvironmentItemId): Promise<void> {
     if (this.disposed) throw new Error('环境服务已关闭')
     if (this.job?.state === 'running') throw new Error('环境正在准备或自检，请等待完成后再编译和召回')
     const view = this.view()
-    const recent = view.report.checkedAt && Date.now() - Date.parse(view.report.checkedAt) < 5 * 60_000
-    const report = view.report.state === 'ready' && recent ? view.report : await this.check(true)
-    if (report.state !== 'ready') throw new Error(`环境未就绪：${report.items.filter(item => item.state !== 'ready').map(item => `${item.label}：${item.message}`).join('；')}。请在 Tita 设置中完成环境准备`)
+    // A passing result stays valid while the model, provider, runtime, and device fingerprint stays the same.
+    // The operation itself still reports inference failures, and the user can always request a fresh probe.
+    const alreadyReady = kind ? view.report.items.find(item => item.id === kind)?.state === 'ready' : view.report.state === 'ready'
+    const report = alreadyReady ? view.report : await this.check(true, kind)
+    if (kind ? report.items.find(item => item.id === kind)?.state !== 'ready' : report.state !== 'ready') throw new Error(`环境未就绪：${report.items.filter(item => (!kind || item.id === kind) && item.state !== 'ready').map(item => `${item.label}：${item.message}`).join('；')}。请在 Tita 设置中完成环境准备`)
   }
 
-  check(deep = true): Promise<EnvironmentReport> {
-    if (this.checkPending) return this.checkPending
-    const pending = this.performCheck(deep)
+  check(deep = true, kind?: EnvironmentItemId): Promise<EnvironmentReport> {
+    if (this.checkPending) return this.checkPending.then(report => !kind || report.items.find(item => item.id === kind)?.state === 'ready' ? report : this.check(deep, kind))
+    const pending = this.performCheck(deep, kind)
     this.checkPending = pending
     void pending.finally(() => { if (this.checkPending === pending) this.checkPending = undefined }).catch(() => undefined)
     return pending
@@ -100,23 +148,38 @@ export class KnowledgeEnvironment {
     this.report.items = this.report.items.map(item => item.id === id ? { ...item, ...patch } : item)
   }
 
-  private async performCheck(deep: boolean): Promise<EnvironmentReport> {
+  private async performCheck(deep: boolean, kind?: EnvironmentItemId): Promise<EnvironmentReport> {
     const checkController = new AbortController()
     this.checkController = checkController
     const signal = this.controller ? AbortSignal.any([this.controller.signal, checkController.signal]) : checkController.signal
     const fingerprint = this.fingerprint()
     const { config, paths } = this.options.snapshot()
-    this.report = blankReport()
+    if (this.report.fingerprint !== fingerprint) this.report = blankReport()
+    /**
+     * 解释器**结构上**装不了原生扩展时，先判失败，不白跑一次模型加载。
+     *
+     * 这一条是 2026-10-18 补的：那之前自检会照常 `import torch`，然后把 macOS 的
+     * `dlopen ... different Team IDs` 整段异常当成失败消息贴给用户 —— 一屏报文，
+     * 但真正该说的是「这个 Python 带签名保护，点修复换一个」。一次 `codesign` 就能判，
+     * 不必先加载几百 MB 的模型。
+     */
+    const interpreter = deep ? await this.interpreterProblem(paths.python) : undefined
     this.report.state = 'checking'
-    for (const id of ['embedding', 'rerank'] as const) {
+    for (const id of kind ? [kind] : ['embedding', 'rerank'] as const) {
       if (signal.aborted || this.disposed) break
       const path = id === 'embedding' ? paths.embeddingModel : paths.rerankModel
+      const cached = this.report.fingerprint === fingerprint ? this.report.items.find(item => item.id === id) : undefined
       this.item(id, { path })
       const disabled = id === 'embedding' ? config.embeddingProvider === 'none' : config.rerankProvider === 'none'
       const problem = disabled ? '此能力是必需项，请启用模型'
         : id === 'embedding' && config.embeddingProvider === 'ollama' ? undefined : modelFilesProblem(path)
       if (problem) { this.item(id, { state: 'missing', message: problem }); continue }
-      if (!deep) { this.item(id, { state: 'unchecked', message: '资源已找到，尚未完成实际推理自检' }); continue }
+      if (interpreter) { this.item(id, { state: 'failed', message: interpreter }); continue }
+      if (!deep) {
+        if (cached && cached.state !== 'unchecked' && cached.state !== 'checking') this.item(id, { state: cached.state, message: cached.message })
+        else this.item(id, { state: 'unchecked', message: '资源已找到，尚未完成实际推理自检' })
+        continue
+      }
       this.item(id, { state: 'checking', message: '加载模型并运行推理自检，首次加载可能较慢' })
       try {
         const result = await this.options.probe(id)
@@ -131,12 +194,34 @@ export class KnowledgeEnvironment {
       ? { ...item, state: 'unchecked', message: '自检已停止，请重新运行' }
       : item)
     this.report.state = this.report.items.every(item => item.state === 'ready') ? 'ready' : 'blocked'
-    this.report.checkedAt = new Date().toISOString()
+    if (deep) this.report.checkedAt = new Date().toISOString()
     this.report.fingerprint = fingerprint
     if (this.checkController === checkController) this.checkController = undefined
+    if (deep && !signal.aborted && !this.disposed) {
+      try {
+        await mkdir(this.options.resourceRoot, { recursive: true })
+        await writeFile(join(this.options.resourceRoot, CHECK_FILE), JSON.stringify(this.report, null, 2))
+      } catch { /* The current process can use the result; a later restart may need to probe again. */ }
+    }
     return structuredClone(this.report)
   }
 
+  /**
+   * 这个解释器有没有「加载不了第三方原生扩展」的结构性问题。
+   *
+   * 目前只有一种：macOS 上带 hardened runtime（`codesign` 的 flags 里有 `runtime`）——
+   * 库校验只喂它自己 Team ID 签的 dylib，而 pip 上的 torch 等轮子是 ad-hoc 签名的。
+   * 判据来自 `dsh-python.ts`，安装那条路用的是同一个函数：**自检与安装必须看同一件事**，
+   * 否则会出现「自检说没问题、装的时候换了解释器」这种两边不对账的情况。
+   */
+  private async interpreterProblem(python: string): Promise<string | undefined> {
+    if (!python) return undefined
+    const hardened = await hasHardenedRuntime(python, this.options.run ?? runProcess)
+    if (!hardened) return undefined
+    return '这个环境的 Python 带 macOS 签名保护（hardened runtime），加载不了 pip 安装的原生扩展；'
+      + '点「一键安装 / 修复」会用不带签名保护的解释器重建环境。'
+  }
+
   start(action: 'check' | 'install', requestedSelection?: unknown): EnvironmentView {
     if (this.disposed) throw new Error('环境服务已关闭')
     if (this.job?.state === 'running') return this.view()
@@ -151,6 +236,7 @@ export class KnowledgeEnvironment {
     const job = this.job
     const log = (line: string): void => { job.logs = [...job.logs, line.slice(-1500)].slice(-12) }
     const work = async (): Promise<void> => {
+      let rollbackSettings: (() => Promise<void>) | undefined
       try {
         // A first-use guard can already be checking. Do not install into that probe.
         if (this.checkPending) await this.checkPending
@@ -164,16 +250,18 @@ export class KnowledgeEnvironment {
             const id = label.includes('向量') ? 'embedding' : label.includes('重排') ? 'rerank' : undefined
             if (id) this.item(id, { state: 'checking', message: label })
           }, log, this.options.run ?? runProcess, selection)
+          rollbackSettings = await this.options.activateSelection?.()
           this.options.reload()
         } else this.options.reload()
         job.stage = '运行实际推理自检'
         const report = await this.check(true)
         if (controller.signal.aborted) throw new Error('ENVIRONMENT_CANCELLED')
         if (report.state !== 'ready') throw new Error(report.items.filter(item => item.state !== 'ready').map(item => `${item.label}：${item.message}`).join('；'))
-        await mkdir(this.options.resourceRoot, { recursive: true })
-        await writeFile(join(this.options.resourceRoot, 'environment-last-check.json'), JSON.stringify(report, null, 2))
         job.state = 'succeeded'; job.stage = '环境已就绪'
       } catch (cause) {
+        if (rollbackSettings) {
+          try { await rollbackSettings() } catch (rollbackCause) { log(`恢复模型设置失败：${rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause)}`) }
+        }
         if (action === 'install') {
           const activeSelection = readModelSelection(this.options.resourceRoot)
           if (activeSelection.embedding !== previousSelection.embedding || activeSelection.rerank !== previousSelection.rerank) {

package/src/environment/types.ts

@@ -17,6 +17,11 @@ export interface EnvironmentReport {
   fingerprint?: string
   items: EnvironmentItem[]
 }
+export interface EnvironmentCurrentModel {
+  id?: string
+  label: string
+  state: 'active' | 'disabled'
+}
 export interface EnvironmentJob {
   id: string
   state: 'running' | 'succeeded' | 'failed' | 'cancelled'
@@ -30,5 +35,6 @@ export interface EnvironmentView {
   report: EnvironmentReport
   job?: EnvironmentJob
   selection: ModelSelection
+  current: { embedding: EnvironmentCurrentModel; rerank: EnvironmentCurrentModel }
   models: { embedding: ModelOptionView[]; rerank: ModelOptionView[] }
 }

package/src/events.ts

@@ -46,6 +46,18 @@ export interface EventEntity {
   updatedAt: string
 }
 
+/** Remove the legacy generated Event list from a WikiCard body. References live in card_event. */
+export function stripEventReferenceSection(content: string): string {
+  const lines = content.split('\n')
+  for (let start = lines.length - 1; start >= 0; start -= 1) {
+    if (!/^##\s+关联\s*Events?\s*$|^##\s+关联事件\s*$/.test((lines[start] ?? '').trim())) continue
+    let end = start + 1
+    while (end < lines.length && !/^#{1,2}\s+/.test(lines[end] ?? '')) end += 1
+    lines.splice(start, end - start)
+  }
+  return lines.join('\n').trim()
+}
+
 export function compositeEventIdentity(occurredAt: string | null, coordinate: CardCoordinate, symptom: string | null): string {
   const payload = [occurredAt, coordinate.objectId, coordinate.actionId, coordinate.sceneId, normalizeKnowledge(symptom ?? '')]
   return 'composite:' + createHash('sha256').update(JSON.stringify(payload)).digest('hex').slice(0, 24)

package/src/extract-contract.ts

@@ -13,6 +13,7 @@
  */
 
 import { AXIS_CONTRACT_LINES } from './axis-contract.js'
+import { TABLE_OUTPUT_CONTRACT } from './extract-table-contract.js'
 
 /**
  * 把骨架允许的小节拼成提示词里那一条。
@@ -37,14 +38,15 @@ function sectionRule(sections: string[] | undefined): string[] {
  * 编译链路用 `buildTrialSystem(profileSections)`；试跑面板用默认实例（不下发小节清单），
  * 因为那一层没有「本库骨架」这个概念。
  */
-export function buildTrialSystem(sections?: string[]): string {
-  return trialSystemBody(sectionRule(sections))
+export function buildTrialSystem(sections?: string[], format: 'table' | 'json' = 'table'): string {
+  return trialSystemBody(sectionRule(sections), format)
 }
 
-const trialSystemBody = (positionRule: string[]): string => [
+const trialSystemBody = (positionRule: string[], format: 'table' | 'json'): string => [
   '你在把一份业务文档拆成知识库要用的内容。知识以 Knowledge 为单位：',
   '一条可独立检索、验证或执行的最小知识单元。',
   '',
+  ...(format === 'table' ? TABLE_OUTPUT_CONTRACT : [
   '只回一个 JSON 对象，不要散文，不要代码围栏。',
   '',
   '输出形状：',
@@ -73,6 +75,7 @@ const trialSystemBody = (positionRule: string[]): string => [
   '  "dropped": [ { "quote": "原文片段", "why": "为什么丢掉" } ]',
   '}',
   '',
+  ]),
   '# 知识：一条只讲一个单元',
   '- text 是一条能脱离上下文独立阅读的最小知识单元。事实要能判断真假，操作步骤要能被执行。',
   '- 一段原文里有几个独立单元就写几条。不要压成一条，也不要拆碎。',

package/src/extract-model.ts

@@ -65,6 +65,8 @@ export type ModelCall = (request: {
   sessionId?: string
   /** 可选观察本次请求的 provider 用量；普通调用方可以忽略。 */
   onUsage?: (usage: TrialTokenUsage) => void
+  /** Public response text only; reasoning chunks are not exposed. */
+  onDelta?: (text: string) => void
 }) => Promise<string>
 
 /** 归并条目：与规则抽取的 `NormalizedCandidates['merges']` 保持同一形状。 */

package/src/extract-table-contract.ts

@@ -0,0 +1,29 @@
+/** Kept free of server dependencies so the architecture page shows the real contract. */
+export const TABLE_OUTPUT_CONTRACT = [
+  '只返回 TOON 固定列表格，不要 Markdown 围栏或说明。format 必须是 knowledge-table-v1。',
+  '每个数组头的 [N] 是本次实际行数；每行必须与 {列名} 的列数和顺序一致。空表写 名称[0]:。',
+  '逗号分列。字符串包含逗号、冒号、换行或首尾空格时用双引号包裹；内部双引号写 \\"，换行写 \\n，反斜杠写 \\\\。',
+  '缺失值写 null。字符串列表 heading_path 和 missing 写为 JSON 数组字符串。',
+  'evidence 表每个引文只写一次。其它表的 evidence 列写出处 ID，多个 ID 用空格分隔。所有 ID 必须存在。',
+  '以下是列定义和示例；示例内容必须换成当前文档的数据：',
+  'format: knowledge-table-v1',
+  'subject: 业务主体',
+  'knowledge[1]{id,text,object,action,scene,section,order,evidence}:',
+  '  k1,一条最小知识单元,对象名,动作名,场景名,字段,1,q1',
+  'events[1]{id,external_id,title,summary,object,action,scene,occurred_at,symptom,root_cause,root_cause_status,outcome,missing,evidence}:',
+  '  e1,null,一次具体发生,原文明确的概述,对象名,动作名,场景名,null,null,null,null,null,"[]",q1',
+  'timeline[1]{event_id,order,type,description,result,at,evidence}:',
+  '  e1,1,observation,原文记录的现象,null,null,q1',
+  'objects[1]{mention,definition,evidence,existing,parent}:',
+  '  对象名,对象的边界和含义,q1,null,null',
+  'actions[1]{mention,definition,evidence,existing,parent}:',
+  '  动作名,动作的含义,q1,null,null',
+  'scenes[1]{mention,definition,evidence,existing,parent}:',
+  '  场景名,场景的含义,q1,null,null',
+  'evidence[1]{id,quote,heading_path}:',
+  '  q1,原文逐字引文,"[]"',
+  'dropped[0]:',
+  'timeline.type 只能是 observation/check/action/result/conclusion；root_cause_status 只能是 confirmed/suspected/null。',
+  'dropped 非空时列为 {quote,why}。对象 parent 只填原文有证据的父对象；existing 填已有实体名。',
+  '',
+]