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

Canonical source: https://maguyva.ai/zh-hant/blog/progressive-disclosure-cli-into-agents

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

Date: 2026-01-20 · Author: Maguyva Team

> 代理系統預設是不透明的。漸進式揭露為操作者提供分層的 CLI 檢視——從快速狀態檢查，到完整的代理內部細節與決策軌跡，一應俱全。

> *本文中的數字反映發布當下（2026 年 1 月）的系統狀態。目前最新數字請參見我們的[團隊頁面](/zh-hant/team)。*

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

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

## 不透明的問題

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

- 超過 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 工具 | 讓我看看程式碼。 |

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

## 第一層：系統健康狀態

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

```bash
$ orkestra system status
```
```json
{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}
```

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

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

## 第二層：代理清單

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

```bash
$ orkestra agents list
```

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

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

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

```bash
$ orkestra agents search "database"
```

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

## 第三層：代理深度檢視

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

```bash
$ orkestra agents info architecture-advisor
```

輸出內容包括：

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

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

```jsonc
{
  "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",
      ...
    ]
  }
}
```

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

## 第四層：決策考古

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

```bash
$ orkestra decisions search "agent"
```

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

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

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

```bash
$ orkestra decisions info DEC-SR-049
```

```json
{
  "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 的替代品，而是具備圖譜感知能力、經過語意索引，並與驅動代理自身運作的那套程式碼智慧完全整合。

## 跨登錄檔的統一搜尋

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

```bash
$ orkestra search "database" --summary
```

```json
{
  "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. **連接到程式碼智慧。** 最終，使用者需要看到實作內容本身。

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

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