readme-generate

# README 產生器 透過分析專案原始碼來生成專業的雙語 README 文件。 ## 指令語法 ``` /readme-generate [private] [LICENSE_TYPE] [REPO_PATH] ``` ### 參數（全部為選填） | 參數 | 格式 | 範例 | 行為 | |-----------|--------|---------|----------| | `private` | 關鍵字 | `private` | 生成時不包含徽章和星標歷史 | | `LICENSE_TYPE` | 授權識別碼 | `MIT`、`Apache-2.0` | 生成 LICENSE 檔案 | | `REPO_PATH` | `github.com/{owner}/{repo}` | `github.com/foo/bar` | 覆蓋預設的擁有者/儲存庫 | ### 參數偵測規則 | 模式 | 偵測為 | |---------|-------------| | `private`（不區分大小寫） | `PRIVATE_MODE` 旗標 | | 包含 `github.com/` | `REPO_PATH` | | 符合已知授權類型（不區分大小寫） | `LICENSE_TYPE` | **順序獨立**：參數可以任意順序出現。 ### 支援的 LICENSE 類型 | 類型 | 別名（不區分大小寫） | |------|----------------------------| | MIT | `mit` | | Apache-2.0 | `apache`、`apache2`、`apache-2.0` | | GPL-3.0 | `gpl`、`gpl3`、`gpl-3.0` | | BSD-3-Clause | `bsd`、`bsd3`、`bsd-3-clause` | | ISC | `isc` | | Unlicense | `unlicense`、`public-domain` | | Proprietary | `proprietary`（隱含 `private` 模式） | ### 範例 ```bash /readme-generate # 全部重生成 + MIT（若無 LICENSE） /readme-generate MIT # 全部重生成 + MIT LICENSE /readme-generate private # 全部重生成，不含徽章/星標歷史 /readme-generate private MIT # 私有模式 + MIT LICENSE /readme-generate proprietary # 私有模式 + Proprietary LICENSE /readme-generate github.com/foo/bar # 全部重生成，使用自訂儲存庫路徑 ``` --- ## Step 0：作者設定（強制性 - 第一步） **在執行任何動作前，必須先載入或建立作者設定。所有載入與建立都透過 `scripts/setup_config.py` 腳本完成。** 下文指令中的 `{skill_dir}` 為本 `SKILL.md` 所在目錄的絕對路徑，依當前執行環境實際載入位置代入。 ### 設定檔位置 ``` ~/.skill-readme-generate.json ``` ### 設定檔格式 ```json { "author_name": "張三 John Doe", "author_email": "dev@example.com", "author_url": "https://linkedin.com/in/johndoe", "github_owner": "johndoe" } ``` ### 執行協議（必須嚴格遵守） **Step 0.1：檢查設定檔** ```bash python3 {skill_dir}/scripts/setup_config.py check ``` | Exit Code | stdout | 意義 | 下一步 | |-----------|--------|------|--------| | `0` | 單行 JSON | 設定存在且完整 | 解析 JSON，載入 `{author_name}`、`{author_email}`、`{author_url}`、`{github_owner}`，跳到 Step 1 | | `1` | （無） | 設定缺失或欄位不完整 | 進入 Step 0.2 | **Step 0.2：收集使用者輸入** 當 Step 0.1 回傳 exit code `1` 時，**必須向使用者詢問**下列四個欄位（順序固定，全部必填）： | 欄位 | 提示文字 | 範例 | |------|----------|------| | `author_name` | 作者姓名（顯示於版權頁尾與 LICENSE） | `張三 John Doe` | | `author_email` | 聯絡 Email | `dev@example.com` | | `author_url` | 個人連結（LinkedIn、GitHub、個人網站皆可） | `https://linkedin.com/in/johndoe` | | `github_owner` | GitHub 使用者名稱（用於預設 `{owner}`） | `johndoe` | **Step 0.3：寫入設定** 將使用者的四個答案按順序傳給腳本的 `write` 子指令： ```bash python3 {skill_dir}/scripts/setup_config.py write \ "{author_name}" "{author_email}" "{author_url}" "{github_owner}" ``` 腳本會將設定寫入 `~/.skill-readme-generate.json` 並將該 JSON 印到 stdout（供 agent 解析載入）。後續執行可直接由 Step 0.1 讀取，不再詢問。 ### 手動初始化（使用者自行執行） 使用者可在終端直接執行腳本以互動方式建立設定（適合首次設定或手動重置）： ```bash python3 {skill_dir}/scripts/setup_config.py ``` 若檔案已存在，腳本會直接印出現有設定；若不存在則以 `input()` 逐欄詢問。 ### 覆蓋機制 - 若指令列傳入 `REPO_PATH`（含 `github.com/{owner}/{repo}`），則 `{owner}` 使用指令列的值，其餘作者欄位仍從設定檔取得 - 使用者可隨時手動編輯 `~/.skill-readme-generate.json` 更新資訊，或刪除該檔以觸發重新設定 --- ## 關鍵：必要輸出 **務必生成六個檔案：** | 檔案 | 語言 | 用途 | |------|----------|---------| | `README.md` | 英文 | 主要文件（精簡，特色驅動） | | `doc/README.zh.md` | 繁體中文（ZH-TW） | 中文文件（精簡，特色驅動） | | `doc/doc.md` | 英文 | 詳細技術文件（安裝、使用、參考） | | `doc/doc.zh.md` | 繁體中文（ZH-TW） | 中文詳細技術文件 | | `doc/architecture.md` | 英文 | 詳細架構圖（完整 Mermaid） | | `doc/architecture.zh.md` | 繁體中文（ZH-TW） | 中文詳細架構圖 | **README 負責吸引人，doc 負責教會人，architecture 負責畫清楚。** --- ## 參數（從專案中提取） | 參數 | 來源 | 範例 | |-------|--------|---------| | `{owner}` | `REPO_PATH` 覆蓋 > `~/.skill-readme-generate.json` 的 `github_owner` > `git remote` | `johndoe` | | `{author_name}` | `~/.skill-readme-generate.json` 的 `author_name` | `張三 John Doe` | | `{author_email}` | `~/.skill-readme-generate.json` 的 `author_email` | `dev@example.com` | | `{author_url}` | `~/.skill-readme-generate.json` 的 `author_url` | `https://linkedin.com/in/johndoe` | | `{date}` | 生成當日 `date +%Y-%m-%d`（Author 區段 contrib.rocks 的 `cache_bust`） | `2026-09-16` | | `{updated}` | 各輸出檔的最後更新日期，見「最後更新日期」 | `2026-10-06` | | `{repo}` | `REPO_PATH` 覆蓋或資料夾名稱或 `git remote get-url origin` | `go-scheduler` | | `{package}` | `package.json` name、`go.mod` module、`pyproject.toml` name | `@aspect/utils` | | `{year}` | 現有 README 年份或 `git log --reverse --format=%ai \| head -1` 或當前年份 | `2024` | **優先順序**：指令列 `REPO_PATH` > `~/.skill-readme-generate.json` > 本地 git remote > 資料夾名稱 --- ## 工作流程 ``` 0. 作者設定 → `scripts/setup_config.py check` 讀取 ~/.skill-readme-generate.json；缺失則詢問使用者後以 `write` 子指令建立 1. 解析 → 從指令中提取 PRIVATE_MODE、LICENSE_TYPE、REPO_PATH 2. 分析 → 在目標專案上執行 analyze_project.py 3. 提取 → 從專案取得 {repo}、{package}、{year}（或使用 REPO_PATH 覆蓋） 4. 檢視 → 檢查現有文件、LICENSE、範例；讀 `CHANGELOG.md`，「破壞性變更」全部項目逐項比對既有產物，命中即直接修改；回應中列出命中項與改動 5. 選特色 → 從分析結果中提煉出所有精妙且具代表性的專案特色 6. 生成 readme → 先建立 doc/README.zh.md，再翻譯為 README.md 7. 生成 doc → 先建立 doc/doc.zh.md，再翻譯為 doc/doc.md 8. 生成 architecture → 先建立 doc/architecture.zh.md，再翻譯為 doc/architecture.md 9. 授權 → 若指定 LICENSE_TYPE → 使用指定類型；若無 LICENSE 檔案且未指定 → 預設生成 MIT LICENSE 10. 驗證 → 依「驗證檢查清單」逐項確認 11. 儲存 → README.md 寫入專案根目錄；其餘檔案寫入 doc/ 子目錄（自動建立） 12. SEO → 以專案根執行 `/seo-optimize`：GitHub repo description／topics／homepage（R9），有 `wiki-worker/` 一併檢查（見順序 3「搭配 `/seo-optimize`」） ``` --- ## 步驟 1：分析專案 ```bash python3 {skill_dir}/scripts/analyze_project.py /path/to/project ``` 輸出：包含語言、名稱、版本、類型、函式、相依性的 JSON。 --- ## 步驟 2：提取參數 ```bash # 如果提供 REPO_PATH，解析它： # github.com/owner/repo → {owner}=owner, {repo}=repo # 否則回退到： # 取得儲存庫名稱 basename $(pwd) # 或 git remote get-url origin | sed 's/.*\/\([^\/]*\)\.git/\1/' # 取得首次提交年份 git log --reverse --format=%ai | head -1 | cut -d'-' -f1 # 取得套件名稱（Node.js） jq -r '.name' package.json # 取得模組名稱（Go） sed -n 's/^module //p' go.mod ``` --- ## 步驟 3：提煉專案特色 **這是整份 README 的核心。** 從分析結果中識別出所有精妙且能區分此專案的特色。 ### 特色選擇原則 | 優先級 | 類型 | 範例 | |--------|------|------| | 最高 | 解決的核心問題 | 「透過統一 Agent 介面支援 5 家 AI 後端」 | | 高 | 獨特的技術手段 | 「安全指令執行：rm 自動移至 .Trash」 | | 中 | 開發者體驗差異 | 「互動式確認機制，支援 --allow 跳過」 | | 低 | 通用能力 | 「支援多種語言」（太泛，避免） | ### 規則 - **數量限制：3–5 個**。少於 3 個代表提煉不夠深入，超過 5 個會稀釋焦點 - 若候選特色超過 5 個，**依優先級表合併或刪除**，保留最具區分度的 3–5 個 - 每個特色：一行標題（≤15 字）+ **一句話說明**（簡潔扼要） - **不提供 code snippet** — 純文字描述核心價值 - **不做細節展開** — 不列舉子功能、不解釋實作細節、不提供參數說明 --- ## 步驟 4：生成中文版本 **使用精確的區段順序建立 `README.zh.md`：** ### 區段順序（強制性） | 順序 | 區段 | 必要 | 公開模式 | 私有模式 | |-------|---------|----------|-------------|--------------| | 0 | LLM 生成通知 + `***` | **是** | ✓ | ✓ | | 1 | 置中封面圖片 | 否 | ✓ | **跳過** | | 2 | 置中標語 + 置中徽章 + `***` | **是**（私有模式跳過） | 標語 + 徽章 | **跳過** | | 3 | 簡短描述 | **是** | ✓ | ✓ | | 4 | 目錄 | **是** | ✓ | ✓ | | 5 | 功能特點（3–5 個精妙特色，list 呈現）| **是** | ✓ | ✓ | | 6 | 架構（僅與特色相關）| 否 | ✓ | ✓ | | 7 | 授權 | **是**（公開模式） | ✓ | **跳過** | | 8 | 作者 | **是**（公開模式） | ✓ | **跳過** | | 9 | 星標歷史 | 否 | ✓ | **跳過** | | 10 | 版權頁尾 | 否 | ✓ | ✓ | --- ## 強制性區段（完全複製） ### 最後更新日期（六個輸出檔皆適用） 每個輸出檔開頭標示該檔的最後更新日期 `{updated}`： | 檔案 | 位置 | EN | ZH | |---|---|---|---| | `README.md`／`doc/README.zh.md` | 檔案第一行（順序 0 之前），後接空行 | `Last updated: {updated}` | `最後更新：{updated}` | | `doc/doc*.md`／`doc/architecture*.md` | `# 標題` 下一行，後接空行（h1 維持第一行） | 同上 | 同上 | `{updated}` 取值：除日期行外的內容與既有檔相同 → 沿用既有日期並跳過寫入；內容有變或為新檔 → 生成當日 `{date}`。EN／ZH 各自判斷。 **為何：** 日期代表內容最後變動日，重生成沒有實質改動時換日期只會產生無意義的 diff，也讓讀者誤判內容新鮮度。文件站首頁鏡像 README 時會移除這一行，改由 `build.js` 依內容雜湊產生日期（與 sitemap `lastmod` 同值）。 ### 順序 0：LLM 生成通知 + 分隔線 **英文（README.md）：** ```markdown > [!NOTE] > This README was generated by [SKILL](https://github.com/agenvoy/skill-readme-generate), get the ZH version from [here](./doc/README.zh.md). *** ``` **中文（README.zh.md）：** ```markdown > [!NOTE] > 此 README 由 [SKILL](https://github.com/agenvoy/skill-readme-generate) 生成，英文版請參閱 [這裡](../README.md)。 *** ```