@kenz1117/dsh-engram 0.7.4 → 0.7.5

package/lib/index.js

@@ -3708,31 +3708,156 @@ function truncateItem(text, maxChars = RECALL_PER_ITEM_CHARS) {
 	return text.length <= maxChars ? text : `${text.slice(0, maxChars)}…`;
 }
 /**
-* 总量预算内贪心装填行（保序；某行装不下时继续尝试更短的后续行），
-* 被跳过的行计数并在末尾追加提示行。
-* @param lines - 候选行（已按相关性排序）。
-* @param totalBudget - 总字符预算，默认 RECALL_TOTAL_CHARS。
-* @returns 装填后的行；有丢弃时末尾含「另有 N 条…」提示。
+* 预算内的贪心装填（保序）：按 cost 逐个判断，装不下的计入 dropped 并继续试后续更短的项。
+* @param items - 候选（已按相关性排序）。
+* @param cost - 单项占用预算（字符数等）。
+* @param totalBudget - 总预算。
+* @returns 保留项与丢弃数。
 */
-function enforceBudget(lines, totalBudget = RECALL_TOTAL_CHARS) {
+function fitWithinBudget(items, cost, totalBudget) {
 	const kept = [];
 	let used = 0;
 	let dropped = 0;
-	for (const line of lines) {
-		if (used + line.length > totalBudget) {
+	for (const item of items) {
+		const size = cost(item);
+		if (used + size > totalBudget) {
 			dropped += 1;
 			continue;
 		}
-		kept.push(line);
-		used += line.length;
+		kept.push(item);
+		used += size;
 	}
+	return {
+		kept,
+		dropped
+	};
+}
+/**
+* 总量预算内贪心装填行（保序；某行装不下时继续尝试更短的后续行），
+* 被跳过的行计数并在末尾追加提示行。
+* @param lines - 候选行（已按相关性排序）。
+* @param totalBudget - 总字符预算，默认 RECALL_TOTAL_CHARS。
+* @returns 装填后的行；有丢弃时末尾含「另有 N 条…」提示。
+*/
+function enforceBudget(lines, totalBudget = RECALL_TOTAL_CHARS) {
+	const { kept, dropped } = fitWithinBudget(lines, (line) => line.length, totalBudget);
 	if (dropped > 0) kept.push(`（另有 ${dropped} 条未展示：缩小查询范围或降低 limit 后重试）`);
 	return kept;
 }
+/** 判定后可选的下一步策略。 */
+const NEXT_STRATEGIES = [
+	"answer",
+	"search_keyword",
+	"search_room",
+	"search_timeline",
+	"ask_user",
+	"stop"
+];
+/**
+* 判断字符串是否为合法策略。
+* @param value - 待判定字符串。
+*/
+function isNextStrategy(value) {
+	return NEXT_STRATEGIES.includes(value);
+}
+/**
+* 构造批次内唯一的证据 ref：已排桩时用「scope/房间#桩位」（与检索行里的宫殿坐标一致），
+* 未排桩时用「scope/#id 前 8 位」。带 scope 前缀，跨作用域的同名房间不会撞号。
+* @param scope - 条目所在作用域。
+* @param id - 条目 id。
+* @param slot - 宫殿坐标；未排桩传 undefined。
+*/
+function evidenceRefOf(scope, id, slot) {
+	return slot === void 0 ? `${scope}/#${id.slice(0, 8)}` : `${scope}/${slot.room}#${slot.index}`;
+}
+/** 批次注册表：按会话隔离，超出上限丢最旧的批次。 */
+var EvidenceBatches = class {
+	bySession = /* @__PURE__ */ new Map();
+	counter = 0;
+	/**
+	* 注册一个批次。
+	* @param sessionId - 会话标识。
+	* @param refs - 本次输出中可引用的证据 ref（重复项只留一次）。
+	* @param now - 当前时间（测试注入）。
+	* @returns 新批次。
+	*/
+	register(sessionId, refs, now = Date.now()) {
+		this.counter += 1;
+		const batch = {
+			batchId: `batch-${String(this.counter)}`,
+			refs: new Set(refs),
+			createdAt: now
+		};
+		const batches = this.bySession.get(sessionId) ?? /* @__PURE__ */ new Map();
+		batches.set(batch.batchId, batch);
+		while (batches.size > 20) {
+			const oldest = batches.keys().next().value;
+			if (oldest === void 0) break;
+			batches.delete(oldest);
+		}
+		this.bySession.set(sessionId, batches);
+		return batch;
+	}
+	/**
+	* 取会话内指定批次。
+	* @param sessionId - 会话标识。
+	* @param batchId - 批次 id。
+	* @returns 批次；不存在或已被上限淘汰时返回 undefined。
+	*/
+	get(sessionId, batchId) {
+		return this.bySession.get(sessionId)?.get(batchId);
+	}
+	/**
+	* 清理会话的全部批次（会话销毁时调用，避免长驻进程累积）。
+	* @param sessionId - 会话标识。
+	*/
+	clear(sessionId) {
+		this.bySession.delete(sessionId);
+	}
+};
+/** 进程内批次注册表：插件为单实例，会话销毁时调用 clear 释放该会话的批次。 */
+const evidenceBatches = new EvidenceBatches();
+/**
+* 校验判定：ref 必须属于批次，sufficient 由代码强制。
+* 强制规则：sufficient 需同时满足「模型声称充足」「至少一条本批次有效证据」「策略为 answer」；
+* 三者缺一即判为不充足，并把策略改写为继续检索（模型声称充足时）或尊重其非作答策略。
+* @param batch - 被引用的批次。
+* @param request - 模型提交的判定。
+* @returns 校验后的判定结果（含被拒绝与超限的 ref 明细）。
+*/
+function assessEvidence(batch, request) {
+	const submitted = request.evidenceRefs.filter((ref) => typeof ref === "string").map((ref) => ref.trim()).filter((ref) => ref !== "");
+	const unique = [...new Set(submitted)];
+	const limited = unique.slice(0, 8);
+	const droppedRefs = unique.slice(8);
+	const accepted = [];
+	const rejectedRefs = [];
+	for (const ref of limited) if (batch.refs.has(ref)) accepted.push(ref);
+	else rejectedRefs.push(ref);
+	const rawMissing = typeof request.missing === "string" ? request.missing.trim() : "";
+	const missingTruncated = rawMissing.length > 160;
+	const missing = missingTruncated ? `${rawMissing.slice(0, 160)}…` : rawMissing;
+	const requestedStrategy = typeof request.nextStrategy === "string" ? request.nextStrategy.trim() : "";
+	const strategy = isNextStrategy(requestedStrategy) ? requestedStrategy : "search_keyword";
+	const claimed = request.sufficient === true;
+	const sufficient = claimed && accepted.length > 0 && strategy === "answer";
+	const nextStrategy = sufficient || strategy !== "answer" ? strategy : "search_keyword";
+	return {
+		sufficient,
+		evidenceRefs: accepted,
+		rejectedRefs,
+		droppedRefs,
+		missing,
+		missingTruncated,
+		nextStrategy,
+		requestedStrategy,
+		forced: claimed !== sufficient || strategy !== requestedStrategy || nextStrategy !== strategy
+	};
+}
 //#endregion
 //#region src/tools/create.ts
 /**
-* 15 个 engram_ 工具的定义与执行器。工具 schema 保持窄参数；
+* 17 个 engram_ 工具的定义与执行器。工具 schema 保持窄参数；
 * scope 决定读写哪个分库；嵌入缺失时检索结果显式标记降级。
 * @module @kenz1117/dsh-engram/tools/create
 */
@@ -3770,6 +3895,26 @@ function renderHistoryRun(result) {
 	lines.push("同一批可重复执行：已完成的轮次按幂等键跳过，只补未完成的部分。");
 	return lines.join("\n");
 }
+/** 证据门策略的可读提示。 */
+const STRATEGY_HINT = {
+	answer: "可以据此作答",
+	search_keyword: "换关键词再检索（engram_search）",
+	search_room: "收窄到具体房间再检索（engram_search 带 room）",
+	search_timeline: "按时间线找（engram_timeline）",
+	ask_user: "向用户澄清缺失的信息",
+	stop: "不回答，并向用户说明缺少什么"
+};
+/** 证据门判定的模型可读文本（含被拒绝的 ref 与强制改写说明）。 */
+function renderAssessText(verdict, batchId) {
+	const lines = [verdict.sufficient ? `证据判定：充足（批次 ${batchId}，${String(verdict.evidenceRefs.length)} 条有效证据）——可以据此作答。` : `证据判定：不足（批次 ${batchId}）。`];
+	if (verdict.evidenceRefs.length > 0) lines.push(`有效证据：${verdict.evidenceRefs.join("、")}`);
+	if (verdict.rejectedRefs.length > 0) lines.push(`无效 ref（不属于该批次，已忽略）：${verdict.rejectedRefs.join("、")}`);
+	if (verdict.droppedRefs.length > 0) lines.push(`超出上限被丢弃（单次最多 ${String(8)} 条）：${verdict.droppedRefs.join("、")}`);
+	lines.push(`缺口：${verdict.missing === "" ? "（未填写）" : verdict.missing}${verdict.missingTruncated ? "（已截断）" : ""}`);
+	lines.push(`下一步：${verdict.nextStrategy} —— ${STRATEGY_HINT[verdict.nextStrategy]}`);
+	if (verdict.forced) lines.push("注意：判定由代码修正——sufficient 需同时满足「你声称充足」「至少一条属于本批次的有效证据」「nextStrategy=answer」。");
+	return lines.join("\n");
+}
 /** 从模型参数收敛 scope（非法值或缺失回退 fallback）。 */
 function scopeOf(raw, fallback) {
 	if (raw === "user" || raw === "project" || raw === "shared") return raw;
@@ -3839,7 +3984,7 @@ async function rewriteQueries(deps, exec, query) {
 	}
 }
 /**
-* 构造 16 个工具定义（engram_save/search/timeline/update/forget/report/review/review_queue/
+* 构造 17 个工具定义（engram_save/search/assess/timeline/update/forget/report/review/review_queue/
 * stats/export/distill/examine/neighbors/audit_forgotten/tour/ingest_history）。
 * @param deps - 分库打开器、嵌入器、辅助 LLM、导出目录。
 * @returns 可直接 register 的工具定义数组。
@@ -4219,16 +4364,106 @@ function createEngramTools(deps) {
 				};
 			}));
 			const degraded = retrievals.some((retrieval) => retrieval.degraded);
-			const lines = enforceBudget(mergeQueryResults(retrievals, limit, 60, Math.floor(Math.max(0, limit) / Math.max(1, rewrite.queries.length))).map((hit, index) => {
+			const { kept, dropped } = fitWithinBudget(mergeQueryResults(retrievals, limit, 60, Math.floor(Math.max(0, limit) / Math.max(1, rewrite.queries.length))).map((hit, index) => {
+				const ref = evidenceRefOf(hit.record.scope, hit.record.id, hit.record.slot);
 				const edge = hit.viaEdge === void 0 ? "" : `（经 ${hit.viaEdge.type} 关联自 ${hit.viaEdge.from}）`;
 				const slot = hit.record.slot === void 0 ? "" : ` ${hit.record.slot.room}#${hit.record.slot.index}`;
 				const date = ` 刻于 ${new Date(hit.record.createdAt).toISOString().slice(0, 10)}`;
 				const cues = hit.cues === void 0 ? "" : ` 相邻桩位: ${hit.cues.neighbors.join(", ")}`;
-				return `${index + 1}. [${hit.record.scope}/${hit.record.kind}]${slot}${date} ${truncateItem(hit.record.content)}（id=${hit.record.id}）${edge}${cues}`;
-			}));
+				return {
+					ref,
+					line: `${index + 1}. [${hit.record.scope}/${hit.record.kind}]${slot}${date} ${truncateItem(hit.record.content)}（id=${hit.record.id}, ref=${ref}）${edge}${cues}`
+				};
+			}), (entry) => entry.line.length, RECALL_TOTAL_CHARS);
+			const lines = kept.map((entry) => entry.line);
+			if (dropped > 0) lines.push(`（另有 ${dropped} 条未展示：缩小查询范围或降低 limit 后重试）`);
+			const sessionId = exec.agent === void 0 ? void 0 : String(exec.agent.session.id);
+			const batch = sessionId === void 0 || kept.length === 0 ? void 0 : evidenceBatches.register(sessionId, kept.map((entry) => entry.ref));
+			const prefix = degraded && lines.length > 0 ? "（语义嵌入不可用，仅关键词检索）\n" : "";
+			const roomNote = rooms === void 0 ? "" : `（房间路由：${rooms.join("、")}）\n`;
+			const batchNote = batch === void 0 ? "" : `\n批次 ${batch.batchId}（${String(batch.refs.size)} 条可引用证据）：作答前用 engram_assess 判定证据是否充分，evidenceRefs 只能引用上面的 ref。`;
 			return {
 				degraded,
-				text: renderMemoryPacket(`${degraded && lines.length > 0 ? "（语义嵌入不可用，仅关键词检索）\n" : ""}${rooms === void 0 ? "" : `（房间路由：${rooms.join("、")}）\n`}${lines.join("\n") || "无命中"}`, "tool_search", input.query)
+				text: renderMemoryPacket(`${prefix}${roomNote}${lines.join("\n") || "无命中"}${batchNote}`, "tool_search", input.query)
+			};
+		}
+	});
+	const assess = defineTool({
+		name: "engram_assess",
+		description: "证据门：检索（engram_search）之后、作答之前，判定「检索到的内容是否足以回答当前问题」。提交 batchId、sufficient、最多 8 条 evidenceRefs（只能引用该批次输出里的 ref=…）、缺口说明 missing（≤160 字符）与下一步 nextStrategy。代码强制校验：sufficient 需同时满足「你声称充足」「至少一条属于本批次的有效证据」「nextStrategy=answer」，否则判为不足并把策略改回继续检索；不属于该批次的 ref 会被拒绝并列出。判词与拒绝明细写入审计日志。",
+		parameters: {
+			batchId: {
+				type: "string",
+				required: true,
+				description: "engram_search 输出末尾给出的批次 id（如 batch-3）"
+			},
+			sufficient: {
+				type: "boolean",
+				required: true,
+				description: "证据是否足以回答当前问题（true 时 nextStrategy 必须为 answer）"
+			},
+			evidenceRefs: {
+				type: "array",
+				items: { type: "string" },
+				description: "引用的证据 ref（最多 8 条，只能取该批次输出里的 ref=…）"
+			},
+			missing: {
+				type: "string",
+				description: "缺少什么维度的信息（≤160 字符）"
+			},
+			nextStrategy: {
+				type: "string",
+				enum: [...NEXT_STRATEGIES],
+				description: "下一步：answer 作答 / search_keyword 换关键词 / search_room 换房间 / search_timeline 查时间线 / ask_user 问用户 / stop 不回答"
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					sufficient: {
+						type: "boolean",
+						required: true
+					},
+					nextStrategy: {
+						type: "string",
+						required: true
+					},
+					text: {
+						type: "string",
+						required: true
+					}
+				}
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: value.text
+			}]
+		},
+		async execute(args, exec) {
+			const input = args;
+			if (typeof input.batchId !== "string" || input.batchId.trim() === "") throw new Error("engram_assess: batchId 必填（取自 engram_search 输出末尾）");
+			const sessionId = exec.agent === void 0 ? void 0 : String(exec.agent.session.id);
+			const batch = sessionId === void 0 ? void 0 : evidenceBatches.get(sessionId, input.batchId.trim());
+			if (batch === void 0) throw new Error(`engram_assess: 批次 ${input.batchId} 不存在或已过期（每个会话保留最近 ${String(20)} 个批次）——请重新 engram_search 取新批次`);
+			const verdict = assessEvidence(batch, {
+				sufficient: input.sufficient === true,
+				evidenceRefs: Array.isArray(input.evidenceRefs) ? input.evidenceRefs.filter((ref) => typeof ref === "string") : [],
+				missing: typeof input.missing === "string" ? input.missing : "",
+				nextStrategy: typeof input.nextStrategy === "string" ? input.nextStrategy : ""
+			});
+			await (await deps.openStore("user")).audit("assess", batch.batchId, JSON.stringify({
+				batchId: batch.batchId,
+				sufficient: verdict.sufficient,
+				refs: verdict.evidenceRefs,
+				rejected: verdict.rejectedRefs,
+				strategy: verdict.nextStrategy
+			}));
+			return {
+				sufficient: verdict.sufficient,
+				nextStrategy: verdict.nextStrategy,
+				text: renderAssessText(verdict, batch.batchId)
 			};
 		}
 	});
@@ -4622,6 +4857,7 @@ function createEngramTools(deps) {
 	return [
 		save,
 		search,
+		assess,
 		timeline,
 		update,
 		forget,
@@ -5270,6 +5506,38 @@ function reasonsLabel(reasons) {
 	return reasons.map((r) => LABELS[r]).join(" / ");
 }
 //#endregion
+//#region src/token.ts
+/**
+* token 估算：CJK 感知的上下文预算口径。
+*
+* 汉字、假名、韩文与全角标点按 1.5 token/字计，其余字符按 4 字符/token 计。
+* 统一的 `长度 / 4` 会把中文低估四倍以上，使按 token 计的注入预算与实际占用脱钩
+* （中文 1024 token 预算实际会注入四千余 token）。
+* @module @kenz1117/dsh-engram/token
+*/
+/** 单个 CJK 字符的 token 成本。 */
+const WIDE_TOKENS_PER_CHAR = 1.5;
+/**
+* 判断码点是否属于 CJK 文字与全角符号区间（含扩展平面）。
+* @param codePoint - Unicode 码点。
+*/
+function isWideCodePoint(codePoint) {
+	return codePoint >= 12288 && codePoint <= 12351 || codePoint >= 12352 && codePoint <= 12543 || codePoint >= 13312 && codePoint <= 19903 || codePoint >= 19968 && codePoint <= 40959 || codePoint >= 43360 && codePoint <= 43391 || codePoint >= 44032 && codePoint <= 55295 || codePoint >= 63744 && codePoint <= 64255 || codePoint >= 65280 && codePoint <= 65376 || codePoint >= 65504 && codePoint <= 65510 || codePoint >= 131072 && codePoint <= 262143;
+}
+/**
+* 估算文本占用的 token 数（向上取整）。
+* @param text - 待估算文本。
+* @returns token 估算值；空串为 0。
+*/
+function estimateTokens(text) {
+	if (text === "") return 0;
+	let wide = 0;
+	let narrow = 0;
+	for (const char of text) if (isWideCodePoint(char.codePointAt(0))) wide += 1;
+	else narrow += 1;
+	return Math.ceil(wide * WIDE_TOKENS_PER_CHAR + narrow / 4);
+}
+//#endregion
 //#region src/index.ts
 /**
 * dsh-engram：DeepSeek Harness 跨会话长期记忆插件（host 半）。
@@ -5280,19 +5548,20 @@ function reasonsLabel(reasons) {
 /** Cordis 插件名（loader 诊断与注入 source 使用）。 */
 const name = "dsh-engram";
 /** 插件版本（与 package.json 同步，写进备份 _meta.json）。 */
-const VERSION = "0.7.2";
+const VERSION = "0.7.5";
 /** 必需服务：工具注册表与 LLM 流式端点（摄取/蒸馏的辅助调用）。 */
 const inject = ["tools", "llm"];
 /**
-* 会话开始注入的画像渲染：按重要性降序在 token 预算内整行装填（估算 ceil(len/4)，
-* 超预算的行跳过不截断、继续试更短行）；装不下的条目降级为索引行（#id + 前 40 字），
-* 索引行也装不下的折成末尾 `+N more; use engram_search` 计数行。
+* 会话开始注入的画像渲染：按重要性降序在 token 预算内整行装填（估算见
+* estimateTokens：中文按 1.5 token/字、其余按 4 字符/token，超预算的行跳过不截断、
+* 继续试更短行）；装不下的条目降级为索引行（#id + 前 40 字），
+* 索引行也装不下的折成末尾 `+N more; use engram_search` 计数行；计数行同样占用预算。
 * @param records - 候选条目（调用方已按重要性排序、按条数截断）。
 * @param tokenBudget - 整段画像的 token 预算（含首尾固定行）。
 * @returns 渲染文本与溢出条目（调用方可用辅助 LLM 压缩后重渲染）。
 */
 function renderProfileDetailed(records, tokenBudget) {
-	const estimate = (text) => Math.ceil(text.length / 4);
+	const estimate = estimateTokens;
 	const header = "User memory profile (dsh-engram, cross-session) — Grand Hall (always present):";
 	const footer = "Use engram_search to recall details (pass room to search inside one room); use engram_save to persist new facts.";
 	let remaining = Math.max(0, tokenBudget - estimate(header) - estimate(footer));
@@ -5308,6 +5577,7 @@ function renderProfileDetailed(records, tokenBudget) {
 		} else overflow.push(record);
 	}
 	let more = 0;
+	remaining -= overflow.length === 0 ? 0 : estimate(`+${overflow.length} more; use engram_search`);
 	for (const record of overflow) {
 		const line = `- [${record.kind}] #${record.id} ${record.content.slice(0, 40)}…`;
 		const cost = estimate(line);
@@ -5316,7 +5586,7 @@ function renderProfileDetailed(records, tokenBudget) {
 			remaining -= cost;
 		} else more += 1;
 	}
-	if (more > 0) lines.push(`+${more} more; use engram_search`);
+	if (more > 0 && remaining >= 0) lines.push(`+${more} more; use engram_search`);
 	return {
 		text: [
 			header,
@@ -5727,6 +5997,9 @@ function apply(ctx, config = {}) {
 		});
 	});
 	if (resolved.injectProfile || resolved.ingest !== "off") ctx.on("agent/pre-step", (payload, next) => preStep(ctx, openStore, resolved, embedder, preStepState, logIngestRequest, payload, next), { prepend: true });
+	ctx.on("session/disposed", (session) => {
+		evidenceBatches.clear(String(session.id));
+	});
 	if (resolved.ingest !== "off") ctx.on("session/disposed", (session) => {
 		const mode = resolved.ingest;
 		if (mode === "off") return;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kenz1117/dsh-engram",
   "description": "Cross-session long-term memory for DeepSeek Harness (memory palace · AGI Architecture Exploration on dsh-market): dual-scope SQLite memory graph, hybrid retrieval, provenance audit, and a knowledge flywheel.",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "icon": "icon.svg",
   "logo": "icon-256.svg",
   "publishConfig": {