@dshtrading/knowledge 0.6.1 → 0.6.3

package/lib/knowledge-fs.js

@@ -1,19 +1,19 @@
 import { canonicalizeCardAuthor } from "./authors.js";
-import { readFile } from "node:fs/promises";
-import { SKIP_WRITE, transactStore } from "@dshtrading/dsh-home";
+import { SKIP_WRITE, createRecordStoreAdapter, readStoreText } from "@dshtrading/dsh-home";
 //#region src/knowledge-fs.ts
 /**
 * 文件持久化版知识卡片存储（Node.js 宿主端专用）。
 *
-* 整表持久化经 `@dshtrading/dsh-home` 的 {@link transactStore}——跨进程排他锁 +
-* 锁内新鲜读盘 + 原子写（2026-10-09 多进程互相覆盖事故修复）。读取面作者归一与坏
-* 文件降级纪律不变（逐行对齐 custom-fs.ts 先例）。
+* 读写骨架经 `@dshtrading/dsh-home` 的 {@link createRecordStoreAdapter}——跨进程排他锁 +
+* 锁内新鲜读盘 + 原子写 + 落盘成功后才发布缓存（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;
+	/** 读盘/解析失败的日志前缀（坏 JSON 与非 ENOENT 读失败同一条，与既有 load 口径逐字一致）。 */
+	const READ_FAILED = `[dsh-trading/knowledge] failed to read knowledge cards from ${filePath}:`;
 	/**
-	* 新鲜读盘（作者别名归一、坏 JSON 降级空表）；供 load 与锁内重读共用。
+	* 文本 → 卡片表（作者别名归一、坏 JSON 降级空表）。
 	*
 	* 作者别名在读取时归一（authors.ts）：历史数据即刻在 GUI/检索层表现为规范名。
 	* 读本身不写盘，但归一结果留在缓存里，会被下一次写操作的全表回写落盘——
@@ -21,10 +21,10 @@ function createFileKnowledgeCardStore(filePath) {
 	* 缺 source / 缺 id 的脏行原样保留（不丢数据）；结构性校验只在入库发生，
 	* 但这类行仍会让 getByUrl/search/graph 的解引用抛错（既有边界，未在此收口）。
 	*/
-	async function readFromDisk() {
+	function decode(text) {
+		if (text === void 0) return /* @__PURE__ */ new Map();
 		try {
-			const content = await readFile(filePath, "utf8");
-			const parsed = JSON.parse(content);
+			const parsed = JSON.parse(text);
 			const map = /* @__PURE__ */ new Map();
 			if (Array.isArray(parsed)) {
 				let healed = 0;
@@ -37,40 +37,45 @@ function createFileKnowledgeCardStore(filePath) {
 			}
 			return map;
 		} catch (err) {
-			if (err?.code !== "ENOENT") console.error(`[dsh-trading/knowledge] failed to read knowledge cards from ${filePath}:`, err);
+			console.error(READ_FAILED, err);
 			return /* @__PURE__ */ new Map();
 		}
 	}
-	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;
-	}
+	const store = createRecordStoreAdapter({
+		filePath,
+		logPrefix: LOG_PREFIX,
+		readFromDisk: () => readStoreText(filePath, READ_FAILED),
+		decode,
+		encode: (table) => [...table.values()]
+	});
 	return {
 		async list() {
-			return [...(await load()).values()];
+			return [...(await store.load()).values()];
 		},
 		async get(id) {
-			return (await load()).get(id);
+			return (await store.load()).get(id);
 		},
 		async getByUrl(url) {
-			const map = await load();
+			const map = await store.load();
 			const trimmed = url.trim();
 			for (const card of map.values()) if (card.source.url.trim() === trimmed) return card;
 		},
 		async save(card) {
-			await commit((onDisk) => {
+			await store.commit((onDisk) => {
 				onDisk.set(card.id, canonicalizeCardAuthor({ ...card }));
 				return onDisk;
 			});
 		},
+		async saveMany(cards) {
+			if (cards.length === 0) return;
+			await store.commit((onDisk) => {
+				for (const card of cards) onDisk.set(card.id, canonicalizeCardAuthor({ ...card }));
+				return onDisk;
+			});
+		},
 		async delete(id) {
 			let existed = false;
-			await commit((onDisk) => {
+			await store.commit((onDisk) => {
 				existed = onDisk.delete(id);
 				return existed ? onDisk : SKIP_WRITE;
 			});

package/lib/store-memory.js

@@ -17,6 +17,9 @@ function createMemoryKnowledgeCardStore(initialCards = []) {
 		async save(card) {
 			map.set(card.id, canonicalizeCardAuthor({ ...card }));
 		},
+		async saveMany(cards) {
+			for (const card of cards) map.set(card.id, canonicalizeCardAuthor({ ...card }));
+		},
 		async delete(id) {
 			return map.delete(id);
 		}

package/lib/tool.js

@@ -26,6 +26,19 @@ function renderCardFullLines(card) {
 	if (card.tickers && card.tickers.length > 0) lines.push(`  关联标的: ${card.tickers.join(", ")}`);
 	return lines;
 }
+/** 时间字段的可读回显：空值/缺省一律写「未知」，不留空位冒充有日期。 */
+function shownTimestamp(value) {
+	return value !== void 0 && value.trim().length > 0 ? value : "未知";
+}
+/** 解析显式时效筛选的 ISO 日期：空值表示不筛，非法值抛错由工具回显而不是静默当无命中。 */
+function parseCutoff(value, field) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	if (trimmed.length === 0) return void 0;
+	const ms = Date.parse(trimmed);
+	if (Number.isNaN(ms)) throw new Error(`[knowledge_search] 参数 ${field} 不是合法日期: ${trimmed}`);
+	return ms;
+}
 function createKnowledgeIngestTool(store, options = {}) {
 	const { onWritten } = options;
 	return defineTool({
@@ -67,35 +80,35 @@ function createKnowledgeIngestTool(store, options = {}) {
 				description: "Overall fact-check grade: \"high\" | \"medium\" | \"low\"."
 			},
 			coreClaimsJson: {
-				type: "string",
+				type: "json",
 				required: true,
-				description: "JSON string array of core claims, preserving the author's reasoning chain, e.g. '[\"claim1\", \"claim2\"]'."
+				description: "JSON array of core claims (also accepted as a JSON string), preserving the author's reasoning chain, e.g. '[\"claim1\", \"claim2\"]'."
 			},
 			factCheckJson: {
-				type: "string",
+				type: "json",
 				required: true,
-				description: "JSON object with the three fact-check buckets, e.g. '{\"verified\":[\"...\"],\"discrepancies\":[\"...\"],\"unverifiable\":[]}'."
+				description: "JSON object with the three fact-check buckets (also accepted as a JSON string), e.g. '{\"verified\":[\"...\"],\"discrepancies\":[\"...\"],\"unverifiable\":[]}'."
 			},
 			takeawaysJson: {
-				type: "string",
-				description: "Optional JSON string array of reusable analysis frameworks and lessons."
+				type: "json",
+				description: "Optional JSON array of reusable analysis frameworks and lessons (also accepted as a JSON string)."
 			},
 			boundariesJson: {
-				type: "string",
-				description: "Optional JSON string array of applicability boundaries, invalidation cases and pitfalls."
+				type: "json",
+				description: "Optional JSON array of applicability boundaries, invalidation cases and pitfalls (also accepted as a JSON string)."
 			},
 			tagsJson: {
-				type: "string",
+				type: "json",
 				required: true,
-				description: "JSON string array of controlled topic tags, e.g. '[\"宏观\", \"高股息\", \"红利策略\"]'."
+				description: "JSON array of controlled topic tags (also accepted as a JSON string), e.g. '[\"宏观\", \"高股息\", \"红利策略\"]'."
 			},
 			tickersJson: {
-				type: "string",
-				description: "Optional JSON string array of related instrument codes, e.g. '[\"BTCUSDT\", \"600519.SH\"]'."
+				type: "json",
+				description: "Optional JSON array of related instrument codes (also accepted as a JSON string), e.g. '[\"BTCUSDT\", \"600519.SH\"]'."
 			},
 			relatedJson: {
-				type: "string",
-				description: "Optional JSON string array of related card ids already in the library, e.g. '[\"kc_01j...\", \"kc_01k...\"]'."
+				type: "json",
+				description: "Optional JSON array of related card ids already in the library (also accepted as a JSON string), e.g. '[\"kc_01j...\", \"kc_01k...\"]'."
 			}
 		},
 		output: {
@@ -196,7 +209,7 @@ function createKnowledgeIngestTool(store, options = {}) {
 function createKnowledgeSearchTool(store) {
 	return defineTool({
 		name: "knowledge_search",
-		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).",
+		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, credibility and explicit freshness cutoffs updatedAfter / publishedAfter. Every result reports its updatedAt and source publish date (unknown is stated as such); cards are never dropped or downgraded by age unless an explicit cutoff asks for it. detail=\"full\" also returns core claims, the fact-check buckets and reusable lessons (capped at 20 cards).",
 		parameters: {
 			query: {
 				type: "string",
@@ -222,6 +235,14 @@ function createKnowledgeSearchTool(store) {
 				type: "string",
 				description: "Credibility filter: \"high\" | \"medium\" | \"low\"."
 			},
+			updatedAfter: {
+				type: "string",
+				description: "Explicit freshness cutoff: keep only cards updated at or after this ISO date/datetime (e.g. \"2026-01-01\" or \"2026-01-01T00:00:00Z\"). Cards with an unparsable updatedAt never match. Omitting it applies no age filter."
+			},
+			publishedAfter: {
+				type: "string",
+				description: "Explicit freshness cutoff on the source publish date: keep only cards whose source.publishedAt is at or after this ISO date. Cards without a source publish date never match an explicit cutoff (unknown is not assumed fresh)."
+			},
 			limit: {
 				type: "number",
 				description: "Maximum results to return (default 20).",
@@ -249,12 +270,29 @@ function createKnowledgeSearchTool(store) {
 			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;
+			let updatedAfterMs;
+			let publishedAfterMs;
+			try {
+				updatedAfterMs = parseCutoff(params.updatedAfter, "updatedAfter");
+				publishedAfterMs = parseCutoff(params.publishedAfter, "publishedAfter");
+			} catch (error) {
+				return error instanceof Error ? error.message : String(error);
+			}
 			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 (updatedAfterMs !== void 0) {
+					const updatedAtMs = Date.parse(card.updatedAt);
+					if (Number.isNaN(updatedAtMs) || updatedAtMs < updatedAfterMs) return false;
+				}
+				if (publishedAfterMs !== void 0) {
+					const publishedAt = card.source.publishedAt;
+					const publishedAtMs = publishedAt === void 0 ? NaN : Date.parse(publishedAt);
+					if (Number.isNaN(publishedAtMs) || publishedAtMs < publishedAfterMs) 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) {
@@ -290,6 +328,7 @@ function createKnowledgeSearchTool(store) {
 			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(`  时间: 更新 ${shownTimestamp(card.updatedAt)} | 发布 ${shownTimestamp(card.source.publishedAt)}`);
 				lines.push(`  摘要: ${card.summary}`);
 				lines.push(`  标签: ${card.tags.join(", ")} | 链接: ${card.source.url}`);
 				if (detail === "full") lines.push(...renderCardFullLines(card));
@@ -364,15 +403,20 @@ function createKnowledgeDeleteTool(store, options = {}) {
 			const target = await store.get(id);
 			if (!target) return `[knowledge_delete] 未找到卡片 [${id}]，请先用 knowledge_search 确认卡片 id`;
 			const referencing = [];
+			const cleaned = [];
 			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({
+				cleaned.push({
 					...card,
 					related: remaining.length > 0 ? remaining : void 0,
 					updatedAt: (/* @__PURE__ */ new Date()).toISOString()
 				});
 			}
+			if (cleaned.length > 0) {
+				if (typeof store.saveMany === "function") await store.saveMany(cleaned);
+				else for (const card of cleaned) await store.save(card);
+			}
 			if (!await store.delete(id)) return `[knowledge_delete] 删除失败：卡片 [${id}] 在删除时已不存在`;
 			onWritten?.();
 			const lines = [`[knowledge_delete] 已删除卡片 [${target.id}] "${target.title}"`, `  核心论点（留痕回显）: ${target.coreClaims.join("；")}`];

package/lib/types.d.ts

@@ -73,6 +73,14 @@ interface KnowledgeCardStore {
   get(id: string): Promise<KnowledgeCard | undefined>;
   getByUrl(url: string): Promise<KnowledgeCard | undefined>;
   save(card: KnowledgeCard): Promise<void>;
+  /**
+   * 批量写入（可选能力）：最终状态等同于按序逐张 save，但实现可为一次事务。
+   *
+   * 存在的理由：文件版 store 的 save 是整表事务（跨进程排他锁 + 锁内读盘 + 序列化 +
+   * 原子写），knowledge_delete 清理 F 张引用方就是 F+1 次整表落盘。调用方在能力存在时
+   * 必须走本方法，缺席（轻量/第三方实现）则逐张 save 降级——正确性两版一致，只差落盘次数。
+   */
+  saveMany?(cards: readonly KnowledgeCard[]): Promise<void>;
   delete(id: string): Promise<boolean>;
 }
 //#endregion

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.1",
+  "version": "0.6.3",
   "type": "module",
   "main": "lib/index.js",
   "types": "./lib/index.d.ts",
@@ -25,12 +25,11 @@
   ],
   "license": "PolyForm-Noncommercial-1.0.0",
   "dependencies": {
-    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
-    "@deepseek-ai/schemastery": "^3.18.4",
-    "@dshtrading/dsh-home": "^0.6.1"
+    "@dshtrading/dsh-home": "^0.6.3"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": ">=4.0.0"
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/dsh-tools": ">=0.2.1-rc.2"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",