DingTalk Address Book Skill

dt_helper.sh

is located in

scripts/dt_helper.sh

at the same level as this

SKILL.md

.

Workflow (Before Each Execution)

1. First identify the task type → e.g., search user, check user details, search department, list department members, check department path, count employee number
2. Validate required configurations for the task → Read via

   bash scripts/dt_helper.sh --get KEY

   ; only validate the necessary items for this task
3. Collect only missing configurations → If any item is missing, ask the user for all missing values at once, and write them using

   bash scripts/dt_helper.sh --set KEY=VALUE

4. Obtain Token → Directly call

   bash scripts/dt_helper.sh

5. Execute the operation → For complex tasks, create a temporary file first then execute; for simple tasks, execute directly; heredoc is prohibited

Configuration Validation by Task (Must Be Done First)

• Required for all tasks:

  DINGTALK_APP_KEY

  ,

  DINGTALK_APP_SECRET

• Tasks that require "starting from the current operator" or "directly reading the operator's own identity information": Must have

  DINGTALK_MY_USER_ID

Rule: Do not proceed to the API call step until the "task configuration validation" is passed.

Credentials are prohibited from being printed in full. Only display the first 4 characters +

****

during confirmation.

Required Configurations

DINGTALK_APP_KEY

DINGTALK_APP_SECRET

DINGTALK_MY_USER_ID

Identifier Description

userId

staffId

unionId

bash scripts/dt_helper.sh --to-unionid <userid>

Execution Script Template

#!/bin/bash
set -e
HELPER="./scripts/dt_helper.sh"
NEW_TOKEN=$(bash "$HELPER" --token)       # api.dingtalk.com 接口用
OLD_TOKEN=$(bash "$HELPER" --old-token)   # oapi.dingtalk.com 接口用
# USER_ID=$(bash "$HELPER" --get DINGTALK_MY_USER_ID)  # 以当前操作用户为起点时启用

# 在此追加具体 API 调用，例如按姓名搜索用户并获取详情：
KEYWORD="张三"
SEARCH=$(curl -s -X POST https://api.dingtalk.com/v1.0/contact/users/search \
  -H "x-acs-dingtalk-access-token: $NEW_TOKEN" \
  -H 'Content-Type: application/json' \
  -d "{\"queryWord\":\"$KEYWORD\",\"offset\":0,\"size\":20}")
echo "搜索结果: $SEARCH"

TARGET_UID=$(echo "$SEARCH" | grep -o '"list":\["[^"]*"' | grep -o '"[^"]*"$' | tr -d '"')
DETAIL=$(curl -s -X POST "https://oapi.dingtalk.com/topapi/v2/user/get?access_token=${OLD_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d "{\"userid\":\"$TARGET_UID\",\"language\":\"zh_CN\"}")
echo "用户详情: $DETAIL"

Token Invalid Handling: dt_helper only caches by time and cannot detect if the token is revoked in advance. If the API returns

errcode 40001

/

40014

(token invalid/expired), use

--nocache

to skip the cache and force a re-acquisition:

bash

OLD_TOKEN=$(bash "$HELPER" --old-token --nocache)  # 强制重新获取旧版 token
NEW_TOKEN=$(bash "$HELPER" --token --nocache)       # 强制重新获取新版 token

references/api.md Index

references/api.md

grep -A 30 "^## 1. 按关键词搜索用户" references/api.md
grep -A 50 "^## 2. 获取用户完整详情" references/api.md
grep -A 20 "^## 3. unionId → userId 转换" references/api.md
grep -A 18 "^## 4. 企业员工总人数" references/api.md
grep -A 25 "^## 5. 按关键词搜索部门" references/api.md
grep -A 25 "^## 6. 获取子部门列表" references/api.md
grep -A 20 "^## 7. 获取子部门 ID 列表" references/api.md
grep -A 25 "^## 8. 获取部门详情" references/api.md
grep -A 40 "^## 9. 获取部门成员完整列表" references/api.md
grep -A 18 "^## 10. 获取部门成员 userId 列表" references/api.md
grep -A 20 "^## 11. 获取用户所在部门路径" references/api.md
grep -A 12 "^## 错误码" references/api.md
grep -A 6 "^## 所需应用权限" references/api.md