yuque

name	yuque
description	Read and write Yuque (语雀) documents with the user's own personal access token through the official open API at https://www.yuque.com/api/v2. Use when the user wants to publish Markdown to 语雀, list their knowledge bases (知识库), read or update a 语雀 document, or delete one.
when_to_use	Trigger for 语雀 / Yuque document management: verify the connected account, list knowledge bases or the documents inside one, read a document, create a Markdown document, update an existing one, or delete one. Writes and destructive actions require explicit confirmation.
connections	["yuque"]
allowed_tools	["Bash"]
license	Apache-2.0
metadata	{"author":"acedatacloud","version":"1.0"}

Use the bundled standard-library CLI. The connector injects the user's 语雀 personal access token as $YUQUE_TOKEN. Never print it. The CLI uses the official open API at https://www.yuque.com/api/v2 with the documented X-Auth-Token header.

python3 "$SKILL_DIR/scripts/yuque.py" whoami

If $SKILL_DIR points at a different skill loaded in the same turn, resolve this skill's directory explicitly before running the commands below.

If authentication fails, ask the user to create a token at https://www.yuque.com/settings/tokens and reconnect at https://auth.acedata.cloud/user/connections. Do not ask for their account password or Cookie.

Read

A repo is a 语雀 knowledge base, addressed either by its namespace (user/book, as shown in the document URL) or by its numeric id. Always run repos first — never guess a namespace.

# Verify the token and see the account.
python3 "$SKILL_DIR/scripts/yuque.py" whoami

# List knowledge bases, then the documents in one.
python3 "$SKILL_DIR/scripts/yuque.py" repos
python3 "$SKILL_DIR/scripts/yuque.py" docs germey/blog --limit 20
python3 "$SKILL_DIR/scripts/yuque.py" doc germey/blog DOC_ID

Create and update

Prepare the complete Markdown in a file. 语雀 has no separate draft state — a document is either private or public — so the CLI creates private documents by default and only publishes publicly with an explicit --public.

# First call is always a dry run and does not load credentials or call the API.
python3 "$SKILL_DIR/scripts/yuque.py" create germey/blog \
  --title "标题" --content-file /tmp/article.md

# Create it privately after the user confirms.
python3 "$SKILL_DIR/scripts/yuque.py" create germey/blog \
  --title "标题" --content-file /tmp/article.md --confirm

# Public publishing additionally requires --public.
python3 "$SKILL_DIR/scripts/yuque.py" create germey/blog \
  --title "标题" --content-file /tmp/article.md --public --confirm

python3 "$SKILL_DIR/scripts/yuque.py" update germey/blog DOC_ID \
  --title "新标题" --content-file /tmp/article.md --public --confirm

--confirm is valid only as the final argument. Always show the target knowledge base, title, visibility and full content to the user before a public publish. Default to a private document unless the user explicitly asks to publish publicly.

Note that update rewrites the whole document body. Read the current document first if the user only wants part of it changed.

Delete

python3 "$SKILL_DIR/scripts/yuque.py" delete germey/blog DOC_ID --confirm

Use the real returned doc_id and URL. Do not retry a timed-out write automatically because its outcome may be unknown; list the documents first so you do not create a duplicate.

Gotchas

• Images referenced by external URL are not re-hosted; 语雀 renders them from the original host. If the source blocks hotlinking, upload the images to 语雀 manually first and reference the returned URLs.
• 语雀's own terms state the open API is for normal reading and writing of 语雀 content; abnormal automated behaviour can get the account blocked. Keep the volume human-scale.

Record the output

After a confirmed public publish returns a real URL, call publish_artifact once with kind="article", channel="yuque", the title, returned URL, and status="delivered". Do not record private documents or failed/unknown writes.