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 |

## 意图判断

用户说"创建文档/新建文档/写个文档/帮我建个文档":
- 创建文档 → 先 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_und...

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

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

## 功能特性

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

## 快速开始

### 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>"
```

### 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.write_content_to_document --args '{"content": "# 标题\n\n内容", "updateType": 0, "targetDentryUuid": "doc_xxx"}'

# 获取文档内容
mcporter call dingtalk-docs.get_document_content_by_url --args '{"docUrl": "https://alidocs.dingtalk.com/i/nodes/doc_xxx"}'
```

## 方法列表

| 方法 | 说明 | 必填参数 |
|------|------|---------|
| `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` | 获取文档内容 | docUrl |

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

## 注意事项

- **accessType 必须是字符串**（如 `"13"`），传数字会静默失败
- **updateType...