前言¶
在 DeepSeek Harness（DSH）里跑智能体时，单次会话的上下文窗口会截断历史；把事实写进普通文件或笔记，检索又往往靠关键词，语义相近的表述容易漏掉。社区插件 dsh-vecrecall（维护者 snowfoxHQ）把 vecRecall 接到 Harness 工具注册表上，提供本地优先、四层结构（L0 身份 / L1 关键时刻 / L2 语义 / L3 深度检索）的持久记忆，并带混合检索与意义级去重，数据落在本机磁盘。
下面介绍插件定位、工具能力、安装步骤与配置要点。事实以 GitHub 仓库 README 为准；目录页见 SkillHub 插件页。SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
dsh-vecrecall 是 DeepSeek Harness 插件（npm 包名 dsh-vecrecall，当前版本 0.1.2，MIT 许可证）。它在 Harness 上注册六个 vecrecall_* 工具，后端由 vecRecall 引擎承担：记忆以明文文件形式存放在你配置的目录，嵌入与检索在长驻 Python 进程中完成，避免每次工具调用都重新加载嵌入模型（README 称冷启动约 23 秒，之后单次调用约 20–120ms）。
核心功能¶
四层记忆与 vecRecall¶
vecRecall 被描述为 local-first 的四层认知记忆引擎：L0 身份、L1 关键时刻、L2 语义、L3 深度检索；支持混合检索、意义级去重，数据存于本机。
六个工具¶
插件挂载的工具如下（名称均以 vecrecall_ 为前缀）：
| 工具 | 作用 |
|---|---|
vecrecall_remember |
写入可长期保留的事实；近义重复会合并，而不是堆叠多条。 |
vecrecall_recall |
纯语义搜索；无结果表示确实未命中，应视为信号而非失败。 |
vecrecall_context |
组装 L0/L1/L2/L3 四层上下文包；适合会话开始或续聊某主题时使用。 |
vecrecall_list |
按 wing/topic 做结构化列表；也可用来查找待删除条目的 id。 |
vecrecall_forget |
按 id 或无歧义前缀删除一条记忆。 |
vecrecall_stats |
查看存储规模与后端健康状态。 |
使用习惯（来自 README）：content 按原文存储，应写成自洽的陈述句；summary 仅用于展示、不参与检索。不要把整文件或临时工具输出灌进记忆。
安装与启用¶
安装分两步：先装 Python 侧的 vecRecall 运行时，再把插件挂到 DSH profile。
# 1. Python side (vecRecall runtime). There is no PyPI package yet, so install from GitHub:
pip install "vecrecall @ git+https://github.com/snowfoxHQ/vecRecall.git"
# 2. Mount the plugin into a dsh profile
dsh plugin --profile web add dsh-vecrecall
将 web 换成你实际使用的 profile 名。完成后重启该 profile，工具会以 vecrecall_* 出现在注册表中。
若报错「vecRecall 未安装或不可导入」，说明插件启动的 Python 解释器无法 import vecrecall；若包装在虚拟环境中，需在 cordis.yml 里把 python 指到该环境的解释器路径。
配置¶
各字段均有默认值，只需在 cordis.yml 中覆盖必要项。README 给出的插入片段示例：
- insert:
- id: vecrecall
name: 'dsh-vecrecall'
config:
dataDir: '~/.vecrecall' # where memories live, created on first start
wing: 'default' # namespace: a project, user, or domain
embedder: 'auto' # auto | bow | sentence | ollama | api
python: 'python' # interpreter used for the helper process
chain: false # hash chain; ~2x storage, for tamper auditing
startupTimeoutMs: 120000 # first start loads the embedding model
toolTimeoutMs: 120000
maxRenderChars: 8000 # cap rendered output to protect the context window
onSensitive: redact # redact | reject | allow; see "Credentials" below
embedder: 'bow' 可完全离线、无需额外依赖；'auto' 在已安装 sentence-transformers 时选用该方案，否则静默回退到 bag-of-words。若召回结果很少，README 建议安装 sentence-transformers 或显式设置 embedder: 'sentence'。
首次工具调用较慢属预期（加载嵌入模型）；若机器超过 120 秒仍未就绪，可提高 startupTimeoutMs。
安全与凭证¶
辅助服务仅监听 127.0.0.1，并使用每进程随机 bearer token，README 说明不会绑定到对外网卡。记忆以明文存于 dataDir；检索需要嵌入明文，因此秘密一旦写入无法在不牺牲检索的前提下「加密存、明文搜」。写入前会做敏感内容筛查，onSensitive 可选：
| 值 | 行为 |
|---|---|
redact（默认） |
将凭证片段替换为 ***，保留其余可检索语义 |
reject |
拒绝写入并提示模型去掉秘密 |
allow |
原样存储（不推荐） |
README 强调这是模式匹配，不能保证捕获所有裸密码；可靠做法是把凭证放在环境变量或 vault，让智能体只引用变量名（如 DB_URL）。
兼容性与运行环境¶
README 记载：已与 @deepseek-ai/cordis 4.0.5、@deepseek-ai/dsh-tools 0.0.1-rc.1 做验证声明；在 DSH 0.2.1-rc.2（桌面端）上完成工具注册与读写验证。package.json 要求 Node >=20，peer 依赖含 @deepseek-ai/cordis ^4.0.5、@deepseek-ai/dsh-tools ^0.2.1-rc.2。
适用场景与注意¶
适合需要在多轮、跨会话中保留项目事实、偏好或决策理由的 DSH 智能体开发者；需要按语义召回而非仅靠关键词时，vecRecall 的路径比手写 Markdown 笔记更贴近「记忆」语义。
启用前请自行阅读仓库源码与 MIT 许可证。插件以当前 DSH 进程权限运行，记忆目录与 Python 辅助进程同样受该权限约束；勿在未审查的情况下向记忆写入密钥或受监管数据。
