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

package/lib/types/types.d.ts

@@ -0,0 +1,799 @@
+export type KnowledgeStatus = 'unreviewed' | 'draft' | 'reviewed' | 'active' | 'deprecated' | 'problem';
+/**
+ * 内置来源业务分类的 id（0013 注册表）。
+ *
+ * 注册表允许用户追加自定义分类，所以**运行时一律按 `string` 处理**
+ * （见 `SourceType`）；这个字面量联合只用来标记哪些 id 是内置的。
+ */
+export type BuiltinSourceType = 'chat_message' | 'ai_chat_message' | 'document' | 'book' | 'article' | 'prd' | 'question';
+/** 来源业务分类 id。自定义分类是开放集合，所以不是字面量联合。 */
+export type SourceType = string;
+/**
+ * 知识卡片的 entity_type 白名单。
+ *
+ * **智能归因的五类也在这里**，这不是放宽而是纠错：排查思路本来就应该是一张 wiki 卡片
+ * （0021 §6.4 定了五类实体与三段式卡片），但白名单里没有它们的时候，`writeCard` 会直接
+ * 返回 `SCHEMA_TYPE_INVALID`，`readCards` 也会跳过 —— 于是排查思路**永远进不了 wikiNotes，
+ * 也就永远召不回来**。列表本身在 `diagnosis/schema.ts` 里定义一次，这里只做联合。
+ */
+export type SchemaType = 'concept' | 'metric' | 'table' | 'event' | 'playbook' | 'case' | 'diagnosis/symptom' | 'diagnosis/hypothesis' | 'diagnosis/check' | 'diagnosis/failure-mode' | 'diagnosis/case';
+export type EmbeddingProvider = 'wemm-python' | 'ollama' | 'none';
+export type EmbeddingDevice = 'auto' | 'mps' | 'cpu';
+export type RerankProvider = 'bert-python' | 'none';
+/** 真正跑起来的召回路线。`graph` 是 0021 加入的知识图谱路。 */
+export type RecallRoute = 'fts' | 'vector' | 'graph';
+/**
+ * 召回路线选择（0031 起语义有变）。
+ *
+ * `graph` 与 `hybrid` **同义**：知识图谱从「第三路」降成了 boost，它不能凭自己制造
+ * 候选，只给已经在候选池里的条目加权（见 `recallBoost`/`graphBoost`）。所以「只靠图谱」
+ * 的召回在设计上不成立，保留这个取值只为兼容已存的设置与调用方。
+ */
+export type RecallMode = 'fts' | 'vector' | 'graph' | 'hybrid';
+import type { DataError, Envelope as WireEnvelope } from 'dsh-data-contracts/envelope';
+import type { LineageContext, LineageRef } from 'dsh-data-contracts/refs';
+export interface KnowledgeError extends DataError {
+    code: string;
+    message: string;
+    retryable: boolean;
+    suggestion?: string;
+}
+/**
+ * This plugin's envelope: the shared five-key wire contract
+ * (`spec/contracts/envelope.json`) with the error narrowed to `KnowledgeError`,
+ * so `retryable` / `suggestion` stay visible to callers and the panel.
+ *
+ * The shape itself lives in `dsh-data-contracts` — the status rule
+ * "warnings make it partial" is defined once there, not re-spelled here.
+ */
+export type Envelope<T> = WireEnvelope<T, KnowledgeError>;
+export interface KnowledgeConfig {
+    /**
+     * **Tita Agent 根路径** —— 用户唯一要设的那个路径（0029）。
+     *
+     * 根路径下固定四段：`domain_knowledge/`（知识树，按知识库 id 分叉）、
+     * `output/`（交付物，二级按日期）、`tmp/`（运行期临时文件，二级按日期）、
+     * `resource/`（模型、Python 环境、注册表）。
+     * 四段为什么这么分，见 `layout.ts` 顶部的四条原理。
+     */
+    agentRoot: string;
+    /**
+     * @deprecated 0029：这是**旧布局**的知识树根（`01_source_truth` 直接躺在它
+     * 下面）。它不再可设置，也不再决定任何路径 —— 只作为一次性的迁移来源存在：
+     * 值非空且新位置还是空的时，把旧树搬进 `<agentRoot>/domain_knowledge/default`。
+     * 搬完（或本来就没有）它就不再有意义。
+     */
+    rootDir: string;
+    schemaTypes: SchemaType[];
+    /**
+     * @deprecated 0013：来源分类改为**按知识库持久化的注册表**
+     * （`KnowledgeBase.sourceTypes` / `00_schema/source-types.json` 语义）。
+     * 这个字段只是历史 settings JSON 的兼容壳，既不参与 `addSource` 校验，
+     * 也不再暴露在设置面板里；判定与校验一律走注册表。
+     */
+    sourceAppendTypes: SourceType[];
+    allowSourceTruth: boolean;
+    /**
+     * Pass 0（候选抽取 + 归一）的总开关。
+     *
+     * 默认**开**：它是「SourceRaw → Wiki」这条链上唯一不依赖模型的一步，关掉之后
+     * 知识库就只能靠 Agent 逐张 `write_knowledge_card` 长大。关掉的场景是真实存在的
+     * （批量导入时不想让每份文档都自动长出一张未审核卡片），所以它必须可关，
+     * 但关掉不等于删除：计数器会如实回 0，而不是假装抽过了。
+     */
+    extractCandidates: boolean;
+    /**
+     * #3b：用模型做**实体抽取与归并**（`extract-model.ts`）。
+     *
+     * 开着时，`rebuild` 把「这份来源里有哪些实体、其中哪些 wiki 里已经有了」交给模型；
+     * 关系候选仍由规则抽取补上，模型不可用则整轮退回规则。所以它是**增强**而不是依赖 ——
+     * 关掉它链路照跑，只是同一实体横跨两份文档时可能落成两张卡（实测过）。
+     *
+     * 触发时机跟着来源走：只有**变化的来源**才进这一轮（增量复用没变的不重跑），
+     * 所以成本与「改了多少来源」成正比，而不是与库的大小成正比。
+     */
+    extractWithModel: boolean;
+    /** Python 解释器。空串 = 自动（`<agentRoot>/resource/python/bin/python`，退回旧家当目录，再退回 `python3`）。 */
+    python: string;
+    embeddingProvider: EmbeddingProvider;
+    embeddingBaseUrl: string;
+    /** 嵌入模型：一个本地目录或一个 HF 模型名。空串 = 自动（根路径下的本地模型，退回旧家当目录，再退回 HF 名）。 */
+    embeddingModel: string;
+    embeddingDimension: number;
+    embeddingBatchSize: number;
+    embeddingTimeoutMs: number;
+    embeddingDevice: EmbeddingDevice;
+    /** Stage 3 recall: how many wikiNotes the multi-route recall may return. */
+    recallTopK: number;
+    /**
+     * Stage 3 的**候选池**深度：融合之前每一路各自超采多少条（0031）。
+     *
+     * 它和 `recallTopK` 是两件事，0014 早就点明过：前者是「先粗召回多少」，
+     * 后者是「最终给模型多少」。两者共用一个数时，重排只能给已经截断的列表换顺序，
+     * 永远救不回被融合排到窗口外的那一条。默认 50（与 WeKnora 的 `EmbeddingTopK` 一致）。
+     */
+    recallCandidatePool: number;
+    /** Stage 3 recall: default route when a caller does not pass `mode`. */
+    recallMode: RecallMode;
+    /**
+     * 关键词路的最低分（归一化 BM25，0..1）。低于它不进候选池。
+     *
+     * 注意它是**相对**阈值（按本次查询的最高分归一），所以它挡得住「弱命中」，
+     * 挡不住「整批都弱」；真正的绝对闸门是 `rerankThreshold`。
+     */
+    keywordThreshold: number;
+    /** 向量路的最低相似度（原始余弦，−1..1）。这是**绝对**阈值，可直接用于弃答。 */
+    vectorThreshold: number;
+    /** Stage 4 rerank: how many reranked wikiNotes enter the model context. */
+    contextTopN: number;
+    /**
+     * Stage 4 重排后的最低分（0..1，sigmoid 之后的 cross-encoder 分）。
+     *
+     * 它是整条链路里唯一**跨查询可比**的相关性判据，所以「弃答」主要靠它。
+     */
+    rerankThreshold: number;
+    /** Stage 4 rerank: BERT cross-encoder provider, or `none` to skip reranking. */
+    rerankProvider: RerankProvider;
+    /** 重排模型：同上。空串 = 自动。 */
+    rerankModel: string;
+    rerankTimeoutMs: number;
+}
+/**
+ * 旧的「家当」目录（0029 之前模型与虚拟环境住在这里）。
+ *
+ * 现在它们是**兜底**：路径解析优先看 `<agentRoot>/resource/`，找不到再回这里，
+ * 最后才退回裸的模型名（从 HuggingFace 拉）。这样搬完家当、或还没搬完家当，
+ * 行为都对；而 `TITA_DATA_AGENT_HOME` 仍然是覆盖它的入口。
+ */
+export declare const legacyResourceHome: () => string;
+/** 本地模型目录名。与 `layout.ts` 的 `resourceModels()` 拼在一起就是主位置。 */
+export declare const LOCAL_EMBEDDING_MODEL_DIR = "WeMM-Embedding-2B-Quantized";
+export declare const LOCAL_RERANK_MODEL_DIR = "bge-reranker-base";
+/** 裸模型名：本地没有时从 HuggingFace 拉。 */
+export declare const FALLBACK_EMBEDDING_MODEL = "ewin-reg/WeMM-Embedding-2B-Quantized";
+export declare const FALLBACK_RERANK_MODEL = "BAAI/bge-reranker-base";
+/**
+ * 一个**知识库运行时**需要的那部分配置。
+ *
+ * 去掉的是两个**路径**字段：运行时是「一个知识库」的视角，它的根由构造参数单独
+ * 传入（`rootDir`），而 `agentRoot` 是整个部署的根路径 —— 运行时既不该拥有它，
+ * 也不该从它推自己的位置。两个字段留在 `KnowledgeConfig` 里，是因为设置面板要
+ * 编辑 `agentRoot`、迁移要读旧的 `rootDir`。
+ */
+export type RuntimeKnowledgeConfig = Omit<KnowledgeConfig, 'rootDir' | 'agentRoot'>;
+/**
+ * 除两个路径字段以外的全部默认值。
+ *
+ * `agentRoot` / `rootDir` 由 `index.ts` 用 `layout.ts` 算出来再合进来 —— 它们是
+ * 环境与磁盘事实（桌面在哪、旧树在不在），不是这张常量表能自己回答的。
+ */
+export declare const DEFAULT_KNOWLEDGE_CONFIG: RuntimeKnowledgeConfig;
+/** 一条原始可追溯文档（SourceRaw）。磁盘布局沿用 `01_source_truth`。 */
+export interface SourceRaw {
+    sourceId: string;
+    sourceType: SourceType;
+    title: string;
+    content: string;
+    externalId?: string;
+    metadata: Record<string, unknown>;
+    lineage?: LineageContext;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * `query_source_truth` 读回来的一条来源：`SourceRaw` + **它在磁盘上的位置**。
+ *
+ * ## 为什么必须带 `path`
+ *
+ * 读取有配额（一次最多 `max_chars`，上限 40000 字符），而且配额是**跨多条来源共享**
+ * 的 —— 一份长文档很容易只回来一个开头。被截断时 `content` 是**不完整**的，而「不完整」
+ * 如果只能靠调用方拿长度自己猜，就会出最坏的那种错：以为读到了全文，其实只有前 4 万字符。
+ *
+ * 所以每条都给出绝对路径与全长：Agent 看到 `returnedChars < totalChars` 就知道该去读
+ * 文件原文（它本来就有读文件的能力），而不是基于半份文档下结论。这个路径是知识库里的
+ * **真实文件**，读它与读这里的内容是同一份数据。
+ */
+export interface SourceRawRead extends SourceRaw {
+    /** 这份来源在磁盘上的绝对路径。 */
+    path: string;
+    /** 本次实际返回的字符数。 */
+    returnedChars: number;
+    /** 这份来源正文的完整字符数。`returnedChars < totalChars` 即被截断。 */
+    totalChars: number;
+}
+export interface KnowledgeCard {
+    entityId: string;
+    entityType: SchemaType;
+    title: string;
+    status: KnowledgeStatus;
+    summary?: string;
+    content: string;
+    sourceRefs: string[];
+    provenance?: LineageRef[];
+    metadata: Record<string, unknown>;
+    updatedAt: string;
+    /** Resolved local markdown image references used by the multimodal embedder. */
+    imagePaths?: string[];
+}
+/**
+ * A compiled recall unit. Stage 2 turns every wiki card into one or more
+ * wikiNotes; stage 3 recalls wikiNotes (never the wiki directly) and resolves
+ * each hit back to its parent wiki.
+ */
+export interface WikiNote {
+    /**
+     * Stable recall id. The first note of a wiki reuses `<entityType>:<entityId>`
+     * so historical qrels keep working; later notes append `#<n>`.
+     */
+    unitId: string;
+    /** Alias of `unitId`, in wikiNotes vocabulary. */
+    noteId: string;
+    entityId: string;
+    /** The wiki card this note was compiled from (alias of `entityId`). */
+    wikiId: string;
+    entityType: SchemaType;
+    title: string;
+    /** Section heading when a long wiki card was split into several notes. */
+    heading?: string;
+    content: string;
+    sourceRefs: string[];
+    sourceTypes: SourceType[];
+    provenance?: LineageRef[];
+    status: KnowledgeStatus;
+    /** Local markdown image references are embedded with the text when possible. */
+    imagePaths?: string[];
+}
+/** Backwards-compatible alias: compiled retrieval units are now wikiNotes. */
+export type KnowledgeUnit = WikiNote;
+/**
+ * One historical revision of a wiki card.
+ *
+ * Mirrors `DocumentVersion` on purpose: SourceRaw and wiki are the two content
+ * layers in this plugin, and a user who can roll a document back must be able to
+ * roll the card compiled from it back too. Snapshots live under
+ * `04_memory/card-versions/<entityType>/<entityId>/`, hold the *original card
+ * markdown bytes*, and are append-only — reverting snapshots the pre-revert head
+ * as well, so a rollback is itself reversible.
+ */
+export interface WikiCardVersion {
+    versionId: string;
+    createdAt: string;
+    contentHash: string;
+    bytes: number;
+    title: string;
+    status: string;
+    label: string;
+    isCurrent: boolean;
+}
+export interface SearchHit extends WikiNote {
+    score: number;
+    match: 'fts' | 'vector' | 'graph' | 'hybrid';
+    /**
+     * 这个命中在每一路里的**名次**（1 起，0031）。
+     *
+     * 融合改用 RRF 之后，名次是唯一进入融合的量 —— 所以它必须留痕：界面上的
+     * 「三路状态」、`match` 的推导、以及「为什么这条排第一」都读它。
+     * 缺失 = 那一路没有召回它。
+     */
+    ranks?: Partial<Record<RecallRoute, number>>;
+    /** 该命中引用的 SourceRaw 证据片段（0031）。可追溯从卡片级下沉到段落级。 */
+    evidence?: RecallEvidence[];
+}
+/**
+ * 一条命中的**证据片段**：它引用的 SourceRaw 里，与查询最相关的那一段原文。
+ *
+ * 为什么要有它：`context` 原来只带 wiki 卡片，模型要核对原文还得自己再调一次工具。
+ * 把证据放进上下文，「每一个数字都能指回它的口径定义与原始文档」才在**上下文层面**
+ * 成立，而不是靠模型自觉。
+ */
+export interface RecallEvidence {
+    sourceId: string;
+    title?: string;
+    /** 覆盖查询词最多的那一段原文（已按上限截断）。 */
+    excerpt: string;
+    /** 该段在原文正文里的字符偏移，便于回跳。 */
+    offset: number;
+    /** 这一段覆盖了查询词的比例（0..1）。 */
+    coverage: number;
+}
+export interface RecallHit extends SearchHit {
+    /** Cross-encoder score after stage 4 rerank; absent when rerank is skipped. */
+    rerankScore?: number;
+}
+export interface RerankResult {
+    status: 'ready' | 'unavailable' | 'skipped';
+    provider: RerankProvider;
+    model?: string;
+    scored?: number;
+    error?: string;
+    /** 这一轮生效的最低分（0031）。**原始 logit 刻度**，低于它的一律不进上下文。 */
+    threshold?: number;
+    /** 被阈值丢掉的条数 —— 「弃答」能不能发生，看的就是它。 */
+    dropped?: number;
+    /**
+     * 候选池里最高的 logit（0031）。
+     *
+     * 与 `dropped` 一起回答「这一批到底有多相关」：`dropped: 0` 有两种可能 ——
+     * 全都相关（topLogit 高），或者阈值根本没在工作（topLogit 贴近阈值）。
+     * 只报 `dropped` 会把这两种情况混成一个。
+     */
+    topLogit?: number;
+    /**
+     * cross-encoder 分词器的词表大小（0031）。
+     *
+     * 存在的理由是**回归可见性**：词表退化成 5 个特殊 token 时，模型照样返回分数、
+     * 照样 `status: ready`，只是所有输入都变成 `<unk>`（实测三条无关文本 0.998–0.9994）。
+     * 现在 worker 会在加载时直接报 `RERANK_TOKENIZER_DEGENERATE`，这个字段则让
+     * 「真的加载了 250002 条词表」在面板上看得见。
+     */
+    vocabSize?: number;
+}
+/**
+ * 一路在**这一轮**里的真实状态（0031）。
+ *
+ * 「降级不谎报」原来只体现在 `routes` 数组里，但 `routes` 只回答「跑没跑」，
+ * 回答不了「为什么没结果」。诊断把阈值、候选数、最高分一起给出，于是弃答
+ * （`insufficientEvidence`）不再是黑箱。
+ */
+export interface RecallRouteDiagnostic {
+    route: RecallRoute;
+    status: 'ran' | 'degraded' | 'skipped';
+    /** 过滤前该路超采到的候选数。 */
+    candidates?: number;
+    /** 过阈值之后剩下的条数。 */
+    kept?: number;
+    /** 该路的最高分（解释「为什么弃答」时最有用的一格）。 */
+    topScore?: number;
+    threshold?: number;
+    /** 降级 / 跳过的原因，直接给用户看。 */
+    reason?: string;
+}
+export interface RecallDiagnostics {
+    routes: RecallRouteDiagnostic[];
+    fusion: {
+        method: 'rrf';
+        k: number;
+        weights: Partial<Record<RecallRoute, number>>;
+    };
+    /** 图谱 boost 命中了多少条、权重多少。 */
+    graphBoost: {
+        applied: number;
+        weight: number;
+    };
+    /**
+     * 弃答判据的强度，如实标注：
+     * - `rerank-threshold`：重排跑通且**真的丢了东西** —— 跨查询可比的绝对判据；
+     * - `vector-threshold`：向量余弦阈值丢的（原始余弦也是绝对量）；
+     * - `relative-only`：只剩「按本次最高分归一」的相对阈值 —— 挡得住弱命中，挡不住
+     *   「整批都弱」；
+     * - `not-needed`：有结果且不需要判弃答。
+     */
+    abstention: 'rerank-threshold' | 'vector-threshold' | 'relative-only' | 'not-needed';
+    /** 向量索引与编码器的健康检查结论（0031 的 P0 门）。 */
+    encoder?: {
+        ok: boolean;
+        reason?: string;
+    };
+    /** 弃答时的一句话原因。 */
+    reason?: string;
+}
+export interface ContextGraph {
+    nodes: Array<Record<string, unknown>>;
+    edges: Array<Record<string, unknown>>;
+}
+export interface ContextItem {
+    note: RecallHit;
+    wiki: KnowledgeCard | null;
+    /** 1-hop subgraph around the hit's wiki card. */
+    graph: ContextGraph;
+    /**
+     * 这条命中引用的 SourceRaw 证据片段（0031）。
+     *
+     * 与 `note.evidence` 同源，放在这里是为了让「上下文包」自包含：读到 `context`
+     * 就拿到了「片段（为什么召回）→ 卡片（结论）→ 原文（证据）」三层。
+     */
+    evidence?: RecallEvidence[];
+}
+export interface RecallResult {
+    /** Stage 3: 融合（+ 重排）之后的 wikiNotes，最多 `recallTopK`。 */
+    hits: RecallHit[];
+    /** Stage 4: the `contextTopN` notes expanded to their wiki + 1-hop graph. */
+    context: ContextItem[];
+    /** Distinct wiki cards hit by the recalled notes. */
+    wiki: KnowledgeCard[];
+    /** Union of the 1-hop subgraphs of the recalled wiki cards. */
+    graph: ContextGraph;
+    backend: string;
+    routes: RecallRoute[];
+    /** Route actually used (caller override or the configured default). */
+    recallMode: RecallMode;
+    rerank: RerankResult;
+    recallTopK: number;
+    /** 融合之前每一路的超采深度（0031）。 */
+    candidatePool: number;
+    contextTopN: number;
+    /**
+     * 一路都没过阈值 = 这个知识库里没有能回答这个问题的东西（0031）。
+     *
+     * 它是产品诚实性的一部分：与其凑满 5 条噪声让模型编，不如明确说「没有」。
+     * 消费方（Agent 工具 / 面板）看到 true 就该如实转述，而不是把 `hits: []`
+     * 当成一次失败。
+     */
+    insufficientEvidence: boolean;
+    /** 每一路在这一轮里发生了什么（阈值、候选数、最高分、降级原因）。 */
+    diagnostics: RecallDiagnostics;
+    recallId: string;
+    indexVersion?: number;
+    compileRunId?: string;
+    lineage?: LineageContext;
+}
+/** 一个知识库 = 独立配置 + 独立内容根目录。 */
+export interface KnowledgeBase {
+    id: string;
+    name: string;
+    description: string;
+    rootDir: string;
+    isDefault: boolean;
+    /**
+     * 来源业务分类注册表（0013），与 `wikiTypes` 平级、同样按库持久化。
+     * `fileCount` / `sourceCount` 这类计算字段由 refresh 实时算出。
+     */
+    sourceTypes: SourceTypeDef[];
+    /**
+     * Wiki 卡片类型注册表（0024）：决定"SourceRaw → Wiki"这一段能生成哪些类型的卡片、
+     * 每类卡片必须有哪些小节与字段。与 `sourceTypes` 同处持久化，理由见 0013 §7.1。
+     */
+    wikiTypes: WikiTypeDef[];
+    /**
+     * 卡片 schema 的生效方式：`report` 只把问题写进卡片并回报，`strict` 直接拒绝不合规的写入。
+     * 默认 `report`，避免存量卡片在升级后被挡在门外。
+     */
+    wikiSchemaMode: WikiSchemaMode;
+    /**
+     * 计算字段：当前 `wikiTypes` 是否已偏离出厂定义。界面据此决定「恢复默认」是否可点，
+     * 也让人一眼看出这套 schema 是本库自己调过的。
+     */
+    wikiTypesCustomized: boolean;
+    createdAt: string;
+    updatedAt: string;
+    sourceCount: number;
+    cardCount: number;
+    noteCount: number;
+    buildVersion: number;
+}
+/** 文档列表项（SourceRaw 的对外投影，不含正文）。 */
+export interface KnowledgeDocument {
+    /** = SourceRaw.sourceId */
+    docId: string;
+    title: string;
+    sourceType: string;
+    /**
+     * `sourceType` 是否仍在当前知识库的注册表里。
+     *
+     * 0013 之前 `loadSources()` 会把未知分类**静默丢弃**，文档凭空消失；
+     * 现在一律保留并把这个标记交给前端渲染成「未知分类」徽标。
+     */
+    sourceTypeKnown: boolean;
+    sourceFormat: string;
+    parser: string;
+    externalId: string;
+    contentHash: string;
+    bytes: number;
+    assetCount: number;
+    createdAt: string;
+    updatedAt: string;
+    versionCount: number;
+    /** 相对知识库根目录，如 `01_source_truth/<slug>.md`。 */
+    relativePath: string;
+    ext: string;
+}
+/** 详情页要展示的资产引用；`url` 直接指向 `/knowledge/assets/<kbId>/<rel>`。 */
+export interface KnowledgeAssetRef {
+    rel: string;
+    bytes: number;
+    url: string;
+}
+export interface KnowledgeDocumentDetail extends KnowledgeDocument {
+    content: string;
+    frontmatter: Record<string, unknown>;
+    assets: KnowledgeAssetRef[];
+    lineage?: Record<string, string>;
+}
+/** 文档版本：`isCurrent` 的那条是当前 head，其余是历史快照。 */
+export interface DocumentVersion {
+    versionId: string;
+    createdAt: string;
+    contentHash: string;
+    bytes: number;
+    sourceFormat: string;
+    label: string;
+    isCurrent: boolean;
+}
+/** 默认「文件类型 → 解析引擎」规则的内容，不含 `fileCount`。 */
+/**
+ * 从 SourceRaw 的 `metadata` 推导文档扩展名。
+ *
+ * **这个推导是有损的。** SourceRaw 只保存正文与 metadata，并不保存原始文件名；
+ * 因此只有上游（`src/convert/ingest.ts`）显式写了 `metadata.source_path` 时才能拿到
+ * 真实扩展名。回退链是启发式的：
+ *
+ * 1. `metadata.source_path` 的 basename 扩展名（最可信）；
+ * 2. `metadata.source_format === 'markdown'` → `.md`；
+ * 3. `metadata.source_format === 'office'` → `.docx`（office 是容器格式的粗粒度标记，
+ *    真实的 .doc/.xls/.ppt 会被误报为 `.docx`）；
+ * 4. 其余 `source_format` → `.` + source_format（当它本身就是一个扩展名时才对）；
+ * 5. 都没有 → `.md`（知识库里最常见的形态）。
+ *
+ * 因此 `fileCount` 与按扩展名过滤都只是近似值；要精确统计需要在入库时写 `source_path`。
+ */
+export declare function deriveSourceExt(metadata: Record<string, unknown> | undefined): string;
+export interface RebuildReport {
+    runId: string;
+    version: number;
+    only: string;
+    cards: number;
+    units: number;
+    /** Compiled wikiNotes count (stage 2 output). */
+    notes: number;
+    graphNodes: number;
+    graphEdges: number;
+    embedding: 'ready' | 'unavailable' | 'skipped';
+    embeddingItems?: number;
+    embeddingReused?: number;
+    embeddingDimension?: number;
+    vectorQuantization?: 'binary+hamming+int8';
+    embeddingError?: string;
+    /**
+     * 关键词索引（FTS5）的构建结论（0031）。
+     *
+     * 与 `embedding` 并列而不是塞进它：两者可以一个成一个败（编码器坏了但关键词索引照样
+     * 能建），而「哪一路现在是活的」必须一眼看得出。
+     */
+    fts?: 'ready' | 'unavailable';
+    lineage?: LineageContext;
+    compileRunId?: string;
+    startedAt: string;
+    finishedAt: string;
+    /**
+     * Stage-2 incrementality. `compileNotes` is deterministic, so recompiling is
+     * cheap — what is *not* cheap is invalidating a stable corpus: a rebuild that
+     * renumbers notes forces a full re-embedding and breaks existing qrels.
+     * These counters make the reuse visible instead of implicit.
+     */
+    cardsReused?: number;
+    cardsRecompiled?: number;
+    cardsAdded?: number;
+    cardsRemoved?: number;
+    notesReused?: number;
+    notesRecompiled?: number;
+    /** Nothing changed: knowledge artifacts were left byte-identical. */
+    incremental?: boolean;
+    /** The run was a no-op (a `wiki`-only rebuild over an unchanged corpus). */
+    skipped?: boolean;
+    /**
+     * 「SourceRaw → Wiki」第一段的诚实计数。
+     *
+     * 这八个数**每一个都来自真实发生过的事件**，没有一个是估算出来的：抽取了几个
+     * 候选、其中几个被类型闸门拒了、建了几张卡、并进几张卡、几条关系真的连上了、
+     * 几条因为端点不存在被丢掉、几份来源这次被重抽、几份因为指纹没变被跳过。
+     * `extractCandidates` 关掉时它们全部回 0，而不是从响应里消失 —— 「跳过」和
+     * 「没有这个能力」是两件事，用缺字段表达会让人分不清。
+     */
+    candidatesExtracted: number;
+    candidatesRejected: number;
+    cardsCreated: number;
+    cardsMerged: number;
+    relationsExtracted: number;
+    relationsDropped: number;
+    sourcesExtracted: number;
+    sourcesSkipped: number;
+}
+/**
+ * 一条来源业务分类。
+ *
+ * 设计原则：`source_type` 描述**业务场景**，不描述载体格式；载体走
+ * `source_format` / `parser`（见 `deriveSourceExt`）。三个「判定档位」是刻意
+ * 分开的，UI 与 Agent 都按这个契约消费：
+ *
+ * - 必填且不可动（`fallback`）：兜底分类必须存在且始终启用；
+ * - 内置可调（`builtin && !fallback`）：可改文案、可停用，但不可删除、不可改 id；
+ * - 自定义（`!builtin`）：可增可删，但新建时必须提交完整判定文案。
+ */
+export interface SourceTypeDef {
+    /** 稳定 id，`^[a-z][a-z0-9_]{1,40}$`，创建后不可修改。 */
+    id: string;
+    label: string;
+    /** 一句话定义，同时是 Agent 的判定依据。 */
+    description: string;
+    /** 典型信号，至少 2 条；与 `description` 一起拼进判定提示词。 */
+    signals: string[];
+    /** 明确排除项，至少 1 条，每条必须指向一个已存在的分类。 */
+    excludes: string[];
+    /** 停用后不再出现在选择器与判定提示词里，历史引用仍能解析。 */
+    enabled: boolean;
+    /** 内置分类只允许停用，不允许删除。 */
+    builtin: boolean;
+    /** 兜底分类（`document`）：必须存在且不可停用，判定链最后一步落在它上。 */
+    fallback: boolean;
+    /** 计算字段：该库中引用该分类的来源数，由 `refresh` 实时算出，不参与持久化。 */
+    sourceCount: number;
+}
+/** 分类 id 的形状约束；与 0013 规范第 1 节一致。 */
+export declare const SOURCE_TYPE_ID_PATTERN: RegExp;
+/** 兜底分类 id；判定链全不命中时落它，因此它不可停用、不可删除。 */
+export declare const FALLBACK_SOURCE_TYPE = "document";
+/** 单库自定义分类数量上限，防止注册表无界膨胀。 */
+export declare const MAX_SOURCE_TYPES = 50;
+/**
+ * 内置分类的出厂默认值（0013 规范第 7 节的 `source-types.json` 内容）。
+ *
+ * 这些值**可以改**（label / description / signals / excludes / enabled），
+ * 但条目本身不可删除——`normalizeSourceTypes()` 会把缺失的内置条目补回来。
+ */
+export declare const BUILTIN_SOURCE_TYPES: ReadonlyArray<Omit<SourceTypeDef, 'sourceCount'>>;
+export declare function isBuiltinSourceType(id: string): boolean;
+/** 出厂默认注册表（全部启用，`sourceCount` 待算）。 */
+export declare function defaultSourceTypes(): SourceTypeDef[];
+/**
+ * 内置只读判定提示词。
+ *
+ * **它不允许被用户修改**——注册表里没有任何字段能覆盖它；但它必须**被暴露
+ * 出来**：`list_source_types` 工具、`GET /knowledge/source-types` 与设置面板的
+ * 「判定规则（内置，只读）」都原样返回它，让用户看得见 Agent 到底按什么判。
+ * 用户能写的只有每个分类自己的 `description` / `signals` / `excludes`。
+ */
+export interface SourceClassifierStep {
+    /** 该步落到哪个分类；`user` 表示"用户显式指定"这个非分类入口。 */
+    type: string;
+    rule: string;
+}
+export interface SourceClassifierPrompt {
+    readonly: true;
+    version: number;
+    title: string;
+    /** 从最特征化走到最泛化；全不命中落 `fallback.type`。 */
+    priority: SourceClassifierStep[];
+    confidenceRule: string;
+    fallback: {
+        type: string;
+        note: string;
+    };
+    escalation: {
+        code: string;
+        note: string;
+    };
+    /** 自定义分类由用户撰写的判定文案如何参与判定。 */
+    extensionRule: string;
+}
+export declare const SOURCE_CLASSIFIER_PROMPT: SourceClassifierPrompt;
+/** 判定提示词 + 每个分类当前是否启用；停用的分类标注出来而不是从提示词里删掉。 */
+export interface SourceClassifierPromptView extends SourceClassifierPrompt {
+    steps: ReadonlyArray<Readonly<SourceClassifierStep & {
+        label: string;
+        enabled: boolean;
+        exists: boolean;
+    }>>;
+}
+/**
+ * 展开成"每步带 label / enabled / exists"的视图。
+ *
+ * `priority` 直接复用被冻结的原数组（不复制），所以视图也无法被就地改写；
+ * 每次调用只新建 `steps`，并把它一并冻结。注册表怎么改，提示词骨架都不变。
+ */
+export declare function classifierPromptView(defs: SourceTypeDef[]): SourceClassifierPromptView;
+/** 一个知识库的完整分类目录：注册表 + 内置只读提示词。 */
+export interface SourceTypeCatalog {
+    types: SourceTypeDef[];
+    classifierPrompt: SourceClassifierPromptView;
+    fallbackTypeId: string;
+    builtinIds: string[];
+}
+export declare function buildSourceTypeCatalog(defs: SourceTypeDef[]): SourceTypeCatalog;
+/** 新建 / 编辑分类时提交的草稿。 */
+export interface SourceTypeDraft {
+    id?: string;
+    label?: string;
+    description?: string;
+    signals?: unknown;
+    excludes?: unknown;
+    enabled?: boolean;
+}
+export interface SourceTypeDraftProblem {
+    ok: false;
+    code: string;
+    message: string;
+    suggestion?: string;
+    /** 出错的字段，供表单高亮。 */
+    field: 'id' | 'label' | 'description' | 'signals' | 'excludes' | 'enabled';
+}
+/**
+ * 校验一份自定义分类草稿。
+ *
+ * 这是在守「用户追加新类型时，必须用文字标明怎么判断」这条要求：光给个名字
+ * 是不允许入库的——入库的 `description` 会直接变成 Agent 的判定依据。
+ */
+export declare function validateSourceTypeDraft(draft: SourceTypeDraft, knownIds: ReadonlySet<string>): {
+    ok: true;
+} | SourceTypeDraftProblem;
+/**
+ * 只校验判定文案（label / description / signals / excludes），不碰 id。
+ *
+ * 内置分类改文案走这里：id 锁定，但「必须写得能判」的标准一样严。
+ */
+export declare function validateSourceTypeText(draft: SourceTypeDraft, knownIds: ReadonlySet<string>): {
+    ok: true;
+} | SourceTypeDraftProblem;
+/**
+ * Wiki 卡片类型的一条正文小节要求。
+ *
+ * 「正文小节」是给人读的部分：0021 的判断是"序和枚举一旦写进散文，归并算法就再也读不到
+ * 它们了"，所以小节名要固定，模板卡照着它生成。
+ */
+export interface WikiSectionSpec {
+    /** 小节名，同时是模板卡里的 Markdown 标题。 */
+    label: string;
+    required: boolean;
+}
+/**
+ * 一条 front matter / metadata 字段要求（机器读的部分）。
+ *
+ * `name` 对应 `write_knowledge_card` 的顶层字段（`owner` / `summary`）或 `metadata` 里的键。
+ */
+export interface WikiFieldSpec {
+    name: string;
+    required: boolean;
+    note: string;
+}
+/**
+ * 一个 wiki 卡片类型（0024）。
+ *
+ * 它是"SourceRaw → Wiki"这一段的**约束**：哪些类型能生成、每类必须有哪些小节与字段、
+ * 期望来自哪些来源分类、模板长什么样。判定与生成仍交给模型，这里给的是**判据与骨架**。
+ */
+export interface WikiTypeDef {
+    /** 稳定 id，`^[a-z][a-z0-9_/-]{1,60}$`（允许 `diagnosis/symptom` 这类命名空间）。 */
+    id: string;
+    label: string;
+    description: string;
+    /** 借 0021 的分层：类型层可复用上千次（假设/口径），实例层只发生过一次（案例）。 */
+    layer: 'type' | 'instance';
+    sections: WikiSectionSpec[];
+    fields: WikiFieldSpec[];
+    /** 期望的来源业务分类 id（0013 的 `source_type`）；空数组表示不限制。 */
+    sourceTypes: string[];
+    /** few-shot：用户会怎么提到这种卡片。随工具描述下发。 */
+    examples: string[];
+    /** 模板卡（Markdown 骨架），新建卡片时照抄。 */
+    template: string;
+    enabled: boolean;
+    /** 内置类型只允许停用，不允许删除。 */
+    builtin: boolean;
+    /** 计算字段：该库中该类型的卡片数，由 refresh 实时算出。 */
+    cardCount: number;
+}
+/** 卡片 schema 的生效方式。 */
+export type WikiSchemaMode = 'strict' | 'report';
+/** 卡片校验问题的一层。混成同一个「校验失败」，人就学不会怎么写卡片（0021 §1）。 */
+export type CardIssueLevel = 'format' | 'reference' | 'semantic';
+export interface CardSchemaIssue {
+    level: CardIssueLevel;
+    /** 出问题的小节名或字段名。 */
+    field?: string;
+    message: string;
+}
+/** 卡片类型目录：注册表 + 生效方式 + 内置只读判定规则 + 当前卡片的问题清单。 */
+export interface WikiTypeCatalog {
+    types: WikiTypeDef[];
+    mode: WikiSchemaMode;
+    /** 内置只读的判定规则：模型该按什么顺序挑类型。 */
+    rules: string;
+    /** 已落库卡片的三层校验结果（前 N 条）。 */
+    issues: Array<CardSchemaIssue & {
+        entityId: string;
+        entityType: string;
+    }>;
+    issueCount: number;
+}
+/** 卡片类型 id 的形状；允许 `diagnosis/symptom` 这类带命名空间的 id。 */
+export declare const WIKI_TYPE_ID_PATTERN: RegExp;
+//# sourceMappingURL=types.d.ts.map