# @duke-dsh-plugins/dsh-memory-manager 中文文档

规范地址：https://npmcn.com/package/%40duke-dsh-plugins/dsh-memory-manager/

版本：1\.5\.0
npm 元数据更新时间：2026-11-10T07:14:16.088Z
中文译文更新时间：2026-11-16T05:36:28.248Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40duke-dsh-plugins/dsh-memory-manager
原文对照：https://npmcn.com/package/%40duke-dsh-plugins/dsh-memory-manager/?lang=original
项目主页：https://github.com/MoonlitDropOfBlood/dsh-memory-manager
源码仓库：https://github.com/MoonlitDropOfBlood/dsh-memory-manager

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：200 kB，9 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-typert-protocol ^0\.1\.0-rc\.7 \|\| ^0\.2\.0-rc\.1
- 首次发布：2026-08-22T23:08:35.665Z
- 最新版本发布：2026-11-10T07:14:15.695Z
- 近 30 天下载量：1959（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

DeepSeek Harness 的持续项目内存,从 ZCode 移植: ZCode- style markdown 内存存储器(每个项目+全局),设置中包含完整的内存管理页面,索引首个即时注入出处,代理内存生命周期(memory sav)

## 安装

```sh
npm install @duke-dsh-plugins/dsh-memory-manager
```

也可以使用：`pnpm add @duke-dsh-plugins/dsh-memory-manager`、`yarn add @duke-dsh-plugins/dsh-memory-manager`、`bun add @duke-dsh-plugins/dsh-memory-manager`

## README

### DeepSeek Harness 记忆管理插件

![DSH plugin](https://img.shields.io/badge/DSH-Plugin-4D6BFE?style=flat) [![MIT License](https://img.shields.io/badge/license-MIT-2EA44F?style=flat)](https://npmcn.com/package/%40duke-dsh-plugins/dsh-memory-manager/LICENSE) ![Web UI](https://img.shields.io/badge/Web%20UI-Yes-22C55E?style=flat)

中文

* * *

为 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) Web UI 打造的**持久化记忆**插件，移植自 **ZCode 的项目记忆（Memory）**：按项目（工作区）保存结构化记忆，并在**设置**里提供完整的记忆管理页面。

记忆以 ZCode 同款 Markdown 格式落盘（`<DSH_HOME>/memories/projects/<project>/memory/*.md`，含 `MEMORY.md` 索引与 `memory_summary.md` 摘要），并支持**一键从 ZCode 记忆目录导入**，把 ZCode 里积累的用户偏好 / 反馈 / 技术参考直接搬进 DSH。

## 功能

| 功能 | 说明 |
| --- | --- |
| 🧠 ZCode 记忆移植 | 沿用 ZCode 的记忆文件格式（YAML frontmatter + 正文）、类型体系（user / feedback / reference / project / other）与按项目分目录的存储布局 |
| ⚙️ 设置中的记忆管理 | 设置面板新增 **记忆管理** 页（侧栏带 brain 图标）：搜索、项目/类型筛选、按项目分组、新建 / 编辑 / 删除 / 查看正文 |
| 🗑️ 回收站（软删除） | 删除不再永久销毁：记忆移入项目回收站并留下「遗忘原因」墓志铭，随时可恢复；只有「彻底删除」才移除文件 |
| 🧬 记忆生命周期 | 置顶（永不被条数上限挤掉）、取代链（`memory_correct` 写新条目并把旧条目标为「已被取代」，旧文件保留可审计且不再注入）、覆盖快照（`.history/` 保留最近 5 版） |
| 🏷️ 来源与时效标注 | 注入的索引行带来源（人工 / AI / 导入）与日期，AI 自己写下的旧结论会被明示为低证据强度；超过类型相关期（user 10 年 / feedback 3 年 / project·reference 180 天）的条目标「可能过时」 |
| 🔍 相似记忆提示 | 新建记忆时按「名称字符相似 + TF-IDF 语义余弦 + 释义改写」三层信号检测近乎重复的旧条目（阈值用真实库 2485 对校准，不误报同前缀不同主题），提示改用 `memory_correct` |
| 🛡️ 并发安全 | 写入走跨进程目录锁 + 原子 rename：两个会话同时改同一条记忆时，后写者收到「已被其他会话修改」冲突而不是互相覆盖；崩溃也不会留下半截文件 |
| 🔄 自动加载到对话 | 每次模型调用自动把「当前项目 + 全局」的记忆**索引**按相关度（置顶 > 类型 > 使用次数 > 新旧）排序注入，省上下文；也可切换为附带正文截断的旧模式 |
| 🤖 Agent 记忆工具 | 注册 `memory_save` / `memory_get` / `memory_list` / `memory_forget` / `memory_correct` / `memory_review` 六个工具：读取全文、跨项目搜索、自我纠错（取代链）、软遗忘、定期体检 |
| 📥 从 ZCode 导入 | 一键扫描 `~/.zcode/cli/memories`（`memory/` + `topics/`），按项目 + 名称去重，不覆盖已有记忆 |
| 🌐 全局 + 项目记忆 | `global` 项目存放跨项目记忆；项目 key 取自工作区路径名，自动清洗为安全片段 |
| 📄 自动索引 | 每次变更自动重写 `MEMORY.md` 索引与 `memory_summary.md` 摘要（含「已被取代」标记） |
| 🌗 主题适配 | 全部使用 DSH 设计 token（按钮为官方 DSH Button 组件），明暗主题自动跟随 |

## 安装

### 标准安装（推荐）

本插件是**标准 DSH bundle**：`package.json` 声明 `dsh.bundle.patch`，包内自带 `cordis.patch.yml`，用官方 `dsh plugin` 命令安装：

```bash
# 本地开发：pnpm 软链到本仓库，改代码即生效（无需重新复制）
dsh plugin --profile web add /path/to/dsh-memory-manager

# 正式发布：从 GitHub Release tarball 安装
dsh plugin --profile web add https://github.com/MoonlitDropOfBlood/dsh-memory-manager/releases/download/v1.5.0/dsh-memory-manager-1.5.0.tgz
```

重启 DSH 后，打开 **设置 → 记忆管理** 即可使用。

> `dsh plugin add` 把插件装成 profile 的 npm 依赖并追加到 `dsh.profile.bundles`，启动时 DSH 自动应用包内的 `cordis.patch.yml` 挂载插件。卸载：`dsh plugin --profile web remove dsh-memory-manager`。

### 宿主兼容性

支持 **DSH 0.1.0-rc.7 ~ 0.2.x**（`engines.dsh: ^0.1.0-rc.7 || ^0.2.0-rc.1`，已在本机 0.2.0-rc.1 与 0.2.2-rc.1 宿主端到端验证）。DSH 0.2.0 起宿主会在启动时按 `peerDependencies` 的 `@deepseek-ai/dsh*` 声明做兼容预检，范围不满足的 bundle 会被静默跳过——如果升级宿主后插件消失，先确认版本声明覆盖了新宿主，再跑 `npm run e2e`（对真实安装验证闸门、Host 激活、CRUD、TypertRegistry 与 client bundle）。

DSH 0.2.2 起设置壳把导航图标改为从 `settings.section.icon` 槽按行 id 取（`settings.section` 本身仍只投影 id/order/label），本插件已原生注册侧栏 brain 图标；0.2.1 及更早的宿主没有该槽，继续走 CSS 兜底路径，两条路径互斥、不会同时渲染。

## 使用

1.  打开 **设置**，侧栏出现 **记忆管理** 页。
2.  列表按项目分组、最新优先；顶部可**搜索**（名称/描述）、按**项目**和**类型**筛选；卡片展示类型徽章与更新时间。
3.  **自动加载记忆到对话上下文**：默认开启。每次模型调用，DSH 会把当前会话工作区项目的记忆 + 全局记忆的**索引**（名称 + 描述 + 来源 + 日期，不含正文）按相关度排序注入给智能体，agent 对某条感兴趣时自行用 `memory_get` 工具读取全文——比全量注入省一个量级的上下文。需要旧行为（每条附带 400 字正文截断）可在记忆管理页打开「注入记忆正文」。
4.  **Agent 回写记忆**：agent 在对话中发现值得长期保留的用户偏好、纠正/反馈、项目约定时，会自己调用 `memory_save` 写入记忆（`origin: agent`），之后每轮索引自动带上它。也可在记忆管理页看到、编辑或删除这些记忆。
5.  **并发与冲突**：如果你在设置页编辑一条记忆的同时另一个会话也改了它，保存会提示「记忆已被其他会话修改，请刷新后重试」，不会悄悄覆盖。
6.  **纠错与遗忘**：旧结论被推翻时 agent 会用 `memory_correct` 写新条目并取代旧条目（旧条目留在磁盘标记「已被取代」、不再注入）；确定无用则 `memory_forget` 移入回收站。`memory_review` 可列出过时 / 长得一样 / 已被取代的条目，相当于记忆体检。
7.  **新建记忆**：填写名称（建议短横线 slug，可含中文）、类型、项目（`global` = 全局，或某个项目名，可参考工作区建议）、描述与 Markdown 正文；可勾选「置顶」让它永远排在索引最前。
8.  **编辑 / 查看 / 删除**：每行右侧操作；编辑会自动留旧版本快照；删除只会移入**回收站**（可在侧栏「回收站 (n)」里恢复或彻底删除）。
9.  **从 ZCode 导入**：一键导入 `~/.zcode/cli/memories` 下各项目的记忆，同名自动跳过，结束后展示每个项目的导入/跳过统计。

## 工作原理

```
DSH Web UI
  └─ client.js (window.__ModuleLoader__.load bundle)
       └─ settings.section 注册「记忆管理」页
            ├─ settings.section.icon 注册侧栏 brain 图标（DSH >= 0.2.2 原生槽；旧宿主走 CSS 兜底）
            └─ ctx.remote.memoryManager.{list|get|create|update|delete|forget|restore|purge|importZCode|getConfig|setConfig}
                 └─ index.js (MemoryService, TypertRemoteService)
                      ├─ systemPrompt.section（order 90）→ 每次模型调用注入「记忆索引」段落
                      │    └─ context.agent.session.header.cwd → 项目 key → 项目 + 全局记忆索引
                      │       （置顶 > 类型权重 > 使用次数 > 新旧；带来源/日期/可能过时标记）
                      ├─ ctx.tools.register → memory_save / memory_get / memory_list /
                      │                       memory_forget / memory_correct / memory_review
                      │    └─ systemPrompt.section（order 100）→ 工具使用指引
                      └─ memory-core.mjs（node:fs 直接读写）
                           ├─ <DSH_HOME>/memories/projects/<p>/memory/<name>.md
                           ├─ <DSH_HOME>/memories/projects/<p>/.archive/      （回收站，优雅遗忘）
                           ├─ <DSH_HOME>/memories/projects/<p>/.history/      （覆盖快照，保留最近 5 版）
                           ├─ <DSH_HOME>/memories/projects/<p>/MEMORY.md
                           ├─ <DSH_HOME>/memories/projects/<p>/memory_summary.md
                           └─ <DSH_HOME>/memories/config.json（autoLoad / injectBody 开关）
```

记忆存储走 `node:fs` 直接落在 `<DSH_HOME>/memories/`（与 DSH 核心写 `~/.dsh` 的方式一致），无需 shell 沙箱。

## 目录结构

```
dsh-memory-manager/
├── index.js            # Host 半：MemoryService（Remote 服务）
├── client.js           # Client 半：设置「记忆管理」页 UI bundle
├── typert.host.js      # Typert Host manifest（Remote 方法描述）
├── memory-core.mjs     # 共享记忆核心（frontmatter / 存储 / 索引 / ZCode 导入），零依赖
├── cordis.patch.yml    # dsh bundle patch（挂载行）
├── scripts/self-test.mjs # 独立核心自测（无需 DSH 进程）
├── .github/workflows/  # GitHub Actions 发布
├── AGENTS.md           # 面向 AI agent 的开发指南（含踩坑）
└── LICENSE             # MIT
```

## 开发

```bash
npm run check           # 全文件语法检查
npm test                # 独立核心自测（CRUD / 索引 / ZCode 导入 / 遗忘·取代链·相似度 / 注入排序）
npm run e2e             # 对真实 DSH 安装跑端到端（启动闸门 / Host 激活 / Remote / 工具 / client bundle）
dsh plugin --profile web add /path/to/dsh-memory-manager   # 安装/重装到本机 DSH profile
```

详见 [AGENTS.md](https://npmcn.com/package/%40duke-dsh-plugins/dsh-memory-manager/AGENTS.md)——记录了 DSH 正式插件（Host/Client/Typert 三件套）的完整机制和踩坑。

## License

本项目遵循 [MIT License](https://npmcn.com/package/%40duke-dsh-plugins/dsh-memory-manager/LICENSE)。

> 本项目是基于 DeepSeek Harness 构建的社区插件，并非 DeepSeek 官方产品。记忆格式移植自 ZCode 的项目记忆设计。

## 常见问题

### @duke-dsh-plugins/dsh-memory-manager 是什么？

DeepSeek Harness 的持续项目内存,从 ZCode 移植: ZCode- style markdown 内存存储器\(每个项目\+全局\),设置中包含完整的内存管理页面,索引首个即时注入出处,代理内存生命周期\(memory sav\)

### 如何安装 @duke-dsh-plugins/dsh-memory-manager？

在项目目录运行 npm install @duke-dsh-plugins/dsh-memory-manager，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-typert-protocol（^0\.1\.0-rc\.7 \|\| ^0\.2\.0-rc\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @duke-dsh-plugins/dsh-memory-manager 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/duke-dsh-plugins\_\_dsh-memory-manager 是否存在。

### @duke-dsh-plugins/dsh-memory-manager 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @duke-dsh-plugins/dsh-memory-manager 可以商用吗？

@duke-dsh-plugins/dsh-memory-manager 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @duke-dsh-plugins/dsh-memory-manager 的下载量有多少？

根据 npm 官方下载统计，@duke-dsh-plugins/dsh-memory-manager 在 2026/10/13 – 2026/11/11 这 30 天内被下载 1,959 次，日均约 65 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @duke-dsh-plugins/dsh-memory-manager 还在维护吗？

最新版本 1\.5\.0 发布于 2026/11/10（5 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/08/23。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

