# dsh-study-note

[English](README.md) | 中文

把明确开启记录的 DeepSeek Harness 对话整理成结构化 Markdown 学习笔记的插件。每个对话默认关闭，开启一个对话不会影响其他对话。

## 快速开始 — 教程

需要 Node.js 22.19+，以及提供 `commands`、`sessions`、`llm` 的 DSH profile。已验证本机 DSH 0.1.0-rc.8 和本地 0.1.1-rc.2 构建的 loader 组合；更新版本尚未验证。包内直接包含可运行的 JavaScript，安装时无需构建。

1. 克隆插件、安装开发依赖并生成可安装压缩包：

   ```sh
   git clone https://github.com/WaterFountain-Jack/dsh-study-note.git
   cd dsh-study-note
   npm install
   npm pack
   ```

2. 安装到目标 profile。这个命令会修改该 profile；如果你的名称不是 `desktop`，请替换。包未发布到 npm，因此不能按 npm 包名安装。

   ```sh
   dsh plugin --profile desktop add "$PWD/dsh-study-note-0.1.0.tgz"
   dsh --profile desktop --dump-config
   ```

3. 如果插件没有热加载，请重启该 DSH profile。在一个对话里，分别发送以下命令，再提出学习问题，等助手完整回答：

   ```text
   /note on Cordis
   /note status
   ```

4. 完整回答后会在后台整理。`/note sync` 立即检查所有符合条件的完整轮次并重试未完成的失败任务；`/note status` 显示文件位置和最近错误。到配置的笔记目录检查文档及根索引。用 `/note off` 关闭这个对话的记录。

卸载会保留笔记和本地状态：

```sh
dsh plugin --profile desktop remove dsh-study-note
```

## 对话控制 — 参考

| 命令 | 行为 |
| --- | --- |
| `/note on [topic]` | 开启当前对话；只处理开启后开始的完整轮次。重复开启不会重置检查点。 |
| `/note off` | 取消并等待后台任务停止，保留已有文件。成功返回后不再为这个对话自动写入。 |
| `/note status` | 查看开关、目录、分类、文件、待处理任务和最近错误。 |
| `/note sync` | 立即处理符合条件的完整轮次；需要已开启记录。不补录关闭期间的内容。 |
| `/note topic <topic>` | 固定分类并移动本对话已有笔记，重建索引。 |
| `/note reindex` | 无需模型调用，重建插件负责的根索引；关闭时也能使用。 |
| `/note new` | 仅在旧笔记被删除或移出根目录后清除关联；保持关闭。随后用 `on` 开始新笔记，不回填历史。 |

分类名为 1–64 位字母、汉字、数字、下划线或短横线，以字母或数字开头。手动指定分类可以创建目录；自动分类只选择已有目录，不确定时归入 `inbox`。subagent 对话不能开启记录。

## 笔记与索引 — 参考

```text
~/.dsh/study-notes/
├── README.md
├── Cordis/
│   └── 2026-10-15-Cordis-学习-<session-hash>.md
├── inbox/
└── .study-note/
    ├── state.json
    ├── writer.lock
    └── requests/
```

一个对话对应一份文档。值得记录的问题形成小节，包括问题、一句话结论、解释、公式/代码/例子、供你改写的 AI（人工智能）理解草稿、遗留疑问和来源轮次/事件编号。追问可以更新原小节，不同问题新增小节。笔记不代表事实已经核验或用户已经掌握。

手工修改过的小节不会被替换：相关追问改为追加补充小节。请保留 HTML 元数据和小节标记。在根目录内改名或移动，会在下次写入或 `/note reindex` 时发现；不持续监听外部编辑。删除笔记不会静默重建。根目录内每个对话只保留一份文档。

只维护 `README.md` 中 `<!-- dsh-study-note:index:start -->` 与 `<!-- dsh-study-note:index:end -->` 之间的区域，区域外的手写条目不变。自动索引只收录本插件生成的文档，不改写或自动编目已有的其他笔记。

## 配置 — 参考

组合包配置项 id 为 `study-note`。可以用可选 overlay 指定其他根目录：

```yaml
- id: study-note
  config:
    notesDir: '~/study-notes'
```

把 overlay 保存在你选择的位置，启动 profile 时传入 `--patch <absolute-overlay-path>`。也可以将该配置项合并到 profile 补丁，保留其他配置项。本项目不会修改你正在使用的 profile 或已有知识库。

| 字段 | 默认值 | 含义 |
| --- | --- | --- |
| `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 key 或环境变量，但不会自动脱敏你写进问答的秘密。仅在接受该模型提供方和本地留存时，为敏感对话开启记录。

调用前，完整系统提示词、消息、路由、token 限制及来源事件编号会保存到 `.study-note/requests/`。这些本地审计文件包含选取的问答，即使模型跳过或随后关闭记录也会保留。新文件使用仅所有者可读写的权限，不加密，也不收紧已有父目录的权限。关闭或卸载不会删除文件，暂不提供自动留存清理。

整理请求不插入主模型历史，也不写入 DSH 会话日志。已测试宿主无法安全注册外部信息类会话事件，因此回放需要同时保留插件审计目录和 DSH 对话日志。整理过程不执行 shell 命令或模型工具。

模型报错、非法 JSON、截断结束、文件缺失、标记损坏和权限错误会通过 `/note status` 及运行日志显示。修复原因后执行 `/note sync`；失败的模型任务重试可能再次计费。笔记、状态和索引分别原子替换，不是跨文件事务；索引失败时笔记可能已经保存，sync 会重建索引，不重新生成已经提交的轮次。崩溃可能导致模型重复计费，但笔记元数据会在恢复时避免重复提交小节。不保证突然断电时文件系统重命名的持久性。

一个笔记目录只允许一个写入者。崩溃可能留下 `.study-note/writer.lock`；确认其中记录的进程已停止后，仅移除这个锁，再重新加载插件。只读实例加载后状态被别人修改，需要重新加载该实例。不要与不可信写入者共享目录，也不要在自动保存期间同时编辑同一小节；文件比较能发现许多文件系统竞态，但不是全部。

## 开发与分发 — 参考

```sh
npm run check
npm test
npm run test:dsh
```

loader 冒烟测试默认使用上级 DSH 源码目录的构建产物。要验证其他已安装 DSH，将 `DSH_PACKAGE_JSON` 设为它的命令行包 `package.json` 路径。只模拟外部模型提供方，不使用真实 API key 或产生付费请求。测试使用真实 loader、会话、命令和 LLM（大语言模型）服务，并比较规范化输出快照。这些检查不评估真实模型整理质量、桌面显示效果、最新宿主兼容性或所有操作系统。

社区市场提交要求见[发布说明](PUBLISHING.md)，生命周期和审计取舍见[设计记录](DESIGN.md)。