滴答任务桥 ztllll/dida-todo

dida-todo

中文 · English

让滴答清单成为人与 Pi Agent 共享的长期工作入口：人随时记录，Agent 领取执行，进度实时回写，完成后由人验收。

dida-todo 是 Pi Coding Agent 扩展，同时提供 dsh（DeepSeek Harness） 插件。它保留 todo 工具、/todos 命令和编辑器上方的 Todo 面板，但把滴答清单作为任务真源。在 dsh 上它还负责会话中断后自动续跑。

工作方式

人在滴答记录任务并设优先级 → Pi 空闲时自动领取（或完整输入“检查todo”立即执行） → Agent 按 Checklist 执行，每步结果写成滴答评论 → 全部完成：顶层任务自动完成，并生成“🧑🔬 待验收”任务（+3/+6 分钟提醒） → 人完成验收任务即闭环；在验收任务下本人评论 = 自动返工

数据模型：

一个滴答清单（绑定一个项目 / tmux pane） ├── 顶层工作任务（一次完整请求） │ └── Checklist 子项（Agent 的执行步骤） ├── 🧑🔬 待验收任务 └── 🙋 需要你处理（Agent 挂起等待你时的提醒）

Agent 什么时候建 Todo

在已绑定会话里，Agent 在开始工作前判断，满足任一条件就建一个顶层工作并一次写好所有子项：

1. 你明确要求追踪 / 记录 / 加 Todo；
2. 请求有 3 个及以上独立交付步骤（例如多处修复、代码 + 测试 + 文档）；
3. 工作会跨轮或跨会话；
4. 后台 / 轮询执行，需要事后验收。

聊天、问答、只读排查、调研总结、单条命令、一处小改动都不会建 Todo。

任务卡住、需要你时

Agent 遇到必须由人确认、授权、决策或线下操作才能继续的任务时，会调用 todo_work wait_for_human：

- 滴答上这个任务的优先级被清零，轮询不再领取，不会每 10 分钟刷屏；
- 新建一条 🙋 需要你处理：<任务名>，写明原因，+3 / +6 分钟提醒两次；
- 原任务保持未完成，不会被硬勾掉，并写一条原因评论。

恢复方式（任选其一）：在原会话里发任何消息（Pi 或 dsh），会自动恢复挂起的工作并勾掉 🙋 提醒；也可在滴答勾掉 / 删除 🙋 提醒，或把原任务优先级改回低/中/高，在下次同步时恢复。dsh 默认不开轮询，想立即恢复请在会话里回复；dsh 只恢复本会话拥有的工作，Pi 恢复当前绑定内的挂起工作。

兜底：即使 Agent 没有调用挂起，只要队列自上次唤醒后没有任何变化（没有进展、你也没有编辑），轮询也不会再重复唤醒 Agent。

两种任务的完成规则

- 直接任务（只有描述）：Agent 建一个可见步骤并完成，顶层随之完成。
- Checklist 任务（若干子项）：所有子项完成或跳过后，顶层任务自动完成，Agent 不需要自己去勾顶层。只有你明确要求“顶层保持未完成”时才会保留。
- 循环任务按实例执行：今天的实例完成只影响今天，到点后下一次轮询领取，错过的实例不补跑。

dsh：中断自动续跑

dsh 会话经常因为模型返回 content_filter、429 限流、Overloaded 或进程崩溃而停下，而且停下后不会自己继续，必须有人输入“继续”。dida-todo 的 dsh 插件接管这件事：

- 自动续跑：回合以错误或崩溃结束、且会话还有未完成工作（滴答工作、dsh goal、todo_write 清单任一）时，等 30s / 1m / 2m / 5m / 10m 后自动发一条续跑消息；content_filter 会提示模型换个说法，不原样重复。
- goal 复活：dsh 官方 goal 驱动器出错后会停止自动推进，插件会先把 goal 重新激活。
- 转人工：连续 5 次续跑仍中断，就在滴答清单建 🙋 需要你处理 提醒（+3/+6 分钟两次），不再无限重试。
- 人优先：你在会话里发任何消息，待发的续跑立即撤销。你主动点停止的回合不会续跑。
- 已绑定滴答清单的目录里，dsh 同样可用 todo / todo_work、自动收口和待验收，与 Pi 共用同一套绑定。滴答 Checklist 会显示在 dsh 输入框上方的“任务”面板里（完成 / 进行中 / 待办），和 Pi 的 Todo 面板一样随步骤实时更新。
- 按会话隔离：同一项目开多个 dsh 会话时，每个会话只显示、只推进自己创建或领取的工作；新会话不会接管别的会话正在执行的工作，新建的任务也不会并进去。要让某个会话接手别人的工作或清单里的新任务，在该会话输入 检查todo。
- 标准 / PTC 模式兼容：dsh 适配层将 todo / todo_work 的 TypeBox 参数定义转换为纯 JSON Schema，只剥离 TypeBox 隐藏元数据并保留参数约束，避免 PTC 生成工具 SDK 时出现 parameters must be lossless JSON before schema projection。Pi 仍使用原始 TypeBox schema，dsh 宿主的严格 JSON 校验不变。

安装：dsh 侧栏 插件 → 添加插件，填 github:ztllll/dida-todo#v0.9.5；或命令行 dsh plugin --profile web add "github:ztllll/dida-todo#v0.9.5"。仓库本身就是标准 dsh 组合包（package.json 声明 dsh.bundle），出现在插件页「已安装」里，可停用、可卸载。它只新增一行插件和 todo / todo_work 两个工具，不覆盖、不禁用 dsh 自带的 todo_write 与任务面板；卸载后 dsh 恢复原样。详见 dsh-plugin/README.md。

绑定沿用 ~/.config/pi-dida-todo/config.json 的 cwd 绑定（在 Pi 中 /dida-bind 一次即可）。未绑定目录里续跑仍然生效，只是用尽后无处发滴答提醒。

已验证的 dsh 版本：0.2.0-rc.2、0.2.1-rc.2。dsh 升级后插件无需重装，升级 dsh 不会卸载它。

安装

pi install git:github.com/ztllll/dida-todo@v0.9.5

新开 Pi 会话后：

1. 对智能体说「登录滴答」（浏览器 OAuth，依赖已随包安装）；
2. 执行 /dida-bind [清单名称]：唯一同名清单直接绑定，不存在则按输入名称创建，取消则什么也不做。

升级时先等正在使用 dida-todo 的 Pi 空闲，再安装新版本，然后对每个已运行的 Pi 执行 /reload。忙碌时覆盖安装可能让旧进程与新文件混用。0.9.5 的会话回复恢复与收尾护栏在新插件加载后生效；无需改绑定或开启 dsh 轮询。

与 rpiv-todo 冲突（两者都注册 todo 和 /todos），需先禁用。

使用

| 操作 | 方式 |
| 看当前工作 | /todos；Ctrl+Shift+T 折叠/展开面板 |
| 立即执行整个队列 | 完整输入 检查todo（近似说法不会触发） |
| 加 / 改 / 完成 Todo | 自然语言，只操作对应工作，不扫描队列 |
| 暂存草稿 | 在滴答创建任务但不设优先级，不会被执行 |
| 恢复挂起任务 | 在原会话回复；或勾掉 / 删除 🙋 提醒、改回优先级后同步 |

调度规则

- 收尾护栏：正常结束仍有 pending / in_progress 子项时，自动续写一轮要求逐项核对：已验证的 completed，确定不做的 skipped / deleted（不能删除用户原始子项），仍在进行或被阻塞的保持原状并说明原因，需要人类决定时挂起，不开始新工作；每条人类消息之后最多一次，等待人类时不催促。dsh 子代理不触发此护栏，也不因此开启轮询。

- 轮询默认 10 分钟（pollIntervalMinutes 可设 1–1440），只在 Pi 空闲且无待处理消息时运行，只在 TUI 会话里运行。
- 只执行：优先级为低/中/高、未完成、且已到计划时间的任务。按优先级高→中→低，同级保持滴答顺序。
- 计划时间 = startDate ?? dueDate，按任务时区判断。非全天任务需当天且已到点；全天任务只看日期；没有日期则随时可执行。

宿主模式

| 模式 | 面板 | 启动同步 | 自动轮询 |
| TUI（已绑定） | 是 | 是 | 是 |
| Web/RPC（如 pi-web） | 是 | 是 | 否 |
| Print（pi -p） | 否 | 否 | 否 |
| 未绑定目录 | 被动 | 否 | 否 |

Pi 自带的 --mode rpc 命令行客户端只渲染字符串，看不到面板；pi-web 正常。

配置

~/.config/pi-dida-todo/config.json（/dida-bind 会自动写入）：

{
"pollIntervalMinutes": 10,
"maxWidgetLines": 12,
"collapseKey": "ctrl+shift+t",
"autoResumeSingle": true,
"bindings": [
{ "key": "tmux:my-project:0.0", "cwd": "/abs/path", "projectId": "DIDA_PROJECT_ID", "label": "my-project" },
{ "key": "cwd:/abs/path", "projectId": "DIDA_PROJECT_ID", "label": "my-project" }
]
}

精确 tmux target 优先于精确 cwd；绑定的清单被删除时回退到同 cwd 的有效绑定。

限制

1. 滴答官方 API 没有附件接口：链接可用，文件请走 IM 通道。
2. 滴答子项没有「进行中」状态，只在 Pi 面板显示。
3. 同一台机器上的并发写有跨进程锁；多台机器之间没有强一致保证（滴答 API 无 CAS/ETag）。
4. 只针对滴答清单，不保证 TickTick 国际版。
5. 等待人类的去重记录在内存中，重启 Pi 后会对未变化的队列重新唤醒一次。
6. dsh 安装或升级插件后刷新/重启 dsh-web 生效；续跑计数在内存中，重启 dsh 后清零（重启时被打断、30 分钟内的回合会在恢复后续跑）。

开发

git clone https://github.com/ztllll/dida-todo.git && cd dida-todo
npm ci && npm run check
npm run e2e:dsh # 真实 dsh 端到端验证（临时目录，不碰本机 ~/.dsh）

开发约定见 AGENTS.md，安全问题见 SECURITY.md，变更见 CHANGELOG.md。

致谢：@juicesharp/rpiv-todo（Todo 交互设计）、@suibiji/dida-cli（滴答 CLI）、Pi。与滴答官方无隶属关系。

维护者：Ztllll（@ztllll）。只在 GitHub 发布，不发 npm。MIT 许可。

dida-todo 是 Pi Coding Agent 的扩展，让 Dida365 成为 todo 工具、/todos 和 Todo 面板的持久数据源。
- 流程： 在滴答清单里建任务并设优先级 → 空闲 TUI 轮询器（或输入 检查todo）认领到期工作 → 智能体按 Checklist 逐项执行，并回帖每一步结果 → 所有 Item 完成或跳过后，顶层任务自动完成，同时创建一个 🧑🔬 验收任务，带两条提醒（+3/+6 分钟）。你用自己账号在该任务下评论，就会触发返工。
- 智能体何时创建 Todo： 你要求跟踪进度、请求包含 3 个以上独立交付物、工作跨多轮对话或会话，或后台运行需要验收。聊天、问答、只读检查、调研、单个小操作，一律不建。
- 卡在等人： 智能体调用 todo_work wait_for_human。任务优先级被清空（轮询停止），🙋 提醒触发两次，任务保持打开。在原始会话里发任意人类消息即可恢复并完成提醒；也可以在滴答清单里完成或删除 🙋 提醒（或恢复优先级）再同步。dsh 只恢复自己的工作；Pi 恢复当前绑定里等待中的工作。兜底机制：队列没变化时，轮询器不会重新唤醒智能体。
- dsh 插件： 仓库根目录是标准 dsh bundle：在 Plugins 页面用 github:ztllll/dida-todo#v0.9.5 安装；它只新增一行插件和 todo/todo_work 工具，绝不覆盖内置的 todo_write，卸载后 dsh 恢复原样。某轮以错误结束（content_filter、429、Overloaded）或崩溃，且会话仍有未完成工作（滴答清单工作、dsh goal 或 todo_write 列表）时，它会按退避策略（30s 到 10m）重新提示智能体，重新激活被解除的 goal，连续失败 5 次后在滴答清单留一条提醒。任意人类消息都会取消待执行的继续。已在 dsh 0.2.0-rc.2 和 0.2.1-rc.2 验证。
- dsh 原生 / PTC 兼容： dsh 适配器把 todo 和 todo_work 的 TypeBox 参数定义转成纯 JSON Schema，只剥离 TypeBox 的隐藏元数据，保留参数约束。这样可避免 PTC SDK 生成时报 parameters must be lossless JSON before schema projection。Pi 保留原有 TypeBox schema，dsh 严格的宿主 JSON 校验不变。
- 安装： pi install git:github.com/ztllll/dida-todo@v0.9.5，然后说「登录滴答清单」并运行 /dida-bind [name]。请在 Pi 空闲时安装，装完对运行中的会话执行 /reload。
- 收尾守卫： 正常结束但仍有未完成 Item 时，会追问一次，让你复查这些 Item，同时不会误关进行中或受阻的工作，每条人类消息最多触发一次。等待中的工作不在此列；dsh 子代理也不在此列。
- 宿主： TUI 有面板 + 同步 + 轮询器；Web/RPC（pi-web）有面板 + 同步，没有轮询器；Print 和未绑定目录保持被动。
- 限制： 没有附件 API；Checklist Item 没有原生的进行中状态；不保证跨机器强一致；仅支持滴答清单。

开发规则：AGENTS.md。MIT 协议。