腾讯文档Markdown

核心用法

tencent-docs-markdown 是一款面向腾讯文档生态的 Markdown 管理工具，提供完整的文档生命周期操作：新建并写入内容、创建空文档、下载为本地 .md 文件、读取在线内容、更新覆盖、删除（移入回收站）、重命名及获取文档元信息。

关键工作流：

• 认证：首次使用需微信/QQ扫码登录，Cookie 自动缓存于 .cookies.json，支持快捷登录检测
• URL 解析：自动将腾讯文档 URL 标识符（DSxxxxxxxx）解析为 API 所需的真实 padId，用户无感知
• 双模式支持：命令行 CLI 与编程接口并重，适合自动化脚本与 Agent 集成

典型场景：

• 本地 Markdown 批量同步至腾讯文档
• 云端文档自动备份到本地 Git 仓库
• Agent 驱动的文档协作（如"帮我新建文档并写入会议纪要的摘要"）

显著优点

1. 全功能覆盖：涵盖 CRUD 完整操作，支持文件路径与文本内容双模式输入
2. 智能登录：自动检测微信快捷登录，减少扫码次数；Cookie 失效自动重登
3. URL 透明化：内置 resolveRealPadId() 自动处理腾讯文档的标识符映射问题
4. MIT 开源：可自由二次开发，适合构建企业级文档工作流
5. Agent 友好：预定义触发短语与 Mermaid 流程图，降低 LLM 集成成本

潜在缺点与局限性

• 强依赖腾讯生态：仅支持腾讯文档 Markdown（doc_type=14），不兼容其他云文档平台
• Cookie 安全风险：凭据以明文 JSON 存储于本地，多用户环境需额外防护
• 无版本控制：更新操作为覆盖式写入，无自动历史版本保留
• 回收站非彻底删除："删除"仅移至回收站，需手动清空
• _rate limit 未披露_：高频 API 调用可能触发平台限流

适合人群

• 需将本地 Markdown 工作流与腾讯文档打通的技术写作者
• 构建办公自动化 Agent 的开发者
• 团队协作中需要批量文档管理的管理员
• 依赖微信/QQ 生态的企业用户

常规风险

| 风险类型 | 说明 | 缓解建议 |

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

| 会话劫持 | `.cookies.json` 泄露可导致账号被盗用 | 设置文件权限 600，勿提交至 Git |

| 误操作覆盖 | `update` 命令无确认直接覆盖 | 操作前手动备份或使用 Git 管理本地副本 |

| 平台依赖 | 腾讯 API 变更可能导致功能失效 | 关注上游更新，锁定版本号 |

| 隐私合规 | 文档内容经腾讯服务器处理 | 敏感内容建议本地加密后再上传 |

功能定位

tencent-docs-markdown 是一个基于 Node.js 的命令行工具，专为腾讯文档 Markdown 格式的全生命周期管理而设计。用户可通过自然语言指令驱动，实现文档的创建、写入、读取、更新、删除、重命名及下载等操作，打通了本地 Markdown 文件与云端腾讯文档的双向同步通道。

核心用法

该技能采用 CLI + 编程接口 双模式设计。首次使用需执行 login 命令，通过微信或 QQ 扫码完成 OAuth 认证，系统会将 Cookies 持久化存储至本地 .cookies.json 文件，后续操作自动复用该凭证。核心操作包括：

• write: 新建文档并写入内容，支持直接传入 Markdown 文本或本地文件路径
• create: 创建空白文档
• read/download: 读取云端内容或下载为本地 .md 文件
• update: 覆盖更新已有文档内容
• delete: 将文档移入回收站
• rename/info: 文档元数据管理

技术实现上，该工具通过 Puppeteer 模拟浏览器行为完成扫码登录流程，并封装腾讯文档私有 API（docs.qq.com/cgi-bin/online_docs/* 及 /api/markdown/*）实现文档操作。特别值得注意的是，系统内置了 padId 解析机制——由于腾讯文档 URL 中的标识符与 API 所需的真实 padId 不同，工具会自动访问文档页面，从嵌入的 basicClientVars 中提取真实 ID，对用户完全透明。

显著优点

1. 自动化闭环: 扫码登录一次后，Cookies 自动缓存，实现"零感知"持续使用
2. 双向同步: 既支持将本地 Markdown 推送到云端，也支持将云端文档拉取到本地
3. URL 智能解析: 自动处理腾讯文档 URL 标识符到真实 API ID 的映射，用户无需理解底层细节
4. 多维度操作: 覆盖文档全生命周期，包括批量重命名、信息查询等进阶功能
5. 安全可控: 网络请求严格限定于 docs.qq.com 官方域名，依赖均为知名开源库

潜在局限与风险

1. Puppeteer 沙箱禁用: 为兼容 Docker/无头环境，启动参数包含 --no-sandbox 和 --disable-setuid-sandbox，降低了浏览器进程隔离强度（安全报告 RISK-001）
2. Cookie 明文存储: 认证信息以明文 JSON 形式保存于本地，虽配置了 .gitignore，但缺乏文件权限强制约束（如 0o600），存在多用户环境下的信息泄露风险（RISK-002）
3. URL 解析健壮性: 当前采用正则表达式提取 URL 中的 padId，对非常规 URL 格式的容错能力有限（RISK-003）
4. 单点依赖: 完全依赖腾讯文档私有 API，若官方调整接口或增加风控策略，功能可能失效
5. 权限边界: 以用户身份执行所有操作，无法区分"只读"与"管理"权限的细粒度控制

适合人群

• 个人知识管理用户: 希望将本地 Markdown 笔记批量同步至腾讯文档进行分享或协作
• 开发/运维人员: 需要自动化生成技术文档并发布到企业腾讯文档空间
• 内容创作者: 追求"本地编辑 + 云端分发"工作流，减少手动复制粘贴
• 团队协作场景: 需要将标准化文档（如 API 文档、部署手册）快速部署到共享空间

常规风险提示

• 认证安全: 建议定期检查 .cookies.json 文件权限，避免在公共服务器或共享环境中存储
• 数据一致性: update 操作采用覆盖模式，无版本历史比对，重要文档更新前建议先 download 备份
• API 稳定性: 腾讯文档未公开 Markdown API 文档，存在接口变更导致功能异常的可能性
• 删除可恢复: delete 操作实际为"移入回收站"，非永久删除，敏感数据需手动前往腾讯文档回收站二次清理