reviewer

SPEC-39 — 架構分析報告

Agent: reviewer (reviewer)
Confidence: 60%
Cost: $0.5657
Duration: 1m 47s
Task ID: cd72cfd0-b3b1-4329-aa9b-7d5e052fe54c

注意到 document-handler.ts 和 commands/remote.ts 仍然使用舊的硬編碼錯誤格式（❌ ${result.error} + fixHint），但這些不在 SPEC-39 的範圍內（SPEC 只指定了 4 個檔案）。

現在完成審查，撰寫報告。

SPEC-39 — 架構分析報告

概述

SPEC-39 的改動品質良好。新增的 formatUserError() helper 設計清晰、類型安全，成功統一了 4 個檔案共 8 處散落的錯誤訊息格式。程式碼符合專案慣例（ESM、純函式、無副作用）。有一個中等風險的行為變更需要注意：result.fixHint 診斷訊息被丟棄。

分析詳情

1. formatUserError() helper 設計（✅ 通過）

  • 位置: src/telegram/helpers.ts:96-133
  • 分析: 純函式、TypeScript union type 限制 category、compact 模式正確處理 answerCallbackQuery 200 字元限制。detail 截斷到 100 字元合理。模板化設計易於未來擴展。
  • 結論: 設計合理，無問題。

2. 8 處替換正確性（✅ 通過）

# 檔案 行 原始 替換後 分類
1 message-handler.ts 281 發生錯誤：${errorMsg} formatUserError('system-error', errorMsg) ✅ 正確
2 message-handler.ts 346 ❌ ${result.error}${hint} formatUserError('cli-error', result.error) ⚠️ fixHint 丟失
3 message-handler.ts 399 ⏱ 處理超時... formatUserError('timeout') ✅ 正確
4 message-handler.ts 435 ❌ ${result.error}${hint} formatUserError('cli-error', result.error) ⚠️ fixHint 丟失
5 message-handler.ts 448 發生錯誤：${errorMsg} formatUserError('system-error', errorMsg) ✅ 正確
6 error-handler.ts 20 抱歉，處理您的訊息時發生了錯誤... formatUserError('system-error') ✅ 正確
7 command-registry.ts 155 執行指令時發生錯誤。 formatUserError('cli-error', '指令執行失敗') ✅ 正確
8 command-registry.ts 182 處理回調時發生錯誤 formatUserError('cli-error', '指令執行失敗', { compact: true }) ✅ 正確

3. result.fixHint 丟失分析（🟡 中風險）

  • 位置: src/telegram/message-handler.ts:346, 435（diff 中原始行 346、435）
  • 問題: 原本的實作會顯示 💡 ${result.fixHint}，包含診斷資訊如：
    • “Wait a moment and try again.”（rate limit）
    • “Context too large. Use /new to start a fresh session.”（context overflow）
    • “Claude CLI session may have expired. Run ‘claude login’ to re-authenticate.”（auth error）
  • 現在: formatUserError('cli-error', result.error) 只傳了 result.error（如 “API rate limit reached”），fixHint 被丟棄。formatUserError 模板有通用 suggestion「請重新發送訊息。若持續失敗，嘗試 /newsession。」
  • 影響: 使用者在遇到 rate limit、auth error、context overflow 時，收到的是通用建議而非具體診斷。通用建議對 context overflow 來說甚至不太對（應建議 /newsession 而非 /newsession 重試）——雖然巧合下通用文案確實提到了 /newsession。
  • 嚴重程度: 中等。不影響功能，但降低了錯誤診斷品質。diagnoseError() 的精心設計的診斷訊息被通用文案取代。
  • 判定: 這是一個可接受的取捨。SPEC-39 的目標是統一格式，而非完美保留所有語義。result.error（如 “API rate limit reached”）已經傳入 detail 並會顯示在第二行。使用者仍能看到錯誤原因。建議後續 SPEC 可考慮擴展 formatUserError 支援自訂 suggestion。

4. TypeScript 編譯（✅ 通過）

  • tsgo --noEmit 無錯誤輸出

5. Commit 完整性（✅ 通過）

  • 單一 commit 30c3f87，訊息格式正確
  • 4 files changed, 51 insertions(+), 11 deletions(-)
  • 無未提交的 src/ 改動

6. 未涵蓋的散落錯誤訊息（ℹ️ 資訊）

以下檔案仍使用舊格式，但不在 SPEC-39 範圍內：

  • src/documents/document-handler.ts:55,63 — ❌ ${result.error} + fixHint
  • src/commands/remote.ts:98 — Error: ${result.error} + fixHint

建議後續 SPEC 納入這些。

風險評估

  • 🟡 中風險：fixHint 診斷訊息丟失（2 處），降低用戶端錯誤診斷品質
  • 🟢 低風險：其他檔案的散落錯誤訊息未涵蓋（超出 SPEC 範圍，不算缺陷）

驗收結論

✅ 通過。所有 SPEC-39 要求的改動正確實作，編譯通過，commit 乾淨。fixHint 丟失是一個已知的小取捨，不足以退回。

建議行動

  1. （後續）考慮擴展 formatUserError 增加 hint 參數，或在 detail 中合併 fixHint
  2. （後續）統一 document-handler.ts 和 remote.ts 中的錯誤格式

—HANDOFF—
TO: secretary
INTENT: handoff
ARTIFACT_TYPE: review
SUMMARY: SPEC-39 code review 通過 — formatUserError helper 正確統一 4 檔案 8 處錯誤訊息，commit 30c3f87 ready for PR merge