跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

aggrega serve

aggrega serve 将 Aggrega 作为长时间运行的编译器即服务守护进程运行,用于 IDE 集成。它通过 stdin/stdout 使用 JSON-RPC 2.0 通信,并在多个请求之间保留目录解析器、解析缓存和诊断状态,因此编辑器操作可以获得亚秒级反馈,而无需在每次按键时承担完整的目录加载开销。

该守护进程通常由编辑器扩展作为子进程启动,而不是手动运行。VS Code 扩展是参考客户端;其他编辑器可以通过使用相同的协议进行集成。

协议

线路协议是采用 Content-Length 分帧的 JSON-RPC 2.0,位于 aggrega/ 方法命名空间下。它有意不是 Language Server Protocol——Aggrega 具有 LSP 中没有对应物的领域操作(IR 图查询、缓存失效信号)。编辑器扩展负责在编辑器的 LSP 请求与这些 aggrega/* 方法之间进行转换;在适用之处,复用 LSP 形式的位置、范围和定位值。

有两个方法保留其协议标准的 $/ 名称,而没有改名到 aggrega/ 命名空间中,因为二者都是传输层面的事务,不带任何 Aggrega 含义,已在使用该协议的客户端无需额外处理即可应对:$/cancelRequest 用于停止客户端不再需要答复的请求,$/progress 则是守护进程在长时间操作运行期间报告其进度的方式。二者均在下文说明。

🔴 下文每个请求都携带 workspaceRoot,即其所作用的工作区的绝对路径,各方法中不再重复说明。有三个请求不携带,因为它们的对象不是工作区:aggrega/initialize、aggrega/getSchema 和 aggrega/scaffoldEntity——不过,aggrega/scaffoldEntity 在写入或列出可运行示例时确实会指明工作区。未指明工作区的请求会得到什么,参见每个请求都指明其所涉及的工作区;推送的诊断发往何处,参见声明你希望为其推送诊断的工作区。

**逐字段的结构以 schema 形式发布,请在线路结构参考中查阅。**该页面列出每个方法的参数对象、每个结果和每个通知载荷——每个字段的类型、是否必需及其承载的内容——以及三项适用于整个接口而非单个方法的属性:除各方法自身声明的字段外,每个请求都接受的两个字段,即上文的 workspaceRoot 和监视长时间操作中的 workDoneToken;参数对象若携带其方法不接受的键,会被拒绝,并在拒绝中列出可接受的键集合;以及缺失的集合在何处以 null 而非空集合的形式出现在线路上。该页面由该 schema 生成,因此契约变化时它随之变化。

**本页说明协议,那一页说明结构,二者应结合阅读。**本页包括:分帧、每个方法的用途、其作用范围、写入的内容、引发哪些拒绝及原因、错误码以及各自的处理方式。那一页包括:逐键说明线路上应放入什么。因此,下面的列表列出每个方法并说明调用它意味着什么,而你正在编写的请求的字段列表则在旁边的参考中。

请求:

  • aggrega/initialize——握手。协商位置编码(服务器依次优先 UTF-8、UTF-16、UTF-32,默认使用 UTF-16),接收你为推送诊断声明的工作区,并报告该工作区的根目录、其设置所解析自的配置层,以及解析出该工作区的标记。答复还携带 version,即作出答复的二进制文件的版本:与 aggrega version 为该二进制文件报告的值相同。它描述的是正在运行的进程,因此一旦启动守护进程所用的文件被替换——例如重新构建到同一路径——version 仍指明正在运行的守护进程,而查询该文件得到的是替换后的版本;当你要确认正在与哪个版本通信时,请在此处读取。workspaceRoot 为可选项,它声明一个工作区而非作用于某个工作区——参见声明你希望为其推送诊断的工作区。发送 capabilities.window.workDoneProgress: true 以表明你的客户端能够处理进度通知;答复中的 capabilities.workDoneProgress 会回显该值,若客户端未声明任何内容,则该字段不存在。参见监视长时间操作。
  • aggrega/validate——验证文件内容;返回诊断。release 是相对于工作区根目录的路径,指明用于验证的 Release——与 aggrega/irGraph 接受的值相同,也与从根目录运行时 aggrega build --release 接受的值相同。它是可选的,并决定答复的范围:指明一个 Release,则需要 Release 的检查会基于它运行——目录实体按该 Release 的语境作为单个实体检查,其他任何文档则基于该 Release 的依赖闭包检查;省略它,则答复涵盖文档自身所能满足的检查,并携带 checked 以说明这一点。无论哪种情况,存在但格式错误的值都会被拒绝——绝对路径或解析到工作区根目录之外的路径会被拒绝而不是被解析。参见实时验证。
  • aggrega/diagnostics——返回为某个文件保存的发现结果。如果请求到达时该文件的验证正在运行,答复会等待其完成并报告其发现,因此对于守护进程正在查找问题的文件,答复绝不会给出一切正常的结论。参见在验证运行时请求诊断。
  • aggrega/hover——某位置处实体的悬停内容。release 为可选项,按该 Release 的语境作答——参见按某个 Release 的语境作答。
  • aggrega/completion——某位置处的补全候选项。当光标处按类型指明一个实体时——component 的 type、Feature 附加项的 type、extends: 值、Recipe 或 FeatureRecipe 的 implements:——候选项是你的工作区自身文档所声明的该类型的名称;对于 Component 或 Feature,还包括你配置的 catalog_dirs 所声明的名称,每个只提供一次,并按名称排序。因此,从目录获取其 Components 和 Features 的工作区会得到这些候选项,而不仅仅是其自身编写的内容。在 Manifest 映射的值处提供的 Recipes 和 FeatureRecipes 来自工作区自身的文档。仅存在于制品缓存或注册表中的实体不会被提供:回答补全请求从不执行拉取。release 为可选项,按该 Release 的语境作答——参见按某个 Release 的语境作答。
  • aggrega/resolve——解析某位置处引用的实体(转到定义)。release 为可选项,按该 Release 的语境作答——参见按某个 Release 的语境作答。
  • aggrega/findReferences / aggrega/findImplementations。二者均接受可选的 release,并按该 Release 的语境作答——参见按某个 Release 的语境作答。
  • aggrega/irGraph — 某个 Release 的已编译 IR 图,供编辑器内省使用。release 是相对于工作区根目录的路径,指向工作区内的一个 Release,与从根目录运行时 aggrega build --release 接受的值相同。其他任何形式都会被拒绝,并返回标准的 invalid-params 错误,说明应改为发送什么:绝对路径、解析到工作区根目录之外的路径(无论是按字面写法向上越出,还是经由链接越出,链接指向文件或途经的某个目录均算),以及空值,都会被拒绝而不会被解析,因此请求永远不会报告工作区并不包含的文件。你的工作区配置以 build.authoring_release 或 workspace.releases 的某个键的形式指定的 Release,无论其文件位于何处,都视为工作区所包含的 Release,因此工作区内指向它的链接会被接受,与 aggrega/releaseCandidates 列出它的方式一致。Release 读取的某个目录目录若无法遍历(例如存在但无法读取),会像 aggrega inspect 那样被拒绝,且在读取其他任何内容之前:错误为 1004 entity-not-resolvable,其消息是命令行针对该目录打印的报告,占一行([CATALOG_ERROR] <directory>: catalog load: …),并且不会基于其余目录绘制图。工作区配置列出的某个目录若并不是目录(例如该处什么都不存在),会以同样的方式、在同一时刻被拒绝,返回 1004 entity-not-resolvable,其消息是每个命令对它给出的拒绝,指出该条目、列出它的配置文件和行,以及相应的设置项(本地实体从何处读取)。若某个目录目录中包含一个链接,指向其读取必须限定在内的目录之外(即从别处链接而来的文档或目录,无论位于工作区内的目录目录之下,还是位于配置在工作区之外指定的目录目录之下),则会以同样的方式、在同一时刻被拒绝,返回 1004,并附上该情形自身的说明语句,指出该链接及其指向:不会通过此类链接读取任何内容,而不含该链接绘制的图可能会在其位置解析到另一个同名实体。同样,当 Release 按标识指定其 Aggregate 或 Manifest 时,Release 旁的文档中指向外部的链接也会被拒绝。Release、其 Manifest 或其所扩展的 Release 通过路径(aggregate:、manifest:、extends: 或 parameters 的 $import:)指定的文件,若按字面写法或经由链接越出工作区,会被拒绝,并附上该情形自身的说明语句(fatal-halts.md §“A reference to another file leads out of the directory it must stay inside(对另一个文件的引用越出了其必须限定在内的目录)”),错误的 data 将其定位到 Release 中引出该文件的键上,且不会从该文件读取任何内容;配置在工作区之外指定的 Release 同样被限定在包含它的目录内,因此它或其链中所引出的 Release 所写的、离开该目录的路径也会被拒绝。注意 aggrega/releaseCandidates 返回的是绝对路径,因此在两个接口之间互相传递数据的客户端需要在两者之间转换。此参数拒绝逐文档参数 file 和 uri 所接受的某种写法,这是有意为之,你发送的参数接受哪些写法说明了其依据。图会隐去作者声明为敏感的每个值,与命令行上 --ir-graph 的隐去方式完全相同:每个值都被替换为 aggrega-inspect “Machine-readable output”所描述的标记,其余内容则按编译器记录的原样携带。unredacted: true 请求以明文返回这些值,它是命令行 --unredacted 在协议中的写法,也是唯一的请求方式;缺省或为 false 时,响应会隐去这些值。响应所到达之处随后都会携带明文值,因此客户端只应在其使用者已提出请求时才请求它们。
  • aggrega/build — 编译一个 Release,并将其产物写入工作区的输出目录,即从工作区根目录运行 aggrega build 时写入的同一目录。release 遵循与上文相同的约定。它在所有检查门均开启的情况下渲染,因此命令行构建会因之中止的偏差在这里同样会中止。Release 读取的目录中无法遍历的 catalog 目录(例如存在但无法读取的目录)会像 aggrega build 那样被拒绝,且在写入任何内容之前:不产生任何产物,设置了 autoPull 时也不产生 lockfile。工作区配置列出、但实际上并不是目录的目录也同样被拒绝,所用措辞与 aggrega build 拒绝它时相同(Where local entities are read from)。该拒绝与 aggrega/irGraph 对同一目录给出的拒绝相同,即 1004 entity-not-resolvable,并附上命令行报告(单行);指向 catalog 目录读取范围之外或 Release 旁文档之外的链接,会像 aggrega/irGraph 那样被拒绝,且不写入任何内容。响应会指明其写入的 outputDirectory 和写入的 files(均相对于该目录并已排序),以及运行中产生的所有 notices;带有文档位置的发现则改由 aggrega/publishDiagnostics 传递。在渲染过程中拒绝的 Release,其响应即为该拒绝,使用编译器的原话并包含所有原因,且该拒绝会发布到其所指向的位置——参见 A refusal raised while rendering。设置了 autoPull 时,响应还会携带 dependencyResolution,即与 aggrega/resolveDependencies 响应相同的报告,因此在构建过程中填充依赖的客户端无需再次请求即可读取已固定的内容——以及本次构建的解析从何处获取每个引用,这是关于该次运行的事实,lockfile 不会记录。每条 notice 都携带产生它的环节的 class——deprecation、catalog、catalog-lint、extends、release-composition,或对下文依赖解析产生的行使用 dependency-resolution——守护进程无法命名该环节时则为空 class,客户端此时应直接呈现 text,而不是猜测最接近的匹配。写入时在输出目录中、或在其下它写入过文件或经过的目录中发现的、并非由本次构建写入的文件,会保留在原处,并在运行自身的各条 notice 之后,以一条位于空 class 下的 notice 列出,所用句子与 aggrega build 打印其警告时相同——参见 构建未写入的文件;files 从不列出它们。outputParent 指明产物在工作区内的位置,其名称即其全部含义:它是创建输出目录的所在目录,因此发送 docs 会将产物写入 docs/dist,而不是 docs 本身——与在终端中于 docs 下运行构建的结果完全相同。省略它时,构建写入的位置与在工作区根目录运行时相同。它与此处其他写入请求所接受的 outputDir 含义不同,而且是有意为之:后者指明写入其中的目录,而本参数指明该目录的父目录,二者名称不同,因为它们是不同的东西。它仍是工作区内的目标位置,因此绝对路径、越出根目录的值,以及通过链接越出根目录的值(根目录外的链接目录,或其下尚未创建的目录)都会被拒绝而不予解析。在其中创建的输出目录以及构建写入其中的每个文件同样受限于工作区:若其中任何一个通过链接越出工作区,构建会以 1004 被拒绝,并附上该条件自身的语句,指明该链接及其指向,且不清理或写入任何内容。autoPull 在渲染之前解析 Release 的依赖,与 aggrega/resolveDependencies 执行的解析相同,且除非请求要求,否则为关闭状态,与命令行自身的默认值一致;未设置时,没有 lockfile 的 Release 会以 lockfile-absent 错误被拒绝,并指明应运行的命令。设置 autoPull 后,此请求会访问 registry 并写入 lockfile——参见 Reaching a registry, and writing。先进行解析的请求仍只渲染 Release 一次:查明一个 Release 使用了哪些远程引用本身就是一次渲染,因此解析已渲染了构建所涉及的内容,构建直接基于该次渲染给出响应,而不再重复渲染。policyInput 指明工作区内的一个目录(相对于其根目录),无论构建完成还是中止,构建都会另外将每个治理角色交给挂接于该处的插件的载荷写入该目录——即 aggrega build --policy-input 写出的那些文件,名称相同;随后响应的 notices 会说明写入了多少个文件,并在空 class 下指明每个未写入任何文件的角色。**请求失败时,已写入的文件留在磁盘上,而这份说明不在回复中:**错误信封只携带拒绝本身。它是一个目标位置,因此绝对路径或越出工作区的值会在任何操作运行之前被拒绝。
  • aggrega/buildPreview — 报告一次 Release 构建将会写入的内容,但不写入任何内容。release 遵循与上文相同的约定。它执行与 aggrega/build 相同的计算,使用相同的检查门,因此一个 Release 要么在两者中都会被拒绝,要么在两者中都会得到报告——正因如此,在两者之间的选择是关于输出的选择,而非关于严格程度的选择。Release 读取的目录中无法遍历的 catalog 目录,或包含指向其读取范围之外的链接的 catalog 目录,会以相同方式被拒绝,且在渲染任何内容之前;工作区配置列出、但实际上并不是目录的目录也同样被拒绝,与 aggrega/build 相同。响应携带 files,即构建将会输出的、相对于输出目录的名称(已排序),以及所有 notices;不存在 outputDirectory,因为没有写入任何位置可供指明。在渲染过程中拒绝的 Release,其响应和发布方式与 aggrega/build 完全相同。它拒绝 autoPull,返回 invalid-params 错误并指明应改为发送的内容:填充依赖会写入 lockfile,而此请求不写入 lockfile。它不访问任何 registry。policyInput 是它唯一会进行的写入,且仅在发送该参数时进行:它会与 aggrega/build 完全相同地将治理载荷写入该目录——即 aggrega build --dry-run --policy-input 写出的文件——不触动输出目录和 lockfile,在 notices 中给出相同的说明,并受相同的限制:请求失败时,已写入的文件留在磁盘上,而这份说明不在回复中。
  • aggrega/resolveDependencies — 将 Release 的 catalog 依赖和源依赖解析到缓存中,把其渲染所使用的外部输入固定到内容寻址存储中,并写入其 lockfile。release 是相对于工作区根目录的路径,与 aggrega/irGraph 接受的值相同,被拒绝的形式也相同。upgrade 丢弃已记录的固定版本并重新解析,将每个依赖浮动到可用的最高版本;targets 将其范围缩小到所指明的实体引用,其他固定版本均保持不变。verify 将已记录的解析与本请求在不带该参数时会执行的解析进行比对,以相同方式遵循已记录的固定版本,且不写入 lockfile、plugin trust record 或 entity.lock——缓存的读取和填充与不带该参数时相同——响应为 verified: true 以及 lockfile 记录的 toolchain。verify 与 upgrade、与 targets、与 pinSources(无论其取值如何)同时出现时,会以 invalid params 被拒绝,且在解析任何内容或报告任何进度之前:升级会丢弃 verify 所要遵循的固定版本,指明的目标只有在升级时才会重新解析,而 pinSources 决定解析是记录 entity.lock 中缺失的固定版本还是因此拒绝,而不写入 entity.lock 的比对不会做这两件事中的任何一件。命令行和助手工具拒绝相同的组合。响应会指明其写入或比对的 lockfile,以及其固定的每个引用,分列于 entities、libraries 和 plugins 中,每个条目携带其解析到的 version 及其 source——即本次运行从何处获取该引用,使用 aggrega pull --detail 对同一解析打印的词:fetched-fresh、cache-reuse、local、in-binary 或 external——此外还有 sourceArtifacts、trustedPlugins、externalInputs(运行完成后 lockfile 固定的外部输入数量,既包括沿用的,也包括本次运行发现的),以及解析产生的所有 notices。🔴 成功的响应本身并不意味着外部输入的固定已经完成。 若运行固定了所有依赖,但未能完全查明 Release 使用了哪些外部输入,它会以 incompleteExternalInputs 说明是什么中止了发现过程,且仍以成功响应——依赖的固定已完整并已写入磁盘,若将整个请求报告为失败,就会让你重做已经正确完成的工作。**在将 lockfile 视为已完全固定之前,请先读取该字段:**没有遗漏未发现的内容时该字段不存在,因此它的出现本身就是信号。不存在 catalog 目录参数:搜索栈即工作区所配置的搜索栈。这是会话中针对一个 Release 的唯一固定请求,外部输入也在这里固定——渲染使用哪些 URL 取决于它渲染的内容,因此本请求会渲染该 Release 以查明这一点,之后的构建请求则基于其记录的内容提供服务。若 Release 构建的某个 Recipe 或 FeatureRecipe 的 entity.lock 未记录该实体所读取的某个输入的固定版本,请求会被拒绝,并指明 aggrega pin 以及每个未记录的输入;pinSources: true 则改为对这些实体执行该固定步骤,在每个实体旁写入 entity.lock——与 aggrega/pin 执行的步骤相同,写入的字节也相同。省略时,pinSources 遵循工作区的 pin_sources_at_pull;发送时,它会在两个方向上覆盖该设置,因此即使在配置为固定的工作区中,false 也会拒绝。此请求会访问 registry 并写入——参见 Reaching a registry, and writing。
  • aggrega/pin — 在 Recipe 或 FeatureRecipe 旁的 entity.lock 中,记录该实体从其自身文档之外读取的每个输入的内容固定:坐标完整写出的远程源、artifacts 条目导入的文件,以及本地源为该实体的发布内容所贡献的每个文件。它与在终端运行 aggrega pin 的步骤相同,写入的字节也相同。entity 为必填项,是相对于工作区根目录、指明实体文档的路径,被拒绝的三种形式与 release 相同。不指明任何 Release:坐标不含模板的远程源对使用该实体的每个 Release 都指向同一个产物,因此固定它无需任何 Release 提供的内容,而坐标来自模板的远程源则由 aggrega/resolveDependencies 按 Release 固定;以模板形式编写的本地源会贡献实体目录中的每个文件,这些文件均在此处固定。dryRun 解析输入,并以 content 返回该步骤将会写入的锁内容,不在实体旁写入任何内容;内容缓存仍会被填充。响应携带 entity、kind、name 和 pinnable——对于不读取任何需由锁记录内容的类型,其值为 false,此时实体旁不会有任何改动,其他字段均不存在——否则携带其写入的 lock、changed(锁已记录所有固定且保持字节不变时为 false)、removed(实体现在不再读取任何需由锁记录的内容且其锁已被删除时出现),以及 pins,每类固定一个条目,附锁中所含的数量。实体文件本身永远不会被写入。此请求会在工作区内的实体旁写入,并访问实体的源所指明的主机——参见 Reaching a registry, and writing。
  • aggrega/cacheStatus — 磁盘缓存中保存的内容:每个缓存元素一个条目,附其大小,以及(如有)其内容摘要,按类别分组。只接受工作区,不接受其他参数。每个类别携带一个 reach——workspace 表示位于此工作区自身缓存目录下的产物缓存,machine 表示机器上所有项目共享的已编译模块、plugin-describe 和文档包存储——scope 则直接指明机器范围的类别。它不写入任何内容。关于为何在不改变任何内容的响应中也包含 reach,参见 Reaching a registry, and writing。
  • aggrega/cachePrune、aggrega/cacheEvict、aggrega/cacheClear — 回收缓存内容。prune 删除任何工作区 lockfile 都未引用的内容;evict 将已编译模块存储裁剪到 maxSize,这是一个字节量,写法与命令行相同(5GiB、512MiB 或字节数);clear 清空本会话涉及的所有缓存。每个响应都会指明其删除的内容,每项删除都携带其所属类别的 reach,且每个响应都携带 scope。每个响应还会指明因被其他进程打开而保留的内容——Windows 拒绝删除已打开的文件,此时操作会继续处理其余内容而不会失败:prune 或 evict 会在 heldOpen 中列出这些条目,clear 则针对其清空的每个缓存,在 heldOpenFiles 中计数保留的文件,并在 heldOpenBytes 中给出其大小。在其他平台上,该列表为空、计数为零,之后的运行可以回收保留下来的内容。这些请求的影响范围超出工作区——参见 Reaching a registry, and writing。
  • aggrega/registryList — 此工作区配置可访问的 registry:每个条目的主机、可选别名、是否为默认值、以离散字段表示的信任策略,以及该主机的凭据是否存在。只接受工作区,不接受其他参数。它不联系任何 registry。凭据状态仅报告是否存在——从不报告凭据本身、其形式,也不报告 registry 是否会接受它,因为那需要一次列表操作不会进行的网络往返——且凭据状态读取自机器范围的凭据存储,credentialStateIsMachineWide 会明确说明这一点。
  • aggrega/search — 搜索已配置注册表的本地索引。每个字段都用于缩小范围,且都是可选的,因此空的 params 对象会请求索引中的全部内容。它不访问网络:索引是写在此工作区自身缓存目录下的离线快照。报告的版本就是解析时会选取的版本——撤回记录带有此工作区所信任签名的版本会被排除,并在 retracted 中列出——回答还附带自身的来源信息:indexes 给出每个被搜索注册表的快照时长,stale 标记值得刷新的快照,missingIndexHosts 列出没有本地索引的已配置注册表,因此这些注册表的内容不在回答中。
  • aggrega/registryAdd — 注册一个注册表及其签名信任策略。host 为必填项;其余字段决定策略或写入目标。keyPath 和 trustedRoot 指定文件:绝对路径(例如在对话框中选取的文件)按其所指位置读取;相对路径指工作区内的文件,相对于工作区根目录而非守护进程运行目录解析,越出根目录或经由链接通向根目录之外的路径会在读写任何内容之前以 invalid-params 错误被拒绝。相对的 trustedRoot 会被记录为它在工作区中所指的文件,因此无论之后的验证在哪个目录运行,该条目都指向那个文件。缺少该键时,fetchTrust 默认为 true,与命令行一致,并在首次连接时采用注册表自身公布的策略;回答中的 trust 说明发生了什么——策略已固定、注册表未公布策略(若旁边有 unreachable,则表示根本无法连接)、以官方 hub 的内置基线代替固定,或未尝试获取。该注册与 aggrega registry add 执行的注册相同:在相同的网络策略下进行相同的获取,逐字节写入相同的条目。在离线工作区中,获取会在发起任何连接之前被拒绝,因此不会询问注册表,并且官方 hub 以外的注册表会被拒绝,除非请求提供 identities 或 keyPath,这两者会原样注册所发送的内容且不进行获取:错误消息就是命令行打印的那句话,前面加上该条件的短代码 E0310——本请求中凡指明条件的拒绝,其消息都以短代码开头——且不写入任何内容。官方 hub 仍会基于其内置基线写入,回答中 trust.baseline 为 true,trust.reason 说明由于工作区处于离线状态而未向 hub 询问其信任策略——这正是命令行提示开头的原因说明——且没有 notAdvertised,因为从未询问过 hub。默认情况下,此请求会写入全局配置——参见连接注册表与写入。
  • aggrega/registryRemove — 删除一个注册表的条目,按主机名或友好别名指定。不匹配任何条目的标识会被拒绝,而不是在配置未变的情况下作为成功返回。默认情况下,此请求会写入全局配置——参见连接注册表与写入。
  • aggrega/logout — 移除某个注册表已存储的凭据,与 aggrega logout 在终端中执行的移除相同。registry 为必填项,指定你进行身份验证时所用的注册表主机;这里没有友好别名可解析,因为凭据存储以客户端进行身份验证的地址为键,而非以配置中的任何名称为键,所以即使某个主机未被任何工作区配置,也可能有可供移除的凭据。对于存储中没有凭据的主机,移除会成功,且不会重写任何内容——调用方要求某主机没有凭据,它已得到所求,因此这是一个回答而非错误,终端命令也是如此。回答包含 registry 和 scope。它不以任何形式包含凭据的任何部分,也不报告此前是否存在凭据:要确定这一点需要再读一次存储,而没人要求这样做,因此当问题在于是否存在时,请使用 aggrega/registryList。它不联系任何注册表——移除已存储的凭据是本地操作,不会询问该注册表是否会接受该凭据。此请求会更改本机所有项目共享的凭据存储——参见连接注册表与写入。
  • aggrega/registryUpdate — 刷新 aggrega/search 读取的本地可搜索索引。缺少 registry 时刷新所有已配置的注册表;指定一个则只刷新该注册表。upgrade 会完整地重新读取每个仓库,不与已写入的索引做任何比较;不带它的刷新本就会重新读取所有发生变化的内容。回答包含每个主机的记录数、无法读取的仓库(每个都附有 reason,在有的情况下以该读取最后一次失败的类型开头)、readsRetried(注册表在过程中拒绝或丢弃、随后被再次请求的读取次数,每个读取只计一次,为零时同样给出)、遇到的弃用标记、失败主机的 error(无法连接该注册表时旁边附有 unreachable),以及 indexRoot,即索引写入的位于此工作区自身缓存下的目录。此请求会连接它刷新的每个注册表——参见连接注册表与写入。
  • aggrega/publishEntity — 将一个目录实体打包并发布到注册表。entity 是相对于工作区根目录的路径,指明要发布的文档,其拒绝情形与 release 相同,共三种:缺失、绝对路径、或解析到根目录之外。Plugin 实体还需要 plugin,它是同类路径,指明发布在该实体自身清单中的可执行文件。registry 是发布目标,默认为工作区配置的注册表。dryRun 会计算出包以及发布它将得到的摘要,且不联系任何注册表。省略 sign 时遵循目标注册表自身的策略,这与命令行在未给出该标志时的行为一致;发送它则由调用方决定——两者都不会放宽拒绝,因为要求签名的注册表或工作区策略无论该字段如何都会拒绝未签名的发布。pinSources: true 会在打包前对实体运行实体作者的固定(pin)步骤,因此该步骤写在实体旁边的 entity.lock 也是发布内容的一部分——这与 aggrega/pin 运行的步骤相同。它在任何评判实体内容的拒绝(签名策略、不可变性保护)之前运行,因此在那里被拒绝的发布仍会留下已写入的锁文件;关于请求本身的拒绝,例如工作区处于离线状态或没有发布目标,则会先发生且不固定任何内容;对于与另一个实体共享目录的实体,其拒绝同样如此,因为该步骤不得向这样的目录写入锁文件。缺省时,它遵循工作区的 pin_sources_at_push;发送时,它在两个方向上覆盖该设置。在 dryRun 下,该步骤报告它将写入的锁文件,但不写入任何内容。不运行该步骤的发布,会在打包任何内容之前拒绝其 entity.lock 未为所读取的某个输入记录固定值、或该输入已不再匹配的 Recipe 或 FeatureRecipe——在 dryRun 下同样如此——并指明 aggrega pin、pinSources 和 pin_sources_at_push;这与 aggrega/resolveDependencies 针对同一锁文件给出的拒绝相同。应答包含 reference、tag、kind、mediaType、size 对、已发布的 digest(在 dryRun 下为该发布将得到的摘要,即 aggrega push --dry-run 打印的摘要)、signed、alreadyPublished、dryRun 和 reach;在该步骤运行时包含 pin(与 aggrega/pin 给出的应答相同);在实体的本地源以模板形式编写时包含 wholeDirectorySource,按编写原样指明该源。这样的源只有在某个 Release 填充模板后才会确定其目录,因此发布会携带实体目录中的所有文件,而不仅是实体指明的文件,调用方正是通过该字段得知这一点的——试运行时同样如此。当发布所携带的归档中包含 Windows 无法按原样保存的条目时,应答还包含 windowsUnusableEntries:即路径中某一部分以设备命名(例如 CON、AUX 或 NUL,不区分大小写,无论后接什么扩展名),或某一部分以句点或空格结尾;它会逐一列出这些条目,先列实体文档自身的文件名,再列它携带的文件;没有此类条目时该字段缺失,仅以文档本身发布的实体也属于这种情况。在 Windows 上运行的 aggrega 会拒绝解包此类条目,因此 Windows 工作区无法使用该版本。这些正是 aggrega push 发出警告的条目,要求接收报告的请求会在发布进度中读到相同的警告行;两者都不会拒绝任何内容,因此发布会照常进行或被拒绝,与没有这些条目时完全一样,在 dryRun 下同样如此。此操作会写入注册表并触及本机之外,运行固定步骤时还会在实体旁边写入内容——参见访问注册表与写入。
  • aggrega/publishArtifact — 发布一个独立的数据制品,例如文档包。file 是相对于工作区根目录的路径,遵循相同的约束,其字节按原样发布:不解析实体封装,也不按种类分派。name 和 tag 指明发布时使用的名称,二者均为必需。mediaType 默认为文档包类型。应答包含 reference、tag、mediaType、size 对、已发布的 digest、alreadyPublished、dryRun 和 reach。它不签署任何内容——已发布的制品之后通过 aggrega/signArtifacts 按引用签名,后者只需要本应答报告的引用。此操作会写入注册表并触及本机之外——参见访问注册表与写入。
  • aggrega/signArtifacts — 为已发布的制品签名并附加每个签名。references 携带一个或多个注册表地址而非路径,因此不适用相对于工作区的约束;空列表或其中的空条目会被拒绝。整批使用同一个身份,并在签署任何引用之前解析,因此完全没有可用凭据的批次会在开始时就被拒绝,而不是在中途失败。引用需要不同凭据的批次同样如此:请求不指明密钥,因此这种情况是工作区配置为某个引用所在注册表指定了一个已持有的密钥,而为另一个引用的注册表未指定密钥或指定了另一个密钥——此时不签署任何内容,拒绝信息会指明两侧的注册表,如 References signed together need different signing credentials(一同签名的引用需要不同的签名凭据) 所述。对未发布任何内容的引用签名会被拒绝,而不是附加到空无一物之上;已带有其注册表信任策略可验证的签名的引用会保持原样,并计为已签名,如 aggrega sign 所述。jobs 为可选参数,表示同时签名的引用数量:缺省时逐个签名,小于 1 的值会在读取任何引用之前以 invalid-params 错误被拒绝。每个引用仍会完全像单独签名时那样被签名,如 aggrega sign 所述,且请求报告的进度和应答都保持引用给出的顺序。应答包含 signed,其中每个条目指明一个 reference 及其签名所承诺的已发布 digest,另有 reach;任何引用失败的批次都会以失败作答并指明每一个失败的引用,而不是返回一个较短列表的结果。此操作会写入注册表并触及本机之外——参见访问注册表与写入。
  • aggrega/deprecateArtifact — 为已发布的制品附加一个已签名的弃用标记。可以发送单个 reference 及其 severity 和 reason,或者发送 from 指明一个相对于工作区根目录的批处理文件——同时发送两者会被拒绝。内容字段为必需,而不会提示输入:没有人在监看此数据流,因此缺少某个字段的请求会被拒绝,并指明应发送什么。这些字段只属于单个 reference:批处理文件在其各自的条目中携带每个标记的内容,因此与 from 一起发送的 severity、reason、replacement 或 message 会作为无效参数被拒绝,并逐一指明所发送的字段,而不会被忽略。两个签名请求所接受的无密钥输入在此同样适用,因为标记按其自身摘要签名;批处理文件中的条目也须使用同一凭据,与签名批次中的引用完全一样。应答包含 marked,其中每个条目指明被撤回的 reference、其 severity、issuedOn 时间戳以及标记自身的清单 digest——标记作为其所撤回制品的无标签引用者附加,因此没有其他方式可以寻址它——另有 reach。此操作会写入注册表并触及本机之外——参见访问注册表与写入。
  • aggrega/catalogIndex — 实体索引:请求所指定的工作区中每个实体的 kind、name、apiVersion、description、labels、源文件和 origin。接受工作区,并可选接受 release:该集合是这个工作区根目录及其所配置的目录目录(catalog directories)的属性;若提供 release,则是配置为该 Release 指定的目录的属性——参见以某个 Release 的视角作答。它涵盖实体的两个来源——工作区根目录下的 Aggrega 文档,以及所配置的目录目录所包含的 Features——因为客户端需要实体的描述性字段时,正是基于这个接口进行关联,而只知道其中一处的索引会使每个候选列表中的一部分无法解析。工作区中的文档只有在同时声明了 kind: 和 metadata.name,且未声明属于其他项目组的 apiVersion 时,才算作实体,因此恰好位于目录树中的 YAML——chart 的 values 文件、CI 配置、渲染后的 Kubernetes 清单——会被跳过而不会列出。完全未声明 apiVersion 的文档会被报告:它是一个缺少字段的 Aggrega 文档,看到它被列出,你才能发现它需要修复。关于 origin 和空的 file 的含义,参见如何寻址一个实体。不会读取位于指向工作区根目录之外的链接背后的任何文档:根目录之外的目录不会被搜索,根目录之外的文件无论声明什么都不会被读取,因此编辑器在此类链接下显示的实体不会被列为工作区自身的实体——也不会由读取相同文档的 aggrega/attachCandidates 或 aggrega/connectionCandidates 提供,即使编辑器正打开着该文档。无论该文档声明什么,这一点都成立。唯一的例外是工作区配置所指定的 Release——作为 build.authoring_release,或作为 workspace.releases 的键,按链接所指向的文件来判断,因此指定链接或指定该文件效果相同——它会从链接所指向的文件中读取,在链接自身的位置列出(与 aggrega/releaseCandidates 列出它的方式相同),且不会被点名;上述设置所指定的文件若声明的不是 Release,则不会被列出,其链接会被点名。所配置的目录目录是工作区读取存放在别处的其他实体的方式,因此指向配置在 catalog_dirs 下所列目录(无论是为工作区还是为某个 Release)的链接,不会像工作区自身文档那样被搜索,也不会被点名:配置已经覆盖了它,其 Features 会从目录中列出,与每个已配置目录目录的 Features 一样。从目录目录列出的 Features 绝不包括位于指向目录目录读取范围之外的链接背后的 Feature——对于工作区内的目录目录,该范围是工作区;对于配置指定在工作区外的目录目录,则是该目录本身——因此,响应中标明位于未读取链接背后的实体,绝不会同时以该名称被列出。响应在 unreadLinkedDirs 中列出每个指向目录的此类链接,在 unreadLinkedFiles 中列出自身名称以 .yaml 或 .yml 结尾且指向文件的此类链接——路径相对于根目录、为链接所在位置,顺序与工作区搜索顺序一致——以便客户端说明原因。因名称、所在位置或 .gitignore 而被搜索排除的链接不会被点名;在以某个 Release 视角作答的响应中,仅由其他 Releases 读取的目录目录下的链接也不会被点名。工作区外目录目录下的链接没有相对于根目录的位置可供点名,因此不会被点名。这两个字段始终存在,没有此类链接时为空。若工作区自身的配置文件,或其旁边由 CI 拥有的覆盖文件,本身就是指向工作区之外的链接,则无论搜索如何处理,该文件都会在 unreadLinkedFiles 中被点名,且索引就是不带任何配置的工作区自身读取结果——不会为其读取任何目录目录,以某个 Release 视角的索引请求会被拒绝;参见工作区根目录与活动 Release。
  • aggrega/entityDefinition — 指定实体解析的结果:其 kind、自身的 name 和 version、存在时的 description 和 publishScope、声明它的 file、其背后编写文本的 authoredLength,以及已应用继承的 YAML 文档形式的 definition。file 对每种 kind 都会报告,是一个你可以打开的路径——对于根目录内的文档相对于工作区根目录,对于根目录外的文档则为绝对路径,详见报告的路径如何书写。只有一种情况下它为空:从注册表解析的实体在本机上没有可指明的编写文档。authoredLength 回答的是另一个问题——解析保留了多少编写文本——且只有 Aggregate 会带有该内容,因此请将两者分开解读,而不要视为一对。name 是实体的标识,写法与一个实体引用另一个实体时相同,可以带有版本后缀。这是此处唯一从名称而不是从光标出发的请求,因此当你已经知道所指的实体时,应使用它。release 为可选,按该 Release 的视角解析名称——参见以某个 Release 的视角作答。解析不到任何内容的名称会被拒绝,而不是以空文档作答;参见区分两种按名称的拒绝。name 也可以是注册表引用——oci://<host>/<repository>:<tag>,或以 @<digest> 代替 :<tag>——此时响应是发布在该坐标上、从其注册表读取的实体,并由 published 指明所读取的内容;参见查询某个坐标。
  • aggrega/releaseClosure — 一个 Release 的依赖闭包:它触及哪些实体及其解析后的版本,位于 entities、libraries 和 plugins 中,同时包含其两个指针解析到的 aggregate 和 manifest 标识、解析过程中产生的 mappingDiagnostics,以及在其锁文件和其旁边的插件信任记录中针对其所触及内容记录的 deprecations,因此以裁决角色挂载的已撤回插件会像已撤回的固定引用一样被指明。release 是相对于工作区根目录、指定根目录内某个 Release 的路径,与 aggrega/irGraph 接受的值相同,被拒绝的情形也相同,并且出于同样的原因需要锁文件。不会渲染任何内容。其条目不指明 source:它们说明的是该 Release 依赖什么,而不是某次运行做了什么,后者由 aggrega/resolveDependencies 报告。参见闭包不是图,因为已经接收图的客户端并不具备这些信息。
  • aggrega/attachCandidates — 哪些 Features 可以挂接到某个节点:即其声明的适用条件能被该节点标签满足的那些。请恰好发送一个坐标。node 按 metadata.name 指定一个工作区文档;graphNode 按 release 的编译图为节点所用的键 id,指定该图上的一个节点;labels 直接携带一个标签集而不指定任何东西,供已持有标签集的客户端使用。响应会重复它所回答的坐标(没有可重复的坐标时为空),携带 nodeLabels,即匹配所依据的标签对,携带 labelSource,说明这些标签属于哪一类标签集,并以用于定位的 kind、name、源文件和 origin 给出每个候选项。把标签一并返回,使答案本身即可审计:客户端无需自行推断节点的标签,就能解释为何提供了某个 Feature,而自行推断正是客户端的答案与编译器的答案产生分歧的原因。对于图节点,可提供的 Features 是该节点所在 Release 所触及的那些。在 graphNode 之外,connection 指定该节点的 component 所建立的一个连接(其 socket 和 alias),此时答案还会携带 slots,即该连接的 socket 声明的每个槽位及可填入该槽位的 Features;若没有可填充的槽位,则携带 noSlotReason。参见挂接候选响应告诉你什么。
  • aggrega/connectionCandidates — 指定的实体可以连接到什么。node 是实体的 metadata.name,与 aggrega/attachCandidates 以该名称接收的坐标相同。参见下文连接候选响应告诉你什么,因为答案的两部分完整程度不同,响应会说明哪部分是哪种。
  • aggrega/insertionPoint — 在已编写的文档中,某个指定容器下的新条目应放在何处,其表达方式使客户端无需自行解析文档即可应用。file 指定工作区包含的一个文档,可以是相对于工作区根目录的路径、绝对路径或其 file:// 地址;根目录之外的文档,无论是按原样写出的,还是经由一个通向根目录之外的链接(指向该文件,或指向途经的某个目录),不论用哪种写法指定、也不论你是否持有其副本,都会被拒绝;container 是从文档根到条目所在容器的结构路径,每个元素是一个映射键或以十进制书写的序列位置。该路径由你提供——守护进程读取文档自身的结构,绝不根据某物的名称推断它应放在何处。参见插入点响应告诉你什么,因为仅凭位置不足以应用编辑。
  • aggrega/attachmentContainer — 某个节点的 Feature 挂接应写入哪个文档,以及该文档中的哪个容器。graphNode 按 release 的编译图为节点所用的键 id 指定该图上的一个节点,两者都是必需的:节点 id 是某个 Release 的图的键,离开该图便没有意义。答案携带 node、file 和 container——一个段列表,形状与 aggrega/insertionPoint 接收的完全相同,因此两者可直接组合,中间无需任何推算。若要挂接到该节点的 component 所建立的某个连接上,请添加 connection,包含其 socket、alias 和 document(aggregate 或 release),答案随后会指出该文档中该连接自身的 features 容器。参见挂接容器响应告诉你什么,因为 file 是答案的一部分,而不是你事先已知的内容。
  • aggrega/connectionAtPosition — Aggregate 或 Release 中的某个位置落在哪个连接的条目之内,并以上述两个请求接收连接的方式作答。file 按 aggrega/insertionPoint 的方式指定文档,且优先读取会话为其持有的内容;position 是文档中的位置,即按会话编码从零计数的 line 和 character;release 指定其编译图记录了这些连接的 Release,对于 Aggregate 中的位置也是必需的,因为图节点和连接只存在于编译图上。答案携带 graphNode 和 connection(其 socket、alias 以及读取该位置所在的 document),可原样交给 aggrega/attachCandidates 和 aggrega/attachmentContainer;若该处没有写入连接,则携带 noConnectionReason。参见某位置连接响应告诉你什么。
  • aggrega/editDocument — 对已编写的文档应用一次有界的结构化编辑,保留其未触及的每个字节。它是上述两个定位方法的另一半:那两个方法说明条目应放在何处,由你组合并应用;这个方法则组合并应用一次编辑。edit 指定四种之一——add-component、attach-feature、wire-edge、set-value——超出这些的值会被拒绝而不会被解释;node 是从文档根开始的结构路径,即一个段列表,形状与 aggrega/insertionPoint 接收的完全相同;name 是条目写入时所用的键,value 是它携带的内容,其含义由 edit 决定;socket 仅在 wire-edge 时读取,其他情况下忽略。dryRun 执行普通请求的所有操作,唯独不写入,并以 content 返回编辑后的文档,供先把结果呈现给作者的客户端使用;此时不会创建任何内容,written 为空。file 以相对于工作区根目录的路径或绝对路径指定文档,根目录之外的文档——无论是按原样写出的,还是经由一个通向根目录之外的链接(指向该文件,或指向途经的某个目录)——都会被拒绝,且不读取或写入任何内容。这会写入你指定的、位于工作区内的文档——在任一交付方式下,它都不解析任何依赖、不访问任何 registry、不触及任何网络,并且只有组合后的文档通过其自身种类 schema 的校验时才会写入。参见文档编辑响应告诉你什么,因为默认行为是写入,而拒绝会让文件逐字节保持原样。
  • aggrega/releaseCandidates — 请求所指定工作区中的 Release 文档,以绝对路径给出。只接受工作区,不接受其他参数:该集合是该工作区根目录的属性。成员资格由文档类型决定(文件的 kind: 为 Release),而不是由文件名决定,因此没有使用约定前缀命名的 Release 也会被列出,而仅仅名称像 Release 的文件不会被列出。这正是编辑器的“选择哪个 Release?”选择器应列出的内容,因为它与下文活动 Release 级联所选择的集合相同。答案还包含 lockfiles,它将每个列出的 Release(键恰好是 releases 列出它时使用的字符串)映射到其 lockfile 的绝对路径;该字段始终存在,当工作区不含 Release 时为空对象。答案还包含 unreadLinkedDirs,以相对于根目录(即链接所在位置)的路径列出每个这样的链接:它位于列举时会读取目录的位置,并指向工作区根目录之外的目录。根目录之外的目录不会被搜索,因此编辑器在这类目录中显示的 Release 不会被列出,而此字段让选择器能够说明原因。指向工作区配置中 catalog_dirs 所列目录的链接不会被列出:配置已经覆盖了它,它是作为目录库(catalog)目录,而不是存放 Releases 的位置。该字段始终存在,没有此类链接时为空。此外,unreadLinkedFiles 以同样方式列出每个自身名称以 .yaml 或 .yml 结尾、并指向工作区根目录之外文件的链接:无论此类文件内容是什么,都不会被读取,因此仅通过这类链接才能到达的 Release 不会被列出,下文级联中的单 Release 步骤也不会计入它。例外是工作区配置将其命名为 Release 的文件(作为 build.authoring_release,或作为 workspace.releases 的键;按链接指向的文件判断,因此命名链接或命名该文件效果相同):只要它声明的是 Release,就会被读取并在链接自身的位置列出,且不会出现在此字段中;声明其他内容的文件不会被列出,其链接会被列出。该字段始终存在,没有此类链接时为空。如果工作区自身的配置文件,或其旁边由 CI 拥有的覆盖文件,本身就是指向工作区之外的链接,那么无论搜索如何处理它,该文件都会在此列出,并且列举将在没有任何配置的情况下进行,因此配置原本会通过链接命名的 Release 不会被列出;参见 工作区根目录与活动 Release。参见 Release 的 lockfile 在哪里。
  • aggrega/activeRelease — 请求所指定的工作区指向哪个 Release,以绝对路径形式放在 release 字段中,供客户端决定默认选择什么。只接受工作区,不接受其他参数。该字段始终存在,空值表示工作区未指向任何 Release;这是一个成功的答案而不是错误,因此每次守护进程重启时刷新此信息的客户端不会被迫把普通工作区当作失败处理。当值为空时,答案还包含 reason(对级联查找内容的一行摘要)和 trace(逐步骤的说明);当解析出 Release 时,两者都会省略。当解析出 Release 时,答案改为包含 lockfile,即该 Release 的 lockfile 的绝对路径;未解析出时省略。它所指定的 Release 不必是 aggrega/releaseCandidates 列出的那些:标记文件可以指定位于该列表排除的目录(例如 vendor/)中的 Release,或者没有 YAML 扩展名的 Release,因此客户端应从此答案中读取默认 Release 的 lockfile。参见 Release 的 lockfile 在哪里。请直接请求此答案,而不要根据级联的某个输入自行推算:级联最终未采用的输入所指定的 Release 与它选中的不同。答案在你请求时计算,因此在写入标记、编辑配置或添加 Release 文件之后再次请求,报告的是新答案,而不是守护进程启动时工作区的状态。
  • aggrega/setActiveRelease — 通过写入请求所指定工作区的 .aggrega/active-release 标记,将一个 Release 记录为该工作区的默认值,并在标记写入后按 aggrega/activeRelease 的方式作答。接受工作区和 release:一个相对于工作区根目录、指定其中某个 Release 的路径,遵循与 aggrega/irGraph 的 release 相同的约束:绝对路径、向上越出工作区的路径和空值都会被拒绝;通过链接指向外部的路径也会被拒绝,除非工作区配置指定了该 Release。标记是一行以相对于根目录的路径指定 Release 的文本,即下文级联读取的形式。它只写入工作区内部,不会写到其他地方:如果 .aggrega 或标记本身是指向工作区之外的链接(无论其指向的位置是否已存在),请求会以 invalid-params 错误被拒绝,其消息是该条件本身的句子,前面带有其短代码 E0320: …(fatal-halts.md §“A path the operation writes leads through a link out of the directory it must stay inside(操作写入的路径通过链接越出了它必须保持在内的目录)”),并指出该链接及其指向位置,且不写入任何内容;保持在工作区内部的链接会被透过写入。答案给出的是级联最终确定的结果,而不是回显你发送的内容;当 build.authoring_release 指定了一个 Release 时两者会不同,因为配置的优先级高于标记。请通过这种方式记录默认值,而不要自己写入该文件,这样标记落在何处将按照产品在工作区中写入的每个文件都遵循的规则来判断,参见 工作区边界。
  • aggrega/effectiveConfiguration — 请求所指定工作区当前生效的配置,以及每项设置来自哪一层。只接受工作区,不接受其他参数:答案是该工作区的属性。layers 列出起作用的配置文件和环境覆盖,优先级最低的在前;settings 以点分名称、生效值以及决定该值的 source 给出每项可归属的设置。source 的写法与 layers 中对应条目完全相同,因此两者可以直接关联。关于 source 指的是哪一层,以及一行记录所表示含义的边界,参见 effective-configuration 响应涵盖哪些内容。
  • aggrega/configInit — 通过注册一个 registry 及其签名信任策略来生成一份可用的配置,使一台新机器无需手动编辑 YAML 即可拉取并验证已签名的制品。registry 可选,省略时生成官方 hub,与 aggrega config init 的默认值相同;答复中的 host 指明实际使用的是哪一个。global 和 workspace 是写入目标的覆盖项,同时发送两者会被拒绝。它拒绝覆盖已有的配置文件,并指明该文件——发送 force 可继续执行,此时会把 registry 条目合并到已有内容中,并保留其他设置。dryRun 执行普通请求的全部操作但不写入,以 content 返回生成的配置,供需要在保存前把文档呈现给作者的客户端使用;此时不会创建任何内容,written 为 false。已有文件的拒绝在 dryRun 下同样适用,因此需同时发送 force,才能得到覆盖写入会产生的合并结果。在离线工作区中只能生成官方 hub:该请求不接受身份或密钥,因此其他任何 registry 都会像 aggrega/registryAdd 那样被拒绝,包括短代码和语句在内完全一致,应改为通过该请求并手动提供策略来添加。答复包含 host、scope、trust 和 written,以及 existed:配置文件原已存在时为 true——此时 registry 条目合并到其中,而非新建文件——文件为新建时则省略。该请求默认写入全局配置——参见访问 registry 与写入。
  • aggrega/configCapture — 将生效的构建关键配置冻结到该工作区自己的配置文件中,使工作区在没有机器全局配置作为底层的情况下也能得到相同的构建结果。不接受写入目标:冻结的目的是让一个工作区自成一体,因此它始终写入该工作区的文件。allPlugins 将冻结的集合从决定渲染输出的插槽——provider 绑定和 label-transform 治理挂载——扩展到所有插件插槽,加入 verdict 治理、linter 关卡以及导入插槽。答复包含 configFile、workspaceRoot、captured、sockets 和 catalogDirs。参见配置写入留下了什么,因为答复指明的是一份现已存在的文档,客户端的下一步就是打开它。
  • aggrega/skillsInstall — 将内置于此二进制文件中的 Aggrega skill 写入请求指明的每个助手的 skill 文件夹,与 aggrega skills install 在终端中执行的安装相同。agents 按标识符列出助手,即 aggrega/skillsList 报告的标识符;重复给出的标识符只安装一次,若所指明的多个助手读取同一个共享文件夹,skill 只在那里写入一次。项目级安装必须提供该字段。未指明任何助手的 global 请求会为在本机上找到的助手安装,与不带 --agent 的 aggrega skills install --global 相同——即配置文件夹位于主目录中、或其命令位于守护进程环境的 PATH 中的每个助手——如果一个都找不到,则拒绝且不写入任何内容;不会提示任何输入,installed 会指明它为哪些助手写入了 skill。不带 global 时,skill 会落在每个助手位于请求指明的工作区内的项目文件夹中,绝不会落在守护进程启动时所在的目录中;带 global: true 时,它会落在守护进程环境所指明的主目录(HOME,Windows 上为 USERPROFILE)下每个助手的用户级文件夹中。在写入任何内容之前会检查每个目标,因此一次拒绝会让每个文件夹保持原样:没有已知 skill 文件夹的标识符会被拒绝,并指明该标识符及现有的标识符;目标位置上的文件若不带有每份写入的 skill 副本都带有的那行注释,会被拒绝并指明其路径。带有该行的副本——由之前的安装写入,或取自已发布的 skills 仓库——会被替换,较新的 aggrega 正是以此将 skill 更新到其自身版本。通过指向工作区之外的链接到达的项目文件夹会被拒绝且不写入任何内容,守护进程在工作区中进行的每次写入都是如此——参见工作区边界。响应携带 skill、installed——每个写入的文件夹一个条目,按助手被指明的顺序排列,每个条目包含读取它的 agents、绝对路径 folder 和 replaced——以及 scope。带 global 时,此操作会写入机器上每个项目都会读取的文件夹——参见访问注册表与写入。
  • aggrega/skillsList — 此二进制文件附带的 skills,以及 aggrega/skillsInstall 可以为其写入这些 skills 的每个助手,即 aggrega skills list 打印的列表。只接受工作区参数,不接受其他参数,且不从工作区读取任何内容。skills 携带每个 skill 的 name 和 description;agents 携带每个助手的 id、name、projectFolder(相对于项目根目录,在此接口上即请求指明的工作区)以及 userFolder(相对于主目录),二者均以斜杠分隔,按标识符排序。它不写入任何内容,也不访问任何地方。
  • aggrega/pluginAdd — 在已配置的 registry 中搜索指定类型的插件并将其加入配置。type 和 query 均为必填:type 是 provider、governance、linter、importer 和 cli 之一,query 与该类型的插件名称匹配,且必须恰好解析为一个,因此匹配多个的查询会连同候选项一起被拒绝,而不是被任意解析。capability 指明 provider 绑定所服务的能力,在该类型下必填;role 指明 governance 挂载的角色——label-transform、ir-verdict 或 render-verdict——在该类型下必填;两者都只在各自的类型下读取,在其他类型下会被拒绝,因为一个悄无声息地不起作用的字段会让人误以为它已生效。acceptCapabilities 对 cli 必填,用于确认该插件声明的能力:终端命令通过询问获得这一决定,而此接口无人可问,因此由调用方获得并发送。global 和 workspace 是写入目标的覆盖项,同时发送两者会被拒绝。dryRun 执行普通请求的全部操作但不写入,以 content 返回结果配置;不会创建或修改任何内容,written 为 false。registry 仍会被搜索,版本仍会被解析,因为该内容中的标识就是写入时会固定的标识。dryRun 在 cli 类型上会被拒绝,而不是被忽略:命令扩展的添加所记录的是它已验证字节的内容摘要,这是由编译器维护的记录,而不是任何人编辑的内容,且添加过程中会缓存这些字节——因此它会被写入,而不是返回。版本会为你固定——查询解析为一个插件,写入条目的是查询以 <name>:<version> 形式指明的版本,未指明时则是该插件已发布的最高版本;即使指明的版本已被本工作区信任的撤回声明撤回,它也照样会被固定,且应答带有 withdrawn: true。该请求会访问 registry,且未指明任何作用域的 cli 类型添加会写入全局配置——参见访问 registry 与写入。参见插件变更告诉你什么。
  • aggrega/pluginRemove — 删除一个已配置插件的条目,使其不再参与。type 的取值集合与添加时相同,query 标识条目:插件的短名称、其固定引用,或者——对 provider 而言——绑定所服务的能力。两者均为必填。global 和 workspace 是同样的写入目标覆盖项,同样不可同时发送。未匹配任何条目的查询会被拒绝,而不是在配置未变的情况下作为成功答复,因此调用方绝不会在插件仍在参与时被告知它已停止参与,拼写错误也绝不会删除另一个插件。它不访问任何 registry:删除只作用于配置文本。未指明任何作用域的 cli 类型删除会写入全局配置——参见访问 registry 与写入。参见插件变更告诉你什么。
  • aggrega/pluginSync — 使一个 Plugin 实体中由机器维护的记录与其模块保持一致:由模块自身导入推导出的宿主函数集合,以及从模块自我报告中读取的命令镜像。这两项记录都不由手工编写,因为两者的事实依据都在模块中。两个字段均为必填且都没有默认值——记录由模块推导而来,因此未指明任何内容的对齐没有可对齐的对象——两者都是相对于工作区根目录的路径,若为绝对路径或解析到根目录之外(无论按字面写法还是通过链接)都会被拒绝。只有这两个块会改变:其他每个字节都原样保留,包括注释、空行和引号风格;已经记录了模块所隐含内容的文件会保持字节级不变,并报告为未更改。该请求会写入你指明的实体文件,位于工作区内,且不访问任何 registry。参见插件变更告诉你什么。
  • aggrega/pluginGenCatalog — 为每个选定的 guest 生成一个 Plugin 实体,将从 guest 自我报告派生的契约字段与手工编写的逐插件覆盖层合并。fromEmbedded 和 plugin 是两种选择模式,恰好适用其中一种:此二进制携带的每个 guest,或你指定路径上的单个模块;两者都指定或都不指定会被拒绝,而不会被自行解析。overlay 为必填项,在 fromEmbedded 下它是覆盖层目录,在 plugin 下它是单个覆盖层文件——有多个 guest 时,覆盖层按身份与 guest 匹配;只有一个时则无需匹配。outputDir 在两种交付方式下都是必填项,dryRun 也不能免除它:试运行改变的是内容的去向,而不是内容所属的文件,因此每个返回的文档仍会指明它所对应的路径,而该路径由此目录组成。这里的三个路径并不按同样标准判定,区分依据是生成过程如何使用每个路径。plugin 和 overlay 是被读取的,且都是你选定的文件——模块位于其工具链构建输出的任意目录下,其覆盖层就编写在它旁边——因此两者都可以是绝对路径,并在其实际所在位置读取。outputDir 是被写入的,因此它相对于工作区根目录,若为绝对路径或解析到根目录之外(无论按字面写法还是经由链接),都会被拒绝——位于指向外部的链接目录之下、尚未创建的目录,会与该链接目录一样被拒绝。在输入未改变时重新运行会生成字节完全相同的实体。**此请求会将生成的实体写入工作区内的 outputDir 下,除非 dryRun 要求将其作为内容返回。**参见插件变更告诉你什么。
  • aggrega/getSchema — 实体或契约种类的 JSON Schema,读取自编译进当前运行二进制中的副本。kind 是小写连字符形式的 schema 标记——component、aggregate、release、recipe、ir、wasm-provider 等——它是可选的,因为它决定你问的是两个问题中的哪一个。指定一个种类,响应携带 kind 和 schema,schema 以 JSON 文档形式给出,而不是包含该文档的字符串。不指定种类,响应则携带 kinds 和 entityKinds:即你可以指定哪些种类,分两种范围。kinds 是此二进制可被请求的每个标记,顺序与 aggrega get-schema --list 打印的顺序相同。entityKinds 是作者可编写文档的较窄集合,每个条目携带要回传的 kind 标记、填入文档自身 kind: 字段的 documentKind 值,以及 acceptedBy,后者说明单实体校验、发布和按名称检查是否接受该种类的文档。在基于其中任一集合构建选择器之前,请参见可以向作者提供哪些种类。schema 答复与枚举从不合并,因此从响应即可看出回答的是哪个问题。没有对应 schema 的标记会被拒绝,并在消息中给出完整的有效集合,这样无需第二次调用即可纠正拼写错误。它不从工作区获取任何内容,不联系任何注册表,也不写入任何内容,因此在空无一物的工作区中也能作答——正因如此,它可用于针对编辑器实际驱动的二进制来配置编辑器的 schema 关联,而不是针对安装在别处的某份 schema 副本。
  • aggrega/scaffoldEntity — 某个实体种类的起始文档:恰好包含该种类 schema 要求的字段,填入固定的 apiVersion 和 kind,并在每个需要值的地方放置占位符。kind 为必填项,是小写连字符形式的 schema 标记——component、aggregate、release、recipe、manifest、feature 等;不带 kind 的 aggrega/getSchema 会报告你可以发送哪些标记,没有对应 schema 的标记会被拒绝,并在消息中给出该集合,这样无需第二次调用即可纠正拼写错误。向作者提供种类选择的客户端读取该方法的 entityKinds,即可编写文档的种类集合。name 是可选的,对于 schema 要求名称的种类,它用于填充 metadata.name。响应携带 kind 和 skeleton。参见scaffold 响应给你什么,因为该答复是一个待写入的文档,而不是已写入的文档。骨架派生自 aggrega/getSchema 报告的同一 schema,因此两者出自同一来源。若发送 example 而不是 kind,它会将文档中的一个可运行示例写入工作区中的一个新目录,与 aggrega scaffold --example 在终端中的做法相同;若仅发送 list: true,它会以现有的所有示例作答,且不写入任何内容。这两种形式都需要工作区,因此对其中任一形式的请求都要在 workspaceRoot 中指明工作区,未指明的请求会被拒绝。dir 指定新目录相对于工作区根目录的路径,默认为示例的名称;绝对路径值,或解析到根目录之外的值——无论是按写法如此还是经由链接——都会在读取任何内容之前被拒绝,而已有任何内容的目录会被拒绝并保持原样。列表的回答携带 examples,每项包含 name、level 和 summary;写入的回答携带 example、dir、files——写入的每个文件,相对于 dir——next,即示例页面给出的构建命令,页面未给出时不存在,以及 version,即读取该示例所用的文档版本。同时发送属于两种形式的字段——kind 与 example、list 与 example 或 kind、name 与 example 或 list,或不带 example 的 dir——会在读取任何内容之前被拒绝,措辞与助手工具拒绝它们时相同。写入时,如果本机没有通过工作区自身签名检查的副本,则会获取文档包,并在工作区内写入——参见访问注册表与写入。
  • aggrega/import — 将外部源描述转换为 Aggrega 编写文件草稿,与 aggrega import 在终端执行的转换相同。source 为必填项,指明要转换的文件或目录,可以是绝对路径,也可以相对于工作区根目录——由其他工具导出的描述位于你保存它的任何位置,因此它在实际所在位置读取,而不仅限于工作区内。目录的读取方式与 aggrega import 相同:读取其中由导入器声明的文件模式所选中的文件,工作区的构建输出文件夹 dist/ 除外,并且无论目录位于何处都限定在其自身范围内,因此不会沿其中的任何链接跳出该目录。outputDir 是可选的,指明草稿存放的目录,它不遵循上述约定:它是被写入的,因此是工作区内的路径,绝对值或解析到根目录之外的值(无论按字面写法还是经由链接,包括位于这样的链接之下、尚未创建的目录)都会被拒绝。省略它,草稿就放在工作区根目录下,即 aggrega import 未指定目标时写入的位置——在 dryRun 下也是如此。format 显式指明源格式;省略它,则按导入器声明的特征识别格式——工作区目录中的导入器与编译器的核心导入器一视同仁——没有导入器能识别的源,或被多种格式的导入器识别的源,会被拒绝并要求提供 format,而不是靠猜测。target 指明一个 provider 能力,例如 compose 或 helm——即 Recipe 的 spec.capability 所绑定的词——并在导入器的草稿之外,为该 provider 起草所起草的 Release 据以构建的 Manifest,与 aggrega import --target 的行为完全相同:manifest.yaml,将草稿所需的每个组件类型和功能类型(包括所起草的 Aggregate 所组合的目录 Aggregate 的类型)映射到工作区目录为其提供的该能力的 Recipe 或功能配方,使用其能力限定名称且不带版本:只有一个时取该项,有多个时取以该类型命名的那一项。Release 的 spec.manifest 设为它;没有任何对应项,或有多个但都不以该类型命名的类型保持未映射,并产生一条指明它的 warn 发现;导入器自行起草的映射,若目录为该类型和能力提供了它则保留,否则丢弃并产生一条 warn 发现。目录中没有任何 Recipe 绑定的 target 会在导入器运行前被拒绝,消息指明该 target 及目录中 Recipes 所绑定的能力,且不写入任何内容;省略它则不起草 Manifest——sync 下除外,此时会为先前导入记录中指明的 target 起草。机器上尚未持有的核心导入器,会由第一次需要它的导入获取——参见import 响应告诉你什么。dryRun 执行普通请求的全部操作但不写入,以内容形式返回草稿,供先将其展示给作者的客户端使用;在此模式下不创建任何内容,written 为空。sync 会使先前导入在 outputDir 中起草的内容与源保持同步,只改动导入所写的内容,与 aggrega import --sync 相同;不带它时,草稿将覆盖已存在的 Aggregate 的请求会被拒绝。答复携带 format、outputDir、written、files、drift、diagnostics、decisions 和 halted。参见import 响应告诉你什么,因为导入器未能完全转换的源是一个成功的答复,而不是错误。
  • aggrega/explainError — 编译器对某个代码所指条件的声明,以及讲解如何修正编写内容的已发布条目。code 为必填项,接受条件的任一标识符:诊断在 shortCode 中携带的短代码,或在 code 中携带的描述性代码。它是对该协议上的诊断已携带代码的展开,与 aggrega explain 在终端打印的回答相同。回答始终携带条件——shortCode、code 和 message——因为这些内容在二进制文件内部声明,无需网络;entries 携带已发布的详细讲解,缺失时由 note 说明原因。当本机没有工作区自身签名检查所认可的副本时,此请求会获取文档包——参见访问注册表与写入。参见展开诊断所携带的代码。
  • aggrega/invalidate — 来自编辑器文件监视器的缓存失效信号。

通知:

  • $/cancelRequest — 客户端发往服务器:停止以该 id 发送的进行中请求。守护进程会取消该请求的工作;操作在下一个步骤边界而非立即察觉取消,因此已在进行的工作会再持续片刻。取消一个没有任何任务在运行的 id 是安全的空操作。
  • $/progress — 服务器发往客户端:长时间操作在执行过程中正在做什么,通过请求所要求报告的令牌发送。仅针对携带了令牌的请求发送。参见观察长时间操作。
  • aggrega/shutdown — 开始协作式排空:进行中的请求完成,新请求被拒绝,然后守护进程退出。
  • aggrega/publishDiagnostics — 服务器推送的诊断集(用于 lockfile 漂移警告和启动时状态)。每个条目携带一个 source,指明由守护进程的哪个诊断层产生:aggrega 表示关于所编写文档的发现,aggrega-build 表示构建产生的建议——即其产生的全部建议,与 aggrega build 打印的集合相同——aggrega-lint 表示发布约定方面的发现,与 aggrega lint 打印的发现相同。该字段在每个条目上始终存在,因此客户端可以对条目分组,而不必显示一个不加区分的列表,也无需区分缺失的来源与某个层。仅当某文件的集合与上次告知该客户端的集合不同时才为其发送帧,因此重新计算出相同发现的请求不会发送任何内容;文件的第一帧以及清空文件集合的帧都属于差异,始终会发送。

**要求进程本身停止,对守护进程的效果相同。**来自终端的中断,或来自监管程序或容器运行时的终止请求,会开始与 aggrega/shutdown 相同的排空:进行中的请求完成,新请求被拒绝,然后守护进程退出。第二次请求会立即结束进程。启动守护进程的客户端可以用任一方式停止它,通过协议停止和通过信号停止会得到相同的排空。

实时验证

每次收到 aggrega/validate 时,守护进程都会根据文档的 schema 验证编辑器缓冲区,并返回指向出错键的诊断——与构建给出的判定相同,只是针对未保存的内容。未发送 content 的请求询问的是磁盘上的文件;发送为空的 content 表示一个空缓冲区,而不是对文件的请求。未附带内容发送的文件必须是工作区包含且可读取的文件——工作区之外的文件、通过指向工作区外的链接到达的文件,或不存在的文件,都会以 invalid-params 代码被拒绝。目录实体、Aggregates、Manifests 和 Releases 通过其 apiVersion 和 kind 识别。不带此类头部的两种文档——.aggrega-config.yaml 工作区配置,以及请求所指定 Release 的锁文件——改为通过文件名识别,因此其中任一文档中的无效或格式错误的键也会实时显示波浪线。不是 Aggrega 文档的文件——Helm chart 模板、Compose 文件、Kubernetes 清单,以及其他生态系统的 .lock 文件(如 Cargo.lock 或 flake.lock)——不会收到任何诊断;守护进程从不报告外部文件。

仍待填写的占位符会在其键上被指出,并说明它接受什么。 对于 aggrega validate 作为单个实体检查的那类目录实体,还会按该命令所采用的读取方式,读取其以空字符串留下的必需值,因此对于相同的字节,守护进程会指出该命令指出的每个占位符。每个占位符是一个条目:其 message 说明该键是仍待填写的占位符,其 suggest 说明该值接受什么,其 keyPath 携带该键的点分路径。该条目取代 schema 对该空值本身的发现,文档上的其他所有发现均按 schema 检查的报告方式报告。schema 允许为空的占位符也会被指出,尽管 schema 检查对其不作任何报告——你会遇到的是草拟中的 Recipe 或 FeatureRecipe 的 capability 和 implements。当 schema 检查同时拒绝该文档时,每个条目都携带该检查的代码 E0215;当它接受该文档时,条目不携带代码:与该命令对这些字节的报告所携带的标识符相同。条目绘制在持有空值的键上,位于该命令指出它的那一行——即使是自身名称包含点的键,例如 component.aggrega.ai/type 标签(schema 检查对该键报告的发现会绘制在包含它的键上)——且 keyPath 完整地指出该键。无论请求是否指定 Release,这一点都成立,因为这是文档自身就能回答的问题,而且仍待填写值的文档尚不属于需要询问发布约定的文档:对它而言,该层被清空,就像对 schema 拒绝其结构的文档一样。

**每个请求都指明它所针对的 Release,守护进程自身不保留任何 Release。**语义检查会解析该 Release 的依赖闭包,并读取该 Release 的 lockfile 以获取其固定版本——或者,对于目录实体,读取该 Release 构建时使用的目录,如下一段所述——因此,两个分别指明两个 Releases 的请求,会各自针对所指明的 Release 得到回答。两者之间不会保留任何状态:不存在需要更改的已选 Release,更改你用于验证的 Release 只是下一个请求中的一个不同值,而无需告诉守护进程忘记任何东西。

与 Release 一同指定的目录实体,会按该 Release 的条件作为单个实体检查。 持有 Component、Feature、Recipe、FeatureRecipe 或 Plugin 的 file,若与 release 一同发送,会在编辑器的未保存缓冲区上得到 aggrega validate <path> --release <release> 所运行的检查:其引用——Recipe 实现的 Component、某个支柱引用的库——会通过工作区配置为该 Release 给出的目录进行解析,因此同一文件可能按使用它构建的 Release 的条件是干净的,而按另一个其目录不包含其所引用内容的 Release 的条件则失败。这与命令行和 aggrega mcp 的 validate 工具针对同一实体、同一 Release 给出的判定相同,并且与它们一样,不遍历闭包,也不读取锁文件。阻塞性发现是一个错误条目,使用检查自身的措辞并携带其代码,绘制在它在实体中指出的键上,若未指出键,则绘制在实体的 kind: 键上,如 What a diagnostic entry carries(诊断条目携带的内容) 所述——除非构建已在该文件上报告了该错误,此时构建的条目即为唯一的报告;检查在读取目录时提出的建议是位于其前面的警告条目;在目录全部存在的情况下检查干净,则不产生任何条目。失败的断言——即在 Recipe 或其实现的 Component 中调用 fail 的断言——在这里不是阻塞性发现,而是一个警告条目,使用检查的措辞并携带其代码,以句子 A Release must satisfy this assertion before a build of it can pass. 结尾,并绘制在阻塞性发现本应所在的位置:Recipe 的断言绘制在 assertions 下该断言自身的键上,Component 的断言绘制在 Recipe 的 kind: 键上。与阻塞性发现一样,若构建的条目在该文件上报告了相同错误,则让位于构建的条目。该检查围绕占位符和 schema 默认值构建实体,而不是使用 Release 设置的值,因此无法区分等待 Release 的断言和已损坏的断言,而将判定留给构建,构建会将同一断言报告为错误(失败的断言是警告)。工作区配置为该 Release 列出的目录若并非目录——例如那里什么都不存在——检查便不会越过它:该文件携带一个错误条目,取代检查的判定,即每个命令对该目录给出的拒绝,指出该条目、列出它的配置文件和行,以及该设置(本地实体从何处读取)。未指向任何文件或指向目录的 release,会在该文件上以命令行拒绝它时使用的句子作答,而不是按工作区的条件进行检查。单个实体的构建所无法替代的内容,按命令行的判定方式判定,而命令行搁置或不检查的内容在这里不产生任何条目——参见单实体正确性不检查的内容,以及对于模板读取仅由拓扑边或附加凭据提供的值的 Recipe,参见单实体正确性。Release 自身的 Aggregate、Manifest、Release 和库不会逐个检查,因为单实体检查不接受这些种类;它们保留上述闭包检查。持有 Workload 内容的缓冲区被视为非 Aggrega 文档的 YAML,因为该内容写在 Recipe 或 FeatureRecipe 的 workload: 字段中,并在其所在之处进行检查;命令行和 validate 工具在通过路径获得 Workload 文件时,会单独检查其结构。

**指定 Release 是可选的,应答会说明你请求的是两种中的哪一种。**指定一个 Release,你会得到上述全部检查。不指定,你得到的是文档自身就能回答的检查——能否解析、自身结构是否可接受,以及对于按单个实体验证的那类目录实体,它仍欠哪些占位符——不解析 Release,不遍历闭包,也不读取 lockfile;此时回复带有 checked: "document"。指定了 Release 时该键不存在,因为该应答就是此方法的完整结论,无需加以限定。

请读取该键,而不要从诊断结果推断,因为两种应答可能看起来完全相同。一个格式良好的文档在不指定 Release 的情况下验证,会回复空的诊断列表,这与无问题的完整结论的回复完全一样,因此只有 checked 能区分“没有问题”与“没有检查需要 Release 的内容”。同一规则还带来一个结果:lockfile 是根据它与请求所指定 Release 的关联来识别的,因此未指定 Release 的请求不识别任何 lockfile,也不对其报告任何内容。

**不包含 Release 的工作区会得到应答而不是被拒绝,正是这一点让守护进程的其余功能在那里仍然可用。**验证负责填充其他所有文件操作读取的解析缓存,因此仅含目录的仓库、单 Aggregate 脚手架或临时目录仍能获得悬停提示、补全、跳转到定义、引用、实现以及缓存的诊断。若改为拒绝,这些功能会一并失去,而且恰恰发生在客户端没有 Release 可指定的那些工作区中。

诊断条目包含什么

每个条目用 line 和 column 定位,两者都从 1 开始,采用握手时协商的位置编码;当条目跨越整个记号时,还会添加 end_line 和 end_column。message 是客户端向用户显示的文本,severity 对其分类,source 指明是守护进程的哪一层产生了它,如上文所述。

各层回答的是关于同一文件的不同问题,因此来自各层的条目可以位于同一行,而彼此并不重复:一个说部署不正确,另一个说实体不可发布。将它们显示为一个列表的客户端会把同一个问题报告两次,读取 source 才能将它们区分开。

**条目的位置取决于它所涉及的内容,而不是产生它的层。**关于作者所写内容的发现定位在作者写下它的键上,因此编辑器会把它绘制在应当修改的地方。关于已部署拓扑结构的发现指明的是一个组件和一个交付键,而不是一行——这些是已部署拓扑中的坐标,而非文档中的坐标——因此它绘制在文档的 kind: 键上,并在消息中给出其坐标。两类发现都会到达 aggrega-build 层,因为构建会产生这两类发现。构建在渲染时产生的拒绝也会到达该层,位于拒绝本身所指向的文档上——不满足其检查的 Workload 位于其 Recipe 的 workload 键上,Recipe 中失败的断言位于该断言自身的键上,被图组合拒绝的条目位于 Release 或 Aggregate 写下它的键上,汇集多个发现的拒绝中的每个发现位于其各自的文档和键上——而在不指向任何文档时,位于 Aggregate 的 kind: 键上;渲染时产生的拒绝对此有描述。因此,客户端应按每个条目自身的 line 和 column 放置它,绝不要根据层来推断位置。

**未指明文档中所含键的发现,绘制在指明该文档的键上。**文档自身检查就其内容产生的发现、单实体检查的发现,以及构建产生的提示或拒绝,各自绘制在其指明的键上;当它们未指明键,或指明的键不在文档中时,则绘制在文档的 kind: 键上,文档未声明 kind: 时绘制在其 metadata.name 上,仅当文档两者都未声明或无法解析时才绘制在文件开头。文档通常以注释开头——每个目录文件都带有许可证头——绘制在第一行的条目会落在该注释上,读起来像是注释有误,而文档自身的标识是作者亲手写的一行。涉及文档内容以外事物的条目放在文件开头:关于 Release 依赖的 Dependencies: 条目、未指明文档中任何内容就停止的阶段、已漂移的 lockfile、渲染不得不拒绝的引用、未能加载的 Release——规则未计算出行号的 aggrega-lint 条目也是如此。在位置是陈述而非绘制的地方,未指明键的发现仍然没有键:未指明键的拒绝,其错误应答只在 data 中携带文档。

**条目发布在哪个文档上,也遵循同一规则。**指定 Release 的验证会应答该 Release 的 Aggregate、Release 本身、该 Aggregate 导入的每个模块的文档,以及该 Release 指定的 Manifest。定位在 Release 中的发现——对 Release 在某个组件的连接上写入的条目、对它给该连接的规模设定、对它在那里填充或设定规模的挂载、对它连接的连线、对仅由 Release 挂载到组件或边界上的 Feature,或对它给某个挂载的 infra 的拒绝——在验证 Release 文档时发布,位于 Release 中写下它的键上,而完全不发布在 Aggregate 上。定位在某个模块自身文档中的发现——对该模块某个组件所声明内容、对其挂载所连接的 socket、对其值或其自身连接上的值的拒绝——在验证该模块的文档时发布,位于那里写下它的键上,而完全不发布在 Aggregate 上。关于 Manifest 映射表的发现——将某个类型映射到并未实现该类型的 Recipe 或 FeatureRecipe 的条目、版本固定无法解析的条目,或其 extends 链无法追溯的被映射类型——在验证该 Manifest 时发布,位于其所涉及的映射条目的键上,而完全不发布在 Aggregate 上;如果 Manifest 打开的文本中没有写出该条目——例如通过其自身的 extends 继承的条目,或被未保存的编辑删除的条目——该发现会发布在 Manifest 的第一行。该 Release 的验证产生的其他所有发现都发布在 Aggregate 上,其中包括不指向你工作区中任何文档的依赖层面的发现:被撤回的引用或插件、extends 链无法解析或 schema 无效的目录 Component 或 Feature、与信任记录不匹配的门禁插件、没有任何映射能解析的组件实例、其提供程序无法渲染其所声明输入类型的 Recipe 或 FeatureRecipe,以及 schema 支柱重叠和 extend 时收窄的建议。因此,无论是构建的哪个阶段产生的,关于运维人员所写内容的发现会在 Release 打开时出现,关于模块所声明内容的发现会在该模块打开时出现,关于映射的发现会在 Manifest 打开时出现;针对该 Release 验证每个打开文档的编辑器会在相应位置显示每个发现。依赖完全无法解析的 Release 不会产生上述任何发现,解析失败是一个条目,位于 Release 自身文档的开头,以及针对它验证的、守护进程能识别(如 Live validation 所述)且不作为单个实体检查的其他每个文档的开头——其 Aggregate、其 Manifest、库、另一个 Release、工作区配置——前缀为 Dependencies:,并携带解析过程自身对停止原因的说明。在 Release 自身的文档上,该条目就是这份说明,别无其他。在其他每个文档上,它首先说明该文档是针对该 Release 检查的,并按请求指定的方式给出 Release 的名称——Dependencies: this document is checked against the Release <release>, whose dependencies cannot be resolved:,后接该说明——因为该文档中没有任何内容表明它是针对哪个 Release 检查的:针对所选的单个 Release 检查每个打开文档的编辑器,会把该条目放在与该 Release 毫无关系的文档上,而名称正是告诉你原因在于该选择。守护进程不识别的文件不带此类条目,无论与它一起指定的是哪个 Release。

无论验证进行到哪一步,应答都携带该文件上现存的每一层。aggrega/validate 应答是文件完整的当前状态:本次验证的发现、构建、预览或图请求在该文件上发布的 aggrega-build 条目,以及其发布约定的发现,各自位于其 source 之下。在缓冲区阶段就停止的验证——无法解析的内容,或结构外壳被 schema 拒绝的文档——也以同样方式应答:它报告自己的发现,并保留文件上的每个构建条目,因为它对构建一无所知。因此,客户端可以根据任何应答,逐层替换它为该文件保存的内容。

**同一个错误只报告一次。**文档自身的验证和构建可能在其中发现同一个错误:单实体检查会渲染构建同样会渲染的 Recipe,验证会组合构建同样会组合的图,而依赖无法解析的 Release 会让两者都失败。当构建在某个文档上报告了这样的错误时,该文档的验证不会再报告一次:一个 aggrega 条目,若与同一文档上构建的拒绝指明同一条件(同一个 code),且位于相同的范围或不在其自身的任何键上(绘制在未指明键的条目所绘制的位置,或文件开头),则会从该文档的每个应答和每次发布中省略,只保留构建的报告。构建的报告是该拒绝在 aggrega-build 层上的条目;或者,对于因依赖无法解析而以 1004 被拒绝的 aggrega/build、aggrega/buildPreview 或 aggrega/irGraph,就是该应答本身(它不会被任何发布),落在其 data.file 所指的文档上,否则是其 data.lockfile,否则是请求所指明的 Release;对于一个 Release,以最近的此类应答为准。验证会保留它的发现:一旦不再有构建报告该错误(下一次运行发布的该层中不含它,该 Release 的下一次构建、预览或图应答是其他结果,或者连接了一个未曾收到此类 1004 应答的客户端),文档自身的条目会重新被报告;在尚未运行过任何构建的情况下,不会省略任何内容。位于没有任何构建拒绝所在键上的 aggrega 条目会保留,即使它指明同一条件,因为它可能是构建尚未报告的同类第二个错误。

code 是条目所报告内容的稳定、可供机器匹配的代码,因此客户端可以据此分支,而无需匹配消息文本。无论由谁分配,代码都放在同一个键中,而 source 告诉你手中是哪一种,因为各层使用不同的词汇来命名事物。

  • 在 aggrega 条目(关于所编写文档的发现)上,代码是该条件注册时使用的字符串,写作声明它的包加上 kebab-case 形式的规则。它与 Go 使用方通过 CodeOf 读取的值相同,其形式和可匹配的部分见错误哨兵参考。
  • 在 aggrega-build 条目(构建提出的建议)上,代码是提出位置所分配的任何值;由于构建会就两种不同的事物提出建议,该层承载来自两套不同词汇的建议。关于已部署拓扑形态的建议带有一个类别代码,例如 unsupported-field,由提出它的位置分配,无论是渲染插件还是渲染本身;类别代码指明的是一类建议而非已注册的条件,因此在哨兵参考中没有对应行,警告参考描述了 unsupported-field 类别以及使其静默的标志。关于所编写文档的建议(与某个已声明名称只差一处编辑的名称、无人读取的参数)带有其条件注册时使用的字符串,形式与 aggrega 条目相同,并在哨兵参考中有对应行。无论哪种情况,代码指明的是发现是什么,而不是由谁发现,因此无论多少位置提出某一类别,你都以同一个代码收到它;读取代码而非层,才能告诉你手中是两者中的哪一种。构建在渲染时因之停止的拒绝是这里唯一不属于建议的条目,它同样带有其条件注册时使用的字符串。
  • 在 aggrega-lint 条目(发布约定的发现)上,代码是该发现的标识:产生它的规则的标识,或者,对于未指明规则的发现(你自己的 linter 可能以其自有代码报告此类发现),就是那个代码。它是 aggrega lint 在该发现所在行上打印的标识符(若有短代码,则位于短代码之后),也是 aggrega lint --output json 为同一发现携带的值,作为 ruleId,对于未指明规则的发现则作为 code。同一发现在各个界面上保持同一标识,因此在编辑器中对某条规则进行分组或抑制的客户端,在终端中也会对同一规则分组和抑制。Aggrega 声明的发布 linter 规则集中的每条规则都以该标识注册为一个条件,因此它列在所有条件的表格中,使用 aggrega lint 在同一发现所在行开头打印、并由 aggrega lint --output json 作为 shortCode 携带的短代码。Aggrega 未声明的、来自你自己 linter 的规则不指明任何已注册条件,未指明规则的发现也是如此,即使其自有代码拼写的是 Aggrega 所声明规则的标识,因此两者都不会列在那里。这些规则的说明见 aggrega lint 参考。

无论哪一层,该键都回答同一个问题:这是什么,以机器可以匹配的方式表达。因此,对某一类发现进行高亮、分组或抑制的编辑器扩展应以代码为依据,这样在消息措辞变化时依然有效。

注意哪个对象携带哪一种:这是诊断条目上的字符串,不同于下文错误代码中所述 JSON-RPC 错误信封上的数字 code。一个响应只携带其中一种,二者绝不会出现在同一位置。

当产生条目的任何环节都未分配代码时,该键会被省略,每一种条目都有这种情况。任何 YAML 解析器都无法读取的缓冲区只报告解析器自身的文本而没有代码,因为其背后没有 Aggrega 自有的条件;在不指明条件的情况下报告失败的阶段同样没有代码可报告;提出者未分配代码的建议到达时也不带代码。因此,请将 code 视为可选,与 end_line 和 end_column 一样,仅在其存在时据此分支。代码是诊断所报告的内容,而绝不是用来选择诊断的依据:没有任何请求接受代码,把代码写回你自己的代码中,得到的只是一个字符串,而不是一种匹配方式。

程序匹配的标识符,与人引用的标识符

一个条件带有两个标识符,分别面向两类不同的读者。 code 即上文所述的那个:带限定前缀并以连字符连接,因此依据它分支的程序读起来就能看出其含义。shortCode 是字母 E 加四位数字(如 E0164),它是供人念出、输入搜索框或粘贴到 issue 中的标识符。两者指向同一个条件,任何一个都不是另一个的缩写。

该用哪一个,取决于谁在读。 在你的扩展中依据 code 匹配;把 shortCode 展示给作者。只显示 code 的扩展会让读者拿着一个面向程序的标识符,而依据 shortCode 匹配的扩展则是在匹配一个对条件本身毫无说明的编号。正因为这种分工,两者会同时传递,而不是只传一个。

codeDescription 是该条件的发布位置,以 { "href": … } 的形式携带,这是协议自身用于表示“可打开以了解诊断详情”的引用的结构。支持该协议的编辑器无需了解任何关于 Aggrega 的知识,就能将其变成一个“了解更多”的入口,任何客户端也都无需保存这些说明的副本。该地址解析到已发布的全部条件列表,其中某个 shortCode 的条目会说明该条件,并继而给出编写层面修复方法的详细讲解。

说明文字本身不在条目上,这是有意为之。 每次编辑都会发出诊断,若每条诊断都附带说明,每敲一次键就会把同样的段落重新发布给一个通常早已读过它们的读者。需要文字的客户端可以通过下文的 aggrega/explainError 请求一次;能够跟随链接的客户端则两者都不需要。

当且仅当条目指向一个已注册的条件时,这两个键才会出现,否则两者一同缺失。 决定它们的是条目背后是什么,而不是哪个层发布了它,因此请读取这些键,而不是层:

  • 指向已注册条件的条目三者齐备。 shortCode 可以解析,引用也解析到它所在的列表。
  • 代码指向一个类别的条目只带有 code。 渲染建议的类别,以及来自你自己的 linter 的约定检查结果的标识(Aggrega 未声明的规则,或未指明规则的检查结果所带的代码),都是可用于分组和抑制的真实标识符,但都不是已注册的条件,因此没有可供引用的编号,该地址处也没有描述它们的内容。若仍发送引用,就会是一个打开与读者问题无关的页面的链接,所以不发送。这是 aggrega-build 层上的常见形态,不过确实指向已注册条件的构建建议也像其他条目一样三者齐备。在 aggrega-lint 层上,常见形态是完整的一组:Aggrega 声明的发布 linter 规则集中的每条规则都是已注册的条件,因此其检查结果带有与 aggrega lint 在该结果行首打印的相同的 shortCode,以及旁边的引用。
  • 不指向任何内容的条目不带任何标识符。

因此仅凭这些键就能区分这三种情况:没有 code 表示没有可指称的内容;有 code 而旁边没有 shortCode 表示该标识符无法进一步解析;完整的一组则表示该标识符有可供阅读的说明之处。请像对待 code 一样,将这两个新键视为可选,并且只在收到 codeDescription 时才为读者提供可打开的内容。

展开诊断所带的代码

aggrega/explainError 将条件的任一标识符展开为编译器对该条件的声明,以及讲解编写层面修复方法的已发布条目。它与 aggrega explain 在终端中执行的、以及 explain-error 工具为助手执行的展开相同,三者都从同一处给出答案,因此在这里展开的代码与在别处展开的同一代码是同一个答案,而不是恰好一致的三个答案。

code 为必填项,可接受任一标识符(诊断所带的 shortCode,或其旁边的 code),因为持有其中一个的客户端不经询问就无法获得另一个。空值会被拒绝,并说明应发送什么。

答案总是带有 shortCode、code 和 message:即条件的两个标识符,以及每条指向该条件的诊断开头的那句话。这些都在二进制文件内部声明,因此无需网络和缓存即可获得,这也使得不含任何文档的工作区依然能得到答案。reference 与诊断的 codeDescription 所带的地址相同,供宁愿把读者引向文档而不是渲染文字的客户端使用。

entries 携带已发布的详细讲解,每个条目由开头的 heading 和其下的 body 组成,顺序与文档本身将它们与该条件配对的顺序一致。无法加入讲解时它会被省略,此时 note 说明原因:已发布页面尚未为该条件记录条目,或此工作区无法读取文档(机器上没有副本,或只有一个被工作区签名检查拒绝的副本)。无论哪种情况,上面的条件依然成立:该答案并非失败,客户端应显示收到的内容及旁边的说明。entries 和 note 永远不会同时出现。

无法解析的代码会被拒绝,而不是以一个所有字段都为空的条件作答,并且每次拒绝都会说明属于哪种情况:没有任何条件以该代码注册;某个编号曾指向一个条件且永远不会再指向其他条件;或者在已发布列表完全无法读取时,该二进制文件未声明此代码。最后一种情况两种修复方式都可行,因为为其他版本发布的列表可能指向此二进制文件未声明的条件。

文档从为请求所指定工作区缓存的包中读取,缺失时会在首次使用时获取,这也是此请求唯一需要访问注册表的情形,参见访问注册表与写入。不会向工作区写入任何内容。任何验证都不会触发它:展开之所以发生,是因为有请求要求展开,因此在验证或检查文档期间永远不会访问注册表。

发布约定:按请求检查与每次编辑时检查

守护进程回答关于目录实体的两个不同问题,它们正是 aggrega validate 和 aggrega lint 在终端中回答的问题:部署是否正确,以及该实体按目录的约定是否可发布。一次验证总是回答第一个问题。只有在你要求时,它才回答第二个。

**aggrega/lint 直接要求回答第二个问题。**发送 entity 检查单个目录实体,发送 release 检查该 Release 的依赖闭包所触及的每个实体,两者都不发送则检查所配置的目录路径下的每个实体——这就是该命令的三种范围。同时发送 entity 和 release 指定了两个不同的对象,会被拒绝。应答携带 checked,即本次运行覆盖的实体文档数量;以及 files,即按所涉文档分组并按路径排序的检查结果,每个文件的条目都采用上文所述的诊断结构。halted 表示本次运行自身的结论是否拒绝发布。

**两者都不发送时,会像不带参数的 aggrega lint 一样检查整个目录。**如果工作区的配置没有为 Release 给出自己的目录路径,则在其自身的目录上检查一次,应答即上文所述。如果工作区在 workspace.releases 下列出了 Releases,则对其中每个 Release 各检查一次,范围是该 Release 读取的目录,绝不会把所有目录合在一起检查——因此并排保存、每个 Release 一份的目录变体,各自按读取它的 Release 的条件进行检查。此时应答还携带 passes,每轮检查一个条目:releases,即该轮所针对的 Releases,各自相对于工作区根目录,读取相同目录的 Releases 共享一个条目;catalogDirs,即该轮读取的目录,拼写方式与 files 拼写路径的方式相同,对于不读取任何目录的 Release 则为空,这种情况会被报告,而不会导致其他轮失败;以及该轮自身的计数和 files,由它们说明某条检查结果是针对哪个 Release 发现的。外层的 checked、计数和 files 涵盖所有轮次,因此不读取 passes 的客户端仍能读到整次运行。如果没有任何一轮有目录可读,该运行会被拒绝,而不会被当作干净的目录来应答。

在 entity 旁设置 prePublish,可将该实体与其先前发布的版本进行比较,并据此对拟议的版本升级进行分类。这是此处唯一会访问注册表的模式,它之所以运行,是因为请求指定了它:允许一个向外访问的操作的,是调用方的明确要求。它只在带有 entity 时才有意义,因此不带实体的 prePublish 会被拒绝。

aggrega/lint 不向会话发布任何内容。它只回答关于所给对象的问题,而把其检查结果写入编辑器的问题列表,会替换验证为该请求从未覆盖的文件所发布的内容。在任何模式下都不会向磁盘写入任何内容。

**serve.lint_on_validate 在每次验证时运行相同的规则,除非你开启,否则它处于关闭状态。**在 .aggrega-config.yaml 中开启它,位置是你希望获得其实体建议的那个工作区:

serve:
lint_on_validate: true

它没有对应的标志,因为它回答的问题关乎工作区自身的内容,而有这个问题的人是编写该工作区的人,而不是启动守护进程的人。开启后,对目录实体的验证还会在 aggrega-lint 来源下发布约定检查结果;关闭时(默认),验证只报告正确性层,不会有任何约定检查结果到达你这里。在你请求该层之前,编辑器会话不会说明实体是否可发布。

无论该键取何值,该层都满足三点。只运行读取本地内容的模式,因此不会查询注册表,不获取任何内容,也不写入任何内容;发布前比较需通过发送带 prePublish 的 aggrega/lint 来触发,绝不会由验证触发,因为每次编辑都运行的检查恰恰是不得访问注册表的地方。规则针对请求携带的缓冲区求值,而不是磁盘上的文件,因此你修正的名称在保存之前就不再被报告。并且检查结果是建议性的——产生这些结果的文档仍然通过验证,其 Release 仍能解析和渲染——因此它增加的是一个层,而绝不是一次拒绝。

该键只控制这一层,别无其他。无论取哪个值,aggrega/lint 都会回答所问的内容,因为发送它的调用方已经按名称请求了这项检查。

只检查会被发布到目录的类型,因为约定针对的正是这些内容。不属于目录内容的文档——其中包括 Aggregate 和 Release——会被跳过,根本不是 Aggrega 文档的 YAML 也会被跳过。正因如此,会话对作者花费大部分时间编辑的那些文档保持安静。

报告的路径如何书写

当一个应答指明守护进程为你定位到的文档时,该路径的写法由一条规则决定:文档在工作区根目录内时,写成相对于工作区根目录的路径;不在时,写成绝对路径。 这涵盖实体标识上的 file、实体定义上的 file,以及 lint 应答中每个分组用作键的 file。两种写法都是你可以打开的路径——前者相对于你指定的根目录,后者按原样打开——且两者都不会因文档所在位置而留空。

规则的后半部分是已配置的 catalog 目录所需要的。工作区可以指向机器上任何位置的 catalog 目录,其中的文档与根目录下的文档同样真实。为其命名的是绝对路径,这也正是 aggrega lint 和中止诊断在终端中为该文件打印的写法——因此无论你询问哪个界面,一个文件都只有一个名称。你不会得到一个向上越出根目录的路径,因为这样的路径会因读取位置的不同而指向不同的文件。

你拿到的是哪种写法,从值本身即可读出:你的平台视为绝对路径的就是第二种形式,其余都相对于工作区根目录。为了打开文件,你不必对此进行判断——把相对路径拼接到根目录上,或按原样打开绝对路径,都能奏效——但按工作区文档分组的客户端无需询问就能区分两者。

这条规则不涵盖的内容。 你发送的路径由该请求自身的契约约束,契约已在上文随请求说明,且通常更严格:目标路径必须相对于工作区根目录且解析后位于其内(包括其中的链接),否则会被拒绝。aggrega/publishDiagnostics 通知在任何情况下都以绝对路径携带其 file,无论在根目录内外,因为该值是你用来与自己已打开文档匹配的标识符,而不是工作区中的坐标——你的编辑器将其作为文件系统路径解析。aggrega/releaseCandidates 和 aggrega/activeRelease 以绝对路径指明每个 Release 和 lockfile,正如上文各自的条目所述。而 aggrega/irGraph 按编译器记录的样子携带编译后的图——只隐去作者声明为敏感的值——因此其中记录的任何路径都是编译器记录的路径,采用图自身契约规定的形式,而不是本协议为你组织的路径。

你发送的参数接受哪些写法

决定参数接受哪些写法的,是路径所指的对象,而不是携带它的方法。 上文每个请求自身的条目说明了它所接受参数的契约;下面说明它们之间的差异,以及为什么这是一种差异,而不是你需要按方法逐一记忆的不一致。

指明你已持有的文档的参数可以用三种方式书写:相对于工作区根目录的路径、绝对路径,或语言服务器客户端为已打开文档发送的 file:// 地址。 这包括 aggrega/validate、aggrega/diagnostics、aggrega/invalidate、aggrega/hover、aggrega/completion、aggrega/resolve、aggrega/findReferences、aggrega/findImplementations、aggrega/insertionPoint 和 aggrega/connectionAtPosition 的 file 或 uri。三种写法指明同一个文档,应答也相同,因为每种写法在任何读取之前都会在请求边界处归约为一种规范写法——因此以路径校验过的文档可以通过其地址找到,反之亦然,发送哪种写法都不会改变应答。当地址的 authority 为空或为 localhost 时,地址被读作它所指的路径,并解码其百分号转义;指向另一台机器的地址,在以这种方式打开该处文档的系统上被读作那台机器的网络共享,在其他系统上则不指向守护进程能打开的任何内容。同时携带查询、片段、凭据或端口的地址,同样不指向守护进程能打开的任何内容。不以 file:// 开头的值(无论大小写)永远不会被读作地址,而 file-not-validated 拒绝会指明你发送的值,无论其写法如何。其中,aggrega/insertionPoint 和 aggrega/connectionAtPosition 是在你未持有副本时从磁盘读取文档的两个请求,它们只为工作区内的文档作答:位于根目录之外的文档——无论是按书写方式,还是经由指向外部的链接(指向该文件或途经的某个目录)——无论用三种写法中的哪一种指明,都会被拒绝;而根目录内的文档在三种写法下都会得到应答。其余八个请求不会在其所指路径处从磁盘读取任何内容——aggrega/validate 从 content 获取文档字节,其余请求根据已校验的内容作答——因此无论你在何处持有文档,在工作区内与否,它们都会作答,也不会跟随它们所指的任何链接去读取文件。指明你从工作区之外选取的文档的参数,出于同样的原因属于同一情况:aggrega/import 的 source 在其实际所在位置读取,正如其自身条目所述。两者都是按类别对工作区边界的例外——客户端保持打开的文档,以及某人选取的文件——工作区边界说明了为何各自成为例外。

守护进程必须据以在工作区内定位文档的参数,只接受相对于工作区的路径。 需要了解的是 release——位于 aggrega/irGraph 上,以及它出现的其他任何地方,契约相同——绝对值会以 invalid-params 错误被拒绝,该错误先说明契约,再指明具体问题。在工作区内写入的请求也让其目标路径遵循同一契约,各自如其条目所述。随后,每个这样的路径都按其指向何处来判断,无论请求是读取还是写入,规则只有一条——即工作区边界所说明的“内部”的定义——指向外部的路径会以该请求自身的错误被拒绝,并按你发送的原样引用该值,不读取也不写入任何内容:指向外部文件的链接和途经目录的链接一样;位于指向外部的链接目录之下、尚未创建的路径,也会因该链接而被拒绝,而不会被写入,或在外部查找后报告为缺失。这涵盖请求指明让守护进程读取的每个路径——任何位置的 release、aggrega/lint 的 entity,以及发布类请求的 entity、plugin、file 和 from——因此请求无法通过链接读取工作区自身列表所排除的文件;也涵盖每个目标路径:生成、导入和构建写入的目录,aggrega/pin 在其旁写入锁的实体,aggrega/pluginSync 读取并重写的实体文件和模块,以及 aggrega/editDocument 编辑的文档。指明你的工作区配置所列 Release 的 release 是唯一的例外,正如 aggrega/irGraph 的条目所述。

两者之所以不同,是因为可能出现的问题不同。 指明你已持有文档的参数只留下一个问题——是哪个文档——因此把你的写法归约为规范写法不会丢失任何信息,接受每种写法也不会给你带来代价。从工作区中选取文档的参数则不同:在客户端可能使用的路径库中,把绝对值拼接到根目录上会得到该绝对值,而不是错误。因此,悄悄修复的值会让守护进程读取工作区从未包含的路径并针对其报告结果,你会被告知一个并不存在的文件。答案是拒绝而不是修复,因为修复这类值的守护进程会让每个发送此类值的客户端误以为契约是可选的。

如何寻址实体

响应中提到的每个实体都以相同方式寻址:kind、name 和 file。如需显示任何内容,请基于这三个键与 aggrega/catalogIndex 进行关联:它是承载实体完整描述字段集(apiVersion、description 和 labels)的接口,因此只需指称某个实体的响应只报告这三个寻址键,描述工作集中交给一处完成。按名称查找的请求(如 aggrega/entityDefinition)会重复其自身回答所涉及的少数描述字段;当你需要完整字段集时,仍应与索引进行关联。

当响应可能指称来自多个位置的实体时,每个标识除这三个键外还带有 origin。aggrega/catalogIndex 和 aggrega/attachCandidates 都是如此,因为它们的实体既来自工作区文档,也来自已配置的目录(catalog)目录。只取自一个位置的响应只报告这三个键而不带 origin,因为只有一个可能取值的键不提供任何信息——此类响应指称的每个实体都是工作区文档,其 file 是你可以打开的、相对于工作区的路径。因此,在 origin 存在时读取它,而不要求它处处都有;无论哪种情况,你都基于这三个键进行关联。

origin 属于列出实体的响应,在这类响应中,区分不同来源的实体群体是读者需要解决的问题。按名称查询的回答(例如 aggrega/entityDefinition)不携带该键:它指明的是该名称解析到的那一个实体,因此没有需要区分的群体。上方它自己的条目说明了其 file 何时为空;不要借助下面的 origin 取值来解读这种空值,那些取值描述的是列表。

origin 说明守护进程从何处读取该实体,正是它使 file 变得可解读。

  • workspace——位于工作区根目录下的 Aggrega 文档。file 是其相对于该根目录的路径,你的客户端可以打开该路径。
  • catalog——从已配置的目录(catalog)目录中解析出的实体。在此列表中 file 为空,name 即完整地址。之所以为空,是因为列表报告的是目录查找所枚举的内容,即一个标识而非一个文档,所以该条目没有可报告的路径——并不是因为其所在位置而隐瞒了路径。如需该文档,请用同一名称请求 aggrega/entityDefinition:该请求会解析实体,并按照上述规则报告其 file,因此位于工作区根目录之外的目录(catalog)目录在那里以绝对路径指称。name 本来就是 Aggregate、Recipe 和目录查找共同使用的坐标。

应将两者结合起来解读,而不是只检查 file。单凭空的 file 无法判断该实体是没有工作区路径,还是只是未报告路径;origin 直接回答了这一点。

当某个 Feature 可通过两种方式访问时(工作区根目录本身就是已配置的目录(catalog)目录之一,这是一种常见布局),它只报告一次,作为工作区文档,因为这是你可以打开其文件的那一份。

attach-candidate 响应告诉你什么

aggrega/attachCandidates 只回答一个问题——这个标签集接纳哪些 Features——并提供三种方式来说明你指的是哪个标签集。只发送一个坐标;发送两个或一个都不发送,请求会被拒绝,而不是被排序择优。

{node} 按 metadata.name 寻址一个工作区文档,不需要其他任何信息。匹配针对该文档在 metadata.labels 中声明的标签求值,响应报告 labelSource: "declared"。

{graphNode, release} 寻址已编译图上的一个节点。graphNode 是图用来索引该节点的 id——与你从 aggrega/irGraph 读到的 id 相同,包括由子 aggregate 贡献的节点所带的限定形式。release 是相对于工作区根目录的路径,指明要构建其图的 Release,与 aggrega/irGraph 接受的值相同。匹配针对节点的最终标签求值,响应报告 labelSource: "resolved"。

**{labels} 直接携带标签集本身,不寻址任何对象。**它是另外两种方式底层的形态:匹配是标签集与可用 Features 的函数,因此已经持有标签集的客户端无需指名,也无需等待。发送一个由标签键值对组成的 JSON 对象;响应报告 labelSource: "supplied" 和空的 node,因为该请求没有寻址任何节点。空对象也是一个坐标——它询问的是不带任何标签的节点——而完全省略该键或发送 null 则不寻址任何对象,会被拒绝。

**两种名称坐标之所以分开,是因为它们的标识符空间相互重叠。**图节点 id 与文档的 metadata.name 可能是同一个字符串,却指代不同的东西,因此用一个参数同时承载两者会产生歧义,而猜测你所指空间的守护进程有时会对错误的对象给出笃定的回答。说明你在问哪个问题,才能消除歧义。

labelSource 告诉你答案能覆盖到什么程度,三个值不可互换。declared 是针对单个文档关于自身的声明所做的匹配,也就是读取源码所能看到的内容。resolved 是针对节点最终实际拥有的标签所做的匹配,也就是构建据以评估适用性的依据——因此 resolved 答案是关于构建将如何判定的陈述,而 declared 答案不是。supplied 表示守护进程完全没有读取标签,而是匹配你发送的内容;这个答案有多可靠,完全取决于你的标签集从何而来。

**因此,持有图的客户端应当发送 {labels} 而不是名称。**节点的最终标签是它所解析到的 component 类型的标签,而不是恰好与其 id 相同的某个文档的标签,并且 label-transform 附件随后可能会添加、修改或移除这些标签——所以决定节点适用性的标签不一定是任何单个文档声明的标签。绘制图的客户端已经从 aggrega/irGraph 得到了这个标签集;把它传回去,就能得到与 {graphNode, release} 坐标相同的答案,而无需为此重新构建图。传回守护进程自己报告过的标签集——节点的来自 aggrega/irGraph,实体的来自 aggrega/catalogIndex——你对节点标签的理解就不会与守护进程的产生偏差,因为这个集合从未离开它自己的答案。自行拼装一个标签集,就是在问一个假设性问题,它会得到如实的回答,但并不是关于工作区中任何节点的陈述。

**候选项来自工作区和目录(catalog)。**把 Features 放在目录中而不是自身目录树里的工作区根本没有本地 Feature,其候选项全部为 origin: "catalog"。**对于图节点,两者都按该节点所属 Release 的范围读取:**目录中的 Features 是工作区配置为该 Release 指定的目录中所声明的那些,而工作区自身的文档在提供时会排除那些位于仅由其他 Releases 读取的目录下的文档。因此,为每个 Release 保留一个 Feature 变体的工作区,会为每个 Release 的图提供它自己的变体,而绝不提供其他 Release 的变体;而写在目录旁边、不在任何目录之下的 Feature 会提供给每个 Release。{node} 和 {labels} 不指明 Release,因此它们使用所有工作区文档以及工作区自身的 catalog_dirs。完全没有声明适用性的 Feature 是每个节点的候选项——没有声明就意味着没有要求——而声明无法读取的 Feature 不是任何节点的候选项,因为把无法读取的选择器视为已满足,会让一个拼写错误扩大你所提供的范围。

**无法解析的名称是错误,而不是空列表。**这两种答案含义不同:空的 candidates 数组表示该节点没有任何可附加的内容,而以这种方式报告拼错的名称,会把拼写错误呈现为确定的答案。拒绝信息会指明所搜索的空间,让你知道该去找工作区文档还是图节点。{labels} 没有这种风险——不存在可能拼错的名称——因此没有任何 Feature 接纳的标签集会以成功响应返回,并携带空数组;而守护进程无法读取的请求仍会在任何匹配运行之前被拒绝。

**图节点坐标需要 lockfile;另外两种不需要。**构建图意味着解析 Release 所能到达的内容,因此在尚未生成 lockfile 时,该路径会以 lockfile 缺失错误拒绝请求,并指明要运行的命令——这与 aggrega/irGraph 的前提条件相同,原因也相同。寻址工作区文档不构建图,提供标签集则什么都不构建,因此两者都可以在尚无人准备过的工作区上作答。

**它只报告,从不创建。**该方法不修改任何内容,不写入任何内容,也不创建任何附件。编写和应用编辑是编辑器的职责,缓冲区和撤销历史都在编辑器那里。

它解析什么取决于坐标,三者并不相同。{node} 不解析任何内容,也不访问任何 registry 或网络——候选项来自工作区和目录,两者都已在磁盘上。{labels} 解析得更少:它什么都不查找,因为没有可查找的内容。{graphNode, release} 会构建 Release 的图,因此它以与 aggrega/irGraph 相同的方式解析该 Release 的依赖闭包:先从本地目录和制品缓存解析,对两者都没有的实体再从配置的 registry 解析。对于实体全部在本地的工作区,三者都可离线作答;只有图节点坐标可能向更远处查找。

询问某个连接

组件绘制的连接可以携带自己的附件,用于填充其 socket 在消费方 Component 上声明的插槽——例如组件向该连接所到达的对象出示的凭据。在 {graphNode, release} 旁发送 connection,即可询问哪些内容可以放在那里:socket 是该连接所经由的依赖 socket,alias 是它在该 socket 内携带的名称,两者都与作者所写的完全一致。连接只存在于已编译的图上,因此在 node 或 labels 旁发送 connection 会被拒绝;未指明 socket 或 alias 的连接,或该节点并未绘制的连接,同样会被拒绝。

答案是图节点答案再加上该连接的插槽。candidates 的含义不变——即可以附加到节点本身的 Features——并新增 slots,socket 声明的每个插槽对应一个条目,顺序与 Component 声明它们的顺序一致:

  • slot——填充该插槽的附件在连接的 features 中所使用的名称。
  • selector、required、inject、sensitive 和 description——与 Component 在该 socket 上声明的插槽完全一致,未声明的项为空或 false。selector 是用于缩小候选范围的约束,因此仅凭答案即可解释某个候选项为何出现或为何缺失。
  • candidates——可以在此连接上填充该插槽的 Features。构建会让这类附件同时满足两条规则,并且两条都会应用:Feature 声明的适用性与节点最终确定的标签相匹配,节点携带的每个附件都需满足这一点;以及插槽的 selector 与 Feature 自身的标签相匹配。因此,插槽的候选项始终是节点候选项的子集,并经选择器进一步缩小。如果选择器无法针对某个 Feature 的标签求值,则该 Feature 不会被提供,因为构建会拒绝而不是接纳它。

**当没有任何插槽可以填充时,slots 是一个空列表,noSlotReason 说明原因。**请阅读原因,而不要把空列表当作“没有 Feature 匹配”——那是另一种答案,而原因正是区分两者的依据:

  • feature-created-connection——该连接由某个 Feature 从其自身的依赖块中绘制。附件只能写在由组件或 Release 绘制的连接上,因此无论 socket 声明了什么,这里都不能放任何内容。
  • ad-hoc-socket——该 socket 并非 Component 所声明的。作者为其命名是合法的,而未声明的 socket 不声明任何插槽。
  • no-slot-declared——Component 声明了该 socket,但其上没有插槽。

只要存在插槽,noSlotReason 就不会出现;对于未指明连接的请求,其答案中 slots 和 noSlotReason 都不会出现——因此未指明连接的请求,其答案中这两个字段都没有。

**document 会被接受,但在此处不改变任何内容。**插槽属于 socket,候选项属于 Features,无论附件写在哪个文档中都相同;附件写到哪里由 aggrega/attachmentContainer 回答。aggregate 或 release 以外的值仍会被拒绝,因为一个被接受却被忽略的值,在发送方看来就像已被采纳。

connection-candidate 响应告诉你什么

aggrega/connectionCandidates 同时回答两个问题,其中只有一个有完整的答案。把响应当作一个经过筛选的单一列表来读,会把另一个问题理解错。

每个报告的 socket 都带有 targets——工作区本地的 Components,其声明的标签满足该 socket 针对可满足它的对象所声明的标签约束——以及计算这些目标所依据的 selector、该 socket 声明的 required 标志和 declaration。targets 始终是一个数组,为空而不是缺失,因此没有任何对象满足的 socket 仍会作为实体所声明的 socket 被报告。

**目标这一半是完整的。**该集合通过将 socket 声明的约束与候选者声明的标签进行求值来确定,与构建执行的求值相同,因此你提供的选项就是同一约束在构建期间所接受的。未声明约束的 socket 不对其目标施加约束,并报告每一个 Component——这是约束语言对空 selector 的含义,而不是错误。

socket 这一半是开放的,declaration 加上 adHocSocketsAccepted 用于区分。Aggregate 的作者拥有其拓扑,可以连接该组件的目录实体从未声明过的 socket,因此实体声明的 socket 是一个有用的起始集合,而不是合法 socket 名称的集合。应将它们作为建议呈现,而不是唯一的选择——只提供已声明 socket 的选择器会让作者以为自己的自由度比实际更窄。

  • 当被寻址的实体在其 usesSchema 中列出该 socket 时,declaration 为 declared;未列出时为 ad-hoc。这与 IR 图中边所携带的两个值相同,因此无论在何处遇到“这个 socket 来自哪里”的问题,都由同一套词汇回答。
  • adHocSocketsAccepted 报告被寻址实体的接口面是否接受其自身声明中未列出的 socket。它并非总是为真:Component 自身的依赖接口面接受,而 Feature 的挂载接口面不接受,因为挂载参与的是被挂载的 Feature 所声明的拓扑,而不是自行编写拓扑。在不接受临时 socket 的接口面上,临时 socket 会被报告为没有目标,因为经由它的任何连接都无法构建。

在请求中指定 socket 会将答案限定为该 socket,这也是询问实体未声明的 socket 的唯一方式——未声明的 socket 不出现在任何可枚举的声明中。省略它则按编写顺序获取实体声明的所有 socket。

它报告的是基于已声明标签的匹配。构建会将 socket 的约束与边远端节点的最终标签进行求值,而这些标签是该节点解析到的组件类型的标签,并且已经过任何 label-transform 挂载的处理——不一定是你所指定文档的标签。因此,这里的肯定答案并不是对构建将如何判定的承诺——这与 aggrega/attachCandidates 在其 declared 标签来源下所带的限制相同。

**它只报告,从不创建。**该方法不解析任何内容,不访问任何注册表或网络,也不写入任何内容:它不创建边,也不提议文本。编写和应用编辑由编辑器负责,缓冲区和撤销历史都在那里。

对于 targets 中的实体标识——kind、name 和 file——按照如何寻址实体中的描述与 aggrega/catalogIndex 进行关联。描述性字段在那里报告,并有意不在此重复,因此本响应不携带可能与之不同步的第二份副本。目标是工作区 Components,因此每个目标都有一个你可以打开的 file,且都不带 origin:本响应只取自一个地方,关联基于这三个键。

attachment-container 响应告诉你什么

aggrega/attachmentContainer 位于上文的候选请求与下文的插入点之间。前者说明什么可以附加到一个节点;它说明该节点的附加项属于哪个容器,以及位于哪个文档中;后者说明文本应放在该文档字节中的哪个位置。

请求容器,而不是自行拼装。 节点的 id 和包含它的子系统路径都用点分隔各部分,而点在作者输入的名称中是合法字符——因此从文档外部无法区分结构性的点与名称内部的点。自行组装路径的客户端会得到一个看似正确、却指向无人编写的键的结果,随后的编辑会创建该键,而不是被拒绝。两条路径都由编译器拼装,因此也由编译器拆解。

节点 id 完全不带有其所在子系统的痕迹。 在 subsystems.billing.subsystems.payments 内编写的组件在图中的键为 ledger,与顶层组件完全相同,因此无论客户端如何仔细地拆分,id 中都没有可依据的信息。

答案包含三个字段。

  • node 重复答案所针对的节点,因此同时有多个未完成请求的客户端无需自行记录顺序,即可将每个答案与其问题配对。
  • file 是编写该节点的文档,相对于工作区。它属于答案,而不是你已知的信息:由导入模块提供的节点,是在该模块自己的文档中、以模块赋予的名称编写的,因此文件和容器的最后一段都与请求中给出的任何内容不同。
  • container 是从该文档根开始的结构路径,以段列表表示——["spec", "subsystems", "billing", "subsystems", "payments", "components", "ledger", "features"]。每一层外围子系统都再次位于 subsystems 键下,这正是文档的写法。作者在顶层编写的组件则给出 ["spec", "components", "checkout", "features"],因为这类组件被编译进的作用域不包含在任何文件中。

它是段列表,绝不是拼接后的字符串,这正是该形态的用意。拼接后的路径必须由接收方再次拆分,这等于在下一次调用中重新引入了上述歧义。将该列表原样作为 container 传给 aggrega/insertionPoint。

它只读取结构,从不读取含义。 答案来自编写该节点的文档、节点所在的作用域以及作者输入的名称。不会从组件的名称、类型或任何标签的内容中读取任何信息。

它只报告,从不写入。 该方法不修改任何内容,也不向任何文档写入。它不创建附加项、不拼装文本、不应用编辑;它也不判定什么可以附加,那是 aggrega/attachCandidates 的职责。

指定了图中不存在的节点的请求会被拒绝,而不是给出答案。 节点 id 是图自身的键——从 aggrega/irGraph 返回的图中读取——由导入模块提供的节点带有限定 id。图中未记录文档的节点同样会被拒绝:附加项应属于何处是关于文档的事实,因此没有文档的节点没有答案,而不是得到空答案。

它需要锁文件,原因与 aggrega/irGraph 相同:确定容器意味着构建该 Release 的图,而由无人担保的字节构建的图,其报告方式会与经过检查的图完全相同。

连接上的附加项

在 {graphNode, release} 旁发送 connection——包括其 socket、alias 和 document——答案将给出该连接自身条目上的 features 容器,而不是节点的容器。此处 document 为必填,因为对于 Aggregate 绘制的连接,两个文档都可能持有其附加项:开发者将其写在 Aggregate 中该连接的条目上,运维人员则写在 Release 中对应的逐边条目上。

  • aggregate 指定编写该节点的文档中该连接的条目——对于顶层组件为 ["spec", "components", "gateway", "uses", "models", "gpt", "features"],每一层外围子系统按上文方式逐层写出。由 Release 绘制的连接在 Aggregate 中没有条目,因此在该处会被拒绝。
  • release 指定 Release 中该节点自身条目下的逐边条目——["spec", "boundaries", "cluster", "components", "gateway", "uses", "models", "gpt", "features"]——无论该 Release 是否已编写该逐边条目。若尚未编写,aggrega/insertionPoint 会在 missingContainerKeys 中报告仍需写入的键。此时 file 为该 Release 文档。完全没有为该节点编写条目的 Release 会被拒绝:节点放在何处由运维人员编写,答案不替其决定。

由 Feature 绘制的连接在两个文档中都会被拒绝,原因见上文 feature-created-connection。节点、socket 和别名均按书写内容精确匹配,节点未绘制的连接会被拒绝,而不是返回一条路径。上文的其他所有特性均保持不变:答案是段列表,只读取结构从不读取含义,并且不写入任何内容。

connection-at-position 响应告诉你什么

aggrega/connectionAtPosition 是上面两个连接请求之前的一步,面向持有文档中某个位置而非图上某个节点的客户端——例如光标停在某个连接的条目上。它回答那里写的是哪个连接,使用那些请求所接受的坐标,然后就此为止。

答案是两半之一,绝不会两者兼有。

  • graphNode 和 connection——前者是其组件绘制该连接的节点,使用编译后的图为其设定的键 id;后者按其 socket 和 alias 标识该连接,并由 document 指明读取该位置的文档:aggregate 表示 Aggregate 或其导入的模块,release 表示 Release。将 graphNode、同一个 release 和 connection 传给 aggrega/attachCandidates 以获取该连接的 socket 声明的槽位,传给 aggrega/attachmentContainer 以获取其上附件的去处;它所指明的容器正位于该位置所在的条目之内。
  • noConnectionReason——未报告连接的原因。该集合是封闭的:
    • no-connection-entry——该位置不在任何可写入附件的条目上。以目标列表形式写出的连接(db: [store])以及由 Feature 自身依赖块绘制的连接都没有这样的条目,因此位于两者之一上的位置也返回此值。
    • feature-created-connection——该位置位于 Release 为某个由 Feature 绘制的连接所写的条目上,出于上文槽位答案给出的原因,该条目不承载附件。当 Feature 的依赖块通过一个消费方 Component 同样声明的 socket 进行绘制时,Release 会写出这样的条目;无论该条目什么都不配置,还是设置连接的逐边 infra,它都能构建成功。
    • unknown-connection——该位置位于 Release 为某个编译后的图中不存在的连接所写的条目上。一个能构建成功的 Release 可以包含这样的条目——例如,位于一个没有任何东西绘制的别名下、什么都不配置的条目(没有 target、没有 infra、没有 features),或者为一个被 active: 开关关闭的组件所写的条目,其连接随之离开构建。

哪些条目算数。 在 Aggregate 中,是组件绘制的每个连接,位于编写该组件的文档中该连接别名下的条目——对于由导入模块贡献的组件,则是该模块自己的文档。在 Release 中,是它写出的每个逐边条目,无论该条目是自己绘制连接,还是配置 Aggregate 绘制的连接。每个条目所在位置由编译后的图记录,因此某个键是否为连接,绝不会根据它的名称推断。被 active: 开关关闭的组件不在编译后的图中,因此它在 Aggregate 中自身的条目返回 no-connection-entry,而 Release 中为其某个连接所写的条目返回 unknown-connection。

条目内的任何位置都算在条目内。 条目从其别名键开始,一直延伸到其下缩进的最后一行,因此位于别名上、其 target 上或其 features 内的位置都按该连接作答;条目嵌套时,最内层条目优先。位于 socket 自身键上、在其下所写别名之上的位置,不在任何别名条目内——无论该 socket 包含一个还是多个别名——别名键之前缩进处的位置也是如此。

哪个文档是哪个,由 Release 决定。 Release 自身的文件按其写出的条目读取;其他任何文件按图所记录的组件编写位置的条目读取。Release 的图不从中读取任何内容的文档,在每个位置都返回 no-connection-entry。

它只报告,从不写入,并以与 aggrega/insertionPoint 相同的方式读取文档:优先读取会话中的副本,否则读取磁盘,限于工作区内,对于位于工作区外、无法读取或不是格式良好的 YAML 的文档,同样予以拒绝。它需要 lockfile,原因与 aggrega/attachmentContainer 相同,并在不渲染任何内容的情况下构建图。

插入点响应告诉你什么

aggrega/insertionPoint 是上述两个候选请求的对应请求。那两个请求说明什么可以挂接或连接;这个请求说明相应文本在某一特定文档中应放在哪里。它给出答案后即止步。

你指定容器;守护进程定位它。 container 是从文档根开始的结构路径——["spec", "components", "web", "features"]——它是你对此类条目在此类文档中应放在何处的声明。守护进程不会根据实体的名称、它携带的类型或它看似表达的含义推导该路径。它读取作者写下的字节,并报告该文档已具有路径中的哪些段、其条目所在的列,以及其最内层块到达的最后一行。因此,知道哪个键由调用方负责,而知道该键的条目在此文件中放在哪里则来自这里。

对于编译后图中某节点上的 Feature 挂接,调用方不必自己知道那个键:向 aggrega/attachmentContainer 请求文档和容器,然后将两者原样传到这里。

答案是一个零宽度位置,加上你需要在其周围写入的内容。 file 是该文档,相对于工作区。container 重复你所询问的路径,因此同时有多个未完成请求的客户端无需自行维护顺序,即可将每个答案与其问题配对。position 表示插入而非替换:文档中已有的内容不会被覆盖或移动。

  • precededByLineBreak——以换行符开始你写入的文本。该位置位于新条目所跟随那一行的末尾,无论文件是否以换行符结尾都在范围内,且不会扰动任何已写入的字节。只有当文档中没有可跟随的内容时它才为 false,此时你从文件开头写入。
  • missingContainerKeys——容器路径中该文档尚未包含的段,从最外层开始。每一段都必须先作为单独的键写入,条目才能放入最内层的那个键中。当整个路径已存在时,它为空。
  • entryIndent——条目自身第一行起始的列,从行首开始以空格计数。
  • indentStep——每一嵌套层级额外缩进的量。
  • indentStepMeasured——该步长是否根据此文档自身的嵌套测量得出。为 false 时,文档中没有可供测量的嵌套,步长是一个回退值,因此更愿意使用自己步长的客户端知道它可以这样做。
  • entryShape——mapping 或 sequence,根据容器已包含的内容读取;当容器尚不存在或为空时为 unknown。unknown 不是失败:文档尚未表明其条目采用何种形态,因此由你来选择。

应用答案。 当设置了 precededByLineBreak 时,写入一个换行符。然后为每个 missingContainerKeys 条目写一行,从最外层开始,每行是键后跟一个冒号——第一行缩进为 entryIndent 减去 indentStep 乘以缺失键的数量,之后每行再多缩进 indentStep。然后写入条目本身,缩进为 entryIndent。当 missingContainerKeys 为空时,条目是你写入的唯一一行。

即使你预期容器已存在,也要读取 missingContainerKeys。应用某个位置时若缺少必须位于其前的键,产生的文档将无法再解析,而这正是此答案绝不能被误读为不存在的那种失败。

position 从零开始计数,与诊断的位置不同。 line 和 character 都是从 0 开始的,与本协议复用的 LSP 形式位置值一致;而诊断条目上的 line 和 column 是从 1 开始的,如诊断条目携带什么中所述。在两者之间互相转送数据的客户端需要进行转换。

positionEncoding 指明 character 的度量单位,它是握手时协商的编码。之所以在答案中报告而不是隐含,是因为调用方需要猜测单位的位置是无法应用的位置:以一种方式测量的偏移量应用到以另一种方式测量的缓冲区中,会在第一个非 ASCII 字符处破坏文档。

未指向条目可放置之处的请求会被拒绝,而不是得到回答。 以下每种情况都是请求的状态,而非工作区的状态,因此会返回标准的 invalid-params 代码,且在 file 或 container 改变之前,重试不会有任何变化。

  • 文档未被指定、不在工作区内、无法读取,或不是格式良好的 YAML——没有结构的文档没有可报告的位置。
  • 容器路径没有指向任何内容:它不包含任何段,或其中某一段为空。
  • 路径经过文档中作为标量的值。标量内部无法追加任何内容,而替换它将是重写而非插入。
  • 路径到达作者以流式风格编写的集合。向其中追加条目会重写作者已写下的字节,而不是添加一行,这属于编辑而非位置。
  • 路径用非索引的内容来访问块序列。序列的条目按位置访问,因此名称在序列中找不到任何内容,也无法创建承载该名称的条目。

它读取编辑器持有的缓冲区,而不仅是磁盘上的文件。 守护进程会先查询其解析缓存,因此如果存在未保存的内容,位置将基于该内容报告;如果缓存中没有该文件的内容,则基于文件本身报告。

它只报告,从不写入。 该方法不修改任何内容、不解析任何依赖、不访问任何注册表或网络,也不向任何文档写入内容。它不组合条目的文本,也不应用条目。组合并应用编辑由编辑器负责,缓冲区和撤销历史都在那里。

document-edit 响应告诉你什么

aggrega/editDocument 是上面那对请求的另一半:那些请求说明条目应放在哪里,由你自己编写并应用它;这个请求则编写并应用一个条目,并且它会写入。两者都保留可用,因为持有未保存缓冲区的客户端与编辑磁盘上内容的客户端需要不同的一半——拥有自己撤销历史的编辑器自行放置文本,而宁愿直接编辑文件、不想被告知在哪里编辑的客户端则发送这个请求。

一次调用应用一个编辑,编辑的集合是封闭的。 edit 指明是哪一种:add-component 在 components 容器下添加一个组件实例,attach-feature 将一个 Feature 附加到节点上,wire-edge 在节点的某个依赖插槽内连接一个连接,set-value 在节点上设置一个值。不存在删除、替换你已写好的块、重新排序任何内容或逐字写入你提供的字节的编辑——因此这并不是换了个更窄名字的文件写入器,这四种之外的值会被拒绝而不是被解释。拒绝信息会列出你可以指定的值。

你以结构路径指定节点,与上面两个请求接受路径的方式完全相同。 node 是从文档根开始的路径——["spec", "components", "web"]——条目所进入的容器由 edit 决定。对于 add-component,路径指定的是 components 容器本身,因为被添加的条目就是该节点。name 是条目写入时使用的键:实例名、附件名、连接的别名或值的键。value 是该条目携带的内容,其含义由 edit 决定——条目所请求的实体、连接指向的节点,或值被设置成的标量。socket 仅对 wire-edge 读取,其他情况下忽略。

之所以用路径而不是名称,理由与定位请求接受路径相同:名称需要搜索,而出现在两个层级的名称会让编译器去决定你指的是哪一个。因此,知道自己在编辑哪个节点的客户端会明确说出来,而不知道的客户端则知道在编辑任何内容之前,它还有一个问题需要回答。

编辑未触及的每个字节都会保留。 文档只被解析以定位容器及其块结束的行;条目在行级别渲染并拼接。注释、空行、引号风格、折叠和字面标量、模板表达式以及末尾换行的形式都原样保留,嵌套步长从文档自身的缩进中测量而非强加——因此条目会落在你已在使用的风格中。对同一文档发出同一请求会产生相同的字节,因此客户端可以比较两次运行,评审时一次编辑就是一个 diff。

结果必须是你本可以手写出来的文档,写入正以此为前提。 编写出的文档会按其自身种类的 schema 进行校验,只有通过才会写入磁盘。会产生编写 schema 所拒绝内容的请求将返回 E0275——the edit was refused because the resulting document would not be valid, and nothing was written(编辑被拒绝,因为生成的文档将无效,且未写入任何内容)——并附带 schema 不接受的属性及其位置。文件按字节保持原样,因此被拒绝的编辑与从未尝试过的编辑无法区分,你可以针对最初的文档重试修正后的请求。这也是这里不重述任何规则的原因:要求一个 Release 文档携带开发者值,会被同一个拒绝手写文档的 schema 拒绝。

语义上是否可接受不在这里决定。 某个依赖插槽是否是生产者声明的插槽,或者某个 Feature 的适用条件是否满足,属于构建所执行的解析,各有其报告方式。因此你可以指定这个请求从未见过的连接,一个 Aggregate 也可以编写其目录实体未预先声明的插槽;而跨插槽可以消费什么,仍由生产者声明。当问题在于此时,运行指定某个 Release 的 aggrega/validate,或请求图。

答复说明了落下了什么以及写入磁盘的是什么,这是两个不同的问题。 在两种交付方式下,content 都携带编辑生成的文档。written 指明写入磁盘的文件,在 dryRun 下为空。container 是条目所落入容器的结构路径,因此你无需重新推导该规则即可定位刚添加的内容。createdContainers 指明本次编辑因文档中不存在而写入的路径段,最外层在前——在整个路径已存在的常见情况下为空;读取它就能区分条目是添加到现有块中,还是自带新建了块。file 和 edit 回显你发送的内容,因此有多个未完成请求的客户端可以把每个答复与其问题配对。written、container 和 createdContainers 始终是数组,为空而不是缺失。

在 dryRun 下不会创建任何内容。 written 为空,content 携带写入本应生成的文档,文件保持不变——因此编辑器可以把结果展示给作者,由其保存、修改或丢弃。默认是写入,因为该操作的产物是编辑后的文档,产生文档的接口理应交付它:未说明交付方式的请求会编辑文件。

写入所做的其他一切,试运行也都会做。 无论哪种方式,编写出的文档都会按其自身种类的 schema 校验,因此写入会拒绝的编辑在 dryRun 下同样会被拒绝,并指出相同的属性——这意味着你从试运行得到的错误,就是写入会给你的错误。

已存在且携带你所请求内容的条目是空操作——文档原样返回,不写入任何内容。同名但携带其他内容的条目会被拒绝而不是被替换,因为替换作者写下的内容不属于这四种编辑。

写入之后,守护进程会重新读取文档。 它为该文件持有的内容会被丢弃,其工作区级视图会被重置,因此下一次校验、悬停、补全或图请求都基于编辑生成的字节来回答,而不是基于被替换的版本。编辑本身读取的是磁盘上的文件,而不是你持有的缓冲区——这与上面的定位请求不同,后者会先查询未保存的内容。这是有意为之:从未保存的缓冲区写入,会以应用一个条目为名,把作者尚未保存的内容写到文件中。请先保存缓冲区,再编辑。

未指向条目可放置位置的请求会被拒绝而不是被回答,返回标准的 invalid-params 代码,并且在请求改变之前重试不会有任何变化。具体情况包括:文档未指定、不在工作区内、无法读取、不是格式良好的 YAML,或未声明可用于检查结果的 schema 所属种类;edit 未指定或不是这四种之一;node 不指向任何内容,或其某个路径段为空;未给出 name;wire-edge 未指定 socket;set-value 在应为标量的位置得到了映射或序列;节点路径到达标量、序列或以流式风格编写的集合,而添加一行会改写已写入的字节;或节点路径在文档中不指向任何内容。

在两种交付方式下,它都不解析任何依赖、不访问任何注册表,也不接触任何网络。

有效配置响应涵盖的内容

aggrega/effectiveConfiguration 回答两个问题:本会话中适用的是什么配置,以及每项设置由哪一层决定。它与 aggrega config show --origin 打印的答案相同,只计算一次并在两个界面上报告,因此两者不会在设置来自何处这一点上产生分歧。

source 有四种形态之一。 配置文件的绝对路径——包括以 aggrega --config <file> serve 启动的守护进程所读取的全局文件,以给定的路径命名;带 env: 前缀的环境变量,例如 env:AGGREGA_SIGNING_REQUIRED;在启动守护进程的命令行上键入的全局标志,以标志命名,例如以 aggrega --offline serve 启动的守护进程对应 --offline;或者对于没有任何层设置的设置,为 (built-in defaults)。前三种原样出现在 layers 中。默认值不会出现,因为默认值不是作出贡献的层——它们是在没有任何层发声时适用的值。

一项设置归属于设置它的最高优先级层,无论该层写入的是什么值。 写入内置默认值、或重申其下层文件已设置之值的配置文件,就是被指名的文件:正是它将该值固定在原位。文件通过携带某设置的键来设置它(包括列表的 _append 配套键),环境变量则通过以非空值导出来设置。你的流水线所拥有的配置文件,绝不会因其忽略的键而被指名。aggrega config show --origin 按同一规则报告。

配置 schema 声明的每项设置都有交代,但并非每项都有自己的一行。 列表的累加型 _append 配套键报告在它所追加的列表那一行上,因此仅通过配套键作出贡献的层会在该列表的行上被指名,配套键本身没有行。列表条目内部的设置——registry 的信任策略、插件挂载的输入——由该列表的行涵盖。

另有两个限制,每一个都会使答案比看上去更粗略。

  • 列表或映射类设置作为整体归属于设置它的最高优先级层。不跟踪逐条目的归属,因此由两层组合而成的列表只报告优先级较高的那一层,较低层贡献的条目与较高层写入的条目无法区分。
  • 签名要求归属于第一个开启它的层,而不是最后一个提及它的层。该设置的组合方式是:任何开启它的层都胜出,之后的层都无法将其关闭,因此第一个开启它的层就是使有效值成为当前值的那一层。写入 required: false 的层不开启任何东西,因此当所有提及它的层都写入 false 时,该设置报告 (built-in defaults)。

每个报告的值都是该工作区首次被指名时得出的解析结果。 编辑配置文件不会改变这里的值;重启守护进程才会。这是有意为之——这些值正是回答该工作区所有其他请求时所依据的配置,这也使它们能与握手为该工作区报告的根目录和配置层相比较。在用户正在编辑的文件旁显示配置的客户端,应说明自己显示的是两者中的哪一个。

层归属是在你询问时、针对文件当前状态计算的。 因此之后编辑的配置文件可能会使 source 改变,而其旁的值仍保持解析时的样子。两半回答不同的问题——什么在生效,以及哪一层决定了它——只有前者是固定的。重启守护进程可使两者重新同步。

它只报告,从不写入。 该方法不更改任何配置,不创建任何文件,也不从 registry 或网络解析任何内容。

这里不提供单层文件的内容。 命令行可以原样打印某一层自身的字节,保留注释和格式;本方法报告的是解析结果而非字节。需要某层文本的客户端可从 layers 中获得路径并打开它。

配置写入会留下什么

aggrega/configInit 和 aggrega/configCapture 都会生成一个配置文档,并且都会写入它。响应会给出该文件的名称;打开它是你的下一步操作,而不是写入的替代。除非你明确要求,二者都不会把内容交给你自行放置,因为一个产物是从未写入的文档的能力,是另一种借用了同一名称的能力。

**二者的作用范围不同,每个响应都会说明是哪一种。**在展示结果之前先读取这一点。

  • **默认情况下,初始化写入的是本机所有工作区共享的配置。**一个 registry 以及你在其上信任的身份通常在你工作的任何地方都相同,因此除非请求发送 workspace: true,条目都会写到那里。scope 携带被写入的 configFile,以及表示它是否为共享文件的 machineWide——它由写入实际解析到的文件推导而来,而不是由请求所要求的内容推导,因此响应不会把全机范围的更改描述为本地更改。
  • **冻结从不超出工作区。**它不接受写入目标,也不接受覆盖:它的全部目的是让一个项目自包含,因此它总是写入该项目自己的 .aggrega-config.yaml。这就是为什么它的响应携带 configFile 和 workspaceRoot,而不声明作用范围——没有需要说明的范围。

**初始化会拒绝而不是覆盖。**已存在的配置文件保持不变,拒绝信息会指明该文件,因为初始化针对的是尚不存在的配置,而它所委托的共享写入在设计上会进行合并。发送 force 以强制写入;registry 条目会合并到已有内容中,其他设置保持不变。被拒绝的请求不会做任何更改。

trust 以独立的结果而非文字描述来说明 registry 所公布的策略产生了什么作用。pinned 表示 registry 公布了策略且该策略被采用,identities 给出身份的数量。notAdvertised 表示已询问 registry 而它未公布任何策略,这不是失败——初始化会继续,reason 说明该端点做了什么。无法访问的 registry 也以这种方式报告,因为同样没有返回策略且初始化同样继续;当失败本身表明从未访问到该 registry 时,它还会同时携带 unreachable:其名称无法解析、到它的连接被拒绝或无法打开,或无法与它建立安全连接。已作出响应的 registry——无论返回 not-found 还是错误状态——都不会携带 unreachable,因此请读取该键而不是 reason 的措辞,来区分不发布策略的 registry 与从未被询问的 registry。baseline 表示由于没有采用任何公布的策略,官方 hub 的内置基线被固定,reason 说明原因;该条目带有策略,因此无需手动固定。这两个键回答不同的问题,因此被询问且未公布任何内容的 hub 会同时携带两者,而处于离线工作区中的 hub——从未被询问——只携带 baseline,reason 说明工作区处于离线状态。其他任何未公布策略的 registry 只携带 notAdvertised,以无策略的方式初始化,随后的建议是手动固定身份;离线时它会被拒绝而不是得到响应。skipped 表示未尝试获取。把 pinned 之外的任何结果都当作错误的客户端,会把一个正常工作的配置报告为损坏。

在 dryRun 下不会创建任何内容。written 为 false,content 携带写入本应生成的文档,该内容所对应的文件是 scope.configFile。不会创建目录,也不会触碰任何文件,因此编辑器可以把文本呈现给作者,让其保存、修改或丢弃。

**试运行与写入只在一个方面不同——它不写入——因此写入会执行的每一种拒绝它也都会执行。**这里重要的是已存在文件的拒绝:对已存在的配置文件执行 dryRun 会被拒绝并指明该文件,与写入完全一样。这正是使该响应可以用作判断依据的原因——如果试运行拒绝,写入也会以相同的原因和相同的消息拒绝。将 force 与 dryRun 一起发送,即可改为得到覆盖写入会产生的合并结果,同时仍不写入任何内容。无论哪种交付方式,都会联系 registry 获取其公布的信任策略,因为该内容中的策略就是写入本应固定的策略。

冻结报告的是它写入的内容,而不是对其的描述。sockets 列出每个被冻结的插件 socket 以及在那里冻结的附加项;catalogDirs 携带目录(catalog)目录。两者始终是数组,为空而不是缺失。

  • socket 和 field 不是同一个字符串,这种差异也并非表面上的。socket 指附加项所绑定的 socket;field 是它们在文件中写入时所用的键。两者仅在 provider socket 上不同,它写在一个复数键下——因此在把读者引向文档中某一行时使用 field,在指称 socket 本身时使用 socket。
  • **每个附加项都携带 uri、capability、function 和 role,仅当该附加项具有相应值时才出现。**它们用于指称附加项而不是完整复现它:附加项可选的附加时输入会原样冻结到文件中,不会在响应中重复。文件才是权威副本。
  • **captured: false 表示成功。**如果构建不涉及某个项目的配置,该项目就没有影响构建的内容需要冻结,因此文件保持原样,两个列表都返回为空。把它当作错误会把一个健康的工作区报告为损坏。

默认只冻结决定输出字节的内容——provider 绑定,以及转换标签的 governance 附加项。裁决型 governance、linter 关卡和 import socket 不包括在内,因为它们本就应在不同环境之间变化,冻结它们会把某一个环境的关卡带入每一个检出副本。allPlugins: true 会把范围扩大到所有插件 socket。成员资格按附加项而非按 socket 计算,因此一个同时带有一个标签转换附加项和一个裁决附加项的 governance socket,在默认情况下只贡献前者。

每个值都按其生效值冻结——即本机配置与项目自身配置合并后解析出的值——因此一个目前仅来自本机配置的绑定会被写入项目并随项目一起迁移。全机范围的工具设置(包括 registry 的信任策略)不影响构建,保持在原处。在配置未改变时冻结两次会重写相同的字节,因此客户端可以放心提供该操作:第二次调用会让读者手中的文档保持原样。

插件变更告诉你什么

四个插件请求都默认写入,并按写入的内容分为两类:两个修改配置文件,两个在工作区中生成文档。其中两个——添加和生成——接受 dryRun,它执行请求的其余所有操作,但不写入任何内容。请读取应答自身对变更落点的说明,而不要从请求推断——对其中一个请求而言,请求未提及作用域意味着最广的范围。

添加和移除都携带 scope,它由写入实际解析到的文件推导而来。 configFile 就是该文件,machineWide 表示它是否是本机上每个工作区都会经由其解析的那个文件,workspaceRoot 指明本会话所打开的工作区,因此工作区作用域的应答会说明是哪个工作区。machineWide 读取自解析后的文件,而非请求所要求的内容,正是这一点使应答不会把机器范围的变更描述为本地变更。

🔴 既未指定 global 也未指定 workspace 的 cli 类型添加会在机器范围注册命令。 命令扩展属于机器范围的工具,因此在没有覆盖的情况下,它被写入本机每个工作区都会经由其解析的全局配置文件——它注册的命令随即成为该机器上每个项目的顶层 aggrega 命令,包括本会话中无人提及的项目。provider、governance、linter 或 importer 添加则相反:它们影响单个项目的构建,因此在没有覆盖的情况下写入该项目自己的 .aggrega-config.yaml。对于相同类型,移除遵循同样的规则。发送 workspace: true 可使命令扩展保持本地,发送 global: true 可将其他任一类型推送到共享文件;两者同时发送会被拒绝。无论哪种情况,应答上的 scope 都是权威说明,客户端应在依据结果行动之前展示它。

添加会指明落地的内容,且恰好有三个字段之一说明它是哪类事物。 type 回显添加条目所针对的类型,然后:对于 governance、linter 或 importer 挂载,identity 携带固定版本的裸实体标识;对于 provider 绑定,uri 携带插件的 oci:// 制品地址,并附带它现在服务的 capability;对于 cli 安装,reference 携带其命令已被注册的固定引用。因此调用方从应答中读取落地的是哪类挂载,而不必根据自己发送的类型重新推导。移除只在其 scope 旁回显 type 和 query,别无其他——对一个已不存在的条目,没有更多可报告的内容。

添加还携带 written,并在 dryRun 下携带 content。 written 是客户端据以分支的字段:为 true 表示现已在磁盘上、客户端可以打开的配置文件;在 dryRun 下它为 false,而 content 携带写入本应生成的配置文档。两者从不同时有意义,且 content 所对应的文件是 scope.configFile,因此应答中没有任何内容携带该路径的第二份副本——这一点在此很重要,因为 global 挂载的文件是本机每个工作区都会经由其解析的那个文件。

没有已发布版本的插件会被拒绝,而不是以未固定版本的方式挂载。 添加会将查询解析为一个插件并固定其最高已发布版本,因此它写入的条目带有版本。仓库中没有发布任何符合要求版本的插件会被拒绝并指明该插件;本工作区所信任的撤回声明已撤回的版本会被跳过,转而选用下一个较低版本。

查询指明的版本即使已被撤回也会被固定,并由 withdrawn 说明这一点。 写作 <name>:<version> 的 query 会固定该版本而非最新版本——适用于除 provider 之外的所有类型,后者仅按名称绑定并拒绝指定版本——而指明版本本身就是覆盖:若本工作区信任的撤回声明已撤回该版本,它照样会被固定,且应答带有 withdrawn: true——即 aggrega plugin add 在终端上以一行 retraction: 陈述的事实。withdrawn 在其他所有应答中都不出现,因此它的出现就是全部信号——而它的缺失并不表示该版本未被撤回。若无法读取指明版本的撤回标记,withdrawn 不出现,retraction 带有 unscreened 并说明原因,与未指明版本的添加遇到同样故障时的情形相同;未指明版本的添加则改为在 retraction 中报告撤回检查对其所选版本得出的结论。

对齐会报告它是否做了任何更改,这就是据以行动的字段。 changed 区分一次写入与发现记录已正确的对齐:未更改的文件保持字节完全相同,因此持有该文档的客户端无需重新加载,两次运行该请求时第二次会报告没有更改。entity 指明文件,hostFunctions 携带推导出的集合,commands 以值的形式而非终端打印的行来携带镜像——每个条目包含 name、可选的 description 和 flags,每个标志携带其 name 以及可选的 shorthand、description、type 和 default。写入是原子的,因此在对齐运行期间读取该文件的客户端永远不会看到不完整的文档。

生成恰好只填充其应答的一半,而应答自身的 dryRun 说明是哪一半。 默认情况下实体会被写入,notices 携带生成过程对其所执行写入的说明。在 dryRun 下不创建或修改任何内容:documents 以其对应的 path 及其 content 携带每个生成的实体,以便客户端将它们放入自己的文档模型,在保存之前可见,并可修改或丢弃。两半从不同时被填充,因此执行的是哪种交付方式可以从响应中读出,而不必依据请求的内容。

插件请求写入的位置始终在该请求所指明的工作区内;它读取的位置则按字段决定。 绝对目标路径、向上越出根目录的路径,以及经由链接通向根目录之外的路径都会被拒绝而不会被解析——因此无论发送什么,生成都无法在会话从未打开的目录树中创建实体。请求仅读取的路径是另一个问题,逐字段回答,而非由一条规则统管:aggrega/pluginGenCatalog 从你选择的任意位置读取模块及其覆盖层,因为你构建的模块位于工具链的输出目录下,拒绝在那里读取就等于拒绝了该操作的全部目的。aggrega/pluginSync 在工作区内读取它的两个路径,因为该请求针对的是工作区已有的文件。上文的定位请求接受绝对路径则又是出于另一个原因——那是客户端已打开的文档,以其持有的任意写法命名。

缺少操作所需内容的请求会被拒绝,并指明应发送的字段。 缺少 type 或 query 的添加或移除;缺少 capability 的 provider 添加,或缺少 role 的 governance 添加;缺少 acceptCapabilities 的 cli 添加;缺少 entity 或 plugin 的对齐;同时指定两种选择模式或均未指定,或缺少 overlay 或 outputDir 的生成。每种情况都返回标准的 invalid-params 代码,在请求改变之前重试不会有任何变化。查询未匹配任何条目的移除也会被拒绝,并指明类型、查询及其查找的文件——这种情况是配置的状态而非请求的状态,因此需要更正的可能是二者之一。

不会提示任何内容,原本需要询问用户的那一项决定改为以字段形式提供。 终端命令会询问正在观看的人是否接受命令扩展插件声明的能力。而这个流没有人在观看,因此 acceptCapabilities 需要由调用方获取并发送;未携带它的请求会被拒绝并指明应发送的内容,而不会基于无人给出的同意进行安装。启动时不具备安装命令扩展手段的守护进程会直接拒绝 cli 添加,而不是报告一次什么都没安装的成功。

可以向作者提供哪些种类

不带 kind 的 aggrega/getSchema 会回答你可以指定哪些种类,并且它以两种宽度作答,因为客户端在不同的工作中需要不同的宽度。请读取你所询问的那一种。

**kinds 是该二进制文件能够响应的每一个标记。entityKinds 是作者会为其编写文档的集合。**宽列表除了你编写的种类之外,还包含中间表示、lockfile、工作区配置和插件套接字契约——它们每一个都是真实的 schema,但没有人会为它们编写文件。因此,宽列表用于配置编辑器的 schema 关联,窄列表用于构建选择器。用宽列表构建的选择器会提供任何编写 schema 都不接受的值,而作者只有在选中其中一个之后才会遇到拒绝。

**窄集合也比实体种类更窄,而且没有任何 schema 会告诉你是哪些。**一个由平台拥有、其内容写在另一种类文档内部的种类,不是可以提供给作者从头开始编写的文档。Workload 就是这样的种类:workload 内容写在 Recipe 或 FeatureRecipe 的 workload: 字段中,可以内联,也可以来自该字段导入的文件,因此不存在可以单独寻址的 workload 文档——该内容应写在何处,请参阅 Workload 编写界面。它的 schema 与编写种类的 schema 一样固定了 apiVersion 和 kind,因为正是这一点让内容能在其所在位置被校验;这些固定值标识该内容,但并不使其可寻址。因此,它们并不表示某个种类可以起草。答案由 entityKinds 给出,schema 字节中没有任何内容给出答案。

每个 entityKinds 条目都带有客户端所需的两种写法,且二者无法互相推导。kind 是小写连字符形式的标记——将它作为 kind 发回给本方法或 aggrega/scaffoldEntity。documentKind 是文档本身在其顶层 kind: 字段中携带的值。对于名称由多个单词组成的种类,两者的差异不止于大小写:无论你对 featurerecipe 做什么处理,都得不到 FeatureRecipe。从条目中分别取用二者,而不是由一个推导另一个,这样客户端就无需维护任何映射。

每个条目还说明哪些操作接受该种类的文档,因此在文档上提供这些操作的控件只会提供不会因其种类而拒绝它的操作。acceptedBy 带有三个布尔值,每个条目上都会出现,每一个都针对单独指定的该种类文档——通过其路径,或在查看时通过其名称——且不附带其他任何内容。singleEntityValidation 表示 aggrega validate <path> 是否检查该种类的文档,而不是拒绝它并指出改为检查它的整个目录或 Release 范围。publication 表示仅指定该文档的 aggrega/publishEntity 是否会发布它:Plugin 为 false,因为其发布还会绑定请求在 plugin 中指定的可执行文件,所以只指定文档的请求会被拒绝;Manifest 和 Release 为 false,因为这两个种类都不会被发布。inspectionByName 表示 aggrega/entityDefinition 是否将名称解析为该种类的实体,名称按一个实体引用另一个实体时的写法发送——Plugin 写作 <pluginType>/<name>,Recipe 或 FeatureRecipe 写作 <capability>/<name>,或者在只有一个 capability 声明该名称时仅写其名称。true 表示该操作不会因文档属于该种类而拒绝它;它仍可能因某个具体文档的内容而拒绝该文档。

**不要自己维护列表。**存在哪些种类是你所对话的二进制文件的属性,因此写进客户端的列表在编写当天是一致的,而在新增种类的那天就不再一致——届时作者看到的是,本应提供其种类的那个控件中恰恰缺少了它。去询问,答案就会跟随二进制文件。

**两部分会一起返回,且仅在你不指定种类时返回。**指定了种类的请求会以该种类的 schema 作答,不带任何列表,因此从响应即可看出你问的是哪个问题。没有 schema 对应的标记会以标准的 invalid-params 代码被拒绝,消息中附带完整的有效集合,因此拼写错误是一个需要更正的请求,而不是需要去问人的事情。

**它在空无一物的工作区中也会作答。**词汇表已编译进二进制文件,因此这不需要任何文档、lockfile 或目录——而这正是作者开始编写第一个文档时所处的工作区。

脚手架响应提供什么

本节讨论的是起草。该方法的另一种形式会写入一个可运行示例,其回答已在上文该方法处说明。

aggrega/scaffoldEntity 返回的是文本。skeleton 是你所指定种类的 YAML:包含该种类 schema 要求的每个字段,顺序与 schema 声明的顺序一致。schema 固定为单一值的字段会直接填好(你会注意到的是 apiVersion 和 kind),metadata.name 填入你发送的 name,其余每个必需值都以占位符形式出现,其类型与 schema 在该处的声明一致:空字符串、零、false、空列表、空映射。kind 重复该文档所派生自的 token,因此同时有多个未完成请求的客户端可以直接根据响应本身判断它对应哪个请求,而无需自行维护关联。

它不写入任何内容,而这正是设计时需要考虑的部分。 该方法不创建文件、不选择路径,也不触碰任何目录。你收到的是一份待写入的文档,而不是一份已写入的文档。因此编辑器应将文本放入一个新的未保存缓冲区,作者可以阅读、编辑或丢弃它,而新文件写入磁盘的时机仍由缓冲区和撤销历史所在的一方掌握。没有其他请求会接收这份文档并代你放到某处;决定新文档存放在哪里是编辑器的事。

它不解析任何内容,也不需要工作区提供任何东西。 文档派生自二进制文件自带的 schema,因此该方法不访问任何 registry 或网络,不查询任何 catalog,也不读取任何文件。它在每个工作区中的回答都相同,包括尚无任何 Aggrega 文档的空目录,而这正是作者开始编写第一份文档时所处的工作区,此处的大多数其他方法都会先要求有一份文档或一个 lockfile。

同一请求无论在哪里发出,都给出相同的字节。 文档由一次计算生成,该计算与提供此功能的其他界面共享,因此对于相同的种类和相同的名称,编辑器和助手向作者展示的起始文本相同。

骨架包含其种类要求的字段,但它不是一份完成的文档。 它只包含必需字段:你需要的可选字段要自己添加,每个占位符都是一个尚待填写的值。先填写占位符,然后对缓冲区运行 aggrega/validate。对于 aggrega validate 作为单个实体检查的种类的 catalog 实体,该方法会列出每个尚待填写的占位符,每个都标注在其键处并说明它需要什么,所依据的解读与该命令应用于已保存文件的解读相同,其中也包括 schema 允许为空的占位符,你会遇到的是草拟的 Recipe 或 FeatureRecipe 的 capability 和 implements。对于其他任何种类,它按该种类的 schema 检查缓冲区,因此 schema 不允许为空的占位符(例如版本)会作为该 schema 的发现返回,而 schema 允许为空的占位符则不会产生任何发现。实时验证描述了每个占位符以何种条目出现。

导入响应告诉你什么

aggrega/import 将为其他工具编写的源转换为 Aggrega 文档草稿,并且会写入它们——这与上文只交回文本的脚手架不同。written 列出每个已写入磁盘的文件,路径相对于 outputDir;files 携带请求写入的每个文件及其 content,无论是否已写入——先是导入器生成的每份草稿,然后是导入所写内容的记录,或在 sync 下是同步所做的更改。两者回答不同的问题,因此请读取与你的问题对应的那个:现在磁盘上有什么,还是生成了什么。

草稿的位置由你选择,或交由工作区根目录决定。 outputDir 是可选的,正如 aggrega import --output-dir 以及助手的 import 工具的 output_dir 一样:未指定目录的请求在工作区根目录下生成草稿——即 aggrega import 未给定目标时写入的位置,无论它在何处运行——指定了目录的请求则在该目录中生成草稿。指定的目录是工作区内的路径,相对值相对于工作区根目录解析,而不是相对于守护进程恰好所在的目录。你转换的 source 是另一种情况,不受此限制:该文件或目录是你选择的,因此会在其所在位置读取,而在那里读取它并不会改变草稿的落点。目录不存在时会被创建。在 dryRun 下不写入任何内容,每份草稿仍会给出其对应的路径,相对于响应中给出的 outputDir——即你发送的目录,或工作区根目录。

请求绝不会覆盖 outputDir 中已有的 Aggregate。 Aggregate 是作者在草稿生成后会持续编辑的文档,因此若请求的某份草稿会落在一个被识别为 Aggregate 的文件上,该请求会被拒绝,并指出该草稿以及该 Aggregate 所在位置,且完全不写入任何内容——在 dryRun 下同样如此,因为试运行会拒绝写入所拒绝的内容。请改为发送 sync 使其与源保持同步,或指定另一个 outputDir 在其旁边生成草稿。草稿路径上已有的其他文件都会被覆盖,而先前导入生成但本次未生成的文件会原样保留。每个生成了任何草稿的请求还会在 outputDir 中写入 .aggrega-import.json,即导入所写内容的记录——请求所发送的 target(若发送了的话)、导入所读取的目录快照(若读取了的话),以及每个草稿文件;在草稿 Aggregate 或 Release 中,还记录每一层级的每个键及其所写文本的摘要,其他草稿文件则整体记录——files 和 written 在草稿之后携带它。它是 JSON,因此读取工作区 YAML 文档的任何程序都不会读取它;sync 与 aggrega import --sync 一样,读取它以使草稿与其源保持同步。未发送 target 的 sync 会为记录中指定的目标生成草稿,因此会生成先前导入所生成的 Manifest;发送了 target 的则为该目标生成草稿,记录随后会指定它。目录中没有任何 Recipe 绑定的已记录目标,会像发送的目标一样被拒绝,拒绝信息会说明该目标是记录中的目标。由于草稿 Release 是逐键记录的,作者在导入为其留下注释之处写入的环境属于作者写入的键,同步会逐字节保留它。

发送 sync 可使先前导入在 outputDir 中生成的草稿与源保持同步,且只更改导入所写的内容。每个部分从三个方面判断——记录中导入上次在该处写入了什么、磁盘上有什么、以及源现在生成了什么。源保持为导入上次所写状态的部分,会完全按磁盘上的样子保留,无论作者是否编辑过它。源更改了的部分会被重新写入,源删除了的部分会被移除——草稿文件则整体删除——源新增的部分会添加到草稿中其周围部分的旁边;以上每种操作都仅在磁盘上的内容就是导入上次所写内容、且不含作者添加的任何内容时进行。其他一切都逐字节保留:作者在任何位置添加的键——参数、Feature(包括草稿 Component 实例之下的)、另一个 Component——不直接位于草稿键上方的注释,以及记录未列出的每个文件。对一个既没有记录、草稿路径上也没有任何文件的目录执行同步,会写入完整草稿,与不带 sync 的请求相同。

drift 是同步所更新的内容,也是对“源是否已变化”的回答。 它列出同步更改的每个部分——或在 dryRun 下列出将要更改的每个部分——按草稿中的顺序排列,每项包括 change(added、removed 或 changed)、file(所在的草稿文件,相对于 outputDir)以及 key(在草稿 Aggregate 或 Release 中通向该部分的键,以列表形式给出,因此含句点的键仍是一个条目);当该部分是整个文件时 key 为空,同步删除的草稿文件即以此方式表示。aggrega import 在标准错误上以 <change> <key> in <file> 或 <change> <file> 的形式打印相同的条目,其在 --sync --dry-run 下的退出状态表明源是否发生漂移;此接口没有退出状态,因此请发送带 dryRun 的 sync,并查看 drift 是否为空。对于非同步请求、与源一致的同步,以及导入器未能完成的同步,drift 都是空列表。在 sync 下,files 携带同步更改的每个草稿文件及其新内容,若记录也有更改则随后附上记录,written 列出已写入磁盘的那些——因此一致的同步对两者都返回空列表。同步删除的草稿文件只在 drift 中给出,不出现在这两个列表中:其带空 key 的 removed 条目是响应对它的唯一说明,在 dryRun 下则指出写入时将删除的文件。

同步绝不会改写作者所写的内容,而是拒绝执行。 若同步会更改或移除作者编辑过的部分、在作者已写入的位置添加部分,或移除包含作者所添加内容的部分,则会被拒绝,并逐行指出每个这样的部分及原因,措辞与 aggrega import --sync 相同——<file> <key>: <why>,整个文件则为 <file>: <why>——且不写入任何内容;直接写在草稿键上方的注释视为编辑了该键。对记录未列出的 Aggregate 执行同步会被拒绝,并指出该 Aggregate 和记录;记录无法读取的同步同样如此,因为没有记录就无法将其各部分与作者的内容区分开。这两种拒绝都以 invalid-params 错误返回,在 dryRun 下同样如此,并指明 sync。请手动协调每个被指出的部分,或恢复导入在该处所写的内容,然后再次发送请求。

🔴 halted: true 不是错误,把它当作错误处理正是设计时需要避免的错误。 未能转换全部内容的导入器仍会为其能转换的部分生成草稿:响应携带这些草稿,written 列出它们,diagnostics 说明遗漏了什么。这是该操作所能给出的最有用的回答,它以结果而非失败的形式返回,正是为了让你能向作者展示这两部分。在 sync 下,同样的回答不写入任何内容——files、written 和 drift 都为空——因为部分草稿会被视为源删除了导入器未处理到的所有部分。导入器完全无法读取的源属于另一种情况,确实会以错误返回。

每条诊断都带有 severity 和 message,在导入器指定了 code 时还带有该字段。 若要对某个特定情况作出响应,请根据 code 进行分支,并向读者显示 message;severity 取自每个插件套接字报告时所用的同一组值——halt、warn、info——因此 halted 是对这些条目的汇总,而不是一个单独的判断。files、written、drift、diagnostics 和 decisions 始终是数组,为空时是空数组而不会缺失。

**decisions 说明导入在哪些地方做了推测。**导入器每映射一个源节点,它就携带一个条目,按导入器的顺序,且完全按导入器报告的内容:sourceNode,即该节点的 id、type 和 paramsSummary;candidates,即导入器为该节点权衡过的每个目录 Component,以 componentName、score、tier 和 signals 表示——后者是其每个信号的贡献,分列于 table、category、domainLabels、shape 和 name 之下;chosen,即它选定的 target、写入时采用的 mode——指向现有 Component 的 reference 或一个 draft——以及该选择的 tier;rationale,即原因;以及 swapHint,即如何做出不同的选择。导入器未权衡任何候选时不出现 candidates,未做选择时不出现 chosen,未写出时不出现 rationale 和 swapHint。每个值都来自导入器自身——如何为候选打分、各层级如何划分都是它的选择——因此应把一个条目展示为它对映射的说明,而不是定论。无论在 dryRun 下还是 halted 为 true 时,这些决策都会返回:部分导入的推测正是审阅它的作者所需要的,而不报告任何决策的导入器返回空列表。如果以文本形式展示,aggrega import 已将一条决策表述为 mapped <node id> (<node type>) to <target> as a <mode>, <tier> at <score>,其中分数取最佳候选的分数。

除非你指定格式,否则格式会从源中识别。 识别使用各导入器声明的签名(无论是工作区目录中的导入器,还是编译器的核心导入器),这些签名记录在每个导入器的 Plugin 实体中:读取源所用的语法、签名适用的文件名,以及解析后的树必须或不得包含的路径。因此守护进程本身不了解任何格式,新导入器的格式无需其他任何改动即可被识别。检测只读取你发送的源——对于目录,只读取签名的文件模式所选中的文件——不访问网络;它读取的每个文件,都通过工作区目录为相应语法提供的解析器来解析(若目录未为某种语法提供解析器,则使用编译器自带的解析器),对适用于该文件名的签名所采用的每种语法各解析一次;随后导入器通过同一解析器读取源。未声明文件模式的签名适用于你发送的单个文件(无论其名称为何),而不适用于目录中的任何文件;Langflow、Flowise 和 n8n 导入器的签名属于此类,读取 JSON,而 Dify 导入器的签名读取 YAML。因此,识别你单独发送的文件时,会将其分别按 JSON 和 YAML 读取,这无需工作区目录中有解析器:编译器自带 JSON 和 YAML 解析器,目录提供的解析器则会取而代之。没有任何签名匹配的源会被拒绝,并要求提供 format,同时列出各导入器声明的格式——对于目录,则改为要求单独发送其中的某个文件,或提供其导入器声明了文件模式的 format,且只列出这些格式——所属条件为 No importer recognises the source(没有导入器能识别该源);被多种格式的签名匹配的源会被拒绝并列出这些格式,所属条件为 More than one importer recognises the source(有多个导入器能识别该源)。每次拒绝的 data 都带有其条件的 code 和 shortCode,因此客户端应依据代码而非文字来请求格式。这两种情况都不会去猜测,因为猜错的格式会解析到错误的导入器,产生看似可信的无意义结果。响应中的 format 是实际使用的格式(无论是检测到的还是指定的),因此省略了它的客户端也能得知所用格式。

你发送的目录会被读取为其导入器所指定的文件,无法读取的目录则返回错误。 当 source 指向一个目录时,交给导入器的是该目录中被其签名所声明的文件模式选中的文件(工作区的构建输出文件夹 dist/ 除外),每个文件以其在目录内的路径命名,按排序顺序排列,与其 plugins.importer 条目在 with.sources 下指定的文件并列。以下情况都会返回带有相应条件代码的错误,且不写入任何内容:导入器未声明任何文件模式;目录中没有被这些模式选中的文件;目录中的文件与 with.sources 中的文件同名;导入将读取的文件中存在通向目录之外的链接,或存在指向目录的链接。

运行哪个导入器由工作区决定,而不由请求决定。 格式会解析到在工作区的目录插件和编译器的核心导入器中声明了该格式的导入器;若工作区配置中有 plugins.importer 条目附加了其中一个,则解析到它附加的那个。因此请求无法选择某个模块,也无法指向磁盘上的模块。没有导入器声明的格式会被拒绝并给出该格式名;由两个导入器声明且两者都未被附加的格式(包括一个核心导入器与目录中为同一格式提供的另一名称的导入器)会被视为有歧义而拒绝,而不会被随意解析。

**本机尚未持有的核心导入器,会由第一个需要它的导入获取一次。**它来自工作区的默认注册表,限定为编译器的发布版本所发布的模块,并按 pull 验证其获取的插件的方式进行验证——依据该注册表的信任策略验证其签名,并检查它使用的宿主函数——然后保存在工作区的内容缓存中,这是为它写入的唯一内容:不写 lockfile,也不写受信任插件的记录。之后的每次导入都从那里读取它,不访问任何注册表。未通过验证的模块是一个携带其条件代码的错误,且不会保存任何内容;无法获取的模块——工作区处于离线状态、无法访问其注册表,或注册表中没有它——是 A plugin’s .wasm is not on this machine(插件的 wasm 文件不在本机上) 下的错误,会指明该导入器、其版本,以及如何将其模块放到本机上。请求本身不指定注册表,而所需的每个导入器以及它所读取的目录都已在本机上的导入完全不访问网络。

当工作区未指定任何目录文件夹时,导入会读取其默认注册表所发布的目录。 如果工作区的 workspace.catalog_dirs、AGGREGA_CATALOG_DIRS 和根目录都未指定目录文件夹,该工作区会将标准库目录作为单个已签名快照读取,该快照位于其默认注册表上的 catalog/snapshot。快照只获取一次:依据该注册表的信任策略验证其签名,然后将其保存在工作区的内容缓存中,并在那里作为目录文件夹读取,限定于其摘要,不会再向任何注册表请求它。请求读取哪个快照:带 upgrade 时,读取最新的;否则读取 outputDir 中的记录所指定的快照,本机未持有时按其摘要获取;否则读取工作区上一次作为最新快照获取的那个;否则读取最新的。导入写入的记录会按摘要指明它所读取的快照,因此之后向同一 outputDir 发出的请求会读取同一目录。在离线模式下,需要获取快照的请求是 The workspace is offline and the step needs the network(工作区处于离线状态,而该步骤需要网络) 下的错误,会指明应运行什么;而无论本机持有什么,upgrade 都会被拒绝,因为只有注册表才能说明哪个快照是最新的。不发布任何快照的注册表会使导入没有目录可用,diagnostics 中的一条 warn 条目会说明这一点。指定了目录文件夹的工作区会以该文件夹为依据进行导入,不获取任何快照,upgrade 在那里也不会改变任何内容。

在 dryRun 下不会创建任何内容。 written 为空,files 带有与写入时相同的文件(若带 sync,则是同步将写入的文件,以及它将更新的 drift),也不会创建目录,因此编辑器可以把这些文件呈现给作者,由其保存、修改或丢弃。写入所做的其他一切都会照做:同一导入器在同一源上运行并报告相同的诊断,因此写入时会被拒绝的源在这里同样会被拒绝。在 dryRun 下获取的核心导入器或目录快照会像写入时一样保存在内容缓存中,因为获取导入运行所依赖的内容属于运行导入的一部分,而不属于放置草稿。

导入器返回的路径必须位于 outputDir 之内。 草稿的路径来自导入器而不是你,因此越出输出目录的路径会被拒绝,并且完全不写入任何内容——即使是路径正常的草稿也不写入。拒绝信息会指出有问题的路径,由此可知需要修正的是导入器,而不是你的请求。

每个实体请求回答哪个问题

这里有四个请求可以告诉你某个实体的信息,它们不可互换。在它们之间选择,取决于你提问时手里握着的是什么。

你握着一个光标。aggrega/hover 和 aggrega/resolve 接受一个文件和一个位置,并根据该处所写的内容推断所指的是哪个实体。它们覆盖文档中实际出现的引用形式:extends 值、component 或 feature 类型、Recipe 的 implements、Manifest 的 recipe 引用、Release 的两个路径指针、uses 目标,以及实体自身的 metadata.name。当用户的光标就是坐标时使用它们:用户正在阅读文档,想知道某个引用指向什么。

你握着一个名称。aggrega/entityDefinition 直接接受标识。无需打开任何文件,不涉及位置,实体也不必在客户端能找到的任何地方被提及。当用户输入了一个名称、从列表中选了一个,或沿着你的客户端已知其标识的某个对象操作时使用它:hover 需要你先找到写有该名称的地方,而这项工作你本不必做。

你还什么都没握着。aggrega/catalogIndex 列举工作区所持有的内容,并附带每个实体的描述性字段。用它填充选择器,然后把选中的名称传给 aggrega/entityDefinition。

你握着一个 Release。aggrega/releaseClosure 回答的是关于一个 Release 而非单个实体的问题,见下一节。

按名称请求返回的定义是解析后的实体,而非任何单个文件所声明的样子。扩展了某个基础的 Component 或 Feature 返回时会携带该基础的契约,而这在声明其名称的文档中并不出现,因此该回答描述的是实体本身是什么,自己读文件得不到同样的内容。

它以 YAML 文档的形式返回,而非响应中的结构,这是有意为之:schema 支柱有多种编写形式——直接写出的内容、对共享文档的引用,或表示内容来自基础的标记——文档会按作者自己的键顺序重现解析所得的那一种。如需其字段,请将其作为文档解析;如果要放进面板展示,按原样显示即可。

区分两种按名称请求的拒绝

解析不到任何内容的名称会被拒绝,而不是返回空文档,因为空回答会把拼写错误报告成一个无可描述的实体。名称解析不到内容有两种情况,它们要求读者做不同的事,你要根据错误的 data 携带了什么来区分,而不是阅读消息:

  • **data 中没有 file。**工作区中没有任何内容声明该名称,也没有任何目录层级能解析它。这几乎总是请求需要更正——拼写错误,或者名称来自本工作区搜索路径上没有的目录。
  • **data 中有 file。**某个工作区文档确实声明了该名称,但目录仍未为它解析出任何内容。实体已被写下,却有某处拒绝了它,这是需要人来修复的工作区状态。若恰好有一个被目录读取并拒绝的文档声明了该名称(通常的原因),消息会以该拒绝开头,只陈述一次:其类别和短代码、按报告路径给出的文档,以及它的问题所在,例如所在行和违反的约束;然后说明该文件在加载时被跳过,并列出加载拒绝的其他文件。否则,消息会指出声明该名称的文档,列出加载拒绝的文件,并说明本工作区从何处读取本地实体以及要改什么才能读到该文档——当被拒绝的文档声明了该名称时则省略这部分说明,因为该文档已位于目录读取的位置。

两者都携带 entity-not-resolvable 代码,因此应根据 file 是否存在来分支,而不是根据代码。

查询坐标

**你握着一个 registry 引用。**将它作为 aggrega/entityDefinition 的 name 发送,回答即为在该坐标发布的实体,其结果形式与名称请求相同,另加 published,内容取自所发布的内容,而非目录所解析的内容:

  • definition 是与发布时完全一致的实体文档。若坐标的实体发布时附带了其声明的文件,则该坐标携带一个归档,文档从中解包;若实体未声明文件,则坐标原样携带其文档;Plugin 的实体从其 manifest 读取,而非从与之一同发布的可执行文件读取。不应用任何继承。
  • authoredLength 是该文档的长度,因为这里的定义是编写的文档,而非解析后文档的渲染。
  • file 为空,因为从 registry 读取的实体在本机上没有可指明的文档。
  • publishScope 被省略:你已持有坐标,即实体的发布位置。
  • published 是所读取的内容,它出现在此回答中,而不出现在任何按名称请求的回答中:reference;archive,表示其字节是否为解包出文档的归档——坐标本身持有文档时为 false;manifest 声明的 mediaType;以及该 manifest 的 manifestDigest,你可以将其放在 @ 之后代替标签发送,以再次精确读取相同的字节。

该请求会访问引用所指的 registry,使用本守护进程运行用户的凭据和本工作区的网络策略,因此离线工作区会拒绝它。获取的字节只与制品自身 manifest 为其记录的摘要进行校验,不做其他校验——不验证签名,也不报告撤回——且不写入任何内容。无法读取的引用会以 entity-not-resolvable 被拒绝,消息以说明原因的条件短代码开头——与 aggrega inspect 报告的条件相同——并以应对方法结尾。未指明仓库,或既无标签也无摘要的引用属于格式错误的请求,会以 invalid params 被拒绝。

闭包不是图

aggrega/irGraph 和 aggrega/releaseClosure 派生自同一 Release 的同一次解析,但回答的是不同的问题。已经在接收图的客户端可能会合理地以为自己也拿到了闭包,但事实并非如此。

图说明 Release 部署了什么——它的节点、节点所处的边界、哪些部分相互连接,以及每个节点携带的值和附件。它是一幅图景。

闭包说明为构建部署引入了什么,以及引入的是哪些版本。 包括该 Release 触及的每个实体,无论它是否成为节点;这些实体所引用的共享文档;以及塑造输出的插件。它是一份物料清单。

两者都无法从对方还原。一个实体可以被触及却从不作为节点出现——Manifest 将某个 component 类型映射到的 Recipe 会被每次构建触及,却不是其中任何一次构建的节点——而节点也不携带其类型解析到的版本。因此,读者若问“为什么这个版本变了?”、“修改这个共享文档会影响什么?”或“这个 Release 实际依赖什么?”,需要的是闭包;读者若问“这个 Release 部署了什么?”,需要的是图。

闭包请求不做什么。 它不渲染任何内容,也不发布它找到的任何内容。尤其是,它不会发出漂移警告或渲染建议:这些属于请求它们的那个请求,而发布会替换整个诊断层,因此一个会发布的列表会抹去图请求已经展示给用户的内容。需要漂移判定时,请请求图。它唯一会发布的内容并非它自己的发现:无论是哪个请求,只要发现 lockfile 已不存在,就会撤回基于该 lockfile 的漂移警告——参见 Lockfile 感知。

与图一样,它需要 lockfile。 列表报告的版本是该 Release 所解析到的版本,而一个无人准备过的工作区尚未解析它们。没有 lockfile 时生成的列表会报告目录当前恰好包含的内容,这与该 Release 依赖什么是不同的问题。拒绝信息会指出 lockfile 和 Release,因此客户端可以直接提供 aggrega pull --release <release>。

闭包条目上的 kind 仅在已知时出现。 引用是从文档中的某个位置收集的,有些位置说明了所指向的 kind,有些则没有。该字段在引用位置记录了 kind 时报告,未记录时省略,而不是根据名称的形式猜测。它以作者在文档开头写的那个词报告,这也是每个报告闭包的界面对同一条目所使用的词。

在其他地方,同样的词请求同样的文档。 aggrega inspect <release> --closure 在命令行中回答这个问题,describe 工具的 release 模式则通过助手工具协议回答它。三者对该 Release 运行同一次解析,因此它们不会在 Release 依赖什么的问题上出现分歧。参见 aggrega inspect “The dependency closure”。

缓存模型

各项操作由缓存驱动:对某个文件调用 hover / completion / resolve / diagnostics 之前,先对该文件调用 aggrega/validate。这次预热调用不需要 Release——未指定 Release 的验证仍会解析缓冲区并填充缓存——因此这些操作在没有可指定 Release 的工作区中也能使用。每次读取时,解析缓存都会与每个文件在磁盘上的修改时间进行比对,因此外部编辑(编辑器保存、git checkout)会被自动识别——编辑器发送的 aggrega/invalidate 只是一种优化,而不是保证正确性的必要条件。

缓存属于对其进行预热的工作区。 在某个工作区下验证的文件只为该工作区缓存,因此在另一个工作区下询问同一路径时,会报告为尚未验证,而不会用第一个工作区的条目作答。正是这一点使得针对第二个工作区的询问既不会给出错误答案,也不会让第一个工作区失去其热状态——同样,aggrega/invalidate 也只清除它所指定的工作区。

在验证运行期间请求诊断

一次验证会为文件预热两样东西——交给其他操作使用的解析结果,以及它报告的检查结果——而这两者的预热时间相隔片刻。 aggrega/diagnostics 是唯一同时读取两者的请求:它需要解析结果来确认该文件是它能够作答的文件,并根据检查结果作答。因此,在这两个时刻之间到达的请求,会在尚无可用于作答的内容时就判定自己可以作答。

因此它会等待。 对一个正在验证的文件发送 aggrega/diagnostics,回复会在该验证完成时到达,并携带验证发现的结果。无论时序如何,该文件只有一个正确答案,你得到的就是这个答案——对于验证即将报告错误的文件,它绝不会返回空列表;这正是客户端无法从中恢复的那种错误答案,因为对于一个已被告知没有问题的文件,没有任何东西会提示你再次询问。其他基于位置的操作——hover、completion、resolve、findReferences、findImplementations——读取解析结果并据此作答,因此它们无需等待,也从不等待。

有两种方式可以提前结束等待,而且两者你都已具备。 针对该请求 id 发送的 $/cancelRequest 会停止它,协作式的 aggrega/shutdown 也会停止它。两者都不需要在请求上附加任何额外内容。

而且等待是有上限的。 如果验证未能在守护进程为其设定的时间预算内完成,请求会以“验证进行中”错误码被拒绝,而不是返回空答案——参见错误码。这种拒绝意味着你所等待的工作确实正在进行,因此应稍后再次询问;它并不是让你再发送一次验证的信号,那样只会增加工作量而得不到任何答案。

逐个运行请求的守护进程按到达顺序作答,因此不会有重叠,也从不发生等待。并发运行请求的守护进程以同样的方式回答同样的问题,而正是等待保证了这一点:你得到的答案就是串行顺序会给出的答案。

应答中的大小

报告字节量的应答会报告两次:一次是数值,一次是写成文字的同一数量。 文字字段的名称是数值字段的名称后加 Text——size 与 sizeText、totalSize 与 totalSizeText、reclaimedBytes 与 reclaimedBytesText,以此类推, 适用于每个携带大小的应答。

显示文字形式,用数值计算。同时发送两者的目的在于,客户端永远不必自己书写大小:守护进程使用与命令行相同的格式化器书写它, 因此 aggrega cache status 和 aggrega/cacheStatus 对同一缓存的显示完全一致,连舍入也相同。 自行拼写文字的客户端,一旦在某个边界上意见不一,就会与之产生偏差。

文字形式使用二进制单位——512 B、1.0 KiB、5.0 MiB、3.0 GiB——这与 aggrega/cacheEvict 在 maxSize 中接受的写法相同,因此从一个应答中读出的大小无需改写即可在下一个请求中发回。 大于字节时,文字保留一位小数,因此它以读者希望看到的方式表述数量,而不是精确到字节; 需要精确计数时,请使用数值字段。

数值可选时,文字也随之可选,且两者绝不会只出现一个: 发布应答中的插件大小要么同时携带 pluginSize 和 pluginSizeText,要么两者都不携带。

每个请求都指明其所涉及的工作区

在每个请求上发送 workspaceRoot:即该请求所作用的工作区根的绝对路径。 守护进程自身不持有任何工作区,也不会在请求之间记住任何工作区,因此一个请求得到的回答只关于它所指明的工作区,别无其他。指明两个工作区的两个请求得到两个回答,彼此都看不到对方的实体、Releases、缓存的解析结果或诊断。

未指明工作区的请求会被拒绝,返回标准的 invalid-params 错误,并指出该参数;空值同样会被拒绝,它没有声明任何工作区,会被当作缺失的工作区作答。另外两种形式也因同样的原因被拒绝,每种都会在消息中指出:相对路径,因为工作区根没有可以相对的基准;以及不是已存在目录的路径,因为工作区是一棵目录树。

有三个请求不需要 workspaceRoot,原因都是其对象不是工作区。aggrega/getSchema 和 aggrega/scaffoldEntity 依据编译进正在运行的二进制文件中的 schema 作答,因此工作区对二者都没有任何贡献——正因如此,二者都能在一个无人准备过的目录中作答。aggrega/initialize 是第三个,它是你声明工作区的地方,而不是对工作区执行操作的地方。aggrega/scaffoldEntity 的另一种形式,即写入或列出文档中的可运行示例,确实会对工作区执行操作,对它的请求会像其他请求一样指明工作区。

每个工作区的缓存状态各自独立保存,指明第二个工作区不会给第一个带来任何代价。 一个工作区的目录索引、解析缓存和诊断都属于该工作区,因此关于别处提出的问题不会驱逐编辑器为某人打开的文件夹所积累的内容。同一个根的两种写法是同一个工作区,因此包含内部 . 或重复分隔符的路径,与其普通形式会命中同一个已预热的状态。

声明你希望为其推送诊断的工作区

诊断有两种传递方式:你主动请求,或由守护进程推送。守护进程只为你在握手时声明的工作区推送诊断。 其他每个请求都在自己的响应中给出其发现,不推送任何内容。

通过在 aggrega/initialize 上发送 workspaceRoot 来声明它。这就是该声明的全部作用——它不锚定任何东西,之后的请求也不会针对它作答。

限制推送范围的原因在于推送诊断的用途。推送是为了在有人输入时保持编辑器的问题列表为最新,而对一个无人要求查看的回答这样做恰恰是错误的:如果没有这条规则,关于第二个工作区提出的问题——比如由共享该守护进程的另一个工具提出——就会用读者从未打开过的文件的发现填满其问题列表。限制推送可以让一个调用方的问题不会进入另一个调用方的问题列表。

该字段是可选的,你用它可能表达的三种含义可以相互区分:

你发送的内容推送去向握手报告的内容
不发送进程启动时所基于的工作区该工作区
一个工作区根该工作区该工作区
空字符串无处——永远不推送任何诊断空的根

不发送任何内容时,推送仍针对进程启动时所在的工作区,因此不声明任何内容的客户端会收到该工作区的诊断。对于不是编辑器、也没有需要保持同步的问题列表的调用方,发送空字符串是如实的声明:每一项发现仍会送达它,体现在产生该发现的请求的响应中。

已声明的工作区与请求指明的工作区以完全相同的方式解析,因此指明相对路径或非目录路径的声明会在握手时被拒绝,而不会让推送指向某个意料之外的地方。

工作区根与活动 Release

守护进程解析请求所指明的每个工作区的方式,与每个 aggrega 命令解析工作区的方式相同,配置一文说明了哪些东西会锚定一个根以及按什么顺序。对客户端而言有两个重要后果。不含 workspace: 块的 .aggrega-config.yaml 不会锚定:它仍然贡献其设置,但单纯的设置文件不能把每个父目录都变成工作区根。而当没有任何东西锚定时,会使用工作目录——守护进程照常启动,操作只是什么都解析不到,而不是拒绝运行。

进程启动时也基于一个工作区,该工作区来自 --workspace-root,或从其工作目录向上查找得到。这次解析只做两件事,别无其他:它决定工作线程池的大小,这是进程的属性而非任何请求的属性;它也是推送诊断的默认声明。任何请求都不会针对它作答。

配置同样是每个命令都读取的那套层叠,配置一文对其进行了说明。守护进程额外做的只是:每个工作区对它的读取只进行一次,即在该工作区第一次被指明时,之后关于它的每个请求都复用这次读取。层叠会读取的配置文件如果是一个指向工作区之外的链接——工作区自身的 .aggrega-config.yaml,或其旁边由 CI 拥有的覆盖层——则不会被读取,这里与在终端中一样,而且该文件本会配置的其他任何内容也不会被别的东西代替读取。与终端不同的是仍然会作答的部分。基于这样的工作区启动的守护进程会启动,并在其错误流上说明一次;指明这样一个工作区的请求,无论哪种情况都按如下方式作答。aggrega/releaseCandidates 和 aggrega/catalogIndex——列出工作区所含内容的两个请求——会作答,读取时不带任何配置:列出工作区自身的文档,不读取任何目录(catalog)目录,并在 unreadLinkedFiles 中指出被搁置的文件,无论搜索是否遇到它。客户端正是通过这个名称得知工作区的配置指向了工作区之外。指明该工作区的其他每个请求——构建、图、验证、默认 Release、有效配置、写入,以及以某个 Release 为准的 aggrega/catalogIndex——都由该配置决定,因此会被拒绝,返回携带 E0321 的 invalid-params 错误——错误的 data 中为 read-leads-out-of-workspace——以及指出该链接及其指向位置的句子。对于这样的工作区,握手也会作答,并将其 configSource 报告为 defaults,因为没有任何配置文件为这些列表的回答贡献内容。移除该链接,或让它指向工作区内的文件,下一个请求就会读取配置。项目文件之下是全局层:启动守护进程的命令行上 --config 所指明的文件,适用于它服务的每个工作区;否则是设置了 AGGREGA_CONFIG 环境变量时它所指明的文件;再否则是默认位置——在 Windows 上为 APPDATA 环境变量所指明目录中的 aggrega\config.yaml,在其他系统上为 XDG_CONFIG_HOME 所指明目录中的 aggrega/config.yaml,回退为 ~/.config/aggrega/config.yaml——存在时加载。内置默认值位于其下。

作用于某个 Release 的操作将其作为参数接收;守护进程不会自行选择任何 Release。 工作区仍会声明它指向哪个 Release,并由一个四步层叠读取该声明:build.authoring_release 配置字段,然后是 .aggrega/active-release 标记文件,然后是“工作区中只有一个 Release”的启发式规则,最后是仅 Aggregate 的回退。因此你写入的标记优先于启发式规则,而指明一个无法加载的 Release 的标记会落到启发式规则,而不是回退。指明工作区之外 Release 的标记——通过绝对路径、通过向上越出根的路径,或通过指向根之外的链接——不会被读取,除非你的工作区配置将该 Release 指明为 build.authoring_release 或 workspace.releases 的某个键:配置是访问工作区之外 Release 的途径,标记则不是。此时层叠的后续处理与对无法加载的标记完全相同;当它最终什么都没选中时,trace 会在标记那一行说明原因,reason 则在其关于标记的句子中说明。

aggrega/activeRelease 报告该层叠的选择,它是给客户端的建议,而不是守护进程据以行动的设置。请询问守护进程,而不是自己读取层叠的输入:配置字段和标记文件只是四个输入中的两个,因此你读取的任何一个,只有恰好是胜出的那个输入时,才指明工作区的选择。指明无法加载的 Release 的标记是最清楚的例子——层叠会选择完全不同的 Release,而读取标记的人会报告那个加载失败的 Release。

层叠在你询问时才运行,不会提前运行,这带来两个值得依赖的后果。无论目录树多大,握手都保持快速,因为它不等待工作区遍历。而且回答会跟随工作区变化:写入一个标记——使用 aggrega/setActiveRelease,它会直接以新的选择作答——编辑配置、添加或删除一个 Release 文件,然后再次询问,就能从同一个守护进程得到新的回答。切换你所处理的 Release 从不需要重启守护进程——客户端在下一个请求中发送不同的 release 即可。

搜索整个工作区而非单个缓冲区的操作——completion、hover、resolve、findReferences 和 findImplementations——会枚举工作区根下的 YAML,这种枚举遵循 .gitignore。从工作区根到文件自身所在目录的每个 .gitignore 都会起作用,最近的那个优先,因此你的仓库忽略的 YAML 文件不会作为补全候选提供,也不会被报告为定义或引用。作为指向工作区之外链接的 .gitignore 不会被读取,因此机器上别处的文件永远不会决定搜索工作区中的哪些文档。因此,vendor 目录树和生成的输出无需维护任何单独的排除设置,就不会出现在跨文件结果中——而你期望被找到却已被忽略的文档不会出现,这是引用似乎缺失时值得检查的唯一情况。completion 还会从你配置的 catalog_dirs 中提供 Components 和 Features,这是另一种读取:它们按配置来自这些目录——与配置未给某个 Release 指定其自己的目录时构建该 Release 所读取的目录相同,或者对于指明某个 Release 的请求,是该 Release 自己的目录——因此无论 .gitignore 是否覆盖某个 catalog 目录,其中的实体都会被提供——但位于指向该 catalog 目录读取必须限定的目录之外的链接后面的实体除外,它不会被读取,也不会被提供。

命名了某个 Release 的请求会读取该 Release 的目录(catalog)目录,即在终端中构建它时读取的那些目录:如果工作区配置在 workspace.releases 下为它指定了目录,则读取它自己的目录,否则读取工作区的 catalog_dirs。这涵盖命名了某个 Release 的 aggrega/build、aggrega/buildPreview、aggrega/irGraph、aggrega/releaseClosure、aggrega/resolveDependencies、aggrega/validate 和 aggrega/lint,指向某个 Release 图中节点的 aggrega/attachCandidates 和 aggrega/attachmentContainer,以及 aggrega/connectionAtPosition,还有下一节列出的请求在命名了某个 Release 时的情形。因此,在为每个 Release 保留一个目录变体的工作区中,一个会话即可回答其中的每个 Release,每个都基于它自己的变体,除 Release 的路径外无需发送任何其他内容。不涉及单个 Release 的请求——aggrega/catalogIndex、aggrega/entityDefinition,未命名 Release 的 completion、hover 和 resolve,以及指向某个实体或某个标签集的 aggrega/attachCandidates——读取工作区的 catalog_dirs。在 workspace.releases 下命名了 Releases 的工作区中,既未命名实体也未命名 Release 的 aggrega/lint 是例外:此时它为每个 Release 检查一次整个目录,每一遍都基于该 Release 的目录,如按请求及每次编辑时发布约定所述。参见为 Release 指定其自己的目录目录。

以单个 Release 的视角作答

aggrega/catalogIndex、aggrega/entityDefinition 以及从光标出发的五个请求——aggrega/hover、aggrega/resolve、aggrega/completion、aggrega/findReferences 和 aggrega/findImplementations——不涉及单个 Release,它们各自接受一个可选的 release,使其涉及某个 Release。它是相对于工作区根目录的路径,遵循其他接受 Release 的请求所遵循的同一约束;若该值未指向任何 Release 文件,或指向一个目录,请求会被拒绝,而不会以工作区的视角作答却看似是该 Release 的答案。

对于此处的每个请求,一个 Release 可达的范围是:其栈读取的目录目录下的工作区文档,以及不在任何目录目录下的每个工作区文档——例如写在目录旁边的 Release、其 Aggregate 和其 Manifest。仅由其他 Releases 读取的目录目录下的工作区文档不属于它的答案:不会被列出、不会被解析、不会被提供。正是这一点使为不同 Releases 并排保留的同一实体的多个变体不会被混淆。

  • **列表。**指定某个 Release 时,列出该 Release 可见的实体。列出的 Features 是该 Release 的目录目录所声明的那些,而仅由其他 Releases 读取的目录目录下的工作区文档会被排除——因此,为每个 Release 保留同一实体一个变体的工作区,只列出该 Release 构建时使用的那个变体,而不是并排列出所有变体。不在任何目录目录下的文档,例如写在目录旁边的 Release、其 Aggregate 和其 Manifest,属于每个 Release 的列表。
  • **按名称查找。**指定某个 Release 时,名称通过该 Release 的目录目录解析,因此由多个变体声明的名称会解析为该 Release 构建时使用的变体。其目录无法解析的名称会被拒绝,并附带一段说明,指出该 Release 在 workspace.releases 下的条目,因为查找读取的正是该条目。注册表引用不接受 Release,带有 Release 时会被拒绝:无论指定哪个 Release,它都从发布它的注册表读取。
  • **悬停与转到定义。**指定某个 Release 时,光标处的引用首先通过该 Release 的目录目录解析,顺序为工作区配置给出的顺序——与以该 Release 视角按名称查找时执行的解析相同——因此显示的实体和打开的文档,就是这些目录将其解析到的变体,即使其他位置的工作区文档声明了同一名称。只有当这些目录下没有文档能对应它时,才会搜索该 Release 可达的工作区文档。未指定 Release 时,顺序相反:先搜索工作区文档,因此工作区文档能对应的引用保留该结果,只有在没有文档声明该名称时才会查询工作区自己的 catalog_dirs——这样才能找到只有某个已配置目录目录才包含的实体,包括位于工作区树之外的实体。如果编辑器持有某个 Release 的目录所解析到的文档的未保存副本,且该副本仍声明该名称,则从该副本读取答案,使位置落在编辑器所显示的行上。
  • **补全。**指定某个 Release 时,提供的名称是该 Release 可达的工作区文档所声明的名称,以及该 Release 的目录目录所声明的 Components 和 Features。
  • **引用与实现。**指定某个 Release 时,该 Release 不可达的工作区文档中的位置不会被报告,因此为另一个 Release 保留的变体绝不会被列为此 Release 的引用或实现。
  • **可附加到图节点的内容。**指向某个 Release 图中节点的 aggrega/attachCandidates 始终以该 Release 的视角作答——参见附加候选响应告诉你什么。

未指定 Release 时,依据工作区自己的目录目录作答,如上一段所述。

访问 registry 与写入

这里的大多数请求依据工作区和已缓存的内容作答,不写入任何内容。少数指定的请求做得更多, 它们沿两条相互独立的轴划分:请求访问什么,以及它所更改的内容影响 多远。

访问 registry 的请求分为读取类和发布类。aggrega/resolveDependencies 获取一个 Release 所需的内容;aggrega/build 在且仅在其 autoPull 字段要求先解析依赖时加入其中,此时它会访问 registry,并在渲染前写入 lockfile;aggrega/registryUpdate 遍历每个已配置的 registry 以重建本地搜索索引;aggrega/pluginAdd 在已配置的 registry 中搜索请求所指定的插件,并读取其已发布版本以固定其中一个;aggrega/registryAdd 向它所注册的 registry 请求该 registry 公布的信任策略,除非请求拒绝此次获取或自行提供策略,aggrega/configInit 也向它所初始化的 registry 请求同样的内容;aggrega/explainError 在本机所有项目共享的缓存中没有通过工作区自身签名检查的副本时,获取一次它用来读取某个条件讲解的文档包——参见 aggrega explain;aggrega/scaffoldEntity 在发送了 example 或 list 时,以同样的条件获取同一个文档包,写入时随后会将示例写入工作区中的一个新目录;aggrega/import 在本机尚未持有某个核心导入器时,从工作区的默认 registry 获取一次,并在未指定目录文件夹的工作区中获取它所读取的已发布目录快照——参见 import 响应告诉你什么;aggrega/entityDefinition 在其 name 为一个 registry 引用时读取该引用所指的实体,不写入任何内容。aggrega/publishEntity、aggrega/publishArtifact、aggrega/signArtifacts 和 aggrega/deprecateArtifact 向 registry 写入——字节、签名或撤回标记。请求只有在被要求这样做时才会访问 registry:列表报告配置所固定的内容,搜索读取离线快照,而带 dryRun 的发布只计算它将要发送的内容,不联系任何一方。

这条规则关乎操作何时运行,而非由哪个界面运行。 获取或写入的操作 之所以运行,是因为某个请求指定了它,而绝不会作为验证文档、检查图或列出工作区实体的副作用。因此,每次 按键都验证的编辑器不会访问网络,也不会重写 lockfile;而用户点击的“解析依赖”操作 所做的与 aggrega pull 完全相同——两个界面背后是同一套解析,写入 逐字节相同的 lockfile,并填充同一个制品缓存。

不会提示输入任何内容。 没有人在看这个流,因此身份从提供的 或环境中的凭据来源解析,绝不通过询问获得。凡是终端命令会向人提问的地方 ——需要凭据的 registry、由多个 provider 插件提供的能力、撤回要附带的文本——请求都会失败,并给出说明需要提供什么的消息, 而不是阻塞等待一个永远不会到来的答复。拒绝会让工作区保持原样:不写入 lockfile,不留下部分记录;无法解析凭据的发布会在任何字节到达 registry 之前拒绝。

有些更改会影响到本工作区之外,响应会说明是哪些

请求只指定一个工作区,因此一个对自身影响范围只字未提的响应会被理解为 只涉及该工作区。对其中若干请求而言,这种理解是错误的,因此每个请求都 携带其作用范围,客户端应在依据结果行动之前展示它。

发布、签名和撤回完全超出本机范围,这是此处所有操作中影响最广的。 下面的其他写入改变的是本机解析的内容;这些操作改变的是所有从该 registry 解析的人所得到的内容。已发布的字节是该 registry 每个使用者都会得到的内容,并且在某个 tag 上重新发布不同内容会被拒绝,因此这里没有任何 请求能撤回一次发布——办法是发布新版本。签名和撤回标记作为制品的同级附加,而不是替换它,因此字节 本身不受影响;但此后获取该制品的任何人也会获取它们,并且 两者都无法从已经拥有它的人那里收回。撤回是三者中最容易误读的: 该版本仍可获取,而工作区信任的撤销会将它从该处解析将选择的范围中移除。

签名需要凭据,在接入客户端之前值得了解凭据从何而来。 无密钥签名按顺序解析身份令牌:先是请求中的 identityToken,然后是守护进程环境中的 AGGREGA_IDENTITY_TOKEN,然后是可访问时环境中的 GitHub Actions OIDC 端点, 最后是 SIGSTORE_ID_TOKEN。若均未得到令牌,操作 会拒绝并说明需要发送什么;它绝不会打开浏览器,因为没有人会去看。 有密钥签名是离线的替代方案,并且请求不指定密钥路径:请求读取的内容 位于它所指定的工作区内,而私钥绝不会存放在工作区内,因此 密钥改为来自该工作区自身配置的 signing: 块。有关两种签名模式及各自联系的对象,参见 aggrega sign。

这四个响应都携带 reach,其中包含 registries——调用所访问的每个 registry 主机, 每个只列出一次,按调用首次访问的顺序排列,因此引用跨越多个 registry 的签名批次或批处理 文件会列出每一个——以及 beyondThisMachine,它依据调用实际附加的内容而非请求的内容得出: 当且仅当调用上传了内容,或附加了签名、发布日期或弃用标记时为 true;对于 dry run 以及发现所有将附加的内容都已存在的调用为 false——例如对已完整的版本再次运行的发布,或每个引用都已带有 可通过验证的签名的签名批次。dry run 仍会列出它本将访问的目标。请在依据结果行动之前 展示它。

注册或移除 registry 默认写入本机所有工作区共享的配置。 一个 registry 及你在其上信任的身份通常无论在哪里工作都相同,因此除非请求发送 workspace: true,条目就写到那里。其后果 值得明确说明:aggrega/registryAdd 和 aggrega/registryRemove 会改变本机每个 项目所依据的解析,包括本会话中无人指定的项目。两个 响应都携带 scope,其中 configFile 为被写入的文件,machineWide 表示它是否为 共享文件。移除是两者中影响更大的,因为重新添加并不是同一回事——原先固定的信任 策略已经消失,之后的注册会固定 registry 届时公布的内容。

初始化配置默认也写入同一个共享文件,原因相同。 aggrega/configInit 注册一个 registry 及其信任策略,这属于全机范围的工具配置,因此在没有覆盖设置时,它写入本机每个项目所依据的配置——并会访问一次该 registry 以读取其公布的策略。其响应携带与两个 registry 方法相同的 scope 对。它与它们有一点值得依赖的不同:它会拒绝而不是覆盖已有的配置文件,因此除非请求发送 force,它无法替换某人正在使用的配置。冻结则相反: aggrega/configCapture 不接受任何覆盖设置,始终写入项目自身的配置文件,且不访问任何 registry,因此它所做的一切对其他项目都不可见。参见配置写入会留下什么。

🔴 添加或移除命令扩展插件默认也会写入同一个共享文件,这一点需要仔细阅读。 aggrega/pluginAdd 和 aggrega/pluginRemove 接受一个 type,在未发送覆盖选项时,由该类型决定写入位置。provider、governance、linter 或 importer 条目影响的是单个项目的构建,因此写入该项目自己的配置。cli 条目属于机器范围的工具,因此一个类型为 cli、既未指定 global 也未指定 workspace 的添加操作,会把该命令注册到全局配置文件中,而这台机器上的每个工作区都通过该文件进行解析——该命令会成为这台机器上每个项目的顶层 aggrega 命令,包括本会话中无人指定的项目,而撤回它需要另行移除,而不是撤销。发送 workspace: true 可将其保留在本地。两个应答都带有 scope,其中包含被写入的 configFile,以及表示它是否为共享文件的 machineWide,后者根据写入实际解析到的文件得出。添加操作还会访问它所搜索的注册表,因此它同时处于两个维度上。参见插件变更告诉你什么。

另外两个插件请求只在工作区内写入。 aggrega/pluginSync 写入请求所指定的 Plugin 实体文件,aggrega/pluginGenCatalog 将生成的实体写入请求所指定的 outputDir 下——两者都写入请求所指定的工作区内,都会拒绝绝对路径或解析到工作区之外的目标,且都不会被其他项目看到。aggrega/pluginGenCatalog 从你选择的任意位置读取其模块和覆盖层,但这不会扩大其写入范围:两者按不同的规则解析,因此生成过程可以读取你在任何地方构建的模块,而它产生的实体仍然落在工作区内。在 dryRun 下,aggrega/pluginGenCatalog 不写入任何内容,而是将内容返回。

固定一个实体同样只在工作区内写入,并会访问其来源所指定的主机。 aggrega/pin 在请求所指定的实体旁写入 entity.lock,这是工作区内的一个路径,并用它获取的来源填充工作区的内容缓存;它写入的任何内容都不会被其他项目看到。它会向外访问以解析该实体指定的每个远程来源——chart 仓库、Git 主机、URL——这与 aggrega/resolveDependencies 为 Release 所使用的来源而进行的访问相同。发送了 pinSources 的 aggrega/resolveDependencies 和 aggrega/publishEntity 会运行同一步骤,因此它们也会在所固定的实体旁写入;因此,执行固定的发布既会触及工作区,也会触及注册表。不执行固定的发布不会在实体旁写入任何内容,但仍会访问这些主机:将锁文件与该步骤将要记录的内容进行比较,意味着要完整获取该实体写出的每个远程来源。

安装助手 skill 不会超出工作区,除非请求发送 global。aggrega/skillsInstall 将每个指明的助手的项目 skill 文件夹写入请求指明的工作区内,它在那里写入的任何内容对其他项目都不可见;其响应的 scope 携带值为 false 的 machineWide。带 global: true 时,它改为写入主目录下每个助手的用户级文件夹,该助手会在机器上的每个项目中读取该文件夹,此时 machineWide 为 true。无论哪种方式,它都不访问任何 registry,也不访问网络。

移除已存储的凭据,其影响范围比这里其他止于本机的操作都更广。 aggrega/logout 会更改凭据存储,而该存储不仅由这台机器上的每个项目共享,还由向相同注册表进行身份验证的所有其他工具共享——因此,通过会话移除的凭据对所有这些工具都会消失,aggrega/registryList 在其他每个工作区中也会报告它不存在。其应答带有 scope 和 machineWide,后者始终为 true:该存储没有可解析到的工作区范围形式,因此没有可发送的覆盖选项,请求也没有可选择启用的内容。与上面的配置写入不同,scope 刻意不指明任何文件。该存储委托给机器上配置的凭据助手或操作系统钥匙串,因此移除操作常常由根本不是文件的东西完成,指明一个路径会让你指向移除操作未必触及的位置。

移除并不是身份验证的逆操作,客户端不应将其作为逆操作提供。 此接口只移除凭据,不获取凭据:要重新获得凭据,需要在终端中使用 aggrega login 再次进行身份验证,因为存储凭据需要由人输入密钥,而没有人在关注此流。因此,客户端提供的“登出”从这里看是单向的。区分两者的是该操作是否必须从驱动它的一方获取某些东西——移除操作在请求中携带它唯一需要的值,而获取凭据则不然——而不是是否有人参与,因为两者都是由人选择的。

回收缓存内容同样会超出工作区。 已编译模块存储和插件描述存储由这台机器上的每个项目共享,因此 aggrega/cachePrune、aggrega/cacheEvict 和 aggrega/cacheClear 可能会移除其他项目所依赖的内容。每次移除都带有其所属类别的 reach,每个应答都带有 scope.machineWideClasses。aggrega/cacheStatus 即使不做任何更改,也会在每个类别上带有同样的影响范围,因为决定是否回收的客户端需要在行动之前知道它。

刷新搜索索引的情况正好相反。 aggrega/registryUpdate 会访问每个 已配置的注册表,而它写入的内容落在本工作区自己配置的缓存目录下—— 因此它不会改变其他项目解析所依据的任何内容。应答中的 indexRoot 指明该 目录。

部分刷新会给出应答,而不是失败。 指定单个注册表且其刷新失败的请求 是一个错误,因为没有可给出的应答。刷新每个已配置注册表的请求即使其中部分或全部失败,也会成功:已刷新的注册表被索引并写入, failed 列出其余的注册表,每个主机都带有各自的错误。请读取 failed,而不是依据是否存在错误来判断。

注册表能否访问由一个键表示,而不是通过解读消息得出。 失败的主机在注册表从未被访问到时带有 unreachable: true——其名称无法解析、到它的连接被拒绝或无法建立,或者无法与它建立安全连接——而对指定单个注册表的请求的拒绝,在其 data 中也带有同一个键。 已访问到但失败的注册表(例如列表出现重复或返回错误状态)两者都不带,其 error 或拒绝的消息会说明它的应答内容。该键从失败本身读取,因此不取决于本机解析器如何描述失败,并且仅在失败表明注册表从未被访问到时才会设置:无法表明任何一方的失败,例如时间限制已到但没有记录中断的是哪一步,在报告时不带该键。请依据该键将注册表标记为未访问到,并将错误显示为原因。

命令行将同一次遍历报告为非零退出,而你是哪种读者决定了该退出的意义。 对于终端前的人来说,它不是完整的说明:aggrega registry update 会打印它索引了所选注册表中的多少个、每个注册表发现了什么、哪些未被索引,以及索引写入的位置——因此摘要说明发生了什么,退出状态只说明是否全部成功。对于脚本来说,它就是完整的说明,因为该命令不提供结构化输出模式,所以其退出状态是唯一可供机器读取的结论。这就是为什么两个接口对同一次部分遍历的应答不同,而两者都是正确的:这个接口向结构化调用方提供 failed 并返回成功,而命令行只有一个比特可用,并把它用在了“是否有注册表被遗漏”上。

观察长时间运行的操作

这里的大多数请求根据磁盘上已有的内容立即作答。少数请求会先做实际工作——解析 Release 的依赖、固定其外部输入、发布、签名、撤回——调用方需要等待。这些请求会在执行过程中报告正在做什么,且需按请求选择启用。

启用需要两步,按以下顺序进行。

  1. 在握手时声明该能力,并等待回复。 在 aggrega/initialize 上发送 capabilities.window.workDoneProgress: true。在该回复到达之前不要发送任何其他内容:请求是并发处理的,因此在握手应答之前写出的请求,可能与本应为其协商的握手同时运行。每个客户端本来就应当遵守协议的这一顺序;这只是又一项依赖它的事情。
  2. 在请求的 params 中放入一个令牌。 向你希望获得报告的请求的 params 添加 workDoneToken。其值由你选择——字符串或数字——它将通知与该调用关联起来。每次调用都生成一个新的令牌。

通知。 每条通知都是 $/progress,其中 params.token 设为你的令牌,params.value 携带一个负载:

value.kind携带时机
begintitle——正在发生什么,用一个可以展示给读者的短语表述一次,在工作开始时
reportmessage——操作对自身的一行陈述任意次数,随操作写出而发送
end除类型外不含任何内容一次,在工作结束时

按令牌关联,切勿按请求 id 关联。 通知不携带 id——它不是对任何内容的响应——令牌是其中唯一指回你的调用的东西。这是有意为之:在许多客户端中,请求 id 属于传输层,从不会到达发起调用的代码,而令牌是该代码已经持有的值。

report 携带编译器自己的文本。 消息是操作在工作时写出的一行,去除首尾空白后原样传递,其他不做任何改动——不改写、不概括、不重组——操作写出的空行会被丢弃,而不是作为空消息报告。因此客户端按原样显示所收到的内容。这与响应自身的诊断具有相同的特性:无论有多少处报告同一条件,其措辞都保持一致。

操作所等待的步骤也是一个 report。 当操作进入它要等待的步骤时——读取 registry、获取制品、编译插件——一个 report 会携带该步骤的名称,用词与命令行针对同一步骤在其进度指示器旁显示的相同。只有在 begin 与 end 之间进入的步骤才会被报告。

一行输出就是一个 report。 一次写出多行的操作会每行产生一条通知,分段写出的一行会在完整后才报告——因此消息永远不会是半句话。

没有比例也没有百分比,这并不是有待实现的遗漏。 这里会报告的操作所处理的集合,其大小在工作开始时是未知的——一次解析要遍历多少引用、一次发布要上传多少层——因此任何比例都将是编造的。请绘制不确定进度指示器,并显示最新的 message。

帧在响应之前到达,绝不会在响应之后。 begin 在工作真正开始后才到达,因此因 params 被拒绝的请求——绝对路径、缺少必填字段——不会产生任何通知,只有其错误。end 在响应之前到达,操作是否成功体现在响应中,而不会在 end 中重复。

停止工作是一条单独的通知。 使用你发送请求时所用的 id 发送 $/cancelRequest。令牌在取消中不起作用,取消也不会撤销已发送的帧。

哪些请求会报告,其余请求应有何预期

恰好是这些请求会报告: aggrega/resolveDependencies、aggrega/pin、aggrega/publishEntity、aggrega/publishArtifact、aggrega/signArtifacts、aggrega/deprecateArtifact。

它们每一个都满足两点,这也正是它们列入清单的原因:它会代表你访问注册表或远程 URL,因此耗时由本机之外的因素决定;并且它本来就会在执行过程中写出对自身的陈述——即在终端前观察的人所读到的内容。因此报告交给你的就是同一份陈述,而不是为传输另行编写的第二份,操作本身的行为也无需为此做任何改变。

其他所有请求都接受令牌,但不发送任何内容。 发送令牌无害,不会报错:它会被接受,不会有通知到达,答复与不带令牌时完全相同。因此客户端可以随意附加令牌,没有收到内容时什么都不绘制即可。

🔴 不要把沉默理解为“这个是即时的”。 其余请求大多确实根据磁盘上已有的内容作答——验证、悬停、补全、图、缓存列表、配置读取——但并非全部如此:刷新注册表索引、添加插件、发布前检查,以及在本机没有工作区可读文档时首次展开某个代码,都会访问注册表,而编译 Release 是实际工作。这些请求需要多久就是多久,目前不报告任何内容。对任何你准备等待的请求都显示不确定进度指示器,并将通知视为有则可得的细节,而不是表明工作正在进行的依据。

两种拒绝

两者都是 invalid-params 错误,并且都会指明该怎么做,因为一个悄无声息不起作用的令牌会让你一直等待一个永远不会到来的流。

  • 来自未声明 window.workDoneProgress 能力的会话的令牌会被拒绝,并指明需要声明的能力。请在握手时声明它,或者不带令牌。
  • 既不是字符串也不是数字的令牌会被拒绝,并指明这两种形式。缺省令牌以及显式的 null 不会被拒绝——两者都表示你没有请求报告。

锁文件感知

守护进程在每次 aggrega/irGraph 时,针对该请求指定的 Release 检查锁文件是否发生漂移,并将漂移作为非阻塞警告呈现。该警告会指出用于重写包含该 Release 的锁文件的命令,其写法与请求发送时一致——aggrega pull --release 后接你发送的 release,也就是在工作区根目录的终端中的写法。aggrega/irGraph 要求锁文件存在。启动时没有单独的检查:请求会说明它针对哪个 Release,因此结论是在被请求时针对该 Release 计算的,而不是针对预先选定的某一个 Release 只计算一次。

**锁文件消失时,漂移警告随之消失。**警告发布在引发它的锁文件上,而一个已不存在的锁文件没有任何可漂移的固定项——警告所指的命令会写入一个新文件,而不是修复旧文件。因此,每个发现锁文件缺失的请求都会先撤回警告,再以锁文件缺失错误拒绝:aggrega/irGraph、aggrega/releaseClosure、aggrega/build、aggrega/buildPreview、针对图节点的 aggrega/attachCandidates 和 aggrega/attachmentContainer,以及 aggrega/connectionAtPosition。撤回以针对该锁文件、携带空列表的 aggrega/publishDiagnostics 通知形式送达,先于拒绝。它来自上述请求中最先得知删除的那一个,因此客户端报告删除后再请求与该 Release 相关的任何内容,警告就会被清除,而无需专门请求图。仍然存在且仍有漂移的锁文件,在上述每个请求中都会保留其警告。指定该锁文件的 aggrega/invalidate 会丢弃守护进程为其持有的内容,但不发送任何东西;随后的请求才会告知客户端。而守护进程甚至无法检查的锁文件——例如其所在目录不允许读取——不会撤回任何内容,因为它可能仍然存在,警告也可能仍然成立。

aggrega/build 和 aggrega/buildPreview 同样要求锁文件,并且会让 Release 严格符合它,而不只是警告——它们以产出制品的界面的姿态进行渲染,因此,对于检查只会发出警告的情形,即锁文件不再与 Release 解析的结果相符,会使它们停止。没有锁文件的 Release 会以锁文件缺失错误被拒绝。例外是 autoPull 字段要求先解析依赖的构建:该构建会写入锁文件,然后针对所写内容进行渲染,以这种方式产生的锁文件不会被第二次检查漂移,因为写入它的解析过程在写入前已对其运行了相同的检查,且不会写入该检查拒绝的锁文件。

**存在但未记录某个插件摘要的锁文件不会阻止图——缺失的锁文件才会。**这是两种情况,只有第二种会拒绝。aggrega/irGraph 不会要求它解析出的字节符合其记录的摘要:无法验证的固定项会被报告而不是拒绝,图照常绘制,结果显示在 Problems 面板上,因为拒绝绘制图的编辑器让读者一无所有,而报告则给读者留下可以采取行动的东西。在其他地方插件同样会运行,并附带一条警告,说明没有任何东西检查过其字节。aggrega/irGraph 拒绝的是缺失的锁文件:它在解析任何内容之前停止,并以锁文件缺失错误作答,指出它查找的锁文件和 Release,因此客户端可以直接提供 aggrega pull --release <release>——或为该 Release 发送 aggrega/resolveDependencies,在不离开会话的情况下写入锁文件。区分这两者很重要,因为绘制出的图是读者随后据以推理的画面,而用未经检查的字节构建的图与经过检查的图画得一模一样,结果却位于读者没有注意的地方。所以图并不是对其背后字节的裁定——aggrega/build 和 aggrega/buildPreview 才是让 Release 符合其记录摘要的界面,在检查只报告的地方停止。

**aggrega/validate 在请求指定 Release 时,只读取该 Release 锁文件中的固定项和弃用通知——而对它作为单个实体检查的目录实体,则不读取任何锁文件,与命令行一样。**它不要求所运行的插件符合记录的摘要,也不根据锁文件重建转换插件的挂接集合——它针对你眼前现有的工作区配置进行验证,这正是编辑器在你编辑该配置时必须做的。aggrega validate 和 aggrega build 两者都会做,并且仍是对已提交工作区作出裁定的权威界面。

**其弃用通知涵盖记录撤回的两个位置。**固定引用上的标记位于锁文件中;以返回接受或拒绝裁决的角色挂载的插件上的标记——即位于 ir-verdict 或 render-verdict 的 plugins.governance 挂载,或 plugins.linter 挂载——位于其旁边的插件信任记录中,因此验证会读取两者,并以 aggrega build 打印的措辞,在 Aggregate 开头将每个已撤回的引用和每个已撤回的插件作为警告列出。通知不会改变任何裁决。存在但无法读取的信任记录会作为错误报告以取代验证结果,而不会被当作未记录任何内容的记录来读取。aggrega/releaseClosure 在其 deprecations 中报告同一组内容。

Release 的锁文件在哪里

每个指定 Release 的回答也会指定其锁文件,因此客户端无需自行推算路径。aggrega/activeRelease 以 lockfile 携带它,与 release 并列;aggrega/releaseCandidates 以 lockfiles 映射携带,与 releases 并列;锁文件缺失错误则在其 data 中以 lockfile 携带。每一项都是 aggrega pull --release <release> 写入、aggrega build 读取的文件,也是上述每个请求所检查的文件——因此监视 Release 锁文件以察觉其被写入、重写或删除的客户端,监视的正是守护进程所指的文件。锁文件位于其 Release 旁边,采用 Release 的名称,并将 .yaml 或 .yml 扩展名替换为 .lock;使用其他扩展名命名的 Release 会保留其完整名称,因此 release.rel 的锁文件是 release.rel.lock。请从回答中读取路径,而不是根据上述描述拼接,这样两者就不会出现偏差。

渲染请求的外部引用

渲染可能会请求来自远程 URL 的内容,例如某个 chart 的 values schema 带有远程引用。对于只要求告知信息的请求,守护进程为响应它而执行的每次渲染都会冻结外部输入。 该 Release 的 lockfile 所固定的引用由内容寻址存储提供,这是读取已在磁盘上的内容而非获取,并且在提供其字节之前会与 lockfile 的记录进行核对——因此这里的渲染看到的与构建看到的相同,并引发构建会引发的提示。lockfile 未固定的引用会被拒绝而不是获取:获取它需要访问网络并向存储写入 blob,而会话在只要求告知信息的请求上两者都不做。这就是从渲染一侧来看的 访问注册表与写入 下的规则,无论这样的渲染是如何触发的,它都成立。

专门用于固定的请求是例外,而且与注册表规则已有的例外相同。 aggrega/resolveDependencies 的职责就是获取,因此它为发现该 Release 使用了哪些引用而执行的渲染会访问网络并写入它所固定的内容——正因如此,它的结果是一个 lockfile 而不是一份报告。图请求或构建请求为自身执行的渲染都不会做这些事。

要求先解析的构建直接使用那次渲染作答,因此它只渲染该 Release 一次。 解析已经针对刚写入的固定项、在构建所运行的检查关卡下渲染了构建所涉及的内容,因此构建呈现那次渲染而不再执行第二次——获取仍然属于解析而非构建。只有完成的渲染才会这样使用:如果解析固定了依赖但未能完成外部引用的发现,构建会针对已写入的固定项自行渲染,未固定的引用会在那里被拒绝并报告,与未解析任何内容的构建完全相同。

拒绝会被报告而不是被吞掉,因为结果本身无法说明缺少了哪个引用。对于此二进制文件自带的 provider,请求该引用的 provider 会把拒绝交回,因此触及被拒绝引用的渲染不会完成。因此,每个被拒绝的引用都会作为 aggrega-build 层上的独立条目出现,指明该引用以及固定它的命令:aggrega pull --release <release>,或者不离开会话完成同样工作的 aggrega/resolveDependencies。这些条目是提示性的而非拒绝——图仍会返回,与上文的漂移警告地位相同——并且它们归属于文件开头的 Aggregate,因为渲染请求的引用并不对应作者编写的任何键。它们与渲染自身的提示在同一次发布中传送,该发布会整体替换该层,因此你随后固定的引用会自动不再被报告,无需任何清除操作。完全固定的渲染对此不会有任何输出。每个条目的结构参见 诊断条目包含的内容。

在 aggrega/irGraph 上,这取决于渲染阶段是否运行。 除非 --build-on-inspect 或它所覆盖的 serve.build_on_inspect 键将其开启,图请求会跳过渲染;该开关关闭时,不会请求任何外部引用,也就没有可拒绝的内容。开启它才会把渲染自身的提示以及这些条目带入编辑器会话。

会话与命令行上相同冻结的区别。 aggrega build 在试运行时同样冻结外部输入,未固定的引用在两个界面上的行为相同:它被报告为指明该引用的发现,随后渲染停止,因为请求它的 provider 会把拒绝交回。区别在于重新获取。在命令行上,存储副本已丢失的固定引用会按其记录的摘要重新获取;而响应图请求或构建请求的渲染不会重新获取任何内容,因为该渲染不访问网络,所以无法取回存储中已不存在的固定引用——这样的引用也不属于上文所述的拒绝,后者指的是 lockfile 未固定的内容。让会话执行固定即可恢复:上文提到的请求会访问网络并补回缺失的字节。固定会获取和记录哪些内容,参见 aggrega pull。

被拒绝的运行仍会告诉你什么

拒绝的请求以错误信封作答,而运行此前已得出的发现不会随该信封传递——信封根本不携带结果体。它们到达你的方式与运行完成时相同:作为 aggrega-build 层上的一次诊断发布,详见诊断条目携带的内容。因此,处理拒绝的客户端从信封中读取需要更改什么,从问题面板中读取运行发现了什么,二者互不替代。渲染期间引发的拒绝是唯一一种同时也是关于作者所写内容的发现的拒绝,因此它会同时到达两处,如下一节所述。

**无论运行是否到达终点,该发布都会发生。**中途停止的运行仍然发现了停止点之前的所有内容,而丢失这些发现的读者将不得不再次运行才能看到它们——因此,警告根据运行到达的位置发布,拒绝随后返回。它们是同一组发现,保真度相同,定位在相同的编写键上:拒绝不会把一个发现降格为一句话。被拒绝的外部引用也随同一次发布传递,原因相同,途径相同。

**限定它的是运行进行到了哪一步,而不是该层能携带什么。**来自编译器启动之前运行的检查之一的拒绝——Release 的闭包无法解析、Manifest 将某个类型映射到未实现它的 recipe、lockfile 不再与 Release 解析的结果匹配、缓存中某个已固定条目不再与为其记录的摘要匹配且没有任何目录目录持有已固定的字节——没有可发布的警告,因为此时还没有引发任何警告。此时该层不携带任何内容,而不是携带过时的内容;而一次连文档都还没命名的运行则根本不发布任何内容,使你问题面板上已有的内容保持原样,而不是清除它对其一无所知的条目。

渲染期间引发的拒绝

编译器在渲染时拒绝的 Release——Workload 命名了其 Component 未声明的槽位、断言失败、模板无法求值、实现未达到其必须提供的内容——会在每个渲染它的请求上,在其指向之处、以编译器的原话报告:aggrega/build、aggrega/buildPreview,以及开启了渲染阶段的 aggrega/irGraph。答复是带有 -32603 代码的错误信封,其 message 是该拒绝及其下的每个原因,措辞与命令行对同一构建打印的相同:正在渲染的节点,然后是其中拒绝的内容,每个原因位于它所解释的原因之后——当拒绝命名一个已注册条件时,以该条件的短代码开头,与每个命名条件的拒绝一样。其 data 以 file 命名拒绝所指向的文档,以 line、column、end_line 和 end_column 命名其中该键的范围,并附带该条件的 code 和 shortCode;未命名键的拒绝,或所命名的键不在该文档中的拒绝,仅携带 file;不指向任何文档的拒绝则命名该 Release 的 Aggregate。

同一拒绝会发布在 aggrega-build 层上,位于该文档、该键处,作为一个严重级别为 error 的条目,携带拒绝自身的 keyPath 和去掉开头短代码的信封 message,并且——当拒绝命名一个已注册条件时——携带该条件的 code、shortCode 和 codeDescription,短代码在那里以其自身字段传递。它随携带运行停止前所引发警告的同一次发布传递,因此它像这些警告一样替换该层:该 Release 下一次渲染的运行会发布不含它的层,而它所在的文档会被发布为空,这正是将它从你的问题面板中清除的方式。

**拒绝指向何处,取决于拒绝本身命名了什么,不会更精细。**Workload 的检查评判的是其模板生成的文档,而模板可以写出没有作者写过的行——循环、条件、从文件或库导入的文本——因此渲染后 Workload 的一行并不对应 Recipe 的一行。因此,关于 Workload 的拒绝放在 Recipe 的 workload 键上,它在渲染文档内命名的路径保留在其消息中。失败的断言放在声明它的 Recipe 或 FeatureRecipe 中 assertions 下其自身的键上;Component 或 Feature 声明的断言在任何文档可供命名之前就已引发,放在 Aggregate 的 kind: 键上。来自命名了文档但未命名键的步骤的拒绝,放在该文档的 kind: 键上。

**合并了多个发现的拒绝会逐个发现发布。**渲染所依据的图的组合会在一次拒绝中带上它发现的所有违规——一个条目命名了没有任何对象响应的目标、一个 component 的两个连接被赋予同一别名——命令行会将每一项作为单独的诊断打印,各有其标题。在这里,每一项都是 aggrega-build 层上的单独条目,位于该发现所命名的文档和键处——Release 写的就在 Release 上,Aggregate 写的就在 Aggregate 上——使用其自身的措辞和代码。答复的 message 携带所有发现,其 data 命名第一个发现指向的位置。

**作者声明为敏感的值在这里的隐藏方式与命令行完全相同。**拒绝的文本就是编译器引发的文本,这一层不会改写它,而编译器会在引发拒绝之处隐藏已声明的值——以 <redacted> 代替——因此此答复、此条目和终端以相同措辞呈现它;拒绝对已声明值说了什么说明了具体方式,以及哪些拒绝不在此范围内。

**来自渲染前运行的关卡的拒绝不属于此类。**上文列出的检查按 被拒绝的运行仍会告诉你什么 所述的方式作答。Component 或 Feature 声明的断言,以及针对组合图的拒绝,介于两者之间:它们都在渲染之前、由每个解析 Release 图的请求引发,因此 aggrega/irGraph 在渲染阶段关闭时也会如上所述作答并发布;aggrega/releaseClosure、被问及图节点的 aggrega/attachCandidates 和 aggrega/attachmentContainer,以及 aggrega/connectionAtPosition,则以相同的信封作答且不发布任何内容,因为它们不拥有问题面板。

错误码

响应使用标准 JSON-RPC 错误码,外加 1xxx 区段内的应用级范围。编辑器客户端可以根据错误码分支处理,而无需解析消息。

  • 1001 file-not-validated——对于该文件的当前状态,守护进程未持有任何可供请求据以应答的内容:没有其解析结果,或者,对于 aggrega/diagnostics,没有其解析结果,或者没有为该文件持有任何针对守护进程当前所持文本的验证应答。为其发送 aggrega/validate 后再次请求。
  • 1003 lockfile-absent——请求所指定的 Release 没有 lockfile,而所请求的操作需要一个。
  • 1004 entity-not-resolvable——该名称在任何目录层级中都没有匹配到实体,在请求所指定的 Release 中也没有;或者作为名称发送的注册表引用无法读取为实体,消息会指出说明原因的条件;或者该 Release 的 lockfile 是一个指向工作区之外的链接,这会在任何读取之前被拒绝,此时 data 会指明该 lockfile 和该 Release,消息以该条件的短代码 E0321 开头——参见工作区边界。
  • 1005 shutting-down——守护进程在收到关闭通知后正在排空,并拒绝新请求。不要针对同一子进程重试。
  • 1006 validation-in-flight——该文件的验证正在运行,且未在等待中的请求所允许的时间预算内完成。稍后再次请求,不要发送任何内容。

1002 未被分配,可供下一个需要错误码的条件使用。

File-not-validated 与 validation-in-flight 报告的是相反的状态,各自要求的操作也相反。 File-not-validated 表示,对于该文件的当前状态,守护进程未持有任何可供请求据以应答的内容——没有其解析结果,或者,对于 aggrega/diagnostics,没有其解析结果,或者没有为该文件持有任何针对守护进程当前所持文本的验证应答:发送 aggrega/validate 后再次请求。中途被取消的验证会让文件处于这种状态,因为它不存储任何内容,而先前一次验证针对不同文本的发现并不是对守护进程当前所持文本的应答;只要文本仍是先前应答所检查的那份,该应答就依然有效。守护进程针对它自己从磁盘读取的文件推送的发现——发生漂移的 lockfile、无法加载的 Release——并不是对你所持文本的验证,因此也不能应答此请求。针对不同文本、间隔很近地发送的两次验证,也可能让你处于这种状态,即守护进程所保留文本对应的那次验证先完成时:尽管该文本已经过检查,请求仍会被拒绝,再验证一次即可得到应答。它以解析结果而非文件来表述,是因为一个没有任何解析器会读取的缓冲区恰好处于这种状态——验证已经运行并报告了它的发现,但仍然没有可用于应答的解析结果。Validation-in-flight 表示该文件的验证正在运行,且未在等待中的请求所允许的时间预算内完成:稍后再次请求,不要发送任何内容,因为你需要的状态已在途中,第二次验证只会增加工作量。把两者当作同一个条件,会导致客户端在不应发送验证的情况下发送验证。两个区段对客户端意味着不同的事情:1xxx 错误码指出用户可以处理的工作区状态——验证文件、生成 lockfile——而 invalid-params 之类的标准错误码指出格式错误的请求,由客户端而非用户来纠正。存在但格式错误的 release 值——绝对路径,或解析到工作区根目录之外——属于第二个区段:需要修复的不是工作区的状态,而是请求。省略 release 不属于任何区段,因为它根本不是错误;它会选择实时验证中描述的两种应答里范围较窄的那一种。

错误可以携带一个 data 对象,其中每个键只指代一件事。file 是失败所涉及的源文档——正在验证的文档、加载失败的 Release、声明了无法解析的名称的工作区文档,或渲染期间引发的拒绝所指向的文档——随附的 line 和 column 即在该文档中定位位置。这两者本身是可选的:涉及整个文档的失败只携带 file。lockfile 是一个 lockfile。release 是错误所涉及的 Release,写法与请求中的指定方式一致,因此客户端无需从消息中解析即可组合出 aggrega pull --release <release>。unreachable 表示被拒绝的请求所指定的注册表无法访问:指定了某个注册表的被拒绝的索引刷新会携带它,其值读取自失败本身;已应答的注册表则不带此键。每个键都是可选的,仅当守护进程掌握该值时才出现;没有哪个键代替另一个键,因此一个键指向什么从不取决于其旁边的错误码。

data 中的 code 和 shortCode 指明拒绝所报告的条件,凡是报告已注册条件的拒绝都会携带,无论其数字错误码是什么:程序据以分支的描述性代码,以及人引用的短代码——与诊断条目为同一条件携带的两个标识符相同、名称相同,并列在所有条件的表中。请根据 code 分支。数字错误码指出请求的状态,对许多条件都保持不变——因目录链接指向外部而被拒绝的构建,与因名称无法解析而被拒绝的构建,都是 1004——而消息是可能被改写的文字,因此两者都无法区分不同条件。Invalid-params 就是这样一个共享的错误码:指定了一个其配置文件指向自身之外的工作区的请求同样会得到它,此时 read-leads-out-of-workspace 表明问题出在工作区的布局,需要由人来修复,而不是请求本身。未报告已注册条件的拒绝不携带这两个键,两者要么同时出现,要么都不出现。指明某个条件的拒绝,其消息以该条件的短代码开头一次,即 E0321: …,这是阅读者在每个此类拒绝中看到的形式;如果拒绝的消息已经以带有该代码的方括号标头开头——即加载所拒绝的目录文档的单行报告——则不会再次添加。

工作区 Release 级联的运行过程说明随 aggrega/activeRelease 的应答在其 trace 字段中传递,而不是随错误传递:未指向任何 Release 的工作区是一种普通状态,而不是失败的请求。**它是供人阅读的诊断文字,而不是供解析的结构。**请按原样展示——写入日志,或写入用户可以打开的面板——不要对其进行模式匹配、从中提取值,或根据其中使用的标签分支:其措辞、布局和这些标签随级联本身而定,级联一变它们就会变。原样传递文本的客户端在此类变化后仍能正常工作;学习了其形态的客户端则会因此出错。

另请参阅

  • ../schema/other/serve-wire.md — 本协议交换的消息结构,由已发布的 schema 生成:逐字段列出每个方法的参数对象、每个结果和每个通知载荷。
  • ./aggrega-build.md — build 命令,aggrega/build 同样运行其编译器流水线、关卡和依赖解析,因此两个入口写出的是同一个输出树,而不是两个。
  • ./aggrega-version.md — 编辑器扩展用来检查守护进程兼容性的 version 命令。
  • ./aggrega-pull.md — 守护进程的漂移检测入口所读取的 lockfile。
  • ./aggrega-lint.md — 守护进程按请求报告的发布约定;开启 serve.lint_on_validate 后,每次验证时也会报告。

概要

aggrega serve [flags]

说明

Run the Aggrega compiler as a long-running service. The daemon
reads JSON-RPC 2.0 messages from stdin and writes responses to stdout
under the aggrega/ method namespace. State (parsed YAML, diagnostics,
resolved catalog) holds across requests so IDE clients can issue many
cheap operations without re-paying per-invocation startup cost.
The daemon resolves its workspace root through the same path every
aggrega command uses: --workspace-root when set (used as-is, validated
to exist as a directory), otherwise discovery walking upward from the
current working directory. A directory anchors the workspace when it
holds a .aggrega-config.yaml carrying a workspace: block, or — as a
fallback — any of .aggrega/, aggregate*.yaml, release*.yaml,
manifest*.yaml.
Configuration is the cascade composition of the .aggrega-config.yaml
files from the workspace root down to the working directory (nearer
overrides farther), beneath which the global config file — the one
--config names, else the one the AGGREGA_CONFIG environment variable
names, else the default location when a file is there — and the
built-in defaults apply.
The daemon honors the aggrega/shutdown JSON-RPC notification for a
cooperative cross-platform exit: the daemon completes the in-flight
handler if any, refuses new requests with code 1005, and exits
cleanly within a 2-second drain budget.
Asking the process itself to stop — an interrupt from the terminal, or
a termination request from a supervisor or container runtime — takes
the same path on the same terms: the first request drains the daemon
and it exits cleanly, and a second ends the process at once.

标志

标志默认值描述
--build-on-inspectfalse在检查 IR 图时运行制品渲染阶段,使 aggrega build 在渲染时发出的建议也显示为编辑器问题。它不会添加任何导致构建中止的检查。不会向磁盘写入任何内容:没有渲染出的制品,没有输出目录,也没有 lockfile。默认关闭,与 aggrega inspect 一致,后者同样不发出此类建议。设置后,会覆盖 serve.build_on_inspect 配置键。