Skip to content

Commit 21abd07

Browse files
committed
feat(inject): 能力说明与约束/偏好分池逐字保真(#249 第一批)
- 新键 injectGuidanceEnabled(默认关):memory_search / memory_save 工具描述 尾部追加判断指引,并注册 order 150 系统提示段(常量文本、同会话稳定); 指引写英文单一正本(src/guide.js),与 memory.language 管辖的生成内容/块内 标题分家 - 新键 pinnedInjectBudget(0-5,默认 0 = 关闭):约束/偏好类进独立 pin 池, 块头前置、不参与跨轮轮换(也不进轮换历史)、逐字保真(2000 字硬顶,超顶 照旧带截断提示),超预算条数在块内如实标注「另有 N 条未展示」 - 默认档注入块构成逐字节不变(回归首例锁这条);选路统计经可选出参 pinnedStats 透出,injectCandidates 的数组契约不变 - 测试 1220 -> 1228
1 parent f2f658c commit 21abd07

18 files changed

Lines changed: 468 additions & 33 deletions

‎dsh-mneme/CHANGELOG.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44

55
## 🆕 新增
66

7+
- **注入形态(issue #249 第一批):能力说明 + 约束/偏好分池逐字保真**:两个 opt-in 键,默认关/零,默认档下注入块与既有行为逐字节一致。① `injectGuidanceEnabled`(默认关)——把「怎么用记忆」的判断指引落到两个零注入成本的位置:`memory_search` / `memory_save` 的工具描述尾部各追加一句判断指引(工具描述常驻、不进每轮上下文),以及一段 order 150 的系统提示段(常量文本、`[dsh-mneme memory]` 前缀——常驻段内容必须同会话内稳定,否则每轮变化会作废其后的前缀缓存;宿主不提供 section seam 时静默跳过,能力说明仍落在工具描述上,不算失败)。指引只加在「何时不该用」真有歧义处:`memory_list` / `memory_get` / `memory_update` 的触发是机械的,`memory_register_document`(#230 已内建 `Use for … lookups`)与 `memory_runtime`(已自带 provision 成本告诫)不重复;跨工具的克制判断进总则段——第 5 条点明可逆替代品(`memory_archive` 隐藏、`memory_forget` 只停注入,两者均可恢复)与**不可逆**的 `memory_delete`,这是全 guide 里唯一有数据损失后果的一句(回归测试锁它在场)。指引写**英文单一正本**(新内聚块 `src/guide.js`):注入指引的三条参照实现(ACP 的 `ACP_SYSTEM_PROMPT` + `HOW_TO_COMPRESS_RULES`、mnemon 的 `ROUTING_GUIDANCE`、宿主压缩摘要规则)全为英文,仓库既有先例也是工具描述硬编码英文,而 `memory.language` 管的是「生成出来的记忆内容与块内标题」,与本模块是两件事——故不并入 `STR`、不做 zh/en 双写(双写只会让两份文本日后漂移)。② `pinnedInjectBudget`(0–5,默认 0 = 关闭)——约束/偏好类进独立 pin 池:不进相关性竞争(取满预算后前置到块内排序之前)、不参与跨轮轮换(也不进轮换历史——每轮固定出现的 pin 若记进去只会占满轮换窗口、挤掉情景候选的新鲜度)、逐字保真(不受 `injectContentMaxChars` 的常规截断,只受 2000 字硬顶:逐字不等于无界,一条超长约束若无上限会每轮把常驻段吃满,超顶照旧带截断提示)。独立预算的意义是 pin 不占 `maxInjectedItems` 名额、也不会把当前任务需要的情景候选挤出去;超预算条数在块内如实标注「另有 N 条未展示」,绝不静默。选路统计经可选出参 `pinnedStats` 透出,`injectCandidates` 的「返回数组」契约不变。待维护者拍板(PR 内说明,本批次不自行决定):`constraint` 同属 `CODING_MEMORY_TYPES`,非编码任务里已被 `codingGate` 滤掉、pin 池同样拿不到它。测试 1220 → **1228**。
8+
79
- **document 型记忆——agent 产长文档入库为指针行(issue #230)**:写入权分离——全文归 agent(管线零读零写零改),库里只存摘要 + doc_path + evidence 三样;新工具 `memory_register_document({path,title,summary,tags,importance,evidence})` 作唯一铸造口(内聚块 `src/document.js`,service barrel 出口):注册校验(~ 展开后绝对路径、存在 + 非空常规文件、evidence 与库求交——合法子集落库 + `evidence_degraded` 系统标记、全捏造整单拒绝);C2 vector 档比对(minSim 0.92 复用 #127 档语义;同 doc_path/同标题 = 出新版显式 supersede——旧行归档 + `[superseded by <id>]` 指针注记 + content_history 存旧摘要,旧文件不删;仅向量近重复而路径标题都不同 = 拒绝并指路,不越 C1 矛盾检测替 agent 裁决);store 新增 doc_path 列(幂等迁移),toApiList 条件透出 doc_path(普通行 DTO 逐字节同形),memory_get 渲染亮出文件路径;`documentMemoryEnabled`(默认关,白名单 + lightMode 强制关,面板「记忆增强」组第三处落位)+ `documentInjectBudget`(1–5 默认 2);注入档位合并拍板(#164 评审线,#230 内一次落地):叙述条(source=narrative)从纯按需解禁进注入落次优先档(受 dreamNarrativeEnabled 约束,语义/检索路径不变),document 摘要行同档 + 独立预算封顶(超预算跳过由后续候选补位),dream/sleep 五个候选池排除 document(互不代管),heat 免疫(λ=0,指针行不衰减);写入权分离守卫双保险(saveWithDedupe / updateMemory 拒绝铸造或改入 document,standalone API 数据面给 400 `document-requires-register`),MCP 六件套 memory_list 枚举平价同步 +document(注册工具不进 MCP,接口面归 #231)。
810
- **总览(dream_summarize)独立路由与输入硬上限(issue #258)**:`dreamSummaryProvider` / `dreamSummaryModel`(默认空 = 沿用巩固路由,行为逐字节不变)——consolidate 有 `dreamMaxSnapshotSize` 窗口而总览输入为全库无界,两者 ctx 需求差数倍却强制共用 dream 路由:`dreamProvider` 指向小 ctx 模型时总览当场 `CONTEXT_WINDOW_EXCEEDED`(实测 120,969 > 32,768 tokens),指向大 ctx 模型则 consolidate 的卸载收益归零;`dreamSummaryMaxInputs`(默认 0 = 不设上限,0–100000 可调)>0 时按 `updated_at` 倒序保留最新 N 条(与 consolidate 窗口同一排序口径),总览口径脚注的条数随实际输入变化。三键 schema 与 settings 白名单成对落位,面板可调。
911

‎dsh-mneme/lib/client.js‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -305,6 +305,8 @@ window.__ModuleLoader__.load({
305305
"memory.features.loadFailed": "加载失败",
306306
"memory.features.autoInject": "自动注入",
307307
"memory.features.autoInject.hint": "每轮对话自动携带相关记忆",
308+
"memory.features.injectGuidanceEnabled": "能力说明",
309+
"memory.features.injectGuidanceEnabled.hint": "在工具描述与一次性提示段里说明怎么用记忆(何时查、何时写、拿不准就不做)",
308310
"memory.features.autoSummarize": "自动总结",
309311
"memory.features.autoSummarize.hint": "对话结束自动提炼记忆条目",
310312
"memory.features.hotMemoryEnabled": "热记忆",
@@ -668,6 +670,8 @@ window.__ModuleLoader__.load({
668670
"memory.features.loadFailed": "Failed to load",
669671
"memory.features.autoInject": "Auto injection",
670672
"memory.features.autoInject.hint": "Carry relevant memories into every turn",
673+
"memory.features.injectGuidanceEnabled": "Capability guide",
674+
"memory.features.injectGuidanceEnabled.hint": "Explain how to use memory (when to search, when to save, when to do nothing) in tool descriptions plus a one-time prompt section",
671675
"memory.features.autoSummarize": "Auto summarization",
672676
"memory.features.autoSummarize.hint": "Distill memory entries when a conversation ends",
673677
"memory.features.hotMemoryEnabled": "Hot memory",
@@ -1774,7 +1778,7 @@ window.__ModuleLoader__.load({
17741778
// 不被专业项淹没。429 调速器参数、distillMaxChars、codingBoostFactor
17751779
// 属调优噪音,按对齐结论留在配置文件,不上 UI。
17761780
const FEATURE_GROUPS = [
1777-
{ key: "group.core", items: ["autoInject", "autoSummarize", "hotMemoryEnabled", "memoryQualityFilter.enabled", "llmAudit.enabled"] },
1781+
{ key: "group.core", items: ["autoInject", "injectGuidanceEnabled", "autoSummarize", "hotMemoryEnabled", "memoryQualityFilter.enabled", "llmAudit.enabled"] },
17781782
{ key: "group.enhance", items: ["entityExtractionEnabled", "codingRetrospect", "rerankEnabled", "resilientModelDownload", "searchSemanticDedup", "bm25SearchEnabled", "heatEnabled", "documentMemoryEnabled"] },
17791783
{ key: "group.dream", items: ["autoDream", "sleepModeEnabled"] },
17801784
// v0.8.0 A4(issue #17):作用域隔离组——标注总开关 + 严格硬过滤。

‎dsh-mneme/lib/config.js‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,20 @@ export const Config = z.object({
7777
// maxInjectedItems 上限——只做**单向收缩**,绝不越过用户配置的上限;判据只看
7878
// 查询本身,不做额外检索(先探针检索等于白付一次 fuseRecall)。
7979
injectUncertaintyAdaptive: z.boolean().default(false),
80+
// #249(第一批):能力说明——「怎么用记忆」的判断指引。落两个零注入成本的
81+
// 位:①`memory_search` / `memory_save` 的工具描述补一句判断指引(工具描述是
82+
// 常驻文本,不进每轮上下文);②一段 order 150 的系统提示段(一次性、同会话
83+
// 内不随轮次变化,因此不作废前缀缓存),只讲总则(优先序、何时查、何时写、
84+
// 何时 no-op)。默认关:关闭时工具描述与提示段与既有行为逐字节一致。
85+
injectGuidanceEnabled: z.boolean().default(false),
86+
// #249(第一批):B1 pin 池预算——约束/偏好类注入条目的独立小上限。约束与
87+
// 偏好被静默降级是本议题的立项核心(同类知识与情景日志同池同速率摘要,实测
88+
// 一轮压缩后仅保 53%、五轮 10%),故这两类不进相关性竞争、不参与跨轮轮换、
89+
// 逐字保真(仅受超大条目的硬顶保护,截断仍带提示)并排在块内排序之前。
90+
// 独立预算的意义:pin 不占 maxInjectedItems 名额,不会把当前任务需要的情景
91+
// 候选挤出预算(另一种「批量塞历史」)。0(默认)= 关闭,注入块构成与既有
92+
// 行为逐字节一致;超出预算的条数在块内如实标注未展示条数,绝不静默。
93+
pinnedInjectBudget: z.natural().min(0).max(5).default(0),
8094
// 编码记忆蒸馏(codingRetrospect,opt-in,默认关)。开启时,turn/end 蒸馏
8195
// 额外提取三类编码专属记忆:rejected_solution(被否决方案)/ pitfall(踩坑)/
8296
// constraint(工程约束)。蒸馏上下文为整轮完整对话(用户输入 → 助手思考/回答

‎dsh-mneme/lib/guide.js‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
// #249(第一批):能力说明——写给模型的「怎么用这套记忆」,不是给用户的文案。
2+
//
3+
// 为什么英文、且只留一份正本:注入指引的参照实现全部用英文(ACP 的
4+
// ACP_SYSTEM_PROMPT + HOW_TO_COMPRESS_RULES、mnemon 的 ROUTING_GUIDANCE、
5+
// 宿主压缩摘要规则),仓库既有先例也是 src/tools.js 的工具描述硬编码英文。
6+
// src/lang.js 的 memory.language 管的是「生成出来的记忆内容与块内标题」,与本
7+
// 模块是两件事,故不并入 STR、不做 zh/en 双写(双写只会让两份文本日后漂移)。
8+
//
9+
// 两个承载位(#249 §5):①工具描述——常驻、零注入成本,放「何时用这个工具」
10+
// 这类单工具指引(TOOL_GUIDE);②系统提示段 order 150——放工具描述装不下的
11+
// 总则(优先序、何时查 / 何时写 / 何时 no-op)。该段必须同会话内稳定,否则
12+
// 每轮变化会作废其后的前缀缓存,因此这里全是常量,不含任何运行时插值。
13+
//
14+
// 前缀 `[dsh-mneme memory]` 是机械校验用的:测试按它断言「只在开时出现、且不
15+
// 逐轮复读」,也让维护者能一眼认出这段文本的归属。
16+
17+
const SECTION_LINES = [
18+
"[dsh-mneme memory] Read once; it applies to every turn of this session.",
19+
"1. Precedence: the current instruction and the repository's actual state outrank any stored memory. " +
20+
"When a memory contradicts either, call memory_search to verify before relying on it, and never treat an old memory as current fact.",
21+
"2. Recall on demand: call memory_search when the task depends on earlier decisions, user preferences, or project history " +
22+
"that is not already in context. Do not search for facts you can read directly from the repository.",
23+
"3. Write back sparingly: use memory_save for durable, cross-session value — a preference, a decision with its rationale, " +
24+
"an engineering constraint, a pitfall with its root cause. Trivial single-turn work is not worth a memory.",
25+
"4. When unsure, do nothing. Not acting is a valid outcome: a useless memory is paid for by every future session.",
26+
"5. Prefer the reversible tools. memory_archive hides an entry and memory_forget only stops it being injected — both are " +
27+
"recoverable. memory_delete is permanent, so reach for it only when an entry is wrong or unwanted, not merely stale."
28+
];
29+
30+
/** 系统提示段(order 150)的总则文本。常量:同会话内稳定是硬约束。 */
31+
export const MEMORY_GUIDE_SECTION = SECTION_LINES.join("\n");
32+
33+
/** 单工具判断指引,追加到对应工具描述尾部(`injectGuidanceEnabled` 开启时)。 */
34+
export const TOOL_GUIDE = {
35+
memory_search:
36+
" Use this when the task depends on earlier decisions, preferences, or project history that is not already in context, " +
37+
"and to verify a memory that contradicts the current instruction or the repository's actual state. " +
38+
"Skip it for facts you can read directly from the repository.",
39+
memory_save:
40+
" Save only durable, cross-session value (a preference, a decision with its rationale, an engineering constraint, " +
41+
"a pitfall with its root cause). Trivial single-turn work does not belong here, and when unsure it is correct to save nothing."
42+
};

‎dsh-mneme/lib/inject.js‎

Lines changed: 36 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import { createScopeResolver } from "./scope.js";
22
import { createHotMemory } from "./hot-memory.js";
33
import { STR, langOf } from "./lang.js";
4+
import { MEMORY_GUIDE_SECTION } from "./guide.js";
45
import { adaptiveInjectBudget } from "./search/adaptive.js";
56

67
// Best-effort extraction of the current user's latest message text from the
@@ -144,6 +145,10 @@ export function createInjector(ctx, service, settings, config) {
144145
// stale 1500) and an entry that would exceed it collapses to its title only.
145146
const maxContent = config.injectContentMaxChars ?? 300;
146147
const MAX_BLOCK = Math.max(1500, maxContent + 600);
148+
// #249 第一批:pin 条目的正文硬顶。逐字保真不等于无界——单条上限取
149+
// injectContentMaxChars 与 2000 的较大者,默认档下约束/偏好不会因常规截断
150+
// 失真,同时给「一条超长约束每轮吃满常驻段」留一道闸(超顶仍带截断提示)。
151+
const PINNED_CONTENT_MAX = Math.max(maxContent, 2000);
147152

148153
// Compressed injection (v0.5.0 2.1): a sleep-demoted row already carries its
149154
// summary in `content` with the original parked in `_full_content` — inject
@@ -193,26 +198,36 @@ export function createInjector(ctx, service, settings, config) {
193198
return escapePromptVars(STR.hotHeader[language](rounds.length, body));
194199
}
195200

196-
function render(candidates) {
201+
function render(candidates, pinnedStats = null) {
197202
if (!candidates.length) return "";
198203
const header = STR.memoryHeader[language];
199204
const lines = [header];
200205
let budget = MAX_BLOCK - header.length;
201-
for (const m of candidates) {
206+
// #249 第一批:pin 池(约束/偏好)排在块头且不参与块的塌缩预算——「与情景
207+
// 日志抢同一份预算后被降级」正是本议题要修的结构缺陷。单条仍有硬顶
208+
// (PINNED_CONTENT_MAX),超出照旧带截断提示,不静默。
209+
const pinnedCount = Math.max(0, Math.min(candidates.length, pinnedStats?.shown ?? 0));
210+
for (let i = 0; i < candidates.length; i++) {
211+
const m = candidates[i];
212+
const pinned = i < pinnedCount;
202213
// Epistemic trust (v0.4.5): when enabled, measured observations are
203214
// flagged so the agent can weigh them above guesses/opinions.
204215
const verified = config.trustEpistemicWeighting === true && m.epistemic_status === "observation"
205216
? STR.verified[language]
206217
: "";
207218
const title = STR.entryTitle[language](m.title, m.importance);
208-
const content = injectMemory(m);
219+
const content = injectMemory(m, pinned ? PINNED_CONTENT_MAX : maxContent);
209220
const full = STR.entryLine[language](m.type, verified, title, content);
210-
if (budget - full.length >= 0) {
221+
if (pinned || budget - full.length >= 0) {
211222
lines.push(full);
212223
budget -= full.length;
213224
} else {
214225
lines.push(`- [${m.type}] ${verified}${title}`);
215226
}
227+
if (pinned && i === pinnedCount - 1) {
228+
const hidden = Math.max(0, pinnedStats?.suppressed ?? 0);
229+
if (hidden > 0) lines.push(STR.pinnedOverflow[language](hidden));
230+
}
216231
}
217232
return escapePromptVars(lines.join("\n"));
218233
}
@@ -251,7 +266,17 @@ export function createInjector(ctx, service, settings, config) {
251266
return escapePromptVars(lines.join("\n"));
252267
}
253268

269+
// #249 第一批:能力说明的系统提示段。order 150 = 插件指引段的既有惯例
270+
// (ACP 的 ACP_SYSTEM_PROMPT 与 mnemon 的 routing 段都在 150)。文本是常量、
271+
// 同会话内不随轮次变化,故不影响其后的前缀缓存,也不逐轮复读。宿主若不提供
272+
// section seam 就静默跳过——#249 §3 的口径是「只用现成 seam,拿不到位的语义
273+
// 降级处理」:能力说明仍落在工具描述上,不算失败。
274+
const guideSection = config.injectGuidanceEnabled === true && typeof ctx.systemPrompt?.section === "function"
275+
? ctx.systemPrompt.section({ name: "memory-guide", order: 150, text: MEMORY_GUIDE_SECTION })
276+
: null;
277+
254278
const disposers = [
279+
...(guideSection ? [guideSection] : []),
255280
ctx.systemPrompt.context({
256281
name: "memory",
257282
order: 90,
@@ -277,14 +302,18 @@ export function createInjector(ctx, service, settings, config) {
277302
const maxItems = config.injectUncertaintyAdaptive === true
278303
? adaptiveInjectBudget(query, baseMaxItems)
279304
: baseMaxItems;
280-
const candidates = service.injectCandidates({ query, queryVector, maxItems, threshold, scope, rotate, rotateWindow: rotationTurns });
281-
recordInjection(sessionId, query, candidates);
305+
// #249 第一批:pin 池统计走可选出参,不动 injectCandidates 的数组契约。
306+
const pinnedStats = {};
307+
const candidates = service.injectCandidates({ query, queryVector, maxItems, threshold, scope, rotate, rotateWindow: rotationTurns, pinnedStats });
308+
// #249:pin 条目不进轮换历史——它们每轮固定前置,记进去只会占满轮换
309+
// 窗口、挤掉情景候选的新鲜度(验收:pin 不参与跨轮轮换)。
310+
recordInjection(sessionId, query, pinnedStats.shown > 0 ? candidates.slice(pinnedStats.shown) : candidates);
282311
// Hot memory (v0.5.0 1.3) leads the single memory block: the agent
283312
// sees the short-term rounds first, then the cross-session recall —
284313
// the documented injection order 1→2. Folding it here (instead of a
285314
// separate context) keeps the prompt assembly stable at two blocks.
286315
const hotText = renderHotContext(ctx);
287-
const body = render(candidates);
316+
const body = render(candidates, pinnedStats);
288317
if (!hotText) return body;
289318
return body ? `${hotText}\n\n${body}` : hotText;
290319
}

‎dsh-mneme/lib/lang.js‎

Lines changed: 6 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)