通过钉钉文档官方 MCP Server 全面操作云端文档。
始终使用用户输入的语言进行回复。 如果用户用英文提问，则全程用英文回复；如果用户用中文，则全程用中文回复。无法判断时默认使用中文。
读
写
管理
不负责：
钉钉文档 MCP Server 必须已配置到当前 Agent 的 MCP 设置中，服务名称为 dingtalk-doc。
如果 MCP 工具不可用，先走初始化流程，再执行任何文档操作。
> 请打开以下链接，使用钉钉账号登录后，点击页面上的【开通服务】按钮：
> https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail
dingtalk-doc 为服务名，必须为 ASCII）：
方案 A — Claude Code（优先尝试，运行命令看是否成功）：
```bash
claude mcp add --transport http --scope user dingtalk-doc "<用户提供的 URL>"
```
成功则跳到步骤 5。
方案 B — 写入配置文件（通用方案，大多数 Agent 均可用）：
检测当前环境存在哪些配置文件，找到第一个匹配项写入：
| Agent | 配置文件（全局） | 配置文件（项目级） | mcpServers 键名 |
|-------|---------------|----------------|-----------------|
| Cursor | ~/.cursor/mcp.json | .cursor/mcp.json | mcpServers |
| VS Code Copilot | ~/Library/Application Support/Code/User/mcp.json（Mac）%APPDATA%\Code\User\mcp.json（Win） | .vscode/mcp.json | servers |
| Roo Code | — | .roo/mcp.json | mcpServers |
| Gemini CLI | ~/.gemini/settings.json | — | mcpServers |
| OpenAI Codex | ~/.codex/config.json | — | mcpServers |
向目标文件追加（若文件已有 mcpServers/servers，只添加新条目，不覆盖原有内容）：
```json
{
"mcpServers": {
"dingtalk-doc": {
"type": "http",
"url": "<用户提供的 URL>"
}
}
}
```
> VS Code Copilot 的 .vscode/mcp.json 使用 "servers" 而非 "mcpServers"，写入时注意区分。
成功写入则跳到步骤 5。
方案 C — 手动兜底（方案 A/B 均不适用时）：
向用户展示以下信息，请其参照所用 Agent 的文档手动添加 MCP 服务，完成后回来继续：
```
传输类型：StreamableHttp（HTTP）
服务名称：dingtalk-doc
URL：<用户提供的 URL>
```
用户手动配置完成后，本 Skill 只需确认 MCP 工具可用即可继续。
> URL 中含有个人 API Key，写入配置后不要在回复中重复显示完整 URL。
> 请在浏览器中打开你常用的钉钉知识库，把地址栏的 URL 粘贴给我（格式类似 https://alidocs.dingtalk.com/i/spaces/xxxxx/overview）。
> 如果暂时不设默认知识库，可以跳过，后续每次操作时再指定。
references/dingtalk.config：
```
DINGTALK_DEFAULT_WORKSPACE_URL=<用户提供的知识库 URL>
```
此文件已被 .gitignore 排除，不会进入版本控制。无需重启，下次操作时直接读取生效。
references/dingtalk.config 中的 DINGTALK_DEFAULT_WORKSPACE_URL；② 若文件不存在或值为空，检查环境变量 $DINGTALK_DEFAULT_WORKSPACE_URL（兼容已有 Claude Code 配置）；③ 两者均无则询问用户
get_document_info 传入该 URL 解析出 nodeId，再用 nodeId 调用 list_nodes 或作为 parentNodeId
当用户说"更换默认知识库"、"修改知识库地址"等时：
references/dingtalk.config：
```
DINGTALK_DEFAULT_WORKSPACE_URL=<新的知识库 URL>
```
references/dingtalk.config 保存知识库 URL，已被 .gitignore 排除，不会提交到版本控制
references/dingtalk.config（或环境变量 $DINGTALK_DEFAULT_WORKSPACE_URL）获取默认知识库 URL，调用 get_document_info 解析出 nodeId；否则调用 search_documents 或 list_nodes 定位目标，让用户确认后再操作
需要确认的操作（所有会写入或修改云端数据的操作）：
create_document、update_document、create_folder、create_file、delete_document、rename_document、move_document、copy_document、insert_document_block、update_document_block、delete_document_block、文件上传（get_file_upload_info + commit_uploaded_file）、submit_export_job、add_permission、update_permission
无需确认的操作（只读）：
search_documents、list_nodes、get_document_info、get_document_content、list_document_blocks、list_permission、query_export_job、download_file、download_doc_attachment
确认摘要格式（根据操作类型调整）：
即将执行以下操作，请确认：
操作：<创建 / 更新（覆盖）/ 更新（追加）/ 删除 / 重命名 / 移动 / 复制 / 创建文件夹>
目标：<文档标题或文件夹名>
位置：<知识库名或文件夹路径>
说明：<一句话描述本次变更，例如"将以本地文件 xxx.md 的内容覆盖云端文档全文">
确认请回复「是」或「确认」，取消请回复「否」或「取消」。
收到取消时：停止操作，不重试，告知用户已取消。
详见 references/mcp-tools.md。常用映射如下：
| 用户意图 | MCP 工具 |
|---------|---------|
| 推送/创建文档（含 markdown 内容） | create_document |
| 拉取云端文档内容到本地 | get_document_content |
| 覆盖或追加文档内容 | update_document |
| 精确块级编辑（段落/标题/表格等） | list_document_blocks → insert/update/delete_document_block |
| 列出知识库/文件夹下的文档 | list_nodes |
| 按关键词搜索文档 | search_documents |
| 获取文档元信息（标题、类型等） | get_document_info |
| 下载钉盘文件 | download_file |
| 下载文档内嵌附件 | download_doc_attachment |
| 导出文档为 PDF/Word | submit_export_job → query_export_job（轮询至完成）|
| 创建文件夹 | create_folder |
| 删除文档节点 | delete_document |
| 重命名节点 | rename_document |
| 移动节点到其他文件夹 | move_document |
| 复制节点到其他文件夹 | copy_document |
| 查看节点成员权限 | list_permission |
| 添加/修改节点成员权限 | add_permission / update_permission |
search_documents 或 list_nodes 找到目标，让用户确认后再操作
> 请访问钉钉开发者入门文档，确认你已在所在组织中开通了开发者权限：
> https://open.dingtalk.com/document/dingstart/dingtalk-developer
>
> 开通步骤简述：登录钉钉开放平台 → 选择对应组织 → 完成开发者认证/开通。完成后重新尝试操作。
update_document 和 create_document 仅支持 adoc（文字类型） 文档，不支持表格、演示、脑图等
create_document 和 update_document 的 markdown 参数上限均为 10,000 字符；超出会报 invalidRequest.inputArgs.invalid 错误。推送前应先估算内容字符数，超过 9,500 字符（留余量）时走大文档推送策略（见下文）
delete_document 是移入回收站，不是永久删除，30 天内可从回收站恢复
list_nodes 只返回直接子节点，不递归。需要深层列表时需要多次调用
submit_export_job 返回 jobId 后需轮询 query_export_job 直到状态完成，再将下载链接告知用户；轮询间隔建议 1-2 秒
create_document 推送的 `mermaid 代码块会被解析为普通代码块，而非钉钉原生文本绘图块。钉钉的文本绘图是私有块类型，API 层未暴露，无法通过 MCP 创建或转换。推送前告知用户此限制，建议推送后在钉钉编辑器中手动将代码块转换为文本绘图
用户可能在对话中直接上传 markdown 文件并要求推送到钉钉。
create_document
当需要将本地 markdown 文件推送为钉钉在线文档（adoc）时，推送前先估算内容字符数。超过 9,500 字符 时，单次 create_document 必然失败，需主动告知用户并让其选择方案：
## / ### 标题边界将内容切分为若干段，每段 ≤ 9,500 字符，避免在表格中间切断
create_document 写入第 1 段（含标题）
update_document（append 模式）追加后续各段，每段单独一次调用
适合场景：用户需要在钉钉在线编辑、评论、协作，或希望文档格式被渲染
走三步文件上传流程：get_file_upload_info → HTTP PUT → commit_uploaded_file
适合场景：只需存档或分享下载，不需要在线编辑；操作更简单，文件完整保留原格式
向用户说明两个方案后，推荐如下：
> 如果你需要在钉钉里直接编辑或与同事协作，推荐方案 A（分段推送）；如果只是存档或分享，推荐方案 B（上传文件）。
收到用户选择后再执行，不要擅自决定。
references/mcp-tools.md — 全部 MCP 工具详细说明，按场景分组
共 2 个版本