dsh-data-domain-knowledge 0.1.0-alpha.2 → 0.1.0-alpha.4

package/src/intent/types.ts

@@ -131,7 +131,7 @@ export const DEFAULT_CATEGORIES: Array<IntentCategory & { examples: string[] }>
 
 export const DEFAULT_PREDICATES: string[] = [
   'query_babel_data', 'query_knowledge', 'query_source_truth', 'query_metadata',
-  'query_graph', 'add_source', 'write_knowledge_card', 'rebuild_knowledge',
+  'query_graph', 'add_source', 'propose_wiki_cards', 'rebuild_knowledge',
   'send_message', 'export_artifact', 'unknown',
 ]
 

package/src/knowledge-bases.ts

@@ -2,7 +2,7 @@
  * 多知识库注册表（0021）。
  *
  * 产品参照 WeKnora：**一个知识库 = 独立配置 + 独立内容**。每个库有自己的
- * `rootDir`（沿用既有的 `01_source_truth` / `02_wiki` / `03_compiled` /
+ * `rootDir`（沿用既有的 `01_source_raw` / `02_wiki` / `03_compiled` /
  * `04_memory` 布局）和一套「文件类型 → 解析引擎」规则；库下面挂文档列表、
  * 文档详情与版本历史。
  *
@@ -29,15 +29,15 @@ import { homedir } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 import {
   BUILTIN_SOURCE_TYPES, defaultSourceTypes, FALLBACK_SOURCE_TYPE, isBuiltinSourceType,
-  MAX_SOURCE_TYPES, SOURCE_TYPE_ID_PATTERN, validateSourceTypeDraft, validateSourceTypeText, WIKI_TYPE_ID_PATTERN,
+  LEGACY_SOURCE_TYPE_IDS, MAX_SOURCE_TYPES, normalizeMetadataFields, SOURCE_TYPE_ID_PATTERN, validateSourceTypeDraft, validateSourceTypeText, WIKI_TYPE_ID_PATTERN,
   type Envelope, type KnowledgeBase, type KnowledgeConfig,
-  type SourceTypeDef, type SourceTypeDraft, type WikiSchemaMode, type WikiTypeDef,
+  type SourceTypeDef, type SourceTypeDraft, type WikiTypeDef,
 } from './types.js'
 import {
-  defaultWikiTypes, isBuiltinWikiType, parseFieldLines, parseSectionLines, templateCardFor,
+  defaultWikiTypes, isBuiltinWikiType, LEGACY_WIKI_TYPE_IDS, parseFieldLines, parseSectionLines, templateCardFor,
   validateWikiTypeDraft, validateWikiTypeText, type WikiTypeDraft,
 } from './wiki-types.js'
-import { defaultKnowledgeRoot, failure, KnowledgeRuntime, success } from './runtime.js'
+import { defaultKnowledgeRoot, failure, KnowledgeRuntime, success, type KnowledgeRuntimeOptions } from './runtime.js'
 import { knowledgeBaseRoot, memoryRoot } from './layout.js'
 
 /** 持久化形态：配置 + 计算字段缓存分区。 */
@@ -50,8 +50,6 @@ interface KnowledgeBaseRecord {
   sourceTypes: SourceTypeDef[]
   /** Wiki 卡片类型注册表（0024）。 */
   wikiTypes: WikiTypeDef[]
-  /** `report` 只标记问题，`strict` 拒绝不合规的写入。 */
-  wikiSchemaMode: WikiSchemaMode
   createdAt: string
   updatedAt: string
 }
@@ -96,6 +94,16 @@ export interface KnowledgeBasesOptions {
   defaultRuntime?: () => KnowledgeRuntime
   /** 非默认库的 runtime 配置来源（embedding / rerank / topK 等跟随插件设置）。 */
   config?: () => Partial<Omit<KnowledgeConfig, 'rootDir' | 'agentRoot'>>
+  /**
+   * 非默认库的 runtime **附加能力**来源（0044：模型接缝）。
+   *
+   * 与 `config` 的分工：`config` 是「这个库自己的设置」（embedding / rerank / topK），
+   * 而这里给的是「宿主才有的能力」—— 典型是 `modelSeam`，它要问插件所在的 `ctx`
+   * 才拿得到 `llm` 与默认模型。之前**只有默认库**的 runtime 带了模型接缝（那一个在
+   * `index.ts` 里直接 new），新建的库一律退回规则抽取：正文按 `##` 小节切，
+   * 界面上只留一句「运行时没有注入模型接缝」。这跟写库 id 无关，纯粹是构造点漏了。
+   */
+  runtimeOptions?: () => Partial<KnowledgeRuntimeOptions>
   /**
    * 覆盖注册表文件位置（默认 `<dataHome>/knowledge-bases.json`）。
    *
@@ -124,7 +132,7 @@ function normalizeExt(value: unknown, fallback: string): string {
 function emptyBase(id: string): KnowledgeBase {
   return {
     id, name: id, description: '', rootDir: '', isDefault: false, sourceTypes: [],
-    wikiTypes: [], wikiSchemaMode: 'report', wikiTypesCustomized: false,
+    wikiTypes: [], wikiTypesCustomized: false,
     createdAt: '', updatedAt: '', sourceCount: 0, cardCount: 0, noteCount: 0, buildVersion: 0,
   }
 }
@@ -236,10 +244,12 @@ export class KnowledgeBases {
       ? this.options.defaultRuntime()
       : new KnowledgeRuntime(base.rootDir, this.options.config?.() ?? {}, {
         sourceTypes: () => this.sourceTypesOf(base.id),
-        wikiSchema: () => ({ types: this.wikiTypesOf(base.id), mode: base.wikiSchemaMode }),
+        wikiSchema: () => ({ types: this.wikiTypesOf(base.id) }),
         // 0032：记忆段跟着**这个库**走，二级用 id。`agentRoot` 没给时（只测注册表
         // 逻辑的单元测试）留空，runtime 会退回知识树里的 `04_memory`。
         ...(this.options.agentRoot ? { memoryRoot: memoryRoot(this.options.agentRoot(), base.id) } : {}),
+        // 0044：宿主级能力（模型接缝）必须一起带过来，否则非默认库静默退回规则抽取。
+        ...(this.options.runtimeOptions?.() ?? {}),
       })
     runtime.baseId = base.id
     this.runtimes.set(key, runtime)
@@ -333,7 +343,6 @@ export class KnowledgeBases {
       isDefault: false,
       sourceTypes: defaultSourceTypes(),
       wikiTypes: defaultWikiTypes(),
-      wikiSchemaMode: 'report',
       createdAt: now,
       updatedAt: now,
     }
@@ -354,7 +363,7 @@ export class KnowledgeBases {
    * 恢复，并给出 warning）、兜底分类 `document` 不允许停用、新建自定义分类必须
    * 提交完整判定文案。
    */
-  async update(id: string, patch: { name?: string; description?: string; sourceTypes?: SourceTypeDef[]; wikiTypes?: WikiTypeDef[]; wikiSchemaMode?: WikiSchemaMode; resetWikiTypes?: boolean }): Promise<Envelope<KnowledgeBase>> {
+  async update(id: string, patch: { name?: string; description?: string; sourceTypes?: SourceTypeDef[]; wikiTypes?: WikiTypeDef[]; resetWikiTypes?: boolean }): 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)
@@ -387,7 +396,6 @@ export class KnowledgeBases {
     if (patch.description !== undefined) base.description = String(patch.description)
     if (sourceTypes !== undefined) base.sourceTypes = sourceTypes
     if (wikiTypes !== undefined) base.wikiTypes = wikiTypes
-    if (patch.wikiSchemaMode !== undefined) base.wikiSchemaMode = patch.wikiSchemaMode === 'strict' ? 'strict' : 'report'
     base.updatedAt = new Date().toISOString()
     await this.refreshOne(base)
     await this.persist()
@@ -436,6 +444,7 @@ export class KnowledgeBases {
       enabled: draft.enabled !== false,
       builtin: false,
       fallback: false,
+      ...(normalizeMetadataFields(draft.metadataFields).length > 0 ? { metadataFields: normalizeMetadataFields(draft.metadataFields) } : {}),
       sourceCount: 0,
     }
     base.sourceTypes = [...base.sourceTypes, created]
@@ -467,10 +476,14 @@ export class KnowledgeBases {
       signals: patch.signals ?? existing.signals,
       excludes: patch.excludes ?? existing.excludes,
       enabled: patch.enabled === undefined ? existing.enabled : patch.enabled !== false,
+      // 0048：`metadataFields` 缺省继承磁盘上已有的（与 signals 同一条约定：
+      // 「没传」不等于「清空」，否则一次改文案就会把字段声明悄悄抹掉）。
+      metadataFields: patch.metadataFields ?? existing.metadataFields,
     }
     const known = new Set(base.sourceTypes.map(def => def.id))
     const problem = validateSourceTypeText(merged, known)
     if (!problem.ok) return failure({} as SourceTypeDef, problem.code, problem.message, false, problem.suggestion)
+    const declared = normalizeMetadataFields(merged.metadataFields)
     const next: SourceTypeDef = {
       ...existing,
       label: String(merged.label).trim(),
@@ -478,6 +491,7 @@ export class KnowledgeBases {
       signals: (merged.signals as unknown[]).map(item => String(item).trim()).filter(Boolean),
       excludes: (merged.excludes as unknown[]).map(item => String(item).trim()).filter(Boolean),
       enabled: merged.enabled === true,
+      ...(declared.length > 0 ? { metadataFields: declared } : { metadataFields: undefined }),
     }
     base.sourceTypes = base.sourceTypes.map(def => def.id === typeId ? next : def)
     base.updatedAt = new Date().toISOString()
@@ -549,12 +563,6 @@ export class KnowledgeBases {
     return base.wikiTypes.map(def => ({ ...def, cardCount: counts[def.id] ?? 0 }))
   }
 
-  /** 卡片 schema 生效方式；未知 id 回退出厂值。 */
-  wikiSchemaModeOf(id: string): WikiSchemaMode {
-    this.ensureLoaded()
-    return this.records.find(item => item.id === id)?.wikiSchemaMode ?? 'report'
-  }
-
   /**
    * 新增一个卡片类型。
    *
@@ -592,7 +600,6 @@ export class KnowledgeBases {
       layer: patch.layer ?? existing.layer,
       sections: patch.sections ?? existing.sections,
       fields: patch.fields ?? existing.fields,
-      sourceTypes: patch.sourceTypes ?? existing.sourceTypes,
       examples: patch.examples ?? existing.examples,
     }
     const problem = validateWikiTypeText(merged)
@@ -606,7 +613,6 @@ export class KnowledgeBases {
       layer: merged.layer === 'instance' ? 'instance' : 'type',
       sections,
       fields,
-      sourceTypes: this.stringList(merged.sourceTypes),
       examples: this.stringList(merged.examples),
       template: templateCardFor(sections, fields),
       enabled: patch.enabled === undefined ? existing.enabled : patch.enabled !== false,
@@ -642,17 +648,6 @@ export class KnowledgeBases {
     return success({ deleted: true })
   }
 
-  /** 切换卡片 schema 的生效方式（`report` 只标记，`strict` 拒绝不合规的写入）。 */
-  async setWikiSchemaMode(id: string, mode: WikiSchemaMode): Promise<Envelope<{ mode: WikiSchemaMode }>> {
-    this.ensureLoaded()
-    const base = this.records.find(item => item.id === id)
-    if (!base) return failure({ mode }, 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
-    base.wikiSchemaMode = mode === 'strict' ? 'strict' : 'report'
-    base.updatedAt = new Date().toISOString()
-    await this.persist()
-    return success({ mode: base.wikiSchemaMode })
-  }
-
   /** 把一条 draft 转成完整类型（模板卡由小节派生，不手写第二份）。 */
   private wikiTypeFromDraft(typeId: string, draft: WikiTypeDraft): WikiTypeDef {
     const sections = parseSectionLines(draft.sections)
@@ -664,7 +659,6 @@ export class KnowledgeBases {
       layer: draft.layer === 'instance' ? 'instance' : 'type',
       sections,
       fields,
-      sourceTypes: this.stringList(draft.sourceTypes),
       examples: this.stringList(draft.examples),
       template: templateCardFor(sections, fields),
       enabled: true,
@@ -683,15 +677,21 @@ export class KnowledgeBases {
    *
    * 与 `normalizeSourceTypes` 同一套语义：老配置（没有 `wikiTypes` 字段）升级时补齐内置，
    * 缺失的内置类型被恢复（内置只允许停用，不允许删除）。
+   *
+   * 0040 的两次改名（`check` → `check_point`、`failure-mode` → `failure_reason`）在这里
+   * 也认别名：存量配置里那一项写着旧 id，不认的话它会被当成一个**自定义类型**留下来，
+   * 而内置的那一项会被补回来 —— 于是注册表里同时有 `diagnosis/check` 与
+   * `diagnosis/check-point` 两个类型，卡片该归哪个就再也说不清了。
    */
   private normalizeWikiTypes(raw: unknown): WikiTypeDef[] {
     const persisted = Array.isArray(raw) ? raw : []
     const byId = new Map<string, Record<string, unknown>>()
     for (const item of persisted) {
       const value = record(item)
-      const id = typeof value.id === 'string' ? value.id.trim() : ''
+      const rawId = typeof value.id === 'string' ? value.id.trim() : ''
+      const id = LEGACY_WIKI_TYPE_IDS[rawId] ?? rawId
       if (!id || !WIKI_TYPE_ID_PATTERN.test(id) || byId.has(id)) continue
-      byId.set(id, value)
+      byId.set(id, { ...value, id })
     }
     const defaults = defaultWikiTypes()
     const builtins = defaults.map(def => {
@@ -703,7 +703,7 @@ export class KnowledgeBases {
     const customs: WikiTypeDef[] = []
     for (const [id, value] of byId) {
       if (isBuiltinWikiType(id)) continue
-      const base: WikiTypeDef = { id, label: id, description: '', layer: 'type', sections: [], fields: [], sourceTypes: [], examples: [], template: '', enabled: true, builtin: false, cardCount: 0 }
+      const base: WikiTypeDef = { id, label: id, description: '', layer: 'type', sections: [], fields: [], examples: [], template: '', enabled: true, builtin: false, cardCount: 0 }
       const draft = this.wikiTypeFromRecord(base, value)
       // 只有能写出骨架的自定义类型才值得留下；否则它既没有模板也校验不了。
       if (validateWikiTypeText(draft).ok) customs.push(draft)
@@ -722,7 +722,6 @@ export class KnowledgeBases {
       layer: value.layer === 'instance' ? 'instance' : base.layer,
       sections: sections.length > 0 ? sections : base.sections.map(section => ({ ...section })),
       fields: Array.isArray(value.fields) ? fields : base.fields.map(field => ({ ...field })),
-      sourceTypes: Array.isArray(value.sourceTypes) ? this.stringList(value.sourceTypes) : [...base.sourceTypes],
       examples: this.stringList(value.examples).length > 0 ? this.stringList(value.examples) : [...base.examples],
       template: textOr(value.template, base.template),
       enabled: value.enabled !== false,
@@ -735,7 +734,7 @@ export class KnowledgeBases {
   private wikiTypesDifferFromDefaults(types: WikiTypeDef[]): boolean {
     const signature = (list: WikiTypeDef[]): string => JSON.stringify(list.map(def => ({
       id: def.id, label: def.label, description: def.description, layer: def.layer, enabled: def.enabled,
-      sections: def.sections, fields: def.fields, sourceTypes: def.sourceTypes, examples: def.examples,
+      sections: def.sections, fields: def.fields, examples: def.examples,
     })))
     const defaults = defaultWikiTypes()
     if (types.length !== defaults.length) return true
@@ -753,7 +752,6 @@ export class KnowledgeBases {
     const base = this.records.find(item => item.id === id)
     if (!base) return failure(emptyBase(id), 'BASE_NOT_FOUND', `知识库不存在: ${id}`, true)
     base.wikiTypes = defaultWikiTypes()
-    base.wikiSchemaMode = 'report'
     base.updatedAt = new Date().toISOString()
     await this.refreshOne(base)
     await this.persist()
@@ -783,7 +781,6 @@ export class KnowledgeBases {
       isDefault: base.isDefault,
       sourceTypes: base.sourceTypes.map(def => ({ ...def, sourceCount: stats?.sourceTypes?.[def.id] ?? 0 })),
       wikiTypes: base.wikiTypes.map(def => ({ ...def, cardCount: stats?.wikiTypes?.[def.id] ?? 0 })),
-      wikiSchemaMode: base.wikiSchemaMode,
       wikiTypesCustomized: this.wikiTypesDifferFromDefaults(base.wikiTypes),
       createdAt: base.createdAt,
       updatedAt: base.updatedAt,
@@ -804,7 +801,6 @@ export class KnowledgeBases {
       isDefault: true,
       sourceTypes: defaultSourceTypes(),
       wikiTypes: defaultWikiTypes(),
-      wikiSchemaMode: 'report',
       createdAt: now,
       updatedAt: now,
     }
@@ -869,7 +865,6 @@ export class KnowledgeBases {
       isDefault: value.isDefault === true || id === this.defaultId,
       sourceTypes: this.normalizeSourceTypes(value.sourceTypes),
       wikiTypes: this.normalizeWikiTypes(value.wikiTypes),
-      wikiSchemaMode: value.wikiSchemaMode === 'strict' ? 'strict' : 'report',
       createdAt: typeof value.createdAt === 'string' && value.createdAt ? value.createdAt : now,
       updatedAt: typeof value.updatedAt === 'string' && value.updatedAt ? value.updatedAt : now,
     }
@@ -880,18 +875,22 @@ export class KnowledgeBases {
   /**
    * 把磁盘上的 `sourceTypes` 规整成一个**必定包含全部内置分类**的合法注册表。
    *
-   * 两个关键行为：
+   * 三个关键行为：
    * 1. 老注册表（没有 `sourceTypes` 字段）升级时自动补上全部内置分类；
-   * 2. 任何缺失的内置分类都会被补回来——内置分类只允许停用，不允许删除。
+   * 2. 任何缺失的内置分类都会被补回来——内置分类只允许停用，不允许删除；
+   * 3. **改名过的内置分类按别名认**（`LEGACY_SOURCE_TYPE_IDS`）：存量配置里那一项写着
+   *    旧 id，不认的话它会被当成一个自定义分类留下来，而新的内置项同时被补回来 ——
+   *    于是「注册表里到底有什么」永远说不清。
    */
   private normalizeSourceTypes(raw: unknown): SourceTypeDef[] {
     const persisted = Array.isArray(raw) ? raw : []
     const byId = new Map<string, Record<string, unknown>>()
     for (const item of persisted) {
       const value = record(item)
-      const id = typeof value.id === 'string' ? value.id.trim() : ''
+      const rawId = typeof value.id === 'string' ? value.id.trim() : ''
+      const id = LEGACY_SOURCE_TYPE_IDS[rawId] ?? rawId
       if (!id || !SOURCE_TYPE_ID_PATTERN.test(id) || byId.has(id)) continue
-      byId.set(id, value)
+      byId.set(id, { ...value, id })
     }
     const defaults = defaultSourceTypes()
     const builtins = defaults.map(def => {
@@ -928,6 +927,8 @@ export class KnowledgeBases {
       enabled: base.fallback ? true : value.enabled !== false,
       builtin: base.builtin,
       fallback: base.fallback,
+      // 0048：元数据字段声明跟着分类走。缺省继承默认值（内置分类出厂没有声明）。
+      metadataFields: normalizeMetadataFields(value.metadataFields ?? base.metadataFields),
       sourceCount: 0,
     }
   }
@@ -983,6 +984,7 @@ export class KnowledgeBases {
         signals: (draft.signals as unknown[]).map(item => String(item).trim()).filter(Boolean),
         excludes: (draft.excludes as unknown[]).map(item => String(item).trim()).filter(Boolean),
         enabled: seed.fallback ? true : draft.enabled !== false,
+        metadataFields: normalizeMetadataFields(value.metadataFields ?? previous.metadataFields),
         sourceCount: 0,
       })
     }
@@ -1007,6 +1009,9 @@ export class KnowledgeBases {
         signals: (draft.signals as unknown[]).map(item => String(item).trim()).filter(Boolean),
         excludes: (draft.excludes as unknown[]).map(item => String(item).trim()).filter(Boolean),
         enabled: draft.enabled !== false, builtin: false, fallback: false, sourceCount: 0,
+        ...(normalizeMetadataFields(value.metadataFields ?? previous?.metadataFields).length > 0
+          ? { metadataFields: normalizeMetadataFields(value.metadataFields ?? previous?.metadataFields) }
+          : {}),
       })
     }
     if (keptCustoms.length > Math.max(0, MAX_SOURCE_TYPES - BUILTIN_SOURCE_TYPES.length)) {
@@ -1065,7 +1070,6 @@ export class KnowledgeBases {
         layer: value.layer === 'instance' ? 'instance' : previous.layer,
         sections: Array.isArray(value.sections) ? value.sections : previous.sections,
         fields: Array.isArray(value.fields) ? value.fields : previous.fields,
-        sourceTypes: Array.isArray(value.sourceTypes) ? value.sourceTypes : previous.sourceTypes,
         examples: Array.isArray(value.examples) ? value.examples : previous.examples,
       }
       const problem = validateWikiTypeText(draft)
@@ -1079,7 +1083,6 @@ export class KnowledgeBases {
         layer: draft.layer === 'instance' ? 'instance' : 'type',
         sections,
         fields,
-        sourceTypes: this.stringList(draft.sourceTypes),
         examples: this.stringList(draft.examples),
         template: templateCardFor(sections, fields),
         enabled: value.enabled === undefined ? previous.enabled : value.enabled !== false,
@@ -1098,7 +1101,6 @@ export class KnowledgeBases {
         layer: value.layer === 'instance' ? 'instance' : previous?.layer ?? 'type',
         sections: Array.isArray(value.sections) ? value.sections : previous?.sections ?? [],
         fields: Array.isArray(value.fields) ? value.fields : previous?.fields ?? [],
-        sourceTypes: Array.isArray(value.sourceTypes) ? value.sourceTypes : previous?.sourceTypes ?? [],
         examples: Array.isArray(value.examples) ? value.examples : previous?.examples ?? [],
       }
       const problem = previous ? validateWikiTypeText(draft) : validateWikiTypeDraft(draft, new Set(existing.map(def => def.id)))
@@ -1112,7 +1114,6 @@ export class KnowledgeBases {
         layer: draft.layer === 'instance' ? 'instance' : 'type',
         sections,
         fields,
-        sourceTypes: this.stringList(draft.sourceTypes),
         examples: this.stringList(draft.examples),
         template: templateCardFor(sections, fields),
         enabled: value.enabled === undefined ? previous?.enabled ?? true : value.enabled !== false,

package/src/layout.ts

@@ -14,7 +14,7 @@
  * <agentRoot>/
  *   domain_knowledge/          知识本身（唯一的真相来源，必须备份）
  *     <知识库 id>/             一个知识库 = 一棵独立的树（0021）
- *       01_source_truth/       SourceRaw：原始可追溯文档
+ *       01_source_raw/       SourceRaw：原始可追溯文档
  *       02_wiki/               Wiki 卡片（人可读的结论）
  *       03_compiled/           编译产物：wikiNotes / 向量 / 知识图谱
  *       05_diagnosis/          智能归因图谱（派生层，可重建）
@@ -33,7 +33,7 @@
  *
  * 1. **`domain_knowledge` 与 `output` / `tmp` 的边界是「能不能重建」**，不是
  *    「谁写的」。知识树里每一样东西要么是别的层重建出来的（`03_compiled`、
- *    `05_diagnosis`），要么是不可再生的原始记录（`01_source_truth`、`02_wiki`）——
+ *    `05_diagnosis`），要么是不可再生的原始记录（`01_source_raw`、`02_wiki`）——
  *    它们同属一个必须整体备份的单位，所以同在一棵树下、按知识库分叉。`output` 是
  *    **交付物**：转换出来的 Markdown 与图片，用户会把它拷走或录入知识库；`tmp` 是
  *    **中间态**：转换的工作目录与任务队列快照，删掉最多让一个未完成的任务失败。
@@ -319,10 +319,10 @@ export function intentRoot(agentRoot: string): string {
  * 的空壳（注册表 `create()` 就会先 `mkdir`），空壳不该让迁移误判为「目标已占用」。
  */
 export function looksLikeKnowledgeTree(path: string): boolean {
-  return existsSync(join(path, '01_source_truth')) || existsSync(join(path, '03_compiled'))
+  return existsSync(join(path, '01_source_raw')) || existsSync(join(path, '03_compiled'))
 }
 
-/** 旧布局的判据：`01_source_truth` 直接躺在被检查的目录下。 */
+/** 旧布局的判据：`01_source_raw` 直接躺在被检查的目录下。 */
 export function looksLikeLegacyKnowledgeRoot(path: string): boolean {
   if (!path) return false
   return basename(path) !== '' && looksLikeKnowledgeTree(path)

package/src/migrate.ts

@@ -4,7 +4,7 @@
  * ## 为什么要迁移
  *
  * 0029 之前，「知识树在哪」由用户直接设的那个 `rootDir` 决定，而它指向的是**知识树
- * 本身** —— `01_source_truth` 直接躺在它下面。新布局多了一层：`rootDir` 变成
+ * 本身** —— `01_source_raw` 直接躺在它下面。新布局多了一层：`rootDir` 变成
  * `agentRoot`，知识树退到 `<agentRoot>/domain_knowledge/<知识库 id>`。
  *
  * 也就是说，对**改过** `rootDir` 的用户，磁盘上那棵树的位置变了。数据不能跟着
@@ -43,7 +43,7 @@ import { knowledgeBaseRoot, looksLikeKnowledgeTree, memoryRoot, resourceRoot } f
  * `<agentRoot>/memory/<库 id>`，由 `migrateLegacyMemory` 负责搬。它留在这里会让
  * 知识树迁移把 `04_memory` 当成「一段知识」搬进新树 —— 那是搬错方向。
  */
-const LAYOUT_DIRS = ['01_source_truth', '02_wiki', '03_compiled', '05_diagnosis'] as const
+const LAYOUT_DIRS = ['01_source_raw', '02_wiki', '03_compiled', '05_diagnosis'] as const
 
 export interface MigrationOutcome {
   /** `skipped` 无事可做 / `moved` 搬成功 / `failed` 搬失败。 */

package/src/model-text.ts

@@ -0,0 +1,126 @@
+/**
+ * 把平台 `llm` 服务的 chunk 流收成一段文本（0044 实机验证第三批）。
+ *
+ * ## 为什么单独一个文件
+ *
+ * 它可以在没有 DSH 上下文的情况下被测试：喂一串假 chunk，看结论对不对。
+ * 这段逻辑躲在 `index.ts` 的接缝里时，唯一能验证它的方法是「真跑一次编译再看告警」——
+ * 而正是因为没人那样做，下面这个坑活了很久。
+ *
+ * ## 那个坑：模型失败**不是抛异常**，是一条 finish chunk
+ *
+ * `LlmRuntime.stream()` 的契约写得很清楚：adapter 选择、派发、迭代的失败都会变成
+ * **终结性的 `finish` chunk**（`reason.kind === 'error' | 'aborted'`，里面带
+ * `failure.code` / `failure.message`）。只有中间件、嵌套调用这类问题才抛。
+ *
+ * 第一版接缝只挑 `text-delta` 累加文本，于是：
+ *
+ * - 模型调用失败（比如默认模型那一行选错了 provider）→ 一个文本都没收到 → 收成空串；
+ * - 空串交给 JSON 解析 → 「模型输出不是 JSON 对象」；
+ * - **真正的失败原因（code / message）被丢掉了**，人看到的是「模型答非所问」，
+ *   而事实是「模型根本没被调到」。
+ *
+ * 这两种故障的处理方式完全不同：一个是改提示词，一个是去改设置。所以这里把
+ * finish chunk 读出来，并在没有任何文本时**主动抛**——抛出去的 message 会原样出现在
+ * `rebuild` 的告警里（`extractWithModel` 接到异常后写的是「模型抽取不可用：…」）。
+ */
+
+/** 平台 chunk 的最小形状。只声明这里用得到的字段，避免把平台类型引进来。 */
+interface StreamChunkLike {
+  type?: string
+  text?: string
+  reason?: { kind?: string; failure?: { code?: string; message?: string } }
+}
+
+/**
+ * 组一次模型请求。
+ *
+ * ## 为什么单独一个函数
+ *
+ * 实机验证时这里的形状错过两次，而**两次的错误信息都完全指不出这一点**：
+ *
+ * 1. `messages: [{ role: 'user', content: prompt }]`（content 是字符串）→ 平台在适配器里
+ *    对 content 调 `.some()`，整次调用以 `content.some is not a function` 失败。
+ *    那句话里既没有 `messages`，也没有 `content` 的类型要求。
+ * 2. **没有带 `sessionId`** → OpenCode 系的路由直接回
+ *    `400 MissingSessionID: Request is missing x-opencode-session`。
+ *    这个字段在 `GenerateOptions` 里是可选的，所以类型不报错；而它在
+ *    「路由与缓存亲和」这件事上是必需的（`dsh-opencode-session` 插件只在
+ *    `options.sessionId` 存在时才打那个头，没有就原样放过去）。
+ *
+ * 平台的 `RequestMessage.content` 是**内容块数组**（`[{ type: 'text', text }]`），
+ * 不是字符串。把这些形状固定到一个纯函数里，就有了唯一的去处，也能被测试钉住。
+ *
+ * ## `sessionId` 给什么值
+ *
+ * 知识编译不是一段对话，但它确实需要「同一批调用被路由到同一个后端」这个性质：
+ * 反复编译同一个知识库时，提示词里有大段的 wiki 类型定义与已有卡片清单，**亲和性直接
+ * 影响命中缓存的概率**。所以给一个**按知识库稳定**的值，而不是随机的 UUID。
+ *
+ * 用 `knowledge:<库 id>` 这个形状而不是裸库 id：它明确说出这不是一个会话，
+ * 排查的人一眼能看出这些调用是谁发的（同一个头的值还会出现在上游的日志里）。
+ */
+export function buildModelRequest(input: {
+  provider: string
+  model: string
+  system?: string
+  prompt: string
+  reasoningEffort?: string
+  /** 路由与缓存亲和的会话身份。知识编译用 `knowledge:<库 id>`。 */
+  sessionId: string
+}): {
+  provider: string
+  model: string
+  reasoningEffort?: string
+  system?: string
+  sessionId: string
+  messages: Array<{ role: 'user'; content: Array<{ type: 'text'; text: string }> }>
+} {
+  const { provider, model, system, prompt, reasoningEffort, sessionId } = input
+  return {
+    provider,
+    model,
+    ...(reasoningEffort ? { reasoningEffort } : {}),
+    ...(system ? { system } : {}),
+    sessionId,
+    messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
+  }
+}
+
+/**
+ * 收完一条模型流的文本。
+ *
+ * @param stream 平台 `llm.stream()` 返回的 chunk 流
+ * @returns 模型输出的全文（不做 trim —— 调用方可能要看空白，也方便断言）
+ * @throws 流以 error / aborted 结束时，抛出带 code 与 message 的错误；
+ *         流正常结束但一个字符都没有时，也抛 —— 「模型没说话」不是一次成功的调用。
+ */
+export async function collectModelText(stream: AsyncIterable<StreamChunkLike>): Promise<string> {
+  let text = ''
+  /** 流怎么结束的。用来区分「正常但空」「失败」「中止」三种情况。 */
+  let finish: string | undefined
+  let failure: { code?: string; message?: string } | undefined
+
+  for await (const chunk of stream) {
+    if (!chunk || typeof chunk !== 'object') continue
+    if (chunk.type === 'text-delta' && typeof chunk.text === 'string') {
+      text += chunk.text
+      continue
+    }
+    if (chunk.type === 'finish') {
+      finish = chunk.reason?.kind
+      if (finish === 'error' || finish === 'aborted') failure = chunk.reason?.failure
+    }
+  }
+
+  if (failure) {
+    const code = failure.code?.trim() || '未知错误码'
+    const message = failure.message?.trim() || '模型服务没有给出说明'
+    throw new Error(`模型调用失败（${code}）：${message}`)
+  }
+  if (text.length === 0) {
+    // 走到这里说明流正常结束（或者压根没有 finish 块）却没有一个字符。
+    throw new Error(`模型没有返回任何文本（结束原因：${finish ?? '没有收到 finish 块'}）`)
+  }
+  return text
+}