draft-cli

Draft CLI スキル

JSON Workspace のページドメインに関する Draft 操作と、ホスト型 Secret Share ヘルパーには draft を使用します。

現在のランタイム契約

• デフォルトのページ対象には、保存済みの JSON Workspace を優先してください。
• ページコマンドを実行する前にワークスペースのメタデータコマンドを使用し、CLI がどのフォルダーとソースを使用しているか確認してください。
• ヘッドレスストレージが廃止されるまでは、JSON Workspace のデータを対象とする必要があるページコマンドに、解決済みのワークスペースパスを --workspace-json <folder> で渡してください。

ページコマンドでのワークスペース優先パターン

draft page ls、draft page cat、draft page create、 draft page append、draft page replace、draft page patch、draft page annotate、および draft page publish などのページコマンドでは、次のようにします。

draft workspace status --json
draft workspace path --json

返された active_workspace_path を使用して、ページコマンドの対象を明示してください。

draft --workspace-json <active_workspace_path> page ls --json
draft --workspace-json <active_workspace_path> page cat <page_id> --json

フォルダーを明示的に上書きする場合は、--workspace-json を指定してコマンドの対象を固定してください。

draft --workspace-json <folder> page ls --json
draft --workspace-json <folder> page cat <page_id> --json

そのフォルダーをデフォルトのワークスペースにする場合は、まず設定してください。

draft workspace set-path <folder> --json
draft workspace status --json

結果をユーザーに説明する前に、CLI が保存済みのデフォルトパスと明示的な上書きのどちらを使用しているか、ワークスペースのメタデータで確認してください。

バージョンの検出と古い CLI へのフォールバック

新しい CLI では、次のようなワークスペースのメタデータコマンドを利用できます。

draft workspace status --json
draft workspace path --json
draft workspace set-path <folder> --json

これらのコマンドが利用できない場合は、その状態を一度検出して安全にフォールバックしてください。

draft workspace --help
draft --workspace-json <folder> page ls --json

• draft workspace --help または draft workspace status --json が未知のコマンドに類するエラーで失敗した場合は、CLI が古いものと判断してください。
• 古い CLI では、フォルダーを明示的に指定し、draft --workspace-json <folder> ... でページコマンドを実行してください。
• ユーザーがフォルダーを指定しておらず、CLI にワークスペースコマンドがない場合は、JSON Workspace のフォルダーパスを尋ねるか、CLI のアップグレードを依頼してください。

ページコマンド

JSON Workspace を対象とする場合は、明示的な draft page ... コマンドを優先してください。移行期間中は、コマンドが誤って従来のヘッドレスストレージを対象にしないよう、--workspace-json <folder> を指定してください。

draft --workspace-json <folder> page ls --json
draft --workspace-json <folder> page search "phrase" --json
draft --workspace-json <folder> page cat <page_id> --json
draft --workspace-json <folder> page create "Title" --json
draft --workspace-json <folder> page append <page_id> "More content" --json
draft --workspace-json <folder> page replace <page_id> --heading "Status" "Updated body" --json
draft --workspace-json <folder> page patch <page_id> --json < change.diff
draft --workspace-json <folder> page annotate <page_id> --anchor "exact text" --note "Reviewer note" --json
draft --workspace-json <folder> page comments <page_id> --json
draft --workspace-json <folder> page comment <comment_id> <page_id> --json
draft --workspace-json <folder> page insert-image <page_id> ./image.png --json
draft --workspace-json <folder> page update-image <page_id> <local_id> --width 320 --json
draft --workspace-json <folder> page delete-image <page_id> <local_id> --json
draft --workspace-json <folder> page publish <page_id> --json

エージェント向けの読み取りガイダンス

• 人による確認を目的としたページのレンダリング済み読み取りには、draft --workspace-json <folder> page cat <page_id> を優先してください。Markdown の表示形式は、pages/*.json から手動でレンダリングするよりも、リンク、マーク、テーブル、画像、番号付きリスト、改行、カスタムブロックを適切に保持します。
• 解析や自動化のために構造化されたブロックデータが必要な場合に限り、draft --workspace-json <folder> page cat <page_id> --json を使用してください。出力は Markdown の読み取り形式より大きくなります。
• ワークスペースの生の JSON ファイルは、復旧や低レベルの調査が必要な場合の最終手段として扱い、通常の読み取り方法としては使用しないでください。
• 検索には、CLI が対応している場合、draft --workspace-json <folder> page search "phrase" --json を優先してください。ページ検索に対応していない古い CLI では、候補となるページ ID やタイトルの検出に限り、rg でワークスペースのページファイルを検索してください。その後、正確なレンダリング結果を得るために、draft --workspace-json <folder> page cat <page_id> に戻ってください。

パッチの契約

draft page patch は、ページ本文の Markdown のみに統一差分を適用します。Title:、ID:、または --- の区切り行を含む装飾済みの page cat 出力からパッチを生成しないでください。また、page cat --json のブロック出力からもパッチを生成しないでください。

パッチのワークフロー：

draft --workspace-json <folder> page cat <page_id>
# Extract only the body markdown, build a unified diff against that body, then:
draft --workspace-json <folder> page patch <page_id> --json < change.diff
draft --workspace-json <folder> page cat <page_id> --json

編集したテキストに依存する後続コマンド（page annotate --anchor "new text" など）を実行する前に、パッチの出力または続けて実行する page cat を確認してください。パッチで PATCH_MISMATCH が返された場合は、現在のページ本文の Markdown を再度読み込み、その本文と完全に一致する表示内容を基に新しい差分を生成してから再試行してください。

画像変更の契約

draft page insert-image は local_id を返します。後続の update-image コマンドおよび delete-image コマンドには、返された local_id を使用してください。page cat --json の互換出力では、同じ識別子が画像ブロックの id として示されます。

互換性維持期間中はトップレベルのページエイリアスも引き続き存在する場合がありますが、エージェントは draft page ... 名前空間を使用してください。

公開プレビューのフィードバック

公開 Draft のプレビュー URL と公開済み URL では、JSON Workspace のページコマンドではなく、公開ページ上でレビューのフィードバックを確認できます。公開レビューのワークフローでは、公開プレビュー URL または公開済み URL を、機械で読み取り可能な主要なエントリーポイントとして扱ってください。タスクが公開プレビュー URL または公開済み URL から始まる場合は、まずその公開 URL を取得し、メタデータ／フロントマターを解析してから、返されたエンドポイントを優先順位に従って使用してください。

この公開ページからフィードバックを直接読み取る方法では、draft、draft workspace status、draft status、JSON Workspace フォルダー、デーモン、ブラウザーとのペアリングは必要ありません。ユーザーが公開 URL を指定したという理由だけで、draft --workspace-json <folder> page comments <page_id> --json を実行しないでください。

「この公開 Draft プレビュー URL からフィードバックを読み取る」場合の例：

1. 指定された公開プレビュー URL または公開済み URL を取得します。
2. メタデータ／フロントマターを解析し、comments_api_url と task_toggles_api_url を P0 エンドポイントとして読み取ります。
3. comments_api_url を直接取得し、人間からのフィードバックとコメントを読み取ります。
4. task_toggles_api_url を直接取得し、レビューのトグル状態とタスクの判断を読み取ります。
5. source_snapshot_url がある場合は、公開済みコンテンツの構造化されたスナップショット（P1、任意）として扱い、コメントとトグルを公開済みの正確な本文に対応付ける際に役立てます。
6. フィードバックと判断の状態を要約します。source_snapshot_url は、レビュー対象の公開済みコンテンツの特定に役立つ場合にのみ使用します。

公開レビューの読み取り時の取得順序：

1. 公開 URL を取得します。
2. メタデータ／フロントマターを解析します。
3. comments_api_url を取得します。
4. task_toggles_api_url を取得します。
5. 必要に応じて source_snapshot_url を取得します。
6. フィードバックと判断の状態を要約します。

JSON Workspace のコメントコマンドで、公開プレビュー URL または公開済み URL もあるページの結果が空の場合は、その公開 URL で comments_api_url と task_toggles_api_url を確認するまで、フィードバックや判断がないと結論付けないでください。

draft --workspace-json <folder> page comments <page_id> --json などの CLI コメントコマンドは、主にプライベートまたはローカルの Draft ページのワークフロー、ライブのワークスペースページ、ローカルのページ注釈に使用します。プレビュー URL または公開済み URL の公開レビューで、標準の方法として使用するものではありません。

書き込みと共有に関するガードレール

安全なデフォルトの動作は読み取り専用です。ユーザーが操作と対象を明示的に指定しない限り、書き込み／共有コマンドを実行しないでください。

• 書き込みコマンド：draft --workspace-json <folder> page create、draft --workspace-json <folder> page append、draft --workspace-json <folder> page replace、draft --workspace-json <folder> page patch、draft --workspace-json <folder> page annotate
• 共有コマンド：draft --workspace-json <folder> page publish、draft secret create

公開 URL または共有可能な URL を返す前に、コマンドの出力を確認し、要求された成果物であることを確かめてください。

Secret Share

Secret Share コマンドは、ホスト型／ローカル暗号化のヘルパー機能であり、ワークスペースの確認、draft status、draft start-server は必要ありません。

API キーを設定します：

draft auth set-key <secret-share-api-key>
draft auth status --json

Secret Share を作成します：

draft secret create --file docs/brief.md --expires 1h --json

Secret Share を読み取ります：

draft secret open '<secret_url_or_id>' --password "$DRAFT_SECRET_PASSWORD" --json

パスワードで保護された共有には --password を使用してください。DRAFT_SECRET_PASSWORD は、実行環境からすでに提供されている場合にのみ使用してください。

エラーハンドリング

• 不明な draft workspace ... コマンド：draft --workspace-json <folder> ... に切り替え、フォルダーが指定されていない場合はパスを尋ねます。
• 設定済みのワークスペースパスがない場合：デフォルトを設定したい場合は draft workspace set-path <folder> --json を使用し、単発のコマンドには draft --workspace-json <folder> ... を使用します。
• PAGE_NOT_FOUND：draft --workspace-json <folder> page ls --json を実行し、有効なページ ID を指定して再試行します。
• PATCH_MISMATCH：draft --workspace-json <folder> page cat <page_id> で再読み込みし、ページ本文の Markdown のみを抽出して、その本文に合わせてパッチを再生成してから再試行します。
• ANCHOR_NOT_FOUND：注釈を付ける前に現在のページを再読み込みします。失敗したパッチで作成されなかったテキストには注釈を付けないでください。
• Secret Share API キーがない場合：draft auth set-key、--api-key、または DRAFT_SECRET_SHARE_API_KEY を使用します。