Dingtalk Docs

钉钉云文档 Skill

⚠️ 版本兼容提醒

本 Skill v1.0 需要新版钉钉文档 MCP URL（mcpId=9629）。

如果你看到的工具名是 list_accessible_documents、write_content_to_document 等旧名称，说明配置的是旧版 MCP URL，需要重新获取：

1. 访问 钉钉文档 MCP 广场 获取新版 StreamableHttp URL 2. 重新配置：mcporter config add dingtalk-docs --url "<新版URL>"

严格禁止

1. 禁止编造 nodeId / blockId — 必须从工具返回值中提取，编造 ID 会操作到错误文档或块 2. 覆盖前必须确认 — update_document(mode="overwrite") 会清空全部内容，不确定时先问用户 3. 禁止删除前不确认 blockId — delete_document_block 不可恢复，必须先用 list_document_blocks 确认 4. 仅 ALIDOC 支持 Markdown 读写 — 表格/PPT/PDF 不支持 get_document_content 和 update_document 5. `get_document_content` 需要下载权限 — 仅有查看权限时无法获取内容，且不支持跨组织文档 6. `heading.level` 必须传整数 — insert_document_block 插入标题时，level 必须传 1 而非 "1"，传字符串会导致后端报错

工具列表

核心工具（8个）

Block 精细编辑工具（4个，按需使用）

意图判断

创建在线文档（"新建文档/帮我建个文档/写个文档"）:

• 直接 create_document(name, markdown?) — 不传 folderId 默认到根目录
• 指定文件夹 → create_document(name, folderId=<文件夹nodeId>)

创建其他类型文件（"新建表格/脑图/白板/演示/多维表/文件夹"）:

• create_file(name, type) — type 枚举：adoc/axls/appt/adraw/amind/able/folder
• 指定文件夹 → create_file(name, type, folderId=<文件夹nodeId>)
• 指定知识库 → create_file(name, type, workspaceId=<知识库ID>)（folderId 优先级高于 workspaceId）
• create_document vs create_file：前者专为在线文档设计且支持写入初始 Markdown，后者支持 7 种文件类型但不支持初始内容

搜索文档（"找文档/查一下/有没有某个文档"）:

• search_documents(keyword=关键词)

读取文档内容（"读文档/看看内容/这个文档写了什么"）:

• get_document_content(nodeId) — nodeId 支持 URL 或 ID 自动识别
• 若返回 UNSUPPORTED_CONTENT_TYPE → 告知用户该文档类型不支持 Markdown 读取

更新文档内容（"写入/更新/编辑/往文档里加点东西"）:

• 替换全部 → update_document(nodeId, markdown, mode="overwrite")（⚠️ 会清空，先确认）
• 追加内容 → update_document(nodeId, markdown, mode="append")
• 不确定 → 先问用户是覆盖还是追加

创建文件夹（"建文件夹/新建目录"）:

• create_folder(name, folderId?) — 不传 folderId 默认到根目录

遍历文件夹（"列出文件夹/看看里面有什么"）:

• list_nodes(folderId?) — 支持分页（pageSize, nextPageToken）

精细编辑块元素（"修改第几段/在某段后面插入/删除某个块/在标题后加内容"）:

第一步：必须先 list_document_blocks(nodeId) 获取 blockId、index 和 blockType，禁止猜测或编造。

第二步，根据意图选择操作：

• 插入新块 → insert_document_block(nodeId, element, referenceBlockId?, where?)
• 不传位置参数 → 插入到文档末尾
• where="after" / where="before" 配合 referenceBlockId 控制插入位置
• 修改已有块 → update_document_block(nodeId, blockId, element)（⚠️ 仅支持 paragraph 类型）
• 删除块 → delete_document_block(nodeId, blockId)（不可恢复，操作前务必向用户确认）
• 批量删除时从后向前按 index 倒序删除，避免 index 位移

⚠️ 高频易错点：

• paragraph 属性对象不可省略，内容为空时须传 "paragraph": {}
• heading.level 必须传整数（1 而非 "1"），传字符串会导致后端报错
• 列表块的 list 字段必填，不可省略
• 多级有序列表同组须保持相同 listId，否则展示错误

element 常用类型速查（完整结构见 dingtalk_document_struct.md）:

// 段落（paragraph）— paragraph 对象不可省略，空段落传 {}
{ "blockType": "paragraph", "paragraph": {}, "children": [{ "text": "普通文字" }] }

// 标题（heading）— level 传整数 1~6
{ "blockType": "heading", "heading": { "level": 1 }, "children": [{ "text": "一级标题" }] }

// 引用（blockquote）
{ "blockType": "blockquote", "blockquote": {}, "children": [{ "text": "引用内容" }] }

// 无序列表（unorderedList）— list 字段必填
{
  "blockType": "unorderedList",
  "unorderedList": {
    "list": { "level": 0, "listStyleType": "disc", "listStyle": { "format": "disc", "text": "%1", "align": "left" } }
  },
  "children": [{ "text": "列表项" }]
}

// 有序列表（orderedList）— list 字段必填，同组多级列表须保持相同 listId
{
  "blockType": "orderedList",
  "orderedList": {
    "list": { "listId": "list-001", "level": 0, "listStyleType": "decimal", "listStyle": { "format": "decimal", "text": "%1.", "align": "left" } }
  },
  "children": [{ "text": "列表项" }]
}

// 表格（table）— cells 为二维字符串数组
{ "blockType": "table", "table": { "rolSize": 2, "colSize": 3, "cells": [["A", "B", "C"], ["1", "2", "3"]] } }

children 行内元素（InlineElement）常用写法:

{ "text": "普通文字" }
{ "text": "加粗", "bold": true }
{ "text": "斜体", "italic": true }
{ "text": "代码", "fonts": "monospace" }
{ "elementType": "link", "properties": { "href": "https://..." }, "children": [{ "text": "链接文字" }] }
{ "elementType": "sticker", "properties": { "code": "灯泡" } }

核心工作流

创建文档并写入内容（一步完成）:

create_document(name="标题", markdown="# 标题\n\n内容") → 提取 nodeId

搜索并读取:

search_documents(keyword) → 提取 nodeId
get_document_content(nodeId) → 获取 markdown 内容

遍历文件夹并操作文档:

list_nodes(folderId?) → 提取 nodes[].nodeId
get_document_info(nodeId) → 确认 contentType=ALIDOC
get_document_content(nodeId) → 读取内容

Block 精细编辑:

list_document_blocks(nodeId) → 提取 blockId
insert_document_block(nodeId, referenceBlockId, where, element)

错误处理

1. PERMISSION_DENIED — 提示用户确认对该文档有操作权限 2. UNSUPPORTED_CONTENT_TYPE — 该文档类型（表格/PPT等）不支持 Markdown 读写 3. BLOCK_NOT_FOUND — blockId 不存在，先用 list_document_blocks 重新获取 4. UNSUPPORTED_BLOCK_TYPE — update_document_block 当前仅支持 paragraph 类型 5. CROSS_ORG_NOT_ALLOWED — 跨组织操作被禁止 6. Invalid credentials — 提示用户重新配置凭证，检查 MCP URL 是否为新版

遇到错误时展示 logId 给用户，便于向钉钉官方反馈排查。

详细参考（按需读取）

• references/api-reference.md — 12 个工具完整参数 Schema + 返回值（含 Block 工具 9-12）
• dingtalk_document_struct.md — Block 元素完整数据结构（BlockElement / InlineElement）
• references/error-codes.md — 错误码说明 + 调试流程

Changelog

[0.4.0] - 2026-03-17

新增

• ✅ 新增 create_file 工具文档（references/api-reference.md 第 12 节）：支持 7 种文件类型（adoc/axls/appt/adraw/amind/able/folder），含完整入参/出参/调用示例/错误码
• ✅ 新增 scripts/create_file.py：命令行创建文件脚本，支持 7 种类型和位置参数
• ✅ 新增 scripts/block_ops.py：Block 精细编辑脚本，支持 list/insert/update/delete 四个子命令
• ✅ 新增 references/block-api.md 分栏（columns）结构示例（B.4 节）

文档更新

• ✅ SKILL.md：工具列表 7→8 个，新增 create_file；意图判断新增"创建其他类型文件"场景；Block 意图判断重构（两步流程 + 高频易错点 + element 常用类型速查 + InlineElement 速查）
• ✅ SKILL.md：修复严格禁止第 6 条错误描述（heading.level 必须传整数，不是字符串）
• ✅ SKILL.md：frontmatter description 更新，移除"不要在用户需要操作多维表时触发"（create_file 现已支持多维表）
• ✅ README.md：功能特性列表新增 create_file；工具列表新增 create_file；目录结构补充 mcporter_utils.py/create_file.py/block_ops.py；api-reference.md 注释更新为 12 个工具
• ✅ references/block-api.md：所有调用示例从点号写法改为空格写法；insert_document_block 返回值补充 blockId；heading 示例修正（level 传整数，text 移到 children）；blockquote 示例修正（属性对象不可省略）；新增高频易错点警告块
• ✅ package.json：description 同步 create_file、Block 工具，移除多维表排除描述
• ✅ scripts/mcporter_utils.py：工具名对照注释扩展至 12 个工具
• ✅ testcases.json：新增 6 个 create_file 测试用例（044~049），总用例数 43→49

修复

• ✅ 修复 SKILL.md 中 heading.level 描述错误（之前误写为"必须传字符串"，实际 schema 类型为 number）
• ✅ 修复 references/block-api.md 中 blockquote 示例（属性对象不可省略，须传 {}）

---

[0.3.4] - 2026-03-07

修复

• ✅ SKILL.md frontmatter 补充 mcporter 二进制依赖声明
• ✅ SKILL.md frontmatter 补充 DINGTALK_MCP_DOCS_URL 凭证声明和 primaryEnv
• ✅ README.md 明确补充环境变量配置方式与凭证敏感性说明
• ✅ README.md / SKILL.md 新增本地文件脚本行为说明，明确 import / export 会处理工作区内文件
• ✅ 统一 registry metadata、package.json、README、SKILL 的依赖与凭证口径

[0.3.3] - 2026-03-07

文档一致性修复

• ✅ README.md 的读取示例补充灰度提示，避免用户误以为所有实例都能直接调用读取接口
• ✅ references/api-reference.md 补充 get_document_content_by_url 灰度说明
• ✅ references/api-reference.md 的“搜索并读取”工作流改为条件可用说明
• ✅ references/error-codes.md 新增“方法列表只显示 5 个工具”时的处理规则

[0.3.2] - 2026-03-07

文档更新

• ✅ README.md 新增已知限制说明，明确 get_document_content_by_url 当前仍处于灰度发布
• ✅ README.md 补充 5 个稳定工具 + 1 个灰度工具的可用性说明
• ✅ SKILL.md 新增灰度发布说明，要求缺少读取接口时按官方未放量处理
• ✅ SKILL.md 调整读文档意图与错误处理，避免把缺少接口误判为本地配置或权限问题

[0.3.1] - 2026-03-05

修复 (open-spec 合规审计)

SKILL.md 三项审计修复：

• ✅ "重要约束"改为"严格禁止"，使用 Authority 原则措辞（"禁止"/"必须"）
• ✅ 核心工作流写入步骤添加 HARD-GATE 标注 + "提取什么"标注
• ✅ 意图判断新增"关键区分"说明，明确区分在线表格/多维表/文档

package.json description 同步：

• ✅ description 与 SKILL.md frontmatter 保持一致，补充口语同义词和排除场景

---

[0.3.0] - 2026-03-05

重构

SKILL.md 按 dingtalk-neulink 技能包规范全面重构：

• ✅ 满足 7 区块规范（frontmatter / 严格禁止 / 方法总览 / 意图决策树 / 核心工作流 / 上下文传递 / 错误处理）
• ✅ 主文件控制在 117 行（规范要求 ≤ 150 行）
• ✅ 严格禁止 7 条，含产品专属禁令（类型混淆、URL 格式、覆盖写入确认等）
• ✅ 意图决策树覆盖 6 种用户意图，使用中文自然语言 + 口语化表达
• ✅ 上下文传递链完整无断裂
• ✅ 参数格式区块含正确/错误 JSON 对比示例

package.json 规范化：

• ✅ description 符合 D-01~D-08 规则（动词短语开头、含触发场景、含排除场景、含口语同义词、无内部术语）
• ✅ 版本号升级至 0.3.0
• ✅ keywords 移除 "mcp"，新增 "钉钉文档"、"在线文档"

references/api-reference.md 增强：

• ✅ 每个方法描述包含四要素（一句话用途 + 使用场景 + 区分说明 + 调用示例）
• ✅ 参数来源标注（如 parentDentryUuid 来自 get_my_docs_root_dentry_uuid）
• ✅ 类型陷阱高亮（accessType 字符串、updateType 数字、docUrl 完整 URL）

references/error-codes.md 精简：

• ✅ 错误码速查表精简为一行一错误，含具体修复动作
• ✅ 新增参数类型速查表（正确/错误/后果）
• ✅ 调试流程精简为 6 步

README.md 同步更新：

• ✅ 使用示例改为 --args JSON 格式
• ✅ 新增目录结构说明
• ✅ 新增注意事项（参数类型陷阱）

---

[0.2.1] - 2026-03-04

修复

• 🐛 测试套件同步适配 v0.2.0 JSON 传参（旧测试用位置参数调用 run_mcporter，与代码不一致）
• ✅ 新增 parse_response / 函数签名一致性 / 内容常量等测试用例（10→18 个）
• 🐛 修复 macOS symlink 导致路径比较失败（/var → /private/var）
• 📝 更新 TEST_REPORT.md

[0.2.0] - 2026-03-04

改动

传参方式统一为 JSON：

• ✅ SKILL.md 所有示例改用 --args '{"key": "value"}' 格式
• ✅ create_doc.py — run_mcporter() 改为 --args JSON 传参
• ✅ import_docs.py — 同上
• ✅ export_docs.py — 同上
• ✅ 三个脚本新增 parse_response() 统一处理嵌套 result 返回结构

Bug 修复：

• 🐛 修复脚本无法正确提取 dentryUuid 和 pcUrl（API 返回嵌套在 result 字段内）
• 🐛 export_docs.py UUID 正则从固定 32 位改为 [a-zA-Z0-9]+，兼容不同长度 ID

---

[0.1.1] - 2026-03-02

新增功能

脚本工具：

• ✅ create_doc.py - 创建文档并写入内容
• ✅ import_docs.py - 从本地文件导入文档（支持 .md/.txt/.markdown）
• ✅ export_docs.py - 导出文档到本地

测试套件：

• ✅ test_security.py - 10 个安全功能单元测试
• ✅ TEST_REPORT.md - 完整测试报告

API 方法（6 个）

安全特性

• ✅ 路径沙箱保护
• ✅ 文件扩展名白名单
• ✅ 文件大小限制（10MB）
• ✅ 内容长度限制（50K 字符）
• ✅ URL 格式验证
• ✅ 命令超时保护

---

[0.1.0] - 2026-03-02

初始发布

• ✅ 6 个真实可用的 API 方法
• ✅ 完整 SKILL.md 文档
• ✅ README.md 使用指南

---

已知限制

• ⚠️ 创建文档可能返回错误码 52600007（企业账号限制）
• ⚠️ 仅支持当前用户有权限访问的文档

Data Structures

An online document is a tree composed of block elements. Different types of BlockElement support different nestable child element types. For example, a callout block can nest any BlockElement, while a paragraph block can only nest InlineElement.

A single block element has the following structure:

{
  "blockType": enum(BlockType),             // Block element type, see BlockType enum below
  /**
   * The following are all supported Block types, such as Heading, Paragraph.
   * Each block type has its own specific property object.
   */
  "blockquote": Object(Callout),
  "callout": Object(Callout),
  "columns": Object(Columns),
  "heading": Object(Heading),
  "paragraph": Object(Paragraph),
  "orderedList": Object(OrderedList),
  "unorderedList": Object(UnorderedList),
  "table": Object(Table),
  // Each Block type has its own supported BlockChildren, see each Block type's `children` description
  "children": BlockChildren[],
}

BlockElement Reference

An online document is a tree structure composed of block elements (BlockElement). Different block types support different child element types:

• callout and columns: children must be a BlockElement array
• paragraph, heading, orderedList, unorderedList, blockquote: children must be an InlineElement array
• table: children is not supported

---

BlockType Enum

Unsupported element types are returned as Undefined.

---

1. Paragraph

{
  "blockType": "paragraph",
  "paragraph": {
    "text": "Paragraph text content",
    "indent": { "left": 32 },
    "folded": false
  },
  "children": [InlineElement]
}

• children: InlineElement array
• The paragraph object must not be omitted; pass {} when content is empty

---

2. Heading

{
  "blockType": "heading",
  "heading": {
    "level": 1,
    "text": "Heading Level 1"
  },
  "children": [InlineElement]
}

• children: InlineElement array

---

3. Blockquote

{
  "blockType": "blockquote",
  "blockquote": {
    "text": "Quoted content",
    "indent": { "left": 32 }
  },
  "children": [InlineElement]
}

• children: InlineElement array

---

4. Callout

{
  "blockType": "callout",
  "callout": {
    "sticker": "灯泡",
    "showstk": true,
    "color": "#333333",
    "border": "#FFD700",
    "bgcolor": "#FFF9C4"
  },
  "children": [BlockElement]
}

• children: BlockElement array (InlineElement is not allowed)

---

5. Columns

{
  "blockType": "columns",
  "columns": {
    "size": 2,
    "noFill": false
  },
  "children": [BlockElement]
}

• children: BlockElement array (InlineElement is not allowed)

---

6. Ordered List

{
  "blockType": "orderedList",
  "orderedList": {
    "list": {
      "listId": "list-001",
      "level": 0,
      "listStyleType": "decimal",
      "listStyle": {
        "format": "decimal",
        "text": "%1.",
        "align": "left"
      },
      "symbolStyle": {
        "bold": false
      }
    },
    "indent": { "left": 32 }
  },
  "children": [InlineElement]
}

• children: InlineElement array

---

7. Unordered List

{
  "blockType": "unorderedList",
  "unorderedList": {
    "list": {
      "listId": "list-002",
      "level": 0,
      "listStyleType": "disc",
      "listStyle": {
        "format": "disc",
        "text": "%1",
        "align": "left"
      },
      "symbolStyle": {
        "bold": false
      }
    },
    "indent": { "left": 32 }
  },
  "children": [InlineElement]
}

• children: InlineElement array

---

8. Table

{
  "blockType": "table",
  "table": {
    "rolSize": 3,
    "colSize": 4,
    "cells": [
      ["Row1-Col1", "Row1-Col2", "Row1-Col3", "Row1-Col4"],
      ["Row2-Col1", "Row2-Col2", "Row2-Col3", "Row2-Col4"],
      ["Row3-Col1", "Row3-Col2", "Row3-Col3", "Row3-Col4"]
    ]
  }
}

• children: Not supported

---

InlineElement Reference

Inline elements are used in the children of text-based block elements (paragraph, heading, list, etc.).

InlineType Enum

---

Text

{
  "text": "Bold red text",
  "sz": 16,
  "color": "red",
  "highlight": "yellow",
  "bold": true,
  "italic": false,
  "stike": false,
  "underline": false,
  "fonts": "monospace"
}

Fonts Enum

---

Emoji (sticker)

{
  "elementType": "sticker",
  "properties": {
    "code": "大笑"
  }
}

---

Image

{
  "elementType": "image",
  "properties": {
    "src": "https://example.com/image.jpg"
  }
}

---

Link

{
  "elementType": "link",
  "properties": {
    "href": "https://example.com"
  },
  "children": [
    { "text": "Click to open link" }
  ]
}

• children: Text array — required when inserting a link; must contain at least one text node with a non-empty text field.

---

Common Data Structures

Indent

---

ListObject

---

ListStyle

---

SymbolStyle

---

Emoji Enum (Complete List)

The following values can be used in callout.sticker and inline sticker elements (sticker.properties.code).

数据结构

一篇在线文档是由若干个块元素组成的树，不同类型的 BlockElment 内部可嵌套的元素的类型是不同，例如 高亮块 里可以嵌套任意的BlockElement，但是 段落块 下只能其嵌套 InlineElement 。

1 个块元素的数据结构如下：

{
  "blockType": enum(BlockType),             // 块元素类型，详见文档底部的 `BlockType` 枚举类型
  /**
   * 以下为所有支持的 Block 类型，如 Heading、Paragraph。 
   * 不同类型的 Block 有自己的 property。
  */
  "blockquote": Object(Callout),
  "callout": Object(Callout),
  "columns": Object(Columns),
  "heading": Object(Heading),
  "paragraph": Object(Paragraph),
  "orderedList": Object(OrderedList)
  "unorderedList": Object(UnorderedList),
  "table": Object(Table),
  // 每1种 Block 都有自己能支持的 BlockChildren，详见每个 Block 类型里的 `children` 的描述
  "children": BlockChildren[],
}

块元素数据结构说明（BlockElement Reference）

一篇在线文档由若干块元素（BlockElement） 组成的树状结构构成。不同类型的块元素内部可嵌套的子元素类型不同：

• callout、columns 的 children 只能是 BlockElement 数组
• paragraph、heading、orderedList、unorderedList、blockquote 的 children 只能是 InlineElement 数组
• table 暂不支持指定 children

---

BlockType 枚举

暂未支持的元素类型统一返回 Undefined。

---

一、段落（paragraph）

{
  "blockType": "paragraph",
  "paragraph": {
    "text": "段落文字内容",
    "indent": { "left": 32 },
    "folded": false
  },
  "children": [InlineElement]
}

• children：InlineElement 数组
• paragraph 对象不可省略，内容为空时须传 {}

---

二、标题（heading）

{
  "blockType": "heading",
  "heading": {
    "level": 1,
    "text": "一级标题"
  },
  "children": [InlineElement]
}

• children：InlineElement 数组

---

三、引用（blockquote）

{
  "blockType": "blockquote",
  "blockquote": {
    "text": "引用内容",
    "indent": { "left": 32 }
  },
  "children": [InlineElement]
}

• children：InlineElement 数组

---

四、高亮块（callout）

{
  "blockType": "callout",
  "callout": {
    "sticker": "灯泡",
    "showstk": true,
    "color": "#333333",
    "border": "#FFD700",
    "bgcolor": "#FFF9C4"
  },
  "children": [BlockElement]
}

• children：BlockElement 数组（不能是 InlineElement）

---

五、分栏（columns）

{
  "blockType": "columns",
  "columns": {
    "size": 2,
    "noFill": false
  },
  "children": [BlockElement]
}

• children：BlockElement 数组（不能是 InlineElement）

---

六、有序列表（orderedList）

{
  "blockType": "orderedList",
  "orderedList": {
    "list": {
      "listId": "list-001",
      "level": 0,
      "listStyleType": "decimal",
      "listStyle": {
        "format": "decimal",
        "text": "%1.",
        "align": "left"
      },
      "symbolStyle": {
        "bold": false
      }
    },
    "indent": { "left": 32 }
  },
  "children": [InlineElement]
}

• children：InlineElement 数组

---

七、无序列表（unorderedList）

{
  "blockType": "unorderedList",
  "unorderedList": {
    "list": {
      "listId": "list-002",
      "level": 0,
      "listStyleType": "disc",
      "listStyle": {
        "format": "disc",
        "text": "%1",
        "align": "left"
      },
      "symbolStyle": {
        "bold": false
      }
    },
    "indent": { "left": 32 }
  },
  "children": [InlineElement]
}

• children：InlineElement 数组

---

八、表格（table）

{
  "blockType": "table",
  "table": {
    "rolSize": 3,
    "colSize": 4,
    "cells": [
      ["Row1-Col1", "Row1-Col2", "Row1-Col3", "Row1-Col4"],
      ["Row2-Col1", "Row2-Col2", "Row2-Col3", "Row2-Col4"],
      ["Row3-Col1", "Row3-Col2", "Row3-Col3", "Row3-Col4"]
    ]
  }
}

• children：暂不支持指定 children

---

InlineElement 数据结构说明

行内元素用于文本类块元素（段落、标题、列表等）的 children 中。

InlineType 枚举

---

文本（text）

{
  "text": "加粗红色文字",
  "sz": 16,
  "color": "red",
  "highlight": "yellow",
  "bold": true,
  "italic": false,
  "stike": false,
  "underline": false,
  "fonts": "monospace"
}

Fonts 枚举值

---

表情（sticker）

{
  "elementType": "sticker",
  "properties": {
    "code": "大笑"
  }
}

---

图片（image）

{
  "elementType": "image",
  "properties": {
    "src": "https://example.com/image.jpg"
  }
}

---

链接（link）

{
  "elementType": "link",
  "properties": {
    "href": "https://example.com"
  },
  "children": [
    { "text": "点击跳转链接" }
  ]
}

• children：Text 数组，插入链接时必须指定 children，且至少包含 1 个 text 不为空的文本节点。

---

通用数据结构

Indent（缩进）

---

ListObject（列表对象）

---

ListStyle（列表样式）

---

SymbolStyle（列表符样式）

---

Emoji 枚举值（表情编码完整列表）

以下枚举值可用于 callout.sticker 和行内表情元素 sticker.properties.code。

---

钉钉文档操作技能 (dingtalk-docs) v1.0

管理钉钉云文档中的文档、文件夹和内容。支持文档搜索、创建、内容读写、文件夹遍历和块元素精细编辑。

⚠️ 版本兼容提醒

本 Skill v1.0 需要新版钉钉文档 MCP URL。

如果你之前配置的是旧版 URL（工具名为 list_accessible_documents、write_content_to_document 等），需要重新配置：

1. 访问 钉钉文档 MCP 广场 获取新版 StreamableHttp URL 2. 重新配置：mcporter config add dingtalk-docs --url "<新版URL>"

功能特性

• ✅ 文档搜索 — 搜索有权限访问的文档（search_documents）
• ✅ 文档创建 — 支持同时写入初始内容，默认创建到根目录（create_document）
• ✅ 内容读取 — 获取文档 Markdown 内容（get_document_content）
• ✅ 内容更新 — 覆盖或追加模式（update_document）
• ✅ 文档元信息 — 获取文档类型、创建时间等（get_document_info）
• ✅ 文件夹管理 — 创建文件夹（create_folder）
• ✅ 文件夹遍历 — 列出子节点，支持分页和递归（list_nodes）
• ✅ Block 精细编辑 — 插入/更新/删除文档块元素（insert/update/delete_document_block）
• ✅ 文件创建 — 创建在线文档、表格、演示、白板、脑图、多维表、文件夹（create_file）

快速开始

1. 安装技能

clawhub install dingtalk-docs

2. 安装依赖

npm install -g mcporter

3. 配置凭证

访问 钉钉文档 MCP 广场 获取新版 StreamableHttp URL：

mcporter config add dingtalk-docs --url "<你的新版URL>"

也可以使用环境变量：

export DINGTALK_MCP_DOCS_URL="<你的新版URL>"

这个 URL 含访问令牌，属于敏感凭证。推荐优先用 mcporter config 保存，避免泄露到 shell 历史。

4. 使用示例

# 创建文档（带初始内容，一步完成）
mcporter call dingtalk-docs create_document --args '{"name": "项目计划", "markdown": "# 项目计划\n\n## 目标"}'

# 搜索文档
mcporter call dingtalk-docs search_documents --args '{"keyword": "项目"}'

# 获取文档内容（支持 URL 或 nodeId）
mcporter call dingtalk-docs get_document_content --args '{"nodeId": "https://alidocs.dingtalk.com/i/nodes/xxx"}'

# 追加内容到文档
mcporter call dingtalk-docs update_document --args '{"nodeId": "doc_nodeId", "markdown": "\n\n## 新章节", "mode": "append"}'

# 列出文件夹内容
mcporter call dingtalk-docs list_nodes --args '{"folderId": "folder_nodeId"}'

# 创建文件夹
mcporter call dingtalk-docs create_folder --args '{"name": "2026 项目"}'

工具列表

核心工具

Block 精细编辑工具

完整参数说明请查看 references/api-reference.md

Block 元素数据结构请查看：

• 中文版：dingtalk_document_struct.md
• English：dingtalk_document_struct_en.md

注意事项

• nodeId 支持 URL 或 ID 自动识别，无需手动拼接 URL
• `update_document(mode="overwrite")` 会清空全部内容，操作前请确认
• `delete_document_block` 不可恢复，删除前先用 list_document_blocks 确认 blockId
• 仅支持 contentType=ALIDOC 的文档读写内容，表格/PPT/PDF 不支持 Markdown 读写
• `get_document_content` 需要对目标文档有「下载」权限，仅有查看权限时无法获取内容
• `get_document_content` 不支持跨组织文档，跨组织文档会返回 forbidden.accessDenied 错误
• 凭证 URL 包含访问令牌，请妥善保管

目录结构

dingtalk-docs/
├── SKILL.md                 # AI 技能入口（≤150 行）
├── package.json             # 元数据
├── README.md                # 人类可读说明
├── CHANGELOG.md             # 变更日志
├── references/
│   ├── api-reference.md     # 12 个工具完整参数 Schema
│   ├── block-api.md         # Block 工具完整 Schema + 块元素数据结构
│   └── error-codes.md       # 错误码说明 + 调试流程
├── scripts/
│   ├── mcporter_utils.py    # mcporter 公共工具函数
│   ├── create_doc.py        # 创建在线文档脚本
│   ├── create_file.py       # 创建文件脚本（支持7种类型）
│   ├── block_ops.py         # Block 精细编辑脚本
│   ├── import_docs.py       # 导入文档脚本
│   └── export_docs.py       # 导出文档脚本
└── tests/
    ├── test_security.py     # 安全功能测试
    ├── testcases.json       # 评测用例
    └── TEST_REPORT.md       # 测试报告

开发

# 克隆仓库
git clone https://github.com/aliramw/dingtalk-docs.git

# 运行测试
python3 tests/test_security.py -v

许可证

MIT License

作者

Marila@Dingtalk

钉钉云文档 API 参考（v1.0）

新版 MCP 工具完整参数 Schema、返回值格式和调用示例。

需要新版 MCP URL：钉钉文档 MCP 广场

公共说明

nodeId 格式

所有接受 nodeId / folderId 的参数均支持两种格式，系统自动识别：

• 文档 URL：https://alidocs.dingtalk.com/i/nodes/{dentryUuid}
• 文档 ID：32 位字母数字字符串（dentryUuid）

公共返回字段

每个工具的返回值都包含以下公共字段：

---

1. search_documents — 搜索文档

根据关键词搜索当前用户有权限访问的文档列表。不传 keyword 时返回最近访问的文档（最多 10 条）。

入参:

出参:

调用示例:

# 搜索包含"项目"的文档
mcporter call dingtalk-docs search_documents --args '{"keyword": "项目"}'

# 返回最近访问的文档
mcporter call dingtalk-docs search_documents

---

2. get_document_content — 获取文档内容

获取钉钉文档的内容，以 Markdown 格式返回。仅支持 contentType=ALIDOC 的在线文档，表格/PPT/PDF 等不支持。

入参:

出参:

调用示例:

# 通过 nodeId 获取
mcporter call dingtalk-docs get_document_content --args '{"nodeId": "DnRL6jAJMNX9kAgycoLy2vOo8yMoPYe1"}'

# 通过 URL 获取（自动识别）
mcporter call dingtalk-docs get_document_content --args '{"nodeId": "https://alidocs.dingtalk.com/i/nodes/DnRL6jAJMNX9kAgycoLy2vOo8yMoPYe1"}'

---

3. create_document — 创建文档

创建一篇新的钉钉在线文档，支持同时写入初始内容。不传 folderId 时默认创建到用户"我的文档"根目录。

入参:

入参优先级： folderId > workspaceId > 默认（我的文档根目录）

出参:

调用示例:

# 创建空文档到根目录
mcporter call dingtalk-docs create_document --args '{"name": "项目计划"}'

# 创建带初始内容的文档（一步完成）
mcporter call dingtalk-docs create_document --args '{"name": "项目计划", "markdown": "# 项目计划\n\n## 目标\n完成 Q1 目标"}'

# 在指定文件夹下创建
mcporter call dingtalk-docs create_document --args '{"name": "子文档", "folderId": "folder_nodeId"}'

# 在知识库根目录下创建
mcporter call dingtalk-docs create_document --args '{"name": "知识库文档", "workspaceId": "workspace_id"}'

---

4. update_document — 更新文档内容

更新钉钉文档的内容，支持覆盖和追加两种模式。

⚠️ overwrite 模式会清空文档全部内容（包括图片、评论等），操作前请先确认用户意图，建议先用 get_document_content 备份。

入参:

出参:

调用示例:

# 覆盖写入（⚠️ 会清空原内容）
mcporter call dingtalk-docs update_document --args '{"nodeId": "doc_nodeId", "markdown": "# 新内容\n\n全量替换", "mode": "overwrite"}'

# 追加内容（安全，不影响现有内容）
mcporter call dingtalk-docs update_document --args '{"nodeId": "doc_nodeId", "markdown": "\n\n## 新章节\n追加的内容", "mode": "append"}'

---

5. get_document_info — 获取文档元信息

获取文档的元信息（标题、类型、创建时间等），不返回文档正文内容。适合在读取内容前先确认文档类型（contentType=ALIDOC 才支持 Markdown 读写）。

入参:

出参:

调用示例:

mcporter call dingtalk-docs get_document_info --args '{"nodeId": "doc_nodeId"}'

---

6. create_folder — 创建文件夹

在指定位置创建一个新的文件夹。不传 folderId 时默认创建到用户"我的文档"根目录。

入参:

出参:

调用示例:

# 在根目录创建文件夹
mcporter call dingtalk-docs create_folder --args '{"name": "2026 项目"}'

# 在指定文件夹下创建子文件夹
mcporter call dingtalk-docs create_folder --args '{"name": "子文件夹", "folderId": "parent_folder_nodeId"}'

---

7. list_nodes — 遍历文件列表

列出指定文件夹或知识库下的直接子节点列表，支持分页。返回结果基于当前用户的可访问权限过滤。

入参:

入参优先级： folderId > workspaceId > 默认（我的文档根目录）

出参:

nodeType 与 contentType 关系：

调用示例:

# 列出根目录
mcporter call dingtalk-docs list_nodes

# 列出指定文件夹
mcporter call dingtalk-docs list_nodes --args '{"folderId": "folder_nodeId"}'

# 分页获取
mcporter call dingtalk-docs list_nodes --args '{"folderId": "folder_nodeId", "pageSize": 10, "pageToken": "next_page_token"}'

---

完整工作流示例

创建文档并写入内容（一步完成）

# 直接创建带内容的文档，无需先获取根目录 ID
mcporter call dingtalk-docs create_document --args '{"name": "项目计划", "markdown": "# 项目计划\n\n## 目标\n完成 Q1 目标"}'

搜索并读取文档

# 1. 搜索文档，获取 nodeId
mcporter call dingtalk-docs search_documents --args '{"keyword": "项目"}'

# 2. 获取文档内容（直接用 nodeId，无需拼接 URL）
mcporter call dingtalk-docs get_document_content --args '{"nodeId": "<step1返回的nodeId>"}'

遍历文件夹并读取 ALIDOC 文档

# 1. 列出文件夹内容
mcporter call dingtalk-docs list_nodes --args '{"folderId": "folder_nodeId"}'

# 2. 对 contentType=ALIDOC 的节点读取内容
mcporter call dingtalk-docs get_document_content --args '{"nodeId": "<nodes[].nodeId>"}'

创建文件夹并在其中创建文档

# 1. 创建文件夹
mcporter call dingtalk-docs create_folder --args '{"name": "2026 项目"}'
# 返回 nodeId: "folder_abc123"

# 2. 在文件夹中创建文档
mcporter call dingtalk-docs create_document --args '{"name": "Q1 计划", "folderId": "folder_abc123"}'

追加内容到已有文档

# 1. 搜索文档
mcporter call dingtalk-docs search_documents --args '{"keyword": "周报"}'

# 2. 追加内容（不影响现有内容）
mcporter call dingtalk-docs update_document --args '{"nodeId": "<nodeId>", "markdown": "\n\n## 2026-W11\n本周完成了...", "mode": "append"}'

覆盖更新前先备份

# 1. 先读取现有内容作为备份
mcporter call dingtalk-docs get_document_content --args '{"nodeId": "doc_nodeId"}'

# 2. 确认用户意图后再覆盖
mcporter call dingtalk-docs update_document --args '{"nodeId": "doc_nodeId", "markdown": "# 全新内容", "mode": "overwrite"}'

Block 精细编辑工作流

# 1. 查询文档块列表，获取 blockId
mcporter call dingtalk-docs list_document_blocks --args '{"nodeId": "doc_nodeId"}'

# 2. 在指定块之后插入一个段落
mcporter call dingtalk-docs insert_document_block --args '{"nodeId": "doc_nodeId", "element": {"blockType": "paragraph", "paragraph": {"text": "新段落内容"}}, "referenceBlockId": "block_id", "where": "after"}'

# 3. 更新某个段落块的内容
mcporter call dingtalk-docs update_document_block --args '{"nodeId": "doc_nodeId", "blockId": "block_id", "element": {"paragraph": {"elements": [{"textRun": {"content": "更新后的内容"}}]}}}'

# 4. 删除指定块（不可恢复）
mcporter call dingtalk-docs delete_document_block --args '{"nodeId": "doc_nodeId", "blockId": "block_id"}'

---

Block 精细编辑工具

Block 工具用于对文档进行块级精细操作。块元素的完整数据结构请参考 dingtalk_document_struct.md。

公共说明

• blockId：块元素的唯一标识，通过 list_document_blocks 获取
• element：块元素数据对象，必须包含 blockType 字段及对应类型的属性对象
• 所有写操作（insert/update/delete）均需要对文档有编辑权限

---

8. list_document_blocks — 查询文档块列表

查询指定文档下的一级块元素列表（根节点下第一级 BlockElement），支持按起始/终止位置范围及块类型过滤。返回每个块的 blockId、index 和完整数据结构。

入参:

blockType 枚举值:

出参:

调用示例:

# 查询所有块
mcporter call dingtalk-docs list_document_blocks --args '{"nodeId": "doc_nodeId"}'

# 查询第 0-5 个块
mcporter call dingtalk-docs list_document_blocks --args '{"nodeId": "doc_nodeId", "startIndex": 0, "endIndex": 5}'

# 只查询 heading 类型的块
mcporter call dingtalk-docs list_document_blocks --args '{"nodeId": "doc_nodeId", "blockType": "heading"}'

---

9. insert_document_block — 插入块元素

在指定文档的根目录中插入 1 个块元素，可指定插入位置和方向（之前/之后）。两者均不传时默认插入到文档末尾。目前仅支持插入到根目录（一级节点）。

入参:

⚠️ 注意：heading.level 参数必须传字符串类型（如 "1"），传整数会导致后端报错。

出参:

调用示例:

# 插入段落到文档末尾
mcporter call dingtalk-docs insert_document_block --args '{
  "nodeId": "doc_nodeId",
  "element": {
    "blockType": "paragraph",
    "paragraph": {"text": "新段落内容"},
    "children": [{"text": "新段落内容"}]
  }
}'

# 在指定块之后插入标题（注意 level 必须是字符串）
mcporter call dingtalk-docs insert_document_block --args '{
  "nodeId": "doc_nodeId",
  "element": {
    "blockType": "heading",
    "heading": {"level": "2", "text": "二级标题"}
  },
  "referenceBlockId": "block_id",
  "where": "after"
}'

# 在指定块之前插入引用块
mcporter call dingtalk-docs insert_document_block --args '{
  "nodeId": "doc_nodeId",
  "element": {
    "blockType": "blockquote",
    "blockquote": {"indent": {"left": 32}},
    "children": [{"text": "引用内容"}]
  },
  "referenceBlockId": "block_id",
  "where": "before"
}'

# 插入表格（使用 dingtalk_document_struct.md 中的 table 结构）
mcporter call dingtalk-docs insert_document_block --args '{
  "nodeId": "doc_nodeId",
  "element": {
    "blockType": "table",
    "table": {
      "rolSize": 2,
      "colSize": 3,
      "cells": [["表头1", "表头2", "表头3"], ["数据1", "数据2", "数据3"]]
    }
  }
}'

# 插入高亮块（callout）
mcporter call dingtalk-docs insert_document_block --args '{
  "nodeId": "doc_nodeId",
  "element": {
    "blockType": "callout",
    "callout": {"sticker": "灯泡", "showstk": true, "bgcolor": "#FFF9C4", "border": "#FFD700"},
    "children": [{"blockType": "paragraph", "paragraph": {"text": "高亮内容"}}]
  }
}'

---

10. update_document_block — 更新块元素

更新指定文档中某一个块元素的属性。本操作为 PATCH（局部更新） 语义，只修改 element 中传入的字段，未传入的字段保持原值不变。

⚠️ 目前仅支持更新 `paragraph`（段落）类型的块，其他类型会返回 `UNSUPPORTED_BLOCK_TYPE` 错误。

入参:

⚠️ 注意：indent 参数类型为对象（如 {"indentFirstLine": {"unit": "pt", "value": 24}}），传入整数会报错。

出参:

调用示例:

# 更新段落文字内容
mcporter call dingtalk-docs update_document_block --args '{
  "nodeId": "doc_nodeId",
  "blockId": "block_id",
  "element": {
    "paragraph": {
      "elements": [{"textRun": {"content": "更新后的文字内容"}}]
    }
  }
}'

# 仅更新折叠状态（不影响文字）
mcporter call dingtalk-docs update_document_block --args '{
  "nodeId": "doc_nodeId",
  "blockId": "block_id",
  "element": {
    "paragraph": {"collapsed": true}
  }
}'

# 同时更新文字和缩进
mcporter call dingtalk-docs update_document_block --args '{
  "nodeId": "doc_nodeId",
  "blockId": "block_id",
  "element": {
    "paragraph": {
      "elements": [{"textRun": {"content": "更新后的文字"}}],
      "indent": {"indentFirstLine": {"unit": "pt", "value": 24}}
    }
  }
}'

---

11. delete_document_block — 删除块元素

删除指定文档中的某一个块元素。此操作不可恢复，删除前请先用 list_document_blocks 确认 blockId。

入参:

出参:

调用示例:

# 删除指定块
mcporter call dingtalk-docs delete_document_block --args '{"nodeId": "doc_nodeId", "blockId": "block_id"}'

批量删除建议：批量删除多个块时，建议从后向前按 index 倒序删除，避免删除后 index 位移导致定位错误。

---

Block 工具错误码汇总

---

12. create_file — 创建文件

在指定位置创建一个新文件，支持钉钉在线文档、表格、演示、白板、脑图、多维表和文件夹七种类型。

入参:

入参优先级： folderId > workspaceId > 默认（我的文档根目录）

`type` 枚举值:

出参:

调用示例:

# 创建钉钉在线文档到"我的文档"根目录
mcporter call dingtalk-docs create_file --args '{"name": "2026 Q2 计划", "type": "adoc"}'

# 在指定文件夹下创建表格
mcporter call dingtalk-docs create_file --args '{"name": "数据统计", "type": "axls", "folderId": "folder_nodeId"}'

# 在知识库根目录下创建多维表
mcporter call dingtalk-docs create_file --args '{"name": "项目看板", "type": "able", "workspaceId": "workspace_id"}'

# 在指定文件夹下创建子文件夹
mcporter call dingtalk-docs create_file --args '{"name": "2026 项目", "type": "folder", "folderId": "folder_nodeId"}'

# 创建脑图
mcporter call dingtalk-docs create_file --args '{"name": "架构设计", "type": "amind"}'

# 创建白板
mcporter call dingtalk-docs create_file --args '{"name": "头脑风暴", "type": "adraw"}'

# 创建演示文稿
mcporter call dingtalk-docs create_file --args '{"name": "季度汇报", "type": "appt"}'

错误码:

钉钉云文档 Block API 参考 (v1.0)

Block 精细编辑工具的完整参数 Schema 和块元素数据结构。

适用于需要精确控制文档结构的场景（在指定位置插入、修改、删除块元素）。

常规的文档内容读写请使用 update_document / get_document_content，无需使用 Block API。

---

Block 工具概览

重要限制：

• 所有 Block 工具仅操作一级块元素（根节点直接子节点），不支持嵌套层级
• update_document_block 当前仅支持 paragraph 类型
• delete_document_block 不可恢复，删除含子块的块（callout/columns/table）时子块一并删除

---

1. list_document_blocks — 查询块列表

参数:

返回值:

{
  "success": true,
  "blocks": [
    {
      "blockId": "mmpzx96vb8asm77jil",
      "index": 0,
      "blockType": "heading",
      "element": { "blockType": "heading", "heading": { "level": 1, "text": "文档标题" } }
    },
    {
      "blockId": "mmpzx96ve10038tufl",
      "index": 1,
      "blockType": "paragraph",
      "element": { "blockType": "paragraph", "paragraph": { "text": "段落内容" } }
    }
  ]
}

关键字段:

• blocks[].blockId — 块唯一标识，用于 update_document_block / delete_document_block 的 blockId
• blocks[].index — 块在文档中的位置（从 0 开始），用于 insert_document_block 的 index 参数

调用示例:

# 查询全部块
mcporter call dingtalk-docs list_document_blocks --args '{"nodeId": "docNodeId"}'

# 查询第 1~3 个块
mcporter call dingtalk-docs list_document_blocks --args '{"nodeId": "docNodeId", "startIndex": 1, "endIndex": 3}'

# 只查询段落块
mcporter call dingtalk-docs list_document_blocks --args '{"nodeId": "docNodeId", "blockType": "paragraph"}'

---

2. insert_document_block — 插入块元素

参数:

返回值:

{ "success": true, "blockId": "新块的blockId" }

调用示例:

# 在文档末尾插入段落
mcporter call dingtalk-docs insert_document_block --args '{
  "nodeId": "docNodeId",
  "element": {"blockType": "paragraph", "paragraph": {}, "children": [{"text": "新段落"}]}
}'

# 在指定块之后插入二级标题（level 传整数）
mcporter call dingtalk-docs insert_document_block --args '{
  "nodeId": "docNodeId",
  "referenceBlockId": "mmpzx96vb8asm77jil",
  "where": "after",
  "element": {"blockType": "heading", "heading": {"level": 2}, "children": [{"text": "新章节"}]}
}'

# 在指定块之前插入无序列表
mcporter call dingtalk-docs insert_document_block --args '{
  "nodeId": "docNodeId",
  "referenceBlockId": "mmpzx96vb8asm77jil",
  "where": "before",
  "element": {"blockType": "unorderedList", "unorderedList": {"list": {"level": 0, "listStyleType": "disc", "listStyle": {"format": "disc", "text": "%1", "align": "left"}}}, "children": [{"text": "列表项"}]}
}'

---

3. update_document_block — 更新块元素

PATCH 语义：只修改传入的字段，未传入的字段保持原值不变。当前仅支持 paragraph 类型。

参数:

返回值:

{ "success": true }

调用示例:

# 修改段落文字（不影响其他属性）
mcporter call dingtalk-docs update_document_block --args '{
  "nodeId": "docNodeId",
  "blockId": "mmpzx96ve10038tufl",
  "element": {"blockType": "paragraph", "paragraph": {}, "children": [{"text": "更新后的内容"}]}
}'

# 设置段落折叠（不影响文字）
mcporter call dingtalk-docs update_document_block --args '{
  "nodeId": "docNodeId",
  "blockId": "mmpzx96ve10038tufl",
  "element": {"blockType": "paragraph", "paragraph": {"folded": true}}
}'

---

4. delete_document_block — 删除块元素

⚠️ 删除不可恢复。删除含子块的块（callout/columns/table）时，所有子块一并删除。

参数:

返回值:

{ "success": true }

调用示例:

# 删除指定块（先确认 blockId）
mcporter call dingtalk-docs delete_document_block --args '{"nodeId": "docNodeId", "blockId": "mmpzx97482905xaj5dy"}'

批量删除建议： 按 index 从后向前删除，避免索引位移导致误删。

---

附录 A：BlockType 枚举

---

附录 B：块元素数据结构（insert 时使用）

children 规则

• paragraph、heading、orderedList、unorderedList、blockquote 的 children → InlineElement 数组
• callout、columns 的 children → BlockElement 数组
• table 暂不支持指定 children

⚠️ 高频易错点：

• paragraph 属性对象不可省略，内容为空时须传 "paragraph": {}（blockquote 同理）
• heading.level 必须传整数（1 而非 "1"），传字符串会导致后端报错
• 列表块的 list 字段必填，不可省略
• 多级有序列表同组须保持相同 listId，否则展示错误

B.1 段落（paragraph）

{
  "blockType": "paragraph",
  "paragraph": { "text": "段落文字", "indent": { "left": 32 }, "folded": false },
  "children": [{ "text": "加粗文字", "bold": true }, { "text": "普通文字" }]
}

B.2 标题（heading）

{
  "blockType": "heading",
  "heading": { "level": 1 },
  "children": [{ "text": "一级标题" }]
}

level 取值 1～6（整数），1 表示一级标题。⚠️ 必须传整数，传字符串 `"1"` 会报错。

B.3 引用（blockquote）

{
  "blockType": "blockquote",
  "blockquote": {},
  "children": [{ "text": "引用内容" }]
}

⚠️ `blockquote` 属性对象不可省略，内容为空时须传 `{}`。

B.4 分栏（columns）

{
  "blockType": "columns",
  "columns": { "size": 2, "noFill": false },
  "children": [
    { "blockType": "paragraph", "paragraph": {}, "children": [{ "text": "左栏内容" }] },
    { "blockType": "paragraph", "paragraph": {}, "children": [{ "text": "右栏内容" }] }
  ]
}

size 为分栏数量，children 为 BlockElement 数组（不能是 InlineElement）。

B.5 高亮块（callout）

{
  "blockType": "callout",
  "callout": { "sticker": "灯泡", "showstk": true, "bgcolor": "#FFF9C4", "border": "#FFD700" },
  "children": [
    { "blockType": "paragraph", "paragraph": {}, "children": [{ "text": "高亮块内容" }] }
  ]
}

sticker 可选值见附录 D（Emoji 枚举）。

B.6 有序列表（orderedList）

{
  "blockType": "orderedList",
  "orderedList": {
    "list": { "listId": "list-001", "level": 0, "listStyleType": "decimal",
              "listStyle": { "format": "decimal", "text": "%1.", "align": "left" } }
  },
  "children": [{ "text": "列表项内容" }]
}

同组多级列表需保持 listId 一致，level 从 0 开始。

B.7 无序列表（unorderedList）

{
  "blockType": "unorderedList",
  "unorderedList": {
    "list": { "listId": "list-002", "level": 0, "listStyleType": "disc",
              "listStyle": { "format": "disc", "text": "%1", "align": "left" } }
  },
  "children": [{ "text": "列表项内容" }]
}

B.8 表格（table）

{
  "blockType": "table",
  "table": {
    "rolSize": 3,
    "colSize": 4,
    "cells": [
      ["Row1-Col1", "Row1-Col2", "Row1-Col3", "Row1-Col4"],
      ["Row2-Col1", "Row2-Col2", "Row2-Col3", "Row2-Col4"],
      ["Row3-Col1", "Row3-Col2", "Row3-Col3", "Row3-Col4"]
    ]
  }
}

rolSize（行数）和 colSize（列数）必填，cells 为二维字符串数组。

---

附录 C：InlineElement 数据结构

行内元素用于文本类块元素的 children 中。

C.1 文本（text）

{ "text": "加粗红色文字", "bold": true, "color": "red", "highlight": "yellow",
  "italic": false, "underline": false, "stike": false, "sz": 16, "fonts": "monospace" }

C.2 链接（link）

{
  "elementType": "link",
  "properties": { "href": "https://example.com" },
  "children": [{ "text": "点击跳转" }]
}

插入链接时 children 必须包含至少 1 个 text 不为空的文本节点。

C.3 图片（image）

{ "elementType": "image", "properties": { "src": "https://example.com/image.jpg" } }

---

附录 D：常用 Emoji 枚举（callout sticker）

灯泡 警告 对勾 禁止 火箭 火 赞 100分 KPI OKR Done 优先级: 1 优先级: 2 优先级: 3 进度: 未开始 进度: 已完成 大笑 流泪 思考 疑问 惊讶 加油 鼓掌 撒花 握手

完整枚举值区分全角/半角及大小写，请严格按照上述格式填写。

钉钉云文档错误码参考 (v1.0)

SKILL.md 的按需加载参考文件。遇到错误时查阅此文档。

>

每次 API 调用都会返回 `logId`（请求追踪 ID），遇到问题时请保存该值提供给技术支持。

错误码速查表

新版参数说明

新版 API 参数体系已简化，不再有旧版的类型陷阱：

调试流程

1. 保存 logId → 每次 API 返回都包含，遇到问题时提供给技术支持
2. 检查错误码 → 对照上方速查表
3. 确认 nodeId 来源 → 必须从 API 返回值中提取，禁止编造
4. 确认文档类型 → get_document_info 确认 contentType=ALIDOC 才能读写内容
5. 检查权限 → 确认用户对文档/文件夹有操作权限
6. 检查 MCP URL 版本 → 新版工具名以 search_documents / create_document 等为准
7. 重试 → 排除服务端临时故障

日志位置

~/.mcporter/logs/      # mcporter 日志
~/.openclaw/logs/      # 技能执行日志