AI Knowledge Archive

--- tags: [AI商業, 商業策略, 產業趨勢, 系統架構] date: 2026-06-16 read: false source: "2026-06-16T093946+0800-A frontier without an ecosystem is not stable.md" original_title: "A frontier without an ecosystem is not stable" --- # A frontier without an ecosystem is not stable 原始來源與檔名：2026-06-16T093946+0800-A frontier without an ecosystem is not stable.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 企業未來價值 = 人力資本 (Human Capital) × 演算法代幣資本 (Token Capital) × 持續學習迴圈 (Learning Loop) _企業未來的競爭力不再是單純購買最強大的模型，而是建立能將人類領域知識轉化為組織專屬 AI 能力的持續學習系統。_ ### 一句话 > 在 AI 時代，企業的生存法則不是依賴少數強大的通用模型，而是建立屬於自己的學習迴圈，讓員工的專業判斷與企業的 AI 能力共同成長。 ### 餐巾纸草图 ```text [ 人類專長與判斷力 (Human Capital) ] | ^ 指導/設定目標/回饋 放大能力/最佳化流程 v | [ 私有強化學習迴圈 (Private Reinforcement Learning) ] | ^ 訓練信號/工作流積累 持續升級 v | [ 企業專屬 AI (Token Capital) ] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 在 AI 驅動的經濟時代，企業將如何學習、建立智慧財產權並保持競爭力？ * **核心答案**: 企業必須建立「代理人系統」(Agentic Systems) 與私有學習迴圈，將人力資本轉化為專屬的「代幣資本」(Token Capital)，而不是被少數通用大模型徹底商品化。 * **論證結構**: 演繹與警示對比型 (Deductive & Contrastive) ### 章節骨架 1. **認知迴圈的誕生**: AI 首度讓人與數位系統建立真實的認知互動。 2. **資本的重新定義**: 企業價值由人力資本與代幣資本構成。 3. **學習迴圈即新 IP**: 競爭優勢在於建立專屬學習系統而非挑選模型。 4. **架構的根本改變**: 需要保留企業自主權與評估機制的代理人架構。 5. **反對壟斷與掏空**: 必須避免少數模型吞噬所有行業價值的反烏托邦。 6. **共榮的邊界生態**: 建立邊界生態系統，確保價值廣泛流動與創新。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text [AI 能持續吸收人類專業知識] --> [若無防備，企業知識將被通用模型商品化] --> [企業必須將人類判斷力轉化為專屬的 Token Capital] --> [這需要依賴包含私有評估與強化學習的學習迴圈] --> [這種學習迴圈將成為企業難以被複製的新型 IP，並推動整體生態系的健康發展] ``` ### 關鍵證據 1. **歷史教訓對比**: 全球化第一階段造成的產業掏空與失業，警示 AI 時代若由少數模型壟斷，將面臨同樣的社會與政治經濟反撲。 2. **人機協作本質**: 沒有人類的方向設定與領域知識連接，運算能力只是在「原地打轉」，證明人力資本在 AI 時代只會升值。 3. **模型可替換性**: 強調在未來的架構中，「通用模型」可以隨時被替換，但企業累積的「老員工」經驗 (Learning System) 才是真正的護城河。 ### 隱形假設與邊界條件 * **隱形假設**: * 企業有能力與資源建立並維護自己的私有強化學習環境與資料管線。 * 「代幣資本」(Token Capital) 的成長率與商業變現能力足以抵消建立這些系統的成本。 * 政治與社會力量會積極介入以防止少數 AI 巨頭的絕對壟斷。 * **邊界條件**: * 當開源或第三方通用模型的能力進步速度遠遠超過企業內部私有迴圈的積累速度時，這套防禦策略可能會失效。 * 若特定產業高度標準化且缺乏獨特的「隱性知識」(Tacit Knowledge)，建立私有學習迴圈的價值將大幅降低。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 文章較少著墨中小型企業 (SME) 面對建立高門檻「私有強化學習迴圈」時的技術與資金困境，這可能會加劇大企業與小企業間的數位落差。 * **知識連接**: 與軟體工程中的「領域驅動設計」(DDD)、知識管理中的「SECI 模型」(隱性知識與顯性知識轉換)、以及機器學習中的 RLHF (人類回饋強化學習) 高度契合。 * **行動觸發**: 企業領導者與架構師不應再把精力花在「比較哪個大模型跑分高」，而是立刻開始盤點企業內部最有價值的工作流，並建構能夠捕捉這些工作流回饋的資料收集與評估平台。 ### 跨域映射 * 在 **知識管理學**，這叫 **組織記憶 (Organizational Memory) 的數位化與活化** * 在 **投資經濟學**，這叫 **複利效應 (Compounding Effect) 的知識資產化** --- # A frontier without an ecosystem is not stable (Architectural Deep Dive) ## 前言/背景 微軟執行長 Satya Nadella 在這篇文章中，探討了在 AI 驅動的經濟體系下「企業」的未來形態。文章要解決的核心問題是：當 AI 模型能夠持續吸收並複製人類與組織的專業知識時，企業如何避免自身的領域知識被「商品化」？為此，作者提出了一套以建立「學習迴圈」(Learning Loop) 與結合「人力資本」(Human Capital) 及「代幣資本」(Token Capital) 為核心的防禦與進化架構。 ## 章節詳細總結 ### 1. 認知迴圈與新型態的企業資本 過去的數位系統僅是增強人類能力的工具，但 AI 帶來了本質上的改變：**人與數位系統之間首次建立了「認知迴圈」(Cognitive Loop)**。在這個背景下，企業未來的核心資產分為兩類： * **人力資本 (Human Capital)**：員工的知識、判斷力、關係網、創造力以及模式識別能力。 * **代幣資本 (Token Capital)**：企業構建並擁有的 AI 運算能力與智慧資產。 架構決策的核心在於，這兩者並非零和遊戲。隨著代幣資本的成長，人力資本將變得更有價值，因為沒有人類設定目標與跨領域串聯，運算資源只是在「原地打轉」浪費算力。 ### 2. 架構轉型：從「挑選模型」到「建構學習迴圈」 文章強調，真正的商業機會**不在於挑選市面上最強的基礎模型，而在於建立一個能讓「人力資本與代幣資本產生複利效應」的學習迴圈 (Learning Loop)。** 在架構設計上，這意味著： * **業務代理人化 (Agentic Systems)**：企業需要全新的架構方法，讓每個業務都能建立隨著時間改進的代理系統。 * **IP 控制權與主權**：系統架構必須解耦「通用模型」與「領域知識」。企業應該要能隨時抽換底層的「通用主義者」模型，同時不會流失系統中已經累積的「企業老兵」專業經驗。這就是企業在 AI 時代保持控制權的關鍵測試。 ### 3. 私有評估與組織內部的強化學習環境 為確保領域知識能沉澱為企業專屬的新型 IP（作者稱之為「爬山機器」Hill Climbing Machine），系統架構必須涵蓋以下工程實踐： * **私有評估機制 (Private Evals)**：不能依賴外部公開的基準測試 (Benchmarks)。企業必須建立私有的 Eval 系統，透過真實商業產出的指標，來衡量底層模型或 Agent 是否真的在進步。 * **私有強化學習環境 (Private Reinforcement Learning Environments)**：利用組織內部真實發生的操作軌跡 (Traces) 與工作流，作為回饋訊號來強化模型。每一次優化的工作流，都會產生更優質的訓練訊號。 * **可查詢的組織記憶庫**：企業的知識庫必須轉化為向量或圖譜架構，讓組織的隱性與顯性記憶都變得「可查詢 (Queryable)」，並進一步提升 Token 使用的效率。 ### 4. 拒絕模型壟斷，建立邊界生態系 從宏觀的系統工程與經濟角度來看，如果所有價值都被少數幾個全能的大模型吞噬，將導致整個產業被「掏空」，就如同早期全球化外包造成的工業衰退一樣。 架構層面的反思在於：**必須建立一個「前沿生態系 (Frontier Ecosystem)」，而不僅僅是開發一個「前沿模型 (Frontier Model)」。** 良好的平台架構應該賦能上層應用創造出比平台自身擷取還要更多的價值，確保每一家企業都能擁有自己的學習迴圈，讓員工的專業判斷得以外放並規模化。 ## 總結與結論 * **模型解耦與抽象層設計**：架構師必須設計抽象層 (Abstraction Layer)，將企業核心的業務邏輯、私有知識庫與底層 LLM 解耦，確保隨時可替換外部模型而不損失系統智慧。 * **建立 Private Evals 基礎設施**：除了傳統的 CI/CD 測試，必須為 AI 系統導入「評估即代碼 (Evals-as-Code)」的管線，使用企業真實業務指標來持續監控並評測模型在特定工作流中的表現。 * **構建資料與回饋飛輪**：未來的系統不僅僅是處理 CRUD，更要具備「捕獲真實操作軌跡 (Traces) 與隱性回饋」的能力，將其作為私有強化學習的訓練資料，這是企業未來無法被複製的核心護城河。 * **注重 Token 使用效率與 RAG 優化**：將組織記憶轉化為可高效查詢的結構，是降低代幣資本 (Token Capital) 消耗並提升 AI 推論精準度的關鍵基礎工程。

--- tags: [AI工具, 產品管理, Agent架構, 工作流, Claude, MCP] date: 2026-06-16 read: false source: "2026-06-16T093833+0800-AI PM OS — now in Claude Cowork too!.md" original_title: "AI PM OS — now in Claude Cowork too!" --- # AI PM OS — now in Claude Cowork too!  ## 核心概念 (Core Concept) AI PM OS 2.1 是一個專為產品經理 (PM) 深度客製化的作業系統級外掛，現已正式整合至 Claude Cowork。此系統透過定義明確的技能模組、自動化工作流、子代理架構 (Subagents) 以及跨工具的記憶匯入機制，將產品管理的經驗法則轉化為可被 AI 執行的具體指令與自動化流程，極大地降低了認知負載並提升了專案推進的效率。 ## 架構深潛 (Architectural Deep Dive) ### 1. 系統控制與工作流引擎 系統底層配置了 13 種系統技能（System Skills）負責核心的生命週期管理與環境建構，例如使用 `/pm-os:pm-os-start` 初始化專案上下文，或以 `/pm-os:pm-os-tidy` 執行工作狀態的快取與同步。在此基礎上，系統內建了 10 種序列化 PM 工作流（Sequenced PM Workflows），涵蓋了策略研擬、市場研究、決策框架、利害關係人溝通及會議管理等，這些工作流本質上是將高複雜度的產品管理任務封裝為可執行的狀態機 (State Machine)，以確保 AI 輔助的連貫性。 ### 2. 動態技能調度與多代理協作 AI PM OS 具備一個包含 214 種可重用產品管理技能的動態函式庫（例如 `find-the-strategic-crux` 或 `mckinsey-issue-tree`）。Claude 模型會根據當下的任務上下文，動態路由並掛載所需的技能，實現了按需計算的資源最佳化。此外，系統配備了 10 個專屬子代理 (Subagents)，這些代理獨立運行於主流程之外，專責進行任務產出的品質審查 (Review) 以及長文本上下文狀態管理 (Context Management)，確保複雜系統在多步推理中不會發生資訊丟失或幻覺。 ### 3. 資料整合與狀態持久化 系統深度依賴模型上下文協議 (MCP, Model Context Protocol) 來連接外部資料源，預設即配置了特定領域知識庫（如 Lenny's Transcripts），使代理能動態獲取高質量的外部參考。在資料持久化與初始化方面，2.1 版本引入了跨工具記憶匯入 (Cross-tool Memory Import) 架構，透過解析與提取來自 ChatGPT、Claude 乃至 Gemini 的歷史對話特徵與關鍵上下文，讓新使用者的環境設定與領域知識對齊 (Onboarding) 能夠在 5 分鐘內完成，大幅優化了系統冷啟動 (Cold Start) 的效率。

--- tags: [AI工具, 開發工具, 工作流, Agent架構] date: 2026-06-16 read: false source: "2026-06-16T093955+0800-Mastering Codex (Mobile) for Engineering.md" original_title: "Mastering Codex (Mobile) for Engineering" --- # Mastering Codex (Mobile) for Engineering  原始來源與檔名：2026-06-16T093955+0800-Mastering Codex (Mobile) for Engineering.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > Codex Mobile = 遠端運算環境 (Host) + 非同步控制平面 (Control Plane) + 脈絡隔離通道 (Side Chats) _將手機轉變為指揮開發主機的高階遙控器，而非受限的迷你終端機。_ ### 一句话 > 你的手機不是用來親自敲擊程式碼的，而是用來設定目標、切分工作區、引導 AI 代理，以及隨時隨地進行程式碼審查的指揮中心。 ### 餐巾纸草图 ```text +-------------------+ Commands & Goals +-----------------------+ | Codex Mobile | --------------------------> | Host (Mac/Win/Devbox)| | (Control Plane) | | (Execution Engine) | | | <-------------------------- | | | - Side Chats | Diffs, Status, Insights | - Worktrees & Git | | - Goals / Plans | | - Local Environment | | - Code Reviews | | - Source Code | +-------------------+ +-----------------------+ ``` ## ROUND 1: SKELETON | 骨架掃描 **"這本書在說什麼"** * **核心問題**: 開發者如何在不便使用電腦的場景下，利用行動裝置高效推進複雜的工程任務？ * **核心答案**: 將 Codex Mobile 定位為遠端工作機的「控制中心」，透過精確的環境隔離、對話狀態管理以及行動裝置原生功能來指揮 AI。 * **論證結構**: 實戰指南型 (Pattern-based Guide) ### 章节骨架 1. **控制中心思維**: 手機是遙控器，運算仍在遠端主機。 2. **邊界設定**: 遠端配置 Git 與隔離的工作目錄 (Worktrees)。 3. **旁支對話**: 利用 `/side` 隔離主線任務與探索性問題。 4. **計畫與目標**: 區分實作路徑 (Plan) 與最終交付狀態 (Goal)。 5. **行動原生賦能**: 結合相機、語音與照片，加速上下文收集。 6. **無縫程式碼審查**: 行動端 inline review，打破非同步開發的瓶頸。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 论证链 ```text AI 開發會產生大量冗長的上下文 --> 若在同一對話列出所有疑問會污染主代理的理解 --> 必須使用 Side Chats 來解耦 開發流程需要明確的驗證點 --> 若只提供模糊指令會浪費 Token 與算力 --> 必須區分 Plan (如何做) 與 Goal (完成標準) 零碎時間阻礙開發進度 --> 將 Blockers (如 Code Review) 轉移至行動端 --> 透過手機即時解鎖決策瓶頸 ``` ### 关键证据 1. **環境腳本同步**: Codex Mobile 能夠直接調用並執行桌面端建立的環境設定腳本，確保遠端工作目錄 (Worktree) 的初始狀態正確。 2. **Side Chats 實踐**: 選取主對話中的日誌或程式碼，利用 `/side <prompt>` 針對架構或錯誤訊息提問，不干擾原本的工作執行緒。 3. **目標管理機制**: `/goal` 讓 AI 在多輪對話中保持對最終狀態的追求，而不會因為中途的編譯錯誤或修改而忘記原始目的。 ### 隐形假设与边界 * **隐形假设**: * 使用者的基礎建設完善，擁有一台可隨時連線並執行建置與測試的遠端主機。 * 專案本身已經具備高度自動化的測試與建置腳本，讓 AI 可以自我驗證。 * **边界条件**: * 遇到需要通盤閱讀並重構跨越多個檔案的遺留系統時，手機螢幕的尺寸限制依然會導致脈絡掌握困難。 * 在缺乏穩定網路連線的環境下，Mobile 幾乎無法發揮作用。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲点**: 缺乏對於多人協作環境下的衝突處理方案（例如兩個開發者同時對同一個遠端主機的 Worktree 下達相衝突的 Goal）。 * **知识连接**: 這種將「決策下達」與「勞力執行」分離的模式，在分散式系統中被稱為 **Control Plane** 與 **Data/Worker Plane** 的分離設計；在組織管理上，這就是「賦能授權」(Delegation) 的終極體現。 * **行动触发**: 下次遇到阻礙 (Blocker) 時，不要急著回到電腦前，嘗試在手機上啟動一個 `/side` 詢問錯誤日誌，或使用語音輸入一段 `/goal` 讓遠端主機開始自動探索解法。 ### 跨域映射 * 在 **分散式架構**，這叫 **Control Plane / Data Plane Separation** * 在 **產品管理**，這叫 **非同步決策 (Asynchronous Decision Making)** ## STRUCTURE MAP | 全书结构图 ```text [ Codex Mobile Operations ] | +--> 1. Environment Setup (Worktrees, Git Branches) | +--> 2. Intent Specification | +-- /plan (Propose Implementation Path) | +-- /goal (Define Durable Outcomes) | +--> 3. Contextual Inquiry | +-- /side (Isolate Q&A from Main Thread) | +--> 4. Mobile Context Injection | +-- Photos, Voice Dictation, Screenshots | +--> 5. Validation & Review +-- Diff Inspection, Inline Comments ``` --- # Mastering Codex (Mobile) for Engineering (Architectural Deep Dive) ## 前言/背景 本文深入探討了如何將 OpenAI 的 Codex Mobile 轉變為強大的工程開發控制中心。文章解決的核心問題是：開發者往往誤以為行動裝置的限制（螢幕小、打字慢）使其無法進行嚴肅的開發工作。作者透過展示如何精細地操作狀態管理、脈絡隔離以及宣告式目標，將手機重新定位為遠端開發主機的「非同步決策控制平面 (Control Plane)」。 ## 章節詳細總結 ### 1. 確立場景邊界：建立隔離的開發環境 (Worktrees) 在啟動 AI 代理執行任務前，首要任務是提供一個乾淨且被正確隔離的作用域 (Scope)。 * **技術細節**：Codex Mobile 允許使用者在第一道 Prompt 發出前，選擇連接的遠端主機 (Host) 與工作區 (Workspace)。系統支援在手機上直接建立新的 Git 分支與 **Worktree**，這意味著主分支的狀態不會被實驗性的修改污染。 * **環境初始化**：當建立 Worktree 後，Codex 可以直接觸發在桌面端預先配置的環境建置腳本 (Environment Setup Scripts)。這讓 AI 在開始編寫程式碼之前，就處於正確的依賴 (Dependencies) 狀態。 ### 2. 脈絡隔離：利用 Side Chats 保持主線純粹 在長時間運行的 AI 開發執行緒中，累積的對話記錄包含了極高價值的上下文 (Context)。 * **技術細節與決策**：如果開發者為了理解某個實作細節而隨意插入提問，會導致主執行緒充滿「雜訊」，這稱為 Context Pollution。為解決此問題，Codex 引入了 `/side` 指令。 * **操作模式**：使用者可以圈選一段日誌或程式碼，觸發「Ask in side chat」，或者直接輸入 `/side <prompt>`。這會建立一個掛載於當前執行緒、但擁有獨立對話脈絡的子對話。 * **架構意義**：這就像是為主從式架構中的背景任務 (Background Worker) 建立一個旁路診斷通道 (Side-channel Diagnostic)，主執行緒負責「更改狀態 (Mutation)」，而 Side Chat 負責「查詢狀態 (Query)」。 ### 3. 指令集架構：Plan 與 Goal 的語意區別 AI 開發必須從 Imperative (指令式) 轉向 Declarative (宣告式) 的互動模式。 * **Plan 模式 (`/plan`)**：這相當於系統設計階段。要求 Codex 在修改任何程式碼之前，先產出實作路徑。適用於風險較高或橫跨多個微服務的任務。Plan 解決的是 "How" 的問題。 * **Goal 模式 (`/goal`)**：目標是具有「持久性 (Durable)」的狀態機。在手機上設定 Goal 後，Codex 會自動在多個回合的編譯、測試與修改中持續追求這個結果。Goal 解決的是 "What" 的問題。 * **實戰建議**：作者指出，給予 Goal 時必須具備「可驗證的結束狀態 (Verifiable End State)」，避免過度寬泛的指令導致 Token 浪費與 AI 的無效迭代。 ### 4. 融合行動原生能力 (Mobile Context Injection) 行動裝置擁有桌機所缺乏的感測器優勢。 * **技術細節**：利用手機的相機、相簿與語音輸入作為 Prompt 的載體。例如，在測試 Web 或 iOS App 時，直接擷取畫面的 Bug 截圖並發送到 Codex 任務中。 * **非同步語音 (Dictation)**：Codex iOS 支援在背景持續錄音。開發者可以開啟語音輸入後，將 App 退至背景，花 10 分鐘邊操作測試中的 App 邊口述問題，隨後再切回 Codex 發送完整的 Context。 ### 5. 無縫的程式碼審查 (Code Review) 機制 將決策瓶頸從電腦桌前轉移至手機上。 * **技術細節**：Codex 提供了完整的 Diff 檢視表，包含變更檔案摘要、展開或收合區塊、語法高亮 (Syntax Highlighting) 等功能。 * **Inline Comments**：可以在 Diff 的特定行數加入內聯註解，這些註解會被打包回 Composer 中，作為下一波 Prompt 精準反饋給 Codex，要求其修正。這實現了真正意義上的「行動化 Code Review」。 ## 總結與結論 * **架構範式轉移**：Codex Mobile 的設計理念印證了「Control Plane 與 Data Plane 分離」的架構模式。手機不再是終端機，而是負責 Orchestration (編排) 與 Review (審核) 的控制台。 * **防禦性上下文管理**：透過 `/side` 進行探索性提問，是保護 AI 長期記憶與專注力的關鍵技術。在架構設計中，嚴格區分「執行 (Execution)」與「診斷 (Diagnostics)」通道是確保系統穩定性的最佳實踐。 * **宣告式狀態驅動**：善用 `/goal` 設定可驗證的結束狀態 (Verifiable End State)，而非微觀指令。這是未來與 Agentic AI 協作的核心能力，猶如 Kubernetes 依賴宣告式的 YAML 來維持叢集狀態。 * **解鎖非同步開發瓶頸**：將 Code Review、架構探討與 Bug 發現等「決策點」轉移至行動端，能大幅縮短工程師被阻擋 (Blocked) 的時間，提升整體敏捷開發的吞吐量。

--- tags: [AI工具, Agent, CodeGeneration, Ponytail] date: 2026-06-16 read: false source: "2026-06-16T093654+0800-Post by @techNmak on X.md" original_title: "Post by @techNmak on X" --- # Post by @techNmak on X  ## 核心主張 (Core Argument) AI 代理（AI Agents）在生成程式碼時常有過度編寫（over-engineering）的傾向，導致冗長且難以維護的代碼。透過引入類似資深工程師（Ponytail）的思維模式——「在寫任何代碼之前，先尋找不寫的理由」，可以大幅減少生成的代碼量，從而降低成本、提升執行速度與代碼品質。最優秀的程式碼，就是你從未寫下的那行程式碼。 ## XRay 認知解構 (Cognitive XRay) - **問題核心 (The Problem)**: AI 代理為了完成任務，傾向於從零開始編寫大量底層邏輯（動輒 500 行程式碼解決 5 行能解決的問題），忽視了現有庫、內建函數或更簡潔的解決方案。這不僅增加計算成本，更使代碼庫變得龐大且難以審查。 - **解方機制 (The Mechanism)**: 引入名為 "Ponytail" 的機制（或思維框架）。其核心理念是**「減法思維」 (Subtractive Thinking)** 與 **「防禦性生成」 (Defensive Generation)**。在 AI 開始編寫代碼之前，強制其進入一個「審視與質疑」的階段，尋找可以避免編寫新代碼的方法（例如：重用現有邏輯、運用標準函式庫、或是重新定義問題以繞過複雜邏輯）。 - **關鍵成效 (Metrics & Impact)**: - 減少 80-94% 的代碼量 (Less Code) - 降低 47-77% 的成本 (Cheaper) - 提升 3-6x 的速度 (Faster) - **反方視角與爭議 (Counter-perspective)**: - 極致濃縮的代碼（One-liners 或高度抽象的邏輯）可能導致可讀性下降，從「人類可讀的冗長代碼」變成「難以理解的簡潔代碼」，反而增加了代碼審查（Code Review）的難度與出錯風險。 - 替代方案主張：未必需要專門的工具，透過精心設計的系統提示詞（如 `AGENTS.md`），即足以約束 AI 代理的行為模式，達到相同的簡潔效果。 ## 系統架構深度剖析 (Architectural Deep Dive) ### 1. 代理攔截與審查架構 (Agent Interception & Review Architecture) Ponytail 機制本質上是在標準的「需求輸入 -> 代碼生成」管線中，插入了一個**預生成審查層 (Pre-generation Review Layer)**。 傳統架構：`User Prompt -> LLM Generation -> Output Code` Ponytail 架構：`User Prompt -> Strategy Evaluation (尋找現成方案/簡化邏輯) -> Refined Prompt / Direct Call -> LLM Generation (極簡化) -> Output Code` 這種架構將「思考如何不寫代碼」視為一個獨立的運算步驟，利用 LLM 的推理能力先進行策略規劃，而非直接進入實作細節。 ### 2. 減法最佳化 (Subtractive Optimization) 系統透過限制輸出長度、強制要求調用現有 API、或是優先匹配系統標準庫，來實現代碼的減法。這在工程上類似於靜態代碼分析中的「死代碼消除 (Dead Code Elimination)」或「代碼去重 (Code Deduplication)」，但在 Ponytail 中，這種消除發生在**代碼生成之前 (Pre-generation)**，是一種主動防禦機制。 ### 3. 性能與成本效益模型 (Performance & Cost Efficiency Model) AI 代理的成本與延遲主要與 Token 消耗量（Input + Output Tokens）成正比。藉由抑制過度生成： - **Output Token 顯著減少**：直接導致成本降低 47-77%，生成速度提升 3-6 倍。 - **計算資源的轉移**：將原本用於生成無用代碼的運算能力（Compute），轉移到前期的「邏輯簡化推理」上，實現了 ROI 更高的運算投資。 ### 4. 抽象化與可讀性的權衡 (Abstraction vs. Readability Trade-off) 如評論區所指出，過度的代碼簡化可能引入新的技術債：**認知負擔轉換 (Cognitive Load Shift)**。當 500 行的顯式邏輯（Explicit Logic）被壓縮成 1 行的高度抽象邏輯（Implicit/Dense Logic）時，雖然減少了代碼體積，但可能依賴了複雜的正則表達式、不常見的 API 或高階函數。這種現象在架構上稱為「密度過載 (Density Overload)」，要求團隊在引入此類自動化簡化工具時，必須同步強化代碼的註解生成與測試覆蓋率，以彌補可讀性的流失。

--- tags: [AI工具, Claude, Context管理, 開發者工具] date: 2026-06-16 read: false source: "2026-06-16T094007+0800-一个 skill 成为 TOP 1% Context 管理大师，比官方好用 100x 的 fork.md" original_title: "一个 skill 成为 TOP 1% Context 管理大师，比官方好用 100x 的 fork" --- # 一个 skill 成为 TOP 1% Context 管理大师，比官方好用 100x 的 fork  ## 🧠 XRay 深度解析 ### 1. 核心概念與痛點 本文主要解決在終端機中使用 Claude Code 等無狀態 (Stateless) AI 代理時，管理上下文 (Context) 的痛點。當開發者需要進行岔路提問或嘗試破壞性重構時，直接在當前會話操作會污染主線上下文，而重新開啟新會話則會丟失之前累積的歷史對話，導致需要重新傳輸完整的上下文，不僅耗時且無法利用緩存 (Cache) 機制（命中緩存可節省高達 90% 的 Token 成本）。 ### 2. 原生機制的局限性 Claude Code 原生提供了幾個管理上下文的指令，但存在操作不便的缺點： - `/btw <問題>`：唯一能在提示詞處理過程中發起額外會話的指令，不會寫入歷史記錄，可完美命中緩存。 - `--continue (-c)`：接續最近的對話，只要在 TTL (預設 1 小時) 內皆可利用前綴緩存。 - `/branch` 與 `/fork`：雖然能建立分支或讓後台去執行任務，但無法自動在終端機中開啟一個並排、帶有相同上下文且支援多輪對話的獨立會話視窗。 ### 3. branchnew 的解決方案與機制 作者開發了 `branchnew` 工具，其底層封裝了 `claude --continue --fork-session` 指令。其核心運作機制為： - **自動分屏與無縫接續**：在 iTerm2 等終端機中，一鍵 (或使用 `/branchnew` 指令) 即可將視窗向右分割。 - **100% 緩存命中**：右側的新視窗會做為當前對話的分支，由於共享相同的歷史前綴 (History Prefix)，在分岔那一刻不需要重放歷史，上下文完全命中緩存，實現幾乎零成本的會話拷貝。 - **隔離執行**：主線與分支各自獨立運行，開發者可以在分支中試錯，成功後再將代碼合併回主線，失敗則直接關閉視窗，對左側的主會話毫無影響。 ## 🏗️ 系統架構與技術深潛 (Architectural Deep Dive) ### 1. 緩存利用與狀態管理架構 由於大語言模型 (LLM) 本質上是無狀態的，每次請求都必須攜帶完整的對話歷史。系統架構上高度依賴 API 端的前綴緩存 (Prefix Caching) 機制。`branchnew` 的設計決策在於「不複製上下文資料，而是複製 Session 狀態指標」。透過 `--continue --fork-session`，工具讓新程序繼承舊有的 Session ID 與對話歷史樹的特定節點，從而讓 LLM 伺服器將其識別為相同的緩存前綴。 ### 2. 終端機整合與自動化工作流 `branchnew` 結合了終端機的視窗管理 API（如 iTerm2 的 Python API）。其工作流拆解如下： 1. **觸發階段**：使用者輸入 `/branchnew` 或按下快捷鍵 `⌘F`。 2. **會話捕捉**：腳本精確捕捉當前活動格 (Pane) 內的會話狀態與 Session ID，確保分支不會串接錯誤的會話。 3. **UI 操作**：自動調用終端機 API 執行向右分割視窗的操作。 4. **子程序啟動**：在新的視窗中注入並執行 `claude --continue --fork-session [可選分支名稱]`。 5. **並行交互**：使用者獲得一個立即可用的獨立 Repl 環境，無需手動尋找路徑或重新命名分支。 ### 3. 最佳實踐與場景應用 - **防禦性重構 (Defensive Refactoring)**：在進行高風險的代碼修改前，使用 `branchnew` 開啟分支。這相當於 Git 的 `checkout -b`，但作用於 AI 的思維與對話上下文中。 - **異步任務並行**：當主會話正在執行耗時較長的操作（如分析大文件或生成長代碼）時，立刻分出一個分支處理其他關聯性低但需要同等上下文的次要任務，最大化開發者的等待時間效益。 - **緩存生命週期管理**：利用 TTL (Time-To-Live) 特性，理解上下文在伺服器端存活的時間。善用 `/rewind` 退回歷史節點或透過 `--continue` 重連，確保在 TTL 內能低成本地重複利用計算資源。

--- tags: [AI工具, 開發工具, 工作流, Agent架構] date: 2026-06-16 read: false source: "2026-06-16T094003+0800-一篇文章带你了解——gStack.md" original_title: "一篇文章带你了解——gStack" --- # 一篇文章带你了解——gStack  原始來源與檔名：2026-06-16T094003+0800-一篇文章带你了解——gStack.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 1 個人 + gStack = 1 支完整的產品團隊 *這代表 AI 的價值不再只是單點的「程式碼生成」，而是透過角色分工，覆蓋從需求質疑、架構設計到測試發布的完整產品週期。* ### 一句话 > gStack 不是幫你寫程式的工具，而是先幫你確認這段程式碼值不值得寫的「AI 團隊作業系統」。 ### 餐巾纸草图 ```text [ 你 ] | (提供 Idea) v +-----------------------+ | gStack 團隊作業系統 | | | | [PM/CEO] -> 質疑/收斂| | | | | [架構師] -> 規劃/設計| | | | | [工程師] -> 撰寫/實作| | | | | [QA/安全] -> 測試/審查| +-----------------------+ | (自動傳遞上下文) v [ 穩定可用的產品 ] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 為什麼即使 AI 寫程式速度很快，我們仍然會寫出充滿 Bug 且難以維護的系統？ * **核心答案**: 因為我們只讓 AI 當打字員，卻缺少了團隊中「質疑需求」與「多角色審查」的機制；gStack 透過多個 AI 專家角色解決了這個問題。 * **論證結構**: 案例對比型 (傳統 Prompt 開發 vs gStack 流程開發)。 ### 章節骨架 1. **搞懂它是什麼**: gStack 是一個 AI 團隊，核心在於「反諂媚」與先質疑。 2. **它是作業系統**: Roles, Not Prompts，讓上下文在角色間自動傳遞。 3. **動手做**: 30 秒安裝，並演示從 Idea 到 PR 的 8 個關鍵命令流程。 4. **往深走**: 新手只需掌握 4 個核心命令，並了解何時不該使用它。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text AI 寫程式很快但容易出錯 --> 因為 AI 同時兼任 PM/架構師/工程師，腦袋混亂且缺乏質疑 --> 引入 gStack 將職責拆分給 23+ 個虛擬專家 --> /office-hours 負責質疑與收斂需求 --> 設計文件自動傳遞給架構師與工程師 --> /qa 進行真實瀏覽器測試 --> 最終產出高品質、經過完整審查的產品。 ``` ### 關鍵證據 1. YC CEO Garry Tan 使用 gStack 全職管理的同時，2026 年 GitHub 貢獻達 1,237 次，大幅超過過往全職工程師時期。 2. 「日曆每日簡報」案例：/office-hours 透過 6 輪追問，將表面的功能需求轉化為深層的「個人首席 AI 幕僚」身份需求。 3. 騰訊雲開發者社群案例：將上下文分為四層，從過往 11 分鐘溝通背景縮短至 30 秒載入，並標準化 Code Review 與 API 開發流程。 ### 隱形假設與邊界條件 * **隱形假設**: * 使用者有能力判斷 AI 提出的技術方案與產品方向是否合理。 * 專案規模夠大，值得投入前期規劃與架構設計的時間。 * **邊界條件**: * 僅撰寫幾十行腳本時，使用完整 Sprint 流程過於大材小用。 * 已具備完整實體團隊（PM、QA 齊全）的組織，多角色模擬可能造成重複建設。 * 不熟悉終端機命令列，或對隱私/遙測數據極度敏感的使用者不適用。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 較少提及在超大型且高耦合的遺留系統 (Legacy System) 中，gStack 如何有效地理解數十萬行程式碼的上下文並進行重構。 * **知識連接**: 與軟體工程中的領域驅動設計 (DDD)、行為驅動開發 (BDD) 以及微服務架構的康威定律 (Conway's Law) 高度相關——組織結構決定系統架構，gStack 實際上是在你的本機建立了一個高標準的虛擬組織。 * **行動觸發**: 下次開新專案前，不要直接叫 AI 寫程式，先用 `/office-hours` 讓它挑戰你的需求前提；將「自動化真實瀏覽器測試」納入標準開發流程。 ### 跨域映射 * 在 **軟體工程**，這叫 **職責分離與多角色審查 (Separation of Concerns & Code Review)**。 * 在 **產品管理**，這叫 **需求挖掘與反覆代代 (Requirements Elicitation & Iteration)**。 ## STRUCTURE MAP | 全書結構圖 ```text [ 困境 ] AI 淪為盲目打字員，程式碼充滿雷區 | v [ 解法 ] gStack: Roles, Not Prompts (角色取代提示詞) | +--> 1. 質疑階段 (/office-hours) : 反諂媚，確認值得開發 | +--> 2. 規劃階段 (/plan-ceo/eng) : 產出架構與測試矩陣，上下文自動傳遞 | +--> 3. 實作階段 (Claude Code) : 依據架構藍圖精確撰寫 | +--> 4. 驗證階段 (/review, /qa): 偏執級代碼審查與真實瀏覽器測試 | v [ 成果 ] 一鍵發布 (/ship)，產出高穩定度產品 ``` --- # 一篇文章带你了解——gStack (Architectural Deep Dive) ## 前言/背景 隨著 LLM 的普及，許多開發者習慣將需求直接交給 AI 生成程式碼，卻常面臨「初期看起來能跑，後期 Bug 叢生且難以重構」的困境。這篇文章介紹了由 YC CEO Garry Tan 開源的 `gStack` 專案——這不僅是一套 AI 開發工具，更是一個「團隊作業系統」。它解決了 AI 缺乏自我質疑與角色混亂的問題，透過將 PM、架構師、工程師與 QA 拆分為獨立的 Agent 角色，確保在寫出大量程式碼前，先驗證需求的合理性與架構的正確性。 ## 章節詳細總結 ### 1. 搞懂 gStack 是什麼：反諂媚的設計哲學 傳統使用 AI 寫程式的最大痛點在於 AI「太聽話」，它會盲目執行錯誤的產品方向。gStack 的核心特色是其 23+ 個專家角色中，被調用最頻繁的 `/office-hours` 技能。 * **反諂媚 (Anti-sycophancy) 機制**：當你提出需求時，`/office-hours` 不會馬上寫程式，而是啟動追問模式。例如，對於「日曆簡報 APP」的需求，它會追問痛點頻率、使用場景與手動操作的繁瑣處。 * **需求挖掘**：透過 6 輪追問，AI 協助開發者將表面的功能需求，重新定義為核心的「身份需求」（如：個人首席 AI 幕僚）。這大幅降低了因方向錯誤導致的無效開發。 ### 2. 不是工具箱，而是作業系統：Roles, Not Prompts gStack 放棄了傳統的「超長提示詞」做法，改採「賦予角色」的設計 (Roles, Not Prompts)。 * **上下文自動傳遞 (Automated Context Handoff)**：這是系統架構中最關鍵的設計。在 gStack 中，各角色的產出會自動流轉，形成一條 `Think → Plan → Build → Review → Test → Ship → Reflect` 的 Pipeline。 * `/office-hours` 產出的設計文件會自動被 `/plan-ceo-review` 讀取。 * `/plan-eng-review` 產出的測試計畫會自動被 `/qa` 技能識別。 * **消除資訊遺失**：這避免了過往開發者需要反覆貼上上下文給 AI 的問題，實現了「一個人 + gStack = 一支完整產品團隊」的協作模式。 ### 3. 動手做：8 個核心命令跑完 Sprint gStack 建構在 Claude Code 之上，安裝後透過以下標準流程即可完成從 Idea 到 PR 的全生命週期開發： * **Step 1: `/office-hours` (需求質疑)**：生成包含極窄切入點 (方案 A)、中等範圍 (方案 B) 與完整願景 (方案 C) 的設計文件，並儲存於 `~/.gstack/projects/`。 * **Step 2: `/plan-ceo-review` (商業審查)**：挑戰產品範圍，確定是否需要擴展或縮減核心功能。 * **Step 3: `/plan-eng-review` (架構設計)**：在動工前，產出 ASCII 架構圖、資料流圖、狀態機 (State Machine)、錯誤路徑與測試矩陣。 * **Step 4: 實作階段**：Claude 基於上述確定的設計文件，自動生成跨越多個檔案的程式碼（例如：8 分鐘內生成 11 個檔案，約 2,400 行程式碼）。 * **Step 5: `/review` (偏執級審查)**：不檢查常規的 Code Style，而是專注於會導致生產環境崩潰的架構缺陷，例如： * **N+1 查詢問題** (N+1 Queries) * **競態條件** (Race Conditions) * **錯誤的信任邊界** (Improper Trust Boundaries) * **缺失的資料庫索引** (Missing Indexes) * **Step 6: `/qa` (端對端自動化測試)**：並非讓 AI 產生測試報告而已，而是啟動真實的 Chromium 瀏覽器進行點擊與截圖。支援差異感知模式 (基於 Git Diff 尋找受影響頁面) 與快速回歸模式 (`--regression baseline.json`)。 * **Step 7: `/ship` (一鍵發布)**：自動同步主分支、運行測試、稽核覆蓋率（產生 ASCII 覆蓋率圖），並提交 PR 與 Changelog。 ### 4. 實戰優化：上下文的分層架構 在高階使用場景（如微服務架構）中，開發者可以將提供給 gStack 的上下文進行分層，以極大化開發效率： * **四層上下文架構**： 1. **基礎層**：所有後端專案通用的規範。 2. **技術棧層**：例如 Go + Gin + GORM 專用的實踐。 3. **專案層**：特定微服務的業務上下文。 4. **任務層**：具體 API 的範本。 * 此架構讓新 API 開發的上下文溝通時間從 11 分鐘大幅縮短至 30 秒。 ### 5. 邊界與限制 gStack 並非銀彈，作者明確指出了幾種**不適用**的場景： * **微型腳本**：幾十行的簡單任務不值得啟動完整的 Sprint 流程。 * **實體團隊完備**：若已有 PM 與 QA，多角色模擬會造成流程冗餘。 * **CLI 新手與隱私顧慮**：需要熟練終端機操作，且 `/browse` 會維持瀏覽器 Session，遙測功能需手動關閉。 ## 總結與結論 * **架構決策前置化**：gStack 最核心的價值在於「延遲寫程式碼的時間」，強迫開發者在動工前完成需求質疑與架構設計（ASCII 架構圖、資料流、狀態機），這在根本上減少了技術債的產生。 * **Pipeline 式的 AI 協作**：未來的 AI 開發將從「單一 Prompt 生成」轉向「Agent 之間的 Pipeline 協作」。透過標準化格式（如設計文件、測試矩陣）在不同專長角色的 AI 之間自動傳遞上下文，能大幅提升程式碼的工程品質。 * **專注於結構性缺陷的審查**：AI Code Review 的重點應從語法與風格，轉移至高併發與資料庫層面的結構性問題（如 N+1 查詢、競態條件），這能有效彌補單一 LLM 在全域架構視野上的不足。 * **所見即所得的自動化 QA**：結合真實 Chromium 瀏覽器的端對端 (E2E) 測試，並基於 Git Diff 進行智慧回歸測試，為「AI 生成程式碼」提供了最後一道防線，確保軟體在生產環境中的可靠性。

--- tags: [AI工程, Code Review, Agent架構, 工程管理] date: 2026-06-16 read: false source: "2026-06-16T093814+0800-Agentic Code Review.md" original_title: "Agentic Code Review" --- # Agentic Code Review  原始來源與檔名：2026-06-16T093814+0800-Agentic Code Review.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > AI Code Review 效能 = (生成速度 × 產出量) - (理解成本 × 爆炸半徑) _AI 讓寫程式變便宜，讓讀懂程式變昂貴，因此審查流程必須依照爆炸半徑分級，才能最大化整體工程效能。_ ### 一句話 > AI 代理將寫程式的成本降至極低，卻讓「驗證與理解」成為軟體工程的新瓶頸，因此 Code Review 成為當下最具槓桿效應的核心技能。 ### 餐巾纸草图 ```text [撰寫程式] -----> (10x速度) -----> [Code Review] -----> (瓶頸) -----> [驗證與部署] / \ 低風險 高風險 / \ 異質化 AI 審查 人類決策與意圖驗證 ``` ## ROUND 1: SKELETON | 骨架掃描 **"這本書在說什麼"** * **核心問題**: 當 AI 代理 (Agents) 能以極快速度產生大量程式碼時，軟體開發團隊該如何調整其 Code Review 流程與工程實踐以避免被產出淹沒？ * **核心答案**: 團隊必須將審查流程依照「爆炸半徑 (Blast Radius)」分級，善用異質化 AI 進行第一線審查，並將人類的專注力轉移到意圖驗證與高風險決策上。 * **論證結構**: 數據對比與實證分析 ### 章節骨架 1. **AI 帶來產能與審查瓶頸**: 寫作變便宜，理解沒變快。 2. **數據證實 Review 負載劇增**: 缺陷率與無審查合併暴增。 3. **依據爆炸半徑分級審查**: 專案規模與風險決定審查深度。 4. **恢復遺失的程式意圖**: AI 產生代碼缺乏意圖，需靠工具補齊。 5. **善用異質化 AI 審查工具**: 多種模型平行審查優於單一模型。 6. **人類移至迴圈之上**: 人類轉作高階決策，而非逐行檢查。 7. **團隊管理與未來展望**: 確保能為交付的程式碼背書。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text AI 代理提升 4x 產量 --> 人類閱讀速度未提升 --> 審查成為系統新瓶頸 --> 產生零審查合併與高缺陷率 --> 必須導入自動化 AI 審查與風險分級 --> 人類專注於決策與意圖，維持高吞吐與安全性 ``` ### 關鍵證據 1. Faros AI (2026) 報告顯示：AI 採用後程式碼變動率提升 861%，但每位開發者的缺陷率從 9% 飆升至 54%，且零審查合併 (Zero-review merges) 增加 31.3%。 2. CodeRabbit 報告指出，AI 協作產生的程式碼帶有大約 1.7 倍的邏輯與安全問題。 3. 實證測試 146 個 PR 中，四款獨立 AI 審查工具 (CodeRabbit, Seer, Greptile, BugBot) 抓出的 679 個問題，高達 93.4% 是由單一工具獨立發現的，證明異質性模型的強大互補價值。 ### 隱形假設與邊界 * **隐形假设**: * 團隊擁有足夠完善的 CI/CD 基礎設施與自動化測試網，使 AI 產生的代碼有確定性閘門 (Deterministic gates) 把關。 * 團隊能精確評估並量化各模組的「爆炸半徑」(Blast Radius)。 * **边界条件**: * 單人且無真實用戶的綠地專案 (可大量依賴 AI 與測試，大幅減少人工 Review)。 * 負責十年以上且牽涉高度合規或財務的大型企業遺留系統 (絕對不可單靠 AI，必須嚴格由人類介入高風險部分)。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲点**: 雖然強調人類應該專注於「意圖 (Intent)」的驗證，但並未深入探討如何系統化、自動化地從需求端追蹤意圖到程式碼的具體實現路徑。 * **知识连接**: 這與工業工程中的「限制理論 (Theory of Constraints)」不謀而合，當一個環節 (編寫) 的產能極大化時，瓶頸自然轉移至下一個環節 (審查與QA)。 * **行动触发**: 立即在日常的 PR 流程中導入至少兩款底層模型不同的 AI Code Review 機器人；並在 CI 流程加入強制規則，阻擋沒有清楚描述「架構意圖」的大型 PR。 ### 跨域映射 * 在 **雲端原生架構 (Cloud Native)**，這叫 **多層次防禦機制 (Defense in Depth)**。 * 在 **工業工程**，這叫 **瓶頸轉移 (Theory of Constraints)**。 --- # Agentic Code Review (Architectural Deep Dive) ## 前言/背景 在 AI 代理 (Agents) 輔助開發的 2026 年，寫程式的成本急遽下降，導致程式碼產出量暴增。這篇文章探討了當生成速度遠大於人類閱讀速度時，Code Review 如何從一個「順便」的知識共享過程，轉變為整個軟體交付管道 (Delivery Pipeline) 中最核心、也最容易發生瓶頸的驗證關卡。作者 Addy Osmani 提出，開發團隊必須重新設計審查流程，從傳統的逐行閱讀轉向基於「爆炸半徑」的動態風險分級。 ## 章節詳細總結 ### What the 2026 data actually shows (2026 數據顯示的殘酷現實) * **生產力提升帶來的副作用**：根據 Faros AI 對 22,000 名開發者的遙測數據分析，高度採用 AI 後，程式碼變動率飆升了 861%。然而，這帶來了嚴峻的後遺症： * 事件與 PR 的比例上升了 242.7%。 * 每位開發者的缺陷率從 9% 飆升至 54%。 * 未經審查即合併 (Zero-review merges) 增加了 31.3%。 * **價值增長與程式碼量的落差**：GitClear 的數據指出，AI 使用者能產生約 4 倍的程式碼，但實際交付價值僅增長約 12%。這中間的巨大落差，全部成了 Code Review 的負擔。 * **架構層面的意義**：系統的吞吐量受限於最慢的環節。當開發速度達到了機器級別，而審查速度依然維持在人類級別時，流程不可避免地崩潰，團隊必須正視「驗證 (Verification)」已取代「建構 (Construction)」成為軟體工程的最大挑戰。 ### Everyone is solving a different problem (依照爆炸半徑動態調整策略) * **三個決定審查策略的變數**： 1. **爆炸半徑 (Blast radius)**：系統損壞時的代價 (例如無影響 vs. 用戶個資外洩或財務損失)。 2. **程式碼生命週期**：下週就會重寫的雛型 vs. 維護十年的核心系統。 3. **知識共享需求**：單兵作戰 vs. 大型協作團隊。 * **情境對應策略**：若為單人專案，完全可以依賴自動化測試 (Tests pass, ship it)，因為錯誤成本低且沒有理解債 (Comprehension debt) 的問題；但如果將這套套用在大型支付系統上，等同於打造「帶有綠色勾勾的災難產生器」。 ### What review is actually for now (意圖重建：審查的核心轉變) * **遺失的意圖 (Missing Intent)**：人類工程師提交 PR 時，其腦中包含了對各種架構替代方案的權衡，這就是「意圖」。然而，AI 代理在產生程式碼後，通常會丟棄其背後的推理過程 (Thinking traces)。 * **重建成本**：這導致 Code Reviewer 變成了「全世界第一個閱讀這段程式碼的人」，被迫從零開始反向工程 (Reverse Engineering) 猜測這段程式碼的邏輯，這也是為何 Faros 數據顯示審查時間大增 441.5% 的原因。 * **解決方案**：必須在工具鏈層面捕捉 AI 的決策日誌 (Decision log)，將「為何這樣寫 (Why)」附帶於 PR 之中，減少人類重構意圖的時間。 ### The tools are good, but not always for the reason they advertise (異質化 AI 審查工具的實戰策略) * **AI 審查的驚人有效性**：Anthropic 內部將其實質審查率從 16% 提升到 54%，且錯誤攔截率極高。 * **異質性的價值 (Heterogeneity)**：在 146 個 PR 的實測中，平行使用四款不同的 AI 審查工具 (CodeRabbit, Seer, Greptile, Cursor BugBot) 抓出了 679 個問題。 * 驚人的是：**93.4% 的錯誤僅被單一工具發現**，完全沒有任何錯誤是被四個工具同時抓出。 * **架構層面的意義**：在資源分配上，不該執著於尋找「最強的單一模型」，而是在高風險路徑上部署多款底層特性不同的模型 (例如一款專精靜態正確性，一款專精生產環境嚴重錯誤)，透過盲點差異極大化覆蓋率。 ### Should we just let AI review more of it? (人類移至迴圈之上) * **AI 閉環的危險性**：如果讓 AI 寫程式、另一套 AI 審查、第三套 AI 核准，很容易產生「借用的自信 (Borrowed confidence)」——系統彼此同意，但沒有任何人類理解實際發生了什麼。 * **Human on the Loop (從迴圈內到迴圈上)**：人類不該再逐行審查 (那是機器的強項)，而是進行高階把關： * 判斷這是否為正確的架構決策。 * 把關高爆炸半徑的路徑。 * 利用 AI 進行初步 PR 分診 (Triage)，標示出哪些安全可放行，哪些需要人類花費數小時仔細驗證。 ### What to actually do (行動指南與 CI 紀律) * **風險分層 (Tier by risk)**：不應平等對待所有 PR。配置檔變更只需 Linter，核心商業邏輯變更則需要型別檢查、測試、雙重 AI 審查及人類資安審查。 * **提高進件門檻 (Intake Bar)**：拒絕沒有包含「意圖說明」、過大 (例如 3500 行無註解)、或沒有提供測試執行證明的 PR。 * **測試與 CI 的鐵腕防守**： * **審查測試代碼重於實作**：AI 常為了讓測試變綠，而偷偷篡改測試斷言 (Assertion)。必須優先審閱測試代碼的變更。 * **CI 是不可退讓的防線 (Wall that does not move)**：防止 AI 關閉 Linter 或降低測試覆蓋率。 ## 總結與結論 * **多層次異質 AI 審查架構**：對於核心微服務或高併發系統，應在 CI 流程中整合至少兩套不同底層模型 (例如 Claude 體系與 GPT 體系) 的 AI Review 工具，透過其盲點差異 (Blind spot divergence) 來極大化架構缺陷的攔截率。 * **意圖驅動的 PR 閘門 (Intent-Driven Gates)**：將理解成本前置化。架構上應透過自動化腳本 (Git Hooks / CI Checks) 阻擋任何未包含架構意圖 (Architectural Intent) 或決策日誌的 Pull Request，避免高級工程師淪為「反向工程」的勞工。 * **強化 CI/CD 環境的唯讀與不可變性**：在 Agentic 開發時代，自動化測試與靜態分析是最後的安全防線。必須強化 CI 腳本的唯讀權限，嚴格防止 AI 為了求綠燈而偷偷重寫測試斷言 (Assertion)、關閉嚴格的 Linter 規則或引入潛在的 Prompt Injection 漏洞。 * **實施風險分層 (Risk-Tiered) 交付管線**：不再將所有 PR 視為相同權重。透過預測模型或靜態路徑分析，區分「設定檔變更」與「核心交易邏輯」，動態套用不同深度的審查、測試與部署策略。

--- tags: [AI工程, 開發工具, 自動化, Agent架構] date: 2026-06-16 read: false source: "2026-06-16T093635+0800-Agents can now run the full SDLC in Cosmos. What do engineers do?.md" original_title: "Agents can now run the full SDLC in Cosmos. What do engineers do?" --- # Agents can now run the full SDLC in Cosmos. What do engineers do?  原始來源與檔名：2026-06-16T093635+0800-Agents can now run the full SDLC in Cosmos. What do engineers do?.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > Coding + (Review/Ops) * Agent = SDLC 自动化 *僅加速寫程式（Coding）無法突破阿姆達爾定律（Amdahl's law），唯有將系統審查（Review）與維運（Ops）交由代理（Agent）自動處理，才能實現整個軟體開發生命週期的自動化。* ### 一句话 > 開發者的角色已經從「執行每一個機械步驟」轉變為「設定方向、判斷風險與做出最終決策」，讓 Agent 處理剩餘的例行公事。 ### 餐巾纸草图 ``` +-------------+ +-------------------+ +------------------+ | | | Deep Review & | | | | AI Coding | ---> | Agent Routing | ---> | Human Judgment | | (Fast PRs) | | (Cosmos Platform) | | (Arch & Design) | +-------------+ +-------------------+ +------------------+ ^ | +-------------+ | Incidents | | & Alerts | +-------------+ ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 當 AI 生成程式碼變得極快，導致 Code Review 與維運負擔成為新的瓶頸時，軟體工程師該做什麼？ * **核心答案**: 工程師應該利用 Cosmos 等 Agent 平台自動化處理繁瑣的審查與事件回應，專注於架構設計、風險評估與高階決策。 * **論證結構**: 案例對比型（透過導入平台前後的效率對比，證明平台機制的必要性）。 ### 章節骨架 1. **AI 寫作的天花板**: 僅加速寫作無法提升整體效率 2. **不再排隊的程式碼審查**: Agent 預先處理正確性，人類專注設計 3. **On-call 不再手動重建上下文**: Agent 自動收集證據並提出 RCA 4. **平台即核心**: 將所有環節串聯的統一平台 5. **SDLC 全面自動化**: 現在就可實現的未來 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ``` 寫程式只佔工作的 30% --> 僅加速寫程式會導致 Review 和 On-call 成為瓶頸 --> 引入具備上下文共享與工作移交能力的 Agent 平台 (Cosmos) --> Agent 自動化處理錯誤修正、風險路由與事件調查 --> 工程師的產出從 40% 提升至 3 倍，且品質提高。 ``` ### 關鍵證據 1. 在導入 Cosmos 後，大型 PR 的審查時間從 6-7 小時縮短至 45 分鐘，每週產出增加至三倍，且引入 Bug 的提交率下降。 2. On-call 事件處理（RCA 生成）的初步時間從 30 分鐘降至 6 分鐘，代理處理了 81.3% 的事件，讓工程師多合併了 44% 的 PR。 3. 透過 Deep Code Review 發現了一個隱藏的 Runtime 崩潰（舊提示檔被刪除但仍被參照），由 PR 作者修正後，人類審查者才介入針對「合併專家模板」的架構進行 Pair Review。 ### 隱形假設與邊界 * **隱形假設**: * Agent 具備足夠的上下文理解能力，可以精準判斷程式碼風險並提出可行的 RCA（根本原因分析）。 * 團隊使用的開發堆疊（Git, CI/CD, Issue Tracker）必須是標準且現代化的。 * **邊界條件**: * 如果團隊運行完全客製化的流程、特殊基礎設施或非標準的工作流，這套 Agent 平台的導入將面臨巨大挑戰。 * 如果風險分析器判斷錯誤（False low-risk），其代價將遠大於一次不必要的審查。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 文章主要關注於開發（Code/Review）與維運（Incident），但未深入討論產品需求分析、系統測試策略（如大規模整合測試）以及安全性稽核等環節如何被 Agent 取代。 * **知識連接**: 此概念與系統工程中的「阿姆達爾定律 (Amdahl's law)」直接相關，並呼應了「DevOps 自動化」與「平台工程 (Platform Engineering)」的演進。 * **行動觸發**: 開發團隊應該停止尋找「更好的 AI 補全工具」，轉而建立或導入「AI 協作平台」，將機械性工作交給 Agent，並重新培訓工程師的架構審查能力。 ### 跨域映射 * 在 **製造業**，這叫 **自動化生產線與品管分流 (Automated Assembly & QA Triage)** * 在 **雲端運算**，這叫 **無伺服器架構下的資源編排 (Serverless Orchestration)** --- # Agents can now run the full SDLC in Cosmos. What do engineers do? (Architectural Deep Dive) ## 前言/背景 隨著 AI 程式碼生成工具的普及，工程師寫程式的速度大幅提升。然而，軟體開發生命週期 (SDLC) 中僅有約 30% 的時間是用於編碼，剩餘的 70% 耗費在 Code Review、測試、事件回應 (Incident Response) 與規劃上。這導致了「阿姆達爾定律 (Amdahl's law)」效應：單純提升編碼速度，整體交付吞吐量幾乎沒有顯著增長。本文探討如何透過 Cosmos 這個統一代理平台 (Unified Agent Platform) 將審查、維運等流程自動化，從根本上改變軟體工程師的工作職責。 ## 章節詳細總結 ### The ceiling on coding agents (編碼代理的天花板) 作者指出，即使 IDE 和 CLI 具備強大的 AI 能力，端到端 (End-to-End) 功能交付的產出僅提升約 40%。因為瓶頸已經轉移到了後續的流程。 * **缺失的拼圖**：市場需要的不是另一個「會寫程式的 Agent」，而是一個能讓多個 Agents 共享上下文 (Share context)、記住模式 (Remember patterns)，並在不同開發階段之間**移交工作 (Hand work across stages)** 的系統。 * **流程對比**： * **大型 PR 審查**：過去需要排隊等待人類逐行閱讀；現在由 Agent 檢查正確性、處理例行修正，並準備一份聚焦的審查報告。 * **事件分流 (Incident triage)**：過去需要手動追蹤 Log、指標和最近的部署；現在由 Incident Investigator (事件調查 Agent) 直接在 Slack 中發布根本原因分析 (RCA) 與建議行動。 ### Code review stopped being a queue (程式碼審查不再需要排隊) 當程式碼生成速度加快，PR (Pull Requests) 開始堆積。此時的瓶頸是「信心 (Confidence)」——人類需要確保每一行程式碼都是安全的。 * **Deep Code Review + Pair Reviewer 工作流**： * 解決方案並非增加一個深度審查步驟，而是提取審查周圍的「機械性工作」並將其自動化。 * **實例**：作者提交了一個約 1000 行的 PR（合併兩個相似的事件回應範本）。在人類審閱之前，`Deep Code Review` 代理程式抓到了一個嚴重的 Runtime Bug：一個被刪除的 prompt 檔案仍被已部署的 bundle 參照。 * PR 作者直接在執行緒中修正此問題並推送 Commit。 * **架構層級的審查**：當人類介入時，審查者不再需要花費 7 小時閱讀被刪除的程式碼。他們啟動了 `Pair Reviewer` 會話，專注於架構設計的探討（例如：將兩個專家範本合併為一個是否為正確的設計決策？）。 * **效能數據**：引入此機制後，大型 PR 的審查時間從 6-7 小時縮減至 45 分鐘，每週產出達到 3 倍，同時減少了引入 Bug 的 Commit 數量。這依賴於保守的風險分析器（Risk Analyzer），因為誤判為低風險的代價遠高於一次多餘的審查。 ### On-call stopped being manual context reconstruction (On-call 不再是手動的上下文重建) 隨著開發與審查速度提升，維運負擔 (Operational load) 成為新的痛點。更快的交付意味著更多的警報與部署。 * **Incident Investigator (事件調查員)**： * 過去調查一個警報需要 30 分鐘，在 Slack、PagerDuty、Logs、Metrics 之間切換。 * 現在，Agent 在 Slack 中進行初步篩選，收集證據，發布包含建議修復路徑的 RCA，並將事件導向監控、程式碼修復或回滾 (Rollback)。 * 如果需要修改程式碼，Agent 會將修復任務移交給 `PR Author` 代理，並將結果送入 Review 流程。 * **效能數據**：首次產生 RCA 的時間從 30 分鐘降至 6 分鐘，整體處理時間減少了約三分之一。Agent 現在處理了 81.3% 的事件，使 On-call 工程師每週能多合併 44% 的 PR。 * **人類角色轉變**：工程師僅需檢視 RCA、提出後續問題並批准修復路徑，最終的生產環境決策 (Production call) 仍由人類掌握。 ### The platform is the point (平台才是重點) Code Review 和 Incident Response 不應是獨立的工具，它們必須在相同的平台上運行，以實現上下文共享與修正的延續。 * **工作流無縫移交**：一個警報可以從 RCA 移交至 Remediation（修復），再到 PR，最後進入 Review。工程師不再需要手動串接這些步驟。 * **工程師的職責轉型**：代理程式接管了讀取 Diff、追蹤 Log、重建上下文、編寫例行修復和總結證據等機械性工作。工程師的職責轉向： 1. 架構設計 (Architecture)。 2. 設定風險閾值 (Risk thresholds)。 3. 判斷 RCA 是否足夠準確。 4. 決定何時擴大自動批准 (Auto-approval) 範圍。 5. 當代理遺漏問題時，指導其如何改進。 * 這個轉變使得工程師的工作更具影響力，因為在人類介入之前，已經有大量的程式碼和事件通過了系統。 ## 總結與結論 1. **AI 的價值在於工作流編排而非單純補全**：突破 Amdahl's law 的關鍵，在於打造如 Cosmos 般能處理 Code Review、Testing 與 Incident Response 的統一平台，實現跨階段的 Context 共享。 2. **人類審查的昇華 (Shift to Intent Review)**：未來的 Code Review 將不再是逐行檢查語法或低階邏輯（由 Agent 的 Deep Code Review 處理），而是轉向「架構設計探討」與「高階風險評估」。 3. **On-call 機制的重塑**：透過 Incident Investigator 自動收集 Logs/Metrics 並產生初步 RCA，將 MTTA (Mean Time To Acknowledge) 與基礎排障時間縮減了 80%，讓維運人員能專注於決策與根因決策的批准。 4. **擁抱現代化工具鏈**：要能完美發揮 SDLC 自動化的潛力，企業必須具備標準化且現代化的 DevOps 基礎設施（如常見的 Git Workflows、CI/CD、Observability 堆疊），高度客製化或非標準流程將成為導入的阻礙。

--- tags: [AI工程, LangChain, LLMOps, Fine-tuning, Evaluator, Observability] date: 2026-06-16 read: false source: "2026-06-16T093650+0800-Building a 100x Cheaper Trace Judge with Fireworks.md" original_title: "Building a 100x Cheaper Trace Judge with Fireworks" --- # Building a 100x Cheaper Trace Judge with Fireworks  ## XRay 認知透視 ### 核心論點 (Core Thesis) 針對大規模生產環境中的 AI Agent 軌跡（Trace）數據，透過微調開源模型（如 Qwen-3.5-35B）作為特定任務（如「感知錯誤 Perceived Error」）的評判器（Judge），不僅能達到甚至超越前沿閉源模型（Frontier Models）的準確率，更能將推論成本大幅降低 10-100 倍。 ### 關鍵概念 (Key Concepts) - **Trace Judge (軌跡評判器)**：專門用於分析和評估 AI 與人類互動軌跡的模型，用於提取信號與回饋，為持續學習提供依據。 - **Perceived Error (感知錯誤)**：當用戶認為 AI 助手犯錯或產生需要修正的內容時所產生的錯誤。它不代表客觀正確性或用戶滿意度（例如 AI 給出正確答案但用戶仍對資訊感到挫折）。 - **Transfer Learning in Eval (評估器的遷移能力)**：在一個領域（如文件 Q&A）上訓練的感知錯誤評判模型，能夠有效地泛化至完全不同領域（如無代碼 AI 構建工具）的軌跡數據上，證明此類人類回饋信號具備普適性。 - **Model-Assisted Labeling (模型輔助標註)**：多模型協同的一致性過濾標註策略，利用「模型委員會」建立基準真實標籤（Ground Truth），只有在多輪模型都無法達成共識時才介入高成本的人工標註。 ### 為什麼這很重要？(Why it matters?) 隨著 Agent 應用投入生產環境，軌跡（Trace）成為理解系統行為的關鍵數據。然而，使用頂級閉源模型對所有海量日誌進行全量評估成本極高。此研究證明了「專用微調模型」是解決 LLM 系統持續學習（Continual Learning）與低成本全量觀測（Observability）的最佳工程實踐路徑。 --- ## Architectural Deep Dive ### 系統架構解析 1. **數據工程與前置處理** * **資料來源**：來自 LangChain 生產環境的兩套真實日誌：`chat-langchain` (技術文件 Q&A) 與 `Fleet` (任務型 Agent 創建工具)。 * **過濾策略**：僅選擇「多輪對話 (Multi-turn)」，因為感知錯誤的信號通常表現在後續的人類回應中（如糾正助手或重複請求）。 * **特徵工程 (Feature Selection)**：在訓練與預測時，**僅保留 Human 與 AI 訊息，刻意忽略所有 Tool calls (工具呼叫)**，並保留完整的長文本而不進行截斷。這大幅降低了輸入上下文的複雜度與 Token 成本，並聚焦在對話意圖上。 2. **標籤生成管線 (Label Generation Pipeline)** 採用三階段漸進式共識機制，最大化自動化比例： * **第一階段 (Panel 1)**：多個模型獨立評估同一筆軌跡。若全體一致，則直接作為 Ground Truth。 * **第二階段 (Panel 2 - Meta Judge)**：若第一階段產生分歧，將各模型的標籤與推理過程（Rationales）交給另一組模型委員會進行仲裁。若此階段達成一致，則作為 Ground Truth。 * **第三階段 (Human Review)**：若第二階段依然無法達成共識，才落入人工手動標註環節。 3. **微調策略與模型選擇** * **基底模型**：選用 `Qwen-3.5-35B`。團隊實驗發現，參數過小的模型錯誤率過高，缺乏跨多輪對話的推理能力。35B 級別具備足夠的推理深度，且擁有透過微調逼近前沿模型的空間。 * **訓練基礎設施**：在 Fireworks 平台上使用托管式的 LoRA 進行監督式微調（SFT）。 * **訓練集隔離**：為驗證模型的泛化能力，模型**僅在** `chat-langchain` 數據集上訓練，再將其直接應用於未見過的 `Fleet` 數據上進行推論驗證。 ### 技術權衡與決策 (Trade-offs & Decisions) * **閉源小模型 vs. 開源微調模型**：高併發低成本推論的常規解法是使用閉源小模型（如 Claude Haiku）。但團隊測試發現，透過良好提示的強大開源模型（Qwen base）在開箱即用的表現上即優於 Haiku，且微調後的開源模型在成本與性能上能形成雙重優勢。 * **過濾 Tool Calls 的利與弊**：忽略工具呼叫能節省大量 Token 並聚焦人類意圖，但也可能遺失導致 AI 決策錯誤的根因上下文。團隊將其作為當前版本的架構決策，並預留為未來迭代的實驗變數。 * **通用評判標準 vs. 應用專屬評判標準**：LangChain 過去強烈建議開發「應用專屬」的 Evaluator。但他們發現，「感知錯誤」的信號特徵（如用戶拒絕、糾正、重複請求）具有高度的領域通用性，這使得開發一個泛用型、開箱即用的 Evaluator 成為可能。 ### 效能表現與數據 * **準確度比較**： * 在 `chat-langchain` 測試集上：微調 Qwen 達到 **96.1%**，優於 Claude Opus (91.6%)，僅略遜於基準高標 GPT-5.5 (98.9%)。 * 在未見過的跨領域 `Fleet` 測試集上：僅用 `chat-langchain` 訓練的 Qwen 依然達到 **90.8%**，超越了 Claude Opus (90.2%) 與 GPT-5.5 (89.1%)。若進一步使用專屬 Fleet 數據微調，則可微升至 91.3%。 * **成本效益**：微調模型的推論成本視流量規模與對標模型而定，整體成本相較調用前沿模型節省了 10 到 100 倍，成功打破了在全量生產數據上運行複雜 Evaluator 的經濟壁壘。

--- tags: [AI工程, Agent架構, 系統架構, 軟體開發] date: 2026-06-16 read: false source: "2026-06-16T093752+0800-Factory 2.0 From coding agents to software factories.md" original_title: "Factory 2.0 From coding agents to software factories" --- # Factory 2.0: From coding agents to software factories  原始來源與檔名：2026-06-16T093752+0800-Factory 2.0 From coding agents to software factories.md --- ## NAPKIN | 餐巾纸 ### 餐巾紙公式 > (AI Agents + Model Independence + Sovereign Intelligence + Continual Learning) × Engineering Governance = Software Factory *這套公式說明，企業級軟體工廠不僅僅是單一 AI 代理的疊加，而是將獨立的模型路由、企業智能主權與持續學習的閉環，透過工程師的架構治理結合在一起的自動化生產線。* ### 一句話 > 軟體開發的未來不再是提升單一工程師的程式碼撰寫效率，而是建立端到端的自動化「軟體工廠」，讓 AI 代理負責開發，而工程師負責建造這座工廠。 ### 餐巾紙草圖 ``` [Signals: Bugs, Feedback, Requirements] │ ▼ +--------------+ | Triage/Plan | <--- Sovereign Intelligence (企業獨有上下文與記憶) +--------------+ │ ▼ +--------------+ | Build/Test | <--- Model Router (動態切換最佳模型/降低成本) +--------------+ │ ▼ +--------------+ | Deploy/Monitor|<--- Continual Learning (透過部署與事件監控形成反饋閉環) +--------------+ │ └────── [Agent Core / Shared Context] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這本書在說什麼"** * **核心問題**: 如何在企業層級實現超越單一工程師生產力提升的端到端自動化軟體開發？ * **核心答案**: 透過建立「軟體工廠 (Software Factory)」，以互聯的 AI 代理 (Agents) 為基礎單位，將軟體生命週期全面自動化，並由工程師來設計和管理這套系統。 * **論證結構**: 演繹型與願景宣告 (Vision Declaration)。從當前 AI 輔助編碼的局限性出發，推導出組織級自動化的必要條件，再展示其實踐路徑。 ### 章節骨架 1. **軟體工廠的定義**: 從單點效率提升轉向代理原生的端到端開發迴圈。 2. **三大核心支柱**: 模型獨立性、主權智能、持續學習與自我完善。 3. **漸進式自主架構**: 依任務難度從單點 Agent 到多軌並行的 Missions。 4. **工程師的典範轉移**: 從寫程式碼的工人轉為建造軟體工廠的架構師。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ``` 單一工程師效率提升遇瓶頸 --> 組織級效率需要端到端的持續反饋迴圈 --> 建立以 AI Agent 為增量單位的互聯系統 (軟體工廠) --> 此工廠需具備模型路由、資料主權與學習能力才能落地 --> 軟體工程師的角色轉移為「工廠的建造者與治理者」 ``` ### 關鍵證據 1. 這套理念已在全球大型企業（如 NVIDIA, EY, Adobe, Palo Alto Networks 等）投入生產驗證。 2. 實際運作展示：當資安掃描、Code Review 與事件排查在同一平台（共享 Agent Core）上運行時，一個資安發現能直接指導後續的 Code Review，形成自動擴展的知識網絡。 3. 技術架構上的實現：提供多層次的執行環境（Droids, Droid Computers, Missions），以應對從簡單腳本到耗時數天的複雜並行開發任務。 ### 隱形假設與邊界 * **隱形假設**: * 企業願意將核心的軟體生命週期 (SDLC) 逐步交由 AI 代理自主運行，並信任其產出的代碼品質。 * AI 模型的能力會持續商品化且成本下降，使得動態多模型路由 (Model Router) 成為經濟上的最佳實踐。 * **邊界條件**: * 如果組織的開發工作流與流程完全未標準化，缺乏清晰的 API 邊界與自動化測試驗證，這套系統將無法有效推行。 * 在極高合規要求且無法提供完全 Air-gapped (物理隔離) 部署的環境下，方案可能受阻。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 如何處理 AI 代理產生的隱性技術債？當所有程式碼均由多個 AI 代理自動生成並互相修改時，系統架構的長期可維護性、一致性與除錯複雜度該如何有效控制？ * **知識連接**: 類似於工業革命中「手工作坊轉向自動化流水線」的演進，以及現代運維理念 DevOps 走向極致的「NoOps / AgentOps」。 * **行動觸發**: 工程團隊應停止只尋找「更強的程式碼補全工具」，而是開始盤點組織內的開發流程，將其高度標準化並設計為可被 AI 代理接管的 API 節點與檢驗關卡。 ### 跨域映射 * 在 **工業製造**，這叫 **自動化流水線 (Automated Assembly Line)**。 * 在 **基礎設施運維**，這叫 **無人運維 (NoOps)**。 --- # Factory 2.0: From coding agents to software factories (Architectural Deep Dive) ## 前言/背景 當前多數企業導入 AI 仍停留在「程式碼補全工具 (Copilots)」的階段，僅能提升單一工程師的局部生產力。這篇文章探討如何突破此瓶頸，提出一套端到端、由 AI Agent 為增量單元構成的「軟體工廠 (Software Factory)」架構。它解決了企業級自動化開發在模型依賴、資料主權以及上下文割裂上的核心問題，並宣告工程師即將面臨從「寫碼者」到「工廠架構師」的典範轉移。 ## 章節詳細總結 ### 軟體工廠的端到端運作迴圈 (The Software Factory Loop) 軟體工廠是一個具備自我觀察與完善能力的互聯 AI 代理系統。其核心架構是一個**持續的反饋迴圈 (Continuous Feedback Loop)**： * **信號觸發**：系統的起點來自外部信號，例如 Bug 報告、Slack 上的內部對話、客戶反饋與業務需求 (Business Requirements)。 * **計畫與執行**：信號被分流處理並轉化為具體的程式碼變更計畫，接續進入構建、測試、審查、安全掃描、交付等流程。 * **監控與反饋**：部署後的軟體透過監控系統生成新的信號，這些信號再次回饋到工廠系統中。這要求整個迴圈必須被高度 Instrumentation（儀表化）且 AI 驅動。 ### 強健軟體工廠的三大架構支柱 要建立企業級的軟體工廠，架構設計上必須滿足三個關鍵條件： 1. **模型獨立性 (Model Independence)** * 沒有任何單一模型能完美適應企業內部的所有任務。架構設計必須解耦任務與底層大模型，透過引入 **模型路由器 (Router)** 來進行動態調度。 * 路由器的運作原理是根據特定任務在「成本、性能、速度」之間的權衡，自動（或基於規則）選擇最合適的模型。隨著 LLM 逐漸商品化，這種動態路由機制能夠在提升執行速度的同時大幅壓低推理成本。 2. **主權智能 (Sovereign Intelligence)** * 企業必須對軟體工廠擁有絕對的主權。這不僅是基礎設施的選擇（如雲端託管、Bring-Your-Own-Key、自託管資料層、歐盟專屬或完全的物理隔離 Air-gapped 網路限制）。 * 架構的核心意義在於：這是一個**具有記憶的閉環系統**。每一次 Agent 的 PR 審查或事件排查，都會被向量化並回饋至系統，成為組織專屬的私有 Context，確保智能與能力累積在企業內部。 3. **持續學習與自我完善 (Continual Learning and Self-Improvement)** * 當所有的 SDLC 流程（程式碼審查、安全掃描、文件生成、QA 測試、事件響應）都在同一個平台上運行時，它們能**共享同一個 Agent Core 與模型路由器**。 * **連鎖反應機制**：一個模塊的輸出是另一個模塊的輸入。例如，一項安全掃描的發現會自動通知 Code Review Agent 調整審查標準；一次成功的部署會觸發文件更新；監控報警會自動與導致它的 PR 進行關聯分析。 ### 漸進式自主架構的實踐 (Spectrum of Autonomy) 完全自主的開發不是一蹴可幾的，架構上需提供不同複雜度的執行環境，來適應組織對 AI 的準備度 (Agent Readiness) 與資訊敏感度： * **Droids / Skills**: 用於運行定義明確、可測量的單點任務，負責處理日常且具體的自動化邏輯。 * **Droid Computers**: 為了需要**遠端且持久性執行 (Persistent execution)** 的長期任務所設計，通常擁有本地環境或常駐的進程支持。 * **Missions (多代理協作)**: 用於解決耗時數小時到數天的複雜任務。其架構原理是將大型任務拆解成多條平行的執行軌道 (Parallel tracks)，並透過共享目標與記憶的多個 Agent 進行非同步協同處理。 ### 工程師角色的典範轉移 在高度自動化的未來，軟體工程師不再是唯一手寫程式碼的執行者。他們的職責將跨越業務與技術邊界，負責**建造這些「軟體工廠」**。工程師的核心技能將轉向：如何編排 (Orchestrate) 代理工作流、管理自動化流程的安全性 (Safety) 與治理 (Governance)，以及為最終的商業結果負責。 ## 總結與結論 * **解耦模型與任務依賴 (Model Router Pattern)**：在架構系統時，必須加入模型抽象層（Router），避免被單一供應商綁定，並隨時捕捉開源/商用模型商品化帶來的效能套利空間。 * **打通資料孤島，建立共享上下文 (Shared Context Core)**：不要建立散落的 AI 小工具，應將 Code Review、CI/CD 掃描與 APM 監控日誌打通，讓所有 Agent 共用同一個企業上下文底座，讓資安與 QA 的學習能即時回饋至開發階段。 * **長週期與非同步架構 (Long-horizon Execution)**：應對複雜需求，需設計支援長時間運行及狀態持久化的代理基礎設施（如文中的 Droid Computers 與 Missions），並將任務平行化。 * **標準化是代理化的先決條件**：要讓 Agent 接管工作，企業必須先透過嚴謹的工程手段標準化其開發流程與環境，AI 只能在邊界清晰的系統中實現高可靠的自動化。

--- tags: [AI工程, 架構設計, 非同步處理, 系統設計] date: 2026-06-16 read: false source: "2026-06-16T094211+0800-OpenAI Background Mode Still Needs a Job System.md" original_title: "OpenAI Background Mode Still Needs a Job System" --- # OpenAI Background Mode Still Needs a Job System  原始來源與檔名：2026-06-16T094211+0800-OpenAI Background Mode Still Needs a Job System.md --- ## NAPKIN | 餐巾紙 ### 餐巾紙公式 > 穩健的 AI 任務系統 = OpenAI Background Mode + 產品專屬 Job 表 + Webhook 通知 + 慢速輪詢兜底 _API 的 background mode 僅解決連線等待問題，你的系統仍需自行管理任務狀態、重試與資料一致性。_ ### 一句話 > 別把供應商的 Response ID 當作你的業務 Job，就算 AI 在背景執行，你還是需要一個扎實的非同步任務系統來掌控全局。 ### 餐巾紙草圖 ```text [ 客戶端 ] --> (建立任務) --> [ 你的系統 DB (Job Table) ] --> (呼叫 API) --> [ OpenAI Background API ] | ^ | | | | v | +-----(查詢/進度)--------------+ [ Worker ] <-----(Webhook 事件)------+ | | +<------(慢速輪詢兜底)----------------------+ ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 當使用 OpenAI 的 Background Responses API 處理耗時任務時，如何確保系統的穩定性與使用者體驗？ * **核心答案**: 建立一個產品專屬的 Job 系統來隔離供應商的處理狀態，並結合 Webhook 與慢速輪詢來維持狀態一致性。 * **論證結構**: 演繹與實踐案例結合 ### 章節骨架 1. **API 解決了連線問題**: 背景模式避免了客戶端長連線，但沒有解決產品狀態管理。 2. **常見錯誤是將 Response ID 視為 Job**: 產品需要自己的 Job 記錄，包含更多業務相關欄位。 3. **Webhook 只是通知而非工作單元**: 必須處理重複事件，避免重複執行。 4. **輪詢是兜底機制**: Webhook 走 Happy Path，輪詢修補遺漏的事件。 5. **串流背景回應增加新狀態**: 串流只代表進度，不等於最終完成狀態。 6. **資料保留影響設計**: Background Mode 強制開啟 `store=true`，需考慮隱私合規。 7. **取消操作需要產品規則**: 供應商的取消和產品的取消狀態需要映射。 8. **生產環境模式**: 建立任務表的 10 步驟實戰指南。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text 長連線容易中斷 --> 背景模式解決了連線問題 --> 但背景模式只提供 Response ID --> 應用程式仍不知道任務的業務脈絡 --> 必須建立專屬 Job Table 儲存狀態 --> Webhook 通知可能遺漏或重複 --> 結合冪等處理與慢速輪詢兜底 --> 形成高可靠的非同步 AI 架構 ``` ### 關鍵證據 1. OpenAI 文件明示：「背景模式執行模型呼叫。它不應該成為你整個任務佇列。」 2. Webhook 事件可能會重複發送（rare cases），如果處理邏輯不是冪等的，將導致重複扣款或發送多封 Email。 3. Background API 要求開啟 `store=true` 才能進行輪詢，這會將資料保留至少 10 分鐘（預設 30 天），違反某些企業的零資料保留政策。 ### 隱形假設與邊界 * **隱形假設**: * 開發者有能力建構關聯式資料庫（如 PostgreSQL）來維護 Job 狀態並支援 Transaction / Lock。 * 系統架構中已經存在背景 Worker 機制可以處理非同步任務。 * **邊界條件**: * 當使用者的資料具有極高機密性，不允許 OpenAI 儲存資料時，此背景輪詢方案將失效（因為 `store=true` 的限制）。 * 在開發環境下沒有正確配置 Local Tunnel，會導致 Webhook 接收失敗。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 未詳細討論大規模併發情況下的 Job Table 鎖定效能瓶頸，以及分散式系統中如何優化慢速輪詢（例如分片掃描）。 * **知識連接**: 此架構與分散式系統中的「Outbox Pattern」或「Saga Pattern」中的補償機制高度相似，都是為了解決外部系統與內部狀態最終一致性的問題。 * **行動觸發**: 檢查現有專案中直接依賴外部 API Response ID 的地方，重構並引入本地的 Job Table 進行隔離與管理。 ### 跨域映射 * 在 **微服務架構**，這叫 **最終一致性 (Eventual Consistency) 與補償機制**。 * 在 **支付系統**，這叫 **非同步通知 (Webhook) 與主動查單 (Polling)**。 ## STRUCTURE MAP | 全書結構圖 ```text [ 使用者請求 ] | v +------------------+ | 建立本地 Job | (UUID, Status, Input Hash) +------------------+ | +--------------+---------------+ | | v v [ 呼叫 OpenAI API ] [ 儲存 Response ID ] (background=true) | | v | [ 返回 Job ID 給前端 ] | | | (異步通知) v +-----> [ Webhook ] ---> [ 驗證與冪等處理 ] | | | v | +-------------------+ +-----> [ Polling ] | 更新本地 Job 狀態 | (慢速兜底輪詢) +-------------------+ | v [ 前端獲取最終結果 ] ``` --- # OpenAI Background Mode Still Needs a Job System (Architectural Deep Dive) ## 前言/背景 當我們使用 OpenAI 的 Responses API 處理長達數分鐘的複雜推理任務時，傳統的同步 HTTP 請求往往會因為超時或客戶端斷線而失敗。儘管 OpenAI 推出了 Background Mode（背景模式）將長時間運行的工作移出請求路徑，但這篇文章犀利地指出：**API 提供的背景模式不能取代應用程式自己的 Job 系統**。本文探討如何圍繞 Background Responses 建立一個具備容錯能力、冪等性且符合業務邏輯的非同步任務管理架構。 ## 章節詳細總結 ### API 解決連線痛點，但無法承擔業務職責 Background Mode 的確解決了最直接的問題：模型可以花費數分鐘處理大型文件，而不需要伺服器或行動裝置保持 HTTP 連線開啟。然而，它沒有回答產品設計的核心問題： * 誰擁有工作狀態？ * 如何避免 Webhook 重複處理？ * 何時該取消任務？ 作者引用了文件中的直白觀點：*「背景模式執行模型呼叫。它不應該成為你整個任務佇列 (Job Queue)。」* ### 常見錯誤：把 Response ID 當成 Job 開發者常犯的錯誤是將 OpenAI 回傳的 `response_id` 視為系統的唯一任務識別碼。`response_id` 只是供應商端的操作把手，應用程式需要一個有意義的 Job 記錄。 這個 Job 記錄應該包含租戶、使用者、請求類型、輸入的 Hash 值、超時策略以及取消狀態。 **具體的結構設計建議（至少需要包含以下欄位）**： ```sql create table ai_jobs ( id uuid primary key, user_id text not null, status text not null, response_id text, -- OpenAI 的 Response ID last_event_id text, -- 用於冪等性校驗的 Webhook 事件 ID input_hash text not null, created_at timestamptz not null, finished_at timestamptz ); ``` **架構決策理由**：這個 Table 是你的「單一真實來源 (Source of Truth)」。Response ID 只是外部供應商的附屬品，任務 ID 才真正屬於你的產品。 ### Webhook 是通知，而非工作單元 (Work Units) OpenAI 會在任務完成、失敗或取消時發送 Webhook（如 `response.completed`）。然而，Webhook 的 Handler 不該執行繁重的業務邏輯。 * **最佳實踐**：端點應該快速回傳 `2xx` 狀態碼，並將工作卸載到背景 Worker。 * **冪等性 (Idempotency) 處理**：OpenAI 文件表明，在罕見情況下可能會發生「重複的 Webhook 事件」。因此，必須使用 Headers 中的 `webhook-id` 作為冪等鍵 (Idempotency Key)。在處理事件時，鎖定 `ai_jobs` 資料列，檢查並儲存 Event ID，確保不會發送兩封信或重複扣除 Credit。 ### Polling（輪詢）作為防護網 (Fallback) 雖然 Webhook 是處理完成事件的理想方式，但它可能會因為端點宕機、佇列崩潰或資料庫鎖定而遺失。因此，必須實作**慢速輪詢 (Slow Polling)** 作為兜底機制。 * **運作原理**：實作一個背景對帳 Worker (Reconciliation Worker)，定期掃描 `ai_jobs` 表中處於「非最終狀態」的任務，主動向 OpenAI API 查詢狀態並修補遺漏的轉換。 * **黃金守則**：Webhook 負責 Happy Path，Polling 負責修補邊界錯誤。這樣可以避免無止盡的瘋狂輪詢，節省 API 呼叫成本與系統資源。 ### 串流背景回應引入了多重狀態 如果在建立 Background Response 時同時開啟 `stream=true`，系統將需要追蹤 `sequence_number` 作為游標 (Cursor)。 這在架構上區分了幾個層次： * **Stream Events**：僅用於 UI 進度展示。 * **Webhook Event**：作為完成的訊號。 * **Retrieve Call**：用於獲取最終結果。 * **Job Record**：產品層面的真實狀態。 將這些關注點分離，可以避免在偵錯時陷入混亂。 ### 資料保留 (Data Retention) 的架構衝擊 使用背景模式需要特別注意資料隱私。OpenAI 要求背景採樣必須設定 `store=true`，這意味著拒絕無狀態請求。 資料預設會被保留 30 天，為了輪詢，背景模式至少會將資料寫入磁碟 10 分鐘。如果企業有嚴格的零資料保留 (Zero-data-retention) 規定，這個限制將直接影響系統架構設計，必須在正式上線前確認合規性。 ### 取消機制 (Cancellation) 需建立產品規則 OpenAI 允許取消正在執行中的背景回應，且重複取消是冪等的。然而，你的系統必須有更豐富的「產品級取消規則」。 不管是使用者主動點擊取消、超時被系統終止，還是權限檢查失敗，都需要在資料庫中記錄細緻的狀態（如 `cancel_requested`, `cancelled_remote`, `expired` 等）。這能防止系統在使用者已經取消任務後，還向前端推播過時的 AI 產出。 ### 生產環境的實作模式 (The Production Pattern) 作者總結了一個安全的 v1 版本流程： 1. 呼叫 API 前，先在 `ai_jobs` 建立一筆資料。 2. 提交 Background Response，並更新儲存 `response_id`。 3. 將**你自己的 `job_id`** 返回給 Client 端。 4. Webhook 僅用於將後續工作放入佇列 (Enqueue)。 5. 在執行後端邏輯前，嚴格驗證 Webhook 簽章。 6. 使用 `webhook-id` 進行去重 (Deduplication)。 7. 在 Worker 中擷取最終回應。 8. **在 Transaction 或 Lock 的保護下**，執行狀態轉換。 9. 維持一個慢速的 Polling 對帳程式來處理遺漏事件。 ## 總結與結論 * **所有權隔離 (Ownership Isolation)**：永遠不要將第三方服務的識別碼 (Response ID) 作為系統內部的主要關聯鍵。必須透過本地的 Job 系統來隔離外部供應商的狀態，將主導權留在自己手上。 * **Eventual Consistency 的雙保險**：在處理外部非同步狀態時，始終採用「Webhook 驅動即時更新 + 慢速 Polling 對帳兜底」的雙軌架構，這是高可用性系統的標配。 * **防禦性與冪等性設計**：無論是 Webhook 還是本地的 Worker 重試，所有的狀態轉換都必須依賴 Transaction 和 Idempotency Key (`webhook-id`)，確保在重試風暴中不會產生髒資料或重複扣款。 * **狀態與進度解耦**：Streaming 事件只應該視為 UI 層面的「進度指示器」，系統的最終狀態確認與結果落盤，必須依賴 Webhook 通知及本地 Job Table 的原子操作。

--- tags: [AI工程, LLM, 系統架構, 工具實踐] date: 2026-06-16 read: false source: "2026-06-16T093747+0800-The 2026 LLM Engineering Roadmap (with free and 100% open-source resources).md" original_title: "The 2026 LLM Engineering Roadmap (with free and 100% open-source resources)" --- # The 2026 LLM Engineering Roadmap (with free and 100% open-source resources)  原始來源與檔名：2026-06-16T093747+0800-The 2026 LLM Engineering Roadmap (with free and 100% open-source resources).md --- ## NAPKIN | 餐巾紙 ### 餐巾紙公式 > LLM Engineering = Prompting × (RAG + Context) × Fine-tuning × Agents / (Deployment + Optimization + Evals) _建構生產級 LLM 系統不只是依賴提示詞，還需要整合檢索、上下文管理、微調與代理機制，並由部署、優化與評估監控來支撐整體穩定性。_ ### 一句話 > 生產級的 LLM 開發是涵蓋提示工程、RAG、上下文工程、微調、代理、部署、優化及監控的八大支柱系統工程。 ### 餐巾紙草圖 ``` [Prompt] -> [Context/RAG] -> [LLM Core / Fine-tuning] -> [Agent Logic] -> [Output] | [Optimization] | [Observability & Evals] ------+------ [Deployment / vLLM / LitServe] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 建立生產級 (Production-grade) LLM 系統需要具備哪些深度工程知識與技能？ * **核心答案**: 開發者必須掌握提示工程、RAG、上下文工程、微調、AI 代理、部署、模型優化以及安全評估這八大支柱。 * **論證結構**: 歸納型（將複雜的 LLM 工程拆解為 8 個循序漸進的關鍵領域並提供相應資源）。 ### 章節骨架 1. **Prompt engineering**: 提示工程是起點與最經濟的槓桿。 2. **RAG systems**: 解決模型未知數據的檢索增強生成。 3. **Context engineering**: 決定上下文中 Token 配置的權衡。 4. **Fine-tuning**: 使用 LoRA 等技術微調權重以適應領域需求。 5. **Agents**: 編排多工具呼叫與狀態管理。 6. **LLM deployment**: 將 LLMOps 與 DevOps 區分，處理併發與部署。 7. **LLM optimization**: 透過量化等技術降低推論成本與記憶體。 8. **Safety, Evals & observability**: 確保系統輸出品質與即時監控。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ``` 提示詞達到瓶頸 --> 需要外部知識 (RAG) 與更好的記憶分配 (Context) --> 基礎模型能力不足 --> 針對領域微調 (Fine-tuning) --> 需要自主執行複雜任務 --> 建構代理 (Agents) --> 走向生產環境 --> 解決部署 (Deployment)、優化成本 (Optimization) 及品質監控 (Evals & Observability) ``` ### 關鍵證據 1. RAG 透過將文件嵌入到向量索引中，並在查詢時取回頂部區塊拼接到提示中，解決了模型知識的截止日期與隱私資料問題。 2. vLLM 使用 PagedAttention 將 KV cache 的浪費從 60-80% 降低至不到 4%，相比 TGI 提高了 2-4 倍的吞吐量。 3. 量化技術 (Quantization) 將權重從 FP16 降至 4-bit (如 llama.cpp 中的 Q4_K_M)，成本不到 1% 的困惑度 (perplexity) 卻能減少近 4 倍記憶體，使 70B 模型能放進單張 24GB GPU 中。 ### 隱形假設與邊界 * **隱形假設**: * 開發者已經具備基本的 Python 程式設計能力與機器學習概念。 * 開源工具與社群資源足以支撐企業級的生產環境部署。 * **邊界條件**: * 當企業對資料隱私有絕對的封閉需求時，某些依賴公有 API 的做法 (如 LiteLLM 的某些路由) 可能不適用，需完全地端部署。 * 硬體資源若遠低於 24GB GPU，可能連量化後的 70B 模型都無法運行，需退而使用更小的模型。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 雖然提到了八大支柱，但在資料工程 (Data Engineering) 方面的著墨較少，特別是 RAG 和微調前置的資料清洗與 ETL 流程，這在生產環境中往往是最大的痛點。 * **知識連接**: 這種系統性的拆解與傳統的微服務架構 (Microservices) 或 DevOps 管道有異曲同工之妙，但加入了「機率性輸出」的變數，因此需要不同的測試 (Evals) 與優化策略。 * **行動觸發**: 團隊在構建 LLM 應用時，應停止單純的 API 呼叫，轉而建立包含評估集 (Evals)、監控 (Observability) 與推論優化 (如 vLLM/量化) 的完整標準作業流程。 ### 跨域映射 * 在 **傳統軟體工程**，這叫 **系統架構設計與 DevOps**。 * 在 **機器學習領域**，這叫 **MLOps 管道**。 --- # The 2026 LLM Engineering Roadmap (with free and 100% open-source resources) (Architectural Deep Dive) ## 前言/背景 本文旨在解決開發者在構建大型語言模型 (LLM) 應用時，僅停留在「提示詞 (Prompting)」層面的盲點。文章指出生產級 (Production-grade) 系統需要對 LLM 的工程化、部署與優化有深度的理解，並將其系統性地拆解為八大支柱 (Pillars)，為開發者提供了一條清晰的學習與實踐路徑，並附帶 100% 開源且免費的資源。 ## 章節詳細總結 ### 1. 提示工程 (Prompt Engineering) 提示工程是開發 LLM 應用的起點，因為它是成本最低的控制槓桿。在引入複雜的 RAG 或微調前，應先榨乾提示詞的潛力。 * **核心策略**：撰寫能減少歧義的指令，使用小樣本 (Few-shot) 範例來錨定輸出格式，並利用思維鏈 (Chain-of-thought) 來穩定模型的推理過程。 * **工程化思維**：應將提示詞視為程式碼 (Code) 來看待，這意味著它們需要被妥善地進行版本控制 (Versioned)、測試 (Tested) 以及確保可重複性 (Reproducible)，而不是一次性的複製貼上。 ### 2. 檢索增強生成系統 (RAG Systems) 當問題需要模型從未見過的資料 (如公司內部文件、客戶歷史紀錄或超出訓練截止日期的資訊) 時，純粹的提示詞就會碰壁，此時需要 RAG。 * **運作原理**：將文件進行嵌入 (Embedding) 並存入向量索引 (Vector Index)。在查詢時，檢索出最相關的文本區塊 (Top chunks)，並將它們串接 (Concatenate) 到提示詞中。 * **關鍵技術管線**：一個可運作的 RAG 系統必須處理以下核心技術： * 區塊大小與重疊率 (Chunk size and overlap) 的設定。 * 檢索前的查詢重寫 (Query rewriting)。 * 檢索後使用交叉編碼器 (Cross-encoder) 進行重新排序 (Reranking)。 ### 3. 上下文工程 (Context Engineering) 模型的上下文視窗 (Context window) 資源有限，檢索只是其中一個輸入。 * **資源競爭**：對話歷史、工具輸出、過去會話的記憶、系統提示詞以及小樣本範例都在競爭相同的 Token 空間。 * **架構決策**：上下文工程是一門決定「保留什麼、壓縮什麼、丟棄什麼」的學問。因為每個 Token 都代表著金錢成本，且過多的上下文會稀釋模型的注意力 (Attention)。RAG 只是解決此巨大問題的其中一項工具。 ### 4. 模型微調 (Fine-tuning) 當提示工程與上下文工程達到極限時，下一個可動用的槓桿就是修改模型的權重 (Weights)。 * **高效微調技術 (PEFT)**：使用 LoRA (Low-Rank Adaptation) 和 QLoRA 可以在單張 GPU 上對基礎模型進行適配。其原理是不訓練完整的參數集，而是訓練小型的低秩矩陣 (Low-rank matrices)。這通常只需要幾千個範例就能彌補特定領域的知識差距。 * **資料工程的挑戰**：微調的訓練迴圈 (Training loop) 相對簡單，真正的難點在於資料處理。這包含了資料去重 (Deduplication)、指令格式化 (Instruction formatting) 以及品質過濾 (Quality filtering)。 ### 5. AI 代理 (Agents) 代理機制擴展了 LLM 的迴圈，使模型能夠選擇工具、呼叫工具、讀取結果，並決定下一步行動，直到任務完成。 * **編排與狀態管理 (Orchestration)**：工程的重心在於編排層。這包含跨回合 (Across turns) 的狀態管理、當工具返回垃圾資料時的重試邏輯 (Retry logic)、防止無限迴圈的步驟限制 (Step limits)，以及模型選擇錯誤工具時的優雅降級/失效處理 (Graceful failure)。 ### 6. LLM 部署 (LLM Deployment) 部署關注於處理高併發請求、負載下的擴展能力，以及在流量激增時控制延遲 (Latency)。 * **LLMOps vs DevOps**：許多團隊試圖將 DevOps 實踐套用在 LLM 應用上，但這兩者解決的是根本上不同的問題，LLMOps 需要針對模型推理的特性進行優化。 * **推論引擎架構 (Inference Engine)**： * **vLLM**：使用 **PagedAttention** 技術，將 KV Cache 的記憶體浪費從 60-80% 大幅降低至不到 4%。在相同的硬體上，其吞吐量 (Throughput) 可比 TGI 提升 2 到 4 倍，是開源模型服務的標準選擇。 * **服務層與閘道器**：架構上還需要疊加服務層 (如 LitServe，基於 FastAPI 構建，專注於批次處理與串流) 以及 LLM 閘道器 (如 LiteLLM，用於統一 API、路由控制與成本追蹤)。 ### 7. LLM 優化 (LLM Optimization) 推論的帳單會讓優化技能變得至關重要。 * **量化 (Quantization)**：這是降低成本最大的槓桿。將權重從 FP16 降至 4-bit (例如 llama.cpp 中的 `Q4_K_M`)，通常只會損失不到 1% 的困惑度 (Perplexity)，卻能減少大約 4 倍的記憶體佔用。這正是 70B 參數的模型能夠擠進單張 24GB GPU 的關鍵技術。 * **其他技術**： * **知識蒸餾 (Distillation)**：在大型教師模型 (Teacher) 的輸出上訓練較小的學生模型 (Student)。 * **剪枝 (Pruning)**：移除低於特定閾值的權重。 * **基準測試**：所有的優化折衷方案都必須在實際的工作負載 (Actual workload) 上進行測試，而非依賴通用的評估指標。 ### 8. 安全、評估與 LLM 監控 (Safety, Evals & LLM Observability) 如果無法得知系統是否正常運作，上述的努力皆為枉然。 * **評估 (Evals) - 「輸出好嗎？」**：在部署前使用黃金資料集 (Golden datasets) 運行，作為每次提示詞或模型變更時的迴歸測試 (Regression check)。 * **監控 (Observability) - 「現在發生了什麼？」**：追蹤生產環境中的即時請求、監控 Token 使用量與延遲，並浮現實際環境中的錯誤 (Failures in production)。 * **安全性 (Safety)**：針對提示詞注入 (Prompt injection) 建立實用的防禦機制，是每個 LLM 應用必備的條件。 ## 總結與結論 * **架構分層與解耦**：生產級 LLM 系統不該是一個單體腳本，而應解耦為提示控制、知識檢索 (RAG)、狀態代理 (Agents) 以及推論優化 (vLLM/LitServe) 等多個可獨立擴展的層級。 * **記憶體管理是推論的核心**：在部署架構中，採用 PagedAttention 等技術來最佳化 KV Cache，以及透過 INT4/8 量化技術，是解決 GPU 記憶體瓶頸與提升吞吐量 (Throughput) 的架構關鍵。 * **以數據為中心的工程 (Data-Centric Engineering)**：無論是 RAG 的區塊檢索、微調的資料清洗，還是 Evals 的黃金資料集，LLM 工程的成敗高度依賴於前置資料處理的品質，而非僅是模型本身的演算法。 * **建立雙軌品質保證體系**：架構設計必須同時包含部署前的自動化評估 (Evals) 與部署後的即時監控 (Observability)，以應對 LLM 輸出的非確定性 (Non-deterministic) 本質。

--- tags: [AI工程, Agent架構, 系統架構, 系統工程] date: 2026-06-16 read: false source: "2026-06-16T093934+0800-从 Prompt 到 loop：AI 工程正在走向 Runtime.md" original_title: "从 Prompt 到 loop：AI 工程正在走向 Runtime" --- # 从 Prompt 到 loop：AI 工程正在走向 Runtime  原始來源與檔名：2026-06-16T093934+0800-从 Prompt 到 loop：AI 工程正在走向 Runtime.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > Agent = Model(機率核心) + Runtime(控制層: Context + Harness + Loop) *將不穩定的機率模型封裝在可控的工程環境中，實現持續且穩定的自動化執行。* ### 一句话 > AI 系統的演進，是從「人呼叫單一 AI 函數」轉變為「AI 在人類設計的 Runtime (運行環境) 中持續進行主循環運作」。 ### 餐巾纸草图 ```text +-----------------------------------+ | Agent Runtime | | +-----------------------------+ | | | Loop (持續運行控制/狀態機) | | | | +-----------------------+ | | | | | Harness (執行外殼/沙盒| | | | | | +-----------------+ | | | | | | | Context (記憶) | | | | | | | | +-----------+ | | | | | | | | | Prompt | | | | | | | | | | (函數參數)| | | | | | | | | +-----------+ | | | | | | | +-----------------+ | | | | | +-----------------------+ | | | +-----------------------------+ | +-----------------------------------+ ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: AI 系統在落地至真實工程環境時，為何單靠 Prompt Engineering 無法解決系統穩定性與持續運作的問題？ * **核心答案**: 因為 AI 正在從被動調用的函數轉變為持續運行的系統，真正決定穩定性的不再是模型本身，而是包覆模型的控制層（Runtime）。 * **論證結構**: 層次遞進型 (Prompt -> Context -> Harness -> Loop) ### 章節骨架 1. **Prompt**: 解決輸入問題，作為底層呼叫參數。 2. **Context**: 解決資訊問題，提供精確的工作現場。 3. **Harness**: 解決邊界問題，提供受控的執行外殼。 4. **Loop**: 解決持續運行，構建主循環與防錯機制。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text 單純呼叫Prompt易缺背景知識 --> 需引入Context提供工作現場 --> AI依據Context開始呼叫工具產生越權風險 --> 需Harness建立沙盒與權限邊界 --> AI要完成複雜目標需持續迭代 --> 需Loop主循環來規劃與修正 --> 結論：AI工程就是打造可控的Runtime ``` ### 關鍵證據 1. **資訊隔離導致幻覺**：在修復程式碼或分析業務時，不給予完整的 Context（真實規則和資料），AI 只能憑空捏造，放大幻覺。 2. **權限失控導致事故**：當 AI 具備呼叫工具的能力（讀寫檔案、執行命令）後，若無 Harness 控制權限與紀錄日誌，無限重試或錯誤調用將直接演變成系統災難。 3. **主循環的典範轉移**：早期的 `output = model(prompt)` 已被 `while not done: plan() act() observe() evaluate() repair()` 取代，AI 正在承接系統的主循環任務。 ### 隱形假設與邊界條件 * **隱形假設**: * 大型語言模型本質上是不穩定的機率模型，必然會產生合理的錯誤。 * 賦予 AI 的工具數量與系統能力並不成正比，工具越多代表權限越大，風險也呈指數上升。 * **邊界條件**: * 在僅需單次文本生成的場景（如純翻譯、簡單摘要），傳統的 Prompt Engineering 即已足夠，不需過度設計 Runtime。 * 當 Loop 缺乏明確的退出條件 (Exit Condition) 或回滾機制時，系統會陷入「事故自動化」的無限迴圈。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 本文側重於概念演進的框架，但未深入探討在高併發或分散式架構下，Agent 狀態如何持久化，以及 Context 上下文窗口管理的具體工程極限。 * **知識連接**: 與軟體工程中的作業系統設計 (OS Kernel Sandbox vs User Application)、狀態機設計 (State Machine)、及分散式系統的重試與斷路器機制 (Circuit Breaker) 高度脗合。 * **行動觸發**: 停止盲目優化冗長的 Prompt，將開發資源轉移到建立具有權限控制、日誌追蹤及回滾機制的 Agent Runtime 框架上。 ### 跨域映射 * 在 **作業系統工程**，這叫 **沙盒隔離與資源排程 (Sandboxing & Scheduling)** * 在 **控制理論**，這叫 **閉環回饋控制系統 (Closed-loop Feedback System)** --- # 从 Prompt 到 loop：AI 工程正在走向 Runtime (Architectural Deep Dive) ## 前言/背景 本文探討了過去一年 AI 應用程式在軟體架構層面的根本性典範轉移。傳統上，AI 被視為一個單次呼叫的無狀態函數（Stateless Function），依賴輸入提示詞來產生回覆；然而，現代 AI 應用正在演化為具備自主規劃、狀態管理與工具操作能力的代理系統（Agentic System）。為了解決機率模型固有的不穩定性，架構師必須設計並實作一個完整的控制層（Runtime），將 AI 從單純的生成工具轉換為可控的閉環執行系統。 ## 章節詳細總結 ### Prompt Engineering：函數層級的參數最佳化 在 AI 應用的初期，架構非常直觀，本質上就是一次遠端過程呼叫（RPC）。 ```python # 傳統 AI 呼叫模型 def execute_ai_task(prompt: str) -> str: return model.generate(prompt) ``` 在這個階段，模型扮演「能力介面」的角色。Prompt Engineering 解決的僅是**輸入問題**（設定角色、描述任務、提供 Few-shot examples）。然而，單靠優化參數無法解決狀態維持或執行驗證的問題。Prompt 並未過時，但其在系統架構中的地位已從「全部邏輯」退居為「底層能力呼叫」。 ### Context Engineering：工作現場的重建與資訊過濾 為了解決模型在缺乏真實業務邏輯時所產生的「幻覺」問題，架構演進到了需要注入上下文的階段。 ```python # 引入上下文的 AI 呼叫模型 def execute_ai_task_with_context(prompt: str, context: ContextData) -> str: # context 包含程式碼庫、API 規格、錯誤日誌等 return model.generate(prompt, context) ``` Context Engineering 的核心挑戰在於**資訊的精煉與注入**。架構上必須解決：文件如何進行語義切片（Chunking）、向量檢索的排序策略（Re-ranking）、上下文去重，以及如何避免過期資訊污染當前決策。給予過多無關的上下文並不能增強能力，反而會造成雜訊干擾，因此設計一個高質量的 RAG (Retrieval-Augmented Generation) 管線是此階段的工程重點。 ### Harness Engineering：執行外殼與權限沙盒 隨著模型開始被賦予呼叫外部 API、讀寫檔案甚至執行 Shell 命令的工具權限，系統面臨了嚴重的安全與越權風險。Harness（執行外殼）的概念應運而生，其實作層面類似於作業系統的進程沙盒（Sandbox）機制。 架構師在此階段必須設計一個安全容器，處理以下關鍵問題： * **工具參數校驗**：模型輸出的工具呼叫請求必須經過嚴格的反序列化與 Schema 驗證。 * **權限控制與隔離（RBAC/ABAC）**：限制模型可以存取的檔案系統路徑或網路白名單。 * **日誌記錄與審計**：攔截並記錄模型的所有行為，以便在發生異常時進行追溯。 * **中斷與人工介入 (Human-in-the-loop)**：高風險操作在執行前必須觸發非同步的審核流程。 沒有 Harness 的防護，工具授權就等同於開啟了系統的事故入口。 ### Loop Engineering：主循環與狀態機控制 進入 Agent 階段後，系統的執行流發生了根本性的反轉。主程序的控制權（Main Loop）部分移交給了 AI，系統從單步執行演化為持續的觀察與修正迴圈（ReAct Pattern）。 ```python # Agent Runtime 的核心 Loop 架構 async def agent_main_loop(objective: str): state = init_state(objective) while not state.is_done() and state.retry_count < MAX_ITERATIONS: plan = await model.plan(state) action = await model.select_action(plan) # Harness 控制層介入 if harness.validate_action(action): result = await harness.execute(action) state.update_observation(result) else: state.record_error("Action validation failed") await model.evaluate_and_repair(state) ``` Loop Engineering 是最高層的抽象，解決的是**持續運行問題**。這要求架構師考慮：狀態（State）如何跨輪次持久化、任務失敗時的重試退避策略（Exponential Backoff）、策略切換的條件、防止無窮迴圈的成本斷路器（Cost Breaker），以及明確的退出與回滾機制。這相當於在撰寫 Agent 的 `main.py`。 ## 總結與結論 * **架構重心的轉移**：AI 系統工程的核心已從「提升模型生成品質」轉移到「建構強健的控制層 (Runtime)」。控制層包含 Context (記憶/狀態)、Harness (權限/邊界) 以及 Loop (流程/狀態機)。 * **防禦性設計是必要條件**：將 LLM 視為一個「充滿變數且可能自信犯錯的機率引擎」。在設計 Harness 時，必須實作強型別校驗、權限隔離與操作日誌記錄，絕不可信任模型輸出的原始執行指令。 * **建立明確的退出與中斷機制**：在實作 Loop 架構時，必須設定嚴格的防呆機制（如最大迭代次數、Token 消耗上限）與高危險動作的 Human-in-the-loop 斷點，防止「事故自動化」的無限迴圈。 * **工程師角色的升級**：未來的軟體架構師不僅要編寫業務邏輯，更要設計 AI 的運行邊界與驗證機制，成為「Runtime Designer」，引導不可預測的模型在可控的軌道上產生價值。

--- tags: [AI模型, 實戰教學, AI工程, 系統架構] date: 2026-06-16 read: false source: "2026-06-16T094015+0800-How To Build Your Own LLM from Scratch (The 5-Stage Pipeline Behind GPT and Claude).md" original_title: "How To Build Your Own LLM from Scratch (The 5-Stage Pipeline Behind GPT and Claude)" --- # How To Build Your Own LLM from Scratch (The 5-Stage Pipeline Behind GPT and Claude)  原始來源與檔名：2026-06-16T094015+0800-How To Build Your Own LLM from Scratch (The 5-Stage Pipeline Behind GPT and Claude).md --- ## NAPKIN | 餐巾紙 ### 餐巾紙公式 > 高質量領域資料 (Domain Data) + 基礎語言模型 (Base LLM) + 對齊微調 (Alignment) = 具有商業價值的專家級模型 (Expert LLM) _架構的公開並不代表模型的成功，決定模型能力的是資料清洗的品質與對齊策略的精準度。_ ### 一句話 > 不要再迷信模型架構，構建實用大語言模型的真正秘密在於「五階段流水線」：資料清洗、分詞、預訓練、對齊與評估，而高品質的特定領域資料才是變現的關鍵。 ### 餐巾紙草圖 ```text [Raw Data] -> (Stage 1: Clean & Filter) -> [Clean Data] | v [Clean Data] -> (Stage 2: Tokenization BPE) -> [Tokens] | v [Tokens] -> (Stage 3: Pretraining / Predict Next Token) -> [Base Model] | v [Base Model] -> (Stage 4: Alignment SFT + RLHF) -> [Assistant Model] | v [Assistant Model] -> (Stage 5: Human Eval & Benchmarks) -> [Production Ready LLM] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這本書在說什麼"** * **核心問題**: 在 Transformer 架構已經公開的今天，為什麼不是每個人都能訓練出 GPT-4 等級的模型？到底如何從頭建構一個真正有用的大語言模型？ * **核心答案**: 構建 LLM 的秘密不在於神經網路架構，而在於嚴格執行的五階段流水線（資料、分詞、訓練、對齊、評估），只要掌握這個流程並注入專屬的高質量資料，任何人都能訓練出高價值的特定領域專家模型。 * **論證結構**: 演繹型與案例型結合。先從抽象的五階段流程逐一拆解原理，再列舉五個具體的商業領域（程式碼、SQL、法律、醫療、電商）作為實戰應用案例。 ### 章節骨架 1. **Stage 1 資料**: 資料品質勝過數量，清洗是核心。 2. **Stage 2 分詞**: 模型不讀文字，只讀片段 (Tokens)。 3. **Stage 3 訓練**: 唯一目標就是預測下一個 Token。 4. **Stage 4 對齊**: 透過 SFT 和 RLHF 將文字預測器變為助理。 5. **Stage 5 評估**: 放棄困惑度，轉向人類基準測試。 6. **五個致命錯誤**: 避開過度關注架構、忽略資料等常見陷阱。 7. **實戰利基應用**: 五個可用同樣流水線變現的垂直領域模型。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text Transformer 架構已公開且標準化 --> 所有人使用相同的底層技術結構 --> 但各大實驗室產出的模型能力差異巨大 --> 差異來源必在架構之外 --> 即五階段流水線中的資料清洗、規模縮放定律 (Scaling Laws)、SFT 及 RLHF 對齊策略 --> 因此掌握流水線與獨特資料集，即可打造出高商業價值的專家模型。 ``` ### 關鍵證據 1. **資料清理的價值**：Common Crawl 包含 2500 億個網頁，但多數為垃圾資訊。必須經過多步過濾（如模型評分、去重），頂級實驗室在資料清理上的花費超過模型設計。 2. **對齊 (Alignment) 的重要性**：未經 RLHF 的模型（僅完成預訓練和 SFT）雖然流暢，但自信且常出錯。只有經過 RLHF，模型才能學會人類偏好，知道何時該回答「不知道」，變得安全且有條理。 3. **利基應用的程式碼範例**：展示了如何使用 15M 參數的小模型，搭配 GitHub Python 程式碼和 Stack Overflow 資料進行訓練，最終能寫出具備重試機制與指數退避 (Exponential backoff) 的生產級代碼。 ### 隱形假設與邊界條件 * **隱形假設**: * 開源工具 (如 Hugging Face `transformers`, `datasets`) 與基礎硬體算力 (如 Google Colab, 筆記型電腦 GPU) 已足夠支援百萬級別參數模型的訓練。 * 使用者能夠取得且合法使用該特定領域的訓練資料（例如合約、醫療紀錄）。 * **邊界條件**: * **算力瓶頸**：若要訓練與 GPT-4 同等規模（兆級參數）的模型，此流程雖然理論相同，但工程複雜度與基礎設施要求將呈指數級增長。 * **領域風險**：在醫療或法律領域，若模型的免責聲明與安全對齊沒有做好，可能會導致嚴重的法律後果。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 雖然強調了流程的五個階段，但沒有深入討論在微調 (SFT/RLHF) 階段出現的「災難性遺忘 (Catastrophic Forgetting)」問題，以及基礎架構上的分佈式訓練 (Distributed Training, DDP/FSDP) 細節。 * **知識連接**: 與軟體工程中的「資料管線 (Data Pipeline)」和「測試驅動開發 (TDD)」概念相通。模型訓練本質上是高度資料驅動的 ETL 過程，而 Stage 5 的評估階段等同於軟體測試。 * **行動觸發**: 不要再去追逐最新的模型架構，而是盤點自己手邊擁有什麼獨特的、高質量的領域資料（例如公司內部的架構文件、特定的客服對話紀錄），並使用這套五階段流水線訓練一個 15M~100M 參數的專屬微型模型。 ### 跨域映射 * 在 **資料工程 (Data Engineering)**，這叫 **ETL (Extract, Transform, Load)** * 在 **產品開發 (Product Management)**，這叫 **Product-Market Fit (尋找特定利基痛點並對症下藥)** --- # How To Build Your Own LLM from Scratch (The 5-Stage Pipeline Behind GPT and Claude) (Architectural Deep Dive) ## 前言/背景 當前技術圈充滿了關於大型語言模型 (LLM) 的討論，但多數開發者仍將其視為黑盒子，誤以為構建 LLM 的核心在於複雜的神經網路架構。本文旨在打破這個迷思，揭示所有主流模型 (如 GPT, Claude, Llama) 背後共用的「五階段流水線 (5-Stage Pipeline)」。文章從工程實踐的角度出發，提供了從零開始使用 PyTorch 建構、訓練與微調 LLM 的具體程式碼與架構決策，並指導如何將此流程應用於具備高度商業價值的垂直領域。 ## 章節詳細總結 ### 核心迷思：架構並非秘密 多數人認為構建 LLM 的關鍵在於 Transformer 架構、注意力機制 (Attention heads) 或神經網路層數。然而，Transformer 架構早已公開，各大實驗室使用的基礎模塊幾乎相同。真正的核心競爭力在於**資料 (Data)、訓練 (Training) 與對齊 (Alignment)**。 ### 階段一：資料 (Data) - 模型的勝負關鍵 原始的網路文本（如 Common Crawl）充滿垃圾資訊。在進行任何訓練之前，必須實施嚴格的多步驟過濾管線： * 從 HTML 中萃取純文字，過濾有害內容 (NSFW) 與個人隱私資料 (PII)。 * 在 URL、文件與行層級進行去重 (Deduplication)。 * 依據字數和 Token 密度移除低品質文件。 * 使用基於模型的品質評分 (Model-based quality scoring，例如判斷這是否能被維基百科引用)。 * 平衡資料配比 (混合程式碼、書籍、科學論文與網頁)。 > **架構洞察**：Data quality beats data quantity. 頂級實驗室在資料清洗上的投入遠超模型設計。 ### 階段二：分詞 (Tokenization) 模型無法直接讀取原始文字，而是讀取 Tokens（模型學習到的字串片段）。標準作法是 **Byte-Pair Encoding (BPE)**。 BPE 從單一字元開始，不斷合併最常見的字元對，直到達到固定的詞彙表大小（通常為 32,000 到 100,000 個 Tokens）。經驗法則：1 個 Token 約等於 0.75 個單字。 **實作範例 (基於 Hugging Face `tokenizers`)**： ```python from tokenizers import Tokenizer, models, trainers, pre_tokenizers # 初始化 BPE Tokenizer tokenizer = Tokenizer(models.BPE()) tokenizer.pre_tokenizer = pre_tokenizers.Whitespace() # 訓練詞彙表大小為 32000 trainer = trainers.BpeTrainer( vocab_size=32000, special_tokens=["<PAD>", "<BOS>", "<EOS>", "<UNK>"] ) tokenizer.train(files=["your_data.txt"], trainer=trainer) ``` ### 階段三：訓練 (Training) 預訓練的核心目標非常單一：**預測下一個 Token (Predict the next token)**。當模型在數兆個 Token 上執行此任務時，它會「湧現 (Emerge)」出語法、事實、推理甚至寫程式的能力。 **架構細節與實作**： 底層採用 Decoder-only Transformer。以下是核心組件 `CausalSelfAttention` 的 PyTorch 實作細節，這包含了模型如何學習文字之間的關聯性： * **Query, Key, Value 投影**：透過線性層計算 Q, K, V。 * **縮放點積注意力 (Scaled Dot-Product Attention)**：計算 `(Q @ K^T) / sqrt(d_k)`。 * **因果遮罩 (Causal Mask)**：這是自迴歸模型 (Autoregressive) 的關鍵。使用下三角矩陣 (Lower triangular matrix) 進行遮罩 `torch.tril()`，將未來 Token 的注意力權重設為 `-inf`，確保模型只能「看向過去」，防止資料洩漏。 ```python # Causal Mask 實作 mask = torch.tril(torch.ones(T, T, device=x.device)) attn = attn.masked_fill(mask == 0, float('-inf')) attn = torch.softmax(attn, dim=-1) ``` 訓練迴圈使用交叉熵損失 (CrossEntropyLoss) 來衡量預測的準確度，並採用梯度裁剪 (Gradient Clipping, `clip_grad_norm_`) 來防止梯度爆炸。 ### 階段四：對齊 (Alignment) 預訓練模型只是一個文字預測器，如果直接問它問題，它可能會用更多問題來回答。對齊階段將其轉化為實用的助理，包含兩個步驟： 1. **監督式微調 (Supervised Fine-Tuning, SFT)**： 使用數千個 `Prompt -> Ideal Response` 的問答對進行訓練。因為模型在預訓練階段已經具備了知識，SFT 的作用是教導模型以特定的「格式」輸出。訓練的迴圈與預訓練相同，只是資料集換成了問答對。 2. **基於人類回饋的強化學習 (RLHF)**： SFT 教會了格式，而 RLHF 教會了「人類偏好」。模型生成多個答案，由人類或獎勵模型 (Reward Model) 挑選出最佳答案。優化模型以最大化該獎勵。沒有 RLHF 的模型會表現得「自信卻錯誤」，加入 RLHF 後，模型才學會安全、有條理，並知道何時該拒絕回答。 ### 階段五：評估 (Evaluation) * **預訓練階段**：主要依賴 **困惑度 (Perplexity)**，衡量模型對真實文本的「驚訝程度」。Perplexity 越低，表示模型預測能力越強。 * **對齊階段後**：Perplexity 不再適用（微調後模型的困惑度通常會變差，但實用性卻提升）。必須轉向人類基準測試，如 MMLU (測量知識廣度)、Chatbot Arena (人類盲測比較)、或 AlpacaEval (以強大 LLM 作為裁判)。 ### 五大常見陷阱 1. **過度執著於架構**：Transformer 已標準化，最不重要。 2. **將資料視為商品**：髒資料會直接封死模型能力的上限。 3. **忽視擴展定律 (Scaling Math)**：最優比例約為 **每 1 個模型參數對應 20 個訓練 Tokens** (Chinchilla Scaling Laws)。 4. **止步於 SFT**：缺乏 RLHF 的模型無法真正理解人類偏好。 5. **對齊後仍依賴困惑度 (Perplexity) 評估**：對齊改變了輸出分佈，應立即切換至人類基準測試。 ### 商業應用：打造利基專家模型 (Niche LLMs) 同樣的五階段流水線，只要注入不同的特定領域資料，就能創造極具商業價值的產品。文章舉例了五種場景： 1. **Coding Assistant (程式碼助理)**：利用 GitHub 的 Python 代碼與 Stack Overflow 問答資料訓練。可以生成帶有完整重試機制與錯誤處理的生產級程式碼。 2. **SQL Query Generator**：利用 Spider (10,000+ 跨領域 SQL 查詢) 或 WikiSQL 訓練，將非技術創辦人的白話文翻譯為複雜的 SQL 語法。 3. **Legal Document Summarizer (法律文件摘要)**：使用 Free Law Project 資料，將 40 頁合約濃縮成白話文，並標示紅旗風險 (Red Flags)。 4. **Medical Symptom Explainer (醫療症狀解釋)**：基於 PubMed 與 MedQA，提供非災難化的醫學解釋，並附上嚴格的免責聲明與就醫建議。 5. **E-commerce Product Description Writer (電商文案生成)**：抓取頂級 Shopify 商店的高轉換率文案進行訓練，寫出能激發消費者情感的商品描述。 ## 總結與結論 * **資料工程即模型工程**：在當前的 LLM 生態中，架構趨於同質化。核心競爭力已從「神經網路設計」轉移到「資料清洗管線 (Data Cleaning Pipeline)」與「資料品質控制」。確保高質量的領域資料，是訓練出高價值模型的絕對前提。 * **對齊策略 (Alignment) 決定產品體驗**：預訓練只賦予模型知識與文字生成能力，SFT 教會了互動格式，而真正讓模型變得可信、安全且具備「助理感」的，是 RLHF (強化學習) 對齊。 * **微型專家模型 (Small Expert Models) 的崛起**：不必盲目追求百億或千億參數的通用大模型。憑藉 15M 到數百萬參數的微型模型，配合極高質量的特定領域資料（如程式碼、SQL、合約），即可在一般硬體 (如 Colab 或筆電 GPU) 上訓練出解決特定痛點且具備商業變現能力的 AI 產品。

--- tags: [AI模型, Agent架構, 產品設計] date: 2026-06-16 read: false source: "2026-06-16T093742+0800-大模型的内部运行原理——10岁小孩都能看懂.md" original_title: "大模型的内部运行原理——10岁小孩都能看懂" --- # 大模型的内部运行原理——10岁小孩都能看懂  原始來源與檔名：2026-06-16T093742+0800-大模型的内部运行原理——10岁小孩都能看懂.md --- ## NAPKIN | 餐巾纸 ### 餐巾紙公式 > 大模型 = 詞向量轉化 + 注意力機制找線索 + 前饋網絡翻記憶 + 預測下一個詞 *大模型本質上是一個將人類語言轉化為數字，並透過龐大的參數記憶與上下文關聯，不斷預測下一個字詞的「接話機器」。* ### 一句話 > 大模型本質上就是一個讀了全世界所有書的「接話王」，透過上下文關聯和機率預測下一個字，當參數夠多時便會產生湧現能力。 ### 餐巾紙草圖 ``` [輸入提示詞] ---> [詞向量 (Word Vector)] | v +--------------------+ | Transformer層 | | 1. Attention (找線索)| | 2. FFN (翻記憶) | +--------------------+ | v [預測下一個詞 (Next Token)] ---> (循環重複) ``` ## ROUND 1: SKELETON | 骨架掃描 **"這本書在說什麼"** * **核心問題**: 大模型到底是怎麼運作的，且產品經理該如何理解？ * **核心答案**: 大模型透過將文字轉化為向量，利用 Transformer 架構理解上下文，並根據預料庫不斷預測下一個字來運作。 * **論證結構**: 演繹型 ### 章節骨架 1. **詞向量**: 文字轉化數字與關係 2. **Transformer**: 找線索並預測字詞 3. **訓練方式**: 預測與反向傳播修正 4. **湧現能力**: 量變產生質變智慧 5. **產品建議**: 處理幻覺與提示詞 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ``` 電腦不認字只認數字 --> 將詞語轉換為可運算的詞向量 --> 透過 Transformer 的注意力機制理解上下文關係 --> 結合前饋網絡預測最可能的下一個詞 --> 大量預測與修正訓練出大模型 --> 參數規模足夠時產生湧現能力 ``` ### 關鍵證據 1. 詞向量算術：如「國王」減「男人」加「女人」結果接近「女王」，證明向量能捕捉語義關係。 2. 注意力機制解析：在「今天天氣真好，我想去公園」中，注意力頭會前後看，釐清「我」與上下文的關聯。 3. 預測訓練：如同教小孩說話，擋住最後一個詞讓模型猜，錯了就用反向傳播微調參數。 ### 隱形假設與邊界條件 * **隱形假設**: * 人類語言的意義與邏輯，可以被高維度空間中的數學向量精準捕捉與表達。 * 足夠多的「預測下一個詞」任務，可以讓模型隱式地學會邏輯推理規則。 * **邊界條件**: * 當遇到訓練數據中未曾出現過的極度創新或小眾知識時，純粹的機率預測會導致幻覺。 * 如果提示詞（Prompt）缺乏足夠的上下文線索，模型的表現品質將大幅下降。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 僅著重在模型「如何預測」，未深入探討為什麼單純的預測任務能夠演化出高階的推理能力，以及訓練數據的品質對最終湧現能力的影響。 * **知識連接**: 大模型的學習過程與人腦神經網絡可塑性（透過不斷試錯與反饋強化突觸連結）高度相似。 * **行動觸發**: 在設計 Agent 或 AI 產品時，不再期望它絕對正確，而是將「幻覺兜底」和「Prompt 上下文注入」列為核心的工程與設計模塊。 ### 跨域映射 * 在 **神經科學**，這叫 **赫布理論 (Hebbian theory)** * 在 **統計學**，這叫 **馬可夫鏈 (Markov chain)** ## STRUCTURE MAP | 全書結構圖 ``` +-------------------+ | 人類自然語言輸入 | +-------------------+ | v +-------------------+ +-------------------------+ | 詞向量 (Vectors) | ---> | 具備算術與語義關係特性 | +-------------------+ +-------------------------+ | v +-----------------------------------+ | Transformer 架構 | | | | +-------------------------------+ | | | 注意力機制 (Attention) | | ---> 尋找上下文線索 | +-------------------------------+ | | | | +-------------------------------+ | | | 前饋網絡 (Feed-Forward) | | ---> 提取預先訓練的記憶 | +-------------------------------+ | +-----------------------------------+ | v +-----------------------------------+ | 訓練: Next Token Prediction | | 修正: Backpropagation (反向傳播) | +-----------------------------------+ | v +-----------------------------------+ | 湧現能力 (Emergent Abilities) | ---> 推理、寫詩、寫程式碼 +-----------------------------------+ | v +-----------------------------------+ | 產品經理的洞察 | | 1. 防範幻覺 (兜底機制) | | 2. 重視 Prompt (上下文線索) | | 3. 模型選型 (決定能力天花板) | +-----------------------------------+ ``` --- # 大模型的内部运行原理——10岁小孩都能看懂 (Architectural Deep Dive) ## 前言/背景 這篇文章旨在為非技術背景的讀者（特別是想轉行 Agent 產品經理的人）提供大語言模型 (LLM) 的核心運作機制。文章透過生動的比喻，將大模型複雜的內部架構拆解為詞向量、Transformer 層、訓練機制與湧現能力，最終導出在設計 AI 產品時必須考量的架構性與設計決策，如幻覺防範、Prompt 依賴與底層模型能力天花板。 ## 章節詳細總結 ### 一、詞向量（Word Vector）：語言的數學表徵 大模型作為計算機系統，無法直接理解人類文字。其第一步是透過 **詞向量 (Word Vector)** 技術將詞彙轉換為高維度的浮點數陣列（例如一萬多維度的向量）。 * **語義空間映射**：意義相近的詞彙在向量空間中的距離較近（例如「貓」與「狗」向量接近，而與「卡車」相距甚遠）。 * **向量算術與語義關係**：詞向量可以進行代數運算，經典範例為 `Vector("國王") - Vector("男人") + Vector("女人") ≈ Vector("女王")`。這代表模型即使不具備視覺或真實世界經驗，也能純粹依賴這套數字系統捕捉並理解詞語間微妙的邏輯與語義關係。 ### 二、Transformer：語言的上下文處理 大模型的核心是 **Transformer** 架構，由多個相同的層（Layers）堆疊而成（如 GPT-3 具有 96 層）。每個 Transformer 層主要執行兩大核心運作： * **注意力機制 (Attention Mechanism)**： * 負責在輸入的字串中「尋找關聯線索」。 * 當處理一句話時，注意力機制會計算每個詞與其他詞之間的權重關係。 * 透過多個 **注意力頭 (Attention Heads)** 進行平行運算，不同的 Head 負責捕捉不同的語法或語義特徵（例如釐清「我」指代誰，或者判斷語境中「公園」的意思）。這使得模型能夠精準掌握上下文（Context）。 * **前饋網絡 (Feed-Forward Network, FFN)**： * 負責從龐大的預訓練參數中「提取記憶」。 * 在注意力機制釐清了上下文關係後，前饋網絡會根據其在訓練階段閱讀過的數千億字數據，預測接下來最可能出現的詞彙（例如「去公園」後面可能接「散步」）。 * **總結協作**：Attention 負責從文字中找線索，FFN 負責從背下來的知識裡找答案，兩者結合決定最終輸出的機率分佈。模型輸出一個詞後，會將其附加到原本的輸入序列中，再次送入模型猜測下一個詞，形成自回歸生成 (Autoregressive Generation)。 ### 三、訓練與湧現能力 * **預測下一個詞 (Next Token Prediction)**：大模型的基礎訓練方式極其簡單，就是擋住最後一個詞，讓模型不斷地猜測被遮蔽的下一個字詞。 * **反向傳播 (Backpropagation)**：當模型預測錯誤時，會透過反向傳播算法計算誤差梯度，並微調內部數百億或數千億的權重參數，讓下次猜對的機率變大。這是一個重複數十億次、消耗龐大算力的暴力美學過程。 * **湧現能力 (Emergent Abilities)**：當模型的參數規模與訓練數據量跨越某個臨界點時，模型會突然展現出在較小規模時不具備的高階能力（如邏輯推理、程式寫作）。沒有人特別教導模型推理，但它在海量預測下一個詞的過程中，突然「開竅」了。 ### 四、產品經理的洞察與設計原則 基於大模型的運作原理，在設計基於大模型的 Agent 系統或應用架構時，必須掌握三個關鍵點： * **防範幻覺 (Hallucination) 的兜底機制**：大模型的本質是「基於機率猜詞」，它並非真實理解事實，因此會一本正經地胡說八道。在系統架構上，必須設計事實核查、防呆或容錯的兜底邏輯。 * **提示詞 (Prompt) 是一切的線索**：大模型高度依賴上下文幹活。Prompt 提供了系統唯一的線索，Prompt 設計的品質將直接決定 Agent 系統的表現。 * **能力天花板取決於底層模型**：模型越大越新，Agent 能做的事越多。因此，底層模型的選型與持續跟進模型迭代，是產品架構決策的核心。 ## 總結與結論 * **詞向量是語義計算的基礎**：透過高維向量映射，語言的模糊性被轉換為可精確計算的數學關係。 * **Attention 與 FFN 構成雙引擎**：Transformer 架構完美結合了上下文的動態解析（Attention 找線索）與靜態知識的提取（FFN 翻記憶）。 * **系統架構需具備幻覺容錯性**：大模型「猜詞」的本質決定了其機率性輸出特徵，產品設計中必須將防護網與容錯兜底邏輯納入考量。 * **重視上下文的注入與管理**：對於 Agent 而言，Prompt 就是執行環境。結構化的 Prompt 設計與精確的上下文注入是發揮模型最大潛能的關鍵。

--- tags: [Agent架構, AI工程, 基礎設施, 開源項目] date: 2026-06-16 read: false source: "https://x.com/AomyYing/status/2066373859692220900" original_title: "5 个 GitHub 热门项目，刚好拼出了 Agent 生态全图" --- # 5 个 GitHub 热门项目，刚好拼出了 Agent 生态全图 ## 核心論點 (Core Thesis) AI Agent 的發展正從「單點模型能力的突破」轉向「系統與基礎設施的建設」。透過近期 GitHub 上的五個熱門開源項目，可以拼湊出 Agent 生態系最關鍵的五個底層架構層次：資訊獲取、運行環境、技能市場、成本控制（上下文壓縮）與安全審計。這標誌著 Agent 正從展示用 Demo 走向真實生產環境，其競爭核心已轉變為系統工程能力。 ## XRay 架構解構 (Architectural Deep Dive) ### 1. 資訊獲取層 (Information Acquisition) **代表項目：last 30 days skill** Agent 要在真實世界發揮作用，首要條件是具備廣泛擷取與處理異質數據的能力。此項目突破了封閉上下文的限制，使 Agent 能夠直接從 Reddit、X (Twitter)、YouTube、Hacker News、Poly Market 等多種異質來源抓取資訊。在技術層面上，它不僅是單純的爬蟲，更包含智能摘要合成的能力，直接應用於趨勢追蹤、市場調研與競品分析。這反映了 Agent 基礎設施中，對於「先接觸世界，再組織事實」的資料處理管線 (Data Pipeline) 需求日益增加。 ### 2. 運行環境層 (Execution Environment) **代表項目：Apple 官方 Container 工具** 穩定的運行底座是生態普及的關鍵。Apple 推出的輕量級虛擬機容器工具，針對 Mac 開發者的本地部署與測試需求進行了底層解決。其技術細節包含支援 Swift 開發、對 Apple Silicon 進行深度優化，以及原生 Linux 容器的支援。在 Agent 的開發與部署流程中，這類不顯眼卻至關重要的基礎設施，確保了跨平台兼容性與本地端運算資源的高效利用，是避免系統出錯的最底層保障。 ### 3. 技能市場層 (Skill Market) **代表項目：PM skills** Agent 的能力正在被高度模組化與標準化，形成類似「技能樂高」的可插拔架構。此項目提供了一整套可調用的能力組件，涵蓋 100 多個 Agent 技能外掛，貫穿產品全生命週期（發現、戰略、上線、增長）。技術上，這意味著 Agent 的架構已從單一對話入口，演進為支援服務導向架構 (SOA) 或微服務架構的系統。開發者不再需要從頭訓練模型具備某項能力，而是透過 API 或標準介面，將封裝好的技能組件接入工作流程中。 ### 4. 成本控制層 (Context Compression) **代表項目：headroom** 長上下文 (Long Context) 與多步驟 Agent 協作在商業化過程中面臨嚴重的成本與延遲問題。headroom 專注於日誌與上下文壓縮，技術指標顯示其能達到 60% 至 95% 的壓縮率，且標榜不損失回答品質。此外，它支援函式庫 (Library)、代理 (Proxy) 以及 MCP (Model Context Protocol) 伺服器等多模式部署。這層架構直接解決了 Agent 系統在持續運行與大規模部署時的 Token 消耗成本與效能瓶頸，是決定 Agent 能否進入實用工作流的關鍵技術。 ### 5. 安全審計層 (Security Audit) **代表項目：Nvidia skill spectre** 隨著 Agent 技能生態擴張及自主執行權限的增加，安全防護成為不可或缺的主線。英偉達的 skill spectre 專注於防範 Agent 系統的特有漏洞。其技術實踐包含：惡意模式注入檢測、Agent 技能漏洞審計，以及防範 Prompt 注入 (Prompt Injection) 與權限越界 (Privilege Escalation) 等風險。這代表著行業正在積極建立 Agent 生態的安全網關 (Security Gateway)，確保在賦予 Agent 更多操作權限時，系統不會遭受惡意攻擊或產生不可控的行為。 ## 底層邏輯與趨勢 (Underlying Logic & Trends) 這五個層次的共同指向是「系統工程」的崛起。當前的開發趨勢已不再局限於讓某個單一 Agent 模型變得更聰明，而是專注於打造穩定的工作流底層拼圖：如何高效獲取資訊、如何在安全環境中運行、如何掛載與重用技能組件、如何透過上下文壓縮降低維運成本，以及如何建立嚴格的安全防禦機制。這些開源項目的爆發，證明了 AI Agent 生態正在長出真正的、具備企業級生產標準的基礎設施。

--- tags: [Agent架構, AI工程, 系統架構, 工具實踐] date: 2026-06-16 read: false source: "2026-06-16T093643+0800-AI Agent Stack Everyone Must Use in 2026 (Builder’s Guide).md" original_title: "AI Agent Stack Everyone Must Use in 2026 (Builder’s Guide)" --- # AI Agent Stack Everyone Must Use in 2026 (Builder’s Guide)  原始來源與檔名：2026-06-16T093643+0800-AI Agent Stack Everyone Must Use in 2026 (Builder’s Guide).md --- ## NAPKIN | 餐巾紙 ### 餐巾紙公式 > Agent Intelligence = Markdown Memory + Progressive Skills + Strict Protocols _智能並非源於模型本身，而是來自持續迭代的記憶、逐步載入的技能以及嚴格遵守的執行協議。_ ### 一句話 > 不要試圖打造全能模型，而是要建立一個由記憶、技能和約束協議組成的「基礎設施」，讓模型只作為一個輕量級的執行大腦。 ### 餐巾紙草圖 ```text +-------------------+ +-------------------+ | Harness | | Protocols | | (Thin Conductor) |----->| (Permissions & | | - build_context | | Tool Schemas) | +---------+---------+ +-------------------+ | v +---------+---------+ +-------------------+ | Memory | | Skills | | - Working | | - _index.md | | - Episodic |----->| - _manifest.jsonl| | - Semantic | | - SKILL.md | | - Personal | | - Self-rewrite | +-------------------+ +-------------------+ ``` ## ROUND 1: SKELETON | 骨架掃描 **"這本書在說什麼"** * **核心問題**: 開發者在 2026 年該如何建立真正能落地、可持續進化的 AI Agent？ * **核心答案**: 拋棄訓練自有模型的想法，將精力集中在構建基於 Markdown 的四層記憶體、具備自我重寫能力的技能庫，以及嚴格的工具協議上。 * **論證結構**: 案例型與歸納型（作者透過自身花費三個月建構的系統，展示架構的優勢並歸納出設計原則）。 ### 章節骨架 1. **全局架構**: 記憶、技能、協議與輕量化 Harness。 2. **Harness 設計**: 負責上下文組裝，自身不具備智能。 3. **四層記憶系統**: 區分工作、情節、語義與個人記憶。 4. **夜間夢境循環**: 自動化記憶壓縮與知識萃取。 5. **技能與漸進式揭露**: 按需載入技能，避免上下文爆炸。 6. **協議與約束**: 嚴格定義 Agent 可執行的權限邊界。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text 模型算力有限且容易遺忘 --> 需要外部化記憶體與技能庫 --> 扁平化的記憶會導致上下文崩潰 --> 必須設計四層記憶系統與漸進式技能載入 --> 缺乏約束會導致執行失控 --> 必須透過協議（Protocols）與掛鉤（Hooks）實施邊界攔截 --> 最終形成自我迭代的 AI 基礎設施 ``` ### 關鍵證據 1. **上下文預算分配**: 透過 `build_context` 限制每次傳入模型的 token 數量，證明無差別載入所有技能會導致模型性能下降。 2. **四層記憶的必要性**: 展示了如果不區分 Semantic（語義）和 Episodic（情節）記憶，Agent 會在六週後因為記憶混亂而崩潰。 3. **Hooks 的攔截效果**: 透過 `pre_tool_call` 成功攔截強制推播（force push）到 main 分支等危險操作，證明協議層的重要性。 ### 隱形假設與邊界條件 * **隱形假設**: * 底層的 LLM (如 Claude-Sonnet-4) 具備足夠的基礎推理能力來理解 Markdown 格式的約束與技能指令。 * 使用者會定期檢閱並進行小幅度的干預（如刪除錯誤的 Semantic 記憶），確保錯誤不會被無限放大。 * **邊界條件**: * 當任務的複雜度超出單一使用者的領域知識，或跨團隊協作時，個人的偏好記憶（Personal Memory）可能會成為障礙。 * 在需要毫秒級延遲的即時系統中，這種基於文件讀寫和多次 Hook 攔截的架構會因為延遲過高而失效。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 系統高度依賴純文本 (Markdown/JSON) 的檔案系統，隨著時間推移，Git Repo 可能會變得龐大且難以快速檢索，缺乏傳統向量資料庫在超大規模知識檢索下的擴展性分析。 * **知識連接**: 這種架構與微服務架構中的 Sidecar 模式高度相似，也呼應了人類大腦的記憶模型（短期記憶與長期記憶的鞏固過程）。 * **行動觸發**: 停止花時間微調模型。開始為你現有的工作流撰寫 `SKILL.md`，並定義清晰的輸入/輸出 Schema，建立你的第一個 Agent 基礎設施。 ### 跨域映射 * 在 **神經科學**，這叫 **記憶鞏固 (Memory Consolidation)**（對應夜間的夢境循環機制）。 * 在 **軟體工程**，這叫 **關注點分離 (Separation of Concerns)**（Harness 只負責排程，邏輯交由 Skills 處理）。 --- # AI Agent Stack Everyone Must Use in 2026 (Builder’s Guide) (Architectural Deep Dive) ## 前言/背景 這篇文章探討了 2026 年 AI Agent 構建的核心真相：開發者不需要訓練自己的模型，而是應該專注於打造圍繞模型的基礎設施（基礎架構）。作者詳細分享了其耗時三個月打造的架構，核心在於將 Harness（調度器）、Memory（記憶）、Skills（技能）和 Protocols（協議）解耦，讓 Agent 具備自我學習與迭代的能力。 ## 章節詳細總結 ### 1. The Shape of the Full Stack (全端架構的形狀) 作者認為 Harness（調度器）不應該具備智能，它只是一個輕量級的指揮家（Conductor），負責讀取檔案、呼叫工具、寫入日誌與觸發掛鉤（Hooks）。真正的智能存在於 Markdown 格式的技能與記憶檔案中。這種解耦帶來的架構優勢是，未來無論替換底層模型還是替換調度器，都不會遺失累積的知識。 **架構目錄範例**： ```bash .agent/ ├── AGENTS.md # 根配置檔 ├── harness/ # 輕量級的調度器 (~200行) │ ├── conductor.py │ └── hooks/ # 生命週期事件 ├── memory/ # 四層記憶體 │ ├── working/ │ ├── episodic/ │ ├── semantic/ │ └── personal/ ├── skills/ # 技能庫 │ ├── _index.md # 漸進式載入索引 │ └── skillforge/ ├── protocols/ # 執行協議 │ ├── tool_schemas/ │ └── permissions.md └── tools/ ``` ### 2. The Files Nobody Shows You (隱藏的關鍵設定檔) 系統中有幾個決定成敗的核心檔案，它們負責引導 Agent 的行為模式： * **`AGENTS.md`**: 作為 Agent 啟動時最先讀取的根目錄索引，告訴 Agent 記憶、技能和協議的具體位置，並訂立如「在做決策前必須先檢查過往教訓」的絕對規則。 * **`DECISIONS.md`**: 記錄架構上的重大決策（例如為什麼選擇 FastAPI 而不是 Express），包含決策理由與替代方案。這能防止 Agent（或人類）日後反覆針對已解決的問題進行無意義的重構。 * **`on_failure.py` (掛鉤)**: 將錯誤轉化為經驗。當工具執行失敗時，不僅記錄錯誤，還會給予較高的「痛苦分數 (Pain Score)」。如果同一個技能在近期連續失敗超過三次，系統會自動標記該技能需要重寫（Trigger skill rewrite）。 ### 3. The Harness: Thin Conductor (輕量級的調度器) Harness 的核心工作不是推理，而是**上下文組裝 (Context Assembly)**。模型的 Context Window 被視為一個「運算盒子 (Computation box)」，任何不在盒子裡的知識都不存在。 `build_context` 函數是整個系統的心臟，負責在預算內（Token Budget）精確注入有用的片段： 1. 首先載入個人偏好與當前工作區狀態。 2. 載入語義記憶（經驗教訓）。 3. 利用顯著性評分 (Salience Score) 載入前 5 條最重要的情節記憶。 4. 最後載入被觸發的技能與安全權限。 如果片段無法協助當前決策，就會變成干擾模型的雜訊。作者強調 Harness 的代碼必須保持在 200 行以內。 ### 4. Memory: Four Layers, Not One (四層記憶架構) 將所有記憶混在一起會導致檢索崩潰，因此必須區分四個具備不同生命週期的記憶層次： * **Working (工作記憶)**: 記錄當下任務的狀態、開啟的檔案與假設。高度不穩定，任務結束即歸檔，主要用於系統中斷後的「狀態恢復」。 * **Episodic (情節記憶)**: 記錄過去發生的具體事件（例如 API 呼叫失敗）。包含 `pain_score` (痛苦分數) 和 `importance` (重要性) 等屬性，用於檢索評分。 * **Semantic (語義記憶)**: 跨越單一事件的抽象模式（例如 API 設計模式、測試策略）。這層記憶是將情節記憶濃縮後的結果，指導未來的全局行動。 * **Personal (個人記憶)**: 存放與使用者特定相關的偏好（如程式碼風格為 TypeScript 嚴格模式），這些偏好不應被混入全局的 Semantic 記憶中。 ### 5. The Upgraded Dream Cycle (升級版夢境循環) 系統利用一個在凌晨 3 點執行的 Cron Job (`auto_dream.py`) 來模擬人類大腦的記憶鞏固過程。 這個過程會分析情節記憶 (`AGENT_LEARNINGS.jsonl`)，尋找重複出現的模式。如果某個模式的顯著性分數達到閾值，就會被「提升 (Promote)」到語義記憶 (`LESSONS.md`) 中。同時，對於過期且低價值的記憶會進行衰退存檔 (Decay & Archive)，並透過 Git 自動提交變更。這保證了知識的持續萃取且不會讓資料無限制膨脹。 ### 6. The Skills & Progressive Disclosure (技能與漸進式揭露) **漸進式揭露** 是解決 Token 浪費的關鍵設計。 Agent 不會在啟動時載入所有的 `SKILL.md`。相反地，它會先讀取一個極輕量的 `_index.md` 與 `_manifest.jsonl`，裡面只包含技能名稱和觸發條件 (Triggers)。當使用者的輸入匹配到特定的觸發詞時，Harness 才會將完整的技能內容讀入 Context Window。 此外，每一個技能檔案都包含了**自我重寫掛鉤 (Self-rewrite hook)**。例如 `skillforge` (負責創造新技能的技能) 在失敗或發現新模式時，能修改自己的程式碼與邏輯，讓 Agent 的能力隨時間產生複利效應。 ### 7. Protocols: The Layer Most Builders Skip (被忽視的協議層) 沒有協議層，模型就會自己瞎猜 API 的參數，這是生產環境失敗的主因。 * **Tool Schemas (工具結構定義)**: 明確定義每一個工具操作所需的參數、前置條件 (Preconditions)、副作用與是否需要人工批准。 * **Permissions (權限邊界)**: 明確劃分「總是允許」、「需要批准」以及「絕對禁止」的操作清單。 * **Hooks 攔截**: `pre_tool_call.py` 會在執行前比對 Schema 與 Permissions。如果 Agent 試圖對 `main` 分支進行 `force_push`，Hook 會直接攔截並返回錯誤，強制模型修正行為。 ## 總結與結論 * **架構解耦是進化的前提**：將智能的核心從黑箱模型轉移到外部的 Git 倉庫（Markdown 檔案），Harness 只做排程與上下文控制，這是建立具備長久記憶能力系統的最佳實踐。 * **漸進式揭露解決上下文瓶頸**：不要依賴無限大的 Context Window，透過 Metadata 索引進行動態按需載入（Progressive Disclosure），不僅節省 Token 成本，還能大幅提高 LLM 遵循指令的精確度。 * **建立「護欄」而非「導航」**：在設計技能與協議時，應該提供目的地與邊界限制（Protocols & Permissions），而不是微觀管理每一步驟（Micromanagement）。讓模型在有明確型別與約束（Tool Schemas）的安全沙盒內自主探索。 * **善用 Hook 實現閉環反饋**：透過 `on_failure` 和 `post_execution` 捕捉每次執行的狀態與代價，並結合夜間的 Dream Cycle，系統能夠將局部的錯誤自動收斂為全局的經驗法則（Semantic Memory），實現無須人工干預的自我進化。

--- tags: [Agent架構, 產業趨勢, AI商業] date: 2026-06-16 read: false source: "2026-06-16T094215+0800-AI News Volume 1 The AI Agent War Is No Longer About the Smartest Model.md" original_title: "AI News Volume 1 The AI Agent War Is No Longer About the Smartest Model" --- # AI News Volume 1: The AI Agent War Is No Longer About the Smartest Model  原始來源與檔名：2026-06-16T094215+0800-AI News Volume 1 The AI Agent War Is No Longer About the Smartest Model.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 智能 (Smart Models) + 執行環境 (Runtime) + 治理控制 (Governance) = 企業級 AI 代理 (Enterprise AI Agents) *AI 代理的價值不再僅取決於模型的智力，而是取決於其執行環境的持久性、安全性和可控性。* ### 一句话 > AI 代理市場的競爭已經從「誰有最聰明的模型」轉移到了「誰能提供最安全、最持久且最具經濟效益的代理執行環境 (Runtime)」。 ### 餐巾纸草图 ```text [ LLMs ] -> Engine (Intelligence) | V [ Runtime Layer ] -> Vehicle (Tools, File System, Memory, Sandbox) | V [ Governance ] -> Brakes (Permissions, Audits, Costs) | V [ Workflows ] -> Destination (Enterprise Action) ``` ## ROUND 1: SKELETON | 骨架掃描 **"这本书在说什么"** * **核心问题**: 下一代 AI 代理市場的真正競爭核心是什麼？ * **核心答案**: 競爭已從模型能力轉向「執行環境 (Runtime)」，誰能控制代理的運行、權限、日誌和安全性，誰就能贏得企業市場。 * **论证结构**: 案例型與歸納型（透過 OpenAI、Google、Anthropic、xAI、Perplexity 的最新產品動態歸納出市場趨勢）。 ### 章节骨架 1. **從模型戰到環境戰**: 模型是引擎，但代理需要運行環境。 2. **OpenAI 收購 Ona**: Codex 從寫程式助理轉向雲端安全執行層。 3. **Google Antigravity**: 封裝 Sandbox 成為受管代理的執行環境。 4. **Anthropic 分離計費**: 將對話式與自動化代理 SDK 拆分計費。 5. **xAI 工具經濟學**: 以低成本 API 搶佔開發者工作流。 6. **Perplexity 企業版**: 將代理直接嵌入企業既有協作平台。 7. **全新 AI 代理技術棧**: 模型之上，工具、迴圈、執行環境、控制層與工作流堆疊。 8. **企業落地現實檢驗**: 安全、合規與成本是代理落地的護城河。 ## ROUND 2: DISSECTION | 血肉解剖 **"凭什么这么说"** ### 论证链 ```text 模型能力逐漸同質化 --> 代理需要持久與安全的環境來執行複雜任務 --> 企業擔憂數據安全與成本失控 --> 各大巨頭紛紛佈局 Runtime 層與治理控制 --> 代理市場的核心競爭力轉變為基礎設施與執行環境 ``` ### 关键证据 1. OpenAI 計畫收購 Ona (前 Gitpod)，為 Codex 提供雲端持久化且安全的程式碼執行環境。 2. Google 推出 Antigravity Agent，提供託管的 Linux 沙盒供 Gemini API 呼叫執行程式碼和網頁瀏覽，並強制轉移 Gemini CLI 用戶。 3. Anthropic 將 Agent SDK 從一般的 Claude 訂閱中拆分，反映出代理自動化工作負載與人類對話有本質上的區別與成本差異。 ### 隐形假设与边界 * **隐形假设**: * 代理將愈來愈多地執行長週期、需要大量上下文的自主任務。 * 企業最終會願意將內部核心系統的權限適度開放給具備治理能力的代理平台。 * **边界条件**: * 當企業完全禁止外部 AI 連接內部資料庫時，Runtime 的價值會大打折扣。 * 如果模型的幻覺或錯誤率無法降至可接受水平，即使 Runtime 再完美，代理計畫依然會失敗。 ## ROUND 3: SOUL | 靈魂提取 **"还能怎么用"** * **作者盲点**: 較少討論開源代理框架 (如 AutoGPT, LangChain, LlamaIndex 等) 或是開源自託管 Runtime 在企業內部的競爭力。 * **知识连接**: 與雲端計算的發展歷程極為相似 (IaaS -> PaaS -> Serverless/Managed Services)。目前的 Runtime 爭奪戰就像當年 AWS/GCP 爭奪雲端基礎設施一樣。 * **行动触发**: 在評估或導入 AI 代理時，不要只看模型跑分 (Benchmarks)，應將重點放在評估各平台的日誌、權限控制、沙盒安全與成本管理能力。 ### 跨域映射 * 在 **雲端運算**，這叫 **平台即服務 (PaaS) 與 Serverless 架構** * 在 **作業系統**，這叫 **行程管理與權限隔離 (Process Management & Sandboxing)** ## STRUCTURE MAP | 全书结构图 ```text [ Enterprise Workflows ] | [ Control & Governance ] <-- Brakes/Audits | +---------------------------------------------------------------+ | RUNTIME LAYER (The Moat) | | OpenAI(Ona) | Google(Antigravity) | Anthropic(SDK/Code) | | xAI(Tool Economics) | Perplexity(Enterprise Context) | +---------------------------------------------------------------+ | [ Agent Loops / Tools ] | [ Foundation Models ] <-- The Engine ``` --- # AI News Volume 1 The AI Agent War Is No Longer About the Smartest Model (Architectural Deep Dive) ## 前言/背景 本文深入探討了 AI 代理 (AI Agents) 市場的最新戰略轉變。作者指出，AI 產業的競爭焦點已經從單純比較語言模型 (LLMs) 的智商、上下文長度與推理能力，轉移到了代理的「執行環境 (Runtime)」。企業要真正讓 AI 代理落地執行長週期的任務，需要的是一個具備檔案系統、工具存取權、日誌紀錄、權限模型且安全的受管環境。各大 AI 巨頭正積極透過併購或發布新平台來搶佔這個將智力轉化為實際勞動力的基礎設施層。 ## 章節詳細總結 ### 從模型競賽到執行環境 (Runtime) 競賽 過去幾年，業界沉迷於模型跑分測試。然而，模型就像是引擎，引擎本身無法構成完整的交通系統。AI 代理需要一個實際的工作環境 (Runtime)。在技術層面上，這個 Runtime 代表了代理可以： * 讀取與寫入檔案。 * 執行程式碼與測試。 * 呼叫外部 API 工具並管理狀態 (State Management)。 * 在受限的安全邊界內運行長達數分鐘至數天的背景任務。 這個環境將「智能」轉化為「勞動力」，而這正是當前市場的核心轉捩點。 ### OpenAI 收購 Ona：為 Codex 建立持久雲端環境 OpenAI 收購 Ona (前身為雲端開發環境 Gitpod) 解決了 Codex 戰略上的基礎設施問題。Codex 每週活躍用戶已達 500 萬，其定位正從「對話式助理」轉變為「工作代理」。 * **技術需求**：一個實用的軟體代理需要檢查程式碼庫 (Repository)、執行測試、修改多個檔案、等待回呼 (Callbacks) 或結果、除錯，最終發起 Pull Request (PR)。 * **架構決策 (Why)**：企業不希望強大的代理在敏感系統中毫無邊界地遊蕩。收購 Ona 意味著 OpenAI 想要提供一個具備可觀察性 (Observability)、作用域存取控制 (Scoped Access) 和合規性控制的持久雲端執行層，解決企業的「安全操作」痛點。 ### Google Antigravity：將沙盒 (Sandbox) 產品化 Google 推出的 Antigravity Agent 直接將受管代理環境封裝為產品，透過 Gemini API 和 Google AI Studio 提供服務。 * **技術實作細節**：Antigravity 在 Google 託管的 Linux 沙盒 (Linux Sandbox) 內運作，允許代理推論、執行程式碼、管理檔案並瀏覽網頁。 * **架構意義**：開發者不再需要自行將模型、工具迴圈 (Tool Loop)、瀏覽器、檔案系統、Shell 和安全邊界拼湊在一起。Google 透過提供這個產品化的 Runtime，不僅在銷售 Gemini 模型，更在銷售一個讓 Gemini 驅動的代理可以安全執行的空間。此外，Google 宣布在 2026 年 6 月停止為部分用戶提供 Gemini CLI，強制引導開發者轉向 Antigravity CLI，展現其整合代理優先 (Agent-first) 開發環境的戰略決心。 ### Anthropic 的計費策略：分離對話與自動化工作負載 Anthropic 將 Claude Agent SDK 與 `claude -p` 的使用量從一般互動式 Claude 訂閱中抽離，改為獨立的 Agent SDK 額度。 * **架構決策 (Why)**：代理工作負載與人類對話有本質上的差異。人類是「提問 -> 讀取 -> 上傳」，而代理則是高頻的「迴圈執行 (Looping) -> 呼叫工具 -> 檢查程式碼 -> 重試失敗步驟 -> 生成子代理 (Subagents) -> 大量消耗 Context Token」。 * **企業管理細節**：隨著代理自動化加深，扁平化的訂閱制不再適用。企業需要精確的計費與使用限制追蹤：誰觸發了代理？執行了什麼任務？呼叫了幾次工具？存取了哪些系統？這些都是核心的 Runtime 治理問題。 ### xAI 與 Perplexity 的不同切入點 * **xAI 工具經濟學**：xAI 的策略專注於擴展 API 介面並降低工具使用的經濟成本 (如檔案處理、搜尋、WebSocket 支援、遠端 MCP 工具等)。因為在生產環境中，代理的每一次檢索、執行、重試都會產生單位成本 (Unit Economics)。高可組合性與可負擔的成本是開發者選擇自動化方案的關鍵。 * **Perplexity 企業協作介面**：Perplexity 不從開發者底層環境切入，而是直接將 "Computer" 代理帶入 Slack、Snowflake 等企業數據工作流。在企業架構中，上下文存在於資料庫與 CRM 系統中。Perplexity 試圖從協作層 (Collaboration Layer) 切入，成為工作協調者。 ### 全新 AI 代理技術棧 (The New AI Agent Stack) 文章定義了現代 AI 代理系統的架構分層： 1. **Workflows (工作流)**：最頂層的實際業務任務。 2. **Controls (治理控制)**：包含身分認證 (Identity)、權限、日誌、計費、可觀察性與合規性。 3. **Runtime (執行環境)**：安全且實際執行任務的沙盒環境，這將成為最強的護城河 (Moat)。 4. **Agent Loops (代理迴圈)**：規劃、執行、反思、重試、子代理編排。 5. **Tools (工具層)**：搜尋、程式碼執行、MCP、企業連接器等。 6. **Models (基礎模型)**：最底層的推論引擎。 一旦企業基於特定的 Runtime 建立了工作流，該環境累積的權限、日誌和內部信任就會產生強大的平台黏性 (Platform Power)。 ## 總結與結論 * **Runtime 才是代理的護城河**：企業可以隨時更換底層的 LLM 模型，但要遷移一個包含權限控制、日誌記錄、安全沙盒和企業整合的代理執行環境 (Runtime) 成本極高。未來的競爭關鍵在於基礎設施。 * **安全與治理是落地的先決條件**：如果缺乏身分驗證、存取範圍控制、成本追蹤機制和決策可解釋性，即便代理的 Demo 再驚艷，在企業生產環境中依然會面臨合規性阻礙而失敗。 * **架構選型的新標準**：在設計或採購 AI 代理架構時，首要評估指標不再僅是模型的 Benchmark，而應著重於其工具存取能力、沙盒邊界、異常復原機制 (Recovery)、以及基礎架構的可觀察性與可審計性 (Auditability)。

--- tags: [Agent架構, AI工程, 系統工程, 自動化] date: 2026-06-16 read: false source: "2026-06-16T093913+0800-Autonomous Long-Running Coding Agents.md" original_title: "Autonomous Long-Running Coding Agents" --- # Autonomous Long-Running Coding Agents (自主長效程式代理)  原始來源與檔名：2026-06-16T093913+0800-Autonomous Long-Running Coding Agents.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 自主性 = 明確的目標 (Goal) + 嚴謹的驗證器 (Verifier) + 控制迴圈 (Loop) _長效運行的代理需要將人類的提示轉化為可自我檢測與重複修正的控制系統。_ ### 一句话 > 把程式代理從「單次對話產生器」變成「自動化執行與驗證系統」，關鍵在於設計強大的控制迴圈和驗證器，而不是追求更完美的提示詞。 ### 餐巾纸草图 ``` [ 人類 (規劃與目標) ] | v +------------+ | 目標與約束 | +------------+ | (輸入) v +------------+ (失敗重試) +-------------+ | 執行者Agent| <---------------------- | 控制迴圈 | +------------+ +-------------+ | (產出) ^ v | +------------+ (成功/失敗) | | 驗證器 | ------------------------------+ |(決定性/AI) | +------------+ | (通過) v [ 視覺化產出 (Artifacts) ] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 如何讓程式代理在沒有人類不斷介入的情況下，長期且穩定地執行複雜的工程任務？ * **核心答案**: 開發者必須將代理包裹在目標、評估器、控制迴圈和驗證器之中，建立一個自治的控制系統。 * **論證結構**: 演繹型與最佳實踐說明（從傳統 Prompting 到控制系統各組件的逐步拆解）。 ### 章節骨架 1. **從提示到目標設計**: 用合約般的目標取代單次提示。 2. **評估器成為一等公民**: 決定性檢查與代理評估的結合。 3. **驗證器定義信任邊界**: 系統自主性依賴於外部客觀證據。 4. **迴圈讓自主性持久**: 外部控制系統確保任務持續到完成。 5. **規劃是專業知識的切入點**: 區分規劃者與執行者模型。 6. **視覺化產出成為控制介面**: 儀表板取代難以閱讀的終端機日誌。 7. **會話探勘轉化為記憶**: 從失敗記錄中提煉出專案指引規則。 8. **實用營運模式與限制**: AI 工程師的實戰工作流與當前模型的限制。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ``` 長效任務充滿未知與錯誤 --> 依賴人類逐次指導無法擴展 --> 需要代理具備自我糾正能力 --> 自我糾正依賴客觀標準 --> 建立以「目標、驗證、迴圈」為核心的控制系統 --> 代理才能安全地長期自主運行。 ``` ### 關鍵證據 1. 代理常會在達成部分解決方案或遇到轉折點時提前停止，沒有控制迴圈會導致任務失敗卻未被發現。 2. 代理的自我解釋不可信（會幻覺成功），必須依賴外部工具（如測試腳本、型別檢查、截圖比對）作為證據。 3. 當同時執行多個代理時，純文字日誌（Terminal transcripts）難以監控，證明需要視覺化產出（Artifacts）作為控制介面。 ### 隱形假設與邊界 * **隱形假設**: * 開發者有能力清楚定義「成功」的客觀標準。 * 模型具備足夠的基礎編碼與糾錯能力，可以在給定失敗反饋後進行修正。 * 底層基礎設施（如沙盒、測試環境）足夠穩定且自動化。 * **邊界條件**: * 當任務屬於全新的未見領域（Out of Distribution, OOD），模型的規劃與驗證能力會大幅下降。 * 如果驗證器定義過於模糊，模型會走捷徑；若過於狹隘，模型會過度擬合而忽視整體意圖。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 較少提及控制迴圈中如果陷入死胡同（Infinite Loop of failures）時的熔斷機制與回退策略。 * **知識連接**: 與控制工程（Control Engineering）中的閉迴路系統（Closed-loop System）概念完全一致。 * **行動觸發**: 停止編寫越來越長的提示詞；開始為你的專案撰寫自動化測試、定義 Lint 規則，並用程式碼封裝代理的執行過程。 ### 跨域映射 * 在 **控制工程**，這叫 **閉迴路反饋控制 (Closed-loop Feedback Control)**。 * 在 **軟體工程測試**，這叫 **測試驅動開發 (Test-Driven Development, TDD) 的自動化延伸**。 --- # Autonomous Long-Running Coding Agents (Architectural Deep Dive) ## 前言/背景 隨著 AI 模型能力的提升，開發者正在從單純的「提示工程 (Prompt Engineering)」轉向建構「控制系統 (Control Systems)」。這篇文章旨在解決一個核心挑戰：如何在充滿模糊需求、潛在失敗與動態環境的複雜工程任務中，讓程式代理 (Coding Agents) 能夠在沒有人類逐次介入的情況下，持續規劃、執行、驗證並糾正錯誤，實現真正的長效自主運行。 ## 章節詳細總結 ### 從提示到目標設計 (From Prompting to Goal Design) 自主編程系統的第一步是改變人類與代理的互動方式。不再是回合制 (turn-by-turn) 的對話，而是定義一個如同「合約」般的目標。 * **嚴格的目標定義**：目標必須包含期望的最終狀態、證明成功的具體證據、不可違反的約束條件，以及回合數或預算限制。 * **防禦性設計**：薄弱的目標會給模型留下「走捷徑」或提早結束的空間；強大的目標則迫使模型不斷自我檢測。例如：在機器學習研究中，目標不是「寫一個模型」，而是「達到特定基準分數、輸出 Loss 曲線，並超越基礎 Baseline」；在前端 UI 開發中，目標是「符合截圖參考、滿足特定版面約束，並通過瀏覽器驗證」。 ### 評估器成為一等公民 (The Evaluator Becomes a First-Class Component) 長效代理需要將「評估」從執行中剝離出來，成為一個獨立的角色。 * **決定性檢查 (Deterministic Checks)**：當成功標準明確時，應優先使用編譯器、型別檢查、單元測試、Lint 規則和整合測試。這是系統信任的底層基準。 * **代理評估器 (Agent Evaluator)**：當成功標準模糊（如研究報告的邏輯連貫性、UI 是否符合設計意圖）時，就需要引入另一個 AI 模型作為評估器 (LLM-as-judge) 或運用視覺能力進行審查。 * **分層架構**：最佳實踐是將決定性檢查作為第一道防線，將 AI 代理評估作為高階審查，藉此降低幻覺帶來的假性成功。 ### 驗證器定義信任邊界 (Verifiers Define the Boundary of Trust) 系統的自主性建立在可靠的驗證器上。代理自己說「完成了」不能當作證據，證據必須來自它無法輕易繞過的外部檢驗。 * **客觀證據**：對於程式碼，證據是測試套件或 Reproducible 腳本；對於 UI，證據是截圖比對；對於研究，證據是重現的表格或超越基準的分數。 * **捷徑與過度擬合問題**：如果驗證器太模糊，模型會採取最簡單的解釋；太狹隘，則會過度擬合。因此需要多層次的驗證機制。作者指出，目前模型在處理訓練分佈外 (Out of Distribution, OOD) 的驗證任務時仍會顯著掙扎，企業正在這個領域投入大量資源。 ### 迴圈讓自主性持久 (Loops Make Autonomy Durable) 目標給予方向，但控制迴圈 (Loop) 維持系統運行。模型經常會因為上下文耗盡、達到回合限制或對部分結果感到滿意而提前停止。 * **外部控制層**：迴圈是外部的控制系統，負責喚醒代理、檢查進度、運行驗證，並在目標未達成時，將代理送回執行狀態。 * **持久性機制**：長效自主性不是依賴一次性的超級智能，而是在控制層監督下的反覆重試。迴圈確保系統能察覺失敗並繼續嘗試，而不是默默宣告勝利。 ### 規劃是專業知識的切入點 (Planning Is Where Expertise Enters) 雖然系統是自主的，但人類工程師的專業知識主要體現在「規劃階段」。 * **職責分離 (Division of Labor)**：系統應採用架構級別的模型選擇策略。使用推理能力更強（但也更貴）的模型來定義目標、列出約束與生成評估計畫；接著將執行任務交給另一個執行模型。 * **靈活編排**：不應依賴單一供應商的完美模型，而是根據任務需求（如誰更會規劃、誰更會執行、誰適合視覺審查）動態切換模型角色。 ### 視覺化產出成為控制介面 (Visual Artifacts Become Control Surfaces) 當多個代理平行運行時，傳統的終端機文字日誌 (Terminal transcripts) 會變得無法閱讀。 * **狀態分離**：將狀態存儲（Markdown、Log、結果）與呈現介面（HTML 儀表板）分離。 * **控制平面 (Control Surface)**：視覺化產出（如 Loss 曲線、基準分數、系統狀態、截圖）成為人類監督自主系統的控制介面，幫助人類在正確的時機介入。特別是在 UI 開發中，視覺化截圖參考能精準傳遞對齊與層級關係，避免模型在程式碼上成功但視覺上失敗。 ### 會話探勘轉化為記憶 (Session Mining Turns Usage Into Memory) 代理失敗的歷史紀錄是極具價值的數據庫。 * **提取操作規則**：系統應能掃描過去（如三十天內）的會話日誌，找出重複出現的錯誤（例如：總是忘記跑某個檢查、使用錯誤的路徑）。 * **動態修正**：將這些教訓轉化為專案層級的指令或 Vault 學習規則，這樣團隊就能逐步優化代理的執行環境，而無需重新訓練模型。 ## 總結與結論 * **架構範式轉移**：開發 AI 應用已經從「給定完美 Prompt 期待單次輸出」轉移到「設計分散式控制系統 (規劃、執行、驗證、迴圈)」。模型選擇變成了一種微服務式的架構決策。 * **TDD 的終極型態**：自主編程代理的實踐是測試驅動開發 (TDD) 的極致延伸。只有在具備 100% 決定性測試覆蓋率與嚴格 Linting 規則的基礎設施上，代理才能安全地長效運行。 * **可觀測性 (Observability) 是關鍵**：不能依賴終端機輸出，必須建立以視覺化 Artifacts 為核心的監控儀表板，將代理的思考與執行過程具象化，以便人類在關鍵節點進行干預。 * **專案級上下文記憶**：導入會話日誌探勘機制 (Session Mining)，將反覆發生的錯誤轉化為靜態配置或系統規則，這是在不 Fine-tuning 模型的情況下，提升系統局部穩定性的最高效架構實踐。

--- tags: [Agent架構, MCP, 系統最佳化, Prompt工程] date: 2026-06-16 read: false source: "2026-06-16T093928+0800-Context Engineering for MCP Servers.md" original_title: "Context Engineering for MCP Servers" --- # Context Engineering for MCP Servers 原始來源與檔名：2026-06-16T093928+0800-Context Engineering for MCP Servers.md --- ## NAPKIN | 餐巾纸 ### 餐巾紙公式 > Agent 效能 = (MCP Tool Groups 範圍限縮 + 特定工具挑選) × Strip-Markdown 輸出最佳化 _透過減少無關的工具定義與冗餘的標記語言，最大化 LLM 的注意力與 Token 使用效率。_ ### 一句話 > 不要把所有 MCP 工具都塞給 Agent，精準控制輸入與輸出才能打造高效、低幻覺的生產級 AI。 ### 餐巾紙草圖 ```text [ MCP Server ] | +-- (1) Tool Groups (e.g. ECOMMERCE, SOCIAL_MEDIA) -> 減少 78-95% Token | +-- (2) Hand-pick Tools (精準挑選 1~2 個) -> 避免 LLM 分心 | +-- (3) Strip-Markdown -> 過濾粗體、圖片語法 -> 減少 40% Token | V [ AI Agent (Claude/Cursor) ] -> 更快、更準確、不易被反爬蟲機制阻擋 ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 當 MCP 伺服器載入大量工具時，會造成 Token 浪費與 LLM 幻覺，該如何解決？ * **核心答案**: 透過「工具分組」、「精準挑選工具」與「輸出格式最佳化」來進行 Context Engineering（上下文工程）。 * **論證結構**: 案例型（以 Bright Data MCP 伺服器與保護機制網站的爬取為例） ### 章節骨架 1. **問題背景**: 全工具載入導致 Token 浪費與準確度下降 2. **方法一**: 使用工具分組 (Tool Groups) 縮小範圍 3. **方法二**: 精準手動挑選工具 (Hand-pick individual tools) 4. **方法三**: 使用 Strip-Markdown 最佳化工具輸出 5. **結論**: Context Engineering 是生產級 Agent 的必備技能 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text 全工具載入耗用 10k+ Tokens --> LLM 注意力分散、產生幻覺 --> 限制工具載入範圍 (Groups/Hand-pick) --> 減少 Token 並提升專注度 --> 優化回傳的 Markdown 格式 (移除無效語法) --> 進一步節省 40% 輸出 Token --> 成功提升爬蟲與資料獲取成功率 ``` ### 關鍵證據 1. **LinkedIn 爬取測試**: 使用社交媒體工具群組 (Social Media) 的 MCP Agent 成功爬取受保護的 LinkedIn，而單獨使用 Claude 則失敗。 2. **Token 減少數據**: 動態構建工具列表可減少 78-95% 的 MCP 工具上下文 Token。 3. **Markdown 最佳化數據**: 使用 remark + strip-markdown 後，能剔除粗體、圖片語法，使回傳的網頁內容減少約 40% 的 Token。 ### 隱形假設與邊界 * **隱形假設**: * LLM 不需要完整的 Markdown 標籤也能理解網頁內容與結構。 * 使用者在任務開始前，能預先知道並配置 Agent 所需的特定工具群組或工具名稱。 * **邊界條件**: * 當任務屬於高度探索性、無法預知需要何種工具時，過度限縮工具範圍可能導致 Agent 缺乏必要手段而失敗。 * 若工具的回傳格式本身就是高度結構化的 JSON 而非 Markdown，Strip-Markdown 方法則不適用。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 文章主要集中在靜態設定檔（如 Claude Desktop config）層級的優化，未深入探討如何讓 Agent 在運行時「動態」請求與釋放工具權限。 * **知識連接**: 與軟體工程中的「最小權限原則」(Principle of Least Privilege) 以及作業系統的「記憶體分頁/載入」(Paging/Lazy Loading) 概念高度相似。 * **行動觸發**: 審查現有的 MCP 伺服器配置，停止「一次性注入所有工具」的做法，並為資料抓取類工具加入 Markdown 淨化器 (Sanitizer)。 ### 跨域映射 * 在 **資安領域**，這叫 **最小權限原則 (Principle of Least Privilege)** * 在 **資料庫領域**，這叫 **Select 投影優化 (避免 SELECT *)** ## STRUCTURE MAP | 全书结构图 ```text Context Engineering | +-------------------------+-------------------------+ | | | 1. Scope Tools 2. Precision Picks 3. Optimize Output | | | (Use Tool Groups) (Hand-pick specific tools) (Strip-Markdown filtering) | | | e.g., SOCIAL_MEDIA e.g., Amazon, eBay Remove bold/italic, images | | | Reduces Context 78-95% Laser-focused attention Reduces Output Tokens ~40% | | | +-------------------------+-------------------------+ | Production-Grade AI Agents (Better Accuracy, Less Cost) ``` --- # Context Engineering for MCP Servers (Architectural Deep Dive) ## 前言/背景 當 AI Agent (如 Claude Desktop 或 Cursor) 連線到 MCP (Model Context Protocol) 伺服器時，預設會將所有工具定義（包含 docstrings、參數等）全部載入上下文。對於擁有 60+ 生產級工具的伺服器來說，這輕易就會消耗超過 10,000 個 Tokens。這篇文章探討如何透過 Bright Data MCP 伺服器的開源實踐，運用「上下文工程 (Context Engineering)」解決 Token 浪費與 LLM 幻覺問題，從而打造更穩定且高效的 AI 爬蟲系統。 ## 章節詳細總結 ### 問題定義：工具定義全載入的代價 當 MCP 伺服器將所有工具傾倒給 LLM 時，會引發兩個架構層面的核心問題： * **Token 成本浪費**：為了 Agent 永遠用不到的工具定義支付昂貴的上下文成本。 * **準確度下降 (Reduced accuracy)**：LLM 容易被不相關的工具分散注意力，甚至在呼叫工具時產生參數幻覺 (Hallucinate parameters)。 ### 解決方案一：使用工具群組 (Tool Groups) 限縮上下文範圍 與其載入所有工具，系統架構應支援按功能領域 (Domain) 分組載入。 以 Bright Data MCP 為例，它將伺服器邏輯分組如下： * `ECOMMERCE`: Amazon, Walmart, eBay 等。 * `SOCIAL_MEDIA`: TikTok, Instagram, Facebook, LinkedIn 等。 * `BUSINESS`: LinkedIn, Crunchbase, Zillow 等。 **架構實踐**： 在 Claude Desktop 的配置檔 (`claude_desktop_config.json`) 中，透過環境變數 `TOOL_GROUPS` 傳入特定群組： ```json { "mcpServers": { "brightdata": { "command": "node", "args": ["build/index.js"], "env": { "BRIGHTDATA_API_TOKEN": "your_token", "TOOL_GROUPS": "SOCIAL_MEDIA" } } } } ``` *技術效益*：在底層，MCP 伺服器會動態建構工具列表，這種依賴注入 (Dependency Injection) 的變體設計，可將 MCP 工具的上下文 Token 消耗減少 78-95%。這使得 Agent 能夠成功爬取防護嚴密的網站（如 LinkedIn），因為它的注意力被高度集中在特定的社交媒體工具上。 ### 解決方案二：精準手動挑選工具 (Hand-pick individual tools) 當 Tool Groups 的範圍仍然過大時，系統支援更細粒度 (Fine-grained) 的配置，僅保留 Agent 執行任務所需的 1~2 個特定工具。 **架構實踐**： 若要打造一個僅負責價格監控的 Agent，可以使用 `ALLOWED_TOOLS` 環境變數： ```json { "mcpServers": { "brightdata": { "command": "node", "args": ["build/index.js"], "env": { "BRIGHTDATA_API_TOKEN": "your_token", "ALLOWED_TOOLS": "amazon_search,ebay_search,google_shopping" } } } } ``` *技術效益*：這類似於微服務架構中的路由白名單 (Routing Whitelist)，它強制將 LLM 的工具呼叫空間縮小至絕對必要範圍。此外，這種設計支援 `TOOL_GROUPS` 與 `ALLOWED_TOOLS` 混用，提供了極大的配置彈性。 ### 解決方案三：透過 Strip-Markdown 最佳化工具輸出 選擇正確的輸入工具僅完成了一半的最佳化；另一半在於優化工具回傳給 LLM 的資料（Payload Optimization）。 當系統從網頁爬取內容時，原始 Markdown 包含許多 LLM 進行語意分析時不需要的標記語法： * **粗體/斜體**：`**Important**` 可簡化為純文字 `Important`。 * **圖片語法**：`` 可簡化為 `alt text` 或直接移除。 * **標題**：`### Section Title` 轉為 `Section Title`。 * **程式碼區塊**：減少多餘的 backticks，僅保留內容。 **架構實踐**： MCP 伺服器在內部整合了 `remark` (Markdown 處理庫) 結合 `strip-markdown` 套件，在資料回傳給 Client 前進行攔截與過濾 (Interceptor Pattern)。 *技術效益*：確保 LLM 仍能獲取關鍵的文本、評論與評分資訊，但移除了冗長的 URL、圖片路徑與標記符號。這種資料淨化 (Data Sanitization) 流程能為抓取下來的網頁帶來約 40% 的 Token 縮減。 ## 總結與結論 * **實踐最小權限原則 (PoLP) 於 Prompt 工程**：MCP Server 不應依賴 Client 端來過濾工具，而應在配置層 (Configuration) 就透過 `TOOL_GROUPS` 與 `ALLOWED_TOOLS` 實作白名單，拒絕不必要的 Context 污染。 * **輸出資料淨化 (Payload Sanitization) 提升效能**：針對 Web Scraping 場景，實施中介軟體 (Middleware) 來剔除無效的 Markdown 標記，不僅能降低約 40% 的 Token 傳輸成本，還能加速 LLM 的推理速度。 * **上下文工程 (Context Engineering) 的系統化**：構建生產級 Agent 時，我們不能單純依賴基礎模型的 Context Window 變大，而必須從系統架構端介入，動態控制輸入端 (Tool List) 與輸出端 (Tool Output)，以維持低幻覺、高精度的穩定運行。

--- tags: [Agent架構, LoopEngineering, Claude, AI工作流, 自動化] date: 2026-06-16 read: false source: "2026-06-16T093922+0800-Cómo crear Loops con Claude.md" original_title: "Cómo crear Loops con Claude" --- # Cómo crear Loops con Claude  ## 核心概念與 XRay 結構分析 (XRay Structure) * **核心論點的轉變**：「提示詞工程 (Prompt Engineering)」作為工作單元的時代已經結束，未來的核心是「迴圈工程 (Loop Engineering)」。過去人類在提示與修改之間成為了系統效能的瓶頸，新的典範是賦予 Agent 一個可驗證的任務目標，讓其自主完成迭代。 * **迴圈的五大運作階段**：一個完整的 Agent 迴圈 (Loop) 會經歷：**發現 (Discover) → 計畫 (Plan) → 執行 (Execute) → 驗證 (Verify) → 迭代 (Iterate)**。如果驗證失敗，Agent 會帶著失敗的反饋重新開始；如果驗證通過，迴圈即告終止。其核心在於「可驗證性」，例如「所有 /auth 相關的測試通過且 lint 無誤」，而非「寫出好看的程式碼」。 * **實驗效能突破 (Fable 5 vs Opus 4.7)**：在 Anthropic 內部的 Parameter Golf 挑戰中 (限制 16MB 內、10分鐘、8 張 H100 GPU 上尋找最佳訓練模型)，Fable 5 的效能達到了 Opus 4.7 的 6 倍。Fable 5 敢於在迴圈中做出重大的架構性調整，並能承受量化過程中的退化錯誤，最終從迴圈內自我修復並取得最佳結果；而 Opus 4.7 則受限於微小的參數調整。 * **黃金法則：執行者與驗證者必須分離**：LLM 模型往往不擅長客觀評價自己的產出。解決方案是引入一個獨立的「驗證子 Agent」，該 Agent 擁有獨立的上下文，專門負責評判工作是否達標。沒有獨立驗證者，Agent 容易偏離軌道；有了獨立驗證者，Agent 就能持續優化。 * **跨會話的深度記憶機制**：在 Continual Learning Bench 測試中，Fable 5 的表現 (0.839) 遠勝 Opus 4.7 (0.700) 與 Sonnet 4.6 (0.364)。文章將記憶能力分為五個層次： 1. 記錄失敗 2. 調查失敗原因 3. 驗證原因並轉化為確定的事實 4. 將事實提煉為通用規則 5. 在未來任務中直接查詢這些規則，而非重新推導 Fable 5 能夠將高達 73% 的診斷驗證為規則，使其成為一個能跨越會話累積知識的系統。 ## 架構深度剖析 (Architectural Deep Dive) * **建構高品質迴圈的六大架構模組**： 1. **自動化 (Automations)**：驅動迴圈持續運作的引擎，包含 Prompt、執行頻率與可量化的目標。例如 Claude Code 中的 `/goal` 指令，在條件滿足前會不斷驅動系統前進。 2. **工作樹 (Worktrees)**：允許並行運行的 Agent 互不干擾。每個 Agent 在自己的 Git 分支和隔離目錄下運作，避免檔案衝突。 3. **靜態技能與上下文 (Skills / Context)**：專案的核心定義文件 (如 `VISION.md`, `ARCHITECTURE.md`, `RULES.md`)。這是每次迴圈啟動時必讀的基礎設定，避免 Agent 每次都從零開始推導專案結構。 4. **連接器 (Connectors / MCP)**：擴展 Agent 的感知與操作範圍，使其能讀取 Issue Tracker、操作資料庫、建立 PR，甚至在 CI 綠燈時發送 Slack 通知，打破純檔案系統的限制。 5. **子 Agent 驗證機制 (Subagents)**：利用全新的模型實例來判定當前迴圈是否可以終止。這種職責分離是確保品質閘門 (Quality Gate) 可靠性的關鍵。 6. **長期記憶儲存 (Memory)**：一個獨立於對話之外的 Markdown 檔案 (如 `MEMORY.md`)，負責記錄「已測試的方法」、「已驗證的事實」與「尚未解決的問題」，讓第 47 次迭代的 Agent 能完全掌握前 46 次的探索歷程。 * **兩種實務落地架構設計**： * **選項 A：基於 Claude Code 的指令迴圈 (適合中短期任務)** * **配置與啟動**：準備好上下文文件後，使用 `/goal [具體且可驗證的條件]. 最大 [N] 輪限制.` 來啟動。 * **運行邏輯**：Agent 執行任務，獨立評估模型裁定。若不通過則自動進入下一輪 (帶入失敗分析)；若通過則清除 Goal 並終止，全程無須人類介入。 * **選項 B：基於 Claude Managed Agents 的量表評估 (適合長時程任務)** * **配置與啟動**：設計一份嚴謹的「評分量表 (Rubric)」，逐行列出評估標準。 * **運行邏輯**：透過 Outcomes 機制觸發評估子 Agent。在達到 `max_iterations` 限制或所有量表條件皆滿足之前，執行 Agent 會被強制要求持續迭代。 * **迴圈的收斂與發散策略 (Closed vs Open Loops)**： * **閉環 (Closed Loop)**：由開發者定義清晰的路徑、階段性評估與停止點。這是初期最推薦的架構，結果穩定且資源消耗可控。 * **開環 (Open Loop)**：僅給予廣泛目標，放任 Agent 自由探索。雖然潛力極大，但若缺乏優良的品質閘門，極易消耗大量 Token 並產生無效輸出。 * **角色定位的轉變：Prompt Engineer vs Loop Engineer**： * 提示詞工程師：手工編寫指令並人工審查輸出，人類本身就是系統中的反饋迴圈。 * 迴圈工程師：負責設計高效的反饋循環與自動化測試機制，將系統本身建構成為自動驗證與修正的閉環，將專注力放在架構層級的任務定義與記憶管理。

--- tags: [Agent架構, ClaudeCode, AIWorkflow] date: 2026-06-16 read: false source: "2026-06-16T093942+0800-Goal + Loop + Workflows 三大利器.md" original_title: "Goal + Loop + Workflows 三大利器" --- # Goal + Loop + Workflows 三大利器  ## 核心概念 (Core Concepts) - **/goal (目標導向)**: 將任務完成的判斷權交給可驗證的客觀條件。由單一智能體在當前會話中進行多輪迭代，每次迭代後由評估模型檢查條件，達標即自動停止。 - **/loop (定時輪詢)**: 按固定時間節奏重複執行相同任務，專注於外部狀態的監控與值守。由定時器驅動，只要不手動中止便會持續運行，無明確終點。 - **/workflows (平行編排)**: 用於監控多智能體平行處理進度的控制面板。針對單一上下文無法容納的大型任務，橫向拉起多個子智能體分頭執行並彙整結果。 ## 架構深度解析 (Architectural Deep Dive) 本篇文章深入剖析了 Claude Code 在人機互動模式上的三大核心指令機制，這三個機制分別解決了任務執行的終點、節奏與規模問題。它們將傳統的「一問一答」互動，進化為「交代目標後自動執行」的代理化操作。 ### 1. 單智能體縱向深度：/goal 與自動化驗證機制 `/goal` 指令的底層架構依賴於「輕量級評估模型」與「迴圈控制」。當使用者給定一個具體驗收標準（例如特定目錄下的測試通過且 Lint 無錯誤）後，Claude 會自動進行多輪修改與測試。每一輪執行完畢後，評估模型會介入檢查條件是否滿足。此機制將判斷任務完成的控制權從人類手中轉移至機器驗證邏輯，適合處理具有客觀終點的離散任務（如 API 遷移、設計文件實作、Issue 清理）。值得注意的是，`/goal` 並不依賴定時器或平行編排，其多輪迭代完全由內建的條件判斷機制所驅動。 ### 2. 時間驅動的輪詢架構：/loop 與狀態監聽 相對於 `/goal` 的條件驅動，`/loop` 採用純粹的時間間隔觸發機制。它不關心任務是否「完成」，而是扮演一個背景值守（Daemon）的角色，定時監測外部狀態的變化（如 CI/CD 部署狀態、遠端任務佇列、PR 列表）。技術上，它以固定的頻率執行同一組 Prompt。若使用者未指定時間間隔，模型甚至能根據監測對象的特性自動調整喚醒頻率，以優化 Token 使用率並避免頻繁發送無效請求。 ### 3. 多智能體平行編排：Workflow 引擎與 /workflows 面板 當任務規模超越單一大語言模型的上下文視窗限制，或需要多角度交叉驗證時，系統會啟用 Workflow 引擎進行平行處理。與前兩者單線程多輪的架構不同，Workflow 屬於橫向擴展，能夠同時啟動數十個子智能體（Sub-agents），分別執行代碼審查、批量文件遷移或多路對抗式驗證。而 `/workflows` 指令本身並不發起任務，它僅作為一個即時監控面板，用來視覺化呈現各個平行智能體的執行進度與狀態匯總。由於多智能體編排會消耗大量 Token，因此這套機制必須由使用者明確宣告啟動，不會被單一的 `/goal` 指令自動在底層喚醒。 ### 4. 系統性防呆與最佳實踐 在實際應用架構中，必須嚴格區分這三者的適用場景以避免運算資源浪費： 具備明確驗證條件的任務必須使用 `/goal`，若誤用 `/loop` 將導致條件達成後系統依然無意義地持續消耗資源。其次，設置 `/loop` 的輪詢間隔時，必須與外部系統（如 CI 伺服器）的真實狀態變化頻率相匹配，盲目縮短輪詢間隔只會徒增 Token 消耗並破壞快取狀態。最後，多智能體平行處理（Workflow）成本極高，僅適用於大型任務拆解，對於單一上下文可處理的微小修改（如錯字修正）應避免啟動此機制，以防陷入效能陷阱。 ## 洞察與應用 (Insights & Applications) - **互動典範轉移**: 從「指令-回應」的微觀控制，轉變為「意圖-驗證-自治」的宏觀放權，大幅降低了開發者在排程與催促上的認知負載。 - **任務解構思維**: 在執行大型專案前，必須先評估任務的本質維度：是需要明確的終點驗證（Goal）、持續的狀態監控（Loop），還是橫向的算力擴展（Workflow）。 - **成本與效能最佳化**: 正確選擇 AI 代理工具不僅關乎任務能否自動完成，更直接影響 API 呼叫成本與系統快取命中率，為開發團隊帶來實質的經濟效益。

--- tags: [Agent架構, AI工程, 系統架構, LLM應用] date: 2026-06-16 read: false source: "2026-06-16T094254+0800-Harness Engineering vs Prompt Engineering vs Context Engineering.md" original_title: "Harness Engineering vs Prompt Engineering vs Context Engineering" --- # Harness Engineering vs Prompt Engineering vs Context Engineering  原始來源與檔名：2026-06-16T094254+0800-Harness Engineering vs Prompt Engineering vs Context Engineering.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > Agent = Prompt (如何說) + Context (說什麼) + Harness (如何執行與控制) _建構可靠的 AI 系統不僅僅依賴模型的聰明程度，更依賴於我們如何與之溝通、餵給它什麼資訊，以及用什麼系統來包裝它。_ ### 一句话 > 要讓 AI 模型從「玩具」變成「生產力工具」，必須超越 Prompt 與 Context，打造堅固的 Harness (運行時與控制系統)。 ### 餐巾纸草图 ```text +-------------------+ | Harness | | (Orchestration) | | | | +-------------+ | | | Context | | | | +---------+ | | | | | Prompt | | | | | | +-----+ | | | | | | | LLM | | | | | | | +-----+ | | | | | +---------+ | | | +-------------+ | +-------------------+ ``` ## ROUND 1: SKELETON | 骨架掃描 **"这本书在说什么"** * **核心问题**: 為什麼光靠 Prompt Engineering 和 Context Engineering 不足以打造可靠的 AI 生產系統？ * **核心答案**: 因為系統的可靠性、狀態管理、錯誤恢復與真實世界互動，需要透過 Harness Engineering (架構運行時與控制系統) 來達成。 * **论证结构**: 對比型 (橫向比較 Prompt, Context, Harness 的優缺點與範疇) ### 章节骨架 1. **Prompt Engineering**: 如何下達正確指令 2. **Context Engineering**: 如何提供對的資訊 3. **Harness Engineering**: 如何控制系統執行 ## ROUND 2: DISSECTION | 血肉解剖 **"凭什么这么说"** ### 论证链 ```text 模型缺乏穩定性與狀態記憶 --> Prompt 可引導方向但脆弱 --> Context 可補充知識但無法確保執行正確 --> Harness 提供運行時控制、記憶與防呆機制 --> 最終組成可靠的 Agent ``` ### 关键证据 1. **Prompt 的極限**: 一個完美的 Prompt 無法彌補知識缺失、缺乏長期記憶或自我糾錯能力。 2. **Context 的極限**: 給予模型整個程式碼庫和 API 規格可以改善生成品質，但如果程式碼編譯失敗，單靠 Context 無法讓系統自動修復。 3. **Harness 的必要性**: 在實際案例中，開發代理 (Coding Agent) 能夠規劃、實作、測試、驗證並重試，這些都需要依賴 Harness 的協調與反饋迴圈。 ### 隐形假设与边界 * **隐形假设**: * 目前的 LLM 模型尚未具備完美的自我糾錯與長期推理能力。 * 企業應用對容錯率的要求遠高於個人輔助工具。 * **边界条件**: * 當任務屬於一次性、低風險的文本生成時，Harness 的重要性較低。 * 如果未來模型 (如更強大的基礎模型) 具備內建的完美執行與記憶機制，Harness 的部分功能可能會被弱化。 ## ROUND 3: SOUL | 靈魂提取 **"还能怎么用"** * **作者盲点**: Harness 的建構成本與維護複雜度可能會抵銷 AI 帶來的開發效率提升，文章並未深入探討如何降低 Harness 的開發門檻。 * **知识连接**: Harness Engineering 與傳統微服務架構中的 Orchestration (如 Kubernetes, 服務網格) 非常相似，都是在解決「控制平面 (Control Plane)」的問題。 * **行动触发**: 停止在每一次生成結果不佳時只去微調 Prompt，開始思考如何建立測試迴圈、日誌追蹤與重試機制 (Harness)。 ### 跨域映射 * 在 **軟體架構**，这叫 **控制平面 (Control Plane) / 服務網格 (Service Mesh)** * 在 **DevOps**，這叫 **CI/CD 管道與監控 (Pipeline & Monitoring)** --- # Harness Engineering vs Prompt Engineering vs Context Engineering (Architectural Deep Dive) ## 前言/背景 隨著大語言模型 (LLM) 的應用日益普及，業界發現單純依靠提示工程 (Prompt Engineering) 或提供上下文 (Context Engineering) 已無法滿足生產環境的需求。這篇文章旨在釐清這三個概念的差異，並強調「Harness Engineering (封裝工程/運行時工程)」在構建可靠、可用於生產環境的 AI 代理 (Agents) 中的關鍵作用。 ## 章節詳細總結 ### 1. 提示工程 (Prompt Engineering)：控制對話的藝術 提示工程的本質是**與 AI 模型溝通的藝術**，透過精心設計的指令來引導 LLM 提供我們期望的輸出格式與內容。這些「黃金指令」會存在於 LLM 每次請求的上下文視窗中。 * **關鍵技術 (Key Techniques)**： * **角色扮演 (Role-playing)**：賦予 LLM 特定的專業角色（例如：「你是一位資深的軟體工程師...」）。 * **思維鏈 (Chain-of-Thought)**：強制 LLM 在給出最終答案前，逐步推理問題，提高邏輯準確度。 * **小樣本提示 (Few-shot Prompting)**：提供輸入與輸出的範例，讓模型學習期望的行為模式。 * **輸出格式化 (Output Formatting)**：強制要求模型以 JSON、XML 或 Markdown 等結構化格式回應。 * **約束條件 (Constraints)**：定義回應的語氣、長度、安全規則等。 * **優勢與限制**： * **優勢**：極大影響模型表現，成本低且無需資源密集型的微調 (Fine-tuning)。 * **限制**：具有脆弱性且屬「單次擊發 (Single-shot)」。完美的提示無法彌補模型缺乏領域知識、長期記憶或錯誤恢復能力的問題。LLM 被當作無狀態的函數，但現實任務往往是一個有狀態的流程。 ### 2. 上下文工程 (Context Engineering)：提供模型需要的知識 上下文工程的重點在於**策展與管理放置於 LLM 上下文視窗中的資訊**。目的並非塞滿視窗，而是智慧地「在正確的時間提供正確的資訊」。 * **運作原理與關鍵概念**： * **檢索增強生成 (RAG, Retrieval-Augmented Generation)**：動態拉取相關的文件或數據。 * **記憶系統 (Memory Systems)**：管理短期對話歷史與長期知識庫。 * **上下文壓縮 (Context Compression)**：透過摘要、分塊 (Chunking) 或漸進式揭露來減少不必要的 Token 消耗。 * **架構決策理由 (Why)**： * **Token 成本與效能**：上下文視窗越大，API 成本越高，延遲 (Latency) 也會增加。更重要的是，給予過多資訊會導致「資訊過載 (Information overload)」，反而降低模型效能。 * **克服知識盲區**：LLM 天生不了解企業的程式碼庫、商業邏輯或內部 API。透過提供正確的 Context，可以避免「上下文腐敗 (Context rot)」。 * **限制**：即使提供了完美的上下文（例如完整的 Repo 結構、API 規格），若生成的程式碼編譯失敗，系統依然無法自動修復，因為它缺乏持續執行的控制迴圈。 ### 3. Harness Engineering：控制執行的運行時架構 Harness Engineering 是真正讓 AI 模型進入生產環境的核心。它指的是**圍繞 LLM 建立的運行時 (Runtime)、編排層 (Orchestration)、護欄 (Guardrails)、工具整合 (MCP)、記憶體系統以及反饋迴圈**。簡言之，就是將機率性的 AI 轉換為確定性的軟體系統。 * **架構公式**：**Agent = Model + Harness** * **核心組件與技術細節**： * **運行時與編排 (Runtime and Orchestration)**：管理模型、工具和工作流程之間的互動邏輯。 * **護欄 (Guardrails)**：強制執行安全性、合規性和業務邏輯過濾。 * **記憶體系統 (Memory Systems)**：在多次互動與跨會話中維持狀態 (State)。 * **工具與 MCP 整合 (Tool and MCP Integration)**：讓模型能與外部 API、資料庫或終端機互動（例如 Model Context Protocol）。 * **反饋迴圈 (Feedback Loops)**：系統能從失敗中學習（例如，測試失敗後將錯誤日誌餵回模型進行修復）。 * **可觀測性與容錯 (Observability & Resilience)**：監控成本、延遲，並優雅地處理錯誤、重試 (Retries) 與降級 (Fallbacks)。 * **真實世界應用場景**： * 一個具備 Harness 的 Coding Agent 其工作流為：**規劃器拆解任務 -> 代理實作 -> 自動執行測試 -> 錯誤反饋迴圈 -> 強制執行架構規則 -> 人工批准 (Human-in-the-loop) 高風險變更**。這與傳統 CI/CD 流程高度融合。 ## 總結與結論 * **系統工程重於模型智慧**：當前 AI 應用的瓶頸已經從「模型不夠聰明」轉移到「系統工程不夠完善」。我們不需要等待 GPT-6 才能打造生產級應用，利用現有模型搭配強大的 Harness 即可解決大部分商業問題。 * **將 AI 視為不可靠的微服務**：在架構設計上，應將 LLM 視為一個會隨機失敗、有延遲且無狀態的外部相依服務。必須在呼叫層外圍加上重試 (Retry)、斷路器 (Circuit Breaker) 與日誌追蹤等經典分散式系統的防護機制。 * **從 Stateless 到 Stateful**：Prompt 和 Context 解決的是單次無狀態請求 (Stateless) 的品質問題，而 Harness Engineering 則負責維持長生命週期任務中的狀態 (Stateful) 與錯誤恢復，這是建構自主代理 (Autonomous Agents) 的必要條件。

--- tags: [Agent架構, AI代理, 工作流, Hermes, 系統架構] date: 2026-06-16 read: false source: "2026-06-16T093758+0800-Hermes Agent Is CRACKED Now And Most Builders Have No Idea What It Actually Is..md" original_title: "Hermes Agent Is CRACKED Now And Most Builders Have No Idea What It Actually Is." --- # Hermes Agent Is CRACKED Now And Most Builders Have No Idea What It Actually Is.  ## 核心概念 (Core Concept) Hermes Agent 是一個具備持久記憶與自主技能創建能力的伺服器常駐型 AI 代理架構，它打破了傳統會話型（Session-based）代理每次啟動都必須重新注入上下文的限制，透過長時間運作與自建技能庫實現知識的複利效應。 ## XRay 結構分析 (XRay Structural Analysis) * **架構典範轉移 (Paradigm Shift)** * 會話型架構 (Session-based)：如 Claude Code, Cursor, Codex。啟動即從零開始，關閉即遺忘，開發者面臨沉重的「上下文稅 (Context Tax)」。 * 持久型架構 (Persistent)：如 Hermes。常駐於本地端或伺服器，具備跨日誌記憶，將重心從「優化單次 Prompt」轉移至「長期代理管理」。 * **五大核心差異化特徵 (Key Differentiators)** * 跨會話持久記憶：利用資料庫與 LLM 自動摘要機制保存所有互動。 * 自主技能創建：執行完複雜任務後，自動歸納經驗並生成系統可重用的功能模組。 * 多角色平行處理 (Multi-profile)：支援設立組織架構（如幕僚長、研究主管），讓各自獨立的代理平行運作。 * 多平台無頭通訊：深度整合 Telegram 等 20+ 款通訊軟體，支援遠端行動操控。 * 伺服器常駐執行 (Server-resident)：可部署於 $5 VPS、GPU 叢集或無伺服器架構（如 Modal, Daytona）。 * **檔案與組態結構 (Component Design)** * `SOUL.md`：核心身份配置檔，取代系統預設提示詞。 * Markdown 技能檔：具備高度可讀性與版本控制能力的程序記憶。 * 看板儀表板 (Kanban Dashboard)：本機端調度與監控代理狀態的可視化介面。 ## 架構深度拆解 (Architectural Deep Dive) * **混合式記憶與上下文管理**：Hermes 不依賴單一會話的 Token 視窗限制，而是建構了基於 FTS5（全文本搜尋）機制的持久化記憶庫。系統會在後台對歷史對話進行 LLM 自動摘要，確保長時間運行下的記憶不會產生嚴重的上下文漂移（Context Drift）。 * **自我進化機制與 Markdown 技能庫**：每次代理完成超過 5 次工具呼叫的複雜任務後，會自動在 `~/.hermes/skills/` 目錄下生成人類可讀、可被 Git 版控的 Markdown 技能檔案。這些技能檔結構嚴謹，包含觸發條件、執行步驟、已知陷阱（Pitfalls）與驗證步驟（Verification）。這使得代理的程序記憶能夠實質累積，避免重複試錯。 * **系統提示詞注入與邊界控制 (`SOUL.md`)**：有別於專案層級的 `CLAUDE.md`，Hermes 引入了代理本體層級的 `SOUL.md`。此檔案會直接覆寫大語言模型系統提示詞的最高優先順序（Slot #1），用於定義代理的個性、語氣以及硬性邊界約束（例如安全協議：「未經明確確認，絕不匯出資金」）。 * **異構模型路由 (Model Routing)**：架構設計為與供應商解耦（Provider-agnostic）。日常驅動可依賴低延遲的 GPT-5.5；多步驟複雜邏輯推理可動態切換至 Claude Opus 4 或 Sonnet 4；而長達數十小時的自主後台運作（高達上千次工具呼叫）則可路由至 Qwen 3.7 Max 處理，以優化 Token 成本效益。 * **非同步任務調度與 Daemon 輪詢**：Hermes 在背景以 Daemon 模式運行（v0.16+ 預設每 60 秒輪詢一次任務佇列）。使用者透過 `/goal` 指令（配合可配置的 `max_turns`，例如針對程式碼重構設為 50）觸發狀態機，代理便會在無人值守的情況下自主迭代，並透過 Telegram 即時回報進度，達成從「交談」到「非同步委派」的互動模式轉變。 ## 實踐指南 (Implementation Guide) * **基礎安裝與身份配置**：透過 Curl 腳本一鍵安裝後，首要任務是編輯 `~/.hermes/SOUL.md`。將代理設定為具備特定品味的實用主義工程師，並設置安全護欄，防止預設的幻覺或過度解釋。 * **通訊端點綁定**：在 Telegram 中透過 `@BotFather` 取得 Token 並輸入至 Hermes 配置中。務必發送「第一則訊息」告知代理你的身份與中長期目標，該訊息將成為代理後續所有主動任務的預設過濾器。 * **構建平行多角色結構 (Profiles)**：為不同職能建立專屬目錄（如 `chief-of-staff`, `head-of-research`），分別撰寫各自的 `SOUL.md` 並隔離記憶庫。將任務投放至看板的 Triage 區塊，讓多個代理在背景平行處理。 * **漸進式授權與隔夜執行**：為了控制 Token 花費與安全性，預設關閉「電腦控制」與「瀏覽器自動化」功能，僅在特定 Profile 需要時透過 localhost:9119 看板個別開啟。睡前使用 `/goal` 指令派發高耗時研究任務，讓代理在夜間自主調用數十個回合完成草稿，實踐自動化的複利成長。

--- tags: [Agent架構, 知識管理, Obsidian, 工作流, AI工程] date: 2026-06-16 read: false source: "2026-06-16T093720+0800-How To Build a Second Brain That Runs Itself With Obsidian (Full Course).md" original_title: "How To Build a Second Brain That Runs Itself With Obsidian (Full Course)" --- # 如何使用 Obsidian 打造自動運作的第二大腦 (完整教學)  原始來源與檔名：2026-06-16T093720+0800-How To Build a Second Brain That Runs Itself With Obsidian (Full Course).md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 第二大腦 = (捕捉想法 × 0 摩擦力) + (多 Agent 協同批次處理 × 睡眠時間) _知識管理不該依賴個人的下班時間，而是將大腦視為「接收器」，將整理與連結的苦工交給在背景定時運行的 Agent 群集。_ ### 一句话 > 停止扮演自己知識庫的圖書管理員，直接僱用 300 個 AI Agent 在深夜為你自動拆解、連結與反思所有原始資訊。 ### 餐巾纸草图 ```text [Day Shift: You] [Night Shift: 300-Agent Swarm] 0-raw/ (Dump) ----> 11 PM: Scouts (Fetch sources) 3 AM: Refinery (Atomize, Link, Critique) 6 AM: Editors (Synthesize, Briefing) -----> briefings/ (Ready for coffee) ``` ## ROUND 1: SKELETON | 骨架掃描 **"这本书在说什么"** * **核心问题**: 為什麼多數人的「第二大腦」最終都變成充滿未整理筆記的數位墳墓，以及該如何解決？ * **核心答案**: 因為傳統方法依賴你手動整理；解法是透過本地多 Agent 系統，在夜間自動化執行蒐集、原子化、連結與審查的工作。 * **论证结构**: 案例型與系統工程型 ### 章节骨架 1. **心智重構**: 第二大腦需要夜班 2. **認識夜班**: 5 種 Agent 角色分工 3. **週期展示**: 從混亂筆記到清晰報告 4. **架構設計**: 是煉油廠而非抽屜 5. **核心章程**: 系統的最高準則 6. **運行引擎**: Kimi Work 桌面代理 7. **四大劇本**: 夜間的自動化排程 8. **無感捕捉**: 將輸入摩擦降至最低 9. **全域大腦**: MCP 協議統一知識庫 10. **防腐護欄**: 避免系統崩壞的原則 ## ROUND 2: DISSECTION | 血肉解剖 **"凭什么这么说"** ### 论证链 ```text 人類缺乏時間與精力手動整理筆記 --> 筆記系統越龐大越容易癱瘓 --> 引入夜間自動運行的 Agent 群集分工處理 --> 將大文件拆解為原子筆記並建立關聯 --> 利用 AI 找出矛盾並生成摘要 --> 系統自動隨時間增值而非腐爛 ``` ### 关键证据 1. 透過實際的 `0-raw/` 凌亂筆記範例，展示系統如何在無人介入的情況下，於清晨轉化為具備 [FRICTION] 矛盾提示與結構化的原子筆記。 2. 透過明確的 Pipeline 資料夾結構 (`0-raw/`, `2-atoms/`, `3-threads/`) 證明「流水線」比「主題分類」更適合 AI 處理。 3. 介紹 Kimi Work (K2.6 模型) 的 256K Context、WebBridge 與 Cron 引擎等具體規格，證明本地自動化 300 個 Agent 的技術可行性。 ### 隐形假设与边界 * **隐形假设**: * 使用者每天能穩定產生或輸入一定品質的原始資料 (Raw Data)。 * AI 提取的原子筆記能精確反映原始文章的真實意圖，不會產生嚴重幻覺（透過不修改來源檔來防範）。 * 本地硬體與 Kimi Work 能夠穩定地在夜間被喚醒並執行高併發的 LLM 推理。 * **边界条件**: * 當原始來源包含大量圖像、影片等非純文字內容時，此系統目前的處理能力可能受限。 * 當系統產生的矛盾 (Frictions) 數量過多，超過人類每週 20 分鐘的消化極限時，系統可能再度陷入停滯。 ## ROUND 3: SOUL | 靈魂提取 **"还能怎么用"** * **作者盲点**: 系統高度依賴文字和 Markdown 的結構，對於需要視覺化空間思考或手繪草圖的知識捕捉沒有著墨；此外，300 個 Agent 的本地並行運算對硬體資源的消耗（如記憶體與 GPU/NPU）可能被低估。 * **知识连接**: 這與軟體工程中的 ETL (Extract, Transform, Load) 資料管線、GitOps 自動化、以及微服務架構 (Microservices) 中不同角色的協同工作模式高度一致。 * **行动触发**: 停止在 Obsidian 中建立複雜的「主題資料夾」，改為建立基於處理階段的「Pipeline 資料夾」；嘗試撰寫第一份針對知識庫的「提示章程」(House Rules)。 ### 跨域映射 * 在 **軟體工程**，这叫 **非同步批次處理與 CI/CD 管線 (Asynchronous Batch Processing & CI/CD Pipeline)** * 在 **組織管理**，這叫 **非同步跨職能團隊協作 (Asynchronous Cross-functional Team Collaboration)** ## STRUCTURE MAP | 全书结构图 ```text [Human (Day Shift)] | (Raw Capture) v +-------------------------------------------------------+ | Local Vault Pipeline | | | | 0-raw/ <--- WebBridge (Scouts fetch articles) | | | | | v | | 1-desk/ (Scratch space for Swarm) | | | | | v | | 2-atoms/ <--- Catalogers (Atomize) | | | <--- Cartographers (Link) | | | <--- Critics (Find Frictions) | | v | | 3-threads/ <-- Editors (Synthesize & Brief) | +-------------------------------------------------------+ | (Morning Briefing) v [Human (Decision & Review)] ``` --- # How To Build a Second Brain That Runs Itself With Obsidian (Full Course) (Architectural Deep Dive) ## 前言/背景 這篇文章探討了解決個人知識管理 (PKM) 長期痛點的終極方案。過去如 Zettelkasten 或 PARA 等方法，最終都因為依賴人類作為「免費圖書管理員」進行手動整理、連結和歸檔而失敗。文章提出了一套基於本地端 (Local-first)、Markdown 格式與 300 個 AI Agent 群集的自動化架構。這套系統在夜間自動執行資料的抓取、拆解、連結與反思，讓使用者的第二大腦從一個靜態的數位抽屜，進化成一個自動運作的知識煉油廠 (Refinery)。 ## 章節詳細總結 ### 1. 角色分工架構：認識「夜班」團隊 系統的核心不在於單一的強大 AI 模型，而在於將任務拆解給五個具備特定職責的 Agent 角色，如同微服務架構 (Microservices architecture) 般並行運作： * **Scouts (斥候)**：負責執行外部資料抓取，驅動瀏覽器進入閱讀清單並帶回完整原文。 * **Catalogers (編目員)**：並行處理的核心。針對每篇來源文章，將其拆解為多個「原子筆記」(Atomic notes)，堅持「一個概念一個檔案」的原則。 * **Cartographers (製圖師)**：負責維護知識圖譜 (Link graph)。每當新的原子筆記生成，就將其與既有筆記建立關聯。 * **Critics (評論家)**：最具價值的核心邏輯。比對新筆記與既有金庫內容，尋找矛盾與衝突，並打上 `[FRICTION]` 標籤。 * **Editors (編輯)**：負責知識的聚合與摘要。將相關的原子筆記編織成更長的脈絡文件 (Synthesis documents)，並產生每日晨報。 ### 2. 資料流與目錄結構 (Pipeline Directory Architecture) 作者拋棄了傳統的「主題式 (Topic-based)」分類，改採「狀態處理式 (Pipeline-based)」的目錄結構，這是一種典型的 ETL (Extract, Transform, Load) 實踐： ```markdown brain/ ├── 0-raw/ <- 接收端 (Intake)，未處理的原始想法與草稿。 ├── 1-desk/ <- 工作區 (Scratch space)，Agent 夜間處理的暫存區。 ├── 2-atoms/ <- 原子筆記 (Permanent core)，一檔一概念。 ├── 3-threads/ <- 聚合脈絡 (Synthesis)，由編輯整合的長篇文件。 ├── sources/ <- 來源庫 (Originals)，絕對唯讀，防止知識漂移。 ├── briefings/ <- 輸出端，Agent 寫給人類的晨報與報告。 ├── playbooks/ <- 劇本/配置檔，定義不同批次任務的指令。 └── house-rules.md <- 系統全域章程。 ``` **關鍵架構決策 (Architectural Reasoning)**： * **不可變的資料來源 (Immutable Sources)**：`0-raw/` 和 `sources/` 被設定為 **Read-Only (唯讀)**。AI 代理只能讀取並衍生出新內容，但絕不能修改原始資料。這徹底解決了 AI 知識庫常見的「知識漂移 (Knowledge Drift)」問題——避免了 AI 用自己產生的二手筆記生成三手筆記，最終導致內容失真甚至產生幻覺。 ### 3. 系統核心與引擎規範 (The Engine & House Rules) 整套系統透過一個名為 `house-rules.md` 的全局系統提示詞 (System Prompt / Charter) 來約束 Agent 的行為。 **Prime Directive (最高指導原則)**： > 每個原子筆記都必須追溯到 `sources/` 或 `0-raw/` 中的真實來源。沒有來源就不能建立筆記，絕不能用語氣自信的幻覺來填補資訊空白。 運作此架構的底層引擎是 **Kimi Work** (基於開源的 Kimi K2.6 模型，256K Context Window)。此引擎具備幾個達成自動化的關鍵能力： * **Agent Swarm**：支援最高 300 個子代理與 4000 個協同步驟並發執行 (Concurrency)。 * **Built-in Cron Engine**：內建的排程引擎，支援定時觸發腳本與 Agent。 * **WebBridge**：能夠接管並操作使用者已登入的實體瀏覽器 (Inheriting cookies)，突破付費牆與驗證機制的限制。 * **Local-first & MCP 協議**：支援 Model Context Protocol (MCP)，可以將 Obsidian Vault 暴露為一個本地伺服器，讓編譯器或 IDE 內的 AI (如 Cursor) 也能直接調用知識庫內容。 ### 4. 批次處理排程 (The Playbooks & Cron Jobs) 系統將繁重的工作拆分佈署於深夜，以避免佔用使用者日常工作的計算資源。排程定義如下： * **11:00 PM - The Scout Run**： 讀取 `0-raw/reading-list.md`，使用 WebBridge 下載完整網頁內容，存入 `sources/` 並加上 YAML 前置元資料 (URL, Date, Word count)。 * **3:00 AM - The Refinery Run (Heavy Shift)**： 啟動 Agent Swarm 進行大數據量處理。為每一個 `0-raw/` 項目分配一個獨立 Agent，平行執行拆解、原子化、關聯與評論工作。 * **衝突處理 (Friction Handling)**：當新筆記與舊筆記矛盾時，寫入以下程式碼區塊： ```markdown ## [FRICTION] Raised by review > [[lithium-supply-bottleneck-thesis]] treats lithium cost as the primary ceiling. This note directly pressures that. Both cannot be fully right. Flagged for your judgment. ``` * **6:00 AM - The Editor Run**： 尋找過去 24 小時內建立/修改的原子筆記，更新 `3-threads/` 的綜合文件，並將結果寫入今日晨報。 * **Sunday 10:00 PM - The Audit Run (健康度掃描)**： 掃描全域：尋找孤兒節點 (Orphan atoms)、超過 14 天未審閱的暫定筆記、超過 7 天未解決的 `[FRICTION]` 區塊，以及沒有資料來源的違規筆記。這完全等同於軟體工程中的 Linter 或 CI 測試失敗報告。 ### 5. 防腐機制與版本控制 (Guardrails) 將寫入權限交給自動化 AI 代理存在極大風險，文章強調了三道護欄： 1. **Ask-before-acting (確認機制)**：在初期信任建立前，要求 Agent 修改檔案前必須彈窗確認。 2. **Git Version Control (版本控制)**：為整個 Obsidian Vault 建立 Git Repository。如果夜班 Agent 發生了破壞性修改或幻覺覆蓋，只需 `git reset --hard` 即可回滾整個知識庫。 3. **Human-in-the-loop (人類決策保留)**：AI 不主動覆蓋矛盾，而是標記矛盾。人類每週只需花 20 分鐘解決被標記的 `[FRICTION]`，這是系統唯一無法自動化的高價值決策工作。 ## 總結與結論 * **架構層面的典範轉移**：個人知識管理 (PKM) 系統應從「靜態儲存庫 (Storage)」升級為非同步處理的「資料管線 (Data Pipeline)」。按資料的處理成熟度 (Raw -> Atoms -> Threads) 來設計目錄，遠比主題分類更利於 AI 自動化。 * **不變性 (Immutability) 是防範幻覺的基石**：設計不可篡改的來源區 (`sources/`)，讓所有 AI 生成的關聯與總結都必須具備 Traceability (可追溯性)，這是解決 AI 知識庫隨時間發生「知識漂移與腐壞」的關鍵架構決策。 * **透過並行 Swarm 突破效能瓶頸**：利用 Local LLM 搭配 Agent Swarm 進行 Map-Reduce 模式的處理（平行拆解文件，最終合併報告），成功將耗時的勞力密集型知識整理壓縮在夜間執行，極大化了單機算力的利用率。 * **利用 MCP 打通工具孤島**：將 Markdown 知識庫透過 Model Context Protocol (MCP) 發布為本地微服務，使得知識不再被封閉於單一筆記軟體，而是成為所有本地 AI 開發工具（如 IDE）皆可調用的共用記憶體 (Shared Memory)。

--- tags: [Agent架構, AI工具, 工作流, Prompt工程] date: 2026-06-16 read: false source: "2026-06-16T093903+0800-How to Build a Claude Code Team Where Every Agent Knows Its Role (Exact Setup Inside).md" original_title: "How to Build a Claude Code Team Where Every Agent Knows Its Role (Exact Setup Inside)" --- # How to Build a Claude Code Team Where Every Agent Knows Its Role (Exact Setup Inside)  原始來源與檔名：2026-06-16T093903+0800-How to Build a Claude Code Team Where Every Agent Knows Its Role (Exact Setup Inside).md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 效率 = 專業化角色 (Writer + Reviewer + Tester) × 統一調度指揮 (Coach Brief) _將單一全能型 Agent 拆解為職責單一的多個 Agent，並透過教練給定明確規格，能大幅提升程式碼品質與執行效率。_ ### 一句话 > 不要讓一個 Claude 代理做所有事情，而是建立一個包含作者、審查員、測試員和教練的四人團隊，讓每個代理專注於單一職責。 ### 餐巾纸草图 ```text [Coach (指揮/寫 Brief)] | +-----------------+ | | [Writer (寫 Code)] [Tester (寫測試)] | | [Reviewer (找問題)] | | | +-----------------+ | [最終總結報告] ``` ## ROUND 1: SKELETON | 骨架掃描 **"这本书在说什么"** * **核心问题**: 開發者使用單一全能型 Claude Code 代理時，常導致職責模糊與程式碼品質不佳，該如何解決？ * **核心答案**: 建立一個具有四個專屬角色的多代理 (Multi-Agent) 團隊（Writer、Reviewer、Tester、Coach），讓每個代理只做一件事。 * **论证结构**: 案例對比型（以尼克隊奪冠比喻，並給出具體配置指南與常見錯誤）。 ### 章节骨架 1. **背景**: 單一代理 vs 多角色團隊 2. **Player 1**: Writer 專職寫扣不測試 3. **Player 2**: Reviewer 專職挑錯不修改 4. **Player 3**: Tester 依規格寫測試 5. **Player 4**: Coach 撰寫規格與平行調度 6. **常見錯誤**: 避免角色重疊與權限過大 7. **快速設定**: 十分鐘建置專屬團隊 ## ROUND 2: DISSECTION | 血肉解剖 **"凭什么这么说"** ### 论证链 ```text 單一 Agent 缺乏制衡且容易幻覺 --> 將職責拆分為專職寫作、審查與測試 --> 限制各 Agent 的可用工具 (如審查員不准修改) --> 透過教練角色撰寫統一規格 (Brief) 確保目標一致 --> 達到更高品質的程式碼產出 ``` ### 关键证据 1. **角色分離機制**: 寫作、審查與測試擁有完全不同的 prompt 與可用工具（例如 Reviewer 沒有 Write 工具），避免球員兼裁判。 2. **規格導向測試**: Tester 必須在 Writer 寫 code 時平行作業，強制要求 Tester 看 spec 寫測試，避免測試只是照抄錯誤的實作邏輯。 3. **教練協同調度**: Coach 使用 `Task` 與平行派發指令，確保所有人依據唯一的 Brief (劇本) 行事，不會各自偏離主題。 ### 隐形假设与边界 * **隐形假设**: * 使用者具備 Claude Code CLI 的基礎操作能力與配置目錄知識。 * 大型語言模型在處理單一、聚焦的任務時，表現遠優於處理多重、複雜的任務。 * 專案結構允許透過 `.claude/agents` 與 `.claude/commands` 進行自訂指令設定。 * **边界条件**: * 對於極度微小的修改（如改一個字），啟動四個代理的團隊可能會造成過高的延遲與 API 成本。 * 當任務的規格 (Brief) 本身就模糊不清或系統過於龐大時，Coach 可能無法有效指揮團隊。 ## ROUND 3: SOUL | 靈魂提取 **"还能怎么用"** * **作者盲点**: 未詳細討論各個 Agent 之間的對話回饋迴圈 (Feedback Loop) 該如何自動化，目前似乎仍需要依賴人類或 Coach 在收到報告後做最後決策與 Commit。 * **知识连接**: 與軟體工程中的「關注點分離 (Separation of Concerns)」以及「測試驅動開發 (TDD)」高度吻合，只是執行者從人類變成了 AI。也呼應了微服務架構中「單一職責原則 (Single Responsibility Principle)」。 * **行动触发**: 立即在自己的專案中建立 `.claude` 目錄，將過於肥大的 Prompt 拆解為多個單一職責的 Agent 進行實驗。 ### 跨域映射 * 在 **軟體工程**，这叫 **單一職責原則 (SRP) 與 關注點分離** * 在 **管理學**，這叫 **專業分工與流程隔離** --- # 如何建立一個角色分明的 Claude Code 團隊 (附完整設定) (Architectural Deep Dive) ## 前言/背景 多數開發者在使用 Claude Code CLI 時，往往將其視為一個「全能將軍」，在同一個 session 中混雜了寫作、測試與審查的指令。這篇文章提出了一個基於 Multi-Agent 架構的最佳實踐，透過在專案的 `.claude` 隱藏目錄下定義四種專屬角色（Writer, Reviewer, Tester, Coach），實踐「關注點分離」，從而大幅提升 AI 輔助開發的準確度與程式碼品質。 ## 章節詳細總結 ### 1. 核心角色 1：Writer (實作者) Writer 的唯一職責是**寫出能運作的程式碼**。作者透過 `.claude/agents/writer.md` 的 YAML 配置限制了它的行為： * **配置細節**：允許使用的工具包含 `Read, Write, Edit, Glob, Grep, Bash`，且指定使用 `sonnet` 模型。 * **架構決策 (Why)**：明確禁止 Writer 進行自我審查或寫測試 (`You do not write tests. You do not review your own work.`)。這是為了避免 AI 在生成程式碼時陷入「自我肯定」的幻覺（球員兼裁判）。它只需要閱讀規格、理解上下文、實作，並確保語法能通過編譯。 ```yaml --- name: writer description: Implements features. Invoke when code needs to be written. Returns working code, no review pass. tools: Read, Write, Edit, Glob, Grep, Bash model: sonnet --- You write code that ships. You do not review, you do not test. ... ``` ### 2. 核心角色 2：Reviewer (審查員) Reviewer 的職責是**尋找問題，而非修改代碼**。 * **配置細節**：其工具被嚴格限縮為 `Read, Grep, Glob, Bash`，**刻意移除了 `Write` 和 `Edit` 工具**。 * **架構決策 (Why)**：透過剝奪寫入權限，強迫模型專注於執行 `git diff` 並尋找邏輯漏洞、安全隱患或邊界條件。輸出被規範為分為 Critical, Important, Nitpick 三個等級，並附上精確的 `file:line` 參考。這確保了 Reviewer 不會擅自覆寫原本的邏輯，而是成為客觀的監督者。 ### 3. 核心角色 3：Tester (測試員) Tester 被設計來**測試規格 (Spec)，而非測試實作 (Implementation)**。 * **配置細節**：使用 `.claude/agents/tester.md` 定義，具備讀寫權限。其 Prompt 強調「Priorities: edge cases first, error paths second, happy path last」。 * **架構決策 (Why)**：作者指出一個常見的致命錯誤：「讓測試員先讀實作代碼」。如果 AI 先看代碼再寫測試，它會寫出完全映照代碼邏輯的測試（Mirror tests），導致即使邏輯全錯，測試依然會通過綠燈。因此，Tester 必須嚴格基於 Coach 給予的規格 (Brief) 來設計測試案例，這本質上實踐了黑箱測試的理念。 ### 4. 核心角色 4：Coach (教練/指揮官) Coach 是使用者真正呼叫的 Orchestrator，負責統籌整個流程。 * **配置細節**：設定在 `.claude/commands/ship.md`，使用能力最強的 `opus` 模型，並擁有 `Task` 工具來並發調度其他 Agent。 * **架構決策 (Why)**：Coach 的工作流程定義了完美的 Multi-Agent 協作模式： 1. 撰寫統一的段落規格 (Brief) 作為團隊唯一真理 (Playbook)。 2. **平行派發 (Parallel Dispatch)** Writer 與 Tester。這確保了 Tester 完全不知道 Writer 寫了什麼，純粹依據規格開發測試。 3. 待 Writer 完成後，派發 Reviewer 去看 diff。 4. 最終聚合三份報告（實作結果、測試結果、審查意見）給人類開發者決定是否 Commit。 此設計避免了單一對話上下文過度膨脹，並最大化了 Opus 與 Sonnet 模型的協同效應。 ```yaml --- description: Run the writer, tester, and reviewer as a team on one task argument-hint: <task> allowed-tools: Read, Grep, Glob, Bash, Task model: opus --- Ship this task: $ARGUMENTS 1. Write a one-paragraph brief: goal, files in scope... 2. Dispatch the writer and tester in parallel with the brief... ... ``` ### 5. 架構常見反模式 (Anti-Patterns) 作者總結了在建構 AI Agent 團隊時常見的架構失誤： * **自我審查**：讓生成代碼的模型自己 Review，失去檢查的意義。 * **測試與實作耦合**：讓寫測試的 Agent 依賴已經寫好的邏輯，而非需求規格。 * **權限過載**：給予每個 Agent 所有的工具（如給審查員寫入權限），導致職責越界。 * **缺乏共識基礎 (Brief)**：不寫規格直接開工，導致各個 Agent 對任務的理解產生分歧。 ## 總結與結論 * **單一職責與權限最小化**：在設計 AI Agent 時，應比照微服務架構的權限控管，透過移除不必要的工具（如移除 Reviewer 的 Write 工具）來強制 Agent 遵守其本分。 * **平行與隔離的測試策略**：真正的測試驅動或黑箱測試，必須確保 Tester 的輸入僅有規格 (Spec) 而無實作 (Implementation)，這在 Multi-Agent 架構中可透過平行的 Task Dispatch 完美實現。 * **引入 Orchestrator 模式**：人類開發者不應直接管理底層 Worker (Writer/Tester)，而應透過能力更強的模型 (如 Opus) 作為 Coach 進行中介，由 Coach 產出統一的規格劇本，以避免上下文漂移 (Context Drift)。 * **基礎設施代碼化 (IaC for Agents)**：將 Agent 的角色定義與 Prompt 存儲在專案的 `.claude/agents` 目錄中並提交至 Git，能確保整個開發團隊共享相同的 AI 協作基礎設施與質量標準。

--- tags: [Agent架構, AI工程, 工作流, Prompt工程] date: 2026-06-16 read: false source: "2026-06-16T093725+0800-How to Create Loops with Claude.md" original_title: "How to Create Loops with Claude" --- # 如何使用 Claude 建立迴圈 (How to Create Loops with Claude)  原始來源與檔名：2026-06-16T093725+0800-How to Create Loops with Claude.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > Prompt = 1 次回應；Loop (迴圈) = 觸發器 (Trigger) + 記憶 (Memory) + 驗證 (Verifier) + 終止條件 (Stop Condition) = 自主系統 _從單次對話轉向建立能夠在你關閉電腦後持續運作的自主代理系統。_ ### 一句话 > 停止撰寫單次的提示詞 (Prompts)，開始設計能讓 AI 代理持續運作、具有記憶與隔離機制的自動化迴圈 (Loops)。 ### 餐巾纸草图 ```text [Trigger] --> (Agent Reads STATE.md) | v [Worktree: Agent Executes] | v [Evaluator/Verifier Agent] / (Fail) \ (Pass/Stop Condition) v v (Update STATE.md) -----> [End/Human Review] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 在 AI 代理時代，我們應該如何與模型互動以發揮最大價值？ * **核心答案**: 開發者的核心工作已從「撰寫完美的提示詞」轉變為「設計由觸發器、記憶和多代理協作組成的自動化迴圈」。 * **論證結構**: 演繹與實踐指南型。 ### 章节骨架 1. **迴圈的本質**: 迴圈是遞迴目標，代理會遺忘，但迴圈有記憶。 2. **單一觸發器起步**: 用 Cron 或 Webhook 啟動第一個迴圈。 3. **賦予記憶檔案**: 使用 `STATE.md` 讓迴圈記住進度。 4. **拆分撰寫與檢查**: 評估者-最佳化者模式 (Evaluator-Optimizer)。 5. **工作樹隔離**: 使用 Git Worktrees 避免並行代理衝突。 6. **硬性終止條件**: 防止「Ralph Wiggum」假完成迴圈。 7. **人類審查節點**: 逐步提升自主層級。 8. **監控 Token 成本**: 避免無人值守的迴圈造成天價帳單。 9. **迴圈間的連接**: 讓迴圈共享狀態與技能，形成流水線。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text 完美的 Prompt 只能帶來單次結果 --> AI 模型具備一定的自主修正能力 --> 透過自動化觸發器、持久化記憶 (Markdown) 與客觀驗證條件建立迴圈 --> 系統可以在無人介入的情況下推進任務進度 ``` ### 关键证据 1. **Anthropic 工程實踐**: Claude Code 的負責人 Boris Cherny 不再親自寫 Prompt，而是撰寫會自動提示 Claude 並決定下一步的迴圈。 2. **Addy Osmani 的框架**: Google 工程師將迴圈拆解為自動化、工作樹、技能、連接器、子代理和記憶六大部分，證明其工程可行性。 3. **評估者-最佳化者模式 (Evaluator-Optimizer)**: 引用 Anthropic 的代理工程白皮書，證明讓 AI 自己評分會產生樂觀偏差，需要外部硬性檢查 (如 CI/Linter)。 ### 隐形假设与边界 * **隐形假设**: * 底層的 LLM (如 Claude 3.5 Sonnet) 具有足夠的推理與編寫程式碼能力，能夠在限定上下文中完成工作。 * 專案具有完善的自動化測試、編譯檢查與 Linter，可作為客觀的「硬性閘門 (Hard gate)」。 * **边界条件**: * 在缺乏客觀驗證標準（如缺乏單元測試）的專案中，迴圈的驗證機制會失效。 * Token 上下文窗口限制：如果記憶檔案 (`STATE.md`) 增長到數千行，代理將無法有效讀取與處理。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲点**: 如何處理多個迴圈之間的死結 (Deadlock) 以及 `STATE.md` 的版本衝突尚未深入探討。 * **知识连接**: 與微服務架構中的非同步事件驅動、狀態機 (State Machine) 以及 GitOps 理念高度一致。 * **行动触发**: 今天就挑選一個日常重複性任務（如總結 CI 失敗原因），寫一個定時執行的 Cron Job 呼叫 Claude CLI，並將結果輸出到 `PROGRESS.md`。 ### 跨域映射 * 在 **分散式系統**，这叫 **事件驅動架構 (Event-Driven Architecture) 與持久化狀態 (State Persistence)**。 * 在 **控制理論**，這叫 **閉環控制系統 (Closed-loop Control System)**。 --- # 如何使用 Claude 建立迴圈 (Architectural Deep Dive) ## 前言/背景 隨著大型語言模型 (LLM) 推理能力的提升，開發者的互動模式正在發生典範轉移：從單次的「提示詞工程 (Prompt Engineering)」轉向建構自主運作的「代理迴圈 (Agentic Loops)」。本文作者指出，與其花時間雕琢完美的單次 Prompt，不如建立包含自動化觸發、狀態記憶、隔離工作區與客觀驗證的迴圈系統。這能讓 AI 代理在開發者不介入的情況下，持續且安全地推進程式碼庫的演進。 ## 章節詳細總結 ### 迴圈的本質與架構 (What a Loop Actually Is) 迴圈本質上是一個**遞迴的目標執行系統**。單次的 AI 代理在執行間是沒有記憶的 (Stateless)，但「迴圈」本身保有狀態。根據 Google 工程師 Addy Osmani 的分類，一個完整的迴圈系統包含六個核心元件： * **自動化 (Automations)**：如 Cron Job 或 Webhook，決定何時觸發代理。 * **工作樹 (Worktrees)**：利用 Git Worktrees 提供隔離的開發環境。 * **技能 (Skills)**：提供給代理的標準作業程序 (SOP) 文件。 * **連接器 (Connectors)**：與外部系統交互的介面。 * **子代理 (Sub-agents)**：負責特定小任務的 AI 實例。 * **記憶 (Memory)**：持久化在硬碟上的狀態檔案。 ### 從單一觸發器與記憶檔案開始 (Start With One Trigger & Give the Loop a Memory File) 不要試圖第一天就建構六大元件的複雜系統。最簡單的起點是： 1. **設定觸發器**：例如設定一個 Cron Job，每天早上 8 點讀取昨日的 CI 失敗紀錄。 2. **掛載記憶檔案 (`STATE.md` 或 `PROGRESS.md`)**：這在架構上是 **State Hydration** 的關鍵。每次迴圈啟動時，代理首先讀取這個 Markdown 檔案；結束時，將「完成了什麼、卡在何處、下一步是什麼」寫回檔案。 * **架構決策理由 (Why)**：因為 LLM 呼叫是無狀態的 (Stateless)，沒有 `PROGRESS.md`，每次執行都是從零開始。 * **限制與最佳實踐**：檔案必須保持簡短。如果 `PROGRESS.md` 膨脹到 2000 行，不僅會大幅消耗 Token，更會干擾模型的注意力機制，導致比沒有記憶更糟的結果。 ### 分離產出與驗證角色 (Split the Writer From the Checker) 單一代理自己寫程式並審查自己的工作，會產生嚴重的「樂觀偏差」——它太容易給自己及格了。 * **評估者-最佳化者模式 (Evaluator-Optimizer Pattern)**：這是 Anthropic 推薦的架構。讓一個子代理負責生成程式碼，另一個子代理負責審查。 * **客觀閘門 (Hard Gate)**：審查代理不能只依賴「主觀意見」，它必須與客觀標準綁定。例如：測試套件 (Test Suite)、型別檢查器 (Type Checker)、建置指令 (Build Command) 或是 Linter。如果測試沒過，就強制退回修正，形成真正的閉環。 ### 使用工作樹隔離並行任務 (Isolate Parallel Work With Worktrees) 當多個代理並行運作時，它們不能在同一個資料夾中修改同一個檔案。 * **實踐方式**：使用指令 `git worktree add ../agent-1-branch` 為每一個代理建立獨立的工作目錄與分支。 * **工作流範例**： 1. 子代理 A 在目錄 A 探索並撰寫計畫。 2. 子代理 B 在目錄 B (有自己的 Worktree) 依照計畫實作。 3. 子代理 C 在目錄 C 針對獨立的工作樹執行測試與驗證。 這解決了多代理系統中的資源競爭 (Race Condition) 與檔案損壞問題。 ### 設定硬性終止條件與人類審查 (Stop Conditions & Human Review) * **Ralph Wiggum 迴圈陷阱**：如果代理提前發出完成訊號，迴圈就會安靜地以「半成品」狀態終止。 * **客觀終止條件**：「測試通過」、「CI 綠燈」才是終止條件，而非「代理聲稱已完成」。同時，必須在程式碼層面設置一個**最大迭代次數 (Max Iteration Count)**（例如 10 到 20 次）作為後備 (Backstop)。如果達到上限仍未完成，應暫停並標記給人類審查。 * **自主性階梯 (Autonomy Ladder)**： * Level 1: 僅提供建議。 * Level 2: 建立 Draft PR 交由人類套用。 * Level 3: 自動套用低風險變更，但合併前需人類批准。 * Level 4: 完全自動化與合併，僅保留稽核日誌 (Audit Logs)。 所有新的迴圈都應從 Level 1 或 2 開始，確保其輸出穩定後再逐步升級。 ### 監控成本與安全性防護 (Watch the Token Cost) 無人值守的代理可能在一夜之間因為無限迴圈耗盡數百萬 Token，導致巨額帳單。 * **成本估算**：在自動化前，手動執行 3-5 次，計算單次迭代 Token 消耗 $\times$ 最大迭代次數 $\times$ 觸發頻率，得出最糟情況的每日成本。 * **指令白名單 (Command Allowlist)**：如果代理能執行 Shell 指令，絕對不能給予無限制存取權。必須將權限限制在 `npm`, `git`, `ls`, `cat` 等特定指令內，否則成本問題會直接演變成嚴重的系統安全漏洞。 ## 總結與結論 * **從 Prompt 到 Pipeline 的思維轉變**：架構師的職責不再是最佳化單一請求，而是設計系統架構，讓代理間的狀態傳遞、驗證邏輯與錯誤處理能夠自動流轉。 * **狀態持久化是核心**：利用輕量級的 `STATE.md` 作為代理間的記憶載體，是低成本且高效率的 State Management 策略，這與事件溯源 (Event Sourcing) 中維護系統狀態的理念有異曲同工之妙。 * **隔離與客觀驗證缺一不可**：在多代理協同架構下，利用 Git Worktrees 提供 Sandbox 隔離環境，並以編譯或測試結果作為 Evaluator 的唯一判斷標準，是防止代理幻覺 (Hallucination) 破壞程式碼庫的最有效手段。 * **嚴格的邊界控制與成本管理**：強制設定最大迭代次數 (Max Iterations) 與 Shell 指令白名單，是確保 AI 自動化系統在生產環境安全落地的基礎防線。

--- tags: [Agent架構, 知識管理, AI應用] date: 2026-06-16 read: false source: "2026-06-16T094019+0800-How we built a Single Company Brain (and how you can too).md" original_title: "How we built a Single Company Brain (and how you can too)" --- # How we built a Single Company Brain (and how you can too)  原始來源與檔名：2026-06-16T094019+0800-How we built a Single Company Brain (and how you can too).md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 企業大腦 = 知識擷取 (Capture) × 精準檢索 (Retrieval) × 權限邊界 (Permissions) ^ 修正迴圈 (Feedback Loops) _企業知識的價值不在於儲存了多少，而在於能否在正確的場景下，給予特定 Agent 精確無誤且受信任的上下文，並透過修正不斷進化。_ ### 一句话 > 真正的「企業大腦」不是一個塞滿文件的巨大資料庫，而是一個擁有擷取、檢索、信任機制、權限控制與反饋修正的五層智能操作架構。 ### 餐巾纸草图 ```text [ Work / Execution ] ▲ [ Retrieval ] ◄── [ Permissions ] ▲ [ Source Truth ] ▲ [ CRM ] [ Calls ] [ SOPs ] [ Slack ] │ [ Feedback Loop ] ``` ## ROUND 1: SKELETON | 骨架掃描 **"这本书在说什么"** * **核心问题**: 為什麼大多數公司建立的「內部 AI 知識庫 (大腦)」在實際運作中效率低下，甚至成為瓶頸？ * **核心答案**: 因為它們只做到了「儲存 (Capture)」和「記憶」，卻缺乏精準的「檢索 (Retrieval)」、「來源信任 (Source Truth)」、「權限 (Permissions)」與「反饋迴圈 (Feedback)」。 * **论证结构**: 對比型與案例型（先指出錯誤的純記憶模式，再提出五層架構的解決方案，並輔以 Single Grain 的實戰數據）。 ### 章节骨架 1. **問題根源**: 純記憶導致上下文過載 2. **Layer 1 (Capture)**: 收集工作廢氣轉為素材 3. **Layer 2 (Retrieval)**: 只提供當下任務需要的上下文 4. **Layer 3 (Source Truth)**: 建立信任與資料優先級 5. **Layer 4 (Permissions)**: 根據任務劃定資料邊界 6. **Layer 5 (Feedback Loops)**: 將人類修正轉化為系統規則 ## ROUND 2: DISSECTION | 血肉解剖 **"凭什么这么说"** ### 论证链 ```text 人類成為 AI 任務的上下文路由節點效率極低 --> 單純增加 Context Window 會導致 Agent 抓取錯誤資訊 --> 必須建立介於原始數據與 Agent 之間的中介智能層 (五層架構) --> 系統才能自動在正確情境下提供正確、受控的資訊。 ``` ### 关键证据 1. **失敗經驗**: 在 Single Grain 早期，系統保留所有通話和筆記，導致持久化記憶佔用 40% 的 Context Window，Agent 開始抓錯資訊，變得「技術上更聰明，操作上更混亂」。 2. **成功數據**: 導入五層架構後，累積 500K+ token 持久記憶，90+ 日常 cron job。15 通銷售電話可自動提煉出 390 個洞察、470 個事實和 125 個框架。 3. **工作流加速**: 以每週報告為例，原本需要手動拉數據、解釋並耗時數小時，擁有正確 Context 的 Agent 可以在 60 秒內給出答案，大幅降低決策延遲。 ### 隐形假设与边界 * **隐形假设**: * 公司內部的通話、CRM 紀錄與 Slack 對話中，確實蘊含高價值的隱性知識（Work Exhaust）。 * 員工願意且能夠提供高品質的反饋 (Corrections) 來幫助系統學習。 * **边界条件**: * 如果公司的原始數據品質極差（例如 CRM 從不更新，通話無實質內容），該系統也是「Garbage In, Garbage Out」。 * 對於高度依賴直覺且無任何歷史模式可循的全新創意型任務，此大腦的幫助有限。 ## ROUND 3: SOUL | 靈魂提取 **"还能怎么用"** * **作者盲点**: 系統建置的技術門檻與維護成本。五層架構需要龐大的資料工程支援，對於小型團隊而言可能難以從零搭建。 * **知识连接**: 與軟體工程中的「微服務架構」與「API 閘道器」概念相似——不讓服務 (Agent) 擁有全部資料，而是透過 API (Retrieval Layer) 取得當下所需、具權限控管的資料。也與 RAG (Retrieval-Augmented Generation) 的進階設計模式高度相關。 * **行动触发**: 停止盲目地將公司文件倒進 Vector DB，先挑選一個最耗時的痛點工作流（如每週報告），回答六個架構問題（來源為何、誰是真理、需什麼上下文、拒絕什麼上下文、常見修正為何、如何變規則），再來進行自動化。 ### 跨域映射 * 在 **搜尋引擎工程**，这叫 **PageRank 與意圖識別 (Intent Recognition)** * 在 **資料庫安全**，這叫 **Row-Level Security 與 Role-Based Access Control (RBAC)** ## STRUCTURE MAP | 全书结构图 ```text [ Raw Material ] [ Core Architecture ] [ Business Impact ] Calls ──────┐ ┌───────────────────┐ Faster Execution CRM ──────┼────────► │ L1: Capture │ ▲ SOPs ──────┤ │ L2: Retrieval │ ──────────────┤ Slack ──────┘ │ L3: Source Truth │ │ │ L4: Permissions │ Decision Latency ▼ Human Corrections ───► │ L5: Feedback Loops│ │ └───────────────────┘ Compounding Value ``` --- # How we built a Single Company Brain (and how you can too) (Architectural Deep Dive) ## 前言/背景 本文探討了為什麼傳統的「公司知識庫（Company Brain）」在導入 AI Agent 時往往效果不彰。核心問題在於大多數團隊只做到了「儲存 (Capture)」，把所有的通話記錄、Slack 訊息和文件丟給 Agent 的 Context Window。這導致 Context 過載，Agent 抓取錯誤資訊，最終人類依然淪為整理上下文的路由節點。為了解決這個問題，Single Grain 團隊設計了一個「五層智能架構 (5-Layer System)」，用來橋接公司的歷史知識與 AI Agent 的實際執行，實現高效率、有邊界且具備自我修正能力的自動化工作流。 ## 章節詳細總結 ### 錯誤的架構：上下文過載與人類路由瓶頸 作者指出，最初他們嘗試給予 Agent 所有能獲得的記憶與上下文。但大約三週後，「記憶」本身成為了系統的瓶頸： * **Context Window 浪費**：持久化的記憶檔案吃掉了大約 40% 的 Context Window。 * **檢索混亂**：雖然 Agent 擁有更多資訊，但無法在「正確的時間」提取「正確的資訊」。 * **人類成為 Router**：整個流程變成「通話紀錄 -> 隨機筆記 -> 人類記憶 -> Agent 冷啟動 -> 人類重新解釋」，系統並未真正縮放，反而增加了維運的混亂度。 ### 正確的架構：以檢索為核心的五層系統 新的架構將「記憶」視為原物料，而將「檢索 (Retrieval)」視為真正的作業層 (Operating Layer)。架構由下到上分為五個核心層級： #### Layer 1: Capture (知識擷取) * **技術細節與邏輯**：這是系統的原物料層。擷取的來源包含：銷售通話 (Gong)、CRM 活動 (HubSpot)、內容決策、內部 SOP、Agent 輸出結果、每日日誌以及人類的修正回饋。 * **架構洞察**：單純將資料 Dump 進 Vector Database 並不是大腦，那只是儲存單元 (Storage Unit)。原始資料無法自己做決策、無法區分事實是否過期、無法處理敏感資訊的衝突。在實戰中，Single Grain 將 2,862 份通話逐字稿轉化為營運 Playbooks，甚至 15 通電話的日誌可自動萃取出 390 個洞察、470 個事實和 125 個框架。 #### Layer 2: Retrieval (精準檢索) * **技術細節與邏輯**：這是 AI 系統在生產環境中最常失敗的地方。Agent 不需要公司的完整歷史，只需要執行當前任務的 **6 個關鍵上下文**。 * **實戰範例**： * **撰寫 Outbound Email 的 Agent**：需要檢索 `ICP (理想客戶輪廓)`、`Offer (報價/方案)`、`Objections (常見反對意見)`、`Prior Campaign Performance (過往成效)`、`Brand Voice (品牌語氣)` 以及 `Current Goal (當前目標)`。 * **Pipeline 審查 Agent**：需要檢索 `Deal stage changes (階段變化)`、`Stalled accounts (停滯帳戶)`、`Recent call notes (近期通話筆記)` 以及 `CRM current state (CRM 當前狀態)`。 * **架構洞察**：在 Demo 中看似聰明的 AI，通常是因為 Context 是手動餵給的 (Hand-fed)。但在 Production 環境，必須建構強大的自動化檢索層 (Retrieval Layer)。 #### Layer 3: Source Truth (來源信任與衝突解決) * **技術細節與邏輯**：當資料量變大，必然會發生資訊衝突。例如：銷售通話、CRM 欄位、Slack 的修正與舊的 SOP，哪一個才是「真理」？ * **架構洞察**：如果沒有處理來源優先級，Agent 將成為「有著漂亮排版的自信說謊者」。架構上必須將來源進行層級劃分： * `Live Truth`：即時事實（例如 CRM 的最新金額）。 * `Historical Context`：歷史脈絡（如過去的通話）。 * `Inspiration`：靈感參考（不可當作事實陳述）。 * `Internal Pattern`：內部模式（可以分析，但絕對不可在公開內容中引用）。 #### Layer 4: Permissions (權限與資料邊界) * **技術細節與邏輯**：行銷 Agent 不需要 HR 私密資料；內容 Agent 不需要客戶財務數據。一個真實的企業大腦必須建立「工作流級別 (Workflow-level)」的權限邊界。 * **架構洞察**：在開始生成答案之前，系統的權限層必須攔截並限制任務所能存取的範圍。如果缺乏這層防護，要麼會發生機敏資料外洩，要麼只能把系統閹割到無法發揮作用。 #### Layer 5: Feedback Loops (反饋與修正迴圈) * **技術細節與邏輯**：這是讓系統產生複利效應 (Compound) 的關鍵。 * **修正規則對應**： * `人類修正 Agent 的僵硬語氣` -> 自動更新 `Voice Rule (語氣規則)`。 * `Agent 引用了不安全的案例` -> 自動更新 `Source Rule (來源使用規則)`。 * `Agent 漏抓了 CRM 的風險訊號` -> 自動更新 `Pipeline Scan (掃描邏輯)`。 * `工作被路由到了錯誤的地方` -> 自動更新 `Workflow Rule (工作流規則)`。 * **架構洞察**：沒有反饋迴圈，你只是在當軟體的「保姆」；有了反饋迴圈，每一次的人類修正都成為整個作業系統的訓練數據 (Training Rep)。 ## 總結與結論 * **檢索層 (Retrieval Layer) 決定成敗**：不要迷信巨大的 Context Window。AI 在生產環境的穩定性，取決於你能否精確地只餵給 Agent 完成單一任務所需的最小、最必要的 5-6 個上下文。 * **將事實來源 (Source Truth) 架構化**：必須在系統層面定義不同資料源的權重與角色（Live Truth vs. Inspiration）。在 RAG 架構中，這意味著 Metadata 標籤與權重演算法的設計，以避免 Agent 產生幻覺或引用過期 SOP。 * **工作流驅動的權限控制 (RBAC for Agents)**：不要打造一個全知全能、沒有邊界的超級 Agent。應該為不同的業務場景（行銷、業務、報告）配置專屬的資料邊界，實作 Workflow-level 的權限隔離。 * **以「反饋修正 (Feedback to Rules)」取代「重複提示」**：人類不應該重複糾正 AI 同樣的錯誤。系統必須具備機制，將使用者的修正 (Corrections) 解析並持久化為全局的防護欄規則 (Guardrails/Rules)，實現系統自我進化。

--- tags: [Agent架構, AI工程, 系統架構] date: 2026-06-16 read: false source: "2026-06-16T093731+0800-KV Cache：从推理优化到 Runtime 基础设施.md" original_title: "KV Cache：从推理优化到 Runtime 基础设施" --- # KV Cache：从推理优化到 Runtime 基础设施  原始來源與檔名：2026-06-16T093731+0800-KV Cache：从推理优化到 Runtime 基础设施.md --- ## NAPKIN | 餐巾纸 ### 餐巾紙公式 > Agent Runtime = State (Context) + Computed Cache (KV Cache) + Iterative Loop (while not done) *KV Cache 正在從單純的 LLM 推理性能優化技術，演變為 Agent 持續運行所需的 Runtime 計算結果快取基礎設施。* ### 一句话 > KV Cache 的本質是「計算結果快取」，它幫助持續運行的 Agent 避免重複思考已計算過的歷史內容。 ### 餐巾纸草图 ``` [Chat 時代] Prompt -> [Model] -> Answer (KV Cache = 推理加速器) [Agent 時代] +-------------------------+ | KV Cache | | (Computed Cache) | +-------------------------+ ^ | | v [Context] -> [ Agent Runtime ] -> Action | (思考/行動/觀察) | +-----------------+ ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 隨著 AI 從單次對話 (Chat) 走向持續運行的代理 (Agent)，系統該如何避免高昂的重複計算成本？ * **核心答案**: KV Cache 作為「計算結果快取 (Computed Cache)」，將從性能優化手段轉變為 Agent Runtime 的核心基礎設施，避免 AI 重複思考已計算過的內容。 * **論證結構**: 演繹與對比型 (對比 Chat 時代與 Agent 時代的需求差異) ### 章節骨架 1. **什麼是 KV Cache**: 快取已計算的 Attention 結果。 2. **出現原因**: 避免歷史內容重複計算。 3. **Chat 時代**: 僅是推理性能優化。 4. **Agent 時代**: 成為持續運行的必需品。 5. **重要性**: 知識與計算的本質差異。 6. **研究信號**: KV Cache 跨越會話與工作流。 7. **未來**: Agent Runtime 將依賴多種 Cache。 8. **結語**: AI 基礎設施的必然演化方向。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ``` Agent 需要長時間持續循環 (思考/行動/觀察) --> 每一輪若重新計算上下文將導致成本失控 --> 必須要有機制保存已完成的計算過程 --> KV Cache 恰好能勝任「計算結果快取」的角色 --> KV Cache 演化為 Agent Runtime 的基礎設施 ``` ### 關鍵證據 1. Chat 時代的線性呼叫 (`answer = model(prompt)`) 對比 Agent 時代的持續循環 (`while not done: think() act() observe() repair()`)。 2. 將 Context (AI 知道什麼) 與 KV Cache (AI 已經算過什麼) 進行明確的工程定義區分。 3. 學術界近期研究 (Persistent KV Cache, Workflow-aware KV Cache) 顯示 KV Cache 的資源化管理趨勢。 ### 隱形假設與邊界條件 * **隱形假設**: * Agent 在執行任務時，其上下文歷史 (Context) 的前半部多數時間是固定不變的。 * 持續將 Context 狀態保留在記憶體或磁碟中的儲存成本，遠低於重新計算 Transformer Attention 的算力成本。 * **邊界條件**: * 當 Agent 的狀態頻繁發生不可預測的覆寫時，快取可能失效。 * 上下文視窗長度超出硬體記憶體極限時，傳統 KV Cache 將面臨嚴重的驅逐 (Eviction) 與換頁問題。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 作者主要從宏觀架構討論，未深入探討 KV Cache 膨脹帶來的顯存 (VRAM) 瓶頸，以及如 PagedAttention、RadixAttention 等具體內存管理技術如何實際支撐此架構。 * **知識連接**: 與傳統軟體工程中的 Memoization（記憶化）、編譯器優化 (Incremental Compilation) 以及 CPU Cache 架構 (L1/L2/L3) 高度相似。 * **行動觸發**: 系統架構師在設計 Agent 框架時，應將「計算結果的復用性」作為一級架構考量，引入狀態保留機制而非單純調用無狀態 (Stateless) 的 LLM API。 ### 跨域映射 * 在 **前端開發**，這叫 **React Memo / UseMemo** (避免不必要的重新渲染計算)。 * 在 **後端架構**，這叫 **Redis 快取 / Memoization** (快取資料庫或高成本的運算結果)。 --- # KV Cache：从推理优化到 Runtime 基础设施 (Architectural Deep Dive) ## 前言/背景 隨著人工智慧的應用範式從單次問答 (Chat) 轉向長時間持續運作的代理程式 (Agent)，如何避免在迭代過程中重複計算龐大的上下文，成為了成本與效能的核心瓶頸。本文剖析了 KV Cache 的本質定位，指出它正從單純的「大模型推理效能優化手段」，演變為支撐 Agent 持續運行的「Runtime 基礎設施」。 ## 章節詳細總結 ### 一、什麼是 KV Cache 及其本質 從工程架構的角度來看，KV Cache 不是用來儲存知識、文件或記憶的資料庫，它的本質是 **Computed Cache (計算結果快取)**。 * 在 Transformer 的架構中，模型會計算每個 Token 之間的 Attention。KV Cache 負責將「已經計算過的 Attention 狀態 (Key 和 Value 張量)」緩存下來。 * **核心區別**：Context (如 RAG、Prompt) 解決的是「AI 知道什麼」(Data)；而 KV Cache 解決的是「AI 已經算過什麼」(Computed State)。 ### 二、Chat 時代的定位：效能優化 在單次對話的情境下，系統的呼叫模式非常線性： ```python answer = model(prompt) ``` 在這種無狀態 (Stateless) 請求或短生命週期的對話中，KV Cache 主要用於加速生成過程中的 Decoding 階段。其價值體現於： * 更快的首字回應時間 (TTFT) 與更高的吞吐量。 * 更低的推論服務成本。 即使沒有 KV Cache，系統依然能產出正確結果，只是延遲極高。因此，它在此階段僅是**推論優化技術**。 ### 三、Agent 時代的轉變：Runtime 的必需品 Agent 的運作模式徹底改變了生命週期，從單次呼叫變成了持續循環： ```python while not done: think() act() observe() repair() ``` * **成本失控問題**：Agent 的運行週期可能是數小時甚至數天。如果在每一次 `observe()` 獲取新資訊後，都需要把過去累積的所有對話與狀態「重新計算」一次 Attention，運算成本將呈現指數級增長。 * **架構定位轉移**：此時，KV Cache 成為了 Runtime 必須解決的經典狀態問題——**哪些東西已經算過了，不要重複思考**。它從效能優化工具，正式晉升為維持系統可持續運行的核心基礎設施。 ### 四、學術界與工程界的訊號 近期的研究趨勢證明了 KV Cache 正在被「資源化」與「持久化管理」： * **Persistent KV Cache**：將快取跨 Session 儲存，類似於休眠狀態的持久化。 * **Workflow-aware KV Cache**：根據 Agent 的決策樹或執行路徑來動態載入/卸載緩存，將工作流邏輯與底層記憶體管理結合。 * **KV Cache Memory**：直接將其作為工作記憶 (Working Memory) 進行讀寫操作。 這意味著架構師們不再只關注「如何計算」，而是將重點轉移至「如何管理並複用已有的運算狀態」。 ### 五、未來架構趨勢 所有長期運作的軟體系統（如作業系統、資料庫、瀏覽器）最終都會面臨「避免重複工作」的問題。Agent Runtime 的演化也將遵循此路徑。未來除了 KV Cache，我們預期會看到更多針對不同層級的快取機制： * **Tool Cache** (工具呼叫快取) * **Planning Cache** (路徑規劃快取) * **Inference Cache** (推演邏輯快取) ## 總結與結論 * **基礎設施範式轉移**：在設計 Agentic 系統時，應將大模型服務視為具備狀態 (Stateful) 的 Runtime 環境，而非單純的無狀態 (Stateless) API。 * **快取策略需升級**：系統架構師需要引入如 RadixAttention 或 PagedAttention 等高階記憶體管理機制，以樹狀結構或分頁方式管理 KV Cache，支援 Agent 的多分支推演與回溯。 * **計算與資料的分離設計**：在架構層面上，必須明確區分「知識層」(RAG、向量庫、Context) 與「運算狀態層」(KV Cache、Working Memory)，並針對兩者設計不同的持久化與驅逐 (Eviction) 策略。

--- tags: [Agent架構, Loop Engineering, AI Agents, ReAct, Reflexion] date: 2026-06-16 read: false source: "2026-06-16T093805+0800-My Thoughts on Loop Engineering.md" original_title: "My Thoughts on Loop Engineering" --- # My Thoughts on Loop Engineering  ## XRay 核心認知結構 **一、核心論點 (Core Thesis)** 所謂的「迴圈工程 (Loop Engineering)」雖然被包裝為 AI 代理發展的最新階段（取代了先前的提示工程與平行代理），但其真正的核心與瓶頸始終是「驗證 (Verification)」。設計代理系統的重點不在於生成器如何產出，而在於驗證器如何確保輸出的正確性並阻斷錯誤傳播。管理 AI 代理就如同管理人類，重點在於設計他們運行的約束條件。 **二、關鍵概念 (Key Concepts)** * **迴圈工程 (Loop Engineering)**: 一種自動化迭代機制，將人類傳統的「提示、閱讀、再次提示」循環替換為代理自我驅動的「探索、計畫、執行、驗證」循環。 * **開放與封閉迴圈 (Open vs. Closed Loops)**: * **開放迴圈**: 給予代理廣闊的探索空間與目標，但執行路徑不受限。容易產生新穎結果，但極度消耗 Token 且容易失控產出無用資訊 (Slop)，高度依賴結果檢查。 * **封閉迴圈**: 預先定義明確的目標、步驟與驗證節點。代理在既定框架內運行，路徑受限因而預算可控。目前能真正產出穩定結果的多為此類迴圈。 * **內部與外部迴圈 (Inner vs. Outer Loops)**: * **內部迴圈**: 針對單一任務的自我驗證。如：寫程式、寫測試、執行測試、捕捉邊緣情況並修正。 * **外部迴圈**: 跨會話 (Cross-session) 的持久化學習。代理記錄失敗經驗至持久化檔案（如 SKILL.md），使後續會話能讀取歷史教訓而避開相同錯誤。 **三、底層理論基礎 (Underlying Theoretical Patterns)** * **ReAct (Reasoning and Action)**: 交替進行思考與行動。在程式開發上體現為：理解目標、編寫程式、運行、讀取錯誤、推斷原因、修正並重試，直到測試通過。 * **Reflexion**: 具備記憶機制的 ReAct。當嘗試失敗時，代理會以自然語言記錄失敗原因並儲存，在下一次嘗試時讀取。這是現代「持久化記憶 (Persistent Memory)」系統的技術雛形。 ## 系統架構深度剖析 (Architectural Deep Dive) **一、系統設計理念 (Design Philosophy)** 迴圈架構的核心並非代理本身的自主性，而是評估閘門 (Evaluation Gate) 的設計。生成器從來不是系統的效能或品質瓶頸，如何建立一套嚴謹的驗證機制，防止「充滿自信的錯誤答案」在迭代中層層傳播，才是系統設計的本質。從架構抽象來看，一個有效的迴圈就是「一個生成器連接到一個驗證器」的拓樸結構。 **二、Anthropic 實踐案例分析：Bun 的 Rust 移植** 這個大規模工程案例利用 Claude Code 的動態工作流將 Bun 的 Zig 執行環境移植到 Rust（約 75 萬行程式碼）。其架構流程展現了極致的驗證設計： * **第一階段 (映射與初步生成)**: 透過數百個代理平行處理，精準映射每個結構體欄位的 Rust 生命週期，並將每一個檔案轉換為行為等價的 Rust 程式碼。 * **第二階段 (並行審查與對抗驗證)**: 每個檔案嚴格配置兩個審查代理，並引入了專門用於「反駁 (Refute)」其他代理產出的對抗層代理 (Adversarial Layer)。 * **第三階段 (修復迴圈)**: 驅動建置系統與測試套件，持續進行「編譯 - 測試 - 修復」循環，直到現有的測試套件達到 99.8% 的通過率。這證明了「驗證並不是流程最後的單一步驟，它就是整個系統的架構本身」。 **三、具體實作與機械元件 (Implementation Mechanics)** 在建構自動化迴圈系統時，開發者需要整合以下關鍵的底層機械元件 (Mechanical Parts)： * **任務發現觸發器 (Scheduled Trigger)**: 用於排程並觸發代理啟動工作，尋找待處理任務。 * **Git 工作樹隔離 (Isolated Worktrees)**: 確保高並發平行執行的代理不會互相覆蓋程式碼變更。 * **技能描述檔 (Skills Files)**: 預載專案的開發慣例，避免每次運行時系統消耗額外 Context 解釋基礎規範。 * **職責分離 (Separated Roles)**: 嚴格切分生成器與驗證器角色實例，因為如果讓同一個代理實例對自己產出的程式碼進行評分，往往會給出過於寬鬆的驗證結果。 * **持久化狀態 (Persistent Memory)**: 透過跨會話的實體檔案儲存（而非依賴易失的 Context Window），讓系統的外部迴圈能真正傳遞教訓。 **四、架構瓶頸與未來挑戰 (Bottlenecks & Limitations)** 目前的原生工具鏈（如 Claude Code 的 `/goal` 指令以及動態工作流編排）已經自動化了大部分的 Orchestration 管線化問題。然而，業界最常陷入的盲區在於：一個能順利通過現有測試的迴圈 (Goes Green)，並不等於一個在未定義行為上絕對正確的迴圈，它的品質上限完全受限於開發者設計的「驗證器品質」。因此，對於架構師而言，技術發展的重點已經轉移：你應該停止設計 Prompt，轉而設計嚴格的 Verifier，明確定義代理應當檢查什麼指標、以什麼為基準，以及如何建立提早捕捉失敗的防禦機制。

--- tags: [Agent架構, Prompt工程, AI工程] date: 2026-06-16 read: false source: "2026-06-16T093705+0800-The 170-Line SOUL.md That Made My Hermes Agent Dangerous.md" original_title: "The 170-Line SOUL.md That Made My Hermes Agent Dangerous" --- # The 170-Line SOUL.md That Made My Hermes Agent Dangerous  原始來源與檔名：2026-06-16T093705+0800-The 170-Line SOUL.md That Made My Hermes Agent Dangerous.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 智能體效能 = (身份定義 + 邊界) × 任務地圖 × 逆向當責 _賦予 AI 明確的身份、自主權邊界、專案全貌以及反向監督使用者的權力，能將其從被動工具昇華為高效的自主營運夥伴。_ ### 一句话 > 用一個包含身份、邊界、專案地圖與當責機制的 170 行 Markdown 系統提示詞，將只會點頭的 AI 變成能與你爭辯、推動進度的強大虛擬合夥人。 ### 餐巾纸草图 ```text [ User ] ^ | 當責 / | \ 任務指令 監督 / | \ / v v +-----------------------+ | SOUL.md | | 1. 身份: 自主營運者 | | 2. 邊界: 4大禁區 | | 3. 地圖: 專案優先級 | | 4. 語氣: 公私分離 | +-----------------------+ | v [ Agent Actions ] (推動工作, 提出異議) ``` ## ROUND 1: SKELETON | 骨架掃描 **"这本书在说什么"** * **核心问题**: 如何讓 AI 智能體超越被動的聊天機器人，成為真正有用、具備上下文認知且能推動工作的自主營運者？ * **核心答案**: 撰寫一個稱為 "SOUL.md" 的核心契約檔案，明確定義其身份、反駁規則、當責機制、語氣切換、任務地圖與自主邊界。 * **论证结构**: 案例型與對比型（對比傳統「有求必應」的 AI 與具備 SOUL.md 的 Hermes Agent）。 ### 章节骨架 1. **引言與 SOUL.md**: 一個改變一切的 170 行系統提示詞。 2. **打破無用恭維**: 要求 AI 具備批判性並主動提出證據與異議。 3. **雙向當責機制**: AI 必須監督人類是否實際執行了產出，避免「產出墳墓」。 4. **雙重人格設定**: 私下直率且不修飾，公開發表則保持專業。 5. **即時任務地圖**: 讓 AI 掌握當前所有專案的狀態與優先級，提供準確上下文。 6. **自主權邊界**: 除了發布、購買與破壞性行為外，賦予 AI 全面行動自由。 ## ROUND 2: DISSECTION | 血肉解剖 **"凭什么这么说"** ### 论证链 ```text AI 若缺乏具體角色與邊界 --> 淪為只會同意的被動工具，產生無用內容 (Output Graveyard) --> 提供明確的 SOUL.md (包含任務地圖、反駁規則與邊界) --> AI 能掌握上下文並提出高價值異議 --> 提升工作效率並確保產出被執行 ``` ### 关键证据 1. Hermes 能夠在使用者提出爛點子時，要求提供數據與邏輯，而不是直接順從地產出無用草案。 2. 透過「任務地圖」，Hermes 知道使用者忽略了哪些高優先級專案（如 AgentDocs），並主動提醒使用者聚焦，停止分散精力。 3. 明確的四項禁止行為（發文、發布、購買、不可逆破壞）讓 AI 可以在其餘領域（如分析、除錯）自由發揮，減少頻繁的許可確認。 ### 隐形假设与边界 * **隐形假设**: * 使用者具有足夠的自我反省能力與心理素質，能夠接受 AI 的「直白批評」與「反向要求」。 * AI 模型本身的推理能力已經達到能夠準確判斷「何時該反駁」以及「如何改進計畫」的水準。 * **边界条件**: * 當專案數量過於龐大或變化極快，導致 SOUL.md 中的「任務地圖」未及時更新時，AI 的建議會基於錯誤的優先級而失效。 * 如果基礎模型的 Context Window 限制或指令遵循能力不足，170 行的複雜規則可能在長對話中被遺忘。 ## ROUND 3: SOUL | 靈魂提取 **"还能怎么用"** * **作者盲点**: 依賴單一的 SOUL.md 檔案可能在未來隨著系統複雜度增加而變得臃腫，並未探討如何將這類系統提示詞進行模組化，或是結合動態載入的 RAG 架構。 * **知识连接**: 這與軟體工程中的「合約式設計 (Design by Contract)」、微服務架構的「守護進程 (Daemon)」，或是管理學中的「授權矩陣 (RACI)」概念極為相似。 * **行动触发**: 立刻為自己的 AI 助手（如 ChatGPT 的 Custom Instructions 或 Claude 的 Project Instructions）建立一個包含「任務地圖」、「自主權邊界」與「反駁規則」的營運契約。 ### 跨域映射 * 在 **企業管理**，這叫 **職務說明書與授權矩陣 (JD & Delegation Poker)** * 在 **系統架構**，這叫 **合約式設計與守護進程 (Design by Contract & Daemon)** ## STRUCTURE MAP | 全书结构图 ```text [ SOUL.md - The Agent Operating Contract ] | +-- 1. Identity (自主營運者，而非助理) | +-- 2. Dissent Rules (必須基於證據反駁，拒絕盲目同意) | +-- 3. Accountability (監督人類使用產出，防止產出墳墓) | +-- 4. Voice Modes (私下: 直白粗口 / 公開: 專業簡練) | +-- 5. Mission Map (動態專案清單與優先級) | +-- 6. Autonomy Line (除了發布/購買/破壞外，完全自主) ``` --- # The 170-Line SOUL.md That Made My Hermes Agent Dangerous (Architectural Deep Dive) ## 前言/背景 本文探討如何透過一個 170 行的 Markdown 檔案（稱為 `SOUL.md`），徹底重構大語言模型 (LLM) Agent 的行為模式與執行邊界。這份檔案跳脫了傳統「你是一個樂於助人的助手」的泛用系統提示詞 (System Prompt) 框架，轉而將 AI 塑造成一位具備主動性、批判能力且能反向要求使用者的「虛擬營運合夥人」。此架構完美解決了目前 AI 應用中常見的「過度迎合 (Sycophancy)」、「過度詢問授權」以及「產出無法落地 (Output Graveyard)」等系統工程難題。 ## 章節詳細總結 ### 核心設計理念：定義運作契約 (Operating Contract) 傳統的 System Prompt 將 AI 定位為飯店禮賓人員，導致 AI 提供的是「昂貴的贊同 (Expensive agreement)」。作者透過 `SOUL.md` 將 AI (Hermes) 重新定義為「自主營運者與思考夥伴 (Autonomous operator and thought partner)」。 * **架構意義**：這是將系統角色從被動回應器 (Passive Responder) 轉變為主動驅動程式 (Proactive Daemon) 的關鍵。透過在初始狀態注入這段宣告，直接鎖定了模型在後續執行迴圈中的順從傾向。 * **關鍵宣告**："You are Hermes, Tony's autonomous operator and thought partner. You don't wait for orders. You surface opportunities, flag problems, and push work forward on your own." (你不會等待命令，你會主動發掘機會、標記問題並推進工作)。 ### 強制性異議機制 (Required to Push Back) 為了提升決策品質並過濾無效請求，系統不允許 AI 盲目同意使用者的想法。 * **實作細節**：在提示詞中明確規定，反駁必須具備證據，如："Push back aggressively when it makes sense... Every objection comes with evidence: data, examples, reasoning, proof." * **運作原理**：藉由強加的約束條件（Constraints），強迫 LLM 在生成回覆的 Token 前，必須先執行隱式的「可行性分析」與「成本效益評估」。這等同於在系統的 Request Pipeline 中插入了一層業務邏輯驗證閘門 (Validation Gate)。 ### 雙向當責與防堵產出墳墓 (Accountability) 這是該設計中最具突破性的一環。傳統 AI 工作流通常在生成結果後便結束，導致計畫常被閒置遺忘。 * **機制設計**：AI 被賦予權力去追蹤使用者的執行狀況："If Tony isn't acting on what you surface, the feedback loop is broken... Tony should be held accountable to use what you produce." * **架構決策**：將單向的 Request-Response 模式，升級為具備狀態追蹤 (State Tracking) 的閉環回饋系統 (Closed-loop feedback system)。這賦予了系統監控外部依賴（使用者）執行狀態的職責。 ### 雙重語氣模式與 Context Switching 針對不同的輸出終端（Private Console vs. Public Channel），設定了截然不同的訊息格式化策略。 * **配置**： * **Private Mode**："Casual, authoritative, and unfiltered. Cuss like a motherfucking sailor — it's just us." (要求極低延遲、高資訊密度且無修飾)。 * **Public Mode**："No em dashes. Profanity: tasteful... Write like someone who builds things..." (要求專業、精煉、符合對外發布標準)。 * **架構價值**：這展現了強大的 Context Switching 能力，讓同一個核心模型能透過不同的「介面合約」適配內部除錯與外部發布，保證了內部溝通的高信噪比與外部輸出的穩定品質。 ### 動態任務地圖 (Mission Map) 取代了傳統每次請求都需要「注入背景」的做法，`SOUL.md` 內嵌了一個「動態狀態表」。 * **狀態清單**：檔案內明確列出正在進行的活躍專案（如 Kiln, AgentDocs）、當前北極星指標（Monetization），以及已經停滯或需被降級的項目。 * **運作原理**：這相當於 Agent 的 In-Memory Cache 或全局狀態表 (Global State Table)。當收到新指令時，系統會將其與當前的 Mission Map 進行比對（Pattern Matching），若發現資源衝突或偏離主線，就會拋出警告。 * **維護成本**：作為一個活文件 (Living document)，當專案狀態改變時，必須同步修改此配置檔，這正是 Infrastructure as Code (IaC) 的體現。 ### 極簡的自主權邊界 (Autonomy Boundary) 在系統工程中，權限控管策略 (RBAC/ABAC) 若過於複雜，將拖慢執行效能。作者採用了一種「黑名單 (Deny-list)」的極簡防禦架構。 * **權限配置**："Never without Tony's explicit approval: posting, publishing, purchasing, or making destructive changes that can't be reversed. Everything else... move." * **架構優勢**：除了 4 項高風險的外部副作用操作（發文、發布、購買、不可逆變更）需要阻斷等待人工授權 (Human-in-the-loop) 之外，其餘唯讀或內部操作皆授予最高執行權。這種 "Fail-safe" 設計大幅降低了系統的 I/O 阻塞，極大地提升了 Agent 的非同步並發執行能力與效率。 ## 總結與結論 * **配置即系統 (Configuration as System)**：將 System Prompt 視為 Agent 的作業系統核心配置檔。透過 `SOUL.md` 集中宣告狀態、權限與行為約束，比零散的對話式指令更具備軟體工程的嚴謹性與可維護性。 * **引入反向依賴與守護程序 (Daemon) 特性**：強大的系統不應只是被動執行，而應具備主動偵測不合理輸入的能力。賦予 Agent「強制異議」與「當責追蹤」的權力，能有效防堵上游（使用者）的錯誤決策與執行怠惰。 * **採用「預設允許，例外阻斷」的權限模型**：與其窮舉所有授權行為，不如採用「除少數高危險副作用需攔截外，其餘一律放行」的預設信任模型，以此換取自主系統最大的運作效能與流暢度。 * **輕量級狀態感知 (Stateful Context)**：在 Prompt 中靜態維護一份即時的「專案地圖」，以最低的運算成本為 LLM 提供了全局狀態表，使其具備了跨請求的長期優先級認知與上下文一致性。

--- tags: [Agent架構, AI工具, 工作流, 自動化] date: 2026-06-14 read: false source: "2026-06-16T093918+0800-The 7-day Hermes setup (full guide).md" original_title: "The 7-day Hermes setup (full guide)" --- # The 7-day Hermes setup (full guide)  原始來源與檔名：2026-06-16T093918+0800-The 7-day Hermes setup (full guide).md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 個人 AI 代理 = 基礎代理 + 身份邊界 + 高訊號記憶 + 日常介面 + 真實技能 + 安靜排程 _這代表一個有效的個人 AI 助理並非依賴繁雜的工具堆疊，而是建立在清晰邊界與循序漸進的層次之上。_ ### 一句话 > 不要試圖在一個週末建立混亂的 AI 系統，用七天的時間，循序漸進地建立擁有身份、記憶、技能與邊界的個人代理。 ### 餐巾纸草图 ```text [ Telegram ] | [ Hermes ] -- (Identity) | [ Memory ] -- (High-Signal only) | [ Skill ] -- (Procedural Memory) | [ Output ] -- (Short Receipt) *Cron: Sources -> Filter -> Alert ``` ## ROUND 1: SKELETON | 骨架掃描 **"這本書/文章在說什麼"** * **核心問題**: 為什麼多數人建立的 AI 助理系統最終會變得混亂且難以使用，而該如何正確建立？ * **核心答案**: 因為他們疊加工具的順序錯誤，正確的做法是花七天時間，從基礎層次逐步建立身份、記憶、介面、技能與排程。 * **論證結構**: 演繹與步驟指南型 ### 章节骨架 1. **Day 1 (基礎)**: 安裝並驗證基本功能。 2. **Day 2 (身份)**: 定義語氣與邊界。 3. **Day 3 (記憶)**: 只保留高訊號資訊。 4. **Day 4 (介面)**: 整合至日常通訊軟體。 5. **Day 5 (技能)**: 將真實任務轉化為技能。 6. **Day 6 (排程)**: 新增安靜不打擾的排程任務。 7. **Day 7 (設定檔)**: 僅在需要隔離時建立多個設定檔。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 论证链 ```text AI 系統混亂的根源在於過快堆疊工具 --> 穩固的基礎依賴於清晰的層次順序 (身份 > 記憶 > 技能) --> 在熟悉介面中運行且具備高訊號記憶的代理才有實用價值 --> 只有邊界明確的自動化才能實現長期複利效應。 ``` ### 关键证据 1. 在沒有設定身份邊界前加入工具，代理會過度猜測並執行危險操作。 2. 記憶若不加篩選，代理會將舊的任務進度和無關痛癢的錯誤不斷帶入新的對話中。 3. 不使用 Telegram 等日常對話介面，終端機代理很容易被遺忘。 ### 隐形假设与边界 * **隐形假设**: * 使用者每天會頻繁透過 Telegram (或類似工具) 與他人互動。 * 使用者有可重複的日常工作流程可被轉化為程式化記憶 (技能)。 * **边界条件**: * 當任務不具備重複性或僅需一次性操作時，建立技能的成本大於效益。 * 需要處理極度機密資料，且不適合透過 Telegram 進行通訊時，此架構可能不適用。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲点**: 本文未深入探討如何處理與管理多個工具 API 的認證安全，以及資料在本地端與雲端間的同步問題。 * **知识连接**: 本文的概念與軟體工程中的「防禦性編程 (Defensive Programming)」以及系統架構的「關注點分離 (Separation of Concerns)」不謀而合。 * **行动触发**: 刪除目前過度臃腫的 AI System Prompt，重新從定義「邊界」與「高訊號記憶」開始建構自己的代理。 ### 跨域映射 * 在 **軟體工程**，這叫 **關注點分離與漸進式交付**。 * 在 **管理學**，這叫 **標準作業程序 (SOP) 的建立與授權邊界**。 --- # The 7-day Hermes setup (full guide) (Architectural Deep Dive) ## 前言/背景 本文解決了多數人在建立個人 AI 代理 (AI Agent) 時常見的「架構混亂」問題。開發者往往在一個週末內塞入過多工具、API 與複雜的提示詞，導致系統脆弱且難以維護。作者提出了一套為期七天的漸進式架構建立法則，強調按照「身份 (Identity)、記憶 (Memory)、技能 (Skills)、工具 (Tools)、介面 (Telegram)、排程 (Crons) 與設定檔 (Profiles)」的順序疊加層次，從而打造出一個具有複利效應且低噪音的個人操作員 (Personal Operator)。 ## 章節詳細總結 ### Day 1: 基礎驗證 (Base Agent Verification) 架構的第一步並非自動化，而是確保底層基礎設施穩定運行。任何建立在不穩定基石上的「進階」功能都會大幅增加除錯難度。 * **安裝與驗證**：透過簡單的 Bash 腳本安裝 Hermes，並運行設定精靈。 * **關鍵指令**： ```bash curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash hermes setup hermes model hermes doctor hermes chat ``` * **架構意義**：證明 Hermes 能夠運行、呼叫工具、讀取環境狀態，並穩定回覆。這是後續所有層次的基石。 ### Day 2: 建立身份層 (The Identity Layer) 多數人跳過此階段直接接入工具，這是一個架構上的錯誤。身份層定義了代理的「操作邊界與執行策略」。 * **邊界設定**：需要明確定義語氣、風險邊界、直接程度、何時該拒絕請求，以及何時不該在未經批准的情況下執行操作。 * **範例配置**： ```text You are my practical AI operator. Be concise. Use tools when facts matter. Do not guess file contents, current dates, system state, or live facts. Ask before risky writes. Prefer small verified actions over big plans. If a workflow becomes repeatable, offer to save it as a skill. ``` * **架構意義**：強大的身份層能防止未來的系統混亂。如果代理在第二天表現得模糊或過度熱情，在加入記憶和排程後情況只會更糟。 ### Day 3: 高訊號記憶 (High-Signal Memory) 系統記憶設計中最常見的錯誤是「全部儲存」。當代理將舊有的專案狀態、過期偏好和一次性筆記帶入新任務時，會造成嚴重的上下文污染 (Context Pollution)。 * **應保留的持久化狀態 (Durable Facts)**：偏好的答案長度、常使用的工具、穩定的專案慣例。 * **應捨棄的暫態資料 (Transient Data)**：臨時任務進度、隨機連結、單日提醒。 * **架構意義**：記憶的重點不在於歸檔使用者的生活，而在於「減少重複的系統操縱 (Steering)」。 * **Good Memory**: "For calculations, use a tool instead of mental math." * **Bad Memory**: "We are currently debugging issue #217." ### Day 4: 使用者介面整合 (Interface Gateway) 強大的終端機代理如果沒有被開啟，就毫無用處。系統必須被整合到使用者每日的「溝通主線」中。 * **Telegram 閘道**： ```bash hermes gateway setup hermes gateway start ``` * **架構意義**：將系統從被動的「請求-回應」模型轉化為日常工作流程的一部分，使其能夠接收快速輸入並發送處理回條。 ### Day 5: 技能作為程序化記憶 (Skills as Procedural Memory) 技能不應憑空想像，而是將真實工作路徑轉化為可重複的程序化記憶。 * **技能定義**：告訴代理下一次如何執行特定任務。包含：何時觸發、檢查哪些檔案、執行哪些命令、常見錯誤處理，以及如何驗證成功。 * **具體範例**： ```text When I send a raw X link in the content topic, inspect the source, extract the structure, write a fresh Zaimiri-native draft, route it to Typefully as draft-only, and send a one-line receipt. ``` * **架構意義**：具備邊界、工作流和輸出定義的技能，讓 Hermes 從單純的聊天機器人 (Chatbot) 轉變為個人操作員。 ### Day 6: 安靜的排程任務 (Quiet Crons) 在代理擁有足夠的上下文和程序之前，不應加入排程。 * **低噪音原則 (Low-Noise Principle)**：如果沒有重要的訊號，系統應保持靜默。過於嘈雜的 AI 提醒最終會淪為背景噪音而被忽略。 * **具體範例**： ```text Every weekday at 8:30, check these sources for concrete Hermes Agent updates. Only message me if there is a real product change... If there is no signal, stay silent. ``` * **架構意義**：排程讓 Hermes 成為 24/7 的監控器。系統的價值在於「觀測正確的事物並減少中斷」，而非發送更多訊息。 ### Day 7: 設定檔隔離 (Profile Isolation) 避免為了酷炫而建立多個代理。只有當任務需要不同的權限、記憶或工具隔離時，才應進行設定檔拆分。 * **隔離維度**：記憶 (Memory)、身份 (Identity)、權限 (Permissions)、憑證 (Credentials)。 * **架構意義**：維持系統整潔。例如，研究代理不應具備與管理員代理相同的寫入權限；客戶代理不應存取內部專案的命名慣例。 ## 總結與結論 * **系統架構的層次依賴**：一個穩健的 AI 系統必須遵循嚴格的構建順序（身份 -> 記憶 -> 技能），過早引入複雜工具會導致系統崩潰。 * **無狀態與有狀態的切割**：區分「暫態對話」與「高訊號持久化記憶」，防止上下文污染，這是維持代理精準度的關鍵。 * **靜默預設 (Secure & Silent by Default)**：在設計自動化與排程 (Crons) 時，應遵循無訊號即靜默的原則，避免過度干擾使用者。 * **基於邊界的隔離 (Boundary-based Isolation)**：利用 Profiles 實作權限與上下文的隔離，落實最小權限原則 (Principle of Least Privilege)。

--- tags: [Agent架構, 工作流, 開發工具, AI工程] date: 2026-06-16 read: false source: "2026-06-16T093713+0800-The 9-Step Loop That Turns Claude Code Into a Senior Engineer.md" original_title: "The 9-Step Loop That Turns Claude Code Into a Senior Engineer" --- # The 9-Step Loop That Turns Claude Code Into a Senior Engineer  原始來源與檔名：2026-06-16T093713+0800-The 9-Step Loop That Turns Claude Code Into a Senior Engineer.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > AI 能力 = 基礎模型能力 × (結構化工作流 + 自動化驗證循環) _即使是強大的語言模型，沒有嚴謹的工作流也只能像初階工程師，加上完整的迴圈控制才能達到資深水平。_ ### 一句话 > 把 Claude Code 變成資深工程師的關鍵不是更強的模型，而是建立一個包含探索、計畫、標準、測試與審查的 9 步驟自動化迴圈。 ### 餐巾纸草图 ```text [探索/Explore] -> [計畫/Plan] -> [載入標準/CLAUDE.md] | [審核通過] <-------------------- [審查與修正/Review] ^ | | [建置/Build] -> [自動掛鉤/Hooks] -> [測試/Tests] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 如何讓 AI 寫程式碼的表現從「需要時刻監督的初階開發者」晉升為「可信賴的資深工程師」？ * **核心答案**: 透過 Claude Code 內建的原生功能（子代理、計畫模式、Hooks），建立一個不可跳過的 9 步驟紀律迴圈。 * **論證結構**: 演繹與實戰操作說明（分步解析）。 ### 章节骨架 1. **探索 (Explore)**: 先讀懂程式碼再動手 2. **計畫 (Plan)**: 決策先行，等待批准 3. **標準 (CLAUDE.md)**: 載入團隊開發公約 4. **小步建置 (Build)**: 拆解任務，小步交付 5. **掛鉤 (Hooks)**: 強制執行不可妥協的規則 6. **測試 (Tests)**: 用測試結果證明程式可用 7. **審查 (Review)**: 使用獨立子代理進行客觀代碼審查 8. **修正迴圈 (Fix)**: 修正、重測、重審直至無瑕疵 9. **一鍵發布 (Ship)**: 將工作流封裝成單一命令 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text AI 單次生成容易出錯且缺乏上下文 --> 必須建立結構化約束 --> 結合專屬工具特性 (Plan, Subagents, Hooks) --> 形成具備驗證機制的閉環工作流 --> 產生資深工程師等級的穩定輸出 ``` ### 關鍵證據 1. **Explore 子代理**: 能在隔離上下文中唯讀掃描程式碼，解決 AI 盲目修改的問題。 2. **Deterministic Hooks**: `PostToolUse` 等鉤子能 100% 強制執行 Linter 或測試，防止 AI 遺忘。 3. **Review 子代理**: 使用無歷史包袱的新對話視窗來審查程式碼，能抓出連「撰寫者」都忽略的安全漏洞或邊界條件。 ### 隱形假設與邊界 * **隐形假设**: * 專案已經具備良好的測試框架與 Linter 工具鏈。 * 開發者有能力辨識 AI 提出的「計畫」是否合理，並給予正確的核准。 * **边界条件**: * 專案極度依賴尚未成文的潛規則，無法寫入 `CLAUDE.md` 時會降低工作流效果。 * 當變更過於龐大或牽涉複雜系統架構時，單一命令可能無法順利跑完全程。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲点**: 此工作流高度依賴本地端的 CLI 操作，忽略了與遠端 CI/CD 管道深度整合的可能性，以及如何處理跨依賴專案的重構。 * **知识连接**: 軟體工程中的「TDD (測試驅動開發)」與「持續整合/持續部署 (CI/CD)」概念，被作者無縫移植到了 AI Agent 的生命週期中。 * **行动触发**: 放棄在聊天視窗中以「對話」方式指使 AI 寫程式，改為在專案內配置 `.claude/settings.json` 與 `CLAUDE.md`，建立自動化開發管道。 ### 跨域映射 * 在 **軟體工程**，這叫 **Pipeline / CI 流程 (持續整合)** * 在 **Agent 架構**，這叫 **多代理協作與反思循環 (Multi-Agent Reflection Loop)** ## STRUCTURE MAP | 全书结构图 ```text +-------------------------------------------------------+ | The 9-Step Agentic Loop | +-------------------------------------------------------+ | 1. Explore (Read-only context mapping) | | | | | 2. Plan (Step-by-step strategy + Human Approval) | | | | | 3. CLAUDE.md (Advisory standards & rules) | | | | | 4. Build (Small, isolated changes) | | | | | 5. Hooks (Deterministic enforcement: lint/test) | | | | | 6. Prove (Automated testing validation) | | | | | 7. Review (Skeptical subagent critique) | | | | | 8. Fix Loop (Address -> Re-test -> Re-review) | | | | | 9. Ship (Slash command encapsulation: /ship) | +-------------------------------------------------------+ ``` --- # The 9-Step Loop That Turns Claude Code Into a Senior Engineer (Architectural Deep Dive) ## 前言/背景 多數開發者將 Claude Code 等 AI 編碼工具視為「需要時刻監督的初階開發者」，採用「下達指令 -> 觀察修改 -> 肉眼檢查」的原始模式。這篇文章的核心問題在於：如何透過工具原生的結構化基元（Primitives），將這種不可控的單向生成過程，轉變為具備高度紀律、自動驗證與審查閉環的「資深工程師工作流」。作者提出了一個可重複的 9 步驟自動化迴圈，藉由子代理、鉤子 (Hooks)、計畫模式與 Slash 命令，徹底升級 AI 輔助開發的架構層級。 ## 章節詳細總結 ### 1. 探索前置 (Explore Before Touching Anything) 資深工程師動手前會先理解整體架構。在 AI 的應用上，應避免盲目編輯，而是利用 Claude Code 內建的 **Explore 子代理 (Explore Subagent)**。 * 此子代理在獨立的上下文視窗中以「唯讀模式」運行，不會污染主對話或造成意外修改。 * **指令範例**： ```python "Explore how authentication works across this codebase. Map the files involved, the data flow, and anything that looks fragile. Don't change anything yet." ``` * 這種設計確保了 Agent 在撰寫任何程式碼前，已具備全域的領域知識 (Domain Knowledge)。 ### 2. 進入計畫模式 (Make a Plan in Plan Mode) 決策先行是高階架構設計的基礎。透過「計畫模式 (Plan Mode)」，AI 必須先產出詳細的實作步驟、預期修改的檔案清單以及潛在風險，然後暫停執行。 * **架構意義**：這提供了一個**人機協作的中斷點 (Human-in-the-loop breakpoint)**，讓開發者能夠在早期階段糾正架構走向，避免浪費算力與時間產出無效程式碼。 * **指令範例**： ```python "In plan mode: lay out exactly how you'd add rate limiting to the API. List the files you'll touch, the order, and the risks. Wait for my approval before writing code." ``` ### 3. 將標準寫入 CLAUDE.md (Put Your Standards in CLAUDE.md) 如同開發團隊的 Coding Conventions，AI 需要一份每次連線都會讀取的「專案憲法」。 * 將技術約定（如 TypeScript strict mode）、常用命令（lint/build）及設計規則寫入專案根目錄的 `CLAUDE.md`。 * **關鍵設定範例**： ```markdown ## Conventions - TypeScript strict mode, no `any` - Functions over classes where possible - Every new function gets a test ``` * **架構考量 (Why)**：這些是指導性原則 (Advisory)，提供 AI 預設行為。然而模型偶爾會偏離，若有絕對不能打破的規則，必須依靠後續的 Hooks 處理。 ### 4. 拆解為可審核的小區塊建置 (Build the Change in Small, Reviewable Pieces) 在取得計畫批准與標準載入後，系統進入主迴圈 (Main Session)。此時應要求 AI 以「小型且自洽的區塊」實作計畫。 * 較小的 Diff 範圍不僅便於人類進行 Code Review，在發生錯誤時也更容易 Rollback，這是控制系統複雜度與錯誤爆炸半徑的標準工程實踐。 ### 5. 以 Hooks 強制執行不可妥協的規則 (Enforce the Non-Negotiables With Hooks) 這是區分初階與資深設定的**分水嶺**。相較於 `CLAUDE.md` 的「建議」性質，掛鉤 (Hooks) 在 Claude Code 生命週期中是**100% 決定性 (Deterministic) 執行的**。 * 透過 `.claude/settings.json` 定義 `PostToolUse` 掛鉤，能在每一次程式碼編輯或寫入後，強制觸發本地的 Linter 與測試腳本。 * **配置範例**： ```json { "hooks": { "PostToolUse": [{ "matcher": "Edit|Write", "command": "npm run lint && npm run test" }] } } ``` * **架構價值**：透過自動化腳本強制收斂 AI 的產出品質，將「不要忘記跑測試」這種口頭命令，轉化為實體系統約束。 ### 6. 用測試證明結果 (Make It Prove the Change Works) 資深開發者不相信「看起來沒問題 (Looks good to me)」，只相信測試結果。 * 要求 AI 針對每次變更撰寫單元測試（包含 Edge cases，例如 Token 過期）。結合前述的 Hooks，測試將成為驗收標準，確保功能正確性不再依賴人類的肉眼審查。 ### 7. 使用次級代理進行代碼審查 (Have a Second Agent Review the First) 這是引入了**多代理反思機制 (Multi-Agent Reflection)** 的核心技巧。 * 啟動一個全新的 **Review 子代理 (Review Subagent)**。因為它具有乾淨的上下文 (Clean context window)，沒有主體代理在建置過程中的「合理化偏見」，能夠以懷疑者的視角審查變更。 * **指令範例**： ```python "Launch a review subagent. Its job: review the diff I just made as a skeptical senior engineer. Check for security issues, missed edge cases, and anything that violates CLAUDE.md. Report problems, do not fix them yet." ``` ### 8. 修正與重驗證迴圈 (Fix What the Review Found, Then Re-Check) 這一步讓直線流程正式閉環。針對 Review 找出的問題，要求建置代理進行修正。 * 修正後必須**重新執行測試**，並再次啟動 Review 子代理。這個迴圈持續直到審核結果為「乾淨 (Clean)」，完美模擬了資深工程師處理 PR (Pull Request) 的反覆迭代過程。 ### 9. 將迴圈封裝為 Slash 命令 (Ship It With a Slash Command) 架構師最終的目標是將複雜的工作流抽象化。將上述的 9 個步驟整合成一個自訂的 Slash 命令 `/ship`。 * 透過建立 `.claude/commands/ship.md`，開發者只需下達單一命令，即可觸發完整的「探索 -> 計畫 -> 建置 -> 測試 -> 審查 -> 修正 -> 提交」Pipeline。 * **配置範例**： ```markdown # /ship : run the full senior-engineer loop 1. Explore the relevant code (Explore subagent) 2. Plan the approach and wait for my approval 3. Build per CLAUDE.md, in small pieces 4. Write + run tests (hooks enforce this) 5. Launch a review subagent on the diff 6. Fix issues, re-test, re-review until clean 7. Commit with a clear message and open a PR ``` ## 總結與結論 * **多重上下文隔離以消弭偏見 (Context Isolation for Objective Critique)**：透過啟動獨立的 Review 子代理，利用乾淨的 Context Window 打破 AI 在生成程式碼時的自我合理化循環，這是提升產出品質的關鍵架構模式。 * **決定性約束補足機率性缺陷 (Deterministic Constraints over Probabilistic Fallacies)**：由於大語言模型本質上具備機率性，不能依賴 Prompt (`CLAUDE.md`) 來確保關鍵品質。必須藉由 Shell Hooks 等外掛系統，強制在寫入後執行 Linter/Testing，建立不可逾越的系統邊界。 * **自動化 Pipeline 抽象 (Pipeline Abstraction)**：將繁瑣的 Multi-Agent 協作、反思及驗證步驟，透過 Slash Command (`/ship`) 封裝成單一介面，降低認知負擔，實現了 AI 工具從「交談式機器人」到「工程自動化管線」的架構升級。 * **決策與執行分離 (Separation of Planning and Execution)**：善用 Plan 模式作為中斷點，將「架構決策 (What to do)」與「程式編寫 (How to do)」分離，保證人類監督投入在最高價值的階段。

--- tags: [Agent架構, EventSourcing, 狀態管理, 系統架構] date: 2026-06-16 read: false source: "2026-06-16T093852+0800-The Log Is the Agent.md" original_title: "The Log Is the Agent" --- # The Log Is the Agent  ## 1. 核心概念 XRay - **核心論點**：如同遊戲角色的本體是「存檔」而非遊戲引擎，AI Agent 的本質不是模型、執行環境或控制迴圈，而是其「日誌 (Log)」——即由事件歷史（使用者輸入、模型輸出、工具呼叫與結果）構成的僅附加 (append-only) 狀態紀錄。 - **核心機制**：當日誌被視為 Agent 的唯一真相來源時，系統就成為一個狀態機的投影。執行器（Executor）會獲取日誌、重建狀態、呼叫模型進行決策，並將新動作寫回日誌，這種冪等 (idempotent) 設計帶來了極高的容錯與非同步擴展能力。 - **核心影響**：將日誌作為一等公民，使系統原生具備高可靠性（執行緒崩潰但狀態不滅）、可擴展性（無狀態工作節點可隨時接手）、分支能力（平行探索不同策略）、無痛遷移，以及最關鍵的：資料與控制權的完全擁有（避免深度的 Log Lock-in 供應商鎖定）。 ## 2. 架構深潛 Architectural Deep Dive ### 狀態持久化與控制迴圈 (Control Loop) 在「日誌即 Agent」的架構中，系統圍繞著持久化日誌運作。一個高階的控制迴圈被簡化為：取得租約 (lease) -> 從日誌重建狀態 -> 執行模型推論 -> 附加結果至日誌 -> 觸發或等待工具執行 -> 結束回合。 這種設計徹底解耦了運算（Model/Executor）與狀態（Log）。如果工作節點崩潰，新的節點能立即從日誌中接手，精準還原包括「等待使用者授權」在內的各種中斷點。這使得擴展變得極為容易：無需處理狀態遷移或複雜的協調開銷，只需增加工作節點，每個節點都在無狀態的環境下透過日誌還原上下文。 ### 壓縮策略的定位 (Compaction as a Materialized View) 受限於模型上下文視窗（Context Window），系統必然需要歷史壓縮。但在這套架構中，壓縮（Compaction）並不意味著覆寫或取代原始日誌，而是被視為針對原始日誌的「有損分支 (Lossy Fork)」或「實體化視圖 (Materialized View)」。 這進一步強化了日誌的價值：保留完整的原始紀錄，未來就可以隨時產生新的視圖投影；如果拋棄原始日誌只留壓縮檔，就等同遺失了 Agent 的部分人格或歷程。因此，壓縮處理應該是一項盡力而為（best-effort）的投影操作，新回合則在壓縮結果之上延續新的日誌分支。 ### 事件驅動與外部副作用管理 對於會改變外部世界狀態的工具（如發送 Email、修改 GitHub Issue），日誌的作用是紀錄 Agent 對世界的「觀察與行動歷史」，而不是要具備還原外部世界的能力。 這使得非同步工具的執行變得優雅：當 Agent 啟動耗時長達數小時的工具時，工作節點無須將狀態鎖在記憶體內乾等。它只需在日誌中標記「工具呼叫已啟動」即可釋放資源。當外部工具執行完畢，結果被附加回日誌，便會喚醒下一個可用的工作節點重建狀態並繼續執行。這確保了系統能夠在真實世界各種失效場景（節點重啟、沙盒消失、網路斷線）中穩健存活。 ### 日誌鎖定與供應商控制 (Log Lock-in) 文章在架構層面提出了長遠的警告：最強的供應商鎖定（Vendor Lock-in）不再是模型或 API，而是「日誌鎖定」。如果基礎設施供應商（如雲端 Managed Agents）擁有了 Agent 唯一的持久化紀錄，他們實質上就擁有了該 Agent。對於架構師而言，在設計或選擇 Agent 基礎設施時，必須確保日誌的獨立所有權，使其具備可重放 (replayable)、可分支 (forkable) 與可匯出 (exportable) 的特性，這將是決定企業 AI 資產核心掌控權的關鍵防線。

--- tags: [Agent架構, 開發工具, 系統工程, 工作流] date: 2026-06-16 read: false source: "2026-06-16T093823+0800-The context layer.md" original_title: "The context layer" --- # The context layer  原始來源與檔名：2026-06-16T093823+0800-The context layer.md --- ## NAPKIN | 餐巾纸 ### 餐巾紙公式 > Context Layer = 能力 (Skills/MCP) + 規範 (Rules/Plans) + 記錄 (Sessions) → Shared Infrastructure _獨立於個別 Agent 的中介基礎設施，統一管理工具能力、團隊協作規範與歷史上下文。_ ### 一句話 > 解決多 Agent 協作摩擦的關鍵，是將上下文從各個工具中抽離，獨立成一層可共享、可追溯的基礎設施。 ### 餐巾纸草图 ```text [Agent A: Claude] [Agent B: Cursor] \ / \ / +---------------------------------------+ | CONTEXT LAYER | | | | - 能力 (Push/Pull): MCP, Skills | | - 規範 (Push): Rules, AGENTS.md | | - 記錄 (Pull): Session Logs, Blame | +---------------------------------------+ | v [ Codebase / Project ] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 開發者與團隊在多個 Agent 工具間切換時，面臨配置散落、上下文無法共享與對話歷史難以追蹤的管理困境，該如何解決？ * **核心答案**: 建立獨立於個別 Agent 之外的「上下文層 (Context Layer)」，將 session、plan、rules、skill 和 MCP 配置集中管理。 * **論證結構**: 痛點分析 -> 提出解法 (Context Layer) -> 拆解運作機制 -> 具體進階場景 (Session Blame) ### 章節骨架 1. **痛點盤點**: 多 Agent 造成的管理摩擦 2. **概念提出**: Context Layer 的定義與邊界 3. **三層架構**: 能力、規範與記錄的消費模式 4. **進階場景**: Session Blame 的實踐 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 隱形假設與邊界 * **隱形假設**: * 未來的開發工作流將無可避免地跨越多個異質 AI Agent。 * Agent 依賴的上下文設定 (Skills, MCP) 會快速膨脹，無法靠單一配置檔或專案級別設定維護。 * 對話歷史 (Sessions) 包含有價值的決策邏輯，必須被視為專案資產。 * **邊界條件**: * 當依賴封閉生態系的 Agent 工具時，難以將上下文外掛至獨立的 Context Layer。 * 當單一專案規模極小且僅使用單一 Agent 時，引入 Context Layer 會增加不必要的複雜度。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 跨 Session 共享資料時的安全與權限隔離，以及大量歷史對話存入 Context Layer 後，如何透過高效檢索 (如 RAG) 在不爆表 Token 的情況下精準提取。 * **知識連接**: 此概念類似於雲端原生架構中的「中介軟體 (Middleware)」，或是服務網格 (Service Mesh) 中的控制面 (Control Plane) —— 將底層基礎設施從應用邏輯中解耦。 * **行動觸發**: 開始將專案中散落的 Prompt 與 MCP 設定收斂，並實驗性地在 Git Commit Message 中加入 Session ID 錨點，以便未來追溯 AI 生成的代碼決策。 ### 跨域映射 * 在 **分散式系統**，這叫 **中介軟體 (Middleware) / 配置中心** * 在 **知識管理 (PKM)**，這叫 **團隊共用大腦 (Shared Second Brain)** --- # The context layer (Architectural Deep Dive) ## 前言/背景 隨著開發者與團隊開始同時使用多種 AI Agent 工具（如 Claude Code、Cursor 等），面臨到配置檔（Skills, MCP）散落各處、上下文無法在 Agent 之間共享，以及過去的對話紀錄（Sessions）難以追蹤的痛點。為了解決這些摩擦，文章提出將上下文管理從單一工具中抽離出來，建立一層獨立的「上下文層 (Context Layer)」。 ## 章節詳細總結 ### 痛點：多 Agent 的摩擦與協作失控 目前在開發流程中使用 Agent，存在幾個關鍵的架構性問題： * **Session 不透明**：CLI Agent 的執行會話 (Session) 對使用者不透明，難以管理。 * **上下文孤島**：單個 Agent 無法有效利用過往歷史的上下文，多個 Agent 之間也缺乏共享機制。 * **配置散落**：Skill 與 MCP (Model Context Protocol) 檔案混亂，分散在全域與各專案中。 * **協作災難**：在團隊中，缺乏統一的管理機制來維護通用 Skill (如 PPTX 解析、Design-to-Code)，以及決定哪些規則是團隊共識。 ### 核心解法：獨立的 Context Layer 作者提出，Session、Plan、Rules、Skills、MCP 應該作為一個整體被管理。 * **避免供應商鎖定 (Vendor Lock-in)**：將這些配置從特定 Agent 中抽離，可以讓所有 Agent 基於同一層基礎設施工作。 * **與代碼庫保持距離**：這些上下文屬於工具配置與決策過程，不應完全耦合於專案的原始碼中。 * **架構鏈路**：整體工作流的邊界被重新定義為：`harness -> context layer -> project/codebase`。 * **Context Layer**：跨 Session 持久存在的基礎設施。 * **Harness**：單次 Session 內的臨時編排與執行容器。 ### 理想的 Context Layer 系統設計 一個完整的上下文管理平台應具備以下機制： * **統一入口與權限**：整合所有的能力與歷史，並支援團隊間的權限管控。 * **持續提煉 (Continuous Extraction)**：具備自動化工作流，定時從歷史 Session 中提取可重複使用的 Pattern，經過管理者審查後轉化為全局 Skill。 * **版本控制**：Context 本身也應當基於 Git 等工具進行版本控管。 ### 上下文資料的三層分類與消費模式 (Token 優化策略) 為了在提供豐富上下文與控制 Token 成本之間取得平衡，Context Layer 的資料被分為三類： 1. **能力 (Skills, MCP)** * **運作機制**：MCP Tools 在 Session 開始時 push 進上下文，Skill 元數據 (Metadata) 以 push 方式注入，正文則在需要時 pull。 * **架構理由**：體積小且經常相關，適合預加載。 2. **規範 (Rules, CLAUDE.md, AGENTS.md)** * **運作機制**：在 Session 開始時全數 push 進上下文。 * **架構理由**：作為全域約束，指導 Agent「該怎麼做」。 3. **記錄 (Sessions, Plans)** * **運作機制**：透過專用工具 (如 search, blame) 進行按需 pull。 * **架構理由**：資料量海量但僅偶爾相關，必須作為資料庫儲存，僅在檢索命中時才提取片段。 ### 關鍵應用：Session Blame 與 Git Commit 錨點 探討程式碼的修改歷程時，傳統的 `git blame` 只能追蹤到 Commit，但因為開發者可能編輯了 Agent 生成的代碼再提交，Commit 與 Session 之間缺乏直接的映射。 為了解決這個問題： * **Commit Trailer 機制**：必須在 Git 的 commit message 末尾顯式釘上一個「Session 錨點」。 * **實踐方式**：Agent 提交時，自動附加上 `Session-id: <uuid>` 的鍵值對（類似於 `Co-authored-by:`）。 * **架構價值**：只要有這個錨點，未來的開發者就能透過 Context Layer 穩定地「回鏈」到當時完整的對話過程，理解修改背後的「Why」。沒有獨立的 Context Layer，這類跨專案、持久化的 Session Blame 功能將無法實現。 ## 總結與結論 * **架構解耦勢在必行**：將 Agent 的配置與上下文管理從開發工具中解耦出來，建立獨立的中介層 (Context Layer)，是團隊推廣 AI 工具標準化的關鍵。 * **精細化的 Context 注入策略**：必須依照資料的特性 (能力、規範、記錄) 區分 Push 與 Pull 的消費模式，以在提升 AI 決策品質的同時避免 Token 溢出。 * **歷史脈絡作為工程資產**：引入 `Session-id` 至 Git Commit Trailer，將 AI 生成代碼的推理過程持久化，實現可追溯的 Session Blame 機制，這將大幅改善後續維護程式碼時的認知負荷。

--- tags: [Obsidian, 知識管理, AI應用, 工作流, 工具實踐] date: 2026-06-16 read: false source: "2026-06-16T093951+0800-9 Things My Obsidian Vault Does While I Sleep.md" original_title: "9 Things My Obsidian Vault Does While I Sleep" --- # 9 Things My Obsidian Vault Does While I Sleep  原始來源與檔名：2026-06-16T093951+0800-9 Things My Obsidian Vault Does While I Sleep.md --- ## NAPKIN | 餐巾纸 ### 餐巾紙公式 > Obsidian + n8n + LLM = Automated Intelligence Layer (自動化智慧層) _透過 n8n 串接 Obsidian 與 Claude，將靜態的筆記庫轉變為 24 小時運作的主動式大腦，幫你合成洞見與抓出盲點。_ ### 一句話 > 將 n8n 部署在底層作為自動化大腦，Obsidian 就不再只是儲存資訊的死水，而是一個每天早晨為你獻上洞見與挑戰的智慧工作夥伴。 ### 餐巾紙草圖 ```text [Telegram/Readwise] --> (n8n Automation) --> [Obsidian Vault] ^ | | v +----(Claude)------+ Synthesis Contradictions Triage ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 如何讓個人筆記庫 (Obsidian) 從被動的儲存系統，升級為能主動幫忙思考、發現盲點的基礎設施？ * **核心答案**: 在 Obsidian 底層建構一個獨立運行的 n8n 自動化層，利用 Claude 每天定時對筆記進行跨維度分析、總結與矛盾檢查。 * **論證結構**: 案例型 ### 章節骨架 1. **基礎建設**: VPS 部署 n8n 以確保持續運行 2. **每日合成**: 清晨產出非摘要式的筆記關聯報告 3. **無縫捕獲**: 透過 Telegram 30秒內隨時抓取靈感 4. **市場簡報**: 結合外部 API 對比自身論點與市場現況 5. **收件匣分類**: LLM 協助分類待發展、封存或捨棄的筆記 6. **矛盾檢查**: 找出新舊筆記中互相衝突的論點 7. **舊知重構**: 結合 Readwise 與新筆記激發長尾洞見 8. **每週深思**: 跨月維度分析宏觀趨勢與知識盲區 9. **清除與備份**: 孤兒筆記警告與自動 GitHub 備份 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 隱形假設與邊界 * **隱形假設**: * 筆記的真正價值在於它們之間的「關聯與碰撞」，而非單純的「儲存與收集」。 * 使用者有一套結構化的資料夾體系（如 Inbox, Sources, Ideas），自動化流程才能精準定位與執行。 * 創作者每天會產生大量且瑣碎的想法，需要自動化系統來協助過濾與關聯，否則大腦會超載。 * **邊界條件**: * 若筆記庫的日常輸入量不足，LLM 將難以產生有意義的交叉關聯 (Synthesis)，最終報告會顯得空洞。 * 如果 n8n 沒有獨立部署在雲端伺服器 (VPS) 上，而是安裝於本機筆電，當筆電休眠時自動化將完全失效。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: LLM 在進行「洞見合成」時可能產生幻覺 (Hallucination)，強行將兩個毫不相干的概念連結在一起，使用者需具備足夠的批判思考來審視這些自動生成的報告。 * **知識連接**: 這種做法非常類似軟體工程中的「CI/CD Pipeline」與「背景定時任務 (Cron Jobs)」。作者將開發者確保程式碼品質的機制（如自動化測試找 bug、自動構建）搬到了知識管理領域，用於測試邏輯與重構思想。 * **行動觸發**: 首先在雲端 (如 DigitalOcean) 部署一套 n8n 實例，接著先實作最基本的「Telegram 捕捉」與「GitHub 每日備份」功能，確保資料能安全且無阻礙地流入系統中。 --- # 9 Things My Obsidian Vault Does While I Sleep (Architectural Deep Dive) ## 前言/背景 本文探討如何將 Obsidian 從一個被動的儲存系統（Storage System）轉變為一個主動的智慧層（Intelligence Layer）。作者透過在 Obsidian 底層建立一個 n8n 自動化架構，並串接 Anthropic Claude API，設計了 9 個背景工作流（Cron Jobs）。這些工作流會在夜間自動對個人的知識庫進行分析、對比、分類與備份，使得隔天清晨就能獲得整理好的洞見與行動建議。 ## 章節詳細總結 ### 部署前提與基礎設施 (Prerequisites and Hosting) 作者強調，整個自動化架構的基石在於 **n8n 必須獨立運作**。若 n8n 只安裝在本機筆電，當筆電休眠時所有夜間排程都會失效。 * **最佳架構決策**：強烈建議採用 **VPS 自行託管 (Self-hosted)**。在 DigitalOcean 或 Hetzner 租用一個 $5-7/月的虛擬主機（1-2GB RAM），透過 Docker Compose 部署 n8n 社群版。這樣能獲得無限次的執行次數 (Unlimited executions) 且完全掌握資料控制權，遠勝於限制執行次數的 n8n Cloud 方案。 * **系統依賴要求**： * 嚴格遵守 5 個核心資料夾結構以利腳本定位：`00-Inbox`, `01-Sources`, `02-Ideas`, `03-Projects`, `04-Claude`。 * 各項外部 API 金鑰：Anthropic (Claude)、Readwise、CoinGecko、LunarCrush、Telegram Bot Token。 * 主機上配置好 SSH Key 以存取 GitHub Private Repository 進行備份。 ### 1. 清晨 6 點：每日綜合簡報 (The 6am Daily Synthesis Brief) 在每天早上 6 點，系統會將過去 7 天內新增的筆記傳遞給 Claude，並產出一份專注於「合成」而非「摘要」的報告。 * **N8N 節點配置與提示詞工程**： * **Schedule Trigger**: 每天 06:00 觸發。 * **Read Binary Files**: 讀取 Obsidian Vault 中過去 7 天有修改過的檔案。 * **Anthropic Node**: 呼叫 Claude 3.5 Sonnet，並在 System Prompt 嚴格要求「合成，不要摘要 (Synthesise, do not summarise)」。指示其產出四個具體區塊： 1. **Connections**: 找出兩篇無關筆記之間非顯而易見的關聯。 2. **Pattern**: 總結出現在三篇以上筆記中的共同趨勢。 3. **Contradiction**: 找出敘述互相衝突的筆記。 4. **Best capture**: 選出最值得深入發展的單一筆記。 * **Write Binary File**: 將結果直接寫入 `00-Inbox/brief-[date].md`。 ### 2. Telegram 即時捕捉管線 (The Telegram Capture Pipeline) 隨時隨地將靈感在 30 秒內寫入 Obsidian，將捕捉的摩擦力降到最低。 * **運作原理與實作細節**： * **Telegram Trigger**: 透過 BotFather 連結 Bot Token 監聽訊息。 * **Code Node (JavaScript)**: 使用 JS 解析輸入訊息並動態生成 Markdown 內容。 ```javascript const msg = $input.first().json.message; const text = msg?.text || "(no text)"; const date = new Date().toISOString().split("T")[0]; return [{ json: { filename: "00-Inbox/" + date + "-capture.md", content: "# Capture\n" + text + "\nDate: " + date } }]; ``` * **Write Binary File**: 將 Code 節點輸出的 JSON 物件提取檔案路徑與內容，寫入實體資料夾中。 ### 3. 清晨 5:45：加密貨幣市場簡報 (The Crypto Morning Brief) 利用外部資料 API 對比內部的研究假設，以獲得即時且客製化的市場動態。 * **工作流架構**： * 透過 **HTTP Request** 呼叫 CoinGecko API 獲取指定資產的價格與交易量，以及透過 LunarCrush API 獲取社交聲量 (Social volume)。 * 讀取 `03-Projects` 資料夾中作者自行建立的「論點筆記 (Thesis notes)」。 * **AI 推理分析**: 將市場數據與現有論點交由 Claude 分析。提示詞特別要求：「這份今天的數據是支持 (support)、挑戰 (challenge) 還是增加了新維度 (add new dimension) 到目前的論述中？請具體說明並參考數據。」 ### 4. 晚上 11 點：收件匣處理器 (The Inbox Processor) 實作「Triage (檢傷分類)」系統，自動處理每天進入 Inbox 的瑣碎思緒，防止 Inbox 變成無底洞。 * **自動化流程**： * 讀取當天新增的 Inbox 筆記，同時讀取整個 Vault 作為比對上下文。 * 要求 Claude 產出建議報告，為每則筆記標註三種狀態之一： * `DEVELOP`: 內容夠好，值得發展成獨立的 Ideas。 * `ARCHIVE`: 概念有價值但與現有 Vault 某筆記重複，提供重複的來源參考。 * `DELETE`: 經不起數小時沉澱的無意義靈感。 * **架構亮點**: 此步驟不會自動刪除檔案，而是只產出一個 Markdown 清單。決策與執行的主控權仍留在人類手上，避免 AI 誤刪重要想法。 ### 5. 早上 7 點：論點矛盾檢查 (The Thesis Contradiction Check) 自動化尋找反面證據的機制，有效對抗確認偏誤 (Confirmation Bias)。 * **配置邏輯**： * 讀取 `02-Ideas` 裡使用者的核心論述。 * 讀取過去 30 天內加進 `01-Sources` 的外部資料筆記。 * **提示詞防護**: 提示詞設定極為嚴格：「你的唯一工作就是找矛盾 (Your only job is contradiction)」。LLM 不允許尋找同意的觀點，只能指出新輸入的外部來源是否會推翻或複雜化現有論點。若沒有衝突則一律只回覆 "Clear"。 ### 6. 晚上 10 點：Readwise 舊知重構 (The Readwise Resurfacer) 活化長尾資料，讓過去的知識點能與當前的思考產生共鳴。 * **技術整合**： * 呼叫 Readwise API，優先提取超過 90 天且鮮少複習的 20 條畫線重點 (Highlights)。 * 讀取 `00-Inbox` 過去 14 天的筆記。 * 交由 Claude 找出兩者之間「非顯而易見的關聯」，只要有關聯就產出一句話的解釋，藉此引發跨時間維度的思考碰撞。 ### 7. 星期日晚上 11 點：每週深度連結 (The Weekly Deep Connection Session) 跨越 30 天維度的宏觀分析，用來彌補每日 7 天維度分析的侷限性。 * **執行腳本目標**： * 分析過去 30 天所有新增內容，要求 LLM 產出四個洞察： 1. **Emerging thesis**: 思考中正在成形但尚未被明確命名的新論述。 2. **Full contradiction map**: 盤點所有衝突與矛盾的全域地圖。 3. **Knowledge gaps**: 根據現有觀點指出「明顯缺失的視角」。 4. **One action**: 推薦本週單一最高槓桿的研究或寫作行動。 ### 8. 星期一早上 8 點：過期來源警告 (The Source Aging Alert) 建立系統的垃圾回收 (Garbage Collection) 與強制轉化機制。 * **實作機制**： * 讀取 `01-Sources` 內超過 60 天的舊筆記。 * 使用 **Code Node** 尋找筆記內是否有包含 `"My take:"` 或 `"Reaction:"` 標題，判斷該外部來源是否已經過使用者的個人思考。 * **Filter Node** 會將那些缺少反應段落的「孤兒筆記 (Orphaned captures)」過濾出來。 * 透過 Telegram 發送警告，強制使用者在當週處理或刪除這些積壓的來源。 ### 9. 午夜：GitHub 備份 (The Midnight GitHub Backup) * **自動化指令**：這被認為是最關鍵的防禦性機制，利用 Execute Command 節點每天深夜執行 Shell 腳本： ```bash cd /path/to/your/vault && git add -A && git commit -m "vault-backup-$(date +%Y-%m-%d)" && git push origin main ``` * 藉此確保 Vault 中所有的 AI 產出報告、原始筆記與分類建議，都能被永久保存且具備 Git 版本控制的歷史紀錄。 ## 總結與結論 * **基礎設施即習慣 (Infrastructure as a Habit)**：將 N8N (事件驅動與排程引擎) 獨立部署在 VPS 上，是讓系統持續運算的關鍵。這改變了應用程式的生命週期，將 Obsidian 從一個靜態的本機編輯器，升級為一個具有運算能力的背景服務。 * **利用 LLM 執行自動化測試與斷言**：作者巧妙地將軟體工程中「自動化測試 (Automated Testing)」的概念引入知識管理。例如「Thesis Contradiction Check」，透過 Prompt 強制 LLM 只尋找衝突與矛盾，相當於為個人的論點編寫了一套自動化的壓力測試腳本。 * **遵循防禦性設計的非破壞性工作流**：在諸如 Triage 垃圾清理等高風險操作中，系統並不直接執行覆蓋或刪除，而是產出「建議清單」。決策權始終保留在人類身上，有效管控了 LLM 產生幻覺 (Hallucination) 可能帶來的資料遺失風險。 * **極高的成本效益比 (High Cost-Efficiency)**：即便每天執行 9 個包含 LLM 推理的定時任務，藉助高效能模型（如 Claude 3.5 Haiku）與免費開源自託管的 n8n，整套系統的每月運行成本僅約 $8 到 $15 美金。相較於其產出的智慧綜合成效，這是一筆回報極高架構投資。

--- tags: [Prompt工程, AI模型, 工具技巧, 工作流] date: 2026-06-16 read: false source: "2026-06-16T093858+0800-300 Claude Fable 5 Prompts That Replace Hours of Manual Work Every Single Day.md" original_title: "300 Claude Fable 5 Prompts That Replace Hours of Manual Work Every Single Day" --- # 300 Claude Fable 5 Prompts That Replace Hours of Manual Work Every Single Day  原始來源與檔名：2026-06-16T093858+0800-300 Claude Fable 5 Prompts That Replace Hours of Manual Work Every Single Day.md --- ## NAPKIN | 餐巾纸 ### 餐巾紙公式 > 深度提示詞 (Deep Prompts) × (百萬 Token 脈絡 + 誠實反饋 + 自主運行能力) = 取代人工基礎架構 _將 Claude Fable 5 當作長期自主運行的系統，而非單次問答工具，能產生質變的效率提升。_ ### 一句話 > 不要把 Fable 5 當作問答機器人，而應該將高階提示詞編碼為自動化技能，讓它成為運行你思維邏輯的基礎設施。 ### 餐巾紙草圖 ``` [常規模型] Question ---> [ LLM ] ---> Answer (結束) [Fable 5 基礎設施] Context (百萬 Token) ---+ Deep Prompts (系統化) ---+---> [ Fable 5 Autonomous Engine ] ---> (持續自主迭代/誠實反饋) ---> 結構化輸出/自動化技能 Scheduled Tasks ---+ ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 人們為何沒有發揮 Claude Fable 5 的真正潛力，以及如何將其應用於複雜的高階工作？ * **核心答案**: 透過專為其百萬脈絡、誠實度和自主能力設計的 300 個深度提示詞，並將其轉化為自動化技能，Fable 5 可以成為代替人類執行深層思考和複雜任務的基礎設施。 * **論證結構**: 分類展示型（歸納與案例），將 300 個提示詞分為十個領域，最後提出系統化的應用框架。 ### 章節骨架 1. **深度研究與合成**: 跨文獻的模式識別與盲點尋找。 2. **寫作與內容生產**: 挑戰性寫作與多維度重構。 3. **商業策略與分析**: 壓力測試、假設驗證與護城河分析。 4. **程式碼與技術工作**: 架構評估、重構計畫與深層除錯。 5. **決策支援**: 逆向思維、風險評估與二三階效應。 6. **溝通與說服**: 換位思考與防禦性溝通。 7. **學習與知識發展**: 專家心智模型與盲區突破。 8. **生產力與系統**: 系統化工作流與瓶頸消除。 9. **問題解決與創新**: 第一性原理與逆向工程。 10. **個人與專業發展**: 職涯覆盤與反思性回饋。 11. **如何使用**: 將提示詞轉化為自動化技能。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 隱形假設與邊界條件 * **隱形假設**: * 使用者擁有足夠高品質的原始資料（Context）可以餵給模型。 * Fable 5 的「誠實度」（承認失敗率低至 5%）能夠在所有領域保持一致。 * 使用者具有將提示詞轉化為 Agent 技能的技術能力或工具（如 Hermes Agent）。 * **邊界條件**: * 當任務是簡單的單次問答時，使用 Fable 5 加這些複雜提示詞會是殺雞用牛刀。 * 若輸入的上下文本身充滿噪音或完全錯誤，模型可能無法產出有效的深度洞察（Garbage In, Garbage Out）。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 文章雖然提供了強大的提示詞，但並未深入探討自主運行（Autonomous operation）可能帶來的失控風險或除錯成本。 * **知識連接**: 與 GitOps 中的「宣告式基礎設施 (Infrastructure as Code)」概念相似，這裡提倡的是「思維即基礎設施 (Thinking as Infrastructure)」。 * **行動觸發**: 不要只是複製貼上這些提示詞。挑選 3 個最符合目前工作痛點的提示詞，將其寫成自動化腳本，設定排程讓其每週自動對個人知識庫進行掃描與輸出。 ### 跨域映射 * 在 **軟體工程**，這叫 **Continuous Integration/Continuous Deployment (CI/CD)**（讓程式碼自動編譯測試，Fable 5 則是讓思考自動化運行）。 * 在 **系統工程**，這叫 **批次處理與自動化排程 (Batch Processing & Cron Jobs)**。 --- # 300 Claude Fable 5 Prompts That Replace Hours of Manual Work Every Single Day (Architectural Deep Dive) ## 前言/背景 這篇文章探討了多數人使用 AI 模型（特別是強大的 Claude Fable 5）的誤區：仍將其視為簡單的單次問答工具（Chatbot）。作者主張 Fable 5 是一種具備百萬 Token 脈絡、深層推理能力與自主運行特性的基礎設施，並提供了橫跨 10 大專業領域、總計 300 個高階提示詞。核心目標是將這些提示詞轉化為系統化的「自動化技能」，徹底改變知識工作者的作業模式。 ## 章節詳細總結 ### 1. 深度研究與合成 (Deep Research and Synthesis) 利用 Fable 5 龐大的 Context Window，將整個資料庫作為輸入，並要求其進行跨文獻的模式識別。 * **技術細節保留**： * 不要求表面摘要，而是要求提取**「共識」、「矛盾」以及「無人提及的盲點」**。 * 要求對不同來源的數據進行「壓力測試」，例如：找出若某項假設為假，將導致哪些結論失效（Cascade Effect）。 * 要求辨識**「相關性被誤導為因果關係」**的具體實例，並標示來源與日期。 ### 2. 寫作與內容生產 (Writing and Content Production) 將模型作為嚴苛的編輯與不同視角的代寫者。 * **技術細節保留**： * 要求進行**「魔鬼代言人」測試**：先寫出初稿，再寫出全面反駁初稿的第二稿，最後融合兩者產出第三稿。 * 針對長文，要求直接辨識「負載最大（Load-bearing）」的段落，並優先強化，同時刪除沒有實際作用的句子。 * 要求以「逆向工程」方式寫作：從結論出發，反推並建立證據鏈。 ### 3. 商業策略與分析 (Business Strategy and Analysis) 這部分的提示詞將 AI 轉換為具備冷酷邏輯的 CFO 或競爭對手。 * **技術細節保留**： * 要求辨識商業計畫中的「關鍵假設（Crucial Assumptions）」，並按其出錯的機率進行排序。 * 進行**「二階與三階效應（Second and Third-order Effects）」**分析，特別是在建置 (Build) 或是購買 (Buy) 系統能力的決策上。 * 要求挑出正在被最佳化、但實際上無法預測核心目標的「虛榮指標（Vanity Metrics）」。 ### 4. 程式碼與技術工作 (Code and Technical Work) 對工程師最實用的架構審查與除錯模式。 * **技術細節保留**： * **架構決策審查**：輸入整個 Codebase，要求 AI 點出「隨著規模擴張，未來最難以逆轉的 3 個架構決策」。 * **相依性與重構**：在修改程式碼前，先要求 AI 繪製相依性映射圖（Dependencies Map），並給出風險最小的重構順序。 * **深層效能分析**：不只是要求最佳化，而是要求「分析當前流量增長十倍時，哪裡會最先崩潰（What breaks first at 10x traffic）」。 * **邊界條件測試**：寫測試案例時，明確限制 AI「只專注於可能導致正式環境當機的邊界情況（Edge cases），忽略 Happy Path」。 ### 5. 決策支援與問題解決 (Decision Support & Problem Solving) 利用模型強大的邏輯推演能力來消除人類認知偏誤。 * **技術細節保留**： * **前置驗屍（Pre-mortem）**：假設兩年後專案失敗了，要求 AI 推演失敗的完整過程。 * **決策樹展開**：為特定選擇列出所有節點、分支與應該分配的機率。 * **第一性原理與限制解除**：分析問題時，區分「真正的限制」與「被認知為限制的變數」，並應用「如果解決方案必須免費，它會長什麼樣」的極端約束來逼出創新。 ### 6. Fable 5 基礎設施化實踐 (How to Use These Prompts With Fable 5) 這是全篇最具架構思維的章節，將 Prompt 從「工具」提升為「基礎設施」。 * **架構決策理由 (Architectural Reasoning)**： * **脈絡視窗 (Context Window)**：因為 Fable 5 支援 1M tokens，過去無法一次性送入的龐大 Codebase 或文獻庫現在可作為完整 Context 傳入，避免了 RAG 系統中 Chunking 帶來的脈絡斷層。 * **誠實度 (Honesty Rate)**：模型的自我報告失敗率降低至 5% 以下，這意味著它能真正提出「挑戰性反饋」，而不是為了解決用戶情緒而給出虛假的肯定。 * **自主運行 (Autonomous Operation)**：作者強烈建議不要「手動執行」這些提示詞，而是將其打包成 Agent 技能（如 Hermes Agent），定期對知識庫或程式碼庫進行背景掃描與自動產出（例如每週一早上的優先級審查）。 ## 總結與結論 * **Prompt as Infrastructure（提示詞即基礎設施）**：高階 AI 模型的用法已經從「單次對話」演進到「非同步的自動化批次處理」，開發者應將好的 Prompt 封裝為可定時執行的背景 Job。 * **Context 完整性優於局部檢索**：在處理架構重構或系統分析時，直接餵入整個專案的上下文（得益於百萬 Token 能力）能產生比傳統 RAG 更精準的全局架構洞察。 * **反向工程思維 (Reverse Engineering in Prompts)**：在設計 AI 任務時，多使用「找出盲點」、「如果失敗會是因為什麼」、「哪裡最先崩潰」等負面表列與壓力測試型 Prompt，能挖掘出更深層的系統脆弱點。 * **批判性替代驗證性**：不再讓 AI 單純生成內容，而是讓 AI 成為「魔鬼代言人」，針對人類提出的架構設計進行嚴格的漏洞掃描與邊界測試。

--- tags: [Prompt工程, AI工具, AI工程] date: 2026-06-16 read: false source: "2026-06-16T094257+0800-Claude Opus 4.8 Prompting Guide 9 Copy-Paste Prompts for Real Work.md" original_title: "Claude Opus 4.8 Prompting Guide 9 Copy-Paste Prompts for Real Work" --- # Claude Opus 4.8 Prompting Guide: 9 Copy-Paste Prompts for Real Work  原始來源與檔名：2026-06-16T094257+0800-Claude Opus 4.8 Prompting Guide 9 Copy-Paste Prompts for Real Work.md --- ## NAPKIN | 餐巾纸 ### 餐巾紙公式 > Claude 4.8 效能 = 自適應思考 (Adaptive Thinking) + 明確語氣/格式 + 容許不確定性 (Uncertainty Allowance) _捨棄傳統的溫度參數 (Temperature) 與預算控制，改以純文字提示引導模型思考層級與誠實度。_ ### 一句話 > Claude Opus 4.8 移除了溫度與思考預算的參數控制，改由自適應思考與五級投入度 (Effort) 決定，因此提示詞必須明確指示何時該思考、何時該直接回答，並給予承認未知的許可。 ### 餐巾紙草圖 ``` [ 舊版 Prompt ] --> ( Temperature / Tokens ) --> [ 黑盒子 ] | v [ 4.8 版 Prompt ] ├── 簡單任務 --> "直接回答，不需多想" ---> [ 快速產出 (Low Effort) ] ├── 複雜任務 --> "多步推理，檢查條件" ---> [ 自適應思考 (High Effort) ] └── 代理系統 --> "說明工具用途，確認後停止" -> [ 精準工具呼叫 ] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: Claude Opus 4.8 的底層機制改變後，如何重新撰寫有效能且節省成本的提示詞？ * **核心答案**: 拋棄不可用的參數設定 (如 Temperature)，使用作者提供的 9 個具體提示詞模式，在不同情境中精確控制思考深度、確定性與代理行為。 * **論證結構**: 案例型/實戰型。透過具體代碼塊和應用場景展示每一個提示詞的功效。 ### 章節骨架 1. **核心改變**: 參數棄用，思考轉為自適應。 2. **控制思考**: 用文字開關深思或速答。 3. **誠實度控制**: 允許模型承認不確定性。 4. **格式與確定性**: 移除溫度後，用語氣控制。 5. **代理防護**: 防止工具濫用與無窮迴圈。 6. **動態更新**: 運行中更改系統提示詞。 7. **系統模板**: 將所有控制手段整合。 8. **防過度工程**: 一句話擋下小題大作。 9. **反面教材**: 避免過時的提示習慣。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ``` Claude 4.8 取消了 Temperature 等參數 --> 開發者無法再用硬參數控制創造力或精確度 --> 必須改用語意明確的文字提示來約束模型 --> 作者經過實測整理出 9 種最高效的複製貼上提示詞。 ``` ### 關鍵證據 1. 官方 API 變更：使用 `temperature`、`top_p` 或舊版 `budget_tokens` 會直接觸發 400 錯誤。 2. 實證對比： Opus 4.8 預設會過度思考（high effort），用提示詞強制 "直接回答" 可顯著節省 Token 和延遲。 3. 實戰數據：使用這些模式建構的工具（如 Bun 的 Zig 轉 Rust）能處理幾十萬行程式碼並維持 99.8% 的測試通過率。 ### 隱形假設與邊界 * **隱形假設**: * 使用者已經熟悉 Claude API 或是 Claude Code 工具的基本操作。 * 使用者開啟了自適應思考 (`thinking: {type: "adaptive"}`)，否則部分提示詞無效。 * **邊界條件**: * 若任務本身不需要推理，即使開啟最高 effort 也只是浪費資源。 * 對於非 Opus 4.8 的舊模型，這些提示詞的效率可能不彰，甚至不如直接調整溫度參數。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 雖然強調了提示詞在 4.8 中的核心地位，但較少探討如何讓 LLM 透過自身狀態動態自我評估何時該切換 Effort，仍較仰賴人工預設。 * **知識連接**: 與軟體工程中的 "防禦性程式設計" (Defensive Programming) 極為相似——在提示詞中加入各種斷言 (Assertions) 與失敗條件，防止模型 "幻覺" (Hallucination) 導致整個代理崩潰。 * **行動觸發**: 全面清理現有的系統提示詞，移除所有涉及 Temperature 或 Token 預算的描述，並在所有自動化代理腳本中強制加入「承認不確定性」的護欄提示詞。 ### 跨域映射 * 在 **軟體工程**，這叫 **防禦性程式設計 (Defensive Programming)** * 在 **組織管理**，這叫 **授權與邊界設定 (Delegation with Boundaries)** --- # Claude Opus 4.8 Prompting Guide: 9 Copy-Paste Prompts for Real Work (Architectural Deep Dive) ## 前言/背景 這篇文章針對 Claude Opus 4.8 模型的底層架構變更（移除了傳統的 `temperature` 參數控制，並引入預設關閉的自適應思考 `adaptive thinking`），提供了一套實戰等級的 Prompting 策略。核心解決了開發者在升級至 4.8 版本時遇到的 400 錯誤、過度消耗思考 Token、以及代理模型 (Agent) 在迴圈中失控或產生幻覺等問題。 ## 章節詳細總結 ### 1. Claude Opus 4.8 的四大底層機制變更 在架構層面上，Opus 4.8 移除了過往開發者依賴的機率控制參數，將控制權全面轉移至自然語言。 * **棄用機率參數**：無法設定 `temperature`、`top_p` 或 `top_k`。傳入這些非預設值會直接觸發 API 的 400 錯誤。 * **自適應思考 (Adaptive Thinking)**：預設為關閉。原本的 `budget_tokens` 參數被移除，現在必須透過 `thinking: {type: "adaptive"}` 開啟，並搭配 `effort` 參數來控制。 * **五級投入度 (Effort Levels)**：分為 `low`, `medium`, `high` (預設), `xhigh`, `max` 五種級別。 * **增強的自我糾錯能力**：模型對自身產出的程式碼缺陷有更強的辨識力（約提升了 4 倍），這使得「誠實度提示詞」變得極具價值。 ### 2. 精確控制自適應思考的消耗 (Token/Latency Optimization) 預設的 `high` effort 會導致模型對不需推理的簡單問題（如單檔編輯、格式化）過度思考，浪費大量 Token 與等待時間。 * **全局防過度思考 (Prompt 1)**：在 System Prompt 寫入規則，約束模型在簡單任務中直接給出答案： ```text Extended thinking costs latency and tokens. Use it only when a task genuinely needs multi-step reasoning. For lookups, single-file edits, renames, and formatting, answer directly without deliberating. ``` *架構意義*：將此設定搭配 `effort: "medium"` 處理雙峰型負載（Bimodal Workloads，即大量簡單任務加上少量複雜任務），能有效降低系統開銷。此設定僅在 `thinking` 啟動時有效。 * **單次強制深度推理 (Prompt 2)**：遇到極度困難的單一步驟時，不要全域拉高 effort，而是在該次 User Message 附加： ```text This needs multi-step reasoning. Think carefully before you answer, and check your result against the requirements before you respond. ``` *架構意義*：實踐了細粒度的資源控制 (Fine-grained resource control)，避免全域狀態導致的不必要花費。 ### 3. 強化代理的誠實度與防禦邊界 (Defensive Prompting) 代理系統 (Agents) 最怕的是「假陽性」的成功回報（例如回報測試通過但實際上並未執行）。 * **防禦性承諾 (Prompt 3)**： ```text If you are not confident a change is correct, stop and tell me exactly what you're unsure about. Do not guess. Never say a test or build passed unless you ran it and saw it pass. If you didn't verify something, say so plainly. ``` *架構意義*：利用 4.8 增強的錯誤標記能力，賦予模型「提早失敗 (Fail-Fast)」的權限。這是在迴圈式 Agent 系統中最重要的一個安全護欄。 ### 4. 移除溫度後的格式與確定性控制 在沒有 `temperature=0` 可以使用的情況下，必須透過嚴格的文字約束來達到系統所需的 Deterministic Output。 * **無解釋的純程式碼產出 (Prompt 4)**： ```text Output only the final code block. No preamble, no explanation, no alternatives. If a caveat is essential, put it in one trailing comment inside the code. ``` *架構意義*：保證 API 回應能夠直接被下游的 Parser 或 AST 工具攝取，而不會被 Markdown 的閒聊文字 (Preamble) 破壞。 ### 5. 工具呼叫的防護與動態系統提示 * **防止工具濫用 (Prompt 5)**： ```text Before each tool call, state in one sentence why you're calling it. After you get the result, decide whether you can answer now. If you can, stop calling tools and respond. Don't call a tool you don't need. ``` *架構意義*：結合自適應思考，強迫模型在多次呼叫之間產生 State Check 邏輯，大幅降低 API 迴圈失控（無限調用工具）的風險。 * **Mid-run 動態更新 (Prompt 6)**： 在對話中途插入 `{"role": "system", "content": "..."}` 來更改代理的上下文或預算限制： ```json {"role": "system", "content": "Update: budget is now tight. Prefer the smallest correct fix. Stop after the failing test passes. Do not refactor beyond what the test requires."} ``` *架構意義*：這是 4.8 Messages API 的新特性，允許系統在長任務中途動態注入狀態變更，而不需要重新發送 2000 token 的完整 System Prompt，完美保全了 Prompt Cache，大幅降低成本。 ### 6. 整合式框架與反過度工程 * **標準系統模板 (Prompt 8)**：將所有防護機制（Thinking 控制、誠實度、工具紀律、輸出格式）集中成一個可重用的樣板。 * **防過度工程 (Prompt 9)**： ```text If the fix is a one-line change, just make it. Don't write a plan. ``` *架構意義*：針對 `xhigh` effort 下模型的通病（寫單行代碼卻產生長篇大論的計畫）進行的「短路處理 (Short-circuiting)」，這能移除多餘的系統摩擦並提升執行效率。 ## 總結與結論 * **從參數微調轉向語意架構**：對於 Cloud Native 的 AI 應用開發者來說，不再需要微調 Temperature 或 Token 預算，提示詞即是系統配置檔 (Prompt as Configuration)。開發者必須精確定義「何時該思考、何時該直接行動」。 * **防禦性提示詞 (Defensive Prompting) 是 Agent 的基石**：在多步代理迴圈中，賦予模型「承認不知道」與「提早終止」的明確權限（Fail-Fast 機制），遠比追求模型每次都產出完美答案來得更安全且可靠。 * **利用動態系統訊息保全 Cache 成本**：善用 Messages API 中途注入 `system` role 的能力，在長任務代理 (Long-running Agents) 中動態調整邊界條件（如：預算緊縮、停止重構），這是目前優化 Token Cache 的最佳架構實踐。

--- tags: [Prompt工程, AI輔助編程, Agent, 邊界框架, 工作流] date: 2026-06-16 read: false source: "2026-06-16T094222+0800-The Best AI Coding Hack I Found Wasn’t a Prompt. It Was a Boundary..md" original_title: "The Best AI Coding Hack I Found Wasn’t a Prompt. It Was a Boundary." --- # The Best AI Coding Hack I Found Wasn’t a Prompt. It Was a Boundary.  ## 1. 核心概念與 XRay 結構 - 核心概念：在 AI 輔助編程（Agent）中，優化產出品質的關鍵不在於撰寫更巧妙的提示詞（Prompt），而是為 AI 設定明確的「工作邊界（Boundary）」，以此限制其行為沙盒，確保修改結果安全、可控且便於人類審查。 - XRay 結構解析： - **現狀痛點**：給予 AI 過於開放的任務（如「讓程式碼更乾淨」）會導致其越權修改無關檔案、破壞現有架構，產生看似合理但難以驗證的大型 Diff。 - **核心主張**：提示詞是在「指派工作」，而邊界是在「定義工作區域」。必須讓 AI 清楚知道什麼是成功的結果、什麼是危險的行為，以及何時該停下。 - **四大邊界維度（The Four Boundaries）**： - 檔案邊界（File Boundary）：明確指定允許編輯的資料夾與絕對禁止觸碰的目標（如共用合約、自動生成檔案、CI 配置）。 - 行為邊界（Behavior Boundary）：定義必須維持不變的系統特徵（如不改變公開 API 簽名、維持既有請求與回應結構）。 - 驗證邊界（Validation Boundary）：規範必須執行的證明程序（如指定需通過的單元測試指令）。 - 停止邊界（Stop Boundary）：設定自動煞車機制（如當需修改超過三個檔案時，必須停止並先提出計畫）。 - **高風險防禦機制（Plan-First Rule）**：處理驗證、支付、資料庫遷移等核心模組時，強制執行「先診斷後執行」的原則，在修改前必須先輸出預期修改清單並等待人類批准。 - **基礎架構化**：將邊界規則從單次的提示詞，下沉至程式碼庫級別的系統配置（如 `.github/copilot-instructions.md` 或 `AGENTS.md`），將隱性團隊知識轉化為 AI 的標準操作手冊。 ## 2. 架構深潛 (Architectural Deep Dive) - **Agent 介面的擴展與風險**：隨著 AI 從單純的文字補全進化為具備工具使用能力的 Agent，其互動介面已超越對話框，延伸至檔案讀取、指令執行與分支建立。若不施加嚴格約束，模型在尋求最佳解時，極易透過修改全域合約來解決局部問題。邊界框架本質上是為 Agent 的行動能力施加「最小權限原則（Principle of Least Privilege）」。 - **可審查性（Reviewability）優於自動化程度**：導入嚴格的邊界會增加開發流程的摩擦力——AI 會頻繁暫停、拒絕修改某些檔案或要求計畫審查。然而，這種效率上的妥協是必要的。在生產環境中，將修改的「爆炸半徑（Blast Radius）」控制在開發者認知負荷範圍內，防止難以察覺的架構層次破壞，其工程價值遠高於一次性的大規模自動重構。 - **決策與執行的狀態解耦**：AI 編程災難多源於模型過早猜測設計意圖並開始改變程式碼狀態（Mutate state）。「Plan-First Rule」在架構上強行切斷了推論與執行的耦合，迫使模型將隱含的規劃過程外顯化為可觀測的計畫。這種機制避免了模型因過早修改而陷入路徑依賴（Path dependence）。 - **權限控制的工程落地**：文章提到了 Claude Code 的權限控制（如編輯白名單/黑名單、讀取拒絕規則、沙盒檔案系統控制）以及 GitHub Copilot 的 Repository 級別指令。這代表著邊界管理正在從「Prompt Engineering」演進為「Configuration as Code」，未來的 AI 專案必須將 Agent 權限範圍直接編碼於 Repo 的基礎架構中，避免 AI 重複性地破壞既定的架構邊界。

--- tags: [實戰教學, Agent架構, AI工程, 開發工具] date: 2026-06-16 read: false source: "2026-06-16T093828+0800-AI Agents. What they are and how to Build Your Own Step by Step..md" original_title: "AI Agents. What they are and how to Build Your Own Step by Step." --- # AI Agents. What they are and how to Build Your Own Step by Step.  原始來源與檔名：2026-06-16T093828+0800-AI Agents. What they are and how to Build Your Own Step by Step..md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > Agent = LLM + Tools + Memory + Loop _代理不只是一個語言模型，它是模型加上可呼叫的外部工具、跨任務的持久記憶，以及直到任務完成才停止的執行迴圈。_ ### 一句话 > AI 代理不是單一的分類而是一個光譜，只要結合 Claude Code 與 Telegram，任何人都能在 20 分鐘內用自然語言打造出具備外部工具與記憶功能的自動化個人助理。 ### 餐巾纸草图 ```text [ 用戶請求 ] --> [ Agent Loop ] <====> [ Memory / Context ] | v [ 決策與規劃 (LLM) ] / | \ v v v [ Search ] [ File ] [ API ] \ | / \ v / [ 執行結果回饋 ] ----> [ 任務完成? ] --> [ 輸出結果 ] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這本書在說什麼"** * **核心問題**: 什麼是真正的 AI Agent，以及普通人如何快速建立自己的 Agent？ * **核心答案**: Agent 是具備工具、記憶和執行迴圈的 LLM；透過 Claude Code 與 VPS，只需自然語言即可快速部署專屬的 Telegram 代理機器人。 * **論證結構**: 案例型與實操型結合（先定義光譜，再提供具體程式碼 Prompt 範本與佈署步驟）。 ### 章節骨架 1. **定義光譜**: Agent 從單純對話到全自動化。 2. **常見類型**: 研究、寫作、程式、商業與個人助理。 3. **環境準備**: API 金鑰、Telegram Token 與 VPS 伺服器。 4. **初始化建置**: 利用 Claude Code 透過 Prompt 自動生成 Python 程式碼並部署。 5. **擴充技能**: 透過對話新增網路搜尋、儲存筆記、用戶限制等能力。 6. **解決失憶**: 使用 Checkpoint 與 Rolling Summary 解決長文脈絡遺失問題。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text 單純的 LLM 無法自主執行任務 --> 賦予 LLM 工具呼叫、記憶保留與自動迴圈能力即可成為 Agent --> Claude Code 擅長根據自然語言指令生成並修改系統程式碼 --> 結合 Python 的 Telegram 函式庫與 VPS，即可建立專屬個人的 Agent ``` ### 關鍵證據 1. **具備現成工具的生態系**: 使用 Claude API (Sonnet 4.6)、Tavily API 進行網路搜尋，證明外部工具的容易整合。 2. **Claude Code 的程式生成能力**: 只需提供「Build me a Telegram bot...」的 Prompt，Claude Code 就能自動產出包含 `requirements.txt`、`.env` 模板與 `main` 程式碼在內的完整專案。 3. **記憶留存機制**: 透過系統提示詞（System Prompt）以及讀寫 JSON 檔案的方式，能有效解決 Context Window 溢出問題。 ### 隱形假設與邊界 * **隱形假設**: * 使用者具備基礎的終端機 (Terminal) 操作能力。 * 自然語言提示 (Prompt) 必須足夠精準，Claude Code 才能寫出無 Bug 的程式碼。 * 伺服器 (VPS) 能夠穩定連線至 Telegram API 與 Anthropic API。 * **邊界條件**: * 當任務過於複雜，超出了 Claude 模型的規劃能力時，迴圈可能會無限卡死或產生錯誤決策。 * 當對話歷史不斷堆疊，即便有摘要機制，最終仍可能面臨 Token 成本過高或細節丟失的問題。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 文章雖然解決了個人 Agent 的構建，但忽略了安全性考量（如 Prompt Injection 攻擊），以及系統錯誤時的自動降級或警報機制。 * **知識連接**: * 與軟體工程中的「狀態機 (State Machine)」概念高度重合。 * 呼應了 LangChain 或 AutoGen 架構中關於 ReAct (Reasoning and Acting) 的核心設計模式。 * **行動觸發**: 立即租用一台廉價的 VPS (如 DigitalOcean)，並使用文中提供的 Prompt 部署一個追蹤個人任務與每日 API 成本的專屬機器人。 ### 跨域映射 * 在 **軟體工程**，這叫 **狀態持久化與插件化架構 (State Persistence & Plugin Architecture)** * 在 **控制理論**，這叫 **閉環控制系統 (Closed-loop Control System)** --- # AI Agents. What they are and how to Build Your Own Step by Step. (Architectural Deep Dive) ## 前言/背景 隨著大型語言模型 (LLM) 的普及，「AI Agent」成為業界熱詞，但多數人對其定義仍停留在模糊的「自動做事的 AI」。本文從工程角度切入，精確定義了 Agent 的核心構成（工具、記憶、執行迴圈），並提供了一套不需手動編寫程式碼，完全依賴 Claude Code 與自然語言 Prompt，將 AI 代理整合進 Telegram 並部署於雲端 VPS 的完整實戰架構與流程。 ## 章節詳細總結 ### 1. Agent 的定義與光譜架構 (The Spectrum: From Chat to Agent) 作者指出，Agent 並非一種非黑即白的分類，而是一個「光譜」。一個完整的 Agent 架構必須具備三個超越傳統聊天機器人 (Chatbot) 的核心元件： * **工具 (Tools)**：能夠主動呼叫的外部介面，如搜尋引擎、檔案系統操作、程式碼執行環境或外部 API。 * **記憶 (Memory)**：能跨越單一 Session 持久化儲存的上下文狀態，而不僅是單次對話的 Token 視窗。 * **執行迴圈 (Loop)**：這是一個控制流 (Control Flow)，驅動 Agent 持續執行「評估->行動->反饋」的循環，直到滿足任務完成條件。 ### 2. 系統架構與基礎設施準備 (What you need before starting) 建置個人專屬的 Agent 不需要龐大的算力，其架構極為輕量： * **大腦運算層**：透過呼叫 Anthropic 的 Claude API。作者建議個人日常使用 **Sonnet 4.6**（效能與成本的最佳平衡），若要極致省錢可選 Haiku 4.5，高難度推理才使用 Opus 4.8。 * **介面層**：透過 BotFather 申請 Telegram Bot Token，作為與 Agent 互動的使用者介面。 * **執行環境**：一台運行 Linux 的低階 VPS（1 CPU, 1GB RAM, 20GB Storage），部署成本約每月 $4-6 USD。 * **建置工具**：在 VPS 上透過 npm 全域安裝 Claude Code：`npm i -g @anthropic-ai/claude-code`。這將作為自動化寫扣與部署的開發者代理。 ### 3. 初始化核心架構與部署 (Building Your First Agent) 本文最核心的技術實踐是利用「自然語言即程式碼 (Natural Language as Code)」。透過向 Claude Code 輸入特定的 Prompt，讓其生成 Python 系統架構： **基礎機器人架構 Prompt**： ```text Build me a Telegram bot that uses the Claude API as its brain. Requirements: - Language: Python - Library for Telegram: python-telegram-bot - Claude model: claude-sonnet-4-6 - The bot receives a message, sends it to Claude API, and returns Claude's response to Telegram - Maintain conversation history per user — each user has their own context within the session - Add a /start command that introduces the bot - Add a /clear command that resets conversation history for that user Create all necessary files: main bot file, requirements.txt, and a .env file template for API keys. Do not hardcode any API keys — read them from environment variables. ``` * 架構決策 (Why)*：要求使用 `.env` 是為了避免金鑰外洩的標準安全實踐；使用 `python-telegram-bot` 是因為其具備良好的異步 (Async) 支援；按使用者 ID 隔離 Conversation History 是多租戶 (Multi-tenant) 設計的基礎。 **背景服務部署 Prompt**： 為了確保高可用性 (High Availability)，將 Python 腳本封裝為 Linux `systemd` 服務： ```text Create a systemd service file so this bot runs automatically on my Linux VPS and restarts if it crashes. ``` * 架構決策 (Why)*：依賴系統層級的進程守護程式，實現 Crash 後的自動重啟 (Auto-recovery)，並確保伺服器重開機時自動掛載服務。 **持久化記憶設計 Prompt**： ```text Save each user's conversation history to a JSON file on disk after every message. Load it back automatically when the bot starts. Add a maximum history length — keep only the last 20 messages per user so the context window never gets too long. ``` * 架構決策 (Why)*：記憶體內的變數在進程終止時會遺失。透過寫入磁碟 (JSON 檔案) 達成狀態持久化 (State Persistence)；限制保留 20 則訊息則是簡單的滑動視窗 (Sliding Window) 策略，用以控制 Token 消耗與防止 Context Overflow。 ### 4. 擴充技能模組 (Adding Skills) 在核心迴圈建立後，透過模組化 (Modular) 的方式為 Agent 增加能力： * **Web Search (網路搜尋)**：透過 `Tavily API`，並啟用 Claude 的 `Tool use (Function Calling)` 特性。Agent 能自主決定何時呼叫搜尋 API 獲取外部即時數據。 * **Note Saving (檔案系統 I/O)**：實現持久化外部知識庫，遇到特定關鍵字觸發寫入 `notes.txt` 檔案的 IO 動作。 * **Security (權限隔離)**：將管理員的 Telegram User ID 寫入環境變數 `ALLOWED_USER_ID`，並在路由層攔截未授權的請求，避免 API 資源被惡意消耗。 * **Cost Tracking (成本監控)**：攔截 API Response 中的 Token Usage 數據，累積寫入 `costs.json`，並換算為美金，實現基礎的系統可觀測性 (Observability)。 * **Cron Jobs (排程任務)**：整合 `APScheduler` 實作每日定時任務 (Daily Briefing) 的主動推送 (Push Notification)。 ### 5. 解決 Context 遺失的記憶工程 (The Memory Problem Every Agent Has) 長任務會導致 Token 視窗溢位。作者提出了四種「記憶壓縮與文脈恢復」的 Prompt 工程策略： 1. **Checkpoint Prompt**：在暫停前，強制 Agent 輸出當前進度、已作決策、待辦事項與所需文脈。 2. **Memory File Prompt**：規定固定的格式記錄狀態 `STEP COMPLETED`, `KEY DECISIONS`, `CURRENT STATE`, `NEXT STEP`，這等同於在對話中實作了一個簡單的狀態機快照 (State Snapshot)。 3. **Context Recovery Prompt**：在新 Session 開始時注入前述的 Snapshot，讓 Agent 無縫恢復狀態。 4. **Rolling Summary Prompt**：當對話過長時，強制觸發一次摘要：「The conversation is getting long. Compress everything important into a summary...」。這是將 O(N) 的歷史紀錄壓縮成 O(1) 的核心技術。 ## 總結與結論 * **Agent 的本質是工程封裝而非單純的演算法突破**：將 LLM 加上 `Function Calling` (工具)、`State Persistence` (記憶) 以及 `Control Loop` (迴圈) 即可打造出實用的自動化代理。 * **自然語言即程式碼 (NL-as-Code) 的開發典範**：利用 Claude Code 作為開發代理，架構師只需定義架構需求 (Requirements)、限制條件 (Constraints) 與非功能性需求 (如環境變數、持久化)，而無需處理底層語法細節。 * **狀態管理與文脈壓縮是 Agent 系統的設計核心**：採用滑動視窗 (Sliding Window)、定期狀態快照 (State Snapshot) 以及滾動摘要 (Rolling Summary) 策略，是解決 LLM Token 上限限制並保持長期上下文連貫性的最佳實踐。 * **微型應用的伺服器無伺服器化 (Serverless) 替代性**：雖然本文使用 VPS 加上 `systemd` 部署，但此類無狀態 (Stateless，依靠外部 JSON 儲存) 的 Webhook 機器人，未來也非常適合遷移至 Cloud Run 或 AWS Lambda 配合 DynamoDB 來達成更佳的雲端原生架構。

--- tags: [實戰教學, AI工具, 工作流, Agent架構] date: 2026-06-16 read: false source: "2026-06-16T093808+0800-How to Actually Build Your First AI Agent Using Claude (Full Course).md" original_title: "How to Actually Build Your First AI Agent Using Claude (Full Course)" --- # How to Actually Build Your First AI Agent Using Claude (Full Course)  原始來源與檔名：2026-06-16T093808+0800-How to Actually Build Your First AI Agent Using Claude (Full Course).md --- ## NAPKIN | 餐巾紙 ### 餐巾紙公式 > Agent = Claude + System Prompt + Automated Sequence _Agent 與普通 Chatbot 的差別在於，它能自動執行一連串的工作流，而不需要人類在每個步驟間進行手動的批准或串接。_ ### 一句話 > 透過明確的連續性指令與系統提示，任何人都可以不寫一行程式碼，使用 Claude 建立自動化處理研究、檔案批次作業和排程任務的 AI 代理。 ### 餐巾紙草圖 ``` [使用者輸入] | v +------------+ (不需手動介入) | 步驟 1 | --------+ +------------+ | v +------------+ | 步驟 2 | --------+ +------------+ | v +------------+ | 步驟 3 | +------------+ | v [最終產出] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 非技術人員如何利用現有的工具建構能自動化工作的 AI Agent？ * **核心答案**: 透過 Claude 的 Projects, Cowork 以及 /schedule 功能，設定清晰的連續性系統指令，即可建立無需編寫程式碼的 AI 代理。 * **論證結構**: 案例教學型 (Step-by-step Tutorial) ### 章節骨架 1. **什麼是 AI Agent**: 從繁瑣的手動操作到自動化連續執行。 2. **三種無程式碼 Agent**: 聊天 (Chat)、檔案處理 (File) 與排程 (Scheduled) 代理。 3. **實作一：研究到文章 Agent**: 透過 Projects 設定流程寫長文。 4. **實作二：檔案處理 Agent**: 透過 Cowork 進行批次摘要與彙整。 5. **實作三：排程晨間 Agent**: 每日定時總結電子郵件與日曆事件。 6. **迭代與優化法則**: 透過修正規則、提供範例與定期回饋來強化模型。 7. **五個實用 Agent 點子**: 內容重製、競品追蹤、客戶引導、會議總結與發票處理。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ``` [Claude 具備連續推理與執行能力] --> [透過嚴格且結構化的 Prompt 將步驟串聯] --> [AI 可自行在各階段傳遞上下文並執行多步驟任務] --> [非技術人員也能建立高效率的 AI Agent 業務工作流] ``` ### 關鍵證據 1. **Chat Agent 實證**：只需要一個包含五個步驟 (研究、切入點、大綱、撰寫、審閱) 的 Prompt，就能從一句簡單的輸入，自動產出具備特定格式的完整文章。 2. **File Agent 實證**：透過 Claude Cowork 存取本地端資料夾，下達單一 Prompt 即可讓其自動讀取數十份 PDF、萃取重點並輸出獨立檔案與總結檔，省下數小時人工時間。 3. **Scheduled Agent 實證**：結合 `/schedule` 指令，能在不開啟電腦或手動輸入的情況下，自動於早上 7 點觸發讀取信件、生成草稿與彙整日曆的流程。 ### 隱形假設與邊界條件 * **隱形假設**: * 使用者擁有存取 Claude 進階功能 (如 Projects, Cowork 存取本地目錄, Schedule 指令) 的版本或權限。 * 目標任務可以被明確拆解為線性的、具備清晰判定標準的邏輯步驟。 * Claude 的上下文長度與指令遵循能力足以支撐這些連續性的任務而不會發生「指令遺忘」或「幻覺」。 * **邊界條件**: * 當任務需要高度跳躍式創意且無法標準化時，此類固定工作流 Agent 的產出品質會下降。 * 對於需要串接外部私有 API、複雜資料庫查詢等操作，純無程式碼的 Claude 環境可能無法直接勝任。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 文章主要集中在個人生產力與單一 Agent 應用，較少探討多個不同職能的 Agent 如何在複雜專案中互相配合 (Multi-Agent System 的協作機制)。 * **知識連接**: 與軟體工程中的 CI/CD (持續整合/持續部署) 流水線概念高度相似，都是將原本需要手動審查與點擊的節點，轉換為程式化自動傳遞的流程。 * **行動觸發**: 列出日常工作中最耗時、最具重複性的三項任務，立刻為其中一項撰寫 System Prompt 並在 Claude Projects 中建立第一個專屬 Agent。 ### 跨域映射 * 在 **軟體工程**，這叫 **Pipeline / Workflow Automation (流水線自動化)** * 在 **企業管理**，這叫 **SOP (標準作業程序) 的全數位化與執行** --- # How to Actually Build Your First AI Agent Using Claude (Full Course) (Architectural Deep Dive) ## 前言/背景 這篇文章探討了在沒有程式設計背景的情況下，如何利用 Claude 內建的進階功能（如 Projects, Cowork, Schedule）來建構自動化的 AI 代理 (AI Agent)。作者旨在打破「建立 Agent 必須寫程式」的傳統技術壁壘，展示了只要定義好清晰的多步驟 Prompt 工作流，就能將繁瑣的、需要人類反覆確認的狀態轉移，轉化為端到端的全自動化處理系統。 ## 章節詳細總結 ### 什麼是 AI Agent (In Normal Words) 作者在開篇清楚指出，Chatbot 和 Agent 的根本區別在於 **執行流程的連續性與自治性**。 * **傳統 Chatbot 互動模式**：使用者需要介入每一個工作步驟 (例如：下指令研究 -> 人類閱讀與確認 -> 下指令寫大綱 -> 人類審核 -> 下指令寫草稿)。這在架構上是一個分散的、需人工觸發的狀態機 (State Machine)。 * **Agent 代理模式**：透過預先定義好的嚴格狀態轉換，自動依序完成上述所有步驟。使用者只需下達初始指令「研究並完成文章」，Agent 會自動將上一個步驟的輸出無縫作為下一個步驟的輸入，最終直接交付完成品。 ### 三種無程式碼的 Agent 架構 (The 3 Types of Agents) 作者總結了三種利用 Claude 現有工具可實現的代理架構設計： 1. **Type 1: Chat Agent (Claude Projects)**： * 這是一種基於**狀態預設與上下文邊界**的代理。透過配置一個強大且結構化的 `System Prompt`，預先定義好多步驟的工作流，確保代理在特定場景下的行為一致性。 2. **Type 2: File Agent (Claude Cowork)**： * 這是一種具備**本地 I/O (輸入/輸出) 權限**的代理。賦予 Claude 讀取和寫入本地檔案系統的權限，使其能進行大批量的資料處理與轉換。 3. **Type 3: Scheduled Agent (Cowork + /schedule)**： * 這是一種具備**定時觸發機制 (Cron-like Job Scheduler)** 的代理。結合本地應用程式的存取權限與時間觸發器，實現完全無人值守 (Unattended) 的背景自動運行。 ### 實戰 1：從研究到撰寫文章的代理 (The Research-to-Article Agent) 這個代理展示了如何撰寫一個高內聚、低耦合的系統提示 (System Prompt)，將複雜的認知任務分解。 * **架構決策 (Why)**：為了避免大語言模型在步驟間停頓並等待使用者回覆，作者特別在指令中加入了關鍵參數配置：`execute the following workflow automatically without stopping for approval between steps`。 * **Pipeline 步驟設計解析**： 1. `STEP 1 - RESEARCH`：定義輸入來源（網頁搜尋），提取統計數據與專家見解。 2. `STEP 2 - ANGLE`：設定思考與推理模式（尋找能挑戰既有認知的切入點）。 3. `STEP 3 - OUTLINE`：建立輸出結構（引言、5-7 個帶標題的段落、具體數據、CTA）。 4. `STEP 4 - WRITE`：設定格式與語氣的強約束限制（最多3句一段，零廢話，需包含具體數字）。 5. `STEP 5 - REVIEW`：加入自我審查機制 (Self-Reflection Pattern)，要求模型在輸出前確認是否每一段都有新資訊，確保符合品質標準。 ### 實戰 2：檔案批次處理代理 (The File Processing Agent) 此代理展示了 MapReduce 風格的批次處理 (Batch Processing) 和資料聚合 (Data Aggregation) 能力。 * **工作流邏輯與配置**： 1. **Map 階段**：遍歷指定的 `/Downloads` 目錄中的所有 PDF 檔案。對每個檔案萃取摘要 (最多 5 個 bullet points) 與識別出 3 個最重要的行動項目 (Action Items)。 2. **I/O 寫入操作**：在 `/Summaries` 目錄將每個分析結果儲存為同名但附檔名為 `.md` 的檔案。 3. **Reduce 階段**：處理完畢後，執行資料聚合，將所有摘要合併為一個主檔案 `all-summaries.md`，並強制要求依日期排序。指令中明確要求 `Process all files. Do not stop between files.`，確保批次作業不會中斷。 ### 實戰 3：排程晨間代理 (The Scheduled Morning Agent) 展示了如何將 Agent 深度整合進使用者的日常營運，成為背景服務。 * **排程參數**：設定 Cron 頻率為 `Every weekday at 7:00am`。 * **任務整合細節**： 1. **跨系統整合**：讀取 Gmail (昨日下午 5 點後的信件) 與 Google Calendar (今日行程)。 2. **Triage (分流) 邏輯**：將信件精確分類為 `ACTION REQUIRED`, `FYI ONLY`, `CAN IGNORE`。 3. **預先運算 (Pre-computation)**：針對 `ACTION REQUIRED` 的信件預先生成回覆草稿。 4. **結構化輸出**：最終將彙整結果以嚴格的 Markdown 結構輸出至本地 `/Daily` 目錄下的 `morning-brief-[today's date].md`。 ### 讓 Agent 持續進化的三個法則 (How to Make Your Agents Better) 作者強調了 Prompt Engineering 中的「持續優化」原則，這與機器學習中的模型微調 (Fine-tuning) 和軟體工程中的重構 (Refactoring) 有異曲同工之妙。 1. **修正法則 (The Correction Rule)**：遇到錯誤或不如預期的輸出時，不要只手動修改結果，而是將錯誤轉化為新的約束規則 (Constraint) 更新到 System Prompt 中。例如從抱怨「太長」改為具體規則「Each summary must be under 100 words」。 2. **範例法則 (The Example Rule)**：這即是架構上的 Few-Shot Prompting 實踐。將優質的產出範例作為 Ground Truth 匯入 Project 的知識庫中。具備具體範例基準的代理，效能遠勝於僅有抽象指令的代理。 3. **回饋循環 (The Feedback Loop)**：建議每週進行一次系統性的審查 (Review)，審視代理處理邊界案例 (Edge Cases) 的表現並更新指令。 ## 總結與結論 * **連續性與工作流是 Agent 的靈魂**：不要將大語言模型僅當作一問一答的工具，透過強制的 Pipeline 階段劃分（如 Research -> Outline -> Write -> Review），能大幅提升複雜認知任務的完成度與穩定性。 * **無程式碼 I/O 與排程釋放 LLM 潛力**：透過工具賦予 LLM 本地檔案系統的存取權限與定時觸發能力，能立刻將 LLM 從「對話視窗」中解放出來，轉變為實用的背景批次處理系統 (Background Worker)。 * **必須內建防呆與自我審查機制**：在架構複雜的 System Prompt 時，為了避免無人值守狀態下產出崩潰，必須在流程末端加入如 `STEP 5 - REVIEW` 的自我審查節點，並建立清晰、可量化的品質標準。 * **將 Prompt 視為需持續重構的程式碼**：我們應將 System Prompt 視為一種宣告式程式碼 (Declarative Code)，遵循持續迭代的原則（如 Correction Rule, Feedback Loop），不斷加入具體的限制條件以處理各種 Edge Cases。

--- tags: [工作方法, 軟體工程, 程式碼規範, 系統架構] date: 2026-06-16 read: false source: "2026-06-16T094218+0800-7 Coding Patterns I Stole From Senior Engineers.md" original_title: "7 Coding Patterns I Stole From Senior Engineers" --- # 7 Coding Patterns I Stole From Senior Engineers  原始來源與檔名：2026-06-16T094218+0800-7 Coding Patterns I Stole From Senior Engineers.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 高手程式碼 = (提早返回 + 業務命名 + 邊界隔離 + 嚴謹狀態 + 分離決策) × 易讀性 _好程式碼不是炫技，而是為了讓下一個接手的人減少猜測。_ ### 一句话 > 資深工程師的程式碼之所以無聊，是因為他們把複雜性鎖在清晰的邊界內，而不是讓它蔓延到別人的大腦裡。 ### 餐巾纸草图 ```text [複雜的外部世界 / API] | (3. 邊界隔離) V [清晰的內部領域模型] |--- (4. 嚴謹的狀態設計) |--- (2. 具備業務意義的命名) V [業務決策邏輯] <--- (5. 分離決策與行動) ---> [副作用/執行行動] | (1. 提早返回，過濾無效狀態) V [清晰且有用的錯誤日誌] (6. 錯誤對下一個人有用) ``` ## ROUND 1: SKELETON | 骨架掃描 **"這本書在說什麼"** * **核心問題**: 資深工程師到底如何寫出能夠在生產環境中存活的程式碼？ * **核心答案**: 他們不是使用更酷炫的語法，而是撰寫「無聊」的程式碼，不給下一個人製造麻煩。 * **論證結構**: 案例型與對比型 (比較菜鳥寫法與老手寫法的差異)。 ### 章節骨架 1. **提早返回 (Return Early)**: 移除無效路徑，讓核心邏輯浮現。 2. **業務命名 (Business Meaning)**: 用業務意義命名，而非技術載體。 3. **邊界隔離 (Boundaries)**: 不讓外部系統定義內部資料形狀。 4. **嚴謹狀態 (Invalid States)**: 用型別讓無效狀態難以存在。 5. **分離決策與行動 (Separate Decisions)**: 抽離決策邏輯，使其易於單元測試。 6. **有用的錯誤 (Useful Errors)**: 錯誤訊息是寫給除錯者和系統看的。 7. **優化審查 (Optimize for Diff)**: 專注於 PR 的易讀性與可回溯性。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text 程式碼主要成本在於閱讀與除錯 --> 複雜且模糊的結構會增加認知負擔 --> 資深工程師透過一系列模式 (提早返回、業務命名、防禦型狀態等) 降低認知負擔 --> 因此程式碼更穩定且易於維護 ``` ### 關鍵證據 1. **巢狀條件災難**：多層 if 判斷隱藏了真實的業務邏輯，提早返回可立即曝露錯誤路徑。 2. **外部依賴蔓延**：如果直接使用第三方 API 的欄位名稱（如 `response.data.user_name`），一旦 API 改變，整個程式碼庫都會崩潰；而映射層能控制爆炸半徑。 3. **狀態不一致**：將所有欄位設為 Optional 只是掩耳盜鈴，建立如 `DraftUser` 和 `SavedUser` 的嚴謹型別，能在編譯期就攔截邏輯漏洞。 ### 隱形假設與邊界 * **隱形假設**: * 程式碼的閱讀次數遠大於撰寫次數。 * 測試與可維護性比少寫幾行程式碼更重要。 * **邊界條件**: * 在極小型的拋棄式腳本中，嚴格的邊界隔離可能是過度設計 (Over-engineering)。 * 某些特定的樹狀遍歷或解析器確實需要巢狀結構。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 雖然提到了這些模式，但並未深入探討如何將這些模式與團隊的 CI/CD 或程式碼審查自動化工具結合。 * **知識連接**: 這些模式與《Clean Code》(無瑕的程式碼) 和《Domain-Driven Design》(領域驅動設計) 中的防腐層 (Anti-corruption Layer) 概念高度一致。 * **行動觸發**: 下次提交 PR 之前，檢查是否將重構與新功能混在一起，並確保自己撰寫的錯誤日誌能讓半夜起床值班的同事一眼看懂。 ### 跨域映射 * 在 **領域驅動設計 (DDD)**，這叫 **防腐層 (Anti-corruption Layer)**（對應邊界隔離）。 * 在 **函數式編程 (FP)**，這叫 **純函數與副作用分離**（對應分離決策與行動）。 --- # 7 Coding Patterns I Stole From Senior Engineers (Architectural Deep Dive) ## 前言/背景 這篇文章探討了資深工程師與初階開發者在撰寫程式碼時的根本差異。作者指出，資深工程師之所以優秀，並非因為他們掌握了更多酷炫的語法或框架技巧，而是因為他們專注於「減少驚嚇 (Reduce surprise)」。他們透過七種實用的程式碼設計模式，將系統的複雜度封裝在可控的範圍內，使程式碼在面臨需求變更或生產環境事故時，依然具備極高的可維讀性與可維護性。 ## 章節詳細總結 ### 1. 提早返回 (Return Early) 替代巢狀條件迷宮 初階開發者經常習慣將業務邏輯寫在層層遞進的 `if` 條件中，導致核心邏輯深陷在巢狀結構內，這被稱為「條件迷宮 (Conditional Mazes)」。資深工程師則採用「Guard Clauses (守衛子句)」，優先排除無效或錯誤的執行路徑，讓正常的業務邏輯 (Happy Path) 能夠在最外層清晰展開。 **技術細節與程式碼展示：** 與其撰寫層層嵌套的結構，不如提早拋出錯誤： ```typescript async function updateUserProfile(userId: string, input: ProfileInput) { const user = await getUser(userId); // 提早返回：過濾無效狀態 if (!user) throw new NotFoundError("User not found"); if (!input.email) throw new ValidationError("Email is required"); if (!user.canEditProfile) throw new ForbiddenError("User cannot edit profile"); // 核心業務邏輯直接浮現 return saveProfile(user.id, input); } ``` **架構意義**：這符合「Fail Fast」原則。在處理生產環境事故時，工程師能依序且直觀地理解「什麼情況會阻止程式執行」，而不需要在腦海中維持複雜的條件狀態樹。 ### 2. 基於業務意義命名 (Name the Business Meaning) 許多開發者習慣使用 `data`、`result`、`payload` 或 `item` 這些反映技術載體的詞彙來命名變數。然而，當系統變大時，這些詞彙會失去上下文，導致語義不清（例如 `activeUsers` 可能包含被停權但未刪除的用戶）。 **技術細節與程式碼展示：** ```typescript // 菜鳥寫法：只表達了這是一個結果與狀態 const result = await getData(id); if (result.status === "active") { await process(result); } // 資深寫法：表達了領域模型與業務意圖 const subscription = await getSubscription(subscriptionId); if (subscription.isBillable) { await chargeSubscription(subscription); } ``` **架構意義**：良好的命名本身就是一種防禦性設計，它創造了「誤用的摩擦力」。在微服務架構或領域驅動設計中，使用 Ubiquitous Language (通用語言) 能夠確保技術實作與業務邏輯的緊密對齊。 ### 3. 建立外部混亂的隔離邊界 (Boundaries Around External Chaos) 第三方 API、Webhook 或是外部資料庫的結構是不穩定的。如果讓外部系統的資料結構（如 `response.data.user_name`）直接滲透到核心業務邏輯或 UI 層，那麼第三方系統的任何變更都會引發全域性的重構。 **技術細節與程式碼展示：** 資深工程師會在系統邊界建立映射層 (Mapping Layer) 或防腐層 (Anti-corruption Layer)： ```typescript // 建立邊界，將外部的蛇形命名與不穩定結構，轉換為內部控制的領域模型 function mapBillingCustomer(response: BillingCustomerResponse): Customer { return { id: response.id, name: response.user_name, isBillable: response.status === "ACTIVE", planName: response.subscription?.plan_name ?? "Free" }; } ``` **架構意義**：「永遠不要讓你無法控制的系統，來定義你能控制的系統的形狀」。這有效控制了爆炸半徑 (Blast Radius)，當第三方 API 升級或欄位變更時，只需要修改這個轉接器 (Adapter/Mapper) 即可。 ### 4. 讓無效狀態難以存在 (Make Invalid States Hard) 為了讓編譯器 (如 TypeScript) 不報錯，開發者常將所有屬性設為可選 (`?`)，這導致整個系統充滿了對 null 或 undefined 的猜忌與防禦性檢查。 **技術細節與程式碼展示：** 與其使用一個充滿 Optional 的泛用型別，不如誠實地建模不同的業務狀態： ```typescript // 定義不同生命週期的精確狀態 type DraftUser = { email: string; role: "admin" | "member"; }; type SavedUser = { id: string; email: string; role: "admin" | "member"; status: "active" | "disabled"; }; // 使用 Discriminated Unions 處理複雜狀態 type Payment = | { state: "pending"; id: string } | { state: "authorized"; id: string; authorizationId: string } | { state: "captured"; id: string; receiptId: string } | { state: "failed"; id: string; reason: string }; // 函數簽名直接要求特定的安全狀態 function sendReceipt(payment: Extract<Payment, { state: "captured" }>) { return emailReceipt(payment.receiptId); } ``` **架構意義**：這是「Parse, don't validate」理念的延伸。在型別系統層面消滅不合法的狀態組合，可以大幅減少執行期的 Bug (如對尚未授權的付款進行退款)。 ### 5. 分離決策與行動 (Separate Decisions From Actions) 將「判斷邏輯」與「副作用 (如資料庫寫入、發送 API、寄送 Email)」混在一起，會使得單元測試變得極其困難，因為你必須 Mock 大量的外部依賴。 **技術細節與程式碼展示：** 將決策抽離成純函數 (Pure Function)： ```typescript // 決策層：純函數，極易進行單元測試 function getRefundEligibility(invoice: Invoice): RefundEligibility { if (invoice.status !== "paid") return { allowed: false, reason: "Invoice is not paid" }; if (invoice.refundedAt) return { allowed: false, reason: "Invoice is already refunded" }; if (invoice.amount <= 0) return { allowed: false, reason: "Invalid refund amount" }; return { allowed: true }; } // 行動層：只負責執行決策與副作用 async function refundInvoice(invoiceId: string) { const invoice = await getInvoice(invoiceId); const eligibility = getRefundEligibility(invoice); // 調用決策 if (!eligibility.allowed) throw new ValidationError(eligibility.reason); await paymentProvider.refund(invoice.paymentId); await markInvoiceRefunded(invoice.id); } ``` **架構意義**：這是命令與查詢職責分離 (CQRS) 和六角架構的核心精神。將核心業務規則與副作用隔離，不僅提高了可測試性，也讓規則更具可重用性。 ### 6. 提供有用的錯誤訊息 (Make Errors Useful) 拋出 `{ "message": "Something went wrong" }` 是一種災難，因為它對後端除錯、前端狀態展示和維運監控都毫無幫助。文字訊息是給人類看的，系統應該依賴結構化的代碼 (Codes)。 **技術細節與程式碼展示：** 優秀的錯誤響應應該包含結構化的錯誤碼與上下文： ```json { "code": "USER_EMAIL_ALREADY_EXISTS", "message": "A user with this email already exists.", "details": { "field": "email" }, "requestId": "req_8f91a2" } ``` 在後端日誌中： ```typescript // 記錄充分的上下文，但絕不記錄敏感資訊 (如密碼、信用卡號) logger.warn("Refund rejected", { invoiceId, customerId, reason: eligibility.reason, requestId }); ``` **架構意義**：這增強了系統的可觀測性 (Observability)。透過RequestId 串聯分散式追蹤 (Distributed Tracing)，讓排查生產環境問題從「通靈猜測」變成「精準定位」。 ### 7. 針對差異優化，而非演示 (Optimize for the Diff, Not the Demo) 初階工程師追求在本地端把功能跑通就好，經常提交包含重構、新功能、修正 Bug 以及格式調整的「巨大 PR (Pull Request)」。資深工程師知道程式碼審查 (Code Review) 和回滾 (Rollback) 的成本，因此他們優化的是「Diff 的可讀性」。 **技術細節與程式碼展示：** 將巨大的變更拆分為微小且獨立的 PR 序列： * PR 1: 無行為變更的欄位重命名 * PR 2: 新增退款資格的邏輯與測試 (不影響現有流程) * PR 3: 將退款邏輯接入計費流程 * PR 4: 更新儀表板 UI **架構意義**：這不僅是 Git 工作流的最佳實踐，更是維持高頻率部署與降低回滾風險的核心。將基礎設施重構與業務邏輯變更分開提交，能保證 CI/CD 流程的順暢與安全。 ## 總結與結論 * **建立領域防腐層**：外部 API 與資料庫定義是極度不穩定的。在系統邊界建立映射層 (Mapping Layer) 可以將第三方依賴的爆炸半徑控制在單一轉接器內，保護核心業務邏輯的純潔性。 * **運用型別系統推演狀態機**：不要濫用 Optional 屬性。利用型別系統（如 Discriminated Unions）精確描述領域模型在不同生命週期下的狀態，這能將絕大多數的運行時錯誤 (Runtime errors) 提前在編譯期攔截。 * **擁抱純函數以提升可測試性**：將業務「決策 (Decision)」與「副作用 (Action)」嚴格分離。這不僅消除了大量複雜且脆弱的 Mock 測試，更能確保核心業務規則能夠被獨立、充分地驗證。 * **可觀測性從錯誤設計開始**：錯誤處理不是事後補救，而是 API 設計的一環。利用標準化的錯誤碼與夾帶 RequestID 的上下文日誌，是建構高可用分散式系統的基石。

--- tags: [工作流, Prompt工程, AI工程, 工具技巧] date: 2026-06-16 read: false source: "2026-06-16T093908+0800-Codex-maxxing treating Codex like an operating loop.md" original_title: "Codex-maxxing treating Codex like an operating loop" --- # Codex-maxxing: treating Codex like an operating loop (將 Codex 視作營運迴圈)  原始來源與檔名：2026-06-16T093908+0800-Codex-maxxing treating Codex like an operating loop.md --- ## NAPKIN | 餐巾紙 ### 餐巾紙公式 > Agent = 持續迴圈 (Operating Loop) + 外部記憶 (Disk Memory) + 視覺驗證 (Visual Review) _摒棄一次性對話，將 AI 轉化為具有狀態、可驗證且持續運作的非同步工作引擎。_ ### 一句話 > 不要只把編程 Agent 當作高級自動補全，而應該將其打造成具備外部記憶、能自我驗證且持續迭代的工作迴圈 (Operating Loop)。 ### 餐巾紙草圖 ```text [ One-shot Prompting ] [ Operating Loop ] User -> Prompt -> Code User -> Task (End) | v +-------------+ <---- Memory (Disk/Notes) | Agent | +-------------+ ----> Visual/Browser Review | v [ Verification ] (Tests, Lint, Build) | +-> Done / Await Approval ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 如何最大化 AI 編程助手 (如 Codex) 的價值，而不是僅停留在「代碼生成」的表面？ * **核心答案**: 將 Codex 視為一個持續的「工作迴圈 (Operating Loop)」，透過系統提示詞賦予其持久記憶、視覺驗證與自動化跟進的能力。 * **論證結構**: 案例與指令型 (提供具體的 System Prompt 並解釋其設計理念)。 ### 章節骨架 1. **工作模式的轉變**: 從一次性對話走向持續的工作迴圈。 2. **自定義指令實踐**: 將迴圈思維寫入 System Prompt。 3. **持久化與驗證**: 強調硬碟記憶與多維度結果驗證。 4. **實戰應用與背書**: 透過開源專案與專家觀點佐證迴圈的強大。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 隱形假設與邊界條件 * **隱形假設**: * AI 模型具有足夠的上下文理解能力，能閱讀與修改本地硬碟檔案，並利用瀏覽器等工具進行自我驗證。 * 使用者熟悉如何切割任務，並能夠管理多個同時運作的 Agent 迴圈。 * **邊界條件**: * 當任務屬於極短篇、一次性的代碼諮詢時，建立複雜的迴圈可能過於冗餘。 * 若系統不具備提供本地文件讀寫或瀏覽器查閱權限 (沙箱過於嚴格)，此工作流將難以實現。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **知識連結**: 這與軟體工程中的 CI/CD 流水線 (持續整合/持續交付) 以及控制理論中的「閉環反饋系統 (Closed-loop feedback system)」概念高度吻合。 * **深層洞見**: 未來的 AI 不是「問答機」，而是「非同步工作者」。我們的工作將從「編寫代碼」轉移到「設計與管理迴圈」。 * **行動呼籲**: 立即將文章中提供的 Prompt 貼入你所使用的 AI Agent (如 Cursor, Codex 等) 的自定義指令中，並開始建立你的第一個持久化工作迴圈。 --- # Codex-maxxing: treating Codex like an operating loop (Architectural Deep Dive) ## 前言/背景 多數開發者在使用 AI 編程代理 (Coding Agents) 時，仍將其視為「高級的自動補全」或「一次性的問答機器 (One-shot chat box)」，這大幅低估了 AI 的潛力。本文旨在探討一種名為 "Codex-maxxing" 的模式，即將 Codex (或其他相似的 AI 代理) 轉變為一個**持久的、具備驗證能力的營運迴圈 (Durable Operating Loop)**，從根本上改變人機協作的工作流。 ## 章節詳細總結 ### 從一次性問答到持續營運迴圈 作者指出，若只要求 AI 生成代碼便停止，會浪費大量的上下文價值。更好的模式是將代理視為持續執行的工作流： * **持久的對話串 (Persistent threads)**：針對長期的工作流保持對話狀態。 * **基於磁碟的記憶 (Disk-backed notes)**：將記憶寫入實體檔案，便於審查與比對 (Diff)。 * **視覺化審查 (Browser surfaces)**：利用瀏覽器介面進行真實的視覺檢查，而非僅依賴文字反饋。 * **輕量化互動 (Small HTML apps)**：當需要互動時，產出小型的 HTML 應用而非死板的 Markdown。 * **後續自動化與驗證 (Automations & Verification)**：設立清晰的驗證閘門 (Verification gates)，在標記完成前自動進行測試與檢查。 一個高價值的 Codex 執行緒應該能夠：檢查本地應用程式、打開靜態產物、檢視渲染出的簡報、監控 PR (Pull Request)、更新專案筆記，並最終帶著「可審查的結果」返回。 ### 核心自定義指令 (System Prompt) 深度解析 作者提供了一段配置於 Settings > Personalization > Custom instructions 的指令，其架構設計極具參考價值： #### 1. 持續性工作 (Ongoing Work) * 要求代理優先使用持久對話串。 * **狀態外掛 (State Externalization)**：明確指示將上下文寫入具體文件 (如 `TODOs`, `AGENTS.md`, 決策記錄等)。這解決了 LLM 記憶力有限與對話窗格過長的缺點。 * 強調**磁碟檔案才是單一真相來源 (Source of Truth)**，代理應主動更新這些檔案，而非只在對話歷史中提供資訊。 #### 2. 產物設計 (Artifacts) * **優先產出可檢查的結果 (Inspectable outputs)**。 * 對於輕量互動，預設生成單一且自包含的 `index.html` (包含 CSS/JS)，除非絕對必要，否則避免引入複雜的後端架構。 * 根據任務特性靈活使用多種載體 (Markdown, CSV, PDF, Storybook, Streamlit 等)，並在創建視覺產物後，主動使用應用內瀏覽器打開與驗證。 #### 3. 瀏覽器與電腦操作 (Browser/Computer Work) * **範圍界定 (Scoping)**：對代理的工具權限做精細控制。 * 一般靜態或本地服務使用預設 Browser。 * 需要登入狀態或 Cookie 時才使用 Chrome。 * 僅在無法透過 Shell、檔案或瀏覽器解決時，才動用 Computer Use (GUI 級別控制)。 * 要求代理必須以「檢查渲染結果 -> 修復最小問題 -> 重新檢查」的閉環方式進行。 #### 4. 迴圈與驗證 (Recurring Loops & Verification) * **自動化心跳 (Heartbeat)**：當需要輪詢或監控時，代理應建議帶有明確停止條件的自動化流程。 * **安全邊界**：代理可草擬回覆與行動，但**未經明確批准，不得採取公開或帳戶級別的操作**。 * **嚴格的驗證閘門**： * 禁止僅因為「修改了檔案」就宣告成功。 * 必須執行最小單位的驗證：如測試 (Tests)、代碼格式化 (Lint)、類型檢查 (Typecheck)、建置 (Build)、冒煙測試 (Smoke test) 或截圖。 * 向開發者報告「改變了什麼」、「如何驗證的」以及「殘留風險」。 ### 開源與實戰應用背書 作者提到他利用這套 "Looping" 工作流來維護包含 OpenClaw、Veritas Kanban 等開源專案，並為客戶開發解決方案。在任何特定時間點，他都有超過十幾個迴圈在 Codex 中並行運作。此外，OpenAI 的 Jason Liu 亦曾強調：「你不再應該只是提示 (Prompting) 你的編程代理，你應該設計迴圈 (Loops) 來提示你的代理。」 ## 總結與結論 * **系統架構思維轉移**：開發者應從「微觀代碼生成者」升級為「宏觀系統編排者 (System Orchestrator)」，設計並管理具備自主驗證與狀態更新能力的 AI 迴圈。 * **記憶體外掛化 (Disk-as-Memory)**：LLM 的對話上下文不可靠，必須將系統決策、待辦清單和專案狀態實體化為本地檔案 (如 `AGENTS.md`)，這有助於版本控制與跨執行緒共享記憶。 * **測試與驗證左移 (Shift-Left Verification)**：AI 代理不該只對代碼修改負責，還必須對代碼的正確性與視覺渲染負責。將 CI 流水線的思維 (Lint, Build, Test) 融入代理的 Prompt 中，能大幅降低錯誤率。 * **操作權限的最小化原則 (Least Privilege)**：在 Prompt 中嚴格區分不同工具 (Browser vs Chrome vs Computer Use) 的使用場景，並設置安全卡控 (需人工批准才能進行公開操作)，是防範 AI 幻覺引發災難的關鍵架構決策。

--- tags: [工作流, AI工具, 工作方法, PDCA] date: 2026-06-16 read: false source: "2026-06-16T093736+0800-怎么在 AI 时代，超越你身边的大多数人？.md" original_title: "怎么在 AI 时代，超越你身边的大多数人？" --- # 怎么在 AI 时代，超越你身边的大多数人？  原始來源與檔名：2026-06-16T093736+0800-怎么在 AI 时代，超越你身边的大多数人？.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > 競爭力 = AI 工具 × PDCA (記錄 + 分析 + 改進) _在大家都擁有相同 AI 工具的時代，差異化來自於你能否利用 PDCA 迴圈持續迭代並優化你的 AI 工作流。_ ### 一句话 > 真正的優勢不在於裝了多少 AI 工具，而在於使用像 flowtrace 這樣的工具將 AI 互動過程自動化記錄並透過 PDCA 持續迭代優化。 ### 餐巾纸草图 ```text [ AI 工具 ] ---基線---> [ 一般使用者 ] | +---[ 自動記錄 (flowtrace) ] | v [ 分析/可視化 ] -> [ 發現盲點 ] -> [ 介入改進 ] -> [ 再次執行 ] -> (超越多數人) ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 在大家都使用 AI 工具的時代，如何才能真正超越身邊的大多數人？ * **核心答案**: 透過 PDCA 方法（計畫、實踐、檢查、改進）配合 AI 原生紀錄工具（如 flowtrace）持續迭代優化自己的工作流。 * **論證結構**: 演繹與案例結合（先點出問題，再提出 PDCA 理論，接著介紹 flowtrace 落地方法，最後用開源項目評估作為實戰案例）。 ### 章節骨架 1. **問題浮現**: 工具普及成為新基線。 2. **理論基礎**: PDCA 是優化流程的核心。 3. **落地痛點**: 傳統 PDCA 斷在「懶得記錄」。 4. **解決方案**: flowtrace 自動記錄與可視化。 5. **實戰案例**: 評估開源項目的流程優化。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text AI 工具大眾化 --> 每個人都在同一起跑線 --> 單純增加工具數量無法產生壁壘 --> 必須優化工具使用的流程 --> 傳統 PDCA 缺乏自動記錄難以維持 --> flowtrace 解決了記錄痛點 --> 實現 AI 工作流的可追溯與可介入 --> 持續優化產生競爭優勢 ``` ### 關鍵證據 1. 豐田流水線與 AI 工作流的本質相同：皆為可重複且可優化的流程。 2. flowtrace 提供透明、可追溯、可介入、可復用的特性，完全對應 PDCA 的「檢查」與「改進」步驟。 3. 作者以「開源項目評估」為例：從初期的單純看文檔，透過視覺化分析發現缺少健康度檢查，進而改進工作流，成功排雷（高 star 但無維護的項目）。 ### 隱形假設與邊界 * **隱形假設**: * 使用者的 AI 任務是具備重複性或可流程化的（如選股、寫報告），而非單次創意發想。 * 使用者具備一定程度的問題分析能力，能夠看懂流程圖並發現缺失的環節。 * **邊界條件**: * 當任務是一次性、毫無規律的閒聊時，此工作流優化的價值較低。 * 依賴於底層 AI 模型（如 Claude Code）支援外部 skill 工具鏈的整合。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 文章主要關注個人效率的提升，未深入探討團隊協作中如何共享與標準化這些固化的 traces（例如建立企業級的最佳實踐庫）。 * **知識連接**: 與 DevOps 中的 CI/CD 管線（Pipeline）極為相似。flowtrace 本質上就是將人類的思維工作流「管線化」，並加入可視化的 Debug 機制。 * **行動觸發**: 挑選一個日常最常重複的 AI 對話任務，安裝 flowtrace 跑一次完整記錄，並嘗試修改其中一個節點來觀察產出變化。 ### 跨域映射 * 在 **軟體工程**，這叫 **Pipeline As Code (管線即程式碼) 與 Continuous Improvement** * 在 **精實生產 (Lean Production)**，這叫 **Kaizen (持續改善)** --- # 怎么在 AI 时代，超越你身边的大多数人？ (Architectural Deep Dive) ## 前言/背景 文章探討了在 AI 工具日益普及、工具本身已經成為「新基線」的時代，個體如何保持競爭力。核心觀點指出，堆疊工具數量並不能帶來實質的躍升，真正的護城河在於「持續迭代優化工具使用流程」的能力。為了解決傳統 PDCA（Plan-Do-Check-Act）在實踐中常因缺乏詳細記錄而中斷的痛點，作者介紹了一款名為 `flowtrace` 的 AI 原生工具，展示如何透過自動化記錄、可視化與節點層級的可介入性，將工作流優化真正落地。 ## 章節詳細總結 ### 工具成為基線與 PDCA 的重要性 作者開篇指出，當所有人都能使用 AI 工具時，工具的取得便無法成為優勢。要拉開差距，必須依賴 PDCA 循環（計畫、實踐、檢查、改進）。 * **本質洞察**：AI 工作流本質上與豐田（Toyota）流水線上的製造流程一樣，都是**可重複的流程**。只要是流程，就存在優化的空間。 * **卡點分析**：大多數人在實踐 PDCA 時，並非卡在「分析」或「改進」，而是卡在第一步的「記錄」。與 AI 的優秀對話工作流往往因為缺乏文檔化而流失，導致無法進行後續的追溯與優化。 ### AI 時代的 PDCA 落地工具：flowtrace 為了解決記錄的痛點，作者引入了開源項目 `flowtrace`。這是一個將 AI 互動過程自動轉化為可復用紀錄（trace）的工具。 * **安裝與配置**： ```bash git clone https://github.com/AIScientists-Dev/flowtrace.git cd flowtrace ./scripts/install.sh ``` 安裝後，將 `make-trace` skill 複製到 AI 工具的 skills 目錄，透過輸入 `/make-trace` 即可觸發記錄。 * **核心特性 (Architectural Mapping)**： * **透明 (Transparency)**：每一步產出皆為獨立文件，非隱藏於對話紀錄中。 * **有據可查 (Traceability)**：結論可追溯至來源文件，確保核驗而非盲信。 * **可介入 (Intervention)**：修改單一節點時，**僅依賴該節點的後續任務會重跑 (Dependency-based execution)**，此機制類似於 Makefile 或現代構建系統（如 Bazel）的增量編譯，大幅節省 Token 與時間。 * **可復用 (Reusability) 與會進化 (Evolution)**：工作流固化後，更換輸入參數即可重複執行。 ### 實戰案例：評估開源項目流程優化 作者展示了如何利用 flowtrace 優化「開源項目調研」的工作流，完美演示了 PDCA 循環： 1. **第一步：執行與記錄 (Do & Record)** * 使用指令 `/make-trace 记录这调研开源项目的工作流`。 * AI 自動將工作流拆解為：`克隆項目 -> 閱讀 README -> 分支讀取核心文檔/示例/競品 -> 彙整筆記`。 * 工具啟動本地伺服器，將此流程**可視化為節點圖 (DAG, Directed Acyclic Graph)**，固化為可復用的 trace。 2. **第二步：分析 (Check)** * 套用該 trace 到第二個項目。AI 依照可視化圖譜逐節點執行並產出文件。 * 在覆盤過程中，作者透過流程圖發現**盲點**：原本的工作流缺乏對項目「健康度 (Health Metrics)」的檢查（如 star 數、issue 處理率、更新頻率）。 3. **第三步：改進 (Act)** * 作者透過命令列介入，要求在 trace 中新增「體檢項目健康度」的節點。 * 套用至第三個項目時，成功排雷：發現一個擁有 34.8k Stars 但積壓 800+ 且三個月未更新的「殭屍」明星項目。 ## 總結與結論 * **自動化取代手動日誌 (Automated Traceability)**：在高度自動化的 AI 協作中，手動記錄 Prompt 或對話流是不切實際的。必須依賴如 `flowtrace` 這種底層攔截與記錄機制，將過程自動生成為可視化的 DAG (有向無環圖)。 * **增量式執行 (Incremental Execution)**：flowtrace 的「可介入」特性展現了優秀的系統設計。修改流程中的某個節點，僅觸發下游依賴節點的重新執行，這在處理耗時或高成本的 AI 任務時，能有效降低 Token 消耗並提升除錯效率。 * **工作流即程式碼 (Workflow As Code)**：個人工作者應開始採用 DevOps 的思維，將日常重複性任務視為 Pipeline。透過持續的 Debug 與優化，讓 AI 工作流累積成為個人專屬的基礎設施與護城河。

--- tags: [系統架構, 系統工程, 後端架構, 效能優化] date: 2026-06-16 read: false source: "2026-06-16T094226+0800-OpenTelemetry Arrow The Bold Bet That Could Redefine Telemetry Pipelines.md" original_title: "OpenTelemetry Arrow The Bold Bet That Could Redefine Telemetry Pipelines" --- # OpenTelemetry Arrow: The Bold Bet That Could Redefine Telemetry Pipelines  原始來源與檔名：2026-06-16T094226+0800-OpenTelemetry Arrow The Bold Bet That Could Redefine Telemetry Pipelines.md --- ## NAPKIN | 餐巾紙 ### 餐巾紙公式 > 遙測資料 (Telemetry) + 欄位化儲存 (Columnar Data / Apache Arrow) = 極致壓縮率 + 原生計算優化 _將遙測資料從「巢狀物件」轉為「欄位化關聯資料」，以換取在傳輸與計算上數十倍的效能提升。_ ### 一句話 > OTel-Arrow 將遙測資料視為「資料」而非「物件」，透過 Apache Arrow 格式與 Rust 原生引擎，從根本上解決了現代遙測管線的傳輸與計算瓶頸。 ### 餐巾紙草圖 ```text [傳統 OTLP 管線] SDK(物件) -> 序列化 -> 網路 -> 反序列化 -> Collector(物件) -> 資料庫格式 (高 CPU、高頻寬消耗、多次轉換) [OTel-Arrow 管線] SDK -> OTAP (Apache Arrow 欄位格式) ----------------------> 分析引擎/儲存 (零拷貝、高壓縮、SIMD 優化計算、全程一致的格式) ``` ## ROUND 1: SKELETON | 骨架掃描 **"這篇文章在說什麼"** * **核心問題**: 現代可觀測性系統面臨的最大挑戰已不再是「收集」遙測資料，而是如何高效地「移動」與「處理」這些海量資料（日誌、指標、追蹤）。 * **核心答案**: OpenTelemetry Arrow (OTel-Arrow) 專案透過結合 Apache Arrow 與 OTAP 協議，將遙測資料欄位化，並發展出 Rust 原生的資料流引擎，實現巨幅的壓縮與計算效能提升。 * **論證結構**: 案例與對比型 (點出傳統痛點 -> 提出架構變革 -> 數據佐證 -> 未來發展)。 ### 章節骨架 1. **沒人討論的問題**: 遙測資料移動成本極高 2. **Apache Arrow**: 從互通性轉向計算優化 3. **OTAP 協議**: 串流遙測協議的誕生 4. **殺手級功能**: 透過多重壓縮大幅降低頻寬 5. **量化成效**: ServiceNow 生產環境驗證 6. **Phase 2 演進**: Rust 引擎與 Thread-per-core 模型 7. **核心理念**: 遙測是資料，而非軟體物件 8. **優勢總結**: 網路、運算、生態系全面升級 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 論證鏈 ```text 遙測資料量爆炸且充滿重複性 --> 傳統 OTLP 將其視為巢狀物件處理，導致大量序列化與網路成本 --> Apache Arrow 提供記憶體欄位佈局與零拷貝特性 --> 開發 OTAP 協議結合 gRPC 與 Arrow IPC --> 實現高達 15x-30x 的壓縮率與 30-70% 頻寬節省 --> 催生純 Rust 的 OTAP 資料流引擎，徹底改變觀測管線底層架構 ``` ### 關鍵證據 1. **ServiceNow 生產環境驗證**: 實機部署結果顯示 OTel-Arrow 相較於原本的 OTLP，顯著降低了基礎設施成本。 2. **壓縮表現數據**: 達到 15 倍至 30 倍的壓縮率，並且傳輸頻寬節省 30% 到 70%。 3. **Phase 2 架構選擇**: 採用 Rust 實現 Thread-per-core 引擎，以極小化跨執行緒的同步開銷並支援 SIMD 向量運算。 ### 隱形假設與邊界 * **隱形假設**: * 接收端的下游系統（分析引擎、資料湖）能夠或即將能夠原生支援 Apache Arrow 格式，否則在終端仍需進行格式轉換。 * 開發與維運團隊能夠承擔 OTAP 引入的額外複雜性（如：字典狀態管理、Schema 演進）。 * **邊界條件**: * 如果系統的遙測資料量極小，引入 OTel-Arrow 的複雜度可能超過其節省的網路傳輸成本。 * 在缺乏 Rust / Arrow 生態系支援的遺留系統中，整合難度可能會大幅提升。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲點**: 雖然強調了計算效率，但較少著墨於舊有基礎設施遷移至 OTAP 過程中的相容性陣痛期以及除錯難度（因為資料變成欄位化的 Chunk，人類可讀性降低）。 * **知識連接**: 此架構高度呼應了「資料湖倉 (Lakehouse)」與「OLAP 資料庫 (如 ClickHouse)」的底層設計哲學，只是這次被應用到了「傳輸管線」上。 * **行動觸發**: 架構師應重新評估現有遙測管線的瓶頸；若網路頻寬與序列化佔用大量 CPU 資源，應開始 PoC 評估 OTel-Arrow 或將遙測管線的設計思維向「資料工程」靠攏。 ### 跨域映射 * 在 **資料庫領域**，這叫 **Columnar Storage (欄位式儲存)** * 在 **大數據分析**，這叫 **Vectorized Query Execution (向量化查詢執行)** ## STRUCTURE MAP | 全書結構圖 ```text [Telemetry Producers] | v +-------------------------------+ | OTel-Arrow Architecture | | | | [OTAP Protocol] | | - gRPC + Arrow IPC | | - Dictionary / Delta Encode | | | | [OTAP Dataflow Engine] | | - Rust Native | | - Thread-per-core | | - Zero-copy Processing | +-------------------------------+ | (15x-30x Compression) | (30%-70% Bandwidth saving) v [Analytical Engines / Lakehouse] (DataFusion, ClickHouse, etc.) ``` --- # OpenTelemetry Arrow: The Bold Bet That Could Redefine Telemetry Pipelines (Architectural Deep Dive) ## 前言/背景 現代雲端原生環境中，日誌、指標和追蹤等可觀測性資料呈指數級增長。收集資料已非難事，真正的挑戰在於**如何在各個子系統中「移動」與「處理」這些資料**。傳統的遙測管線在每個節點都會經歷昂貴的序列化、反序列化、資料拷貝與記憶體分配，導致大量 CPU 與網路頻寬浪費。本文深入探討了 OpenTelemetry Arrow (OTel-Arrow) 專案如何透過導入 Apache Arrow 欄位化格式與 Rust 原生執行引擎，從根本上顛覆遙測資料的傳輸與運算架構。 ## 章節詳細總結 ### 遙測系統的痛點與 Apache Arrow 的引入 遙測資料流經 SDK、Agent、Collector、Queue、Storage，每一步都在做重複的資料轉換。OpenTelemetry Arrow 提出了一個大膽的假設：**如果遙測資料從產生到消費，始終保持在高度優化的分析型格式中呢？** 為此，專案選擇了 **Apache Arrow**。相較於傳統遙測格式優化「互通性」，Arrow 專注於優化「計算」。它的核心特性包含： * **欄位化記憶體佈局 (Columnar memory layouts)** * **零拷貝資料交換 (Zero-copy data exchange)** * **SIMD 友善的處理機制** ### OTAP：開放遙測 Arrow 協議 為使 Arrow 適用於遙測傳輸，專案開發了 **OpenTelemetry Arrow Protocol (OTAP)**。這是一種基於以下技術棧的串流協議： ```text Apache Arrow IPC + gRPC = OTAP ``` OTAP 屏棄了傳統 OTLP 巢狀物件的設計，將遙測表示為具有外鍵關係的正則化欄位表。例如 Traces 變成了關係表結構： ```text SPANS ├── SPAN_ATTRS ├── SPAN_EVENTS ├── SPAN_EVENT_ATTRS ├── SPAN_LINKS └── SPAN_LINK_ATTRS ``` 這種分解在小規模看似複雜，但在大規模資料下極具效率。 ### 多維度壓縮：OTel-Arrow 的殺手級功能 網路傳輸是遙測平台最大的成本驅動因素。OTel-Arrow 使用多層次技術進行極限壓縮： * **字典編碼 (Dictionary Encoding)**：重複出現的值（如主機名稱、服務標籤）轉為指標參考。 * **資源去重 (Resource Deduplication)**：Resource 與 Scope 僅編碼一次，後續多次引用。 * **Delta 與 Quasi-Delta 編碼**：針對連續生成的 ID 或重複的屬性關聯，僅存儲「差值」。 * **欄位化佈局**：將相似型別的值在記憶體中連續存放，這使得前述的壓縮演算法發揮極致效能。 **效能數據驗證**： ServiceNow Cloud Observability 在生產環境部署後，數據顯示壓縮係數可達 **15 倍至 30 倍**（相較於未壓縮資料），並減少了 **30% 至 70%** 的網路頻寬。這意味著 100TB 的 OTLP 流量可以被大幅縮減，直接轉化為基礎設施費用的節省。 ### Phase 2：Rust 原生的 OTAP 資料流引擎 到了 2025 年，專案進入了更宏大的第二階段：建構圍繞 Arrow 的完整遙測執行平台。團隊選擇了 **Rust** 作為核心語言，看重其強大的記憶體安全性、無垃圾回收的零拷貝能力以及與 DataFusion 等 Arrow 生態系統的原生整合能力。 **架構決策：Thread-per-core 執行模型** 與傳統在執行緒池中最大化共用並行性的設計不同，OTAP Dataflow Engine 採用了極端的高效能系統工程設計： * 每一個 CPU Core 運行一個獨立的 Pipeline Engine。 * 極小化共享狀態（Shared State），跨執行緒之間的協調完全依賴「顯式的控制訊息 (Control Messages)」和無鎖佇列 (Queue-based communication)。 * 確保熱路徑 (Hot paths) 的隔離性與 CPU 快取局部性 (Cache Locality)。 ### 思維典範轉移：遙測是資料，而非物件 文章點出整個專案最重要的一句話：**「OTel-Arrow 認為遙測是資料 (Data)，而不是物件 (Objects)。」** 傳統將 Span 視為物件是為了「軟體抽象」；而將其視為 Record Batches 與 Vectors 則是為了「資料移動、儲存與分析」。這呼應了未來可觀測性將越來越像「資料工程 (Data Engineering)」。 ## 總結與結論 * **網路與基礎設施成本巨幅下降**：透過 Arrow 的欄位化特性與進階壓縮算法（字典、Delta），企業能以 30%-70% 的頻寬節省傳輸等量的遙測資料。 * **計算與序列化負載消除**：維持資料在分析型格式中流轉，避免了各個代理節點間無謂的物件序列化與反序列化，同時解鎖了 SIMD 與零拷貝的極速計算潛能。 * **無鎖架構的最佳實踐 (Thread-per-core)**：Rust 原生資料流引擎摒棄了共享狀態的並發模型，為高吞吐量遙測管線示範了「隔離熱路徑與訊息傳遞」的高效能架構模式。 * **與現代 Data 平台的無縫接軌**：直接產出 Arrow Record Batches，使得遙測資料能以近乎零轉換的成本，流向 ClickHouse、DataFusion 等支援 Arrow 生態系的現代資料湖倉。 * **架構師建議**：若您的系統正遭遇大規模日誌與指標的傳輸與計算瓶頸，應密切關注 OTel-Arrow 生態。但在導入時，需評估 OTAP 帶來的 Schema 管理與串流狀態管理的額外維運複雜性。

--- tags: [職場技能, AI技能, 工作方法, 效率工具] date: 2026-06-16 read: true source: "2026-06-16T093819+0800-2026 值得学的 12 项 AI 技能：别再乱追工具了，真正值钱的是能力.md" original_title: "2026 值得学的 12 项 AI 技能：别再乱追工具了，真正值钱的是能力" --- # 2026 值得学的 12 项 AI 技能：别再乱追工具了，真正值钱的是能力  # XRay 結構 - **核心論點**：學習 AI 的重點不在於盲目追逐和收藏工具，而在於「能否使用 AI 完成真實任務」。工具會不斷更迭，但解決問題的能力與框架會沉澱下來。 - **目標受眾**：希望提升工作效率、不知如何系統性學習 AI 的新手與一般工作者。 - **關鍵字**：Prompt Engineering, AI Workflow, AI Agent, RAG, Multimodal AI, AI-Assisted Development ## 12 項 AI 技能深度解析與架構 這 12 項技能被分為三個漸進的學習層次：基礎通用層、效率提升層、產品化層。 ### 第一層：所有人先學（基礎通用層） 這四項技能適用於所有職位（營運、內容、產品、開發），是使用 AI 的基石。 1. **提示詞工程（Prompt Engineering）**：本質是為 AI 搭建清晰的工作現場，而非背誦神祕咒語。核心公式為「背景 + 目標 + 素材 + 限制 + 輸出格式」。 2. **多模態 AI（Multimodal AI）**：跳脫純文字互動，學會讓 AI 處理圖片、截圖、表格、程式碼等多元資訊。例如透過介面截圖讓 AI 分析轉換率瓶頸。 3. **AI 工具組合（AI Tool Combinations）**：打破單點使用工具的習慣，建立成套的作業流程。例如結合大語言模型寫腳本、Notion 管理、Midjourney 製圖、n8n 自動化推送。 4. **持續學習與篩選（Continuous Learning & Filtering）**：面對快速變化的 AI 生態，建立每週 30 分鐘的更新系統。專注於模型更新、工具更新及應用案例，並嚴格限制測試數量，避免資訊焦慮。 ### 第二層：想提效再學（效率提升層） 這四項技能著重於減少重複勞動，打造自動化與高度客製化的工作環境。 5. **AI 工作流（AI Workflow）**：識別日常重複性動作（如收集資料、總結、發送），並利用 n8n、Make 等自動化工具串聯。從最簡單的單一流程（如每日新聞摘要推送）開始實作。 6. **RAG 檢索增強生成（Retrieval-Augmented Generation）**：解決大模型記憶限制與幻覺問題。讓 AI 在回答前先檢索指定的私有資料庫（如 FAQ、產品說明書），確保輸出的準確性與依據。 7. **AI 助手定制（Custom AI Assistants）**：透過預設系統提示詞（System Prompt），為自己配置具備固定人設與工作脈絡的 AI 助手（例如獨立開發助手），免去每次重新解釋背景的溝通成本。 8. **AI 視頻內容生成（AI Video Generation）**：理解影片生成的核心在於「腳本結構」（開頭鉤子、資訊節奏、結尾行動指令），而非特效。從讓 AI 拆解文字為分鏡腳本開始，再進行配音與剪輯。 ### 第三層：想產品化再學（業務變現層） 這四項技能更接近實際業務開發與商業應用，需要具體的真實場景支撐。 9. **AI 智能體（AI Agents）**：從單純的問答進化為「執行」。智能體能根據目標拆解任務、呼叫外部工具並處理多步流程（如 SEO 分析智慧體）。初期應聚焦於單一明確場景（如客服助理）。 10. **AI 輔助開發（AI-Assisted Development）**：利用 Cursor、Claude Code 等工具輔助建立產品原型（如落地頁、小型後台）。重點在於先學會拆解功能模組與資料流向，而非直接撰寫程式碼。 11. **模型管理與判斷（Model Management & Evaluation）**：培養根據任務特性選擇合適模型的評估能力。判斷何時使用低成本模型、何時需要強推理模型、或是需要本地模型以保護隱私，並建立自己的多模型測試基準。 12. **語音 AI 與數字人（Voice AI & Digital Humans）**：將內容生產輕量化，適用於標準化介紹、課程配音等重複性高的展示場景。重點在於認知其邊界，作為降低試錯成本的工具，而非萬能變現神器。 # Architectural Deep Dive 在架構設計層面上，這 12 項技能勾勒出一個從「單一節點操作」到「系統級協同」的演進路徑。 1. **資料與上下文管理（Context & Data Management）** 提示詞工程與 AI 助手定制，本質上是在處理 Session Level 的上下文邊界設定；而 RAG 則是架構級的外部記憶體擴充（External Memory Access）。RAG 透過向量資料庫或語意搜尋，將私有資料注入 LLM 的 Context Window，這要求工作者具備將非結構化文件轉化為可檢索結構的思維。 2. **流程編排與自動化（Orchestration & Workflow Automation）** AI 工具組合與 AI 工作流對應到軟體工程中的 Pipeline 與 Orchestration 概念。使用者從原本的人工呼叫 API（手動切換工具），轉變為透過 n8n/Zapier 建立 Event-Driven 的自動化流程。這涉及輸入源（Triggers）、中介資料處理（Transformations/LLM Nodes）以及終端輸出（Actions）的串接設計。 3. **自主執行單元（Autonomous Executable Units）** AI Agent 代表了系統複雜度的躍升。相較於靜態 Workflow，Agent 具備動態規劃（Planning）與工具呼叫（Tool Use/Function Calling）能力。設計 Agent 時，需要嚴格定義其 System Prompt（系統邊界）、可用 Tools 的輸入輸出規範，以及錯誤處理（Error Handling）機制，這已經是微型服務架構的初步雛形。 4. **解耦思維（Decoupling Strategy）** 在影片生成或輔助開發中，作者強調「先寫腳本再加特效」或「先拆解功能再寫程式碼」。這體現了軟體工程中的「關注點分離（Separation of Concerns）」與「先設計後實作（Design before Implementation）」的架構思維。將邏輯層（腳本/功能模組）與表現層（畫面/程式碼實作）解耦，能大幅提升 AI 輔助生成的成功率與可維護性。 # 總結 本篇文章提供了一個極具實用價值的 AI 技能樹，將看似零散的工具收斂為以「任務」為核心的能力框架。對於個人或企業而言，導入 AI 的關鍵不在於追求最新潮的模型，而在於能否建立一套具備高內聚（單一任務目標明確）、低耦合（工具可彈性替換）的工作流架構，並透過持續學習機制進行迭代。

--- tags: [開發工具, ClaudeCode, MCP, 插件, 開發工作流] date: 2026-06-16 read: false source: "2026-06-16T093628+0800-Claude Code 高阶用法：10 个插件搭起完整开发工作流.md" original_title: "Claude Code 高阶用法：10 个插件搭起完整开发工作流" --- # Claude Code 高阶用法：10 个插件搭起完整开发工作流  ## 1. 核心概念與痛點 (XRay) * **核心痛點**：原生的 Claude Code 存在跨 Session 無記憶、無法實時連網、無法進行瀏覽器測試、缺乏安全門檻等問題。 * **解決方案**：透過掛載各類 MCP (Model Context Protocol) 插件，為開發者建構包含思考、測試、Code Review 到部署的「一條龍」完整開發環境。 * **關鍵機制**：插件生態系 (ClaudePluginHub, Anthropic Marketplace)，運用 MCP 伺服器擴展 Claude 的上下文邊界與執行能力。 ## 2. 系統架構與技術深度剖析 (Architectural Deep Dive) 本篇介紹了 10 種關鍵的 Claude Code 插件，從架構層面來看，它們分別補足了 LLM 在開發流程中的不同短板： ### 2.1 自主執行與自動化 (Autonomous Execution) * **Ralph Loop (自主編程代理)**：實作 `stop-hook` 模式，允許 Claude 執行長時間、多任務的自動化編程 Session。其機制是接收 PRD 後啟動循環 (Loop)，逐一拾取任務、實作並 Commit，每個子任務完成後重置 Context，避免 Context Window 污染。 ### 2.2 上下文注入與數據抓取 (Context Injection & Web Extraction) * **Context7 (實時文檔注入器)**：按需查詢 MCP 伺服器，將 Next.js、React 等框架的最新 API 文件實時注入 Claude 的 Context 中，從根本上解決 LLM 訓練資料過期導致的 API 幻覺 (Hallucination) 問題。 * **Firecrawl**：解決非結構化網頁資料抓取的問題。它具備 JavaScript 渲染能力，能將動態網頁轉換為 LLM 友好的乾淨 Markdown 或結構化 JSON，支援全站爬取與網站結構映射。 ### 2.3 測試與除錯環境整合 (Testing & Debugging Integration) * **Playwright MCP**：賦予 Claude 直接操作本地 Chrome 瀏覽器的能力。開發者可透過自然語言驅動 UI 測試，LLM 可接管具備登入態 (Login Session) 的瀏覽器，進行動態行為捕捉。 * **Chrome DevTools MCP**：突破靜態分析限制，讓 Claude 獲取真實瀏覽器的 Runtime 狀態（Network Requests、Console Errors、Performance Metrics），實現基於真實 DevTools 數據的深度除錯。 ### 2.4 安全與代碼審查 (Security & Code Review) * **Security Guidance (AI 代碼安全護欄)**：在每次檔案編輯 (Edit) 之前攔截並執行安全掃描，檢測 9 種高危漏洞（如 Command Injection、XSS、`eval()`、Pickle 反序列化等），在 Runtime 層面阻斷危險代碼寫入。 * **Code Review (多智能體並行審查)**：採用 Multi-Agent 架構，並行拉起多個專門 Agent（測試、類型檢查、錯誤處理、程式碼品質等），針對 PR 輸出附帶 Confidence Score 的結構化審查報告。 ### 2.5 外部系統與設計工具對接 (External Systems & Design Tools) * **Figma MCP**：直接讀取 Figma 檔案的真實數據結構（Frame、Components、Layout Data）而非依賴截圖，提升 UI 轉代碼的精準度。 * **Frontend Design**：透過 Prompt Engineering 與特定 Skill 配置，引導 Claude 做出更具視覺辨識度的設計決策，避免 AI 生成 UI 的同質化現象。 * **Linear**：將 Issue Tracker 直接整合進終端機，允許在 Terminal 內完成狀態更新與任務拆解，實現 Context Switching 的最小化。 ## 3. 實踐與部署建議 * **漸進式掛載**：由於每個外掛都會在 Context Window 內增加工具定義 (Tool Definitions)，掛載過多會拖慢回應速度。建議遵循「按需加載」原則。 * **基礎三件套配置**： 1. **長期記憶系統** (如 MemClaw)：維持跨 Session 的架構與決策記憶。 2. **實時資料獲取** (Context7 / Firecrawl)：確保 API 正確性。 3. **安全審查** (Security Guidance)：部署前的最後一道防線。

--- tags: [開發工具, AI工具, 自動化, 工作流] date: 2026-06-16 read: false source: "2026-06-16T093611+0800-Codex 这些功能你开了等于白装.md" original_title: "Codex 这些功能你开了等于白装" --- # Codex 这些功能你开了等于白装  原始來源與檔名：2026-06-16T093611+0800-Codex 这些功能你开了等于白装.md --- ## NAPKIN | 餐巾纸 ### 餐巾纸公式 > Codex 效能 = (正確權限設定 + 專案級 AGENTS.md + 插件生態) × 使用者引導能力 _Codex 不是開箱即用的工具，而是需要深度配置與指令調教才能發揮潛力的專屬 AI 開發助理。_ ### 一句話 > 如果你只把 Codex 當作單純的程式碼補全工具，而忽略了它內建的權限配置、專案上下文持久化與環境自動化功能，那就等於白裝了。 ### 餐巾纸草图 ```text [ 使用者意圖 ] | v +------------------+ | Codex AI Agent | | - AGENTS.md | | - Plan Mode | | - Auto review | +------------------+ | [ 插件生態 ] -----> Automation, Chrome, Computer Use | v [ 高效程式碼產出 & 專案重構 ] ``` ## ROUND 1: SKELETON | 骨架掃描 **"這本書/文章在說什麼"** * **核心問題**: 開發者如何避免只用到 Codex 的皮毛，從而真正發揮這款 AI 工具的強大代理效能？ * **核心答案**: 必須深入配置其隱藏選單，包括權限模式、思考深度、Plan Mode 以及全局 AGENTS.md。 * **論證結構**: 案例指南型（依重要性與使用頻率遞減排序）。 ### 章節骨架 1. **權限模式**: 拒絕 Full Access，推薦 Auto review 防護。 2. **速度與深度**: 依任務動態切換模型與思考深度。 3. **視覺化修改**: Annotate 截圖改 UI 提升 Feedback Loop。 4. **版控整合**: 內建 Git 介面與終端機雙管齊下。 5. **會話管理**: 善用 Fork (分支) 與 Archive (歸檔) 隔離上下文。 6. **專案規劃**: 大工程必須開啟 Plan Mode，避免方向偏航。 7. **全局配置**: 撰寫 AGENTS.md 實現跨會話的指令持久化。 8. **插件生態**: 善用 Image Gen、Chrome、Computer Use 擴展能力。 9. **定時任務**: Automation 實踐工作流程自動化。 10. **遠端遙控**: 透過手機版操控電腦，打破硬體限制。 ## ROUND 2: DISSECTION | 血肉解剖 **"憑什麼這麼說"** ### 隱形假設與邊界 * **隐形假设**: * 假設使用者具備基礎的軟體工程經驗，能判斷何時該用 AI 代理，何時該以人為介入為主。 * 假設 AI 在生成與理解複雜架構時，需要人類先期的框架引導（如 Plan Mode）。 * **边界条件**: * 預覽區 (Preview) 無法完全模擬真實瀏覽器環境（如 LocalStorage 失效時需於外部瀏覽器測試）。 * 高難度任務若未開啟 Plan Mode，AI 極容易在執行過程中因為上下文流失而偏航。 * 修改 `AGENTS.md` 本身不會自動觸發 Git Commit，必須手動執行版控。 ## ROUND 3: SOUL | 靈魂提取 **"還能怎麼用"** * **作者盲点**: 原文主要聚焦於個人單機開發流的設定，未深入探討 Codex 在大型微服務架構或多人協作（如解決 Git 衝突與權限控管）的應用。 * **知识连接**: 與 DevOps 領域的 IaC (基礎設施即代碼) 概念高度相似，`AGENTS.md` 本質上就是 AI 行為的宣告式設定檔。 * **行动触发**: 讀完後應立刻為目前的主力專案根目錄建立 `AGENTS.md`，並將 Codex 預設權限切換為 Auto review，確保安全與一致性。 ### 跨域映射 * 在 **開發維運 (DevOps)**，這叫 **Policy as Code (原則即程式碼)** * 在 **管理學與團隊協作**，這叫 **標準作業程序 (SOP) 預加載** --- # Codex 这些功能你开了等于白装 (Architectural Deep Dive) ## 前言/背景 本篇探討 AI 開發代理工具 Codex 的進階配置與架構最佳實踐。許多開發者僅將其作為簡單的程式碼補全工具，而忽略了其內建的狀態管理、權限控制以及跨會話的指令持久化機制。這篇文章解決的核心問題是：如何透過系統化的配置（如 `AGENTS.md`、Plan Mode、插件生態），將 Codex 從一個被動的問答機器人，轉變為深度理解專案上下文的自動化開發助理。 ## 章節詳細總結 ### 權限控制與執行沙箱 (Permissions & Sandboxing) * **權限模式選擇**：Codex 提供三種權限層級。預設為 `Default permissions`（高度攔截，每個檔案修改皆需確認）、`Auto review`（智能放行，高危操作才彈窗）以及 `Full access`（完全放行，AI 可自行決定所有操作）。 * **架構師視角**：在本地端執行 AI Agent 時，必須建立適當的防護網，推薦使用 `Auto review`。這類似於作業系統中的 UAC (User Account Control)，讓 AI 代理在處理日常檔案 I/O 時保持流暢，但在遇到刪除系統檔案或高危險操作時進行中斷防護。`Full Access` 雖然看似零中斷，但一旦 AI 產生幻覺（Hallucination）誤刪目錄或檔案，將導致無法挽回的災難。 ### 資源調度：模型選擇與推論深度 (Model & Inference Tuning) * **推論深度 (Reasoning Depth)**：可設定為 `low`, `medium`, `high`, `extra high`。深度越高，模型探索與驗證解法的能力越強，但會消耗極大 Token 與運算時間。 * **輸出速度 (Speed)**：分為 `Standard` 與 `Fast`。以 GPT-5.5 為例，`Fast` 模式會將生成速度提升 1.5 倍，但底層 Token 消耗會直接加倍。 * **策略建議**：對於單純的 CSS 樣式修改或小型 Utility 函式，使用 `low + Fast` 即可；若涉及核心業務邏輯重構、系統架構設計，則應切換至 `high + Standard` 以確保代碼品質。不盲目追求最新模型（如退回 GPT-5.4 處理低複雜度 CRUD 任務）是節省運算成本的最佳實踐。 ### 視覺反饋迴圈：Annotate UI 修改 * **機制**：透過 `Annotate` 標註工具，開發者可直接在 Codex 的預覽區框選 UI 元素並下達自然語言指令（如「顏色換成藍色」或「去掉這個按鈕」），Codex 會反向定位 DOM 或組件樹並直接修改源代碼。 * **邊界限制**：Codex 的預覽區並非完整的瀏覽器環境（例如 `localStorage` 或某些特定的 Web API 可能無法正常掛載）。 * **架構師視角**：在前端開發中，這種 Reverse Engineering (從渲染結果反推原始碼) 的能力極大縮短了從需求到落地的 Feedback Loop。但必須嚴守「開發區與測試區隔離」的原則，功能性與狀態驗證仍需在獨立的外部 Chrome 瀏覽器中進行。 ### 版本控制整合策略 (Git Integration) Codex 內建了兩種 Git 操作流，應根據場景靈活切換： * **CLI 終端機流（精準控制）**：透過快捷鍵 `Command + J` 喚出終端機，執行標準指令： ```bash git init . git add . git commit -m "Initial commit" ``` 開發者能確保對每個變更具有 100% 的掌控力，適合重構階段的精細 Commit。 * **GUI 自動化流（快速迭代）**：在環境資訊視圖中檢視未暫存變更，並直接填寫 Message 一鍵提交。適合瑣碎的樣式修改。若發現 AI 改動有誤，可直接透過對話框下達回退指令。 ### 狀態隔離：會話的 Fork 與歸檔管理 * **上下文隔離 (Context Isolation)**：當需要在同一專案測試兩種截然不同的技術方案時，Codex 提供了 `Fork` 機制以避免上下文污染： * `Fork into local`：複製對話上下文，但共用同一個實體檔案目錄。這意味著若需要代碼回退，仍需依賴 `git reset --hard <commit_hash>` 配合操作。 * `Fork into new worktree`：複製對話並建立全新的隔離目錄，確保兩條開發分支實體檔案完全互不干擾，類似 Git 原生的 Worktree 機制。 * **會話歸檔 (Archive)**：將不再活躍的會話移出主視圖，降低介面認知負荷，同時保留對話歷史以備未來需要追溯架構決策。 ### 系統性推演：Plan Mode 與平行執行 * **Plan Mode**：面對大型架構變更（例如將靜態 HTML 遷移至 Tauri/Electron 並引入 React 與 TypeScript 架構），禁止直接要求 AI 生成代碼。開啟 Plan Mode 後，Codex 會先進入「需求釐清階段」，主動詢問資料持久化方案、交付標準與測試策略。AI 會先搭建架構骨架，待開發者確認方向正確後，再逐步落地代碼。 * **非阻塞對話 (Side Chat)**：在主任務編譯或建置的長時間等待期間，可利用 Side Chat 詢問輕量級問題（如查詢環境變數設定），確保主執行緒任務不受干擾。 * **動態插斷 (Steer)**：若需緊急修正 AI 的開發方向，可透過 `Ctrl + Enter` 發送 Steer 指令，Codex 會將新條件併入目前的執行佇列中，無需等待上一階段完全結束。 ### 指令持久化：AGENTS.md 的全局架構 * **核心機制**：在專案根目錄建立 `AGENTS.md` 檔案，Codex 每次啟動新會話都會預先讀取並嚴格遵守其中的規則。這相當於將 System Prompt 與專案結合的持久化操作。 * **實戰範例**： ```markdown # 專案規範與邊界 - 每次完成功能修改後，必須執行自動測試並自動 git commit。 - 變數命名嚴格遵守 CamelCase，並需附帶完整的 JSDoc 註解。 - 本專案限定使用 React 18+ 與 TypeScript 5+。 - 所有後端 API 請求必須包含 Try-Catch 錯誤捕捉與 Retry 重試邏輯。 ``` * **架構師視角**：這是整個 Codex 生態中最具價值的特性，實踐了「開發規範即代碼 (Enforcement as Code)」。團隊不再依賴繁瑣的口頭交接或耗時的 Code Review 來抓基本排版與架構風格錯誤，AI 在產出代碼的生成階段就已自動套用這些邊界條件。 ### 擴展能力：插件生態、自動化與跨端遙控 * **Chrome 與 Computer Use**：授權 AI 取得虛擬滑鼠與瀏覽器的控制權，Codex 能自動查閱最新 API 線上文檔，甚至操作本機行事曆等應用程式。 * **自定義 Skill**：允許開發者將特定 Prompt 流程封裝為獨立指令。例如建立 `/rewrite` 技能，未來只需輸入指令，Codex 即會套用特定的 Markdown 改寫規則進行轉換。 * **自動化 (Automation)**：支援在特定環境（`local`, `worktree`, `chat`）定期執行背景任務。例如每日清晨自動執行 Lint 檢查、單元測試，並生成專案健康度報告。 * **跨端控制**：透過手機端 Codex 連動 PC 端，開發者可實現在手機上發送自然語言指令（如「清理系統無用行程」），並在電腦端背景執行，打破了物理裝置的開發限制。 ## 總結與結論 * **配置即能力 (Configuration is Capability)**：不要將進階 AI 開發工具視為「開箱即用」的黑盒魔法。沒有 `AGENTS.md` 注入上下文與規範，AI 產出的代碼將缺乏專案一致性且難以維護。 * **權限與風險控管並重**：AI Agent 具備直接修改與刪除本機檔案的強大能力，必須堅守 `Auto review` 模式與頻繁的版本控制（Git）底線，切忌在缺乏防護網的情況下授予 `Full access` 權限。 * **分而治之的隔離策略**：面對複雜系統重構，務必善用 Plan Mode 建立架構骨架，並透過 `Fork into new worktree` 建立沙箱環境，避免實驗性的 AI 修改污染主分支結構。 * **自動化工作流前置**：將團隊的 Coding Convention 與底層架構決策寫入 `AGENTS.md`，並結合 Automation 插件定期執行品質檢查，可大幅降低資深工程師在 Code Review 上的心智耗損。

--- tags: [開發工具, CLI, tmux, 系統架構, 開源專案] date: 2026-06-16 read: false source: "2026-06-16T094251+0800-I Quit tmux. Here’s What I Built Instead..md" original_title: "I Quit tmux. Here’s What I Built Instead." --- # I Quit tmux. Here’s What I Built Instead.  ## 核心論述 (Core Thesis) 傳統的終端機連線管理器（如 tmux 與 screen）因實作了完整的虛擬終端機，導致攔截與重編碼輸出時常破壞滑鼠事件、真彩顯示及替代螢幕（alternate screen）功能，且其記憶體架構會在系統崩潰時遺失所有歷史紀錄。為了解決這些痛點，作者開發了 `atch` —— 一款基於「透明位元組流傳遞」架構且具備「硬碟持久化日誌」的極簡工具，將介面渲染與控制權完全交還原生終端，並為現代 CI/CD 及 AI Agent 提供了極致穩定的自動化會話管理基礎。 ## XRay 核心結構 * **終端機會話管理的演進與架構包袱** * **GNU Screen 時代**：架構古老，不支援現代終端逃脫序列（Escape Sequences）與真彩（True Color），需要繁瑣的按鍵進入複製模式。 * **tmux 的「過度干預」痛點**： * 實作完整的虛擬終端機。 * 攔截並重新編碼所有輸出（尤其是滑鼠報告序列）。 * 記憶體內建回溯緩衝區（Scrollback buffer），伺服器重啟即遺失資料。 * 配置語法順序敏感，導致需要大量調校才能讓其表現得像「一般終端機」。 * **極簡主義的啟發 (abduco/dtach)**：符合 Unix 哲學，僅處理分離/重連（Session detachment）與純粹的位元組傳遞，但不支援歷史紀錄、會話列表或指令注入。 * **atch 的創新設計與架構決策** * **完全透明（Transparent Passthrough）**：不實作終端模擬，不做字串解析，保持原生 `$TERM` 環境不變。 * **滑鼠與繪圖原生支援**：因無干預機制，真彩、Sixel/Kitty 圖像協議、Vim/fzf 的備用螢幕（Alternate screen）均可直接相容運作。 * **硬碟持久化機制（Disk-Backed Logging）**：會話歷史紀錄不存放於記憶體，而是同步寫入磁碟，支援崩潰與重啟後的完整重播（Replay）。 * **對自動化工作流（Agentic/CI-CD）的賦能** * **標準輸入注入**：支援 `push` 指令將外部資料打入後台運行中的會話。 * **非同步部署**：透過 `start` 觸發長期任務後立即脫離，隨時跨 SSH 連線重連讀取完整日誌。 * **狀態探測**：透過 `current` 腳本化指令精準判斷運行狀態，提升 AI 代理與系統運維的後置偵錯能力。 ## 架構深潛 (Architectural Deep Dive) **1. 虛擬終端攔截 vs. 透明位元組流傳遞** tmux 的核心架構是建立在一個完整的「終端模擬器（Terminal Emulator）」之上。當內部程序（如 htop 或 vim）寫入資料時，tmux 會攔截這些資料，進行解析、過濾，並重寫終端逃脫序列（Escape Sequences），以便自我維護窗格佈局與回溯緩衝區。然而，滑鼠事件（Mouse reporting sequences）和特定游標控制（如切換到 Alternate screen）高度依賴底層協定，tmux 的二次編碼經常造成滑鼠滾輪行為與子程序的預期不符。 相反地，`atch` 沿用了 `dtach` 的設計模式，將自己定義為一個「透明管道（Transparent Pipe）」。它建立一個偽終端（Pseudoterminal, PTY），然後以零解析的方式，將原始的位元組流（Raw Byte Stream）原封不動地在 PTY 和物理終端機之間中繼轉發。這種不觸碰 `$TERM` 變數且不做編碼轉換的架構，使得複雜的終端序列（如 OSC、Sixel 圖像協定）能夠順利穿越代理層，將所有渲染邏輯交還給現代客戶端終端機。 **2. 硬碟持久化重播引擎 (Disk-backed Replay Engine)** 現有工具（screen、tmux、abduco）的 Scrollback history 皆分配於會話管理程序的堆積記憶體（Heap memory）中，若遇到 Kernel Panic、記憶體溢出（OOM）或伺服器重啟，該記憶體區段將被立即釋放，導致重要日誌永久遺失。 `atch` 改變了此狀態管理機制：所有流向 PTY 的位元組除了轉發給連接的客戶端外，還會被非同步附加（Append）至磁碟上的二進位日誌檔（預設寫入 `~/.cache/atch/<session>`，編譯期可設定最大 1MB 上限的環狀輪替）。當觸發 `atch attach` 重新連接時，系統的 I/O 引擎會優先開啟對應的本地日誌檔案，對客戶端進行「冷啟動重播（Replay）」，將任務歷史全數輸出到畫面上後，才切換到即時 PTY 串流。此機制保證了嚴苛重啟環境下的完全可觀測性（Full Observability）。 **3. 進階 IPC 與會話控制拓撲** 在 IPC（進程間通訊）層面，`atch` 使用 Unix Domain Sockets 進行會話註冊。每個會話對應一個 Socket 檔案，使得工具無需啟動全域的背景守護行程（Global Daemon），便能達到分散式的會話管理。 為支援 CI/CD 管道與 AI Agent 架構，`atch` 開放了 `push` 介面，這使得從外部行程將標準輸入（stdin）推入已掛載的 PTY 變得可能（例如：`printf 'command\n' | atch push session_name`）。結合 `atch start` 執行的立即分叉（Fork and detach），開發者能夠無縫結合 Webhook 架構，發起非同步任務，同時透過磁碟日誌實作多客戶端同時唯讀連接與事後 Forensic 分析。