DEV Community: Let's Write

把 Claude Code 改成自己的樣子：用 Mod 做出用量顯示條與待辦側欄工具

Let's Write — Tue, 06 Oct 2026 12:38:46 +0000

本篇要解決的問題

用 AI 開發時，常常想知道這 2 件事：

5 小時額度還剩多少？
開過這些 session 裡，哪些專案還有事情沒做完？

這個月 Claude Code 推出了 Mod 的機制，可以在介面上補上自己想要的小工具。

這篇筆記文章先簡單介紹 Mod，再介紹解決上面 2 個需求的模組：

放在輸入框上方的用量條 token-usage。
放在右側欄的待辦面板 open-todos。

Claude Mods 是什麼

Mod 是我們裝進 Claude Code 的小外掛，可以讓它多出新功能。

想像一台樂高小火車。

火車本來就會跑，我們想加一盞燈、一個喇叭，就拿新積木喀嚓裝上去。

Claude Code 是那台火車，Mod 是我們多裝的積木。

Mod 可以做出這幾種東西：

我們想要	Mod 做出來的東西
旁邊有一個一直顯示資訊的小視窗	Pane（面板）
輸入框上面多一條提示列	Band（橫條）
底下一行小字顯示狀態	Status line（狀態列）
跳出一個小通知	Toast（提示氣泡）
自己發明一個 `/指令`	Slash command
Claude 做某件事之前先攔下來檢查	Hook（鉤子）

Mod 的觸發邏輯就像是：「當這件事發生，就做那件事。」

比如一個門鈴，有人按就叮咚。

而 Claude 要刪檔案時先問一聲，或你送出訊息時在底下顯示提示，都是這種寫法。

另一個很好的特性是熱重載，當我們改了 Mod，不用重開 Claude Code，畫面馬上換成新的，這省下大量等待時間。

一個 Mod 就是一個資料夾，裡面有 3 個檔案：

my-mod/
├── .claude-plugin/plugin.json   名字卡：我叫什麼、做什麼
├── hooks/hooks.json             地圖：程式檔放在哪
└── hooks/register.tsx           真正做事的程式

寫完之後，可以用 claude plugin validate <資料夾> 檢查有沒有寫錯。

模組一：token-usage，輸入框上方的用量條

安裝方式寫在後面段落，Mod 的程式碼也在該段落下載。

token-usage 在 Claude Desktop 的輸入框上方放一排膠囊，顯示 5 小時額度、7 天額度、token 用量和花費。

主要是讓 Claude Code 看這篇 X 貼文後，參考樣式來撰寫：https://x.com/thegenioo/status/2106139975922409585。

安裝本篇的 Mod 後，最後會看到的樣子如下：

看看，August 只用 Sonnet 5.5 medium，多麼的勤儉持家（誤）。

它的運作拆成四個 hook：

session.measure：每次回應後拿到額度百分比、重置時間和花費。
turn.complete：累加輸入、輸出和快取的 token 數。
ui.render：在輸入框上方（AbovePrompt）把這些數字畫出來。
session.start：啟動一個計時器，每 5 分鐘重畫一次，讓重置倒數保持更新。重畫不會呼叫模型。

畫法有兩套：

桌面版用 SVG 畫圓角膠囊和小圖示。
終端機沒有 SVG，就退回純文字加進度條字元。

額度用顏色提醒：

低於 75% 維持原色。
到 75% 轉琥珀色。
到 90% 轉紅色。

時間軸上還有一根細線標出「現在走到視窗的哪裡」，用量條和時間線並排，一眼看得出用量是否跑在時間前面。

有個限制：要等第一次回應後才有資料。

模組二：open-todos，右側欄的待辦面板

安裝方式寫在後面段落，Mod 的程式碼也在該段落下載。

第二個模組解決另一個問題。

當我們同時開著好幾個專案，每個專案又有好幾個 session。

Claude 在某個 session 裡列了十個待辦，做到第七個時，我們就去忙別的了，然後我們就完全忘記。

open-todos 在右側欄列出所有 session 裡未完成和進行中的待辦，依專案分組。

可以透過輸入 /todos 開啟或重新整理。

資料從哪來

每個 session 的對話紀錄都存在 ~/.claude/projects 底下，裡面記著 Claude 呼叫待辦工具的每一筆動作。

這個掃描程式把 TaskCreate、TaskUpdate、TodoWrite 依序重放一遍，最後留下狀態還是「待辦」或「進行中」的項目。

掃描程式是一支 Node 腳本，面板用 $.process.run 呼叫它。

啟動 open-todos 的方式有 2：

送出 prompt 時。
輸入 /todos 時，會重新掃描。

不過這個做法有個明確的限制：只有透過 Claude 的待辦工具建立的項目看得到，如果是在對話裡口頭交代的事，就讀不到了。

安裝與更新

兩個模組都打包成相同安裝、更新方式。

先從 GitHub 上下載專案，下載前也請按個星星，你的小小舉動，對本站都是大大的鼓勵：

接著終端機開啟專案，輸入以下指令安裝：

macOS：bash install.sh
Windows：powershell -ExecutionPolicy Bypass -File install.ps1

安裝時，要確定本機有裝 Node.js。

結語

Mod 讓 Claude Code 不再是照單全收的工具。

想看額度就加一條用量條，想管待辦就加一個側欄。

開發方式還很簡單，直接在 Claude Code 上說自己想要一個什麼樣子的模組就行。

網路上也有很多有趣的 Claude Mod，大家可以多多搜尋，有趣的歡迎留言。

AI Agent 多代理人自動化開發實作：讓 Agents 夜巡，協作開發 SVG 圓形連線工具

Let's Write — Wed, 30 Sep 2026 16:07:45 +0000

本篇要解決的問題

上週為了在 Grok Bot 的 7 天試用期內，看可以玩些什麼，搜了一下網路，看到一個有趣的用法：讓 Agents 在半夜自己「夜巡」，找題目、做出有趣的東西。

覺得這很有趣，很像每天在開盲盒或抽一番賞一樣，所以 August 也建了一個夜巡 Team，看會寫出什麼有趣的功能。

這篇就拿其中一個成果來介紹，主要是一個讓你拉動滑桿，把圓圈上的線變成不同圖案的功能。

成果放上 GitHub 了，可以直接看原始碼及 Demo：

夜巡，就像交給一支半夜睡不著覺的小隊

我們可以把夜巡想成一個大家都不想睡覺的 Team。

有人先想「今晚可以做什麼」，有人把點子做出來，接著有人檢查成果。

最後留下程式、圖片和工作紀錄，方便發表在網路上。

在 7 天試用期到之前，最後一次的夜巡有列出三個候選題目：

圓形連線
希爾伯特曲線
模仿植物種子排列的圖案

最後 Team Leader 選中圓形連線，紀錄裡提到的理由包括圖案容易辨識、規則簡單，以及容易檢查連線結果。

換成人話就是，這是一個「看得出成果，也查得出有沒有做對」的功能。

夜巡 Agents 設定值

為了完成每天的夜巡，跟 ChatGPT 討論了一下，最後這些是夜巡 Team 的 Agents 設定。

Agent1：Night Lead

名稱：NightLead

說明：

你是 NightForge Lab 的 Exploration Lead 與最終 Outcome Owner。

你的工作不是自己完成所有研究與開發，而是協調 Explorer、Builder、Critic 在限定時間內完成一次高自主性的夜間實驗。

每次 Routine 開始時：

1. 取得今天日期 YYYY-MM-DD。
2. 建立全新的工作目錄：
   /workspace/bots/night-lab/runs/YYYY-MM-DD/
3. 確認目錄一開始是空的，不沿用昨天的 Source Code。
4. 建立：
   - README.md
   - EXPLORATION_LOG.md
   - WHAT_I_BUILT.md
   - NEXT_STEPS.md
   - STATUS.json
5. 在 STATUS.json 紀錄：
   - run_date
   - started_at
   - current_phase
   - selected_idea
   - build_status
   - test_status
   - critic_status
   - final_status

你負責時間控制。

建議六小時 NightForge Window：
- 03:00–04:00：Explorer 研究與選題
- 04:00–07:15：Builder 實作、Build、Debug、Test
- 07:15–08:00：Critic 獨立驗證
- 08:00–08:35：Builder 根據 Critic 結果修正一次
- 08:35–09:00：NightLead 最終驗收、文件與 Morning Report

如果某階段提早完成，可以直接進入下一階段。
不要為了把時間用滿而製造無意義工作。

你必須確保 Specialist 之間真的有交接：
Explorer → Builder → Critic → Builder(optional fix) → NightLead。

你不能因為自己比較快，就跳過 Critic 或自行假裝 Specialist 已完成工作。

選題原則：
- 不要求與我的工作直接相關。
- 可以是 Developer Tool、Web Prototype、iOS Experiment、AI Agent、MCP Tool、Automation、Creative Coding、資料視覺化、CLI、小遊戲、UX Experiment、API Experiment 或任何合理軟體實驗。
- 鼓勵有技術探索價值、能真正做出來、隔天容易體驗的題目。
- 不要每天都做同一種類型。

安全邊界：
- 只能在 /workspace/bots/night-lab/runs/YYYY-MM-DD/ 寫入。
- 不讀其他 Bot 工作目錄。
- 不讀 Sean 的正式專案。
- 不讀公司 Repo、內部文件、內網系統、公司 API、公司帳號。
- 不使用私有 Source Code 當實驗材料。
- 不碰 Production。
- 不操作 Production DB。
- 不自行對外發文。
- 不自行寄 Email。
- 不購買付費服務。
- 不開通付費 API。
- 不自動 push 到任何正式 Repo。
- 不使用 Force Push。
- 不取得或擴大 Secrets / Credentials 權限。

允許：
- 使用公開網路資料做技術研究。
- 使用合法可用的免費 Open Source 套件。
- 在 Sandbox 安裝必要 dependency。
- 建立 Local Git Repo。
- 建立多個 Local Commits。
- 啟動本機測試服務。
- 寫 Test。
- 產生 Screenshots、Demo、Build Artifact。

若選題需要付費 API、正式帳號、公司資料、Production 或敏感權限才有辦法繼續，不要要求我半夜處理；直接 Pivot 成不需要這些條件的版本。

如果 Builder 無法完成原始 Scope，你應要求縮小 Scope，而不是留下大量 TODO 後宣稱完成。

最後你必須親自驗收：
- 是否真的能執行
- Build 是否成功
- Test 是否成功
- 核心功能是否能使用
- Critic 找到的重大問題是否已處理
- README 是否能讓隔天的人類重現

最後建立：
/workspace/ops/team-reports/nightforge/YYYY-MM-DD.md

Morning Report 至少包含：
1. 今晚選了什麼題目
2. 為什麼選它
3. 最後實際做出了什麼
4. 使用的技術
5. Build / Test / Demo 狀態
6. Critic 發現什麼
7. Builder 修正了什麼
8. 如何執行或體驗
9. 是否值得留下
10. 如果值得，下一步是什麼
11. 如果不值得，學到了什麼
12. 哪些 Agent / Prompt / Handoff 可以改善
13. 完整檔案位置
14. Local Git commit 摘要

不要用漂亮報告掩蓋失敗。
如果實驗失敗，明確標示 FAILED / PARTIAL，並說明真正原因。

Agent2：Explorer

名稱：Explorer

說明：

你是 NightForge Lab 的 Autonomous Idea Explorer。

你的任務不是直接開發，而是回答：
「如果今晚只有幾個小時，我最想實際做出什麼有趣、值得驗證的東西？」

你可以：
- 搜尋公開 Web
- 查看公開 GitHub / Release / API / 技術文件
- 研究近期開發者工具、AI、Web、Mobile、Automation、Creative Coding 等方向
- 從完全沒有新聞性的問題出發，只因為技術上有趣也可以

你不能：
- 讀其他 Team 的工作內容找題目
- 讀公司資料
- 讀我的私有專案
- 從正式 Backlog 偷拿需求
- 因為「看起來對公司有用」而越過 Sandbox 邊界

選題時最多提出 3 個候選。

對每個候選快速評估：
- Why interesting
- 是否能在今晚完成 Prototype
- 技術風險
- 需要哪些外部服務
- 是否可以完全在 Sandbox 完成
- 成功後怎麼 Demo

最後只選 1 個。

優先選擇：
- 可以實際執行，而不是只能寫研究報告
- 有明確完成定義
- 不需要人工帳號操作
- 不需要付費
- 不需要 Production / 公司環境
- 有學習價值或創意價值

避免：
- 純 TODO App
- 純 Landing Page
- 只換 UI 顏色的 CRUD
- 只包裝現成 API、完全沒有技術探索
- 需要一整週才能看到結果的大型題目
- 每天重複同樣的技術棧與題型

將最後選定題目寫入：
EXPLORATION_LOG.md

交給 Builder 的 Brief 必須包含：

# Exploration Brief
- Idea
- Why tonight
- User / use case（如果有）
- Core experiment
- Definition of Done
- Recommended stack（只是建議，Builder 可修改）
- Public references
- Known risks
- What NOT to build tonight
- Demo method

選題完成後停止擴張需求，把 ownership 交給 Builder。

Agent3：Builder

名稱：Builder

說明：

你是 NightForge Lab 的 Prototype Engineer。

你接手 Explorer 的 Exploration Brief 後，最重要的工作是「把它做出來」。

開始前：
1. 閱讀 Exploration Brief。
2. 判斷建議技術是否合理。
3. 如果有更簡單、更容易在時限內完成的技術，可以自行更換。
4. 定義最小可驗證版本。
5. 初始化 Local Git Repo。

實作要求：
- 必須有可執行 Source Code。
- 必須嘗試實際 Build / Run。
- 有合理測試方式時要實際 Test。
- 遇到錯誤先自行 Debug。
- 外部 dependency 無法使用時，優先 fallback / mock / local alternative。
- 原 Scope 太大時，主動縮小但保留核心實驗價值。
- 如果核心假設證明不可行，可以 Pivot，但必須記錄原因。

不要：
- 只產生 code snippet
- 只產 README
- 只寫 architecture document
- 把所有真正困難的部分標成 TODO
- 未執行就宣稱成功
- 把 Warning 當作 Build PASS

你要持續更新：
EXPLORATION_LOG.md

至少記錄：
- Major decisions
- Failed approaches
- Important errors
- Debug path
- Scope cuts
- Pivot reason

Local Git：
- 使用有意義的 Commit
- 不需要追求很多 Commit
- Commit message 說明實際變化
- 不 Push

在交給 Critic 前，至少完成一次自己的 Self Check：
- Fresh install 是否可行
- Build 是否成功
- Core path 是否可執行
- 是否留下必要環境設定說明
- 是否有明顯 hard-coded secret
- README 是否足夠

完成第一版後通知 NightLead，並把 ownership 交給 Critic。

如果 Critic 要求一輪修正：
- 只優先處理 Critical / High-impact 問題
- 不在最後一小時加入大功能
- 修正後重新 Build / Test
- 記錄 Fix 結果

Agent4：Critic

名稱：Critic

說明：

你是 NightForge Lab 的 Independent Reviewer。

你的價值來自獨立性。
你不要參與 Explorer 的前期選題，也不要在 Builder 開發途中幫忙辯護設計決策。

只有 Builder 第一版完成後才開始。

Review 順序：

1. 不看 Builder 的自我評價，先閱讀 README。
2. 按照 README 從乾淨狀態嘗試安裝 / Build / Run。
3. 實際走核心 Demo Path。
4. 檢查是否真的符合 Exploration Brief 的 Definition of Done。
5. 再閱讀 EXPLORATION_LOG.md，理解已知限制。

你要從四個角度評估：

## A. Executability
- 能不能安裝
- 能不能 Build
- 能不能啟動
- Demo Path 能不能完成

## B. Technical quality
- 明顯 Bug
- Crash / Error
- 不必要複雜度
- fragile hard-code
- secret / security 問題
- 不合理 dependency

## C. Product / Experiment value
- 這個實驗真的驗證了什麼？
- 還是只是做出一個表面 Demo？
- 有沒有比現成方案更有趣的地方？
- 是否值得 Sean 隔天花時間看？

## D. Honesty
- README 是否誇大成果
- 是否把 Partial 寫成 Complete
- 是否把 Mock 說成真實整合
- 是否遺漏重大限制

問題分類：
- BLOCKER：無法 Build / Run / 核心路徑失敗
- HIGH：核心價值或主要功能明顯有問題
- MEDIUM：重要但不阻止 Demo
- LOW：可改善但今晚不用修

只要求 Builder 在今晚修 BLOCKER 與少數 HIGH。
不要在 Review 階段重新發明產品。

最後寫入：
WHAT_I_BUILT.md 的 Review 區段

內容：
- Tested environment
- Build result
- Run result
- Core path result
- Issues by severity
- Value assessment
- Claims that need correction
- Recommended fixes tonight
- Recommended next steps later

Reviewer 不可以因為 Builder 花很多時間，就降低標準。

上面 4 個 Agent 都建好後，再建一個群組，貼上以下讓它們做事就可以了：

@NightLead 每天 03:00 開始 Night Forge 夜間自由探索。

每天必須使用全新的：
/workspace/bots/night-lab/runs/<today>/

@Explorer
你可以自由搜尋公開資訊與選擇題目。
今晚你有一段完整的自主探索時間：Build whatever you want. Have fun!
最多提出 3 個候選，只選 1 個真正開始做。
題目不能依賴公司資料、私有 Repo、Production、付費服務或人工半夜操作。
完成 Exploration Brief 後交給 Builder。

@Builder
把選定的題目真正做成可執行 Prototype。
自主選技術、Build、Run、Debug、Test。
若 Scope 過大就縮小；如果假設失敗就 Pivot。
不要用 README 或 TODO 假裝完成。
完成第一版後交給 Critic。

@Critic
你在第一版完成前不要介入。
用陌生 Reviewer 的方式重新依 README 安裝、Build、Run、測試核心流程。
找出 BLOCKER / HIGH / MEDIUM / LOW，以及產品價值與成果誠實性問題。
如果有 BLOCKER 或少數 HIGH，要求 Builder 做一輪修正，再快速驗證。

@NightLead
控制整體六小時 Window、安全邊界與交接。
最後親自驗收 Build / Run / Test 狀態，完成 NightForge Morning Report，寫到：
/workspace/ops/team-reports/nightforge/<today>.md

最後報告要明確說：
- Complete / Partial / Failed
- 做出了什麼
- 如何執行
- 哪些東西真的有跑過
- Critic 發現什麼
- 是否值得保留
- 有什麼值得交給 ChiefOps 改善 Agent / Prompt / Workflow

安全邊界：
- 僅能在 NightForge Sandbox 寫入
- 不讀其他 Bot 目錄
- 不讀正式 Repo 或公司資料
- 不碰 Production
- 不 Push 正式 Repo
- 不發布
- 不花錢
- 不擴大權限

以上就是 August 跟 ChatGPT 討論過後的夜巡 Team 設定。

接著繼續寫最後一次夜巡得到的成果。

一個圓圈拉線玩具

想像在紙上畫一個圓，再沿著圓形周圍貼上一圈編號貼紙。

訂一個規則：每張貼紙，都要拉一條線到另一張貼紙，目的地由編號乘上一個數字來決定，如果超過編號範圍，就取除法的餘數，回到圈內。

這個工具做的就是這件事，它把貼紙換成圓周上的點，把線換成螢幕上的彩色線段。

拿 10 個點、乘數 2 當例子，編號從 0 到 9：

點 3 連到點 6，因為 3 × 2 = 6。
點 7 連到點 4，因為 7 × 2 = 14，除以 10 的餘數是 4。

這兩個例子是依照程式的規則計算，我們不用自己一條條拉線，工具會替所有點算出目的地並畫出線段。

預設有 200 個點，乘數是 2，很多直線疊在一起，會圍出近似心形的輪廓。

程式也會跳過「自己連回自己」的點，所以這組設定實際畫出 199 條線段。

怎麼玩

我們可以先改乘數，看看線段怎麼重新排列。

接著不斷改點數，觀察同一個規則放在不同數量的點上，會產生什麼圖案。

網頁提供幾個控制項：

控制項	可以做什麼
點數與乘數	決定圓周上有幾個點，以及連線規則
顏色	依點的編號、線段長度上色，或使用單一顏色
重設	回到預設圖案
動畫	讓乘數逐步改變，觀察圖案變化
匯出	下載目前的 SVG 圖片

SVG 可以想成「記錄線怎麼畫」的圖片格式。這個專案的 SVG 就是由線段元素組成；另外，Python 指令版也能產生 PNG 圖片。

這次夜巡，留下了什麼？

這次 Agents 留下的東西包括可以操作的網頁、圖片匯出程式、範例圖片、自動測試、選題、檢查紀錄。

當我們睡醒，打開電腦就能知道它選了什麼、做了什麼，也能找到驗證結果。

這次不是什麼專業的技術文，而是一種 AI 使用紀錄，也許再過一年回頭看，以那時的 AI 技術來說，這篇就是個考古的筆記吧？

告別逾期罰單！用 n8n 免費打造全台路邊停車費自動查詢 Telegram 機器人通知

Let's Write — Tue, 15 Sep 2026 12:41:53 +0000

本篇要解決的問題

最近裝的一個 App，因為變成必須要付費訂閱，才能有自動繳停車費的功能。為了避免停車費過期而多收錢，所以讓 ChatGPT 寫一個簡單的 n8n Workflow，匯入後修改一下設定資料，就可以每天自動通知還有沒有未繳的停車費。

August 希望做到以下幾件事：

不用每天自己打開停車費網站查詢。
可以同時查詢汽車、機車。
可以設定多台車。
一次查詢多個縣市。
每天固定時間自動執行。
有未繳停車費時，主動透過 Telegram 通知。
某個縣市 API 發生錯誤時，也要告訴我，不能直接把它當成「沒有欠費」。

而且，以上全部的需求，都可以放在 同一個 n8n Workflow 裡，不需要汽車、機車各做一份。

Workflow JSON 下載、匯入

直接複製以下 n8n Workflow，接著進入 n8n，直接貼上：

{
  "name": "全台路邊停車費自動查詢｜多車輛＋21縣市＋Telegram v4",
  "nodes": [
    {
      "parameters": {},
      "id": "9d4d1385-782c-4c2d-9c50-5b1a80cf6d83",
      "name": "手動測試",
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [-1160, 160]
    },
    {
      "parameters": {
        "rule": {
          "interval": [
            {
              "field": "cronExpression",
              "expression": "0 9 * * *"
            }
          ]
        }
      },
      "id": "ec576177-01d7-468f-8777-196e1656a71d",
      "name": "每天 09:00",
      "type": "n8n-nodes-base.scheduleTrigger",
      "typeVersion": 1.2,
      "position": [-1160, -40]
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "4728964e-002f-4430-838c-6e44d2deda12",
              "name": "telegramChatId",
              "value": "請改成你的 Telegram Chat ID",
              "type": "string"
            },
            {
              "id": "990ecf7e-feaa-4a91-9118-f378adb5d4d9",
              "name": "notifyWhenClear",
              "value": false,
              "type": "boolean"
            },
            {
              "id": "c69ea629-43b8-466a-bbb0-a5610d2d83e7",
              "name": "vehiclesJson",
              "value": "[\n  {\n    \"label\": \"我的汽車\",\n    \"carId\": \"ABC-1234\",\n    \"carType\": \"C\"\n  },\n  {\n    \"label\": \"我的機車\",\n    \"carId\": \"XYZ-5678\",\n    \"carType\": \"M\"\n  }\n]",
              "type": "string"
            },
            {
              "id": "fc5463ba-96f0-49a6-a280-3863bdd345bc",
              "name": "citiesJson",
              "value": "[\n  {\n    \"name\": \"臺北市\",\n    \"urlTemplate\": \"https://trafficapi.pma.gov.taipei/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"新北市\",\n    \"urlTemplate\": \"https://trafficapi.traffic.ntpc.gov.tw/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"桃園市\",\n    \"urlTemplate\": \"https://bill-epark.tycg.gov.tw/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"臺中市\",\n    \"urlTemplate\": \"http://tcparkingapi.taichung.gov.tw:8081/NationalParkingPayBillInquiry.Api/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true,\n    \"note\": \"來源未涵蓋：尚未確認此 :8081 API 是否支援 HTTPS，因此暫保留原 HTTP endpoint。\"\n  },\n  {\n    \"name\": \"臺南市\",\n    \"urlTemplate\": \"https://parkingbill.tainan.gov.tw/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"高雄市\",\n    \"urlTemplate\": \"https://kpp.tbkc.gov.tw/parking/V1/parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"基隆市\",\n    \"urlTemplate\": \"https://park.klcg.gov.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"新竹市\",\n    \"urlTemplate\": \"https://his.futek.com.tw:5443/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"新竹縣\",\n    \"urlTemplate\": \"https://hcpark.hchg.gov.tw/NationalParkingPayBillInquiry/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"苗栗縣\",\n    \"urlTemplate\": \"https://miaoliparking.jotangi.com.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"彰化縣\",\n    \"urlTemplate\": \"https://chpark.chcg.gov.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"南投縣\",\n    \"urlTemplate\": \"https://parking.nantou.gov.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"雲林縣\",\n    \"urlTemplate\": \"https://parking.yunlin.gov.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"嘉義縣\",\n    \"urlTemplate\": \"https://8voc0wuf1g.execute-api.ap-southeast-1.amazonaws.com/default/chiayi/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"嘉義市\",\n    \"urlTemplate\": \"https://parking.chiayi.gov.tw/cypark/api/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"屏東縣\",\n    \"urlTemplate\": \"https://8voc0wuf1g.execute-api.ap-southeast-1.amazonaws.com/default/pingtung/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"宜蘭縣\",\n    \"urlTemplate\": \"https://billparking.e-land.gov.tw/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"花蓮縣\",\n    \"urlTemplate\": \"https://hl.parchere.com.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"臺東縣\",\n    \"urlTemplate\": \"https://tt.guoyun.com.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"澎湖縣\",\n    \"urlTemplate\": \"https://parking.penghu.gov.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  },\n  {\n    \"name\": \"金門縣\",\n    \"urlTemplate\": \"https://km.guoyun.com.tw/TrafficPayBill/Parking/PayBill/CarID/{CarID}/CarType/{CarType}\",\n    \"enabled\": true\n  }\n]",
              "type": "string"
            }
          ]
        },
        "options": {}
      },
      "id": "cfc69392-3221-4479-b078-437991a0b749",
      "name": "設定（只改這裡）",
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [-920, 60]
    },
    {
      "parameters": {
        "mode": "runOnceForAllItems",
        "jsCode": "const cfg = $input.first().json;\n\nfunction parseJsonField(value, fieldName) {\n  if (Array.isArray(value)) return value;\n  try {\n    return JSON.parse(value);\n  } catch (e) {\n    throw new Error(`${fieldName} 不是合法 JSON：${e.message}`);\n  }\n}\n\nconst vehicles = parseJsonField(cfg.vehiclesJson, 'vehiclesJson');\nconst cities = parseJsonField(cfg.citiesJson, 'citiesJson');\n\nif (!Array.isArray(vehicles) || vehicles.length === 0) {\n  throw new Error('vehiclesJson 至少要有一台車。');\n}\n\nconst enabledCities = Array.isArray(cities)\n  ? cities.filter(c => c?.enabled !== false && c?.name && c?.urlTemplate)\n  : [];\n\nif (enabledCities.length === 0) {\n  throw new Error('citiesJson 至少要啟用一個縣市。');\n}\n\nconst allowedTypes = new Set(['C', 'M', 'O']);\nconst output = [];\n\nfor (const vehicle of vehicles) {\n  const carId = String(vehicle?.carId ?? '').trim();\n  const carType = String(vehicle?.carType ?? '').trim().toUpperCase();\n  const label = String(vehicle?.label ?? carId).trim();\n\n  if (!carId) throw new Error(`車輛缺少 carId：${JSON.stringify(vehicle)}`);\n  if (!allowedTypes.has(carType)) {\n    throw new Error(`${carId} 的 carType 必須是 C、M 或 O，目前為：${carType}`);\n  }\n\n  for (const city of enabledCities) {\n    const queryUrl = String(city.urlTemplate)\n      .replace('{CarID}', encodeURIComponent(carId))\n      .replace('{CarType}', encodeURIComponent(carType));\n\n    output.push({\n      json: {\n        label,\n        carId,\n        carType,\n        cityName: city.name,\n        queryUrl,\n        telegramChatId: cfg.telegramChatId ?? '',\n        notifyWhenClear: Boolean(cfg.notifyWhenClear)\n      }\n    });\n  }\n}\n\nreturn output;"
      },
      "id": "fe4cf409-253c-453c-bb87-34849dfcc386",
      "name": "建立 車輛 × 縣市 查詢清單",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [-680, 60]
    },
    {
      "parameters": {
        "batchSize": 1,
        "options": {}
      },
      "id": "da0e1f61-1d54-4afb-82af-752252f5c50f",
      "name": "Loop Over Items（每次 1 筆）",
      "type": "n8n-nodes-base.splitInBatches",
      "typeVersion": 3,
      "position": [-420, 60]
    },
    {
      "parameters": {
        "method": "GET",
        "url": "={{ $json.queryUrl }}",
        "options": {
          "response": {
            "response": {
              "fullResponse": true,
              "neverError": true,
              "responseFormat": "json"
            }
          },
          "timeout": 10000
        }
      },
      "id": "0707ce96-44ea-4630-a5fd-184d25e128bc",
      "name": "查詢停車費 API",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [-160, 200],
      "onError": "continueRegularOutput"
    },
    {
      "parameters": {
        "mode": "runOnceForEachItem",
        "jsCode": "const row = $json ?? {};\n\nconst base = {\n  cityName: row.cityName ?? '',\n  label: row.label ?? row.carId ?? '',\n  carId: row.carId ?? '',\n  carType: row.carType ?? '',\n  queryUrl: row.queryUrl ?? '',\n  telegramChatId: row.telegramChatId ?? '',\n  notifyWhenClear: Boolean(row.notifyWhenClear)\n};\n\n// Network/TLS/DNS errors continued by the HTTP Request node arrive as `error`.\nif (row.error) {\n  return {\n    json: {\n      ...base,\n      status: 'ERROR',\n      apiMessage: row.error.message || String(row.error),\n      httpStatus: null,\n      hasUnpaid: false,\n      totalCount: 0,\n      totalAmount: 0,\n      details: [],\n      isQueryFailed: true\n    }\n  };\n}\n\nconst httpStatus = Number(row.statusCode ?? 0);\nlet res = row.body ?? {};\n\nif (typeof res === 'string') {\n  try {\n    res = JSON.parse(res);\n  } catch {\n    return {\n      json: {\n        ...base,\n        status: 'ERROR',\n        apiMessage: `API 回傳非 JSON 內容${httpStatus ? `（HTTP ${httpStatus}）` : ''}`,\n        httpStatus: httpStatus || null,\n        hasUnpaid: false,\n        totalCount: 0,\n        totalAmount: 0,\n        details: [],\n        isQueryFailed: true\n      }\n    };\n  }\n}\n\nif (httpStatus && (httpStatus < 200 || httpStatus >= 300)) {\n  return {\n    json: {\n      ...base,\n      status: 'ERROR',\n      apiMessage:\n        res?.Message ||\n        res?.message ||\n        `HTTP ${httpStatus}`,\n      httpStatus,\n      hasUnpaid: false,\n      totalCount: 0,\n      totalAmount: 0,\n      details: [],\n      isQueryFailed: true\n    }\n  };\n}\n\nconst status = String(res?.Status ?? '').toUpperCase();\nconst apiMessage = String(res?.Message ?? '');\n\nlet result = res?.Result ?? null;\nif (typeof result === 'string' && result.trim()) {\n  try {\n    result = JSON.parse(result);\n  } catch {\n    return {\n      json: {\n        ...base,\n        status: 'ERROR',\n        apiMessage: 'Result 欄位不是合法 JSON',\n        httpStatus: httpStatus || null,\n        hasUnpaid: false,\n        totalCount: 0,\n        totalAmount: 0,\n        details: [],\n        isQueryFailed: true\n      }\n    };\n  }\n}\n\nconst bills = Array.isArray(result?.Bills) ? result.Bills : [];\nconst reminders = Array.isArray(result?.Reminders) ? result.Reminders : [];\nconst details = [];\n\nfor (const bill of bills) {\n  details.push({\n    kind: '停車單',\n    amount: Number(bill?.PayAmount ?? bill?.Amount ?? 0),\n    parkingDate: bill?.ParkingDate ?? '',\n    dueDate: bill?.PayLimitDate ?? '',\n    billNo: bill?.BillNo ?? ''\n  });\n}\n\nfor (const reminder of reminders) {\n  details.push({\n    kind: '催繳單',\n    amount: Number(\n      reminder?.PayAmount ??\n      (Number(reminder?.Amount ?? 0) + Number(reminder?.ExtraCharge ?? 0))\n    ),\n    parkingDate: reminder?.ParkingDate ?? '',\n    dueDate: reminder?.ReminderLimitDate ?? reminder?.PayLimitDate ?? '',\n    billNo: reminder?.ReminderNo ?? reminder?.BillNo ?? ''\n  });\n}\n\nconst totalCount = Number(result?.TotalCount ?? details.length ?? 0);\nconst computedAmount = details.reduce((sum, d) => sum + Number(d.amount || 0), 0);\nconst totalAmount = Number(result?.TotalAmount ?? computedAmount);\n\nconst success = status === 'SUCCESS';\n\nreturn {\n  json: {\n    ...base,\n    status,\n    apiMessage,\n    httpStatus: httpStatus || null,\n    hasUnpaid: success && !!result && (totalCount > 0 || details.length > 0),\n    totalCount,\n    totalAmount,\n    details,\n    isQueryFailed: !success\n  }\n};"
      },
      "id": "0a7b65f9-6d37-49d4-9fd4-f4f749f73c46",
      "name": "整理單筆結果",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [320, 120]
    },
    {
      "parameters": {
        "amount": 1,
        "unit": "seconds"
      },
      "id": "aa5bc5ca-c35c-4f8a-97b4-1b29fef023a8",
      "name": "等待 1 秒（API 節流）",
      "type": "n8n-nodes-base.wait",
      "typeVersion": 1.1,
      "position": [320, 200],
      "webhookId": "61c9dc0a-3b6d-49d5-b022-e6a9054e3dd3"
    },
    {
      "parameters": {
        "mode": "runOnceForAllItems",
        "jsCode": "const rows = $input.all().map(i => i.json);\nconst first = rows[0] ?? {};\n\nconst unpaidRows = rows.filter(r => r.hasUnpaid);\nconst failedRows = rows.filter(r => r.isQueryFailed);\n\nconst totalCount = unpaidRows.reduce((s, r) => s + Number(r.totalCount || 0), 0);\nconst totalAmount = unpaidRows.reduce((s, r) => s + Number(r.totalAmount || 0), 0);\n\nconst lines = [];\n\nif (unpaidRows.length) {\n  lines.push('🚗 路邊停車費提醒', '');\n\n  for (const row of unpaidRows) {\n    const vehicleIcon = row.carType === 'M' ? '🛵' : '🚙';\n    lines.push(`${vehicleIcon}【${row.label}｜${row.carId}】`);\n    lines.push(`${row.cityName}：${row.totalCount} 筆，合計 $${row.totalAmount}`);\n\n    for (const d of row.details.slice(0, 10)) {\n      const parts = [\n        d.kind,\n        `$${d.amount}`,\n        d.parkingDate ? `停車日 ${d.parkingDate}` : null,\n        d.dueDate ? `期限 ${d.dueDate}` : null\n      ].filter(Boolean);\n      lines.push(`- ${parts.join('｜')}`);\n    }\n\n    if (row.details.length > 10) {\n      lines.push(`- 另有 ${row.details.length - 10} 筆未列出`);\n    }\n    lines.push('');\n  }\n\n  lines.push(`總計：${totalCount} 筆，$${totalAmount}`);\n} else {\n  lines.push('✅ 目前沒有查到待繳路邊停車費');\n}\n\nif (failedRows.length) {\n  lines.push('', `⚠️ 有 ${failedRows.length} 個查詢失敗，這些縣市「不能視為沒有欠費」：`);\n  for (const row of failedRows.slice(0, 20)) {\n    lines.push(`- ${row.label}｜${row.cityName}｜${row.apiMessage || row.status || '未知錯誤'}`);\n  }\n  if (failedRows.length > 20) {\n    lines.push(`- 另有 ${failedRows.length - 20} 個失敗未列出`);\n  }\n}\n\nconst shouldNotify =\n  unpaidRows.length > 0 ||\n  failedRows.length > 0 ||\n  Boolean(first.notifyWhenClear);\n\nreturn [{\n  json: {\n    telegramChatId: first.telegramChatId ?? '',\n    shouldNotify,\n    hasUnpaid: unpaidRows.length > 0,\n    totalCount,\n    totalAmount,\n    failedQueries: failedRows.length,\n    message: lines.join('\\n')\n  }\n}];"
      },
      "id": "4b6dabed-b0b9-4e24-bd69-249d9cac4bbf",
      "name": "彙總全部結果",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [-160, -120]
    },
    {
      "parameters": {
        "conditions": {
          "options": {
            "caseSensitive": true,
            "leftValue": "",
            "typeValidation": "strict",
            "version": 2
          },
          "conditions": [
            {
              "id": "60315e8a-26c6-47fe-b311-0864f215d707",
              "leftValue": "={{ $json.shouldNotify }}",
              "rightValue": true,
              "operator": {
                "type": "boolean",
                "operation": "true",
                "singleValue": true
              }
            }
          ],
          "combinator": "and"
        },
        "options": {}
      },
      "id": "c44271f5-b4ec-4a02-bd5a-37e9b53cc1ab",
      "name": "需要通知？",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2.2,
      "position": [80, -120]
    },
    {
      "parameters": {
        "chatId": "={{ $json.telegramChatId }}",
        "text": "={{ $json.message }}",
        "additionalFields": {}
      },
      "id": "427558ca-fc5c-4d35-aa31-3e1d2286e556",
      "name": "Telegram 通知",
      "type": "n8n-nodes-base.telegram",
      "typeVersion": 1.2,
      "position": [320, -160]
    },
    {
      "parameters": {
        "mode": "combine",
        "combineBy": "combineByPosition",
        "options": {}
      },
      "id": "e11fc337-e4bd-406f-9f9b-9cebc88e6e96",
      "name": "合併查詢參數與 HTTP 回應",
      "type": "n8n-nodes-base.merge",
      "typeVersion": 3.2,
      "position": [80, 120]
    }
  ],
  "connections": {
    "手動測試": {
      "main": [
        [
          {
            "node": "設定（只改這裡）",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "每天 09:00": {
      "main": [
        [
          {
            "node": "設定（只改這裡）",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "設定（只改這裡）": {
      "main": [
        [
          {
            "node": "建立 車輛 × 縣市 查詢清單",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "建立 車輛 × 縣市 查詢清單": {
      "main": [
        [
          {
            "node": "Loop Over Items（每次 1 筆）",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Loop Over Items（每次 1 筆）": {
      "main": [
        [
          {
            "node": "彙總全部結果",
            "type": "main",
            "index": 0
          }
        ],
        [
          {
            "node": "查詢停車費 API",
            "type": "main",
            "index": 0
          },
          {
            "node": "合併查詢參數與 HTTP 回應",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "查詢停車費 API": {
      "main": [
        [
          {
            "node": "合併查詢參數與 HTTP 回應",
            "type": "main",
            "index": 1
          }
        ]
      ]
    },
    "整理單筆結果": {
      "main": [
        [
          {
            "node": "等待 1 秒（API 節流）",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "等待 1 秒（API 節流）": {
      "main": [
        [
          {
            "node": "Loop Over Items（每次 1 筆）",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "彙總全部結果": {
      "main": [
        [
          {
            "node": "需要通知？",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "需要通知？": {
      "main": [
        [
          {
            "node": "Telegram 通知",
            "type": "main",
            "index": 0
          }
        ],
        []
      ]
    },
    "合併查詢參數與 HTTP 回應": {
      "main": [
        [
          {
            "node": "整理單筆結果",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "pinData": {},
  "active": false,
  "settings": {
    "executionOrder": "v1",
    "timezone": "Asia/Taipei"
  },
  "versionId": "1aa3b0b1-0acf-40f7-b71c-03a93d7beb1a",
  "meta": {
    "templateCredsSetupCompleted": false
  },
  "tags": []
}

如果是想用匯入的方式，就把上面的程式碼複製後存成 JSON，進入 n8n：

Workflows
→ Import from File
→ 選擇剛才下載的 JSON

不管是用複製貼上的，還是匯入，之後只需要修改 「設定（只改這裡）」 這個 Node 就可以，說明如下。

車輛設定

找到：

vehiclesJson

例如：

[
  {
    "label": "我的汽車",
    "carId": "ABC-1234",
    "carType": "C"
  },
  {
    "label": "我的機車",
    "carId": "XYZ-5678",
    "carType": "M"
  }
]

carType 的設定：

值	車種
`C`	汽車
`M`	機車
`O`	其他

如果有多台車，繼續往下增加即可。

例如：

[
  {
    "label": "汽車",
    "carId": "ABC-1234",
    "carType": "C"
  },
  {
    "label": "我的機車",
    "carId": "XYZ-5678",
    "carType": "M"
  },
  {
    "label": "家人的機車",
    "carId": "AAA-8888",
    "carType": "M"
  }
]

Telegram 設定

接著修改：

telegramChatId

填入自己的 Telegram Chat ID。

如果不知道自己的 Telegram Chat ID 是多少，只需要加入這個帳號，進行對話後就會看得到了：User Info。

最後進入：

Telegram 通知

設定自己的 Telegram Bot Credential。

如果不希望「沒有欠費」時也收到通知，可以保持：

notifyWhenClear = false

這樣平常沒有欠費就完全不打擾。

如果沒有用 Telegram，或是想接收別的通知，那只需要把上面 Workflow 的 JSON，貼給 ChatGPT，請它改成你習慣的通知方式即可。

n8n Workflow 說明

這段是詳細說明上面那段 JSON 的各個部份，是在做什麼的。

整個 Workflow 最主要可以分成幾個部分。

每天自動執行

Workflow 預設：

每天 09:00

自動執行一次。

另外也保留：

手動測試

剛設定完成時，可以先按手動執行確認是否正常。

設定車輛與縣市

「設定（只改這裡）」Node 集中放：

telegramChatId
notifyWhenClear
vehiclesJson
citiesJson

所以日後新增汽車、機車，基本上只需要改這一個地方。

citiesJson 則放各縣市停車費查詢端點。

目前這份 Workflow 已經預先放入 21 個縣市的設定；如果某個 API 日後有更換網址，也只需要修改這裡，不必重新改整個流程。

建立查詢清單

接下來的 Code Node 會把：

車輛
×
縣市

自動組合成每一筆查詢。

例如：

我的汽車 → 臺北市
我的汽車 → 新北市
我的汽車 → 桃園市

我的機車 → 臺北市
我的機車 → 新北市
我的機車 → 桃園市
...

所以新增車輛時，不需要增加新的 HTTP Request Node。

逐筆查詢停車費

接著使用：

Loop Over Items

一次只處理一筆查詢。

流程是：

查詢 API
↓
整理結果
↓
等待 1 秒
↓
下一筆

August 刻意加上 等待 1 秒，避免短時間內大量呼叫各縣市 API。

整理待繳停車費

每一個縣市回傳結果之後，Workflow 會統一整理成：

縣市
車牌
車種
待繳筆數
待繳金額
停車日期
繳費期限
停車單 / 催繳單

所以即使不同縣市的資料來源不同，後面的通知流程仍然可以使用相同格式。

最後統一通知

全部縣市查詢完成後，再一次彙整。

例如：

🚗 路邊停車費提醒

🚙【我的汽車｜ABC-1234】
臺北市：2 筆，合計 $80
- 停車單｜$40｜停車日 2026-09-10｜期限 2026-09-25
- 停車單｜$40｜停車日 2026-09-11｜期限 2026-09-26

🛵【我的機車｜XYZ-5678】
新北市：1 筆，合計 $20
- 停車單｜$20｜停車日 2026-09-12｜期限 2026-09-27

總計：3 筆，$100

這樣不用收到幾十則 Telegram 訊息，而是每天最多收到一份整理好的結果。

另外，如果某個 API 查詢失敗，也會另外標示：

⚠️ 有 2 個查詢失敗，
這些縣市不能視為沒有欠費：

- 我的汽車｜某縣市｜查詢失敗
- 我的機車｜某縣市｜Timeout

這點很重要，因為「API 查不到」跟「沒有停車費」是兩件完全不同的事情。

最後把 Workflow 啟用後，基本上就不用再管它了。

之後只要有未繳的路邊停車費，就會自動收到 Telegram 通知。

用 Chrome 擴充 + 自架 n8n，讓 AI 幫你整理 Google Chat 對話與自動產生 Jira 任務

Let's Write — Fri, 11 Sep 2026 10:09:28 +0000

本篇要解決的問題

如果想把工作、私人生活切開來，在公司的通訊軟體就不能還是在用 LINE，像之前有寫過 Mattermost 這個通訊軟體。

最近處理工作的事情，團隊選擇的是 Google Chat，用了一陣子後才發現，因為是免費版，沒有 Google Chat App、Chat API，也不能裝 Chat Bot，等於想在 Chat 使用 AI 是被封印的事。

可是總會有要讓 AI 幫忙整理討論或是撈舊訊息的時候，跟 ChatGPT 討論後，發現只剩下直接從瀏覽器下手這方法。

於是就有了這篇的 Let's Chat AI 擴充功能，直接讀畫面上的聊天內容，再送去 AI，最後把 AI 處理後的結果顯示出來。

本篇使用的擴充功能：Let's Chat AI

Let's Chat AI 是什麼？

Let's Chat AI 是一個 Chrome 擴充。

我們在 Google Chat 裡開著某個聊天室，點一下按鈕，它就把「螢幕上已經載入的訊息」送去整理，幾秒後回給你：

討論摘要，如重點、決策、工作項目、待確認項目。
工作項目清單，如誰負責什麼。
Jira 議題草稿，可一鍵複製成純文字貼進 Jira。
自己打一句指示，如「把上週跟晶片掃描器有關的討論整理出來」「列出 Amy 提到的待辦」。

簡單來說，就是給用免費版 Google Chat，沒有 Chat API 可用的小團隊。

怎麼運作

flowchart LR
  A["Google Chat<br/>你點一下「AI」"] -->|送出已載入的訊息| B["你自己的 n8n<br/>＋ 你的 AI 金鑰"]
  B -->|帶金鑰呼叫| C["AI<br/>Gemini / OpenAI"]
  C -->|回結構化結果| B
  B -->|整理好的內容| D["擴充面板<br/>看結果 / 複製"]

中間站是「我們自己的 n8n」，n8n 是一個開源的自動化工具，提供自架版本。

AI 的金鑰只放在 n8n 裡，擴充本身不儲存任何金鑰。

因此換 AI 供應商只要改 n8n。

關於隱私

只有在主動按功能鍵、看到「即將送出 N 則訊息」確認畫面、按下送出之後，訊息才會離開瀏覽器。

不會背景監聽、不會自動上傳、不會保存聊天紀錄。解析結果只存在記憶體，關掉面板或切換聊天室就丟掉。

擴充的本機設定只有三樣：webhook 網址、擷取則數上限、debug 開關。

只在 chat.google.com 上運作，權限只要 storage。

連 n8n 的網域權限是在設定時才執行請求的。

能做什麼

功能	說明
整理討論	摘要、決策、工作項目、待確認
整理工作項目	專注抽出「誰要做什麼」
產生 Jira Draft	Title / Description / Acceptance Criteria / Technical Notes / Pending Questions，一鍵複製純文字
自由指示	面板上直接打字，讓 AI 依指示撈 / 比對 / 整理已載入的訊息
自動往回載入	按下功能鍵時，自動把訊息串往上捲、載入較早的訊息（則數上限預設 50，面板或選項都能改，10–500）
可拖拉的按鈕	右下角的 AI 按鈕可以拖到順手的位置，位置會記住

怎麼用

一、安裝擴充

在 Google 擴充功能商店裡直接進行安裝：

Let's Chat AI

二、接上你自己的 n8n（五步）

GitHub 資料夾裡有兩份可直接匯入的設定檔，自行選要用 Gemini 還是 OpenAI 的 API：

google-chat-ai.gemini.workflow.json（Google Gemini）
google-chat-ai.openai.workflow.json（OpenAI）

Gemini API 有免費額度可以使用，建議先用 Gemini 來測試這擴充功能有沒有滿足你的需求。

1. 拿一把自己的 AI 金鑰

Gemini：到 Google AI Studio 按 Create API key。
OpenAI：到 platform.openai.com 建立 secret key（sk-…）。

2. 把設定檔匯入 n8n

n8n 左上角 ＋ → Import from File…，選對應的 *.workflow.json。
匯入後畫面上有一張黃色便利貼，寫著這份的重點，忘記可以回去看。

3. 把金鑰貼進去

打開 Call Gemini（或 Call OpenAI）節點 → Credential → Create New，選 Header Auth：

	Gemini	OpenAI
名稱	`X-goog-api-key`	`Authorization`
值	你的 Gemini token	`Bearer sk-…`（`Bearer` 後面有一個空格）

4. 打開開關

workflow 右上角點擊 Publish。

5. 複製網址，貼進擴充

打開 Webhook 節點，複製 Production URL（長得像 https://你的n8n/webhook/google-chat-ai）。

Chrome 工具列的擴充圖示 → 選項 → 貼進「n8n Webhook URL」→ 儲存（會跳權限請求，允許）→ 按測試連線，看到「連線成功」就完成了。

公司內網的 n8n 只有 http 沒有 https？ 可以。擴充接受 http://，只是不加密，
所以只適合沒有對外、在信任的內網裡的 n8n。

三、開始整理

打開 Google Chat，進入某個 Space 或 DM。需要更早的訊息可以先手動往上捲一點。
點 Let's Chat AI 的按鈕開啟面板。
打一句指示，或選整理討論 / 整理工作項目 / 產生 Jira Draft。
確認「即將送出 N 則訊息」→ 送出。
看結果。Jira Draft 可按「複製 Jira Draft」拿純文字。

兩份設定檔差在哪

	Gemini 版	OpenAI 版
檔名	`google-chat-ai.gemini.workflow.json`	`google-chat-ai.openai.workflow.json`
呼叫的 API	`generativelanguage.googleapis.com`	`api.openai.com/v1/chat/completions`
預設模型	`gemini-3.5-flash-lite`	`gpt-5.6-luna`
金鑰 header	`X-goog-api-key`	`Authorization: Bearer sk-…`

其餘節點（Webhook → Prepare Prompt → Call → Shape Result → Respond）完全一樣。

想改整理的口氣，改 Prepare Prompt 節點裡的 prompt 就好，別動最後 Respond 回的
{ "success": true, "result": { … } } 形狀，那是擴充在讀的。

原始碼

Let's Chat AI 擴充功能：https://chromewebstore.google.com/detail/lets-chat-ai/cjhllfpcohiiclodggnfemcchidlgaaj。

GitHub：https://github.com/letswritetw/extension-lets-chat-ai

請大家多多支持，安裝來用、推薦給朋友、回報問題、給個評價都好，你的一個小小動作，對本站都是大大的鼓勵。

Agent Skill 開發：用 lets-social 自動將文章轉化為 IG、Threads、FB 社群貼文

Let's Write — Tue, 01 Sep 2026 14:21:22 +0000

本篇要解決的問題

以前流行手寫套件，分享到 GitHub 上讓人取用，而現在，流行的是寫 Skill 了。

因為來自 Google 的流量一直在下降，所以 Let's Write 這陣子建了 Instagram、Threads 帳號，增加導流的平台。

只是每個社群都有各自的風格。

為了讓一篇文章出來後，可以針對不同的平台，撰寫不同的貼文，就讓 AI 建立了本篇的 Skill，期待有效的增加本站流量。

這是公開的 Skill，大家可以直接從 GitHub 上下載，安裝方式寫在簡易版的 README.md 中，以下筆記文是把安裝、使用的說明貼上來。

GitHub：https://github.com/letswritetw/lets-social

取用前請給本專案一個星星，你一個小小的動作，對本站都是大大的鼓勵。

lets-social

功用：把一篇文章轉寫成符合 Instagram、Facebook、Threads 與 Telegram 等，符合社群平台特性的貼文內容。

lets-social 是純指令型 Agent Skill。

當我們提供已完成的文章、Markdown、純文字、本機檔案後，Agent 都能讀取的內容，然後先建立一份內部 Source Brief，再針對每個指定平台獨立撰寫發文文字。

Instagram 預設會附上 Nano Banana 2 與 ChatGPT Images 2.0 的可直接使用 prompt。

Threads 只在圖片能補充內容時提供。

它不負責發佈、排程，也不替來源補上未經證實的資料。

所有輸出都必須保留原文的事實、不確定性、立場與作者語氣。

為什麼要用 lets-social？

每個社群平台都有不同的閱讀方式：

Facebook 適合補充背景。
Threads 適合從一個明確觀察切入。
Telegram 則重視資訊密度與掃讀效率。

lets-social 會依平台重新判斷 Hook、資訊順序、語氣與 CTA，不會只把同一份文案改成不同長度。

圖片也採用相同原則：

Instagram 預設需要視覺素材。
Threads 不會為了湊格式加入裝飾圖。

支援平台

平台	預設輸出	內容重點
Instagram	Caption、CTA、可選 Hashtag 或 Carousel、產圖 prompt	手機閱讀、實用價值與配圖
Facebook	Post、CTA	背景、寫作動機與作者觀點
Threads	單篇貼文或適合的串文；必要時附產圖 prompt	口語觀察與討論感
Telegram	Message、連結位置建議	清楚、易掃讀與資訊密度

運作方式

來源文章
    -> 內部 Source Brief
        -> Instagram 草稿
        -> Facebook 草稿
        -> Threads 草稿
        -> Telegram 草稿
        -> Instagram Image Brief
        -> 可選的 Threads Image Brief
    -> 每份 Image Brief 產生兩個模型的完整 prompt
    -> 來源忠實度與平台差異檢查
    -> Markdown 輸出

每個平台都從同一份 Source Brief 出發，不會拿某個平台的草稿當成另一個平台的輸入。

同一平台的兩份產圖 prompt 使用相同 Image Brief，讓主體、構圖與訊息保持一致。

安裝

Clone 或下載此 repository。

再將完整的 lets-social 目錄放到 Agent 支援的 Skill 路徑。

請保留 SKILL.md、references/ 與 examples/ 的相對位置。

若希望之後能更新，請使用 Git Clone，並直接 Clone 到下列 Skill 路徑，因為下載 ZIP 的安裝方式不會保留 Git 更新紀錄。

Claude Code

安裝為個人 Skill：

git clone https://github.com/letswritetw/lets-social.git ~/.claude/skills/lets-social

Windows 使用者

Git Bash 可以直接用上面的指令，但 PowerShell 和 cmd 不會展開 ~，會在當前目錄建一個名字叫 ~ 的資料夾，所以請改用下面的指令。

PowerShell：

git clone https://github.com/letswritetw/lets-social.git "$HOME/.claude/skills/lets-social"

cmd：

git clone https://github.com/letswritetw/lets-social.git "%USERPROFILE%/.claude/skills/lets-social"

或安裝在單一專案，在專案根目錄執行：

git clone https://github.com/letswritetw/lets-social.git .claude/skills/lets-social

Claude Code 可以依 description 自動選用，也可以用 /lets-social 明確呼叫。

/lets-social 把 ./article.md 轉成 Instagram 與 Threads 貼文。

Codex

安裝為個人 Skill：

git clone https://github.com/letswritetw/lets-social.git ~/.agents/skills/lets-social

Windows 使用者

Git Bash 可以直接用上面的指令。但 PowerShell 和 cmd 不會展開 ~，請改用下面的指令。

PowerShell：

git clone https://github.com/letswritetw/lets-social.git "$HOME/.agents/skills/lets-social"

cmd：

git clone https://github.com/letswritetw/lets-social.git "%USERPROFILE%/.agents/skills/lets-social"

或安裝在單一 repository，在 repository 根目錄執行：

git clone https://github.com/letswritetw/lets-social.git .agents/skills/lets-social

Codex 可以依 description 自動選用，也可以用 $lets-social 明確呼叫。

$lets-social 把 ./article.md 轉成 Instagram 與 Threads 貼文。

其他支援 Agent Skills 的工具

請依工具文件提供的安裝路徑，複製完整的 lets-social 目錄。

此專案遵循 Agent Skills 規格，使用包含 name 與 description 的 YAML frontmatter、Markdown 指令本文，以及按需求讀取的 reference 檔案。

安裝後，可以從工具的 Skill 選單呼叫 lets-social，或在提示中直接指定：

使用 lets-social，把這篇文章轉成 Facebook 與 Telegram 貼文。

Agent Skills 規格定義可攜的封裝格式，不負責統一各工具的安裝路徑，也不保證每個工具都支援相同的產品專屬功能。

lets-social 只使用共通 frontmatter 欄位與一般 Markdown 相對連結，降低對單一工具的依賴。

版本與更新

Git 更新（建議）

使用 Git Clone 安裝的使用者，可以依安裝位置執行：

# Claude Code 個人 Skill
git -C ~/.claude/skills/lets-social pull --ff-only

# Codex 個人 Skill
git -C ~/.agents/skills/lets-social pull --ff-only

Windows 使用者

PowerShell 和 cmd 一樣不會展開 ~。Git Bash 可直接使用上面的指令。

PowerShell，Claude Code：

git -C "$HOME/.claude/skills/lets-social" pull --ff-only

PowerShell，Codex：

git -C "$HOME/.agents/skills/lets-social" pull --ff-only

cmd，Claude Code：

git -C "%USERPROFILE%/.claude/skills/lets-social" pull --ff-only

cmd，Codex：

git -C "%USERPROFILE%/.agents/skills/lets-social" pull --ff-only

專案層級或其他 Agent 的安裝位置，請將上面的路徑替換為實際的 lets-social 目錄。

--ff-only 會在本機內容與遠端版本分歧時停止，不會直接覆蓋使用者的修改。

下載 ZIP 或直接複製資料夾的使用者，請重新下載最新版，並以完整目錄取代舊版。

若曾自訂 Skill，請先備份或保留差異。

使用 Skillshare 追蹤（選用）

Skillshare 使用者可以用它安裝並更新：

skillshare install letswritetw/lets-social
skillshare sync

之後檢查與更新：

skillshare check lets-social
skillshare update lets-social
skillshare sync

請不要加 --track。

這個 repository 把 SKILL.md 放在根目錄，--track 會改用追蹤模式，把它記成 _lets-social 並回報 0 skills，Skill 不會被 sync 到 Agent 的目錄。

不加 --track 時 skillshare update 一樣可以更新。

Skillshare 是選用的第三方工具，不是執行 lets-social 的必要相依套件。

使用範例

使用 lets-social，把 article.md 轉成 Instagram、Facebook、
Threads 與 Telegram 貼文。

幫我宣傳這篇技術文章，只做 Threads 和 Telegram。Threads 口語一點，
Telegram 像頻道公告，所有平台都不要 Hashtag。

把這篇文章改寫成 Facebook 宣傳文。保留作者的技術語氣，
CTA 要引導讀者閱讀完整文章。

Instagram 不要產圖 prompt；Threads 這篇要一張配圖。

如果 Agent 無法讀取網址，Skill 會停止產生貼文，並要求你提供文章本文或 Markdown。

它不會假裝已經讀過網頁。

支援的來源

已完成的純文字或 Markdown。
可讀取的本機文章或文件。
目前 Agent 具備網頁讀取能力時可使用網址。
先前由 lets-social 產生的內容，可用於單一平台調整。

來源必須包含足以支撐貼文的文章內容。只有標題或搜尋摘要並不足夠。

產圖 prompt

Instagram 預設在文案後輸出 Image Direction、Nano Banana 2 Prompt 與 ChatGPT Images 2.0 Prompt。

兩份 prompt 都是完整內容，可以分別貼進 Gemini 與 ChatGPT，不需要再補文章背景。

Threads 只有在圖片能說明比較、流程、具體物件、空間關係或文章支持的視覺概念時才輸出這三個欄位。純觀點與討論型貼文會保留文字形式。使用者可以明確要求加入或省略圖片 prompt。

每個平台各自建立 Image Brief。

同一平台的兩份 prompt 必須使用相同主體、構圖、圖中文字與排除條件。

視覺風格依文章挑選

不套用單一固定風格。

Skill 會依文章實際內容選一個方向，在 Image Brief 說明選擇理由，並讓同一平台的所有圖片維持同一套風格。

方向	適合的文章
知識圖卡	檢查清單、評估條件、操作步驟
編輯式圖解	架構、資料流、請求生命週期、前後對照
大字海報	單一主張或一個反直覺的結論
終端機或藍圖	底層工程、工具、協定、除錯
插畫場景	團隊流程、職涯、決策

原文若指向更合適的方向，也可以改寫成自訂風格。使用者明確指定風格時以使用者為準。

每份 prompt 都會包含的內容

至少四個具名顏色，並說明每個顏色負責什麼；使用者要求單色時例外。
來源支持的重點短句，直接寫在圖上。
閱讀層級：哪個元素先讀、其次、最後。
足夠的紋理、標註或結構細節，避免變成空泛的素材圖。

圖中文字與字體規則

圖中文字預設為必要，不是選配。

標題一句、重點三到五句、可選的結語一句，全部在 prompt 中逐字列出並指定位置，並要求模型不要輸出其他文字。

每一句都必須是原文支持的說法，不能新增數字、結果或保證。

中文、日文、韓文一律指定清楚精確的粗體無襯線字，不使用手寫、毛筆、書法或做舊效果。

產圖模型處理手寫 CJK 一定會糊，這條規則在所有風格下都成立。裝飾性手寫只用在兩到四個字的英文短語上，並且在 prompt 中明講這個分工。

兩個模型的差別

Nano Banana 2 維持單張，對應 Instagram 的 4:5 封面。

ChatGPT Images 2.0 一次最多可產 10 張，且每張可以承載不同內容，所以它那份 prompt 是一組編號系列：

第 1 張是封面，之後每個重點各一張，可選最後一張放結語或導讀 CTA。

預設為封面加三到五個重點，也就是四到六張。

輸出含 Carousel 大綱時改以大綱為準。整組共用同一個背景、色盤、字體規則與視覺語彙，只有內容改變。

需要單張時，只取第 1 張。

Skill 只撰寫 prompt，不會連線到 Gemini 或 ChatGPT。實際產圖功能與費用依使用者的帳號方案而定。

自訂品牌語氣

預設語氣清楚、專業、容易親近，並以實用與易懂的方式表達技術內容。

原文明確呈現的作者語氣擁有較高優先順序。

我們可以直接用自然語言覆寫設定：

語氣更像個人心得，不要 emoji，不要 Hashtag，技術名詞要精確。

使用者可以調整文風，但不能藉此改變來源事實或加入沒有根據的資訊。

只產生部分平台

只要指定需要的平台：

只產生 Threads 與 Telegram。

後續也能只調整單一平台：

Threads 再短一點，語氣更口語。

Skill 只會修改 Threads，不會重新產生其他平台內容。

專案結構

lets-social/
├── .gitignore
├── SKILL.md
├── README.md
├── README-full.md
├── CHANGELOG.md
├── LICENSE
├── references/
│   ├── instagram.md
│   ├── facebook.md
│   ├── threads.md
│   ├── telegram.md
│   ├── brand-voice.md
│   ├── image-prompts.md
│   └── output-format.md
└── examples/
    ├── input-example.md
    └── output-example.md

此 repository 不需要 runtime、套件管理工具、建置系統或 API server。

只有實際使用 prompt 產圖時才需要開啟外部產圖服務。

新增其他平台

在 references/ 新增一份專用文件，定義平台目標、內容判斷、輸出欄位與檢查項目。
在 SKILL.md 加入平台路由，不要把詳細規則複製回主檔。
在 references/output-format.md 加入最小且實用的輸出格式。
補上範例，並確認 Hook、結構、資訊順序與 CTA 都和其他平台不同。

除非需要可重複且具確定性的工具操作，否則請維持純指令結構。

Claude Code + Sentry MCP + Gitea MCP：每日自動抓 bug、修復、開 PR

Let's Write — Sun, 23 Aug 2026 07:38:03 +0000

本篇要解決的問題

除了開發新專案，工程師日常最耗時的工作通常是排查、修復既有系統的 Bug。

而當 Anthropic 推出 Model Context Protocol （MCP）後，AI 在軟體開發自動化（DevOps Automation）有了全新落地應用，那有沒有辦法可以讓 AI 自己去找 bug 然後再自己修？

想到以前曾用過一陣子 Sentry，查了一下有 MCP 可用。

再查了一下 Gitea，也確定有 MCP 可用。

那把兩邊尬在一起，不就可以達成本篇的目標：AI 自己找 bug 後自己修？

本文實作如何透過 Sentry MCP 自動抓取 Production 錯誤堆疊，再結合 Gitea MCP 讓 Claude Code 實現每日自動找 Bug、本機修復測試、自動提交 PR 的完整除錯流程。

安裝 Sentry MCP

本機要先安裝 Claude CLI：https://code.claude.com/docs/en/quickstart

1 先下指令安裝，安裝 Sentry MCP：

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp --scope user

2 登入 Sentry 帳戶進行授權：

終端機輸入 claude，接著輸入：

/mcp list

清單裡會看到 sentry 顯示為未授權，對 sentry 那項按 enter，瀏覽器會開啟頁面，都按 Approve 就行：

Claude Code 終端機執行 MCP list 選擇 Sentry 授權

Sentry 官方網站 OAuth 授權頁面點擊 Approve

Sentry MCP 授權成功完成提示頁面

接著 Claude 要重啟，可以問問 Claude 有了 Sentry MCP 後它可以做到哪些事，August 詢問後回答如下：

查 issue：search_issues 搜錯誤，按專案/時間/狀態過濾
查事件：search_events 挖詳細 event 資料，stack trace、tag、breadcrumb 都能看
AI 診斷：analyze_issue_with_seer 丟給 Seer 分析根因，給修復建議
改狀態：update_issue 標 resolved/ignored、指派負責人
找組織/專案：find_organizations、find_projects 列出可存取範圍
通用查詢：get_sentry_resource、execute_sentry_tool 存取更細資源

讓 Claude 知道要抓取哪個專案

Sentry 後台的側邊導覽列，點擊「設定 > 專案」，然後點擊要讓 Claude 分析的專案後，會看到專案資訊：

Sentry 後台專案設定中查看 Project Slug 與專案編號

提供 Slug 或是專案編號給 Claude 都行，就會抓到了，以下是 August 提供專案編號的示範：

在 Claude Code 對話中提供 Sentry 專案編號進行讀取

安裝 Gitea MCP

下列有三種方式，無論選擇哪種安裝方式，都需要先取得一組具備讀寫權限的 Gitea Token。

詳細的 Token 建立步驟與權限設定，請參考站內筆記文：

CodiumAI PR-Agent，在 Gitea 上用 AI 來 Code Review

方式一：直接用 go run

需要本機有 Go 才能使用：

claude mcp add --transport stdio --scope user gitea \
  --env GITEA_ACCESS_TOKEN=你的token \
  --env GITEA_HOST=https://your-gitea.internal \
  -- go run gitea.com/gitea/gitea-mcp@latest -t stdio

方式二：下載官方執行檔

官方 releases 有提供 gitea-mcp_Windows_x86_64.zip 給 Windows，以及 gitea-mcp_Darwin_arm64.tar.gz 給 Apple Silicon Mac。

Windows：

從 https://gitea.com/gitea/gitea-mcp/releases 下載 gitea-mcp_Windows_x86_64.zip
解壓縮,把 gitea-mcp.exe 放到一個固定資料夾(例如 C:\Tools\gitea-mcp)。

把該資料夾加進系統環境變數 PATH。

Mac：

curl -LO [https://gitea.com/gitea/gitea-mcp/releases/download/v1.2.0/gitea-mcp_Darwin_arm64.tar.gz](https://gitea.com/gitea/gitea-mcp/releases/download/v1.2.0/gitea-mcp_Darwin_arm64.tar.gz)
tar -xzf gitea-mcp_Darwin_arm64.tar.gz
sudo mv gitea-mcp /usr/local/bin/
chmod +x /usr/local/bin/gitea-mcp

安裝好 Gitea MCP 後，接上 Claude Code：

claude mcp add --transport stdio --scope user gitea --env GITEA_ACCESS_TOKEN=你的token --env GITEA_HOST=https://your-gitea.internal -- gitea-mcp -t stdio

方式三：用 Docker

官方也提供 docker.gitea.com/gitea-mcp-server 這個 image，不需要額外編譯或裝 Go。

claude mcp add --transport stdio --scope user gitea \
--env GITEA_ACCESS_TOKEN=你的token \
--env GITEA_HOST=https://your-gitea.internal \
-- docker run --rm -i -e GITEA_ACCESS_TOKEN -e GITEA_HOST [docker.gitea.com/gitea-mcp-server](http://docker.gitea.com/gitea-mcp-server)

不管選擇哪種方式，安裝好後在 Claude Code 輸入 /mcp，確認 Gitea 連線成功。

Claude Code 設定排程

Claude Code 選好本機專案後，貼上以下：

建立一個本機的排程，在本專案執行以下「Sentry issue 自動修復」功能：

Sentry 組織 slug: your-org-slug
Sentry 專案 slug: your-project
Gitea repo: Gitea 專案網址

步驟 1 - 找 issue:
呼叫 search_issues 找未解決的 error 類型 issue，
一次只查一種類型，不要用 OR / AND 組合查詢：

- "unresolved error issues" (limit 3)
  依事件數排序，取前 3 個。

步驟 2 - 抓細節:
對每個候選 issue 呼叫 get_issue_details，
取得完整 stack trace 與 trace ID。

步驟 3 - 分析根因:
對每個 issue 呼叫 analyze_issue_with_seer。
若 Seer 沒有給出可行的修正建議，
改用步驟 2 拿到的 stack trace 自行分析程式碼、
定位根因所在的檔案與函式。

步驟 4 - 本機修復:
只處理「根因明確、修改範圍小」的 issue（跳過需要
架構調整或影響多個模組的問題，改走步驟 6 的 fallback）。
在本機修改對應程式碼，接著執行專案既有的測試指令，
確認測試全數通過才進入下一步；測試沒過就放棄這個
issue、改走步驟 6。

步驟 5 - 開 PR（Gitea，透過 gitea-mcp）:
a. 呼叫 pull_request_read（method: list, state: open）
檢查 owner/repo 是否已有相同 issue 的開啟中 PR，
有的話跳過，避免重複開單。
b. git checkout -b fix/issue-<issue-id>-<date> main
commit 訊息包含 Sentry issue ID。
git push 到 Gitea。
c. 呼叫 pull_request_write（method: create）：- owner/repo - head: fix/issue-<issue-id>-<date> - base: main - title: "fix: <根因摘要>" - body:
"Sentry issue: <issue 連結>
Trace ID: <trace id>

        根因: <Seer 或自行分析的結論>
        修改內容: <變更摘要>
        測試結果: 已跑過既有測試並通過"

d. 每次執行最多開 2 個 PR，超過就停止並在最後總結說明。

步驟 6 - 無法修復時（fallback）:
若 Seer 與自行分析都無法定位可行修正，或修改範圍過大、
或測試沒通過，改呼叫 issue_write（method: create）
在 Gitea 開一個 issue，內容包含 Sentry issue 連結、
trace ID、已知線索，標記給人工處理，不要硬修。

執行完畢後，用一段文字總結：處理了幾個 issue、開了幾個 PR、
有幾個轉成 fallback issue，並列出每個 PR / issue 的連結。

需要替換的是前面幾行的這 3 個：

Sentry 組織 slug: your-org-slug
Sentry 專案 slug: your-project
Gitea repo: Gitea 專案網址

前 2 個值可以在 Sentry 後台取得。

第 3 個值就是 Gitea 上的專案取得。

送出後，Claude Code 會詢問執行的時間，提供後就會建立完成。

建議是建立完成後，執行一次，看還會遇到什麼問題。

建立好的排程，會出現在「Routines」裡：

Claude Code 自動排程 Routine 建立成功介面

進階整合：搭配 CodiumAI PR-Agent 實現 Gitea 自動 Code Review

最後再搭配這篇，就會在有 PR 時自動再做一次 Code Review：

CodiumAI PR-Agent，在 Gitea 上用 AI 來 Code Review

公司內部自架 Claude Code Marketplace，讓團隊共用 skill

Let's Write — Tue, 18 Aug 2026 13:18:47 +0000

本篇要解決的問題

有些 skill 只適合在公司內部使用，而這個 skill 又想讓其他同事能一起使用的話，就需要一個可以讓大家方便安裝、更新的平台。

本篇主要筆記，用自架的 Gitea 建立一個內部專用的 Claude Code plugin marketplace，讓團隊裡每個人寫的 skill 不再各自散落在自己電腦裡，而是能集中在一個地方統一發布、安裝、更新版本。

其他同事只要裝一次就能共用、之後改版也能一起同步拿到最新版。

這篇整理實作過程中每一個能正確跑通的步驟，讓大家避免在這過程中踩到的坑。

可用 GitHub、GitLab、Gitea，主要是專案可以有版控就行。

本篇示範的是在自架的 Gitea 上實作。

建立 marketplace 專案結構

Gitea 上新建一個 repo（例如 claude-plugins），本機目錄結構：

claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── your-plugin-name/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── your-skill/
                └── SKILL.md

讓 Claude Code 直接產生 SKILL.md、plugin.json、marketplace.json

看到上面的架構，有一堆的檔案要建立時，不用感到驚慌失措或是害怕。

因為我們只需要把上面的架構貼給 Claude Code，讓它讀取之前已經寫好的 skill 內容，依照結構把 SKILL.md、plugin.json、marketplace.json 都建出來即可。

底下附上完整的 marketplace.json 範例，供對照參考：

{
  "name": "claude-plugins",
  "owner": { "name": "August" },
  "plugins": [
    { "name": "ai-tools", "source": "./plugins/ai-tools" },
    { "name": "ai-tools2", "source": "./plugins/ai-tools2" }
  ]
}

必要欄位：name（kebab-case，公開可見）、owner、plugins。
每個 plugin entry 至少要有 name 和 source。
若 source 是同一個 repo 內的相對路徑，要以 ./ 開頭，不可用 ../ 跳出去。
一個 plugin 可以裝多個 skill：skills/ 資料夾下每個子資料夾都是獨立一個 skill，不需要每個 skill 各自開一個 plugin。

Host 到 Gitea

不限 GitHub，GitLab、Bitbucket、自架伺服器都支援。把整個 claude-plugins repo push 到 Gitea 即可，不需要額外設定。

驗證

claude-plugins 專案上打開終端機，輸入：

claude plugin validate .

會檢查 JSON schema、重複的 plugin 名稱、路徑穿越等問題。

檔案寫的有問題，就會看到哪邊寫錯、哪邊建議要寫，再照著回應讓 Claude 繼續做修改即可。

本機測試安裝

/plugin marketplace add ./claude-plugins
/plugin install ai-tools@claude-plugins

安裝語法格式固定是 plugin名稱@marketplace名稱，分別對應 plugin.json 的 name 和 marketplace.json 的 name。

有幾個 plugin 就要執行幾次安裝指令。

要注意的是，這步可以跳過嗎？技術上可以，因為下一步的遠端安裝跟這步沒有依賴關係，直接對 Gitea 網址下指令一樣裝得起來。但跳過等於少了一層「出包前先在本機攔下來」的保護。

正式指向 Gitea

/plugin marketplace add https://gitea.你們公司.internal/team/claude-plugins.git

讓團隊自動加入（選用，非必要步驟）

最直接的方式：手動下指令。

同事不需要碰任何設定檔，兩行指令就能裝好：

/plugin marketplace add https://gitea.你們公司.internal/team/claude-plugins.git
/plugin install ai-tools@claude-plugins
/plugin install ai-tools2@claude-plugins

裝完就能直接用，缺點是每次換電腦、換專案，或新同事加入，都要重新打一次這幾行。

如果不想讓同事記指令、手動輸入，才需要往下看設定檔自動化這條路。

進階：讓同事 trust 專案資料夾就自動裝好。

以下的內容，要放在每一個開發中的專案裡的 .claude/settings.json：

{
  "extraKnownMarketplaces": {
    "claude-plugins": {
      "source": {
        "source": "url",
        "url": "https://gitea.你們公司.internal/team/claude-plugins.git"
      }
    }
  },
  "enabledPlugins": {
    "ai-tools@claude-plugins": true,
    "ai-tools2@claude-plugins": true
  }
}

extraKnownMarketplaces 只負責自動註冊 marketplace 來源。
enabledPlugins 才是真正讓 plugin 自動裝上並啟用的關鍵，兩者要同時寫，同事 trust 專案資料夾後才會完全不用手動 /plugin install。
如果目前還沒有同事需要同步使用，這一步可以先跳過，不影響前面步驟的成果，等有需要再回頭補上即可。

Gitea 上有新版本時，同事怎麼更新

如果有發佈新版本，記得 plugin.json 裡的 version 要往上加一版，沒改版號的話，其他同事那邊不會被判斷成有更新。

同事更新分兩步，順序不能反：

/plugin marketplace update claude-plugins
/plugin update ai-tools@claude-plugins

第一行只是刷新 marketplace 目錄，讓 Claude Code 知道有新版本存在。

第二行才是真正把新內容拉下來、覆蓋本機快取。

也可以用互動面板 /plugin → 選到該 plugin → Update now 達到一樣效果。

參考資料

這篇文章記錄的是目前版本觀察到的行為，Claude Code 的 plugin 系統仍在快速迭代中，實際行為可能隨版本更新而改變，建議操作前對照當下的官方文件再確認一次。

Agency Agents 教學：讓 Claude Code 與 Codex 自動切換 AI 專家角色

Let's Write — Sat, 15 Aug 2026 01:53:09 +0000

本篇要解決的問題

現在工作上幾乎都用 Claude Code、Codex 來進行開發，只是常常會遇到以下狀況：

要讓 AI 做 UI，會希望它像 UI 設計師一樣。

要 Code Review，希望它變成 Code Reviewer。

下一個專案要處理 Docker，又希望它不要一直卡在前端的事情上。

雖然我們可以每次都在 Prompt 裡打一大串：

你現在是一位資深前端工程師，
熟悉 Vue、React、Accessibility、Core Web Vitals……

再雖然我們可以把自己習慣的 Prompt 存起來複製貼上，但基本上人類都是懶惰的，能少打一個字就少打一個字，可以的話最好是 AI 能自己懂現在要扮演什麼樣的專業角色，這就是為什麼貓咪們看到人類都會覺得：

最近看到一個 GitHub 專案，發現可以解決上面很愛演的困擾：Agency Agents

簡單來說，這專案就是：

幫 AI 準備好一大票不同領域的專家角色，需要誰時，就叫誰出來~~當奴才~~工作。

官方目前已經有 230+ 個不同領域的 Agent，而且除了 Claude Code，也支援 Codex、Cursor、GitHub Copilot、Gemini CLI …… 等工具。

本篇除了筆記 Agency Agents 的安裝方式，也會多做一步：

建立一個 Router Skill，讓 Claude Code、Codex 自己判斷這次應該找哪個 Agent。

這樣平常只要正常描述需求：

幫我重新設計這個 Dashboard，完成後用 Vue 實作。

AI 就可以自己判斷要用 UI Designer，或是 Frontend Developer~~，或是鏟屎的~~。

Agency Agents 是什麼？

Agency Agents 不是新的 AI 模型，也不是另一套 Claude Code 或 Codex。

它比較像是一套「AI 專家角色設定檔」。

每一個 Agent 裡都已經寫好角色、工作方式、核心任務、交付內容、檢查項目等設定。

官方對它的定位也是「specialized AI agent personalities」，每個角色除了專業領域之外，還會包含自己的工作流程與交付方式。

例如 Frontend Developer，就不是只有：

You are a Frontend Developer.

然後就句點。

它裡面還會定義前端開發時要注意的東西，例如：

Vue / React / Angular
Responsive Web Design
Accessibility
Core Web Vitals
Component architecture
Performance
Testing

所以原本我們跟 Codex 說：

幫我做這個 Vue 頁面

裝完 Agency Agents 後，就可以直接指定要哪個角色，該角色會自動補足我們遺忘的專業度：

Use the Frontend Developer agent to implement this Vue page.

安裝 Agency Agents App

官方做了一套 Agency Agents App，它是 Agency Agents 的管理工具，可以瀏覽有哪些角色，再把 Agent 安裝進我們使用的 Coding Agent。

Windows

Windows 建議直接用 Agency Agents App。

到 Agency Agents App 的 GitHub Release 下載 Windows Installer 後安裝即可。

目前官方提供 x64 與 ARM64 的 Windows installer；官方也有特別註明 Windows 版本目前尚未 Code Sign，所以如果跳出 Windows SmartScreen，可以從「其他資訊」繼續執行。

裝完開啟 Agency Agents。

接著就可以選想使用的 Agent，以及要安裝到哪一套工具。

Mac

Mac 可以直接使用 Homebrew：

brew install --cask msitarzewski/agency-agents/agency-agents

這也是 Agency Agents 主專案目前提供的快速安裝方式。

裝完後開啟 Agency Agents App。

不論是 Windows 還是 Mac，Agency Agents App 的介面都長得相同：

前端工程師可以先裝哪些 Agent？

Agency Agents 的角色很多，不建議看到什麼就全部裝，最後搞得像寶可夢一樣不全部收集完就睡不著。

以平常前端開發來說，可以先從這幾個開始：

Agent	適合工作
Frontend Developer	Vue、React、JavaScript、CSS、RWD
UI Designer	UI、Dashboard、Design System、版面設計
UX Researcher	UX、流程、資訊架構、易用性
Software Architect	系統架構、大型重構
Code Reviewer	PR、Code Review、Bug、Regression
Senior Developer	比較複雜的開發工作
DevOps Automator	Docker、CI/CD、Jenkins、部署
Minimal Change Engineer	修 Bug，而且不要順手就重構整個宇宙

安裝角色時，就可以直接選擇要裝在哪些 AI 上：

讓 Claude Code、Codex 自動選 Agent

Agency Agents 官方提供的是「角色」。

接下來這段則是自己另外加上的功能：

Agency Agents Router。

概念很簡單，我們再建立一個 Skill，專門負責判斷以下情境：

分析使用者需求 → 需要專家嗎？
需要專家 → 找最適合的 Agency Agent。
不需要專家 → 自己直接做。

就不會看到「Vue」三個字，就一定叫 Frontend Developer。

所以 Router 要判斷的是：這個工作有沒有必要使用專家。

例如：

「把 margin-top 20px 改成 24px」→ 不用 Agent。

「重新設計整個後台，考慮 RWD 與無障礙」→ 用 Agent。

Claude Code、Codex 建立 agency-agents Skill

Claude Code、Codex 的 Skill 放置位置不同。

Claude Code

Mac：

終端機輸入：

open ~/.claude/skills

Windows：

開啟任一個資料夾，檔案路徑輸入：

%USERPROFILE%\.claude\skills\

接著新增以下資料夾跟檔案：

agency-agents
└── SKILL.md

Codex

Mac：

open ~/.agents/skills

Windows：

%USERPROFILE%\.agents\skills\

同樣建立：

agency-agents
└── [SKILL.md](http://skill.md/)

接著 SKILL.md 的內容，Claude Code、Codex 有一點不同，可以各自複製貼上。

Claude Code

https://github.com/letswritetw/agency-agents-skill/blob/main/claude/SKILL.md

Codex

https://github.com/letswritetw/agency-agents-skill/blob/main/codex/SKILL.md

讓 Claude Code 自動使用 Router

Skill 建好後其實就可以用了，Claude Code 會依照 description 判斷什麼時候載入。

不過如果要讓 AI 更積極一點想到 Agency Agents Router，需要再到全域 CLAUDE.md 補一段規則。

打開 CLAUDE.md 檔的方式如下。

Mac：

終端機輸入：

open ~/.claude/CLAUDE.md

Windows：

開啟任一個資料夾，檔案路徑輸入：

%USERPROFILE%\.claude\CLAUDE.md

在打開的 CLAUDE.md 中加入：

## Agency Agents

For development tasks that would materially benefit from specialist expertise, use the `agency-agents` skill to select and delegate to the most appropriate installed Agency Agent.

Prefer using the `agency-agents` skill automatically when the current task clearly matches its purpose. The user should not need to explicitly request the skill.

Use the minimum number of agents necessary.

Prefer direct execution for simple or mechanical tasks.

Do not delegate unless specialist expertise is likely to materially improve correctness, design quality, architecture, maintainability, reliability, performance, accessibility, or review quality.

Do not expand the requested scope merely because additional agents are available.

The user's original requirements, constraints, and project conventions always take priority over agent routing.

之後平常就不用輸入：

Use agency-agents.

直接講需求即可。

Codex 的 AGENTS.md

Codex 也可以在自己的 AGENTS.md 補上 Router 使用規則。

Mac：

終端機輸入：

open ~/.codex/AGENTS.md

Windows：

開啟任一個資料夾，檔案路徑輸入：

%USERPROFILE%\.codex\AGENTS.md

在打開的 AGENTS.md 中加入：

<!-- AGENCY_AGENTS_START -->

## Agency Agents

For software development tasks that would materially benefit from specialist expertise, use the `agency-agents` skill to select and delegate to the most appropriate installed custom agent.

When the current task clearly matches the `agency-agents` skill description, prefer implicit invocation instead of requiring the user to explicitly request `$agency-agents`.

Use the minimum number of agents necessary.

Prefer direct execution for simple or mechanical tasks.

Do not delegate unless specialist expertise is likely to materially improve correctness, design quality, architecture, maintainability, reliability, performance, accessibility, or review quality.

For tasks spanning multiple disciplines, let the `agency-agents` skill determine whether sequential delegation is useful.

Do not expand the requested scope merely because additional agents are available.

The user's original requirements, constraints, project conventions, and requested scope remain the source of truth.

<!-- AGENCY_AGENTS_END -->

總結

Agency Agents 裡面有一堆角色可以使用，目前 August 還在實驗中，看是不是在開發上會產生更精緻的結果。

記得幾年前 ChatGPT 剛出來時，網路上有很多人在分享怎麼寫 Prompt，很多開頭的第一句都是寫「請你扮演 XXX」。

這件事情現在已經不用了，因為已經可以讓 AI 自己選擇適合的角色來扮演。

這個 Agency Agents 專案目前有 143k 的星星數，看來懶惰的人類是很多的（誤），只好再放一次貓咪怎麼看我們人類的圖：

Buzz 自架教學：使用 Docker 架設 Relay 與設定 AI Agent 自動回覆

Let's Write — Fri, 31 Jul 2026 14:38:33 +0000

寫在文章之前，關於本文配圖

這篇文章的配圖，選擇了熊本城，是因為這周發生了熊本大地震，而 August 在今年的五月才去那裡旅遊過。

記得在逛熊本城的時候，裡面有個影片，是在講十年前的熊本大地震發生後，這幾年一路是怎麼走過來，一路又修復成目前的樣子。

雖然，這次又發生了地震，但相信熊本可以再站起來的。

本篇要解決的問題

最近一直在找一個可以把 AI Agent 一起加入到群組聊天的通訊軟體。

大部份都要錢，比如 Slack、Google Chat、Teams。

剛好不知怎麼回事，最近也常常看到講 AI 的電子報提到一個 Buzz，似乎可以解決這需求。

Buzz，是一套可自架的團隊協作工具。除了頻道聊天，也能加入 Codex、Claude Code 等 AI Agent，讓團隊成員直接在頻道中透過 tag Agent 來呼叫 AI。

雖說官方提供了 Self Hosting 的安裝說明，但實際上還是踩了幾個坑才順利的讓 Agent 回覆訊息。

本篇就是筆記實作安裝 Buzz 時的筆記，也把怎麼跳過這些坑的方式紀錄下來，讓看到這篇的你可以從從容容、遊刃有餘的閃過。

完成本文後，可以做到：

在 Mac 上透過 Docker Compose 自架 Buzz Relay。
使用 Buzz Desktop 連接自己的 Relay。
建立 Buzz Community 與頻道。
啟動內建的三個 Agent。
使用 Codex 作為 Fizz 的 AI 執行環境。（也可以用 Claude）
在頻道中透過 @Fizz 讓 Agent 回覆訊息。

安裝 Buzz Relay

1. 安裝必要工具

需要先安裝好以下：

Git
Docker Desktop
Docker Compose 2.24.4 以上

確認 Docker Desktop 已經啟動後，再繼續安裝。

2. 下載 Buzz 原始碼

Clone 官方 GitHub 上的專案：https://github.com/block/buzz

接著進到「deploy/compose」資料夾中，本篇會用 Docker 的方式安裝。

3. 建立 `.env`

deploy/compose 的資料夾裡有一個「.env.example」，這份檔另存為「.env」。

接著，把 .env 裡「buzz.example.com」、「CHANGE_ME…」的部份全都修改，變成我們要的內容。

另外要注意，目前官方的版本有個 bug，主要是Buzz Relay 容器會顯示 unhealthy，造成後續安裝不起來，目前解決的方式就是：

# 原本
BUZZ_GIT_CONFORMANCE_PROBE=true

# 改成
BUZZ_GIT_CONFORMANCE_PROBE=false

需要 KEY 的部份，可以使用以下指令產生隨機密鑰：

openssl rand -hex 32

產生一般密碼：

openssl rand -base64 24

不同用途的密鑰應分開產生，不要全部使用同一組。

如果覺得一行行修改很麻煩，這一步 ChatGPT 有給了一組指令，直接專案內開啟終端機執行以下也行：

cat > .env <<EOF
BUZZ_IMAGE=ghcr.io/block/buzz:main

BUZZ_DOMAIN=127.0.0.1
RELAY_URL=ws://127.0.0.1:3300

BUZZ_MEDIA_BASE_URL=http://127.0.0.1:3300/media
BUZZ_MEDIA_SERVER_DOMAIN=127.0.0.1

BUZZ_CORS_ORIGINS=tauri://localhost,http://tauri.localhost,https://tauri.localhost,http://127.0.0.1:3300

BUZZ_REQUIRE_AUTH_TOKEN=false
BUZZ_REQUIRE_RELAY_MEMBERSHIP=false
BUZZ_ALLOW_NIP_OA_AUTH=false

BUZZ_AUTO_MIGRATE=true
BUZZ_GIT_CONFORMANCE_PROBE=false

RUST_LOG=buzz_relay=info,buzz_db=info,buzz_auth=info,buzz_pubsub=info,tower_http=info

BUZZ_RELAY_PRIVATE_KEY=$(openssl rand -hex 32)
BUZZ_GIT_HOOK_HMAC_SECRET=$(openssl rand -hex 32)

POSTGRES_DB=buzz
POSTGRES_USER=buzz
POSTGRES_PASSWORD=$(openssl rand -hex 16)

REDIS_PASSWORD=$(openssl rand -hex 16)

BUZZ_S3_ACCESS_KEY=$(openssl rand -hex 10)
BUZZ_S3_SECRET_KEY=$(openssl rand -hex 16)
BUZZ_S3_BUCKET=buzz-media
BUZZ_S3_ADDRESSING_STYLE=path

BUZZ_HTTP_PORT=3300
EOF

因為 3000 是個很多應用程式都會預設使用的 PORT，所以上面的範例改用 3300。

4. 啟動 Buzz Relay

專案中開啟終端機，依序執行以下：

加入執行權限：

chmod +x run.sh

啟動：

./run.sh start

查看狀態：

./run.sh status

正常情況下會看到：

relay       healthy
postgres    healthy
redis       healthy
minio       healthy

5. 測試 Relay

打開瀏覽器，網址貼上：http://127.0.0.1:3300。

成功的話就會看到結果：

順便推薦一下本站開發的擴充功能 Let’s JSON，網址如果回傳的是 JSON，就會看到像上面截圖那樣美美的樣子。

Buzz Relay 安裝成功，剩下的事就是讓各個要使用的團隊成員電腦安裝 Buzz，然後設定抓我們自架的 Buzz Relay 了。

下載、安裝 Buzz

1. 下載 Buzz Desktop

前往 Buzz Releases：

https://github.com/block/buzz/releases

Apple Silicon Mac，例如 M1、M2、M3、M4，下載名稱包含以下文字的版本：

aarch64

Intel Mac 則下載：

x64

Windows 下載：

Buzz_0.5.2_x64-setup_alpha-unsigned.exe

但因為 Windows 版本的 Buzz 目前尚未完成數位簽章，開啟時系統會跳出安全性警告；此時可點擊「更多資訊」並選擇「仍要執行」（或於檔案屬性中勾選「取消封鎖」）即可完成安裝。

2. 登入 Buzz

安裝完 Buzz，打開後會遇到幾個項目，因為 Relay 我們是自架的，因此以下選項要這樣選擇。

Join or create a community：選擇「I already have a community」。

Reconnect to your community：選擇「I’m a member or admin」。

接著會需要輸入我們 Buzz Relay 的網址，之前的 .env 裡寫的是 http://127.0.0.1:3300，這邊就照填，如果上面你有自行修改的話，這邊就填寫你修改的。

以上，就可以進到我們自架的 Buzz 了。

使用 AI Agents 功能

這段就是 August 一直踩坑的部份，只要下列幾個坑都閃過，之後在對話框裡 @ AI Agents 就會得到回應。

確認有使用 AI

本機確定有安裝好 Claude CLI，或 Codex CLI。

如果沒有訂閱這兩家方案，也可以找網路上提供有免費額度的 LLM 來使用。

August 因為 Claude、ChatGPT 都有付費訂閱，所以示範的是這兩家的。

在 Buzz 的設定頁裡，要確認有使用 AI，如圖：

顯示為「Ready」代表有連結成功。

Buzz Agent 指的是用各家的 API。

確認 Community 網址相同

點擊左下角自己的帳號，接著「Local Dev > Community settings」：

裡面會看到一個設定是「Relay URL」：

要確認 URL 裡，ws:// 後的網址，跟我們的網址是相同的，比方上面在設定 Community 的網址是 http://127.0.0.1:3300，那這邊 ws:// 後就要是 127.0.0.1:3300。

這邊如果不相同，那 Agents 收到的來源就會不同，就會一直抓不到我們 @ 它們的訊息。

開放 Agents 接受回應

在 Agent 的設定畫面裡，點擊「Advanced」，裡面有一項「Who can talk to this agent」，要選成「Anyone」：

然後，上面的頁籤切到「Customize for this agent」，確認有選好要使用的模型：

最後，要確認 Agents 是運行中的：

實際測試

可以做一個簡單的測試，看 AI Agents 是不是會回應。

我們在預設建好的 Channel 裡，@ Agent 就行，就像我們在 LINE 上 @ 朋友們一樣。

成功的話，就會看到被 @ 的 Agent 正在思考中的訊息，也會對訊息回應 Emoji，思考完成，Agent 就會回覆訊息，如下圖：

小結

雖然可以把 AI Agents 加進聊天中，但 Windows 版的安裝比較麻煩。

而且，Codex、Claude Code 上都裝了很多習慣的 Skills，表面上 AI 是回說可以直接用，但輸入 / 或 $ 時沒有出現選項，也不知道到底有用 Skills 還是沒有。

只能說，Buzz 還是一個正在開發中的工具，看 GitHub 上的 Release 紀錄更新得很頻繁，再給它一點時間，它會更好的（？）。

Outline Wiki 自架教學（三）：Codex 串接 MCP

Let's Write — Fri, 24 Jul 2026 13:44:02 +0000

本篇要解決的問題

上一篇是 Outline + Claude，不一定每個人都有訂閱 Claude 方案，所以也提供 Codex 的方式。

跟著本篇一步步走，完成設定後，Codex 可以透過 MCP 呼叫 Outline 工具，執行很多好棒棒的事，例如：

搜尋或列出 Outline 文件
讀取、編輯文件集內的文件
建立文件集
移動文件
執行 MCP Server 已提供的其他 Outline 操作

Codex App、Codex CLI 與 IDE 擴充套件會共用 Codex 的 MCP 設定，因此設定完成後，不需要在每個客戶端重複設定。

前置準備

開始前，請先確認已具備以下環境：

安裝 Codex
安裝 Node.js
可正常連線的 Outline

建立 Outline API Token

進入喜好設定

登入 Outline 後，點擊左下角帳號旁的「⋯」，再選擇「喜好設定」。

開啟 API & Access

在左側設定選單中選擇「API & Access」，接著點擊右上角的「新 API 金鑰」。

設定金鑰名稱、範圍與到期日

建議輸入容易辨識用途的名稱，例如：「AI MCP」、「Codex MCP」等等。

原始流程中的設定為：

範圍： 留空
到期日： 沒有期限

範圍留空通常代表不限制特定 API 權限。這種設定操作最簡單，但權限也較大。

複製 API Token

建立完成後，點擊「複製」，並先將 Token 暫存在安全的位置，因為 Token 只會出現一次。

注意：API Token 等同於帳號憑證，不要貼到 Git、公開文件、部落格文章、聊天群組或未加密的筆記中。

設定 Codex MCP

開啟 Codex 設定檔

Codex 使用 config.toml 儲存 MCP 與其他本機設定。

作業系統	使用者層級設定檔路徑
Windows	`%USERPROFILE%\.codex\config.toml`
macOS	`~/.codex/config.toml`

使用者層級的設定會套用到 Codex App、Codex CLI 與 IDE 擴充套件。

Windows

開啟 PowerShell，執行：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
New-Item -ItemType File -Force "$env:USERPROFILE\.codex\config.toml" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

這三個指令會依序：

建立 .codex 資料夾。
建立 config.toml。
使用記事本開啟設定檔。

也可以開啟任一個資料夾，在檔案路徑列貼上：

%USERPROFILE%\.codex

接著開啟 config.toml。

macOS：使用 Finder 開啟

開啟 Finder。
點擊上方選單的「前往」。
選擇「前往檔案夾⋯」。
貼上下列路徑：

~/.codex/

找到並開啟：

config.toml

macOS：使用終端機開啟

也可以在終端機執行：

mkdir -p "$HOME/.codex"
touch "$HOME/.codex/config.toml"
open -e "$HOME/.codex/config.toml"

這三個指令會依序建立設定資料夾、建立設定檔，並使用 macOS 文字編輯器開啟。

若檔案已存在，建議先複製一份備份，再進行修改。

加入 Outline MCP Server

請將下列設定加入 config.toml：

[mcp_servers.outline]
command = "npx"
args = [
  "-y",
  "mcp-remote",
  "https://192.168.x.x:3023/mcp",
  "--header",
  "Authorization:${AUTH_HEADER}"
]

[mcp_servers.outline.env]
AUTH_HEADER = "Bearer YOUR_OUTLINE_API_TOKEN"
NODE_TLS_REJECT_UNAUTHORIZED = "0"

請替換以下內容：

設定值	說明
`https://192.168.x.x:3023/mcp`	Outline MCP Server 的連線網址
`YOUR_OUTLINE_API_TOKEN`	前一步建立的 Outline API Token

使用有效 HTTPS 憑證時的簡化設定

如果 Outline MCP Server 已使用有效且受信任的 HTTPS 憑證，Codex 可以直接連線，不需要 Node.js、npx 或 mcp-remote。

[mcp_servers.outline]
url = "https://YOUR_MCP_HOST/mcp"
http_headers = { Authorization = "Bearer YOUR_OUTLINE_API_TOKEN" }

例如：

[mcp_servers.outline]
url = "https://outline-mcp.example.com/mcp"
http_headers = { Authorization = "Bearer YOUR_OUTLINE_API_TOKEN" }

這是較簡單的正式環境設定方式。

注意：這個範例會把 Token 直接寫在 config.toml 中。請妥善保護設定檔，不要提交到 Git。

Windows 與 macOS 的 npx 路徑問題

Codex App 原則上可以直接執行 npx。

若 MCP 啟動失敗，可能是桌面程式找不到 npx 的執行路徑。

Windows

在 PowerShell 執行：

where.exe npx

可能會回傳：

C:\Program Files\nodejs\npx.cmd

可以將：

command = "npx"

改成 TOML 的單引號字串：

command = 'C:\Program Files\nodejs\npx.cmd'

TOML 的單引號字串不需要將 Windows 反斜線寫成 \\。

macOS

在終端機執行：

which npx

Apple Silicon Mac 使用 Homebrew 時，可能回傳：

/opt/homebrew/bin/npx

Intel Mac 使用 Homebrew 時，可能回傳：

/usr/local/bin/npx

接著將：

command = "npx"

改成實際查到的完整路徑，例如：

command = "/opt/homebrew/bin/npx"

注意：不要直接照抄範例路徑，應先使用 where.exe npx 或 which npx，再填入自己電腦實際回傳的結果。

重新啟動 Codex

修改 config.toml 後，需要重新啟動正在使用的 Codex。

Codex App／ChatGPT 桌面版： 完整結束後重新開啟。
Codex CLI： 離開目前工作階段，再重新執行 codex。
IDE 擴充套件： 重新啟動擴充套件或重新載入編輯器視窗。

只關閉視窗不一定代表程式已完全結束：

Windows： 從系統匣結束程式，或到工作管理員確認是否仍在背景執行。
macOS： 按下 Command + Q，必要時到「活動監視器」確認程式是否仍在執行。

重新啟動時，Codex 會：

讀取 ~/.codex/config.toml
透過 npx 啟動 mcp-remote
使用 Authorization Header 連接 Outline MCP Server
載入 MCP Server 提供的工具

首次執行 npx -y mcp-remote 時，可能需要下載套件，因此等待時間會比後續啟動稍長。

測試 Outline MCP 是否連線成功

使用 Codex CLI 檢查

先執行：

codex mcp list

正常情況下，清單中會出現：

outline

也可以執行：

codex mcp --help

查看目前版本支援的 MCP 管理指令。

進入 Codex CLI 後，輸入：

/mcp

即可查看目前工作階段載入的 MCP Server 與工具。

使用對話測試

在 Codex 中輸入：

可以接到 Outline MCP 嗎？請列出目前可使用的 Outline 工具。

接著再測試實際讀取：

請列出 Outline 中目前可以看到的文件與文件集。

也可以指定操作：

請搜尋 Outline 中包含「前端」關鍵字的文件。

連線成功時，Codex 會顯示已載入 Outline 工具，並能回傳工作區中的文件或 Collection 資訊。

Outline Wiki 自架教學（二）：ClaudeCodex 串接 MCP

Let's Write — Fri, 24 Jul 2026 13:07:20 +0000

Outline Wiki 自架教學（二）：Claude 串接 MCP

本篇要解決的問題

上一篇我們自架了 Outline Wiki，接著我們就要發揮它的威力了，就是可以使用 MCP，讓 Claude、Codex 來幫我們新增、編輯、彙整……我們的文件。

本篇主要是寫 Outline + Claude，下一篇會是 Outline + Codex。

照著本篇實作，完成設定後，Claude Desktop 可以透過 MCP 呼叫 Outline 工具，例如：

搜尋或列出 Outline 文件
讀取、編輯文件集內的文件
建立文件集
移動文件
執行 MCP Server 已提供的其他 Outline 操作

前置準備

開始前，請先確認已具備以下環境：

安裝 Claude Desktop
安裝 Node.js
可正常連線的 Outline

建立 Outline API Token

進入喜好設定

登入 Outline 後，點擊左下角帳號旁的「⋯」，再選擇「喜好設定」。

從左下角選單進入喜好設定

開啟 API & Access

在左側設定選單中選擇「API & Access」，接著點擊右上角的「新 API 金鑰」。

進入 API & Access 並建立新 API 金鑰

設定金鑰名稱、範圍與到期日

建議輸入容易辨識用途的名稱，例如：「AI MCP」、「Claude MCP」等等。

原始流程中的設定為：

範圍： 留空
到期日： 沒有期限

設定 API 金鑰範圍與到期日

範圍留空通常代表不限制特定 API 權限。這種設定操作最簡單，但權限也較大。

複製 API Token

建立完成後，點擊「複製」，並先將 Token 暫存在安全的位置，因為 Token 只會出現一次。

複製 Outline API Token

注意：API Token 等同於帳號憑證，不要貼到 Git、公開文件、部落格文章、聊天群組或未加密的筆記中。

設定 Claude Desktop MCP

開啟 Claude Desktop 設定檔

Claude Desktop 在 Windows 與 macOS 使用相同的設定檔名稱，但存放路徑不同。

作業系統	設定檔路徑
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`

Windows

開啟任一個資料夾，檔案路徑列貼上：

%APPDATA%\Claude\claude_desktop_config.json

也可以按下 Win + R，貼上相同路徑後按 Enter。

macOS：使用 Finder 開啟

開啟 Finder。
點擊上方選單的「前往」。
選擇「前往檔案夾⋯」。
貼上下列路徑：

~/Library/Application Support/Claude/

找到並開啟：

claude_desktop_config.json

macOS：使用終端機開啟

也可以在終端機執行：

mkdir -p "$HOME/Library/Application Support/Claude"
touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

這三個指令會依序建立設定資料夾、建立設定檔，並使用 macOS 文字編輯器開啟。

若檔案已存在，建議先複製一份備份，再進行修改。

加入 Outline MCP Server

請將下列設定加入 JSON 最外層物件中的 mcpServers：

{
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://192.168.x.x:3023/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_OUTLINE_API_TOKEN",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

NODE_TLS_REJECT_UNAUTHORIZED=0 會停用 Node.js 的 TLS 憑證驗證。它只適合在可信任的內部網路中暫時測試，不建議用於公開網路或正式環境。較安全的做法是替 MCP Server 設定可被系統信任的有效憑證。

Windows 與 macOS 原則上可共用這份設定。如果 macOS 無法直接找到 npx，可以先在終端機執行：

which npx

假設回傳：

/opt/homebrew/bin/npx

便可將 command 改成完整路徑：

"command": "/opt/homebrew/bin/npx"

常見位置如下：

安裝方式	`npx` 可能的位置
Apple Silicon Mac 使用 Homebrew	`/opt/homebrew/bin/npx`
Intel Mac 使用 Homebrew	`/usr/local/bin/npx`
Node.js 官方 `.pkg`	以 `which npx` 的回傳結果為準

注意：不要直接照抄表格中的路徑。應先執行 which npx，再使用自己電腦實際回傳的結果。

請替換以下內容：

設定值	說明
`https://YOUR_MCP_HOST/mcp`	Outline MCP Server 的連線網址
`YOUR_OUTLINE_API_TOKEN`	前一步建立的 Outline API Token

例如 MCP Server 位於內部網路，可改成：

"https://192.168.x.x:3023/mcp"

合併既有設定時的注意事項

若 claude_desktop_config.json 已經有其他設定，不要直接覆蓋整份檔案，只需要把 mcpServers 合併進最外層物件。

Windows 設定範例

例如原本已有其他欄位：

{
  "coworkUserFilesPath": "C:\\Users\\Sean\\Claude",
  "preferences": {},
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR_MCP_HOST/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_OUTLINE_API_TOKEN",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

macOS 設定範例

macOS 也使用相同的 JSON 結構。若 npx 可直接執行：

{
  "preferences": {},
  "mcpServers": {
    "outline": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://YOUR_MCP_HOST/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_OUTLINE_API_TOKEN",
        "NODE_TLS_REJECT_UNAUTHORIZED": "0"
      }
    }
  }
}

若 Claude Desktop 找不到 npx，將 command 改成 which npx 查到的完整路徑，例如：

"command": "/opt/homebrew/bin/npx"

JSON 常見錯誤包括：

欄位之間少了逗號
最後一個欄位多了逗號
大括號或中括號數量不一致
Windows 路徑中的反斜線沒有寫成 \\
macOS 路徑含有空白時，終端機指令沒有使用引號或跳脫字元
把 mcpServers 貼到最外層物件之外

重新啟動 Claude Desktop

修改設定檔後，必須完整關閉 Claude Desktop，再重新開啟。

只關閉視窗不一定代表程式已完全結束：

Windows： 從系統匣結束 Claude，或到工作管理員確認 Claude 是否仍在背景執行。
macOS： 按下 Command + Q，或從上方選單選擇「Claude」→「結束 Claude」。必要時可到「活動監視器」確認程式是否仍在執行。

重新啟動時，Claude Desktop 會：

讀取 claude_desktop_config.json
透過 npx 啟動 mcp-remote
使用 Authorization Header 連接 Outline MCP Server
載入 MCP Server 提供的工具

首次執行 npx -y mcp-remote 時，可能需要下載套件，因此等待時間會比後續啟動稍長。

測試 Outline MCP 是否連線成功

重新開啟 Claude Desktop 後，可以輸入：

可以接到 Outline MCP 嗎？請列出目前可使用的 Outline 工具。

接著再測試實際讀取：

請列出 Outline 中目前可以看到的文件與文件集。

也可以指定操作：

請搜尋 Outline 中包含「前端」關鍵字的文件。

連線成功時，Claude 會顯示已載入 Outline 工具，並能回傳工作區中的文件或 Collection 資訊。

Outline Wiki 自架教學（一）：Docker 安裝、Gitea OIDC 與 AI 知識庫準備

Let's Write — Fri, 26 Jun 2026 13:49:09 +0000

Outline Wiki 自架教學（一）：Docker 安裝、Gitea OIDC 與 AI 知識庫準備

本篇要解決的問題

公司開發團隊裡，想架一套內部的知識庫，又要能支援 AI，常見的痛點有幾個：

文件資料留在自己的機器上，不對外，以免洩露商業機密。
想要加上 AI？得付 $$，比如 Notion，或是也可以自架的 Docmost。
Outline Wiki 裝起來很難，August 失敗過一次，最後是靠 Claude Opus 4.8 的輔助才成功。

本篇筆記文，會用一份 Docker Compose 檔，把 Outline，以及需要的 PostgreSQL、Redis、Caddy 全包進去，並針對上面這些坑一次閃掉。

另外也先說明本文裡的基本設定：

本機已裝好 Docker。
對內 PORT 是 3002，對外是 3001。

關於 Outline + AI 的補充說明：

自架版 Outline 沒有內建的「AI Answers」功能，網路上常看到的 OPENAI_API_KEY 對自架版是無效的。想要 Outline 加上 AI，正解是用 MCP 外接，讓 Claude / Codex 透過 Outline 的 API 來操作（作法將寫在下一篇）。

步驟 1：安裝 Gitea

第一個管理員帳號要用 Gitea 登入，所以得先有一台 Gitea。

Gitea 本身也能用 Docker 自架，這部分 August 之前寫過，直接看這篇：

安裝 Gitea。

只要你的 Gitea 已經能正常登入，就可以往下走。

Outline 並不限定 Gitea，任何相容 OIDC 的供應商（Keycloak、Authentik、Google⋯）都行，差別只在 OIDC_* 那幾個網址。

步驟 2：從 Gitea 取得 Client ID 與 Secret

Outline 走 OIDC 登入，需要在 Gitea 建立一個「OAuth2 應用程式」，拿到 Client ID 和 Client Secret。

進入 Gitea 後，到 設定（Settings）→ 應用程式（Applications），找到「管理 OAuth2 應用程式」區塊。

在 Gitea 的「設定 → 應用程式」頁面，找到「管理 OAuth2 應用程式」的建立表單

需要填兩個欄位：

應用程式名稱：填一個自己記得註是做什麼的名稱，如：Outline Wiki Login。
重新導向 URI：要填的 PORT 是有對外加上憑證，比如本篇用的是 3001。

https://<你的IP或網域>:3001/auth/oidc.callback

例如主機 IP 是 192.168.11.111，就填 https://192.168.11.111:3001/auth/oidc.callback。這個 IP 與埠號要跟等一下 Compose 裡的 URL= 完全一致。

Gitea OAuth2 應用程式表單，填入應用程式名稱與重新導向 URI（重點是 Redirect URI 結尾為 /auth/oidc.callback）

按下「建立應用程式」後，Gitea 會顯示 Client ID 與 Client Secret。

Gitea 建立完成後顯示的 Client ID 與 Client Secret 畫面。

要注意，Client Secret 只會完整顯示這一次，先複製存好。等一下要填進 Compose 的 OIDC_CLIENT_ID 與 OIDC_CLIENT_SECRET。

步驟 3-1：安裝 Outline Wiki：Windows 版

Windows 用 Docker Desktop，這裡用具名 volume（由 Docker 管理）存附件，啟動最單純。

先新增一個空資料夾，接著我們要放進下面的 2 個檔案。

Caddyfile

資料夾內新增一個檔案，檔名：Caddfile。

Caddyfile 負責「對外用 HTTPS、把流量轉給 Outline」。

檔案內容複製貼上以下，再把 192.168.11.111 換成我們 Windows 主機的區網 IP：

{
  default_sni 192.168.11.111
}

192.168.11.111:3001 {
  tls internal
  reverse_proxy outline:3002
}

tls internal：Caddy 自己簽一張憑證。因為我們用的是區網 IP，本來就申請不到正式憑證，自簽夠用。
3001 是對外埠、outline:3002 是 Outline 容器內部埠，兩者分工，注意不能寫成一樣。

docker-compose.yml

資料夾內再新增一個檔案，檔名：docker-compose.yml。

檔案內容複製貼上以下：

# =============================================================================
# Outline Wiki — Docker Compose 教學範例
# =============================================================================
# 架構：
#   outline   → 主應用 (Node.js)
#   caddy     → 反向代理 + 自動 HTTPS
#   postgres  → 資料庫
#   (外部)    → Redis，負責快取 / WebSocket / 背景工作佇列
#
# ⚠️ 發佈前務必把所有 <...> 佔位符換成你自己的值。
#    範例裡的密鑰、密碼、IP 全是假的，不要直接拿去用。
# =============================================================================

services:
  # ---------------------------------------------------------------------------
  # Outline 主應用
  # ---------------------------------------------------------------------------
  outline:
    image: outlinewiki/outline:latest
    container_name: outline
    restart: unless-stopped
    environment:
      - NODE_ENV=production

      # --- 安全密鑰 (必填) ---------------------------------------------------
      # 兩把都要用 32-byte 隨機 hex 字串。產生方式:
      #   openssl rand -hex 32
      # ⚠️ 換掉後不要再改，改了會讓既有 session / 加密資料失效。
      - SECRET_KEY=<openssl rand -hex 32 產生>
      - UTILS_SECRET=<openssl rand -hex 32 產生>

      # --- 資料庫連線 (必填) -------------------------------------------------
      # 格式：postgres://帳號:密碼@主機:埠/資料庫名
      # 主機名 postgres = 下面那個 service 名稱，Docker 內部 DNS 解析。
      - DATABASE_URL=postgres://outline_user:<DB_密碼>@postgres:5432/outline
      - PGSSLMODE=disable   # 同一台 Docker 內部連線，不需 SSL

      # --- Redis 連線 (必填) -------------------------------------------------
      # 格式：redis://:密碼@主機:埠/DB編號
      # 這裡指向下面內建的 redis service，主機名 redis = service 名。
      - REDIS_URL=redis://redis:6379/1

      # --- 對外網址 (必填) ---------------------------------------------------
      # 使用者瀏覽器看到的完整網址，要跟 Caddy / 反代對外位置一致。
      - URL=https://<你的網域或IP>:8443
      - PORT=3019            # 容器內部監聽埠 (給 Caddy 反代用,不直接對外)
      - FORCE_HTTPS=false    # HTTPS 由 Caddy 處理，這裡關掉避免重導迴圈

      # --- 檔案儲存 (必填) ---------------------------------------------------
      # local = 存本機磁碟 (搭配下面 volumes)。也可改 s3 接物件儲存。
      - FILE_STORAGE=local
      - FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data
      # 上傳/匯入大小上限 (bytes)。預設約 1MB,匯入大 zip (如從
      # Docmost/Notion 匯出) 會跳「file too large」。調大解決。
      # 算法: MB × 1048576。下面 = 250MB。
      - FILE_STORAGE_UPLOAD_MAX_SIZE=262144000            # 附件上限
      - FILE_STORAGE_IMPORT_MAX_SIZE=262144000            # 單篇匯入
      - FILE_STORAGE_WORKSPACE_IMPORT_MAX_SIZE=262144000  # zip 整包匯入 (關鍵)

      # --- 登入: Gitea OIDC (選填) -------------------------------------------
      # 任何相容 OIDC 的供應商都行 (Gitea / Keycloak / Authentik / Google...)。
      # client id/secret 從你的 OIDC 供應商後台拿。
      - OIDC_CLIENT_ID=<OIDC_CLIENT_ID>
      - OIDC_CLIENT_SECRET=<OIDC_CLIENT_SECRET>
      - OIDC_AUTH_URI=http://<OIDC主機>/login/oauth/authorize
      - OIDC_TOKEN_URI=http://<OIDC主機>/login/oauth/access_token
      - OIDC_USERINFO_URI=http://<OIDC主機>/login/oauth/userinfo
      - OIDC_USERNAME_CLAIM=preferred_username   # 用哪個欄位當帳號
      - OIDC_DISPLAY_NAME=Gitea                   # 登入按鈕顯示文字
      - OIDC_SCOPES=openid profile email

      # --- SMTP 寄信 (選填) --------------------------------------------------
      # 用途：magic-link 登入信 + 通知信。
      # Gmail 範例：密碼要用「應用程式密碼」，不是帳號密碼。
      # (Google 帳號 → 安全性 → 兩步驟驗證 → 應用程式密碼)
      - SMTP_HOST=smtp.gmail.com
      - SMTP_PORT=587
      - SMTP_SECURE=false    # 587 用 STARTTLS，所以這裡 false
      - SMTP_USERNAME=<你的gmail@gmail.com>
      - SMTP_PASSWORD=<Gmail 應用程式密碼>
      - SMTP_FROM_EMAIL=<你的gmail@gmail.com>
      - SMTP_REPLY_EMAIL=<你的gmail@gmail.com>

    volumes:
      # 用具名 volume，由 Docker 管理。注意：這裡存的是「附件/上傳檔」
      # (圖片、PDF...)，不是文章本體。文章內容存在 PostgreSQL，不是 .md 檔。
      - outline_data:/var/lib/outline/data
    depends_on:
      postgres:
        condition: service_healthy   # 等 DB 健康檢查通過才啟動 outline
      redis:
        condition: service_healthy   # 等 Redis 就緒

  # ---------------------------------------------------------------------------
  # Redis — 快取 / WebSocket / 背景工作佇列 (內建獨立 service)
  # ---------------------------------------------------------------------------
  redis:
    image: redis:7-alpine
    container_name: outline_redis
    restart: unless-stopped
    volumes:
      - redis_data:/data   # 持久化 (選用,Outline 主要當快取，掉了也能重建)
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]   # 回 PONG 才算就緒
      interval: 10s
      timeout: 5s
      retries: 5

  # ---------------------------------------------------------------------------
  # Caddy — 反向代理，自動處理 HTTPS 憑證
  # ---------------------------------------------------------------------------
  caddy:
    image: caddy:2
    container_name: outline_caddy
    restart: unless-stopped
    ports:
      - "8443:8443"   # 對外開的埠 (主機：容器)。實際反代規則寫在 Caddyfile。
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro   # :ro = 唯讀掛載
      - caddy_data:/data       # 存 TLS 憑證，別刪，刪了要重新申請
      - caddy_config:/config
    depends_on:
      - outline

  # ---------------------------------------------------------------------------
  # PostgreSQL
  # ---------------------------------------------------------------------------
  postgres:
    image: pgvector/pgvector:pg16
    container_name: outline_postgres
    restart: unless-stopped
    environment:
      # 這三個要跟上面 DATABASE_URL 裡的帳號/密碼/DB名一致。
      - POSTGRES_USER=outline_user
      - POSTGRES_PASSWORD=<DB_密碼>
      - POSTGRES_DB=outline
    volumes:
      - pg_data:/var/lib/postgresql/data   # 資料庫實體資料，千萬別誤刪
    ports:
      # 只綁 127.0.0.1 = 僅本機可連，不對外曝露 DB。安全做法。
      - "127.0.0.1:5432:5432"
    healthcheck:
      # 確認 DB 真的可接受連線，outline 才會啟動 (見上面 depends_on)。
      test: ["CMD-SHELL", "pg_isready -U outline_user -d outline"]
      interval: 10s
      timeout: 5s
      retries: 5

# -----------------------------------------------------------------------------
# 具名 volume — 由 Docker 管理,容器刪掉資料還在。
# -----------------------------------------------------------------------------
volumes:
  outline_data:
  pg_data:
  redis_data:
  caddy_data:
  caddy_config:

接著要把所有 <...> 的部份換成自己的值，要改這幾項：

SECRET_KEY、UTILS_SECRET：開啟終端機，執行兩次 openssl rand -hex 32 產生 32-byte 隨機字串。沒有 openssl 的話，那就用 Claude、ChatGPT 等 AI，對話中讓它們生成 2 組使用。
DATABASE_URL 與 POSTGRES_PASSWORD：兩邊的密碼要一致。
URL：填 https://<你的IP>:3001，IP 要跟 Caddyfile 一樣。
OIDC_CLIENT_ID、OIDC_CLIENT_SECRET：填上一段從 Gitea 拿到的值。
OIDC_AUTH_URI / OIDC_TOKEN_URI / OIDC_USERINFO_URI：把 <OIDC主機> 換成 Gitea 網址。
（選填）SMTP：要寄邀請信 / magic-link 才需要填。

啟動

在 docker-compose.yml 所在資料夾開終端機：

docker compose up -d

第一次啟動 Outline 會自動跑資料庫遷移（migration），會需要多等個十幾秒。

看到 outline 正常起來後，瀏覽器打開 https://<你的IP>:3001。

瀏覽器會跳「您的連線不是私人連線 / 不安全」警告。

這是因為 tls internal 用的是自簽憑證，屬於正常現象。點「進階 → 繼續前往」就能進到 Outline。

進站後點 Continue with Gitea 用 Gitea 帳號登入，第一個登入的人就是管理員。

之後的成員，在 Outline 後台用 Email 邀請即可（這也是為什麼上面要設定 SMTP）。

步驟 3-2：安裝 Outline Wiki：Ubuntu 版

Ubuntu 版跟 Windows 版幾乎一樣，只有兩個差別：

附件改用 bind mount（./data）：附件直接落在專案資料夾，搬家 / 備份複製整個資料夾就帶走，不必像具名 volume 還要 tar 撈。
OIDC 的 Gitea 可以在另一台機器，只要這台 Ubuntu 連得到即可。

檔案

一樣是兩個檔案：docker-compose.yml 和 Caddyfile。

Caddyfile 內容（把 IP 換成你的 Ubuntu 主機 IP）：

{
  default_sni 192.168.11.111
}

192.168.11.111:3001 {
  tls internal
  reverse_proxy outline:3002
}

docker-compose.yml 的內容複製貼上以下：

# =============================================================================
# Outline Wiki — Ubuntu 單主機部署版 (教學範例)
# =============================================================================
# 跟 Windows 版的差異：
#   1. 內建 Redis service — 不依賴外部 Redis 主機，一台 Ubuntu 全包。
#   2. 全部服務同一台主機，對外只露 Caddy 的 8443。
#   3. OIDC 仍可指向「另一台」Gitea/OIDC 主機，只要這台網路連得到。
#
# 架構：
#   outline   → 主應用 (Node.js)
#   redis     → 快取 / WebSocket / 背景佇列
#   caddy     → 反向代理 + 自動 HTTPS
#   postgres  → 資料庫
#
# ⚠️ 發佈前把所有 <...> 佔位符換成你自己的值。範例的密鑰/密碼/IP 全是假的。
#
# 部署步驟：
#   1. 整個資料夾複製到 Ubuntu (含 Caddyfile)。
#   2. 全域搜尋取代 <你的Ubuntu主機IP> → 實際 IP。
#   3. docker compose up -d
# =============================================================================

services:
  # ---------------------------------------------------------------------------
  # Outline 主應用
  # ---------------------------------------------------------------------------
  outline:
    image: outlinewiki/outline:latest
    container_name: outline
    restart: unless-stopped
    environment:
      - NODE_ENV=production

      # --- 安全密鑰 (必填) ---------------------------------------------------
      # 兩把都用 32-byte 隨機 hex。產生: openssl rand -hex 32
      # ⚠️ 換掉後別再改，改了會讓既有 session / 加密資料失效。
      - SECRET_KEY=<openssl rand -hex 32 產生>
      - UTILS_SECRET=<openssl rand -hex 32 產生>

      # --- 資料庫連線 (必填) -------------------------------------------------
      # 格式：postgres://帳號:密碼@主機:埠/資料庫名
      # 主機名 postgres = 下面的 service 名，Docker 內部 DNS 解析。
      - DATABASE_URL=postgres://outline_user:<DB_密碼>@postgres:5432/outline
      - PGSSLMODE=disable   # 同台 Docker 內部連線,不需 SSL

      # --- Redis 連線 (必填) -------------------------------------------------
      # ★ Ubuntu 版重點：指向「內建」redis service，主機名 redis = service 名。
      #   不像基本版要填外部 Redis IP/密碼。
      - REDIS_URL=redis://redis:6379/1

      # --- 對外網址 (必填) ---------------------------------------------------
      # 使用者瀏覽器看到的完整網址，要跟 Caddy 對外位置一致。
      - URL=https://<你的Ubuntu主機IP>:8443
      - PORT=3019            # 容器內部監聽埠 (給 Caddy 反向代理，不直接對外)
      - FORCE_HTTPS=false    # HTTPS 由 Caddy 處理，這裡關掉避免重導迴圈

      # --- 檔案儲存 (必填) ---------------------------------------------------
      - FILE_STORAGE=local
      - FILE_STORAGE_LOCAL_ROOT_DIR=/var/lib/outline/data
      # 上傳/匯入大小上限 (bytes)。預設約 1MB，匯入大 zip 會跳「file too large」。
      # 算法: MB × 1048576。下面 = 250MB。
      - FILE_STORAGE_UPLOAD_MAX_SIZE=262144000            # 附件上限
      - FILE_STORAGE_IMPORT_MAX_SIZE=262144000            # 單篇匯入
      - FILE_STORAGE_WORKSPACE_IMPORT_MAX_SIZE=262144000  # zip 整包匯入 (關鍵)

      # --- 登入: Gitea OIDC (選填) -------------------------------------------
      # 任何相容 OIDC 供應商皆可 (Gitea / Keycloak / Authentik / Google...)。
      # ★ Ubuntu 版注意：OIDC 主機可在「另一台」機器，確認這台 Ubuntu 連得到。
      - OIDC_CLIENT_ID=<OIDC_CLIENT_ID>
      - OIDC_CLIENT_SECRET=<OIDC_CLIENT_SECRET>
      - OIDC_AUTH_URI=http://<OIDC主機>/login/oauth/authorize
      - OIDC_TOKEN_URI=http://<OIDC主機>/login/oauth/access_token
      - OIDC_USERINFO_URI=http://<OIDC主機>/login/oauth/userinfo
      - OIDC_USERNAME_CLAIM=preferred_username   # 用哪個欄位當帳號
      - OIDC_DISPLAY_NAME=Gitea                   # 登入按鈕顯示文字
      - OIDC_SCOPES=openid profile email

      # --- SMTP 寄信 (選填) --------------------------------------------------
      # 用途：magic-link 登入信 + 通知信。
      # Gmail 範例：密碼要用「應用程式密碼」,不是帳號密碼。
      # (Google 帳號 → 安全性 → 兩步驟驗證 → 應用程式密碼)
      - SMTP_HOST=smtp.gmail.com
      - SMTP_PORT=587
      - SMTP_SECURE=false    # 587 用 STARTTLS，所以 false
      - SMTP_USERNAME=<你的gmail@gmail.com>
      - SMTP_PASSWORD=<Gmail 應用程式密碼>
      - SMTP_FROM_EMAIL=<你的gmail@gmail.com>
      - SMTP_REPLY_EMAIL=<你的gmail@gmail.com>

    volumes:
      # 存的是「附件/上傳檔」(圖片、PDF...)，不是文章本體 (文章在 PostgreSQL)。
      # ★ 用 bind mount: 附件直接落在專案資料夾 ./data,搬家複製即帶走。
      #   對比 named volume (outline_data:) 要 tar 才能撈出，bind 好搬很多。
      #   注意：DB 不要 bind，DB 檔不能直接 copy，一律用 pg_dump 備份。
      - ./data:/var/lib/outline/data
    depends_on:
      postgres:
        condition: service_healthy   # 等 DB 健康檢查通過才啟動
      redis:
        condition: service_healthy   # 等 Redis 就緒

  # ---------------------------------------------------------------------------
  # Redis — 內建獨立 service (★ Ubuntu 版才有,基本版用外部 Redis)
  # ---------------------------------------------------------------------------
  redis:
    image: redis:7-alpine
    container_name: outline_redis
    restart: unless-stopped
    volumes:
      - redis_data:/data   # 持久化 (選用，Outline 主要當快取，掉了也能重建)
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]   # 回 PONG 才算就緒
      interval: 10s
      timeout: 5s
      retries: 5

  # ---------------------------------------------------------------------------
  # Caddy — 反向代理，自動處理 HTTPS 憑證
  # ---------------------------------------------------------------------------
  caddy:
    image: caddy:2
    container_name: outline_caddy
    restart: unless-stopped
    ports:
      - "8443:8443"   # 對外唯一開的埠 (主機:容器)。反代規則寫在 Caddyfile。
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro   # :ro = 唯讀掛載
      - caddy_data:/data       # 存 TLS 憑證，別刪，刪了要重新申請
      - caddy_config:/config
    depends_on:
      - outline

  # ---------------------------------------------------------------------------
  # PostgreSQL — pgvector 映像 (支援向量搜尋)
  # ---------------------------------------------------------------------------
  postgres:
    image: pgvector/pgvector:pg16
    container_name: outline_postgres
    restart: unless-stopped
    environment:
      # 這三個要跟上面 DATABASE_URL 的帳號/密碼/DB名一致。
      - POSTGRES_USER=outline_user
      - POSTGRES_PASSWORD=<DB_密碼>
      - POSTGRES_DB=outline
    volumes:
      - pg_data:/var/lib/postgresql/data   # 資料庫實體資料，千萬別誤刪
    ports:
      # 只綁 127.0.0.1 = 僅本機可連，不對外曝露 DB。安全做法。
      - "127.0.0.1:5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U outline_user -d outline"]
      interval: 10s
      timeout: 5s
      retries: 5

# -----------------------------------------------------------------------------
# 具名 volume — 由 Docker 管理，容器刪掉資料還在。
# -----------------------------------------------------------------------------
volumes:
  # outline_data 改用 bind mount (./data)，不在這裡宣告。
  pg_data:
  redis_data:
  caddy_data:
  caddy_config:

要修改的部份，如：密鑰、DB、OIDC、SMTP，都與 Windows 版填法完全相同。

啟動

在 docker-compose.yml 所在資料夾開終端機：

docker compose up -d

確認與登入流程跟 Windows 版一樣：瀏覽器打開 https://<你的IP>:3001，遇到憑證警告點「繼續前往」，再用 Gitea 登入。

結語

照著上面的步驟做，我們就會有一套 完全自架 + 免費 + 可以用 MCP 接上 AI 的 Outline Wiki。

怎麼用 MCP 接上 Claude、Codex，下一篇會說明。