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

package/scripts/environment.mjs

@@ -0,0 +1,29 @@
+import { KnowledgeEnvironment } from '../lib/types/environment/service.js'
+import { KnowledgeRuntime, defaultKnowledgeRoot } from '../lib/types/runtime.js'
+import { defaultAgentRoot, resourceRoot } from '../lib/types/layout.js'
+
+const runtime = new KnowledgeRuntime(defaultKnowledgeRoot(), {}, { resourceRoot: resourceRoot(defaultAgentRoot()) })
+const environment = new KnowledgeEnvironment({ resourceRoot: resourceRoot(defaultAgentRoot()),
+  snapshot: () => ({ config: runtime.config, paths: runtime.resourcePaths() }),
+  probe: kind => runtime.environmentProbe(kind), reload: () => runtime.reloadResources(),
+})
+const stop = () => environment.cancel()
+process.once('SIGINT', stop)
+process.once('SIGTERM', stop)
+const action = process.argv.includes('--install') ? 'install' : 'check'
+environment.start(action)
+let last = ''
+const timer = setInterval(() => {
+  const view = environment.view()
+  const line = `${view.job?.stage ?? ''}: ${view.job?.logs.at(-1) ?? ''}`
+  if (line !== last) { process.stderr.write(`${line}\n`); last = line }
+}, 1000)
+try {
+  await environment.wait()
+  const view = environment.view()
+  console.log(JSON.stringify(view, null, 2))
+  if (view.job?.state !== 'succeeded') process.exitCode = 1
+} finally {
+  clearInterval(timer); environment.close(); runtime.close()
+  process.removeListener('SIGINT', stop); process.removeListener('SIGTERM', stop)
+}

package/scripts/setup-embedding.sh

@@ -9,11 +9,20 @@ DSH_HOME_ROOT="${DSH_HOME:-$HOME/.dsh}"
 TITA_HOME="$DSH_HOME_ROOT/tita-agent"
 VENV="${DSH_EMBEDDING_VENV:-$TITA_HOME/resource/python}"
 MODEL_DIR="${DSH_EMBEDDING_MODEL_PATH:-$TITA_HOME/resource/models/WeMM-Embedding-2B-Quantized}"
+BASE_PYTHON="${DSH_PYTHON:-python3}"
 PYTHON_BIN="$VENV/bin/python"
 
 mkdir -p "$TITA_HOME" "$MODEL_DIR"
-if [ ! -x "$PYTHON_BIN" ]; then
-  uv venv --python 3.11 "$VENV"
+BASE_VERSION="$("$BASE_PYTHON" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")')"
+if [[ ! "$BASE_VERSION" =~ ^3\.(10|11|12|13)$ ]]; then
+  echo "Unsupported base Python version: $BASE_VERSION (need 3.10–3.13)" >&2
+  exit 1
+fi
+if [ ! -x "$PYTHON_BIN" ] || [ "$("$PYTHON_BIN" -c 'import sys; print(f"{sys.version_info.major}.{sys.version_info.minor}")' 2>/dev/null || true)" != "$BASE_VERSION" ]; then
+  if [ -d "$VENV" ]; then
+    mv "$VENV" "$VENV-backup-$(date +%Y%m%d%H%M%S)-$$"
+  fi
+  uv venv --python "$BASE_PYTHON" --python-preference only-system "$VENV"
 fi
 uv pip install --python "$PYTHON_BIN" -r "$ROOT/python/requirements.txt"
 

package/src/axis-registry.ts

@@ -34,14 +34,13 @@
  * ## 为什么存在记忆段
  *
  * 注册表**不可重建**：它是人确认过的命名决定（改 canonical name、并两个实体、加一个别名），
- * 重跑一次抽取不会得到同样的结果。所以它和操作日志、抽取轨迹一样落在
- * `<memoryDir>/knowledge.sqlite`，不在 `03_compiled/`。
+ * 重跑一次抽取不会得到同样的结果。所以它与 Knowledge 共享 `knowledge.db`，
+ * 经过同一个属主与 schema 版本入口校验。
  */
 
 import { createHash } from 'node:crypto'
-import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
 import { loadSqlite, type SqliteDatabase } from './fts.js'
+import { KnowledgeDb } from './store/knowledge-db.js'
 
 /** 三个轴。三者地位相同（§3.1）—— 没有哪个更特殊。 */
 export type AxisKind = 'object' | 'action' | 'scene'
@@ -252,20 +251,27 @@ CREATE INDEX IF NOT EXISTS idx_axis_relation_to ON axis_relations(to_id, relatio
  */
 export class AxisRegistry {
   private db: SqliteDatabase | null = null
+  private owner: KnowledgeDb | null = null
 
-  constructor(private readonly file: string) {}
+  constructor(private readonly file: string, private readonly shared?: SqliteDatabase) {}
 
   async open(): Promise<boolean> {
     if (this.db !== null) return true
     const sqlite = await loadSqlite()
     if (sqlite === null) return false
     try {
-      await mkdir(dirname(this.file), { recursive: true })
-      this.db = new sqlite.DatabaseSync(this.file)
+      if (this.shared) this.db = this.shared
+      else {
+        const opened = await KnowledgeDb.open(this.file, sqlite.DatabaseSync)
+        if (!opened.ok) return false
+        this.owner = opened.db
+        this.db = opened.db.connection()
+      }
       this.db.exec(SCHEMA)
+      this.db.exec('CREATE TABLE IF NOT EXISTS axis_input_revision (id INTEGER PRIMARY KEY CHECK(id = 1), revision INTEGER NOT NULL); INSERT OR IGNORE INTO axis_input_revision VALUES (1, 0)')
       /*
-       * 补列。这个库**没有 `user_version` 那一套**（它是记忆段里的一张注册表，不是知识本体），
-       * 所以判据落在列上：缺就补，补齐之后什么都不做。`CREATE TABLE IF NOT EXISTS` 对
+       * 主库已通过 `user_version` 校验，再幂等补齐存量注册表的扩展列。缺就补。
+       * `CREATE TABLE IF NOT EXISTS` 对
        * 已经存在的表一个字都不改 —— 少了这一段，0068 之前建的库会永远没有这两列，
        * 而症状是「定义存进去了，下次打开又没了」。
        */
@@ -277,11 +283,19 @@ export class AxisRegistry {
       }
       return true
     } catch {
+      this.owner?.close()
+      this.owner = null
       this.db = null
       return false
     }
   }
 
+  inputRevision(): number {
+    return Number((this.db?.prepare('SELECT revision FROM axis_input_revision WHERE id = 1').get() as { revision?: number } | undefined)?.revision ?? 0)
+  }
+
+  private changedInput(): void { this.db?.prepare('UPDATE axis_input_revision SET revision = revision + 1 WHERE id = 1').run() }
+
   available(): boolean {
     return this.db !== null
   }
@@ -343,7 +357,7 @@ export class AxisRegistry {
 
     // 2 · 作用域内 alias
     if (parentId) {
-      const aliased = this.findAlias(normalized, parentId)
+      const aliased = this.findAlias(input.kind, normalized, parentId)
       if (aliased) {
         this.learn(aliased, mention, normalized, parentId, input.description)
         return { mention, normalized, outcome: 'matched', entity: aliased, how: 'scoped-alias' }
@@ -557,6 +571,7 @@ export class AxisRegistry {
     const now = new Date().toISOString()
     this.db.prepare('UPDATE axis_entities SET name = ?, updated_at = ? WHERE id = ?').run(next, now, id)
     this.insertAlias(id, current.name, normalizeAxisName(current.name), current.scopeId, now)
+    this.changedInput()
     return this.get(id)
   }
 
@@ -572,6 +587,7 @@ export class AxisRegistry {
     const normalized = normalizeAxisName(alias)
     if (!normalized) return false
     this.insertAlias(id, alias.trim(), normalized, scopeId.trim(), new Date().toISOString())
+    this.changedInput()
     return true
   }
 
@@ -583,6 +599,7 @@ export class AxisRegistry {
   async setStatus(id: string, status: AxisStatus): Promise<AxisEntity | null> {
     if (this.db === null) throw new Error('AXIS_REGISTRY_UNAVAILABLE')
     this.db.prepare('UPDATE axis_entities SET status = ?, updated_at = ? WHERE id = ?').run(status, new Date().toISOString(), id)
+    this.changedInput()
     return this.get(id)
   }
 
@@ -593,19 +610,34 @@ export class AxisRegistry {
    * 它转成 `merged`，`scopeId` 改存目标 id —— 复用这一列而不是新加一列，因为
    * 「它现在归谁」与「它在谁的下面」对解析来说问的是同一件事。
    */
-  async merge(fromId: string, intoId: string): Promise<boolean> {
+  async merge(fromId: string, intoId: string, redirect?: (kind: AxisKind) => void): Promise<boolean> {
     if (this.db === null) throw new Error('AXIS_REGISTRY_UNAVAILABLE')
     if (fromId === intoId) return false
     const [from, into] = [await this.get(fromId), await this.get(intoId)]
-    if (from === null || into === null || from.kind !== into.kind) return false
+    if (from === null || into === null || from.kind !== into.kind || from.status === 'merged' || into.status === 'merged') return false
     const now = new Date().toISOString()
-    this.db.prepare('UPDATE axis_entities SET status = ?, scope_id = ?, updated_at = ? WHERE id = ?').run('merged', intoId, now, fromId)
-    // 被并者的别名与名字一起搬过去：按旧名、旧别名都要搜得到。
-    this.insertAlias(intoId, from.name, normalizeAxisName(from.name), into.scopeId, now)
-    const aliases = this.db.prepare('SELECT alias, scope_id FROM axis_aliases WHERE entity_id = ?').all(fromId) as Array<Record<string, unknown>>
-    for (const row of aliases) this.insertAlias(intoId, String(row.alias), normalizeAxisName(String(row.alias)), String(row.scope_id ?? ''), now)
-    this.redirectRelations(fromId, intoId, now)
-    return true
+    this.db.exec('SAVEPOINT axis_merge')
+    try {
+      this.db.prepare('UPDATE axis_entities SET status = ?, scope_id = ?, updated_at = ? WHERE id = ?').run('merged', intoId, now, fromId)
+      // 被并者的别名与名字一起搬过去：按旧名、旧别名都要搜得到。
+      this.insertAlias(intoId, from.name, normalizeAxisName(from.name), into.scopeId, now)
+      const aliases = this.db.prepare('SELECT alias, scope_id FROM axis_aliases WHERE entity_id = ?').all(fromId) as Array<Record<string, unknown>>
+      for (const row of aliases) this.insertAlias(intoId, String(row.alias), normalizeAxisName(String(row.alias)), String(row.scope_id ?? ''), now)
+      this.redirectRelations(fromId, intoId, now)
+      redirect?.(from.kind)
+      // Scope references on both canonical names and aliases move together.
+      this.db.prepare("UPDATE axis_entities SET scope_id = ? WHERE scope_id = ? AND status <> 'merged'").run(intoId, fromId)
+      this.db.prepare(`INSERT OR IGNORE INTO axis_aliases (entity_id, alias, normalized, scope_id, created_at)
+        SELECT entity_id, alias, normalized, ?, created_at FROM axis_aliases WHERE scope_id = ?`).run(intoId, fromId)
+      this.db.prepare('DELETE FROM axis_aliases WHERE scope_id = ?').run(fromId)
+      this.db.prepare('UPDATE entity_guidance SET entity_id = ? WHERE entity_id = ?').run(intoId, fromId)
+      this.changedInput()
+      this.db.exec('RELEASE axis_merge')
+      return true
+    } catch (cause) {
+      this.db.exec('ROLLBACK TO axis_merge; RELEASE axis_merge')
+      throw cause
+    }
   }
 
   /** 合并轴实体时转移相关关系，并折叠重复边与自环。 */
@@ -642,6 +674,7 @@ export class AxisRegistry {
     const next = text.trim()
     this.db.prepare('UPDATE axis_entities SET description = ?, description_source = ?, updated_at = ? WHERE id = ?')
       .run(next, next ? 'human' : '', new Date().toISOString(), id)
+    this.changedInput()
     return this.get(id)
   }
 
@@ -732,6 +765,7 @@ export class AxisRegistry {
     }
     this.db.prepare('INSERT INTO entity_guidance (id, entity_id, kind, text, author, created_at) VALUES (?, ?, ?, ?, ?, ?)')
       .run(guidance.id, guidance.entityId, guidance.kind, guidance.text, guidance.author, guidance.createdAt)
+    this.changedInput()
     return guidance
   }
 
@@ -741,6 +775,7 @@ export class AxisRegistry {
     const before = this.db.prepare('SELECT id FROM entity_guidance WHERE id = ?').get(id) as { id?: unknown } | undefined
     if (before === undefined) return false
     this.db.prepare('DELETE FROM entity_guidance WHERE id = ?').run(id)
+    this.changedInput()
     return true
   }
 
@@ -829,7 +864,8 @@ export class AxisRegistry {
   }
 
   close(): void {
-    this.db?.close()
+    this.owner?.close()
+    this.owner = null
     this.db = null
   }
 
@@ -843,10 +879,10 @@ export class AxisRegistry {
     return hit === undefined ? undefined : rowToEntity(hit)
   }
 
-  private findAlias(normalized: string, scopeId: string): AxisEntity | undefined {
+  private findAlias(kind: AxisKind, normalized: string, scopeId: string): AxisEntity | undefined {
     const row = this.db!.prepare(
-      "SELECT e.* FROM axis_aliases a JOIN axis_entities e ON e.id = a.entity_id WHERE a.normalized = ? AND a.scope_id = ? AND e.status <> 'merged' LIMIT 1",
-    ).get(normalized, scopeId) as Record<string, unknown> | undefined
+      "SELECT e.* FROM axis_aliases a JOIN axis_entities e ON e.id = a.entity_id WHERE a.normalized = ? AND a.scope_id = ? AND e.kind = ? AND e.status <> 'merged' LIMIT 1",
+    ).get(normalized, scopeId, kind) as Record<string, unknown> | undefined
     return row === undefined ? undefined : rowToEntity(row)
   }
 

package/src/card-organize.ts

@@ -428,6 +428,8 @@ export function checkOrganize(
   plan: OrganizePlan,
   known: string[],
   options: {
+    /** Check literal changes; this does not prove semantic entailment. */
+    knowledge?: Array<{ id: string; text: string }>
     /**
      * 正文里**可以**指向的其他卡片（`buildOrganizePrompt` 下发的那一份）。
      *
@@ -442,11 +444,24 @@ export function checkOrganize(
   const knownSet = new Set(known)
   const cited: string[] = []
   const seen = new Set<string>()
+  const byId = new Map(options.knowledge?.map(item => [item.id, item.text]) ?? [])
+  const literals = (text: string): string[] => [...text.replace(/\[\^[^\]]+\]/g, '').matchAll(/(?<![A-Za-z0-9_])(?:[<>≤≥]=?\s*)?[+-]?\d+(?:\.\d+)?(?:%|％)?/g)].map(match => match[0].replace(/\s/g, '').replace('％', '%'))
+  if (options.knowledge) {
+    const supported = new Set(literals(citationsIn(plan.summary).map(id => byId.get(id) ?? '').join('\n')))
+    const unsupported = literals(plan.summary).filter(value => !supported.has(value))
+    if (unsupported.length > 0) problems.push({ code: 'ORGANIZE_UNSUPPORTED_LITERAL', message: `概述的数值或比较条件没有引用依据：${[...new Set(unsupported)].join('、')}` })
+  }
 
   // 1 + 2：正文里的引用必须都存在，且每条知识都要落地。
   for (const section of plan.sections) {
     for (const block of section.blocks) {
       for (const text of blockTexts(block)) {
+        if (options.knowledge) {
+          const citedText = citationsIn(text).map(id => byId.get(id) ?? '').join('\n')
+          const supported = new Set(literals(citedText))
+          const unsupported = literals(text).filter(value => !supported.has(value))
+          if (unsupported.length > 0) problems.push({ code: 'ORGANIZE_UNSUPPORTED_LITERAL', message: `小节「${section.title}」的数值或比较条件没有引用依据：${[...new Set(unsupported)].join('、')}` })
+        }
         for (const id of citationsIn(text)) {
           if (!knownSet.has(id)) {
             problems.push({ code: 'ORGANIZE_UNKNOWN_CITATION', message: `小节「${section.title}」引用了这批知识里没有的 id「${id}」` })

package/src/client/EnvironmentSetup.tsx

@@ -0,0 +1,145 @@
+import { useCallback, useEffect, useState, type ReactNode } from 'react'
+import { Button, cn, Select, SelectContent, SelectItem, SelectLabel, SelectGroup, SelectTrigger, SelectValue } from '@tita-agent/ui/components'
+import { AlertCircle, Check, ChevronDown, Download, LoaderCircle, RefreshCw } from '@tita-agent/ui/icons'
+import type { ModelSelection, ModelOptionView } from '../environment/model-catalog.js'
+import type { EnvironmentView } from '../environment/types.js'
+
+async function environmentRequest(init?: RequestInit): Promise<EnvironmentView> {
+  const response = await fetch(init ? '/knowledge/environment/prepare' : '/knowledge/environment', init)
+  const payload = await response.json() as { ok?: boolean; data?: EnvironmentView; error?: { message?: string } }
+  if (!response.ok || !payload.ok || !payload.data) throw new Error(payload.error?.message ?? `环境服务响应失败（${response.status}）`)
+  return payload.data
+}
+
+export function useKnowledgeEnvironment(visible: boolean, revision: number) {
+  const [view, setView] = useState<EnvironmentView>()
+  const [error, setError] = useState<string>()
+  const [submitting, setSubmitting] = useState(false)
+  const refresh = useCallback(async (): Promise<void> => {
+    try { setView(await environmentRequest()); setError(undefined) }
+    catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)) }
+  }, [])
+  const busy = submitting || view?.job?.state === 'running' || view?.report.state === 'checking'
+  useEffect(() => {
+    if (!visible) return
+    void refresh()
+    const onFocus = (): void => { void refresh() }
+    window.addEventListener('focus', onFocus)
+    const timer = busy ? setInterval(() => { void refresh() }, 1500) : undefined
+    return () => { if (timer) clearInterval(timer); window.removeEventListener('focus', onFocus) }
+  }, [visible, revision, busy, refresh])
+  const prepare = useCallback(async (action: 'install' | 'check' | 'cancel', selection?: ModelSelection): Promise<void> => {
+    setSubmitting(true)
+    try {
+      setView(await environmentRequest({ method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ action, ...(selection ? { selection } : {}) }) }))
+      setError(undefined)
+    } catch (cause) { setError(cause instanceof Error ? cause.message : String(cause)) }
+    finally { setSubmitting(false) }
+  }, [])
+  return { view, error, busy, prepare }
+}
+
+type EnvironmentController = ReturnType<typeof useKnowledgeEnvironment>
+
+function ModelSelect({ id, label, value, options, disabled, onChange }: {
+  id: string
+  label: string
+  value: string
+  options: ModelOptionView[]
+  disabled: boolean
+  onChange: (value: string) => void
+}): ReactNode {
+  const chosen = options.find(option => option.id === value)
+  const descriptionId = `${id}-description`
+  return <div className="grid min-w-0 gap-1.5">
+    <label htmlFor={id} className="text-xs font-medium text-tita-ink">{label}</label>
+    <Select value={value} onValueChange={onChange} disabled={disabled}>
+      <SelectTrigger id={id} aria-describedby={descriptionId} className="w-full"><SelectValue /></SelectTrigger>
+      <SelectContent position="popper" align="start" className="max-h-64">
+        <SelectGroup>
+          <SelectLabel>按资源占用从低到高</SelectLabel>
+          {options.map(option => <SelectItem key={option.id} value={option.id}>
+            {option.label} · {option.download}
+          </SelectItem>)}
+        </SelectGroup>
+      </SelectContent>
+    </Select>
+    <p id={descriptionId} className="m-0 text-xs leading-relaxed text-tita-ink-muted">
+      {chosen ? `${chosen.description} 下载约 ${chosen.download}${chosen.dimension ? `，输出 ${chosen.dimension} 维` : ''}。` : '请选择模型。'}
+    </p>
+    {chosen?.modelCardUrl && <a href={chosen.modelCardUrl} target="_blank" rel="noreferrer" className="w-fit text-xs text-tita-ink underline underline-offset-2">查看模型卡与许可</a>}
+  </div>
+}
+
+export function EnvironmentNotice({ controller, onOpen }: { controller: EnvironmentController; onOpen: () => void }): ReactNode {
+  const { view, error, busy } = controller
+  if (!error && (!view || view.report.state === 'ready')) return null
+  return <div className="mx-3 mt-2 flex shrink-0 items-center gap-2 border-b border-tita-line pb-2 text-xs text-tita-ink" role="status">
+    {busy ? <LoaderCircle size={14} className="tita-spin shrink-0" /> : <AlertCircle size={14} className="shrink-0 text-tita-warning" />}
+    <span className="min-w-0 flex-1">{error ? '环境状态读取失败' : busy ? view?.job?.stage ?? '正在检查运行环境' : '首次使用前，请准备向量和重排模型'}</span>
+    <Button variant="outline" size="sm" onClick={onOpen}>环境准备</Button>
+  </div>
+}
+
+export function EnvironmentSetup({ controller }: { controller: EnvironmentController }): ReactNode {
+  const { view, error, busy, prepare } = controller
+  const [details, setDetails] = useState(false)
+  const [selection, setSelection] = useState<ModelSelection>()
+  useEffect(() => {
+    if (view) setSelection(view.selection)
+  }, [view?.selection.embedding, view?.selection.rerank])
+  const ready = view?.report.state === 'ready'
+  const job = view?.job
+  const running = job?.state === 'running'
+  const failure = job?.state === 'failed' ? job.error : undefined
+  const chosen = selection ?? view?.selection
+  const selectionChanged = Boolean(chosen && view && (chosen.embedding !== view.selection.embedding || chosen.rerank !== view.selection.rerank))
+  return <section id="tita-environment" tabIndex={-1} aria-labelledby="tita-environment-title" className="tita-settingsSection">
+    <div className="tita-settingsSectionHeader">
+      <h3 id="tita-environment-title">环境准备</h3>
+      <span className={cn('text-xs', ready ? 'text-tita-success' : 'text-tita-ink-muted')} role="status" aria-live="polite">
+        {ready ? '已就绪' : busy ? '进行中' : '必需'}
+      </span>
+    </div>
+    <p className="m-0 mb-3 text-xs leading-relaxed text-tita-ink-muted">首次准备需要联网下载所选模型和推理依赖。模型保存在 Tita 专属目录，并通过实际推理自检后启用。</p>
+    <ul className="m-0 grid list-none gap-3 p-0" aria-label="运行环境检查项">
+      {(view?.report.items ?? []).map(item => <li key={item.id} className="flex min-w-0 items-start gap-2">
+        {item.state === 'ready' ? <Check size={14} className="mt-0.5 shrink-0 text-tita-success" /> : item.state === 'checking'
+          ? <LoaderCircle size={14} className="tita-spin mt-0.5 shrink-0" /> : <AlertCircle size={14} className="mt-0.5 shrink-0 text-tita-warning" />}
+        <div className="min-w-0 flex-1 text-xs leading-relaxed">
+          <span className="font-medium text-tita-ink">{item.label}</span>
+          <p className="m-0 break-words text-tita-ink-muted">{item.message}</p>
+        </div>
+      </li>)}
+    </ul>
+    {view && chosen && <div className="my-4 grid gap-3" aria-label="模型选择">
+      <ModelSelect id="tita-embedding-model" label="向量模型" value={chosen.embedding} options={view.models.embedding} disabled={busy}
+        onChange={value => setSelection(current => ({ ...(current ?? view.selection), embedding: value as ModelSelection['embedding'] }))} />
+      <ModelSelect id="tita-rerank-model" label="重排模型" value={chosen.rerank} options={view.models.rerank} disabled={busy}
+        onChange={value => setSelection(current => ({ ...(current ?? view.selection), rerank: value as ModelSelection['rerank'] }))} />
+      {selectionChanged && <p className="m-0 text-xs leading-relaxed text-tita-warning" role="status">
+        安装并通过实际推理自检后才会切换当前模型。更改向量模型后，已有知识需要重新编译。
+      </p>}
+    </div>}
+    {!view && !error && <p className="text-xs text-tita-ink-muted" role="status">正在读取环境状态…</p>}
+    {running && <p className="my-3 text-xs text-tita-ink" role="status" aria-live="polite">{job.stage}。你可以离开此面板，任务会继续。</p>}
+    {(error || failure) && <p className="my-3 break-words text-xs text-tita-danger" role="alert">{error ?? failure}</p>}
+    {job?.state === 'cancelled' && <p className="my-3 text-xs text-tita-ink-muted" role="status">{job.error}</p>}
+    <div className="mt-4 flex flex-wrap gap-2">
+      <Button size="sm" variant={ready ? 'outline' : 'default'} disabled={busy} onClick={() => { void prepare('install', chosen) }}>
+        <Download size={13} />{selectionChanged ? '安装所选模型' : ready ? '修复当前环境' : job?.state === 'failed' || job?.state === 'cancelled' ? '重试准备' : '一键安装 / 修复'}
+      </Button>
+      <Button variant="outline" size="sm" disabled={busy || selectionChanged} onClick={() => { void prepare('check') }}><RefreshCw size={13} />重新自检</Button>
+      {running && <Button variant="ghost" size="sm" disabled={controller.busy && !running} onClick={() => { void prepare('cancel') }}>停止</Button>}
+    </div>
+    {ready && <p className="mb-0 mt-3 text-xs text-tita-ink-muted">环境自检通过。已有知识请重新编译，以生成当前模型的向量索引。</p>}
+    <Button variant="ghost" size="sm" className="mt-2" aria-expanded={details} aria-controls="tita-environment-details" onClick={() => setDetails(value => !value)}>
+      <ChevronDown size={13} />{details ? '收起检查详情' : '检查详情与日志'}
+    </Button>
+    {details && <div id="tita-environment-details" className="mt-2 grid gap-2 text-xs leading-relaxed text-tita-ink-muted">
+      {view?.report.checkedAt && <p className="m-0">最近自检：{new Date(view.report.checkedAt).toLocaleString()}</p>}
+      {view?.report.items.map(item => item.path && <p key={item.id} className="m-0 break-all">{item.label}：{item.path}</p>)}
+      {job?.logs.length ? <pre className="m-0 max-h-40 overflow-auto whitespace-pre-wrap break-all rounded-tita-control bg-tita-surface-muted p-2 font-mono">{job.logs.join('\n')}</pre> : null}
+    </div>}
+  </section>
+}

package/src/client/KnowledgePanel.tsx

@@ -11,6 +11,7 @@ import {
 import { KNOWLEDGE_SETTINGS_ORDER, NodeSettingsPanel, settingsAnchorId, useScope, type SettingsNode, type SettingsScopeLike } from './NodeSettings.tsx'
 import { useAgentLayout } from './DirectoryPicker.tsx'
 import { AgentPresetCard, type AgentPresetRemote } from './AgentPresetCard.tsx'
+import { EnvironmentNotice, EnvironmentSetup, useKnowledgeEnvironment } from './EnvironmentSetup.tsx'
 import {
   NODE_META, NODE_ORDER, NODE_STATUS_LABEL, noteCountOf, sourceCountOf,
   type KnowledgeStats, type KnowledgeTab, type NodeId, type PanelTab, type Tone, type WorkspaceTabKind,
@@ -212,7 +213,7 @@ export function KnowledgePanel({ visible, currentQuestion, onOpenTab, settings,
   /** 从架构图节点跳到知识库分栏：tab + 一个递增的 nonce（同栏再点也要生效）。 */
   const [knowledgeFocus, setKnowledgeFocus] = useState<{ tab: KnowledgeTab; nonce: number } | undefined>(undefined)
   /** 设置抽屉入口。`null` = 关闭；否则定位到对应分组。 */
-  const [settingsTarget, setSettingsTarget] = useState<SettingsNode | null>(null)
+  const [settingsTarget, setSettingsTarget] = useState<SettingsNode | 'environment' | null>(null)
   const [showAdvancedSettings, setShowAdvancedSettings] = useState(false)
   /**
    * 固定 Agent 目录 + 家当解析结果。它们是**服务端算出来的**（`layout.ts` 是唯一真源），
@@ -223,6 +224,7 @@ export function KnowledgePanel({ visible, currentQuestion, onOpenTab, settings,
    */
   const knowledgeSnapshot = useScope(settings?.knowledge)
   const { layout } = useAgentLayout(knowledgeSnapshot.revision ?? 0)
+  const environment = useKnowledgeEnvironment(visible, knowledgeSnapshot.revision ?? 0)
 
   /**
    * 只报**失败**的两条（2026-10-06）。
@@ -252,7 +254,7 @@ export function KnowledgePanel({ visible, currentQuestion, onOpenTab, settings,
   useEffect(() => {
     if (!settingsTarget) return
     const frame = requestAnimationFrame(() => {
-      const section = document.getElementById(settingsAnchorId(settingsTarget))
+      const section = document.getElementById(settingsTarget === 'environment' ? 'tita-environment' : settingsAnchorId(settingsTarget))
       section?.scrollIntoView({ block: 'start' })
       section?.focus({ preventScroll: true })
     })
@@ -260,7 +262,7 @@ export function KnowledgePanel({ visible, currentQuestion, onOpenTab, settings,
   }, [settingsTarget])
 
   /** 打开设置抽屉并落到某一块。传 `null` 就是关。 */
-  const openSettings = useCallback((target: SettingsNode | null): void => { setSettingsTarget(target) }, [])
+  const openSettings = useCallback((target: SettingsNode | 'environment' | null): void => { setSettingsTarget(target) }, [])
 
   const refreshStats = useCallback(async (): Promise<void> => {
     setStatsLoading(true); setStatsError(null)
@@ -330,10 +332,12 @@ export function KnowledgePanel({ visible, currentQuestion, onOpenTab, settings,
         <Button
           variant="ghost" size="icon" className={styles.tabBarSettings}
           aria-label="设置" title="设置 · 本方案参数"
-          onClick={() => openSettings('storage')}
+          onClick={() => openSettings('environment')}
         ><Settings2 size={15} /></Button>
       </div>
 
+      <EnvironmentNotice controller={environment} onOpen={() => openSettings('environment')} />
+
       {/* 两栏走「舞台」版式（自己占满高度、不参与面板滚动）：智能归因是图 + 运行面板，
           概览是画布 + 画布内浮层。同一套语汇，同一个理由 —— 它们的内容都要自己撑满
           可视区，让面板替它们滚会把画布推成一条可以滚出视口的纸。 */}
@@ -436,6 +440,7 @@ export function KnowledgePanel({ visible, currentQuestion, onOpenTab, settings,
         <DrawerBody>
           {/* 设置按数据位置、向量模型、检索与上下文分组。坐标定义按知识库保存，入口在工具栏。 */}
           <div className={styles.settingsStack}>
+            <EnvironmentSetup controller={environment} />
             {/* 故障排在最前面（同一条纪律：对不上账的事排在「有什么」之前）。 */}
             {layoutFailures.map(text => <div key={text} className="tita-settingsError" role="alert">
               <AlertCircle size={13} /><span>{text}</span>

package/src/compiler/embedding-identity.ts

@@ -0,0 +1,21 @@
+import { createHash } from 'node:crypto'
+import { readdirSync, statSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+
+/** Cache compatibility includes the checkpoint location and its local revision. */
+export function embeddingFingerprint(model: string, resourceRoot?: string, endpoint?: string): string {
+  let location = model
+  const files: Array<[string, number, number]> = []
+  if (isAbsolute(model)) {
+    const root = resourceRoot && resolve(resourceRoot)
+    location = root && model.startsWith(`${root}${sep}`) ? `resource:${relative(root, model)}` : resolve(model)
+    try {
+      for (const name of readdirSync(model).sort()) {
+        if (!/\.(?:json|safetensors|bin|model)$/.test(name)) continue
+        const stat = statSync(join(model, name))
+        if (stat.isFile()) files.push([name, stat.size, stat.mtimeMs])
+      }
+    } catch { /* The normal model loader reports missing or inaccessible checkpoints. */ }
+  }
+  return createHash('sha256').update(JSON.stringify({ location, files, endpoint })).digest('hex')
+}

package/src/compiler/snapshot.ts

@@ -0,0 +1,17 @@
+import type { Knowledge } from '../knowledge.js'
+import type { CardKnowledgeRow } from '../store/knowledge-db.js'
+import type { ContextGraph, KnowledgeCard, WikiNote } from '../types.js'
+
+/** One published generation; retrieval captures this value before any model call. */
+export interface CompileSnapshot {
+  version: number
+  compileRunId: string
+  cards: KnowledgeCard[]
+  notes: WikiNote[]
+  graph: ContextGraph
+  diagnosisGraph: ContextGraph
+  placements: Array<[string, CardKnowledgeRow[]]>
+  knowledge: Knowledge[]
+}
+
+export const COMPILE_SNAPSHOT = 'recall-snapshot.json'

package/src/diagnosis/store.ts

@@ -317,6 +317,7 @@ export class DiagnosisStore {
     const records: DiagnosisRunRecord[] = []
     const problems: string[] = []
     for (const source of await this.host.loadSources()) {
+      if (!source.sourceId.startsWith('diagnosis:') && !source.content.includes('```json diagnosis-run')) continue
       const record = parseRunSource(source.content)
       if (record) records.push(record)
       else problems.push(`诊断日志 ${source.sourceId} 里没有可解析的 \`json diagnosis-run\` 块，已跳过`)