開發工具 on KnightLi的博客

Obsidian 和 Joplin 怎麼選？Markdown 筆記工具對比指南

Sat, 30 May 2026 14:43:56 +0800

Obsidian 和 Joplin 都是 Markdown 筆記工具，但適合的人群不太一樣。

簡單說，Obsidian 更適合深度知識管理、雙鏈卡片盒筆記和高度自訂的使用者；Joplin 更適合注重資料隱私、需要全平台同步、偏向傳統資料夾分類和網頁剪藏的實用型使用者。

如果你想搭建「第二大腦」、寫長期研究筆記、折騰外掛和知識圖譜，優先看 Obsidian。如果你想找一個更安全、更自由的 Evernote / 有道雲筆記替代品，優先看 Joplin。

核心差異對比

對比維度	Obsidian	Joplin
開源屬性	閉源，個人免費，商業使用收費	完全開源，AGPL-3.0 license
資料儲存	本地 `.md` 純文字檔案	本地資料庫管理，筆記內容使用 Markdown
資料可控性	檔案直接在本地資料夾中，遷移和備份直觀	需要透過應用或匯出功能管理，但支援加密和同步
官方同步	Obsidian Sync，付費	Joplin Cloud，付費
免費同步	需要第三方方案，例如 iCloud、Git、堅果雲、Syncthing 等	內建支援 OneDrive、Dropbox、WebDAV、檔案系統等同步目標
核心優勢	雙向連結、知識圖譜、外掛生態、強自訂	網頁剪藏、端到端加密、跨平台同步、開源
組織方式	關係網路、雙鏈、標籤、資料夾	筆記本、子筆記本、筆記、標籤
上手體驗	功能強，但容易越用越複雜	更接近傳統筆記應用，上手更直接

資料管理與隱私

Obsidian 的特點是「檔案即資料」。你的筆記就是一個個普通 .md 檔案，直接保存在本地資料夾中。即使將來不用 Obsidian，也可以用任何文字編輯器打開這些檔案。

這種方式的優勢是直觀、開放、便於備份，也適合用 Git 管理。缺點是同步、附件管理和多端一致性需要使用者自己規劃。

Joplin 同樣使用 Markdown 語法，但筆記由應用資料庫管理。它的優勢是功能更完整，筆記、附件、標籤、同步狀態都由應用統一處理。Joplin 還原生支援端到端加密（E2EE），配合第三方網碟同步時，雲服務商也較難直接讀取筆記內容。

如果你更看重「我的筆記就是本地檔案」，Obsidian 更順手。如果你更看重「應用幫我管理同步、加密和附件」，Joplin 更省心。

同步方案與成本

Obsidian 的官方同步服務是 Obsidian Sync，體驗好，但需要付費。如果想免費在手機、平板和電腦之間同步，就要自己配置第三方方案，例如 iCloud、Git、Syncthing、堅果雲或其他 WebDAV 方案。這對熟悉檔案同步的人問題不大，但對新手有門檻。

Joplin 的同步更偏內建能力。它支援 Joplin Cloud，也支援 OneDrive、Dropbox、WebDAV、檔案系統等同步目標。只要綁定帳號或配置地址，就可以在多端之間同步筆記。

需求	更適合
願意為官方同步付費，想要省心體驗	Obsidian Sync 或 Joplin Cloud 都可以
想免費使用第三方網碟同步	Joplin 更直接
熟悉 Git / Syncthing / iCloud，並願意折騰	Obsidian 也很好用
希望同步時啟用端到端加密	Joplin 更內建

外掛生態與自訂

Obsidian 的外掛生態是它最強的部分之一。透過外掛，它可以變成任務看板、閃卡工具、日曆、思維導圖、個人資料庫，甚至接近一個本地知識系統。

雙向連結、反向連結、局部圖譜和 Dataview 這類外掛，能讓零散筆記逐漸形成知識網路。對寫書、研究、知識卡片、專案資料沉澱來說，這種能力非常有吸引力。

Joplin 也支援外掛、主題和一些連結能力，但生態豐富度和折騰空間不如 Obsidian。它的好處是更克制，不容易讓使用者把大量時間花在改介面、換主題和試外掛上。

如果你的目標是「深度自訂知識管理系統」，Obsidian 更強。如果你的目標是「穩定記錄、同步和搜尋」，Joplin 已經夠用。

網頁剪藏能力

網頁剪藏是 Joplin 的強項。它提供官方 Web Clipper，可以從瀏覽器保存網頁、簡化文章內容、截取頁面或保存連結。對於收集離線資料、保存技術文章和整理網頁內容的人來說，這個功能很實用。

Obsidian 原生網頁剪藏能力相對弱，通常需要依賴第三方瀏覽器擴充或其他工作流程。可用方案不少，但體驗和穩定性取決於外掛與網頁結構，剪藏後也可能需要手動整理排版。

場景	更適合
高頻保存網頁文章	Joplin
做離線資料庫	Joplin
只偶爾保存網頁連結	兩者都可以
保存後還要深度改寫、雙鏈整理	Obsidian

組織方式差異

Obsidian 更像一個以本地資料夾為基礎的知識網路。你可以用資料夾整理，也可以用標籤、雙鏈、反向連結和圖譜組織知識。它適合非線性筆記和主題之間關係複雜的知識庫。

Joplin 更像傳統筆記軟體。它採用筆記本、子筆記本、筆記的層級結構，也支援標籤。對習慣 Evernote、有道雲筆記、OneNote 這類工具的人來說，Joplin 的組織方式更熟悉。

偏好	推薦
喜歡資料夾 + 雙鏈 + 圖譜	Obsidian
喜歡筆記本 + 子筆記本 + 標籤	Joplin
做學術研究、寫書、卡片盒	Obsidian
做資料收集、專案筆記、網頁歸檔	Joplin

你應該選哪個

選擇 Obsidian，如果：

你在做長期研究、寫書、課程資料整理或個人知識庫。
你重視雙向連結、反向連結和知識圖譜。
你希望高度自訂介面、快捷鍵、外掛和工作流程。
你願意花時間折騰同步、外掛和檔案結構。
你希望筆記直接作為本地 Markdown 檔案存在。

選擇 Joplin，如果：

你想要一個開源、跨平台、可同步的傳統筆記應用。
你重視端到端加密和資料隱私。
你經常使用網頁剪藏保存文章。
你不想為基礎同步付費，也不想折騰複雜同步方案。
你更習慣筆記本、子筆記本、標籤這種傳統結構。

簡單結論

Obsidian 和 Joplin 不是誰絕對更好，而是設計目標不同。

Obsidian 更像一個可高度自訂的 Markdown 知識管理平台，適合願意搭系統、做雙鏈、玩外掛的人。它的上限很高，但也容易讓人陷入「搭建系統比寫筆記更開心」的狀態。

Joplin 更像一個開源、可同步、可加密的傳統筆記應用，適合想穩定記錄、網頁剪藏、多端同步和長期保存資料的人。它沒有 Obsidian 那麼強的雙鏈生態，但更接近「裝好就能認真記筆記」的工具。

一句話：想搭第二大腦，選 Obsidian；想要開源版 Evernote，選 Joplin。

Joplin：離線優先、支援同步和加密的開源筆記應用

Sat, 30 May 2026 14:39:48 +0800

Joplin 是一個開源筆記與待辦應用，支援 Windows、macOS、Linux、Android 和 iOS。它的定位不是輕量便箋，而是一個可以長期保存大量筆記、同步到多裝置，並盡量讓資料掌握在使用者手裡的知識管理工具。

Joplin 的筆記使用 Markdown 格式，支援筆記本、標籤、全文搜尋、附件、待辦事項、外掛、主題和瀏覽器 Web Clipper。對於想從 Evernote 遷移出來，或者想用更開放格式管理個人資料的人來說，它是很常見的選擇。

Joplin 解決什麼問題

很多筆記應用用起來方便，但資料容易被鎖在某個帳號、某個雲服務或某種私有格式裡。Joplin 的思路更偏開放：本地保留完整資料，筆記正文使用 Markdown，再透過使用者選擇的同步目標在多裝置之間同步。

它適合下面幾類需求：

想把筆記長期保存為 Markdown。
想在電腦和手機之間同步筆記。
想從 Evernote 匯入舊筆記和附件。
想使用端到端加密同步。
想用外掛和主題擴展筆記應用。
想把網頁內容快速剪藏到自己的筆記庫。

核心特性速查

特性	說明
開源	倉庫公開，專案長期維護，授權為 AGPL-3.0 license
跨平台	支援 Windows、macOS、Linux、Android、iOS
Markdown	筆記正文使用 Markdown，便於閱讀、遷移和長期保存
離線優先	本地始終保存資料，沒有網路也能查看和編輯
同步	支援多種同步目標，包括 Joplin Cloud、Nextcloud、Dropbox、OneDrive 等
端到端加密	同步時可以啟用 E2EE，降低雲端儲存風險
匯入	支援從 Evernote 匯入，也支援普通 Markdown 檔案匯入
擴展	支援外掛、主題和 Web Clipper

離線優先是什麼意思

Joplin 官方 README 中強調它是 “offline first”。這意味著筆記不是只存在於雲端，而是保存在本機或手機中。即使沒有網路，也能打開、搜尋和編輯已有筆記。

這個設計對筆記工具很重要。網路不好、同步服務臨時不可用，或者帳號服務出現問題時，本地仍然有完整資料。同步只是讓多裝置保持一致，而不是把所有使用體驗都綁定到雲端。

Markdown 與匯入能力

Joplin 的筆記使用 Markdown，這讓它比完全私有格式更容易遷移和備份。使用者可以直接匯入普通 Markdown 檔案，也可以從 Evernote 匯入筆記。

Evernote 匯入時，Joplin 會嘗試轉換格式化內容，並保留資源檔案，例如圖片和附件，同時保留建立時間、更新時間、地理位置等中繼資料。對有多年 Evernote 資料的人來說，這一點比單純複製文字更重要。

不過，任何跨應用遷移都不應該盲信「一鍵完成」。複雜排版、表格、附件、內部連結和標籤結構都建議先用少量樣本測試，再遷移完整資料庫。

同步與加密

Joplin 支援多種同步方式。常見選擇包括：

同步目標	適合場景
Joplin Cloud	想省心使用官方服務
Nextcloud	已經有自建雲或團隊協作環境
Dropbox	習慣使用 Dropbox 的個人使用者
OneDrive	使用 Microsoft 生態的使用者
檔案系統 / WebDAV 等	想自己控制同步位置的人

同步可以配合端到端加密使用。啟用後，筆記內容在同步到雲端前會先加密，雲服務更多只是保存加密後的資料。這樣可以降低第三方雲碟或同步服務洩露內容的風險。

加密也會帶來管理成本。使用者需要妥善保存密碼和恢復資訊，否則換裝置或重裝後可能無法解密舊筆記。

Web Clipper 與外掛

Joplin 還提供瀏覽器 Web Clipper，用來從 Chrome、Firefox 等瀏覽器保存網頁和截圖。對做資料收集、網頁剪藏和研究筆記的人來說，這是很實用的入口。

外掛和主題則讓 Joplin 更接近一個可擴展平台，而不是固定功能的筆記軟體。使用者可以根據自己的工作流程擴展編輯、展示、搜尋、匯入匯出等能力。

和 Obsidian 的區別

Joplin 和 Obsidian 都常被 Markdown 使用者拿來比較，但兩者側重點不同。

維度	Joplin	Obsidian
主要定位	開源筆記與待辦應用，內建同步方案和加密能力	本地 Markdown 知識庫，強調雙鏈、外掛生態和圖譜
資料組織	應用管理筆記本、標籤、附件和資料庫索引	直接圍繞資料夾和 Markdown 檔案工作
同步	內建多種同步目標和 E2EE	官方同步是付費服務，也可自行使用第三方同步
適合人群	想要開箱即用、跨端同步、兼顧隱私的人	想深度定制個人知識庫和本地檔案工作流程的人

如果你想要一個「開源版 Evernote + Markdown + 同步加密」，Joplin 更貼近這個需求。如果你想圍繞本地 Markdown 檔案搭建高度定制的知識系統，Obsidian 可能更順手。

適合誰使用

Joplin 適合幾類使用者：

想從 Evernote 遷移出來的人。
想把筆記保存為 Markdown 的使用者。
需要 Windows、macOS、Linux、Android、iOS 多端同步的人。
關心隱私，希望啟用端到端加密的人。
希望筆記軟體開源、可自託管、可長期遷移的人。
需要網頁剪藏和附件管理的人。

它不一定適合只想要極簡便箋的人。Joplin 功能較完整，配置同步、加密、外掛和匯入時，也需要花一點時間理解。

使用建議

如果你準備試用 Joplin，可以按這個順序開始：

先在桌面端建立一個測試筆記本。
匯入少量 Markdown 或 Evernote 樣本。
檢查圖片、附件、標籤、建立時間和格式是否正常。
再設定同步目標，例如 Joplin Cloud、Nextcloud、Dropbox 或 OneDrive。
如果要開啟端到端加密，先確認所有裝置都能正常同步和解密。
最後再遷移完整筆記庫。

這樣做比直接把多年筆記一次性匯入更穩，也方便在正式遷移前發現格式或同步問題。

我的判斷

Joplin 的優勢在於把幾個重要方向放在了一起：Markdown、開源、跨平台、離線優先、同步和端到端加密。它不只是一個寫 Markdown 的編輯器，更像一個面向長期使用的個人筆記系統。

如果你希望筆記資料盡量開放，又不想完全自己拼同步、加密和移動端應用，Joplin 是很值得試的選擇。它尤其適合從 Evernote 遷移、重視隱私、多裝置使用，並希望以後仍能把資料遷走的使用者。

專案連結：laurent22/joplin
官方文件：Joplin documentation

Jimmy：把 Evernote、Notion、Google Keep 等筆記匯出轉換成 Markdown

Sat, 30 May 2026 11:55:56 +0800

Jimmy 是一個筆記轉換工具，目標是把不同筆記應用或文件格式裡的內容轉換成 Markdown。它適合想把筆記從封閉應用裡遷出來、放進 Obsidian、Joplin，或者只想長期保存為純文字的人。

專案文件裡的定位很直接：匯出或備份原筆記應用的資料，運行 jimmy 轉換，再把結果匯入 Joplin、Obsidian，或者直接用 VSCode 等文字編輯器查看。

Jimmy 解決什麼問題

很多筆記應用都有自己的匯出格式。換應用時，最麻煩的往往不是文字內容，而是圖片、附件、標籤、內部連結和 front matter 這些結構化資訊。

Jimmy 做的事情就是把這些匯出資料盡量整理成更通用的 Markdown 目錄：

筆記正文轉換為 Markdown。
盡量保留圖片、資源和附件。
盡量保留標籤、外部連結和筆記內部連結。
輸出 Markdown + front matter。
結果可以匯入 Joplin、Obsidian 等工具，也可以直接用文字編輯器查看。

這類工具的意義在於降低遷移成本。筆記一旦變成 Markdown，就不再強綁定某個應用，後續備份、搜尋、版本管理和 LLM 處理都會簡單很多。

支援的筆記應用很多

Jimmy 支援的來源覆蓋面很廣，包括 Anki、Anytype、Bear、CherryTree、ColorNote、Day One、Diaro、Drafts、Dynalist、Evernote、Google Docs、Google Keep、Joplin、Notion、Obsidian、OneNote、QOwnNotes、RedNotebook、Reflect、Roam Research、Signal、Simplenote、Standard Notes、Synology Note Station、Telegram、Tiddlywiki、Turtl、UpNote、Wordpress、Zim、Zoho Notebook 等。

並不是所有來源的保真度都完全一樣。實際遷移時，仍然要先用一小批筆記試跑，重點檢查圖片、附件、標籤、內部連結和日期欄位是否符合預期。

也能轉換普通文件

除了筆記應用匯出，Jimmy 也能處理一些常見文件格式。文件中提到可以轉換單一檔案，也可以遞迴轉換整個資料夾，適合把雜亂的資料目錄整理成 Markdown。

常見支援格式包括：

類型	例子
辦公文件	DOCX、ODT、RTF
標記語言	Asciidoc、DocBook、Markdown、MediaWiki、reStructuredText
網頁與電子書	HTML、MHTML、EPUB
資料與結構化檔案	CSV、OPML、Jupyter Notebook
其他	PDF、EML、Fountain、txt2tags

如果只是把 DOCX、PDF 或 HTML 批量轉成 Markdown，Jimmy 也可以作為一個離線批次處理工具來用。

兩種使用方式

Jimmy 提供 CLI 和 TUI 兩種介面。

介面	適合場景	說明
CLI	批次處理、腳本、完整功能	適合一次性轉換資料夾、寫遷移腳本、指定來源格式
TUI	互動式轉換	適合手動操作，目前功能子集仍處於 beta 狀態

官方 README 給出的 Linux 示例命令如下：

# 使用互動式 TUI 轉換
jimmy-linux tui

# 轉換一個 pandoc 支援的單檔案
jimmy-linux cli libre_office_document.odt

# 轉換整個資料夾
jimmy-linux cli path/to/folder

# 轉換 Google Keep 匯出
jimmy-linux cli takeout-20240401T160516Z-001.zip --format google_keep

這些命令說明它不是只面向某一個筆記應用，而是把「筆記匯出包」和「普通文件目錄」都納入了同一套轉換流程。

它的幾個特點

特點	說明
離線運行	轉換過程不依賴雲服務，適合處理私人筆記
開源	倉庫採用 GPL-3.0 license
跨平台	官方提供 Linux、Windows、macOS 下載
獨立二進位檔	不要求使用者額外安裝 Docker、Python 或 Node.js
不使用 AI	轉換過程不調用 AI，結果更可控，也減少隱私顧慮
Markdown + front matter	方便匯入筆記軟體，也方便後續用 Git 管理

其中「離線」和「不使用 AI」很適合筆記遷移場景。筆記裡經常有私人資訊、工作資料和歷史附件，把轉換放在本地完成，會讓風險邊界更清楚。

適合誰使用

Jimmy 適合幾類人：

想從 Evernote、Notion、OneNote、Google Keep 等工具遷移到 Markdown 的使用者。
想把筆記匯入 Obsidian、Joplin 或其他純文字工作流的人。
想把長期資料保存為未來更容易讀取格式的人。
想把筆記或文件準備成 LLM 可處理文字的人。
需要遞迴轉換 DOCX、PDF、HTML、ODT 等資料夾內容的人。

它不一定適合追求「一鍵完美遷移」的使用者。不同筆記應用匯出格式差異很大，複雜頁面、資料庫、嵌入內容和內部連結都可能需要人工複查。

使用前的檢查建議

真正遷移前，建議按這個順序做：

先從原筆記應用匯出一小批樣本。
用 Jimmy 轉換樣本，而不是一上來轉換全部筆記。
檢查 Markdown 正文、圖片、附件、標籤、建立時間、內部連結。
確認目標應用，例如 Obsidian 或 Joplin，能正確識別目錄結構和 front matter。
再對完整匯出包執行轉換。
保留原始匯出包和轉換結果，至少等確認無誤後再清理。

這個流程雖然慢一點，但能避免遷移後才發現附件遺失、連結斷掉或標籤結構不對。

我的判斷

Jimmy 的價值在於把筆記遷移從「依賴某個應用的匯入器」變成「先轉成通用 Markdown」。它支援的來源很多，輸出也足夠通用，適合把個人知識庫從封閉格式裡釋放出來。

如果你只是偶爾匯出一兩篇筆記，可能用不到它。但如果你有多年積累的筆記、附件和文件目錄，想遷移到 Obsidian、Joplin 或 Git 管理的 Markdown 工作流，Jimmy 很值得試。它最適合做遷移中間層：先把資料變成可讀、可備份、可批次處理的文字，再決定放進哪個筆記系統。

專案連結：marph91/jimmy
文件連結：Jimmy - Note Conversion Tool

Google Pay 與 Wallet 推出 Developer MCP Server：把支付整合接入 AI 助手

Fri, 29 May 2026 15:24:18 +0800

Google Developers 發布了 Google Pay 與 Wallet Developer MCP Server。它面向正在整合 Google Pay API 和 Google Wallet API 的開發者，把官方文件、帳號狀態、整合校驗和部分業務指標接入 MCP 相容的 AI 開發工具。

這類更新看起來不像模型發布那麼熱鬧，但對開發者很實用。支付和錢包整合往往不是「會不會寫程式碼」的問題，而是文件細節多、設定項多、審核要求多、錯誤回饋分散。MCP Server 的價值就在於讓 AI 助手可以在更接近真實上下文的位置幫開發者排查問題。

它解決什麼問題

開發者在接入 Google Pay 或 Google Wallet 時，通常要在多個地方來回切換：

查官方文件和範例程式碼
確認帳號與商戶設定
檢查請求參數和返回錯誤
驗證整合是否符合要求
觀察呼叫表現和關鍵指標

如果只把這些內容當成網頁文件，AI 助手最多只能解釋概念或生成範例。接入 MCP Server 後，助手可以透過工具存取更具體的資訊，從而給出更貼近目前專案狀態的建議。

MCP 在這裡為什麼合適

MCP 的作用是給 AI 應用提供標準化工具介面。對 Google Pay 和 Wallet 這樣的開發者產品來說，它非常適合處理「文件加狀態加校驗」的組合任務。

例如，開發者可以讓支援 MCP 的 AI 工具幫助回答：

目前整合缺了哪些設定
某個 Google Pay 請求為什麼失敗
Wallet pass 定義裡哪些欄位可能不符合要求
程式碼範例應該如何改成目前業務需要的形態
整合上線前還需要檢查哪些項目

這些問題如果只靠大模型記憶，風險很高；如果能結合官方工具和目前帳號資訊，回答就更可操作。

對 AI 程式設計工作流的意義

這次發布也說明一個趨勢：AI 程式設計助手正在從「讀程式碼」走向「讀產品系統」。

過去，開發者讓 AI 幫忙整合支付能力，通常只能把文件片段、錯誤日誌和程式碼貼進去。AI 可以解釋，但不一定知道目前整合的真實狀態。MCP Server 把這部分能力向前推進了一步，讓 AI 助手有機會直接圍繞產品整合環境工作。

這對幾類場景尤其有價值：

新專案首次接入 Google Pay 或 Wallet。
舊專案遷移到新的 API 或設定方式。
上線前做整合檢查。
遇到錯誤碼、審核問題或設定不一致時快速定位。

對團隊來說，收益不只是少查幾頁文件，而是減少「文件理解正確，但設定現場不一致」的摩擦。

它不會替代開發者判斷

支付和錢包相關整合有安全、合規和使用者體驗要求。MCP Server 可以幫助 AI 助手更快找到資訊、檢查狀態、生成建議，但最終仍需要開發者確認程式碼、安全策略、商戶設定和上線流程。

尤其是支付鏈路，不能因為 AI 給出一個看似合理的建議就直接上線。更穩妥的方式是把 MCP 工具當成檢查員和導航員：它能縮短定位時間，但不能替代審核、測試和業務責任。

我的判斷

Google Pay 與 Wallet Developer MCP Server 的意義不在於「又多了一個 MCP 範例」，而在於它把 MCP 放進了一個真實、複雜、強約束的開發者場景。

如果 MCP 只連接文件，它的價值有限；如果它能連接帳號狀態、整合校驗、指標和產品後台，AI 助手就能承擔更多實際開發工作。Google 這次發布正好展示了這個方向。

未來類似能力很可能會出現在更多雲端服務、廣告平台、支付系統和企業 SaaS 裡。開發者要適應的不是「AI 會寫程式碼」，而是「AI 可以透過標準工具介面參與整個整合流程」。

原文連結：Supercharge your integration workflow with the Google Pay & Wallet Developer MCP Server

Remotion：用 React 以程式化方式生成影片

Wed, 27 May 2026 14:39:22 +0800

remotion-dev/remotion 是一個用 React 以程式化方式建立影片的框架。它把影片製作從傳統時間軸工具裡抽離出來，變成可以用元件、狀態、資料、API、CSS、Canvas、SVG、WebGL 和演算法控制的前端工程問題。

專案地址：remotion-dev/remotion

這類工具很適合今天的 AI 編程工作流程：如果一個 agent 能生成網頁、圖表和資料視圖，它也可以繼續生成影片腳本、動畫元件和可渲染的短片。

Remotion 解決的是什麼問題

傳統影片工具擅長人工剪輯，但不擅長規模化、參數化和自動化。

例如這些任務：

為每個使用者生成一支個人化年度回顧影片
根據資料庫自動生成產品示範影片
把圖表、程式碼片段和講解字幕組合成技術短片
批次生成行銷素材、社群媒體短影片或課程片段
用 CI/CD 或後端服務按需渲染影片

如果使用傳統剪輯軟體，這些任務很難完全自動化。Remotion 的做法是把影片當成 React 應用來寫：每一幀都是元件和資料在某個時間點的結果。

為什麼是 React

Remotion README 裡給出的理由很清楚：React 可以複用 Web 技術和元件化能力。

它讓你可以使用：

CSS 做版面配置和動畫
SVG 做向量圖形
Canvas 和 WebGL 做複雜繪製
JavaScript / TypeScript 做變數、函式、API 呼叫、數學和演算法
React 元件做複用、組合和快速迭代

這意味著前端開發者不需要重新學習一套完全陌生的影片 DSL。許多既有的 UI、圖表、設計系統和資料邏輯，都可以遷移到影片生成場景裡。

快速開始

如果已經安裝 Node.js，README 給出的入口命令是：

`1`	`npx create-video@latest`

建立專案後，你通常會撰寫 React 元件來描述畫面，再讓 Remotion 逐幀渲染輸出影片。

更完整的文件可以看：

文件：remotion.dev/docs
API Reference：remotion.dev/api

它適合哪些場景

Remotion 最適合「影片內容由資料或程式碼驅動」的場景。

個人化影片

例如年度回顧、使用者成就、訂單總結、學習報告。每個使用者的資料不同，但視覺結構相同。用 React 元件加資料驅動，會比手工剪輯更自然。

技術示範影片

如果影片裡包含程式碼、圖表、產品介面、步驟動畫和說明文字，Remotion 很適合把這些元素組織成可重複渲染的模板。

資料影片和圖表動畫

資料視覺化本來就是前端強項。Remotion 讓圖表不僅可以出現在網頁裡，也可以沿著時間軸進入影片。

AI 生成影片工作流程

AI agent 可以先生成腳本和素材結構，再生成 Remotion 元件，最後渲染影片。這比讓模型直接生成最終影片更可控，因為中間產物是程式碼，可以檢查、修改、版本管理和複用。

對 AI 編程工具的意義

Remotion 對 Codex、Claude Code、Cursor、Gemini CLI 這類 AI 編程工具特別有意思。

原因是影片生成被拆成了開發任務：

生成 React 元件。
調整樣式和版面。
接入資料。
預覽畫面。
根據回饋修改。
渲染輸出。

這套流程非常適合 agent：每一步都有檔案、有程式碼、有預覽、有明確回饋。相較於「直接生成一個影片檔」，程式碼化影片更容易被審閱和迭代。

如果再結合瀏覽器側邊欄、截圖檢查、自動化渲染和評論回饋，Remotion 可以成為 AI 工作流程裡的影片產物層。

使用前要注意授權

Remotion README 特別提醒：Remotion 有特殊授權，在某些公司使用場景下需要取得 company license。

所以不要只把它當成普通 MIT 小工具來用。個人專案、開源專案、商業專案、企業內部工具，授權要求可能不同。正式用於公司生產前，應該先閱讀它的 LICENSE 頁面和官方授權說明。

這點很重要，尤其是把 Remotion 接進自動化內容生成、行銷素材生成或企業內部影片流水線時。

我的判斷

Remotion 的價值不只是「用 React 做影片」，而是把影片變成可程式化、可複用、可自動化的產物。

對普通前端團隊來說，它適合做資料驅動的影片模板。對 AI 工具來說，它更像一個穩定的輸出目標：模型不需要一次性生成黑盒影片，而是生成可讀、可改、可渲染的 React 程式碼。

如果你的內容需要批次生成、個人化生成、根據資料更新，或者需要讓 agent 反覆調整視覺細節，Remotion 值得放進工具箱裡。它不是傳統剪輯軟體的替代品，而是把影片生產接入軟體工程流程的一種方式。

CLIProxyAPI Management Center：給 CLIProxyAPI 配一個視覺化管理後台

Sun, 24 May 2026 10:05:15 +0800

Cli-Proxy-API-Management-Center 可以理解成 CLIProxyAPI 的「駕駛艙」。

前一篇提到的 CLIProxyAPI 負責把 Gemini CLI、Codex、Claude Code、OpenRouter 等能力代理成統一 API；而這個 Management Center 解決的是另一個問題：

代理服務跑起來之後，設定、帳號、OAuth、日誌、配額和憑證，總不能全靠手改檔案和翻終端機吧？

所以它提供了一個 Web 管理介面，讓你可以用瀏覽器管理 CLIProxyAPI 的設定與執行狀態。

它是什麼

從專案說明看，Cli-Proxy-API-Management-Center 是 CLIProxyAPI 的獨立管理前端，核心功能包括：

視覺化編輯 CLIProxyAPI 設定。
上傳和管理 auth.json 一類認證檔案。
查看請求日誌和模型回應日誌。
管理 OAuth 認證流程。
檢查 Gemini CLI 帳號配額。
提供帳號、設定、日誌等日常維護入口。

另外，官方倉庫也提示：新版 CLIProxyAPI 已經內建了這個管理介面，可以直接透過 /management.html 存取；獨立倉庫仍然保留給需要單獨部署或二次開發的人使用。

這點很重要。也就是說，大多數普通使用者未必需要額外部署這個倉庫；先確認你的 CLIProxyAPI 版本是否已經自帶管理頁。

它解決的不是「呼叫模型」，而是「管理模型入口」

CLIProxyAPI 的難點不只是能不能把請求轉到模型。

真正麻煩的是這些東西：

多個 Gemini、OpenAI、Claude、Codex 帳號如何放進池子裡。
哪個帳號已經失效，哪個帳號配額快用完。
OAuth 登入狀態怎麼匯入、刷新和排查。
設定檔怎麼改才不會漏逗號、漏欄位。
請求到底打到了哪個 provider、哪個模型、哪個帳號。
失敗請求是上游問題、協議問題，還是本機設定問題。

Management Center 的價值就在這裡：它把「代理基礎設施」的日常維護變成視覺化操作。

如果你只是本機跑一個帳號、偶爾調幾次 API，它不一定是剛需；但只要你開始做多帳號、多模型、多客戶端接入，一個後台介面就會明顯省事。

典型使用場景

第一，管理帳號池。

CLIProxyAPI 支援多帳號輪詢和負載均衡，但帳號越多，越不適合靠手工翻設定檔維護。管理中心可以幫助你查看帳號狀態、匯入憑證、排查異常帳號。

第二，排查請求失敗。

當客戶端報錯時，你需要知道請求有沒有進代理、走了哪個 provider、返回了什麼錯誤。日誌介面比在終端機裡滾屏找錯誤舒服很多。

第三，處理 OAuth。

Codex、Claude Code、Gemini CLI 這類工具經常涉及 OAuth 登入狀態。管理中心提供 OAuth 相關操作入口，能減少重複命令列操作。

第四，給團隊內部使用。

如果 CLIProxyAPI 變成團隊共享閘道，那管理者需要一個能快速查看設定和狀態的介面。否則每次變更都要登入伺服器改檔案，效率很低，也容易誤操作。

和 CLIProxyAPI 的關係

可以把兩者分成前後兩層：

客戶端 / IDE / 腳本
        |
        v
CLIProxyAPI：負責協議代理、帳號池、模型路由
        |
        v
Gemini CLI / Codex / Claude Code / OpenRouter / 上游模型

Management Center 不在這條推理請求鏈路的核心位置。它更像維運面板：

瀏覽器
  |
  v
Management Center：編輯設定、看日誌、管帳號、查配額
  |
  v
CLIProxyAPI 管理介面 / 設定 / 日誌 / 憑證

所以不要把它理解成另一個模型代理。它是管理 CLIProxyAPI 的工具，不是替代 CLIProxyAPI 的工具。

為什麼新版內建後仍然值得單獨看

既然 CLIProxyAPI 已經內建了 /management.html，為什麼還要關注這個獨立倉庫？

主要有三個原因。

第一，獨立倉庫能讓你看清管理中心本身的功能邊界。哪些是前端負責的，哪些必須由 CLIProxyAPI 後端提供介面，一眼更清楚。

第二，如果你要二次開發，比如改 UI、加鑑權、接自己的監控系統，獨立倉庫更適合作為入口。

第三，如果你的部署環境比較特殊，比如前後端分開部署、管理頁走單獨網域、靜態資源由內網閘道託管，獨立版本更靈活。

對普通個人使用者來說，優先用 CLIProxyAPI 內建版就夠了；對團隊或深度定制使用者，獨立倉庫更有意義。

部署時最該注意什麼

管理後台接觸的是敏感東西：帳號、OAuth、API Key、日誌、請求內容、上游配額。

所以第一條原則是：不要把管理頁面裸露到公網。

比較穩的做法是：

只允許本機存取，比如綁定 127.0.0.1。
如果必須遠端存取，放到 VPN、Tailscale、內網跳板機或反向代理鑑權後面。
給管理介面加認證，不要只靠「地址沒人知道」。
日誌裡盡量避免暴露完整 Key、Cookie、OAuth token 和使用者原始請求。
團隊環境裡要分清「呼叫 API 的人」和「能改設定的人」。

很多代理工具真正出問題，不是模型呼叫失敗，而是管理口、日誌和憑證檔案沒保護好。

它適合和哪些東西一起用

如果你只部署 CLIProxyAPI，一個管理中心已經能解決基礎維護問題。

如果你進一步關心統計和可觀測性，還可以搭配 CLIProxyAPI 生態裡的其他工具：

CPA Usage Keeper：偏用量同步和 SQLite 儲存。
CLIProxyAPI Usage Dashboard：偏本機優先的用量、配額和圖表展示。
CPA-Manager：偏完整管理中心，關注請求監控、費用估算、帳號池巡檢和異常帳號清理建議。

可以簡單理解：

Management Center 管「設定和日常維護」。
Usage Dashboard 管「看用量和配額」。
CPA-Manager 管「更重的營運和巡檢」。

實際用哪個，要看你的部署規模。個人本機用不需要把全家桶都裝上。

使用建議

如果你剛開始折騰 CLIProxyAPI，可以按這個順序來：

先讓 CLIProxyAPI 本體跑通，確認 API 能正常回應。
打開內建的 /management.html，看看設定和日誌是否能正常讀取。
再匯入一個帳號或一個 provider，確認管理介面能反映狀態變化。
有公網存取需求時，先做認證和網路隔離，再考慮開放入口。
等帳號和請求量變多，再補用量統計和更完整的管理工具。

不要一開始就把所有帳號、所有 provider、所有管理元件一次性接上。越是代理和帳號池類專案，越適合小步驗證。

總結

Cli-Proxy-API-Management-Center 的定位很清楚：它不是模型、不是聊天客戶端，也不是新的 API 閘道；它是 CLIProxyAPI 的視覺化管理層。

當 CLIProxyAPI 只是一個本機小工具時，你可以不用它；當 CLIProxyAPI 開始承載多帳號、多模型、多客戶端呼叫時，它就會變成很實用的「控制台」。

真正要注意的是安全邊界。管理後台能改設定、看日誌、碰憑證，一旦暴露不當，風險比普通 API 呼叫口還高。把它放在可信網路裡，用認證保護好，再去享受視覺化管理帶來的省心。

參考資料：

CLIProxyAPI：把 Codex、Claude Code、Gemini CLI 統一封裝成 API

Sun, 24 May 2026 10:03:33 +0800

CLIProxyAPI 是一個很有「民間工程味」的專案：它不是再造一個大模型，也不是單純做 API 轉發，而是把一堆原本偏互動式、偏 CLI、偏 OAuth 登入的 AI 工具，重新包成統一 API 服務。

它支援的對象包括 Gemini CLI、OpenAI Codex、Claude Code、Amp CLI、AI Studio Build，以及上游 OpenAI 相容服務。換句話說，它想解決的問題是：

我手上有 CLI 工具、有訂閱帳號、有 OAuth 登入狀態，能不能像呼叫普通 API 一樣，把這些能力接到自己的客戶端、腳本、IDE 或內部服務裡？

CLIProxyAPI 給出的答案是：可以，中間加一層代理，把不同來源的 CLI 能力轉換成 OpenAI、Gemini、Claude、Codex 相容介面。

它真正解決的痛點

很多 AI 編程工具的能力本來很強，但預設使用方式並不適合自動化。

比如：

Gemini CLI 能登入帳號使用，但你的程式更習慣呼叫 HTTP API。
Claude Code 很適合互動式編碼，但接入其他客戶端時會遇到協議不一致。
Codex CLI 支援 OAuth 登入和 Responses 風格能力，但不是所有上層工具都知道怎麼和它說話。
一個團隊可能有多個帳號，需要輪詢、負載均衡、異常帳號剔除和配額觀察。
你想讓某些工具只認 OpenAI 格式，但後端實際可能是 Gemini、Claude 或 Codex。

CLIProxyAPI 的定位，就是做這些工具和客戶端之間的「協議適配層」。

它把複雜的一側藏在後面：OAuth、CLI 登入、多帳號、不同協議、不同 provider。前面則暴露相對熟悉的介面，比如 OpenAI Chat Completions、OpenAI Responses、Gemini、Claude Messages、Codex 相關端點。

能力概覽

從官方 README 和文件看，CLIProxyAPI 目前的核心能力包括：

為 CLI 模型提供 OpenAI、Gemini、Claude、Codex 相容 API 端點。
透過 OAuth 登入接入 OpenAI Codex 和 Claude Code。
支援串流、非串流回應，以及部分場景下的 WebSocket。
支援函式呼叫、工具呼叫和多模態輸入。
支援 Gemini、OpenAI、Claude 多帳號輪詢與負載均衡。
支援 Gemini AI Studio API Key。
支援 AI Studio Build、Gemini CLI、Claude Code、OpenAI Codex 的多帳號池。
可以透過設定接入 OpenAI 相容上游，比如 OpenRouter。
提供 Go SDK，方便把代理能力嵌入到自己的服務裡。

這類專案最有價值的地方，不是「多支援幾個模型名」，而是把帳號登入、協議轉換和請求路由這些瑣碎工作打包起來。

它適合誰用

CLIProxyAPI 更適合下面幾類人。

第一類是重度 AI 編程使用者。你已經在用 Codex、Claude Code、Gemini CLI，但想把它們接到 Cursor、Cline、RooCode、Amp、內部腳本或自建工作流裡。

第二類是有多帳號池的人。比如你有多個 Gemini、OpenAI、Claude 登入狀態，不想手工切換，希望自動輪詢、均衡使用、遇到異常帳號時能快速排查。

第三類是做團隊內部閘道的人。團隊不希望每個客戶端都分別適配 Gemini、Claude、Codex，而是想透過一個中間層統一暴露 API。

第四類是喜歡折騰協議的人。你可能關心 Responses、Chat Completions、Claude Messages、Gemini v1beta 這些介面如何互相轉換，也可能希望在同一套客戶端裡切換不同後端。

如果只是個人偶爾問幾句 AI，或者只用官方 App 聊天，那 CLIProxyAPI 的部署和維護成本就顯得重了。

和普通 API 中轉有什麼不同

普通 API 中轉服務一般是：

`1`	`客戶端 -> 中轉 API -> 上游模型 API`

CLIProxyAPI 的鏈路更像：

`1`	`客戶端 -> CLIProxyAPI -> CLI / OAuth 登入狀態 / 多帳號池 -> 模型服務`

區別在於，它處理的不只是 API Key 轉發，還包括 CLI 工具、OAuth 帳號、協議表面和模型別名。

比如 Codex 和 Claude Code 這類工具，本身就不是傳統意義上「拿一個 API Key 就能穩定呼叫」的模式。CLIProxyAPI 把這些登入狀態和呼叫邏輯包裝起來，讓外部客戶端像呼叫 API 一樣存取它們。

這也是它吸引人的地方，同時也是它複雜的地方。

使用時最容易誤解的地方

第一，不要以為統一 /v1/... 就能解決所有協議差異。

CLIProxyAPI 文件裡專門提醒過：當你需要某一類後端的請求和回應形態時，優先使用 provider-specific 路徑。例如 messages 風格用 /api/provider/{provider}/v1/messages，Gemini 模型路徑用 /api/provider/{provider}/v1beta/models/...，chat-completions 風格用 /api/provider/{provider}/v1/chat/completions。

統一入口方便，但不同協議的語義並不會憑空消失。工具呼叫、串流回傳、多模態輸入、系統訊息處理，都可能因為後端不同而有細節差異。

第二，模型名不等於唯一後端。

如果多個後端暴露了相同的客戶端可見模型名，僅靠路徑不一定能鎖定真正執行推理的那個後端。要嚴格固定後端，最好使用唯一 alias、前綴，或者避免讓多個後端暴露同名模型。

第三，多帳號輪詢不是無限額度。

輪詢只能更均勻地使用帳號池，不能繞過上游服務的真實限制。帳號異常、配額耗盡、風控、OAuth 失效，都需要單獨監控。

第四，它不是免維護魔法盒。

一旦你把它放進日常工作流，就要關心設定、日誌、上游帳號狀態、版本升級、客戶端相容性和安全邊界。

管理和監控怎麼辦

官方 README 提到，從 v6.10.0 開始，CLIProxyAPI 和 CPAMC 不再預置資料統計功能。如果需要使用量統計，可以配合獨立專案：

CPA Usage Keeper：同步 CLIProxyAPI 資料，存到 SQLite，並提供聚合 API 和儀表板。
CLIProxyAPI Usage Dashboard：本機優先的用量與配額看板，可展示帳號、模型、時間窗口和 Codex 配額餘量。
CPA-Manager：更完整的管理中心，面向請求監控、費用估算、帳號池巡檢、異常帳號定位和清理建議。

這說明 CLIProxyAPI 的核心更偏「代理和協議層」，而不是一站式商業管理後台。如果是團隊使用，最好一開始就把日誌、監控和帳號池管理考慮進去。

一個比較合理的使用姿勢

如果要試用，可以按這個順序來：

先用官方文件的 Quick Start 跑起來。
只接一個 provider，比如 Gemini CLI 或 Codex，確認基本請求能通。
再測試串流回應、工具呼叫、多模態輸入這些高風險能力。
確認客戶端實際使用的是哪個 endpoint，不要混用協議路徑。
最後再加入多帳號輪詢、管理面板和用量統計。

不要一上來就把 Gemini、Codex、Claude、OpenRouter、多帳號和所有客戶端全接進去。這樣出錯時很難判斷是認證問題、協議問題、模型名問題，還是上游帳號問題。

安全邊界也要想清楚

CLIProxyAPI 會接觸到帳號登入狀態、API Key、OAuth 相關憑據和請求內容。它如果只跑在自己機器上，風險相對可控；如果暴露到公網或團隊內網，就必須認真處理認證、存取控制、日誌脫敏和網路隔離。

尤其是管理端點，最好只允許本機或可信內網存取。不要為了省事直接把管理介面裸露出去。

總結

CLIProxyAPI 的價值在於，它把原本散落在多個 CLI、多個帳號、多個協議裡的 AI 能力，收攏成一個可編程的 API 層。

它適合重度 AI 編程使用者、多帳號使用者和團隊內部閘道場景；不太適合只想「開箱即用、完全無維護」的輕量使用者。

如果你正在折騰 Codex、Claude Code、Gemini CLI 這些工具，並且希望把它們接進自己的客戶端或自動化工作流裡，CLIProxyAPI 值得認真看一眼。但要把它當基礎設施來用，而不是當一次性小工具來用。

參考資料：

讓 Codex 使用 DeepSeek 模型的兩種方法：本機閘道和 OpenRouter BYOK

Sun, 24 May 2026 09:52:55 +0800

想讓 Codex 使用 DeepSeek，第一反應通常是改 ~/.codex/config.toml：

1
2

model = "deepseek-chat"
base_url = "https://api.deepseek.com"

這個思路在一些舊版本或普通 OpenAI SDK 場景裡確實成立，但放到目前的 Codex CLI 上，很容易撞到一個底層問題：Codex 的自訂模型供應商走的是 OpenAI Responses 協議，而 DeepSeek 官方介面主要提供 OpenAI 相容的 Chat Completions 呼叫方式。

我本機目前是 codex-cli 0.111.0。codex --help 裡可以看到它支援 --config、--model、--profile 這些設定入口；OpenAI 官方 Codex 設定參考也寫得很明確：model_providers.<id>.wire_api 目前只支援 responses，省略時也預設是 responses。

DeepSeek 官方文件則給出的呼叫路徑是 https://api.deepseek.com/chat/completions，範例也是 client.chat.completions.create(...)。所以問題不在於 DeepSeek 不能被 OpenAI SDK 呼叫，而在於 Codex 發出的請求語義，和 DeepSeek 原生介面能理解的語義不完全是同一套東西。

這就是為什麼直接把 base_url 改成 https://api.deepseek.com 後，可能出現下面這些現象：

請求路徑不匹配，直接 404 或回傳格式不對。
多輪對話、工具呼叫、補丁產生時解析失敗。
tool_calls 順序、訊息結構、串流事件格式對不上。
看起來模型能回一句話，但一到 Codex 真正幹活就開始報錯。

更穩的辦法，是在 Codex 和 DeepSeek 之間放一個「翻譯層」。常見有兩種路線。

方法一：用本機閘道橋接 DeepSeek

本機閘道的作用不是簡單轉發，而是把 Codex 側的 Responses 風格請求，轉換成 DeepSeek 能處理的 Chat Completions 風格請求，再把 DeepSeek 的結果轉換回 Codex 能吃的格式。

如果你用的是 ccx 這類本機閘道，設定思路大致是這樣：

[profiles.deepseek-ccx]
model = "deepseek-v4-flash"
model_provider = "ccx-bridge"

[model_providers.ccx-bridge]
name = "Local CCX Gateway"
base_url = "http://localhost:3000/v1"
env_key = "DEEPSEEK_API_KEY"

然後在終端機裡設定 DeepSeek Key，再用這個 profile 啟動：

1
2

export DEEPSEEK_API_KEY="your-deepseek-key"
codex --profile deepseek-ccx

PowerShell 裡是：

1
2

$env:DEEPSEEK_API_KEY="your-deepseek-key"
codex --profile deepseek-ccx

這裡有兩個細節要注意。

第一，base_url 要指向閘道暴露給 Codex 的位址，不是 DeepSeek 官方位址。閘道背後再去呼叫 DeepSeek。

第二，env_key 寫什麼取決於閘道怎麼鑑權。有的閘道直接讀取 DeepSeek 官方 Key，有的閘道會要求你給它一個本機代理 Key，再由閘道自己的後台保存 DeepSeek Key。遇到這種情況，env_key 就應該改成閘道要求的環境變數名。

這條路的優點是本機可控，延遲和成本也更容易算清楚。缺點是你必須確認閘道真的支援 Codex 目前使用的 Responses 語義，而不是只做了普通 Chat Completions 代理。

方法二：用 OpenRouter BYOK 做線上橋接

如果不想在本機部署閘道，可以考慮 OpenRouter 的 BYOK。BYOK 的意思是把你自己的上游供應商 Key 綁定到 OpenRouter，由 OpenRouter 負責路由和轉發。

這裡最容易寫錯的是環境變數。Codex 存取的是 OpenRouter，所以 env_key 通常應該是 OPENROUTER_API_KEY，不是 DEEPSEEK_API_KEY。DeepSeek Key 要在 OpenRouter 的 BYOK 或 provider key 設定裡新增。

設定範例：

[profiles.deepseek-openrouter]
model = "deepseek/deepseek-chat"
model_provider = "openrouter"

[model_providers.openrouter]
name = "OpenRouter"
base_url = "https://openrouter.ai/api/v1"
env_key = "OPENROUTER_API_KEY"

啟動方式：

1
2

export OPENROUTER_API_KEY="your-openrouter-key"
codex --profile deepseek-openrouter

PowerShell：

1
2

$env:OPENROUTER_API_KEY="your-openrouter-key"
codex --profile deepseek-openrouter

然後在 OpenRouter 後台把 DeepSeek 的 provider key 加進去。OpenRouter 的 BYOK 文件說明，綁定的 provider key 會被加密保存，並用於路由到對應供應商。

這條路的優點是省掉本機閘道維護成本，設定起來更像普通第三方 API 代理。缺點是中間多了一層線上服務，排障時要同時看 Codex、OpenRouter、DeepSeek 三邊的錯誤訊息。

要不要繼續用 deepseek-chat 這個模型名？

DeepSeek 官方文件在 2026 年 5 月的說明裡，推薦模型名已經出現 deepseek-v4-flash 和 deepseek-v4-pro，並提示 deepseek-chat、deepseek-reasoner 相容別名會在 2026-07-24 之後廢棄。

所以新設定裡更建議優先測試：

`1`	`model = "deepseek-v4-flash"`

如果走 OpenRouter，則要按 OpenRouter 的模型命名來寫，例如：

`1`	`model = "deepseek/deepseek-chat"`

實際可用名稱以你所用閘道或 OpenRouter 模型頁為準。模型名不對時，錯誤通常會表現為 model not found、404，或者 provider 找不到對應 endpoint。

直接改 DeepSeek 官方 base_url 為什麼不推薦

你當然可以試著寫：

[profiles.deepseek-direct]
model = "deepseek-v4-flash"
model_provider = "deepseek"

[model_providers.deepseek]
name = "DeepSeek"
base_url = "https://api.deepseek.com"
env_key = "DEEPSEEK_API_KEY"

但這更像排錯實驗，不適合作為穩定方案。因為 Codex 會按 Responses 協議去和自訂 provider 說話，而 DeepSeek 官方範例走的是 /chat/completions。如果 DeepSeek 或 Codex 未來補齊了相容層，這種直連才可能變得簡單；在此之前，橋接層更可靠。

改完設定後還是走 OpenAI 怎麼辦

先確認設定檔位置。全域設定應該在：

`1`	`~/.codex/config.toml`

專案裡的 .codex/config.toml 不適合放 model_provider、model_providers 這類機器級 provider 設定。OpenAI 官方文件也提醒，專案級設定不會覆蓋這些本機 provider 和認證相關欄位。

如果 Codex 仍然要求網頁登入，或者看起來還在走預設 OpenAI 模型，可以先退出目前登入狀態：

`1`	`codex logout`

有些舊教學會寫成交互介面裡的 /logout。在目前 CLI 裡，更穩的是直接在終端機執行 codex logout。

還可以用臨時參數做一次快速驗證：

`1`	`codex --profile deepseek-ccx`

或者：

`1`	`codex -c model_provider=ccx-bridge -c model=deepseek-v4-flash`

如果這樣能生效，說明設定本身可讀；如果不生效，優先檢查 profile 名稱、TOML 語法、環境變數是否只在目前 shell 裡有效。

排障清單

401：Key 不對，或者 env_key 指向了錯誤的環境變數。
404：base_url 或模型名不對，也可能是把 Responses 請求打到了只支援 Chat Completions 的位址。
tool_calls、patch、串流解析報錯：大機率是協議橋接不完整。
仍然提示登入 OpenAI：執行 codex logout，再確認是否用了正確 profile。
PowerShell 設定環境變數後新開視窗失效：$env:... 只對目前會話生效，需要長期保存就改使用者環境變數。
OpenRouter BYOK 沒走自己的 DeepSeek Key：檢查 OpenRouter 後台 provider key 是否綁定、是否允許目前 OpenRouter API Key 使用，以及是否開啟了 fallback。

結論

讓 Codex 使用 DeepSeek，不是不能改 config.toml，而是不能只改 base_url 就指望一切自動相容。

目前更穩的兩條路是：

用本機閘道做協議橋接，Codex 連本機閘道，閘道再連 DeepSeek。
用 OpenRouter BYOK 做線上轉發，Codex 連 OpenRouter，DeepSeek Key 綁定在 OpenRouter 後台。

如果只是想快速試用，OpenRouter 路線更省事；如果你希望 Key、成本、日誌都盡量掌握在自己手裡，本機閘道更適合長期折騰。

參考資料：

CodeGraph 是什麼？給 Claude Code、Codex 和 Cursor 加一張本地程式碼地圖

Sat, 23 May 2026 21:09:46 +0800

CodeGraph 是一個給 AI 編程工具使用的本地程式碼知識圖譜。它會提前給專案建立索引，把符號關係、呼叫圖、程式碼結構、路由關係等資訊整理成可查詢的圖，讓 Claude Code、Codex CLI、Cursor、OpenCode、Hermes Agent 這類工具不用每次都靠 grep、glob、Read 和子代理到處翻檔案。

它解決的是一個很實際的問題：AI Agent 看大型程式碼庫時，很多成本不是花在真正修改程式碼上，而是花在「找程式碼在哪裡」。如果每次都重新搜尋、讀取、篩選，token、時間和工具呼叫都會被消耗掉。CodeGraph 的思路是先把程式碼庫變成一張本地地圖，讓 Agent 先問地圖，再決定要不要讀具體檔案。

它主要解決什麼痛點

AI 編程工具在小專案裡通常還好，檔案少，搜尋快，讀一遍也不貴。但專案一大，常見問題就會出現：

Agent 為了理解一個模組，反覆呼叫 grep、find、ls、Read。
探索子代理讀了很多無關檔案，主任務上下文卻沒有變清楚。
問一個架構問題時，token 大量花在定位檔案上。
改一個函式前，不知道誰在呼叫它、它又呼叫了誰。
Web 專案裡，URL 路由和實際處理函式之間的關係不夠直觀。

CodeGraph 試圖把這些「先找路」的工作前置。專案索引建好後，Agent 可以直接查詢相關符號、呼叫方、被呼叫方、影響範圍和程式碼片段。

安裝方式

專案提供跨平台安裝腳本，不要求使用者自己準備 Node.js：

`1`	`curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh \| sh`

Windows PowerShell 可以使用：

`1`	`irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 \| iex`

如果已經有 Node 環境，也可以直接用 npm：

`1`	`npx @colbymchenry/codegraph`

或者全域安裝：

`1`	`npm i -g @colbymchenry/codegraph`

安裝器會自動偵測並配置已安裝的 Agent，例如 Claude Code、Cursor、Codex CLI、opencode 和 Hermes Agent。它會寫入對應的 MCP server 配置和指令檔案，讓這些工具知道什麼時候呼叫 CodeGraph。

初始化專案

安裝完成後，需要在目標專案裡建立索引：

1
2

cd your-project
codegraph init -i

這個命令會產生專案級知識圖譜索引。README 中提到，只要專案裡存在 .codegraph/ 目錄，Agent 就可以自動使用 CodeGraph 工具。

如果不想繼續使用，也可以卸載全域配置：

`1`	`codegraph uninstall`

它會移除安裝器寫入的 MCP server 配置、指令和權限。專案中的 .codegraph/ 索引不會被自動刪除，如果要移除專案索引，需要使用 codegraph uninit。

為什麼它對 Agent 有用

Claude Code、Codex CLI、Cursor 這類工具在理解程式碼庫時，常常會先做探索：找檔案、讀入口、查引用、再追呼叫鏈。這個過程對人來說像「翻專案」，對模型來說就是一串工具呼叫和上下文消耗。

CodeGraph 把這一步變成索引查詢。Agent 可以先用 codegraph_context 找到相關入口、符號和片段，再用 codegraph_explore 或其他工具讀取必要內容。這樣做的好處是：

少讀無關檔案。
少呼叫搜尋工具。
更快找到真正相關的程式碼。
改動前更容易看清影響範圍。
大型倉庫裡的架構問題更容易回答。

專案 README 給出的基準測試顯示，在 7 個真實開源程式碼庫上，對比啟用 CodeGraph 和不啟用 CodeGraph，平均結果是成本更低、token 更少、速度更快、工具呼叫更少。具體數字會受專案規模、語言、問題類型和 Agent 使用方式影響，但方向很清楚：越大的倉庫，預索引的價值越明顯。

核心能力

1. 智慧上下文構建

一個工具呼叫可以返回入口點、相關符號和程式碼片段，減少 Agent 先派一堆探索任務再慢慢篩選的情況。對架構理解、模組定位、功能入口分析很有用。

2. 全文搜尋

CodeGraph 使用 FTS5 做全文搜尋，可以在整個程式碼庫裡快速按名稱和文字查找程式碼。這不是替代所有 grep 場景，而是讓 Agent 有一個更結構化的第一站。

3. 影響分析

在改函式、類別、方法或路由前，可以查詢 callers、callees 和影響半徑。對重構、修 bug、刪除舊程式碼尤其有用，因為最怕的就是只改了當前檔案，卻漏掉上游或下游呼叫。

4. 自動保持新鮮

README 中提到，CodeGraph 使用原生檔案系統事件，例如 FSEvents、inotify、ReadDirectoryChangesW，並帶有 debounce auto-sync。意思是索引會隨著本地程式碼變化自動更新，不需要每改一個檔案都手動重建。

5. 多語言支援

專案列出的支援範圍超過 19 種語言，包括 TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Lua、Luau、Svelte、Liquid、Pascal / Delphi 等。

這讓它更適合多語言倉庫和全棧專案，而不是只服務某一種語言。

6. Web 路由感知

CodeGraph 還會識別多種 Web 框架裡的路由檔案和路由宣告，把 URL pattern 和處理函式連接起來。README 中提到的框架包括 Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、Axum、ASP.NET、Vapor、React Router、SvelteKit 等。

這點很實用。很多 Web 專案的真實入口不是某個明顯的 main 函式，而是路由、controller、handler、view 或 resolver。Agent 如果能先知道 URL 到處理函式的關係，理解業務流程會快很多。

本地優先的設計

CodeGraph 強調 100% local。它不需要 API key，不依賴外部服務，索引資料保存在本地 SQLite 資料庫裡。

對企業專案、私有倉庫或敏感程式碼來說，這個設計很重要。AI 工具接入程式碼庫時，大家最擔心的往往不是「能不能查到程式碼」，而是「程式碼結構和索引會不會被發出去」。CodeGraph 的定位是本地構建、本地查詢、本地服務 Agent。

當然，本地也意味著要考慮磁碟空間、索引時間、檔案監聽和專案規模。如果倉庫特別大，第一次初始化和後續同步仍然需要資源。

適合哪些場景

CodeGraph 更適合這些場景：

大型程式碼庫，經常需要問架構和呼叫鏈問題。
使用 Claude Code、Codex CLI、Cursor 等 Agent 做程式碼理解和修改。
希望減少 Agent 到處讀檔案、亂搜、反覆探索。
需要在改動前分析影響範圍。
Web 專案路由複雜，需要快速從 URL 找到處理函式。
團隊希望給 AI Agent 一個更穩定的本地專案索引。

如果只是幾十個檔案的小專案，普通搜尋已經夠快，CodeGraph 的優勢可能不明顯。它最有價值的地方，是中大型程式碼庫和經常讓 Agent 做探索的場景。

使用時要注意什麼

第一，CodeGraph 不是替代程式碼審查和測試的工具。它能幫助 Agent 更快找到相關程式碼，但不能保證 Agent 的修改一定正確。

第二，索引品質會影響使用效果。專案結構複雜、生成程式碼很多、語言混雜或 build 產物沒有排除時，索引可能會變得臃腫。使用前最好確認 .gitignore、專案目錄和索引範圍是否合理。

第三，MCP 配置和 Agent 指令很關鍵。README 裡也提醒，CodeGraph 只有在被正確查詢時才有幫助。如果 Agent 仍然繞開它去大量讀檔案，預索引就會變成額外開銷。

第四，雖然它是本地工具，也要注意權限。安裝器會寫入 Agent 配置和權限列表，團隊環境中最好統一審查這些配置。

小結

CodeGraph 的價值可以簡單理解為：給 AI Agent 一張本地程式碼地圖。它不是讓模型更聰明，而是讓模型少迷路。

當 Claude Code、Codex CLI、Cursor 這類工具面對大型倉庫時，最耗費上下文的往往是探索過程。CodeGraph 用預索引的符號關係、呼叫圖、路由圖和全文搜尋，把「找程式碼」這一步提前做好，讓 Agent 把更多預算花在理解和修改上。

如果你已經在真實專案裡使用 AI 編程工具，並且經常遇到「它讀了一堆檔案還是沒找到重點」的情況，CodeGraph 值得試一下。它代表了 AI 編程工具的一個重要方向：不只是換更強的模型，也要給模型更好的本地程式碼上下文。

參考資料：

GitHub 專案：https://github.com/colbymchenry/codegraph

oh-my-pi 是什麼？一個把終端機、IDE 和除錯器打通的 AI 程式設計助手

Sat, 23 May 2026 19:02:20 +0800

oh-my-pi 是一個面向終端機和編輯器的 AI Coding Agent。它來自 Mario Zechner 的 Pi 專案分支，由 can1357 繼續擴展，目標不是只做一個命令列聊天介面，而是把檔案讀取、程式碼搜尋、結構化編輯、LSP、除錯器、瀏覽器、子代理和多模型提供商接到同一個編程工作流裡。

從專案 README 來看，它更像一套 AI 編程工具底座：終端機裡可以直接互動，編輯器可以透過 ACP 接入，Node 專案也可以透過 SDK 嵌入。對已經在用 Claude Code、Codex CLI、Cline、Cursor 或其他 Agent 工具的人來說，oh-my-pi 值得關注的地方在於它把很多原本分散在外部工具裡的能力做成了內建工具面。

它主要解決什麼問題

很多 AI 編程工具的短板不在模型本身，而在工具介面。模型想改程式碼時，如果只能拿到粗糙的全文、脆弱的字串替換和一次性的 shell，失敗率就會被工具鏈放大。

oh-my-pi 的思路是把這些常見摩擦點壓低：

讀取檔案時優先給結構化摘要，而不是把整份檔案塞進上下文。
搜尋、glob、find、語法高亮、token 計數等能力盡量放進原生實作，減少對外部命令的依賴。
寫程式碼時接入 LSP，讓重新命名、引用查找、檔案移動更接近 IDE 行為。
除錯時接入 lldb、dlv、debugpy 等 DAP 工具，而不是只靠日誌和猜測。
複雜任務可以拆給子代理，並用結構化結果返回。
對編輯操作使用內容錨點和預覽機制，降低錯誤 patch 直接落盤的機率。

這些設計說明它關注的不是「模型會不會回答」，而是「模型能不能穩定完成一次真實程式碼修改」。

安裝方式

專案提供了幾種安裝入口。macOS 和 Linux 可以使用安裝腳本：

`1`	`curl -fsSL https://omp.sh/install \| sh`

如果使用 Bun，官方推薦全域安裝 npm 套件：

`1`	`bun install -g @oh-my-pi/pi-coding-agent`

Windows PowerShell 可以使用：

`1`	`irm https://omp.sh/install.ps1 \| iex`

專案 README 還提到可以透過 mise 固定版本：

`1`	`mise use -g github:can1357/oh-my-pi`

安裝前要注意 Bun 版本要求。README 中標註的平台範圍包括 macOS、Linux、Windows，並要求 bun >= 1.3.14。

值得關注的能力

1. 工具呼叫不只停留在 shell

oh-my-pi 內建了檔案讀取、搜尋、寫入、編輯、AST 編輯、瀏覽器、任務拆分、除錯、LSP 等工具。README 中提到它有 32 個內建工具、13 個 LSP 操作和 27 個 DAP 操作。

這意味著 Agent 不必把所有事情都包裝成命令列輸出。比如查引用可以走 LSP，讀 PR 或 issue 可以走統一的檔案式介面，網頁和 PDF 可以被轉換成帶連結結構的 Markdown，再交給模型處理。

2. LSP 接入更適合真實程式碼庫

對大型專案來說，重新命名和移動檔案最怕漏掉 re-export、別名匯入、barrel file 或跨目錄引用。oh-my-pi 的 README 特別強調寫入路徑會接入 LSP，例如檔案重新命名會經過 workspace/willRenameFiles，讓編輯更接近 IDE 的語意操作。

這類能力適合 TypeScript、Rust、Go、Python 等專案裡的日常重構，尤其是那些「手動改能改，但很容易漏一個引用」的場景。

3. 除錯器是一級工具

很多 AI 編程流程遇到崩潰時，仍然停留在加日誌、重新執行、再讀輸出。oh-my-pi 把 DAP 除錯器接入工具面，README 裡舉了 C 程式用 lldb、Go 服務用 dlv、Python 行程用 debugpy 的例子。

這會改變 Agent 處理 bug 的方式：它可以暫停行程、查看堆疊框架、讀局部變數，再決定下一步，而不是只靠錯誤文字猜測。

4. Hashline 編輯降低 patch 失敗率

專案強調的 Hashline 是一種基於內容錨點的編輯方式。它的目標是讓模型指向要修改的內容錨點，而不是反覆輸出大段 diff。這樣做的好處是減少空格、上下文過期、字串匹配失敗造成的編輯錯誤。

對 Agent 工具來說，這類機制很重要。模型能力再強，如果寫入介面經常失敗，最終體驗仍然會變成反覆重試。

5. 子代理和工作區隔離

README 中介紹了 task 子代理能力：一個任務可以拆給多個隔離 worker，結果再以結構化物件返回。專案還包含工作區隔離相關實作，用來支援並行任務、分支探索和避免互相覆蓋。

這適合程式碼審查、遷移、批量修復、測試定位等任務。真正的價值不只是「並行更快」，而是讓不同探索路徑之間的上下文和檔案改動更清楚。

6. 相容已有規則和配置

oh-my-pi 首次執行時會讀取已有工具留下的規則和配置，包括 .claude、.cursor、.windsurf、.gemini、.codex、.cline、.github/copilot 和 .vscode 等目錄。

這點很實用。很多團隊已經為不同 AI 工具寫過規則，如果每換一個工具都要遷移一遍，成本會很高。oh-my-pi 的做法是盡量直接繼承已有上下文。

四種入口

專案提供了四類使用入口：

互動式 TUI：在終端機裡直接執行 omp。
一次性命令：用 omp -p 發送單次 prompt。
Node SDK：透過 @oh-my-pi/pi-coding-agent 嵌入到 Node 或 TypeScript 專案。
RPC / ACP：透過 stdio 或 Agent Client Protocol 接入其他程式和編輯器。

這說明它不只面向個人終端使用者，也給 IDE、插件、自動化平台和內部工具留了整合空間。

適合誰嘗試

oh-my-pi 比較適合這幾類使用者：

經常在終端機裡做程式碼修改、除錯和審查的人。
已經在使用 AI Coding Agent，但覺得檔案讀取、patch、搜尋或除錯鏈路不夠穩的人。
想把 Agent 接入編輯器、RPC 或 Node 服務的開發者。
需要在一個工具裡切換多模型和多提供商的人。
對 LSP、DAP、AST 編輯和子代理這些底層能力感興趣的工具開發者。

如果只是想要一個開箱即用的聊天式程式碼助手，學習成本可能會偏高。它更適合願意理解工具鏈，並把 Agent 當成可配置開發環境的人。

使用時要注意什麼

第一，oh-my-pi 仍然是快速演進中的開源專案。倉庫提交頻繁，issue 和 PR 數量也不少，安裝和使用時要預期到變化。

第二，它的能力邊界和本地環境強相關。LSP、除錯器、Bun、模型提供商認證、終端環境、Windows 或 Unix 差異都會影響體驗。

第三，內建工具多不等於每個場景都應該全開。實際使用時更適合按任務啟用需要的工具，把規則、權限和工作區邊界配置清楚。

第四，AI Agent 能寫程式碼，也能誤改程式碼。即使有預覽和錨點編輯機制，重要專案仍然要保留版本控制、測試和人工審查。

小結

oh-my-pi 的亮點不在於又做了一個 AI 終端殼，而在於它把 AI 編程中最容易拖後腿的工具層重新整理了一遍：檔案讀取、搜尋、編輯、LSP、除錯、瀏覽器、子代理和 SDK 都被放進同一個 Agent 工作流。

它適合關注 AI 編程基礎設施的人，也適合想比較不同 Coding Agent 路線的開發者。當前 AI 編程工具的競爭，已經不只是模型回答品質的競爭，也是在比誰能把模型穩定接入真實程式碼庫、真實除錯流程和真實團隊規則。oh-my-pi 正是在這個方向上給出了一套很激進的開源實作。

參考資料：

GitHub 專案：https://github.com/can1357/oh-my-pi
官方站點：https://omp.sh/
SDK 文件：https://omp.sh/docs/sdk

Graphify 解決 Claude Code 最大局限：把程式碼庫變成 AI 可查詢知識圖譜

Thu, 21 May 2026 08:02:32 +0800

safishamsi/graphify 是一個面向 AI 編程助手的知識圖譜工具。它的目標很直接：把一個專案目錄裡的程式碼、文件、SQL schema、腳本、論文、圖片、影片和音訊，整理成可查詢的知識圖譜，讓 AI 助手不再只靠 grep、全文閱讀或臨時搜尋來理解專案。

專案地址：safishamsi/graphify

截至本文整理時，GitHub 頁面顯示專案約有 50.2k stars、5.4k forks，授權為 MIT。README 對它的描述是：在 AI 編程助手裡輸入 /graphify，它就會把整個專案映射成一個可以查詢的知識圖譜。

它解決的核心問題

AI 編程助手越來越強，但在真實程式碼庫裡仍然經常遇到幾個問題：

不知道關鍵模組之間怎麼連接。
讀了很多檔案，但沒形成整體架構地圖。
搜尋命中了文字，卻不知道上下游依賴。
程式碼、資料庫 schema、文件和基礎設施設定分散在不同地方。
多人協作時，每個人對專案結構的理解不一致。

Graphify 想做的是給專案生成一層「記憶層」。它把程式碼實體、文件概念、資料庫表、設定、設計說明和跨檔案關係連接起來，讓 AI 助手可以按圖譜查詢，而不是每次從零開始掃檔案。

最小使用方式

Graphify 的最小用法非常簡單。安裝後，在 AI 編程助手裡輸入：

`1`	`/graphify .`

在 PowerShell 裡要注意，前導 / 會被當成路徑分隔符，所以 Windows PowerShell 下應使用：

`1`	`graphify .`

執行後會生成 graphify-out/ 目錄，核心檔案包括：

graphify-out/
├── graph.html
├── GRAPH_REPORT.md
└── graph.json

這三個檔案分工不同：

graph.html：瀏覽器裡打開的互動式圖譜，可以點擊節點、過濾和搜尋。
GRAPH_REPORT.md：專案亮點、關鍵概念、意外連接和推薦問題。
graph.json：完整圖譜，後續可以直接查詢，不必重新讀所有檔案。

如果想生成更可讀的架構頁面和 Mermaid 呼叫流程圖，可以執行：

`1`	`graphify export callflow-html`

安裝和平台支援

Graphify 的 PyPI 包名是 graphifyy，注意是雙 y。README 特別提醒，PyPI 上其他 graphify* 包並不屬於該專案，但 CLI 命令仍然叫 graphify。

推薦安裝方式是：

`1`	`uv tool install graphifyy`

也可以使用：

1
2

pipx install graphifyy
pip install graphifyy

安裝後註冊到 AI 助手：

`1`	`graphify install`

專案支援的平台很多，包括 Claude Code、Codex、OpenCode、GitHub Copilot CLI、VS Code Copilot Chat、Aider、Cursor、Gemini CLI、Kimi Code、Kiro、Google Antigravity 等。不同平台可以用不同安裝命令，例如：

graphify install --platform codex
graphify install --platform gemini
graphify cursor install
graphify antigravity install

Codex 使用者還需要在 ~/.codex/config.toml 的 [features] 下加入：

`1`	`multi_agent = true`

README 也說明，Codex 使用 $graphify，不是 /graphify。

它能處理哪些檔案

Graphify 覆蓋的輸入類型很廣。

程式碼方面，它支援 31 種語言，包括 Python、TypeScript、JavaScript、Go、Rust、Java、C/C++、Ruby、C#、Kotlin、Scala、PHP、Swift、Lua、Zig、PowerShell、SQL、Shell、JSON 等。

文件方面，它支援：

.md
.mdx
.qmd
.html
.txt
.rst
.yaml
.yml

還可以透過可選依賴擴展更多類型：

pip install "graphifyy[pdf]"
pip install "graphifyy[office]"
pip install "graphifyy[video]"
pip install "graphifyy[mcp]"
pip install "graphifyy[neo4j]"
pip install "graphifyy[sql]"
pip install "graphifyy[all]"

其中，pdf 用於 PDF 提取，office 用於 .docx 和 .xlsx，video 用於影片和音訊轉寫，mcp 用於 MCP stdio server，neo4j 用於推送到 Neo4j，sql 用於 SQL schema 提取。

生成的報告有什麼價值

GRAPH_REPORT.md 不是普通摘要，它會把專案裡更值得 AI 助手關注的關係挑出來。

README 裡提到的報告內容包括：

God nodes：專案裡連接最多的核心概念。
Surprising connections：跨檔案、跨模組的意外連接。
The why：從註解、docstring、設計文件裡提取出的設計理由。
Suggested questions：圖譜特別適合回答的問題。
Confidence tags：關係會標記為 EXTRACTED、INFERRED 或 AMBIGUOUS。

這點很關鍵。普通搜尋只能告訴你「哪裡出現了這個詞」，而圖譜可以回答「這個概念和哪些模組、設定、表、文件有關」。對大型程式碼庫來說，這比單純全文檢索更接近架構理解。

常用命令

Graphify 的常見命令包括：

/graphify .
/graphify ./docs --update
/graphify . --cluster-only
/graphify . --no-viz
/graphify . --wiki
graphify export callflow-html
/graphify query "what connects auth to the database?"
/graphify path "UserService" "DatabasePool"
/graphify explain "RateLimiter"

也可以把論文或影片加入圖譜：

1
2

/graphify add https://arxiv.org/abs/1706.03762
/graphify add <youtube-url>

如果要做 PR 輔助分析，還可以使用：

graphify prs
graphify prs 42
graphify prs --triage
graphify prs --conflicts

這類命令適合程式碼評審場景：看 PR 影響了哪些圖譜社群、是否和其他 PR 有衝突風險、哪些 review queue 更值得優先處理。

和 MCP、Neo4j、CI 的關係

Graphify 不只是生成 HTML 圖。它也可以把圖譜暴露給 AI 助手反覆呼叫。

例如可以啟動 MCP server：

`1`	`python -m graphify.serve graphify-out/graph.json`

MCP server 提供的能力包括 query_graph、get_node、get_neighbors、shortest_path、list_prs、get_pr_impact、triage_prs 等。

它也支援 Neo4j 匯出或推送：

1
2

/graphify ./raw --neo4j
/graphify ./raw --neo4j-push bolt://localhost:7687

團隊協作上，README 建議可以提交 graphify-out/，讓團隊每個人拉取後都能共享同一份專案地圖。還可以執行：

`1`	`graphify hook install`

這樣每次 git commit 後自動重建圖譜，並設定 merge driver，避免 graph.json 在多人並行提交時留下衝突標記。

隱私和成本要怎麼看

Graphify 的 README 對隱私邊界寫得比較清楚。

程式碼檔案會透過 tree-sitter 在本地解析，不會發出 API 呼叫。影片和音訊可以透過 faster-whisper 本地轉寫。文件、PDF、圖片這類語義提取內容，則會透過你的 AI 助手模型 API 處理。

如果用 headless graphify extract，可能需要設定這些環境變數：

ANTHROPIC_API_KEY
GEMINI_API_KEY
GOOGLE_API_KEY
OPENAI_API_KEY
DEEPSEEK_API_KEY
MOONSHOT_API_KEY
OLLAMA_BASE_URL

本地 Ollama、AWS Bedrock、Claude Code CLI 等也可以作為 backend。README 還寫明專案沒有 telemetry、usage tracking 和 analytics。

實際使用時要注意：程式碼本地解析不等於所有內容都不出網。涉及文件、PDF、圖片或雲端模型時，仍然要看 backend、API key、企業合規和資料邊界。

適合哪些場景

Graphify 適合幾類使用者：

想讓 Claude Code、Codex、Cursor、Gemini CLI 更懂專案結構的開發者。
需要快速理解大型陌生程式碼庫的人。
需要把程式碼、SQL schema、文件、設定放在一起分析的團隊。
做架構審查、PR review、重構影響分析的人。
希望把專案知識暴露成 MCP 工具給 Agent 使用的人。
想為團隊保留「專案地圖」的技術負責人。

它不一定適合所有專案。小型腳本、一次性 demo、結構非常簡單的倉庫，用普通搜尋和 README 可能已經夠用。Graphify 的價值更容易出現在模組多、文件多、團隊協作多、AI 助手頻繁參與開發的大專案裡。

小結

Graphify 的意義在於，它把 AI 編程助手的上下文從「臨時讀取檔案」推進到「長期可查詢的專案知識圖譜」。

對開發者來說，它不是替代 IDE、搜尋或 LSP，而是給 AI 助手補一層結構化記憶：哪些模組重要、哪些概念連接緊密、哪些文件解釋了設計理由、某個 PR 會影響哪些社群。隨著 Codex、Claude Code、Gemini CLI、Antigravity 這類 Agent 工具繼續普及，這類「專案圖譜層」會越來越有用。

參考來源：

GitHub：safishamsi/graphify

Vercel AI SDK 是什麼？TypeScript 開發者構建 AI 應用的統一工具包

Sun, 17 May 2026 23:07:38 +0800

vercel/ai 是 Vercel 維護的開源 AI SDK。

它的定位很明確：為 TypeScript 開發者提供一套統一工具，用來構建 AI 應用和 AI Agent。它來自 Next.js 背後的團隊，但並不只服務於 Next.js，也支援 React、Svelte、Vue、Angular 等 UI 框架，以及 Node.js 等執行環境。

專案地址：https://github.com/vercel/ai

如果你正在做聊天應用、AI 寫作工具、RAG 應用、帶工具呼叫的 Agent、串流輸出介面，或者想把多個模型供應商接到同一個應用裡，Vercel AI SDK 是一個值得關注的基礎庫。

它解決的核心問題

現在做 AI 應用，最大的麻煩之一不是「能不能呼叫模型」，而是不同模型供應商的介面、串流輸出、工具呼叫、錯誤處理和前端狀態管理都不一樣。

例如：

OpenAI 有自己的 SDK 和回應格式。
Anthropic 有自己的訊息結構。
Google、xAI、Mistral、DeepSeek、Groq 等也各有差異。
串流輸出需要處理 chunk。
工具呼叫需要處理模型發起的結構化請求。
前端聊天 UI 還要管理訊息、載入狀態、取消、重試和錯誤顯示。

如果每個供應商都手寫一套適配層，專案會很快變複雜。

Vercel AI SDK 的思路是把這些差異收斂到統一 API 後面。開發者用一套介面寫應用，再透過 Provider 接入不同模型。

統一 Provider 架構

Vercel AI SDK 的一個核心特點，是 provider-agnostic，也就是不綁定單一模型廠商。

它可以透過統一 API 存取 OpenAI、Anthropic、Google 等模型提供方。專案 README 還提到，預設情況下 AI SDK 會使用 Vercel AI Gateway，讓開發者更容易存取多個主流 provider。

這對工程專案很實用。

因為很多 AI 產品最終都不會只依賴一個模型：

有的任務適合強推理模型。
有的任務適合便宜快速模型。
有的任務需要多模態。
有的任務需要長上下文。
有的任務需要本地或私有部署模型。

統一 Provider 架構讓應用更容易做模型切換、灰度測試、成本控制和備援方案。

串流輸出是前端體驗的關鍵

AI 應用和傳統 API 最大的體驗差異之一，是回應可能很長。

如果使用者每次都要等完整回答返回，聊天工具、寫作工具和程式碼助手會顯得很慢。串流輸出可以讓文字逐步顯示，使用者更早看到結果。

Vercel AI SDK 對串流生成做了比較完整的封裝。開發者不需要從零處理底層事件流，而是可以使用 SDK 提供的生成和串流介面，把模型輸出接到前端 UI。

這對 Next.js / React 應用尤其方便。

一個 AI 聊天介面看起來簡單，但實際要處理：

訊息列表。
使用者輸入。
伺服器請求。
串流 token 顯示。
載入狀態。
錯誤狀態。
中止生成。
重新生成。

這些都是 AI SDK 試圖幫開發者減少重複勞動的地方。

工具呼叫和 Agent 場景

隨著 AI 應用從「聊天」走向「做事」，工具呼叫變得越來越重要。

模型不只是輸出自然語言，還可能需要呼叫外部函式：

查資料庫。
搜尋文件。
呼叫業務 API。
讀取訂單狀態。
生成圖表。
建立日曆事件。
修改專案檔案。

Vercel AI SDK 支援工具呼叫相關能力，讓開發者可以定義工具、參數和執行邏輯，再讓模型在合適時機請求呼叫。

這也是它從「聊天 UI SDK」擴展到「AI 應用和 Agent 工具包」的關鍵。

不過，工具呼叫不是加上去就萬事大吉。真實專案還要考慮：

參數校驗。
權限邊界。
工具呼叫日誌。
冪等性。
超時和重試。
人工確認。
敏感操作限制。

AI SDK 可以幫助處理介面和流程，但安全邊界仍然需要開發者自己設計。

UI 整合能力

Vercel AI SDK 對前端框架比較友好。

它不僅提供核心生成 API，也圍繞聊天、補全、訊息狀態和串流 UI 做了封裝。對於使用 Next.js 和 React 的團隊來說，這能減少很多樣板程式碼。

但它並不只適合 Vercel 部署。

如果你的專案本身是 TypeScript 技術棧，或者後端執行在 Node.js 環境，AI SDK 仍然可以作為模型呼叫和串流處理層來使用。是否部署在 Vercel，取決於你的應用架構、團隊習慣和基礎設施選擇。

Skill for Coding Agents

vercel/ai README 裡還有一個有趣的建議：如果你使用 Claude Code、Cursor 等 coding agent，可以把 AI SDK skill 加到倉庫裡。

範例命令是：

`1`	`npx skills add vercel/ai`

這說明 Vercel 已經意識到，AI SDK 的使用者不只是人類開發者，也包括 coding agent。

當 agent 修改使用 AI SDK 的專案時，如果倉庫裡有專門的 skill，它可以更好地理解 SDK 約定、常見 API、專案結構和最佳實踐，減少亂寫程式碼的機率。

這個方向很值得注意。

未來開源專案可能不只提供 README 和 docs，還會提供給 AI coding agent 使用的結構化技能說明。對複雜 SDK 來說，這會變成新的開發者體驗入口。

適合哪些專案

Vercel AI SDK 適合這幾類場景：

基於 Next.js / React 的 AI 聊天應用。
需要串流輸出的寫作、問答、客服和程式碼助手。
需要接入多個模型 provider 的 AI 產品。
想快速構建 RAG 或文件問答原型的團隊。
需要工具呼叫、函式呼叫或輕量 Agent 能力的應用。
已經使用 TypeScript / Node.js 技術棧的團隊。

它尤其適合前端和全端開發者。因為很多 AI 應用的難點不只是模型呼叫，而是如何把模型輸出變成穩定、流暢、可互動的產品體驗。

不適合什麼場景

如果你的專案主要是 Python 後端、深度學習訓練、模型微調或底層推理服務，Vercel AI SDK 可能不是核心工具。

它更偏應用層，而不是模型訓練框架。

如果你需要的是：

自己訓練模型。
管理 GPU 推理叢集。
做底層 batch inference。
深度控制 tokenizer、KV cache、量化和推理引擎。

那更應該看 PyTorch、vLLM、SGLang、TensorRT-LLM、llama.cpp 或雲端廠商推理服務。

Vercel AI SDK 更像「把模型能力接進產品」的應用開發層。

使用時要注意什麼

第一，不要把統一 API 理解成完全無差異。

不同模型 provider 的能力、上下文長度、工具呼叫格式、串流細節、錯誤類型和計費方式仍然不同。統一 SDK 能減少工程摩擦，但不能消除模型差異。

第二，要控制成本。

AI 應用一旦上線，串流聊天、重試、工具呼叫、RAG 檢索和多模型 fallback 都可能增加呼叫成本。需要做限流、快取、日誌和預算監控。

第三，要處理安全邊界。

如果模型能呼叫工具，就必須限制工具能做什麼。不要讓模型直接執行高風險操作，也不要把密鑰、資料庫寫入權限和生產環境操作裸露給模型。

第四，要保留可觀測性。

AI 應用出問題時，不能只看前端錯誤。你需要知道使用者輸入、模型選擇、工具呼叫、回應時間、token 消耗、錯誤類型和最終輸出。

小結

vercel/ai 不是一個新的模型，也不是單純的聊天元件。

它更像 TypeScript AI 應用開發的基礎設施：統一 Provider、串流輸出、工具呼叫、前端狀態管理和 agent 場景，都被放進一個開源 SDK 裡。

對已經使用 Next.js、React、TypeScript、Node.js 的團隊來說，它可以顯著降低從「模型 API 能跑」到「產品體驗可用」的工程成本。

但它也不是萬能層。模型選擇、權限設計、成本控制、日誌監控和業務安全，仍然需要開發者自己負責。

如果你想做 AI 應用，而不是訓練模型，Vercel AI SDK 是一個值得先試的工具包。

參考資料

Bun：把 JavaScript 執行時、套件管理器、測試和打包合在一起

Sun, 17 May 2026 17:42:25 +0800

Bun 是 oven-sh 開源的 JavaScript / TypeScript 一體化工具鏈。

它不是只想做一個更快的 Node.js 替代品，而是把執行時、套件管理器、腳本執行器、測試執行器和打包器都放進同一個 bun 命令裡。對前端和 Node.js 開發者來說，Bun 的吸引力在於：少裝一堆工具，少等一堆安裝和建置流程，很多常見任務可以直接用一個命令完成。

專案地址：https://github.com/oven-sh/bun

先說結論

Bun 最適合想簡化 JavaScript 工具鏈的人。

它能做這些事：

執行 JavaScript、TypeScript、JSX 和 TSX。
作為 Node.js 相容執行時。
替代 npm / yarn / pnpm 做套件管理。
執行 package.json 裡的 scripts。
執行測試。
打包前端或後端程式碼。
用 bunx 執行 npm 套件裡的命令。
提供 Bun.serve、bun:sqlite、Bun.sql、Bun.redis、Bun.s3 等內建 API。

它最明顯的價值是開發體驗：安裝依賴快、啟動快、命令統一、TypeScript 和 JSX 開箱即用。

但 Bun 也不是所有專案都應該立刻切換。大型 Node.js 專案、依賴大量原生擴充的專案、生產穩定性要求極高的服務，仍然需要逐項驗證相容性、建置行為、測試行為和部署方式。

Bun 是什麼

按照官方 README 的描述，Bun 是一個面向 JavaScript 和 TypeScript 應用的一體化工具包。它以單一可執行檔 bun 發布。

它的核心是 Bun runtime：一個快速 JavaScript 執行時，目標是作為 Node.js 的 drop-in replacement。Bun 使用 Zig 編寫，底層基於 JavaScriptCore，重點優化啟動時間和記憶體占用。

這意味著你可以直接執行：

`1`	`bun run index.tsx`

TypeScript 和 JSX 不需要額外設定就能跑。

同一個 bun 命令還包含：

test runner
script runner
Node.js 相容套件管理器
bundler
package runner

常見命令包括：

bun test
bun run start
bun install <pkg>
bunx cowsay 'Hello, world!'

過去一個專案裡可能同時出現 node、npm、pnpm、tsx、jest、vitest、webpack、esbuild、ts-node 等工具。Bun 的路線是盡量把高頻路徑收進一個工具裡。

安裝方式

Bun 支援 Linux、macOS 和 Windows，覆蓋 x64 與 arm64。

官方推薦安裝腳本：

`1`	`curl -fsSL https://bun.com/install \| bash`

Windows：

`1`	`powershell -c "irm bun.sh/install.ps1 \| iex"`

也可以透過 npm 安裝：

`1`	`npm install -g bun`

macOS Homebrew：

1
2

brew tap oven-sh/bun
brew install bun

Docker：

1
2

docker pull oven/bun
docker run --rm --init --ulimit memlock=-1:-1 oven/bun

Linux 使用者要注意核心版本。README 提到強烈建議 Linux kernel 5.6 或更高，最低要求是 5.1。

升級到最新版：

`1`	`bun upgrade`

升級到 canary：

`1`	`bun upgrade --canary`

生產環境一般不建議直接用 canary，除非你是在驗證新特性或排查特定 bug。

為什麼 Bun 會快

Bun 的「快」主要來自幾個層面。

第一，執行時啟動快。很多 CLI 工具和開發腳本的瓶頸不是長期 CPU 運算，而是程序啟動、模組載入、TypeScript 轉譯和依賴解析。Bun 針對這些路徑做了很多優化。

第二，套件管理快。bun install 的目標是替代 npm / yarn / pnpm 的依賴安裝流程。它使用全域快取和自己的 lockfile，安裝大量依賴時通常能明顯減少等待。

第三，TypeScript / JSX 開箱即用。很多專案只是想執行一個 .ts 或 .tsx 腳本，傳統 Node.js 工具鏈需要額外加 tsx、ts-node、Babel 或建置步驟。Bun 可以直接跑，減少了膠水工具。

第四，內建工具減少程序和設定切換。測試、腳本、打包、執行都在同一個工具裡，很多場景不用再在多個 CLI 之間切換。

但要注意，「Bun 很快」不等於每個專案都一定更快。真實效果取決於依賴類型、腳本邏輯、測試框架、建置設定、Node.js API 使用情況和 CI 快取策略。

套件管理：替代 npm / yarn / pnpm

Bun 可以直接安裝依賴：

`1`	`bun install`

新增依賴：

`1`	`bun add react`

新增開發依賴：

`1`	`bun add -d typescript`

移除依賴：

`1`	`bun remove react`

查看依賴原因：

`1`	`bun why react`

安全檢查：

`1`	`bun audit`

如果你從 npm 或 pnpm 遷移，重點要看：

bun.lock 是否進入版本控制。
CI 是否使用 bun install --frozen-lockfile。
私有 registry 和 .npmrc 是否相容。
workspace 行為是否符合預期。
lifecycle scripts 是否會帶來安全風險。
原本依賴 pnpm 特性的 monorepo 是否能平順遷移。

小專案可以直接試。大型 monorepo 不建議一次性全切，可以先在單個 package 或 CI 的非關鍵任務裡試。

執行腳本和 TypeScript

Bun 可以執行 package.json 裡的腳本：

`1`	`bun run start`

也可以直接執行檔案：

1
2

bun run index.ts
bun run index.tsx

這對工具腳本很方便，例如：

scripts/build.ts
scripts/seed.ts
scripts/migrate.ts
scripts/check.ts

如果用 Node.js，通常要處理 TypeScript loader 或預編譯問題。Bun 的直接執行能力可以讓這些腳本更輕。

不過，如果腳本依賴 Node.js 特定行為，尤其是 loader、ESM/CJS 邊界、原生模組、child process、檔案監聽和某些邊緣 API，仍然要測試。

測試執行器

Bun 內建測試執行器：

`1`	`bun test`

它適合想減少 Jest / Vitest 設定的小專案，也適合把一些單元測試、工具測試、庫測試遷移到更輕的執行方式。

遷移測試時重點關注：

expect 行為差異。
mock API 差異。
snapshot 行為。
DOM 測試環境。
測試發現規則。
覆蓋率輸出。
CI reporter 支援。

如果專案已經深度依賴 Jest 生態，例如大量自訂 matcher、複雜 mock、jsdom、babel-jest、ts-jest，遷移就不要太急。可以先讓新模組用 bun test，舊測試繼續保留原框架。

打包和建置

Bun 也提供 bundler，常見用法是：

`1`	`bun build ./src/index.ts --outdir ./dist`

它可以用於前端包、後端腳本、CLI 工具和庫建置。Bun 文件還覆蓋 loaders、plugins、macros、CSS、HTML、HMR、minifier、single-file executable 等方向。

適合優先嘗試的場景：

小型前端工具。
Node.js CLI。
內部腳本。
單檔服務。
不依賴複雜 webpack loader 的專案。

謹慎遷移的場景：

複雜 webpack 外掛鏈。
大量 Vite 外掛。
深度依賴 Babel 轉換。
特殊 CSS / asset pipeline。
微前端和模組聯邦。
對建置產物 hash、chunk、相容性要求很細的專案。

Bun bundler 很有吸引力，但建置工具遷移的風險通常比套件管理更高，最好單獨驗證。

執行 HTTP 服務

Bun 提供 Bun.serve 來寫 HTTP 服務：

Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello from Bun")
  },
})

這對小型 API、內部服務、Webhook receiver、邊緣風格服務很方便。Bun 還提供 WebSockets、Workers、Streams、SQLite、PostgreSQL、Redis、S3、TCP/UDP sockets 等 API。

如果你已有 Express、Fastify、NestJS、Next.js、Hono、Elysia 等框架，也可以先看它們在 Bun 上的相容程度，不必為了用 Bun 就重寫服務。

更現實的路徑是：

先用 Bun 做開發腳本和套件管理。
再用 Bun 跑測試。
最後評估是否把執行時切到 Bun。

執行時遷移最需要謹慎，因為它直接影響生產服務行為。

和 Node.js 的關係

Bun 的目標之一是作為 Node.js 的 drop-in replacement，但「相容」不是「完全等同」。

Node.js 生態已經累積很多年，很多套件依賴細微行為：

CJS / ESM 互操作。
Node 內建模組。
原生擴充。
npm lifecycle scripts。
檔案系統邊緣行為。
stream 和 Buffer 細節。
worker / child_process。
除錯和 profiling。

Bun 在相容性上進步很快，但生產遷移仍要以測試結果為準。

比較穩妥的判斷方式：

你的測試能否在 Bun 下通過。
關鍵依賴是否支援 Bun。
建置產物是否一致。
CI 和本地表現是否一致。
線上執行是否有監控和回滾。
Docker 映像和部署腳本是否穩定。

如果只是替換套件管理器，風險較低；如果替換生產執行時，風險高很多。

適合哪些專案

Bun 很適合這些場景：

新的 JavaScript / TypeScript 小專案。
內部工具和腳本。
CLI 專案。
需要快速安裝依賴的 CI。
希望減少工具鏈複雜度的前端專案。
對啟動速度敏感的腳本和服務。
想用 TypeScript 開箱即跑的開發者。

暫時要謹慎的場景：

超大型 monorepo。
深度綁定 pnpm workspace 行為的專案。
依賴大量 Node.js 原生擴充的服務。
建置鏈路高度客製的前端工程。
對生產執行時一致性要求極高的後端。
依賴 Jest 複雜生態的測試套件。

一個保守但實用的策略是：先把 Bun 當作開發工具，而不是馬上替代全部生產執行時。

遷移建議

如果想在現有專案試 Bun，可以按這個順序：

在本地安裝 Bun。
執行 bun install，觀察依賴安裝結果。
提交或暫存 bun.lock，避免和舊 lockfile 混用造成混亂。
嘗試 bun run <script> 跑常用腳本。
用 bun test 遷移少量測試。
在 CI 加一個非阻塞 Bun job。
確認沒有相容問題後，再考慮替換主安裝流程。
最後再評估生產執行時是否切換。

對團隊專案，最好保留回滾路徑：

遷移前保留原 npm / pnpm / yarn 流程。
CI 裡同時跑一段時間。
不要在同一次改動裡同時換執行時、套件管理器、測試框架和打包器。
把遷移拆成小步驟，每一步都有可驗證收益。

這樣做雖然慢一點，但不容易把問題混在一起。

常見命令速查

安裝：

`1`	`curl -fsSL https://bun.com/install \| bash`

升級：

`1`	`bun upgrade`

安裝依賴：

`1`	`bun install`

新增依賴：

`1`	`bun add lodash`

執行腳本：

`1`	`bun run dev`

直接執行 TypeScript：

`1`	`bun run scripts/build.ts`

測試：

`1`	`bun test`

打包：

`1`	`bun build ./src/index.ts --outdir ./dist`

執行套件命令：

`1`	`bunx cowsay 'Hello, world!'`

總結

Bun 的價值不只是「比 Node.js 快」。更重要的是，它把 JavaScript / TypeScript 開發裡一堆分散工具收進一個 bun 命令：執行時、套件管理器、腳本執行器、測試執行器和打包器。

對新專案和內部工具來說，這種一體化體驗很舒服：安裝快、啟動快、設定少，TypeScript 和 JSX 也能直接跑。對已有大型專案來說，Bun 更適合先從低風險環節切入，例如套件安裝、腳本和部分測試，再逐步驗證建置和執行時。

如果你經常被 Node.js 工具鏈裡的安裝速度、設定碎片和測試啟動時間折磨，Bun 值得認真試一下。但真正遷移生產服務時，還是要回到最樸素的工程判斷：測試能不能過、依賴是否相容、CI 是否穩定、線上有沒有回滾。

參考連結：

Godot 遊戲開發入門：從節點、場景到第一個 2D 小遊戲

Sun, 17 May 2026 12:37:30 +0800

Godot 是一款開源遊戲引擎，適合從 2D 小遊戲、獨立遊戲原型，到中等規模的 3D 專案開發。

它最大的特點是輕量、開源、啟動快，節點和場景系統非常清晰。對新手來說，Godot 的門檻通常比 Unity 低；對獨立開發者來說，它不繫結商業授權模式，也更容易做出可控的小專案。

這篇文章用最少概念把 Godot 的入門路線講清楚：你先理解節點和場景，再學 GDScript，最後用一個 2D 小遊戲把輸入、物理、碰撞、UI、音效和匯出串起來。

先說結論

Godot 入門不要一上來就學大而全的引擎功能。

更合理的路線是：

先做 2D，不急著做 3D。
先理解節點和場景，不急著寫複雜架構。
先學 GDScript，不急著上 C#。
先做一個能跑、能失敗、能重開的小遊戲。
再逐步補動畫、音效、UI、關卡和匯出。

只要做完一個完整小專案，你對 Godot 的理解會比刷十幾個零散教程更穩。

Godot 適合什麼人

Godot 很適合這幾類人：

想從零開始學遊戲開發。
想做 2D 獨立遊戲。
想快速做玩法原型。
不想被複雜商業引擎工具鏈壓住。
想理解遊戲引擎底層組織方式。
有一點 Python / JavaScript 經驗，想快速上手指令碼。

如果你的目標是大型 3A 畫面、複雜商業團隊管線、現成資產商店生態，Unity 或 Unreal 可能仍然更成熟。但如果目標是學習和做自己的遊戲，Godot 非常適合起步。

安裝和專案建立

Godot 的安裝很簡單。

到官網下載安裝包，解壓後直接執行即可。它不像很多大型引擎那樣必須先裝完整啟動器，也不需要複雜賬號流程。

新建專案時，建議先選：

Renderer：預設即可。
Project Name：用英文短橫線或下劃線。
路徑：不要放在中文或空格特別多的目錄裡。
版本管理：建議從一開始就用 Git。

第一個專案可以叫：

`1`	`first-godot-game`

專案建立後，Godot 會進入編輯器。你需要先熟悉幾個區域：

Scene：當前場景的節點樹。
FileSystem：專案資源目錄。
Inspector：選中節點的屬性面板。
Script：指令碼編輯區。
2D / 3D 檢視：編輯畫面和物件位置。

Godot 的核心：節點和場景

Godot 最重要的概念只有兩個：節點和場景。

節點是功能單元。比如：

Node2D：2D 物件基礎節點。
Sprite2D：顯示圖片。
CollisionShape2D：碰撞形狀。
CharacterBody2D：可移動角色。
Camera2D：2D 攝像機。
AudioStreamPlayer：播放音訊。
Label：顯示文字。

場景是一組節點的組合。一個角色可以是一個場景，一個敵人可以是一個場景，一個關卡也可以是一個場景。

比如一個玩家角色場景可能長這樣：

Player (CharacterBody2D)
├── Sprite2D
├── CollisionShape2D
└── Camera2D

這棵樹的意思是：玩家本體負責移動，Sprite2D 負責顯示角色圖片，CollisionShape2D 負責碰撞，Camera2D 跟隨玩家。

Godot 的思路就是：把遊戲拆成很多可複用場景，再把場景組合成完整遊戲。

第一個 2D 專案做什麼

新手第一個專案不要做 RPG、開放世界、聯機遊戲或複雜平臺跳躍。

建議做一個最小 2D 閃避遊戲：

玩家可以上下左右移動。
敵人從螢幕邊緣出現。
玩家碰到敵人就失敗。
存活時間越長分數越高。
有開始按鈕、失敗介面和重新開始。

這個專案很小，但能覆蓋 Godot 入門最重要的東西：

角色移動。
輸入系統。
碰撞檢測。
敵人生成。
UI 顯示。
定時器。
音效。
場景切換。

做完它，你就已經跨過了“只會看教程，不知道怎麼組織專案”的第一道坎。

玩家移動怎麼寫

在 Godot 裡，玩家角色通常用 CharacterBody2D。

給 Player 節點掛一個指令碼：

extends CharacterBody2D

@export var speed := 300.0

func _physics_process(delta):
    var direction := Vector2.ZERO

    direction.x = Input.get_axis("move_left", "move_right")
    direction.y = Input.get_axis("move_up", "move_down")
    direction = direction.normalized()

    velocity = direction * speed
    move_and_slide()

這段程式碼做了幾件事：

讀取水平和垂直方向輸入。
把方向向量歸一化，避免斜向移動更快。
把方向乘以速度，得到 velocity。
用 move_and_slide() 讓角色移動並處理碰撞。

還需要在 Project Settings 裡設定輸入：

move_left  -> A / Left
move_right -> D / Right
move_up    -> W / Up
move_down  -> S / Down

Godot 的輸入系統建議一開始就用 action，不要在程式碼裡直接寫死鍵盤按鍵。這樣以後支援手柄、觸屏或改鍵會方便很多。

碰撞和物理怎麼理解

Godot 的碰撞不是隻靠圖片大小判斷，而是靠碰撞形狀。

常用節點有：

CollisionShape2D：給角色或敵人定義碰撞範圍。
Area2D：檢測進入、離開、重疊，適合觸發器。
CharacterBody2D：適合玩家和會移動的角色。
RigidBody2D：適合受物理力影響的物體。
StaticBody2D：適合牆、地面、固定障礙。

入門階段記住一個原則：

如果你要自己控制角色移動，用 CharacterBody2D。

如果你只想檢測“玩家碰到敵人”，敵人可以用 Area2D，再監聽訊號：

1
2
3

func _on_body_entered(body):
    if body.name == "Player":
        get_tree().reload_current_scene()

後面專案變複雜時，可以改成傳送 game_over 訊號，而不是直接過載場景。新手階段先跑通邏輯更重要。

場景例項化：讓敵人不斷出現

Godot 的場景可以當成“預製體”使用。

假設你有一個 Enemy.tscn，可以在主場景裡用指令碼生成它：

@export var enemy_scene: PackedScene

func spawn_enemy():
    var enemy = enemy_scene.instantiate()
    enemy.position = Vector2(800, randf_range(50, 550))
    add_child(enemy)

再配合 Timer 節點，每隔一段時間呼叫一次 spawn_enemy()，敵人就會不斷生成。

這就是 Godot 專案常見組織方式：

一個場景負責一種物件。
主場景負責排程和組合。
需要時動態例項化子場景。

UI 和分數

Godot 的 UI 使用 Control 系列節點。

常用節點包括：

CanvasLayer：讓 UI 固定在螢幕上，不跟隨相機移動。
Label：顯示文字。
Button：按鈕。
Panel：面板背景。
VBoxContainer / HBoxContainer：自動排版。

分數可以先用存活時間來做：

var score := 0.0

func _process(delta):
    score += delta
    $CanvasLayer/ScoreLabel.text = str(int(score))

這樣每秒增加 1 分。後面可以改成擊敗敵人、收集金幣或完成關卡加分。

音效和反饋

小遊戲好不好玩，很大一部分來自反饋。

即使畫面很簡單，也要加：

移動或點選音效。
碰撞音效。
得分音效。
失敗音效。
螢幕震動或閃爍。
按鈕 hover / pressed 狀態。

Godot 裡可以用 AudioStreamPlayer 播放音效：

`1`	`$HitSound.play()`

新手常犯的錯誤是隻做功能，不做反饋。功能能跑只是第一步，玩家能不能感到“我做了一個動作，遊戲回應了我”，才是遊戲體驗的開始。

檔案怎麼組織

專案一開始就建議整理目錄：

res://
├── scenes/
│   ├── Main.tscn
│   ├── Player.tscn
│   └── Enemy.tscn
├── scripts/
│   ├── player.gd
│   └── enemy.gd
├── assets/
│   ├── sprites/
│   └── audio/
└── ui/
    └── GameOver.tscn

不要把所有資源都丟在根目錄。小遊戲階段無所謂，專案稍微大一點就會混亂。

一個簡單原則是：

場景放 scenes/。
指令碼放 scripts/。
圖片和音訊放 assets/。
UI 單獨放 ui/。

Godot 新手常見坑

第一個坑：節點選錯。

能自己控制移動的角色用 CharacterBody2D，不是隨便用 Node2D。觸發檢測用 Area2D，固定障礙用 StaticBody2D。

第二個坑：忘記碰撞形狀。

只有圖片沒有碰撞體，遊戲不會知道它們撞上了。

第三個坑：把按鍵寫死。

不要直接判斷 KEY_A，用輸入 action。

第四個坑：場景職責混亂。

不要讓一個指令碼同時管玩家、敵人、UI、音效和關卡。新手可以簡單，但不要所有東西都堆在 Main.gd。

第五個坑：一開始就做大專案。

第一個專案越小越好。只要完整，有開始、有失敗、有重新開始，就比半途而廢的大專案更有價值。

Godot 和 Unity 怎麼選

如果你主要做 2D 獨立遊戲、教學專案、個人原型，Godot 非常舒服。

如果你需要龐大的資產商店、成熟商業外掛、移動廣告和商業化 SDK、成熟團隊經驗，Unity 生態仍然更強。

如果你要做高規格 3D、複雜渲染、影視級畫面，Unreal 更適合。

對新手來說，不要把選引擎變成拖延。Godot 足夠你做出大量完整小遊戲。你真正需要先學會的是：

遊戲迴圈。
輸入響應。
碰撞和反饋。
場景組織。
狀態管理。
資源和版本管理。

這些能力換到其他引擎也能用。

第一個專案的完成標準

你可以用這個清單判斷自己是否真的入門：

玩家能移動。
有敵人或障礙。
有碰撞失敗。
有分數或目標。
有開始介面。
有失敗介面。
能重新開始。
有至少兩個音效。
有簡單動畫或視覺反饋。
能匯出一個可執行版本。

做到這裡，你就不是“開啟過 Godot”，而是真的完成了一個遊戲閉環。

總結

Godot 入門的關鍵，不是把所有功能看一遍，而是先理解它的組織方式：節點組成場景，場景組成遊戲，指令碼驅動行為，訊號連線事件，資源透過目錄管理。

第一個專案建議從 2D 小遊戲開始。玩家移動、敵人生成、碰撞失敗、UI 分數、音效反饋、重新開始，這幾個環節跑通之後，再去學動畫樹、TileMap、存檔、狀態機、3D、Shader 和匯出最佳化。

遊戲開發不是先學完引擎再開始做，而是在做小專案的過程中反覆補概念。Godot 的優勢正好在這裡：它足夠輕，能讓你很快從“想做遊戲”走到“真的跑起來”。

Ghostty 文件速讀：安裝、設定與日常使用要點

Fri, 15 May 2026 14:50:11 +0800

Ghostty 是一個新的終端模擬器，但它不只是「又一個更快的終端」。按照官方文件的說法，它想同時兼顧三個方向：速度、功能和原生桌面體驗。也就是說，它既希望有 GPU 加速和較好的渲染效能，也希望在 macOS 和 Linux 上盡量像一個真正的本機應用，而不是把所有互動都塞進自繪介面裡。

如果你正在用 iTerm2、Kitty、Alacritty、WezTerm 或系統內建終端，Ghostty 最值得關注的地方不是某一個單點功能，而是它把「開箱即用」和「深度可設定」放在了一起。預設設定已經能直接使用；想繼續折騰時，文件又給了設定檔、主題、快捷鍵、字型、Shell 整合和終端控制序列等完整入口。

先看定位

Ghostty 的核心定位可以概括為三句話：

它是跨平台終端模擬器，目前重點覆蓋 macOS 和 Linux。
它使用平台原生 UI：macOS 端使用 Swift、AppKit 和 SwiftUI，Linux 端使用 Zig 和 GTK4。
它的終端核心是 libghostty，GUI 應用圍繞這個共享核心構建。

這個設計會影響日常體驗。比如分頁、分割視窗、錯誤提示、視窗狀態恢復、系統快捷鍵等能力，不是簡單做成「看起來像桌面應用」的元件，而是盡量貼近所在系統的互動習慣。macOS 和 Linux 預設快捷鍵也會按各自平台約定區分。

安裝方式：macOS 最直接，Linux 看發行版

官方預構建二進位主要面向 macOS。最普通的安裝方式是下載 .dmg，打開後把 Ghostty 拖到 Applications 目錄。Homebrew 使用者也可以用社群維護的 cask：

`1`	`brew install --cask ghostty`

Linux 的情況更分散。Ghostty 文件把不同發行版的套件管理器、社群二進位和原始碼構建分開說明。Arch、Alpine、Gentoo、NixOS、Snap、Solus、Void 等都有對應路徑；如果發行版沒有官方或可信倉庫，文件更傾向於讓使用者從原始碼構建，而不是隨意安裝第三方二進位。

這點對伺服器和工作機尤其重要：終端模擬器會處理大量輸入輸出、剪貼簿、連結、SSH 工作階段和本機檔案路徑。安裝來源最好保守一點，優先選官方 macOS 套件、發行版倉庫或自己能審計來源的構建流程。

設定：先別急著複製一大份 dotfiles

Ghostty 的設定哲學是「零設定可用」。預設字型內建 JetBrains Mono，也帶有 Nerd Font 支援；多數使用者第一次打開就能正常工作。文件甚至建議，如果你發現必須設定某個非主觀選項才舒服，可以先考慮它是不是應該成為預設行為。

真正需要定製時，Ghostty 使用文字設定檔。當前設定檔名是 config.ghostty，舊版本也支援 config。常見路徑包括：

$XDG_CONFIG_HOME/ghostty/config.ghostty
$XDG_CONFIG_HOME/ghostty/config
$HOME/.config/ghostty/config.ghostty
$HOME/.config/ghostty/config

macOS 還會讀取：

1
2

$HOME/Library/Application Support/com.mitchellh.ghostty/config.ghostty
$HOME/Library/Application Support/com.mitchellh.ghostty/config

設定語法非常直接，就是 key = value。例如：

font-family = JetBrains Mono
font-size = 14
theme = light:Rose Pine Dawn,dark:Rose Pine
keybind = ctrl+shift+t=new_tab

一個實用建議是：不要一開始就找別人的完整設定照抄。更穩的方式是先裸跑幾天，只改三類東西：字型、字號和主題。等你真的發現快捷鍵、分割視窗、視窗、Shell 整合有摩擦，再逐項加設定。

文件查詢：本機也能查完整設定

Ghostty 的設定項很多，官方文件把它們集中在 Option Reference。除了網頁，安裝後也可以從本機查設定參考：

`1`	`ghostty +show-config --default --docs`

這個命令會把預設設定和文件輸出到標準輸出，適合接到分頁器裡慢慢搜尋：

`1`	`ghostty +show-config --default --docs \| less`

查看可用字型時可以用：

`1`	`ghostty +list-fonts`

查看內建和可用主題時可以用：

`1`	`ghostty +list-themes`

查看預設快捷鍵時可以用：

`1`	`ghostty +list-keybinds --default`

這些命令比在網路上複製片段更可靠，因為它們來自你當前安裝的 Ghostty 版本。

快捷鍵：把「動作」當成核心概念

Ghostty 的快捷鍵設定格式是：

`1`	`keybind = trigger=action`

trigger 是按鍵觸發方式，action 是 Ghostty 執行的動作。比如新建分頁、關閉當前 surface、重新載入設定、跳轉到提示符等，都屬於 action。這個模型的好處是清晰：你不是在「改某個選單項」，而是在把一個輸入序列綁定到一個動作。

設定改完後，可以在執行時重新載入。預設快捷鍵是：

Linux：ctrl+shift+,
macOS：cmd+shift+,

不過並不是所有設定都能即時生效。有些選項只影響新建終端，有些需要完整重啟。遇到「設定寫了但沒變化」時，先查對應選項說明，比反覆懷疑語法更省時間。

主題和字型：先用內建，再做細調

Ghostty 自帶大量主題，並支援按系統淺色、深色模式切換不同主題：

`1`	`theme = light:Rose Pine Dawn,dark:Rose Pine`

主題也可以來自自訂檔案。文件提醒得很明確：主題檔案本質上也是 Ghostty 設定檔，可以設定很多設定項，所以不要隨便使用不可信來源的主題。

字型方面，font-family 可以重複多次，用來指定 fallback 字型。對多語言環境很實用，比如主字型負責英文和符號，後續字型補中文、日文或其他字元。遇到 emoji、粗體、斜體、連字等顯示細節時，再去 Option Reference 裡查對應選項即可。

Shell 整合：SSH 使用者尤其應該看

Ghostty 支援自動注入 shell integration，覆蓋 bash、elvish、fish、nushell 和 zsh。啟用後，一些體驗會更自然，比如：

新終端從前一個終端的工作目錄打開。
複雜提示符 resize 時可以重繪，而不是被錯誤回流。
可以透過提示符標記在命令輸出之間跳轉。
在提示符處支援更符合編輯習慣的游標行為。

如果不想自動注入，可以在設定裡關閉：

`1`	`shell-integration = none`

更值得注意的是 SSH。Ghostty 使用 xterm-ghostty 作為 TERM，但很多遠端主機還沒有對應的 terminfo。文件提供了 ssh-env 和 ssh-terminfo 兩個 shell integration 功能，預設關閉，可以按需啟用：

`1`	`shell-integration-features = ssh-env,ssh-terminfo`

如果你經常連接舊伺服器、容器、跳板機或嚴格管理的生產環境，建議先讀完官方的 Terminfo 和 Shell Integration 文件，再決定是否啟用這些功能。終端能力協商看起來不起眼，但一旦出問題，表現可能是顏色異常、快捷鍵失靈、全螢幕程式顯示錯亂。

我的上手順序

如果只是想判斷 Ghostty 是否適合自己，可以按這個順序試：

安裝後不寫設定，直接用一天。
只調整 font-family、font-size 和 theme。
用 ghostty +list-keybinds --default 看預設快捷鍵，而不是先搬運別人的快捷鍵表。
如果常用 SSH，優先檢查遠端主機的 terminfo 相容問題。
最後再處理分割視窗、視窗、透明度、標題列、背景圖等視覺和工作流偏好。

Ghostty 文件寫得比較工程化，適合把它當成「設定參考手冊」而不是「宣傳頁」閱讀。對多數使用者來說，真正的判斷標準也很簡單：預設體驗是否已經舒服，日常編輯器、Shell、SSH、tmux 或 Zellij 是否穩定。如果這幾件事都順，Ghostty 就值得進入你的長期終端候選列表。

參考連結

VS Code 切換介面語言的方法：中文、英文和其他語言

Fri, 08 May 2026 13:18:57 +0800

VS Code 支援多種介面語言。常見做法是先安裝對應語言套件，再透過命令面板選擇顯示語言；如果需要固定某種語言，也可以手動修改 argv.json 中的 locale。

這套方法不只適用於簡體中文，也適用於英文、繁體中文、日文、韓文、法文、德文、西班牙文等語言。

安裝對應語言套件

如果要切換到非英文介面，通常需要先安裝語言套件。

開啟 VS Code 左側擴充功能面板，也可以使用快捷鍵 Ctrl+Shift+X。
在搜尋框中輸入目標語言，例如 Chinese、Japanese、Korean、French。
選擇對應語言套件，點擊 Install。
安裝完成後，依提示重新啟動 VS Code。

簡體中文常用語言套件是 Chinese (Simplified)，繁體中文常用語言套件是 Chinese (Traditional)。

透過命令面板切換語言

這是最推薦的切換方式，適合大多數使用者。

開啟命令面板：Ctrl+Shift+P。
輸入 Configure Display Language。
選擇 Configure Display Language 命令。
在列表中選擇要使用的語言。
依提示重新啟動 VS Code。

重新啟動後，選單、設定頁和常見提示會切換到所選語言。如果列表裡沒有目標語言，先到擴充功能面板安裝對應語言套件。

透過 argv.json 手動指定語言

如果命令面板切換失敗，或者想明確固定顯示語言，可以直接修改 VS Code 的執行階段參數檔案。

開啟命令面板：Ctrl+Shift+P。
輸入並選擇 Preferences: Configure Runtime Arguments。
找到或新增 locale 設定項。
將它改成目標語言代碼。
儲存後重新啟動 VS Code。

例如切換為英文：

1
2
3

{
  "locale": "en"
}

切換為簡體中文：

1
2
3

{
  "locale": "zh-cn"
}

切換為日文：

1
2
3

{
  "locale": "ja"
}

argv.json 是 JSON 檔案，修改時要注意逗號和引號。設定寫錯時，VS Code 可能無法正確讀取語言設定。

常用介面語言代碼

顯示語言	locale
English (US)	`en`
簡體中文	`zh-cn`
繁體中文	`zh-tw`
French	`fr`
German	`de`
Italian	`it`
Spanish	`es`
Japanese	`ja`
Korean	`ko`
Russian	`ru`
Portuguese (Brazil)	`pt-br`
Turkish	`tr`
Bulgarian	`bg`
Hungarian	`hu`

語言沒有生效怎麼辦

可以按下面順序排查：

確認目標語言套件已經安裝。
確認 locale 寫的是正確語言代碼，例如簡體中文是 zh-cn，不是 zh-CN。
修改語言後完整關閉並重新開啟 VS Code。
如果手動改過 argv.json，檢查 JSON 語法是否正確。
如果設定混亂，可以刪除 locale 項，再透過 Configure Display Language 重新選擇。

一般來說，透過 Configure Display Language 切換最省事；只有在需要強制指定語言或命令面板切換不生效時，才建議手動修改 argv.json。

參考資料

VScode：將VScode界面的顯示語言改為簡體中文，切換VScode界面的顯示語言

opencode、Claude Code、Codex 有什麼區別？開源 AI 編程工具使用指南

Fri, 08 May 2026 08:33:37 +0800

opencode 是 anomalyco 開源的 AI Coding Agent。它的定位很直接：讓開發者在終端裡使用一個可程式化、可擴充、可接入多家模型的程式碼助手。

如果把它和 Claude Code、Codex 放在一起看，三者解決的是同一類問題：讓 AI 進入真實程式碼庫，理解上下文，修改檔案，執行命令和測試。但它們的產品取向不一樣。

opencode 更強調開源、多模型和終端 TUI；Claude Code 更強調 Anthropic 模型生態和本地工程協作；Codex 則是 OpenAI 的 AI coding agent，可以在終端、IDE、Codex app 和雲端任務裡使用。

opencode 適合誰

opencode 更適合這幾類開發者：

想在終端裡完成程式碼修改、專案分析和工程任務的人。
希望 AI Coding Agent 不綁定單一模型提供商的人。
偏好開源工具，想自己審計、擴充或二次開發的人。
已經習慣 Neovim、TUI、命令列工作流的人。
希望以後用桌面端、行動端或其他客戶端遠端驅動同一個編碼代理的人。

它的重點不是做一個聊天視窗，而是把 AI 編程能力放進開發者原本使用的終端和專案目錄裡。

安裝方式

官方 README 提供了多種安裝方式。

# 直接安裝
curl -fsSL https://opencode.ai/install | bash

# npm
npm i -g opencode-ai@latest

# Windows
scoop install opencode
choco install opencode

# macOS 和 Linux
brew install anomalyco/tap/opencode
brew install opencode

# Arch Linux
sudo pacman -S opencode
paru -S opencode-bin

# 其他方式
mise use -g opencode
nix run nixpkgs#opencode

官方也提醒，安裝前最好先移除 0.1.x 之前的舊版本，避免舊版本殘留造成問題。

安裝腳本會按優先級選擇安裝目錄：

$OPENCODE_INSTALL_DIR
$XDG_BIN_DIR
$HOME/bin
$HOME/.opencode/bin

如果需要指定路徑，可以這樣寫：

1
2

OPENCODE_INSTALL_DIR=/usr/local/bin curl -fsSL https://opencode.ai/install | bash
XDG_BIN_DIR=$HOME/.local/bin curl -fsSL https://opencode.ai/install | bash

桌面應用還在 Beta

除了命令列工具，opencode 也提供桌面應用，目前仍處於 Beta。可以從 GitHub Releases 或 opencode.ai/download 下載。

桌面端覆蓋這些平台：

平台	檔案
macOS Apple Silicon	`opencode-desktop-mac-arm64.dmg`
macOS Intel	`opencode-desktop-mac-x64.dmg`
Windows	`opencode-desktop-windows-x64.exe`
Linux	`.deb`、`.rpm` 或 `.AppImage`

macOS 和 Windows 也可以透過套件管理器安裝桌面端。

# macOS
brew install --cask opencode-desktop

# Windows
scoop bucket add extras
scoop install extras/opencode-desktop

兩種內建 Agent 模式

opencode 內建兩種 Agent，可以透過 Tab 鍵切換。

build 是預設模式，擁有完整開發權限，適合直接修改程式碼、執行命令和推進工程任務。

plan 是唯讀模式，更適合分析陌生程式碼庫、理解專案結構、制定修改方案。它預設拒絕檔案編輯，並且在執行 bash 命令前會詢問。

另外，opencode 還帶有一個 general 子 Agent，用於複雜搜尋和多步驟任務。使用者可以在訊息中輸入 @general 呼叫。

這個設計比較實用：真正動手前先用 plan 看清楚專案，需要改程式碼時再切到 build。對於大型倉庫，讀寫權限分開能減少誤操作。

Codex 是什麼

Codex 是 OpenAI 的 AI coding agent，用來幫助開發者寫程式碼、審查程式碼、修復 bug 和交付工程任務。

和單純的程式碼補全工具不同，Codex 更接近一個可以操作程式碼庫的 Agent。它可以在本地工具裡和你結對，也可以把任務委託到雲端執行。OpenAI 官方資料裡提到，Codex 可以透過 CLI、IDE、Codex app、ChatGPT/Codex 雲端等不同入口使用。

對開發者來說，Codex 的重點有幾處：

可以讀取程式碼庫、編輯檔案、執行命令和測試。
支援終端、IDE、應用和雲端等多種使用介面。
適合修 bug、寫功能、重構、遷移、程式碼審查和測試補齊。
更偏 OpenAI 帳號、模型和 Codex 產品體系。
雲端任務適合並行處理多個相對清晰的工程任務。

如果 opencode 更像一個開放的終端代理框架，Codex 更像 OpenAI 提供的一整套 AI 編程工作台：本地可以結對，雲端可以委託，團隊可以把它接入更長的工程流程。

三者核心區別

opencode、Claude Code、Codex 都是 AI 編程工具，但選擇時可以先看這幾個維度。

工具	核心定位	主要優勢	更適合
`opencode`	開源 AI Coding Agent	開源、多模型、TUI、客戶端/伺服器架構	想要開放工具鏈、可替換模型、偏終端工作流的開發者
`Claude Code`	Anthropic 的命令列編程工具	Claude 模型體驗、程式碼理解、長上下文、工程任務協作	已經使用 Claude/Anthropic 生態，希望本地推進程式碼任務的開發者
`Codex`	OpenAI 的 AI coding agent	CLI、IDE、Codex app、雲端任務、多 Agent 工作流	已經使用 ChatGPT/OpenAI，希望本地結對和雲端委託並用的團隊

簡單說，opencode 的關鍵詞是「開源和可替換」，Claude Code 的關鍵詞是「Claude 生態和本地工程代理」，Codex 的關鍵詞是「OpenAI 生態和多入口協作」。

和 Claude Code 的區別

opencode 的官方 FAQ 直接把 Claude Code 拿來對比。兩者能力上很接近，但差異主要在這幾處。

第一，opencode 是 100% 開源專案，程式碼託管在 GitHub，並使用 MIT license。

第二，opencode 不綁定單一模型提供商。它推薦 OpenCode Zen 提供的模型，但也可以搭配 Claude、OpenAI、Google 或本地模型。對開發者來說，這意味著模型成本、能力和可用性變化時，不必被某一個平台鎖住。

第三，opencode 內建可選的 LSP 支援。對程式碼補全、跳轉、診斷和專案理解來說，LSP 是非常關鍵的基礎能力。

第四，opencode 更強調 TUI。它由 Neovim 使用者和 terminal.shop 的建立者打造，產品重心明顯放在終端體驗上。

第五，opencode 採用客戶端/伺服器架構。也就是說，opencode 可以在你的電腦上執行，未來由 TUI、桌面端、行動端或其他客戶端來控制。TUI 只是其中一種前端形態。

什麼時候選 opencode、Claude Code 或 Codex

如果你已經在使用 Claude Code 或 Codex，opencode 不一定是立刻替換它們的工具。更合理的看法是：它提供了一個開源、可替換模型、偏終端的選擇。

可以優先考慮 opencode 的場景包括：

你希望 AI 編程工具盡量開源。
你不想把工作流綁定在某個模型供應商上。
你希望用同一個工具測試 Claude、OpenAI、Google 或本地模型。
你喜歡 TUI，不希望主要工作流被桌面應用或網頁應用打斷。
你關注客戶端/伺服器架構帶來的遠端控制能力。

可以優先考慮 Claude Code 的場景包括：

你主要使用 Claude 模型。
你重視長上下文、程式碼理解和複雜工程任務協作。
你希望在本地倉庫中持續推進修改、測試和重構。
你更信任 Anthropic 對 Claude Code 的預設產品體驗。

可以優先考慮 Codex 的場景包括：

你已經在使用 ChatGPT 或 OpenAI 帳號體系。
你希望同一個 coding agent 覆蓋終端、IDE、桌面應用和雲端任務。
你想把較清晰的 bug 修復、功能開發、遷移、測試補齊交給雲端並行處理。
你需要程式碼審查、背景任務、團隊協作和多 Agent 工作流。

如果你更看重官方閉環體驗、模型預設配置、企業管理和現成整合，Claude Code 或 Codex 可能更省心；如果你更看重可控性、開放性和 provider-agnostic，opencode 更值得關注。

需要注意的地方

opencode、Claude Code 和 Codex 都發展很快，GitHub release、安裝命令、桌面端檔名、模型可用性和方案權限都可能變化。實際安裝和選型前，最好直接查看各自官方 README、文件和發布頁面。

另外，它的桌面應用仍然標註為 Beta，不適合預設當作穩定生產工具。對於日常工程任務，終端版仍然是更主要的入口。

從工具趨勢看，opencode 代表的是 AI Coding Agent 的開放工具鏈方向：模型可以替換，客戶端可以替換，核心代理能力盡量開放。Codex 和 Claude Code 則更像模型公司把 coding agent 做成完整產品入口。對開發者來說，這兩條路線會長期並存。

參考連結

opencode GitHub：https://github.com/anomalyco/opencode
opencode 官網：https://opencode.ai
opencode 文件：https://opencode.ai/docs
opencode Releases：https://github.com/anomalyco/opencode/releases
OpenAI Codex：https://openai.com/codex/
Using Codex with your ChatGPT plan：https://help.openai.com/en/articles/11369540-codex-in-chatgpt
OpenAI Codex CLI Getting Started：https://help.openai.com/en/articles/11096431-openai-codex-ci-getting-started

uv 安裝指南：macOS、Linux、Windows、pipx、Homebrew 和 WinGet 怎麼選

Thu, 07 May 2026 23:23:58 +0800

uv 是 Astral 推出的 Python 工具鏈管理器，可以用來管理 Python 版本、虛擬環境、依賴、腳本、專案和工具。它的安裝方式很多，官方文件提供了獨立安裝腳本，也支援 PyPI、Homebrew、WinGet、Scoop、Docker、GitHub Releases 和 Cargo。

如果只是想快速安裝，優先使用官方獨立安裝腳本。如果你希望透過系統套件管理器維護版本，就用 Homebrew、WinGet 或 Scoop。如果你已經習慣用隔離方式安裝 Python 工具，可以用 pipx。

快速選擇

場景	推薦方式	命令
macOS / Linux 快速安裝	官方獨立安裝腳本	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
macOS / Linux 沒有 curl	官方腳本 + wget	`wget -qO- https://astral.sh/uv/install.sh \| sh`
Windows 快速安裝	PowerShell 安裝腳本	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`
Python 工具隔離安裝	pipx	`pipx install uv`
臨時或傳統 Python 安裝	pip	`pip install uv`
macOS 套件管理	Homebrew	`brew install uv`
macOS MacPorts 使用者	MacPorts	`sudo port install uv`
Windows 套件管理	WinGet	`winget install --id=astral-sh.uv -e`
Windows Scoop 使用者	Scoop	`scoop install main/uv`
Rust 使用者	Cargo	`cargo install --locked uv`

最推薦的通用方案：

macOS / Linux：官方獨立安裝腳本；
Windows：官方 PowerShell 安裝腳本或 WinGet；
已經使用 pipx 管理 Python CLI 工具：pipx install uv。

macOS 和 Linux：官方安裝腳本

官方最直接的安裝方式，是用 curl 下載腳本並交給 sh 執行：

`1`	`curl -LsSf https://astral.sh/uv/install.sh \| sh`

如果系統沒有 curl，可以用 wget：

`1`	`wget -qO- https://astral.sh/uv/install.sh \| sh`

如果想安裝指定版本，可以把版本號放進 URL。比如官方範例中的 0.11.11：

`1`	`curl -LsSf https://astral.sh/uv/0.11.11/install.sh \| sh`

這個方式適合絕大多數個人開發環境。它的優點是簡單、跨平台，並且和 uv 官方更新機制配合最好。

安裝腳本會把 uv、uvx 等二進位檔安裝到使用者目錄下，並可能修改 shell profile，讓命令可以直接在終端機中使用。如果你不希望安裝器修改 PATH，可以參考官方 installer 選項，例如設定 UV_NO_MODIFY_PATH=1。

Windows：PowerShell 安裝腳本

Windows 官方安裝方式是用 PowerShell 執行安裝腳本：

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"`

如果要安裝指定版本，也可以把版本號放進 URL：

`1`	`powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.11.11/install.ps1 \| iex"`

這裡的 ExecutionPolicy ByPass 是為了允許從網際網路取得並執行安裝腳本。從安全習慣來看，執行前可以先查看腳本內容：

`1`	`powershell -c "irm https://astral.sh/uv/install.ps1 \| more"`

如果你習慣 Windows 套件管理器，也可以優先用 WinGet 或 Scoop。

用 pipx 安裝

官方文件提到，uv 發布到了 PyPI。如果從 PyPI 安裝，建議放進隔離環境，例如用 pipx：

`1`	`pipx install uv`

這個方式適合已經把 pipx 當作 Python CLI 工具管理器的人。它可以避免把 uv 和目前專案環境混在一起。

如果沒有 pipx，也可以直接用 pip：

`1`	`pip install uv`

但要注意：uv 在許多平台上提供預建 wheel。如果某個平台沒有對應 wheel，就會從原始碼建置，這時需要 Rust 工具鏈。

我的建議是：個人機器上，pipx install uv 比 pip install uv 更乾淨；專案環境裡，不建議把 uv 當作專案依賴安裝。

Homebrew、MacPorts、WinGet 和 Scoop

如果你更喜歡系統套件管理器，uv 也支援常見渠道。

macOS 上用 Homebrew：

`1`	`brew install uv`

MacPorts 使用者可以用：

`1`	`sudo port install uv`

Windows 上用 WinGet：

`1`	`winget install --id=astral-sh.uv -e`

Scoop 使用者可以用：

`1`	`scoop install main/uv`

這些方式的好處是統一交給系統套件管理器維護。缺點是升級節奏取決於對應套件來源，而不是 uv 官方安裝腳本。

Docker、GitHub Releases 和 Cargo

uv 還提供 Docker 映像，地址在 GitHub Container Registry：

`1`	`ghcr.io/astral-sh/uv`

這適合 CI、Dockerfile、建置映像和臨時執行環境。實際使用時，建議再看官方 Docker 整合文件。

如果你想手動下載二進位檔，可以從 GitHub Releases 取得。每個 release 頁面通常包含支援平台的二進位檔，也會說明如何用 GitHub 地址呼叫獨立安裝器。

Rust 使用者也可以從 crates.io 安裝：

`1`	`cargo install --locked uv`

但這個方式會從原始碼建置，需要相容的 Rust 工具鏈。除非你明確需要從 Rust 生態安裝，否則一般使用者不必優先選 Cargo。

升級 uv

如果 uv 是透過官方獨立安裝腳本安裝的，可以用自我更新命令：

`1`	`uv self update`

官方提示說，更新 uv 會重新執行安裝器，並可能修改 shell profile。如果不希望更新時修改 PATH，可以設定：

`1`	`UV_NO_MODIFY_PATH=1`

如果你是透過其他方式安裝的，就應該用對應套件管理器升級。比如用 pip 安裝，就用：

`1`	`pip install --upgrade uv`

Homebrew、WinGet、Scoop、MacPorts 也應該走各自的升級命令。

啟用 shell 自動補全

uv 支援 shell 自動補全。官方文件建議先用下面命令確認目前 shell：

`1`	`echo $SHELL`

Bash：

`1`	`echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc`

Zsh：

`1`	`echo 'eval "$(uv generate-shell-completion zsh)"' >> ~/.zshrc`

fish：

`1`	`echo 'uv generate-shell-completion fish \| source' > ~/.config/fish/completions/uv.fish`

PowerShell：

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uv generate-shell-completion powershell) | Out-String | Invoke-Expression'

如果你也經常用 uvx，可以單獨啟用 uvx 補全。

Bash：

`1`	`echo 'eval "$(uvx --generate-shell-completion bash)"' >> ~/.bashrc`

Zsh：

`1`	`echo 'eval "$(uvx --generate-shell-completion zsh)"' >> ~/.zshrc`

fish：

`1`	`echo 'uvx --generate-shell-completion fish \| source' > ~/.config/fish/completions/uvx.fish`

PowerShell：

if (!(Test-Path -Path $PROFILE)) {
  New-Item -ItemType File -Path $PROFILE -Force
}
Add-Content -Path $PROFILE -Value '(& uvx --generate-shell-completion powershell) | Out-String | Invoke-Expression'

設定後需要重新啟動 shell，或重新載入對應設定檔。

解除安裝 uv

如果要解除安裝 uv，可以先清理快取和 uv 儲存的資料：

1
2
3

uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

然後刪除二進位檔。

macOS / Linux：

`1`	`rm ~/.local/bin/uv ~/.local/bin/uvx`

Windows：

1
2
3

rm $HOME\.local\bin\uv.exe
rm $HOME\.local\bin\uvx.exe
rm $HOME\.local\bin\uvw.exe

官方文件還提醒：0.5.0 之前，uv 會安裝到 ~/.cargo/bin。如果你從早期版本升級過，舊二進位檔可能仍然留在那裡，需要手動刪除。

安裝後先做什麼

安裝完成後，建議先確認版本：

`1`	`uv --version`

然後可以從幾個常見任務開始：

uv python install
uv venv
uv pip install requests
uvx ruff --version

如果你是新專案，可以進一步學習：

uv init：初始化專案；
uv add：新增依賴；
uv sync：同步環境；
uv run：在專案環境中執行命令；
uvx：臨時執行 Python CLI 工具。

我的建議

個人開發機上，優先使用官方獨立安裝腳本，因為它最貼近 uv 官方文件，也支援 uv self update。

Windows 使用者如果不想執行遠端腳本，可以用 WinGet 或 Scoop。macOS 使用者如果習慣所有工具都交給 Homebrew 管理，可以直接 brew install uv。

已經使用 pipx 管理 Python CLI 工具的人，可以用 pipx install uv。但不建議在具體專案虛擬環境裡用 pip install uv，這樣容易把工具鏈和專案依賴混在一起。

如果是 CI 或容器建置，優先看 Docker 和 GitHub Releases，根據映像建置流程固定版本。

Awesome Codex Skills：給 Codex CLI 擴充技能的社群清單

Thu, 07 May 2026 20:19:15 +0800

ComposioHQ 的 awesome-codex-skills 是一個面向 Codex CLI 的社群技能清單。它的價值不在於再寫一堆提示詞模板，而是把一類可重複的工作流程整理成可安裝、可重複使用、可維護的 Skill。

如果你已經把 Codex 當成日常開發搭檔，這類倉庫的意義會很直接：把經常重複說明的規則、命令、資料入口和操作步驟沉澱下來，下次只要呼叫對應技能，Codex 就能依同一套上下文繼續工作。

這個倉庫解決什麼問題

Codex Skills 可以理解成給 Codex CLI 增加「專門工作模式」的方式。普通提示詞適合臨時說明一次需求，Skill 更適合長期重複使用。

比如你經常需要：

依固定格式生成提交訊息；
查閱某類 API 文件；
執行特定專案的測試和部署命令；
依團隊規範重寫文章、翻譯文件或整理資料；
呼叫外部工具完成重複性的開發輔助任務。

這些內容如果每次都重新輸入，很快就會變成負擔。Skill 的思路是把這些規則放進一個獨立目錄裡，核心通常是一份 SKILL.md，必要時再配合腳本、模板、參考資料或素材檔。Codex 被觸發時會讀取這份說明，然後依照裡面定義的流程執行。

和普通提示詞有什麼不同

普通提示詞更像一次性指令，適合告訴模型「這次怎麼做」。Skill 更像一份小型操作手冊，適合告訴 Codex「以後遇到這類任務都照這個方式做」。

它的優勢主要有三個：

可重複使用：常用工作流不用反覆複製貼上。
可審查：技能檔案通常是本地 Markdown，可以直接打開、修改和版本管理。
可擴充：複雜技能可以帶腳本、模板和參考資料，不只是自然語言說明。

這也是 awesome-codex-skills 這類清單的價值所在：它幫你集中發現已經寫好的技能，再依自己的工作習慣挑選、安裝和改造。

如何安裝和使用

倉庫提供了安裝腳本，也支援手動安裝。典型流程是先 clone 倉庫，再執行安裝腳本：

1
2
3

git clone https://github.com/ComposioHQ/awesome-codex-skills.git
cd awesome-codex-skills
python install.py

如果你只想試用少數技能，建議先看清每個技能目錄裡的 SKILL.md，確認它會讀取哪些資料、執行哪些腳本、修改哪些檔案，再安裝到本地 Codex skills 目錄。

安裝之後，Codex 可以在合適的任務中自動匹配技能，也可以透過明確點名的方式呼叫。對長期使用者來說，更實用的方式往往是：先安裝一個社群技能，再把裡面的說明改成自己的專案規範。

適合關注哪些技能

這類倉庫裡最值得優先看的，不一定是名字最酷的技能，而是能穩定減少重複勞動的技能。

我會優先關注幾類：

開發流程類：程式碼審查、測試、提交、發布、依賴檢查。
文件處理類：重寫、翻譯、摘要、結構化整理。
工具整合類：把 Codex 和外部服務、API、命令列工具連接起來。
專案規範類：把團隊約定、目錄結構、命名規則、部署步驟寫進固定流程。

如果一個技能只是把一句提示詞包裝了一下，價值有限；如果它能把「查資料、判斷、執行、驗證、輸出」串成穩定流程，就值得長期保留。

使用時要注意什麼

社群技能雖然方便，但不要把它當成黑盒直接執行。尤其是帶腳本的 Skill，安裝前最好先檢查三件事：

SKILL.md 裡要求 Codex 做什麼；
是否包含會存取網路、讀寫檔案或呼叫外部服務的腳本；
預設路徑、命令和權限是否適合你的本地環境。

Skill 本質上是在擴大 Codex 的行動邊界。寫得好，它會讓 Codex 更像熟悉你專案的同事；寫得粗糙，它也可能把不適合你的規則帶進工作流。所以最理想的用法不是「裝很多」，而是「裝少數、改到順手、長期維護」。

我的判斷

awesome-codex-skills 值得收藏，尤其適合已經開始用 Codex CLI 做真實開發、文件或自動化任務的人。它不是官方能力本身，而是一個社群整理的技能入口：你可以從裡面找靈感，也可以把常用流程改造成自己的本地技能庫。

對重度使用者來說，Codex Skills 的重點不是讓 AI 多記一點東西，而是讓 AI 在同類任務中少走彎路。把規則寫成 Skill，等於把一次次臨時溝通沉澱成可重複使用的工作基礎設施。

Warp 開源：從終端到 Agentic Development Environment

Thu, 07 May 2026 20:15:08 +0800

warpdotdev/warp 是 Warp 的開源客戶端倉庫。Warp 官方現在把它定位為一個「從終端生長出來的 agentic development environment」，也就是以終端為基礎，但把 AI coding agent、程式碼庫索引、任務管理和開發工作流放進同一個環境裡。

這不是一個普通的終端模擬器開源倉庫。它更像是在回答一個問題：當 Claude Code、Codex、Gemini CLI 這類 agent 越來越常見時，終端本身要不要變成一個能調度、觀察和管理 agent 的開發環境？

Warp 的答案是：要。

這個倉庫現在是什麼狀態

截至 2026 年 5 月 7 日查看，warpdotdev/warp 是公開倉庫，GitHub 頁面顯示約 56k stars、4.1k forks。倉庫 README 說明，Warp 的客戶端程式碼已經開源，並歡迎社群貢獻。

倉庫的主語言是 Rust。GitHub 語言統計裡，Rust 占比超過 98%。這和 Warp 的定位一致：它不是網頁殼，而是一個跨平台的原生開發工具。

README 中有幾個資訊點很重要：

Warp 是一個 agentic development environment, born out of the terminal。
它可以使用內建 coding agent，也可以接入 Claude Code、Codex、Gemini CLI 等外部 CLI agent。
OpenAI 是新開源 Warp 倉庫的 founding sponsor。
倉庫中的 agentic management workflows 由 GPT models 驅動。
Warp UI framework 相關 crate 使用 MIT license，其餘程式碼使用 AGPL v3。

這些資訊說明，Warp 開源不是單純把一個終端放出來，而是把它作為「agent 工作流實驗場」來營運。

Warp 不只是終端

傳統終端主要解決三個問題：

啟動 shell。
執行命令。
顯示輸出。

Warp 早期的差異化，是讓終端更現代：命令區塊、補全、歷史、協作、UI 化互動、跨平台體驗。現在它的重心繼續往前走，開始圍繞 AI agent 組織開發流程。

從 README 看，Warp 不再只強調「更好用的 terminal」，而是強調：

內建 coding agent。
支援外部 CLI agent。
issue triage。
spec 編寫。
PR review。
contributor coordination。
可觀察的 agent sessions。

也就是說，Warp 想把終端從「你輸入命令的地方」，變成「你和多個 agent 一起工作的地方」。

Oz 和開源專案管理

README 裡多次提到 Oz。

Warp 的貢獻概覽頁面可以看到成千上萬個 Oz agents 在做 issue triage、寫 specs、實作改動、review PR。這個設計很有意思，因為它把 AI agent 從「幫個人寫程式碼」擴展到了「幫開源專案管理協作」。

傳統開源專案最難的不是寫程式碼，而是維護：

issue 太多，沒人分類。
bug 和 feature request 混在一起。
新貢獻者不知道哪些任務能做。
PR review 壓力大。
維護者很難持續跟進社群討論。

Warp 的思路是，讓 agent 先承擔一部分專案管理和協作工作。README 中還提到 Oz for OSS，這是面向維護者的合作計畫，用於把類似 agentic open-source management workflows 帶到其他開源倉庫。

這說明 Warp 的野心不只是終端產品本身，也包括探索 AI 時代開源維護的新模式。

倉庫結構和技術棧

從倉庫結構看，Warp 是一個大型 Rust 專案。

根目錄裡能看到：

app/：主應用相關程式碼。
crates/：核心 Rust crates。
assets/：資源檔案。
command-signatures-v2/：命令簽名相關內容。
docker/、script/、resources/、specs/ 等工程目錄。
.claude/、.warp/、.agents/skills 等 agent 相關配置。

WARP.md 裡給出了更詳細的工程說明。它提到 Warp 是 Rust-based terminal emulator，並使用一個自研 UI framework WarpUI。

主要模組可以粗略理解為：

app/：終端模擬、shell 管理、AI 整合、Drive、認證、設定、workspace 和 session。
crates/warp_core/：核心工具和平台抽象。
crates/editor/：文字編輯功能。
crates/warpui/ 和 crates/warpui_core/：自研 UI framework。
crates/ipc/：行程間通訊。
crates/graphql/：GraphQL client 和 schema。

WARP.md 還提到幾個架構特點：

Entity-Handle system。
模組化 workspace 結構。
macOS、Windows、Linux 跨平台，以及 WASM target。
AI integration，包含 Agent Mode、上下文感知和程式碼庫索引。
Warp Drive 雲端同步。

這說明 Warp 的複雜度已經接近一個完整 IDE，而不是傳統意義上的輕量 terminal。

本地建置方式

README 給出的本地建置方式很簡潔：

1
2
3

./script/bootstrap
./script/run
./script/presubmit

其中：

./script/bootstrap：執行平台相關初始化。
./script/run：建置並執行 Warp。
./script/presubmit：執行格式化、clippy 和測試等提交前檢查。

WARP.md 裡還列出了更細的命令：

cargo run
cargo bundle --bin warp
cargo nextest run --no-fail-fast --workspace --exclude command-signatures-v2
cargo fmt
cargo clippy --workspace --all-targets --all-features --tests -- -D warnings

如果要給 Warp 提交程式碼，./script/presubmit 基本是必須跑的。

貢獻流程

Warp 的貢獻流程不是簡單「發 PR 就行」。

README 描述了一個從 issue 到 PR 的輕量流程：

先搜尋已有 issue。
沒有重複再提交 bug 或 feature request。
維護者會 review issue，並可能打上 readiness label。
ready-to-spec 表示設計可以被貢獻者展開成 spec。
ready-to-implement 表示設計已相對明確，可以開始寫程式碼 PR。
貢獻者可以認領帶標籤的 issue。

這個流程適合大型開源專案。它把「想法」「設計」「實作」拆開，減少貢獻者一上來就寫錯方向的風險。

對 AI agent 來說，這也很適合。agent 可以先整理 issue、寫 spec、補測試，再進入實作。Warp 自己也在用這種方式展示 agentic project management。

授權：MIT + AGPL v3

Warp 採用雙授權結構。

README 說明：

Warp UI framework，也就是 warpui_core 和 warpui crates，使用 MIT license。
倉庫其餘程式碼使用 AGPL v3。

這點很重要。AGPL v3 對網路服務和分發有更強的開源要求。如果你只是學習、研究、貢獻程式碼，問題不大；但如果想把 Warp 程式碼用於商業產品或閉源衍生專案，就必須認真讀 license，必要時諮詢法律意見。

簡單說，Warp 是開源了，但不是「隨便拿去閉源商用」的寬鬆授權。

值得關注的地方

第一，Warp 把終端、agent、專案管理放在一起。

很多 AI coding 工具仍然是 CLI 或編輯器外掛。Warp 試圖從終端入口出發，把 agent 任務、程式碼執行、命令輸出、PR 工作流和團隊協作整合起來。

第二，Warp 的開源方式很適合觀察 agent 工作流。

它不只是發布程式碼，還把貢獻概覽、agent session、issue triage 和 spec 流程公開出來。對於想研究 AI 如何參與開源協作的人，這個倉庫本身就是樣本。

第三，Warp 是一個複雜 Rust 桌面應用。

如果你想學習 Rust GUI、終端模擬器、跨平台應用、GraphQL client、雲端同步和 AI 整合，Warp 倉庫有不少可看的結構。但它不是小專案，新貢獻者需要先讀文件和 issue 流程。

第四，Warp 支援「自帶 agent」和「bring your own CLI agent」兩條線。

這點很現實。開發者不會只用一個 agent。Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 等工具會長期共存。Warp 如果能成為它們的工作台，就比單一終端更有價值。

適合誰關注

如果你是普通終端使用者，關注 Warp 的意義在於：終端可能正在從命令列工具變成 AI 工作台。

如果你是 AI coding agent 重度使用者，Warp 值得關注，因為它試圖管理多個 agent，而不是只做一個聊天入口。

如果你是開源維護者，可以關注 Oz for OSS 這條線。它試圖用 agent 做 issue triage、PR review、社群協作和貢獻者引導。

如果你是 Rust 開發者，Warp 是一個大型真實桌面應用樣本，可以研究它如何組織 UI、終端、雲端同步、AI 整合和跨平台程式碼。

如果你只是想找一個能馬上替代傳統終端的工具，建議先下載正式版使用，再決定是否研究源碼。直接從源碼建置更適合貢獻者和深度玩家。

簡短判斷

Warp 開源的重點，不只是「一個現代終端開源了」。

更準確地說，Warp 正在把終端升級成 agentic development environment：終端負責連接 shell、程式碼庫、命令執行、agent、issue、PR 和協作流程。

在 AI coding agent 持續增長的背景下，開發環境的入口可能會發生變化。過去是 IDE 統治開發體驗，終端負責命令執行；現在終端可能反過來成為 agent 協作的中心。Warp 這個倉庫，正是在探索這種可能性。

編譯 UEFI 程式入門：從 uefi-simple 到第一個 .EFI

Thu, 30 Apr 2026 19:53:08 +0800

編譯第一個 UEFI 程式並不輕鬆：環境安裝耗時，連結器錯誤很多，.EFI 程式也不像普通桌面程式那樣有成熟直觀的編輯和執行體驗。

這篇就按入門角度整理一下：如果只是想先編譯出自己的第一個 UEFI 程式，應該從哪裡開始，哪些概念要先搞清楚，哪些坑最容易遇到。

UEFI 程式是什麼

UEFI 程式通常是一個 .EFI 檔案。

它不是 Windows 下雙擊執行的普通 .exe，而是執行在 UEFI 韌體環境裡的 PE/COFF 可執行檔。常見場景包括：

啟動管理器
硬體初始化工具
韌體更新工具
開機前診斷工具
自訂啟動流程

你在系統啟動早期看到的很多功能，本質上都可能和 UEFI 應用程式、驅動或韌體服務有關。

對初學者來說，先不用急著理解完整韌體開發。第一步只要完成一個目標：編譯出一個能被 UEFI Shell 或模擬器載入的 .EFI 檔案。

為什麼不建議一開始就上 EDK II

UEFI 正式開發經常會遇到 EDK II。

EDK II 功能完整，也更接近真實韌體工程，但它對新手不太友好：

工程結構複雜
建構系統有學習成本
環境變數和工具鏈配置比較多
編譯錯誤不容易看懂
很容易還沒寫程式碼，就先卡在環境上

如果目標只是「先跑起來一個最小 UEFI 程式」，更適合從輕量範例開始。

pbatard/uefi-simple 就是這類專案。它的定位很直接：提供一個簡單的 UEFI Hello World 範例，讓你先把 .EFI 編譯出來。

`uefi-simple` 適合用來做什麼

uefi-simple 適合做 UEFI 入門的第一塊踏板。

它主要解決三個問題：

給你一個最小可編譯的 UEFI 應用結構
幫你避開一開始就接觸大型韌體工程的複雜度
讓你能先驗證編譯、連結、執行鏈路是否通

這個專案支援不同建構方式，包括 Visual Studio 2022 和 MinGW/gcc，也可以配合 QEMU 與 OVMF 做測試。

也就是說，你不一定非要準備真實機器反覆重開機測試。先用模擬器把程式跑起來，會安全很多。

入門前要準備哪些東西

最少需要準備幾類工具。

第一類是編譯工具鏈。

如果你在 Windows 上，可以優先考慮：

Visual Studio 2022
或 MinGW/gcc

第二類是 UEFI 執行環境。

可以有兩種選擇：

用真實機器的 UEFI Shell 執行 .EFI
用 QEMU + OVMF 在虛擬環境裡測試

第三類是範例專案。

新手不建議從空目錄開始手寫建構腳本。直接使用 uefi-simple 這類最小範例，可以少踩很多建構系統的坑。

大致流程

一個最小 UEFI 程式的入門流程可以這樣理解。

第一步，取得範例專案。

`1`	`git clone https://github.com/pbatard/uefi-simple.git`

第二步，選擇建構工具鏈。

如果用 Visual Studio，就按專案裡的 Visual Studio 方案建構。
如果用 MinGW/gcc，就按專案提供的 Makefile 或說明走。

第三步，產生 .EFI 檔案。

這裡最關鍵的是確認目標架構。常見 PC 一般是 x86_64，也就是 64 位元 UEFI 環境。

第四步，把 .EFI 放到可以被 UEFI Shell 存取的位置。

如果用真實機器，通常會準備一個 FAT32 分割區或 USB 隨身碟。
如果用 QEMU，可以把目錄或映像檔掛載進去。

第五步，在 UEFI Shell 裡執行。

執行效果通常就是一個最小輸出，比如印出類似 Hello World 的內容。

最容易卡住的地方

編譯 UEFI 程式最容易卡的不是 C 語言本身，而是環境和連結。

常見問題包括：

編譯器架構不對
目標格式不對
連結參數不完整
缺少 UEFI 進入點
產生的是普通可執行檔，不是 UEFI 能載入的 .EFI
QEMU 或 OVMF 沒配置好
真實機器 Secure Boot 阻止執行未簽署程式

尤其是連結器錯誤，經常會讓新手誤以為程式碼寫錯了。
實際上，很多時候是進入函式、子系統、目標架構或連結腳本配置不對。

所以第一階段不要急著改複雜邏輯。先確保原始範例能編譯、能執行，再一點點改輸出內容。

測試時為什麼推薦 QEMU + OVMF

真實機器測試 UEFI 程式並不是不行，但新手階段不太方便。

因為你可能需要反覆：

編譯
複製到 USB 隨身碟
重開機
進入 UEFI Shell
執行
記錄錯誤
回到系統修改

這個循環很慢。

QEMU + OVMF 的好處是可以在作業系統裡直接模擬 UEFI 環境。你可以更快地驗證 .EFI 是否能被載入，也不容易影響真實機器啟動項。

等程式基本跑通，再放到真實機器上測試，會更穩。

新手應該先改哪裡

如果你已經用範例專案編譯出了第一個 .EFI，下一步不要馬上寫複雜功能。

建議按這個順序改：

先改輸出文字，確認重新編譯後的程式確實生效。
再嘗試讀取 UEFI 提供的簡單資訊。
再理解進入函式、輸出協定和基本服務。
最後再考慮檔案系統、圖形輸出、啟動項管理等複雜功能。

這樣做的好處是每一步都能驗證。
如果一上來就改很多東西，出錯時很難判斷到底是程式碼問題、編譯問題，還是執行環境問題。

和普通 C 程式有什麼不同

UEFI 程式雖然可以用 C 寫，但它和普通 C 程式的執行環境完全不同。

普通 C 程式通常執行在作業系統裡，可以依賴標準函式庫、檔案系統、程序模型和系統呼叫。

UEFI 程式執行在作業系統啟動之前，它依賴的是 UEFI 韌體提供的服務。很多你在普通程式裡習慣使用的東西，在這裡並不是天然可用。

所以寫 UEFI 程式時，要先適應幾個變化：

進入函式不一樣
輸出方式不一樣
可用函式庫不一樣
記憶體和檔案存取方式不一樣
除錯方式不一樣

這也是為什麼推薦先從最小範例開始，而不是直接照普通 C 程式的習慣寫。

一個比較現實的學習路線

如果只是入門，可以按這個路線走：

第一步：編譯 uefi-simple
第二步：用 QEMU + OVMF 跑起來
第三步：修改 Hello World 輸出
第四步：理解 UEFI Shell 怎麼載入 .EFI
第五步：學習 UEFI 的進入函式和基本輸出協定
第六步：再看 EDK II 或更完整的 UEFI 開發資料

這條路線的重點是先讓回饋閉環跑起來。

只要你能從原始碼產生 .EFI，再在 UEFI 環境裡看到輸出，就已經跨過了最難的第一道門檻。

參考

最後一句

編譯第一個 UEFI 程式，難點通常不在「寫出一段 C 程式碼」，而在把工具鏈、連結格式和執行環境串起來。

先別急著做複雜功能。
從 uefi-simple 這種最小範例開始，先得到一個能執行的 .EFI，再逐步理解 UEFI 的進入點、協定和建構方式，會輕鬆很多。

GoAccess 最新版自編譯與使用記錄：從原始碼安裝到即時 HTML 報表

Wed, 29 Apr 2026 00:08:00 +0800

時間點按 2026-04-29 整理。
目前官方 README 裡給出的最新穩定版是 1.10.2。

1. 先裝編譯依賴

1
2
3

sudo apt-get update
sudo apt-get install -y build-essential wget tar \
  libncurses-dev libmaxminddb-dev libssl-dev zlib1g-dev

2. 下載最新版原始碼包

cd /usr/local/src
sudo wget https://tar.goaccess.io/goaccess-1.10.2.tar.gz
sudo tar -xzvf goaccess-1.10.2.tar.gz
cd goaccess-1.10.2

3. 配置編譯參數

`1`	`sudo ./configure --enable-utf8 --enable-geoip=mmdb --with-zlib`

如果你還想給即時 HTML 報表配 TLS，也可以改成：

`1`	`sudo ./configure --enable-utf8 --enable-geoip=mmdb --with-zlib --with-openssl`

4. 編譯並安裝

1
2

sudo make
sudo make install

5. 確認版本

1
2

goaccess --version
which goaccess

6. 直接看終端報表

Nginx 或 Apache 常見 combined 日誌可以先這樣跑：

`1`	`goaccess /var/log/nginx/access.log --log-format=COMBINED`

如果日誌路徑是 Apache：

`1`	`goaccess /var/log/apache2/access.log --log-format=COMBINED`

7. 生成靜態 HTML 報表

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o /usr/share/nginx/html/goaccess-report.html

輸出到目前目錄也可以：

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o report.html

8. 生成即時 HTML 報表

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o /usr/share/nginx/html/goaccess-report.html \
  --real-time-html

如果要改埠號：

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o /usr/share/nginx/html/goaccess-report.html \
  --real-time-html \
  --port=7891

如果只綁定本機：

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o /usr/share/nginx/html/goaccess-report.html \
  --real-time-html \
  --addr=127.0.0.1

9. 持續追日誌

`1`	`tail -f /var/log/nginx/access.log \| goaccess --log-format=COMBINED -`

從檔案開頭開始並保持即時：

tail -f -n +0 /var/log/nginx/access.log | goaccess \
  --log-format=COMBINED \
  -o report.html \
  --real-time-html -

10. 只看某類請求

例如只看帶 firefox 的請求：

1
2

tail -f /var/log/nginx/access.log | grep -i --line-buffered 'firefox' | goaccess \
  --log-format=COMBINED -

例如只看 5xx 和 3xx：

1
2
3

tail -f -n +0 /var/log/nginx/access.log | awk '$9~/3[0-9]{2}|5[0-9]{2}/' | goaccess \
  --log-format=COMBINED \
  -o out.html -

11. 多個日誌一起分析

`1`	`goaccess /var/log/nginx/access.log /var/log/nginx/access.log.1 --log-format=COMBINED`

壓縮和未壓縮一起讀：

`1`	`zcat --force /var/log/nginx/access.log* \| goaccess --log-format=COMBINED -`

12. 開多執行緒

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -o report.html \
  -j 4

加大 chunk：

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -o report.html \
  -j 4 \
  --chunk-size=8192

13. 增量處理

先持久化一份舊日誌：

`1`	`goaccess /var/log/nginx/access.log.1 --log-format=COMBINED --persist`

再追加目前日誌：

`1`	`goaccess /var/log/nginx/access.log --log-format=COMBINED --restore --persist`

只讀取已持久化資料：

`1`	`goaccess --restore`

14. 我自己會先跑的一組命令

sudo apt-get update
sudo apt-get install -y build-essential wget tar \
  libncurses-dev libmaxminddb-dev libssl-dev zlib1g-dev

cd /usr/local/src
sudo wget https://tar.goaccess.io/goaccess-1.10.2.tar.gz
sudo tar -xzvf goaccess-1.10.2.tar.gz
cd goaccess-1.10.2
sudo ./configure --enable-utf8 --enable-geoip=mmdb --with-zlib --with-openssl
sudo make
sudo make install

goaccess --version

goaccess /var/log/nginx/access.log \
  --log-format=COMBINED \
  -a \
  -o /usr/share/nginx/html/goaccess-report.html \
  --real-time-html

就這樣。
如果你的目標很明確，其實只要把最新版原始碼編譯好，再把 --log-format=COMBINED 和 --real-time-html 這兩個參數先跑通，後面基本就是圍著日誌路徑、輸出檔案和埠號在改。

2026 年嵌入式開發環境怎麼選：Keil、STM32CubeIDE、VS Code 與 AI 協作

Wed, 22 Apr 2026 23:05:00 +0800

只要你還在做單晶片或嵌入式開發，很快就會遇到一個很現實的問題：到了 2026 年，在 AI 寫程式已經越來越普遍的情況下，開發環境到底該怎麼選？

這個問題表面上像是在比較幾個 IDE，實際上討論的卻是另一件事：你到底是要一個「能把工程跑起來的工具」，還是一套「兼顧生態、編碼體驗與 AI 協作能力」的工作流。

如果從這個角度去看，答案往往就不是簡單地在 Keil、STM32CubeIDE、VS Code、CLion 裡選一個，而是重新組合它們各自最擅長的部分。

先看幾個主流選項，各自解決什麼問題

嵌入式領域這些年常見的環境，基本還是那幾類：

Keil
STM32CubeIDE
VS Code
CLion

如果再往前追，當然還會有人提 IAR。只是從今天的討論出發，更值得看的已經不是「誰資歷最老」，而是誰更適合當前這套開發現實。

Keil：生態強、上手穩，但編輯體驗已經明顯落後

Keil 到今天仍然很難繞開，原因不複雜：它用得實在太廣了。

無論是公司裡留下來的老工程，還是網上大量教學、資料、示例工程，很多都還是圍繞 Keil 組織的。它在編譯、下載、調試這一整套流程上依然成熟，尤其是你真的要把板子跑起來時，它的路徑非常短。

它的問題也同樣明顯：

介面老
編輯體驗一般
不擅長承擔 AI 輔助寫程式的主場

所以 Keil 更像是一個「工程入口和調試底座」，而不是一個面向 2026 年編碼體驗的理想編輯環境。

STM32CubeIDE：對 STM32 友好，但更多是學習和快速起步工具

如果你主要在 STM32 生態裡活動，STM32CubeIDE 很容易成為第一個接觸到的環境。

它的優點很明確：

上手友好
外設配置和工程生成方便
調試鏈路相對完整

對學生、新手和剛起步的專案來說，這套體驗確實足夠直接。

但一旦進入更長期、更多協作、更多客製化的工程環境，它的局限也會慢慢暴露出來。尤其是在商業專案或更複雜的團隊工作流裡，它未必是那個最舒服的主環境。

所以它更適合「快速啟動」和「STM32 生態內的一體化體驗」，不一定適合作為長期主力編輯器。

VS Code：嚴格來說不是 IDE，但在 AI 時代優勢越來越明顯

VS Code 嚴格來說並不是傳統意義上的 IDE，更準確地說，它是一個可擴充的程式碼編輯器。

這也意味著它天然有兩面性。

它的弱點是：

需要外掛和配置
對新手不夠友好
不能開箱即用地取代嵌入式 IDE 全流程

但它真正強的地方，恰恰也在這裡：

可擴充性強
編碼體驗明顯更現代
語法高亮、跳轉、搜尋、重構體驗更好
對 AI 工具和 Agent 工作流支援更積極

在今天這個階段，很多人真正需要的已經不只是「能寫程式」，而是「寫程式時能不能順手把 AI 協作接進來」。從這個角度看，VS Code 的優勢幾乎是肉眼可見的。

CLion：體驗不錯，但在嵌入式場景裡不夠主流

CLion 經常會被提到，因為它的 C/C++ 編碼體驗一直不差。

但對很多嵌入式開發者來說，它的問題不一定出在「好不好用」，而是「值不值得切過去」：

用的人相對少
與現有嵌入式工程生態連接不如 Keil 直接
在 AI 協作這件事上，也未必比 VS Code 更有現實優勢

所以它更像是一個「理論上也能做得不錯」的選項，但在今天的嵌入式主流工作流裡，並不是最自然的那個核心。

更現實的答案：Keil 負責編譯調試，VS Code 負責寫程式

如果把上面這些工具拆開來看，很容易得到一個更務實的結論：

用 Keil 保留現有工程生態、編譯、下載和調試能力
用 VS Code 承擔日常編碼、搜尋、跳轉和 AI 協作

這套組合的價值在於，它不是試圖用一個工具包打天下，而是讓每個工具回到自己最擅長的位置。

對很多嵌入式工程來說，Keil 的生態根本繞不開。既然如此，與其強行把所有工作都塞回 Keil，不如承認它更適合作為後端編譯調試入口；而真正的編輯體驗，則交給 VS Code。

為什麼這套組合在 AI 時代更有優勢

到了今天，開發環境的分界線已經不只是「編輯器順不順手」，而是「它能不能自然接入 AI」。

VS Code 在這件事上有幾個很現實的優勢：

AI 外掛和 Agent 支援更活躍
程式碼瀏覽體驗更適合讓 AI 讀工程、改工程
更容易和現代外掛生態結合

這意味著你可以把嵌入式開發裡最痛苦的一部分工作，開始交給 AI 幫你分擔：

在現有工程裡找函式和呼叫鏈
快速生成一段初始化程式碼
幫你補一個串口列印
解釋舊工程結構
在既有檔案裡做小範圍修改

這些事情過去不是不能做，而是做起來不順。VS Code 的意義不只是「更好看」，而是它更容易成為 AI 協作的工作台。

關鍵補丁：用外掛把 VS Code 和 Keil 工程接起來

這套工作流能不能成立，核心不在口號，而在你能不能把 VS Code 和 Keil 工程接起來。

比較實用的一類外掛思路，是讓 VS Code 直接讀取 Keil 工程結構，並在編輯器內部呼叫 Keil 後台程式完成：

打開工程
編譯
下載

這樣一來，你日常寫程式不用頻繁在兩個介面之間來回切，只有到了更重的調試環節，再回到 Keil 裡做單步、斷點和寄存器觀察。

這類外掛真正有價值的地方，不只是「少切幾個視窗」，而是它讓工作流連續起來了。

不要忽視 C/C++ 基礎外掛配置

如果你打算把 VS Code 當作嵌入式主編輯器，一個非常基礎但常被忽略的點是：一定要把 C/C++ 基礎外掛和工程索引配置好。

否則你會遇到一系列很影響體驗的問題：

跳轉不到定義
紅線誤報
補全不準
標頭檔關係混亂

很多人會誤以為是 VS Code 不適合嵌入式，實際上往往只是工程索引和外掛配置沒接好。

一旦這部分配置完整，VS Code 才能真正發揮出它在閱讀大型工程、搜尋符號、配合 AI 輔助修改程式碼上的優勢。

這套工作流最適合誰

我覺得下面這幾類人，會特別適合這種組合式環境。

1. 已經有大量 Keil 工程的人

如果你公司專案、課程資料或歷史程式碼都圍繞 Keil 展開，那就沒必要為了「現代化」硬切掉原有生態。保留 Keil，再補一個 VS Code 前端，是遷移成本最低的做法。

2. 想用 AI 輔助寫嵌入式程式的人

如果你已經習慣讓 AI 幫你解釋函式、補樣板程式碼、改局部邏輯，那麼 VS Code 會比傳統嵌入式 IDE 更自然地承接這件事。

3. 想同時兼顧學習資料和真實專案的人

很多學習資料仍然建立在 Keil 上，但你自己的工作流未必要停留在那個年代。把 Keil 作為工程相容層，把 VS Code 作為生產力層，會更平衡。

結語

到了 2026 年，嵌入式開發環境的關鍵問題，已經不再只是「哪個 IDE 功能更多」，而是「哪種組合最符合今天的工作方式」。

如果你只想快速起步，STM32CubeIDE 依然有它的位置；如果你要穩定接住大量既有工程，Keil 依然繞不開；但如果你還想把現代編輯體驗和 AI 協作一起接進來，那麼更現實的答案，往往是：

Keil 負責編譯和調試，VS Code 負責寫程式。

這不一定是唯一答案，但很可能是當下最不彆扭的一種答案。

8 種常見設定檔格式怎麼選：INI、XML、JSON、YAML、TOML 到 Markdown

Wed, 22 Apr 2026 21:48:37 +0800

只要你常寫程式、折騰伺服器、調遊戲參數，或者維護各種工具鏈，基本都逃不過設定檔。

很多時候，真正把程式搞炸的不是演算法，也不是框架，而是一行不起眼的設定：少了一個空格、多了一個逗號，或者某個值寫成了系統不想看到的樣子。把常見設定檔格式放在一起看，很自然就會回到幾個核心問題：

哪些格式比較適合人來寫？
哪些格式比較適合機器來讀？
在 AI Agent 時代，設定檔這件事會不會發生變化？

這篇文章就是圍繞這個問題做的一次簡潔整理。

01 設定檔，本質上是在協調「人」和「機器」

有個說法我覺得很準確：設定檔其實就是人和程式之間簽下的一份「行為契約」。

它的價值很明顯。你不需要重寫業務程式碼，也不用重新編譯，只改幾行文字，就能改變網站行為、應用邏輯、部署方式，甚至遊戲畫質和隱藏選項。

問題在於，這份契約天生就有矛盾。

從人的角度，我們想要的是：

好看、好寫、層級清楚
最好支援註解，方便自己和別人之後回頭看
能少寫就少寫，最好還能重用和模組化
寫錯時不要一碰就炸

但從機器的角度，它根本不在乎優不優雅，只在乎兩件事：

解析要快
規則要嚴，型別要清楚，最好沒有歧義

這就是為什麼設定檔格式總是在「人類友善」和「機器友善」之間拉扯。越適合人閱讀的格式，機器往往解析更麻煩；越適合機器高效處理的格式，人寫起來通常越容易崩潰。

02 INI：簡單直接，但能力有限

先從 INI 說起。

它的優點非常直接：

結構簡單
分區加鍵值對，幾乎一眼就能看懂
支援註解
很適合一些輕量設定場景，例如遊戲參數微調、基礎環境設定

如果你改過老遊戲設定，或手動調過某些工具參數，基本都見過它。

但 INI 的問題也很明顯。它的結構太扁平，原生不適合表達複雜巢狀和陣列。再加上它通常缺少嚴格的型別系統，很多值本質上就是一串文字，最後怎麼解釋，還是得靠程式自己處理。

所以 INI 比較像一台老式但順手的工具車，做輕活很好用，專案一複雜就容易顯得力不從心。

一個很典型的 INI 設定會長這樣：

[server]
host=127.0.0.1
port=8080

[feature]
enable_cache=true

03 XML：嚴謹、穩定，但寫起來很累

第二位是 XML。

如果你維護過老 Java 專案，或者看過一大堆成對閉合標籤的設定檔，對它應該不陌生。

XML 的優點包括：

層級結構明確
支援註解
規則嚴整
可以搭配 schema 做強校驗

這意味著機器在正式讀取前，就能先知道欄位型別、出現次數和結構約束，安全感很高。

但它對人的折磨也很經典：

標籤冗長
視覺噪音很大
檔案容易膨脹
稍微漏掉一個閉合標籤，就可能整頁報錯

所以 XML 非常像一份蓋章齊全的正式合約。機器喜歡，人維護 often 很累。現在很多新專案已經不再優先選它，但在一些老系統和嚴規則場景裡，它仍然沒有完全退場。

同樣的設定如果寫成 XML，大概會像這樣：

<config>
  <server>
    <host>127.0.0.1</host>
    <port>8080</port>
  </server>
  <feature>
    <enable_cache>true</enable_cache>
  </feature>
</config>

04 JSON：資料交換霸主，但不適合手寫複雜設定

說到現代開發，JSON 幾乎繞不過去。

對 JSON 來說，一個很典型的判斷是：作為資料交換格式，它非常強；但作為人工維護的設定檔，它有點彆扭。

它的優勢包括：

物件和陣列結構清楚
網路傳輸友善
解析器成熟
很適合 Web API 和前後端通信

尤其跟 XML 放在一起看時，JSON 的輕量優勢會很明顯。同樣的資料結構，JSON 通常更短，也更適合在網路中傳來傳去。

但它有個致命缺點：標準 JSON 不支援註解。

另外，它的語法也比較嚴格：

key 必須加雙引號
最後一項後面不能多逗號
少一個符號就可能直接報錯

所以 JSON 很適合 API、服務之間的資料交換，卻不一定適合需要人手動維護、寫說明、頻繁修改的設定檔。

例如：

{
  "server": {
    "host": "127.0.0.1",
    "port": 8080
  },
  "feature": {
    "enable_cache": true
  }
}

05 YAML：可讀性很強，但縮排和隱式型別會坑你

如果你碰過 Docker、CI/CD、Kubernetes、自動化部署，那基本一定和 YAML 打過交道。

它最吸引人的地方，就是看起來很「乾淨」：

少了很多大括號和引號
用縮排表達層級
支援註解
還能做錨點重用

所以從人的第一眼體驗來看，YAML 通常比 JSON 友善得多。

但問題也正出在這裡。它把很多複雜性藏起來了，實際使用時經常會出現兩類經典事故：

縮排地獄
隱式型別轉換

縮排問題很好理解，空格多一個少一個，設定就可能直接壞掉。更麻煩的是隱式型別轉換，例如某些看起來像普通字串的值，可能會被自動解釋成布林值或其他型別。

這也是為什麼很多人一邊誇 YAML 好看，一邊又被它折騰得很慘。它在人的閱讀體驗上確實很好，但機器解析它時並不輕鬆，而且不同解析庫之間還可能有細微差異。

同樣的設定寫成 YAML，通常會更清爽：

server:
  host: 127.0.0.1
  port: 8080

feature:
  enable_cache: true

06 TOML：在可讀性和確定性之間找平衡

TOML 經常被放在「當代均衡答案」的位置上。

TOML 的好處在於，它有點像把 INI 的直觀和 JSON 的型別明確結合在一起：

支援註解
結構清楚
強型別更明確
日期時間等常見型別支援更自然
不容易出現 YAML 那種隱式轉換坑

尤其在現代工具鏈裡，TOML 已經越來越常見，例如 Python 的 pyproject.toml。

當然它也不是沒有缺點。對於很深層的巢狀結構，TOML 會顯得有點囉嗦，路徑式書寫多了會煩。但如果場景是中小型專案設定、工具設定、套件管理設定，TOML 的整體體驗通常比較穩。

如果你想找一種「註解有、語義清、機器也不難受」的格式，TOML 的確值得優先考慮。

一個常見的 TOML 寫法會像這樣：

[server]
host = "127.0.0.1"
port = 8080

[feature]
enable_cache = true

07 `.conf` 和 Apache 設定：不是通用格式，而是領域語法

有一點很值得提醒：很多人看到 .conf，會誤以為它是一種統一格式，其實不是。

.conf 只是 “configuration” 的副檔名，裡面到底怎麼寫，完全取決於具體系統自己的規則。也就是說，.conf 比較像一個大類，而不是一套標準語法。

拿 Apache 設定舉例，它的寫法很有代表性：

一部分像單行指令
一部分又像有作用域的標籤結構
很適合 Web 伺服器這種特定領域

優點是對運維場景很順手，表達權限、路由、虛擬主機這類規則都很自然；缺點是它幾乎只服務於自己的生態，不具備太強的通用性。

所以這類設定更像「領域專用語言」，在特定系統裡很好用，但不適合拿來當成通用設定格式來看。

例如一個極簡的 Apache 風格設定，看起來會更像一組指令：

Listen 80

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/var/www/html"
</VirtualHost>

08 Protocol Buffers：工業級強型別方案，但門檻高

Protocol Buffers 其實已經不是傳統意義上的「隨手寫個設定檔」了，而更像一套正式的資料定義與序列化方案。

它的優勢很強：

強型別
schema 明確
向前向後相容性好
二進位傳輸體積小
機器處理效率高

但代價也很明顯：

需要先寫 .proto
需要工具鏈和編譯步驟
對小專案來說門檻偏高

所以它不適合「我只是配個小工具」這種輕量場景，但如果你是在做大型系統、RPC、分散式服務，或長期演進的資料協議，它往往會比很多輕量設定格式更可靠。

它的寫法更接近「先定義結構，再生成程式碼」：

syntax = "proto3";

message ServerConfig {
  string host = 1;
  int32 port = 2;
  bool enable_cache = 3;
}

09 在 AI Agent 時代，Markdown 可能重新變成「設定方式」

最有意思的部分，是把 Markdown 也放進了「設定檔」的討論裡。

從傳統程式的視角來看，這聽起來有點奇怪，因為 Markdown 本來更像文檔格式。但如果把對象換成大語言模型或 AI Agent，這個判斷其實是成立的。

為什麼？

因為傳統程式依賴的是嚴格語法和固定欄位，而大模型更擅長理解語義、結構和上下文。對它們來說：

標題就是層級
列表就是步驟
粗體就是強調
自然語言本身就能承載規則

也就是說，當設定對象從「死板的解析器」變成「能讀懂語義的 Agent」，Markdown 這類對人友善的結構化文字，反而可能成為一種更自然的設定形式。

這也是一個很關鍵的判斷：在傳統軟體時代，很多設定格式是為了讓人去適應機器；而在 AI 時代，機器開始反過來適應人的表達。

例如給 Agent 寫任務設定，完全可以直接寫成：

# 任务目标

为新用户写一封欢迎邮件。

## 要求

- 语气友好
- 不超过 150 字
- 提到产品的 3 个核心功能

## 禁止事项

- 不要承诺不存在的功能
- 不要使用夸张营销语气

10 到底該怎麼選

如果把這些觀點壓縮一下，我覺得大致可以分成這幾類：

想要極簡、輕量、扁平設定：INI
想要強結構、強校驗、舊系統相容：XML
想要網路傳輸和介面交換：JSON
想要高可讀性、雲原生與部署設定：YAML
想要更穩的現代通用設定體驗：TOML
想要特定系統內部規則：.conf / Apache 一類 DSL
想要工業級協議與長期演進能力：Protocol Buffers
面向 AI Agent 的自然表達與任務編排：Markdown

所以「最好的設定檔格式」其實並不存在。它取決於你是寫給誰看的：

給人維護
給機器高速解析
給服務彼此通信
或者給 AI Agent 理解與執行

簡單總結

設定檔的發展史，本質上就是人和機器不斷重新分配理解成本的過程。

過去是人遷就機器，所以我們要記住各種括號、縮排、引號和嚴格規則。現在隨著大語言模型和 Agent 系統越來越成熟，機器開始更能理解自然表達，於是「設定」這件事本身也在發生變化。

也許未來很多場景裡，設定檔不再是某種固定語法，而會更像一段結構化的意圖說明。而在那之前，JSON、YAML、TOML、INI、XML 這些格式仍然會長期共存，各自佔據最適合自己的位置。

Windows 上在 VS Code 建置 Docker 映像：從環境準備到一鍵建置

Thu, 16 Apr 2026 10:20:00 +0800

如果你想在 Windows 上直接用 VS Code 管理並建置 Docker 映像，流程其實不長。核心就是三步：先把環境準備好，再建立 Dockerfile，最後執行建置。

01 前置準備

先確認兩個基礎條件：

安裝並啟動 Docker Desktop。
在 VS Code 安裝 Microsoft 官方 Docker 擴充套件。

在 Windows 上，建議把 Docker Desktop 切到 WSL 2 後端（Settings > Resources > WSL Integration），通常會更穩定、效能也更好。

02 準備 Dockerfile

如果專案裡還沒有 Dockerfile，可以讓 VS Code 直接產生：

在 VS Code 開啟你的專案資料夾。
按 F1 或 Ctrl+Shift+P 開啟命令面板。
執行 Docker: Add Docker Files to Workspace。
選擇你的平台（例如 Node.js、Python、.NET），依提示完成。

完成後通常至少會得到：

Dockerfile
.dockerignore

這一步的重點是先得到可運作的基礎版本，後續再依需求微調。

03 三種建置映像方式

方式 A：右鍵 Dockerfile

在檔案總管中右鍵 Dockerfile，選擇 Build Image...，再輸入映像標籤（tag）。

方式 B：命令面板

按 F1 執行 Docker: Build Image，再依提示選擇上下文與標籤。

方式 C：整合終端機

`1`	`docker build -t your-image-name .`

這條命令會用目前目錄當建置上下文，建立標籤為 your-image-name 的映像。

04 常見問題快速檢查

Docker Desktop 未啟動：先確認程式正在執行。
建置很慢：優先檢查是否啟用 WSL 2 後端。
建置失敗顯示找不到檔案：確認執行目錄是專案根目錄，且檔案在建置上下文內。
VS Code 看不到 Docker 資源：重啟 VS Code，並確認 Docker CLI 可用（docker version）。

小結

在 Windows 上用 VS Code 建置 Docker 映像並不困難。先完成 Docker Desktop 與擴充套件安裝，再用命令面板產生 Dockerfile，最後透過 UI 或 docker build 就能完成日常建置流程。

CH347 開發常用資源整理：驅動、工具與 SPI Flash 刷寫

Fri, 03 Apr 2026 10:00:00 +0800

這篇文章整理我在使用 CH347 時最常用的一組資源，目標是開箱就能開始調試與刷寫。

如果你剛接觸 CH347，建議依照下面順序準備環境：

先看官方產品頁確認資料入口
依用途安裝對應驅動
準備 SPI Flash 刷寫工具並做連通性驗證

官方入口

CH347 產品頁：https://www.wch.cn/products/CH347.html

建議優先從官方頁面進入下載區，避免拿到來源不明或版本過舊的驅動包。

常用驅動

1) `CH341PAR.EXE`

用途：

USB 轉 JTAG / SPI / I2C / 並口 / GPIO 等介面驅動

適用情境：

需要用 CH347 做多協議通訊或底層介面調試時

2) `CH343SER.EXE`

用途：

USB 轉高速序列埠 Windows 廠商驅動

適用情境：

主要把 CH347 當序列埠工具使用，且需要較高傳輸速率時

SPI Flash 刷寫工具

AsProgrammer：https://github.com/nofeletru/UsbAsp-flash

常見用途：

識別 SPI NOR Flash
讀取晶片 ID
備份原始韌體
擦除 / 寫入 / 校驗韌體

常見問題速查

設備已插入但工具看不到：多半是驅動未正確載入，或 USB 線僅供電不傳輸。
能識別但讀寫失敗：優先排查接線順序、共地與供電穩定性。
速度過快不穩定：先降速讀寫，確認穩定後再逐步提升。

總結

CH347 的使用門檻不高，關鍵是把「驅動、工具、連線、校驗」四件事一次做對。

上面這組資源已覆蓋多數入門與日常維護場景，照流程走通常就能快速進入可用狀態。

FFmpeg 的 `-map` 參數詳解：精準選擇影片、音訊與字幕串流

Thu, 02 Apr 2026 23:14:03 +0800

在多音軌、多字幕的影片處理中，-map 是 FFmpeg 最關鍵也最容易用錯的參數之一。

如果你不明確指定 -map，FFmpeg 會依預設規則自動挑選串流，結果常常不是你要的。像是：

匯出後字幕不見
選錯音軌語言
混入不需要的資料串流

這篇文章用最常見的情境，講清楚 -map 怎麼用。

先理解什麼是「串流」

一個容器檔（例如 mp4、mkv）通常不只一個內容串流（stream），常見包含：

影片串流（v）
音訊串流（a）
字幕串流（s）
附件/資料串流（如字型、封面、章節等）

你可以先用 ffprobe 看清檔案裡有哪些串流：

`1`	`ffprobe -hide_banner input.mkv`

`-map` 的基本語法

最常見寫法：

`1`	`-map input_index[:stream_type][:stream_index]`

例如：

0:v：第 1 個輸入檔的所有影片串流
0:a:0：第 1 個輸入檔的第 1 條音訊串流
1:s:1：第 2 個輸入檔的第 2 條字幕串流

說明：

input_index 從 0 開始，對應 -i 的順序
stream_index 也從 0 開始

實戰範例

1) 影片來自 A，音訊來自 B

ffmpeg -i english.mp4 -i french.mp3 \
  -map 0:v:0 -map 1:a:0 \
  -c:v copy -c:a aac \
  french.mp4

含義：

取 english.mp4 的第 1 條影片串流
取 french.mp3 的第 1 條音訊串流
合併輸出成 french.mp4

2) 保留第一個輸入的全部串流，再額外加一條音軌

ffmpeg -i english.mp4 -i french.mp3 \
  -map 0 -map 1:a:0 \
  -c copy \
  english-french.mp4

含義：

-map 0 先帶上第一個輸入檔的所有串流
再追加第二個輸入的第 1 條音訊串流

兩個很實用的進階技巧

1) 負映射：排除不需要的串流

例如保留第一個輸入的全部串流，但去掉第 2 條音訊串流：

`1`	`ffmpeg -i input.mkv -map 0 -map -0:a:1 -c copy output.mkv`

2) 可選映射：串流不存在也不中斷

有些檔案可能沒有字幕，這時可用 ?：

`1`	`ffmpeg -i input.mp4 -map 0:v -map 0:a -map 0:s? -c copy output.mp4`

0:s? 表示「有字幕就映射，沒有就跳過，不報錯」。

常見坑位

一旦使用 -map，FFmpeg 就不再自動選流，必須把要的串流都寫出來。
-c copy 只是封裝複製，不做轉碼；若目標容器不支援某編碼，仍會失敗。
多輸入時最容易錯的是輸入序號，序號只看 -i 的先後順序。
要做穩定腳本時，先 ffprobe 再生成 -map，通常比手寫更穩。

總結

-map 的核心就一句話：明確告訴 FFmpeg，「從哪個輸入，拿哪類串流，拿第幾條」。

掌握之後，你就能穩定處理多音軌、多字幕、跨檔合成等複雜場景，避免「輸出不對卻不知道原因」的情況。

如何排查由外掛引起的 VS Code CPU 佔用過高

Wed, 01 Apr 2026 00:00:00 +0000

當 VS Code 突然變卡、風扇狂轉、CPU 長時間高佔用時，最常見原因通常不是編輯器本體，而是擴充外掛衝突或外掛行為異常。

這篇文章提供一套可立即執行的排查路徑，優先用最省時間的方法定位問題。

先做最快的定位：Start Extension Bisect

Start Extension Bisect 的核心思路是二分法：每一輪暫時停用一半擴充並重啟，透過你回報「問題是否仍存在」，快速縮小範圍，直到定位到可疑外掛。

操作步驟：

按 Ctrl+Shift+P（macOS 為 Cmd+Shift+P）開啟命令面板。
輸入並執行 Start Extension Bisect。
每次重啟後觀察 CPU 佔用與卡頓是否重現，並依提示選擇 Good now 或 This is bad。
重複幾輪後，VS Code 會給出可疑擴充清單。

定位後怎麼處理

找到可疑外掛後，建議按這個順序處理：

先更新外掛到最新版本。
若無改善，暫時停用該外掛 1-2 天觀察。
對於功能可替代的外掛，優先換成更輕量的方案。
若必須使用該外掛，檢查其進階設定，關閉不必要的即時分析、索引或監聽功能。

兩個容易被忽略的「放大器」

即使主因是外掛，以下設定也會放大 CPU 問題：

搜尋範圍過大
例如把建置產物、依賴目錄、日誌目錄也納入全域搜尋，會讓外掛與檔案索引持續高負載。
檔案監控包含大型目錄或軟連結
軟連結、快取目錄、自動產生目錄容易觸發大量檔案事件，導致擴充反覆工作。

可以在 settings.json 中適當排除目錄，例如：

{
  "search.exclude": {
    "**/node_modules": true,
    "**/dist": true,
    "**/build": true
  },
  "files.watcherExclude": {
    "**/.git/objects/**": true,
    "**/node_modules/**": true,
    "**/dist/**": true
  }
}

復盤建議

如果你已定位到問題外掛，建議記錄三件事：外掛名稱、觸發場景、最終處理方式。
這樣下次遷移環境或重裝系統時，可以快速避開同類問題。

總結

VS Code 高 CPU 佔用的排查，最有效路徑是先用 Start Extension Bisect 快速定位，再結合搜尋與檔案監控範圍做收斂。
先定位，再優化，比「盲目停用一堆外掛」更省時間，也更穩定。