dsh-data-domain-knowledge 0.1.0-alpha.1

package/lib/types/convert/ingest.js

@@ -0,0 +1,228 @@
+/**
+ * The knowledge-ingestion seam.
+ *
+ * Rules this file obeys, and why:
+ *
+ * 1. **One write entry, in-process.** Since 0018 the convert host lives inside
+ *    the knowledge plugin, so ingestion calls `KnowledgeRuntime.addSource()`
+ *    directly instead of `POST /knowledge/sources`. That removes a JSON body
+ *    cap (the old transport 400'd above ~1.2 MB) and removes port discovery,
+ *    startup ordering and error-code re-translation from the failure surface.
+ *    The structural `IngestTarget` interface is deliberately the only knowledge
+ *    API this module may touch — conversion code must not reach into the store.
+ * 2. **The kernel never writes the knowledge store.** It only produces
+ *    `convert-out/<taskId>/`. This module is the translation step.
+ * 3. **`source_type` stays the knowledge side's decision.** We propose
+ *    candidates; if the store rejects the value we surface its error verbatim
+ *    instead of silently defaulting.
+ * 4. **Images must land inside the knowledge root**, because retrieval only
+ *    reads local relative paths — and only the *first* image of a unit reaches
+ *    the multimodal embedder, so we also emit card hints that tell the Agent how
+ *    to reference them.
+ */
+import { cp, mkdir, stat } from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
+import { failure, KNOWLEDGE_ASSET_DIR, KNOWLEDGE_SOURCE_DIR, KNOWLEDGE_WIKI_DIR, success, } from './types.js';
+const ENTITY_TYPES = ['concept', 'metric', 'table', 'event', 'playbook', 'case'];
+/** Refuse any path that would escape the knowledge root. */
+export function safeJoin(root, ...parts) {
+    const base = resolve(root);
+    const target = resolve(base, ...parts);
+    if (target !== base && !target.startsWith(base + sep))
+        return undefined;
+    return target;
+}
+function rewriteImageRefs(markdown, mapping) {
+    let result = markdown;
+    for (const [from, to] of mapping) {
+        result = result.split(`(${from})`).join(`(${to})`);
+    }
+    return result;
+}
+function cardImageRef(hash, rel, entityType) {
+    // 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)}`;
+}
+export function buildCardHints(input) {
+    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)])));
+    const imageRefs = input.payload.assets.map(asset => cardImageRef(input.assetBucket, asset.rel, entityType));
+    const summary = input.payload.content
+        .replace(/!\[[^\]]*\]\([^)]*\)/g, '')
+        .replace(/[#>*`_\-[\]()]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 160);
+    return {
+        entityTypes: ENTITY_TYPES,
+        sourceRefs: [input.sourceId],
+        title: input.payload.title,
+        summary,
+        contentWithImages: content,
+        imageRefs,
+    };
+}
+/**
+ * Turn a store rejection into an actionable suggestion without inventing one.
+ *
+ * 0013：分类候选来自**当前知识库的注册表**（含用户自定义分类），不再写死三个内置值。
+ */
+function suggestionFor(code, candidates) {
+    if (code === 'SOURCE_TYPE_UNKNOWN') {
+        return `当前知识库的分类注册表里没有这个分类。可用分类：${candidates.join(' / ') || '（无）'}；要新增分类请到「知识库设置 → 来源类型」，并写清怎么判断它是这一类。`;
+    }
+    if (code === 'SOURCE_TYPE_DISABLED') {
+        return `该分类已停用。可用分类：${candidates.join(' / ') || '（无）'}；要恢复请到「知识库设置 → 来源类型」重新启用。`;
+    }
+    // 这里曾经有一条 `CONTENT_TOO_LARGE` 的建议（「调大 maxSourceBytes」）。0029 撤掉
+    // 那个上限之后，`addSource` 再也不会产出这个 code，留着它就成了一条指向不存在开关
+    // 的指路牌 —— 环境里已经没有任何东西会触发它。
+    if (code === 'SOURCE_TRUTH_DISABLED') {
+        return '在知识插件设置里打开「允许写入 SourceTruth」（allowSourceTruth）。';
+    }
+    return undefined;
+}
+export async function ingestDelivery(options) {
+    const { service, taskId } = options;
+    let payload;
+    try {
+        payload = await service.ingestPlan(taskId);
+    }
+    catch (cause) {
+        const error = cause;
+        return failure(emptyOutcome(taskId, options.knowledgeRoot, options.sourceType), error.code ?? 'TASK_NOT_READY', error.message, false, error.suggestion);
+    }
+    const bucket = payload.contentHash.slice(0, 12);
+    const assetRoot = safeJoin(options.knowledgeRoot, KNOWLEDGE_SOURCE_DIR, KNOWLEDGE_ASSET_DIR, bucket);
+    if (!assetRoot) {
+        return failure(emptyOutcome(taskId, options.knowledgeRoot, options.sourceType), 'PATH_OUTSIDE_KNOWLEDGE_ROOT', '资产目标路径越出知识库根目录。');
+    }
+    const assetMapping = new Map();
+    const placed = [];
+    const notes = [];
+    const warnings = [];
+    if (options.planOnly !== true && payload.assets.length > 0) {
+        await mkdir(assetRoot, { recursive: true });
+        for (const asset of payload.assets) {
+            const target = safeJoin(assetRoot, basename(asset.rel));
+            if (!target) {
+                warnings.push(`跳过越界资产：${asset.rel}`);
+                continue;
+            }
+            try {
+                await cp(asset.path, target, { force: true });
+                const info = await stat(target);
+                placed.push({ rel: asset.rel, target, bytes: info.size });
+                assetMapping.set(asset.rel, asset.rel);
+            }
+            catch (cause) {
+                warnings.push(`资产复制失败（${asset.rel}）：${cause instanceof Error ? cause.message : String(cause)}`);
+            }
+        }
+        if (placed.length !== payload.assets.length) {
+            notes.push(`${payload.assets.length - placed.length} 个图片资产未复制，正文中的对应引用会指向不存在的文件。`);
+        }
+    }
+    else if (options.planOnly === true) {
+        for (const asset of payload.assets)
+            assetMapping.set(asset.rel, asset.rel);
+        notes.push('planOnly=true：未复制资产、未写入 SourceRaw。');
+    }
+    const sourceContent = rewriteImageRefs(payload.content, new Map([...assetMapping].map(([from, to]) => [from, `${KNOWLEDGE_ASSET_DIR}/${bucket}/${basename(to)}`])));
+    const metadata = {
+        ...(options.metadata ?? {}),
+        source_format: payload.sourceFormat,
+        parser: payload.parser,
+        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)}`),
+    };
+    const sourceType = options.sourceType?.trim() || 'document';
+    // 分类候选取自当前知识库的注册表（0013）：内置分类 + 用户自定义，只列启用的。
+    const sourceTypeCandidates = (options.runtime.sourceTypes?.() ?? [])
+        .filter((def) => def.enabled)
+        .map((def) => def.id);
+    payload.sourceTypeCandidates = sourceTypeCandidates;
+    const title = options.title?.trim() || payload.title;
+    const externalId = payload.externalId;
+    if (!options.planOnly) {
+        const result = await options.runtime.addSource({
+            sourceType: sourceType,
+            title,
+            content: sourceContent,
+            externalId,
+            metadata,
+            ...(options.lineage ? { lineage: options.lineage } : {}),
+        });
+        if (!result.ok) {
+            const code = result.error?.code ?? 'KNOWLEDGE_WRITE_FAILED';
+            return failure(emptyOutcome(taskId, options.knowledgeRoot, options.sourceType), code, result.error?.message ?? '知识库拒绝了该来源', false, result.error?.suggestion ?? suggestionFor(code, sourceTypeCandidates));
+        }
+        const sourceId = result.data.sourceId;
+        const sourcePath = result.data.path;
+        const cardHints = buildCardHints({ payload, sourceId, assetBucket: bucket, assetMapping });
+        notes.push('SourceRaw 已写入；图片要进入多模态召回，还需要一张引用它们的 wiki 卡片（见 cardHints）。');
+        return success({
+            taskId,
+            sourceId,
+            ...(sourcePath ? { sourcePath } : {}),
+            knowledgeRoot: options.knowledgeRoot,
+            externalId,
+            contentHash: payload.contentHash,
+            sourceFormat: payload.sourceFormat,
+            parser: payload.parser,
+            sourceType,
+            sourceTypeSupplied: Boolean(options.sourceType?.trim()),
+            sourceTypeCandidates: payload.sourceTypeCandidates,
+            assets: placed,
+            ...(sourcePath ? { relativeSourcePath: relativeTo(options.knowledgeRoot, sourcePath) } : {}),
+            cardHints,
+            notes,
+        }, warnings);
+    }
+    // Dry run: report what would happen, including the card hints.
+    const preview = buildCardHints({ payload, sourceId: '<add_source 返回的 sourceId>', assetBucket: bucket, assetMapping });
+    return success({
+        taskId,
+        knowledgeRoot: options.knowledgeRoot,
+        externalId,
+        contentHash: payload.contentHash,
+        sourceFormat: payload.sourceFormat,
+        parser: payload.parser,
+        sourceType,
+        sourceTypeSupplied: Boolean(options.sourceType?.trim()),
+        sourceTypeCandidates: payload.sourceTypeCandidates,
+        assets: payload.assets.map(asset => ({ rel: asset.rel, target: join(assetRoot, basename(asset.rel)), bytes: asset.bytes })),
+        cardHints: preview,
+        notes: [...notes, `将写入 ${KNOWLEDGE_SOURCE_DIR}，资产放入 ${KNOWLEDGE_ASSET_DIR}/${bucket}/`],
+    });
+}
+function relativeTo(root, path) {
+    const base = resolve(root);
+    const target = resolve(path);
+    return target.startsWith(base + sep) ? target.slice(base.length + 1) : target;
+}
+function emptyOutcome(taskId, knowledgeRoot, sourceType) {
+    return {
+        taskId,
+        knowledgeRoot,
+        externalId: '',
+        contentHash: '',
+        sourceFormat: '',
+        parser: '',
+        sourceType: sourceType?.trim() || 'document',
+        sourceTypeSupplied: Boolean(sourceType?.trim()),
+        sourceTypeCandidates: [],
+        assets: [],
+        cardHints: { entityTypes: ENTITY_TYPES, sourceRefs: [], title: '', summary: '', contentWithImages: '', imageRefs: [] },
+        notes: [],
+    };
+}
+export { ENTITY_TYPES, KNOWLEDGE_WIKI_DIR };
+//# sourceMappingURL=ingest.js.map

package/lib/types/convert/ingest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ingest.js","sourceRoot":"","sources":["../../../src/convert/ingest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAClD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,WAAW,CAAA;AAIxD,OAAO,EACL,OAAO,EACP,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,OAAO,GAER,MAAM,YAAY,CAAA;AAsFnB,MAAM,YAAY,GAAG,CAAC,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,CAAA;AAEhF,4DAA4D;AAC5D,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,GAAG,KAAe;IACvD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,CAAA;IACtC,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC;QAAE,OAAO,SAAS,CAAA;IACvE,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,gBAAgB,CAAC,QAAgB,EAAE,OAA4B;IACtE,IAAI,MAAM,GAAG,QAAQ,CAAA;IACrB,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,OAAO,EAAE,CAAC;QACjC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IACpD,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,SAAS,YAAY,CAAC,IAAY,EAAE,GAAW,EAAE,UAAkB;IACjE,qEAAqE;IACrE,yCAAyC;IACzC,MAAM,KAAK,GAAG,CAAC,CAAA;IACf,MAAM,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;IAC9D,OAAO,GAAG,EAAE,IAAI,oBAAoB,IAAI,mBAAmB,IAAI,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAA;AACxF,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAM9B;IACC,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,IAAI,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAA;IAC7G,MAAM,OAAO,GAAG,gBAAgB,CAC9B,KAAK,CAAC,OAAO,CAAC,OAAO,EACrB,IAAI,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,YAAY,CAAC,KAAK,CAAC,WAAW,EAAE,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,CAC9G,CAAA;IACD,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAA;IAC3G,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO;SAClC,OAAO,CAAC,uBAAuB,EAAE,EAAE,CAAC;SACpC,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC;SAC/B,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC;SACpB,IAAI,EAAE;SACN,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;IAChB,OAAO;QACL,WAAW,EAAE,YAAY;QACzB,UAAU,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC;QAC5B,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK;QAC1B,OAAO;QACP,iBAAiB,EAAE,OAAO;QAC1B,SAAS;KACV,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,aAAa,CAAC,IAAY,EAAE,UAAoB;IACvD,IAAI,IAAI,KAAK,qBAAqB,EAAE,CAAC;QACnC,OAAO,2BAA2B,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,sCAAsC,CAAA;IACzG,CAAC;IACD,IAAI,IAAI,KAAK,sBAAsB,EAAE,CAAC;QACpC,OAAO,eAAe,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,2BAA2B,CAAA;IAClF,CAAC;IACD,+DAA+D;IAC/D,mDAAmD;IACnD,2BAA2B;IAC3B,IAAI,IAAI,KAAK,uBAAuB,EAAE,CAAC;QACrC,OAAO,iDAAiD,CAAA;IAC1D,CAAC;IACD,OAAO,SAAS,CAAA;AAClB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,OAAsB;IACzD,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAA;IACnC,IAAI,OAAsB,CAAA;IAC1B,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC,CAAA;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,GAAG,KAAuD,CAAA;QACrE,OAAO,OAAO,CACZ,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,EAC/D,KAAK,CAAC,IAAI,IAAI,gBAAgB,EAC9B,KAAK,CAAC,OAAO,EACb,KAAK,EACL,KAAK,CAAC,UAAU,CACjB,CAAA;IACH,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAA;IAC/C,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,aAAa,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,CAAC,CAAA;IACpG,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,OAAO,OAAO,CAAC,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE,6BAA6B,EAAE,iBAAiB,CAAC,CAAA;IACnI,CAAC;IAED,MAAM,YAAY,GAAG,IAAI,GAAG,EAAkB,CAAA;IAC9C,MAAM,MAAM,GAAkB,EAAE,CAAA;IAChC,MAAM,KAAK,GAAa,EAAE,CAAA;IAC1B,MAAM,QAAQ,GAAa,EAAE,CAAA;IAE7B,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3D,MAAM,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;QAC3C,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;YACnC,MAAM,MAAM,GAAG,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;YACvD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,QAAQ,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,GAAG,EAAE,CAAC,CAAA;gBACpC,SAAQ;YACV,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;gBAC7C,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,CAAA;gBAC/B,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;gBACzD,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;YACxC,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,QAAQ,CAAC,IAAI,CAAC,UAAU,KAAK,CAAC,GAAG,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;YACjG,CAAC;QACH,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YAC5C,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,8BAA8B,CAAC,CAAA;QACpF,CAAC;IACH,CAAC;SAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;QACrC,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,MAAM;YAAE,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC,CAAA;QAC1E,KAAK,CAAC,IAAI,CAAC,oCAAoC,CAAC,CAAA;IAClD,CAAC;IAED,MAAM,aAAa,GAAG,gBAAgB,CACpC,OAAO,CAAC,OAAO,EACf,IAAI,GAAG,CAAC,CAAC,GAAG,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,mBAAmB,IAAI,MAAM,IAAI,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAC3G,CAAA;IAED,MAAM,QAAQ,GAA4B;QACxC,GAAG,CAAC,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;QAC3B,aAAa,EAAE,OAAO,CAAC,YAAY;QACnC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,YAAY,EAAE,OAAO,CAAC,WAAW;QACjC,eAAe,EAAE,MAAM;QACvB,wBAAwB,EAAE,CAAC;QAC3B,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAClE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,mBAAmB,IAAI,MAAM,IAAI,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;KACvF,CAAA;IAED,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,UAAU,CAAA;IAC3D,4CAA4C;IAC5C,MAAM,oBAAoB,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC;SACjE,MAAM,CAAC,CAAC,GAAkB,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC;SAC3C,GAAG,CAAC,CAAC,GAAkB,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IACtC,OAAO,CAAC,oBAAoB,GAAG,oBAAoB,CAAA;IACnD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,IAAI,EAAE,IAAI,OAAO,CAAC,KAAK,CAAA;IACpD,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,CAAA;IAErC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;QACtB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC;YAC7C,UAAU,EAAE,UAAwB;YACpC,KAAK;YACL,OAAO,EAAE,aAAa;YACtB,UAAU;YACV,QAAQ;YACR,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAyB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC3E,CAAC,CAAA;QAEF,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,EAAE,IAAI,IAAI,wBAAwB,CAAA;YAC3D,OAAO,OAAO,CACZ,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,EAC/D,IAAI,EACJ,MAAM,CAAC,KAAK,EAAE,OAAO,IAAI,WAAW,EACpC,KAAK,EACL,MAAM,CAAC,KAAK,EAAE,UAAU,IAAI,aAAa,CAAC,IAAI,EAAE,oBAAoB,CAAC,CACtE,CAAA;QACH,CAAC;QAED,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAA;QACrC,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAA;QACnC,MAAM,SAAS,GAAG,cAAc,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAA;QAC1F,KAAK,CAAC,IAAI,CAAC,2DAA2D,CAAC,CAAA;QAEvE,OAAO,OAAO,CACZ;YACE,MAAM;YACN,QAAQ;YACR,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrC,aAAa,EAAE,OAAO,CAAC,aAAa;YACpC,UAAU;YACV,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,YAAY,EAAE,OAAO,CAAC,YAAY;YAClC,MAAM,EAAE,OAAO,CAAC,MAAM;YACtB,UAAU;YACV,kBAAkB,EAAE,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;YACvD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;YAClD,MAAM,EAAE,MAAM;YACd,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,UAAU,CAAC,OAAO,CAAC,aAAa,EAAE,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5F,SAAS;YACT,KAAK;SACN,EACD,QAAQ,CACT,CAAA;IACH,CAAC;IAED,+DAA+D;IAC/D,MAAM,OAAO,GAAG,cAAc,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,2BAA2B,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC,CAAA;IACrH,OAAO,OAAO,CACZ;QACE,MAAM;QACN,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,UAAU;QACV,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU;QACV,kBAAkB,EAAE,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;QACvD,oBAAoB,EAAE,OAAO,CAAC,oBAAoB;QAClD,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QAC3H,SAAS,EAAE,OAAO;QAClB,KAAK,EAAE,CAAC,GAAG,KAAK,EAAE,OAAO,oBAAoB,SAAS,mBAAmB,IAAI,MAAM,GAAG,CAAC;KACxF,CACF,CAAA;AACH,CAAC;AAED,SAAS,UAAU,CAAC,IAAY,EAAE,IAAY;IAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;AAC/E,CAAC;AAED,SAAS,YAAY,CAAC,MAAc,EAAE,aAAqB,EAAE,UAA8B;IACzF,OAAO;QACL,MAAM;QACN,aAAa;QACb,UAAU,EAAE,EAAE;QACd,WAAW,EAAE,EAAE;QACf,YAAY,EAAE,EAAE;QAChB,MAAM,EAAE,EAAE;QACV,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,UAAU;QAC5C,kBAAkB,EAAE,OAAO,CAAC,UAAU,EAAE,IAAI,EAAE,CAAC;QAC/C,oBAAoB,EAAE,EAAE;QACxB,MAAM,EAAE,EAAE;QACV,SAAS,EAAE,EAAE,WAAW,EAAE,YAAY,EAAE,UAAU,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,iBAAiB,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,EAAE;QACtH,KAAK,EAAE,EAAE;KACV,CAAA;AACH,CAAC;AAED,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,CAAA"}

package/lib/types/convert/settings-schema.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 转换设置的 schema（纯数据，单独一个模块）。
+ *
+ * 与 `src/intent/settings-schema.ts` 同一个理由：0.1.7 之后它要被 `Config` 组合、
+ * 并被 `tests/settings-schema.test.mjs` 独立解析一遍，而 `host.ts` 会 `import`
+ * 工具层 —— 那条依赖在 `node --test` 里拉不起来（`dsh-tools` 的
+ * `@deepseek-ai/dsh-sandbox` 是未安装的 peer）。
+ *
+ * 0029 起这里**没有路径字段**：交付物与工作区都从知识插件的 `agentRoot` 推出来
+ * （`<agentRoot>/output/<日期>/`、`<agentRoot>/tmp/`）。一个 Agent 只有一个根路径，
+ * 所以这里再放一个 `rootDir` 就等于把「东西存在哪」这个答案劈成两半。
+ *
+ * @module
+ */
+import { type ConvertPluginConfig } from './types.js';
+/** 显式标注是为了 TS2742（见 `intent/settings-schema.ts` 上的同一条注释）。 */
+export declare const CONVERT_SETTINGS_SCHEMA: Schemastery<ConvertPluginConfig>;
+//# sourceMappingURL=settings-schema.d.ts.map

package/lib/types/convert/settings-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-schema.d.ts","sourceRoot":"","sources":["../../../src/convert/settings-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAA0B,KAAK,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAE7E,6DAA6D;AAC7D,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,mBAAmB,CAMlE,CAAA"}

package/lib/types/convert/settings-schema.js

@@ -0,0 +1,26 @@
+/**
+ * 转换设置的 schema（纯数据，单独一个模块）。
+ *
+ * 与 `src/intent/settings-schema.ts` 同一个理由：0.1.7 之后它要被 `Config` 组合、
+ * 并被 `tests/settings-schema.test.mjs` 独立解析一遍，而 `host.ts` 会 `import`
+ * 工具层 —— 那条依赖在 `node --test` 里拉不起来（`dsh-tools` 的
+ * `@deepseek-ai/dsh-sandbox` 是未安装的 peer）。
+ *
+ * 0029 起这里**没有路径字段**：交付物与工作区都从知识插件的 `agentRoot` 推出来
+ * （`<agentRoot>/output/<日期>/`、`<agentRoot>/tmp/`）。一个 Agent 只有一个根路径，
+ * 所以这里再放一个 `rootDir` 就等于把「东西存在哪」这个答案劈成两半。
+ *
+ * @module
+ */
+import z from '@deepseek-ai/schemastery';
+import { volatileFields } from '../settings-volatile.js';
+import { DEFAULT_CONVERT_CONFIG } from './types.js';
+/** 显式标注是为了 TS2742（见 `intent/settings-schema.ts` 上的同一条注释）。 */
+export const CONVERT_SETTINGS_SCHEMA = z.object(volatileFields({
+    maxConcurrent: z.number().step(1).min(1).max(8).default(DEFAULT_CONVERT_CONFIG.maxConcurrent),
+    maxInputBytes: z.number().step(1).min(1024).default(DEFAULT_CONVERT_CONFIG.maxInputBytes),
+    retentionDays: z.number().step(1).max(365).default(DEFAULT_CONVERT_CONFIG.retentionDays),
+    toolWaitMs: z.number().step(1).min(1000).max(900000).default(DEFAULT_CONVERT_CONFIG.toolWaitMs),
+    ingestEnabled: z.boolean().default(DEFAULT_CONVERT_CONFIG.ingestEnabled),
+}));
+//# sourceMappingURL=settings-schema.js.map

package/lib/types/convert/settings-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings-schema.js","sourceRoot":"","sources":["../../../src/convert/settings-schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAA;AACxD,OAAO,EAAE,sBAAsB,EAA4B,MAAM,YAAY,CAAA;AAE7E,6DAA6D;AAC7D,MAAM,CAAC,MAAM,uBAAuB,GAAqC,CAAC,CAAC,MAAM,CAAC,cAAc,CAAC;IAC/F,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC,aAAa,CAAC;IAC7F,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC,aAAa,CAAC;IACzF,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC,aAAa,CAAC;IACxF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAAC,UAAU,CAAC;IAC/F,aAAa,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,sBAAsB,CAAC,aAAa,CAAC;CACzE,CAAC,CAAC,CAAA"}

package/lib/types/convert/types.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Plugin-level types, defaults and the envelope shape for the **convert seam**.
+ *
+ * These live inside `data-knowledge` since 0018: conversion is a sub-capability
+ * of the knowledge plugin, not a separately mounted plugin. The kernel itself
+ * (`dsh-convert-core`) stays an independent, optional package.
+ */
+export declare const CONVERT_SETTINGS_NAMESPACE = "tita-data-agent-convert";
+/** Knowledge store layout the convert seam cooperates with (issue 0013). */
+export declare const KNOWLEDGE_SOURCE_DIR = "01_source_truth";
+export declare const KNOWLEDGE_WIKI_DIR = "02_wiki";
+/** Sub-directory inside `01_source_truth` that holds converted images. */
+export declare const KNOWLEDGE_ASSET_DIR = "_assets";
+export interface ConvertPluginConfig {
+    maxConcurrent: number;
+    maxInputBytes: number;
+    /** Deliveries older than this are pruned on start; 0 disables. */
+    retentionDays: number;
+    /** How long a tool call waits for the conversion before returning `running`. */
+    toolWaitMs: number;
+    /** Allow `convert_ingest` to write into the knowledge store. */
+    ingestEnabled: boolean;
+}
+/**
+ * @deprecated 0029：转换不再有自己的根目录。交付物落
+ * `<agentRoot>/output/<日期>/`、工作区落 `<agentRoot>/tmp/<日期>/`，
+ * 由 `layout.ts` 统一算出来。这个函数只留给**独立运行的内核**
+ * （`bin/tita-convert.mjs`）与它的单测，插件侧不再读它。
+ */
+export declare function defaultConvertRoot(): string;
+export declare const DEFAULT_CONVERT_CONFIG: ConvertPluginConfig;
+export interface Envelope<T> {
+    ok: boolean;
+    data: T;
+    warnings?: string[];
+    error?: {
+        code: string;
+        message: string;
+        suggestion?: string;
+        retryable?: boolean;
+    };
+}
+export declare function success<T>(data: T, warnings?: string[]): Envelope<T>;
+export declare function failure<T>(data: T, code: string, message: string, retryable?: boolean, suggestion?: string): Envelope<T>;
+export declare const WRITE_TOOLS: readonly ["convert_source", "convert_ingest"];
+//# sourceMappingURL=types.d.ts.map

package/lib/types/convert/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/convert/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,eAAO,MAAM,0BAA0B,4BAA4B,CAAA;AAEnE,4EAA4E;AAC5E,eAAO,MAAM,oBAAoB,oBAAoB,CAAA;AACrD,eAAO,MAAM,kBAAkB,YAAY,CAAA;AAC3C,0EAA0E;AAC1E,eAAO,MAAM,mBAAmB,YAAY,CAAA;AAE5C,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAA;IACrB,aAAa,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAA;IACrB,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAA;IAClB,gEAAgE;IAChE,aAAa,EAAE,OAAO,CAAA;CACvB;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAG3C;AAED,eAAO,MAAM,sBAAsB,EAAE,mBAMpC,CAAA;AAED,MAAM,WAAW,QAAQ,CAAC,CAAC;IACzB,EAAE,EAAE,OAAO,CAAA;IACX,IAAI,EAAE,CAAC,CAAA;IACP,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CACpF;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEpE;AAED,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,UAAQ,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,CAEtH;AAED,eAAO,MAAM,WAAW,+CAAgD,CAAA"}

package/lib/types/convert/types.js

@@ -0,0 +1,41 @@
+/**
+ * Plugin-level types, defaults and the envelope shape for the **convert seam**.
+ *
+ * These live inside `data-knowledge` since 0018: conversion is a sub-capability
+ * of the knowledge plugin, not a separately mounted plugin. The kernel itself
+ * (`dsh-convert-core`) stays an independent, optional package.
+ */
+import { homedir } from 'node:os';
+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_WIKI_DIR = '02_wiki';
+/** Sub-directory inside `01_source_truth` that holds converted images. */
+export const KNOWLEDGE_ASSET_DIR = '_assets';
+/**
+ * @deprecated 0029：转换不再有自己的根目录。交付物落
+ * `<agentRoot>/output/<日期>/`、工作区落 `<agentRoot>/tmp/<日期>/`，
+ * 由 `layout.ts` 统一算出来。这个函数只留给**独立运行的内核**
+ * （`bin/tita-convert.mjs`）与它的单测，插件侧不再读它。
+ */
+export function defaultConvertRoot() {
+    if (process.env.DSH_CONVERT_ROOT)
+        return process.env.DSH_CONVERT_ROOT;
+    return join(homedir(), '.tita-data-agent', 'convert');
+}
+export const DEFAULT_CONVERT_CONFIG = {
+    maxConcurrent: 2,
+    maxInputBytes: 256 * 1024 * 1024,
+    retentionDays: 14,
+    toolWaitMs: 120_000,
+    ingestEnabled: true,
+};
+export function success(data, warnings) {
+    return { ok: true, data, ...(warnings && warnings.length > 0 ? { warnings } : {}) };
+}
+export function failure(data, code, message, retryable = false, suggestion) {
+    return { ok: false, data, error: { code, message, retryable, ...(suggestion ? { suggestion } : {}) } };
+}
+export const WRITE_TOOLS = ['convert_source', 'convert_ingest'];
+//# sourceMappingURL=types.js.map

package/lib/types/convert/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/convert/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAEhC,MAAM,CAAC,MAAM,0BAA0B,GAAG,yBAAyB,CAAA;AAEnE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,oBAAoB,GAAG,iBAAiB,CAAA;AACrD,MAAM,CAAC,MAAM,kBAAkB,GAAG,SAAS,CAAA;AAC3C,0EAA0E;AAC1E,MAAM,CAAC,MAAM,mBAAmB,GAAG,SAAS,CAAA;AAa5C;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB;IAChC,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB;QAAE,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAA;IACrE,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,kBAAkB,EAAE,SAAS,CAAC,CAAA;AACvD,CAAC;AAED,MAAM,CAAC,MAAM,sBAAsB,GAAwB;IACzD,aAAa,EAAE,CAAC;IAChB,aAAa,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IAChC,aAAa,EAAE,EAAE;IACjB,UAAU,EAAE,OAAO;IACnB,aAAa,EAAE,IAAI;CACpB,CAAA;AASD,MAAM,UAAU,OAAO,CAAI,IAAO,EAAE,QAAmB;IACrD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAA;AACrF,CAAC;AAED,MAAM,UAAU,OAAO,CAAI,IAAO,EAAE,IAAY,EAAE,OAAe,EAAE,SAAS,GAAG,KAAK,EAAE,UAAmB;IACvG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAA;AACxG,CAAC;AAED,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,gBAAgB,EAAE,gBAAgB,CAAU,CAAA"}

package/lib/types/diagnosis/cards.d.ts

@@ -0,0 +1,71 @@
+import { type DiagnosisEntityType } from './schema.js';
+import type { AttributionCase } from './seed.js';
+import type { AttributionEdgeKind, AttributionGraphData, AttributionNodeKind } from './types.js';
+export interface DiagnosisCardSection {
+    heading: string;
+    body: string;
+}
+export interface DiagnosisCard {
+    entityId: string;
+    entityType: DiagnosisEntityType;
+    title: string;
+    /** 一句话说明。落到节点上是 `summary`（现象上是 `observable`）。 */
+    summary?: string;
+    status: string;
+    owner?: string;
+    sourceRefs: string[];
+    updatedAt?: string;
+    /** 正文小节，顺序按 spec。 */
+    sections: DiagnosisCardSection[];
+    /** 结构化块。字段随 entity_type 而定，见 `CARD_LAYOUT`。 */
+    block: Record<string, unknown>;
+}
+/** 卡片不声明状态时的默认值：它已经被人写过一遍，只是还没走评审流程。 */
+export declare const DEFAULT_CARD_STATUS = "reviewed";
+/** 反向查表：节点 kind → 卡片 entity_type。`asset` 与执行产物没有卡片。 */
+export declare function entityTypeOf(kind: AttributionNodeKind): DiagnosisEntityType | undefined;
+/** 卡片能定义的节点类型。其余（asset / evidence / cause / unknown）不走卡片。 */
+export declare const CARD_NODE_KINDS: AttributionNodeKind[];
+/** 卡片能定义的边：全部是卡片字段的确定性投影。 */
+export declare const CARD_EDGE_KINDS: AttributionEdgeKind[];
+/** 一次排查写下的边。它们不属于任何卡片，见文件头的边界表。 */
+export declare const RUN_EDGE_KINDS: AttributionEdgeKind[];
+/**
+ * 卡片 → markdown 文本。
+ *
+ * 结构化块放在**正文里**而不是 front matter 的 JSON 里：改一个字段就从「一个几百字符的
+ * 长行整体重写」变成「一行改动」，review 时才看得出改了哪条判据、哪一步顺序。
+ * 这正是 §6.3 把三段分开的理由。
+ */
+export declare function serializeCard(card: DiagnosisCard): string;
+export declare function parseCard(source: string): DiagnosisCard | undefined;
+/**
+ * 类型层与案例 → 卡片。
+ *
+ * `asset` / `evidence` / `cause` 节点**不产出卡片**：它们不是手写的知识（§6.4）。
+ * 被假设引用的资产会在反序列化时按 id 补一个最小节点回来。
+ */
+export declare function graphToCards(graph: AttributionGraphData, cases?: AttributionCase[]): DiagnosisCard[];
+export interface CompiledDiagnosis {
+    graph: AttributionGraphData;
+    cases: AttributionCase[];
+    /** 卡片之间的关系（引用完整性等）；节点字段校验仍走 `validateDiagnosis`。 */
+    problems: string[];
+}
+/**
+ * 卡片 → 图。
+ *
+ * 只产出「卡片定义得了」的那部分（类型层 + 引用层的资产 + 案例，以及五种卡片边）；
+ * `evidence` / `cause` 与四条执行边由一次排查写入，不在这里合成 —— 否则一次执行的结果
+ * 会被伪装成可复用的知识。
+ */
+export declare function cardsToGraph(cards: DiagnosisCard[]): CompiledDiagnosis;
+/**
+ * 卡片在磁盘上的相对路径：`02_wiki/<entity_type>/<slug(entity_id)>.md`。
+ *
+ * `entity_type` 里的斜杠是**目录层级**（五类排查卡片因此落在 `02_wiki/diagnosis/` 下，
+ * 与其它 wiki 子树分开），不是要压成横杠 —— 我一开始压了，结果写进去的卡片和编译器去读的
+ * 路径差一层目录，而失败是静默的：读不到，就只是图上少几条边。
+ */
+export declare function cardPathOf(card: DiagnosisCard): string;
+//# sourceMappingURL=cards.d.ts.map

package/lib/types/diagnosis/cards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cards.d.ts","sourceRoot":"","sources":["../../../src/diagnosis/cards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,mBAAmB,EAAE,MAAM,aAAa,CAAA;AAC1E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAChD,OAAO,KAAK,EACO,mBAAmB,EAAE,oBAAoB,EAAmB,mBAAmB,EAEjG,MAAM,YAAY,CAAA;AAwCnB,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,mBAAmB,CAAA;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,qBAAqB;IACrB,QAAQ,EAAE,oBAAoB,EAAE,CAAA;IAChC,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC/B;AAED,wCAAwC;AACxC,eAAO,MAAM,mBAAmB,aAAa,CAAA;AAgC7C,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,mBAAmB,GAAG,SAAS,CAEvF;AAED,6DAA6D;AAC7D,eAAO,MAAM,eAAe,EAAE,mBAAmB,EAA8C,CAAA;AAE/F,6BAA6B;AAC7B,eAAO,MAAM,eAAe,EAAE,mBAAmB,EAEhD,CAAA;AAED,mCAAmC;AACnC,eAAO,MAAM,cAAc,EAAE,mBAAmB,EAAwD,CAAA;AAQxG;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAiBzD;AAID,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CA+BnE;AAoDD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,oBAAoB,EAAE,KAAK,GAAE,eAAe,EAAO,GAAG,aAAa,EAAE,CA8ExG;AAID,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,oBAAoB,CAAA;IAC3B,KAAK,EAAE,eAAe,EAAE,CAAA;IACxB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,iBAAiB,CA+HtE;AA2BD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAEtD"}