Bộc lộ dần dần: Cửa sổ CLI nhìn vào hệ thống agent

Các con số trong bài này phản ánh hệ thống tại thời điểm xuất bản (tháng 1/2026). Xem trang team của chúng tôi để biết số liệu hiện tại.

Các hệ thống agent vốn mờ đục theo thiết kế. Chúng ra quyết định, gọi công cụ, và điều phối công việc trên hàng chục chuyên gia. Nhưng khi có gì đó trục trặc — hoặc khi bạn đơn giản chỉ muốn hiểu chuyện gì đang xảy ra — bạn nhìn vào đâu?

Câu trả lời là bộc lộ dần dần (progressive disclosure): một giao diện theo lớp bộc lộ đúng bằng lượng độ phức tạp bạn cần, đúng vào lúc bạn cần nó.

Vấn đề mờ đục

Một hệ thống điều phối agent hiện đại có thể có:

• 40+ agent chuyên biệt, mỗi agent có năng lực riêng
• 700+ skill trải khắp tự động hóa nội bộ và tích hợp vendor
• 470+ quyết định kiến trúc định hình hành vi
• Hàng chục máy chủ công cụ MCP cung cấp năng lực bên ngoài

Độ phức tạp này là có chủ đích. Agent cần quyền truy cập vào ngữ cảnh phong phú — tri thức domain, trí tuệ mã nguồn, schema database — để ra quyết định tốt. Nhưng chính sự phong phú đó tạo ra một vấn đề về khả năng quan sát.

Làm sao bạn biết agent nào xử lý di trú database? Những quyết định nào đã định hình hành vi xếp hạng của hệ thống tìm kiếm? Bộ tư vấn kiến trúc có quyền truy cập vào những công cụ nào?

Không có quyền truy cập có cấu trúc, bạn chỉ còn cách đọc mã nguồn hoặc hy vọng tài liệu vẫn còn cập nhật.

Bộc lộ dần dần như một kiến trúc

Bộc lộ dần dần không chỉ là một mẫu UI. Đó là một nguyên tắc kiến trúc: tổ chức thông tin theo từng lớp, mỗi lớp sâu hơn lớp trước, để người dùng có thể dừng lại ở mức trả lời được câu hỏi của họ.

Với các hệ thống agent, điều này chuyển thành các lệnh CLI ở các độ sâu tăng dần:

Mức	Lệnh	Câu hỏi được trả lời
1	orkestra system status	Mọi thứ có khỏe mạnh không?
2	orkestra agents list	Có những agent nào?
3	orkestra agents info <name>	Agent này làm gì?
4	orkestra decisions search	Tại sao nó hoạt động theo cách này?
5	Công cụ MCP của Maguyva	Cho tôi xem mã nguồn.

Mỗi mức trả lời một câu hỏi tiếp nối tự nhiên. Bạn hiếm khi cần nhảy thẳng đến mức 5.

Mức 1: Sức khỏe hệ thống

Câu hỏi đầu tiên luôn là: mọi thứ có đang hoạt động không?

$ orkestra system status

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

Một lệnh. Bốn con số. Đủ để biết hệ thống đã được cấu hình và các registry đã được nạp đầy đủ.

Nếu số lượng agent giảm đột ngột hoặc skill không nạp được, bạn sẽ thấy điều đó ở đây đầu tiên. Không cần lặn sâu vào log.

Mức 2: Kho agent

Một khi bạn biết hệ thống khỏe mạnh, câu hỏi tiếp theo là: có gì sẵn có?

$ orkestra agents list

Lệnh này trả về dữ liệu có cấu trúc — tên agent, mô tả, mô hình ưa thích, độ phủ domain. Đầu ra mặc định là JSON, giúp dễ dàng pipe vào jq để lọc:

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

Muốn tìm các agent xử lý công việc database? Lệnh tìm kiếm sẽ thu hẹp phạm vi:

$ orkestra agents search "database"

Lệnh này quét tên, mô tả, và năng lực. Bạn tìm đúng chuyên gia mà không cần đọc 40 định nghĩa agent.

Mức 3: Đào sâu vào agent

Đã tìm thấy một agent có vẻ liên quan? Lệnh info bộc lộ mọi thứ:

$ orkestra agents info architecture-advisor

Đầu ra bao gồm:

• Metadata: Tên, danh mục, mô hình ưa thích, mô tả
• Domains: Những lĩnh vực tri thức nào agent này bao phủ
• Identity: Đặc điểm tính cách (architect, strategist, knowledge-architect)
• Hướng dẫn công cụ: Tài liệu công cụ nào được tiêm vào ngữ cảnh
• Tools: Danh sách đầy đủ các công cụ MCP mà agent này có quyền truy cập

Đây là một mẫu về những gì bạn thấy:

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

Điều này cho bạn biết chính xác agent có thể làm gì. Không cần đến mã nguồn.

Mức 4: Khảo cổ quyết định

Agent hành xử theo các quyết định đã được ghi lại tài liệu. Khi bạn cần hiểu vì sao một thứ gì đó hoạt động theo một cách cụ thể, registry quyết định là nguồn chân lý.

$ orkestra decisions search "agent"

Lệnh này trả về các quyết định kiến trúc khớp:

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

Mỗi quyết định có nguồn gốc đầy đủ — khi nào nó được đưa ra, vì sao, những sự đánh đổi nào đã được cân nhắc, những commit nào đã triển khai nó:

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

Đây là tài liệu kiến trúc luôn cập nhật vì nó được khai thác từ các commit, không phải được bảo trì thủ công.

Mức 5: Trí tuệ mã nguồn trực tiếp

Khi bạn cần thấy việc triển khai thực sự — không phải metadata về nó — các công cụ MCP của Maguyva cung cấp quyền truy cập trực tiếp.

Từ bên trong một phiên agent:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Lệnh này tự động định tuyến qua tìm kiếm ngữ nghĩa, văn bản, và AST để tìm mã liên quan. Với các symbol cụ thể:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Cho phân tích phụ thuộc:

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

Đây không chỉ là những thứ thay thế grep. Chúng nhận biết đồ thị, được lập chỉ mục ngữ nghĩa, và tích hợp với cùng lớp trí tuệ mã nguồn đang vận hành chính các agent.

Tìm kiếm hợp nhất trên các Registry

Đôi khi bạn không biết registry nào giữ câu trả lời. Tìm kiếm hợp nhất trải khắp mọi thứ:

$ orkestra search "database" --summary

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

254 khớp trên năm registry. Bản tóm tắt cho bạn biết nên đào sâu vào đâu. Bỏ --summary để có kết quả chi tiết, hoặc thêm --limit 5 để giữ đầu ra gọn gàng.

Vì sao điều này quan trọng

Bộc lộ dần dần không chỉ là về sự tiện lợi. Nó thay đổi cách bạn tương tác với các hệ thống phức tạp.

Việc debug trở nên khả thi. Khi một agent ra một quyết định bất ngờ, bạn không phải grep xuyên qua log. Bạn kiểm tra nó có quyền truy cập vào những công cụ nào (agents info), những quyết định nào định hình hành vi của nó (decisions search), và theo dõi việc triển khai nếu cần (intelligent_search).

Onboarding tăng tốc. Thành viên mới trong đội không cần đọc toàn bộ codebase. Họ bắt đầu với system status, khám phá với agents list, và chỉ đào sâu hơn khi gặp phải thứ gì đó họ không hiểu.

Tài liệu luôn cập nhật. Vì CLI đọc từ cùng các registry cấu hình các agent, đầu ra luôn chính xác. Không có sự trôi dạt giữa những gì tài liệu nói và những gì hệ thống làm.

CLI như một giao diện

Chúng tôi có thể đã xây dựng một dashboard web. Chúng tôi có thể đã viết tài liệu đồ sộ. Thay vào đó, chúng tôi xây dựng một CLI đọc trực tiếp từ nguồn chân lý.

CLI có những lợi thế:

• Có thể kết hợp (Composable): Pipe đầu ra qua jq, tích hợp với script
• Có thể lập trình (Scriptable): Tự động hóa kiểm tra, sinh báo cáo
• Nhanh: Không tải trang, không luồng xác thực
• Chính xác: Đọc cấu hình thực tế, không phải một bản biểu diễn đã cache

Với các hệ thống nơi tính đúng đắn quan trọng hơn tính thẩm mỹ, CLI thắng.

Xây dựng bộc lộ dần dần của riêng bạn

Nếu bạn đang xây dựng các hệ thống agent, hãy cân nhắc cách người dùng sẽ kiểm tra chúng:

1. Bắt đầu với kiểm tra sức khỏe. Một lệnh cho bạn biết mọi thứ có đang hoạt động hay không.
2. Cung cấp các khung nhìn kho hàng. Liệt kê những gì tồn tại trước khi giải thích nó làm gì.
3. Cho phép truy vấn có mục tiêu. Tìm kiếm vượt trội hơn duyệt thủ công ở quy mô lớn.
4. Phơi bày nguồn gốc. Cho phép người dùng theo dõi các quyết định về tận nguồn gốc của chúng.
5. Kết nối với trí tuệ mã nguồn. Cuối cùng, người dùng cần thấy việc triển khai.

Mỗi lớp trả lời một câu hỏi tiếp nối. Xây dựng chúng theo thứ tự tần suất — hầu hết người dùng dừng ở lớp 2 hoặc 3. Chỉ những power user mới chạm đến lớp 5.

Mục tiêu không phải là phơi bày mọi thứ. Đó là phơi bày chính xác những gì cần thiết, đúng vào lúc cần thiết. Đó là bộc lộ dần dần được áp dụng vào kiến trúc agent.