meisijiya/omp-memory-dsh

omp-memory-dsh

把 omp（oh-my-pi coding agent）的项目级记忆接入 DeepSeek Harness，让两个 agent 在同一个项目里 共用同一份教训沉淀。

• DSH 侧注入 memory_summary.md + learned.md 的一个窗口
• DSH 侧提供 learn 工具，把新教训写回同一个 learned.md
• omp 侧的 learn / autolearn 完全不受影响，两边看到的内容一致

---

🔴 安全承诺（先看这一节）

这个插件会写你的文件系统，而且那份文件是另一个 agent 的。所以它的默认行为是保守的：

为什么默认拒绝淘汰？ omp 的教训上限是 100 条，超了就静默淘汰最旧的。在真实项目里，DSH 每写一条都会 加速这个淘汰，而 omp 自己毫不知情。默认 refuse 把这个决定权交回给人： 要不要用历史沉淀换一条新教训，你说了算。 确实需要与 omp 完全一致时，配置 evictionPolicy: "omp-parity" 即可（仍会如实回报淘汰条数）。

🔴 100 条封顶是 omp 的规则，不是本插件的

这个上限由 omp 强制。本插件只能控制自己这一侧（默认 refuse ⇒ DSH 绝不触发淘汰）， omp 自己继续写就会淘汰掉它最早的沉淀。

本插件对此的处理：

• learn 撞顶时拒绝写入，并报出真实总数与剩余额度（例：「当前已有 100 条教训…距上限还差 0 条」）。
• 成功写入时也回报当前条数（例：「当前 84/100 条，距上限还差 16 条」）。
• 注入文本的 Project: 行标明这是哪个项目的记忆。

⚠️ 注意：这条风险不因装了这个插件而消失。插件只能保证「DSH 不加速它」。 要真正控制它，得改 omp 侧的上限（那是另一个话题，本插件不碰 omp 的配置）。

---

兼容性

DSH 的官方包一律声明在 peerDependencies（不作为生产依赖打包），插件本身只引入 @deepseek-ai/schemastery 一个运行时依赖。

---

安装

推荐：用预构建 tarball（不需要本地构建）

dsh plugin --profile web add https://github.com/meisijiya/omp-memory-dsh/releases/download/v0.2.0/omp-memory-dsh-0.2.0.tgz

或者：从 GitHub 源码安装（会跑 prepare 自动构建）

dsh plugin --profile web add github:meisijiya/omp-memory-dsh

或者：手动挂到 profile

本包是一个 DSH bundle：package.json 里声明了 dsh.bundle.patch， 所以 dsh plugin add 装上之后会自动生效，不需要额外写 patch。

如果你要手动挂载，把插件加进 profile 的 package.json 依赖，然后在 cordis.patch.yml 里写包名（不是绝对路径）：

- insert:
    - id: omp-memory
      name: 'omp-memory-dsh'
      config:
        enabled: true
        evictionPolicy: 'refuse'

🔴 为什么是包名而不是绝对路径？ DSH 的 loader 用 import(name) 加载插件。Node 的 ESM 在 Windows 上不接受裸绝对路径 （会报 ERR_UNSUPPORTED_ESM_URL_SCHEME），而且绝对路径换台机器就断。 包名由 profile 的 node_modules 解析，是唯一可分发的写法。 （本仓库里 cordis.patch.yml 就是这个文件本身。）

装完需要重启 DSH（插件在进程启动时装载）。

或者：从插件市场的「索引源」装

本仓库根目录带一份 format-1 插件市场索引 index.json。 在「插件 → 发现 → 索引源」里加上它的地址（https://raw.githubusercontent.com/meisijiya/omp-memory-dsh/main/index.json）， omp-memory-dsh 就会出现在「发现」页，可点安装、可人工启用 / 停用 / 卸载。

索引格式由宿主校验器定义，规则多、易踩，所以本仓库带了一个闸门：

npm run verify:market-index

完整说明（三个插件界面的区别、索引源怎么加、启停卸载各改什么、以后发 npm 要改哪几处）见 docs/plugin-market.md。

---

配置

所有配置项都有默认值，不配置也能跑。

---

工作原理

读路径

1. 会话首次装配 system prompt 时，读取 <root>/<项目键>/memory_summary.md 与 learned.md。
2. 摘要先占预算：共享预算是 5000 token（≈ 20 000 字符），learnedBudget = 5000 - ceil(摘要字符数 / 4)。
3. learned.md 只读窗口，不整读：读文件头部（60%）与尾部（40%），中间省略。
4. 切点吸附行边界 ⇒ 绝不产出「半条教训」。省略处会插入截断标记与一句提示。
5. 快照在整个会话内冻结（与 omp 一致），只有 DSH 自己刚写过一次才会刷新。 这样 system prompt 不会在一轮对话中途漂移。
6. 内容注入到一个 interpolate: false 的 section 里，外面包着 <omp-memory-data> 标签， 并附上 omp 原版的 6 条 Rules。

项目键在会话开始时冻结。 DSH 的工作目录在会话中可变，但项目键不变 —— 否则 learn 会写到另一个项目的目录里去。

写路径

learn 工具的完整闸门顺序（任何一步不过，都不写文件）：

内容检查（拒绝指令式内容）
  → 格式与长度归一（脱敏 + 中和注入 + 上限 2000/400 字符）
  → writeEnabled 闸门
  → 目录存在性检查（绝不静默新建目录）
  → 文件锁（withFileLock，超时即报错）
  → 撕裂守卫（无尾换行 ⇒ 复读一次比对）
  → 计算新内容（去重 + 插入第一个 bullet 段 + 封顶处理）
  → 封顶闸门（refuse 模式下会淘汰就拒绝）
  → 写前 CAS 指纹复核（size + mtime + sha256）
  → 原子写（writeFileAtomic）
  → 写后校验
  → 写 sidecar 溯源账本

目录必须先存在。 如果这个项目在 omp 那边还没有记忆目录，learn 会拒绝写入并说明原因， 而不是替 omp 建一个 —— 静默建目录会让两端从此分叉。需要先让 omp 打开过该项目。

---

工具面

learn

把一条持久教训写进本项目的共享记忆。

写入失败时抛错并说明原因（例如「拒绝写入：本次写入将淘汰最旧的 1 条既有教训」）。

memory_read

按行分页读取本项目的完整记忆，只读。用于读到被注入窗口省略掉的教训，或审计记忆实际内容。

---

与 omp 的关系

omp 的 config.yml、autolearn、managed-skills 一律不碰。

---

一致性是怎么验证的

单元测试能证明「实现符合我们写下的规则」，但不能证明「两端真的看到同一份东西」。 所以另有一组黑盒对跑：同一句提示词，分别喂给 omp 的无头模式与 DSH 的一次性任务， 再用一个没有记忆的目录做对照。

反方向也验证过：DSH 的 learn 写进去一条带唯一标记的教训后， omp 在同一个项目里能读到它。

对照组的意义：正确答案只有在两边都拿到记忆时才出现 ⇒ 它来自记忆，不是模型猜的。

---

已知限制（诚实清单）

1. 只做项目级记忆。 不读 omp 的 managed-skills/，不做 auto-learn 的自进化。
2. Linux 上需要显式配 root。 omp 在 Linux 上用 $XDG_STATE_HOME/omp/memories， 本插件的默认是 ~/.omp/agent/memories，两者不一致时需要手工指定。
3. 不是 100% 原子。 CAS 复核与 rename 之间仍有极小竞态窗口。真正兜底的是 原子写 + 撕裂守卫 + 写后校验三件套。
4. omp 的非原子写（Bun.write）在写入瞬间可能让 DSH 读到半截文件。 撕裂守卫会检出并重试，但极端情况下仍可能读到不完整内容。
5. requireApproval 默认关闭。 DSH 没有工具级审批字段，审批只能通过 tools/pre-execute 的 waterfall 模拟，且必须有审批服务在场，否则 ask 降级为拒绝。
6. 脱敏规则是上游 v18.12.2 的快照。 上游改进后需要重新对齐（重跑 npm run test:fixture 会报漂移）。
7. DSH 侧比 omp 多一层护栏 ⇒ 两端行为有分叉。 DSH 拒收指令式内容与明文凭据， omp 不拒收（omp 那边只是中和注入载体、不做语义判断）。所以同一条内容， DSH 可能写不进去而 omp 写得进去。护栏命中时会在报错里说明原因。
8. 读侧不拦明文凭据。 写侧会拒收凭据形状，但读侧只过滤指令性内容 —— omp 那边写进去的 password=... 仍会被原样注入。收紧读侧会破坏与 omp 的字节一致性， 这是一个已知的、刻意保留的不对称。
9. 注入的是窗口，不是全部。5000 token 共享预算下，大项目只有开头与结尾的教训进入注入， 中间的要用 memory_read 主动读。（读取预算是按字符算的，实际 I/O 按字节算，中文约 ×2.7。）

---

开发

npm install
npm run check            # typecheck + vitest + fixture 三连
npm run build            # 产出 lib/（逐文件编译，不是一个 bundle）
npm run test             # 只跑 vitest
npm run test:fixture     # 上游漂移检查 / oracle 自检 / 安全红线脚本
npm run test:upstream    # 在线拉取 GitHub 上的 omp 固定 tag 比对 sha256
npm run verify:build     # 把构建产物装进真实 cordis 容器并加载
npm run verify:package   # 打包 → 解包 → 逐个解析相对 import → 真的 import 一次

verify:package 不是形式检查：它会真的 npm pack，解包，验证产物里每个相对 import 都能解析（漏发一个 .js 文件就会在这里炸），然后真的 import 一次产物入口。

上游 oracle

test/fixtures/omp-v18.12.2/ 里是 oh-my-pi v18.12.2 的上游源码切片 （memories/index.ts、memories/storage.ts、memory-backend/redact.ts、 prompts/memories/read-path.md）以及一份 manifest.json（逐文件 sha256）。

• check.mjs —— 校验本地切片与 manifest 一致，并把 pure.ts 重新抽取后逐字节比对（oracle 手改即漂移）
• selftest.mjs —— oracle 自身的行为自检，并全量扫描真实记忆目录验不变式
• safety.mjs —— C6 安全红线的可执行判据
• verify-upstream.mjs —— 在线拉取 GitHub 上的 omp 固定 tag 比对 sha256
• pure.ts —— 从上游切片抽出的纯逻辑，测试专用

npm run test:fixture 全绿是放行的前提之一。

重新生成 oracle

上游升级后：

node test/fixtures/omp-v18.12.2/regen.mjs

---

License

MIT

上游 oh-my-pi 的相关代码遵循其自身许可证；本仓库只包含为差分测试而保留的源码切片。