readme-banner は何をしますか？
ローカルCLIでデュアルテーマSVGを生成します。READMEの編集は、ユーザーが明示的にバナーの挿入・更新を要求した場合のみ行います。設定と具体的な制限については設定リファレンスを参照してください。CLIフラグや設定フィールドを記憶頼りに発明しないでください。
先に操作範囲を確認
- ターゲットリポジトリの絶対パスを特定します。 ユーザーのプロジェクトリポジトリとreadme-bannerツールのソースディレクトリは異なる場合があります。現在の作業ディレクトリを読み取り、ターゲットプロジェクトのREADME/プロジェクトメタデータと照合します。スキルが存在するディレクトリ、ツールのチェックアウト、ターミナルのデフォルトディレクトリは、自動的にはターゲットになりません。
- ターゲットに曖昧さがある場合は、まずユーザーに確認します。カレントディレクトリがたまたまreadme-bannerだからといって、ツール自体にバナーを追加しないでください。ユーザーが明示的にツールリポジトリをターゲットとして選択した場合にのみ、その中で設定と画像を生成します。
- 「リソース/プレビュー断片の生成のみ」なのか、「指定されたREADMEへの挿入/更新」なのかを明確にします。README編集のリクエストが明確でない限り、
--readmeを決して渡さず、他のファイル編集ツールを使ってREADMEを代筆もしません。 ファイル名を確認し、すべての言語バージョンや全ディレクトリのREADMEを自動的に書き換えないでください。 - 既存の設定、画像、管理ブロック、および関連する未コミットの変更を確認します。無関係な変更は保持します。reset、clean、古いリソースの削除、またはユーザーの他のドキュメントの置き換えは行いません。既存の設定はまず読み込んで再利用し、上書きには追加の確認が必要です。習慣的に
--forceを付けないでください。
外観を選択
presetはまずasciiを使用します。これは最初のレンダラーであり、「すべてのテーマ」の名前ではありません。themeは独立して選択します：terminal（緑のターミナル）、ocean（青系）、neon（紫/ピンク）、minimal（モノクロ）。ユーザーの好みに従います。指定がない場合は、プロジェクトの雰囲気に基づいて簡単な提案を1つ行います。カスタムテーマIDを捏造しないでください。- タイトル、サブタイトル、オプションの組み込みアートを取得します。許可なくブランドロゴを使用しないでください。
donutは非ブランドの例です。リアルタイムクロックに依存する組み込みピースは、成果物が再現可能に生成できるように拒否されます。このチェックをバイパスしないでください。 - ASCIIタイトルは最大120文字で、選択した組み込みフォントでサポートされている必要があります。中国語、絵文字、サポートされていない句読点を黙って削除しないでください。代わりの英語の短いタイトルが必要な場合はユーザーに確認し、原文は最大240文字のプレーンテキスト
taglineに残すことができます。 mixedは英語の大文字小文字を保持します。他のフォントは大文字に変換されます。上流URLの20/60文字制限はローカルCLIには適用されませんが、120文字が見た目の美しさを保証するわけではありません。長いタイトルは短くするか、slimやアートの削減を検討してください。- アニメーションタイトルには
glintまたはtypeを使用します。ユーザーが静止バナーを要求した場合はstillを使用します。stillは組み込みアートもフリーズしますが、SVG内にはアートのアニメーションフレームデータが保持されるため、ファイルサイズが大幅に小さくなることは保証されません。
信頼できるCLIエントリポイントを使用
Node.js 22以上が必要です。まず利用可能なバージョンを確認してください。
ツールソースのチェックアウト内にある場合
タスク環境にこのツールのソースコードがすでにある場合は、それを直接使用し、同じツールをネット経由でbootstrapしないでください:
- ツールのソースディレクトリで
npm installを実行します。prepareがTypeScriptをコンパイルします。ツールをビルドするために、依存関係をユーザーのターゲットプロジェクトにインストールしないでください。 - ローカルエントリポイントを確認します:
node "/absolute/path/readme-banner/bin/readme-banner.mjs" --help
- 以降はローカルのNodeエントリポイントを維持し、常に明示的にターゲットの
--cwdを渡します。コマンドの作業ディレクトリがツールのチェックアウトであっても、ターゲットの分離を省略しないでください。
ローカルチェックアウトがない場合
公開リポジトリ abworks-dev/readme-banner の固定Gitタグ v0.1.0 のエントリポイントを使用できます。これにはGit、ネットワーク、およびユーザーが信頼できるサードパーティコードのインストール/実行を許可していることが必要です:
npx --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner --help
@readme-banner/cli はまだnpmに公開されていないローカルパッケージ名です。npx @readme-banner/cli を使用したり、他のnpmパッケージを捏造したりしないでください。 インストールに失敗した場合は実際のエラーを報告し、出所不明、最新の未知のバージョン、またはリモートSVGサービスにフォールバックしないでください。
EALLOWGIT エラーが発生した場合、npmのグローバル設定を自動的に変更しないでください。ユーザーがすでにこの信頼できるリポジトリのインストール/実行を許可しており、組織のポリシーが許す場合にのみ、対応するオプションをサポートするnpmで npx --allow-git=root --yes --package github:abworks-dev/readme-banner#v0.1.0 readme-banner … を1回だけ使用できます。許可がない場合はまず確認します。組織のポリシーによって制限されている場合は停止します。古いnpmがこのオプションを認識しない場合は、通常のコマンドまたは許可されたソースインストールを使用します。
以下の例ではローカルエントリポイントを使用しています。リモートエントリポイントの場合は、node … プレフィックス全体を上記の完全な npx --yes --package … readme-banner に置き換え、後続のパラメータのセマンティクスを変更しないでください。
実行フロー: init → generate → check
1. 設定を作成または再利用
node "/absolute/path/readme-banner/bin/readme-banner.mjs" init --cwd "/absolute/path/target-project" --config "banner.config.json" --preset ascii --theme ocean --title "MY PROJECT" --tagline "Build something useful" --art donut --effect glint
initは設定のみを作成し、画像は生成せず、READMEも変更しません。次に必ずgenerateを実行する必要があります。- 既存の設定がある場合は、まず読み込んでからユーザーの意図に従って最小限に変更するか、そのまま再利用します。自動的に
--forceで再作成しないでください。サブタイトルやアートが不要な場合は、対応するパラメータを省略します。 - フォント、色、影、位置、速度、背景などは、JSONでサポートされているフィールドを使用して設定します。まず設定リファレンスを読み、
init --fontなどのオプションを発明しないでください。 - 設定はJSONのみです。コードを実行する設定は作成せず、任意の設定プラグインをインストールせず、ユーザー提供のリモートSVGをプルまたは注入しないでください。
2. リソースを生成 (デフォルトモード)
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json"
デフォルトでは、設定の outputDir 以下に banner.light.svg、banner.dark.svg を書き込み、<picture> スニペットを出力します。このコマンドはREADMEを変更してはいけません。 ユーザーがリソースのみを要求している場合は、ここで終了し、スニペットをREADMEにこっそり挿入しないでください。
3. README編集の許可を得た場合のみ挿入
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --readme "README.md"
--readme は既存の .md ファイルのみを指定できます。CLIは <!-- readme-banner:start --> と <!-- readme-banner:end --> で囲まれたブロックを管理します。ブロック外のコンテンツは変更しないことを確認します。同じREADME内で、完全なマーカーがコード例に現れた場合でも、重複マーカーとして慎重に扱われるため、デモ用のマーカーペアを追加で挿入しないでください。マーカーに異常がある場合はエラーを調査し、無関係な本文を削除したり、置換範囲を拡大したりしないでください。実際に生成されたスニペットを使用します。URLはターゲットREADMEからの相対パス、セグメント毎にURIエンコードされ、altテキストはHTMLエスケープされている必要があります。エスケープされていないHTMLを自分で組み立てないでください。
4. 結果を確認
# README編集の許可がないタスクは画像のみ確認
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --check
# タスクが指定されたREADMEに明確に関係する場合のみ、管理ブロックも同時に確認
node "/absolute/path/readme-banner/bin/readme-banner.mjs" generate --cwd "/absolute/path/target-project" --config "banner.config.json" --readme "README.md" --check
--checkはファイルを書き込みません。欠落または期限切れの成果物は失敗とすべきです。失敗した場合は理由を報告し、終了コードを無視したり、未実行のチェックを合格と報告したりしないでください。- 2つのSVGが存在し、パスが正しいことを確認します。表示ツールがある場合は、ライト/ダークテーマ、長いタイトル、アートの実際の見た目を確認します。SVGが正常に生成されたことを、すべてのMarkdownクライアントがアニメーションを再生することと同一視しないでください。
- 機械可読な結果が必要な場合は
generate --jsonを使用します。利用可能なメタデータはpresets --json、themes --jsonで確認できます。 - パス範囲外、シンボリックリンク、またはハードリンク保護によるエラーが発生した場合は、ユーザーのターゲットを確認し、ルートディレクトリ内の安全な通常ファイルを選択します。既存ファイルのハードリンク数
nlink > 1は拒否されます。保護を無効にしたり、ファイルをルート外に移動して「回避」したりしないでください。
コマンドとファイルの安全性
- すべての実行呼び出しで正しい作業ディレクトリを明示的に設定し、ターゲット
--cwdを渡します。エージェントの実行時デフォルトディレクトリに依存しないでください。 - タイトル、パス、サブタイトルはデータパラメータです。可能な限りパラメータ配列を渡せる実行APIを使用します。シェルを使用する場合は、そのシェルのルールに従って各パラメータを引用符/エスケープします。例の二重引用符は、そこに含まれる単純なプレースホルダ値にのみ適用され、すべてのシェルインターpolationを防ぐことはできません。信頼できない入力をコマンド、
eval、またはエスケープされていないスクリプトに結合しないでください。Windowsパスも個別に引用符で囲む必要があります。 - ユーザーが許可した設定、生成リソース、指定された管理ブロックのみを変更します。ビジネスロジックコード、無関係なドキュメント、またはユーザーが行った既存の変更は変更しません。
- 自動的にcommit、push、リモートリポジトリを作成、リリース発行、画像のアップロード、npmパッケージの公開、またはその他のリモート公開を行わないでください。 これらには独立した明確なリクエストが必要です。
納品に関する説明
簡潔なレポート: ターゲットリポジトリ、採用したpreset/theme/タイトル、生成された2つの画像、READMEを変更したかどうかとその場所、実際に実行したチェック結果。README編集の許可がない場合は「READMEは変更していません」と明示し、生成されたスニペットをユーザーが選択できるように返すことができます。ユーザーの確認が必要な字形の代替、長すぎるタイトル、ビューアの互換性の問題などをリストアップします。実行していないテストが合格したと主張しないでください。