腾讯文档 Markdown 技能

名称： tencent-docs-markdown 许可证： MIT 简介： 腾讯文档 Markdown 技能，支持新建 Markdown 并写入内容、下载、删除、读取、更新、重命名等操作。

---

Agent 如何使用此技能

触发短语

当用户表达以下意图时，Agent 应激活此技能：

意图	示例短语
新建并写入	"新建一个Markdown到腾讯文档并写入内容[xxx]" / "帮我新建腾讯文档md，写入以下内容" / "上传xxx.md到腾讯文档" / "上传xxx.md文档" / "同步xxx.md文档" / "提交xxx.md文档" / "把本地文件同步到腾讯文档"
新建空文档	"帮我创建名为xxx.md" / "新建一个Markdown文档"
下载	"把https://docs.qq.com/markdown/[xxx]文档保存到本地"
读取	"读取https://docs.qq.com/markdown/[xxx]文档内容"
更新	"更新[xxx]到https://docs.qq.com/markdown/[xxx]"
删除	"删除https://docs.qq.com/markdown/[xxx]"
重命名	"重命名https://docs.qq.com/markdown/[xxx]文档为xxx"
查看信息	"获取https://docs.qq.com/markdown/[xxx]文档的详情"
登录	"登录腾讯文档" / "重新登录" / "Cookie过期了"

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 文件路径）。

⚠️ 安全提示： 这是破坏性操作。交互模式下会显示目标文档标题与 URL 并要求确认 (y/N)。程序化调用须显式传入 confirm=True，否则操作会被拒绝。CLI 也可加 -y/--yes 跳过提示。

命令行：

python -m src.main update https://docs.qq.com/markdown/DQxxxxxxxx "# 新内容"
python -m src.main update https://docs.qq.com/markdown/DQxxxxxxxx ./updated.md
python -m src.main update https://docs.qq.com/markdown/DQxxxxxxxx ./updated.md -y   # 跳过确认

编程接口：

from src.main import handle_update
handle_update('https://docs.qq.com/markdown/DQxxxxxxxx', '# 更新后的内容', confirm=True)

6. 删除文档

将文档移入回收站。

⚠️ 安全提示： 交互模式下会展示目标文档标题与 URL 并要求确认 (y/N)。程序化调用须显式传入 confirm=True，否则操作会被拒绝。CLI 也可加 -y/--yes 跳过提示。

命令行：

python -m src.main delete https://docs.qq.com/markdown/DQxxxxxxxx
python -m src.main delete https://docs.qq.com/markdown/DQxxxxxxxx -y        # 跳过确认

编程接口：

from src.main import handle_delete
result = handle_delete('https://docs.qq.com/markdown/DQxxxxxxxx', confirm=True)
# result: {'padId': ..., 'title': ..., 'deleted': True}

7. 重命名文档

⚠️ 安全提示： 交互模式下会展示原标题、新标题与 URL 并要求确认 (y/N)。程序化调用须显式传入 confirm=True。

命令行：

python -m src.main rename https://docs.qq.com/markdown/DQxxxxxxxx "新标题"
python -m src.main rename https://docs.qq.com/markdown/DQxxxxxxxx "新标题" -y  # 跳过确认

编程接口：

from src.main import handle_rename
handle_rename('https://docs.qq.com/markdown/DQxxxxxxxx', '新标题', confirm=True)

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  # 强制重新登录

10. 登出 / 清除 Cookies

删除本地 .cookies.json 凭证文件，在不再需要该会话时使用。

命令行：

python -m src.main logout

编程接口：

from src.auth import clear_cookies
clear_cookies()

---

认证机制

首次使用需扫码登录，之后 Cookie 会缓存在 .cookies.json 中自动复用。

🔐 凭证管理： .cookies.json 被明确声明为 账户级凭证。保存时会自动应用 POSIX 0600 权限（仅当前用户可读写），并在终端提示用户其敏感性。切勿将此文件提交到版本控制或共享给他人；不再使用时请运行 python -m src.main logout 或手动删除。推荐使用专用的自动化账号，而非个人主账号。

支持两种登录方式：

1. 扫码登录 — 使用微信/QQ 扫描二维码
2. 微信快捷登录 — 如果之前在当前浏览器已有微信登录记录，系统会自动检测并点击"微信快捷登录"按钮，页面显示"登录中..."后自动完成登录

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），保存时自动设置 0600 权限
• 安全提示： .cookies.json 包含敏感的会话 Cookie，其作用等同于账户凭证。请勿提交到版本控制或分享给他人；文件自动设置 0600 权限，如需手动重置：chmod 600 .cookies.json。不再使用时请运行 python -m src.main logout 清除。
• 破坏性操作保护： update / delete / rename 均为不可撤销或影响用户文档的操作；它们在执行前会解析并展示目标文档的标题与 URL，交互模式下要求 y/N 确认；程序化调用必须显式传入 confirm=True，否则操作会被拒绝。
• 隐私提示： download / read 会将文档内容暴露给当前 agent 会话、终端输出或本地文件；请避免对高敏感文档使用这些操作。
• 依赖版本锁定： requirements.txt 中所有运行时依赖都被锁定到确定版本以减少供应链风险；请在可信任的环境中安装并审查任何依赖更新。
• 删除操作会将文档移至回收站（可恢复）
• 下载/读取/更新操作会自动解析 URL 中的标识符为真实 padId
• 建议在受控或受信环境中运行此工具，因为 Playwright 会下载 Chromium 并使用浏览器自动化权限
• Python 版本要求： Python >= 3.10

---

所需配置

配置项	路径	说明
Cookie 存储（凭证）	.cookies.json（项目根目录，自动生成）	存储腾讯文档会话 Cookie 的账户级凭证文件。首次登录后自动创建，保存时自动应用 0600 权限。此文件包含敏感信息，请勿泄露；不再使用时请运行 python -m src.main logout 或手动删除。