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

package/src/environment/model-catalog.ts

@@ -0,0 +1,105 @@
+/** Models supported by the local embedding and reranking workers. Revisions are pinned in manifest.ts. */
+export const EMBEDDING_MODELS = [
+  {
+    id: 'bge-small-zh-v1.5', repo: 'BAAI/bge-small-zh-v1.5', directory: 'bge-small-zh-v1.5',
+    label: 'BGE Small 中文', dimension: 512, download: '约 96 MB',
+    description: '资源占用最低，适合先跑通本地知识检索。',
+  },
+  {
+    id: 'bge-base-zh-v1.5', repo: 'BAAI/bge-base-zh-v1.5', directory: 'bge-base-zh-v1.5',
+    label: 'BGE Base 中文', dimension: 768, download: '约 409 MB',
+    description: '效果与资源占用较均衡。',
+  },
+  {
+    id: 'bge-large-zh-v1.5', repo: 'BAAI/bge-large-zh-v1.5', directory: 'bge-large-zh-v1.5',
+    label: 'BGE Large 中文', dimension: 1024, download: '约 1.3 GB',
+    description: '中文向量效果优先，需要更多内存与磁盘。',
+  },
+  {
+    id: 'wemm-embedding-2b-quantized', repo: 'ewin-reg/WeMM-Embedding-2B-Quantized', directory: 'WeMM-Embedding-2B-Quantized',
+    label: 'WeMM Embedding 2B 社区量化版', dimension: 2048, download: '约 1.8 GB',
+    description: '社区维护的 INT4 / FP8 量化模型，非腾讯官方发布；模型卡标注 license: other，请查看协议。',
+  },
+  {
+    id: 'wemm-embedding-2b', repo: 'tencent/WeMM-Embedding-2B', directory: 'WeMM-Embedding-2B',
+    label: '腾讯 WeMM Embedding 2B（BF16）', dimension: 2048, download: '约 5.5 GB',
+    description: '多模态向量模型，支持文本和图片；下载与推理资源占用较高。',
+  },
+] as const
+
+export const RERANK_MODELS = [
+  {
+    id: 'bge-reranker-base', repo: 'BAAI/bge-reranker-base', directory: 'bge-reranker-base',
+    label: 'BGE Reranker Base', download: '约 1.1 GB',
+    description: '中文重排的轻量选项。',
+  },
+  {
+    id: 'qwen3-reranker-0.6b', repo: 'Qwen/Qwen3-Reranker-0.6B', directory: 'Qwen3-Reranker-0.6B',
+    label: 'Qwen3 Reranker 0.6B', download: '约 1.2 GB',
+    description: '支持 100 多种语言，适合先试用 Qwen 重排。',
+  },
+  {
+    id: 'bge-reranker-large', repo: 'BAAI/bge-reranker-large', directory: 'bge-reranker-large',
+    label: 'BGE Reranker Large', download: '约 2.2 GB',
+    description: '中文和英文重排效果优先，推理速度较慢。',
+  },
+  {
+    id: 'qwen3-reranker-4b', repo: 'Qwen/Qwen3-Reranker-4B', directory: 'Qwen3-Reranker-4B',
+    label: 'Qwen3 Reranker 4B', download: '约 8.1 GB',
+    description: 'Qwen 中档重排模型；请先确认磁盘与内存充足。',
+  },
+  {
+    id: 'qwen3-reranker-8b', repo: 'Qwen/Qwen3-Reranker-8B', directory: 'Qwen3-Reranker-8B',
+    label: 'Qwen3 Reranker 8B', download: '约 16.4 GB',
+    description: '资源占用最高；下载前请确认有足够磁盘与内存。',
+  },
+] as const
+
+export type EmbeddingModelId = (typeof EMBEDDING_MODELS)[number]['id']
+export type RerankModelId = (typeof RERANK_MODELS)[number]['id']
+export interface ModelSelection { embedding: EmbeddingModelId; rerank: RerankModelId }
+export interface ModelOptionView {
+  id: string
+  label: string
+  dimension?: number
+  download: string
+  description: string
+  modelCardUrl?: string
+}
+export const DEFAULT_MODEL_SELECTION: ModelSelection = {
+  embedding: 'bge-small-zh-v1.5',
+  rerank: 'bge-reranker-base',
+}
+
+export function isModelSelection(value: unknown): value is ModelSelection {
+  if (!value || typeof value !== 'object') return false
+  const selection = value as Record<string, unknown>
+  return EMBEDDING_MODELS.some(model => model.id === selection.embedding)
+    && RERANK_MODELS.some(model => model.id === selection.rerank)
+}
+
+export function parseModelSelection(value: unknown, fallback = DEFAULT_MODEL_SELECTION): ModelSelection {
+  if (value === undefined || value === null) return { ...fallback }
+  if (!isModelSelection(value)) throw new Error('模型选择无效，请重新选择向量模型和重排模型')
+  return { embedding: value.embedding, rerank: value.rerank }
+}
+
+export function embeddingModel(id: EmbeddingModelId) {
+  return EMBEDDING_MODELS.find(model => model.id === id)!
+}
+
+export function rerankModel(id: RerankModelId) {
+  return RERANK_MODELS.find(model => model.id === id)!
+}
+
+export function modelOptionsView() {
+  const present = <T extends { id: string; label: string; download: string; description: string; repo: string }>(model: T) => ({
+    id: model.id, label: model.label, download: model.download, description: model.description,
+    modelCardUrl: `https://huggingface.co/${model.repo}`,
+    ...('dimension' in model ? { dimension: model.dimension as number } : {}),
+  })
+  return {
+    embedding: EMBEDDING_MODELS.map(present),
+    rerank: RERANK_MODELS.map(present),
+  }
+}

package/src/environment/selection.ts

@@ -0,0 +1,29 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { mkdir, rename, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { DEFAULT_MODEL_SELECTION, embeddingModel, isModelSelection, type ModelSelection } from './model-catalog.js'
+
+export const MODEL_SELECTION_FILE = 'environment-model-selection.json'
+
+export function readModelSelection(resourceRoot: string): ModelSelection {
+  try {
+    const value: unknown = JSON.parse(readFileSync(join(resourceRoot, MODEL_SELECTION_FILE), 'utf8'))
+    if (isModelSelection(value)) return { embedding: value.embedding, rerank: value.rerank }
+  } catch { /* first install or damaged selection: use the shipped defaults */ }
+  return { ...DEFAULT_MODEL_SELECTION }
+}
+
+export function selectedEmbedding(resourceRoot: string | undefined): { path?: string; dimension?: number } {
+  if (!resourceRoot) return {}
+  const model = embeddingModel(readModelSelection(resourceRoot).embedding)
+  const path = join(resourceRoot, 'models', model.directory)
+  return existsSync(path) ? { path, dimension: model.dimension } : {}
+}
+
+export async function writeModelSelection(resourceRoot: string, selection: ModelSelection): Promise<void> {
+  await mkdir(resourceRoot, { recursive: true })
+  const destination = join(resourceRoot, MODEL_SELECTION_FILE)
+  const temporary = `${destination}.${process.pid}.tmp`
+  await writeFile(temporary, `${JSON.stringify(selection, null, 2)}\n`, 'utf8')
+  await rename(temporary, destination)
+}

package/src/environment/service.ts

@@ -5,8 +5,10 @@ import { dirname, isAbsolute, join } from 'node:path'
 import { embeddingFingerprint } from '../compiler/embedding-identity.js'
 import type { RuntimeKnowledgeConfig } from '../types.js'
 import { installRequiredEnvironment, requirementsFile } from './install.js'
-import { ENVIRONMENT_PROBE_VERSION, PYTHON_PROBE } from './manifest.js'
+import { modelOptionsView, parseModelSelection, type ModelSelection } from './model-catalog.js'
+import { ENVIRONMENT_PROBE_VERSION } from './manifest.js'
 import { runProcess } from './process.js'
+import { readModelSelection, writeModelSelection } from './selection.js'
 import type { EnvironmentItem, EnvironmentItemId, EnvironmentReport, EnvironmentView } from './types.js'
 
 export interface EnvironmentOptions {
@@ -18,11 +20,22 @@ export interface EnvironmentOptions {
   install?: typeof installRequiredEnvironment
 }
 
-const labels = { python: 'Python 运行环境', embedding: '向量模型', rerank: '重排模型' }
+const labels = { embedding: '向量模型', rerank: '重排模型' }
 function blankReport(): EnvironmentReport {
-  return { state: 'unchecked', required: true, items: (['python', 'embedding', 'rerank'] as const).map(id => ({ id, label: labels[id], state: 'unchecked', message: '首次使用前必须完成环境自检' })) }
+  return { state: 'unchecked', required: true, items: (['embedding', 'rerank'] as const).map(id => ({ id, label: labels[id], state: 'unchecked', message: '首次使用前必须完成模型推理自检' })) }
 }
 function stamp(path: string): unknown { try { const value = statSync(path); return [value.size, value.mtimeMs] } catch { return null } }
+function sitePackagesPath(pythonPath: string): string {
+  const environmentRoot = dirname(dirname(pythonPath))
+  const windows = join(environmentRoot, 'Lib', 'site-packages')
+  try { if (statSync(windows).isDirectory()) return windows } catch { /* use the platform-neutral lib layout */ }
+  const libraryRoot = join(environmentRoot, 'lib')
+  try {
+    const versionDirectory = readdirSync(libraryRoot).find(name => /^python\d+\.\d+$/.test(name))
+    if (versionDirectory) return join(libraryRoot, versionDirectory, 'site-packages')
+  } catch { /* no venv/site-packages directory */ }
+  return join(libraryRoot, 'site-packages')
+}
 
 export function modelFilesProblem(path: string): string | undefined {
   if (!isAbsolute(path)) return '尚未准备本地模型，请安装默认资源或填写已下载模型的完整路径'
@@ -55,13 +68,14 @@ export class KnowledgeEnvironment {
       probe: ENVIRONMENT_PROBE_VERSION, paths,
       provider: config.embeddingProvider, rerank: config.rerankProvider, device: config.embeddingDevice, dimension: config.embeddingDimension, endpoint: config.embeddingBaseUrl,
       embedding: embeddingFingerprint(paths.embeddingModel, this.options.resourceRoot), rerankModel: embeddingFingerprint(paths.rerankModel, this.options.resourceRoot),
-      python: stamp(paths.python), venv: stamp(join(env, 'pyvenv.cfg')), dependencies: stamp(join(env, 'lib', 'python3.11', 'site-packages')), requirements: stamp(requirementsFile),
+      python: stamp(paths.python), venv: stamp(join(env, 'pyvenv.cfg')), dependencies: stamp(sitePackagesPath(paths.python)), requirements: stamp(requirementsFile),
     })).digest('hex')
   }
 
   view(): EnvironmentView {
     if (!this.checkPending && this.report.state === 'ready' && this.report.fingerprint !== this.fingerprint()) this.report = blankReport()
-    return structuredClone({ report: this.report, ...(this.job ? { job: this.job } : {}) })
+    const selection = readModelSelection(this.options.resourceRoot)
+    return structuredClone({ report: this.report, selection, models: modelOptionsView(), ...(this.job ? { job: this.job } : {}) })
   }
   invalidate(): void { if (!this.checkPending) this.report = blankReport() }
 
@@ -94,20 +108,6 @@ export class KnowledgeEnvironment {
     const { config, paths } = this.options.snapshot()
     this.report = blankReport()
     this.report.state = 'checking'
-    this.item('python', { state: 'checking', path: paths.python, message: '检查解释器与依赖' })
-    let pythonReady = false
-    try {
-      const output = await (this.options.run ?? runProcess)(paths.python, ['-c', PYTHON_PROBE], { signal, timeoutMs: 60_000 })
-      const line = output.split(/\r?\n/).filter(line => line.startsWith('{')).pop()
-      const result = JSON.parse(line ?? '{}') as { version?: number[]; missing?: string[] }
-      if (!result.version || result.version[0] !== 3 || result.version[1]! < 10 || result.version[1]! >= 14) throw new Error('需要 Python 3.10–3.13，默认安装 Python 3.11')
-      if (!Array.isArray(result.missing)) throw new Error('Python 自检返回格式不完整')
-      if (result.missing.length) throw new Error(`依赖缺失或无法导入：${result.missing.join('；')}`)
-      pythonReady = true
-      this.item('python', { state: 'ready', message: `Python ${result.version.join('.')} 与推理依赖可用` })
-    } catch (cause) {
-      this.item('python', { state: 'failed', message: cause instanceof Error ? cause.message : String(cause) })
-    }
     for (const id of ['embedding', 'rerank'] as const) {
       if (signal.aborted || this.disposed) break
       const path = id === 'embedding' ? paths.embeddingModel : paths.rerankModel
@@ -116,7 +116,6 @@ export class KnowledgeEnvironment {
       const problem = disabled ? '此能力是必需项，请启用模型'
         : id === 'embedding' && config.embeddingProvider === 'ollama' ? undefined : modelFilesProblem(path)
       if (problem) { this.item(id, { state: 'missing', message: problem }); continue }
-      if (!pythonReady) { this.item(id, { state: 'unchecked', message: '先修复 Python，再检查模型推理' }); continue }
       if (!deep) { this.item(id, { state: 'unchecked', message: '资源已找到，尚未完成实际推理自检' }); continue }
       this.item(id, { state: 'checking', message: '加载模型并运行推理自检，首次加载可能较慢' })
       try {
@@ -125,8 +124,12 @@ export class KnowledgeEnvironment {
       } catch (cause) { this.item(id, { state: 'failed', message: cause instanceof Error ? cause.message : String(cause) }) }
     }
     const changed = fingerprint !== this.fingerprint()
-    if (changed) this.item('python', { state: 'unchecked', message: '自检期间配置或资源发生变化，请重新自检' })
-    if (signal.aborted || this.disposed) this.item('python', { state: 'unchecked', message: '自检已停止，请重新运行' })
+    if (changed) this.report.items = this.report.items.map(item => item.state === 'ready'
+      ? { ...item, state: 'unchecked', message: '自检期间配置或资源发生变化，请重新自检' }
+      : item)
+    if (signal.aborted || this.disposed) this.report.items = this.report.items.map(item => item.state === 'checking'
+      ? { ...item, state: 'unchecked', message: '自检已停止，请重新运行' }
+      : item)
     this.report.state = this.report.items.every(item => item.state === 'ready') ? 'ready' : 'blocked'
     this.report.checkedAt = new Date().toISOString()
     this.report.fingerprint = fingerprint
@@ -134,9 +137,13 @@ export class KnowledgeEnvironment {
     return structuredClone(this.report)
   }
 
-  start(action: 'check' | 'install'): EnvironmentView {
+  start(action: 'check' | 'install', requestedSelection?: unknown): EnvironmentView {
     if (this.disposed) throw new Error('环境服务已关闭')
     if (this.job?.state === 'running') return this.view()
+    const previousSelection = readModelSelection(this.options.resourceRoot)
+    const selection: ModelSelection = action === 'install'
+      ? parseModelSelection(requestedSelection, previousSelection)
+      : previousSelection
     this.checkController?.abort()
     this.controller = new AbortController()
     const controller = this.controller
@@ -154,9 +161,9 @@ export class KnowledgeEnvironment {
           await (this.options.install ?? installRequiredEnvironment)(this.options.resourceRoot, controller.signal, label => {
             job.stage = label
             for (const item of this.report.items) if (item.state === 'checking') this.item(item.id, { state: 'unchecked', message: '准备步骤已完成，等待实际自检' })
-            const id = label.includes('向量') ? 'embedding' : label.includes('重排') ? 'rerank' : 'python'
-            this.item(id, { state: 'checking', message: label })
-          }, log)
+            const id = label.includes('向量') ? 'embedding' : label.includes('重排') ? 'rerank' : undefined
+            if (id) this.item(id, { state: 'checking', message: label })
+          }, log, this.options.run ?? runProcess, selection)
           this.options.reload()
         } else this.options.reload()
         job.stage = '运行实际推理自检'
@@ -167,6 +174,19 @@ export class KnowledgeEnvironment {
         await writeFile(join(this.options.resourceRoot, 'environment-last-check.json'), JSON.stringify(report, null, 2))
         job.state = 'succeeded'; job.stage = '环境已就绪'
       } catch (cause) {
+        if (action === 'install') {
+          const activeSelection = readModelSelection(this.options.resourceRoot)
+          if (activeSelection.embedding !== previousSelection.embedding || activeSelection.rerank !== previousSelection.rerank) {
+            try {
+              await writeModelSelection(this.options.resourceRoot, previousSelection)
+              this.options.reload()
+              this.report = blankReport()
+              log('所选模型未通过自检，已恢复此前启用的模型')
+            } catch (rollbackCause) {
+              log(`恢复此前模型选择失败：${rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause)}`)
+            }
+          }
+        }
         job.state = controller.signal.aborted ? 'cancelled' : 'failed'
         job.error = controller.signal.aborted ? '已停止，已下载的资源可在下次重试时复用' : cause instanceof Error ? cause.message : String(cause)
         job.stage = controller.signal.aborted ? '已停止' : '准备未完成'

package/src/environment/types.ts

@@ -1,5 +1,7 @@
 /** Installation state is deployment-wide; it is not knowledge or a build artifact. */
-export type EnvironmentItemId = 'python' | 'embedding' | 'rerank'
+import type { ModelOptionView, ModelSelection } from './model-catalog.js'
+
+export type EnvironmentItemId = 'embedding' | 'rerank'
 export type EnvironmentItemState = 'unchecked' | 'checking' | 'ready' | 'missing' | 'failed'
 export interface EnvironmentItem {
   id: EnvironmentItemId
@@ -27,4 +29,6 @@ export interface EnvironmentJob {
 export interface EnvironmentView {
   report: EnvironmentReport
   job?: EnvironmentJob
+  selection: ModelSelection
+  models: { embedding: ModelOptionView[]; rerank: ModelOptionView[] }
 }

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

@@ -44,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,
@@ -555,7 +556,7 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
     // 0044：非默认库的 runtime 也要拿到模型接缝。只传 `config` 不够 —— 默认库走上面
     // 那个 `new KnowledgeRuntime(... runtimeOptions())`，别的库走注册表这条支路，
     // 两边必须都带上，否则「新建一个库 → 导入文档」静默变成规则抽取。
-    runtimeOptions: () => ({ modelSeam: modelSeamFor, environmentGuard: () => environment.requireReady() }),
+  runtimeOptions: () => ({ resourceRoot: resourceRoot(config.agentRoot), modelSeam: modelSeamFor, environmentGuard: () => environment.requireReady() }),
   })
   compileModelForBase = id => bases.compileModelOf(id)
   runtime.baseId = bases.defaultId
@@ -776,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` 也退役了，因为待办队列不存在了。
@@ -823,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)),
@@ -1022,10 +1048,10 @@ export function apply(ctx: Context, pluginConfig: KnowledgePluginConfig = {}): v
       { 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 } | null
+          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)))
+          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) => {

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} **并列且同构**：一个装内容里提取出来的
  * 图，一个装用户送进来的原件 —— 两者都是「从这个知识库里能直接拿到手的东西」，