语雀文档同步

解决什么问题

把本地 Markdown 文档同步到语雀时，常见痛点不是单次 API 调用，而是文档 ID/slug、目录挂载、标题来源、链接映射、重复推送和远端草稿状态难以判断。这个技能把单个语雀知识库的文档管理收敛到 yuque_cli.py：先完成连接配置，再按命令执行 list、get、create、update、delete、toc、sync、pull、status，并在结果中返回 doc ID、title、slug 等可核对信息。

工作方式

• 基础 CRUD：通过语雀 OpenAPI 操作一个知识库内的文档；create 默认会把文档追加到目录，get/update/delete 可用整数 ID 或更可读的 slug。
• 同步状态：sync 使用 .yuque-sync.json 记录本地正文 hash 与远端 latest_version_id，只推送实际变化的文档，未变化项跳过，避免每次全量 GET 和盲写。
• 本地布局：支持 flat、nested、frontmatter 三种 Markdown 目录约定；frontmatter 可声明 slug 和 title，推送前会移除 frontmatter。
• 正文转换：推送时重写文档间链接，并修正语雀渲染器对 **标签：** 值 的加粗闭合空格要求；拉取时可把 slug 链接还原为本地文件链接。
• 安全边界：token 只用于 setup 参数和 .env，不打印、不硬编码；脚本会检查 .gitignore，删除远端文档需要显式确认。

适用边界

它适合管理单个知识库中的 Markdown 文档和目录状态，不负责语雀团队、成员、仓库创建/删除，也不做跨知识库迁移。目录插入默认追加到根目录子节点，不能指定父节点或位置。sync 以已发布版本的 latest_version_id 做变更判断，可能覆盖未发布的远端草稿；遇到冲突、本地缺失文件、布局不明确时，会要求人工选择而不是自动决策。