Toolbox on 愷的大冒險 Kai's Adventure

從模糊通訊到精確修復：如何運用 AI 協作、重構、除錯之開發工作流

Mon, 04 May 2026 00:00:00 +0800

在真實的軟體維護與開發場景中，任務往往不是從一份清晰的規格書開始，而是一長串雜亂的商業通訊或 Email；這篇文章將探討如何將 AI 融入日常工作流，從「接收業務抱怨」到「提交安全的程式碼變更」，把 AI 當作技術協作的思考夥伴，而不僅僅是一台代碼生成機；以下是運用 AI 提升遺留系統（Legacy System）維護效率與安全性的協作方法：

從商業語言萃取技術問題 ( Issue Intake & Hypothesis)

輸入來源：雜亂的商業通訊記錄、Email 討論串或 PDF。
協作模式：讓 AI 扮演第一線的「需求翻譯官」。
- 可以請 AI 閱讀長篇大論的討論串，從中剝離情緒與表面症狀，找出真正的需求。
- 接著，與 AI 討論根本原因的假設「這究竟是基礎設施層級的錯誤、系統整合失敗，還是單純的商業邏輯落差？」，這能有效避免我們在一開始就找錯系統層級，將「修復整合問題」的大方向，收斂為具體可行的技術行動。

系統勘查與新舊行為比對 (Reconnaissance & Comparison)

輸入來源：舊版系統的執行腳本與現有程式碼架構。
協作模式：在改動任何遺留系統前，釐清「過去的基準是什麼」至關重要。
- 我們可以將舊有的腳本或程式碼作為來源，讓 AI 協助比對現行程式碼中的執行路徑與邏輯斷層，透過比對列出遺失的商業規則（例如：時間視窗的處理、過濾邏輯的差異），而非不斷的對著錯誤代碼做猜測。

邊界談判與範圍收斂 (Scope Reduction & Constraint Negotiation)

輸入來源：比對結果與開發的限制及偏好。
協作模式：這是實務上最關鍵，卻常被忽略的一步。
- 告訴 AI 你的底線，例如：「不引入新的抽象層」、「不改動共用的核心模組」、「避免不必要的全域設定（Global config）重構」，甚至限制修改的檔案數量。
- 與 AI 進行條件談判，將原本龐大的系統修復目標，限縮為風險最低的最小程度變更，良好的維護不僅追求技術上的正確，更要契合團隊習慣、邊界與上線風險。

迭代規劃與微創實作 (Iterative Implementation)

輸入來源：收斂後的執行計畫與動態的環境反饋。
協作模式：在遺留系統中，修復計畫很少是一次到位的。
- 隨著開發進行或外部設定的調整，必須隨時與 AI 重新校準範圍；在撰寫程式碼時，嚴格要求 AI 僅針對痛點進行最小化修補，保留不想更動的既有邏輯，確保修改範圍集中，不引發大範圍的架構震盪。

版本控制與技術敘事 (Git Hygiene & Technical PR Narrative)

輸入來源：最終測試通過的程式碼差異 (Diff) 與工作紀錄。
協作模式：修補完成後，AI 也能協助提升版本控制的品質。
- 可以請 AI 協助檢視改動，並建議如何拆分為原子化提交（Atomic Commits，確保單一檔案或單一邏輯獨立提交）。
- 此外，在未審核的前提下，讓 AI 根據你的習慣草擬 PR(Pull Request)，好的 PR 能清楚交代修改動機、改變了什麼、沒改變什麼，這是給審查者最好的技術文件，也能大大加速 Code Review 的流程。

透過上述方法，AI 能夠成為引導診斷與控制範圍的最佳助手，讓我們重新思考軟體維護的工作流，可以是「萃取意圖、比對行為、收斂範圍、最小化實作，將過程沉澱為可重複的技術」，讓每次的修復都更安全、更精準且具備高度可追溯性。

搶救儲值金：OpenCode + OpenRouter 的背景扣費，配置 Small Model 心得分享

Sun, 03 May 2026 00:00:00 +0800

承續上篇 OpenCode 搭配 OpenRouter 的踩坑紀錄：意外的模型扣費之謎，在今日反覆測試之後，終於找到了初步的解決之道。

今日行動：馴服 OpenCode 的設定檔

為了拿回控制權，嘗試透過設定檔明確指定 small_model，在摸索過程中排除了幾個關鍵障礙：

路徑迷蹤：在 Windows 系統上，OpenCode 的設定檔位置並非在安裝目錄，而是位於 %USERPROFILE%\.config\opencode\opencode.jsonc。
格式陷阱：模型設定必須是頂層字串格式；我曾嘗試使用巢狀物件（nested objects）來描述模型屬性，但這會導致解析錯誤。
聯動依賴（關鍵）：這是過程中遇到的最大阻礙，如果只單獨設定 small_model 而忽略了 model 的宣告，OpenCode 會噴出 ConfigInvalidError 並導致 Session 無法載入；兩者必須同時存在於設定檔中。
Model ID 命名：Model ID 格式不需要額外加上 openrouter/ 前綴，直接使用原廠定義的 ID 即可。

最終有效的設定方案

經過多次失敗與修正，整理出這份能讓 OpenCode 穩定啟動的 opencode.jsonc 範例：

1{
2 "$schema": "https://opencode.ai/config.json",
3 "model": "google/gemini-3.1-pro-preview", // 主模型設定
4 "small_model": "google/gemini-3-flash-preview" // 強制指定背景任務使用的模型，避免自動選取導致額外扣費
5}

目前設定檔已能成功讓 OpenCode 運行，不再發生啟動失敗的問題。

不過，這項修正是否能完美杜絕「意外扣費」，仍需觀察 OpenRouter 的 Generation Data；目前正在等待後台出現 Gemini 3 Flash Preview 的請求紀錄，以便驗證 OpenCode 是否確實將背景任務轉發到指定的 BYOK 模型上。

OpenCode 搭配 OpenRouter 的踩坑紀錄：意外的模型扣費之謎

Sat, 02 May 2026 00:00:00 +0800

今天在開發時，遇到了一個有趣但也讓人有點困擾的狀況；使用的開發環境是 OpenCode 搭配 OpenRouter，主模型則是透過 OpenRouter BYOK (Bring Your Own Key) 綁定 Google AI Studio API Key 的 Google Gemini 3.1 Pro。

本來預期所有的花費都會走自己的 Key，享受免費或可控的額度，沒想到卻在 OpenRouter 的後台發現了預期之外的扣費紀錄。

案發現場：被悄悄觸發的背景請求

透過檢查 OpenRouter Log 的 Generation Data，我發現 OpenCode 在使用過程中，背景會自動觸發額外的 API 請求，而這些請求的行為跟我的全域設定完全不同：

模型被切換：請求並沒有發給 Gemini，而是被發送到了 anthropic/claude-haiku-4.5。
Provider 改變：走的是 Amazon Bedrock（OpenRouter 自己的後端）。
BYOK 失效：紀錄顯示 is_byok: false，代表這筆請求沒有走我綁定的 Key，而是直接扣除了我 OpenRouter 帳戶裡的餘額。
用量特徵：tokens_prompt: 603, tokens_completion: 10，典型的輕量級背景任務用量，且 origin 標示為 https://opencode.ai/。

推測原因：獨立的 Small Model 機制

仔細調查與推敲後，我認為這跟 OpenCode 底層的任務分發機制有關。

OpenCode 內部應該有一個獨立的 small_model 機制，專門用來處理像是「生成 Session 標題」、「壓縮摘要 Context」這類不需要強大推理能力的輕量級背景任務。

如何在 Claude Code 中透過 OpenRouter 串接第三方模型

Fri, 01 May 2026 00:00:00 +0800

在 AI 輔助開發的過程中，為了能自由體驗更多不同模型的特性，無論是想測試各家模型在特定任務上的表現，還是單純想感受如 DeepSeek V4 Pro 這類強大開源模型的邏輯推演能力，需要有彈性的開發環境；這篇文章將分享如何透過簡單的配置，讓你在 Claude Code 中解鎖模型限制，串接 OpenRouter 的豐富的第三方模型。

引導 CLI 走向 OpenRouter

要讓 Claude Code 放棄預設的官方伺服器並將請求轉發至 OpenRouter，我們需要設定特定的環境變數。

關鍵技巧：必須將官方的 ANTHROPIC_API_KEY 留空；這樣可以完全避免 CLI 預設去向 Anthropic 伺服器進行驗證而產生錯誤，確保所有的請求都乾淨地透過 ANTHROPIC_AUTH_TOKEN 轉發。

在終端機（以 PowerShell 為例）輸入以下指令：

1$env:ANTHROPIC_BASE_URL = "https://openrouter.ai/api"
2$env:ANTHROPIC_AUTH_TOKEN = "Your_OpenRouter_API_Key"
3$env:ANTHROPIC_API_KEY = ""

抽換 Claude Code 的邏輯大腦

Claude Code 實際運作時，會根據任務的複雜度自動調度不同的模型，例如：預設會使用 Sonnet 來做快速的檔案結構掃描與意圖判斷，然後用 Opus 進行核心的程式碼生成與重構。

與其單純設定單一的 $env:ANTHROPIC_MODEL，更進階且優雅的做法是直接覆寫預設的任務模型；我們可以將 DeepSeek V4 Pro 部署在最關鍵的主力開發位置：

1# 將負責核心邏輯與重構的 Model 替換為 DeepSeek V4 Pro，也可以視需求將輕量級任務指派給其他反應更快的模型
2$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "deepseek/deepseek-v4-pro"
3$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "deepseek/deepseek-v4-pro"
4$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "deepseek/deepseek-v4-pro"

透過覆寫這些特定變數，等於讓不同的第三方模型各司其職，精準對應到不同的思考與執行階段。

AI 模型聚合平台 OpenRouter 靈活性與隱私的平衡

Thu, 30 Apr 2026 00:00:00 +0800

在 AI 快速迭代的當前，開發者可能會面臨著兩難，是應該忠於單一模型供應商（如：Anthropic、Google、OpenAI），還是擁抱具備高 CP 值的開源模型（如：DeepSeek、GLM、Kimi、Qwen）？ OpenRouter 作為一個 AI 模型的聚合平台（Aggregator），為開發者提供了一種「抽象層」解決方案。

核心價值：API 的統一與抽象化

OpenRouter 的本質是將零散的模型市場標準化，透過單一的進入點（Single Entry Point），開發者可以獲得以下優勢：

介面標準化：無論底層模型是由哪家廠商提供，OpenRouter 均將其封裝為相容 OpenAI 的 API 格式；這意味著開發者在進行模型切換時，只需更改一個字串參數，而無需重新調整程式碼邏輯。
供應商多樣性：同一個模型（如： Llama 4）可能由多家算力供應商（Providers）代管；OpenRouter 會根據延遲、價格與可靠性進行動態路由，確保服務的穩定。
支付統一化：開發者無需在數十家供應商分別綁定信用卡，僅需在單一錢包儲值，即可跨模型、跨廠商消費。

隱私防線：理解「零資料留存 (ZDR)」

對於處理程式碼與商業邏輯的開發者而言，隱私是選擇平台時的首要考量；OpenRouter 在隱私保護上建立了一套透明的過濾機制，其核心在於 ZDR (Zero Data Retention)。

ZDR 的定義：當模型標註為 ZDR 時，代表供應商承諾不會將資料存入磁碟，資料僅在記憶體中進行即時推理，且絕對不會被用於後續的模型訓練。
過濾機制：OpenRouter 允許用戶設定「強制執行 ZDR」；一旦開啟，系統將自動屏蔽所有不符合該隱私標準的供應商，確保資料路徑的純粹。
訓練權限的權衡：平台提供了細緻的開關，讓用戶決定是否接受「以數據換取折扣」的節點；對於測試性質的對話，用戶可選擇較便宜的非 ZDR 節點；而對於涉及敏感專利的開發工作，則可一鍵切換至高強度隱私模式。

成本管理與透明化

OpenRouter 的另一大特色在於其透明的定價模型；相較於原廠通常具備的固定分層計費（Tiers），聚合平台提供了更細粒度的選擇：

動態降價：由於聚合了多家供應商，平台競爭往往會推動價格低於原廠官方定價。
免費額度與贊助：許多新興模型為了推廣，會透過 OpenRouter 提供限時或限量的免費節點，成為開發者進行「模型選型」時的最佳實驗場。

策略建議

對於正處於嘗試期、尚未決定核心模型的開發者，建議採取以下策略：

實驗階段（探索期）：利用 OpenRouter 的統一 API 進行對照測試，觀察不同模型在特定領域（如：程式碼生成或長文本推理）的優劣。
隱私分級：
- 通用技術詢問：可選用具備成本優勢的非 ZDR 免費節點。
- 專案程式碼實作：建議開啟 Always enforce ZDR，並關閉所有涉及「資料用於訓練」的選項。
架構解耦：在專案初期即採用 OpenRouter 的抽象接口，為未來隨時切換至更高性能或更廉價的模型預留空間。

OpenRouter 不僅是 API 轉發站，更是間接定義了「模型消費標準」的協議層，對於追求靈活性與技術前瞻性的人而言，可以從繁瑣的帳務管理與格式轉換中解放，並在保護數據隱私的前提下，以最低的摩擦成本享受 AI 技術的最新成果。

AI 應用的效率指標：Cache Hit Rate 快取命中率

Mon, 27 Apr 2026 00:00:00 +0800

在當前的 AI 領域，Cache Hit Rate（快取命中率）已不再僅僅是後端開發的專有名詞，它已成為衡量大語言模型（LLM）應用效率、成本控制與反應速度的最核心指標之一。

什麼是 Cache Hit Rate？

在 API 呼叫的脈絡下，Cache Hit Rate 指的是模型在處理請求時，能夠直接從快取中讀取「已計算過的前綴（Prefix）」的比例。其計算方式如下：

Cache Hit Rate = 快取讀取 Token 數 / (快取讀取 Token 數 + 快取寫入 Token 數 + 一般輸入 Token 數)

當命中率越高，代表模型重複運算的次數越少，整體的執行效率也就越高。

為什麼快取命中率如此重要？

Cache Hit Rate 對於生產環境中的 AI 應用有三大直接影響：

成本大幅下降：快取讀取的費用通常遠低於原始輸入；以某些供應商為例，快取讀取僅需原價的 10%；如果命中率從 90% 降至 70%，整體的運算成本幾乎會翻倍。
回應速度提升：跳過重複的預運算過程可以顯著減少首字反應時間（TTFT），尤其在 Context（上下文）越長的情況下，提速感越明顯。
配額（Quota）保護：高命中率能減少 Token 的淨消耗，避免開發者或訂閱用戶在短時間內觸發服務上限。

在頂尖的 AI 開發團隊中，Cache Hit Rate 被視為與系統「可用性（Uptime）」同等重要的核心指標，一旦命中率異常過低，便會觸發告警機制進行排查。

常見的快取破壞行為

要維持高命中率，必須避免以下幾種會導致快取失效的行為：

頻繁切換模型：快取通常無法跨模型共用。
超過 TTL（生存時間）：快取具有時效性，若閒置時間過長，快取將被自動清除。
內容擾動：修改 System Prompt、AGENTS/CLAUDE.md 或變動 Tool 定義的順序，都會導致前綴無法匹配，必須重新建立快取。
工作節奏不連貫：長時間的閒置（Idle）會導致重建成本增加。

對於一個穩定運行的 AI Session，90% 的快取命中率是理想的健康標準；如果長期低於 70%，開發者就應重新檢視提示詞（Prompt）的結構順序或快取生存時間的設定。

導入 AI 的決策：「預留算力」與「按量計費」

Sun, 26 Apr 2026 00:00:00 +0800

隨著生成式 AI 深入企業內部流程與產品，算力的「穩定性」與「成本控管」成為 IT 架構的重大考驗；在雲端 AI 模型（如 Azure OpenAI）的部署上，企業通常面臨兩種資源配置模式：「按量計費 (Pay-as-you-go)」與「預留算力 (Provisioned Throughput)」。

這兩者不僅僅是計費方式的差異，更直接決定了企業級 AI 應用的可靠度與未來擴展性。

核心概念：美食街與專屬包廂

按量計費 (Pay-as-you-go)：就像在熱門的美食街用餐；人少時很快就能買到餐點，但在尖峰時段必須跟所有人排隊競爭資源，甚至可能因為人潮爆滿而被拒絕服務（觸發限流）。
預留算力 (Provisioned)：就像在高級餐廳長期預訂了一間專屬包廂；不論何時抵達、吃多快或吃多慢，這個空間永遠為你保留；即使今天沒去用餐，包廂費依然要付，但換來的是絕對的保障與尊榮體驗。

預留算力能消除網路延遲嗎？

許多人誤以為購買預留算力後，跨國連線的延遲就會消失，這是一個迷思；在跨海調用 AI 模型時，我們需要區分兩種延遲：

物理傳輸延遲（不變）：資料在光纖中跨國傳輸的物理時間（如台灣到美國的 0.2 秒）；這是受物理法則限制的，無論買多少算力都不會改變。
伺服器排隊延遲（完全消除）：這是請求到達雲端機房後，等待 GPU 撥出空檔運算的時間。

預留算力的威力，在於為企業開闢了一條專屬的高架快速道路；物理距離的里程數沒變，但永遠不會遇到「塞車」；這讓 AI 回應的「體感速度」大幅提升，且每次呼叫的等待時間都會變得高度一致。

從財務與營運角度的綜合評估

從帳面上看，預留算力是一筆不小的固定支出，但對於重度依賴 AI 的企業而言，往往是更划算的投資：

變動成本轉化為固定成本：企業能精確預估年度 AI 預算，不再擔心因為內部員工或外部客戶的突然爆量使用，導致下個月收到天價帳單。
規模經濟的黃金交叉：當企業的 AI 總體用量（Token 消耗量）達到一定規模時，預留算力所帶來的折扣，將使其平均單價遠低於按量計費。
釋放開發潛能：開發團隊不再需要為了遷就「限速（Rate Limit）」而撰寫複雜的重試邏輯或刻意降低處理速度；團隊可以放心開發高併發、大批次的自動化代理任務（Agentic Workflows），最大化 AI 的價值。

「預留算力」不僅僅是一種付費方案，更是企業將 AI 視為關鍵數位基礎設施的宣示；它用固定的金錢成本，買到了極致的系統穩定度、可預測的效能，以及無後顧之憂的開發自由度；對於準備將 AI 投入大規模生產環境的企業來說，這是邁向成熟應用的必經之路。

如何透過 Microsoft Foundry 部署的模型設定 Codex

Sat, 25 Apr 2026 00:00:00 +0800

為什麼會想寫這篇文章呢？主要是因為我發現，現在還是有不少人在使用免費版的 AI 工具；同時，許多企業也正嘗試在雲端環境（例如透過 Microsoft Foundry）部署專屬的高階模型，卻往往卡在不知道如何設定，或部署完後不知道該如何串接到實際的工具中使用。

因此，我決定把這篇心得分享出來，我會帶大家從雲端部署開始，一路到如何將模型成功串接到 Codex 上進行實戰；不管你是精打細算的「無課金御主」，還是正在為公司尋找解決方案的工程師，這篇文章都會是你的實作指南。

在正式進入雲端部署之前，我們需要先準備好手邊的武器；首先，必須要先有個 Azure 帳號（如果還沒有可以去申請一個，微軟通常有提供免費額度可以試玩）；接下來，我們需要安裝對接的工具，可以選擇安裝有圖形介面的 Codex App；如果習慣敲打鍵盤、熱愛終端機，也可以選擇安裝 Codex CLI，兩者擇一即可。

建立 Azure 訂閱

準備好 Azure 帳號後，我們登入 Azure；要部署任何雲端資源之前，我們都必須先建立一個「訂閱 (Subscription)」，這就像是你在雲端上的專屬帳單與資源管理帳戶。

請跟著以下步驟做：

在 Azure 首頁上方的搜尋列，輸入並點選 「訂閱 (Subscriptions)」。
進入頁面後，點擊左上角的 「+ 新增 (Add)」。
選擇適合你的方案：
- 如果是初次體驗的無課金玩家，建議選擇「免費試用 (Free Trial)」，微軟會提供一筆免費額度讓你無痛跟著這篇教學實作。
- 如果是為公司部署，則可以選擇「隨用隨付 (Pay-As-You-Go)」或是套用你們公司既有的企業合約。

透過 AI Foundry 建立你的第一個 Agent

當我們進入 Microsoft AI Foundry 的首頁後，會發現介面非常現代化，與其在後台設定一堆看不懂的雲端資源，微軟現在提供了一個更直覺的起手式！

請跟著以下步驟做：

直接點擊畫面上非常醒目的「Create an agent (建立代理程式)」按鈕。
這個按鈕就像是一個智慧嚮導，點擊後系統會開始引導你建立「專案（Project）」。
在建立專案的設定畫面中，系統同樣會讓你選擇前面準備好的「訂閱方案」，這時候就可以直接點選新建一個資源群組（Resource Group），把底層的煩人設定一次搞定！

挑選大腦：部署你的 GPT-4.1 模型

當 Agent 建立完成後，畫面會自動彈出「Deploy a model」的邀請，這就是我們要幫 AI 安裝「大腦」的時刻。

請跟著以下步驟做：

進入模型目錄：點擊部署後會看到琳瑯滿目的模型清單；請直接搜尋並選擇你心儀的高階模型，本文會以「GPT-4.1」作為示範。
自訂部署名稱：這裡建議取一個好記的名字，例如 gpt-4.1；請記住這個名字，因為待會我們在 Codex 串接時會用到它。
調整性能指標 (TPM)：部署時會有一個「Tokens Per Minute (TPM)」的拉桿；如果你是個人測試或初學者，設定一個適中的數值即可，這樣既能保證反應速度，也能有效控管預算。
點擊「Deploy」後，稍微等待幾分鐘，你的專屬雲端模型就正式上線了！

取得連接憑證：找到正確的「通訊位址」

模型部署好了，接著我們要去撈取連接用的憑證；這裡有個非常重要的細節，請大家一定要看清楚，因為這是最容易出錯的地方！

Cursor Meetup：從 Vibe Coding 到 AI Agent 的自我進化

Sun, 19 Apr 2026 00:00:00 +0800

前陣子參加了一場收穫滿滿的 Cursor Meetup，現場聚集了許多對使用 AI 工具開發充滿熱情的夥伴，從實戰 App 開發到複雜的 Agent 架構設計都有精彩討論；我整理了三位參與者的核心分享，這不僅是技術交流，更是對未來工作流的重新想像。

創意與開發的平衡，讓 AI 更懂你自己

參與者 A 分享了如何利用 AI 打造行程規劃 App，他提出了一個非常有人性的切入點：連點子都能由 AI 幫你量身打造。

用 Shared Memories 塑造人格：可以透過 ChatGPT 的「長期記憶（Shared Memories）」功能，持續餵養你的興趣、偏好與生活習慣；這樣一來當你缺乏靈感時，AI 能根據它對你的了解，主動提議對你真正有幫助的功能；這不再只是寫程式，而是 AI 在幫你優化生活。
Vibe Coding 視覺先行：在開發初期，可以先請 AI 列出幾種建議的 UI 風格；因為在 Vibe Coding 的模式下，AI 產出的介面很容易趨同，先選定風格（Vibe）才能確保產品有獨特性。
開發流程的取捨：對於追求速度的開發者，傳統的 SDD (設計文件) 或 TDD (測試驅動) 並非絕對必要；但在「放手讓 AI 自由生長」時，這些規範反而成了最好的約束工具，能確保 AI 清楚交代工作內容，不至於寫出沒人看得懂的黑盒子。

分工合作藝術，用 Subagent 突破 Token 上限

參與者 B 展示了如何打造一個專業的「翻譯 Agent」，重點在於不要讓一個 AI 做所有的事；將任務拆解成多個 Subagent（子代理），就像精密的流水線這種「專業分工」能完美解決 AI 記憶力（Token 上限）不足的問題，讓翻譯長文不再斷頭斷尾。

結構化：先把文件轉成標題分明的 Markdown（例如 # 第一章）。
分段搬運：按照標題順序，把內容一段段餵給翻譯模組。
精準翻譯：在不變動格式的前提下完成翻譯。
組裝與導出：最後再進行編排、彙整，並轉為 PDF。
核心邏輯：每個子代理都只讀取專屬的指令檔（SKILL.md），透過一位「總指揮」調度，最後再加上人工 Review。

自我進化系統，打造專屬AI 技能庫

參與者 C 則分享了讓 Agent 變聰明的流程（例如 Moltbot），這類 Agent 具備「學習」的能力：