619 lines
30 KiB
Markdown
619 lines
30 KiB
Markdown
# AI Code Review
|
||
|
||
> 更新時間：2026/07/28 13:57:24
|
||
|
||
AI 多角色 code review 的 Gitea **node action**（`node24`、零外部相依）：以攻擊方六角色（🔮 Mage 邏輯、🗡️ Assassin 安全、⚡ Rogue 效率、🎼 Bard 風格、🧪 Maya 測試、🧰 Leo 可維護性）並行找問題、防守方（🛡️ Paladin）裁決誤報，結果留言到 PR、保存 findings，並以 bot commit 標記審查結果（`[success]`／`[failure]`）供下次觸發快速回報。
|
||
|
||
## 使用方式
|
||
|
||
```yaml
|
||
# .gitea/workflows/review.yaml（呼叫端範例）
|
||
name: AI-REVIEW
|
||
on:
|
||
pull_request:
|
||
branches: [master, develop]
|
||
types: [opened, synchronize]
|
||
jobs:
|
||
review:
|
||
runs-on: ubuntu
|
||
steps:
|
||
- uses: actions/checkout@v4
|
||
with:
|
||
fetch-depth: 0 # 需完整歷史以計算 merge-base
|
||
- uses: https://gitea.jsc.idv.tw/node-actions/ai-code-review@v1
|
||
with:
|
||
token: ${{ secrets.GITHUB_TOKEN }} # 必填：PR 留言與 push findings 用
|
||
model: '' # 選填：指定 AI 模型（空＝工具預設）
|
||
create-issue: 'false' # 選填：'true' 時問題另建 issue 追蹤
|
||
```
|
||
|
||
| input | 必填 | 預設 | 說明 |
|
||
| --- | --- | --- | --- |
|
||
| `token` | ✅ | — | Gitea API token（PR 留言與 push findings 用；呼叫端以 secrets 傳入） |
|
||
| `model` | ❌ | `''` | 指定 AI 工具使用的模型（空值＝各工具預設） |
|
||
| `create-issue` | ❌ | `'false'` | `'true'` 時建立 issue 逐條留言問題明細，收尾只 commit `exclusions.json` |
|
||
|
||
審查流程（10 步驟）：
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
S1[1 判斷 bot commit 標記] -->|命中| E0[直接回報 success/failure]
|
||
S1 -->|未命中| N3[3 偵測 AI 工具並留言]
|
||
N3 --> N4[4 讀 .reviewignore 整理 diff 並留言]
|
||
N4 --> N5[5 攻擊方登場留言]
|
||
N5 --> N6[6 攻擊方 sub agent 並行找問題]
|
||
N6 --> N7[7 防守方登場留言]
|
||
N7 --> N8[8 防守方裁決 → 保存 findings ＋ 誤判回寫 exclusions.json]
|
||
N8 --> N2[2 延後將舊留言標記解決（成功產生結果後才執行）]
|
||
N2 --> N9[9 嚴重問題逐條掛行留言]
|
||
N9 --> N10[10 警告＋建議彙整表格留言]
|
||
N10 --> E1[收尾 commit/push ＋ exit code]
|
||
```
|
||
|
||
## 專案列表
|
||
|
||
### 專案描述表
|
||
|
||
| 專案名稱 | 專案描述 |
|
||
| --- | --- |
|
||
| [ai-code-review](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/) | Gitea node action：提供台北時區日誌工具、runner 上下文載入、git diff／commit 操作、Gitea REST API 客戶端（留言／review／issue／標籤）、AI CLI 工具偵測與 sub agent 執行、角色提示載入、固定留言模板，以及多角色審查編排（攻擊方找問題、防守方裁決、findings 保存、誤判回寫、建問題模式） |
|
||
|
||
### 參考專案表
|
||
|
||
| 專案名稱 | 參考專案列表 |
|
||
| --- | --- |
|
||
| [ai-code-review](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/) | 無 |
|
||
|
||
### NuGet 套件表
|
||
|
||
| 專案名稱 | NuGet 套件列表 |
|
||
| --- | --- |
|
||
| [ai-code-review](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/) | 無 |
|
||
|
||
## 功能列表
|
||
|
||
### ai-code-review
|
||
|
||
| 功能名稱 | 功能描述 |
|
||
| --- | --- |
|
||
| [log.taipeiNow](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/log.js) | [取得台北時區 yyyy/MM/dd HH:mm:ss 時間字串](#logtaipeinow) |
|
||
| [log.taipeiFileStamp](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/log.js) | [取得檔名用時間戳 yyyy-MM-dd-HH:mm:ss](#logtaipeifilestamp) |
|
||
| [log.taipeiFromIso](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/log.js) | [將 ISO 時間字串轉為台北時區顯示字串](#logtaipeifromiso) |
|
||
| [log.log](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/log.js) | [以統一格式輸出一行日誌](#loglog) |
|
||
| [context.loadContext](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/context.js) | [彙整 runner 環境變數與事件 payload 為執行上下文](#contextloadcontext) |
|
||
| [gitrepo.latestCommitSubject](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js) | [取得最新 commit 的訊息標題](#gitrepolatestcommitsubject) |
|
||
| [gitrepo.resolveMergeBase](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js) | [解析 base 分支與 HEAD 的 merge-base](#gitreporesolvemergebase) |
|
||
| [gitrepo.changedFiles](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js) | [列出 base 與 HEAD 之間有變更的檔案](#gitrepochangedfiles) |
|
||
| [gitrepo.fileDiff](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js) | [取得單一檔案的 git diff 內容](#gitrepofilediff) |
|
||
| [gitrepo.fileLastUpdatedIso](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js) | [取得檔案最後一次 commit 的 ISO 時間](#gitrepofilelastupdatediso) |
|
||
| [gitrepo.commitAndPushFindings](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitrepo.js) | [以 bot 身分 commit 結果檔並 push 回 PR 來源分支](#gitrepocommitandpushfindings) |
|
||
| [gitea.whoAmI](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [取得 token 對應的使用者（bot 身分）](#giteawhoami) |
|
||
| [gitea.createCommentOnIssue](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [對指定編號 issue／PR 新增一般留言](#giteacreatecommentonissue) |
|
||
| [gitea.createIssueComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [對本次 PR 新增一般留言](#giteacreateissuecomment) |
|
||
| [gitea.listLabels](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [列出存取庫可用標籤](#gitealistlabels) |
|
||
| [gitea.createIssue](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [在存取庫建立 issue（可掛標籤）](#giteacreateissue) |
|
||
| [gitea.listIssueComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [列出 PR 全部一般留言（自動分頁）](#gitealistissuecomments) |
|
||
| [gitea.editIssueComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [編輯既有一般留言](#giteaeditissuecomment) |
|
||
| [gitea.createReview](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [建立 code review 並掛行內留言](#giteacreatereview) |
|
||
| [gitea.listReviews](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [列出 PR 全部 review（自動分頁）](#gitealistreviews) |
|
||
| [gitea.listReviewComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [列出某 review 的全部行內留言](#gitealistreviewcomments) |
|
||
| [gitea.tryResolveReviewComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/gitea.js) | [盡力將行內留言標記為已解決](#giteatryresolvereviewcomment) |
|
||
| [agents.detectTool](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/agents.js) | [依優先序偵測可用的 AI CLI 工具](#agentsdetecttool) |
|
||
| [agents.runAgent](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/agents.js) | [非互動執行一次 sub agent 並取回回覆](#agentsrunagent) |
|
||
| [agents.extractJson](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/agents.js) | [從 agent 回覆萃取 JSON（容忍雜訊）](#agentsextractjson) |
|
||
| [roles.loadRoles](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/roles.js) | [載入角色提示檔並解析 frontmatter](#rolesloadroles) |
|
||
| [roles.attackersOf](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/roles.js) | [過濾出攻擊方角色](#rolesattackersof) |
|
||
| [roles.defendersOf](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/roles.js) | [過濾出防守方角色](#rolesdefendersof) |
|
||
| [templates.toolComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js) | [產生步驟 3 審查工具留言](#templatestoolcomment) |
|
||
| [templates.diffComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js) | [產生步驟 4 變更摘要留言](#templatesdiffcomment) |
|
||
| [templates.rolesComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js) | [產生步驟 5／7 角色登場留言](#templatesrolescomment) |
|
||
| [templates.severeCommentBody](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js) | [產生步驟 9 單條嚴重問題留言](#templatesseverecommentbody) |
|
||
| [templates.severeReviewBody](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js) | [產生步驟 9 嚴重問題 review 總覽](#templatesseverereviewbody) |
|
||
| [templates.othersComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js) | [產生步驟 10 警告＋建議彙整表格留言](#templatesotherscomment) |
|
||
| [templates.issueBody](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js) | [產生建問題模式的 issue 本文](#templatesissuebody) |
|
||
| [templates.issueFindingComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js) | [產生建問題模式單條問題的 issue 留言](#templatesissuefindingcomment) |
|
||
| [templates.nothingToReviewComment](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/templates.js) | [產生無可審查變更留言](#templatesnothingtoreviewcomment) |
|
||
| [review.loadReviewIgnore](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [讀取 .reviewignore 忽略前綴清單](#reviewloadreviewignore) |
|
||
| [review.isIgnored](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [判斷檔案是否忽略不送審](#reviewisignored) |
|
||
| [review.collectDiffRows](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [整理送審 diff 資料列（含長度上限）](#reviewcollectdiffrows) |
|
||
| [review.fillPurposes](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [以 AI 補齊每個檔案的一行用途描述](#reviewfillpurposes) |
|
||
| [review.runAttackers](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [攻擊方 sub agent 並行找問題並合併列表](#reviewrunattackers) |
|
||
| [review.runDefenders](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [防守方 sub agent 裁決保留或排除](#reviewrundefenders) |
|
||
| [review.sortFindings](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [依嚴重度→檔案→行號排序 findings](#reviewsortfindings) |
|
||
| [review.appendExclusions](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [誤判問題附加到 exclusions.json](#reviewappendexclusions) |
|
||
| [review.sortFindingsForIssue](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [依檔案→嚴重度→行號排序（建問題模式）](#reviewsortfindingsforissue) |
|
||
| [review.selectLabels](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [以 AI 從可用標籤挑選 issue 標籤](#reviewselectlabels) |
|
||
| [review.createIssueWithFindings](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [建 issue 並逐條留言問題明細](#reviewcreateissuewithfindings) |
|
||
| [review.resolveOldComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [將 PR 舊留言標記為解決／過時](#reviewresolveoldcomments) |
|
||
| [review.postSevereComments](https://gitea.jsc.idv.tw/node-actions/ai-code-review/src/branch/develop/src/lib/review.js) | [嚴重問題逐條掛行留言（含降級）](#reviewpostseverecomments) |
|
||
|
||
## 使用範例
|
||
|
||
<a id="logtaipeinow"></a>
|
||
### log.taipeiNow
|
||
|
||
將指定時間（省略時為現在）轉為台北時區（Asia/Taipei）的 `yyyy/MM/dd HH:mm:ss` 字串，輸出不受主機系統時區影響；供日誌時間戳與 findings 產生時間使用。
|
||
|
||
```js
|
||
const { taipeiNow } = require('./src/lib/log');
|
||
taipeiNow(); // '2026/07/17 16:46:13'
|
||
taipeiNow(new Date('2026-01-01')); // '2026/01/01 08:00:00'
|
||
```
|
||
|
||
<a id="logtaipeifilestamp"></a>
|
||
### log.taipeiFileStamp
|
||
|
||
產生檔名用時間戳 `yyyy-MM-dd-HH:mm:ss`（空白換成 `-`）；findings 檔案即以此命名。注意輸出含 `:`，Linux 檔名合法、不可移植到 Windows。
|
||
|
||
```js
|
||
const { taipeiFileStamp } = require('./src/lib/log');
|
||
taipeiFileStamp(); // '2026-07-17-16:46:13' → .gitea/ai-review/findings/2026-07-17-16:46:13.json
|
||
```
|
||
|
||
<a id="logtaipeifromiso"></a>
|
||
### log.taipeiFromIso
|
||
|
||
將 ISO 8601 時間字串轉為台北時區顯示字串；輸入為空或無法解析時回傳佔位符「—」不丟例外，適合直接嵌進留言表格。
|
||
|
||
```js
|
||
const { taipeiFromIso } = require('./src/lib/log');
|
||
taipeiFromIso('2026-07-17T06:30:05Z'); // '2026/07/17 14:30:05'
|
||
taipeiFromIso(''); // '—'
|
||
```
|
||
|
||
<a id="loglog"></a>
|
||
### log.log
|
||
|
||
以統一格式 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息` 輸出一行日誌到 stdout；stage 為空時省略階段區塊，等級約定限 INF／WRN／ERR／TRC／DBG。
|
||
|
||
```js
|
||
const { log } = require('./src/lib/log');
|
||
log('步驟4', 'INF', '變更檔案 5 個，送審 3 個。');
|
||
// [2026/07/17 16:46:13][步驟4][INF]: 變更檔案 5 個，送審 3 個。
|
||
```
|
||
|
||
<a id="contextloadcontext"></a>
|
||
### context.loadContext
|
||
|
||
彙整 runner 注入的 `GITHUB_*` 環境變數、`INPUT_*` 輸入參數與事件 payload，組出審查流程所需的完整上下文（repo、PR 編號／標題／描述、head/base、token、model、createIssue、workspace、actionPath 等）。前置條件：於 Actions runner 環境執行；呼叫端應檢查 `prNumber` 與 `token` 是否有值。
|
||
|
||
```js
|
||
const { loadContext } = require('./src/lib/context');
|
||
const ctx = loadContext();
|
||
if (!ctx.prNumber || !ctx.token) process.exit(1); // 非 PR 事件或缺 token
|
||
```
|
||
|
||
<a id="gitrepolatestcommitsubject"></a>
|
||
### gitrepo.latestCommitSubject
|
||
|
||
取得目前 HEAD 最新 commit 的訊息標題；主流程步驟 1 以此比對 `chore: update ai-review findings [ai-review-bot][success|failure]` 決定是否直接回報結果。
|
||
|
||
```js
|
||
const gitrepo = require('./src/lib/gitrepo');
|
||
const subject = gitrepo.latestCommitSubject(process.cwd());
|
||
```
|
||
|
||
<a id="gitreporesolvemergebase"></a>
|
||
### gitrepo.resolveMergeBase
|
||
|
||
先嘗試 `git fetch origin <baseRef>`（失敗靜默沿用本地資料），再以 `git merge-base origin/<baseRef> HEAD` 取得共同祖先，作為 diff 比較基準，避免把 base 分支後續演進算進 PR 變更。
|
||
|
||
```js
|
||
const base = gitrepo.resolveMergeBase(cwd, 'master'); // '3f2a…'（40 碼 SHA）
|
||
```
|
||
|
||
<a id="gitrepochangedfiles"></a>
|
||
### gitrepo.changedFiles
|
||
|
||
列出 base 與 HEAD 之間有變更的檔案（repo 相對路徑陣列）；結果再經 `.reviewignore` 過濾後逐檔送審。
|
||
|
||
```js
|
||
const files = gitrepo.changedFiles(cwd, base); // ['src/index.js', 'action.yml']
|
||
```
|
||
|
||
<a id="gitrepofilediff"></a>
|
||
### gitrepo.fileDiff
|
||
|
||
取得單一檔案在 base 與 HEAD 之間的 unified diff 原始文字（無變更時為空字串），供組進攻擊方提示。
|
||
|
||
```js
|
||
const diff = gitrepo.fileDiff(cwd, base, 'src/index.js');
|
||
```
|
||
|
||
<a id="gitrepofilelastupdatediso"></a>
|
||
### gitrepo.fileLastUpdatedIso
|
||
|
||
取得檔案最後一次 commit 的 ISO 8601 時間；查不到（未 commit、git 失敗）回空字串，由呼叫端以「—」佔位。
|
||
|
||
```js
|
||
const iso = gitrepo.fileLastUpdatedIso(cwd, 'src/index.js'); // '2026-07-17T15:00:00+08:00'
|
||
```
|
||
|
||
<a id="gitrepocommitandpushfindings"></a>
|
||
### gitrepo.commitAndPushFindings
|
||
|
||
以 `ai-review-bot` 身分將指定檔案 commit 並 push 回 PR 來源分支；HEAD 停在 merge commit 時先 detach 到 head sha，暫存區無差異時不建空 commit（回傳 `false`），origin push 失敗改用帶 token 的 URL 重試（該 URL 絕不可輸出到日誌）。
|
||
|
||
```js
|
||
const committed = gitrepo.commitAndPushFindings(cwd, {
|
||
headRef: 'feature/x', headSha: ctx.headSha,
|
||
message: 'chore: update ai-review findings [ai-review-bot][success]',
|
||
files: ['.gitea/ai-review/findings/2026-07-17-16:46:13.json'],
|
||
token: ctx.token, serverUrl: ctx.serverUrl, repository: ctx.repository,
|
||
}); // true＝已推送、false＝無變更略過
|
||
```
|
||
|
||
<a id="giteawhoami"></a>
|
||
### gitea.whoAmI
|
||
|
||
取得 token 對應的使用者（`GET /user`），即 bot 身分；步驟 2 以 `login` 比對留言作者辨識本 action 發過的留言。
|
||
|
||
```js
|
||
const gitea = require('./src/lib/gitea');
|
||
const me = await gitea.whoAmI(ctx); // { id, login, ... }
|
||
```
|
||
|
||
<a id="giteacreatecommentonissue"></a>
|
||
### gitea.createCommentOnIssue
|
||
|
||
對指定編號的 issue（或 PR，Gitea 兩者共用留言機制）新增一般留言；建問題模式逐條留言問題明細即用本函式。
|
||
|
||
```js
|
||
await gitea.createCommentOnIssue(ctx, issue.number, '🔴 嚴重｜...');
|
||
```
|
||
|
||
<a id="giteacreateissuecomment"></a>
|
||
### gitea.createIssueComment
|
||
|
||
對本次 PR（`ctx.prNumber`）新增一般留言；為 `createCommentOnIssue` 的便捷包裝，主流程各步驟的留言都經由它發出。
|
||
|
||
```js
|
||
const created = await gitea.createIssueComment(ctx, '## 📋 變更摘要 ...');
|
||
// created.id 記入本回合留言集合，步驟 2 標註過時時跳過
|
||
```
|
||
|
||
<a id="gitealistlabels"></a>
|
||
### gitea.listLabels
|
||
|
||
列出存取庫可用標籤（自動分頁）；建問題模式先取得標籤，再交給 `review.selectLabels` 由 AI 挑選。
|
||
|
||
```js
|
||
const labels = await gitea.listLabels(ctx); // [{ id, name, color }, ...]
|
||
```
|
||
|
||
<a id="giteacreateissue"></a>
|
||
### gitea.createIssue
|
||
|
||
在存取庫建立 issue；`labels`（標籤 id 陣列）僅在非空時帶入。建問題模式以 PR 標題／描述為內容建立追蹤 issue。
|
||
|
||
```js
|
||
const issue = await gitea.createIssue(ctx, { title: 'PR 標題', body: '…', labels: [3, 7] });
|
||
// issue.number 供後續逐條留言
|
||
```
|
||
|
||
<a id="gitealistissuecomments"></a>
|
||
### gitea.listIssueComments
|
||
|
||
列出 PR 全部一般留言（自動分頁，每頁 50 筆）；步驟 2 據此找出 bot 舊留言標註〔已過時〕。
|
||
|
||
```js
|
||
const comments = await gitea.listIssueComments(ctx);
|
||
```
|
||
|
||
<a id="giteaeditissuecomment"></a>
|
||
### gitea.editIssueComment
|
||
|
||
以新內容整段覆寫既有一般留言（留言 id 於 repo 層級定位）；步驟 2 用來替舊留言加上〔已過時〕前綴。
|
||
|
||
```js
|
||
await gitea.editIssueComment(ctx, comment.id, `> 〔已過時〕…\n\n${comment.body}`);
|
||
```
|
||
|
||
<a id="giteacreatereview"></a>
|
||
### gitea.createReview
|
||
|
||
建立 event 為 `COMMENT` 的 code review，並把行內留言逐條掛在檔案行號上；步驟 9 以單一 review 送出全部嚴重問題。若行號不在 PR diff 內會整包失敗，呼叫端（`review.postSevereComments`）會降級為一般留言。
|
||
|
||
```js
|
||
await gitea.createReview(ctx, '## 🔴 嚴重問題（共 2 條）…', [
|
||
{ path: 'src/a.js', new_position: 42, body: '…' },
|
||
]);
|
||
```
|
||
|
||
<a id="gitealistreviews"></a>
|
||
### gitea.listReviews
|
||
|
||
列出 PR 全部 review（自動分頁）；步驟 2 據此逐一取出行內留言嘗試解決。
|
||
|
||
```js
|
||
const reviews = await gitea.listReviews(ctx);
|
||
```
|
||
|
||
<a id="gitealistreviewcomments"></a>
|
||
### gitea.listReviewComments
|
||
|
||
列出指定 review 底下的全部行內留言（單次呼叫、未分頁）。
|
||
|
||
```js
|
||
const comments = await gitea.listReviewComments(ctx, reviews[0].id);
|
||
```
|
||
|
||
<a id="giteatryresolvereviewcomment"></a>
|
||
### gitea.tryResolveReviewComment
|
||
|
||
盡力將行內留言標記為已解決；resolve endpoint 依 Gitea 版本不一定存在（需人工確認），任何失敗一律回 `false` 不丟錯，呼叫端第一次失敗即停止嘗試。
|
||
|
||
```js
|
||
const ok = await gitea.tryResolveReviewComment(ctx, reviewId, commentId);
|
||
if (!ok) { /* 版本不支援 → 記 WRN 後放棄後續 resolve */ }
|
||
```
|
||
|
||
<a id="agentsdetecttool"></a>
|
||
### agents.detectTool
|
||
|
||
依 antigravity → codex → claude 優先序，以 `<tool> --version`（30 秒逾時）偵測可用工具，第一個成功者中選並附版本字串；全部不可用回 `null`（主流程記 ERR 失敗收場）。antigravity 的非互動參數尚未驗證（需人工確認）。
|
||
|
||
```js
|
||
const agents = require('./src/lib/agents');
|
||
const tool = agents.detectTool(); // { name: 'codex', version: 'codex-cli 0.144.5', ... } | null
|
||
```
|
||
|
||
<a id="agentsrunagent"></a>
|
||
### agents.runAgent
|
||
|
||
以非互動模式執行一次 sub agent：提示從 stdin 餵入，codex 改讀 `--output-last-message` 暫存檔取最終回覆。永不 reject——逾時、非零退出碼都以 `{ ok: false }` resolve，由呼叫端降級。
|
||
|
||
```js
|
||
const res = await agents.runAgent(tool, { model: '', prompt: '…', cwd, timeoutMs: 600000 });
|
||
const data = res.ok ? agents.extractJson(res.output) : null;
|
||
```
|
||
|
||
<a id="agentsextractjson"></a>
|
||
### agents.extractJson
|
||
|
||
從 agent 自由文字回覆萃取 JSON：先剝 code fence、再以「陣列優先」的最大範圍切片嘗試 parse；失敗一律回 `null` 不丟例外。
|
||
|
||
```js
|
||
agents.extractJson('```json\n[{"a":1}]\n```'); // [{ a: 1 }]
|
||
agents.extractJson('雜訊 {"b":2} 雜訊'); // { b: 2 }
|
||
agents.extractJson('不是 JSON'); // null
|
||
```
|
||
|
||
<a id="rolesloadroles"></a>
|
||
### roles.loadRoles
|
||
|
||
載入目錄下全部 `*.md` 角色提示檔（依檔名排序），解析開頭 `---` 包夾的輕量 frontmatter（單行「鍵: 值」），回傳 `{ file, meta, body, raw }` 陣列。
|
||
|
||
```js
|
||
const { loadRoles } = require('./src/lib/roles');
|
||
const roles = loadRoles(path.join(ctx.actionPath, 'src', 'prompts', 'roles'));
|
||
// roles[0].meta => { name: 'Assassin', side: 'attack', focus: 'security', ... }
|
||
```
|
||
|
||
<a id="rolesattackersof"></a>
|
||
### roles.attackersOf
|
||
|
||
過濾出 `meta.side === 'attack'` 的攻擊方角色（現況 6 位：Assassin／Bard／Leo／Mage／Maya／Rogue），保留檔名排序、不改原陣列。
|
||
|
||
```js
|
||
const attackers = attackersOf(roles); // 6 位攻擊方
|
||
```
|
||
|
||
<a id="rolesdefendersof"></a>
|
||
### roles.defendersOf
|
||
|
||
過濾出 `meta.side === 'defend'` 的防守方角色（現況 1 位：Paladin，focus: verdict）。
|
||
|
||
```js
|
||
const defenders = defendersOf(roles); // [Paladin]
|
||
```
|
||
|
||
<a id="templatestoolcomment"></a>
|
||
### templates.toolComment
|
||
|
||
產生步驟 3 的審查工具留言：工具／版本／模型／審查 commit／Run Job 連結表格＋審查管線 mermaid 流程圖；開頭含隱藏標記供步驟 2 辨識。
|
||
|
||
```js
|
||
const body = templates.toolComment({
|
||
toolName: 'codex', version: 'codex-cli 0.144.5', model: '',
|
||
sha: ctx.headSha, runNumber: ctx.runNumber,
|
||
runLink: `${ctx.serverUrl}/${ctx.repository}/actions/runs/${ctx.runId}`,
|
||
});
|
||
```
|
||
|
||
<a id="templatesdiffcomment"></a>
|
||
### templates.diffComment
|
||
|
||
產生步驟 4 的變更摘要留言：四欄表格（檔案／用途／git diff 長度／最後更新時間），截斷送審的檔案加註，結尾統計送審與排除數。
|
||
|
||
```js
|
||
const body = templates.diffComment(diffRows, ignoredCount);
|
||
```
|
||
|
||
<a id="templatesrolescomment"></a>
|
||
### templates.rolesComment
|
||
|
||
產生步驟 5／7 共用的角色登場留言：三欄表格（角色／面向／個性），面向以「中文（原文）」並列。
|
||
|
||
```js
|
||
const body = templates.rolesComment({ title: '⚔️ 攻擊方登場', roles: attackers });
|
||
```
|
||
|
||
<a id="templatesseverecommentbody"></a>
|
||
### templates.severeCommentBody
|
||
|
||
產生步驟 9 單條嚴重問題的留言內容（程式碼片段／問題／修改建議／建議寫法，結尾提示可回覆）；降級為一般留言時以 `withLocation: true` 在內文標明檔案與行號。
|
||
|
||
```js
|
||
const body = templates.severeCommentBody(finding, snippet);
|
||
const fallback = templates.severeCommentBody(finding, snippet, { withLocation: true });
|
||
```
|
||
|
||
<a id="templatesseverereviewbody"></a>
|
||
### templates.severeReviewBody
|
||
|
||
產生步驟 9 嚴重問題 review 的總覽 body（標明總數，說明逐條掛行）。
|
||
|
||
```js
|
||
await gitea.createReview(ctx, templates.severeReviewBody(severe.length), comments);
|
||
```
|
||
|
||
<a id="templatesotherscomment"></a>
|
||
### templates.othersComment
|
||
|
||
產生步驟 10 的警告＋建議彙整表格留言（等級／審查員／檔案名稱／問題起訖行數／問題描述／修改建議），儲存格經防呆逸出。
|
||
|
||
```js
|
||
const body = templates.othersComment(others); // others＝非嚴重的保留問題
|
||
```
|
||
|
||
<a id="templatesissuebody"></a>
|
||
### templates.issueBody
|
||
|
||
產生建問題模式新 issue 的本文：PR 描述為主體（缺省以「（PR 無描述）」佔位），尾端附追溯引言標明來源 PR。
|
||
|
||
```js
|
||
const body = templates.issueBody({ prNumber: ctx.prNumber, prBody: ctx.prBody });
|
||
```
|
||
|
||
<a id="templatesissuefindingcomment"></a>
|
||
### templates.issueFindingComment
|
||
|
||
產生建問題模式單條問題的 issue 留言（固定模板：嚴重等級／位置起訖行數／問題描述／修改建議／建議寫法）；issue 留言無法掛行，位置一律以內文標明。
|
||
|
||
```js
|
||
await gitea.createCommentOnIssue(ctx, issue.number, templates.issueFindingComment(finding));
|
||
```
|
||
|
||
<a id="templatesnothingtoreviewcomment"></a>
|
||
### templates.nothingToReviewComment
|
||
|
||
產生「無可審查變更」留言：套用 `.reviewignore` 後送審清單為空時取代變更摘要，宣告本回合視為審查通過。
|
||
|
||
```js
|
||
const body = templates.nothingToReviewComment(ignoredCount);
|
||
```
|
||
|
||
<a id="reviewloadreviewignore"></a>
|
||
### review.loadReviewIgnore
|
||
|
||
讀取 repo 根目錄的 `.reviewignore`（每行一個路徑前綴、`#` 註解、空行略過）；檔案不存在回空陣列。
|
||
|
||
```js
|
||
const review = require('./src/lib/review');
|
||
const ignores = review.loadReviewIgnore(cwd); // ['.gitea/', 'README.md', ...]
|
||
```
|
||
|
||
<a id="reviewisignored"></a>
|
||
### review.isIgnored
|
||
|
||
判斷檔案是否忽略不送審：任何深度的 `node_modules/` 一律排除（內建保險），其餘依前綴比對。
|
||
|
||
```js
|
||
const files = allFiles.filter((f) => !review.isIgnored(f, ignores));
|
||
```
|
||
|
||
<a id="reviewcollectdiffrows"></a>
|
||
### review.collectDiffRows
|
||
|
||
為每個送審檔案取得 diff 並計算統計（行數／字元數／最後更新時間），套用單檔 16,000／總量 160,000 字元送審上限（超限記 WRN、不靜默截斷）；`purpose` 先以「—」佔位。
|
||
|
||
```js
|
||
const diffRows = review.collectDiffRows({ cwd, files, base, gitrepo });
|
||
```
|
||
|
||
<a id="reviewfillpurposes"></a>
|
||
### review.fillPurposes
|
||
|
||
以選定 AI 工具為每個送審檔案產生一行用途描述並就地寫回 `diffRows[].purpose`；失敗只記 WRN 保留「—」，不阻斷流程。
|
||
|
||
```js
|
||
await review.fillPurposes({ tool, model: ctx.model, cwd, diffRows });
|
||
```
|
||
|
||
<a id="reviewrunattackers"></a>
|
||
### review.runAttackers
|
||
|
||
步驟 6：每位攻擊方角色一個 sub agent 並行分析 diff，回覆經檢核標準化後合併為單一問題列表並編派 `F001…` 流水號；單一角色失敗只記 WRN 以空結果代替。
|
||
|
||
```js
|
||
const findings = await review.runAttackers({ tool, model: ctx.model, cwd, attackers, diffRows });
|
||
```
|
||
|
||
<a id="reviewrundefenders"></a>
|
||
### review.runDefenders
|
||
|
||
步驟 8：每位防守方角色一個 sub agent 配合 `exclusions.json` 與歷史 findings 裁決；「全部防守方都判可排除」才移除，拿不準一律保留，每條附 `verdicts` 供追溯。
|
||
|
||
```js
|
||
const { kept, excluded } = await review.runDefenders({ tool, model: ctx.model, cwd, defenders, findings });
|
||
```
|
||
|
||
<a id="reviewsortfindings"></a>
|
||
### review.sortFindings
|
||
|
||
就地排序：嚴重→警告→建議，再依檔案路徑、起始行遞增；供 findings 保存與步驟 9／10 分組留言使用。
|
||
|
||
```js
|
||
review.sortFindings(kept);
|
||
```
|
||
|
||
<a id="reviewappendexclusions"></a>
|
||
### review.appendExclusions
|
||
|
||
把防守方判定排除（誤判／重複）的問題附加到 `.gitea/ai-review/exclusions.json`（含各防守方理由與來源 PR 編號）；既有檔案壞損或非陣列時不動原檔、記 WRN（需人工確認）。回傳是否有寫入，決定收尾是否一併 commit。
|
||
|
||
```js
|
||
const changed = review.appendExclusions({ cwd, excluded, prNumber: ctx.prNumber });
|
||
```
|
||
|
||
<a id="reviewsortfindingsforissue"></a>
|
||
### review.sortFindingsForIssue
|
||
|
||
建問題模式的就地排序：檔案路徑→嚴重等級（嚴重→建議）→起始行，讓 issue 留言同檔集中、便於逐檔處理。
|
||
|
||
```js
|
||
const sorted = [...kept];
|
||
review.sortFindingsForIssue(sorted);
|
||
```
|
||
|
||
<a id="reviewselectlabels"></a>
|
||
### review.selectLabels
|
||
|
||
以 AI 依 PR 標題／描述與問題列表摘要，從存取庫可用標籤挑選子集合（白名單過濾幻覺名稱後轉標籤 id）；無標籤或失敗一律回空陣列不阻斷。
|
||
|
||
```js
|
||
const labelIds = await review.selectLabels({ tool, model, cwd, labels, prTitle, prBody, findings });
|
||
```
|
||
|
||
<a id="reviewcreateissuewithfindings"></a>
|
||
### review.createIssueWithFindings
|
||
|
||
建問題模式主流程：AI 挑標籤 → 建立 issue（標題＝PR 標題、本文＝PR 描述＋追溯）→ 問題依檔案→嚴重度排序逐條留言到 issue；建 issue 失敗記 ERR 回 `null` 不阻斷主流程。
|
||
|
||
```js
|
||
if (ctx.createIssue && kept.length > 0) {
|
||
await review.createIssueWithFindings({ ctx, gitea, tool, model: ctx.model, cwd, findings: kept });
|
||
}
|
||
```
|
||
|
||
<a id="reviewresolveoldcomments"></a>
|
||
### review.resolveOldComments
|
||
|
||
步驟 2：bot 舊一般留言（非本回合）編輯加〔已過時〕前綴；review 行內留言盡力呼叫 resolve API，第一次失敗即判定版本不支援並停止。任何失敗只記 WRN 不阻斷。
|
||
|
||
```js
|
||
await review.resolveOldComments({ ctx, gitea, currentRunCommentIds });
|
||
```
|
||
|
||
<a id="reviewpostseverecomments"></a>
|
||
### review.postSevereComments
|
||
|
||
步驟 9：嚴重問題以單一 code review 逐條掛在對應程式碼行上（含問題區塊程式碼片段，最多 40 行）；建立 review 失敗時降級為一般留言逐條發布並在內文標明位置。
|
||
|
||
```js
|
||
if (severe.length > 0) {
|
||
await review.postSevereComments({ ctx, gitea, severe, cwd });
|
||
}
|
||
```
|