钉钉云文档 Skill

概述

用户可能要求你创建、搜索、读取或编辑钉钉云文档。操作之间存在严格依赖关系：必须先获取 ID 才能执行后续操作。

严格禁止

1. 1. 禁止编造 ID -- dentryUuid 必须从返回值中提取，编造 ID 会操作到错误文档或报错
2. 创建前必须先获取根目录 ID -- 必须先调 getmydocsrootdentryuuid 拿到 rootDentryUuid
3. 禁止混淆两个创建方法 -- createdocundernode 只能创建文档，createdentryunder_node 支持文件夹/表格/PPT 等多种类型
4. 写入前必须确认 updateType -- 0=覆盖（清空后写入），1=续写（追加到末尾），搞反会丢数据，不确定时必须先问用户
5. 禁止只传 ID 读内容 -- 必须拼成完整 URL https://alidocs.dingtalk.com/i/nodes/{dentryUuid}
6. 禁止在用户说表格时默认创建文档 -- 可能要在线表格(accessType=1)或多维表(accessType=7)，不确定必须先问
7. 禁止传错参数类型 -- accessType 必须是字符串，updateType 必须是数字，类型传错会导致静默失败

可用方法列表

方法	用途	必填参数	可用性
getmydocsrootdentryuuid	获取我的文档根目录 ID	无	稳定可用
listaccessible_documents

搜索有权限的文档 | 无 (keyword 选填) | 稳定可用 | | createdocunder_node | 创建在线文档 | name, parentDentryUuid | 稳定可用 | | createdentryunder_node | 创建节点 (文档/表格/文件夹等) | name, accessType, parentDentryUuid | 稳定可用 | | writecontentto_document | 写入文档内容 (覆盖或续写) | content, updateType, targetDentryUuid | 稳定可用 | | getdocumentcontentbyurl | 通过 URL 获取文档 Markdown 内容 | docUrl | 灰度中，部分实例不可见 |

灰度发布说明（重要）

根据 GitHub issue #1 下维护者的明确回复：getdocumentcontentbyurl 目前在灰度中，全量还需要一点时间。

因此你必须按下面规则处理：

1. 1. 如果 MCP 客户端里只看到 5 个工具，不要先判断为配置错误
2. 如果缺少 getdocumentcontentbyurl，不要先判断为权限缺失
3. 通过钉钉 MCP 广场拿到的 URL，当前很可能因为服务端未放量而看不到该方法
4. 在该方法未放开前，Skill 应把读文档内容视为条件可用能力，不是所有环境都保证存在
5. 向用户说明时要直接说清：这是官方灰度状态，不是本地接入姿势问题

意图判断

用户说创建文档/新建文档/写个文档/帮我建个文档:

• - 创建文档 → 先 getmydocsrootdentryuuid，再 createdocundernode
• 创建到指定文件夹 → 用文件夹的 dentryUuid 作为 parentDentryUuid

用户说建文件夹/新建目录/整理一下文档:

• - 创建文件夹 → createdentryunder_node(accessType=13)

用户说创建表格/建个PPT/做个脑图:

• - 非文档类型 → createdentryunder_node，accessType: 表格=1，PPT=2，脑图=6，多维表=7
• 用户说表格但不确定类型 → 先问是在线表格还是多维表

关键区分: 在线表格(accessType=1) vs 多维表(accessType=7) vs 文档(用 createdocunder_node)

用户说搜索/找文档/查一下/有没有某个文档:

• - 搜索 → listaccessibledocuments(keyword=关键词)

用户说读文档/看看内容/打开文档/这个文档写了什么:

• - 先确认当前 MCP 服务是否真的暴露了 getdocumentcontentbyurl
• 有 URL 且该方法可用 → 直接 getdocumentcontentbyurl
• 有文档名且该方法可用 → 先 listaccessibledocuments 搜索，拿到 dentryUuid，拼 URL 再读
• 如果当前实例缺少 getdocumentcontentbyurl → 明确告诉用户：该读取能力目前仍在官方灰度中，你的实例暂未放开，不要把原因归咎于用户配置

用户说写入/更新内容/编辑文档/往文档里加点东西:

• - 全新内容或替换 → writecontenttodocument(updateType=0) 覆盖
• 追加内容 → writecontenttodocument(updateType=1) 续写
• 不确定 → 问用户是覆盖还是追加

核心工作流

创建文档并写入:

1. 1. getmydocsrootdentryuuid() → 提取 rootDentryUuid
2. createdocundernode(name, parentDentryUuid=rootDentryUuid) → 提取 dentryUuid
3. (HARD-GATE: 必须确认 updateType) writecontenttodocument(content, updateType=0, targetDentryUuid=dentryUuid) → 提取写入结果
4. getdocumentcontentby_url(docUrl=https://alidocs.dingtalk.com/i/nodes/{dentryUuid}) → 验证

搜索并读取（仅当 getdocumentcontentbyurl 已放量可用时）:

1. 1. listaccessibledocuments(keyword=关键词) → 提取 docs[].dentryUuid
2. getdocumentcontentbyurl(docUrl=https://alidocs.dingtalk.com/i/nodes/{dentryUuid})

如果当前实例没有 getdocumentcontentbyurl：

• - 停在搜索结果这一步
• 明确提示用户该能力仍处于官方灰度阶段
• 不要伪造读取成功或编造替代读接口

创建文件夹并整理:

1. 1. getmydocsrootdentryuuid() → 提取 rootDentryUuid
2. createdentryundernode(name, accessType=13, parentDentryUuid=rootDentryUuid) → 提取 dentryUuid
3. createdocunder_node(name, parentDentryUuid=文件夹dentryUuid)

上下文传递规则

操作	从返回中提取	用于
getmydocsrootdentryuuid	rootDentryUuid	createdocundernode / createdentryundernode 的 parentDentryUuid
createdocundernode

dentryUuid | writecontentto_document 的 targetDentryUuid，拼 URL 读内容 | | createdentryunder_node | dentryUuid | 作为子节点的 parentDentryUuid | | listaccessibledocuments | docs[].dentryUuid | 拼成 https://alidocs.dingtalk.com/i/nodes/{dentryUuid} 用于读取 |

CRITICAL: 参数格式

jsonc
// [正确] docUrl 必须是完整 URL
{docUrl: https://alidocs.dingtalk.com/i/nodes/DnRL6jAJ...}
// [错误] 只传 ID → 报错
{docUrl: DnRL6jAJ...}

// [正确] accessType 是字符串
{name: 报表, accessType: 1, parentDentryUuid: xxx}
// [错误] accessType 传数字 → 静默失败
{name: 报表, accessType: 1, parentDentryUuid: xxx}

// [正确] updateType 是数字
{content: ..., updateType: 0, targetDentryUuid: xxx}
// [错误] updateType 传字符串 → 静默失败
{content: ..., updateType: 0, targetDentryUuid: xxx}

本地文件脚本说明

scripts/ 目录中的辅助脚本会处理本地文件输入 / 输出：

• - importdocs.py 会读取工作区内的 .md / .txt / .markdown 文件并导入到钉钉文档
• exportdocs.py 会将钉钉文档内容导出为工作区内的本地 Markdown 文件
• create_doc.py 会调用 mcporter 创建文档并写入内容

这些脚本都受以下规则约束：

• - 仅允许访问工作区内路径
• 使用 resolvesafepath() 防止目录遍历
• 限制文件大小和