Dingtalk Document

钉钉知识库和文档管理操作。当用户提到"钉钉文档"、"知识库"、"新建文档"、"查看文档目录"、"读取文档内容"、"写入文档"、"更新文档"、"文档成员"、"dingtalk doc"、"knowledge base"时使用此技能。支持：创建知识库、查询知识库列表、新建文档/文件夹、读取/写入文档正文内容、管理成员...

Security Scan

The skill appears to implement DingTalk document operations as described, but the package metadata omits required credentials and the included helper script persistently stores sensitive tokens/credentials in a local config file — this mismatch and the way secrets are handled merit caution.

Purpose & Capability

The SKILL.md and scripts implement DingTalk document and knowledge-base operations (token fetch, userId↔unionId conversion, CRUD on docs) which align with the skill's description. However the registry metadata declares no required env vars/credentials while the runtime instructions clearly require DINGTALK_APP_KEY, DINGTALK_APP_SECRET, DINGTALK_MY_USER_ID and DINGTALK_MY_OPERATOR_ID (stored in a local config). The omission in metadata is an incoherence.

Instruction Scope

The SKILL.md confines actions to DingTalk API calls and to using the shipped helper script. It tells the agent to read/write a per-user config file (~/.dingtalk-skills/config), fetch tokens, convert IDs, and create temporary /tmp/<task>.sh scripts that it executes. Those steps are within the expected scope for a DingTalk doc skill, but the instructions give the agent the ability to persist credentials and run generated shell scripts — things the user should be aware of.

Install Mechanism

There is no install spec and no downloads; the skill is instruction-first and includes a helper shell script bundled in the skill. No external binaries or network downloads beyond calls to official DingTalk endpoints are introduced by an installer.

Credentials

Although the skill needs standard DingTalk credentials (AppKey/AppSecret and user IDs), these are not declared in the registry's required env vars. The helper script persists AppSecret and access tokens in plaintext under ~/.dingtalk-skills/config and uses them to call the API. Requesting and persistently storing these high-value secrets is proportionate to the functionality, but the metadata omission and plaintext persistent storage are concerning from a transparency and secrets-management perspective.

Persistence & Privilege

The skill does not request platform-wide privileges or set always:true. It writes a per-user config file (~/.dingtalk-skills/config) and caches access tokens there; this is normal for credential caching but means credentials/tokens remain on disk until cleared. It also creates and executes /tmp/<task>.sh scripts for multi-line operations, which will execute shell commands the skill composes.

What to consider before installing

This skill implements DingTalk document operations and includes a helper script that requires your DingTalk AppKey/AppSecret and user IDs. Before installing: 1) Expect to provide DINGTALK_APP_KEY, DINGTALK_APP_SECRET, DINGTALK_MY_USER_ID (and the script may write DINGTALK_MY_OPERATOR_ID) even though the registry metadata doesn't declare them. 2) The helper stores AppSecret and access tokens in plaintext at ~/.dingtalk-skills/config — consider whether you are comfortable with persistent local storage of these secrets. 3) Review scripts/dt_helper.sh yourself (it uses only api.dingtalk.com and oapi.dingtalk.com endpoints) and ensure you trust the skill source. 4) If you proceed, prefer using a dedicated account or sandbox environment, rotate AppSecret/token after testing, and consider restricting the app's scopes to the minimum required (read/write docs only). 5) If you need metadata accuracy/privacy guarantees, ask the publisher to update the registry requirements to list the required credentials and document where/how secrets are stored.

钉钉文档技能

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

dt_helper.sh 位于本 SKILL.md 同级目录的 scripts/dt_helper.sh。

核心概念

• 知识库（Workspace）：文档容器，有 workspaceId 和 rootNodeId
• 节点（Node）：文件或文件夹，type 为 FILE 或 FOLDER
• 文档标识（用于 /v1.0/doc/suites/documents/{id}）：可用 docKey 或 dentryUuid
  • 创建文档响应会返回：docKey、dentryUuid、nodeId
  • 其中 docKey / dentryUuid 可用于读写正文；nodeId 用于删除和文档管理类接口
  • wiki/nodes 返回的 nodeId 实际上是 dentryUuid，可直接用于正文读写
• operatorId：所有接口必须的 unionId 参数，通过 bash scripts/dt_helper.sh --to-unionid 自动转换

工作流程（每次执行前）

1. 先识别本次任务类型 → 例如：列知识库、读文档、写文档、创建文档、成员管理
2. 按本次任务校验所需配置 → 通过 bash scripts/dt_helper.sh --get KEY 读取；仅校验本任务必须项
3. 仅收集缺失配置 → 若缺少某项，一次性询问用户所有缺失值，用 bash scripts/dt_helper.sh --set KEY=VALUE 写入
4. 获取 Token / operatorId → 直接调用 bash scripts/dt_helper.sh，token 获取与缓存细节无需关心
5. 执行操作 → 凡是包含变量替换、管道或多行逻辑的命令，写入 /tmp/<task>.sh 再 bash /tmp/<task>.sh 执行。不要把多行命令直接粘到终端里（终端工具会截断），也不要用 <<'EOF' 语法（heredoc 在工具中同样会被截断导致变量丢失）

按任务校验配置（必须先做）

• 所有任务通用必需：DINGTALK_APP_KEY、DINGTALK_APP_SECRET、DINGTALK_MY_USER_ID
• 涉及任何文档/知识库 API 调用：必须有 DINGTALK_MY_OPERATOR_ID（若缺失，先用 bash scripts/dt_helper.sh --to-unionid 自动转换并写回）
• 创建/读取/写入/删除/成员管理：除上述通用项外，无额外固定配置键；workspaceId/nodeId/docKey 属于任务参数，运行时从用户输入或 API 响应中获取

规则：未通过“本次任务配置校验”前，不得进入 API 调用步骤。

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

所需配置

配置键	必填	说明	如何获取
DINGTALK_APP_KEY	✅	应用 AppKey	钉钉开放平台 → 应用管理 → 凭证信息
DINGTALK_APP_SECRET	✅	应用 AppSecret	同上
DINGTALK_MY_USER_ID	✅	当前用户的企业员工 ID（userId）	管理后台 → 通讯录 → 成员管理 → 点击姓名查看
DINGTALK_MY_OPERATOR_ID	✅	当前用户的 unionId（operatorId）	首次由 bash scripts/dt_helper.sh --to-unionid 自动转换并写入

身份标识说明

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

执行脚本模板

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

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

references/api.md 查阅索引

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

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