钉钉待办 API 管理与操作：需要创建、查看、更新…

通过钉钉开放平台待办 API 管理钉钉待办任务，覆盖创建、查询、更新、完成、删除及身份/Token 配置。

适用场景

解决思路

1. 每次执行前，用一条 `grep -E` 命令一次性读取配置文件 `~/.dingtalk-skills/config` 中所有所需配置键值；配置文件跨会话保留，无需重复询问。
2. 仅收集缺失配置：若配置文件不存在或缺少某项，一次性询问用户所有缺失的值，不要逐条问。
3. 持久化配置：将收集到的值写入 `~/.dingtalk-skills/config` 文件，后续无需再问。
4. 获取/复用 Token：有效期内复用缓存，缓存 `7000` 秒（约 2 小时），避免重复请求；遇 `401` 重新获取。
5. 执行命令时，凡是包含变量替换、管道或多行逻辑的命令，写入 `/tmp/<task>.sh` 再执行 `bash /tmp/<task>.sh`；不要把多行命令直接粘到终端里，也不要用 `<<'EOF'` 语法，因为终端工具会截断且 heredoc 会丢失变量。
6. 凭证禁止在输出中完整打印，确认时仅显示前 4 位 + `****`。
7. 获取配置：`DINGTALK_APP_KEY` 从钉钉开放平台 → 应用管理 → 凭证信息获取；`DINGTALK_APP_SECRET` 从同一位置获取；`DINGTALK_MY_USER_ID` 从管理后台 → 通讯录 → 成员管理 → 点击姓名查看（不是手机号、不是 unionId）；`DINGTALK_MY_OPERATOR_ID` 首次由脚本自动通过 userId 转换获取并写入。
8. 识别身份标识：`userId`（= `staffId`）是企业内部员工 ID，最容易获取；`unionId` 是跨企业/跨应用唯一，通过 userId 调用 API 转换获取。
9. 在待办 API 中，路径参数 `{unionId}` 和查询参数 `operatorId` 均使用 `unionId`；`executorIds` / `participantIds`（指派同事）也使用 `unionId`。
10. 配置中优先收集 `userId`，由脚本自动转换为 `unionId`。
11. 执行 userId 到 unionId 转换：先获取旧版 access_token：`OLD_TOKEN=$(curl -s "https://oapi.dingtalk.com/gettoken?appkey=${APP_KEY}&appsecret=${APP_SECRET}" | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)`；再 POST 到 `https://oapi.dingtalk.com/topapi/v2/user/get?access_token=${OLD_TOKEN}`，使用 `-H 'Content-Type: application/json'` 和 `-d "{\"userid\":\"${USER_ID}\"}"`，提取 `unionid` 后写入配置：`echo "DINGTALK_MY_OPERATOR_ID=$UNION_ID" >> ~/.dingtalk-skills/config`。
12. 转换时注意：返回体中 `result.unionid`（无下划线）有值，`result.union_id`（有下划线）可能为空。
13. 给同事创建待办时，若需要指定 `executorIds`，需要同事的 `unionId`；向用户询问同事的 `userId`（管理后台可查），然后用上述 userId 到 unionId 方法转换。
14. 执行脚本模板时先 `set -e`；设置 `CONFIG=~/.dingtalk-skills/config`，然后读取：`APP_KEY=$(grep '^DINGTALK_APP_KEY=' "$CONFIG" | cut -d= -f2-)`、`APP_SECRET=$(grep '^DINGTALK_APP_SECRET=' "$CONFIG" | cut -d= -f2-)`、`USER_ID=$(grep '^DINGTALK_MY_USER_ID=' "$CONFIG" | cut -d= -f2-)`。
15. 新版 Token 缓存逻辑：读取 `DINGTALK_ACCESS_TOKEN` 和 `DINGTALK_TOKEN_EXPIRY`，用 `NOW=$(date +%s)` 判断；若缓存存在且 `NOW` 小于过期时间则复用；否则 POST `https://api.dingtalk.com/v1.0/oauth2/accessToken`，使用 `-H 'Content-Type: application/json'` 和 `-d "{\"appKey\":\"$APP_KEY\",\"appSecret\":\"$APP_SECRET\"}"`，提取 `accessToken`；用 `sed -i '/^DINGTALK_ACCESS_TOKEN=/d;/^DINGTALK_TOKEN_EXPIRY=/d' "$CONFIG"` 删除旧值，再写入 `DINGTALK_ACCESS_TOKEN=$TOKEN` 和 `DINGTALK_TOKEN_EXPIRY=$((NOW + 7000))`。
16. unionId 获取逻辑：优先从配置读取 `DINGTALK_MY_OPERATOR_ID`；若未存储，则用旧版 token 调用 `https://oapi.dingtalk.com/topapi/v2/user/get` 从 `USER_ID` 转换，写入配置后再使用。
17. 在脚本模板中追加具体 API 调用，例如创建待办：POST `https://api.dingtalk.com/v1.0/todo/users/${UNION_ID}/tasks?operatorId=${UNION_ID}`，使用 `-H "x-acs-dingtalk-access-token: $TOKEN"`、`-H 'Content-Type: application/json'` 和 `-d "{\"subject\":\"今天完成需求评审\"}"`，将结果存入 `RESULT` 并输出。
18. 创建待办后解析 taskId：`TASK_ID=$(echo "$RESULT" | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)`，输出 `创建成功，taskId=$TASK_ID`。
19. 注意：通过应用 API 创建的待办显示在钉钉「待办」的 Teambition 分类下，不是「个人」分类。
20. 注意：通过 API 创建的任务无法在钉钉 UI 里手动删除，只能通过 API 删除。
21. 确定要做什么之后，从 `references/api.md` 中提取对应章节的完整 API 细节（请求格式、参数说明、返回值示例）。
22. 查阅身份标识与 userId ↔ unionId 转换：`grep -A 28 "^## 身份标识" references/api.md`。
23. 查阅创建待办（含所有可选字段）：`grep -A 47 "^## 1. 创建待办" references/api.md`。
24. 查阅获取待办详情：`grep -A 29 "^## 2. 获取待办详情" references/api.md`。
25. 查阅查询待办列表（含分页）：`grep -A 42 "^## 3. 查询待办列表" references/api.md`。
26. 查阅更新待办：`grep -A 25 "^## 4. 更新待办" references/api.md`。
27. 查阅删除待办：`grep -A 16 "^## 5. 删除待办" references/api.md`。
28. 查阅错误码表：`grep -A 9 "^## 错误码" references/api.md`。
29. 查阅所需应用权限：`grep -A 7 "^## 所需应用权限" references/api.md`。
30. 支持并执行这些待办操作：创建待办（含描述/截止时间/优先级/参与者）、获取详情、查询列表（按完成状态过滤）、更新待办、标记完成、删除待办。

适用边界 · 注意事项

• 没有钉钉开放平台应用及 `DINGTALK_APP_KEY` / `DINGTALK_APP_SECRET` 等凭证时，不适用。
• 期望通过 API 创建的待办显示在钉钉「待办」的「个人」分类时，不适用；它会显示在 Teambition 分类下。
• 期望在钉钉 UI 中手动删除通过 API 创建的任务时，不适用；此类任务只能通过 API 删除。