Dida-Task:滴答清单 Agent 工具
让 agent 完全打通滴答清单(Dida365):读、写、统计一应俱全。
何时使用
触发场景:
- 用户要写任务到滴答:"加个任务"、"提醒我..."、"加到 dida / 滴答"
- 用户要读滴答数据:"今天完成了哪些任务"、"我有哪些清单"、"专注了多久"
- 用户要统计/复盘:"这周完成了什么"、"花了几个番茄在 X 上"
不要触发:
- 用户的"任务"明显指当前对话工作项,不是 App 里的任务
- 用户在专门的 GTD 笔记系统里操作(除非明确说"同步到滴答")
首次使用
凭证未配置时,先引导用户走 setup:
bashpython3 scripts/dida.py setup
详细引导见 setup.md。
能力速查
所有命令统一入口:python3 scripts/dida.py <子命令>
读
| 命令 | 作用 |
|---|---|
read list-projects | 列所有清单 |
read list-columns <project> | 列 kanban 清单的分组(columns) |
read list-tasks <project> | 列某清单下未完成任务 |
read get-task <task-id> | 拿单个任务详情 |
read search <关键词> | 全量任务模糊搜索(按标题/内容) |
read today | 跨清单:今日到期的未完成任务,按清单分组 |
read upcoming [--days N] | 跨清单:未来 N 天(默认 7)到期 |
read by-tag <tag> [--prefix] | 按标签筛选;--prefix 含子标签(如 12wy 匹配 12wy/a) |
read list-tags | 列出账号所有标签(含父子关系、颜色) |
read completed-today | 今天已完成任务 |
read completed-range <from> <to> | 按日期范围拉已完成任务 |
番茄/专注
| 命令 | 作用 |
|---|---|
pomo today | 今天专注总时长 + 段数 |
pomo by-task <task-id-或关键词> | 某任务花了几个番茄 / 多少分钟 |
pomo stats <from> <to> | 按日期范围的专注统计(heatmap + 项目分布) |
写
| 命令 | 作用 |
|---|---|
write create-task --title <标题> [选项] | 创建任务 |
write update-task <task-id> [选项] | 更新任务 |
write complete-task <task-id> | 标记完成 |
write delete-task <task-id> | 删除任务(默认 dry-run) |
write add-subtask <task-id> --title <标题> | 给任务追加一个子任务(checklist 项) |
write complete-subtask <task-id> <子任务-id-或关键词> | 标记某子任务完成 |
write create-project --name <名字> [选项] | 创建清单 |
write update-project <project-id> [选项] | 更新清单 |
write delete-project <project-id> | 删除清单(默认 dry-run) |
create-task / update-task 选项:
| 参数 | 说明 |
|---|---|
--content <文本> | 备注内容 |
--project <id|名字> | create-task:目标清单(默认收件箱);update-task:移动到该清单 |
--priority {0,1,3,5} | 0 无 / 1 低 / 3 中 / 5 高 |
--due <YYYY-MM-DD[THH:MM]> | 截止时间 |
--all-day | 全天任务(忽略时分) |
--repeat "RRULE:..." | 重复规则,如 RRULE:FREQ=WEEKLY;BYDAY=MO |
--column <id|名字> | kanban 分组(需配合 --project) |
--tags "a,b,c" | 标签数组,逗号分隔 |
--items "step1|step2|step3" | 子任务(仅 create-task;竖线分隔,自动设 kind=CHECKLIST) |
元
| 命令 | 作用 |
|---|---|
setup | 首次配置(OAuth + cookie) |
refresh-token | OAuth token 过期时重走授权 |
refresh-cookie | Cookie 失效时引导更新 |
health | 检查 token / cookie 状态 |
所有命令支持 --json 输出结构化数据,方便 agent 解析。
Agent 使用准则
- 写操作默认确认:
delete-task/delete-project默认 dry-run,加--confirm才真删 - 批量写入要分步:一次创建多个任务时,先列计划→等用户确认→再调 API
- 批量必须限速:官方 API 限流 100 req/min per token(滚动 60s 窗口,超限返回 HTTP 500
exceed_query_limit,不是 429)。批量写入每条 sleep 1s,超过 50 条每 20 条歇 30s。注意update-task/delete-task/complete-task内部会调_find_project_id_of_task,最坏遍历所有清单(N+1 次调用),是隐藏的限流杀手 —— 大批量操作前先read list-projects拿到 project id 直接传,能少一半请求 - 凭证失败要给指引:API 401/500 access_forbidden 时,不要重试,告诉用户跑哪个 refresh 命令
- 限流触发等满 60 秒:触发
exceed_query_limit后等满 60s,不是 30s(滚动窗口) - 输出尊重用户语境:用户问中文就用中文回,时间用北京时间
详细文档
- setup.md — 首次配置完整流程(如何申请 client_id、拿 cookie)
- api-reference.md — 官方 + 私有 API 端点速查
- examples/usage.md — 常见用法示例
重要声明
已完成任务读取、番茄统计走的是滴答的私有 API(非官方公开),用 cookie 鉴权:
- 优点:功能完整(官方 OpenAPI 没有这些能力)
- 风险:滴答随时可能改、cookie 会过期(几周到几个月)
- 失败时 skill 会给出明确的 refresh 指引,不会卡死
所有写操作(建任务/改任务/删任务)走官方 OpenAPI,稳定可靠。


