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

package/src/environment/install.ts

@@ -0,0 +1,129 @@
+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 { 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'
+
+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') }
+
+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 }) }
+}
+
+async function installLock(root: string): Promise<() => Promise<void>> {
+  const path = join(root, 'environment-install.lock')
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const file = await open(path, 'wx')
+      try { await file.writeFile(JSON.stringify({ 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 })
+    } 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
+        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> {
+  await mkdir(root, { recursive: true })
+  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 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`)
+    }
+    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
+      } 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', '--python', basePython, '--python-preference', 'only-system', join(root, 'python')])
+    }
+    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 = 2

package/src/environment/model-catalog.ts

@@ -0,0 +1,105 @@
+/** Models supported by the local embedding and reranking workers. Revisions are pinned in manifest.ts. */
+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
+}
+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)!
+}
+
+export function modelOptionsView() {
+  const present = <T extends { id: string; label: string; download: string; description: string; repo: string }>(model: T) => ({
+    id: model.id, label: model.label, download: model.download, description: model.description,
+    modelCardUrl: `https://huggingface.co/${model.repo}`,
+    ...('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)
+}

package/src/environment/service.ts

@@ -0,0 +1,211 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { readdirSync, statSync } from 'node:fs'
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname, isAbsolute, join } from 'node:path'
+import { embeddingFingerprint } from '../compiler/embedding-identity.js'
+import type { RuntimeKnowledgeConfig } from '../types.js'
+import { installRequiredEnvironment, requirementsFile } from './install.js'
+import { modelOptionsView, parseModelSelection, 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'
+
+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
+  run?: typeof runProcess
+  install?: typeof installRequiredEnvironment
+}
+
+const labels = { embedding: '向量模型', rerank: '重排模型' }
+function blankReport(): EnvironmentReport {
+  return { state: 'unchecked', required: true, items: (['embedding', 'rerank'] as const).map(id => ({ id, label: labels[id], state: 'unchecked', message: '首次使用前必须完成模型推理自检' })) }
+}
+function stamp(path: string): unknown { try { const value = statSync(path); return [value.size, value.mtimeMs] } catch { return null } }
+function sitePackagesPath(pythonPath: string): string {
+  const environmentRoot = dirname(dirname(pythonPath))
+  const windows = join(environmentRoot, 'Lib', 'site-packages')
+  try { if (statSync(windows).isDirectory()) return windows } catch { /* use the platform-neutral lib layout */ }
+  const libraryRoot = join(environmentRoot, 'lib')
+  try {
+    const versionDirectory = readdirSync(libraryRoot).find(name => /^python\d+\.\d+$/.test(name))
+    if (versionDirectory) return join(libraryRoot, versionDirectory, 'site-packages')
+  } catch { /* no venv/site-packages directory */ }
+  return join(libraryRoot, 'site-packages')
+}
+
+export function modelFilesProblem(path: string): string | undefined {
+  if (!isAbsolute(path)) return '尚未准备本地模型，请安装默认资源或填写已下载模型的完整路径'
+  try {
+    const files = readdirSync(path)
+    if (!files.includes('config.json')) return '模型缺少 config.json'
+    const weights = files.filter(name => /\.(safetensors|bin)$/.test(name))
+    if (!weights.length || weights.some(name => statSync(join(path, name)).size < 1024)) return '模型权重缺失或下载不完整'
+    const tokenizer = ['tokenizer.json', 'sentencepiece.bpe.model', 'vocab.txt'].some(name => files.includes(name) && statSync(join(path, name)).size >= 1024)
+    if (!tokenizer) return '模型缺少完整分词器词表'
+  } catch { return '模型目录不存在或无法读取' }
+  return undefined
+}
+
+/** Preparation and readiness are shared by all bases in one deployment. */
+export class KnowledgeEnvironment {
+  private report = blankReport()
+  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) {}
+
+  private fingerprint(): string {
+    const { config, paths } = this.options.snapshot()
+    const env = dirname(dirname(paths.python))
+    return createHash('sha256').update(JSON.stringify({
+      probe: ENVIRONMENT_PROBE_VERSION, paths,
+      provider: config.embeddingProvider, rerank: config.rerankProvider, device: config.embeddingDevice, dimension: config.embeddingDimension, endpoint: config.embeddingBaseUrl,
+      embedding: embeddingFingerprint(paths.embeddingModel, this.options.resourceRoot), rerankModel: embeddingFingerprint(paths.rerankModel, this.options.resourceRoot),
+      python: stamp(paths.python), venv: stamp(join(env, 'pyvenv.cfg')), dependencies: stamp(sitePackagesPath(paths.python)), requirements: stamp(requirementsFile),
+    })).digest('hex')
+  }
+
+  view(): EnvironmentView {
+    if (!this.checkPending && this.report.state === 'ready' && this.report.fingerprint !== this.fingerprint()) this.report = blankReport()
+    const selection = readModelSelection(this.options.resourceRoot)
+    return structuredClone({ report: this.report, selection, models: modelOptionsView(), ...(this.job ? { job: this.job } : {}) })
+  }
+  invalidate(): void { if (!this.checkPending) this.report = blankReport() }
+
+  async requireReady(): 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 设置中完成环境准备`)
+  }
+
+  check(deep = true): Promise<EnvironmentReport> {
+    if (this.checkPending) return this.checkPending
+    const pending = this.performCheck(deep)
+    this.checkPending = pending
+    void pending.finally(() => { if (this.checkPending === pending) this.checkPending = undefined }).catch(() => undefined)
+    return pending
+  }
+
+  private item(id: EnvironmentItemId, patch: Partial<EnvironmentItem>): void {
+    this.report.items = this.report.items.map(item => item.id === id ? { ...item, ...patch } : item)
+  }
+
+  private async performCheck(deep: boolean): 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()
+    this.report.state = 'checking'
+    for (const id of ['embedding', 'rerank'] as const) {
+      if (signal.aborted || this.disposed) break
+      const path = id === 'embedding' ? paths.embeddingModel : paths.rerankModel
+      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 }
+      this.item(id, { state: 'checking', message: '加载模型并运行推理自检，首次加载可能较慢' })
+      try {
+        const result = await this.options.probe(id)
+        this.item(id, { state: result.ok ? 'ready' : 'failed', message: result.message })
+      } catch (cause) { this.item(id, { state: 'failed', message: cause instanceof Error ? cause.message : String(cause) }) }
+    }
+    const changed = fingerprint !== this.fingerprint()
+    if (changed) this.report.items = this.report.items.map(item => item.state === 'ready'
+      ? { ...item, state: 'unchecked', message: '自检期间配置或资源发生变化，请重新自检' }
+      : item)
+    if (signal.aborted || this.disposed) this.report.items = this.report.items.map(item => item.state === 'checking'
+      ? { ...item, state: 'unchecked', message: '自检已停止，请重新运行' }
+      : item)
+    this.report.state = this.report.items.every(item => item.state === 'ready') ? 'ready' : 'blocked'
+    this.report.checkedAt = new Date().toISOString()
+    this.report.fingerprint = fingerprint
+    if (this.checkController === checkController) this.checkController = undefined
+    return structuredClone(this.report)
+  }
+
+  start(action: 'check' | 'install', requestedSelection?: unknown): EnvironmentView {
+    if (this.disposed) throw new Error('环境服务已关闭')
+    if (this.job?.state === 'running') return this.view()
+    const previousSelection = readModelSelection(this.options.resourceRoot)
+    const selection: ModelSelection = action === 'install'
+      ? parseModelSelection(requestedSelection, previousSelection)
+      : previousSelection
+    this.checkController?.abort()
+    this.controller = new AbortController()
+    const controller = this.controller
+    this.job = { id: randomUUID(), state: 'running', stage: action === 'install' ? '准备安装' : '环境自检', startedAt: new Date().toISOString(), logs: [] }
+    const job = this.job
+    const log = (line: string): void => { job.logs = [...job.logs, line.slice(-1500)].slice(-12) }
+    const work = async (): Promise<void> => {
+      try {
+        // A first-use guard can already be checking. Do not install into that probe.
+        if (this.checkPending) await this.checkPending
+        if (controller.signal.aborted) throw new Error('ENVIRONMENT_CANCELLED')
+        if (action === 'install') {
+          this.report = blankReport()
+          this.report.state = 'checking'
+          await (this.options.install ?? installRequiredEnvironment)(this.options.resourceRoot, controller.signal, label => {
+            job.stage = label
+            for (const item of this.report.items) if (item.state === 'checking') this.item(item.id, { state: 'unchecked', message: '准备步骤已完成，等待实际自检' })
+            const id = label.includes('向量') ? 'embedding' : label.includes('重排') ? 'rerank' : undefined
+            if (id) this.item(id, { state: 'checking', message: label })
+          }, log, this.options.run ?? runProcess, selection)
+          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 (action === 'install') {
+          const activeSelection = readModelSelection(this.options.resourceRoot)
+          if (activeSelection.embedding !== previousSelection.embedding || activeSelection.rerank !== previousSelection.rerank) {
+            try {
+              await writeModelSelection(this.options.resourceRoot, previousSelection)
+              this.options.reload()
+              this.report = blankReport()
+              log('所选模型未通过自检，已恢复此前启用的模型')
+            } catch (rollbackCause) {
+              log(`恢复此前模型选择失败：${rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause)}`)
+            }
+          }
+        }
+        job.state = controller.signal.aborted ? 'cancelled' : 'failed'
+        job.error = controller.signal.aborted ? '已停止，已下载的资源可在下次重试时复用' : cause instanceof Error ? cause.message : String(cause)
+        job.stage = controller.signal.aborted ? '已停止' : '准备未完成'
+        if (this.report.state !== 'ready') {
+          this.report.state = 'blocked'
+          for (const item of this.report.items) if (item.state === 'checking') this.item(item.id, { state: controller.signal.aborted ? 'unchecked' : 'failed', message: job.error })
+        }
+      } finally {
+        job.finishedAt = new Date().toISOString()
+        if (this.controller === controller) this.controller = undefined
+      }
+    }
+    this.work = Promise.resolve().then(work)
+    return this.view()
+  }
+  async wait(): Promise<void> { await this.work }
+  cancel(): void {
+    this.controller?.abort(); this.checkController?.abort()
+    if (this.job?.state === 'running') this.job.stage = '正在停止，请等待当前步骤结束'
+  }
+  close(): void { this.disposed = true; this.cancel() }
+}

package/src/environment/types.ts

@@ -0,0 +1,34 @@
+/** Installation state is deployment-wide; it is not knowledge or a build artifact. */
+import type { ModelOptionView, ModelSelection } from './model-catalog.js'
+
+export type EnvironmentItemId = 'embedding' | 'rerank'
+export type EnvironmentItemState = 'unchecked' | 'checking' | 'ready' | 'missing' | 'failed'
+export interface EnvironmentItem {
+  id: EnvironmentItemId
+  label: string
+  state: EnvironmentItemState
+  message: string
+  path?: string
+}
+export interface EnvironmentReport {
+  state: 'unchecked' | 'checking' | 'blocked' | 'ready'
+  required: true
+  checkedAt?: string
+  fingerprint?: string
+  items: EnvironmentItem[]
+}
+export interface EnvironmentJob {
+  id: string
+  state: 'running' | 'succeeded' | 'failed' | 'cancelled'
+  stage: string
+  startedAt: string
+  finishedAt?: string
+  error?: string
+  logs: string[]
+}
+export interface EnvironmentView {
+  report: EnvironmentReport
+  job?: EnvironmentJob
+  selection: ModelSelection
+  models: { embedding: ModelOptionView[]; rerank: ModelOptionView[] }
+}

package/src/events.ts

@@ -1,3 +1,5 @@
+import { createHash } from 'node:crypto'
+import { normalizeKnowledge } from './knowledge.js'
 import type { CardCoordinate } from './types.js'
 import type { TrialEvent, TrialSource } from './wiki-trial-types.js'
 
@@ -43,3 +45,47 @@ export interface EventEntity {
   createdAt: string
   updatedAt: string
 }
+
+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)
+}
+
+/** Recompute the aggregate after records are appended, pruned or redirected. */
+export function eventEntityFromRecords(input: {
+  id: string
+  identityKey: string
+  identityType: EventEntity['identityType']
+  records: EventSourceRecord[]
+  createdAt: string
+  updatedAt?: string
+}): EventEntity {
+  const { id, identityKey, identityType, records } = input
+  const first = records[0]
+  const firstCoordinate = records.find(record => record.coordinateIds.objectId || record.coordinateIds.actionId || record.coordinateIds.sceneId)
+  const sources = new Map<string, TrialSource>()
+  for (const record of records) {
+    for (const source of record.sources) sources.set(`${source.documentId}\u0001${source.quote}`, source)
+  }
+  return {
+    id, identityKey, identityType,
+    externalId: records.find(record => record.externalId)?.externalId ?? null,
+    title: first?.title ?? id,
+    summary: records.find(record => record.summary.trim())?.summary ?? first?.title ?? id,
+    coordinate: {
+      object: records.find(record => record.coordinate.object)?.coordinate.object ?? null,
+      action: records.find(record => record.coordinate.action)?.coordinate.action ?? null,
+      scene: records.find(record => record.coordinate.scene)?.coordinate.scene ?? null,
+    },
+    coordinateIds: firstCoordinate?.coordinateIds ?? { objectId: '', actionId: '', sceneId: '' },
+    occurredAt: records.find(record => record.occurredAt)?.occurredAt ?? null,
+    symptom: records.find(record => record.symptom)?.symptom ?? null,
+    timeline: records.flatMap(record => record.timeline.map(step => ({ ...step, sourceId: record.sourceId }))),
+    rootCauses: records.flatMap(record => record.rootCause ? [{ text: record.rootCause, status: record.rootCauseStatus, sourceId: record.sourceId }] : []),
+    outcomes: records.flatMap(record => record.outcome ? [{ text: record.outcome, sourceId: record.sourceId }] : []),
+    missing: [...new Set(records.flatMap(record => record.missing))],
+    sources: [...sources.values()], records,
+    createdAt: input.createdAt,
+    updatedAt: input.updatedAt ?? new Date().toISOString(),
+  }
+}