编辑器、助手和其他前端
Aggrega 可以在多个地方使用:终端、Visual Studio Code 扩展、通过 Model Context Protocol(MCP)连接的 AI 助手,以及任何驱动 aggrega 二进制文件的程序。这些前端都不自带编译器。每个前端都运行 aggrega 二进制文件,或连接到一个已在运行的实例,并向它发出请求,因此 YAML 的解析、目录的解析和图的构建都在同一个地方进行,前端显示的就是该二进制文件编译出的结果。前端不重新实现其中任何部分,因此不存在会与原版产生偏差的第二份副本。
本章介绍这些前端共享的契约,以及每个前端向该二进制文件请求什么。
IR 图是公开契约
编译一个 Release(连同它所指定的 Aggregate 和 Manifest)会生成一张中间表示(IR)图:每个节点,包括它实例化的组件、该组件解析到的版本、它所在的边界和子系统,以及声明它的文件;节点之间的每条连接;附加到每个节点上的 Features;以及映射到它们上面的值,并注明每个值的来源。它是编译器即将渲染为产物的内容的快照。
该图的结构以 JSON Schema 的形式发布,即 https://aggrega.ai/schemas/ir-v1beta1.schema.json,IR schema 参考描述了其中的每个字段。前端依据该 schema 读取图,而不是依据编译器的内部实现,因此 schema 是该结构唯一的演进之处,用任何语言编写的前端都以相同方式跟进它。
作者声明为敏感的值,在图被交出的任何地方都会被隐去。需要明文获取这些值的前端必须显式请求,此后该答复所到之处都会以明文携带这些值。
请求图的三种方式
同一张图在每个界面上都可获取,每个答复都是一份完整的图文档:
- 从命令行。
aggrega build、给定 Release 的aggrega inspect,以及aggrega validate --release均接受--ir-graph,它会在命令原有的全部输出之外,将该次运行计算出的图以 JSON 形式写入标准输出。与之同用的--unredacted会打印敏感值。参见aggrega inspect。 - 从守护进程。 向
aggrega serve发送aggrega/irGraph请求,并以相对于工作区根目录的路径指定 Release,它会在graph下返回同一份文档;unredacted: true用于请求敏感值。参见aggrega serve。 - 从 AI 助手。 MCP 服务器的
cli-inspect、cli-build和cli-validate工具以ir_graph参数接收该命令的标志。参见aggrega mcp。
每个答复描述的是提出请求时的 Release。跟踪编辑的前端会再次请求:Visual Studio Code 扩展在每次保存文档时都会重绘其图。
Visual Studio Code 扩展
Visual Studio Code 的 Aggrega 扩展会启动 aggrega serve,并使其在该工作区中持续运行。它显示的每个答复都来自 aggrega 二进制文件:大多数来自该守护进程——其中包括编辑时的诊断、悬停提示、补全、转到定义、查找引用、构建和预览构建——其余则来自运行该二进制文件自身的命令。
它的拓扑图就是 IR 图。扩展为所选的 Release 发送 aggrega/irGraph 并绘制答复:边界和子系统作为嵌套容器,组件作为节点,连接作为边;在选中的节点或连接上,显示附加到它的 Features。编译器发送拓扑,从不发送坐标;布局在编辑器中计算。从图中附加 Feature 同样要经过守护进程:编译器指明该附加所属的文档及其中的位置,由扩展写入该处。关于该视图显示的内容和功能,参见拓扑图。
MCP 服务器
aggrega mcp 将二进制文件作为 Model Context Protocol 服务器运行,使 AI 助手能够发现 Aggrega 的操作并调用它们,而不是读取命令输出。通过标准输入和输出,它使用以换行符分隔的 JSON-RPC 2.0 通信,以子进程方式启动它的客户端就是这样访问它的;通过 HTTP,它提供一个端点 /mcp,供其他机器上的调用方使用。它的工具就是编译器的操作——读取 schema、描述工作区、验证、构建、起草和编辑文档——每次调用都由命令行所运行的同一个二进制文件来响应。
连接 MCP 服务器介绍了如何连接各个客户端,你的助手能用 Aggrega 做什么介绍了这些工具提供的功能。
aggrega serve 守护进程
aggrega serve 将编译器作为面向编辑器的长时间运行进程来运行。它在多个请求之间保留已解析的文档、已解析的目录和诊断信息,因此编辑器可以提出许多小问题,而无需每次都承担完整加载目录的开销。
该协议是基于标准输入和输出的 JSON-RPC 2.0,每条消息前带有 Content-Length 头,方法位于 aggrega/ 命名空间下。它不是 Language Server Protocol,因为它承载了该协议无处容纳的操作,例如 IR 图请求;编辑器扩展在其编辑器的请求与这些方法之间进行转换,并在合适之处复用该协议的位置(position)、范围(range)和定位(location)结构。会话以 aggrega/initialize 开启,它会报告工作区以及作答的二进制文件的版本;守护进程通过 aggrega/publishDiagnostics 推送诊断;aggrega/shutdown 通知则干净地结束会话。
每个消息体都以 schema 的形式发布,即 https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json,在线路格式参考中有说明;Visual Studio Code 扩展的消息类型即取自于此。其他编辑器只要使用相同的协议即可集成。aggrega serve 参考描述了每个方法、它读取和写入的内容以及它引发的错误。