Dingtalk Contact

钉钉通讯录与联系人查询。当用户提到"钉钉通讯录"、"查找员工"、"搜索用户"、"查用户信息"、"获取用户详情"、"用户手机号"、"员工姓名"、"员工工号"、"查部门"、"搜索部门"、"部门成员"、"部门列表"、"部门详情"、"子部门"、"父部门"、"部门路径"、"员工总数"、"通讯录搜索"、"userId 转 u...

Security Scan

The skill legitimately implements DingTalk contact queries, but its metadata omits the credentials it actually requires and the bundled helper will persist secrets to disk and execute shell scripts—this mismatch and persistence are concerning and worth explicit attention.

Purpose & Capability

The skill's name/description match the included scripts and API references (search users/departments, get user details, unionId/userId conversion). However, the registry metadata declares no required environment variables or primary credential, while SKILL.md and scripts clearly require and manage DINGTALK_APP_KEY and DINGTALK_APP_SECRET (and optionally DINGTALK_MY_USER_ID). That omission is an incoherence: a contact-directory skill would reasonably need app credentials, but the metadata should have declared them.

Instruction Scope

SKILL.md instructs the agent to read/write a persistent config file (default ~/.dingtalk-skills/config) via scripts/dt_helper.sh, to cache tokens, and to write multi-line task scripts to /tmp/<task>.sh and execute them. Those actions go beyond simple read-only API calls: the skill will persist secrets and run generated shell scripts. While these are functionally required for token management, they expand the runtime footprint and create opportunities for misuse if commands are constructed incorrectly or if the config is exposed.

Install Mechanism

There is no install spec (instruction-only plus one bundled helper script). No external downloads or package installs are performed. The bundled shell script is included in the skill package, so nothing is pulled from arbitrary URLs at install time.

Credentials

Although registry metadata lists no required env vars, SKILL.md and scripts expect and manage DINGTALK_APP_KEY and DINGTALK_APP_SECRET (required) and may use DINGTALK_MY_USER_ID and DINGTALK_CONFIG. The script also writes access tokens and secrets into a plaintext config file. Asking for app key/secret is proportionate to the stated purpose, but failing to declare them in metadata and persisting them unencrypted is a notable mismatch and risk.

Persistence & Privilege

The skill persistently stores credentials and tokens under a per-user config file (~/.dingtalk-skills/config) and caches tokens. always:false and no cross-skill modification are fine. The persistence behavior is expected for token caching, but users should be aware credentials are stored on disk in clear form (the script attempts to mask output but does not encrypt the file). The skill also writes temporary scripts to /tmp and executes them.

What to consider before installing

This skill does what it says (DingTalk contact lookups) but has some operational and metadata mismatches you should consider before installing: - The package metadata declares no required credentials, but the skill requires DINGTALK_APP_KEY and DINGTALK_APP_SECRET (and may ask for DINGTALK_MY_USER_ID). Expect the skill to prompt you for these and to persist them. - The helper (scripts/dt_helper.sh) stores AppKey/AppSecret and cached tokens in a plaintext file by default at ~/.dingtalk-skills/config. If you install, review and protect that file (filesystem permissions) or override DINGTALK_CONFIG to a secure location. - The skill writes multi-line task scripts to /tmp and executes them (bash /tmp/<task>.sh). That is how it runs the curl calls, but it means the agent will be creating and executing shell scripts—avoid giving it elevated privileges and consider running in an isolated account or environment. - Source/homepage is unknown; if you rely on this in production, request provenance or a signed source. Consider creating an application with the minimal DingTalk scopes and rotate/revoke AppSecret if you stop using the skill. If you want to proceed: (1) verify the script content yourself, (2) provide least-privilege credentials (read-only contact scope), (3) place the config file in a secure location and set restrictive permissions, and (4) consider running the skill in a sandboxed agent session until you are comfortable.

钉钉通讯录技能

负责钉钉通讯录的所有查询操作。本文件为策略指南，仅包含决策逻辑和工作流程。完整 API 请求格式见文末「references/api.md 查阅索引」。

工作流程（每次执行前）

1. 读取/写入配置 → 通过 scripts/dt_helper.sh 管理，配置跨会话保留，无需重复询问
2. 仅收集缺失配置 → 若缺少某项，一次性询问用户所有缺失的值，用 bash scripts/dt_helper.sh --set KEY=VALUE 写入
3. 获取 Token → 直接调用 dt_helper.sh 即可，token 如何获取/缓存无需关注
4. 执行操作 → 凡是包含变量替换、管道或多行逻辑的命令，写入 /tmp/<task>.sh 再 bash /tmp/<task>.sh 执行。不要把多行命令直接粘到终端里（终端工具会截断），也不要用 <<'EOF' 语法（heredoc 在工具中同样会被截断导致变量丢失）

凭证禁止在输出中完整打印，确认时仅显示前 4 位 + ****

所需配置

配置键	必填	说明	如何获取
DINGTALK_APP_KEY	✅	应用 AppKey	钉钉开放平台 → 应用管理 → 凭证信息
DINGTALK_APP_SECRET	✅	应用 AppSecret	同上
DINGTALK_MY_USER_ID	❌	当前操作用户的 userId（即运行此技能的人自己），仅在需要以自身为起点查询时才需要	管理后台 → 通讯录 → 成员管理 → 点击姓名查看

身份标识说明

标识	说明
userId（= staffId）	企业内部员工 ID，可通过通过管理后台 -> 通讯录 -> 成员管理 -> 点击姓名查看
unionId	跨企业/跨应用唯一标识，可通过bash scripts/dt_helper.sh --to-unionid <userid> 获取

执行脚本模板

#!/bin/bash
set -e
HELPER="<THE_SKILL_MD_PATH>/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 失效处理：dt_helper 仅按时间缓存，无法感知 token 被提前吊销。若 API 返回 errcode 40001/40014（token 无效/过期），用 --nocache 跳过缓存强制重新获取：

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

references/api.md 查阅索引

确定好要做什么之后，用以下命令从 references/api.md 中提取对应章节的完整 API 细节（请求格式、参数说明、返回值示例）：

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