dx-roaster
評論 GitHub 儲存庫的開發者體驗。產生四個檔案：roast.md、action-plan.md、ideal-readme.md、score.json。專為開放原始碼維護者和開發工具創辦人設計，以備戰 Show HN、Product Hunt 或任何前五分鐘至關重要的發布場合。
重要規則 (每次執行前務必閱讀)
-
在評分之前，先閱讀所有三個參考檔案。
references/scoring-rubric.md、references/roast-voice-guide.md、references/readme-template.md。評分標準是不可妥協的——請使用精確的 10 個維度。 -
每個維度都必須評分，範圍 0–10。絕不跳過。 缺少資料 = 分數 0，而非「不適用」。
-
評論必須引用具體發現。 逐字引用糟糕的行。參考檔案路徑。儘可能引用行號。切勿撰寫像「文件可以做得更好」這種空洞的陳腔濫調。
-
語氣很重要。 預設為
honest。根據references/roast-voice-guide.md切換語氣。Brutal 要風趣但絕不針對個人。Kind 要鼓勵但仍具體。 -
行動計畫按影響力排序，而非嚴重性。 使用
impact × (1 / effort)。一個增加 10 分的 5 分鐘修復，排名高於一個增加 12 分的 2 小時修復。 -
絕不發明 URL。 在撰寫
ideal-readme.md時，對遺失的連結使用<placeholder>語法。評論會告訴維護者填入內容。 -
絕不指名道姓維護者或貢獻者。 評論作品，而非人。
-
輸出四個檔案 至
dx-roast/。不要寫入其他位置。不要跳過檔案。
步驟 1: 接收
必要參數：
repo— 本機路徑 (預設.) 或https://github.com/owner/repoURL
選擇性參數：
| 參數 | 預設值 | 說明 |
|---|---|---|
tone | honest | brutal / honest / kind |
output_dir | dx-roast/ | 寫入 4 個輸出檔案的位置 |
compare_to | 無 | 用於基準比較的選擇性第二個儲存庫 URL |
如果 repo 是 URL：使用 git clone <url> /tmp/dx-roast-<short-hash> 複製到暫存目錄。從那裡掃描。執行完畢後刪除暫存目錄。
如果 repo 是 . 或本機路徑：在原地掃描，不修改任何內容。
步驟 2: 探索
讀取這些檔案 (每個檔案都可能不存在——請注意其不存在)：
README.md— 完整內容、結構 (標題)、程式碼區塊、圖片引用、徽章 URLCONTRIBUTING.md、CODE_OF_CONDUCT.md.github/ISSUE_TEMPLATE/、.github/PULL_REQUEST_TEMPLATE.md、.github/CODEOWNERSpackage.json(說明、首頁、儲存庫、授權、腳本)、pyproject.toml、Cargo.toml、go.modLICENSE(存在與否 + 類型)docs/資料夾內容 (僅檔案名稱 + 大小)examples/或samples/或cookbook/資料夾.github/workflows/*.yml(僅名稱 + 簡要的 CI 存在性檢查)
如果 repo 是 URL，也透過 gh 擷取：
gh api repos/<owner>/<repo> --jq '{stars: .stargazers_count, forks: .forks_count, watchers: .subscribers_count, pushed_at, description, homepage, topics, default_branch}'
gh api repos/<owner>/<repo>/commits --jq '.[0].commit.author.date' | head -1
gh api repos/<owner>/<repo>/contributors --paginate --jq '[.[] | .login] | length'
如果任何 GitHub 呼叫失敗，則捕捉並繼續。
步驟 3: 為 10 個維度評分
針對 references/scoring-rubric.md 中的每個維度，輸出 {score: 0–10, evidence: [...]}，其中 evidence 是 1-3 個簡短字串的列表，引用您發現的內容。
範例：
"visual_proof": {
"score": 4,
"evidence": [
"在第 89 行找到 1 個螢幕截圖 (在折疊線下方)",
"沒有動畫展示 / gif",
"沒有影片"
]
}
加總分數 → 總分 (0–100) → 等級 (依評分標準為 A/B/C/D/F)。
以精確的格式儲存至 dx-roast/score.json：
{
"repo": "<owner/repo 或本機路徑>",
"scanned_at": "<ISO 8601 時間戳>",
"dimensions": {
"time_to_first_success": { "score": 7, "evidence": ["..."] },
"what_is_this_clarity": { "score": 5, "evidence": ["..."] },
"visual_proof": { "score": 4, "evidence": ["..."] },
"install_simplicity": { "score": 9, "evidence": ["..."] },
"runnable_quick_start": { "score": 8, "evidence": ["..."] },
"documentation_depth": { "score": 6, "evidence": ["..."] },
"examples": { "score": 5, "evidence": ["..."] },
"community_signals": { "score": 3, "evidence": ["..."] },
"trust_signals": { "score": 7, "evidence": ["..."] },
"marketing_signals": { "score": 4, "evidence": ["..."] }
},
"total": 58,
"grade": "D",
"tone": "honest"
}
步驟 4: 撰寫評論
閱讀 references/roast-voice-guide.md。套用要求的語氣。撰寫 250–500 字的內容至 dx-roast/roast.md。
必要結構：
# DX Roast: <儲存庫名稱>
**等級: <字母> (<總分>/100)** · 語氣: <tone>
<段落 1: 結論。哪些做得好 + 最大的差距。>
<段落 2: 引用 2 個具體發現，附檔案引用。>
<段落 3: 引用另外 2 個發現，連結至維度分數。>
<段落 4 (選擇性): 最終的轉折或與一個知名儲存庫的比較。>
<結尾段落: 指向 `action-plan.md` 以獲取前進方向。>
每個評論都必須引用來自 score.json 證據陣列的至少 3 個具體發現。
步驟 5: 產生行動計畫
對每個候選修復計算 priority = impact / effort_minutes。選取前 5–10 個。按優先順序降序排序。
對每個修復，寫入 dx-roast/action-plan.md：
### N. <以命令語氣撰寫的修復，一行>
**原因：** <一句話的合理性。引用其改善的維度。>
**影響：** +<X> 分 · **努力程度：** <5分鐘 / 30分鐘 / 2小時 / 半天>
**方法：**
1. <具體步驟 1>
2. <具體步驟 2>
3. <具體步驟 3>
<顯示確切變更的選擇性程式碼/markdown 片段>
action-plan.md 的開頭：
# 行動計畫 — <儲存庫名稱>
當前等級：<字母> (<總分>/100)
按影響 × 努力程度排名的頂級修復。請依序執行這些項目。
---
步驟 6: 產生理想 README
閱讀 references/readme-template.md。根據「填寫規則」章節填寫範本。寫入 dx-roast/ideal-readme.md。
對遺失的值使用 <homepage_url> 等佔位符。長度上限：100 行。
步驟 7: 終端摘要
向使用者印出精確的格式：
DX Roast 完成 — 等級：<字母> (<總分>/100)
前 3 個修復 (按影響力排序)：
1. <修復 1> +<X> 分 · <努力程度>
2. <修復 2> +<X> 分 · <努力程度>
3. <修復 3> +<X> 分 · <努力程度>
檔案：
→ dx-roast/roast.md (可分享的結論)
→ dx-roast/action-plan.md (優先排序的修復)
→ dx-roast/ideal-readme.md (目標狀態)
→ dx-roast/score.json (原始分數)
如果提供了 compare_to，則加入比較行：
基準：<其他儲存庫> 得分 <X>/100 (等級 <Y>) — 差距 <delta> 分。
自我問答 (每次執行，在印出終端摘要之前)
-
score.json中的所有 10 個維度都有分數 + 證據 - 總分等於各維度分數的總和
- 等級字母與依評分標準閾值的總分相符
- 評論引用了 score.json 中的至少 3 個證據項目
- 評論未指名任何維護者 / 貢獻者
- 行動計畫有 5–10 個項目，按優先順序降序排列
- 理想 README 少於 100 行
- 理想 README 對掃描中未找到的任何 URL 使用了
<placeholder> - 所有 4 個檔案都存在於 output_dir 中
- roast.md 或 action-plan.md 中沒有
<TBD>/<TODO>佔位符
如果任何檢查失敗，修正後重新執行該步驟。
錯誤處理
這四種失敗模式會得到明確的處理——絕不讓技能在未顯示原因的情況下，默默地產出部分輸出。
| 情況 | 行為 |
|---|---|
repo 不存在、無法複製或無法讀取 | 立即退出並顯示訊息 儲存庫未找到或無法存取：<repo>。不要寫入任何輸出檔案。 |
README.md 遺失 | 無論如何都執行。將 what_is_this_clarity、visual_proof、runnable_quick_start 和 marketing_signals 的分數評為接近 0。將缺失作為評論的開場白 (「沒有 README 本身就是一種聲明」)。 |
| 儲存庫為私有且無可用的 GitHub 驗證 | 嘗試本機複製 (git clone <url>)；如果失敗，則退出並顯示 儲存庫為私有且無可用的驗證。建議使用者設定 GITHUB_TOKEN 或傳遞本機路徑。 |
compare_to URL 失敗 (網路、404、私有等) | 在不進行基準比較的情況下繼續。在評論中新增一行：注意：請求與 <compare_to> 進行基準比較，但無法擷取。從終端摘要中省略 基準： 行。 |
步驟 2 元資料擷取期間的任何 GitHub API 錯誤 (速率限制、暫時性 5xx) 都會被捕捉，並在 score.json 的 trust_signals.evidence 中以 "github 元資料不可用" 記錄。其餘執行繼續進行。
範例
良好呼叫：
"Roast my repo at https://github.com/myorg/mytool — tone: brutal."
→ 技能會複製、掃描、評分、將 4 個檔案寫入 dx-roast/、印出摘要。對於典型儲存庫，總執行時間 < 60 秒。
良好比較：
"DX audit on the current dir. Benchmark against https://github.com/vercel/next.js."
→ 掃描兩者，為當前目錄評分，在評論和摘要中包含基準比較行。
此技能不包含的功能
- 不修改目標儲存庫 (唯讀掃描)
- 不執行安全稽核或相依性掃描
- 不產出行銷文案 (行動項目是具體的，而非「為語氣重寫」)
- 不產生圖片或素材 (僅使用佔位符)
- 不發佈到社群媒體 (僅撰寫可分享的文字)