前言¶
在 DSH 里跑 agent 时，常见需求是把决策、摘录或模板写进工作区文件，并在后续回合里继续读改。若只靠通用写文件工具，缺少「读—改—写」之间的版本校验，并发或重复编辑容易互相覆盖。下面介绍社区插件 dsh-notes（维护者 LIghtJUNction，目录分类为「记忆」）：它在工作区 .dsh-notes/ 下提供平面 Markdown 笔记与模板，更新和删除必须携带上次读取返回的 revision（内容为 UTF-8 的 SHA-256）。插件不提供自动会话召回、后台记忆，也不是 DSH session-search 的替代实现。
这是什么¶
dsh-notes 是面向 DSH 0.2.1-rc.2 的 Markdown 笔记工具，npm 包名 @lightjunction/dsh-notes，当前资料中的版本为 0.1.0，许可证 MIT。笔记保存在 .dsh-notes/notes，模板保存在 .dsh-notes/templates。所有文件操作走 DSH 进程所在主机的 Node 本地文件系统，不是远程 world 或 sandbox；仅在 host-local 工作区启用。
核心功能¶
插件通过 Cordis 注册工具 id dsh-notes，向 agent 暴露五类操作：
| 工具 | 主要参数 | 行为 |
|---|---|---|
notes_list |
collection? |
按名称列出笔记或模板，最多 1000 项，超出时返回 limited: true |
notes_read |
path, collection? |
返回 { path, content, revision } |
notes_create |
path, content, template?, collection? |
新建文件，拒绝覆盖；可选模板原文加在 content 前（不自动加换行） |
notes_update |
path, content, revision, collection? |
revision 匹配后整文件替换 |
notes_delete |
path, revision, collection? |
revision 匹配后永久删除 |
collection 只能是 notes（默认）或 templates。模板与笔记共用同一套读写删工具。
约束要点（与 README 一致）：
- 文件名：平面 ASCII，首字符为字母或数字，其余为字母、数字、点、下划线或连字符，以
.md结尾，最长 123 字符；不支持子目录、绝对路径、重命名或 Pi TUI。 - 单文件上限 256 KiB；拒绝符号链接目录/文件，拒绝读取硬链接文件。
- revision 相同内容相同，不是递增序号，无法检测「改回原内容」的 ABA 情况。
- 多进程写同一 store 时用
.dsh-notes/.write-lock协调；锁忙需重试，崩溃遗留锁需确认无写入者后手动删除。
安装与启用¶
面向 Node 24+（README 写明本地验收为 Node 26）。GitHub Release 发布 v0.1.0 后，可按 tarball 安装；README 注明该说明不表示版本一定已发布：
dsh plugin --profile tui add https://github.com/LIghtJUNction/dsh-notes/releases/download/v0.1.0/lightjunction-dsh-notes-0.1.0.tgz
包内自带 cordis.patch.yml。在 profile 的 cordis.patch.yml 或 --patch overlay 中配置：
- id: dsh-notes
config:
root: /absolute/path/to/project
不设置 root 时，使用调用 agent 的 workingDirectory 服务；没有 agent 的直接工具调用必须提供 root。
典型用法¶
1、创建模板与基于模板的笔记
先建模板，再创建引用该模板的笔记：
{"tool":"notes_create","arguments":{"collection":"templates","path":"decision.md","content":"# Decision\n\n"}}
{"tool":"notes_create","arguments":{"path":"cache.md","template":"decision.md","content":"Use a bounded local cache."}}
{"tool":"notes_read","arguments":{"path":"cache.md"}}
2、带 revision 的更新
将 notes_read 返回的完整 revision 填入下一次更新：
{"tool":"notes_update","arguments":{"path":"cache.md","revision":"<revision returned by notes_read>","content":"# Decision\n\nUse a 256-entry local cache."}}
3、用自然语言驱动 agent
也可以直接要求 agent：「把我明确选择的这段对话摘录保存到 decision.md。」agent 通过 notes_create 保存你给出的文本；插件不会自动读取或导出整段会话。
适用场景与注意¶
适合谁： 需要在当前 DSH 工作区里维护少量结构化 Markdown（决策记录、缓存策略说明、可复用模板），并希望通过 revision 降低并发覆盖风险的开发者。
务必知晓：
- 笔记内容会进入模型上下文与正常工具记录，不要把密钥等秘密写进笔记。
- 工具在 DSH 进程权限下运行，安装前请自行查看源码与 MIT 许可证。
- 不要在插件写入期间用外部编辑器改同一文件；插件不是 OS 级权限隔离。
- 社区目录页 skillhub.cn 上的 dsh-notes 与 GitHub 仓库由社区维护，与 DeepSeek / 幻方无官方从属关系；DSH 生态理念是「一切皆插件」，目录站是独立站点。
结尾¶
dsh-notes 把「列表 / 读 / 建 / 改 / 删」收敛到 revision 校验的 Markdown 文件上，适合作为 agent 可调用、可审计的本地笔记层，而不是全自动记忆系统。进一步细节见 GitHub：LIghtJUNction/dsh-notes。
