腾讯文档管家
一句话：批量打理你的腾讯文档知识库——盘点体检、归档归类、重命名、权限治理、备份导出。
执行任务前先读配置
| 顺序 | 位置 | 用途 |
|---|---|---|
| 1 | ~/.tdoc/config.local.md |
真实配置（空间 ID、默认落点、命名规范、删除策略、权限策略） |
| 2 | 本目录 config.md |
空模板，用来看该填哪些字段 |
| 3 | 两处都没有 | 不猜，直接问用户 |
私人配置不存在时，按模板各节的「缺省行为」执行，并在回执里说明采用了哪个缺省值。
> 技能目录内不放任何真实数据；真实配置一律写在 ~/.tdoc/ 下。
它会自己选路，你不用管
本 skill 有两条凭证通道，自动选择，优先用不需要你操心的那条：
| 场景 | 走哪条 | 你要做什么 |
|---|---|---|
| 在 WorkBuddy 里，且已授权腾讯文档连接器 | 连接器模式 | 什么都不用做 |
| 在 Cursor / Claude Code / 其他客户端 | 直连模式 | 配一个 access_token（一分钟） |
不确定走的是哪条？跑一句就知道：
python3 "${CODEBUDDY_SKILL_DIR}/scripts/tdoc.py" mode
只在其他客户端时需要：拿一个 token
打开腾讯文档官方的智能体入口：https://docs.qq.com/scenario/open-claw.html
- QQ 或微信登录（无需注册开发者）
- 点「获取 token」，复制
- 放进
~/.tdoc/token.txt（只放一行），或设环境变量TDOC_ACCESS_TOKEN
随时可以点「重置 token」作废旧的。token 只属于你，别发给别人。
开始用
S="${CODEBUDDY_SKILL_DIR}/scripts"
python3 "$S/selfcheck.py" # 0. 自检（可选但推荐）
python3 "$S/tdoc.py" list # 1. 先看有哪些工具（共 224 个，别凭记忆）
python3 "$S/tdoc.py" schema <工具名> # 2. 调用任何工具前先查参数
python3 "$S/traverse_space.py" <space_id> tree.json # 3. 遍历**单个**空间（推荐；何时该用它见「排障」表）
python3 "$S/inventory.py" --fetch # 4. 盘点体检（只读）
python3 "$S/batch.py" --plan plan.json # 5. 批量操作，默认只试运行
traverse_space.py 输出扁平节点表（node_id / title / node_type / doc_type / has_child / path），
path 是完整路径，可直接拿来数「哪个目录塞了多少篇」「哪些文件在根层裸奔」。325 篇约 1.5 分钟。
环境要求：只用 Python 3 标准库，不需要 pip install 任何东西。
上面是 bash 写法，但脚本本身只依赖 python3。如果你机器上的 shell 缺基础命令
（有些 Windows Git Bash 没有 head/tail/ls/dirname），不影响脚本运行；
但别用 shell 管道去筛脚本输出——直接读它写出的 JSON 文件，或改用 Python 处理。
四条铁律
- 先查参数再调用。
tdoc.py schema <工具名>拿真实参数定义，严禁凭记忆拼参数。已踩过的坑：manage.recent_online_file的count上限是 20，不传会被下游拒绝。 - 批量操作一律先试运行。
batch.py不加--apply就是预览，绝不写远端。把预览给用户看，确认后再执行。 - 删除与权限收紧必须逐项确认。删除需额外
--allow-danger；改权限会影响其他协作者，改前先列清单确认。 - 拿不到的数据不要编。节点树和最近浏览列表都不返回修改时间，不支持"多久没更新"类分析；只有空间级
updated_at可用。
batch.py 的执行语义（做重构前必读）
- 先建目录、再搬东西，必须拆两个计划。
batch.py不会把 create 返回的node_id回填给后续 move；
第一批只跑 create，从输出里抄下新目录 id（✓行下面会直接打印→ 新建节点 id: Rxxx），再生成第二批 move。 - 结果有三种，不是两种：
ok/failed/unknown（无返回，成败未知）。
看到unknown不要去远端复核前直接重跑。 - 自动重试只对幂等操作生效：移动 / 改名 / 删除会重试 2 次；新建类绝不自动重试
（create_space_node若其实已成功只是没返回，重试就会建出重复目录）。 - 做完必须复查。用
traverse_space.py再遍历一次，把前后两份快照按node_id比：
文件数是否一致、有没有丢失/新增/被改名。这是唯一可信的"我没搞坏东西"的证据。
工具速查（已实测）
权限语义 policy：0=私密 · 1=部分成员可见 · 2=所有人可读 · 3=所有人可编辑。
> ⚠️ 这只是常用子集。真实可用工具共 224 个，跑 python3 tdoc.py list 看全量。
> 动「新增一层分类」这类重构前必须先跑一次 list——下面这几个重整型工具不在常规文档里但确实存在。
| 工具 | 关键参数 | 说明 |
|---|---|---|
query_space_list |
num 页码从 0 开始，query_by 0全部/1我创建/2我加入 |
返回 spaces[] + has_next；含 file_cnt、space_size、policy、updated_at |
query_space_node |
space_id 必填，num 页码从 0 开始每页 20，parent_id 空取根层 |
返回 children[]：node_id/title/node_type/has_child。无 has_next，取到不足 20 条为止 |
manage.recent_online_file |
num 页码从 1 开始，count 必须显式传 1~20 |
只返回 id/名称/链接，无时间字段，不含文件夹 |
manage.get_privilege |
file_id（也接受空间 ID） |
返回 policy |
manage.move_file_to_space |
file_id、space_id、target_parent_id（可选） |
空间内归档主力，也能移动文件夹节点本身 |
manage.delete_file |
file_id、remove_type current（默认）/all（递归删子节点，谨慎） |
危险操作 |
create_space_node |
title、node_type=wiki_folder、space_id、wiki_folder_node={"title":...} |
新建文件夹。加分类层的唯一手段 |
manage.rename_file_title |
file_id、title（≤36 字符） |
批量改名 |
delete_space_node |
node_id、space_id、remove_type |
删空间节点；current 时子节点上挂 |
manage.query_file_info |
file_id |
报 file type not support query 说明是上传的本地文件，API 读不到内容 |
CLI 姿势：args_json 是位置参数，写成 --json 会静默失败（exit 2、stdout 空）。
python3 tdoc.py call create_space_node '{"space_id":"Rxx","node_type":"wiki_folder","title":"新目录","wiki_folder_node":{"title":"新目录"}}'
先建目录再搬东西要分两批：batch.py 不会把 create 返回的 node_id 回填给后续 move。
第一批只跑 create 拿到 id，第二批再生成 move 计划。
完整参数与已知坑见 references/api-params.md；node_id 可直接当 file_id 用。
排障
| 现象 | 处理 |
|---|---|
| 两条路都没有 | 授权 WorkBuddy 连接器，或按「拿一个 token」一节取一把 |
| 个人版与企业版都已授权 | 用 --flavor personal\|saas 明确指定 |
code:400001 count exceeds maximum |
recent_online_file 的 count 超过 20 |
code:400016 |
用错品类的工具，先 manage.query_file_info 确认类型 |
HTTP 401 / invalid_token |
token 失效，回页面重新取一把 |
ERROR:http_failed |
网络或代理问题，加 --no-proxy 再试 |
inventory.py --fetch --deep 跑几分钟没动静 |
它遍历全部空间且 --out 只在结束时落盘。只想看一个空间就写定向遍历脚本（325 篇约 1.5 分钟） |
| 调用返回空、exit code 2 | args_json 写成了 --json，它是位置参数 |
| 执行器报「失败」但操作其实生效了 | 老版 batch.py 用 '"error"' in out 判失败，而成功响应里也带空的 "error":""（create_space_node 就是这样）。已在 v2 改为解析 JSON、只认非空 error。若用旧报告重跑，会建出重复目录 |
| 某条操作报「待确认 / 无返回」 | 网络抖动导致空响应（实测 11 条里偶发 1 条）。不要直接重跑——新建类会重复建。先去远端复核 |
file type not support query |
该节点是上传的本地文件，不是在线文档；API 读不到内容，别指望自动起名 |
命令报 dirname / head / ls command not found |
本机 shell 缺 coreutils（部分 Windows Git Bash 如此），与技能无关。脚本只用 python3，照样能跑；但别用 shell 管道筛它的输出 |
脚本报 ModuleNotFoundError |
不该发生：本技能只用 Python 标准库、零第三方依赖。出现说明跑的不是本技能里的脚本 |
