@dshtrading/knowledge 0.1.0

package/LICENSE

@@ -0,0 +1,75 @@
+Copyright (c) 2026 zhu1090093659 (dsh-trading)
+
+# PolyForm Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose.  However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+## Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software.  Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Yoyodyne, Inc. (http://example.com)
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/lib/graph.d.ts

@@ -0,0 +1,5 @@
+import { BuildGraphOptions, KnowledgeCard, KnowledgeGraphData } from "./types.js";
+//#region src/graph.d.ts
+declare function buildGraph(cards: readonly KnowledgeCard[], options?: BuildGraphOptions): KnowledgeGraphData;
+//#endregion
+export { buildGraph };

package/lib/graph.js

@@ -0,0 +1,145 @@
+//#region src/graph.ts
+function buildGraph(cards, options = {}) {
+	const { coTag = true, coAuthor = true, tagHubs = false } = options;
+	if (!cards || cards.length === 0) return {
+		nodes: [],
+		links: []
+	};
+	const cardMap = /* @__PURE__ */ new Map();
+	for (const c of cards) cardMap.set(c.id, c);
+	const linkMap = /* @__PURE__ */ new Map();
+	function makeLinkKey(id1, id2, kind) {
+		const [a, b] = id1 < id2 ? [id1, id2] : [id2, id1];
+		return `${kind}:${a}:${b}`;
+	}
+	if (tagHubs) {
+		for (const card of cards) {
+			if (card.related && Array.isArray(card.related)) {
+				for (const targetId of card.related) if (cardMap.has(targetId) && targetId !== card.id) {
+					const key = makeLinkKey(card.id, targetId, "related");
+					if (!linkMap.has(key)) {
+						const [source, target] = card.id < targetId ? [card.id, targetId] : [targetId, card.id];
+						linkMap.set(key, {
+							source,
+							target,
+							kind: "related",
+							weight: 2
+						});
+					}
+				}
+			}
+			const seen = /* @__PURE__ */ new Set();
+			for (const tag of card.tags) {
+				const name = (tag ?? "").trim();
+				if (!name || seen.has(name)) continue;
+				seen.add(name);
+				const hubId = "tag:" + name;
+				linkMap.set(makeLinkKey(card.id, hubId, "tag-hub"), {
+					source: card.id,
+					target: hubId,
+					kind: "tag-hub",
+					weight: 1
+				});
+			}
+		}
+		const hubLinks = Array.from(linkMap.values());
+		const degreeMap = /* @__PURE__ */ new Map();
+		for (const c of cards) degreeMap.set(c.id, 0);
+		for (const l of hubLinks) {
+			degreeMap.set(l.source, (degreeMap.get(l.source) ?? 0) + 1);
+			degreeMap.set(l.target, (degreeMap.get(l.target) ?? 0) + 1);
+		}
+		const cardNodes = cards.map((card) => ({
+			id: card.id,
+			label: card.title,
+			cluster: card.tags[0] ?? "未分类",
+			credibility: card.credibility,
+			degree: degreeMap.get(card.id) ?? 0,
+			type: "card",
+			raw: card
+		}));
+		const hubNodes = [...degreeMap.keys()].filter((id) => id.startsWith("tag:")).map((id) => ({
+			id,
+			label: id.slice(4),
+			cluster: id.slice(4),
+			credibility: "medium",
+			degree: degreeMap.get(id) ?? 0,
+			type: "tag"
+		}));
+		return {
+			nodes: [...cardNodes, ...hubNodes],
+			links: hubLinks
+		};
+	}
+	for (const card of cards) if (card.related && Array.isArray(card.related)) {
+		for (const targetId of card.related) if (cardMap.has(targetId) && targetId !== card.id) {
+			const key = makeLinkKey(card.id, targetId, "related");
+			if (!linkMap.has(key)) {
+				const [source, target] = card.id < targetId ? [card.id, targetId] : [targetId, card.id];
+				linkMap.set(key, {
+					source,
+					target,
+					kind: "related",
+					weight: 2
+				});
+			}
+		}
+	}
+	if (coTag) for (let i = 0; i < cards.length; i++) {
+		const cardA = cards[i];
+		const tagsA = new Set(cardA.tags);
+		for (let j = i + 1; j < cards.length; j++) {
+			const cardB = cards[j];
+			let sharedTagCount = 0;
+			for (const t of cardB.tags) if (tagsA.has(t)) sharedTagCount++;
+			if (sharedTagCount > 0) {
+				const key = makeLinkKey(cardA.id, cardB.id, "co-tag");
+				const [source, target] = cardA.id < cardB.id ? [cardA.id, cardB.id] : [cardB.id, cardA.id];
+				linkMap.set(key, {
+					source,
+					target,
+					kind: "co-tag",
+					weight: sharedTagCount
+				});
+			}
+		}
+	}
+	if (coAuthor) for (let i = 0; i < cards.length; i++) {
+		const cardA = cards[i];
+		const authorA = cardA.source.author.trim();
+		if (!authorA || authorA === "manual" || authorA === "手工") continue;
+		for (let j = i + 1; j < cards.length; j++) {
+			const cardB = cards[j];
+			if (authorA === cardB.source.author.trim()) {
+				const key = makeLinkKey(cardA.id, cardB.id, "co-author");
+				const [source, target] = cardA.id < cardB.id ? [cardA.id, cardB.id] : [cardB.id, cardA.id];
+				linkMap.set(key, {
+					source,
+					target,
+					kind: "co-author",
+					weight: 1
+				});
+			}
+		}
+	}
+	const links = Array.from(linkMap.values());
+	const degreeMap = /* @__PURE__ */ new Map();
+	for (const c of cards) degreeMap.set(c.id, 0);
+	for (const l of links) {
+		degreeMap.set(l.source, (degreeMap.get(l.source) ?? 0) + 1);
+		degreeMap.set(l.target, (degreeMap.get(l.target) ?? 0) + 1);
+	}
+	return {
+		nodes: cards.map((card) => ({
+			id: card.id,
+			label: card.title,
+			cluster: card.tags[0] ?? "未分类",
+			credibility: card.credibility,
+			degree: degreeMap.get(card.id) ?? 0,
+			raw: card
+		})),
+		links
+	};
+}
+//#endregion
+export { buildGraph };

package/lib/index.d.ts

@@ -0,0 +1,5 @@
+import { BuildGraphOptions, GraphLinkKind, KnowledgeCard, KnowledgeCardInput, KnowledgeCardStore, KnowledgeCredibility, KnowledgeFactCheck, KnowledgeGraphData, KnowledgeGraphLink, KnowledgeGraphNode, KnowledgeSource, KnowledgeSourceType } from "./types.js";
+import { ValidationResult, generateCardId, validateKnowledgeCard } from "./validate.js";
+import { buildGraph } from "./graph.js";
+import { createMemoryKnowledgeCardStore } from "./store-memory.js";
+export { 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, createMemoryKnowledgeCardStore, generateCardId, validateKnowledgeCard };

package/lib/index.js

@@ -0,0 +1,4 @@
+import { generateCardId, validateKnowledgeCard } from "./validate.js";
+import { buildGraph } from "./graph.js";
+import { createMemoryKnowledgeCardStore } from "./store-memory.js";
+export { buildGraph, createMemoryKnowledgeCardStore, generateCardId, validateKnowledgeCard };

package/lib/knowledge-fs.d.ts

@@ -0,0 +1,5 @@
+import { KnowledgeCardStore } from "./types.js";
+//#region src/knowledge-fs.d.ts
+declare function createFileKnowledgeCardStore(filePath: string): KnowledgeCardStore;
+//#endregion
+export { createFileKnowledgeCardStore };

package/lib/knowledge-fs.js

@@ -0,0 +1,77 @@
+import { mkdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+//#region src/knowledge-fs.ts
+/**
+* 文件持久化版知识卡片存储（Node.js 宿主端专用）。
+*
+* 采用 tmp + rename 原子写入模式，并包含明确的错误日志与异常处理（逐行对齐 custom-fs.ts 先例）。
+*/
+function createFileKnowledgeCardStore(filePath) {
+	let cache = null;
+	async function load() {
+		if (cache !== null) return cache;
+		try {
+			const content = await readFile(filePath, "utf8");
+			const parsed = JSON.parse(content);
+			const map = /* @__PURE__ */ new Map();
+			if (Array.isArray(parsed)) {
+				for (const item of parsed) if (item && typeof item.id === "string") map.set(item.id, item);
+			}
+			cache = map;
+			return map;
+		} catch (err) {
+			if (err?.code !== "ENOENT") console.error(`[dsh-trading/knowledge] failed to read knowledge cards from ${filePath}:`, err);
+			cache = /* @__PURE__ */ new Map();
+			return cache;
+		}
+	}
+	async function flush(map) {
+		const dir = dirname(filePath);
+		const tmpPath = `${filePath}.tmp.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`;
+		const data = JSON.stringify([...map.values()], null, 2);
+		try {
+			await mkdir(dir, { recursive: true });
+			await writeFile(tmpPath, data, "utf8");
+			let lastError;
+			for (let attempt = 0; attempt < 3; attempt++) try {
+				await rename(tmpPath, filePath);
+				return;
+			} catch (err) {
+				if (err?.code !== "EPERM" && err?.code !== "EBUSY") throw err;
+				lastError = err;
+				await new Promise((resolve) => setTimeout(resolve, 25 * (attempt + 1)));
+			}
+			throw lastError;
+		} catch (error) {
+			console.error(`[dsh-trading/knowledge] failed to atomic flush knowledge cards to ${filePath}:`, error);
+			await unlink(tmpPath).catch(() => {});
+			throw error;
+		}
+	}
+	return {
+		async list() {
+			return [...(await load()).values()];
+		},
+		async get(id) {
+			return (await load()).get(id);
+		},
+		async getByUrl(url) {
+			const map = await load();
+			const trimmed = url.trim();
+			for (const card of map.values()) if (card.source.url.trim() === trimmed) return card;
+		},
+		async save(card) {
+			const map = await load();
+			map.set(card.id, { ...card });
+			await flush(map);
+		},
+		async delete(id) {
+			const map = await load();
+			const existed = map.delete(id);
+			if (existed) await flush(map);
+			return existed;
+		}
+	};
+}
+//#endregion
+export { createFileKnowledgeCardStore };

package/lib/plugin.d.ts

@@ -0,0 +1,34 @@
+import { KnowledgeCardStore } from "./types.js";
+import { createFileKnowledgeCardStore } from "./knowledge-fs.js";
+import { Context, Service } from "@deepseek-ai/cordis";
+//#region src/plugin.d.ts
+/** Cordis 插件名 = patch 行 id（TEMPLATES §8）。 */
+declare const name = "dsh-trading-knowledge";
+/** 本插件不硬依赖任何服务。 */
+declare const inject: string[];
+/** SDK 服务键：知识卡片 store 单实例。 */
+declare const TRADING_KNOWLEDGE_CARDS_KEY = "tradingKnowledgeCards";
+/** tradingEvents 的最小发布面（鸭式；总线缺席时静默降级）。 */
+interface TradingEventsPublisher {
+  emit(store: 'knowledge'): void;
+}
+/** 默认存储路径：~/.dsh/knowledge/cards.json（与 client-ui-trading 旧路径一致）。 */
+declare function defaultStorePath(): string;
+interface KnowledgeGraphToolOptions {
+  store: KnowledgeCardStore;
+}
+/** knowledge_graph 工厂（issue #33 新增；只读结构概要，不倾倒全量 label）。 */
+declare function createKnowledgeGraphTool(options: KnowledgeGraphToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
+interface KnowledgePluginDeps {
+  store: KnowledgeCardStore;
+}
+declare function registerKnowledgeTools(ctx: Context, deps: KnowledgePluginDeps): void;
+/** 知识卡片 store 服务（桥与工具的单实例共享点）。 */
+declare class KnowledgeCardsService extends Service {
+  readonly store: KnowledgeCardStore;
+  constructor(ctx: Context, store: KnowledgeCardStore, serviceName?: string);
+}
+/** Host plugin body：store 服务 provide + 工具注册。 */
+declare function apply(ctx: Context): void;
+//#endregion
+export { KnowledgeCardsService, KnowledgeGraphToolOptions, KnowledgePluginDeps, TRADING_KNOWLEDGE_CARDS_KEY, TradingEventsPublisher, apply, createFileKnowledgeCardStore, createKnowledgeGraphTool, defaultStorePath, inject, name, registerKnowledgeTools };

package/lib/plugin.js

@@ -0,0 +1,92 @@
+import { buildGraph } from "./graph.js";
+import { createFileKnowledgeCardStore } from "./knowledge-fs.js";
+import { createKnowledgeDeleteTool, createKnowledgeGetTool, createKnowledgeIngestTool, createKnowledgeSearchTool } from "./tool.js";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import path from "node:path";
+import { Service } from "@deepseek-ai/cordis";
+import os from "node:os";
+//#region src/plugin.ts
+/** Cordis 插件名 = patch 行 id（TEMPLATES §8）。 */
+const name = "dsh-trading-knowledge";
+/** 本插件不硬依赖任何服务。 */
+const inject = [];
+/** SDK 服务键：知识卡片 store 单实例。 */
+const TRADING_KNOWLEDGE_CARDS_KEY = "tradingKnowledgeCards";
+/** 默认存储路径：~/.dsh/knowledge/cards.json（与 client-ui-trading 旧路径一致）。 */
+function defaultStorePath() {
+	return path.join(os.homedir(), ".dsh", "knowledge", "cards.json");
+}
+/** knowledge_graph 工厂（issue #33 新增；只读结构概要，不倾倒全量 label）。 */
+function createKnowledgeGraphTool(options) {
+	const { store } = options;
+	return defineTool({
+		name: "knowledge_graph",
+		description: "Level 1 of the two-level knowledge retrieval: structural overview of the persisted cards (nodes = cards, edges = shared tags/authors/related). Returns the full cluster (topic) distribution and credibility counts. Pick a cluster here, then drill down with knowledge_search { cluster } and read full cards with knowledge_get.",
+		parameters: {},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: value
+			}]
+		},
+		async execute() {
+			const cards = await store.list();
+			const data = buildGraph(cards);
+			const clusterCounts = /* @__PURE__ */ new Map();
+			const credibility = {
+				high: 0,
+				medium: 0,
+				low: 0
+			};
+			for (const card of cards) {
+				const cluster = card.tags[0] ?? "未分类";
+				clusterCounts.set(cluster, (clusterCounts.get(cluster) ?? 0) + 1);
+				credibility[card.credibility] += 1;
+			}
+			const clusters = [...clusterCounts.entries()].sort((a, b) => b[1] - a[1]).map(([cluster, count]) => ({
+				cluster,
+				count
+			}));
+			return JSON.stringify({
+				ok: true,
+				cards: cards.length,
+				nodeCount: data.nodes.length,
+				edgeCount: data.links.length,
+				clusters,
+				credibility
+			});
+		}
+	});
+}
+function registerKnowledgeTools(ctx, deps) {
+	ctx.inject(["tools"], (toolCtx) => {
+		const tools = toolCtx.tools;
+		if (!tools || typeof tools.register !== "function") return;
+		const events = () => ctx.get?.("tradingEvents", false);
+		const register = (tool) => {
+			if (tools.get(tool.name) === void 0) tools.register(tool);
+		};
+		register(createKnowledgeIngestTool(deps.store, { onWritten: () => events()?.emit("knowledge") }));
+		register(createKnowledgeSearchTool(deps.store));
+		register(createKnowledgeGetTool(deps.store));
+		register(createKnowledgeDeleteTool(deps.store, { onWritten: () => events()?.emit("knowledge") }));
+		register(createKnowledgeGraphTool({ store: deps.store }));
+	});
+}
+/** 知识卡片 store 服务（桥与工具的单实例共享点）。 */
+var KnowledgeCardsService = class extends Service {
+	store;
+	constructor(ctx, store, serviceName = TRADING_KNOWLEDGE_CARDS_KEY) {
+		super(ctx, serviceName);
+		this.store = store;
+	}
+};
+/** Host plugin body：store 服务 provide + 工具注册。 */
+function apply(ctx) {
+	const store = createFileKnowledgeCardStore(defaultStorePath());
+	new KnowledgeCardsService(ctx, store);
+	registerKnowledgeTools(ctx, { store });
+}
+//#endregion
+export { KnowledgeCardsService, TRADING_KNOWLEDGE_CARDS_KEY, apply, createFileKnowledgeCardStore, createKnowledgeGraphTool, defaultStorePath, inject, name, registerKnowledgeTools };

package/lib/store-memory.d.ts

@@ -0,0 +1,5 @@
+import { KnowledgeCard, KnowledgeCardStore } from "./types.js";
+//#region src/store-memory.d.ts
+declare function createMemoryKnowledgeCardStore(initialCards?: readonly KnowledgeCard[]): KnowledgeCardStore;
+//#endregion
+export { createMemoryKnowledgeCardStore };

package/lib/store-memory.js

@@ -0,0 +1,25 @@
+//#region src/store-memory.ts
+function createMemoryKnowledgeCardStore(initialCards = []) {
+	const map = /* @__PURE__ */ new Map();
+	for (const c of initialCards) map.set(c.id, { ...c });
+	return {
+		async list() {
+			return Array.from(map.values());
+		},
+		async get(id) {
+			return map.get(id);
+		},
+		async getByUrl(url) {
+			const trimmed = url.trim();
+			for (const card of map.values()) if (card.source.url.trim() === trimmed) return card;
+		},
+		async save(card) {
+			map.set(card.id, { ...card });
+		},
+		async delete(id) {
+			return map.delete(id);
+		}
+	};
+}
+//#endregion
+export { createMemoryKnowledgeCardStore };

package/lib/tool.d.ts

@@ -0,0 +1,17 @@
+import { KnowledgeCard, KnowledgeCardStore } from "./types.js";
+import { createFileKnowledgeCardStore } from "./knowledge-fs.js";
+//#region src/tool.d.ts
+interface KnowledgeIngestToolOptions {
+  /** 可选：卡片成功落盘后的回调（issue #30：事件总线 emit('knowledge') 的接线点）。 */
+  onWritten?: (card: KnowledgeCard) => void;
+}
+declare function createKnowledgeIngestTool(store: KnowledgeCardStore, options?: KnowledgeIngestToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createKnowledgeSearchTool(store: KnowledgeCardStore): import("@deepseek-ai/dsh-tools").ToolDefinition;
+declare function createKnowledgeGetTool(store: KnowledgeCardStore): import("@deepseek-ai/dsh-tools").ToolDefinition;
+interface KnowledgeDeleteToolOptions {
+  /** 可选：删除成功后的回调（与 ingest 一致，emit('knowledge') 通知 UI 刷新）。 */
+  onWritten?: () => void;
+}
+declare function createKnowledgeDeleteTool(store: KnowledgeCardStore, options?: KnowledgeDeleteToolOptions): import("@deepseek-ai/dsh-tools").ToolDefinition;
+//#endregion
+export { KnowledgeDeleteToolOptions, KnowledgeIngestToolOptions, createFileKnowledgeCardStore, createKnowledgeDeleteTool, createKnowledgeGetTool, createKnowledgeIngestTool, createKnowledgeSearchTool };

package/lib/tool.js

@@ -0,0 +1,383 @@
+import { validateKnowledgeCard } from "./validate.js";
+import { createFileKnowledgeCardStore } from "./knowledge-fs.js";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/tool.ts
+/**
+* 知识库 Agent 工具（对齐 docs/design/knowledge-graph.md §4 与 dsh-tools 规范）。
+*
+* 包含：
+*   - knowledge_ingest: 结构校验 + URL 查重 Update / Create
+*   - knowledge_search: 跨字段检索（相关度排序）+ 多维过滤 + detail=full 全文返回
+*   - knowledge_get:    按 id 读取单张卡片全文
+*   - knowledge_delete: 证伪下架（删除卡片并清理 related 悬空引用）
+*/
+/** 卡片全文的统一文本渲染（knowledge_get 与 knowledge_search detail=full 共用）。 */
+function renderCardFullLines(card) {
+	const lines = [];
+	if (card.coreClaims.length > 0) lines.push(`  核心论点: ${card.coreClaims.join("；")}`);
+	const fc = card.factCheck;
+	const fcParts = [];
+	if (fc.verified.length > 0) fcParts.push(`证实: ${fc.verified.join("；")}`);
+	if (fc.discrepancies.length > 0) fcParts.push(`有出入: ${fc.discrepancies.join("；")}`);
+	if (fc.unverifiable.length > 0) fcParts.push(`无法核实: ${fc.unverifiable.join("；")}`);
+	if (fcParts.length > 0) lines.push(`  事实核查: ${fcParts.join(" | ")}`);
+	if (card.takeaways.length > 0) lines.push(`  可复用经验: ${card.takeaways.join("；")}`);
+	if (card.boundaries.length > 0) lines.push(`  适用边界: ${card.boundaries.join("；")}`);
+	if (card.tickers && card.tickers.length > 0) lines.push(`  关联标的: ${card.tickers.join(", ")}`);
+	return lines;
+}
+function createKnowledgeIngestTool(store, options = {}) {
+	const { onWritten } = options;
+	return defineTool({
+		name: "knowledge_ingest",
+		description: "将经事实核查后的结构化知识卡片（Content Insight 产物）入库到本地知识库。支持自动 URL 查重（重复 URL 自动走更新且保持 ID 不变）及关联关系验证。",
+		parameters: {
+			title: {
+				type: "string",
+				required: true,
+				description: "知识卡片主题（例如「高股息策略在低利率环境下的防御逻辑」）"
+			},
+			summary: {
+				type: "string",
+				required: true,
+				description: "2-4 条核心论点合并的一句话概述（图谱 hover 与快速导读展示）"
+			},
+			sourceType: {
+				type: "string",
+				required: true,
+				description: "素材来源类型：\"bilibili\"（B站）、\"wechat\"（微信公众号）、\"manual\"（手工录入）"
+			},
+			sourceUrl: {
+				type: "string",
+				required: true,
+				description: "素材链接或去重标识（例如 B 站 BV 链接、公众号文章链接）"
+			},
+			sourceAuthor: {
+				type: "string",
+				required: true,
+				description: "来源作者/UP主/公众号名称"
+			},
+			publishedAt: {
+				type: "string",
+				description: "素材发布日期（ISO 格式如 2026-08-30，可选）"
+			},
+			credibility: {
+				type: "string",
+				required: true,
+				description: "依据事实核查整体定级：\"high\"（事实严密证据充分）、\"medium\"（观点可取但部分有出入）、\"low\"（存在重大未核实或明显漏洞）"
+			},
+			coreClaimsJson: {
+				type: "string",
+				required: true,
+				description: "JSON 字符串数组，核心论点列表（保留原作者推理链条），例如 '[\"论点1\", \"论点2\"]'"
+			},
+			factCheckJson: {
+				type: "string",
+				required: true,
+				description: "JSON 对象，事实核查三档分类，例如 '{\"verified\":[\"证实1\"],\"discrepancies\":[\"出入1\"],\"unverifiable\":[]}'"
+			},
+			takeawaysJson: {
+				type: "string",
+				description: "可选 JSON 字符串数组，可复用的分析框架与经验总结，例如 '[\"经验1\"]'"
+			},
+			boundariesJson: {
+				type: "string",
+				description: "可选 JSON 字符串数组，适用边界、失效情景与避坑指南，例如 '[\"边界1\"]'"
+			},
+			tagsJson: {
+				type: "string",
+				required: true,
+				description: "JSON 字符串数组，受控主题标签列表，例如 '[\"宏观\", \"高股息\", \"红利策略\"]'"
+			},
+			tickersJson: {
+				type: "string",
+				description: "可选 JSON 字符串数组，关联标的代码列表，例如 '[\"BTCUSDT\", \"600519.SH\"]'"
+			},
+			relatedJson: {
+				type: "string",
+				description: "可选 JSON 字符串数组，显式关联的其他已入库卡片 ID 列表，例如 '[\"kc_01j...\", \"kc_01k...\"]'"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: String(value)
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			function parseJsonArray(val, fieldName, required = false) {
+				if (!val) return [];
+				if (Array.isArray(val)) return val.map(String);
+				if (typeof val === "string") try {
+					const parsed = JSON.parse(val);
+					if (Array.isArray(parsed)) return parsed.map(String);
+				} catch {
+					throw new Error(`[knowledge_ingest] 参数 ${fieldName} 不是合法的 JSON 数组: ${val}`);
+				}
+				if (required) throw new Error(`[knowledge_ingest] 参数 ${fieldName} 必须为字符串数组`);
+				return [];
+			}
+			function parseJsonObject(val, fieldName) {
+				if (!val) return {};
+				if (typeof val === "object" && !Array.isArray(val)) return val;
+				if (typeof val === "string") try {
+					const parsed = JSON.parse(val);
+					if (typeof parsed === "object" && parsed !== null) return parsed;
+				} catch {
+					throw new Error(`[knowledge_ingest] 参数 ${fieldName} 不是合法的 JSON 对象: ${val}`);
+				}
+				return {};
+			}
+			let coreClaims = [];
+			let factCheck = {
+				verified: [],
+				discrepancies: [],
+				unverifiable: []
+			};
+			let takeaways = [];
+			let boundaries = [];
+			let tags = [];
+			let tickers;
+			let related;
+			try {
+				coreClaims = parseJsonArray(args.coreClaimsJson, "coreClaimsJson", true);
+				factCheck = parseJsonObject(args.factCheckJson, "factCheckJson");
+				takeaways = parseJsonArray(args.takeawaysJson, "takeawaysJson");
+				boundaries = parseJsonArray(args.boundariesJson, "boundariesJson");
+				tags = parseJsonArray(args.tagsJson, "tagsJson", true);
+				tickers = args.tickersJson ? parseJsonArray(args.tickersJson, "tickersJson") : void 0;
+				related = args.relatedJson ? parseJsonArray(args.relatedJson, "relatedJson") : void 0;
+			} catch (err) {
+				return `[knowledge_ingest] 参数解析失败: ${err.message}`;
+			}
+			const cardInput = {
+				title: typeof args.title === "string" ? args.title : "",
+				summary: typeof args.summary === "string" ? args.summary : "",
+				source: {
+					type: args.sourceType || "manual",
+					url: typeof args.sourceUrl === "string" ? args.sourceUrl : "",
+					author: typeof args.sourceAuthor === "string" ? args.sourceAuthor : "",
+					publishedAt: typeof args.publishedAt === "string" ? args.publishedAt : void 0
+				},
+				credibility: args.credibility || "high",
+				coreClaims,
+				factCheck: {
+					verified: Array.isArray(factCheck.verified) ? factCheck.verified.map(String) : [],
+					discrepancies: Array.isArray(factCheck.discrepancies) ? factCheck.discrepancies.map(String) : [],
+					unverifiable: Array.isArray(factCheck.unverifiable) ? factCheck.unverifiable.map(String) : []
+				},
+				takeaways,
+				boundaries,
+				tags,
+				tickers,
+				related
+			};
+			const existingList = await store.list();
+			const existingByUrl = await store.getByUrl(cardInput.source.url);
+			const inputToValidate = {
+				...cardInput,
+				id: existingByUrl?.id,
+				createdAt: existingByUrl?.createdAt
+			};
+			const validation = validateKnowledgeCard(inputToValidate, existingList);
+			if (!validation.ok || !validation.card) return `[knowledge_ingest] 知识卡片校验失败: ${validation.error ?? "未知校验错误"}`;
+			const card = validation.card;
+			await store.save(card);
+			onWritten?.(card);
+			return `[knowledge_ingest] ${!!existingByUrl ? "成功更新已有知识卡片" : "成功创建新知识卡片"} [${card.id}] "${card.title}" (标签: ${card.tags.join(", ")}${card.related?.length ? `, 关联: ${card.related.join(", ")}` : ""})`;
+		}
+	});
+}
+function createKnowledgeSearchTool(store) {
+	return defineTool({
+		name: "knowledge_search",
+		description: "检索本地知识库中的知识卡片。有关键词时按字段命中相关度排序（标签 > 标题 > 核心论点 > 摘要/作者），无关键词时按更新时间倒序；支持按主体（cluster，配合 knowledge_graph 两级检索）、作者、来源类型、可信度多维过滤。detail=\"full\" 时同时返回核心论点、事实核查与可复用经验全文（上限 20 张）。",
+		parameters: {
+			query: {
+				type: "string",
+				description: "搜索关键词（在标题、摘要、核心论点、标签中模糊匹配）"
+			},
+			tags: {
+				type: "string",
+				description: "逗号分隔的标签过滤（例如 \"宏观,高股息\"，匹配其中任意一个）"
+			},
+			cluster: {
+				type: "string",
+				description: "按主体精确过滤（主体 = 图谱聚类键 = 卡片首个标签）。两级检索第二级：先 knowledge_graph 看主体分布，再用本参数钻取该主体下的卡片"
+			},
+			author: {
+				type: "string",
+				description: "按作者/UP主/公众号过滤（子串匹配）"
+			},
+			sourceType: {
+				type: "string",
+				description: "按来源类型过滤：\"bilibili\" | \"wechat\" | \"manual\""
+			},
+			credibility: {
+				type: "string",
+				description: "按可信度过滤：\"high\" | \"medium\" | \"low\""
+			},
+			limit: {
+				type: "number",
+				description: "最大返回数量（默认 20）",
+				default: 20
+			},
+			detail: {
+				type: "string",
+				description: "返回详略：\"summary\"（默认，摘要级）| \"full\"（附核心论点/事实核查/经验/边界全文）",
+				default: "summary"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: String(value)
+			}]
+		},
+		async execute(raw) {
+			const params = raw ?? {};
+			const allCards = await store.list();
+			const queryLower = typeof params.query === "string" ? params.query.trim().toLowerCase() : "";
+			const authorLower = typeof params.author === "string" ? params.author.trim().toLowerCase() : "";
+			const rawTags = typeof params.tags === "string" ? params.tags.split(",").map((t) => t.trim().toLowerCase()).filter(Boolean) : [];
+			const targetCluster = typeof params.cluster === "string" ? params.cluster.trim().toLowerCase() : "";
+			const targetSourceType = typeof params.sourceType === "string" ? params.sourceType.trim() : void 0;
+			const targetCredibility = typeof params.credibility === "string" ? params.credibility.trim() : void 0;
+			const limit = typeof params.limit === "number" && Number.isFinite(params.limit) ? Math.max(1, Math.min(params.limit, 100)) : 20;
+			const detail = params.detail === "full" ? "full" : "summary";
+			const effectiveLimit = detail === "full" ? Math.min(limit, 20) : limit;
+			const matched = allCards.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 (authorLower && !card.source.author.toLowerCase().includes(authorLower)) return false;
+				if (rawTags.length > 0) {
+					const cardTagsLower = card.tags.map((t) => t.toLowerCase());
+					if (!rawTags.some((t) => cardTagsLower.includes(t))) return false;
+				}
+				if (queryLower) {
+					const titleMatch = card.title.toLowerCase().includes(queryLower);
+					const summaryMatch = card.summary.toLowerCase().includes(queryLower);
+					const claimsMatch = card.coreClaims.some((c) => c.toLowerCase().includes(queryLower));
+					const tagsMatch = card.tags.some((t) => t.toLowerCase().includes(queryLower));
+					const authorMatch = card.source.author.toLowerCase().includes(queryLower);
+					if (!titleMatch && !summaryMatch && !claimsMatch && !tagsMatch && !authorMatch) return false;
+				}
+				return true;
+			});
+			const scored = matched.map((card) => {
+				let score = 0;
+				if (queryLower) {
+					if (card.tags.some((t) => t.toLowerCase().includes(queryLower))) score += 4;
+					if (card.title.toLowerCase().includes(queryLower)) score += 3;
+					if (card.coreClaims.some((c) => c.toLowerCase().includes(queryLower))) score += 2;
+					if (card.summary.toLowerCase().includes(queryLower)) score += 1;
+					if (card.source.author.toLowerCase().includes(queryLower)) score += 1;
+				}
+				return {
+					card,
+					score
+				};
+			});
+			scored.sort((a, b) => b.score - a.score || new Date(b.card.updatedAt).getTime() - new Date(a.card.updatedAt).getTime());
+			const results = scored.slice(0, effectiveLimit).map((s) => s.card);
+			const lines = [`[knowledge_search] 匹配到 ${matched.length} 张卡片 (展示前 ${results.length} 项${detail === "full" ? ", detail=full" : ""}):`];
+			for (const card of results) {
+				lines.push(`- [${card.id}] "${card.title}" (${card.source.type} @ ${card.source.author}, 可信度: ${card.credibility})`);
+				lines.push(`  摘要: ${card.summary}`);
+				lines.push(`  标签: ${card.tags.join(", ")} | 链接: ${card.source.url}`);
+				if (detail === "full") lines.push(...renderCardFullLines(card));
+			}
+			if (results.length === 0) lines.push("（未搜索到符合条件的知识卡片）");
+			return lines.join("\n");
+		}
+	});
+}
+function createKnowledgeGetTool(store) {
+	return defineTool({
+		name: "knowledge_get",
+		description: "按 id 读取单张知识卡片的完整内容（核心论点、事实核查三桶、可复用经验、适用边界）。id 可来自 knowledge_search 结果或历史分析中的引用标注。",
+		parameters: { id: {
+			type: "string",
+			required: true,
+			description: "知识卡片 id（kc_...）"
+		} },
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: String(value)
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const id = typeof args.id === "string" ? args.id.trim() : "";
+			if (!id) return "[knowledge_get] 参数 id 为必填字符串";
+			const card = await store.get(id);
+			if (!card) return `[knowledge_get] 未找到卡片 [${id}]`;
+			const lines = [
+				`[knowledge_get] [${card.id}] "${card.title}"`,
+				`  摘要: ${card.summary}`,
+				`  来源: ${card.source.type} @ ${card.source.author}${card.source.publishedAt ? ` (${card.source.publishedAt})` : ""} | 可信度: ${card.credibility} | 更新: ${card.updatedAt}`,
+				`  标签: ${card.tags.join(", ")} | 链接: ${card.source.url}`,
+				...renderCardFullLines(card)
+			];
+			if (card.related && card.related.length > 0) lines.push(`  显式关联: ${card.related.join(", ")}`);
+			return lines.join("\n");
+		}
+	});
+}
+function createKnowledgeDeleteTool(store, options = {}) {
+	const { onWritten } = options;
+	return defineTool({
+		name: "knowledge_delete",
+		description: "从本地知识库删除（下架）指定知识卡片。用于知识点/经验被事实证伪、来源撤稿或卡片重复等场景。删除时自动清理其他卡片指向本卡片的 related 引用，并在输出中回显被删卡片的标题与核心论点留痕；证伪结论本身应另行记入交易日志或对话沉淀。",
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "要删除的知识卡片 id（kc_...）。不确定 id 时先用 knowledge_search 查询确认，不要凭模糊记忆删除。"
+			},
+			reason: {
+				type: "string",
+				description: "删除原因（如「核心论点被 XX 数据证伪」「来源撤稿」），回显在结果中供留痕"
+			}
+		},
+		output: {
+			schema: { type: "string" },
+			render: (_args, value) => [{
+				type: "text",
+				text: String(value)
+			}]
+		},
+		async execute(raw) {
+			const args = raw ?? {};
+			const id = typeof args.id === "string" ? args.id.trim() : "";
+			const reason = typeof args.reason === "string" ? args.reason.trim() : "";
+			if (!id) return "[knowledge_delete] 参数 id 为必填字符串";
+			const target = await store.get(id);
+			if (!target) return `[knowledge_delete] 未找到卡片 [${id}]，请先用 knowledge_search 确认卡片 id`;
+			const referencing = [];
+			for (const card of await store.list()) if (card.related && card.related.includes(id)) {
+				const remaining = card.related.filter((r) => r !== id);
+				referencing.push(card.id);
+				await store.save({
+					...card,
+					related: remaining.length > 0 ? remaining : void 0,
+					updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+				});
+			}
+			if (!await store.delete(id)) return `[knowledge_delete] 删除失败：卡片 [${id}] 在删除时已不存在`;
+			onWritten?.();
+			const lines = [`[knowledge_delete] 已删除卡片 [${target.id}] "${target.title}"`, `  核心论点（留痕回显）: ${target.coreClaims.join("；")}`];
+			if (reason) lines.push(`  删除原因: ${reason}`);
+			lines.push(referencing.length > 0 ? `  已清理 ${referencing.length} 张卡片的 related 引用: ${referencing.join(", ")}` : "  无其他卡片引用本卡片");
+			return lines.join("\n");
+		}
+	});
+}
+//#endregion
+export { createFileKnowledgeCardStore, createKnowledgeDeleteTool, createKnowledgeGetTool, createKnowledgeIngestTool, createKnowledgeSearchTool };

package/lib/types.d.ts

@@ -0,0 +1,79 @@
+//#region src/types.d.ts
+/**
+ * 知识库核心契约类型（对齐 docs/design/knowledge-graph.md §2）。
+ */
+type KnowledgeSourceType = 'bilibili' | 'wechat' | 'manual';
+type KnowledgeCredibility = 'high' | 'medium' | 'low';
+interface KnowledgeFactCheck {
+  readonly verified: readonly string[];
+  readonly discrepancies: readonly string[];
+  readonly unverifiable: readonly string[];
+}
+interface KnowledgeSource {
+  readonly type: KnowledgeSourceType;
+  readonly url: string;
+  readonly author: string;
+  readonly publishedAt?: string;
+}
+interface KnowledgeCard {
+  readonly id: string;
+  readonly title: string;
+  readonly summary: string;
+  readonly source: KnowledgeSource;
+  readonly credibility: KnowledgeCredibility;
+  readonly coreClaims: readonly string[];
+  readonly factCheck: KnowledgeFactCheck;
+  readonly takeaways: readonly string[];
+  readonly boundaries: readonly string[];
+  readonly tags: readonly string[];
+  readonly tickers?: readonly string[];
+  readonly related?: readonly string[];
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}
+type KnowledgeCardInput = Omit<KnowledgeCard, 'id' | 'createdAt' | 'updatedAt'> & {
+  readonly id?: string;
+  readonly createdAt?: string;
+  readonly updatedAt?: string;
+};
+type GraphLinkKind = 'related' | 'co-tag' | 'co-author' | 'tag-hub';
+interface KnowledgeGraphNode {
+  readonly id: string;
+  readonly label: string;
+  readonly cluster: string;
+  readonly credibility: KnowledgeCredibility;
+  readonly degree: number;
+  /** 节点类别：'card' = 知识卡片（默认，向后兼容），'tag' = 标签 hub 节点（Obsidian 式）。 */
+  readonly type?: 'card' | 'tag';
+  readonly raw?: KnowledgeCard;
+}
+interface KnowledgeGraphLink {
+  readonly source: string;
+  readonly target: string;
+  readonly kind: GraphLinkKind;
+  readonly weight: number;
+}
+interface KnowledgeGraphData {
+  readonly nodes: readonly KnowledgeGraphNode[];
+  readonly links: readonly KnowledgeGraphLink[];
+}
+interface BuildGraphOptions {
+  readonly coTag?: boolean;
+  readonly coAuthor?: boolean;
+  /**
+   * Obsidian 式标签 hub 模式（2026-09-01 起 UI 默认开启）：标签聚合为独立 hub 节点，
+   * 卡片仅与自己的标签建边（kind='tag-hub'）+ 显式 related 建边；关闭 co-tag/co-author
+   * 全配对边。大规模单作者/单标签库下全配对是 O(n²) 边爆炸（215 卡 ≈ 2 万+边），
+   * 力导模拟发散、画布糊成一团——hub 模式把边数降为 O(卡片数 × 平均标签数)。
+   */
+  readonly tagHubs?: boolean;
+}
+interface KnowledgeCardStore {
+  list(): Promise<readonly KnowledgeCard[]>;
+  get(id: string): Promise<KnowledgeCard | undefined>;
+  getByUrl(url: string): Promise<KnowledgeCard | undefined>;
+  save(card: KnowledgeCard): Promise<void>;
+  delete(id: string): Promise<boolean>;
+}
+//#endregion
+export { BuildGraphOptions, GraphLinkKind, KnowledgeCard, KnowledgeCardInput, KnowledgeCardStore, KnowledgeCredibility, KnowledgeFactCheck, KnowledgeGraphData, KnowledgeGraphLink, KnowledgeGraphNode, KnowledgeSource, KnowledgeSourceType };

package/lib/validate.d.ts

@@ -0,0 +1,11 @@
+import { KnowledgeCard, KnowledgeCardInput } from "./types.js";
+//#region src/validate.d.ts
+interface ValidationResult {
+  ok: boolean;
+  card?: KnowledgeCard;
+  error?: string;
+}
+declare function generateCardId(): string;
+declare function validateKnowledgeCard(input: KnowledgeCardInput, existingCards?: readonly KnowledgeCard[]): ValidationResult;
+//#endregion
+export { ValidationResult, generateCardId, validateKnowledgeCard };

package/lib/validate.js

@@ -0,0 +1,127 @@
+//#region src/validate.ts
+const ALLOWED_CREDIBILITY = /* @__PURE__ */ new Set([
+	"high",
+	"medium",
+	"low"
+]);
+const ALLOWED_SOURCE_TYPES = /* @__PURE__ */ new Set([
+	"bilibili",
+	"wechat",
+	"manual"
+]);
+function isValidSourceUrl(url, type) {
+	if (!url || typeof url !== "string") return false;
+	const trimmed = url.trim();
+	if (type === "manual") return trimmed === "manual" || trimmed.startsWith("manual:") || trimmed.startsWith("http://") || trimmed.startsWith("https://");
+	if (type === "bilibili") return trimmed.includes("bilibili.com") || trimmed.includes("b23.tv") || trimmed.startsWith("BV");
+	if (type === "wechat") return trimmed.includes("mp.weixin.qq.com") || trimmed.includes("weixin.qq.com");
+	return true;
+}
+function generateCardId() {
+	return `kc_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`;
+}
+function validateKnowledgeCard(input, existingCards = []) {
+	if (!input || typeof input !== "object") return {
+		ok: false,
+		error: "输入卡片数据必须是非空对象"
+	};
+	if (!input.title || typeof input.title !== "string" || input.title.trim().length === 0) return {
+		ok: false,
+		error: "卡片标题 (title) 为必填字段且不能为空"
+	};
+	if (!input.summary || typeof input.summary !== "string" || input.summary.trim().length === 0) return {
+		ok: false,
+		error: "卡片概述 (summary) 为必填字段且不能为空"
+	};
+	if (!input.source || typeof input.source !== "object") return {
+		ok: false,
+		error: "卡片来源 (source) 为必填对象"
+	};
+	const { type, url, author } = input.source;
+	if (!type || !ALLOWED_SOURCE_TYPES.has(type)) return {
+		ok: false,
+		error: `来源类型 (source.type) 非法，允许值为: ${Array.from(ALLOWED_SOURCE_TYPES).join(", ")}`
+	};
+	if (!url || typeof url !== "string" || url.trim().length === 0) return {
+		ok: false,
+		error: "来源链接 (source.url) 为必填字段且不能为空"
+	};
+	if (!isValidSourceUrl(url, type)) return {
+		ok: false,
+		error: `来源链接 (source.url) 与来源类型 (${type}) 不匹配或不符合白名单规范`
+	};
+	if (!author || typeof author !== "string" || author.trim().length === 0) return {
+		ok: false,
+		error: "来源作者/UP主/公众号 (source.author) 为必填字段"
+	};
+	if (!input.credibility || !ALLOWED_CREDIBILITY.has(input.credibility)) return {
+		ok: false,
+		error: `内容可信度 (credibility) 非法，允许值为: ${Array.from(ALLOWED_CREDIBILITY).join(", ")}`
+	};
+	if (!Array.isArray(input.coreClaims) || input.coreClaims.length === 0) return {
+		ok: false,
+		error: "核心论点 (coreClaims) 必须是非空字符串数组"
+	};
+	if (!input.factCheck || typeof input.factCheck !== "object") return {
+		ok: false,
+		error: "事实核查三桶 (factCheck) 为必填对象，包含 verified, discrepancies, unverifiable"
+	};
+	const { verified = [], discrepancies = [], unverifiable = [] } = input.factCheck;
+	if (!Array.isArray(verified) || !Array.isArray(discrepancies) || !Array.isArray(unverifiable)) return {
+		ok: false,
+		error: "事实核查分类项 (verified / discrepancies / unverifiable) 必须为数组"
+	};
+	if (!Array.isArray(input.takeaways)) return {
+		ok: false,
+		error: "可复用经验 (takeaways) 必须为字符串数组"
+	};
+	if (!Array.isArray(input.boundaries)) return {
+		ok: false,
+		error: "适用边界与避坑 (boundaries) 必须为字符串数组"
+	};
+	if (!Array.isArray(input.tags) || input.tags.length === 0) return {
+		ok: false,
+		error: "主题关键词标签 (tags) 必须包含至少一个标签"
+	};
+	if (input.related && Array.isArray(input.related) && input.related.length > 0) {
+		const existingIds = new Set(existingCards.map((c) => c.id));
+		for (const relId of input.related) if (!existingIds.has(relId)) return {
+			ok: false,
+			error: `显式关联卡片 id [${relId}] 在知识库中不存在（拒绝悬空关联）`
+		};
+	}
+	const now = (/* @__PURE__ */ new Date()).toISOString();
+	const id = input.id && input.id.startsWith("kc_") ? input.id : generateCardId();
+	const createdAt = input.createdAt || now;
+	const updatedAt = now;
+	return {
+		ok: true,
+		card: {
+			id,
+			title: input.title.trim(),
+			summary: input.summary.trim(),
+			source: {
+				type: input.source.type,
+				url: input.source.url.trim(),
+				author: input.source.author.trim(),
+				publishedAt: input.source.publishedAt
+			},
+			credibility: input.credibility,
+			coreClaims: input.coreClaims.map((c) => String(c).trim()).filter(Boolean),
+			factCheck: {
+				verified: verified.map((c) => String(c).trim()).filter(Boolean),
+				discrepancies: discrepancies.map((c) => String(c).trim()).filter(Boolean),
+				unverifiable: unverifiable.map((c) => String(c).trim()).filter(Boolean)
+			},
+			takeaways: input.takeaways.map((c) => String(c).trim()).filter(Boolean),
+			boundaries: input.boundaries.map((c) => String(c).trim()).filter(Boolean),
+			tags: input.tags.map((t) => String(t).trim()).filter(Boolean),
+			tickers: input.tickers ? input.tickers.map((t) => String(t).trim().toUpperCase()).filter(Boolean) : void 0,
+			related: input.related ? Array.from(new Set(input.related)) : void 0,
+			createdAt,
+			updatedAt
+		}
+	};
+}
+//#endregion
+export { generateCardId, validateKnowledgeCard };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "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.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "./lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./tool": {
+      "types": "./lib/tool.d.ts",
+      "default": "./lib/tool.js"
+    },
+    "./plugin": {
+      "types": "./lib/plugin.d.ts",
+      "default": "./lib/plugin.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "PolyForm-Noncommercial-1.0.0",
+  "dependencies": {
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsdown": "^0.22.0",
+    "typescript": "^5.9.0",
+    "vitest": "^3.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}