前言¶
在 DSH（DeepSeek Harness）里跑长会话时，常见问题不是「完全记不住」，而是记忆混在一起：上一个项目的坑被带进下一个项目；计划、状态写在聊天里，一压缩就丢；多个智能体改同一份笔记，互相覆盖。全局单一记忆库能存东西，却难和「当前工作区」对齐。
下面介绍维护者 a4223091 发布的 dsh-memory-book（社区分类：记忆）。它是 DSH 的按项目本地记忆插件：全局库、主项目库与临时项目库分层注入，固定项目文档带版本历史，并由引擎在回合结束时触发补更维护。记忆全部是磁盘上的 Markdown，不上云、没有后台定时任务。插件适配 DSH 0.2.1-rc.3 的插件机制，需要 Node.js ≥ 22，当前包版本 0.13.0，许可 MIT。
这是什么¶
dsh-memory-book 给 AI 编码会话提供长期、可审计的项目记忆：
| 能力 | 说明 |
|---|---|
| 按项目隔离 | 项目对应 DSH 左侧工作区文件夹，记忆落在 <工作区>\.memory-book\ |
| 三层注入 | 全局 + 主项目（始终注入）+ 临时项目（cd 到别的项目时追加） |
| 固定文档 | 说明及目标、策划、计划、状态、交接、决策历史、项目经验；引擎管版本与格式 |
| 引擎强制维护 | 检测到实质变化后自动追加补更轮，减少文档腐烂 |
| 并发安全 | 先读再写、mtime 乐观锁、based_on 比较并交换、原子写 |
本地包名为 @local/dsh-memory-book（本地开发占位名）；侧边栏提供项目文档、知识库与配置浏览。
三层记忆与目录结构¶
注入规则¶
| 库 | 位置 | 何时注入 |
|---|---|---|
| 全局库 | %USERPROFILE%\.dsh\memory\ |
任何会话都注入 |
| 主项目库 | <会话所属工作区文件夹>\.memory-book\ |
任何会话都注入 |
| 临时项目库 | <当前工作目录所属项目>\.memory-book\ |
仅当 cd 到另一个项目时追加 |
主项目在会话创建时确定，不随 cd 变化；临时项目每轮按当前工作目录现算。工作目录落在任何项目之外时保持主项目；没有工作区的会话只注入全局。
项目库布局¶
记忆默认不进 git（.memory-book\.gitignore 内容为 *）。典型结构如下：
<项目文件夹>\
.memory-book\
core\核心记忆.md
wiki\{projects,concepts,lessons,profile,entities}\*.md
raw\*.md
project\
说明及目标.md
经验\<类型>.md
策划\<YYYYMMDD-HHmm>.md
计划\<...>.md
状态\<...>.md
交接\<...>.md
决策历史\<...>.md
固定文档不出现在普通索引里；历史版本用 memory 工具的 history 列出，再用 read 查看。
核心功能¶
memory 工具¶
会话内通过 memory 工具读写页面，常用 action 如下：
| action | 必填 | 说明 |
|---|---|---|
| read | path | 读整页，返回 frontmatter、正文、updated、所属库 |
| add | path, content | 新建普通页；content 含 frontmatter（title+summary） |
| patch | path, old_string, new_string | 片段替换，唯一匹配 |
| remove | path | 删除普通页；固定页拒绝 |
| search | query | 主题词检索，多词须同时命中 |
| put | path, content | 全量覆盖固定页（说明及目标或 project/经验/<类型>） |
| record | doc, content, based_on | 为版本化文档新增一版；based_on 为上一版路径，首版传空串 |
| history | doc | 列出某版本化文档全部版本（新→旧） |
scope 可选 current（默认）、main（主项目，不受 cd 影响）、global（全局库）。先读再写：patch / put / record 前须在本会话 read 过目标页；record 必须带 based_on，非最新版本会被拒绝。
注入预算与配置¶
侧边栏「配置」可调 10 项注入与维护节奏（节选默认值）：
| 项 | 默认 | 说明 |
|---|---|---|
| coreChars / mainCoreChars / transientCoreChars | 1200 / 3000 / 800 | 三层 core 字符上限 |
| indexChars / mainIndexChars / transientIndexChars | 1000 / 2500 / 1200 | 三层索引上限 |
| pagesPerDir | 8 | 每个 wiki 子目录最多列几页 |
| fallbackRounds | 5 | 连续多少用户回合无实质变化后让 AI 询问 |
| handoverChanges | 5 | 累计多少次实质变化强制更新交接 |
| autoFollowup | 开 | 引擎自动追加补更轮 |
配置落在 %USERPROFILE%\.dsh\memory\settings.json；删除该文件即恢复默认。
引擎强制维护¶
回合结束（agent/status 进入 idle）时检测，命中规则会追加一轮补更，例如：工作区文件改动或写类工具成功时更新状态/决策历史；todo_write 或目标变化时更新计划与状态；工具连续失败 ≥2 次时写项目经验；固定文档缺失时补建；累计 5 次实质变化时更新交接等。每用户回合最多触发 1 次，避免死循环。
多智能体协作¶
固定文档仅 Lead 可写；Agent Teams 队友与子代理可写经验页与普通页。版本页 frontmatter 记录 by / session，便于追溯。
安装与启用¶
插件以 DSH bundle 形式安装到当前 profile。安装命令须使用资料原文，将 target 换成本仓库在本机的绝对路径：
plugin_manager install_bundle target=<本仓库目录的绝对路径>
本地开发时 profile 里可能是 link: 链接；改完 Host 半边代码后需先卸载再安装才会重新加载：
plugin_manager remove_bundle target=@local/dsh-memory-book
plugin_manager install_bundle target=<本仓库目录的绝对路径>
发布到 npm 或市场前，需把 package.json 的 name 改成自己的作用域，并同步 cordis.patch.yml。
安全提示：插件随当前 DSH 进程权限读写用户目录与项目下的 .memory-book，安装前请自行查阅源码与 MIT 许可证，确认符合你的环境策略。
典型用法¶
1、读项目说明并 patch 片段¶
先 read 再改，避免乐观锁拒绝：
memory action=read path=project/说明及目标 scope=current
memory action=patch path=project/说明及目标 old_string=... new_string=... scope=current
固定页也可用 put 全量覆盖（同样须先 read）。
2、为策划/计划等追加版本¶
版本化文档用 record，并带上上一版路径：
memory action=read path=project/策划/<最新文件名> scope=current
memory action=record doc=project/策划 content=... based_on=project/策划/<上一版路径> scope=current
memory action=history doc=project/策划 scope=current
3、跨项目规则写全局库¶
memory action=add path=wiki/lessons/某主题.md content=---\ntitle: ...\nsummary: ...\n---\n正文 scope=global
memory action=search query=关键词 scope=global
4、从 0.12 单一全局库升级¶
0.13 起项目记忆在各工作区 .memory-book。步骤：
- 备份
%USERPROFILE%\.dsh\memory； - 安装 0.13；
- 将原
wiki/projects/、raw/中属于某项目的页面移到<项目>\.memory-book\对应目录； - 每项目补
project/说明及目标（正文 ≤2000 字），其余固定文档由引擎在首次会话检测缺失后创建。
适用场景与注意¶
适合：长期在 DSH 内维护多仓库、多工作区，需要把规则、计划、交接从聊天里拆到磁盘；需要主项目与临时 cd 项目分层注入；需要 Lead/子代理分工写记忆的场景。
注意：
- 项目判定依赖 DSH 的 workspace 与 working directory 服务，DSH 接口变动需插件跟进。
- 面板在本地浏览器做过渲染与接口测试，不同 DSH 版本的视觉细节可能变化。
- 社区目录 SkillHub 插件页 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；生态上是「一切皆插件」，请自行评估后再安装。
仓库自带四套离线测试（npm test，279 项断言），覆盖 host、routes、client、render，测试会隔离 USERPROFILE / DSH_HOME，不触碰真实记忆。
结尾¶
dsh-memory-book 用三层本地 Markdown 把记忆按项目切开，用固定文档和版本历史留住计划与交接，并用回合结束时的引擎补更缓解「改了代码却忘了更新状态」的问题。若要查看说明与源码，可打开 SkillHub 目录页 与 GitHub 仓库。
