dingtalk-cli

当用户提到钉钉知识库、钉钉文档、读取/写入文档、知识库目录、文档成员、`.axls` 表格、workbook、dingtalk doc、wiki workspace 时使用。通过本地 `dingtalk-cli` 命令调用钉钉开放平台 API，适合 agent 直接执行。

Security Scan

The skill's instructions expect DingTalk credentials and a local config file (and tell the agent to run a pip-installed CLI), but the package metadata declares no required credentials or config paths — that mismatch and the implied installation of external code are reasons for caution.

Purpose & Capability

The SKILL.md clearly intends to drive a local dingtalk-cli binary (read/write docs, workbooks, members). That purpose is coherent with the name/description. However the instructions require DingTalk credentials (app key/secret and operator id) and a config file at ~/.dingtalk-cli/config.json, but the skill metadata declares no required environment variables or config paths — an inconsistency between what the skill needs at runtime and what is advertised.

Instruction Scope

Runtime instructions tell the agent to run local CLI commands that will read/write documents and to save credentials via `dingtalk-cli auth setup` which writes to ~/.dingtalk-cli/config.json (or use env vars). The actions are within the described purpose, but they include storing and reading sensitive credentials from the user's home directory and rely on a separately-installed binary; the SKILL.md does not describe how long-lived tokens are handled or file permissions, which is relevant for security.

Install Mechanism

There is no formal install spec in the registry (skill is instruction-only). SKILL.md recommends `pip install dingtalk-cli`. Installing a third-party pip package is a moderate-risk action (it fetches and executes remote code). The skill metadata does not provide a vetted source/URL or checksum; users should verify the PyPI package and its source before installing.

Credentials

The instructions reference sensitive environment variables (DINGTALK_APP_KEY, DINGTALK_APP_SECRET, DINGTALK_OPERATOR_ID) and require a real operator identity for write operations. Those variables are appropriate for the stated purpose, but the skill metadata lists no required env vars or primary credential; this omission reduces transparency about what secrets are needed and should raise caution.

Persistence & Privilege

The CLI stores configuration under ~/.dingtalk-cli/config.json (persistence limited to the user's home). always is false and the skill does not request system-wide privileges. Still, storing credentials locally creates a persistent credential surface the agent or CLI can later use; users should be aware of where credentials are written and protect that file (permissions, scope-limited credentials).

What to consider before installing

This skill's instructions require DingTalk app credentials and will write them to ~/.dingtalk-cli/config.json or read them from environment variables, but the registry entry does not declare those requirements — that's an inconsistency you should resolve before installing. Before using: (1) verify the dingtalk-cli package source (PyPI project page, GitHub repo) and review its code or install in an isolated environment; (2) prefer providing a scoped service account or short-lived credentials, not a full human account; (3) check and restrict ~/.dingtalk-cli/config.json file permissions; (4) if you need metadata declared for audits, ask the publisher to list required env vars/config paths and justify them. If you cannot verify the underlying pip package, treat this skill as higher-risk.

dingtalk-cli 是面向 agent 的钉钉文档 CLI，覆盖：

• 知识库列表与详情
• 节点查询、URL 反查
• 文档创建、正文读取、Markdown 覆盖写入、删除
• .axls 钉钉表格的 workbook/sheet/range 读取
• 文档成员添加、更新、移除

安装

pip install dingtalk-cli

如需从源码开发安装：

pip install -e .

启动前配置

优先使用命令保存配置：

dingtalk-cli auth setup \
  --app-key <APP_KEY> \
  --app-secret <APP_SECRET> \
  --operator-union-id <UNION_ID>

如果只有 userId：

dingtalk-cli auth setup \
  --app-key <APP_KEY> \
  --app-secret <APP_SECRET> \
  --operator-user-id <USER_ID>

配置会写到 ~/.dingtalk-cli/config.json。也可用环境变量覆盖：

• DINGTALK_APP_KEY
• DINGTALK_APP_SECRET
• DINGTALK_OPERATOR_ID
• DINGTALK_CLI_CONFIG_DIR

注意：

• 写操作必须带真实用户身份 operatorId，且应为 unionId
• 输出中不会打印完整凭证，只显示脱敏值

常用命令

# 看知识库
dingtalk-cli workspace list --all

# 用 URL 反查节点
dingtalk-cli node resolve-url "https://alidocs.dingtalk.com/i/nodes/xxx"

# 读取文档正文
dingtalk-cli doc read --url "https://alidocs.dingtalk.com/i/nodes/xxx"

# 覆盖写入文档
dingtalk-cli doc overwrite --doc-key <DOC_KEY> --content-file /abs/path/content.md --yes

# 若立即删除刚创建的文档，优先使用 create 返回的 workspace_id + node_id
dingtalk-cli doc delete --workspace-id <WORKSPACE_ID> --node-id <NODE_ID> --yes

# 读取 .axls 表格
dingtalk-cli workbook read --node-id <NODE_ID> --range A1:Z80

# 添加成员
dingtalk-cli member add --node-id <NODE_ID> --member-id <USER_ID> --role editor

Agent 使用约定

• 优先使用 --json
• 对破坏性命令显式传 --yes
• 读取普通文档用 doc
• 读取 .axls 用 workbook
• 若 doc read 返回“目标节点是 .axls”，不要重试同一命令，直接切到 workbook
• 对创建命令返回的结果，立即读写时优先使用 doc_key
• 对创建后立即删除的场景，优先使用返回的 workspace_id + node_id

错误提示

• MissingoperatorId：未配置 operator unionId
• paramError：把 userId 当成 unionId 传了
• Forbidden.AccessDenied.AccessTokenPermissionDenied：应用权限不够
• Target document should be doc.：目标不是普通文档，通常应改走 workbook