语雀文档

通过语雀 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.

1. 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

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

```bash

python scripts/yuque_cli.py setup --url "" --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.

1. 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 | |

| Create | python scripts/yuque_cli.py create -t "Title" -b "Body" | -f FILE, --no-toc, --format, --slug |

| Update | python scripts/yuque_cli.py update -t "T" | -b, -f FILE, --format |

| Delete | python scripts/yuque_cli.py delete --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 | --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 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 --overwrite — accept remote version locally.
• update -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 .
• 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 --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 --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.