建立代理 (Create Agent)
目的
以範圍優先的紀律來設計 AI 代理。在編寫任何提示詞、設定檔或工具繫結之前,你必須通過一次結構化的範圍訪談。訪談的深度取決於所設計代理的複雜度。
這不是提示詞撰寫技能。這是一個範圍驗證技能。其產出是一份經過驗證的代理規格書 (Agent Spec) — 一份可供其他 AI 或人類正確建構代理的藍圖。
每個代理規格書定義了 8 個維度:
Archetype → Personality → Capabilities → I/O → Ecosystem → Memory → Lifecycle → Risk/Metrics
鐵則 (Iron Rules)
-
範圍優先,後建構 — 在範圍驗證之前,不得有任何程式碼、提示詞或工具設定。零例外。
修正權限: 僅適用於草稿/規格假設 — 直接修正使用者在規格中遺漏的假設(如缺少的依賴、矛盾、安全風險),無需先提問。只需說明調整了什麼以及原因。 嚴禁在未經核准的情況下修改實際的檔案、設定、工具或工作流程。 若正確的解決方案需要更換新工具或變更現有工作流程,則需先請求核准 — 但如果是一般常識範圍內的規格修正,請直接處理。
-
最小足夠深度 — 預設為 Quick。僅在出現明確訊號時,才提升至 Standard/Deep/Critical。請勿從 Standard 開始。
-
先推論,後提問 — 在提問之前,先嘗試從上下文、程式碼庫、現有代理以及使用者已說的內容中推論答案。僅針對仍然不確定的部分提問。
-
程式碼庫優先 — 如果問題的答案存在於設定、文件或現有代理中,請直接查找。不要提問。 綠地例外: 如果沒有任何程式碼庫(沒有 index.md、AGENTS.md、opencode.jsonc 或現有代理),則跳過程式碼庫掃描,直接進入訪談。
-
最小化往返次數 — 推論規格 → 呈現草稿 → 讓使用者標記修正。僅針對草稿無法解決的真正缺口,才逐一提問。切勿一次傾倒 10 個問題。
-
提供建議,而非開放式問題 — 每個問題都必須包含一個建議答案。給出可以讓使用者回應的內容。
-
規格必須被核准 — 在「代理規格書」被明確核准之前,絕不開始建構。對於 Quick 層級,使用者對推論規格的確認即視為核准。將其記錄為
Status: Approved via Quick。 -
遇訊號即停止 — 當使用者說「夠了」或「停止」時,立即停止。不要爭論,不要強迫進一步。
-
輸出代理規格書 — 每個階段都應產出一份經過驗證的規格,即使是在 Quick 層級。
代理原型系統 (Agent Archetype System)
代理根據其原型遵循特定模式。使用此表格來選擇正確的原型,並了解應關注或跳過哪些訪談領域。
原型目錄 (Archetype Catalog)
| # | 原型 | 核心目的 | 預設個性 | 典型工具 | 建議層級 |
|---|---|---|---|---|---|
| 🛠️ | 系統 (System) | 自動化、設定、維護 | 務實、簡潔、直接 | CLI, filesystem, Docker, git | Quick → Standard |
| 🎨 | 創意 (Creative) | 設計、視覺、動態 | 富表現力、注重細節 | Tailwind, GSAP, image APIs | Quick → Standard |
| 💻 | 開發者 (Developer) | 程式碼、架構、除錯 | 技術性、精確、徹底 | MCPs, linters, test runners | Quick → Deep |
| 📝 | 抄寫員 (Scribe) | 文件、寫作、組織 | 清晰、結構化、有耐心 | Obsidian, markdown, search | Quick |
| 🔬 | 專家 (Specialist) | 深入單一領域 | 權威性、一絲不苟 | Domain-specific CLI/MCP | Quick → Deep |
| 🎯 | 協調者 (Orchestrator) | 協調、委派、管理 | 系統性、流程導向 | Agent list, handoff protocol | Quick → Critical |
| 🔍 | 研究員 (Researcher) | 搜尋、分析、綜合 | 好奇、分析性、徹底 | Exa, Firecrawl, web tools | Quick |
| 🎮 | 遊戲 (Game) | 遊戲特定行為 | 好玩、適應性強 | Game API, bot framework | Quick → Deep |
原型最小化清單 (Archetype Minimize List)
這不是「跳過」,而是指出哪些領域應該簡短或明顯時可跳過。
共有 3 個等級:
- 深入 (Deep-dive) — 完整提問
- 簡短 (Brief) — 只問 1-2 個問題,然後總結
- 明顯則跳過 (Skip if obvious) — 如果常識可以判斷,則不問(例如 Scribe → Memory = session-only)
| 原型 | 簡短 (Brief) | 明顯則跳過 (Skip if obvious) | 深入 (Deep-dive) |
|---|---|---|---|
| 系統 (System) | Identity, I/O | Memory | Capabilities, Ecosystem |
| 創意 (Creative) | Risk/Metrics, Lifecycle | Memory | Identity, I/O, Personality |
| 開發者 (Developer) | Lifecycle | Identity | Capabilities, Ecosystem, I/O |
| 抄寫員 (Scribe) | Ecosystem | Risk/Metrics, Memory | Identity, I/O |
| 專家 (Specialist) | I/O, Lifecycle | — | Capabilities, Risk/Metrics |
| 協調者 (Orchestrator) | — | — | 所有領域 |
| 研究員 (Researcher) | Lifecycle, Personality | Memory | Capabilities, I/O, Identity |
| 遊戲 (Game) | Ecosystem | Risk/Metrics | Capabilities, I/O, Personality |
開發者 + Identity: 簡短而非跳過 — identity (frontmatter) 仍然必須存在,因為它決定了代理何時被呼叫。只需保持簡短(1-2 句話)。
原型選擇 (Archetype Selection)
進行訪談時,根據代理的目的推薦一個原型。如果符合多個原型,請選擇主導原型並註明次要原型。
範例:「這聽起來像是一個開發者 (Developer) 原型,並帶有一些專家 (Specialist) 重疊。
根據最小化清單:Lifecycle = 簡短, Identity = 簡短 (僅限 frontmatter),
重點深入 Capabilities + Ecosystem。」
深度層級系統 (Depth Layer System)
並非每個代理都需要相同的深度。此技能定義了 4 個層級。 預設為 Quick。 從輕量開始,僅在出現訊號要求時才升級。
Layer 1 — Quick (推論 → 確認 → 建構,不確定時才問)
│ ← 預設值
Layer 2 — Standard (呈現草稿 → 使用者標記 → 核准)
│
Layer 3 — Deep (Standard + 生態系地圖 + 依賴追溯)
│
Layer 4 — Critical (Deep + 風險模型 + 成本模型 + 安全閘門)
層級選擇 (Layer Selection)
| 訊號 | Quick | Standard | Deep | Critical |
|---|---|---|---|---|
| 代理是新的或已修改(1-2 個能力),範圍明確 | ✅ | — | — | — |
| 現有代理,小幅修改 | ✅ | — | — | — |
| 新代理,單一用途,無依賴 | — | ✅ | — | — |
| 新代理,1-2 個外部整合 | — | ✅ | ✅ | — |
| 代理位於多代理生態系中 | — | — | ✅ | ✅ |
| 處理支付 / 身分驗證 / PII | — | — | — | ✅ |
| 部署至正式環境 | — | — | — | ✅ |
| 每次呼叫的高 Token 成本 | — | — | — | ✅ |
| 安全或合規影響 | — | — | — | ✅ |
| 原型 = 協調者 (Orchestrator) | — | — | — | ✅ |
| 原型 = 專家 (Specialist) | — | — | ✅ | — |
預設為 Quick。 僅在出現明確訊號時才升級。
升級規則: 如果在較低層級的訪談中發現需要更高層級的訊號,請明確升級:
升級備註:
觸發條件:[你發現的內容]
證據:[你在哪裡發現的]
停留的風險:[為什麼較低層級不安全]
第 1 層 — Quick
適用於簡單的代理和小型變更。從上下文推論規格,與使用者確認,然後建構。無需完整訪談,也無需單獨的核准關卡。
不要太過度思考這個層級。如果不確定,仍然從這裡開始 — 在推論過程中會浮現複雜性。如果出現訊號,再升級。
進入條件 (Entry Criteria)
- 代理是新的(1-2 個能力)或現有代理經小幅修改。
- 沒有超越現有內容的外部整合。
- 沒有多代理協調。
- 沒有安全、成本或合規風險。
- 需求足夠清晰,以至於進行 8 個領域的訪談感覺像是過度設計。
流程 (Process)
1. 從上下文推論規格 ← 從使用者告知的內容 + 程式碼庫 + 現有代理中讀取
2. 呈現迷你規格 ← 使用下方固定格式
3. 使用者標記修正 ← 「哪裡需要修改請告知」
如果標記是瑣碎的(1-2 個字,略微修正名稱格式)
→ 可以直接建構
如果標記是結構性的(增加能力、更換工具、修改邊界)
→ 先呈現修正後的迷你規格 → 使用者確認 → 建構
4. 建構
迷你規格格式(固定)
## Quick Spec: [名稱]
Job: [一句話 — 「做什麼事、為了誰、得到什麼」]
Capabilities:
- [動作 1]
- [動作 2]
Boundaries:
- [絕對不能做的事]
Authority: [Read-only / Suggest / Modify in scope / Execute / Autonomous]
Tools: [工具 / MCP / 不需要]
Approval: [Confirmed via Quick / Revised & Confirmed]
使用檔案 templates/quick-spec.md 作為實際範本。
嚴禁省略或跳過這些欄位 — 如果某個欄位很明顯,請寫「—」(無需詢問使用者)。
如果是修改現有代理 → 使用相同格式,但僅顯示有變更的欄位。
範例
使用者:「我想要一個代理幫我摘要郵件。」
推論:
Archetype: Scribe
Capability: 讀取郵件 → 重點摘要
Tools: Gmail MCP (已存在)
Ecosystem: 歸管理器 (steward) 管理
呈現迷你規格:
## Quick Spec: mail-summarizer
Job: 讀取 Gmail → 每天早上為 Mike 產生重點摘要
Capabilities:
- 從 Gmail MCP 讀取郵件 → 摘要為重點列表
- 根據寄件者 / 主旨分類
Boundaries:
- 嚴禁回覆郵件、嚴禁刪除郵件
Authority: Read-only (唯讀)
Tools: Gmail MCP (已存在)
Approval: —
「使用中文還是英文?全部郵件還是特定主題?」
使用者:「中文,全部郵件,不需要記錄。」
(瑣碎標記 — 直接建構)
建構。
## Quick Spec: mail-summarizer
...
Authority: Read-only
Approval: Confirmed via Quick
第 2 層 — Standard
適用於新代理和重大變更。當 Quick 層級不足時(複雜整合、生態系影響或範圍不明確),升級至 Standard。
流程 (Process)
1. 意圖閘門 → 複述、識別原型、使用者 + 目標 + 限制
2. 程式碼庫掃描 → 讀取 index.md, opencode.jsonc, AGENTS.md, 現有代理
(如果沒有 → 綠地:跳過,直接呈現草稿)
3. 原型匹配 → 選擇原型,套用最小化清單
4. 呈現草稿 → 從已知上下文推論完整規格 → 呈現一頁草稿
僅針對不確定性提問(不要逐項詢問)
5. 使用者標記修正 → 使用者編輯 / 增加 / 從草稿中刪除
6. 疊代(如有需要) → 如果有缺口 → 呈現修正後的草稿
7. 提出規格 → 完整代理規格書 (參見 templates/agent-spec.md)
8. 核准關卡 → 使用者建構前核准
範圍訪談 (8 個領域)
對於 Quick 層級: 全部跳過 — 直接從頭開始推論 + 確認
對於 Standard+:
- 從現有上下文推論草稿規格 → 將單頁草稿呈現給使用者
- 使用者閱讀後標記修正(修改/增加/刪除)
- 使用下方檢查清單檢查是否有遺漏 — 僅針對草稿未涵蓋的部分提問
- 套用原型最小化清單 — 根據原型進行簡短 / 明顯則跳過 / 深入
嚴禁逐項詢問檢查清單 — 先呈現草稿,僅針對缺口提問
領域 1:身份與目的 (Identity & Purpose)
-
名稱 — 代理叫什麼?(如果尚未命名,請提議)
-
原型 — 根據目錄屬於哪個原型?
-
角色 — 一句清楚的句子:「這個代理[做 X 事]給[使用者 Y],以達成[Z]。」
-
人格 (Persona) —
欄位 內容 範例 Tone 正式 / 隨意 / 技術性 / 好玩 / 權威 / 溫暖 「技術性但平易近人」 範例句 代理實際會說的話 「讓我檢查一下設定... 找到了。問題在第 42 行。」 務必推薦一個人格。
「我建議採用技術性但平易近人的語氣 — 事實精確,對話輕鬆。」 -
已知上下文 — 在開始工作前必須知道什麼?
-
最狹義的工作 — 其角色最有用的最小定義是什麼?
領域 2:能力與邊界 (Capabilities & Boundaries)
-
能力 (Capabilities) — 核心動作,按優先順序排列。 每個能力包括:
- 描述(1 句話)
- 觸發條件(如何呼叫此能力?)
- 預期輸出(成功的樣子是什麼?)
- 失敗模式(如果它不工作會怎樣?)
-
邊界 (Boundaries) — 明確列出它絕對不能做的事。 每個邊界都以關鍵規則格式呈現,並附帶情境:
規則:嚴禁修改專案目錄外的檔案。 情境:使用者要求「修復我的桌面設定」— 代理有檔案系統存取權。 後果:有禮貌地拒絕,解釋範圍限制。 -
工具映射 (Tool Mapping) — 對於每個能力,決定需要哪些工具。 請在能力和邊界明確之後再進行此步驟。
能力:「搜尋文件」 ↓ 搜尋程式碼庫中現有工具 → 找到 Exa MCP(網路搜尋) ↓ 建議:「透過 Exa MCP(已設定)進行知識檢索。 若 Exa 不可用,則備用透過 Firecrawl 進行網路搜尋。」規則: 如果程式碼庫中已有特定工具,請提議使用該工具。 僅在沒有現有工具符合需求時,才提議一個類別。 但是: 如果現有工具與需求不匹配(例如需要本地文件搜尋,但只有 Exa 網路搜尋)— 嚴禁硬塞 (force-fit)。將其標記為部分符合或缺口,並提議更符合的類別。
✅ 「使用 Exa MCP 進行網路搜尋 — 已設定」 ✅ 「Exa MCP 可用於網路搜尋,但工作日誌搜尋應使用 Obsidian + grep 替代 — 對於外部搜尋算是部分符合」 ✅ 「未找到現有向量資料庫。需要一個語意搜尋工具, 例如 Chroma 或 Qdrant。」 ❌ 「需要一個知識檢索工具」(含糊 — Exa 已存在,使用它) ❌ 「為所有功能使用 Exa MCP」(硬塞 — Exa 不適合本地搜尋)工具類別(供參考缺口用):
Knowledge retrieval → search, vector DBs, document stores, web scraping Code execution → sandboxes, interpreters, compilers, linters Communication → email, messaging, notifications, webhooks System operations → file I/O, process management, network, registry Data processing → ETL, transformation, validation, storage Visual/creative → image generation, layout engines, animation Monitoring → logs, metrics, tracing, alerting AI/LLM → model APIs, embeddings, RAG pipelines, vector DBs Testing → test runners, coverage, mocking, E2E browsers -
技能 (Skills) — 需要哪些技能?
…
[因篇幅限制,內容已截斷]