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

Canonical source: https://maguyva.ai/zh-hans/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-hans/team)。*

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

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

## 不透明问题

一套现代智能体编排系统，可能拥有：

- 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 层。

## 第一层：系统健康度

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

```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
```

输出内容包括：

- **元数据**：名称、类别、模型偏好、描述
- **领域**：这个智能体覆盖哪些知识领域
- **身份**：性格特质（architect、strategist、knowledge-architect）
- **工具指南**：哪些工具文档被注入到了上下文中
- **工具**：这个智能体可用的完整 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

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

CLI 有它的优势：

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

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

## 构建你自己的渐进式披露

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

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

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

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