yuque-cookie-plugin

一个面向 AI Agent 的本地语雀 Web Session 自动化工具。

本项目的核心目标是让 AI 通过和浏览器一致的网页 Session 路径操作语雀文档，而不是依赖语雀 Personal Token、OpenAPI Token、Skill 或 MCP。工具使用 _yuque_session 和 yuque_ctoken 访问语雀网页端接口，用于降低 token 限流和 MCP 部署带来的限制。

这不是一个 OpenAPI wrapper，而是一个本地 CLI 操作面：AI 可以用它读取、整理、下载、快照、对比、格式化并安全写入语雀文档，尽量接近语雀编辑器原生 Lake 结构。

项目新增能力必须继续沿用 _yuque_session + yuque_ctoken 认证方式。即使参考项目使用 token、OpenAPI、MCP 或 Skill，本项目也只借鉴功能设计，不能迁移其认证链路；下载、上传、创建和写入都遵守这一约束。

当前能力

• Cookie 登录、清理和登录态检测：auth login、auth logout、auth status
• 浏览器扫码登录：auth browser-login、auth browser-login --refresh
• 读取语雀信息：book list、book inspect、book snapshot、doc inspect
• 通用定位和本地分析：book map、md inspect
• Markdown 资源准备和 Lake 序列化：md prepare、lake serialize --markdown-file
• 文档快照和结构对比：doc snapshot、lake diff
• Lake 和 Markdown 辅助转换：lake to-markdown、lake serialize
• 安全写入和写后验证：doc apply-lake、doc update-lake、doc write-lake
• 通用本地 Markdown 批量同步：book sync-local-md
• 创建知识库和文档：book create、doc create
• 标题原生编号：--number-headings
• 整库/单篇下载：book download、doc download
• 下载资源清单、warning、retry 报告
• 本地 VitePress 预览：serve-book
• 上传并插入图片、PDF 附件：doc upload、doc insert-image、doc insert-attachment

安装

从 npm 安装：

npm install -g yuque-cookie-plugin

当前 npm 最新版本：

npm view yuque-cookie-plugin version

安装后可直接运行：

yuque --help
yuque-local --version
yuque-local --help
yuque-local auth browser-login
yuque-local doctor --json
yuque-local skill install --json

开发者本地源码运行：

git clone [email protected]:c-sunc6/yuque-cookie-plugin.git
cd yuque-cookie-plugin
npm install

开发者也可以在源码目录中作为“项目内本地 CLI”使用：

npm run yuque-local -- --help

登录

推荐使用浏览器扫码登录，这也是最接近普通用户登录语雀的方式：

yuque-local auth browser-login

它会打开语雀官方登录页，使用持久 Chromium profile：

~/.config/yuque-cookie-plugin/browser-profile

用户扫码或自行登录后，工具会读取本工具浏览器上下文中的 _yuque_session 和 yuque_ctoken，并通过 /api/mine/books 验证认证态。验证通过后才保存到本机配置。

如果 profile 中已经登录过，可以刷新 Cookie：

yuque-local auth browser-login --refresh --json

手动粘贴 Cookie 的方式仍然保留，但入口改成更明确的 auth cookie-login。旧命令 auth login 继续兼容：

yuque-local auth cookie-login

命令会打开一个本地网页，需要填写：

• 语雀个人/团队主页 URL，例如 https://www.yuque.com/your-login/
• _yuque_session
• yuque_ctoken

凭据会保存到：

~/.config/yuque-cookie-plugin/config.json

项目目录不会保存真实 Cookie。配置文件会记录保存时间、更新时间、最近成功验证时间和最近失败时间。

如果你在同一台电脑上同时做全局 npm 版真实测试和本地源码开发，可以用独立配置目录隔离 Cookie：

YUQUE_COOKIE_PLUGIN_CONFIG_DIR=/tmp/yuque-plugin-real-test yuque-local auth login
YUQUE_COOKIE_PLUGIN_CONFIG_DIR=/tmp/yuque-plugin-real-test yuque-local auth status --json

这会把配置保存到 /tmp/yuque-plugin-real-test/config.json，不会影响默认的 ~/.config/yuque-cookie-plugin/config.json。

也可以用环境变量覆盖本地配置：

export YUQUE_SESSION='your _yuque_session'
export YUQUE_CTOKEN='your yuque_ctoken'
export YUQUE_HOME_URL='https://www.yuque.com/your-login/'

验证登录态：

yuque-local auth status --json

auth status 默认会请求语雀 /api/mine/books 做真实只读验证，只返回 book_count 摘要，不展开全部知识库列表；如果只想查看本地配置文件是否存在，使用：

yuque-local auth status --local-only --json

也可以指定某个知识库或文档 URL，让状态检查改用该 URL 做 inspect：

yuque-local auth status https://www.yuque.com/<your-login>/<your-book> --json

在 Docker、SSH、远程服务器或浏览器无法自动打开的环境中，使用终端手动登录：

yuque-local auth cookie-login --manual

清理本机保存的 Cookie：

yuque-local auth logout

也可以一次性传入参数，适合本地受控脚本：

yuque-local auth cookie-login --manual \
  --home-url https://www.yuque.com/<your-login>/ \
  --session '<_yuque_session>' \
  --ctoken '<yuque_ctoken>'

常用命令

查看知识库或文档信息：

npm run yuque-local -- book inspect https://www.yuque.com/<your-login>/<your-book>

列出当前账号可访问的知识库：

yuque-local book list --json

生成整库只读快照：

yuque-local book snapshot https://www.yuque.com/<your-login>/<your-book> \
  --out /tmp/book.snapshot.json \
  --json

生成可供 AI 匹配和批量计划使用的知识库映射：

yuque-local book map https://www.yuque.com/<your-login>/<your-book> \
  --out /tmp/book.map.json \
  --json

扫描本地 Markdown 目录，不访问语雀：

yuque-local md inspect \
  --root /path/to/local-markdown \
  --out /tmp/local-md.inspect.json \
  --json

准备单篇 Markdown 的本地图片/附件：

yuque-local md prepare \
  --markdown-file article.md \
  --doc-url https://www.yuque.com/<your-login>/<your-book>/<doc-slug> \
  --out /tmp/article.prepared.md \
  --json

如果语雀网页端返回上传频率限制，命令会做短重试；仍失败时会生成失败报告并拒绝输出可继续写入的 prepared Markdown。

把 Markdown 转成语雀 Lake：

yuque-local lake serialize \
  --markdown-file /tmp/article.prepared.md \
  --out /tmp/article.lake.html \
  --json

安全写入 Lake。默认 dry-run，必须显式 --execute 才会写线上：

yuque-local doc write-lake https://www.yuque.com/<your-login>/<your-book>/<doc-slug> \
  --lake-file /tmp/article.lake.html \
  --dry-run \
  --json

yuque-local doc write-lake https://www.yuque.com/<your-login>/<your-book>/<doc-slug> \
  --lake-file /tmp/article.lake.html \
  --execute \
  --json

按标题匹配本地 Markdown 和线上已有文档，先生成批量计划：

yuque-local book sync-local-md https://www.yuque.com/<your-login>/<your-book> \
  --root /path/to/local-markdown \
  --match title \
  --dry-run \
  --json

默认 JSON 只输出摘要和 report 路径，完整计划会写入报告文件；确实需要把完整 plan/results 打到 stdout 时再加 --verbose。

确认计划后再执行，可断点续跑：

yuque-local book sync-local-md https://www.yuque.com/<your-login>/<your-book> \
  --root /path/to/local-markdown \
  --match title \
  --execute \
  --resume \
  --json

下载整个知识库：

npm run yuque-local -- book download https://www.yuque.com/<your-login>/<your-book> \
  --dist-dir download \
  --incremental

下载单篇文档：

npm run yuque-local -- doc download https://www.yuque.com/<your-login>/<your-book>/<doc-slug> \
  --dist-dir download

创建文档：

npm run yuque-local -- doc create https://www.yuque.com/<your-login>/<your-book> \
  --title AI测试文档 \
  --markdown-file article.md \
  --number-headings

插入图片：

npm run yuque-local -- doc insert-image https://www.yuque.com/<your-login>/<your-book>/<doc-slug> \
  --file ./image.png \
  --after-text "图片位置"

插入 PDF 附件：

npm run yuque-local -- doc insert-attachment https://www.yuque.com/<your-login>/<your-book>/<doc-slug> \
  --file ./example.pdf \
  --after-text "附件位置"

生成文档快照：

npm run yuque-local -- doc snapshot https://www.yuque.com/<your-login>/<your-book>/<doc-slug> \
  --out /tmp/doc.snapshot.json

对比两个快照：

npm run yuque-local -- diff-lake before.json after.json

预览下载后的知识库：

npm run yuque-local -- serve-book download/知识库 --config-only
npm run yuque-local -- serve-book download/知识库 --port 5173

原生 Lake 写入策略

项目优先使用语雀自身生成的 Lake 结构，而不是手写 Markdown 后直接覆盖。

典型流程：

1. 通过语雀 Web Session 创建或读取文档。
2. snapshot 获取语雀生成的 body_asl。
3. 只做已验证的 Lake 变换，例如标题编号 data-lake-index-type="2"。
4. 写入前生成备份和报告。

PDF 附件写入已通过真实测试验证：file card 必须包含 src + name，其中 src 指向 https://www.yuque.com/office/<filekey>?from=<doc-url>，否则语雀阅读页可能打开 about:blank。

yuque-dl 迁移

本项目已迁移并改造了部分 gxr404/yuque-dl 的核心下载能力，但不通过外部 shell 调用它，而是使用 TypeScript 在本项目内实现，并适配 _yuque_session + yuque_ctoken 的认证路径。

已支持：

• 整库下载并保持 TOC 目录结构
• 单篇/多篇文档下载
• progress.json 增量下载
• index.md 汇总页
• 图片、附件、音视频资源本地化
• 资源清单、失败 warning、retry 信息
• VitePress 本地预览配置

仍在继续补齐：

• 复杂语雀表格变体
• 音视频真实复杂样例
• 思维导图、画板、复杂 card 的原生创建和更新

开发与验证

npm run typecheck
npm test
npm run yuque-local -- --help

发布检查：

npm run release:check
npm run release:smoke

真实语雀验收不会进入默认 npm test。需要手动运行：

npm run real:acceptance -- \
  --book-url https://www.yuque.com/<your-login>/<your-book> \
  --dist-dir /tmp/yuque-real-acceptance

文档

• docs/usage-zh.md：中文完整使用指南
• docs/ai-dialogue-test-cases.md：用户和 AI 对话测试用例
• docs/real-acceptance.md：真实语雀验收流程
• docs/native-lake-capability.md：原生 Lake 能力矩阵
• docs/development-plan.md：开发计划和迭代日志
• docs/principles.md：项目开发原则
• docs/github-mvp-release.md：GitHub MVP 发布检查清单
• docs/npm-release.md：npm 发布指南
• docs/docker-quickstart.md：Docker 隔离试用命令
• docs/yuque-github-repos-cr.md：语雀 GitHub 生态项目 Change Request 分析
• docs/cr/book-snapshot-plan.md：book snapshot 整库快照功能计划
• docs/cr/browser-login-plan.md：auth browser-login 浏览器扫码登录功能计划

安全约束

• 不要把真实 _yuque_session 或 yuque_ctoken 写入项目文件。
• 不要提交 ~/.config/yuque-cookie-plugin/config.json。
• 需要清理本机凭据时运行 yuque-local auth logout。
• reports/、backups/、node_modules/ 已被 .gitignore 忽略。
• 批量写入前先对单篇文档做真实实验。
• 不确定 Lake 语义时，先 snapshot，再 diff，再实现。