@lovenndme/dsh-workspace-memory 0.0.0-stage → 0.8.3

package/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+## 0.8.3 — 2026-11-15
+
+- ci: note why windows+node 18 is intentionally not in the matrix
+- fix: use fileURLToPath instead of import.meta.dirname so tests run on node 18
+- ci: add scheduled multi-platform test workflow (ubuntu 18/20, windows 20)
+- fix: ship scripts/install-deps.mjs so the README step works after npm install
+- docs: record the npm publish and the Linux-only CI failures
+
+
+## 0.8.2 — 2026-11-15
+
+- release: v0.8.1
+- fix: skip Windows-only cmd-quoting cases on other platforms
+- fix: make tests run on Linux CI (portable absolute path, skip embedder-only cases)
+- feat: publish to npm as @lovenndme/dsh-workspace-memory with CI release pipeline
+- Panel redesign: overview map, review cards, instructions and memories pages
+- Preview: memory panel redesign (approved static preview)
+- Docs: rewrite README for users, move design notes to docs/DESIGN.md
+- Memory admission redesign: source-based routing, call-time destinations
+- HANDOFF: record the real-memory cleanup (24.7)
+- Tests: never launch real processes (stop popping terminal windows)
+- Docs: README/HANDOFF/CLAUDE.md for the review-and-fix round
+- Host: harden routes, self-healing recall, word-boundary keywords, slug guard
+- Storage: block id path traversal, lossless frontmatter, safer AGENTS.md edits
+- Panel: fix save races, pending edits, AGENTS.md positional writes
+- Pin LF line endings via .gitattributes
+- Baseline before code-review fixes
+
+
+## 0.8.1 — 2026-11-15
+
+- fix: skip Windows-only cmd-quoting cases on other platforms
+- fix: make tests run on Linux CI (portable absolute path, skip embedder-only cases)
+- feat: publish to npm as @lovenndme/dsh-workspace-memory with CI release pipeline
+- Panel redesign: overview map, review cards, instructions and memories pages
+- Preview: memory panel redesign (approved static preview)
+- Docs: rewrite README for users, move design notes to docs/DESIGN.md
+- Memory admission redesign: source-based routing, call-time destinations
+- HANDOFF: record the real-memory cleanup (24.7)
+- Tests: never launch real processes (stop popping terminal windows)
+- Docs: README/HANDOFF/CLAUDE.md for the review-and-fix round
+- Host: harden routes, self-healing recall, word-boundary keywords, slug guard
+- Storage: block id path traversal, lossless frontmatter, safer AGENTS.md edits
+- Panel: fix save races, pending edits, AGENTS.md positional writes
+- Pin LF line endings via .gitattributes
+- Baseline before code-review fixes
+

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lovenndme
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,246 @@
-# Temporary Holding Version
+# dsh-workspace-memory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+给 DSH（DeepSeek Harness）用的记忆插件：让 agent 跨会话记住你是谁、你希望它怎么做事，以及每个项目里代码看不出来的事。
+做法对标 Claude Code 的记忆：分层的指令文件（CLAUDE.md 那一套，在 DSH 里是 AGENTS.md）加上自动记忆。
+
+## 为什么需要它
+
+每开一个新会话，agent 都从零开始：上次纠正过的做法这次又犯，上周定下的期限它不知道，仓库外的资料放在哪也得重新问一遍。
+光有一个「记忆工具」还不够。实际用下来，常见的问题是三类：该记的没记（用户纠正了一句，模型嘴上答应「以后注意」，却什么都没写下来）；
+记的东西放错地方（全员都要守的仓库规则被存进了某个人的记忆，流程和设计说明也塞进了记忆）；模型自己往每轮都会注入的常驻文件里乱写规则。
+这个插件把「一条东西该写到哪」理清楚，让模型在对的时机写到对的地方，并且常驻的东西一律由你点头。
+
+## 记忆分几层
+
+### 每轮都会看到的（常驻）
+
+这三层由 DSH 宿主在每个会话里加载，模型每一轮都看得到：
+
+- ① **全局 AGENTS.md**（`~/.dsh/AGENTS.md`）：在所有项目都成立的东西——你是谁、你对做事和表达方式的要求、后果不可挽回的坑。
+   模型通过记忆工具提出，先进待确认，**你在面板上点「收下」之后才写入**。
+- ② **项目 AGENTS.md**（仓库根目录，进 git）：进这个仓库的人和 agent 都要守的规则，包括仓库约定（提交说明、代码风格、命名）。
+   插件不写它：模型先向你提议，你同意后用文件工具写。
+- ③ **AGENTS.local.md**（和项目 AGENTS.md 同一个目录，不进 git）：只对你成立的项目规则。写法同上。
+
+### 用到时才看的（按需）
+
+- ④ **项目记忆库**（`~/.dsh/projects/<工作区>/memory/`）：本项目进行中的决定和期限、仓库外资源的位置、本项目踩过的坑。
+- ⑤ **跨项目记忆库**（`~/.dsh/dsh-workspace-memory/global/memory/`）：哪个项目都可能遇到的坑、参考资料。
+- ⑥ **skill**（`~/.dsh/skills/` 或项目里的 `.dsh/skills/`）：可重复的多步流程。插件不写 skill，模型提议、你同意后用文件工具写。
+
+④⑤ 的索引每轮都可见，一条记忆占一行摘要；正文用到时才取出来。记忆会在三个时机被想起来：每轮按你说的话预取最相关的几条，
+读写某个文件时提示与它相关的记忆，以及模型主动调用 `memory_recall`。
+
+### 待确认：一道关卡，不是一层
+
+模型自己总结出来的、要写进全局 AGENTS.md 的、声称是你的原话但核对不到的，都先进待确认，由你在面板上收下或丢弃。
+
+### 和 Claude Code 的对照
+
+| 这里 | Claude Code |
+|---|---|
+| ① 全局 AGENTS.md | `~/.claude/CLAUDE.md` |
+| ② 项目 AGENTS.md | 项目里的 `CLAUDE.md` |
+| ③ AGENTS.local.md | `CLAUDE.local.md` |
+| ④⑤ 项目记忆库、跨项目记忆库 | 自动记忆 |
+| ⑥ skill | skills |
+
+区别有两点：按需的记忆分成本项目、跨项目两个库；写入多了一道待确认关卡。
+
+插件面板里用的叫法：① 是「全局指令」，②③ 是「项目指令 · 团队 / 仅你」，④⑤ 是「项目记忆」「通用记忆」。
+面板能编辑记忆和全局指令；**项目指令在面板里只读**，它们是仓库里的普通文件，直接用编辑器改（面板上有打开按钮）。
+
+## 一条新东西怎么决定去哪
+
+模型照下面的顺序判断：
+
+1. 可重复的多步流程（怎么部署、怎么排查某类故障），不管是只有它用还是大家都用，写成 skill。
+2. 必须遵守的规则，以 AGENTS.md 为准：全员都要守的写项目 AGENTS.md，只对你成立的写 AGENTS.local.md。记忆里不再存第二份。
+3. 关于你本人、或者你对它做事和表达方式的要求，并且在所有项目都成立的，写进全局 AGENTS.md（先进待确认）。
+4. 其余只有你和它用得上的，按「只在本项目成立」还是「哪个项目都成立」分别进项目记忆库或跨项目记忆库。
+5. 拿不准该去哪，或者拿不准是长期规则还是只管这一次，它会在回复末尾问你一句，并给出选项。
+6. 只纠正这次结果的（算错了、写错了），或者你话里带了「这次」的，不记。
+
+模型调用记忆工具时必须给内容归类。归成「流程」「全员规则」「项目文档」这三类时，工具什么都不保存，而是告诉模型该写到哪
+（skill、项目 AGENTS.md、README），由模型再向你提议。设计上为什么这样分、每一步怎么来的，见 [docs/DESIGN.md](docs/DESIGN.md) 的「记忆写到哪」。
+
+## 安装
+
+从 npm 装（推荐）：
+
+```text
+plugin_manager install_bundle --target @lovenndme/dsh-workspace-memory
+```
+
+或者以本地目录 link 的方式装：
+
+```text
+plugin_manager install_bundle --target <插件目录>
+```
+
+**国内网络**：DSH 的「发现」面板走 GitHub Pages，无代理经常加载不出来（表现为「搜不到插件」）。
+这时走「插件 → 添加插件 → 安装源选『中国大陆镜像源』→ 粘贴包名 `@lovenndme/dsh-workspace-memory`」
+即可；结束后 npm 会自动同步，通常几分钟就能拿到最新版。只有安装这一步需要联网，装完完全离线可用。
+
+装好后把它**先禁用、再启用**一次，让宿主换上新模块（在插件列表里切，或者让 agent 调用）：
+
+```text
+plugin_manager set_plugin --target include:dsh-workspace-memory --enabled false
+plugin_manager set_plugin --target include:dsh-workspace-memory --enabled true
+```
+
+以后改了代码或拉了新版本，也要这样切一次。
+确认插件行的 `application` 状态是 `applied`、没有 diagnostic，才算装好。
+
+**可选：装上语义检索用的嵌入模型 `leanvec`。** 不装也能用，只是检索退化成纯关键词，同义改写、换个说法问就找不到。
+在插件目录里运行一次：
+
+```bash
+node scripts/install-deps.mjs   # 约 85 MB，装到 ~/.dsh/dsh-workspace-memory-deps
+```
+
+装完再禁用、启用一次插件。`memory_status` 会显示当前是 `hybrid`（向量加关键词）还是 `keyword`（纯关键词）。
+
+## 平时怎么用
+
+大多数时候你什么都不用做：模型会在合适的时候自己调用记忆工具，你只需要偶尔去面板上处理待确认。
+
+### 面板
+
+右侧栏的「记忆」页签，也可以用 `/memory_list` 打开。顶部四页：
+
+- **总览**：一张「记忆地图」，按「在哪儿生效（所有项目 / 本项目）× 什么时候读（每轮都读 / 用到才查）」摆出全局指令、通用记忆、
+  项目指令、项目记忆四处各有多少、离上限多远；下面是每轮固定带给模型的内容约多少 tokens、最近变化，
+  以及很久没被用到、可能过时的记忆。有待确认时顶部会提示。
+- **待确认**：等你决定的草稿，一张卡一条。每张卡写明收下后去哪（例如「→ 全局指令 · 覆盖第 2 章」「→ 项目记忆 · 替换「…」」）、
+  为什么要你确认、出处原话；覆盖或替换时可以和现在的内容逐行对比。「收下」写入，「丢弃」删掉草稿（会先确认，丢弃不留历史）。
+  焦点在面板里时可以用 J / K 切换、A 收下、D 丢弃。
+- **指令**：「全局」逐章查看和编辑全局指令（`~/.dsh/AGENTS.md`），增删章，编号自动重排，显示字节用量与上限，也可以用本机编辑器打开；
+  文件还不存在时可以在这里新建。「本项目」只读展示项目根目录（从当前会话目录往上最近的 `.git` 所在处，也就是 DSH 实际加载项目指令的位置）的 AGENTS.md 与 AGENTS.local.md。
+- **记忆**：项目记忆和通用记忆的列表与详情。可以搜索、按适用范围和类型筛选，编辑标题、摘要、正文、类型、标签和文件名；
+  改「适用范围」保存后会把条目移到另一个库；「升为全局指令」把一条记忆变成全局指令的新一章并从记忆里移出（两个库的都可以）。
+  删除和覆盖前都会留一份历史版本。有未保存的修改时离开会先问你，Ctrl+S 保存。
+
+### 命令
+
+```text
+/memory                      概览：记忆条数、检索模式、助手总结的记忆怎么处理
+/memory list                 列出全部记忆
+/memory pending              列出待确认草稿（也可以用 /memory_pending）
+/memory accept <id>          收下一条草稿
+/memory reject <id>          丢弃一条草稿
+/memory forget <id> [project|global]
+                             删除一条记忆（两个库都有同一个 id 时要写明是哪个）
+/memory extract              立刻从当前对话里抽取一次候选，结果进待确认（也可以用 /memory_extract）
+/memory reindex              手改过记忆文件后，重建索引
+/memory_list                 在右侧栏打开记忆面板
+```
+
+### 模型用的工具
+
+- `memory_remember`：写一条记忆，或者被告知这条内容该写到别处。
+- `memory_recall`：在两个记忆库里检索，返回正文和最后更新日期；什么都没找到时会明确告诉模型「没有记录」，而不是让它自己猜。
+- `memory_forget`：按 id 删除一条记忆。
+- `memory_status`：排障用，报告两个库的条数、索引、检索模式、最近一次证据核对和配置问题。
+
+## 哪些时候要你确认
+
+- **写进全局 AGENTS.md 的，一律先进待确认**，不论是谁提出的。
+- **模型自己总结的**（例如它自己踩到并验证过的坑）进待确认。想让这类按需记忆直接生效，可以把配置 `agentWrites` 改成 `direct`。
+- **你说的原话**：模型写入时要附上你的原话，插件会到你发过的消息里核对。核对得上的直接写进记忆库（要进全局 AGENTS.md 的除外，那些照样先进待确认），
+  核对不上的进待确认。
+- 面板上的来源标签：「你的原话 · 已核对」表示核对过、确实出自你；「说是你的原话 · 没核对上」表示模型说是你的原话，但对话里找不到；
+  「你的原话 · 旧条目未核对」是核对机制出现之前记下的；「Agent 总结」表示模型自己得出的。
+- 草稿卡片的去向如果是「替换「…」」，或写着「同时删除」某条记忆，收下它会删掉那条旧记忆（删除前留历史版本）。
+
+## 配置
+
+不改任何配置也能用。要调整时，在 profile 的 `cordis.patch.yml` 里本插件那一行下加 `config`，改完禁用再启用插件生效：
+
+```yaml
+- id: dsh-workspace-memory
+  name: '@lovenndme/dsh-workspace-memory'
+  config:
+    enableExtraction: true
+    agentWrites: direct
+```
+
+常用的几项：
+
+| 键 | 默认 | 作用 |
+|---|---|---|
+| `enableExtraction` | `false` | 每隔几个回合自动从对话里抽取候选，进待确认。会给这些回合多加一次模型调用 |
+| `agentWrites` | `review` | 模型自己总结的按需记忆：`review` 进待确认，`direct` 直接写入。写全局 AGENTS.md 不受它影响 |
+| `maxMemoryCount` | `50` | 每个记忆库最多多少条，满了拒绝写入；`0` 表示不限 |
+| `maxAgentsBytes` | `10000` | 全局 AGENTS.md 的字节上限，超了拒绝写入；`0` 表示不限 |
+| `globalMemoryDir` | 空 | 跨项目记忆库的位置；空表示 `~/.dsh/dsh-workspace-memory/global/memory/` |
+| `globalIndexMaxLines` | `60` | 跨项目记忆库的索引每轮最多显示几行；`0` 表示不显示 |
+| `prefetchRecall` | `true` | 每轮按你的话预取最相关的几条记忆 |
+| `pathsHint` | `true` | 读写与某条记忆相关的文件时，在工具结果末尾提示 |
+
+完整的配置列表和每项的取值范围见 [docs/DESIGN.md](docs/DESIGN.md) 的「配置」。
+
+## 数据存在哪 / 隐私
+
+所有数据都在本机。插件自己不发网络请求；打开自动抽取后，它会经 DSH 调用当前会话所用的模型；`leanvec` 的安装脚本会从 npm 下载一次。
+
+- 全局 AGENTS.md：`~/.dsh/AGENTS.md`；插件每次改写前把原文件备份到 `~/.dsh/.dsh-workspace-memory-history/agents/`，保留最近 20 份。
+- 项目记忆库：`~/.dsh/projects/<工作区>/memory/`，一条记忆一个 Markdown 文件，旁边的 `MEMORY.md` 是索引。
+  这里的「工作区」是你在 DSH 里注册的工作区，整个工作区共用一个库。
+- 跨项目记忆库：`~/.dsh/dsh-workspace-memory/global/memory/`。
+- 待确认草稿：`~/.dsh/projects/<工作区>/.memory-state/pending/`。
+- 历史版本：每个库旁边的 `.memory-state/history/`，覆盖或删除前留档，每条记忆保留最近 20 版。
+- 语义检索的向量只在进程内存里，不写到磁盘，重启后第一次检索时重建。
+
+记忆都是普通的 Markdown 文件，插件卸了、坏了，记忆都还在，可以直接用编辑器看和改（改完运行一次 `/memory reindex`）。
+设置了环境变量 `DSH_HOME` 时，上面所有的 `~/.dsh` 都换成它。
+
+## 效果怎么样
+
+在目标模型（Ollama 上的 DeepSeek V4.1 Flash，也就是 DSH 里实际在用的模型）上，用 52 个合成的对话场景实测：
+模型该记的记了、不该记的没记、东西写到了对的地方，才算判对。
+
+| 指标 | 结果 |
+|---|---|
+| 最新版，正常收尾的 46 个场景 | 判对 45 个（另有 6 个场景在步数上限内没跑完，不计入） |
+| 同一模型对照改动前（两版都正常收尾的 20 个场景） | 改动前 13 个，改动后 18 个 |
+
+几点要如实说明：场景是合成的，不是真实对话；对话在模拟的宿主和虚拟的仓库里进行，插件这一版还没有在真实 DSH 里逐项验证过；
+每个场景基本只跑了一次，单题的对错会有波动，部分类别的结果来自稍早一点的版本。
+详细记录见 [HANDOFF.MD](HANDOFF.MD) 第二十五节和 [docs/DESIGN.md](docs/DESIGN.md) 的「写入怎么衡量」。
+
+## 已知限制
+
+- **证据核对只核出处，不核语义。** 它能确认「这句话确实是你说的、和这条记忆沾边」，判断不了意思有没有被曲解（比如只截了否定句的后半句）。
+  所以要写进全局 AGENTS.md 的一律由你确认，核对不上的在面板上标「说是你的原话 · 没核对上」。
+- **面板用的本机 HTTP 接口没有鉴权**（DSH 的网页服务本身不提供）。插件保证的是记忆工具不会直接写常驻的全局 AGENTS.md，
+  不是本机上的程序无论如何都改不了它。
+- **配置写错不会报错。** 插件没有声明配置表单，写错的值会悄悄回落成默认值；问题会列在 `memory_status` 的配置问题里。
+- **常驻写入常常多花一步。** 模型第一次写全局 AGENTS.md 时往往没指明是新章还是更新哪一章，会被要求先选一次再重试。
+- **不做跨语言的语义匹配。** 记忆尽量用你平时提问的语言写，中文问题找英文记忆效果会差。
+
+## 环境要求
+
+| 项 | 要求 |
+|---|---|
+| DSH | `>= 0.2.1-rc.5 < 0.3.0` |
+| Node | `>= 18` |
+| 运行时依赖 | 无；`leanvec` 可选，约 85 MB |
+
+## 卸载
+
+在插件列表里禁用或移除本插件即可（移除：`plugin_manager remove_bundle --target dsh-workspace-memory`）。记忆数据不在插件目录里，卸载后都还在：要彻底清掉，删除 `~/.dsh/projects/<工作区>/memory/`
+与旁边的 `.memory-state/`、`~/.dsh/dsh-workspace-memory/`、`~/.dsh/dsh-workspace-memory-deps/`、`~/.dsh/.dsh-workspace-memory-history/`。
+全局 AGENTS.md 是你自己的文件，插件写进去的章节不会随卸载删除，需要的话在里面手动删。
+
+## 参与开发
+
+- `npm test`：跑全部测试，测试只在临时目录里读写。
+- `node eval/remember.mjs`：主路径评测，模拟对话、让模型真实调用记忆工具并计分；要调模型、会消耗额度，手动跑。
+- [docs/DESIGN.md](docs/DESIGN.md)：设计取舍、踩过的坑、评测细节。
+- [HANDOFF.MD](HANDOFF.MD)：当前状态、事故记录、还没验证的地方。
+- [CLAUDE.md](CLAUDE.md)：给编码 agent 的仓库导航和容易再踩的坑。
+
+## 许可
+
+MIT