知识库空间 API 参考

本文件包含腾讯文档 MCP 知识库空间相关工具的 API 说明，包括空间管理和节点操作。

---

通用类型说明

node_type 枚举值

值	说明
wiki_folder	文件夹
wiki_tdoc	在线文档（请求时使用）
wiki_file	在线文档（返回值中使用）
link	链接
resource	资源文件

doc_type 枚举值

值	说明
word	文字处理文档
excel	电子表格
form	收集表
slide	幻灯片
smartcanvas	智能文档
smartsheet	智能表格
mind	思维导图
flowchart	流程图

NodeInfo 节点信息结构

{
  "node_id": "节点 ID，同时也是 file_id",
  "title": "节点标题",
  "node_type": "节点类型",
  "has_child": true,
  "doc_type": "文档类型（仅 wiki_file 有效）",
  "url": "访问链接"
}

StringMatrix 表格数据结构

{
  "texts": {
    "rows": [
      {"values": ["单元格1", "单元格2"]},
      {"values": ["单元格3", "单元格4"]}
    ]
  }
}

数据从 A1 单元格开始，按行列顺序填充。

---

工具列表

工具名称	功能说明
query_space_list	获取知识库空间列表
create_space	创建新的知识库空间
query_space_node	查询空间内节点列表
create_space_node	在空间中创建新节点（文件夹、文档或链接）
delete_space_node	删除空间中的指定节点

---

工具详细说明

1. query_space_list

功能说明

获取知识库空间列表，支持按不同方式排序和分页查询。

调用示例

{
  "num": 0,
  "order_by": 1,
  "query_by": 1,
  "descending": true
}

参数说明

• num (uint32, 可选): 分页页码，从0开始，每页最多返回100个空间
• order_by (uint32, 可选): 排序方式（1-按最近预览时间排序，2-按最近编辑时间排序，3-按创建时间排序）
• query_by (uint32, 可选): 查询范围（0-查询全部空间（默认），1-仅查询我创建的空间，2-仅查询我加入的空间）
• descending (bool, 可选): 是否降序排列，true-降序（最新在前），false-升序，默认为true

返回值说明

{
  "spaces": [
    {
      "space_id": "space_1234567890",
      "title": "我的知识库",
      "description": "知识库描述",
      "is_top": false,
      "file_cnt": 10,
      "member_cnt": 5,
      "is_owner": true,
      "created_at": 1713600000,
      "updated_at": 1713600000
    }
  ],
  "has_next": false,
  "error": "",
  "trace_id": "trace_1234567890"
}

2. create_space

功能说明

创建新的知识库空间。空间是组织和管理文档的容器，可以包含文件夹、文档等节点。

调用示例

{
  "title": "项目文档库",
  "description": "存放项目相关的所有文档"
}

参数说明

• title (string, 必填): 空间标题
• description (string, 可选): 空间描述

返回值说明

{
  "space_id": "space_1234567890",
  "error": "",
  "trace_id": "trace_1234567890"
}

3. query_space_node

功能说明

查询空间内的节点列表，支持按父节点分页查询。

调用示例

{
  "space_id": "space_1234567890",
  "parent_id": "folder_1234567890",
  "num": 0
}

参数说明

• space_id (string, 必填): 空间ID，用于指定查询的空间
• parent_id (string, 可选): 父节点ID，为空时返回根节点
• num (uint32, 可选): 分页页码，从0开始，每页返回20个节点

返回值说明

{
  "children": [
    {
      "node_id": "doc_1234567890",
      "title": "项目文档",
      "node_type": "wiki_file",
      "has_child": false,
      "doc_type": "smartcanvas",
      "url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH"
    }
  ],
  "error": "",
  "has_next": false,
  "trace_id": "trace_1234567890"
}

4. create_space_node

功能说明

在空间中创建新节点（文件夹、文档或链接）。

调用示例

{
  "space_id": "space_1234567890",
  "parent_node_id": "folder_1234567890",
  "title": "新建页面文档1",
  "node_type": "wiki_tdoc",
  "wiki_tdoc_node": {
    "title": "新建页面文档",
    "doc_type": "smartcanvas"
  }
}

参数说明

• space_id (string, 必填): 空间ID，用于指定在哪个空间下创建节点
• parent_node_id (string, 可选): 父节点ID，为空或在根目录创建时可不传
• title (string, 必填): 节点标题
• node_type (string, 必填): 节点类型（wiki_folder/wiki_tdoc/link）
• is_before (bool, 可选): 插入位置，true 表示插入到父节点子列表开头，false 表示插入到末尾
• wiki_folder_node (object, 可选): 文件夹节点配置，node_type 为 wiki_folder 时必填
• wiki_tdoc_node (object, 可选): 在线文档节点配置，node_type 为 wiki_tdoc 时必填
• link_node (object, 可选): 链接节点配置，node_type 为 link 时必填

返回值说明

{
  "node_info": {
    "node_id": "doc_1234567890",
    "title": "新建页面文档",
    "node_type": "wiki_file",
    "has_child": false,
    "doc_type": "smartcanvas",
    "url": "https://docs.qq.com/doc/DV2h5cWJ0R1lQb0lH"
  },
  "error": "",
  "trace_id": "trace_1234567890"
}

5. delete_space_node

功能说明

删除空间中的指定节点。仅删除当前节点时，子节点自动挂载到上级节点；使用 all 模式时递归删除所有子节点（谨慎使用）。

调用示例

{
  "space_id": "space_1234567890",
  "node_id": "doc_1234567890",
  "remove_type": "current"
}

参数说明

• space_id (string, 必填): 空间ID
• node_id (string, 必填): 要删除的节点ID
• remove_type (string, 可选): 删除类型，枚举值：current（默认，仅删除当前节点，子节点挂载到上级）、all（删除当前节点及所有子节点，⚠️ 谨慎使用）

返回值说明

{
  "error": "",
  "trace_id": "trace_1234567890"
}

---

典型工作流示例

组织文档到指定空间目录

1. 调用 query_space_list 获取空间列表，找到目标空间的 space_id
2. 调用 query_space_node 遍历空间节点，查找目标文件夹，获取 parent_node_id
3. 调用 create_space_node 在目标位置创建文档节点（doc_type 优先选择 smartcanvas）
   或调用 manage.create_file（传入 space_id 和 parent_id）在空间内创建文件，两者均可

查找空间中的文档

1. 调用 query_space_list 获取空间列表
2. 调用 query_space_node 遍历节点树查找文档
3. 从结果中获取 node_id（即 file_id）和 url

---

注意事项

• node_id 即 file_id：空间节点的 node_id 同时也是文档的 file_id
• 删除节点需谨慎：delete_space_node 默认仅删除当前节点（remove_type=current），使用 all 时会递归删除所有子节点
• 分页查询：query_space_list 每页 100 条，query_space_node 每页 20 条，使用 has_next 判断是否有更多数据，页码从 0 开始