Yuque 语雀知识库管理

This skill enables AI agents to interact with Yuque (语雀) — a Chinese knowledge management platform — through its OpenAPI. It works across Claude Code, opencode, openclaw, and any agent with shell access.

Quick Start#

Install this skill, then tell your AI agent:

帮我配置语雀 API，我的 token 是 xxxxxxxx

The agent will automatically create config.json and verify connectivity.

How to get your API Token#

1. Login to Yuque
2. Click Avatar → Settings (设置) → Developer (开发者) → Personal Access Token (个人访问令牌)
3. Create a new token, copy it

Setup Details#

Authentication requires a Yuque API token. The scripts look for it in this order:

1. config.json (preferred): Create config.json in this skill's root directory: json

   {
     "api_token": "your-yuque-api-token",
     "base_url": "https://www.yuque.com"
   }
   
   

   See config.example.json for the template.

2. Environment variable (fallback): export YUQUE_TOKEN="your-token"

When the user provides their API token, create config.json by copying config.example.json and filling in the token, then run python scripts/get_user.py to verify. If verification succeeds, show the user's name to confirm.

Verify setup: python scripts/get_user.py

Scripts#

All scripts are in the scripts/ directory. They use only Python standard library (zero dependencies). Output is JSON to stdout, errors go to stderr.

Search & Read (RAG)#

ScriptUsageDescriptionsearch.py``python scripts/search.py "keyword"Search docs or reposget_doc.py``python scripts/get_doc.py --repo REPO --doc DOCGet full document contentlist_docs.py``python scripts/list_docs.py --repo REPOList all docs in a repodoc_versions.py``python scripts/doc_versions.py --doc DOCDocument version history

Create & Edit#

ScriptUsageDescriptioncreate_doc.py``python scripts/create_doc.py --repo REPO --title "Title" --body-file file.mdCreate a documentupdate_doc.py``python scripts/update_doc.py --repo REPO --doc DOC --body-file file.mdUpdate a documentdelete_doc.py``python scripts/delete_doc.py --repo REPO --doc DOCDelete a document

Knowledge Base#

ScriptUsageDescriptionlist_repos.py``python scripts/list_repos.pyList user's reposcreate_repo.py``python scripts/create_repo.py --name "Name" --slug slugCreate a new repo

Table of Contents#

ScriptUsageDescriptionget_toc.py``python scripts/get_toc.py --repo REPOGet repo TOC treeupdate_toc.py``python scripts/update_toc.py --repo REPO --action appendNode ...Update TOC structure

User#

ScriptUsageDescriptionget_user.py``python scripts/get_user.pyGet current user info

Workflows#

Search & Read (RAG)#

When the user asks to find or read content from Yuque:

1. Search: python scripts/search.py "keyword" — returns titles, IDs, and summaries
2. Present the search results to the user as a numbered list
3. Once the user selects a document, fetch the full content: python scripts/get_doc.py --repo REPO_ID --doc DOC_ID
4. The response data.body field contains the markdown content. If body is empty, use body_html or body_lake as fallback.

Write & Upload#

When the user asks to write content and upload it to Yuque (e.g., "write a dev doc and upload to Yuque"):

1. Write the content locally as a markdown file (e.g., /tmp/yuque_doc.md)
2. Find the target repo: python scripts/list_repos.py — ask the user which repo to use
3. Upload: python scripts/create_doc.py --repo REPO_ID --title "Title" --body-file /tmp/yuque_doc.md
4. The response includes the document URL in data.slug — combine with repo namespace to form the full URL

Edit Existing Document#

When the user asks to update an existing Yuque document:

1. Find the doc: python scripts/search.py "doc title" or python scripts/list_docs.py --repo REPO_ID
2. Read current content: python scripts/get_doc.py --repo REPO_ID --doc DOC_ID
3. Modify the content locally
4. Update: python scripts/update_doc.py --repo REPO_ID --doc DOC_ID --body-file /tmp/updated.md

Organize Notes#

When the user asks to organize or restructure their knowledge base:

1. View current structure: python scripts/get_toc.py --repo REPO_ID
2. Plan the reorganization based on user instructions
3. Apply changes: python scripts/update_toc.py --repo REPO_ID --action appendNode --action-mode child --doc-ids DOC_ID
4. Use --action removeNode to remove nodes, --action editNode to rename

Script Details#

Body input for create/update#

Documents support three ways to provide body content:

• --body "inline content" — for short content
• --body-file /path/to/file.md — for files (recommended for long content)
• Pipe via stdin: echo "content" | python scripts/create_doc.py ...

Pagination#

List endpoints support --offset and --limit parameters. Default limit is 100.

Repository identifiers#

The --repo parameter accepts either:

• Numeric ID: --repo 12345
• Namespace path: --repo group_login/book_slug (more readable)

Document format#

Default format is markdown. All scripts default to creating/updating in markdown format. Use --format html or --format lake if needed.

User Intent Mapping#

User saysAction"搜索/查找语雀上关于 X 的文档"search.py "X" → get_doc.py"读取/打开这篇语雀文档"get_doc.py --repo R --doc D"写一篇文档上传到语雀"Write locally → list_repos.py → create_doc.py"更新/修改语雀上的文档"search.py → get_doc.py → edit → update_doc.py"列出我的知识库"list_repos.py"查看知识库目录"get_toc.py --repo R"整理/重新组织笔记"get_toc.py → update_toc.py"创建新的知识库"create_repo.py --name "X" --slug x"删除这篇文档"delete_doc.py --repo R --doc D"查看文档历史版本"doc_versions.py --doc D