From 7138250b22dd90e6d9c656e4b6e4e40376a8d4c8 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 18 Jun 2026 08:07:27 +0000 Subject: [PATCH] =?UTF-8?q?docs(=E5=B0=88=E6=A1=88=E8=AA=AA=E6=98=8E):=20?= =?UTF-8?q?=E7=A7=BB=E9=99=A4=20skill=20=E5=90=8C=E6=AD=A5=E7=9B=B8?= =?UTF-8?q?=E9=97=9C=E6=96=87=E4=BB=B6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 16 ---------------- ANTIGRAVITY.md | 14 -------------- CLAUDE.md | 16 ---------------- GEMINI.md | 14 -------------- README.md | 34 ++-------------------------------- TODO.md | 8 ++++---- 6 files changed, 6 insertions(+), 96 deletions(-) delete mode 100644 AGENTS.md delete mode 100644 ANTIGRAVITY.md delete mode 100644 CLAUDE.md delete mode 100644 GEMINI.md diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index fa2403d..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,16 +0,0 @@ -# Triage Findings - -When the task is to triage review findings, follow this workflow: - -1. Merge all findings into one list. -2. Remove duplicates. -3. Sort by severity: `critical` -> `warning` -> `info`. -4. Renumber from 1 after sorting. -5. Fix real issues with the smallest safe change. -6. Add false positives to `.gitea/ai-review/exclusions.json`, preserving the original wording, language, and semantics as much as possible. -7. Add or update tests when behavior changes. -8. Re-check the issue after each fix. - -Use the repo-local `triage-findings` skill for the same workflow when running in Codex. - -Trigger it with `/triage-findings`. diff --git a/ANTIGRAVITY.md b/ANTIGRAVITY.md deleted file mode 100644 index 70b8f1d..0000000 --- a/ANTIGRAVITY.md +++ /dev/null @@ -1,14 +0,0 @@ -# Triage Findings - -Use the triage-finding workflow for review issue lists: - -1. Merge findings into one list. -2. Remove duplicates. -3. Sort by severity: `critical` -> `warning` -> `info`. -4. Renumber from 1. -5. Fix real issues with the smallest safe change. -6. Put false positives into `.gitea/ai-review/exclusions.json`, preserving the original wording, language, and semantics as much as possible. -7. Add or update tests when behavior changes. -8. Re-check after each fix. - -The reusable skill lives in `.antigravity/skills/triage-findings/SKILL.md`. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index e1c3938..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,16 +0,0 @@ -# Triage Findings - -When the task is to triage review findings, follow this workflow: - -1. Merge all findings into one list. -2. Remove duplicates. -3. Sort by severity: `critical` -> `warning` -> `info`. -4. Renumber from 1 after sorting. -5. Fix real issues with the smallest safe change. -6. Add false positives to `.gitea/ai-review/exclusions.json`, preserving the original wording, language, and semantics as much as possible. -7. Add or update tests when behavior changes. -8. Re-check the issue after each fix. - -Use the repo-local `triage-findings` skill for the same workflow when running in Claude. - -Trigger it with `/triage-findings`. diff --git a/GEMINI.md b/GEMINI.md deleted file mode 100644 index 8ca4117..0000000 --- a/GEMINI.md +++ /dev/null @@ -1,14 +0,0 @@ -# Triage Findings - -Use the triage-finding workflow for review issue lists: - -1. Merge findings into one list. -2. Remove duplicates. -3. Sort by severity: `critical` -> `warning` -> `info`. -4. Renumber from 1. -5. Fix real issues with the smallest safe change. -6. Put false positives into `.gitea/ai-review/exclusions.json`, preserving the original wording, language, and semantics as much as possible. -7. Add or update tests when behavior changes. -8. Re-check after each fix. - -The reusable skill lives in `.gemini/skills/triage-findings/SKILL.md`. diff --git a/README.md b/README.md index 0e48726..e956074 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ 5. 從 PR 問題表格中取出所有舊問題，依照等級排序後 Comment 到 Pull Request 6. 從 PR 問題表格中取出所有新問題，排除嚴重等級的問題後 Comment 到 Pull Request 7. 從 PR 問題表格中取出所有新問題，將每個嚴重等級的問題以 Gitea 行內 review comment 標註在問題所在的檔案與行數上，留言內容為等級／審查員／建議；若問題位置無法解析出行號（例如未標行號或一次列出多個檔案），或該行不在本次 diff 範圍內導致行內留言失敗，則降級為一般 PR Comment -8. Commit 問題檔案，將 workspace 中實際存在的同步檔覆蓋到記憶區；workspace 沒有的同步檔就略過，不會刪除記憶區既有內容。自動提交的 commit message 會帶上 `[ai-review-bot]`，供 workflow 判斷是否要跳過重跑 +8. Commit 問題檔案，只將 workspace 中實際存在的 `.gitea/ai-review/findings.json` 與 `.gitea/ai-review/exclusions.json` 覆蓋到記憶區；workspace 沒有的問題檔就略過。自動提交的 commit message 會帶上 `[ai-review-bot]`，供 workflow 判斷是否要跳過重跑 9. 如果 PR 問題表格中有嚴重問題，則不要讓 workflow 執行成功(exit 1) # 設計 @@ -28,7 +28,7 @@ 4. 盡量將應用程式放在 ./app，修改 entrypoint.sh 與 Dockerfile 讓程式可以正常運行 5. 將提示詞放到 ./app/prompts 內供程式讀取 6. API Key 支援逗號分隔傳入多個，隨機順序各嘗試一次，全部失敗則 exit 1 -7. 讀取 Git Diff 時排除 `.gitea/`、`.amazonq/`、`.agents/`、`.antigravity/`、`.claude/`、`.codex/`、`.gemini/`、`.github/` 資料夾，以及 `AGENTS.md`、`ANTIGRAVITY.md`、`CLAUDE.md`、`GEMINI.md`、`TODO.md`、`README.md`，避免 AI 分析 workflow 設定、skill 入口與文件等非業務程式碼 +7. 讀取 Git Diff 時排除 `.gitea/`、`.github/` 資料夾，以及 `TODO.md`、`README.md`，避免 AI 分析 workflow 設定與文件等非業務程式碼 8. 階段七驗證來源分支中的 `findings.json` 與 `exclusions.json` 是否為合法 JSON 格式，格式錯誤時先嘗試透過 AI 修正內容，再重新驗證；修正後仍不合法才 exit 1；之後才檢查檔案是否存在，不存在則建立並寫入 `[]` 9. 傳給 AI 的 findings 只保留必要欄位（level、role、location、suggestion），排除 `is_new` 等內部欄位；system prompt 精簡為指令核心；exclusions hint 只傳 location 與 suggestion，減少 token 用量 10. 執行時會額外記錄來源分支狀態、`findings.json` / `exclusions.json` 的檔案路徑、大小、mtime 與 raw/normalized 筆數，方便追查讀檔與分支內容不一致的問題 @@ -276,33 +276,3 @@ jobs: pull-requests: write issues: write ``` - -## Skill：Triage Findings - -這份 skill 用來處理 review 問題清單。 - -### 規則 - -1. 合併問題。 -2. 依嚴重度排序：`critical` -> `warning` -> `info`。 -3. 重新編號。 -4. 真問題就修。 -5. 誤判就加到 `.gitea/ai-review/exclusions.json`。 -6. 有變更就補測試。 - -### 使用方式 - -Codex：`$triage-findings 問題原始檔(文字或截圖)` -Copilot：`/triage-findings 問題原始檔(文字或截圖)` -Claude：直接輸入 `triage-findings 問題原始檔(文字或截圖)` -Gemini：直接輸入 `triage-findings 問題原始檔(文字或截圖)` -Amazon Q：直接輸入 `triage-findings 問題原始檔(文字或截圖)` -Antigravity：直接輸入 `triage-findings 問題原始檔(文字或截圖)` - -### 適用情境 - -`triage-findings 問題原始檔(文字或截圖)` 用在 review 問題整併、排序、修正、排除誤判。 - -### 版本包含 - -提交時一併包含 `triage-findings` skill 與各平台入口檔；其中 `AGENTS.md`、`ANTIGRAVITY.md`、`CLAUDE.md`、`GEMINI.md` 會在目標專案已存在時先做規則化合併，並在可用 LLM 時再用 AI 輔助檢查是否有遺失任何 skill、command 或規則；其餘同步檔則以來源覆蓋；若 workspace 沒有某個同步檔，記憶區會保留原檔，不做刪除。`findings.json` 與 `exclusions.json` 都從使用此 action 的存取庫來源分支讀取，而不是從 action 本地 workspace 讀取。寫入 `.gitea/ai-review/exclusions.json` 時，盡量保留原始問題文字的語言與語意，避免過度改寫。未來若新增任何 skill 或新增其他平台的 skill 入口，必須同時把對應檔案複製進 Docker image，並把同步清單更新到會使用此 action 的目標專案，避免 action 與目標專案內容脫節。 diff --git a/TODO.md b/TODO.md index 17e570a..4703e54 100644 --- a/TODO.md +++ b/TODO.md @@ -6,7 +6,7 @@ - 已驗收：`code-review` job 的 log 已完整出現 `Step1` 到 `Step8`，並以 `Pipeline 完成` 結束。 ## 階段二：Git Diff 排除 .gitea/ 資料夾 -- 目標：讀取 Git Diff 時排除 `.gitea/` 資料夾內的所有檔案，以及 `.amazonq/`、`.antigravity/`、`.claude/`、`.codex/`、`.gemini/`、`.github/`、`ANTIGRAVITY.md`、`CLAUDE.md`、`GEMINI.md`、`TODO.md`、`README.md`，避免 AI 分析 workflow 設定、skill 入口與文件等非業務程式碼。 +- 目標：讀取 Git Diff 時排除 `.gitea/` 資料夾內的所有檔案，以及 `.github/`、`TODO.md`、`README.md`，避免 AI 分析 workflow 設定與文件等非業務程式碼。 - 驗收：PR 中有上述路徑或檔案的變更時，diff 內容不包含該區塊，AI 分析結果不含這些路徑相關問題。 - 已驗收：`app/gitea.js` 已在取得 diff 時過濾 `.gitea/` 區塊，且相關單元測試已覆蓋。 @@ -38,9 +38,9 @@ - 已驗收：log 已明確顯示 `.gitea/ai-review/findings.json` 與 `.gitea/ai-review/exclusions.json` 都是 `JSON 格式正確`。 ## 階段八：記憶區 commit/push 與錯誤處理 -- 目標：記憶區能成功 commit/push，且一併包含 `triage-findings` skill 與各平台入口檔；`AGENTS.md`、`ANTIGRAVITY.md`、`CLAUDE.md`、`GEMINI.md` 在目標專案已存在時會先做規則化合併，並在可用 LLM 時再做 AI 輔助檢查以避免遺失 skill、command 或規則；其餘同步檔則以來源覆蓋；workspace 沒有的同步檔則保留記憶區既有內容，不做刪除；錯誤時有明確 log，流程結束有總結訊息。 -- 驗收：log 有「persisted findings」、「commit=...」、「push=...」等訊息，且能看出四個入口檔會先規則合併、再由 AI 輔助檢查，其他同步檔會被來源覆蓋；當 workspace 缺少某個同步檔時，記憶區中的對應檔案不會被刪除；錯誤時有「Runner failed: ...」等明確錯誤說明。 -- 已驗收：commit/push 成功時會出現 `persisted findings commit=... push=... review_outcome=...`，且同步規則與缺檔不刪除的行為都有單元測試覆蓋。 +- 目標：記憶區能成功 commit/push，且只提交 workspace 中實際存在的 `.gitea/ai-review/findings.json` 與 `.gitea/ai-review/exclusions.json`；workspace 沒有的問題檔就略過；錯誤時有明確 log，流程結束有總結訊息。 +- 驗收：log 有「persisted findings」、「commit=...」、「push=...」等訊息；git add 只包含新的問題檔；錯誤時有「Runner failed: ...」等明確錯誤說明。 +- 已驗收：commit/push 成功時會出現 `persisted findings commit=... push=... review_outcome=...`，且只提交問題檔的行為已有單元測試覆蓋。 ## 階段九：阻擋嚴重問題 PR（第 8 點） - 目標：如果 PR 問題表格中有嚴重（critical）問題，workflow 需直接 exit 1，不讓流程成功。