D131: tencent-docs-write 工具链重写 · 移除markdown方案改用MDX正确格式 · smartcanvas.edit/INSERT_AFTER/UPDATE 实战验证

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

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