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

package/src/runtime.ts

@@ -44,7 +44,7 @@ import {
   RELATED_METADATA_KEY, type DeadLink, type RelatedEntry,
 } from './wiki-finalize.js'
 import { applyRerank, applyThreshold, evidenceExcerpts, graphBoost, matchOf, noteIndexText, reviewWeight, rrfFuse, tokenSet, type RouteRanking } from './recall-rank.js'
-import { ASSETS_DIR, KNOWLEDGE_DB_FILE, SOURCE_RAW_DIR, defaultAgentRoot, knowledgeBaseRoot } from './layout.js'
+import { ASSETS_DIR, KNOWLEDGE_DB_FILE, PUBLISHED_IMAGE_MARKER, SOURCE_RAW_DIR, defaultAgentRoot, knowledgeBaseRoot } from './layout.js'
 import { KnowledgeDb, type CardKnowledgeRow, type Journal as StoreJournal, type SourceOriginal } from './store/knowledge-db.js'
 import { exportKnowledgeTree as exportTree, migrateKnowledgeTree } from './store/migrate.js'
 import { COMPILE_SNAPSHOT, type CompileSnapshot } from './compiler/snapshot.js'
@@ -59,6 +59,8 @@ import { unlinkIfExists, writeBufferAtomic, writeTextAtomic } from './fs-atomic.
 import { envelopeFailure, envelopeSuccess } from 'dsh-data-contracts/envelope'
 import type { LineageContext, LineageRef } from 'dsh-data-contracts/refs'
 import { analyzeQuery, relationCandidates, type QueryAnalysis } from './query-analysis.js'
+import { readModelSelection, selectedEmbedding } from './environment/selection.js'
+import { rerankModel as rerankModelOption } from './environment/model-catalog.js'
 
 // **知识树只有三段**（v1.1 起）：`01_source_raw` / `02_wiki` / `03_compiled`。
 //
@@ -1719,8 +1721,8 @@ export interface WikiSchemaSnapshot {
 /**
  * 解析三个「家当」路径（0029）。
  *
- * 优先级：**配置里显式写的值**（由构造函数处理）> `<agentRoot>/resource/…`（存在时）
- * > 兜底（`python3` / HF 模型名）。
+ * 资源目录内的隔离解释器优先于 DSH_PYTHON；自定义配置路径仍由构造函数处理。
+ * 未准备资源时回退到 DSH_PYTHON、`python3` 或 HF 模型名。
  *
  * `modelId` 把本地模型的**身份**与它的位置解耦，避免同一 Agent 根目录下的
  * resource 目录变化导致向量清单误判为配置不匹配。
@@ -1729,6 +1731,7 @@ function resolveResources(resourceRoot: string | undefined): {
   python: string
   embeddingModel: string
   rerankModel: string
+  embeddingDimension?: number
   modelId: (path: string) => string
 } {
   const root = resourceRoot ? resolve(resourceRoot) : undefined
@@ -1739,14 +1742,20 @@ function resolveResources(resourceRoot: string | undefined): {
   const python = firstExisting([
     root && process.platform === 'win32' ? join(root, 'python', 'Scripts', 'python.exe') : undefined,
     root ? join(root, 'python', 'bin', 'python') : undefined,
-  ], 'python3')
+  ], process.env.DSH_PYTHON || 'python3')
+  const selected = selectedEmbedding(root)
+  const selection = root ? readModelSelection(root) : undefined
+  const selectedRerank = root && selection ? join(root, 'models', rerankModelOption(selection.rerank).directory) : undefined
   const embeddingModel = firstExisting([
+    selected?.path,
     root ? join(root, 'models', PREFERRED_LOCAL_EMBEDDING_MODEL_DIR) : undefined,
     root ? join(root, 'models', LOCAL_EMBEDDING_MODEL_DIR) : undefined,
   ], FALLBACK_EMBEDDING_MODEL)
   const rerankModel = firstExisting([
+    selectedRerank,
     root ? join(root, 'models', LOCAL_RERANK_MODEL_DIR) : undefined,
   ], FALLBACK_RERANK_MODEL)
+  const embeddingDimension = selected?.path && embeddingModel === selected.path ? selected.dimension : undefined
   const modelId = (path: string): string => {
     for (const base of [root]) {
       if (!base || !path.startsWith(`${base}${sep}`)) continue
@@ -1755,7 +1764,14 @@ function resolveResources(resourceRoot: string | undefined): {
     }
     return path
   }
-  return { python, embeddingModel, rerankModel, modelId }
+  return { python, embeddingModel, rerankModel, embeddingDimension, modelId }
+}
+
+/** An inherited DSH_PYTHON value selects the base interpreter, not the dependency environment. */
+function resolveConfiguredPython(configured: string | undefined, resourcePython: string): string {
+  const selected = configured?.trim()
+  const hostPython = process.env.DSH_PYTHON?.trim()
+  return selected && selected !== hostPython ? selected : resourcePython
 }
 
 export interface KnowledgeRuntimeOptions {
@@ -1773,7 +1789,7 @@ export interface KnowledgeRuntimeOptions {
    * 0029：家当目录（`<agentRoot>/resource`）。
    *
    * 配置里那三个路径字段（`python` / `embeddingModel` / `rerankModel`）为空时，
-   * 它们从这里解析。省略时使用系统命令或模型名作为兜底 —— 独立运行时与单元
+   * 它们从这里解析。省略时使用 DSH Python、系统命令或模型名作为兜底 —— 独立运行时与单元
    * 测试不必先造一个根路径。
    */
   resourceRoot?: string
@@ -2161,7 +2177,8 @@ export class KnowledgeRuntime {
     this.modelSeamProvider = options.modelSeam
     this.resourceRoot = options.resourceRoot
     const resources = resolveResources(options.resourceRoot)
-    this.pythonPath = config.python?.trim() || resources.python
+    if (!this.config.embeddingModel?.trim() && resources.embeddingDimension) this.config.embeddingDimension = resources.embeddingDimension
+    this.pythonPath = resolveConfiguredPython(config.python, resources.python)
     this.embeddingModelPath = config.embeddingModel?.trim() || resources.embeddingModel
     this.rerankModelPath = config.rerankModel?.trim() || resources.rerankModel
     this.embeddingModelId = resources.modelId(this.embeddingModelPath)
@@ -2201,6 +2218,10 @@ export class KnowledgeRuntime {
   updateConfig(patch: Partial<RuntimeKnowledgeConfig>): void {
     const previous = this.config
     this.config = { ...previous, ...patch }
+    const resources = resolveResources(this.resourceRoot)
+    // A managed model preset owns its output dimension. Custom model paths keep
+    // the advanced dimension setting from the plugin config.
+    if (!this.config.embeddingModel?.trim() && resources.embeddingDimension) this.config.embeddingDimension = resources.embeddingDimension
 
     const modelChanged =
       previous.embeddingProvider !== this.config.embeddingProvider ||
@@ -2227,8 +2248,7 @@ export class KnowledgeRuntime {
       this.rerankWorker = null
       this.rerankUnavailable = undefined
     }
-    const resources = resolveResources(this.resourceRoot)
-    if (patch.python !== undefined) this.pythonPath = patch.python.trim() || resources.python
+    this.pythonPath = resolveConfiguredPython(this.config.python, resources.python)
     if (patch.embeddingModel !== undefined) this.embeddingModelPath = patch.embeddingModel.trim() || resources.embeddingModel
     if (patch.rerankModel !== undefined) this.rerankModelPath = patch.rerankModel.trim() || resources.rerankModel
     this.embeddingModelId = resources.modelId(this.embeddingModelPath)
@@ -7454,7 +7474,7 @@ export class KnowledgeRuntime {
     const cardOrphans = cards.filter(card => card.sourceRefs.every(ref => !live.has(ref))).length
     const events = (await this.loadEvents()).filter(event => event.records.some(record => !live.has(record.sourceId))).length
     /**
-     * 图片也进这张账（2026-10-05）。
+     * 未被引用的来源图片也进这张账（2026-10-05）。`images.publish` 写入的独立图片会被识别并保留。
      *
      * 少了它，「来源与卡片都清完了、只剩一堆没人引用的图」这种状态在界面上**一个字都没有**
      * —— 清理孤儿的入口因此不出现，而用户唯一能看到的读数（「收录 N 个文件」）又把它算成
@@ -7462,7 +7482,7 @@ export class KnowledgeRuntime {
      * 「按一下能清掉几个」是同几个。
      */
     const names = await this.assetBucketNames()
-    const assets = names.length === 0 ? 0 : this.unreferencedBuckets(names, sources, cards).length
+    const assets = names.length === 0 ? 0 : (await this.unreferencedBuckets(names, sources, cards)).length
     return { knowledge, cards: cardOrphans, events, assets }
   }
 
@@ -7490,8 +7510,9 @@ export class KnowledgeRuntime {
   }
 
   /**
-   * 还有没有人在引用这个桶 —— 判据是**三处文本里出现过 `_assets/<bucket>/`**：
-   * 来源正文、来源 front matter 的 `metadata.assets`、卡片正文。
+   * 还有没有人在引用这个桶 —— 判据是来源正文、来源 front matter 的 `metadata.assets`、
+   * 卡片正文出现过 `_assets/<bucket>/`，或者它是 `images.publish` 写入的独立图床图片。
+   * 独立图片没有来源/卡片引用是正常状态，必须保留。
    *
    * 为什么三处都要看：桶名是**内容哈希的前 12 位**（`convert/ingest.ts`），不是来源 id。
    * 同一份内容以两个分类导入会共用同一个桶；而卡片正文会把图片引用**复制进去**
@@ -7499,7 +7520,7 @@ export class KnowledgeRuntime {
    *
    * 不看 `03_compiled/`：那是派生物，下一次 `rebuild` 会把指向已删图片的引用一起扔掉。
    */
-  private unreferencedBuckets(names: string[], sources: SourceRaw[], cards: KnowledgeCard[]): string[] {
+  private async unreferencedBuckets(names: string[], sources: SourceRaw[], cards: KnowledgeCard[]): Promise<string[]> {
     const referenced = new Set<string>()
     /**
      * **两种引用形式都算**：`assets/<桶>/`（新写的）与 `_assets/<桶>/`（存量）。
@@ -7518,7 +7539,38 @@ export class KnowledgeRuntime {
       if (Array.isArray(source.metadata.assets)) for (const item of source.metadata.assets) if (typeof item === 'string') collect(item)
     }
     for (const card of cards) collect(card.content)
-    return names.filter(name => !referenced.has(name))
+    const unreferenced: string[] = []
+    for (const name of names) {
+      if (referenced.has(name)) continue
+      if (await this.isPublishedImageBucket(name)) continue
+      unreferenced.push(name)
+    }
+    return unreferenced
+  }
+
+  /**
+   * `images.publish` 的图片不需要被来源或卡片引用。新写入的桶有明确标记；同时兼容
+   * 标记加入前已发布的图片：它们以图片自身的 SHA-256 前 12 位作为桶名。
+   */
+  private async isPublishedImageBucket(name: string): Promise<boolean> {
+    for (const root of this.assetRoots()) {
+      if (existsSync(join(root, name, PUBLISHED_IMAGE_MARKER))) return true
+    }
+
+    // 旧版本 images.publish 只会写入知识库根目录的 assets/，因此只在这里做哈希识别。
+    if (!/^[a-f0-9]{12}$/i.test(name)) return false
+    const dir = join(this.rootDir, ASSETS_DIR, name)
+    try {
+      for (const entry of await readdir(dir, { withFileTypes: true })) {
+        if (!entry.isFile() || !/\.(?:png|jpe?g|gif|webp|avif|bmp|svg)$/i.test(entry.name)) continue
+        const path = join(dir, entry.name)
+        const details = await stat(path)
+        if (details.size > 20 * 1024 * 1024) continue
+        const bytes = await readFile(path)
+        if (createHash('sha256').update(bytes).digest('hex').slice(0, 12) === name) return true
+      }
+    } catch { /* 桶目录可能在扫描期间被删除 */ }
+    return false
   }
 
   /**
@@ -7588,7 +7640,7 @@ export class KnowledgeRuntime {
     if (names.length === 0) return { buckets: 0, files: 0, problems: [] }
     const problems: string[] = []
     const cards = this.cards.length > 0 ? this.cards : await this.loadCards()
-    const doomed = this.unreferencedBuckets(names, await this.loadSources(), cards)
+    const doomed = await this.unreferencedBuckets(names, await this.loadSources(), cards)
     let buckets = 0
     let files = 0
     for (const name of doomed) {

package/src/store/migrate.ts

@@ -35,7 +35,7 @@
 import { existsSync } from 'node:fs'
 import { cp, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative } from 'node:path'
-import { ASSETS_DIR, SOURCE_RAW_DIR } from '../layout.js'
+import { ASSETS_DIR, PUBLISHED_IMAGE_MARKER, SOURCE_RAW_DIR } from '../layout.js'
 import type { KnowledgeCard, SourceRaw } from '../types.js'
 import type { KnowledgeDb } from './knowledge-db.js'
 
@@ -300,7 +300,7 @@ export async function migrateKnowledgeTree(input: MigrationInput): Promise<Migra
     const to = join(kbRoot, ASSETS_DIR, bucket)
     report.assetBuckets += 1
     if (dryRun) {
-      report.assetFiles += (await listFiles(from, '')).length
+      report.assetFiles += (await listFiles(from, '')).filter(path => basename(path) !== PUBLISHED_IMAGE_MARKER).length
       continue
     }
     try {
@@ -316,7 +316,7 @@ export async function migrateKnowledgeTree(input: MigrationInput): Promise<Migra
        */
       if (!existsSync(to)) await rename(from, to)
       else await mergeAssetBucket(from, to)
-      report.assetFiles += (await listFiles(to, '')).length
+      report.assetFiles += (await listFiles(to, '')).filter(path => basename(path) !== PUBLISHED_IMAGE_MARKER).length
     } catch (cause) {
       problems.push(`搬不动图片桶 ${bucket}：${cause instanceof Error ? cause.message : String(cause)}`)
     }
@@ -565,7 +565,7 @@ async function copyContentTree(from: string, to: string, overwrite: boolean): Pr
     if (!overwrite && existsSync(target)) continue
     await mkdir(dirname(target), { recursive: true })
     await cp(source, target, { force: true })
-    copied += 1
+    if (basename(source) !== PUBLISHED_IMAGE_MARKER) copied += 1
   }
   return copied
 }

package/src/types.ts

@@ -130,7 +130,7 @@ export interface KnowledgeConfig {
    * 组织（表达层）。两步都开着才是完整的「Knowledge Compiler + Wiki Materializer」。
    */
   cardOrganize: boolean
-  /** Python 解释器。空串 = 自动（`<agentRoot>/resource/python/bin/python`，再退回 `python3`）。 */
+  /** Python 解释器。空串 = 自动（隔离依赖环境，再退回 `DSH_PYTHON` / `python3`）。 */
   python: string
   embeddingProvider: EmbeddingProvider
   embeddingBaseUrl: string
@@ -231,10 +231,9 @@ export const DEFAULT_KNOWLEDGE_CONFIG: RuntimeKnowledgeConfig = {
   // 卡片组织（模型）默认**开**：Knowledge 只是事实层，Wiki 卡片正文必须经过这一步
   // 物化成可读的表达。只有显式写 `false` / `0` 才关闭兼容路径。
   cardOrganize: !['false', '0'].includes((process.env.DSH_KNOWLEDGE_CARD_ORGANIZE ?? '').trim().toLowerCase()),
-  // 0029：三个「家当」路径的默认值是**空串 = 自动**。它们跟着 `<agentRoot>/resource/`
-  // 走，而 agentRoot 由设置决定、模块加载时还不知道 —— 所以在运行时解析
-  // （`runtime.ts` 的 `resolveResources`）。环境变量仍然优先。
-  python: process.env.DSH_PYTHON || '',
+  // 0029：空串 = 自动。优先用 `<agentRoot>/resource/python/` 的隔离依赖环境；
+  // DSH_PYTHON 只作为创建该环境的基础解释器和未准备时的运行时回退。
+  python: '',
   embeddingProvider: 'wemm-python',
   embeddingBaseUrl: process.env.DSH_EMBEDDING_BASE_URL || 'http://127.0.0.1:11434',
   embeddingModel: process.env.DSH_EMBEDDING_MODEL || process.env.DSH_EMBEDDING_MODEL_PATH || '',