papercut-setup

Papercut のセットアップ

install.sh をラップしたガイド付きセットアップです。インストール済みのものを確認し、どこまでセットアップするかを尋ね、インストーラーを非対話モードで実行して結果を報告します。別の papercut スキルで不足が見つかった場合は、いつでもこのスキルを使ってください。

事前確認

• リポジトリのルート（install.sh がある場所）を見つけます。インストール済みのスキルフォルダーに対して readlink を実行すると、末尾が <root>/skills/papercut-setup になります。各ハーネスのスキルフォルダーを順番に確認してください（一覧は harnesses.sh にあります。通常は ~/.claude/skills、~/.agents/skills、~/.config/opencode/skills、または <project>/ 配下の同じ場所です）。見つからない場合は、${XDG_CONFIG_HOME:-~/.config}/papercut-explainer/config.env 内の PAPERCUT_HOME= を確認してください。どちらも存在しない場合、スキルは npx skills add から入手された可能性があります（ライブラリはなく、スキルのみです）。リポジトリをクローンする場所を尋ね（デフォルトは ~/papercut-explainer）、git clone https://github.com/0xS4N4TG/papercut-explainer <dir> を実行し、その場所をルートとして使います。インストーラーは、コピーされたスキルフォルダーをチェックアウト内へのリンクに置き換えます（実フォルダーがあれば、先にバックアップします）。パスを推測してはいけません。
• install.sh のコマンドはすべて、そのルートから実行してください。bash と macOS または Linux が必要です（Windows の場合は WSL を使います）。
• インストーラー独自のプロンプトにはターミナルが必要ですが、エージェントのシェルツールでは利用できません。必ず --yes と回答をフラグで渡してください。対話型メニューを使う場合は、ユーザー自身で ./install.sh を実行できることを伝えてください。

1. Doctor

./install.sh --doctor

スキルが検出されたデフォルト以外の場所にある場合は、--project DIR、--skills-dir DIR または --target <names> を追加してください。doctor は指定された場所だけを確認します。また、--target を指定しない場合は、完全なインストール先が1か所あれば十分です。結果には [ok]、[--]（不足）または [!!]（不適切）が表示されます。結果を平易な言葉で要約してください。

• スキルのインストール状況、設定ファイル、PAPERCUT_LIB
• node 20+、npm、ffmpeg、python3
• Remotion エージェントスキル、Python ツール（numpy + Pillow）
• 音声：インポート可能な qwen_tts、Hugging Face キャッシュ内の CustomVoice モデル
• ライブラリファイルの有無

次に、これらの結果に該当するインストールモードを伝えてください（papercut-explainer の「インストールモード」を参照）。

2. 質問する

未確定のことだけを、1 回の呼び出しで質問してください（例：Claude Code の AskUserQuestion など、エージェントの質問ツールを使います）。検出されたハーネスを確認する必要がある場合は、先に ./install.sh --dry-run --mode minimal --yes を実行してください（--target auto がデフォルトです）。

質問	選択肢
どの程度にしますか？	最小：スキルのみ。数秒で完了します。標準：プレースホルダー音声でレンダリングします。約 0.7 GB、数分かかります。フル：標準にローカルのナレーションを追加します。さらに 4～6 GB（1.5 GB の venv と、2.3 GB または 4.2 GB のモデル）と、2 分間のスモークテストが必要です。カスタム：コンポーネントを選択します。
どのエージェントを使いますか？	このマシンで検出されたもの（デフォルトの --target auto。何も検出されない場合は Claude Code）、--target claude,codex,gemini のようなリスト、または --target all。名前は harnesses.sh に記載されています。README の 対応状況 の表で、テスト済みのものを確認できます。
スキルの配置先はどこにしますか？	ユーザー全体（デフォルト）または 1 つのプロジェクト（--project DIR）。
コピーとリンクのどちらにしますか？	シンボリックリンク（デフォルト。git pull で更新されます）または --copy（スナップショット）。
ファイルサブエージェントを使うエージェント（claude、opencode、codex、gemini。それ以外はスキップ）ごとに、シーンエージェントのモデルを指定しますか？	選択したエージェントごとに質問します。それぞれ 継承（セッションのモデルを使用）を選択肢に含めます。Claude Code の場合：Sonnet（デフォルト。最も安価で、シーンエージェントの調整に使用されたモデルです）・Opus（最も高性能。並列実行されるシーンエージェントすべてに Opus の料金がかかります）・Haiku・継承。--claude-model sonnet|opus|haiku|inherit|<id> に対応します。ほかのエージェントの場合：デフォルトは 継承。または、そのエージェント独自の形式でモデル ID を指定します（例：opencode では provider/model-id、たとえば anthropic/claude-sonnet-5-5。Codex と Gemini ではプレーンな ID）。--opencode-model M または --agent-model codex=M に対応します。
別のプロバイダーのモデル（DeepSeek など）を使いますか？	ユーザーから希望があった場合に限ります。まずエージェント内でプロバイダーに接続し（OpenCode では /connect、Codex では config.toml のプロバイダー、Claude Code では ANTHROPIC_* 変数）、その後、上記の形式でモデル ID を渡します。手順と DeepSeek の ID は、README の Claude 以外のモデル のセクションに記載されています。エンドツーエンドのテストは未実施であり、性能の低いモデルでは QA の反復回数が増えることを明確に伝えてください。
TTS モデルのサイズ（フル）	1.7B：韻律がより自然で、約 4.2 GB（デフォルト）。0.6B：軽量で高速、約 2.3 GB。
音声クローンモデル（フル）	いいえ（デフォルト）、または --with-clone：同じサイズの Base モデルをもう 1 つ追加します。

数 GB のダウンロードを実行する前に、必ず確認してください。GPU のないマシン（Apple Silicon でも NVIDIA でもない）では、TTS の生成に 1 行あたり数分かかります。代わりに、ナレーションを録音するか、プレースホルダー音声を使うよう提案してください。

3. インストール

./install.sh --mode <minimal|standard|full> --yes [--target auto|all|claude,codex,...] [--claude-model M] [--opencode-model M] [--agent-model NAME=M] [--skills-dir DIR | --project DIR] [--copy] [--tts-model 1.7B|0.6B] [--with-clone]
./install.sh --mode custom --components skills,deps,remotion-skills,pytools,tts,verify --yes

• ユーザーが計画を確認したい場合は、最初に --dry-run を追加してください。変更は加えられません。
• シーンビルダーエージェントは、ハーネスごとにコピーとして、そのハーネス独自の形式（Claude と OpenCode は Markdown、Codex は TOML、Gemini は Markdown）で作成され、選択したモデルの行が設定されます。Inherit の場合はモデルの行はありません。ファイルベースのサブエージェントに対応していないハーネスでは作成されません。その場合、papercut-build がシーンを自ら作成するか、ハーネス独自の並列タスクを使用します。スキルはシンボリックリンクのままです。後からモデルを変更するには、./install.sh --mode custom --components skills --target codex --agent-model codex=<id> --yes（または --claude-model、--opencode-model）を実行します。
• Standard と Full は完了まで数分かかります（npm のインストール、Remotion の Chrome、venv、モデルのダウンロード）。バックグラウンドで実行して出力を確認し、フォアグラウンドの呼び出しを占有しないでください。
• 各モードの動作：Minimal はスキルとシーンビルダーエージェントを、選択した各ハーネスの skills フォルダーと agents フォルダーにリンクします。Standard は依存関係のチェック、Remotion エージェントスキル（選択した各ハーネスについて npx skills add remotion-dev/skills -g -y -a <harness id> を一度実行し、ユーザー全体にインストールされます。計画を確認する際にその旨を伝えてください）、numpy、Pillow、soundfile を含む Python venv、およびセルフテストのレンダリングを追加します。Full は library/voice/setup_tts.sh を追加します。これにより、Qwen3-TTS を含む音声用 venv、ASR バックエンド（Apple Silicon では mlx-whisper、それ以外では faster-whisper）、モデルのダウンロード、および1行のスモークテストが追加されます。
• インストーラーは PAPERCUT_HOME、PAPERCUT_LIB、PAPERCUT_PY、QWEN_TTS_PY、ASR_PY を ~/.config/papercut-explainer/config.env に書き込みます。このチェックアウトと異なる既存のスキルフォルダーは ~/.config/papercut-explainer/backups/ にバックアップされます（スキルフォルダー内ではないため、二重に読み込まれることはありません）。npx skills add などで作成された同一のコピーは、そのまま置き換えられます。

4. 検証と報告

同じ --project、--skills-dir、または --target を指定して、もう一度 ./install.sh --doctor を実行します。インストールされたもの、各エージェントに設定されたシーンエージェントのモデル、失敗したもの（インストーラーはコンポーネント名とともに needs attention: を表示します）、およびその修正方法を報告してください。新しい Claude Code、Codex、または Gemini CLI のセッションでは、新たにリンクされたスキルを反映するために再起動が必要です。opencode は設定を自動的に再読み込みします。その後、「 について papercut explainer を作って」と提案するか、「...のフックを書いて」「このスクリプトのストーリーボードを作って」「音声をセットアップして」のように、各段階を個別に提案してください。

トラブルシューティング

症状	対処方法
node が 20 未満、または見つからない	Node 20 以降をインストールし（nodejs.org、brew install node）、./install.sh --mode custom --components deps,verify --yes を実行します。
ffmpeg が見つからない	brew install ffmpeg または apt install ffmpeg を実行します。
音声用 venv：「Python 3.10-3.12 が必要です」	Qwen3-TTS は新しいバージョンの Python 用のホイールがありません。uv（https://docs.astral.sh/uv/）または brew install [email protected] をインストールし、tts コンポーネントを再実行します。
Hugging Face のダウンロードが停止する、または失敗する	再実行します。ダウンロード済みのファイルは保持され、スクリプトは 3 回再試行します。HF_HUB_DISABLE_XET=1 が設定されます。手動でダウンロードする場合は、自分で設定してください。
初回のレンダリングが遅い	Remotion はヘッドレス Chrome を一度ダウンロードします。音声のレンダリングと capture.mjs では手元の Chrome を使用します。通常とは異なる場所にある場合は CHROME_PATH を設定してください。
セルフテストが失敗する	library/tools/selftest.sh を直接実行すると、失敗したステップを確認できます。
スキルが表示されない	Claude Code、Codex、または Gemini CLI を再起動します（opencode は再読み込みされます）。ハーネスのフォルダー（harnesses.sh。大半の場合は ~/.agents/skills）を確認し、./install.sh --doctor を実行します。
opencode：「Configuration is invalid ... tools」	opencode のエージェントフォルダーに、古い Claude エージェントファイルが残っています。./install.sh --target opencode を再実行すると、opencode 版が書き込まれます。
シーンエージェントのコストが高すぎる、または誤ったモデルで実行される	別のモデルを指定してスキルの手順を再実行します：./install.sh --mode custom --components skills --claude-model sonnet --yes（または --opencode-model inherit）。inherit はセッションのモデルを意味します。
Minimal から Standard に移行する	./install.sh --mode custom --components deps,remotion-skills,pytools,verify --yes
後から音声を追加する	./install.sh --mode custom --components tts --yes [--tts-model 0.6B] [--with-clone]
削除する	./install.sh --uninstall は、記録されたリンクを削除します。config.env、~/.local/share/papercut-explainer 内の venv、および Hugging Face キャッシュは残ります。容量を空けるには、これらを手動で削除してください。
Windows	直接のサポート対象外です。WSL を使用してください。

引き継ぎ

ここに案内したスキル、またはステージ一覧を確認する場合は papercut-explainer に戻ります。状態はファイルに保存されます。config.env にライブラリのパスが記録されるため、ほかのスキルは再度尋ねることなくパスを解決できます。