腾讯文档Markdown

核心用法

腾讯文档 Markdown 技能是一套完整的自动化工具，用于通过程序化方式管理腾讯文档平台上的 Markdown 文档。主要功能包括：

1. 文档创建与初始化：支持新建空白文档或带内容的文档，自动处理 doc_type=14 的 Markdown 类型标识
2. 内容同步：支持双向同步——既可将本地 .md 文件上传至云端，也可将云端文档下载为本地文件
3. 实时读写：通过 read/update API 实现文档内容的读取与覆盖更新
4. 文档管理：提供重命名、删除（移至回收站）、获取元信息等管理操作

技术实现亮点：

• URL 标识符自动解析：系统通过访问文档页面从 basicClientVars 中提取真实的 padId，解决 URL 标识符与 API 所需 globalPadId 不匹配的问题
• 双模式登录：优先尝试微信快捷登录（无感体验），失败时降级为二维码扫码
• Cookie 持久化：登录状态缓存于 .cookies.json，自动复用避免重复认证

显著优点

| 优势 | 说明 |

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

| 完整 CRUD | 覆盖文档全生命周期，非仅单一功能 |

| 无缝集成 | 同时提供 CLI 与 Python API，易于嵌入工作流 |

| 智能认证 | 支持快捷登录+扫码双通道，Cookie 自动管理 |

| 安全设计 | 破坏性操作强制确认、文件权限 `0600`、明确凭证风险提示 |

| 依赖锁定 | `requirements.txt` 版本固定，降低供应链风险 |

潜在缺点与局限性

1. 平台绑定：仅支持腾讯文档 Markdown（doc_type=14），不支持其他腾讯文档类型（表格、幻灯片等）或其他云文档平台
2. 认证门槛：必须使用微信或 QQ 账号，不支持企业微信/邮箱等独立认证体系；首次使用需人工扫码
3. 浏览器依赖：基于 Playwright + Chromium 实现，需下载约 100MB+ 浏览器二进制文件，对资源受限环境不友好
4. 隐私暴露风险：read/download 操作会将文档内容完全暴露给 agent 会话，不适合高敏感场景
5. 破坏性操作不可逆：update 为覆盖写入（非追加/合并），delete 虽移至回收站但自动化场景下难以恢复
6. Python 版本限制：仅支持 >= 3.10，老旧系统兼容性受限

适合人群

• 开发者/技术写作者：需要将本地 Markdown 写作流与腾讯文档协作流桥接的用户
• 自动化运维人员：构建文档同步流水线（如 CI/CD 生成文档自动上传）
• 内容运营团队：批量管理文档、自动化内容分发场景
• 个人知识管理用户：偏好本地编辑器（Obsidian/Vim/VS Code）但需腾讯文档分享能力的用户

常规风险

| 风险类别 | 具体风险 | 缓解措施 |

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

| **凭证泄露** | `.cookies.json` 包含会话 Cookie，等同账户凭证 | 文件自动 `0600` 权限、明确提示勿提交 Git、提供 `logout` 清除命令 |

| **误操作数据丢失** | `update` 覆盖写入、`delete` 删除文档 | 强制交互确认（`y/N`）或显式 `confirm=True` 参数、操作前展示文档标题与 URL |

| **隐私泄露** | `read`/`download` 暴露文档内容至 agent/终端 | 文档中明确警示避免用于高敏感文档 |

| **供应链攻击** | 依赖包被篡改 | 版本锁定、建议审查依赖更新 |

| **会话劫持** | Cookie 被盗用可导致账户接管 | 推荐使用专用自动化账号（非个人主账号）、定期重新登录轮换 Cookie |

核心用法

腾讯文档 Markdown 技能是一款面向开发者和自动化工作流的文档管理工具，提供对腾讯文档 Markdown 类型的完整操作能力。核心功能包括：

文档生命周期管理：支持新建空文档或带内容写入、读取文档内容、更新覆盖、重命名、删除（移入回收站）以及下载为本地 .md 文件。所有操作均通过腾讯文档官方 API 完成。

认证与持久化：采用微信/QQ 扫码登录，会话 Cookie 自动缓存至 .cookies.json 文件，后续操作无需重复认证。支持 Cookie 有效期检测和自动重新登录。

编程与 CLI 双模式：既可通过 python -m src.main 命令行使用，也提供完整的 Python API 接口（handle_create, handle_read, handle_update 等），便于集成到自动化脚本或 Agent 工作流。

URL 智能解析：腾讯文档 URL 中的标识符与 API 所需的真实 padId 不同，工具自动访问文档页面解析 basicClientVars 获取真实 ID，对用户透明。

显著优点

安全设计完善：Cookie 文件自动设置 POSIX 0600 权限（仅所有者可读写）；破坏性操作（update/delete/rename）强制双重确认机制，交互模式要求 y/N 确认，程序化调用需显式 confirm=True；依赖版本全部锁定，无已知 CVE。

代码质量优秀：结构清晰，2700 行代码分布 11 个文件，Python 占比 70.9%；具备完善的输入验证、错误处理和防御性编程；安全检测六维评分 85/100，获 A 级认证。

隐私保护到位：明确标注数据流向，Cookie 作为账户级凭证管理，提供 logout 命令清除敏感文件，文档中包含多项隐私风险提示。

生态兼容性强：支持微信快捷登录自动检测，Playwright 浏览器自动化限于腾讯文档域名，无越权行为；CLI 设计符合 Unix 哲学，支持 -y/--yes 批量确认。

潜在缺点与局限性

平台依赖：必须使用 Playwright + Chromium 进行浏览器自动化，首次安装体积较大（约 100MB+），且需在受控/受信环境运行。

腾讯生态绑定：仅支持腾讯文档 Markdown 类型（doc_type=14），无法操作其他文档类型；功能受腾讯 API 限制，如速率限制、功能变更等。

会话管理风险：Cookie 文件虽设 0600 权限，但仍为本地明文存储，在共享环境或 root 权限场景存在泄露风险；建议配置专用自动化账号而非个人主账号。

无访问日志：当前仅终端输出结果，缺乏结构化审计日志，不利于企业级合规追踪。

适合人群

• 自动化工作流开发者：需将文档操作集成到 CI/CD、数据处理管道的工程师
• Agent/AI 应用构建者：为 LLM Agent 提供腾讯文档读写能力的开发者
• 团队协作工具维护者：需批量管理文档、同步本地 markdown 文件与云端的运维人员
• 个人效率用户：习惯本地 Markdown 编辑但需云端备份分享的写作者

常规风险

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

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

| 凭证泄露 | `.cookies.json` 包含会话 Cookie，等同于账户凭证 | 设置 `0600` 权限、不入版本库、使用专用账号、及时 `logout` |

| 误操作数据丢失 | update/delete/rename 为破坏性操作 | 强制确认机制、操作前展示文档详情、回收站可恢复 |

| 供应链攻击 | 依赖包被篡改 | 版本锁定、使用可信 PyPI 源、定期审计 |

| 隐私泄露 | read/download 暴露文档内容 | 避免对高敏感文档使用、在可信环境运行 |

| 账户封禁 | 高频 API 调用可能触发风控 | 建议自实现速率限制、避免异常操作模式 |