渐进式披露:透视智能体系统的 CLI 窗口

本文中的数字反映的是发布时(2026 年 1 月)的系统状态。如需查看最新数据,请参阅我们的 团队页面。

智能体系统在设计上就是不透明的。它们做决策、调用工具,在数十个专家之间协调工作。但当出了问题——或者你只是单纯想弄清楚正在发生什么——你该往哪里看?

答案是渐进式披露:一个分层的界面,恰好在你需要的时候,精确地展现出你所需要的那部分复杂度。

不透明问题

一套现代智能体编排系统,可能拥有:

• 40 多个各有专长的专家智能体
• 700 多项技能,涵盖内部自动化和供应商集成
• 470 多条塑造行为的架构决策
• 数十个提供外部能力的 MCP 工具服务器

这种复杂性是有意为之的。智能体需要访问丰富的上下文——领域知识、代码智能、数据库 Schema——才能做出好的决策。但正是这种丰富性,带来了一个可见性问题。

你怎么知道该由哪个智能体来处理数据库迁移?是哪些决策塑造了搜索系统的排序行为?架构顾问又能访问哪些工具?

没有结构化的访问方式,你就只能去读源代码,或者祈祷文档是最新的。

作为一种架构的渐进式披露

渐进式披露不只是一种 UI 模式,它是一条架构原则:把信息分层组织,一层比一层深入,让用户可以在回答了自己问题的那一层停下来。

对智能体系统而言,这转化成了深度逐级递增的 CLI 命令:

层级	命令	回答的问题
1	orkestra system status	一切都健康吗?
2	orkestra agents list	有哪些智能体存在?
3	orkestra agents info <name>	这个智能体做什么?
4	orkestra decisions search	它为什么是这样运作的?
5	Maguyva MCP 工具	把代码给我看看。

每一层都回答了一个自然而然会引出的追问。你很少需要直接跳到第 5 层。

第一层:系统健康度

第一个问题永远是:一切都在正常运作吗?

$ orkestra system status

on
{
  "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

输出内容包括:

• 元数据:名称、类别、模型偏好、描述
• 领域:这个智能体覆盖哪些知识领域
• 身份:性格特质(architect、strategist、knowledge-architect)
• 工具指南:哪些工具文档被注入到了上下文中
• 工具:这个智能体可用的完整 MCP 工具列表

下面是你会看到的内容示例:

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

这会准确地告诉你这个智能体能做什么,不需要去看源代码。

第四层:决策考古

智能体的行为,遵循着已经记录在案的决策。当你需要理解某件事为什么是这样运作的,决策注册表就是那个唯一可信的来源。

$ orkestra decisions search "agent"

这会返回匹配的架构决策:

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

每一条决策都有完整的溯源信息——它是何时做出的、为什么、权衡过哪些取舍、哪些提交实现了它:

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

这是一份始终保持最新的架构文档,因为它是从提交记录中挖掘出来的,而不是靠人工手动维护的。

第五层:直接的代码智能

当你需要看到真正的实现——而不只是关于它的元数据——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

on
{
  "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

我们本可以搭建一个 Web 仪表盘,本可以写一份详尽的文档。但我们选择打造了一个直接读取唯一可信来源的 CLI。

CLI 有它的优势:

• 可组合:可以把输出通过管道传给 jq,与脚本集成
• 可编写脚本:能自动化检查、生成报告
• 快:没有页面加载,没有身份验证流程
• 准确:读取的是真实的配置,而不是某个缓存版本

对于正确性比美观更重要的系统来说,CLI 才是赢家。

构建你自己的渐进式披露

如果你正在构建智能体系统,不妨想一想用户会如何检视它们:

1. 从健康检查开始。 用一条命令,告诉你事情是否在正常运作。
2. 提供清单视图。 在解释某样东西做什么之前,先列出有哪些东西存在。
3. 支持有针对性的查询。 在规模面前,搜索胜过浏览。
4. 暴露溯源信息。 让用户能把决策追溯回它们的源头。
5. 接入代码智能。 最终,用户总是需要看到实际的实现。

每一层都回答了一个后续的追问。请按使用频率来构建它们——大多数用户会在第 2 层或第 3 层就止步了,只有资深用户才会一路走到第 5 层。

目标不是把一切都暴露出来,而是恰好在需要的时候,暴露出恰好需要的那部分。这就是把渐进式披露应用到智能体架构上的样子。