鱼的记忆 ytsu-ki/dsh-relink

dsh-relink · 鱼的记忆

Project memory and native subagent coordination for DeepSeek Harness
面向 DeepSeek Harness 的项目记忆与原生子代理协作插件

English · 简体中文

dsh-relink（原 dsh-memory-team）帮 Harness 智能体不再重复发现它已经知道的东西。每个新请求到达模型之前，它会召回当前项目真正用得上的少量已验证结论；没有相关内容时，它直接说明，而不是塞进噪音。它能把真正独立的调查分给两个原生子代理，还能显示一次慢回合把时间花在了哪里。它从不给模型设截止时间，不取消有效工作，也不截断你要求的输出。

[!NOTE]
这是非官方社区项目，且为预发布版。请先在单独的测试配置档里试用。见状态。

界面

dsh-relink 在隔离的 Harness 配置档中运行

亮点

- 召回相关，不制造噪音。 所有后端共用一套确定性相关性模型。说出记录的键名或完整标题就能找到它；像「请检查这个文件」这类泛泛的请求，什么也召回不到。
- 默认本地运行。 记忆存在本地 SQLite 数据库里，不需要账号、服务或额外的模型调用。可选的 Markdown 仓库兼容 Obsidian 和任何编辑器。
- 后台不跑任何东西。 没有文件监听、定时器或辅助进程。服务首次使用时才启动，外部改动在下一次读取时生效。
- 如实报告健康状态。 每个结果都是 ok、no-match、degraded、withheld 或 unavailable，坏掉的组件绝不会看起来像空记忆。
- 原生协作。 team_start 使用宿主自带的 subagent 工具，所以权限、取消、递归限制和结果投递都归 Harness 管。
- 安全升级。 0.5.x 的数据库和笔记原地读取，并已在同一份数据上与 0.5.3-beta.3 做过往返测试。

0.6 实测

同样的负载对比 0.5.3-beta.3，各跑五次全新进程，取中位数。在 Apple M1 上用带标签的合成语料测得；细节和取舍见 docs/benchmarks.md。

| | 0.5.3-beta.3 | 0.6.0-beta.1 |
| 无关请求仍召回记录的比例 | 40-80% | 0-4% |
| 召回记录的精确率 | 43-71% | 94-97% |
| 对 2,000 条已有笔记的首次 Markdown 搜索 | 861 ms | 312 ms |
| 外部编辑笔记后，下一次搜索可见的延迟 | 224-330 ms | 107-126 ms |
| 桌面运行时冷启动增加的时间 | 约 100-125 ms | 约 50 ms |
| 配置了 vault 后的后台辅助进程 | 约 190 MiB（Basic Memory） | 无 |

有些搜索比之前慢 1-2 ms；基准测试说明解释了原因。

功能

| | 作用 |
| 项目记忆 | 每次新的用户输入到达模型之前，为当前项目补充最多三条相关记录。记录按项目隔离（Git 根目录或工作目录）。过期记录，以及证据文件已变更的记录，不会被自动召回。 |
| Markdown vault（可选） | 把记录存成纯 Markdown，你可以在 Obsidian 里编辑。插件不会自行改写你的笔记；通过保存工具做的替换会在历史中保留上一版本。加上 dsh_private: true 可让某条笔记不参与召回。 |
| 任务记录（需配置 vault） | 把每个完成的回合记成一条未验证的日志笔记（请求、最终回复、结果和工具名），全程不调用模型。推理过程、工具参数和工具输出不会存储。 |
| 子代理协作 | team_start 并行运行最多两项独立调查；父级保留编辑权和最终验收权。team_wait 只等待一次，不轮询。 |
| 执行诊断 | workflow_status 报告步骤、输出、重试和实际耗时明细。每回合最多三条简短提醒，标记重复出现的相同结果或过长的回合；它们从不阻塞工具，也不结束任务。 |

环境要求

- DeepSeek Harness 0.2.1-rc.2 或 0.2.1-rc.3
- Node.js 22.17 或更高版本（Harness 桌面应用已自带合适的运行时）
- 可选：Obsidian、Basic Memory 0.23.2 或 Betterleaks 1.9.0，均需单独安装

安装

1. 从 Releases 下载 dsh-relink-0.6.0-beta.2.tgz，并用 SHA256SUMS 校验。
2. 在 Harness 中打开 Plugins > Add plugin（最好在测试配置档里操作），输入下载文件的绝对路径。
3. 启用 dsh-relink，按提示重启 Harness。

从命令行安装：

dsh plugin --profile my-test-profile add /absolute/path/dsh-relink-0.6.0-beta.2.tgz

就这些：记忆功能配合本地 SQLite 即可立即使用。不要手动编辑配置档清单或 lockfile。

可选：给 Obsidian 用的 Markdown vault

node scripts/setup-knowledge.mjs \
--vault '/absolute/path/to/Obsidian Vault/DSH Knowledge' \
--project '/absolute/path/to/project' \sh
--config-dir '/absolute/path/to/plugin-state'

脚本会创建 vault，并把设置保存到 ~/.local/share/dsh-memory-team/settings.json（这个目录沿用插件的旧名，现有设置才能继续生效），同时备份之前的文件。之后重新加载插件。选项：--seed-file /absolute/notes.json 导入已批准的 [key, title, kind, summary, evidence] 行，不覆盖已有的 key；--no-activate 只准备文件，不改动设置。

在 Obsidian 里编辑笔记时，保留 dsh_ 开头的 frontmatter 字段。不需要安装 Obsidian 插件。

可选：Basic Memory

插件不会启动 Basic Memory，也不依赖它。如果你想让 Basic Memory 自带的工具作用于同一个 vault，请单独安装官方 Basic Memory 0.23.2（在 macOS arm64 上，scripts/basic-memory-macos-arm64.txt 固定了一组已验证的依赖，供 pip install -r 使用），并把 --basic-memory-config /absolute/path 传给安装脚本。按脚本写入的设置，Basic Memory 0.23.2 会索引插件的笔记，但不会修改它们。Basic Memory 0.24 会往笔记里写入 permalink 字段；插件能容忍这一点，但每篇被重写的笔记都会多出一个新修订版本。

可选：用 Betterleaks 扫描凭据 sh
node scripts/setup-retrieval.mjs

下载固定版本的 Betterleaks 1.9.0（macOS 和 Linux，arm64 或 x64），校验 SHA-256 后启用。--archive /absolute/release.tar.gz 可离线安装。没有 Betterleaks 时，内置规则仍会脱敏常见凭据格式。

用法

像平常一样给 Harness 派任务；何时搜索、保存或委派，由模型自己决定。你也可以直接说：

先搜索这个项目的记忆。把实现排查和测试审查交给两个独立的子代理，问题你自己修，然后保存验证过的结论。

| 工具 | 用途 |
| project_memory_search | 搜索当前项目；查询为空时列出最近的记录 |
| project_memory_save | 保存带证据的已验证事实、工作流或坑点 |
| project_memory_forget | 按 key 和当前修订版本删除记录 |
| project_memory_status | 显示后端、存储路径、健康状态和配置问题 |
| team_start | 启动最多两个独立排查 |
| team_wait | 等待一次原生子任务，然后列出任务状态 |
| workflow_status | 显示一轮的步骤、输出、重试和耗时明细 |
json
{
"key": "viewport-acceptance",
"title": "Prerequisites for 1440px acceptance",
"kind": "pitfall",
"summary": "Close overlays before checking button clickability at 1440px.",
"evidence": "Playwright trace showed the cookie banner intercepting clicks.",
"files": ["tests/layout.test.js"]
}
证据文件只做指纹记录，不复制；一旦文件发生变化，记录就不再自动召回。替换记录需要提供当前的 expected_revision，搜索会返回这个值。

配置

所有设置都是可选项，可在插件设置中修改。

| 设置 | 默认值 | 含义 |
| database | $DSH_PROFILE_DIR/data/dsh-memory-team.sqlite | SQLite 数据库（绝对路径） |
| knowledgeRoot | 未设置 | 已有 Markdown 仓库的绝对路径 |
| knowledgeProject | 所有项目 | 只有这个项目使用该仓库，其他项目使用 SQLite |
| projectRoot | 自动 | 绝对根目录，把自身及其子目录归为一组 |
| basicMemoryConfig | $DSH_PROFILE_DIR/data/basic-memory | 历史、回收站和派生索引的状态目录（沿用旧名） |
| incrementalIndex | true | 设为 false 时，派生索引只保留在内存中 |
| betterleaksCommand | 未设置 | Betterleaks 1.9.0 的绝对路径 |
| ttlDays | 30 | 超过这个天数的记录（1-365 天）不再自动召回 |
| recallLimit / recallChars | 3 / 6000 | 每次自动召回的记录条数和字符数 |
| maxWorkers | 2 | 插件拥有的并行子代理数（1-2） |
| repeatThreshold / checkpointSteps / longOutputTokens | 3 / 20 / 4000 | 执行提醒出现的时机 |

为兼容旧配置，basicMemoryCommand 仍会被接受，但会被忽略。默认数据库文件等存储路径保留旧名 dsh-memory-team，这样改名后仍能找到已有数据。

隐私

所有内容都以明文形式存储在本地。召回的片段会随普通请求一起发送给你的模型服务商，因此不要保存凭据或私人对话。保存、记录或召回之前都会筛查凭据；配置了扫描器但扫描失败时，记忆传输会被阻断，而不是放行。在 Windows 上，文件继承所在目录的权限；参见 docs/windows-acceptance.md。

状态

- 已验证： macOS arm64 搭配 DeepSeek Harness 0.2.1-rc.3 桌面运行时（安装、工具、跨进程重启的保存与召回），以及 Node.js 22.17、24 和 26 上的测试套件。详情参见 docs/compatibility.md。
- 尚未验证： Windows 和 Linux，以及桌面窗口本身的冷启动。
- 部分 0.5.x 用户反馈，启用插件后宿主无法启动或退出。原始原因尚未查明。0.6 移除了最可能的故障点：激活时不进行任何文件系统、进程或网络操作，不运行后台进程或文件监视器，所有后台错误都在插件内部处理。
如果 Harness 启动失败，请在恢复对话框中选择 Disable third-party plugins, back up profile patch, and restart（这也会影响其他第三方插件）。请用 bug report template 报告问题，附上对话框里的 crash-...-host.log 和 project_memory_status 的输出，并移除凭据和隐私数据。

从 0.5.x（dsh-memory-team）升级

0.6 以新名称 dsh-relink 发布。先从配置档中移除 dsh-memory-team，再安装 dsh-relink。如果两个都保持启用，后加载的那个会激活失败，于是你可能一直在跑旧版本却毫无察觉。你的设置、数据库和 Markdown 笔记会原样沿用，不需要转换数据。如果你的配置档补丁用 id: dsh-memory-team 覆盖了插件配置，请改成 id: dsh-relink。

回滚就是移除 dsh-relink，再重新安装 dsh-memory-team 0.5.3-beta.3。插件不再启动 Basic Memory，如果你要用它的工具，请自行启动。完整流程和 scripts/migrate.mjs 检查辅助脚本见 docs/migration.md。

文档

| 文档 | 内容 |
| Architecture | 设计决策、数据归属、对账与失败状态 |
| Migration | 从 0.5.x 升级、回滚与契约变更 |
| Compatibility | 支持的版本，以及各项验证的环境 |
| Benchmarks | 方法、结果与取舍 |
| Windows acceptance | Windows 上仍需手动检查的项目 |
| Slow-session notes | 为什么要有执行提醒和耗时分类 |

开发 sh
pnpm install --frozen-lockfile --ignore-scripts
pnpm check
pnpm test
pnpm bench

测试使用官方 Harness 组件和模拟模型，不调用付费 API。设置 BASIC_MEMORY_TEST_COMMAND、BETTERLEAKS_TEST_COMMAND 或 DSH_RELINK_BASELINE_ENTRY 会追加真实服务和回滚检查。pnpm release:prepare 会构建安装包和源码归档，并做交叉校验。

旧的 stream-request guard 仍以 dsh-relink/legacy-stream-guard 提供，但已废弃，将在 0.7.0 移除（详情）。

许可证

MIT。可选工具单独安装，遵循各自的许可证：Betterleaks（MIT）和 Basic Memory（AGPL-3.0-or-later）。Obsidian 是可选编辑器，不是依赖项。

鱼的记忆（dsh-relink）（原名 dsh-memory-team）让 Harness 中的智能体不必反复探索已经知道的事情。每次新请求发送给模型之前，它会为当前项目召回少量真正相关的已验证结论；没有相关内容时，它会如实说明，而不是塞入无关信息。它还可以把真正独立的调查交给两个原生子代理并行处理，并展示一轮缓慢的任务把时间花在了哪里。它从不对模型设置时限、不取消有效工作，也不截断用户要求的输出。

[!NOTE]
这是一个非官方的社区项目，目前为预发布版。请先在单独的测试配置（profile）中试用，详见项目状态。

界面鱼的记忆在隔离 Harness 配置中的运行界面

亮点

- 召回精准，不制造噪声：所有存储后端共用同一套确定性的相关度模型。在请求中写出记录的键名或完整标题即可找到它；「请帮我检查这个文件」之类的泛化请求不会召回任何记录。
- 默认完全本地：记忆保存在本地 SQLite 数据库中，不需要账号、服务或额外的模型调用。可选的 Markdown 知识库可以直接用 Obsidian 或任意编辑器编辑。
- 后台零常驻：没有文件监听、定时器或辅助进程。服务在首次使用时才启动，外部编辑会在下一次读取时生效。
- 健康状态透明：每个结果都标明 ok、no-match、degraded、withheld 或 unavailable，组件故障不会被误认为「没有记忆」。
- 原生协作：team_start 调用宿主自带的 subagent 工具，权限、取消、递归层数限制和结果投递都由 Harness 管理。
- 升级安全：0.5.x 的数据库和笔记原地读取，并且测试过与 0.5.3-beta.3 在同一份数据上来回切换。

0.6 实测数据

在相同负载下与 0.5.3-beta.3 对比，每项在全新进程中重复 5 次，取中位数。测试环境为 Apple M1 和一套带标注的合成语料，方法与取舍详见 docs/benchmarks.md。

| | 0.5.3-beta.3 | 0.6.0-beta.1 |
| 无关请求仍被注入记录的比例 | 40-80% | 0-4% |
| 召回记录的精确率 | 43-71% | 94-97% |
| 首次检索 2,000 条已有 Markdown 笔记 | 861 ms | 312 ms |
| 外部编辑后，下一次检索可见所需时间 | 224-330 ms | 107-126 ms |
| 桌面运行时冷启动增加的耗时 | 约 100-125 ms | 约 50 ms |
| 配置知识库后的后台辅助进程 | 约 190 MiB（Basic Memory） | 无 |

部分检索比以前慢 1-2 ms，原因见基准测试说明。

功能

| | 作用 |
| 项目记忆 | 每次新的用户输入发送给模型前，为当前项目补充最多三条相关记录。记录按项目隔离（Git 根目录或工作目录）。过期记录、以及证据文件已变化的记录不会被自动召回。 |
| Markdown 知识库（可选） | 以纯 Markdown 保存记录，可在 Obsidian 中编辑。插件不会擅自改写你的笔记；通过保存工具替换记录时，旧版本会保留在历史记录中。在笔记中加入 dsh_private: true 即可让它不参与召回。 |
| 任务记录（需配置知识库） | 每轮任务结束后自动记一条未经验证的日志笔记（请求、最终回复、结果和工具名称），不调用模型；不保存推理过程、工具参数和工具输出。 |
| 子代理协作 | team_start 最多并行运行两个独立调查；修改与最终验收仍由主代理负责。team_wait 只等待一次，不轮询。 |
| 执行诊断 | workflow_status 报告步数、输出量、重试次数和耗时分解。每轮最多三条简短提醒，提示重复的相同结果或过长的任务；提醒从不阻止工具调用，也不会结束任务。 |

环境要求

- DeepSeek Harness 0.2.1-rc.2 或 0.2.1-rc.3
- Node.js 22.17 或更高版本（Harness 桌面版已自带合适的运行时）
- 可选：Obsidian、Basic Memory 0.23.2 或 Betterleaks 1.9.0，均需另行安装

安装

1. 从 Releases 下载 dsh-relink-0.6.0-beta.2.tgz，并用 SHA256SUMS 核对校验和。
2. 在 Harness 中打开 Plugins > Add plugin（建议使用测试配置），输入下载文件的绝对路径。
3. 启用 鱼的记忆，按提示重启 Harness。

命令行安装： sh
dsh plugin --profile my-test-profile add /absolute/path/dsh-relink-0.6.0-beta.2.tgz

到这里就可以使用了：记忆功能默认使用本地 SQLite，开箱即用。请不要手动编辑配置清单或锁文件。

可选：配合 Obsidian 使用 Markdown 知识库 sh
node scripts/setup-knowledge.mjs \
--vault '/absolute/path/to/Obsidian Vault/DSH Knowledge' \
--project '/absolute/path/to/project' \
--config-dir '/absolute/path/to/plugin-state'

该脚本会创建知识库目录，并把设置写入 ~/.local/share/dsh-memory-team/settings.json（该目录沿用插件的旧名称，以便继续使用已有设置；原有文件会先备份），完成后请重新加载插件。--seed-file /absolute/notes.json 可导入已审核的 [key, title, kind, summary, evidence] 记录，且不会覆盖已有的键；--no-activate 只准备文件，不修改设置。

在 Obsidian 中编辑笔记时请保留以 dsh_ 开头的 frontmatter 字段。不需要安装任何 Obsidian 插件。

可选：Basic Memory 插件不会启动，也不依赖 Basic Memory。如果你想在同一个知识库上使用 Basic Memory 自带的工具，请另行安装官方 Basic Memory 0.23.2（在 macOS arm64 上，可用 scripts/basic-memory-macos-arm64.txt 中经过验证的依赖版本执行 pip install -r），并在运行设置脚本时加上 --basic-memory-config /absolute/path。按脚本写入的设置，Basic Memory 0.23.2 能索引插件的笔记而不修改它们。Basic Memory 0.24 会往笔记里写入 permalink 字段：插件可以兼容，但每条被改写的笔记都会得到新的修订号（revision）。

可选：使用 Betterleaks 扫描凭据 sh
node scripts/setup-retrieval.mjs

该脚本会下载固定版本的 Betterleaks 1.9.0（支持 macOS 和 Linux 的 arm64 / x64），校验 SHA-256 后启用。--archive /absolute/release.tar.gz 可离线安装。即使不安装 Betterleaks，内置规则也会屏蔽常见格式的凭据。

使用

像平常一样给 Harness 布置任务即可，由模型自行决定何时检索、保存或分派任务。你也可以直接要求：

先检索本项目的记忆。把实现排查和测试审查分别交给两个独立的子代理，由你亲自修复问题，验证通过后保存结论。

| 工具 | 用途 |
| project_memory_search | 检索当前项目；查询为空时列出最近的记录 |
| project_memory_save | 保存带证据的已验证事实、工作流程或踩坑经验 |
| project_memory_forget | 按键名和当前修订号删除一条记录 |
| project_memory_status | 查看存储后端、存储路径、健康状态和配置问题 |
| team_start | 启动最多两个独立调查 |
| team_wait | 等待一次原生子任务完成，并列出各任务状态 |
| workflow_status | 查看一轮任务的步数、输出量、重试次数和耗时分解 |
json
{
"key": "viewport-acceptance",
"title": "Prerequisites for 1440px acceptance",
"kind": "pitfall",
"summary": "Close overlays before checking button clickability at 1440px.",
"evidence": "Playwright trace showed the cookie banner intercepting clicks.",
"files": ["tests/layout.test.js"]
}

证据文件只记录指纹，不复制内容；文件一旦变化，该记录就不再被自动召回。替换已有记录时需要提供当前的 expected_revision，可以从检索结果中获得。

配置

所有设置均为可选，可在插件设置中修改。

| 设置 | 默认值 | 说明 |
| database | $DSH_PROFILE_DIR/data/dsh-memory-team.sqlite | SQLite 数据库（绝对路径） |
| knowledgeRoot | 未设置 | 已存在的 Markdown 知识库的绝对路径 |
| knowledgeProject | 所有项目 | 仅此项目使用知识库，其他项目使用 SQLite |
| projectRoot | 自动 | 绝对路径；该目录及其子目录视为同一个项目 |
| basicMemoryConfig | $DSH_PROFILE_DIR/data/basic-memory | 存放历史版本、回收站和派生索引的状态目录（沿用旧名称） |
| incrementalIndex | true | 设为 false 时派生索引只保存在内存中 |
| betterleaksCommand | 未设置 | Betterleaks 1.9.0 的绝对路径 |
| ttlDays | 30 | 超过该天数（1-365）的记录不再被自动召回 |
| recallLimit / recallChars | 3 / 6000 | 每次自动召回的记录数和字符数上限 |
| maxWorkers | 2 | 插件可并行使用的子代理数量（1-2） |
| repeatThreshold / checkpointSteps / longOutputTokens | 3 / 20 / 4000 | 执行提醒的触发条件 |

为保持兼容，basicMemoryCommand 仍可配置，但会被忽略。默认数据库文件等存储路径沿用旧名称 dsh-memory-team，因此改名后仍能找到已有数据。

隐私

所有数据都以明文保存在本地。召回的摘录会随正常请求发送给你使用的模型服务商，因此请不要保存凭据或私密对话。保存、记录和召回之前都会筛查凭据；如果已配置的扫描器出现故障，插件会阻止记忆传输，而不是直接放行。在 Windows 上，文件沿用所在目录的权限，详见 docs/windows-acceptance.md。

项目状态

- 已验证：macOS arm64 上的 DeepSeek Harness 0.2.1-rc.3 桌面运行时（安装、工具调用、保存以及跨进程重启后的召回），以及 Node.js 22.17、24 和 26 上的测试套件。详情见 docs/compatibility.md。
- 尚未验证：Windows 和 Linux，以及桌面窗口本身的冷启动。
- 部分 0.5.x 用户反馈启用插件后宿主无法启动或意外退出，原始原因至今尚未查明。0.6 消除了最可能的故障点：激活时不进行任何文件、进程或网络操作，不运行后台进程或文件监听，所有后台错误都在插件内部处理。
如果 Harness 无法启动，请在恢复对话框中选择 Disable third-party plugins, back up profile patch, and restart（这也会影响其他第三方插件）。反馈问题请使用 Bug 报告模板，附上对话框给出的 crash-...-host.log 和 project_memory_status 的输出，并删除其中的凭据和隐私信息。

从 0.5.x（dsh-memory-team）升级

0.6 起以新名称 dsh-relink 发布。请先从配置中移除 dsh-memory-team，再安装 dsh-relink。如果两者同时启用，后加载的那个会激活失败，你可能在不知情的情况下继续运行旧版本。已有的设置、数据库和 Markdown 笔记会被原样沿用，无需转换数据。如果你的配置补丁（profile patch）用 id: dsh-memory-team 覆盖了插件配置，请改为 id: dsh-relink。

回退时，移除 dsh-relink 并重新安装 dsh-memory-team 0.5.3-beta.3 即可。新版插件不再启动 Basic Memory，如果你需要使用它的工具，请自行运行。完整步骤和检查工具 scripts/migrate.mjs 见 docs/migration.md。

文档

以下文档为英文：

| 文档 | 内容 |
| Architecture | 设计决策、数据归属、同步方式与故障状态 |
| Migration | 从 0.5.x 升级、回退及接口变化 |
| Compatibility | 支持的版本以及各环境的验证情况 |
| Benchmarks | 测试方法、结果与取舍 |
| Windows acceptance | Windows 上仍需人工完成的验收项 |
| Slow-session notes | 执行提醒和耗时分类的设计背景 |

开发 sh
pnpm install --frozen-lockfile --ignore-scripts
pnpm check
pnpm test
pnpm bench

测试使用 Harness 官方组件和模拟模型，不会调用任何付费 API。设置 BASIC_MEMORY_TEST_COMMAND、BETTERLEAKS_TEST_COMMAND 或 DSH_RELINK_BASELINE_ENTRY 可额外运行真实服务和回退测试。pnpm release:prepare 会构建并交叉校验安装包和源码包。

旧版流式请求守卫仍可通过 dsh-relink/legacy-stream-guard 使用，但已弃用，将在 0.7.0 中移除（详情）。

许可证

MIT。可选工具需另行安装，并遵循各自的许可证：Betterleaks（MIT）、Basic Memory（AGPL-3.0-or-later）。Obsidian 只是可选的编辑器，不是本项目的依赖。