漸進式揭露：透過 CLI 窺探代理系統

本文中的數字反映發布當下（2026 年 1 月）的系統狀態。目前最新數字請參見我們的團隊頁面。

代理系統在設計上本就不透明。它們會做決策、呼叫工具，並協調數十位專家之間的工作。但當出了問題——或你單純只是想了解目前發生了什麼事——該從哪裡著手查看？

答案是漸進式揭露：一種分層介面，恰好在你需要的時候、揭露恰好足夠的複雜度。

不透明的問題

一套現代的代理協調系統，可能包含：

• 超過 40 位各具能力的專家代理
• 超過 700 項技能，涵蓋內部自動化與第三方整合
• 超過 470 項塑造行為的架構決策
• 數十個提供外部能力的 MCP 工具伺服器

這樣的複雜度是刻意設計的：代理需要取用豐富的情境資訊——領域知識、程式碼智慧、資料庫結構描述——才能做出好的決策。但這份豐富度，同時也帶來了能見度的問題。

你怎麼知道哪個代理負責處理資料庫遷移？哪些決策塑造了搜尋系統的排名行為？架構顧問代理又能取用哪些工具？

若沒有結構化的存取方式，你就只能翻讀原始碼，或是祈禱文件仍是最新的。

將漸進式揭露視為一種架構

漸進式揭露不只是一種 UI 模式，而是一項架構原則：將資訊分層組織，一層比一層深入，讓使用者能在剛好回答出自己問題的那一層停下來。

對代理系統而言，這化為深度遞增的一系列 CLI 指令：

層級	指令	回答的問題
1	orkestra system status	一切是否健康？
2	orkestra agents list	有哪些代理存在？
3	orkestra agents info <name>	這個代理做什麼？
4	orkestra decisions search	為什麼它是這樣運作的？
5	Maguyva MCP 工具	讓我看看程式碼。

每一層都回答了一個自然而然的後續問題，你很少需要直接跳到第五層。

第一層：系統健康狀態

第一個問題永遠是：一切都在正常運作嗎？

$ orkestra system status

{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

一個指令、四個數字，就足以知道系統設定完成、各登錄檔也都已經填入資料。

若代理數量意外下降、或技能載入失敗，你會在這裡第一時間看到，不需要翻找日誌。

第二層：代理清單

一旦確認系統健康，下一個問題是：有哪些可用？

$ orkestra agents list

這會回傳結構化資料——代理名稱、說明、模型偏好、涵蓋領域。輸出預設為 JSON 格式，可輕鬆透過管線送入 jq 進行篩選：

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

想找出負責資料庫工作的代理？搜尋指令可以幫你縮小範圍：

$ orkestra agents search "database"

它會掃描名稱、說明與能力，讓你不必讀完 40 份代理定義，就能找到對的專家。

第三層：代理深度檢視

找到一個看起來相關的代理了？info 指令會揭露所有細節：

$ orkestra agents info architecture-advisor

輸出內容包括：

• 中繼資料：名稱、類別、模型偏好、說明
• 領域：這個代理涵蓋哪些知識領域
• 身份：性格特質（架構師、策略家、知識架構師）
• 工具指南：哪些工具文件會被注入情境
• 工具：這個代理可用的完整 MCP 工具清單

以下是你會看到的內容範例：

{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

這會準確告訴你這個代理能做什麼，完全不需要查看原始碼。

第四層：決策考古

代理會依照已記錄的決策行事。當你需要理解某件事為什麼是這樣運作時，決策登錄檔就是最終真實來源。

$ orkestra decisions search "agent"

這會回傳相符的架構決策：

{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

每項決策都具備完整的溯源資訊——何時做出、為何做出、考量過哪些取捨、由哪些提交實作：

$ orkestra decisions info DEC-SR-049

{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

這是一份能持續保持最新的架構文件，因為它是從提交中挖掘出來的，而非人工手動維護。

第五層：直接的程式碼智慧

當你需要看到實際的實作內容——而不只是關於它的中繼資料——Maguyva 的 MCP 工具能提供直接存取。

在代理工作階段中：

mcp__maguyva__intelligent_search
  query: "agent context loading"

這會自動橫跨語意、文字與 AST 搜尋，找出相關程式碼。若要查詢特定符號：

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

若要進行依賴分析：

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

這些工具不只是 grep 的替代品，而是具備圖譜感知能力、經過語意索引，並與驅動代理自身運作的那套程式碼智慧完全整合。

跨登錄檔的統一搜尋

有時候你根本不知道答案藏在哪個登錄檔裡，統一搜尋能一次橫跨所有登錄檔：

$ orkestra search "database" --summary

{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

在五個登錄檔中共找到 254 筆相符結果。摘要會告訴你該往哪裡深入查看。移除 --summary 可取得詳細結果，或加上 --limit 5 讓輸出量維持在可掌控範圍內。

為什麼這很重要

漸進式揭露不只是為了方便，它改變了你與複雜系統互動的方式。

除錯變得可掌控。 當代理做出意外決策時，你不必翻遍日誌，而是先檢查它能取用哪些工具（agents info）、哪些決策塑造了它的行為（decisions search），必要時再追蹤實作內容（intelligent_search）。

新人上手更快。 新進團隊成員不必讀完整個程式碼庫，而是從 system status 開始，透過 agents list 探索，只有在遇到自己不理解的地方時，才需要深入研究。

文件保持最新。 因為 CLI 讀取的，正是設定代理所用的那些登錄檔本身，輸出內容永遠準確，文件所說的與系統實際運作的內容之間，不會出現落差。

以 CLI 作為介面

我們原本可以打造一個網頁儀表板，也可以寫出大量文件。但我們選擇打造一套直接讀取最終真實來源的 CLI。

CLI 具備以下優勢：

• 可組合：可透過管線將輸出送入 jq，並與腳本整合
• 可腳本化：可自動化檢查、產生報告
• 快速：不需要頁面載入，也不需要身分驗證流程
• 準確：讀取的是真實設定，而非快取後的呈現版本

對於正確性比美觀更重要的系統來說，CLI 才是贏家。

打造你自己的漸進式揭露

如果你正在打造代理系統，請思考使用者將如何檢視它：

1. 從健康檢查開始。 一個指令，就能告訴你一切是否運作正常。
2. 提供清單檢視。 先列出有什麼存在，再解釋它做什麼。
3. 支援針對性查詢。 在大規模情境下，搜尋勝過瀏覽。
4. 揭露溯源資訊。 讓使用者能追蹤決策回到其源頭。
5. 連接到程式碼智慧。 最終，使用者需要看到實作內容本身。

每一層都回答一個後續問題，請依使用頻率順序建構它們——多數使用者會停在第二層或第三層，只有進階使用者才會抵達第五層。

目標並不是揭露一切，而是恰好揭露需要的東西、在恰好需要的時候。這正是漸進式揭露應用於代理架構的方式。