dingtalk-todo

DingTalk Todo Skill

Responsible for all operations of DingTalk Todo. This file isStrategy Guide, containing only decision logic and workflows. For complete API request formats, see "references/api.md Reference Index" at the end of this document.

---

Workflow (before each execution)

1. Read configuration → Use one grep -E command to read the configuration file in one go~/.dingtalk-skills/config, all required configuration key values (the configuration file persists across sessions, no need to ask repeatedly)
2. Collect only missing configuration → If the configuration file does not exist or is missing an item,ask the user oncefor all missing values, do not ask one by one
3. Persist → Write the collected values into the ~/.dingtalk-skills/config file, no need to ask again afterward
4. Obtain/Reuse Token → Reuse the cache within its validity period (cache for 7000 seconds, about 2 hours) to avoid repeated requests; re-obtain on 401
5. Execute operation → For any command containing variable substitution, pipes, or multi-line logic,/tmp/<task>.sh then bash /tmp/<task>.sh execute. Do not paste multi-line commands directly into the terminal (the terminal tool will truncate them), and do not use <<'EOF' syntax (heredoc will also be truncated in the tool, causing variable loss)

Credentials must not be printed in full in the output; when confirming, show only the first 4 characters + ****

Required configuration

Configuration key	Description	How to obtain
DINGTALK_APP_KEY	Application AppKey	DingTalk Open Platform → Application Management → Credential Information
DINGTALK_APP_SECRET	Application AppSecret	Same as above
DINGTALK_MY_USER_ID	The current user's enterprise employee ID (userId)	Admin Console → Contacts → Member Management → Click the name to view (not a phone number, not a unionId)
DINGTALK_MY_OPERATOR_ID	The current user's unionId	On first use, automatically obtained and written by the script via userId conversion

Identity Identifier Description

DingTalk has two types of user IDs, and different APIs use different IDs:

Identifier	Description	How to obtain
userId（= staffId）	Enterprise internal employee ID,easiest to obtain	Admin Console → Contacts → Member Management → Click the name to view; or call the phone number query API
unionId	Unique across enterprises/applications	Obtained via userId by calling the API conversion

• The Todo API's path parameter {unionId} and query parameter operatorId both use unionId
• executorIds / participantIds (assigning colleagues) also use unionId
• Therefore, in the configuration, prioritize collecting userId(easy for users to obtain), and the script will automatically convert it to unionId

userId → unionId conversion

Requires the old version access_token (different from the new version):

# 1. 获取旧版 token
OLD_TOKEN=$(curl -s "https://oapi.dingtalk.com/gettoken?appkey=${APP_KEY}&appsecret=${APP_SECRET}" | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)

# 2. userId → unionId
UNION_ID=$(curl -s -X POST "https://oapi.dingtalk.com/topapi/v2/user/get?access_token=${OLD_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{\"userid\":\"${USER_ID}\"}" | grep -o '"unionid":"[^"]*"' | cut -d'"' -f4)

# 3. 写入配置文件
echo "DINGTALK_MY_OPERATOR_ID=$UNION_ID" >> ~/.dingtalk-skills/config

⚠️ Note: In the response body, result.unionid(without underscore) has a value,result.union_id(with underscore) may be empty.

When creating a to-do for a colleague

If the user wants to create a to-do for a colleague (specifying executorIds), the colleague's unionIdis required. Ask the user for the colleague's userId(available in the admin console), then convert it using the method above.

Execution script template

#!/bin/bash
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-)

# 新版 Token 缓存（用于待办 API）
CACHED_TOKEN=$(grep '^DINGTALK_ACCESS_TOKEN=' "$CONFIG" 2>/dev/null | cut -d= -f2-)
TOKEN_EXPIRY=$(grep '^DINGTALK_TOKEN_EXPIRY=' "$CONFIG" 2>/dev/null | cut -d= -f2-)
NOW=$(date +%s)
if [ -n "$CACHED_TOKEN" ] && [ -n "$TOKEN_EXPIRY" ] && [ "$NOW" -lt "$TOKEN_EXPIRY" ]; then
  TOKEN=$CACHED_TOKEN
else
  RESP=$(curl -s -X POST https://api.dingtalk.com/v1.0/oauth2/accessToken \
    -H 'Content-Type: application/json' \
    -d "{\"appKey\":\"$APP_KEY\",\"appSecret\":\"$APP_SECRET\"}")
  TOKEN=$(echo "$RESP" | grep -o '"accessToken":"[^"]*"' | cut -d'"' -f4)
  sed -i '/^DINGTALK_ACCESS_TOKEN=/d;/^DINGTALK_TOKEN_EXPIRY=/d' "$CONFIG"
  echo "DINGTALK_ACCESS_TOKEN=$TOKEN" >> "$CONFIG"
  echo "DINGTALK_TOKEN_EXPIRY=$((NOW + 7000))" >> "$CONFIG"
fi

# unionId：优先从配置读取，未存储时自动从 userId 转换并写入
UNION_ID=$(grep '^DINGTALK_MY_OPERATOR_ID=' "$CONFIG" 2>/dev/null | cut -d= -f2-)
if [ -z "$UNION_ID" ]; then
  OLD_TOKEN=$(curl -s "https://oapi.dingtalk.com/gettoken?appkey=${APP_KEY}&appsecret=${APP_SECRET}" | grep -o '"access_token":"[^"]*"' | cut -d'"' -f4)
  UNION_ID=$(curl -s -X POST "https://oapi.dingtalk.com/topapi/v2/user/get?access_token=${OLD_TOKEN}" \
    -H 'Content-Type: application/json' \
    -d "{\"userid\":\"${USER_ID}\"}" | grep -o '"unionid":"[^"]*"' | cut -d'"' -f4)
  echo "DINGTALK_MY_OPERATOR_ID=$UNION_ID" >> "$CONFIG"
fi

# 在此追加具体 API 调用，例如创建待办：
RESULT=$(curl -s -X 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\":\"今天完成需求评审\"}")
echo "$RESULT"
TASK_ID=$(echo "$RESULT" | grep -o '"id":"[^"]*"' | head -1 | cut -d'"' -f4)
echo "创建成功，taskId=$TASK_ID"

---

⚠️ To-dos created via the app API appear under the Teambition categoryin DingTalk "To-dos", not under the "Personal" category. ⚠️ Tasks created via the API cannot be manually deleted in the DingTalk UI; they can only be deleted via the API.

references/api.md lookup index

After deciding what to do, use the following command to extract the complete API details (request format, parameter descriptions, return value examples) for the corresponding section from references/api.md :

# 身份标识与 userId ↔ unionId 转换（28 行）
grep -A 28 "^## 身份标识" references/api.md

# 创建待办（含所有可选字段）（47 行）
grep -A 47 "^## 1. 创建待办" references/api.md

# 获取待办详情（29 行）
grep -A 29 "^## 2. 获取待办详情" references/api.md

# 查询待办列表（含分页）（42 行）
grep -A 42 "^## 3. 查询待办列表" references/api.md

# 更新待办（25 行）
grep -A 25 "^## 4. 更新待办" references/api.md

# 删除待办（16 行）
grep -A 16 "^## 5. 删除待办" references/api.md

# 错误码表（9 行）
grep -A 9 "^## 错误码" references/api.md

# 所需应用权限（7 行）
grep -A 7 "^## 所需应用权限" references/api.md