tencent-docs

腾讯文档（腾讯文档）

使用 curl + jq 调用 腾讯文档 Open API。所有操作都在用户自己的腾讯文档账号中执行——仅限他们有权访问的文件，且仅限他们连接时授予的权限范围。

身份验证 — 三个请求头（不是单个 Bearer）

tencentdocs BYOC 连接器会注入三个环境变量；每次调用都要发送这三个请求头：

• TENCENTDOCS_ACCESS_TOKEN → Access-Token 请求头（OAuth2 访问令牌）。机密。
• TENCENTDOCS_CLIENT_ID → Client-Id 请求头（开发者应用的 Client ID）。
• TENCENTDOCS_OPEN_ID → Open-Id 请求头（随令牌返回的用户 ID）。

所有端点都位于 https://docs.qq.com/openapi 下。每个会话开始时定义一次可复用的请求头集合：

AUTH=(-H "Access-Token: $TENCENTDOCS_ACCESS_TOKEN" \
      -H "Client-Id: $TENCENTDOCS_CLIENT_ID" \
      -H "Open-Id: $TENCENTDOCS_OPEN_ID")

切勿回显、打印或记录 TENCENTDOCS_ACCESS_TOKEN——它拥有完整的账号访问权限。

响应格式与错误处理

每个响应的格式都是 {"ret": 0, "msg": "Succeed", "data": {…}}。ret == 0 表示成功；任何非零 ret 都表示错误——向用户显示 msg。 务必检查：

resp=$(curl -sS "${AUTH[@]}" … )
echo "$resp" | jq 'if .ret == 0 then .data else error("Tencent Docs \(.ret): \(.msg)") end'

常见错误代码：

代码	含义	处理方式
400006	访问令牌无效 / 已过期	告知用户在 https://studio.acedata.cloud/console/connectors 重新连接腾讯文档——不要循环重试
400007	需要 VIP（超级会员）权限	所请求的功能需要腾讯文档超级会员；告知用户并提供链接 https://docs.qq.com/vip
400008	积分不足	AI 生成额度已用完；告知用户充值
11607 / -32603	请求参数错误	根据下方示例重新检查 fileID / type / 请求体字段

文档类型（创建时的 type）

type	产品	说明
doc	在线文档（Word 风格）	经典富文本文件
sheet	在线表格（Excel）	数据表格
slide	幻灯片（PPT）	演示文稿
mind	思维导图	思维导图
flowchart	流程图	流程图
smartsheet	智能表格	结构化多视图表格
form	收集表	表单 / 问卷

操作示例

验证身份验证（始终先执行）

简单的连通性检查——读取应用的 OpenAPI 使用量计数器：

curl -sS "${AUTH[@]}" "https://docs.qq.com/openapi/drive/v2/util/resource-use" \
  | jq 'if .ret == 0 then .data else "ERR \(.ret): \(.msg)" end'

如果返回 400006，说明连接已过期——请用户重新连接。

列出文件夹（根目录 = /）

curl -sS "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/folders/%2F?listType=folder&sortType=browse&asc=0" \
  | jq 'if .ret == 0 then [.data.list[]? | {ID, title, type, url}] else . end'

%2F 是经过 URL 编码的根文件夹 ID。要访问子文件夹，请在路径中使用其文件夹 ID。

按关键词搜索文件

curl -sS -G "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/search" \
  --data-urlencode "searchName=Q1 预算" \
  | jq 'if .ret == 0 then [.data.list[]? | {ID, title, type, url}] else . end'

读取文件元数据

fileID 是 https://docs.qq.com/doc/<id>（或 /sheet/、/slide/ 等）URL 中的最后一个路径段。

curl -sS "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID/metadata" \
  | jq 'if .ret == 0 then .data else . end'

读取在线文档内容

curl -sS "${AUTH[@]}" \
  "https://docs.qq.com/openapi/document/v3/files/FILE_ID/export?exportType=text" \
  | jq 'if .ret == 0 then .data else . end'

读取表格单元格区域

先从元数据中获取表格的 sheetId 列表，然后读取单元格区域（A1:D10）：

curl -sS "${AUTH[@]}" \
  "https://docs.qq.com/openapi/spreadsheet/v2/files/FILE_ID/sheets/SHEET_ID/values?range=A1:D10" \
  | jq 'if .ret == 0 then .data.values else . end'

创建文件

使用表单 URL 编码的 title 和 type 向 POST /openapi/drive/v2/files 发送请求。返回新文件的 ID 和 url。

curl -sS -X POST "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files" \
  --data-urlencode "title=会议纪要 2026-07-03" \
  --data-urlencode "type=doc" \
  | jq 'if .ret == 0 then {ID: .data.ID, url: .data.url} else . end'

要创建其他类型的文档，请将 type=sheet / slide / mind / flowchart / smartsheet / form 替换为相应类型。添加 --data-urlencode "folderID=<id>" 可在文件夹内创建，而非在根目录创建。

上传图片（用于嵌入文档）

curl -sS -X POST "${AUTH[@]}" \
  "https://docs.qq.com/openapi/resources/v2/images" \
  -F "file=@./cover.png" \
  | jq 'if .ret == 0 then .data else . end'

重命名文件 — 需先确认

向用户显示当前的 title 和 url 以及新标题，获得明确的“是”后再执行：

curl -sS -X PATCH "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID" \
  --data-urlencode "title=新的标题" \
  | jq 'if .ret == 0 then "renamed" else . end'

移动文件 — 需先确认

向用户显示文件当前的 title 和位置以及目标文件夹，获得明确的“是”后再执行。folderID=/ 可将文件移回根目录。

curl -sS -X PATCH "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID/move" \
  --data-urlencode "folderID=DEST_FOLDER_ID" \
  | jq 'if .ret == 0 then "moved" else . end'

复制文件

curl -sS -X POST "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID/copy" \
  --data-urlencode "title=副本 - 项目计划" \
  | jq 'if .ret == 0 then {ID: .data.ID, url: .data.url} else . end'

删除文件 — 需先确认

删除操作会将文件移至回收站，但仍具有破坏性。向用户显示确切的 title 和 url，获得明确的“是”后再执行：

curl -sS -X DELETE "${AUTH[@]}" \
  "https://docs.qq.com/openapi/drive/v2/files/FILE_ID" \
  | jq 'if .ret == 0 then "deleted" else . end'

注意事项

• 限制写入操作。 重命名、移动、删除、复制以及任何共享权限变更都会作用于用户的真实文件——运行前请确认确切目标。
• 从链接中提取 ID。 当用户粘贴 docs.qq.com/doc/<id>（或 /sheet/、/slide/、/mind/、/flowchart/、/form/、/smartsheet/）URL 时， 从路径中提取 ID，而不要向用户索要。
• 分页。 列表／搜索端点会在 data 中返回游标／next 标记；传回该标记以获取下一页。标记为空时停止。
• 速率／配额。 免费应用每月可调用 API 20,000 次（超级会员每天 20,000 次， Plus 每天 40,000 次）。AI 生成类功能还会消耗积分，且可能需要超级会员——400007／400008 表示账户等级／积分不足，而非请求有误。
• 完整 API 索引。 除上述示例外，Open API 还涵盖智能表格记录、表单收集、文件夹 CRUD、权限 以及导入／导出——请参阅接口索引。