@dshtrading/knowledge 0.5.0 → 0.6.0

package/lib/knowledge-fs.js

@@ -1,16 +1,27 @@
 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);
@@ -24,16 +35,20 @@ function createFileKnowledgeCardStore(filePath) {
 				}
 				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() {
@@ -48,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, canonicalizeCardAuthor({ ...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/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: {
@@ -196,40 +196,40 @@ function createKnowledgeIngestTool(store, options = {}) {
 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"
 			}
 		},
@@ -302,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" },
@@ -337,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/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.5.0",
+  "version": "0.6.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -27,7 +27,7 @@
   "dependencies": {
     "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
     "@deepseek-ai/schemastery": "^3.18.4",
-    "@dshtrading/dsh-home": "^0.5.0"
+    "@dshtrading/dsh-home": "^0.6.0"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": ">=4.0.0"