dsh-memu-memory 1.1.3 → 1.2.0

package/docs/binding-lifecycle.md

@@ -0,0 +1,99 @@
+# 绑定生命周期 — dsh-memu-memory
+
+> 本文对应 W9 只读诊断。实现：`lib/binding-diagnostics.js`；CLI：`scripts/diagnose-bindings.mjs`；测试：`tests/binding-diagnostics.test.mjs`。诊断只读取磁盘上的持久层，不创建、不修复、不删除、不 GC、不写回。
+
+## 12. 绑定生命周期
+
+### 12.1 三层状态：哪些在磁盘上，哪些只在进程里
+
+一个会话的记忆状态分成三层。只有第一层能被另一个进程从磁盘读到，后两层由运行中的插件进程持有；诊断报告把后两层明确标成不可观察，而不是猜成 0。
+
+| 层 | 内容 | 生命周期 | 诊断可见性 |
+|---|---|---|---|
+| 1. 持久绑定 | `state.json` 的 `sessions[sessionId]`：`scopeKey`、`libraryId`、开关、`memoryContext`、`inbound.pending/seen/claimed/clock`、`sleepRetryAt`、注入标记等 | 跨重启、fork、插件重载保留；只有显式状态写入才改变 | 只读快照可读；报告的核心对象 |
+| 2. 运行时监听器 | `lib/preset-scope.js:19` 的 `attachments`，按 **agent context 对象** 键控 | 随 context 存在；context 被替换时旧监听器应释放，下一次 attach 重新挂载 | 跨进程不可读，声明为 `runtime-listener` |
+| 3. 临时映射/缓存 | `lib/inbound.js:12-14` 的 `mediaJobs`/`calls`/`sessions`、`lib/media.js:19` 的 `captures`、`lib/private.js:213` 的 `inFlight`、`lib/curator.js:11` 的 `jobs`、`lib/state.js:938` 的 `indexCache`、`lib/paths.js:52` 的 `readFailures` | 随 promise settle、turn/end、session/disposed、下一次成功读取或下一次加载清理 | 跨进程不可读，声明为 `temporary-map` 或 `cache` |
+
+**三层不混算。** `summary.bindings`、`summary.inbound`、`summary.unfinished` 只统计持久绑定；`summary.runtime` 只在调用方提供了进程内快照时出现，分别是 `runtimeListeners` 和 `temporaryMaps` 的合计。runtime 计数不会加进 binding 数，也不会把“持久层零候选”解释成“运行时没有残留”。同一份 state 在提供/不提供 runtime 快照时，`bindings` 与 `candidates` 必须完全一致。
+
+`RUNTIME_STATE` 里的 `file:line` 是诊断契约的一部分。测试会逐条打开源文件、检查对应行确实声明了该名字；源文件移动后必须同步更新 `RUNTIME_STATE`，否则测试直接失败，避免报告印出过期位置。
+
+### 12.2 生命周期各阶段
+
+- **首次绑定**：会话第一次进入记忆流程时创建 `sessions[sessionId]`。同一 `sessionId` 重连只复用这一条绑定，不按标题、不按 agent 实例、不按时间新建。文件级重复读取也必须幂等：同一 `state.json` 连续诊断两次，`bindings` 与 `candidates` 相同，字节和 mtime 不变。
+- **开关打开但还没有库**：`useLibrary: true` 且 `libraryId: null` 本身不是故障。文件夹没有库时，注入路径用 `createLibrary: false` 延迟创建，这是文档化的形状。只有快照里存在“完成过注入”的证据（`injectedIds` 非空或 `lastInjectedTurn > 0`）时，才把 `library-enabled-but-unbound` 作为候选；否则只计入 `unbound-basis-unknown` 未知项，不虚增候选。
+- **ctx 替换**：agent context 被替换只影响第 2 层监听器，不应改写 `sessions[sessionId]`。替换前后持久绑定的 `bindings`、队列、作用域和候选必须相同；变化只出现在 runtime 的 `presetAttachments` 计数上。
+- **同标题不同 id**：标题只是标签，`sessionId` 才是身份。两个会话可以标题完全相同但一个是已绑定、一个是未绑定；`sameTitleGroups` 会把它们放在同一组，给出 `bound` 数量、各自的 `libraries`（未绑定位置为 `null`）、`mergeable: false`、`identity: "sessionId"`，并且从不输出标题原文。诊断不会因为标题相同就合并、复制或删除绑定。
+- **预设消失又出现**：`agents` 是活 agent 视图，只能证明“在场”，不能证明“缺席”。预设从列表消失时 `host.status` 变为 `partial`（或 `not-loaded`），`host-session-missing` 被扣住；绑定、作用域和待注入队列原样保留。预设回来时仍是同一条绑定，不产生重复。
+- **删除会话**：睡眠整理报告会话已删除时，绑定保留并打上 `sessionGone`。这是“保留以便恢复”的标记，不是删除指令。若宿主会话注册表同时权威地不列出该 id，会额外出现 `host-session-missing`；它是两个独立事实，和 `pending-inbound` 可以同时存在。作用域、`libraryId`、待注入消息都不因删除标记而丢失。
+- **恢复会话**：同一 `sessionId` 恢复后，`sessionGone` 应为 `false`，绑定继续使用原来的库、作用域和队列；诊断只观察这个状态，不负责清除标记，也不写回。恢复后的候选只剩仍然存在的独立事实（例如队列里的待注入消息）。
+- **宿主查询失败**：`host` 缺失、`not-loaded`、`partial`、空权威列表、活 agent 列表或未知来源都不能推出“会话不存在”。报告保留全部绑定、`libraryId`、`memoryContext.scopeKeys`、`inbound.pending`，只增加 `host-unavailable`/`host-not-loaded`/`host-partial` 等未知项，绝不下发 `host-session-missing` 删除信号。
+- **库指针异常**：`libraryId` 指向不存在的库时报告 `library-missing`，但不改写指针；库被归档时报告 `library-archived`，但归档库仍在磁盘上，不等于可以解绑。
+
+### 12.3 诊断字段
+
+`diagnoseBindings()` 返回一个 JSON-safe 报告：
+
+| 字段 | 含义 |
+|---|---|
+| `schema` | `dsh-memu-memory/binding-diagnostics@1` |
+| `generatedAt` | 报告生成时刻（由 `now` 决定，便于测试） |
+| `readOnly` / `mode` | 固定 `true` / `report-only` |
+| `refusals` | 明确拒绝的动作：`gc`、`delete-binding`、`delete-session`、`delete-library`、`write-state` 等 |
+| `thresholds` | `{ idleInspectionDays: 30, idleIsDeletionTrigger: false }` |
+| `state` | 快照文件 `file`、`status`（ok/missing/corrupt/unreadable）、`bytes`、`mtimeMs`、`sha256` |
+| `analysis` | 文件不可读时为 `null`；可读时为下面的分析对象 |
+| `unknowns` | 不可观察或不可判定的项，带 `code`、`detail`、`keeps` |
+| `readOnlyProof` | 读取前后的 sha256、字节数、mtime 对比和 `unchanged` |
+
+`analysis.summary` 的计数：`bindings`、`host`（status/source/complete/sessions/unboundHostSessions）、`switches`、`libraries`、`memoryContext`、`guide`、`inbound`、`sleep`、`unfinished`、`runtime`（无进程内快照时为 `null`）、`candidates`、`sameTitleGroups`。
+
+每个 `analysis.bindings[]`（由 `bindingFacts` 产生）包含：`sessionId`、`switches`、`effective`、`folder`（仅 `scopeKeyHash`，不含路径）、`domain`、`library`、`memoryContext`（仅 `present` 和 `scopeKeys`）、`guide`、`inbound`、`sleep`、`recall`、`injection`、`activity`。`activity` 同时给出精确的 `idleMs` 和仅用于展示的 `idleDays`（四舍五入到 1 位小数）。默认不输出错误原文；`--redact` 时连 session id 也做伪名化，标题和文件夹路径从不输出。
+
+每个候选形如 `{ sessionId, kind, inspectionOnly: true, action: "inspect", reason, evidence }`。候选种类包括 `session-gone`、`host-session-missing`、`library-missing`、`library-archived`、`library-enabled-but-unbound`、`pending-inbound`、`sleep-retry`、`recall-degraded`、`reinject-pending`、`idle-inspection`。**候选是“请人工看一眼”的提示，不是删除队列。**
+
+`analysis.runtime`：调用方提供进程内快照时为 `{ status: "provided", source, layers }`；未提供时为 `{ status: "unknown", reason, layers }`，其中 `layers` 仍列出 `RUNTIME_STATE` 声明的层，但不含任何进程内计数。
+
+### 12.4 30 天阈值：检查线，不是删除触发器
+
+`INSPECTION_DAYS = 30`。只有 `activity.idleMs > 30 * 24 * 60 * 60 * 1000` 才产生 `idle-inspection` 候选；**恰好 30 天不报，超过 1 毫秒才报**。判定使用精确毫秒 `idleMs`，`idleDays` 只用于展示，不能反过来参与比较。
+
+这条线只回答“要不要人工检查”。它不会：
+
+- 删除会话、绑定、记忆或库；
+- 自动解绑或清空待注入队列；
+- 重置 `sleepRetryAt`、`lastTurnAt` 或其他时间戳；
+- 触发 GC、flush、mark-injected 或任何状态写入。
+
+报告的 `thresholds.idleIsDeletionTrigger` 固定为 `false`，`REFUSALS` 固定包含 `gc` 与各类删除动作。即使报告里出现 `idle-inspection`，也只是提示。
+
+### 12.5 自动 GC 必须另行确认
+
+W9 的交付范围是只读诊断，**不包含自动 GC**。将来若要做自动回收，必须作为独立工作包另行获得用户确认，并至少满足：
+
+1. 宿主权威确认目标会话确实已删除，而不是仅凭标题、超时或本地快照推断；
+2. 有可恢复的备份，且备份本身不被同一次清理覆盖；
+3. 在事务中重读最新状态、重新校验绑定与队列，避免用过期快照删除新数据；
+4. 留下可审计记录，说明删了什么、依据是什么、如何恢复；
+5. 永不删除记忆库本身，永不丢失 `inbound.pending`，恢复会话时永不丢失作用域。
+
+在这些条件满足前，诊断报告只做候选标记；任何“清理”“解绑”“删库”都需要用户显式操作。
+
+### 12.6 CLI 与只读证据
+
+```bash
+node scripts/diagnose-bindings.mjs --state <state.json> [--json] [--redact] [--now <ISO>]
+```
+
+退出码：
+
+| 码 | 含义 |
+|---|---|
+| 0 | 成功生成报告，没有检查候选 |
+| 1 | 成功生成报告，有检查候选（仍只是提示，没有改动任何东西） |
+| 2 | 用法错误（未知参数、非法 `--now`） |
+| 3 | 没有报告：state.json 缺失、损坏或不可读；没有创建目录、没有修复文件 |
+
+CLI 只写 stdout/stderr。它不创建父目录，不创建缺失的 `state.json`，不隔离损坏文件，不更新时间戳；文本报告会打印 `readOnlyProof`。测试覆盖 0/1/2/3 四种退出码、缺失路径不建目录、已有文件字节与 mtime 不变。
+
+`readBindingSnapshot()` 直接 `fs.readFileSync`，不调用会修复文件的 `loadState()`；`diagnoseBindings()` 在分析后再哈希一次并比较 mtime，形成 `readOnlyProof`。缺失或损坏时 `analysis` 为 `null`，报告只说明状态并保持现场。

package/docs/contributing.md

@@ -125,7 +125,7 @@ npm run check                        # node --check + i18n 键对齐 + package.j
 - [ ] `injectedIds` 记的是**真正进入文本**的条目？（§8.4）
 - [ ] token 预算走 `lib/budget.js`，没有 `tokens * 3`？（§8.4）
 - [ ] `pending_review` 被挡在注入与召回之外？（§3.9）
-- [ ] 没有每步注入、动态记忆没进 system prompt？（§1.3、§1.4）
+- [ ] 没有每步注入、记忆规则与动态记忆都没进 system prompt？
 
 **数据安全**
 - [ ] 读失败没被当成空数据（改名 `*.corrupt-<ts>` + 拒绝写入）？（§2.3 铁律一）

package/docs/emotion-model-spec.md

@@ -0,0 +1,281 @@
+# 情绪模型改造方案：四项构成与双辅助轴
+
+状态：**已实施（P0–P3）**，WebUI 只读展示随 P2 落地  
+版本：v3（2026-10-30）  
+适用范围：私有记忆的本地情绪读取、记忆写入与召回排序；不扩展全局记忆。
+
+> 本文仍是目标契约：实现应与本文一致；不一致时以本文为准并修实现。实施结果与三处已修正的偏差见 §10。
+
+## 1. 目标与边界
+
+### 1.1 目标
+
+1. 在不调用模型的前提下，把当前单一 valence 扩展为四项情绪构成、arousal 和 dominance。
+2. 保留现有 valence 读写兼容性，并为旧条目提供确定的降级路径。
+3. 让情绪对召回的影响有界、可关闭、可回归测试。
+4. 让后台整理、远程整理和前台写入明确区分情绪来源。
+
+### 1.2 非目标
+
+- 不给全局记忆增加情绪字段。
+- 不把情绪写入注入文本或记忆正文。
+- 不改变 peak、confidence、accuracyOf、negativityBias 的既有语义。
+- 不引入模型调用或真实模型标注作为运行时依赖。
+- 不在本阶段制作 WebUI 编辑控件；读取展示可以在后续阶段加入。
+
+## 2. 当前实现事实
+
+在开始实现前，以代码为准的现状是：
+
+| 位置 | 当前行为 |
+|---|---|
+| lib/mood.js:29-71 | readMood、moodDecay、moodCongruence 只处理 valence/arousal |
+| lib/state.js:893-900 | 会话 mood 只保存 valence/arousal/at |
+| lib/memory.js:1135-1141 | 条目只写入 moodValence/arousal |
+| lib/tools.js:190-193,309-320 | 工具尚无 emotion/dominance 参数 |
+| lib/prompts.js:85-90 | 远程 JSON 契约尚无 emotion 字段 |
+| lib/remote-summary.js:15-40 | 远程解析只保留现有 mood 字段 |
+| lib/rpc.js:87-90 | RPC 只投影 moodValence/arousal |
+
+本文中的路径和行号只用于定位现状；实现时应按符号搜索，不依赖固定行号。
+
+## 3. 规范化数据契约
+
+### 3.1 情绪构成
+
+使用四个固定轴：joy、anger、sorrow、fear。
+
+有效的非空 emotion 满足：
+- 四个键都存在；值必须是有限数。
+- 每个值必须大于等于 0。
+- 四项之和必须大于 0；写入前归一化到和为 1。
+- 归一化误差要求 abs(sum - 1) < 1e-9。
+
+emotion: null 是规范的中性表示。为了兼容工具调用，显式全零对象也接受，但在校验后规范化为 null；它不能被当作四轴全都有少量情绪。
+
+非法输入必须拒绝并在错误中包含 emotion：缺键、非有限数、负数、数组、字符串和非正和都不能静默修复。实现可对极小浮点误差使用固定容差，但不得把负数 clamp 成合法值。
+
+### 3.2 强度与掌控感
+
+| 字段 | 范围 | 缺失默认 | 说明 |
+|---|---:|---:|---|
+| arousal | 0..1 | 0.35 | 情绪激活程度；显式 0 保留为 0 |
+| dominance | -1..1 | 0 | 主动/失控程度；显式 0 保留为 0 |
+
+缺失和显式值必须区分：缺失使用默认值，显式 arousal: 0 或 dominance: 0 不得被 || 覆盖。
+
+内部存储、工具和远程协议统一使用字段 dominance，不再引入 mood_dominance。若未来必须兼容该别名，只能在输入边界映射一次，内部和输出只保留 dominance。
+
+### 3.3 记忆条目字段
+
+| 字段 | 类型/范围 | 说明 |
+|---|---|---|
+| emotion | 四轴对象或 null | 事件的情绪构成 |
+| arousal | 0..1 | 事件激活程度 |
+| dominance | -1..1 | 事件中的主动/失控程度 |
+| emotionSource | model/session/content/unknown | 系统审计字段 |
+| moodValence | -1..1 | 派生的旧路径兼容投影 |
+| peak | boolean | 保持现有语义 |
+
+emotionSource 不属于普通用户可编辑字段：model 表示工具参数显式提供；session 表示允许继承当前会话 mood；content 表示从记忆正文读取；unknown 表示没有足够证据。
+
+旧条目没有 emotion 时保持原样，不从旧 valence 反推四轴。
+
+## 4. 本地读取算法
+
+### 4.1 readMood 返回值
+
+返回值必须继续包含 valence，并追加目标字段：
+
+{ valence, emotion, arousal, dominance }
+
+现有否定预处理必须保留。实现建议按句切分，在每句内取各轴的最大命中权重，再按规则合并；不得继续使用会把多个命中平均到接近中性的旧算法。
+
+- 缓和词按所在分句生效：有点、稍微、一点点、a bit、somewhat。
+- 一点都、一点也不、一点也没不属于缓和词。
+- 强度词和重复标点可以提高 arousal，但必须有明确上限。
+- 未命中可靠情绪词时返回 emotion: null，而不是强行生成均匀分布。
+
+### 4.2 dominance
+
+初始实现采用可解释的词表加构成先验：
+
+dominance = clamp(lexicalDominance + 0.4 * (anger - fear), -1, 1)
+
+词表中存在歧义词时，不能把结果宣称为事实；dominance 只作为有界排序辅助。词表测试必须覆盖高控制、低控制、怒和惧的相反方向。
+
+### 4.3 派生 valence
+
+必须先确定并测试纯轴结果，再实现公式。v3 采用以下固定系数：
+
+raw = 0.8 * joy - 0.8 * anger - 0.8 * sorrow - 0.8 * fear
+moodValence = clamp(raw, -1, 1)
+
+这保证四个纯负轴都为负，纯喜为正；emotion 的构成仍由四轴本身表达，valence 只是旧路径的兼容投影。所有纯轴和代表性复合轴都必须有单元测试，不能同时保留与该结论冲突的经验公式。
+
+### 4.4 衰减
+
+情绪构成不按比例衰减；强度和掌控感衰减回基线：
+
+fade = 0.5 ** (minutes / 90)
+arousal = 0.35 + (arousal - 0.35) * fade
+dominance = dominance * fade
+
+当 fade < 0.35 时，emotion 变为 null。边界是严格小于；fade === 0.35 仍保留构成。即使 emotion 变为 null，arousal 和 dominance 仍返回并继续衰减。
+
+## 5. 召回语义与兼容降级
+
+### 5.1 新路径
+
+双方都有合法 emotion 时：
+
+overlap(p, q) = sum(min(p[i], q[i]))
+moodBias = 1 + 0.3 * fab * (2 * overlap - 1)
+
+moodBias 必须限制在 [0.7, 1.3]。dominance 双方都有有限值时：
+
+domBias = 1 + 0.2 * (0.5 - abs(entry.dominance - context.dominance) / 2)
+
+domBias 必须限制在 [0.9, 1.1]。任一 dominance 缺失或非法时，domBias 必须为 1，而不是传播 NaN。
+
+### 5.2 旧路径
+
+读路径必须使用唯一分流：
+1. 双方都有合法 emotion：使用 overlap；
+2. 否则双方都有可用 legacy valence：使用既有 moodCongruence/fadedValence；
+3. 否则：情绪乘数为 1。
+
+旧条目不反推 emotion。新字段接入召回后，必须验证旧条目、旧会话 mood 和缺失字段不会产生 NaN。
+
+### 5.3 门控
+
+门控是三条独立条件的 OR：
+
+emotionActive = (emotion !== null && maxShare(emotion) >= 0.35) || abs(arousal - 0.35) >= 0.1 || abs(dominance) >= 0.25
+
+emotion === null 只会关闭第一条，不会关闭 arousal 或 dominance 两条。必须测试 null+高 arousal 开启、null+高 dominance 开启、全基线关闭，以及非空低 share。
+
+arousal intensity 代理应使用 max(arousal, maxShare(emotion), legacyValenceProxy, peak ? 1 : 0)；没有 emotion 时只使用旧字段和 arousal。
+
+## 6. 写入、远程和 fork 语义
+
+### 6.1 工具参数
+
+memu_private_remember 和 memu_private_update 使用 emotion: object|null、arousal: number、dominance: number。
+
+工具描述必须说明：emotion 描述记忆所述事件，不是整理时的心情；省略、null、全零的语义分别是继承、明确中性、规范化为 null。对工程事实（owner=about_project）默认使用 null。
+
+更新操作单独定义：省略字段表示保留原值；显式 null 清除 emotion 并将来源设为 unknown；显式对象经过同一套校验和归一化。
+
+### 6.2 远程 JSON
+
+远程协议只输出一个 JSON 对象，字段使用统一名称：
+
+{ memories: [{ title, content, emotion: null, arousal: 0.35, dominance: 0, mood_valence: 0, source: inferred, visibility: shared }] }
+
+visibility 只允许当前代码支持的 shared 或 secret；不得再使用已废弃的 session。远程缺字段时回落到兼容默认；字段存在但非法时应记录可诊断错误并拒绝该条，不静默改成合法情绪。
+
+### 6.3 后台整理 fork
+
+后台 fork 不继承父会话的即时 mood。创建子 binding 时显式使用 mood: null，避免把整理时的心情误写成事件情绪。
+
+写入来源优先级：模型显式 emotion -> model；允许继承且存在 session mood -> session；从该条 content 读取出可靠情绪 -> content；否则 emotion=null、dominance=0、arousal=0.35、source=unknown。工程事实固定使用中性。
+
+## 7. 分期
+
+### P0：本地读取，保持旧 API
+
+只改 lib/mood.js 及其单元测试：四轴词表、校验/归一化、dominance、派生 valence、分句和衰减。返回值追加字段但保留 valence。P0 不是零召回行为变化：inject.js 会把读取结果写入 binding，arousal/valence 变化可能影响后续排序；若产品必须零变化，则 P0 必须由 feature flag 隔离新字段。
+
+### P1：召回
+
+在 lib/memory.js 接入 overlap、domBias、三腿门控和 intensity 代理；保留旧路径。补充 property tests、legacy fixtures 和 NaN 防护。
+
+### P2：写入与协议
+
+更新 state.js、memory.js、tools.js、prompts.js、remote-summary.js、rpc.js。完成 remember/list/update/recall 往返测试，确认缺失字段和旧 index 可读取。
+
+### P3：来源与 fork
+
+更新 private.js、整理提示词和来源审计；验证 fork 不继承即时 mood，验证 emotionSource 不可被普通 update 伪造。
+
+### P4：展示与文档
+
+更新 UI 只读展示、文档和 CHANGELOG。全局、图谱、备份和 active-memory A/B 不属于本功能范围。
+
+## 8. 验收标准
+
+- 有效 emotion 归一后和为 1，所有分量非负。
+- 缺键、负数、非有限数、数组和非法 dominance 被拒绝。
+- 全零输入规范化为 null；null 不生成均匀分布。
+- 四个纯轴的 derived valence 方向正确；复合轴结果可复算。
+- overlap 自反、对称且在 [0,1]；bias 范围始终满足上界。
+- 门控测试覆盖 null、高 arousal、高 dominance 和低 share。
+- decay 在 0.35 两侧有明确、稳定结果。
+- readMood(...).valence 继续存在；旧 setSessionMood({ valence, arousal }) 继续可读。
+- 旧条目无 emotion 时不反推四轴。
+- 远程缺字段可解析，非法字段可诊断拒绝。
+- fork 不继承父即时 mood；工程事实保持中性。
+- remember -> list -> update -> recall 往返保留字段和来源。
+
+项目门禁：node --check changed JS files；npm test 必须 exit 0（允许明确列出的 skipped）；node scripts/acceptance-local.mjs；npm run check；git diff --check。文档中的测试数字不是永久常量，报告必须记录本次实际结果，不得以 fail 0 替代成功退出。
+
+## 9. 风险与默认决策
+
+- 词典推断不是事实识别；dominance 只能作为低权重排序信号。
+- 四轴归一化会丢失强弱，强弱由 arousal 承载。
+- fade < 0.35 有离散边界；实现不得私自改变契约。
+- 远程模型可能输出不符合协议的 JSON；严格校验优先于尽量解析。
+
+默认决策：四轴为 joy/anger/sorrow/fear；保留 valence；dominance 参与 P1 召回；门控阈值 0.35；旧路径至少保留一个版本；WebUI 本轮只读；远程和工具统一使用 dominance。
+
+## 附录 A：初始词表与测试样例
+
+初始词表至少覆盖：
+- joy：开心、高兴、太好了、喜欢、爱、满意、惊喜、谢谢、期待；
+- anger：气、烦、讨厌、气死、烦死、离谱、凭什么、受不了、恨；
+- sorrow：难过、失望、崩溃、委屈、心疼、累、困、没意思；
+- fear：害怕、恐慌、焦虑、担心、紧张、慌、吓死、不敢、万一；
+- compounds：尴尬、嫉妒等必须有明确词条或明确组合规则，不能只出现在测试期望中。
+
+复合预设是可解释的初始建议，不是硬编码事实：
+
+| 表达 | 建议构成 | 建议 dominance |
+|---|---|---:|
+| 委屈 | sorrow 0.70 / anger 0.30 | -0.4 |
+| 尴尬 | sorrow 0.50 / fear 0.50 | -0.5 |
+| 嫉妒 | anger 0.50 / sorrow 0.30 / fear 0.20 | -0.1 |
+| 心疼 | sorrow 0.80 / joy 0.20 | -0.2 |
+| 不甘 | anger 0.60 / sorrow 0.40 | +0.4 |
+
+验收样例必须把期望写成可计算范围：分别统计主导轴准确率、null precision/recall、arousal 误差和 dominance 误差；复合情绪允许 top-2 轴集合匹配并记录容差。
+
+## 附录 B：实施前检查清单
+
+- [ ] 实现并测试 normalizeEmotion、derivedValence、overlap 和门控真值表。
+- [ ] 决定 P0 是否启用 feature flag；不要同时声称改 mood.js 且零召回变化。
+- [ ] 明确 remember/update 的 omitted/null/zero 语义。
+- [ ] 统一远程字段名和 visibility 枚举。
+- [ ] 为旧 index、旧 binding、后台 fork 增加兼容测试。
+- [ ] 以 npm test 退出码作为门禁，不引用过时的 878/取消测试数字。
+- [x] 实现完成后再更新本文状态、版本和变更日志。
+
+## 10. 实施结果（2026-10-30）
+
+| 阶段 | 落地位置 | 结果 |
+|---|---|---|
+| P0 | `lib/mood.js` 重写：四轴词表、`normalizeEmotion`、`derivedValence`（统一 0.8 系数）、`maxShare`、`overlap`、`dominanceBias`、`emotionActive`、分句读取、`moodDecay` 的 0.35 边界 | 完成 |
+| P1 | `lib/memory.js` 召回：overlap 路径 + 旧 valence 回落、dominance 乘数、三腿门控、`arousalBias` 的强度代理纳入 `maxShare` | 完成；`moodBias` 实测边界 0.7 / 1.3 |
+| P2 | `state.js` / `tools.js` / `prompts.js` / `remote-summary.js` / `rpc.js` / `client.js` | 完成；remember → list → update → recall 往返通过 |
+| P3 | `private.js` fork 显式 `mood: null`；四份整理提示词按回合还原情绪 | 完成 |
+| P4 | 文档与只读展示 | 完成；WebUI 编辑控件按 §1.2 不做 |
+
+实现期间发现并修正的三处偏差，记在这里避免重犯：
+
+1. **`derivedValence` 早期草稿把 anger 记成正贡献**，与"四个纯负轴都为负"冲突。统一为 `0.8 * (joy - anger - sorrow - fear)`。
+2. **`emotion: null` 曾在工具层被 `?? null` 与"省略"合并**，导致"明确中性"被会话心情覆盖。现在三态分开：`undefined` = 继承，`null` = 明确中性，全零对象 = 规范化为 null。
+3. **`dominanceBias(null, x)` 曾因 `Number(null) === 0` 返回 1.05**。现在缺失或非法一律返回 1。
+
+验收：`tests/emotion-contract.test.mjs`（17 条，由独立验收者按 §8 编写，不迁就实现）+ 全量 `npm test` 944 / 942 pass / 0 fail / exit 0。
+
+端到端链路验证覆盖 8 条：读取、写入四态来源、持久化、更新三态、召回、旧条目降级、展示与协议、远程清洗；36 项断言全通过。

package/docs/host-api.md

@@ -68,7 +68,7 @@ ctx.inject([sidebarRightTabs], ...) + ctx.slots.register({ name: sidebar.right.p
 
 - 标准会话 `session-<redacted-standard-a>`（`agentPreset: "standard"`，21 个非 session 事件）：模型请求头 `request/header` 的工具表为 **82 个工具**，首尾两次一致；其中 `memu_*` 共 **10 个**：`memu_private_list`、`memu_private_recall`、`memu_private_remember`、`memu_private_update`、`memu_private_archive`、`memu_private_link`、`memu_private_unpin`、`memu_global_list`、`memu_global_recall`、`memu_status`。同一会话中 `===== memory anchor =====` 出现 1 次，锚点内是真实私有 id。
 - 标准会话 `session-<redacted-standard-b>`（`agentPreset: "standard"`，本轮扫描时 1737 个非 session 事件）：`<memory-guide>` 只对应 **1 个** plugin 消息 id（`<redacted-plugin-message-id>`），锚点 1 次。该 id 在多个快照/工具记录里重复出现是日志回放，不是重复投放。
-- 因此“标准会话的工具表里有 `memu_*`”“标准会话 anchor/guide 只投放一次”是**已证实**；标准会话的 guide 走 system prompt 段，不必然出现 `<memory-guide>` 消息。
+- 因此“标准会话的工具表里有 `memu_*`”“标准会话 anchor/guide 只投放一次”是**已证实**。注意这是 2026-10-29 的历史快照：当前版本标准和预设都走 `<memory-guide rules="…">` 插件消息，system prompt 不再有本插件段。
 
 #### 仅机制 + mock：独立人格预设 `yuike`
 
@@ -87,6 +87,6 @@ ctx.inject([sidebarRightTabs], ...) + ctx.slots.register({ name: sidebar.right.p
 - **工具已注册 ≠ 已向当前模型暴露。** 上文的工具名单取自 `request/header.data.header.tools`；没有该字段或只有标题请求的会话，不能拿插件侧注册表冒充模型可见工具。
 - **guide 有 `<memory-guide>` ≠ 有 `memu_*`。** 正文自带“若本会话的工具列表里没有 `memu_*` 工具，请忽略本段”，它只声明规则可用性，不证明工具存在。
 
-复核方法：用 `zlib.zstdDecompressSync` 逐 frame 解压 `~/.dsh/sessions/<bucket>/<id>/session.v4.jsonl.zstd`；只统计 `request/header` 的工具名、`session.v4` 消息 id 和 `<memory-guide>`/`===== memory anchor =====` 标签。不要打印会话正文，不要把同一消息在快照中的重复出现计成多次投放。
+复核方法：用 `zlib.zstdDecompressSync` 逐 frame 解压 `~/.dsh/sessions/<bucket>/<id>/session.v4.jsonl.zstd`；只统计 `request/header` 的工具名、`session.v4` 消息 id 和 `<memory-guide`/`===== memory anchor =====` 标签。不要打印会话正文，不要把同一消息在快照中的重复出现计成多次投放。
 
 ---

package/docs/memory-semantics.md

@@ -28,22 +28,23 @@
 
 ### 8.4 注入
 
-- 静态 guide 默认在 system prompt（按 domain 选变体）；动态记忆走 plugin 消息。`persona` 带 `complete: true` 的预设会把 system prompt 段整段丢弃，这类会话改由**一次性消息**投放：`withGuideMessage`（`lib/inject.js:703`）按 `binding.guideMessageAt` 在**首步**追加一条 `<memory-guide>` 插件消息，会话内只发一次（`:708` 只在 `step === 1` 投放，`:719` 发完写 binding；fail-open，`:721`）；投放的是静态规则，动态记忆仍然不进 system prompt。
+- 静态 guide 与动态记忆都走 plugin 消息；当前版本不再注册本插件的 system prompt 段。所有会话（含 `persona` `complete: true`）统一由 `lib/inject.js` 的 `ensureUnifiedGuide` 在**回合首步**投放一条 `<memory-guide rules="…">` 插件消息；`rulesKey` 由协议版本、domain 和实际渲染正文计算，domain/覆盖/默认稿变化或压缩丢失（`guideLost`）时在下一个合法首步替换，同一规则不逐回合重复。旧 binding 只有 `guideMessageAt`、没有 `guideRulesKey` 时视为旧版，补投一次；失败 fail-open，不写新版本。
 - 首轮锚点 + 每用户回合最多一次；长工具回合仅有新的真实人类消息批次时追加一次，普通工具步骤不触发。私有优先、全局补充；冲突时私有胜。
 - **`injectedIds` 只能记真正进入文本的条目**，否则从未展示的记忆被白白压制 8 轮。
 - 锚点分段预算 pin 40% / core 30% / global 30%；pin 装不下时末尾明示「另有 N 条未展开」，**不静默丢弃**。
 - 预算单位是**模型 token**不是字符：中文 ≈1 字符/token、英文 ≈3.4，一律走 `lib/budget.js`，**不要再用 `tokens * 3`**（英文口径，中文超支约 3 倍）。
 - 压缩后下一条用户消息重注入锚点；子代理不注入。文件夹两开关都关 → 不注入（看 clamp 后生效值，不是 binding 原始值）。召回为空必须留信号（§1.10）。
-- **召回排序的准确口径**：`privateWeighted`（`lib/memory.js:643`）只服务**私有召回流水线**（`privateRecall` 调用它）；全局召回（`globalRecall`，`lib/memory.js:1526`）走 `localRecall`，不经过它。cue 会经 `cueRecall`（`lib/inject.js:124`）**间接**调用 `privateRecall`，所以**不能**概括成「cue 不走私有排序」。心境一致性与唤起窄化**默认关闭**（`moodEnabled: false`，`lib/memory.js:645`），只有 `|valence| ≥ 0.15` 或 `|arousal − 0.35| ≥ 0.1` 才打开（`lib/memory.js:1110`，阈值见 `:75` 与 `lib/mood.js:27`），平缓对话里两项乘数恒为 1。`privateRecall` 的 topK 兜底是「传入 topK → `settings.privateTopK`（默认 5）→ 4」（`lib/memory.js:1107`）：引用 3 或 4 时必须说清是**设置默认值**还是**代码兜底值**，两个数不是同一个。
+- **召回排序的准确口径**：`privateWeighted` 只服务**私有召回流水线**（`privateRecall` 调用它）；全局召回（`globalRecall`）走 `localRecall`，不经过它。cue 会经 `cueRecall` **间接**调用 `privateRecall`，所以**不能**概括成「cue 不走私有排序」。排序里的心境项默认关闭——`privateWeighted` 自己的缺省上下文就是 `moodEnabled: false`，真正打开它的是 `privateRecall`，条件是 `|valence| ≥ MOOD_MIN_STRENGTH` 或 `|arousal − BASE_AROUSAL| ≥ 0.1`（`BASE_AROUSAL` 来自 `lib/mood.js`）；平缓对话里两项乘数恒为 1。`privateRecall` 的 topK 兜底是「传入 topK → `settings.privateTopK`（默认 5）→ 4」：引用 3 或 4 时必须说清是**设置默认值**还是**代码兜底值**，两个数不是同一个。
+- **情绪模型（v3）**：一条记忆的情绪由四项构成 `joy / anger / sorrow / fear`（归一后和为 1）、强度 `arousal` 与掌控感 `dominance` 组成，`moodValence` 只是四轴在旧路径上的兼容投影。门控是三条**独立**条件的 OR：主导项 share ≥ 0.35、`|arousal − 0.35| ≥ 0.1`、`|dominance| ≥ 0.25`——「没有情绪构成」只关掉第一条，高唤起或明确的掌控感仍会打开排序项。双方都有合法 emotion 时用 overlap（各轴取较小值再求和）算一致性，任一侧缺失就回落到旧的 valence 路径；旧条目不从 valence 反推四轴。情绪只影响排序权重，不写进注入文本，也不进记忆正文。
 
 ### 8.5 提示词管理
 
 - 默认稿在 `lib/prompts/*.md`（随包）；用户覆盖在 `~/.dsh/dsh-memu-memory/prompts/*.md`；`manifest.json` 记 `defaultHash / userHash / defaultUpdated`。运行时统一 `lib/prompts.js` 的 `loadPrompt(key, vars)` / `loadPromptForDomain(key, vars, domain)`，**业务代码里不许硬编码正文**。
-- system prompt 的 section `text` 必须是函数（每次装配重读文件，保存后下一轮生效）且**整体包 try/catch**（§3.7）。
+- 规则消息每次首步重新渲染；`rulesKey` 只含版本、domain 和渲染后的正文，不含时间/回合，避免每轮不同。`private-policy` 模板保留供查阅和覆盖记录，但当前版本不再自动投放主会话；字段契约由工具 schema 与运行校验提供。
 - 模板只做单趟 `{{variable}}` 替换，变量值里的 `{{` 不会被二次展开——所以把记忆正文当变量塞进模板是安全的。**改成多趟插值前先想清楚这点。**
 - 恢复默认 = 只删用户覆盖；全部恢复 = 清空覆盖目录。升级后：无覆盖用新默认，有覆盖保留并标 `defaultUpdated`。
 - 分层：**作用域 → 类型页 → 项**。类型页是数据（`settings.promptDomains`，默认 `[rp, coding, mixed]` 全启用；`domainOverride` 默认 `rp`），`general` 内置不可删。变体 `<name>.<domain>.md` 由 `resolveDef` 解析：domain 在列表内且变体文件存在（默认**或**覆盖目录）→ 用变体，否则回落基础稿。
-- **职责分工**：`system-guide.*` 只写领域行为、检索时机、回答口径；字段定义、层级、复核、预算、unpin 只写在 `private-policy.*`。同一规则不要两份都写——重复撑长常驻提示词，改一处还留下另一半旧口径。
+- **职责分工**：`system-guide.*` 是唯一常驻规则，只写领域行为、检索时机、回答口径；`private-policy.*` 保留为字段规约参考，不再投放，避免两套常驻文本互相漂移。
 - **只有三个 key 分域**：`system-guide`、`private-policy`、`private-consolidation`；`global-curator` 不分域。
 - **远程与本地共用一份 `private-consolidation`**：正文讲「记什么、字段怎么填」，差异只有输出协议（`CONSOLIDATION_CONTRACTS.local` 调工具 / `.remote` 返回 JSON，代码追加）。不要拆第二份。
 - RP 与 coding 是**内容**差异：coding 记事实（决定、约束、踩过的坑、工程偏好），召回当「可能过期的事实」，与代码冲突时以代码为准；rp 记经验（具体瞬间、半句原话、身体感觉、没说出口的话），允许模糊记错，不确定就标低 `confidence`。
@@ -88,10 +89,11 @@
 ### 8.9 空闲整理：什么时候跑，以及为什么可以什么都不写
 - 触发：`settings.sleepConsolidation` 开着时，每 5 分钟扫一遍（`lib/cycle.js` 的 `runSleepPass`），挑「`lastTurnAt` 早于 `lastSleepAt` 且已经安静 ≥ `sleepAfterIdleMinutes`」的会话，交给 `requestPrivateConsolidation` 起一个 fork 去读转录、写记忆。**默认 3 分钟**（`lib/state.js` 的 `DEFAULT_SETTINGS`）；旧值 8/20 的安装保留原选择，只是新装默认更短。
 - 应用启动后 8 秒补跑一次（`STARTUP_SWEEP_MS`），因为定时器只在应用开着时存在：一段对话如果是在应用关着的时候结束的，它永远等不到那个「空闲窗口」——用户一回来发消息，`lastTurnAt` 就被顶新了。补偿每次最多处理 **2 个**会话（`runSleepPass` 的 `limit`），按最近活动排序。
-- **有新回合 ≠ 该写记忆。** 进 fork 之前先做一次本地评估（`lib/private.js` 的 `assessConsolidationValue`，只看 `lastSleepSeq` 之后的转录）：①没有任何人类消息（只有插件通知、工具结果、心跳）→ 跳过；②只有一条**纯应答**（「谢谢」「好的」「ok」「收到」，且没有任何工具调用）→ 跳过。**这里刻意不按字数判断**：字数少的偏好句（「我不吃香菜」）比一千字的闲聊更该留，长度是坏代理。其余一律交给 fork——**跳过只是省一次 fork，「该不该留」仍由整理提示词判断**，它完全可以读完写 0 条。宁可多跑一次，也不要在本地猜「这条不重要」。
-- 评估通过但整理写了 0 条 = 正常成功（`lastSleepAt` 前移），不会每小时重来。
-- 会话被删：host 对 `readSession` 报 `session "…" not found`，这是**不变量**而不是瞬时故障。`runSleepPass` 一旦看到就把 binding 标 `sessionGone: true` 并清掉重试计数，此后直接跳过（以前会按 2 的幂退避、封顶 1 小时，永远重试）；同名会话后来真的收到新消息时（`lib/inbound.js`）会清掉这个标记。
-- 手动「整理这场对话」（RPC `generatePrivate`）带 `force: true`，跳过上面那道评估：用户已经决定了。
+- **有新回合 ≠ 该写记忆。** 进 fork 之前先做两道本地评估（只看 `lastSleepSeq` 之后的转录）：① `assessConsolidationValue` 的硬门槛——没有任何人类消息（只有插件通知、工具结果、心跳）→ 跳过；只有一条**纯应答**（「谢谢」「好的」「ok」「收到」，且没有任何工具调用）→ 跳过。**这里刻意不按字数判断**：字数少的偏好句（「我不吃香菜」）比一千字的闲聊更该留，长度是坏代理。② `assessWake` 的加权分（`lib/active-memory.js`）：`H` 真人回合、`C` 真人文字 + 助手正文 + 去重后的成功工具结果（每个结果最多 2000 字符）、`U` 去重后的有效工具单元；`score = 0.35*min(H/3,2) + 0.45*min(C/4000,2) + 0.20*min(U/20,2)`，默认 `activeMemoryMinScore = 0.8`。空闲未到 `activeMemoryStarvationMinutes`（默认 15 分钟）时分数必须达标；到了饥饿阈值，**小于 2000 条事件的会话**无条件唤醒，**大 transcript 不吃饥饿豁免**——fork 的 seed 是整段前缀（真机 5913 条事件约 26MB），宿主虽然会压缩上下文，实测一次整理仍要约 4~22 万 input tokens（含缓存读，主要取决于记忆工具步数）；一个「继续」级薄回合只有 0.14~0.43 分，不能靠饥饿反复付这笔钱；大会话里的密集回合仍按分数正常触发。
+- **近期触发过记忆就不 fork。** `runSleepPass` 先看 `suppressionReason`：距上次整理不足 `activeMemoryCooldownMinutes`（默认 0）或距上次**注入过记忆**不足 `activeMemoryRecallCooldownMinutes`（默认 15 分钟）→ 跳过并发 `check` 日志。被抑制或低分跳过的回合返回 `settled: false`，不推进 `lastSleepSeq`/`lastSleepAt`；下一轮扫描重新评估，等真正有密集新内容再整理。
+- 评估通过但整理写了 0 条 = 正常成功（`lastSleepAt` 前移），不会每小时重来。整理日志额外记录 `scanned/fresh/index +N`（扫描多少事件、上次游标后新增多少、索引实际新增多少），`check` 日志记录 `score/reason/parts/空闲分钟/会话事件数`，用来区分「没触发、被门挡住、提取空转」。
+- 会话被删：host 对 `readSession` 报 `session "…" not found`，这是**不变量**而不是瞬时故障。`runSleepPass` 一旦看到就把 binding 标 `sessionGone: true` 并清掉重试计数，此后直接跳过（以前会按 2 的幂退避、封顶 1 小时，永远重试）；同名会话后来真的收到新消息时（`lib/inbound.js`）会清掉这个标记。**"读不出来"不是"被删了"**：转录读失败（例如 `ENOENT`）由快照层显式标成可重试（`lib/consolidation-snapshot.js` 的 `failed()` → `retryable: true`），`runSleepPass` 只按退避重试、不打 `sessionGone`——`isGoneSessionError` 只认宿主那句 `session "…" not found` / `no such session`。
+- 手动「整理这场对话」（RPC `generatePrivate`）带 `force: true`，跳过上面两道评估与抑制：用户已经决定了。
 
 ---
 
@@ -101,9 +103,9 @@
 
 插件侧的处理（`lib/preset-scope.js`）：每 10 秒枚举 `ctx.get('agents').list()`，沿 `agent.ctx.fiber` 往上找本插件的 fiber——找不到（= 不在自己这棵树里）才在该 agent 自己的 ctx（`lib/preset-scope.js:71` 取 `raw?.ctx || agent?.ctx || agents.get(sessionId)?.ctx`）上补挂 `registerInjection(actx, { guide: false, guideMessage: true })`（`lib/preset-scope.js:79`）。**首参必须是这个 agent 自己的 ctx**，不是部署级实例的 ctx，否则绑定与注入会挂错会话。`guide: false` 只表示**不注册 system prompt 的 guide 段**（预设未列本插件时没有 `memu_*` 工具；即便列了，`persona` 的 `complete: true` 也会丢弃该段），规则改由 `guideMessage: true` 用一次性消息投放，正文自带「工具列表里没有 `memu_*` 就忽略本段」。同树的正常会话跳过，避免注入两遍；agent 消失就卸载。
 
-**提示词怎么办**：`persona` 常带 `complete: true`——装配完成后它会被恢复为唯一的 system prompt 段，本插件 `systemPrompt.section()` 注册的 guide 会被整段丢弃（实测 RP 会话的 `system/message` 只有人格正文）。所以预设会话改用**消息**投放规则：首步追加一次 `<memory-guide>` 插件消息（`withGuideMessage`，按 `binding.guideMessageAt` 会话内只发一次），并注明「工具列表里没有 `memu_*` 就忽略本段」。工具确实存在的预设会话因此重新拿到主动性规则，而不是只有一个 anchor。
+**提示词怎么办**：所有会话现在都走同一条消息路径，预设的 `complete: true` 不再造成投放差异；`ensureUnifiedGuide` 在回合首步追加 `<memory-guide rules="…">`，文末提示「工具列表里没有 `memu_*` 就忽略本段」。切域、改稿、默认稿升级和压缩丢失由 `rulesKey`/`guideLost` 处理；旧会话只有 `guideMessageAt` 时补投一次。
 
-**边界要分三件事讲**：① **注入监听**——补挂到 agent 自己的 ctx 后，锚点与召回上下文能送达；② **guide 投放**——首步一条 `<memory-guide>` 消息，会话内只发一次，正文自己声明「没有工具就忽略」；③ **最终工具面**——由该预设自己的 `cordis.yml` 清单与宿主 scope 决定，本插件**不能**从「有没有列上它」推断出一定有或一定没有。历史记录里曾出现过某些 RP 会话工具链含 `memu_private_*`，但 2026-10-29 复核无法把它归到本机 `yuike` bundle（该 bundle 未列本插件，且本机无 `agentPreset=yuike` 的真机会话），只能保留为未复核历史观察；**逐预设的真实工具名单仍须真机核实（W3）**，核实前不要写成「只有注入、没有工具」，也不要反过来写成「列上插件就一定可用」。真要在没有工具的会话里写记忆，进一次标准会话仍是最直接的办法——但如果该预设确实列了本插件且工具注册成功，记忆可以直接在那个会话里写。**不要为了这个去改别人的人格插件**：预设文件属于它的维护者，插件只能在自己的 scope 里做适配。
+**边界要分三件事讲**：① **注入监听**——补挂到 agent 自己的 ctx 后，锚点与召回上下文能送达；② **guide 投放**——首步一条 `<memory-guide>` 消息，规则变化或压缩丢失时替换，不是每回合重复；正文自己声明「没有工具就忽略」；③ **最终工具面**——由该预设自己的 `cordis.yml` 清单与宿主 scope 决定，本插件**不能**从「有没有列上它」推断出一定有或一定没有。历史记录里曾出现过某些 RP 会话工具链含 `memu_private_*`，但 2026-10-29 复核无法把它归到本机 `yuike` bundle（该 bundle 未列本插件，且本机无 `agentPreset=yuike` 的真机会话），只能保留为未复核历史观察；**逐预设的真实工具名单仍须真机核实（W3）**，核实前不要写成「只有注入、没有工具」，也不要反过来写成「列上插件就一定可用」。真要在没有工具的会话里写记忆，进一次标准会话仍是最直接的办法——但如果该预设确实列了本插件且工具注册成功，记忆可以直接在那个会话里写。**不要为了这个去改别人的人格插件**：预设文件属于它的维护者，插件只能在自己的 scope 里做适配。
 
 ### 8.11 全局整理的间接输入边界