shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 其它需要 API Key

语雀文档skill

当用户想要操作语雀文档时使用本 Skill。支持：推送本地 markdown 到语雀知识库、拉取云端文档到本地、创建/更新/删除文档、查看目录结构（TOC）、智能增量同步（sync）、状态对比（status）。当用户想管理语雀团队成员/权限/知识库设置、跨知识库批量迁移、或操作飞书/钉钉/Notion 等其他平台时，不要使用本 Skill。

person作者: user_924c5114hubcommunity
download下载资源包

语雀文档

通过语雀 OpenAPI 管理知识库文档。支持文档 CRUD、目录查看和智能增量同步。

语言规则

始终使用用户输入的语言进行回复。 如果用户用英文提问，则全程用英文回复；如果用户用中文，则全程用中文回复。无法判断时默认使用中文。CLI 输出为固定英文格式，转述给用户时需翻译为用户使用的语言（保留 flag 名称、slug、路径等字面值不翻译）。

What this skill owns

  • CRUD operations on documents within a single Yuque knowledge base.
  • Automatic TOC insertion after document creation.
  • Reading and displaying the knowledge base table of contents.

This skill does NOT own:

  • Yuque repository or team management (create/delete repos, manage members).
  • Cross-repo operations or batch migration.
  • Yuque authentication setup (the user must provide a valid token).

Prerequisites

  1. Python 3.8+ with requests and python-dotenv installed.
  2. A .env file in the project root (created via the setup flow below).

First-time setup

If the user has not configured this skill yet (no .env file, or list returns a config error), follow this flow:

  1. Ask for the knowledge base URL. Tell the user:

    Please paste your Yuque knowledge base URL, for example: https://xxx.yuque.com/group/book

    You can find it by opening your knowledge base in the browser and copying the address bar URL.

  2. Ask for the API token. Tell the user:

    Please paste your Yuque API token.

    To create one: open Yuque -> click your avatar (top right) -> "Account Settings" -> "Tokens" -> "Create new token". Grant it read/write access to your target knowledge base.

    Token page: https://www.yuque.com/settings/tokens

  3. Run the setup command. The script auto-parses the URL and validates the connection:

    python scripts/yuque_cli.py setup --url "<user_url>" --token "<user_token>"
    • On success: .env is written, connection is verified, .gitignore is checked.
    • On failure: the script prints the exact error (bad token, wrong URL, etc.). Fix and retry.
    • Use --force to overwrite an existing .env.

  4. Confirm by running python scripts/yuque_cli.py list.

Security rules

  • NEVER echo, print, or include the token in your text responses to the user. Pass it only as a CLI argument to the setup script.
  • NEVER commit .env to git. The setup script checks .gitignore and warns if .env is not excluded.
  • NEVER hardcode the token in any file other than .env.
  • If the user pastes a token in chat, immediately use it in the setup command and do not repeat it back.

Default path

  1. Validate prerequisites. Run python scripts/yuque_cli.py list to confirm token and repo are valid.
  2. Identify the action. Determine whether the user wants to create, update, delete, or inspect.
  3. Execute the action using scripts/yuque_cli.py with the matching subcommand.
  4. Verify the result. Use list, get, or toc to confirm the operation succeeded.
  5. Report the outcome: doc ID, title, slug, and any errors.

Command reference

| Action | Command | Key flags | |--------|---------|-----------| | Setup | python scripts/yuque_cli.py setup --url URL --token TOKEN | --force, --env-path | | List | python scripts/yuque_cli.py list | --offset, --limit | | Get | python scripts/yuque_cli.py get <id_or_slug> | | | Create | python scripts/yuque_cli.py create -t "Title" -b "Body" | -f FILE, --no-toc, --format, --slug | | Update | python scripts/yuque_cli.py update <id_or_slug> -t "T" | -b, -f FILE, --format | | Delete | python scripts/yuque_cli.py delete <id_or_slug> --confirm | --confirm required (not optional) | | TOC | python scripts/yuque_cli.py toc | | | Sync | python scripts/yuque_cli.py sync | --check, --root, --layout, --on-missing | | Pull | python scripts/yuque_cli.py pull --slug <slug> | --all, --overwrite, --root, --layout | | Status | python scripts/yuque_cli.py status | --root, --layout |

Global flags available on all commands: --json (machine-readable output), --dry-run (preview without executing).

Dry-run mode always outputs JSON regardless of the --json flag. Use it to inspect the payload before committing.

Sync workflow

Use sync for "push only what actually changed" instead of blind update. The script maintains .yuque-sync.json (auto-added to .gitignore) tracking each doc's local content hash and remote latest_version_id, so unchanged docs are skipped without any GET-detail call.

First-time init

When the user runs sync/pull/status and no state file exists, the script auto-detects the local layout from .md files under --root (default cwd):

  • flat — all .md files at top level. Slug = file stem.
  • nested — .md files under subdirectories. Slug = file stem (subdirs are organizational only; they do not create TOC groups).
  • frontmatter — every file has --- slug: xxx --- frontmatter at the top. Slug = frontmatter value.
  • empty — no .md files yet; suggest pull --all to seed locally.

If layouts are mixed or partially-frontmatter, the script errors and asks the user to pass --layout flat|nested|frontmatter or normalize the directory.

Sync flow per run

  1. Lists all remote docs once (with optional_properties=latest_version_id) — no per-doc GET.
  2. For each local file, compares normalized SHA-256 of the body and the remote latest_version_id to the values stored in .yuque-sync.json.
  3. Pushes:
    • create for local files with no remote counterpart (auto-adds to TOC).
    • update for local files whose body changed and remote did not.
    • Skips unchanged, conflicts (both sides changed, or remote moved), and non-markdown remotes (with a warning).
  4. After push, if any tracked doc has gone missing locally, stops with exit code 2 and prints a confirmation block (see below). Never auto-deletes remote docs.

Confirmation handling (exit code 2)

sync exits 2 when local files that were previously synced are now missing. This is not an error — it means the script needs an explicit choice from the user. The stdout block describes three options, each with the exact flag to re-run with:

  • --on-missing delete — delete on Yuque too
  • --on-missing pull — restore locally from Yuque
  • --on-missing forget — keep on Yuque, drop from local state

When you see exit code 2, show the printed block to the user (translated to their query language; see Language section), then re-invoke sync --on-missing <choice> once they pick.

Conflicts

If a doc was changed both locally and remotely (or remote moved while local stayed), sync lists it under "Conflicts" and skips it. Resolve manually:

  • pull --slug <slug> --overwrite — accept remote version locally.
  • update <slug> -f path/to/file.md — overwrite remote with local version.

After resolution, the next sync run will reconcile the state file.

Failure handling

  • Missing .env or token: Stop. Run the first-time setup flow above. Do NOT ask the user to manually edit .env.
  • Invalid YUQUE_REPO format: Stop. Re-run setup with the correct URL.
  • .gitignore missing .env entry: Warn the user immediately. Do not proceed with any API calls until .env is protected.
  • 401 Unauthorized: Stop. Token is invalid or expired — ask the user to regenerate it.
  • 404 Not Found: Stop. The repo path or doc ID/slug is wrong — ask the user to verify.
  • 429 Rate Limited: Wait briefly and retry once. If it fails again, stop and inform the user.
  • No fields provided on update: Stop. At least one of --title, --body, --body-file, --slug, --format, --public must be given.
  • Delete without --confirm: The script refuses. This is intentional — always pass --confirm.
  • sync exit code 2: Not an error. Confirmation required for missing-local files. Show the block to the user, get their choice, re-run with --on-missing <choice>.
  • Layout ambiguous on first sync: Show the script's suggestion to the user; do NOT pick --layout for them — ask which structure they intend.

Do NOT guess doc IDs or slugs. If unknown, run list, toc, or status first to find the target.

资源导航

  • references/yuque-cli.md — 全部命令详细说明，按场景分组
  • scripts/yuque_cli.py — CLI 工具本体，运行它；除非调试，不要直接阅读源码
  • scripts/yuque_cli.py --help 和 scripts/yuque_cli.py <cmd> --help 查看完整 flag 说明
  • 项目根目录 .env 存储凭据（不得提交到版本控制）

High-value pitfalls

  1. Creating a document does NOT auto-add it to the TOC. The script handles this by default via append_doc_to_toc. Use --no-toc only if you explicitly want an unlisted document.
  2. The id parameter in get/update/delete can be either an integer doc ID or a string slug. Both work, but slugs are more readable.
  3. Body content with shell-special characters: Use --body-file instead of --body for any non-trivial content to avoid shell quoting issues.
  4. The Yuque Lake format is proprietary. Always use --format markdown (the default) unless the user specifically needs Lake format.
  5. TOC insertion always appends to the repo root as a child node. There is no way to specify a parent node or insert at a specific position via this skill. If the user needs custom TOC structure, they must reorder it manually in the Yuque UI.
  6. sync ignores remote drafts (body_draft). Change detection is based on latest_version_id (the last published version). If a teammate is editing in the Yuque web editor without publishing, that draft will be overwritten by sync update. If you suspect this, use pull --slug <slug> --overwrite to inspect remote first.
  7. Never auto-delete remote docs. sync will only delete remotely when the user explicitly passes --on-missing delete after seeing the confirmation block. Do not pass delete on the user's behalf without an unambiguous yes.