前言¶
在 DeepSeek Harness（DSH）里跑多轮、多智能体任务时，笔记和结论往往散落在对话与工具返回值里。只靠会话上下文或纯文本摘抄，很难表达「这条结论和那条事实有多相关、置信度如何」，也不方便跨会话复用。向量检索能找相似段落，但弱于显式的图结构与可计算的遍历。
下面介绍社区插件 dsh-notemap（snow-the/dsh-notemap）：在 DSH 进程内维护一张带量化关系的笔记图谱，通过 notemap_* 工具供智能体读写与查询；自 0.12.0 起为 Headless 形态，不提供画布 UI，由 agent 直接查图。
这是什么¶
- 定位：Shared knowledge graph for DeepSeek Harness（
package.json中的description）。 - 维护者：GitHub 用户 snow-The。
- 分类：社区目录 SkillHub 将其归为「记忆」；仓库当前 0 star（GitHub 页面与目录页一致）。
- 许可证：MIT（
package.json）。 - 当前版本：
0.15.0（SkillHub 目录页与package.json一致）。
插件通过 Cordis bundle patch 注册为宿主插件 dsh-notemap，包名为 @snow-the/dsh-notemap：
# cordis.patch.yml（节选）
- insert:
- id: dsh-notemap
name: '@snow-the/dsh-notemap'
注释说明：宿主注册 notemap_* 图工具；0.12.0 起已移除 canvas UI，仅保留无头工具面。
核心功能¶
以下能力均来自 package.json 简介、CHANGELOG、cordis.patch.yml 与仓库测试/类型声明，未单独编造成户案例。
笔记与量化关系¶
图谱节点为笔记（note），边带 weight / confidence 等量化关系（简介与测试中的 addEdge 用法）。写入侧测试覆盖 notemap_add（可指定 title、content、id、provenance 等）；节点 meta.provenance 可取 agent_authored、session_derived、external_source。
图算法与检索工具¶
CHANGELOG 与测试用例体现的工具面包括（共约 27 个注册工具，以仓库 test/tools.test.mjs 为准）：
| 方向 | 工具名（示例） | 作用概要 |
|---|---|---|
| 检索 | notemap_search、notemap_recall、notemap_fusion |
按关键词等在图中检索、召回与跨会话/跨 agent 融合索引 |
| 遍历 | notemap_neighbors、notemap_related、notemap_paths、notemap_common、notemap_context |
邻接、相关节点、路径（含 BFS/Dijkstra 等图算法场景）、共同邻居、以 seed 为心的子图 |
| 分析 | notemap_centrality、notemap_pagerank |
中心性与 PageRank |
| 元数据 | notemap_labels、notemap_stats、notemap_filter |
标签（默认按度数排序；prefix 为子串匹配）、统计、结构化过滤 |
| 解析 | notemap_resolve |
将 ID 或标题 解析为节点；返回 matched_by（id / title / ambiguous / none），不静默猜错节点 |
| 协作 | notemap_agents、notemap_consensus |
与多 agent 相关的索引/共识查询 |
| 数据 | notemap_export |
导出图数据（0.12.0 之前读工具异常时仍可通过其访问数据） |
| 维护 | notemap_add、notemap_autolink（0.11.2） |
写入笔记；bigram-Jaccard 语义自动连边 |
列表类读工具返回带 items、total、returned、truncated、unknown_id 的 envelope，用于区分「没有结果」与「句柄未解析」或「结果被截断」。
快照与会话导入¶
简介提到 DuckLake-inspired snapshots；notemap_stats 的渲染测试入参含 snapshots 字段。导出的 importSessions() 可从会话目录导入 checkpoint/event，并支持 assistant/message 事件（0.11.2 CHANGELOG）。
检索信号（L4）¶
退化检索（截断、未解析句柄等）会写入检索日志，默认路径为 <DSH_HOME>/notemap-retrieval.jsonl，可由环境变量 DSH_NOTEMAP_RETRIEVAL 覆盖（dist/index.d.ts 与测试）。与 dsh-session-handoff 的 acp_status 有跨插件约定（CHANGELOG 0.14.0–0.15.0）。正常、完整的检索 deliberately 不记入，以免稀释信号率。
运行形态¶
- Headless：智能体通过 DSH 工具调用查图，无画布界面（
cordis.patch.yml与简介）。 - 依赖：
peerDependencies要求@deepseek-ai/dsh、@deepseek-ai/dsh-tools均>=0.2.0-rc.1；engines.dsh为>=0.2.1-rc.2 <0.3.0-0。package.json中dsh.compatibility.verifiedAgainst为0.2.1-rc.2（该字段供人与 CI 阅读，宿主加载门禁以peerDependencies为准，见docs/compatibility.md）。
安装与启用¶
SkillHub 目录页标注本插件 可安装，但当前 暂无 README，抓取到的页面也未包含明文安装命令。安装前请自行在 GitHub 仓库 核对源码与 MIT 许可证，并确认 DSH 版本满足 peer 与 engines 约束。
宿主侧插件标识与 npm 包名如下（来自 cordis.patch.yml / package.json）：
插件 id：dsh-notemap
npm 包名：@snow-the/dsh-notemap
版本：0.15.0
数据路径相关环境变量在仓库测试中使用（首次加载插件前设置）：
# 测试套件中的约定（test/tools.test.mjs）
export DSH_DATA_DIR=/path/to/your/dsh-data
export DSH_NOTEMAP_DB="$DSH_DATA_DIR/g.db"
export DSH_NOTEMAP_RETRIEVAL="$DSH_DATA_DIR/retrieval.jsonl"
具体如何把 @snow-the/dsh-notemap 加入你的 DSH profile，请以你本机 DSH 文档或 SkillHub 安装入口为准；请勿在未核对资料的情况下臆造 dsh plugin add 参数。
典型用法¶
仓库没有 README，下列步骤复现自 test/tools.test.mjs 对工具边界的 conformance 测试，展示智能体侧常见调用参数（在 DSH 中对应同名 notemap_* 工具）。
1、写入一条笔记并标明来源
// 等价于智能体调用 notemap_add
await notemap_add.execute({
title: 'provenance probe',
provenance: 'external_source',
}, {});
// 未声明 provenance 时默认为 agent_authored
2、用标题或 ID 解析节点（遍历类工具只吃 ID）
await notemap_resolve.execute({ handle: 'zig compiler notes' }, {});
// resolved: true, matched_by: 'title', id: 'zig-1'
await notemap_neighbors.execute({ id: 'zig-1' }, {});
// items 为邻接记录；unknown_id 为 null 表示句柄有效
3、检索与图分析
await notemap_search.execute({ q: 'zig', limit: 5 }, {});
await notemap_paths.execute({ from: 'zig-1', to: 'misc-1' }, {});
await notemap_pagerank.execute({}, {});
await notemap_fusion.execute({ q: 'zig', limit: 5 }, {});
4、处理「空结果」与「未找到」
未解析的 ID 会在 envelope 中给出 unknown_id，例如：
await notemap_neighbors.execute({ id: 'definitely-not-a-node' }, {});
// items: [], unknown_id: 'definitely-not-a-node'
notemap_context 对子图使用 unknown_id 字段（0.15.0 起与列表工具词汇统一），未解析 seed 会写入检索日志 kind: "graph"。
经过上面的步骤，agent 可以在不打开 UI 的情况下维护一张可查询、可度量关系的共享笔记图，并在多会话场景下借助 notemap_fusion、importSessions 等能力做融合与导入（行为细节以仓库源码与 CHANGELOG 为准）。
适用场景与注意¶
适合谁
- 需要在 DSH 内长期沉淀结构化笔记，并显式维护关系权重、路径与中心性的团队或个人。
- 多 agent / 多会话希望共用同一图谱与融合索引，而不是每次从零复述上下文。
- 接受 无头 工作流：由模型通过工具 API 操作图，而非图形画布。
注意事项
- 权限：插件随当前 dsh 进程 运行，读写其配置的数据目录与 SQLite（测试中使用
DSH_NOTEMAP_DB）；安装前务必审阅源码与许可证。 - 文档缺口：SkillHub 与 GitHub 目前均无 README；
docs/compatibility.md只覆盖加载期 peer 判定，不保证功能端到端可用，并明确未跑通全量测试矩阵。 - 版本：
engines.dsh带上界<0.3.0-0，升级 DSH 主版本前需重新核对兼容性。 - 生态：DSH 奉行「一切皆插件」；SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-notemap 把「笔记 + 量化关系 + 图算法 + 快照/会话导入 + 跨会话融合」收敛到一组 notemap_* 工具里，适合作为 DSH 记忆类插件的无头图谱后端。查阅安装与更新请以社区目录与仓库为准：
- 目录页：https://www.skillhub.cn/plugins/snow-The/dsh-notemap
- 源码：https://github.com/snow-The/dsh-notemap
