openakita-skills-yuque-skills

name	openakita/skills@yuque-skills
description	Manage Yuque (语雀) knowledge bases, documents, and team collaboration through API integration. Supports personal search, weekly reports, knowledge base management, document CRUD, and group collaboration workflows. Based on yuque/yuque-skills.
license	MIT
metadata	{"author":"openakita","version":"1.0.0"}

Yuque Skills — 语雀知识管理

When to Use

• 用户需要搜索语雀中的文档和知识
• 需要创建、编辑、发布语雀文档
• 需要生成周报/月报并发布到语雀
• 需要管理知识库结构（目录、分类）
• 需要在团队知识库中进行协作
• 需要从语雀导出文档或同步内容
• 需要统计知识库的使用数据

---

Prerequisites

必需配置

配置项	说明
YUQUE_TOKEN	语雀 API Token
YUQUE_HOST	语雀 API 地址（默认 https://www.yuque.com/api/v2）

获取 Token：

1. 登录语雀 → 点击头像 → 设置 → Token
2. 或访问：https://www.yuque.com/settings/tokens
3. 创建新 Token，勾选所需权限

在 .env 中配置：

YUQUE_TOKEN=your_yuque_token_here
YUQUE_HOST=https://www.yuque.com/api/v2

企业版语雀的 Host 格式为 https://your-company.yuque.com/api/v2

必需依赖

依赖	用途	安装方式
httpx	HTTP API 调用	pip install httpx

可选依赖

依赖	用途	安装方式
markdownify	HTML → Markdown 转换	pip install markdownify
beautifulsoup4	HTML 解析	pip install beautifulsoup4

验证配置

curl -s -H "X-Auth-Token: $YUQUE_TOKEN" "https://www.yuque.com/api/v2/user" | python -m json.tool

---

Instructions

语雀核心概念

概念	英文	说明
用户	User	个人账号
团队	Group	组织/团队空间
知识库	Book/Repo	文档集合，类似文件夹
文档	Doc	具体的内容页面
目录	TOC	知识库内的文档组织结构
协作者	Collaborator	知识库的共同维护者

API 基础调用

所有 API 请求需携带 Token：

import httpx

YUQUE_HOST = os.environ.get("YUQUE_HOST", "https://www.yuque.com/api/v2")
YUQUE_TOKEN = os.environ["YUQUE_TOKEN"]

headers = {
    "X-Auth-Token": YUQUE_TOKEN,
    "Content-Type": "application/json",
    "User-Agent": "OpenAkita-Agent/1.0"
}

async def yuque_api(method, path, data=None):
    async with httpx.AsyncClient() as client:
        url = f"{YUQUE_HOST}{path}"
        response = await client.request(method, url, headers=headers, json=data)
        response.raise_for_status()
        return response.json()["data"]

权限说明

权限	可执行操作
只读	搜索、查看文档、导出
读写	创建、编辑、删除文档
管理	知识库设置、成员管理

---

Workflows

Workflow 1: 个人文档搜索

步骤 1 — 获取用户信息

user = await yuque_api("GET", "/user")
user_login = user["login"]
print(f"当前用户: {user['name']} ({user_login})")

步骤 2 — 搜索文档

async def search_docs(query, scope="user"):
    """搜索语雀文档"""
    params = {
        "q": query,
        "type": "doc",
        "scope": scope,
    }
    result = await yuque_api("GET", f"/search?q={query}&type=doc")
    return result

步骤 3 — 获取文档内容

async def get_doc(repo_slug, doc_slug):
    """获取文档详细内容"""
    doc = await yuque_api("GET", f"/repos/{repo_slug}/docs/{doc_slug}")
    return {
        "title": doc["title"],
        "body": doc["body"],        # Markdown 格式
        "body_html": doc["body_html"],  # HTML 格式
        "word_count": doc["word_count"],
        "updated_at": doc["updated_at"],
    }

步骤 4 — 返回搜索结果摘要

---

Workflow 2: 周报/月报生成

步骤 1 — 收集周报内容

向用户询问或从其他来源汇总：

模块	内容
本周完成	已完成的工作项列表
进行中	正在推进的工作
下周计划	下周的工作安排
风险与阻塞	需要协助的问题
数据指标	关键 KPI 变化

步骤 2 — 生成 Markdown 内容

def generate_weekly_report(data):
    """生成周报 Markdown"""
    report = f"""# 周报 | {data['date_range']}

## ✅ 本周完成

{format_task_list(data['completed'])}

## 🔄 进行中

{format_task_list(data['in_progress'])}

## 📋 下周计划

{format_task_list(data['next_week'])}

## ⚠️ 风险与阻塞

{format_risk_list(data['risks'])}

## 📊 关键指标

{format_metrics_table(data['metrics'])}
"""
    return report

步骤 3 — 发布到语雀

async def publish_report(repo_slug, title, content):
    """发布周报到指定知识库"""
    doc_data = {
        "title": title,
        "slug": generate_slug(title),
        "body": content,
        "format": "markdown",
        "status": 1,  # 0=草稿, 1=发布
    }
    result = await yuque_api("POST", f"/repos/{repo_slug}/docs", data=doc_data)
    return result

步骤 4 — 返回文档链接

---

Workflow 3: 知识库管理

列出所有知识库

async def list_repos(user_login=None, group_login=None):
    """列出知识库"""
    if group_login:
        repos = await yuque_api("GET", f"/groups/{group_login}/repos")
    else:
        repos = await yuque_api("GET", f"/users/{user_login}/repos")

    return [{
        "id": r["id"],
        "name": r["name"],
        "slug": r["slug"],
        "description": r["description"],
        "docs_count": r["items_count"],
        "namespace": r["namespace"],
        "public": r["public"],
        "updated_at": r["updated_at"],
    } for r in repos]

获取知识库目录

async def get_toc(repo_namespace):
    """获取知识库的目录结构"""
    toc = await yuque_api("GET", f"/repos/{repo_namespace}/toc")
    return toc

创建知识库

async def create_repo(user_or_group_login, name, description="", public=0):
    """创建新知识库"""
    data = {
        "name": name,
        "slug": slugify(name),
        "description": description,
        "public": public,  # 0=私有, 1=公开
        "type": "Book",
    }
    result = await yuque_api("POST", f"/users/{user_or_group_login}/repos", data=data)
    return result

---

Workflow 4: 文档 CRUD 操作

创建文档

async def create_doc(repo_namespace, title, body, format="markdown"):
    data = {
        "title": title,
        "slug": generate_slug(title),
        "body": body,
        "format": format,
    }
    return await yuque_api("POST", f"/repos/{repo_namespace}/docs", data=data)

更新文档

async def update_doc(repo_namespace, doc_id, title=None, body=None):
    data = {}
    if title:
        data["title"] = title
    if body:
        data["body"] = body
    return await yuque_api("PUT", f"/repos/{repo_namespace}/docs/{doc_id}", data=data)

删除文档

async def delete_doc(repo_namespace, doc_id):
    return await yuque_api("DELETE", f"/repos/{repo_namespace}/docs/{doc_id}")

导出文档

async def export_doc(repo_namespace, doc_slug, format="markdown"):
    """导出文档为指定格式"""
    doc = await get_doc(repo_namespace, doc_slug)
    if format == "markdown":
        return doc["body"]
    elif format == "html":
        return doc["body_html"]
    elif format == "text":
        from bs4 import BeautifulSoup
        return BeautifulSoup(doc["body_html"], "html.parser").get_text()

---

Workflow 5: 团队协作

列出团队

async def list_groups():
    """列出用户加入的所有团队"""
    groups = await yuque_api("GET", "/users/groups")
    return [{
        "id": g["id"],
        "name": g["name"],
        "login": g["login"],
        "description": g["description"],
        "members_count": g["members_count"],
    } for g in groups]

团队知识库报告

async def generate_team_report(group_login):
    """生成团队知识库使用报告"""
    repos = await list_repos(group_login=group_login)

    report = {
        "total_repos": len(repos),
        "total_docs": sum(r["docs_count"] for r in repos),
        "repos_detail": [],
    }

    for repo in repos:
        docs = await yuque_api("GET", f"/repos/{repo['namespace']}/docs")
        recent_docs = sorted(docs, key=lambda d: d["updated_at"], reverse=True)[:5]
        report["repos_detail"].append({
            "name": repo["name"],
            "doc_count": repo["docs_count"],
            "recent_updates": [d["title"] for d in recent_docs],
        })

    return report

知识库协作者管理

async def add_collaborator(repo_namespace, user_login, role="writer"):
    """添加知识库协作者"""
    data = {
        "login": user_login,
        "role": role,  # reader, writer, admin
    }
    return await yuque_api("POST", f"/repos/{repo_namespace}/collaborators", data=data)

---

Workflow 6: 知识库内容同步

将外部内容同步到语雀，或从语雀同步到本地：

从 Markdown 文件同步到语雀

async def sync_markdown_to_yuque(md_dir, repo_namespace):
    """将本地 Markdown 文件目录同步到语雀知识库"""
    import glob

    md_files = glob.glob(f"{md_dir}/**/*.md", recursive=True)

    for md_file in md_files:
        with open(md_file, "r", encoding="utf-8") as f:
            content = f.read()

        title = os.path.splitext(os.path.basename(md_file))[0]

        existing = await search_doc_by_title(repo_namespace, title)
        if existing:
            await update_doc(repo_namespace, existing["id"], body=content)
            print(f"更新: {title}")
        else:
            await create_doc(repo_namespace, title, content)
            print(f"创建: {title}")

从语雀导出到本地

async def export_repo_to_local(repo_namespace, output_dir):
    """将语雀知识库导出为本地 Markdown 文件"""
    docs = await yuque_api("GET", f"/repos/{repo_namespace}/docs")

    os.makedirs(output_dir, exist_ok=True)

    for doc_info in docs:
        doc = await get_doc(repo_namespace, doc_info["slug"])
        file_path = os.path.join(output_dir, f"{doc_info['slug']}.md")
        with open(file_path, "w", encoding="utf-8") as f:
            f.write(f"# {doc['title']}\n\n{doc['body']}")
        print(f"导出: {doc['title']} -> {file_path}")

---

Output Format

搜索结果

🔍 搜索 "项目规范" 共找到 5 条结果：

1. 📄 代码规范 v2.0
   - 知识库: 工程团队/开发规范
   - 更新时间: 2025-02-28
   - 链接: https://www.yuque.com/team/repo/doc-slug

2. 📄 项目管理规范
   - 知识库: PMO/流程文档
   - 更新时间: 2025-02-25
   - 链接: https://www.yuque.com/team/repo/doc-slug2

...

周报输出

生成后返回发布链接和摘要。

知识库统计

📊 团队知识库统计
- 总知识库数: 12
- 总文档数: 456
- 本月新增: 28 篇
- 最活跃知识库: "产品设计" (本月 12 篇更新)
- 最近更新:
  1. API 接口文档 v3 (2 小时前)
  2. Q1 OKR 复盘 (昨天)
  3. 新员工入职手册 (3 天前)

---

Common Pitfalls

1. Token 权限不足

症状：API 返回 401 或 403 解决：

• 确认 Token 有读写权限
• 企业版语雀可能需要管理员授权
• 检查 Token 是否过期

2. namespace 格式错误

语雀的 namespace 格式为 {user_or_group_login}/{repo_slug}，例如 myteam/dev-docs。

错误：使用 repo 名称代替 slug 正确：使用 URL 中的 slug

3. Markdown 与 HTML 格式混淆

语雀文档有两种内容格式：

• body：Markdown 格式（创建时使用 format: "markdown"）
• body_html：HTML 格式

创建文档时需明确指定 format 参数。

4. API 频率限制

语雀 API 有请求频率限制：

• 个人版：约 100 次/分钟
• 企业版：通常更高

解决：批量操作时添加延迟：

import asyncio
for doc in docs:
    await process_doc(doc)
    await asyncio.sleep(0.5)

5. 文档 slug 冲突

同一知识库中 slug 必须唯一。创建文档前先检查是否已存在：

async def safe_create_doc(repo_namespace, title, body):
    slug = generate_slug(title)
    existing = await find_doc_by_slug(repo_namespace, slug)
    if existing:
        slug = f"{slug}-{int(time.time())}"
    return await create_doc(repo_namespace, title, body, slug=slug)

6. 企业版与个人版 API 差异

企业版语雀的部分 API 路径和参数可能有差异：

• Host 不同（your-company.yuque.com）
• 部分接口需要额外权限
• 团队管理接口更丰富

7. 大文档性能问题

超过 5 万字的文档在创建/更新时可能超时。建议：

• 拆分为多篇文档
• 使用分页上传
• 图片先上传到 CDN 再引用

---

EXTEND.md 扩展

用户可在技能同目录下创建 EXTEND.md 添加：

• 默认知识库 namespace
• 团队的语雀 Host 地址
• 周报/月报模板定制
• 常用知识库列表和别名
• 自定义文档模板