Files

root 691b8cdd0c feat: 初始化黄小瓜AI助手记忆仓库

- 核心配置: IDENTITY, USER, SOUL, AGENTS, TOOLS, HEARTBEAT, MEMORY
- memory/: 每日总结和临时记录
- skills/: 所有已安装技能
- notes/: 语音配置笔记

2026-04-04 02:42:48 +08:00

24 KiB

Raw Permalink Blame History

文档（SmartCanvas）工具完整参考文档

腾讯文档文档（SmartCanvas）提供了一套完整的文档元素操作 API，支持对页面、文本、标题、待办事项等元素进行增删改查操作。

概念说明

概念	说明
`file_id`	文档的唯一标识符，每个文档有唯一的 file_id
`element_id`	元素 ID，文档中每个元素（页面、文本、标题、任务）都有唯一 ID
`page_id`	页面元素 ID，Page 是文档的基本容器单元
`parent_id`	父元素 ID，用于确定元素的层级关系

元素层级关系：

file_id（文档）
└── Page（页面）
    ├── Heading（标题，LEVEL_1 ~ LEVEL_6）
    ├── Text（文本）
    └── Task（待办事项）

⚠️ 重要约束：

Text、Task、Heading 必须挂载在 Page 类型的父节点下

Page 可以不指定父节点（挂载到根节点）

父节点不支持为 Heading 类型

创建智能文档 — create_smartcanvas_by_mdx

通过 MDX 格式创建排版丰富的在线智能文档。MDX 支持分栏布局（ColumnList）、高亮块（Callout）、待办列表（Todo）、表格（Table）、带样式文本（Mark）等高级组件。MDX 内容必须严格遵循 mdx_references.md 规范生成。

📖 MDX 规范详见： mdx_references.md

工作流

1. 阅读 mdx_references.md 了解 MDX 组件规范（组件、属性、取值白名单、格式约束）
2. 按规范生成包含 Frontmatter 和 MDX 组件的内容
3. 对照 mdx_references 逐条自校验，确保格式合规
4. 调用 create_smartcanvas_by_mdx 创建文档（传入 title + MDX 内容）
5. 从返回结果中获取 file_id 和 url

参数说明

参数	类型	必填	说明
`title`	string	✅	文档标题，不超过36个字符
`mdx`	string	✅	严格符合 mdx_references 规范的 MDX 格式文本
`parent_id`	string		父节点ID，为空时在空间根目录创建，不为空时在指定节点下创建

调用示例

{
  "title": "项目需求文档",
  "mdx": "---\ntitle: 项目需求文档\nicon: 📋\n---\n\n# 项目需求\n\n<Callout icon=\"📌\" blockColor=\"light_blue\" borderColor=\"blue\">\n    本项目旨在开发一套智能文档管理系统。\n</Callout>\n\n## 功能需求\n\n<BulletedList>\n    文档创建功能\n</BulletedList>\n<BulletedList>\n    文档编辑功能\n</BulletedList>\n<BulletedList>\n    协作功能\n</BulletedList>"
}

返回值说明

{
  "file_id": "doc_1234567890",
  "url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH",
  "error": "",
  "trace_id": "trace_1234567890"
}

元素操作

smartcanvas.create_smartcanvas_element

功能：在文档中新增元素，支持同时添加页面、文本、标题、待办事项等多种类型元素。

使用场景：

在文档中追加新页面
在已有页面中添加文本、标题、待办事项
在指定元素后面插入新内容

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	文档的唯一标识符
`parent_id`	string	条件必填	父节点元素 ID。插入 Text/Task/Heading 时必填（父节点必须为 Page 类型）；插入 Page 时可不填（插入到根节点）
`after`	string		插入到哪个节点之后的元素 ID，不填则作为父节点的最后一个子节点插入
`pages`	[]Page		要添加的页面元素列表
`texts`	[]Text		要添加的文本元素列表
`tasks`	[]Task		要添加的待办事项元素列表
`headings`	[]Heading		要添加的标题元素列表
`image`	[]Image		要添加的图片元素列表，需先调用 `upload_image` 获取 image_ID

返回字段：

字段	类型	说明
`element_infos`	array	创建的元素信息列表，详见 ElementInfo 结构
`error`	string	错误信息，操作失败时返回
`trace_id`	string	调用链追踪 ID

ElementInfo 结构：

字段	类型	说明
`id`	string	元素唯一标识符
`version`	uint32	元素版本号
`type`	string	元素类型：Page、Text、Heading、Task
`element`	string	元素内容（JSON 格式字符串）
`parent_id`	string	父元素 ID
`children`	[]string	子元素 ID 列表
`created_by`	string	创建者用户 ID
`created_at`	uint64	创建时间戳（毫秒）
`updated_by`	string	最后更新者用户 ID
`updated_at`	uint64	最后更新时间戳（毫秒）

调用示例（新增页面）：

{
  "file_id": "your_file_id",
  "pages": [
    {
      "title": "第一章：项目背景"
    }
  ]
}

调用示例（在页面中添加标题和文本）：

{
  "file_id": "your_file_id",
  "parent_id": "page_element_id",
  "headings": [
    {
      "rich_text": {
        "text": "项目目标",
        "formats": {
          "bold": true
        }
      },
      "level": "LEVEL_1"
    }
  ],
  "texts": [
    {
      "rich_text": {
        "text": "本项目旨在提升用户体验，优化核心流程。"
      }
    }
  ]
}

调用示例（添加待办事项）：

{
  "file_id": "your_file_id",
  "parent_id": "page_element_id",
  "tasks": [
    {
      "rich_text": {
        "text": "完成需求评审"
      },
      "reminder": {
        "due_time": 1720072890000,
        "reminder_time": 30
      }
    },
    {
      "rich_text": {
        "text": "提交设计稿"
      }
    }
  ]
}

调用示例（添加图片）：

⚠️ 需先调用 upload_image 上传图片获取 image_id，再传入此处。

{
  "file_id": "your_file_id",
  "parent_id": "page_element_id",
  "image": [
    {
      "image_id": "从 upload_image 返回的 image_id",
      "width": 800,
      "height": 600
    }
  ]
}

smartcanvas.get_element_info

功能：批量查询指定元素的详细信息，支持同时查询多个元素。

使用场景：

查询特定元素的内容和属性
获取元素的父子关系
验证元素是否存在及其当前状态

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	文档的唯一标识符
`element_ids`	[]string	✅	查询元素 ID 列表，支持批量查询多个元素

返回字段：

字段	类型	说明
`element_infos`	array	查询到的元素信息列表，详见 ElementInfo 结构
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "element_ids": ["element_id_001", "element_id_002"]
}

返回示例：

{
  "element_infos": [
    {
      "id": "element_id_001",
      "version": 3,
      "type": "Page",
      "element": "{\"title\": \"第一章：项目背景\"}",
      "parent_id": "",
      "children": ["element_id_003", "element_id_004"],
      "created_by": "user_001",
      "created_at": 1720000000000,
      "updated_by": "user_001",
      "updated_at": 1720086400000
    }
  ],
  "error": "",
  "trace_id": "trace_xyz"
}

smartcanvas.get_page_info

功能：查询指定页面内的所有元素，支持分页获取。

使用场景：

读取某个页面下的所有内容（标题、文本、待办事项）
分页获取内容较多的页面
遍历文档内容进行分析

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	文档的唯一标识符
`page_id`	string	✅	要查询的页面元素 ID
`cursor`	[]CursorItem		分页游标，首次查询不传，后续查询使用上次响应返回的 cursor

CursorItem 结构：

字段	类型	说明
`id`	string	游标 ID
`index`	uint32	游标索引位置

返回字段：

字段	类型	说明
`element_infos`	array	页面内的元素信息列表
`cursor`	[]CursorItem	下次分页的 cursor 信息
`is_over`	bool	是否已查询完所有内容，为 true 表示分页结束
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例（首次查询）：

{
  "file_id": "your_file_id",
  "page_id": "page_element_id"
}

调用示例（分页继续查询）：

{
  "file_id": "your_file_id",
  "page_id": "page_element_id",
  "cursor": [
    { "id": "cursor_id_001", "index": 20 }
  ]
}

smartcanvas.get_top_level_pages

功能：查询文档的所有顶层页面列表，返回根节点下的直接子页面。

使用场景：

获取文档的目录结构（顶层页面列表）
遍历文档所有页面
在操作前先了解文档的页面组织结构

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	文档的唯一标识符

返回字段：

字段	类型	说明
`top_level_pages`	array	顶层页面列表，包含所有顶级页面的基本信息
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id"
}

返回示例：

{
  "top_level_pages": [
    {
      "id": "page_id_001",
      "type": "Page",
      "element": "{\"title\": \"第一章：项目背景\"}",
      "children": ["element_id_003", "element_id_004"]
    },
    {
      "id": "page_id_002",
      "type": "Page",
      "element": "{\"title\": \"第二章：技术方案\"}",
      "children": ["element_id_005"]
    }
  ],
  "error": "",
  "trace_id": "trace_xyz"
}

smartcanvas.update_element

功能：批量修改元素内容，支持同时更新多个元素的文本、格式、标题级别等属性。

使用场景：

修改页面标题
更新文本内容或格式（加粗、颜色等）
修改标题级别
更新待办事项内容或截止时间

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	文档的唯一标识符
`updates`	[]UpdateElementRequest	✅	元素更新请求列表，支持批量更新多个元素

UpdateElementRequest 结构：

字段	类型	必填	说明
`element_id`	string	✅	要更新的元素 ID
`page`	Page		更新页面元素（修改标题）
`text`	Text		更新文本元素
`task`	Task		更新待办事项元素
`heading`	Heading		更新标题元素

返回字段：

字段	类型	说明
`updated_elements`	array	更新成功的元素信息列表
`error`	string	错误信息
`trace_id`	string	调用链追踪 ID

调用示例（修改页面标题）：

{
  "file_id": "your_file_id",
  "updates": [
    {
      "element_id": "page_element_id",
      "page": {
        "title": "第一章：项目背景（已更新）"
      }
    }
  ]
}

调用示例（修改文本内容和格式）：

{
  "file_id": "your_file_id",
  "updates": [
    {
      "element_id": "text_element_id",
      "text": {
        "rich_text": {
          "text": "这是更新后的文本内容，支持富文本格式。",
          "formats": {
            "bold": true,
            "text_color": "COLOR_BLUE"
          }
        },
        "block_color": "BG_COLOR_LIGHT_BLUE"
      }
    }
  ]
}

调用示例（修改标题级别）：

{
  "file_id": "your_file_id",
  "updates": [
    {
      "element_id": "heading_element_id",
      "heading": {
        "rich_text": {
          "text": "技术架构设计"
        },
        "level": "LEVEL_2"
      }
    }
  ]
}

调用示例（更新待办事项截止时间）：

{
  "file_id": "your_file_id",
  "updates": [
    {
      "element_id": "task_element_id",
      "task": {
        "rich_text": {
          "text": "完成代码评审"
        },
        "reminder": {
          "due_time": 1720159290000,
          "reminder_time": 60
        }
      }
    }
  ]
}

smartcanvas.delete_element

功能：批量删除元素，支持同时删除多个指定元素。

使用场景：

删除不再需要的页面或内容块
清理文档中的冗余内容
批量删除多个元素

⚠️ 注意：删除 Page 元素时，其下的所有子元素（Text、Heading、Task）也会被一并删除，请谨慎操作。

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	文档的唯一标识符
`element_ids`	[]string	✅	需要批量删除的元素 ID 列表

返回字段：

字段	类型	说明
`error`	string	错误信息，操作失败时返回
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "element_ids": ["element_id_001", "element_id_002"]
}

追加内容

smartcanvas.append_insert_smartcanvas_by_markdown 追加

功能：通过 Markdown 文本向已有文档追加内容，内容追加到文档末尾。

使用场景：

快速向文档末尾追加大段 Markdown 内容
批量导入 Markdown 格式的文档内容
在已有文档基础上继续补充内容

请求参数：

参数	类型	必填	说明
`file_id`	string	✅	文档的唯一标识符
`markdown`	string	✅	UTF-8 格式的 Markdown 文本，特殊字符不需要转义

返回字段：

字段	类型	说明
`error`	string	错误信息，操作失败时返回
`trace_id`	string	调用链追踪 ID

调用示例：

{
  "file_id": "your_file_id",
  "markdown": "## 新增章节\n\n这是通过 Markdown 追加的内容。\n\n- 支持列表\n- 支持**加粗**\n- 支持`代码`"
}

枚举值参考

标题级别（HeadingLevel）

枚举值	说明
`LEVEL_1`	一级标题（最大）
`LEVEL_2`	二级标题
`LEVEL_3`	三级标题
`LEVEL_4`	四级标题
`LEVEL_5`	五级标题
`LEVEL_6`	六级标题（最小）

文本颜色（TextColor）

枚举值	颜色
`COLOR_GREY`	灰色
`COLOR_BLUE`	蓝色
`COLOR_SKY_BLUE`	天蓝色
`COLOR_GREEN`	绿色
`COLOR_YELLOW`	黄色
`COLOR_ORANGE`	橙色
`COLOR_RED`	红色
`COLOR_ROSE_RED`	玫瑰红
`COLOR_PURPLE`	紫色

背景颜色（BackgroundColor）

枚举值	颜色
`BG_COLOR_GREY`	灰色
`BG_COLOR_LIGHT_GREY`	浅灰色
`BG_COLOR_DARK`	深色
`BG_COLOR_LIGHT_BLUE`	浅蓝色
`BG_COLOR_BLUE`	蓝色
`BG_COLOR_LIGHT_SKY_BLUE`	浅天蓝色
`BG_COLOR_SKY_BLUE`	天蓝色
`BG_COLOR_LIGHT_GREEN`	浅绿色
`BG_COLOR_GREEN`	绿色
`BG_COLOR_LIGHT_YELLOW`	浅黄色
`BG_COLOR_YELLOW`	黄色
`BG_COLOR_LIGHT_ORANGE`	浅橙色
`BG_COLOR_ORANGE`	橙色
`BG_COLOR_LIGHT_RED`	浅红色
`BG_COLOR_RED`	红色
`BG_COLOR_LIGHT_ROSE_RED`	浅玫瑰红
`BG_COLOR_ROSE_RED`	玫瑰红
`BG_COLOR_LIGHT_PURPLE`	浅紫色
`BG_COLOR_PURPLE`	紫色

元素类型详细说明

Page（页面）

页面是文档的基本容器单元，所有内容元素（Text、Heading、Task）都必须挂载在 Page 下。

{
  "title": "页面标题（仅支持纯文本）"
}

字段	类型	必填	说明
`title`	string		页面标题，仅支持纯文本，不支持富文本格式

Text（文本）

普通文本块，支持富文本格式和背景颜色。

{
  "rich_text": {
    "text": "文本内容",
    "formats": {
      "bold": false,
      "italic": false,
      "under_line": false,
      "strike": false,
      "text_color": "COLOR_BLUE",
      "background_color": "BG_COLOR_LIGHT_YELLOW",
      "text_link": {
        "link_url": "https://example.com"
      }
    }
  },
  "block_color": "BG_COLOR_LIGHT_GREY"
}

字段	类型	必填	说明
`rich_text`	RichText	✅	富文本内容
`block_color`	BackgroundColor		文本块背景颜色

Heading（标题）

标题块，支持 1-6 级标题，支持富文本格式和背景颜色。

{
  "rich_text": {
    "text": "标题内容",
    "formats": {
      "bold": true
    }
  },
  "level": "LEVEL_1",
  "block_color": "BG_COLOR_LIGHT_BLUE"
}

字段	类型	必填	说明
`rich_text`	RichText	✅	富文本内容
`level`	HeadingLevel	✅	标题级别，枚举值：LEVEL_1 ~ LEVEL_6
`block_color`	BackgroundColor		标题块背景颜色

Image（图片）

图片块，需先通过 upload_image 工具上传图片获取 image_id，再插入到文档中。

{
  "image_id": "从 upload_image 返回的 image_id",
  "width": 800,
  "height": 600
}

字段	类型	必填	说明
`image_id`	string	✅	图片 ID，通过 `upload_image` 工具上传图片后获取，有效期为一天
`width`	float		图片显示宽度（像素），不填则使用图片原始宽度
`height`	float		图片显示高度（像素），不填则使用图片原始高度

⚠️ 注意：image_id 有效期为一天，请在获取后及时使用。

Task（待办事项）

待办事项块，支持设置截止时间和提醒。

{
  "rich_text": {
    "text": "待办事项内容"
  },
  "reminder": {
    "due_time": 1720072890000,
    "reminder_time": 30
  }
}

字段	类型	必填	说明
`rich_text`	RichText	✅	待办事项文本内容
`reminder`	Reminder		提醒设置

Reminder 结构：

字段	类型	说明
`due_time`	uint64	任务截止时间，Unix 时间戳（毫秒），例如 `1720072890000`
`reminder_time`	int32	提前提醒时间间隔（分钟）

RichText（富文本）

富文本对象，包含文本内容和格式设置。

{
  "text": "文本内容",
  "formats": {
    "bold": true,
    "italic": false,
    "under_line": true,
    "strike": false,
    "text_color": "COLOR_RED",
    "background_color": "BG_COLOR_LIGHT_YELLOW",
    "text_link": {
      "link_url": "https://docs.qq.com"
    }
  }
}

Formats 格式说明：

字段	类型	说明
`bold`	bool	粗体
`italic`	bool	斜体
`under_line`	bool	下划线
`strike`	bool	删除线
`text_color`	TextColor	文本颜色，枚举值见上方
`background_color`	BackgroundColor	背景颜色，枚举值见上方
`text_link`	TextLink	文本链接，包含 `link_url` 字段

典型工作流示例

创建通用文档（推荐方式）

📖 参考文档： mdx_references.md — create_smartcanvas_by_mdx

1. 阅读 mdx_references.md 了解 MDX 组件规范
2. 按规范生成包含 Frontmatter 和 MDX 组件的内容
3. 对照 mdx_references 逐条自校验，确保格式合规
4. 调用 create_smartcanvas_by_mdx 创建文档
5. 从返回结果中获取 file_id 和 url

编辑已有文档（智能文档 smartcanvas）

1. 调用 smartcanvas.get_top_level_pages 获取文档页面结构
2. 按需调用 smartcanvas.* 工具进行增删改查：
   - 追加内容：smartcanvas.append_insert_smartcanvas_by_markdown（Markdown 方式）
   - 新增元素：smartcanvas.create_smartcanvas_element
   - 查询元素：smartcanvas.get_element_info / smartcanvas.get_page_info
   - 修改元素：smartcanvas.update_element
   - 删除元素：smartcanvas.delete_element

工作流一：创建结构化文档

步骤 1：创建文档
  → create_smartcanvas_by_mdx（创建文档，获取 file_id）

步骤 2：查询顶层页面
  → smartcanvas.get_top_level_pages（获取已有页面的 page_id）

步骤 3：在页面中添加内容
  → smartcanvas.create_smartcanvas_element（传入 parent_id=page_id，添加标题和文本）

步骤 4：继续追加内容
  → smartcanvas.create_smartcanvas_element（追加更多页面或内容块）

读取文档内容

步骤 1：获取顶层页面列表
  → smartcanvas.get_top_level_pages（获取所有顶层页面）

步骤 2：逐页读取内容
  → smartcanvas.get_page_info（传入 page_id，获取页面内所有元素）
  → 若 is_over=false，继续传入 cursor 获取下一页

步骤 3：（可选）查询特定元素详情
  → smartcanvas.get_element_info（传入 element_ids，获取元素详细信息）

工作流三：更新文档内容

步骤 1：获取顶层页面
  → smartcanvas.get_top_level_pages（获取页面列表）

步骤 2：读取页面内容，找到目标元素
  → smartcanvas.get_page_info（获取页面内元素及其 element_id）

步骤 3：更新目标元素
  → smartcanvas.update_element（传入 element_id 和新内容）

工作流四：追加内容到已有文档

步骤 1：获取文档 file_id
  → manage.search_file（搜索文档，获取文档id）

步骤 2：追加 Markdown 内容
  → smartcanvas.append_insert_smartcanvas_by_markdown（传入 file_id 和 markdown 内容）

步骤 3：（可选）精细化追加结构化元素
  → smartcanvas.get_top_level_pages（获取最新页面列表）
  → smartcanvas.create_smartcanvas_element（在指定页面后追加元素）

工作流五：清理文档内容

步骤 1：获取顶层页面
  → smartcanvas.get_top_level_pages

步骤 2：读取页面内容，找到要删除的元素
  → smartcanvas.get_page_info（获取 element_id 列表）

步骤 3：批量删除元素
  → smartcanvas.delete_element（传入 element_ids 数组）

注意事项

所有操作都需要先获取 file_id，可通过 manage.search_file 搜索文档获取，或在创建文档时从返回结果中获取
操作元素前，建议先调用 smartcanvas.get_top_level_pages 了解文档结构，再调用 smartcanvas.get_page_info 获取具体元素 ID
元素挂载约束：Text、Heading、Task、Image 必须挂载在 Page 下，parent_id 必须为 Page 类型元素 ID
分页查询：smartcanvas.get_page_info 使用 cursor 分页，is_over=true 表示已获取全部内容
删除注意：删除 Page 元素时，其下所有子元素也会被一并删除

24 KiB Raw Permalink Blame History Unescape Escape

文档（SmartCanvas）工具完整参考文档

目录

概念说明

创建智能文档 — create_smartcanvas_by_mdx

工作流

参数说明

调用示例

返回值说明

元素操作

smartcanvas.create_smartcanvas_element

smartcanvas.get_element_info

smartcanvas.get_page_info

smartcanvas.get_top_level_pages

smartcanvas.update_element

smartcanvas.delete_element

追加内容

smartcanvas.append_insert_smartcanvas_by_markdown 追加

枚举值参考

标题级别（HeadingLevel）

文本颜色（TextColor）

背景颜色（BackgroundColor）

元素类型详细说明

Page（页面）

Text（文本）

Heading（标题）

Image（图片）

Task（待办事项）

RichText（富文本）

典型工作流示例

创建通用文档（推荐方式）

编辑已有文档（智能文档 smartcanvas）

工作流一：创建结构化文档

读取文档内容

工作流三：更新文档内容

工作流四：追加内容到已有文档

工作流五：清理文档内容

注意事项

24 KiB

Raw Permalink Blame History