KeepDoing
登录开始使用 KeepDoing

KeepDoing

开发者

在脚本、服务器和终端里使用你的任务。公开 API 与应用遵循同样的规则：重要的事先做，不会在你背后改动任何东西。

API

应用中的每个任务功能都是一个返回 JSON 的 HTTP 接口：

  • 任务与清单创建、编辑和整理任务，支持清单、标签、检查清单、日期和预估时长；开始、暂停、完成、取消。
  • 视图今天、近期、重要/紧急四象限、收件箱待评估汇总，以及按状态分列的看板。
  • 每日专注在专注上限内，读取和设置你承诺当天完成的几件事。
  • 批量修改一次修改最多 100 个任务，要么全部成功要么全部不变，一步即可撤销。
  • 搜索按标题、描述、标签或清单名称查找任务，按匹配位置排序。
  • 回收站与撤销删除的任务 30 天内可恢复；最近一次修改在 24 小时内可撤销。

基础地址： https://api.keepdoing.app/v1

响应统一包装为 code、message 和 data；错误带有稳定的 error_code。日期是本地日历日（YYYY-MM-DD），ID 是 UUID。

curl -H "X-API-Key: $KEEPDOING_API_KEY" \
  https://api.keepdoing.app/v1/views/today

密钥与权限范围

在这里创建个人 API 密钥： 设置 → API 密钥

通过 X-API-Key 请求头发送。请求需要的权限范围由 HTTP 方法决定：

任务权限范围
权限范围方法包含于
tasks:readGET“读取任务”和“读写任务”
tasks:write其他所有方法“读写任务”
  • 权限检查是精确匹配：写权限不包含读权限，读写密钥需要同时具备两个范围。
  • 密钥只代表你本人，只能看到你自己的工作区。别人的任务与不存在的任务返回同样的 404。
  • 密钥是给服务器、脚本和命令行用的机密。不要放进网页或公开仓库；泄露后请在设置中吊销。
  • 密钥不能创建或吊销密钥，也不能访问账户设置。

速率限制

每个密钥在任务 API 上每分钟最多 600 次请求。每个已认证的请求都会计数，包括因权限范围被拒绝的请求。

超出限制时 API 返回 429 COMMON.RATE_LIMITED，并带有以秒为单位的 Retry-After 头。等待相应时间后重试同一请求。

错误

请根据状态码和 error_code 处理错误，不要依赖可能变化或被翻译的 message 文本。

常见错误码
状态码error_code含义
401AUTH.UNAUTHORIZED没有发送密钥，也没有会话。
401API_KEY.INVALID · API_KEY.EXPIRED · API_KEY.REVOKED密钥未知或格式错误、已过期或已吊销。
403PERMISSION.DENIED密钥缺少该方法需要的权限范围。
404TASK.WORKSPACE_NOT_INITIALIZED工作区尚未设置；先打开一次应用，或运行 keepdoing auth login。
404TASK.NOT_FOUND任务不存在、不属于你，或已被永久删除。
409TASK.VERSION_CONFLICT对象在你读取后已被修改。请重新获取，再有意识地重试。
409TASK.IDEMPOTENCY_CONFLICT这个 Idempotency-Key 已用于另一个不同的请求。
422COMMON.VALIDATION_FAILED有字段不合法；errors 列出了每个字段。
428TASK.PRECONDITION_REQUIRED · TASK.IDEMPOTENCY_KEY_REQUIRED缺少必需的 If-Match 或 Idempotency-Key 请求头。
429COMMON.RATE_LIMITED这个密钥的请求过多；参见 Retry-After。
503COMMON.SERVICE_UNAVAILABLE服务暂时不可用。请用同一个 Idempotency-Key 重试。

幂等与 If-Match

Idempotency-Key

每个操作发送一个 Idempotency-Key（1–128 个可见 ASCII 字符）。创建任务、清单和标签、批量修改和撤销时必须提供，其他命令也接受。用同一个键重试会返回原来的结果，并带有 Idempotent-Replayed: true，所以连接中断也不会让修改执行两次。

curl -X POST https://api.keepdoing.app/v1/tasks \
  -H "X-API-Key: $KEEPDOING_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"title": "Write report", "importance": "important", "due_date": "2026-10-27"}'

If-Match

修改已有对象时需要 If-Match，值是你读到的版本，来自 ETag 响应头或 version 字段，例如 "task-v3"、"list-v2"、"workspace-v1"。版本过期时返回 409 TASK.VERSION_CONFLICT，而不会覆盖别人的修改。

curl -X PATCH https://api.keepdoing.app/v1/tasks/$TASK_ID \
  -H "X-API-Key: $KEEPDOING_API_KEY" \
  -H 'If-Match: "task-v3"' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"priority": "high"}'

修改任务的命令会返回 operation_id 和 undoable；POST /v1/task-operations/:operation_id/undo 可撤销最近一次操作。

keepdoing 命令行

keepdoing 把你的任务带到终端，规则与应用完全一致。它会安全地重试、自动发送 If-Match，并在覆盖修改前先询问你。

安装

# Download keepdoing_<version>_<os>_<arch>.tar.gz (.zip on Windows) from a release,
# check it against checksums.txt, then put keepdoing on your PATH.
tar -xzf keepdoing_<version>_<os>_<arch>.tar.gz
sudo mv keepdoing /usr/local/bin/

# Or build from source
cd cli && go build -o keepdoing ./cmd/keepdoing

登录

创建一个“读写任务”密钥，然后登录。密钥不会作为参数传入，也不会被打印；它保存在只有你能读取的文件中。

keepdoing auth login                          # hidden prompt
printf '%s\n' "$KEY" | keepdoing auth login   # from standard input
keepdoing auth status

示例

  • 添加一个明天截止的重要任务
    keepdoing add "Write report" --important --due tomorrow
  • 列出重要且紧急的任务
    keepdoing ls --quadrant q1
  • 查看今天：专注、需要关注、已安排和已完成
    keepdoing today
  • 按象限查看一个清单
    keepdoing matrix --list Work
  • 把任务加入今天的专注
    keepdoing focus add 0192f0c4-7b1e
  • 一步把多个任务安排到今天
    keepdoing batch schedule 0192f0c4-7b1e 0192f0c5-aaaa --date today
  • 搜索，包括已完成的任务
    keepdoing search report --done
  • 撤销最近一次修改
    keepdoing undo

象限总是同时显示图标和文字：◆ Q1 重要且紧急，◇ Q2 重要，● Q3 紧急，○ Q4 都不是，? 未评估。

退出码：0 成功，1 其他错误，2 冲突和无效输入，3 重试后仍有网络或服务器错误，4 密钥被拒绝或缺少权限范围，5 被限流。

OpenAPI

OpenAPI 3.1 文档描述了每个操作、请求和响应，可以用它生成客户端。OpenAPI 无法表达的行为，如排序、幂等和保留期限，记录在任务契约中。

查看 OpenAPI 文档（在新标签页打开）