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

package/src/knowledge-bases.ts

@@ -11,8 +11,8 @@
  * 挑一个目录 —— 见 `layout.ts` 的三条原理。
  *
  * 注册表本身只持久化**配置**（id / name / description / rootDir），
- * 落到 `<dataHome>/knowledge-bases.json`，`dataHome =
- * process.env.TITA_DATA_AGENT_HOME || ~/.tita-data-agent`。
+ * 落到 `<agentRoot>/resource/knowledge-bases.json`。插件运行时会显式传入这个注册表
+ * 位置；没有传入时也使用固定的 DSH/Tita Agent 目录，不再回退到旧的用户目录。
  * `sourceCount` / `cardCount` / `noteCount` / `buildVersion` 都是**计算字段**，缓存在同一个 JSON 里，由 `refresh()` 从真实
  * runtime 重新统计；这样 `list()` / `get()` 保持同步签名（前端首屏直接用），
  * 路由在返回前 `await refresh()` 拿到准确值。
@@ -24,13 +24,13 @@
 
 import { existsSync, readFileSync } from 'node:fs'
 import { mkdir, rename, unlink, writeFile } from 'node:fs/promises'
-import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import {
-  type Envelope, type KnowledgeBase, type KnowledgeConfig,
+  DEFAULT_COMPILE_MODEL, type CompileModelSelection, type Envelope, type KnowledgeBase, type KnowledgeConfig,
 } from './types.js'
 import { defaultKnowledgeRoot, failure, KnowledgeRuntime, success, type KnowledgeRuntimeOptions } from './runtime.js'
-import { knowledgeBaseRoot, memoryRoot } from './layout.js'
+import { defaultAgentRoot, knowledgeBaseRoot, memoryRoot, resourceRoot } from './layout.js'
+import { writeTextAtomic } from './fs-atomic.js'
 
 /** 持久化形态：配置 + 计算字段缓存分区。 */
 interface KnowledgeBaseRecord {
@@ -47,6 +47,8 @@ interface KnowledgeBaseRecord {
    * 这个库自己的判断。
    */
   extractionNote: string
+  /** 编译模型路由；它是注册表配置，不属于知识正文。 */
+  compileModel: CompileModelSelection
   createdAt: string
   updatedAt: string
 }
@@ -69,7 +71,7 @@ interface BaseStats {
 export const DEFAULT_KB_ID = 'default'
 
 export interface KnowledgeBasesOptions {
-  /** 覆盖 `~/.tita-data-agent`；测试用临时目录，避免写用户主目录。 */
+  /** 注册表的备用数据目录；生产运行时使用 `registryFile` 指向 Agent 的 resource。 */
   dataHome?: string
   /** 默认库的根目录来源；插件传入由 `agentRoot` 推出来的那一格。 */
   defaultRootDir?: () => string
@@ -96,7 +98,7 @@ export interface KnowledgeBasesOptions {
    * `index.ts` 里直接 new），新建的库一律退回规则抽取：正文按 `##` 小节切，
    * 界面上只留一句「运行时没有注入模型接缝」。这跟写库 id 无关，纯粹是构造点漏了。
    */
-  runtimeOptions?: () => Partial<KnowledgeRuntimeOptions>
+  runtimeOptions?: (baseId: string) => Partial<KnowledgeRuntimeOptions>
   /**
    * 覆盖注册表文件位置（默认 `<dataHome>/knowledge-bases.json`）。
    *
@@ -115,6 +117,17 @@ function textOr(input: unknown, fallback: string): string {
   return typeof input === 'string' && input.trim() ? input.trim() : fallback
 }
 
+function compileModelOf(input: unknown): CompileModelSelection {
+  const value = record(input)
+  const effort = typeof value.reasoningEffort === 'string' && value.reasoningEffort.trim() ? { reasoningEffort: value.reasoningEffort.trim() } : {}
+  if (value.mode !== 'fixed') return { ...DEFAULT_COMPILE_MODEL, ...effort }
+  const provider = typeof value.provider === 'string' ? value.provider.trim() : ''
+  const model = typeof value.model === 'string' ? value.model.trim() : ''
+  // 旧版本没有这个字段，或留下了半截配置时，安全地回到 DSH 默认模型。
+  if (!provider || !model) return { ...DEFAULT_COMPILE_MODEL }
+  return { mode: 'fixed', provider, model, ...effort }
+}
+
 function normalizeExt(value: unknown, fallback: string): string {
   const text = typeof value === 'string' ? value.trim().toLowerCase() : ''
   const ext = text || fallback
@@ -126,22 +139,13 @@ function emptyBase(id: string): KnowledgeBase {
   return {
     id, name: id, description: '', rootDir: '', isDefault: false,
     extractionNote: '',
+    compileModel: { ...DEFAULT_COMPILE_MODEL },
     createdAt: '', updatedAt: '', sourceCount: 0, cardCount: 0, noteCount: 0, buildVersion: 0,
   }
 }
 
-async function writeTextAtomic(path: string, content: string): Promise<void> {
-  const temporary = `${path}.${process.pid}.${Date.now().toString(36)}.tmp`
-  try {
-    await writeFile(temporary, content, 'utf8')
-    await rename(temporary, path)
-  } finally {
-    try { await unlink(temporary) } catch { /* rename already consumed it */ }
-  }
-}
-
 export function defaultDataHome(): string {
-  return resolve(process.env.TITA_DATA_AGENT_HOME || join(homedir(), '.tita-data-agent'))
+  return resourceRoot(defaultAgentRoot())
 }
 
 export class KnowledgeBases {
@@ -243,7 +247,7 @@ export class KnowledgeBases {
         // 逻辑的单元测试）留空，runtime 会退回知识树里的 `04_memory`。
         ...(this.options.agentRoot ? { memoryRoot: memoryRoot(this.options.agentRoot(), base.id) } : {}),
         // 0044：宿主级能力（模型接缝）必须一起带过来，否则非默认库静默退回规则抽取。
-        ...(this.options.runtimeOptions?.() ?? {}),
+        ...(this.options.runtimeOptions?.(base.id) ?? {}),
       })
     runtime.baseId = base.id
     this.runtimes.set(key, runtime)
@@ -268,6 +272,15 @@ export class KnowledgeBases {
     this.runtimes.clear()
   }
 
+  /** Volatile settings apply to every cached base, including non-default bases. */
+  updateRuntimeConfig(config: Partial<import('./types.js').RuntimeKnowledgeConfig>): void {
+    for (const runtime of this.runtimes.values()) runtime.updateConfig(config)
+  }
+
+  reloadResources(): void {
+    for (const runtime of this.runtimes.values()) runtime.reloadResources()
+  }
+
   // ------------------------------------------------------------- 统计刷新
 
   /**
@@ -324,6 +337,7 @@ export class KnowledgeBases {
       rootDir,
       isDefault: false,
       extractionNote: '',
+      compileModel: { ...DEFAULT_COMPILE_MODEL },
       createdAt: now,
       updatedAt: now,
     }
@@ -337,12 +351,23 @@ export class KnowledgeBases {
    * 更新名称 / 描述 / 坐标提取备注。
    *
    */
-  async update(id: string, patch: { name?: string; description?: string; extractionNote?: string }): Promise<Envelope<KnowledgeBase>> {
+  async update(id: string, patch: { name?: string; description?: string; extractionNote?: string; compileModel?: CompileModelSelection }): Promise<Envelope<KnowledgeBase>> {
     this.ensureLoaded()
     const base = this.records.find(item => item.id === id)
     if (!base) return failure(emptyBase(id), 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
     // 守卫必须基于精确的实时计数，不能用可能过期的缓存。
     await this.refreshOne(base)
+    let nextCompileModel = base.compileModel
+    if (patch.compileModel !== undefined) {
+      if (patch.compileModel.mode !== 'default' && patch.compileModel.mode !== 'fixed') {
+        return failure(this.view(base), 'COMPILE_MODEL_INVALID', '编译模型 mode 只能是 default 或 fixed', false, '从编译模型选择项中选择“跟随 DSH 默认模型”或一个固定模型。')
+      }
+      const selected = compileModelOf(patch.compileModel)
+      if (patch.compileModel.mode === 'fixed' && selected.mode !== 'fixed') {
+        return failure(this.view(base), 'COMPILE_MODEL_INVALID', '固定编译模型必须同时提供 provider 和 model', false, '从当前 DSH 模型目录中选择一个可用模型。')
+      }
+      nextCompileModel = selected
+    }
     if (patch.name !== undefined) {
       const name = String(patch.name).trim()
       if (!name) return failure(this.view(base), 'NAME_REQUIRED', 'name 不能为空', false)
@@ -351,6 +376,7 @@ export class KnowledgeBases {
     if (patch.description !== undefined) base.description = String(patch.description)
     // 长度上限不是配额，是防呆：这条备注逐字进每一次抽取的提示词，几万字会把文档挤出去。
     if (patch.extractionNote !== undefined) base.extractionNote = String(patch.extractionNote).slice(0, 4000)
+    base.compileModel = nextCompileModel
     base.updatedAt = new Date().toISOString()
     await this.refreshOne(base)
     await this.persist()
@@ -366,6 +392,12 @@ export class KnowledgeBases {
     return this.records.find(item => item.id === id)?.extractionNote ?? ''
   }
 
+  /** 当前知识库的编译模型路由。不存在的库回到默认路由，避免读路径抛错。 */
+  compileModelOf(id: string): CompileModelSelection {
+    this.ensureLoaded()
+    return { ...(this.records.find(item => item.id === id)?.compileModel ?? DEFAULT_COMPILE_MODEL) }
+  }
+
   /**
    * 删除知识库。
    *
@@ -410,6 +442,7 @@ export class KnowledgeBases {
       rootDir: base.isDefault ? this.defaultRootDir() : base.rootDir,
       isDefault: base.isDefault,
       extractionNote: base.extractionNote,
+      compileModel: { ...base.compileModel },
       createdAt: base.createdAt,
       updatedAt: base.updatedAt,
       sourceCount: stats?.sourceCount ?? 0,
@@ -428,6 +461,7 @@ export class KnowledgeBases {
       rootDir: this.defaultRootDir(),
       isDefault: true,
       extractionNote: '',
+      compileModel: { ...DEFAULT_COMPILE_MODEL },
       createdAt: now,
       updatedAt: now,
     }
@@ -468,6 +502,7 @@ export class KnowledgeBases {
         isDefault: true,
         rootDir: seed.rootDir,
         name: existing.name || seed.name,
+        compileModel: existing.compileModel ?? seed.compileModel,
       }
     }
   }
@@ -488,6 +523,7 @@ export class KnowledgeBases {
       isDefault: value.isDefault === true || id === this.defaultId,
       // 0068 之前存下来的注册表里没有这个键：算空串，不报错，也不影响别的字段。
       extractionNote: typeof value.extractionNote === 'string' ? value.extractionNote : '',
+      compileModel: compileModelOf(value.compileModel),
       createdAt: typeof value.createdAt === 'string' && value.createdAt ? value.createdAt : now,
       updatedAt: typeof value.updatedAt === 'string' && value.updatedAt ? value.updatedAt : now,
     }

package/src/knowledge-contract.ts

@@ -0,0 +1,114 @@
+/** Browser-safe Knowledge contracts. Axis semantics remain in axis-contract.ts. */
+export type KnowledgeKind = 'fact' | 'procedure' | 'case'
+export type WikiKind = 'fact' | 'way'
+
+export interface ProcedureContent {
+  question: string
+  appliesWhen: string[]
+  method: string[]
+  resultChecks: string[]
+  limitations: string[]
+  completeness: 'complete' | 'partial' | 'reference_only'
+  caseRefs: Array<{ id: string; version: number }>
+}
+
+export interface KnowledgeContent {
+  conditions?: string[]
+  procedure?: ProcedureContent
+}
+
+export function wikiProjection(kind: KnowledgeKind, coordinate: { objectId: string; actionId: string; sceneId: string }): { objectId: string; actionId: string; sceneId: string } | undefined {
+  if (kind === 'case' || !coordinate.objectId || (kind === 'procedure' && !coordinate.actionId)) return undefined
+  return { objectId: coordinate.objectId, actionId: kind === 'procedure' ? coordinate.actionId : '', sceneId: '' }
+}
+
+export function procedureText(value: ProcedureContent): string {
+  return [value.question, value.appliesWhen.length ? `适用条件：${value.appliesWhen.join('；')}` : '',
+    value.method.map((step, index) => { const prefix = `${index + 1}. `; return prefix + step.replace(/\n/g, `\n${' '.repeat(prefix.length)}`) }).join('\n'),
+    value.resultChecks.length ? `结果检查：${value.resultChecks.join('；')}` : '',
+    value.limitations.length ? `边界：${value.limitations.join('；')}` : ''].filter(Boolean).join('\n\n')
+}
+
+type Row = Record<string, unknown>
+const row = (v: unknown): Row => v !== null && typeof v === 'object' && !Array.isArray(v) ? v as Row : {}
+const rows = (v: unknown): Row[] => Array.isArray(v) ? v.map(row) : []
+function list(v: unknown): unknown[] {
+  if (typeof v === 'string') { const p: unknown = JSON.parse(v || '[]'); if (!Array.isArray(p)) throw new Error('列表字段必须为数组'); return p }
+  if (v === null || v === undefined) return []
+  if (!Array.isArray(v)) throw new Error('列表字段必须为数组')
+  return v
+}
+const strings = (v: unknown): string[] => list(v).map(x => { if (typeof x === 'string') return x; if (typeof row(x).text === 'string') return row(x).text as string; throw new Error('列表项必须为字符串或包含 text 的对象') }).map(x => x.trim()).filter(Boolean)
+
+/** Adapt v2 wire records to the existing evidence/axis resolver; legacy reports remain readable. */
+export function normalizeKnowledgeExtraction(value: unknown): unknown {
+  const input = row(value)
+  if (!('facts' in input) && !('procedures' in input) && !('cases' in input)) return value
+  for (const key of ['facts', 'procedures', 'cases']) if (!Array.isArray(input[key])) throw new Error(`抽取缺少 ${key} 数组`)
+  const evidence = new Map<string, Row>()
+  for (const entry of rows(input.evidence)) {
+    const id = typeof entry.id === 'string' ? entry.id.trim() : ''
+    if (!id || evidence.has(id) || typeof entry.quote !== 'string' || !entry.quote.trim()) throw new Error('引文 ID 重复、为空或缺少 quote')
+    evidence.set(id, entry)
+  }
+  const refs = (item: Row): Row[] => {
+    if (Array.isArray(item.sources)) {
+      const sources = rows(item.sources)
+      if (!sources.length || sources.some(source => typeof source.quote !== 'string' || !source.quote.trim())) throw new Error('记录缺少有效来源引文')
+      return sources
+    }
+    const ids = typeof item.evidence === 'string' ? item.evidence.trim().split(/\s+/).filter(Boolean) : list(item.evidence)
+    if (!ids.length) throw new Error('记录缺少 evidence 引用')
+    return ids.map(id => {
+      const e = evidence.get(String(id))
+      if (!e || typeof e.quote !== 'string' || !e.quote.trim()) throw new Error(`引文 ${String(id)} 不存在或为空`)
+      return { quote: e.quote, heading_path: strings(e.heading_path) }
+    })
+  }
+  const seen = new Set<string>()
+  const checkId = (v: Row): void => {
+    const id = String(v.id ?? '').trim()
+    if (!id || seen.has(id)) throw new Error('Knowledge 局部 ID 为空或重复')
+    seen.add(id)
+  }
+  const knowledge = rows(input.facts).map(f => {
+    checkId(f)
+    return { ...f, scope_identity: true, kind: 'fact', data: strings(f.conditions).length ? { conditions: strings(f.conditions) } : {}, sources: refs(f) }
+  })
+  for (const p of rows(input.procedures)) {
+    checkId(p)
+    const completeness = p.completeness
+    if (!['complete', 'partial', 'reference_only'].includes(String(completeness))) throw new Error(`Procedure ${p.id} completeness 不合法`)
+    if (list(p.case_refs).length) throw new Error('抽取阶段不能生成 Case 版本引用，请使用独立提炼阶段')
+    const method = list(p.method)
+    const stepSources = method.flatMap(step => typeof step === 'string' ? [] : refs(row(step)))
+    const procedure: ProcedureContent = {
+      question: String(p.question ?? '').trim(), appliesWhen: strings(p.applies_when), method: strings(method),
+      resultChecks: strings(p.result_checks), limitations: [...strings(p.limitations), ...strings(p.missing)],
+      completeness: completeness as ProcedureContent['completeness'],
+      caseRefs: list(p.case_refs).map(ref => ({ id: String(row(ref).id ?? ''), version: Number(row(ref).version ?? 0) })),
+    }
+    if (!procedure.question || (procedure.completeness === 'complete' && procedure.method.length === 0)) throw new Error(`Procedure ${p.id} 缺少问题或完整方法`)
+    knowledge.push({ ...p, scope_identity: true, kind: 'procedure', text: procedureText(procedure), data: { procedure }, sources: [...refs(p), ...stepSources] } as typeof knowledge[number])
+  }
+  const caseIds = new Set(rows(input.cases).map(c => c.id))
+  const timelineKeys = new Set<string>()
+  for (const step of rows(input.timeline)) {
+    if (!caseIds.has(step.case_id)) throw new Error('时间线引用不存在的 Case')
+    const key = `${step.case_id}:${step.order}`
+    if (!Number.isInteger(step.order) || Number(step.order) < 1 || timelineKeys.has(key)) throw new Error('时间线顺序必须为不重复的正整数')
+    timelineKeys.add(key)
+  }
+  const events = rows(input.cases).map(c => {
+    checkId(c)
+    const timeline = Array.isArray(c.timeline) ? rows(c.timeline) : rows(input.timeline).filter(step => step.case_id === c.id)
+    if (timeline.some(step => !['observation', 'check', 'action', 'result', 'conclusion'].includes(String(step.type)))) throw new Error('Case 时间线类型不合法')
+    const rootCause = typeof c.root_cause === 'string' ? c.root_cause ? { text: c.root_cause, status: c.root_cause_status } : null : c.root_cause
+    return { ...c, coordinate: c.coordinate ?? { object_mention: c.object, action_mention: c.action, scene_mention: c.scene },
+      missing: strings(c.missing), root_cause: rootCause, sources: refs(c),
+      timeline: timeline.map(step => ({ ...step, sources: refs(step) })) }
+  })
+  return { ...input, knowledge, events,
+    ...Object.fromEntries(['objects', 'actions', 'scenes'].map(key => [key, rows(input[key]).map(a => ({ ...a,
+      parent_mention: a.parent_mention ?? a.parent, evidence: typeof a.evidence === 'string' && !evidence.has(a.evidence) ? a.evidence : refs(a).map(e => e.quote).join('\n') }))])) }
+}