dingtalk-todo

Original：🇨🇳 Chinese
Translated

DingTalk Todo Management. Use this skill when the user mentions terms like "DingTalk Todo", "todo task", "create todo", "add todo", "view todo", "complete todo", "mark as complete", "delete todo", "todo list", "my todos", "set deadline", "assign todo", "dingtalk todo", "todo task", "task management". Supported operations include: creating todos (with description/deadline/priority/participants), getting details, querying lists (filtered by completion status), updating todos, marking as complete, deleting todos, and all other todo-related operations.

8installs
Sourcebreath57/dingtalk-skills
Added on

NPX Install

npx skill4agent add breath57/dingtalk-skills dingtalk-todo

Tags

Translated version includes tags in frontmatter
dingtalk-todotask-managementapi-integrationbash-scripttoken-caching

SKILL.md Content (Chinese)

View Translation Comparison →

DingTalk Todo Skill

Responsible for all operations of DingTalk Todo. This document is a Strategy Guide that only includes decision logic and workflows. Complete API request formats can be found in the "references/api.md Index" at the end of the document.

Workflow (Before Each Execution)

  1. Read Configuration → Use a single 
    grep -E
    command to read all required configuration key-value pairs from the configuration file 
    ~/.dingtalk-skills/config
    at once (the configuration file is retained across sessions, no need to ask repeatedly)
  2. Collect Missing Configurations Only → If the configuration file does not exist or is missing certain items, ask the user all missing values at once, do not ask one by one
  3. Persistence → Write the collected values to the 
    ~/.dingtalk-skills/config
    file, no need to ask again in subsequent uses
  4. Retrieve/Reuse Token → Reuse the cache within its validity period (cached for 7000 seconds, approximately 2 hours) to avoid repeated requests; retrieve a new token if a 401 error is encountered
  5. Execute Operation → For any command involving variable substitution, pipes, or multi-line logic, write it to 
    /tmp/<task>.sh
    first and then execute it with 
    bash /tmp/<task>.sh
    . Do not directly paste multi-line commands into the terminal (terminal tools will truncate them), and do not use the 
    <<'EOF'
    syntax (heredoc will also be truncated in tools leading to variable loss)
Credentials are prohibited from being printed in full in the output; only display the first 4 digits + 
****
when confirming

Required Configurations

Configuration KeyDescriptionHow to Obtain
DINGTALK_APP_KEY
App KeyDingTalk Open Platform → Application Management → Credential Information
DINGTALK_APP_SECRET
App SecretSame as above
DINGTALK_MY_USER_ID
Current user's enterprise employee ID (userId)Admin Backend → Address Book → Member Management → Click on the name to view (not phone number, not unionId)
DINGTALK_MY_OPERATOR_ID
Current user's unionIdAutomatically obtained and written by the script via userId conversion for the first time

Identity Identification Description

DingTalk has two types of user IDs, and different APIs use different IDs:
IdentifierDescriptionHow to Obtain
userId
(= 
staffId
)		Internal enterprise employee ID, easiest to obtainAdmin Backend → Address Book → Member Management → Click on the name to view; or call the phone number query API
unionId
Unique across enterprises/applicationsObtained by calling the API to convert from userId
  • The path parameter 
    {unionId}
    and query parameter 
    operatorId
    of the Todo API both use unionId
  • executorIds / participantIds (assigning to colleagues) also use unionId
  • Therefore, prioritize collecting 
    userId
    (easy for users to obtain) in the configuration, and the script will automatically convert it to 
    unionId

userId → unionId Conversion

Requires the old version of access_token (different from the new version):
bash
# 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: 
result.unionid
(without underscore) has a value in the response body, while 
result.union_id
(with underscore) may be empty.

When Creating a Todo for a Colleague

If the user wants to create a todo for a colleague (specify executorIds), the colleague's unionId is required. Ask the user for the colleague's userId (available in the admin backend), then convert it using the method above.

Execution Script Template

bash
#!/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"
⚠️ Todos created via the application API are displayed under the Teambition category in DingTalk's "Todo" section, not the "Personal" category. ⚠️ Tasks created via the API cannot be manually deleted in the DingTalk UI, only via the API.

references/api.md Index

After determining what to do, use the following commands to extract the complete API details (request format, parameter description, return value example) of the corresponding section from 
references/api.md
:
bash
# 身份标识与 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