@dshtrading/knowledge 0.4.1 → 0.6.0

package/lib/authors.d.ts

@@ -0,0 +1,13 @@
+import { KnowledgeCard } from "./types.js";
+//#region src/authors.d.ts
+declare const AUTHOR_ALIASES: Readonly<Record<string, string>>;
+/** 把作者名归一到规范名；未登记的写法原样返回（仅去除首尾空白）。 */
+declare function canonicalAuthor(author: string): string;
+/**
+ * 返回作者已归一的卡片副本；已是规范名时原样返回同一引用。
+ * 非破坏性：不修改传入卡片。缺 `source`/`author` 的畸形条目按原样放行——文件读取
+ * 层不为历史脏数据抛错，结构校验只在入库（`validateKnowledgeCard`）发生。
+ */
+declare function canonicalizeCardAuthor(card: KnowledgeCard): KnowledgeCard;
+//#endregion
+export { AUTHOR_ALIASES, canonicalAuthor, canonicalizeCardAuthor };

package/lib/authors.js

@@ -0,0 +1,35 @@
+//#region src/authors.ts
+const AUTHOR_ALIASES = Object.freeze({
+	"鳄鱼派": "鳄鱼派（像鳄鱼一样思考）",
+	"鳄鱼派（公众号：像鳄鱼一样思考）": "鳄鱼派（像鳄鱼一样思考）",
+	"像鳄鱼一样思考（鳄鱼派）": "鳄鱼派（像鳄鱼一样思考）",
+	"zcl × DSH Master（自有分析，非外部素材）": "zcl × DSH Master（自有分析）",
+	"zcl × DSH Master（自有框架综合，非外部素材）": "zcl × DSH Master（自有分析）",
+	"山基说（素材提炼）/ zcl（分层核查，事实依据 facts/oil.md、facts/fed.md）": "山基说",
+	"小鹿投研日记（转播大摩闭门会 9.14，发言人Robin/Steven/钟申/Jenny；Laura股票部分视频截断未录）": "小鹿投研日记",
+	"中金点睛（刘刚、杨萱庭）": "中金点睛"
+});
+/** 把作者名归一到规范名；未登记的写法原样返回（仅去除首尾空白）。 */
+function canonicalAuthor(author) {
+	const trimmed = author.trim();
+	return AUTHOR_ALIASES[trimmed] ?? trimmed;
+}
+/**
+* 返回作者已归一的卡片副本；已是规范名时原样返回同一引用。
+* 非破坏性：不修改传入卡片。缺 `source`/`author` 的畸形条目按原样放行——文件读取
+* 层不为历史脏数据抛错，结构校验只在入库（`validateKnowledgeCard`）发生。
+*/
+function canonicalizeCardAuthor(card) {
+	if (!card || typeof card !== "object" || !card.source || typeof card.source.author !== "string") return card;
+	const canonical = canonicalAuthor(card.source.author);
+	if (canonical === card.source.author) return card;
+	return {
+		...card,
+		source: {
+			...card.source,
+			author: canonical
+		}
+	};
+}
+//#endregion
+export { AUTHOR_ALIASES, canonicalAuthor, canonicalizeCardAuthor };

package/lib/index.d.ts

@@ -2,4 +2,5 @@ import { BuildGraphOptions, GraphLinkKind, KnowledgeCard, KnowledgeCardInput, Kn
 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 };
+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 };

package/lib/index.js

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

package/lib/knowledge-fs.js

@@ -1,32 +1,54 @@
+import { canonicalizeCardAuthor } from "./authors.js";
 import { readFile } from "node:fs/promises";
-import { writeJsonAtomic } from "@dshtrading/dsh-home";
+import { SKIP_WRITE, transactStore } from "@dshtrading/dsh-home";
 //#region src/knowledge-fs.ts
 /**
 * 文件持久化版知识卡片存储（Node.js 宿主端专用）。
 *
-* 采用 tmp + rename 原子写入模式，并包含明确的错误日志与异常处理（逐行对齐 custom-fs.ts 先例）。
+* 整表持久化经 `@dshtrading/dsh-home` 的 {@link transactStore}——跨进程排他锁 +
+* 锁内新鲜读盘 + 原子写（2026-10-09 多进程互相覆盖事故修复）。读取面作者归一与坏
+* 文件降级纪律不变（逐行对齐 custom-fs.ts 先例）。
 */
+const LOG_PREFIX = "[dsh-trading/knowledge] failed to atomic flush knowledge cards to";
 function createFileKnowledgeCardStore(filePath) {
 	let cache = null;
-	async function load() {
-		if (cache !== null) return cache;
+	/**
+	* 新鲜读盘（作者别名归一、坏 JSON 降级空表）；供 load 与锁内重读共用。
+	*
+	* 作者别名在读取时归一（authors.ts）：历史数据即刻在 GUI/检索层表现为规范名。
+	* 读本身不写盘，但归一结果留在缓存里，会被下一次写操作的全表回写落盘——
+	* 即一次静默迁移，故这里显式 log 一次，让「改别名表 = 改历史数据」可见。
+	* 缺 source / 缺 id 的脏行原样保留（不丢数据）；结构性校验只在入库发生，
+	* 但这类行仍会让 getByUrl/search/graph 的解引用抛错（既有边界，未在此收口）。
+	*/
+	async function readFromDisk() {
 		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);
+				let healed = 0;
+				for (const item of parsed) if (item && typeof item.id === "string") {
+					const card = canonicalizeCardAuthor(item);
+					if (card !== item) healed += 1;
+					map.set(item.id, card);
+				}
+				if (healed > 0) console.warn(`[dsh-trading/knowledge] 作者别名归一：读取时治愈 ${healed} 张历史卡片（${filePath}）；下一次写操作会把结果落盘`);
 			}
-			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;
+			return /* @__PURE__ */ new Map();
 		}
 	}
-	async function flush(map) {
-		await writeJsonAtomic(filePath, [...map.values()], "[dsh-trading/knowledge] failed to atomic flush knowledge cards to");
+	async function load() {
+		if (cache !== null) return cache;
+		cache = await readFromDisk();
+		return cache;
+	}
+	async function commit(mutate) {
+		cache = await transactStore(filePath, readFromDisk, mutate, (table) => [...table.values()], LOG_PREFIX);
+		return cache;
 	}
 	return {
 		async list() {
@@ -41,14 +63,17 @@ function createFileKnowledgeCardStore(filePath) {
 			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);
+			await commit((onDisk) => {
+				onDisk.set(card.id, canonicalizeCardAuthor({ ...card }));
+				return onDisk;
+			});
 		},
 		async delete(id) {
-			const map = await load();
-			const existed = map.delete(id);
-			if (existed) await flush(map);
+			let existed = false;
+			await commit((onDisk) => {
+				existed = onDisk.delete(id);
+				return existed ? onDisk : SKIP_WRITE;
+			});
 			return existed;
 		}
 	};

package/lib/store-memory.js

@@ -1,7 +1,8 @@
+import { canonicalizeCardAuthor } from "./authors.js";
 //#region src/store-memory.ts
 function createMemoryKnowledgeCardStore(initialCards = []) {
 	const map = /* @__PURE__ */ new Map();
-	for (const c of initialCards) map.set(c.id, { ...c });
+	for (const c of initialCards) map.set(c.id, canonicalizeCardAuthor({ ...c }));
 	return {
 		async list() {
 			return Array.from(map.values());
@@ -14,7 +15,7 @@ function createMemoryKnowledgeCardStore(initialCards = []) {
 			for (const card of map.values()) if (card.source.url.trim() === trimmed) return card;
 		},
 		async save(card) {
-			map.set(card.id, { ...card });
+			map.set(card.id, canonicalizeCardAuthor({ ...card }));
 		},
 		async delete(id) {
 			return map.delete(id);

package/lib/tool.js

@@ -30,72 +30,72 @@ function createKnowledgeIngestTool(store, options = {}) {
 	const { onWritten } = options;
 	return defineTool({
 		name: "knowledge_ingest",
-		description: "将经事实核查后的结构化知识卡片（Content Insight 产物）入库到本地知识库。支持自动 URL 查重（重复 URL 自动走更新且保持 ID 不变）及关联关系验证。",
+		description: "Ingest one fact-checked knowledge card (a Content Insight product) into the local knowledge base. Duplicate source URLs are detected automatically: an existing card with the same URL is updated in place and keeps its id. Related-card references are validated.",
 		parameters: {
 			title: {
 				type: "string",
 				required: true,
-				description: "知识卡片主题（例如「高股息策略在低利率环境下的防御逻辑」）"
+				description: "Card subject, e.g. the defensive logic of high-dividend strategies in a low-rate environment."
 			},
 			summary: {
 				type: "string",
 				required: true,
-				description: "2-4 条核心论点合并的一句话概述（图谱 hover 与快速导读展示）"
+				description: "One-sentence overview merging the 2-4 core claims; shown in the graph hover and quick read."
 			},
 			sourceType: {
 				type: "string",
 				required: true,
-				description: "素材来源类型：\"bilibili\"（B站）、\"wechat\"（微信公众号）、\"manual\"（手工录入）"
+				description: "Source kind: \"bilibili\" | \"wechat\" | \"manual\"."
 			},
 			sourceUrl: {
 				type: "string",
 				required: true,
-				description: "素材链接或去重标识（例如 B 站 BV 链接、公众号文章链接）"
+				description: "Source link or dedup key, e.g. a Bilibili BV link or a WeChat article link."
 			},
 			sourceAuthor: {
 				type: "string",
 				required: true,
-				description: "来源作者/UP主/公众号名称"
+				description: "Source author, channel or account name."
 			},
 			publishedAt: {
 				type: "string",
-				description: "素材发布日期（ISO 格式如 2026-08-30，可选）"
+				description: "Optional source publish date, ISO format such as 2026-08-30."
 			},
 			credibility: {
 				type: "string",
 				required: true,
-				description: "依据事实核查整体定级：\"high\"（事实严密证据充分）、\"medium\"（观点可取但部分有出入）、\"low\"（存在重大未核实或明显漏洞）"
+				description: "Overall fact-check grade: \"high\" | \"medium\" | \"low\"."
 			},
 			coreClaimsJson: {
 				type: "string",
 				required: true,
-				description: "JSON 字符串数组，核心论点列表（保留原作者推理链条），例如 '[\"论点1\", \"论点2\"]'"
+				description: "JSON string array of core claims, preserving the author's reasoning chain, e.g. '[\"claim1\", \"claim2\"]'."
 			},
 			factCheckJson: {
 				type: "string",
 				required: true,
-				description: "JSON 对象，事实核查三档分类，例如 '{\"verified\":[\"证实1\"],\"discrepancies\":[\"出入1\"],\"unverifiable\":[]}'"
+				description: "JSON object with the three fact-check buckets, e.g. '{\"verified\":[\"...\"],\"discrepancies\":[\"...\"],\"unverifiable\":[]}'."
 			},
 			takeawaysJson: {
 				type: "string",
-				description: "可选 JSON 字符串数组，可复用的分析框架与经验总结，例如 '[\"经验1\"]'"
+				description: "Optional JSON string array of reusable analysis frameworks and lessons."
 			},
 			boundariesJson: {
 				type: "string",
-				description: "可选 JSON 字符串数组，适用边界、失效情景与避坑指南，例如 '[\"边界1\"]'"
+				description: "Optional JSON string array of applicability boundaries, invalidation cases and pitfalls."
 			},
 			tagsJson: {
 				type: "string",
 				required: true,
-				description: "JSON 字符串数组，受控主题标签列表，例如 '[\"宏观\", \"高股息\", \"红利策略\"]'"
+				description: "JSON string array of controlled topic tags, e.g. '[\"宏观\", \"高股息\", \"红利策略\"]'."
 			},
 			tickersJson: {
 				type: "string",
-				description: "可选 JSON 字符串数组，关联标的代码列表，例如 '[\"BTCUSDT\", \"600519.SH\"]'"
+				description: "Optional JSON string array of related instrument codes, e.g. '[\"BTCUSDT\", \"600519.SH\"]'."
 			},
 			relatedJson: {
 				type: "string",
-				description: "可选 JSON 字符串数组，显式关联的其他已入库卡片 ID 列表，例如 '[\"kc_01j...\", \"kc_01k...\"]'"
+				description: "Optional JSON string array of related card ids already in the library, e.g. '[\"kc_01j...\", \"kc_01k...\"]'."
 			}
 		},
 		output: {
@@ -186,47 +186,50 @@ function createKnowledgeIngestTool(store, options = {}) {
 			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(", ")}` : ""})`;
+			const actionDesc = !!existingByUrl ? "成功更新已有知识卡片" : "成功创建新知识卡片";
+			const requestedAuthor = typeof args.sourceAuthor === "string" ? args.sourceAuthor.trim() : "";
+			const authorNote = requestedAuthor !== "" && requestedAuthor !== card.source.author ? `（作者已归一：${requestedAuthor} → ${card.source.author}）` : "";
+			return `[knowledge_ingest] ${actionDesc} [${card.id}] "${card.title}"${authorNote} (标签: ${card.tags.join(", ")}${card.related?.length ? `, 关联: ${card.related.join(", ")}` : ""})`;
 		}
 	});
 }
 function createKnowledgeSearchTool(store) {
 	return defineTool({
 		name: "knowledge_search",
-		description: "检索本地知识库中的知识卡片。有关键词时按字段命中相关度排序（标签 > 标题 > 核心论点 > 摘要/作者），无关键词时按更新时间倒序；支持按主体（cluster，配合 knowledge_graph 两级检索）、作者、来源类型、可信度多维过滤。detail=\"full\" 时同时返回核心论点、事实核查与可复用经验全文（上限 20 张）。",
+		description: "Search knowledge cards in the local library. With a keyword the results rank by field hit weight (tags > title > core claims > summary/author); without one they come newest-updated first. Filters: cluster (the graph clustering key, pair with knowledge_graph for two-stage retrieval), author, source kind and credibility. detail=\"full\" also returns core claims, the fact-check buckets and reusable lessons (capped at 20 cards).",
 		parameters: {
 			query: {
 				type: "string",
-				description: "搜索关键词（在标题、摘要、核心论点、标签中模糊匹配）"
+				description: "Search keyword, fuzzy-matched against title, summary, core claims and tags."
 			},
 			tags: {
 				type: "string",
-				description: "逗号分隔的标签过滤（例如 \"宏观,高股息\"，匹配其中任意一个）"
+				description: "Comma-separated tag filter, e.g. \"宏观,高股息\"; matches any one of them."
 			},
 			cluster: {
 				type: "string",
-				description: "按主体精确过滤（主体 = 图谱聚类键 = 卡片首个标签）。两级检索第二级：先 knowledge_graph 看主体分布，再用本参数钻取该主体下的卡片"
+				description: "Exact subject filter (subject = graph clustering key = the card first tag). Second stage of a two-stage retrieval: call knowledge_graph for the subject distribution, then drill in here."
 			},
 			author: {
 				type: "string",
-				description: "按作者/UP主/公众号过滤（子串匹配）"
+				description: "Author/channel filter (substring match)."
 			},
 			sourceType: {
 				type: "string",
-				description: "按来源类型过滤：\"bilibili\" | \"wechat\" | \"manual\""
+				description: "Source kind filter: \"bilibili\" | \"wechat\" | \"manual\"."
 			},
 			credibility: {
 				type: "string",
-				description: "按可信度过滤：\"high\" | \"medium\" | \"low\""
+				description: "Credibility filter: \"high\" | \"medium\" | \"low\"."
 			},
 			limit: {
 				type: "number",
-				description: "最大返回数量（默认 20）",
+				description: "Maximum results to return (default 20).",
 				default: 20
 			},
 			detail: {
 				type: "string",
-				description: "返回详略：\"summary\"（默认，摘要级）| \"full\"（附核心论点/事实核查/经验/边界全文）",
+				description: "Detail level: \"summary\" (default) | \"full\" (adds core claims, fact check, lessons and boundaries).",
 				default: "summary"
 			}
 		},
@@ -299,11 +302,11 @@ function createKnowledgeSearchTool(store) {
 function createKnowledgeGetTool(store) {
 	return defineTool({
 		name: "knowledge_get",
-		description: "按 id 读取单张知识卡片的完整内容（核心论点、事实核查三桶、可复用经验、适用边界）。id 可来自 knowledge_search 结果或历史分析中的引用标注。",
+		description: "Read one knowledge card in full by id: core claims, the three fact-check buckets, reusable lessons and applicability boundaries. Ids come from knowledge_search results or citation markers in earlier analyses.",
 		parameters: { id: {
 			type: "string",
 			required: true,
-			description: "知识卡片 id（kc_...）"
+			description: "Knowledge card id (kc_...)."
 		} },
 		output: {
 			schema: { type: "string" },
@@ -334,16 +337,16 @@ function createKnowledgeDeleteTool(store, options = {}) {
 	const { onWritten } = options;
 	return defineTool({
 		name: "knowledge_delete",
-		description: "从本地知识库删除（下架）指定知识卡片。用于知识点/经验被事实证伪、来源撤稿或卡片重复等场景。删除时自动清理其他卡片指向本卡片的 related 引用，并在输出中回显被删卡片的标题与核心论点留痕；证伪结论本身应另行记入交易日志或对话沉淀。",
+		description: "Delete (retire) one knowledge card from the local library, for a claim disproved by evidence, a retracted source or a duplicate card. Other cards' related references to it are cleaned up automatically, and the deleted title and core claims are echoed as a trail. Record the disproof itself separately in the trading journal or the conversation.",
 		parameters: {
 			id: {
 				type: "string",
 				required: true,
-				description: "要删除的知识卡片 id（kc_...）。不确定 id 时先用 knowledge_search 查询确认，不要凭模糊记忆删除。"
+				description: "Knowledge card id to delete (kc_...). Confirm the id with knowledge_search first; never delete from vague memory."
 			},
 			reason: {
 				type: "string",
-				description: "删除原因（如「核心论点被 XX 数据证伪」「来源撤稿」），回显在结果中供留痕"
+				description: "Deletion reason, echoed in the result as a trail."
 			}
 		},
 		output: {

package/lib/validate.js

@@ -1,3 +1,4 @@
+import { canonicalAuthor } from "./authors.js";
 //#region src/validate.ts
 const ALLOWED_CREDIBILITY = /* @__PURE__ */ new Set([
 	"high",
@@ -103,7 +104,7 @@ function validateKnowledgeCard(input, existingCards = []) {
 			source: {
 				type: input.source.type,
 				url: input.source.url.trim(),
-				author: input.source.author.trim(),
+				author: canonicalAuthor(input.source.author),
 				publishedAt: input.source.publishedAt
 			},
 			credibility: input.credibility,

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.4.1",
+  "version": "0.6.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -25,9 +25,9 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@deepseek-ai/dsh-tools": "0.1.5-rc.1",
-    "@deepseek-ai/schemastery": "^3.18.2",
-    "@dshtrading/dsh-home": "^0.4.1"
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.4",
+    "@dshtrading/dsh-home": "^0.6.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0"