Skip to content

Commit aa5eeb4

Browse files
authored
Merge pull request #266 from heptaspirit/feat/249-inject-first
feat(inject): 能力说明 + 约束/偏好分池逐字保真(issue #249 第一批)
2 parents 54b6566 + 5dac721 commit aa5eeb4

19 files changed

Lines changed: 520 additions & 46 deletions

‎dsh-mneme/CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
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**。
78
- **注入预览(issue #179)**:面板状态页新增「注入预览」卡——展示最近一帧 prompt 组装实际注入了什么:条目构成(类型/标题/重要性/字符数)、hot memory 与总体积、生效参数(maxItems / threshold / 自适应条数 / scope / 轮换抑制)。实现走旁路快照:`src/inject.js` 在真实渲染路径上缓存同一份候选与最终文本(`getInjectionSnapshot()`,不二次检索、零额外开销),`GET /api/dsh-mneme/inject-preview` 只读透传,无快照(autoInject 关闭 / 新会话 / 旧宿主)整卡退化为「暂无预览」不猜;注入器卸载即清空快照,不跨生命周期存留。与 #182 的「极简模式注入关闭」提示卡同区呈现,状态页至此覆盖注入可观测性两端:为什么没注入(minimal 压制)+ 注入了什么(本卡)。另含 #178 无障碍批次一(面板 aria-live 播报网络 / 状态卡语义标题 / 弹层焦点圈 / 冲突按钮可区分标签 / ego 图摘要,对比度审计待宿主主题联调)。
89

910
- **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)。

‎dsh-mneme/lib/client.js‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -325,6 +325,8 @@ window.__ModuleLoader__.load({
325325
"memory.features.loadFailed": "加载失败",
326326
"memory.features.autoInject": "自动注入",
327327
"memory.features.autoInject.hint": "每轮对话自动携带相关记忆",
328+
"memory.features.injectGuidanceEnabled": "能力说明",
329+
"memory.features.injectGuidanceEnabled.hint": "在工具描述与一次性提示段里说明怎么用记忆(何时查、何时写、拿不准就不做)",
328330
"memory.features.autoSummarize": "自动总结",
329331
"memory.features.autoSummarize.hint": "对话结束自动提炼记忆条目",
330332
"memory.features.hotMemoryEnabled": "热记忆",
@@ -701,6 +703,8 @@ window.__ModuleLoader__.load({
701703
"memory.features.loadFailed": "Failed to load",
702704
"memory.features.autoInject": "Auto injection",
703705
"memory.features.autoInject.hint": "Carry relevant memories into every turn",
706+
"memory.features.injectGuidanceEnabled": "Capability guide",
707+
"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",
704708
"memory.features.autoSummarize": "Auto summarization",
705709
"memory.features.autoSummarize.hint": "Distill memory entries when a conversation ends",
706710
"memory.features.hotMemoryEnabled": "Hot memory",
@@ -1824,7 +1828,7 @@ window.__ModuleLoader__.load({
18241828
// 不被专业项淹没。429 调速器参数、distillMaxChars、codingBoostFactor
18251829
// 属调优噪音,按对齐结论留在配置文件,不上 UI。
18261830
const FEATURE_GROUPS = [
1827-
{ key: "group.core", items: ["autoInject", "autoSummarize", "hotMemoryEnabled", "memoryQualityFilter.enabled", "llmAudit.enabled"] },
1831+
{ key: "group.core", items: ["autoInject", "injectGuidanceEnabled", "autoSummarize", "hotMemoryEnabled", "memoryQualityFilter.enabled", "llmAudit.enabled"] },
18281832
{ key: "group.enhance", items: ["entityExtractionEnabled", "codingRetrospect", "rerankEnabled", "resilientModelDownload", "searchSemanticDedup", "bm25SearchEnabled", "heatEnabled", "documentMemoryEnabled"] },
18291833
{ key: "group.dream", items: ["autoDream", "sleepModeEnabled"] },
18301834
// 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: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
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, check the instruction or the repository itself before relying on it — memory_search " +
21+
"searches stored memories only, so it finds earlier context, never the present state. Never treat an old memory as current fact.",
22+
"2. Recall on demand: call memory_search when the task depends on earlier decisions, user preferences, or project history " +
23+
"that is not already in context. Do not search for facts you can read directly from the repository.",
24+
"3. Write back sparingly: use memory_save for durable, cross-session value — a preference, a decision with its rationale, " +
25+
"an engineering constraint, a pitfall with its root cause. Trivial single-turn work is not worth a memory.",
26+
"4. When unsure, do nothing. Not acting is a valid outcome: a useless memory is paid for by every future session.",
27+
"5. Prefer the reversible tools. memory_archive hides an entry and memory_forget only stops it being injected — both are " +
28+
"recoverable. memory_delete is permanent, so reach for it only when an entry is wrong or unwanted, not merely stale."
29+
];
30+
31+
/** 系统提示段(order 150)的总则文本。常量:同会话内稳定是硬约束。 */
32+
export const MEMORY_GUIDE_SECTION = SECTION_LINES.join("\n");
33+
34+
/** 单工具判断指引,追加到对应工具描述尾部(`injectGuidanceEnabled` 开启时)。 */
35+
export const TOOL_GUIDE = {
36+
memory_search:
37+
" Use this when the task depends on earlier decisions, preferences, or project history that is not already in context, " +
38+
"or to look for a newer memory behind one that seems stale. " +
39+
"Skip it for facts you can read directly from the repository.",
40+
memory_save:
41+
" Save only durable, cross-session value (a preference, a decision with its rationale, an engineering constraint, " +
42+
"a pitfall with its root cause). Trivial single-turn work does not belong here, and when unsure it is correct to save nothing."
43+
};

0 commit comments

Comments
 (0)