sueqet/dsh-todo-board

dsh-todo-board

DeepSeek Harness 的跨会话 TODO 板 —— 一次只交给 agent 一个任务，它会自己接着做下一个。

DeepSeek Harness（DSH）的跨会话 TODO 板 —— 一次只派一件事，干完它自己去拿下一件。

topic: dsh-plugin
license: MIT
node

TODO board panel

它解决什么 / Why

让 AI 干完一件事之后，自己去待办板里找同一目录下还没做完的下一件继续干 —— 不用你盯着逐个验收，也不用一次性把一堆任务塞给它、结果每件都做得半吊子。

让 agent 做完一件事，然后在同一工作目录里查找下一个未完成的任务并继续做下去。不用盯着每一步，也不用一次性把一堆任务丢给它、最后拿回五个半成品。

安装 / Install

dsh plugin --profile web add dsh-todo-board          # 发布到 npm 之后 / once published to npm
dsh plugin --profile web add        # 或直接从仓库/目录安装 / or from a repo or local path

安装后重启 Profile（重新执行 dsh web）才会装载 —— 本插件是 host 组合里的一行，不是运行时热加载。

之后重启 profile（再次运行 dsh web）：该插件是 host 组合中的一行，不是运行时热加载。

卸载 / Uninstall:

dsh plugin --profile web remove dsh-todo-board

快速上手 / Quick start

1. 右上角出现浮窗，输入一条待办，选执行模式，点「添加」。
2. 让 AI 去做这件事。它做完会调用 todo_board action=done 给自己打左勾，然后查同目录下一条。
3. 你验收后点右勾；底部「清理已验收」批量清掉。

1. 在浮窗面板里输入一个任务，选择运行模式，点击添加。
2. 让 agent 开始工作。完成后它会调用 todo_board action=done 勾选自己的复选框，然后查找同一目录中的下一个任务。
3. 你验证后，勾选右侧的复选框；“清理已验收”会清除已验证的那些。

三档执行模式 / Run modes

每条待办在新增时必须选一档（默认「提醒」）。每个任务只携带一种模式，在你添加时选定。

| 模式 | 行为 | 行为 |
| --- | --- | --- |
| 提醒 | 不自动做任何事，等你在浮窗里点 ▶ | 不自动执行任何操作；你想做时按 ▶ |
| 自动续跑 | AI 回合结束时，把同目录下一条待办注入当前会话继续跑 | 回合结束时，将同一目录中的下一个任务注入当前会话 |
| 自动新会话 | AI 回合结束时，新建一个同目录会话并执行该待办 | 回合结束时，在同一目录中创建一个新会话并在那里运行任务 |

派发顺序 = 面板里从上到下的顺序。拖动行首 ⠿ 调整，顺序持久化。

派发顺序是面板中从上到下的顺序。拖动 ⠿ 手柄可更改顺序；顺序会被持久化。

「自动新会话」第一次派发时创建会话，并把它绑定到这条待办上：之后 ▶ 或回合结束自动接续都复用同一个会话，不会一次运行开一个会话。绑定会话已不在（比如你把它删了）时，下一次派发才会再开一个新的；想手动换一个新会话，点行上的 会话 … ✕ 解绑即可。

自动新会话 任务会打开一次会话，并将它绑定到该行：之后按 ▶ 和回合结束交接都会复用同一个会话，而不是再开一个。只有绑定失效（会话被移除）—— 或点击 会话 … ✕ 标签解除绑定 —— 才会让下一次派发打开一个新会话。

新会话会被登记进待办目录所属的工作区，侧栏里和手动开的会话一样归组（不是「未分组」）。

图片附件 / Attached images
待办可以带图片（最多 4 张，PNG / JPG / WebP / GIF）。图片存进 DSH 的附件库，派发时作为真正的图片和提示词一起发给模型——不是把文件名写进文字里。

- 新增框里点「📎 图片」选图，带缩略图预览，可逐张移除；行上显示缩略图，点击放大，✕ 移除单张。
- 上限、媒体类型与归一化都用 harness 自己那套（同一条 attachments.saveImage 通路），不是本插件自己定的规则。
- 图片字节由本插件自己的 GET /dsh-todo-board/image?id=… 提供：harness 自带的图片读取是会话作用域的（只认会话日志里引用过的附件），而待办的附件存在板上，所以板自己当权威——没被任何待办引用的 id 一律 404。
- 目标模型必须支持图片：派发前会查模型是否声明了 image。文本模型（如 deepseek-v4-flash）会直接提示「目标会话的模型不接受图片输入」，而不是让适配器抛 UNSUPPORTED_CONTENT。这是 DSH 的模型声明问题，不是插件的限制。

定时执行 / Scheduled execution

每条待办都可以带一个本地时间（YYYY-MM-DDTHH:mm，分钟精度）。到点之前这条待办不会被派发；到点之后 DSH 按它自己的模式执行它 —— 就像你此刻按了 ▶ 一样。

- 新增框里的「定时」一行用浏览器的时间选择器挑时间；留空 = 立即可执行。
- 行上的定时标签显示时间，已到点会变黄；点它即取消定时。
- 提醒 模式到点只弹一条桌面通知（需要浏览器通知权限），不会自动给模型发消息；自动续跑 / 自动新会话 到点才真正派发。
- 定时只判一次：派发过（或被提醒过）就不再重复触发。错过的时间（DSH 当时没运行）会在下次启动后立刻补上。
- 时间用主机本地时区解释；面板存的就是你选的那一刻。

双勾选 / Two checkboxes

| 勾 | 谁勾 | 含义 |
| --- | --- | --- |
| 左（方框） | 模型自己调 todo_board action=done，也可手点 | AI 已完成，等你验收 |
| 右（圆框） | 只有用户 | 已验收，真正了结 |

只有右勾才把待办从未完成列表里移除。系统提示段落明确禁止模型代勾右勾。

面板操作 / Panel

- 折叠为一行：标题栏右侧的 – 把整板收成一行 —— TODO · 未完成数 · 下一条待办 · 待验 N，点这一行任意位置展开。平时挂着不占地方，扫一眼就知道还剩什么。
- 区块折叠：面板内部三个区块（新增待办 / 待办列表 / 面板）各自可折叠，点区块标题切换，▾ 展开、▸ 已折叠。只留列表时最省空间；折叠状态记在 localStorage，刷新后保持。
- 拖动 / 缩放：拖标题栏移动，右下角 ◢ 缩放；位置与尺寸存进 localStorage，刷新保留；双击标题栏或拖柄还原。
- 筛选：当前目录 / 当前会话 / 全部，每段带未完成计数。
- 行内编辑：双击标题改名；点模式标签在 提醒 → 续跑 → 新会话 之间循环切换。
- 多行输入：新增框自动增高（3 行起步，最高 180px），Enter 添加、Shift+Enter 换行。
- Cordis 入口：侧边栏底部的 Cordis Plugin 按钮折起，入口移到本面板底部；点它打开原面板，面板出现在本面板正下方（右对齐、互不覆盖），拖动或缩放本面板时它会跟着走。找不到入口时按钮会变灰并给出提示。

- 折叠为一行：标题栏中的 – 可将整个面板折叠为一行 —— TODO · 未完成计数 · 下一任务 · 待验 N。点击该行任意位置（或按 Enter/Space）即可展开；该行紧贴内容，而非横跨整个面板。在你需要之前，它一直不碍事。
- 分区折叠：输入框、列表和页脚各自可从自己的标题处折叠（▾ 展开，▸ 折叠）；只留列表时面板最小。折叠状态保存在 localStorage 中，刷新后保留。

模型工具 / The todo_board tool

| action | 作用 |
| --- | --- |
| list | 列出当前工作目录下未验收的待办（all: true 列全部目录），带 id、执行顺序与定时时间 |
| add | 新增一条（追加到列表底部），可带 schedule |
| done | 打左勾「AI 已完成」 |
| reopen | 撤销左勾 |
| note | 追加备注 |
| schedule | 设置或取消某条待办的定时时间（schedule 传空字符串即取消） |

工具输出 schema 是 additionalProperties: false 的严格 JSON Schema，返回值只含声明过的字段。

数据 / Data

${DSH_HOME}/todo-board/board.json（默认 ~/.dsh/todo-board/board.json），原子写入（临时文件 + rename）。文件缺失时自动创建；读坏或写失败会在浮窗底部红字提示。待办板是全局的，面板内按目录分组。

会话生命周期 / Session lifecycle

「自动新会话」创建的会话走 ctx.root + agentPresets.mount()：

- 归属应用根上下文而不是本插件行，因此停用 / 更新 / 卸载本插件不会连带拆掉这些会话；
- setup 里挂载 agent preset，与 api-proxy 创建会话的方式一致 —— 少了这一步新会话会没有工具和提示词；
- 模型优先沿用来源会话的 provider/model，否则取 agentDefaultModel 的当前选择。

结构 / Layout

package.json          dsh.bundle.patch → cordis.patch.yml；dsh.client.platform = web
cordis.patch.yml      向 profile 树 insert 一行 todo-board
lib/index.js          Host：板文件、todo_board 工具、回合结束钩子、提示词段落、/dsh-todo-board/api
client/client.js      Browser：shell.overlay 浮窗，走 fetch 访问上面的路由
tools/smoke.mjs       Host 半边自检（stub ctx + 临时 DSH_HOME）
tools/client-smoke.mjs  Browser 半边自检（极简 React hook 运行时 + DOM stub，折叠行为）

Host 半刻意不 import 任何 @deepseek-ai/*：profile 安装的插件从自身目录解析模块，harness 包在那里不可达，一切通过 ctx。

开发 / Development

npm run check   # node --check 两个入口
npm test        # host + client 两半 smoke 自检

改完客户端只需刷新页面；改 Host 半边需要重启 Profile。

已知限制 / Limitations

- 浮窗每 2.5s 轮询一次 /dsh-todo-board/api，不是推送。
- 待办板是全局单文件，不按目录分文件。
- 「自动新会话」需要待办上的目录路径可创建。
- 定时只支持单次的绝对时间，没有 cron / 周期规则；到点后「自动续跑」需要来源会话当时还在运行，否则按「没有可接续的活动会话」处理（改「自动新会话」可脱离会话存活）。
- Cordis 入口是 DOM 桥接：按该插件自己渲染的 data-cordis-badge 属性定位，用带 !important 的规则覆盖它计算出的位置。DSH 升级若改了这套实现，桥接会失效——那时按钮会变灰并提示，不会静默失灵。

License

MIT