dsh-plugin-todo

DeepSeek Harness (dsh) TODO 管理插件（v0.2.0）：让 Agent 像项目管理工具一样管理任务列表，用户通过自然语言即可新增、查询、修改、完成和删除任务，支持优先级、备注与关键词搜索。

功能

| 工具 | 说明 | |---|---| | todo_add | 添加任务，指定内容、优先级（high / medium / low，默认 medium）与可选备注，返回任务 ID | | todo_list | 列出任务，支持排序（sort: "priority" / "created"）、状态过滤（filter: "all" / "pending" / "done"）、优先级过滤（priority: "high,medium"）与关键词搜索（search） | | todo_update | 修改任务的内容、优先级或备注（至少提供一个；note: "" 表示清除备注） | | todo_done | 按任务 ID 标记完成；再次调用同一 ID 会切换回待办 | | todo_remove | 按任务 ID 删除任务 |

搜索语义

search 把输入按空格拆成多个关键词，全部命中才算匹配（AND 语义），匹配范围为任务内容与备注，大小写不敏感。例如 search: "文档 k8s" 只会命中同时提到两者的任务。

工具间协作：todo_add 返回的 ID 可直接传给 todo_done / todo_remove；todo_list 输出中包含每条任务的 ID。

数据模型与持久化

任务数据持久化存储在工作区（cwd）下的 .todos.json：

{
  "tasks": [
    {
      "id": 1,
      "content": "完成插件开发教程",
      "priority": "high",
      "note": "先看官方文档第 3 章",
      "done": false,
      "created": "2026-08-22T10:00:00Z",
      "updated": "2026-09-30T09:00:00Z"
    }
  ]
}

数据文件路径可通过 ctx.settings 配置 todo.dataFile（相对路径基于工作区解析），未配置时默认 .todos.json。文件损坏时工具返回错误提示并重置为空列表，不会静默丢数据。

安装

方式一：通过 npm 安装（推荐）

# 1. 确保 dsh 已安装
npm install -g @deepseek-ai/dsh-cli

# 2. 安装插件
dsh plugin --profile web add dsh-plugin-todo

# 3. 验证安装
dsh plugin --profile web list

方式二：本地开发调试

# 1. 克隆或进入插件目录
cd E:/dsh-plugins/dsh-plugin-todo

# 2. 安装依赖
pnpm install

# 3. 创建调试配置
cat > debug.patch.yml <<"EOF"
- insert:
    - id: todo
      name: "E:/dsh-plugins/dsh-plugin-todo/index.js"
EOF

# 4. 启动 dsh Web
pnpm dsh web --patch ./debug.patch.yml

# 5. 打开 http://127.0.0.1:3080 使用插件

方式三：从本地 tarball 安装

# 1. 构建插件
cd E:/dsh-plugins/dsh-plugin-todo
pnpm pack

# 2. 安装本地包
dsh plugin --profile web add ./dsh-plugin-todo-0.2.0.tgz

方式四：从源码直接运行（开发模式）

# 1. 安装依赖
pnpm install

# 2. 使用 pnpm 脚本直接启动（开发模式）
pnpm dev

# 3. 打开 http://127.0.0.1:3080 使用插件

源码及发布地址

• GitHub 仓库: https://github.com/geeklei/dsh-plugins/tree/main/dsh-plugin-todo
• npm 包: https://www.npmjs.com/package/dsh-plugin-todo
• 版本: 0.2.0
• 许可证: MIT

FAQ

Q1: 任务数据存储在哪里？

任务数据持久化存储在工作区（cwd）下的 .todos.json 文件中，文件路径可通过 ctx.settings.todo.dataFile 配置，未配置时默认为 .todos.json。

Q2: 可以同时使用多个工作区的任务吗？

不可以。每个工作区（cwd）有独立的 .todos.json 文件，插件会自动使用当前工作区的数据文件。

Q3: 如何备份任务数据？

直接备份工作区目录下的 .todos.json 文件即可。建议定期备份或在重要操作前手动复制该文件。

Q4: 任务 ID 是如何生成的？

任务 ID 是自增整数，从 1 开始，每次添加任务时自动递增。即使删除任务，新任务的 ID 也不会重复使用。

Q5: 文件损坏了怎么办？

如果 .todos.json 文件损坏，工具会返回错误提示并自动重置为空列表，不会静默丢失数据。建议定期备份文件。

Q6: 支持多用户吗？

不支持。插件为当前工作区提供全局的任务列表，不区分用户。

Q7: 如何修改任务的优先级？

用 todo_update：todo_update(id=3, priority="high")。同一个工具也能改内容（content）和备注（note），参数与当前值一致时会提示“无需修改”。

Q8: 可以设置任务截止日期吗？

当前版本暂不支持截止日期功能，优先级仅用于排序参考。

Q9: 插件支持自定义命令吗？

不支持。插件仅提供工具（tools）接口，通过自然语言与 AI 交互，不提供独立的命令行工具。

Q10: 备注和任务内容有什么区别？

内容（content）是任务标题，列表里始终显示；备注（note）用来放背景信息、链接、验收标准等补充说明，列表里以 ↳ 前缀折叠显示一行（超 60 字符截断）。两者都会被 search 检索到。

Q11: 如何卸载插件？

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

安全边界

数据隔离

• 工作区隔离: 任务数据严格限制在当前工作区内，不会跨工作区访问或修改其他目录的数据。
• 路径限制: 插件不会访问工作区以外的任何文件或目录。
• 配置安全: 用户可配置数据文件路径，但仅支持相对路径（相对于工作区根目录）。

权限控制

• 无系统权限: 插件不请求任何系统级权限（文件读写、网络访问等）。
• 沙箱环境: 在 dsh Web 环境中运行，受浏览器沙箱限制。
• 权限最小化: 仅访问当前工作区内的 .todos.json 文件。

数据保护

• 文件损坏处理: 文件损坏时工具会返回错误提示并重置为空列表，不会静默丢失数据。
• 无网络访问: 插件完全离线运行，不会上传或下载任何数据。
• 无数据聚合: 任务数据仅存储在本地文件中，不会发送到任何外部服务。

输入验证

• 参数验证: 所有工具参数都会进行严格验证，拒绝非法输入。
• 类型检查: 对任务内容、优先级等参数进行类型和格式检查。
• 长度限制: 对任务内容长度进行限制，防止过长的输入。

审计与监控

• 日志记录: 插件会记录关键操作日志（添加、完成、删除任务）。
• 错误追踪: 所有错误都会被捕获并返回给调用者，不会导致程序崩溃。

版本历史

v0.2.0 (2026-09-30)

• ✨ 新增 todo_update 工具：修改任务内容、优先级、备注（note: "" 清除备注）
• ✨ 任务备注能力：todo_add 支持 note，列表以 ↳ 折叠展示，参与搜索
• ✨ todo_list 新增 search（多关键词 AND、匹配内容与备注）与 priority 过滤（支持 "high,medium" 组合）
• ✨ 摘要增加优先级分布统计（如 high 1 / low 2）
• ✨ 内容/备注长度上限（500 / 1000 字符）与 updated 时间戳
• ✨ 测试扩展到 39 项断言

v0.1.0 (2026-09-04)

• ✨ 首次发布
• ✨ 实现 todo_add 工具（支持优先级 high/medium/low）
• ✨ 实现 todo_list 工具（支持排序和过滤）
• ✨ 实现 todo_done 工具（支持任务完成状态切换）
• ✨ 实现 todo_remove 工具（支持任务删除）
• ✨ 任务数据持久化到 .todos.json
• ✨ 完整的错误处理和输入验证
• ✨ 基础测试覆盖

RoadMap

v0.2.0 计划功能（已完成）

• ✅ 支持任务优先级调整（todo_update 工具）
• ✅ 支持任务备注/描述（note 字段）
• ✅ 支持任务搜索功能（search，多关键词 AND）
• ✅ 支持任务统计（摘要中的优先级分布）
• 🎯 支持导出/导入任务数据（JSON 格式）→ 顺延至 v0.3.0
• 🎯 支持任务提醒功能（改用 dsh-plugin-timer 协作）

v0.3.0 计划功能

• 🎯 支持任务子任务（嵌套结构）
• 🎯 支持任务标签/分类
• 🎯 支持任务拖拽排序（通过工具参数）
• 🎯 支持任务截止日期
• 🎯 支持任务依赖关系
• 🎯 支持任务模板

v0.4.0 及以后

• 🎯 多工作区任务同步（本地存储）
• 🎯 任务数据加密（可选）
• 🎯 任务协作功能（多人共享任务列表）
• 🎯 Web 界面集成（通过 dsh Web）
• 🎯 插件配置界面（通过 dsh CLI）

长期规划

• 🎯 支持任务周期性提醒
• 🎯 支持任务完成度分析
• 🎯 支持任务优先级算法（自动调整优先级）
• 🎯 支持任务移动到其他工作区
• 🎯 与其他项目管理工具集成

使用示例

自然语言对话即可：

• 「帮我加一条高优先级任务：明天上午提交周报」→ 调用 todo_add
• 「看看我还有哪些没做完的，按优先级排一下」→ 调用 todo_list
• 「1 号任务做完了」→ 调用 todo_done（id=1）
• 「把那个低优先级的删掉」→ Agent 先 todo_list 查 ID，再 todo_remove

测试

# 运行单元测试（39 项断言）
pnpm test

# 验证插件配置
pnpm validate

# 格式化代码
pnpm format

# 语法检查
pnpm lint

贡献指南

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

典型场景

1. 会话中记录待办

用户：帮我记一下：明天要补 D9 插件的 README

todo_add 记录任务，todo_list 随时查看。

2. 完成与清理

用户：第一个做完了

todo_done 标记完成，todo_remove 删除不再需要的条目。

3. 任务盘点

用户：我还有哪些没做完

todo_list 按状态列出，便于安排优先级；摘要给出各优先级的数量分布。

4. 搜索历史任务

用户：跟"文档"有关的任务有哪些

todo_list(search="文档") 匹配任务内容与备注，多个关键词按 AND 组合。

5. 调整优先级

用户：这条任务优先级提到 high，顺手记一句"周五前给评审"

todo_update(id=3, priority="high", note="周五前给评审")。

6. 与定时任务配合

用户：到期提醒我处理这件事

由 dsh-plugin-timer 负责计时，本插件负责记录与跟进。

其他插件集成说明

| 协作插件 | 集成方式 | |---|---| | dsh-plugin-timer | timer 负责到期提醒，本插件负责记录与跟进 | | dsh-workspace-journal | 待办事项沉淀到工作日志 | | dsh-fs-inspector | 结合目录检查确认待办涉及的文件状态 |

许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件