dingtalk-todo

DingTalk ToDo スキル

DingTalk の ToDo に関するすべての操作を担当します。このファイルは方針ガイドであり、意思決定のロジックとワークフローのみを記載しています。完全な API リクエスト形式については、末尾の「references/api.md 参照インデックス」をご覧ください。

---

ワークフロー（実行のたびに）

1. 設定を読み込む → 1つの grep -E コマンドを使って、設定ファイル ~/.dingtalk-skills/config から必要な設定キーと値を一括で読み込みます（設定ファイルはセッションをまたいで保持されるため、繰り返し尋ねる必要はありません）
2. 不足している設定のみ収集する → 設定ファイルが存在しない、または項目が不足している場合は、不足している値をすべて一度にユーザーに尋ねます。1つずつ尋ねないでください
3. 永続化する → 収集した値を ~/.dingtalk-skills/config ファイルに書き込みます。以後、尋ねる必要はありません
4. トークンを取得／再利用する → 有効期間内はキャッシュを再利用します（キャッシュは 7000 秒、約 2 時間）。重複したリクエストを避け、401 が発生した場合は再取得します
5. 操作を実行する → 変数置換、パイプ、複数行のロジックを含むコマンドは、/tmp/<task>.sh に保存してから bash /tmp/<task>.sh で実行します。複数行のコマンドをターミナルに直接貼り付けないでください（ターミナルツールで切り詰められるため）。また、<<'EOF' 構文も使用しないでください（heredoc もツールで切り詰められ、変数が失われるため）

認証情報を出力に完全な形で表示することは禁止されています。確認時は先頭 4 文字と **** のみを表示してください

必要な設定

設定キー	説明	取得方法
DINGTALK_APP_KEY	アプリの AppKey	DingTalk オープンプラットフォーム → アプリ管理 → 認証情報
DINGTALK_APP_SECRET	アプリの AppSecret	同上
DINGTALK_MY_USER_ID	現在のユーザーの企業内従業員 ID（userId）	管理画面 → アドレス帳 → メンバー管理 → 名前をクリックして確認します（電話番号でも unionId でもありません）
DINGTALK_MY_OPERATOR_ID	現在のユーザーの unionId	初回にスクリプトが userId から自動変換して取得し、書き込みます

ID の説明

DingTalk には2種類のユーザー ID があり、API によって使用する ID が異なります。

ID	説明	取得方法
userId（= staffId）	企業内の従業員 ID。最も簡単に取得できます	管理画面 → アドレス帳 → メンバー管理 → 名前をクリックして確認します。または携帯電話番号検索 API を呼び出します
unionId	企業間／アプリ間で一意	userId を使って API を呼び出し、変換して取得します

• ToDo API のパスパラメーター {unionId} とクエリパラメーター operatorId は、どちらも unionId を使用します
• executorIds / participantIds（同僚の割り当て）にも unionId を使用します
• そのため、設定ではまず userId（ユーザーが取得しやすい）を収集し、スクリプトが自動的に unionId に変換します

userId → unionId の変換

旧版の access_token が必要です（新版とは異なります）。

# 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

⚠️ 注意：レスポンス本文では result.unionid（アンダースコアなし）に値があり、result.union_id（アンダースコアあり）は空の場合があります。

同僚の ToDo を作成する場合

ユーザーが同僚の ToDo を作成する場合（executorIds を指定）、同僚の unionId が必要です。ユーザーに同僚の userId（管理画面で確認できます）を尋ね、上記の方法で変換してください。

実行スクリプトのテンプレート

#!/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"

---

⚠️ アプリ API で作成した ToDo は、DingTalk の「ToDo」にある Teambition カテゴリーに表示され、「個人」カテゴリーには表示されません。 ⚠️ API で作成したタスクは、DingTalk UI から手動で削除できません。削除するには API を使用してください。

references/api.md 参照インデックス

実行する操作を決めたら、以下のコマンドで references/api.md から該当セクションの API の詳細（リクエスト形式、パラメーターの説明、戻り値の例）を抽出してください。

# 身份标识与 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