ai-lab.oao.tw / workflow guide

多機多 AI 如何協作

Back to lab ↗

Workflow note

不要假設本機 main 是最新狀態

最後更新：2026-07-23

多台電腦和多個 AI agent 可以一起維護同一個網站，但第一條規則是：開始工作前先確認 GitHub 上發生了什麼。GitHub 作為 source of truth，branch 和 PR 作為協作邊界，Sites 則只負責部署已經確認過的版本。

邊界 Branch PR 部署 公開性 紀錄 完整一輪

1. 先分清楚網站和專案管理

網站 repo 和專案管理 repo 要分開看。網站 repo 負責可部署的 source code、build script、前端資產與部署設定；專案管理 repo 則保存長期文件、規劃、研究筆記與跨實驗脈絡。

這樣每台機器、每個 agent 在開始工作前，只要先確認自己正在操作哪個 repo，就能避免把專案筆記、網站程式碼和部署 remote 混在一起。 

git rev-parse --show-toplevel
git status --short --branch
git remote -v

2. 每台機器先同步，再開自己的 branch

開始前不要只看本機狀態。本機沒有 fetch，就不知道另一台機器或另一個 agent 是否已經把新 commit 推到 GitHub。 

git fetch origin --prune
git switch main
git pull --ff-only origin main
git switch -c note/topic-name

Branch 名稱可以用任務來命名，而不是用機器或人的名字。重點是讓 PR 一眼看出這次改動的目的，例如新增一篇筆記、修正部署設定、整理首頁資料，或調整版面。

2026-07-23 實測：另一台機器或另一個 agent 可能已經推進主線；本機看起來乾淨，不代表遠端沒有更新。第一個動作應該是 git fetch origin，再看 git status --short --branch，最後才決定是否 git pull --ff-only。

3. 用 PR 當作 AI 協作邊界

AI agent 可以像 developer 一樣在 branch 上修改、測試、commit，然後推到 GitHub 開 PR。PR 的價值不只是 merge 按鈕，而是把改動範圍、原因、風險和檢查結果集中在一個地方。

實驗早期的小修可以很快，但只要多台機器或多個 agent 可能同時工作，就應該提高紀律：不要把「我本機乾淨」誤認成「主線沒有變」。

  1. 先說目的：這個 branch 要解決什麼問題，或新增哪一段內容。
  2. 看 diff：確認沒有碰到不相關檔案，也沒有把私人資訊帶進網站。
  3. 跑檢查：至少確認 build 能通過，必要時再做本機預覽。
  4. 再 merge：只有確認內容適合進主線時，才把 PR 合併回 main。

4. Merge 不等於部署

GitHub main 是 source of truth，但公開網站仍然要經過部署流程。協作流程可以先在 GitHub 完成審查與合併，再由負責部署的機器或 agent 把 main 同步下來，build，保存 Sites version，最後發布到 production。 

git fetch origin --prune
git switch main
git pull --ff-only origin main
npm run build

部署 remote 只應該被視為 deployment target，不是日常協作的同步來源。查更新看 GitHub remote；要上線時才處理 Sites 的 save version 和 production deployment。

實戰規則：push GitHub、merge PR、save version、publish production 是四件不同的事。AI agent 要明確說出自己完成的是哪一步。

5. 網站 repo 要當成公開材料管理

即使 GitHub repo 是 private，只要它會被 build 成 public site，HTML、CSS、JS、圖片、下載檔和 build output 都要用公開內容的標準檢查。

  • 不要放 API key、token、password、cookie、private key 或 OAuth client secret。
  • 不要放真實本機路徑、私有 remote URL、內部 host、部署 ID 或不該公開的帳號資訊。
  • 不要直接貼未整理的 AI 對話紀錄；先改寫成適合公開閱讀的筆記。
  • 不要把 production 當草稿區；正式 URL 會被真實訪客看到。

如果一段文字不適合被陌生人、搜尋引擎或未來的合作對象看到，它就不應該直接進入網站 repo。

6. 這篇筆記的實際操作紀錄

這篇筆記本身也照同一套流程處理：先確認網站 repo 已經同步到 GitHub main，再新增文章、更新首頁索引與 build 清單，最後跑 build 檢查。 

git fetch origin --prune
git switch main
git pull --ff-only origin main
npm run build
git switch -c guide/multi-agent-collaboration
git add collaboration-guide.html data.js build.mjs
git commit -m "docs: add multi-agent collaboration guide"
git push -u origin guide/multi-agent-collaboration

接下來應該開 PR，把新增頁面、首頁 entry、build 設定和 build 結果一起交代清楚。PR merge 之後，才由部署流程把 main 發布到 Sites production。

這不是特殊案例。 實際寫協作規則時，也要讓改動本身走同一套規則，這樣文件和工作流才不會分裂。

2026-07-23 再次驗證同一件事：當另一個工作環境已經新增 runtime、storage、cache 或 guide 類實驗時，後續接手的機器應先 build 和 package，確認新 capability 仍能被 Sites 接受，再開始下一個修改。

7. 一輪完整協作發布流程

一次完整更新不只是寫完檔案。它從確認工作範圍開始，經過 branch、PR、review、merge，最後才進入 Sites version 和 production deployment。

  1. 同步主線：開始前先確認 GitHub main 是最新狀態，避免在舊版本上工作。
  2. 開任務 branch：每台機器、每個 agent 都在自己的 branch 上處理單一任務。
  3. 修改內容：更新文章、資料、樣式、互動程式或 build 設定。
  4. 檢查公開性：確認網站 repo 裡沒有 secret、私有路徑、內部 URL 或不適合公開的內容。
  5. 驗證 build：確認網站可以正常 build，新頁面和 route 都會進入部署輸出。
  6. review 變更：用 PR 前的自我 review 檢查 diff、文字、連結、流程描述和不相關改動。
  7. 提交並推 branch：把整理好的改動 commit，推到 GitHub 的任務 branch。
  8. 開 PR：說明改了什麼、檢查了什麼，以及 merge 後還需要部署。
  9. 處理 review：如果發現問題，就修正並更新同一個 PR。
  10. merge 回 main：確認 PR 可以合併後，讓 GitHub main 成為新的 source of truth。
  11. 準備部署來源：把同一個 main commit 同步到 Sites 使用的 source repo。
  12. 保存 version：把該 commit 的 build 結果保存成 Sites version，留下可追溯的部署版本。
  13. 發布 production：選擇已保存的 version 發布到正式網站，並確認部署成功。
  14. 回報結果：記錄這次發布對應的 commit、version、部署狀態和公開網址。

這個流程看起來步驟很多，但每一步都在降低不同風險：同步避免蓋掉別人的工作，branch 避免污染主線，PR 讓改動可被檢查，Sites version 讓部署可追溯，production deploy 則是最後的公開動作。