Progressive Disclosure: Tetingkap CLI ke Dalam Sistem Ejen

Angka dalam penulisan ini mencerminkan sistem pada masa penerbitan (Januari 2026). Lihat halaman pasukan kami untuk angka terkini.

Sistem ejen bersifat legap mengikut reka bentuk. Ia membuat keputusan, memanggil tool, dan menyelaraskan kerja merentasi berpuluh-puluh spesialis. Tetapi apabila sesuatu tidak kena — atau apabila anda sekadar mahu memahami apa yang sedang berlaku — di manakah anda perlu lihat?

Jawapannya ialah progressive disclosure: satu antara muka berlapis yang mendedahkan tepat seberapa banyak kerumitan yang anda perlukan, tepat pada masa anda memerlukannya.

Masalah Kelegapan

Satu sistem orkestrasi ejen moden mungkin mempunyai:

• 40+ ejen spesialis, setiap satu dengan keupayaan berbeza
• 700+ skill merentasi automasi dalaman dan integrasi vendor
• 470+ keputusan seni bina yang membentuk gelagat
• Berpuluh-puluh server tool MCP yang menyediakan keupayaan luaran

Kerumitan ini adalah sengaja. Ejen memerlukan akses kepada konteks yang kaya — pengetahuan domain, code intelligence, skema pangkalan data — untuk membuat keputusan yang baik. Tetapi kekayaan yang sama itu mencipta satu masalah keterlihatan.

Bagaimana anda tahu ejen mana yang mengendalikan migrasi pangkalan data? Keputusan apa yang membentuk gelagat pemeringkatan sistem carian? Tool apa yang boleh dicapai oleh architecture advisor?

Tanpa akses berstruktur, anda terpaksa membaca kod sumber atau berharap dokumentasi itu terkini.

Progressive Disclosure sebagai Seni Bina

Progressive disclosure bukan sekadar corak UI. Ia adalah satu prinsip seni bina: menyusun maklumat dalam lapisan, setiap satu lebih mendalam daripada yang sebelumnya, supaya pengguna boleh berhenti pada tahap yang menjawab soalan mereka.

Untuk sistem ejen, ini diterjemahkan kepada arahan CLI pada kedalaman yang semakin meningkat:

Tahap	Arahan	Soalan Yang Dijawab
1	orkestra system status	Adakah segala-galanya sihat?
2	orkestra agents list	Ejen apa yang wujud?
3	orkestra agents info <name>	Apa yang dilakukan oleh ejen ini?
4	orkestra decisions search	Mengapa ia berfungsi sebegini?
5	Tool MCP Maguyva	Tunjukkan kod itu.

Setiap tahap menjawab satu soalan susulan yang semula jadi. Anda jarang perlu melompat terus ke tahap 5.

Tahap 1: Kesihatan Sistem

Soalan pertama sentiasa: adakah segala-galanya berfungsi?

$ orkestra system status

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

Satu arahan. Empat angka. Cukup untuk mengetahui sistem itu telah dikonfigurasikan dan registri telah diisi.

Jika bilangan ejen jatuh secara tidak dijangka atau skill gagal dimuatkan, anda melihatnya di sini dahulu. Tiada keperluan menyelam ke dalam log.

Tahap 2: Inventori Ejen

Sebaik sahaja anda tahu sistem itu sihat, soalan seterusnya ialah: apa yang tersedia?

$ orkestra agents list

Ini memulangkan data berstruktur — nama ejen, penerangan, keutamaan model, liputan domain. Output itu adalah JSON secara lalai, memudahkan ia untuk di-pipe ke dalam jq untuk penapisan:

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

Mahukan ejen yang mengendalikan kerja pangkalan data? Arahan carian menyempitkan pencarian itu:

$ orkestra agents search "database"

Ini mengimbas nama, penerangan, dan keupayaan. Anda menemui spesialis yang tepat tanpa membaca 40 takrifan ejen.

Tahap 3: Selami Mendalam Ejen

Menemui satu ejen yang kelihatan relevan? Arahan info mendedahkan segala-galanya:

$ orkestra agents info architecture-advisor

Output itu merangkumi:

• Metadata: Nama, kategori, keutamaan model, penerangan
• Domains: Kawasan pengetahuan mana yang diliputi oleh ejen ini
• Identity: Sifat karakter (architect, strategist, knowledge-architect)
• Panduan tool: Dokumentasi tool mana yang disuntik ke dalam konteks
• Tools: Senarai penuh tool MCP yang boleh dicapai oleh ejen ini

Berikut satu sampel apa yang anda lihat:

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

Ini memberitahu anda dengan tepat apa yang boleh dilakukan oleh ejen itu. Tiada keperluan kod sumber.

Tahap 4: Arkeologi Keputusan

Ejen bergelagat mengikut keputusan yang didokumenkan. Apabila anda perlu memahami mengapa sesuatu berfungsi dengan cara tertentu, registri keputusan adalah sumber kebenaran.

$ orkestra decisions search "agent"

Ini memulangkan keputusan seni bina yang sepadan:

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

Setiap keputusan mempunyai provenans penuh — bila ia dibuat, mengapa, trade-off apa yang dipertimbangkan, commit mana yang melaksanakannya:

$ orkestra decisions info DEC-SR-049

on
{
  "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..."
    }
  ]
}

Ini adalah dokumentasi seni bina yang kekal terkini kerana ia di-mine daripada commit, bukan disenggara secara manual.

Tahap 5: Code Intelligence Langsung

Apabila anda perlu melihat pelaksanaan sebenar — bukan metadata tentangnya — tool MCP Maguyva menyediakan akses langsung.

Dari dalam sesuatu sesi ejen:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Ini auto-menghalakan merentasi carian semantic, text, dan AST untuk mencari kod yang relevan. Untuk simbol khusus:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Untuk analisis kebergantungan:

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

Ini bukan sekadar pengganti grep. Ia sedar-graf (graph-aware), diindeks secara semantik, dan diintegrasikan dengan code intelligence yang sama yang menggerakkan ejen itu sendiri.

Carian Bersatu Merentasi Registri

Kadangkala anda tidak tahu registri mana yang menyimpan jawapan itu. Carian bersatu merangkumi segala-galanya:

$ orkestra search "database" --summary

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

254 padanan merentasi lima registri. Ringkasan itu memberitahu anda di mana untuk menyelam lebih dalam. Buang --summary untuk hasil terperinci, atau tambah --limit 5 untuk mengekalkan output yang boleh diurus.

Mengapa Ini Penting

Progressive disclosure bukan sekadar tentang kemudahan. Ia mengubah cara anda berinteraksi dengan sistem yang kompleks.

Penyahpepijatan menjadi terkawal. Apabila seorang ejen membuat keputusan yang tidak dijangka, anda tidak perlu grep menerusi log. Anda menyemak tool apa yang boleh dicapainya (agents info), keputusan apa yang membentuk gelagatnya (decisions search), dan menjejaki pelaksanaan jika perlu (intelligent_search).

Onboarding dipercepatkan. Ahli pasukan baharu tidak perlu membaca keseluruhan pangkalan kod. Mereka bermula dengan system status, meneroka dengan agents list, dan menyelam lebih dalam hanya apabila mereka bertembung dengan sesuatu yang mereka tidak faham.

Dokumentasi kekal terkini. Kerana CLI membaca daripada registri yang sama yang mengkonfigurasikan ejen, output itu sentiasa tepat. Tiada penyimpangan antara apa yang dikatakan oleh dokumentasi dan apa yang dilakukan oleh sistem.

CLI sebagai Antara Muka

Kami boleh sahaja membina satu dashboard web. Kami boleh sahaja menulis dokumentasi yang ekstensif. Sebaliknya, kami membina satu CLI yang membaca daripada sumber kebenaran.

CLI itu mempunyai kelebihan:

• Boleh Digubah (Composable): Pipe output menerusi jq, integrasikan dengan skrip
• Boleh Diskrip (Scriptable): Automasikan semakan, jana laporan
• Pantas: Tiada muat semula halaman, tiada aliran pengesahihan
• Tepat: Membaca konfigurasi sebenar, bukan representasi cache

Untuk sistem di mana ketepatan lebih penting daripada estetika, CLI menang.

Membina Progressive Disclosure Anda Sendiri

Jika anda sedang membina sistem ejen, pertimbangkan bagaimana pengguna akan memeriksanya:

1. Mulakan dengan semakan kesihatan. Satu arahan yang memberitahu anda sama ada perkara berfungsi.
2. Sediakan paparan inventori. Senaraikan apa yang wujud sebelum menerangkan apa yang ia lakukan.
3. Bolehkan pertanyaan bersasar. Carian mengatasi penyemakan imbas pada skala besar.
4. Dedahkan provenans. Benarkan pengguna menjejaki keputusan kembali kepada asal-usulnya.
5. Sambungkan kepada code intelligence. Akhirnya, pengguna perlu melihat pelaksanaan.

Setiap lapisan menjawab satu soalan susulan. Bina ia mengikut urutan kekerapan — kebanyakan pengguna berhenti pada lapisan 2 atau 3. Hanya pengguna mahir yang mencapai lapisan 5.

Matlamatnya bukan untuk mendedahkan segala-galanya. Ia adalah untuk mendedahkan tepat apa yang diperlukan, tepat pada masa ia diperlukan. Itulah progressive disclosure yang diterapkan kepada seni bina ejen.