dsh-plugin-todo

DeepSeek Harness (dsh) TODO 管理插件：让 Agent 像项目管理工具一样管理任务列表，用户通过自然语言即可新增、查询、完成和删除任务。

功能

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

数据模型与持久化

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

{  ”tasks”: [    {      ”id”: 1,      ”content”: ”完成插件开发教程”,      ”priority”: ”high”,      ”done”: false,      ”created”: ”2026-08-22T10: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 Webpnpm dsh web --patch ./debug.patch.yml# 5. 打开 http://127.0.0.1:3080 使用插件

方式三：从本地 tarball 安装

# 1. 构建插件cd E:/dsh-plugins/dsh-plugin-todopnpm pack# 2. 安装本地包dsh plugin --profile web add ./dsh-plugin-todo-0.1.0.tgz

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

# 1. 安装依赖pnpm install# 2. 使用 pnpm 脚本直接启动（开发模式）pnpm dev# 3. 打开 http://127.0.0.1:3080 使用插件

源码及发布地址

• GitHub 仓库: https://github.com/geeklei/dsh-plugin-todo
• npm 包: https://www.npmjs.com/package/dsh-plugin-todo

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: 如何修改任务的优先级？

当前版本不支持修改已有任务的优先级。如需调整，建议删除旧任务后重新添加。

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

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

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

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

Q10: 如何卸载插件？

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

安全边界

数据隔离

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

权限控制

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

数据保护

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

输入验证

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

审计与监控

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

版本历史

v0.1.0 (2026-09-04)

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

RoadMap

v0.2.0 计划功能

• 🎯 支持任务优先级调整（todo_priority 工具）
• 🎯 支持任务备注/描述（扩展数据模型）
• 🎯 支持任务搜索功能（按内容搜索）
• 🎯 支持任务统计（按优先级、完成状态统计）
• 🎯 支持导出/导入任务数据（JSON 格式）
• 🎯 支持任务提醒功能（可选）

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

测试

# 运行单元测试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