google-tasks

通过 curl + jq 操作 Google Tasks。用户的 OAuth 持有者令牌位于 $GOOGLE_TASKS_TOKEN；每次调用都需要使用 Authorization: Bearer $GOOGLE_TASKS_TOKEN。令牌至少包含 tasks.readonly 和身份范围 （openid email profile）；如果用户在安装时选择启用写入权限，还会包含更广泛的 tasks 范围（读写）。

Tasks API 返回标准 JSON；失败时会显示为 {"error": {"code": 401|403|..., "message": "..."}}——原样显示该 错误。401 表示令牌已过期（重新安装）。写入操作出现 403 insufficientPermissions 表示用户只授予了 tasks.readonly——请让他们 勾选读写选项后重新安装。

始终先调用 users/@me/lists，以查明账号有哪些任务清单 ——包括用户的默认清单，以及他们在 calendar.google.com 或 Tasks 应用中创建的其他清单。

批量创建、完成或删除任务前，向用户逐一列出确切标题并请他们确认。不要靠猜测 ID 来删除 任务。

操作示例

验证身份验证并列出所有任务清单（始终首先运行）

curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq '.items[] | {id, title, updated}'

默认清单通常名为“我的任务” / “My Tasks”，但后续每次调用 lists/{id}/tasks 都需要使用 id（类似 MTAxMjM0NTY3OA 的不透明长字符串）。

列出所有清单中未完成的任务

curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
      --data-urlencode 'showCompleted=false' \
      --data-urlencode 'maxResults=100' \
      | jq --arg list "$LIST_TITLE" '.items[]? | {list: $list, title, due, status, notes}'
  done | jq -s '. | sort_by(.due // "9999")'

showCompleted=false 会在 API 层面筛除已完成的项目。默认的 showCompleted=true&showHidden=false 也会返回已完成的任务。

列出某个特定清单中按截止日期排序的待办任务

LIST_ID='MTAxMjM0NTY3OA'
curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
  --data-urlencode 'showCompleted=false' \
  --data-urlencode 'maxResults=100' \
  | jq '.items // [] | sort_by(.due // "9999") | .[] | {title, due, notes, status, position}'

position 是用户在清单内拖动排序的排名——用户询问“我的任务列表顶部是什么”时很有用。没有 due 字段的任务没有截止期限。

今天到期的任务

TODAY=$(date -u +%Y-%m-%d)
TOMORROW=$(date -u -d "+1 day" +%Y-%m-%d 2>/dev/null \
  || date -u -v+1d +%Y-%m-%d)
TODAY_START="${TODAY}T00:00:00.000Z"
TOMORROW_START="${TOMORROW}T00:00:00.000Z"

curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
      --data-urlencode "dueMin=$TODAY_START" \
      --data-urlencode "dueMax=$TOMORROW_START" \
      --data-urlencode 'showCompleted=false' \
      | jq --arg list "$LIST_TITLE" '.items[]? | {list: $list, title, due, notes}'
  done | jq -s

dueMin / dueMax 是 RFC 3339 时间戳。Tasks API 将 due 存储为 UTC 午夜，因此当地日期范围在日期边界附近只是近似值——对于“今天到期”的语义来说没有问题；只有用户提出异议时才需要说明这一点。

已逾期的任务（所有仍待办且截止日期已过的任务）

NOW=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
      --data-urlencode "dueMax=$NOW" \
      --data-urlencode 'showCompleted=false' \
      | jq --arg list "$LIST_TITLE" '.items[]? | {list: $list, title, due, daysOverdue: (((now * 1000) - (.due | sub("Z"; "+00:00") | fromdateiso8601 * 1000)) / 86400000 | floor)}'
  done | jq -s

最近完成的任务（本周，供回顾）

ONE_WEEK_AGO=$(date -u -d "-7 days" +%Y-%m-%dT%H:%M:%S.000Z 2>/dev/null \
  || date -u -v-7d +%Y-%m-%dT%H:%M:%S.000Z)

curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq -r '.items[] | "\(.id)\t\(.title)"' | while IFS=$'\t' read LIST_ID LIST_TITLE; do
    curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
      --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
      --data-urlencode 'showCompleted=true' \
      --data-urlencode 'showHidden=true' \
      --data-urlencode "completedMin=$ONE_WEEK_AGO" \
      | jq --arg list "$LIST_TITLE" '.items[]? | select(.status=="completed") | {list: $list, title, completed}'
  done | jq -s '. | sort_by(.completed)'

completedMin / completedMax 与 dueMin / Max 类似，只适用于已 移至“已完成”状态的任务。要查看这些任务，必须传入 showCompleted=true 和 showHidden=true——Google 会从默认列表中隐藏 已完成的任务。

获取单个任务的详情

LIST_ID='MTAxMjM0NTY3OA'
TASK_ID='dGFza0lkRXhhbXBsZQ'
curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
  | jq '{title, due, status, notes, completed, position, links: .links}'

links 会显示用户手动添加的超链接（例如附加的邮件 或 Drive 文档）——如果存在，请将它们以列表形式展示给用户。

分页

maxResults 每页最多为 100。使用 nextPageToken：

LIST_ID='MTAxMjM0NTY3OA'
PAGE_TOKEN=''
while : ; do
  RESP=$(curl -sS -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
    --get "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
    --data-urlencode 'maxResults=100' \
    --data-urlencode 'showCompleted=false' \
    ${PAGE_TOKEN:+--data-urlencode "pageToken=$PAGE_TOKEN"})
  echo "$RESP" | jq -c '.items[]?'
  PAGE_TOKEN=$(echo "$RESP" | jq -r '.nextPageToken // empty')
  [ -z "$PAGE_TOKEN" ] && break
done

写入操作示例

这些操作都需要更广泛的 tasks 范围。如果用户只授予了 tasks.readonly，你会收到 403 insufficientPermissions——请展示该错误，并让他们勾选读写选项后重新安装。

添加新任务

LIST_ID='MTAxMjM0NTY3OA'
curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"title":"Draft Q2 plan","notes":"Outline + risks + asks.","due":"2026-05-15T00:00:00.000Z"}' \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
  | jq '{id, title, due, status}'

Google 会将 due 存储为所选日期 UTC 午夜——界面会忽略具体时间。 要将任务插入清单最顶部，请在 URL 中添加 ?previous=（不填值）。

经用户确认后批量添加三个任务

LIST_ID='MTAxMjM0NTY3OA'
DUE='2026-05-12T00:00:00.000Z'
for T in 'Reply to Alice' 'Review PR #404' 'Send meeting recap'; do
  curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
    -H 'Content-Type: application/json' \
    --data "{\"title\":$(jq -nr --arg t "$T" '$t'),\"due\":\"$DUE\"}" \
    "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks" \
    | jq -c '{id, title, due}'
done

运行此循环前，务必列出即将创建的任务标题并征得用户同意——没有原子批量接口。

将任务标记为已完成

LIST_ID='MTAxMjM0NTY3OA'
TASK_ID='dGFza0lkRXhhbXBsZQ'
NOW=$(date -u +%Y-%m-%dT%H:%M:%S.000Z)
curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data "{\"status\":\"completed\",\"completed\":\"$NOW\"}" \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
  | jq '{id, title, status, completed}'

使用 {"status":"needsAction","completed":null} 可撤销此操作。

编辑任务的标题 / 备注 / 截止日期

LIST_ID='MTAxMjM0NTY3OA'
TASK_ID='dGFza0lkRXhhbXBsZQ'
curl -sS -X PATCH -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"title":"Draft Q2 plan (rev2)","notes":"Cover risks + asks + budget.","due":"2026-05-20T00:00:00.000Z"}' \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
  | jq '{id, title, due, notes}'

删除任务

LIST_ID='MTAxMjM0NTY3OA'
TASK_ID='dGFza0lkRXhhbXBsZQ'
curl -sS -X DELETE -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID" \
  -o /dev/null -w 'HTTP %{http_code}\n'

204 = 成功。此操作不可软删除——任务一旦删除就无法恢复。删除前，先向用户复述任务标题。

重新排序：将任务移至指定位置

LIST_ID='MTAxMjM0NTY3OA'
TASK_ID='dGFza0lkRXhhbXBsZQ'
PREV='dGFza0lkUHJldg'  # task id this one should appear AFTER; omit to move to top
curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  --data '' \
  "https://tasks.googleapis.com/tasks/v1/lists/$LIST_ID/tasks/$TASK_ID/move?previous=$PREV" \
  | jq '{id, title, parent, position}'

使用 ?parent=... 代替 ?previous=...，可将任务嵌套到另一个任务下，作为子任务。

创建全新的任务清单

curl -sS -X POST -H "Authorization: Bearer $GOOGLE_TASKS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"title":"Q2 follow-ups"}' \
  "https://tasks.googleapis.com/tasks/v1/users/@me/lists" \
  | jq '{id, title}'

常见错误代码

HTTP	含义	告诉用户的内容
401 UNAUTHENTICATED	令牌已过期／已撤销	“请在 Connections 页面重新连接 Google Tasks 连接器。”
403 insufficientPermissions	缺少写入权限范围	“此操作需要 Tasks 读写权限范围，但当前仅授予了 tasks.readonly。请勾选读写选项并重新安装连接器。”
404 notFound	列表 ID／任务 ID 错误	使用 users/@me/lists 重新列出，以查找正确的 ID。
429 quotaExceeded	配额超限／请求受限	等待约 5 秒后重试一次。

切勿记录或回显 $GOOGLE_TASKS_TOKEN——请将其视为机密。