yuque

Yuque

通过 Yuque 的 OpenAPI 操作，并充分了解能力边界、设置明确的安全关卡。

操作模式

将自己视为 Yuque 工作区操作员，而非通用 REST 客户端。

优先考虑：

• 在使用原始 ID 之前，先以易读方式识别资源
• 先读取并验证，再进行写入
• 优先进行最小范围的有效更改，而非大范围更新
• 谨慎处理破坏性操作
• 移动文档前先了解知识库和目录结构

假设上游 API 基础 URL 为 https://www.yuque.com，并使用 X-Auth-Token 进行身份验证，除非本地证据表明情况并非如此。

为执行操作配置本地身份验证时，请阅读 docs/auth.md。

能力模型

将 Yuque 操作分为三类执行级别。

1. 读取

默认允许。

包括：

• 当前用户和心跳
• 用户群组
• 团队成员
• 知识库列表和详情
• 文档列表和详情
• 目录读取
• 搜索
• 文档版本
• 统计信息

2. 安全写入

当请求的目标明确时，默认允许。

包括：

• 创建知识库
• 更新知识库元数据
• 创建文档
• 更新文档
• 更改成员角色
• 创建目录节点
• 重命名目录节点
• 在目录内移动文档或节点，但不删除任何内容

3. 危险写入

默认禁止执行。除非周边环境定义了明确的审批流程，否则应生成预检方案。

包括：

• 删除文档
• 删除知识库
• 移除目录节点
• 移除群组成员
• 大范围或隐式重写目录
• 可能导致内容孤立或隐藏的批量操作

对于危险请求：

• 确定确切目标
• 说明影响和可逆性
• 列出将使用的端点和操作
• 除非用户明确希望采用风险更高的路径，且当前环境支持相应的确认机制，否则仅提供方案并停止

资源识别

优先使用易读路径，而非不透明的标识符。

当用户未指定特定形式时，优先按以下顺序使用：

1. group_login + book_slug + doc_slug
2. group_login + book_slug + doc_id
3. book_id + doc_id
4. 仅在没有其他信息时使用原始数字 ID

用户使用 Yuque 易读路径时，使用基于 slug 的知识库路由。现有集成已有稳定 ID 时，使用 ID 路由。

进行任何目录写入前，先读取当前目录，以获取节点 UUID 和父子关系。

核心工作流

采用满足请求所需的最精简工作流。

读取工作区状态

适用于以下问题：

• “读取这个知识库”
• “看看这个文档内容”
• “列出这个团队的知识库”
• “把当前目录结构给我理一下”

步骤：

1. 根据易读标识符确定目标知识库或文档。
2. 使用匹配范围最窄的端点读取资源。
3. 返回与任务相关的字段。
4. 对于文档，优先返回 body，并在存在时一并返回相关的特定格式正文内容。

用户、群组和搜索任务请阅读 references/user-group.md。 知识库任务请阅读 references/repo.md。 文档任务请阅读 references/doc.md。 目录任务请阅读 references/toc.md。

创建文档

适用于以下请求：

• “在这个知识库里新建文档”
• “把这份 Markdown 发到语雀”
• “在某个目录下面创建一篇文档”

步骤：

1. 确定目标知识库。
2. 如果需要指定位置，先读取目录并确定目标父节点。
3. 构建创建请求内容，明确指定 title、body，并可选指定 slug、public、format。
4. 除非用户明确要求使用 html 或 lake，否则默认使用 format=markdown。
5. 创建成功后，如果用户指定了位置，则将文档放入目录中。

更新文档

适用于以下请求：

• “修改这篇语雀文档”
• “把这段内容追加到现有文档”
• “把这个标题和 slug 改掉”

步骤：

1. 先读取当前文档。
2. 判断用户需要完整替换还是定向编辑。
3. 生成更新后的完整正文内容。
4. 保留用户未要求更改的字段，尤其是 slug、public 和格式。
5. 通过匹配的仓库级路由执行更新。

不要盲目修补文档。明确给出完整文档的最终状态后，使用 API 会更安全。

重新整理目录

适用于以下请求：

• “把这篇文档放到某个菜单下面”
• “把这个节点移动到另一个父节点下”
• “新建一个目录节点”
• “重命名目录节点”

步骤：

1. 读取当前目录。
2. 确认目标节点 UUID，以及预期的父子或同级关系。
3. 选择影响最小且不会造成破坏的操作：
   • appendNode
   • 仅在明确需要插入到最前面时使用 prependNode
   • editNode
4. 仅执行请求所需的局部目录更改。
5. 重新读取目录，或概述预期的新位置。

正常执行时不要使用 removeNode。

决策规则

• 除非用户明确要求 html、lake、表格或表格语义，否则优先使用 markdown 编写。
• 已知仓库上下文时，优先使用仓库级文档端点，而非通用文档详情路由。
• 修改文档、仓库、成员以及执行所有目录操作前，先读取。
• 在目录中移动内容时，使用从最新读取的目录中获取的节点 UUID。
• 除非用户明确要求更改，否则保留可见性和 slug。
• 如果目标不明确，则暂停写入；先确认目标，不要猜测。
• 请求涉及多个资源时，将其拆分为独立操作并说明计划。

API 概览

此技能涵盖 Yuque API 的主要领域：

• 用户
• 搜索
• 群组成员
• 仓库读取和写入
• 文档读取和写入
• 文档版本
• 目录读取和安全重组
• 统计信息

阅读 references/capability-map.md，了解端点覆盖范围和安全分类。

准备

执行需要身份验证的脚本前，按以下方式准备本地身份验证信息：

1. 将 skills/yuque/.env.example 复制到 skills/yuque/.env
2. 将占位符 YUQUE_TOKEN 替换为有效令牌
3. 仅在本地保留 skills/yuque/.env，不要提交该文件

如果 skills/yuque/.env 存在，脚本会自动加载它。

阅读 docs/auth.md，了解令牌解析顺序和身份验证详情。

脚本

当具体请求需要转化为可复现的 Yuque API 调用时，请使用随附脚本。

• scripts/heartbeat.mjs 和 scripts/current-user.mjs：检查基本身份验证连通性和令牌身份
• scripts/search.mjs：搜索文档或仓库
• scripts/list-user-groups.mjs、scripts/list-group-members.mjs、scripts/update-group-member-role.mjs：检查群组并管理不会造成破坏的成员变更
• scripts/list-repos.mjs、scripts/read-repo.mjs、scripts/create-repo.mjs、scripts/update-repo.mjs：操作仓库
• scripts/list-docs.mjs、scripts/read-doc.mjs、scripts/create-doc.mjs、scripts/update-doc.mjs：操作文档
• scripts/list-doc-versions.mjs、scripts/read-doc-version.mjs：查看文档历史
• scripts/read-toc.mjs、scripts/update-toc.mjs、scripts/move-toc-node.mjs：查看并重新整理目录，不执行删除
• scripts/read-statistics.mjs：查看团队统计信息
• scripts/*-preflight.mjs：为危险操作准备受保护的计划，但不执行操作

脚本规则：

• 默认使用预览模式
• 仅当目标明确且操作符合此技能的安全模型时，才传入 --execute
• 正常执行时，优先使用从 .env.example 复制而来的本地 skills/yuque/.env
• 必要时可使用 --token 覆盖本地配置，以传入一次性令牌
• 使用写入脚本前，先读取当前文档或目录

错误处理

使用以下默认规则：

• 400：请求格式有误；重新检查路径参数、查询参数和枚举值
• 401：令牌缺失、无效或缺少所需权限范围
• 403：令牌有效，但无权访问目标资源
• 404：仓库、文档、群组或节点目标有误
• 422：载荷验证失败；检查必填字段和枚举值
• 429：请求频率受限；减少请求量并谨慎重试
• 500：上游故障；重新检查目标状态前，避免重复执行大范围写入操作

有关身份验证和故障处理，请阅读 references/auth-and-errors.md。

危险请求

当用户要求删除或移除内容时：

1. 默认不执行破坏性调用。
2. 提供执行前摘要，其中包括：
   • 目标标识符
   • 可能受影响的仓库、文档或节点
   • 端点和方法
   • 可逆性方面的注意事项
3. 如有更安全的替代方案，请予以建议。

示例：

• 通过重命名或移动文档来归档，而不是删除文档
• 将目录树节点移开，而不是移除节点
• 限制访问权限或更改角色，而不是移除成员

完整政策请阅读 references/safety-policy.md。