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

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()
   })
 
@@ -402,7 +418,7 @@ export function applyConvert(ctx: Context, deps: ConvertHostDeps): ConvertHost {
       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 +429,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 +441,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 +477,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/diagnosis/cards.ts

@@ -1,8 +1,9 @@
-import { DIAGNOSIS_ENTITIES, type DiagnosisEntityType } from './schema.js'
-import type { AttributionCase } from './seed.js'
+import { DIAGNOSIS_ENTITIES, LEGACY_BLOCK_FIELDS, LEGACY_ENTITY_TYPES, type DiagnosisEntityType } from './schema.js'
 import type {
+  AssetType,
+  AttributionCase,
   AttributionEdge, AttributionEdgeKind, AttributionGraphData, AttributionNode, AttributionNodeKind,
-  FailureMode,
+  FailureReason,
 } from './types.js'
 
 /**
@@ -10,13 +11,12 @@ import type {
  *
  * ## 为什么这一层必须存在
  *
- * 在它之前，智能归因的图只有一条来源：`seed.ts` 里的 TypeScript 字面量，被
- * `DiagnosisStore.ensure()` 直接写成 `05_diagnosis/*.jsonl`。那意味着**排查思路从来没有
- * 进过 wiki**：它不在 `01_source_truth` 里、不是 `02_wiki` 的卡片、编译器连
- * `diagnosis/hypothesis` 这个 entity_type 都不认 —— 于是它既不会被 wikiNote 化，
+ * 在它之前，智能归因的图只有一条来源：`seed.ts` 里的 TypeScript 字面量。那意味着
+ * **排查思路从来没有进过 wiki**：它不在 `01_source_truth` 里、不是 `02_wiki` 的卡片、
+ * 编译器连 `diagnosis/hypothesis` 这个 entity_type 都不认 —— 于是它既不会被 wikiNote 化，
  * 也不会进向量索引，**召回永远召不到它**。而「遇到类似问题先召回」正是这个产品的主张。
  *
- * 这一层把图变成卡片的**投影**：卡片是手写的（人写、Agent 写、从 SourceRaw 编译而来），
+ * 这一层把图变成卡片的**投影**：卡片是手写的（人写、Agent 提议后由人确认），
  * 图是算出来的。§4「存图、显树」讲的是同一件事 —— 存的是知识，图是它的一种读法。
  *
  * ## 卡片三段式与「谁由卡片定义」的边界
@@ -31,10 +31,10 @@ import type {
  *
  * | 图上的东西 | 谁定义 | 为什么 |
  * | --- | --- | --- |
- * | symptom / hypothesis / check / failure-mode / case 节点 | **卡片** | 这五类是人写的知识（§6.4） |
+ * | symptom / hypothesis / check_point / failure_reason / case 节点 | **卡片** | 这五类是人确认过的知识（§6.4） |
  * | asset 节点 | 引用反推 | 它随数据目录同步，不手写；卡片里只留 id |
- * | 现象→假设 / 假设→检查 / 假设→失败模式 / 资产→假设 / 案例→现象 边 | **卡片** | 都是卡片字段的确定性投影 |
- * | evidence / cause 节点，produces / supports / refutes / confirmed_as 边 | **一次排查** | 它们是一次执行的结果，不是知识；由排查自动写入（§6.4） |
+ * | 现象→假设 / 假设→检查点 / 假设→失败原因 / 检查点→资产 / 资产→假设 / 案例→现象 边 | **卡片** | 都是卡片字段的确定性投影 |
+ * | evidence / cause 节点，produces / supports / refutes / confirmed_as 边 | **一次排查** | 它们是一次执行的结果，不是知识；由 `01_source_truth/agent_diagnosis_case/` 那条 SourceRaw 读时解析出来 |
  *
  * 最后一行不是妥协，是分层：把「上次查到什么」写进卡片，等于让一份可复用的知识
  * 绑死在一次具体的执行上。
@@ -80,14 +80,15 @@ const CARD_LAYOUT: Record<DiagnosisEntityType, { block: string[]; summaryFrom: s
     summaryFrom: 'observable',
   },
   'diagnosis/hypothesis': {
-    block: ['discriminator', 'not_when', 'failure_mode', 'verified_by', 'assets', 'reuse_count', 'stale'],
+    block: ['discriminator', 'not_when', 'failure_reason', 'verified_by', 'assets', 'reuse_count', 'stale'],
     summaryFrom: 'summary',
   },
-  'diagnosis/check': {
-    block: ['cost_minutes', 'automation', 'verdict_true', 'verdict_false', 'stale'],
+  'diagnosis/check-point': {
+    // `assets` 是 v1.3 新增的**查询依据**：它承载「检查点 → 资产」这条 `queries` 边。
+    block: ['cost_minutes', 'automation', 'verdict_true', 'verdict_false', 'runbook', 'side_effect', 'assets', 'stale'],
     summaryFrom: 'summary',
   },
-  'diagnosis/failure-mode': {
+  'diagnosis/failure-reason': {
     block: ['code', 'label', 'boundary'],
     summaryFrom: 'summary',
   },
@@ -107,7 +108,7 @@ export const CARD_NODE_KINDS: AttributionNodeKind[] = DIAGNOSIS_ENTITIES.map(spe
 
 /** 卡片能定义的边：全部是卡片字段的确定性投影。 */
 export const CARD_EDGE_KINDS: AttributionEdgeKind[] = [
-  'may_be_caused_by', 'verified_by', 'categorized_as', 'indexed_from', 'instance_of',
+  'may_be_caused_by', 'verified_by', 'categorized_as', 'queries', 'indexed_from', 'instance_of',
 ]
 
 /** 一次排查写下的边。它们不属于任何卡片，见文件头的边界表。 */
@@ -150,8 +151,8 @@ export function serializeCard(card: DiagnosisCard): string {
 export function parseCard(source: string): DiagnosisCard | undefined {
   // 复用运行时的 front matter 解析（同一个 yaml 子集），不另写一套。
   const parsed = parseFrontmatter(source)
-  const entityType = String(parsed.frontmatter.entity_type ?? '')
-  if (!isEntityType(entityType)) return undefined
+  const entityType = normalizeEntityType(String(parsed.frontmatter.entity_type ?? ''))
+  if (!entityType) return undefined
   const entityId = String(parsed.frontmatter.entity_id ?? '').trim()
   if (!entityId) return undefined
 
@@ -160,7 +161,7 @@ export function parseCard(source: string): DiagnosisCard | undefined {
   if (match) {
     try {
       const value = JSON.parse(match[1])
-      if (value && typeof value === 'object' && !Array.isArray(value)) block = value as Record<string, unknown>
+      if (value && typeof value === 'object' && !Array.isArray(value)) block = normalizeBlock(value as Record<string, unknown>)
     } catch { /* 块坏了不静默降级成空对象：留空之后由三层校验的「格式层」报缺字段。 */ }
   }
   const body = match ? parsed.content.replace(match[0], '') : parsed.content
@@ -180,6 +181,22 @@ export function parseCard(source: string): DiagnosisCard | undefined {
   }
 }
 
+/** 改名之前的 `entity_type` 按别名认，而不是判为未知类型然后静默丢掉这张卡片。 */
+export function normalizeEntityType(value: string): DiagnosisEntityType | undefined {
+  const mapped = LEGACY_ENTITY_TYPES[value] ?? value
+  return DIAGNOSIS_ENTITIES.some(spec => spec.entityType === mapped) ? mapped as DiagnosisEntityType : undefined
+}
+
+/** 结构化块里的旧字段名（`failure_mode`）搬到新名字上。 */
+function normalizeBlock(block: Record<string, unknown>): Record<string, unknown> {
+  const next: Record<string, unknown> = { ...block }
+  for (const [from, to] of Object.entries(LEGACY_BLOCK_FIELDS)) {
+    if (next[to] === undefined && next[from] !== undefined) next[to] = next[from]
+    delete next[from]
+  }
+  return next
+}
+
 /**
  * 只解析 front matter 与正文。
  *
@@ -224,20 +241,21 @@ function splitSections(body: string): DiagnosisCardSection[] {
   return sections.filter(section => section.body !== '')
 }
 
-function isEntityType(value: string): value is DiagnosisEntityType {
-  return DIAGNOSIS_ENTITIES.some(spec => spec.entityType === value)
-}
-
 /* ─────────────────────────────────────────────── 图 → 卡片 ── */
 
 /**
  * 类型层与案例 → 卡片。
  *
- * `asset` / `evidence` / `cause` 节点**不产出卡片**：它们不是手写的知识（§6.4）。
- * 被假设引用的资产会在反序列化时按 id 补一个最小节点回来。
+ * `asset` / `evidence` / `cause` 节点**不产出卡片**：它们不是手确认过的知识（§6.4）。
+ * 被引用的资产会在反序列化时按 id 补一个最小节点回来。
  */
 export function graphToCards(graph: AttributionGraphData, cases: AttributionCase[] = []): DiagnosisCard[] {
   const cards: DiagnosisCard[] = []
+  /** 资产 id → 卡片声明过的种类。它写在**引用它的那张卡片**上，不写在资产节点自己身上。 */
+  const assetTypeById = new Map<string, AssetType>()
+  for (const node of graph.nodes) {
+    if (node.kind === 'asset' && node.assetType) assetTypeById.set(node.id, node.assetType)
+  }
 
   for (const node of graph.nodes) {
     // 案例节点只是图上的**桩**：它的正文与有序路径住在 `cases` 里（§6.4）。图上的桩不单独成卡，
@@ -264,18 +282,25 @@ export function graphToCards(graph: AttributionGraphData, cases: AttributionCase
     } else if (node.kind === 'hypothesis') {
       block.discriminator = node.discriminator ?? ''
       block.not_when = node.notWhen ?? ''
-      block.failure_mode = node.failureMode ?? null
+      block.failure_reason = node.failureReason ?? null
       block.verified_by = graph.edges.filter(edge => edge.kind === 'verified_by' && edge.source === node.id).map(edge => edge.target)
-      block.assets = graph.edges.filter(edge => edge.kind === 'indexed_from' && edge.target === node.id).map(edge => edge.source)
+      block.assets = graph.edges
+        .filter(edge => edge.kind === 'indexed_from' && edge.target === node.id)
+        .map(edge => assetEntryOf(edge.source, assetTypeById))
       block.reuse_count = node.reuseCount ?? 0
       if (node.stale !== undefined) block.stale = node.stale
-    } else if (node.kind === 'check') {
+    } else if (node.kind === 'check_point') {
       block.cost_minutes = node.costMinutes ?? null
       block.automation = node.automation ?? null
       block.verdict_true = node.verdictTrue ?? ''
       block.verdict_false = node.verdictFalse ?? ''
+      // 检查点 → 资产：`queries` 边。它和假设上的 `assets`（`indexed_from`）是两条边，
+      // 两端与回答的问题都不同，所以各读各的，不共用一份。
+      block.assets = graph.edges
+        .filter(edge => edge.kind === 'queries' && edge.source === node.id)
+        .map(edge => assetEntryOf(edge.target, assetTypeById))
       if (node.stale !== undefined) block.stale = node.stale
-    } else if (node.kind === 'failure-mode') {
+    } else if (node.kind === 'failure_reason') {
       block.code = node.code ?? null
       block.label = node.title
       block.boundary = ''
@@ -328,9 +353,9 @@ export interface CompiledDiagnosis {
 /**
  * 卡片 → 图。
  *
- * 只产出「卡片定义得了」的那部分（类型层 + 引用层的资产 + 案例，以及五种卡片边）；
- * `evidence` / `cause` 与四条执行边由一次排查写入，不在这里合成 —— 否则一次执行的结果
- * 会被伪装成可复用的知识。
+ * 只产出「卡片定义得了」的那部分（类型层 + 引用层的资产 + 案例，以及六种卡片边）；
+ * `evidence` / `cause` 与四条执行边由一次排查写入（`agent_diagnosis_case` 的 SourceRaw），
+ * 不在这里合成 —— 否则一次执行的结果会被伪装成可复用的知识。
  */
 export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
   const nodes: AttributionNode[] = []
@@ -343,16 +368,25 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
     seen.add(card.entityId)
   }
 
-  /** 资产节点按引用反推：引用层随数据目录同步，卡片里只留 id。 */
+  /**
+   * 资产节点按引用反推：引用层随数据目录同步，卡片里只留 id。
+   *
+   * `assets[]` 的每一项可以是 `"dwd_ord_di"`，也可以是 `{ id, type }` —— 后者顺带声明
+   * 资产的种类，它只影响「查询依据」那一段怎么分组（§7.7 ④），不改变边的两端。
+   */
   const assetIds = new Set<string>()
-  const modeIdByCode = new Map<FailureMode, string>()
+  const assetTypes = new Map<string, AssetType>()
+  const reasonIdByCode = new Map<FailureReason, string>()
 
   for (const card of cards) {
-    if (card.entityType === 'diagnosis/failure-mode' && typeof card.block.code === 'string') {
-      modeIdByCode.set(card.block.code as FailureMode, card.entityId)
+    if (card.entityType === 'diagnosis/failure-reason' && typeof card.block.code === 'string') {
+      reasonIdByCode.set(card.block.code as FailureReason, card.entityId)
     }
-    if (card.entityType === 'diagnosis/hypothesis' && Array.isArray(card.block.assets)) {
-      for (const id of card.block.assets) assetIds.add(String(id))
+    if (card.entityType === 'diagnosis/hypothesis' || card.entityType === 'diagnosis/check-point') {
+      for (const ref of assetRefsOf(card.block.assets)) {
+        assetIds.add(ref.id)
+        if (ref.type) assetTypes.set(ref.id, ref.type)
+      }
     }
   }
 
@@ -393,8 +427,8 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
       if (discriminator) node.discriminator = discriminator
       const notWhen = stringOf(card.block.not_when)
       if (notWhen) node.notWhen = notWhen
-      const failureMode = stringOf(card.block.failure_mode)
-      if (failureMode) node.failureMode = failureMode as FailureMode
+      const failureReason = stringOf(card.block.failure_reason)
+      if (failureReason) node.failureReason = failureReason as FailureReason
       const reuse = numberOf(card.block.reuse_count)
       if (reuse !== undefined) node.reuseCount = reuse
       if (typeof card.block.stale === 'boolean') node.stale = card.block.stale
@@ -402,15 +436,15 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
       for (const [index, target] of listOf(card.block.verified_by).entries()) {
         edges.push({ id: `e-${card.entityId.toLowerCase()}-${String(target).toLowerCase()}-${index}`, source: card.entityId, target: String(target), kind: 'verified_by' })
       }
-      for (const [index, asset] of listOf(card.block.assets).entries()) {
-        edges.push({ id: `e-${String(asset).toLowerCase()}-${card.entityId.toLowerCase()}-${index}`, source: String(asset), target: card.entityId, kind: 'indexed_from' })
+      for (const [index, asset] of assetRefsOf(card.block.assets).entries()) {
+        edges.push({ id: `e-${asset.id.toLowerCase()}-${card.entityId.toLowerCase()}-${index}`, source: asset.id, target: card.entityId, kind: 'indexed_from' })
       }
-      if (failureMode) {
-        const modeNode = modeIdByCode.get(failureMode as FailureMode)
-        if (modeNode) edges.push({ id: `e-${card.entityId.toLowerCase()}-${modeNode.toLowerCase()}`, source: card.entityId, target: modeNode, kind: 'categorized_as' })
-        else problems.push(`${card.entityId} 的 failure_mode=${failureMode} 找不到对应的失败模式卡片 —— categorized_as 边无从建立`)
+      if (failureReason) {
+        const reasonNode = reasonIdByCode.get(failureReason as FailureReason)
+        if (reasonNode) edges.push({ id: `e-${card.entityId.toLowerCase()}-${reasonNode.toLowerCase()}`, source: card.entityId, target: reasonNode, kind: 'categorized_as' })
+        else problems.push(`${card.entityId} 的 failure_reason=${failureReason} 找不到对应的失败原因卡片 —— categorized_as 边无从建立`)
       }
-    } else if (card.entityType === 'diagnosis/check') {
+    } else if (card.entityType === 'diagnosis/check-point') {
       const cost = numberOf(card.block.cost_minutes)
       if (cost !== undefined) node.costMinutes = cost
       const automation = stringOf(card.block.automation)
@@ -419,10 +453,18 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
       if (verdictTrue) node.verdictTrue = verdictTrue
       const verdictFalse = stringOf(card.block.verdict_false)
       if (verdictFalse) node.verdictFalse = verdictFalse
+      const assets = assetRefsOf(card.block.assets).map(ref => ref.id)
+      if (assets.length > 0) node.assets = assets
       if (typeof card.block.stale === 'boolean') node.stale = card.block.stale
-    } else if (card.entityType === 'diagnosis/failure-mode') {
+
+      // 检查点 → 资产（`queries`）：这条检查要去查哪些对象。与假设上的
+      // `indexed_from`（这条假设落在哪个对象上）是两条边，方向和语义都不同。
+      for (const [index, asset] of assets.entries()) {
+        edges.push({ id: `e-${card.entityId.toLowerCase()}-${asset.toLowerCase()}-q${index}`, source: card.entityId, target: asset, kind: 'queries' })
+      }
+    } else if (card.entityType === 'diagnosis/failure-reason') {
       const code = stringOf(card.block.code)
-      if (code) node.code = code as FailureMode
+      if (code) node.code = code as FailureReason
     } else if (card.entityType === 'diagnosis/case') {
       const symptom = stringOf(card.block.symptom)
       if (!symptom) problems.push(`${card.entityId} 没有 symptom —— 案例必须从一个现象进入`)
@@ -447,7 +489,8 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
 
   for (const id of assetIds) {
     if (nodes.some(node => node.id === id)) continue
-    nodes.push({ id, kind: 'asset', layer: 'reference', title: id })
+    const assetType = assetTypes.get(id)
+    nodes.push({ id, kind: 'asset', layer: 'reference', title: id, ...(assetType ? { assetType } : {}) })
   }
 
   // 引用完整性：卡片引用了不存在的卡片时，必须报出来（否则图上会出现悬空边，
@@ -461,6 +504,33 @@ export function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis {
   return { graph: { nodes, edges }, cases, problems }
 }
 
+/**
+ * `assets[]` 的一项 → `{ id, type? }`。
+ *
+ * 两种写法都认：`"dwd_ord_di"`（只留 id，资产随数据目录同步）与
+ * `{ id: "dwd_ord_di", type: "table" }`（顺带声明种类，供「查询依据」那一段分组）。
+ * 认不出来的项直接丢掉 —— 造一个 id 是 `[object Object]` 的资产节点，比少一条边难解释。
+ */
+function assetRefsOf(value: unknown): Array<{ id: string; type?: AssetType }> {
+  return listOf(value).flatMap((entry): Array<{ id: string; type?: AssetType }> => {
+    if (typeof entry === 'string') return entry.trim() ? [{ id: entry.trim() }] : []
+    if (entry && typeof entry === 'object') {
+      const record = entry as { id?: unknown; type?: unknown }
+      const id = stringOf(record.id)
+      if (!id) return []
+      const type = stringOf(record.type) as AssetType | undefined
+      return [{ id, ...(type ? { type } : {}) }]
+    }
+    return []
+  })
+}
+
+/** 写回卡片时用同一条规则：声明过种类就写成对象，否则保持一行一个 id 的短写法。 */
+function assetEntryOf(id: string, types: Map<string, AssetType>): string | { id: string; type: AssetType } {
+  const type = types.get(id)
+  return type ? { id, type } : id
+}
+
 function stringOf(value: unknown): string | undefined {
   return typeof value === 'string' && value.trim() !== '' ? value : undefined
 }