guanghulab/.workbuddy/skills/tencent-docs-write/SKILL.md

name, description, agent_created, created

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

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

核心规则

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

关键教训（D131踩坑）：

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

工具链

追加新内容（最常用）

{
  "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 为空 = 追加到文档末尾。这是最常用的模式。

修改已有内容

// 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>"
  }
}

读取文档内容

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