jingchangzhao-gif/dsh-note

dsh-note

CI
License

为 DeepSeek Harness（dsh）智能体提供的长期 markdown 记忆——记住，这样你就不必重复发送。

dsh-note 是编码智能体的持久记忆，用 TypeScript 编写，零运行时依赖。智能体不再携带冗长的对话（并在每一轮为其重复支付 token），而是把重要部分保存在本地 markdown 文件中，之后只回忆其中相关的一小段。上下文保持小巧且按需获取，从而在整个会话中节省 token。

dsh-note 本身不消耗 token——这正是它的全部价值所在。下面的每个工具都是纯粹的本地文件操作（免费）。只有当模型真正被要求思考时才会消耗 token；笔记层只是让这种思考变得小巧：用搜索、尾部读取和有界上下文包，而不是整文件转储。

两个区域，绝不混用

存储被拆分到会话工作区下的两个目录中，因此文章写作和长期记忆永远不会混淆（每个工具都接受 dir 覆盖）：

| 区域      | 默认目录    | 存放内容                                                          |
| --------- | ----------- | ----------------------------------------------------------------- |
| writing | ./notes   | 工作笔记、草稿、文章、会话日志                                     |
| memory  | ./memory  | 长期记忆库：按主题划分的、包含带时间戳条目的文件                    |

记忆库文件是主题文件（例如 decisions.md），其正文是一系列条目，每条以 ##  [标题] 开头。文件可以嵌套在某个区域内（例如 log/today.md）；名称永远不能逃出区域根目录。进程无法读取的文件或子目录会被跳过，因此一个坏的权限永远不会导致整个列表、回忆或搜索失败。读取区域永远不会创建它——缺失的文件夹只会被读作空，只有写入才会创建它。

简单的前置元数据

记忆文件（以及任何笔记）可以以一个简单的 --- 块开头：

title: decisions
tags: tooling, workflow
type: decision
created: 2025-01-03T08:00:00.000Z
updated: 2025-01-05T12:30:00.000Z
summary: compact one-paragraph digest (model-written, on request)

2025-01-05T12:30:00.000Z — merges

decided: use merge commits on paired PRs

- created/updated 时间戳在每次写入时自动维护，无需额外成本。
- summary 是可选的，它是 compact 回忆首先展示的内容。
- aliases（或旧版 alias）是一个逗号分隔的列表，列出笔记响应的其他名称，在解析链接时使用（见 note_links）。
- type: archive 标记压缩归档，回忆/搜索会跳过它们。
- 未知键在重写时会被保留；值就是普通的 key: value 行。
- 开头的 --- 块只有在至少包含一个
key: value 行。以 --- 分隔线开头的笔记会将其保留为正文文本，
而不是让该块被读取（然后删除）为元数据。

工具

| 工具             | 功能                                                                      | 成本 |
| ---------------- | ------------------------------------------------------------------------- | ---- |
| note_remember  | 向写作笔记追加片段（若不存在则创建）                                      | 免费 |
| note_recall    | 读回笔记——全文、最近的 tail 或 compact 视图                           | 免费 |
| note_write     | 完全替换笔记正文（更新、重写、重新排序）                              | 免费 |
| note_edit      | 对正文进行原地字面编辑，前置元数据保持不变                                | 免费 |
| note_list      | 列出某个区域的笔记及其标题 / 类型 / 标签                                  | 免费 |
| note_search    | 跨写作/记忆/全部区域进行免费关键词搜索                                | 免费 |
| note_forget    | 从任一区域删除笔记文件                                                    | 免费 |
| note_stats     | 统计某个区域的规模：文件、归档、条目、字节数、最大文件                    | 免费 |
| note_map       | 勾勒某个区域的轮廓：文件行数 + 最新条目标题，在预算范围内             | 免费 |
| note_links     | 追踪笔记之间的链接：出链、反向链接、失效链接、孤立笔记、孤岛              | 免费 |
| note_rename    | 重命名/移动笔记，并重写指向它的链接                                        | 免费 |
| note_context   | 围绕焦点组装小型有界上下文（优先取尾部）                                  | 免费 |
| memory_add     | 向长期库追加带时间戳的条目                                                | 免费 |
| memory_recall  | 召回最近/相关的小块内容（查询/标签/类型/日期过滤）                    | 免费 |
| memory_update  | 合并前置元数据（summary/tags/…）和/或追加条目                         | 免费 |
| memory_compact | 保留最新的 N 条条目；将较旧的移至 .archive.md                          | 免费 |
| memory_remove  | 删除匹配的条目（有意丢弃，不归档）                                        | 免费 |

真正的推理功能——总结上述上下文、推断接下来会发生什么、提取关键信息、整理草稿顺序——是智能体工作流，将这些免费工具与一个刻意的思考步骤结合起来。有关可直接使用的配方，请参见 docs/workflows.md。

它如何节省 token

1. 小规模召回：使用带 tail 的 note_recall，以及 memory_recall，
后者返回最新优先的条目，受 limit + chars 预算限制——绝不返回整个历史记录。
2. 免费搜索：note_search 是带有片段的纯本地关键词搜索，
因此模型无需自行扫描所有内容即可找到正确的文件。
3. 紧凑回退：带 compact 的 note_recall 返回 summary
字段加上最近的尾部。memory_compact 通过以下方式保持活动库小巧：
将旧条目移入归档。当记忆处理会耗时过长时，
改为抓取紧凑版本。
4. 编辑，而不只是追加：note_write/note_edit 让模型就地重写一条
笔记——只有它真正思考过的文本才会改变。
5. 忘掉其余部分：note_forget/memory_remove 让存储的上下文保持
精简，这样未来的提示词也能保持轻量。
6. 先看大小再回忆：note_stats 报告一个区域包含多少文件、条目和
字节——免费——这样模型就能挑选回忆预算，而不是靠猜。
7. 先看地图再回忆：note_map 返回大纲——文件行、最新条目标题以及
该区域的链接结构——这样模型就能挑对文件，完全不必为条目正文付出
代价。
8. 跟随，而非搜索：note_links 沿着一条笔记已有的链接行走，因此
相关上下文的成本只是一跳，而不是一次关键词扫描——而 orphans
会显示哪些笔记无人触及。

安装

dsh plugin --profile web add dsh-note

工具参考

这些是 dsh 插件工具调用；在 GUI 之外，它们每一个都有
直接的 CLI 等价形式（参见 用法），
而 docs/workflows.md 以两种形式展示了推理工作流。

note_remember

{ "name": "session", "content": "Decided: use pnpm + merge commits on paired PRs." }

如果笔记不存在则创建，否则在 --- 分隔符之后追加。

note_recall

{ "name": "session", "tail": 2000 }

返回 { name, content, truncated }。使用 tail 时，只返回最后 N 个
字符；使用 compact: true 时，返回 summary 字段加上最近的约 800
个字符。

note_write

{ "name": "article.md", "content": "# New order\n\n…", "tags": "draft" }

替换整个正文；给出的 front matter 键会合并进来，其他键则保留。

note_edit

{ "name": "session.md", "old": "pnpm install", "new": "pnpm i", "all": true }

替换正文中的字面文本（绝不在 front matter 内部）。

note_list

{ "zone": "memory" }

列出带有标题/类型/标签的笔记；归档在记忆视图中隐藏。

note_search

{ "query": "pnpm merge", "zone": "all" }

返回排序后的命中 { name, title, snippet, score }。零 token。

note_forget

{ "name": "session.md", "zone": "writing" }

note_stats

{ "zone": "memory" }

一个区域的只读清单：活动 files、archives、记忆 entries、
总 bytes，以及最大的文件（名称 + 大小）。除了这些数字之外，不会向
模型返回任何内容，因此不消耗内容 token。

note_map

{ "zone": "memory", "chars": 1200 }

一个区域的免费大纲：每个文件一行（name — title (entries, bytes)）
加上每个文件最新的条目标题，最新的在前，截断到 chars。
条目标题通常承载要点（2024-06-01 — use pnpm），因此一张地图
通常足以决定要召回 _哪个_ 文件，而无需为条目正文付出代价。
total 统计区域内的文件数，omitted 则是预算省略掉的那些。

大纲还携带该区域的链接结构——links、broken 和
orphans——以末尾的 links: 3 (1 broken) / orphans: … 行呈现，因此
一次廉价的调用就能同时回答“这里有什么”和“什么与什么相关”。笔记之间没有链接的区域不会多说任何东西（单条笔记的细节见 note_links）。

note_links

{ "name": "session.md" }

免费链接图。带 name 时：该笔记指向什么（out）、什么指回它（back），以及它悬空的目标（broken）。不带时：该区域的 links 计数、它的 orphans（没有任何链接指向或来自它们）、与最大簇隔断的已链接 islands，以及每个 broken 目标。

Markdown 链接（label，以及用于带空格名称的 ）
和 wikilinks（[[decisions]]，可选 [[target|label]]）都计入。目标的解析方式与笔记生态解析链接的方式一致：先精确的区域相对路径，然后 +".md"，然后唯一的文件基名，不区分大小写且最短路径优先——因此 [[decisions]] 找到 decisions.md，[[today]]
找到 log/today.md。若以上都失败，裸名称可以匹配 front matter 中的
aliases: 条目（aliases: adr, choices 让 [[adr]] 到达该笔记），它
永远不会遮蔽真实文件名。有两个同样好的候选者的名称保持未解析，而不是猜测。

不是笔记之间的链接，因此忽略：URL、页内锚点、绝对路径、
图像和媒体目标、alt 嵌入、围栏代码块内的链接，
以及笔记链接到自身（这只会掩盖没有任何东西到达它）。

note_rename

{ "from": "session.md", "to": "log/session.md" }

移动笔记并重写所有解析到它的链接，这样图就不会断裂。Wikilinks 保持其风格（无扩展名），markdown 链接保持
其扩展名，并且 #anchors、|labels 和链接标题得以保留。通过别名
到达该笔记的链接也会被重写。

dryRun: true 返回计划——哪些笔记会改变以及多少链接——
而不触碰任何文件。已存在的目标名称会被拒绝
而不是覆盖，将笔记重命名为其自身名称是空操作。

note_context

{ "focus": "what should I do next?", "notes": ["session.md"] }

返回一个有界上下文包：指定笔记的近期尾部、针对焦点的搜索
片段，以及近期/相关的记忆尾部。当 chars 预算（默认 6000）紧张时，较旧的部分会首先被丢弃。

memory_add

{ "content": "user prefers dark mode", "tags": "prefs", "type": "preference" }

向 memory.md（或在给出 name 时向其）追加一个 ##  条目。

memory_recall

{ "query": "dark mode", "limit": 5, "chars": 2000 }
最新优先，有界。支持 name、tags、type、newerThan、
olderThan。每个匹配的文件在设置了 summary front matter 字段时以其开头，
然后是其条目。没有过滤器时，它只返回 bank 的近期尾部。

memory_update

{ "name": "decisions.md", "meta": { "summary": "digest: …" } }

合并 front matter 字段；content 追加一个条目。

memory_compact

{ "name": "decisions.md", "keep": 20 }

保留最新的 20 个条目，将其余的移到 decisions.archive.md
（type: archive，对 recalls 和 search 不可见）。

memory_remove

{ "name": "decisions.md", "match": "superseded idea" }

用法 — run.bat / run.command：将其指向一个文件夹，然后操作

启动器是使用 dsh-note 的主要方式。一个逻辑文件（cli.mjs）
在 Windows 和 macOS 上同样运行；run.bat 和 run.command 是轻量
外壳，只是转发每一个参数——因此你给该工具一个具体的
文件夹地址加上一个操作，免费的文件工作就在本地发生。
没有模型，没有网络，没有 token。

首次使用前构建一次（cli.mjs 驱动构建后的 lib/）：

pnpm build

基本形式：

run.bat  [dir] [--flags...]

-  是命令操作的文件夹。普通命令期望
笔记文件夹；memory- 命令期望 memory-bank 文件夹。当
省略时，普通命令默认为 ./notes，memory- 默认为 ./memory。
- 运行 run.bat help（或 run.bat --help）获取完整参考。

Windows：

run.bat list "C:\Users\me\notes"
run.bat remember "C:\Users\me\notes" --name session.md --content "decided: pnpm"
run.bat recall  "C:\Users\me\notes" --name session.md --tail 2000
run.bat write   "C:\Users\me\notes" --name article.md --file new-draft.md --title "Article"
run.bat search  "C:\Users\me\notes" --query "pnpm merge"
run.bat memory-add "D:\memory" --content "user prefers dark mode" --tags prefs --type preference
run.bat memory-recall "D:\memory" --query "dark mode"
run.bat memory-compact "D:\memory" --name decisions.md --keep 20

macOS 完全相同，只是用 ./run.command 代替 run.bat。

| 命令                                                                   | 作用                                            |
| ---------------------------------------------------------------------- | ----------------------------------------------- |
| list [dir] [--zone writing\|memory]                                  | 列出笔记文件及其 title/type/tags                |
| remember  --name f [--content \| --file \| -]                  | 追加一个块（如果缺失则创建）                    |
| recall  --name f [--tail N] [--compact]                        | 读取全文、近期尾部或紧凑视图                    |
| write  --name f (--content \| --file) [--title/--tags/--type]  | 完全替换正文                                    |
| edit  --name f --old x [--new y] [--all]                       | 就地字面正文编辑                      |
| search  --query words [--limit N] [--zone writing\|memory]     | 带片段的关键词自由搜索               |
| forget  --name f                                               | 删除笔记文件                              |
| stats [dir]                                                          | 区域清单：文件、归档、条目、字节 |
| map [dir] [--chars N] [--zone writing\|memory]                       | 勾勒区域：文件行 + 最新标题    |
| mindmap [dir] [--chars N] [--zone ...] [--file out.md]               | 以 Mermaid 思维导图呈现大纲（可渲染）     |
| links [dir] [--name ] [--zone writing\|memory]                 | 跟踪链接：出链、反向链接、失效链接、孤立笔记        |
| linkmap [dir] [--zone ...] [--max N] [--file out.md]                 | 以 Mermaid 流程图呈现链接图           |
| rename [dir] --from  --to  [--dry-run]                     | 移动笔记并重写指向它的链接       |
| export  --file f.json                                          | 将整个文件夹快照为一个 JSON 文件    |
| import  --file f.json [--force]                                | 写回快照（跳过已存在的文件）    |
| context  [--focus q] [--notes a,b] [--memory ]            | 组装一个小型有界上下文包         |
| memory-add  (--content \| --file) [--name] [--tags] [--type]   | 追加一条带时间戳的记忆库条目                 |
| memory-recall  [--query] [--tags] [--type] [--limit] [--chars] | 召回近期/相关的小块内容          |
| memory-update  [--summary etc.] [--content \| --file]          | 合并 front matter / 追加条目               |
| memory-compact  [--name] [--keep N \| --older-than date]       | 将较旧的条目移至 .archive.md            |
| memory-remove  --match text [--name]                           | 删除匹配的条目                         |

注意：

- 在任何命令后追加 --json 可打印结构化结果。
- --zone memory 使 list 和 search 作用于 ./memory 而不是
./notes，并隐藏归档，这与 note_list/note_search 应用的规则相同；
dir 参数仍可将它们指向任何其他文件夹。
- 带单个裸参数的 run.bat  保持旧版启动器形式
（列出该目录）。
- 多词值请加引号。对于中文或多行内容，请传入 --file
（UTF-8）或 --content - 并通过管道传入 stdin。macOS/Linux 上的 "$@"
会逐字节精确转发参数；在 Windows 上 %* 会被 cmd 重新解析（%、
! 和 ^ 是特殊字符），因此在那里处理棘手文本时优先使用 --file 或 stdin。
- linkmap 将图绘制为 Mermaid 流程图：中心节点在前，孤立节点用虚线
表示，孤岛成员用轮廓标出，因此该图能表达 links 所报告的内容。
- --max N 限制绘制的节点数（默认 40，上限 500）。
- export/import 将整个文件夹作为一个 JSON 文件移动（用于备份、另一台
机器、另一个工作区）。import 会跳过已存在的文件，除非传入
--force，因此恢复操作绝不会静默覆盖更新的笔记。
这两个仅限 CLI——agent 工具没有对应的 bundle 等价物。
- 同一个包也可作为 DeepSeek Harness GUI 内的 dsh 插件使用
（dsh plugin --profile web add dsh-note）；它的 17 个工具涵盖了上述笔记
和记忆命令。

开发

pnpm install
pnpm format:check
pnpm typecheck
pnpm build   # 先构建：CLI 及其端到端测试针对 lib/ 运行
pnpm test
pnpm coverage  # 同一套测试，附带 v8 报告和回归阈值
pnpm lint

CI 在 Linux、macOS 和 Windows 上运行完整检查（CLI 附带 run.bat
和 run.command）。Node 22 被固定，因为构建工具链需要它
—— tsdown 需要 ^22.18 || >=24，而 rolldown/oxlint 需要
^20.19 || >=22.12；engines.node >=18 的下限描述的是已发布的
lib/ 输出，而非开发工具链。

许可证

MIT