dsh-task-todo

Readme

<h1 align="center">dsh-task-todo · 待办任务</h1>

<p align="center">在 DSH 里管理你的任务：四种视图、子任务与备注、每日/每周/每月重复，<br>
并且同一份数据对 agent 开放为工具与斜杠命令。</p>

<p align="center">
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-0B7285?style=flat-square" alt="MIT License"></a>
  <a href="https://github.com/deepseek-ai/deepseek-harness"><img src="https://img.shields.io/badge/DSH-Web%20plugin-5B4CF0?style=flat-square" alt="DSH Web plugin"></a>
  <img src="https://img.shields.io/badge/node-%3E%3D22-5FA04E?style=flat-square" alt="Node 22+">
</p>

---

## 它做什么

侧边栏在「新建会话」和「工作区」之间多出一个「待办任务」入口，点开即用主面板里的完整任务页；
再点一次同一个入口就收起、回到会话。同一份数据也是 agent 可读写的工具集。任务是全局的
（不是按会话分库），所以你早上加的任务，下午在另一个会话里依然在。

| 能力 | 说明 |
| --- | --- |
| 浮窗 | 一个可拖到页面任意位置、可拉伸大小的独立小窗口，专门用来一边看会话一边盯任务清单；它只放"我该看哪些任务"的控件，视图切换与清单管理仍留在面板里。详见下一节 |
| 四种视图 | 列表（按 逾期/今天/明天/本周/以后/未安排 分组）、看板（列 = 清单，可拖拽换清单）、日历（月网格，重复任务出现在每个发生日）、甘特图（`start` → `due` 区间，可前后翻页）。切换器在左侧栏的「视图」分组里，窄宽度下自动搬到顶栏 |
| 任务详情 | 点任意任务/子任务从屏幕正中弹出卡片（Esc、点遮罩、点 ✕ 都能关），面板和全屏用的是同一个弹窗 |
| 子任务 | 任意层级，可折叠；每个子任务有自己的备注、优先级、截止时间 |
| 备注 | 任务与子任务都能写多行备注（列表里以图标标记，鼠标悬停看内容） |
| 重复 | 每天 / 每周（可指定周几）/ 每月，支持间隔（每 2 周）、结束条件（到某天 / 共 N 次）；完成一次会滚动到下一次并重置子任务 |
| 快速添加 | 一句话搞定：`明天 15:00 交周报 !高 #工作 @紧要`；输入框下方**实时显示这次回车会创建什么**（标题、截止、重复、优先级、标签、清单，清单不存在时会说明将自动创建）——识别结果来自宿主自己的解析器，所见即所得 |
| 标签 | 左栏「标签」分组列出所有用过的标签与未完成计数，点一下只看该标签；搜索框输入 `#工作` 是同一件事。标签可整体改名（改一次，所有任务跟着变）或清空 |
| 智能清单 | 今天 / 最近 7 天 / 已逾期 / 未安排 / 全部 / 已完成，带实时计数 |
| 清单管理 | 左栏每行一个清单：点齿轮（或选中该行后点）打开居中弹窗，可**改名 / 换颜色 / 上移下移 / 删除**；也能直接拖拽换位置。颜色是 8 个预设色，点一下即生效 |
| 新建清单 | 左栏「清单」分组里直接输入名字回车即建，输入框前的圆点就是它将要得到的颜色（宿主决定的，不是猜的） |
| 数据与备份 | 左侧栏「数据」分组写明数据文件叫什么、在哪儿，并给出一键 导出备份 / 导入恢复 / 复制路径 |
| 全屏 | 覆盖整个框架的全屏模式（Esc 退出，再点入口也可收起），切换不丢当前视图与筛选 |
| 侧边栏徽标 | 入口图标右上角显示待办数（口径可在设置里切换：今天 / 逾期 / 未完成） |
| 与 agent 协作 | 6 个工具 + `/todo` 斜杠命令 + 随包分发的技能，天然可对话操作 |

---

## 浮窗

一个**可拖、可拉伸的独立小窗口**，用来一边干别的、一边把任务清单摆在眼前。

- **怎么打开**：面板（或全屏）头部点「⇱ 浮动」；浮动后同一位置变成「⇤ 停靠」和「✕ 关闭」，
  停靠就是把界面交回侧边栏面板，关闭则是收起窗口。`Ctrl+K` 命令面板里也有「浮动窗口 / 停靠回面板」。
  它挂在框架级覆盖层上，所以不会被侧边栏或面板裁切。
- **摆放**：拖头部挪位置，右下角的小三角拉伸尺寸（最小宽度 260px）。
  位置与尺寸记在浏览器本地（`dsh-task-todo:float:v1`），下次打开还在原处——不用每次都重新摆。
- **窗口里只放三件事**：顶部常驻的捕获条（和面板同一个输入框、同一份草稿与预览）、一条「浮窗栏」
  （智能清单页签：今天 / 最近 7 天 / 已逾期 / 未安排 / 全部 / 已完成，带计数，窄了可横向滚）、
  以及清单选择器（每个清单带自己的未完成数）。视图切换、搜索、清单管理、标签与数据块都留在面板里，
  所以这个窗口就是一份清单，不是第二个面板。
- **行在这里是紧凑形态**：只有复选框 + 标题（悬停看完整标题），没有元信息胶囊、没有行尾 ＋ / ×、
  不展开子任务树，行高也更小。窗口只有几百像素宽时，卡片和一堆元信息会把标题挤成一个字一行。
- **它有自己的皮肤**：窗口内单独重指了一层令牌——奶白表面 + 蓝色强调，连复选框的勾都是蓝的
  （不是面板里那个绿色）；蓝色只承担"状态"（当前页签、复选框、你所在的那一行），
  任务标题是窗口里唯一的重色文本，其余都退成发丝线级别的底噪。深色主题下同样成立。
- **同一份数据**：浮窗、侧边栏面板、全屏、agent 的 6 个工具共用同一个数据文件与同一份界面状态，
  在窗口里勾完、回面板看不丢，换个座位也不丢。

---

### 界面

![列表视图](docs/images/panel-list.png)

| 看板 | 日历 |
| --- | --- |
| ![看板](docs/images/board.png) | ![日历](docs/images/calendar.png) |

| 甘特图 | 任务详情 |
| --- | --- |
| ![甘特图](docs/images/gantt.png) | ![任务详情](docs/images/dialog.png) |

| 深色列表 | 深色看板 | 深色任务详情 |
| --- | --- | --- |
| ![深色列表](docs/images/list-dark.png) | ![深色看板](docs/images/board-dark.png) | ![深色任务详情](docs/images/dialog-dark.png) |

---

## 安装

前置：已安装 DeepSeek Harness（`dsh`，且 `dsh web` 能跑起来），Node ≥ 22。

```sh
# 从 npm 安装（包发布后可用；当前请先 git clone 再指本地目录）
dsh plugin --profile web add dsh-task-todo

# 或者指到本地目录（开发形态）
dsh plugin --profile web add "<插件目录的绝对路径>"
```

然后**重启 `dsh web`**：bundle 层只在启动时读取。带 UI 的插件还要
`Ctrl+F5` 强刷一次浏览器（客户端 bundle 按包路径缓存）。

卸载：

```sh
dsh plugin --profile web remove dsh-task-todo
```

## 配置

设置 → 插件 → 待办任务：

| 项 | 默认 | 说明 |
| --- | --- | --- |
| 启用 | 开 | 关闭后工具与界面都不工作 |
| 数据文件 | `<DSH_HOME>/todo/tasks.json` | 留空用默认；改动会重新加载 |
| 默认清单 | 收集箱 | 新增任务未指定清单时的归属 |
| 每周起始日 | 周一 | 只影响日历视图的列顺序 |
| 侧边栏徽标 | 今天 | 今天（今天到期 + 逾期）/ 逾期 / 未完成 |

---

## Skills

| Skill | 用途 |
| --- | --- |
| `todo` | 教模型如何用这 6 个工具、日期与重复约定、快速添加语法、以及哪些事不要承诺（例如提醒） |

## MCP servers

无。本插件不依赖外部进程。

## Tools

| 工具 | 参数 | 返回 |
| --- | --- | --- |
| `task_list` | `filter` `list` `query` `includeDone` `includeSubtasks` `today` | 任务列表 + 计数 + 全部清单（含 id/颜色/顺序/任务数）+ 文本摘要 |
| `task_add` | `title` `due` `start` `priority` `list` `tags` `note` `repeat` `repeatInterval` `repeatWeekdays` `repeatUntil` `repeatCount` `parent` | 新任务 |
| `task_update` | `id`(或唯一标题) + 任意可改字段 | 更新后的任务 |
| `task_done` | `id` `undone` | 任务（重复任务会滚动到下一次） |
| `task_delete` | `id` | 被删除的 id（含子任务） |
| `list_manage` | `action`(list/create/update/move/delete) `id`(或唯一清单名) `name` `newName` `color` `index` `delta` | 清单（或清单列表）+ 文本摘要 |

`id` 也接受唯一标题；标题不唯一时会拒绝并返回候选，不会替你猜。清单同理：`list_manage`
接受唯一的清单名，删除只删分组、任务移到「收集箱」，系统清单「收集箱」删不掉。

## 斜杠命令

| 命令 | 行为 |
| --- | --- |
| `/todo` | 今天的概览 |
| `/todo add <文本>` | 快速添加 |
| `/todo ls [今天\|本周\|逾期\|未安排\|全部\|已完成]` | 列出任务 |
| `/todo done <id\|标题>` | 完成 |
| `/todo help` | 语法速查 |