readme-banner 是做什麼的？
用本地 CLI 生成雙主題 SVG；僅在用戶明確要求插入 / 更新橫幅時編輯 README。設定和具體限制見 configuration reference，不要憑記憶發明 CLI 標誌或設定欄位。
先確認操作範圍
- 確定目標倉庫的絕對路徑。 用戶的專案倉庫與 readme-banner 工具原始碼目錄可能不同。讀取當前工作目錄並核對目標專案的 README / 專案元資料；skill 所在目錄、工具 checkout、終端預設目錄都不自動等於目標。
- 如果對目標有歧義，先問用戶；不要因為當前目錄恰好是 readme-banner 就給工具本身加橫幅。只有用戶明確選擇工具倉庫作為目標時才在其中產生設定和圖片。
- 明確是「只產生資源 / 預覽片段」，還是「插入 / 更新指定 README」。沒有明確 README 編輯請求，就絕不傳
--readme，也不透過其他檔案編輯工具代寫 README。 確認檔案名，不能自動改寫所有語言版本或所有目錄下的 README。 - 檢查已存在的設定、圖片、受管區塊及相關未提交變更。保留無關修改；不要 reset、clean、刪除舊資源或取代用戶其他文件。已有設定先讀取並複用，覆蓋需要額外確認，不要習慣性加
--force。
選擇外觀
preset先用ascii；它是第一個渲染器，不是「所有主題」的名字。theme獨立選擇：terminal綠色終端、ocean藍青、neon紫粉、minimal單色。遵從用戶偏好；未指定時根據專案氣質提出一個簡短建議，不捏造自定義主題 id。- 獲取標題、副標題和可選內建 art。避免未經請求使用品牌標誌；
donut是非品牌示例。依賴即時時鐘的內建 piece 會被拒絕，以便產物可重複生成；不要繞過該校驗。 - ASCII 標題最多 120 字元，必須全部所選內建字體支援；中文、emoji 與不支援的標點不能靜默刪除。需要替代英文短標題時請用戶確認，原文可放在最多 240 字元的普通文字
tagline。 mixed保留英文大小寫；其他字體會轉為大寫。上游 URL 的 20 / 60 字元限制不適用於本地 CLI，但 120 字元不是美觀保證。長標題應縮短，或考慮slim、減少 art。- 動畫標題用
glint或type；用戶要求靜止橫幅時用still。still也會凍結內建 art；SVG 中仍保留 art 的動畫幀資料，所以它不保證檔案體積顯著減小。
選用可靠的 CLI 入口
需要 Node.js >=22，先檢查可用版本。
已在工具原始碼 checkout 中
若任務環境已有本工具原始碼，直接使用它，不要連網 bootstrap 同一個工具：
- 在工具原始碼目錄執行
npm install；prepare會編譯 TypeScript。不要為了建構工具而把依賴裝進用戶的目標專案。 - 驗證本地入口：
node "/absolute/path/readme-banner/bin/readme-banner.mjs" --help
- 後續保持本地 Node 入口，始終顯式傳目標
--cwd。即使命令的工作目錄是工具 checkout，也不能省略目標隔離。
沒有本地 checkout
可使用公開倉庫 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 …。未獲授權時先詢問；受組織策略限制時停止。舊版 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重建。不需要副標題或 art 時省略對應參數。 - 字型、顏色、陰影、位置、速度、背景等透過 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不寫檔案；缺失或過期產物應失敗。失敗時報告原因，不能忽略退出碼或把未執行的檢查說成通過。- 核對兩張 SVG 都存在、路徑正確；有檢視工具時檢查淺 / 深主題、長標題與 art 的實際效果。不能把 SVG 成功生成等同於所有 Markdown 用戶端都會播放動畫。
- 需要機器可讀結果時使用
generate --json；可用元資料透過presets --json、themes --json檢視。 - 路徑越界、符號連結或硬連結保護報錯時，確認用戶目標並選擇根目錄內的安全普通檔案；現有檔案的硬連結數
nlink > 1會被拒絕。不關閉防護、不把檔案搬到根外「繞過」。
命令與檔案安全
- 所有執行呼叫顯式設定正確工作目錄，並傳入目標
--cwd；不要依賴 agent 執行階段的預設目錄。 - 標題、路徑與副標題是資料參數。優先使用可傳參數陣列的執行 API；用 shell 時按該 shell 的規則引用 / 跳脫每個參數。範例雙引號僅適用於其中的簡單佔位值，不能防禦所有 shell 插值；不要把不可信輸入拼成命令、
eval或未經跳脫的腳本。Windows 路徑也應單獨引用。 - 只修改用戶授權的設定、生成資源與指定受管區塊；不改業務程式碼、無關文件或已有用戶更改。
- 不自動 commit、push、建立遠端倉庫、發 release、上傳圖片、發佈 npm 套件或觸發其他遠端發佈。 這些都需要獨立的明確請求。
交付說明
簡短報告：目標倉庫、採用的 preset / theme / 標題、生成的兩張圖片、是否修改 README 及其位置、實際執行的檢查結果。沒有 README 授權時明確說「未修改 README」，並可返回生成片段供用戶選擇。列出仍需用戶確認的字形替代、超長標題或檢視器相容性問題；不要聲稱未執行的測試已通過。