什么是 钉钉文档管理技能？

钉钉文档技能是专为 AI 智能体设计的专业级集成工具，旨在与钉钉云文档平台无缝交互。它支持以编程方式创建、检索和修改各种文档类型，包括标准文档、电子表格和文件夹。通过利用 Openclaw Skills 框架，该工具为处理协作文档工作流提供了一种结构化方式。

对于希望弥合 AI 驱动的任务管理与钉钉企业协作环境之间差距的开发人员来说，此技能至关重要。它执行严格的数据完整性规则（例如强制根 ID 获取和明确的更新类型定义），以确保文档操作既安全又准确。

下载入口:https://github.com/openclaw/skills/tree/main/skills/aliramw/dingtalk-docs

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

钉钉文档管理技能 应用场景

• 在钉钉中直接自动创建标准化的项目报告或会议纪要。
• 根据特定关键词搜索和检索现有文档，为 AI 智能体提供上下文。
• 通过在云端创建结构化的文件夹层级，以编程方式组织工作空间文件。
• 将本地 Markdown 文件与钉钉云文档同步，实现统一的知识管理。
• 无需人工干预，即可向现有在线文档追加实时数据或状态更新。

1. 该技能首先使用 get_my_docs_root_dentry_uuid 方法获取根目录 ID，为所有操作建立基础。
2. 创建新文档时，它利用 create_doc_under_node 或 create_dentry_under_node 函数，这需要一个有效的父级 UUID。
3. 对于内容修改，它使用 write_content_to_document，用户必须指定 updateType 为 0（覆盖）或 1（追加）。
4. 要读取内容，智能体将构建一个完整 URL，如果当前灰度发布中可用该功能，则通过 get_document_content_by_url 获取 Markdown 内容。
5. 该技能使用 mcporter 作为桥接器，在不从智能体脚本进行直接网络调用的情况下安全地执行这些请求。

钉钉文档管理技能 配置指南

要将此技能集成到您的环境中，请确保已安装并可访问 mcporter 二进制文件。您还必须配置如下所示的主要环境变量：

export DINGTALK_MCP_DOCS_URL="your_dingtalk_mcp_service_url"

配置完成后，智能体可以使用 Openclaw Skills 界面触发文档管理工作流。

钉钉文档管理技能 数据架构与分类体系

该技能使用基于节点的分类法组织数据。以下是主要元数据结构：

name: dingtalk-docs
description: 管理钉钉云文档中的文档、文件夹和内容。当用户想要创建文档、搜索文档、读取或写入文档内容、创建文件夹整理文档时使用。也适用于用户提到云文档、在线文档、钉钉文档、钉文档等关键词的场景。不要在用户需要操作多维表、管理日程、发消息或处理审批流时触发。
version: 0.3.4
metadata:
  openclaw:
    requires:
      bins:
        - mcporter
      env:
        - DINGTALK_MCP_DOCS_URL
    primaryEnv: DINGTALK_MCP_DOCS_URL
    homepage: https://github.com/aliramw/dingtalk-docs

钉钉云文档 Skill

Overview

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

严格禁止

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

可用方法列表

灰度发布说明（重要）

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

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

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

意图判断

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

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

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

• 创建文件夹 → create_dentry_under_node(accessType="13")

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

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

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

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

• 搜索 → list_accessible_documents(keyword=关键词)

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

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

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

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

核心工作流

创建文档并写入:

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

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

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

如果当前实例没有 get_document_content_by_url：

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

创建文件夹并整理:

1. get_my_docs_root_dentry_uuid() → 提取 rootDentryUuid
2. create_dentry_under_node(name, accessType="13", parentDentryUuid=rootDentryUuid) → 提取 dentryUuid
3. create_doc_under_node(name, parentDentryUuid=文件夹dentryUuid)

上下文传递规则

CRITICAL: 参数格式

// [正确] 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/ 目录中的辅助脚本会处理本地文件输入 / 输出：

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

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

• 仅允许访问工作区内路径
• 使用 resolve_safe_path() 防止目录遍历
• 限制文件大小和扩展名
• 仅通过 mcporter 调用 MCP 服务，不直接发起网络请求

错误处理

1. 遇到错误: 展示错误信息给用户，不要自行猜测解决方案
2. "Invalid credentials": 提示用户重新配置凭证
3. "Permission denied": 提示用户确认对该文档有操作权限
4. "Document not found": 用 list_accessible_documents 重新搜索确认文档是否存在
5. 如果方法列表里根本没有 get_document_content_by_url：按官方灰度未放量处理，不要误报为本地配置错误
6. 错误码 52600007: 可能是企业账号限制或父节点 ID 无效，确认 parentDentryUuid 来源

详细参考 (按需读取)

• references/api-reference.md -- 完整参数 Schema + 返回值 + 节点类型枚举
• references/error-codes.md -- 错误码说明 + 调试流程