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.

6installs

Sourcebreath57/dingtalk-skills

Added on2026-03-26

NPX Install

npx skill4agent add breath57/dingtalk-skills dingtalk-todo

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)

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)
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
Persistence → Write the collected values to the
```
~/.dingtalk-skills/config
```
file, no need to ask again in subsequent uses
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
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 Key	Description	How to Obtain
`DINGTALK_APP_KEY`	App Key	DingTalk Open Platform → Application Management → Credential Information
`DINGTALK_APP_SECRET`	App Secret	Same 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 unionId	Automatically 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:

Identifier	Description	How to Obtain
`userId` (= `staffId` )	Internal enterprise employee ID, easiest to obtain	Admin Backend → Address Book → Member Management → Click on the name to view; or call the phone number query API
`unionId`	Unique across enterprises/applications	Obtained 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

dingtalk-todo

NPX Install

Tags

SKILL.md Content (Chinese)

DingTalk Todo Skill

Workflow (Before Each Execution)

Required Configurations

Identity Identification Description

userId → unionId Conversion

When Creating a Todo for a Colleague

Execution Script Template

references/api.md Index