腾讯文档Markdown

核心用法

腾讯文档 Markdown 技能提供完整的腾讯文档 Markdown 管理能力，支持 Agent 通过自然语言指令触发文档操作。主要功能包括：

1. 文档创建与写入：支持新建空白文档或直接写入 Markdown 内容
2. 本地同步：将在线文档下载为本地 .md 文件，或将本地文件上传同步
3. 内容管理：读取、更新、删除（移至回收站）、重命名文档
4. 智能登录：首次扫码登录后自动缓存 Cookie，支持微信快捷登录检测

技术实现上，该技能通过 Playwright 模拟浏览器行为，解析文档页面 HTML 提取真实 padId，再调用腾讯文档内部 API 完成操作。关键机制是将 URL 中的表面标识符解析为 globalPadId（{domainId}${padId}）格式用于 API 认证。

显著优点

• 完整生命周期管理：覆盖创建、编辑、同步、归档全流程
• 无缝本地集成：支持直接传入文件路径或 Markdown 文本
• 智能会话保持：Cookie 自动复用减少重复登录
• 微信生态原生：深度适配腾讯文档的认证体系

潜在缺点与局限性

• 依赖浏览器自动化：需安装 Chromium，启动开销较大
• API 非官方公开：基于内部接口逆向，存在失效风险
• 单账号限制：Cookie 绑定单个微信/QQ 账号，不支持多账号切换
• 权限边界模糊：删除操作仅移至回收站，彻底删除需手动到腾讯文档网页操作

适合人群

• 需要批量管理腾讯文档的开发者或内容运营人员
• 希望将本地 Markdown 工作流与腾讯文档同步的个人用户
• 构建自动化文档发布管道的 Agent 开发者

常规风险

• Cookie 泄露风险：.cookies.json 包含完整会话凭证，文件权限需严格限制
• 账号关联风险：扫码登录绑定个人微信/QQ，企业场景下需注意合规
• API 变更风险：非官方 API 可能随腾讯文档更新而失效
• 内容安全风险：更新操作直接覆盖原文，无版本回滚机制

核心用法

腾讯文档 Markdown 技能（tencent-docs-markdown）是一个功能完整的文档自动化工具，主要面向需要与腾讯文档平台进行 Markdown 交互的开发者和自动化场景。该技能支持以下核心操作：

• 文档创建与写入：支持新建空文档或直接写入 Markdown 内容，自动返回可分享的文档链接
• 文档下载与读取：可将腾讯文档下载为本地 .md 文件，或直接读取内容到内存
• 文档更新与重命名：支持覆盖更新已有文档内容，或修改文档标题
• 文档删除：将文档移至回收站（可恢复）
• 文档信息查询：获取文档元数据详情

技术实现上，该技能采用 Playwright 浏览器自动化 完成微信/QQ 扫码登录，会话 Cookie 缓存在本地 .cookies.json 文件中自动复用。所有 API 调用均通过官方腾讯文档域名（docs.qq.com）进行，支持自动解析 URL 标识符为真实 padId。

显著优点

1. 完整的 CRUD 能力：覆盖文档全生命周期管理，满足自动化文档工作流需求
2. 安全的认证机制：扫码登录 + Cookie 缓存，避免密码硬编码；内置域名白名单验证和 Cookie 净化函数
3. 双重登录方式：支持微信快捷登录（自动检测）和传统二维码扫描，提升用户体验
4. 清晰的架构设计：模块化代码结构（auth/api/main 分离），CLI 与编程接口并重
5. 开源透明：MIT 许可证，代码可审计，社区驱动维护

潜在缺点与局限性

1. 浏览器依赖：必须安装 Playwright 和 Chromium，环境体积较大（约 100MB+）
2. Cookie 安全风险：.cookies.json 包含敏感会话信息，虽加入 .gitignore 但仍需用户自行保护文件权限
3. 无头模式限制：扫码登录需可视化浏览器窗口，难以在纯服务器环境运行
4. 腾讯生态绑定：仅支持腾讯文档，无法迁移至其他 Markdown 平台
5. Cookie 过期处理：会话超时后需重新扫码，暂无自动续期机制

适合人群

• 需要将本地 Markdown 工作流与腾讯文档同步的个人开发者
• 构建文档自动化 pipeline 的DevOps/工具链工程师
• 团队协作中需要批量管理腾讯文档的技术团队管理员
• 开发腾讯文档相关集成插件的第三方开发者

常规风险

| 风险类别 | 说明 | 缓解措施 |

|---------|------|---------|

| Cookie 泄露 | `.cookies.json` 包含会话凭证 | 设置 600 文件权限，不提交到版本控制 |

| 凭证重放攻击 | Cookie 被窃取后可冒用身份 | 定期重新登录刷新会话，监控异常登录 |

| 依赖供应链 | 4 个外部依赖（requests/playwright/click/Pillow） | 锁定版本号，定期审计依赖 |

| 浏览器自动化 | Playwright 操作需系统级权限 | 在受控环境运行，避免多用户共享会话 |

| 内容注入 | Markdown 内容未本地过滤 | 依赖腾讯文档服务端 XSS 防护 |

Python 版本要求：>= 3.10