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 必须是数字，类型传错会导致静默失败

## 可用方法列表

| 方法 | 用途 | 必填参数 | 可用性 |
|------|------|---------|--------|
| `get_my_docs_root_dentry_uuid` | 获取"我的文档"根目录 ID | 无 | 稳定可用 |
| `list_accessible_documents` | 搜索有权限的文档 | 无 (keyword 选填) | 稳定可用 |
| `create_doc_under_node` | 创建在线文档 | name, parentDentryUuid | 稳定可用 |
| `create_dentry_under_node` | 创建节点 (文档/表格/文件夹等) | name, accessType, parentDentryUuid | 稳定可用 |
| `write_content_to_document` | 写入文档内容 (覆盖或续写) | content, updateType, targetDentryUuid | 稳定可用 |
| `get_document_content_by_url` | 通过 URL 获取文档 Markdown 内容 | docUrl | **灰度中，部分实例不可见** |

## 灰度发布说明（重要）

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

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

1. **如果 MCP 客户端里只看到 5 个工具，不要先判断为配置错误**
2. **如果缺少 `get_document_content_by_url`，不要先判断为权限缺失**
3. 通过钉钉 MCP 广场拿到的 URL，当前很可能因为**服务端未放量**而看不到该方法
4. 在该方法未放开前，Skill 应把“读文档内容”视为**条件可用能力**，不是所有环境都保证存在
5. 向...

# 钉钉文档操作技能 (dingtalk-docs)

管理钉钉云文档中的文档、文件夹和内容。支持文档搜索、创建、内容读写和文件夹整理。

## 功能特性

- ✅ 文档搜索 — 搜索有权限访问的文档
- ✅ 文档创建 — 在指定节点下创建新文档
- ✅ 多类型节点创建 — 支持文档/表格/PPT/文件夹等 11 种类型
- ✅ 内容写入 — 覆盖写入或续写模式（支持 Markdown）
- ✅ 内容读取 — 通过 URL 获取文档 Markdown 内容（当前为灰度能力）
- ✅ 根目录获取 — 获取"我的文档"根节点 ID

## 当前已知限制

### `get_document_content_by_url` 仍在灰度发布

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

这意味着：

- 通过 **钉钉 MCP 广场** 获取的 Streamable HTTP URL，接入后**可能只会看到 5 个工具**
- 缺失 `get_document_content_by_url` **不代表你配置错了，也不一定是权限问题**
- 当前更可能是**官方服务端尚未对你的实例放量**

目前常见的 5 个可见工具是：

- `list_accessible_documents`
- `get_my_docs_root_dentry_uuid`
- `create_doc_under_node`
- `create_dentry_under_node`
- `write_content_to_document`

如果你在 `mcporter list` 或其他 MCP 客户端里看不到 `get_document_content_by_url`，先按**服务端灰度未放开**处理，不要先怀疑本地配置。

## 快速开始

### 1. 安装技能

```bash
clawhub install dingtalk-docs
```

### 2. 安装依赖

```bash
npm install -g mcporter
```

### 3. 配置凭证

访问 [钉钉 MCP 广场](https://mcp.dingtalk.com) 找到 **钉钉文档** 服务，获取 Streamable HTTP URL：

```bash
mcporter config add dingtalk-docs --url "<你的_URL>"
```

也可以使用环境变量：

```bash
export DINGTALK_MCP_DOCS_URL="<你的_URL>"
```

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

### 4. 使用示例

```bash
# 获取根目录 ID
mcporter call dingtalk-docs.get_my_docs_root_dentry_uuid

# 创建文档
mcporter call dingtalk-docs.create_doc_under_node --args '{"name": "我的文档", "parentDentryUuid": "ROOT_ID"}'

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

# 写入内容到文档（覆盖模式）
mcporter call dingtalk-docs.wri...