语雀 Skill

SKILL.md

---
name: yuque
description: 通过语雀开放API对语雀(Yuque)文档与知识库执行端到端自动化操作 —— 创建/读取/更新/删除文档、管理知识库目录(TOC)、调整Markdown排版(字号、颜色、标题、表格、代码块、提示框)、全文搜索及批量导入导出。任何用户提到"语雀""yuque""知识库""文档目录""TOC""语雀文档格式调整""语雀批量导出"或上传语雀导出的Markdown文件,即使没有显式说"使用skill",也应主动调用此skill。
license: Complete terms in LICENSE.txt
---

# 语雀(Yuque)自动化Skill

把语雀的开放API包装成一组开箱即用的Python脚本,让Openclaw / Claude Code能够像操作本地文件那样操作云端语雀文档。

## 何时用本Skill

- 用户提到"语雀"或"yuque"——无论是想"在语雀里建一篇文章"、"把这份Markdown发到我的语雀知识库"、"调整语雀目录结构"还是"批量导出我语雀小记里的文档"。
- 用户描述了语雀文档但没点名API:例如"帮我把这份会议纪要按一级标题分章后发布"或"把这30篇文档按主题重排目录",仍应优先考虑本skill。
- 用户上传了`.md`并要求"同步到语雀"或上传了从语雀导出的Markdown想做处理。
- 用户问"我的语雀里面有哪些文档/知识库"或"按关键词搜一下我的语雀"。

不适用场景:用户只是问语雀这个产品本身的功能或定价(直接回答即可,无需调用脚本)。

## 第0步:确认凭证

语雀API所有写操作都需要 `X-Auth-Token`。本skill支持两种凭证来源,优先级 **环境变量 > 配置文件**:

1. 环境变量 `YUQUE_TOKEN`(推荐,长期任务可在Openclaw启动shell时 `export`)。
2. 配置文件 `~/.yuque/config.json`,格式:
   ```json
   {"token": "xxxxxxxxxxxxxxxx", "base_url": "https://www.yuque.com/api/v2"}
   ```
   私有部署的语雀专有云请把 `base_url` 改成自己的域名。

调用任何脚本前先执行 `python scripts/yuque_client.py whoami` 自检,如果返回当前用户信息就说明凭证可用;若返回401请引导用户去 [https://www.yuque.com/settings/tokens](https://www.yuque.com/settings/tokens) 创建Token,再决定是写入环境变量还是配置文件。

## 第1步:用脚本完成具体操作

每个脚本都是命令行入口,统一返回JSON到stdout(便于后续pipeline处理)。在Openclaw中通过 `python scripts/<name>.py <subcmd> [args]` 调用即可。

### 文档与知识库 CRUD —— `scripts/docs.py`

```
docs.py list-repos [--user <login>] [--group <group>]
docs.py list-docs <namespace>                     # 列知识库下的全部文档
docs.py get <namespace> <slug>                    # 读取单篇正文(Markdown)
docs.py create <namespace> --title <t> [--slug <s>] [--body-file <path>] [--public 0|1]
docs.py update <namespace> <slug_or_id> [--title ...] [--body-file ...] [--public ...]
docs.py delete <namespace> <slug_or_id>
docs.py copy   <src_ns> <slug> --to <dst_ns>      # 跨知识库克隆
```

`namespace` 形如 `user_login/repo_slug`。如果用户只给了知识库名而没给slug,先用 `list-repos` 找到对应namespace。

### 目录(TOC)管理 —— `scripts/toc.py`

```
toc.py show     <namespace>                        # 树形输出当前TOC
toc.py add-doc  <namespace> --doc-id <id> [--parent-uuid <uuid>] [--title ...]
toc.py add-title <namespace> --title <章节名> [--parent-uuid ...]   # 纯目录占位节点
toc.py move     <namespace> --uuid <uuid> --target <uuid> --mode {before|after|inside}
toc.py rename   <namespace> --uuid <uuid> --title <新名>
toc.py remove   <namespace> --uuid <uuid> [--keep-doc]              # 默认连文档一起移除
```

TOC的节点uuid通过`show`拿到。任何批量重排都建议先 `toc.py show > tmp.json`,在内存里改完再用 `toc.py apply tmp.json` 一次提交,避免中间态导致目录错乱(详见 `references/toc_operations.md`)。

### Markdown格式化辅助 —— `scripts/format_helpers.py`

语雀本质上吃Markdown,但额外支持一些显示控件(`<font color>`、`color()`、警示框、思维导图等)。本脚本提供以下生成器,直接 import 调用:

```python
from scripts.format_helpers import (
    heading,         # heading("标题", level=2) -> "## 标题"
    colored,         # colored("重要", "#FF0000") -> '<font color="#FF0000">重要</font>'
    sized,           # sized("大字", "20px")
    styled,          # styled("文字", color="#FF0000", size="18px", bold=True) -> <span style="...">
    callout,         # callout("注意", kind="warning") -> 语雀提示框
    table,           # table(headers, rows) -> Markdown表格
    code_block,      # code_block(src, lang="python")
    toc_anchor,      # 在文档内插入#anchor
    math_block,      # 行间LaTeX
    sanitize,        # sanitize(body) -> 清洗语雀不支持的危险HTML(422前调用)
)
```

详细可用值与转义规则参见 `references/markdown_format.md`。

### 搜索 —— `scripts/search.py`

```
search.py docs <keyword> [--scope user|group|repo] [--namespace ...] [--type doc|book]
search.py find-by-title <namespace> <substring>    # 本地索引精确匹配
```

### 批量操作 —— `scripts/batch.py`

```
batch.py export <namespace> --out-dir ./dump        # 把整本知识库存成Markdown
batch.py import --from-dir ./dump --to <namespace>  # 反向同步,文件名即slug
batch.py replace <namespace> --pattern <re> --replacement <s> [--dry-run]
```

## 第2步:把结果回报给用户

脚本默认输出JSON。把JSON里的关键字段(文档url、id、title、count)抽出来,用人话告诉用户做了什么:

> 已在「我的工作笔记」知识库下创建《Q4复盘》,链接: https://www.yuque.com/<login>/<book>/<slug>。共写入 8 段、2 张表格。

如果操作影响多篇文档(批量),给出受影响数量与一份示例链接,而不是把每条都列出来。

## 错误处理约定

- 401:凭证失效 → 提示重新生成Token。
- 404:namespace或slug错 → 自动调用 `docs.py list-repos / list-docs` 确认存在性后再决定是否重试。
- 429:被限流 → 脚本内置指数退避(`yuque_client.py` 中 `_request` 实现),不需要在外层处理。
- 422:正文里含语雀不支持的HTML → 调用 `format_helpers.sanitize(body)` 清洗一遍再重提交。

## 进一步阅读

- `references/api_reference.md` —— 语雀v2 API所有已封装端点的速查表
- `references/markdown_format.md` —— 语雀Markdown扩展语法(颜色/字号/警示框/公式/思维导图)
- `references/toc_operations.md` —— TOC的action/target_type字段细节及批量重排范式
- `README.md` —— 在Openclaw中安装与部署本skill的步骤