SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdingtalk-document

dingtalk-document

Office & productivity

View repository

Updated 10-15 17:29

About this skill

DingTalk Docs Skill

Responsible for all operations of the DingTalk knowledge base and documents. This file is thestrategy guide, containing only decision logic and workflow. For the complete API request formats, see "references/api.md lookup index" at the end of this document.

dt_helper.sh Located in this SKILL.md sibling directory's scripts/dt_helper.sh。

Core Concepts

  • Knowledge Base (Workspace): A document container, with workspaceId and rootNodeId
  • Node: A file or folder,type is FILE or FOLDER
  • Document identifier (used for /v1.0/doc/suites/documents/{id}）: Can use docKey or dentryUuid
    • The create document response returns:docKey、dentryUuid、nodeId
    • Where docKey / dentryUuid can be used to read and write the body;nodeId is used for deletion and document management APIs
    • wiki/nodes The returned nodeId is actually dentryUuid, and can be used directly for reading and writing the body
  • operatorId: The unionId parameter required by all APIs, automatically converted via bash scripts/dt_helper.sh --to-unionid automatically converted

Workflow (before each execution)

  1. First identify the type of this task → For example: list knowledge bases, read document, write document, create document, member management
  2. Validate the required configuration for this task → Read via bash scripts/dt_helper.sh --get KEY ; only validate the required items for this task
  3. Collect only missing configuration → If something is missing,ask the user in one gofor all missing values, and write them with bash scripts/dt_helper.sh --set KEY=VALUE and write
  4. Get Token / operatorId → Call bash scripts/dt_helper.shdirectly; no need to care about token acquisition and caching details
  5. Execute the operation → For any command containing variable substitution, pipes, or multi-line logic, write to /tmp/<task>.sh then bash /tmp/<task>.sh execute. Do not paste multi-line commands directly into the terminal (the terminal tool will truncate them), and do not use <<'EOF' syntax (heredoc will also be truncated in the tool, causing variables to be lost)

Validate configuration by task (must be done first)

  • Required for all tasks：DINGTALK_APP_KEY、DINGTALK_APP_SECRET、DINGTALK_MY_USER_ID
  • Involves any document/knowledge base API call: Must have DINGTALK_MY_OPERATOR_ID(if missing, first use bash scripts/dt_helper.sh --to-unionid to automatically convert and write back)
  • Create/read/write/delete/member management: Apart from the above common items, there are no additional fixed configuration keys;workspaceId/nodeId/docKey are task parameters, obtained at runtime from user input or API responses

Rule: Before passing the "configuration validation for this task", do not proceed to the API call step.

Credentials must not be printed in full in the output; when confirming, show only the first 4 characters + ****

Required Configuration

Configuration Key Required Description How to obtain
DINGTALK_APP_KEY ✅ App AppKey DingTalk Open Platform → App Management → Credential Information
DINGTALK_APP_SECRET ✅ App AppSecret Same as above
DINGTALK_MY_USER_ID ✅ The current user's enterprise employee ID (userId) Admin console → Contacts → Member Management → Click the name to view
DINGTALK_MY_OPERATOR_ID ✅ The current user's unionId (operatorId) First time by bash scripts/dt_helper.sh --to-unionid automatically converted and written

Identity Identifier Description

Identifier Description
userId（= staffId） Enterprise internal employee ID, can be viewed via Admin console -> Contacts -> Member Management -> Click the name
unionId Cross-enterprise/cross-application unique identifier, can be obtained via bash scripts/dt_helper.sh --to-unionid <userid> obtain

Execution Script Template

#!/bin/bash
set -e
HELPER="./scripts/dt_helper.sh"
NEW_TOKEN=$(bash "$HELPER" --token)
OPERATOR_ID=$(bash "$HELPER" --get DINGTALK_MY_OPERATOR_ID)

# 在此追加具体 API 调用，例如查询知识库列表：
WORKSPACES=$(curl -s -X GET "https://api.dingtalk.com/v2.0/wiki/workspaces?operatorId=${OPERATOR_ID}&maxResults=20" \
  -H "x-acs-dingtalk-access-token: $NEW_TOKEN")
echo "知识库列表: $WORKSPACES"

Token Invalidation Handling: dt_helper only caches by time and cannot detect that a token has been revoked early. If the API returns 401 (invalid/expired token), use --nocache to skip the cache and force re-acquisition:

NEW_TOKEN=$(bash "$HELPER" --token --nocache)

references/api.md Lookup Index

After determining what to do, use the following command to extract the complete API details of the corresponding section from references/api.md (request format, parameter descriptions, return value examples):

grep -A 30 "^## 1. 查询知识库列表" references/api.md
grep -A 10 "^## 2. 查询知识库信息" references/api.md
grep -A 35 "^## 3. 查询节点列表" references/api.md
grep -A 10 "^## 4. 查询单个节点" references/api.md
grep -A 15 "^## 5. 通过 URL 查询节点" references/api.md
grep -A 28 "^## 6. 创建文档" references/api.md
grep -A 10 "^## 7. 删除文档" references/api.md
grep -A 30 "^## 8. 读取文档内容" references/api.md
grep -A 15 "^## 9. 覆盖写入文档内容" references/api.md
grep -A 12 "^## 10. 追加文本到段落" references/api.md
grep -A 18 "^## 11. 添加文档成员" references/api.md
grep -A 12 "^## 12. 更新文档成员权限" references/api.md
grep -A 10 "^## 13. 移除文档成员" references/api.md
grep -A 10 "^## 错误码" references/api.md
grep -A 10 "^## 所需应用权限" references/api.md