dsh-tool-todo-plus

DeepSeek Harness 任务清单插件 —— 官方 todo_write 的增强 fork

优先级标签 · 完整清单渲染 · 会话内浮动任务面板

安装 · 功能 · 常见问题 · 安全 · 上游致谢

界面预览

浮动任务面板（展开态）——模型写入清单时自动弹出，实时跟随状态流转；毛玻璃表面与原生主题融合：

执行中——两次清单写入之间，⚙ 行实时显示模型此刻执行的工具（截图中对应正在进行的第 2 步）：

<p align="center"><img src="docs/screenshots/panel-executing.png" alt="执行中：当前动作行"></p>

胶囊态——收起为 ZCode 计划面板同款的内容优先级链（进行中项 →，截图中为"编写 README 使用说明"），点击展开：

<p align="center"><img src="docs/screenshots/panel-capsule.png" width="420" alt="胶囊态"></p>

面板可拖动 + 双击复位——按住卡片头部实时拖动，展开态 / 胶囊态下均可；双击头部，面板一步跳回默认锚定位置（实拍 GIF，约 7 秒）：

<p align="center"><img src="docs/screenshots/panel-drag.gif" alt="面板拖动与形态切换实拍"></p>

<b>目录</b>

• 它是什么
• 功能
• 安装
  • 方式一：npm 包名安装（最简）
  • 方式二：git 直装（始终最新 main）
  • 方式三：桌面端插件页
  • 方式四：源码构建
  • 更新到新版
• 配置
• 安全
• 常见问题
• 已知限制
• 上游致谢
• 许可证

它是什么

零网络请求、零运行时 npm 依赖（依赖仅在构建期），宿主半不触文件系统——安全细节见文末。

一个"模型侧工具 + 用户侧面板"的组合：

• 模型侧：注册增强版任务清单工具。是否建清单由模型根据任务复杂度自主判断（多步骤任务通常会建），你也可以在消息里直接要求"先列个任务清单"来引导。
• 用户侧：模型每次写入清单，会话内自动弹出浮动面板并实时跟随更新；面板是纯展示层，不会无中生有。

功能

功能速览：

• 🧩 优先级标签：high / medium / low，对齐 ZCode 的 TodoWrite —— 增强工具
• 📋 完整清单渲染：工具结果返回完整 markdown 清单（官方版只有一行计数）—— 增强工具
• 🪟 浮动任务面板：自动弹出、实时跟随、可拖动带位置记忆、毛玻璃原生外观 —— 浮动任务面板
• ⚡ 当前动作：两次清单写入之间，实时显示模型此刻执行的工具 —— 浮动任务面板
• 🛟 轮次间不闪空：发新消息时保留上一轮清单，淡化并标"上一轮" —— 浮动任务面板
• 🤝 零冲突共存：与官方 todo_write 并存，会话日志双向兼容 —— 与官方版共存

增强工具（模型侧）

• 优先级标签：TodoItem 增加可选 priority（high / medium / low），对齐 ZCode 的 TodoWrite
• 完整清单渲染：工具结果向模型返回完整 markdown 清单（官方版只有一行计数）
• 行为纪律：工具 description 内置"何时用/不用、整表替换、单 in_progress、完成即刻标记、切换即写（步骤切换时在同一次调用里完成两个状态变更）"的完整指引，并在存在官方工具时声明优先使用本插件
• 参数双保险：参数 schema（enum + additionalProperties: false）之外再做运行时规范化——空白 content 条目丢弃、重复 content 自动加后缀、默认只保留第一个 in_progress（多余自动降级为 pending）；调整内容会在工具结果里告知模型。0.7.3 起不再拒绝写入：拒绝会让这次调用在会话日志里不留任何事件，面板就永久停在旧状态

浮动任务面板（用户侧）

• 独立浮窗：插件自绘 overlay，不推挤聊天区，也不会展开右侧栏；只在会话界面显示，切到插件页等其他界面自动隐藏
• 两种形态：展开态（状态点 / 划线 / 优先级徽章 / 进度计数 / "进行中"标记）⇄ 胶囊态（ZCode 计划面板同款内容优先级链：进行中项 → → 最近完成项 ✓ → ☰ 待办 完成/总数），点击即时切换
• 自动弹出规则：
  • 模型实时写入 → 自动弹出（面板刚关掉也会为新任务重开）
  • 重新进入会话 / 切换会话 / 重启应用 → 历史清单只同步数据，不弹面板（关了就保持关着）
• 轮次间不闪空：发新消息（新一轮开始）时保留上一轮清单，淡化显示并标"上一轮"，等新清单写入再替换——执行过程中面板不会闪"暂无任务"
• 当前动作：两次清单写入之间，面板/胶囊实时显示模型此刻执行的工具（如 ⚙ pwsh · Run tests，取自会话节点流中已发出但未返回结果的调用），空闲时自动消失
• 手动入口：会话标题栏"☰ 任务清单"按钮随时开关；✕ 关闭
• 面板可拖动：按住卡片头部拖到任意位置，位置自动记忆（重进会话/重启保持）；双击头部复位到默认锚定位置
• 原生外观：颜色、圆角、阴影、毛玻璃材质全部解析 dsh 宿主的 --dsw-* 设计 token，亮暗主题自动跟随

与官方版共存

• 本插件在桌面端注册为 todo_write_plus，与官方 todo_write 并存，零冲突
• 会话日志复用官方 todo/write 事件类型：与官方插件写出的日志可互相读取，会话重载无兼容性风险
• 工具名万一被占用，本插件记日志后优雅让位（entry 正常激活），不会导致 agent preset 审计失败

安装

方式	适合谁	特点
npm 包名	大多数用户（CLI / 桌面端均可）	最简，可指定版本
git 直装	急用最新版	始终拉取 main 最新
桌面端插件页	桌面端、不想敲命令行	图形界面操作
源码构建	开发者 / 二次开发	本地构建 tgz

<a id="install-npm"></a>

方式一：npm 包名安装（最简）

包已发布到 npm：dsh-tool-todo-plus——安装时只需包名，无需 git 地址，且可指定版本。

CLI profile（有 dsh 命令的环境）：

…