dsh-observational-memory

dsh plugin --profile web add dsh-observational-memory

DSH Observational Memory

中文 | [English](README.en.md)

适用于 DeepSeek Harness（DSH）的插件：在后台持续把会话工作沉淀为观察（Observations）与反思（Reflections），让长会话经过多轮压缩依然连贯。移植自 pi-observational-memory（Pi 的扩展）。

当 DSH 发生上下文压缩时，压缩摘要有现成的记忆可用——不再需要模型现场重写历史：观察器、反思器、清理器在后台按 token 节奏运行，压缩真正发生时只需一次确定性的渲染，零模型调用。

为什么需要

长会话最终都会撞上上下文墙。压缩把会话总结成摘要，多轮压缩之后，代理携带的已经是"摘要的摘要"——设计决策的理由、被否决过的方案、关键约束、用户已澄清过的内容开始悄悄丢失。

本插件把记忆工作前置到会话进行过程中，而不是等压缩发生时再补救。

特性

• 后台记忆流水线：观察器（把会话事件蒸馏为带时间戳、带相关度的观察）→ 反思器（从观察中提炼长期事实）→ 清理器（修剪已被反思覆盖的观察），全部由 turn/end 等会话事件按 token 阈值驱动。
• 压缩即渲染：DSH 压缩引擎发起摘要调用时（purpose: 'compaction'），插件在 llm/stream 瀑布中拦截，直接用渲染好的记忆文本应答——压缩零等待、零模型调用；记忆为空时回退 DSH 原生摘要。
• 主动压缩：会话空闲且上下文达到阈值时主动触发压缩；阈值支持 calibrated（固定值）与 ratio（上下文窗口 × 比例）两种模式，设置卡片只显示当前模式生效的那个参数。
• recall 工具：模型可凭记忆 id 精确恢复任意观察/反思背后的原始会话证据（带时间戳的原文）。
• 记忆选项卡：对话视图环新增「记忆」页，实时展示记忆清单、worker 进度、记忆内容（可见/完整）与调试日志。
• 回退按钮：每条用户消息下新增「回退」，一键在消息前分叉会话并把原文放回输入框。
• 双语设置卡片：「设置 → 插件」中打开 dsh-observational-memory 的包详情页，其中的 Observational Memory 配置卡支持中/英文，模型覆盖从 DSH 已添加的模型列表按 提供商 → 模型 → 推理强度 级联选择。

核心概念

• 观察（Observation）：带时间戳、带相关度（low/medium/high/critical）的会话事件记录，每条都锚定到产生它的会话事件（sourceEventSeqs）。
• 反思（Reflection）：从观察中蒸馏出的长期事实（用户偏好、项目约束、技术决策、已完成的结果），每条都引用支撑它的观察（supportingObservationIds）。
• 清理（Drop）：清理器在反思成功后修剪活跃观察池，删除内容已被反思覆盖的观察。删除只是从活跃记忆中移除，账本历史仍然保留、仍可被 recall 工具追溯。

工作原理

flowchart TD
    Turn[turn/end 会话事件] --> ObsDue{观察阈值到期?}
    ObsDue -->|是| Observer[观察器调用模型<br/>写入 observations-recorded]
    ObsDue -->|否| RefDue{反思阈值到期?}
    RefDue -->|是| Reflector[反思器写入 reflections-recorded]
    Reflector -->|观察池超目标| Dropper[清理器写入 observations-dropped]
    Compact[DSH 压缩发起] --> Hook[llm/stream 拦截 purpose=compaction]
    Hook -->|记忆非空| Render[确定性渲染记忆摘要<br/>（零模型调用）]
    Hook -->|记忆为空| Native[回退 DSH 原生摘要]

1. 会话正常推进；turn/end 与 agent/created 事件驱动整合流水线（观察器优先，随后反思器，最后清理器）。

2. 每个 worker 只有一个记录工具，由代码校验模型产出（来源 seq、支撑 id 必须真实存在），id 由内容哈希确定性生成。

3. DSH 压缩引擎做摘要调用时（purpose: 'compaction'），本插件在 llm/stream 瀑布中拦截：投影非空则直接返回渲染好的记忆文本，压缩零等待；投影为空则放行原生摘要。

4. 压缩提交后，可见记忆（visible memory）记入账本，供状态对比（drift）使用。

与 pi 版的差异（平台适配）：

• 账本存储：DSH 的持久化只接受其内置事件词表（外部插件无法写入带 ignorable 标记的自定义会话事件），因此账本存放在插件自己的目录（默认 $DSH_HOME/observational-memory/<sessionId>.jsonl），不动会话日志，不影响 DSH 本体。
• 压缩集成：pi 用 session_before_compact 钩子替换摘要；DSH 没有这个钩子，本插件通过 llm/stream 瀑布拦截压缩摘要调用来实现同样的"压缩即渲染"。
• 主动压缩：阈值有两种模式（与 pi 版一致），见下文「配置」；在 Web 组合中压缩引擎位于 agent preset 的隔离 realm 内，本插件经 agentPresets.serviceFor 跨 realm 解析。
• 命令行界面的对应形态：pi 版的 /om:status、/om:view TUI 命令在 DSH 中由对话上方的记忆选项卡承载（见下文「使用」）；pi 版的剪贴板复制由选项卡内的复制按钮承载。
• 回退：新增用户消息下的回退按钮（中止当前运行、回退到最近一条用户输入之前、把原文放回输入框，详见下文「使用」）。

安装

插件版本与 DSH 版本对应关系矩阵如下：

插件版本 · 最低适配的 DSH 版本 · 最高适配的 DSH 版本

0.4.3 · 0.1.5-rc.2 · 0.2.1-rc.5

0.4.2 · 0.1.5-rc.2 · 0.2.1-rc.4

0.4.1 · 0.1.5-rc.2 · 0.2.1-rc.2

0.4.0 · 0.1.5-rc.2 · 0.2.1-rc.2

0.3.0 · 0.1.5-rc.2 · 0.2.0-rc.2

0.2.0 · 0.1.5-rc.2 · 0.1.7-rc.1

0.1.4 · 0.1.5-rc.2 · 0.1.5-rc.3

0.1.3 · 0.1.5-rc.2 · 0.1.5-rc.2

0.1.2 · 0.1.5-rc.2 · 0.1.5-rc.2

插件在 0.1.7 及以上使用 Profile 持有的实时配置，在 0.1.5 上回退到经典 settings.yaml 设置节，旧设置文档在 0.1.7 首次启动时自动导入。

通过 DSH CLI 把插件加入指定的 Profile（这里以 web 为例，按需替换）。本包自带 cordis.patch.yml，组合器会自动挂载 host 半端，并向 Web 客户端提供 /plugins/dsh-observational-memory/client.js——安装后无需额外的组合配置。

从 npm 安装

dsh plugin --profile web add dsh-observational-memory

从 GitHub 安装

dsh plugin --profile web add github:EPCN-fla/dsh-observational-memory

通过 git 源安装时，npm 会执行包的 prepare 脚本自动完成构建（要求 Node ^22.19.0 或 >=24）。

从 tarball 安装

git clone https://github.com/EPCN-fla/dsh-observational-memory.git
cd dsh-observational-memory
npm install
npm run build
npm pack        # 产出 dsh-observational-memory-<version>.tgz
dsh plugin --profile web add ./dsh-observational-memory-<version>.tgz

本地开发

开发期也可以把 CLI 直接指向工作副本目录；每次改动后重新 npm run build 即可生效：

dsh plugin --profile web add /absolute/path/to/dsh-observational-memory

安装后重启 DSH Web。确认加载：dsh --profile web --dump-config | grep observational-memory。

使用

设置卡片

打开 设置 → 插件，点击 dsh-observational-memory 进入包详情页，在 Observational Memory 配置卡中编辑，保存即时生效（无需重启）。（0.1.5 宿主机型：卡片位于「设置 → 插件 → 插件配置」选项卡。）卡片支持中/英双语，跟随 DSH 的语言设置。

• 阈值区：「压缩阈值模式」决定只显示哪个阈值参数——calibrated 显示「主动压缩阈值」，ratio 显示「压缩阈值比例」；只有显示的参数有效，隐藏的参数无论设成多少都不生效。
• 模型（可选）区：「提供商 → 模型 ID → 推理强度」三级下拉，选项来自 DSH 已添加的模型列表；前者未选择时后者的下拉框为空。全部留空则记忆 worker 跟随会话当前模型。
• 每个字段可「重置为默认」；保存即时生效，校验不通过时保存按钮不可用并提示原因。

记忆选项卡

对话上方的视图环在「对话」「轨迹」右侧新增记忆选项卡，对应 pi 版的 /om:status 与 /om:view 命令，内容经插件注册的 Typert Remote 端点（observationalMemory/status|view|run|logs）由宿主实时生成：

• 状态：记忆清单（已记录/已清理/活跃/可见 观察数与反思数、漂移统计）、各 worker 的进度条（距下次观察/反思/压缩的 token 进度，含 ratio 模式标注）、在途任务与最近的 worker 错误。
• 记忆内容：/om:view 的内容，可在「当前可见」（最近一次压缩后代理实际可见的记忆）与「完整记录」（账本全量）之间切换；复制按钮把当前内容写入剪贴板。
• 调试日志：debugLog 开启时显示该会话 NDJSON 调试事件的尾部（默认 200 行）。

工具栏的立即运行按钮手动触发一次完整整合（观察 → 反思 → 清理），绕过被动开关与 token 阈值（空积压仍然不产生模型调用）；已有任务在途时不会重复触发。这是被动模式下保留的主动入口，主动模式下同样可用。

选项卡在打开时拉取一次，之后用「刷新」按钮更新；不会轮询。

recall 工具

代理可调用 recall(id)（12 位小写十六进制记忆 id）恢复某条观察/反思背后的原始会话证据（带时间戳的原文）。它是精确定位工具，不是搜索工具：模型在压缩后的记忆行里看到 id，需要确证时再调用。结果按 50,000 字符分页；截断时会给出下一次 recall(id, offset) 所需的偏移量。

回退按钮

每条用户消息（含 steering 消息）下方、「复制」左侧新增回退按钮：点击后在该消息之前的最近已完成轮次边界处分叉出一个新会话（fork），打开新会话，并把该消息的原文放回其输入框——可以修改后重新发送。整个过程非破坏性：原会话历史原样保留在自己的分支上。

新分支在首次触及记忆时继承原会话截至分叉点的记忆（观察、反思、清理记录与可见记忆），回退后无需从零积累；仅覆盖被放弃分支（分叉点之后事件）的记录不随分叉转移。父分支账本为空时会沿分叉链向上找到最近可用的账本，因此连续回退也能继承。被动模式不影响继承。

DSH 只能按轮次边界切分会话，因此按钮在以下情况保持禁用（悬停有提示）：首轮消息（之前没有可回退的边界）、纯附件或含附件的消息（草稿无法还原附件）、无文本消息。卸载本插件后，用户消息渲染恢复原样。

配置

配置使用独立的 observational-memory 命名空间，与 DSH 本体其他配置隔离。DSH ≥0.1.7 将用户层保存到当前 Profile 的 cordis.patch.yml；DSH ≤0.1.5 使用 $DSH_HOME/settings.yaml，旧文档会在升级后首次启动时导入。两种改法：

1. 界面（推荐）：见上文「设置卡片」，由宿主写入当前版本正确的位置。

2. 手改文件：DSH ≥0.1.7 编辑当前 Profile 的 `cord

…(truncated)