{"id":"405cc095-be4f-4982-8181-2735cdd30dd5","entityType":"agent","slug":"clawhub-cpsean-dingtalk-docs-skill","name":"dingtalk-docs-skill","canonicalUrl":"https://www.xpersona.co/agent/clawhub-cpsean-dingtalk-docs-skill","canonicalPath":"/agent/clawhub-cpsean-dingtalk-docs-skill","generatedAt":"2026-10-12T03:49:43.882Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-11T20:51:20.357Z","emptyReason":null},"description":"当用户想要操作钉钉文档或向钉钉知识库推送本地文件时使用本 Skill。支持：将 Markdown/纯文本推送为可编辑钉钉文档、原格式上传 HTML/图片/PDF/Office 等文件、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。 Skill: dingtalk-docs-skill Owner: cpsean Summary: 当用户想要操作钉钉文档或向钉钉知识库推送本地文件时使用本 Skill。支持：将 Markdown/纯文本推送为可编辑钉钉文档、原格式上传 HTML/图片/PDF/Office 等文件、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。 Tags: latest:1.0.3 Version history: v1.0.3 | 2026-09-10T13:42:08.952Z | user dingtalk-docs-skill 1.0.3 - Break","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 994 downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s17fx8atp092kybw1jg9xrwchs87jzzg:dingtalk-docs-skill","sourceUrl":"https://clawhub.ai/cpsean/dingtalk-docs-skill","homepage":"https://clawhub.ai/cpsean/skills/dingtalk-docs-skill","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/cpsean/dingtalk-docs-skill","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/cpsean/skills/dingtalk-docs-skill","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":60,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"当用户想要操作钉钉文档或向钉钉知识库推送本地文件时使用本 Skill。支持：将 Markdown/纯文本推送为可编辑钉钉文档、原格式上传 HTML/图片/PDF/Office 等文件、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权"},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:51:20.357Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:51:20.357Z","emptyReason":null},"stars":null,"forks":null,"downloads":994,"likes":null,"task":null,"library":null,"packageName":null,"latestVersion":"1.0.3","tractionLabel":"994 downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T20:51:20.280Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T20:51:20.357Z","lastCrawledAt":"2026-10-11T20:51:20.280Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T20:51:20.280Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.3","createdAt":"2026-09-10T13:42:08.952Z","changelog":"dingtalk-docs-skill 1.0.3 - Breaking: Removed 5 repository files (.gitignore, LICENSE, evals, references, skill-card.md) for a leaner distribution. - SKILL.md rewritten for stronger security and privacy: strict URL whitelist enforcement for MCP endpoints and mandatory user confirmation before modifying config files. - Initialization process updated to always prefer workspace/project-level MCP configs, confirming with user before ever touching global/user-level files. - Data transfer safety highlighted: all cross-boundary operations (upload, download, cloud reads) now require explicit user confirmation and clear communication of data flow and associated risks. - File push capabilities clarified: now explicitly supports both editable markdown→adoc conversion and original format preservation for HTML/Office/PDF/image uploads, with appropriate workflows and confirmation for each. - Expanded internal documentation for agent config compatibility, default workspace management, and operation boundary protections.","fileCount":7,"zipByteSize":28523},{"version":"1.0.2","createdAt":"2026-08-31T07:51:37.093Z","changelog":"dingtalk-docs-skill 1.0.2 - Added: `.gitignore` and `LICENSE` files to the project. - Added: `evals` and `references` directories for evaluation and reference resources. - Removed: Obsolete `skill-card.md` documentation. - Internal structure improvement: supporting files are now organized outside version control and the main repository. - No changes to user-facing features or core functionality.","fileCount":11,"zipByteSize":17726},{"version":"1.0.1","createdAt":"2026-06-08T04:25:43.066Z","changelog":"dingtalk-docs-skill v1.0.1 - 移除 skill-card.md 文件，整理文档结构 - 在说明文档（SKILL.md）中补充了 `create_document` 和 `update_document` 的内容上限（10,000 字符/单次）、并新增“大文档推送策略”，指导如何处理超长 markdown 的分段推送及钉盘上传 - 其他描述细节优化，保证功能说明准确易用","fileCount":7,"zipByteSize":16583},{"version":"1.0.0","createdAt":"2026-05-28T10:13:48.932Z","changelog":"dingtalk-docs-skill v1.0.0 - Initial release providing full-featured operation of DingTalk Docs via the official MCP Server. - Supports syncing local markdown to DingTalk, pulling and updating documents (including block-level editing), file/attachment downloads, PDF/Word export, and full document/folder management. - Includes robust initialization guidance with support for Claude Code, Cursor, VS Code, Roo Code, Gemini CLI, and Codex. - Implements safety checks for write operations, default knowledge base configuration, multi-language support, and detailed error handling. - Enforces strict security: user API keys and workspace configs are never exposed or checked into version control. - Special care for file uploads and encoding, especially for non-ASCII markdown.","fileCount":7,"zipByteSize":15784}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17fx8atp092kybw1jg9xrwchs87jzzg:dingtalk-docs-skill","setupComplexity":"low","setupSteps":["Setup complexity is LOW. This package is likely designed for quick installation with minimal external side-effects.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cpsean-dingtalk-docs-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cpsean-dingtalk-docs-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cpsean-dingtalk-docs-skill/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cpsean-dingtalk-docs-skill/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cpsean-dingtalk-docs-skill/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cpsean-dingtalk-docs-skill/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-12T03:49:43.879Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cpsean-dingtalk-docs-skill/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cpsean-dingtalk-docs-skill/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cpsean-dingtalk-docs-skill/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cpsean-dingtalk-docs-skill/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-11T20:51:20.357Z","emptyReason":null},"readme":"Skill: dingtalk-docs-skill\n\nOwner: cpsean\n\nSummary: 当用户想要操作钉钉文档或向钉钉知识库推送本地文件时使用本 Skill。支持：将 Markdown/纯文本推送为可编辑钉钉文档、原格式上传 HTML/图片/PDF/Office 等文件、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。\n\nTags: latest:1.0.3\n\nVersion history:\n\nv1.0.3 | 2026-09-10T13:42:08.952Z | user\n\ndingtalk-docs-skill 1.0.3\n\n- Breaking: Removed 5 repository files (.gitignore, LICENSE, evals, references, skill-card.md) for a leaner distribution.\n- SKILL.md rewritten for stronger security and privacy: strict URL whitelist enforcement for MCP endpoints and mandatory user confirmation before modifying config files.\n- Initialization process updated to always prefer workspace/project-level MCP configs, confirming with user before ever touching global/user-level files.\n- Data transfer safety highlighted: all cross-boundary operations (upload, download, cloud reads) now require explicit user confirmation and clear communication of data flow and associated risks.\n- File push capabilities clarified: now explicitly supports both editable markdown→adoc conversion and original format preservation for HTML/Office/PDF/image uploads, with appropriate workflows and confirmation for each.\n- Expanded internal documentation for agent config compatibility, default workspace management, and operation boundary protections.\n\nv1.0.2 | 2026-08-31T07:51:37.093Z | auto\n\ndingtalk-docs-skill 1.0.2\n\n- Added: `.gitignore` and `LICENSE` files to the project.\n- Added: `evals` and `references` directories for evaluation and reference resources.\n- Removed: Obsolete `skill-card.md` documentation.\n- Internal structure improvement: supporting files are now organized outside version control and the main repository.\n- No changes to user-facing features or core functionality.\n\nv1.0.1 | 2026-06-08T04:25:43.066Z | user\n\ndingtalk-docs-skill v1.0.1\n- 移除 skill-card.md 文件，整理文档结构\n- 在说明文档（SKILL.md）中补充了 `create_document` 和 `update_document` 的内容上限（10,000 字符/单次）、并新增“大文档推送策略”，指导如何处理超长 markdown 的分段推送及钉盘上传\n- 其他描述细节优化，保证功能说明准确易用\n\nv1.0.0 | 2026-05-28T10:13:48.932Z | auto\n\ndingtalk-docs-skill v1.0.0\n\n- Initial release providing full-featured operation of DingTalk Docs via the official MCP Server.\n- Supports syncing local markdown to DingTalk, pulling and updating documents (including block-level editing), file/attachment downloads, PDF/Word export, and full document/folder management.\n- Includes robust initialization guidance with support for Claude Code, Cursor, VS Code, Roo Code, Gemini CLI, and Codex.\n- Implements safety checks for write operations, default knowledge base configuration, multi-language support, and detailed error handling.\n- Enforces strict security: user API keys and workspace configs are never exposed or checked into version control.\n- Special care for file uploads and encoding, especially for non-ASCII markdown.\n\nArchive index:\n\nArchive v1.0.3: 7 files, 28523 bytes\n\nFiles: evals/evals.json (9462b), evals/trigger-evals.json (1747b), README.md (11094b), references/mcp-tools.md (14810b), skill-card.md (2577b), SKILL.md (27905b), _meta.json (138b)\n\nFile v1.0.3:SKILL.md\n\n---\r\nname: dingtalk-docs-skill\r\ndescription: 当用户想要操作钉钉文档或向钉钉知识库推送本地文件时使用本 Skill。支持：将 Markdown/纯文本推送为可编辑钉钉文档、原格式上传 HTML/图片/PDF/Office 等文件、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。\r\ncompatibility: Requires dingtalk-doc MCP server (StreamableHttp transport). Compatible with any MCP-capable agent (Claude Code, Cursor, VS Code, Roo Code, Gemini CLI, Codex, etc.). Auto-detects Claude Code; falls back to writing config files or manual setup for other agents.\r\n---\r\n\r\n# 钉钉文档\r\n\r\n通过钉钉文档官方 MCP Server 全面操作云端文档。\r\n\r\n## 语言规则\r\n\r\n**始终使用用户输入的语言进行回复。** 如果用户用英文提问，则全程用英文回复；如果用户用中文，则全程用中文回复。无法判断时默认使用中文。\r\n\r\n## 能力范围\r\n\r\n**读**\r\n- 拉取云端文档正文为 markdown（保存到本地）\r\n- 列出知识库/文件夹下的文档节点\r\n- 按关键词搜索文档\r\n- 获取文档元信息（标题、类型、创建时间等）\r\n- 下载钉盘文件或文档内嵌附件\r\n\r\n**写**\r\n- 按内容类型将本地内容推送到知识库：创建可编辑的 adoc 文档，或保留原格式上传文件\r\n- 覆盖或追加内容到已有文档\r\n- 按块精确编辑（插入/更新/删除段落、标题、表格等）\r\n- 上传本地文件（PDF、图片、Word 等）到知识库\r\n- 将本地图片**内联**嵌入文档正文（自动上传转存为内联图，非占位符人工粘贴）\r\n\r\n**管理**\r\n- 创建文件夹\r\n- 重命名/移动/复制/删除文档和文件夹\r\n- 导出文档为 PDF 或 Word 格式\r\n- 查看/添加/修改知识库节点的成员权限\r\n\r\n**不负责：**\r\n- 飞书、语雀、Notion 等其他平台\r\n- 只修改本地文件（无云端操作）\r\n- 钉钉 IM 消息、企业成员管理\r\n\r\n## 前置条件\r\n\r\n钉钉文档 MCP Server 必须已配置到当前 Agent 的 MCP 设置中，服务名称为 `dingtalk-doc`。\r\n\r\n如果 MCP 工具不可用，先走**初始化流程**，再执行任何文档操作。\r\n\r\n## 初始化流程（首次使用或 MCP 不可用时）\r\n\r\n1. 告知用户访问帮助手册页面并完成开通：\r\n > 请打开以下链接，使用钉钉账号登录后，点击页面上的【开通服务】按钮：\r\n > https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail\r\n\r\n2. 开通后复制页面右侧 **StreamableHttp URL**（不是 JSON Config）\r\n\r\n3. 请用户将 URL 粘贴给你\r\n\r\n4. 收到 URL 后，**先做两项安全校验，再注册**：\r\n\r\n **① URL 域名白名单**：只接受钉钉官方域名——`aihub.dingtalk.com`、`alidocs.dingtalk.com` 及其它 `*.dingtalk.com` 子域。若 URL 域名不在白名单内，**停止注册**并提示用户「该 URL 非钉钉官方域名，可能填错或有风险，请核对」，用户确认后再继续。此举防止把 MCP 流量（含个人 API Key）导向恶意/错误 endpoint。\r\n\r\n **② 写前确认（不静默改用户环境）**：写任何配置文件前，先向用户展示**目标文件完整路径 + 将写入的确切 JSON 内容**，用户显式同意后再写；只追加 `dingtalk-doc` 新条目，绝不覆盖或改动文件里已有的其它配置。\r\n\r\n 两项校验通过后，按以下顺序尝试注册 MCP 服务（`dingtalk-doc` 为服务名，必须为 ASCII）：\r\n\r\n **方案 A — Claude Code**（优先尝试；默认项目级 scope，运行前把命令展示给用户）：\r\n ```bash\r\n claude mcp add --transport http --scope local dingtalk-doc \"<用户提供的 URL>\"\r\n ```\r\n - `--scope local`：仅当前项目生效（项目级，影响面最小）。用户明确希望所有项目通用时，才改 `--scope user`（全局），改前先确认。\r\n - 成功则跳到步骤 5。\r\n\r\n **方案 B — 写入配置文件**（通用方案，大多数 Agent 均可用）：\r\n\r\n **优先项目级、全局需确认**：优先写 workspace 内的**项目级**配置（影响面最小、随项目走、不碰用户全局环境）；仅当该 Agent 没有项目级配置项（如 Gemini CLI、OpenAI Codex 只有全局），或用户明确同意写全局时，才写**全局用户级**配置，且写前必须按步骤 4 ② 展示路径 + 内容确认。\r\n\r\n 检测当前环境存在哪些配置文件，找到第一个匹配项写入：\r\n\r\n | Agent | 配置文件（项目级，优先写这个） | 配置文件（全局，仅无项目级或用户确认后写） | `mcpServers` 键名 |\r\n |-------|----------------|----------------|-----------------|\r\n | Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json`（写前确认） | `mcpServers` |\r\n | VS Code Copilot | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json`（Mac）
`%APPDATA%\\Code\\User\\mcp.json`（Win）（写前确认） | `servers` |\r\n | Roo Code | `.roo/mcp.json` | —（无全局需求） | `mcpServers` |\r\n | Gemini CLI | —（无项目级） | `~/.gemini/settings.json`（仅全局，写前确认） | `mcpServers` |\r\n | OpenAI Codex | —（无项目级） | `~/.codex/config.json`（仅全局，写前确认） | `mcpServers` |\r\n\r\n 向目标文件追加（若文件已有 `mcpServers`/`servers`，只添加新条目，不覆盖原有内容）：\r\n\r\n ```json\r\n {\r\n \"mcpServers\": {\r\n \"dingtalk-doc\": {\r\n \"type\": \"http\",\r\n \"url\": \"<用户提供的 URL>\"\r\n }\r\n }\r\n }\r\n ```\r\n > VS Code Copilot 的 `.vscode/mcp.json` 使用 `\"servers\"` 而非 `\"mcpServers\"`，写入时注意区分。\r\n\r\n 成功写入则跳到步骤 5。\r\n\r\n **方案 C — 手动兜底**（方案 A/B 均不适用时）：\r\n\r\n 向用户展示以下信息，请其参照所用 Agent 的文档手动添加 MCP 服务，完成后回来继续：\r\n ```\r\n 传输类型：StreamableHttp（HTTP）\r\n 服务名称：dingtalk-doc\r\n URL：<用户提供的 URL>\r\n ```\r\n 用户手动配置完成后，本 Skill 只需确认 MCP 工具可用即可继续。\r\n\r\n > URL 中含有个人 API Key，写入配置后不要在回复中重复显示完整 URL。\r\n\r\n5. 询问用户的默认知识库地址：\r\n > 请在浏览器中打开你常用的钉钉知识库，把地址栏的 URL 粘贴给我（格式类似 `https://alidocs.dingtalk.com/i/spaces/xxxxx/overview`）。\r\n > 如果暂时不设默认知识库，可以跳过，后续每次操作时再指定。\r\n\r\n6. 收到知识库 URL 后，写入 `references/dingtalk.config`：\r\n ```\r\n DINGTALK_DEFAULT_WORKSPACE_URL=<用户提供的知识库 URL>\r\n ```\r\n 此文件已被 `.gitignore` 排除，不会进入版本控制。无需重启，下次操作时直接读取生效。\r\n\r\n7. MCP 配置写入后，提示用户重启 Agent 客户端以使 MCP 生效，重启后回来继续操作即可。\r\n\r\n### 使用默认知识库\r\n\r\n- 当用户说\"列出我的知识库文档\"、\"推送到知识库\"等未指明位置的操作时，优先使用默认知识库 URL\r\n- **读取顺序**：① 读取 `references/dingtalk.config` 中的 `DINGTALK_DEFAULT_WORKSPACE_URL`；② 若文件不存在或值为空，检查环境变量 `$DINGTALK_DEFAULT_WORKSPACE_URL`（兼容已有 Claude Code 配置）；③ 两者均无则询问用户\r\n- 获得 URL 后，调用 `get_document_info` 传入该 URL 解析出 nodeId，再以该 nodeId 作为 `list_nodes` / `create_folder` 的 `folderId`（知识库根则用 `workspaceId`）\r\n\r\n### 更改默认知识库\r\n\r\n当用户说\"更换默认知识库\"、\"修改知识库地址\"等时：\r\n\r\n1. 请用户在浏览器打开目标钉钉知识库，复制地址栏 URL\r\n2. 收到新 URL 后，覆盖写入 `references/dingtalk.config`：\r\n ```\r\n DINGTALK_DEFAULT_WORKSPACE_URL=<新的知识库 URL>\r\n ```\r\n3. 无需重启，下次操作时读取新值即生效\r\n\r\n### 安全规则\r\n\r\n- **URL 域名白名单**：注册的 MCP URL 只接受钉钉官方域名（`*.dingtalk.com`）；非白名单域名先停下让用户核对，防止把含 API Key 的流量导向恶意/错误 endpoint\r\n- **写前确认 + 优先项目级**：写任何 Agent 配置文件前展示目标路径 + 确切内容供用户确认；优先项目级配置，全局用户级配置仅在无项目级选项或用户明确同意时写，且只追加不覆盖\r\n- MCP 服务 URL 含有个人 API Key，**不得出现在任何版本控制文件中**；写入配置后不要在回复中重复显示完整 URL\r\n- `references/dingtalk.config` 保存知识库 URL，已被 `.gitignore` 排除，不会提交到版本控制\r\n- 如果用户将 URL 粘贴到聊天中，立即写入配置后不再引用\r\n\r\n## 默认路径\r\n\r\n1. 确认 MCP 工具可用（若不可用，进入初始化流程）\r\n2. 理解用户意图，映射到对应 MCP 工具（见工具映射表）\r\n3. 如需要 dentryUuid/nodeId 但用户未提供：优先读取 `references/dingtalk.config`（或环境变量 `$DINGTALK_DEFAULT_WORKSPACE_URL`）获取默认知识库 URL，调用 `get_document_info` 解析出 nodeId；否则调用 `search_documents` 或 `list_nodes` 定位目标，让用户确认后再操作\r\n4. 对推送请求确定推送方案；若格式、是否保留原格式、是否需要在线编辑或用户意图不足以唯一确定方案，先让用户选择方案，**不得开始创建或上传**\r\n5. **执行前确认**（只读操作除外，见下方说明）：方案确定后，向用户展示操作摘要，收到明确同意后再调用 MCP 工具\r\n6. 执行操作\r\n7. 报告结果：操作类型、文档标题、文档链接（如有）\r\n\r\n### 执行前确认规则\r\n\r\n**需要确认的操作**（所有会写入或修改云端数据的操作）：\r\n`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`\r\n\r\n**无需确认的操作**（只读）：\r\n`search_documents`、`list_nodes`、`get_document_info`、`get_document_content`、`list_document_blocks`、`list_permission`、`query_export_job`、`download_file`、`download_doc_attachment`\r\n\r\n> **只读 ≠ 无边界**（敏感读取护栏）：`get_document_content` / `download_*` 会把云端正文或文件字节拉进本地上下文。遵循**最小化**——只读当前任务确需的文档、不批量拉全文；请求模糊或命中多目标时**先确认具体是哪一篇**再读；读取内容仅用于当前任务，不外传、不沉淀到无关文件。\r\n\r\n**确认摘要格式**（根据操作类型调整）：\r\n\r\n```\r\n即将执行以下操作，请确认：\r\n\r\n操作：<创建 / 更新（覆盖）/ 更新（追加）/ 删除 / 重命名 / 移动 / 复制 / 创建文件夹 / 图片内联 / 批量修复>\r\n目标：<文档标题或文件夹名>\r\n位置：<知识库名或文件夹路径>\r\n说明：<一句话描述本次变更，例如\"将以本地文件 xxx.md 的内容覆盖云端文档全文\"；批量修复须注明\"将删除 N 个块并重插 N 张图\">\r\n\r\n确认请回复「是」或「确认」，取消请回复「否」或「取消」。\r\n```\r\n\r\n收到取消时：停止操作，不重试，告知用户已取消。\r\n\r\n## 数据安全与边界\r\n\r\n本 Skill 在本地与钉钉云端之间**双向搬运数据**。以下三类跨边界操作，除「执行前确认」外，还须在回复中明示数据去向与风险（对齐 clawhub 上架安全要求）：\r\n\r\n### 1. 数据离开本地（上传 / HTTP PUT）\r\n\r\n- **文件上传**（`get_file_upload_info` → HTTP PUT → `commit_uploaded_file`）与**图片内联**（`get_doc_attachment_upload_info` → HTTP PUT）会把**本地文件的原始字节经 HTTP PUT 直传钉钉 OSS 云端**，再入库/转存——这不是纯本地操作。\r\n- 确认摘要须写明：「本地文件 `<名称>` 的原始字节将上传到钉钉云端存储」，用户同意后再传。\r\n- 上传目标 URL 由钉钉官方接口签发（OSS 凭证），**不接受用户手填的任意 endpoint**。\r\n\r\n### 2. 数据扩散（导出 / 下载 / 临时签名 URL）\r\n\r\n- **导出**（`submit_export_job`）产生文档的**可移植副本**（PDF/Word/markdown）；**下载**（`download_file` / `download_doc_attachment`）与签名 URL 把云端内容取到本地或生成**临时可访问链接**。\r\n- 提示用户：导出/下载产生的是**可扩散副本**，签名 URL 在时效内**任何持有者可访问**；后续存储、分享、传播的责任与风险由用户承担，链接有时效、勿长期外发。\r\n\r\n### 3. 敏感读取（拉正文进上下文）\r\n\r\n- `get_document_content` 等只读操作把云端正文拉进当前对话上下文。遵循**最小化**：只读确需文档、不批量拉全文、模糊请求先确认具体文档、内容仅用于当前任务（详见「执行前确认规则」下的敏感读取护栏）。\r\n\r\n## MCP 工具映射\r\n\r\n详见 `references/mcp-tools.md`。常用映射如下：\r\n\r\n| 用户意图 | MCP 工具 |\r\n|---------|---------|\r\n| 推送 Markdown / 纯文本为可编辑钉钉文档 | `create_document` |\r\n| 推送 HTML、图片或其他本地文件并保留原格式 | `get_file_upload_info` → HTTP PUT → `commit_uploaded_file` |\r\n| 拉取 adoc 文字文档内容到本地 | `get_document_content` |\r\n| 覆盖或追加文档内容 | `update_document` |\r\n| 精确块级编辑（段落/标题/表格等） | `list_document_blocks` → `insert/update/delete_document_block` |\r\n| 将本地图片内联嵌入文档正文 | `get_doc_attachment_upload_info` → HTTP PUT → `download_doc_attachment`（取签名 URL）→ `update_document`(append, ``) |\r\n| 列出知识库/文件夹下的文档 | `list_nodes` |\r\n| 按关键词搜索文档 | `search_documents` |\r\n| 获取文档元信息（标题、类型等） | `get_document_info` |\r\n| 下载钉盘文件 | `download_file` |\r\n| 下载文档内嵌附件 | `download_doc_attachment` |\r\n| 导出文档为 PDF/Word | `submit_export_job` → `query_export_job`（轮询至完成）|\r\n| 创建文件夹 | `create_folder` |\r\n| 删除文档节点 | `delete_document` |\r\n| 重命名节点 | `rename_document` |\r\n| 移动节点到其他文件夹 | `move_document` |\r\n| 复制节点到其他文件夹 | `copy_document` |\r\n| 查看节点成员权限 | `list_permission` |\r\n| 添加/修改节点成员权限 | `add_permission` / `update_permission` |\r\n\r\n## 失败处理\r\n\r\n- **MCP 工具不可用**：停止，进入初始化流程，不要猜测或尝试其他方式调用\r\n- **未提供目标文档**：先用 `search_documents` 或 `list_nodes` 找到目标，让用户确认后再操作\r\n- **读取非 adoc 节点**：先调用 `get_document_info` 或使用列表/搜索结果中的类型字段确认 `contentType`。只有 `adoc` 可调用 `get_document_content`；不要对其他类型反复重试该工具\r\n- **读取 axls（钉钉表格）**：`get_document_content` 不支持 `axls`。仅当当前会话实际提供可用的表格 MCP 工具时，才使用该工具读取所需单元格或区域；不得根据报错臆造或调用未安装的工具。若表格工具不可用，明确说明当前无法读取该表格，并请用户直接粘贴需要处理的表格内容，或提供导出的文件/目标数据\r\n- **读取 dlink（快捷方式）**：`dlink` 不是正文载体，不能直接调用 `get_document_content`。从其元信息中取得指向目标的原始 nodeId，使用原始 nodeId 继续查询类型和读取；搜索或列出结果同时含有原节点与指向该节点的 `dlink` 时，按原始 nodeId 去重，优先保留原节点。无法解析原始 nodeId 时，向用户说明该快捷方式无法直接读取，不要重试正文读取\r\n- **读取其他非 adoc 节点**：演示、脑图、白板、文件等非 `adoc` 节点不适用 `get_document_content`。仅在当前会话存在匹配的专用读取工具时使用；否则说明限制，并请用户粘贴所需内容、提供导出文件，或改为下载/导出后处理\r\n- **update_document 报错**：确认目标是否为 adoc（文字类型）文档，非 adoc 文档不支持此操作\r\n- **delete_document 前**：确认摘要中必须注明\"将移入回收站，30 天内可恢复\"，收到确认后再执行\r\n- **API 报错（权限/鉴权类）**：当 API 返回权限不足、无权限、鉴权失败、Forbidden、Unauthorized 等错误时，除了展示原文错误信息外，提示用户可能尚未开通所在组织的钉钉开发者权限，引导用户参考以下链接完成开通：\r\n > 请访问钉钉开发者入门文档，确认你已在所在组织中开通了开发者权限：\r\n > https://open.dingtalk.com/document/dingstart/dingtalk-developer\r\n >\r\n > 开通步骤简述：登录钉钉开放平台 → 选择对应组织 → 完成开发者认证/开通。完成后重新尝试操作。\r\n- **并发写冲突**：报 `unable to write to document concurrently` 时，说明有多个写操作同时进行。所有写操作（create/update/insert/delete block）必须**严格串行**，一个完成后再执行下一个；不要并行提交\r\n- **图片内联后显示\"暂无权限访问\"/占位插画**：说明用了 `resourceUrl`（`/core/api/resources/img/…`）当图源且该资源对导入器不可达，抓到的是占位图（≈42210 字节 PNG）。改用 `download_doc_attachment` 返回的**签名下载 URL** 重新内联，并按字节级验收复核\r\n- **删块结果异常**：删除后若发现块未删或误删邻块，用 `list_document_blocks` 复核实际结果再决定下一步，不要盲目重试删除\r\n- **其他 API 报错**：原文展示错误信息，不猜测原因，不自动重试\r\n\r\n## 关键约束\r\n\r\n- `update_document` 和 `create_document` 仅支持 **adoc（文字类型）** 文档，不支持表格、演示、脑图等\r\n- `create_document` 和 `update_document` 的 `markdown` 参数上限均为 **10,000 字符**；超出会报 `invalidRequest.inputArgs.invalid` 错误。推送前应先估算内容字符数，超过 **9,500 字符**（留余量）时走大文档推送策略（见下文）\r\n- `delete_document` 是移入回收站，不是永久删除，30 天内可从回收站恢复\r\n- `list_nodes` 只返回直接子节点，不递归。需要深层列表时需要多次调用\r\n- **所有写操作严格串行**：`create_document`、`update_document`、`insert/update/delete_document_block` 不能并行作用于同一文档，否则报 `unable to write to document concurrently`；删块后必须 `list_document_blocks` 复核\r\n- **含图推送时 index 按块算**：图片不计入 10000 字符上限，但每张内联图占用一个块位；用 `update_document`(append, index) 定位时，index 以 `list_document_blocks` 的块序号为准，插入后其后所有块 index +1\r\n- **导出为异步操作**：`submit_export_job` 返回 jobId 后需轮询 `query_export_job` 直到状态完成，再将下载链接告知用户；轮询间隔建议 1-2 秒\r\n- **Mermaid 文本绘图**：通过 `create_document` 推送的 ` ```mermaid ` 代码块会被解析为普通代码块，而非钉钉原生文本绘图块。钉钉的文本绘图是私有块类型，API 层未暴露，无法通过 MCP 创建或转换。推送前告知用户此限制，建议推送后在钉钉编辑器中手动将代码块转换为文本绘图\r\n- 操作完成后，从返回值中提取文档链接告知用户，方便直接点击查看\r\n\r\n## 对话中上传文件的处理\r\n\r\n用户可能在对话中直接上传文件并要求推送到钉钉。先识别文件扩展名、MIME 类型或实际内容，再按下列规则选择推送方案；**保留用户提供的原始格式，不要为了使用 `create_document` 擅自转码或转换格式**。\r\n\r\n### 推送方案选择\r\n\r\n| 输入内容 | 默认推送方案 | 原因与限制 |\r\n|---|---|---|\r\n| Markdown / 纯文本（`.md`、`.markdown`、`.txt`）或用户直接提供的文字内容 | `create_document` 创建 `adoc` | 适合在线编辑、评论和协作；受单次 10,000 字符限制 |\r\n| HTML（`.html`、`.htm`） | 文件上传三步流程 | 以 HTML 文件原样存入知识库，不转换为 Markdown / adoc |\r\n| 图片（如 `.png`、`.jpg`、`.jpeg`、`.gif`、`.webp`、`.svg`） | 文件上传三步流程 | 以图片文件原样上传 |\r\n| PDF、Office 文件、表格、压缩包、音视频及其他二进制文件 | 文件上传三步流程 | 以原始文件上传；不能使用 `create_document` 或 `update_document` 写入 |\r\n| 无扩展名或类型无法判断的文件 | 先询问用户希望“在线可编辑文档”还是“原文件上传” | 不擅自猜测或转换；只有用户确认文本内容且希望在线编辑时才创建 adoc |\r\n\r\n用户明确要求改变默认方案时，以用户要求为准。例如，用户要求将 HTML 转为可编辑文字文档时，先说明转换后可能丢失样式或交互，再经确认后转换为 Markdown / 纯文本并使用 `create_document`。\r\n\r\n### MD 优先与方案确认\r\n\r\n- **原始 Markdown 文件优先创建 adoc**：对于 `.md` / `.markdown` 文件，用户未指定其他目标时，先估算 Markdown 正文的**字符数**。不以文件字节大小或行数代替此判断；估算不超过 9,500 字符时，默认方案为创建可编辑的 adoc\r\n- **超出 adoc 单次上限时必须选择**：Markdown 正文超过 9,500 字符时，不得自动拆分或直接上传。先向用户说明 adoc 单次 `create_document` / `update_document` 上限为 10,000 字符，并提供两个选项：方案 A 为分段创建并追加 adoc，方案 B 为原样上传 `.md` 文件。推荐需要在线编辑、评论或协作时选择方案 A；只需存档或下载分享时选择方案 B。收到用户选择后才进入写入确认\r\n- **推送方案不明确时必须先确认**：只要文件类型、是否保留原格式、是否转换为可编辑 adoc，或用户期望的交付形态存在歧义，就先展示可选方案并等待用户明确选择。此时可进行只读的文件类型或元信息识别，但不得调用 `create_document`、`get_file_upload_info`、HTTP PUT 或 `commit_uploaded_file`\r\n- **方案确认不替代写入确认**：用户选定方案后，仍须按“执行前确认规则”展示目标位置、文件/文档名称和操作摘要；收到明确同意后才执行云端写入\r\n\r\n### 文件上传流程\r\n\r\n对于应原样保留的文件，确认目标位置与文件名后，执行：\r\n\r\n1. 调用 `get_file_upload_info`，传入原始 `fileName`、实际 `fileSize` 和目标 `folderId` 或 `workspaceId`\r\n2. 使用返回的凭证对文件原始字节执行 HTTP PUT；不得将图片、HTML 或其他文件内容改写为 Markdown\r\n3. 调用 `commit_uploaded_file`，使用返回的 `uploadKey` 提交入库\r\n4. 返回上传文件的名称、节点标识和访问链接（如返回）\r\n\r\n### 已知限制\r\n\r\n- 对话上传的文件内容是**临时的**，不会持久保存到磁盘，上下文压缩或会话结束后内容即丢失\r\n- **非 ASCII 文件（如中文 markdown）通过对话上传时，0x80-0x9F 范围的字节会被文本处理层丢弃，导致不可逆乱码**。这是客户端文本传输的固有限制，编码修复无法还原丢失的字节\r\n\r\n### 处理规则\r\n\r\n1. **优先使用本地文件路径**：当用户要推送含非 ASCII 内容（中文、日文等）的文本文件，或任何需要原样上传的二进制/HTML 文件时，请用户提供本地磁盘路径，直接读取文件内容或原始字节，避免编码问题\r\n2. **对话上传的文件先检查编码**：如果用户直接在对话中上传了文件，先检查内容是否出现乱码。如果存在乱码，立即告知用户并请其提供本地文件路径\r\n3. **文本按类型路由**：可正确读取的 Markdown / 纯文本按上表创建 adoc；HTML 即使能读取文本，也默认按原 HTML 文件上传\r\n4. **二进制或原格式上传须读取本地文件**：图片、PDF、Office 文件等需要读取原始字节；如果对话附件无法提供可靠的本地文件内容，请用户提供本地磁盘路径后走文件上传三步流程\r\n5. **命名规则**：创建 adoc 时默认使用文件名去掉扩展名作为文档标题；上传原文件时默认保留原始文件名。用户要求修改名字时，以用户指定的名字为准\r\n\r\n## 大文档推送策略\r\n\r\n当原始 Markdown 文件的正文超过 **9,500 字符** 时，单次 `create_document` / `update_document` 会超过 10,000 字符上限。此时先让用户在以下两种方案中选择，**不要自动执行任一方案**：\r\n\r\n### 方案 A — 分段推送（生成可在线编辑的 adoc）\r\n\r\n1. 按 `## ` / `### ` 标题边界将内容切分为若干段，每段 ≤ 9,500 字符，避免在表格中间切断\r\n2. 用 `create_document` 写入第 1 段（含标题）\r\n3. 依次用 `update_document`（`append` 模式）追加后续各段，每段单独一次调用\r\n4. 全部追加完成后报告文档链接\r\n\r\n**适合场景**：用户需要在钉钉在线编辑、评论、协作，或希望文档格式被渲染\r\n\r\n### 方案 B — 上传原始 .md 文件（存入钉盘）\r\n\r\n走三步文件上传流程：`get_file_upload_info` → HTTP PUT → `commit_uploaded_file`\r\n\r\n**适合场景**：只需存档或分享下载，不需要在线编辑；操作更简单，文件完整保留原格式\r\n\r\n### 推荐选择\r\n\r\n向用户说明两个方案后，推荐如下：\r\n\r\n> 如果你需要在钉钉里直接编辑或与同事协作，推荐方案 A（分段推送）；如果只是存档或分享，推荐方案 B（上传文件）。\r\n\r\n收到用户选择后再执行，不要擅自决定。\r\n\r\n## 本地图片内联到文档正文\r\n\r\n当用户要把本地图片作为**文档正文的一部分**（内联图，随文档在线渲染/评论），而非作为独立文件存入知识库时，走自动内联链路，**不要用占位符 + 人工粘贴**。完整步骤与陷阱见 `references/mcp-tools.md`「本地图片内联到文档正文」，要点：\r\n\r\n1. **区分两种图片意图**：图片作为独立文件存档 → `get_file_upload_info` 三步上传（见「对话中上传文件的处理」）；图片内联进正文 → 本节链路\r\n2. **链路**：`get_doc_attachment_upload_info` 上传拿 `resourceId` → HTTP PUT 原始字节 → `download_doc_attachment` 取**签名下载 URL** → `update_document`(append) 或 `create_document` 写入 ``，钉钉自动抓取转存为内联图\r\n3. **统一用签名下载 URL**：`resourceUrl`（`/core/api/resources/img/…`）行为不稳定——资源可达时能解析，不可达时会变「暂无权限访问」占位插画；为可靠起见一律用 `download_doc_attachment` 的签名下载 URL\r\n4. **替换旧图净零位移**：先 append 新图到旧图 index，再按 `blockId` 删旧块，先加后删配对完成\r\n5. **字节级验收**：推送后导出或取 markdown，下载新图签名 URL 比对字节数等于原图；抽查 2-3 张。修复类批量操作（删坏块 + 重插图）在执行前确认摘要中注明「将删除 N 个块并重插 N 张图」\r\n\r\n---\r\n\r\n## 资源导航\r\n\r\n- `references/mcp-tools.md` — 全部 MCP 工具详细说明，按场景分组（含「本地图片内联到文档正文」完整链路与「已知陷阱速查」）\n\nFile v1.0.3:README.md\n\n# dingtalk-docs-skill\n\n[English](#english) | [中文](#中文)\n\n---\n\n## 中文\n\n**dingtalk-docs-skill** 是一个兼容多平台的 Agent Skill，通过钉钉文档官方 MCP Server 全面操作钉钉云端文档，支持读取、推送、同步、导出、权限管理等。\n\n### 功能\n\n| 类别 | 能力 |\n|------|------|\n| **读** | 拉取云端文档正文为 markdown、列出知识库/文件夹文档、按关键词搜索、获取文档元信息、下载钉盘文件与文档附件 |\n| **写** | 将 Markdown/纯文本推送为可编辑钉钉文档、按原格式上传 HTML/图片/PDF/Office 等文件、将本地图片内联嵌入文档正文、覆盖/追加更新文档内容、块级精确编辑（段落/标题/表格等） |\n| **管理** | 创建文件夹、重命名/移动/复制/删除文档和文件夹、导出文档为 PDF/Word、管理节点成员权限 |\n\n所有操作通过[钉钉官方 MCP Server](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) 完成，无需本地脚本，API Key 不会写入代码。\n\n### 快速开始\n\n**1. 安装 Skill**\n\n**用户级安装**（推荐，所有项目均可使用）：\n\nmacOS / Linux：\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n ~/.claude/skills/dingtalk-docs-skill\n```\n\nWindows（PowerShell）：\n```powershell\ngit clone https://github.com/CPsean/dingtalk-docs-skill `\n \"$env:USERPROFILE\\.claude\\skills\\dingtalk-doc\"\n```\n\n**项目级安装**（仅当前项目可用）：\n\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n .claude/skills/dingtalk-docs-skill\n```\n\n安装后重启 Claude Code 使 Skill 生效。\n\n**2. 开通钉钉文档 MCP 服务**\n\n首次使用时，Skill 会引导你完成配置：\n\n1. 打开[钉钉 AI Hub MCP 页面](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail)，登录钉钉账号，点击【开通服务】\n2. 复制页面右侧的 **StreamableHttp URL**（不是 JSON Config）\n3. 将 URL 粘贴给 Claude\n\nSkill 会自动注册 MCP 服务。Claude Code 客户端执行：\n\n```bash\nclaude mcp add --transport http --scope user dingtalk-doc \"<你的 URL>\"\n```\n\n其他客户端（Claude Desktop、Cursor 等）需手动配置 StreamableHttp 类型的 MCP 服务。\n\n**3.（可选）设置默认知识库**\n\n提供你常用的知识库 URL，后续操作无需每次指定：\n\n```\nhttps://alidocs.dingtalk.com/i/spaces/xxxxx/overview\n```\n\n### 使用示例\n\n直接用自然语言和 Claude 对话即可：\n\n- *\"把 `docs/design.md` 推送到我的钉钉知识库\"*\n- *\"用本地最新版本更新钉钉上的 PRD 文档\"*\n- *\"把这篇带本地截图的 markdown 推到钉钉，图片要能正常显示\"*\n- *\"列出我知识库里的所有文档\"*\n- *\"在钉钉文档里搜索「认证」\"*\n- *\"把会议纪要从钉钉拉取到本地\"*\n- *\"删除钉钉上的测试文档\"*\n\n### 工作流程\n\n```\n用户请求\n → Skill 激活（通过 description 触发词匹配）\n → MCP 工具映射（create / update / list / search / delete ...）\n → 执行前确认（所有写操作需用户确认）\n → 钉钉文档 MCP Server\n → 返回结果：文档标��� + 链接\n```\n\n### 已知限制\n\n| 限制项 | 详情 |\n|---|---|\n| **Mermaid 流程图** | ` ```mermaid ` 代码块推送后显示为普通代码块，而非钉钉原生「文本绘图」。推送后需在钉钉编辑器中手动转换。 |\n| **对话上传文件编码** | 非 ASCII 文件（中文等）通过对话上传时可能出现不可逆乱码。请始终提供**本地文件路径**。 |\n| **文档类型** | `create_document` 和 `update_document` 仅支持 **adoc**（文字类型）文档。 |\n| **非 adoc 读取** | `get_document_content` 只可读取 adoc。`axls` 表格需使用当前会话实际可用的表格工具；工具不可用时请直接提供所需内容或导出文件。`dlink` 快捷方式需先解析目标原始 nodeId，并按该 ID 去重。 |\n| **推送类型选择** | Markdown/纯文本默认创建可编辑 adoc；HTML、图片、PDF、Office 等默认按原格式上传到知识库，不会擅自转换。 |\n| **Markdown 大文件** | `.md` / `.markdown` 优先创建 adoc；正文超过 9,500 字符时，先由用户选择分段 adoc 或原样上传 MD 文件。 |\n| **方案不明确** | 文件格式、保留原格式或在线编辑需求不明确时，先确认推送方案；方案确认不替代云端写入前的确认。 |\n| **删除** | 移入回收站（30 天内可恢复），非永久删除。 |\n| **本地图片内联** | 需内联进正文的图片走 `get_doc_attachment_upload_info` → PUT → `download_doc_attachment` 取签名 URL → 写入 `` 自动转存链路。**统一用签名 URL，勿依赖 `resourceUrl`**（资源不可达时会得到「暂无权限访问」占位插画）。所有写操作串行，推送后做字节级校验。 |\n\n### 安全性\n\n- MCP 服务 URL 包含个人 API Key，仅写入本地配置，**不会提交到版本控制**\n- 所有写操作执行前都需要用户明确确认\n\n### 文件结构\n\n```\n.claude/skills/dingtalk-docs-skill/\n├── SKILL.md # Skill 入口（触发器 + 指令）\n├── README.md # 本文件\n├── evals/\n│ ├── evals.json # 任务执行测评\n│ └── trigger-evals.json # 触发边界测评\n└── references/\n └── mcp-tools.md # MCP 工具速查表\n```\n\n---\n\n## English\n\n**dingtalk-docs-skill** is a cross-platform Agent Skill for reading, pushing, syncing, exporting, and managing documents on [DingTalk Docs](https://alidocs.dingtalk.com) via the official DingTalk Document MCP Server.\n\n### Features\n\n| Category | Capabilities |\n|----------|-------------|\n| **Read** | Pull cloud document content as markdown, list knowledge base / folder nodes, search by keyword, get document metadata, download DingTalk Drive files and attachments |\n| **Write** | Push Markdown/plain text as editable DingTalk documents, upload HTML/images/PDF/Office files in their original formats, inline local images into the document body, overwrite / append document content, and make block-level edits |\n| **Manage** | Create folders, rename / move / copy / delete documents and folders, export documents to PDF or Word, manage node member permissions |\n\nAll operations go through [DingTalk's official MCP Server](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) — no local scripts or API keys in code.\n\n### Quick Start\n\n**1. Install the Skill**\n\n**User-level install** (recommended — available across all projects):\n\nmacOS / Linux:\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n ~/.claude/skills/dingtalk-docs-skill\n```\n\nWindows (PowerShell):\n```powershell\ngit clone https://github.com/CPsean/dingtalk-docs-skill `\n \"$env:USERPROFILE\\.claude\\skills\\dingtalk-doc\"\n```\n\n**Project-level install** (current project only):\n\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n .claude/skills/dingtalk-docs-skill\n```\n\nRestart Claude Code after installing to load the skill.\n\n**2. Enable the DingTalk Document MCP Server**\n\nOn first use, the skill will guide you through setup:\n\n1. Open the [DingTalk AI Hub MCP page](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) and activate the service\n2. Copy the **StreamableHttp URL** from the page\n3. Paste it into the Claude conversation\n\nThe skill automatically registers the MCP server. For Claude Code:\n\n```bash\nclaude mcp add --transport http --scope user dingtalk-doc \"\"\n```\n\nFor other clients (Claude Desktop, Cursor, etc.), configure a StreamableHttp MCP server manually.\n\n**3. (Optional) Set a Default Knowledge Base**\n\nProvide your knowledge base URL so you don't have to specify it every time:\n\n```\nhttps://alidocs.dingtalk.com/i/spaces/xxxxx/overview\n```\n\n### Usage Examples\n\nJust talk to Claude naturally:\n\n- *\"Push `docs/design.md` to my DingTalk knowledge base\"*\n- *\"Update the PRD document on DingTalk with the latest local version\"*\n- *\"Push this markdown with local screenshots to DingTalk so the images render inline\"*\n- *\"List all documents in my knowledge base\"*\n- *\"Search DingTalk docs for 'authentication'\"*\n- *\"Pull the meeting notes from DingTalk to local\"*\n- *\"Delete the test document from DingTalk\"*\n\n### How It Works\n\n```\nUser request\n → Skill activation (matched by description trigger)\n → MCP tool mapping (create / update / list / search / delete ...)\n → Pre-execution confirmation (for all write operations)\n → DingTalk Document MCP Server\n → Result: document title + link\n```\n\n### Known Limitations\n\n| Limitation | Detail |\n|---|---|\n| **Mermaid diagrams** | ` ```mermaid ` blocks are pushed as plain code blocks, not DingTalk's native \"text drawing\" blocks. Manually convert after pushing. |\n| **File encoding on chat upload** | Non-ASCII files (Chinese, etc.) uploaded through the chat may suffer irreversible garbled text. Always provide a **local file path**. |\n| **Document types** | `create_document` and `update_document` only support **adoc** (text document) type. |\n| **Non-adoc reads** | `get_document_content` only reads adoc. `axls` needs a spreadsheet tool that is actually available in the current session; otherwise provide the content or an export. Resolve `dlink` shortcuts to their original node IDs and deduplicate by that ID. |\n| **Push routing** | Markdown/plain text creates editable adoc by default. HTML, images, PDF, and Office files upload in their original formats without implicit conversion. |\n| **Large Markdown** | `.md` / `.markdown` prefers adoc. Above 9,500 characters, the user chooses between segmented adoc and uploading the original MD file. |\n| **Ambiguous routing** | When the format, original-format preservation, or online-editing intent is unclear, the Skill confirms the route before creating or uploading. Route confirmation is separate from write confirmation. |\n| **Deletion** | Moves to trash (recoverable within 30 days), not permanent deletion. |\n| **Inline local images** | Images meant for the body go through `get_doc_attachment_upload_info` → PUT → `download_doc_attachment` (signed URL) → write `` so DingTalk auto-fetches and re-hosts them. **Always use the signed URL; `resourceUrl` is unreliable** (it yields a \"no access\" placeholder illustration). Keep writes serial and verify byte-for-byte after pushing. |\n\n### Security\n\n- The MCP server URL contains a personal API key — written to local config only, **never committed to version control**\n- All write operations require explicit user confirmation before execution\n\n### File Structure\n\n```\n.claude/skills/dingtalk-docs-skill/\n├── SKILL.md # Skill entry point (trigger + instructions)\n├── README.md # This file\n├── evals/\n│ ├── evals.json # Task execution evals\n│ └── trigger-evals.json # Trigger boundary evals\n└── references/\n └── mcp-tools.md # MCP tool reference\n```\n\n### License\n\nMIT\n\nFile v1.0.3:_meta.json\n\n{\n \"ownerId\": \"kn7facsvhzy0pcacszzatx32th87jknt\",\n \"slug\": \"dingtalk-docs-skill\",\n \"version\": \"1.0.3\",\n \"publishedAt\": 1789047728952\n}\n\nFile v1.0.3:references/mcp-tools.md\n\n# 钉钉文档 MCP 工具速查\n\nMCP 名称：`dingtalk-doc`（注册方式见 SKILL.md 初始化流程）\n\n---\n\n## 文档内容操作\n\n### create_document\n创建文字类型（adoc）钉钉文档，支持带初始 markdown 内容。\n\n- 关键参数：`name`（文档标题，必填）、`markdown`（初始正文）、`folderId`（目标文件夹节点）、`workspaceId`（知识库 ID）\n- 放置位置优先级：`folderId` > `workspaceId` > 两者都不传时建在「我的文档」根目录\n- 返回：新文档的 `dentryUuid`、文档链接\n- **`markdown` 换行必须用真实换行符（U+000A）**，不能是字面量 `\\n`，否则标题/段落/表格会全部渲染在同一行\n- 上限 **10000 字符**，超出改用 `update_document` 分批 append\n- 注意：只能创建 adoc 类型；表格/演示等其他类型用 `create_file`\n\n### update_document\n更新文字类型（adoc）文档的内容，支持两种模式：\n\n- `overwrite`（默认）：清空全文后重写，**会丢失原有图片/评论**，谨慎使用\n- `append`：追加内容，可配合 `index` 精确插入到指定块之前\n- 关键参数：`nodeId`（文档 URL 或 dentryUuid）、`markdown`（正文）、`mode`（overwrite/append）、`index`（仅 append 生效）、`format`（markdown/jsonml，默认 markdown）\n- **`index` 语义**：从 0 开始，表示插入到文档第 index 个块**之前**；不传则追加到末尾。index 由 `list_document_blocks` 获取\n- **index 位移规则**：插入成功后，该位置及其后所有块的 index 依次 **+1**；批量插/删须按此重算，或采用「先加后删配对完成」避免连锁位移\n- **`markdown` 换行必须用真实换行符（U+000A）**，不能是字面量 `\\n`\n- 上限 **10000 字符**，超出分批 append\n- 限制：**仅支持 adoc 类型文档**，其他类型会报错\n\n### get_document_content（高敏感）\n获取文档的 markdown 正文内容。\n\n> ⚠️ **敏感读取边界**：本操作把云端文档正文**拉进当前对话上下文**。遵循最小化——只读当前任务确需的文档、不批量拉全文；请求模糊或命中多目标时**先确认具体是哪一篇**再读；读取内容仅用于当前任务，不外传、不写入无关文件。\n\n- 关键参数：`nodeId`（文档 URL 或 dentryUuid）\n- 用途：读取文档内容、做差异对比后再更新、核对图片是否内联成功（返回 markdown 中可见 ``）\n- **仅适用于 `adoc` 文字文档**。调用前通过 `get_document_info` 或结果中的 `contentType` 确认类型\n- `axls`（钉钉表格）、`dlink`（快捷方式）及其他非 `adoc` 节点会报错或不提供正文，禁止将报错视为可重试错误\n- 对 `axls`，仅在当前会话确实提供表格读取工具时使用该工具；工具不可用时请用户粘贴所需内容或提供导出文件\n- 对 `dlink`，先解析其指向的原始 nodeId，再对原节点执行后续查询。检索结果按原始 nodeId 去重，优先保留原节点\n\n---\n\n## 块级精确编辑\n\n适用于需要在文档特定位置插入/修改/删除段落、标题、表格等场景。\n\n### list_document_blocks\n列出文档的一级块元素（段落、标题、表格等）。\n\n- 关键参数：`nodeId`（文档 URL 或 dentryUuid）、`startIndex`/`endIndex`（范围）、`blockType`（过滤）、`format`（element/jsonml，默认 element）\n- 返回：各块的 `blockId` 与 `index`，供 `update_document(index)` / insert / update / delete_document_block 定位使用\n- **图片块识别坑**：element 格式下，内联图片块表现为**空文本 paragraph**，与真空段落无法区分；核对图片请用 markdown 视图（`get_document_content`）或导出，不要依赖 element 列表\n\n### insert_document_block\n在文档指定位置插入新块元素。\n\n- 关键参数：`nodeId`、`element`（含 `blockType` 及对应属性对象）、定位用 `referenceBlockId`（优先）或 `index`、`where`（before/after，默认 after）、`format`（element/jsonml）\n- 支持类型：paragraph/heading/blockquote/callout/columns/orderedList/unorderedList/table/attachment 等\n- **行内 image 不可用**：`element.children` 的 `properties.src`（图片 Url）虽在 schema 中声明，但实测插入行内 image 会报 **\"Undefined block element\"**。**不要用本工具插图**，改走 markdown 导入链路（见「本地图片内联到文档正文」）\n- **attachment 的 `size` 必须省略**：`size`（number）经 MCP 桥接层会被序列化成字符串，报 **\"expected number, but got string\"**；插入 attachment 块时省略 size\n- **attachment 块 ≠ 内联图**：attachment 块导出为 `[文件名](链接)` 的附件卡片，不是内联图片；仅在图片内联链路中作为临时上传媒介，转存成功后即删除\n\n### update_document_block\n更新指定块元素的内容或样式。\n\n- 关键参数：`nodeId`、`blockId`、`element`（含 `blockType` 和属性对象）\n\n### delete_document_block\n删除指定块元素。\n\n- 关键参数：`nodeId`、`blockId`（支持逗号分隔批量删除，一次最多 50 个；未命中的列入返回的 `notFoundBlockIds`）\n- 需有编辑权限\n- **删后必须复核**：并行/连续删除曾出现「返回成功但未删或误删邻块」，删除后务必用 `list_document_blocks` 复核结果\n\n---\n\n## 文档/节点查找\n\n### search_documents\n按关键词搜索当前用户有权限访问的文档。\n\n- 关键参数：`keyword`（匹配标题和内容）、可选过滤条件（类型、时间范围等）\n- 用途：在不知道 dentryUuid 时定位目标文档\n\n### list_nodes\n列出指定文件夹或知识库下的直接子节点（文件夹/文档/文件）。\n\n- 关键参数：`folderId`（文件夹节点）或 `workspaceId`（知识库 ID）；分页用 `pageSize`（默认/最大 50）+ `pageToken`（首次不传）\n- 注意：**只返回直接子节点，不递归**；需要更深层列表时多次调用\n\n### get_document_info\n获取节点的元信息（标题、类型、创建者、创建时间等）。\n\n- 关键参数：`nodeId`（支持文档 URL 或 dentryUuid）\n- 返回的 `contentType` 字段可判断文档类型（adoc/sheet/ppt 等）\n\n---\n\n## 文件夹与节点管理\n\n### create_folder\n在指定位置创建文件夹，返回新文件夹的节点 ID。\n\n- 关键参数：`name`（文件夹名，必填）、`folderId`（父文件夹节点）或 `workspaceId`（知识库 ID；同时传 folderId 时以 folderId 为准，都不传建在\"我的文档\"根目录）\n\n### create_file\n创建各类型节点（文档、表格、演示、白板、脑图、多维表、文件夹）。\n\n- 支持三种创建位置（优先级顺序）：指定 folderId、指定 workspaceId、默认位置\n- 与 `create_document` 的区别：`create_file` 可创建所有类型，但不支持带初始内容\n\n### delete_document\n将节点移入回收站（30 天内可恢复，超过 30 天永久删除）。\n\n- 支持：知识库下的文档节点、文件夹节点、钉盘文件\n- **执行前需告知用户这是移入回收站，获得确认后再调用**\n\n### rename_document\n重命名节点（知识库下的文档/文件夹节点）。\n\n### move_document\n将节点移动到目标文件夹。\n\n- 支持：知识库节点、钉盘文件/文件夹\n- `nodeId` 支持文档 URL 或 dentryUuid\n\n### copy_document\n将节点复制到目标文件夹。\n\n- 与 `move_document` 参数相同，区别是原节点保留\n\n---\n\n## 文件上传（非 adoc 文件）\n\n上传本地文件（PDF、图片、Word 等）到钉钉文档/知识库，分三步：\n\n1. **get_file_upload_info** — 获取 OSS 上传凭证（第一步）\n2. **HTTP PUT** — 使用凭证将文件直传 OSS（Claude 代理发起 HTTP 请求）\n3. **commit_uploaded_file** — 提交完成文件入库（第三步）\n\n> ⚠️ **数据离开本地**：第 2 步 HTTP PUT 把**本地文件的原始字节直传到钉钉 OSS 云端存储**，不是纯本地操作。执行前须在确认摘要中明示「本地文件 `<名称>` 原始字节将上传到钉钉云端」，用户同意后再传；上传 URL 由钉钉官方接口签发，不接受手填任意 endpoint。\n\n### get_file_upload_info\n- 关键参数：`fileName`、`fileSize`、目标位置（folderId 或 workspaceId）\n\n### commit_uploaded_file\n- 关键参数：上传凭证中的 `uploadKey`\n\n---\n\n## 权限管理\n\n### add_permission\n为知识库节点添加企业用户成员（指定角色）。\n\n### update_permission\n修改企业用户在节点上的角色。\n\n### list_permission\n查询节点当前的成员权限列表。\n\n---\n\n## 导出\n\n将文档异步导出为 PDF 或 Word 等格式，分两步：\n\n> ⚠️ **数据扩散**：导出产生文档的**可移植副本**（PDF/Word/markdown），完成后的下载链接在时效内**任何持有者可访问**。提示用户副本的存储/分享/传播责任与风险自负，链接有时效、勿长期外发。\n\n### submit_export_job\n提交导出任务，返回 `jobId`。\n\n- 关键参数：`nodeId`（文档 URL 或 dentryUuid）、`exportFormat`（`docx` / `markdown` / `pdf`）\n- 返回：`jobId`，供轮询使用\n\n### query_export_job\n查询导出任务状态，直到完成为止。\n\n- 关键参数：`jobId`\n- 返回：任务状态；完成时包含下载链接\n- 注意：需轮询直至状态为成功，建议间隔 1-2 秒\n\n---\n\n## 附件操作\n\n### get_doc_attachment_upload_info\n获取向指定文档上传「文档内嵌附件」的 OSS 上传凭证。注意区别于 `get_file_upload_info`（后者是往知识库/钉盘放独立文件）：本工具绑定到某个文档 `nodeId`，是「本地图片内联」链路的第一步。\n\n- 关键参数：`nodeId`（文档 URL 或 dentryUuid）、`fileName`（含扩展名）、`fileSize`（字节，须与实际一致）、`mimeType`（如 `image/png`）\n- 返回：`uploadUrl`（OSS PUT 目标，有时效，尽快使用）+ `resourceId`\n- 随后对 `uploadUrl` 执行 HTTP PUT 上传**原始字节**，Header 带 `Content-Type: `、`Content-Length: `，须返回 **200**\n\n### download_doc_attachment\n获取文档内指定资源（`resourceId`）的临时**签名下载 URL**（OSS 公开可取）。\n\n- 关键参数：`nodeId`（文档 URL 或 dentryUuid）、`resourceId`（资源标识）\n- 返回：签名 `downloadUrl`\n- **实测补注（与官方 schema 前置说明不同）**：官方 schema 写「需先 `list_document_blocks` 找到 attachment 块再提取 resourceId」，但实测**任意经 `get_doc_attachment_upload_info` 上传过的 resourceId 都能直接取到签名 URL，无需 attachment 块存在**。「本地图片内联」链路正是利用这一点：上传 → 取签名 URL → 写进 markdown 让钉钉抓取转存，全程不落地 attachment 块\n\n### download_file\n获取钉盘文件的下载凭证，供 Claude 发起 HTTP GET 下载。\n\n> ⚠️ **数据扩散**：`download_doc_attachment` 的签名 URL 与 `download_file` 的下载凭证都会把云端内容取到本地或生成**临时可访问链接**，时效内任何持有者可访问；提示用户扩散风险与存储/分享责任自负。\n\n---\n\n## 本地图片内联到文档正文（推荐链路）\n\n把本地图片作为**内联图**嵌入 adoc 文档正文，区别于「作为独立文件上传到知识库/钉盘」（`get_file_upload_info` 三步流程）。适用场景：markdown 引用了本地相对路径图片、需要图片随文档一起在线渲染/评论/协作。\n\n**原理**：钉钉在 `create_document` / `update_document` 导入 markdown 时，会**自动抓取外部 https 图片 URL 的真字节并转存为文档自托管内联图**。因此只要能拿到一个钉钉 OSS 可公开访问的签名 URL，写入 `` 即可让图片内联。\n\n**链路（所有写操作严格串行）**：\n\n1. `get_doc_attachment_upload_info`(nodeId, fileName, fileSize, mimeType) → 拿 `uploadUrl` + `resourceId`\n2. HTTP PUT 图片**原始字节**到 `uploadUrl`，Header `Content-Type: `、`Content-Length: `，须返回 200\n3. `download_doc_attachment`(nodeId, resourceId) → 拿**签名下载 URL**（OSS 公开可取）\n4. `update_document`(mode=append, index=<目标位置>) 或 `create_document`，markdown 写入 `` → 钉钉导入器抓取真字节并转存为内联图\n5. **替换旧图（净零位移）**：先 append 新图到旧图所在 index，再按旧块 `blockId` 删除旧块——先加后删配对完成，避免连锁重算 index\n\n**不要依赖 `resourceUrl` 当图源（行为不稳定）**：`get_doc_attachment_upload_info` 返回的 `resourceUrl`（形如 `/core/api/resources/img/…`）实测行为取决于资源可达性——指向本文档刚上传、导入器可达的资源时可被正确解析为内联图（实测字节级一致）；但指向无权访问/跨文档/不可达的资源时，导入器抓取失败会存成「暂无权限访问」占位插画（≈42210 字节 PNG）。为消除这种不确定性，**统一只用 `download_doc_attachment` 返回的签名下载 URL**（实测 100% 转存成功）。\n\n**字节级验收（必做）**：\n1. 导出文档（`submit_export_job`）或用 `get_document_content` 取 markdown\n2. 下载新图的签名 URL\n3. 比对字节数是否等于原图 —— 相等即健康；若为 ≈42210 字节的占位图，说明误用了 `resourceUrl`\n4. 抽查 2-3 张即可，不必全量\n\n---\n\n## 已知陷阱速查（图片 / 块编辑）\n\n| 陷阱 | 现象 | 正确做法 |\n|---|---|---|\n| 用 `resourceUrl`（`/core/api/resources/img/…`）当 markdown 图源 | 行为不稳定：资源可达时能解析，无权/跨文档/不可达时抓取失败存成「暂无权限访问」占位插画（≈42210 字节 PNG） | 统一用 `download_doc_attachment` 的签名下载 URL（最可靠） |\n| `insert_document_block` 的行内 image（`children.src`） | 报 \"Undefined block element\"（schema 声明但实际不可用） | 不要尝试，走 markdown 导入链路 |\n| attachment 块传 `size` | 被 MCP 桥接层序列化为字符串，报 \"expected number, but got string\" | 省略 `size` |\n| 把 attachment 块当图片用 | 导出为 `[文件名](链接)`，是附件卡片不是内联图 | 仅作上传媒介，图片转存后即删 |\n| 并行写同一文档 | 报 \"unable to write to document concurrently\"；并行 delete 曾出现「返回成功但未删/误删邻块」 | 所有写操作严格串行；删后必须 `list_document_blocks` 复核 |\n| element 视图找图片块 | 图片块表现为空文本 paragraph，与真空段无法区分 | 用 markdown 视图（`get_document_content`）或导出核对 |\n| markdown 传字面量 `\\n` | 全文渲染在同一行，格式错乱 | 用真实换行符（U+000A） |\n\nFile v1.0.3:skill-card.md\n\n## Description:\n\nA DingTalk Docs agent skill for reading, creating, updating, exporting, downloading, and managing DingTalk cloud documents through the official dingtalk-doc MCP server.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cpsean](https://clawhub.ai/user/cpsean)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal developers and agent users use this skill to connect an MCP-capable agent to DingTalk Docs, push local Markdown or files into a knowledge base, sync or export cloud documents, and manage folders and permissions with confirmation before writes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A personal API-key URL may be persisted in agent configuration or exposed in chat or logs.\n\nMitigation: Use only an official HTTPS DingTalk MCP URL, prefer project-local configuration, do not commit or share MCP config files containing the URL, and rotate the URL if it was pasted or logged.\n\nRisk: MCP traffic could be directed to a non-DingTalk endpoint if endpoint checks are bypassed.\n\nMitigation: Approve only official DingTalk domains for MCP URLs and reject non-DingTalk endpoints before registering the server.\n\nRisk: Cloud document reads, downloads, exports, and uploads move data between the local environment and DingTalk and can create portable copies or temporary signed links.\n\nMitigation: Confirm write and transfer operations with the user, read only the documents needed for the task, disclose where data will go, and avoid long-term sharing of temporary download links.\n\n## Reference(s):\n\n- [DingTalk Docs MCP tool reference](references/mcp-tools.md)\n- [DingTalk AI Hub MCP page](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail)\n- [DingTalk Developer guide](https://open.dingtalk.com/document/dingstart/dingtalk-developer)\n- [DingTalk Docs](https://alidocs.dingtalk.com)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Shell commands, Configuration]\n\n**Output Format:** [Markdown with inline shell commands and configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May propose MCP tool calls and file-transfer workflows; write operations require user confirmation.]\n\n## Skill Version(s):\n\n1.0.3 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.3:evals/evals.json\n\n{\n \"skill_name\": \"dingtalk-docs-skill\",\n \"evals\": [\n {\n \"id\": 1,\n \"prompt\": \"我有一个本地文件 weekly-report.md，内容是本周工作总结，帮我把它推送到钉钉知识库，放在「周报」文件夹下，标题叫「2026-W18 周报」。\",\n \"expected_output\": \"调用 list_nodes 或 search_documents 找到「周报」文件夹的 nodeId，然后调用 create_document 创建文档，读取 weekly-report.md 内容作为 content 参数，最后返回文档标题和访问链接。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 create_document MCP 工具\",\n \"文档标题包含「2026-W18 周报」\",\n \"输出包含文档访问链接或 dentryUuid\",\n \"没有跳过定位父文件夹的步骤\"\n ]\n },\n {\n \"id\": 2,\n \"prompt\": \"帮我更新钉钉上的「产品需求文档 v2」，把本地的 prd-v2.md 内容覆盖上去。\",\n \"expected_output\": \"先调用 search_documents 找到目标文档的 dentryUuid，确认文档类型是 adoc，然后调用 update_document 以 overwrite 模式更新内容，最后返回更新结果和文档链接。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 search_documents 或 get_document_info 定位文档\",\n \"调用了 update_document 且 updateMode 为 overwrite\",\n \"输出包含操作成功的确认信息\"\n ]\n },\n {\n \"id\": 3,\n \"prompt\": \"帮我配置钉钉文档 MCP，我现在是第一次用。\",\n \"expected_output\": \"输出初始化引导步骤：提供开通链接、说明需要登录并开通服务、说明复制 StreamableHttp URL、说明后续 Claude 会写入 settings.json。不调用任何 MCP 文档工具。\",\n \"files\": [],\n \"assertions\": [\n \"输出包含 aihub.dingtalk.com 开通链接\",\n \"说明需要复制 StreamableHttp URL\",\n \"提到需要重启 Claude Code\",\n \"没有尝试直接调用 create_document 等文档操作工具\"\n ]\n },\n {\n \"id\": 4,\n \"prompt\": \"列出钉钉知识库根目录下的所有文档。\",\n \"expected_output\": \"调用 list_nodes 并传入知识库根节点 ID（如果用户未提供则先询问或说明需要知识库 ID），返回文档节点列表（标题、类型、节点 ID）。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 list_nodes MCP 工具\",\n \"如果缺少知识库 ID 则向用户说明而不是猜测\",\n \"输出展示了文档列表或明确说明缺少必要参数\"\n ]\n },\n {\n \"id\": 5,\n \"prompt\": \"读取知识库里的「2026 绩效表」并总结重点。该节点的 contentType 是 axls，但当前 MCP 只安装了文档工具，没有表格读取工具。\",\n \"expected_output\": \"确认节点类型为 axls，不调用或重试 get_document_content，也不调用报错中提到但当前未安装的工具；明确请用户粘贴需要分析的表格内容，或提供导出的文件。\",\n \"files\": [],\n \"assertions\": [\n \"没有调用 get_document_content\",\n \"没有臆造或调用未安装的表格 MCP 工具\",\n \"请求用户粘贴表格内容或提供导出文件\"\n ]\n },\n {\n \"id\": 6,\n \"prompt\": \"搜索「项目计划」后读取结果。搜索结果中同时有原文档 nodeId=doc-1 和一个 dlink 快捷方式，快捷方式指向的原始 nodeId 也是 doc-1。\",\n \"expected_output\": \"按原始 nodeId 对结果去重，优先保留原文档；只对保留的原节点确认类型并在它是 adoc 时调用 get_document_content，不直接读取 dlink。\",\n \"files\": [],\n \"assertions\": [\n \"按原始 nodeId 对 dlink 和原节点去重\",\n \"没有对 dlink 调用 get_document_content\",\n \"后续操作使用原节点 nodeId\"\n ]\n },\n {\n \"id\": 7,\n \"prompt\": \"把本地文件 landing-page.html 推送到钉钉知识库的「设计交付」文件夹。\",\n \"expected_output\": \"定位「设计交付」文件夹并在用户确认后，将 landing-page.html 作为原始 HTML 文件走 get_file_upload_info、HTTP PUT、commit_uploaded_file 上传，不转换为 Markdown 或创建 adoc。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 get_file_upload_info 和 commit_uploaded_file\",\n \"没有调用 create_document\",\n \"保留 HTML 原始格式和文件名\"\n ]\n },\n {\n \"id\": 8,\n \"prompt\": \"把截图 release-dashboard.png 上传到默认钉钉知识库。\",\n \"expected_output\": \"在用户确认后，将 PNG 原文件走三步文件上传流程上传到默认知识库，不创建 adoc 文档。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 get_file_upload_info 和 commit_uploaded_file\",\n \"没有调用 create_document\",\n \"使用原始 PNG 文件上传\"\n ]\n },\n {\n \"id\": 9,\n \"prompt\": \"把本地 architecture.md 推送到钉钉知识库。文件正文约 12,500 个字符，用户没有说明需要在线编辑还是仅存档。\",\n \"expected_output\": \"识别原始文件为 Markdown 且超过 adoc 单次 10,000 字符上限，先推荐用户选择“分段创建并追加 adoc”或“原样上传 .md 文件”；在用户选择方案前不执行创建、上传或获取上传凭证。\",\n \"files\": [],\n \"assertions\": [\n \"说明 Markdown 默认优先创建 adoc，但当前内容超过单次字符上限\",\n \"提供分段 adoc 与原样上传 MD 两个选项\",\n \"在用户选择前没有调用 create_document、get_file_upload_info 或 commit_uploaded_file\"\n ]\n },\n {\n \"id\": 10,\n \"prompt\": \"把本地交付文件推送到钉钉知识库。文件没有扩展名，用户也没有说明要保留原格式还是转成在线文档。\",\n \"expected_output\": \"先识别可用的只读文件信息，并向用户确认要创建在线可编辑 adoc 还是原样上传文件；在推送方案明确前不执行任何创建或上传步骤。\",\n \"files\": [],\n \"assertions\": [\n \"向用户确认推送方案\",\n \"没有擅自转换文件格式\",\n \"在方案确认前没有调用 create_document、get_file_upload_info、HTTP PUT 或 commit_uploaded_file\"\n ]\n },\n {\n \"id\": 11,\n \"prompt\": \"把本地 report.md 推送到钉钉知识库，正文里引用了 3 张本地图片（如 ./img/a.png），要求图片在钉钉文档里能正常显示。\",\n \"expected_output\": \"识别到 markdown 引用本地相对路径图片需要内联，而非当作独立文件上传。对每张图走内联链路：get_doc_attachment_upload_info 上传拿 resourceId → HTTP PUT 原始字节 → download_doc_attachment 取签名下载 URL → 用 create_document/update_document 写入 ，由钉钉自动抓取转存为内联图。所有写操作串行执行；推送后做字节级校验（下载新图签名 URL 比对字节数等于原图）。不使用 resourceUrl 当图源，不使用占位符人工粘贴。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 get_doc_attachment_upload_info 上传本地图片\",\n \"用 download_doc_attachment 获取的签名下载 URL 作为 markdown 图源\",\n \"没有使用 /core/api/resources/img/ 形式的 resourceUrl 当图源\",\n \"所有写操作串行执行，没有并行写同一文档\",\n \"推送后进行了字节级或 markdown 图片校验\"\n ]\n },\n {\n \"id\": 12,\n \"prompt\": \"在钉钉文档第 3 个块的位置插入一张本地图片 screenshot.png。\",\n \"expected_output\": \"不使用 insert_document_block 的行内 image（children.src），因为实测会报“Undefined block element”。改走内联链路：get_doc_attachment_upload_info 上传图片取签名 URL，再用 update_document(mode=append, index=3) 写入 。index 语义为插入到第 3 个块之前，插入成功后其后所有块 index 依次 +1。\",\n \"files\": [],\n \"assertions\": [\n \"没有用 insert_document_block 插入行内 image 元素\",\n \"走 get_doc_attachment_upload_info → download_doc_attachment → update_document 内联链路\",\n \"正确使用 update_document 的 index 定位（插入到指定块之前）\"\n ]\n },\n {\n \"id\": 13,\n \"prompt\": \"之前推送到钉钉的文档里有几张图片全部显示“暂无权限访问”的占位插画，帮我修复。\",\n \"expected_output\": \"诊断为误用了 resourceUrl 当图源，导致导入器抓取到占位插画（约 42210 字节 PNG）。修复方案：对每张原图重新走内联链路取 download_doc_attachment 的签名下载 URL；替换时先 append 新图到旧图所在 index，再按旧块 blockId 删除旧块（净零位移，先加后删配对）；所有写操作串行，删后用 list_document_blocks 复核。执行前展示确认摘要并注明“将删除 N 个块并重插 N 张图”，收到确认后再操作；修复后做字节级校验。\",\n \"files\": [],\n \"assertions\": [\n \"诊断出占位插画是误用 resourceUrl 当图源导致\",\n \"改用 download_doc_attachment 的签名下载 URL 重新内联\",\n \"替换采用先加后删配对（append 新图到旧 index + 按 blockId 删旧块）\",\n \"执行前给出确认摘要并注明删除/重插的块数量\",\n \"所有写操作串行且删后用 list_document_blocks 复核\"\n ]\n }\n ]\n}\n\nFile v1.0.3:evals/trigger-evals.json\n\n{\n \"skill_name\": \"dingtalk-docs-skill\",\n \"evals\": [\n {\n \"query\": \"帮我把这个 markdown 文件推送到钉钉文档\",\n \"should_trigger\": true\n },\n {\n \"query\": \"更新钉钉上的周报文档，用本地最新版本覆盖\",\n \"should_trigger\": true\n },\n {\n \"query\": \"列出我的钉钉知识库里有哪些文档\",\n \"should_trigger\": true\n },\n {\n \"query\": \"在钉钉文档里搜索项目计划\",\n \"should_trigger\": true\n },\n {\n \"query\": \"初始化钉钉文档 MCP 配置\",\n \"should_trigger\": true\n },\n {\n \"query\": \"在钉钉知识库里创建一个新文件夹叫「产品设计」\",\n \"should_trigger\": true\n },\n {\n \"query\": \"把这篇技术文档同步到钉钉知识库\",\n \"should_trigger\": true\n },\n {\n \"query\": \"把这个带本地图片的 markdown 推送到钉钉文档，图片要能正常显示\",\n \"should_trigger\": true\n },\n {\n \"query\": \"帮我在钉钉文档正文里插入几张本地截图\",\n \"should_trigger\": true\n },\n {\n \"query\": \"钉钉文档里的图片都显示“暂无权限访问”，帮我修一下\",\n \"should_trigger\": true\n },\n {\n \"query\": \"帮我把这个文件推送到语雀\",\n \"should_trigger\": false\n },\n {\n \"query\": \"帮我编辑本地的 README.md，修改第三段\",\n \"should_trigger\": false\n },\n {\n \"query\": \"给钉钉群里发一条消息通知大家\",\n \"should_trigger\": false\n },\n {\n \"query\": \"帮我把文档上传到飞书知识库\",\n \"should_trigger\": false\n },\n {\n \"query\": \"把这个 md 文件格式化一下，不需要上传\",\n \"should_trigger\": false\n }\n ]\n}\n\nArchive v1.0.2: 11 files, 17726 bytes\n\nFiles: .gitignore (99b), evals (0b), evals/evals.json (2542b), evals/trigger-evals.json (1350b), LICENSE (1063b), README.md (8443b), references (0b), references/mcp-tools.md (5449b), skill-card.md (2764b), SKILL.md (15036b), _meta.json (138b)\n\nFile v1.0.2:SKILL.md\n\n---\nname: dingtalk-docs-skill\ndescription: 当用户想要操作钉钉文档时使用本 Skill。支持：推送本地 markdown 到钉钉知识库、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。\nlicense: MIT\ncompatibility: Requires dingtalk-doc MCP server (StreamableHttp transport). Compatible with any MCP-capable agent (Claude Code, Cursor, VS Code, Roo Code, Gemini CLI, Codex, etc.). Auto-detects Claude Code; falls back to writing config files or manual setup for other agents.\n---\n\n# 钉钉文档\n\n通过钉钉文档官方 MCP Server 全面操作云端文档。\n\n## 语言规则\n\n**始终使用用户输入的语言进行回复。** 如果用户用英文提问，则全程用英文回复；如果用户用中文，则全程用中文回复。无法判断时默认使用中文。\n\n## 能力范围\n\n**读**\n- 拉取云端文档正文为 markdown（保存到本地）\n- 列出知识库/文件夹下的文档节点\n- 按关键词搜索文档\n- 获取文档元信息（标题、类型、创建时间等）\n- 下载钉盘文件或文档内嵌附件\n\n**写**\n- 将本地 markdown 推送为钉钉文档（adoc 类型）\n- 覆盖或追加内容到已有文档\n- 按块精确编辑（插入/更新/删除段落、标题、表格等）\n- 上传本地文件（PDF、图片、Word 等）到知识库\n\n**管理**\n- 创建文件夹\n- 重命名/移动/复制/删除文档和文件夹\n- 导出文档为 PDF 或 Word 格式\n- 查看/添加/修改知识库节点的成员权限\n\n**不负责：**\n- 飞书、语雀、Notion 等其他平台\n- 只修改本地文件（无云端操作）\n- 钉钉 IM 消息、企业成员管理\n\n## 前置条件\n\n钉钉文档 MCP Server 必须已配置到当前 Agent 的 MCP 设置中，服务名称为 `dingtalk-doc`。\n\n如果 MCP 工具不可用，先走**初始化流程**，再执行任何文档操作。\n\n## 初始化流程（首次使用或 MCP 不可用时）\n\n1. 告知用户访问帮助手册页面并完成开通：\n > 请打开以下链接，使用钉钉账号登录后，点击页面上的【开通服务】按钮：\n > https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail\n\n2. 开通后复制页面右侧 **StreamableHttp URL**（不是 JSON Config）\n\n3. 请用户将 URL 粘贴给你\n\n4. 收到 URL 后，按以下顺序尝试注册 MCP 服务（`dingtalk-doc` 为服务名，必须为 ASCII）：\n\n **方案 A — Claude Code**（优先尝试，运行命令看是否成功）：\n ```bash\n claude mcp add --transport http --scope user dingtalk-doc \"<用户提供的 URL>\"\n ```\n 成功则跳到步骤 5。\n\n **方案 B — 写入配置文件**（通用方案，大多数 Agent 均可用）：\n\n 检测当前环境存在哪些配置文件，找到第一个匹配项写入：\n\n | Agent | 配置文件（全局） | 配置文件（项目级） | `mcpServers` 键名 |\n |-------|---------------|----------------|-----------------|\n | Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | `mcpServers` |\n | VS Code Copilot | `~/Library/Application Support/Code/User/mcp.json`（Mac）
`%APPDATA%\\Code\\User\\mcp.json`（Win） | `.vscode/mcp.json` | `servers` |\n | Roo Code | — | `.roo/mcp.json` | `mcpServers` |\n | Gemini CLI | `~/.gemini/settings.json` | — | `mcpServers` |\n | OpenAI Codex | `~/.codex/config.json` | — | `mcpServers` |\n\n 向目标文件追加（若文件已有 `mcpServers`/`servers`，只添加新条目，不覆盖原有内容）：\n\n ```json\n {\n \"mcpServers\": {\n \"dingtalk-doc\": {\n \"type\": \"http\",\n \"url\": \"<用户提供的 URL>\"\n }\n }\n }\n ```\n > VS Code Copilot 的 `.vscode/mcp.json` 使用 `\"servers\"` 而非 `\"mcpServers\"`，写入时注意区分。\n\n 成功写入则跳到步骤 5。\n\n **方案 C — 手动兜底**（方案 A/B 均不适用时）：\n\n 向用户展示以下信息，请其参照所用 Agent 的文档手动添加 MCP 服务，完成后回来继续：\n ```\n 传输类型：StreamableHttp（HTTP）\n 服务名称：dingtalk-doc\n URL：<用户提供的 URL>\n ```\n 用户手动配置完成后，本 Skill 只需确认 MCP 工具可用即可继续。\n\n > URL 中含有个人 API Key，写入配置后不要在回复中重复显示完整 URL。\n\n5. 询问用户的默认知识库地址：\n > 请在浏览器中打开你常用的钉钉知识库，把地址栏的 URL 粘贴给我（格式类似 `https://alidocs.dingtalk.com/i/spaces/xxxxx/overview`）。\n > 如果暂时不设默认知识库，可以跳过，后续每次操作时再指定。\n\n6. 收到知识库 URL 后，写入 `references/dingtalk.config`：\n ```\n DINGTALK_DEFAULT_WORKSPACE_URL=<用户提供的知识库 URL>\n ```\n 此文件已被 `.gitignore` 排除，不会进入版本控制。无需重启，下次操作时直接读取生效。\n\n7. MCP 配置写入后，提示用户重启 Agent 客户端以使 MCP 生效，重启后回来继续操作即可。\n\n### 使用默认知识库\n\n- 当用户说\"列出我的知识库文档\"、\"推送到知识库\"等未指明位置的操作时，优先使用默认知识库 URL\n- **读取顺序**：① 读取 `references/dingtalk.config` 中的 `DINGTALK_DEFAULT_WORKSPACE_URL`；② 若文件不存在或值为空，检查环境变量 `$DINGTALK_DEFAULT_WORKSPACE_URL`（兼容已有 Claude Code 配置）；③ 两者均无则询问用户\n- 获得 URL 后，调用 `get_document_info` 传入该 URL 解析出 nodeId，再用 nodeId 调用 `list_nodes` 或作为 `parentNodeId`\n\n### 更改默认知识库\n\n当用户说\"更换默认知识库\"、\"修改知识库地址\"等时：\n\n1. 请用户在浏览器打开目标钉钉知识库，复制地址栏 URL\n2. 收到新 URL 后，覆盖写入 `references/dingtalk.config`：\n ```\n DINGTALK_DEFAULT_WORKSPACE_URL=<新的知识库 URL>\n ```\n3. 无需重启，下次操作时读取新值即生效\n\n### 安全规则\n\n- MCP 服务 URL 含有个人 API Key，**不得出现在任何版本控制文件中**；写入配置后不要在回复中重复显示完整 URL\n- `references/dingtalk.config` 保存知识库 URL，已被 `.gitignore` 排除，不会提交到版本控制\n- 如果用户将 URL 粘贴到聊天中，立即写入配置后不再引用\n\n## 默认路径\n\n1. 确认 MCP 工具可用（若不可用，进入初始化流程）\n2. 理解用户意图，映射到对应 MCP 工具（见工具映射表）\n3. 如需要 dentryUuid/nodeId 但用户未提供：优先读取 `references/dingtalk.config`（或环境变量 `$DINGTALK_DEFAULT_WORKSPACE_URL`）获取默认知识库 URL，调用 `get_document_info` 解析出 nodeId；否则调用 `search_documents` 或 `list_nodes` 定位目标，让用户确认后再操作\n4. **执行前确认**（只读操作除外，见下方说明）：向用户展示操作摘要，收到明确同意后再调用 MCP 工具\n5. 执行操作\n6. 报告结果：操作类型、文档标题、文档链接（如有）\n\n### 执行前确认规则\n\n**需要确认的操作**（所有会写入或修改云端数据的操作）：\n`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`\n\n**无需确认的操作**（只读）：\n`search_documents`、`list_nodes`、`get_document_info`、`get_document_content`、`list_document_blocks`、`list_permission`、`query_export_job`、`download_file`、`download_doc_attachment`\n\n**确认摘要格式**（根据操作类型调整）：\n\n```\n即将执行以下操作，请确认：\n\n操作：<创建 / 更新（覆盖）/ 更新（追加）/ 删除 / 重命名 / 移动 / 复制 / 创建文件夹>\n目标：<文档标题或文件夹名>\n位置：<知识库名或文件夹路径>\n说明：<一句话描述本次变更，例如\"将以本地文件 xxx.md 的内容覆盖云端文档全文\">\n\n确认请回复「是」或「确认」，取消请回复「否」或「取消」。\n```\n\n收到取消时：停止操作，不重试，告知用户已取消。\n\n## MCP 工具映射\n\n详见 `references/mcp-tools.md`。常用映射如下：\n\n| 用户意图 | MCP 工具 |\n|---------|---------|\n| 推送/创建文档（含 markdown 内容） | `create_document` |\n| 拉取云端文档内容到本地 | `get_document_content` |\n| 覆盖或追加文档内容 | `update_document` |\n| 精确块级编辑（段落/标题/表格等） | `list_document_blocks` → `insert/update/delete_document_block` |\n| 列出知识库/文件夹下的文档 | `list_nodes` |\n| 按关键词搜索文档 | `search_documents` |\n| 获取文档元信息（标题、类型等） | `get_document_info` |\n| 下载钉盘文件 | `download_file` |\n| 下载文档内嵌附件 | `download_doc_attachment` |\n| 导出文档为 PDF/Word | `submit_export_job` → `query_export_job`（轮询至完成）|\n| 创建文件夹 | `create_folder` |\n| 删除文档节点 | `delete_document` |\n| 重命名节点 | `rename_document` |\n| 移动节点到其他文件夹 | `move_document` |\n| 复制节点到其他文件夹 | `copy_document` |\n| 查看节点成员权限 | `list_permission` |\n| 添加/修改节点成员权限 | `add_permission` / `update_permission` |\n\n## 失败处理\n\n- **MCP 工具不可用**：停止，进入初始化流程，不要猜测或尝试其他方式调用\n- **未提供目标文档**：先用 `search_documents` 或 `list_nodes` 找到目标，让用户确认后再操作\n- **update_document 报错**：确认目标是否为 adoc（文字类型）文档，非 adoc 文档不支持此操作\n- **delete_document 前**：确认摘要中必须注明\"将移入回收站，30 天内可恢复\"，收到确认后再执行\n- **API 报错（权限/鉴权类）**：当 API 返回权限不足、无权限、鉴权失败、Forbidden、Unauthorized 等错误时，除了展示原文错误信息外，提示用户可能尚未开通所在组织的钉钉开发者权限，引导用户参考以下链接完成开通：\n > 请访问钉钉开发者入门文档，确认你已在所在组织中开通了开发者权限：\n > https://open.dingtalk.com/document/dingstart/dingtalk-developer\n >\n > 开通步骤简述：登录钉钉开放平台 → 选择对应组织 → 完成开发者认证/开通。完成后重新尝试操作。\n- **其他 API 报错**：原文展示错误信息，不猜测原因，不自动重试\n\n## 关键约束\n\n- `update_document` 和 `create_document` 仅支持 **adoc（文字类型）** 文档，不支持表格、演示、脑图等\n- `create_document` 和 `update_document` 的 `markdown` 参数上限均为 **10,000 字符**；超出会报 `invalidRequest.inputArgs.invalid` 错误。推送前应先估算内容字符数，超过 **9,500 字符**（留余量）时走大文档推送策略（见下文）\n- `delete_document` 是移入回收站，不是永久删除，30 天内可从回收站恢复\n- `list_nodes` 只返回直接子节点，不递归。需要深层列表时需要多次调用\n- **导出为异步操作**：`submit_export_job` 返回 jobId 后需轮询 `query_export_job` 直到状态完成，再将下载链接告知用户；轮询间隔建议 1-2 秒\n- **Mermaid 文本绘图**：通过 `create_document` 推送的 ` ```mermaid ` 代码块会被解析为普通代码块，而非钉钉原生文本绘图块。钉钉的文本绘图是私有块类型，API 层未暴露，无法通过 MCP 创建或转换。推送前告知用户此限制，建议推送后在钉钉编辑器中手动将代码块转换为文本绘图\n- 操作完成后，从返回值中提取文档链接告知用户，方便直接点击查看\n\n## 对话中上传文件的处理\n\n用户可能在对话中直接上传 markdown 文件并要求推送到钉钉。\n\n### 已知限制\n\n- 对话上传的文件内容是**临时的**，不会持久保存到磁盘，上下文压缩或会话结束后内容即丢失\n- **非 ASCII 文件（如中文 markdown）通过对话上传时，0x80-0x9F 范围的字节会被文本处理层丢弃，导致不可逆乱码**。这是客户端文本传输的固有限制，编码修复无法还原丢失的字节\n\n### 处理规则\n\n1. **优先使用本地文件路径**：当用户要推送含非 ASCII 内容（中文、日文等）的文件时，请用户提供本地磁盘路径，直接读取文件内容，避免编码问题\n2. **对话上传的文件先检查编码**：如果用户直接在对话中上传了文件，先检查内容是否出现乱码。如果存在乱码，立即告知用户并请其提供本地文件路径\n3. **纯 ASCII 内容可直接处理**：如果上传的文件内容全是 ASCII（英文、代码等），可以直接处理，在同一轮回复中完成：读取内容 -> 确认摘要 -> （用户确认后）调用 `create_document`\n4. **文档命名**：默认使用上传文件名（去掉扩展名）作为钉钉文档标题。如果用户要求修改名字，按用户指定的名字创建\n5. **仅支持 markdown / 纯文本**：对话上传的二进制文件（PDF、图片、Word 等）当前不支持直接推送，需要用户提供本地磁盘路径后走文件上传三步流程\n\n## 大文档推送策略\n\n当需要将本地 markdown 文件推送为钉钉在线文档（adoc）时，**推送前先估算内容字符数**。超过 **9,500 字符** 时，单次 `create_document` 必然失败，需主动告知用户并让其选择方案：\n\n### 方案 A — 分段推送（生成可在线编辑的 adoc）\n\n1. 按 `## ` / `### ` 标题边界将内容切分为若干段，每段 ≤ 9,500 字符，避免在表格中间切断\n2. 用 `create_document` 写入第 1 段（含标题）\n3. 依次用 `update_document`（`append` 模式）追加后续各段，每段单独一次调用\n4. 全部追加完成后报告文档链接\n\n**适合场景**：用户需要在钉钉在线编辑、评论、协作，或希望文档格式被渲染\n\n### 方案 B — 上传原始 .md 文件（存入钉盘）\n\n走三步文件上传流程：`get_file_upload_info` → HTTP PUT → `commit_uploaded_file`\n\n**适合场景**：只需存档或分享下载，不需要在线编辑；操作更简单，文件完整保留原格式\n\n### 推荐选择\n\n向用户说明两个方案后，推荐如下：\n\n> 如果你需要在钉钉里直接编辑或与同事协作，推荐方案 A（分段推送）；如果只是存档或分享，推荐方案 B（上传文件）。\n\n收到用户选择后再执行，不要擅自决定。\n\n---\n\n## 资源导航\n\n- `references/mcp-tools.md` — 全部 MCP 工具详细说明，按场景分组\n\nFile v1.0.2:README.md\n\n# dingtalk-docs-skill\n\n[English](#english) | [中文](#中文)\n\n---\n\n## 中文\n\n**dingtalk-docs-skill** 是一个兼容多平台的 Agent Skill，通过钉钉文档官方 MCP Server 全面操作钉钉云端文档，支持读取、推送、同步、导出、权限管理等。\n\n### 功能\n\n| 类别 | 能力 |\n|------|------|\n| **读** | 拉取云端文档正文为 markdown、列出知识库/文件夹文档、按关键词搜索、获取文档元信息、下载钉盘文件与文档附件 |\n| **写** | 推送本地 markdown 到钉钉、覆盖/追加更新文档内容、块级精确编辑（段落/标题/表格等）、上传本地文件（PDF/图片/Word 等） |\n| **管理** | 创建文件夹、重命名/移动/复制/删除文档和文件夹、导出文档为 PDF/Word、管理节点成员权限 |\n\n所有操作通过[钉钉官方 MCP Server](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) 完成，无需本地脚本，API Key 不会写入代码。\n\n### 快速开始\n\n**1. 安装 Skill**\n\n**用户级安装**（推荐，所有项目均可使用）：\n\nmacOS / Linux：\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n ~/.claude/skills/dingtalk-docs-skill\n```\n\nWindows（PowerShell）：\n```powershell\ngit clone https://github.com/CPsean/dingtalk-docs-skill `\n \"$env:USERPROFILE\\.claude\\skills\\dingtalk-doc\"\n```\n\n**项目级安装**（仅当前项目可用）：\n\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n .claude/skills/dingtalk-docs-skill\n```\n\n安装后重启 Claude Code 使 Skill 生效。\n\n**2. 开通钉钉文档 MCP 服务**\n\n首次使用时，Skill 会引导你完成配置：\n\n1. 打开[钉钉 AI Hub MCP 页面](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail)，登录钉钉账号，点击【开通服务】\n2. 复制页面右侧的 **StreamableHttp URL**（不是 JSON Config）\n3. 将 URL 粘贴给 Claude\n\nSkill 会自动注册 MCP 服务。Claude Code 客户端执行：\n\n```bash\nclaude mcp add --transport http --scope user dingtalk-doc \"<你的 URL>\"\n```\n\n其他客户端（Claude Desktop、Cursor 等）需手动配置 StreamableHttp 类型的 MCP 服务。\n\n**3.（可选）设置默认知识库**\n\n提供你常用的知识库 URL，后续操作无需每次指定：\n\n```\nhttps://alidocs.dingtalk.com/i/spaces/xxxxx/overview\n```\n\n### 使用示例\n\n直接用自然语言和 Claude 对话即可：\n\n- *\"把 `docs/design.md` 推送到我的钉钉知识库\"*\n- *\"用本地最新版本更新钉钉上的 PRD 文档\"*\n- *\"列出我知识库里的所有文档\"*\n- *\"在钉钉文档里搜索「认证」\"*\n- *\"把会议纪要从钉钉拉取到本地\"*\n- *\"删除钉钉上的测试文档\"*\n\n### 工作流程\n\n```\n用户请求\n → Skill 激活（通过 description 触发词匹配）\n → MCP 工具映射（create / update / list / search / delete ...）\n → 执行前确认（所有写操作需用户确认）\n → 钉钉文档 MCP Server\n → 返回结果：文档标��� + 链接\n```\n\n### 已知限制\n\n| 限制项 | 详情 |\n|---|---|\n| **Mermaid 流程图** | ` ```mermaid ` 代码块推送后显示为普通代码块，而非钉钉原生「文本绘图」。推送后需在钉钉编辑器中手动转换。 |\n| **对话上传文件编码** | 非 ASCII 文件（中文等）通过对话上传时可能出现不可逆乱码。请始终提供**本地文件路径**。 |\n| **文档类型** | `create_document` 和 `update_document` 仅支持 **adoc**（文字类型）文档。 |\n| **删除** | 移入回收站（30 天内可恢复），非永久删除。 |\n\n### 安全性\n\n- MCP 服务 URL 包含个人 API Key，仅写入本地配置，**不会提交到版本控制**\n- 所有写操作执行前都需要用户明确确认\n\n### 文件结构\n\n```\n.claude/skills/dingtalk-docs-skill/\n├── SKILL.md # Skill 入口（触发器 + 指令）\n├── README.md # 本文件\n├── evals/\n│ ├── evals.json # 任务执行测评\n│ └── trigger-evals.json # 触发边界测评\n└── references/\n └── mcp-tools.md # MCP 工具速查表\n```\n\n---\n\n## English\n\n**dingtalk-docs-skill** is a cross-platform Agent Skill for reading, pushing, syncing, exporting, and managing documents on [DingTalk Docs](https://alidocs.dingtalk.com) via the official DingTalk Document MCP Server.\n\n### Features\n\n| Category | Capabilities |\n|----------|-------------|\n| **Read** | Pull cloud document content as markdown, list knowledge base / folder nodes, search by keyword, get document metadata, download DingTalk Drive files and attachments |\n| **Write** | Push local markdown to DingTalk, overwrite / append document content, block-level precise editing (paragraphs, headings, tables, etc.), upload local files (PDF, images, Word, etc.) |\n| **Manage** | Create folders, rename / move / copy / delete documents and folders, export documents to PDF or Word, manage node member permissions |\n\nAll operations go through [DingTalk's official MCP Server](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) — no local scripts or API keys in code.\n\n### Quick Start\n\n**1. Install the Skill**\n\n**User-level install** (recommended — available across all projects):\n\nmacOS / Linux:\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n ~/.claude/skills/dingtalk-docs-skill\n```\n\nWindows (PowerShell):\n```powershell\ngit clone https://github.com/CPsean/dingtalk-docs-skill `\n \"$env:USERPROFILE\\.claude\\skills\\dingtalk-doc\"\n```\n\n**Project-level install** (current project only):\n\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n .claude/skills/dingtalk-docs-skill\n```\n\nRestart Claude Code after installing to load the skill.\n\n**2. Enable the DingTalk Document MCP Server**\n\nOn first use, the skill will guide you through setup:\n\n1. Open the [DingTalk AI Hub MCP page](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) and activate the service\n2. Copy the **StreamableHttp URL** from the page\n3. Paste it into the Claude conversation\n\nThe skill automatically registers the MCP server. For Claude Code:\n\n```bash\nclaude mcp add --transport http --scope user dingtalk-doc \"\"\n```\n\nFor other clients (Claude Desktop, Cursor, etc.), configure a StreamableHttp MCP server manually.\n\n**3. (Optional) Set a Default Knowledge Base**\n\nProvide your knowledge base URL so you don't have to specify it every time:\n\n```\nhttps://alidocs.dingtalk.com/i/spaces/xxxxx/overview\n```\n\n### Usage Examples\n\nJust talk to Claude naturally:\n\n- *\"Push `docs/design.md` to my DingTalk knowledge base\"*\n- *\"Update the PRD document on DingTalk with the latest local version\"*\n- *\"List all documents in my knowledge base\"*\n- *\"Search DingTalk docs for 'authentication'\"*\n- *\"Pull the meeting notes from DingTalk to local\"*\n- *\"Delete the test document from DingTalk\"*\n\n### How It Works\n\n```\nUser request\n → Skill activation (matched by description trigger)\n → MCP tool mapping (create / update / list / search / delete ...)\n → Pre-execution confirmation (for all write operations)\n → DingTalk Document MCP Server\n → Result: document title + link\n```\n\n### Known Limitations\n\n| Limitation | Detail |\n|---|---|\n| **Mermaid diagrams** | ` ```mermaid ` blocks are pushed as plain code blocks, not DingTalk's native \"text drawing\" blocks. Manually convert after pushing. |\n| **File encoding on chat upload** | Non-ASCII files (Chinese, etc.) uploaded through the chat may suffer irreversible garbled text. Always provide a **local file path**. |\n| **Document types** | `create_document` and `update_document` only support **adoc** (text document) type. |\n| **Deletion** | Moves to trash (recoverable within 30 days), not permanent deletion. |\n\n### Security\n\n- The MCP server URL contains a personal API key — written to local config only, **never committed to version control**\n- All write operations require explicit user confirmation before execution\n\n### File Structure\n\n```\n.claude/skills/dingtalk-docs-skill/\n├── SKILL.md # Skill entry point (trigger + instructions)\n├── README.md # This file\n├── evals/\n│ ├── evals.json # Task execution evals\n│ └── trigger-evals.json # Trigger boundary evals\n└── references/\n └── mcp-tools.md # MCP tool reference\n```\n\n### License\n\nMIT\n\nFile v1.0.2:_meta.json\n\n{\n \"ownerId\": \"kn7facsvhzy0pcacszzatx32th87jknt\",\n \"slug\": \"dingtalk-docs-skill\",\n \"version\": \"1.0.2\",\n \"publishedAt\": 1788162697093\n}\n\nFile v1.0.2:references/mcp-tools.md\n\n# 钉钉文档 MCP 工具速查\n\nMCP 名称：`dingtalk-doc`（注册方式见 SKILL.md 初始化流程）\n\n---\n\n## 文档内容操作\n\n### create_document\n创建文字类型（adoc）钉钉文档，支持带初始 markdown 内容。\n\n- 关键参数：`title`（标题）、`content`（markdown 正文）、`parentNodeId`（父节点 ID，指定放置位置）\n- 返回：新文档的 `dentryUuid`、文档链接\n- 注意：只能创建 adoc 类型，不能创建表格/演示等\n\n### update_document\n更新文字类型（adoc）文档的内容，支持两种模式：\n\n- `overwrite`：覆盖全部内容（常用于推送本地文件）\n- `append`：追加到文档末尾\n- 关键参数：`dentryUuid`、`content`（markdown）、`updateMode`（overwrite/append）\n- 限制：**仅支持 adoc 类型文档**，其他类型会报错\n\n### get_document_content（高敏感）\n获取文档的 markdown 正文内容。\n\n- 关键参数：`dentryUuid`\n- 用途：读取文档内容、做差异对比后再更新\n\n---\n\n## 块级精确编辑\n\n适用于需要在文档特定位置插入/修改/删除段落、标题、表格等场景。\n\n### list_document_blocks\n列出文档的一级块元素（段落、标题、表格等）。\n\n- 关键参数：`dentryUuid`，支持按起始/终止位置和块类型过滤\n- 返回：blockId 列表，供后续插入/更新/删除使用\n\n### insert_document_block\n在文档指定位置插入新块元素。\n\n- 关键参数：`dentryUuid`、`blockType`（块类型）、块内容属性对象\n- 支持类型：段落、标题、表格、高亮块、列表等\n\n### update_document_block\n更新指定块元素的内容或样式。\n\n- 关键参数：`dentryUuid`、`blockId`、新内容（含 `blockType` 和属性对象）\n\n### delete_document_block\n删除指定块元素。\n\n- 关键参数：`dentryUuid`、`blockId`\n- 需有编辑权限\n\n---\n\n## 文档/节点查找\n\n### search_documents\n按关键词搜索当前用户有权限访问的文档。\n\n- 关键参数：`keyword`（匹配标题和内容）、可选过滤条件（类型、时间范围等）\n- 用途：在不知道 dentryUuid 时定位目标文档\n\n### list_nodes\n列出指定文件夹或知识库下的直接子节点（文件夹/文档/文件）。\n\n- 关键参数：`parentNodeId`（知识库 ID 或文件夹节点 ID），支持分页\n- 注意：**只返回直接子节点，不递归**；需要更深层列表时多次调用\n\n### get_document_info\n获取节点的元信息（标题、类型、创建者、创建时间等）。\n\n- 关键参数：`nodeId`（支持文档 URL 或 dentryUuid）\n- 返回的 `contentType` 字段可判断文档类型（adoc/sheet/ppt 等）\n\n---\n\n## 文件夹与节点管理\n\n### create_folder\n在指定位置创建文件夹，返回新文件夹的节点 ID。\n\n- 关键参数：`name`（文件夹名）、`parentNodeId`（父节点）\n\n### create_file\n创建各类型节点（文档、表格、演示、白板、脑图、多维表、文件夹）。\n\n- 支持三种创建位置（优先级顺序）：指定 folderId、指定 workspaceId、默认位置\n- 与 `create_document` 的区别：`create_file` 可创建所有类型，但不支持带初始内容\n\n### delete_document\n将节点移入回收站（30 天内可恢复，超过 30 天永久删除）。\n\n- 支持：知识库下的文档节点、文件夹节点、钉盘文件\n- **执行前需告知用户这是移入回收站，获得确认后再调用**\n\n### rename_document\n重命名节点（知识库下的文档/文件夹节点）。\n\n### move_document\n将节点移动到目标文件夹。\n\n- 支持：知识库节点、钉盘文件/文件夹\n- `nodeId` 支持文档 URL 或 dentryUuid\n\n### copy_document\n将节点复制到目标文件夹。\n\n- 与 `move_document` 参数相同，区别是原节点保留\n\n---\n\n## 文件上传（非 adoc 文件）\n\n上传本地文件（PDF、图片、Word 等）到钉钉文档/知识库，分三步：\n\n1. **get_file_upload_info** — 获取 OSS 上传凭证（第一步）\n2. **HTTP PUT** — 使用凭证将文件直传 OSS（Claude 代理发起 HTTP 请求）\n3. **commit_uploaded_file** — 提交完成文件入库（第三步）\n\n### get_file_upload_info\n- 关键参数：`fileName`、`fileSize`、目标位置（folderId 或 workspaceId）\n\n### commit_uploaded_file\n- 关键参数：上传凭证中的 `uploadKey`\n\n---\n\n## 权限管理\n\n### add_permission\n为知识库节点添加企业用户成员（指定角色）。\n\n### update_permission\n修改企业用户在节点上的角色。\n\n### list_permission\n查询节点当前的成员权限列表。\n\n---\n\n## 导出\n\n将文档异步导出为 PDF 或 Word 等格式，分两步：\n\n### submit_export_job\n提交导出任务，返回 `jobId`。\n\n- 关键参数：`dentryUuid`、`exportType`（`pdf` / `docx` 等）\n- 返回：`jobId`，供轮询使用\n\n### query_export_job\n查询导出任务状态，直到完成为止。\n\n- 关键参数：`jobId`\n- 返回：任务状态；完成时包含下载链接\n- 注意：需轮询直至状态为成功，建议间隔 1-2 秒\n\n---\n\n## 附件操作\n\n### get_doc_attachment_upload_info\n获取向指定文档上传附件所需的 OSS 凭证（文档内嵌附件，非知识库文件）。\n\n### download_doc_attachment\n获取文档内指定附件的临时下载 URL。\n\n- 关键参数：`nodeId`（文档标识）、`resourceId`（附件资源标识）\n\n### download_file\n获取钉盘文件的下载凭证，供 Claude 发起 HTTP GET 下载。\n\nFile v1.0.2:skill-card.md\n\n## Description:\n\nGuides an MCP-capable agent through reading, creating, updating, exporting, and managing DingTalk Docs via the configured dingtalk-doc MCP server.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cpsean](https://clawhub.ai/user/cpsean)\n\n### License/Terms of Use:\n\nMIT\n\n## Use Case:\n\nDevelopers, knowledge workers, and agent users use this skill to synchronize local Markdown with DingTalk knowledge bases, search and retrieve cloud documents, export files, and manage document nodes or permissions through DingTalk Docs.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Setup can persistently modify agent MCP configuration with an API-key-bearing DingTalk MCP URL.\n\nMitigation: Review the target config file and MCP URL before they are written, avoid repeating the full URL after setup, and install only when DingTalk document access is acceptable.\n\nRisk: The configured MCP server can access enterprise documents and support exports, downloads, uploads, permission changes, and document deletion.\n\nMitigation: Confirm write, export, delete, upload, and permission operations before execution, and use the least DingTalk workspace access needed for the task.\n\nRisk: Non-ASCII content uploaded through chat may be corrupted before it is pushed to DingTalk.\n\nMitigation: Prefer local file paths for Markdown files containing Chinese, Japanese, or other non-ASCII text, and check uploaded text for corruption before creating or updating documents.\n\n## Reference(s):\n\n- [Server-resolved GitHub source](https://github.com/CPsean/dingtalk-docs-skill)\n- [ClawHub skill page](https://clawhub.ai/cpsean/skills/dingtalk-docs-skill)\n- [DingTalk AI Hub MCP page](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail)\n- [DingTalk Docs](https://alidocs.dingtalk.com)\n- [DingTalk developer getting started](https://open.dingtalk.com/document/dingstart/dingtalk-developer)\n- [MCP tools reference](references/mcp-tools.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown or plain text guidance with optional shell commands and MCP tool-use instructions]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May guide MCP calls that read, write, export, delete, upload, or change permissions on DingTalk documents after required user confirmation.]\n\n## Skill Version(s):\n\n1.0.2 (source: server-resolved release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.0.2:evals/evals.json\n\n{\n \"skill_name\": \"dingtalk-docs-skill\",\n \"evals\": [\n {\n \"id\": 1,\n \"prompt\": \"我有一个本地文件 weekly-report.md，内容是本周工作总结，帮我把它推送到钉钉知识库，放在「周报」文件夹下，标题叫「2026-W18 周报」。\",\n \"expected_output\": \"调用 list_nodes 或 search_documents 找到「周报」文件夹的 nodeId，然后调用 create_document 创建文档，读取 weekly-report.md 内容作为 content 参数，最后返回文档标题和访问链接。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 create_document MCP 工具\",\n \"文档标题包含「2026-W18 周报」\",\n \"输出包含文档访问链接或 dentryUuid\",\n \"没有跳过定位父文件夹的步骤\"\n ]\n },\n {\n \"id\": 2,\n \"prompt\": \"帮我更新钉钉上的「产品需求文档 v2」，把本地的 prd-v2.md 内容覆盖上去。\",\n \"expected_output\": \"先调用 search_documents 找到目标文档的 dentryUuid，确认文档类型是 adoc，然后调用 update_document 以 overwrite 模式更新内容，最后返回更新结果和文档链接。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 search_documents 或 get_document_info 定位文档\",\n \"调用了 update_document 且 updateMode 为 overwrite\",\n \"输出包含操作成功的确认信息\"\n ]\n },\n {\n \"id\": 3,\n \"prompt\": \"帮我配置钉钉文档 MCP，我现在是第一次用。\",\n \"expected_output\": \"输出初始化引导步骤：提供开通链接、说明需要登录并开通服务、说明复制 StreamableHttp URL、说明后续 Claude 会写入 settings.json。不调用任何 MCP 文档工具。\",\n \"files\": [],\n \"assertions\": [\n \"输出包含 aihub.dingtalk.com 开通链接\",\n \"说明需要复制 StreamableHttp URL\",\n \"提到需要重启 Claude Code\",\n \"没有尝试直接调用 create_document 等文档操作工具\"\n ]\n },\n {\n \"id\": 4,\n \"prompt\": \"列出钉钉知识库根目录下的所有文档。\",\n \"expected_output\": \"调用 list_nodes 并传入知识库根节点 ID（如果用户未提供则先询问或说明需要知识库 ID），返回文档节点列表（标题、类型、节点 ID）。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 list_nodes MCP 工具\",\n \"如果缺少知识库 ID 则向用户说明而不是猜测\",\n \"输出展示了文档列表或明确说明缺少必要参数\"\n ]\n }\n ]\n}\n\nFile v1.0.2:evals/trigger-evals.json\n\n{\n \"skill_name\": \"dingtalk-docs-skill\",\n \"evals\": [\n {\n \"query\": \"帮我把这个 markdown 文件推送到钉钉文档\",\n \"should_trigger\": true\n },\n {\n \"query\": \"更新钉钉上的周报文档，用本地最新版本覆盖\",\n \"should_trigger\": true\n },\n {\n \"query\": \"列出我的钉钉知识库里有哪些文档\",\n \"should_trigger\": true\n },\n {\n \"query\": \"在钉钉文档里搜索项目计划\",\n \"should_trigger\": true\n },\n {\n \"query\": \"初始化钉钉文档 MCP 配置\",\n \"should_trigger\": true\n },\n {\n \"query\": \"在钉钉知识库里创建一个新文件夹叫「产品设计」\",\n \"should_trigger\": true\n },\n {\n \"query\": \"把这篇技术文档同步到钉钉知识库\",\n \"should_trigger\": true\n },\n {\n \"query\": \"帮我把这个文件推送到语雀\",\n \"should_trigger\": false\n },\n {\n \"query\": \"帮我编辑本地的 README.md，修改第三段\",\n \"should_trigger\": false\n },\n {\n \"query\": \"给钉钉群里发一条消息通知大家\",\n \"should_trigger\": false\n },\n {\n \"query\": \"帮我把文档上传到飞书知识库\",\n \"should_trigger\": false\n },\n {\n \"query\": \"把这个 md 文件格式化一下，不需要上传\",\n \"should_trigger\": false\n }\n ]\n}\n\nFile v1.0.2:LICENSE\n\nMIT License\n\nCopyright (c) 2026 CPsean\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\nArchive v1.0.1: 7 files, 16583 bytes\n\nFiles: evals/evals.json (2542b), evals/trigger-evals.json (1350b), README.md (8443b), references/mcp-tools.md (5449b), skill-card.md (2918b), SKILL.md (15036b), _meta.json (138b)\n\nFile v1.0.1:SKILL.md\n\n---\nname: dingtalk-docs-skill\ndescription: 当用户想要操作钉钉文档时使用本 Skill。支持：推送本地 markdown 到钉钉知识库、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。\nlicense: MIT\ncompatibility: Requires dingtalk-doc MCP server (StreamableHttp transport). Compatible with any MCP-capable agent (Claude Code, Cursor, VS Code, Roo Code, Gemini CLI, Codex, etc.). Auto-detects Claude Code; falls back to writing config files or manual setup for other agents.\n---\n\n# 钉钉文档\n\n通过钉钉文档官方 MCP Server 全面操作云端文档。\n\n## 语言规则\n\n**始终使用用户输入的语言进行回复。** 如果用户用英文提问，则全程用英文回复；如果用户用中文，则全程用中文回复。无法判断时默认使用中文。\n\n## 能力范围\n\n**读**\n- 拉取云端文档正文为 markdown（保存到本地）\n- 列出知识库/文件夹下的文档节点\n- 按关键词搜索文档\n- 获取文档元信息（标题、类型、创建时间等）\n- 下载钉盘文件或文档内嵌附件\n\n**写**\n- 将本地 markdown 推送为钉钉文档（adoc 类型）\n- 覆盖或追加内容到已有文档\n- 按块精确编辑（插入/更新/删除段落、标题、表格等）\n- 上传本地文件（PDF、图片、Word 等）到知识库\n\n**管理**\n- 创建文件夹\n- 重命名/移动/复制/删除文档和文件夹\n- 导出文档为 PDF 或 Word 格式\n- 查看/添加/修改知识库节点的成员权限\n\n**不负责：**\n- 飞书、语雀、Notion 等其他平台\n- 只修改本地文件（无云端操作）\n- 钉钉 IM 消息、企业成员管理\n\n## 前置条件\n\n钉钉文档 MCP Server 必须已配置到当前 Agent 的 MCP 设置中，服务名称为 `dingtalk-doc`。\n\n如果 MCP 工具不可用，先走**初始化流程**，再执行任何文档操作。\n\n## 初始化流程（首次使用或 MCP 不可用时）\n\n1. 告知用户访问帮助手册页面并完成开通：\n > 请打开以下链接，使用钉钉账号登录后，点击页面上的【开通服务】按钮：\n > https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail\n\n2. 开通后复制页面右侧 **StreamableHttp URL**（不是 JSON Config）\n\n3. 请用户将 URL 粘贴给你\n\n4. 收到 URL 后，按以下顺序尝试注册 MCP 服务（`dingtalk-doc` 为服务名，必须为 ASCII）：\n\n **方案 A — Claude Code**（优先尝试，运行命令看是否成功）：\n ```bash\n claude mcp add --transport http --scope user dingtalk-doc \"<用户提供的 URL>\"\n ```\n 成功则跳到步骤 5。\n\n **方案 B — 写入配置文件**（通用方案，大多数 Agent 均可用）：\n\n 检测当前环境存在哪些配置文件，找到第一个匹配项写入：\n\n | Agent | 配置文件（全局） | 配置文件（项目级） | `mcpServers` 键名 |\n |-------|---------------|----------------|-----------------|\n | Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | `mcpServers` |\n | VS Code Copilot | `~/Library/Application Support/Code/User/mcp.json`（Mac）
`%APPDATA%\\Code\\User\\mcp.json`（Win） | `.vscode/mcp.json` | `servers` |\n | Roo Code | — | `.roo/mcp.json` | `mcpServers` |\n | Gemini CLI | `~/.gemini/settings.json` | — | `mcpServers` |\n | OpenAI Codex | `~/.codex/config.json` | — | `mcpServers` |\n\n 向目标文件追加（若文件已有 `mcpServers`/`servers`，只添加新条目，不覆盖原有内容）：\n\n ```json\n {\n \"mcpServers\": {\n \"dingtalk-doc\": {\n \"type\": \"http\",\n \"url\": \"<用户提供的 URL>\"\n }\n }\n }\n ```\n > VS Code Copilot 的 `.vscode/mcp.json` 使用 `\"servers\"` 而非 `\"mcpServers\"`，写入时注意区分。\n\n 成功写入则跳到步骤 5。\n\n **方案 C — 手动兜底**（方案 A/B 均不适用时）：\n\n 向用户展示以下信息，请其参照所用 Agent 的文档手动添加 MCP 服务，完成后回来继续：\n ```\n 传输类型：StreamableHttp（HTTP）\n 服务名称：dingtalk-doc\n URL：<用户提供的 URL>\n ```\n 用户手动配置完成后，本 Skill 只需确认 MCP 工具可用即可继续。\n\n > URL 中含有个人 API Key，写入配置后不要在回复中重复显示完整 URL。\n\n5. 询问用户的默认知识库地址：\n > 请在浏览器中打开你常用的钉钉知识库，把地址栏的 URL 粘贴给我（格式类似 `https://alidocs.dingtalk.com/i/spaces/xxxxx/overview`）。\n > 如果暂时不设默认知识库，可以跳过，后续每次操作时再指定。\n\n6. 收到知识库 URL 后，写入 `references/dingtalk.config`：\n ```\n DINGTALK_DEFAULT_WORKSPACE_URL=<用户提供的知识库 URL>\n ```\n 此文件已被 `.gitignore` 排除，不会进入版本控制。无需重启，下次操作时直接读取生效。\n\n7. MCP 配置写入后，提示用户重启 Agent 客户端以使 MCP 生效，重启后回来继续操作即可。\n\n### 使用默认知识库\n\n- 当用户说\"列出我的知识库文档\"、\"推送到知识库\"等未指明位置的操作时，优先使用默认知识库 URL\n- **读取顺序**：① 读取 `references/dingtalk.config` 中的 `DINGTALK_DEFAULT_WORKSPACE_URL`；② 若文件不存在或值为空，检查环境变量 `$DINGTALK_DEFAULT_WORKSPACE_URL`（兼容已有 Claude Code 配置）；③ 两者均无则询问用户\n- 获得 URL 后，调用 `get_document_info` 传入该 URL 解析出 nodeId，再用 nodeId 调用 `list_nodes` 或作为 `parentNodeId`\n\n### 更改默认知识库\n\n当用户说\"更换默认知识库\"、\"修改知识库地址\"等时：\n\n1. 请用户在浏览器打开目标钉钉知识库，复制地址栏 URL\n2. 收到新 URL 后，覆盖写入 `references/dingtalk.config`：\n ```\n DINGTALK_DEFAULT_WORKSPACE_URL=<新的知识库 URL>\n ```\n3. 无需重启，下次操作时读取新值即生效\n\n### 安全规则\n\n- MCP 服务 URL 含有个人 API Key，**不得出现在任何版本控制文件中**；写入配置后不要在回复中重复显示完整 URL\n- `references/dingtalk.config` 保存知识库 URL，已被 `.gitignore` 排除，不会提交到版本控制\n- 如果用户将 URL 粘贴到聊天中，立即写入配置后不再引用\n\n## 默认路径\n\n1. 确认 MCP 工具可用（若不可用，进入初始化流程）\n2. 理解用户意图，映射到对应 MCP 工具（见工具映射表）\n3. 如需要 dentryUuid/nodeId 但用户未提供：优先读取 `references/dingtalk.config`（或环境变量 `$DINGTALK_DEFAULT_WORKSPACE_URL`）获取默认知识库 URL，调用 `get_document_info` 解析出 nodeId；否则调用 `search_documents` 或 `list_nodes` 定位目标，让用户确认后再操作\n4. **执行前确认**（只读操作除外，见下方说明）：向用户展示操作摘要，收到明确同意后再调用 MCP 工具\n5. 执行操作\n6. 报告结果：操作类型、文档标题、文档链接（如有）\n\n### 执行前确认规则\n\n**需要确认的操作**（所有会写入或修改云端数据的操作）：\n`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`\n\n**无需确认的操作**（只读）：\n`search_documents`、`list_nodes`、`get_document_info`、`get_document_content`、`list_document_blocks`、`list_permission`、`query_export_job`、`download_file`、`download_doc_attachment`\n\n**确认摘要格式**（根据操作类型调整）：\n\n```\n即将执行以下操作，请确认：\n\n操作：<创建 / 更新（覆盖）/ 更新（追加）/ 删除 / 重命名 / 移动 / 复制 / 创建文件夹>\n目标：<文档标题或文件夹名>\n位置：<知识库名或文件夹路径>\n说明：<一句话描述本次变更，例如\"将以本地文件 xxx.md 的内容覆盖云端文档全文\">\n\n确认请回复「是」或「确认」，取消请回复「否」或「取消」。\n```\n\n收到取消时：停止操作，不重试，告知用户已取消。\n\n## MCP 工具映射\n\n详见 `references/mcp-tools.md`。常用映射如下：\n\n| 用户意图 | MCP 工具 |\n|---------|---------|\n| 推送/创建文档（含 markdown 内容） | `create_document` |\n| 拉取云端文档内容到本地 | `get_document_content` |\n| 覆盖或追加文档内容 | `update_document` |\n| 精确块级编辑（段落/标题/表格等） | `list_document_blocks` → `insert/update/delete_document_block` |\n| 列出知识库/文件夹下的文档 | `list_nodes` |\n| 按关键词搜索文档 | `search_documents` |\n| 获取文档元信息（标题、类型等） | `get_document_info` |\n| 下载钉盘文件 | `download_file` |\n| 下载文档内嵌附件 | `download_doc_attachment` |\n| 导出文档为 PDF/Word | `submit_export_job` → `query_export_job`（轮询至完成）|\n| 创建文件夹 | `create_folder` |\n| 删除文档节点 | `delete_document` |\n| 重命名节点 | `rename_document` |\n| 移动节点到其他文件夹 | `move_document` |\n| 复制节点到其他文件夹 | `copy_document` |\n| 查看节点成员权限 | `list_permission` |\n| 添加/修改节点成员权限 | `add_permission` / `update_permission` |\n\n## 失败处理\n\n- **MCP 工具不可用**：停止，进入初始化流程，不要猜测或尝试其他方式调用\n- **未提供目标文档**：先用 `search_documents` 或 `list_nodes` 找到目标，让用户确认后再操作\n- **update_document 报错**：确认目标是否为 adoc（文字类型）文档，非 adoc 文档不支持此操作\n- **delete_document 前**：确认摘要中必须注明\"将移入回收站，30 天内可恢复\"，收到确认后再执行\n- **API 报错（权限/鉴权类）**：当 API 返回权限不足、无权限、鉴权失败、Forbidden、Unauthorized 等错误时，除了展示原文错误信息外，提示用户可能尚未开通所在组织的钉钉开发者权限，引导用户参考以下链接完成开通：\n > 请访问钉钉开发者入门文档，确认你已在所在组织中开通了开发者权限：\n > https://open.dingtalk.com/document/dingstart/dingtalk-developer\n >\n > 开通步骤简述：登录钉钉开放平台 → 选择对应组织 → 完成开发者认证/开通。完成后重新尝试操作。\n- **其他 API 报错**：原文展示错误信息，不猜测原因，不自动重试\n\n## 关键约束\n\n- `update_document` 和 `create_document` 仅支持 **adoc（文字类型）** 文档，不支持表格、演示、脑图等\n- `create_document` 和 `update_document` 的 `markdown` 参数上限均为 **10,000 字符**；超出会报 `invalidRequest.inputArgs.invalid` 错误。推送前应先估算内容字符数，超过 **9,500 字符**（留余量）时走大文档推送策略（见下文）\n- `delete_document` 是移入回收站，不是永久删除，30 天内可从回收站恢复\n- `list_nodes` 只返回直接子节点，不递归。需要深层列表时需要多次调用\n- **导出为异步操作**：`submit_export_job` 返回 jobId 后需轮询 `query_export_job` 直到状态完成，再将下载链接告知用户；轮询间隔建议 1-2 秒\n- **Mermaid 文本绘图**：通过 `create_document` 推送的 ` ```mermaid ` 代码块会被解析为普通代码块，而非钉钉原生文本绘图块。钉钉的文本绘图是私有块类型，API 层未暴露，无法通过 MCP 创建或转换。推送前告知用户此限制，建议推送后在钉钉编辑器中手动将代码块转换为文本绘图\n- 操作完成后，从返回值中提取文档链接告知用户，方便直接点击查看\n\n## 对话中上传文件的处理\n\n用户可能在对话中直接上传 markdown 文件并要求推送到钉钉。\n\n### 已知限制\n\n- 对话上传的文件内容是**临时的**，不会持久保存到磁盘，上下文压缩或会话结束后内容即丢失\n- **非 ASCII 文件（如中文 markdown）通过对话上传时，0x80-0x9F 范围的字节会被文本处理层丢弃，导致不可逆乱码**。这是客户端文本传输的固有限制，编码修复无法还原丢失的字节\n\n### 处理规则\n\n1. **优先使用本地文件路径**：当用户要推送含非 ASCII 内容（中文、日文等）的文件时，请用户提供本地磁盘路径，直接读取文件内容，避免编码问题\n2. **对话上传的文件先检查编码**：如果用户直接在对话中上传了文件，先检查内容是否出现乱码。如果存在乱码，立即告知用户并请其提供本地文件路径\n3. **纯 ASCII 内容可直接处理**：如果上传的文件内容全是 ASCII（英文、代码等），可以直接处理，在同一轮回复中完成：读取内容 -> 确认摘要 -> （用户确认后）调用 `create_document`\n4. **文档命名**：默认使用上传文件名（去掉扩展名）作为钉钉文档标题。如果用户要求修改名字，按用户指定的名字创建\n5. **仅支持 markdown / 纯文本**：对话上传的二进制文件（PDF、图片、Word 等）当前不支持直接推送，需要用户提供本地磁盘路径后走文件上传三步流程\n\n## 大文档推送策略\n\n当需要将本地 markdown 文件推送为钉钉在线文档（adoc）时，**推送前先估算内容字符数**。超过 **9,500 字符** 时，单次 `create_document` 必然失败，需主动告知用户并让其选择方案：\n\n### 方案 A — 分段推送（生成可在线编辑的 adoc）\n\n1. 按 `## ` / `### ` 标题边界将内容切分为若干段，每段 ≤ 9,500 字符，避免在表格中间切断\n2. 用 `create_document` 写入第 1 段（含标题）\n3. 依次用 `update_document`（`append` 模式）追加后续各段，每段单独一次调用\n4. 全部追加完成后报告文档链接\n\n**适合场景**：用户需要在钉钉在线编辑、评论、协作，或希望文档格式被渲染\n\n### 方案 B — 上传原始 .md 文件（存入钉盘）\n\n走三步文件上传流程：`get_file_upload_info` → HTTP PUT → `commit_uploaded_file`\n\n**适合场景**：只需存档或分享下载，不需要在线编辑；操作更简单，文件完整保留原格式\n\n### 推荐选择\n\n向用户说明两个方案后，推荐如下：\n\n> 如果你需要在钉钉里直接编辑或与同事协作，推荐方案 A（分段推送）；如果只是存档或分享，推荐方案 B（上传文件）。\n\n收到用户选择后再执行，不要擅自决定。\n\n---\n\n## 资源导航\n\n- `references/mcp-tools.md` — 全部 MCP 工具详细说明，按场景分组\n\nFile v1.0.1:README.md\n\n# dingtalk-docs-skill\n\n[English](#english) | [中文](#中文)\n\n---\n\n## 中文\n\n**dingtalk-docs-skill** 是一个兼容多平台的 Agent Skill，通过钉钉文档官方 MCP Server 全面操作钉钉云端文档，支持读取、推送、同步、导出、权限管理等。\n\n### 功能\n\n| 类别 | 能力 |\n|------|------|\n| **读** | 拉取云端文档正文为 markdown、列出知识库/文件夹文档、按关键词搜索、获取文档元信息、下载钉盘文件与文档附件 |\n| **写** | 推送本地 markdown 到钉钉、覆盖/追加更新文档内容、块级精确编辑（段落/标题/表格等）、上传本地文件（PDF/图片/Word 等） |\n| **管理** | 创建文件夹、重命名/移动/复制/删除文档和文件夹、导出文档为 PDF/Word、管理节点成员权限 |\n\n所有操作通过[钉钉官方 MCP Server](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) 完成，无需本地脚本，API Key 不会写入代码。\n\n### 快速开始\n\n**1. 安装 Skill**\n\n**用户级安装**（推荐，所有项目均可使用）：\n\nmacOS / Linux：\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n ~/.claude/skills/dingtalk-docs-skill\n```\n\nWindows（PowerShell）：\n```powershell\ngit clone https://github.com/CPsean/dingtalk-docs-skill `\n \"$env:USERPROFILE\\.claude\\skills\\dingtalk-doc\"\n```\n\n**项目级安装**（仅当前项目可用）：\n\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n .claude/skills/dingtalk-docs-skill\n```\n\n安装后重启 Claude Code 使 Skill 生效。\n\n**2. 开通钉钉文档 MCP 服务**\n\n首次使用时，Skill 会引导你完成配置：\n\n1. 打开[钉钉 AI Hub MCP 页面](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail)，登录钉钉账号，点击【开通服务】\n2. 复制页面右侧的 **StreamableHttp URL**（不是 JSON Config）\n3. 将 URL 粘贴给 Claude\n\nSkill 会自动注册 MCP 服务。Claude Code 客户端执行：\n\n```bash\nclaude mcp add --transport http --scope user dingtalk-doc \"<你的 URL>\"\n```\n\n其他客户端（Claude Desktop、Cursor 等）需手动配置 StreamableHttp 类型的 MCP 服务。\n\n**3.（可选）设置默认知识库**\n\n提供你常用的知识库 URL，后续操作无需每次指定：\n\n```\nhttps://alidocs.dingtalk.com/i/spaces/xxxxx/overview\n```\n\n### 使用示例\n\n直接用自然语言和 Claude 对话即可：\n\n- *\"把 `docs/design.md` 推送到我的钉钉知识库\"*\n- *\"用本地最新版本更新钉钉上的 PRD 文档\"*\n- *\"列出我知识库里的所有文档\"*\n- *\"在钉钉文档里搜索「认证」\"*\n- *\"把会议纪要从钉钉拉取到本地\"*\n- *\"删除钉钉上的测试文档\"*\n\n### 工作流程\n\n```\n用户请求\n → Skill 激活（通过 description 触发词匹配）\n → MCP 工具映射（create / update / list / search / delete ...）\n → 执行前确认（所有写操作需用户确认）\n → 钉钉文档 MCP Server\n → 返回结果：文档标��� + 链接\n```\n\n### 已知限制\n\n| 限制项 | 详情 |\n|---|---|\n| **Mermaid 流程图** | ` ```mermaid ` 代码块推送后显示为普通代码块，而非钉钉原生「文本绘图」。推送后需在钉钉编辑器中手动转换。 |\n| **对话上传文件编码** | 非 ASCII 文件（中文等）通过对话上传时可能出现不可逆乱码。请始终提供**本地文件路径**。 |\n| **文档类型** | `create_document` 和 `update_document` 仅支持 **adoc**（文字类型）文档。 |\n| **删除** | 移入回收站（30 天内可恢复），非永久删除。 |\n\n### 安全性\n\n- MCP 服务 URL 包含个人 API Key，仅写入本地配置，**不会提交到版本控制**\n- 所有写操作执行前都需要用户明确确认\n\n### 文件结构\n\n```\n.claude/skills/dingtalk-docs-skill/\n├── SKILL.md # Skill 入口（触发器 + 指令）\n├── README.md # 本文件\n├── evals/\n│ ├── evals.json # 任务执行测评\n│ └── trigger-evals.json # 触发边界测评\n└── references/\n └── mcp-tools.md # MCP 工具速查表\n```\n\n---\n\n## English\n\n**dingtalk-docs-skill** is a cross-platform Agent Skill for reading, pushing, syncing, exporting, and managing documents on [DingTalk Docs](https://alidocs.dingtalk.com) via the official DingTalk Document MCP Server.\n\n### Features\n\n| Category | Capabilities |\n|----------|-------------|\n| **Read** | Pull cloud document content as markdown, list knowledge base / folder nodes, search by keyword, get document metadata, download DingTalk Drive files and attachments |\n| **Write** | Push local markdown to DingTalk, overwrite / append document content, block-level precise editing (paragraphs, headings, tables, etc.), upload local files (PDF, images, Word, etc.) |\n| **Manage** | Create folders, rename / move / copy / delete documents and folders, export documents to PDF or Word, manage node member permissions |\n\nAll operations go through [DingTalk's official MCP Server](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) — no local scripts or API keys in code.\n\n### Quick Start\n\n**1. Install the Skill**\n\n**User-level install** (recommended — available across all projects):\n\nmacOS / Linux:\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n ~/.claude/skills/dingtalk-docs-skill\n```\n\nWindows (PowerShell):\n```powershell\ngit clone https://github.com/CPsean/dingtalk-docs-skill `\n \"$env:USERPROFILE\\.claude\\skills\\dingtalk-doc\"\n```\n\n**Project-level install** (current project only):\n\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n .claude/skills/dingtalk-docs-skill\n```\n\nRestart Claude Code after installing to load the skill.\n\n**2. Enable the DingTalk Document MCP Server**\n\nOn first use, the skill will guide you through setup:\n\n1. Open the [DingTalk AI Hub MCP page](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) and activate the service\n2. Copy the **StreamableHttp URL** from the page\n3. Paste it into the Claude conversation\n\nThe skill automatically registers the MCP server. For Claude Code:\n\n```bash\nclaude mcp add --transport http --scope user dingtalk-doc \"\"\n```\n\nFor other clients (Claude Desktop, Cursor, etc.), configure a StreamableHttp MCP server manually.\n\n**3. (Optional) Set a Default Knowledge Base**\n\nProvide your knowledge base URL so you don't have to specify it every time:\n\n```\nhttps://alidocs.dingtalk.com/i/spaces/xxxxx/overview\n```\n\n### Usage Examples\n\nJust talk to Claude naturally:\n\n- *\"Push `docs/design.md` to my DingTalk knowledge base\"*\n- *\"Update the PRD document on DingTalk with the latest local version\"*\n- *\"List all documents in my knowledge base\"*\n- *\"Search DingTalk docs for 'authentication'\"*\n- *\"Pull the meeting notes from DingTalk to local\"*\n- *\"Delete the test document from DingTalk\"*\n\n### How It Works\n\n```\nUser request\n → Skill activation (matched by description trigger)\n → MCP tool mapping (create / update / list / search / delete ...)\n → Pre-execution confirmation (for all write operations)\n → DingTalk Document MCP Server\n → Result: document title + link\n```\n\n### Known Limitations\n\n| Limitation | Detail |\n|---|---|\n| **Mermaid diagrams** | ` ```mermaid ` blocks are pushed as plain code blocks, not DingTalk's native \"text drawing\" blocks. Manually convert after pushing. |\n| **File encoding on chat upload** | Non-ASCII files (Chinese, etc.) uploaded through the chat may suffer irreversible garbled text. Always provide a **local file path**. |\n| **Document types** | `create_document` and `update_document` only support **adoc** (text document) type. |\n| **Deletion** | Moves to trash (recoverable within 30 days), not permanent deletion. |\n\n### Security\n\n- The MCP server URL contains a personal API key — written to local config only, **never committed to version control**\n- All write operations require explicit user confirmation before execution\n\n### File Structure\n\n```\n.claude/skills/dingtalk-docs-skill/\n├── SKILL.md # Skill entry point (trigger + instructions)\n├── README.md # This file\n├── evals/\n│ ├── evals.json # Task execution evals\n│ └── trigger-evals.json # Trigger boundary evals\n└── references/\n └── mcp-tools.md # MCP tool reference\n```\n\n### License\n\nMIT\n\nFile v1.0.1:_meta.json\n\n{\n \"ownerId\": \"kn7facsvhzy0pcacszzatx32th87jknt\",\n \"slug\": \"dingtalk-docs-skill\",\n \"version\": \"1.0.1\",\n \"publishedAt\": 1780892743066\n}\n\nFile v1.0.1:references/mcp-tools.md\n\n# 钉钉文档 MCP 工具速查\n\nMCP 名称：`dingtalk-doc`（注册方式见 SKILL.md 初始化流程）\n\n---\n\n## 文档内容操作\n\n### create_document\n创建文字类型（adoc）钉钉文档，支持带初始 markdown 内容。\n\n- 关键参数：`title`（标题）、`content`（markdown 正文）、`parentNodeId`（父节点 ID，指定放置位置）\n- 返回：新文档的 `dentryUuid`、文档链接\n- 注意：只能创建 adoc 类型，不能创建表格/演示等\n\n### update_document\n更新文字类型（adoc）文档的内容，支持两种模式：\n\n- `overwrite`：覆盖全部内容（常用于推送本地文件）\n- `append`：追加到文档末尾\n- 关键参数：`dentryUuid`、`content`（markdown）、`updateMode`（overwrite/append）\n- 限制：**仅支持 adoc 类型文档**，其他类型会报错\n\n### get_document_content（高敏感）\n获取文档的 markdown 正文内容。\n\n- 关键参数：`dentryUuid`\n- 用途：读取文档内容、做差异对比后再更新\n\n---\n\n## 块级精确编辑\n\n适用于需要在文档特定位置插入/修改/删除段落、标题、表格等场景。\n\n### list_document_blocks\n列出文档的一级块元素（段落、标题、表格等）。\n\n- 关键参数：`dentryUuid`，支持按起始/终止位置和块类型过滤\n- 返回：blockId 列表，供后续插入/更新/删除使用\n\n### insert_document_block\n在文档指定位置插入新块元素。\n\n- 关键参数：`dentryUuid`、`blockType`（块类型）、块内容属性对象\n- 支持类型：段落、标题、表格、高亮块、列表等\n\n### update_document_block\n更新指定块元素的内容或样式。\n\n- 关键参数：`dentryUuid`、`blockId`、新内容（含 `blockType` 和属性对象）\n\n### delete_document_block\n删除指定块元素。\n\n- 关键参数：`dentryUuid`、`blockId`\n- 需有编辑权限\n\n---\n\n## 文档/节点查找\n\n### search_documents\n按关键词搜索当前用户有权限访问的文档。\n\n- 关键参数：`keyword`（匹配标题和内容）、可选过滤条件（类型、时间范围等）\n- 用途：在不知道 dentryUuid 时定位目标文档\n\n### list_nodes\n列出指定文件夹或知识库下的直接子节点（文件夹/文档/文件）。\n\n- 关键参数：`parentNodeId`（知识库 ID 或文件夹节点 ID），支持分页\n- 注意：**只返回直接子节点，不递归**；需要更深层列表时多次调用\n\n### get_document_info\n获取节点的元信息（标题、类型、创建者、创建时间等）。\n\n- 关键参数：`nodeId`（支持文档 URL 或 dentryUuid）\n- 返回的 `contentType` 字段可判断文档类型（adoc/sheet/ppt 等）\n\n---\n\n## 文件夹与节点管理\n\n### create_folder\n在指定位置创建文件夹，返回新文件夹的节点 ID。\n\n- 关键参数：`name`（文件夹名）、`parentNodeId`（父节点）\n\n### create_file\n创建各类型节点（文档、表格、演示、白板、脑图、多维表、文件夹）。\n\n- 支持三种创建位置（优先级顺序）：指定 folderId、指定 workspaceId、默认位置\n- 与 `create_document` 的区别：`create_file` 可创建所有类型，但不支持带初始内容\n\n### delete_document\n将节点移入回收站（30 天内可恢复，超过 30 天永久删除）。\n\n- 支持：知识库下的文档节点、文件夹节点、钉盘文件\n- **执行前需告知用户这是移入回收站，获得确认后再调用**\n\n### rename_document\n重命名节点（知识库下的文档/文件夹节点）。\n\n### move_document\n将节点移动到目标文件夹。\n\n- 支持：知识库节点、钉盘文件/文件夹\n- `nodeId` 支持文档 URL 或 dentryUuid\n\n### copy_document\n将节点复制到目标文件夹。\n\n- 与 `move_document` 参数相同，区别是原节点保留\n\n---\n\n## 文件上传（非 adoc 文件）\n\n上传本地文件（PDF、图片、Word 等）到钉钉文档/知识库，分三步：\n\n1. **get_file_upload_info** — 获取 OSS 上传凭证（第一步）\n2. **HTTP PUT** — 使用凭证将文件直传 OSS（Claude 代理发起 HTTP 请求）\n3. **commit_uploaded_file** — 提交完成文件入库（第三步）\n\n### get_file_upload_info\n- 关键参数：`fileName`、`fileSize`、目标位置（folderId 或 workspaceId）\n\n### commit_uploaded_file\n- 关键参数：上传凭证中的 `uploadKey`\n\n---\n\n## 权限管理\n\n### add_permission\n为知识库节点添加企业用户成员（指定角色）。\n\n### update_permission\n修改企业用户在节点上的角色。\n\n### list_permission\n查询节点当前的成员权限列表。\n\n---\n\n## 导出\n\n将文档异步导出为 PDF 或 Word 等格式，分两步：\n\n### submit_export_job\n提交导出任务，返回 `jobId`。\n\n- 关键参数：`dentryUuid`、`exportType`（`pdf` / `docx` 等）\n- 返回：`jobId`，供轮询使用\n\n### query_export_job\n查询导出任务状态，直到完成为止。\n\n- 关键参数：`jobId`\n- 返回：任务状态；完成时包含下载链接\n- 注意：需轮询直至状态为成功，建议间隔 1-2 秒\n\n---\n\n## 附件操作\n\n### get_doc_attachment_upload_info\n获取向指定文档上传附件所需的 OSS 凭证（文档内嵌附件，非知识库文件）。\n\n### download_doc_attachment\n获取文档内指定附件的临时下载 URL。\n\n- 关键参数：`nodeId`（文档标识）、`resourceId`（附件资源标识）\n\n### download_file\n获取钉盘文件的下载凭证，供 Claude 发起 HTTP GET 下载。\n\nFile v1.0.1:skill-card.md\n\n## Description:
\nHelps agents operate DingTalk Docs through the official DingTalk Docs MCP Server, including document creation, reading, updates, search, export, permission management, and setup guidance.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[cpsean](https://clawhub.ai/user/cpsean)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers, operators, and knowledge workers use this skill to connect an MCP-capable agent to DingTalk Docs and manage cloud documents from natural-language requests. It is intended for DingTalk Docs workflows such as pushing local markdown, pulling cloud content, editing documents, exporting files, and managing document nodes and permissions.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The skill can modify DingTalk Docs content, files, nodes, exports, and permissions using the user's account permissions.
\nMitigation: Require explicit user confirmation before write, delete, export, upload, move, copy, rename, or permission-management actions, and summarize the target and change before execution.
\nRisk: The DingTalk MCP StreamableHttp URL contains sensitive credentials.
\nMitigation: Treat the URL as a credential, avoid repeating it after configuration, and keep local MCP configuration files out of version control.
\nRisk: Overwrite or delete operations may affect the wrong document if the target is ambiguous.
\nMitigation: Resolve and confirm document titles, node locations, and operation modes before destructive or replacing changes; deletion should be described as moving the item to the recycle bin.
\n\n\n## Reference(s):
\n- [Dingtalk Docs Skill on ClawHub](https://clawhub.ai/cpsean/dingtalk-docs-skill)
\n- [DingTalk AI Hub MCP Page](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail)
\n- [DingTalk Developer Getting Started](https://open.dingtalk.com/document/dingstart/dingtalk-developer)
\n- [MCP Tools Reference](artifact/references/mcp-tools.md)
\n\n\n## Skill Output:
\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]
\n**Output Format:** [Markdown responses with inline shell commands, configuration snippets, and DingTalk document links when available]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May guide the agent to call DingTalk Docs MCP tools and to request user confirmation before write, delete, export, upload, or permission changes.]
\n\n## Skill Version(s):
\n1.0.1 (source: server release evidence)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.1:evals/evals.json\n\n{\n \"skill_name\": \"dingtalk-docs-skill\",\n \"evals\": [\n {\n \"id\": 1,\n \"prompt\": \"我有一个本地文件 weekly-report.md，内容是本周工作总结，帮我把它推送到钉钉知识库，放在「周报」文件夹下，标题叫「2026-W18 周报」。\",\n \"expected_output\": \"调用 list_nodes 或 search_documents 找到「周报」文件夹的 nodeId，然后调用 create_document 创建文档，读取 weekly-report.md 内容作为 content 参数，最后返回文档标题和访问链接。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 create_document MCP 工具\",\n \"文档标题包含「2026-W18 周报」\",\n \"输出包含文档访问链接或 dentryUuid\",\n \"没有跳过定位父文件夹的步骤\"\n ]\n },\n {\n \"id\": 2,\n \"prompt\": \"帮我更新钉钉上的「产品需求文档 v2」，把本地的 prd-v2.md 内容覆盖上去。\",\n \"expected_output\": \"先调用 search_documents 找到目标文档的 dentryUuid，确认文档类型是 adoc，然后调用 update_document 以 overwrite 模式更新内容，最后返回更新结果和文档链接。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 search_documents 或 get_document_info 定位文档\",\n \"调用了 update_document 且 updateMode 为 overwrite\",\n \"输出包含操作成功的确认信息\"\n ]\n },\n {\n \"id\": 3,\n \"prompt\": \"帮我配置钉钉文档 MCP，我现在是第一次用。\",\n \"expected_output\": \"输出初始化引导步骤：提供开通链接、说明需要登录并开通服务、说明复制 StreamableHttp URL、说明后续 Claude 会写入 settings.json。不调用任何 MCP 文档工具。\",\n \"files\": [],\n \"assertions\": [\n \"输出包含 aihub.dingtalk.com 开通链接\",\n \"说明需要复制 StreamableHttp URL\",\n \"提到需要重启 Claude Code\",\n \"没有尝试直接调用 create_document 等文档操作工具\"\n ]\n },\n {\n \"id\": 4,\n \"prompt\": \"列出钉钉知识库根目录下的所有文档。\",\n \"expected_output\": \"调用 list_nodes 并传入知识库根节点 ID（如果用户未提供则先询问或说明需要知识库 ID），返回文档节点列表（标题、类型、节点 ID）。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 list_nodes MCP 工具\",\n \"如果缺少知识库 ID 则向用户说明而不是猜测\",\n \"输出展示了文档列表或明确说明缺少必要参数\"\n ]\n }\n ]\n}\n\nFile v1.0.1:evals/trigger-evals.json\n\n{\n \"skill_name\": \"dingtalk-docs-skill\",\n \"evals\": [\n {\n \"query\": \"帮我把这个 markdown 文件推送到钉钉文档\",\n \"should_trigger\": true\n },\n {\n \"query\": \"更新钉钉上的周报文档，用本地最新版本覆盖\",\n \"should_trigger\": true\n },\n {\n \"query\": \"列出我的钉钉知识库里有哪些文档\",\n \"should_trigger\": true\n },\n {\n \"query\": \"在钉钉文档里搜索项目计划\",\n \"should_trigger\": true\n },\n {\n \"query\": \"初始化钉钉文档 MCP 配置\",\n \"should_trigger\": true\n },\n {\n \"query\": \"在钉钉知识库里创建一个新文件夹叫「产品设计」\",\n \"should_trigger\": true\n },\n {\n \"query\": \"把这篇技术文档同步到钉钉知识库\",\n \"should_trigger\": true\n },\n {\n \"query\": \"帮我把这个文件推送到语雀\",\n \"should_trigger\": false\n },\n {\n \"query\": \"帮我编辑本地的 README.md，修改第三段\",\n \"should_trigger\": false\n },\n {\n \"query\": \"给钉钉群里发一条消息通知大家\",\n \"should_trigger\": false\n },\n {\n \"query\": \"帮我把文档上传到飞书知识库\",\n \"should_trigger\": false\n },\n {\n \"query\": \"把这个 md 文件格式化一下，不需要上传\",\n \"should_trigger\": false\n }\n ]\n}\n\nArchive v1.0.0: 7 files, 15784 bytes\n\nFiles: evals/evals.json (2542b), evals/trigger-evals.json (1350b), README.md (8443b), references/mcp-tools.md (5449b), skill-card.md (2576b), SKILL.md (13450b), _meta.json (138b)\n\nFile v1.0.0:SKILL.md\n\n---\nname: dingtalk-docs-skill\ndescription: 当用户想要操作钉钉文档时使用本 Skill。支持：推送本地 markdown 到钉钉知识库、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。\nlicense: MIT\ncompatibility: Requires dingtalk-doc MCP server (StreamableHttp transport). Compatible with any MCP-capable agent (Claude Code, Cursor, VS Code, Roo Code, Gemini CLI, Codex, etc.). Auto-detects Claude Code; falls back to writing config files or manual setup for other agents.\n---\n\n# 钉钉文档\n\n通过钉钉文档官方 MCP Server 全面操作云端文档。\n\n## 语言规则\n\n**始终使用用户输入的语言进行回复。** 如果用户用英文提问，则全程用英文回复；如果用户用中文，则全程用中文回复。无法判断时默认使用中文。\n\n## 能力范围\n\n**读**\n- 拉取云端文档正文为 markdown（保存到本地）\n- 列出知识库/文件夹下的文档节点\n- 按关键词搜索文档\n- 获取文档元信息（标题、类型、创建时间等）\n- 下载钉盘文件或文档内嵌附件\n\n**写**\n- 将本地 markdown 推送为钉钉文档（adoc 类型）\n- 覆盖或追加内容到已有文档\n- 按块精确编辑（插入/更新/删除段落、标题、表格等）\n- 上传本地文件（PDF、图片、Word 等）到知识库\n\n**管理**\n- 创建文件夹\n- 重命名/移动/复制/删除文档和文件夹\n- 导出文档为 PDF 或 Word 格式\n- 查看/添加/修改知识库节点的成员权限\n\n**不负责：**\n- 飞书、语雀、Notion 等其他平台\n- 只修改本地文件（无云端操作）\n- 钉钉 IM 消息、企业成员管理\n\n## 前置条件\n\n钉钉文档 MCP Server 必须已配置到当前 Agent 的 MCP 设置中，服务名称为 `dingtalk-doc`。\n\n如果 MCP 工具不可用，先走**初始化流程**，再执行任何文档操作。\n\n## 初始化流程（首次使用或 MCP 不可用时）\n\n1. 告知用户访问帮助手册页面并完成开通：\n > 请打开以下链接，使用钉钉账号登录后，点击页面上的【开通服务】按钮：\n > https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail\n\n2. 开通后复制页面右侧 **StreamableHttp URL**（不是 JSON Config）\n\n3. 请用户将 URL 粘贴给你\n\n4. 收到 URL 后，按以下顺序尝试注册 MCP 服务（`dingtalk-doc` 为服务名，必须为 ASCII）：\n\n **方案 A — Claude Code**（优先尝试，运行命令看是否成功）：\n ```bash\n claude mcp add --transport http --scope user dingtalk-doc \"<用户提供的 URL>\"\n ```\n 成功则跳到步骤 5。\n\n **方案 B — 写入配置文件**（通用方案，大多数 Agent 均可用）：\n\n 检测当前环境存在哪些配置文件，找到第一个匹配项写入：\n\n | Agent | 配置文件（全局） | 配置文件（项目级） | `mcpServers` 键名 |\n |-------|---------------|----------------|-----------------|\n | Cursor | `~/.cursor/mcp.json` | `.cursor/mcp.json` | `mcpServers` |\n | VS Code Copilot | `~/Library/Application Support/Code/User/mcp.json`（Mac）
`%APPDATA%\\Code\\User\\mcp.json`（Win） | `.vscode/mcp.json` | `servers` |\n | Roo Code | — | `.roo/mcp.json` | `mcpServers` |\n | Gemini CLI | `~/.gemini/settings.json` | — | `mcpServers` |\n | OpenAI Codex | `~/.codex/config.json` | — | `mcpServers` |\n\n 向目标文件追加（若文件已有 `mcpServers`/`servers`，只添加新条目，不覆盖原有内容）：\n\n ```json\n {\n \"mcpServers\": {\n \"dingtalk-doc\": {\n \"type\": \"http\",\n \"url\": \"<用户提供的 URL>\"\n }\n }\n }\n ```\n > VS Code Copilot 的 `.vscode/mcp.json` 使用 `\"servers\"` 而非 `\"mcpServers\"`，写入时注意区分。\n\n 成功写入则跳到步骤 5。\n\n **方案 C — 手动兜底**（方案 A/B 均不适用时）：\n\n 向用户展示以下信息，请其参照所用 Agent 的文档手动添加 MCP 服务，完成后回来继续：\n ```\n 传输类型：StreamableHttp（HTTP）\n 服务名称：dingtalk-doc\n URL：<用户提供的 URL>\n ```\n 用户手动配置完成后，本 Skill 只需确认 MCP 工具可用即可继续。\n\n > URL 中含有个人 API Key，写入配置后不要在回复中重复显示完整 URL。\n\n5. 询问用户的默认知识库地址：\n > 请在浏览器中打开你常用的钉钉知识库，把地址栏的 URL 粘贴给我（格式类似 `https://alidocs.dingtalk.com/i/spaces/xxxxx/overview`）。\n > 如果暂时不设默认知识库，可以跳过，后续每次操作时再指定。\n\n6. 收到知识库 URL 后，写入 `references/dingtalk.config`：\n ```\n DINGTALK_DEFAULT_WORKSPACE_URL=<用户提供的知识库 URL>\n ```\n 此文件已被 `.gitignore` 排除，不会进入版本控制。无需重启，下次操作时直接读取生效。\n\n7. MCP 配置写入后，提示用户重启 Agent 客户端以使 MCP 生效，重启后回来继续操作即可。\n\n### 使用默认知识库\n\n- 当用户说\"列出我的知识库文档\"、\"推送到知识库\"等未指明位置的操作时，优先使用默认知识库 URL\n- **读取顺序**：① 读取 `references/dingtalk.config` 中的 `DINGTALK_DEFAULT_WORKSPACE_URL`；② 若文件不存在或值为空，检查环境变量 `$DINGTALK_DEFAULT_WORKSPACE_URL`（兼容已有 Claude Code 配置）；③ 两者均无则询问用户\n- 获得 URL 后，调用 `get_document_info` 传入该 URL 解析出 nodeId，再用 nodeId 调用 `list_nodes` 或作为 `parentNodeId`\n\n### 更改默认知识库\n\n当用户说\"更换默认知识库\"、\"修改知识库地址\"等时：\n\n1. 请用户在浏览器打开目标钉钉知识库，复制地址栏 URL\n2. 收到新 URL 后，覆盖写入 `references/dingtalk.config`：\n ```\n DINGTALK_DEFAULT_WORKSPACE_URL=<新的知识库 URL>\n ```\n3. 无需重启，下次操作时读取新值即生效\n\n### 安全规则\n\n- MCP 服务 URL 含有个人 API Key，**不得出现在任何版本控制文件中**；写入配置后不要在回复中重复显示完整 URL\n- `references/dingtalk.config` 保存知识库 URL，已被 `.gitignore` 排除，不会提交到版本控制\n- 如果用户将 URL 粘贴到聊天中，立即写入配置后不再引用\n\n## 默认路径\n\n1. 确认 MCP 工具可用（若不可用，进入初始化流程）\n2. 理解用户意图，映射到对应 MCP 工具（见工具映射表）\n3. 如需要 dentryUuid/nodeId 但用户未提供：优先读取 `references/dingtalk.config`（或环境变量 `$DINGTALK_DEFAULT_WORKSPACE_URL`）获取默认知识库 URL，调用 `get_document_info` 解析出 nodeId；否则调用 `search_documents` 或 `list_nodes` 定位目标，让用户确认后再操作\n4. **执行前确认**（只读操作除外，见下方说明）：向用户展示操作摘要，收到明确同意后再调用 MCP 工具\n5. 执行操作\n6. 报告结果：操作类型、文档标题、文档链接（如有）\n\n### 执行前确认规则\n\n**需要确认的操作**（所有会写入或修改云端数据的操作）：\n`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`\n\n**无需确认的操作**（只读）：\n`search_documents`、`list_nodes`、`get_document_info`、`get_document_content`、`list_document_blocks`、`list_permission`、`query_export_job`、`download_file`、`download_doc_attachment`\n\n**确认摘要格式**（根据操作类型调整）：\n\n```\n即将执行以下操作，请确认：\n\n操作：<创建 / 更新（覆盖）/ 更新（追加）/ 删除 / 重命名 / 移动 / 复制 / 创建文件夹>\n目标：<文档标题或文件夹名>\n位置：<知识库名或文件夹路径>\n说明：<一句话描述本次变更，例如\"将以本地文件 xxx.md 的内容覆盖云端文档全文\">\n\n确认请回复「是」或「确认」，取消请回复「否」或「取消」。\n```\n\n收到取消时：停止操作，不重试，告知用户已取消。\n\n## MCP 工具映射\n\n详见 `references/mcp-tools.md`。常用映射如下：\n\n| 用户意图 | MCP 工具 |\n|---------|---------|\n| 推送/创建文档（含 markdown 内容） | `create_document` |\n| 拉取云端文档内容到本地 | `get_document_content` |\n| 覆盖或追加文档内容 | `update_document` |\n| 精确块级编辑（段落/标题/表格等） | `list_document_blocks` → `insert/update/delete_document_block` |\n| 列出知识库/文件夹下的文档 | `list_nodes` |\n| 按关键词搜索文档 | `search_documents` |\n| 获取文档元信息（标题、类型等） | `get_document_info` |\n| 下载钉盘文件 | `download_file` |\n| 下载文档内嵌附件 | `download_doc_attachment` |\n| 导出文档为 PDF/Word | `submit_export_job` → `query_export_job`（轮询至完成）|\n| 创建文件夹 | `create_folder` |\n| 删除文档节点 | `delete_document` |\n| 重命名节点 | `rename_document` |\n| 移动节点到其他文件夹 | `move_document` |\n| 复制节点到其他文件夹 | `copy_document` |\n| 查看节点成员权限 | `list_permission` |\n| 添加/修改节点成员权限 | `add_permission` / `update_permission` |\n\n## 失败处理\n\n- **MCP 工具不可用**：停止，进入初始化流程，不要猜测或尝试其他方式调用\n- **未提供目标文档**：先用 `search_documents` 或 `list_nodes` 找到目标，让用户确认后再操作\n- **update_document 报错**：确认目标是否为 adoc（文字类型）文档，非 adoc 文档不支持此操作\n- **delete_document 前**：确认摘要中必须注明\"将移入回收站，30 天内可恢复\"，收到确认后再执行\n- **API 报错（权限/鉴权类）**：当 API 返回权限不足、无权限、鉴权失败、Forbidden、Unauthorized 等错误时，除了展示原文错误信息外，提示用户可能尚未开通所在组织的钉钉开发者权限，引导用户参考以下链接完成开通：\n > 请访问钉钉开发者入门文档，确认你已在所在组织中开通了开发者权限：\n > https://open.dingtalk.com/document/dingstart/dingtalk-developer\n >\n > 开通步骤简述：登录钉钉开放平台 → 选择对应组织 → 完成开发者认证/开通。完成后重新尝试操作。\n- **其他 API 报错**：原文展示错误信息，不猜测原因，不自动重试\n\n## 关键约束\n\n- `update_document` 和 `create_document` 仅支持 **adoc（文字类型）** 文档，不支持表格、演示、脑图等\n- `delete_document` 是移入回收站，不是永久删除，30 天内可从回收站恢复\n- `list_nodes` 只返回直接子节点，不递归。需要深层列表时需要多次调用\n- **导出为异步操作**：`submit_export_job` 返回 jobId 后需轮询 `query_export_job` 直到状态完成，再将下载链接告知用户；轮询间隔建议 1-2 秒\n- **Mermaid 文本绘图**：通过 `create_document` 推送的 ` ```mermaid ` 代码块会被解析为普通代码块，而非钉钉原生文本绘图块。钉钉的文本绘图是私有块类型，API 层未暴露，无法通过 MCP 创建或转换。推送前告知用户此限制，建议推送后在钉钉编辑器中手动将代码块转换为文本绘图\n- 操作完成后，从返回值中提取文档链接告知用户，方便直接点击查看\n\n## 对话中上传文件的处理\n\n用户可能在对话中直接上传 markdown 文件并要求推送到钉钉。\n\n### 已知限制\n\n- 对话上传的文件内容是**临时的**，不会持久保存到磁盘，上下文压缩或会话结束后内容即丢失\n- **非 ASCII 文件（如中文 markdown）通过对话上传时，0x80-0x9F 范围的字节会被文本处理层丢弃，导致不可逆乱码**。这是客户端文本传输的固有限制，编码修复无法还原丢失的字节\n\n### 处理规则\n\n1. **优先使用本地文件路径**：当用户要推送含非 ASCII 内容（中文、日文等）的文件时，请用户提供本地磁盘路径，直接读取文件内容，避免编码问题\n2. **对话上传的文件先检查编码**：如果用户直接在对话中上传了文件，先检查内容是否出现乱码。如果存在乱码，立即告知用户并请其提供本地文件路径\n3. **纯 ASCII 内容可直接处理**：如果上传的文件内容全是 ASCII（英文、代码等），可以直接处理，在同一轮回复中完成：读取内容 -> 确认摘要 -> （用户确认后）调用 `create_document`\n4. **文档命名**：默认使用上传文件名（去掉扩展名）作为钉钉文档标题。如果用户要求修改名字，按用户指定的名字创建\n5. **仅支持 markdown / 纯文本**：对话上传的二进制文件（PDF、图片、Word 等）当前不支持直接推送，需要用户提供本地磁盘路径后走文件上传三步流程\n\n## 资源导航\n\n- `references/mcp-tools.md` — 全部 MCP 工具详细说明，按场景分组\n\nFile v1.0.0:README.md\n\n# dingtalk-docs-skill\n\n[English](#english) | [中文](#中文)\n\n---\n\n## 中文\n\n**dingtalk-docs-skill** 是一个兼容多平台的 Agent Skill，通过钉钉文档官方 MCP Server 全面操作钉钉云端文档，支持读取、推送、同步、导出、权限管理等。\n\n### 功能\n\n| 类别 | 能力 |\n|------|------|\n| **读** | 拉取云端文档正文为 markdown、列出知识库/文件夹文档、按关键词搜索、获取文档元信息、下载钉盘文件与文档附件 |\n| **写** | 推送本地 markdown 到钉钉、覆盖/追加更新文档内容、块级精确编辑（段落/标题/表格等）、上传本地文件（PDF/图片/Word 等） |\n| **管理** | 创建文件夹、重命名/移动/复制/删除文档和文件夹、导出文档为 PDF/Word、管理节点成员权限 |\n\n所有操作通过[钉钉官方 MCP Server](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) 完成，无需本地脚本，API Key 不会写入代码。\n\n### 快速开始\n\n**1. 安装 Skill**\n\n**用户级安装**（推荐，所有项目均可使用）：\n\nmacOS / Linux：\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n ~/.claude/skills/dingtalk-docs-skill\n```\n\nWindows（PowerShell）：\n```powershell\ngit clone https://github.com/CPsean/dingtalk-docs-skill `\n \"$env:USERPROFILE\\.claude\\skills\\dingtalk-doc\"\n```\n\n**项目级安装**（仅当前项目可用）：\n\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n .claude/skills/dingtalk-docs-skill\n```\n\n安装后重启 Claude Code 使 Skill 生效。\n\n**2. 开通钉钉文档 MCP 服务**\n\n首次使用时，Skill 会引导你完成配置：\n\n1. 打开[钉钉 AI Hub MCP 页面](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail)，登录钉钉账号，点击【开通服务】\n2. 复制页面右侧的 **StreamableHttp URL**（不是 JSON Config）\n3. 将 URL 粘贴给 Claude\n\nSkill 会自动注册 MCP 服务。Claude Code 客户端执行：\n\n```bash\nclaude mcp add --transport http --scope user dingtalk-doc \"<你的 URL>\"\n```\n\n其他客户端（Claude Desktop、Cursor 等）需手动配置 StreamableHttp 类型的 MCP 服务。\n\n**3.（可选）设置默认知识库**\n\n提供你常用的知识库 URL，后续操作无需每次指定：\n\n```\nhttps://alidocs.dingtalk.com/i/spaces/xxxxx/overview\n```\n\n### 使用示例\n\n直接用自然语言和 Claude 对话即可：\n\n- *\"把 `docs/design.md` 推送到我的钉钉知识库\"*\n- *\"用本地最新版本更新钉钉上的 PRD 文档\"*\n- *\"列出我知识库里的所有文档\"*\n- *\"在钉钉文档里搜索「认证」\"*\n- *\"把会议纪要从钉钉拉取到本地\"*\n- *\"删除钉钉上的测试文档\"*\n\n### 工作流程\n\n```\n用户请求\n → Skill 激活（通过 description 触发词匹配）\n → MCP 工具映射（create / update / list / search / delete ...）\n → 执行前确认（所有写操作需用户确认）\n → 钉钉文档 MCP Server\n → 返回结果：文档标��� + 链接\n```\n\n### 已知限制\n\n| 限制项 | 详情 |\n|---|---|\n| **Mermaid 流程图** | ` ```mermaid ` 代码块推送后显示为普通代码块，而非钉钉原生「文本绘图」。推送后需在钉钉编辑器中手动转换。 |\n| **对话上传文件编码** | 非 ASCII 文件（中文等）通过对话上传时可能出现不可逆乱码。请始终提供**本地文件路径**。 |\n| **文档类型** | `create_document` 和 `update_document` 仅支持 **adoc**（文字类型）文档。 |\n| **删除** | 移入回收站（30 天内可恢复），非永久删除。 |\n\n### 安全性\n\n- MCP 服务 URL 包含个人 API Key，仅写入本地配置，**不会提交到版本控制**\n- 所有写操作执行前都需要用户明确确认\n\n### 文件结构\n\n```\n.claude/skills/dingtalk-docs-skill/\n├── SKILL.md # Skill 入口（触发器 + 指令）\n├── README.md # 本文件\n├── evals/\n│ ├── evals.json # 任务执行测评\n│ └── trigger-evals.json # 触发边界测评\n└── references/\n └── mcp-tools.md # MCP 工具速查表\n```\n\n---\n\n## English\n\n**dingtalk-docs-skill** is a cross-platform Agent Skill for reading, pushing, syncing, exporting, and managing documents on [DingTalk Docs](https://alidocs.dingtalk.com) via the official DingTalk Document MCP Server.\n\n### Features\n\n| Category | Capabilities |\n|----------|-------------|\n| **Read** | Pull cloud document content as markdown, list knowledge base / folder nodes, search by keyword, get document metadata, download DingTalk Drive files and attachments |\n| **Write** | Push local markdown to DingTalk, overwrite / append document content, block-level precise editing (paragraphs, headings, tables, etc.), upload local files (PDF, images, Word, etc.) |\n| **Manage** | Create folders, rename / move / copy / delete documents and folders, export documents to PDF or Word, manage node member permissions |\n\nAll operations go through [DingTalk's official MCP Server](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) — no local scripts or API keys in code.\n\n### Quick Start\n\n**1. Install the Skill**\n\n**User-level install** (recommended — available across all projects):\n\nmacOS / Linux:\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n ~/.claude/skills/dingtalk-docs-skill\n```\n\nWindows (PowerShell):\n```powershell\ngit clone https://github.com/CPsean/dingtalk-docs-skill `\n \"$env:USERPROFILE\\.claude\\skills\\dingtalk-doc\"\n```\n\n**Project-level install** (current project only):\n\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n .claude/skills/dingtalk-docs-skill\n```\n\nRestart Claude Code after installing to load the skill.\n\n**2. Enable the DingTalk Document MCP Server**\n\nOn first use, the skill will guide you through setup:\n\n1. Open the [DingTalk AI Hub MCP page](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) and activate the service\n2. Copy the **StreamableHttp URL** from the page\n3. Paste it into the Claude conversation\n\nThe skill automatically registers the MCP server. For Claude Code:\n\n```bash\nclaude mcp add --transport http --scope user dingtalk-doc \"\"\n```\n\nFor other clients (Claude Desktop, Cursor, etc.), configure a StreamableHttp MCP server manually.\n\n**3. (Optional) Set a Default Knowledge Base**\n\nProvide your knowledge base URL so you don't have to specify it every time:\n\n```\nhttps://alidocs.dingtalk.com/i/spaces/xxxxx/overview\n```\n\n### Usage Examples\n\nJust talk to Claude naturally:\n\n- *\"Push `docs/design.md` to my DingTalk knowledge base\"*\n- *\"Update the PRD document on DingTalk with the latest local version\"*\n- *\"List all documents in my knowledge base\"*\n- *\"Search DingTalk docs for 'authentication'\"*\n- *\"Pull the meeting notes from DingTalk to local\"*\n- *\"Delete the test document from DingTalk\"*\n\n### How It Works\n\n```\nUser request\n → Skill activation (matched by description trigger)\n → MCP tool mapping (create / update / list / search / delete ...)\n → Pre-execution confirmation (for all write operations)\n → DingTalk Document MCP Server\n → Result: document title + link\n```\n\n### Known Limitations\n\n| Limitation | Detail |\n|---|---|\n| **Mermaid diagrams** | ` ```mermaid ` blocks are pushed as plain code blocks, not DingTalk's native \"text drawing\" blocks. Manually convert after pushing. |\n| **File encoding on chat upload** | Non-ASCII files (Chinese, etc.) uploaded through the chat may suffer irreversible garbled text. Always provide a **local file path**. |\n| **Document types** | `create_document` and `update_document` only support **adoc** (text document) type. |\n| **Deletion** | Moves to trash (recoverable within 30 days), not permanent deletion. |\n\n### Security\n\n- The MCP server URL contains a personal API key — written to local config only, **never committed to version control**\n- All write operations require explicit user confirmation before execution\n\n### File Structure\n\n```\n.claude/skills/dingtalk-docs-skill/\n├── SKILL.md # Skill entry point (trigger + instructions)\n├── README.md # This file\n├── evals/\n│ ├── evals.json # Task execution evals\n│ └── trigger-evals.json # Trigger boundary evals\n└── references/\n └── mcp-tools.md # MCP tool reference\n```\n\n### License\n\nMIT\n\nFile v1.0.0:_meta.json\n\n{\n \"ownerId\": \"kn7facsvhzy0pcacszzatx32th87jknt\",\n \"slug\": \"dingtalk-docs-skill\",\n \"version\": \"1.0.0\",\n \"publishedAt\": 1779963228932\n}\n\nFile v1.0.0:references/mcp-tools.md\n\n# 钉钉文档 MCP 工具速查\n\nMCP 名称：`dingtalk-doc`（注册方式见 SKILL.md 初始化流程）\n\n---\n\n## 文档内容操作\n\n### create_document\n创建文字类型（adoc）钉钉文档，支持带初始 markdown 内容。\n\n- 关键参数：`title`（标题）、`content`（markdown 正文）、`parentNodeId`（父节点 ID，指定放置位置）\n- 返回：新文档的 `dentryUuid`、文档链接\n- 注意：只能创建 adoc 类型，不能创建表格/演示等\n\n### update_document\n更新文字类型（adoc）文档的内容，支持两种模式：\n\n- `overwrite`：覆盖全部内容（常用于推送本地文件）\n- `append`：追加到文档末尾\n- 关键参数：`dentryUuid`、`content`（markdown）、`updateMode`（overwrite/append）\n- 限制：**仅支持 adoc 类型文档**，其他类型会报错\n\n### get_document_content（高敏感）\n获取文档的 markdown 正文内容。\n\n- 关键参数：`dentryUuid`\n- 用途：读取文档内容、做差异对比后再更新\n\n---\n\n## 块级精确编辑\n\n适用于需要在文档特定位置插入/修改/删除段落、标题、表格等场景。\n\n### list_document_blocks\n列出文档的一级块元素（段落、标题、表格等）。\n\n- 关键参数：`dentryUuid`，支持按起始/终止位置和块类型过滤\n- 返回：blockId 列表，供后续插入/更新/删除使用\n\n### insert_document_block\n在文档指定位置插入新块元素。\n\n- 关键参数：`dentryUuid`、`blockType`（块类型）、块内容属性对象\n- 支持类型：段落、标题、表格、高亮块、列表等\n\n### update_document_block\n更新指定块元素的内容或样式。\n\n- 关键参数：`dentryUuid`、`blockId`、新内容（含 `blockType` 和属性对象）\n\n### delete_document_block\n删除指定块元素。\n\n- 关键参数：`dentryUuid`、`blockId`\n- 需有编辑权限\n\n---\n\n## 文档/节点查找\n\n### search_documents\n按关键词搜索当前用户有权限访问的文档。\n\n- 关键参数：`keyword`（匹配标题和内容）、可选过滤条件（类型、时间范围等）\n- 用途：在不知道 dentryUuid 时定位目标文档\n\n### list_nodes\n列出指定文件夹或知识库下的直接子节点（文件夹/文档/文件）。\n\n- 关键参数：`parentNodeId`（知识库 ID 或文件夹节点 ID），支持分页\n- 注意：**只返回直接子节点，不递归**；需要更深层列表时多次调用\n\n### get_document_info\n获取节点的元信息（标题、类型、创建者、创建时间等）。\n\n- 关键参数：`nodeId`（支持文档 URL 或 dentryUuid）\n- 返回的 `contentType` 字段可判断文档类型（adoc/sheet/ppt 等）\n\n---\n\n## 文件夹与节点管理\n\n### create_folder\n在指定位置创建文件夹，返回新文件夹的节点 ID。\n\n- 关键参数：`name`（文件夹名）、`parentNodeId`（父节点）\n\n### create_file\n创建各类型节点（文档、表格、演示、白板、脑图、多维表、文件夹）。\n\n- 支持三种创建位置（优先级顺序）：指定 folderId、指定 workspaceId、默认位置\n- 与 `create_document` 的区别：`create_file` 可创建所有类型，但不支持带初始内容\n\n### delete_document\n将节点移入回收站（30 天内可恢复，超过 30 天永久删除）。\n\n- 支持：知识库下的文档节点、文件夹节点、钉盘文件\n- **执行前需告知用户这是移入回收站，获得确认后再调用**\n\n### rename_document\n重命名节点（知识库下的文档/文件夹节点）。\n\n### move_document\n将节点移动到目标文件夹。\n\n- 支持：知识库节点、钉盘文件/文件夹\n- `nodeId` 支持文档 URL 或 dentryUuid\n\n### copy_document\n将节点复制到目标文件夹。\n\n- 与 `move_document` 参数相同，区别是原节点保留\n\n---\n\n## 文件上传（非 adoc 文件）\n\n上传本地文件（PDF、图片、Word 等）到钉钉文档/知识库，分三步：\n\n1. **get_file_upload_info** — 获取 OSS 上传凭证（第一步）\n2. **HTTP PUT** — 使用凭证将文件直传 OSS（Claude 代理发起 HTTP 请求）\n3. **commit_uploaded_file** — 提交完成文件入库（第三步）\n\n### get_file_upload_info\n- 关键参数：`fileName`、`fileSize`、目标位置（folderId 或 workspaceId）\n\n### commit_uploaded_file\n- 关键参数：上传凭证中的 `uploadKey`\n\n---\n\n## 权限管理\n\n### add_permission\n为知识库节点添加企业用户成员（指定角色）。\n\n### update_permission\n修改企业用户在节点上的角色。\n\n### list_permission\n查询节点当前的成员权限列表。\n\n---\n\n## 导出\n\n将文档异步导出为 PDF 或 Word 等格式，分两步：\n\n### submit_export_job\n提交导出任务，返回 `jobId`。\n\n- 关键参数：`dentryUuid`、`exportType`（`pdf` / `docx` 等）\n- 返回：`jobId`，供轮询使用\n\n### query_export_job\n查询导出任务状态，直到完成为止。\n\n- 关键参数：`jobId`\n- 返回：任务状态；完成时包含下载链接\n- 注意：需轮询直至状态为成功，建议间隔 1-2 秒\n\n---\n\n## 附件操作\n\n### get_doc_attachment_upload_info\n获取向指定文档上传附件所需的 OSS 凭证（文档内嵌附件，非知识库文件）。\n\n### download_doc_attachment\n获取文档内指定附件的临时下载 URL。\n\n- 关键参数：`nodeId`（文档标识）、`resourceId`（附件资源标识）\n\n### download_file\n获取钉盘文件的下载凭证，供 Claude 发起 HTTP GET 下载。\n\nFile v1.0.0:skill-card.md\n\n## Description:
\nDingtalk Docs Skill helps agents read, push, sync, export, and manage DingTalk cloud documents through DingTalk's official MCP Server.
\n\nThis skill is ready for commercial/non-commercial use.
\n\n## Publisher:
\n[cpsean](https://clawhub.ai/user/cpsean)
\n\n### License/Terms of Use:
\nMIT-0
\n\n\n## Use Case:
\nDevelopers and teams that work in DingTalk Docs use this skill to connect an MCP-capable agent to DingTalk documents, sync local Markdown, retrieve cloud content, manage folders and files, export documents, and update permissions.
\n\n### Deployment Geography for Use:
\nGlobal
\n\n## Known Risks and Mitigations:
\nRisk: The DingTalk MCP URL contains sensitive personal credentials.
\nMitigation: Treat the URL as a secret, write it only to local MCP configuration, avoid repeating it in responses, and do not commit it to version control.
\nRisk: The skill can access and manage DingTalk documents, exports, folders, and permissions.
\nMitigation: Confirm the target workspace, document, operation, and permission changes before write, export, upload, delete, or access-control actions.
\nRisk: Project-level installs can place default workspace configuration inside the skill directory.
\nMitigation: Prefer user-level configuration for shared projects or verify the default workspace config is ignored before committing repository changes.
\n\n\n## Reference(s):
\n- [DingTalk Docs MCP Tool Reference](references/mcp-tools.md)
\n- [DingTalk AI Hub MCP Service](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail)
\n- [DingTalk Developer Getting Started](https://open.dingtalk.com/document/dingstart/dingtalk-developer)
\n- [DingTalk Docs](https://alidocs.dingtalk.com)
\n\n\n## Skill Output:
\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration, Guidance]
\n**Output Format:** [Markdown with inline shell commands, JSON configuration snippets, and DingTalk document links]
\n**Output Parameters:** [1D]
\n**Other Properties Related to Output:** [May issue DingTalk MCP tool calls after user confirmation for write operations; handles sensitive MCP URLs as local configuration.]
\n\n## Skill Version(s):
\n1.0.0 (source: server release metadata)
\n\n## Ethical Considerations:
\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.
\n\nFile v1.0.0:evals/evals.json\n\n{\n \"skill_name\": \"dingtalk-docs-skill\",\n \"evals\": [\n {\n \"id\": 1,\n \"prompt\": \"我有一个本地文件 weekly-report.md，内容是本周工作总结，帮我把它推送到钉钉知识库，放在「周报」文件夹下，标题叫「2026-W18 周报」。\",\n \"expected_output\": \"调用 list_nodes 或 search_documents 找到「周报」文件夹的 nodeId，然后调用 create_document 创建文档，读取 weekly-report.md 内容作为 content 参数，最后返回文档标题和访问链接。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 create_document MCP 工具\",\n \"文档标题包含「2026-W18 周报」\",\n \"输出包含文档访问链接或 dentryUuid\",\n \"没有跳过定位父文件夹的步骤\"\n ]\n },\n {\n \"id\": 2,\n \"prompt\": \"帮我更新钉钉上的「产品需求文档 v2」，把本地的 prd-v2.md 内容覆盖上去。\",\n \"expected_output\": \"先调用 search_documents 找到目标文档的 dentryUuid，确认文档类型是 adoc，然后调用 update_document 以 overwrite 模式更新内容，最后返回更新结果和文档链接。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 search_documents 或 get_document_info 定位文档\",\n \"调用了 update_document 且 updateMode 为 overwrite\",\n \"输出包含操作成功的确认信息\"\n ]\n },\n {\n \"id\": 3,\n \"prompt\": \"帮我配置钉钉文档 MCP，我现在是第一次用。\",\n \"expected_output\": \"输出初始化引导步骤：提供开通链接、说明需要登录并开通服务、说明复制 StreamableHttp URL、说明后续 Claude 会写入 settings.json。不调用任何 MCP 文档工具。\",\n \"files\": [],\n \"assertions\": [\n \"输出包含 aihub.dingtalk.com 开通链接\",\n \"说明需要复制 StreamableHttp URL\",\n \"提到需要重启 Claude Code\",\n \"没有尝试直接调用 create_document 等文档操作工具\"\n ]\n },\n {\n \"id\": 4,\n \"prompt\": \"列出钉钉知识库根目录下的所有文档。\",\n \"expected_output\": \"调用 list_nodes 并传入知识库根节点 ID（如果用户未提供则先询问或说明需要知识库 ID），返回文档节点列表（标题、类型、节点 ID）。\",\n \"files\": [],\n \"assertions\": [\n \"调用了 list_nodes MCP 工具\",\n \"如果缺少知识库 ID 则向用户说明而不是猜测\",\n \"输出展示了文档列表或明确说明缺少必要参数\"\n ]\n }\n ]\n}\n\nFile v1.0.0:evals/trigger-evals.json\n\n{\n \"skill_name\": \"dingtalk-docs-skill\",\n \"evals\": [\n {\n \"query\": \"帮我把这个 markdown 文件推送到钉钉文档\",\n \"should_trigger\": true\n },\n {\n \"query\": \"更新钉钉上的周报文档，用本地最新版本覆盖\",\n \"should_trigger\": true\n },\n {\n \"query\": \"列出我的钉钉知识库里有哪些文档\",\n \"should_trigger\": true\n },\n {\n \"query\": \"在钉钉文档里搜索项目计划\",\n \"should_trigger\": true\n },\n {\n \"query\": \"初始化钉钉文档 MCP 配置\",\n \"should_trigger\": true\n },\n {\n \"query\": \"在钉钉知识库里创建一个新文件夹叫「产品设计」\",\n \"should_trigger\": true\n },\n {\n \"query\": \"把这篇技术文档同步到钉钉知识库\",\n \"should_trigger\": true\n },\n {\n \"query\": \"帮我把这个文件推送到语雀\",\n \"should_trigger\": false\n },\n {\n \"query\": \"帮我编辑本地的 README.md，修改第三段\",\n \"should_trigger\": false\n },\n {\n \"query\": \"给钉钉群里发一条消息通知大家\",\n \"should_trigger\": false\n },\n {\n \"query\": \"帮我把文档上传到飞书知识库\",\n \"should_trigger\": false\n },\n {\n \"query\": \"把这个 md 文件格式化一下，不需要上传\",\n \"should_trigger\": false\n }\n ]\n}","readmeExcerpt":"Skill: dingtalk-docs-skill Owner: cpsean Summary: 当用户想要操作钉钉文档或向钉钉知识库推送本地文件时使用本 Skill。支持：将 Markdown/纯文本推送为可编辑钉钉文档、原格式上传 HTML/图片/PDF/Office 等文件、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。 Tags: latest:1.0.3 Version history: v1.0.3 | 2026-09-10T13:42:08.952Z | user dingtalk-docs-skill 1.0.3 - Break","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"git clone https://github.com/CPsean/dingtalk-docs-skill \\\n ~/.claude/skills/dingtalk-docs-skill"},{"language":"powershell","snippet":"git clone https://github.com/CPsean/dingtalk-docs-skill `\n \"$env:USERPROFILE\\.claude\\skills\\dingtalk-doc\""},{"language":"bash","snippet":"git clone https://github.com/CPsean/dingtalk-docs-skill \\\n .claude/skills/dingtalk-docs-skill"},{"language":"bash","snippet":"claude mcp add --transport http --scope user dingtalk-doc \"<你的 URL>\""},{"language":"text","snippet":"https://alidocs.dingtalk.com/i/spaces/xxxxx/overview"},{"language":"text","snippet":"用户请求\n → Skill 激活（通过 description 触发词匹配）\n → MCP 工具映射（create / update / list / search / delete ...）\n → 执行前确认（所有写操作需用户确认）\n → 钉钉文档 MCP Server\n → 返回结果：文档标��� + 链接"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\r\nname: dingtalk-docs-skill\r\ndescription: 当用户想要操作钉钉文档或向钉钉知识库推送本地文件时使用本 Skill。支持：将 Markdown/纯文本推送为可编辑钉钉文档、原格式上传 HTML/图片/PDF/Office 等文件、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。\r\ncompatibility: Requires dingtalk-doc MCP server (StreamableHttp transport). Compatible with any MCP-capable agent (Claude Code, Cursor, VS Code, Roo Code, Gemini CLI, Codex, etc.). Auto-detects Claude Code; falls back to writing config files or manual setup for other agents.\r\n---\r\n\r\n# 钉钉文档\r\n\r\n通过钉钉文档官方 MCP Server 全面操作云端文档。\r\n\r\n## 语言规则\r\n\r\n**始终使用用户输入的语言进行回复。** 如果用户用英文提问，则全程用英文回复；如果用户用中文，则全程用中文回复。无法判断时默认使用中文。\r\n\r\n## 能力范围\r\n\r\n**读**\r\n- 拉取云端文档正文为 markdown（保存到本地）\r\n- 列出知识库/文件夹下的文档节点\r\n- 按关键词搜索文档\r\n- 获取文档元信息（标题、类型、创建时间等）\r\n- 下载钉盘文件或文档内嵌附件\r\n\r\n**写**\r\n- 按内容类型将本地内容推送到知识库：创建可编辑的 adoc 文档，或保留原格式上传文件\r\n- 覆盖或追加内容到已有文档\r\n- 按块精确编辑（插入/更新/删除段落、标题、表格等）\r\n- 上传本地文件（PDF、图片、Word 等）到知识库\r\n- 将本地图片**内联**嵌入文档正文（自动上传转存为内联图，非占位符人工粘贴）\r\n\r\n**管理**\r\n- 创建文件夹\r\n- 重命名/移动/复制/删除文档和文件夹\r\n- 导出文档为 PDF 或 Word 格式\r\n- 查看/添加/修改知识库节点的成员权限\r\n\r\n**不负责：**\r\n- 飞书、语雀、Notion 等其他平台\r\n- 只修改本地文件（无云端操作）\r\n- 钉钉 IM 消息、企业成员管理\r\n\r\n## 前置条件\r\n\r\n钉钉文档 MCP Server 必须已配置到当前 Agent 的 MCP 设置中，服务名称为 `dingtalk-doc`。\r\n\r\n如果 MCP 工具不可用，先走**初始化流程**，再执行任何文档操作。\r\n\r\n## 初始化流程（首次使用或 MCP 不可用时）\r\n\r\n1. 告知用户访问帮助手册页面并完成开通：\r\n > 请打开以下链接，使用钉钉账号登录后，点击页面上的【开通服务】按钮：\r\n > https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail\r\n\r\n2. 开通后复制页面右侧 **StreamableHttp URL**（不是 JSON Config）\r\n\r\n3. 请用户将 URL 粘贴给你\r\n\r\n4. 收到 URL 后，**先做两项安全校验，再注册**：\r\n\r\n **① URL 域名白名单**：只接受钉钉官方域名——`aihub.dingtalk.com`、`alidocs.dingtalk.com` 及其它 `*.dingtalk.com` 子域。若 URL 域名不在白名单内，**停止注册**并提示用户「该 URL 非钉钉官方域名，可能填错或有风险，请核对」，用户确认后再继续。此举防止把 MCP 流量（含个人 API Key）导向恶意/错误 endpoint。\r\n\r\n **② 写前确认（不静默改用户环境）**：写任何配置文件前，先向用户展示**目标文件完整路径 + 将写入的确切 JSON 内容**，用户显式同意后再写；只追加 `dingtalk-doc` 新条目，绝不覆盖或改动文件里已有的其它配置。\r\n\r\n 两项校验通过后，按以下顺序尝试注册 MCP 服务（`dingtalk-doc` 为服务名，必须为 ASCII）：\r\n\r\n **方案 A — Claude Code**（优先尝试；默认项目级 scope，运行前把命令展示给用户）：\r\n ```bash\r\n claude mcp add --transport http --scope local dingtalk-doc \"<用户提供的 URL>\"\r\n ```\r\n - `--scope local`：仅当前项目生效（项目级，影响面最小）。用户明确希望所有项目通用时，才改 `--scope user`（全局），改前先确认。\r\n - 成功则跳到步骤 5。\r\n\r\n **方案 B — 写入配置文件**（通用方案，大多数 Agent 均可用）：\r\n\r\n **优先项目级、全局需确认**：优先写 workspace 内的**项目级**配置（影响面最小、随项目走、不碰用户全局环境）；仅当该 Agent 没有项目级配置项（如 Gemini CLI、OpenAI Codex 只有全局），或用户明确同意写全局时，才写**全局用户级**配置，且写前必须按步骤 4 ② 展示路径 + 内容确认。\r\n\r\n 检测当前环境存在哪些配置文件，找到第一个匹配项写入：\r\n\r\n | Agent | 配置文件（项目级，优先写这个） | 配置文件（全局，仅无项目级或用户确认后写） | `mcpServers` 键名 |\r\n |-------|----------------|----------------|-----------------|\r\n | Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json`（写前确认） | `mcpServers` |\r\n | VS Code Copilot | `.vscode/mcp.json` | `~/Library/Application Support/Code/User/mcp.json`（Mac）
`%APPDATA%\\Code\\User\\mcp.json`（Win）（写前确认） | `servers` |\r\n | Roo Code | `.roo/mcp.json` | —（无全局需求） | `mcpServers` |\r\n | Gemini CLI | —（无项目级） | `~/.gemini/settings.json`（仅全局，写前确认） | `mcpServers` |\r\n | Open"},{"path":"README.md","content":"# dingtalk-docs-skill\n\n[English](#english) | [中文](#中文)\n\n---\n\n## 中文\n\n**dingtalk-docs-skill** 是一个兼容多平台的 Agent Skill，通过钉钉文档官方 MCP Server 全面操作钉钉云端文档，支持读取、推送、同步、导出、权限管理等。\n\n### 功能\n\n| 类别 | 能力 |\n|------|------|\n| **读** | 拉取云端文档正文为 markdown、列出知识库/文件夹文档、按关键词搜索、获取文档元信息、下载钉盘文件与文档附件 |\n| **写** | 将 Markdown/纯文本推送为可编辑钉钉文档、按原格式上传 HTML/图片/PDF/Office 等文件、将本地图片内联嵌入文档正文、覆盖/追加更新文档内容、块级精确编辑（段落/标题/表格等） |\n| **管理** | 创建文件夹、重命名/移动/复制/删除文档和文件夹、导出文档为 PDF/Word、管理节点成员权限 |\n\n所有操作通过[钉钉官方 MCP Server](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail) 完成，无需本地脚本，API Key 不会写入代码。\n\n### 快速开始\n\n**1. 安装 Skill**\n\n**用户级安装**（推荐，所有项目均可使用）：\n\nmacOS / Linux：\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n ~/.claude/skills/dingtalk-docs-skill\n```\n\nWindows（PowerShell）：\n```powershell\ngit clone https://github.com/CPsean/dingtalk-docs-skill `\n \"$env:USERPROFILE\\.claude\\skills\\dingtalk-doc\"\n```\n\n**项目级安装**（仅当前项目可用）：\n\n```bash\ngit clone https://github.com/CPsean/dingtalk-docs-skill \\\n .claude/skills/dingtalk-docs-skill\n```\n\n安装后重启 Claude Code 使 Skill 生效。\n\n**2. 开通钉钉文档 MCP 服务**\n\n首次使用时，Skill 会引导你完成配置：\n\n1. 打开[钉钉 AI Hub MCP 页面](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail)，登录钉钉账号，点击【开通服务】\n2. 复制页面右侧的 **StreamableHttp URL**（不是 JSON Config）\n3. 将 URL 粘贴给 Claude\n\nSkill 会自动注册 MCP 服务。Claude Code 客户端执行：\n\n```bash\nclaude mcp add --transport http --scope user dingtalk-doc \"<你的 URL>\"\n```\n\n其他客户端（Claude Desktop、Cursor 等）需手动配置 StreamableHttp 类型的 MCP 服务。\n\n**3.（可选）设置默认知识库**\n\n提供你常用的知识库 URL，后续操作无需每次指定：\n\n```\nhttps://alidocs.dingtalk.com/i/spaces/xxxxx/overview\n```\n\n### 使用示例\n\n直接用自然语言和 Claude 对话即可：\n\n- *\"把 `docs/design.md` 推送到我的钉钉知识库\"*\n- *\"用本地最新版本更新钉钉上的 PRD 文档\"*\n- *\"把这篇带本地截图的 markdown 推到钉钉，图片要能正常显示\"*\n- *\"列出我知识库里的所有文档\"*\n- *\"在钉钉文档里搜索「认证」\"*\n- *\"把会议纪要从钉钉拉取到本地\"*\n- *\"删除钉钉上的测试文档\"*\n\n### 工作流程\n\n```\n用户请求\n → Skill 激活（通过 description 触发词匹配）\n → MCP 工具映射（create / update / list / search / delete ...）\n → 执行前确认（所有写操作需用户确认）\n → 钉钉文档 MCP Server\n → 返回结果：文档标��� + 链接\n```\n\n### 已知限制\n\n| 限制项 | 详情 |\n|---|---|\n| **Mermaid 流程图** | ` ```mermaid ` 代码块推送后显示为普通代码块，而非钉钉原生「文本绘图」。推送后需在钉钉编辑器中手动转换。 |\n| **对话上传文件编码** | 非 ASCII 文件（中文等）通过对话上传时可能出现不可逆乱码。请始终提供**本地文件路径**。 |\n| **文档类型** | `create_document` 和 `update_document` 仅支持 **adoc**（文字类型）文档。 |\n| **非 adoc 读取** | `get_document_content` 只可读取 adoc。`axls` 表格需使用当前会话实际可用的表格工具；工具不可用时请直接提供所需内容或导出文件。`dlink` 快捷方式需先解析目标原始 nodeId，并按该 ID 去重。 |\n| **推送类型选择** | Markdown/纯文本默认创建可编辑 adoc；HTML、图片、PDF、Office 等默认按原格式上传到知识库，不会擅自转换。 |\n| **Markdown 大文件** | `.md` / `.markdown` 优先创建 adoc；正文超过 9,500 字符时，先由用户选择分段 adoc 或原样上传 MD 文件。 |\n| **方案不明确** | 文件格式、保留原格式或在线编辑需求不明确时，先确认推送方案；方案确认不替代云端写入前的确认。 |\n| **删除** | 移入回收站（30 天内可恢复），非永久删除。 |\n| **本地图片内联** | 需内联进正文的图片走 `get_doc_attachment_upload_info` → PUT → `download_doc_attachment` 取签名 URL → 写入 `` 自动转存链路。**统一用签名 URL，勿依赖 `resourceUrl`**（资源不可达时会得到「暂无权限访问」占位插画）。所有写操作串行，推送后做字节级校验。 |\n\n### 安全性\n\n- MCP 服务 URL 包含个人 API Key，仅写入本地配置，**不会提交到版本控制**\n- 所有写操作执行前都需要用户明确确认\n\n### 文件结构\n\n```\n.claude/skills/dingtalk-docs-skill/\n├── SKILL.md "},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7facsvhzy0pcacszzatx32th87jknt\",\n \"slug\": \"dingtalk-docs-skill\",\n \"version\": \"1.0.3\",\n \"publishedAt\": 1789047728952\n}"},{"path":"references/mcp-tools.md","content":"# 钉钉文档 MCP 工具速查\n\nMCP 名称：`dingtalk-doc`（注册方式见 SKILL.md 初始化流程）\n\n---\n\n## 文档内容操作\n\n### create_document\n创建文字类型（adoc）钉钉文档，支持带初始 markdown 内容。\n\n- 关键参数：`name`（文档标题，必填）、`markdown`（初始正文）、`folderId`（目标文件夹节点）、`workspaceId`（知识库 ID）\n- 放置位置优先级：`folderId` > `workspaceId` > 两者都不传时建在「我的文档」根目录\n- 返回：新文档的 `dentryUuid`、文档链接\n- **`markdown` 换行必须用真实换行符（U+000A）**，不能是字面量 `\\n`，否则标题/段落/表格会全部渲染在同一行\n- 上限 **10000 字符**，超出改用 `update_document` 分批 append\n- 注意：只能创建 adoc 类型；表格/演示等其他类型用 `create_file`\n\n### update_document\n更新文字类型（adoc）文档的内容，支持两种模式：\n\n- `overwrite`（默认）：清空全文后重写，**会丢失原有图片/评论**，谨慎使用\n- `append`：追加内容，可配合 `index` 精确插入到指定块之前\n- 关键参数：`nodeId`（文档 URL 或 dentryUuid）、`markdown`（正文）、`mode`（overwrite/append）、`index`（仅 append 生效）、`format`（markdown/jsonml，默认 markdown）\n- **`index` 语义**：从 0 开始，表示插入到文档第 index 个块**之前**；不传则追加到末尾。index 由 `list_document_blocks` 获取\n- **index 位移规则**：插入成功后，该位置及其后所有块的 index 依次 **+1**；批量插/删须按此重算，或采用「先加后删配对完成」避免连锁位移\n- **`markdown` 换行必须用真实换行符（U+000A）**，不能是字面量 `\\n`\n- 上限 **10000 字符**，超出分批 append\n- 限制：**仅支持 adoc 类型文档**，其他类型会报错\n\n### get_document_content（高敏感）\n获取文档的 markdown 正文内容。\n\n> ⚠️ **敏感读取边界**：本操作把云端文档正文**拉进当前对话上下文**。遵循最小化——只读当前任务确需的文档、不批量拉全文；请求模糊或命中多目标时**先确认具体是哪一篇**再读；读取内容仅用于当前任务，不外传、不写入无关文件。\n\n- 关键参数：`nodeId`（文档 URL 或 dentryUuid）\n- 用途：读取文档内容、做差异对比后再更新、核对图片是否内联成功（返回 markdown 中可见 ``）\n- **仅适用于 `adoc` 文字文档**。调用前通过 `get_document_info` 或结果中的 `contentType` 确认类型\n- `axls`（钉钉表格）、`dlink`（快捷方式）及其他非 `adoc` 节点会报错或不提供正文，禁止将报错视为可重试错误\n- 对 `axls`，仅在当前会话确实提供表格读取工具时使用该工具；工具不可用时请用户粘贴所需内容或提供导出文件\n- 对 `dlink`，先解析其指向的原始 nodeId，再对原节点执行后续查询。检索结果按原始 nodeId 去重，优先保留原节点\n\n---\n\n## 块级精确编辑\n\n适用于需要在文档特定位置插入/修改/删除段落、标题、表格等场景。\n\n### list_document_blocks\n列出文档的一级块元素（段落、标题、表格等）。\n\n- 关键参数：`nodeId`（文档 URL 或 dentryUuid）、`startIndex`/`endIndex`（范围）、`blockType`（过滤）、`format`（element/jsonml，默认 element）\n- 返回：各块的 `blockId` 与 `index`，供 `update_document(index)` / insert / update / delete_document_block 定位使用\n- **图片块识别坑**：element 格式下，内联图片块表现为**空文本 paragraph**，与真空段落无法区分；核对图片请用 markdown 视图（`get_document_content`）或导出，不要依赖 element 列表\n\n### insert_document_block\n在文档指定位置插入新块元素。\n\n- 关键参数：`nodeId`、`element`（含 `blockType` 及对应属性对象）、定位用 `referenceBlockId`（优先）或 `index`、`where`（before/after，默认 after）、`format`（element/jsonml）\n- 支持类型：paragraph/heading/blockquote/callout/columns/orderedList/unorderedList/table/attachment 等\n- **行内 image 不可用**：`element.children` 的 `properties.src`（图片 Url）虽在 schema 中声明，但实测插入行内 image 会报 **\"Undefined block element\"**。**不要用本工具插图**，改走 markdown 导入链路（见「本地图片内联到文档正文」）\n- **attachment 的 `size` 必须省略**：`size`（number）经 MCP 桥接层会被序列化成字符串，报 **\"expected number, but got string\"**；插入 attachment 块时省略 size\n- **attachment 块 ≠ 内联图**：attachment 块导出为 `[文件名](链接)` 的附件卡片，不是内联图片；仅在图片内联链路中作为临时上传媒介，转存成功后即删除\n\n### update_document_block\n更新指定块元素的内容或样式。\n\n- 关键参数：`nodeId`、`blockId`、`element`（含 `blockType` 和属性对象）\n\n### delete_document_block\n删除指定块元素。\n\n- 关键参数：`nodeId`、`blockId`（支持逗号分隔批量删除，一次最多 50 个；未命中的列入返回的 `notFoundBlockIds`）\n- 需有编辑权限\n- **删后必须复核**：并行/连续删除曾出现「返回成功但未删或误删邻块」，删除后务必用 `list_document_blocks` 复核结果\n\n---\n\n## 文档/节点查找\n\n### search_documents\n按"},{"path":"skill-card.md","content":"## Description:\n\nA DingTalk Docs agent skill for reading, creating, updating, exporting, downloading, and managing DingTalk cloud documents through the official dingtalk-doc MCP server.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cpsean](https://clawhub.ai/user/cpsean)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal developers and agent users use this skill to connect an MCP-capable agent to DingTalk Docs, push local Markdown or files into a knowledge base, sync or export cloud documents, and manage folders and permissions with confirmation before writes.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: A personal API-key URL may be persisted in agent configuration or exposed in chat or logs.\n\nMitigation: Use only an official HTTPS DingTalk MCP URL, prefer project-local configuration, do not commit or share MCP config files containing the URL, and rotate the URL if it was pasted or logged.\n\nRisk: MCP traffic could be directed to a non-DingTalk endpoint if endpoint checks are bypassed.\n\nMitigation: Approve only official DingTalk domains for MCP URLs and reject non-DingTalk endpoints before registering the server.\n\nRisk: Cloud document reads, downloads, exports, and uploads move data between the local environment and DingTalk and can create portable copies or temporary signed links.\n\nMitigation: Confirm write and transfer operations with the user, read only the documents needed for the task, disclose where data will go, and avoid long-term sharing of temporary download links.\n\n## Reference(s):\n\n- [DingTalk Docs MCP tool reference](references/mcp-tools.md)\n- [DingTalk AI Hub MCP page](https://aihub.dingtalk.com/#/detail?mcpId=9629&detailType=marketMcpDetail)\n- [DingTalk Developer guide](https://open.dingtalk.com/document/dingstart/dingtalk-developer)\n- [DingTalk Docs](https://alidocs.dingtalk.com)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Markdown, Shell commands, Configuration]\n\n**Output Format:** [Markdown with inline shell commands and configuration snippets]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May propose MCP tool calls and file-transfer workflows; write operations require user confirmation.]\n\n## Skill Version(s):\n\n1.0.3 (source: server release metadata)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"当用户想要操作钉钉文档或向钉钉知识库推送本地文件时使用本 Skill。支持：将 Markdown/纯文本推送为可编辑钉钉文档、原格式上传 HTML/图片/PDF/Office 等文件、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。 Skill: dingtalk-docs-skill Owner: cpsean Summary: 当用户想要操作钉钉文档或向钉钉知识库推送本地文件时使用本 Skill。支持：将 Markdown/纯文本推送为可编辑钉钉文档、原格式上传 HTML/图片/PDF/Office 等文件、拉取云端文档到本地、覆盖/追加更新文档内容、块级精确编辑、搜索与列出知识库文档、下载文件与附件、导出文档为 PDF/Word、管理节点权限、创建/重命名/移动/复制/删除文档与文件夹、初始化钉钉文档 MCP 配置。当用户想操作飞书、语雀、Notion 等其他平台、只修改本地文件、管理钉钉 IM 消息或群组时，不要使用本 Skill。 Tags: latest:1.0.3 Version history: v1.0.3 | 2026-09-10T13:42:08.952Z | user dingtalk-docs-skill 1.0.3 - Break","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1413,"uniquenessScore":47,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:51:20.357Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T20:51:20.357Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-12T03:49:43.882Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}