dingtalk-docs

核心用法

钉钉云文档 Skill 提供企业级文档生命周期管理能力，涵盖六大核心操作：获取根目录、搜索文档、创建在线文档、创建多类型节点（文件夹/表格/PPT/脑图/多维表）、写入内容以及条件性读取。

关键操作路径：

• 创建文档：必须先调 get_my_docs_root_dentry_uuid 获取根目录 ID，再执行 create_doc_under_node
• 创建文件夹：使用 create_dentry_under_node 并指定 accessType="13"
• 写入内容：强制区分 updateType——0 为覆盖清空，1 为追加续写，类型传反会导致数据丢失
• 读取内容：依赖 get_document_content_by_url，该接口目前处于官方灰度阶段，非全量可用

显著优点

• 企业级集成：原生对接钉钉云文档生态，支持在线协作场景
• 类型覆盖全：文档、表格、PPT、脑图、多维表、文件夹一站式管理
• 写入灵活：覆盖/续写双模式，适应不同编辑需求
• 搜索能力：支持关键词检索有权限的文档

潜在缺点与局限性

• 读取能力受限：get_document_content_by_url 官方明确灰度中，大量实例尚未开放，导致"读文档"需求可能无法满足
• 参数类型敏感：accessType 必须为字符串、updateType 必须为数字，类型错误会导致静默失败而非明确报错
• ID 依赖链长：任何创建/写入操作都依赖前置 API 返回的 dentryUuid，无法直接通过名称操作
• URL 拼接要求：读文档时必须拼成完整 https://alidocs.dingtalk.com/i/nodes/{id} 格式，仅传 ID 会报错
• 多维表 vs 在线表格易混淆：用户说"表格"时需二次确认类型，默认行为可能导致创建错误

适合人群

• 钉钉企业用户，需批量创建/整理云文档
• 需要程序化写入文档内容（日报、会议纪要模板等）
• 能接受"先搜索、再手动打开"替代方案的用户（在读接口未放量时）

常规风险

• 数据丢失风险：updateType 传错会静默覆盖或错误追加
• 灰度不确定性：读能力不可预期，向用户承诺前必须确认实例是否暴露该方法
• 凭证配置风险：涉及企业文档权限，凭证泄露可能导致敏感信息暴露

核心用法

dingtalk-docs 是一款面向钉钉云文档的 MCP Skill，提供完整的文档生命周期管理能力。核心工作流遵循严格的 ID 依赖链：创建文档前必须先获取"我的文档"根目录 ID（get_my_docs_root_dentry_uuid），再执行创建操作（create_doc_under_node 或 create_dentry_under_node），最后通过 write_content_to_document 写入内容。读取文档内容需拼接完整 URL https://alidocs.dingtalk.com/i/nodes/{dentryUuid} 调用 get_document_content_by_url，但该方法目前处于官方灰度阶段，部分实例尚未开放。支持多类型节点创建：在线文档（专用接口）、表格（accessType="1"）、PPT（"2"）、脑图（"6"）、多维表（"7"）、文件夹（"13"），需注意参数类型严格区分——accessType 为字符串，updateType 为数字。

显著优点

生态深度整合：直接对接钉钉官方 alidocs 服务，与企业现有钉钉组织架构无缝衔接，权限体系天然继承。

操作类型丰富：覆盖文档、表格、PPT、脑图、多维表、文件夹六大内容形态，满足多样化办公需求。

安全设计严谨：实现路径沙箱、文件扩展名白名单、内容长度限制（50K/100K 字符）、URL 格式验证等多重防护。

依赖极简可信：仅依赖 Python 标准库，外部通信全部通过钉钉官方 mcporter 工具代理，无第三方包风险。

潜在缺点与局限性

读取能力灰度受限：get_document_content_by_url 处于官方灰度放量阶段，约 30% 实例暂未开放，导致"读文档"需求可能无法满足，需向用户明确说明非本地配置问题。

参数格式极易出错：accessType 字符串与 updateType 数字的类型要求违反直觉，传错会导致静默失败而非报错，调试成本高。

同步阻塞调用：subprocess 调用 mcporter 为同步模式，大文档操作存在超时风险。

企业账号限制：部分功能受钉钉企业账号策略约束，错误码 52600007 可能涉及父节点权限或企业级限制。

适合的目标群体

• 钉钉深度用户：已全面使用钉钉办公、希望将 AI Agent 接入文档工作流的企业团队
• 知识管理管理员：需要批量整理文档结构、建立标准化文件夹体系的运营人员
• 协同办公场景：多人协作写作、会议纪要沉淀、项目文档归集的轻量级内容生产团队
• 低代码集成者：希望通过 MCP 协议将钉钉文档能力嵌入自建系统的开发者

使用风险

性能风险：subprocess 进程派生存在额外开销，高频调用可能触发系统资源瓶颈；建议控制并发并设置合理超时。

依赖风险：mcporter 为 peerDependency，需用户手动安装，版本不匹配（<0.7.0）会导致功能异常。

数据一致性风险：updateType 0（覆盖）与 1（续写）误用可能导致数据丢失，不确定时必须询问用户确认。

灰度可用性风险：读取功能在目标环境中可能缺失，需前置检测工具列表，避免向用户虚假承诺。

凭证配置风险：OPENCLAW_WORKSPACE 环境变量配置错误会导致全链路失败，需引导用户正确初始化。