---
name: tencent-docs-write
description: 向腾讯文档（智能文档/smartcanvas）写入内容的标准工具链。当需要在腾讯文档中创建项目看板、追加分镜脚本、更新进度等人类可读内容时触发。已通过D130/D131实战验证。
agent_created: true
created: D131 · 2026-06-12 · 铸渊 ICE-GL-ZY001
---

# 腾讯文档写入 · 标准工具链

## 核心规则

**用 MDX 格式，通过 `smartcanvas.edit` 操作已有智能文档。不用 `<Page>` 包裹，直接用 `<Heading>/<Paragraph>/<BlockQuote>/<Divider/>` 这些容器标签。**

关键教训（D131踩坑）：
- ✅ 加粗用 `**文本**`，不要用 `<strong>文本</strong>` → `<strong>` 会在页面显示为纯文本
- ✅ 表格用 `<Table>` + `<TableRow>` + `<TableCell>` 但结构复杂容易出错 → 优先用列表替代
- ✅ 简单列表文字比表格更安全，渲染100%正确

## 工具链

### 追加新内容（最常用）

```json
{
  "toolName": "mcp__tencent-docs__smartcanvas.edit",
  "params": {
    "file_id": "DTHhuWW5OQU9VbFVX",
    "action": "INSERT_AFTER",
    "id": "",
    "content": "<Heading level=\"2\">十、新章节</Heading>\n\n<BlockQuote>摘要说明</BlockQuote>\n\n<Heading level=\"3\">子标题</Heading>\n\n<Paragraph>正文内容，**加粗文字**，普通文字。</Paragraph>\n\n<Divider/>\n\n<Paragraph>底部标注</Paragraph>"
  }
}
```

`id` 为空 = 追加到文档末尾。这是最常用的模式。

### 修改已有内容

```json
// 1. 先搜索找到要修改的块
{
  "toolName": "mcp__tencent-docs__smartcanvas.find",
  "params": { "file_id": "DTHhuWW5OQU9VbFVX", "query": "要搜索的文本" }
}
// 2. 拿到块id后更新
{
  "toolName": "mcp__tencent-docs__smartcanvas.edit",
  "params": {
    "file_id": "DTHhuWW5OQU9VbFVX",
    "action": "UPDATE",
    "id": "对应的块ID",
    "content": "<Paragraph id=\"块ID\">新内容</Paragraph>"
  }
}
```

### 读取文档内容

```json
{
  "toolName": "mcp__tencent-docs__smartcanvas.read",
  "params": { "file_id": "DTHhuWW5OQU9VbFVX" }
}
```

可分页：返回 `next_token` → 传 `next_token` 继续读取。

## 支持的MDX容器

| 容器 | 写法 | 用途 |
|------|------|------|
| 标题 | `<Heading level="2">章节</Heading>` | level 2=二级标题, 3=三级标题 |
| 段落 | `<Paragraph>正文**加粗**</Paragraph>` | 正文，内嵌 `**加粗**` |
| 引用 | `<BlockQuote>提示内容</BlockQuote>` | 摘要/说明/引用 |
| 分割线 | `<Divider/>` | 章节分区 |

## 严格禁止

- ❌ `<strong>` `<b>` 等HTML标签 → 会显示为纯文本
- ❌ `<Page>` 包裹 → 不需要
- ❌ `<Table>` 复杂嵌套 → 优先用列表文字
- ❌ 中文字符直接嵌入MDX标签属性 → 用纯文本Paragraph

## 文档ID

光湖视频AI项目看板: `DTHhuWW5OQU9VbFVX`

## 树状目录导航

智能文档API的 `<Heading>` 自动生成目录锚点。在文档顶部创建一个目录章节，用列表列出各章节名称即可。读者在腾讯文档客户端可以点击目录跳转（腾讯文档自带目录功能）。

如果需要真正的多页面树状结构，使用 `smartcanvas.get_top_level_pages` 查看页面结构，通过腾讯文档网页端手动创建子页面并链接。API目前不直接支持创建子页面。

推荐的折中方案：单文档内用 Heading 层级（level 2/3）组织章节，配合腾讯文档客户端自带的目录面板导航。