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

package/src/client/useFitScale.ts

@@ -16,6 +16,16 @@ import { useEffect, useState, type RefObject } from 'react'
 /** 窄栏下的两档。`fit` = 整图缩到容器，`actual` = 1:1（滚动查看）。 */
 export type ZoomMode = 'fit' | 'actual'
 
+/**
+ * 适应哪一条轴。
+ *
+ * - `both`（默认）：宽高都缩进容器，缩完就是容器的整块面积 —— 知识图谱那一栏用它。
+ * - `width`：只按宽度缩，高度允许溢出 —— 概览画布用它。概览是一块**自持视口**的画布
+ *   （见 `architecture.css` 的 `.tita-archScrollStage`），纵向溢出由空格 + 拖拽平移看，
+ *   而不是把整块板缩到读不出字。
+ */
+export type FitAxis = 'both' | 'width'
+
 export interface FitScale {
   scale: number
   /** 缩放后的板高；容器高度就用它（`fit` 档下正好没有可滚的余量）。 */
@@ -31,6 +41,7 @@ export interface FitScale {
  * @param enabled  容器不可见时不要量（隐藏容器尺寸为 0，算出来的比例是 0）
  * @param fullscreen 全屏时两个方向都按容器算；窄栏只有宽度可用
  * @param mode 缩放档
+ * @param fit 适应哪条轴；`width` 时高度永不算进比例（溢出交由平移）
  */
 export function useFitScale(
   scroller: RefObject<HTMLDivElement | null>,
@@ -39,6 +50,7 @@ export function useFitScale(
   enabled: boolean,
   fullscreen: boolean,
   mode: ZoomMode,
+  fit: FitAxis = 'both',
 ): FitScale {
   /**
    * 可视尺寸。用 `offsetWidth/Height` 而不是 `clientWidth/clientHeight`：后者会随
@@ -60,9 +72,10 @@ export function useFitScale(
   }, [enabled, fullscreen])
 
   // 窄栏只有宽度是可用的：高度由板高自己决定，拿它去算比例就成了一条回路，
-  // 所以那里高度按设计高度算（即「只按宽度适应」）。
+  // 所以那里高度按设计高度算（即「只按宽度适应」）。`fit: 'width'` 把这条规则
+  // 从「窄栏的例外」提升成「这一栏的常态」—— 全屏下也不再把高度算进比例。
   const availW = viewport.w || contentW
-  const availH = fullscreen ? (viewport.h || contentH) : contentH
+  const availH = fit === 'width' ? contentH : fullscreen ? (viewport.h || contentH) : contentH
   const scale = mode === 'actual' ? 1 : Math.min(1, availW / contentW, availH / contentH)
   return { scale, boardH: contentH * scale }
 }

package/src/client/wiki-type-groups.ts

@@ -0,0 +1,86 @@
+/**
+ * Wiki 类型列表的**分组与排布计划**（0040 §4.3）。
+ *
+ * 抽成独立模块的理由是**它出过一次错，而且是静默的**：把「列表怎么摆」直接写在 JSX 的
+ * 三元里时，`prefix === ''` 那一支只渲染了 `members[0]` —— 于是六个没有斜杠的通用类型
+ * （concept / metric / table / event / playbook / case）在界面上只剩第一个，
+ * 另外五个**不见了**，而且没有任何报错。这里把「摆成几行、哪几个进折叠组」
+ * 变成一个可以单独断言的纯函数：它没有 React、没有样式、没有 DOM，输入是注册表、
+ * 输出是行清单。
+ *
+ * 三条规则（都是呈现层行为，不改注册表结构、不改 `entity_type`）：
+ *
+ * 1. **没有斜杠的 id 各自平铺成一行。** 它们不构成一组 —— `concept` 与 `case` 之间
+ *    除了「都没有命名空间」之外没有任何共同点，把它们折成一组只是把六个类型藏进一个
+ *    名字叫空字符串的组里。
+ * 2. **同一个前缀的成员聚成一组，组内保持类型定义顺序**，组与组按前缀第一次出现的
+ *    位置排。注册表的顺序仍然是唯一真源，这里不重排、不排序。
+ * 3. **前缀下只有一个成员时不折叠**（折成只装一项的组，多一次点击、少一次直达），
+ *    那个成员直接平铺回一级列表。
+ */
+
+export interface WikiTypeGroup<T> {
+  prefix: string
+  label: string
+  /** 组内保持注册表里的定义顺序。 */
+  members: T[]
+}
+
+/** 一行要画什么：一个平铺的类型，还是一个可折叠的组。 */
+export type WikiTypeRow<T> =
+  | { kind: 'row'; type: T }
+  | { kind: 'group'; prefix: string; label: string; members: T[] }
+
+/**
+ * 组名默认取前缀本身 —— 只有真正需要翻译的才写进这张表。
+ *
+ * 写死五个 `diagnosis/*` 的 id 是不行的：自定义类型也允许带斜杠，
+ * `diagnosis` 前缀下的类型是可增删的。
+ */
+export const GROUP_LABELS: Record<string, string> = { diagnosis: '归因图谱' }
+
+export const idPrefix = (id: string): string => {
+  const at = id.indexOf('/')
+  return at > 0 ? id.slice(0, at) : ''
+}
+
+export const groupLabel = (prefix: string): string => GROUP_LABELS[prefix] ?? prefix
+
+/** 按 id 前缀把类型折成组。顺序 = 前缀第一次出现的位置。 */
+export function groupWikiTypes<T extends { id: string }>(types: T[]): Array<WikiTypeGroup<T>> {
+  const groups: Array<WikiTypeGroup<T>> = []
+  const byPrefix = new Map<string, WikiTypeGroup<T>>()
+  for (const type of types) {
+    const prefix = idPrefix(type.id)
+    const existing = byPrefix.get(prefix)
+    if (existing) { existing.members.push(type); continue }
+    const created: WikiTypeGroup<T> = { prefix, label: groupLabel(prefix), members: [type] }
+    byPrefix.set(prefix, created)
+    groups.push(created)
+  }
+  return groups
+}
+
+/**
+ * 类型注册表 → 界面上的行清单。
+ *
+ * **不丢任何一个类型**是它的核心承诺：`rows` 里所有 `type` 加起来必须与输入一一对应。
+ * 测试钉住了这一条（见 `tests/wiki-type-groups.test.mjs`）—— 上一次出错时
+ * 界面少了五个类型，而所有既有测试都是绿的。
+ */
+export function wikiTypeRows<T extends { id: string }>(types: T[]): Array<WikiTypeRow<T>> {
+  const rows: Array<WikiTypeRow<T>> = []
+  for (const group of groupWikiTypes(types)) {
+    // 没有命名空间的照旧平铺 —— **每一个成员各占一行**，不是只画第一个。
+    if (group.prefix === '') {
+      for (const type of group.members) rows.push({ kind: 'row', type })
+      continue
+    }
+    if (group.members.length === 1) {
+      rows.push({ kind: 'row', type: group.members[0]! })
+      continue
+    }
+    rows.push({ kind: 'group', prefix: group.prefix, label: group.label, members: group.members })
+  }
+  return rows
+}

package/src/convert/host.ts

@@ -156,7 +156,7 @@ function send(res: ServerResponse, status: number, body: unknown): void {
 }
 
 /** Compact task view for tools — the full ingest payload never enters context. */
-function taskView(task: ConvertTask): Record<string, unknown> {
+function taskView(kernel: ConvertService, task: ConvertTask): Record<string, unknown> {
   const manifest = task.manifest
   return {
     taskId: task.id,
@@ -171,6 +171,8 @@ function taskView(task: ConvertTask): Record<string, unknown> {
     error: task.error ?? null,
     warnings: task.warnings.map(warning => warning.code),
     attempts: task.attempts,
+    /** 与服务端 retry() 的守卫同源（`canRetryTask`）：Agent 不该去点一枚注定失败的按钮。 */
+    canRetry: kernel.canRetry(task).ok,
     deliveryDir: task.deliveryDir,
     assetCount: manifest?.assets.length ?? 0,
     wordCount: manifest?.wordCount ?? 0,
@@ -307,10 +309,24 @@ export function applyConvert(ctx: Context, deps: ConvertHostDeps): ConvertHost {
   config = { ...DEFAULT_CONVERT_CONFIG, ...readConfig() }
   void resetService()
 
+  /**
+   * 写操作要用户点头。
+   *
+   * `convert_task` 是**一个混合工具**：`list` / `get` / `markdown` / `manifest` 只读，
+   * `cancel` / `retry` 会改队列。所以它不能整只进 `WRITE_TOOLS`（那会让「看一眼队列」
+   * 也要审批），也不能整只留在外面 —— 那样一个自称只读的工具就能取消别人的任务。
+   * 判据落在 `action` 上。
+   */
   ctx.on('tools/pre-execute', (exec, next): Promise<PreToolDecision> => {
     if ((WRITE_TOOLS as readonly string[]).includes(exec.name)) {
       return Promise.resolve({ kind: 'ask', reason: '该操作会转换本地内容，并写入 Tita Knowledge Store，需要本轮用户审批。' })
     }
+    if (exec.name === 'convert_task') {
+      const action = (exec.arguments as { action?: unknown } | undefined)?.action
+      if (action === 'cancel' || action === 'retry') {
+        return Promise.resolve({ kind: 'ask', reason: `convert_task 的 ${String(action)} 会改动转换队列，需要本轮用户审批。` })
+      }
+    }
     return next()
   })
 
@@ -346,10 +362,11 @@ export function applyConvert(ctx: Context, deps: ConvertHostDeps): ConvertHost {
 
   ctx.tools.register(tool(
     'convert_source',
-    'Convert a document (Word / PowerPoint / Excel / OpenDocument / RTF / EPUB / CSV / text-layer PDF) or inline text into knowledge-ready Markdown + local images. Async kernel task; returns taskId, delivery dir and ingest hints (source_type candidates, external_id, content_hash). Write operation: DSH asks the user once before execution.',
+    'Convert a document (Word / PowerPoint / Excel / OpenDocument / RTF / EPUB / CSV / text-layer PDF), a web page / WeChat article (a bare URL, or a saved .html/.htm page), local audio-video-image, or inline text into knowledge-ready Markdown + local images. Async kernel task; returns taskId, delivery dir and ingest hints (source_type candidates, external_id, content_hash). Write operation: DSH asks the user once before execution.',
     {
-      kind: { type: 'string', enum: ['file', 'text'], required: true },
+      kind: { type: 'string', enum: ['file', 'text', 'url'], required: true },
       path: { type: 'string' },
+      url: { type: 'string' },
       text: { type: 'string' },
       title: { type: 'string' },
       source_type: { type: 'string' },
@@ -373,6 +390,7 @@ export function applyConvert(ctx: Context, deps: ConvertHostDeps): ConvertHost {
         kind,
         ...(candidates.length > 0 ? { sourceTypeCandidates: candidates } : {}),
         ...(typeof args.text === 'string' ? { text: args.text } : {}),
+        ...(typeof args.url === 'string' ? { url: args.url } : {}),
         ...(typeof args.title === 'string' && args.title.trim() ? { title: args.title.trim() } : {}),
         ...(typeof args.source_type === 'string' && args.source_type.trim() ? { sourceType: args.source_type.trim(), sourceTypeSource: 'agent' as const } : {}),
         ...(typeof args.adapter === 'string' && args.adapter.trim() ? { adapter: args.adapter.trim() } : {}),
@@ -399,10 +417,33 @@ export function applyConvert(ctx: Context, deps: ConvertHostDeps): ConvertHost {
         if (!request.title) request.title = basename(absolute)
       }
 
+      /*
+       * 链接档**必须**在宿主侧就把地址检查掉。
+       *
+       * 内核的 `resolveAdapter` 见到 `kind=url` 会直接交给 web 适配器，而适配器只认
+       * `request.url` —— 少了这个字段，报出来的是一句和用户输入毫无关系的 `URL_REQUIRED`。
+       * 这里挡住并给出「你要给的是哪一种」。
+       */
+      if (kind === 'url') {
+        const raw = typeof args.url === 'string' ? args.url.trim() : ''
+        if (!raw) {
+          return failure({ taskId: null }, 'URL_REQUIRED', 'kind=url 必须提供 http(s) 地址 url。', false, '例如 https://mp.weixin.qq.com/s?__biz=...（公众号文章直接粘整条链接即可）。')
+        }
+        try {
+          const parsed = new URL(raw)
+          if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+            return failure({ taskId: null }, 'URL_INVALID', `只支持 http/https：${parsed.protocol}`, false, '本机文件请用 kind=file + path。')
+          }
+        } catch {
+          return failure({ taskId: null }, 'URL_INVALID', `不是合法的地址：${raw}`, false, '整条链接一起粘过来，包含 https:// 前缀。')
+        }
+        request.url = raw
+      }
+
       const submitted = await kernel.submit(request)
       const shouldWait = args.wait !== false
       const finished = shouldWait ? await waitForTask(kernel, submitted.id, config.toolWaitMs) : submitted
-      const view = taskView(finished ?? submitted)
+      const view = taskView(kernel, finished ?? submitted)
       return success({
         ...view,
         waited: shouldWait,
@@ -413,7 +454,7 @@ export function applyConvert(ctx: Context, deps: ConvertHostDeps): ConvertHost {
 
   ctx.tools.register(tool(
     'convert_task',
-    'Inspect the conversion queue: list, get, cancel, retry, or read the delivered Markdown/manifest of a task. Read-only.',
+    'Inspect and steer the conversion queue. list / get / markdown / manifest are read-only; cancel and retry change the queue (both need user approval). retry only works on a failed or cancelled task whose staged input is still in tmp/ — a delivered task cannot be retried, because its input is cleaned up when it is delivered; submit the file again instead.',
     {
       action: { type: 'string', enum: ['list', 'get', 'cancel', 'retry', 'markdown', 'manifest'], required: true },
       task_id: { type: 'string' },
@@ -425,12 +466,30 @@ export function applyConvert(ctx: Context, deps: ConvertHostDeps): ConvertHost {
       const action = String(args.action)
       if (action === 'list') {
         const limit = Number.isFinite(args.limit) ? Math.max(1, Math.min(100, Number(args.limit))) : 20
-        return success({ tasks: kernel.list().slice(0, limit).map(taskView) })
+        return success({ tasks: kernel.list().slice(0, limit).map(task => taskView(kernel, task)) })
       }
       const taskId = typeof args.task_id === 'string' ? args.task_id.trim() : ''
       if (!taskId) return failure({ taskId: null }, 'TASK_ID_REQUIRED', `${action} 需要 task_id。`)
-      if (action === 'cancel') return success(taskView(kernel.cancel(taskId)))
-      if (action === 'retry') return success(taskView(await kernel.retry(taskId)))
+      /*
+       * `cancel` / `retry` **会改队列**，所以它们不把 `AdapterError` 抛出去让宿主兜，
+       * 而是把 code 与 suggestion 如实放进 envelope：Agent 读到的应该是「为什么不能」
+       * 与「那该怎么办」（例如：已交付的任务要**重新提交文件**，而不是重试 ——
+       * 它的输入在交付后就清理了）。
+       */
+      if (action === 'cancel' || action === 'retry') {
+        try {
+          return success(taskView(kernel, action === 'cancel' ? kernel.cancel(taskId) : await kernel.retry(taskId)))
+        } catch (cause) {
+          const error = cause as { code?: unknown; message?: unknown; suggestion?: unknown }
+          return failure(
+            { taskId },
+            typeof error.code === 'string' ? error.code : 'CONVERT_TASK_FAILED',
+            typeof error.message === 'string' ? error.message : String(cause),
+            false,
+            typeof error.suggestion === 'string' ? error.suggestion : undefined,
+          )
+        }
+      }
       if (action === 'markdown') {
         const file = await kernel.readDeliveryFile(taskId, 'index.md')
         if (!file) return failure({ taskId }, 'ARTIFACT_NOT_FOUND', '该任务没有 index.md（未成功或已被清理）。')
@@ -443,7 +502,7 @@ export function applyConvert(ctx: Context, deps: ConvertHostDeps): ConvertHost {
       }
       const task = kernel.get(taskId)
       if (!task) return failure({ taskId }, 'TASK_NOT_FOUND', `任务不存在：${taskId}`)
-      return success(taskView(task))
+      return success(taskView(kernel, task))
     },
   ))
 

package/src/convert/ingest.ts

@@ -25,7 +25,7 @@ import { cp, mkdir, stat } from 'node:fs/promises'
 import { basename, join, resolve, sep } from 'node:path'
 import type { ConvertService, IngestPayload } from 'dsh-convert-core'
 import type { LineageContext } from 'dsh-data-contracts/refs'
-import type { SourceType, SourceTypeDef } from '../types.js'
+import type { SourceProvenance, SourceType, SourceTypeDef } from '../types.js'
 import {
   failure,
   KNOWLEDGE_ASSET_DIR,
@@ -48,6 +48,8 @@ export interface IngestTarget {
     metadata?: Record<string, unknown>
     sourceId?: string
     lineage?: LineageContext
+    /** OKF v0.2 溯源信息（0048）：写成 front matter 的顶层键，不塞进 metadata。 */
+    provenance?: SourceProvenance
   }): Promise<{
     ok: boolean
     data: { sourceId: string; path: string }
@@ -98,7 +100,7 @@ export interface IngestOutcome {
   sourceTypeSupplied: boolean
   sourceTypeCandidates: string[]
   assets: PlacedAsset[]
-  /** Path to the source file relative to the knowledge root, e.g. `01_source_truth/x.md`. */
+  /** Path to the source file relative to the knowledge root, e.g. `01_source_raw/x.md`. */
   relativeSourcePath?: string
   cardHints: CardHints
   notes: string[]
@@ -111,8 +113,9 @@ export interface CardHints {
   title: string
   summary: string
   /**
-   * Card body with image references already re-based to `02_wiki/<entityType>/`,
-   * so the first image actually reaches the multimodal embedder.
+   * Card body with image references re-based to the canonical
+   * knowledge-root-relative form (`01_source_raw/_assets/<bucket>/<file>`), so
+   * the first image actually reaches the multimodal embedder.
    */
   contentWithImages: string
   /** The image references as they must appear inside a card body. */
@@ -137,12 +140,17 @@ function rewriteImageRefs(markdown: string, mapping: Map<string, string>): strin
   return result
 }
 
-function cardImageRef(hash: string, rel: string, entityType: string): string {
-  // A card lives at 02_wiki/<entityType>/<slug>.md; the asset lives at
-  // 01_source_truth/_assets/<hash>/<file>.
-  const depth = 2
-  const up = Array.from({ length: depth }, () => '..').join('/')
-  return `${up}/${KNOWLEDGE_SOURCE_DIR}/${KNOWLEDGE_ASSET_DIR}/${hash}/${basename(rel)}`
+/**
+ * 图片引用写成**知识库根相对**的规范形：`01_source_raw/_assets/<bucket>/<file>`。
+ *
+ * 为什么不写成「相对引用它的那个文件」：同一份资产会被三处引用 —— SourceRaw 在
+ * `01_source_raw/<type>/`、卡片在 `02_wiki/<type>/`、还有面板拼出来的 URL。写死
+ * 「往上两级」在深度相同的地方凑巧成立，换个深度就错，而且错了不会报错，只会让
+ * 向量编码器读到不存在的文件（0047 实机：`FileNotFoundError: …/02_wiki/concept/_assets/…`）。
+ * 根相对只有一种解释，运行时按 {@link assetRefCandidates} 解析。
+ */
+function assetImageRef(hash: string, rel: string): string {
+  return `${KNOWLEDGE_SOURCE_DIR}/${KNOWLEDGE_ASSET_DIR}/${hash}/${basename(rel)}`
 }
 
 export function buildCardHints(input: {
@@ -152,12 +160,11 @@ export function buildCardHints(input: {
   assetMapping: Map<string, string>
   entityType?: string
 }): CardHints {
-  const entityType = input.entityType && ENTITY_TYPES.includes(input.entityType) ? input.entityType : 'concept'
   const content = rewriteImageRefs(
     input.payload.content,
-    new Map([...input.assetMapping].map(([from, to]) => [from, cardImageRef(input.assetBucket, to, entityType)])),
+    new Map([...input.assetMapping].map(([from, to]) => [from, assetImageRef(input.assetBucket, to)])),
   )
-  const imageRefs = input.payload.assets.map(asset => cardImageRef(input.assetBucket, asset.rel, entityType))
+  const imageRefs = input.payload.assets.map(asset => assetImageRef(input.assetBucket, asset.rel))
   const summary = input.payload.content
     .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
     .replace(/[#>*`_\-[\]()]/g, ' ')
@@ -249,9 +256,17 @@ export async function ingestDelivery(options: IngestOptions): Promise<Envelope<I
 
   const sourceContent = rewriteImageRefs(
     payload.content,
-    new Map([...assetMapping].map(([from, to]) => [from, `${KNOWLEDGE_ASSET_DIR}/${bucket}/${basename(to)}`])),
+    new Map([...assetMapping].map(([from, to]) => [from, assetImageRef(bucket, to)])),
   )
 
+  /**
+   * `metadata` 只剩**类型专属的扩展键**（0048）。
+   *
+   * 原先链接、解析器、格式、哈希、资产清单全挤在这一个 JSON 字符串里 —— 人读不了、
+   * `grep` 不到，等于没有元数据。OKF v0.2 的那一组（`description` / `resource` /
+   * `generated` / `sources[]`）现在走 `provenance`，写成真正的顶层键；这里留下的是
+   * OKF 没有对应概念、但下游确实要用的运行信息。
+   */
   const metadata: Record<string, unknown> = {
     ...(options.metadata ?? {}),
     source_format: payload.sourceFormat,
@@ -259,9 +274,10 @@ export async function ingestDelivery(options: IngestOptions): Promise<Envelope<I
     content_hash: payload.contentHash,
     convert_task_id: taskId,
     convert_contract_version: 1,
-    ...(payload.sourceUrl ? { source_url: payload.sourceUrl } : {}),
-    ...(payload.sourcePath ? { source_path: payload.sourcePath } : {}),
-    assets: placed.map(asset => `${KNOWLEDGE_ASSET_DIR}/${bucket}/${basename(asset.rel)}`),
+    ...(payload.original
+      ? { original: { rel: payload.original.rel, bytes: payload.original.bytes, sha256: payload.original.sha256 } }
+      : {}),
+    assets: placed.map(asset => assetImageRef(bucket, asset.rel)),
   }
 
   const sourceType = options.sourceType?.trim() || 'document'
@@ -273,6 +289,29 @@ export async function ingestDelivery(options: IngestOptions): Promise<Envelope<I
   const title = options.title?.trim() || payload.title
   const externalId = payload.externalId
 
+  /**
+   * OKF v0.2 的溯源信息。
+   *
+   * `generated.at` 就是**采集时间**：OKF 里没有「抓取时间」这个概念，而「这份文件
+   * 什么时候被谁写出来的」正好是它。`sources[]` 记的是这份文件的来源 —— 对网页就是
+   * 那个页面本身（地址、标题、作者、发布时间），对上传的文件就是文件名。
+   */
+  const provenance: SourceProvenance = {
+    ...(payload.document?.description ? { description: payload.document.description } : {}),
+    ...(payload.sourceUrl ? { resource: payload.sourceUrl } : {}),
+    generatedBy: `convert/${payload.parser}`,
+    generatedAt: new Date().toISOString(),
+    sources: [{
+      id: 'origin',
+      resource: payload.sourceUrl ?? payload.original?.rel ?? payload.sourcePath ?? title,
+      title,
+      ...(payload.document?.siteName ? { author: payload.document.siteName } : {}),
+      ...(!payload.document?.siteName && payload.document?.author ? { author: payload.document.author } : {}),
+      ...(payload.document?.publishedAt ? { lastModified: payload.document.publishedAt } : {}),
+    }],
+  }
+
+
   if (!options.planOnly) {
     const result = await options.runtime.addSource({
       sourceType: sourceType as SourceType,
@@ -280,6 +319,7 @@ export async function ingestDelivery(options: IngestOptions): Promise<Envelope<I
       content: sourceContent,
       externalId,
       metadata,
+      provenance,
       ...(options.lineage ? { lineage: options.lineage as LineageContext } : {}),
     })
 
@@ -297,7 +337,10 @@ export async function ingestDelivery(options: IngestOptions): Promise<Envelope<I
     const sourceId = result.data.sourceId
     const sourcePath = result.data.path
     const cardHints = buildCardHints({ payload, sourceId, assetBucket: bucket, assetMapping })
-    notes.push('SourceRaw 已写入；图片要进入多模态召回，还需要一张引用它们的 wiki 卡片（见 cardHints）。')
+    // 0046 起编译会把来源里的图**自动**挂进对应卡片正文（按「图前那段话」定位），
+    // 所以 cardHints 不再是让图进多模态召回的**唯一**办法，只是「想立刻手工建一张图卡」
+    // 时的现成素材。
+    notes.push('SourceRaw 已写入；图片已随正文落地，下一次编译会把它们挂到对应卡片上（cardHints 是手工建图卡时的现成素材）。')
 
     return success<IngestOutcome>(
       {

package/src/convert/types.ts

@@ -12,9 +12,9 @@ import { join } from 'node:path'
 export const CONVERT_SETTINGS_NAMESPACE = 'tita-data-agent-convert'
 
 /** Knowledge store layout the convert seam cooperates with (issue 0013). */
-export const KNOWLEDGE_SOURCE_DIR = '01_source_truth'
+export const KNOWLEDGE_SOURCE_DIR = '01_source_raw'
 export const KNOWLEDGE_WIKI_DIR = '02_wiki'
-/** Sub-directory inside `01_source_truth` that holds converted images. */
+/** Sub-directory inside `01_source_raw` that holds converted images. */
 export const KNOWLEDGE_ASSET_DIR = '_assets'
 
 export interface ConvertPluginConfig {