前言¶
在使用 DeepSeek Harness（DSH）时，对话内容很容易在会话结束后散落。如果不做记录，后续查找和整理会很麻烦。现有的做法通常是手动复制粘贴到文档，既耗时又容易遗漏。
dsh-study-note 是一个 DeepSeek Harness 插件，它让对话按需自动生成结构化的 Markdown 笔记，并维护一个根目录索引。每个对话在开始时默认关闭记录，你需要显式启用，这样不会影响其他对话。
是什么¶
dsh-study-note 是 WaterFountain-Jack 维护的 DeepSeek Harness 插件。它将显式开启的对话转化为 Markdown 学习笔记，并为每个笔记创建单独的文件，同时维护一个根目录的 README.md 索引。
插件通过 /note 命令集控制记录开关、同步、状态查看和主题管理。笔记内容包含问题、结论、解释、公式/代码/示例、AI 起草的理解、未解问题和源轮次编号等区域。后续相关追问会更新同一区域，不相关追问则新增区域。
安装与启用¶
安装前请确保已安装 Node.js 22.19+，并有一个提供 commands、sessions 和 llm 的 DSH 配置文件。插件依赖 DSH 0.1.0-rc.8、0.1.1-rc.2 或 0.2.0-rc.2。
- 克隆插件仓库，安装依赖，打包成安装包：
git clone https://github.com/WaterFountain-Jack/dsh-study-note.git
cd dsh-study-note
npm install
npm pack
- 将打包后的
.tgz文件安装到你指定的 DSH 配置文件中。示例中假设配置文件名为desktop：
dsh plugin --profile desktop add "$PWD/dsh-study-note-0.1.1.tgz"
dsh --profile desktop --dump-config
-
如果 DSH 没有热加载插件，请重启该配置文件。
-
在对话中依次发送以下命令，然后提出学习问题并等待回答：
/note on Cordis
/note status
- 录制会在回答结束后在后台运行。使用以下命令检查和同步：
/note sync
/note status
查看生成的文档和根目录索引。完成后使用 /note off 关闭当前对话的记录。
卸载时保留笔记和本地状态：
dsh plugin --profile desktop remove dsh-study-note
命令参考¶
| 命令 | 行为 |
|---|---|
/note on [topic] |
开启当前对话的记录，仅处理开启后开始的完整轮次。重复使用不会重置检查点。 |
/note off |
取消并等待后台工作完成，保留已有文件。成功后不再对新轮次写入。 |
/note status |
显示开关状态、目录、主题、文件、待处理工作和最新错误。 |
/note sync |
立即处理所有符合条件的已完成轮次。需要在开启状态下运行，不会回填关闭期间的轮次。 |
/note topic <topic> |
固定主题并移动当前对话的笔记，重建索引。 |
/note reindex |
重建插件拥有的根索引，无需模型调用。可在关闭时使用。 |
/note new |
清除关联，需在旧笔记删除或移出根目录后使用。会自动关闭记录。 |
主题命名规则：1–64 个字符，允许字母、数字、下划线、连字符或中文字符，必须以字母或数字开头。固定主题可以创建目录，自动主题选择仅使用现有目录，否则使用 inbox。子代理对话无法开启记录。
笔记与索引结构¶
笔记保存在配置的 notesDir 目录下，结构如下：
~/.dsh/study-notes/
├── README.md
├── Cordis/
│ └── 2026-10-15-Cordis-学习-<session-hash>.md
├── inbox/
└── .study-note/
├── state.json
├── writer.lock
└── requests/
每个文档对应一个对话。相关问题时一个包含问题、结论、解释、公式/代码/示例、AI 起草理解、未解问题和源轮次编号的区域。后续相关追问会更新同一区域，不相关追问则新增区域。手写区域不会被替换，相关追问会追加补充区域。索引只维护 README.md 中 <!-- dsh-study-note:index:start --> 和 <!-- dsh-study-note:index:end --> 之间的内容，外部手写条目保持不变。插件仅索引自己的文档，不会自动整理无关笔记。
配置说明¶
插件条目 ID 为 study-note，可选通过覆盖层指定不同的根目录：
- id: study-note
config:
notesDir: '~/study-notes'
保存覆盖层并在启动时传入 --patch <绝对覆盖路径>，或者将条目合并到你的配置覆盖中。项目不会修改活动配置或现有知识库。
| 字段 | 默认值 | 含义 |
|---|---|---|
notesDir |
~/.dsh/study-notes |
绝对路径或 ~/ 路径，每个同时运行的 DSH 进程建议使用独立目录。 |
debounceMs |
1500 |
完成轮次后延迟多少毫秒开始后台处理。 |
timeoutMs |
60000 |
辅助请求截止时间，包括审计写入。 |
provider、model |
缺失 | 同时提供非空字符串以覆盖，否则复用已完成回答的路径。 |
maxInputBytes |
98304 |
整个分帧辅助请求的 UTF-8 限制，超大会导致明显失败。 |
maxOutputBytes |
65536 |
序列化流块的限制，不仅包括最终文本。 |
maxOutputTokens |
4000 |
辅助输出 token 上限。 |
recentSections |
6 |
作为后续上下文提供的最近笔记区域数量。 |
maxMessageChars |
12000 |
每个问题、回答或区域文本的限制，截断会明确标记。 |
隐私、成本与故障处理¶
从未开启的对话不会产生记录文件或辅助模型调用。录制只选择人类源文本和未来已完成轮次的最后一个完整助手文本，排除推理块、工具结果、图像、注入用户消息和中断输出。本地过滤掉确切确认消息和进度问题，其他无关轮次仍可能需要模型调用以决定是否跳过。
每个符合条件的轮次可能触发对配置提供者的额外付费请求，包括被跳过的内容。同一对话同一时间只运行一个请求，不同对话可并发运行。先前的笔记区域，包括你在这些区域中的编辑，可以进入这些请求。插件不会读取 API 密钥或环境值，但对对话文本中输入的密钥不会进行脱敏。
请求分派前，系统提示、消息路由、token 限制和源事件编号会写入 .study-note/requests/。这些本地审计文件会保留选定的对话文本，即使模型跳过该轮次或随后关闭记录。新文件所有者权限，未加密，现有父目录权限不会收紧。关闭或卸载不会删除文件，没有自动保留清理。
辅助请求不会插入到主模型历史或 DSH 会话日志中。测试过的宿主无法安全注册外部信息会话事件，因此重放需要将插件审计目录与 DSH 对话日志放在一起。录制期间没有 shell 命令或模型工具执行。
模型错误、无效 JSON、截断完成、文件缺失、标记损坏和权限错误通过 /note status 和运行时日志报告。修复原因后使用 /note sync，失败模型工作重试时可能会再次计费。状态、索引和笔记是独立的原子文件替换，不是一次性事务；索引失败可能留下已保存笔记，同步重建不会重新生成已提交轮次。崩溃可能导致重复模型计费，但笔记元数据会在恢复时防止重复提交区域。
适用场景与注意事项¶
适合需要长期保存对话内容、按主题组织学习笔记、希望自动维护索引的开发者和学习者。插件以当前 DSH 进程的权限运行，安装前应检查源码与许可证。
敏感对话请谨慎开启记录，除非你对提供者的本地保留策略可以接受。插件不会自动清理历史数据，卸载不会删除已生成的笔记和审计文件。建议定期手动整理和备份笔记目录。
