From 409536b34133818d2ae69a22c7d2bb153b399523 Mon Sep 17 00:00:00 2001
From: Jeffery <jiantw83@yahoo.com>
Date: Fri, 7 Aug 2026 08:48:50 +0000
Subject: [PATCH] =?UTF-8?q?docs(ai-review=20=E8=A8=BB=E8=A7=A3):=20?=
 =?UTF-8?q?=E6=94=B6=E6=96=82=E8=A8=BB=E8=A7=A3=E8=88=87=E8=85=B3=E6=9C=AC?=
 =?UTF-8?q?=E9=9B=9C=E8=A8=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 entrypoint.sh   |  5 +----
 src/comments.js | 30 +++++++++---------------------
 src/findings.js | 16 ++++++----------
 src/log.js      |  2 +-
 src/main.js     |  3 ---
 5 files changed, 17 insertions(+), 39 deletions(-)

diff --git a/entrypoint.sh b/entrypoint.sh
index 33e36a7..7fd80d0 100755
--- a/entrypoint.sh
+++ b/entrypoint.sh
@@ -1,8 +1,5 @@
 #!/bin/sh
-# ============================================================================
-# 用途：Docker 容器 action 的進入點腳本，於容器啟動時執行 Node 主程式並轉傳所有參數。
-# 更新時間：2026/08/07 13:51:53
-# ============================================================================
+# Docker 容器 action 的進入點腳本，於容器啟動時執行 Node 主程式並轉傳所有參數。
 
 # 遇到任何指令執行失敗時立即中止腳本，避免錯誤被吞掉而繼續往下執行
 set -e
diff --git a/src/comments.js b/src/comments.js
index a14a8db..f0d497a 100644
--- a/src/comments.js
+++ b/src/comments.js
@@ -235,28 +235,16 @@ function toReviewComment(f) {
 }
 
 /**
- * 發布單一 Gitea review：一次性送出「統計摘要 + 逐筆行內 review comment」，並提供多層降級機制。
- *
- * @param {Array<object>} findings 本次審查的完整 findings 陣列；當 `deps.summaryFindings` 或
- *   `deps.commentFindings` 未提供時，兩者皆預設使用此參數。
- * @param {object} [deps={}] 可覆寫的相依注入物件（主要供測試替換，正常情境可省略）。
- * @param {Function} [deps.postReview=postPullReview] 發布整批 review（含 body 與 comments）的函式。
- * @param {Function} [deps.postInline=postPullReviewComment] 發布單筆行內 review comment 的函式。
- * @param {Function} [deps.postIssue=postComment] 發布一般（非 review）comment 的函式，作為最終降級手段。
- * @param {Array<object>} [deps.summaryFindings=findings] 用於統計本文數字（含新舊問題）的 findings 子集合。
- * @param {Array<object>} [deps.commentFindings=findings] 用於產生 review comments 的 findings 子集合；
- *   會先依 {@link bySeverity} 排序，僅新問題（`is_new !== false`）會被轉成行內 comment，
- *   舊問題只計入統計、不再重複標註檔案與行數。
- * @param {string} [deps.usageSection=''] 附加在統計表之後的用量／token 統計區塊；空字串時不附加。
+ * 發布單一 Gitea review，必要時會先降級成 summary review，再降級成一般 comment。
+ * @param {Array<object>} findings 審查 findings。
+ * @param {object} [deps={}] 可注入的相依物件。
+ * @param {Function} [deps.postReview=postPullReview] 發布整批 review 的函式。
+ * @param {Function} [deps.postInline=postPullReviewComment] 發布單筆行內 comment 的函式。
+ * @param {Function} [deps.postIssue=postComment] 發布一般 comment 的降級函式。
+ * @param {Array<object>} [deps.summaryFindings=findings] 用於統計的 findings 子集合。
+ * @param {Array<object>} [deps.commentFindings=findings] 用於建立 review comments 的 findings 子集合。
+ * @param {string} [deps.usageSection=''] 附加的使用量區塊。
  * @returns {Promise<void>} 無回傳值。
- * @remarks
- *   降級順序：① 整批 `postReview`（含 comments）→ 失敗則 ② 僅 body 的 `postReview`
- *   （comments 為空陣列）→ 失敗則 ③ `postIssue(body)`。**注意：③ 未包在 try/catch 中**，
- *   若 `postIssue` 本身失敗，例外會直接從本函式往外拋出（reject），呼叫端須自行 catch。
- *   無論走到哪一步，只要走完 ①～③ 中任一步不再往下失敗，後續都會逐筆嘗試 `postInline` 補發
- *   行內 comment，每筆各自失敗僅記錄 warn 並略過，不影響其他筆。
- *   使用情境：CI 流程完成一輪 AI Code Review 後，呼叫一次本函式即可把整批結果發布到 Gitea PR；
- *   單元測試時可透過 `deps` 注入假的 `postReview`/`postInline`/`postIssue` 以驗證各降級分支。
  */
 export async function postFindingsReview(findings, deps = {}) {
   const {
diff --git a/src/findings.js b/src/findings.js
index 6a2545e..e8f8c2f 100644
--- a/src/findings.js
+++ b/src/findings.js
@@ -411,16 +411,12 @@ function extractFileDiff(diff, file) {
 }
 
 /**
- * 對「只有檔名、缺行號」的 findings，反問原角色依該檔 diff 找出行號，
- * 重複嘗試直到取得有效行號（每條最多 maxAttempts 次，避免無限迴圈）；
- * 成功則直接修改（mutate）該 finding 的 location 為 `檔案:行號`，否則保留原檔名不變。
- * 各條 finding 以獨立 LLM 呼叫並行定位，併發上限見 concurrency。
- *
- * @param {Array<object>} findings - findings 陣列；缺行號且有檔名者會被就地修改 location（mutate），其餘不受影響。
- * @param {string} diff - 完整 unified diff，用於擷取各檔案對應區段作為定位依據。
- * @param {{chatFn?: Function, getRole?: Function, maxAttempts?: number, concurrency?: number}} [deps] - 依賴注入（利於測試）：
- *   chatFn 預設 chatJSON；getRole 預設 loadRole；maxAttempts 預設 3（MAX_LOCATE_ATTEMPTS）；concurrency 預設 LLM_CONCURRENCY。
- * @returns {Promise<Array<object>>} 與傳入 findings 相同參照的陣列（部分項目的 location 已被就地修改）。
+ * 對缺行號的 findings 重新詢問原角色補上行號，成功時會就地更新 `location`。
+ * @param {Array<object>} findings findings 陣列。
+ * @param {string} diff 完整 unified diff。
+ * @param {{chatFn?: Function, getRole?: Function, maxAttempts?: number, concurrency?: number}} [deps]
+ *   測試用依賴注入。
+ * @returns {Promise<Array<object>>} 與傳入相同參照的 findings 陣列。
  */
 export async function resolveMissingLineNumbers(findings, diff, deps = {}) {
   const { chatFn = chatJSON, getRole = loadRole, maxAttempts = MAX_LOCATE_ATTEMPTS, concurrency = LLM_CONCURRENCY } = deps;
diff --git a/src/log.js b/src/log.js
index e02533a..83a8c74 100644
--- a/src/log.js
+++ b/src/log.js
@@ -6,7 +6,7 @@
  * @returns {string} 例如 `2026/08/07 12:39:43`。
  */
 function formatTimestamp(date = new Date()) {
-  const parts = new Intl.DateTimeFormat('en-CA', {
+  const parts = new Intl.DateTimeFormat('zh-TW', {
     timeZone: 'Asia/Taipei',
     year: 'numeric',
     month: '2-digit',
diff --git a/src/main.js b/src/main.js
index 1f3528e..73b3014 100644
--- a/src/main.js
+++ b/src/main.js
@@ -53,9 +53,6 @@ const WORKSPACE = process.env.GITHUB_WORKSPACE || '/workspace';
  * 降級處理：Step4 對話收斂、Step5 角色介紹 comment 與個別角色分析、Step6 clone repo、
  * Step8 Review 發布等非致命步驟失敗時，僅 `warn` 後繼續執行。
  *
- * 目前程式碼中有 3 個 exit 1 呼叫點（未設定 CLIProxyAPI、取 diff 失敗、所有角色分析皆失敗）
- * 退出前未呼叫 `section('Pipeline 結束')`，與其餘 exit 點不一致，會少一行收尾分隔線，
- * 是否為刻意設計尚需人工確認。
  */
 export async function main() {
   section('AI Code Review Pipeline');