腾讯文档 Markdown 技能
名称： tencent-docs-markdown
许可证： MIT
简介： 腾讯文档 Markdown 技能，支持新建 Markdown 并写入内容、下载、删除、读取、更新、重命名等操作。
Agent 如何使用此技能
触发短语
当用户表达以下意图时，Agent 应激活此技能：
Agent 工作流程
flowchart TD
A[用户请求] --> B{Cookies 有效？}
B -->|是| C[执行操作]
B -->|否| D[通过扫码登录]
D --> E[保存 Cookies]
E --> C
C --> F[返回结果 + 文档链接]
快速开始
# 1. 安装依赖
pip install -r requirements.txt
playwright install chromium
# 2. 登录（使用微信/QQ 扫描二维码）
python -m src.main login
# 3. 新建文档并写入内容
python -m src.main write "我的文档" "# Hello World"
功能操作
1. 新建并写入文档
新建一个腾讯文档 Markdown，写入内容后返回文档链接。
命令行：
python -m src.main write "我的文档" "# Hello World\n这是我的文档内容。"
编程接口：
from src.main import handle_create_and_write
result = handle_create_and_write('我的文档', '# Hello World\n这是内容。')
# result: {'docUrl': ..., 'padId': ..., 'globalPadId': ..., 'title': ...}
# → 将 result['docUrl'] 分享给用户
2. 新建空文档
创建一个新的空 Markdown 文档。
命令行：
python -m src.main create "我的新文档"
编程接口：
from src.main import handle_create
result = handle_create('我的文档')
# result: {'docUrl': ..., 'padId': ..., 'globalPadId': ..., 'title': ...}
3. 下载文档
将腾讯文档 Markdown 下载为本地 .md 文件。
注意： 系统会自动从文档页面解析真实的 padId（URL 中的标识符与 API 所需的真实 padId 不同）。
命令行：
python -m src.main download https://docs.qq.com/markdown/DQxxxxxxxx
python -m src.main download https://docs.qq.com/markdown/DQxxxxxxxx -o ./output.md
编程接口：
from src.main import handle_download
result = handle_download('https://docs.qq.com/markdown/DQxxxxxxxx', './output.md')
# result: {'path': ..., 'content': ...}
4. 读取文档
读取并返回文档内容。
命令行：
python -m src.main read https://docs.qq.com/markdown/DQxxxxxxxx
编程接口：
from src.main import handle_read
content = handle_read('https://docs.qq.com/markdown/DQxxxxxxxx')
5. 更新文档
覆盖已有文档的内容（支持直接传入文本或 .md 文件路径）。
命令行：
python -m src.main update https://docs.qq.com/markdown/DQxxxxxxxx "# 新内容"
python -m src.main update https://docs.qq.com/markdown/DQxxxxxxxx ./updated.md
编程接口：
from src.main import handle_update
handle_update('https://docs.qq.com/markdown/DQxxxxxxxx', '# 更新后的内容')
6. 删除文档
将文档移入回收站。
命令行：
python -m src.main delete https://docs.qq.com/markdown/DQxxxxxxxx
编程接口：
from src.main import handle_delete
result = handle_delete('https://docs.qq.com/markdown/DQxxxxxxxx')
# result: {'padId': ..., 'deleted': True}
7. 重命名文档
命令行：
python -m src.main rename https://docs.qq.com/markdown/DQxxxxxxxx "新标题"
编程接口：
from src.main import handle_rename
handle_rename('https://docs.qq.com/markdown/DQxxxxxxxx', '新标题')
8. 获取文档信息
命令行：
python -m src.main info https://docs.qq.com/markdown/DQxxxxxxxx
编程接口：
from src.main import handle_info
info = handle_info('https://docs.qq.com/markdown/DQxxxxxxxx')
9. 登录
命令行：
python -m src.main login # 使用缓存的 Cookies（如有效）
python -m src.main login --force # 强制重新登录
认证机制
首次使用需扫码登录，之后 Cookie 会缓存在 .cookies.json 中自动复用。
支持两种登录方式：
- 扫码登录 — 使用微信/QQ 扫描二维码
- 微信快捷登录 — 如果之前在当前浏览器已有微信登录记录，系统会自动检测并点击"微信快捷登录"按钮，页面显示"登录中..."后自动完成登录
flowchart TD
A[开始] --> B{.cookies.json 存在？}
B -->|是| C{Cookies 有效？}
B -->|否| D[启动浏览器]
C -->|是| E[就绪]
C -->|否| D
D --> F{微信快捷登录可用？}
F -->|是| G[点击'微信快捷登录'按钮]
G --> H[页面显示'登录中...']
H --> I[每10秒轮询检测页面变化]
F -->|否| J[展示二维码供扫描]
J --> I
I --> K{检测到登录成功？}
K -->|是| L[获取并验证 Cookies]
K -->|否 / 超时| I
L --> M[保存 Cookies 到 .cookies.json]
M --> E
API 参考
| 接口 | 方法 | 路径 | 关键参数 |
|---|
| 创建文档 | GET | /cgi-bin/online_docs/createdoc_new | doc_type=14, create_type=1, folder_id=/, title, xsrf |
| 删除文档 | POST | /cgi-bin/online_docs/doc_delete | pad_id, domain_id, xsrf |
| 读取内容 | POST | /api/markdown/read/data | file_id（globalPadId） |
| 写入内容 | POST | /api/markdown/write/data | file_id, mark_down |
| 文档信息 | POST | /cgi-bin/online_docs/doc_info | file_id |
| 重命名 | POST | /cgi-bin/online_docs/doc_changetitle | pad_id, title, xsrf |
| 解析真实 padId | GET | 文档页面 HTML | 从 basicClientVars 中提取 padId |
项目结构
tencent-docs-markdown/
├── requirements.txt # Python 依赖
├── SKILL.md # 技能定义文件（本文件）
├── publish.sh # 版本发布脚本
├── .cookies.json # 保存的登录 Cookies（自动生成，已加入 .gitignore）
└── src/
├── __init__.py # Python 包初始化
├── main.py # 主入口 & CLI 命令
├── auth.py # 扫码登录 & Cookie 管理
├── api.py # 腾讯文档 Markdown API 客户端
└── login_with_polling.py # 轮询登录脚本
核心概念
URL 标识符与真实 padId
腾讯文档 Markdown 的 URL 格式为 https://docs.qq.com/markdown/DSxxxxxxxx，其中 DSxxxxxxxx 是 URL 标识符，并非 API 所需的真实 padId。
系统通过 resolve_real_pad_id() 函数访问文档页面，从嵌入的 basicClientVars JSON 中提取真实的 padId，然后拼接为 globalPadId（格式：{domainId}${padId}）用于 API 调用。
此机制对 下载（download）、读取（read）、更新（update） 操作自动生效，用户无需关注。
错误处理
| 错误 | 原因 | 解决方案 |
|---|
| Cookie 过期 | 会话超时 | 自动通过扫码重新登录 |
retcode !== 0 | API 返回错误 | 显示详细错误信息 |
| 无效 URL | 腾讯文档 URL 格式不正确 | 确保格式为：https://docs.qq.com/markdown/xxxxx |
| 资源不存在 | URL 标识符无法解析为真实 padId | 检查文档是否存在或是否有访问权限 |
备注
- Markdown 文档类型编号为
14（doc_type=14）
- 默认
domain_id 为 300000000
- XSRF Token 从
TOK Cookie 中提取
- Cookies 存储在
.cookies.json 中（已加入 .gitignore）
- 安全提示：
.cookies.json 包含敏感的会话 Cookie，请勿提交到版本控制或分享给他人，建议限制其文件权限（如 chmod 600 .cookies.json）
- 删除操作会将文档移至回收站（可恢复）
- 下载/读取/更新操作会自动解析 URL 中的标识符为真实 padId
- 建议在受控或受信环境中运行此工具，因为 Playwright 会下载 Chromium 并使用浏览器自动化权限
- Python 版本要求： Python >= 3.10
所需配置
| 配置项 | 路径 | 说明 |
|---|
| Cookie 存储 | .cookies.json（项目根目录，自动生成） | 存储腾讯文档会话 Cookie，首次登录后自动创建。此文件包含敏感信息，请勿泄露。 |
