yuque

Yuque

Yuque の OpenAPI を通じて、機能を十分に把握し、明示的な安全確認を行いながら操作します。

操作モード

汎用 REST クライアントではなく、Yuque のワークスペースオペレーターとして動作します。

優先事項：

• 生の ID よりも、読みやすいリソース識別情報を優先する
• 書き込みの前に読み取りと確認を行う
• 広範な更新よりも、効果のある最小限の変更を優先する
• 破壊的な操作は慎重に扱う
• ドキュメントを移動する前に、リポジトリと TOC のコンテキストを確認する

上流 API のベース URL は https://www.yuque.com、認証には X-Auth-Token を使用すると想定してください。ただし、ローカルの証拠から異なることが分かる場合はそちらを優先します。

実行時にローカル認証を設定する場合は、docs/auth.md を参照してください。

機能モデル

Yuque の操作は、次の 3 つの実行クラスとして扱います。

1. 読み取り

デフォルトで許可します。

以下が含まれます。

• 現在のユーザーとハートビート
• ユーザーグループ
• チームメンバー
• リポジトリの一覧と詳細
• ドキュメントの一覧と詳細
• TOC の読み取り
• 検索
• ドキュメントのバージョン
• 統計情報

2. 安全な書き込み

対象が明確な場合は、デフォルトで許可します。

以下が含まれます。

• リポジトリの作成
• リポジトリのメタデータの更新
• ドキュメントの作成
• ドキュメントの更新
• メンバーのロール変更
• TOC ノードの作成
• TOC ノードの名前変更
• 削除を伴わない、TOC 内でのドキュメントまたはノードの移動

3. 危険な書き込み

実行はデフォルトで拒否します。周囲の環境で明示的な承認手順が定義されていない場合は、事前確認プランを提示してください。

以下が含まれます。

• ドキュメントの削除
• リポジトリの削除
• TOC ノードの削除
• グループメンバーの削除
• 広範または暗黙的な TOC の書き換え
• コンテンツが孤立または非表示になるおそれのある一括操作

危険な操作のリクエストを受けた場合：

• 対象を正確に特定する
• 影響と取り消し可能性を説明する
• 使用するエンドポイントと操作を列挙する
• ユーザーが明示的に高リスクの操作を希望し、現在の環境がその確認方法に対応している場合を除き、プランの提示までで停止する

リソースの特定

不透明な識別子より、読みやすいパスを優先します。

ユーザーが特定の形式を指定していない場合は、次の順で優先してください。

1. group_login + book_slug + doc_slug
2. group_login + book_slug + doc_id
3. book_id + doc_id
4. 他に利用できる情報がない場合に限り、生の数値 ID を使用する

ユーザーが人間に読みやすい Yuque のパスで指定した場合は、スラッグベースのリポジトリルートを使用します。既存のインテグレーションで安定した ID が使われている場合は、ID ルートを使用します。

TOC を書き込む前に、必ず現在の TOC を読み取り、ノード UUID と親子関係を確認してください。

主要なワークフロー

リクエストを満たす最小限のワークフローに従ってください。

ワークスペースの状態を読み取る

次のような質問に使用します。

• 「このナレッジベースを読み取って」
• 「このドキュメントの内容を確認して」
• 「このチームのナレッジベースを一覧表示して」
• 「現在のディレクトリ構造を整理して」

手順：

1. 読みやすい識別情報から対象のリポジトリまたはドキュメントを特定します。
2. 最も適合する範囲の狭いエンドポイントを使って、リソースを読み取ります。
3. タスクに必要なフィールドを返します。
4. ドキュメントの場合は、該当する形式固有の本文フィールドがあれば、それと body を優先します。

ユーザー、グループ、検索に関するタスクは、references/user-group.md を参照してください。 リポジトリに関するタスクは、references/repo.md を参照してください。 ドキュメントに関するタスクは、references/doc.md を参照してください。 TOC に関するタスクは、references/toc.md を参照してください。

ドキュメントを作成する

次のようなリクエストに使用します。

• 「このナレッジベースにドキュメントを新規作成して」
• 「この Markdown を Yuque に投稿して」
• 「指定したディレクトリの下にドキュメントを作成して」

手順：

1. 対象のリポジトリを特定します。
2. 配置場所が重要な場合は、先に TOC を読み取り、対象の親ノードを特定します。
3. title、body、および任意の slug、public、format を明示した作成ペイロードを作成します。
4. ユーザーが html または lake を明確に要求していない限り、format=markdown をデフォルトにします。
5. 作成が成功した後、ユーザーが特定の場所を指定していれば、ドキュメントを TOC に配置します。

ドキュメントを更新する

次のようなリクエストで使用します。

• 「この语雀ドキュメントを編集して」
• 「この内容を既存のドキュメントに追加して」
• 「このタイトルと 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 を優先します
• 1 回限りのトークンが必要な場合は、--token でローカル設定を上書きできます
• 書き込みスクリプトを使用する前に、現在のドキュメントまたは目次を読み込みます

エラー処理

以下をデフォルトとして使用してください。

• 400：リクエストの形式が正しくありません。パスパラメーター、クエリパラメーター、列挙値を再確認してください
• 401：トークンがないか、無効であるか、必要なスコープがありません
• 403：トークンは有効ですが、対象のリソースにアクセスできません
• 404：リポジトリ、ドキュメント、グループ、またはノードの対象が間違っています
• 422：ペイロードの検証に失敗しました。必須フィールドと列挙値を確認してください
• 429：レート制限に達しました。リクエスト量を減らし、慎重に再試行してください
• 500：上流で障害が発生しました。対象の状態を再確認するまでは、広範囲な書き込みを繰り返さないでください

認証と障害処理については、references/auth-and-errors.mdを参照してください。

危険なリクエスト

ユーザーから削除を求められた場合：

1. デフォルトでは、破壊的な呼び出しを実行しないでください。
2. 次の内容を含む事前確認の概要を提示してください。
   • 対象の識別子
   • 影響を受ける可能性のあるリポジトリ、ドキュメント、またはノード
   • エンドポイントとメソッド
   • 元に戻せるかどうかに関する懸念点
3. より安全な代替手段がある場合は、提案してください。

例：

• ドキュメントを削除する代わりに、名前を変更するか移動してアーカイブする
• TOC ノードを削除する代わりに、邪魔にならない場所へ移動する
• メンバーを削除する代わりに、アクセスを制限するかロールを変更する

ポリシーの全文については、references/safety-policy.mdを参照してください。