<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>PingChun</name>
  </author>
  <generator uri="https://hexo.io/">Hexo</generator>
  <id>https://calmkoala.github.io/</id>
  <link href="https://calmkoala.github.io/" rel="alternate"/>
  <link href="https://calmkoala.github.io/atom.xml" rel="self"/>
  <rights>All rights reserved 2026, PingChun</rights>
  <subtitle>One is never too old to learn</subtitle>
  <title>CalmKoala</title>
  <updated>2026-11-22T16:09:03.631Z</updated>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="開發" scheme="https://calmkoala.github.io/categories/study-notes/%E9%96%8B%E7%99%BC/"/>
    <category term="自動化" scheme="https://calmkoala.github.io/tags/%E8%87%AA%E5%8B%95%E5%8C%96/"/>
    <category term="Telegram" scheme="https://calmkoala.github.io/tags/Telegram/"/>
    <content>
      <![CDATA[<p>通知內容都整理好了，卻卡在最後一步，送到 Telegram 時收到 <code>400</code>。明明只是一段文字，加個標題、放個版本號，怎麼連送出去都成了問題。</p><p>我做每日推播的小工具時，就修過這種錯誤。當時開啟了 Telegram 舊版 Markdown 格式，讓文字可以顯示粗體等排版，內容裡的特殊字元卻讓整則訊息被拒收。後來的修正包含兩件事，改用 MarkdownV2，並在送出前把內容轉成它接受的寫法。</p><p>光換模式還不夠，文字也得跟著處理。</p><span id="more"></span><h2 id="文字裡的符號，也可能是格式指令"><a href="#文字裡的符號，也可能是格式指令" class="headerlink" title="文字裡的符號，也可能是格式指令"></a>文字裡的符號，也可能是格式指令</h2><p>平常看 <code>build_2.0</code>，會覺得它只是個版本名稱。但開啟格式解析後，底線可能有斜體的意思，星號可能是粗體的開始，方括號則可能進入連結語法。程式認為自己在傳文字，Telegram 卻會依照指定的模式，把其中一些符號當成排版指令。</p><p>都叫 Markdown，寫法卻不一定相同。Telegram 的 <code>Markdown</code> 是保留相容性的舊模式，<code>MarkdownV2</code> 有另一套規則；平常在 Markdown 文件裡寫的 <code>**粗體**</code>，到了 Telegram MarkdownV2，粗體要用的是 <code>*粗體*</code>。</p><p>我這次遇到的錯誤發生在舊模式。改用 V2 後，一般文字裡的底線、方括號、半形句點等符號仍要處理，不能把它當成「比較新，所以什麼文字都吃得下」。完整規則可以查 <a href="https://core.telegram.org/bots/api#formatting-options">Telegram Bot API</a> 的 Formatting options。</p><h2 id="把要排版的部分和一般文字分開"><a href="#把要排版的部分和一般文字分開" class="headerlink" title="把要排版的部分和一般文字分開"></a>把要排版的部分和一般文字分開</h2><p>處理這些符號的方法叫做「跳脫」，也就是在符號前加上反斜線 <code>\</code>，告訴解析器，這裡要顯示符號本身。下面都以 MarkdownV2 解析，第一列保留粗體格式，其餘幾列則把符號當成一般文字。</p><table><thead><tr><th>原始內容</th><th>送給 Telegram 的內容</th><th>手機上預期看到</th></tr></thead><tbody><tr><td><code>**通知**</code>，想顯示粗體</td><td><code>*通知*</code></td><td><strong>通知</strong></td></tr><tr><td><code>build_2.0</code>，只是版本名稱</td><td><code>build\_2\.0</code></td><td>build_2.0</td></tr><tr><td><code>[測試]</code>，只是文字標籤</td><td><code>\[測試\]</code></td><td>[測試]</td></tr><tr><td><code>完成!</code>，保留半形驚嘆號</td><td><code>完成\!</code></td><td>完成!</td></tr></tbody></table><p>表格中間那欄是實際送出的文字，反斜線會在 Telegram 解析時被消耗。寫進程式碼時，還要依照使用語言的字串規則處理反斜線。</p><p>我的每日推播需求很少，主要是保留粗體，其他部分當一般文字。所以轉換時先找出粗體段落，把外層的 <code>**</code> 換成 <code>*</code>，段落內的一般文字照樣跳脫；剩下沒有排版需求的內容，也一起跳脫。這樣既能保留標題的粗體，又不會把版本號裡的底線當成格式。</p><div class="note info no-icon"><p>這個簡化做法只處理「粗體＋一般文字」。如果還要保留連結或程式碼區塊，就得分開處理，因為連結網址和程式碼內部的跳脫規則不同。不要先對整篇內容全部跳脫，再期待原本的格式還在。</p></div><h2 id="格式失敗時，再試一次純文字"><a href="#格式失敗時，再試一次純文字" class="headerlink" title="格式失敗時，再試一次純文字"></a>格式失敗時，再試一次純文字</h2><p>除了每日推播，我也做了一個透過 Telegram 回覆訊息的聊天工具。在這個工具裡，我多加了純文字補送，先轉成 MarkdownV2 發送；如果發送套件回報 <code>BadRequest</code> 例外，表示這次請求無法處理，就再用原始文字試一次，這次關掉格式解析。</p><p>這裡要拿回<strong>轉換前的原始文字</strong>。如果把已經加滿反斜線的內容拿來當純文字送，Telegram 不會再幫忙消耗那些符號，手機上就會看到 <code>build\_2\.0</code>。粗體標記也可能保留下來，雖然排版比較樸素，至少有機會先收到內容。</p><p>被拒絕不全是格式問題，像訊息太長也可能失敗，所以純文字補送只是一次備援嘗試。兩次都失敗時，仍要留下錯誤紀錄，不能把重試當成已經送達。</p><h2 id="先用純文字縮小問題範圍"><a href="#先用純文字縮小問題範圍" class="headerlink" title="先用純文字縮小問題範圍"></a>先用純文字縮小問題範圍</h2><p>下次碰到這類問題，我會先看錯誤說明，再檢查發送時的 <code>parse_mode</code>，也就是控制格式的設定。把同一份原始內容關掉格式解析後送出，如果成功，就回頭查格式轉換；如果仍然失敗，就繼續查長度、發送目標等其他原因。</p><p>修完後，再用包含粗體、版本號和方括號的文字實際送一次，確認訊息有送達，手機上的符號和排版也符合預期。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/long-running-service-watchdog/">一個人也需要 SRE</a></li><li><a href="/ffmpeg-frames-to-data/">把螢幕錄影裡的資料抓出來——ffmpeg 抽影格 + 視覺辨識</a></li><li><a href="/tests-pass-but-does-it-work/">測試通過，真的能用了嗎？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/telegram-message-formatting/</id>
    <link href="https://calmkoala.github.io/telegram-message-formatting/"/>
    <published>2026-10-10T00:00:00.000Z</published>
    <summary>從特殊字元造成的 400 錯誤，整理訊息格式轉換與純文字補送的做法。</summary>
    <title>Telegram 訊息加了格式，怎麼就送不出去了？</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="開發" scheme="https://calmkoala.github.io/categories/study-notes/%E9%96%8B%E7%99%BC/"/>
    <category term="Side Project" scheme="https://calmkoala.github.io/tags/Side-Project/"/>
    <category term="軟體測試" scheme="https://calmkoala.github.io/tags/%E8%BB%9F%E9%AB%94%E6%B8%AC%E8%A9%A6/"/>
    <content>
      <![CDATA[<p>你有沒有遇過，程式明明顯示測試通過，自己打開來用，卻連最常做的操作都沒辦法完成？例如做了一個能匯出報表的小工具，檢查時沒有報錯，按下按鈕也出現成功訊息，下載後才發現檔案是空的。這時再看那一排通過的結果，很難不懷疑，剛才到底測了什麼。</p><p>我在做一套讓 AI 分工的工具時，也遇過類似的落差。角色設定檔產生了，檔案比對也通過，實際打開使用它的工具，卻找不到那些角色。那次通過的是「產生的檔案和預期一致」，並沒有驗到「工具真的讀得懂這些檔案」。兩件事只差一步，對使用結果的影響卻差很多。</p><p>所以看到測試通過，我會接著確認它涵蓋到哪裡。檢查計算結果、檔案內容，和從平常的入口完成一件事，各自能找出不同的問題。做自己的小工具，不必一開始準備完整的測試制度，但至少要挑一條主要流程，確認從開始操作到拿到結果都走得通。</p><span id="more"></span><h2 id="檔案有了，工具卻沒讀到"><a href="#檔案有了，工具卻沒讀到" class="headerlink" title="檔案有了，工具卻沒讀到"></a>檔案有了，工具卻沒讀到</h2><p>那套工具會依照角色定義，產生給開發工具讀取的設定檔，例如負責修改程式的角色、負責審查的角色。設定檔開頭有名稱、用途等欄位，必須照固定格式填寫，開發工具才知道要怎麼使用這個角色。我另外放了一行註解，標明檔案由哪個來源產生，方便日後維護。</p><p>問題出在順序。當時我把註解放在最前面，設定資料排在後面，檔案內容看起來都在，但目標工具要求設定資料必須從第一行開始。它沒有照我預期的方式讀取，幾個角色就這樣被忽略了。直到檢查工具裡的角色清單，並嘗試實際呼叫，才發現檔案有產生，角色卻沒有出現。</p><p>原本的自動檢查會重新產生一份檔案，再和保存的範本比對，確認內容沒有意外改變。比對時，那段註解會先被略過，只比較剩下的設定和內文，因此沒有檢查註解與設定區塊的先後順序。它也沒有啟動目標工具，確認角色能不能被載入。檢查沒有失靈，只是我還少驗了後面那一段。</p><pre><code class="mermaid">graph TD    A[角色定義] --&gt; B[產生設定檔]    B --&gt; C[開發工具讀取]    C --&gt; D[角色出現在清單]    D --&gt; E[實際交付任務]    B -. 比對檔案內容 .-&gt; F[既有檢查通過]</code></pre><p>修正時，我把註解移到設定區塊之後，也把「從工具清單確認已載入，並實際呼叫一次」列為之後的驗收項目。檔案比對仍然保留，因為它適合找出不該改變的內容；只是不能再拿這個結果，代替整條使用流程的確認。這個例子甚至還沒走到複雜的程式邏輯，光是第一行放什麼，就足以讓功能消失。</p><h2 id="先看測試驗到哪裡"><a href="#先看測試驗到哪裡" class="headerlink" title="先看測試驗到哪裡"></a>先看測試驗到哪裡</h2><p>測試會依照設定好的條件判斷結果。例如匯出報表時，檢查總金額是不是算對，和檢查下載的檔案能不能打開，是不同的條件。前者可以直接把資料交給計算程式，快速試很多組數字；後者要經過選資料、按匯出、產生檔案與下載，才能知道這些部分接在一起有沒有問題。</p><p>還有一種常見做法，是在測試裡用預先準備好的回應，暫時代替外部服務。假設工具需要把檔案存到雲端，測試就假裝雲端已回覆「儲存成功」，觀察自己的程式接著會不會顯示正確訊息。這通常叫模擬，或 mock，可以讓測試不必每次連上網路，也方便試出失敗的情況。Playwright 的 <a href="https://playwright.dev/docs/mock">Mock APIs | Playwright</a> 就示範了攔截請求、回傳測試資料，過程中不會真的連到原本的服務。</p><p>這樣的測試有用，但它沒有檢查真實帳號能不能登入、目前有沒有寫入權限，或檔案最後是否真的存在。看到「成功」之前，要先知道這個成功是外部服務回的，還是測試事先安排的。我會保留這些快速檢查，再另外驗證需要實際連接的部分，不會要求每一項測試都去操作一次雲端。</p><h2 id="從平常的入口走一次"><a href="#從平常的入口走一次" class="headerlink" title="從平常的入口走一次"></a>從平常的入口走一次</h2><h3 id="先寫出完成的樣子"><a href="#先寫出完成的樣子" class="headerlink" title="先寫出完成的樣子"></a>先寫出完成的樣子</h3><p>如果我要驗收匯出報表，會先寫下一個具體結果，例如「選定日期後，下載的 CSV 用試算表打開，應該看得到這段期間的紀錄，而且金額和原始資料一致」。CSV 是能用試算表開啟的表格文字檔；這裡要檢查的終點是它裡面的內容，不能只停在按鈕變色或出現成功訊息。</p><p>接著準備少量容易核對的測試資料。例如選定日期內放兩筆紀錄，金額分別是 100 和 200，再放一筆日期外的紀錄。預期匯出只有前兩筆，若工具也提供加總，結果就應該是 300。資料不用多，但要先知道正確答案，才能看出它有沒有漏掉、混入或改錯資料。這裡的報表是示範情境，換成整理照片、預約或待辦工具，也可以用同樣方式訂出完成條件。</p><h3 id="用預計交付的版本操作"><a href="#用預計交付的版本操作" class="headerlink" title="用預計交付的版本操作"></a>用預計交付的版本操作</h3><p>驗收時，要從平常會用的入口開始。網頁工具就打開網頁，選日期、按匯出，再檢查下載的檔案；bot 就從聊天視窗送出操作，確認最後拿到的結果。只在程式裡直接呼叫匯出函式，即使結果正確，也還沒檢查畫面上的按鈕是不是接到了它。</p><p>環境也要對得上。自己電腦裡已經登入的帳號、事先建好的資料夾、開發時留下的設定，可能讓流程剛好能跑。若工具準備放到另一台主機，或交給其他人使用，就要在對應的測試環境重新確認，並使用符合一般使用者權限的測試帳號。不能拿管理員帳號跑過一次，就當作其他人也一定能用。</p><p>這類從操作入口驗到最後結果的檢查，常稱為端到端測試，英文縮寫是 E2E。它也能自動化，不必永遠靠自己點。Playwright 的 <a href="https://playwright.dev/docs/best-practices">Best Practices | Playwright</a> 建議驗證使用者看得到的行為，這也是我選驗收終點的依據。先把流程和預期結果定好，之後才有辦法判斷自動化測試是不是涵蓋了同一件事。</p><h3 id="成功之外，也試一次失敗"><a href="#成功之外，也試一次失敗" class="headerlink" title="成功之外，也試一次失敗"></a>成功之外，也試一次失敗</h3><p>主要流程走通後，我會挑容易出錯、出錯後又需要人處理的情況補測。以報表來說，沒有符合日期的資料時，工具應該說明沒有資料，或產生事先約定好的空報表；儲存失敗時，不該仍然顯示「已儲存」。結果要怎麼呈現可以自己決定，但不能讓使用者以為事情做完了，實際上什麼都沒留下。</p><p>不用一開始窮舉所有異常。若工具只是匯出檔案，可以先測空資料和寫入失敗；若會新增或扣除資料，就多看重複點擊與中途中斷。難以安全重現的情況，可以先用模擬回應測自己的處理邏輯，再把尚未驗證的真實連線列出來。每次只增加一個條件，也比較容易知道問題是從哪裡開始的。</p><div class="note warning no-icon"><p>實跑用的是實際操作方式，不代表要拿正式資料冒險。使用可丟棄的測試資料與獨立帳號；涉及寄信、付款、刪除或對外發布時，要使用測試模式或隔離環境，不要為了驗收真的送出去。</p></div><h2 id="讓-AI-回報做過的檢查"><a href="#讓-AI-回報做過的檢查" class="headerlink" title="讓 AI 回報做過的檢查"></a>讓 AI 回報做過的檢查</h2><p>如果工具主要由 AI 協助開發，我會請它把「已完成」拆成可以核對的內容。它執行了哪個版本、用了什麼測試資料、從哪個入口開始，以及最後看到了什麼結果。拿匯出報表來說，「測試全部通過」太籠統；「用測試帳號從網頁匯出，下載後確認有兩筆紀錄，金額分別是 100 和 200」，才知道這次驗到了哪裡。再附上產出檔、截圖或執行紀錄的位置，才有辦法實際核對。</p><p>報告裡也要留下沒有做的部分。如果 AI 只能讀程式、跑本機測試，卻沒有瀏覽器或測試帳號，就把網頁操作標成未驗證，交給人補做。檔案比對通過、模擬服務回應正確、實際登入後操作成功，可以分開記，不需要湊成一句全部正常。自己不熟程式碼，也能先用這些具體結果，判斷還欠哪一段驗收。</p><p>檢查紀錄不用寫成長篇報告。留下版本、環境、操作、預期與實際結果，以及未驗證項目就夠了；若附截圖或執行紀錄，要先移除金鑰、個人資料與登入資訊。下次出現「我這邊可以，你那邊不行」，至少有資料能比較雙方到底用了什麼條件。</p><h2 id="把漏掉的補回測試"><a href="#把漏掉的補回測試" class="headerlink" title="把漏掉的補回測試"></a>把漏掉的補回測試</h2><p>發現問題後，修好再重跑同一條流程，接著看能不能加上一項自動檢查，讓相同錯誤在日後修改時能被抓到，這也是回歸測試的用途。例如設定區塊是否從第一行開始，就很適合自動檢查；至於目標工具更新後還能不能載入，仍是另一次實跑要驗證的事。</p><p>我不會因此把所有測試都改成從頭操作一次。金額計算、格式判斷這些局部規則，用小範圍測試就能快速確認；資料保存與讀回，要檢查相關部分接在一起的結果；最常用、失敗影響又大的完整流程，再保留端到端驗收。每一層都能做自己的工作，才不用改一行文字，就把整套系統重新點過一次。</p><hr><p>自己的工具，很適合拿平常真的要做的事驗收。挑一個主要功能，準備幾筆知道答案的資料，從正常入口做到拿到結果，再把漏掉的檢查補上。我的角色設定檔已經證明，檔案整整齊齊地躺在那裡，也可能完全沒人理它。下次看到那排通過的結果，我還是會打開工具，確認自己要用的功能真的在。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/google-sheets-as-database/">小工具一定要用資料庫嗎？</a></li><li><a href="/solo-project-jit-governance/">一個人的開源專案，文件要寫多少？</a></li><li><a href="/telegram-message-formatting/">Telegram 訊息加了格式，怎麼就送不出去了？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/tests-pass-but-does-it-work/</id>
    <link href="https://calmkoala.github.io/tests-pass-but-does-it-work/"/>
    <published>2026-10-03T00:00:00.000Z</published>
    <summary>從檔案檢查到實際操作，替自己的小工具補上最後一段驗收。</summary>
    <title>測試通過，真的能用了嗎？</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="開發" scheme="https://calmkoala.github.io/categories/study-notes/%E9%96%8B%E7%99%BC/"/>
    <category term="Side Project" scheme="https://calmkoala.github.io/tags/Side-Project/"/>
    <category term="Google Sheets" scheme="https://calmkoala.github.io/tags/Google-Sheets/"/>
    <category term="資料庫" scheme="https://calmkoala.github.io/tags/%E8%B3%87%E6%96%99%E5%BA%AB/"/>
    <content>
      <![CDATA[<p>做一個小工具時，資料該存在哪裡？存成檔案、放進試算表，或是使用資料庫，看起來都有辦法。但看到各種資料庫和雲端服務的介紹，又容易猶豫，是不是一開始就該準備得完整一點。我覺得可以先看看資料會怎麼使用，有些需求用檔案或試算表就夠了；即使需要資料庫，也不一定要另外架設一套服務。</p><p>我之前設計過一個 Telegram 記帳 bot 的原型，當時選的是 Google Sheets。預計讓使用者從聊天視窗記錄支出，由 bot 把帳目存進試算表，需要整理時再直接打開來看。這個想法很直覺，既然平常就會用表格記帳，讓程式幫忙填進去，似乎也不用為了看幾筆資料，另外做一個管理介面。</p><p>選儲存方式時，我會先看資料要怎麼使用。同樣是一張帳目表，單純記下每天花多少錢，和要處理多人分帳、個別還款，需要照顧的事情就差很多。能直接打開表格整理，是選 Google Sheets 的理由，但也要一起考慮程式會怎麼讀取、修改這些資料。</p><span id="more"></span><h2 id="先看資料怎麼用"><a href="#先看資料怎麼用" class="headerlink" title="先看資料怎麼用"></a>先看資料怎麼用</h2><p>資料需要留下來，不代表一定要用資料庫。程式可以把設定寫進檔案，把報名資料放進試算表，也可以把帳目存進資料庫。幾種方式都能保存資料，選擇時要多看一步，想想以後會怎麼讀取、修改，以及修改到一半出錯時，能不能接受留下不完整的結果。</p><p>例如，一個自己使用的工具，只要記住上次選的資料夾，下次開啟時再讀出來，檔案就很適合。活動名單需要主辦人隨時打開補註記，試算表的現成介面很方便。換成預約系統，兩個人可能同時搶最後一個名額，程式就得處理誰先成功，不能讓兩邊都收到預約完成的通知。資料量還很少，操作方式卻已經影響選擇了。</p><p>我會先把這些使用情境寫下來，再比較工具。這時不用急著研究資料庫語法，先想想誰會改資料、會不會同時修改，以及弄錯一筆會怎樣。這比一開始就找「最好的資料庫」更有用，也比較不會選了一套功能齊全、自己卻用不上的架構。</p><h2 id="不用資料庫的選擇"><a href="#不用資料庫的選擇" class="headerlink" title="不用資料庫的選擇"></a>不用資料庫的選擇</h2><h3 id="設定與簡單紀錄，用檔案"><a href="#設定與簡單紀錄，用檔案" class="headerlink" title="設定與簡單紀錄，用檔案"></a>設定與簡單紀錄，用檔案</h3><p>設定、單機工具的少量狀態，或每次執行後產生的一份報表，都可以先考慮檔案。常見的 JSON 適合表達有層次的資料，例如設定裡同時包含資料夾位置與通知偏好；CSV 則把內容存成一列一列，方便用試算表開啟。它們是檔案格式，讀取哪一筆、怎麼更新，以及哪些值才算合法，都要由程式處理。</p><p>這種做法容易開始，但「存進檔案」仍有一些工作。我會先確認檔案放在哪裡，程式重啟或更新後重新上線，也就是重新部署時，資料會不會消失，再考慮怎麼備份。如果兩個操作同時讀取舊內容，改完各自存回，後存的那份可能蓋掉前一份修改；寫到一半中斷，也得有辦法避免原本的資料跟著壞掉。只由同一個程式依序處理簡單設定時，這些事情比較容易掌握；當自己開始補上大量防止覆寫、查找與更新的邏輯，就值得比較資料庫了。</p><h3 id="需要人工整理，用試算表"><a href="#需要人工整理，用試算表" class="headerlink" title="需要人工整理，用試算表"></a>需要人工整理，用試算表</h3><p>Google Sheets 適合的情況，是你本來就需要一個能直接查看、修改資料的介面。例如活動名單由程式新增，主辦人再手動補註記；或像我的記帳 bot 原型，預計從 Telegram 記帳，需要整理時再打開試算表。Google 提供 API，也就是讓程式透過網路讀寫資料的入口，bot 可以藉此新增一列或讀取帳目，相關做法可參考 <a href="https://developers.google.com/workspace/sheets/api/guides/values">Read and write cell values</a>。</p><p>這裡省下的是自己做資料管理介面的工作，bot 本身仍要有地方執行，也得處理連線與權限。原型還沒有完成 Google Sheets 與 Telegram 的完整串接驗證，所以這是當時的設計考量，不能當成已經長期使用、證明可靠的成果。</p><p>人能直接改表格，也代表程式依賴的格式可能被改掉。例如把「金額」欄改名，或刪除程式需要的編號，bot 就可能找不到資料。分享權限也要分開看，讓 bot 有權限開啟試算表，不代表任何傳訊息給 bot 的人都有權限查帳。因此，我會把供程式使用的原始紀錄和人工整理的報表分開，並限制誰能透過 bot 讀寫。若資料幾乎只由程式維護，這些現成介面的好處就少了，未必需要特地繞一圈用試算表。</p><h2 id="資料庫能幫上什麼忙"><a href="#資料庫能幫上什麼忙" class="headerlink" title="資料庫能幫上什麼忙"></a>資料庫能幫上什麼忙</h2><p>如果工具要處理還款與撤銷操作，我會特別留意修改失敗後，帳目能不能對得起來。查找未還款紀錄、擋下重複記帳，以及把必須一起完成的修改放在一起處理，都可以用到資料庫的能力。即使只有少數人使用，這些需求也可能從第一天就存在，不必等到資料變多才考慮。</p><p>假設記帳工具同時保存還款紀錄和欠款餘額。小美還了 300 元，程式要新增還款紀錄，也要把餘額減掉 300；如果只完成前半段就中斷，兩邊會對不起來。資料庫的「交易」可以把這些修改包成一組，成功時一起保留，失敗時撤回這一組修改。PostgreSQL 的 <a href="https://www.postgresql.org/docs/current/tutorial-transactions.html">3.4. Transactions</a> 用轉帳說明這個概念。程式仍要正確劃定這一組操作並處理失敗，裝好資料庫不會自動替你決定哪些事情要一起完成。</p><p>分帳規則也會影響要存的資料。假設小明先付了 900 元晚餐，三個人平均分攤，小美還了 300 元，小華還沒還。如果資料只留一個「是否結清」欄位，無論放在試算表還是資料庫，都沒辦法完整表達這個狀態。必須先把每個人應付、已付多少分開記錄，程式才有資料可以算。換工具能省掉部分儲存與查詢工作，分帳規則還是得自己想好。</p><p>重複記帳也是類似的情況。使用者沒收到回覆，再送一次訊息，資料庫不會憑空知道兩次是不是同一筆。程式需要識別這次操作，再配合資料庫的唯一性規則，拒絕重複寫入；如果只是新增兩筆編號不同的紀錄，資料庫仍可能照單全收。PostgreSQL 的 <a href="https://www.postgresql.org/docs/current/ddl-constraints.html">5.5. Constraints</a> 整理了這類可由資料庫檢查的條件。這些能力有用，但要和工具本身的規則配合。</p><h2 id="資料庫不一定很重"><a href="#資料庫不一定很重" class="headerlink" title="資料庫不一定很重"></a>資料庫不一定很重</h2><h3 id="SQLite，不必另外架服務"><a href="#SQLite，不必另外架服務" class="headerlink" title="SQLite，不必另外架服務"></a>SQLite，不必另外架服務</h3><p>如果資料主要由程式讀寫，又不想另外管理一套資料庫服務，SQLite 很值得放進候選。它本身就是資料庫，只是由程式直接使用本機的資料庫檔案，不需要另開一個資料庫伺服器。官方的 <a href="https://www.sqlite.org/serverless.html">SQLite Is Serverless</a> 說明了這個差異，所以「不用架資料庫服務」和「不用資料庫」是兩件事。</p><p>SQLite 也有查詢與交易能力，可以拿來保存互有關聯的支出、成員與還款紀錄，不必自己在 JSON 或 CSV 裡重做整套查找和更新。它可以同時讓多個連線讀取，但每個資料庫檔案同一時間只容許一個寫入交易，細節見 <a href="https://www.sqlite.org/lang_transaction.html">Transaction</a>。也就是有兩組修改同時要存入時，程式得安排等待或重試，讓它們依序完成。短時間的修改若能這樣處理，仍然可以支援多人透過同一個 bot 使用；「多人使用」不等於「每個人都直接開啟資料庫檔案」。</p><p>需要注意的是，資料庫檔案仍要放在能長期保存的位置，備份也要使用適合資料庫的方式。SQLite 不會讓沒有持久儲存空間的部署環境，自動變成適合保管帳目的地方。選它之前，我會一起確認程式跑在哪裡、資料放在哪裡，以及換一台主機時怎麼還原。</p><h3 id="獨立服務，讓多個程式共用"><a href="#獨立服務，讓多個程式共用" class="headerlink" title="獨立服務，讓多個程式共用"></a>獨立服務，讓多個程式共用</h3><p>當多台主機上的程式需要共同修改資料，或同時寫入的工作多到不適合依序等待，就值得評估 PostgreSQL 這類獨立的資料庫服務。程式透過網路連線，把讀寫請求交給資料庫處理，而不必讓每台主機直接操作同一個檔案。SQLite 官方的 <a href="https://www.sqlite.org/whentouse.html">Appropriate Uses For SQLite</a> 也把寫入需求和資料的位置列為選擇依據，沒有用「幾個使用者」畫出固定分界。</p><p>獨立服務可以自己架，也可以使用供應商代管的方案，例如雲端平台提供、開通後就能連線的資料庫。自己架要負責安裝、更新與備份，代管則能省下一部分工作，但還是要確認費用、連線方式、備份範圍，以及資料能不能匯出。不想自己架服務，不代表一定要退回檔案；如果程式原本就部署在雲端，而且平台已有合適的方案，一開始使用它也合理，沒有必要把所有選項照順序用過一次。</p><h2 id="替自己的工具做選擇"><a href="#替自己的工具做選擇" class="headerlink" title="替自己的工具做選擇"></a>替自己的工具做選擇</h2><p>我把前面的使用情境和需要自己照顧的部分整理成下面這張表，可以拿自己的需求做第一輪比較。</p><table><thead><tr><th>使用情境</th><th>可以先考慮</th><th>要留意的事</th></tr></thead><tbody><tr><td>簡單設定、依序處理的少量狀態、匯出報表</td><td>JSON、CSV 等檔案</td><td>更新方式、寫入中斷、存放位置與備份</td></tr><tr><td>人需要經常開啟、整理，程式協助新增資料</td><td>Google Sheets</td><td>欄位變動、存取權限、網路與 API 使用限制</td></tr><tr><td>資料主要由程式讀寫，集中在同一台主機</td><td>SQLite</td><td>寫入是否能排隊、資料檔保存與還原</td></tr><tr><td>多台主機共用資料，或寫入需求較高</td><td>獨立或代管資料庫服務</td><td>連線權限、維運或方案費用、備份與匯出</td></tr></tbody></table><p>以記帳 bot 為例，如果需求是記下支出，並且需要經常手動整理表格，Google Sheets 有它方便的地方。但若需要多人分帳、個別還款和撤銷操作，平常又幾乎不會打開表格，我會先評估 SQLite，前提是 bot 集中在同一台能長期保存資料的主機，寫入也能依序處理。這些都是設計時就能比較的條件，不需要等到試算表塞不下，才開始考慮資料庫。</p><p>如果你是用 AI 做小工具，可以先告訴它程式預計跑在哪裡，再拿自己的兩三個實際操作，請它比較用檔案、試算表或資料庫時，資料會存在哪裡、一次修改會動到什麼。接著追問，兩個操作同時送出、寫到一半中斷、重新部署時，原本的資料會怎樣，並請它指出不建議採用的選項和原因。回答若只剩「這個比較簡單」「以後比較好擴充」，還不足以決定；把情境放進測試環境實際跑一次，才知道程式有沒有做到它說的事。</p><hr><p>我當時選 Google Sheets，是因為打開就能看帳，不想再做一個介面。換成只存設定或整理名單的工具，也可以先不用資料庫；要處理還款，SQLite 則可能比自己補齊檔案讀寫規則省事。做小工具時，我會先想清楚要存什麼、怎麼修改，再選資料放哪裡，免得連午餐都還沒記到，先多了一套要照顧的系統。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/tests-pass-but-does-it-work/">測試通過，真的能用了嗎？</a></li><li><a href="/solo-project-jit-governance/">一個人的開源專案，文件要寫多少？</a></li><li><a href="/telegram-message-formatting/">Telegram 訊息加了格式，怎麼就送不出去了？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/google-sheets-as-database/</id>
    <link href="https://calmkoala.github.io/google-sheets-as-database/"/>
    <published>2026-09-26T00:00:00.000Z</published>
    <summary>從檔案、試算表到資料庫，替自己的小工具選個合適的存法。</summary>
    <title>小工具一定要用資料庫嗎？</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="開發" scheme="https://calmkoala.github.io/categories/study-notes/%E9%96%8B%E7%99%BC/"/>
    <category term="工作流程" scheme="https://calmkoala.github.io/tags/%E5%B7%A5%E4%BD%9C%E6%B5%81%E7%A8%8B/"/>
    <category term="開源" scheme="https://calmkoala.github.io/tags/%E9%96%8B%E6%BA%90/"/>
    <category term="Side Project" scheme="https://calmkoala.github.io/tags/Side-Project/"/>
    <content>
      <![CDATA[<p>你有沒有做完一個小工具，準備公開時，就順手請 AI 幫忙把文件也補齊？現在用 AI 整理使用說明很方便，原本懶得從空白頁寫起的安裝步驟、操作範例，都能先有個草稿。既然都請它寫了，再補一份貢獻指南、行為準則，好像也不費什麼力氣，專案看起來還更完整。</p><p>我之前準備公開一套 AI 協作框架時，也整理出了一整套文件。它用 Markdown 和 YAML 這類文字檔，描述不同 AI 角色該做什麼，以及工作要怎麼交接，讓我不用每次重新交代同一套分工。原本想分享的是這個做法，整理到後來，專案裡卻已經有貢獻流程、社群規範和一大份內部架構說明。</p><p>只是文件生出來之後，裡面的流程還是得有人照著做、隨著專案更新。當時我仍打算以一人維護的方式經營專案，並沒有要照那套完整制度運作，後來便把其中幾份文件從對外版本移除，保留自己查閱需要的內容。我開始想的是，第一次看到這個專案的人，到底缺哪一份說明；如果他連怎麼開始用都不知道，我先寫完分支命名規則，好像也幫不上忙。</p><span id="more"></span><h2 id="我刪掉的是哪一種文件"><a href="#我刪掉的是哪一種文件" class="headerlink" title="我刪掉的是哪一種文件"></a>我刪掉的是哪一種文件</h2><p>GitHub 上的專案通常會有一份 README，直接顯示在專案首頁，讓人知道這是什麼、如何使用。想協助修改的人，則可能需要 CONTRIBUTING，也就是貢獻指南，裡面交代怎麼準備開發環境、檢查修改結果，以及把變更交給維護者。兩份文件的讀者可能是同一個人，卻是在不同時候找答案。</p><p>我那次移除的是 CONTRIBUTING、Code of Conduct（行為準則），以及 ARCHITECTURE（內部架構說明）。授權條款和安全回報說明仍然保留，使用者需要的安裝方式也沒有一起拿掉。這是在調整當下對外維護的文件範圍，並不是刪光說明、只留下程式碼。</p><p>其中最需要分開看的是架構文件。未來協作者可能需要知道檔案怎麼組合，第一次使用的人卻未必需要讀完每個設計決策。後來我又把安裝、基本概念、自訂方式等使用說明拆進文件目錄，從首頁連過去。內部筆記可以先留給自己，但別人操作時缺的說明，還是得補回公開文件裡。</p><p>對我來說，成本主要在寫完之後。測試指令換了，貢獻指南得跟著改；工作方式調整了，審查流程也得更新。AI 可以協助更新內容，但裡面的指令是否真的能跑、承諾的流程是否做得到，仍得自己確認。文件寫得越完整，需要核對的地方也越多。</p><h2 id="公開前先交代什麼"><a href="#公開前先交代什麼" class="headerlink" title="公開前先交代什麼"></a>公開前先交代什麼</h2><h3 id="讓第一個使用者能開始"><a href="#讓第一個使用者能開始" class="headerlink" title="讓第一個使用者能開始"></a>讓第一個使用者能開始</h3><p>我現在會先從使用者的第一個動作往回看。對這套 AI 協作框架來說，他需要知道哪些工具能用、怎麼安裝，再用一個小任務確認角色有正常運作。至於我當初比較過哪些設計、為什麼淘汰某種分工方式，可以放在後面，不必擋在開始使用之前。</p><p>換成一般的小工具也一樣。README 至少要說明它解決什麼問題、需要先準備什麼，以及照著做完會看到什麼結果。如果還有尚未支援的平台、可能改動的功能，或只在自己的環境測過，也要讓人事先知道。只寫「安裝後即可使用」，卻沒交代安裝成功長什麼樣子，讀者卡住時還是只能猜。</p><p>這些資訊不一定要各自拆成一份檔案。我會先按用途分配，再決定要放在哪裡。</p><table><thead><tr><th>讀者現在需要知道的事</th><th>起步時可以怎麼放</th><th>什麼時候再擴充</th></tr></thead><tbody><tr><td>這是什麼、如何開始、有哪些限制</td><td>README，加一個能照做的例子</td><td>首頁太長時，把安裝與進階用法拆出去並留下連結</td></tr><tr><td>可以如何使用、修改與散布</td><td>放好適用的授權條款</td><td>授權需求改變時重新評估，不等有人提問才處理</td></tr><tr><td>一般問題、安全問題要去哪裡回報</td><td>README 留一般入口，安全回報另給非公開管道</td><td>回報需要的資訊反覆缺漏時，再補範本</td></tr><tr><td>想協助修改，該先做什麼</td><td>先說是否接受修改，並留下討論想法的入口</td><td>開始邀請貢獻時，補開發與檢查步驟</td></tr><tr><td>多人一起討論或維護，要遵守什麼</td><td>準備招募貢獻或經營討論時，先交代行為邊界與處理方式</td><td>有固定協作者時，再補審查分工與發布權責</td></tr></tbody></table><p>這張表是我整理一人專案時的取捨，沒有規定 CONTRIBUTING 一定得晚寫。如果現在就需要請別人協助，先用幾行交代怎麼參與，會比讓對方來回問更省事。</p><h3 id="安全回報不能等"><a href="#安全回報不能等" class="headerlink" title="安全回報不能等"></a>安全回報不能等</h3><p>一般操作問題，可以請使用者建立 GitHub issue；它是專案用來追蹤問題與建議的討論頁。安全漏洞則要有私下回報的方法，不能等第一個人把敏感內容貼到公開留言區，才開始決定該寄到哪裡。我當時保留的 SECURITY 文件，就把一般問題和安全回報分開處理。</p><p>GitHub 提供私人漏洞回報功能，但在文件裡寫「請使用私人回報」不等於功能已經開啟。依 <a href="https://docs.github.com/en/code-security/security-advisories/working-with-repository-security-advisories/configuring-private-vulnerability-reporting-for-a-repository">Configuring private vulnerability reporting for a repository</a> 的說明，維護者需要啟用功能，對方才會看到回報按鈕；通知設定也會影響維護者能否收到提醒。如果選擇用這個管道，公開前就要確認入口真的可用，而不只是把網址貼上去。</p><div class="note warning no-icon"><p>可以延後的是尚未用到的協作流程。授權條款、API 金鑰與個人資料的檢查、非公開的安全回報入口，都不適合等有人出事才補。把已提交過的文件從目前版本刪掉，也不會自動清除 Git 保留的過去版本紀錄；整理文件和處理資料外洩，是兩件不同的工作。</p></div><h2 id="有人想幫忙時怎麼補"><a href="#有人想幫忙時怎麼補" class="headerlink" title="有人想幫忙時怎麼補"></a>有人想幫忙時怎麼補</h2><p>假設有人試用後，在 issue 問：「我照著安裝說明做，但不知道設定檔要放哪裡。」這時先回覆位置，再把答案補到 README 對應的步驟旁邊就好。對方卡在使用說明，新增一份貢獻指南並不能幫他完成安裝。</p><p>接著，假設他說願意幫忙補一個安裝範例，事情才進到協作。我會先說明範例應放在哪裡、要涵蓋哪種環境，以及送出前怎麼確認步驟可用。不能等他全部做完，才告訴他我其實還要求另一組檢查；如果檢查方式只有我知道，我就得先補出來，或明講哪些部分會由我協助驗證。</p><p>對方把修改送成一筆變更提案，請我審查是否合併；GitHub 把這種提案稱為 pull request，簡稱 PR。第一輪合作結束後，可以把剛才那段說明整理進 CONTRIBUTING。內容不用突然長成一套制度，先讓下一位貢獻者知道「動手前先討論範圍、修改放哪裡、完成後如何檢查」就有用。之後發現每次都漏掉相同資訊，再把那一項加進 PR 範本。</p><p>若改的是功能，檢查方式可能是執行測試；若改的是安裝說明，就應實際照步驟走過。主要靠 AI 做修改的人，可以先請它列出能重做的檢查步驟，自己跑一次並保留結果，再決定文件要記哪些操作。AI 產出的「所有測試均已通過」，仍要有實際執行結果可以核對，不能直接拿這句話當驗收。</p><p>拆出 CONTRIBUTING 也有檔名以外的好處。GitHub 的 <a href="https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors">Setting guidelines for repository contributors</a> 說明，放在支援位置的貢獻指南，會在建立 issue 或 PR 時提供連結。協作開始固定發生後，把規則放到對方準備送出修改的位置，比一直藏在 README 中段更好找。</p><p>我把這種安排理解成「需要時再補規則」。時間點可以是第一次回饋，也可以是自己決定開始找人幫忙；不必硬等到第一個 PR 已經送來，更不用等同一個人踩兩次坑，才承認文件缺了一段。</p><h2 id="什麼時候該提早寫"><a href="#什麼時候該提早寫" class="headerlink" title="什麼時候該提早寫"></a>什麼時候該提早寫</h2><p>查資料時，我也看到跟我當時選擇不同的建議。<a href="https://opensource.guide/starting-a-project/">Starting an Open Source Project</a> 把授權、README、貢獻指南與行為準則都列為起步文件，也提到早期的貢獻指南可以很簡單。這個建議有道理，清楚的參與方式本來就能降低別人第一次幫忙的門檻，不能只看「現在沒人提修改」，就推論永遠不需要寫。</p><p>如果公開的目的就是招募協作者，或已經準備經營討論區，我會在邀請之前補好參與方式與行為準則，包括不當行為要向誰回報、維護者如何處理。人少也可能發生衝突，不能把「等有需要」解讀成等第一次爭執後再想規則。同樣地，多個人開始審查與發布時，誰可以合併、誰可以發版，也應該事先談好。</p><p>我的起點比較小，先把自己做的工具分享出去，由自己維護，沒有打算一開始就建立共同決策的社群。在這個前提下，我願意承擔第一次有人想幫忙時，多花一點時間說明和補文件的成本。所以我會先在 README 留下求助入口與是否接受貢獻，其他制度等實際互動再補。</p><hr><p>下次整理自己的專案，我會先挑一個已經能用的功能，從 README 開始照著做一次，看看哪一步還得靠腦中的記憶補完。那就是現在該寫的地方。至於暫時用不到的審查層級和完整提案範本，先留下需要時再補的空間，至少不用一邊改功能，一邊通知只有自己一個人的委員會。（當然，最好的習慣還是在製作過程中，就順手把需要的文件補好，省得最後再靠記憶補作業。）</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/tests-pass-but-does-it-work/">測試通過，真的能用了嗎？</a></li><li><a href="/google-sheets-as-database/">小工具一定要用資料庫嗎？</a></li><li><a href="/background-ai-agent-tasks/">哪些工作該交給背景 AI agent？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/solo-project-jit-governance/</id>
    <link href="https://calmkoala.github.io/solo-project-jit-governance/"/>
    <published>2026-09-19T00:00:00.000Z</published>
    <summary>先讓別人用得起來，再補實際需要的協作流程。</summary>
    <title>一個人的開源專案，文件要寫多少？</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="開發筆記" scheme="https://calmkoala.github.io/categories/%E9%96%8B%E7%99%BC%E7%AD%86%E8%A8%98/"/>
    <category term="工具" scheme="https://calmkoala.github.io/categories/%E9%96%8B%E7%99%BC%E7%AD%86%E8%A8%98/%E5%B7%A5%E5%85%B7/"/>
    <category term="CI/CD" scheme="https://calmkoala.github.io/tags/CI-CD/"/>
    <category term="開發筆記" scheme="https://calmkoala.github.io/tags/%E9%96%8B%E7%99%BC%E7%AD%86%E8%A8%98/"/>
    <category term="Git" scheme="https://calmkoala.github.io/tags/Git/"/>
    <content>
      <![CDATA[<p>最近替自己的樂譜練習 App LilyScore 準備發版，功能做完、測試也跑過，最後卻卡在一個很普通的問題：這版到底更新了什麼？</p><p>過程中加過播放器功能、修過樂譜庫，還順手調了幾個小地方。每個當下我都知道自己在做什麼，隔了幾天再回頭看，腦袋卻只剩下「好像改了播放器」、「還有一個 bug」。接著又開始翻 commit、issue 和對話紀錄，把剛做完的事情重新整理一次。</p><p>LilyScore 第一次走完整個上架流程時，我才發現每一版都會遇到同一件事。商店要一份讓練習的人看得懂的更新說明，GitHub Release 又要保留完整紀錄；兩份都靠發版前臨時回想，很像考前一天才開始整理筆記。<del>而且還是自己出的題目。</del></p><p>後來我沒有再多維護一份版本說明文件，而是把平常留下的修改紀錄，直接拿來當發版時的原料。</p><span id="more"></span><h2 id="先留下可讀的修改紀錄"><a href="#先留下可讀的修改紀錄" class="headerlink" title="先留下可讀的修改紀錄"></a>先留下可讀的修改紀錄</h2><p>Git 是程式專案常用的版本管理工具；commit 則是每次保存一小段修改時，替那次變更留下的紀錄。tag（版本標記）是替某個版本做的記號，從上一個發版 tag 往後看，就能找出這一版新增了哪些修改。</p><p>如果目前還沒有發版腳本，先手動做一次就夠了：</p><ol><li>找到上一個發版的 tag。</li><li>列出那個 tag 到現在的 commit。</li><li>挑出使用者會在意的功能與修正，改寫成幾行版本說明。</li></ol><p>例如上一版是 <code>v2.2.0</code>，可以先用下面這行列出後續的 commit 標題：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">git <span class="built_in">log</span> v2.2.0..HEAD --pretty=%s</span><br></pre></td></tr></table></figure><p>這裡還不用急著自動化。先讓每次修改都留下一句能看懂的紀錄，發版時就不必從聊天紀錄裡考古。如果你還沒用 Git，同樣可以把紀錄放在待辦清單或更新筆記裡，只要它能回答「上次發布後，我做了什麼」就行。</p><h2 id="兩份版本說明"><a href="#兩份版本說明" class="headerlink" title="兩份版本說明"></a>兩份版本說明</h2><p>同一批 commit，我會整理成兩份內容。短版給實際使用 App 的人看，只留下多了什麼、修了什麼；完整版留給以後的我，連文件、測試與發版過程都保留。以 LilyScore 為例，短版放到 Google Play，完整版放到 GitHub Release，也就是 GitHub 上每個版本的發布頁。</p><p>為了讓腳本分得出哪些修改值得對外說，我在新增功能的標題前加上 <code>feat:</code>，修正問題則用 <code>fix:</code>。這只是平常寫紀錄時採用的分類，先有一致的寫法，發版時才有規則可以篩選。</p><table><thead><tr><th>去哪裡</th><th>取哪些內容</th><th>用來做什麼</th></tr></thead><tbody><tr><td>Google Play</td><td>新增功能與問題修正，篩選後再確認文字</td><td>讓使用者知道這版增加與修正了什麼</td></tr><tr><td>GitHub Release</td><td>版本範圍內的所有 commit 標題與短編號</td><td>讓自己日後追查每一筆修改</td></tr></tbody></table><p>不過，拿掉前綴還不一定能直接放上商店。LilyScore 真的有過下面兩筆 commit，自動整理只會做到中間那欄；右邊是我把同一件事改寫給使用者看的示例，並非腳本會自動產出的文字。</p><table><thead><tr><th>原始 commit</th><th>自動整理的候選文字</th><th>人工改寫示例</th></tr></thead><tbody><tr><td><code>feat(player): A-B 循環在進度條上可視化</code></td><td>A-B 循環在進度條上可視化</td><td>在播放進度條上顯示 A-B 循環範圍，方便查看反覆播放的起點與終點。</td></tr><tr><td><code>fix(home): 空狀態不再放浮動按鈕，「匯入樂譜」不重複出現</code></td><td>空狀態不再放浮動按鈕，「匯入樂譜」不重複出現</td><td>修正尚未匯入樂譜時，畫面重複出現「匯入樂譜」按鈕的問題。</td></tr></tbody></table><p>「空狀態」對寫程式的人很直覺，使用者卻要先猜它指的是哪個畫面。腳本能幫我找出這筆修正，換成對方看得懂的說法，仍然要由我決定。GitHub Release 則保留原本的標題、前綴與短編號，連文件、雜項維護和發版本身的 commit 都列出；要看實際改了哪些程式，再點進 commit。</p><p>這張圖把人工確認也列進流程，這一步目前仍要在發版指令前手動完成。</p><pre><code class="mermaid">flowchart TD    A[留下可讀的修改紀錄] --&gt; B[選定本次更新範圍]    B --&gt; C[挑出新功能與問題修正]    C --&gt; D[人工確認與改寫]    D --&gt; E[Google Play 短版]    B --&gt; F[保留所有修改標題]    F --&gt; G[GitHub Release 完整版]</code></pre><h2 id="Commit-標題要寫給人看"><a href="#Commit-標題要寫給人看" class="headerlink" title="Commit 標題要寫給人看"></a>Commit 標題要寫給人看</h2><p>當 commit 標題有可能出現在商店裡，我就不能再寫「fix bug」、「調整一下」或「final final 真的 final」。以前這種標題只會讓幾週後的我看不懂，現在還可能直接變成使用者看到的版本說明，丟臉範圍變大了。</p><p>這也是我最喜歡的副作用。版本說明的品質，早在每次保存小改動時就決定了一部分。如果你讓 AI 幫忙寫 commit，也要看一眼「這個改動要怎麼講給人聽」。否則只會得到一串文法很完整，卻不知道做了什麼的句子。</p><p>當然，不是所有 commit 都適合對外說。重構、調整測試、修 CI，可能對維護很重要，卻不一定是練習的人需要知道的更新。所以我只把 <code>feat:</code> 和 <code>fix:</code> 當成商店候選內容；你也可以使用自己的分類，先決定哪些變更值得出現在使用者面前即可。</p><h2 id="LilyScore-的發版流程"><a href="#LilyScore-的發版流程" class="headerlink" title="LilyScore 的發版流程"></a>LilyScore 的發版流程</h2><p>我後來把固定步驟放進 <code>scripts/release.ps1</code>。它會檢查目前是不是在主分支 <code>main</code>、有沒有已追蹤但尚未提交的修改、本機是否落後遠端、tag 是否重複，再檢查程式是否有靜態分析能找出的錯誤。通過後，腳本更新版號與建置編號、整理 Play 說明，接著建立 release commit、tag 並推上 GitHub。後續測試、簽章建置與上傳，交給 GitHub Actions 自動執行，這就是下面提到的 CI。</p><h3 id="發版前先確認文字"><a href="#發版前先確認文字" class="headerlink" title="發版前先確認文字"></a>發版前先確認文字</h3><p>這裡還有個目前腳本沒補上的步驟。它會在終端印出版本說明，接著直接 commit、打 tag 並 push，沒有停下來等我確認。因此，要先檢查文字，就得在執行發版指令之前，用前面的 <code>git log</code> 列出修改、整理好內容，再用 <code>-Notes</code> 傳入已確認的版本說明。例如只要說明這次循環範圍的更新，可以在 LilyScore 專案裡執行：</p><figure class="highlight powershell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">.\scripts\release.ps1 <span class="literal">-Version</span> <span class="number">2.3</span>.<span class="number">0</span> <span class="literal">-Notes</span> <span class="string">&#x27;在播放進度條上顯示 A-B 循環範圍。&#x27;</span></span><br></pre></td></tr></table></figure><p>這樣會覆寫自動彙整的文字，並繼續完成發版；它是一條會提交和推送的指令。腳本也有 <code>-NoPush</code> 參數，但那仍會建立 commit 與 tag，只省略推送，不能當成單純預覽。想把「產生候選文字、人工確認、正式送出」接成不中斷的流程，還需要替腳本補上預覽與確認步驟。</p><h3 id="測試版的更新範圍"><a href="#測試版的更新範圍" class="headerlink" title="測試版的更新範圍"></a>測試版的更新範圍</h3><p>兩份紀錄還有個小差別，從哪個版本開始算。假設上次送到 Play 的版本是 <code>v2.2.0</code>，中間做過 <code>v2.3.0-alpha.1</code> 與 <code>v2.3.0-beta.1</code>，現在準備送出 <code>v2.3.0</code>，商店說明應該包含整段測試期間累積的功能。GitHub Release 則每個測試版都有紀錄，可以分開追查這幾次修改。</p><p>LilyScore 因此把名稱含 <code>-</code> 的 tag 視為測試版，只建立 GitHub Release；不含 <code>-</code> 才送進 Play 封閉測試軌道，讓加入測試的人收到更新，這不代表已經發布到正式軌道。Play 說明從上一個不含 <code>-</code> 的 tag 開始，GitHub Release 則取排除本次 tag 後、依版本號排序的第一個 <code>v*</code> tag 作為起點。這是我目前專案的分流規則，其他專案可以按自己的發布方式調整。</p><h2 id="自動彙整的四個邊界"><a href="#自動彙整的四個邊界" class="headerlink" title="自動彙整的四個邊界"></a>自動彙整的四個邊界</h2><h3 id="沒有-feat-或-fix"><a href="#沒有-feat-或-fix" class="headerlink" title="沒有 feat: 或 fix:"></a>沒有 <code>feat:</code> 或 <code>fix:</code></h3><p>這版若找不到 <code>feat:</code> 或 <code>fix:</code>，腳本目前會放入「穩定性與效能改善。」這句備用文字，避免產生空白說明。但這句話未必有 commit 可以證明；更保守的做法是中止發版，要求人工補上內容。目前腳本還沒這樣做，需要在執行前確認這版改了什麼，再用前面的 <code>-Notes</code> 傳入合適的文字。</p><h3 id="內容超過商店上限"><a href="#內容超過商店上限" class="headerlink" title="內容超過商店上限"></a>內容超過商店上限</h3><p>Google Play 的 <a href="https://support.google.com/googleplay/android-developer/answer/9859348?hl=en">Prepare and roll out a release</a> 說明目前允許每種語言最多 500 個 Unicode 字元。我的腳本依新到舊逐條放入，快滿時就停止。它用 PowerShell 的字串長度做較保守的檢查，純中文通常不受影響，emoji 可能提早碰到限制；大改版仍會改用手寫說明。</p><h3 id="tag-畫錯版本範圍"><a href="#tag-畫錯版本範圍" class="headerlink" title="tag 畫錯版本範圍"></a>tag 畫錯版本範圍</h3><p>目前的腳本依版本號排序找上一個 tag，前提是 release tag 都在同一條主線，版號也一直往上增加。如果專案同時維護多條版本分支或做 backport，就該限制為目前 <code>HEAD</code> 的祖先 tag，否則 <code>git log A..HEAD</code> 可能抓錯版本。重寫 Git 歷史、壓縮 commit 或把 tag 打錯位置，也會改變輸出。</p><h3 id="CI-讀不到舊紀錄"><a href="#CI-讀不到舊紀錄" class="headerlink" title="CI 讀不到舊紀錄"></a>CI 讀不到舊紀錄</h3><p><code>actions/checkout</code> 預設只抓觸發 workflow 的一個 commit，runner 可能根本沒有舊 tag。本來要列整段變更的 <code>git log</code>，最後就只剩本次 commit；LilyScore 因此把 <code>fetch-depth</code> 設為 <code>0</code>，讓 CI 取得完整歷史。這類問題平常不容易出現，通常會挑發版那天才突然讓人想把電腦闔起來。</p><hr><p>版本說明最後還是得由我看過，因為讀者不是 CI，也不會因為內容由腳本產生就突然看得懂。有了平常留下的紀錄，發版時可以從這份清單挑選、改寫，不必再從空白頁開始回想。</p><p>把已經寫在 commit 裡的資訊再整理一次，聽起來很勤勞，實際上只是我以前還沒想到要偷懶而已。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/google-play-first-release/">第一次上 Google Play，最麻煩的不是寫 App</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/release-notes-from-commits/</id>
    <link href="https://calmkoala.github.io/release-notes-from-commits/"/>
    <published>2026-09-12T00:00:00.000Z</published>
    <summary>把平常的修改紀錄整理成商店更新與開發紀錄，發版時少一次重新回想。</summary>
    <title>版本說明，別再發版時才重寫</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="AI" scheme="https://calmkoala.github.io/categories/study-notes/AI/"/>
    <category term="AI" scheme="https://calmkoala.github.io/tags/AI/"/>
    <category term="AI agent" scheme="https://calmkoala.github.io/tags/AI-agent/"/>
    <category term="工作流程" scheme="https://calmkoala.github.io/tags/%E5%B7%A5%E4%BD%9C%E6%B5%81%E7%A8%8B/"/>
    <content>
      <![CDATA[<p>最近我在做一套能讓 AI agent 留在背景工作、完成後再把結果送回來的系統。最先拿來測試的，是一場多角色討論：先由一個角色找資料，其他角色從不同角度提出意見，最後再整理成結論。整個流程大約要跑 5 到 10 分鐘，中間也不需要我逐句回覆，看起來很適合丟到背景，<del>終於可以假裝自己有員工了</del>。</p><p>做到一半，我卻開始卡在一些和答案聰不聰明無關的問題。資料不足時，它要直接停下來，還是自己換個題目？其中一個角色失敗後，前面完成的步驟要不要重跑？我關掉對話之後，它跑完或卡住，又要用什麼方式告訴我？</p><p>本文所說的背景 AI agent，指的是工作開始後不再佔住目前的對話；我可以先去做別的事，等它完成、失敗或需要幫忙時再回來處理。那麼，一個任務預計要跑 10 分鐘，直接丟到背景就好了嗎？我實際做完才發現，執行時間只回答了我要等多久，還沒有回答它能不能在沒有人看著時繼續工作。</p><span id="more"></span><h2 id="長時間不等於適合背景"><a href="#長時間不等於適合背景" class="headerlink" title="長時間不等於適合背景"></a>長時間不等於適合背景</h2><p>背景執行可以省下等待時間，判斷仍得由人處理。Agent 跑測試、整理資料或查文件時，我可以回到原本的工作，不必盯著畫面等它交付。不過它也少了對話裡的即時往返；需求有一點模糊、途中出現新線索，或下一步牽涉取捨時，就不適合每次都停下來等我即時決定。</p><p>我現在會先用四個問題判斷：執行中還可能改需求嗎？完成與停止條件能不能核對？中途需不需要人選方向？失敗後能不能查到狀態並安全處理？只看「會跑多久」，很容易把一件仍需要來回討論的工作提早丟出去。</p><pre><code class="mermaid">flowchart TD  START[&quot;準備交給背景 agent&quot;] --&gt; SCOPE{&quot;執行中還可能改需求嗎？&quot;}  SCOPE -- &quot;會&quot; --&gt; CHAT[&quot;留在對話裡&quot;]  SCOPE -- &quot;不會&quot; --&gt; DONE{&quot;完成與停止條件能核對嗎？&quot;}  DONE -- &quot;不能&quot; --&gt; CHAT  DONE -- &quot;能&quot; --&gt; CHOICE{&quot;中途需要人選方向嗎？&quot;}  CHOICE -- &quot;需要&quot; --&gt; CHAT  CHOICE -- &quot;不需要&quot; --&gt; FAILURE{&quot;失敗後能查到狀態並安全處理嗎？&quot;}  FAILURE -- &quot;還不能&quot; --&gt; GUARD[&quot;先補狀態、通知或人工確認&quot;]  FAILURE -- &quot;能&quot; --&gt; BACKGROUND[&quot;適合背景執行&quot;]</code></pre><h2 id="先寫好完成與停止條件"><a href="#先寫好完成與停止條件" class="headerlink" title="先寫好完成與停止條件"></a>先寫好完成與停止條件</h2><p>前面的四個問題用來判斷任務要不要交到背景；決定交出去後，我才用下面幾項把工作內容寫完整。「幫我看看最近系統有沒有問題」很難直接交給背景，AI agent 不知道該看哪些資料、查到什麼程度才算完成，也不知道找不到證據時能不能停下來。最後即使交回一份看似合理的觀察，我也很難核對它漏了什麼。</p><p>如果改成「讀最近七天的錯誤紀錄與任務失敗統計，找出重複出現的問題；沒有足夠證據就回報資料不足；有的話整理成一頁摘要並附上來源，不要修改任何設定」，任務就多了幾個可以檢查的部分：要讀哪些資料、交回什麼、何時可以停止，以及哪些動作不能做。完成後再要求它回報結果或失敗原因，背景 agent 才知道自己要走到哪裡。</p><p>我現在交代背景工作時，至少會寫下五件事：資料範圍、交付內容、停止條件、不能執行的動作，以及完成或失敗後的回報方式。就算不懂複雜的 agent 架構，也能先把原本藏在對話來回裡的判斷寫出來。</p><div class="note info no-icon"><p>背景任務可以停下來等人。資料不足時回報缺了什麼，比自己猜完再交一份完整答案更有用。</p></div><h2 id="中途要選方向，就留在對話"><a href="#中途要選方向，就留在對話" class="headerlink" title="中途要選方向，就留在對話"></a>中途要選方向，就留在對話</h2><p>同一種工作，有時適合背景執行，有時仍要留在眼前，差別通常在於下一步能不能事先決定。修 bug 就是常見的灰色地帶：如果錯誤已經可以重現、修改範圍固定，也有一組測試能判斷修好沒有，agent 可以在背景完成；如果連原因都還不知道，查到新線索後可能要跨服務修改，甚至牽涉產品行為，對話裡的即時判斷會比較省事。</p><table><thead><tr><th>工作</th><th>適合放到背景的情況</th><th>適合留在對話的情況</th></tr></thead><tbody><tr><td>修 bug</td><td>已能重現，範圍固定，有測試可核對</td><td>原因未知，途中可能擴大修改範圍</td></tr><tr><td>查資料</td><td>資料來源與比較項目已指定</td><td>還在找問題，結果會改變研究方向</td></tr><tr><td>批次改檔</td><td>改法一致，可用檢查或測試驗收</td><td>每個檔案都可能需要不同取捨</td></tr><tr><td>寫文章</td><td>格式、錯字與既定規則檢查</td><td>主題、例子與語氣還在來回調整</td></tr></tbody></table><p>這也不必硬分成「全程背景」或「全程對話」。一份探索工作可以先在背景蒐集證據，遇到岔路時停下來請人選方向，再把選定的部分交回背景執行。把人的判斷點切出來，可以分開處理探索與執行，也比較好管理。</p><h2 id="看得到狀態，才敢離開"><a href="#看得到狀態，才敢離開" class="headerlink" title="看得到狀態，才敢離開"></a>看得到狀態，才敢離開</h2><p>我的第一版會保存已完成的調查與各輪討論，遇到部分預料內的成功或失敗情況，也會更新紀錄並嘗試通知。不過我回頭檢查程式才發現，如果整場討論撞到最外層的 10 分鐘上限，內部雖然會產生失敗結果，背景入口目前沒有把它轉成通知，先前建立的討論紀錄也可能還停在「執行中」。工作已經停了，畫面看起來卻像它還在跑。</p><p>這個落差在同步對話裡很快就會被看到，放到背景後卻可能隔很久才發現。通知只能提醒我回來，系統還要留一個能查詢的地方，至少分得出「等待執行、執行中、已完成、失敗或逾時、等待人處理」。理想情況下，就算訊息沒有送達，我仍能靠任務編號回來確認；程式重新啟動後，也能找出上一次沒有收尾的工作。</p><p>如果你主要用現成的 AI 工具，不需要先做一套狀態系統，但可以留意三件事：離開頁面後任務會不會繼續、失敗時能不能查到原因，以及它需要你做決定時會停在哪裡。少了其中一項，背景執行很容易變成「晚一點回來看看有沒有結果」。</p><h2 id="外部動作不要直接重跑"><a href="#外部動作不要直接重跑" class="headerlink" title="外部動作不要直接重跑"></a>外部動作不要直接重跑</h2><p>背景工作遇到網路中斷、工具逾時或使用額度限制，重跑看起來是最直接的處理方式。讀檔、查資料、跑測試通常可以再做一次；寄信、建立排程、發版或修改正式環境就要小心，因為第一次可能已經成功，只是結果來不及傳回來。</p><p>重跑前，我會先確認前一次是否完成外部動作。單靠本機留下一筆「做過了」的紀錄仍有空隙，外部動作可能已經成功，程式卻在存好紀錄前中斷。如果一定要自動重跑，外部服務還得能用固定的請求編號辨識同一筆操作；工程上常把這種重複執行不影響結果的設計稱為「冪等」。做不到時，我會讓背景 agent 只準備資料或草稿，寄出、部署或寫入仍交回人確認。這和我在<a href="/when-multi-agent-works/">上一篇談多 agent 的文章</a>遇到的重複執行問題相同，只是沒有人盯著時更難察覺。</p><p>回到一開始的多角色討論，我願意把它放到背景，10 分鐘的執行時間只是次要理由。它要讀的資料、討論輪數與輸出格式都已經固定，找不到合適的題目也可以停下來；最後交回的是建議，不會直接替我改資料或發布內容。至於最外層逾時後的狀態與通知，我還得補完，否則它只能算「會自己跑」，還不到我能放心離開的程度。</p><p>我現在準備把工作交給背景 agent 前，會先寫出它要讀什麼、在哪裡停、怎麼回報，以及做過的動作能不能再來一次。這幾件事寫不出來，我就繼續留在對話裡。等待久一點有點煩，回來後才發現它卡在一個沒人知道的地方，顯然更煩（？）</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/when-multi-agent-works/">一個 AI agent 做不好，多開幾個就會比較好嗎？</a></li><li><a href="/ai-agent-skills-more-is-better/">Skill 裝得越多，AI agent 就越好用嗎？</a></li><li><a href="/markdown-ai-memory/">AI agent 的記憶該放哪裡？從 Markdown、SQLite 到 LLM Wiki</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/background-ai-agent-tasks/</id>
    <link href="https://calmkoala.github.io/background-ai-agent-tasks/"/>
    <published>2026-09-05T00:00:00.000Z</published>
    <summary>讓 AI agent 在背景執行，可以省下等待時間，但任務還得經得起沒人在場。從一次多角色討論的實作，整理我判斷背景任務的四個條件。</summary>
    <title>哪些工作該交給背景 AI agent？</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="開發" scheme="https://calmkoala.github.io/categories/study-notes/%E9%96%8B%E7%99%BC/"/>
    <category term="Android" scheme="https://calmkoala.github.io/tags/Android/"/>
    <category term="Google Play" scheme="https://calmkoala.github.io/tags/Google-Play/"/>
    <category term="CI/CD" scheme="https://calmkoala.github.io/tags/CI-CD/"/>
    <content>
      <![CDATA[<p>LilyScore 在我的手機上能正常開啟、能讀 PDF、能播伴奏時，我以為最難的部分已經過了。接下來大概就是把 App 打包、拖進 Google Play Console，等審核而已。</p><p>真的開始上架後，我才發現，能跑的 App 跟能上架的 App 中間，還隔著 application ID、簽章金鑰、商店資料、內容申報、測試軌與發布權限。這些設定散在本機、Play Console、Google Cloud 和 GitHub，每一項單獨看都不難，第一次卻會在同一段時間一起出現。</p><p>這篇把 LilyScore 從 Flutter 專案走到 Google Play 正式版的順序完整記下來。前半段是第一次上架一定會碰到的工作，後半段才是 GitHub Actions 自動發版；如果只想手動上傳，做到測試軌與正式版就可以停。</p><span id="more"></span><div class="note info no-icon"><p>本文最後查核日期是 2026 年 8 月 23 日。Google Play 的政策、表單與選單名稱會改，實際送審時仍要以 Play Console Dashboard 顯示的待辦和官方文件為準。</p><p>文章以 Flutter 的 Android App 為例。開始前要有一個已完成註冊與驗證的 Google Play 開發者帳號，以及能在實機執行的 App；帳號需要提供的資料會依個人或組織身分而不同。<a href="https://support.google.com/googleplay/android-developer/answer/13628312">Required information to create a Play Console developer account</a> 文章的終點是測試者能從 Google Play 安裝，並知道如何送往正式軌。</p></div><h2 id="上架流程總覽"><a href="#上架流程總覽" class="headerlink" title="上架流程總覽"></a>上架流程總覽</h2><p>我最後走過的順序如下。第一次上架的主線走到正式版就結束，自動發版是手動流程成功後才加上去的。LilyScore 的自動化終點只有 closed testing，production 仍是 Play Console 裡的人工動作。</p><pre><code class="mermaid">graph TD    app[App 可在實機執行] --&gt; identity[固定 App 永久識別字&lt;br&#x2F;&gt;application ID]    identity --&gt; key[建立上傳金鑰]    key --&gt; aab[簽出第一個上傳檔案&lt;br&#x2F;&gt;AAB]    aab --&gt; console[Play Console 建立 App]    console --&gt; listing[商店資料與內容申報]    listing --&gt; first[手動上傳第一版]    first --&gt; test[測試軌與測試者]    test --&gt; production[申請並發布正式版]    first --&gt; api[選用：設定 Play API]    api --&gt; ci[選用：自動發版&lt;br&#x2F;&gt;GitHub Actions]    ci --&gt; test</code></pre><p>整條流程牽涉五個地方。把它們分開看，遇到錯誤時會比較容易知道該去哪裡找。</p><table><thead><tr><th>場所</th><th>放什麼</th><th>大約多久處理一次</th></tr></thead><tbody><tr><td>本機</td><td>Flutter 專案、上傳金鑰、金鑰設定檔</td><td>每個 App 設定一次，金鑰長期保存</td></tr><tr><td>Play Console</td><td>App、商店資料、內容申報、測試軌、正式軌</td><td>第一次設定最多，之後每版確認</td></tr><tr><td>Google Cloud</td><td>Play API、服務帳號</td><td>只有自動上傳才需要，設定一次</td></tr><tr><td>GitHub Secrets</td><td>自動發版的簽章資料與 Play 憑證</td><td>只有自動上傳才需要，憑證輪替時更新</td></tr><tr><td>GitHub Actions</td><td>測試、建置、建立 Release、上傳測試軌</td><td>只有自動上傳才需要，每次發版執行</td></tr></tbody></table><h2 id="準備-Android-發布檔"><a href="#準備-Android-發布檔" class="headerlink" title="準備 Android 發布檔"></a>準備 Android 發布檔</h2><h3 id="固定-App-識別字"><a href="#固定-App-識別字" class="headerlink" title="固定 App 識別字"></a>固定 App 識別字</h3><p><code>applicationId</code> 是 Google Play 用來辨認 App 的永久識別字，格式通常長得像 <code>com.example.myapp</code>。第一個 AAB 上傳到 Play 後若改掉，Play 會把它視為另一個 App，原本的使用者也收不到更新，因此要在上傳前定案。<a href="https://developer.android.com/build/configure-app-module">Configure the app module</a></p><p>Flutter 專案可以在 <code>android/app/build.gradle.kts</code> 的 <code>defaultConfig</code> 找到它。還要檢查 CI 上傳步驟使用的 <code>packageName</code> 是否完全相同，大小寫也不要自行改。LilyScore 用的是 <code>com.CalmKoala.LilyScore</code>，這是專案選擇，不是 Google 要求的命名格式。</p><h3 id="建立簽章金鑰"><a href="#建立簽章金鑰" class="headerlink" title="建立簽章金鑰"></a>建立簽章金鑰</h3><p>Android App 發布時會遇到兩把金鑰。上傳金鑰（upload key）由開發者保管，用來簽署送進 Play Console 的 AAB；應用程式簽署金鑰（app signing key）由 Play App Signing 保管，Google 會用它簽署真正送到使用者裝置上的 APK。上傳金鑰遺失或外洩時可以申請重設，但仍應把金鑰檔與密碼備份好。<a href="https://developer.android.com/studio/publish/app-signing">Sign your app</a></p><p>Flutter 官方文件提供用 <code>keytool</code> 建立金鑰的方式。下面是 LilyScore 在專案根目錄使用的路徑，金鑰會放在已被 <code>.gitignore</code> 排除的 <code>android/app/</code>；建立時輸入的密碼要直接存進密碼管理器。</p><figure class="highlight powershell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">keytool <span class="literal">-genkey</span> <span class="literal">-v</span> <span class="literal">-keystore</span> android/app/upload<span class="literal">-keystore</span>.jks <span class="literal">-storetype</span> JKS <span class="literal">-keyalg</span> RSA <span class="literal">-keysize</span> <span class="number">2048</span> <span class="literal">-validity</span> <span class="number">10000</span> <span class="literal">-alias</span> upload</span><br></pre></td></tr></table></figure><p>如果終端機顯示找不到 <code>keytool</code>，先執行 <code>flutter doctor -v</code>，找到輸出裡的 <code>Java binary at</code>。<code>keytool</code> 和 <code>java</code> 會在同一個 <code>bin</code> 目錄，可以用它的完整路徑重新執行上面的指令。Android Studio 內附的 JDK 通常已經包含它，不需要另外下載來路不明的工具。</p><p>接著建立 <code>android/key.properties</code>，讓 Gradle 知道 release build 要使用哪一把金鑰。</p><figure class="highlight properties"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br></pre></td><td class="code"><pre><span class="line"><span class="attr">storePassword</span>=<span class="string">&lt;keystore 的密碼&gt;</span></span><br><span class="line"><span class="attr">keyPassword</span>=<span class="string">&lt;key 的密碼&gt;</span></span><br><span class="line"><span class="attr">keyAlias</span>=<span class="string">upload</span></span><br><span class="line"><span class="attr">storeFile</span>=<span class="string">upload-keystore.jks</span></span><br></pre></td></tr></table></figure><p>這組 <code>storeFile</code> 寫法成立，是因為 LilyScore 把金鑰放在 <code>android/app/</code>，而 Gradle 的 App module 也從這裡解析路徑。若你把金鑰放在其他位置，兩邊要一起調整。<code>key.properties</code>、<code>*.jks</code> 與 <code>*.keystore</code> 都要放進 <code>.gitignore</code>。金鑰檔轉成 base64 也只是編碼，不會因此變安全；base64 內容同樣不能放進 repo、對話紀錄或公開文件。</p><p>最後還要在 <code>android/app/build.gradle.kts</code> 載入 <code>key.properties</code>，建立 release signing config，並讓 release build type 使用它。下面保留 LilyScore 實際需要的部分，其他 Flutter 與 Android 設定不用為了這段刪掉。</p><figure class="highlight kotlin"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">import</span> java.io.FileInputStream</span><br><span class="line"><span class="keyword">import</span> java.util.Properties</span><br><span class="line"></span><br><span class="line"><span class="keyword">val</span> keystoreProperties = Properties()</span><br><span class="line"><span class="keyword">val</span> keystorePropertiesFile = rootProject.file(<span class="string">&quot;key.properties&quot;</span>)</span><br><span class="line"><span class="keyword">val</span> hasReleaseSigning = keystorePropertiesFile.exists()</span><br><span class="line"><span class="keyword">val</span> isReleaseTask = gradle.startParameter.taskNames.any &#123;</span><br><span class="line">    it.contains(<span class="string">&quot;Release&quot;</span>, ignoreCase = <span class="literal">true</span>)</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line"><span class="keyword">if</span> (hasReleaseSigning) &#123;</span><br><span class="line">    keystoreProperties.load(FileInputStream(keystorePropertiesFile))</span><br><span class="line">&#125; <span class="keyword">else</span> <span class="keyword">if</span> (isReleaseTask) &#123;</span><br><span class="line">    <span class="keyword">throw</span> GradleException(<span class="string">&quot;缺少 android/key.properties，不能建立 release 版本&quot;</span>)</span><br><span class="line">&#125;</span><br><span class="line"></span><br><span class="line">android &#123;</span><br><span class="line">    <span class="keyword">if</span> (hasReleaseSigning) &#123;</span><br><span class="line">        signingConfigs &#123;</span><br><span class="line">            create(<span class="string">&quot;release&quot;</span>) &#123;</span><br><span class="line">                keyAlias = keystoreProperties[<span class="string">&quot;keyAlias&quot;</span>] <span class="keyword">as</span> String</span><br><span class="line">                keyPassword = keystoreProperties[<span class="string">&quot;keyPassword&quot;</span>] <span class="keyword">as</span> String</span><br><span class="line">                storeFile = file(keystoreProperties[<span class="string">&quot;storeFile&quot;</span>] <span class="keyword">as</span> String)</span><br><span class="line">                storePassword = keystoreProperties[<span class="string">&quot;storePassword&quot;</span>] <span class="keyword">as</span> String</span><br><span class="line">            &#125;</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;</span><br><span class="line"></span><br><span class="line">    buildTypes &#123;</span><br><span class="line">        release &#123;</span><br><span class="line">            <span class="keyword">if</span> (hasReleaseSigning) &#123;</span><br><span class="line">                signingConfig = signingConfigs.getByName(<span class="string">&quot;release&quot;</span>)</span><br><span class="line">            &#125;</span><br><span class="line">        &#125;</span><br><span class="line">    &#125;</span><br><span class="line">&#125;</span><br></pre></td></tr></table></figure><p>這裡先檢查 <code>key.properties</code> 是否存在，是為了讓沒有私密金鑰的新 clone 仍能執行 debug build，同時讓 release build 在缺少設定時直接報錯。Flutter 新專案的 release build type 可能暫時沿用 debug key，接上這段時要把原本的 debug signing 設定移除。如果這段交給 AI 修改，我會要求它說明改了哪個檔案、release build type 最後指向哪個 signing config，再由自己檢查 diff。這樣比只問「幫我把簽章接好」更容易知道它有沒有偷偷沿用 debug key。</p><div class="note warning no-icon"><p>AI 可以幫忙產生 <code>key.properties</code> 範本、Gradle 簽章設定與檢查清單，但不要把金鑰檔、密碼或服務帳號 JSON 貼進對話。讓 AI 告訴你欄位要放在哪裡，實際值由自己填入。</p></div><h3 id="建立-AAB"><a href="#建立-AAB" class="headerlink" title="建立 AAB"></a>建立 AAB</h3><p>Android App Bundle（AAB）是送進 Google Play 的上傳檔案，Play 會再依使用者的裝置產生合適的 APK。Flutter 的 <code>pubspec.yaml</code> 會用 <code>version: x.y.z+N</code> 同時表示兩個值。前面的 <code>x.y.z</code> 會成為使用者看到的 <code>versionName</code>，加號後面的 <code>N</code> 會成為 Play 判斷新舊版本的 <code>versionCode</code>。每次上傳都要使用更大的 <code>versionCode</code>，已經上傳過的數字不能重複使用。<a href="https://developer.android.com/studio/publish/versioning">Version your app</a></p><p>簽章設定接好後，在專案根目錄執行：</p><figure class="highlight powershell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">flutter build appbundle <span class="literal">--release</span></span><br></pre></td></tr></table></figure><p>Flutter 會在 <code>build/app/outputs/bundle/release/</code> 產生 AAB。本機的完成標誌是 release AAB 成功出現，而且 <code>build.gradle.kts</code> 的 release build type 指向前面建立的 release signing config；路徑、密碼或 alias 有任何一項對不上，建置會在這裡失敗。這時也要再檢查 <code>applicationId</code> 已經定案，以及 <code>versionCode</code> 沒有用過。Flutter 官方的 Android 發布指南整理了 keystore、Gradle 與 AAB 的完整設定方式。<a href="https://docs.flutter.dev/deployment/android">Build and release an Android app</a></p><h2 id="設定-Play-Console"><a href="#設定-Play-Console" class="headerlink" title="設定 Play Console"></a>設定 Play Console</h2><h3 id="建立商店頁"><a href="#建立商店頁" class="headerlink" title="建立商店頁"></a>建立商店頁</h3><p>Play Console 的「建立應用程式」會要求預設語言、App 名稱、App 或遊戲、免費或付費、聯絡信箱與政策聲明。建立完成後，Dashboard 會列出送審前仍缺少的工作。<a href="https://support.google.com/googleplay/android-developer/answer/9859152">Create and set up your app</a></p><p>我會在開始填 Console 之前先備好下面這些材料，避免每完成一格又回頭找圖。</p><table><thead><tr><th>材料</th><th>用途或檢查方式</th></tr></thead><tbody><tr><td>App 名稱、簡短說明、完整說明</td><td>名稱與說明要和實際功能一致</td></tr><tr><td>512×512 App 圖示</td><td>Play 商店列表與搜尋結果使用</td></tr><tr><td>1024×500 主題圖片</td><td>商店刊登資訊使用</td></tr><tr><td>手機與平板截圖</td><td>依實際支援裝置準備，不要放尚未推出的畫面</td></tr><tr><td>聯絡信箱與網站</td><td>給使用者聯絡，隱私權政策也需要公開網址</td></tr><tr><td>隱私權政策</td><td>內容要對得上 App 與使用的第三方 SDK</td></tr><tr><td>測試者名單</td><td>封閉測試使用，名單內的人仍要自行 opt-in</td></tr></tbody></table><p>商店素材的尺寸與數量可能調整，正式製作前可以回到 <a href="https://support.google.com/googleplay/android-developer/answer/9866151">Add preview assets to showcase your app</a> 檢查當下要求。</p><h3 id="填寫內容申報"><a href="#填寫內容申報" class="headerlink" title="填寫內容申報"></a>填寫內容申報</h3><p>App content 不是固定十二題。Play Console 會依 App 類型、權限、目標地區與功能顯示需要填寫的申報，常見項目包含隱私權政策、廣告、審查人員如何存取 App、目標對象、內容分級、Data safety 與敏感權限。每一項都要按照 App 實際行為填寫，不能只照另一個 App 的答案複製。<a href="https://support.google.com/googleplay/android-developer/answer/9859455">Prepare your app for review</a></p><p>Data safety 特別容易和程式實作脫節。即使自己的程式沒有主動收集資料，分析、登入、付款或雲端 SDK 仍可能處理使用者資料，所以填表前要把相依套件一起檢查。AI 可以協助列出 Android manifest 的權限、專案裡使用的 SDK，以及程式可能把哪些資料送到網路，但表單答案仍要由自己對照實際行為與第三方文件確認，不能把 AI 的推測直接送出。送審前我會以 Dashboard 沒有未完成的必要項目作為完成標誌。</p><h3 id="上傳第一版"><a href="#上傳第一版" class="headerlink" title="上傳第一版"></a>上傳第一版</h3><p>Google Play Developer Publishing API 的 Edits 文件目前仍寫著，API 只能修改至少已有一個套件上傳的 App，因此第一個套件要先透過 Play Console 上傳。<a href="https://developers.google.com/android-publisher/edits">Edits</a> LilyScore 的第一顆 AAB 也走手動流程，等 Console 已經認得這個 App 後，後續版本才交給 GitHub Actions。</p><p>第一次手動上傳可以照這個順序走：</p><ol><li>打開 Play Console 並選擇 App，進入「Test and release」下的 internal testing 或 closed testing。</li><li>建立一個 release，第一次使用 AAB 時依畫面啟用 Play App Signing。</li><li>上傳前面產生的 release AAB，等 Console 完成處理並顯示新的 <code>versionCode</code>。</li><li>填寫這版的名稱與更新說明，處理 Console 顯示的錯誤或警告。</li><li>儲存後依畫面上的按鈕 rollout 或發布；是否進入審查，要看 Dashboard 與該軌道的狀態。</li><li>到測試者頁面建立 email 名單或 Google Group，取得 opt-in 連結並傳給測試者。</li></ol><p>對新 App 來說，先用 internal testing 驗證安裝速度最快，但它不會累積新個人帳號需要的 12 人、14 天 closed testing 資格。受到正式版測試門檻限制的帳號，還要另外建立 closed testing；<code>opt-in</code> 指的是測試者打開加入連結、主動成為測試成員，不是開發者把 email 填進名單就完成。<a href="https://support.google.com/googleplay/android-developer/answer/9859348">Prepare and roll out a release</a></p><p>「測試者 email 已在名單裡」還不算完成。至少要找一位測試者打開 opt-in 連結、加入測試，再從 Google Play 安裝成功；做到這裡，才代表商店資料、測試軌、簽章與發布設定真的接起來。</p><h3 id="測試內購"><a href="#測試內購" class="headerlink" title="測試內購"></a>測試內購</h3><p>如果 App 有內購，要先讓包含 Google Play Billing Library 的版本進入任一測試軌，再到 Play Console 建立商品。商品 ID 必須和程式內查詢的字串相同；建立後也要完成定價並啟用。做到商品在 Console 顯示為有效，而且 license tester 能看到測試付款工具，才算把內購測試接通。</p><p>測試軌的測試者和 license tester 是兩份設定，兩者用途不同，同一個 Google 帳號可以同時存在於兩邊。</p><table><thead><tr><th>身分</th><th>用途</th><th>容易搞錯的地方</th></tr></thead><tbody><tr><td>測試軌測試者</td><td>安裝 internal 或 closed testing 的版本</td><td>加入名單後仍要點 opt-in</td></tr><tr><td>License tester</td><td>使用測試付款工具驗證內購</td><td>只有測試軌身分仍可能被真實扣款</td></tr></tbody></table><p>如果 App 有內購，測試帳號要加到 Play Console 的 license testing 名單。裝置有多個 Google 帳號時，通常由下載 App 的帳號進行付款，因此測試前要先確認購買面板顯示的是哪一個帳號。<a href="https://developer.android.com/google/play/billing/test">Test your Google Play Billing Library integration</a></p><h3 id="封閉測試門檻"><a href="#封閉測試門檻" class="headerlink" title="封閉測試門檻"></a>封閉測試門檻</h3><p>截至 2026 年 8 月 23 日，2023 年 11 月 13 日後建立的個人開發者帳號，在取得正式版權限前，需要讓至少 12 名測試者在 closed test 持續 opt-in 14 天。時間達標後還要從 Dashboard 申請 production access，回答測試過程、收到的回饋與正式發布準備；完成測試不等於自動取得正式版權限。<a href="https://support.google.com/googleplay/android-developer/answer/14151465">App testing requirements for new personal developer accounts</a></p><div class="note warning no-icon"><p>這 14 天是日曆時間，不能在功能做完後靠自動化追回來。我下次會在 App 已經能完成主要流程時就建立 closed test，提早準備測試者與 opt-in 連結，同時繼續修畫面和商店資料。</p></div><p>取得 production access 後，可以建立正式版 release，也可以把測試軌已驗證的版本升到 production。LilyScore 的 CI 只負責把版本送進封閉測試軌，正式發布仍保留在 Play Console 手動操作，避免測試版因為打了一個 tag 就直接推給所有使用者。</p><h3 id="發布正式版"><a href="#發布正式版" class="headerlink" title="發布正式版"></a>發布正式版</h3><p>Production access 核准後，我會繼續用測試過的同一顆 AAB，不重新建一個相同 <code>versionCode</code> 的檔案。實際選單名稱可能隨 Console 改版，但目前可以照下面的順序操作。<a href="https://support.google.com/googleplay/android-developer/answer/9859348">Prepare and roll out a release</a></p><ol><li>在 Play Console 選擇 App，進入「Test and release」下的 Production。</li><li>點「Create new release」。如果按鈕不能使用，先回 Dashboard 完成它列出的設定或申報。</li><li>從 artifact library 選擇已經在測試軌驗證過的 AAB；若這版尚未上傳，也可以在這裡上傳新的 release AAB。</li><li>確認 <code>versionCode</code>、版本名稱與更新說明，並檢查要發布的國家、地區和定價設定。</li><li>處理頁面上的錯誤。警告不一定會阻擋發布，但仍要逐項確認原因，再進入 release review。</li><li>確認摘要後開始 rollout to production。第一次正式 rollout 通過審查後，會提供給所選國家與地區的使用者。</li><li>回到 Publishing overview 或 Latest releases 追蹤狀態。除了看到 Production release，也要實際打開選定地區的商店頁，確認頁面能搜尋或透過連結開啟，並從 Google Play 安裝正式版。</li></ol><p>對我來說，按下 rollout 還不算結束。Play Console 顯示正式版已發布、商店頁可開啟，而且安裝後跑得過主要流程，這一版才真正完成。</p><div class="note info no-icon"><p>如果只想完成手動上架，做到這裡就可以停。後面的 Google Cloud、服務帳號、GitHub Secrets 與 workflow 都是自動發版才需要的設定。</p></div><h2 id="設定自動發版"><a href="#設定自動發版" class="headerlink" title="設定自動發版"></a>設定自動發版</h2><p>自動發版不是第一次上架的前置條件。如果一年只更新幾次，手動簽 AAB 再上傳也能完成工作；LilyScore 會接 CI，是因為我想把測試、簽章、GitHub Release 與封閉測試上傳固定成同一條流程。</p><h3 id="授權-GitHub-Actions"><a href="#授權-GitHub-Actions" class="headerlink" title="授權 GitHub Actions"></a>授權 GitHub Actions</h3><p>CI 要對 Play 上傳，會跨 Google Cloud 與 Play Console 做一次設定。</p><ol><li>在 Google Cloud 建立或選擇一個 project。</li><li>啟用 Google Play Android Developer API。</li><li>建立專用 service account。</li><li>回到 Play Console 的「使用者和權限」，邀請 service account 的 email。</li><li>只授予這個 App 與目標測試軌需要的發布權限。LilyScore 使用「發布應用程式至測試群組」與「管理測試群組並編輯測試人員名單」，其他 App 應依 workflow 真正執行的動作縮減。</li></ol><p>服務帳號在 Google Cloud 建立，能不能發布 App 則由 Play Console 的權限決定。少做任何一邊，CI 都無法完成上傳。完成時，Play Console 的使用者清單應看得到這個 service account，而且指定 App 的權限已儲存。<a href="https://developers.google.com/android-publisher/getting_started">Getting Started — Google Play Developer API</a></p><p>LilyScore 使用 service account JSON 存進 GitHub Secret，設定快，但它是長期有效的憑證，外洩後等同別人拿到 CI 的發布身分。</p><div class="note info no-icon"><p>若下一個專案要重新建立，我會再評估 Workload Identity Federation，讓 GitHub Actions 用短期憑證連到 Google Cloud。<a href="https://cloud.google.com/iam/docs/workload-identity-federation">Workload Identity Federation</a></p><p>它只取代長期保存的 JSON key，service account 與 Play Console 授權仍然需要。Workflow 還要開啟 GitHub OIDC 權限、限制可交換身分的 repository 與 branch 或 tag，並確認上傳工具支援這種驗證方式，因此不是刪掉原本的 Secret 就完成。</p></div><h3 id="設定-GitHub-Secrets"><a href="#設定-GitHub-Secrets" class="headerlink" title="設定 GitHub Secrets"></a>設定 GitHub Secrets</h3><p>GitHub Actions 需要四項簽章資料與一項 Play API 憑證。Secret 名稱可以公開，值不行。</p><table><thead><tr><th>GitHub Secret</th><th>內容</th><th>Workflow 裡的用途</th></tr></thead><tbody><tr><td><code>ANDROID_KEYSTORE_BASE64</code></td><td>上傳金鑰檔的 base64</td><td>執行時還原 <code>upload-keystore.jks</code></td></tr><tr><td><code>ANDROID_KEYSTORE_PASSWORD</code></td><td>keystore 密碼</td><td>重建 <code>key.properties</code></td></tr><tr><td><code>ANDROID_KEY_ALIAS</code></td><td>key alias</td><td>重建 <code>key.properties</code></td></tr><tr><td><code>ANDROID_KEY_PASSWORD</code></td><td>key 密碼</td><td>重建 <code>key.properties</code></td></tr><tr><td><code>PLAY_SERVICE_ACCOUNT_JSON</code></td><td>service account JSON 全文</td><td>呼叫 Play API</td></tr></tbody></table><p>GitHub Secrets 只有在 workflow 顯式引用時才會提供給工作。Log 的遮蔽機制也不是外洩保證，因此 workflow 不應印出 Secret、解碼後的金鑰或完整環境變數。<a href="https://docs.github.com/en/actions/concepts/security/secrets">Secrets</a></p><h3 id="自動發版流程"><a href="#自動發版流程" class="headerlink" title="自動發版流程"></a>自動發版流程</h3><p>LilyScore 的 <code>release.yml</code> 會在收到 <code>v*</code> tag 後依序執行：</p><ol><li>安裝指定版本的 Flutter 與 JDK。</li><li>執行 <code>flutter analyze</code> 與 <code>flutter test</code>。</li><li>從 Secrets 還原 keystore 與 <code>key.properties</code>。</li><li>建立簽章好的 AAB，以及方便直接安裝測試的 arm64 APK。</li><li>建立 GitHub Release 並附上兩份產物。</li><li>正常版 tag 才把 AAB 上傳到 Play 封閉測試軌；帶 pre-release 字尾的 tag 不上 Play。</li></ol><p>Google Play API 裡的軌道名稱不一定等於 Console 畫面上的顯示文字。官方文件目前將 internal、open testing 與 production 的預設 API 名稱列為 <code>qa</code>、<code>beta</code>、<code>production</code>，closed testing 則可以使用自訂名稱。<a href="https://developers.google.com/android-publisher/tracks">APKs and Tracks</a> LilyScore 的 closed track 剛好叫 <code>alpha</code>，這個值不能直接複製到其他 App。</p><p>LilyScore 第一次讓 CI 上傳時遇到 <code>403</code>。服務帳號建好了，Play Console 權限也給了，最後才發現 Google Cloud 裡的 Play Developer API 沒有啟用。錯誤看起來像程式或權限壞掉，實際上只是另一個 Console 少按了一次開關。</p><h2 id="發布後續版本"><a href="#發布後續版本" class="headerlink" title="發布後續版本"></a>發布後續版本</h2><p>沒有接 CI 時，後續更新就是第一次手動上傳的縮短版。先更新 <code>versionName</code> 與 <code>versionCode</code>，執行測試並建立簽章 AAB，再到 Play Console 的目標軌道建立 release、上傳 AAB、填更新說明，最後 rollout。測試完成後要上正式版，則依前面的 production 步驟選擇同一顆 AAB。只要每次留下版本號、更新說明與測試結果，手動發版也能保有完整紀錄。</p><p>LilyScore 把這條路接上自動化後，正式封測版會從一行指令開始：</p><figure class="highlight powershell"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">scripts\release.ps1 <span class="literal">-Version</span> <span class="number">2.3</span>.<span class="number">0</span></span><br></pre></td></tr></table></figure><p>腳本會檢查目前在 <code>main</code>、工作區沒有已追蹤的未提交修改、本機沒有落後 <code>origin/main</code>、tag 尚未存在，而且 <code>flutter analyze</code> 通過。接著它更新 <code>pubspec.yaml</code> 的版本名稱、自動增加 build number、產生 Play 更新說明，最後建立 commit 與 tag，再 push 讓 CI 接手。</p><p>我另外留了三個參數，避免所有版本都只能走同一條路。</p><table><thead><tr><th>用法</th><th>作用</th></tr></thead><tbody><tr><td><code>-Notes &quot;文字&quot;</code></td><td>覆寫自動產生的 Play 更新說明</td></tr><tr><td><code>-NoPush</code></td><td>停在本機 commit 與 tag，檢查完再手動 push</td></tr><tr><td><code>-Pre alpha.1</code></td><td>建立 GitHub pre-release 與安裝檔，不上傳 Play</td></tr></tbody></table><p>Play 的「這個版本的新功能」會從上一個沒有 pre-release 字尾的 tag 開始，只取 <code>feat:</code> 與 <code>fix:</code> commit 標題；GitHub Release 則從上一個 <code>v*</code> tag 開始列出所有 commit。兩邊面向的讀者不同，所以來源範圍也不同。每次正常版最後仍要確認 Actions 全綠、Play Console 出現新的 <code>versionCode</code>，並在測試軌實際安裝一次。</p><p>正式版不由 LilyScore 的 CI 自動推送。封閉測試確認沒問題後，我會回到 Play Console，把同一顆 AAB 升到 production，再檢查送審狀態與最終商店頁。</p><h2 id="常見錯誤"><a href="#常見錯誤" class="headerlink" title="常見錯誤"></a>常見錯誤</h2><table><thead><tr><th>症狀</th><th>優先檢查</th><th>常見原因</th></tr></thead><tbody><tr><td>終端機找不到 <code>keytool</code></td><td><code>flutter doctor -v</code> 的 Java 路徑</td><td>JDK 已安裝，但它的 <code>bin</code> 不在 <code>PATH</code></td></tr><tr><td><code>Package not found</code></td><td>Play Console、<code>packageName</code></td><td>App 尚未建立、第一個套件尚未上傳，或 application ID 不一致</td></tr><tr><td>API 呼叫回傳 <code>403</code></td><td>Google Cloud、Play Console</td><td>Play Developer API 未啟用，或 service account 沒有目標 App／軌道權限</td></tr><tr><td>Play 拒收版本</td><td><code>pubspec.yaml</code>、Console 版本紀錄</td><td><code>versionCode</code> 已使用或沒有增加</td></tr><tr><td>Workflow 找不到軌道</td><td>Play Console 與 API 回傳值</td><td>把顯示名稱當成 API track name</td></tr><tr><td>CI 簽章失敗</td><td>四個 Android Secrets</td><td>keystore base64、密碼、alias 或還原路徑不一致</td></tr><tr><td>更新卡在送審前</td><td>Play Console Dashboard</td><td>商店資料、App content、定價或政策申報仍有缺項</td></tr><tr><td>測試內購出現真實卡片</td><td>License testing、裝置帳號</td><td>測試者只加入測試軌，或付款帳號不是 license tester</td></tr></tbody></table><p>遇到錯誤時，我會按照「本機 → GitHub → Google Cloud → Play Console」逐段檢查。這個順序不保證每次最快，但至少不會看到 <code>403</code> 就立刻重寫發版腳本。</p><h2 id="上架檢查清單"><a href="#上架檢查清單" class="headerlink" title="上架檢查清單"></a>上架檢查清單</h2><h3 id="一次性設定"><a href="#一次性設定" class="headerlink" title="一次性設定"></a>一次性設定</h3><ul><li><input disabled="" type="checkbox"> application ID 已定案，Gradle 與 CI 的 <code>packageName</code> 相同</li><li><input disabled="" type="checkbox"> upload keystore 已建立，金鑰與密碼分開備份</li><li><input disabled="" type="checkbox"> <code>key.properties</code>、<code>*.jks</code> 已被 <code>.gitignore</code> 擋住</li><li><input disabled="" type="checkbox"> release AAB 能在本機成功建置</li><li><input disabled="" type="checkbox"> Play Console App 已建立</li><li><input disabled="" type="checkbox"> 商店素材、聯絡資料與隱私權政策已準備</li><li><input disabled="" type="checkbox"> Dashboard 要求的 App content 已完成</li><li><input disabled="" type="checkbox"> 第一個 AAB 已手動送進測試軌</li><li><input disabled="" type="checkbox"> 測試者已 opt-in，並從 Google Play 安裝成功</li><li><input disabled="" type="checkbox"> 帳號若受測試門檻限制，closed test 已提早開始</li><li><input disabled="" type="checkbox"> production access 已申請</li><li><input disabled="" type="checkbox"> production access 已核准</li><li><input disabled="" type="checkbox"> 正式版已送審，並確認最終發布狀態</li></ul><h3 id="自動發版設定"><a href="#自動發版設定" class="headerlink" title="自動發版設定"></a>自動發版設定</h3><ul><li><input disabled="" type="checkbox"> Google Play Android Developer API 已啟用</li><li><input disabled="" type="checkbox"> service account 已建立並加入 Play Console</li><li><input disabled="" type="checkbox"> 權限只涵蓋指定 App 與需要的測試軌</li><li><input disabled="" type="checkbox"> CI 簽章資料與 Play 憑證已放入 Secrets</li><li><input disabled="" type="checkbox"> workflow 的 <code>packageName</code> 與 track name 已核對</li><li><input disabled="" type="checkbox"> CI 成功建置、簽章並上傳一個測試版</li></ul><h3 id="每版檢查"><a href="#每版檢查" class="headerlink" title="每版檢查"></a>每版檢查</h3><ul><li><input disabled="" type="checkbox"> <code>versionCode</code> 比 Play 上既有版本大</li><li><input disabled="" type="checkbox"> 使用者看得懂這版更新說明</li><li><input disabled="" type="checkbox"> analyze 與 test 通過</li><li><input disabled="" type="checkbox"> AAB 使用 release key 簽章</li><li><input disabled="" type="checkbox"> GitHub Release 與 Play 測試軌都出現預期版本</li><li><input disabled="" type="checkbox"> 從 Play 安裝並跑過主要流程</li><li><input disabled="" type="checkbox"> 要上正式版時，人工確認升軌與送審內容</li></ul><p>我還會在私有專案文件或密碼管理器的 metadata 欄位留下 application ID、GCP project 名稱、service account email、closed track 的 API 名稱、金鑰備份位置，以及最後一次查核 Play 政策的日期。公開文件只記欄位名稱與存放位置，不貼真實 project number、email 或檔案路徑。這些紀錄能省下半年後重新在四個 Console 裡找路的時間。</p><hr><p>LilyScore 終於上架後，我最想先忘掉的就是這些設定。偏偏它們又是下一個 App 最容易重踩的地方，所以這次乾脆把完成標誌、Secrets 和排錯順序一起記下來。</p><p>希望下次看到 <code>403</code> 時，我能先想到「少了哪個地方的設定」，不要又先懷疑自己把程式寫壞了。啊啊啊～</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/release-notes-from-commits/">版本說明，別再發版時才重寫</a></li><li><a href="/telegram-message-formatting/">Telegram 訊息加了格式，怎麼就送不出去了？</a></li><li><a href="/tests-pass-but-does-it-work/">測試通過，真的能用了嗎？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/google-play-first-release/</id>
    <link href="https://calmkoala.github.io/google-play-first-release/"/>
    <published>2026-08-29T00:00:00.000Z</published>
    <summary>LilyScore 上架後，我把第一次發布會碰到的簽章、商店資料、測試軌與自動發版照順序整理，留一份下一個 App 能直接跟著做的操作筆記。</summary>
    <title>第一次上 Google Play，最麻煩的不是寫 App</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="個人專案" scheme="https://calmkoala.github.io/categories/%E5%80%8B%E4%BA%BA%E5%B0%88%E6%A1%88/"/>
    <category term="LilyScore" scheme="https://calmkoala.github.io/categories/%E5%80%8B%E4%BA%BA%E5%B0%88%E6%A1%88/LilyScore/"/>
    <category term="個人專案" scheme="https://calmkoala.github.io/tags/%E5%80%8B%E4%BA%BA%E5%B0%88%E6%A1%88/"/>
    <category term="LilyScore" scheme="https://calmkoala.github.io/tags/LilyScore/"/>
    <category term="音樂" scheme="https://calmkoala.github.io/tags/%E9%9F%B3%E6%A8%82/"/>
    <content>
      <![CDATA[<p>用 Android 手機或平板看 PDF 樂譜時，同一份譜可能要搭配原調、降半音等不同調性的伴奏，另外還有慢速示範，你會怎麼整理？我以前只能把它們丟在音樂資料夾。今天想換一個調練，就先離開 PDF、打開播放器，再從一串檔名裡找版本；有時還得播放幾秒，才知道自己有沒有選對。</p><p>所以我做了 LilyScore，先把同一份 PDF 樂譜和不同版本的伴奏收在一起，打開譜就能直接切換。不過找到伴奏只是開始，想練中間八小節，要切回播放器重抓進度；老師剛提醒的指法，又得另外找地方記。從紙本換成平板之後，譜是變輕了，練習流程卻還散在好幾個地方，於是後來又補進循環播放、註記與錄音。</p><p>現在 LilyScore 樂譜練習已經在 Google Play 正式上架。我平常打開一份譜，會先選今天要用的伴奏，再開始練習那幾個一直彈不順的小節。</p><span id="more"></span><h1 id="同一份譜，切換不同的伴奏版本"><a href="#同一份譜，切換不同的伴奏版本" class="headerlink" title="同一份譜，切換不同的伴奏版本"></a>同一份譜，切換不同的伴奏版本</h1><p>我最先想處理的，就是那些明明屬於同一份譜，卻各自躺在資料夾裡的音檔。同一首曲子可能有原調、不同調性的伴奏，也可能有示範演奏、慢速版本或純伴奏。練習內容不同，看的仍是同一份譜，但在一般的檔案管理器裡，它們只是幾個彼此不認識的檔案。</p><p>在 LilyScore 裡，可以把這些音檔關聯到同一份樂譜。綁定一次，以後打開這份譜就能看到各個版本，直接選擇今天要用的伴奏，不必跳到另一個 App 找檔案。不同調性的音檔要先準備好，LilyScore 不會自動替音訊變調；它做的事，是把這些版本收在同一份譜下面，讓切換時不用重新找路。</p><h1 id="卡住的八小節，不用一直重抓進度"><a href="#卡住的八小節，不用一直重抓進度" class="headerlink" title="卡住的八小節，不用一直重抓進度"></a>卡住的八小節，不用一直重抓進度</h1><p>選好今天要用的伴奏，練習才真的開始。某一段反覆出錯時，通常得放慢、重聽，再彈一次。LilyScore 的播放器可以調整速度，也能設定 A 點與 B 點；音檔播到 B 點後會回到 A 點，讓同一段持續循環。眼睛留在譜上，手也不用每次演奏完再去拖那條細細的進度列。這就是我最想省掉的動作，A、B 點設好後，「再來一次」不用再碰進度列。</p><img src="/images/lilyscore-ab-loop.png" alt="在 LilyScore 的樂譜畫面直接播放伴奏與設定 A-B 循環" style="display: block; width: 100%; max-width: 480px; margin: 1.5rem auto;"><h1 id="想記的事，直接留在譜上"><a href="#想記的事，直接留在譜上" class="headerlink" title="想記的事，直接留在譜上"></a>想記的事，直接留在譜上</h1><p>有些提醒只在當下有意義。哪裡要換氣、哪顆音老是按錯、老師要我注意什麼，寫在另一個筆記 App 裡，下次打開譜時很容易忘記一起看。LilyScore 可以直接在譜面上使用筆、螢光筆與橡皮擦，也能加入直線與文字註記。這些標記獨立保存，不會修改原本的 PDF；備份時則會跟樂譜和其他練習資料一起打包。</p><p>也可以直接錄下這次練習，錄音檔會跟目前這份譜放在一起。下次回來時，看得到上次圈了什麼，也能聽自己上次彈成什麼樣子。<del>有時候這個功能提供的勇氣比技術更重要</del></p><img src="/images/lilyscore-annotation.png" alt="在原始 PDF 之外保存手寫與螢光筆註記" style="display: block; width: 100%; max-width: 480px; margin: 1.5rem auto;"><h1 id="練習之外，也得找得到譜"><a href="#練習之外，也得找得到譜" class="headerlink" title="練習之外，也得找得到譜"></a>練習之外，也得找得到譜</h1><p>樂譜少的時候，裝置裡放十幾份 PDF 還算好找。數量開始增加，檔名與資料夾很快就會變成另一項練習。LilyScore 有自己的樂譜庫，可以用資料夾整理、搜尋檔名，也會在首頁保留最近打開的樂譜。準備演出時，還能把要用的曲目排成演出清單，不用在台上臨時回檔案管理器翻資料夾。節拍器與調音器也在 App 裡，練習時不用再另外開一個工具。</p><img src="/images/lilyscore-library.png" alt="LilyScore 首頁的樂譜庫與最近樂譜" style="display: block; width: 100%; max-width: 480px; margin: 1.5rem auto;"><h1 id="它適合誰"><a href="#它適合誰" class="headerlink" title="它適合誰"></a>它適合誰</h1><p>如果你已經用 Android 手機或平板看 PDF 樂譜，也習慣搭配示範、伴奏或自己的錄音練習，LilyScore 會比較對位。樂譜、音訊與註記都保存在裝置上，不需要帳號，日常練習也能離線使用。換手機時，可以先匯出備份，再到新裝置匯入。第一次使用也不用先整理完整個樂譜庫，挑一兩份常練的譜放進去就好。</p><h1 id="下載-LilyScore"><a href="#下載-LilyScore" class="headerlink" title="下載 LilyScore"></a>下載 LilyScore</h1><p>LilyScore 已開放 Android 版下載。已經用手機或平板看譜，也常在幾個伴奏版本之間切換的人，可以先匯入一份常練的 PDF，再把示範或伴奏音檔放進去試試：</p><p><a href="https://play.google.com/store/apps/details?id=com.CalmKoala.LilyScore">在 Google Play 下載 LilyScore 樂譜練習</a></p><p>我已經用自己的譜測過一輪，但每個人的樂器、譜面與練習方式都不一樣。如果你碰到不好用、看不懂或缺了一步的地方，歡迎直接留言告訴我。比起猜下一個功能，真實練習時卡住的位置更值得先處理。</p><hr><p>原本只想少切一次 App，最後多寫了一整個 App。至少以後再練同一段八次時，可以把力氣留給手指，不用分一半去瞄播放進度了(？</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/tessa/">tessa：純 markdown 的 AI 多角色協作框架</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/lilyscore-launch/</id>
    <link href="https://calmkoala.github.io/lilyscore-launch/"/>
    <published>2026-08-22T00:00:00.000Z</published>
    <summary>LilyScore 是 Android 樂譜練習 App，讓同一份 PDF 樂譜關聯多個示範或伴奏音檔，看譜時就能切換、變速與循環播放。</summary>
    <title>LilyScore：我把 PDF 樂譜和伴奏放進同一個 App</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="AI" scheme="https://calmkoala.github.io/categories/study-notes/AI/"/>
    <category term="AI" scheme="https://calmkoala.github.io/tags/AI/"/>
    <category term="AI agent" scheme="https://calmkoala.github.io/tags/AI-agent/"/>
    <category term="Multi-agent" scheme="https://calmkoala.github.io/tags/Multi-agent/"/>
    <content>
      <![CDATA[<p>一個 AI agent 做不好時，多開幾個真的會比較好嗎？</p><p>我最近在做一套會把工作分給不同 AI agent 的系統，剛好有一次機會實際驗證。Agent 寄信、排程或寫入資料後，有時會直接回報完成，卻沒有讀回結果，也沒有執行測試。我於是設計了一道「硬驗證閘」，準備在它交付前檢查一次；只要系統找不到驗證紀錄，就把回覆退回去，要求 agent 補做驗證。</p><p>規格裡已經考慮了誤判、重試上限與功能開關，我甚至刻意不檢查答案對不對，只確認 agent 有沒有留下驗證的痕跡。寫完時，我已經準備把它做進系統。不過在實作前，我另外找了一個 agent，請它停止補完設計，改為想辦法把它打穿。它最後找出九個問題，其中三個足以讓整套機制無法成立。這次讓我發現，第二個 agent 有沒有用，要看它能不能拿到一項獨立、可以驗收的工作。如果它只是來「一起想」或「一起做」，增加的通常是重複判斷、交接與合併。</p><span id="more"></span><h2 id="一個看起來完整的設計，為什麼被推翻"><a href="#一個看起來完整的設計，為什麼被推翻" class="headerlink" title="一個看起來完整的設計，為什麼被推翻"></a>一個看起來完整的設計，為什麼被推翻</h2><p>當時的設計會先看 agent 使用過哪些工具。如果它執行了特定的外部變更，最後一次變更之後卻沒有讀取或測試，就退回一次，請它驗證後再交付。系統不需要理解任務內容，只要根據操作紀錄判斷，看起來既簡單又能套用到不同工作。</p><pre><code class="mermaid">flowchart LR  CHANGE[&quot;Agent 寄信、排程或寫入資料&quot;] --&gt; TRACE{&quot;最後有驗證紀錄嗎？&quot;}  TRACE -- &quot;有&quot; --&gt; DELIVER[&quot;交付結果&quot;]  TRACE -- &quot;沒有&quot; --&gt; RETRY[&quot;要求補做驗證&quot;]  RETRY --&gt; DELIVER</code></pre><p>第一個漏洞出在操作紀錄本身。這套系統可以改用不同的 AI 工具，其中一種不會回報自己做過哪些操作。Agent 明明已經改了資料，驗證閘仍看不見。我原本把設計寫成可以支援不同工具，實際上最前面的判斷條件就不成立。</p><p>重試也比我預期的危險。Agent 完成任務後，原本的工作階段可能已經被清空，它不記得前面寄過信、建立過排程，或寫入過哪些資料。這時再補一句「請驗證剛才的結果」，它可能重新做一次相同操作。原本用來避免錯誤的檢查，反而多製造一次外部變更。</p><p>即使系統看得到操作，也只能知道 agent 先寫入、後讀取，無法確認兩次操作是不是針對同一份結果。寫入 A 後讀一份無關的 B，紀錄看起來仍像做過驗證。只檢查步驟是否出現，很容易讓 agent 學會留下符合條件的紀錄，結果本身仍然沒有被確認。</p><p>我最後沒有繼續修補這道硬閘，直接把自動攔截與額外紀錄整套拿掉，改成在每位 agent 都會收到的基本規則裡要求「交付前要實際驗證，並附上證據」。這條規則比較軟，agent 仍可能漏做；至少系統不會再根據一份不完整的操作紀錄，自行判斷該不該退件。</p><h2 id="多一個-agent-什麼時候有用"><a href="#多一個-agent-什麼時候有用" class="headerlink" title="多一個 agent 什麼時候有用"></a>多一個 agent 什麼時候有用</h2><h3 id="小修改留給同一個-agent"><a href="#小修改留給同一個-agent" class="headerlink" title="小修改留給同一個 agent"></a>小修改留給同一個 agent</h3><p>改日期、修錯字，或處理低風險、可逆、影響範圍小的修改時，原本的 agent 已經知道上下文，完成標準也已經確定。我會先讓它把工作做完，失敗時再看缺的是資料、工具說明還是驗收條件。這些問題需要補回原本的任務，多開幾個 agent 只會增加交代與合併的工作。</p><h3 id="reviewer-負責找反例"><a href="#reviewer-負責找反例" class="headerlink" title="reviewer 負責找反例"></a>reviewer 負責找反例</h3><p>驗證閘已經有完整方案，缺的是有人專門檢查它在哪些情況會失效，所以我增加了一位獨立 reviewer，也就是只負責審查的 agent。它讀同一份需求、設計、已知限制與相關程式碼，交付具體反例、成立證據和影響範圍，但不直接修改方案，也不替我決定最後怎麼做。</p><p>如果我只叫第二個 agent「再幫我完善一次」，它很可能沿著原本的方向繼續補規格，最後得到一份更長的設計。這次會找到問題，與獨立的閱讀脈絡有關，也與任務寫法有關。Reviewer 被要求主動找反例、失效條件與沒有被證明的前提，最後仍由我判斷要修補、縮小範圍，或放棄整個方案。換一個 agent 不保證得到同樣結果，但比重複同一份任務更有機會看到原本的盲點。</p><h3 id="能平行的工作才拆開"><a href="#能平行的工作才拆開" class="headerlink" title="能平行的工作才拆開"></a>能平行的工作才拆開</h3><p>需要搜尋大量資料時，工作比較容易拆成互不等待的部分。假設我要整理十間公司的公開資訊，可以讓幾個 agent 各自負責幾間，再由主要 agent 合併。每條搜尋路徑不必等待其他人，也不用讓同一位 agent 讀完所有網頁。Anthropic 在 <a href="https://www.anthropic.com/engineering/multi-agent-research-system">How we built our multi-agent research system</a> 中採用的也是這類做法，以更多 token 與工具呼叫換取搜尋廣度。</p><p>程式開發通常沒有這麼乾淨。幾個 agent 可能同時修改一個檔案、共用一份資料，或執行寄信這類外部動作。沒有先分開寫入範圍，結果就可能互相覆蓋或重複執行；如果每一步又要等待前一步，多 agent 也不會帶來多少平行處理的好處。這時除了分配工作，還要處理彼此的依賴、共用的資料，以及最後由誰合併。</p><h2 id="工作拆開，不代表能平行"><a href="#工作拆開，不代表能平行" class="headerlink" title="工作拆開，不代表能平行"></a>工作拆開，不代表能平行</h2><p>把一個功能拆給三個 agent，不代表三份工作就能同時完成。例如前端要先知道資料格式，整合測試也要等前後端接起來，原本的前後依賴不會因為多開兩個 agent 消失。平行運算只能加快可以同時執行的部分，必須依序完成的步驟仍要照順序走。拆分之前，我會先看哪些工作真的可以獨立完成；如果第二步一定要等待第一步，就留給同一個 agent，或先定好前一步要交付什麼。</p><p>共用資料也是軟體架構裡常見的問題。假設兩個 agent 都從同一個舊版本開始工作，第一個新增函式後寫回檔案，第二個稍晚才完成，卻拿著舊版本覆蓋回去，前面新增的函式就消失了。Git 可能把這種情況攔成 merge conflict，直接寫入資料時也可能形成 lost update；若最後結果會隨執行先後改變，才屬於更狹義的 race condition。實作上可以切開檔案 ownership、限制只有一位 agent 寫入，外部操作則要另外考慮重複執行時是否安全。</p><p>Agent 之間每次交接都要重新說明脈絡，也可能漏掉原本的限制。程式之間傳遞訊息同樣需要格式與錯誤處理，拆得越細，花在溝通與合併的成本就越高。共同輸入還沒固定時，我會先停在單一 agent；確定可以拆開後，再指定誰負責合併，以及合併後由誰重新驗證完整結果。</p><p>一篇名為 <a href="https://arxiv.org/html/2512.08296v3">Towards a Science of Scaling Agent Systems</a> 的 v3 前印本，也觀察到類似差異。在固定總 token 預算下，集中式多 agent 在可以拆成多條資料搜尋與推理工作的 Finance Agent 測試中，比單一 agent 相對提高 80.8%；獨立式多 agent 在步驟必須依序完成的 PlanCraft 測試中，則相對下降 70%。兩個數字來自不同基準與協調架構，無法直接套到日常工作，但可以看出任務的依賴方式與 agent 之間怎麼協調，都會改變最後的結果。</p><h2 id="我現在怎麼決定要不要拆"><a href="#我現在怎麼決定要不要拆" class="headerlink" title="我現在怎麼決定要不要拆"></a>我現在怎麼決定要不要拆</h2><p>這次之後，只要我想多開一個 agent，就會先試著用一句話寫出它要獨立完成的工作。驗證閘的 reviewer 有明確任務，它要找出方案不能成立的情況；大量搜尋也能直接分出每位 agent 負責的範圍。如果最後只能寫成「一起把事情做好」，我通常不會拆，因為每個 agent 很可能重複讀取、重複判斷，最後再把幾份相似的答案交回來。</p><p>所以，當一個 agent 做不好時，我現在不會先增加數量，而是先看它缺的是資料、工具說明，還是驗收條件。這些可以補回原任務，就交給同一個 agent；若需要獨立找反例，或工作能切成互不等待的範圍，我才會多開一個。多 agent 的價值來自明確分工；多幾份相似答案，只會把判斷留到合併時再做一次。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/background-ai-agent-tasks/">哪些工作該交給背景 AI agent？</a></li><li><a href="/ai-agent-skills-more-is-better/">Skill 裝得越多，AI agent 就越好用嗎？</a></li><li><a href="/markdown-ai-memory/">AI agent 的記憶該放哪裡？從 Markdown、SQLite 到 LLM Wiki</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/when-multi-agent-works/</id>
    <link href="https://calmkoala.github.io/when-multi-agent-works/"/>
    <published>2026-08-15T01:00:00.000Z</published>
    <summary>一個 AI agent 做不好時，增加 agent 不一定能解決問題。從一次被獨立審查推翻的系統設計，整理什麼工作適合交給第二個 agent，以及拆分任務時要注意的依賴與共用資料。</summary>
    <title>一個 AI agent 做不好，多開幾個就會比較好嗎？</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="AI" scheme="https://calmkoala.github.io/categories/study-notes/AI/"/>
    <category term="AI" scheme="https://calmkoala.github.io/tags/AI/"/>
    <category term="AI agent" scheme="https://calmkoala.github.io/tags/AI-agent/"/>
    <category term="Agent Skills" scheme="https://calmkoala.github.io/tags/Agent-Skills/"/>
    <content>
      <![CDATA[<p>AI agent 的 skill 很好用。網路上可以找到各式各樣的 skill，每次看到一個可能用得上的，我總會迫不及待裝起來試試看。我原本以為，skill 裝得越多，AI agent 能做的事也會越多。</p><p>有一次，我只請它改兩段文章，它卻先整理需求、列計畫、分派工作，再安排一輪審核。模型沒有突然變笨，幾個 skill 卻讓原本簡單的工作多出許多步驟。我沒有精確量過前後差了多少 token，但計畫、分工與中間輸出都需要脈絡，工作也明顯變得笨重。類似情況發生幾次後，我重新整理自己裝過的 skill，最後刪掉了幾個。我開始在意的也不再是裝了多少，而是它該在什麼時候介入。</p><span id="more"></span><h2 id="兩個讓我開始整理-skill-的例子"><a href="#兩個讓我開始整理-skill-的例子" class="headerlink" title="兩個讓我開始整理 skill 的例子"></a>兩個讓我開始整理 skill 的例子</h2><h3 id="文章開始像同一個模板"><a href="#文章開始像同一個模板" class="headerlink" title="文章開始像同一個模板"></a>文章開始像同一個模板</h3><p>第一個 skill 用來改善文章的可讀性。它會縮短段落、增加提示句，讓讀者更容易快速掃過內容。</p><p>我把它套進 calmkoala 的文章後，句子確實變短了，整體卻開始像社群貼文。段落之間少了鋪陳，原本想慢慢帶出的觀點被切成零散的結論。Skill 有完成自己的任務，但它追求的閱讀節奏不適合這個部落格。</p><p>後來我把寫作檢查縮到草稿完成之後，只處理空泛、太像 AI 的句子，不再讓它決定開頭、結構與段落節奏。範圍縮小後，它才回到編修的位置，沒有接管作者。</p><h3 id="小修改也要跑完整流程"><a href="#小修改也要跑完整流程" class="headerlink" title="小修改也要跑完整流程"></a>小修改也要跑完整流程</h3><p>另一個 skill 提供一套完整的開發流程，包含釐清需求、規劃、分工、審核與驗證。大型功能需要這些步驟，但我平常也會請 agent 改一段說明、調整日期或修一個小錯字。</p><p>當同一套流程套到所有任務，小修改也得先產生計畫，再走完每個檢查點。輸出看起來很嚴謹，實際上增加了等待時間，也讓 agent 少了依任務大小調整做法的空間。</p><p>問題出在 skill 預設每個任務都需要完整流程。這項假設只適用一部分工作，觸發範圍卻涵蓋所有工作。</p><p>這兩個 skill 都有值得保留的內容，我最後沒有把它們整份丟掉。寫作檢查被縮到草稿完成後，完整開發流程只留給大型任務；其他規則則移到更適合的位置。</p><p>整理 skill 時，我先處理的其實不是數量，而是介入範圍。每次工作都要遵守的偏好、特定任務才需要的流程，以及能由程式判定的條件，適合的承載方式不同。先把內容分流，才知道哪些真的需要留在 skill 裡。</p><h2 id="Skill-到底改變了什麼"><a href="#Skill-到底改變了什麼" class="headerlink" title="Skill 到底改變了什麼"></a>Skill 到底改變了什麼</h2><p>大型語言模型（LLM）負責理解與產生內容，也就是聊天 AI 裡讀懂問題、生成回答的核心。AI agent 再把 LLM 與檔案、工具和工作流程連在一起，讓它能實際處理任務。</p><p>Skill 則像交給 agent 的工作手冊，裡面可以放操作步驟、參考資料、範本與腳本。它不會改變模型本身的權重，卻能在執行時補入知識、程序與限制。如果 skill 內含腳本，執行環境也允許使用相關工具，它還可能讓 agent 多一種操作方式。</p><p><a href="https://agentskills.io/client-implementation/adding-skills-support">How to add skills support to your agent</a> 將載入分成三層。Agent 啟動時先看到每個 skill 的名稱與用途，這份清單中的每個 skill 約占 50 至 100 tokens；判斷任務相關後，才載入完整的 <code>SKILL.md</code>，其餘參考檔案與腳本則按需讀取。<a href="https://agentskills.io/specification">Specification - Agent Skills</a> 定義了 skill 的檔案格式與目錄慣例，不同工具仍會用自己的方式實作載入與觸發。</p><p>例如 <a href="https://learn.chatgpt.com/docs/build-skills">Build skills | ChatGPT Learn</a> 提到，Codex 會限制初始 skill 清單占用的脈絡。數量太多時，系統會先縮短用途描述，之後可能省略部分 skill。安裝很多 skill 不等於每次都會載入全部內容，但初始清單、觸發判斷，以及觸發後增加的步驟仍然有成本。</p><h2 id="規則該放哪裡"><a href="#規則該放哪裡" class="headerlink" title="規則該放哪裡"></a>規則該放哪裡</h2><p>我查資料時，發現網路上的討論其實在回答不同問題。有人在意知識能否重用，有人看觸發是否可靠，也有人只用評測結果與權限風險決定去留。這些觀點沒有替我訂出 skill 數量，卻讓我開始先問：這份規則真的該放在 skill 裡嗎？</p><p>Vercel 曾針對 Next.js 16 文件做一組評測。沒有文件的 baseline 與預設由 agent 自行觸發 skill 的通過率都是 53%，而且 56% 的案例根本沒有觸發 skill；明確要求使用後提高到 79%，把壓縮後的文件索引放進 <code>AGENTS.md</code> 則達到 100%。這是特定框架與評測的結果，不能直接套用到所有任務，但它顯示內容寫對仍不夠，資訊放在哪裡也會影響 agent 能不能在需要時取得。<a href="https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals"><code>AGENTS.md</code> outperforms skills in our agent evals</a></p><p>我目前用下面這張表做第一輪分流。這是我的設計判斷，不是 Agent Skills 規格規定的分類。</p><table><thead><tr><th>想解決的事情</th><th>適合的位置</th><th>例子</th></tr></thead><tbody><tr><td>幾乎每次工作都要遵守的簡單規則</td><td>專案指引</td><td>使用繁體中文、公開檔不加入工具署名</td></tr><tr><td>只有特定任務需要的詳細做法</td><td>Skill</td><td>處理 PDF、整理會議記錄、操作瀏覽器</td></tr><tr><td>需要另一個不受原對話影響的視角，或不同工具權限</td><td>獨立 agent</td><td>把草稿交給第一次閱讀的讀者身分審稿</td></tr><tr><td>需要存取外部服務或資料</td><td>工具與權限設定</td><td>查詢資料庫、讀取行事曆</td></tr><tr><td>有明確條件，而且不得漏驗</td><td>程式與測試</td><td>檔案格式、必填欄位、建置是否成功</td></tr></tbody></table><p>專案指引在不同工具裡可能叫 custom instructions、rules 或 <code>AGENTS.md</code>，用途是提供經常需要的背景。只有工具真的分開對話、背景或權限時，另一個 agent 才可能形成不同的審查脈絡；多開一個聊天室不等於自動得到獨立判斷。</p><p>例如「所有公開文章都用繁體中文」適合放在專案指引；「處理 PDF 後要逐頁檢查排版」可以做成 skill；「程式一定要通過測試」則應交給測試與 CI 檢查強制執行，不能只要求 agent 記得。</p><h2 id="我怎麼測一個-skill"><a href="#我怎麼測一個-skill" class="headerlink" title="我怎麼測一個 skill"></a>我怎麼測一個 skill</h2><h3 id="先確認它會在對的時候出現"><a href="#先確認它會在對的時候出現" class="headerlink" title="先確認它會在對的時候出現"></a>先確認它會在對的時候出現</h3><p>我不再因為 skill 看起來完整就安裝。一般任務中，agent 要在同一類工作反覆犯錯，而且處理方式已經穩定，才值得整理成可重用的 skill。只發生一次的問題，可以先在對話中補充；任務範圍說不明白時，skill 的用途描述也很難寫準。</p><p>低頻但後果嚴重的安全或合規問題不能等它重複發生。這類條件更適合交給權限、程式檢查或人工核准，避免把防線只寫在 skill 裡。</p><p>測試時，我會同時準備應該觸發與不該觸發的任務。後者很重要，因為一個 skill 能在 PDF 任務正確出現，不代表它不會在寫文章時插手。</p><h3 id="再比較加入前後"><a href="#再比較加入前後" class="headerlink" title="再比較加入前後"></a>再比較加入前後</h3><p>2026 年的 <a href="https://arxiv.org/abs/2603.15401">SWE-Skills-Bench: Do Agent Skills Actually Help in Real-World Software Engineering?</a> 前印本測試 49 個軟體開發 skill，其中 39 個沒有提高任務通過率，7 個帶來明顯改善，另有 3 個因版本不合而讓表現下降。這份研究一次評估一個任務與一個 skill，沒有測試大型 skill 清單的觸發問題，因此不能拿來訂出數量上限。對我真正有用的結論只有一個：看起來完整，不代表加入後真的會變好。</p><p>我會在安裝前後各跑幾個平常真的會遇到的任務，觀察有沒有少來回修改一次、是否補上原本常漏的步驟，以及處理時間增加多少。我也會放進幾個不該用到這個 skill 的任務，看看它會不會插手。</p><p>假設我想安裝一個 PDF skill，我會先確認自己是否反覆遇到文字擷取或排版漏檢，再用一份 PDF 測它能否補上問題。接著改請 agent 寫文章，確認 PDF 流程不會跑出來。兩邊都符合預期，才有留下的理由。</p><h3 id="模型更新後重跑"><a href="#模型更新後重跑" class="headerlink" title="模型更新後重跑"></a>模型更新後重跑</h3><p>有些 skill 用來補模型當時不穩定的能力。假如流程 skill 原本是為了解決長任務經常做漏，模型或工具更新後，就該重跑當初用來驗證它的任務。在這些測試中停用 skill 沒有造成可觀察的退步，就可以考慮移除。</p><p>Anthropic 在 <a href="https://www.anthropic.com/engineering/harness-design-long-running-apps">Harness design for long-running application development</a> 中也用逐一移除流程元件的方式，檢查哪些做法仍會影響結果。保存領域知識或必要流程的 skill，則要檢查內容是否過期；低頻但高風險的流程也不能只靠少量測試決定去留。</p><h2 id="安裝前先確認能不能信任"><a href="#安裝前先確認能不能信任" class="headerlink" title="安裝前先確認能不能信任"></a>安裝前先確認能不能信任</h2><p>下載第三方 skill 時，我會先看 <code>SKILL.md</code>、參考檔案、附帶腳本，以及它宣告的相依套件。程式規模太大，不一定能逐行讀完，但至少要確認安裝腳本、外連位置、版本鎖定與權限要求。Skill 要求登入、提供 token、下載額外程式、批次讀寫或上傳檔案時，我不會只因為名稱看起來有用就授權。</p><p>即使 skill 沒有附帶腳本，風險也不會消失。<code>SKILL.md</code> 裡的文字本身就會影響 agent 的行為。<a href="https://arxiv.org/abs/2602.20156">Skill-Inject: Measuring Agent Vulnerability to Skill File Attacks</a> 用 202 組刻意設計的攻擊任務，測試透過 skill 檔案發動的提示注入，部分受測 agent 的攻擊成功率最高達 80%。這個數字只適用於刻意植入惡意指令的測試，不能推論市面上有 80% 的 skill 都是惡意內容；它提醒我，來源審查與最小權限不能交給模型能力代替。</p><p>名稱無法證明 skill 實際會做什麼，即使沒有腳本，文字指令也可能讓 agent 改變做法。看不懂內容時，我至少不會先提供 token、批量檔案存取或上傳權限。</p><h2 id="我現在留下-skill-的條件"><a href="#我現在留下-skill-的條件" class="headerlink" title="我現在留下 skill 的條件"></a>我現在留下 skill 的條件</h2><p>我現在只留下能說明任務範圍、補上重複失敗、通過前後比較，而且內容與權限值得信任的 skill。其中一項答不出來時，我會先停用。停用後結果沒有可觀察的差別，就移除；仍有局部價值，就縮小觸發範圍，或把規則移到專案指引、程式檢查與權限設定。</p><p>第五個 skill 仍可能有價值，第二個也可能是多餘的。數量沒有通用門檻，每一個都要證明自己值得留在清單裡。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/background-ai-agent-tasks/">哪些工作該交給背景 AI agent？</a></li><li><a href="/when-multi-agent-works/">一個 AI agent 做不好，多開幾個就會比較好嗎？</a></li><li><a href="/markdown-ai-memory/">AI agent 的記憶該放哪裡？從 Markdown、SQLite 到 LLM Wiki</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/ai-agent-skills-more-is-better/</id>
    <link href="https://calmkoala.github.io/ai-agent-skills-more-is-better/"/>
    <published>2026-08-08T05:00:00.000Z</published>
    <summary>Skill 裝得更多，不代表 AI agent 會持續變好。從整理與刪減 skill 的經驗，比較不同觀點，以及如何判斷規則該放在 skill、專案指引、獨立 agent 或程式檢查。</summary>
    <title>Skill 裝得越多，AI agent 就越好用嗎？</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="AI" scheme="https://calmkoala.github.io/categories/study-notes/AI/"/>
    <category term="AI" scheme="https://calmkoala.github.io/tags/AI/"/>
    <category term="系統設計" scheme="https://calmkoala.github.io/tags/%E7%B3%BB%E7%B5%B1%E8%A8%AD%E8%A8%88/"/>
    <category term="記憶系統" scheme="https://calmkoala.github.io/tags/%E8%A8%98%E6%86%B6%E7%B3%BB%E7%B5%B1/"/>
    <content>
      <![CDATA[<p>剛開始用 AI agent 寫程式時，我沒有特別在意記憶這件事。只要工作留在同一段對話裡，它還記得前面做過的決定，也知道我剛才否決了哪個方案，感覺一切都沒問題，直到我關掉對話，隔天開啟新的工作階段之後。昨天已經決定不用的工具又被提了一次，commit message 的格式要重新交代，做到一半的工作也得花時間說明。</p><p>我最早的處理方式很直覺，把這些內容寫進 <code>MEMORY.md</code>，每次開始前讓 agent 讀取。這個方法一開始確實有用，新對話終於不必每次都從頭建立背景知識。</p><p>但我把這個方法放進三個專案跑了兩個月後，一份檔案開始同時裝著長期規則、短期進度與知識整理。它們都被叫作記憶，保存期限和使用方式卻不一樣。</p><p>這時我才把 LLM 與 AI agent 分開看。LLM 負責理解文字與產生回答；AI agent 則是包住 LLM、能儲存資料與呼叫工具的完整系統。跨對話記憶由外層系統保存，再於適當時機交給 LLM。</p><p>Hermes 把精選資訊放進 Markdown，完整對話則存進 SQLite；Andrej Karpathy 的 LLM Wiki 讓 agent 持續整理讀過的資料。</p><p>我的三層協定處理的範圍比較小，分成持久記憶、工作階段摘要與啟動讀取。第一層保存長期規則，第二層記錄近期進度，第三層規定新對話要載入哪些檔案。把這些案例放在一起，可以看出不同記憶各自需要的讀寫方式。</p><span id="more"></span><div class="note info no-icon"><p><strong>快速摘要</strong>：AI agent 的記憶要先決定資訊何時被讀取與更新，再選擇 Markdown、資料庫或 wiki。最近的工作進度屬於歷史的一部分，可以先產生工作階段摘要，需要原文時再回頭搜尋。</p></div><h2 id="先按用途分類"><a href="#先按用途分類" class="headerlink" title="先按用途分類"></a>先按用途分類</h2><p>如果使用者說「commit message 請用中文」，agent 在下一場工作開始時就要知道。這類資訊數量不多，使用頻率很高，適合放進精簡的偏好或專案記憶。</p><p>「找出上星期討論過的三個名稱」屬於另一種需求。完整對話可能累積幾十萬字，沒有必要每次全部交給 LLM。系統可以保存原始內容，等使用者問起時再搜尋。</p><p>最近的工作進度也屬於歷史資訊，但下一場對話很可能立即用到。系統可以在工作結束時先留下短摘要，接續時直接讀摘要；需要細節時，再回到完整對話。</p><p>「把最近讀過的資料整理成一套知識」又多了一項工作。系統要比較不同來源、更新舊結論，並保留內容之間的關聯。單純找回一段原文不夠，還需要一層持續維護的整理結果。</p><pre><code class="mermaid">flowchart LR  ASK[&quot;希望 agent 記住的內容&quot;] --&gt; ALWAYS[&quot;每次對話都要知道&quot;]  ASK --&gt; HISTORY[&quot;需要時找回原文&quot;]  ASK --&gt; KNOWLEDGE[&quot;持續整理與更新&quot;]  ALWAYS --&gt; CURATED[&quot;少量精選記憶&quot;]  HISTORY --&gt; SEARCH[&quot;需要原文&lt;br&#x2F;&gt;搜尋歷史紀錄&quot;]  HISTORY --&gt; SUMMARY[&quot;近期接續&lt;br&#x2F;&gt;讀工作階段摘要&quot;]  KNOWLEDGE --&gt; WIKI[&quot;agent 維護的知識 wiki&quot;]</code></pre><p>這張圖沒有指定一定要用哪套工具。它先處理資訊何時會被使用，再決定寫入時機、讀取方式與儲存位置。</p><h2 id="兩個外部案例"><a href="#兩個外部案例" class="headerlink" title="兩個外部案例"></a>兩個外部案例</h2><h3 id="Hermes：分開存偏好與對話"><a href="#Hermes：分開存偏好與對話" class="headerlink" title="Hermes：分開存偏好與對話"></a>Hermes：分開存偏好與對話</h3><p>Hermes Agent 同時使用 Markdown 與資料庫。</p><p>它把經過挑選的內容放進 <code>MEMORY.md</code> 和 <code>USER.md</code>。前者保存環境、專案慣例與 agent 學到的經驗；後者記錄使用者偏好和溝通方式。根據本文查核時的 <a href="https://hermes-agent.nousresearch.com/docs/user-guide/features/memory/">Persistent Memory | Hermes Agent</a>，兩份檔案的預設上限分別是 2,200 與 1,375 個字元，合計約 1,300 個模型輸入單位（tokens）。</p><p>每場工作階段（session）開始時，Hermes 會把兩份內容以固定快照放進系統提示詞（system prompt）。寫滿後，agent 必須先合併或移除舊條目，不能讓常駐記憶一直增加。</p><p>固定快照也帶來一項限制。Agent 在同一場工作階段中修改記憶後，資料會立即寫進檔案，但已建立的系統提示詞不會同步改變。新的內容要等下一場工作階段才會進入常駐脈絡。</p><p>完整對話走另一條路。Hermes 把 CLI 與訊息平台的工作階段存進 SQLite，再透過 FTS5 做全文搜尋。使用者問起幾星期前的討論時，agent 才搜尋過去的訊息，取回資料庫裡的原文。</p><p>FTS5 是全文搜尋，不是語意搜尋。歷史訊息和問題使用不同說法時，仍可能找不到結果。它的優點是能保存完整紀錄，也不會讓每次對話都負擔全部歷史的輸入成本。</p><p>Hermes 的做法可以用兩句話理解。「使用者偏好簡短回答」每次都會影響結果，因此放進精選記憶；「上星期二討論過哪些名稱」只在特定問題出現時有用，因此保存原文再按需搜尋。</p><h3 id="LLM-Wiki：整理跨來源知識"><a href="#LLM-Wiki：整理跨來源知識" class="headerlink" title="LLM Wiki：整理跨來源知識"></a>LLM Wiki：整理跨來源知識</h3><p>歷史搜尋能找回說過的內容，卻不會自動把幾十份資料整理成一套持續更新的知識。</p><p>Karpathy 提出的 <a href="https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f">llm-wiki</a> 是一份能交給 AI agent 實作的構想。它包含三層。</p><ul><li>原始來源由使用者提供，agent 只讀取、不修改，作為查證依據。</li><li>Wiki 由 agent 建立與維護，內容包括摘要、主題頁、比較結果與交叉連結。</li><li>結構規則（schema）文件規定資料結構、命名方式，以及匯入、查詢和維護流程。使用 Codex 時，可以把這些規則寫進 <code>AGENTS.md</code>。</li></ul><p>加入一份新資料時，agent 會讀取內容、更新相關主題頁，並記錄新資料和舊結論之間的矛盾。使用者提出的新問題若產生值得保留的分析，也能寫回 wiki，成為之後繼續使用的整理成果。</p><p><code>index.md</code> 負責列出現有頁面與摘要，<code>log.md</code> 記錄每次匯入、查詢與整理的時間。Karpathy 在原始構想中提到，約 100 份來源、數百個頁面的規模仍能用索引檔導覽。這是他的使用經驗，不代表所有資料集都會得到相同結果。資料繼續增加後，Markdown 也能再搭配全文或語意搜尋。</p><p>LLM Wiki 中的主題頁是 agent 根據原始資料整理的結果。重要內容仍要保留它引用了哪些原始來源。缺少來源鏈時，後續頁面可能把先前的摘要當成原始證據，錯誤也會跟著交叉引用繼續流傳。</p><p>Karpathy 的做法還規定 agent 如何更新索引、修訂頁面、找出矛盾與檢查失效內容，Markdown 是承載這套流程的格式。</p><h2 id="我的三層協定"><a href="#我的三層協定" class="headerlink" title="我的三層協定"></a>我的三層協定</h2><p>我的使用情境比 LLM Wiki 小很多。我想處理的是開發偏好、已拍板的專案決策，以及一場工作結束後要如何接續。</p><p>每個專案只有一位使用者，記憶量大約落在幾十到幾百條。我用 Markdown 建立三層協定，並放進三個專案執行了兩個月。</p><h3 id="第一層：持久記憶"><a href="#第一層：持久記憶" class="headerlink" title="第一層：持久記憶"></a>第一層：持久記憶</h3><p>第一層保存使用者偏好、架構決策、否決理由與專案慣例。一則記憶使用一個檔案，附上類型、日期與一句摘要。</p><p><code>MEMORY.md</code> 只放索引，不把所有內文常駐塞進模型脈絡（context）。Agent 遇到相關工作時，再依索引讀取對應檔案。</p><p>我也會保存方案被拒絕的理由。只記住最後選了 A，下一場對話仍可能再次提出 B；把當時的限制一起留下，才能減少重跑同一段討論。</p><h3 id="第二層：工作階段摘要"><a href="#第二層：工作階段摘要" class="headerlink" title="第二層：工作階段摘要"></a>第二層：工作階段摘要</h3><p>「今天修改了哪些檔案」和「還有哪一項測試沒通過」通常只需要保留幾天，不適合和長期偏好共用相同生命週期。</p><p>每場工作告一段落後，agent 會在 <code>memory/sessions/</code> 留下摘要，記錄這次完成的內容、已決定的選項、尚未完成的工作，以及較重要的檔案變動。</p><p>這份摘要接近交接文件。它讓下一場對話知道工作停在哪裡，也避免每次重新搜尋與閱讀完整歷史。</p><p>檔案不會自己出現。我把觸發條件寫進專案的 <code>AGENTS.md</code>，規定使用者準備離開、工作完成或切換主題時產生摘要。使用的工具若不會自動載入專案指引，就要在對話中另外要求。程式意外中斷時仍可能來不及留下摘要，下一場只能改從 Git diff、任務狀態或原始對話恢復進度。</p><h3 id="第三層：啟動讀取"><a href="#第三層：啟動讀取" class="headerlink" title="第三層：啟動讀取"></a>第三層：啟動讀取</h3><p>檔案寫好後，還要規定讀取時機。</p><p>我的做法是在新對話開始時讀取 <code>MEMORY.md</code>，再讀最近三篇工作階段摘要。索引提供長期背景，近期摘要負責恢復進度。如果最後一篇還有未完成項目，agent 會用一兩句提醒我。</p><p>「最近三篇」是目前實際使用後留下的數量。全部載入會讓舊進度占用太多脈絡，只讀一篇又可能漏掉連續幾場的工作。不同專案可以依工作節奏調整。</p><h2 id="記憶也需要維護"><a href="#記憶也需要維護" class="headerlink" title="記憶也需要維護"></a>記憶也需要維護</h2><h3 id="過期與衝突"><a href="#過期與衝突" class="headerlink" title="過期與衝突"></a>過期與衝突</h3><p>跑了兩個月後，最常出現的問題是重複內容與決策過期。</p><p>同一項偏好可能被不同說法記錄三次。其中一份更新後，其餘兩份仍留著舊內容，agent 讀完只能重新判斷該相信哪一份。因此每次寫入前都要搜尋既有條目，找到相近內容就更新原檔。</p><p>已經翻案的決策也要修改、刪除或標示為失效。日期只能說明內容何時寫入，無法證明它現在仍然成立。專案決策還需要保留目前狀態，以及取代它的新決策。</p><p>這些維護規則不限定 Markdown。資料放進 SQLite 或其他資料庫後，仍要處理重複、過期與互相矛盾的內容。儲存空間增加，不會自動判斷哪一筆資訊仍然可信。</p><h3 id="來源與敏感資料"><a href="#來源與敏感資料" class="headerlink" title="來源與敏感資料"></a>來源與敏感資料</h3><p>Wiki 還要多處理來源鏈。Agent 產生的摘要需要指回原始文件，新的來源推翻舊結論時，也要知道哪些頁面需要更新。</p><p>保存完整對話也會留下密鑰、個人資料與內部資訊。我會把記憶目錄留在本機，不提交到公開 repository。一般專案可以先把記憶檔案與 SQLite 加進 <code>.gitignore</code>；確實需要版本紀錄時，再使用私人 repository，並在寫入前排除 API keys、access tokens 與其他敏感內容。</p><h2 id="選擇記憶做法"><a href="#選擇記憶做法" class="headerlink" title="選擇記憶做法"></a>選擇記憶做法</h2><h3 id="四種做法可以並存"><a href="#四種做法可以並存" class="headerlink" title="四種做法可以並存"></a>四種做法可以並存</h3><table><thead><tr><th>要記住的內容</th><th>讀取時機</th><th>適合的處理方式</th><th>主要限制</th></tr></thead><tbody><tr><td>穩定偏好與重要規則</td><td>每場對話開始</td><td>容量受控的精選記憶</td><td>每次都占用模型輸入空間，過期內容會持續影響回答</td></tr><tr><td>完整歷史對話</td><td>使用者問起舊內容時</td><td>資料庫與全文搜尋</td><td>問法不同時可能搜尋不到</td></tr><tr><td>最近工作進度</td><td>接續前幾場工作時</td><td>工作階段摘要與索引</td><td>摘要會遺失部分原始細節</td></tr><tr><td>跨來源整理後的知識</td><td>加入來源或提出新問題時</td><td>agent 維護的 wiki</td><td>需要保留來源並處理衝突</td></tr></tbody></table><p>同一個專案可以同時使用四列。以我自己的協定為例，未來若工作階段數量增加，我可以保留現有的 Markdown 持久記憶，再替完整歷史加入 SQLite 搜尋，不必把所有檔案搬進資料庫。</p><h3 id="先檢查現有設計"><a href="#先檢查現有設計" class="headerlink" title="先檢查現有設計"></a>先檢查現有設計</h3><p>不熟悉資料庫結構或檢索程式碼，也能先讓正在使用的 AI agent 畫出資訊從哪裡進入、保存到哪裡，以及下一場工作如何讀回來。</p><p>下面這段可以直接交給它。</p><figure class="highlight text"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br></pre></td><td class="code"><pre><span class="line">請實際檢查這個專案目前的 AI agent 記憶設計，不要只根據 README 推測，也不要先修改程式碼。</span><br><span class="line"></span><br><span class="line">1. 畫出一段資訊從對話進入系統、被保存，到下一場對話重新取用的完整流程。</span><br><span class="line">2. 把現有資訊分成四類：</span><br><span class="line">   - 每場工作都要使用的精選資訊</span><br><span class="line">   - 需要時才搜尋的原始歷史</span><br><span class="line">   - 需要持續整理與修訂的知識</span><br><span class="line">   - 只負責近期工作接續的摘要</span><br><span class="line">3. 對每一類標出儲存位置、寫入時機、讀取時機、更新方式、刪除方式與原始來源。</span><br><span class="line">4. 檢查同一項偏好重複出現、舊決策已經翻案，以及 agent 找不到過去原文時，系統目前會怎麼處理。</span><br><span class="line">5. 如果系統服務多位使用者，標出身份由哪裡取得，以及查詢如何限制只能讀取目前使用者的資料。</span><br><span class="line">6. 提出最小修改方案並規劃測試。沒有實作的部分請標示「目前缺少」，不要假設它已經存在。</span><br><span class="line"></span><br><span class="line">請先提供流程圖、分類表、風險與測試計畫，等我確認後再修改專案。</span><br></pre></td></tr></table></figure><p>這段提示先要求 agent 檢查現有流程，再提出修改。只說「幫我做一套記憶系統」，很容易直接得到一組技術選型，卻沒有回答哪些資訊需要常駐、哪些應該搜尋。</p><h3 id="多人服務要加身份隔離"><a href="#多人服務要加身份隔離" class="headerlink" title="多人服務要加身份隔離"></a>多人服務要加身份隔離</h3><p>本文的三個案例主要處理個人 agent 與知識管理。系統開始服務多位使用者後，每一筆偏好、歷史對話與 wiki 內容還要標示擁有者，並在讀取時檢查權限。</p><p>資料庫能保存很多人的歷史，但每次搜尋仍要帶入經過驗證的使用者身份。這份身份不能由 LLM 自己填寫，否則仍可能讀到另一位使用者的資料。相關的身份來源與權限流程，我整理在上一篇<a href="/llm-agent-isolation/">〈多人共用 AI bot，別讓它認錯使用者〉</a>。</p><p>檔案或資料庫解決的是內容放在哪裡，權限系統決定目前的人可以讀哪一部分。兩項都完成後，記憶才適合進入多人服務。</p><h2 id="我目前的選擇"><a href="#我目前的選擇" class="headerlink" title="我目前的選擇"></a>我目前的選擇</h2><p>我的三個專案目前會繼續使用三層 Markdown 協定，因為現有規模仍能人工閱讀與維護。若要保留大量完整對話，我會增加資料庫搜尋；開始進行長期、多來源研究後，再獨立建立 LLM Wiki。</p><p>這篇寫完後，我的協定會把這次工作記進工作階段摘要；Hermes 會把完整對話留在 SQLite；如果把資料交給 LLM Wiki，它還會更新相關主題頁。三種做法都叫記憶，保存下來的內容卻不相同。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/llm-agent-isolation/">多人共用 AI bot，別讓它認錯使用者</a></li><li><a href="/background-ai-agent-tasks/">哪些工作該交給背景 AI agent？</a></li><li><a href="/when-multi-agent-works/">一個 AI agent 做不好，多開幾個就會比較好嗎？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/markdown-ai-memory/</id>
    <link href="https://calmkoala.github.io/markdown-ai-memory/"/>
    <published>2026-08-01T01:00:00.000Z</published>
    <summary>AI agent 的記憶可以同時使用 Markdown、SQLite 與 LLM Wiki。從 Hermes、LLM Wiki 與個人三層協定，比較精選記憶、歷史搜尋、知識整理與工作接續的分工。</summary>
    <title>AI agent 的記憶該放哪裡？從 Markdown、SQLite 到 LLM Wiki</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="AI" scheme="https://calmkoala.github.io/categories/study-notes/AI/"/>
    <category term="AI" scheme="https://calmkoala.github.io/tags/AI/"/>
    <category term="系統設計" scheme="https://calmkoala.github.io/tags/%E7%B3%BB%E7%B5%B1%E8%A8%AD%E8%A8%88/"/>
    <category term="安全" scheme="https://calmkoala.github.io/tags/%E5%AE%89%E5%85%A8/"/>
    <content>
      <![CDATA[<p>試著想像一個故事：小明和小美共用同一個 AI bot。兩人都會請它記住一些事情，可能是待辦、工作筆記，也可能是不想讓對方看到的私人內容。</p><p>當小明問「我上次說過什麼？」時，bot 卻把小美留下的內容回傳給他。一次錯誤回答，就變成了私人資料外洩。</p><p>這裡要先分清楚 bot 和 AI。bot 是整套應用系統，負責接收訊息，並串起身份確認、工具與資料。AI 是其中負責理解文字、選擇下一步操作的元件。</p><p>要避免拿錯資料，bot 必須在把訊息交給 AI 之前，先從聊天平台或登入系統確認訊息是誰傳的，不能讓 AI 自己判斷身分。AI 可以判斷小明想找什麼，但不能決定自己目前是代表小明還是小美。</p><pre><code class="mermaid">flowchart LR    U[&quot;小明傳來訊息&quot;] --&gt; P    subgraph B[&quot;AI bot 系統&quot;]        P[&quot;訊息入口&lt;br&#x2F;&gt;確認是小明&quot;] --&gt; A[&quot;AI&lt;br&#x2F;&gt;理解小明想做什麼&quot;]        A --&gt; T[&quot;記憶工具&lt;br&#x2F;&gt;沿用已確認的身份&quot;]    end    T --&gt; D[&quot;只讀小明的資料&quot;]</code></pre><p>圖中的 AI 位於 bot 系統裡面，只負責理解需求。訊息入口先確認現在是誰，記憶工具再沿用這個結果查詢資料。把身份也交給 AI 填，它就有機會用別人的身份讀資料。</p><p>模型可能誤解對話、受到提示注入影響，或在呼叫工具時填錯資料。身份是權限的起點，不能建立在「模型應該會填對」的假設上。</p><span id="more"></span><h2 id="工具把-AI-填的身份當成真的"><a href="#工具把-AI-填的身份當成真的" class="headerlink" title="工具把 AI 填的身份當成真的"></a>工具把 AI 填的身份當成真的</h2><p>我的 bot 只有兩名固定使用者。AI 要讀取記憶時，會呼叫我提供的工具。第一版的工具要求 AI 填入兩個值。</p><table><thead><tr><th>欄位</th><th>代表什麼</th><th>第一版由誰填</th></tr></thead><tbody><tr><td><code>memory_id</code></td><td>想讀哪則記憶</td><td>AI</td></tr><tr><td><code>requester_id</code></td><td>現在是哪位使用者</td><td>AI</td></tr></tbody></table><p>問題就在第二個值。當小明傳來訊息時，只要 AI 取得小美某則記憶的編號，再把 <code>requester_id</code> 填成小美，工具查到的「記憶主人」就會和 <code>requester_id</code> 相同。</p><p>從工具的角度看，記憶主人和提出要求的人都是小美。它沒有收到平台確認的真正身份，因此不知道原始訊息來自小明，權限檢查仍然會通過。</p><p>當時的程式碼大概長這樣。</p><figure class="highlight python"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line"><span class="keyword">def</span> <span class="title function_">read_memory</span>(<span class="params">memory_id: <span class="built_in">str</span>, requester_id: <span class="built_in">str</span></span>) -&gt; <span class="built_in">str</span>:</span><br><span class="line">    memory = load(memory_id)</span><br><span class="line">    <span class="keyword">if</span> memory.owner != requester_id:</span><br><span class="line">        <span class="keyword">raise</span> PermissionError(<span class="string">&quot;not your memory&quot;</span>)</span><br><span class="line">    <span class="keyword">return</span> memory.content</span><br></pre></td></tr></table></figure><p>程式裡的 <code>if</code> 只確認「記憶主人」和 <code>requester_id</code> 是否相同。由於 <code>requester_id</code> 也是 AI 填的，這個檢查無法確認真正傳來訊息的人。</p><p><code>memory_id</code> 可以由模型選，工具再用可信身份檢查目前使用者是否有權讀取。<code>requester_id</code> 則是認證結果，必須來自聊天平台或登入系統，不能由模型自己聲明。</p><h2 id="主要靠-AI-寫程式，也能先檢查三件事"><a href="#主要靠-AI-寫程式，也能先檢查三件事" class="headerlink" title="主要靠 AI 寫程式，也能先檢查三件事"></a>主要靠 AI 寫程式，也能先檢查三件事</h2><p>如果你平常主要靠 vibe coding，不必先學會審查每一行程式。請 AI 回答下面三件事，就能找到需要進一步檢查的地方。</p><h3 id="追出身份從哪裡來"><a href="#追出身份從哪裡來" class="headerlink" title="追出身份從哪裡來"></a>追出身份從哪裡來</h3><p>請 AI 畫出身份從登入或訊息平台，一路傳到工具與資料庫的流程，並標出每個值由誰產生。</p><p>一張可用的圖大概會長這樣。</p><pre><code class="mermaid">flowchart LR    U[&quot;小明傳送訊息&quot;] --&gt; P[&quot;聊天平台&lt;br&#x2F;&gt;確認是小明&quot;]    P --&gt;|&quot;已驗證身份&quot;| B[&quot;bot 訊息入口&quot;]    B --&gt;|&quot;訊息內容&quot;| A[&quot;AI&lt;br&#x2F;&gt;理解想做什麼&quot;]    B --&gt; C[&quot;伺服器端上下文&lt;br&#x2F;&gt;保存小明的身份&quot;]    A --&gt;|&quot;想讀哪則記憶&quot;| T[&quot;記憶工具&quot;]    C --&gt;|&quot;小明的身份&quot;| T    T --&gt; D[&quot;只查小明的資料&quot;]</code></pre><p>這張圖有兩條路。AI 提供「想做什麼」，伺服器端上下文提供「現在是誰」，兩者最後在工具會合。</p><p>如果使用者身份改成從 AI 流向工具，就代表模型有機會替換身份。身份若來自使用者輸入、提示詞或 LLM 的工具參數，也不能直接拿來做授權。可信來源通常是通過驗證的登入狀態、平台訊息，或伺服器建立的請求上下文。</p><h3 id="假設模型能任意填寫工具參數"><a href="#假設模型能任意填寫工具參數" class="headerlink" title="假設模型能任意填寫工具參數"></a>假設模型能任意填寫工具參數</h3><p>可以直接把這段要求交給 AI。</p><blockquote><p>假設 LLM 可以任意填寫每個工具參數，找出它跨使用者讀取、修改或刪除資料的所有路徑。</p></blockquote><p>看到 <code>user_id</code>、<code>owner_id</code>、<code>tenant_id</code> 或 <code>requester_id</code> 出現在工具參數中，可以先追查這些值的來源。欄位名稱本身不代表一定有漏洞，重點是模型能否利用它改變自己的權限。</p><h3 id="同時測兩名使用者，檢查身份是否混用"><a href="#同時測兩名使用者，檢查身份是否混用" class="headerlink" title="同時測兩名使用者，檢查身份是否混用"></a>同時測兩名使用者，檢查身份是否混用</h3><p>許多 AI 產生的範例只測試一名使用者，因此看不出身份混用。請 AI 同時模擬 A 與 B，檢查對話、暫存狀態、工作目錄與請求上下文是否互相影響。</p><p>如果實作會修改一個全域的目前使用者，兩個並行請求就可能互相覆寫身份。</p><h2 id="系統要在入口確認身份，再一路帶到資料查詢"><a href="#系統要在入口確認身份，再一路帶到資料查詢" class="headerlink" title="系統要在入口確認身份，再一路帶到資料查詢"></a>系統要在入口確認身份，再一路帶到資料查詢</h2><p>上面的圖把身份與操作分成兩條路。要讓身份這條路可信，訊息入口還得先驗證來源。</p><p>網站要先驗證登入 session 或 token，聊天平台的 webhook 也要先驗證簽章。完成驗證後，訊息入口才把身份綁進伺服器端上下文或專屬執行環境。</p><p>工具從這個位置取得身份。LLM 可以選擇操作與資源，例如「讀取這則記憶」，但工具仍會用通過驗證的身份限制資料範圍。</p><h2 id="我的兩人版，另外守住執行環境、工具與資料"><a href="#我的兩人版，另外守住執行環境、工具與資料" class="headerlink" title="我的兩人版，另外守住執行環境、工具與資料"></a>我的兩人版，另外守住執行環境、工具與資料</h2><p>我的 bot 讓每位使用者各自使用一個長駐 Claude CLI process。訊息入口驗證使用者後，會從伺服器端保存的對應關係找到該使用者的 process。</p><figure class="highlight python"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">proc = <span class="keyword">await</span> asyncio.create_subprocess_exec(</span><br><span class="line">    <span class="string">&quot;claude&quot;</span>, <span class="string">&quot;-p&quot;</span>, <span class="string">&quot;--input-format&quot;</span>, <span class="string">&quot;stream-json&quot;</span>,</span><br><span class="line">    cwd=<span class="string">f&quot;state/private/<span class="subst">&#123;user_id&#125;</span>/&quot;</span>,</span><br><span class="line">    env=&#123;**os.environ, <span class="string">&quot;DYAD_USER_ID&quot;</span>: user_id&#125;,</span><br><span class="line">)</span><br></pre></td></tr></table></figure><p>每個 process 啟動時只收到自己的 <code>DYAD_USER_ID</code>。環境變數不是使用者清單，只表示這個 process 從啟動到結束代表誰。</p><p>身份的可信度也不是來自環境變數本身。訊息入口已驗證使用者，再由伺服器啟動對應的 process 並注入身份，這條路徑才是信任來源。</p><h3 id="每人一個-process，不代表檔案已經隔離"><a href="#每人一個-process，不代表檔案已經隔離" class="headerlink" title="每人一個 process，不代表檔案已經隔離"></a>每人一個 process，不代表檔案已經隔離</h3><p>每位使用者的對話、上下文與 process 生命週期各自分開。小明的訊息只會送進自己的 process。使用者登出或權限被撤銷時，舊 process 也要停止或重建。</p><p><code>cwd</code> 讓相對路徑預設落在使用者自己的資料夾，但它不是檔案沙盒。只要 process 有任意讀檔能力，<code>../B/memory.md</code> 或完整的絕對路徑仍能離開目前目錄。</p><h3 id="關掉通用工具，只留下受限功能"><a href="#關掉通用工具，只留下受限功能" class="headerlink" title="關掉通用工具，只留下受限功能"></a>關掉通用工具，只留下受限功能</h3><p>Claude CLI 原本帶有 Read、Write、Bash 等內建工具。全部保留時，模型仍能繞過記憶工具，直接讀取其他路徑。</p><p>我的 bot 會關掉內建工具，只允許自己設計的 MCP 工具。</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br></pre></td><td class="code"><pre><span class="line">claude -p --tools <span class="string">&quot;&quot;</span> \</span><br><span class="line">       --mcp-config mcp.json \</span><br><span class="line">       --strict-mcp-config</span><br></pre></td></tr></table></figure><p>模型只會看到 <code>list_memory</code>、<code>propose_memory</code>、<code>delete_memory</code> 等有限功能。它沒有一般讀檔工具，也沒有命令列可以探索其他目錄。</p><p>這層的代價是，每增加一項能力，都要另外設計範圍有限的工具。自訂工具本身也要限制路徑與資料範圍，不能換個名字重新提供任意讀檔能力。</p><h3 id="工具使用系統注入的身份查資料"><a href="#工具使用系統注入的身份查資料" class="headerlink" title="工具使用系統注入的身份查資料"></a>工具使用系統注入的身份查資料</h3><p>我把身份從工具參數移除。Claude CLI 啟動 MCP 伺服器時，伺服器會繼承 process 的環境變數。</p><figure class="highlight python"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br></pre></td><td class="code"><pre><span class="line">USER_ID = os.environ[<span class="string">&quot;DYAD_USER_ID&quot;</span>]</span><br><span class="line"></span><br><span class="line"><span class="meta">@app.tool()</span></span><br><span class="line"><span class="keyword">def</span> <span class="title function_">read_memory</span>(<span class="params">memory_id: <span class="built_in">str</span></span>) -&gt; <span class="built_in">str</span>:</span><br><span class="line">    <span class="keyword">return</span> store.get(user_id=USER_ID, memory_id=memory_id)</span><br></pre></td></tr></table></figure><p>LLM 只提供 <code>memory_id</code>，工具自行把 <code>USER_ID</code> 加進資料查詢。即使模型知道小美的識別碼，工具定義裡也沒有位置讓它替換目前身份。</p><p>四道邊界處理的範圍不同。</p><table><thead><tr><th>邊界</th><th>負責處理</th><th>單獨使用仍缺少</th></tr></thead><tbody><tr><td>訊息入口</td><td>驗證訊息來自哪位使用者</td><td>不會自動限制工具與資料</td></tr><tr><td>process</td><td>分開對話、上下文與生命週期</td><td><code>cwd</code> 擋不住任意路徑</td></tr><tr><td>工具白名單</td><td>限制模型可以使用的能力</td><td>自訂工具仍可能寫錯權限</td></tr><tr><td>資料查詢</td><td>依可信身份限制實際資料</td><td>上游必須先正確驗證身份</td></tr></tbody></table><h2 id="服務更多使用者時，身份要跟著執行環境或請求走"><a href="#服務更多使用者時，身份要跟著執行環境或請求走" class="headerlink" title="服務更多使用者時，身份要跟著執行環境或請求走"></a>服務更多使用者時，身份要跟著執行環境或請求走</h2><p>環境變數可以用在更多使用者，前提是一個 process 或容器從頭到尾只代表一位使用者。每建立一個執行環境，系統只注入它代表的單一身份，不需要把所有使用者寫進環境變數。</p><p>使用者變多後，可以選擇不同的執行方式。</p><table><thead><tr><th>執行方式</th><th>身份放在哪裡</th><th>適合的情況</th></tr></thead><tbody><tr><td>每人一個 process 或容器</td><td>啟動時由伺服器注入</td><td>使用者不多，或需要較強的執行隔離</td></tr><tr><td>多人共用 worker</td><td>每次請求專用的伺服器端上下文</td><td>使用者多，需要共用運算資源</td></tr></tbody></table><p>共用 worker 不能靠修改全域 <code>CURRENT_USER</code> 切換身份。小明與小美的請求同時執行時，後寫入的值可能覆蓋前一個。</p><p>身份要跟著個別請求或非同步任務傳遞。如果 agent runner 與工具伺服器分開部署，這份身份還要透過已驗證的內部連線傳遞，或綁定到伺服器管理的連線與 session。把 <code>user_id</code> 放回模型產生的 JSON，無法取代這段可信傳遞。</p><p>公開的多租戶服務還需要正式的登入驗證、授權與租戶資料隔離。資料風險較高時，可以把高風險工具放進短命容器，或使用獨立的作業系統帳號。</p><h2 id="Hermes-分開對話，不等於分開資料權限"><a href="#Hermes-分開對話，不等於分開資料權限" class="headerlink" title="Hermes 分開對話，不等於分開資料權限"></a>Hermes 分開對話，不等於分開資料權限</h2><p>Hermes Agent 的 <a href="https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/sessions.md">Sessions 文件</a>也把使用者資訊放在模型外面。它的 gateway 會根據平台訊息中的聊天室、使用者與討論串等資料建立 session key，再把訊息送進對應的對話紀錄。</p><p>私訊會依聊天室分開。平台能提供使用者識別碼時，一般群組會把使用者放進 session key。群組討論串預設讓參與者共用對話，需要逐人分開時，可以開啟 <code>thread_sessions_per_user</code>。</p><p>這個設計處理「訊息應該進入哪段對話」，不會自動限制檔案或工具權限。即使小明與小美使用不同 session，兩邊仍可能呼叫接受任意 <code>user_id</code> 的工具。</p><p>Hermes 可以作為身份路由的參考，資料授權仍要由工具與儲存層處理。</p><h2 id="最後檢查模型能否控制身份或繞過工具"><a href="#最後檢查模型能否控制身份或繞過工具" class="headerlink" title="最後檢查模型能否控制身份或繞過工具"></a>最後檢查模型能否控制身份或繞過工具</h2><p>如果 AI bot 會服務多名使用者，可以搜尋工具定義中的 <code>user_id</code>、<code>owner_id</code>、<code>tenant_id</code> 與 <code>requester_id</code>。</p><p>這些欄位出現在參數中不一定有錯。資源或工作區識別碼可以由模型選擇，伺服器仍要用可信身份檢查目前使用者是否有權操作。真正危險的是，工具直接把模型提供的值當成已通過認證的身份。</p><p>也要檢查模型是否擁有旁路能力。Read、Write、Bash、瀏覽器、資料庫查詢與自訂 MCP 工具，都可能繞過原本設計的記憶 API。</p><p>我的第一版沒有漏寫那個 <code>if</code>。我把模型產生的 <code>requester_id</code> 當成通過驗證的身份，才讓檢查看似存在，實際上仍由模型控制。</p><p>兩人版可以把身份固定在專屬 process，多人共用的服務可以放進每次請求專用的伺服器端上下文。實作方式會隨規模改變，模型只負責選擇操作與資源，系統負責決定它目前代表誰，以及可以操作哪些資料。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/markdown-ai-memory/">AI agent 的記憶該放哪裡？從 Markdown、SQLite 到 LLM Wiki</a></li><li><a href="/background-ai-agent-tasks/">哪些工作該交給背景 AI agent？</a></li><li><a href="/when-multi-agent-works/">一個 AI agent 做不好，多開幾個就會比較好嗎？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/llm-agent-isolation/</id>
    <link href="https://calmkoala.github.io/llm-agent-isolation/"/>
    <published>2026-07-25T00:00:00.000Z</published>
    <summary>多人共用 AI bot 時，認錯人可能讀出別人的私人資料。從一個兩人 bot 的實作，說明身份應該從哪裡來，以及如何檢查 AI 產生的設計。</summary>
    <title>多人共用 AI bot，別讓它認錯使用者</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="AI" scheme="https://calmkoala.github.io/categories/study-notes/AI/"/>
    <category term="AI" scheme="https://calmkoala.github.io/tags/AI/"/>
    <content>
      <![CDATA[<p>現在使用市面上的 AI agent framework，安裝完後遇到的第一個設定，通常就是選擇模型供應商，再填入一組 API key。</p><p>這個設計很合理，框架總得知道要去哪裡找模型。但我卡在一個很現實的地方，我本來就在付 Claude 和 ChatGPT 的訂閱費，平常使用 Claude Code 與 Codex CLI 也都包含在方案額度裡。</p><p>如果 agent 改走模型 API，等於又多開一條按 token 計費的路徑。技術上沒有問題，但我的錢很有問題啊啊啊。</p><p>既然 CLI 已經登入，也支援非互動執行，能不能讓自己的 program 直接呼叫它？答案當然是可以，原本給人操作的 CLI，也能放到 agent 的模型層，成為一種 backend。</p><span id="more"></span><h2 id="把-API-client-換成一個-CLI-process"><a href="#把-API-client-換成一個-CLI-process" class="headerlink" title="把 API client 換成一個 CLI process"></a>把 API client 換成一個 CLI process</h2><p>一般的 agent 架構大概長這樣：</p><pre><code class="mermaid">flowchart LR  USER[使用者] --&gt; APP[Agent program]  APP --&gt; SDK[模型 SDK &#x2F; API client]  SDK --&gt; API[模型 API]</code></pre><p>改用 CLI 後，中間那層換成 OS 裡的一個 subprocess：</p><pre><code class="mermaid">flowchart LR  USER[使用者] --&gt; APP[Agent program]  APP --&gt;|啟動 process、傳入 prompt| CLI[Claude Code &#x2F; Codex CLI]  CLI --&gt;|JSON &#x2F; 串流事件| APP  CLI --&gt; MODEL[模型服務]</code></pre><p>Agent program 啟動 CLI，把 prompt 寫進 stdin，再從 stdout 讀回結構化事件。對 agent program 而言，這和呼叫 SDK 的角色很接近，只是邊界從 function call 變成 process communication。</p><p>模型服務背後當然還是存在。這裡省掉的是「自己的 program 直接整合供應商 API」那一層，並非讓模型離線執行。</p><h2 id="CLI-憑什麼能當-backend"><a href="#CLI-憑什麼能當-backend" class="headerlink" title="CLI 憑什麼能當 backend"></a>CLI 憑什麼能當 backend</h2><p>CLI 平常看起來是人坐在終端機前使用的介面，但 Claude Code 與 Codex 都提供非互動模式，也能輸出 JSON Lines 等結構化格式。</p><p>Claude Code 可以用 <code>-p</code> 接收非互動輸入，搭配 <code>stream-json</code> 持續讀寫事件；Codex 則提供 <code>codex exec --json</code>，執行完一個任務後把過程以 JSON Lines 輸出。</p><p>這代表 agent 不必模擬鍵盤輸入，也不用從終端機畫面硬拆文字。只要替不同 CLI 做一層 adapter，就能把輸入與輸出轉成自己系統內統一的格式。</p><p>更有意思的是，CLI 已經包好不少 API client 原本要自己處理的東西，包括帳號登入、模型選擇、工具設定與本機權限。Agent program 可以專心處理自己的路由、排程和狀態。</p><p>Claude 已有 Telegram marketplace plugin，Codex app 也有 Remote，兩者都能讓使用者從手機繼續工作。<a href="https://github.com/anthropics/claude-plugins-official/blob/main/external_plugins/telegram/README.md">claude-plugins-official&#x2F;external_plugins&#x2F;telegram&#x2F;README.md at main · anthropics&#x2F;claude-plugins-official · GitHub</a>、<a href="https://learn.chatgpt.com/docs/remote-connections">Remote connections - OpenAI</a></p><div class="note info no-icon"><p>這些遠端功能解決的是「人如何從手機操作產品」。這篇談的是讓自己的 program 把 CLI 當成模型後端。若你只想遠端繼續對話，直接使用現成功能會簡單很多。</p></div><h2 id="真正麻煩的是-process-lifecycle"><a href="#真正麻煩的是-process-lifecycle" class="headerlink" title="真正麻煩的是 process lifecycle"></a>真正麻煩的是 process lifecycle</h2><p>把 CLI 包進 subprocess 只能算第一步。它開始長時間執行後，就會出現一批 API SDK 不太像的問題。</p><p>CLI process 可能卡住、意外結束，或碰到 rate limit。兩個請求也不能同時往同一條 input stream 裡寫，不然回傳事件會混在一起。Agent 得自己處理 timeout、序列化、重啟與錯誤復原。</p><p>對話狀態也要納入 backend contract。Claude 回傳 session ID 後，可以透過 <code>claude --resume &lt;session-id&gt;</code> 接回先前的 session；Codex 的非互動模式也提供 <code>codex exec resume</code>。兩邊都有續接能力，命令格式與生命週期卻不相同。<a href="https://docs.anthropic.com/en/docs/claude-code/cli-usage">CLI reference - Anthropic</a>、<a href="https://learn.chatgpt.com/docs/non-interactive-mode">Non-interactive mode - OpenAI</a></p><p>所以 adapter 除了傳 prompt、收答案，還得管理 CLI process。它要決定 process 什麼時候啟動或關閉；同時收到多個 request 時，先排好順序；也要保存 session ID，讓 process 掛掉或重啟後能接回原本的對話。這些行為都得寫在 adapter 裡，模型不會幫你處理。</p><h2 id="訂閱帳號也能沿用"><a href="#訂閱帳號也能沿用" class="headerlink" title="訂閱帳號也能沿用"></a>訂閱帳號也能沿用</h2><p>我會走這條路，還有一個很現實的原因。我本來就在付 Claude 與 ChatGPT 的訂閱費。</p><p>Claude Code 和 Codex CLI 都能使用訂閱帳號登入。只要使用量還在方案額度內，透過 CLI 執行的任務就不會另外產生一張 API key 的按量帳單。Codex 官方文件也把 ChatGPT 登入與 API key 列為不同的驗證和計費方式。<a href="https://learn.chatgpt.com/docs/auth">Authentication - OpenAI</a>、<a href="https://learn.chatgpt.com/docs/pricing">Pricing - OpenAI</a></p><p>這不等於免費。訂閱本身要付費，也有 rate limit 與使用上限；CLI 背後照樣會連到模型服務。比較準確的說法是，我沿用訂閱方案內含的使用額度，沒有讓自己的 agent 另外走 API key 計費。</p><h2 id="什麼時候不該這樣做"><a href="#什麼時候不該這樣做" class="headerlink" title="什麼時候不該這樣做"></a>什麼時候不該這樣做</h2><p>CLI backend 很適合本機、單人，而且本來就在使用訂閱版 CLI 的情境。離開這個範圍，代價會逐漸浮現。</p><p>CLI 版本更新可能改變事件格式，登入狀態也不適合複製到大量伺服器。正式服務需要多人共用、成本歸戶、穩定併發或 CI 自動化時，直接使用 API 通常比較容易管理。</p><p>它也會讓 agent 多出 process management 的責任。如果你的 program 只是偶爾呼叫一次模型，為了省一層 API client 卻加上 supervisor、timeout 和 session recovery，可能反而繞了遠路。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/background-ai-agent-tasks/">哪些工作該交給背景 AI agent？</a></li><li><a href="/when-multi-agent-works/">一個 AI agent 做不好，多開幾個就會比較好嗎？</a></li><li><a href="/ai-agent-skills-more-is-better/">Skill 裝得越多，AI agent 就越好用嗎？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/subscription-cli-always-on-agent/</id>
    <link href="https://calmkoala.github.io/subscription-cli-always-on-agent/"/>
    <published>2026-07-19T00:00:00.000Z</published>
    <summary>
      <![CDATA[<p>現在使用市面上的 AI agent framework，安裝完後遇到的第一個設定，通常就是選擇模型供應商，再填入一組 API key。</p>
<p>這個設計很合理，框架總得知道要去哪裡找模型。但我卡在一個很現實的地方，我本來就在付 Claude 和 ChatGPT 的訂閱費，平常使用 Claude Code 與 Codex CLI 也都包含在方案額度裡。</p>
<p>如果 agent 改走模型 API，等於又多開一條按 token 計費的路徑。技術上沒有問題，但我的錢很有問題啊啊啊。</p>
<p>既然 CLI 已經登入，也支援非互動執行，能不能讓自己的 program 直接呼叫它？答案當然是可以，原本給人操作的 CLI，也能放到 agent 的模型層，成為一種 backend。</p>]]>
    </summary>
    <title>CLI 也能當 AI agent 的後端</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="系統設計" scheme="https://calmkoala.github.io/categories/study-notes/%E7%B3%BB%E7%B5%B1%E8%A8%AD%E8%A8%88/"/>
    <category term="自動化" scheme="https://calmkoala.github.io/tags/%E8%87%AA%E5%8B%95%E5%8C%96/"/>
    <category term="SRE" scheme="https://calmkoala.github.io/tags/SRE/"/>
    <category term="系統設計" scheme="https://calmkoala.github.io/tags/%E7%B3%BB%E7%B5%B1%E8%A8%AD%E8%A8%88/"/>
    <content>
      <![CDATA[<p>我有一個常駐的 AI 助理 bot，平常會主動推播提醒、報告工作進度，<del>偶爾覺得它有點吵</del>。某天下午我要重啟它裝新功能，才發現它消失了一陣子。log 最後一行停在前一天早上十點多，沒報錯，也沒留下半點線索，就這樣安靜地不見了 16 個小時。事後推測應該是機器重開的時候沒有一起把服務重啟。</p><p>這讓我開始思考一個問題：要是哪天換別的原因害它死掉，我會不會一樣過了半天才發現？畢竟我平常只有在它跳出訊息的時候去確認，它沒跳訊息的時候我不會特別去看它，所以很難發現它掛了。</p><p>我養這個 bot，本來就是想少花點精力在日常瑣事上。要是反過來得每天盯它有沒有在做事，那反而本末倒置。所以我幫它補了一套三層防線，還在查資料時撞到一件好笑的事。</p><span id="more"></span><div class="note info no-icon"><p><strong>快速摘要</strong>：這次遇到的長駐服務失效，我先分成三種，再用三層防線去接：自動重啟、站在主機外面的心跳監控、開機自啟。背後一句話是「監測的機制不能跟被監測的東西一起死」。後來查了業界做法，發現這些問題早就在 SRE 的範圍裡，附名詞和現成工具。</p><p>如果只是單機要顧一個服務，Linux 用 systemd，Windows 註冊成 Windows Service，再配一個 Healthchecks.io，三層就到齊了。</p></div><h1 id="先分清楚，它會怎麼死"><a href="#先分清楚，它會怎麼死" class="headerlink" title="先分清楚，它會怎麼死"></a>先分清楚，它會怎麼死</h1><p>服務掛掉分好幾種。這次我先把常見的失效方式分成三類，麻煩程度差很多，差在「它死得有多安靜」：</p><ul><li>大喊一聲才死：程式噴錯退出，留了一整串 stack trace。這種至少最好追，因為它通常會留下線索，讓我們知道該從哪裡開始查。</li><li>沒斷氣、卻不做事：這就是占著茅坑不拉屎，它還在工作崗位上領它的薪水但沒有幫我做事，process 還在，功能卻停了。我之前寫過<a href="/apscheduler-windows-misfire/">排程默默不執行</a>就是這種，你去看它一切正常，就是該動的時候沒動。</li><li>無聲無息消失：機器重開、記憶體被系統收走、被誰誤殺。應用程式自己的 log 可能連一行都來不及留，線索散落在系統事件或核心紀錄裡。</li></ul><p>越是「設好就不用管」的長駐服務，越容易死在後面兩種。你不會每天盯著它，它也沒有力氣喊救命。</p><h1 id="看門的人，不能睡在屋裡"><a href="#看門的人，不能睡在屋裡" class="headerlink" title="看門的人，不能睡在屋裡"></a>看門的人，不能睡在屋裡</h1><p>先講一個你家就有的東西：煙霧偵測器。</p><p>它為什麼裝在天花板、還自己帶一顆電池？因為如果它只靠家裡的電路，哪天電線走火、跳電了，它剛好跟著斷電，火最大的那一刻它已經睡死了。它至少要有獨立的備援電源，不能在房子跳電時跟著完全失效。</p><p>長駐服務的守護也是同一句話：監測一個東西的機制，不能跟那個東西一起死。管理員可以跟服務住在同一台機器，但外部心跳監控得站到主機外面；開機自啟則交給作業系統。三層不是整齊的一圈包一圈，比較像一條恢復鏈，再加上一條獨立的報警線：</p><pre><code class="mermaid">flowchart LR  OS[第三層：作業系統開機自啟] --&gt; SUP[第一層：服務管理員]  SUP --&gt;|啟動與監督| SVC([長駐服務])  SUP -.異常退出後重啟.-&gt; SVC  SVC --&gt;|完成工作後定時打卡| HC[第二層：外部心跳監控]  HC --&gt;|逾時告警| YOU([你的手機])</code></pre><h1 id="第一層-管理員：倒了就扶它起來"><a href="#第一層-管理員：倒了就扶它起來" class="headerlink" title="第一層 管理員：倒了就扶它起來"></a>第一層 管理員：倒了就扶它起來</h1><p>先接最單純的死法，自己把遺書寫好的死法。</p><p>這邊的處理方法很簡單，就是不要讓服務「自己跑」，我們在它旁邊派一個管理員，服務一倒就把它扶起來。</p><p>但這個管理員不是隨便找一個就可以，它必須具備兩個技能。</p><p>一是分辨「它是自己想重開」還是「它壞了」，這兩種的待遇不一樣。二是壞掉的時候不能秒扶秒倒。想像你去扶一個站不穩的醉漢，扶起來他又倒、你再扶他又倒，你會被拖著一起累死；服務壞了如果每秒重生一次，CPU、log 和外部依賴都可能先被它打爆。正確做法是加入重啟間隔和頻率限制，必要時再讓等待時間逐步增加，至少不能讓它無限高速重生。</p><p>要做到第一件事，服務跟管理員之間得先講好一套暗號，區分「我要重開」「我壞了」「我正常收工、別扶我」。有了暗號，連「重啟」都變安全：服務好好收工、丟一個「我要重開」的信號、管理員拉新的起來。</p><h1 id="第二層-哨兵：站在門外敲門"><a href="#第二層-哨兵：站在門外敲門" class="headerlink" title="第二層 哨兵：站在門外敲門"></a>第二層 哨兵：站在門外敲門</h1><p>第二種死法最陰險，沒斷氣、卻不做事，這種管理員接不住，得靠站得更外面的哨兵。</p><p>你可能會問，既然管理員會自動把服務重啟，還要哨兵幹嘛？因為管理員站在服務旁邊，服務摔倒它看得到，但有兩個情況它沒辦法處理：它自己睡著了沒人管，還有服務「人在、心不在」的時候。後面這種 process 活得好好的，功能其實早就停了，管理員在旁邊只覺得一切正常。</p><p>哨兵有兩種站法。一種是它定時來敲門，主動問服務還好不好；另一種是要求服務定時去外面打卡，哪天該到卻沒到，外面的人就打電話通知我。對我這種單機服務，後者更直接：bot 每次真的完成工作後，就向外部監控送一次心跳。這個角色有兩個地方最容易做錯。</p><p>第一，報警要用一支跟這棟房子無關的電話。如果報警得透過房子裡的廣播系統，那房子燒了廣播也沒了。哨兵不能跟 bot 住在同一台機器上，通知我的那條路也不能經過 bot 本身。主機關機、系統卡死或服務壞掉時，外面的監控還是得有辦法直接通知手機。</p><p>第二，「你還在嗎」這句話問錯了。你打電話給值班的人問「你在不在」，他回「在」，但他可能人在、正在滑手機。真正該問的是「你手上那件事，上一次做完是多久以前？」他要是說三小時前，那就算接了電話，也是掛機狀態。只證明「有人接電話」不夠，得證明「有人在做事」。所以讓服務回報的別只是「我還活著」，要能回答「我上一次真的完成工作是什麼時候」，這樣才擋得住那種沒斷氣卻不做事的死法。</p><h1 id="第三層-開機自啟：停電後叫醒大家"><a href="#第三層-開機自啟：停電後叫醒大家" class="headerlink" title="第三層 開機自啟：停電後叫醒大家"></a>第三層 開機自啟：停電後叫醒大家</h1><p>最後一種死法最徹底，整台機器重開，把上面所有東西一起帶走。</p><p>問題是，服務和管理員本身也都是程式。機器一重開，它們會一起歸零。我那 16 小時就死在這，前面的監督邏輯根本都寫好了，機器半夜重開一次（尤其是 Windows Update），把它們一起帶走，然後沒有任何人負責把它們叫醒。外部心跳監控倒是還活著，只是當時的我根本還沒讓它盯這件事。</p><p>這一層只能交給作業系統本身，讓它在開機時自動把服務管理員拉起來。它是整串的地基，這層不做，上面寫得再漂亮，停電後也沒人開燈。</p><h1 id="誰來看守看守者？"><a href="#誰來看守看守者？" class="headerlink" title="誰來看守看守者？"></a>誰來看守看守者？</h1><p>聰明的你大概已經想到了，哨兵自己也是程式，它死了怎麼辦？</p><p>順著「監測者要在外面」這句話推下去，會掉進一個無底洞，哨兵要一個哨兵，那個哨兵又要一個哨兵。這個遞迴不能靠「寫一個笨到不會死的本機程式」停下來，因為它再笨，主機斷電時還是會一起消失。</p><p>比較實際的停法，是把最外圈交給另一個故障域裡的外部服務。它當然也可能壞，只是至少不會跟我的 bot 因為同一次重開機、同一顆硬碟或同一段程式一起消失。再往外疊看門狗的看門狗，只會蓋出一座無限高的塔（抖</p><h1 id="這整套早就有名字"><a href="#這整套早就有名字" class="headerlink" title="這整套早就有名字"></a>這整套早就有名字</h1><p>三層都寫好、服務乖乖活著之後，我順手查了「別人都怎麼防這種事」。結果發現，我自己摸索出的這套做法，正好落在 SRE（站點可靠性工程）關注的範圍裡：服務監督、健康檢查、外部告警，以及故障後自動恢復。Google 那本《Site Reliability Engineering》就是這個領域的經典教材。我那三層，每一層都有正式名字，每個念頭都有人做成現成工具。</p><p>那個「管理員」，業界叫 process supervisor。Linux 常見的 systemd 就能負責這件事，內建異常後重啟、重啟間隔和啟動頻率限制，正好能處理第一層的大部分需求。在 Kubernetes 裡，容器如果反覆啟動又崩潰，系統會逐步拉長重啟間隔，最後常會看到那個熟悉的狀態：<code>CrashLoopBackOff</code>。玩過 Kubernetes 的人大概都被它的紅字瞪過。</p><p>那個「哨兵敲門」，在容器平台裡常叫 health probe，而且分得比我細：liveness 管「我是不是卡死了，要不要重啟」，readiness 管「我現在能不能接工作，不能就先別把流量送過來」。我講的「不能只回一句我還在、要證明有在做事」，正是他們早就踩過的坑。至於我最後採用的外部打卡，則比較接近後面會提到的 heartbeat monitoring。</p><p>這裡還讓我補到一個原本會犯的錯：外部依賴可以檢查，但不要直接綁進 liveness 的重啟判斷。資料庫連不上時，服務可能應該暫停接收新工作、回報 degraded 或發出告警，卻不一定適合不斷重啟。不然資料庫一掛，服務被判死、重啟、資料庫還是沒好、又被判死，最後自己把自己踩進 crash loop。liveness 該確認的是「我自己的工作迴圈還有沒有在跳」，不是要求整個世界都得跟著健康。</p><p>「報警要走一支跟房子無關的電話」，其實是這裡面很常見的一招，叫 dead man’s switch，或叫心跳監控。現成服務一堆，像 Healthchecks.io、Dead Man’s Snitch。它們不是定時進來戳我的 bot，而是反過來要求 bot 主動去外面打卡，哪天該報平安卻沒出現，就直接通知我。連整台主機消失都能一起抓到。</p><p>連我那個「誰來看守看守者」的無限遞迴，業界也有類似做法。Prometheus／Alertmanager 的常見配置裡，會放一條永遠處於 firing 狀態的 <code>Watchdog</code> 警報，再交給外部的 dead man’s switch 盯著。哪天這條本來永遠會響的警報不響了，外部就知道整套監控自己可能死了。答案不是讓最外圈永遠不壞，而是別讓它和裡面那一圈一起壞。</p><p>殺雞不用牛刀，我平常寫的簡單服務在 Linux 用 systemd，Windows 註冊成 Windows Service，再配一個 Healthchecks.io，三層就到齊了。放大到公司才需要那整套，但骨架跟你在家土炮的一模一樣。</p><h1 id="最後"><a href="#最後" class="headerlink" title="最後"></a>最後</h1><p>這三層防的是「它死掉」，防不了「它做錯事」。服務要是活得好好的、health 也正常回報，卻把某筆資料算錯了，看門狗只會一路跟你說一切安好。「它還在做事」跟「它做對事」是兩回事，這套只保證前者。後者是另一個題目，得靠別的東西守，這篇罩不到。</p><hr><p>三層設完之後，服務一斷氣，一分鐘內我手機就會叮一聲。當初還嫌這 bot 有點吵，結果我又在旁邊多養了一隻，專門在它出事的時候吵我，家裡的叮咚聲大概只會更多，但至少不會再有下一個安靜消失的 16 小時了(?</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/telegram-message-formatting/">Telegram 訊息加了格式，怎麼就送不出去了？</a></li><li><a href="/markdown-ai-memory/">AI agent 的記憶該放哪裡？從 Markdown、SQLite 到 LLM Wiki</a></li><li><a href="/llm-agent-isolation/">多人共用 AI bot，別讓它認錯使用者</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/long-running-service-watchdog/</id>
    <link href="https://calmkoala.github.io/long-running-service-watchdog/"/>
    <published>2026-07-12T00:00:00.000Z</published>
    <summary>
      <![CDATA[<p>我有一個常駐的 AI 助理 bot，平常會主動推播提醒、報告工作進度，<del>偶爾覺得它有點吵</del>。某天下午我要重啟它裝新功能，才發現它消失了一陣子。log 最後一行停在前一天早上十點多，沒報錯，也沒留下半點線索，就這樣安靜地不見了 16 個小時。事後推測應該是機器重開的時候沒有一起把服務重啟。</p>
<p>這讓我開始思考一個問題：要是哪天換別的原因害它死掉，我會不會一樣過了半天才發現？畢竟我平常只有在它跳出訊息的時候去確認，它沒跳訊息的時候我不會特別去看它，所以很難發現它掛了。</p>
<p>我養這個 bot，本來就是想少花點精力在日常瑣事上。要是反過來得每天盯它有沒有在做事，那反而本末倒置。所以我幫它補了一套三層防線，還在查資料時撞到一件好笑的事。</p>]]>
    </summary>
    <title>一個人也需要 SRE</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="工具" scheme="https://calmkoala.github.io/categories/study-notes/%E5%B7%A5%E5%85%B7/"/>
    <category term="AI" scheme="https://calmkoala.github.io/tags/AI/"/>
    <category term="ffmpeg" scheme="https://calmkoala.github.io/tags/ffmpeg/"/>
    <category term="自動化" scheme="https://calmkoala.github.io/tags/%E8%87%AA%E5%8B%95%E5%8C%96/"/>
    <content>
      <![CDATA[<p>前陣子要整理某個 App 裡的一份清單，但這個 App 沒有匯出功能也沒有 API 可以用，唯一的辦法就是自己把畫面一直往下滑，再把幾百筆內容手動抄出來，懶人如我，當然不可能真的一筆一筆抄，看來這裡又是 AI 該發揮作用的地方了。</p><p>最後我的作法是把清單從頭到尾螢幕錄影錄起來，再用 ffmpeg 抽出少量影格並輸出成圖片，交給有視覺能力的 AI 逐張辨識。兩段影片一共輸出 105 張圖片，最後整理出 108 筆資料。</p><p>這個做法的重點不是「讓 AI 看影片」，而是把一個太大、太密集的輸入，拆成可控制、可檢查的小單位。</p><p><img src="/images/ffmpeg-frames-pipeline.png" alt="整條流程：錄影 → 抽影格 → AI 逐張讀 → 去重"></p><span id="more"></span><h1 id="為什麼不直接把整段影片交給-AI"><a href="#為什麼不直接把整段影片交給-AI" class="headerlink" title="為什麼不直接把整段影片交給 AI"></a>為什麼不直接把整段影片交給 AI</h1><p>其實直接處理影片也不是完全不可行，但不適合這次的情境。</p><p>先碰到的問題是檔案大小。第一段錄影超過 100 MB，已經超過當時傳輸管道的檔案限制，只能改從本機檔案處理。</p><p>再來是影片裡有大量的重複影格。原始錄影是 60 fps，代表影片每秒記錄 60 個影格；但清單滑動得很慢，相鄰影格的內容幾乎一樣。全部交給 AI 辨識只會增加重複資料，白白占掉 context，也增加處理成本。</p><p>用 ffmpeg 從影片取樣後，每個取樣到的影格會輸出成一張圖片。某張圖片辨識錯誤時，只要重新處理那張；取樣頻率不合適，也可以直接從原始影片重新抽取。</p><h1 id="用-ffmpeg-抽出需要的影格"><a href="#用-ffmpeg-抽出需要的影格" class="headerlink" title="用 ffmpeg 抽出需要的影格"></a>用 ffmpeg 抽出需要的影格</h1><p>ffmpeg 是一套處理影音的命令列工具，常用來轉檔、剪輯與壓縮。這次只需要一行指令：</p><figure class="highlight bash"><table><tr><td class="gutter"><pre><span class="line">1</span><br></pre></td><td class="code"><pre><span class="line">ffmpeg -i recording.mp4 -vf fps=1 frame_%04d.png</span><br></pre></td></tr></table></figure><p>這行會讀取 <code>recording.mp4</code>，每秒取樣一個影格，再輸出成 <code>frame_0001.png</code>、<code>frame_0002.png</code> 這類依序編號的圖片。</p><p><code>fps=1</code> 不是每次的固定答案，還是要看錄影時滑動的速度。如果滑得很快，一秒一張可能會漏掉剛好從兩次取樣之間經過的資料，那就調成 <code>fps=2</code> 或 <code>fps=3</code>；滑得慢就不用特別調高，不然只會多切出一堆相似圖片，後面還要花時間辨識和去重。</p><p>這次第一段影片約 63 秒，輸出 63 張圖片；第二段輸出 42 張。用 105 張圖片取代原始影片裡的數千個影格，後面的處理範圍就清楚很多。</p><p>這裡跟我在 <a href="/script-first/">〈重複的事，別每次都讓 AI 重做一遍〉</a> 提過的想法很像。能用固定規則處理的抽影格先交給 ffmpeg，真正需要看懂圖片內容的部分，再交給 AI。</p><h1 id="讓-AI-讀圖前，先固定輸出欄位"><a href="#讓-AI-讀圖前，先固定輸出欄位" class="headerlink" title="讓 AI 讀圖前，先固定輸出欄位"></a>讓 AI 讀圖前，先固定輸出欄位</h1><p>接著把輸出的圖片逐張交給有視覺能力的 AI，要求它只讀出需要的欄位，並使用固定格式輸出。</p><p>如果每張圖片都讓 AI 自由描述，最後會得到一批格式不同的文字，很難合併，然後又要靠 AI 去整理每張圖片的描述，除了增加成本也容易讓最終結果歪掉。所以我們可以先把輸出欄位固定，像是日期、標題、項目與識別條件，後續才能整理成 CSV 或試算表，再做過濾與去重。</p><p>逐張處理還有一個好處，圖片裡的文字被截斷或看不清楚時，可以把該筆標成低信心，留到最後人工確認。辨識結果不是一次產出就直接採用，而是保留回頭校對的入口。</p><h1 id="真正的坑是重複"><a href="#真正的坑是重複" class="headerlink" title="真正的坑是重複"></a>真正的坑是重複</h1><p>滑動式錄影一定會讓相鄰圖片包含重疊內容。同一筆資料可能出現在連續兩三張圖片裡，如果把每次辨識結果都當成新資料，最後的筆數就會被灌水。</p><p>所以 AI 讀完圖之後，還不能直接當成最終結果。要先用幾個相對穩定的欄位組成識別條件，例如日期加標題，再合併重複項目。如果遇到文字略有差異的結果，要回到原圖確認，不能只靠完全相同的字串去重。</p><p><img src="/images/ffmpeg-frames-dedup.png" alt="相鄰圖片內容重疊：同一筆資料出現在好幾張裡，挑 key 去重"></p><h1 id="這個方法適合什麼情境"><a href="#這個方法適合什麼情境" class="headerlink" title="這個方法適合什麼情境"></a>這個方法適合什麼情境</h1><p>這套流程適合結構固定、文字清楚、可以慢慢捲動的清單頁面。前提是需要的欄位確實有出現在畫面上，視覺辨識只能讀取現有內容。它比較像一次性的資料救援，用少量人工校對，換掉幾百筆手抄工作。</p><p>如果同一份資料會反覆處理，應該優先找正式匯出、API 或穩定的網頁資料來源。若畫面變化很快、文字模糊，或結果要求完全正確，單靠抽影格與視覺辨識也不夠。</p><p>整個流程其實就是把影片先抽成圖片，讓 AI 讀出固定欄位，最後再把重複資料合併。拆開之後，哪一步出錯就回頭檢查哪一步，至少比把整段影片丟進去再等一個結果好處理。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/telegram-message-formatting/">Telegram 訊息加了格式，怎麼就送不出去了？</a></li><li><a href="/background-ai-agent-tasks/">哪些工作該交給背景 AI agent？</a></li><li><a href="/when-multi-agent-works/">一個 AI agent 做不好，多開幾個就會比較好嗎？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/ffmpeg-frames-to-data/</id>
    <link href="https://calmkoala.github.io/ffmpeg-frames-to-data/"/>
    <published>2026-07-05T00:00:00.000Z</published>
    <summary>
      <![CDATA[<p>前陣子要整理某個 App 裡的一份清單，但這個 App 沒有匯出功能也沒有 API 可以用，唯一的辦法就是自己把畫面一直往下滑，再把幾百筆內容手動抄出來，懶人如我，當然不可能真的一筆一筆抄，看來這裡又是 AI 該發揮作用的地方了。</p>
<p>最後我的作法是把清單從頭到尾螢幕錄影錄起來，再用 ffmpeg 抽出少量影格並輸出成圖片，交給有視覺能力的 AI 逐張辨識。兩段影片一共輸出 105 張圖片，最後整理出 108 筆資料。</p>
<p>這個做法的重點不是「讓 AI 看影片」，而是把一個太大、太密集的輸入，拆成可控制、可檢查的小單位。</p>
<p><img src="/images/ffmpeg-frames-pipeline.png" alt="整條流程：錄影 → 抽影格 → AI 逐張讀 → 去重"></p>]]>
    </summary>
    <title>把螢幕錄影裡的資料抓出來——ffmpeg 抽影格 + 視覺辨識</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="Python" scheme="https://calmkoala.github.io/categories/study-notes/Python/"/>
    <category term="AI" scheme="https://calmkoala.github.io/tags/AI/"/>
    <category term="Python" scheme="https://calmkoala.github.io/tags/Python/"/>
    <category term="Windows" scheme="https://calmkoala.github.io/tags/Windows/"/>
    <content>
      <![CDATA[<p>最近做的東西常常要用程式開 subprocess 去呼叫 LLM。如果讓 LLM 直接寫檔，或輸出都是英文，都不會有問題；但只要 LLM 回傳中文，而且程式需要拿這段回傳結果接著處理，就會撞到 <code>UnicodeDecodeError</code>。</p><span id="more"></span><h1 id="為什麼會遇到問題"><a href="#為什麼會遇到問題" class="headerlink" title="為什麼會遇到問題"></a>為什麼會遇到問題</h1><p>Python 的 subprocess 在文字模式下抓輸出，會拿「系統的預設編碼」去解，而這個預設每個系統不一樣，一般 Mac、Linux 是 UTF-8，但繁體中文的 Windows 是 cp950。</p><p>LLM 回的中文是 UTF-8，Windows 拿 cp950 去解碼就會撞到對不上的 byte，直接爆炸。</p><p>那叫 AI 改回英文不就好了？但我要的就是那段中文啊，它最後還是得從同一條管子回來，問題是 Windows 怎麼解碼，跟 AI 講哪國話無關。真為了閃這個改成全英文，等於把想要的東西也一起丟了，本末倒置。</p><h1 id="解法：別讓-Python-自己猜"><a href="#解法：別讓-Python-自己猜" class="headerlink" title="解法：別讓 Python 自己猜"></a>解法：別讓 Python 自己猜</h1><p>知道問題是什麼就好解決了，直接指定編碼就好</p><figure class="highlight python"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br></pre></td><td class="code"><pre><span class="line">result = subprocess.run(</span><br><span class="line">    cmd,</span><br><span class="line">    capture_output=<span class="literal">True</span>,</span><br><span class="line">    text=<span class="literal">True</span>,</span><br><span class="line">    encoding=<span class="string">&quot;utf-8&quot;</span>,   <span class="comment"># 明講用 UTF-8，不看系統臉色</span></span><br><span class="line">    errors=<span class="string">&quot;replace&quot;</span>,   <span class="comment"># 真的有解不開的，用替代字元頂著，別整個炸掉</span></span><br><span class="line">)</span><br></pre></td></tr></table></figure><p>如果整個專案都在 Windows 中文環境跑，也可以更上游一點，設個環境變數 <code>PYTHONUTF8=1</code>，讓 Python 全程吃 UTF-8。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/apscheduler-windows-misfire/">排程每天默默不執行，又不報錯——APScheduler 在 Windows 的 misfire 坑</a></li><li><a href="/background-ai-agent-tasks/">哪些工作該交給背景 AI agent？</a></li><li><a href="/when-multi-agent-works/">一個 AI agent 做不好，多開幾個就會比較好嗎？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/subprocess-cp950/</id>
    <link href="https://calmkoala.github.io/subprocess-cp950/"/>
    <published>2026-06-28T00:00:00.000Z</published>
    <summary>
      <![CDATA[<p>最近做的東西常常要用程式開 subprocess 去呼叫 LLM。如果讓 LLM 直接寫檔，或輸出都是英文，都不會有問題；但只要 LLM 回傳中文，而且程式需要拿這段回傳結果接著處理，就會撞到 <code>UnicodeDecodeError</code>。</p>]]>
    </summary>
    <title>subprocess 在 Windows 的 cp950 編碼坑</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="Python" scheme="https://calmkoala.github.io/categories/study-notes/Python/"/>
    <category term="Python" scheme="https://calmkoala.github.io/tags/Python/"/>
    <category term="APScheduler" scheme="https://calmkoala.github.io/tags/APScheduler/"/>
    <category term="Windows" scheme="https://calmkoala.github.io/tags/Windows/"/>
    <content>
      <![CDATA[<p>最近有很多需要定期執行的項目，用 APScheduler 排好時間後，想說設定完就不用再管它。結果某天發現它沒正常運作，連續好幾天都沒動靜，但程式看起來一切正常，也沒噴任何錯誤，第一直覺就是自己程式一定寫錯了(抖</p><p>通常程式掛掉，至少會留個 stack trace 給你查；但這次它根本不報錯。程式還活著、排程也還在，log 翻過去一條紅字都沒有，就是該跑的時間到了，什麼事都沒發生。活著、但不做事。</p><span id="more"></span><h1 id="問題出在「遲到一秒就不算數」"><a href="#問題出在「遲到一秒就不算數」" class="headerlink" title="問題出在「遲到一秒就不算數」"></a>問題出在「遲到一秒就不算數」</h1><p>仔細翻 log，才看到一行不起眼的訊息，排程的執行時間「was missed by」幾秒。</p><p>查了一下，終於找到原因，原來 APScheduler 有個參數叫 <code>misfire_grace_time</code>，預設只有 <strong>1 秒</strong>。意思是，排程到點時，如果因為某些原因晚了超過 1 秒才輪到它，APScheduler 就判定這次「misfire（錯過了）」，直接跳過不執行。</p><p>我這次是在 Windows 上跑。APScheduler 的排程跑在你自己的程式裡，到了該執行的時間，只要程式當下沒能馬上輪到它，就可能晚超過這 1 秒。個人電腦常見的睡眠、休眠，或當下負載偏高、排程執行緒被前一個工作卡住，都會造成這種延遲，放在會自動睡眠的機器上又特別容易遇到。於是每天到了該跑的時間，它就被判定 misfire、整天跳過。</p><p>對 APScheduler 來說，這是「照規則跳過」，不是錯誤。</p><h1 id="解法：把寬限時間放大"><a href="#解法：把寬限時間放大" class="headerlink" title="解法：把寬限時間放大"></a>解法：把寬限時間放大</h1><p>知道原因之後，解法很簡單，把 <code>misfire_grace_time</code> 設大一點，給它足夠的寬限。</p><figure class="highlight python"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">scheduler.add_job(</span><br><span class="line">    push_job,</span><br><span class="line">    <span class="string">&quot;cron&quot;</span>,</span><br><span class="line">    hour=<span class="number">8</span>, minute=<span class="number">30</span>,</span><br><span class="line">    misfire_grace_time=<span class="number">3600</span>,  <span class="comment"># 給一小時寬限，遲到幾秒也照跑</span></span><br><span class="line">)</span><br></pre></td></tr></table></figure><p>我設成 3600（一小時）。對「每天推一次」這種排程來說，晚個幾秒、甚至幾分鐘都無所謂，重點是它要跑。改完之後，每天都正常推了。</p><p>這裡可能會有個疑問，既然問題出在 Windows，為什麼不乾脆用 Windows 內建的 Task Scheduler？<br>因為我這支程式希望可以同時在 Mac 跟 Windows 上跑，APScheduler 讓我用同一套 Python 排程兩邊通用，不必為每個作業系統各維護一份排程設定。換個角度看，這個 misfire 坑算是把排程放進程式裡、換取跨平台便利的代價。</p><hr><p>這個坑的麻煩不在難解，在難發現，它躲在一行 log 裡，表面上什麼都正常。整件事最好笑的是，根因不過是一個預設 1 秒的參數，我一直以為是程式哪裡有問題，研究了一陣子，最後讓 AI 跑一下，馬上就揪出來。如果你的排程在 Windows 上「偶爾」或「整天」不執行又不報錯，先去翻 <code>misfire_grace_time</code>，省得跟我一樣繞遠路。</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/subprocess-cp950/">subprocess 在 Windows 的 cp950 編碼坑</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/apscheduler-windows-misfire/</id>
    <link href="https://calmkoala.github.io/apscheduler-windows-misfire/"/>
    <published>2026-06-21T00:00:00.000Z</published>
    <summary>
      <![CDATA[<p>最近有很多需要定期執行的項目，用 APScheduler 排好時間後，想說設定完就不用再管它。結果某天發現它沒正常運作，連續好幾天都沒動靜，但程式看起來一切正常，也沒噴任何錯誤，第一直覺就是自己程式一定寫錯了(抖</p>
<p>通常程式掛掉，至少會留個 stack trace 給你查；但這次它根本不報錯。程式還活著、排程也還在，log 翻過去一條紅字都沒有，就是該跑的時間到了，什麼事都沒發生。活著、但不做事。</p>]]>
    </summary>
    <title>排程每天默默不執行，又不報錯——APScheduler 在 Windows 的 misfire 坑</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="AI" scheme="https://calmkoala.github.io/categories/study-notes/AI/"/>
    <category term="AI" scheme="https://calmkoala.github.io/tags/AI/"/>
    <category term="工作流" scheme="https://calmkoala.github.io/tags/%E5%B7%A5%E4%BD%9C%E6%B5%81/"/>
    <content>
      <![CDATA[<p>過去半年用 AI 處理雜事，一開始什麼都直接丟給 AI 都能幫我處理到好，真的是有夠方便，但用久了我發現一個問題，身為一個窮人，token 根本不夠燒啊啊啊~</p><p>於是我開始想，有什麼方法可以降低 token 使用量。最先想到的，就是那些重複性的工作。</p><p>最有感的是每個月的銀行對帳單。我會收到幾份 PDF，都是加密的，而且不同來源用不同密碼。一開始我直接把檔案都丟給 AI，請它打開、再把裡面的表格整理出來。每個月、每一份都重來一次。</p><p>第一次叫 AI 做，成果非常好，沒什麼問題。問題是第二次、第三次，我還是叫它「再做一次」，它就又跑一輪推理，重新理解一次需求，重新產出。</p><p>這件事的代價，不只是「多等一下」。每跑一輪，AI 都要重新讀懂需求、重新推理，慢，而且燒 token。更麻煩的是結果不穩——同樣的輸入，這次跟上次的格式、用詞、有沒有漏項，都可能不一樣。重複越多次，成本疊得越高。</p><span id="more"></span><h1 id="其實，回到以前的做法就好"><a href="#其實，回到以前的做法就好" class="headerlink" title="其實，回到以前的做法就好"></a>其實，回到以前的做法就好</h1><p>但仔細想想，這件事的規則其實完全固定：把檔案解開、抽出表格。這種事在以前還沒有 AI 的時候，我會寫個腳本，每次需要的時候執行就好。</p><p>怎麼有了 AI，反而退化成每次都從頭做一遍？</p><p>解法其實很簡單，回到以前的做法：先讓 AI 把它寫成一支腳本，之後只要執行腳本就好。把 AI 做的事，從「每次重做」改成「寫出腳本」。</p><p>規則固定、會重複很多次的工作，先讓 AI 寫成腳本，之後每次只要叫 AI 執行那支腳本。AI 的角色，從「每次重做的苦力」，變成「維護一支工具、需要時跑它」。</p><p>回到對帳單：我把流程寫成一支腳本，丟進資料夾，腳本自己用存好的密碼解開、批次處理、輸出整理好的表格。現在我只要把檔案放進去、跑腳本就好，AI 不必再一份一份重解，省下的時間和 token 很可觀，而且每個月輸出格式都一模一樣。</p><p>換成腳本之後，你會拿回這些東西：</p><ul><li><strong>一致性</strong>：腳本每次輸出都一樣。LLM 每次重跑，格式、用詞、漏項都可能漂移。</li><li><strong>省時省額度</strong>：跑一支寫好的腳本，比重跑一輪 LLM 推理快得多，也不燒 token。</li><li><strong>可檢查</strong>：腳本是固定邏輯，你可以讀、可以測。LLM 中間怎麼想的是黑箱，錯了不好查。</li><li><strong>可累積</strong>：今天寫好，以後每次直接用，不用每次重新交代一遍前因後果。</li></ul><h1 id="但不是什麼都該腳本化"><a href="#但不是什麼都該腳本化" class="headerlink" title="但不是什麼都該腳本化"></a>但不是什麼都該腳本化</h1><p>當然，不是所有事情都該寫成腳本，硬寫反而會綁手綁腳。</p><ul><li><strong>該寫</strong>：規則固定、輸入輸出結構明確、會重複很多次。格式轉換、批次處理、固定報表這類。</li><li><strong>不該寫</strong>：一次性的、規則模糊、每次都要靠語意判斷的。這種就留給 LLM，它的強項本來就在這。</li></ul><p>判斷標準很簡單：這件事下次還會用同樣的規則再做一遍嗎？如果會，那就值得寫成腳本。</p><p>實際上手也不難：</p><ol><li>第一次遇到重複性工作，先讓 AI 寫成腳本。</li><li>你讀過一遍，確認邏輯對。</li><li>之後每次，直接叫 AI 跑這支腳本。</li></ol><p>核心是把 LLM 當推理引擎，不是當苦力。確定性的、重複的事，交給確定性的程式碼，AI 留著做真正需要判斷的部分。</p><hr><p>總之對我這種窮人來說，能少燒一點 token 是一點，跟 AI 公司的 token 之戰仍在持續(?</p><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/background-ai-agent-tasks/">哪些工作該交給背景 AI agent？</a></li><li><a href="/when-multi-agent-works/">一個 AI agent 做不好，多開幾個就會比較好嗎？</a></li><li><a href="/ai-agent-skills-more-is-better/">Skill 裝得越多，AI agent 就越好用嗎？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/script-first/</id>
    <link href="https://calmkoala.github.io/script-first/"/>
    <published>2026-06-13T16:00:00.000Z</published>
    <summary>
      <![CDATA[<p>過去半年用 AI 處理雜事，一開始什麼都直接丟給 AI 都能幫我處理到好，真的是有夠方便，但用久了我發現一個問題，身為一個窮人，token 根本不夠燒啊啊啊~</p>
<p>於是我開始想，有什麼方法可以降低 token 使用量。最先想到的，就是那些重複性的工作。</p>
<p>最有感的是每個月的銀行對帳單。我會收到幾份 PDF，都是加密的，而且不同來源用不同密碼。一開始我直接把檔案都丟給 AI，請它打開、再把裡面的表格整理出來。每個月、每一份都重來一次。</p>
<p>第一次叫 AI 做，成果非常好，沒什麼問題。問題是第二次、第三次，我還是叫它「再做一次」，它就又跑一輪推理，重新理解一次需求，重新產出。</p>
<p>這件事的代價，不只是「多等一下」。每跑一輪，AI 都要重新讀懂需求、重新推理，慢，而且燒 token。更麻煩的是結果不穩——同樣的輸入，這次跟上次的格式、用詞、有沒有漏項，都可能不一樣。重複越多次，成本疊得越高。</p>]]>
    </summary>
    <title>重複的事，別每次都讓 AI 重做一遍</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="個人專案" scheme="https://calmkoala.github.io/categories/%E5%80%8B%E4%BA%BA%E5%B0%88%E6%A1%88/"/>
    <category term="AI" scheme="https://calmkoala.github.io/categories/%E5%80%8B%E4%BA%BA%E5%B0%88%E6%A1%88/AI/"/>
    <category term="AI" scheme="https://calmkoala.github.io/tags/AI/"/>
    <category term="個人專案" scheme="https://calmkoala.github.io/tags/%E5%80%8B%E4%BA%BA%E5%B0%88%E6%A1%88/"/>
    <category term="開發工具" scheme="https://calmkoala.github.io/tags/%E9%96%8B%E7%99%BC%E5%B7%A5%E5%85%B7/"/>
    <content>
      <![CDATA[<h1 id="為什麼會做這個"><a href="#為什麼會做這個" class="headerlink" title="為什麼會做這個"></a>為什麼會做這個</h1><p>過去半年用 AI 寫程式，常常踩到三類問題：</p><ul><li>同一份需求，不同對話會給出不同的命名、錯誤處理、註解風格</li><li>對話跑長之後 AI 會忘掉前面的決策，把砍掉的選項再拿出來提案</li><li>同一個 AI 同時當作者跟審核者，幾乎不會抓到真問題</li></ul><p>試過用更講究的 prompt 解，沒有根本性改善。試過換更強的模型，問題照樣在。</p><p>後來想通，問題不是出在 prompt 或模型，是出在工作方式：規劃跟實作混在同一段對話、審核跟產出由同一個身分做、決策紀錄散在 chat 歷史裡。這三件事只要任何一件還在，下一次合作還是會踩同樣的坑。</p><p>於是動手寫了一套東西，叫 <strong>tessa</strong>。</p><span id="more"></span><h1 id="tessa-是什麼"><a href="#tessa-是什麼" class="headerlink" title="tessa 是什麼"></a>tessa 是什麼</h1><p>tessa 是一套純 markdown 的 AI 多角色協作框架。把跟 AI 協作的流程拆成幾個固定角色：</p><ul><li><strong>planner</strong>：拆需求、列候選方案</li><li><strong>planning_manager</strong>：審候選、決定採哪一條、退掉哪幾條</li><li><strong>executor</strong>：照規格動手產出</li><li><strong>qa</strong>：對照規格驗收</li><li><strong>execution_manager</strong>：最後把關、抓 spec 沒寫到的洞</li></ul><p>每個角色就是一份 markdown 檔，定義它的職責、紀律、輸出格式。沒有 runtime、沒有 SDK、沒有後台依賴，安裝後就是一份 <code>.claude/agents/*.md</code>（或對應 CLI 的格式），跑在你已有的 LLM CLI 上。</p><p>跨 CLI 支援 Claude Code、Cursor、Kiro 三個原生 adapter，加上 Anthropic Agent Skills 標準廣撒到 20+ 個相容 CLI。</p><h1 id="跑一次完整流程是什麼樣"><a href="#跑一次完整流程是什麼樣" class="headerlink" title="跑一次完整流程是什麼樣"></a>跑一次完整流程是什麼樣</h1><p>舉一個實際跑過的例子：為這套工具想名字。任務不是寫 code，是要為這一套小工具挑一個正式名字。最後拍板的結果就是 tessa 這個名字。</p><p>整個流程被拆成 6 段，依序跑：</p><ol><li>planner 出候選結構</li><li>planning_manager 審候選</li><li>planner 寫完整規格書</li><li>planning_manager 審規格書</li><li>executor 照規格產出</li><li>qa + execution_manager 驗收</li></ol><p>每段中間都有「審過才往下走」的閘門。</p><p>第二段 planning_manager 真的退回了我，說需求文件有兩個地方語意不夠精確，要先補完才接著跑。「主管」這個角色不是按按鈕、看一遍蓋章的，它真的會擋。</p><h2 id="planner-出-4-條候選"><a href="#planner-出-4-條候選" class="headerlink" title="planner 出 4 條候選"></a>planner 出 4 條候選</h2><p>planner 給的不是一條方案，是 4 條候選結構：</p><ul><li>每條附「吃哪幾個視角、弱在哪個視角」的論述</li><li>對沒推薦的方案也寫同樣篇幅論述，不用「同上不採」帶過</li><li>末尾列 RISK-FLAG，9 條風險旗標標出來請主管裁決</li><li>其中 2 條是 planner 自己也沒答的開放問題</li></ul><p>planner 不假裝自己什麼都想清楚。自承沒想清楚也是合法輸出，甚至是被鼓勵的輸出。一個會說「這個我還沒想清楚、請你決定」的 planner，比一個假裝什麼都想透了的可信得多。</p><p>好的提案不是給一個答案，是給一張包含取捨的地圖，再加一份還沒答的問題清單。</p><h2 id="planning-manager-審了什麼"><a href="#planning-manager-審了什麼" class="headerlink" title="planning_manager 審了什麼"></a>planning_manager 審了什麼</h2><p>manager 做了 4 件事：</p><ul><li>對 planner 推薦的方案逐條對齊原始需求</li><li>對沒推薦的另外三條方案各寫一段判斷論述，解釋為什麼不採</li><li>跑 friction：強制找四種類型的反例（規格沒講的邊界、可疑假設、沒考慮的使用者情境、外部視角的關鍵問題）</li><li>跑 bias 自承：明寫自己這次審核可能會傾向偷懶或過度找麻煩，給自己訂抵抗方法</li></ul><p>那場 manager 抓了 8 條漏洞。其中一條是我把章節編號引用錯：我寫「§1.3 演進階段表」，manager 跨檔讀對方檔案後發現實質內容在 §3，不是 §1.3。沒有「大概看一下」就放過。</p><p>manager 的價值不在於蓋章放行，在於那 4 件事撐住了「真的有人在擋」這件事。</p><h2 id="executor-寫稿時的紅線守備"><a href="#executor-寫稿時的紅線守備" class="headerlink" title="executor 寫稿時的紅線守備"></a>executor 寫稿時的紅線守備</h2><p>規格書定下來之後，executor 拿著規格動手產出。規格書裡列了一份禁字面表：</p><ul><li>不可以寫某幾個競品名</li><li>不可以提某幾個個人專案名</li><li>不可以出現拍板的最後決定字面（命名審議當時還在進行，結果應該保留 placeholder）</li></ul><p>executor 寫完一段就跑一次字面比對指令，確認禁區沒被踩到。寫到第三段時觸發了一條紅線：無意中提到了應該用 placeholder 代稱的名字字面。executor 沒等 manager 抓，自己跑檢查時就發現，回頭改寫了那三段，再跑一次驗證才往下寫。</p><p>紅線守備是字面 grep 機械可驗，不靠人記。從規格書把禁字面字面化、到 executor 寫完自跑驗證、到 manager 再抽查重跑，這條鏈是機械的，不靠任何角色「應該記得」。</p><p>紀律不依賴每個人的注意力，是寫進規格、跑得起來的。</p><h2 id="qa-execution-manager-驗收"><a href="#qa-execution-manager-驗收" class="headerlink" title="qa + execution_manager 驗收"></a>qa + execution_manager 驗收</h2><p>最後一段是 qa 跟 execution_manager 接手，把產出對著規格書的 AC（驗收條件）逐條跑。</p><p>那場 review 抓到一條規格書沒寫到的紅線：executor 交付的內容字面雖然沒踩禁區，但語意上等於暗示了一個應該用 placeholder 的東西。規格書原本沒涵蓋這種「字面安全但語意洩漏」的情境。</p><p>review 抓出來之後，這個發現被萃成一條經驗寫進團隊記憶。下次同類任務這條紀律會被自動帶進去，不需要再踩一次同樣的坑。</p><p>每跑完一個任務，留下的不只是成品，還有下一次會被帶進去用的經驗。</p><h1 id="不只能寫-code"><a href="#不只能寫-code" class="headerlink" title="不只能寫 code"></a>不只能寫 code</h1><p>剛剛這個命名審議的任務本來就<strong>不是寫 code</strong>。tessa 在「為一套工具想名字」這種純語感、純判斷力的任務上一樣能跑。</p><p>我自己已經實際試過、跑得起來的非工程任務有三類：</p><ul><li><strong>寫文章 &#x2F; 內容企劃</strong>：從題目、到切入角度、到規格書、到初稿、到冷讀檢查。整條鏈跟工程任務形狀一樣。這篇文章本身就是這樣跑出來的。</li><li><strong>個人專案規劃</strong>：一週的工作排程、新功能的優先順序、學習路徑規劃。每次規劃都有「planner 丟候選、manager 挑、規格書定下來」的紀錄，一個月後回去看得懂當時為什麼這樣決定。</li><li><strong>知識整理 &#x2F; 教材</strong>：把學完的主題整理成可以教別人的形狀、寫內訓教材、把研究筆記重組成長文。</li></ul><p>三類都不是寫 code，但都吃同一套「規劃 - 審核 - 執行 - 品保」的形狀。</p><p>tessa 真正解的問題不是「怎麼寫程式」，是「<strong>怎麼跟 AI 做有結構的協作</strong>」。結構這件事，跟你做的是工程任務、寫作任務、規劃任務，沒有本質差別。</p><h1 id="怎麼跑"><a href="#怎麼跑" class="headerlink" title="怎麼跑"></a>怎麼跑</h1><p>下載一個資料夾，看看裡面那幾份 markdown 檔案，跟著 markdown 跑，就有一個結構化團隊。</p><p>這個資料夾裡裝的是：</p><ul><li>幾個角色的職責描述（markdown）</li><li>幾個流程的步驟清單（markdown）</li><li>幾條團隊共用的紀律規則（markdown）</li><li>團隊共同的記憶檔（markdown）</li></ul><p>每一份就是用人話寫的 markdown，看得懂就改得動，不滿意可以自己重寫。沒有要跑什麼程式、沒有要裝什麼後台依賴、沒有要付月費、沒有要登入什麼帳號、沒有 API key 要設。</p><p>tessa 不會自動幫你做事。它不是把你替換掉的東西，是給你一張合作對象清單跟合作流程。<strong>人類仍是 team lead、仍是最後拍板的人</strong>。planner 丟候選你看、manager 擋一次你看、executor 寫稿你看、qa 抓問題你看，最後決定要不要採納的人永遠是你。</p><p>它解的不是「讓 AI 自動完成」，是「讓 AI 用一個你看得懂、你能審、你能改的方式分工合作」。</p><p>自動化是把決策權交出去，結構化是把決策權留在自己手上但讓過程整齊。前者你失去掌控，後者你拿回掌控。</p><h1 id="關於這篇文章"><a href="#關於這篇文章" class="headerlink" title="關於這篇文章"></a>關於這篇文章</h1><p>這篇文章本身是用 tessa 的內容創作預設（content-creation preset）跑出來的。從規劃結構、planner 丟候選、manager 審過退回兩次、規格書定下骨架、executor 照規格寫初稿、到 qa 抓字面，整套流程跟剛剛那個命名審議案例走的是同一條鏈。</p><p>這樣做是想驗證一件事：如果 tessa 真的有用，它在「為一套工具想名字」跟「寫一篇給開發者讀的長文」這兩個性質完全不同的任務上應該都跑得起來。如果只在工程任務上成立，「不只能寫 code」這句話就站不住腳。</p><p>跟 AI 協作的下一步不是更聰明的 prompt，是更結構化的工作方式。<strong>不用寫 code 也能讓 AI 幫你做有結構的協作</strong>。</p><hr><h1 id="參考"><a href="#參考" class="headerlink" title="參考"></a>參考</h1><ul><li><a href="https://github.com/PingChunChung/tessa">tessa repo</a></li><li><a href="https://claude.com/claude-code">Claude Code</a></li><li><a href="https://docs.anthropic.com/en/docs/agent-skills">Anthropic Agent Skills</a></li></ul><div class="related-posts"><p><strong>相關文章</strong></p><ul><li><a href="/background-ai-agent-tasks/">哪些工作該交給背景 AI agent？</a></li><li><a href="/lilyscore-launch/">LilyScore：我把 PDF 樂譜和伴奏放進同一個 App</a></li><li><a href="/when-multi-agent-works/">一個 AI agent 做不好，多開幾個就會比較好嗎？</a></li></ul></div>]]>
    </content>
    <id>https://calmkoala.github.io/tessa/</id>
    <link href="https://calmkoala.github.io/tessa/"/>
    <published>2026-05-06T16:00:00.000Z</published>
    <summary>
      <![CDATA[<h1 id="為什麼會做這個"><a href="#為什麼會做這個" class="headerlink" title="為什麼會做這個"></a>為什麼會做這個</h1><p>過去半年用 AI 寫程式，常常踩到三類問題：</p>
<ul>
<li>同一份需求，不同對話會給出不同的命名、錯誤處理、註解風格</li>
<li>對話跑長之後 AI 會忘掉前面的決策，把砍掉的選項再拿出來提案</li>
<li>同一個 AI 同時當作者跟審核者，幾乎不會抓到真問題</li>
</ul>
<p>試過用更講究的 prompt 解，沒有根本性改善。試過換更強的模型，問題照樣在。</p>
<p>後來想通，問題不是出在 prompt 或模型，是出在工作方式：規劃跟實作混在同一段對話、審核跟產出由同一個身分做、決策紀錄散在 chat 歷史裡。這三件事只要任何一件還在，下一次合作還是會踩同樣的坑。</p>
<p>於是動手寫了一套東西，叫 <strong>tessa</strong>。</p>]]>
    </summary>
    <title>tessa：純 markdown 的 AI 多角色協作框架</title>
    <updated>2026-11-22T16:09:03.631Z</updated>
  </entry>
  <entry>
    <author>
      <name>PingChun</name>
    </author>
    <category term="學習筆記" scheme="https://calmkoala.github.io/categories/study-notes/"/>
    <category term="後端" scheme="https://calmkoala.github.io/categories/study-notes/%E5%BE%8C%E7%AB%AF/"/>
    <category term="DevOps" scheme="https://calmkoala.github.io/categories/study-notes/%E5%BE%8C%E7%AB%AF/DevOps/"/>
    <category term="DevOps" scheme="https://calmkoala.github.io/tags/DevOps/"/>
    <category term="學習筆記" scheme="https://calmkoala.github.io/tags/%E5%AD%B8%E7%BF%92%E7%AD%86%E8%A8%98/"/>
    <content>
      <![CDATA[<h1 id="CI-CD"><a href="#CI-CD" class="headerlink" title="CI&#x2F;CD"></a>CI&#x2F;CD</h1><p>大多數企業採用敏捷開發，而在程式上傳到伺服器的過程中需要經過許多步驟，因此我們可以透過自動化來減少在一連串步驟中的人為疏失，並加速整體開發流程。<del>解決人類懶惰的天性</del></p><span id="more"></span><h2 id="何謂CI-CD"><a href="#何謂CI-CD" class="headerlink" title="何謂CI&#x2F;CD"></a>何謂CI&#x2F;CD</h2><ul><li><p>CI(Continuous integration)持續整合or自動化整合<br>將開發至一個階段性的程式碼(通常是版本控制的一個commit)經由自動化工具測試(Unit test)，協助檢查程式碼問題並建置出佈署的版本。</p></li><li><p>CD (Continuous Deployment)持續部署or自動化佈署<br>將測試通過的代碼自動部署到伺服器上，縮短部署的時間，減少了為錯誤。好的CD包含監控系統進行服務存活檢查，並在發生異常時主動通知開發人員。</p></li></ul><h2 id="常見CI-CD工具"><a href="#常見CI-CD工具" class="headerlink" title="常見CI&#x2F;CD工具"></a>常見CI&#x2F;CD工具</h2><h3 id="架設在本地端"><a href="#架設在本地端" class="headerlink" title="架設在本地端"></a>架設在本地端</h3><ul><li>Jenkins: 最古老的工具<ul><li>優點：能夠自行編寫插件達成各式各樣功能</li><li>缺點：學習成本高、維護不易、設定檔難撰寫</li></ul></li><li>Drone: 近年新出的工具，用Golang開發，會自動建立Docker執行流程並在完成後刪除<ul><li>優點：較易學習、建置速度快、容量小、所有流程都在Docker內完成</li><li>缺點：套件不多</li></ul></li></ul><h3 id="雲端"><a href="#雲端" class="headerlink" title="雲端"></a>雲端</h3><ul><li>GitLab CI: 只能使用在GitLab</li><li>GitHub Action: 相對年輕的工具，只能用在Github<ul><li>優點：與 Github 相容性極佳、易於使用、免費、開放性、靈活性</li><li>缺點：權限設置較為複雜、環境變數(secrets, variables)只能由Repo擁有者設定</li></ul></li></ul><hr><h1 id="GitHub-Action"><a href="#GitHub-Action" class="headerlink" title="GitHub Action"></a>GitHub Action</h1><p>在現代軟體開發中，CI&#x2F;CD是必不可少的流程，而Github Action則是一個相當熱門的工具，可以協助開發者打造自動化的CI&#x2F;CD流程。接下來將會介紹什麼是Github Action，以及如何使用它來自動化你的軟體開發流程。</p><h2 id="什麼是Github-Action？"><a href="#什麼是Github-Action？" class="headerlink" title="什麼是Github Action？"></a>什麼是Github Action？</h2><p>Github Action是一個基於事件驅動的自動化工具，它可以在你的Github repository中註冊一些行為，在某些事件發生時執行一些動作，例如：自動化測試、自動化部署等等。Github Action的核心是一個YAML語言的配置文件，你可以在其中定義工作流程、觸發事件、環境變數、依賴關係等等。Github Action是一個強大的工具，它可以大幅簡化軟體開發流程，同時也可以提升開發效率和品質。</p><!-- [文件](https://docs.github.com/zh/actions/learn-github-actions/understanding-github-actions)由repository內的yaml檔定義，在事件觸發時運行(可手動或排程)。在`.github/workflows`資料夾內建立`*.yml`即完成，會把結果用email寄信通知開發人員(目前已知觸發push時會傳送給push人員，其他條件寄信給誰尚不清楚，似乎是看用哪個帳號執行)。 --><h2 id="核心概念"><a href="#核心概念" class="headerlink" title="核心概念"></a>核心概念</h2><p>在使用 Github Action 之前，需要了解一些基本概念。Github Actions 由四個元素組成，範圍由大至小為：</p><pre><code class="mermaid">graph LR;id1(Workflow) -.-&gt; id2(Job) -.-&gt; id3(Step) -.-&gt; id4(Actions&#x2F;command)</code></pre><ul><li>Workflow：整個CI&#x2F;CD運行一次的流程，定義了一系列的工作，以執行特定的任務，當中可能包含多個 Job。</li><li>Job：任務，工作流程中的單個任務。一個Workflow可能有一至多個 Job 組成。</li><li>Step：步驟，工作流程中的一個操作，一個 Job 由一至多個 Step 組成。</li><li>Actions&#x2F;commands：命令或動作，是Github Action的最小元素，用於執行一個特定的操作，例如：構建、測試、部署等等。動作可以是內置的或來自第三方。</li></ul><p>另外需要了解的是 Event：</p><ul><li>Event：事件，是觸發工作流程的觸發器，例如：程式碼提交、Pull Request等等。</li></ul><h2 id="如何使用Github-Action？"><a href="#如何使用Github-Action？" class="headerlink" title="如何使用Github Action？"></a>如何使用Github Action？</h2><p>使用Github Action非常簡單，只需要在Github倉庫中創建<code>.github/workflows</code>目錄，然後在其中添加YAML文件即可。通常使用 config 類型的語法都是千變萬化的，以下使用一個簡單的範例來解釋：</p><figure class="highlight yaml"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br><span class="line">7</span><br><span class="line">8</span><br><span class="line">9</span><br><span class="line">10</span><br><span class="line">11</span><br><span class="line">12</span><br><span class="line">13</span><br><span class="line">14</span><br><span class="line">15</span><br><span class="line">16</span><br><span class="line">17</span><br><span class="line">18</span><br><span class="line">19</span><br><span class="line">20</span><br><span class="line">21</span><br><span class="line">22</span><br><span class="line">23</span><br><span class="line">24</span><br><span class="line">25</span><br><span class="line">26</span><br><span class="line">27</span><br><span class="line">28</span><br><span class="line">29</span><br><span class="line">30</span><br><span class="line">31</span><br><span class="line">32</span><br><span class="line">33</span><br><span class="line">34</span><br><span class="line">35</span><br><span class="line">36</span><br><span class="line">37</span><br><span class="line">38</span><br></pre></td><td class="code"><pre><span class="line"><span class="attr">name:</span> <span class="string">Go-test</span> <span class="comment"># 可自行定義，主要目的是要能看出哪個workflow在執行</span></span><br><span class="line"></span><br><span class="line"><span class="attr">on:</span></span><br><span class="line">  <span class="attr">push:</span></span><br><span class="line">    <span class="attr">branches:</span> [ <span class="string">&quot;master&quot;</span> ]</span><br><span class="line">  <span class="attr">workflow_dispatch:</span></span><br><span class="line"><span class="attr">jobs:</span></span><br><span class="line">  <span class="attr">build:</span></span><br><span class="line">    <span class="attr">runs-on:</span> <span class="string">ubuntu-latest</span></span><br><span class="line">    <span class="attr">steps:</span></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">uses:</span> <span class="string">actions/checkout@v3</span></span><br><span class="line"></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">name:</span> <span class="string">Set</span> <span class="string">up</span> <span class="string">Go</span></span><br><span class="line">      <span class="attr">uses:</span> <span class="string">actions/setup-go@v3</span></span><br><span class="line">      <span class="attr">with:</span></span><br><span class="line">        <span class="attr">go-version:</span> <span class="number">1.19</span></span><br><span class="line"></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">name:</span> <span class="string">Build</span></span><br><span class="line">      <span class="attr">run:</span> <span class="string">go</span> <span class="string">build</span> <span class="string">-v</span> <span class="string">./...</span></span><br><span class="line"></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">name:</span> <span class="string">Test</span></span><br><span class="line">      <span class="attr">run:</span> <span class="string">go</span> <span class="string">test</span> <span class="string">-v</span> <span class="string">./...</span></span><br><span class="line">  <span class="attr">deploy:</span></span><br><span class="line">    <span class="attr">name:</span> <span class="string">Deploy</span></span><br><span class="line">    <span class="attr">runs-on:</span> <span class="string">ubuntu-latest</span></span><br><span class="line">    <span class="attr">environment:</span> <span class="string">production</span></span><br><span class="line"></span><br><span class="line">    <span class="attr">steps:</span></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">name:</span> <span class="string">Checkout</span></span><br><span class="line">      <span class="attr">uses:</span> <span class="string">actions/checkout@v3</span></span><br><span class="line"></span><br><span class="line">    <span class="bullet">-</span> <span class="attr">name:</span> <span class="string">Configure</span> <span class="string">AWS</span> <span class="string">credentials</span></span><br><span class="line">      <span class="attr">uses:</span> <span class="string">aws-actions/configure-aws-credentials@v1</span></span><br><span class="line">      <span class="attr">with:</span></span><br><span class="line">        <span class="attr">aws-access-key-id:</span> <span class="string">$&#123;&#123;</span> <span class="string">secrets.AWS_ACCESS_KEY_ID</span> <span class="string">&#125;&#125;</span></span><br><span class="line">        <span class="attr">aws-secret-access-key:</span> <span class="string">$&#123;&#123;</span> <span class="string">secrets.AWS_SECRET_ACCESS_KEY</span> <span class="string">&#125;&#125;</span></span><br><span class="line">        <span class="attr">aws-region:</span> <span class="string">$&#123;&#123;</span> <span class="string">env.AWS_REGION</span> <span class="string">&#125;&#125;</span></span><br><span class="line">    <span class="string">...</span></span><br></pre></td></tr></table></figure><ul><li><p><code>name</code>：這個workflow的名子，省略時預設為.yml的檔名</p></li><li><p><code>on</code>：workflow的觸發條件，可以設定多種條件。以此範例來說，設定了一個push條件，並且指定只有 <code>push</code> 到master這個branch才會出發，另外還設定<code>workflow_dispatch</code> 來讓我們能夠直接手動觸發。除此之外還有許多的觸發條件，詳細請參考 <a href="https://docs.github.com/zh/actions/using-workflows/events-that-trigger-workflows">文件</a></p></li><li></li><li><p><code>jobs</code>：在本範例中有 <code>build</code> 和 <code>deploy</code> 兩個job</p><ul><li>name：幫job另外取名，如果不寫的話會直接使用<code>build</code>和<code>deploy</code>來作為job名稱</li><li>runs-on：指定要運行的環境，通常多使用ubuntu，當然也可以選擇windows或macOS。由於指定的內容為docker image，因此也看過直接使用其他image來作環境的使用方法，但我自己沒有測試過。當然也可以自行製作運行環境，詳細請參考 <a href="https://docs.github.com/zh/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idruns-on">文件</a></li></ul><p>所有job會同時執行，除非寫上條仵<code>needs</code>或<code>if</code>，讓jobs之間產生依賴關係就可以指定執行順序，例如：</p><figure class="highlight plaintext"><table><tr><td class="gutter"><pre><span class="line">1</span><br><span class="line">2</span><br><span class="line">3</span><br><span class="line">4</span><br><span class="line">5</span><br><span class="line">6</span><br></pre></td><td class="code"><pre><span class="line">jobs:</span><br><span class="line">  job1:</span><br><span class="line">  job2:</span><br><span class="line">    needs: job-1</span><br><span class="line">  job3:</span><br><span class="line">    needs: [job1, job2]</span><br></pre></td></tr></table></figure><p>在上面這個情況下， job2 會等待 job1 執行完成後才執行， job3 則會等待 job1 和 job2 完成，因此執行順序就會是 job1 –&gt; job2 –&gt; job3。</p></li><li><p><code>steps</code>：真正定義workflow需要執行的指令</p><ul><li>name：一樣是幫step取名，不寫時預設為 <code>Run</code> 加上 <code>users</code>的名稱，例如<code>Run actions/checkout@v3</code>，為了未來能夠清楚了解此步驟在做什麼，建議一律都命名。</li><li>uses：使用別人寫好的actions，可以在github的marketplace搜尋，例如本專案中的 <code>actions/checkout@v3</code> 就是使用<a href="https://github.com/marketplace/actions/checkout">官方提供的action</a>，此步驟在大部分的job內都需要填寫，他會把Repo中的程式碼複製到虛擬主機中。<details class="note info"><summary><p>ng no-icon</p></summary><p>這也是Github Actions的特色之一，透過重複使用step來減少重複撰寫相同的config檔，除了遵照DRY原則也增加可讀性與可維護性。</p></details></li><li>run：在沒有使用預先寫好的steps時，可以使用run指令來下bash指令，每一個指令就是一個action。</li></ul></li></ul><p>另外在範例中可以看到使用<code>secrets.AWS_ACCESS_KEY_ID</code>和<code>env.AWS_REGION</code>，此類變數可以在 Settings 中的 secrets and variables 設定。</p><div class="note warning no-icon"><p>帳號密碼請勿寫在.yml檔內，<strong>所有能看到repository的人都能看到</strong>。</p><ul><li>一般變數可設定在Enviroment Variables<ul><li>在workflow中會以明碼顯示</li></ul></li><li>敏感資訊可設定在Secrets<ul><li>在workflow中會遮蔽部分文字</li></ul></li></ul><p>上面兩項只有repository owner能設定。</p></div><br><hr><h1 id="參考資料"><a href="#參考資料" class="headerlink" title="參考資料"></a>參考資料</h1><p><a href="https://www.youtube.com/watch?v=eOlI6-BBN4E">CICD到底是什麼呢|全網最詳解</a></p>]]>
    </content>
    <id>https://calmkoala.github.io/CI-CD-Github-Action/</id>
    <link href="https://calmkoala.github.io/CI-CD-Github-Action/"/>
    <published>2023-02-07T10:04:13.000Z</published>
    <summary>
      <![CDATA[<h1 id="CI-CD"><a href="#CI-CD" class="headerlink" title="CI&#x2F;CD"></a>CI&#x2F;CD</h1><p>大多數企業採用敏捷開發，而在程式上傳到伺服器的過程中需要經過許多步驟，因此我們可以透過自動化來減少在一連串步驟中的人為疏失，並加速整體開發流程。<del>解決人類懶惰的天性</del></p>]]>
    </summary>
    <title>CI/CD(Github Action)</title>
    <updated>2026-11-22T16:09:03.630Z</updated>
  </entry>
</feed>
