@dshtrading/knowledge 0.6.3 → 0.7.1

package/lib/bundle.d.ts

@@ -0,0 +1,82 @@
+import { KnowledgeCard } from "./types.js";
+//#region src/bundle.d.ts
+/** bundle 格式版本：本机只认这一版，改动卡片契约时递增。 */
+declare const KNOWLEDGE_BUNDLE_SCHEMA_VERSION = 1;
+/** 单次导入卡片数上限：防止一次导入把库撑到图形/检索不可用的量级。 */
+declare const KNOWLEDGE_BUNDLE_MAX_CARDS = 2000;
+/** 单文件字节上限（8 MiB）：整个文件要先读进内存再解析，读之前就要有界。 */
+declare const KNOWLEDGE_BUNDLE_MAX_BYTES = 8388608;
+interface KnowledgeBundleMeta {
+  readonly schemaVersion: number;
+  readonly exportedAt: string;
+  readonly cardCount: number;
+  readonly generator: string;
+  readonly notice: string;
+}
+interface KnowledgeBundle {
+  readonly meta: KnowledgeBundleMeta;
+  readonly cards: readonly KnowledgeCard[];
+}
+/**
+ * 由卡片列表构造 bundle。
+ *
+ * 不做深拷贝也不做字段裁剪：导出的是库里已有的卡片（store 写入面已归一作者），
+ * 这里改字段只会让「导出—导入—再导出」三份内容对不上。
+ */
+declare function createKnowledgeBundle(cards: readonly KnowledgeCard[], options?: {
+  readonly now?: Date;
+}): KnowledgeBundle;
+/** 落盘文本：2 空格缩进（人可读、可 diff）+ 收尾换行（符合 POSIX 文本约定）。 */
+declare function serializeKnowledgeBundle(bundle: KnowledgeBundle): string;
+/**
+ * 解析 bundle 文本，逐条判定并把失败原因写成能直接给用户看的一句话。
+ *
+ * 判定顺序即优先级：先看「有没有内容/是不是 JSON/顶层像不像 bundle」这类
+ * 一眼能定性的问题，再进 schemaVersion 与卡数上限，最后才逐卡看必填字段——
+ * 用户拿到的第一条错误就是最该先修的那条。
+ */
+declare function parseKnowledgeBundle(text: string): {
+  readonly ok: true;
+  readonly bundle: KnowledgeBundle;
+} | {
+  readonly ok: false;
+  readonly error: string;
+};
+type KnowledgeImportMode = 'skip' | 'overwrite';
+interface KnowledgeImportEntry {
+  readonly id: string;
+  readonly title: string;
+  readonly url: string;
+}
+interface KnowledgeImportPlan {
+  readonly create: readonly KnowledgeCard[];
+  readonly update: readonly KnowledgeCard[];
+  readonly skipped: readonly (KnowledgeImportEntry & {
+    readonly reason: string;
+  })[];
+  readonly droppedRelated: readonly {
+    readonly id: string;
+    readonly missing: readonly string[];
+  }[];
+  readonly invalid: readonly {
+    readonly index: number;
+    readonly title?: string;
+    readonly error: string;
+  }[];
+  readonly remappedIds: readonly {
+    readonly from: string;
+    readonly to: string;
+  }[];
+}
+/**
+ * 纯函数：算出「把 incoming 导入本机库」要做的事，不读文件、不调 store、不写库。
+ *
+ * 去重键是 source.url（与 knowledge-fs.getByUrl 同口径：trim 后精确相等）。
+ * 顺序是有意的：先给每张 incoming 定身份与最终 id，再改 related（此时映射表已完整），
+ * 最后统一过 validate——任何一张校验失败只进 invalid，不影响其它卡片。
+ */
+declare function planKnowledgeImport(local: readonly KnowledgeCard[], incoming: readonly KnowledgeCard[], mode: KnowledgeImportMode, options?: {
+  readonly now?: Date;
+}): KnowledgeImportPlan;
+//#endregion
+export { KNOWLEDGE_BUNDLE_MAX_BYTES, KNOWLEDGE_BUNDLE_MAX_CARDS, KNOWLEDGE_BUNDLE_SCHEMA_VERSION, KnowledgeBundle, KnowledgeBundleMeta, KnowledgeImportEntry, KnowledgeImportMode, KnowledgeImportPlan, createKnowledgeBundle, parseKnowledgeBundle, planKnowledgeImport, serializeKnowledgeBundle };

package/lib/bundle.js

@@ -0,0 +1,296 @@
+import { generateCardId, validateKnowledgeCard } from "./validate.js";
+//#region src/bundle.ts
+/** bundle 格式版本：本机只认这一版，改动卡片契约时递增。 */
+const KNOWLEDGE_BUNDLE_SCHEMA_VERSION = 1;
+/** 单次导入卡片数上限：防止一次导入把库撑到图形/检索不可用的量级。 */
+const KNOWLEDGE_BUNDLE_MAX_CARDS = 2e3;
+/** 单文件字节上限（8 MiB）：整个文件要先读进内存再解析，读之前就要有界。 */
+const KNOWLEDGE_BUNDLE_MAX_BYTES = 8388608;
+const BUNDLE_GENERATOR = "dsh-trading";
+const BUNDLE_NOTICE = "知识卡片是第三方观点的结构化转述，不构成投资建议；来源作者与原始链接随卡片保留以便查证。";
+/**
+* 由卡片列表构造 bundle。
+*
+* 不做深拷贝也不做字段裁剪：导出的是库里已有的卡片（store 写入面已归一作者），
+* 这里改字段只会让「导出—导入—再导出」三份内容对不上。
+*/
+function createKnowledgeBundle(cards, options = {}) {
+	return {
+		meta: {
+			schemaVersion: 1,
+			exportedAt: (options.now ?? /* @__PURE__ */ new Date()).toISOString(),
+			cardCount: cards.length,
+			generator: BUNDLE_GENERATOR,
+			notice: BUNDLE_NOTICE
+		},
+		cards
+	};
+}
+/** 落盘文本：2 空格缩进（人可读、可 diff）+ 收尾换行（符合 POSIX 文本约定）。 */
+function serializeKnowledgeBundle(bundle) {
+	return JSON.stringify(bundle, null, 2) + "\n";
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* 解析 bundle 文本，逐条判定并把失败原因写成能直接给用户看的一句话。
+*
+* 判定顺序即优先级：先看「有没有内容/是不是 JSON/顶层像不像 bundle」这类
+* 一眼能定性的问题，再进 schemaVersion 与卡数上限，最后才逐卡看必填字段——
+* 用户拿到的第一条错误就是最该先修的那条。
+*/
+function parseKnowledgeBundle(text) {
+	if (typeof text !== "string" || text.trim().length === 0) return {
+		ok: false,
+		error: "bundle 内容为空"
+	};
+	const bytes = new TextEncoder().encode(text).length;
+	if (bytes > 8388608) return {
+		ok: false,
+		error: `bundle 体积 ${bytes} 字节超过上限 ${KNOWLEDGE_BUNDLE_MAX_BYTES} 字节（8 MiB），请拆分后再导入`
+	};
+	let parsed;
+	try {
+		parsed = JSON.parse(text);
+	} catch (error) {
+		return {
+			ok: false,
+			error: `bundle 不是合法 JSON: ${error instanceof Error ? error.message : String(error)}`
+		};
+	}
+	if (!isRecord(parsed)) return {
+		ok: false,
+		error: "bundle 顶层必须是 JSON 对象（含 meta 与 cards 两个字段）"
+	};
+	if (!isRecord(parsed.meta)) return {
+		ok: false,
+		error: "bundle 缺少 meta 字段（应为对象）"
+	};
+	if (parsed.cards === void 0) return {
+		ok: false,
+		error: "bundle 缺少 cards 字段（应为卡片数组）"
+	};
+	const meta = parsed.meta;
+	if (meta.schemaVersion !== 1) return {
+		ok: false,
+		error: `不支持的 schemaVersion: ${String(meta.schemaVersion)}（本机支持 1）`
+	};
+	if (!Array.isArray(parsed.cards)) return {
+		ok: false,
+		error: "bundle 的 cards 必须是数组"
+	};
+	const cards = parsed.cards;
+	if (cards.length > 2e3) return {
+		ok: false,
+		error: `bundle 卡片数 ${cards.length} 超过上限 ${KNOWLEDGE_BUNDLE_MAX_CARDS} 张，请拆分后再导入`
+	};
+	for (let index = 0; index < cards.length; index += 1) {
+		const card = cards[index];
+		const position = `第 ${index + 1} 张卡片（下标 ${index}）`;
+		if (!isRecord(card)) return {
+			ok: false,
+			error: `${position}不是 JSON 对象`
+		};
+		const missing = [];
+		if (typeof card.id !== "string" || card.id.trim().length === 0) missing.push("id");
+		if (typeof card.title !== "string" || card.title.trim().length === 0) missing.push("title");
+		const source = card.source;
+		if (!isRecord(source) || typeof source.url !== "string" || source.url.trim().length === 0) missing.push("source.url");
+		if (missing.length > 0) return {
+			ok: false,
+			error: `${position}缺少或非法字段: ${missing.join(", ")}`
+		};
+	}
+	return {
+		ok: true,
+		bundle: parsed
+	};
+}
+/**
+* 拆出 related 与其余字段。
+*
+* related 不能简单「置 undefined」：exactOptionalPropertyTypes 下「没有关联」是
+* 不带这个键，而且基础内容若残留 incoming 里已被丢弃的旧引用，校验会替我们放行
+* 一条本该消失的关联。先摘出来、过滤完再条件回填，两个问题一起消掉。
+*/
+function splitRelated(input) {
+	const { related, ...base } = input;
+	return {
+		base,
+		related
+	};
+}
+/**
+* related 存在性校验用的最小占位卡片。
+*
+* 只为凑出「本地 id ∪ 本批次待写 id」这个集合（validateKnowledgeCard 只读 id），
+* 永远不会被写库——所以字段能给多小给多小。
+*/
+function placeholderCard(id) {
+	return {
+		id,
+		title: "",
+		summary: "",
+		source: {
+			type: "manual",
+			url: "",
+			author: ""
+		},
+		credibility: "low",
+		coreClaims: [],
+		factCheck: {
+			verified: [],
+			discrepancies: [],
+			unverifiable: []
+		},
+		takeaways: [],
+		boundaries: [],
+		tags: [],
+		createdAt: "",
+		updatedAt: ""
+	};
+}
+/**
+* 纯函数：算出「把 incoming 导入本机库」要做的事，不读文件、不调 store、不写库。
+*
+* 去重键是 source.url（与 knowledge-fs.getByUrl 同口径：trim 后精确相等）。
+* 顺序是有意的：先给每张 incoming 定身份与最终 id，再改 related（此时映射表已完整），
+* 最后统一过 validate——任何一张校验失败只进 invalid，不影响其它卡片。
+*/
+function planKnowledgeImport(local, incoming, mode, options = {}) {
+	const localIds = new Set(local.map((card) => card.id));
+	const localByUrl = /* @__PURE__ */ new Map();
+	for (const card of local) {
+		const url = typeof card.source?.url === "string" ? card.source.url.trim() : "";
+		if (url.length > 0 && !localByUrl.has(url)) localByUrl.set(url, card);
+	}
+	const skipped = [];
+	const remappedIds = [];
+	const pending = [];
+	/** 本批次已占用的 id：先到的卡片赢，后到的冲突重生成。 */
+	const claimedIds = /* @__PURE__ */ new Set();
+	/**
+	* remappedIds 的 from 侧。这些 bundle id 已经指向别的卡片（本机同链接卡、或本批更早的卡），
+	* 同批次里就不能再拿它当新卡 id——否则同一个 id 在映射表里同时指向两张卡，related 解析变含糊。
+	*/
+	const remappedFrom = /* @__PURE__ */ new Set();
+	/** 记录一条 id 重映射：数组给报告与映射表用，集合给「已占用」判定用，两处必须同步。 */
+	const recordRemap = (from, to) => {
+		remappedIds.push({
+			from,
+			to
+		});
+		remappedFrom.add(from);
+	};
+	for (let index = 0; index < incoming.length; index += 1) {
+		const card = incoming[index];
+		if (!isRecord(card)) continue;
+		const url = typeof card.source?.url === "string" ? card.source.url.trim() : "";
+		const existing = url.length > 0 ? localByUrl.get(url) : void 0;
+		if (existing) {
+			const targetId = existing.id;
+			const bundleId = typeof card.id === "string" ? card.id.trim() : "";
+			if (bundleId.length > 0 && bundleId !== targetId) recordRemap(bundleId, targetId);
+			if (mode === "skip") {
+				skipped.push({
+					id: targetId,
+					title: existing.title,
+					url: existing.source.url,
+					reason: "source.url 已存在"
+				});
+				continue;
+			}
+			const id = targetId;
+			claimedIds.add(id);
+			const merged = {
+				...existing,
+				...card,
+				id,
+				createdAt: existing.createdAt
+			};
+			pending.push({
+				kind: "update",
+				index,
+				id,
+				...splitRelated(merged)
+			});
+			continue;
+		}
+		const bundleId = typeof card.id === "string" ? card.id.trim() : "";
+		let id = bundleId.length > 0 && bundleId.startsWith("kc_") ? bundleId : generateCardId();
+		if (localIds.has(id) || claimedIds.has(id) || remappedFrom.has(id)) {
+			const fresh = generateCardId();
+			recordRemap(id, fresh);
+			id = fresh;
+		}
+		claimedIds.add(id);
+		const createdAt = typeof card.createdAt === "string" ? card.createdAt : void 0;
+		const created = createdAt === void 0 ? {
+			...card,
+			id
+		} : {
+			...card,
+			id,
+			createdAt
+		};
+		pending.push({
+			kind: "create",
+			index,
+			id,
+			...splitRelated(created)
+		});
+	}
+	const pendingIds = new Set(pending.map((item) => item.id));
+	const knownIds = /* @__PURE__ */ new Set([...localIds, ...pendingIds]);
+	const remap = new Map(remappedIds.map((entry) => [entry.from, entry.to]));
+	const existingForValidation = [...local, ...[...pendingIds].map(placeholderCard)];
+	const create = [];
+	const update = [];
+	const droppedRelated = [];
+	const invalid = [];
+	const nowIso = options.now?.toISOString();
+	for (const item of pending) {
+		let related;
+		if (Array.isArray(item.related) && item.related.length > 0) {
+			const mapped = item.related.map((value) => remap.get(value) ?? value);
+			const kept = mapped.filter((value) => knownIds.has(value));
+			const missing = Array.from(new Set(mapped.filter((value) => !knownIds.has(value))));
+			if (missing.length > 0) droppedRelated.push({
+				id: item.id,
+				missing
+			});
+			related = kept.length > 0 ? Array.from(new Set(kept)) : void 0;
+		}
+		const input = related === void 0 ? item.base : {
+			...item.base,
+			related
+		};
+		const validation = validateKnowledgeCard(input, existingForValidation);
+		if (!validation.ok || !validation.card) {
+			const titleText = typeof input.title === "string" && input.title.trim().length > 0 ? input.title : void 0;
+			invalid.push({
+				index: item.index,
+				error: validation.error ?? "未知校验错误",
+				...titleText === void 0 ? {} : { title: titleText }
+			});
+			continue;
+		}
+		const card = nowIso === void 0 ? validation.card : {
+			...validation.card,
+			updatedAt: nowIso
+		};
+		if (item.kind === "create") create.push(card);
+		else update.push(card);
+	}
+	return {
+		create,
+		update,
+		skipped,
+		droppedRelated,
+		invalid,
+		remappedIds
+	};
+}
+//#endregion
+export { KNOWLEDGE_BUNDLE_MAX_BYTES, KNOWLEDGE_BUNDLE_MAX_CARDS, KNOWLEDGE_BUNDLE_SCHEMA_VERSION, createKnowledgeBundle, parseKnowledgeBundle, planKnowledgeImport, serializeKnowledgeBundle };

package/lib/index.d.ts

@@ -2,5 +2,6 @@ import { BuildGraphOptions, GraphLinkKind, KnowledgeCard, KnowledgeCardInput, Kn
 import { ValidationResult, generateCardId, validateKnowledgeCard } from "./validate.js";
 import { buildGraph } from "./graph.js";
 import { createMemoryKnowledgeCardStore } from "./store-memory.js";
+import { KNOWLEDGE_BUNDLE_MAX_BYTES, KNOWLEDGE_BUNDLE_MAX_CARDS, KNOWLEDGE_BUNDLE_SCHEMA_VERSION, KnowledgeBundle, KnowledgeBundleMeta, KnowledgeImportEntry, KnowledgeImportMode, KnowledgeImportPlan, createKnowledgeBundle, parseKnowledgeBundle, planKnowledgeImport, serializeKnowledgeBundle } from "./bundle.js";
 import { AUTHOR_ALIASES, canonicalAuthor, canonicalizeCardAuthor } from "./authors.js";
-export { AUTHOR_ALIASES, type BuildGraphOptions, type GraphLinkKind, type KnowledgeCard, type KnowledgeCardInput, type KnowledgeCardStore, type KnowledgeCredibility, type KnowledgeFactCheck, type KnowledgeGraphData, type KnowledgeGraphLink, type KnowledgeGraphNode, type KnowledgeSource, type KnowledgeSourceType, type ValidationResult, buildGraph, canonicalAuthor, canonicalizeCardAuthor, createMemoryKnowledgeCardStore, generateCardId, validateKnowledgeCard };
+export { AUTHOR_ALIASES, type BuildGraphOptions, type GraphLinkKind, KNOWLEDGE_BUNDLE_MAX_BYTES, KNOWLEDGE_BUNDLE_MAX_CARDS, KNOWLEDGE_BUNDLE_SCHEMA_VERSION, type KnowledgeBundle, type KnowledgeBundleMeta, type KnowledgeCard, type KnowledgeCardInput, type KnowledgeCardStore, type KnowledgeCredibility, type KnowledgeFactCheck, type KnowledgeGraphData, type KnowledgeGraphLink, type KnowledgeGraphNode, type KnowledgeImportEntry, type KnowledgeImportMode, type KnowledgeImportPlan, type KnowledgeSource, type KnowledgeSourceType, type ValidationResult, buildGraph, canonicalAuthor, canonicalizeCardAuthor, createKnowledgeBundle, createMemoryKnowledgeCardStore, generateCardId, parseKnowledgeBundle, planKnowledgeImport, serializeKnowledgeBundle, validateKnowledgeCard };

package/lib/index.js

@@ -2,4 +2,5 @@ import { AUTHOR_ALIASES, canonicalAuthor, canonicalizeCardAuthor } from "./autho
 import { generateCardId, validateKnowledgeCard } from "./validate.js";
 import { buildGraph } from "./graph.js";
 import { createMemoryKnowledgeCardStore } from "./store-memory.js";
-export { AUTHOR_ALIASES, buildGraph, canonicalAuthor, canonicalizeCardAuthor, createMemoryKnowledgeCardStore, generateCardId, validateKnowledgeCard };
+import { KNOWLEDGE_BUNDLE_MAX_BYTES, KNOWLEDGE_BUNDLE_MAX_CARDS, KNOWLEDGE_BUNDLE_SCHEMA_VERSION, createKnowledgeBundle, parseKnowledgeBundle, planKnowledgeImport, serializeKnowledgeBundle } from "./bundle.js";
+export { AUTHOR_ALIASES, KNOWLEDGE_BUNDLE_MAX_BYTES, KNOWLEDGE_BUNDLE_MAX_CARDS, KNOWLEDGE_BUNDLE_SCHEMA_VERSION, buildGraph, canonicalAuthor, canonicalizeCardAuthor, createKnowledgeBundle, createMemoryKnowledgeCardStore, generateCardId, parseKnowledgeBundle, planKnowledgeImport, serializeKnowledgeBundle, validateKnowledgeCard };

package/lib/plugin.js

@@ -1,10 +1,10 @@
 import { countGraphSummary } from "./graph.js";
 import { createFileKnowledgeCardStore } from "./knowledge-fs.js";
-import { createKnowledgeDeleteTool, createKnowledgeGetTool, createKnowledgeIngestTool, createKnowledgeSearchTool } from "./tool.js";
+import { createKnowledgeDeleteTool, createKnowledgeExportTool, createKnowledgeGetTool, createKnowledgeImportTool, createKnowledgeIngestTool, createKnowledgeSearchTool } from "./tool.js";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import path from "node:path";
 import { dshHomeDir } from "@dshtrading/dsh-home";
 import { Service } from "@deepseek-ai/cordis";
-import path from "node:path";
 //#region src/plugin.ts
 /** Cordis 插件名 = patch 行 id（TEMPLATES §8）。 */
 const name = "dsh-trading-knowledge";
@@ -71,6 +71,8 @@ function registerKnowledgeTools(ctx, deps) {
 		register(createKnowledgeSearchTool(deps.store));
 		register(createKnowledgeGetTool(deps.store));
 		register(createKnowledgeDeleteTool(deps.store, { onWritten: () => events()?.emit("knowledge") }));
+		register(createKnowledgeExportTool(deps.store));
+		register(createKnowledgeImportTool(deps.store, { onWritten: () => events()?.emit("knowledge") }));
 		register(createKnowledgeGraphTool({ store: deps.store }));
 	});
 }

package/lib/tool.d.ts

@@ -13,5 +13,11 @@ interface KnowledgeDeleteToolOptions {
   onWritten?: () => void;
 }
 declare function createKnowledgeDeleteTool(store: KnowledgeCardStore, options?: KnowledgeDeleteToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createKnowledgeExportTool(store: KnowledgeCardStore): import("@deepseek-ai/dsh-tools").ToolDefinition;
+interface KnowledgeImportToolOptions {
+  /** 可选：成功写库后的回调（与 ingest/delete 一致，emit('knowledge') 通知 UI 刷新）。 */
+  onWritten?: () => void;
+}
+declare function createKnowledgeImportTool(store: KnowledgeCardStore, options?: KnowledgeImportToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
 //#endregion
-export { KnowledgeDeleteToolOptions, KnowledgeIngestToolOptions, createFileKnowledgeCardStore, createKnowledgeDeleteTool, createKnowledgeGetTool, createKnowledgeIngestTool, createKnowledgeSearchTool };
+export { KnowledgeDeleteToolOptions, KnowledgeImportToolOptions, KnowledgeIngestToolOptions, createFileKnowledgeCardStore, createKnowledgeDeleteTool, createKnowledgeExportTool, createKnowledgeGetTool, createKnowledgeImportTool, createKnowledgeIngestTool, createKnowledgeSearchTool };

package/lib/tool.js

@@ -1,6 +1,11 @@
 import { validateKnowledgeCard } from "./validate.js";
+import { createKnowledgeBundle, parseKnowledgeBundle, planKnowledgeImport, serializeKnowledgeBundle } from "./bundle.js";
 import { createFileKnowledgeCardStore } from "./knowledge-fs.js";
 import { defineTool } from "@deepseek-ai/dsh-tools";
+import os from "node:os";
+import path from "node:path";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dshHomeDir } from "@dshtrading/dsh-home";
 //#region src/tool.ts
 /**
 * 知识库 Agent 工具（对齐 docs/design/knowledge-graph.md §4 与 dsh-tools 规范）。
@@ -10,6 +15,8 @@ import { defineTool } from "@deepseek-ai/dsh-tools";
 *   - knowledge_search: 跨字段检索（相关度排序）+ 多维过滤 + detail=full 全文返回
 *   - knowledge_get:    按 id 读取单张卡片全文
 *   - knowledge_delete: 证伪下架（删除卡片并清理 related 悬空引用）
+*   - knowledge_export: 按检索同款过滤导出单文件 JSON bundle
+*   - knowledge_import: bundle 先算计划（预览）再写库，source.url 去重
 */
 /** 卡片全文的统一文本渲染（knowledge_get 与 knowledge_search detail=full 共用）。 */
 function renderCardFullLines(card) {
@@ -426,5 +433,155 @@ function createKnowledgeDeleteTool(store, options = {}) {
 		}
 	});
 }
+/** bundle 文件名里的时间戳（本地时区）：用户在导出目录里按时间对号，UTC 会错位。 */
+function compactTimestamp(date) {
+	const pad = (value) => String(value).padStart(2, "0");
+	return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+/** 导出/导入共用的路径解析：`~` 前缀展开 + 相对路径按 process.cwd() 解析（与 node 工具惯例一致）。 */
+function resolveUserPath(input) {
+	const trimmed = input.trim();
+	if (trimmed === "~") return os.homedir();
+	if (trimmed.startsWith("~/") || trimmed.startsWith("~\\")) return path.resolve(os.homedir(), trimmed.slice(2));
+	return path.resolve(process.cwd(), trimmed);
+}
+function createKnowledgeExportTool(store) {
+	return defineTool({
+		name: "knowledge_export",
+		description: "Export knowledge cards into one JSON bundle file (meta + cards) for backup or transfer to another library. Filters follow knowledge_search semantics exactly: tags (comma separated, matches any one), sourceType, credibility, and cluster (the card first tag). Without filters the whole library is exported. Import it back with knowledge_import.",
+		parameters: {
+			path: {
+				type: "string",
+				description: "Target file path (absolute, or relative to the current working directory). Omit it to write $DSH_HOME/knowledge/exports/knowledge-<yyyyMMdd-HHmmss>.json."
+			},
+			tags: {
+				type: "string",
+				description: "Comma-separated tag filter, e.g. \"宏观,高股息\"; matches any one of them."
+			},
+			sourceType: {
+				type: "string",
+				description: "Source kind filter: \"bilibili\" | \"wechat\" | \"manual\"."
+			},
+			credibility: {
+				type: "string",
+				description: "Credibility filter: \"high\" | \"medium\" | \"low\"."
+			},
+			cluster: {
+				type: "string",
+				description: "Exact subject filter (subject = the card first tag), same as knowledge_search cluster."
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: String(value)
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const requestedPath = typeof args.path === "string" ? args.path.trim() : "";
+			const rawTags = typeof args.tags === "string" ? args.tags.split(",").map((tag) => tag.trim().toLowerCase()).filter(Boolean) : [];
+			const targetSourceType = typeof args.sourceType === "string" ? args.sourceType.trim() : "";
+			const targetCredibility = typeof args.credibility === "string" ? args.credibility.trim() : "";
+			const targetCluster = typeof args.cluster === "string" ? args.cluster.trim().toLowerCase() : "";
+			const selected = (await store.list()).filter((card) => {
+				if (targetSourceType && card.source.type !== targetSourceType) return false;
+				if (targetCredibility && card.credibility !== targetCredibility) return false;
+				if (targetCluster && (card.tags[0] ?? "").trim().toLowerCase() !== targetCluster) return false;
+				if (rawTags.length > 0) {
+					const cardTags = card.tags.map((tag) => tag.toLowerCase());
+					if (!rawTags.some((tag) => cardTags.includes(tag))) return false;
+				}
+				return true;
+			});
+			const filePath = requestedPath.length > 0 ? resolveUserPath(requestedPath) : path.join(dshHomeDir(), "knowledge", "exports", `knowledge-${compactTimestamp(/* @__PURE__ */ new Date())}.json`);
+			try {
+				await mkdir(path.dirname(filePath), { recursive: true });
+				await writeFile(filePath, serializeKnowledgeBundle(createKnowledgeBundle(selected)), "utf8");
+			} catch (error) {
+				return `[knowledge_export] 导出失败: ${error instanceof Error ? error.message : String(error)}`;
+			}
+			const filterParts = [];
+			if (rawTags.length > 0) filterParts.push(`标签命中任一: ${rawTags.join(" / ")}`);
+			if (targetSourceType) filterParts.push(`来源类型: ${targetSourceType}`);
+			if (targetCredibility) filterParts.push(`可信度: ${targetCredibility}`);
+			if (targetCluster) filterParts.push(`主体(聚类): ${targetCluster}`);
+			return [`[knowledge_export] 已导出 ${selected.length} 张卡片（筛选: ${filterParts.length > 0 ? filterParts.join(" | ") : "全库"}）`, `  文件: ${filePath}`].join("\n");
+		}
+	});
+}
+function createKnowledgeImportTool(store, options = {}) {
+	const { onWritten } = options;
+	return defineTool({
+		name: "knowledge_import",
+		description: "Import knowledge cards from a JSON bundle file produced by knowledge_export. The dedup key is source.url: mode=\"skip\" (default) keeps existing cards and reports them as skipped, mode=\"overwrite\" refreshes their content while keeping the local id and createdAt. The plan is computed first (dryRun=true only previews it, nothing is written), then written with a freshly computed plan. Related ids are remapped inside the bundle; references to cards outside it are dropped and reported.",
+		parameters: {
+			path: {
+				type: "string",
+				required: true,
+				description: "Bundle JSON file path (absolute, \"~/\" prefixed, or relative to the current working directory)."
+			},
+			mode: {
+				type: "string",
+				description: "Duplicate source.url handling: \"skip\" (default, keep the local card) | \"overwrite\" (refresh content, keep local id/createdAt)."
+			},
+			dryRun: {
+				type: "boolean",
+				description: "Preview the plan without writing anything (default false)."
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: String(value)
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const requestedPath = typeof args.path === "string" ? args.path.trim() : "";
+			if (requestedPath.length === 0) return "[knowledge_import] 参数 path 为必填字符串（bundle JSON 文件路径）";
+			const rawMode = typeof args.mode === "string" ? args.mode.trim() : "";
+			if (rawMode !== "" && rawMode !== "skip" && rawMode !== "overwrite") return `[knowledge_import] 参数 mode 非法: ${rawMode}（允许值: skip, overwrite；省略即 skip）`;
+			const mode = rawMode === "overwrite" ? "overwrite" : "skip";
+			const dryRun = args.dryRun === true;
+			const filePath = resolveUserPath(requestedPath);
+			let text;
+			try {
+				text = await readFile(filePath, "utf8");
+			} catch (error) {
+				if (error?.code === "ENOENT") return `[knowledge_import] 文件不存在: ${filePath}`;
+				return `[knowledge_import] 读取失败: ${error instanceof Error ? error.message : String(error)}（${filePath}）`;
+			}
+			const parsed = parseKnowledgeBundle(text);
+			if (!parsed.ok) return `[knowledge_import] ${parsed.error}`;
+			const local = await store.list();
+			const plan = planKnowledgeImport(local, parsed.bundle.cards, mode);
+			const toWrite = [...plan.create, ...plan.update];
+			let written = 0;
+			if (!dryRun && toWrite.length > 0) {
+				try {
+					if (typeof store.saveMany === "function") await store.saveMany(toWrite);
+					else for (const card of toWrite) await store.save(card);
+				} catch (error) {
+					return `[knowledge_import] 写入失败: ${error instanceof Error ? error.message : String(error)}（计划写入 ${toWrite.length} 张）`;
+				}
+				written = toWrite.length;
+				onWritten?.();
+			}
+			const lines = [`[knowledge_import] ${dryRun ? "dryRun 预览（未写库）" : `已写入 ${written} 张`}, mode=${mode}`, `  新增 ${plan.create.length} / 更新 ${plan.update.length} / 跳过 ${plan.skipped.length} / 丢弃关联 ${plan.droppedRelated.length} / 非法 ${plan.invalid.length}`];
+			for (const entry of plan.skipped) lines.push(`  跳过: [${entry.id}] "${entry.title}"（${entry.reason}）`);
+			for (const entry of plan.droppedRelated) lines.push(`  丢弃关联: [${entry.id}] 缺失 ${entry.missing.join(", ")}`);
+			for (const entry of plan.invalid) {
+				const title = entry.title === void 0 ? "" : ` "${entry.title}"`;
+				lines.push(`  非法: 第 ${entry.index + 1} 张卡（下标 ${entry.index}）${title}: ${entry.error}`);
+			}
+			for (const entry of plan.remappedIds) lines.push(`  id 重映射: ${entry.from} → ${entry.to}`);
+			if (toWrite.length === 0) lines.push("  （没有需要写入的卡片）");
+			return lines.join("\n");
+		}
+	});
+}
 //#endregion
-export { createFileKnowledgeCardStore, createKnowledgeDeleteTool, createKnowledgeGetTool, createKnowledgeIngestTool, createKnowledgeSearchTool };
+export { createFileKnowledgeCardStore, createKnowledgeDeleteTool, createKnowledgeExportTool, createKnowledgeGetTool, createKnowledgeImportTool, createKnowledgeIngestTool, createKnowledgeSearchTool };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dshtrading/knowledge",
   "description": "Knowledge base data plane for dsh-trading: KnowledgeCard data model, validation, graph builder, atomic file store, and knowledge_ingest / knowledge_search agent tools.",
-  "version": "0.6.3",
+  "version": "0.7.1",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -25,11 +25,11 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@dshtrading/dsh-home": "^0.6.3"
+    "@dshtrading/dsh-home": "^0.7.1"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": ">=4.0.0",
-    "@deepseek-ai/dsh-tools": ">=0.2.1-rc.2"
+    "@deepseek-ai/cordis": ">=4.1.0",
+    "@deepseek-ai/dsh-tools": ">=0.2.2-rc.1"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",