pp-wavespeed

WaveSpeed — Printing Press コマンドライン

前提条件：CLI をインストールする

このスキルでは wavespeed-pp-cli バイナリを使用します。**このスキルのコマンドを実行する前に、CLI がインストールされていることを必ず確認してください。**インストールされていない場合は、先にインストールしてください。

1. Printing Press インストーラーでインストールします。バイナリのインストール先は、macOS/Linux では $HOME/.local/bin、Windows では %LOCALAPPDATA%\Programs\PrintingPress\bin がデフォルトです。

   npx -y @mvanhorn/printing-press-library install wavespeed --cli-only
   

2. 確認します：wavespeed-pp-cli --version
3. スキルを実行するエージェント／ランタイムから、表示されたインストール先に $PATH が通っていることを確認します。

npx によるインストールに失敗した場合（Node がない、オフラインなど）は、Go から直接インストールしてください（Go 1.26.6 以降が必要です）。インストール先は $GOPATH/bin（デフォルトは $HOME/go/bin）なので、代わりにこのディレクトリに $PATH を通してください。

go install github.com/mvanhorn/printing-press-library/library/ai/wavespeed/cmd/wavespeed-pp-cli@latest

インストール後に --version で「command not found」と表示される場合、ランタイムから $PATH 上のバイナリディレクトリが見えていません。確認が完了するまで、スキルのコマンドを実行しないでください。

WaveSpeed は、画像、動画、音声、3D モデルを単一の API で提供しています。この CLI は、スラッシュ区切りのモデル ID に対応する動的なモデルランナー、無料の料金見積もり、ローカルファイルのアップロード、コストレポート付きの生成ライブラリ、D2C コンテンツレイヤー（plan、pack、batch、variants、compose、aspects、restyle、brand、qa）を追加します。有料の送信が再実行されることはなく、送信後に失敗した場合も、予測 ID と復旧コマンドが必ず保持されます。

この CLI を使う場面

スクリプトやエージェントから WaveSpeed のモデルを使って画像や動画を生成または編集するには、この CLI を使用してください。料金の確認、参照ファイルのアップロード、モデルの実行と待機・ダウンロード、生成物とそのコストのローカル記録ができます。複数のプラットフォーム向けに D2C コンテンツを制作する場合は、plan／pack／batch コマンドを使用してください。

使用しない場面

次の用途には、この CLI を使用しないでください。

• モデルのトレーニングまたはファインチューニング
• 独自のモデルのホスティングまたは提供

独自の機能

これらの機能は、この API のほかのツールでは利用できません。

コア

• run — WaveSpeed モデルの実行を送信します。プロンプトの省略記法、型指定された --set 入力、ローカルの @file メディアアップロード、料金見積もり、待機、復旧に安全なダウンロード、ライブラリへの記録に対応しています。

  単一の生成にはすべてこのコマンドを使います。送信後に失敗した場合も、予測 ID と復旧コマンドは保持されます。

  wavespeed-pp-cli run --model-id google/nano-banana-2/edit --prompt "a red mug on oak" --images @ref.png --set aspect_ratio=9:16 --wait --download 'out/mug_{index}.{ext}' --agent
  

• schema — WaveSpeed の最新モデルカタログを取得し、モデルまたはプロジェクトのエイリアスに対するリクエストスキーマを表示します。

  有料の実行前に、受け付けられる入力と列挙値を確認できます。

  wavespeed-pp-cli schema google/nano-banana-2/edit --agent
  

• price — 予測を送信せずに、run と同じ入力構文を使って WaveSpeed モデルの料金を見積もります。

  無料で利用でき、支出前にコストを確認できます。

  wavespeed-pp-cli price --model-id google/nano-banana-2/edit --set aspect_ratio=9:16 --set resolution=2k --agent
  

• aliases — 繰り返し可能なローカルワークフローのために、wavespeed.json のエイリアス、デフォルトモデル、出力ディレクトリの設定を確認します。

  どの短縮名がどのモデルに対応しているか確認できます。

  wavespeed-pp-cli aliases --agent
  

• init — エイリアス、デフォルトモデル、出力ディレクトリを含む、初期設定用の wavespeed.json を作成します。

  新しい画像プロジェクトを始められます。

  wavespeed-pp-cli init
  

メディア

• upload — ローカルの画像、動画、音声ファイルを WaveSpeed のメディアストレージにアップロードし、モデル入力用の URL にします。アップロードが停滞した場合は、ファイルサイズに応じた制限時間で再試行します。

  ローカルファイルを、モデルが受け付ける URL に変換できます。

  wavespeed-pp-cli upload ./ref.png --agent
  

• download — 生成された出力 URL から、ディレクトリ、正確なパス、またはテンプレートパスで指定した保存先にダウンロードします。API 認証情報が CDN ホストに送信されることはありません。

  完了した予測の出力を再取得できます。

  wavespeed-pp-cli download "$OUTPUT_URL" --output 'out/{index}.{ext}'
  

• last — 最も最近ダウンロードした出力を表示するか、開きます。

  最後に生成されたファイルのパスを取得できます。

  wavespeed-pp-cli last
  

計画

• plan brief-to-shotlist — 自由記述のブリーフを、ハイブリッド型の決定論的パーサー／LLMプランナーを使って、複数のプラットフォームとアスペクト比に対応した構造化ショットリストに変換します。

  キャンペーンのショットリストを作成します。

  wavespeed-pp-cli plan brief-to-shotlist --prompt "Helm Black launch" --platforms instagram,tiktok --agent
  

• plan model-pick — 最新のカタログから、目的に合ったモデルを理由とともに推薦します。

  作業に適したモデルを選びます。

  wavespeed-pp-cli plan model-pick "short product video" --agent
  

• plan cost-estimate — 最新の /model/pricing とアカウント残高をもとにショットリストの料金を算出します。キャッシュされた料金へのフォールバックと、ショットごとの内訳にも対応します。

  ショットリストが予算内に収まるか確認します。

  wavespeed-pp-cli plan cost-estimate shotlist.json --agent
  

• qa preflight — ショットリストについて、残高と料金、モデルの利用可否、プロンプトの安全性、プラットフォームのリクエスト形式、ブランドのカバー範囲を検証し、合格／警告／失敗を判定します。

  パックの生成前にチェックします。

  wavespeed-pp-cli qa preflight shotlist.json --agent
  

生成

• pack — 1つのコンセプトから、複数のプラットフォーム向けクリエイティブパックを、一定の packs/// パスに生成します。プラットフォームごとのマニフェスト、並行処理、コスト上限、画像サイズの検証に対応し、再実行時には置き換えられたマニフェストをアーカイブします。

  プラットフォーム対応アセットを生成します。

  wavespeed-pp-cli pack --concept "Helm Black hero" --platforms instagram,tiktok --max-cost 5.00 --agent
  

• batch — CSV または JSON から多数のプロンプトを送信します。支出上限と、失敗時に即時停止／処理を続行するセマンティクスに対応し、中止前に完了した生成結果を記録します。

  予算内でプロンプトのリストを実行します。

  wavespeed-pp-cli batch --from prompts.csv --max-cost 5.00 --agent
  

• variants — ベースとなるショットからシード、スタイル、またはモデルを変えて出力を生成し、メタデータを並べて比較できるようにします。

  1つのショットでシードやモデルを試します。

  wavespeed-pp-cli variants --base shotlist.json --vary seed --count 4 --agent
  

• compose — 明示的な複数ステップのパイプライン（テキスト->画像->アップスケール->動画）を実行し、各ステップの出力を次のステップに渡します。失敗時には、後続のステップをロールバックします。

  プロンプトから画像を作成し、続けて動画クリップを生成します。

  wavespeed-pp-cli compose --steps "text->image,image->video" --prompt "..." --models m1,m2 --agent
  

調整

• aspects — 1枚の画像を標準的なプラットフォームのアスペクト比に合わせて再フレーミングします。対応している場合はアウトペイントを使い、それ以外の場合は被写体の位置を維持して再レンダリングします。

  メイン画像の9:16版と1:1版を作成します。

  wavespeed-pp-cli aspects hero.png --platforms instagram,tiktok --agent
  

• restyle — スタイルプロンプトを使った img2img により、既存のアセットにブランドプロファイルまたは明示的なスタイルを適用します。

  アセットをブランドイメージに合わせます。

  wavespeed-pp-cli restyle hero.png --brand helm --agent
  

ライブラリ

• library — ローカルの生成ライブラリを、ブランド、モデル、プラットフォーム、タグで一覧表示、検索（FTS5）、表示、タグ付け、エクスポートし、コストレポートを作成します。

  過去の生成結果や総支出を確認します。

  wavespeed-pp-cli library cost-report --group-by model --agent
  

• brand — ブランドプロファイルを作成、確認、適用、編集します。プロファイルは pack、compose、variants、restyle、run に自動的にマージされます。

  一貫した出力のためにブランドを設定します。

  wavespeed-pp-cli brand init helm --palette '#111,#eee' --voice calm
  

コマンドリファレンス

account_balance — アカウント残高を管理します

• wavespeed-pp-cli account-balance — 認証済みアカウントの残高を取得します。

billings — 請求および使用状況の記録

• wavespeed-pp-cli billings — 認証済みアカウントの請求記録を検索します。

media_uploads — メディアのアップロードを管理します

• wavespeed-pp-cli media-uploads — 既存のローカルメディアファイル（画像、動画、音声）を1つ WaveSpeed ストレージにアップロードし、モデル入力用の URL を返します。

model_pricing — モデル料金を管理します

• wavespeed-pp-cli model-pricing — モデルエンドポイントに送信するものと同じ入力を使って、モデル実行の単価を見積もります。

models — モデルカタログとモデルのメタデータ

• wavespeed-pp-cli models — 利用可能な WaveSpeed モデルと API スキーマを一覧表示します。

prediction_deletions — 予測の削除を管理します

• wavespeed-pp-cli prediction-deletions — 履歴から1つ以上の予測を削除します。

prediction_results — 予測結果を管理します

• wavespeed-pp-cli prediction-results <task_id> — 予測タスクの最新のステータスと結果ペイロードを取得します。

predictions — 予測の送信履歴と結果の取得

• wavespeed-pp-cli predictions — 最近の予測履歴を検索します。API の履歴ウィンドウには制限があるため、sync により実行ごとに履歴が蓄積されます。

usage_stats — 使用統計を管理します

• wavespeed-pp-cli usage-stats — 認証済みアカウントの使用統計を取得します。

適切なコマンドを見つける

実行したいことは分かっているものの、どのコマンドを使えばよいか分からない場合は、CLI に直接問い合わせてください。

wavespeed-pp-cli which "<capability in your own words>"

which は、自然言語で指定した機能に関する問い合わせを、この CLI の厳選された機能インデックスから最も一致するコマンドに対応付けます。終了コード 0 は少なくとも 1 件一致したことを示し、終了コード 2 は確信を持って一致を判断できなかったことを示します。その場合は --help を確認するか、より絞り込んだ問い合わせをしてください。--json（およびその他の機械可読形式）でも終了コード 2 の仕様は変わらず、標準出力に {"matches":[]} が書き込まれるため、エージェントは見つからなかった結果を成功とみなさずに応答の形式を確認できます。

レシピ

参照画像を使った画像編集、9:16、2k

wavespeed-pp-cli run --model-id google/nano-banana-2/edit --prompt "$PROMPT" --images https://wavespeed.ai/anchor.png --set aspect_ratio=9:16 --set resolution=2k --wait --download 'raw/shot_{index}.{ext}' --record --agent

URL またはローカルの @file を渡してください。ローカルファイルは自動的にアップロードされます。ダウンロードテンプレートで各出力の名前を指定します。

最初と最後のフレームを指定した動画

wavespeed-pp-cli run --model-id bytedance/seedance-v1.5-pro/image-to-video --prompt "$MOTION" --image https://wavespeed.ai/a.jpg --last-image https://wavespeed.ai/b.jpg --set duration=5 --wait --wait-timeout 10m --download 'clip_{index}.{ext}' --record --agent

--wait-timeout でポーリング時間を制限できます。タイムアウト時には、予測 ID と復旧用コマンドが表示されます。

セッションの料金を確認する

wavespeed-pp-cli billings --page-size 20 --agent

請求行には、予測ごとに請求された料金が記載されます。

キャンペーンを計画する

wavespeed-pp-cli plan brief-to-shotlist --prompt "launch" --platforms instagram,tiktok --agent

ショットリストを保存した後、pack の前に plan cost-estimate と qa preflight を実行してください。

認証の設定

WaveSpeed では、Authorization: Bearer <key> として送信する API キーを使用します。https://wavespeed.ai/accesskey で API キーを作成し、WAVESPEED_API_KEY としてエクスポートしてください。doctor は無料の /balance 読み取りリクエストでキーを検証します。

wavespeed-pp-cli doctor を実行して設定を検証してください。

エージェントモード

任意のコマンドに --agent を追加してください。次のオプションに展開されます：--json --compact --no-input --no-color。

グローバルな形式指定フラグは、promoted、novel、sync、および --deliver の各パスで共通の仕様です。

• --json — 標準出力に 1 つの JSON ドキュメントを出力します（sync の進行状況イベントは標準エラー出力に出力されます）

• --compact — ID／状態／タイムスタンプの各フィールドを保持します。ドキュメント形式とストリーム形式は変更しません

• --csv / --plain — 表形式の行を出力します（コレクションのエンベロープは行の配列に展開されます）

• --quiet — エンベロープなしで、行ごとに 1 つの ID 値を出力します

• パイプに対応 — JSON は標準出力に、エラーは標準エラー出力に出力されます

• フィルタリング可能 — --select でフィールドを絞り込めます。ドット区切りのパスでネスト構造をたどり、配列内の各要素にも適用できます。詳細な API のコンテキストを小さく保つうえで重要です。

  wavespeed-pp-cli billings --agent --select code,data,message
  

• プレビュー可能 — --dry-run で、リクエストを送信せずに内容を確認できます

• オフラインでも利用可能 — sync／search コマンドは、利用可能な場合にローカルの SQLite ストアを使用できます

• 非対話型 — プロンプトは表示されず、入力はすべてフラグで指定します

• 明示的な確認 — --agent は --yes を暗黙に有効にしません。対象、引数、副作用が明確になった場合に限り、別途 --yes を指定してください

• 明示的な再試行 — すでに存在する項目の作成を成功として扱う場合に限り、--idempotent を使用してください

応答エンベロープ

ローカルストアまたは API から読み取るコマンドは、出力を出所情報のエンベロープで包みます。

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

データには .results を、ライブデータかローカルデータかの判定には .meta.source を解析してください。人間が読みやすい N results (live) の要約は、標準出力がターミナルで、かつ機械可読形式のフラグ（--json、--csv、--compact、--quiet、--plain、--select）が指定されていない場合にのみ標準エラー出力に表示されます。パイプ経由またはエージェントによる利用時、および形式を明示して実行した場合、標準出力には JSON のみが出力されます。

パスと状態

エージェントは、CLI のパスリゾルバーをランタイム契約の一部として扱ってください。

• 1 回の実行では --home <dir> を使用するか、WAVESPEED_HOME=<dir> を設定して、4 種類すべてのパスを 1 つのルート配下に移動します。

• 特定の種類のパスだけを変更する必要がある場合に限り、種類ごとの環境変数を使用します：WAVESPEED_CONFIG_DIR、WAVESPEED_DATA_DIR、WAVESPEED_STATE_DIR、WAVESPEED_CACHE_DIR。

• 解決の優先順位は、種類ごとの環境変数、--home、WAVESPEED_HOME、XDG（XDG_CONFIG_HOME、XDG_DATA_HOME、XDG_STATE_HOME、XDG_CACHE_HOME）、プラットフォームのデフォルトの順です。

• config には config.toml やプロファイルなどの設定が含まれます。data には credentials.toml、data.db、Cookie、認証用サイドカーが含まれます。state には永続化されたクエリ、ジョブ、teach.log が含まれます。cache には再生成可能な HTTP／キャッシュファイルが含まれます。

• 保存されたシークレットは、data ディレクトリ内の credentials.toml に格納されます。既存のレガシーな config.toml 内のシークレットは互換性のため読み込まれ、最初の認証書き込み時に config.toml から削除されます。

• wavespeed-pp-cli doctor --fail-on warn を実行して、パスや認証情報の保存場所に関する警告を表示します。解決済みディレクトリを必要とするエージェントには、agent-context が schema v4 の paths ブロックを提供します。

• MCP では、MCP ホストの設定を通じて移動先を指定します。MCP バイナリは CLI フラグを継承しません。

  {
    "mcpServers": {
      "wavespeed": {
        "command": "wavespeed-pp-mcp",
        "env": {
          "WAVESPEED_HOME": "/srv/wavespeed"
        }
      }
    }
  }
  

フリートでの優先順位：引き継がれた種類ごとの環境変数は、その種類について明示的な --home より優先されます。フリート全体に適用する設定には WAVESPEED_HOME または種類ごとの環境変数を使用し、--home は 1 回の実行に限って使用してください。環境変数の設定を解除しても、移動は元に戻りません。WAVESPEED_HOME を解除する前に手動でファイルを移動してください。そうしないと、doctor は以前のルートに残された認証情報を見つけられません。

自動学習

この CLI には、自動記録型の学習ループが組み込まれています。CLI は独自に記録を管理します。すべての実行がローカルに記録され、フラグを誤って指定した後に修正して再試行すると flag_alias 候補が自動で導出され、プレイブックのないクエリファミリーに対して teach を実行すると、セッションの記録から playbook_candidate が自動生成されます。あなたが行うのは判断だけです。まず recall を実行し、提示された候補に基づいて操作し、最終的な回答を teach で教え、修正に気づいたら playbook amend を実行します。失敗を手作業で記録する必要はありません。

ステップ 1：探索の前に recall を実行する

新しいユーザーの質問に対して list／search／drill コマンドを実行する前に、その質問を argv または MCP ツールの引数として recall --agent に渡してください。ユーザーが指定したテキストをシェルコマンドラインに埋め込まないでください。

引用符で囲んだ recall "<question>" は、通常の英語に含まれるアポストロフィがあると失敗します。引用符付きのヒアドキュメントは、本文の行が区切り文字と一致すると失敗します。また、その区切り文字はこのドキュメントで公開されています。シェルを使わないファイル書き込みツールで質問を書き込み、データとして読み戻してください。

# Write the question verbatim with your file-writing tool (no shell involved).
# Command substitution on a file only ever yields data — the shell never
# parses the file's bytes as syntax.
QUERY=$(cat /path/to/question.txt)
wavespeed-pp-cli recall "$QUERY" --agent

MCP を優先してください。質問はツールのクエリ引数として渡します。ファイルを読み込んだ後の "$QUERY" は argv として安全ですが、質問自体をコマンドテキストに含めるのは安全ではありません。

レスポンスのエンベロープ：

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "wavespeed-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

空ストアの場合のショートカット：ストアに学習内容、プレイブック、候補がまだなく（recall で何も見つからず、learnings list と learnings candidates の両方が空の場合）、このセッションの残りでは、クエリごとに負荷をかけないよう recall をスキップします。何かを教えたら、再び recall を最初に実行してください。

ステップ 2：判断ツリー

candidates、playbook、notes、results[0]、警告の順に読みます。

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `wavespeed-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook と Notes は、リソースごとのパスとは独立しています。recall の応答には Playbook と Results[] のヒットの両方が含まれる場合があります。両方を活用してください。Playbook は実行する手順を示し、リソースのヒットは特定のステップを省略できるようにします。デフォルトでは mismatches をスキップしてください。コールドスタート時の予期しない動作を調査する場合に限り、--debug-mismatches を渡します。

候補の判断に関する詳細：learnings confirm <id> は候補を具体化する前に、その完全なペイロードを出力します。出力されたペイロードが、確認済みの動作と一致することを確認してください。learnings reject <id> は導出シグネチャを無効化し、同じ候補が再び表示されないようにします。エンベロープには、今対処する価値のある少数の候補だけが含まれます。wavespeed-pp-cli learnings candidates では、未処理の候補をすべて一覧表示できます。

グレースフルデグラデーション：learnings confirm が不明なコマンドの場合は、古いバイナリを使用しています。候補に関するガイダンスは無視し、残りのプロトコルに従ってください。

ステップ 3：必ず warnings を読む

• low_confidence：confidence<2 の行が存在します。スキップ可能な発見結果ではなく、ヒントとして扱ってください。
• resource_not_in_store：ローカルストアに、学習内容が参照するリソースがありません。一致検証でエンティティを分類できなかったため、直接取得して再評価してください。
• cross_alias_match（結果ごと）：行は別のエイリアスで登録されましたが、entity_lookups を介して、ライブクエリの正規名と一致しました（例：「USA」での登録が、「United States」の recall を満たす場合）。resource_id を信頼してください。
• similar_shape_different_entity:<canonical>（トップレベル）：構造的に一致する行は存在しますが、その正規エンティティはライブクエリのエンティティと異なります。コールドスタートとして扱います。警告にはヒントとして競合する正規名が含まれますが、その行は Results に昇格されません。
• ambiguous_alias（トップレベル）：単一のクエリエンティティが複数の正規名に解決されました（例：「Cards」→ Arizona Cardinals + St. Louis Cardinals）。リソースを確定する前に、コンテキストから曖昧さを明らかにしてください。
• candidates_present（トップレベル）：エンベロープに candidates セクションが含まれています。それ以外のことを行う前に、ステップ 2 の候補分岐に従って処理してください。
• lookup_refresh_available（トップレベル）：クエリ内のエンティティに lookup 行がまだありませんが、同期済みデータから作成できる可能性があります。wavespeed-pp-cli sync を実行して、エンティティの lookup を更新してください。
• トップレベルの no_learnings_for_query_family：テーブルに Jaccard の下限を超える行がありません。完全なコールドスタートです。

ステップ 4：回答を確定したら、必ず teach & を実行する

Teaching は無条件です。ストアで回答できなかったクエリを解決した後、最終的なリソースの対応関係をバックグラウンドで教えてください。呼び出し回数のしきい値はなく、学習する「価値」があったかどうかを判断する必要もありません。teach はこのループの要です。プレイブックがないファミリーではプレイブックの合成が開始され、同じ対象を指す表現はひとつのファミリーに統合されるため、ほぼ重複する teach によってストアが断片化することはありません。ユーザー向けの回答を組み立てた後、出力する前に、シェルの & を付けて実行し、呼び出しがすぐに返るようにしてください。クエリは recall と同じ方法で渡します — argv/MCP、またはファイル経由で $QUERY を使います。質問をコマンドテキストに挿入しないでください。

QUERY=$(cat /path/to/question.txt)
wavespeed-pp-cli teach --query "$QUERY" --resource-type <type> --resource <id1> --resource <id2>
# (append shell `&` to background it)

成功時は何も出力されません。エラーは、解決済みの state dir にある teach.log にのみ記録されます。最も具体的なリソースを teach してください。ユーザーが広範な質問をして、具体的な回答を見つけるために親レコードをたどった場合は、親ではなくリーフ ID を teach してください。CLI は recall 時のエイリアス間の解決にシード済みの entity_lookups を使うため、あるエイリアス（例：「Niners」）で teach すれば、別のエイリアス（例：「49ers」、「San Francisco」）を使った今後のクエリにも自動的に対応します。

PII に関するルール：識別子を取り除いた構造的な質問を teach してください。teach するクエリやメモには、名前、メールアドレス、電話番号、アカウント ID、その他の個人識別情報を決して含めないでください。CLI は teach クエリをスキャンし、明らかなメールアドレスや電話番号の形式を検出すると警告しますが、処理をブロックするわけではありません。警告に頼らず、teach の前に取り除いてください。

ステップ 5：プレイブック — フラグは任意、自動合成

セッションにプレイブックを作る「価値」があるかどうかを判断する必要はありません。プレイブックがないファミリーに対して teach を行うと、セッションのジャーナルから playbook_candidate が自動合成され、次のセッションで confirm/reject による評価が行われます。記録に値する手順をすでに把握している場合にのみ、明示的なプレイブックのフラグを付けてください。たとえば、CLI が表面化しなかった回避策（無言で破棄されるフラグ、文書化されていないパラメーター、ページネーションの工夫、ペイロードの注意点）です。統合された 1 回の呼び出し形式を優先してください。リソースに関する学びとプレイブックを、同じ teach 呼び出しで記録します。

# Common case: record both the resource learning AND the playbook in one call.
QUERY=$(cat /path/to/question.txt)
wavespeed-pp-cli teach \
  --query "$QUERY" \
  --resource <id> \
  --playbook-file ~/playbooks/<shape>.json \
  --playbook-notes-file ~/playbooks/<shape>-notes.md
# (append shell `&` to background it)

# Alternate: playbook-only (no resource to record alongside).
QUERY=$(cat /path/to/question.txt)
wavespeed-pp-cli teach-playbook \
  --query "$QUERY" \
  --playbook-file ~/playbooks/<shape>.json \
  --notes-file ~/playbooks/<shape>-notes.md

プレイブックファイルは、steps、entity_slots、expected_tool_calls を含む JSON 形式です。メモファイルは、注意点をそのまま記載する Markdown 形式です。ファイルを扱わない呼び出し元（MCP 専用エージェント）は、統合形式の teach では --playbook-json と --playbook-notes を、teach-playbook では --playbook-json と --notes を使って、同じ内容をインラインで渡します。統合形式の teach ではプレイブックのフラグは任意です。リソースのみを teach する場合は、フラグをすべて省略してください。単独形式の teach-playbook では、プレイブックとメモのフラグのうち、少なくともひとつを設定する必要があります。両方が空の場合は拒否されます。プレイブックは構造的なクエリファミリー（エンティティを除去したもの）にひも付けられるため、あるエンティティ形式のクエリから teach された手順は、同じ形式の他のすべてのクエリに適用されます。その際、slots_resolved が recall 時にライブクエリの正規形をバインドします。

今後の recall でプレイブックが見つかった場合は、それを正解として扱ってください。slots_resolved による置換を適用して手順を再実行し、手順ですでに説明されている探索は省略して、どの手順を実行するよりも前に notes を読んでください。

ステップ 6：デバッグの応答で修正点が見つかったら playbook amend &

デバッグプロトコルへの応答で、メモやプレイブックに反映すべき具体的な修正点（回避策、ドキュメントに記載されていないエンドポイントの形式、古いフィールド名、確認されたスキーマの変化、空のペイロードに対するフォールバックなど）が見つかった場合は、ユーザー向けの応答を出す前に playbook amend を実行してください。teach と同じく、実行結果を待たずに呼び出します。クエリとメモは argv／MCP 引数として渡すか、シェルを介さないファイルツールでそれぞれ書き込み、読み戻してください（QUERY=$(cat ...)、NOTE=$(cat ...)）。どちらの文字列もコマンドテキストに埋め込まないでください。

QUERY=$(cat /path/to/question.txt)
NOTE=$(cat /path/to/note.txt)
wavespeed-pp-cli playbook amend \
  --query "$QUERY" \
  --add-note "$NOTE"
# (append shell `&` to background it)

修正する価値があるもの：このセッション中に観察した挙動のうち、将来の自分が知っておくと役立つものです。修正する価値がある例：

• CLI のインターフェースで、フラグが無言で削除されたり、順序が入れ替わったりする場合の回避策。
• ドキュメントに記載されていないエンドポイントの形式（レスポンスが {meta, results} でラップされる、ペイロードがドキュメントの説明より 2 階層深くネストされているなど）。
• 確認されたスキーマの変化（フィールド名の変更、シーズン間でのインデックスの移動、API が返すカテゴリラベルの小文字化など）。

メモに含めるべきでないもの：

• ユーザーの質問に対する、特定の年やエンティティに関する回答。それは学びではなく、応答です。
• プレイブックが実行時にすでに取得している、チーム別／アスリート別／行別のデータ。
• 既存のメモの内容を言い換えただけの記述。

amend コマンドは、ファミリーの既存のメモにタイムスタンプ付きのマーカー（[amend YYYY-MM-DDTHH:MMZ]: <text>）を付けて追記します。複数の amend が蓄積され、監査履歴を確認できます。ファミリーのプレイブックがまだ存在しない場合、amend はメモのみのプレイブックを作成するため、コールドスタート時の修正も反映されます。

amend メモにおける PII の取り扱い

playbook amend のメモは、Printing Press の将来のバージョンで共有知識として上流に送られる可能性があります。遡及的な情報削除なしに上流への提供を続けられるよう、ユーザーを特定できる情報を含めないでください。

• 埋め込まないでください：ユーザーのファイルシステム上のパス、個人用 API キーやトークン、ユーザーのメールアドレス、ユーザーの GitHub ハンドル、または特定のユーザーに結び付いた具体的なクエリ履歴。
• 含めても問題ありません：エンドポイントの形式、ドキュメントに記載されていないフィールド名、API の注意点、確認されたスキーマの変化、CLI のインターフェースに対する回避策、汎用的なページネーションや再試行の方法。

修正点がユーザー固有のコンテキストでしか意味をなさない場合は、プレイブック amend ではなく個人用メモに記録してください。

ループの測定

wavespeed-pp-cli learnings stats は、ローカルの learn_events テーブルから、再現率、teach から再利用への移行率、プレイブックの解決率、候補の確認／却下件数を報告します。分母がない間、率は null です。すべてのデータはこのマシン上に保持されます。この CLI でループが効果を発揮しているかを確認するために使用してください。

学習の無効化

• 単一のコマンドに --no-learn を指定すると、recall と teach の書き込み処理の両方が短絡されます。蓄積した学習内容の影響を受けてはならない、決定論的なエージェントのフローやテストに使用してください。
• 環境変数に WAVESPEED_NO_LEARN=true を設定すると、パイプライン全体が無効になります。

エージェントへのフィードバック

この CLI に問題があると（あなたやエージェントが）気付いたら、記録してください。

wavespeed-pp-cli feedback "the --since flag is inclusive but docs say exclusive"
wavespeed-pp-cli feedback --stdin < notes.txt
wavespeed-pp-cli feedback list --json --limit 10

エントリは、解決済みのデータディレクトリにある feedback.jsonl にローカル保存されます。WAVESPEED_FEEDBACK_ENDPOINT が設定され、さらに --send が渡されているか、WAVESPEED_FEEDBACK_AUTO_SEND=true が設定されていない限り、POST されることはありません。デフォルトの動作はローカルのみです。

バグ報告ではなく、意外だったことを書いてください。短く、具体的に、1 行で。それが積み重なって価値になります。

出力の配信

すべてのコマンドで --deliver <sink> を指定できます。出力は標準出力への出力に加えて（または標準出力の代わりに）、指定したシンクに送られるため、エージェントはコマンド結果を手動でパイプに渡さずにルーティングできます。サポートされているシンクは 3 つです。

シンク	効果
stdout	デフォルト。標準出力のみに書き込みます
file:<path>	出力を <path> にアトミックに書き込みます（一時ファイルを作成してから名前を変更）。バイナリ応答を返すコマンドは、デコード済みのペイロードバイト（base64 の JSON エンベロープではありません）を書き込み、標準出力には簡潔な JSON レシートを出力します。このシンクが設定されている場合、--json／--csv は拒否されません。
webhook:<url>	出力本文を URL に POST します（application/json）

不明なスキームは、サポート対象のスキームを示す構造化エラーとともに拒否されます。Webhook の失敗時はゼロ以外の終了コードを返し、URL と HTTP ステータスを標準エラー出力に記録します。

名前付きプロファイル

プロファイルは、フラグ値を保存したセットであり、呼び出しをまたいで再利用できます。スケジュール実行または定期実行するエージェントが、実行ごとに異なる入力を受け取りつつ、同じ保存済みフラグを再利用する場合に使用します。

wavespeed-pp-cli profile save briefing --json
wavespeed-pp-cli --profile briefing billings
wavespeed-pp-cli profile list --json
wavespeed-pp-cli profile show briefing
wavespeed-pp-cli profile delete briefing --yes

明示的に指定されたフラグは常にプロファイル値より優先され、プロファイル値はデフォルトより優先されます。agent-context は、すべての使用可能なプロファイルを available_profiles に一覧表示するため、イントロスペクションを行うエージェントは実行時にプロファイルを検出できます。

終了コード

コード	意味
0	成功
2	使用方法エラー（引数が誤っています）
3	リソースが見つかりません
4	認証が必要です
5	API エラー（上流の問題）
7	レート制限中（待機して再試行してください）
10	設定エラー

引数の解析

$ARGUMENTS を解析します。

1. 空、help、または --help → wavespeed-pp-cli --help の出力を表示します
2. install で始まる → mcp で終わる場合は MCP のインストール、それ以外の場合は上記の前提条件を参照します
3. それ以外 → 直接使用（--agent を付けて CLI コマンドとして実行します）

MCP サーバーのインストール

1. MCP サーバーをインストールします：

   go install github.com/mvanhorn/printing-press-library/library/ai/wavespeed/cmd/wavespeed-pp-mcp@latest
   

2. Claude Code に登録します：

   claude mcp add wavespeed-pp-mcp -- wavespeed-pp-mcp
   

3. 確認します：claude mcp list

直接使用

1. インストールされているか確認します：which wavespeed-pp-cli 見つからない場合は、インストールを提案します（このスキルの冒頭にある前提条件を参照してください）。
2. ユーザーのクエリに最適なコマンドを、上記の独自機能とコマンドリファレンスから選びます。
3. --agent フラグを付けて実行します：

   wavespeed-pp-cli <command> [subcommand] [args] --agent
   

4. あいまいな場合は、サブコマンドのヘルプを確認します：wavespeed-pp-cli <command> --help。