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

package/lib/types/directory-picker.d.ts

@@ -0,0 +1,94 @@
+/**
+ * 目录选择：把 DSH 宿主的 `ctx.directoryPicker` 接到 TitaAgent 控制台上（0029）。
+ *
+ * ## 为什么不让用户手输路径
+ *
+ * 路径是**磁盘事实**，不是用户脑子里的字符串。让人手打 `/Users/xxx/Desktop/…`
+ * 的结果是：拼错一个字符、`~` 没展开、复制粘贴带上了尾随空格 —— 而这一处的错误
+ * 代价特别大，它决定了整个 Agent 的东西存在哪。所以设置里那个「根路径」是一个
+ * **选择**动作，不是一个输入框。
+ *
+ * ## 为什么要适配两种交互
+ *
+ * 宿主把「怎么选目录」抽象成一个 capability，形状有两种：
+ *
+ * - `native`：在**宿主那台机器**上弹系统文件夹对话框，返回一个绝对路径。
+ *   浏览器和宿主在同一台机器上时这是最好的形态 —— 用户看到的是他熟悉的访达。
+ * - `browse`：宿主只提供「列一层 / 建子目录」两个原语，由调用方自己在页面里画
+ *   浏览界面。浏览器在远端（或宿主没有显示器）时这是唯一能用的形态。
+ *
+ * 两者**不能只挑一个**：本机部署走 native，远程访问走 browse，而这是启动时根据
+ * 绑定地址 / SSH / 显示器判定的（`dsh-host-directory-picker-auto`）。所以这里
+ * 如实把 kind 转给前端，由前端决定弹系统框还是画浏览框 —— 前端的默认写法是
+ * 「拿到 kind 再分叉」，而不是假设自己是哪一种。
+ *
+ * ## 为什么类型是结构化的
+ *
+ * `@deepseek-ai/dsh-host-directory-picker` 是 DSH 安装里的包，不是 npm 上可依赖的
+ * 版本，插件不能 import 它（会把 DSH 的内部路径焊进依赖图）。所以这里只声明我们
+ * 真正用到的那几个成员 —— 服务是按名字从 ctx 里取的，取不到就是没有，退化成
+ * 「宿主没提供目录选择器」这一条如实回答，而不是崩掉。
+ *
+ * @module
+ */
+/** 一层目录里的一行：一个子目录，或一个面包屑祖先。 */
+export interface DirectoryEntry {
+    /** 显示用的名字（根面包屑带的是完整路径）。 */
+    name: string;
+    /** 宿主机上的绝对路径 —— 调用方永远不自己拼路径段。 */
+    path: string;
+    /** 宿主平台约定的隐藏项（POSIX 上是点开头）。 */
+    hidden: boolean;
+}
+/** 一层目录 + 它的祖先链。 */
+export interface DirectoryListing {
+    path: string;
+    /** 宿主账号的 home，面包屑的「Home」锚点。 */
+    home: string;
+    crumbs: DirectoryEntry[];
+    entries: DirectoryEntry[];
+    /** 后端把 entries 截断在它的完整结果上限上了。 */
+    truncated: boolean;
+}
+/** 宿主的目录选择能力。两个原语都可能是 `undefined` —— 取决于 kind。 */
+export interface DirectoryPickerCapability {
+    kind: string;
+    pick?(signal: AbortSignal): Promise<string | null>;
+    list?(path?: string, signal?: AbortSignal): Promise<DirectoryListing>;
+    createDirectory?(path: string, name: string): Promise<string>;
+}
+/** `ctx.directoryPicker` 的结构化视图。 */
+export interface DirectoryPickerLike {
+    capability(): DirectoryPickerCapability;
+}
+/** 目录选择失败的业务码。前端据此给出「怎么办」而不是一句「失败了」。 */
+export type PickerErrorCode = 'PICKER_UNAVAILABLE' | 'PICK_CANCELLED' | 'DIRECTORY_UNREADABLE' | 'DIRECTORY_EXISTS' | 'DIRECTORY_CREATE_FAILED';
+/** 带业务码的目录选择失败。 */
+export declare class PickerError extends Error {
+    readonly code: PickerErrorCode;
+    constructor(code: PickerErrorCode, message: string);
+}
+/** 从 ctx 里按名字取目录选择服务。取不到返回 `undefined`（宿主没挂这个能力）。 */
+export declare function pickerOf(ctx: {
+    get(name: string): unknown;
+}): DirectoryPickerLike | undefined;
+/** 宿主当前提供的是哪种交互。取不到服务时返回 `null`。 */
+export declare function pickerKind(picker: DirectoryPickerLike | undefined): string | null;
+/**
+ * 开一次选择。
+ *
+ * native 会**阻塞到用户给出答案**（关掉对话框也算答案：`path` 为 `null`），所以
+ * 调用方的 HTTP 请求会一直挂着 —— 这正是系统对话框的语义，不该用超时把它打断。
+ * browse 立刻返回，让前端去画浏览界面。
+ */
+export declare function pickDirectory(picker: DirectoryPickerLike | undefined, signal: AbortSignal): Promise<{
+    kind: 'native';
+    path: string | null;
+} | {
+    kind: 'browse';
+}>;
+/** 列一层目录（browse 形态）。 */
+export declare function listDirectory(picker: DirectoryPickerLike | undefined, path: string | undefined, signal: AbortSignal): Promise<DirectoryListing>;
+/** 在某个目录下建一个子目录（browse 形态）。 */
+export declare function createDirectory(picker: DirectoryPickerLike | undefined, path: string, name: string): Promise<string>;
+//# sourceMappingURL=directory-picker.d.ts.map

package/lib/types/directory-picker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-picker.d.ts","sourceRoot":"","sources":["../../src/directory-picker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,2BAA2B;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,+BAA+B;IAC/B,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,oBAAoB;AACpB,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,cAAc,EAAE,CAAA;IACxB,OAAO,EAAE,cAAc,EAAE,CAAA;IACzB,iCAAiC;IACjC,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,kDAAkD;AAClD,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAClD,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IACrE,eAAe,CAAC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAC9D;AAED,oCAAoC;AACpC,MAAM,WAAW,mBAAmB;IAClC,UAAU,IAAI,yBAAyB,CAAA;CACxC;AAED,wCAAwC;AACxC,MAAM,MAAM,eAAe,GACvB,oBAAoB,GACpB,gBAAgB,GAChB,sBAAsB,GACtB,kBAAkB,GAClB,yBAAyB,CAAA;AAE7B,mBAAmB;AACnB,qBAAa,WAAY,SAAQ,KAAK;IACpC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;gBAClB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAKnD;AAED,qDAAqD;AACrD,wBAAgB,QAAQ,CAAC,GAAG,EAAE;IAAE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE,GAAG,mBAAmB,GAAG,SAAS,CAG7F;AAED,oCAAoC;AACpC,wBAAgB,UAAU,CAAC,MAAM,EAAE,mBAAmB,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAOjF;AAED;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,GAAG,SAAS,EACvC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAYvE;AAED,wBAAwB;AACxB,wBAAsB,aAAa,CACjC,MAAM,EAAE,mBAAmB,GAAG,SAAS,EACvC,IAAI,EAAE,MAAM,GAAG,SAAS,EACxB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAU3B;AAED,+BAA+B;AAC/B,wBAAsB,eAAe,CACnC,MAAM,EAAE,mBAAmB,GAAG,SAAS,EACvC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,CAAC,CAejB"}

package/lib/types/directory-picker.js

@@ -0,0 +1,110 @@
+/**
+ * 目录选择：把 DSH 宿主的 `ctx.directoryPicker` 接到 TitaAgent 控制台上（0029）。
+ *
+ * ## 为什么不让用户手输路径
+ *
+ * 路径是**磁盘事实**，不是用户脑子里的字符串。让人手打 `/Users/xxx/Desktop/…`
+ * 的结果是：拼错一个字符、`~` 没展开、复制粘贴带上了尾随空格 —— 而这一处的错误
+ * 代价特别大，它决定了整个 Agent 的东西存在哪。所以设置里那个「根路径」是一个
+ * **选择**动作，不是一个输入框。
+ *
+ * ## 为什么要适配两种交互
+ *
+ * 宿主把「怎么选目录」抽象成一个 capability，形状有两种：
+ *
+ * - `native`：在**宿主那台机器**上弹系统文件夹对话框，返回一个绝对路径。
+ *   浏览器和宿主在同一台机器上时这是最好的形态 —— 用户看到的是他熟悉的访达。
+ * - `browse`：宿主只提供「列一层 / 建子目录」两个原语，由调用方自己在页面里画
+ *   浏览界面。浏览器在远端（或宿主没有显示器）时这是唯一能用的形态。
+ *
+ * 两者**不能只挑一个**：本机部署走 native，远程访问走 browse，而这是启动时根据
+ * 绑定地址 / SSH / 显示器判定的（`dsh-host-directory-picker-auto`）。所以这里
+ * 如实把 kind 转给前端，由前端决定弹系统框还是画浏览框 —— 前端的默认写法是
+ * 「拿到 kind 再分叉」，而不是假设自己是哪一种。
+ *
+ * ## 为什么类型是结构化的
+ *
+ * `@deepseek-ai/dsh-host-directory-picker` 是 DSH 安装里的包，不是 npm 上可依赖的
+ * 版本，插件不能 import 它（会把 DSH 的内部路径焊进依赖图）。所以这里只声明我们
+ * 真正用到的那几个成员 —— 服务是按名字从 ctx 里取的，取不到就是没有，退化成
+ * 「宿主没提供目录选择器」这一条如实回答，而不是崩掉。
+ *
+ * @module
+ */
+/** 带业务码的目录选择失败。 */
+export class PickerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PickerError';
+    }
+}
+/** 从 ctx 里按名字取目录选择服务。取不到返回 `undefined`（宿主没挂这个能力）。 */
+export function pickerOf(ctx) {
+    const service = ctx.get('directoryPicker');
+    return service && typeof service.capability === 'function' ? service : undefined;
+}
+/** 宿主当前提供的是哪种交互。取不到服务时返回 `null`。 */
+export function pickerKind(picker) {
+    if (!picker)
+        return null;
+    try {
+        return picker.capability()?.kind ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 开一次选择。
+ *
+ * native 会**阻塞到用户给出答案**（关掉对话框也算答案：`path` 为 `null`），所以
+ * 调用方的 HTTP 请求会一直挂着 —— 这正是系统对话框的语义，不该用超时把它打断。
+ * browse 立刻返回，让前端去画浏览界面。
+ */
+export async function pickDirectory(picker, signal) {
+    const capability = picker?.capability();
+    if (!capability) {
+        throw new PickerError('PICKER_UNAVAILABLE', '宿主没有提供目录选择器，无法打开文件夹对话框。');
+    }
+    if (capability.kind === 'native') {
+        if (typeof capability.pick !== 'function') {
+            throw new PickerError('PICKER_UNAVAILABLE', '宿主的目录选择器声明为 native，但没有提供 pick。');
+        }
+        return { kind: 'native', path: await capability.pick(signal) };
+    }
+    return { kind: 'browse' };
+}
+/** 列一层目录（browse 形态）。 */
+export async function listDirectory(picker, path, signal) {
+    const capability = picker?.capability();
+    if (!capability || capability.kind !== 'browse' || typeof capability.list !== 'function') {
+        throw new PickerError('PICKER_UNAVAILABLE', '宿主没有提供可浏览的目录列表。');
+    }
+    try {
+        return await capability.list(path, signal);
+    }
+    catch (cause) {
+        throw new PickerError('DIRECTORY_UNREADABLE', cause instanceof Error ? cause.message : String(cause));
+    }
+}
+/** 在某个目录下建一个子目录（browse 形态）。 */
+export async function createDirectory(picker, path, name) {
+    const capability = picker?.capability();
+    if (!capability || capability.kind !== 'browse' || typeof capability.createDirectory !== 'function') {
+        throw new PickerError('PICKER_UNAVAILABLE', '宿主没有提供新建目录的能力。');
+    }
+    const trimmed = name.trim();
+    if (!trimmed || trimmed.includes('/') || trimmed.includes('\\') || trimmed === '.' || trimmed === '..') {
+        throw new PickerError('DIRECTORY_CREATE_FAILED', '目录名不能为空、不能包含路径分隔符，也不能是 . 或 ..');
+    }
+    try {
+        return await capability.createDirectory(path, trimmed);
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        throw new PickerError(/exist/i.test(message) ? 'DIRECTORY_EXISTS' : 'DIRECTORY_CREATE_FAILED', message);
+    }
+}
+//# sourceMappingURL=directory-picker.js.map

package/lib/types/directory-picker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-picker.js","sourceRoot":"","sources":["../../src/directory-picker.ts"],"names":[],"mappings":"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"}

package/lib/types/extract-model.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 模型驱动的候选抽取与**实体归并**（#3b）。
+ *
+ * ## 为什么需要这一步，而不是继续改规则
+ *
+ * Pass 0 的规则抽取用**小节标题**当实体身份（`candidateEntityId(candidate.name)`）。
+ * 于是同一件东西只要换个标题写法，就是两个实体。这不是理论问题，是实测出来的：
+ *
+ * - 年报里的小节叫「毛利率变动及其驱动因素」；
+ * - 口径手册里的小节叫「毛利率（口径补充）」；
+ * - 结果：`新建 2 / 并入 0`，两张互不相干的卡片，
+ *   而「实体已存在就追加正文」那条分支**永远不会触发**。
+ *
+ * 想去掉括号后缀、去掉「及其驱动因素」这类尾巴，是**语义判断**：`毛利率` 与
+ * `毛利率变动及其驱动因素` 是同一个东西，而 `应收账款周转天数` 与 `库存周转天数`
+ * 不是 —— 两者字面都带「周转天数」。阈值化的字符串规则在第二步上必然出错，
+ * 所以这件事必须交给模型。
+ *
+ * ## 这一层只问一个问题
+ *
+ * 它**不**让模型自由编造卡片，也不让它决定正文：正文永远是来源里的原文片段，
+ * 模型只回答两件它擅长、而规则做不好的事 ——
+ *
+ * 1. 「这份来源里有哪些**实体**」（规则只会按小节切，切出来的是标题不是实体）；
+ * 2. 「这个实体是不是已经在下表里了」（给出已有卡片的 `existing_id`）。
+ *
+ * 第 2 问是归并的关键：**判断权在模型，决定权在这里**。模型说「是同一个」，
+ * 我们就走追加；说「不是」，就新建。模型给出的 `existing_id` 必须能在已有卡片里
+ * 找到，找不到就退回新建 —— 不能让模型凭一个不存在的 id 把内容写丢。
+ *
+ * ## 为什么要注入 `call`
+ *
+ * 模型调用是这一层唯一的非纯部分。把它作为参数注入，这个模块就能在没有模型的环境里
+ * 被完整测试（见 `tests/extract-model.test.mjs`）——否则「归并对不对」这件事只能靠
+ * 真跑一次模型来验，而那是不可重复的。
+ *
+ * @module
+ */
+import { type ExtractionCandidate } from './extract.js';
+import type { KnowledgeCard, SchemaType, SourceRaw, WikiTypeDef } from './types.js';
+/** 一次纯文本模型调用：给出 system 与 prompt，拿回模型的原始文本。 */
+export type ModelCall = (request: {
+    system: string;
+    prompt: string;
+}) => Promise<string>;
+/** 归并条目：与规则抽取的 `NormalizedCandidates['merges']` 保持同一形状。 */
+export interface ModelMerge {
+    key: string;
+    entityId: string;
+    entityType: SchemaType;
+    sourceId: string;
+    body: string;
+}
+export interface ModelExtractionResult {
+    /** 判定为「wiki 里还没有」的实体 → 新建卡片。 */
+    fresh: ExtractionCandidate[];
+    /** 判定为「wiki 里已经有了」的实体 → 正文追加进那张卡。 */
+    merges: ModelMerge[];
+    warnings: string[];
+}
+export interface ModelExtractionInput {
+    source: SourceRaw;
+    /** 已启用的 wiki 类型：模型只能从这些 id 里选。 */
+    wikiTypes: WikiTypeDef[];
+    /** 当前库里的卡片：既是「已存在」的候选集，也是给模型的上下文。 */
+    existing: KnowledgeCard[];
+    call: ModelCall;
+}
+/**
+ * 用模型抽取实体，并把它们判归到「新建」或「追加到已有卡片」两条路上。
+ *
+ * 失败一律降级而不抛出：模型不可用时返回空结果 + 一条 warning，让上层继续跑规则抽取。
+ * 「因为模型挂了所以整次编译失败」是不能接受的 —— 那条链路本来就不依赖模型。
+ */
+export declare function extractWithModel(input: ModelExtractionInput): Promise<ModelExtractionResult>;
+//# sourceMappingURL=extract-model.d.ts.map

package/lib/types/extract-model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-model.d.ts","sourceRoot":"","sources":["../../src/extract-model.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAqB,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAC1E,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEnF,8CAA8C;AAC9C,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;AAExF,2DAA2D;AAC3D,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,UAAU,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,qBAAqB;IACpC,gCAAgC;IAChC,KAAK,EAAE,mBAAmB,EAAE,CAAA;IAC5B,qCAAqC;IACrC,MAAM,EAAE,UAAU,EAAE,CAAA;IACpB,QAAQ,EAAE,MAAM,EAAE,CAAA;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,SAAS,CAAA;IACjB,kCAAkC;IAClC,SAAS,EAAE,WAAW,EAAE,CAAA;IACxB,qCAAqC;IACrC,QAAQ,EAAE,aAAa,EAAE,CAAA;IACzB,IAAI,EAAE,SAAS,CAAA;CAChB;AA2ED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA4ElG"}

package/lib/types/extract-model.js

@@ -0,0 +1,193 @@
+/**
+ * 模型驱动的候选抽取与**实体归并**（#3b）。
+ *
+ * ## 为什么需要这一步，而不是继续改规则
+ *
+ * Pass 0 的规则抽取用**小节标题**当实体身份（`candidateEntityId(candidate.name)`）。
+ * 于是同一件东西只要换个标题写法，就是两个实体。这不是理论问题，是实测出来的：
+ *
+ * - 年报里的小节叫「毛利率变动及其驱动因素」；
+ * - 口径手册里的小节叫「毛利率（口径补充）」；
+ * - 结果：`新建 2 / 并入 0`，两张互不相干的卡片，
+ *   而「实体已存在就追加正文」那条分支**永远不会触发**。
+ *
+ * 想去掉括号后缀、去掉「及其驱动因素」这类尾巴，是**语义判断**：`毛利率` 与
+ * `毛利率变动及其驱动因素` 是同一个东西，而 `应收账款周转天数` 与 `库存周转天数`
+ * 不是 —— 两者字面都带「周转天数」。阈值化的字符串规则在第二步上必然出错，
+ * 所以这件事必须交给模型。
+ *
+ * ## 这一层只问一个问题
+ *
+ * 它**不**让模型自由编造卡片，也不让它决定正文：正文永远是来源里的原文片段，
+ * 模型只回答两件它擅长、而规则做不好的事 ——
+ *
+ * 1. 「这份来源里有哪些**实体**」（规则只会按小节切，切出来的是标题不是实体）；
+ * 2. 「这个实体是不是已经在下表里了」（给出已有卡片的 `existing_id`）。
+ *
+ * 第 2 问是归并的关键：**判断权在模型，决定权在这里**。模型说「是同一个」，
+ * 我们就走追加；说「不是」，就新建。模型给出的 `existing_id` 必须能在已有卡片里
+ * 找到，找不到就退回新建 —— 不能让模型凭一个不存在的 id 把内容写丢。
+ *
+ * ## 为什么要注入 `call`
+ *
+ * 模型调用是这一层唯一的非纯部分。把它作为参数注入，这个模块就能在没有模型的环境里
+ * 被完整测试（见 `tests/extract-model.test.mjs`）——否则「归并对不对」这件事只能靠
+ * 真跑一次模型来验，而那是不可重复的。
+ *
+ * @module
+ */
+import { candidateEntityId } from './extract.js';
+/** 单个实体最多给模型的正文长度：够判断语义，又不至于把上下文撑爆。 */
+const BODY_LIMIT = 1200;
+/**
+ * 系统提示。**刻意写死在这里**而不是做成设置项：它不是用户的偏好，是这个模块与模型
+ * 之间的接口契约（输出必须是一段可解析的 JSON）。允许用户改它，等于允许用户把这个
+ * 解析器改坏。
+ */
+const SYSTEM = [
+    'You extract wiki entities from a business document and decide which of them already exist.',
+    'Answer with a single JSON object and nothing else. No prose, no code fence.',
+    'Shape: {"entities":[{"name":string,"type":string,"summary":string,"body":string,"existing_id":string|null}]}',
+    'Rules:',
+    '- "name" is the entity name as a business person would say it (e.g. 毛利率). Not a section heading.',
+    '- "type" MUST be one of the allowed type ids given in the prompt.',
+    '- "body" must be verbatim text from the document that backs this entity. Never invent facts.',
+    '- "existing_id" is the entityId of the existing card this entity is the SAME thing as, or null.',
+    '  Same thing means the same business concept; a narrower or different concept is NOT the same.',
+    '- Prefer few, real entities over many headings.',
+].join('\n');
+/** 从一串可能带 ``` 围栏的文本里取出 JSON 对象并解析。 */
+function parseJsonObject(raw) {
+    const trimmed = raw.trim();
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/);
+    const body = (fenced ? fenced[1] : trimmed).trim();
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        // 模型有时会在 JSON 前后带一句解释：退一步，取第一个 `{` 到最后一个 `}`。
+        const start = body.indexOf('{');
+        const end = body.lastIndexOf('}');
+        if (start < 0 || end <= start)
+            return undefined;
+        try {
+            return JSON.parse(body.slice(start, end + 1));
+        }
+        catch {
+            return undefined;
+        }
+    }
+}
+/** 把模型的回答收敛成「合法实体数组」；任何不合法的一条都丢掉并记一条 warning。 */
+function readEntities(raw, allowedTypes, warnings) {
+    if (raw === null || typeof raw !== 'object') {
+        warnings.push('模型输出不是 JSON 对象，本次抽取按空处理');
+        return [];
+    }
+    const list = raw.entities;
+    if (!Array.isArray(list)) {
+        warnings.push('模型输出里没有 entities 数组，本次抽取按空处理');
+        return [];
+    }
+    const kept = [];
+    for (const item of list) {
+        if (item === null || typeof item !== 'object')
+            continue;
+        const record = item;
+        const name = typeof record.name === 'string' ? record.name.trim() : '';
+        const type = typeof record.type === 'string' ? record.type.trim() : '';
+        const body = typeof record.body === 'string' ? record.body.trim() : '';
+        if (!name)
+            continue;
+        if (!allowedTypes.has(type)) {
+            warnings.push(`模型给出的类型「${type}」不在已启用类型里，候选「${name}」被丢掉`);
+            continue;
+        }
+        if (!body) {
+            warnings.push(`候选「${name}」没有正文，被丢掉（卡片不能没有正文）`);
+            continue;
+        }
+        kept.push({ ...record, name, type, body });
+    }
+    return kept;
+}
+/**
+ * 用模型抽取实体，并把它们判归到「新建」或「追加到已有卡片」两条路上。
+ *
+ * 失败一律降级而不抛出：模型不可用时返回空结果 + 一条 warning，让上层继续跑规则抽取。
+ * 「因为模型挂了所以整次编译失败」是不能接受的 —— 那条链路本来就不依赖模型。
+ */
+export async function extractWithModel(input) {
+    const { source, wikiTypes, existing, call } = input;
+    const warnings = [];
+    const enabled = wikiTypes.filter(def => def.enabled);
+    const allowedTypes = new Set(enabled.map(def => String(def.id)));
+    const catalog = existing
+        .slice(0, 200)
+        .map(card => `- ${card.entityId} :: ${card.title}（${card.entityType}）`)
+        .join('\n');
+    const types = enabled
+        .map(def => `- ${def.id} :: ${def.label}${def.description ? ` — ${def.description}` : ''}`)
+        .join('\n');
+    const prompt = [
+        '# Allowed wiki type ids',
+        types || '（没有任何已启用类型）',
+        '',
+        '# Existing wiki cards (entityId :: title)',
+        catalog || '（这个库还是空的）',
+        '',
+        '# Document',
+        `title: ${source.title}`,
+        `source_id: ${source.sourceId}`,
+        '',
+        source.content.slice(0, BODY_LIMIT * 8),
+    ].join('\n');
+    let raw;
+    try {
+        raw = await call({ system: SYSTEM, prompt });
+    }
+    catch (cause) {
+        warnings.push(`模型抽取不可用：${cause instanceof Error ? cause.message : String(cause)}`);
+        return { fresh: [], merges: [], warnings };
+    }
+    const byId = new Map(existing.map(card => [`${card.entityType}:${card.entityId}`, card]));
+    const byEntityId = new Map(existing.map(card => [card.entityId, card]));
+    const fresh = [];
+    const merges = [];
+    const claimed = new Set();
+    for (const entity of readEntities(parseJsonObject(raw), allowedTypes, warnings)) {
+        const name = String(entity.name);
+        const type = String(entity.type);
+        const body = String(entity.body).slice(0, BODY_LIMIT);
+        const wantedId = typeof entity.existing_id === 'string' ? entity.existing_id.trim() : '';
+        // 模型给的 id 必须真的存在：它指着不存在的卡片时退回新建，绝不能让正文丢在空中。
+        const target = (wantedId ? byEntityId.get(wantedId) : undefined) ?? byId.get(`${type}:${name}`);
+        if (target) {
+            const key = `${target.entityType}:${target.entityId}`;
+            // 同一张卡在一次抽取里被多个候选指向时只并一次，正文在这里先合起来。
+            const already = merges.find(entry => entry.key === key);
+            if (already)
+                already.body = `${already.body}\n\n${body}`;
+            else
+                merges.push({ key, entityId: target.entityId, entityType: target.entityType, sourceId: source.sourceId, body });
+            claimed.add(key);
+            continue;
+        }
+        const entityId = candidateEntityId(name);
+        const key = `${type}:${entityId}`;
+        if (claimed.has(key))
+            continue;
+        claimed.add(key);
+        fresh.push({
+            kind: 'entity',
+            name,
+            type,
+            body,
+            aliases: [],
+            evidence: { sourceId: source.sourceId },
+            confidence: 0.7,
+        });
+    }
+    return { fresh, merges, warnings };
+}
+//# sourceMappingURL=extract-model.js.map

package/lib/types/extract-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-model.js","sourceRoot":"","sources":["../../src/extract-model.ts"],"names":[],"mappings":"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"}

package/lib/types/extract.d.ts

@@ -0,0 +1,121 @@
+import type { KnowledgeCard, SchemaType, SourceRaw, WikiTypeDef } from './types.js';
+/**
+ * Pass 0 · 候选抽取 + 归一（与库内判重）。
+ *
+ * 这一层是「SourceRaw → Wiki」的第一个编译阶段，也是唯一一个**不调用模型**的阶段：
+ * 它只做「文档里明明白白写着什么」这件事。三个设计判断：
+ *
+ * 1. **纯函数。** 不碰磁盘、不碰模型、不碰网络，所以它可以被直接单测，
+ *    也可以在重建之外被复用（Agent 想先看看会抽出什么）。真正落盘的是 `rebuild()`。
+ * 2. **只认有据可查的候选。** 每个候选都必须带着 `evidence`（来源 id + 小节 / 原文片段）；
+ *    抽不出证据的位置宁可不出候选，也不编一个名字出来。
+ * 3. **related ≠ same。** `relation` 候选永远只变成图的边，绝不参与卡片合并 ——
+ *    「A 和 B 有关系」和「A 就是 B」是两件事，混起来会把两张卡片糊成一张，
+ *    而且糊掉之后没有任何痕迹能还原。
+ */
+export interface CandidateEvidence {
+    sourceId: string;
+    /** 候选来自哪个 `##`/`###` 小节（声明式候选可自带）。 */
+    heading?: string;
+    /** 支撑这个候选的原文片段；只作证据展示，不参与判重。 */
+    quote?: string;
+}
+export interface ExtractionCandidate {
+    kind: 'entity' | 'concept' | 'relation';
+    /** Display name, e.g. 「销售口径」. */
+    name: string;
+    /** The wiki card type this candidate should become. Must be an enabled WikiTypeDef id. */
+    type: SchemaType;
+    evidence: CandidateEvidence;
+    /** Other spellings that mean the same thing (from `[[Name|alias]]` and frontmatter). */
+    aliases?: string[];
+    /** Markdown body that backs this candidate (used as the card body). */
+    body?: string;
+    /** For kind === 'relation': the other end. */
+    target?: {
+        name: string;
+        type?: SchemaType;
+    };
+    /** For kind === 'relation': the relation id, e.g. 'relates_to'. */
+    relation?: string;
+    confidence: number;
+}
+/** 抽取关系候选时使用的默认关系 id；图里也只认这个 id（见 `rebuild()` 的边装配）。 */
+export declare const RELATES_TO = "relates_to";
+/**
+ * 每份来源最多抽多少张卡片候选。
+ *
+ * 这是**有意为之的上限**，不是省略号：一份长文档的小节可以有几十个，放开就会把
+ * 一个知识库灌成「一篇文档 = 几十张未审核卡片」，人再也不会去看它们。宁可少抽，
+ * 剩下的由 Agent 用声明式候选主动补。
+ */
+export declare const MAX_CANDIDATES_PER_SOURCE = 12;
+/**
+ * 名字归一：小写 + 把非字母数字的连续段折成 `-`。
+ *
+ * **必须与 `candidateKey` / `buildAliasIndex` 用同一套归一**，否则「GMV 口径」和
+ * 「gmv-口径」在索引里是两个键，判重就会漏。这里刻意用小写化而不是运行时 slug 的
+ * 原样保留，因为判重是「同一个指称」的问题，大小写不构成区别。
+ */
+export declare function normalizeCandidateName(value: string): string;
+export declare function candidateKey(candidate: {
+    type: string;
+    name: string;
+}): string;
+/**
+ * 候选落到磁盘时用的 `entity_id`。
+ *
+ * 卡片 id 必须过 `SAFE_ID`（ASCII），而候选名常常是中文，所以中文名不能直接当 id：
+ * 这里退化成 `candidate-<fnv1a>` 的稳定哈希。名字本身仍然完整地写进卡片 title，
+ * 并作为 alias 进索引，所以下一次判重照样能按名字找到它 —— 判重认的是名字，不是 id。
+ */
+export declare function candidateEntityId(name: string): string;
+export declare function extractCandidates(source: SourceRaw, wikiTypes: WikiTypeDef[]): ExtractionCandidate[];
+/**
+ * 现有卡片的判重索引。
+ *
+ * 三处都登记：`entityType + entityId`（技术 id）、`entityType + title`（人写的中文名）、
+ * `metadata.aliases` 里的每个写法。**别名是关键字**：Agent 写卡片时把「GMV 口径」登记
+ * 成 `gmv-kpi` 的别名，抽取器下一次就认得这两者是同一个指称，不会再造第二张卡。
+ */
+export declare function buildAliasIndex(cards: KnowledgeCard[]): Map<string, KnowledgeCard>;
+export interface NormalizedCandidates {
+    fresh: ExtractionCandidate[];
+    /**
+     * Candidates whose referent already exists: merge into that card.
+     *
+     * `body` 是**这次新抽到的正文**，必须一起带出去。只带 `sourceId` 的话，调用方
+     * 除了「记一笔来源」什么也做不了 —— 新写进来源里的内容会**静默消失**，卡片永远
+     * 停在第一次抽取时的样子（落点是 `runtime.ts` 的 `appendExtracted`）。
+     */
+    merges: Array<{
+        key: string;
+        entityId: string;
+        entityType: SchemaType;
+        sourceId: string;
+        body: string;
+    }>;
+    /**
+     * Relation candidates are never merged — they become graph edges.
+     *
+     * `fromKey` / `toKey` 是**图上的节点键**（`<entityType>:<entityId>`），不是候选键
+     * （`<type>:<归一化名字>`）。两者在名字是 ASCII 时长得一样，在中文名上完全不同 ——
+     * 中文名的卡片 id 会退化成 `candidate-<hash>`。这里必须先解析成真正的节点键，
+     * 否则装配图时按候选键去找节点，**所有中文名之间的关系都会被当成「端点不存在」丢掉**。
+     */
+    relations: Array<{
+        fromKey: string;
+        toKey: string;
+        relation: string;
+        sourceId: string;
+    }>;
+}
+/**
+ * 归一：把候选分成「新建」「并入已有卡片」「关系」三类。
+ *
+ * 关系两端也走同一套判重，所以边只可能连到**真实存在的 wiki 节点**上；解析不出来的
+ * 端点会带着一个稳定 key 出去，由 `rebuild()` 在装配图时丢弃并计数，而不是在这里
+ * 凭空造一个节点。
+ */
+export declare function normalizeCandidates(candidates: ExtractionCandidate[], index: Map<string, KnowledgeCard>): NormalizedCandidates;
+//# sourceMappingURL=extract.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extract.d.ts","sourceRoot":"","sources":["../../src/extract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEnF;;;;;;;;;;;;;GAaG;AAEH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAA;IACvC,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,0FAA0F;IAC1F,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,iBAAiB,CAAA;IAC3B,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8CAA8C;IAC9C,MAAM,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,UAAU,CAAA;KAAE,CAAA;IAC5C,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,wDAAwD;AACxD,eAAO,MAAM,UAAU,eAAe,CAAA;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,KAAK,CAAA;AAiB3C;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,YAAY,CAAC,SAAS,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAE9E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAItD;AAmPD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,GAAG,mBAAmB,EAAE,CAyJpG;AAID;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,CAclF;AAED,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,mBAAmB,EAAE,CAAA;IAC5B;;;;;;OAMG;IACH,MAAM,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACxG;;;;;;;OAOG;IACH,SAAS,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACzF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,oBAAoB,CAoF9H"}