\r \r

钉钉文档管理技能\r

\r 通过钉钉开放平台 API 管理钉钉文档与钉钉知识库内文档。SKILL.md 只保留 agent 执行所需规则;配置细节、示例、API 背景见 README.md。\r \r

何时使用\r

\r

触发关键词\r

\r 只有在已经确认对象是钉钉文档时，同时消息包含以下任一关键词时，优先使用本 skill：\r \r | 类别 | 关键词 |\r |------|--------|\r | 平台名 | 钉钉文档、钉钉知识库、alidocs |\r | 读取类 | 总结、读取、查看、浏览、列出结构 |\r | 修改类 | 更新、修改、追加、删除、覆写 |\r | 对象 | 文档、链接、这篇、这个文档 |\r \r 组合示例：\r

• "总结一下这篇钉钉文档"\r
• "读取这个 alidocs 链接"\r
• "更新文档内容"\r
• "删除第三段"\r \r

触发场景（优先级从高到低）\r

\r | 场景 | 示例 | 动作 |\r |------|------|------|\r | 钉钉文档链接 | alidocs.dingtalk.com/i/nodes/xxx | 根据意图选择：元数据→get-doc，正文内容→get-content |\r | 钉钉上下文 + 链接 | "总结 https://alidocs.dingtalk.com/..." | 调用 get-content 读取内容后总结 |\r | 明确命令 | "总结这篇文档"、"读取这个 alidocs 链接" | 根据意图选择命令 |\r | 已知上下文是钉钉文档 | 前文已给出 alidocs 链接，后续说"更新文档"、"删除某段"、"在第三段后追加" | 调用对应命令 |\r | 结构查询 | "列出结构"、"这个 alidocs 有哪些章节" | 调用 get-content |\r | 块级操作 | "删除第三段"、"修改这个段落"、"在这里插入一段" | 先用 get-content 获取 blockId 和位置，再调用 delete-block/modify-block/insert-block |\r \r

不触发的场景\r

• 查询本地文件、离线文档或普通文本内容，且不需要调用钉钉 API\r
• 没有文档链接、docKey、或明确钉钉文档上下文，却要求修改文档\r
• 用户只说"总结文档""更新这个链接"等泛化请求，但上下文无法确认对象是钉钉文档\r
• 与钉钉无关的文档系统，例如本地 Markdown、飞书文档、语雀、Google Docs\r \r

运行前提\r

\r

环境变量\r

\r 必须配置以下环境变量 (在 Gateway 环境中):\r \r

• DINGTALK_CLIENTID - 钉钉应用 Client ID (AppKey)\r
• DINGTALK_CLIENTSECRET - 钉钉应用 Client Secret (AppSecret)\r \r 可选环境变量:\r \r
• OPENCLAW_SENDER_ID / DINGTALK_SENDER_ID - 由 OpenClaw / 钉钉连接器注入的当前用户 sender_id；也可以通过命令行 --senderId= 显式传入\r
• DINGTALK_DEBUG - 设置为 true 启用调试模式；仅输出方法、路径（查询参数已脱敏）、状态码、requestId 等，不打印文档正文与完整请求体\r \r

operatorId 获取方式\r

\r 不需要在配置中指定!系统会自动从当前会话获取:\r \r

1. 从 OPENCLAW_SENDER_ID 或 DINGTALK_SENDER_ID 获取 sender_id\r
2. 调用钉钉 API 查询对应的 unionId\r
3. 使用 unionId 作为 operatorId\r \r 如果获取失败，会显示友好的错误提示。\r \r

执行规则\r

\r

• 读取操作不受白名单限制\r
• 写入操作必须通过白名单检查;未配置 workspace 或节点名不在白名单内时，一律拒绝!没有任何方式可以绕过白名单检查!\r
• whitelist: ["/"] 表示允许写入该 workspace 下的所有节点;更细粒度控制请配置具体文档名，例如 "/三级目录测试文档.adoc"\r
• 白名单配置文件 config/whitelist.json 只能由用户手动修改;AI 只能读取、解释、提示用户手动调整，不能替用户改\r
• 如果用户没有给出 workspaceId,先运行 list-workspaces\r
• 如果用户没有给出目标文档的 nodeId / docKey,先运行 list-docs、search 或 get-doc 确认目标\r \r

URL 解析规则\r

\r 当用户提供钉钉文档 URL 时，按以下规则提取 nodeId:\r \r URL 格式: https://alidocs.dingtalk.com/i/nodes/\x3CnodeId>?...\r \r 提取方法:\r

1. 从 URL 中提取 nodes/ 和 ? 之间的部分\r
2. 该部分即为 nodeId\r \r 示例:\r

URL: https://alidocs.dingtalk.com/i/nodes/oP0MALyR8kOd5BGacKv6NbxE83bzYmDO?utm_scene=team_space\r
nodeId: oP0MALyR8kOd5BGacKv6NbxE83bzYmDO\r
```\r
\r
**提取到 nodeId 后的操作:**\r
1. **获取文档元数据**（名称、知识库 ID 等）：`get-doc --nodeId=\x3C提取的 nodeId>`\r
2. **获取文档内容**（总结、读取正文）：`get-content --docKey=\x3C提取的 nodeId>`\r
3. 注意：`get-doc` 只返回元数据，`get-content` 才返回正文内容\r
\r
## 执行入口\r
\r
- `scripts/index.js`:主入口\r
- `scripts/whitelist.js`:辅助检查白名单配置\r
\r
**跨平台说明：**\r
\r
- 本 skill 的脚本基于 Node.js 内置模块实现，Windows、Linux、macOS 只要安装了 `node` 并配置好环境变量，都可以运行\r
- 推荐优先使用相对路径执行：`node scripts/index.js ...`，这样最不容易受平台路径差异影响\r
\r
**路径示例：**\r
\r
Windows PowerShell 中 `~` 不会自动展开，建议使用以下方式之一：\r
\r
```bash\r
# ✅ 使用 $env:USERPROFILE\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js\r
\r
# ✅ 或使用完整绝对路径\r
node C:\Users\zhenhuaixiu\.openclaw\skills\dingtalk-doc\scripts\index.js\r
\r
# ❌ 错误（~ 不会展开）\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js\r
```\r
\r
Linux / macOS Shell 示例：\r
\r
```bash\r
# ✅ 当前目录下直接运行（推荐）\r
node scripts/index.js list-workspaces\r
\r
# ✅ 或使用完整绝对路径\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js list-workspaces\r
```\r
\r
## 命令映射\r
\r
**路径说明：**\r
\r
- Windows 示例中的 `$env:USERPROFILE\.openclaw` 会展开为 `C:\Users\\x3C用户名>\.openclaw`\r
- Linux / macOS 示例中的 `~/.openclaw` 会展开为用户主目录下的 `.openclaw`\r
- 如果当前工作目录已经在 skill 根目录，直接使用 `node scripts/index.js ...` 即可\r
\r
### 读取操作\r
\r
| 命令 | 用途 | API 端点 |\r
|------|------|---------|\r
| `list-workspaces` | 获取知识库列表 | `GET /v2.0/wiki/mineWorkspaces` |\r
| `list-docs` | 获取知识库中文档列表 | `GET /v2.0/wiki/nodes` |\r
| `get-doc` | 获取**文档元数据**（名称、ID、创建者、字数等） | `GET /v2.0/wiki/nodes/{nodeId}` |\r
| `get-content` | 获取**文档正文内容**（段落、标题、列表等块结构） | `GET /v1.0/doc/suites/documents/{docKey}/blocks` |\r
| `search` | 搜索文档 | `GET /v1.0/doc/workspaces/{workspaceId}/docs` |\r
\r
**示例：**\r
```bash\r
# Linux / macOS\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js list-workspaces\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js list-docs --workspaceId=YRBGvyxxx --parentNodeId=root\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js get-doc --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js get-content --docKey=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js search --workspaceId=YRBGvyxxx --keyword="需求"\r
\r
# Windows PowerShell\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js list-workspaces\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js list-docs --workspaceId=YRBGvyxxx --parentNodeId=root\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js get-doc --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js get-content --docKey=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js search --workspaceId=YRBGvyxxx --keyword="需求"\r
```\r
\r
### 写入操作\r
\r
```bash\r
# Linux / macOS\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js create-doc --workspaceId=YRBGvyxxx --name="新文档" --docType=DOC --parentNodeId=root\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js update-content --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz --content="# 标题\
\
内容"\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js update-content --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz --docKey=真实docKey --content="# 标题\
\
内容"\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js delete-doc --workspaceId=YRBGvyxxx --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz\r
\r
# Windows PowerShell\r
# 创建文档\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js create-doc --workspaceId=YRBGvyxxx --name="新文档" --docType=DOC --parentNodeId=root\r
# 返回：{ "docKey": "abc123", "nodeId": "xyz789", ... }\r
\r
# 更新文档内容（整篇覆写，替换全部内容）\r
# ✅ 推荐：只用 nodeId（大多数情况够用）\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js update-content --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz --content="# 标题\
\
内容"\r
\r
# ✅ 备选：如果上面失败，传入真实的 docKey\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js update-content --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz --docKey=真实 docKey --content="# 标题\
\
内容"\r
\r
# 删除文档\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js delete-doc --workspaceId=YRBGvyxxx --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz\r
```\r
\r
### 块级操作（精细修改单个段落/元素）\r
\r
说明：\r
\r
- `insert-block`、`modify-block`、`delete-block` 已通过真实文档测试\r
- `append-text` 对应的公开 API 当前返回 `InvalidAction.NotFound`，不要再调用或承诺\r
- 如果用户要“追加内容”，优先改成“插入一个新段落”或“读取原段落后使用 `modify-block` 整块替换”\r
\r
```bash\r
# Linux / macOS\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js delete-block --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz --blockId=blk123\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js modify-block --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz --blockId=blk123 --element='{"blockType":"paragraph","paragraph":{"text":"新内容"}}'\r
node ~/.openclaw/skills/dingtalk-doc/scripts/index.js insert-block --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz --element='{"blockType":"paragraph","paragraph":{"text":"插入的内容"}}' --position=3\r
\r
# Windows PowerShell\r
# 删除块元素（删除某个段落/标题/列表项）\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js delete-block --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz --blockId=blk123\r
\r
# 修改块元素（替换单个块的内容，不影响其他部分）\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js modify-block --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz --blockId=blk123 --element='{"blockType":"paragraph","paragraph":{"text":"新内容"}}'\r
\r
# 插入块元素（在指定位置插入新段落/标题等）\r
node $env:USERPROFILE\.openclaw\skills\dingtalk-doc\scripts\index.js insert-block --nodeId=YQBnd5ExVE0PDnezU2PK2RK6WyeZqMmz --element='{"blockType":"paragraph","paragraph":{"text":"插入的内容"}}' --position=3\r
```\r
\r
### 参数说明\r
\r
- `docType`: `DOC`(文字) | `WORKBOOK`(表格) | `MIND`(脑图) | `FOLDER`(文件夹)\r
- `nodeId`: **必填**，节点 ID（用于白名单检查）\r
  - 从文档链接 `alidocs.dingtalk.com/i/nodes/xxx` 提取 `xxx` 部分\r
  - 通过 `get-doc --nodeId=xxx` 或 `get-content --docKey=xxx` 确认\r
- `docKey`: **可选**，真实的文档标识符（用于实际写入 API）\r
  - 如果不传，默认使用 `nodeId` 代替\r
  - 仅在 `nodeId` 作为 `docKey` 写入失败时，才需要传入真实的 `docKey`\r
  - 真实 `docKey` 可通过 createDoc 返回值或钉钉 API Explorer 获取\r
- `blockId`: 块 ID，通过 `get-content` 获取文档结构后得到（块级操作必需）\r
- `element`: 块元素 JSON 对象（**会自动解析**，直接传 JSON 字符串即可）\r
  - 示例：`--element='{"blockType":"paragraph","paragraph":{"text":"新内容"}}'`\r
- `position`: 插入位置（可选），数字，**支持 0**（表示插到最前面）\r
- `workspaceId`: 知识库 ID（可选）\r
  - 注意：写入操作会通过 `nodeId` 查询节点真实 `workspaceId`，传入 `--workspaceId` 时只能作为一致性校验，不能跳过查询\r
  - 适用场景：已知 `workspaceId` 且想显式校验目标文档属于该知识库，但 `nodeId` 仍必需\r
\r
### 命令选择指南\r
\r
| 需求 | 使用命令 | 说明 |\r
|------|---------|------|\r
| 重写整篇文档 | `update-content --nodeId=xxx --content="..."` | 替换全部内容 |\r
| 只修改某个段落 | `modify-block --nodeId=xxx --blockId=blk --element='{...}'` | 只影响单个块 |\r
| 在当前位置新增一段 | `insert-block --nodeId=xxx --element='{...}' --position=3` | 插入一个新块，更适合“追加一段”的需求 |\r
| 删除某一段/标题 | `delete-block --nodeId=xxx --blockId=blk` | 删除块 |\r
| 插入新段落/标题 | `insert-block --nodeId=xxx --element='{...}' --position=3` | 在指定位置插入 |\r
\r
## 常见问题\r
\r
1. **"无法获取文档信息"错误**: \r
   - 确保传入的是 `nodeId`（从文档链接 `/i/nodes/xxx` 提取）\r
   - `--workspaceId` 不能替代 `nodeId`，只能作为额外一致性校验\r
   \r
2. **"paramError" / JSON 解析失败**: \r
   - `--element` 必须是合法的 JSON 格式，检查引号转义\r
   - PowerShell 中用单引号包裹：`--element='{"type":"paragraph"}'`\r
   \r
3. **更新失败（nodeNotExist 等）**: \r
   - 尝试传入真实的 `docKey`：`update-content --nodeId=xxx --docKey=真实 docKey --content="..."`\r
   - createDoc 返回的 `docKey` 和 `nodeId` 可能不同\r
\r
4. **nodeId 和 docKey 到底有什么区别？**\r
   - `nodeId`: 目录树节点 ID（wiki_2.0 API 用），用于定位文档、获取 workspaceId 和节点名、执行白名单检查\r
   - `docKey`: 文档内容标识符（suites/documents API 用），用于实际读写内容\r
   - 经验：大多数情况下 `nodeId` 可直接用作 `docKey`，少数情况需要真实 `docKey`\r
\r
5. **为什么没有 append-text？**\r
   - 当前公开接口 `POST /v1.0/doc/suites/documents/{docKey}/paragraphs/{blockId}/text` 在真实测试中返回 `InvalidAction.NotFound`\r
   - 因此本 skill 不再承诺 `append-text`，请使用 `insert-block` 或 `modify-block`\r
\r
## 推荐流程\r
\r
1. 先确认凭证和 sender_id 是否可用。\r
2. 需要定位文档所在知识库时先跑 `list-workspaces`。\r
3. 需要定位文档时先跑 `list-docs`、`search`、`get-doc`。\r
4. 执行写操作前，默认假设会触发白名单校验，不要跳过读取确认步骤。\r
5. 如果写入被拒绝，只说明是哪个 workspace / 节点名未通过白名单，并提示用户手动调整 `config/whitelist.json`。\r
\r
## 常见失败\r
\r
- 缺少 sender_id:检查钉钉连接器是否注入 `OPENCLAW_SENDER_ID` / `DINGTALK_SENDER_ID`\r
- `forbidden.accessDenied`:检查应用权限或白名单\r
- `invalidRequest.workspaceNode.parentNotFound`:检查 `parentNodeId`\r
- `权限拒绝：知识库 xxx 未配置白名单`:让用户手动补充 `config/whitelist.json`\r
- `nodeNotExist`(更新内容时):**尝试使用 nodeId 代替 docKey** - 钉钉 API 中 createDoc 返回的 docKey 和 overwriteContent 需要的 docKey 可能不一致\r
- `blockNotExist`(块级操作时):先用 `get-content` 获取文档结构，确认 blockId 正确\r
- `paramError`(modify-block/insert-block):检查 `--element` 参数是否是合法的 JSON 格式\r
\r
## 重要提示\r
\r
### get-doc vs get-content\r
\r
| 命令 | 用途 | 返回内容 | 何时使用 |\r
|------|------|---------|---------|\r
| `get-doc` | 获取**文档元数据** | `data.node`：名称、ID、创建者、修改时间、字数、workspaceId | 确认文档存在、获取文档基本信息、定位知识库 |\r
| `get-content` | 获取**文档正文** | `data.result.data[]`：段落、标题、列表等块结构 | 总结内容、读取正文、准备修改文档 |\r
\r
**关键区别：**\r
- `get-doc` → `GET /v2.0/wiki/nodes/{nodeId}` → **不包含正文内容**\r
- `get-content` → `GET /v1.0/doc/suites/documents/{docKey}/blocks` → **包含正文块结构**\r
- **总结、读取内容时，始终使用 `get-content`，不要用 `get-doc`**\r
\r
### docKey vs nodeId\r
\r
- `nodeId`: 目录树节点 ID（wiki_2.0 API 用），用于定位文档、获取 workspaceId 和节点名、执行白名单检查\r
- `docKey`: 文档内容标识符（suites/documents API 用），用于实际读写内容\r
- `create-doc` 返回的 `docKey` 和 `nodeId` 可能是不同的值\r
- `update-content`、`get-content` 等命令**优先使用 `nodeId`** 作为 `--docKey` 参数\r
- 如果使用 `docKey` 更新失败 (`nodeNotExist`),请改用 `nodeId`\r
- 经验：大多数情况下 `nodeId` 可直接用作 `docKey`，少数情况需要真实 `docKey`\r
\r
**示例:**\r
\r
```bash\r
# 创建文档后，使用返回的 nodeId 进行更新\r
node .../index.js create-doc --workspaceId=xxx --name="新文档"\r
# 返回:{ "docKey": "abc123", "nodeId": "xyz789", ... }\r
\r
# ✅ 正确：使用 nodeId 更新\r
node .../index.js update-content --docKey=xyz789 --content="..."\r
\r
# ❌ 可能失败：使用 docKey 更新\r
node .../index.js update-content --docKey=abc123 --content="..."\r
```\r
\r
## 参考\r
\r
- 详细说明见 `README.md`\r
- 钉钉开放平台文档:[knowledge-base-overview](https://open.dingtalk.com/document/development/knowledge-base-overview)\r
- API Explorer:[open-dev.dingtalk.com/apiExplorer](https://open-dev.dingtalk.com/apiExplorer)\r