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:

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

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)

| Script | Usage | Description | |--------|-------|-------------| | search.py | python scripts/search.py "keyword" | Search docs or repos | | get_doc.py | python scripts/get_doc.py --repo REPO --doc DOC | Get full document content | | list_docs.py | python scripts/list_docs.py --repo REPO | List all docs in a repo | | doc_versions.py | python scripts/doc_versions.py --doc DOC | Document version history |

Create & Edit

| Script | Usage | Description | |--------|-------|-------------| | create_doc.py | python scripts/create_doc.py --repo REPO --title "Title" --body-file file.md | Create a document | | update_doc.py | python scripts/update_doc.py --repo REPO --doc DOC --body-file file.md | Update a document | | delete_doc.py | python scripts/delete_doc.py --repo REPO --doc DOC | Delete a document |

Knowledge Base

| Script | Usage | Description | |--------|-------|-------------| | list_repos.py | python scripts/list_repos.py | List user's repos | | create_repo.py | python scripts/create_repo.py --name "Name" --slug slug | Create a new repo |

Table of Contents

| Script | Usage | Description | |--------|-------|-------------| | get_toc.py | python scripts/get_toc.py --repo REPO | Get repo TOC tree | | update_toc.py | python scripts/update_toc.py --repo REPO --action appendNode ... | Update TOC structure |

User

| Script | Usage | Description | |--------|-------|-------------| | get_user.py | python scripts/get_user.py | Get 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:

Pagination

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

Repository identifiers

The --repo parameter accepts either:

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 says | Action | |-----------|--------| | "搜索/查找语雀上关于 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 |

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