AI工具
Hermes Agent 入門指南：模型 × Skills「新手友好」
""
Top 5 Insights
- **組合大於單純的模型能力**：未來的 Agent 工程重點不在於無止盡地追求更大更聰明的模型，而在於如何編寫與編排 (Orchestrate) 高品質的 Skills 來約束既有模型。
- **重視 Plan 階段**：將任務拆解並在執行前進行規劃與人工確認，是降低複雜任務失敗率的關鍵架構模式。
- **工具調用穩定性即生產力**：評估開源模型（如 Ring-2.6-1T）是否適用於 Agent 架構，核心指標應是其對 Skill 文件的理解力與多步驟工具調用的穩定性。
---
tags: [AI工具, Hermes Agent, Model, Skill, Ring-2.6]
date: 2026-05-19
source: "2026-05-19T092625+0800-Hermes Agent 入门指南：模型 × Skills「新手友好」.md"
---
# Hermes Agent 入門指南：模型 × Skills「新手友好」
原始來源與檔名：2026-05-19T092625+0800-Hermes Agent 入门指南：模型 × Skills「新手友好」.md
## 前言/背景
在使用 AI Agent（如 Hermes Agent）時，許多新手常面臨生成效果不如預期、或任務執行中途跑偏的問題。本文旨在釐清 Agent 架構中兩個最核心的元素：「模型 (Model)」與「技能 (Skills)」的乘數關係。透過實際的 PPT 生成測試對比，展示為何將「設計紀律（Skill）」注入「穩定的底層引擎（模型）」中，能將 AI 的輸出品質從「堪用」大幅提升至「驚豔」。
## 章節詳細總結
### 模型 (Model) 與 Skills 的底層邏輯
在 Agent 架構中，兩者扮演著截然不同但相輔相成的角色：
* **模型 (Model)**：驅動 Agent 完成任務的 AI 引擎。決定了能力的上限，包含推理深度、工具呼叫 (Tool Calling) 穩定性以及多模態支援能力。
* **Skills (任務說明書)**：負責約束模型。它告訴模型這類任務該怎麼做、用哪些工具、輸出什麼格式。
這兩者的關係是**乘法**：
1. 能力弱的模型配上再好的 Skill，也容易執行跑偏。
2. 能力強的模型若沒有 Skill 約束，只能靠通用經驗「盲猜」，輸出質量往往止步於「堪用」。
**隱性工程收益**：Skill 為模型節省了算力與規劃成本。有了清晰的執行路徑，模型不必耗費推理資源在「想清楚該怎麼做」上，而是聚焦於執行本身。
### 實戰演練：三組對照實驗
作者使用了 Ring-2.6-1T 開源模型，並以同一篇素材進行了生成 PPT 的三組對照測試：
1. **A 組（無約束直出）**：直接把文章扔給模型。產出結果結構平庸、資訊堆疊、視覺毫無層次，幾乎無法用於實際傳播。
2. **B 組（先規劃，再執行）**：引入 **Plan 階段**。先讓模型讀文章並輸出執行計畫（定好幾頁、每頁講什麼、如何佈局），確認後再動手。產出的結構與資訊層次大幅改善，但視覺風格依然普通。
3. **C 組（先規劃，並加載專門的 PPT Skill）**：確認計畫後，加載 `guizang-ppt-skill` 執行。Skill 介入後，模型明確知道該套用何種佈局風格、數據展示方式及頁面節奏。最終輸出的效果極具專業水準。
### 為什麼多數人用不好 Hermes Agent？
多數人習慣於「拿到任務直接讓模型開幹」，直接跳過 Plan（規劃）階段。
在簡單任務中這並無大礙，但在複雜任務中，一旦中途方向錯誤，重做的成本極高。
優秀的模型（如 Ring-2.6-1T）特點在於「先想清楚再動手」。在 Plan 階段，它會將任務拆解成可執行的步驟，並明確每步的邊界與輸出。這種「人類在迴路中 (Human-in-the-loop)」的設計允許使用者及時介入調整，大幅降低試錯成本。
### 用好 Skill 的兩個關鍵架構認知
1. **Skill 是預設工作流，而非進階外掛**：
不應將 Skill 視為熟悉基礎後的進階玩法，而應將其作為**預設的執行約束**。例如做 PPT 加載 `guizang-ppt-skill`，需要瀏覽網頁加載 `agent-browser`。這些「說明書」消除了模型的瞎猜空間，確保執行的準確性與穩定性。
2. **模型底座必須能接得住 Skill**：
Skill 再好，也需要底層模型具備強大的工具呼叫 (Tool Calling) 與多步執行穩定性。若模型底座能力不足，即使加載相同的 Skill，也常發生「該呼叫的工具不呼叫」或跳過步驟的情況。一個穩定的底座加上清晰的說明書，才是真正具備生產力的組合。
## 總結與結論
* **組合大於單純的模型能力**：未來的 Agent 工程重點不在於無止盡地追求更大更聰明的模型，而在於如何編寫與編排 (Orchestrate) 高品質的 Skills 來約束既有模型。
* **重視 Plan 階段**：將任務拆解並在執行前進行規劃與人工確認，是降低複雜任務失敗率的關鍵架構模式。
* **工具調用穩定性即生產力**：評估開源模型（如 Ring-2.6-1T）是否適用於 Agent 架構，核心指標應是其對 Skill 文件的理解力與多步驟工具調用的穩定性。
Obsidian 整理
原始文章
AI工具
Hermes 作為即時分析師 (Hermes as a Real-time Analyst)
""
Top 5 Insights
- **Agent 應用的典範轉移**：高階使用者的核心技能正在從「依賴 Agent 幫你想」轉向「人類提出假設，Agent 負責驗證」。
- **架構師視角 - 工具解耦 (Tool Decoupling)**：不要盲目追求全能模型。最佳的架構是「解耦」：用 DeepSeek v4 作為主控大腦（擅長邏輯推理與工具編排），用 `x_search`（由 Grok 驅動）作為專職的即時資料庫抓取器。
- **成本與效能優化**：善用平台訂閱機制的漏洞與免費的 Web 介面自動化（Browser CDP），能將原本依賴昂貴官方 API 的資料清洗流水線，轉化為極低成本的常駐微服務。
---
tags: [AI工具, Hermes Agent, xAI, Grok, AI Analyst, x_search]
date: 2026-05-19
source: "2026-05-19T092634+0800-Hermes as a Real-time Analyst.md"
---
# Hermes 作為即時分析師 (Hermes as a Real-time Analyst)
原始來源與檔名：2026-05-19T092634+0800-Hermes as a Real-time Analyst.md
## 前言/背景
Nous Research 最近與 xAI 展開合作，讓擁有 X Premium (或 Premium+) 並訂閱 Grok 的用戶，能夠直接在 Hermes Agent 中使用 `x_search` 工具。X（前 Twitter）是全球宏觀經濟、地緣政治、科技與加密貨幣的「數位城鎮廣場」。過去，透過 X API 獲取資料不但昂貴且難以進行深度分析；現在，`x_search` 賦予 Hermes 原生的即時搜尋與深度研究能力，將 Hermes 真正轉化為強大的即時分析師與第二大腦。
## 章節詳細總結
### Hermes 工作流的 3 大關鍵升級 (How I’m adjusting my workflow)
1. **X 書籤的定時任務 (X bookmark cron job) 優化**：
* **過去的痛點**：依賴 X API 獲取過去 24 小時的書籤，但 API 只能讀取標題、作者與少部分內容，無法讀取全文。
* **現在的解法**：直接輸入「用 `x_search` 總結這篇文章」，`x_search` 會抓取完整文章內容，接著再交給基礎模型（如 DeepSeek-v4-flash）進行深度分析。
* **架構配置細節**：必須正確設定 `xai-oauth` 並配置好 `x_search`，確保流量是走 Grok 訂閱通道，而非昂貴的 xAI API 通道。
2. **深度研究管線 (Deep Research Pipeline) 整合**：
由於 `x_search` 返回的是原始資料 (Raw data)，未經過 Web 介面（如 Grok.com）的後處理與 Prompt 最佳化，作者與 Claude Opus 設計了一套 **6 階段研究管線**，整合多種工具：
* 使用 `x_search` 進行目標檢索。
* 使用 `cookiedotfun` MCP 工具進行市場情緒分析與 KOL 討論趨勢。
* 啟用瀏覽器 CDP 工具（Hermes 內建），讓 Agent 自動打開 Chrome 上的 Grok 進行互動。
* **資料流**：由 DeepSeek 負責整合資訊，配合 Hindsight 提取過往上下文，最終輸出一份包含過去、現在與未來預測的全面分析報告。
3. **X 追蹤者工作流 (X Tracker workflow) 降本增效**：
* 透過定時任務 (Cron jobs) 追蹤特定領域的專家帳號。
* 過去使用 X API 每天約需花費 $0.5 美元；切換至 `x_search` 後，每天的成本大幅降至約 $0.1 美元。
### 實戰除錯與經驗總結 (What I learnt so far)
1. **訂閱策略**：X 平台允許以 $10/月的價格訂閱 Grok。先訂閱 $30/月的方案後立刻取消，系統會自動提供前 3 個月每月只要 $10 的優惠。
2. **x_search 超時配置**：為了防止 `x_search` 在長任務中超時中斷，必須在 `config.yaml` 中將 `timeout_seconds` 設定為 `240` 或 `300`，並將 `retries` 設為 2。
3. **絕對不要使用 Grok 4.3 作為基礎模型 (Base Model)**：
雖然 `x_search` 預設使用 Grok 模型，但在 Hermes 的全局配置中，**切勿將 Grok 4.3 設為 Base Model**。實測證明，Grok 4.3 在瀏覽器控制 (Browser harness)、複雜邏輯推理與多輪工具呼叫 (Multi-turn tool calling) 的表現極差，經常導致任務崩潰。應該繼續使用 DeepSeek v4 負責大腦邏輯，只讓 Grok 負責 `x_search`。
4. **工具的黃金組合**：`x_search` 提供即時新聞與「為什麼 (Why)」的脈絡，而 Cookie MCP 提供結構化數據（排行榜、聲量時序表）。兩者結合能發揮出 1+1>2 的分析能力。
## 總結與結論
* **Agent 應用的典範轉移**：高階使用者的核心技能正在從「依賴 Agent 幫你想」轉向「人類提出假設，Agent 負責驗證」。
* **架構師視角 - 工具解耦 (Tool Decoupling)**：不要盲目追求全能模型。最佳的架構是「解耦」：用 DeepSeek v4 作為主控大腦（擅長邏輯推理與工具編排），用 `x_search`（由 Grok 驅動）作為專職的即時資料庫抓取器。
* **成本與效能優化**：善用平台訂閱機制的漏洞與免費的 Web 介面自動化（Browser CDP），能將原本依賴昂貴官方 API 的資料清洗流水線，轉化為極低成本的常駐微服務。
Obsidian 整理
原始文章
AI工具
停止對 Prompt 走火入魔，你的真正問題出在 CLAUDE.md (Stop Obsessing Over Prompts. Your Real Problem Is Probably CLAUDE.md)
""
Top 5 Insights
- **系統會帶來複利，而 Prompt 只是暫時的**：最頂尖的開發者不把時間花在雕琢 Prompt，而是專注於系統架構、上下文工程 (Context Engineering) 與降低模糊性。
- **將 CLAUDE.md 視為動態演進的企業記憶體 (Institutional Memory)**：每一次 AI 犯錯，都是完善 `CLAUDE.md` 的契機。長期下來，它會變成無可取代的架構指南與防呆機制。
- **競爭優勢的轉移**：AI 時代的優勢不再是誰會寫 Prompt，而是誰能設計出最穩定、防錯的 AI 協作工作流。
---
tags: [AI工具, Prompt Engineering, Claude Code, CLAUDE.md, 上下文管理]
date: 2026-05-19
source: "2026-05-19T092619+0800-Stop Obsessing Over Prompts. Your Real Problem Is Probably CLAUDE.md"
---
# 停止對 Prompt 走火入魔，你的真正問題出在 CLAUDE.md (Stop Obsessing Over Prompts. Your Real Problem Is Probably CLAUDE.md)
原始來源與檔名：2026-05-19T092619+0800-Stop Obsessing Over Prompts. Your Real Problem Is Probably CLAUDE.md
## 前言/背景
當前許多開發者抱怨 AI 工具輸出不穩定，常將原因歸咎於 Prompt 不夠詳細或模型不夠聰明。然而，決定 Claude Code 輸出品質的核心關鍵並非 Prompt，而是專案的上下文環境設定文件——`CLAUDE.md`。本文旨在點出開發者在管理 AI 上下文時的常見誤區，並提出高階開發者如何將 `CLAUDE.md` 作為整個 AI 工作流的「作業系統」來管理，以徹底消除 AI 輸出的隨機性與決策模糊性。
## 章節詳細總結
### 上下文盲區與不穩定性的根源 (The Hidden Reason Claude Feels “Inconsistent”)
Claude 每次啟動新會話時，預設都是「上下文盲區 (context-blind)」。它不了解專案的目錄結構、架構決策、歷史除錯經驗以及工作流規範。若缺乏 `CLAUDE.md` 提供全局設定，Claude 就必須「即興發揮 (improvisation)」，這正是導致輸出結果時好時壞的根本原因。
### CLAUDE.md 的真實目的：防呆系統 (The Real Purpose of CLAUDE.md)
許多人誤以為 `CLAUDE.md` 是一個「許願池 (wishlist)」或指令集，但其真實的工程價值在於 **「減少決策模糊性 (reduces decision ambiguity)」**。
最佳的 `CLAUDE.md` 並不試圖微觀控制所有事，而是專注於**防止最昂貴的錯誤重複發生**。這是一個系統性的思維轉變：從「要求 AI 做好」轉變為「建立防呆機制 (mistake prevention system)」。
### 多數 CLAUDE.md 失敗的三大陷阱 (Why Most CLAUDE.md Files Quietly Fail)
1. **文件過長 (Too Long)**：開發者常誤以為指令越多越好。事實上，過長的文件會導致指令遵從度下降、上下文品質稀釋。高效的系統優先考量清晰度而非數量。
2. **過於泛用 (Generic Instructions)**：像「寫出乾淨的程式碼 (Write clean code)」、「一步步思考」這類廢話無法改變行為，因為 LLM 早已內建這些知識。真正有效的是**專案特定的約束 (project-specific constraints)**，例如：
* 絕不能修改部屬配置 (never modify deployment configs)
* 只能使用現有的 Utils (use existing utilities only)
3. **缺乏結構 (No Structure)**：把個人偏好、架構筆記和常規指令混在一起會產生雜訊。高階設定會將全局規則、專案規則與個人工作流嚴格分層。
### 高品質 CLAUDE.md 必備的五大模組 (The 5 Parts Every High-Quality CLAUDE.md Should Have)
1. **執行指令 (Commands)**：明確告知如何執行 `dev`, `test`, `lint`, `type-check`，消除 AI 猜測的摩擦成本。
2. **架構地圖 (Architecture Map)**：定義業務邏輯、API 路由、UI 元件與狀態管理的存放位置，防止 AI 將程式碼放錯資料夾。
3. **硬性規則 (Hard Rules)**：這是 ROI 最高的區塊。判斷標準為：「如果不寫這條，Claude 會犯下昂貴的錯誤嗎？」強大的規則必須是具體、可強制執行的。尤其是**負面約束 (Negative rules)**，告訴 AI 「不要做什麼」威力無窮。
4. **工作流行為規範 (Workflow Behavior)**：控制協作模式，例如：重大變更前需詢問、只做最小範圍修改、先解釋權衡 (tradeoffs) 再改 code、邏輯分離的 Commit。
5. **界線與禁區 (Out-of-Scope Boundaries)**：極度被低估的功能。明確劃定不可觸碰的區域，例如：不要修改自動生成的檔案、避免變更依賴套件、絕對不要自動修改 Production 基礎設施。界線能帶來穩定性。
## 總結與結論
* **系統會帶來複利，而 Prompt 只是暫時的**：最頂尖的開發者不把時間花在雕琢 Prompt，而是專注於系統架構、上下文工程 (Context Engineering) 與降低模糊性。
* **將 CLAUDE.md 視為動態演進的企業記憶體 (Institutional Memory)**：每一次 AI 犯錯，都是完善 `CLAUDE.md` 的契機。長期下來，它會變成無可取代的架構指南與防呆機制。
* **競爭優勢的轉移**：AI 時代的優勢不再是誰會寫 Prompt，而是誰能設計出最穩定、防錯的 AI 協作工作流。
Obsidian 整理
原始文章
AI工程
11 個每位 AI 基礎設施工程師都該收藏的開源專案 (11 Open-Source Repos Every AI Infra Engineer Should Bookmark)
""
Top 5 Insights
- **基礎設施思維的轉變**：AI Agent 已不再只是單純的應用程式 (Application)，而是需要隔離、可觀測性與治理的自治系統 (Autonomous Systems)。
- **法規遵循即將成為硬限制**：隨著 EU AI Act (2026) 與其他地區 AI 法案的生效，完整的稽核軌跡 (Audit Trails)、風險管理與人類監督機制將從「最佳實踐」轉變為「法律強制要求」。
- **零信任與深度防禦 (Defense in Depth)**：從靜態掃描 (Trivy, Deepsec)、運行時護欄 (LlamaFirewall)、權限控制 (OPA, AgentGateway) 到底層沙箱 (Microsandbox, Container-use)，企業必須建構多層次的防禦架構，絕不可信任單一的安全邊界。
---
tags: [AI工程, 資訊安全, 基礎設施]
date: 2026-05-19
source: "20260519_2026-05-19T092614+0800-11 Open-Source Repos Every AI Infra Engineer Should Bookmark.md"
---
# 11 個每位 AI 基礎設施工程師都該收藏的開源專案 (11 Open-Source Repos Every AI Infra Engineer Should Bookmark)
原始來源與檔名：20260519_2026-05-19T092614+0800-11 Open-Source Repos Every AI Infra Engineer Should Bookmark.md
**來源資訊**：
* **原始檔名**：2026-05-19T092614+0800-11 Open-Source Repos Every AI Infra Engineer Should Bookmark.md
* **原始連結**：https://x.com/AlphaSignalAI/status/2056376024548376723
## 前言/背景
當開發者在週末快速建構出能寫程式、瀏覽網頁、甚至碰觸生產環境資料的 AI Agent 時，往往忽略了背後的基礎設施與安全隔離問題。這篇文章羅列了 11 個專為 AI Agent 設計的開源基礎設施與安全防護專案，涵蓋了從沙箱隔離、權限控制到自動化紅隊測試 (Red Teaming) 的完整生態，幫助工程師在面臨資安事故前，預先建立起企業級的防護網。
## 章節詳細總結
### AI Agent 的基礎設施與安全開源生態
#### 1. ProjectRecon/awesome-ai-agents-security (安全生態系地圖)
* 這是一個持續維護的 AI Agent 安全生態系索引，依照安全生命週期分類：紅隊測試、運行時防護 (Runtime Protection)、沙箱 (Sandboxing)、治理 (Governance) 與中介軟體 (Middleware)。
* **價值**：資安領域變動極快，這個 Repo 是了解全貌與尋找特定防護工具的起點。
#### 2. promptfoo/promptfoo (自動化紅隊測試與評估)
* 標準化的 LLM 自動紅隊測試與評估框架。涵蓋提示詞注入 (Prompt Injection)、越獄 (Jailbreaks)、PII 洩漏等測試。
* 支援 YAML 宣告式設定，原生整合 CI/CD，並被 OpenAI 與 Anthropic 內部使用。
* **價值**：將 Agent 的安全邊界測試自動化，如同軟體工程中的單元測試一樣整合進 CI 流程。
#### 3. aquasecurity/trivy (供應鏈漏洞掃描)
* 全能型的漏洞掃描工具，可掃描容器映像檔 (Container Images)、Git 儲存庫與檔案系統。
* 能捕捉脆弱的基礎映像、設定錯誤的 Terraform、外洩的機密資訊與應用程式依賴漏洞。
* **價值**：防止 Agent 運行在充滿漏洞的底層映像檔或基礎設施上，防禦現今主流的供應鏈攻擊。
#### 4. open-policy-agent/opa (AI 基礎設施的政策即程式碼)
* 通用的政策引擎 (Policy Engine)，使用 Rego 語言撰寫可讀、可測試的安全政策 (Policy-as-Code)。
* 將安全政策與應用程式碼解耦。當 Agent 呼叫工具或 API 時，OPA 負責決定是否放行 (Authorization)。
* **價值**：提供橫跨傳統雲端基礎設施與 Agent 工作負載的一致性審計與權限控制層。
#### 5. AgentGateway (MCP 與 A2A 代理伺服器)
* 專為 A2A (Agent-to-Agent) 與 MCP (Model Context Protocol) 流量設計的 AI 原生 Proxy。
* 提供 RBAC (角色基礎存取控制)、可觀測性與代理-工具互動的政策執行。
* **價值**：解決了多數團隊直接連接 MCP 而無存取控制層的危險，大幅縮小攻擊面 (Attack Surface)。
#### 6. microsoft/agent-governance-toolkit (運行時安全中介軟體)
* 直接對應 OWASP Agentic AI Top 10 風險的運行時政策引擎。
* 具備亞毫秒級 (<0.1ms) 的延遲，可以 Sidecar 或 Middleware 形式部署。
* 包含語意意圖分類器防禦「目標劫持」、隔離沙箱防禦「工具濫用」，以及自動化 Kill Switch 防禦失控 Agent。
* **價值**：針對即將生效的 EU AI Act，提供符合法規要求的全面性風險管理實作。
#### 7. anthropics/claude-code-security-review (AI 驅動的 PR 審查)
* GitHub Action，在每次 Pull Request 上運行 Claude Code 進行程式碼安全審查。
* **價值**：使用語意推理 (Semantic Reasoning) 而非正則表達式，能精準抓出靜態分析工具 (Static Analysis) 容易忽略的邏輯漏洞。
#### 8. vercel-labs/deepsec (Agent 驅動的漏洞掃描)
* 一個 AI Agent，負責掃描整個程式碼庫中潛藏多年的歷史漏洞。
* **價值**：在 Agent 讀取、修改程式碼之前，先主動清理既有的漏洞，防護層級更提前。
#### 9. dagger/container-use (編碼 Agent 的容器化環境)
* 為 Coding Agent 提供持久化、隔離的容器環境，多個 Agent 可平行運行而不衝突。
* 具備完整的 OpenTelemetry 儀表板，追蹤每個 LLM 決策、工具呼叫與錯誤。
* **價值**：將容器化帶來的隔離與可重現性 (Reproducibility) 引入 Agent 執行環境，極大化提升除錯能力。
#### 10. meta-llama/PurpleLlama/LlamaFirewell (防禦 Prompt Injection)
* Meta 開源的護欄系統 (Guardrail System)，攔截提示詞注入、掃描生成程式碼的漏洞。
* 在地端基礎設施運行 (50-100ms 延遲)，資料不出境。
* **價值**：在應用層攔截攻擊，是目前最嚴謹的開源防禦方案之一。
#### 11. microsandbox/microsandbox (可自託管的程式碼執行沙箱)
* E2B 的開源自託管替代方案，支援 Docker、gVisor、Kata Containers 與 Firecracker 隔離層。
* **價值**：消除外部 SaaS 依賴，將隔離保證與資料駐留 (Data Residency) 控制權收回企業內部。
## 總結與結論
* **基礎設施思維的轉變**：AI Agent 已不再只是單純的應用程式 (Application)，而是需要隔離、可觀測性與治理的自治系統 (Autonomous Systems)。
* **法規遵循即將成為硬限制**：隨著 EU AI Act (2026) 與其他地區 AI 法案的生效，完整的稽核軌跡 (Audit Trails)、風險管理與人類監督機制將從「最佳實踐」轉變為「法律強制要求」。
* **零信任與深度防禦 (Defense in Depth)**：從靜態掃描 (Trivy, Deepsec)、運行時護欄 (LlamaFirewall)、權限控制 (OPA, AgentGateway) 到底層沙箱 (Microsandbox, Container-use)，企業必須建構多層次的防禦架構，絕不可信任單一的安全邊界。
Obsidian 整理
原始文章
AI工程
Pi Coding Agent 最全面指南：打造極簡可控的開源模型底座 (Comprehensive Guide to Pi Coding Agent)
"Pi 不是用來取代 Claude Code 的開箱即用全家桶，它是一個「極簡可拆」的 Agent 底座，專為測試開源大模型 (如 Ring-2.6-1T)、控制上下文預算與自定義工程紀律而生。"
Top 5 Insights
- **去神話化**：Ring-2.6-1T 加上 Pi 不是能一次性生成完整系統的魔法黑盒，而是一個需要「目標清晰、流程明確、信息給足」的高效推理引擎。
- **組件化的雙刃劍**：Pi 賦予了極限的可控性，但也要求使用者具備架構師的思維，懂得自行拼裝 Plan 閘門、Context 修剪器與 Subagent 分工。
- **測試策略**：在評測新模型時，最關鍵的不是跑 Benchmark，而是把它放入一個「Plan-first、Skill-amplified、Review-driven」的真實工作流中，觀察其持續推進專案的韌性。
---
tags: [AI工程, 開發工具, Agent架構, LLM, 系統配置]
date: 2026-05-19
read: false
source: "2026-05-19T092710+0800-Pi Coding Agent 最全面指南（完美支持goal）.md"
---
# Pi Coding Agent 最全面指南：打造極簡可控的開源模型底座 (Comprehensive Guide to Pi Coding Agent)
原始來源與檔名：2026-05-19T092710+0800-Pi Coding Agent 最全面指南（完美支持goal）.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> Pi Agent = 最小化核心 (CLI + Tools) + 按需外掛的擴展包 (Skills + MCP + Subagents)
### 一句話
> Pi 不是用來取代 Claude Code 的開箱即用全家桶，它是一個「極簡可拆」的 Agent 底座，專為測試開源大模型 (如 Ring-2.6-1T)、控制上下文預算與自定義工程紀律而生。
### 餐巾紙草圖
```text
[Claude Code] 產品化黑盒：內建 Plan Mode、權限引擎、上下文壓縮 -> 綁定 Anthropic 模型 (開箱即用但難以拆解)
[Pi Agent] 極簡核心：只給讀寫工具 -> 透過 Skill / MCP 注入流程 -> 無縫接軌 OpenAI 兼容開源模型 (高度可控)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼在測試非 Anthropic (如 Ring-2.6-1T) 的開源大模型時，使用 Claude Code 會遭遇巨大的摩擦與效能瓶頸？
- **核心答案**: Claude Code 內建了大量針對 Anthropic 模型的專屬提示詞與工程假設。Pi 則提供一個透明、可控且低上下文佔用的環境，讓使用者能乾淨地測試模型的真實能力。
- **論證結構**: 工具對比 -> 模型配置實戰 -> 最小可用棧推薦 -> 避坑指南 -> 工作流設計。
### 章節骨架
1. **心智模型轉換**: Pi 不是全家桶，它是 Minimal Core。權限、記憶與進階工具都需要透過 Plugins 擴充。
2. **與 Claude Code 的對照**: Pi 贏在模型開放性與拆解度；弱在缺乏持久化記憶 (CLAUDE.md) 與開箱即用的沙盒權限。
3. **Ring-2.6-1T 模型實戰配置**: 必須使用 OpenAI `/v1` 兼容端點，保留 `xhigh` 推理檔位，並給足上下文長度。
4. **最小可用棧與避坑**: 只裝核心 5 個套件保持上下文乾淨。不要依賴 CLI 報錯，直接用 `curl` 測試端點。
5. **Plan-first + Skill 工作流**: 由於 Pi 沒有內建工程紀律，必須透過外掛強制模型「先規劃、再執行」，並利用 Skill 將隱性領域知識顯性化。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 使用者具備較高的工程能力，願意手動撰寫 `models.json` 配置、編寫 Skill 腳本，並且能自行設計與維護 Agent 的防呆與除錯工作流。
- **邊界條件**: 如果開發團隊追求的是「無腦安裝、立刻開始產出業務程式碼」，那麼封閉的 Claude Code 或 Cursor 依然是首選。Pi 更適合用來架設自定義的 Agent 評測環境或高度客製化的任務管線。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 呼應 Unix 哲學 (做一件事並把它做好) 與微核心架構 (Microkernel Architecture)。
- **深層洞見**: Skill 的價值不在於「給模型外掛能力」，而在於「把人類的隱性經驗顯性化」。AI 模型的強大不僅取決於參數量，更取決於它身處的基礎設施 (Plan、Tools、Context Pruning) 是否完善。
- **行動呼籲**: 不要把大模型當作一次性生成系統的黑盒。請建立「高推論成本模型做規劃 (Plan)，低成本模型做執行 (Execute)」的分工機制，並在長任務中隨時注入指令修正方向。
---
# Pi Coding Agent 最全面指南 (Architectural Deep Dive)
## 前言/背景
隨著開源大模型 (如 1T 參數的 Ring-2.6-1T) 能力逼近商業閉源模型，開發者需要一個能乾淨測試這些模型的 Agent 框架。本文作者指出，Claude Code 的「開箱即用」特性反而成為測試開源模型時的黑盒障礙。相對地，Pi Coding Agent 提供了一個極簡、透明、可拆解的底座，允許開發者精細控制上下文預算、外掛工具與推論級別，是打造自定義 AI 基礎設施的最佳選擇。
## 章節詳細總結
### Pi 的架構哲學與 Claude Code 對比 (心智模型转换)
* **Claude Code = 產品化全家桶**：將 Subagents, Plan Mode, MCP, 權限引擎、上下文壓縮焊死在產品裡。優點是省心，缺點是與 Anthropic 深度綁定，測試其他模型時會產生嚴重的摩擦。
* **Pi = 微核心底座 (Minimal Core)**：核心僅提供 CLI、多模型驅動與極少數讀寫工具（佔用約 7.7k Context）。所有進階功能（TypeScript 擴展、Skills、MCP）皆由使用者按需掛載。
* *架構師觀點*：Pi 提供了極高的透明度，讓「模型能力缺陷」與「環境配置缺陷」得以被明確剝離。
### 開源巨獸 Ring-2.6-1T 的配置紀律 (推荐模型配置)
在 Pi 中接入自定義模型時，配置 `models.json` 必須遵守三大紀律，否則會觸發無聲錯誤：
1. **相容性設定**：設定 `compat.supportsDeveloperRole: false`。部分 OpenAI 端點拒絕 developer 角色，此設定可強制回退至 system 角色，避免 400 錯誤。
2. **推理檔位映射**：`thinkingLevelMap` 必須明確包含 `"xhigh": "xhigh"`，否則 Pi UI 會隱藏最高推理檔位。
3. **上下文視窗**：必須給足 `contextWindow` (262k) 與 `maxTokens` (65k)。若給太小，推理預算會在 `<think>` 階段燒光導致答案被截斷。
### 動態推理成本工程 (high 和 xhigh 怎么用)
不要無腦開啟最高推理模式 (xhigh)。架構師應建立分層執行管線：
* **Ring xhigh**：複雜架構規劃、狀態機設計、最終 Code Review。
* **Ring high**：日常高頻的工程執行。
* **DeepSeek (便宜模型)**：單元測試編寫、樣板程式碼、局部除錯。
### 最小可用棧與防坑指南 (推荐的最小可用栈)
* **保持 Context 乾淨**：不要一口氣裝 22 個組件。初期僅需安裝：`mcp-adapter`, `web-access`, `subagents`, `fff (檔案尋找)`, `context-prune (上下文清理)`。
* **除錯思維**：當端點報錯時，不要依賴 Pi 的壓縮日誌。直接寫一個 Shell Script 用 `curl` 暴力遍歷所有 `reasoning_effort` 參數，確認底層 API 的真實接受度。
### 為什麼開源模型需要 Plan-First + Skill 工作流？
Pi 預設沒有強加工程紀律，因此使用者必須自己「把經驗固化進工作流」。
1. **Plan-first (先規劃再執行)**：面對複雜任務，強制模型先輸出「要讀哪些檔、風險點在哪、驗收標準」，經人類 Review 後才放行。這彌補了開源模型在超長依賴鍊中的漂移問題。
2. **Skill 的本質**：Skill 不是安裝檔，而是 SOP。將 UI 驗收標準、Repo 級除錯順序寫成 Skill，能讓模型在碰到特定情境時自動載入該領域的「人類隱性知識」。
3. **即時指令注入**：Pi 允許在 Agent 長期運行期間 (Long-running) 插入新指令而不打斷當前 Task，這提供了強大的「動態方向修正」能力。
## 總結與結論
* **去神話化**：Ring-2.6-1T 加上 Pi 不是能一次性生成完整系統的魔法黑盒，而是一個需要「目標清晰、流程明確、信息給足」的高效推理引擎。
* **組件化的雙刃劍**：Pi 賦予了極限的可控性，但也要求使用者具備架構師的思維，懂得自行拼裝 Plan 閘門、Context 修剪器與 Subagent 分工。
* **測試策略**：在評測新模型時，最關鍵的不是跑 Benchmark，而是把它放入一個「Plan-first、Skill-amplified、Review-driven」的真實工作流中，觀察其持續推進專案的韌性。
Obsidian 整理
原始文章
AI工程
別亂壓縮了——Claude、Codex、Gemini 都有的對話壓縮，省空間還是毀緩存？
""
Top 5 Insights
- **架構決策：延遲 vs 成本**：在設計長期運行的 Agent 記憶體管理模組時，必須權衡「短期重算延遲」與「長期 Token 成本」。只要未達上下文硬限制，應優先依賴模型的原生前綴緩存；當會話過於臃腫時才執行壓縮。
- **平台差異化策略**：針對不同 LLM 供應商應實作不同的 Context 管理策略。對於 Claude 需要極度避免頻繁修改歷史；對於 OpenAI 則可依賴其原生的對話管理；對於 Gemini 則可利用其隱式緩存。
- **壓縮即狀態快照**：不應將壓縮視為單純的「刪減字數」，而應視為系統狀態的快照 (State Snapshot)。在架構上，應確保壓縮過程能精確保留系統當前的核心變數與結論，以利後續的上下文接續。
---
tags: [AI工程, Prompt緩存, 上下文管理]
date: 2026-05-19
source: "20260519_2026-05-19T092606+0800-别乱压缩了——Claude、Codex、Gemini 都有的对话压缩，省空间还是毁缓存？.md"
---
# 別亂壓縮了——Claude、Codex、Gemini 都有的對話壓縮，省空間還是毀緩存？
原始來源與檔名：20260519_2026-05-19T092606+0800-别乱压缩了——Claude、Codex、Gemini 都有的对话压缩，省空间还是毁缓存？.md
**來源資訊**：
* **原始檔名**：2026-05-19T092606+0800-别乱压缩了——Claude、Codex、Gemini 都有的对话压缩，省空间还是毁缓存？.md
* **原始連結**：https://x.com/shachepi/status/2056218453791612930
## 前言/背景
在使用 LLM 進行長期對話或開發時，開發者常使用上下文壓縮指令（如 `/compact` 或 `/compress`）來釋放 Token 空間。然而，這篇文章點出了一個隱藏陷阱：壓縮動作可能會破壞 LLM 的 Prompt 緩存（Prompt Caching）機制，導致下一輪對話必須重新計算，反而增加短期的時間延遲與成本。文章分析了不同模型供應商的緩存實作差異，並給出了何時該壓縮的具體建議。
## 章節詳細總結
### 長期對話的隱藏陷阱：精確前綴匹配
現代 LLM（如 Claude, Codex, Gemini）的緩存機制，底層是基於**精確的前綴匹配 (Exact Prefix Matching)**。
* **不壓縮時**：對話歷史為 `A -> B -> C -> D`，緩存會保存 `A+B+C` 的計算狀態。新增 `E` 時，系統只需計算 `E`。
* **壓縮後**：歷史被揉成一個全新的字串 `Summary(A+B+C+D)`。因為前綴完全改變，之前的緩存全部失效，系統必須從頭對這段 Summary 進行預計算（Pre-fill）。
### 各大平台的緩存機制差異與影響
不同平台對於「精確前綴匹配」的實作與敏感度有所不同，這直接影響了壓縮指令的破壞力：
1. **Anthropic (Claude)**：**最嚴格**
* 要求從請求開頭到標記點之間的所有內容分毫不差（包括空格、大小寫）。
* 需要開發者手動注入 `cache_control` 標記（最多四個點）。
* **優勢**：緩存命中後成本降至 1/10。
* **壓縮影響**：**最致命**。一旦執行壓縮，緩存全部失效。
2. **OpenAI (Codex)**：**較具彈性**
* 使用 `conversation_id` 作為緩存鍵 (Cache Key)。
* 即使配置改變，它傾向於追加新訊息以保住既有緩存，而不是直接修改已有內容。
* 自帶自動壓縮機制（達到閾值自動 compact）。
* **壓縮影響**：較小，因為系統內部已做了最佳化。
3. **Google (Gemini)**：**最無痛**
* Gemini 2.5 以上版本預設開啟隱式緩存，開箱即用。
* 允許手動建立緩存並設定 TTL，但門檻較高（至少需要 32k tokens）。
* **優勢**：緩存折扣約為原價的 25%。
* **壓縮影響**：相對最小。
### 為什麼我們仍然需要壓縮？
儘管會破壞緩存，在以下三種架構場景中，壓縮仍然是必要的：
1. **突破硬限制 (Hard Limit)**：避免 Token 溢位或模型因為 Context 過長而出現「大海撈針」能力下降、胡言亂語的狀況。
2. **降低每輪的基礎成本**：即使緩存打了 1 折，若上下文累積到 500k tokens，每一輪依然要支付相當於 50k tokens 的費用。將其壓縮到 5k tokens，可以將後續每一輪的基礎成本大幅降低。
3. **清理干擾資訊 (Garbage Collection)**：長時間的 Debug 過程會累積大量錯誤嘗試與廢話。壓縮等同於執行一次記憶體 GC，只保留狀態與結論，提升模型對後續問題的專注度 (Attention)。
## 總結與結論
* **架構決策：延遲 vs 成本**：在設計長期運行的 Agent 記憶體管理模組時，必須權衡「短期重算延遲」與「長期 Token 成本」。只要未達上下文硬限制，應優先依賴模型的原生前綴緩存；當會話過於臃腫時才執行壓縮。
* **平台差異化策略**：針對不同 LLM 供應商應實作不同的 Context 管理策略。對於 Claude 需要極度避免頻繁修改歷史；對於 OpenAI 則可依賴其原生的對話管理；對於 Gemini 則可利用其隱式緩存。
* **壓縮即狀態快照**：不應將壓縮視為單純的「刪減字數」，而應視為系統狀態的快照 (State Snapshot)。在架構上，應確保壓縮過程能精確保留系統當前的核心變數與結論，以利後續的上下文接續。
Obsidian 整理
原始文章
AI工程
如何為 LLM 應用設計評估資料集 (Designing Eval Datasets for LLM Applications)
"Dataset 不是冰冷的數據堆，而是 LLM 應用的「單元測試套件」；在上線前，它替你驗證每一次的修改是否真正解決了問題，且沒有破壞原有的功能。"
Top 5 Insights
- **沒有 Eval 就沒有迭代**：修改 Prompt 卻不跑 Dataset，就像改了 Code 不跑 Unit Test 一樣危險。
- **資料集是活的**：它必須隨著生產環境監控到的新問題而持續擴充。
- **多元評估並行**：現代 Eval 框架允許在同一個資料集上混合使用精確匹配、相似度對比與 LLM-as-a-Judge (準則檢查) 來達到全面的品質防護。
---
tags: [AI工程, MLOps, LLM評估, Dataset, 測試驅動]
date: 2026-05-19
read: false
source: "2026-05-19T092752+0800-Designing eval datasets for LLM applications.md"
---
# 如何為 LLM 應用設計評估資料集 (Designing Eval Datasets for LLM Applications)
原始來源與檔名：2026-05-19T092752+0800-Designing eval datasets for LLM applications.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> LLM 應用迭代 = (Tracing + Monitoring 發現問題) -> 修改 Prompt/代碼 -> 執行 Dataset Eval -> 部署上線
### 一句話
> Dataset 不是冰冷的數據堆，而是 LLM 應用的「單元測試套件」；在上線前，它替你驗證每一次的修改是否真正解決了問題，且沒有破壞原有的功能。
### 餐巾紙草圖
```text
[AI Engineering Loop]
1. 生產環境 (Production) -> Tracing (追蹤) & Monitoring (監控) -> 發現 Bad Case
2. 開發環境 (Development) -> 修改 -> 跑 Dataset (測試集) 驗證 -> 通過 -> 部署
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 當你在監控中發現 LLM 應用的瑕疵並修改了代碼/Prompt 後，如何在上線前確保這個修改是有效且安全的？
- **核心答案**: 必須建立標準化的評估資料集 (Eval Dataset)。透過將生產環境的真實案例轉化為具備「輸入、預期輸出與詮釋資料」的測試項目，實現可重複的實驗驗證。
- **論證結構**: 回顧 AI 工程循環 -> 介紹資料集在循環中的定位 -> 拆解資料集欄位與預期輸出模式 -> 探討高品質資料集的特徵 -> 啟動指南。
### 章節骨架
1. **AI 工程循環回顧**: 追蹤(Tracing) -> 監控(Monitoring) -> 資料集(Datasets) -> 實驗(Experiments) -> 評估(Evaluation)。
2. **資料集的定位**: 它是在部署前，用來測試「變更(Experiment)」的防護網。
3. **資料集項目 (Dataset Item)**: 包含必填的 Input，以及選填的 Expected Output 與 Metadata。
4. **預期輸出的 4 種模式**:
- *Exact Match*: 精確匹配 (如分類標籤)。
- *Reference Answer*: 參考答案 (用於語義相似度對比)。
- *Evaluation Criteria*: 評估準則 (如「必須包含退款政策」)。
- *無預期輸出*: 依賴 Reference-free 評估器 (如檢查語氣或格式)。
5. **好資料集的特徵與來源**: 反映真實生產狀況、範圍明確、大小適中；來源應包含生產日誌抽樣、人工手寫邊緣案例、與 AI 合成數據。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 開發者必須願意將傳統軟體工程中的「測試驅動開發 (TDD)」思維引入 AI 開發中。不寫測試集就改 Prompt 直接上線，等同於蒙眼狂奔。
- **邊界條件**: 針對主觀性極強的生成任務 (如創意寫作)，建立精確的 Expected Output 非常困難，這時需重度依賴 Evaluation Criteria 或 LLM-as-a-Judge 的無參考 (Reference-free) 評估。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 軟體工程的 TDD (Test-Driven Development) 與 CI/CD 流程。
- **深層洞見**: 資料集的建立是一個動態演進的過程。不要一開始就追求完美的萬能測試集；應根據具體想要改善的模組 (如：摘要模組、檢索模組)，切割出範圍清晰的小型資料集。
- **行動呼籲**: 不要再靠「感覺」調教 Prompt。立刻從你的生產日誌 (Tracing) 中抓取 10 個失敗案例，手寫出預期輸出，建立你的第一個 AI 單元測試集。
---
# 如何為 LLM 應用設計評估資料集 (Architectural Deep Dive)
## 前言/背景
本文出自 Langfuse Academy 的 AI Engineering Lifecycle 系列。在傳統軟體開發中，單元測試是保障修改不引入新 Bug 的基石；在 LLM 應用中，這個角色由「評估資料集 (Eval Datasets)」擔當。本文詳述了資料集的內部結構、評估模式，以及如何將其融入 CI/CD 流程。
## 章節詳細總結
### AI 工程閉環 (The AI Engineering Loop)
持續改進 AI 系統依賴於一個循環：
1. **生產端**：透過 Tracing (追蹤) 與 Monitoring (監控) 獲取系統真實運作的能見度，並發掘 Bad Cases。
2. **開發端**：針對問題進行修改 (Experiment)，並使用 **Dataset** 進行回測，確保修改通過 Evaluation (評估) 後再上線。
### 資料集項目的解剖 (The dataset item & Expected output)
每一個 Dataset Item 代表一個 Test Case，包含：
* **Input (必填)**：輸入給 LLM 的上下文。
* **Expected Output (選填)**：用以評測輸出的黃金標準。
* **Metadata (選填)**：輔助追蹤的標籤。
依據 Evaluator (評估器) 的不同，`Expected Output` 有四種設計模式：
1. **Exact Match (精確匹配)**：適用於分類或實體擷取 (如：`billing_inquiry`)。
2. **Reference Answer (參考答案)**：提供黃金範例，評估器透過計算語義相似度來打分。
3. **Evaluation Criteria (評估準則)**：提供檢查清單 (如：「必須包含幫助中心連結」)，適合規則導向的驗證。
4. **Nothing (無基準線)**：使用無參考評估器 (Reference-free evaluator)，單純檢查輸出的「安全性」、「語氣」或「JSON 格式」。
### 什麼是好的資料集？(What makes a good dataset)
* **真實映射 (Mirrors Production)**：必須能代表系統在真實世界中會遇到的輸入分佈。
* **範圍清晰 (Clear in Scope)**：可以針對端到端 (End-to-End) 測試，也可以針對特定子模組 (如 RAG 的檢索層) 獨立建立資料集。
* **適應工作流 (Right Size)**：
* *小而快的資料集*：放入 CI/CD pipeline，每次 Push 代碼時執行。
* *大而全的資料集*：用於定期的大型回歸測試。
### 冷啟動策略 (Where to start)
不要試圖憑空想像所有測試案例。資料集的建立應分三步走：
1. **從生產環境萃取 (Tracing)**：抓取真實用戶日誌中的失敗或典型案例 (可進行匿名化處理)。
2. **人工手寫 (Hand-written)**：針對邊緣案例 (Edge cases) 或是絕對不能出錯的行為底線，手寫測試用例。
3. **合成數據 (Synthetic)**：當確認了需要測試的維度後，使用 AI 批量生成大量相似案例以擴大覆蓋率。
## 總結與結論
* **沒有 Eval 就沒有迭代**：修改 Prompt 卻不跑 Dataset，就像改了 Code 不跑 Unit Test 一樣危險。
* **資料集是活的**：它必須隨著生產環境監控到的新問題而持續擴充。
* **多元評估並行**：現代 Eval 框架允許在同一個資料集上混合使用精確匹配、相似度對比與 LLM-as-a-Judge (準則檢查) 來達到全面的品質防護。
Obsidian 整理
原始文章
AI工程
實驗：Karpathy Autoresearch 的人類版本 (Experiments The Human Version of Karpathy's Autoresearch)
"在將 AI 開發交給全自動代理 (Agentic Autoresearch) 之前，人類必須先學會如何手動控制變數、比較結果並定義什麼才是「更好」。"
Top 5 Insights
- **品質、成本與速度的拉扯**：這三個指標在 AI 應用中極少能同時提升。唯有透過實驗，才能在具體的數據上看到這三者如何互相拉扯，而非停留在抽象理論。
- **自動化無法取代問題定義**：自動化的實驗迴圈 (如 Autoresearch) 就像推進器，如果方向錯誤，只會讓你「失敗得更快」。人類理解「什麼是成功」的這一步是無法被外包的。
- **數據品質決定實驗上限**：測試用的數據集必須覆蓋生產環境中 Agent 實際處理的邊緣案例，而不僅僅是那些「容易處理」的標準案例。
---
tags: [AI工程, AI Engineering Loop, 實驗與評估, Autoresearch, Prompt Engineering]
date: 2026-05-19
source: "2026-05-19T092643+0800-Experiments The Human Version of Karpathy's Autoresearch.md"
---
# 實驗：Karpathy Autoresearch 的人類版本 (Experiments The Human Version of Karpathy's Autoresearch)
原始來源與檔名：2026-05-19T092643+0800-Experiments The Human Version of Karpathy's Autoresearch.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 系統進化 = 資料集 (Dataset) + 變數控制 (Variables) + 基準對比 (Baseline vs Output) + 評估器 (Evaluator)
### 一句話
> 在將 AI 開發交給全自動代理 (Agentic Autoresearch) 之前，人類必須先學會如何手動控制變數、比較結果並定義什麼才是「更好」。
### 餐巾紙草圖
```text
[Dataset] --+--> [Baseline System] ----> [Output A] --+
| |--> [Compare / Evaluator] --> [Actionable Insight]
+--> [Changed Condition] --> [Output B] --+
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: AI 團隊如何系統化地優化 AI 應用，避免盲目修改導致「加速失敗」？
- **核心答案**: 實踐 AI 工程迴圈 (AI Engineering Loop)，透過控制單一變數（如模型、提示詞、上下文），在真實數據集上進行 A/B 實驗與結果對比。
- **論證結構**: 步驟型與歸納型
### 章節骨架
1. **什麼是實驗**: 實驗是分離因果關係的唯一方法，包含四要素（數據、基準、變數、對比）。
2. **常見變數**: 模型 (Model)、提示詞 (Prompt)、上下文 (Context)、工具存取 (Tool access)、代理架構 (Agent architecture)。
3. **實驗場景**: 新模型測試、提示詞改進、新架構對比。
4. **實踐路徑**: 從手動開始 (20-30 筆真實數據) -> 肉眼對比 -> 引入評估器 -> 整合 CI/CD。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 系統的優化方向必須清晰可見，且存在具代表性的生產級數據集可以作為測試基準。
- **邊界條件**: 若評估指標錯誤或數據集不能代表真實場景，那麼高速的自動化實驗只會帶來「更快的失敗 (faster failure)」。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 與傳統軟體工程中的 A/B 測試、CI/CD 迴歸測試以及機器學習模型評估高度相關。
- **深層洞見**: Karpathy 的 Autoresearch 之所以成功，是因為他擁有 20 年的經驗直覺來定義「什麼是好」。自動化只是加速，無法取代對問題本質的理解。
- **行動呼籲**: 不要一開始就建立龐大的基礎設施或盲信自動化評估器。先手動閱讀 20-30 個真實的 Trace 對比，建立對系統行為的直覺，再進行擴展與自動化。
---
# 實驗：Karpathy Autoresearch 的人類版本 (Architectural Deep Dive)
## 前言/背景
隨著 Karpathy 的 Autoresearch (自動化代理在一夜之間進行 700 次實驗並優化模型訓練) 引起熱議，許多團隊渴望將 AI 優化流程全自動化。然而，本文指出：在交由 Agent 自動化之前，人類工程師必須先掌握「手動」實驗的科學方法，透過控制變數並在真實數據上對比結果，才能避免系統朝向錯誤的方向盲目狂奔。
## 章節詳細總結
### 實驗在 AI 工程迴圈中的定位 (How experiments fit into the loop)
要系統化地理解並改進 AI 系統，必須具備**分離因果關係**的能力。這正是實驗的價值所在。
每次實驗包含四個核心元素：
1. **數據集 (Dataset)**
2. **基準配置 (Baseline configuration)**
3. **變更變數 (Changed variable)**
4. **輸出比對方式 (Way to compare outputs)**
*架構師原則*：每次盡量只改變一個變數。唯一的例外是變數高度耦合時，例如換了新模型通常需要配上新的提示詞才能發揮其真實效能。
### AI 系統的五大實驗變數 (Variables)
1. **模型 (Model)**：在推理能力、速度與成本之間進行權衡。
2. **提示詞 (Prompt)**：最常用的槓桿。在改 Prompt 前，必須區分這是「規格問題 (specification problem，指令模糊)」還是「泛化問題 (generalization problem，模型無法一致地執行清晰指令)」。前者直接修改，後者才值得設計實驗測量。
3. **上下文 (Context)**：輸入給模型的資訊，如檢索文件 (RAG)、對話歷史或使用者中繼資料。
4. **工具存取 (Tool access)**：新增/移除工具，或修改工具的描述語以提高其被模型發現的機率。
5. **代理架構 (Agent architecture)**：單代理對抗多代理、選擇哪種 Agent harness、框架，以及如何拆解任務。這會極大影響系統的延遲與成本。
### 實驗的實踐路徑與 CI/CD 整合 (Where to start & CI/CD)
* **拒絕過早自動化**：不要一開始就建立龐大的基礎設施或直接導入自動評估器 (Evaluator)。
* **「20-30」手動驗證法則**：從生產環境的 Trace 中提取 20-30 個真實案例（如退款請求）。將這 20 個案例分別用舊配置與新配置跑一次，**並將結果並排放置，用肉眼閱讀**。
* **建立直覺再自動化**：透過手動比對，工程師能理解什麼是「更好」，這時再將這個直覺編碼為 Evaluator。
* **CI/CD 整合**：一旦 Evaluator 穩定，即可將實驗整合進 CI/CD 流水線，在每次部署前確保新配置在基準測試中的得分不會退化。
## 總結與結論
* **品質、成本與速度的拉扯**：這三個指標在 AI 應用中極少能同時提升。唯有透過實驗，才能在具體的數據上看到這三者如何互相拉扯，而非停留在抽象理論。
* **自動化無法取代問題定義**：自動化的實驗迴圈 (如 Autoresearch) 就像推進器，如果方向錯誤，只會讓你「失敗得更快」。人類理解「什麼是成功」的這一步是無法被外包的。
* **數據品質決定實驗上限**：測試用的數據集必須覆蓋生產環境中 Agent 實際處理的邊緣案例，而不僅僅是那些「容易處理」的標準案例。
Obsidian 整理
原始文章
AI工程
把 AI 工程手冊轉化為 AI 能直接執行的紀律 (Executable Agentic Engineering Guidelines)
"方法論寫在 PDF 裡只能給人看，AI 看完還是憑感覺做事；唯有將「建議」翻譯成帶有強制性攔截 (Hard Gates) 的 Skill 檔，才能真正建立 AI 工程紀律。"
Top 5 Insights
- **約束帶來安全感 (Constraints create psychological safety)**：當底層有堅固的驗證閘門與真相源映射時，AI 會更敢於執行大範圍的複雜重構，因為它知道自己不會弄壞系統。
- **可攜帶的工程紀律**：這套架構不綁定單一平台（相容 Claude Code, Codex, OpenCode）。轉換模型時，工程紀律跟著走。
- **競爭維度的轉移**：多數人還在比較第一層的「AI 開發工具哪家強 (Cursor vs Claude Code)」。但真正拉開產能差距的，是第二層的「專案庫工程紀律建置 (Repository Readiness)」。
---
tags: [AI工程, Agent架構, 工程紀律, Skill, 系統整合]
date: 2026-05-19
read: false
source: "2026-05-19T092657+0800-字节写了20篇AI工程手册，我把它做成了AI能直接执行的纪律.md"
---
# 把 AI 工程手冊轉化為 AI 能直接執行的紀律 (Executable Agentic Engineering Guidelines)
原始來源與檔名：2026-05-19T092657+0800-字节写了20篇AI工程手册，我把它做成了AI能直接执行的纪律.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> Agent 生產力 = 方法論 (Know-how) × 系統約束力 (Executable Constraints)
### 一句話
> 方法論寫在 PDF 裡只能給人看，AI 看完還是憑感覺做事；唯有將「建議」翻譯成帶有強制性攔截 (Hard Gates) 的 Skill 檔，才能真正建立 AI 工程紀律。
### 餐巾紙草圖
```text
[人類的文件] "建議修改前確認來源" -> AI 說好 -> 亂改一通 (失敗)
[AI的紀律] "MUST identify canonical files" -> 找不到 -> 拒絕執行並要求澄清 (成功)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼讀了很多 Agent 方法論，實作時 AI 的表現依然不受控、充滿幻覺或遺忘目標？
- **核心答案**: 因為「知道」與「做到」之間缺少了**可執行的結構 (Executable Structure)**。必須把人類讀的指引 (Guidelines)，轉譯成 AI 嚴格執行的約束機制 (Skills)。
- **論證結構**: 問題剖析 -> 機制轉譯 -> 工具實踐 (Kit) -> 實戰驗證
### 章節骨架
1. **三個斷層**: 建議被忽視、驗證無硬性攔截、規則未分層導致上下文混亂。
2. **轉譯動作**: 從「建議 (SHOULD)」升級為「機制 (MUST / MUST NOT)」，實施漸進式上下文載入。
3. **Agentic Engineering Kit**: 包含行為約束的 `agentic-engineering-guidelines` 與審計指令 `/agentic-scan`。
4. **實戰掃描**: 透過 8 個維度 (0-3 分) 對專案進行體檢，找出容易讓 AI 翻車的盲點。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 開發團隊願意在專案初期投入時間整理「真相源 (Source of Truth)」並定義驗證閘門 (Gates)，且 LLM 具備足夠的指令遵從能力 (Instruction Following) 來理解 `MUST` 語意。
- **邊界條件**: 框架只能提供「紀律」，無法提供「業務邏輯」。具體的 L1-L3 業務規則仍需要開發者手動填入，否則 AI 依舊無法處理特定領域需求。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 與合規性檢查 (Compliance as Code) 及軟體工程中的 Linter / CI Pipeline 概念高度共鳴。
- **深層洞見**: 約束並不是限制，而是安全網。當有了明確的真相源映射與驗證機制兜底時，AI 才敢於進行大規模的複雜重構。
- **行動呼籲**: 放棄寫給人看的方法論文件。立即使用 `/agentic-scan` 審計你的專案庫，並建立強制驗證的 Agent 紀律。
---
# 把 AI 工程手冊轉化為 AI 能直接執行的紀律 (Architectural Deep Dive)
## 前言/背景
網路上充斥著各種 AI 工程方法論，但開發者常面臨「懂了概念卻不知如何落地」的窘境。本文作者精闢地指出，寫在 Markdown 裡的「建議」AI 只會點頭但不執行。真正的解法是將最佳實踐轉譯為具有強制約束力的「工程紀律 (Engineering Disciplines)」，並透過開源工具包 `agentic-engineering-kit` 提供 AI 原生的驗證攔截與上下文分層管理機制。
## 章節詳細總結
### 認知斷層：為什麼寫了規則 AI 卻不聽？(三个"知道但做不到"的断层)
方法論的陷阱在於缺乏「強制力」。
1. **建議 vs 絕對命令**：寫 `請在修改前確認`，AI 會當成建議。必須使用 RFC 2119 標準的 `MUST NOT`，強制約束其行為。
2. **缺乏驗證閘門 (Gate)**：沒有「必須回報驗證指令否則不准宣告完成」的硬性攔截，AI 就會靠「感覺」回報測試通過，最終導致 CI 崩潰。
3. **未分層的全局變數**：把所有 React 規範、後端流程塞進同一個文件，會導致嚴重的上下文干擾 (Context pollution)。
### 架構轉譯：從「建議」到「機制」的 3 大實作(三个翻译动作：从"建议"到"机制")
1. **強制前置聲明**：將「建議確認來源」轉為 `MUST identify canonical files before editing`。Agent 必須明確說出真相源與鏡像文件的邊界才能開工。
2. **強制驗證聲明**：`MUST state verification run or why not`。用明確的 CLI 執行結果取代 AI 的「幻覺自信」。
3. **L0-L3 漸進式架構分層 (Progressive Disclosure)**：
* **L0 (全局)**：輸出格式、溝通風格。
* **L1 (路徑匹配)**：React 寫法、Go 錯誤處理。
* **L2 (動態載入)**：特定業務規則。
* **L3 (手動觸發)**：發布流程、Code Review。
*架構師視角*：這是降低 Context Window 負擔的最優解。只預載 Metadata，需要時才拉取完整 Instructions 與 Resources。
### 核心工具包解構 (Kit 里有什么)
作者開源的 `agentic-engineering-kit` 包含兩個組件：
1. **`agentic-engineering-guidelines` (Skill 檔)**：
核心是 `execution-constitution.md`，寫死了 10 條不可逾越的紀律（如：模糊需求必須先轉化為 Spec、禁止順手重構無關程式碼、強制沉澱踩坑經驗等）。背後連結了 12 個按需載入 (On-demand loading) 的參考文件。
2. **`/agentic-scan` (審計指令)**：
針對倉庫進行 8 個維度的 AI 友善度掃描（0-3分）。包含 Context Engineering, Spec Discipline, Agent Loop Hygiene 等，精準揪出導致 AI 翻車的結構性缺陷。
## 總結與結論
* **約束帶來安全感 (Constraints create psychological safety)**：當底層有堅固的驗證閘門與真相源映射時，AI 會更敢於執行大範圍的複雜重構，因為它知道自己不會弄壞系統。
* **可攜帶的工程紀律**：這套架構不綁定單一平台（相容 Claude Code, Codex, OpenCode）。轉換模型時，工程紀律跟著走。
* **競爭維度的轉移**：多數人還在比較第一層的「AI 開發工具哪家強 (Cursor vs Claude Code)」。但真正拉開產能差距的，是第二層的「專案庫工程紀律建置 (Repository Readiness)」。
Obsidian 整理
原始文章
AI工程
當你停止「寫 Prompt」時，Claude Code 的真正威力才開始展現 (The Real Power of Claude Code Starts When You Stop “Prompting”)
"AI 的競爭優勢已經從「寫好 Prompt」轉移到「設計高階工作流與系統編排」，約束與記憶才是讓 AI 從聊天機器人升級為工程系統的關鍵。"
Top 5 Insights
- **AI 放大了系統的本質**：脆弱的系統加上 AI 會以更快的速度產出垃圾 (Garbage in, garbage out faster)；而強大的系統加上 AI 則會無情地產生複利。
- **閉環回饋設計**：將原本 `生成 → 手工審查` 的單向流程，改造成 `生成 → 測試 → 分析 → 改善 → 重複` 的閉環迴圈，是解鎖 AI 自動化開發的終極鑰匙。
- **核心競爭力轉移**：未來的問題不再是「AI 能寫 Code 嗎？」，而是「你能否設計出有效驅動 AI 的系統？」。系統思維 (System Thinking) 是這個時代的唯一護城河。
---
tags: [AI工程, Claude Code, 系統思維, Workflow Design, Agent架構]
date: 2026-05-19
read: false
source: "2026-05-19T092648+0800-The Real Power of Claude Code Starts When You Stop “Prompting”.md"
---
# 當你停止「寫 Prompt」時，Claude Code 的真正威力才開始展現 (The Real Power of Claude Code Starts When You Stop “Prompting”)
原始來源與檔名：2026-05-19T092648+0800-The Real Power of Claude Code Starts When You Stop “Prompting”.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 高效 AI 輸出 = (上下文 + 約束條件) × 迴圈驗證 × 專案記憶
### 一句話
> AI 的競爭優勢已經從「寫好 Prompt」轉移到「設計高階工作流與系統編排」，約束與記憶才是讓 AI 從聊天機器人升級為工程系統的關鍵。
### 餐巾紙草圖
```text
[傳統模式] Prompt -> Output -> 手動修復 (脆弱、不一致)
[系統模式] Context -> Constraints -> Reasoning -> Execution -> Validation -> Memory -> Refinement (自動化複利)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼即使使用相同的 Claude 模型，初學者的輸出往往混亂且不穩定，而進階開發者卻能獲得極高的工程槓桿？
- **核心答案**: 差異不在於 Prompt 技巧，而在於**系統設計 (System Design)**。進階開發者提供架構上下文、記憶系統、推理約束與驗證迴圈。
- **論證結構**: 對比型
### 章節骨架
1. **迷思破除**: 提示詞 (Prompt) 只是暫時的，系統 (Systems) 才能產生複利。
2. **不穩定的根源**: 模糊的上下文導致 AI 只能「即興發揮」。
3. **典範轉移**: 開發者的核心技能從「執行 (Execution)」轉移至「編排 (Orchestration)」。
4. **高價值工作流**: 強制 AI 先思考 (結構化推理) 再生成。
5. **記憶與約束**: 越多的約束帶來更高的精度；持久化記憶讓 AI 具備專案感知能力。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 開發者必須對軟體架構、邊界條件與驗證機制有深刻的理解，才能設定出有效的「約束 (Constraints)」並設計出防呆的迴圈。
- **邊界條件**: 對於極度簡單、一次性的小腳本任務，系統化的工作流可能顯得過於繁瑣（殺雞用牛刀）；但只要專案規模稍大，系統思維的收益就會呈現指數級增長。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 與傳統軟體工程中的 CI/CD、防呆設計、以及系統架構設計 (System Architecture) 的思維完全一致。
- **深層洞見**: AI 輸出的問題通常不是「語法錯誤」，而是「思考品質低劣 (poor thinking)」。如果你不引導 AI 的推理過程，你稍後就必須為它的錯誤付出除錯代價。
- **行動呼籲**: 放棄無腦的「生成 -> 人工審查」線性流程，開始建立包含「架構約束」、「推理前置」與「持久化記憶」的封閉式自我驗證迴圈。
---
# 當你停止「寫 Prompt」時，Claude Code 的真正威力才開始展現 (Architectural Deep Dive)
## 前言/背景
隨著 AI 開發工具（如 Claude Code）的普及，多數開發者仍將其視為「更聰明的自動補齊工具」，在反覆嘗試與失敗中浪費時間。本文一針見血地指出：AI 輔助開發的競爭力不再是「提示詞工程 (Prompt Engineering)」，而是「系統編排 (System Orchestration)」。唯有透過設計包含上下文、約束、推理、執行、驗證與記憶的系統化工作流，才能讓 AI 真正轉變為高產出的工程環境。
## 章節詳細總結
### 提示詞是暫時的，系統帶來複利 (Prompts Are Temporary. Systems Compound.)
* **傳統線性工作流的困境**：`Prompt → Output → Manual Fixes`。這種模式在簡單任務中可行，但一旦專案變大，輸出就會變得不穩定，Bug 倍增，且 AI 會遺忘先前的架構決策。
* **高槓桿的系統化工作流**：真正的 Claude 工程環境應該是：`Context → Constraints → Reasoning → Execution → Validation → Memory → Refinement`。這不僅消除了隨機性，更建立了持續改進的飛輪效應。
### 從「執行」到「編排」的技能轉移 (The Shift From “Prompting” to “Workflow Design”)
未來的 AI 原生開發者，其時間分配將發生根本性轉變：
* **減少的時間**：打字寫 Code、修復語法、撰寫樣板程式碼 (Boilerplate)。
* **增加的時間**：定義系統邊界、編排 AI 推理邏輯、設計工作流、管理上下文、驗證最終輸出。
* **架構師洞察**：高產出的開發者並非自己做了 10 倍的工作，而是他們建立了能夠「倍增產出」的系統。
### 高階工作流的三大實戰紀律 (Advanced Workflow Disciplines)
1. **生成前強制結構化思考 (Force structure before generation)**
不要直接要求 AI「建立功能」。必須強制 AI 依序進行：
* 分析問題 → 找出邊緣案例 (Edge cases) → 解釋架構權衡 (Tradeoffs) → 定義架構決策 → 提出實作策略 → **最後才生成程式碼**。
* *價值*：這解決了 AI 產出最大的痛點——「思考品質低劣」。
2. **約束提升創造力與精度 (Constraints Actually Improve Creativity)**
在 AI 系統中，約束帶來的是「精度」。明確定義架構邊界、禁止修改的範圍、允許使用的工具、程式碼標準與相依性規則。
* **無約束 = 混亂的輸出；有約束 = 聚焦的執行**。
3. **持久化專案記憶 (Memory Is the Most Underrated Part)**
不要讓每一次會話都從零開始。必須為 AI 建立專案記憶庫：
* 架構決策紀錄 (ADRs)
* 命名標準與可重用模式 (Reusable patterns)
* 除錯筆記與邊緣案例
這讓 AI 具備了「專案感知 (project-aware)」能力，其對輸出品質的提升遠勝於任何提示詞技巧。
## 總結與結論
* **AI 放大了系統的本質**：脆弱的系統加上 AI 會以更快的速度產出垃圾 (Garbage in, garbage out faster)；而強大的系統加上 AI 則會無情地產生複利。
* **閉環回饋設計**：將原本 `生成 → 手工審查` 的單向流程，改造成 `生成 → 測試 → 分析 → 改善 → 重複` 的閉環迴圈，是解鎖 AI 自動化開發的終極鑰匙。
* **核心競爭力轉移**：未來的問題不再是「AI 能寫 Code 嗎？」，而是「你能否設計出有效驅動 AI 的系統？」。系統思維 (System Thinking) 是這個時代的唯一護城河。
Obsidian 整理
原始文章
AI工程
讓 Codex 在你睡覺時自己寫代碼 (Let Codex write code while you sleep)
"不要把 AI 當作能獨立思考產品的資深工程師，而是把它當成一個不知疲倦、但需要你發派精確「夜班工單」的底層執行者。"
Top 5 Insights
- **自動化的前提是可預測性**：無邊界的指令只會帶來混亂，極致的邊界約束才能帶來高效率的夜間產出。
- **並行探索，串行修改**：對於多 Agent 協作，建議在夜間進行「並行唯讀探索」，而在寫入程式碼時應保持串行 (Sequential)，以避免 Git 衝突。
- **系統化的派工思維**：給 AI 一句願望，它還你一堆猜測；給它一張規格嚴謹的工單，它還你一份精準的產出。
---
tags: [AI工程, 自動化, 工作流, Agent管理, 系統工程]
date: 2026-05-19
read: false
source: "2026-05-19T092702+0800-让 Codex 在你睡觉时自己写代码.md"
---
# 讓 Codex 在你睡覺時自己寫代碼 (Let Codex write code while you sleep)
原始來源與檔名：2026-05-19T092702+0800-让 Codex 在你睡觉时自己写代码.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 夜間自動化成功率 = 清晰的輸入邊界 + 限定的寫入範圍 + 明確的驗收命令
### 一句話
> 不要把 AI 當作能獨立思考產品的資深工程師，而是把它當成一個不知疲倦、但需要你發派精確「夜班工單」的底層執行者。
### 餐巾紙草圖
```text
[錯誤的許願] "幫我優化專案" -> AI 猜測邊界 -> 隔天充滿 Bug 與衝突 (失敗)
[正確的派工] 定義範圍 + 定義約束 + 指定驗證命令 -> AI 嚴格執行 -> 隔天收穫確定的產出 (成功)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼讓 AI 在無人值守的情況下自動寫程式，隔天早上經常得到一堆半成品、版本衝突與權限災難？
- **核心答案**: 因為開發者習慣對 AI「許願」而非「派工」。必須提供結構化的夜班工單，限定 AI 的修改範圍並強制執行驗證命令。
- **論證結構**: 案例對比 -> 分類歸納 -> 實踐框架
### 章節骨架
1. **睡前任務的致命傷**: 模糊的「幫我優化」會導致 AI 無限發散。
2. **三類最佳夜間任務**: 唯讀掃描產出報告、小範圍針對性補測試、文檔與工程衛生維護。
3. **三類絕對禁止的任務**: 產品判斷過重、跨前後端的大重構、需要真實生產環境權限的操作。
4. **實踐工具**: 標準化的「夜班工單範本」與 `AGENTS.md` (AI 的員工手冊)。
5. **隔日驗收紀律**: 先看 Diff 範圍與測試結果，最後才看 AI 的自我總結。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 開發者對專案的架構邊界有極高的掌控力，知道哪些檔案可以動、哪些不能動，並已經建立好自動化驗證機制 (如 `npm run check`)。
- **邊界條件**: 若專案缺乏良好的單元測試覆蓋率或自動化 Linter 腳本，AI 在夜間就無法進行自我驗證，夜間自動化將失去意義。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 與任務拆解 (Work Breakdown Structure, WBS) 以及微服務架構的隔離原則高度相關。
- **深層洞見**: AI 能替你熬夜，但不能替你想清楚什麼事值得熬夜。自動化的本質不是省去 Code Review，而是把 Review 從「大海撈針」變成「檢查已經收斂的 Patch」。
- **行動呼籲**: 停止在下班前對 AI 輸入「重構這包程式碼」。改為在倉庫中建立 `AGENTS.md`，並使用結構化的「工單模板」來指派任務。
---
# 讓 Codex 在你睡覺時自己寫代碼 (Architectural Deep Dive)
## 前言/背景
隨著 AI Agent 的能力提升，許多開發者幻想能實現「睡前丟需求，醒來收 PR」的完全自動化。然而，本文作者基於半年的實戰經驗指出：如果把 Agent 當作能自主決策的工程師來「許願」，只會引發災難。真正的夜間自動化需要極致的邊界管理與工程紀律，將 AI 視為一個需要明確「夜班工單」的執行者。
## 章節詳細總結
### 夜間自動化的核心條件 (睡前任务，最怕一句“帮我优化一下”)
在無人值守 (Unattended) 的狀態下，AI 一旦遇到模糊地帶就會開始「幻覺式猜測」。
*架構師原則*：睡前交接任務必須滿足三個絕對條件：
1. **輸入清楚**
2. **寫入範圍清楚** (明確指定可讀與可寫的檔案清單)
3. **驗收命令清楚** (如 `npm run check`)
### 三類高 ROI 的夜班任務 (夜间自动化的 3 类好任务)
1. **唯讀掃描 (Read-only Scans)**：最安全、成功率最高。例如掃描 TODOs、風險端點、未覆蓋測試的邊界。隔日產出優先級報告供人類決策。
2. **窄範圍補測試 (Small-scope Testing)**：禁止下達「提高覆蓋率」這種大而化之的指令，這會讓 AI 產出大量低價值測試。必須指定行為，例如「只針對未付費無法產生公開報告這條路徑補測試」。
3. **文檔與工程衛生 (Documentation)**：例如更新 `README.md` 中的環境變數或啟動指令。這類任務不影響線上邏輯，隔日極易 Review。
### 絕對禁止無人值守的三大雷區 (3 类任务，不要睡前交给它)
1. **產品決策過重**：如「提升轉換率」。AI 無法在夜間自主進行視覺取捨與商業策略評估。
2. **跨前後端的架構大重構**：牽一髮動全身的狀態欄位修改，容易導致第二天發生毀滅性的合併衝突 (Merge Conflicts)。
3. **涉及真實生產權限**：絕對禁止夜間觸碰生產資料庫或發送真實信件。權限管理應遵循最小權限原則 (Least Privilege)。
### 實踐框架：夜班工單與 AGENTS.md (员工手册)
* **工單模板 (Work Order Template)**：包含「目標、上下文、修改範圍 (允許與排除)、硬規則 (禁加依賴、禁改 UI)、驗證命令、最終輸出要求」。這是一套嚴謹的合約。
* **AGENTS.md**：這是給 AI 的「員工手冊」。將團隊的硬性架構規定 (如「不允許將確定性引擎替換為 LLM 調用」) 寫在專案根目錄，這比依賴 AI 的短期記憶更為可靠。
### 隔日驗收的標準作業程序 (第二天早上怎么验收)
人類工程師早上的驗收順序必須是防禦性的：
1. **`git diff --stat`**：首先確認修改範圍是否失控。
2. **檢查驗證日誌**：確認自動化測試是否真實跑完且通過。
3. **閱讀關鍵 Diff**：審查具體的程式碼邏輯。
4. **最後才看 AI 總結**：AI 的總結是線索，不是事實 (Summaries are clues, not facts)。若 AI 未執行測試卻宣告完成，該任務視為無效。
## 總結與結論
* **自動化的前提是可預測性**：無邊界的指令只會帶來混亂，極致的邊界約束才能帶來高效率的夜間產出。
* **並行探索，串行修改**：對於多 Agent 協作，建議在夜間進行「並行唯讀探索」，而在寫入程式碼時應保持串行 (Sequential)，以避免 Git 衝突。
* **系統化的派工思維**：給 AI 一句願望，它還你一堆猜測；給它一張規格嚴謹的工單，它還你一份精準的產出。
Obsidian 整理
原始文章
AI研究
本週熱門 AI 論文回顧 (Top AI Papers of the Week: May 11-17, 2026)
"本週研究亮點集中於「不改變模型架構下的效率提升 (Lighthouse Attention, Token Superposition Training)」，以及「重新審視 Agent 的工具與記憶邊界 (Grep 取代向量檢索, 記憶詛咒)」。"
---
tags: [AI研究, 論文摘要, 模型架構, Attention, 多智能體]
date: 2026-05-19
read: false
source: "2026-05-19T092740+0800-Top AI Papers of the Week.md"
---
# 本週熱門 AI 論文回顧 (Top AI Papers of the Week: May 11-17, 2026)
原始來源與檔名：2026-05-19T092740+0800-Top AI Papers of the Week.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> AI 前沿發展 = 長文本訓練優化 (Lighthouse/TST) + 檢索基建反思 (Grep vs Embeddings) + Agent 狀態機升級 (δ-mem/AI Co-Mathematician)
### 一句話
> 本週研究亮點集中於「不改變模型架構下的效率提升 (Lighthouse Attention, Token Superposition Training)」，以及「重新審視 Agent 的工具與記憶邊界 (Grep 取代向量檢索, 記憶詛咒)」。
### 餐巾紙草圖
```text
[架構優化] Lighthouse Attention / TST -> 僅在訓練期優化，推論期與 Vanilla 相容 -> 降本增效
[Agent 基建] Grep 檢索 >= 向量 Embedding (如果 Harness 寫得好)
[長期記憶] δ-mem (隨插即用在線矩陣) / 記憶詛咒 (歷史越長越不合作)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: AI 領域在長文本訓練成本、檢索增強基礎設施、以及多智能體/Agent 的長期記憶管理上，有哪些最新的突破與反思？
- **核心答案**: Nous Research 提出了兩種訓練期優化方案大幅降本；研究證明傳統 grep 檢索在 Agent 中可匹敵 Embedding；DeepMind 的數學 Agent 證明了異步狀態機的威力；同時研究警告過長的 Agent 記憶會導致「合作崩潰」(Memory Curse)。
- **論證結構**: 列舉 10 篇頂尖論文，涵蓋架構優化、檢索技術、內部可解釋性、動態記憶與多智能體協作。
### 章節骨架
1. **Lighthouse Attention & TST**: Nous Research 的兩項預訓練優化技術，皆實現了「訓練期加速，推論期無需改架構」。
2. **Is Grep All You Need?**: 挑戰向量資料庫迷思，證明文本正則檢索在優秀的 Harness 下足以勝任 Coding Agent。
3. **δ-mem & Memory Curse**: 前者提出無須微調的在線外掛記憶矩陣；後者揭示 Agent 記憶過長會導致喪失未來意圖 (退化為糾結過去)。
4. **AI Co-Mathematician (DeepMind)**: 異步、有狀態的數學研究 Agent，在 FrontierMath 創下 48% 新紀錄。
5. **Mechanistic Interpretability**: 在 LLM 內部發現將數字表示為旋轉圓的「幾何計算機」。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: AI 研究正在從「暴力堆疊參數與無窮延伸 Context」轉向「更高性價比的訓練外掛 (Wrappers)」與「更精細的狀態機工程 (Stateful Harness)」。
- **邊界條件**: `Grep > Embedding` 的結論成立前提是代碼庫具備良好的結構與索引；在高度非結構化的自然語言檢索中，向量依然不可或缺。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 呼應奧卡姆剃刀原則 (Occam's razor) —— 簡單的 Grep 勝過複雜的 Vector DB；以及軟體工程的狀態機 (State Machine) 設計。
- **深層洞見**: 「記憶詛咒 (Memory Curse)」完美解釋了為什麼很多長線 Agent 最終會崩潰——當歷史過長，模型會將算力用於反思過去，而非規劃未來。記憶的「品質與內容」比「長度」更重要。
- **行動呼籲**: 開發 Coding Agent 時，考慮將複雜的向量資料庫拔除，換回強大的 Grep 搜尋；在設計長線 Agent 時，務必實作「記憶淨化 (Memory Sanitization)」機制。
---
# 本週熱門 AI 論文回顧 (Architectural Deep Dive)
## 前言/背景
DAIR.AI 整理了 2026 年 5 月中旬最具影響力的 10 篇 AI 論文。本期趨勢明顯指向「訓練效率的工程破解」、「Agent 基礎設施的返璞歸真 (Grep)」，以及「跨度記憶的機制探討」。這些研究為未來 AI 系統的降本增效與穩定運行提供了極具價值的學術支撐。
## 章節詳細總結
### 訓練期黑魔法：無損推論的加速器
Nous Research 本週連續發布兩篇極具影響力的預訓練論文：
* **Lighthouse Attention**：這是一種訓練期的 Attention Wrapper，透過對 Query, Key, Value 進行階層式對稱壓縮來加速長文本訓練。關鍵在於訓練末期會拔除此 Wrapper 進入恢復期，使得最終部署的模型**完全相容標準 SDPA 推論架構**，無須修改底層代碼。
* **Token Superposition Training (TST)**：在訓練前三分之一階段，將連續的 Token 打包並平均其 Embedding 進行預測，獲得 2-3 倍的加速。這同樣不改變任何模型架構與分詞器。
### 基建反思：Grep 取代向量檢索 (Is Grep All You Need?)
業界常預設 Coding Agent 必須搭配 Vector DB。但本論文證明，在設計優良的 Agent Harness (控制環境) 下，傳統的文字搜尋 (Grep) 表現完全匹敵甚至超越 Embedding。研究指出，過去 Embedding 的勝出，多半是因為 Harness 設計的干擾。**如果代碼庫結構清晰，Grep 是更高效、更低成本的選擇。**
### Agent 的記憶雙面刃 (δ-mem vs The Memory Curse)
* **δ-mem**：提供一種免微調的解法。在凍結的骨幹模型上，外掛一個小型的在線聯想記憶矩陣 (透過 delta-rule 即時更新)，產生低秩 (Low-rank) 的注意力修正。這取代了暴力的 Context Extension。
* **記憶詛咒 (Memory Curse)**：研究發現，在長期博弈中，**擴大 Agent 的歷史記憶反而會導致合作崩潰**。原因是過長的歷史會將模型的注意力拉向「糾結過去的互動」，而非「規劃未來的收益」。解法是「記憶淨化 (Sanitization)」——過濾長度不變，但將內容替換為前瞻性摘要。
### AI 數學家與機制可解釋性
* **AI Co-Mathematician (DeepMind)**：突破傳統一問一答，採用**異步、有狀態 (Stateful)、多工作流**的架構。它可以長線在背景跑計算、查文獻，並能澄清使用者意圖。在極難的 FrontierMath 基準上創下 48% 的新高。
* **幾何計算機 (Geometric Calculator)**：Goodfire 在模型內部發現了算術運算的機械原理——模型將數字編碼為激活空間中的傅立葉特徵 (旋轉的圓圈)，並以「剩餘數系統 (Residue Number System)」的變體來執行運算。
Obsidian 整理
原始文章
Agent架構
Agent Runtime 正在成為 AI 的下一個主戰場 (Agent Runtime: The Next Battlefield of AI)
"模型決定了能力的理論上限，但 Agent Runtime (運行時) 決定了實際表現；在模型成本趨近於零的時代，建構具備強大轉換成本的 Runtime 平台已成為 AI 巨頭的終極戰場。"
Top 5 Insights
- **典範轉移**：「模型公司」的定義正在消解，未來只會有提供全端解決方案的「Agent 平台公司」。
- **開發者選型策略更新**：評估 AI 輔助開發工具時，必須將「模型支援廣度、架構分層程度、Prompt 開放性與 Cache 策略」納入考量。
- **在地實測不可少**：公用 Benchmark 僅提供方向，開發者必須在自己的真實代碼庫中，使用 Harbor 等框架執行任務 A/B 測試，才能找到真正契合自身工作流的最強 Runtime。
---
tags: [Agent架構, AI工程, Runtime, 系統底層, 行業趨勢]
date: 2026-05-19
read: false
source: "2026-05-19T092718+0800-Agent Runtime 正在成为 AI 的下一个主战场.md"
---
# Agent Runtime 正在成為 AI 的下一個主戰場 (Agent Runtime: The Next Battlefield of AI)
原始來源與檔名：2026-05-19T092718+0800-Agent Runtime 正在成为 AI 的下一个主战场.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> Agent 綜合能力 = 基礎模型智商 (IQ) + Runtime 工程優化 (Prompt 策略 + 工具定義 + 上下文管理 + 錯誤閉環)
### 一句話
> 模型決定了能力的理論上限，但 Agent Runtime (運行時) 決定了實際表現；在模型成本趨近於零的時代，建構具備強大轉換成本的 Runtime 平台已成為 AI 巨頭的終極戰場。
### 餐巾紙草圖
```text
[過去] 模型 API 競爭 -> 拼參數、拼跑分 -> 切換成本極低 (護城河淺)
[現在] Agent Runtime 戰場 -> 拼 Prompt Caching, 工具定義, 狀態持久化 -> 形成生態與企業工作流鎖定 (護城河深)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼在模型能力日益同質化的今天，Agent 的運行環境 (Runtime/Harness) 變得比單純選擇模型更加重要？
- **核心答案**: 實證數據顯示，優秀的 Runtime 工程能帶來等同於「模型跨代升級」的性能提升 (最高 10-20%)。隨著 Token 價格歸零，AI 公司的護城河正從 API 轉向封閉或半封閉的 Agent 平台。
- **論證結構**: 數據舉證 (Cline 基準測試) -> 剖析 Runtime 差異原因 -> 巨頭戰略佈局 (OpenAI/Anthropic/DeepSeek) -> 對開發者的啟示。
### 章節骨架
1. **4.8 個百分點的震撼**: 同一個 Claude 模型在 Cline 與 Claude Code 上的差距，等於一次模型大版本迭代的紅利。
2. **Runtime 的四大核心優化**: System Prompt 重構、工具定義精簡、上下文壓縮策略 (Prompt Caching 穩定性)、錯誤處理與反饋閉環。
3. **巨頭的向下滲透**: OpenAI 成立 Deployment Co., Anthropic 推出 Partner Network，DeepSeek 大量招募 Harness PM，證明純 API 模式正在終結。
4. **Token 歸零後的商業邏輯**: 當模型切換只需改一行 ID 時，唯一的護城河在於「生態鎖定」(System prompt, Skills, MCP 連接)。
5. **Builder 的選型策略**: Runtime 的選擇維度比模型更複雜，必須在真實代碼庫進行 A/B 測試。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 未來的 AI 應用不再是簡單的 API 呼叫，而是深度依賴特定 Harness 的長期狀態機 (State Machine)。
- **邊界條件**: Harness 的優化有其極限 (約 75% 的修復空間)，若底層模型的邏輯推理能力 (如 Haiku 級別) 根本無法應付複雜重構，再強的 Runtime 也無法彌補那 25% 的能力天花板。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 類似於作業系統 (OS) 對硬體效能的榨取；硬體 (模型) 決定算力極限，但 OS 的排程、記憶體管理 (Runtime) 決定了最終體驗。
- **深層洞見**: 上下文壓縮的策略反直覺——為了維持 Prompt Caching 的命中率以降低成本，壓縮時應「刪除尾部最新對話」而非「頭部舊對話」，因為 Prefix 的穩定性才是降本關鍵。
- **行動呼籲**: 開發者不應再將 Runtime 視為「隨便選一個好看的 UI」，而應視為核心基礎設施，親自用真實 Repo 進行 A/B 測試。
---
# Agent Runtime 正在成為 AI 的下一個主戰場 (Architectural Deep Dive)
## 前言/背景
長久以來，開發者普遍認為「模型決定能力，工具只是外殼」。但隨著 2026 年 Cline 的基準測試與各大 AI 巨頭的招募動作曝光，這個假設被徹底推翻。本文深入探討了 Agent Runtime (運行時/Harness) 如何透過底層工程優化，壓榨出等同於模型代際升級的效能，並分析了此現象背後的商業護城河邏輯。
## 章節詳細總結
### 數據實證：Runtime 帶來的代際跨越 (4.8 个百分点是什么量级)
在 Terminal-Bench 2.0 中，同一個 `claude-opus-4.7` 模型，運行在 Cline 上比在 Claude Code 上高出 4.8%。這 4.8% 的差距，等同於從 `opus-4.6` 升級到 `4.7` 的紅利。更驚人的是，Cline 團隊僅透過純 Runtime 級別的優化 (Hill Climbing A/B 測試)，就將舊模型的勝率提升了 10%，這證明了 **75% 的 Agent 失敗並非模型能力不足，而是 Runtime 工程缺陷導致**。
### Runtime 差異的四大技術支柱 (为什么 runtime 能差出这么多)
1. **Prompt 系統設計**：在長任務的幾十輪迭代中，精確的 System Prompt 決定了模型能否維持方向感而不致迷失。
2. **工具定義 (Tool Schema)**：工具參數的描述方式與返回格式直接決定正確率，必須將 Provider 邏輯隔離，專注於 Agent Loop 本身。
3. **上下文與快取管理 (Context & Caching)**：Agent 視窗會迅速膨脹。為了最大化利用 Prompt Caching (命中與未命中成本差 10 倍)，在執行 Context Compaction 時，必須**優先刪除尾部噪音，保持頭部 Prefix 穩定**。這不僅是優化，更是經濟上的可行性約束。
4. **錯誤回饋閉環**：當模型呼叫工具出錯時，Runtime 不能只報錯，必須提供狀態上下文與可選路徑，幫助模型自我修正。
### 巨頭的戰略位移與商業邏輯 (所有模型公司都在往下走 & Token 价格归零)
* **API 定價戰的終結**：隨著 DeepSeek V4-Flash 將成本打到不可思議的地步，純 API 銷售已無法支撐研發。
* **切換成本的焦慮**：模型 API 的切換成本趨近於零 (只需改 Model ID)。為了建立護城河，AI 公司必須轉向 Agent 平台 (如 OpenAI 的 Frontier、Anthropic 的 Partner Network)，透過企業資料綁定、MCP 協定與專屬 Skills 來鎖定用戶工作流。
* **生態滲透 vs 平台鎖定**：DeepSeek 目前依賴開源與超低價進行滲透，但急需建立專屬的 Harness 平台來轉換這份流量，否則極易被替換。
## 總結與結論
* **典範轉移**：「模型公司」的定義正在消解，未來只會有提供全端解決方案的「Agent 平台公司」。
* **開發者選型策略更新**：評估 AI 輔助開發工具時，必須將「模型支援廣度、架構分層程度、Prompt 開放性與 Cache 策略」納入考量。
* **在地實測不可少**：公用 Benchmark 僅提供方向，開發者必須在自己的真實代碼庫中，使用 Harbor 等框架執行任務 A/B 測試，才能找到真正契合自身工作流的最強 Runtime。
Obsidian 整理
原始文章
Agent架構
Agentic AI: How to Save on Tokens
""
---
title: "Agentic AI: How to Save on Tokens"
source: "https://medium.com/data-science-collective/agentic-ai-how-to-save-on-tokens-9a1571ac6c85"
author:
- "[[Ida Silfverskiöld]]"
published: 2026-05-05
created: 2026-05-19
description: "Strategies for reducing token usage and costs in Agentic AI systems: Caching, lazy-loading, routing, compaction."
tags:
- "clippings"
- "Agent架構"
- "AI工程"
- "成本優化"
read: false
---
# Agentic AI: How to Save on Tokens
## 🎯 NAPKIN (核心洞見公式與餐巾紙草圖)
**核心概念**：
Agent Cost Optimization = (Prompt Caching + Semantic Caching) + (Lazy Loading Tools) + (Model Routing) + (Context Compaction)
**餐巾紙草圖 (節省 Tokens 策略)**：
```mermaid
graph TD
A[Incoming Request] --> B{Semantic Cache Hit?}
B -->|Yes| C[Return Cached Answer]
B -->|No| D{Task Difficulty Router}
D -->|Easy| E[Cheap Model / Subagent]
D -->|Hard| F[Expensive Model]
F --> G[Load Static Prompt with K/V Cache]
G --> H[Lazy Load Relevant Tools]
H --> I[Execute Task]
I --> J[Compact Context / Drop Exhaust]
```
---
## 🦴 ROUND 1: 骨架掃描 (XRay Scanner)
### 1. 文章要解決的核心問題是什麼？
隨著 AI Agent 的發展，系統提示詞 (System Prompt) 包含的工具和上下文越來越多，導致輸入 Token 數量暴增 (例如單次對話高達 150K Token)，使得營運成本極為昂貴，且影響效能。
### 2. 作者提出了什麼解決方案或論點？
提出了四個核心設計原則來節省 Token 和成本：
1. 重複利用 Tokens (Prompt Caching & Semantic Caching)
2. 不預先載入閒置的 Tokens (延遲載入工具 / Lazy Loading Tools)
3. 根據任務難度路由模型 (Model Routing & Cascading)
4. 保持上下文乾淨 (Context Compaction)
### 3. 這個解決方案的關鍵要素有哪些？
* **Prompt Caching**：利用前綴匹配 (Prefix caching)，將靜態的提示詞 (如角色設定、基礎工具) 快取 K/V Tensors，可節省大量運算時間和高達 90% 的輸入成本。
* **Lazy Loading Tools**：不要一次塞入數百個工具。讓 Agent 先透過 `tool_search` 搜尋需要的工具，找到後再將工具定義插入上下文中。
* **Routing & Cascading**：將簡單的問題交給小型/便宜的模型 (如 Haiku 或 GPT-3.5)，只在低信心度時升級給大型模型 (Opus/GPT-4)。
* **Context Compaction**：建立狀態管道，清理執行過程中產生的「廢氣」(如過多的 logs、原始輸出)，只保留有用的狀態。
---
## 🥩 ROUND 2: 血肉解剖 (XRay Dissector)
### 第一層：快取機制 (Caching) 的差異
* **Prompt Caching (KV 快取)**：要求精確匹配 (Exact prefix match)。將穩定的內容放在 Prompt 最前面。適合包含大量固定規則和工具定義的系統。
* **Semantic Caching (語意快取)**：透過 Embeddings 與 Cosine Similarity 匹配。適合有大量重複問題的 Q&A 系統。難點在於如何設定 TTL (存活時間) 和過濾條件，否則容易回傳錯誤答案。
### 第二層：動態上下文管理 (Dynamic Context)
當擁有上百個工具或 MCP 伺服器時，暴力載入會讓 Agent 失焦。Anthropic 的 `tool_search` 示範了如何透過先搜尋、後載入的方式 (Progressive Discovery) 大幅降低 Token 消耗，並保持 Context 清潔，提高模型選擇工具的準確率。
### 第三層：上下文壓縮 (Context Compaction) 作為系統工程
清理 Context 不僅是為了省錢，更是為了解決效能下降問題。
要避免把所有的 grep 結果、測試日誌直接倒進 Context。需要有系統地過濾：保留「架構決策」、「錯誤特徵」，丟棄「完整的測試日誌」和「重複的檔案內容」。研究顯示，6 倍壓縮率能節省高達 70% 預算，並提升問題解決率。
---
## 🧠 ROUND 3: 靈魂提取 (XRay Extractor)
### 本質 (Essence)
「高效率的 Agent 系統並非把所有資訊都塞給最聰明的模型，而是建立一個具有層級過濾、記憶快取、動態載入的漏斗架構。」
### 遷移 (Transfer)
* **架構設計**：在設計 jkopay-agents 時，針對法律/營運領域的龐大知識庫，必須實作 Prompt Caching (將法規前綴快取)，以及 Tool Search (動態載入特定法律條文的檢索工具)。
* **Subagents 模式**：利用較小、便宜的模型來執行探索和資料整理，最後再由大模型進行推理總結，兼顧成本與輸出品質。
---
## 🏗️ Architectural Deep Dive (架構師深研)
**Cascading Routing (階層式路由) 與 Speculative Cascades**
文章提到 Google 的 "Speculative Cascades" 概念，這是在兼顧成本與品質上的絕佳實踐。
1. **便宜模型先行 (Cheap-first)**：所有的 request 都先送給小型/便宜的模型處理。
2. **輕量級驗證 (Lightweight Checker)**：利用輸出結果的對數機率 (logprobs) 或邊際不確定性 (margin-style uncertainty) 進行快速驗證。
3. **升級機制 (Escalate)**：如果驗證器判定信心度不足，才將 Request 送交大型模型。
**實務權衡 (Trade-off)**：
* 這比「在執行前預測任務難度」的路由器 (Predictive Router) 更可靠，因為直接評估生成的答案品質比較容易。
* 缺點是：小型模型有時候會「過度自信地回答錯誤 (confidently wrong)」。必須要有一套防護機制 (Guardrails) 或嚴格的驗證規則，這會增加一些開發成本。
* **潛力**：測試顯示，這類方法能在保持 GPT-4 級別品質的同時，節省約 50% 的成本，並且延遲 (Latency) 影響極小 (<20ms)。
Obsidian 整理
原始文章
Agent架構
Hermes 24小時工作的秘密：Cron、Gateway 和 Heartbeat (The Secret to 24/7 Autonomous Agents)
"Agent 無法真正 24 小時運作的根本原因，不是 Prompt 寫得不夠狠，而是缺乏一個能按時把它叫醒的排程器 (Gateway/Cron)，以及一套讓它在每次失憶醒來後能接續工作的持久化文件系統 (State Files)。"
Top 5 Insights
- **系統即記憶**：Agent 可以失去聊天上下文，但絕對不能失去寫在檔案系統裡的工作上下文。
- **無狀態化設計**：將 Agent 視為一個無狀態 (Stateless) 的處理單元，每一次喚醒都靠讀取外部檔案來重建靈魂。
- **除錯清單**：如果 Agent 停擺，檢查四件事：Gateway 是否運行？Cron 語法是否正確？Prompt 是否自包含(不依賴「剛才」)？有沒有實體檔案承接狀態？
---
tags: [Agent架構, Hermes, 工作流, 系統工程, 自動化]
date: 2026-05-19
read: false
source: "2026-05-19T092756+0800-Hermes 24小时工作的秘密：Cron、Gateway 和 Heartbeat.md"
---
# Hermes 24小時工作的秘密：Cron、Gateway 和 Heartbeat (The Secret to 24/7 Autonomous Agents)
原始來源與檔名：2026-05-19T092756+0800-Hermes 24小时工作的秘密：Cron、Gateway 和 Heartbeat.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 長期自治 = Gateway (後台常駐鬧鐘) + Cron (定時喚醒) + Heartbeat.md (醒來後的 SOP) + State Files (外部持久化狀態)
### 一句話
> Agent 無法真正 24 小時運作的根本原因，不是 Prompt 寫得不夠狠，而是缺乏一個能按時把它叫醒的排程器 (Gateway/Cron)，以及一套讓它在每次失憶醒來後能接續工作的持久化文件系統 (State Files)。
### 餐巾紙草圖
```text
[錯誤的長期自治]
Chat Window: "請繼續 24 小時工作" -> Agent: "好的我繼續" -> 等待用戶輸入 (永遠停擺)
[正確的長期自治 (Hermes)]
Cron 觸發 (每 30 分鐘) -> Gateway 啟動新 Session -> Agent 讀取 HEARTBEAT.md (SOP)
-> Agent 讀取 Task Queue (知道進度) -> 推動工作 -> 寫入 Run State -> 關閉並等待下一次喚醒
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼對 Agent 下達「不要停，繼續工作」的指令，它嘴上答應，實際上做完一輪對話 (Turn) 就停擺了？
- **核心答案**: 大多數 Agent 的底層交互單位是單一回合 (Turn)。要實現 24 小時自治，必須依賴外部排程器定時喚醒 (Gateway+Cron)，並將上下文從「聊天視窗」轉移到「檔案系統 (狀態檔)」中。
- **論證結構**: 釐清認知誤區 (不是 Prompt 問題) -> 拆解 Hermes 的四層自治機制 -> 提供 Heartbeat 模板與 Cron 策略 -> 文件結構與 Git 最佳實踐。
### 章節骨架
1. **問題不在提示詞**: 模型依賴外部觸發，沒有 Runtime 再度喚醒，它就無法自行發起下一輪。
2. **Hermes 的四大部件**:
- *Gateway*: 真正的後台守護行程。
- *Cron*: 負責排程喚醒 (注意 `every` 關鍵字)。
- *Heartbeat*: 定義每次醒來的標準作業程序 (SOP)，防止光說不練。
- *狀態文件*: 取代脆弱的聊天記錄，用檔案持久化記憶。
3. **實戰配置**: 推薦的 30m / 12h / 48h 多層次 Cron 策略；以及 `current-state.md`, `task-queue.md` 等最小狀態檔結構。
4. **Git 不是日誌**: 不應讓 Agent 頻繁自動 push，應將 Git 視為完成明確單元後的審計帳本。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 開發者必須意識到：每一次 Cron 喚醒的 Agent 都是一個「全新、失憶」的實例 (Fresh Session)。它完全不知道「剛才」發生了什麼。
- **邊界條件**: 高頻率的喚醒 (如每 5 分鐘) 若沒有配合嚴格的 Heartbeat 阻擋與進度校驗，會導致 Agent 瘋狂消耗 Token 卻只產生空泛的「正在繼續」日誌。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 伺服器開發中的無狀態架構 (Stateless Architecture) 與定時任務 (Cron Job) 邏輯。
- **深層洞見**: **「不要讓聊天記錄承載連續性，要讓文件系統承載連續性。」** Agent 的靈魂不應該綁在一個隨時會被截斷的 Context Window 上，而應該持久化於工作目錄的 Markdown 檔案中。
- **行動呼籲**: 放棄在 Prompt 裡寫「繼續工作」。立刻為你的專案建立 `HEARTBEAT.md` 與 `task-queue.md`，並啟動背景 Gateway 進行定時調度。
---
# Hermes 24小時工作的秘密 (Architectural Deep Dive)
## 前言/背景
開發者試圖建立一個 24 小時全自動運作的交易研究 Agent，卻發現無論 Prompt 寫得多麼嚴厲，Agent 總是在完成一輪回應後停擺。本文一針見血地指出：問題不在模型智力，而在於缺乏支撐長期自治的 Runtime 基建。作者透過 Hermes Agent 框架，詳細拆解了實現真正 24 小時工作的工程機制。
## 章節詳細總結
### 認知翻轉：問題不在提示詞
多數對話式 AI 的底層邏輯是 `Request -> Response -> Suspend` (一問一答)。當你要求它「繼續工作」時，它能在文本上規劃美好的下一步，但系統底層並沒有機制自動發起下一個 `Request`。**真正的自治，是將長任務切碎，透過定時器反覆喚醒，而不是硬撐一個無限長的對話視窗。**
### 實現自治的四大核心部件
在 Hermes 框架中，長期工作由四個機制協同完成：
1. **Gateway (後台守護)**：如果你只設定了 Cron 卻沒啟動 Gateway (`hermes gateway install`)，任務只會躺在列表裡。Gateway 才是那個真正在後台「看錶叫醒 Agent」的守護行程。
2. **Cron (排程器)**：設定喚醒頻率。陷阱注意：設定 `30m` 是一次性任務，必須使用 `every 30m` 才能實現循環喚醒。
3. **Heartbeat (心跳 SOP)**：每次 Cron 喚醒的都是一個「全新的 Session」。必須透過 `HEARTBEAT.md` 明確指示 Agent 醒來後要做的標準動作：讀取狀態、選擇任務、實質推進工作單元、更新檔案。**嚴禁只輸出計畫。**
4. **狀態文件 (State Files)**：取代脆弱的聊天紀錄。Agent 必須從硬碟讀取 `current-state.md` (當前進展) 與 `task-queue.md` (任務看板)，才能找回「我是誰、我在哪、我要做什麼」。
### 實戰工作流建議
* **多頻率排程策略**：
* `every 30m`: Work Heartbeat (推動日常具體工作)
* `every 12h`: Short Review (短週期覆盤，避免偏航)
* `every 48h`: Major Review (更新方向與清退廢棄任務)
* **最小文件結構**：
必須包含 `HEARTBEAT.md` (做什麼)、`continuity_policy.md` (運行規則)、`task-queue.md` (下一步)、`run-state.md` (上次接力狀態)。
### 安全與儲存紀律 (Git 不应该当作实时日志)
Agent 會頻繁修改檔案，但**絕對不要讓 Cron 任務自動 push 到 Git 遠端**。Git 是審計帳本，應在完成明確的 Milestone 後才 commit。更需嚴防 Agent 將 API Key、密碼或高頻變動的資料庫檔案誤推上雲端。
## 總結與結論
* **系統即記憶**：Agent 可以失去聊天上下文，但絕對不能失去寫在檔案系統裡的工作上下文。
* **無狀態化設計**：將 Agent 視為一個無狀態 (Stateless) 的處理單元，每一次喚醒都靠讀取外部檔案來重建靈魂。
* **除錯清單**：如果 Agent 停擺，檢查四件事：Gateway 是否運行？Cron 語法是否正確？Prompt 是否自包含(不依賴「剛才」)？有沒有實體檔案承接狀態？
Obsidian 整理
原始文章
Agent架構
How to Build Production-Ready AI Agents: MCP, CLI, and Skills — the Right Tool for the Right Job
""
---
title: "How to Build Production-Ready AI Agents: MCP, CLI, and Skills — the Right Tool for the Right Job"
source: "https://medium.com/agentic-builders/how-to-build-production-ready-ai-agents-mcp-cli-and-skills-the-right-tool-for-the-right-job-701dc102863f"
author:
- "[[Ana Bildea]]"
published: 2026-05-02
created: 2026-05-19
description: "A step-by-step guide to the 2026 connectivity stack (Skills, CLI, MCP) that powers enterprise agents."
tags:
- "clippings"
- "Agent架構"
- "MCP"
read: false
---
# How to Build Production-Ready AI Agents: MCP, CLI, and Skills — the Right Tool for the Right Job
## 🎯 NAPKIN (核心洞見公式與餐巾紙草圖)
**核心概念**：
The 2026 Agent Connectivity Stack = Skills (Domain Knowledge) + CLI (Local, Composability) + MCP (Enterprise Governance, Rich Semantics)
**餐巾紙草圖 (三層連接架構)**：
```mermaid
graph TD
A[Agent Brain] --> B(Skills)
A --> C(CLI / Computer Use)
A --> D(MCP / Connective Tissue)
B -.->|Markdown instructions, rules| E[Domain Context]
C -.->|Unix-style, highly composable, token efficient| F[Local Execution]
D -.->|JSON-RPC, OAuth, Governance, Audit Trails| G[SaaS / Enterprise Data]
```
---
## 🦴 ROUND 1: 骨架掃描 (XRay Scanner)
### 1. 文章要解決的核心問題是什麼？
在將 AI Agent 推向生產環境 (特別是企業級應用) 時，單一的連接方式 (如全依賴 MCP 或全依賴 CLI) 無法滿足所有需求。開發者對於如何選擇合適的工具整合方案感到困惑。
### 2. 作者提出了什麼解決方案或論點？
頂級的 Agents 不會在 MCP、CLI 或 Skills 之間做單一選擇，而是根據情境，同時且靈活地使用這三種「連接堆疊 (Connectivity Stack)」。不同的任務應該使用最適合的工具。
### 3. 這個解決方案的關鍵要素有哪些？
* **Skills**：領域知識。可重複使用的 Markdown 文件 (如 `.claude/skills/`)，教導模型如何使用工具。
* **CLI / Computer Use**：本地執行。利用 Unix 哲學，高組合性且節省 Token (依賴模型既有對 `git` 等指令的預訓練)。
* **MCP (Model Context Protocol)**：整合層。提供強型別的 Schema、身分驗證 (OAuth)、治理與稽核軌跡，適合 SaaS 和企業系統。
* **Programmatic Tool Calling (Code Mode)**：讓 Agent 寫腳本執行工具，而非依賴多次 LLM 輪詢的序列呼叫。
* **Progressive Discovery**：漸進式載入工具 (透過 tool search) 以節省 Context Bloat。
---
## 🥩 ROUND 2: 血肉解剖 (XRay Dissector)
### 第一層：何時使用 MCP vs CLI
* **MCP**：當你需要強型別的返回結果、平台獨立性、身分驗證與企業資安稽核時。MCP 是確定性的 (Deterministic)，但代價是回傳的 JSON 經常龐大，耗費 Token。
* **CLI**：當工具已經廣泛存在於模型的預訓練資料中時 (如 `jq`, `curl`)。CLI 非常節省 Token (通常回傳 ~200 Tokens)，且允許利用管道 (Pipes) 與重定向進行高效率組合。
### 第二層：優化 MCP 的設計模式
* **詳盡的參數標註 (Annotated Parameters)**：給予工具與參數清晰的描述，幫助 LLM 準確推斷。
* **Progressive Discovery**：不要把幾百個 MCP Tools 一次載入。提供一個搜尋工具讓模型在需要時才載入特定工具的 schema。
* **為 Agent 設計 (Design for Agents)**：不要只是把 REST API 1:1 映射成 MCP，要根據 Agent 解決問題的邏輯來設計意圖清晰的工具。
### 第三層：Programmatic Tool Calling (Code Mode)
傳統的 Tool Calling 是 sequential 的，每一次呼叫都要經過 LLM 推理的網路延遲。Code Mode 提供了一個 REPL 環境 (如 V8 或 Python Sandbox)，讓模型一次性寫出編排腳本 (orchestration script) 執行多個動作，極大地降低了延遲。
---
## 🧠 ROUND 3: 靈魂提取 (XRay Extractor)
### 本質 (Essence)
「在企業環境中，Agent 的連通性不是單選題，而是利用 MCP 建立治理框架、利用 CLI 獲得執行效率、並利用 Skills 注入領域智慧的協奏曲。」
### 遷移 (Transfer)
* **Agent 系統架構設計**：這篇文章為 jkopay-agents 提供了清晰的指導。內部的運營系統可以透過 MCP 封裝 (解決認證與稽核)，但資料過濾與腳本執行則交給 CLI 工具處理，最後透過 Skills 將特定法務流程的 S.O.P 傳遞給模型。
---
## 🏗️ Architectural Deep Dive (架構師深研)
**MCP 2026 年的演進與企業落地 (Enterprise Adoption of MCP)**
文章點出了 2026 年 MCP 協議的重要演進，解決了 2025 年推廣初期的痛點：
1. **無狀態傳輸 (Stateless Transport)**：
為了解決在 Kubernetes 與 Cloud Run 部署 MCP Server 的困難，提出了新的無狀態傳輸協議，取代過去強制保持連線的限制。
2. **跨應用程式存取 (Cross-App Access)**：
利用公司的 Identity Provider (IdP) 實現 MCP Servers 間的 SSO (單一登入)。這對於企業級 Agent 至關重要，確保 Agent 只能存取授權使用者可見的資料 (RBAC)。
3. **Skills over MCP**：
將 "Skills" (領域知識) 與 "Tools" (執行動作) 結合。MCP Server 不僅能暴露 API (Tools)，還能透過 `skills/list` 和 `skills/get` 端點，把該領域的操作守則與提示詞一起傳遞給 Client 端的 Agent。
**結論**：MCP 的批評者 (嫌 Token 太大、認證麻煩) 指出的問題都是工程挑戰，而非協議本身的死穴。為了換取企業級的治理 (Governance) 與安全審計 (Audit trails)，MCP 是無可替代的核心「結締組織 (Connective Tissue)」。
Obsidian 整理
原始文章
Agent架構
什麼是 AI Agent 的核心：一個約 300 行程式碼的 ReAct 迴圈 (What's actually inside an AI agent: a 300~ LoC ReAct loop)
""
Top 5 Insights
- **權限隔離 (Least Privilege)**：在架構 Agent 的工具層時，必須實行嚴格的最低權限原則。絕不可直接將危險的系統指令（如 `shell.exec`）暴露給 Agent，應使用沙盒或受限的 API 介面。
- **狀態管理與成本控制**：ReAct 迴圈會導致上下文呈線性增長，必須在架構初期就規劃好上下文壓縮與摘要機制，避免 Token 成本失控，不應過度依賴 LLM 供應商的內建方案。
- **領域專用優於通用**：相較於打造一個無所不能的通用 Agent，針對特定任務設計、具備嚴格邊界與特定工具集的小型領域專用 Agent（Domain-Specific Agents），在生產環境中更具可靠性與安全性。
---
tags: [Agent架構, ReAct, AI]
date: 2026-05-19
source: "20260519_2026-05-19T092558+0800-What's actually inside an AI agent a 300~ LoC ReAct loop.md"
---
# 什麼是 AI Agent 的核心：一個約 300 行程式碼的 ReAct 迴圈 (What's actually inside an AI agent: a 300~ LoC ReAct loop)
原始來源與檔名：20260519_2026-05-19T092558+0800-What's actually inside an AI agent a 300~ LoC ReAct loop.md
**來源資訊**：
* **原始檔名**：2026-05-19T092558+0800-What's actually inside an AI agent a 300~ LoC ReAct loop.md
* **原始連結**：https://quantumentangled.dev/viewpost/11/whats-actually-inside-an-ai-agent-a-300-loc-react-loop
## 前言/背景
這篇文章探討了 AI Agent 的真實運作原理，作者透過親自建構一個簡單的 ReAct Agent，打破了 Agent 的神祕感，並指出了在生產環境中運行 Agent 時會面臨的實際風險與架構考量，尤其是工具執行（Actions）的危險性以及上下文視窗（Context Window）的成本管理。
## 章節詳細總結
### 透過簡化版 ReAct Agent 洞察本質
作者透過撰寫偽代碼與參考主流 Agent 論文，實作出一個簡易的本地端 ReAct Agent。作者指出：
* **脆弱性**：使用較小的本地模型取代前沿（Frontier）模型時，Agent 的容錯率極低。單一步驟的錯誤就會「毒害」（poison）整個推理鏈。
* **工具執行的雙面刃**：這是整篇文章最核心的警告。**Actions 可以是任何東西**。
* 在展示階段，工具執行看起來很酷。
* 在生產階段，如果將 `shell.exec` 連結給模型，就等於賦予了模型執行 `rm -rf` 的能力，可能導致嚴重的資安災難（如：將包含機密資訊的 git commit 推送，或將 `source.zip` 推送至 npm registry）。
### 上下文管理 (Context Management) 的架構挑戰
* 在 ReAct 迴圈中，**每一個步驟都會重新傳送整個對話歷史**。
* 這意味著上下文視窗會迅速膨脹，若不加以控制，開發者將在每一次迭代中支付高昂的 Token 成本。
* 儘管供應商提供了諸如 prompt 緩存（Prompt Caching）、上下文壓縮（`/compaction`）或摘要（Summaries）等變通方案，但供應商的核心利益實際上是依賴使用者消耗更多 Token。
### 軟體工程師應有的架構思維
作者建議，工程師應該嚴肅看待上下文管理，並為特定領域打造自訂的 Agent。在這些受控的 Agent 中，**Actions** 應該被嚴格限制為：
* 內部 API 呼叫 (Internal API calls)
* 警報生成 (Alerts generation)
* 資料庫查詢 (Database lookups)
* 網頁搜尋 (Web search)
* 內部流程執行 (Internal process executions)
一旦親自實作過 ReAct 迴圈，Agent 就不再是黑盒子。架構師應該問出正確的問題：
* 上下文裡包含了什麼？
* 工具的存取權限能觸及到哪裡？
* 當模型出錯時有什麼退路機制？
* Prompt 的相關性有多高？（非常高）
## 總結與結論
* **權限隔離 (Least Privilege)**：在架構 Agent 的工具層時，必須實行嚴格的最低權限原則。絕不可直接將危險的系統指令（如 `shell.exec`）暴露給 Agent，應使用沙盒或受限的 API 介面。
* **狀態管理與成本控制**：ReAct 迴圈會導致上下文呈線性增長，必須在架構初期就規劃好上下文壓縮與摘要機制，避免 Token 成本失控，不應過度依賴 LLM 供應商的內建方案。
* **領域專用優於通用**：相較於打造一個無所不能的通用 Agent，針對特定任務設計、具備嚴格邊界與特定工具集的小型領域專用 Agent（Domain-Specific Agents），在生產環境中更具可靠性與安全性。
Obsidian 整理
原始文章
Agent架構
你的 Agent 需要維基和錄音檔，而不是更大的辦公桌 (Your Agent Needs a Wiki and a Recording, Not a Bigger Desk)
"無限擴大上下文視窗 (Context Window) 只是給 Agent 一張更大的辦公桌；真正解決「失憶」問題，需要賦予它查閱公司手冊的能力 (GBrain)，以及隨時倒帶回放當前會議細節的機制 (Lossless)。"
Top 5 Insights
- **Context 不等於 Memory**：擴展 Context Window 只是提升了短期資料吞吐量，並未解決持久化與精確檢索的問題。
- **雙層記憶架構**：一個成熟的企業級 Agent 必須同時具備向外查詢全局知識 (GBrain) 與向內回溯對話細節 (Lossless) 的能力。
- **開發實踐**：應立即審視現有的 Agent Runtime 是否具備無損壓縮外掛，並開始建立基於 Markdown 的 Agent 可讀知識庫，而非僅依賴對話歷史。
---
tags: [Agent架構, 知識管理, 上下文管理, 系統記憶, 向量檢索]
date: 2026-05-19
read: false
source: "2026-05-19T092727+0800-Your Agent Needs a Wiki and a Recording, Not a Bigger Desk.md"
---
# 你的 Agent 需要維基和錄音檔，而不是更大的辦公桌 (Your Agent Needs a Wiki and a Recording, Not a Bigger Desk)
原始來源與檔名：2026-05-19T092727+0800-Your Agent Needs a Wiki and a Recording, Not a Bigger Desk.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 完整的 Agent 記憶系統 = GBrain (跨對話的維基檢索層) + Lossless (單次對話的無損錄音回放) + Context Window (當前處理的辦公桌)
### 一句話
> 無限擴大上下文視窗 (Context Window) 只是給 Agent 一張更大的辦公桌；真正解決「失憶」問題，需要賦予它查閱公司手冊的能力 (GBrain)，以及隨時倒帶回放當前會議細節的機制 (Lossless)。
### 餐巾紙草圖
```text
[傳統架構: 只有大辦公桌]
歷史紀錄塞滿 Context -> 達到極限被粗暴截斷 -> Agent 遺忘關鍵細節
[現代架構: 維基 + 錄音檔]
1. 行動前: 呼叫 GBrain 查詢 Markdown Wiki (獲得跨任務背景)
2. 對話中: 上下文被壓縮以節省 Token，但 Lossless 外掛保存了完整錄音
3. 忘記時: Agent 透過 Lossless 倒帶，精準找回 40 分鐘前的一句話
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼即便模型支援超大上下文 (Context Window)，Agent 依然會忘記重要的客戶規範或 30 分鐘前討論的細節？
- **核心答案**: 因為大上下文不等於結構化的記憶系統。Agent 需要兩種截然不同的記憶層：跨對話的全局知識庫 (GBrain) 與防截斷的會話無損記錄 (Lossless)。
- **論證結構**: 術語定義與隱喻 -> GBrain 的作用場景 -> Lossless 的作用場景 -> 如何整合進 Agent Runtime -> 五層診斷框架。
### 章節骨架
1. **隱喻破題**: 上下文是辦公桌，GBrain 是公司 Wiki 手冊，Lossless 是會議無損錄音檔。單純擴大辦公桌無法解決查詢與回放的需求。
2. **誤區澄清**: 狂塞 30 天對話記錄不等於擁有知識庫；向量資料庫只是儲存底層，不是記憶模式本身。
3. **場景分析**:
- *GBrain*: 用於「跨對話/跨角色」，例如新 Agent 接手舊專案，需了解公司既有決策。
- *Lossless*: 用於「單次長對話」，防止視窗達到極限時，歷史細節被粗暴總結而永久遺失。
4. **架構整合**: Lossless 以外掛形式嵌入 Runtime (如 OpenClaw/Hermes) 的壓縮引擎；GBrain 則作為獨立的外部系統，供 Agent 透過 MCP/CLI 調用。
5. **記憶除錯框架**: Capture -> Lossless -> GBrain -> Ranking -> Task，自底向上排查遺忘原因。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 開發者必須接受一個事實：無論模型上下文多大，為了成本與延遲，Runtime 終究必須進行壓縮 (Context Compaction)。因此，如何優雅地壓縮並保留「找回原貌」的能力，是系統設計的關鍵。
- **邊界條件**: 如果 Agent 任務都非常短 (幾個回合內結束)，Lossless 就沒有意義；如果 Agent 只服務單一短期專案，GBrain 的價值也不大。兩者的價值在於「長時程」與「多專案切換」。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 對應於人類記憶機制的「語義記憶 (Semantic Memory, 如 Wiki)」與「情節記憶 (Episodic Memory, 如錄音回放)」。
- **深層洞見**: 將歷史紀錄丟進向量庫不等於建構大腦，因為向量庫缺乏決策節點間的關聯。GBrain 強調的是基於 Markdown 的結構化索引，讓「事實」跨越對話邊界。
- **行動呼籲**: 不要迷信無限長的 Context 視窗。立刻在你的 Agent 框架中實裝 Lossless 壓縮外掛，並要求團隊將核心決策寫成 Repo 中的 Markdown 讓 Agent 檢索。
---
# 你的 Agent 需要維基和錄音檔 (Architectural Deep Dive)
## 前言/背景
所有 Agent 開發者最終都會撞上「記憶牆」：不論給予多大的 Context Window，Agent 最終還是會忘記過去的決策或剛討論過的細節。本文透過生動的隱喻 (辦公桌、維基、錄音檔) 指出，解決此問題的關鍵並非無腦增加 Token 上限，而是引入兩個關鍵的架構模式：處理跨會話全局知識的 `GBrain`，以及處理單次長會話防遺失的 `Lossless`。
## 章節詳細總結
### 核心隱喻與誤區澄清 (What they are)
* **Context Window (上下文視窗)** = 辦公桌的面積。桌子再大也無法儲存所有公司歷史。
* **GBrain (全局維基)** = 新員工入職手冊。建立在 Markdown Repo 之上的檢索層，讓 Agent 在行動前能查詢「跨越會話的恆定事實」(如客戶偏好、架構政策)。
* **Lossless (無損錄音)** = 會議錄音檔。當對話過長，Runtime 被迫壓縮歷史為「摘要」以節省空間時，Lossless 會保留原始訊息。當 Agent 對摘要有疑慮時，可調閱原始訊息。
* **常見迷思**：將 30 天對話全塞進模型，或是把所有東西丟進向量庫，並不等於記憶系統。向量庫只是儲存介質，缺乏對特定實體 (人、專案、決策) 的結構化梳理。
### 兩大模組的應用場景 (Why you'd use them)
* **GBrain (跨對話)**：適用於 Agent 接手舊客戶、從中斷的專案重啟，或是團隊中多個 Agent 之間的知識交接。它的核心價值在於消除「每次都要重新教導公司規矩」的昂貴成本。
* **Lossless (單次對話)**：適用於 50 輪以上的深度長對話。當使用者突然回溯「30 分鐘前我們討論過的那個 Schema」時，Lossless 確保該細節不會因為底層的上下文自動壓縮機制而永遠消失。
### 系統整合架構 (How to wire them into your agent)
這兩個工具在架構中位於完全不同的位置：
* **Lossless 插在 Runtime 內部**：它是一個 Context Engine 外掛。例如在 OpenClaw 中配置 `lossless-claw`，它會攔截常規的「粗暴截斷 (Hard Truncation)」，替換為「結構化摘要 + 可回溯的原始文本」。
* **GBrain 處於 Runtime 外部**：它是一個獨立的知識檢索服務 (Brain Repo + DB)。Agent 透過 MCP (Model Context Protocol) 或 CLI 工具，在執行動作前主動向 GBrain 請求外部知識。
### 五層記憶診斷框架 (5-row diagnostic)
當 Agent 發生「遺忘」時，不應盲目擴大 Context，應按順序排查這五層：
1. **Capture (擷取)**：這件事當初有被記錄下來嗎？
2. **Lossless (無損)**：在單次對話中，該細節是否被壓縮機制吃掉了？
3. **GBrain (維基)**：跨對話時，這個事實是否能透過專案或人名檢索出來？
4. **Ranking (排序)**：檢索系統是否有將最相關的事實排在頂部提供給 Agent？
5. **Task (任務提示)**：當前的 Prompt 有沒有清楚告訴 Agent，為什麼這個事實對現在的任務很重要？
## 總結與結論
* **Context 不等於 Memory**：擴展 Context Window 只是提升了短期資料吞吐量，並未解決持久化與精確檢索的問題。
* **雙層記憶架構**：一個成熟的企業級 Agent 必須同時具備向外查詢全局知識 (GBrain) 與向內回溯對話細節 (Lossless) 的能力。
* **開發實踐**：應立即審視現有的 Agent Runtime 是否具備無損壓縮外掛，並開始建立基於 Markdown 的 Agent 可讀知識庫，而非僅依賴對話歷史。
Obsidian 整理
原始文章
Agent架構
在 Prompt 裡寫了 10 遍 Mandatory 還是翻車 (Deterministic Control Flows over Prompts)
"不要試圖用 Prompt (自然語言) 來取代程式碼的 與 迴圈；將流程控制權收回給程式碼，讓 LLM 退化為純粹的推理組件，是解決 Agent 任務不穩定的唯一解法。"
Top 5 Insights
- **思維典範轉移**：不要對著黑盒模型祈禱 (Vibe Accept)，而是建立嚴謹的檢驗機制。
- **架構壞味道**：當你在 Prompt 裡寫下 `MANDATORY` 或感嘆號時，就代表你的架構設計出錯了。
- **結論**：模型只是引擎，只有配上變速箱、方向盤與煞車 (確定性控制流)，這台車才能安全上路。
---
tags: [Agent架構, Prompt工程, 工作流, 系統工程, 確定性控制]
date: 2026-05-19
read: false
source: "2026-05-19T092744+0800-在 prompt 里写了 10 遍 mandatory 还是翻车，直到我改了一行代码！.md"
---
# 在 Prompt 裡寫了 10 遍 Mandatory 還是翻車 (Deterministic Control Flows over Prompts)
原始來源與檔名：2026-05-19T092744+0800-在 prompt 里写了 10 遍 mandatory 还是翻车，直到我改了一行代码！.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 可靠的 Agent 系統 = 代碼 (負責流程控制與狀態) + LLM (僅負責自然語言理解與單點決策) + 嚴格校驗 (Schema Validation)
### 一句話
> 不要試圖用 Prompt (自然語言) 來取代程式碼的 `if/else` 與 `while` 迴圈；將流程控制權收回給程式碼，讓 LLM 退化為純粹的推理組件，是解決 Agent 任務不穩定的唯一解法。
### 餐巾紙草圖
```text
[純 Prompt 方案: 祈禱模式]
Prompt: "請嚴格依序跑 200 個檔案, Mandatory!" -> LLM (大腦兼控制台) -> 第 30 個檔案開始跳步驟、幻覺 (失敗)
[確定性控制流: 系統工程]
for file in 200_files:
result = LLM(file) -> LLM 僅作單一判斷
if validate(result): -> Code 負責校驗與重試
save(result)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼在 Prompt 裡加上各種強烈字眼 (大寫、加粗、Mandatory)，LLM 處理多步任務時依然會跳步驟或出錯？
- **核心答案**: 因為自然語言本質上是「建議」而非「命令」。LLM 沒有程式計數器與呼叫疊代 (Call Stack)，無法處理複雜的狀態編排。必須透過「確定性控制流 (Deterministic Control Flow)」將流程交由程式碼控制。
- **論證結構**: 失敗案例引入 -> 剖析 Prompt 的天花板 -> 確定性控制流的定義與範例 -> Stripe 的實踐 -> 行動指南。
### 章節骨架
1. **翻車現場**: 要求 Agent 處理 200 個測試文件，前 30 個正常，後續開始跳步驟、混合結果。修改 Prompt 無效。
2. **Prompt 的本質缺陷**: 語言只是建議。LLM 沒有狀態機，步驟越多，不確定性累積越快。
3. **解決方案 (控制流)**: LLM 降級為組件 (只負責思考)，Python 程式碼升級為指揮官 (負責迴圈、條件、重試)。
4. **工業界實踐**: Stripe 的 Minions 系統在 LLM 節點間插入確定性的校驗節點。Claude Code 的強大也來自其背後的工具鏈與狀態管理，而非單純的模型智商。
5. **落地建議**: 先畫流程圖，拆分調用，強制 Schema 校驗，並使用 LangGraph 等編排框架。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 模型智力 (即使是 GPT-5.5) 在短期內無法內化並無失誤地追蹤幾百個迴圈的內部狀態。可靠性必須來自外部系統設計，而非模型本身。
- **邊界條件**: 如果任務是開放式的創意寫作，純 Prompt 依然有效；但只要涉及精確數量、嚴格順序、結構化輸出，就必須引入外部程式碼校驗。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 軟體工程的「單一職責原則 (Single Responsibility Principle)」。
- **深層洞見**: Agent 開發正在從「Prompt 工程 (玄學)」轉變為「系統工程 (科學)」。下次當你發現自己在 Prompt 裡打下 `MANDATORY` 或 `DO NOT SKIP` 時，這就是一個架構壞味道 (Architecture Smell)，提醒你該寫 Python 程式碼了。
- **行動呼籲**: 放棄要求模型「一次做完所有事」。將大型 Prompt 拆解為 `for` 迴圈中的微型調用，並在每一層加上 JSON Schema 驗證。
---
# 在 Prompt 裡寫了 10 遍 Mandatory 還是翻車 (Architectural Deep Dive)
## 前言/背景
開發者在建構 QA Agent 以批量處理 200 個測試文件時，發現模型在中途開始跳步驟、產出混亂。作者指出，無數次修改 Prompt (使用大寫、警告字眼) 均無濟於事。直到作者放棄讓 LLM 控制流程，改用 Python `for` 迴圈搭配單步 LLM 呼叫與代碼校驗，才實現了零漏檢。這揭示了 Agent 開發的核心轉變：從 Prompt 玄學走向系統工程。
## 章節詳細總結
### Prompt 的天花板：語言是建議，不是命令 (prompt 的天花板在哪)
自然語言的本質缺陷在於缺乏嚴格的執行結構。LLM 沒有「程式計數器 (Program Counter)」、沒有「呼叫疊代 (Call Stack)」、也沒有異常處理機制。要求 LLM 記住並執行 200 步的嚴格順序，是不可能完成的任務。不確定性會隨著步驟增加而指數累積，最終必然崩潰。
### 確定性控制流的設計模式 (确定性控制流长什么样)
核心架構思想：**把 LLM 當作功能組件，把程式碼當作系統大腦。**
* **流程由代碼控制**：`if/else`, `while`, `for` 必須用 Python/TS 寫死。
* **職責剝離**：LLM 僅負責其擅長的事物（讀取文本、判斷邏輯、產出 JSON），而「下一步該做什麼」的決策權由程式碼收回。
* **強制校驗與重試**：呼叫 LLM 後，必須接入 `validate_schema()`，若格式錯誤則觸發代碼層級的 Retry，絕不允許靜默錯誤蔓延。
### 工業界的驗證：Stripe 與 Claude (Stripe 怎么做的)
Stripe 的企業級 Agent (Minions) 正是基於此架構：在 LLM 節點之間插入純粹的程式碼節點進行質量與格式檢查。Claude Code 能夠順暢運行的秘密，不在於 Claude 模型的智商碾壓，而在於其背後包裹了一層堅固的、確定性的「工具呼叫與上下文管理機制 (Harness)」。
### 實踐指南：系統工程師的視角 (怎么开始)
* **架構先行**：在寫 Prompt 之前先畫流程圖。只要圖上出現條件分支 (Branching) 或迴圈 (Loop)，這段邏輯就應該寫在程式碼裡，而不是 Prompt 裡。
* **微服務化 LLM**：每次調用 LLM 只做一件事，確保輸入輸出有嚴格契約 (Contract)。
* **採用編排框架**：停止裸寫 API 調用，採用 LangGraph, BAML 等專為狀態機編排設計的工具，讓工作流具備「遞迴可組合性」。
## 總結與結論
* **思維典範轉移**：不要對著黑盒模型祈禱 (Vibe Accept)，而是建立嚴謹的檢驗機制。
* **架構壞味道**：當你在 Prompt 裡寫下 `MANDATORY` 或感嘆號時，就代表你的架構設計出錯了。
* **結論**：模型只是引擎，只有配上變速箱、方向盤與煞車 (確定性控制流)，這台車才能安全上路。
Obsidian 整理
原始文章
Agent架構
多智能體協作調查：Agent 到底該怎麼分工 (How Should Agents Divide Labor?)
"多智能體不是「多開幾個模型實例」的魔法，而是嚴肅的分散式系統工程；在沒有釐清上下文隔離、寫入權限與衝突合併機制前，盲目並行只會帶來混亂。"
Top 5 Insights
- **先定義邊界，再增加數量**：在沒有明確「委派合約 (Delegation Contract)」的情況下，多 Agent 只是一群盲目消耗 Token 的混亂產生器。
- **尊重生命週期差異**：必須嚴格區分「需在本輪返回的短程 RPC 任務」與「可非同步跨天執行的長程看板任務」。
- **架構決策樹**：遇到問題先問「單 Agent 能不能做？」，再問「主上下文是否會被污染？」，最後才決定是否展開子 Agent，並明確指定唯一的收口者 (Reducer)。
---
tags: [Agent架構, AI工程, 系統設計, 拓撲結構, 多智能體]
date: 2026-05-19
read: false
source: "2026-05-19T092714+0800-多智能体协作调查：Agent 到底该怎么分工.md"
---
# 多智能體協作調查：Agent 到底該怎麼分工 (How Should Agents Divide Labor?)
原始來源與檔名：2026-05-19T092714+0800-多智能体协作调查：Agent 到底该怎么分工.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 多智能體成功率 = 清晰的委派合約 (Context + Ownership) + 嚴格的狀態管理 (短程 RPC vs. 長程 Queue) + 負責任的收口機制 (Reducer)
### 一句話
> 多智能體不是「多開幾個模型實例」的魔法，而是嚴肅的分散式系統工程；在沒有釐清上下文隔離、寫入權限與衝突合併機制前，盲目並行只會帶來混亂。
### 餐巾紙草圖
```text
[錯誤的協作] 模糊任務 -> 隨機 Spawn -> 權限越界 / 寫入衝突 -> 無法合併的災難
[正確的協作] 任務解構 -> 路由/分發 (星型/網狀/看板) -> 嚴格隔離的 Worker 執行 -> 主 Agent 或人類審查收口 (Merge)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼市面上的多智能體 Demo 看起來很強，但實際應用卻經常崩潰？真正的 Agent 系統應該如何設計分工拓撲？
- **核心答案**: 因為真實工程面臨著狀態隔離、權限控制、衝突合併等難題。必須依照任務特性選擇單 Agent、星型 (Fan-out)、鏈式、網狀 (Team Mesh) 或看板 (Kanban) 模式，並制定嚴謹的委派合約。
- **論證結構**: 拆解觸發與拓撲 -> 分析底層調用鏈 -> 對比四大框架 (Codex, Claude, OpenClaw, Hermes) -> 總結反模式與設計決策樹。
### 章節骨架
1. **觸發與拓撲**: 觸發分為顯式、語義、路由與隊列；拓撲分為星型 (主從)、鏈式 (流水線)、網狀 (團隊) 與看板 (長期)。
2. **調用鏈剖析**: Input -> Router -> Context Builder -> Sandbox -> State Store -> Merge/Reduce -> Output。其中 Context Builder 與 Merge 是最常失敗的環節。
3. **框架對比**:
- *Codex*: 克制的顯式授權，星型並行。
- *Claude Code*: 基於 Description 的動態路由與 Team 模式。
- *OpenClaw*: 以入口 (Channel/Account) 為核心的網關路由與隔離。
- *Hermes*: 區分短任務 (RPC/delegate) 與長任務 (Kanban/durable queue)。
4. **反模式與實踐**: 把複雜度當並行理由、不給委派合約、無 Ownership 的並行寫入是三大死穴。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 開發者必須具備「系統架構師」的思維，不能把多 Agent 視為一個萬能的黑盒大腦，而應視為一組需要嚴格編排的微服務。
- **邊界條件**: 單 Agent 永遠是預設首選。只有在「主上下文會被污染」或「需要驗證多重假設」時，才應該考慮跨出單一 Session 進行 Fan-out 或切換至 Team 模式。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 高度呼應分散式系統的 MapReduce 架構、權限最小化原則 (Principle of Least Privilege)，以及微服務中的 Saga 狀態機設計。
- **深層洞見**: 短任務與長任務的生命週期完全不同。短任務是 RPC (等待回傳)，長任務是持久化隊列 (可中斷、交接、重試)。將這兩者混用是目前大多數 Agent 框架最致命的設計失誤。
- **行動呼籲**: 在建立子 Agent 前，先寫好包含 Role, Goal, Context, Allowed Actions, Ownership, Forbidden Actions 的「委派合約 (Delegation Contract)」。
---
# 多智能體協作調查：Agent 到底該怎麼分工 (Architectural Deep Dive)
## 前言/背景
社交媒體上常將「多智能體 (Multi-Agent)」吹捧為無所不能的虛擬團隊，但本文作者 (具備深厚工程背景的開發者) 點出，多智能體本質上是高度複雜的「分散式系統工程」。文章透過深入分析 Codex, Claude Code, OpenClaw 與 Hermes 四大 Agent Runtime 的設計哲學，探討任務調度、上下文隔離與狀態管理的真實工程挑戰。
## 章節詳細總結
### 觸發機制與拓撲結構 (触发与拓扑)
多智能體的首要問題不是「如何工作」，而是「何時啟動」與「如何組織」。
* **四大觸發機制**：顯式觸發 (使用者命令)、語義觸發 (描述匹配)、路由觸發 (依賴對話來源入口) 與隊列觸發 (背景 Cron 任務)。
* **五大拓撲架構**：
1. *單 Agent*：最穩定的預設形態。
2. *星型 (Fan-out/in)*：主 Agent 派發並負責 Reduce 合併，避免 Worker 互相干擾。
3. *鏈式 (Pipeline)*：適合強順序依賴任務。
4. *網狀 (Team Mesh)*：適合多假設驗證 (如排查生產級 Bug)，但協調成本極高。
5. *看板 (Durable Board)*：跨越生命週期的狀態機協作。
### 分散式 Agent 的調用鏈 (调用链)
一個健壯的多智能體系統必須處理完整的生命週期：
`Router -> Context Builder -> Worker Profile -> Sandbox -> State Store -> Merge/Reduce`
* **Context Builder** 的缺失是最大的災難：子 Agent 不會自動繼承父節點的記憶。
* **Merge/Reduce** 是成敗關鍵：多個 Worker 提出相互衝突的 Patch 時，誰來承擔合併與覆蓋的最終責任？
### 四大主流框架的架構取捨
1. **Codex (顯式 Fan-out)**：極度克制。預設不展開，要求使用者明確授權並行。採用星型拓撲，主 Agent 承擔 Dispatcher 與 Reducer 雙重角色。
2. **Claude Code (Description + Team)**：依賴精確的 `description` 進行自動路由。支援 Team Mesh 讓 Agent 互相溝通，但若缺乏 Ownership 容易導致無限迴圈與寫入衝突。
3. **OpenClaw (Gateway + 後台任務)**：專注於「多入口」的網關路由。解決的是 Slack, Telegram 等不同入口的權限、上下文與會話隔離問題，而非單次 Coding 的並行。
4. **Hermes (RPC 短任務 vs. Kanban 長任務)**：展現了最頂級的工程思維。將幾分鐘的並行任務定義為 `delegate_task` (RPC 機制，無狀態)；將跨天、需要人工介入的任務定義為 `Kanban` (持久化 SQLite，可重試與交接)。
### 反模式與防禦性設計 (反模式)
* **無 Ownership 的並行寫入**：多個 Agent 試圖修改同一個檔案必定引發悲劇，必須按目錄或模組嚴格劃分寫入權限。
* **把複雜度當作並行藉口**：複雜但具備強順序依賴的任務 (如：理解規則 -> 設計模型 -> 寫遷移腳本) 必須使用 Pipeline，並行只會讓 Worker 在錯誤假設上浪費算力。
## 總結與結論
* **先定義邊界，再增加數量**：在沒有明確「委派合約 (Delegation Contract)」的情況下，多 Agent 只是一群盲目消耗 Token 的混亂產生器。
* **尊重生命週期差異**：必須嚴格區分「需在本輪返回的短程 RPC 任務」與「可非同步跨天執行的長程看板任務」。
* **架構決策樹**：遇到問題先問「單 Agent 能不能做？」，再問「主上下文是否會被污染？」，最後才決定是否展開子 Agent，並明確指定唯一的收口者 (Reducer)。
Obsidian 整理
原始文章
Agent架構
從 Agent 到 Graph：Google ADK 2.0 到底改了什麼？ (Google ADK 2.0: From Agent to Graph)
"ADK 2.0 的核心哲學是將「流程控制權」從黑盒的 LLM Prompt 奪回，交給開發者用程式碼 (Graph) 進行硬定義，這讓平行處理、條件迴圈與人類介入變得決定性且可測試。"
Top 5 Insights
- **告別 Prompt 玄學**：ADK 2.0 宣告了單純依賴 Prompt 進行系統控制的時代結束，Agent 開發正式回歸「踏實的軟體工程」。
- **確定性至上**：在企業級應用中，可預期性 (Predictability) 與可測試性 (Testability) 永遠高於模型的「靈光一閃」。
- **業界共識**：從 LangGraph 到 ADK 2.0，將 Agent 編排圖表化 (Graph-based orchestration) 已成為解決大模型不可靠問題的最終共識。
---
tags: [Agent架構, Google ADK, 系統設計, 工作流, 確定性控制]
date: 2026-05-19
read: false
source: "2026-05-19T093011+0800- AI Agent Google ADK 2.0 Beta Version 研究— 從 Agent 到 Graph：Google ADK 2.0 到底改了什麼？.md"
---
# 從 Agent 到 Graph：Google ADK 2.0 到底改了什麼？ (Google ADK 2.0: From Agent to Graph)
原始來源與檔名：2026-05-19T093011+0800- AI Agent Google ADK 2.0 Beta Version 研究— 從 Agent 到 Graph：Google ADK 2.0 到底改了什麼？.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> ADK 2.0 = 純 Python Function (節點) + 明確定義的 Edges (流程與條件路由) + LLM Agent (僅負責節點內的智力運算)
### 一句話
> ADK 2.0 的核心哲學是將「流程控制權」從黑盒的 LLM Prompt 奪回，交給開發者用程式碼 (Graph) 進行硬定義，這讓平行處理、條件迴圈與人類介入變得決定性且可測試。
### 餐巾紙草圖
```text
[ADK 1.x: 以 Agent 為中心]
Prompt: "你是一個團隊長，請分配任務給 A 和 B，不滿意就重寫"
-> 控制流隱式、依賴 LLM 自由意志 -> 容易失控、無法預期。
[ADK 2.0: 以 Graph 為中心]
Edges = [
(Start -> 平行觸發 A, B),
(A, B -> JoinNode 合流 -> 編輯 Agent),
(編輯審核 -> 若 revise 迴圈回 A / 若 pass 則結束)
] -> 控制流寫死在 Code 裡 -> 嚴謹、可測試的企業級管線。
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: Google ADK 1.x 雖然能輕易做出炫酷的 Demo，但在導入企業級 Production 場景時，為何常常面臨流程失控與除錯困難？
- **核心答案**: 1.x 版本將「任務調度與流程控制」交給語言模型的自由意志 (透過 Prompt) 決定。ADK 2.0 進行了架構大轉彎，引入 Workflow (Graph) 概念，將平行、路由、迴圈全部轉化為程式碼中明確定義的邊 (Edges)。
- **論證結構**: 提出痛點場景 (SOP 簡報生成) -> 比較 1.x 與 2.0 的設計哲學 -> 代碼範例展示 (圖宣告的力量) -> 分析升級時機與風險。
### 章節骨架
1. **標準 SOP 場景**: 找切角與找事實 (並行) -> 寫草稿 (合流) -> 編輯評審 (條件迴圈)。
2. **1.x 的痛點**: 依賴 `SequentialAgent` 與提示詞哄騙 LLM 執行 `transfer`，流程極不穩定。
3. **2.0 的設計哲學**: 流程不再是 Prompt，而是一張圖 (Graph)。LLM 負責節點智力，圖負責流程紀律。
4. **程式碼對比**: 展示 ADK 2.0 中純 function 作為節點、`JoinNode` 處理 Fan-in、以及依賴結構化輸出 (`Verdict`) 進行明確路由的優雅寫法。
5. **升級建議**: Production 或需要相容舊資料庫，請留在 1.x；若是開發新原型且需要強控制流，強烈建議嘗試 2.0。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 生成式 AI 的不可預測性是企業級應用的最大阻礙。在企業流程中，「防呆與紀律 (Graph)」的重要性遠高於「模型的自主規劃能力 (Autonomous Agent)」。
- **邊界條件**: ADK 2.0 目前仍處於 Beta 階段。由於架構底層發生劇變，2.0 的 session 資料完全無法與 1.x 相容，開發者必須在隔離環境中進行測試。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 呼應 LangChain 演進至 LangGraph 的軌跡；也與傳統軟體工程中的狀態機 (State Machine) 與有向無環圖 (DAG) 高度一致。
- **深層洞見**: 這是一場 Agent 架構的「返璞歸真」。業界終於承認，將系統流程控制權全盤交給 LLM 是不切實際的。**LLM 應該是齒輪，而不是引擎。**
- **行動呼籲**: 放棄用又臭又長的 Prompt 來控制 Agent 迴圈。開始學習以 Graph 為中心的框架 (如 ADK 2.0, LangGraph)，將流程邏輯寫死在 Code 裡，擁抱確定性工程。
---
# 從 Agent 到 Graph：Google ADK 2.0 到底改了什麼？ (Architectural Deep Dive)
## 前言/背景
隨著企業對 Agent 穩定性的要求日益提高，依賴 LLM 自主調度的框架暴露出極大的不可控性。Google ADK (Agent Development Kit) 在 2.0 版本中迎來了底層哲學的劇變：從「以 Agent 為中心的自主協調」轉向「以 Graph 為中心的確定性編排」。本文透過具體的情境與代碼對比，解析這場轉變的本質與工程價值。
## 章節詳細總結
### 痛點場景與 1.x 的極限 (一个标准 SOP 的场景)
在製作「簡報產生器」的情境中，流程包含並行研究 (找切角、找事實)、合流撰寫草稿，以及基於審核結果的退回重寫迴圈。
在 ADK 1.x 中，這類複雜的 SOP 依賴協調者 LLM 讀取指令並自主決定 `transfer`。這導致開發者必須與 LLM 的「自由意志」搏鬥——有時它不願意退回重寫，有時它會擅自略過步驟。流程的對錯完全取決於 Prompt Engineering 的玄學。
### 哲學轉向：將紀律交還給程式碼 (设计哲学)
ADK 2.0 的核心轉變：**「LLM 只負責節點裡的智慧，圖負責流程的紀律。」**
* **1.x (控制流隱式)**：一群專家開會，由大模型主導發言權。
* **2.0 (控制流顯式)**：由開發者畫出流程圖 (`edges`)，清楚定義哪裡並行 (Fan-out)、哪裡合流 (Fan-in)、哪裡條件分支，以及哪裡需要人類介入 (HITL)。
### 代碼範例的震撼 (同一条 pipeline，写两次给你看)
ADK 2.0 的程式碼展現了極致的結構化與決定性：
1. **純 Function 是一等公民**：節點不再非得是笨重的 Agent，普通的 Python function 只要 `yield Event` 就能串入圖中。
2. **優雅的 Fan-out/Fan-in**：`edges` 中可以直接宣告 `(research_a, gather_f)` 進行平行觸發，並透過 `JoinNode` 等待兩者完成。
3. **決定性路由 (Deterministic Routing)**：依賴 Pydantic 定義的結構化輸出 (Verdict)，程式碼能根據 `grade == "revise"` 明確指定路線退回，徹底消除 LLM 走錯路的風險。
### 升級策略與建議 (那我到底该不该在此时间升 ADK 2.0)
* **架構代價**：2.0 的執行模型發生根本變化，Session 資料與 1.x 完全不相容。
* **決策建議**：若是現有 Production 系統或涉及舊有 Session，請務必留在 1.x；若在開發新專案，且高度依賴明確的 SOP、平行處理與審核迴圈，請立刻在獨立環境中擁抱 ADK 2.0。
## 總結與結論
* **告別 Prompt 玄學**：ADK 2.0 宣告了單純依賴 Prompt 進行系統控制的時代結束，Agent 開發正式回歸「踏實的軟體工程」。
* **確定性至上**：在企業級應用中，可預期性 (Predictability) 與可測試性 (Testability) 永遠高於模型的「靈光一閃」。
* **業界共識**：從 LangGraph 到 ADK 2.0，將 Agent 編排圖表化 (Graph-based orchestration) 已成為解決大模型不可靠問題的最終共識。
Obsidian 整理
原始文章
Kubernetes與GitOps
Top 10 Kubernetes Operators for Automating Production Workloads
""
---
title: "Top 10 Kubernetes Operators for Automating Production Workloads"
source: "https://medium.com/devops-ai-decoded/top-10-kubernetes-operators-for-automating-production-workloads-7159311c66d6"
author:
- "[[Neel Shah]]"
published: 2026-05-10
created: 2026-05-19
description: "A comprehensive guide to the top 10 most impactful Kubernetes Operators in 2026 for automating stateful services, infrastructure, and observability."
tags:
- "clippings"
- "Kubernetes與GitOps"
- "基礎設施"
read: false
---
# Top 10 Kubernetes Operators for Automating Production Workloads
## 🎯 NAPKIN (核心洞見公式與餐巾紙草圖)
**核心概念**：
Kubernetes Operators = Controller Loop + Domain-Specific Knowledge (CRDs) -> L5 Auto-Pilot Infrastructure
**餐巾紙草圖 (自動化架構)**：
```mermaid
graph TD
A[Git Repository] -->|ArgoCD Operator| B(Kubernetes Cluster)
B -->|Crossplane| C[Cloud Infrastructure RDS/S3]
B -->|CloudNativePG| D[In-cluster PostgreSQL]
B -->|Strimzi| E[Apache Kafka]
B -->|Cert-manager| F[TLS Certificates]
B -->|KEDA| G[Event-driven Autoscaling]
B -->|Prometheus / OTel| H[Observability]
```
---
## 🦴 ROUND 1: 骨架掃描 (XRay Scanner)
### 1. 文章要解決的核心問題是什麼？
在生產環境中運行 Kubernetes 最困難的不是部署無狀態應用，而是管理狀態 (State)、資料庫升級、自動擴縮容、憑證輪替等複雜的維運工作。原生 K8s API 無法解決所有問題。
### 2. 作者提出了什麼解決方案或論點？
使用 Kubernetes Operators (將人類專家的維運知識編碼為軟體控制器)，將基礎設施、資料庫、可觀測性等堆疊完全自動化，實現 Level 5 (Auto Pilot) 的維運成熟度。
### 3. 這個解決方案的關鍵要素有哪些？
文章列舉了 2026 年最具影響力的 10 個 Operators：
1. **Argo CD Operator** (GitOps 引擎)
2. **cert-manager** (自動化 TLS)
3. **Prometheus Operator** (監控堆疊)
4. **Strimzi** (Kafka 管理)
5. **CloudNativePG** (生產級 PostgreSQL)
6. **KEDA** (事件驅動擴縮容)
7. **Crossplane** (基礎設施即 K8s 資源)
8. **Argo Rollouts** (漸進式交付/金絲雀)
9. **OpenTelemetry Operator** (可觀測性遙測)
10. **VictoriaMetrics Operator** (大規模時間序列數據庫)
---
## 🥩 ROUND 2: 血肉解剖 (XRay Dissector)
### 第一層：GitOps 與安全傳輸
* **Argo CD Operator**：實現「自我管理」的 GitOps 引擎，Argo CD 的設定本身也由 GitOps 驅動。
* **cert-manager**：基礎架構的信任根 (Root of Trust)，自動處理憑證過期與輪替，與 Gateway API 整合，實現 mTLS。
### 第二層：狀態服務 (Stateful Services)
* **Strimzi**：支援 KRaft 模式 (無 ZooKeeper)，宣告式管理 Kafka 集群拓撲與主題。
* **CloudNativePG**：提供串流複寫、自動故障轉移 (Failover)、時間點還原 (PITR)，將傳統 RDS 的功能直接帶入 K8s 中。
### 第三層：自動化擴展與漸進交付
* **KEDA**：打破僅基於 CPU/Memory 的 HPA 限制，讓 Pod 可以根據 Kafka 延遲、SQS 深度或 Cron 自動擴展 (甚至 Scale to zero)。
* **Argo Rollouts**：整合流量分割 (Traffic splitting) 與自動化金絲雀分析 (Analysis Templates)，若錯誤率上升則自動 rollback。
---
## 🧠 ROUND 3: 靈魂提取 (XRay Extractor)
### 本質 (Essence)
「基礎設施即代碼 (IaC) 的終極型態不是寫腳本，而是持續對帳 (Continuous Reconciliation) 的控制迴圈。」
### 遷移 (Transfer)
* **內部開發者平台 (IDP)**：平台工程團隊不應該直接給開發者 K8s YAML，而是提供由 Operator 支援的 CRD (如 `DatabaseCluster`)，隱藏維運複雜度並強制執行合規性。
* **跨雲與混合雲管理**：利用 Crossplane，可以使用相同的 K8s API 與 GitOps 工作流來管理 AWS RDS、GCP Cloud SQL，實現真正的多雲管理。
---
## 🏗️ Architectural Deep Dive (架構師深研)
**Operator 組成平台工程的核心分層架構 (Layered Platform Architecture)**
1. **交付與部署層 (Layer 1)**：
由 `Argo CD` 驅動，所有應用 (包括其他 Operators) 都經由 GitOps 進入集群。`Argo Rollouts` 確保發布的安全性 (Metrics-based Canary)。
2. **基礎設施與狀態層 (Layer 2)**：
`Crossplane` 管理外部雲端資源；`CloudNativePG` 與 `Strimzi` 管理集群內的狀態化系統。這徹底解決了「K8s 不適合跑 DB」的過時觀念。
3. **安全與合規層 (Layer 3)**：
`cert-manager` 作為底層，處理從 Ingress 到 Pod 之間的所有 TLS 憑證，確保零信任架構 (Zero Trust) 落地。
4. **效率與擴展層 (Layer 4)**：
`KEDA` 彌補了原生 HPA 的不足，特別適用於事件驅動架構 (Event-Driven Architecture, EDA)，實現基於業務指標的動態擴縮容。
5. **可觀測性層 (Layer 5)**：
`OpenTelemetry` 負責無侵入式的分散式追蹤注入，`Prometheus/VictoriaMetrics` 負責海量指標的收集與告警，並提供 `ServiceMonitor` 供各團隊自助接入。
Obsidian 整理
原始文章
工作方法
停止寫規格，開始寫事實：SDD 運動的消亡 (Stop Writing Specs. Start Writing Facts)
"不要依賴又臭又長的自然語言規格書 (Spec) 來驅動 AI 寫程式，因為模型對文字的解讀會隨機漂移；你該寫的是一組絕對不會被模型誤解的「可執行測試 (Facts)」，用機器的 Exit 0 來驗證 AI 的產出。"
---
tags: [系統工程, 工作方法, TDD, AI開發, 軟體架構]
date: 2026-05-19
read: false
source: "2026-05-19T093024+0800-Stop Writing Specs. Start Writing Facts. The Entire SDD Movement Is Already Obsolete..md"
---
# 停止寫規格，開始寫事實：SDD 運動的消亡 (Stop Writing Specs. Start Writing Facts)
原始來源與檔名：2026-05-19T093024+0800-Stop Writing Specs. Start Writing Facts. The Entire SDD Movement Is Already Obsolete..md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> Specs (自然語言) + LLM (隨機採樣) = 不確定的程式碼漂移 (Drift)
> Facts (可執行斷言) + LLM = 確定性的驗證結果 (Exit 0)
### 一句話
> 不要依賴又臭又長的自然語言規格書 (Spec) 來驅動 AI 寫程式，因為模型對文字的解讀會隨機漂移；你該寫的是一組絕對不會被模型誤解的「可執行測試 (Facts)」，用機器的 Exit 0 來驗證 AI 的產出。
### 餐巾紙草圖
```text
[SDD: Spec-Driven Development 規格驅動]
Markdown 規格書 -> [Model 3.5 產生 Code A] -> [Model 3.7 解讀產生 Code B]
結果：每次升級模型，程式碼都不一樣，需不斷重寫 Spec。
[FDD: Facts-Driven Development 事實驅動]
Python 測試檔 (Fact) -> 丟給任何模型實作
結果：只要測試能 Pass (Exit Code 0)，就代表完成。Fact 是恆定不變的。
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼風靡一時的「規格驅動開發 (SDD, 如 Spec Kit)」在實際落地後，常常因為底層 LLM 模型的更換而導致產出的程式碼面目全非？
- **核心答案**: 因為自然語言規格書本質上是「對模型的預測」而非「合約」。模型每次閱讀都會進行機率採樣 (即便 Temperature = 0)。解決之道是回歸本質，編寫機器可獨立驗證的「事實 (Facts, 即自動化測試/斷言)」，以此作為唯一真理。
- **論證結構**: 揭示 SDD 的衰退與非確定性本質 -> 定義「規格」與「事實」的差異 -> 追溯 57 年的契約設計史 -> 界定 SDD 的少數合理場景 -> 提出 90 天的轉型遷移計畫。
### 章節骨架
1. **SDD 的泡沫**: Google Trends 顯示 SDD 關注度腰斬。當工具高度工業化時，往往是底層假設崩潰的開始。
2. **規格的幻覺**: 模型閱讀 Spec 就像一個喜怒無常的實習生。即使 `temp=0`，浮點運算與架構差異也會導致同一個 Spec 在不同模型間產生「意圖漂移 (Intent Gap)」。
3. **事實的力量**: Fact (事實) 是一個 Boolean 斷言 (如 `JWT 過期回傳 401`)。它不經過模型解釋，而是由編譯器/直譯器執行。一個測試可以安然度過 Sonnet 3.5 到 Opus 4.5 的升級而不需修改。
4. **SDD 唯一適用的場景**: 只有在「合規審計 (Compliance)」、「B2B 跨團隊對接」以及「新人 Onboarding」時，自然語言的 Spec 才有價值，因為讀者是「人」。
5. **90 天轉型法**: 盤點 (Audit) -> 轉換為測試 (Pivot) -> 設為 CI 閘門 (Gate)。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 作者認為自然語言在精確邏輯表達上有先天的缺陷，無論 AI 模型多麼強大，語言的歧義性永遠無法消除。真正的可靠性只能建立在數學與形式化邏輯 (如單元測試、斷言) 之上。
- **邊界條件**: 撰寫高覆蓋率的自動化測試 (Facts) 本身需要極高的工程紀律與成本。在快速試錯的 MVP 階段，強求所有邏輯都寫成可執行斷言可能會拖慢速度。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 追溯至 1969 年的霍爾邏輯 (Hoare Logic)、1992 年 Eiffel 語言的「契約式設計 (Design by Contract)」，以及 TDD (測試驅動開發)。
- **深層洞見**: **「模型遷移不是系統更新，而是換了一個解譯器。」** 許多人試圖透過完美的 Prompt (Spec) 來控制 AI，這注定徒勞。把精力花在寫「判定對錯的測試機」上，讓 AI 自由發揮去滿足這個測試，才是與 AI 共生的高級智慧。
- **行動呼籲**: 明天早上，挑選一個目前只存在於 Spec 文件裡的商業邏輯，將其改寫為一個能丟進 CI 運行的 Python/TypeScript 單元測試。從一個 Fact 開始。
---
# 停止寫規格，開始寫事實 (Architectural Deep Dive)
## 前言/背景
過去十個月，由 GitHub 的 Spec Kit 等工具帶起的「規格驅動開發 (SDD)」風潮一度席捲業界。然而，作者透過實戰數據與 Google Trends 指出，SDD 運動正在崩潰。其致命缺陷在於「自然語言規格書」無法抵抗 LLM 的非確定性 (Non-determinism)。本文提倡回歸 57 年來的軟體驗證基礎：停止寫給 AI 猜測的 Spec，開始寫機器能直接執行的測試斷言 (Facts)。
## 章節詳細總結
### SDD 運動的興衰與底層缺陷 (Anatomy of a Movement & A Spec Is a Prediction)
SDD 的基本假設是：透過嚴謹的自然語言 (如 EARS notation) 寫出 Spec，LLM 就能穩定輸出對應代碼。
**這是錯的**。Spec 不是合約，而是對模型的「預測」。
* **非確定性機制**：由於 GPU 浮點運算的非關聯性、Batch 調度等問題，即便是 `Temperature = 0`，模型在不同次調用或不同版本間，對同一段 Spec 的解讀也會產生偏差 (意圖差距 / Intent Gap)。
* **規格漂移 (Spec Drift)**：今天能用 Claude 3.5 產出正確代碼的 Spec，明天用 Claude 3.7 可能就會產生 Bug。**模型升級本質上是更換了解譯器 (Interpreter)。**
### 什麼是「事實 (Facts)」？(A Fact as an Executable Assertion)
相對於需要被 LLM「解讀」的 Spec，Fact 是一個**機器可自行驗證的可執行斷言 (Executable Assertion)**。
* 例如：`assert binary_search([1,2,3], 2) == 1`。
* 它不經過模型的心情，只產生 Exit 0 (通過) 或 Non-zero (失敗)。
* 作者指出，他的一組測試代碼，在經歷了 Claude 3.5, 3.7, 4, Opus 4.5 的升級後，完全不需要修改依然能正常守護系統；而同一功能的 Spec 文件，卻被迫重寫了四次以配合不同模型的胃口。
* 這並非新發明，而是延續了 1969 年霍爾邏輯與 1992 年「契約式設計 (Design by Contract)」的驗證哲學。
### 規格書 (SDD) 殘存的價值邊界 (Where Ceremony Is the Product)
SDD 並非一無是處。當閱讀對象是「人」時，自然語言無可取代。
1. **合規與監管 (Compliance)**：如 DO-178C (航空) 或歐盟 AI 法案，審計員需要看人類可讀的文件。
2. **B2B 跨團隊整合**：Stripe 提供 OpenAPI 給合作夥伴，這需要共享的商業意圖，而非單純的測試碼。
3. **新人入職 (Onboarding)**：測試代碼告訴機器 *What*，Markdown 文件告訴新人 *Why*。
**判斷標準：如果這份文件 Merge 後沒有「團隊外部的人」會去讀，那就應該拔除它，轉寫為測試代碼。**
### 90 天轉型遷移計畫 (Ninety Days of Migration)
作者提出分階段脫離 SDD 陷阱的實務路徑：
* **Phase 1: 盤點 (Audit, Days 1-30)**：將文件分為三類：外部人會讀的 (保留)、沒人看的 (廢棄)、以及隱藏在生產環境的高風險隱式規則 (標記為轉換目標)。
* **Phase 2: 轉換 (Pivot, Days 31-60)**：將 API 合約轉為 Pact 測試，資料屬性轉為 Property-based testing (如 QuickCheck)。減少傳統單元測試，增加合約驗證。
* **Phase 3: 設閘 (Gate, Days 61-90)**：將 `facts check` 加入 CI 流程並阻擋 Merge。新功能開發前必須先有「會 Failed 的 Fact」，這就是披著 AI 外衣的 TDD (測試驅動開發)。
## 總結論點
* **PRD 正在消亡**：規格書將離開開發者的內循環 (Inner Loop)。
* **擁抱事實**：你唯一能信任的，是 Python/TS 運行時 (Runtime) 的 Exit Code，而不是模型對你 Markdown 的保證。
* **降低成本**：跑一次自動化測試驗證全庫，比讓大模型閱讀十頁 Spec 便宜且快得多。
Obsidian 整理
原始文章
工具技巧
12 個讓 Claude Code 變成真實工程師的配置技巧 (12 Claude Code Setup Tricks)
"別再把 Claude Code 當成聰明的聊天機器人；只有當你把它視為一個整合了記憶、強大 CLI 工具與平行分支的「AI 原生開發環境」時，它的威力才會真正爆發。"
Top 5 Insights
- **思維升級**：AI 編程的重點不再是「如何寫代碼寫得更快」，而是「如何建構一個讓 AI 高效運作的系統」。
- **系統即 Prompt**：完善的工具鏈 (`ripgrep` + MCP) 與記憶管理 (`CLAUDE.md`)，本身就是最強大的無形 Prompt。
- **未來趨勢**：未建立「AI 原生工作流」的開發者，與已經開始使用平行 Worktree 與 CI/CD AI 攔截的開發者，兩者之間的生產力鴻溝將越來越大。
---
tags: [工具技巧, 開發工具, Claude Code, 系統配置, 工作流]
date: 2026-05-19
read: false
source: "2026-05-19T092748+0800-These 12 Claude Code Setup Tricks Made AI Feel Like a Real Engineer.md"
---
# 12 個讓 Claude Code 變成真實工程師的配置技巧 (12 Claude Code Setup Tricks)
原始來源與檔名：2026-05-19T092748+0800-These 12 Claude Code Setup Tricks Made AI Feel Like a Real Engineer.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> AI 開發效能 = 工具基礎設施 (MCP + CLI) + 專案上下文記憶 (CLAUDE.md) + 平行工作流 (Git Worktrees + Subagents)
### 一句話
> 別再把 Claude Code 當成聰明的聊天機器人；只有當你把它視為一個整合了記憶、強大 CLI 工具與平行分支的「AI 原生開發環境」時，它的威力才會真正爆發。
### 餐巾紙草圖
```text
[新手模式] 聊天機器人 -> 單線程 -> 頻繁遺忘 -> 每次重寫 Prompt (低效)
[工程模式] /init 建構脈絡 -> CLAUDE.md 持久化記憶 -> MCP 連接外部庫 -> Subagent 處理子任務 (高效自動化)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 大多數開發者只把 Claude Code 當作 CLI 版的 ChatGPT 來「許願」，導致輸出不穩定且上下文混亂。該如何配置才能發揮其全部潛力？
- **核心答案**: 透過建立持久記憶 (CLAUDE.md)、提供強大的底層工具 (ripgrep/MCP)、以及重塑工作流 (平行 Worktrees、子任務 Subagents)，將其升級為工業級的開發環境。
- **論證結構**: 點出錯誤認知 -> 提出 12 項具體的系統/環境配置技巧 -> 總結論點 (從偶爾使用走向 AI 原生工作流)。
### 章節骨架
1. **記憶與初始化**: 使用 `CLAUDE.md` 建立專案記憶；接觸新代碼前必跑 `/init`。
2. **底層基礎設施**: 裝備強大的 CLI 工具 (ripgrep, fd)；連接 MCP Server 以獲取真實外部資料。
3. **工作流重塑**: 使用 Git Worktrees 讓 AI 平行開發；在 VS Code 中獲得更好的協作體驗。
4. **自動化與分工**: 設定可複用的 Slash Commands (`/security-audit`)；使用 Subagents 處理雜事以保持主 Context 乾淨。
5. **資源與 CI/CD**: 監控 Token 消耗；使用高 Token 模型處理大重構；將 Claude 整合進 PR 審查流程。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 開發者必須願意投資時間在「配置基礎設施」上，而不是急於寫代碼。磨刀不誤砍柴工，環境越強大，AI 幻覺越少。
- **邊界條件**: 這些高階操作 (如 Subagents, 大量 Context) 會迅速消耗 Token 配額，因此嚴格的 Token 監控 (Trick 10) 是這套工作流得以持續的前提。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 呼應 DevOps 的「基礎設施即代碼 (IaC)」與分散式版本控制 (Git Worktrees) 哲學。
- **深層洞見**: AI 開發的核心已經不再是「如何寫出神級 Prompt」，而是「如何建構一個讓 AI 不會犯錯的生態系統」。給 AI 一個強大的 `ripgrep`，比在 Prompt 裡千叮嚀萬囑咐有用百倍。
- **行動呼籲**: 不要急著叫 Claude 寫 Code。先執行 `/init`，寫好 `CLAUDE.md`，並把 `fd` 和 `ripgrep` 裝進你的終端機。
---
# 12 個讓 Claude Code 變成真實工程師的配置技巧 (Architectural Deep Dive)
## 前言/背景
多數人使用 Claude Code 時，仍停留在「幫我寫這個、幫我修那個」的對話思維。本文作者指出，真正的威力在於將其從「聊天機器人」升級為「AI 開發環境」。透過優化周邊系統配置，能引發複利效應：減少幻覺、加快搜尋、降低認知負擔。
## 章節詳細總結
### 記憶與上下文管理 (Context & Memory)
* **Trick 1: `CLAUDE.md` 持久化記憶**：依賴對話紀錄是危險的。應將架構決策、常犯錯誤、專案背景寫入此檔案。當 AI 記住專案運作方式，你就能省下每次重新解釋的時間。
* **Trick 2: 執行 `/init`**：面對新代碼庫，千萬不要直接下指令。先跑 `/init` 讓 AI 掃描結構、依賴與慣例，這能立刻提升後續輸出的精準度。
* **Trick 9: Subagents 保護主 Context**：將找 Bug、查文獻等雜事交給 Subagent，只把最終結論帶回主會話。這是防止主 Context 被巨量雜訊污染的終極手段。
### 基礎設施與外部感知 (Infrastructure & Perception)
* **Trick 4: 強悍的 CLI 工具**：為終端機配置 `ripgrep`, `fd`, `jq`。當 AI 擁有這些極速搜尋與解析工具時，它的代碼發現與除錯能力會發生質變。
* **Trick 5: 戰略性使用 MCP Servers**：打破訓練資料的限制，透過 MCP 連接動態文檔、資料庫與 Notion。讓 AI 基於「真實外部數據」而非「盲目猜測」來操作。
### 工作流與工程紀律 (Workflows & Engineering)
* **Trick 3: Git Worktrees 實現平行開發**：不要讓 AI 一次只做一件事。利用 Worktrees 開出多個完全隔離的目錄，讓 AI 同時處理 Auth 修復與 UI 重構，互不干擾。
* **Trick 8: 可複用的 Slash Commands**：不要每次手寫 Prompt。將常規流程固化為 `/security-audit`, `/generate-tests` 等巨集命令，實現操作標準化。
* **Trick 7: 建立專門的外掛 (Plugins)**：不要用一個通用助理打天下，應為前端、架構審查、文檔生成設定專職的 AI 角色配置。
* **Trick 6: 結合 VS Code**：純終端機雖然浪漫，但結合 IDE 帶來的行內編輯 (Inline Edits) 與導航能大幅降低摩擦。
### 資源與工業級佈署 (Scale & CI/CD)
* **Trick 10: 嚴肅追蹤 Token**：將 AI 視為運算資源，監控其 Context 成長與無效的工具呼叫。
* **Trick 11: 釋放高 Token 配額模型**：當需要進行架構級別的跨檔案大重構時，切換至高配額模型，讓 AI 編程進入工業級。
* **Trick 12: 深度整合 CI/CD**：讓 Claude 負責 PR 審查、強制執行標準與攔截錯誤。這標誌著 AI 從「開發輔助工具」進化為「軟體生命週期的一部分」。
## 總結與結論
* **思維升級**：AI 編程的重點不再是「如何寫代碼寫得更快」，而是「如何建構一個讓 AI 高效運作的系統」。
* **系統即 Prompt**：完善的工具鏈 (`ripgrep` + MCP) 與記憶管理 (`CLAUDE.md`)，本身就是最強大的無形 Prompt。
* **未來趨勢**：未建立「AI 原生工作流」的開發者，與已經開始使用平行 Worktree 與 CI/CD AI 攔截的開發者，兩者之間的生產力鴻溝將越來越大。
Obsidian 整理
原始文章
工具技巧
Codex 使用本地大模型保姆級教程 (Running Codex with Local LLMs via Ollama)
"透過 Ollama，你可以將 Codex 綁定到本地執行的開源大模型 (如 Gemma 4)，實現完全離線、保護隱私且免費的 AI 輔助開發。"
---
tags: [工具技巧, 開發工具, 本地模型, Ollama, Codex]
date: 2026-05-19
read: false
source: "2026-05-19T092736+0800-Codex 可以使用本地大模型保姆级教程.md"
---
# Codex 使用本地大模型保姆級教程 (Running Codex with Local LLMs via Ollama)
原始來源與檔名：2026-05-19T092736+0800-Codex 可以使用本地大模型保姆级教程.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 本地 AI 編程環境 = Codex Desktop App (前端) + Ollama v0.24+ (後端驅動) + Gemma 4 / Qwen 3.6 (模型)
### 一句話
> 透過 Ollama，你可以將 Codex 綁定到本地執行的開源大模型 (如 Gemma 4)，實現完全離線、保護隱私且免費的 AI 輔助開發。
### 餐巾紙草圖
```text
[Codex Desktop] -- (ollama launch codex-app) --> [Ollama Runtime]
|
v
[Local Model: Gemma 4]
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 如何在不使用雲端 API (保護代碼隱私、節省成本) 的前提下，使用 Codex Desktop App 進行 AI 開發？
- **核心答案**: 升級 Ollama 至 v0.24 以上，透過專用指令啟動 Codex，並選擇本地下載的開源模型 (Gemma 4 或 Qwen 3.6)。
- **論證結構**: 環境要求 -> Ollama 安裝/更新 -> 啟動專用通道 -> 模型選擇與自動下載 -> 復原設定。
### 章節骨架
1. **環境準備**: 需要 Codex Desktop, Ollama v0.24, 以及適配硬體的模型。
2. **安裝與啟動**: 透過 `curl` 安裝 Ollama，使用 `ollama launch codex-app` 啟動。
3. **模型選擇**: 推薦平衡性佳的 Gemma 4，或高階設備可用的 Qwen 3.6。
4. **注意事項**: Ollama 會覆寫 Codex 的 `config.toml`，需提前備份或使用 `--restore` 復原。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 使用者的終端設備具備足夠的 VRAM/RAM 能夠流暢運行 10B 級別的開源語言模型。
- **邊界條件**: 本地模型的推論速度與程式碼品質與設備硬體高度綁定；若硬體不足，仍建議切換回雲端模式。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 邊緣運算 (Edge AI) 與資料隱私 (Data Privacy) 趨勢。
- **深層洞見**: 開發工具的「大腦」正在解耦。前端 IDE (Codex) 負責上下文管理與 UI，後端 (Ollama) 負責模型推論，這種解耦讓開源社群能夠無縫接入頂級工具。
- **行動呼籲**: 開發者應立即備份 `~/.codex/config.toml`，並在本地環境安裝 Gemma 4 測試離線編程流程。
---
# Codex 使用本地大模型保姆級教程 (Architectural Deep Dive)
## 前言/背景
隨著開源模型能力的提升，越來越多開發者希望在本地環境運行 AI 編程助手以確保原始碼隱私並降低 API 成本。本文提供了一套極簡指南，教導使用者如何透過 Ollama 驅動 Codex Desktop App。
## 章節詳細總結
### 環境配置與核心指令
要實現本地驅動，必須確保 Ollama 升級至 v0.24 以上版本。
啟動的關鍵在於使用專用通道指令：`ollama launch codex-app`。該指令會自動攔截 Codex 的後端請求並導向本地服務。
### 模型的抉擇
* **Gemma 4**：文章強烈推薦作為預設選擇，其在參數量與推論速度之間達到了極佳的平衡，適合多數開發者的筆電環境。
* **Qwen 3.6**：針對擁有高階 GPU 的開發者，提供更大的參數規模與更強的邏輯推理能力。
當在介面上選擇本地模式後，Ollama 會自動處理權重的下載並重啟 Codex。
### 設定覆寫與防禦性還原
這個機制的底層原理是 Ollama 動態修改了 Codex 的設定檔 `~/.codex/config.toml`，將 Endpoint 指向 `localhost`。
*安全實踐*：若需要切換回官方雲端服務，使用者必須執行 `ollama launch codex-app --restore` 以還原被覆寫的設定，建議在操作前手動備份該檔案。
Obsidian 整理
原始文章
工具技巧
為什麼 Karpathy 的 CLAUDE.md 獲得了 82,000 顆星 (The Viral CLAUDE.md Explained)
"不要讓 AI 在每次對話時都從零開始猜測你的意圖與架構；建立一個根目錄的 ，將溝通風格、權限邊界與技術棧固化，能徹底終結 AI 擅自重構代碼與遺忘決策的噩夢。"
Top 5 Insights
- **基礎設施即代碼**：`CLAUDE.md` 是一種將團隊文化、工程紀律與防禦性編程策略「代碼化」的偉大實踐。
- **投資報酬率極高**：只需花費 2 小時設定，就能換來一個記得決策、遵守範圍、不破壞系統的專屬 AI 夥伴。
- **循序漸進**：建議開發者立即從 Karpathy 的 4 大法則開始，建立根目錄的 `CLAUDE.md`，並在日常開發中逐步將團隊規範沉澱其中。
---
tags: [工具技巧, AI工程, 系統提示詞, Claude, 最佳實踐]
date: 2026-05-19
read: false
source: "2026-05-19T092723+0800-Karpathy's CLAUDE.md hit 1 on GitHub with 82,000 stars. Most devs still haven't read it..md"
---
# 為什麼 Karpathy 的 CLAUDE.md 獲得了 82,000 顆星 (The Viral CLAUDE.md Explained)
原始來源與檔名：2026-05-19T092723+0800-Karpathy's CLAUDE.md hit 1 on GitHub with 82,000 stars. Most devs still haven't read it..md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> Agent 的可靠度 = 預設行為約束 (Defaults) + 破壞性邊界控制 (Behavior) + 長期決策記憶 (Memory/Stack)
### 一句話
> 不要讓 AI 在每次對話時都從零開始猜測你的意圖與架構；建立一個根目錄的 `CLAUDE.md`，將溝通風格、權限邊界與技術棧固化，能徹底終結 AI 擅自重構代碼與遺忘決策的噩夢。
### 餐巾紙草圖
```text
[無配置的災難] 每次解釋上下文 (耗時) -> AI 瞎猜邊界 -> 擅自重構無關代碼 -> 遺忘過去決策 (高成本修復)
[CLAUDE.md] 注入全局指令 -> 鎖定修改範圍 (Scope) -> 攔截高危操作 -> 讀取 MEMORY.md 延續架構決策 (高精準度)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 開發者每天花費大量時間向 AI 重新解釋專案背景，並收拾 AI 擅自重構代碼或遺忘技術決策的殘局，該如何解決？
- **核心答案**: 在專案根目錄放置一份精確定義預設行為、範圍約束與記憶機制的 `CLAUDE.md`，將重複的溝通成本降為零，大幅提高編程準確率 (從 65% 升至 94%)。
- **論證結構**: 痛點與成本計算 -> Defaults (預設溝通方式) -> Behavior (行為與修改邊界) -> Memory (記憶與技術棧鎖定)。
### 章節骨架
1. **背景**: Andrej Karpathy 提出的 4 大防翻車法則被擴展為 `CLAUDE.md`，引爆 GitHub。
2. **Part 1: Defaults (預設溝通)**: 消除廢話，設定回答長度，強制先提供選項，並定義開發者背景與專案目標。
3. **Part 2: Behavior (行為邊界)**: 絕對禁止修改無關代碼，重大重構或破壞性操作(如刪除、部署)必須獲得「當次對話的明確確認」。
4. **Part 3: Memory & Stack (記憶與技術棧)**: 強制 AI 讀取 `MEMORY.md` 與 `ERRORS.md`，鎖定特定的框架與資料庫，避免提出不相容的建議。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: AI 語言模型本質上是「取悅者 (Pleaser)」，預設會產生大量安撫性廢話，並試圖「超額完成任務」(如擅自優化架構)。
- **邊界條件**: `CLAUDE.md` 的效力取決於底層 Agent Runtime 是否有支援自動讀取專案配置檔的機制 (如 Claude Code)。若工具無此功能，則需手動將其設為 System Prompt。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 軟體工程中的「不可變基礎設施 (Immutable Infrastructure)」與「架構決策紀錄 (ADR)」。
- **深層洞見**: 開發者經常抱怨 AI「記性不好」或「亂改代碼」，這不是智商問題，而是缺乏「邊界合約」。`CLAUDE.md` 就是開發者與 AI 之間簽訂的嚴格勞動合約。
- **行動呼籲**: 立刻在專案根目錄建立 `CLAUDE.md`，先貼上 Karpathy 的 4 大基本法則，再逐步完善記憶日誌機制。
---
# 為什麼 Karpathy 的 CLAUDE.md 獲得了 82,000 顆星 (Architectural Deep Dive)
## 前言/背景
前 Tesla AI 總監 Andrej Karpathy 總結了 4 個導致 Claude Code 失敗的致命行為，隨後社群將其擴展為一份 21 條規則的 `CLAUDE.md` 配置檔，在 GitHub 狂攬 8.2 萬星。本文量化了缺乏這份文件造成的「隱形成本」(如反覆解釋上下文、退回無用重構)，並詳細拆解了這份神級配置檔的三大核心區塊。
## 章節詳細總結
### 問題本質：每次對話都從零開始的昂貴代價
如果沒有 `CLAUDE.md`，Claude Code 每次啟動都是空白的。它不知道你的技術棧、設計標準、過去失敗的嘗試。這種「失憶」會導致它盲目猜測、擅自重構無關代碼，並提出破壞現有架構的建議。
*作者估算*：每位工程師每週因重新解釋上下文、還原錯誤修改、收拾遺忘決策所浪費的成本高達 975 美元。
### 模組 1：預設溝通約束 (Defaults)
旨在消除 AI 的阿諛奉承與廢話，提高資訊密度。
* **擊殺廢話**：禁止使用 "Great question!" 或 "Certainly!" 等無意義的開場白。
* **匹配長度**：簡單問題給短答案，複雜任務給長答案，拒絕結尾重複總結。
* **選項優先**：執行複雜任務前，必須先給出 2-3 個方案供人類選擇。
* **背景注入**：預先聲明開發者的技術強項與弱項，避免 AI 對資深工程師過度解釋基礎概念。
### 模組 2：行為邊界與破壞性攔截 (Behavior)
這是防止 AI「幫倒忙」的核心機制。
* **嚴格控制作用域 (Stay in scope)**：絕對禁止重構、重新命名或美化「與當前任務無關」的程式碼。若發現其他問題，只能在結尾以附註提及，禁止觸碰。
* **防呆確認鎖**：進行任何改變現有邏輯、刪除檔案、修改資料庫或對外 API 部署的行為前，必須獲得使用者在「當前訊息」中的明確 `Yes` 確認。
* **變更透明度**：任務結束時必須列出修改了哪些檔案、修改了什麼，以及「刻意沒有觸碰」的內容。
### 模組 3：長期記憶與技術棧鎖定 (Memory + Stack)
賦予 AI 跨 Session 的決策記憶能力。
* **引入外部日誌庫**：強制 Claude 在會話開始時讀取 `MEMORY.md` (架構決策紀錄) 與 `ERRORS.md` (失敗嘗試紀錄)，避免重複踩坑。
* **Session 總結**：對話結束時，要求 AI 自動將進度與決策寫入 `MEMORY.md`。
* **鎖定技術棧**：明確規定語言 (TypeScript)、框架 (Next.js)、資料庫 (PostgreSQL) 等，禁止 AI 提出與此技術棧不相容的建議。
### 核心靈魂：Karpathy 的 4 大基本法則
這四條規則是將代碼準確率從 65% 提升至 94% 的基石：
1. **先問勿猜 (Ask, don't assume)**：意圖不明時必須發問，禁止靜默假設。
2. **最簡解法 (Simplest solution first)**：永遠實作最簡單的方案，禁止主動添加未要求的抽象層。
3. **隔離無關代碼 (Don't touch unrelated code)**：嚴禁修改不在當前任務範圍內的文件。
4. **明確標示不確定性 (Flag uncertainty explicitly)**：缺乏自信時必須直言不諱，禁止用看似合理的幻覺填補知識空白。
## 總結與結論
* **基礎設施即代碼**：`CLAUDE.md` 是一種將團隊文化、工程紀律與防禦性編程策略「代碼化」的偉大實踐。
* **投資報酬率極高**：只需花費 2 小時設定，就能換來一個記得決策、遵守範圍、不破壞系統的專屬 AI 夥伴。
* **循序漸進**：建議開發者立即從 Karpathy 的 4 大法則開始，建立根目錄的 `CLAUDE.md`，並在日常開發中逐步將團隊規範沉澱其中。
Obsidian 整理
原始文章
後端架構
Netflix 機器學習民主化：建構模型生命週期圖譜 (Democratizing Machine Learning at Netflix: Building the Model Lifecycle Graph)
"Netflix 透過建立統一的 Metadata 服務 (MDS)，將散落各處的特徵庫、工作流引擎、模型註冊表與 A/B 測試平台整合為一張互聯的「模型生命週期圖譜」，徹底解決了跨部門 ML 資產難以發現與追蹤影響的痛點。"
Top 5 Insights
- **從搜尋走向探索**：圖譜建置完成後，使用者不再只是「搜尋一個模型名字」，而是能夠沿著圖譜點擊：從模型 -> 特徵 -> 源資料集 -> Pipeline -> 負責人。
- **非同步解耦的架構藝術**：Netflix 利用「輕量級通知 + 主動補水 + 背景推論」的非同步架構，在不影響即時事件吞吐量的前提下，完成了極耗運算資源的圖譜構建。
- **未來的挑戰**：包含如何為不同實體開發特定的視覺化 UI、如何防範過時或錯誤的 Metadata 污染圖譜，以及嘗試利用 ML 自動推論出「隱式關係」(如兩個模型雖無明文連結，但因為使用高度重疊的特徵，因此具有相似性)。
---
tags: [後端架構, AI工程, 系統工程, MLOps, Netflix]
date: 2026-05-19
read: false
source: "2026-05-19T093028+0800-Democratizing Machine Learning at Netflix Building the Model Lifecycle Graph.md"
---
# Netflix 機器學習民主化：建構模型生命週期圖譜 (Democratizing Machine Learning at Netflix: Building the Model Lifecycle Graph)
原始來源與檔名：2026-05-19T093028+0800-Democratizing Machine Learning at Netflix Building the Model Lifecycle Graph.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 模型生命週期圖譜 = 異質中繼資料 (Kafka 事件) + 統一實體正規化 (AIP URIs) + 非同步關係補水 (Datomic + Elasticsearch)
### 一句話
> Netflix 透過建立統一的 Metadata 服務 (MDS)，將散落各處的特徵庫、工作流引擎、模型註冊表與 A/B 測試平台整合為一張互聯的「模型生命週期圖譜」，徹底解決了跨部門 ML 資產難以發現與追蹤影響的痛點。
### 餐巾紙草圖
```text
[Pipeline] --(event)--> [MDS Ingestion] -> [Hydration (打API抓全貌)] -> [Normalization (AIP URI)]
|
[Model Reg] --(event)--> v
[Datomic (Graph Cache)]
[A/B Test] --(event)--> | (非同步關聯推論)
v
[Elasticsearch (Search & Discovery UI)]
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 隨著 Netflix 的 ML 應用從單一的「個人化推薦」擴展到製片、廣告、支付等多個領域，各部門的 ML 工具與資料成為資訊孤島 (Silos)，從業人員如何跨越部門界線進行模型與特徵的共享、溯源及影響力分析？
- **核心答案**: 建構一個名為 Metadata Service (MDS) 的中心化服務，將各系統的離散事件正規化，並利用 Datomic 與 Elasticsearch 建構出「模型生命週期圖譜 (Model Lifecycle Graph)」，實現強大的探索與關聯查詢能力。
- **論證結構**: 描述碎片化的痛點 -> 定義統一詞彙 (AIP URI) -> 拆解 MDS 系統的 5 大處理階段 -> 展示關聯推論的威力 (模型關聯 A/B 測試) -> 討論未來的挑戰。
### 章節骨架
1. **挑戰 (碎片化景觀)**: ML 從單一領域擴張到全公司，但模型變成了黑盒，特徵商店、管線、模型註冊與實驗平台互不相通，導致無法發現與溯源。
2. **核心抽象化 (Vocabulary)**: 定義 Component, Entity, Domain, Provider。所有資產皆透過 `aip://<type>/<provider>/<id>` (AIP URI) 統一尋址。
3. **從事件到圖譜的 5 個階段**:
- *Ingestion*: 接收輕量級事件。
- *Enrichment (Hydration)*: 打 API 抓取最新完整狀態，保證無序事件也能最終一致。
- *Normalization*: 將異質資料轉化為標準欄位與 AIP URI 參照。
- *Storage*: Datomic (圖形關聯/快取) + Elasticsearch (全文檢索)。
- *Knowledge Enrichment*: 背景作業推論跨系統關係。
4. **探索案例**: 展示如何透過圖譜查詢，將「模型」透過「Pipeline」一路追溯到「A/B 測試單元」。
5. **未來挑戰**: 工具激增的擴充性、特定領域的 UI 視覺化、資料品質監控，以及隱式關係的推論。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 系統設計的底層邏輯是「通知而非日誌 (Notification of change rather than log of changes)」。假設底層事件匯流排 (Kafka) 可能掉訊息或亂序，因此 MDS 採用收到事件後主動反查 (Hydration) 來源系統的 API，以獲取「當前絕對真理」。
- **邊界條件**: 這種 Hydration 設計將沉重的讀取壓力轉嫁給了各來源系統的 API。因此，MDS 必須具備強大的速率限制、快取與退避 (Backoff) 機制，以免將基礎建設打掛。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 軟體架構中的 CQRS (Command Query Responsibility Segregation) 模式、GraphQL 的圖形化查詢，以及資料網格 (Data Mesh) 的治理思維。
- **深層洞見**: Netflix 解決的不是「儲存」問題，而是「語義關聯」問題。當不同的微服務團隊各自開發時，系統邊界成為了知識共享的阻礙。MDS 本質上是在異構微服務之上，強行鋪設了一層全局的「知識語義網」。
- **行動呼籲**: 如果你的企業內部有多個互不相通的 AI 工具鏈，不要試圖重寫一個超級平台。學習 Netflix：制定統一的 URI 標準，並建立一個非同步的中繼資料關聯層來打通孤島。
---
# Netflix 機器學習民主化：建構模型生命週期圖譜 (Architectural Deep Dive)
## 前言/背景
Netflix 早期的機器學習幾乎全用於「個人化推薦」。如今，ML 已經滲透到製片 (Studio)、廣告 (Ads) 與支付防詐騙等各大領域。不同領域使用不同的技術棧，導致 ML 資產成為資訊孤島。為了解決跨團隊的模型復用、血緣追蹤與 A/B 測試影響分析，Netflix AI 平台團隊打造了 Metadata Service (MDS)，構建出全局的「模型生命週期圖譜」。
## 章節詳細總結
### 挑戰：碎片化的 ML 景觀
製片團隊開發的「場景切割 Embedding」對廣告團隊 (Context matching) 或推薦團隊都有極大價值，但因為缺乏發現機制而難以跨部門共享。
最大的技術挑戰在於：特徵庫、工作流引擎、模型註冊表、實驗平台等**來源系統互不相通，且 Schema 各異**。工程師無法簡單回答：「如果我改了這個特徵，會弄壞哪個線上實驗？」
### 核心解法與 URI 定址 (Core Abstractions)
Netflix 建立了統一的詞彙庫。所有的 ML 資產 (Component) 都能透過全局唯一的 **AIP URI** 進行尋址，格式為 `aip://<componentType>/<platformId>/<resourceId>` (例如 `aip://model/registry/ranking-v5`)。這讓跨系統的引用有了標準語言。
### 資料處理的五大階段 (From Events to Graph)
MDS 從接收到建成圖譜分為五個精細的工程階段：
1. **事件接收 (Ingestion)**：從 Kafka/SQS 接收極簡的狀態變更通知，生產端無需組裝龐大的 Payload。
2. **實體補水 (Entity Enrichment / Hydration)**：這是一個關鍵設計。MDS 收到通知後，主動去呼叫來源系統的 API 獲取「最新全貌」。這解決了事件掉包或亂序的問題，保證資料最終一致。
3. **正規化 (Normalization)**：將各系統獨有的 ID 轉譯為 AIP URI，統一欄位命名 (如把 `owner_emails` 轉為對使用者的 URI 引用)。
4. **雙重儲存與索引 (Storage & Indexing)**：
* **Datomic**：作為圖資料庫與快取，存儲不變的事實 (Facts) 與所有實體關聯 (Edges)，適合多節點圖形遍歷。
* **Elasticsearch**：將正規化後的資料即時建索引，提供給使用者介面 (AIP Portal) 進行毫秒級的全文模糊檢索。
5. **知識擴充 (Knowledge Enrichment)**：非同步的背景作業。負責在 Datomic 中自動推理並建立跨系統的關聯。
### 關聯推論的威力：模型與 A/B 測試 (Example)
以「找尋某模型在哪個 A/B 測試中運行」為例：
* 模型本身只記錄了產出它的 `pipeline_run_id`。
* 擴充作業反查 Pipeline 系統，發現該 Pipeline 是為了 `A/B 測試單元 #2` 運行的。
* 擴充作業再查詢實驗平台，確認 `測試單元 #2` 屬於某個具體的 A/B 測試專案。
* **最終結果**：MDS 自動在 Datomic 中畫出一條連接線 (Edge)，將「模型」直接連結到「A/B 測試」。使用者只需一次 GraphQL 查詢就能取得完整上下游脈絡。
## 總結與結論
* **從搜尋走向探索**：圖譜建置完成後，使用者不再只是「搜尋一個模型名字」，而是能夠沿著圖譜點擊：從模型 -> 特徵 -> 源資料集 -> Pipeline -> 負責人。
* **非同步解耦的架構藝術**：Netflix 利用「輕量級通知 + 主動補水 + 背景推論」的非同步架構，在不影響即時事件吞吐量的前提下，完成了極耗運算資源的圖譜構建。
* **未來的挑戰**：包含如何為不同實體開發特定的視覺化 UI、如何防範過時或錯誤的 Metadata 污染圖譜，以及嘗試利用 ML 自動推論出「隱式關係」(如兩個模型雖無明文連結，但因為使用高度重疊的特徵，因此具有相似性)。
Obsidian 整理
原始文章
產業趨勢
AI 編程的黃金時代已經結束 (AI Coding Golden Age Is Over)
"由投資人補貼的「無限算力黃金時代」正在結束，未來的分水嶺不再是誰會用 AI，而是誰能「負擔得起」高階 AI，或是誰能用便宜模型組裝出高階能力。"
Top 5 Insights
- **黃金時代終結**：免費或超低價的高階 AI 時代正式結束，算力成本回歸常態。
- **真正的問題**：未來的開發者社群會被「算力購買力」階級化。誰能負擔得起，誰才有資格進行高效開發。
- **技術避險**：開發者必須立即建立屬於自己的工作流架構 (Harness)，確保在未來 API 大幅漲價或限流時，能平滑切換至更便宜的開源或本地模型而不中斷開發。
---
tags: [產業趨勢, 開發工具, 獨立開發, AI視野, 算力成本]
date: 2026-05-19
read: false
source: "2026-05-19T093015+0800-AI Coding Golden Age Is Over.md"
---
# AI 編程的黃金時代已經結束 (AI Coding Golden Age Is Over)
原始來源與檔名：2026-05-19T093015+0800-AI Coding Golden Age Is Over.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> AI 編程優勢 = 算力補貼 (即將消失) + 企業付費能力 (少數人) + 開源/本地化部署能力 (未來的護城河)
### 一句話
> 開發者正在經歷一場溫水煮青蛙：由投資人補貼的「無限算力黃金時代」正在結束，未來的分水嶺不再是誰會用 AI，而是誰能「負擔得起」高階 AI，或是誰能用便宜模型組裝出高階能力。
### 餐巾紙草圖
```text
[過去兩年 (黃金時代)]
$20/月 -> 無限暢飲 Frontier Models (Cursor, Claude Pro) -> 投資人燒錢獲客
[現在與未來 (補貼退潮)]
嚴苛的 5 小時 Cap 限制 -> 算力短缺 (Anthropic 甚至找 SpaceX 買算力)
-> 企業開發者 (公費無感) vs 獨立開發者 (負擔不起 $200/月，被迫用次等模型)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼最近使用 Claude Code 或 Cursor 等 AI 編程工具時，常常很快就達到使用上限 (Cap)，且模型反應似乎變慢了？
- **核心答案**: AI 編程工具前期的超低定價 ($20/月) 是投資人補貼的幻象。隨著算力需求暴增與基建擴展緩慢，真正的成本開始浮現。這導致了一條隱形的階級鴻溝：企業開發者不受影響，但獨立開發者將失去獲取頂級模型的權利。
- **論證結構**: 點出危機現象 -> 分析算力補貼的瓦解 (SpaceX 案例) -> 揭露企業與個人的資源鴻溝 -> 提出獨立開發者的應對策略 (開源 Harness 與本地模型)。
### 章節骨架
1. **危機浮現**: 訂閱費攀升，輸出品質卻下降，且經常被限流。黃金時代正在結束。
2. **補貼退潮**: Anthropic 為了算力不惜與理念不合的 Elon Musk (SpaceX) 合作，證明算力極度短缺。以前的低價只是為了獲客。
3. **隱形鴻溝**: 拿公司預算的開發者對成本無感；自掏腰包的獨立開發者若付不起 $100-$200/月的費用，將使用次等工具，進一步在求職與產出上落後。
4. **應對策略 (Music Stops)**: 不要被單一昂貴生態綁架。開始投資開源的 Agent Harness (如 Pi, Hermes) 或本地模型，學習如何「用便宜模型榨出高價值」。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 在軟體開發領域，工具的「民主化」正在倒退。如果 AI 成為編程的基礎設施，那算力成本將成為一種新的「開發者稅」，把底層開發者鎖在低效環境中。
- **邊界條件**: 只要半導體與能源的物理限制未被突破 (如核聚變或光子晶片量產前)，算力短缺的經濟壓力就不會緩解。這是一場物理與資本的雙重限制。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 呼應矽谷經典的「補貼獲客 -> 形成壟斷 -> 提高定價 (Enshittification)」的網路經濟學週期。
- **深層洞見**: 真正的 AI 工程能力，不是「會用最貴的 Claude Opus 寫代碼」，而是擁有在資源受限下 (便宜模型 + 開源 Harness) 依然能交付高階產出的**架構設計能力**。
- **行動呼籲**: 不要將你的生產力完全綁死在單一閉源付費工具上。今天就去了解 `create-sbastack-app` 或建構一套能隨時切換底層 API 的本地 Agent 系統。
---
# AI 編程的黃金時代已經結束 (Architectural Deep Dive)
## 前言/背景
當開發者還在爭論「AI 會不會讓我們變笨」時，作者提出了另一個更為致命的問題：「如果我們根本負擔不起 AI 呢？」本文從經濟學與資源分配的角度，剖析了 AI 編程工具背後的算力短缺危機，並警告獨立開發者必須盡早建立不依賴昂貴訂閱的自帶基礎設施 (Own Harness)。
## 章節詳細總結
### 補貼幻象的瓦解 (The subsidy is falling apart)
過去兩年，開發者以每月 $20 的極低價格，享受著 Cursor, Claude Pro 提供的頂級大模型 (Frontier Models) 無限制服務。這並非真實成本，而是風險資本 (VC) 在幫開發者買單以搶佔市佔率。
如今，跡象顯示這種模式已無法維持：
* **限流變嚴**：Claude Code、Codex 頻繁在 1-2 小時內就觸發 5 小時的 Cap 限制。
* **算力枯竭**：標榜高道德標準的 Anthropic 甚至為了取得 22 萬張 GPU 的算力，打破底線與 SpaceX 合作。基礎設施的建設速度遠遠追不上暴增的推論需求。
### 被忽視的階級鴻溝 (The divide nobody’s talking about)
當算力成本回歸真實定價時，開發者將面臨一條巨大的鴻溝：
* **企業開發者**：公司支付高昂的 API 費用，對限制無感，繼續享受高效率。
* **獨立開發者/初學者**：過去「一台筆電加網路就能改變世界」的網際網路精神正在消失。如果負擔不起每月 $100-$200 的 AI 費用，就只能使用笨拙、容易出錯的便宜模型，導致產出速度與履歷競爭力全面落後。
### 準備迎接音樂停止的時刻 (Preparing for when the music stops)
與其抱怨定價，不如建立防禦性架構。作者放棄了尋求「完美且昂貴的單一工具」，轉而投資：
* **開源 Harness**：如 Pi, Hermes，或是作者開源的 `create-sbastack-app`。
* **榨取低端模型**：透過優秀的 Prompt 鏈、RAG 與本地系統配置，讓便宜的 API (甚至是本地 GPU 模型) 能發揮出接近頂尖模型的水準。
* **核心競爭力轉移**：未來的護城河不再是「誰買得起最好的模型」，而是「誰能用最少的算力成本，設計出最穩定的 Agent 工作流」。
## 總結與結論
* **黃金時代終結**：免費或超低價的高階 AI 時代正式結束，算力成本回歸常態。
* **真正的問題**：未來的開發者社群會被「算力購買力」階級化。誰能負擔得起，誰才有資格進行高效開發。
* **技術避險**：開發者必須立即建立屬於自己的工作流架構 (Harness)，確保在未來 API 大幅漲價或限流時，能平滑切換至更便宜的開源或本地模型而不中斷開發。
Obsidian 整理
原始文章
知識管理
Building a Complete Personal Harness: LLM Wiki + Developer’s Second Brain in Obsidian
""
---
title: "Building a Complete Personal Harness: LLM Wiki + Developer’s Second Brain in Obsidian"
source: "https://medium.com/@roanmonteiro/building-a-complete-personal-harness-llm-wiki-developers-second-brain-in-obsidian-d7b61c7398ff"
author:
- "[[Roan Brasil Monteiro]]"
published: 2026-05-03
created: 2026-05-19
description: "Hands-on tutorial for setting up an agent-maintained knowledge base in Obsidian, combining an LLM Wiki with a developer's second brain (ADRs, debriefs, etc.)."
tags:
- "clippings"
- "知識管理"
- "Obsidian"
- "Agent"
read: false
---
# Building a Complete Personal Harness: LLM Wiki + Developer’s Second Brain in Obsidian
## 🎯 NAPKIN (核心洞見公式與餐巾紙草圖)
**核心概念**：
Agent-Maintained Knowledge Base = Immutable Sources (`raw/`) + Autonomous Synthesis (`wiki/`) + Collaborative Work (`dev/`)
**餐巾紙草圖 (架構視覺化)**：
```mermaid
graph TD
A[CLAUDE.md] --> |Policy Rules| B(Claude Code Agent)
B --> |Reads| C[Zone 1: raw/ Immutable]
B --> |Maintains| D[Zone 2: wiki/ Autonomous]
B <--> |Collaborates| E[Zone 3: dev/ Hybrid]
C --> |Source| F[Web Clippings, PDFs, Dailies]
D --> |Synthesizes| G[Concepts, Entities, Index]
E --> |Work| H[ADRs, Debriefs, Snippets]
```
---
## 🦴 ROUND 1: 骨架掃描 (XRay Scanner)
### 1. 文章要解決的核心問題是什麼？
傳統的個人知識管理 (PKM) 系統依賴人工維護，容易產生冗餘且難以交叉引用。對於開發者來說，缺乏將日常閱讀 (技術文章、論文) 與實際工作決策 (ADRs、事後檢討) 結合的有效機制。
### 2. 作者提出了什麼解決方案或論點？
在 Obsidian 中建立一個由 Claude Code 驅動的自動化知識庫，將 Vault 劃分為三個具有嚴格權限與規則的區域 (Zone 1: raw, Zone 2: wiki, Zone 3: dev)，並透過 `CLAUDE.md` 及 Skills 定義 Agent 的行為邊界。
### 3. 這個解決方案的關鍵要素有哪些？
* **Zone 0: Schema (`CLAUDE.md`)**：定義全局行為與權限。
* **Zone 1: `raw/` (唯讀)**：存放原始資料。
* **Zone 2: `wiki/` (Agent 維護)**：概念、實體、雙向連結。
* **Zone 3: `dev/` (協作)**：開發工作、ADRs、Debriefs。
* **Custom Skills & Commands**：使用 `/wiki-ingest` 與 `/wiki-query` 等指令，讓 Agent 依循工作流執行任務。
---
## 🥩 ROUND 2: 血肉解剖 (XRay Dissector)
### 第一層：為什麼選擇 Obsidian 作為 Agent 的基礎？
* **資料主權與開放格式**：基於本地 Markdown 檔案，不會被特定平台鎖死。
* **無縫整合 CLI**：Claude Code 可以直接讀寫檔案系統，不需要依賴封閉的 API。
### 第二層：三個區域的權限隔離機制
* **Raw 區 (唯讀)**：保證原始資訊不被 Agent 竄改或誤刪，作為所有推論的「Ground Truth」。
* **Wiki 區 (全權)**：Agent 可自由創建、修改概念與連結，建立知識圖譜。
* **Dev 區 (協作)**：例如 ADRs，Agent 可以給予建議，但不能擅自修改已接受的決策。
### 第三層：指令化工作流 (`/wiki-ingest` & `/wiki-query`)
* **Ingest**：抓取 URL 內容，清理，建立概念，雙向連結，**先提出計畫再執行** (Present plan before executing)。
* **Query**：透過 `grep` 搜尋 Vault，針對相關檔案進行重點閱讀，並在回答時引用 (`[[Wikilink]]`)。
---
## 🧠 ROUND 3: 靈魂提取 (XRay Extractor)
### 本質 (Essence)
「個人知識庫的未來不在於更好用的筆記軟體，而在於能夠自主關聯、重構並提取見解的智能 Agent。」
### 遷移 (Transfer)
* **企業級知識管理**：可以將此三分區架構推廣至企業的內部知識庫 (如 Confluence 替代方案)，讓 Agent 自動整理團隊的會議記錄與技術決策。
* **個人作業系統**：不僅是筆記，可以將日常日誌轉化為定期的洞察報告 (Weekly Synthesis)。
---
## 🏗️ Architectural Deep Dive (架構師深研)
**Agent Policy Enforcements (Agent 策略強制執行)**
這篇文章展示了非常實用的 Agent Governance (治理) 模式，利用簡單的 Markdown 檔案與檔案系統權限來約束 AI。
1. **宣告式治理 (`CLAUDE.md`)**：
這取代了在每次 prompt 中輸入長篇大論。只要 Agent 在該目錄啟動，就會讀取這個「憲法」，定義了它能做什麼與不能做什麼。
2. **Tools 限縮 (`allowed-tools`)**：
在 Slash Commands 中明確限制 `allowed-tools: Bash(curl:*), Bash(cat:*), Bash(ls:*), WebFetch`。這是一種最小權限原則 (Principle of Least Privilege)，防止 Prompt Injection 導致 Agent 執行 `rm -rf` 等危險操作。
3. **Human-in-the-Loop (HitL) 關卡**：
`/wiki-ingest` 的流程設計了 "Present plan BEFORE creating/editing pages"，這確保了大規模的自動化知識庫建構不會因為幻覺而走偏。
4. **防禦性設計 (Defensive Design)**：
使用 Git 進行版本控制，作為最終的安全網。一旦 Agent 發瘋，隨時可以 rollback。
Obsidian 整理
原始文章
認知思維
10 AI Skills That Will Decide Your Future
""
---
title: "10 AI Skills That Will Decide Your Future"
source: "https://medium.com/lets-code-future/10-ai-skills-that-will-decide-your-future-fd6324930522"
author:
- "[[Deep concept]]"
published: 2026-05-02
created: 2026-05-19
description: "An overview of 10 essential AI skills required to thrive in the shifting technological landscape."
tags:
- "clippings"
- "認知思維"
- "未來趨勢"
read: false
---
# 10 AI Skills That Will Decide Your Future
## 🎯 NAPKIN (核心洞見公式與餐巾紙草圖)
**核心概念**：
Future Success = Mastering AI (from Prompting to Agentic Systems) + Adapting to Automated Workflows
**餐巾紙草圖 (AI 技能階梯)**：
```mermaid
graph UP
A[1. Prompt Engineering] --> B[2. AI Agents]
B --> C[3. Workflow Automation]
C --> D[4. Agentic AI]
D --> E[5. Multimodal AI]
E --> F[6. RAG Systems]
F --> G[7. AEO / GEO]
G --> H[8. AI Tool Stacking]
style A fill:#e1f5fe
style H fill:#81d4fa
```
---
## 🦴 ROUND 1: 骨架掃描 (XRay Scanner)
### 1. 文章要解決的核心問題是什麼？
到 2030 年，職場將呈現兩極化：被 AI 取代的人 vs 利用 AI 效率提升 10 倍的人。多數人仍然將 AI 視為隨機聊天的 chatbot，並未掌握能真正改變工作方式的核心 AI 技能。
### 2. 作者提出了什麼解決方案或論點？
列出了 10 項決定未來競爭力的關鍵 AI 技能 (文章內容提供了前 8 項的詳細說明)，並強調我們必須從「自己動手做」轉變為「指揮 AI 自動完成」。
### 3. 這個解決方案的關鍵要素有哪些？
文章介紹的關鍵技能包括：
1. **Prompt Engineering (提示詞工程)**：學會給予清晰、帶有上下文與角色的指令。
2. **AI Agents (AI 代理)**：從一問一答，轉變為讓 AI 自動完成端到端 (end-to-end) 任務。
3. **Workflow Automation (工作流自動化)**：串接工具 (如 Make/Zapier)，讓重複性任務自動運行。
4. **Agentic AI (代理化 AI)**：具有思考、規劃與自我修正能力的 AI 系統。
5. **Multimodal AI (多模態 AI)**：整合文字、圖像、語音、程式碼等跨媒介的生成。
6. **RAG (檢索增強生成)**：將 AI 連結到私有知識庫，消滅幻覺並提高準確性。
7. **AEO/GEO (AI 引擎最佳化)**：確保內容能在 AI 搜尋工具 (如 ChatGPT/Perplexity) 中被引用與曝光。
8. **AI Tool Stacking (工具堆疊)**：將多個 AI 工具整合成一個自動化流水線系統。
---
## 🥩 ROUND 2: 血肉解剖 (XRay Dissector)
### 第一層：從「對話」到「代理」的思維進化
* **Prompt Engineering** 只是入門，決定了你與 AI 溝通的清晰度。
* **AI Agents & Agentic AI** 則是將 AI 從「回答問題的好學生」提升為「自動規劃與除錯的實習生」。Agentic AI 甚至能在迴圈中修正錯誤、最佳化策略。
### 第二層：企業落地與實用技術
* **RAG (Retrieval-Augmented Generation)** 解決了 AI 最大的痛點：幻覺。企業必須依賴自己的資料做決策，學會連接 Pinecone/LlamaIndex 將決定你是否能打造高價值的商業解決方案。
* **Workflow Automation & Tool Stacking**：打破孤立的工具使用模式。真正的效率來自於把 AI 嵌入到現有的工作流程中 (無縫連結 Sheets, Notion, Emails)。
### 第三層：新型態的內容與行銷 (AEO)
* **AEO (AI Engine Optimization)** 是未來的 SEO。當人們不再 Google，而是直接問 ChatGPT 或 Perplexity，內容創作者必須確保他們的資訊是結構化、精確且容易被 AI 抓取並引用的。
---
## 🧠 ROUND 3: 靈魂提取 (XRay Extractor)
### 本質 (Essence)
「未來的核心競爭力不在於你『會做什麼』，而在於你『能指揮系統自動完成什麼』。」
### 遷移 (Transfer)
* **個人職涯發展**：不要停留在「使用 ChatGPT 寫報告」的階段。應該嘗試結合 RAG (你的個人筆記) 與 Workflow (自動排程發布)，建立個人自動化系統。
* **軟體開發**：開發者需要轉型，從編寫 CRUD 應用程式，轉變為編排 AI Agents、整合 MCP 以及優化 RAG 檢索。
---
## 🏗️ Architectural Deep Dive (架構師深研)
**Agentic AI vs Rule-based Automation (代理化 AI 與基於規則的自動化的差異)**
這篇文章很好地劃分了 Automation (第 3 點) 與 Agentic AI (第 4 點) 的邊界，這也是許多架構師在設計系統時容易混淆的地方。
1. **Workflow Automation (如 Zapier/Make)**：
* **特性**：If-This-Then-That (ITTT)。確定性高，路徑固定。
* **限制**：如果遇到例外狀況 (資料格式錯誤、找不到預期欄位)，工作流就會崩潰 (Crash) 並停止。
2. **Agentic AI (思考型代理)**：
* **特性**：Goal-Oriented (目標導向)。你給定目標，AI 自己規劃路徑 (Plan)、執行 (Act)、反思 (Reflect)。
* **優勢**：具備「容錯與自我修正」能力。如果在抓取資料時發現格式錯誤，它可以自動呼叫 Python 寫一個正則表達式修正，然後繼續下一步。
3. **混合架構 (Hybrid Architecture)**：
未來的企業系統是兩者的堆疊 (Tool Stacking)。
在**骨幹流程**上使用確定性的 Workflow Automation 確保穩定性與稽核性，在**流程節點 (Nodes)** 內嵌入 Agentic AI 來處理非結構化資料的決策與例外狀況處理。
Obsidian 整理
原始文章
認知思維
別把學習外包出去 (Don't Outsource Your Learning)
"過度依賴 AI 直接產生程式碼來「關閉任務」，正在無形中累積工程師的「認知債務」；我們必須刻意在工作流中引入摩擦，用 AI 來驗證假設而非取代思考。"
Top 5 Insights
- **工具無罪，姿態決定一切**：AI 既能產生認知債務，也能成為最強的學習輔導員，完全取決於你在對話框中向它要求了什麼。
- **區分交付與學習指標**：管理層只看交付率，但工程師必須為自己的學習率負責。
- **選擇性委託**：對於無關緊要的樣板程式碼或一次性 CI 腳本，果斷使用純委託；但對於系統的核心業務邏輯與架構設計，絕對不能把思考過程外包。
---
tags: [認知思維, 職場技能, 學習方法, 認知債務, AI工具]
date: 2026-05-19
read: false
source: "2026-05-19T092653+0800-别把学习外包出去.md"
---
# 別把學習外包出去 (Don't Outsource Your Learning)
原始來源與檔名：2026-05-19T092653+0800-别把学习外包出去.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 認知債務 = (依賴 AI 產出量) - (主動理解與重構的次數)
### 一句話
> 過度依賴 AI 直接產生程式碼來「關閉任務」，正在無形中累積工程師的「認知債務」；我們必須刻意在工作流中引入摩擦，用 AI 來驗證假設而非取代思考。
### 餐巾紙草圖
```text
[預設迴圈] 貼上報錯 -> AI 給解法 -> 關閉任務 (認知退化)
[學習迴圈] 提出假設 -> AI 給解釋與解法 -> 驗證與重構 -> 內化知識 (認知升級)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼頻繁使用 AI 寫程式，反而會讓工程師在沒有 AI 輔助時的能力逐漸退化？
- **核心答案**: 因為 AI 工具的預設 UX 是優化「任務完成率 (關閉任務)」而非「學習」。跳過了試錯與摩擦的過程，會阻礙心智模型的建立，形成「認知債務」。
- **論證結構**: 提出現象 -> 數據佐證 -> 分析崩潰點 -> 提出解法。
### 章節骨架
1. **預設的陷阱**: AI 取代了使用者的判斷，用未來的能力換取當下的速度。
2. **科學實證**: Anthropic 與 MIT 的研究證明了純靠 AI 寫出內容的人，其腦部連結度下降，且無法理解自己剛才產出的內容。
3. **純委託的 5 大崩潰點**: 除錯困難、AI 自信出錯、系統底層變更、脫離常規場景、市場價值重估。
4. **與 AI 共學的 6 種姿態**: 先有假設再問 AI、先要解釋再要程式碼、開啟學習模式、將 AI 當作初級工程師 Review、手動重構、讓模型解釋架構決策。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 學習必須伴隨著一定程度的「認知摩擦 (Cognitive Friction)」。太過絲滑的體驗會阻斷大腦神經連結的強化。
- **邊界條件**: 若任務屬於免洗腳本、樣板程式碼或是此生不再維護的膠水層，產生認知債務的成本很低，此時「純委託 (Pure Delegation)」反而是理性的選擇。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 與技術債 (Technical Debt) 的概念高度相似；這是一場關於「工具決定論」與「主體性」的拔河。
- **深層洞見**: 摩擦正是學習所在的地方 (Friction is where learning happens)。軟體的價值不在於程式碼本身，而在於工程師腦中那套能應對系統變更與架構遷移的心智模型。
- **行動呼籲**: 每次結束工作階段時問自己：「我今天學到了什麼，還是只是關閉了問題？」寧願只交付 80% 但學到 100%，也不要盲目依賴 AI。
---
# 別把學習外包出去 (Architectural Deep Dive)
## 前言/背景
隨著 AI 編程助手 (如 Copilot, Claude) 普及，工程師的開發速度大幅提升。然而，本文警告過度依賴 AI 的「預設迴圈」會產生嚴重的「認知債務 (Cognitive Debt)」。如果只把 AI 當作解答機來「關閉任務」，工程師的心智模型將停滯不前，一旦脫離常規場景或系統底層發生變更，將徹底失去架構掌控力。
## 章節詳細總結
### 認知債務的科學實證 (研究怎麼说)
* **Anthropic 實驗**：在使用 AI 學習新庫的實驗中，AI 組與手動組速度相當，但 AI 組在後續的理解測試中慘敗 (50% vs 67%)。進一步分析發現：**用 AI 問概念的人得分超過 65%，而直接複製貼上程式碼的人得分低於 40%**。這證明「使用工具的姿態決定了結果」。
* **MIT 研究**：透過 EEG 測量，發現引入 LLM 會讓大腦連接性下降。高達 83% 的 LLM 使用者無法解釋他們剛剛生成的內容。今天節省的腦力，明天必須為喪失的批判性思維買單。
### UX 引力與預設陷阱 (默认的陷阱)
現在的產品團隊與 AI 工具都在為「減少摩擦」與「完成任務」進行最佳化。工具不會停下來問你「你認為問題出在哪？」
然而，**摩擦正是學習所在的地方**。我們必須刻意抵抗這種 UX 引力，主動尋求理解，而不是單純地追求更少的鍵盤敲擊次數。
### 純委託架構在真實軟體工程中的 5 大崩潰點 (什么时候纯委托会崩溃)
對於核心系統，把思考全包給 AI 會在以下情境徹底崩潰：
1. **當系統壞了**：AI 寫的 Code 依然會崩潰，團隊中必須有人對整體架構擁有心智模型才能除錯。
2. **當 AI 自信地給出錯誤答案 (幻覺)**：對抗看似合理的錯誤，唯一的防禦機制是人類自身的專業知識與架構直覺。
3. **系統底層遷移**：程式碼是暫時的，但系統架構是長存的。框架升級或安全性重構無法單靠「重新下 Prompt」解決，必須依賴理解系統的工程師來執行。
4. **脫離中位數問題 (Edge cases)**：AI 擅長處理 GitHub 上重複出現百萬次的問題。越偏離常規、缺乏文檔的深層領域，AI 表現越差，這正是高階工程師薪水的價值所在。
5. **市場價值重整**：只會用 AI 交付的工程師將失去競爭力。
### 與 AI 共學的 6 種架構師姿態 (六种用 AI 学习的方法)
1. **先形成假設**：在把報錯丟給 AI 之前，先寫下自己對錯誤的推論。用 AI 來驗證你的理論，而非取代它。
2. **先要解釋，再要程式碼**：面對未知領域，第一個 Prompt 應該是：「解釋運作原理與架構權衡 (Tradeoffs)」，理解後再讓它寫 Code。
3. **啟用學習模式**：主動要求 AI 使用蘇格拉底式提問，強迫自己思考。
4. **把 AI 當作初級工程師的 PR**：用嚴苛的 Code Review 標準審視 AI 的產出，不要因為測試通過就盲目 Merge。
5. **手動重新推導 (Re-implementation)**：拿 AI 寫的精巧片段，嘗試從頭自己寫一次，校準自己喪失的理解力。
6. **讓模型解釋設計決策**：當 AI 給出解法後，反問它「你為什麼做這個架構選擇？」
## 總結與結論
* **工具無罪，姿態決定一切**：AI 既能產生認知債務，也能成為最強的學習輔導員，完全取決於你在對話框中向它要求了什麼。
* **區分交付與學習指標**：管理層只看交付率，但工程師必須為自己的學習率負責。
* **選擇性委託**：對於無關緊要的樣板程式碼或一次性 CI 腳本，果斷使用純委託；但對於系統的核心業務邏輯與架構設計，絕對不能把思考過程外包。
Obsidian 整理
原始文章
認知思維
為什麼 AI 時代，別追網紅，要追 Builder (Follow Builders, Not Influencers)
"不要沉溺於網紅製造的「AI 將顛覆一切」的宏大敘事與認知消費中；去關注那些每天在泥濘中修 Bug、寫 Landing Page、承受上線無人問津卻依然持續迭代的實踐者 (Builder)，因為真實世界的反饋遠比空談趨勢重要。"
Top 5 Insights
- **轉移注意力核心**：減少關注抽象的「未來職業預測」，轉向追蹤 X 上的 `#buildinpublic` 或 Indie Hackers 上的實戰覆盤。
- **接受緩慢與挫折**：理解並接受「做了二十個產品才賺錢」的現實，拒絕被爆發式增長的神話綁架。
- **終極競爭力**：在 AI 時代，拉開人與人差距的早已不是「誰懂的名詞多、誰最懂趨勢」，而是「誰真正開始動手寫下第一行代碼」。
---
tags: [認知思維, 職涯發展, Builder, AI時代, 獨立開發]
date: 2026-05-19
read: false
source: "2026-05-19T092731+0800-为什么AI 时代，别追网红，要追 Builder.md"
---
# 為什麼 AI 時代，別追網紅，要追 Builder (Follow Builders, Not Influencers)
原始來源與檔名：2026-05-19T092731+0800-为什么AI 时代，别追网红，要追 Builder.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 真正的 AI 護城河 = (動手實作的髒活 + 解決枯燥的真實痛點 + 失敗覆盤) > 宏大的趨勢焦慮
### 一句話
> 不要沉溺於網紅製造的「AI 將顛覆一切」的宏大敘事與認知消費中；去關注那些每天在泥濘中修 Bug、寫 Landing Page、承受上線無人問津卻依然持續迭代的實踐者 (Builder)，因為真實世界的反饋遠比空談趨勢重要。
### 餐巾紙草圖
```text
[追隨網紅] 聽取宏大趨勢 -> 產生 FOMO 焦慮 -> 收藏一堆名詞 (MCP, Agent) -> 什麼都沒做
[追隨 Builder] 看見具體痛點 -> 動手寫個破爛小工具 -> 獲得第一筆真實付費 -> 在真實市場中迭代成長
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 在 AI 資訊爆炸的時代，為什麼大量關注趨勢分析與未來預測，反而會讓人陷入焦慮且難以真正採取行動？
- **核心答案**: 網紅提供的是「認知消費品」，讓人產生理解時代的錯覺；而 Builder (實踐者) 提供的是真實、具體、甚至充滿挫折的工程經驗。只有停止圍觀、親自動手，才能跨越認知與實踐的鴻溝。
- **論證結構**: 現象點題 -> 對比網紅與 Builder -> Builder 的真實市場洞察 -> Builder 的狼狽日常 -> 行動呼籲。
### 章節骨架
1. **認知消費的陷阱**: 每天高強度關注 AI 資訊，卻發現自己什麼都沒做。
2. **網紅 vs. Builder**: 網紅講趨勢與情緒放大，Builder 講「這東西怎麼做」以及「真實需求是什麼」。
3. **真實商業的樸素**: 用戶不會為「AGI 感」買單，反而願意為「自動整理 SKU 表格」這種省時間的枯燥工具付費。
4. **不光鮮的日常**: 熬夜上線後沒人看、支付流程壞掉、廣告零轉化。這些「失敗經驗」比成功學有價值百倍。
5. **別只圍觀，開始動手**: 能力是做出來的，不是準備出來的。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 市場上存在著嚴重的「偽需求」錯覺。開發者常以為使用者想要酷炫的 AI 生成能力，但真實企業痛點往往是極度無聊的資料清洗與流程自動化。
- **邊界條件**: 關注 Builder 並不是否認趨勢分析的價值，而是在度過最初的「視野拓寬期」後，必須強制自己將注意力轉移到執行層面，否則就會淪為純粹的資訊成癮者。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 呼應精實創業 (Lean Startup) 的 MVP 理念，以及「Build in Public」的開源精神。
- **深層洞見**: 網紅販賣的是未來的完美幻象，Builder 展露的是當下的狼狽現實。能夠接受「上線第一天只有十幾個訪問量」的失落感，是一個人真正進入「做事情」世界的必經儀式。
- **行動呼籲**: 立刻去 X 或 Indie Hackers 上追蹤 `#buildinpublic`，寫一個自動化小腳本，並誠實記錄一次產品失敗的覆盤。
---
# 為什麼 AI 時代，別追網紅，要追 Builder (Architectural Deep Dive)
## 前言/背景
在 AI 熱潮中，社群媒體充斥著焦慮製造者與趨勢預言家。本文作者深刻反思了這種「高強度關注卻零產出」的怪圈。文章指出，過度消費宏大敘事只會讓人停留在「準備中」的幻覺。要在 AI 時代真正立足，必須將注意力轉向那些默默修 Bug、承受失敗、解決真實痛點的獨立開發者 (Builder)，並親自下場弄髒雙手。
## 章節詳細總結
### 認知消費品的陷阱 (网红讲趋势)
網紅的內容具有極高的感染力，能迅速普及概念 (如 Agent, RAG)。但這些內容本質上是「認知消費品」。讀者在閱讀時會產生一種「我已經掌握時代脈搏」的顱內高潮與緊迫感，但因為缺乏具體的執行路徑，最終這些觀點永遠不會轉化為行動。
### 真實市場的樸素需求 (Builder 讲怎么做)
與網紅口中「改變世界」的 AI 應用不同，Builder 面對的是極度骨感的真實市場。
* **案例 1**：開發者原本想做宏大的 AI 寫作工具，無人買單；最後靠一個極其無聊的「幫電商賣家整理 SKU 表格」的小工具獲得了穩定收入。
* **案例 2**：想做生態級平台失敗，最後靠「自動整理會議錄音為客戶紀要」活了下來。
* *核心洞見*：真實的付費需求往往毫無「AGI 感」，它們不過是在幫別人省下 10 分鐘的枯燥重複勞動。
### 剝去浪漫外衣的開發日常 (远没有想象中光鲜)
網路將獨立開發包裝成「喝咖啡收美金」的數位遊牧神話。但 Builder 的真實日常充滿了狼狽：半夜查介面報錯、廣告投放零轉化、以及最經典的打擊——**熬夜兩週上線後，後台只有十幾個訪問量 (其中一半還是自己測試的)**。
真正有價值的分享，不是「三個月 ARR 十萬美元」的倖存者偏差，而是那些坦承自己產品沒人用、默默關掉伺服器的失敗覆盤。
### 能力是做出來的 (别只围观，开始动手)
許多人總是以為自己「還沒準備好」，所以遲遲不動手。但真實世界的運作法則是：你不發布一個破爛產品，就永遠不知道什麼是使用者反饋；你不去踩坑，就永遠無法理解技術名詞背後的工程代價。
## 總結與結論
* **轉移注意力核心**：減少關注抽象的「未來職業預測」，轉向追蹤 X 上的 `#buildinpublic` 或 Indie Hackers 上的實戰覆盤。
* **接受緩慢與挫折**：理解並接受「做了二十個產品才賺錢」的現實，拒絕被爆發式增長的神話綁架。
* **終極競爭力**：在 AI 時代，拉開人與人差距的早已不是「誰懂的名詞多、誰最懂趨勢」，而是「誰真正開始動手寫下第一行代碼」。
Obsidian 整理
原始文章
認知思維
為什麼我不「憑感覺編程」 (Why I Don’t Vibe Code)
"AI 只能解決「偶然複雜度」，但消除所有「摩擦」的代價，是喪失對「本質複雜度」的理解與掌控；真正的編程不僅是產出程式碼，更是一種建構抽象模型與承擔道德責任的社會實踐。"
Top 5 Insights
- **不要神化 AI 工具**：AI 是降低偶然複雜度的利器，但它絕不是軟體工程的「銀彈」。
- **擁抱心智摩擦**：保留對程式設計的熱愛，將克服困難視為建立心智模型與架構直覺的必要修煉。
- **堅守專業底線**：在系統崩潰或造成社會傷害時，沒有人可以把責任推給「提示詞寫得不好」。軟體工程師必須對自己設計的抽象模型負起最終的道德責任。
---
tags: [認知思維, 軟體工程, Vibe Coding, AI反思, 系統複雜度]
date: 2026-05-19
read: false
source: "2026-05-19T092706+0800-为什么我不“凭感觉编程”.md"
---
# 為什麼我不「憑感覺編程」 (Why I Don’t Vibe Code)
原始來源與檔名：2026-05-19T092706+0800-为什么我不“凭感觉编程”.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 軟體開發的真實價值 = 本質複雜度的克服 + 透過摩擦建立的深刻理解 + 道德與責任感的承擔
### 一句話
> AI 只能解決「偶然複雜度」，但消除所有「摩擦」的代價，是喪失對「本質複雜度」的理解與掌控；真正的編程不僅是產出程式碼，更是一種建構抽象模型與承擔道德責任的社會實踐。
### 餐巾紙草圖
```text
[Vibe Coding] 消除摩擦 -> 無意識生成 -> 喪失架構直覺與技術掌控力 (盲目飛行)
[傳統編程] 擁抱摩擦 -> 深入思索抽象與邊界 -> 獲得深層理解與架構演進 (建立心智模型)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼在 AI 時代「憑感覺編程 (Vibe Coding)」被吹捧為未來，但資深工程師卻拒絕這種無摩擦的開發方式？
- **核心答案**: 因為消除摩擦的同時也消除了學習。LLM 無法處理軟體工程中的「本質複雜度」，缺乏後設認知 (Meta-cognition)，無法為程式碼負責，且會摧毀團隊協作的意義與樂趣。
- **論證結構**: 經驗反思 -> 理論支撐 (人月神話) -> 數據陷阱分析 -> 價值觀辯護。
### 章節骨架
1. **本質與偶然的二元對立**: AI 只解決了敲鍵盤的「偶然複雜度」，卻無法應對設計優雅系統的「本質複雜度」。
2. **抽象的盲點**: 程式設計是簡化現實的過程。LLM 無法跳脫模型本身去思考「什麼被遺漏了」(缺乏後設認知)。
3. **摩擦是上天的恩賜**: 在死磕程式碼與架構決策 (ADR) 的「摩擦」中，我們才學會了「為什麼這樣設計」而非僅僅是「寫出程式碼」。
4. **道德外包的荒謬**: AI 沒有意識，不會懊悔。把開發變成純粹的指令生成，是在逃避對產品與社會的個人道德責任。
5. **反烏托邦的工作文化**: Vibe Coding 的倡導者並未用省下的時間去享受生活，反而擁抱了更病態的自我壓榨 (996)。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 軟體的價值在於解決人類真實世界的問題，這需要高度的同理心、脈絡感知與責任感，而這些是基於統計學機率的 LLM 永遠無法具備的。
- **邊界條件**: 若任務是縮放圖片、寫樣板程式碼或是一次性腳本，AI 的確極其高效；但若涉及核心架構設計、牽涉公眾利益的資料分析，AI 的幻覺與缺乏常識將帶來災難。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 呼應 Fred Brooks 在《人月神話》中提出的「沒有銀彈 (No Silver Bullet)」理論；以及技術官僚主義將複雜現實強行量化的危害。
- **深層洞見**: 摩擦 (Friction) 不是系統的 Bug，而是學習的 Feature。如果 LLM 把所有苦差事都代勞了，工程師將淪為只能閱讀而無法創作的技術文盲，留下無人能理解的「AI 屎山」。
- **行動呼籲**: 不要把大腦外包給機器。在遇到困難時，強迫自己停下來寫架構決策紀錄 (ADR)；把編程視為一種創造力的表達，拒絕讓渡這份純粹的快樂與責任。
---
# 為什麼我不「憑感覺編程」 (Architectural Deep Dive)
## 前言/背景
近期科技圈熱炒「憑感覺編程 (Vibe Coding)」，鼓吹完全依賴 LLM 自動生成應用程式的烏托邦。本文作者 (資深開發者 Jacob Harris) 從根本上反駁了這種去脈絡化的開發狂熱。他指出，編程不只是製造會動的程式碼，更是透過「抽象」理解世界的過程。過度依賴 AI 將剝夺開發者與系統「摩擦」中產生的深刻理解，並將最終的道德責任與工程紀律消解於無形。
## 章節詳細總結
### 複雜度的永恆難題 (偶然複雜度 vs. 本質複雜度)
* **偶然複雜度 (Accidental Complexity)**：撰寫語法、編譯流程、API 調用。這些確實是繁瑣的勞動，AI 就像更高級的編譯器，極大地削弱了這部分的負擔。
* **本質複雜度 (Essential Complexity)**：設計出正確、優雅、可維護的系統架構，處理現實世界中詭異且混亂的邊緣案例。**這項挑戰永遠不會消失**。LLM 無法解釋它為何選擇特定架構，也無法應對無法直接套用標準答案的複雜性。
### 缺乏後設認知的 AI 陷阱 (抽象的遮蔽性)
* **抽象即遮蔽**：寫程式的本質是建立抽象模型（如把森林抽象為木材產量）。但每次抽象必定會丟棄部分現實。人類開發者 (如資料記者) 會隨時保持警覺，質問數據背後隱藏了什麼。
* **LLM 的視角極限**：LLM 無法進行後設認知 (Meta-cognition)。對它而言，字元標記 (Tokens) 就是整個現實。它無法意識到資料的荒謬性，只會盲目迎合使用者的偏見（例如 DOGE 錯誤分析社會安全局數據的案例）。
### 摩擦是工程師的導師 (摩擦是上天的恩赐)
* **摩擦即回饋**：當寫程式感覺極度困難時，這不是在呼喚 AI 幫忙硬幹，而是一個**架構警報**，提醒你設計方向走偏了。
* **知其所以然**：在陌生的程式碼中「泡著入味」是必須的。如果你只看 AI 生成的總結，你只知道系統「做了什麼」，卻永遠無法理解設計者「為什麼這麼做」。
* **沒有 ADR 的災難**：LLM 面對摩擦的解法是「強行生成代碼」。最終留下的只是一堆難以理解的抽象邏輯，以及幾行無法逆向工程的 Prompt，徹底摧毀了系統的長期可維護性。
### 協作的溫度與道德的重量 (责任感太关键了)
* **不可推卸的責任**：軟體系統深刻影響著公眾生活。LLM 只是一個把字詞機率性串聯的統計模型，它沒有意識，不會感到懊悔。將開發工作全盤交由 LLM，等同於逃避人類的道德責任。
* **軟體工程是社會實踐**：砍掉團隊中的 PM、設計師與審查機制，換上 AI 幽靈，或許能極速發布產品，但這不僅會讓產品質量下降，更會讓開發過程變得極度孤獨與病態（諷刺的是，省下的時間反而被用來進行更深度的自我壓榨 996）。
## 總結與結論
* **不要神化 AI 工具**：AI 是降低偶然複雜度的利器，但它絕不是軟體工程的「銀彈」。
* **擁抱心智摩擦**：保留對程式設計的熱愛，將克服困難視為建立心智模型與架構直覺的必要修煉。
* **堅守專業底線**：在系統崩潰或造成社會傷害時，沒有人可以把責任推給「提示詞寫得不好」。軟體工程師必須對自己設計的抽象模型負起最終的道德責任。
Obsidian 整理
原始文章
量化交易
馬可夫鏈：量化交易員在 Polymarket 碾壓 87% 玩家的核武級演算法 (Markov Chains on Polymarket)
"Polymarket 上 87% 虧錢的散戶靠直覺下注，而頂尖的 13% 量化玩家則將市場視為「馬可夫鏈」，透過歷史價格矩陣與萬次蒙地卡羅模擬算出真實機率，並永遠以掛單 (Limit Order) 收割散戶的「樂觀稅」。"
---
tags: [量化交易, AI研究, 機率統計, Polymarket, 預測市場]
date: 2026-05-19
read: false
source: "2026-05-19T093032+0800-Markov Chains nuclear algorithm used by Quants to crush 87% of Polymarket traders.md"
---
# 馬可夫鏈：量化交易員在 Polymarket 碾壓 87% 玩家的核武級演算法 (Markov Chains on Polymarket)
原始來源與檔名：2026-05-19T093032+0800-Markov Chains nuclear algorithm used by Quants to crush 87% of Polymarket traders.md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 預測市場勝率 = 馬可夫狀態轉移矩陣 (尋找真實機率) + 蒙地卡羅模擬 (評估期望值) + Maker 模式 (+1.12% 優勢) - 樂觀稅 (長尾偏見校正)
### 一句話
> Polymarket 上 87% 虧錢的散戶靠直覺下注，而頂尖的 13% 量化玩家則將市場視為「馬可夫鏈」，透過歷史價格矩陣與萬次蒙地卡羅模擬算出真實機率，並永遠以掛單 (Limit Order) 收割散戶的「樂觀稅」。
### 餐巾紙草圖
```text
[價格狀態轉移矩陣 (Markov Chain)]
State 4 (40-50¢): 40% 機率不動, 25% 往上, 15% 往下...
|
v
[Monte Carlo Simulation] 模擬 10,000 次未來路徑
|
v
[長尾校正] 散戶偏愛買極低機率的 YES (樂觀稅)，導致 1¢ 的合約實際勝率僅 0.43%
|
v
[執行] Maker (掛單) 賺取流動性溢價 (+1.12%)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼在 Polymarket 這類預測市場中，絕大多數人都在賠錢？頂尖的量化交易員是如何建立數學模型的？
- **核心答案**: 量化交易員使用源自 1906 年的「馬可夫鏈 (Markov Chain)」建立價格狀態轉移矩陣，結合蒙地卡羅模擬推算合約的真實勝率，並利用大數據揭示的「長尾偏見 (Longshot Bias)」與「Maker/Taker 利差」進行無情套利。
- **論證結構**: 歷史科普 (馬可夫鏈的誕生與核彈模擬) -> 演算法核心 (狀態矩陣與蒙地卡羅) -> 7,200萬筆交易的數據洞見 (長尾偏見與樂觀稅) -> 給交易員的 5 步系統指南。
### 章節骨架
1. **歷史淵源 (1906-1998)**: 從俄國數學家馬可夫用《葉甫蓋尼·奧涅金》證明相依事件的大數法則，到核彈研發的蒙地卡羅模擬，再到 Google 價值 2 兆美元的 PageRank，底層全是同一個數學邏輯。
2. **第一步：建立馬可夫模型**: 將 0-100¢ 的價格離散化為 10 個狀態，透過歷史盤口計算出「轉移矩陣 (Transition Matrix)」。
3. **第二步：蒙地卡羅模擬**: 寫 Python 代碼，根據轉移矩陣模擬 10,000 條未來價格路徑，統計最終達到 YES (100¢) 的比例，即為真實機率。
4. **大數據洞見 (7,200萬筆交易分析)**:
- *長尾偏見 (Longshot Bias)*: 極低價合約 (如 5¢) 被嚴重高估，實際勝率極低。
- *Maker/Taker 財富轉移*: 掛單 (Maker) 賺 1.12%，吃單 (Taker) 賠 1.12%。
- *樂觀稅 (Optimism Tax)*: 散戶盲目買 YES，導致在極低價位時，買 NO 的報酬遠超 YES。
5. **5 步量化系統**: 建模 -> 模擬 -> 校正偏見 -> Kelly 倉位控制 -> 限定 Limit Orders。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 市場價格雖然是隨機遊走，但在微觀結構上存在可被捕捉的「轉換機率分佈」特性，且散戶的情緒性溢價 (長期喜愛做多極端小機率事件) 具有高度的統計穩定性。
- **邊界條件**: 這種基於歷史狀態轉移的量化模型，在遇到「突發且決定性的現實事件 (如候選人突然退選)」時會瞬間失效，因為歷史矩陣無法預測突發的外部強特徵斷崖式暴跌。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 賭博機率學的凱利公式 (Kelly Criterion)、量化交易的高頻微觀結構，以及行為金融學中的「樂透效應 (Lottery Effect)」。
- **深層洞見**: **交易不是預測未來，而是捕捉機率的錯價。** 散戶在 Polymarket 買的是「希望 (YES)」，而量化機器人則是作為莊家，提供流動性並收取這筆「樂觀稅」。
- **行動呼籲**: 如果要在 Polymarket 交易，請立刻停止使用 Market Order。永遠掛 Limit Order (做 Maker)，並且在合約價格低於 30¢ 時，優先尋找做空 (買 NO) 的機會。
---
# 馬可夫鏈：量化交易員的核武級演算法 (Architectural Deep Dive)
## 前言/背景
Polymarket (加密貨幣預測市場) 上有 87% 的散戶處於虧損狀態，而頭部的 13% 量化機器人 (如 RN, ColdMath, Sharky6999) 則捲走了數百萬美元的利潤。本文從 1906 年俄國數學家馬可夫的恩怨史切入，揭示了串起核彈模擬、Google 搜尋引擎，以及預測市場致勝策略的終極方程式：馬可夫鏈 (Markov Chains) 結合蒙地卡羅模擬 (Monte Carlo Simulation)。
## 章節詳細總結
### 歷史軌跡：從詩歌到核彈再到 Google
* **馬可夫鏈 (1906)**：為了反駁神學家對「大數法則」的誤用，馬可夫計算了普希金詩作中的字母排列，證明了即使是**相依事件 (下一個狀態依賴於上一個狀態)**，依然符合統計收斂。這成為了預測市場價格跳動的基礎模型。
* **蒙地卡羅模擬 (1946)**：為了解決核彈中無限多種中子反應的運算難題，Stanislaw Ulam 發明了利用電腦執行上萬次隨機模擬來「逼近真實機率」的方法。
* **PageRank (1998)**：Google 將整個網際網路視為巨大的馬可夫鏈，網頁是狀態，超連結是轉移機率，成就了 2 兆美元的帝國。
### 量化策略實作：建模與模擬 (Model & Simulation)
這套在 Polymarket 殺爆散戶的演算法，本質上只有幾行 Python 代碼：
1. **狀態轉移矩陣 (Transition Matrix)**：將 0¢ 到 100¢ 的價格切分為 10 個區間 (狀態)。讀取過去 30-60 天的價格，計算出每個狀態轉移到另一個狀態的機率。例如：`從 40-50¢ 的區間，有 40% 機率不動，25% 往上，15% 往下。`
2. **蒙地卡羅模擬**：從當前價格狀態出發，根據上述機率矩陣向前「隨機漫步」數十天。重複此動作 10,000 次，統計最終停留在 100¢ (YES 結算) 的次數比例，這就是模型的「理論真實勝率」。只要理論勝率與市場現價有落差，就存在套利空間 (Edge)。
### 7,200 萬筆交易揭示的底層真相 (Data Insights)
研究員 Jonathan Becker 分析了 182 億美元的交易資料，揭露了量化機器人獲利的四大基石：
1. **長尾偏見 (Longshot Bias)**：散戶極度熱衷於買廉價合約。市場定價 1¢ 的合約，理論上應有 1% 的勝率，但實際只有 0.43%。把錢砸在 1¢ 合約上，期望值比賭場老虎機還低。
2. **Maker/Taker 財富轉移**：Maker (掛單提供流動性) 平均每筆賺取 1.12% 的優勢，而 Taker (吃單) 則穩定虧損 1.12%。兩者差距高達 2.24%。
3. **娛樂區的暴利**：體育、娛樂這類充滿粉絲情緒的分類，Maker 的獲利空間最高 (高達 7.32%)；而金融分類因為多為專業人士，市場極度有效率。
4. **樂觀稅 (Optimism Tax)**：在低價位區 (30¢ 以下)，散戶不理性地偏愛買 YES (支持自己的隊伍/信仰)。數據顯示，在這些區位買 NO 的報酬率遠超 YES。
## 總結：5 步量化執行系統
1. **建立馬可夫模型**：捕捉市場真實的狀態轉移機率。
2. **運行蒙地卡羅模擬**：獲取理論勝率。
3. **對抗偏見進行校正**：將模擬結果根據「長尾偏見」數據進行向下調整。
4. **凱利公式 (Kelly Criterion) 控倉**：建議使用 Quarter-Kelly (0.25x) 以保護本金。
5. **只用 Limit Orders (掛單) 交易**：絕不支付 Taker 費用，永遠站在收割流動性溢價 (Maker) 的莊家一方。
Obsidian 整理
原始文章
開發工具
Google 釋出 13 個 Agent Skills：代理基礎設施的標準化時刻 (Google's 13 Official Agent Skills)
"Google 官方發布了基於 Anthropic 開源格式的 Agent Skills 庫，這不僅解決了 AI 代理總是引用過期 SDK 的問題，更宣告了「跨平台 Agent 知識注入標準」的確立。"
Top 5 Insights
- **品質躍升的真相**：Google 官方稱這套 Skill 讓代碼準確率飆升至 87%~96%。這並非模型變聰明了，而是模型終於「讀到了對的操作手冊」。
- **產業趨勢**：未來的開發文檔將不只是寫給人類看的，更是寫給 Agent 掛載的。
- **強烈建議**：所有在 Google Cloud 上部署 Agent 工作流的開發者，應立即安裝此官方技能庫，以確保生成的代碼永遠符合最新規範與最佳實踐。
---
tags: [開發工具, Agent架構, Gemini, 系統整合, 標準化]
date: 2026-05-19
read: false
source: "2026-05-19T093036+0800-Google Just Shipped 13 Agent Skills. I Plugged Them Into Gemini CLI and Watched Code Quality Jump..md"
---
# Google 釋出 13 個 Agent Skills：代理基礎設施的標準化時刻 (Google's 13 Official Agent Skills)
原始來源與檔名：2026-05-19T093036+0800-Google Just Shipped 13 Agent Skills. I Plugged Them Into Gemini CLI and Watched Code Quality Jump..md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 程式碼正確率 (87%~96%) = 基礎模型能力 + 漸進式上下文展開 (Progressive Disclosure) + 標準化 Agent Skills 格式
### 一句話
> Google 官方發布了基於 Anthropic 開源格式的 Agent Skills 庫，這不僅解決了 AI 代理總是引用過期 SDK 的問題，更宣告了「跨平台 Agent 知識注入標準」的確立。
### 餐巾紙草圖
```text
[未安裝 Skill]
Prompt -> 模型大腦 -> 撈取過時訓練資料 (幻覺/舊版 SDK) -> 產出不可用的爛 Code
[安裝官方 Skill 後]
Prompt -> 比對 13 個 Skill 描述 -> 觸發 `gemini-api` -> 動態載入 `references/` 官方文件
-> 產出包含 Pydantic Schema 的最新高階架構 Code
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 為什麼即使是最新的 AI 模型，在呼叫各家雲端 API 時，依然經常給出廢棄 (Deprecated) 的 SDK 用法或初階的範例代碼？如何解決上下文過載的問題？
- **核心答案**: 因為模型的訓練資料被過去幾年的舊代碼污染。Google 透過官方釋出 13 個 Agent Skills，採用「漸進式展開」機制，只在需要時將最新的官方文件動態注入 Context。更具指標意義的是，Google 採用了 Anthropic 制定的開源 Skill 格式，促成了生態系的標準化。
- **論證結構**: 破題 (一個安裝指令改變代碼品質) -> 盤點 13 個官方 Skills -> 對比實測 (Gemini API 寫作與 BigQuery 最佳化) -> 解析底層架構 (漸進式展開) -> 探討行業標準化的戰略意義。
### 章節骨架
1. **背景**: Google Cloud Next 2026 釋出 `github.com/google/skills`，只需一行 `gemini skills install` 即可載入。
2. **內容盤點**: 包含 7 個產品技能 (AlloyDB, BQ 等)、3 個架構技能 (資安、可靠性、成本)、3 個腳本技能。
3. **Demo 1 (API 開發)**: 無 Skill 時，模型使用廢棄的 `vertexai` 模組；啟用 Skill 後，模型能寫出基於 `google-genai` 且包含 Pydantic Schema 的現代化代碼。
4. **Demo 2 (BQ 成本最佳化)**: 無 Skill 時給出 Stack Overflow 等級的廢話；啟用 Skill 後，交出一份包含分區、物化視圖與計費模式的企業級 FinOps 架構方案。
5. **架構亮點 (Progressive Disclosure)**: 13 個技能平時只佔極少 Token，當命中描述時，才會提示授權並載入龐大的 Markdown 參考文件，徹底解決 Context Bloat (上下文膨脹) 問題。
6. **行業標準確立**: Google 採用 Anthropic 的開源格式，這意味著同一份 Skill 文件可以直接在 Claude Code, Codex, Gemini CLI 中無縫運行。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: AI 代理能力的瓶頸已經不是「模型智商」，而是「知識傳遞通道的精準度」。提供高品質的最新文件比擴增模型的參數量更能立竿見影地提升產出。
- **邊界條件**: 這種漸進式展開依賴於模型能從簡短的 description 中正確判斷是否需要呼叫該 Skill。如果使用者的 Prompt 過於模糊，可能無法觸發正確的技能載入。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 呼應微服務架構中的 Sidecar 模式 (外掛提供能力)，以及 MCP (Model Context Protocol) 解決「動作存取」與 Skills 解決「知識傳遞」的互補關係。
- **深層洞見**: 這是一場無聲的基建革命。三大實驗室 (Anthropic, HuggingFace, Google) 共用一套 Skill 格式，這代表著**「軟體文件 (Documentation) 的受眾正式從人類轉向機器 (Agents)」**。未來雲端廠商發布新功能，第一步將是發布 Agent Skill 庫。
- **行動呼籲**: 如果你使用 Google Cloud 開發，立刻在終端執行 `gemini skills install https://github.com/google/skills.git`。如果你在開發跨平台系統，請開始使用這套標準格式來撰寫你內部專案的 API 文件。
---
# Google 釋出 13 個 Agent Skills (Architectural Deep Dive)
## 前言/背景
在 Google Cloud Next 2026 大會上，Google 悄悄發布了一個震撼 Agent 開發圈的更新：官方釋出了包含 13 個產品與架構實踐的 Agent Skills 程式庫。作者實測後發現，載入這些技能不僅讓 Gemini CLI 的代碼產出品質發生了質的飛躍，更重要的是，Google 官方採用了 Anthropic 推出的開源格式，這標誌著跨平台 Agent 知識注入標準的正式確立。
## 章節詳細總結
### Google 釋出了什麼？
儲存庫 `github.com/google/skills` 內含三類技能：
1. **產品技能**：BigQuery, Cloud Run, GKE, Gemini API 等官方文檔。
2. **架構支柱 (WAF)**：涵蓋資訊安全、可靠性與成本最佳化的指導原則。
3. **操作腳本**：身分驗證與網路觀測指南。
透過單行指令 `gemini skills install`，這些技能會統一下載至與框架無關的 `~/.agents/skills/` 目錄中。
### 實測震撼：代碼與架構品質的巨大落差
* **API 代碼生成 (Gemini API)**：
* **未裝 Skill**：模型調用了已被 Google 棄用一年的舊版 `vertexai` SDK，並手寫混亂的字典結構。因為模型的訓練資料裡塞滿了過去幾年的舊代碼。
* **啟用 Skill**：模型寫出了符合現代規範、使用最新 `google-genai` SDK，並且完美整合 Pydantic 進行 Schema 驗證的企業級代碼。
* **架構優化 (BigQuery FinOps)**：
* 面對 2TB 的查詢成本優化問題，未裝 Skill 前只給出空泛建議。啟用 Skill 後，模型給出了包含「分區策略 (Time-Unit Partitioning)」、「物化視圖 (Materialized Views) 增量更新」與「Slot 容量計費臨界點」的高階架構師級別執行計畫。
### 解決上下文膨脹：漸進式展開 (Progressive Disclosure)
這套系統之所以能同時裝載 13 個強大技能而不拖垮 Token 與效能，歸功於架構設計：
* 在會話初始，模型 Context 裡只有這 13 個技能的「名稱與簡介 (約數百 tokens)」。
* 當使用者的 Prompt 命中了某個技能 (例如詢問 BQ 成本)，系統才會跳出授權，將背後數千字的 Markdown 官方參考文件一次性注入 Context。
* 這種架構完美解決了過去一年癱瘓無數 Agent 的「Context Bloat (上下文過載)」難題。
### 行業基礎設施的標準化時刻
本文最大的洞見在於：**MCP 解決了 Agent 如何「做事 (存取外部系統)」，而 Skills 解決了 Agent 如何「獲取知識 (閱讀手冊)」**。
Google 選擇放下面子，直接採用競爭對手 (Anthropic) 的開源 Skills 格式。這代表你寫的同一份 `SKILL.md`，未來可以直接在 Claude Code, Gemini CLI, Codex 甚至 Cursor 中無縫運行。這宣告了「機器可讀文件 (Agent-readable documentation)」的標準化時代正式到來。
## 總結與結論
* **品質躍升的真相**：Google 官方稱這套 Skill 讓代碼準確率飆升至 87%~96%。這並非模型變聰明了，而是模型終於「讀到了對的操作手冊」。
* **產業趨勢**：未來的開發文檔將不只是寫給人類看的，更是寫給 Agent 掛載的。
* **強烈建議**：所有在 Google Cloud 上部署 Agent 工作流的開發者，應立即安裝此官方技能庫，以確保生成的代碼永遠符合最新規範與最佳實踐。
Obsidian 整理
原始文章
開發工具
軟體工程師終極 Mac 工具箱 (2026 Edition)
"2026 年的開發工具趨勢，一方面是 AI 從「自動完成工具」進化為「具備執行力的代理 (Agent) 與無縫的語音轉錄」；另一方面則是基礎設施 (終端機、套件管理) 追求用 Rust/Zig 重寫帶來的極致性能與極簡體驗。"
Top 5 Insights
- **2026 工具雙主軸**：一是 AI 深度融入工作流 (Agent 執行、語音轉錄、語義搜尋)；二是底層基建的性能復興 (Rust/Zig 帶來的極致速度)。
- **實踐建議**：永遠保持開放心態。即便是用了十年的 iTerm2 或 pip，當真正有數量級提升 (Order of magnitude) 的新工具出現時，花一個下午進行遷移，將獲得長遠的複利回報。
---
tags: [開發工具, 效率工具, Mac, AI輔助, 終端機]
date: 2026-05-19
read: false
source: "2026-05-19T093019+0800-The Ultimate Toolbox Best New Apps and Tools for Software Engineers on Mac (2026 Edition).md"
---
# 軟體工程師終極 Mac 工具箱 (2026 Edition)
原始來源與檔名：2026-05-19T093019+0800-The Ultimate Toolbox Best New Apps and Tools for Software Engineers on Mac (2026 Edition).md
---
## NAPKIN | 餐巾纸
### 餐巾紙公式
> 2026 終極生產力 = Claude Code (AI 代理) + Ghostty (極速終端) + uv (Python 救星) + Superwhisper (語音輸入) + Pieces (語義 Snippet)
### 一句話
> 2026 年的開發工具趨勢，一方面是 AI 從「自動完成工具」進化為「具備執行力的代理 (Agent) 與無縫的語音轉錄」；另一方面則是基礎設施 (終端機、套件管理) 追求用 Rust/Zig 重寫帶來的極致性能與極簡體驗。
### 餐巾紙草圖
```text
[大腦輸出層] Superwhisper (語音轉文字, 極速打草稿)
|
[系統環境層] Ghostty (Zig 開發的極速終端機) + uv (Rust 開發的閃電 Python 工具)
|
[AI 執行層] Claude Code (終端機內的自主 Agent, 直接寫代碼/測試/修Bug)
|
[知識檢索層] Pieces (AI 語義搜尋程式碼片段, 本地優先)
```
## ROUND 1: SKELETON | 骨架掃描
- **核心問題**: 面對不斷推陳出新的開發工具，2026 年到底有哪些新工具真正經得起日常高強度開發的考驗，值得替換掉既有習慣？
- **核心答案**: 五款工具脫穎而出：Anthropic 的 Claude Code (真 Agent)、Ghostty 終端機 (取代 iTerm2)、uv (取代 pip/pyenv)、Superwhisper (精準的語音轉文字)、以及 Pieces (AI 語義化程式碼庫)。
- **論證結構**: 作者以第一人稱的長期實戰經驗出發，逐一介紹每一款工具「為什麼值得切換」、「如何應用在日常工作」，以及「真實的優缺點警告」。
### 章節骨架
1. **Claude Code**: 從聊天外掛進化為終端機內的 CLI Agent，能端到端完成重構與測試，但需要精確的指令引導。
2. **Ghostty**: Mitchell Hashimoto (Vagrant 作者) 用 Zig 開發的新終端機。速度極快，原生 macOS 體驗，成功讓作者放棄了多年的 iTerm2。
3. **uv**: Astral 團隊用 Rust 打造的 Python 包裝管理工具，將原本需 30 秒的依賴安裝壓縮至 2 秒內。
4. **Superwhisper**: macOS 原生語音轉文字軟體 (基於 OpenAI Whisper)，極大地提升了撰寫 PR、註解與 Slack 的速度與詳細度。
5. **Pieces for Developers**: 本地優先的 AI snippet 工具。無需手動標籤，透過自然語言語義搜索就能找回忘記的程式碼。
6. **總結**: 2026 年的工具特徵：AI 成為基建，且「無聊但極度穩定快速」的底層工具 (uv, Ghostty) 依舊稱王。
## ROUND 2: DISSECTION | 血肉解剖
- **隱形假設**: 開發者的生產力瓶頸已經不在於「打字速度」，而在於「切換上下文的摩擦力 (Friction)」與「環境建置的等待時間」。任何能削減這兩者的工具，都具有極高的轉換價值。
- **邊界條件**: 這些工具高度依賴 macOS (尤其是 Apple Silicon 的效能紅利)。此外，Claude Code 與 Superwhisper 若重度依賴雲端，需注意企業資安合規性 (儘管 Superwhisper 支援本地處理)。
## ROUND 3: SOUL | 靈魂提取
- **知識連結**: 「用更快的系統語言 (Rust/Zig) 重寫核心基礎設施」的技術復興趨勢；以及「語義化搜尋 (Semantic Search)」對傳統樹狀結構資料管理的顛覆。
- **深層洞見**: Superwhisper 帶來了一個意想不到的心理學變化：當輸入文字的成本(打字)降低為語音時，工程師反而願意寫出更詳盡、更容易理解的文件與 PR 描述。這證明了**工具不僅改變效率，更改變了溝通品質。**
- **行動呼籲**: 如果你是 Python 開發者，立刻將環境切換到 `uv`；如果你還在用滑鼠整理 Snippet，今天就安裝 `Pieces` 並體驗語義搜尋。
---
# 軟體工程師終極 Mac 工具箱 (Architectural Deep Dive)
## 前言/背景
本文作者分享了 2026 年大幅改變其日常工作流的五款 Mac 開發工具。有別於市場上的行銷文，這份清單剔除了華而不實的 AI 噱頭，專注於那些能真正減少摩擦力、提升編譯速度與減輕認知負擔的「生產力利器」。
## 章節詳細總結
### 1. Claude Code: 會真正動手的 AI Agent
* **定位**：不是 IDE 聊天視窗，而是一個直接運行在終端機的 Anthropic 官方 CLI 工具。
* **突破**：它具備**全專案上下文意識 (Codebase awareness)**，能夠端到端地執行任務：讀取代碼 -> 寫測試 -> 跑測試 -> 看 Error Log -> 自我修復。
* **場景**：最適合用來處理枯燥的重構、API 遷移與補齊樣板測試。
* **警告**：它就像個非常有能力但需要明確指示的初級工程師，指令模糊會導致它自信地寫出錯誤的代碼。
### 2. Ghostty: 取代 iTerm2 的極速終端機
* **定位**：由 HashiCorp 創辦人 Mitchell Hashimoto 以 Zig 語言從零打造的終端機。
* **突破**：在 Apple Silicon 上渲染速度極快，滑動長日誌時毫無卡頓。它拋棄了冗餘的 UI 介面設定，採用極簡的單一 Config 檔案配置。
* **優勢**：提供極致的原生 macOS 體驗，不試圖做 tmux 該做的事（如多工復用），專心做好最快的終端機。
### 3. uv: 統治 Python 生態的 Rust 工具
* **定位**：由 Astral (Ruff 開發團隊) 開發的極速 Python 套件與版本管理器。
* **突破**：一舉取代了 `pip`, `pip-tools`, `virtualenv`, `pyenv`。將原本需要 30 秒的環境建置與依賴安裝，壓縮到 2 秒內。
* **優勢**：支援 Drop-in 替換 (相容 `requirements.txt` 等)，並內建 Lockfile 支援，徹底解決 Python 依賴解析緩慢的歷史共業。
### 4. Superwhisper: 改變溝通習慣的語音輸入
* **定位**：常駐於 macOS 的語音轉文字應用程式，底層基於 OpenAI 的 Whisper 模型。
* **突破**：對技術名詞、程式庫名稱、命令列參數的辨識度極高，且支援完全本地化 (Local-first) 運算以保護隱私。
* **深遠影響**：作者發現，用語音口述 Slack 回覆、PR 描述與 Commit Message，不僅速度遠超打字，更因為輸入成本降低，使得最終寫出的文件比以前更加詳細且易讀。
### 5. Pieces for Developers: 會思考的 Snippet 管理器
* **定位**：AI 驅動、本地優先的程式碼片段管理器。
* **突破**：解決了傳統 Snippet 依賴「手動命名與打標籤」的痛點。透過自動語言偵測與**語義搜尋 (Semantic Search)**，你只需用自然語言描述「那個用來防抖的 API 呼叫函式」，它就能精準撈出代碼。
* **整合**：完美嵌入 VS Code、瀏覽器與 Claude Code，讓知識的擷取與重複使用實現零摩擦。
## 總結與結論
* **2026 工具雙主軸**：一是 AI 深度融入工作流 (Agent 執行、語音轉錄、語義搜尋)；二是底層基建的性能復興 (Rust/Zig 帶來的極致速度)。
* **實踐建議**：永遠保持開放心態。即便是用了十年的 iTerm2 或 pip，當真正有數量級提升 (Order of magnitude) 的新工具出現時，花一個下午進行遷移，將獲得長遠的複利回報。
Obsidian 整理
原始文章
