sn-ppt-workbench

sn-ppt-workbench

既存の HTML スライドデッキ向けに、AI PPT 編集用 WebUI を起動するか、既存のものを再利用します。利用可能な場合、ヘルパーは Hermes／canvas／ポートフォワーディングの URL を優先します。フォワーディングされた URL がない場合、ネイティブホストはデフォルトで localhost にバインドし、Docker／WSL は 0.0.0.0 にバインドして、ホストネットワーク経由でリモートユーザーが WebUI にアクセスできるようにします。

ユースケース

• ユーザーがすでにデッキを生成しており、WebUI／エディター／ワークベンチを開くよう依頼している。
• ユーザーが task_pack.json、slides/slide_NN.html、pages/page_NNN.html、またはルートレベルの HTML デッキを含む deck_dir を指定している。
• ユーザーが、スライドを再生成せずに以前生成したスライドを確認または編集するよう依頼している。

厳守事項

1. sn-ppt-entry、sn-ppt-standard、page-html、batch-page-html、または export を実行しないでください。
2. スライドファイルを直接編集しないでください。ユーザーに表示される編集は WebUI で行います。
3. deck_dir が見つからない場合は、$(pwd)/ppt_decks の下だけを自動検出してください。 呼び出し元が明示的に --search-root を渡した場合に限り、ほかのルートも対象にしてください。デフォルトではホームフォルダーをスキャンしないでください。
4. 使用可能なデッキが見つからない場合は、ユーザーに絶対パスの deck_dir を尋ねてください。
5. ワークベンチの起動はベストエフォートです。スキップまたは失敗した場合は理由を報告し、代替手段として生成を試みないでください。
6. ユーザーが SSH、IM、または別のリモートデバイスを利用している可能性がある場合は、localhost よりフォワーディング／canvas の URL を優先してください。
7. 統合 PPT フローから起動した場合は、正確な絶対パス task_pack.deck_dir を使用してください。ワークベンチを開くことでタスクを新規作成したり、切り替えたりしてはいけません。
8. task_pack.json は進捗／再開状態として、outline.md はユーザーが編集可能な Story として扱ってください。既存のランタイムビルドでは、これらのアーティファクトの一部しか公開されない場合があります。デッキを再生成するのではなく、互換性の不足を報告してください。

呼び出し方法

ヘルパーを直接使用します。

python3 $SKILL_DIR/scripts/open_workbench.py --deck-dir "<deck_dir>" --agent-session-id "${HERMES_SESSION_KEY:-}"

python3 が使用できないネイティブ Windows の場合：

python $SKILL_DIR/scripts/open_workbench.py --deck-dir "<deck_dir>" --agent-session-id "%HERMES_SESSION_KEY%"

ユーザーがデッキのパスを指定していない場合は、ヘルパーに自動検出させます。

python3 $SKILL_DIR/scripts/open_workbench.py --agent-session-id "${HERMES_SESSION_KEY:-}"

利用可能な場合は、同一セッションのブリッジ情報を渡します。

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-session-id "${HERMES_SESSION_KEY:-}" \
  --agent-managed 1 \
  --agent-provider hermes \
  --agent-transport gateway \
  --webui-base-url "${HERMES_WEBUI_BASE_URL:-}" \
  --gateway-base-url "${HERMES_GATEWAY_BASE_URL:-}"

--agent-transport は省略できます。ヘルパーは、Hermes Gateway のエンドポイントとキーを環境変数または Hermes の .env ファイルから解決できる場合は gateway を自動選択し、それらの情報だけが存在する場合は webui／acp／rest を選択します。明示的なフラグと WORKBENCH_AGENT_TRANSPORT は常に優先されます。解決可能なブリッジがない場合、設計上、下部のチャットは読み取り専用のままになります。

Hermes 以外の対話型プロバイダーでは、CLI／TUI の出力をスクレイピングするのではなく、構造化されたブリッジ情報を渡してください。

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-managed 1 \
  --agent-provider openclaw \
  --agent-transport rest \
  --agent-base-url "${WORKBENCH_AGENT_BASE_URL:-}" \
  --agent-api-key "${WORKBENCH_AGENT_API_KEY:-}"

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-managed 1 \
  --agent-provider codex \
  --agent-transport acp \
  --acp-command "${WORKBENCH_ACP_COMMAND:-codex-acp}"

python3 $SKILL_DIR/scripts/open_workbench.py \
  --deck-dir "<deck_dir>" \
  --agent-managed 1 \
  --agent-provider box-agent \
  --agent-transport acp \
  --acp-command "${WORKBENCH_ACP_COMMAND:-${BOX_AGENT_ACP_COMMAND:-box-agent-acp}}"

このヘルパーが Box Agent 内で実行される場合、エクスポートされた BOX_AGENT_PYTHON または BOX_AGENT_SKILL_TOOLS_ROOT 環境変数によって、box-agent、acp、およびインストール済みの box-agent-acp コマンドが自動的に選択されます。明示的な WORKBENCH_AGENT_* フラグまたは環境変数がある場合は、引き続きそちらが優先されます。

WorkBuddy を使用する場合は、プロバイダーの識別情報としてのみ --agent-provider workbuddy を渡してください。WorkBuddy には現在、対話型ワークベンチブリッジ用のサポート対象 API または ACP インターフェースがないため、WebUI で WorkBuddy の状態は表示できますが、下部のチャットから WorkBuddy に変更指示を送信することはできないと、ユーザーにはっきり伝えてください。

CLI サブコマンド（直接起動時のフォールバック）

open_workbench.py を介さず、ワークベンチランチャーを直接呼び出す場合は、サブコマンドを使用してください。

node <launcher> start   --deck-dir "<path>" [--port 0] [--agent-managed]
node <launcher> status  --deck-dir "<path>"
node <launcher> stop    --deck-dir "<path>"

古い引数のみの形式（サブコマンドなし）は非推奨です。使用方法エラーが表示されます。

再起動時の注意点： start は、同じ deck-dir の既存サーバーインスタンスを黙って再利用します（応答に "reused": true が含まれます）。ワークベンチのコードを更新した場合は、必ず最初に stop を実行してから start を実行してください。そうしないと、古いプロセスが古いコードを配信し続けます。

node <launcher> stop  --deck-dir "<path>"
node <launcher> start --deck-dir "<path>" --port 0

バインドホスト

ワークベンチは、--host CLI フラグ → WORKBENCH_HOST 環境変数 → デフォルトの 127.0.0.1 の順にバインドアドレスを決定します。ユーザーがリモート／LAN からのアクセスを必要とする場合は、WORKBENCH_HOST=0.0.0.0 を設定してください。

export WORKBENCH_HOST=0.0.0.0
node <launcher> start --deck-dir "<path>" --port 0

その場合、応答の url フィールドには 127.0.0.1 ではなく LAN IP が表示されます。

出力の処理

標準出力から単一の JSON 行を解析します。

status == "ok" の場合、既存のデッキを編集するリクエストでは、返された editor_url、public_url、または workbench.editorUrl をそのまま出力します。ヘルパーは generation_url を返すこともあります。この URL は /progress の生成進捗ページを示し、エディターは /editor です。

PPT 编辑工作台已启动：<editor_url>

workbench.reused == true の場合、既存のサーバーを再利用したことを伝えます。

bind_host が 0.0.0.0 の場合、その URL は Docker／WSL の LAN フォールバックです。ユーザーに、デバイス／ネットワークからアクセスできる必要があると伝えてください。アクセスできない場合は、Hermes／canvas／ポート転送 URL を提示して --public-url を付けて再実行するか、--host を付けて明示的なバインドホストを指定するよう依頼してください。

status == "skipped" または status == "failed" の場合、reason フィールドをそのまま出力します。reason == "nodejs_missing" の場合は、NodeJS／依存関係のインストールを希望するかユーザーに尋ねてください。希望しない場合は、WebUI を開かないでください。デッキが見つからなかったことが理由に示されている場合に限り、有効な deck_dir を尋ねてください。

環境

ヘルパーは次の順序でエディターの起動プログラムを探します。

1. SENSENOVA_PPT_WORKBENCH_CLI
2. PPT_WORKBENCH_CLI
3. この Skill と同じ場所にパッケージ化されたランタイム
4. 現在の作業ツリー内で最も近い src/ppt-editor のソースチェックアウトまたはパッケージ化されたリリース
5. よく使用される ~/Repository/ppt-editor のフォールバック

ヘルパーはエンドユーザーによる起動時にエディターをビルドしません。パッケージ化された Skill には workbench-runtime を含める必要があります。ソースチェックアウトでは、起動プログラムを使用する前に src/ppt-editor を明示的にビルドする必要があります。リポジトリレベルの webui/ ディレクトリは別の製品であり、この Skill の起動プログラムのフォールバックではありません。

リモート URL の検出順序：

1. 明示的に指定された --public-url
2. WORKBENCH_PUBLIC_URL、HERMES_WORKBENCH_PUBLIC_URL
3. HERMES_CANVAS_URL、HERMES_PORT_FORWARD_URL、CANVAS_URL、PORT_FORWARD_URL、TUNNEL_URL などの Hermes／canvas／転送用環境変数
4. Codespaces／Gitpod の URL パターン
5. ネイティブホストでは localhost、Docker／WSL ではマシンのループバック以外の IPv4 アドレスを使った LAN フォールバック

Gateway 認証の設定

書き込み可能な対話型エージェントのブリッジ（workbench のチャットパネル）には、Hermes は引き続き既存の WebUI／Gateway プロトコルを使用します。OpenClaw は Gateway／REST 互換の HTTP エンドポイントとして公開してください。Codex、Claude Code、Box Agent には ACP JSON-RPC アダプターを使用し、--acp-command または WORKBENCH_ACP_COMMAND で設定してください。Box Agent の既定値は、インストール済みの box-agent-acp エントリーポイントです。 チャット同期のためにプロバイダー CLI／TUI の出力を解析しないでください。

書き込み可能な Hermes Gateway ブリッジでは、Gateway API サーバーと workbench の認証に、一致する API キーを使用する必要があります。

主な環境変数：

変数	設定元	値
API_SERVER_KEY	Gateway（.env）	共有シークレット
WORKBENCH_GATEWAY_API_KEY	Workbench 環境	API_SERVER_KEY と同じ値。明示的なブリッジキーとして推奨
HERMES_GATEWAY_BASE_URL	Workbench 環境	http://127.0.0.1:8642
WORKBENCH_AGENT_PROVIDER	Workbench 環境	hermes、openclaw、codex、claude-code、box-agent、または workbuddy
WORKBENCH_AGENT_TRANSPORT	Workbench 環境	webui、gateway、rest、または acp
WORKBENCH_AGENT_BASE_URL	Workbench 環境	OpenClaw／Gateway の REST エンドポイント
WORKBENCH_AGENT_API_KEY	Workbench 環境	REST プロバイダーのベアラートークン
WORKBENCH_ACP_COMMAND	Workbench 環境	ACP アダプターコマンド。例：codex-acp
BOX_AGENT_ACP_COMMAND	Box Agent／Workbench 環境	既定の box-agent-acp アダプターコマンドを上書きする場合に指定

簡単な手順：

• Gateway：.env に API_SERVER_KEY を設定し、Gateway を再起動します
• Workbench：WORKBENCH_GATEWAY_API_KEY に同じ値を設定し、HERMES_GATEWAY_BASE_URL=http://127.0.0.1:8642 を設定します
• 明示的なブリッジキーが設定されていない場合、Node リレーは API_SERVER_KEY、HERMES_GATEWAY_API_KEY、次にバックエンド専用の AI_GATEWAY_API_KEY（既定値は ppt-editor-dev）の順にフォールバックします。カスタムまたは共有の Gateway では、明示的なブリッジキーを使用してください。

進捗の通知

ヘルパーの実行前と実行後に、短い進捗メッセージを必ず送信してください。

タイミング	例
ヘルパーの実行前	正在启动 PPT 预览工作台，不会重新生成幻灯片...
成功	PPT 编辑工作台已启动：http://127.0.0.1:18087
生成進捗 URL が利用可能な場合	生成进度工作台：http://127.0.0.1:18087/progress
スキップ／失敗	PPT 工作台未启动：<reason>