195 lines
7.7 KiB
Markdown
195 lines
7.7 KiB
Markdown
---
|
||
name: tencent-docs-mcp
|
||
description: >
|
||
通过腾讯文档 MCP 批量操作文档空间：迁移 Markdown 知识库到空间、建目录树、
|
||
批量建文档、验收内容完整性。当用户要求「把内容传到腾讯文档」「迁移知识库到腾讯文档」
|
||
「在腾讯文档建目录/文档」「同步文档到腾讯文档空间」时使用。
|
||
也适用于排查 tdoc_call 的 502 / no_token 报错。
|
||
agent_created: true
|
||
---
|
||
|
||
# 腾讯文档 MCP 批量操作
|
||
|
||
批量把 Markdown / 结构化内容写入腾讯文档空间，并做完整性验收。
|
||
|
||
## 一、🔴 最先要会排查的两个报错
|
||
|
||
### `ERROR:http_failed - Tunnel connection failed: 502 Bad Gateway`
|
||
|
||
**这个报错具有极强误导性** —— 看起来是网络/代理故障，实际 99% 是
|
||
**宿主下发的 API 域名不存在**。
|
||
|
||
排查三步：
|
||
```bash
|
||
# 1. 开调试，看 provider 下发的 api_base 是什么
|
||
TDOC_DEBUG=1 python tencentdocs.py tdoc_call tencent-docs <tool> '{}'
|
||
# → [TencentDocsSkillCredential] token provider result personal=available api_base=https://xxx
|
||
|
||
# 2. 验证该域名是否存在
|
||
nslookup <上面那个域名>
|
||
# → NXDOMAIN / Non-existent domain ⇒ 就是它的问题
|
||
|
||
# 3. 显式覆盖成正确域名
|
||
TDOC_API_BASE_URL=https://docs.qq.com python tencentdocs.py ...
|
||
```
|
||
|
||
个人版正确域名 = **`https://docs.qq.com`**。
|
||
⚠️ **不要**因为看到 502 就去 unset 代理 —— 那会变成 `getaddrinfo failed`
|
||
（本机往往无法直连外网，代理是必需的）。**问题在域名，不在代理。**
|
||
|
||
### `ERROR:no_token - 未检测到腾讯文档登录票据`
|
||
|
||
连接器没授权。让用户在连接器管理里授权「腾讯文档」即可。
|
||
`provider personal=not_connected enterprise=connector_disabled` 就是没连。
|
||
|
||
---
|
||
|
||
## 二、🔴 三个与文档描述不符的 API 行为
|
||
|
||
| 接口 | 文档说 | 实测 |
|
||
|---|---|---|
|
||
| `query_space_node` | 传 `parent_node_id` 查子节点 | **该参数完全被忽略**，总返回整个空间的扁平节点列表 |
|
||
| `delete_space_node` | `remove_type=all` 递归删除子节点 | **只删当前节点，子节点被提升到根目录** |
|
||
| `doc.create_with_markdown` | — | **不接收 space_id / parent_id**，只能建在个人根目录 |
|
||
|
||
**推论**：
|
||
- 无法用「查子节点」判断文件夹是否为空 → 删除前的空检查要靠**全量遍历**判断
|
||
- 删嵌套树不能一把梭 → 得逐个删，或删完再处理被提升的节点
|
||
- 建文档进空间必须两步：**先建、再移**
|
||
|
||
---
|
||
|
||
## 三、建文档进空间的正确路径
|
||
|
||
```python
|
||
# 1) 建文档 + 写内容（原子操作）
|
||
r = call("tencent-docs", "doc.create_with_markdown", {
|
||
"title": title,
|
||
"base64_markdown": base64.b64encode(md.encode()).decode(),
|
||
})
|
||
file_id = r["data"]["file_id"]
|
||
|
||
# 2) 移入目标文件夹
|
||
call("tencent-docs", "manage.move_file_to_space", {
|
||
"file_id": file_id, "space_id": SPACE, "target_parent_id": folder_id,
|
||
})
|
||
```
|
||
|
||
**为什么不用 `insert_markdown`**：那条路要先 `create_space_node(node_type=wiki_tdoc)`
|
||
建一个**空文档节点**，再写内容。中途失败就留下**空壳文档**，
|
||
而且两步之间用户点进去会看到空白页。`create_with_markdown` 是官方为一步建好设计的。
|
||
|
||
建文件夹：
|
||
```python
|
||
call("tencent-docs", "create_space_node", {
|
||
"space_id": SPACE, "title": name, "node_type": "wiki_folder",
|
||
"wiki_folder_node": {"title": name},
|
||
})
|
||
```
|
||
`node_type` 还支持 `wiki_tdoc`（在线文档）、`link`。
|
||
|
||
**耗时参考**：33 篇文档 ≈ **1 分 28 秒**。不必并发，串行足够。
|
||
|
||
---
|
||
|
||
## 四、🔴 验收判据：用「句子覆盖率」，别用片段指纹
|
||
|
||
这一步反复翻车过两次，方法论比代码重要。
|
||
|
||
### 为什么片段指纹不行
|
||
|
||
**坑 1：`get_content` 返回纯文本，表格结构信息全丢**
|
||
表格被拆成「单元格文本逐行拼接」，**没有 `|` 分隔符**。
|
||
拿源 md 的表格行（`预算明细表 | | | | |`）去比对必然失败。
|
||
|
||
**坑 2：三类格式差异会造成假的「内容缺失」**
|
||
| 差异 | 源 Markdown | 腾讯文档渲染后 |
|
||
|---|---|---|
|
||
| 列表编号 | `1. 必须带日期：…` | `必须带日期：…`（自动编号，**不返回前缀**）|
|
||
| 引号 | `"9月19日"`（直角） | `”9月19日”`（弯引号）|
|
||
| 链接 | `[文字](路径)` | 只剩`文字`，路径不显示 |
|
||
|
||
### 正确判据
|
||
|
||
```python
|
||
def norm(s):
|
||
"""激进归一化：只留实义字符"""
|
||
s = re.sub(r"[\s\u3000\u00a0]+", "", s)
|
||
s = re.sub(r"[|*`>#_~\[\]()（）【】「」『』{}]", "", s)
|
||
s = re.sub(r"[\"'‘’“”‚‛„‟‹›«»]", "", s) # 各类引号（含弯引号！）
|
||
s = re.sub(r"[，,。.：:；;！!？?、－—–\-·…]", "", s)
|
||
s = re.sub(r"^\d+", "", s) # 列表编号残留
|
||
return s
|
||
|
||
def sentences(md):
|
||
body = re.sub(r"^---\n.*?\n---\n+", "", md, flags=re.S) # 去 frontmatter
|
||
body = re.sub(r"```[\s\S]*?```", "", body) # 去代码块
|
||
body = re.sub(r"^#{1,6}\s+", "", body, flags=re.M) # 标题标记
|
||
body = re.sub(r"^\s*\d+\.\s+", "", body, flags=re.M) # 有序列表编号
|
||
body = re.sub(r"^\s*[-*+]\s+", "", body, flags=re.M) # 无序列表符号
|
||
body = re.sub(r"\[([^\]]*)\]\([^)]*\)", r"\1", body) # 链接→只留文字
|
||
body = re.sub(r"\*\*|__|`|~~", "", body)
|
||
body = re.sub(r"^\s*\|", "", body, flags=re.M)
|
||
body = re.sub(r"\|\s*$", "", body, flags=re.M)
|
||
body = re.sub(r"\|\s*\|", " ", body)
|
||
parts = re.split(r"[。！？；\n]", body)
|
||
return [p.strip() for p in parts if len(norm(p)) >= 8] # 短句无判别力，丢掉
|
||
|
||
# 覆盖率 ≥ 90% 判通过
|
||
miss = [s for s in sentences(src) if norm(s) not in norm(got)]
|
||
cov = 1 - len(miss) / len(sentences(src))
|
||
```
|
||
|
||
实测结果：33/33 通过，多数 100%，最低 91%
|
||
（91% 那几篇差异来自表格跨行边界，**不是内容丢失**）。
|
||
|
||
---
|
||
|
||
## 五、工具清单（224 个，按需取用）
|
||
|
||
```bash
|
||
python tencentdocs.py tdoc_list tencent-docs # 列全部工具
|
||
python tencentdocs.py tdoc_schema tencent-docs <tool> # 查参数（★ 调用前必做）
|
||
python tencentdocs.py tdoc_init # 检查 token
|
||
```
|
||
|
||
`--no-proxy` 可绕过代理（但通常不需要，问题在域名）；`--timeout` 调超时。
|
||
|
||
常用分组：
|
||
- `manage.*` — 创建/移动/搜索/权限/导入导出（`create_file` `move_file_to_space` `folder_list` `search_file`）
|
||
- `doc.*` — Word 文档读写（`create_with_markdown` ★ `insert_markdown` `insert_table` `find_and_replace`）
|
||
- `create_space_node` / `query_space_node` / `query_space_list` / `delete_space_node` — 空间树
|
||
- `sheet.*` / `smartsheet.*` / `slide_*` / `flowchart.*` — 表格/智能表/幻灯片/流程图
|
||
- `get_content` — 读文档纯文本（验收必备）
|
||
|
||
---
|
||
|
||
## 六、幂等与可续跑
|
||
|
||
批量任务一定要能断点续跑 —— 33 次调用中途断掉不能从头来。
|
||
|
||
```python
|
||
STATE = Path("_migrate_state.json") # {"folders": {名: id}, "docs": {key: {file_id, ...}}}
|
||
if stem in st["docs"]:
|
||
print("跳过（已完成）")
|
||
continue
|
||
# ... 完成后立刻写回
|
||
st["docs"][stem] = {"file_id": fid, "title": title, "section": sec}
|
||
save_state(st) # 每篇写完就落盘，不要等全部结束
|
||
```
|
||
|
||
文件夹同样做「已存在则复用」：
|
||
先查根目录同名节点，有就复用，没有才建 —— 避免重跑产生一堆重复文件夹。
|
||
⚠️ 因为 `parent_node_id` 不生效，只能靠**全量列表 + 标题匹配**来找。
|
||
|
||
---
|
||
|
||
## 七、危险操作
|
||
|
||
`delete_space_node` 不可逆。执行前必须：
|
||
1. 用**全量遍历**确认该节点子树内 **0 篇文档**（因为查不了子节点）
|
||
2. 把待删结构 dump 到文件留档
|
||
3. 向用户确认
|
||
|
||
⚠️ `remove_type=all` 不是递归删除（见第二节），别指望一把删干净。
|