DSH Todo

在 DSH 左侧导航添加「待办」，集中查看自己要做的事。可将同一份清单打开为独立小窗口，放在桌面一角，按需置顶或最小化。

使用

dsh plugin --profile desktop add 'github:AsakuraAOI/dsh-todo'

在 DSH 的「插件 → 添加插件」中选择本地目录，填写本插件目录的绝对路径；也可以选择打包后的 dsh-todo-0.3.0.tgz。按插件管理器提示重启后，左侧会出现「待办」入口，与插件、学习、技能中心位于同一导航区域。

• 输入标题并按 Enter 或点击「添加」。展开「添加描述和详情」可填写简短描述（最多 200 字）与完整详情（最多 20000 字）。通过「编辑」修改这些内容。
• 列表只显示简短描述预览（最多两行），点击标题或描述查看完整待办内容。详情窗口显示完整标题、描述、详情、状态及倒计时；可从详情进入编辑，点击关闭或按 Escape 返回清单。主页面和独立窗口使用相同操作。
• 旧版的长备注会完整保留在详情中，清单改为显示简短预览。
• 清单、详情和输入框不显示滚动条；长内容仍可通过滚轮、触控板或键盘滚动查看。
• 可选勾选「设置倒计时」，输入时长（分钟、小时或天，最长 365 天），或选择本地截止时间。添加后立即开始计时，关闭窗口或重启也继续计算；编辑时可调整或取消。
• 默认按剩余时间从少到多排列，超时事项在前，未设置倒计时的在后；相同截止时间按创建时间从新到旧排列。倒计时每秒刷新，超时后显示「已超时」，不自动完成事项。已完成或已结束的事项仅显示截止时间。
• 勾选表示「已完成」；在已完成列表取消勾选可恢复为进行中。
• 「结束」表示不再继续，记录移到已结束列表；点击「恢复待办」可重新继续。
• 使用进行中、已完成、已结束、全部筛选查看记录。结束不会删除数据。

主页面右上角的「独立窗口」打开一个单独的桌面窗口，再次点击会唤起已有窗口。小窗口中可添加、编辑、勾选和结束待办，也可点击「置顶／取消置顶」「最小化」「关闭」。关闭小窗口不会清空清单；再次打开时默认不置顶。退出 DSH 或停用插件时，小窗口也会退出。

独立窗口沿用主窗口当前的明暗主题和配色变量；在 DSH 中切换主题后，已打开的小窗口也会同步更新，无需关闭重开。主题同步由客户端插件持续处理，即使已离开待办页面也会继续同步。小窗口的原生标题栏跟随相同的明暗模式，不单独读取系统主题偏好。

Agent 工具

工具	用途
todo_list	默认读取进行中待办，status 可设为 completed、ended 或 all
todo_add	添加 title、可选的简短描述 notes、完整详情 details 和倒计时截止时间 dueAt
todo_update	根据 id、expectedVersion 更新描述／详情、设置／取消 dueAt，或执行 complete、end、reopen

例如可以告诉 Agent：「帮我记一条待办：周五前整理报告」，或「把整理报告标为已完成」。工具说明要求 Agent 仅在用户要求记录待办时写入；其内部执行计划仍使用 DSH 自带的 todo_write。

dueAt 使用带时区的 ISO 日期时间，例如 2026-10-18T18:00:00+08:00；null 取消倒计时，更新时省略则保留已有时间。Agent 读取到的列表与界面采用同样的默认排序。旧版本没有截止时间的待办会继续保留，无需手动迁移。

主页面、独立窗口和工具共用本机的持久清单，所有会话共享，不按会话隔离。页面约每 1.5 秒同步；过期修改会被拒绝，避免覆盖另一处的新内容。编辑时遇到冲突，可先保留输入文字，取消后重新打开该条目进行编辑。

数据与平台

数据保存在用户主目录下的 .dsh/storages/dsh-todo/todos.json。卸载插件不删除该文件，重新安装后可继续使用。备份时请先退出 DSH，再复制此文件；数据损坏时插件会停止写入并提示错误。

主页面和工具运行于 DSH 插件接口。独立窗口当前支持 Windows 桌面版 DSH，复用其已安装的 Electron 运行时，不需要下载其他运行时。首次打开会在同一存储目录的 runtime 下准备私有启动目录：优先硬链接运行时文件，跨磁盘时复制；不会修改 DSH 安装目录。桌面版升级后会创建对应的新启动目录，退出 DSH 后可以清理旧缓存。置顶状态仅影响本次打开的小窗口。

独立窗口使用隔离的本地页面和受限预加载接口；通过带随机令牌的回环连接访问同一份数据，不开放远程待办访问。不支持在普通浏览器页面中创建可置顶的原生窗口。

开发与验证

npm run build
npm run check
npm test
node scripts/electron-smoke.mjs

无运行时 npm 依赖。src/ui.js 是两处清单共用的界面，src/client-template.js 提供 DSH 导航和页面注册，构建生成 client.js 和独立窗口使用的 native/time.js。修改界面后应重新构建。

单元测试覆盖持久化、并发写入、状态转换、过期修改、损坏保护、接口校验、插件注册、可选截止时间、默认排序、描述与详情分离、长中文详情请求、旧数据兼容。Electron 验证使用临时数据，覆盖真实窗口控件、清单操作、跨窗口数据同步、客户端 Bundle 加载，以及宽窄布局截图；不会写入日常清单。真实 DSH 重启后的完整导航与 Agent 对话仍需在桌面应用中验收。

需要单独验证清单操作时，可设置 DSH_TODO_SKIP_WINDOW_CONTROLS=1 后运行 Electron 验证。报告会明确标记跳过置顶和最小化，该结果不能作为这两项通过的证据。