95 lines
3.3 KiB
Markdown
95 lines
3.3 KiB
Markdown
---
|
||
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）组织章节，配合腾讯文档客户端自带的目录面板导航。
|