pi-okf-memory 0.1.0

package/lib/concept.js

@@ -0,0 +1,264 @@
+//#region src/server/concept.ts
+/**
+* concept.ts — OKF v0.1 概念化:frontmatter 组装、正文模板、概念 ID 规范化、frontmatter 解析。
+* 依据 OKF v0.1:frontmatter 唯一硬要求是 type;title/description 强烈建议;tags/timestamp 可选;扩展字段允许。
+*/
+/** 类型词表(起步版) */
+const TYPE_VOCAB = [
+	"Fact",
+	"Preference",
+	"Decision",
+	"Method",
+	"Insight",
+	"Idea",
+	"Lesson",
+	"TechChoice"
+];
+/** 归一化并校验概念类型(大小写不敏感,必须属于 TYPE_VOCAB);非法时抛错 */
+function normalizeType(type) {
+	const t = String(type || "").trim();
+	if (!t) throw new Error("OKF 概念 type 必填");
+	const hit = TYPE_VOCAB.find((v) => v.toLowerCase() === t.toLowerCase());
+	if (!hit) throw new Error(`非法 type:「${type}」;可选:${TYPE_VOCAB.join("/")}`);
+	return hit;
+}
+/** 规范化概念 ID:保留中文/字母数字,其余转连字符(Windows 安全字符集) */
+function slugify(input) {
+	return String(input ?? "").trim().toLowerCase().replace(/[\s_]+/g, "-").replace(/[^\p{L}\p{N}\-]/gu, "").replace(/-+/g, "-").replace(/^-|-$/g, "");
+}
+/** YAML 标量转义 */
+function yamlScalar(v) {
+	if (typeof v === "string") {
+		if (/^[\p{L}\p{N}\s.,\-_/:（）()%¥￥+*#@!?'"=<>\[\]{}|&^~`\\;]*$/u.test(v) && !/^[\s\-?:]/.test(v) && !v.includes(": ")) return v;
+		return JSON.stringify(v);
+	}
+	if (typeof v === "number" || typeof v === "boolean") return String(v);
+	return JSON.stringify(v);
+}
+function yamlTags(tags) {
+	if (!Array.isArray(tags) || tags.length === 0) return "tags: []";
+	return `tags: [${tags.map((t) => {
+		const s = String(t);
+		return /[,()[\]{}"'#:]/.test(s) ? JSON.stringify(s) : yamlScalar(s);
+	}).join(", ")}]`;
+}
+/** 生成 frontmatter(固定顺序,稳定可比较) */
+function buildFrontmatter(meta) {
+	const lines = ["---"];
+	const order = [
+		"type",
+		"title",
+		"description",
+		"resource",
+		"tags",
+		"timestamp",
+		"source"
+	];
+	for (const key of order) {
+		const v = meta[key];
+		if (v === void 0 || v === null || v === "") continue;
+		if (key === "tags") lines.push(yamlTags(v));
+		else lines.push(`${key}: ${yamlScalar(v)}`);
+	}
+	for (const [k, v] of Object.entries(meta)) {
+		if (order.includes(k)) continue;
+		lines.push(`${k}: ${yamlScalar(v)}`);
+	}
+	lines.push("---");
+	return lines.join("\n");
+}
+/**
+* 生成概念文档。
+*/
+function buildConcept(meta, body) {
+	if (!String(meta.type || "").trim()) throw new Error("OKF 概念必须包含非空 type");
+	const fm = buildFrontmatter(meta);
+	const b = String(body || "").trim();
+	return b ? `${fm}\n\n${b}\n` : `${fm}\n`;
+}
+/**
+* 决策/结论三段式模板(继承用户约定:数据/分析/结论)。
+*/
+function buildDecisionBody(parts) {
+	const { data, analysis, conclusion } = parts || {};
+	const out = [];
+	if (data) out.push(`# 数据\n\n${data.trim()}`);
+	if (analysis) out.push(`# 分析\n\n${analysis.trim()}`);
+	if (conclusion) out.push(`# 结论\n\n${conclusion.trim()}`);
+	if (out.length === 0) throw new Error("Decision/Insight 正文需至少包含 conclusion");
+	return out.join("\n\n");
+}
+/**
+* 技术选型正文模板(TechChoice):Options 候选表 + Active 当前使用。
+*/
+function buildTechChoiceBody(spec) {
+	const opts = spec.options || [];
+	if (opts.length === 0) throw new Error("TechChoice 至少需要一个候选");
+	const rows = opts.map((o) => `| ${yamlScalar(o.name)} | ${yamlScalar(o.desc || "")} | ${yamlScalar(o.config || "")} | ${yamlScalar(o.status || "candidate")} |`).join("\n");
+	const out = [];
+	out.push(`## Options\n\n| 候选 | 说明 | 配置要点 | 状态 |\n|---|---|---|---|\n${rows}`);
+	if (spec.active) out.push(`## Active\n\n- 当前使用:${spec.active}`);
+	if (spec.notes) out.push(`## 相关\n\n${spec.notes.trim()}`);
+	return out.join("\n\n");
+}
+/** 解析 frontmatter(容错:解析失败返回 {meta:null, body:原文};支持引号/多行块/flow 数组) */
+function parseFrontmatter(md) {
+	const text = String(md || "");
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
+	if (!m) return {
+		meta: null,
+		body: text
+	};
+	const [, yaml, body] = m;
+	const meta = {};
+	const lines = yaml.split(/\r?\n/);
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i];
+		const trimmed = line.trim();
+		if (!trimmed || trimmed.startsWith("#")) {
+			i++;
+			continue;
+		}
+		const idx = line.indexOf(":");
+		if (idx <= 0) {
+			i++;
+			continue;
+		}
+		const key = line.slice(0, idx).trim().replace(/^['"]|['"]$/g, "");
+		let val = line.slice(idx + 1).trim();
+		if (val === "|" || val === ">" || val === "|-" || val === ">-") {
+			const block = [];
+			i++;
+			while (i < lines.length && /^\s+/.test(lines[i])) {
+				block.push(lines[i].replace(/^[ \t]+/, ""));
+				i++;
+			}
+			meta[key] = block.join("\n");
+			continue;
+		}
+		if (val.startsWith("[") && val.endsWith("]")) {
+			meta[key] = splitFlowArray(val.slice(1, -1));
+			i++;
+			continue;
+		}
+		meta[key] = unquoteScalar(val);
+		i++;
+	}
+	return {
+		meta,
+		body: body || ""
+	};
+}
+/** flow 数组拆分:引号内的逗号不拆,去引号/转义(闭合引号消费但不进内容;反斜杠转义下一个字符) */
+function splitFlowArray(s) {
+	const out = [];
+	let cur = "";
+	let q = null;
+	let esc = false;
+	for (const ch of s) if (esc) {
+		cur += ch;
+		esc = false;
+	} else if (ch === "\\") esc = true;
+	else if (q) {
+		if (ch === q) q = null;
+		else cur += ch;
+	} else if (ch === "\"" || ch === "'") q = ch;
+	else if (ch === ",") {
+		if (cur.trim()) out.push(unquoteScalar(cur));
+		cur = "";
+	} else cur += ch;
+	if (cur.trim()) out.push(unquoteScalar(cur));
+	return out.filter(Boolean);
+}
+/** 去掉标量两端匹配的引号并还原常见转义 */
+function unquoteScalar(v) {
+	const s = String(v || "").trim();
+	if (s.startsWith("\"") && s.endsWith("\"") || s.startsWith("'") && s.endsWith("'")) return s.slice(1, -1).replace(/\\"/g, "\"").replace(/\\'/g, "'").replace(/\\n/g, "\n");
+	return s;
+}
+/**
+* OKF v0.1 符合性校验(三条硬要求 + 建议字段)。
+*/
+function validateConcept(md) {
+	const errors = [];
+	const warnings = [];
+	const { meta } = parseFrontmatter(md);
+	if (!meta) {
+		errors.push("缺少可解析的 YAML frontmatter");
+		return {
+			ok: false,
+			errors,
+			warnings
+		};
+	}
+	if (!String(meta.type || "").trim()) errors.push("type 字段为空");
+	if (!meta.title) warnings.push("缺 title(将用文件名推导)");
+	if (!meta.description) warnings.push("缺 description(索引/搜索靠它)");
+	if (!meta.timestamp) warnings.push("缺 timestamp");
+	return {
+		ok: errors.length === 0,
+		errors,
+		warnings
+	};
+}
+/**
+* 按顶层小节合并两份概念正文(防止更新时无限追加 "## 补充(日期)"):
+* - 相同小节标题(如 # 数据 / ## Options)→ 新内容覆盖旧小节,保留原位置
+* - 新小节 → 追加到末尾
+* - 无标题引言 → 仅当旧文没有引言时才补入
+*/
+function mergeConceptBodies(existing, incoming) {
+	const ex = splitSections(existing);
+	const inc = splitSections(incoming);
+	const byKey = new Map(ex.map((s) => [s.key, s]));
+	for (const s of inc) if (s.key === null) {
+		if (!byKey.has(null)) byKey.set(null, s);
+	} else byKey.set(s.key, s);
+	const out = [];
+	const used = /* @__PURE__ */ new Set();
+	for (const s of ex) {
+		const hit = byKey.get(s.key);
+		if (hit) {
+			out.push(hit);
+			used.add(s.key);
+		}
+	}
+	for (const s of inc) if (!used.has(s.key)) {
+		out.push(s);
+		used.add(s.key);
+	}
+	return out.map(renderSection).filter(Boolean).join("\n\n");
+}
+/** 按 #/##/### 顶层标题切分成小节(含无标题引言小节 key=null) */
+function splitSections(body) {
+	const sections = [];
+	let cur = null;
+	for (const line of String(body || "").split("\n")) {
+		const m = /^(#{1,3})\s+(.*)$/.exec(line);
+		if (m) {
+			cur = {
+				key: `${m[1]} ${m[2]}`.replace(/\s+/g, " ").trim(),
+				content: ""
+			};
+			sections.push(cur);
+		} else {
+			if (!cur) {
+				cur = {
+					key: null,
+					content: ""
+				};
+				sections.push(cur);
+			}
+			cur.content += line + "\n";
+		}
+	}
+	return sections;
+}
+function renderSection(s) {
+	if (s.key === null) return s.content.trim();
+	const body = s.content.trim();
+	return body ? `${s.key}\n\n${body}` : s.key;
+}
+//#endregion
+export { TYPE_VOCAB, buildConcept, buildDecisionBody, buildFrontmatter, buildTechChoiceBody, mergeConceptBodies, normalizeType, parseFrontmatter, slugify, validateConcept };

package/lib/dedupe.js

@@ -0,0 +1,149 @@
+import { parseFrontmatter } from "./concept.js";
+import { readConcept, scanBundle } from "./store.js";
+import { promises } from "node:fs";
+//#region src/server/dedupe.ts
+/**
+* dedupe.ts — 去重与互补决策(对应"互补而非复制"原则)。
+* 写前必查:命中且相同 → skip;命中但互补 → merge 建议 + 交叉链接;未命中 → create。
+*/
+/**
+* 词项化:空白分词 + CJK 二元组。
+* 纯子串匹配对中文短语(如「查询数据库」)几乎必然落空,而库中概念标题/描述往往写成
+* 「查询鼎赞…数据…」。补重叠二元组后,「查询」「数据」等子片段也能命中,提升中文召回。
+* 保留原始整串词项以维持精确短语加分。
+*/
+function tokenizeQuery(q) {
+	const terms = /* @__PURE__ */ new Set();
+	const raw = String(q || "").split(/\s+/).filter(Boolean);
+	for (const token of raw) {
+		terms.add(token);
+		if (/[\u4e00-\u9fff]/.test(token) && token.length >= 3) for (let i = 0; i < token.length - 1; i++) terms.add(token.slice(i, i + 2));
+	}
+	return [...terms];
+}
+/**
+* 全库检索:按关键词匹配 title/description/tags/type(正文做二级加分)。
+*/
+async function search(root, query, opts = {}) {
+	const { type, tags, limit = 20 } = opts;
+	const q = String(query || "").trim().toLowerCase();
+	const qTerms = tokenizeQuery(q);
+	const concepts = await scanBundle(root);
+	const hits = [];
+	for (const c of concepts) {
+		let text;
+		try {
+			text = await promises.readFile(c.filePath, "utf8");
+		} catch {
+			continue;
+		}
+		const { meta } = parseFrontmatter(text);
+		if (!meta || !meta.type) continue;
+		if (type && String(meta.type).toLowerCase() !== String(type).toLowerCase()) continue;
+		if (tags && tags.length > 0) {
+			const mt = Array.isArray(meta.tags) ? meta.tags.map(String) : [];
+			if (!tags.every((t) => mt.some((x) => x.toLowerCase().includes(String(t).toLowerCase())))) continue;
+		}
+		let score = 0;
+		if (qTerms.length > 0) {
+			const hay = [
+				meta.title,
+				meta.description,
+				Array.isArray(meta.tags) ? meta.tags.join(" ") : "",
+				meta.type
+			].filter(Boolean).join(" ").toLowerCase();
+			let matched = 0;
+			for (const t of qTerms) if (hay.includes(t)) matched++;
+			else if (text.toLowerCase().includes(t)) {
+				score += .3;
+				matched++;
+			}
+			if (matched === 0) continue;
+			score += matched / qTerms.length * 2;
+			if (hay.includes(q)) score += 3;
+		}
+		score += (Array.isArray(meta.tags) ? meta.tags.length : 0) * .1;
+		hits.push({
+			conceptId: c.conceptId,
+			title: meta.title || c.conceptId,
+			description: meta.description || "",
+			type: meta.type,
+			tags: Array.isArray(meta.tags) ? meta.tags : [],
+			score
+		});
+	}
+	hits.sort((a, b) => b.score - a.score);
+	return hits.slice(0, limit);
+}
+/**
+* 按标题找相似概念(去重主查:精确相等或互相包含)。
+* 包含判定要求较短一方 ≥ MIN_CONTAIN_LEN(3 字符),否则「前端」这种短词
+* 会误伤「前端方案」,挡住正常新建。
+*/
+const MIN_CONTAIN_LEN = 3;
+async function findSimilarByTitle(root, title, type) {
+	const t = String(title || "").trim().toLowerCase();
+	if (!t) return [];
+	const concepts = await scanBundle(root);
+	const out = [];
+	for (const c of concepts) {
+		let text;
+		try {
+			text = await promises.readFile(c.filePath, "utf8");
+		} catch {
+			continue;
+		}
+		const { meta } = parseFrontmatter(text);
+		if (!meta || !meta.title) continue;
+		if (type && String(meta.type).toLowerCase() !== String(type).toLowerCase()) continue;
+		const ct = String(meta.title).trim().toLowerCase();
+		if (ct === t) out.push({
+			conceptId: c.conceptId,
+			title: meta.title,
+			type: meta.type,
+			similarity: 1
+		});
+		else if ((ct.includes(t) || t.includes(ct)) && Math.min(ct.length, t.length) >= MIN_CONTAIN_LEN) out.push({
+			conceptId: c.conceptId,
+			title: meta.title,
+			type: meta.type,
+			similarity: .6
+		});
+	}
+	return out.sort((a, b) => b.similarity - a.similarity);
+}
+/**
+* 去重决策。
+*/
+async function decide(root, { title, type, body }) {
+	const similar = await findSimilarByTitle(root, title, type);
+	if (similar.length > 0) {
+		const top = similar[0];
+		if (top.similarity >= 1) {
+			const existing = await readConcept(root, top.conceptId);
+			const bodyLen = String(body || "").trim().length;
+			const existingLen = String(existing.body || "").trim().length;
+			if (bodyLen > existingLen * .7) return {
+				action: "update",
+				conceptId: top.conceptId,
+				reason: `标题相同且新正文更完整(${bodyLen}字 vs 已有${existingLen}字),更新已有概念`
+			};
+			return {
+				action: "skip",
+				conceptId: top.conceptId,
+				reason: "标题相同的概念已存在,内容未明显增加,跳过写入"
+			};
+		}
+		return {
+			action: "update",
+			conceptId: top.conceptId,
+			reason: `找到相近概念[${top.title}](similarity ${top.similarity}),建议互补合并或互建交叉链接`
+		};
+	}
+	return {
+		action: "create",
+		reason: "未命中已有概念,新建"
+	};
+}
+//#endregion
+export { decide, findSimilarByTitle, search };

package/lib/graph.js

@@ -0,0 +1,95 @@
+import { parseFrontmatter } from "./concept.js";
+import { scanBundle } from "./store.js";
+import { loadMeta } from "./learning.js";
+import { promises } from "node:fs";
+//#region src/server/graph.ts
+/**
+* graph.ts — 记忆图谱数据提取:把 OKF 记忆库转成图谱 JSON(nodes/edges/timeline)。
+* 供 okf_graph 工具/服务消费,契约与可视化前端一致,可被 dshfind 等复用。
+* 纯业务逻辑,不依赖 dsh ctx,便于单测。
+*/
+/**
+* 提取记忆图谱数据。
+*/
+async function buildGraph(root, _opts = {}) {
+	const concepts = await scanBundle(root);
+	const weights = await loadMeta(root);
+	const meta = {
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		root,
+		totalConcepts: concepts.length
+	};
+	const nodes = [];
+	const byId = /* @__PURE__ */ new Map();
+	for (const c of concepts) {
+		let text;
+		try {
+			text = await readText(c.filePath);
+		} catch {
+			continue;
+		}
+		const { meta: fm } = parseFrontmatter(text);
+		if (!fm) continue;
+		const w = weights.entries[c.conceptId];
+		nodes.push({
+			id: c.conceptId,
+			title: fm.title || c.conceptId.replace(/^[^/]+\//, ""),
+			type: fm.type || "Other",
+			tags: Array.isArray(fm.tags) ? fm.tags : [],
+			description: fm.description || "",
+			weight: w ? +w.weight.toFixed(2) : 1,
+			state: w?.state || "active",
+			lastAccessed: w?.lastAccessed || null
+		});
+		byId.set(c.conceptId, c.conceptId);
+	}
+	const edges = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const c of concepts) {
+		let text;
+		try {
+			text = await readText(c.filePath);
+		} catch {
+			continue;
+		}
+		const { body } = parseFrontmatter(text);
+		const re = /\[([^\]]+)\]\(\/([^)]+\.md)\)/g;
+		let m;
+		while ((m = re.exec(body || "")) !== null) {
+			let targetId = m[2].replace(/^\/+/, "").replace(/\.md$/, "");
+			if (!byId.has(targetId)) {
+				const k = Object.keys(byId).find((x) => x.toLowerCase() === targetId.toLowerCase());
+				if (k) targetId = k;
+			}
+			if (targetId && targetId !== c.conceptId) {
+				const k = [c.conceptId, targetId].sort().join("||");
+				if (!seen.has(k)) {
+					seen.add(k);
+					edges.push({
+						source: c.conceptId,
+						target: targetId,
+						text: m[1]
+					});
+				}
+			}
+		}
+	}
+	return {
+		meta,
+		nodes,
+		edges,
+		timeline: Object.entries(weights.entries || {}).map(([id, e]) => ({
+			id,
+			weight: +e.weight.toFixed(2),
+			state: e.state || "active",
+			lastAccessed: e.lastAccessed || null,
+			accessCount: e.accessCount || 0
+		}))
+	};
+}
+/** 读文件 */
+async function readText(filePath) {
+	return promises.readFile(filePath, "utf8");
+}
+//#endregion
+export { buildGraph };