前言¶
在 DSH 里干活的人大多会遇到这类问题：想在对话间隙记点什么，AI 聊天框的输入体验却很别扭；笔记存在别的应用里，思路和维护的成本又上去了。dsh-notes 是维护者 tyouter 给自己写的插件，定位是 DSH 内部的一个笔记本：一个输入框，一个实时排版的预览，只在需要判断时才调用模型。
下面介绍它的定位、安装方式和典型用法。
这是什么¶
tyouter/dsh-notes 是一个 DSH 插件，npm 包名 @tyouter/dsh-notes，当前版本 1.1.2。它以三个页签的形式工作：Capture、History、Board。它是客户端分类下的插件，属于 npm 上的 bundle，一个安装里同时包含宿主半部分、web panel 和 agent presets。
解决的问题可以归纳成三项：
- 打开工具时还想得起要写什么——需要一个启动即写、不需要点工具栏的界面；
- AI 聊天框的输入难受，复杂笔记应用又不断打扰——需要一个”纸”而不是一个”编辑器”；
- 写完的笔记没人看、没人理——需要 AI 在页面边缘等着，而不是插在正文里。
核心功能¶
一张”纸”。 Capture 页只有一个输入框和一张预览页。排版规则很简单：输入的格式只有空格和换行，两个空格生成一个列表项，四个空格生成下一级，手不需要离开键盘。保存时写入的是排版后的文本，预览不是提示而是承诺。
本地排版。 Format 动作是确定性的本地函数 formatLocally，不发请求也没有按钮。它做的工作是规范化分隔符、编号、空行和散落的星号，不动措辞，并且幂等。
AI 在边缘。 Structure 调用模型对当前笔记（或选中的范围）做改写，生成一份草稿，可以选择 Apply、Save 或 Translate；Translate 改变语言，Apply 只替换对应范围。状态栏里等待，你需要时才回答。
历史与看板。 History 把笔记分组成卡片，可以筛选、搜索、打标签；编辑历史条目时会把 Capture 的输入框挂上去，源码在左、排版结果在右，是一个编辑器而不是两个。Board 页是统计信息加上一个真正的 agent session，跑 notes-board 预设，用的是宿主自带的对话组件。
文件即真相。 笔记以普通 JSON 文件存放，数据库是可以删掉重建的投影。README 上的路径结构如下，完整路径取决于工作区。
notes-vault/
notes.json live notes (source of truth)
trash.json deleted notes, kept as a safety net
links.json which session belongs to the notebook
events.jsonl append-only instrumentation: AI calls, UI actions, charts
dashboard.json charts pinned to the dashboard
index.db SQLite projection of the above, for the query tools
不上传。 模型调用走宿主自身的 llm 服务，用 DSH 已配置的 provider 和 key。看板的 assistant 是一个真实的 agent session，工具只有 notes_query（对 index.db 的只读单条 SELECT）、notes_analyze、dashboard_chart 和读写笔记的 notes 工具。
三种 AI 面，三种机制。 这一点在 README 里被单独强调：早期版本曾把截断的文本塞进 prompt，就是因为把三种机制混在了一起。
- Structuring 是一次流式模型调用，没有 session 也没有工具，推理 effort 设为
off； - Completion 只在停止输入一秒后请求下一句，否则用笔记里重复出现的措辞回答，不发请求；
- Board 聊天是建好的 agent session，面板只负责创建和渲染，投递、流式、工具卡片和审批全部由框架负责。
输入框之外也能用。 Alt+N 或输入组件行上的笔记本图标会打开一个浮动卡片；/note 内容 可以直接从聊天框保存一条笔记。
安装与启用¶
包在 npm 上，官方安装命令只有一条，从 DSH 里带 profile 执行：
dsh plugin --profile <name> add @tyouter/dsh-notes
安装后如果安装程序没有自动处理，需要在 profile 的 package.json 里把 @tyouter/dsh-notes 加到 dsh.profile.bundles，然后重启。插件会出现在侧边栏和插件清单里，名字叫 Notebook。
从源码构建的话，README 给出的路径是 clone 下来跑构建，再把目录通过 Plugin Manager / install_bundle 装进去：
git clone https://github.com/tyouter/dsh-notes.git
cd dsh-notes
npm run build # writes client.js from src/
# then install the directory through Plugin Manager / install_bundle
要求：DSH 构建需要带 node:sqlite（Node 24 自带），lib/ 下都是第一方代码，没有其他运行时依赖。若 node:sqlite 缺失，查询工具会自行禁用并说明，笔记本其他功能照常可用。
配置方面，cordis.patch.yml 里的 notesPath 可以改笔记目录；相对路径锚定的是注册表里的默认工作区，不是第一个调用它的 session。
典型用法¶
- 装好后打开侧边栏的 Notebook，停在 Capture 页；
- 直接在一个框里输入，两个空格做列表，四个空格做下一级，右边页面逐键排版；
- 想让 AI 整理结构时，点工具栏的 Structure，右侧出现草稿，可以 Apply、Save 或 Translate；
- 选中编辑器里的文字再翻译，作用范围就是那一段；
- 到 History 页翻历史笔记，搜索或按标签过滤；需要改某条时，点 Edit 挂载输入框，左右两个视图共用一份源码；
- 在 Board 页跟
notes-board对话，让它统计笔记的by_tag、by_day、长度分布等，或用dashboard_chart在看板上钉一张图。
适用场景与注意¶
适合写笔记频繁、又不想让笔记应用打断思路的人。它把”写作”和”AI 辅助”分开：排版不发请求，AI 只在需要判断时出现。对 DSH 使用者来说，它的价值在于笔记和宿主共用一个模型配置。
两点需要留意。第一，插件以当前 dsh 进程的权限运行，安装前应先检查源码与许可证；本插件许可证为 MIT，作者 tyouter，仓库 https://github.com/tyouter/dsh-notes 。第二，它的 agent 会话带有读写笔记的工具，别把它当成一个只读的展示面板。
结尾¶
dsh-notes 的取舍很明确：把存储做简单（JSON 文件），把排版做成确定性的本地步骤，把 AI 留在边缘。这样一个插件的安装是一个 profile 绑定，代价不大。目录页在 https://www.skillhub.cn/plugins/tyouter/dsh-notes ，源码与 README 在 https://github.com/tyouter/dsh-notes 。
