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

package/src/images.ts

@@ -0,0 +1,203 @@
+import { createHash } from 'node:crypto'
+import { readFile, stat } from 'node:fs/promises'
+import { basename, extname, join } from 'node:path'
+import { ASSETS_DIR, PUBLISHED_IMAGE_MARKER } from './layout.js'
+import { writeBufferAtomic, writeTextAtomic } from './fs-atomic.js'
+
+/** Maximum decoded image size accepted by `images.publish`. */
+export const MAX_PUBLISHED_IMAGE_BYTES = 20 * 1024 * 1024
+
+const IMAGE_FORMATS = [
+  { mimeType: 'image/png', extension: '.png' },
+  { mimeType: 'image/jpeg', extension: '.jpg' },
+  { mimeType: 'image/gif', extension: '.gif' },
+  { mimeType: 'image/webp', extension: '.webp' },
+  { mimeType: 'image/avif', extension: '.avif' },
+  { mimeType: 'image/bmp', extension: '.bmp' },
+  { mimeType: 'image/svg+xml', extension: '.svg' },
+] as const
+
+export class ImagePublishError extends Error {
+  constructor(readonly code: string, message: string, readonly suggestion?: string) {
+    super(message)
+    this.name = 'ImagePublishError'
+  }
+}
+
+export interface PublishKnowledgeImageInput {
+  filePath?: unknown
+  contentBase64?: unknown
+  filename?: unknown
+  mimeType?: unknown
+}
+
+export interface PublishedKnowledgeImage {
+  kb: string
+  filename: string
+  path: string
+  url: string
+  markdown: string
+  mimeType: string
+  bytes: number
+  sha256: string
+}
+
+function invalid(message: string, suggestion?: string): never {
+  throw new ImagePublishError('IMAGE_INVALID', message, suggestion)
+}
+
+function normalizeMimeType(value: string): string {
+  const mimeType = value.split(';', 1)[0]!.trim().toLowerCase()
+  return mimeType === 'image/jpg' ? 'image/jpeg' : mimeType
+}
+
+function detectImageMimeType(bytes: Buffer): string | undefined {
+  if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'image/png'
+  if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'image/jpeg'
+  if (bytes.length >= 6 && (bytes.toString('ascii', 0, 6) === 'GIF87a' || bytes.toString('ascii', 0, 6) === 'GIF89a')) return 'image/gif'
+  if (bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP') return 'image/webp'
+  if (bytes.length >= 12 && bytes.toString('ascii', 0, 2) === 'BM') return 'image/bmp'
+  if (bytes.length >= 12 && bytes.toString('ascii', 4, 8) === 'ftyp') {
+    const brands = bytes.toString('ascii', 8, Math.min(bytes.length, 32))
+    if (/(?:avif|avis)/.test(brands)) return 'image/avif'
+  }
+  // SVG is text, so recognize its root element after an optional XML declaration.
+  const text = bytes.toString('utf8', 0, Math.min(bytes.length, 4096)).replace(/^\uFEFF/, '').trimStart()
+  if (/^(?:<\?xml\b[^>]*>\s*)?<svg(?:\s|>)/i.test(text)) return 'image/svg+xml'
+  return undefined
+}
+
+function decodeBase64(value: string): { bytes: Buffer; declaredMimeType?: string } {
+  let encoded = value.trim()
+  let declaredMimeType: string | undefined
+  if (encoded.startsWith('data:')) {
+    const match = /^data:([^;,]+);base64,([\s\S]*)$/i.exec(encoded)
+    if (!match) invalid('content_base64 的 Data URI 格式无效。', '传标准 Base64，或传 data:image/png;base64,... 形式。')
+    declaredMimeType = normalizeMimeType(match[1]!)
+    encoded = match[2]!
+  }
+  encoded = encoded.replace(/\s+/g, '')
+  if (encoded.length > Math.ceil(MAX_PUBLISHED_IMAGE_BYTES * 4 / 3) + 8) {
+    throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`)
+  }
+  if (encoded.length % 4 === 1 || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}={0,2}|[A-Za-z0-9+/]{3}=?)?$/.test(encoded)) {
+    invalid('content_base64 不是有效的 Base64。')
+  }
+  const bytes = Buffer.from(encoded, 'base64')
+  if (bytes.length === 0) invalid('图片内容不能为空。')
+  if (bytes.length > MAX_PUBLISHED_IMAGE_BYTES) {
+    throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`)
+  }
+  if (bytes.toString('base64').replace(/=+$/, '') !== encoded.replace(/=+$/, '')) invalid('content_base64 不是有效的 Base64。')
+  return { bytes, ...(declaredMimeType ? { declaredMimeType } : {}) }
+}
+
+function safeFilename(value: unknown, fallback: string, extension: string): string {
+  const raw = typeof value === 'string' ? value.trim() : ''
+  const leaf = (raw.replace(/\\/g, '/').split('/').pop() ?? '').replace(/[\u0000-\u001f\u007f]/g, '')
+  const suppliedExtension = extname(leaf)
+  const stem = (suppliedExtension ? leaf.slice(0, -suppliedExtension.length) : leaf)
+    .replace(/[^\p{L}\p{N}._ -]/gu, '_')
+    .replace(/\s+/g, '-')
+    .replace(/^\.+$/, '')
+    .slice(0, 120)
+  return `${stem || fallback}${extension}`
+}
+
+async function readExisting(path: string): Promise<Buffer | undefined> {
+  try { return await readFile(path) } catch (cause) {
+    if ((cause as NodeJS.ErrnoException)?.code === 'ENOENT') return undefined
+    throw cause
+  }
+}
+
+/** Store one validated image using the knowledge assets content-hash bucket layout. */
+export async function publishKnowledgeImage(
+  rootDir: string,
+  kb: string,
+  input: PublishKnowledgeImageInput,
+): Promise<PublishedKnowledgeImage> {
+  const filePath = typeof input.filePath === 'string' ? input.filePath.trim() : ''
+  const base64 = typeof input.contentBase64 === 'string' ? input.contentBase64 : ''
+  if (Boolean(filePath) === Boolean(base64)) {
+    invalid('file_path 和 content_base64 必须且只能提供一个。')
+  }
+
+  let bytes: Buffer
+  let sourceName = ''
+  let dataUriMimeType: string | undefined
+  if (filePath) {
+    let details
+    try { details = await stat(filePath) } catch (cause) {
+      throw new ImagePublishError('IMAGE_SOURCE_NOT_FOUND', `图片文件无法读取：${cause instanceof Error ? cause.message : String(cause)}`)
+    }
+    if (!details.isFile()) throw new ImagePublishError('IMAGE_SOURCE_NOT_FILE', 'file_path 必须指向一个文件。')
+    if (details.size > MAX_PUBLISHED_IMAGE_BYTES) {
+      throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`)
+    }
+    try { bytes = await readFile(filePath) } catch (cause) {
+      throw new ImagePublishError('IMAGE_SOURCE_NOT_FOUND', `图片文件无法读取：${cause instanceof Error ? cause.message : String(cause)}`)
+    }
+    sourceName = basename(filePath)
+  } else {
+    const decoded = decodeBase64(base64)
+    bytes = decoded.bytes
+    dataUriMimeType = decoded.declaredMimeType
+  }
+
+  if (bytes.length === 0) invalid('图片内容不能为空。')
+  if (bytes.length > MAX_PUBLISHED_IMAGE_BYTES) {
+    throw new ImagePublishError('IMAGE_TOO_LARGE', `图片超过 ${MAX_PUBLISHED_IMAGE_BYTES / 1024 / 1024} MiB 限制。`)
+  }
+  const mimeType = detectImageMimeType(bytes)
+  if (!mimeType) invalid('文件内容不是支持的图片格式（PNG、JPEG、GIF、WebP、AVIF、BMP、SVG）。')
+  const declaredMimeType = typeof input.mimeType === 'string' && input.mimeType.trim()
+    ? normalizeMimeType(input.mimeType)
+    : dataUriMimeType
+  if (declaredMimeType && declaredMimeType !== mimeType) {
+    invalid(`声明的 MIME 类型 ${declaredMimeType} 与图片内容 ${mimeType} 不一致。`)
+  }
+
+  const format = IMAGE_FORMATS.find(item => item.mimeType === mimeType)!
+  const sha256 = createHash('sha256').update(bytes).digest('hex')
+  const bucket = sha256.slice(0, 12)
+  const filename = safeFilename(input.filename ?? sourceName, `image-${bucket}`, format.extension)
+  const assetDir = join(rootDir, ASSETS_DIR, bucket)
+  const assetPath = join(assetDir, filename)
+  let existing = await readExisting(assetPath)
+  let storedFilename = filename
+
+  // The established bucket uses only the first 12 hash characters. If that prefix and the
+  // supplied filename both collide with different bytes, add more hash characters instead of
+  // replacing the existing asset.
+  if (existing && !existing.equals(bytes)) {
+    const extension = format.extension
+    const stem = filename.slice(0, -extension.length)
+    storedFilename = `${stem}-${sha256.slice(12, 20)}${extension}`
+    existing = await readExisting(join(assetDir, storedFilename))
+    if (existing && !existing.equals(bytes)) {
+      storedFilename = `image-${sha256}${extension}`
+      existing = await readExisting(join(assetDir, storedFilename))
+    }
+  }
+
+  if (existing && !existing.equals(bytes)) {
+    throw new ImagePublishError('ASSET_NAME_COLLISION', '目标文件名已被不同内容占用，未覆盖现有图片。')
+  }
+  if (!existing?.equals(bytes)) await writeBufferAtomic(join(assetDir, storedFilename), bytes)
+  // Standalone hosted images have no SourceRaw or card by design. Keep that intent beside the
+  // asset so the orphan sweep does not mistake it for a disposable extraction artifact.
+  await writeTextAtomic(join(assetDir, PUBLISHED_IMAGE_MARKER), 'images.publish\n')
+  const relativePath = `${ASSETS_DIR}/${bucket}/${storedFilename}`
+  const url = `/knowledge/assets/${encodeURIComponent(kb)}/${relativePath.split('/').map(encodeURIComponent).join('/')}`
+  return {
+    kb,
+    filename: storedFilename,
+    path: relativePath,
+    url,
+    markdown: `![${storedFilename}](${url})`,
+    mimeType,
+    bytes: bytes.length,
+    sha256,
+  }
+}

package/src/index.ts

@@ -27,6 +27,7 @@ import {
   type ModelSeam,
 } from './runtime.js'
 import { unwrapGroup } from './settings-volatile.js'
+import { KnowledgeEnvironment } from './environment/service.js'
 import { DOC_PAGE_CHARS, DOC_PAGE_CHARS_MAX, documentContentPage } from './document-page.js'
 import type { ModelCall } from './extract-model.js'
 import { runWikiTrial, trialSummary } from './wiki-trial.js'
@@ -43,6 +44,7 @@ import type { DiagnosisRunRecord } from './diagnosis/types.js'
 import { KNOWLEDGE_SETTINGS_SCHEMA, SETTINGS_NAMESPACE } from './settings-schema.js'
 import { DEFAULT_KB_ID, KnowledgeBases } from './knowledge-bases.js'
 import type { KnowledgeQuery } from './knowledge.js'
+import { ImagePublishError, publishKnowledgeImage } from './images.js'
 import {
   applyConvert, CONVERT_SETTINGS_NAMESPACE, CONVERT_SETTINGS_SCHEMA, MOUNT_PATH as CONVERT_MOUNT_PATH,
   type ConvertHost,
@@ -515,7 +517,9 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
       },
     }
   }
+  let environment: KnowledgeEnvironment
   const runtimeOptions = (): KnowledgeRuntimeOptions => ({
+    environmentGuard: () => environment.requireReady(),
     // 0029：家当目录。配置里三个路径为空时，运行时从这里解析模型与解释器。
     resourceRoot: resourceRoot(config.agentRoot),
     // 0032：记忆段。默认库的记忆落在 `<agentRoot>/memory/default`，与知识树平级。
@@ -552,11 +556,19 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     // 0044：非默认库的 runtime 也要拿到模型接缝。只传 `config` 不够 —— 默认库走上面
     // 那个 `new KnowledgeRuntime(... runtimeOptions())`，别的库走注册表这条支路，
     // 两边必须都带上，否则「新建一个库 → 导入文档」静默变成规则抽取。
-    runtimeOptions: () => ({ modelSeam: modelSeamFor }),
+  runtimeOptions: () => ({ resourceRoot: resourceRoot(config.agentRoot), modelSeam: modelSeamFor, environmentGuard: () => environment.requireReady() }),
   })
   compileModelForBase = id => bases.compileModelOf(id)
   runtime.baseId = bases.defaultId
   activeKnowledgeBases = bases
+  environment = new KnowledgeEnvironment({
+    resourceRoot: resourceRoot(config.agentRoot),
+    snapshot: () => ({ config: runtime.config, paths: runtime.resourcePaths() }),
+    probe: kind => runtime.environmentProbe(kind),
+    reload: () => { runtime.reloadResources(); bases.reloadResources() },
+  })
+  // Startup checks imports and resource files; model inference runs on demand.
+  void environment.check(false).catch(() => undefined)
 
   type CompileModelCatalogItem = { provider: string; id: string; name: string; description?: string; available: boolean; current?: boolean }
   const compileModelCatalog = async (kbId: string): Promise<{
@@ -652,6 +664,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     const previousAgentRoot = config.agentRoot
     config = normalizeKnowledge(pluginConfig.knowledge)
     runtime.updateConfig(config)
+    bases.updateRuntimeConfig(config)
     /**
      * 转换设置挂在同一个 entry 上，volatile 事件需要让转换宿主重新读取。
      */
@@ -764,7 +777,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
   applyIntent(ctx, { intentRoot: () => intentRoot(config.agentRoot) })
 
   /**
-   * 需要本轮用户审批的写工具。
+   * 需要本轮用户审批的知识写工具。`images.publish` 只写入本地素材目录，按用户要求免审批。
    *
    * 0044 换过一批名字：`write_knowledge_card`（只接受已确认提议）退役了，因为正文现在
    * 只读、卡片由编译直接写入；`list_card_proposals` 也退役了，因为待办队列不存在了。
@@ -811,6 +824,31 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     })),
   })))
 
+  ctx.tools.register(tool(
+    'images.publish',
+    'Publish one local image into a knowledge base assets bucket without user approval. Pass exactly one of `file_path` or `content_base64` (standard Base64 or a data URI); optional `filename` overrides the stored name, and optional `mime_type` must match the file bytes. Supports PNG, JPEG, GIF, WebP, AVIF, BMP and SVG up to 20 MiB. Returns the local asset URL and Markdown image reference.',
+    {
+      file_path: { type: 'string', description: '宿主可读取的本地图片文件路径；与 content_base64 二选一' },
+      content_base64: { type: 'string', description: '图片的标准 Base64，或 data:image/...;base64,...；与 file_path 二选一' },
+      filename: { type: 'string', description: '可选文件名；默认使用 file_path 的文件名，Base64 输入默认 image-<hash>.<ext>' },
+      mime_type: { type: 'string', description: '可选 MIME 类型；必须与图片二进制内容一致' },
+      kb: { type: 'string', description: '知识库 id；省略时写入默认库' },
+    },
+    async args => withRuntime(args.kb, async target => {
+      try {
+        return success(await publishKnowledgeImage(target.rootDir, target.baseId, {
+          filePath: args.file_path,
+          contentBase64: args.content_base64,
+          filename: args.filename,
+          mimeType: args.mime_type,
+        }))
+      } catch (cause) {
+        if (cause instanceof ImagePublishError) return failure({}, cause.code, cause.message, false, cause.suggestion)
+        return failure({}, 'IMAGE_PUBLISH_FAILED', `图片写入失败：${cause instanceof Error ? cause.message : String(cause)}`, true)
+      }
+    }),
+  ))
+
   ctx.tools.register(tool('add_source', 'Add or update a SourceRaw document (原始可追溯文档). DSH requests one user approval before execution.', { title: { type: 'string' }, content: { type: 'string', required: true }, external_id: { type: 'string' }, metadata: { type: 'json' }, source_id: { type: 'string' }, allow_duplicate_title: { type: 'boolean', description: '默认 false：标题与已有来源重复时拒收（SOURCE_TITLE_DUPLICATED），要求改标题。传 true 才允许并存。' }, kb: { type: 'string' }, session_key: { type: 'string' }, task_id: { type: 'string' }, subtask_id: { type: 'string' }, run_id: { type: 'string' }, turn_id: { type: 'string' }, trace_id: { type: 'string' }, domain: { type: 'string' } }, async (args, exec) => withRuntime(args.kb, target => target.addSource({ title: args.title, content: args.content, externalId: args.external_id, metadata: args.metadata, sourceId: args.source_id, ...(args.allow_duplicate_title === true ? { allowDuplicateTitle: true } : {}), lineage: lineageOf(args, exec) })), {
     call: addSourceCallView,
     meta: (args, value) => addSourceMetaOf(args, dataOf(value)),
@@ -1003,6 +1041,19 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
           },
         ))
       } },
+      { kind: 'exact' as const, path: '/knowledge/environment', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        if (req.method !== 'GET') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '只支持 GET'))
+        return send(res, 200, success(environment.view()))
+      } },
+      { kind: 'exact' as const, path: '/knowledge/environment/prepare', handler: async (req: IncomingMessage, res: ServerResponse) => {
+        if (req.method !== 'POST') return send(res, 405, envelopeError('METHOD_NOT_ALLOWED', '只支持 POST'))
+        try {
+          const body = await readBody(req, 4000) as { action?: string; selection?: unknown } | null
+          if (body?.action === 'cancel') { environment.cancel(); return send(res, 200, success(environment.view())) }
+          if (body?.action !== 'check' && body?.action !== 'install') return send(res, 400, failure({}, 'ACTION_INVALID', 'action 必须是 check、install 或 cancel', false))
+          return send(res, 200, success(environment.start(body.action, body.selection)))
+        } catch (cause) { return send(res, 400, envelopeError('REQUEST_INVALID', cause instanceof Error ? cause.message : String(cause))) }
+      } },
       { kind: 'exact' as const, path: '/knowledge/embedding/health', handler: async (req: IncomingMessage, res: ServerResponse) => {
         const resolved = resolveBase(query(req).searchParams.get('kb'))
         if ('failure' in resolved) return sendEnvelope(res, resolved.failure)
@@ -2160,6 +2211,6 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
       } },
     ]
     const disposers = routes.map(register)
-    return () => { runtime.close(); for (const dispose of disposers) void dispose() }
+    return () => { environment.close(); runtime.close(); bases.closeAll(); for (const dispose of disposers) void dispose() }
   })
 }

package/src/knowledge-bases.ts

@@ -280,6 +280,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()
+  }
+
   // ------------------------------------------------------------- 统计刷新
 
   /**

package/src/knowledge.ts

@@ -21,22 +21,21 @@
  * 还把两个来源都抹了。**也不许删掉任何一条** —— 删了就没有「冲突」这件事了，
  * 而冲突本身是要给人看的信号。
  *
- * ## 身份就是判重键
+ * ## 稳定身份与判重键
  *
- * `id = k_<归一化文本的哈希>`。同一个事实无论来自哪份文档都得到同一个 id，于是
- * 「多来源支持」是**往同一行追加 sources**，而不是靠一条知识挂多个坐标。
- * 文本改了就是一个新 id —— 旧的那条**留着**（不许删），两条之间可以记一条 redirect。
+ * 新行使用 `k_<归一化文本的 SHA-256>`，存量 ID 保留。判重先比较归一化文本，
+ * 不把哈希相同当作事实相同。「多来源支持」往同一行追加版本证据。
+ * 人工编辑正文保留 ID 并增加内容版本；重新抽出不同文本则保留为另一条知识。
  *
  * ## 为什么存在记忆段
  *
  * Knowledge 不可重建：它是抽取产物 + 人的裁决。重跑一次抽取不会得到同样的结果，
- * 而人的裁决根本没有第二次。所以它和轴注册表同一个库（`<memoryDir>/knowledge.sqlite`）。
+ * 而人的裁决根本没有第二次。所以它与轴注册表共享经过属主、版本校验的 `knowledge.db`。
  */
 
-import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
 import { createHash } from 'node:crypto'
 import { loadSqlite, type SqliteDatabase } from './fts.js'
+import { KnowledgeDb } from './store/knowledge-db.js'
 
 /**
  * 一条 Knowledge 的**真值状态**。
@@ -93,6 +92,10 @@ export interface KnowledgeSource {
    * 「这条知识依据的是第 3 版，而那版已经被人改过了」。
    */
   toVersion?: number
+  /** Evidence changes do not change the truth state of the Knowledge. */
+  currentVersion?: number
+  evidenceStatus?: 'current' | 'historical' | 'unversioned' | 'missing' | 'human'
+  quoteInCurrentVersion?: boolean
   createdAt: string
 }
 
@@ -147,9 +150,12 @@ export interface KnowledgeCardRef {
  */
 export function normalizeKnowledge(text: string): string {
   return text
+    .normalize('NFKC')
     .toLowerCase()
     .replace(/\s+/g, '')
-    .replace(/[，。、；：？！,.;:?!"'“”‘’（）()【】\[\]《》<>—\-_/\\]/g, '')
+    // Operators, decimal points, signs and identifier separators carry meaning.
+    .replace(/[，。、；：？！,;:?!“”‘’]/g, '')
+    .replace(/\.$/g, '')
 }
 
 /** FNV-1a（32 位）：只用来生成稳定短 id，不用于任何安全目的。 */
@@ -172,7 +178,7 @@ function fnv1a(value: string): number {
  * 如果未来一个库混合多个 Scope 或有效期，必须先把 Scope/有效性纳入判重策略，再改变 id。
  */
 export function knowledgeId(text: string): string {
-  return `k_${fnv1a(normalizeKnowledge(text)).toString(36)}`
+  return `k_${createHash('sha256').update(normalizeKnowledge(text), 'utf8').digest('hex')}`
 }
 
 export interface KnowledgeIngest {
@@ -458,8 +464,9 @@ CREATE INDEX IF NOT EXISTS revision_blob_idx ON revision(blob_hash);
  */
 export class KnowledgeStore {
   private db: SqliteDatabase | null = null
+  private owner: KnowledgeDb | null = null
 
-  constructor(private readonly file: string) {}
+  constructor(private readonly file: string, private readonly shared?: SqliteDatabase) {}
 
   /**
    * 这个文件里有没有某张表。
@@ -481,14 +488,23 @@ export class KnowledgeStore {
     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)
+      // The retired source_type table can predate revision-bound evidence too.
+      if (!hasColumn(this.db, 'knowledge_sources', 'to_version')) {
+        this.db.exec('ALTER TABLE knowledge_sources ADD COLUMN to_version INTEGER')
+      }
       /*
        * 旧库的 `knowledge_sources` 带有已经撤掉的 `source_type NOT NULL` 列。
        * `CREATE TABLE IF NOT EXISTS` 不会改变旧表；如果直接继续，新的出处写入会因
        * 没有给这个列赋值而全部失败，表现成「抽取报告有知识，但 Knowledge 为 0」。
-       * 只重建这一张可派生关系表，保留正文与出处数据，并让迁移具备事务性。
+       * 只重建这一张出处表，保留原始证据数据，并让迁移具备事务性。
        */
       if (hasColumn(this.db, 'knowledge_sources', 'source_type')) {
         this.db.exec('BEGIN IMMEDIATE')
@@ -521,26 +537,26 @@ export class KnowledgeStore {
           throw cause
         }
       }
-      /*
-       * 0062 v2 补的列。老库（`CREATE TABLE IF NOT EXISTS` 对已存在的表是空操作）不会
-       * 自己长出它来，所以要显式 ALTER —— 与知识库文件「版本不符走迁移、不重建」同一政策。
-       */
-      if (!hasColumn(this.db, 'knowledge_sources', 'to_version')) {
-        this.db.exec('ALTER TABLE knowledge_sources ADD COLUMN to_version INTEGER')
-      }
       if (!hasColumn(this.db, 'knowledge', 'head_version')) {
         this.db.exec("ALTER TABLE knowledge ADD COLUMN head_version INTEGER NOT NULL DEFAULT 0")
       }
+      // Keep legacy IDs and references; replace only the lossy comparison key.
+      const reindex = this.db.prepare('UPDATE knowledge SET normalized = ? WHERE id = ?')
+      for (const row of this.db.prepare('SELECT id, text, normalized FROM knowledge').all() as Array<{ id: string; text: string; normalized: string }>) {
+        const normalized = normalizeKnowledge(row.text)
+        if (normalized !== row.normalized) reindex.run(normalized, row.id)
+      }
       this.backfillContentVersions()
       return true
     } catch {
+      this.owner?.close()
+      this.owner = null
       this.db = null
       return false
     }
   }
 
-  available(): boolean {    return this.db !== null
-  }
+  available(): boolean { return this.db !== null }
 
   /**
    * 为旧 Knowledge 行补首版。
@@ -613,9 +629,12 @@ export class KnowledgeStore {
     const text = input.text.trim()
     if (!text) throw new Error('KNOWLEDGE_TEXT_REQUIRED')
     const normalized = normalizeKnowledge(text)
-    const id = knowledgeId(text)
+    // Edited and migrated facts keep their identity. A hash is not proof of equality.
+    const match = this.db.prepare("SELECT id FROM knowledge WHERE normalized = ? AND merged_into = '' ORDER BY created_at, id LIMIT 1").get(normalized) as { id: string } | undefined
+    const id = match?.id ?? knowledgeId(text)
     const now = new Date().toISOString()
-    const existing = await this.get(id)
+    const existing = this.read(id)
+    if (existing !== null && normalizeKnowledge(existing.text) !== normalized) throw new Error('KNOWLEDGE_ID_COLLISION')
 
     if (existing === null) {
       this.db.exec('BEGIN')
@@ -627,7 +646,7 @@ export class KnowledgeStore {
           (input.objectId ?? '').trim(), (input.actionId ?? '').trim(), (input.sceneId ?? '').trim(),
           input.status ?? 'candidate', (input.runId ?? '').trim(), '', 0, now, now,
         )
-        const added = await this.appendSources(id, input.sources ?? [])
+        const added = this.appendSources(id, input.sources ?? [])
         this.appendContentVersion(id, text, {
           actor: input.actor ?? 'compiler',
           kind: input.revisionKind ?? 'auto',
@@ -636,7 +655,7 @@ export class KnowledgeStore {
         })
         this.db.prepare('UPDATE knowledge SET head_version = 1 WHERE id = ?').run(id)
         this.db.exec('COMMIT')
-        return { knowledge: (await this.get(id))!, merged: false, addedSources: added }
+        return { knowledge: this.read(id)!, merged: false, addedSources: added }
       } catch (cause) {
         this.db.exec('ROLLBACK')
         throw cause
@@ -664,7 +683,7 @@ export class KnowledgeStore {
         incomingCoordinate.objectId, incomingCoordinate.actionId, incomingCoordinate.sceneId, now, id,
       )
     }
-    const added = await this.appendSources(id, input.sources ?? [])
+    const added = this.appendSources(id, input.sources ?? [])
     if (existingHasCoordinate || !incomingHasCoordinate) {
       this.db.prepare('UPDATE knowledge SET updated_at = ? WHERE id = ?').run(now, id)
     }
@@ -713,25 +732,18 @@ export class KnowledgeStore {
   }
 
   /** 追加来源。返回这次真正加进去几条（去重之后）。 */
-  private async appendSources(id: string, sources: Array<Partial<KnowledgeSource>>): Promise<number> {
+  private appendSources(id: string, sources: Array<Partial<KnowledgeSource>>): number {
     if (sources.length === 0) return 0
-    const current = await this.get(id)
+    const current = this.read(id)
     const existingByKey = new Map((current?.sources ?? []).map(source => [sourceKey(source), source]))
     const seen = new Set(existingByKey.keys())
-    let ordinal = current?.sources.length ?? 0
+    let ordinal = Number((this.db!.prepare('SELECT COALESCE(MAX(ordinal), -1) + 1 AS n FROM knowledge_sources WHERE knowledge_id = ?').get(id) as { n: number }).n)
     let added = 0
     const now = new Date().toISOString()
     for (const source of sources) {
       const row = normalizeSource(source, now)
       const key = sourceKey(row)
       if (seen.has(key)) {
-        // 同一出处的来源版本是血缘元数据，不是新的 Knowledge 内容版本。
-        const previous = existingByKey.get(key)
-        if (row.toVersion !== undefined && previous?.toVersion !== row.toVersion) {
-          this.db!.prepare(
-            'UPDATE knowledge_sources SET to_version = ? WHERE knowledge_id = ? AND document_id = ? AND quote = ? AND author = ? AND statement = ?',
-          ).run(row.toVersion, id, row.documentId, row.quote, row.author, row.statement)
-        }
         continue
       }
       seen.add(key)
@@ -748,7 +760,10 @@ export class KnowledgeStore {
     return added
   }
 
-  async get(id: string): Promise<Knowledge | null> {    if (this.db === null) throw new Error('KNOWLEDGE_STORE_UNAVAILABLE')
+  async get(id: string): Promise<Knowledge | null> { return this.read(id) }
+
+  private read(id: string): Knowledge | null {
+    if (this.db === null) throw new Error('KNOWLEDGE_STORE_UNAVAILABLE')
     const row = this.db.prepare('SELECT * FROM knowledge WHERE id = ?').get(id) as Record<string, unknown> | undefined
     if (row === undefined) return null
     const sources = this.db.prepare(
@@ -1341,7 +1356,8 @@ export class KnowledgeStore {
   }
 
   close(): void {
-    this.db?.close()
+    this.owner?.close()
+    this.owner = null
     this.db = null
   }
 }
@@ -1447,7 +1463,7 @@ function hasColumn(db: { prepare: (sql: string) => { all: (...params: unknown[])
 
 function sourceKey(source: KnowledgeSource): string {
   return source.documentId
-    ? `d\u0001${source.documentId}\u0001${source.quote}`
+    ? `d\u0001${source.documentId}\u0001${source.toVersion ?? ''}\u0001${source.quote}`
     : `h\u0001${source.author}\u0001${source.statement}`
 }
 

package/src/layout.ts

@@ -381,6 +381,8 @@ export function intentRoot(agentRoot: string): string {
 export const KNOWLEDGE_DB_FILE = 'knowledge.db'
 export const DERIVED_DB_FILE = 'derived.db'
 export const ASSETS_DIR = 'assets'
+/** Hidden marker: standalone published images must survive source/card orphan sweeps. */
+export const PUBLISHED_IMAGE_MARKER = '.dsh-published-image'
 /**
  * 原始输入的落点（0067）。与 {@link ASSETS_DIR} **并列且同构**：一个装内容里提取出来的
  * 图，一个装用户送进来的原件 —— 两者都是「从这个知识库里能直接拿到手的东西」，

package/src/retrieval/vector-index.ts

@@ -0,0 +1,44 @@
+import type { KnowledgeConfig } from '../types.js'
+import type { DerivedDb } from '../store/derived.js'
+
+export interface VectorItem {
+  unitId: string
+  contentHash: string
+}
+
+export interface VectorManifest {
+  version: number
+  createdAt: string
+  provider: KnowledgeConfig['embeddingProvider']
+  model: string
+  modelFingerprint?: string
+  /**
+   * 编码实现的指纹（0031）。旧清单没有这个字段 → 视为不兼容，于是修复编码器之后
+   * 一定触发一次真正的重编码，而不是把旧向量按 contentHash 复用回来。
+   */
+  encoder?: string
+  device: string
+  dimension: number
+  quantization: 'binary+hamming+int8'
+  itemCount: number
+  items: VectorItem[]
+}
+
+export interface LoadedVectorIndex {
+  manifest: VectorManifest
+  binary: Buffer
+  int8: Buffer
+}
+
+/** Validate a generation's BLOBs before either reuse or query. */
+export function decodeVectorIndex(loaded: ReturnType<DerivedDb['vectorIndex']>, encoder: string): LoadedVectorIndex | null {
+  if (!loaded) return null
+  const manifest = loaded.manifest as VectorManifest
+  if (!manifest || manifest.quantization !== 'binary+hamming+int8' || manifest.encoder !== encoder
+    || !Number.isInteger(manifest.dimension) || manifest.dimension < 8 || manifest.dimension % 8 !== 0
+    || !Number.isInteger(manifest.itemCount) || !Array.isArray(manifest.items)
+    || manifest.itemCount !== manifest.items.length
+    || loaded.binary.length !== manifest.itemCount * Math.ceil(manifest.dimension / 8)
+    || loaded.int8.length !== manifest.itemCount * manifest.dimension) return null
+  return { ...loaded, manifest }
+}

package/src/retrieval/visibility.ts

@@ -0,0 +1,14 @@
+import type { ContextGraph } from '../types.js'
+import type { KnowledgeDb } from '../store/knowledge-db.js'
+
+export function liveGraphKeys(db: KnowledgeDb): Set<string> {
+  const rows = db.raw("SELECT entity_type AS type, entity_id AS id FROM card UNION SELECT 'source' AS type, entity_id AS id FROM source").all() as Array<{ type: string; id: string }>
+  return new Set(rows.map(row => `${row.type}:${row.id}`))
+}
+
+/** A retained generation must not restore entities that the user deleted. */
+export function visibleGraph(graph: ContextGraph, live: Set<string>): ContextGraph {
+  const nodes = graph.nodes.filter(node => live.has(`${node.type}:${node.id}`))
+  const keys = new Set(nodes.map(node => `${node.type}:${node.id}`))
+  return { nodes, edges: graph.edges.filter(edge => keys.has(String(edge.from)) && keys.has(String(edge.to))) }
+}