我原本以為問題是模型，後來發現是交接：Ai-agent 架構拆解

我一開始以為 AI Agent 的問題是模型不夠強。

後來發現不是。

真正卡住我的，是每個 AI 都各自很強，但放進同一條工作流之後，彼此之間沒有共同語言。Claude 可以幫我做規劃，Codex 可以進 repo 改檔，Gemini 可以讀大量脈絡，Ollama 可以在本地做 fallback。單看每個工具都合理，但真的要讓它們接力工作時，問題就會冒出來：上一棒做了什麼，下一棒要怎麼接？任務做到哪個階段？哪些檔案可以碰？什麼時候要停？如果額度用完，要降級還是中止？

這些問題一開始看起來像使用習慣問題，但越用越覺得它其實是系統設計問題。AI 不是不會做事，而是做完之後很難被接續、驗證、降級與恢復。

所以我開始把 Ai-agent 從一組 prompt，整理成一層個人 AI operating layer。它不是要再做一個新的聊天機器人，而是把 Claude、Codex、Gemini、OpenAI、Ollama、Hermes 這些不同 AI runtime，收斂到同一套 adapter、skills、memory、scripts、handoff artifact 與 run-state schema 上。

這件事其實很貼近我在複雜軟體服務裡常遇到的問題。專案不是缺少單一能力，而是缺少穩定交接：需求從 PM 到設計會漏，設計到開發會失真，開發到驗收又會變成另一套語言。AI workflow 如果也複製這種斷裂，只會讓混亂變快。所以我做 Ai-agent，不是為了展示我有很多 AI 工具，而是想把工作流裡的脈絡、邊界、驗收和交接做成可治理的系統。

我想解的問題不是「怎麼讓一個模型更聰明」，而是這件事：

How to make many AI clients execute the same contract safely?

AI 變快之後，瓶頸不再只是生成能力，而是對齊、邊界、恢復、驗證與交接。

我先處理的不是模型，而是規則漂移

不同 AI 客戶端的能力其實很不一樣。Claude Code 很適合做 orchestration，Codex 適合 repo edits、terminal execution 與測試迴圈，Gemini 適合 large-context ingest，OpenAI / ChatGPT 適合工具化分析，Ollama 可以當成本地 fallback，Hermes 則比較像自主代理與 capability-fenced toolsets 的實驗場。

如果每個 AI 都各自維護一份完整規則，很快就會失控。同一條限制在 Claude 裡改了，Codex 裡忘記改；Gemini 的入口文件有一版，OpenAI 的入口文件又是另一版。表面上是多模型，實際上是多份規則開始漂移。

所以 Ai-agent 的入口設計採用 adapter pattern。每個 AI 有自己的薄 adapter，但真正共用的規則要往 shared core 收斂。

AI client adapter
  -> shared generated core
  -> skills/INDEX.md
  -> selected SKILL.md
  -> deterministic scripts
  -> artifacts / run-state / memory

root config 只描述各 runtime 的限制與能力。共通規則放在 shared core，可重複程序放進 skills，可驗證的機械動作交給 scripts。這樣做之後，維護 prompt 就不再只是改文字，而比較像在做 configuration management。

後來我把 AI 行為拆成三層

我原本也會直覺地把很多規則塞在入口 prompt 裡，因為這樣最方便。但入口越厚，後面越難維護。只要任務一複雜，AI 就會同時背著太多規則，最後不知道哪一條才是當下最重要的約束。

所以 .claude/ 的協作層被我拆成三段：

commands/   -> Intent layer
agents/     -> Decision layer
skills/     -> Execution layer

commands/ 只做很薄的路由。它不應該理解太多業務邏輯，只要把意圖導到正確入口。agents/ 負責比較像判斷層的工作，例如拆解任務、派工、判斷是否升級或停下。真正保存執行規則的是 skills/。

我後來覺得，skill 不應該只是 prompt template，而應該是一份 executable policy。每個 SKILL.md 都需要明確寫出它吃什麼 input、產出什麼 output、執行前要滿足哪些條件、可以用哪些工具、遇到什麼情況必須停止。

## Interface

### Inputs
### Outputs
### Preconditions
### Tool Permissions
### Stop Conditions

這個 Interface block 讓 AI 的行動邊界變清楚。AI 可以判斷，但不能無限制行動；agent 可以派工，但 skill 才是執行時真正的約束。一旦某個 skill 被選中，它的規則就應該高於 agent 的自由裁量。

上下文不能每次都全部載入

另一個踩過的坑是上下文膨脹。剛開始會很想讓 AI 讀越多越好，好像只要規則全塞進去，它就會比較穩。但實際上，規則越多，衝突越多，模型也越容易被不相干的內容干擾。

所以 Ai-agent 不會讓每次任務載入所有 skills。它先讀短索引，再選最小可用的 skill，最後只讀那份完整 SKILL.md。

read skills/INDEX.md
  -> select smallest relevant skill
  -> read selected SKILL.md
  -> execute by declared interface

我把 skills/INDEX.md 當成 routing table，SKILL.md 當成 policy module，scripts/ 當成 deterministic primitives。這個設計不是為了看起來乾淨，而是為了降低 context bloat、規則衝突與跨 AI 行為漂移。

記憶也需要分層，不然很快會污染

AI 記憶很容易被高估。只要什麼都想記，最後就會變成什麼都不可靠。短期任務狀態、terminal logs、commit hash、一次性的測試成功，如果全都進長期記憶，AI 之後反而會被雜訊拖累。

所以我把記憶分成 canonical source 與 runtime copy。

ObsidianBook / 90_System / AI共用記憶
  -> canonical source
  -> sync / generate
  -> .memoria/shared/
  -> runtime memory layer

ObsidianBook 是 source of truth，.memoria/shared/ 是各 AI 客戶端讀取的 runtime copy。這樣做的好處是，長期知識庫不會被短期工作流污染，各 AI runtime 又能讀到一致的工作記憶。

這裡真正重要的是 promotion policy。不是所有事情都應該被提升成 durable memory。真正值得留下的，通常是會改變未來 AI 行為的穩定偏好、可重用的踩坑、source-of-truth decision、專案交接，或已經穩定下來的 workflow contract。

長任務一定要能接回來

做 AI 工作流時，最痛的不是模型失敗，而是任務中斷後不知道怎麼接。尤其當一個任務跨過規劃、改檔、驗證、收尾，還可能中間遇到額度限制或工具失敗，如果狀態只存在聊天裡，下一個 session 幾乎等於重新來過。

所以 ops:sprint-agent 把長任務切成四個階段。

planning -> execution -> verification -> wrapup

每個階段的節奏固定下來：先讀契約，再讓 model-router 決定路由，接著宣告會碰哪些檔案，交給協作者執行，然後跑 gate，通過後 checkpoint，最後產生 handoff pack。

讀契約 -> model-router 決策 -> 宣告檔案 -> collab 執行 -> gate -> checkpoint -> handoff pack

這裡最重要的不是自動化有多炫，而是狀態有沒有落地。.memoria/hot/agent/run-state.json 會記錄 change、goal、phase、chunks、artifacts、events、declared_files、route_decisions、opus_budget、token_ledger、provider_status、downgraded 與 halted。

下一個 agent 不需要完整聊天紀錄。它只要讀 files、run-state 與 handoff，就應該知道任務走到哪裡、哪些 chunk 完成了、哪些檔案被宣告過、目前是否降級、是否因為 breaker 停下。

conversation is interface, not state.
run-state is resume point, not report.
events are observability, not final artifact.

這句話後來變成我設計 AI workflow 的核心判斷。對話只是互動介面，不應該承擔狀態儲存的責任。

能用 script 驗證，就不要靠模型感覺

如果每一層都能自己問 LLM，整套系統很快會變成 recursive agent soup。你會不知道到底是誰做了決策、誰改了狀態、誰應該為失敗負責。

所以 scripts/agent-pipeline.sh 被設計成 deterministic mechanics layer。它負責 init、resume、checkpoint、declare、event、route、chunk、gate、breaker、classify、on-fail，但它刻意不呼叫模型。

skill / agent      -> orchestration decisions
agent-pipeline.sh  -> deterministic mechanics
scripts/lib/*.sh   -> reusable primitives

LLM 做判斷與生成，scripts 做狀態變更、schema validation、gate 與 fallback classification。Gate 不相信模型自評，只相信可執行結果。這個分工看起來保守，但它讓整套工作流更像工程 pipeline，而不是一群 agent 在互相猜測。

多模型不是互聊，而是接力

我現在對 multi-agent 的看法比一開始保守很多。真正有用的不是讓多個 agent 自動聊天，而是讓它們交換可驗收的 artifact。

model-router.sh 做的事情不是永遠找最強模型，而是看任務性質選最高 CP 的路由。大量上下文先交給 Gemini，PM framing、寫作與一般規劃多數時候 Claude Sonnet 就夠，repo edits、tests、coding loop 適合 Codex Plus，高風險架構、root cause 或 final review 才值得短暫動用 Claude Opus；如果任務需要本地、隱私或零額度，就讓 Ollama 成為 fallback。

跨模型接力時，我不希望下一棒收到一整段聊天紀錄。它應該收到一個小而完整的 handoff artifact。

task: "one-line imperative task"
effort: low | medium | high
thinking: true | false
criteria:
  - "verifiable done criterion"
files:
  - "path/to/source-artifact"

做完之後，也不應該回一篇散文式心得，而是回一份 compact summary。

status: done | partial | failed
result:
  - "completed fact"
artifacts:
  - "created-or-modified-path"
gaps:
  - "remaining issue"

這樣下一棒不是在讀上一棒的情緒與推理，而是在讀任務、驗收標準、檔案與缺口。這才比較接近工程上的交接。

可靠性不是一直跑，而是知道何時停

很多 agent demo 看起來很厲害，是因為它會一直往下做。但真實工作流裡，可靠性不來自一直跑，而是來自知道何時不能再跑。

sprint-agent 裡我放了幾個防線。Planning 階段不能偷寫實作碼，verification 要優先跑 deterministic tests，失敗時不能一律降級，而是要先分類成 retry、switch、halt 或 surface。Opus 與 token 都要有 breaker；如果整段流程曾經 downgraded，wrapup 階段就不能省略高階模型複審。

這些設計不是為了讓系統看起來複雜，而是為了控制 AI workflow 的 blast radius。模型很會補洞，但也可能在錯誤方向補得更完整。所以停止條件必須是一等公民。

Autonomy without gates is unsupervised drift.

環境層和知識庫要分開

Ai-agent 和 ObsidianBook 的邊界也是後來慢慢整理出來的。Ai-agent 是環境層，負責跨機器同步 settings、skills、memory，以及那些在任何 repo 都可能用到的橫向 workflow。ObsidianBook 是應用層，負責知識庫、INGEST、COMPILE、WRITE、PUBLISH，以及 AI 共用記憶的 canonical source。

我的判斷方式很簡單。如果一個 skill 在任意 git repo 都能合理使用，例如寫文章、code review、commit、model routing，它應該放在 Ai-agent。如果它依賴 vault 裡的語義，例如 00_Inbox、30_Sources、20_Knowledge、概念、問題、知識圖譜，那就應該留在 ObsidianBook。

兩者之間只透過 vaults.json、to-obs、from-obs 做最小橋接。橋接可以讓對話寫入 vault，也可以讓 AI 唯讀搜尋 vault，但它不應該把整個 vault domain logic 搬進環境層。

我會把它放回交付現場看

Ai-agent 想解的不是「我有很多 AI 可以用」，而是把 AI 工作流裡最容易失控的部分工程化：上下文、能力、程序、狀態、交接、驗證、成本與停止條件。

如果 prompt collection 是第一階段，AI execution system 會是下一階段。真正有價值的不是讓模型一直往下跑，而是讓每次 AI 行動都能被定位、被限制、被驗證、被交接，必要時還能停下來。

我現在比較會把它放回交付現場看。複雜服務能不能做成，不只看某個人能力多強，而是看需求、設計、開發、驗收和維運之間有沒有清楚的契約。Ai-agent 只是把這套交付思維搬到 AI 工作流裡：把隱性的判斷寫成 skill，把容易失真的交接寫成 artifact，把看似順利的產出放進 gate 裡檢查。

所以我現在判斷一個 AI workflow 是否成熟，不會先看它用了多少模型，而會看幾件事：prompt 有沒有變薄，contract 有沒有變厚；agent 能不能判斷，但不會無限制行動；能不能用 script 驗證，而不是靠模型感覺；多模型是不是在接力，而不是互相聊天；狀態是不是落地，而不是藏在對話裡。

AI Agent 的下一步不是更會聊天，而是更像可治理的執行環境。

參考結構

Ai-agent
├── root AI adapters
├── docs: AI-ENTRYPOINTS / SKILL-CONTRACT / WORKFLOW-ARCHITECTURE / AGENT-HANDOFF-STANDARD
├── skills: INDEX.md + domain SKILL.md
├── scripts: agent-pipeline.sh / model-router.sh
├── schemas: run-state.schema.json
└── .memoria: shared / hot / cold