前言¶
在 DeepSeek Harness（DSH）里跑智能体时，任务往往会落在三个时间尺度上：跨项目的长期跟进、当前仓库里的开发事项、以及这一次会话里要立刻做完的几步。如果把它们都写进对话或零散备忘录，切换工作区或新开会话后很难对齐上下文；让智能体改待办，又需要明确边界，避免误改你手写的内容。
TODO 便签（dsh-todo-notes）是社区维护者 BlazeNebula 发布的 DSH 插件（package 版本 1.0.1，MIT）。它在客户端提供用户级、工作区级、会话级三组待办，数据全部落在本机 $DSH_HOME/todo-notes/，并通过一组 Agent 工具在 DSH 审批下读写条目。下面介绍安装方式、界面用法、设置项与智能体侧能力。
插件定位与数据模型¶
插件在 DSH 里注册 Web 客户端与宿主侧 HTTP 路由 /dsh-todo-notes/api，面板通过该路由读写本地文件；插件自述不发起外网请求。每条 TODO 存为一个 Markdown 文件，frontmatter 含 id、title、status（todo / partial / done）、created、updated、source、priority、primaryFolder 等字段。
三个层级互不混用：
- 用户级：跨项目长期事项，任意工作区可见。
- 工作区级：按工作区目录分开存放。
- 会话级：仅属当前会话；切换会话时，会话组自动换成对应内容。当前工作区与会话的组标题为斜体，悬停可见工作区路径或会话 ID。
浮动面板与右侧栏「TODO 便签」页签展示同一份数据，任一侧修改会即时同步。
安装与生效¶
官方 README 给出的安装方式如下，未提供 dsh plugin add github:... 一类命令，安装时请按文档操作：
- 在 DSH 插件市场搜索「TODO 便签」安装。
- 若市场尚未收录，在插件页填写仓库地址
https://github.com/BlazeNebula/dsh-todo-notes，或选择本地目录安装。 - 安装完成后，右上角会出现浮动面板，右侧栏页签中也会出现「TODO 便签」。
生效规则需要区分两类改动：
- 仅客户端改动：按
Ctrl+R刷新即可。 - 新增插件或设置页等宿主侧改动：需完全退出 DSH（含托盘图标）后重新启动。
插件以当前 DSH 进程权限运行；安装前建议在 GitHub 查看源码与 LICENSE（MIT）。社区目录页：skillhub.cn 上的 dsh-todo-notes。该目录为社区独立站点，与 DeepSeek / 幻方无官方从属关系。
快速上手¶
- 在浮动面板中点击组标题右侧的「+」，创建第一条 TODO。
- 单击条目打开 Markdown 预览；在预览右上角点编辑，可改标题与正文。
- 拖动面板标题栏移动位置，拖右下角调整大小；位置与尺寸会记住。
- 勾选表示完成；智能体勾选的条目会先进入半完成，待你确认。
组织、预览与批量¶
文件夹与优先级：可建嵌套文件夹；一条 TODO 有主归属，也可被多个文件夹收录。优先级为 T0～T9（T0 最高）。拖动可排序；拖到另一文件夹会移动主归属；按住 Ctrl 拖动仅增加收录。支持框选、Shift 连续选择及批量移动、收录、改优先级、重命名或删除。
预览窗口：单击打开临时预览；拖预览标题栏可保留为独立窗口，可多开，刷新或重启后恢复位置与内容。同一条目只保留一个预览窗口，再次打开会置顶已有窗口。编辑时标题为输入框，正文编辑 frontmatter 之后部分；停止输入后自动保存（间隔可在设置中配置）。
勾选三态：未完成、半完成（智能体勾选待确认）、已完成（人工确认）。单击勾选框切换；双击勾选区域可直接完成。
设置与 Config 默认值¶
路径：设置 → 左侧「TODO 便签」，或从插件列表进入，为同一设置页。
- 状态外观：未完成 / 半完成 / 已完成行透明度（默认已完成 35%、半完成 67%）。
- 优先级颜色：T0～T9 十档，支持取色器或十六进制输入。
- 编辑与保存：「允许智能体修改你手写的条目」默认关闭，开启后每次写入仍须 DSH 审批；正文与标题停止输入后的保存间隔（秒，默认 5）；标题最大长度（默认 30 字，超长时面板截断并提示，智能体工具会拒绝并返回当前字数）。
设置保存在本机 ui-settings.json；点「保存」后立即作用于所有面板。插件 Config 中的 agentWriteUserTodos 与 bodyAutosaveMs 在未改过设置页时作为默认值，改过以后以设置页为准。
智能体工具¶
智能体通过以下工具操作便签（列表类不返回正文）：
| 工具 | 作用 |
|---|---|
todo_notes_list |
按范围列摘要 |
todo_notes_read |
按 id 读正文与属性 |
todo_notes_create |
新建条目 |
todo_notes_update |
改标题、优先级、状态或文件夹 |
todo_notes_toggle |
勾选或取消勾选 |
todo_notes_delete |
删除条目 |
智能体勾选最多为半完成，最终完成须由你确认。修改手写条目需先在设置中开启许可，且每次写入经过 DSH 审批；拒绝或无法审批时不写入。
本机目录结构¶
$DSH_HOME/todo-notes/
windows.json # 保留窗口的位置、尺寸与内容
ui-settings.json # 外观、自动保存、标题长度、智能体权限
user/ # 用户级
workspaces/<工作区 slug>/
sessions/<会话 id>/
适用场景与注意¶
适合需要在 DSH 内长期维护待办、并希望智能体在明确审批与半完成机制下协助增删改的场景。不适合依赖云端同步或多设备共享的需求——数据仅本机存储。
开发侧：lib/ 为宿主逻辑，client/src/ 构建为单文件 client/client.js；改客户端后执行 node scripts/build-client.mjs 或 npm run build:client，npm run check 做语法检查。
结尾¶
TODO 便签把用户 / 工作区 / 会话三层待办、文件夹与优先级整理、以及审批下的 Agent 工具收进同一套本地面板。安装与细节以仓库 README 为准：GitHub：BlazeNebula/dsh-todo-notes，目录页：skillhub.cn/plugins/BlazeNebula/dsh-todo-notes。
