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

Aggrega 后台守护进程线路协议 schema

自动生成的参考文档。请勿手动编辑——请从发布的 JSON Schema 重新生成。

Schema id:https://aggrega.ai/schemas/serve-wire-v1beta1.schema.json

与由 aggrega serve 启动的后台编译器守护进程交换的消息结构。客户端通过握手在该守护进程上打开一个会话,会话决定了设置以及打开对话时所基于的工作区的作用范围;守护进程则是应答请求、发送通知并保存其已读取内容的进程。该协议是基于标准输入和标准输出的 JSON-RPC 2.0,每条消息由 Content-Length 头分帧;本文档描述消息体,既不描述分帧,也不描述传输。消息体是以下四种之一:客户端发送的请求、客户端发送的通知、守护进程发送的通知,或守护进程针对请求返回的响应。该接口的三个特性决定了下文结构的写法。第一,每个请求除其自身方法声明的字段外,还接受两个字段——workspaceRoot,指明请求作用的工作区;以及 workDoneToken,由调用方生成、用于报告进度的值——因此这两个字段出现在此处的每个请求 params 对象上,包括主体不是工作区的三个方法:aggrega/getSchema 和 aggrega/scaffoldEntity 接受 workspaceRoot 但会忽略它,而 aggrega/initialize 将其读作会话所声明的工作区。第二,守护进程会拒绝携带该方法不接受字段的请求 params 对象,并指明它所接受的字段,因此此处每个 params 对象在顶层都是封闭的;请求内部的嵌套对象不封闭,因为该检查只读取最外层的字段名。第三,结果由守护进程组成,而非由调用方提供,因此结果对象在结构固定的每一层都是封闭的,只在值为守护进程不读取而直接透传的不透明 JSON 时才开放。守护进程编码方式带来的一个后果在线路上可见,本文如实描述而不加掩饰:守护进程未标记为可选的集合,在没有值可报告时输出为 null,在所报告的值为空时输出为空集合,因此凡适用之处两种形式都被接受。

以下形态之一

  • Request
  • ClientNotification
  • DaemonNotification
  • SuccessResponse
  • ErrorResponse

定义

ProtocolVersion

每条消息携带的 JSON-RPC 版本。仅支持 2.0。

类型: const "2.0"

常量:"2.0"

RequestId

调用方为请求指定的标识符,会在答复该请求的响应中原样返回。不携带标识符的消息是通知,永远不会得到答复。

类型: string or number

ProgressToken

调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。

类型: string or number

WorkspaceRootSubject

该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。

类型: string

WorkspaceRootAccepted

工作区的绝对路径。该方法的主体不是工作区——它依据二进制文件自身携带的内容作答——因此该字段会被接受但不会被读取。之所以允许该字段,是因为客户端可以在每个请求中统一发送它,而无需知道哪些方法会读取它。

类型: string

RequestMethod

请求可以指定的所有方法。该集合是封闭的:指定其他任何内容的请求会收到 method-not-found 错误作为答复。

类型: string (enum)

允许的值:"aggrega/activeRelease"、"aggrega/attachCandidates"、"aggrega/attachmentContainer"、"aggrega/build"、"aggrega/buildPreview"、"aggrega/cacheClear"、"aggrega/cacheEvict"、"aggrega/cachePrune"、"aggrega/cacheStatus"、"aggrega/catalogIndex"、"aggrega/completion"、"aggrega/configCapture"、"aggrega/configInit"、"aggrega/connectionAtPosition"、"aggrega/connectionCandidates"、"aggrega/deprecateArtifact"、"aggrega/diagnostics"、"aggrega/editDocument"、"aggrega/effectiveConfiguration"、"aggrega/entityDefinition"、"aggrega/explainError"、"aggrega/findImplementations"、"aggrega/findReferences"、"aggrega/getSchema"、"aggrega/hover"、"aggrega/import"、"aggrega/initialize"、"aggrega/insertionPoint"、"aggrega/invalidate"、"aggrega/irGraph"、"aggrega/lint"、"aggrega/logout"、"aggrega/pin"、"aggrega/pluginAdd"、"aggrega/pluginGenCatalog"、"aggrega/pluginRemove"、"aggrega/pluginSync"、"aggrega/publishArtifact"、"aggrega/publishEntity"、"aggrega/registryAdd"、"aggrega/registryList"、"aggrega/registryRemove"、"aggrega/registryUpdate"、"aggrega/releaseCandidates"、"aggrega/releaseClosure"、"aggrega/resolve"、"aggrega/resolveDependencies"、"aggrega/scaffoldEntity"、"aggrega/search"、"aggrega/setActiveRelease"、"aggrega/signArtifacts"、"aggrega/skillsInstall"、"aggrega/skillsList"、"aggrega/validate"

ClientNotificationMethod

客户端通知可以指定的所有方法。该集合是封闭的,且两种通知都不会得到答复。

类型: string (enum)

允许的值:"$/cancelRequest"、"aggrega/shutdown"

DaemonNotificationMethod

守护进程发送的通知可以指定的所有方法。该集合是封闭的。

类型: string (enum)

允许的值:"$/progress"、"aggrega/publishDiagnostics"

Request

由客户端发送、由守护进程答复的请求。method 指明所请求的内容;params 对象携带该方法自身的字段,以及每个方法都允许的两个字段。完全省略 params 的请求被视为所有字段均缺省的请求。

属性类型必需描述
jsonrpcProtocolVersion是每条消息携带的 JSON-RPC 版本。仅支持 2.0。
idRequestId是调用方为请求指定的标识符,会在答复该请求的响应中原样返回。不携带标识符的消息是通知,永远不会得到答复。
methodRequestMethod是请求可以指定的所有方法。该集合是封闭的:指定其他任何内容的请求会收到 method-not-found 错误作为答复。
paramsobject否

不允许其他属性。

每个 method 的 params:

methodparams必需
"aggrega/initialize"InitializeParams否
"aggrega/validate"ValidateParams否
"aggrega/invalidate"InvalidateParams否
"aggrega/diagnostics"DiagnosticsParams否
"aggrega/irGraph"IrGraphParams否
"aggrega/build"BuildParams否
"aggrega/buildPreview"BuildPreviewParams否
"aggrega/entityDefinition"EntityDefinitionParams否
"aggrega/releaseClosure"ReleaseClosureParams否
"aggrega/resolveDependencies"ResolveDependenciesParams否
"aggrega/pin"PinParams否
"aggrega/cacheStatus"WorkspaceAndProgressParams否
"aggrega/cachePrune"WorkspaceAndProgressParams否
"aggrega/cacheEvict"CacheEvictParams否
"aggrega/cacheClear"WorkspaceAndProgressParams否
"aggrega/registryList"WorkspaceAndProgressParams否
"aggrega/search"SearchParams否
"aggrega/registryAdd"RegistryAddParams否
"aggrega/registryRemove"RegistryRemoveParams否
"aggrega/registryUpdate"RegistryUpdateParams否
"aggrega/logout"LogoutParams否
"aggrega/publishEntity"PublishEntityParams否
"aggrega/publishArtifact"PublishArtifactParams否
"aggrega/signArtifacts"SignArtifactsParams否
"aggrega/deprecateArtifact"DeprecateArtifactParams否
"aggrega/resolve"ResolveParams否
"aggrega/findReferences"FindReferencesParams否
"aggrega/findImplementations"FindImplementationsParams否
"aggrega/hover"HoverParams否
"aggrega/completion"CompletionParams否
"aggrega/catalogIndex"CatalogIndexParams否
"aggrega/attachCandidates"AttachCandidatesParams否
"aggrega/connectionCandidates"ConnectionCandidatesParams否
"aggrega/insertionPoint"InsertionPointParams否
"aggrega/attachmentContainer"AttachmentContainerParams否
"aggrega/connectionAtPosition"ConnectionAtPositionParams否
"aggrega/releaseCandidates"WorkspaceAndProgressParams否
"aggrega/activeRelease"WorkspaceAndProgressParams否
"aggrega/setActiveRelease"SetActiveReleaseParams否
"aggrega/editDocument"EditDocumentParams否
"aggrega/effectiveConfiguration"WorkspaceAndProgressParams否
"aggrega/configInit"ConfigInitParams否
"aggrega/configCapture"ConfigCaptureParams否
"aggrega/import"ImportParams否
"aggrega/scaffoldEntity"ScaffoldEntityParams否
"aggrega/lint"LintParams否
"aggrega/pluginAdd"PluginAddParams否
"aggrega/pluginRemove"PluginRemoveParams否
"aggrega/pluginSync"PluginSyncParams否
"aggrega/pluginGenCatalog"PluginGenCatalogParams否
"aggrega/explainError"ExplainErrorParams否
"aggrega/getSchema"GetSchemaParams否
"aggrega/skillsInstall"SkillsInstallParams否
"aggrega/skillsList"WorkspaceAndProgressParams否

ClientNotification

由客户端发送的通知。它不携带标识符,永远不会得到答复。

属性类型必需描述
jsonrpcProtocolVersion是每条消息携带的 JSON-RPC 版本。仅支持 2.0。
methodClientNotificationMethod是客户端通知可以指定的所有方法。该集合是封闭的,且两种通知都不会得到答复。
paramsobject否

不允许其他属性。

每个 method 的 params:

methodparams必需
"$/cancelRequest"CancelRequestParams是
"aggrega/shutdown"ShutdownParams否

DaemonNotification

由守护进程发送的通知。它不携带标识符,永远不会得到答复。

属性类型必需描述
jsonrpcProtocolVersion是每条消息携带的 JSON-RPC 版本。仅支持 2.0。
methodDaemonNotificationMethod是守护进程发送的通知可以指定的所有方法。该集合是封闭的。
paramsobject是

不允许其他属性。

每个 method 的 params:

methodparams必需
"$/progress"ProgressParams是
"aggrega/publishDiagnostics"PublishDiagnosticsParams是

CancelRequestParams

请求守护进程放弃一个正在进行的请求,通过该请求携带的标识符指定它。对于已完成或从未发送的请求,没有可取消的内容,不会有任何提示。

属性类型必需描述
idRequestId是调用方为请求指定的标识符,会在答复该请求的响应中原样返回。不携带标识符的消息是通知,永远不会得到答复。

不允许其他属性。

ShutdownParams

请求守护进程停止接受新工作,并完成已接手的工作。该通知不携带任何字段,通知本身通常完全不带 params 对象发送。第二次发送会放弃仍在进行的工作,而不是等待其完成。

该对象未声明固定属性,也不允许任何属性。

ProgressParams

一条正在进行的工作的报告,仅针对生成了进度令牌的请求发送,且该请求所在的会话已声明能够接收进度报告。

属性类型必需描述
tokenProgressToken是调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
valueProgressBegin 或 ProgressReport 或 ProgressEnd是报告本身。先是一条开始报告,然后是任意数量的行,最后是一条结束报告。

不允许其他属性。

ProgressBegin

开始一份报告,用操作自身的术语说明已开始的内容。

属性类型必需描述
kindconst “begin”是将此负载标记为报告的开始。常量:"begin"
titlestring是已开始的内容。

不允许其他属性。

ProgressReport

操作对自身情况的一行陈述。它不携带完成比例:在此报告的操作处理的是一个在工作开始时大小未知的集合,因此比例只能是凭空编造的。

属性类型必需描述
kindconst “report”是将此负载标记为进行中报告的一行。常量:"report"
messagestring是操作自身输出的一行,已去除首尾空白。

不允许其他属性。

ProgressEnd

结束一份报告。除类型外它不携带任何内容,因为结果通过调用方已在等待的响应传递。

属性类型必需描述
kindconst “end”是将此负载标记为报告的结束。常量:"end"

不允许其他属性。

PublishDiagnosticsParams

一个文件的检查结果,当某次验证针对请求所指定文档以外的文档产生结果时,由守护进程推送。

属性类型必需描述
filestring是检查结果所涉及的文件。
diagnosticsDiagnostic[] 或 null是检查结果,按产生的顺序排列。

不允许其他属性。

SuccessResponse

对成功请求的答复,携带其所答复请求的标识符。响应不携带 method,因此适用哪种结果结构由该标识符所属的请求决定,而不是由响应本身的任何内容决定。

属性类型必需描述
jsonrpcProtocolVersion是每条消息携带的 JSON-RPC 版本。仅支持 2.0。
idRequestId是调用方为请求指定的标识符,会在答复该请求的响应中原样返回。不携带标识符的消息是通知,永远不会得到答复。
resultInitializeResult 或 ValidateResult 或 InvalidateResult 或 DiagnosticsResult 或 IrGraphResult 或 BuildResult 或 BuildPreviewResult 或 EntityDefinitionResult 或 ReleaseClosureResult 或 ResolveDependenciesResult 或 PinResult 或 CacheStatusResult 或 CachePruneResult 或 CacheEvictResult 或 CacheClearResult 或 RegistryListResult 或 SearchResult 或 RegistryAddResult 或 RegistryRemoveResult 或 RegistryUpdateResult 或 LogoutResult 或 PublishEntityResult 或 PublishArtifactResult 或 SignArtifactsResult 或 DeprecateArtifactResult 或 ResolveResult 或 FindReferencesResult 或 FindImplementationsResult 或 HoverResult 或 CompletionResult 或 CatalogIndexResult 或 AttachCandidatesResult 或 ConnectionCandidatesResult 或 InsertionPointResult 或 AttachmentContainerResult 或 ConnectionAtPositionResult 或 ReleaseCandidatesResult 或 ActiveReleaseResult 或 EditDocumentResult 或 EffectiveConfigurationResult 或 ConfigInitResult 或 ConfigCaptureResult 或 ImportResult 或 ScaffoldEntityResult 或 LintResult 或 PluginAddResult 或 PluginRemoveResult 或 PluginSyncResult 或 PluginGenCatalogResult 或 ExplainErrorResult 或 GetSchemaResult 或 SkillsInstallResult 或 SkillsListResult是答复内容,其结构为所请求方法返回的结构。

不允许其他属性。

ErrorResponse

对被拒绝或失败的请求的应答,携带其所应答请求的标识符。

属性类型必需描述
jsonrpcProtocolVersion是每条消息携带的 JSON-RPC 版本。仅支持 2.0。
idRequestId是调用方为请求指定的标识符,会在答复该请求的响应中原样返回。不携带标识符的消息是通知,永远不会得到答复。
errorErrorObject是出了什么问题:一个客户端可据以分支处理的代码,一条供人阅读的消息,以及——在该情况有相关内容时——消息所指的工件和源位置。

不允许其他属性。

ErrorObject

出了什么问题:一个客户端可据以分支处理的代码,一条供人阅读的消息,以及——在该情况有相关内容时——消息所指的工件和源位置。

属性类型必需描述
codeErrorCode是应答所报告的情况。负数代码是协议自身的保留集;四位数代码是此守护进程引发的情况,每个都指明一种客户端可以采取行动的状态。该集合是封闭的。
messagestring是以文字描述出了什么问题。它与报告同一情况的其他所有界面上的措辞相同。
dataErrorData否消息所指的工件和源位置,以结构化方式携带,客户端无需再从文字中解析出来。每个字段都是可选的,一种情况只填充它手头已有的内容;没有字段替代另一个字段,因此客户端从它读取的字段得知收到了什么,而不是从旁边的代码推断。

不允许其他属性。

ErrorCode

应答所报告的情况。负数代码是协议自身的保留集;四位数代码是此守护进程引发的情况,每个都指明一种客户端可以采取行动的状态。该集合是封闭的。

类型: const -32700 or const -32600 or const -32601 or const -32602 or const -32603 or const 1001 or const 1003 or const 1004 or const 1005 or const 1006

允许的值:

  • -32700 — 消息无法解析为 JSON。
  • -32600 — 消息已解析,但不是格式正确的请求。
  • -32601 — 不存在该名称的方法。
  • -32602 — 请求携带的 params 不可接受:方法不接受的字段、类型错误的字段,或方法拒绝的值。
  • -32603 — 守护进程在执行工作时失败。
  • 1001 — 守护进程未持有该文件的读取结果,也没有正在生成。客户端通过请求一次验证来生成它,然后重试。
  • 1003 — 请求所指定 Release 的锁文件不存在,而该操作需要锁文件。
  • 1004 — 无法从目录或请求所指定的 Release 中解析请求所指定的实体。
  • 1005 — 守护进程正在关闭,拒绝新的工作。客户端不会针对同一守护进程重试。
  • 1006 — 该文件的验证当前正在运行,且未能在等待中的请求所允许的时限内完成。客户端等待后再次请求,期间不发送任何内容。

ErrorData

消息所指的工件和源位置,以结构化方式携带,客户端无需再从文字中解析出来。每个字段都是可选的,一种情况只填充它手头已有的内容;没有字段替代另一个字段,因此客户端从它读取的字段得知收到了什么,而不是从旁边的代码推断。

属性类型必需描述
filestring否位置字段所定位的源文档——正在检查的文档,或加载失败的 Release。
lineinteger否该情况所指的行,从 1 开始计数。
columninteger否该情况所指的列,从 1 开始计数。
end_lineinteger否该情况所指词元末尾之后一位的行。当词元没有可恢复的末尾时省略,此时客户端将该位置呈现为一个点。
end_columninteger否该情况所指词元末尾之后一位的列。
releasestring否该情况所指的 Release,写法与请求中命名它的方式相同,因此客户端无需重新拼装即可组成补救措施。
lockfilestring否与锁文件相关的情况所涉及的锁文件:查找后未找到或无法读取的路径。
unreachable布尔值否该拒绝是否是因为请求所指定的注册表无法访问:其名称无法解析,与它的连接被拒绝或无法打开,或无法与它建立安全连接。它从失败本身读取,而不是从消息读取,并且仅在失败表明从未访问到该注册表时才设置。一次指定某个注册表而被拒绝的索引刷新会携带它;一个作出了应答的注册表,无论应答了什么,都不会设置它。
codestring否该拒绝所指情况的描述性名称,跨版本保持稳定:与报告该情况的诊断在其自身代码中携带的值相同。客户端应据此分支处理,而不是依据消息或旁边的数字代码——数字代码表示请求的状态,对每种情况都保持不变。当且仅当该拒绝指明一个已注册的情况时存在,未指明时省略。
shortCodestring否该情况的短代码,即字母 E 加四位数字:读者引用和查找时使用的形式,也是指明某一情况的拒绝消息开头的形式。当且仅当 code 存在时存在。

不允许其他属性。

Diagnostic

关于一个文档的一条发现:它在哪里、有多严重、说了什么,以及指明其所报告情况的可引用代码。

属性类型必需描述
lineinteger是该发现所涉及的行,从 1 开始计数。
columninteger是该发现所涉及的列,从 1 开始计数。
severityconst “error” 或 const “warning” 或 const “info”是发现项的严重程度。允许的值:"error" — 该发现项是一个故障。严重级别为 halt 的插件发现项按此级别报告。"warning" — 该发现项会被报告,但不是故障。严重级别为 warn 的插件发现项按此级别报告。"info" — 该发现项是信息,严重级别为 info 的插件发现项即属此类。
messagestring是以文字描述该发现的内容。
codestring否该情况的描述性名称,跨版本保持稳定,可在抑制中引用。
shortCodestring否该情况的短代码,即中止型诊断开头的形式。
codeDescriptionCodeDescription否该发现所指情况的说明所在之处。
classificationstring否该发现是如何得出的,在该情况对此有所区分时提供。
suggeststring否该发现建议的写法,在该情况能给出时提供——例如标识符的近似拼写。
keyPathstring否文档中通往该发现所涉及键的路径。
sourcestring是产生该发现的来源。
end_lineinteger否该发现所涉及词元末尾之后一位的行,使客户端可以呈现整个词元而不是单个字符。对于跨越多行的词元省略。
end_columninteger否该发现所涉及词元末尾之后一位的列。

不允许其他属性。

CodeDescription

该发现所指情况的说明所在之处。

属性类型必需描述
hrefstring是说明该情况的已发布地址。

不允许其他属性。

Position

文档中的一个位置:一行以及该行内的字符偏移量,均从 0 开始计数。偏移量以会话打开时商定的编码单位计量,除非客户端请求其他编码,否则为 UTF-16。

属性类型必需描述
lineinteger是行,从 0 开始计数。
characterinteger是行内偏移量,从 0 开始计数,以会话商定的编码单位计量。

不允许其他属性。

Range

文档中两个位置之间的跨度。

属性类型必需描述
startPosition是文档中的一个位置:一行以及该行内的字符偏移量,均从 0 开始计数。偏移量以会话打开时商定的编码单位计量,除非客户端请求其他编码,否则为 UTF-16。
endPosition是文档中的一个位置:一行以及该行内的字符偏移量,均从 0 开始计数。偏移量以会话打开时商定的编码单位计量,除非客户端请求其他编码,否则为 UTF-16。

不允许其他属性。

Location

指定文档中的一个跨度。

属性类型必需描述
uristring是跨度所在的文档,以 URI 寻址。
rangeRange是文档中两个位置之间的跨度。

不允许其他属性。

WorkspaceAndProgressParams

未声明自身字段的方法的 params 对象。它仍接受每个请求都接受的两个字段:其作用的工作区,以及一个进度令牌。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。

不允许其他属性。

InitializeParams

在某个工作区上打开会话,并声明客户端能够处理的内容。这是唯一一个 workspaceRoot 作为声明而非请求对象的方法:缺省、空值和路径是三种不同的情况,未提供路径而打开的会话,是客户端尚未指向任何工作区的会话。

属性类型必需描述
capabilitiesClientCapabilities否客户端能够处理的内容。未声明的视为不支持。未知成员会被忽略而非拒绝,因此客户端可以声明此守护进程尚未读取的能力。
workspaceRootstring否要打开的工作区的绝对路径。缺省时会话没有工作区;空字符串是客户端提供的路径,与不发送路径不同。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。

不允许其他属性。

ClientCapabilities

客户端能够处理的内容。未声明的视为不支持。未知成员会被忽略而非拒绝,因此客户端可以声明此守护进程尚未读取的能力。

属性类型必需描述
generalobject否不与某一类应答绑定的能力。
windowobject否关于客户端在工作进行期间能够显示哪些内容的能力。

允许其他属性。

ClientCapabilities.general

不与某一类应答绑定的能力。

属性类型必需描述
positionEncodingsstring[]否客户端能够读取的位置编码,按优先顺序排列。

允许其他属性。

ClientCapabilities.window

关于客户端在工作进行期间能够显示哪些内容的能力。

属性类型必需描述
workDoneProgress布尔值否客户端是否能够接收进度通知。在未声明此项的会话中生成进度令牌的请求会被拒绝。

允许其他属性。

ValidateParams

检查工作区或其中的某个文档,并以检查结果作答。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
filestring否要检查的文档。缺省时检查工作区中的所有内容。
contentstring否客户端当前持有的文档文本,用于检查尚未保存的缓冲区。缺省时读取磁盘上的字节。
releasestring否作为检查依据的 Release,以相对于工作区根目录的路径表示。

不允许其他属性。

InvalidateParams

告知守护进程其已读取的某个文档已发生变更,使关于该文档的下一次应答基于新的字节计算。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
filestring否发生变更的文档。
granularitystring否要丢弃守护进程所持内容的范围:file 仅丢弃其为指定文档持有的内容;workspace 是默认值,任何其他值也都按它理解,它还会丢弃其为整个工作区持有的内容。

不允许其他属性。

DiagnosticsParams

以守护进程已为某个文档持有的检查结果作答,不再重新检查。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
filestring否要报告的文档。守护进程必须已读取过该文档。

不允许其他属性。

IrGraphParams

以 Release 编译得到的已解析图作答,不进行渲染。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
releasestring否要解析的 Release,以相对于工作区根目录的路径表示。绝对路径会被拒绝。
unredacted布尔值否是否以明文形式返回作者声明为敏感的值。缺省或为 false 时,每个此类值都会从图中隐去,并以一个说明原因的标记代替,与命令行的图输出隐去它们的方式相同;为 true 时按 Release 编译所得的图作答,包括这些值。

不允许其他属性。

BuildParams

编译一个 Release,并将渲染出的制品写入工作区。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
releasestring否要构建的 Release,以相对于工作区根目录的路径表示。绝对路径会被拒绝。
outputParentstring否在其中创建输出目录的目录,以相对于工作区根目录的路径表示。制品落在其下的输出目录中,布局与未指定任何目录时在工作区根目录下的布局相同——因此此项指定的是输出目录的父目录,而绝不是输出目录本身。缺省或为空时,输出目录写在工作区根目录下,与 aggrega build 无论从何处运行时的行为相同。绝对路径或越出工作区的路径会被拒绝。
autoPull布尔值否是否先解析该 Release 的依赖。请求此项会访问已配置的注册表并写入锁文件;未请求时,构建不会访问任何注册表。
policyInputstring否用于在产物旁写入每个治理角色交给附加在该处的插件的有效载荷的目录,以相对于工作区根目录的路径表示——即 aggrega build --policy-input 写入的文件,名称相同,无论构建完成还是中止都会写入。应答中的通知会说明写入了多少个文件,并指出每个未写入文件的角色。请求失败时,已写入的文件保留在磁盘上,而这份说明不会出现在回复中:错误只携带拒绝信息。不指定时不写入任何文件。绝对路径或越出工作区的路径会被拒绝。

不允许其他属性。

BuildPreviewParams

编译一个 Release,并报告写入产物将会产生的结果,但不写入其中任何一个。它拒绝接受写入式构建所接受的依赖解析字段,因为不写入任何内容的请求无法填充锁文件。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
releasestring否要编译的 Release,以相对于工作区根目录的路径表示。
autoPull布尔值否在线路协议上被接受,但被该方法拒绝:此请求不写入任何内容,因此无法在填充锁文件的同时保持其声称的行为。
policyInputstring否用于写入每个治理角色交给附加在该处的插件的有效载荷的目录,以相对于工作区根目录的路径表示——即 aggrega build --dry-run --policy-input 写入的文件,名称相同。若指定,这些文件是该请求唯一写入的内容;输出目录和锁文件保持不变。应答中的通知会说明写入了多少个文件,并指出每个未写入文件的角色。请求失败时,已写入的文件保留在磁盘上,而这份说明不会出现在回复中:错误只携带拒绝信息。绝对路径或越出工作区的路径会被拒绝。

不允许其他属性。

EntityDefinitionParams

返回一个实体名称解析到的内容,以及定义它的文档所在的位置。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
namestring否要解析的实体,按名称指定——或者使用注册表引用 oci://<host>/<repository>:<tag>(也可用 @<digest> 代替 :<tag>),以读取在该坐标发布的实体。
releasestring否在其语境下解析该名称的 Release,以相对于工作区根目录的路径表示。此时名称通过工作区配置为该 Release 指定的目录目录进行解析,因此对于一个工作区中由多个变体(每个 Release 一个)声明的名称,会解析为该 Release 构建时使用的变体;若名称无法解析,则请求被拒绝,并附带说明,指出该 Release 在 workspace.releases 下的条目。省略时,名称在工作区自身的目录目录中解析。注册表引用不接受 Release,附带 Release 时会被拒绝;未指向任何 Release 文件的值同样会被拒绝。

不允许其他属性。

CatalogIndexParams

返回工作区包含的实体:其文档声明的每个实体,以及其目录目录声明的 Features。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
releasestring否在其语境下列出实体的 Release,以相对于工作区根目录的路径表示。此时 Features 为工作区配置为该 Release 指定的目录目录所声明的那些,仅由其他 Releases 读取的目录目录下的文档会被排除,因此对于并排保存同一实体多个变体(每个 Release 一个)的工作区,列出的是该 Release 构建时使用的变体。省略时,列出的是工作区自身的内容。未指向任何 Release 文件的值会被拒绝。

不允许其他属性。

ReleaseClosureParams

返回一个 Release 所依赖的全部内容,即解析所触及的范围。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
releasestring否要检查的 Release,以相对于工作区根目录的路径表示。

不允许其他属性。

ResolveDependenciesParams

解析一个 Release 的依赖,将其固定在锁文件中,并获取其渲染所需的外部输入。它会访问已配置的注册表,并执行写入。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
releasestring否要解析的 Release,以相对于工作区根目录的路径表示。
upgrade布尔值否是否在声明的范围内重新解析,而不沿用锁文件中已固定的版本。
targetsstring[]否要重新解析的引用,其余引用保持现有固定状态。为空时解析全部内容。
verify布尔值否是否将已记录的锁文件与此请求在没有锁文件时将执行的解析进行比较(沿用该请求会沿用的固定项),而不是写入锁文件。验证不写入锁文件、插件信任记录或 entity.lock;内容缓存按该解析的方式被读取和填充。存在偏差或缺少锁文件时,请求失败。它不能与 upgrade、targets 或 pinSources 组合使用,无论 pinSources 取何值:同时发送其中任一项的请求会在解析任何内容之前作为无效参数被拒绝。
pinSources布尔值否是否对该 Release 从工作区目录目录构建所用的 Recipes 和 FeatureRecipes 运行 aggrega/pin 所执行的固定步骤,在每个实体旁写入 entity.lock,而不是在某个实体的锁未记录输入所需的固定项时拒绝请求。省略时遵循工作区的 pin_sources_at_pull;任一取值都会针对此请求覆盖该设置。

不允许其他属性。

PinParams

在 Recipe 或 FeatureRecipe 旁的 entity.lock 中,为该实体从其自身文档之外读取的每个输入记录内容固定项。此请求不指定 Release:实体完整写出其标识的输入,对于使用该实体的每个 Release 都指向同一个产物,因此固定它不需要任何 Release 提供的内容。它会访问实体的来源所指定的主机,并在实体旁写入;实体文档本身永远不会被写入。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
entitystring否要固定的实体文档,以相对于工作区根目录的路径表示。
dryRun布尔值否是否返回该步骤将写入的锁,而不实际写入。输入仍会被解析,因此内容缓存仍会被填充。

不允许其他属性。

CacheEvictParams

回收缓存内容,直到剩余内容不超过请求指定的大小。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
maxSizestring否回收后要降至的大小,按人们通常的写法书写,例如 500MB。

不允许其他属性。

SearchParams

搜索已配置注册表的本地索引所提供的内容。它读取磁盘上已有的索引,不联系任何注册表。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
querystring否与记录的名称和描述进行匹配的文本。
kindsstring[]否要保留的实体种类。为空时保留所有种类。
selectorstring否保留的记录必须满足的标签选择器。
capabilitiesstring[]否保留的插件记录必须声明的能力。
pluginTypestring否要保留的插件类型。
registrystring否要搜索的单个注册表主机。省略时搜索所有已配置的主机。
limitinteger否返回记录的最大数量。
includeRetracted布尔值否是否保留已被已发布标记弃用的版本。

不允许其他属性。

RegistryAddParams

注册一个注册表,以及解析对其所提供内容应用的信任策略。除非请求另有要求,它会写入全机配置文件,因此该机器上的每个工作区都会通过该条目进行解析。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
hoststring否要注册的注册表主机。
namestring否解析到该主机的友好别名。
identitiesstring[]否对此注册表所提供内容受信任的签名身份。
keyPathstring否要信任的公钥路径,适用于使用公钥而非无密钥身份签名的注册表。
trustedRootstring否用于验证签名的信任锚路径。
requireSignatures布尔值否来自此注册表的产物是否必须带有经过验证的签名。省略时不作声明,保留解析得到的默认值。
advisory布尔值否验证失败时是否仅报告而不中止。
fetchTrust布尔值否是否读取注册表公布的信任策略并将其固定。省略时不作声明,保留解析得到的默认值。
global布尔值否写入全机配置文件,这是此方法自身的默认行为。
workspace布尔值否写入此工作区自身的配置文件,而不是全机配置文件。

不允许其他属性。

RegistryRemoveParams

移除一个已注册的注册表。除非请求另有要求,它会写入全机配置文件。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
registrystring否要移除的注册表,按主机或别名指定。
global布尔值否写入全机配置文件,这是此方法自身的默认行为。
workspace布尔值否写入此工作区自身的配置文件,而不是全机配置文件。

不允许其他属性。

RegistryUpdateParams

刷新搜索所读取的本地索引,为此会访问注册表。它写入的是此工作区自身配置的缓存目录下的索引。如果注册表需要的凭据不由任何环境来源提供,请求会被拒绝并指明该凭据,而不会提示输入。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
registrystring否要刷新的单个注册表。省略时刷新所有已配置的主机。
upgrade布尔值否是否重建索引,而不是在其已有内容上追加。

不允许其他属性。

LogoutParams

删除已存储的注册表凭据。该存储由本机上的所有项目共享,响应中会说明这一点。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
registrystring否要删除其已存储凭据的注册表。

不允许其他属性。

PublishEntityParams

将实体发布到注册表。它所发布的内容就是该注册表的每个使用者解析到的内容,并且已发布的版本无法从已获取它的任何人那里撤回。不会进行任何提示:身份从请求提供的内容或环境中已有的内容解析。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
entitystring否要发布的实体文档,以相对于工作区根目录的路径表示。
registrystring否要发布到的注册表。省略时使用配置的默认值。
dryRun布尔值否是否只报告发布将会落地的内容而不实际发布。
sign布尔值否是否对发布的内容签名。省略时不作任何声明,保留解析得到的默认值。
pluginstring否随 Plugin 实体一同发布的插件模块。
fulcioUrlstring否用于获取签名证书的证书颁发机构。
rekorUrlstring否用于记录签名的透明度日志。
timestampUrlstring否用于副署的时间戳颁发机构。
identityTokenstring否用于签名的身份令牌,由调用方提供,而不是在终端中获取。
pinSources布尔值否是否在打包实体之前对其运行 aggrega/pin 所运行的固定步骤,使该步骤在实体旁写入的 entity.lock 成为发布内容的一部分。该步骤在所有评判该实体的拒绝检查之前运行;在 dryRun 下,它报告将要写入的锁文件而不写入任何内容。省略时遵循工作区的 pin_sources_at_push;任一取值都会在本次请求中覆盖该设置。

不允许其他属性。

PublishArtifactParams

将任意文件以请求指定的名称和标签发布到注册表。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
filestring否要发布的文件,以相对于工作区根目录的路径表示。
namestring否发布所用的仓库名称。
tagstring否发布所用的标签。
mediaTypestring否为发布的字节记录的媒体类型。
registrystring否要发布到的注册表。省略时使用配置的默认值。
dryRun布尔值否是否只报告发布将会落地的内容而不实际发布。

不允许其他属性。

SignArtifactsParams

对已发布的内容签名。签名无法从已获取它的任何人那里撤回。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
referencesstring[]否要签名的已发布引用。
fulcioUrlstring否用于获取签名证书的证书颁发机构。
rekorUrlstring否用于记录签名的透明度日志。
timestampUrlstring否用于副署的时间戳颁发机构。
identityTokenstring否用于签名的身份令牌,由调用方提供,而不是在终端中获取。
jobsinteger否同时签名的引用数量。不指定时逐个签名。每个引用的签名方式仍与单独签名时完全相同——无密钥签名时,各自使用自己的证书和自己的透明日志条目——应答保持引用给出时的顺序。最小值:1。

不允许其他属性。

DeprecateArtifactParams

将已发布的版本标记为已弃用,使解析可以报告或拒绝该版本。该标记本身也会被发布并签名。请求要么发送一个引用及其内容,要么发送一个批处理文件,其中各条目携带各自的内容——两者绝不同时发送,也绝不在批处理文件之外附带内容。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
referencestring否要标记的已发布引用。是 from 的替代方式:同时携带两者的请求会被拒绝。
severityconst “warning” 或 const “error” 或 const “retracted”否标记的强度——解析是报告该版本还是拒绝它。与 reference 一起时为必填;与 from 同时出现时会被拒绝,后者的批处理文件携带每个标记各自的强度。允许的值:"warning" — 已弃用,处于两个建议级别中较弱的一级:选择版本时仍会被选中。"error" — 已弃用,处于两个建议级别中较强的一级:选择版本时仍会被选中。"retracted" — 已撤回:选择版本时会被排除。
reasonstring否该版本被弃用的原因。与 reference 一起时为必填;与 from 同时出现时会被拒绝,后者的批处理文件携带每个标记各自的原因。
replacementstring否改用的引用。与 from 同时出现时会被拒绝,后者的批处理文件携带每个标记各自的替代引用。
messagestring否遇到该标记的使用者会收到的提示信息。与 from 同时出现时会被拒绝,后者的批处理文件携带每个标记各自的提示信息。
fromstring否由撤回条目组成的批处理文件,以相对于工作区根目录的路径表示,每个条目附加一个标记。每个条目携带各自的引用、严重级别和原因,并可选地携带替代引用和提示信息。是 reference 的替代方式:同时携带两者的请求,或在它之外还携带严重级别、原因、替代引用或提示信息的请求,会被拒绝。
fulcioUrlstring否用于获取签名证书的证书颁发机构。
rekorUrlstring否用于记录签名的透明度日志。
timestampUrlstring否用于副署的时间戳颁发机构。
identityTokenstring否用于签名的身份令牌,由调用方提供,而不是在终端中获取。

不允许其他属性。

ResolveParams

回答光标下的对象在何处定义。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
uristring否光标所在的文档。
positionPosition否文档中的一个位置:一行以及该行内的字符偏移量,均从 0 开始计数。偏移量以会话打开时商定的编码单位计量,除非客户端请求其他编码,否则为 UTF-16。
releasestring否作为回答依据的 Release,以相对于工作区根目录的路径表示。此时,定义即为该引用通过工作区配置为该 Release 指定的目录目录(按其顺序)解析到的文档,因此,若同一工作区中的多个变体(每个 Release 一个)声明了同一名称,则会定位到该 Release 的变体;若这些目录中没有声明此类实体,则搜索工作区的文档,但排除位于该 Release 不读取的工作区目录目录下的文档。省略时,先搜索工作区的文档,仅当没有文档声明该名称时才搜索工作区自身的目录目录。若值未指向任何 Release 文件,则请求会被拒绝。

不允许其他属性。

FindReferencesParams

回答光标下的对象在何处被引用。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
uristring否光标所在的文档。
positionPosition否文档中的一个位置:一行以及该行内的字符偏移量,均从 0 开始计数。偏移量以会话打开时商定的编码单位计量,除非客户端请求其他编码,否则为 UTF-16。
releasestring否作为回答依据的 Release,以相对于工作区根目录的路径表示。此时,位于该 Release 不读取的工作区目录目录下的文档中的引用不会被报告,因此工作区中并存的各个变体(每个 Release 一个)绝不会被报告为彼此的引用。省略时,搜索所有工作区文档。若值未指向任何 Release 文件,则请求会被拒绝。

不允许其他属性。

FindImplementationsParams

回答哪些文档实现了光标下的对象。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
uristring否光标所在的文档。
positionPosition否文档中的一个位置:一行以及该行内的字符偏移量,均从 0 开始计数。偏移量以会话打开时商定的编码单位计量,除非客户端请求其他编码,否则为 UTF-16。
releasestring否作为回答依据的 Release,以相对于工作区根目录的路径表示。此时,位于该 Release 不读取的工作区目录目录下的文档不会被报告,因此另一个 Release 构建所用的变体绝不会列在本 Release 的实现中。省略时,搜索所有工作区文档。若值未指向任何 Release 文件,则请求会被拒绝。

不允许其他属性。

HoverParams

回答关于光标下的对象应显示的内容。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
uristring否光标所在的文档。
positionPosition否文档中的一个位置:一行以及该行内的字符偏移量,均从 0 开始计数。偏移量以会话打开时商定的编码单位计量,除非客户端请求其他编码,否则为 UTF-16。
releasestring否作为回答依据的 Release,以相对于工作区根目录的路径表示。此时,显示的实体即为该引用通过工作区配置为该 Release 指定的目录目录(按其顺序)解析到的实体;若这些目录中没有声明此类实体,则搜索工作区的文档,但排除位于该 Release 不读取的工作区目录目录下的文档。省略时,先搜索工作区的文档,仅当没有文档声明该名称时才搜索工作区自身的目录目录。若值未指向任何 Release 文件,则请求会被拒绝。

不允许其他属性。

CompletionParams

回答光标处可以写入的内容。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
uristring否光标所在的文档。
positionPosition否文档中的一个位置:一行以及该行内的字符偏移量,均从 0 开始计数。偏移量以会话打开时商定的编码单位计量,除非客户端请求其他编码,否则为 UTF-16。
contextCompletionContext否触发该请求的原因(若客户端有跟踪)。
releasestring否作为回答依据的 Release,以相对于工作区根目录的路径表示。此时,提供的名称为工作区文档所声明的名称(排除位于该 Release 不读取的工作区目录目录下的文档),以及工作区配置为该 Release 指定的目录目录所声明的 Components 和 Features。省略时,提供的名称来自工作区的文档,以及工作区自身的目录目录所声明的 Components 和 Features。若值未指向任何 Release 文件,则请求会被拒绝。

不允许其他属性。

CompletionContext

触发该请求的原因(若客户端有跟踪)。

属性类型必需描述
triggerKindinteger否请求补全的原因。
triggerCharacterstring否触发补全的字符(若由字符触发)。

允许其他属性。

AttachCandidatesParams

回答哪些 Features 可以附加到某个实体(依据该实体的标签判断),以及对于图节点的组件所绘制的某条连接,哪些可以填充该连接的套接字所声明的每个槽位。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
nodestring否用于判断候选项的实体,按名称指定,从工作区文档的声明中读取。
graphNodestring否用于判断候选项的图节点,其标签是构建本身用来评估适用性的最终标签集。基于它计算出的回答反映构建实际会做的事情。
releasestring否该节点所属图对应的 Release,以相对于工作区根目录的路径表示。此时按该 Release 的视角选取候选项:工作区配置为该 Release 指定的目录目录中所声明的 Features,以及工作区的文档(排除位于该 Release 不读取的工作区目录目录下的文档),因此为另一个 Release 保留的 Feature 永远不会被提供给本 Release 图中的节点。
labelsmap of string否直接用于判断的标签,代替从实体或图节点中读取标签。
connectionConnectionCoordinate否由 graphNode 所指节点的组件绘制的一条连接,在回答该节点的同时也对其作答:此时回答还会携带 slots,即该连接的套接字声明的每个槽位及可填充它的 Features,或在没有槽位可填充时携带 noSlotReason。它只能与 graphNode 和 release 一起发送,因为连接只存在于已编译的图上;与 node 或 labels 一起发送会被拒绝。旁边的候选项保持原有含义,即可以附加到节点本身的 Features。其 document 会被接受,但不会改变该回答:槽位属于套接字,候选项属于 Features,无论附件写在哪个文档中都相同。

不允许其他属性。

ConnectionCandidatesParams

回答某个实体上的套接字可以连接到哪些实体。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
nodestring否被查询其套接字的实体。
socketstring否要回答的单个套接字。省略时对该实体声明的每个套接字作答。

不允许其他属性。

InsertionPointParams

回答某个命名容器下的新条目应位于文档中的哪个位置,条目的编写和应用留给拥有该缓冲区的调用方。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
filestring否要查询的文档。
containerstring[]否在文档中通往该条目所属容器的路径。

不允许其他属性。

AttachmentContainerParams

回答图节点上的附件,或该节点的组件所绘制的某条连接上的附件,应位于哪个文档以及文档中的哪个位置。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
graphNodestring否附件所针对的图节点。
releasestring否该节点所属图对应的 Release,以相对于工作区根目录的路径表示。
connectionConnectionCoordinate否图节点的组件所绘制的一条连接,用于附件针对该连接而非节点的情况:此时回答会指出该连接自身的 features 容器,位于其 document 字段所指的文档中,此处该字段为必需。在 Aggregate 中,它是该连接在编写该节点的文档中的条目;对于由 Release 绘制的连接会被拒绝,因为 Aggregate 中没有其条目。在 Release 中,它是该 Release 自身为该节点所写条目下的逐边条目,无论该 Release 是否已为该连接编写条目;若该 Release 未为该节点编写条目则会被拒绝。由 Feature 绘制的连接在两种文档中都会被拒绝,因为附件只写在由组件或 Release 绘制的连接上。

不允许其他属性。

ConnectionAtPositionParams

回答 Aggregate 或 Release 中的某个位置落在哪条连接的条目内:按候选项请求和容器请求所采用的形式给出图节点和连接,或说明该处为何没有写连接。这些条目就是编写附件的条目——组件用来绘制连接的条目(位于连接的别名下,在编写该组件的文档中),以及 Release 编写的每个逐边条目——各自以已编译图中记录的位置为准,因此某个键是否为连接从不根据其名称判断。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
filestring否该位置所在的文档:Release,或该 Release 的图记录为组件编写来源的文档——其 Aggregate,或该 Aggregate 导入的模块的文档。优先读取会话为其保存的内容,否则从磁盘读取。
positionPosition否文档中的一个位置:一行以及该行内的字符偏移量,均从 0 开始计数。偏移量以会话打开时商定的编码单位计量,除非客户端请求其他编码,否则为 UTF-16。
releasestring否其已编译图记录这些连接的 Release,以相对于工作区根目录的路径表示。对于 Aggregate 中的位置也是必需的,因为图节点和连接只存在于已编译的图上。

不允许其他属性。

ConnectionCoordinate

图节点的 component 所绘制的一条连接,通过其接线所经的 socket、它在该 socket 中携带的别名,以及写入其上附件的文档来定位。一条连接携带填充其 socket 所声明槽位的附件,Aggregate 或 Release 都可以写入这些附件。

属性类型必需描述
socketstring是该连接接线所经的依赖 socket。
aliasstring是该连接在其 socket 内携带的名称。
documentconst “aggregate” 或 const “release”否写入该连接上附件的文档。该集合是封闭的,集合以外的值会被拒绝。允许的值:"aggregate" — Aggregate,开发者在其中于连接的条目上编写附件。"release" — Release,运维人员在其中于该连接的逐边条目上编写附件。

允许其他属性。

SetActiveReleaseParams

通过在 .aggrega 目录中写入一个标记,将某个 Release 记录为工作区的默认值:aggrega/activeRelease 报告的选择会在配置的创作 Release 之后读取该标记。该标记只写入工作区内部,不会写到其他任何地方:如果 .aggrega 目录或该标记是一个指向工作区之外的链接,无论其指向的位置是否已存在,写入都会被拒绝并指明该链接,且不写入任何内容。返回的结果与写入标记后 aggrega/activeRelease 给出的结果相同,因此当配置的创作 Release 优先于该标记时,结果会指明另一个 Release。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
releasestring否要记录的 Release,以相对于工作区根目录的路径表示。绝对路径以及向上越出工作区的路径会被拒绝;通过链接指向工作区之外的路径同样会被拒绝,除非工作区配置指明了该 Release。

不允许其他属性。

EditDocumentParams

对工作区中的某个文档应用一次有界编辑:在一个容器下添加一个条目,或设置一个标量。组合后的文档会根据其类型的 schema 进行校验,只有校验通过才会写入磁盘,因此该方法无法写入创作 schema 所拒绝的内容。被拒绝的编辑会使文件逐字节保持原样。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
filestring否要编辑的文档。
editconst “add-component” 或 const “attach-feature” 或 const “wire-edge” 或 const “set-value”否要应用的编辑。允许的值:"add-component" — 在 components 容器下添加一个组件实例:name 是实例名称,value 是其请求的 Component。"attach-feature" — 将一个 Feature 附加到请求所指定的节点:name 是附件的实例名称,value 是其请求的 Feature。"wire-edge" — 在 socket 内从请求所指定的节点连接一条依赖连接:name 是用于寻址该连接的别名,value 是其指向的节点。"set-value" — 在请求所指定的节点上设置一个值:name 是值的键,value 是一个标量。
nodestring[]否文档中通往被编辑条目的路径。
socketstring否该编辑所涉及的 socket,适用于对 socket 进行接线的编辑。
namestring否该编辑写入的名称。
valueany否该编辑写入的值,形式取决于编辑本身。
dryRun布尔值否是否返回组合后的文档而不是写入它。

不允许其他属性。

ConfigInitParams

初始化一个配置文档。默认写入全机范围的文件,因为 registry 及其上受信任的身份属于全机范围的工具配置。它会访问指定的 registry 以读取其公布的信任策略;未公布任何策略的 registry 会被如实报告,初始化继续进行:对官方 hub 使用内置基线,对其他 registry 则不使用任何策略。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
registrystring否要为其初始化配置的 registry。
force布尔值否是否覆盖已存在的配置文档。
global布尔值否写入全机配置文件,这是此方法自身的默认行为。
workspace布尔值否写入此工作区自身的配置文件,而不是全机配置文件。
dryRun布尔值否是否返回文档内容而不是写入它,适用于维护自己文档模型的客户端。

不允许其他属性。

ConfigCaptureParams

将解析后的配置固化到该工作区自己的文档中,使工作区自成一体。它始终写入该工作区的文件,且不访问工作区之外的任何内容。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
allPlugins布尔值否是否固化所有已挂载的插件,而不仅是工作区自身配置的插件。

不允许其他属性。

ImportParams

将外部源描述转换为草稿编写文档,并在其旁写入 .aggrega-import.json,即记录此次导入所写内容的文件——给定的目标(如有给定)、读取的目录快照(如有读取)、每个草稿文件,以及草稿 Aggregate 或 Release 在各层级的每个键——供之后的同步读取。无法完全转换的源会得到一个应答而非失败:已生成的草稿会被写入,发现项说明无法转换的内容——但同步模式除外,转换中止时同步不写入任何内容。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
sourcestring否要转换的文件或目录,可为绝对路径或相对于工作区根目录的路径;未提供该字段的请求会被拒绝。它在原处读取,无论是否位于工作区内;对于目录,会读取其中由导入器声明的文件模式所选中的文件。
outputDirstring否工作区下用于写入草稿的目录,相对于工作区根目录;绝对值,或按字面或通过链接指向工作区之外的值,会被拒绝。未提供时写入工作区根目录下,与在终端运行同一转换且未指定目标位置时的写入位置相同。每个草稿路径都相对于应答中作为 outputDir 给出的目录,在 dryRun 下也是如此。
formatstring否源格式。未提供时由转换自行确定。
targetstring否一种 provider 能力,例如 compose 或 helm——即 Recipe 的 spec.capability 所绑定的词——用于在草稿旁起草一个 Manifest,即 manifest.yaml:草稿所需的每个组件类型和功能类型(包括草稿 Aggregate 所组合的目录 Aggregate 的类型)都会映射到工作区目录为其提供的该能力的 Recipe 或功能配方——只有一个时即为该项,有多个时则为以该类型命名的那一项;没有对应项,或有多个但无一以此命名的类型保持未映射,并产生一条指出该类型的警告发现项;导入器自行起草的映射,若目录为该类型和该能力提供了它则保留,否则丢弃并产生一条警告发现项;草稿 Release 的 spec.manifest 会设置为该 Manifest。目录中没有任何 Recipe 绑定的能力会在转换运行前被拒绝,且不写入任何内容。未提供时不起草 Manifest,但同步模式除外:同步会为先前导入记录中指定的目标起草;指定了目标的同步会为该目标起草,之后记录中即为该目标。
dryRun布尔值否是否以请求将写入的每个文件的内容作答,而不实际写入。其余行为均与写入相同,因此写入会拒绝的请求在此模式下同样会被拒绝;与同步一起使用时,它会以同步将写入的内容以及每个会产生偏离的部分作答。
sync布尔值否是否将先前导入在 outputDir 下起草的内容更新为与源一致,而不是整体写入草稿。只有导入所写的内容会发生变化,以草稿旁的记录所列为准:源未改动的部分保持磁盘上的原样,无论是否被编辑过;源更改、删除或新增的部分会重新写入、移除(草稿文件整体删除)或添加,前提是磁盘上的内容就是导入上次写入的内容;其余一切,包括作者添加的键(其中包括草稿 Release 留给作者填写的环境),或未直接写在草稿键上方的注释,均逐字节保持不变。若同步会更改或移除作者编辑或添加的内容,或在作者已写入某部分的位置添加该部分,会被拒绝并指出每个部分;对没有任何记录列出的 Aggregate 进行同步同样会被拒绝;两种情况下都不写入任何内容。不使用该选项时,如果请求的草稿会覆盖 outputDir 中已有的 Aggregate,请求会被拒绝,在 dryRun 下也是如此。
upgrade布尔值否是否获取工作区默认注册表发布的最新目录快照并据此导入,并从此保留该快照,取代工作区所持有的快照或草稿旁的记录所指定的快照;工作区指定了目录文件夹时,此项不改变任何内容;离线时会被拒绝。
answersstring否答案文件:草稿留空且任何源都无法提供的值从该文件读取并写入该文件,路径相对于工作区根目录;绝对值,或按原样或通过链接指向工作区之外的值,会被拒绝。该文件在每个草稿文件的路径下保存该文档内的键路径及其答案,答案会写入草稿。未提供时,读取草稿旁记录所指定的文件,否则读取源文件旁或源目录内的 import-answers.yaml。机密的答案指明机密的来源——变量名、${NAME} 或 Kubernetes Secret 的名称——其他任何内容都会被拒绝,且不写入任何内容。不会进行任何询问:每个仍待提供的值都是答复中 owed 的一个条目,也是一条警告发现项,指出草稿文件、键及其含义,其答案以 answered 发送;在写入草稿的情况下,最后一条发现项会说明还有多少待提供以及位于何处。当草稿包含 Release、没有待提供的值且转换已完成时,随后会拉取其依赖项并写入其 lockfile;拉取失败时,会以一条说明原因的发现项结束,草稿仍已写入;离线时不拉取任何内容,并由一条发现项指出需要运行的拉取。针对这些草稿未留空的键的答案会保留在文件中但不应用,因此一个答案文件可服务于所有目标。
answeredImportAnswered[]否针对答复的 owed 所列值的答案,每个答案都指出草稿文件以及 owed 所指出的键。每个答案都会被评判、保留在答案文件中,并以与在终端输入的答案完全相同的方式写入草稿:机密的答案指明机密的来源——变量名、${NAME} 或 Kubernetes Secret 的名称——不符合这一点的答案既不保留也不写入,其值仍待提供,原因作为其 secretAdvice。答案文件已回答的值从该文件获得答案;空答案,或指向草稿并不缺少的值的答案,不会被应用。请在草稿写入后与 sync 一起发送,因为对于 outputDir 中已有的 Aggregate,非 sync 的请求会被拒绝。在不保留任何答案的 dryRun 下,以及在转换已停止、不写入任何内容的 sync 下,发送的答案都不会被应用。

不允许其他属性。

ScaffoldEntityParams

为某个实体种类起草一份起始文档,或将文档中的某个可运行示例写入工作区中的一个新目录,或列出这些示例。起草时会从二进制文件携带的模式集推导出骨架,因此不会从工作区读取任何内容,也不会写入任何内容——答复是文本,其去向由客户端决定。写入示例只会写入新目录,不写入其他任何内容;示例读取自为该二进制文件版本发布的已签名文档包,若该版本没有发布文档包,则读取在其之前发布的最新文档包,并且在保存或读取之前会根据工作区的签名策略进行验证:未通过验证的文档包会被拒绝,离线时只读取已缓存的副本。同时发送两种形式字段的请求——kind 与 example 或 list 一起、list 与 example 一起、name 与 example 或 list 一起、dir 不与 example 一起——会在读取任何内容之前被拒绝。

属性类型必需描述
workspaceRootstring否工作区的绝对路径。起草不会读取它。写入或列出示例时需要它:工作区的配置决定从何处获取文档以及文档必须带有哪些签名,并且示例会写入工作区内部。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
kindstring否要起草的实体类型,以其小写标记命名,例如 component、aggregate、release、recipe 或 featurerecipe——即 aggrega/getSchema 为其列出的标记。
namestring否要写入草稿文档的名称。仅与 kind 一起发送。
examplestring否要写入的可运行示例,以示例列表为其给出的名称指定。代替 kind 发送。
list布尔值否是否以文档发布的每个可运行示例作答,且不写入任何内容。发送时既不带 example,也不带 kind。
dirstring否要将示例写入的新目录,相对于工作区根目录;缺省时,会写入根目录下以该示例命名的目录。该目录必须尚不存在或为空:含有任何内容的目录会被拒绝并保持原样;绝对路径值,或按字面或经由链接通向工作区之外的值,会在读取任何内容之前被拒绝。仅与 example 一起发送。

不允许其他属性。

LintParams

检查目录发布约定,范围可以是单个实体、某个 Release 闭包所及的全部内容,或配置的目录路径下的全部内容。任何模式下都不写入任何内容。既未指定实体也未指定 Release 时检查整个目录:在配置未为 Release 指定专属目录路径的工作区中,对工作区的目录检查一次;在 workspace.releases 下指定了 Releases 的工作区中,对每个 Release 在其读取的目录上各检查一次,绝不会对所有目录合并检查。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
entitystring否要检查的单个实体文档。
releasestring否要检查其闭包的 Release,以相对于工作区根目录的路径表示。
prePublish布尔值否是否将每个实体与其先前发布的版本进行比较,这会访问配置的注册表。

不允许其他属性。

PluginAddParams

将插件挂接到工作区所配置的某个插槽上。它会访问注册表,将查询解析为单个插件并固定版本。终端上需要获取的唯一决定——是否接受命令扩展插件所声明的能力——在这里以字段形式传入,因此由客户端去询问驱动它的一方,而该接口从不等待提示输入。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
typestring否插件所挂接的插槽。
querystring否要解析为单个插件的内容。
capabilitystring否挂接所针对的能力,适用于插槽承载多个能力的情况。
rolestring否挂接运行时所处的角色,它决定了挂接可以输出什么。
global布尔值否写入全机范围的配置文件。
workspace布尔值否写入该工作区自身的配置文件。
acceptCapabilities布尔值否调用方是否接受命令扩展插件所声明的能力。
dryRun布尔值否是否以配置文档的内容作答,而不是写入该文档。

不允许其他属性。

PluginRemoveParams

将插件从工作区所配置的某个插槽上解除挂接。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
typestring否插件当前所挂接的插槽。
querystring否要移除的挂接。
global布尔值否写入全机范围的配置文件。
workspace布尔值否写入该工作区自身的配置文件。

不允许其他属性。

PluginSyncParams

使 Plugin 实体中由机器维护的记录与其所指向的模块保持一致。它会重写这些记录,文档中的其他所有字节保持不变。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
entitystring否要对齐的 Plugin 实体文档。
pluginstring否从中读取记录的插件模块。

不允许其他属性。

PluginGenCatalogParams

根据插件自身声明的元数据加上编写的覆盖层,生成 Plugin 目录文档。在输入未变的情况下重新生成,会得到逐字节相同的文档。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
fromEmbedded布尔值否是否从二进制文件已携带的插件中读取元数据。
pluginstring否从中读取元数据的插件模块。
outputDirstring否工作区下用于写入文档的目录。
overlaystring否编写的文档,其内容会合并覆盖到生成的元数据之上。
dryRun布尔值否是否以这些文档的内容作答,而不是写入它们。

不允许其他属性。

ExplainErrorParams

将某条发现所携带的代码展开为编译器对该情况的声明,以及讲解如何在编写中修复的已发布条目。当工作区没有已发布文档的副本时,它会获取该文档;无法获取时,仍会返回二进制文件所声明的内容,并说明缺少说明文字的原因。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
codestring否要展开的情况,可用某条发现所携带的代码或其短代码指定。

不允许其他属性。

GetSchemaParams

返回某个类型的 schema,或者——在未指定类型时——返回可以指定哪些类型。它针对正在运行的二进制文件作答,而不是针对安装在其他位置的副本,因此不需要工作区,也不读取工作区。

属性类型必需描述
workspaceRootWorkspaceRootAccepted否工作区的绝对路径。该方法的主体不是工作区——它依据二进制文件自身携带的内容作答——因此该字段会被接受但不会被读取。之所以允许该字段,是因为客户端可以在每个请求中统一发送它,而无需知道哪些方法会读取它。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
kindstring否要返回其 schema 的类型。缺省时改为返回可以指定的类型。

不允许其他属性。

SkillsInstallParams

将内置于二进制文件中的助手技能写入请求所指定的每个助手的技能文件夹,或者,对于未指定任何助手的 global 请求,写入在本机上找到的每个助手的技能文件夹。不带 global 时,它写入请求所指定工作区内每个助手的项目文件夹,且它要在那里写入的每个路径都被限制在该工作区内;带 global 时,它写入主目录下每个助手的用户级文件夹。在写入任何内容之前会检查每个目标,因此一次拒绝会让所有文件夹保持原样。

属性类型必需描述
workspaceRootWorkspaceRootSubject是该请求所作用的工作区的绝对路径。它是请求的主体:守护进程在方法运行前解析它;省略它或将其写成字符串以外的任何形式的请求会被拒绝。
workDoneTokenProgressToken否调用方生成的值,用于将进度通知与请求这些通知的调用对应起来。它会在每条通知中原样返回,因此调用方可以将其与自己发送的值进行比较。每个请求都接受该值;如果在未声明进度能力的会话中发送该值,请求会被拒绝。
agentsstring[]否要为其安装技能的助手,以列表所报告的标识符指定。未指定任何助手的项目级请求会被拒绝。未指定任何助手的 global 请求会为在本机上找到的助手安装技能,即配置文件夹位于主目录中或命令位于 PATH 上的每个助手;若一个也找不到,则该请求被拒绝,且不写入任何内容。没有已知技能文件夹的标识符会被拒绝,并指出其名称;给出两次的标识符只安装一次。
global布尔值否写入主目录下每个助手的用户级技能文件夹(助手在每个项目中都会读取它),而不是其在工作区中的项目文件夹。

不允许其他属性。

ServerCapabilities

守护进程在本会话中将执行的操作,依据客户端声明的处理能力协商确定。

属性类型必需描述
positionEncodingstring是本会话中所有位置所使用的编码。
workDoneProgress布尔值否守护进程在本会话中是否会发送进度通知。仅当客户端声明可以接收进度通知时才出现。

不允许其他属性。

ClosureEntity

某个 Release 所依赖的一个实体,采用解析所确定的版本。

属性类型必需描述
uristring是解析该实体所依据的引用。
versionstring是最终确定的版本。
kindstring否实体类型。
sourcestring否生成此条目的那次运行从何处获取该实体,所用词语与 aggrega pull --detail 为其打印的相同:fetched-fresh(在该次运行中从注册表获取)、cache-reuse(缓存中已有的副本,未经获取直接复用)、local(在本地文件系统中找到,例如目录(catalog)目录)、in-binary(编译器二进制文件内的副本)或 external(该 Release 自身的 Aggregate 或 Manifest,从该 Release 指定的文件或条目读取,而不是作为其依赖之一解析;该次运行从注册表获取的 Aggregate 则为 fetched-fresh)。出现在依赖解析报告的条目中,描述该次运行在本机上所做的操作;在 Release 已解析依赖的列表中不出现,该列表描述的是该 Release 依赖什么。锁文件不记录来源。对于运行未记录其来源的实体,省略此字段。

不允许其他属性。

ToolchainCorePlugin

编译器自身携带的一个插件,以及所使用的版本。

属性类型必需描述
pluginstring是插件的引用。
versionstring是所使用的版本。

不允许其他属性。

ToolchainReport

完成解析的编译器,以及它携带的插件。

属性类型必需描述
compilerVersionstring是完成解析的编译器版本。
corePluginsToolchainCorePlugin[]否编译器携带的插件,以及每个插件所使用的版本。

不允许其他属性。

DependencyResolutionReport

一次依赖解析所固定和获取的内容。

属性类型必需描述
lockfilestring是解析写入的锁文件,或校验时所比对的锁文件。
verified布尔值否该请求是否为校验;校验会比对已记录的锁文件,不写入锁文件、插件信任记录或 entity.lock。
entitiesClosureEntity[] 或 null是解析所固定的实体,或校验所比对的实体。
librariesClosureEntity[] 或 null是解析所固定的库,或校验所比对的库。
pluginsClosureEntity[] 或 null是解析所固定的插件,或校验所比对的插件。
sourceArtifactsinteger是获取的源制品数量。
trustedPluginsinteger是已固定的插件中带有已验证签名的数量。
toolchainToolchainReport否完成解析的编译器,以及它携带的插件。
externalInputsinteger是渲染所使用的外部输入中已获取的数量。
incompleteExternalInputsstring否在部分外部输入无法获取时,列出哪些无法获取。

不允许其他属性。

BuildNotice

构建希望调用方知道的一件事,它既不是关于某个文档的发现,也不是失败。

属性类型必需描述
classstring是该通知的类型。
textstring是通知的内容。

不允许其他属性。

CacheScope

缓存应答的影响范围。其中两类缓存由本机上的所有项目共享,因此每个缓存应答都会指明它涉及了哪些缓存——否则在某个工作区上打开的会话会被理解为只报告该工作区的情况。

属性类型必需描述
machineWideClassesstring[] 或 null是此应答涉及的、由本机所有项目共享的缓存类别。
workspaceRootstring是请求所指定的工作区。

不允许其他属性。

CacheElement

缓存中保存的一项内容。

属性类型必需描述
labelstring是该条目对应的内容。
sizeinteger是它占用的字节数。
sizeTextstring是以便于人阅读的形式表示的同一大小。
digeststring否该条目所用的内容摘要键(如有)。
notestring否关于该条目的其他值得说明的信息。

不允许其他属性。

CacheClass

守护进程所报告的一个缓存。

属性类型必需描述
namestring是这是哪个缓存。
reachstring是该缓存属于此工作区,还是在本机范围内共享。
prunable布尔值是守护进程是否会回收此缓存。
elementsCacheElement[] 或 null是该缓存保存的内容。

不允许其他属性。

CacheProvenance

缓存的制品是以哪些身份获取的,以及它的共享范围有多广。

属性类型必需描述
identitiesstring[] 或 null是该制品所归属的身份。
sharedByinteger否共享该制品的持有者数量。

不允许其他属性。

CacheRemoval

一次回收删除的一项内容——或者,在其保留内容的列表中,它本会删除的一项内容。

属性类型必需描述
classstring是它所属的缓存。
labelstring是它是什么。
reachstring是该缓存属于此工作区,还是在本机范围内共享。
sizeinteger是它占用的字节数,或被删除前占用的字节数。
sizeTextstring是以便于人阅读的形式表示的同一大小。

不允许其他属性。

CacheShortfall

一次回收遗留下的内容,以及什么操作可以回收它们,以便看到比预期更小数值的调用方能得知原因,而不必自行推断。

属性类型必需描述
classstring是遗留内容所在的缓存。
countinteger是遗留的条目数量。
sizeinteger是它们占用的字节数。
sizeTextstring是以便于人阅读的形式表示的同一大小。
reachstring是该缓存属于此工作区,还是在本机范围内共享。
reclaimedBystring[] 或 null是什么操作可以回收它们。

不允许其他属性。

CacheCleared

一次清除所清空的一个缓存。

属性类型必需描述
classstring是被清空的缓存。
reachstring是它属于此工作区,还是在本机范围内共享。
sizeinteger是从中回收的字节数。
sizeTextstring是以便于人阅读的形式表示的同一大小。
heldOpenFilesinteger是由于其他进程打开了这些文件,清除时在此缓存中保留的文件数量。只有 Windows 会拒绝删除已打开的文件,因此在其他平台上该值为零。待该进程不再使用这些文件后,之后的清除会将其删除。
heldOpenBytesinteger是这些文件占用的字节数。它们不计入 size,size 表示清除所回收的量。
heldOpenBytesTextstring是以便于人阅读的形式表示的同一数值。

不允许其他属性。

ConfigWriteScope

写入的是哪个配置文档,以及其影响范围。请求指定了一个工作区,因此不加说明的应答会被理解为针对该工作区——而对于本机范围的写入,这种理解是错误的。

属性类型必需描述
configFilestring是被写入的文档。
machineWide布尔值是该文档是否为本机上所有工作区解析时都会经过的文档。
workspaceRootstring是请求所指定的工作区。

不允许其他属性。

PluginWriteScope

插件变更写入了哪个配置文档,以及其影响范围。命令扩展插槽自身的默认值是本机范围的文档,因此每个应答都会说明它写入了哪个文档。

属性类型必需描述
configFilestring是被写入的文档。
machineWide布尔值是该文档是否为本机上所有工作区解析时都会经过的文档。
workspaceRootstring是请求所指定的工作区。

不允许其他属性。

CredentialStoreScope

凭据变更的影响范围。该存储由本机上的所有项目以及访问相同注册表的所有其他工具共享,因此应答会报告这一点,而不是让人推断其仅作用于会话范围。

属性类型必需描述
machineWide布尔值是该变更所涉及的存储是否在本机范围内共享。
workspaceRootstring是请求所指定的工作区。

不允许其他属性。

SkillFolderScope

技能安装的影响范围。请求指定一个工作区,因此一个什么都不说明的应答会被理解为仅涉及该工作区——而对于助手在每个项目中都会读取的用户级文件夹,这种理解是错误的。

属性类型必需描述
machineWide布尔值是写入的文件夹是否为主目录下的用户级文件夹,助手在本机的每个项目中都会读取它们。
workspaceRootstring是请求所指定的工作区。

不允许其他属性。

PublicationReach

一次发布所触及的范围。这些应答的影响完全超出本机——它们附加的内容就是该注册表的每个使用者所解析到的内容——因此每个应答都会列出它访问过的每个注册表,以及该调用是否在那里附加了任何内容。

属性类型必需描述
registriesstring[]是该调用访问过的每个注册表主机,每个只列出一次,按调用首次访问它的顺序排列。单一引用的调用只列出一个;试运行(dry run)列出它本会访问的目标。
beyondThisMachine布尔值是该调用是否附加了注册表现在向他人提供的任何内容:上传的内容、签名、发布日期或弃用标记。在试运行时为 false;在调用发现它本要附加的一切都已存在时也为 false——例如对一个完整版本再次运行发布,或一批签名中的每个引用都已带有可验证的签名。

不允许其他属性。

WorkspaceEntityRef

一个实体,按种类和名称标识,并附带声明它的文档。

属性类型必需描述
kindstring是实体类型。
namestring是实体名称。
filestring是声明它的文档,以相对于工作区根目录的路径表示。

不允许其他属性。

SourcedEntityRef

一个实体,附带它的读取来源。工作区文档报告其相对于工作区的路径;从已配置的目录(catalog)目录中解析出的实体报告空路径,因为它仅有的路径对客户端没有意义。origin 说明属于这两者中的哪一种,而不是让空路径被理解为无人填写的字段。

属性类型必需描述
kindstring是实体类型。
namestring是实体名称。
filestring是声明它的文档,以相对于工作区根目录的路径表示;若它来自已配置的目录(catalog)目录,则为空。
originstring是该实体的读取来源。

不允许其他属性。

SocketCandidacy

实体上的一个 socket,以及可以连接到它的对象。

属性类型必需描述
socketstring是该 socket 的名称。
declarationstring是该 socket 的声明位置。
selectorstring是目标必须满足的标签选择器。
required布尔值是是否必须连接该 socket,构建才能继续。
targetsWorkspaceEntityRef[] 或 null是可以连接到它的实体。

不允许其他属性。

SlotCandidacy

连接的 socket 所声明的一个 slot(按使用方 Component 在该 socket 上的声明),以及可以在该连接上填充它的 Features。

属性类型必需描述
slotstring是该 slot 的名称,即填充它的附件在该连接的 features 中所使用的键。
selectorstring是填充该 slot 的 Feature 必须以其自身标签满足的标签选择器。若该 slot 未声明选择器则为空,此时接受任何 Feature。
required布尔值是是否每个经由该 socket 连接的连接都必须填充该 slot,构建才能继续。
injectstring[]是该 slot 允许其填充物使用的交付机制,按 Component 声明它们的顺序排列。若未声明则为空。
sensitive布尔值是该 slot 是否声明其填充物会处理机密材料。它会标记填充它的附件,但不拒绝任何内容。
descriptionstring是Component 对该 slot 用途的说明。若未作说明则为空。
candidatesSourcedEntityRef[]是可以在此连接上填充该 slot 的每个 Feature:其声明的适用范围被图节点的标签所满足(该节点携带的每个附件都受此约束),且其自身标签满足该 slot 的选择器。若某个 Feature 的适用范围或标签无法按选择器解读,则不会被提供,因为构建会拒绝而不是接受它。

不允许其他属性。

CatalogEntity

工作区索引中保存的一个实体。

属性类型必需描述
kindstring是实体类型。
namestring是实体名称。
apiVersionstring是文档声明的 schema 版本。
descriptionstring是文档对该实体用途的说明。
labelsmap of string 或 null是文档声明的标签。
filestring是声明它的文档,以相对于工作区根目录的路径表示。
originstring是该实体的读取来源。

不允许其他属性。

CompletionItem

可以在光标处写入的一项内容。

属性类型必需描述
labelstring是要写入的文本。
kindinteger否它属于哪类内容,以便客户端为其选择图标。
detailstring否显示在标签旁的简短限定说明。
documentationstring否对该内容的详细说明。
sortTextstring否用于排序的值(当它与标签不同时)。

不允许其他属性。

MarkupContent

要显示的文本及其标记方式。

属性类型必需描述
kindstring是文本的标记方式。
valuestring是文本。

不允许其他属性。

EntityKindDescriptor

作者编写文档所用的一种种类,将请求中使用的标记与文档自身声明的种类配对,并说明哪些操作接受该种类的文档。

属性类型必需描述
kindstring是请求中使用的小写标记,例如 component 或 featurerecipe。
documentKindstring是文档自身头部声明的种类。
acceptedByEntityKindAcceptance是哪些操作接受单独指定的该种类文档——通过其路径,或为检查而通过其名称——且不附带发送其他任何内容。当该操作不会因文档属于此种类而拒绝它时,对应成员为 true;被接受的文档仍可能因其内容而被拒绝。

不允许其他属性。

EntityKindAcceptance

针对作者编写的一种种类,说明每个操作是否接受单独指定的该种类文档。每个条目上都包含所有成员,因此 false 是一种明确陈述,而不是省略。

属性类型必需描述
singleEntityValidation布尔值是aggrega validate 的单实体范围(即给定单个文档路径的命令)是否检查该种类的文档。它拒绝的种类改由整个目录范围或 Release 范围检查。
publication布尔值是仅指定该文档的 aggrega/publishEntity 是否会发布该种类的文档。若某种类的发布还需绑定与文档并列指定的可执行文件(即 Plugin),则为 false,因为仅指定该文档的请求会被拒绝;Manifest 和 Release 为 false,因为这两种类型都不会被发布。
inspectionByName布尔值是aggrega/entityDefinition 是否将名称解析为该种类的实体,所发送的名称与一个实体引用另一个实体时的写法相同。

不允许其他属性。

RegistryTrust

解析过程对注册表所提供内容应用的信任策略。

属性类型必需描述
signaturesRequired布尔值是来自该注册表的制品是否必须带有经过验证的签名。
verificationSkipped布尔值否是否跳过验证。
advisory布尔值否验证失败时是否仅报告而不中止。
anchorstring否用于验证签名的信任锚。
keylessIdentitiesinteger否该注册表受信任的签名身份数量。

不允许其他属性。

Registry

一个已配置的注册表。此处没有任何字段携带凭据材料、其长度、其形态或其任何呈现形式——报告的只有是否存在,正因如此,该值可以安全地粘贴到 issue 中。

属性类型必需描述
hoststring是注册表主机,即其标识。
namestring否解析到该主机的友好别名(若已配置)。
default布尔值是未指定注册表的操作是否访问此注册表。
authStatestring是该主机的凭据是否存在于机器范围的存储中。即使为空也会报告,以便调用方区分“不存在凭据”与“列出时未查看”。
trustRegistryTrust是解析过程对注册表所提供内容应用的信任策略。

不允许其他属性。

TrustFetchOutcome

读取 registry 所公布的信任策略的结果。这些结果分开表示,因为它们含义不同:采纳了所公布的策略;registry 未公布任何策略(这不算失败);以内置基线代替并固定;或者未尝试读取。在未公布任何策略的情况下,会同时说明该 registry 是否根本无法访问。

属性类型必需描述
pinned布尔值是是否采纳了所公布的策略。
notAdvertised布尔值否是否已询问该 registry 且其未公布任何策略;此时操作按请求中声明的内容继续。因离线模式而未被询问的 registry 不会以这种方式报告。无法访问的 registry 也以这种方式报告,因为它没有返回任何策略,并同时带有 unreachable;读取 unreachable 即可区分这两种情况。
unreachable布尔值否在请求其所公布的策略时,该 registry 是否无法访问:其名称无法解析、到它的连接被拒绝或无法打开,或无法与它建立安全连接。该值根据失败本身判定,而不是根据 reason;它与 notAdvertised 同时出现,并且仅在失败表明从未访问到该 registry 时才设置;作出了应答的 registry(无论是未返回策略还是返回失败)不会设置此字段。
baseline布尔值否是否因为未采纳任何所公布的策略而固定使用了内置基线;只有官方 hub 带有此基线。若已询问 hub 且其未公布任何策略,则它与 notAdvertised 同时出现;若离线模式使 hub 未被询问,则它单独出现。
skipped布尔值否是否未尝试读取,原因是声明的策略覆盖了它,或请求要求不读取。
identitiesinteger否所公布的策略中包含多少个签名身份。
reasonstring否未采纳所公布策略的原因:registry 端点的行为,或阻止询问它的离线拒绝。

不允许其他属性。

SkippedRepo

索引遍历跳过的一个仓库及跳过原因。

属性类型必需描述
repostring是被跳过的仓库。
reasonstring是跳过的原因。

不允许其他属性。

DeprecationNote

索引遍历遇到的一个弃用标记,以及对它的处理。被采纳的标记与存在但被拒绝的标记以同等方式报告,这样记录了许多标记不会悄无声息,而拒绝一个标记也不会格外显眼。

属性类型必需描述
repostring是标记所在的仓库。
versionstring是标记涵盖的版本。
recorded布尔值是标记自身的签名是否通过验证,从而被索引收录。
severityconst “warning” 或 const “error” 或 const “retracted”否标记的强度。允许的值:"warning" — 已弃用,处于两个建议级别中较弱的一级:选择版本时仍会被选中。"error" — 已弃用,处于两个建议级别中较强的一级:选择版本时仍会被选中。"retracted" — 已撤回:选择版本时会被排除。
reasonstring否该版本被弃用的原因。

不允许其他属性。

HostUpdate

一次索引刷新对某个 registry 所做的操作。

属性类型必需描述
hoststring是被刷新的 registry 主机。
indexedinteger是写入的记录数。
deprecationsExamined布尔值是遍历是否查找过弃用标记。它与计数分开,因为“此 registry 未发布任何标记”与“本次运行没有判断依据”是不同的事实。
deprecationsRecordedinteger是被采纳的标记数。
skippedSkippedRepo[] 或 null是遍历跳过的仓库。
deprecationsDeprecationNote[] 或 null是遍历遇到的标记。
readsRetriedinteger是遍历的读取中有多少次被注册中心拒绝或中途丢弃并被重新请求,每次读取只计一次,无论尝试了多少次,也无论之后是否成功;没有时为零。读取最终全部成功的遍历不会在 skipped 下列出任何仓库,因此正是这个计数说明了它离遗漏某个仓库有多近。最小值:0。
errorstring否此主机上失败的内容,这样对多个主机的遍历会报告其中哪些失败,调用方无需自行关联。
unreachable布尔值否该 registry 是否无法访问:其名称无法解析、到它的连接被拒绝或无法打开,或无法与它建立安全连接。该值根据失败本身判定,而不是根据 error;它仅与 error 同时设置,并且仅在失败表明从未访问到该 registry 时设置;作出了应答的 registry,无论应答内容如何,都不会设置此字段。

不允许其他属性。

PublishedVersion

索引为某个引用保存的一个版本:构建索引时其标签解析到的 manifest 摘要;若构建索引所依据的信任策略验证了该版本自身的签名,则包括验证所得的签名者;若有记录,还包括该版本的发布时间及其来源。对于没有签名的版本、所有签名均未通过验证的版本,以及该策略既未固定公钥也未固定可信身份、或关闭了签名验证的情况,签名者均不存在。这些情况都不足以确定签名者,签名者的缺失也不表示其他含义。若发布时未声明日期,且该策略验证的无密钥签名也未记录日期,则发布日期不存在。

属性类型必需描述
versionstring是版本,以其标签命名。
manifestDigeststring是构建索引时该版本标签解析到的 manifest 的摘要,它按所指向的字节而非标签来定位该版本。
signerVerifiedSignature否已按 registry 信任策略通过验证的签名:验证方式、验证所得的签名者,以及通过验证的签名包的摘要。
publishedAtstring否版本的发布时间,为精确到秒的 UTC RFC 3339 时间戳。其来源为 publishedAtSource,二者同时存在或同时不存在。
publishedAtSourceconst “transparency-log” 或 const “publisher”否publishedAt 的来源,以免将透明日志证明的时间误认为发布方声明的时间。该集合是封闭的。允许的值:"transparency-log" — 透明日志记录该版本无密钥签名的时间,构建索引时所依据的信任策略已连同日志对该时间的签名承诺一起验证了它。对于发布时签名的版本,它就是发布时间;对于事后签名的版本,它是该签名生成的时间。"publisher" — 发布内容在所发布内容旁声明的时间,来自发布机器自身的时钟。没有任何东西证明它。当签名不携带经证明的时间时(有密钥签名或没有签名),发布会声明该时间。附有多个时,取最早的一个。

不允许其他属性。

VerifiedSignature

已按 registry 信任策略通过验证的签名:验证方式、验证所得的签名者,以及通过验证的签名包的摘要。

属性类型必需描述
bundleDigeststring是通过验证的签名包的摘要,格式为 sha256: 后跟 64 个小写十六进制字符。
identitystring否签名验证所得的签名者:对于无密钥签名,是签名证书所颁发给的身份,即其主题备用名称;对于有密钥签名,是 keyed:sha256: 后跟所固定公钥 PEM 文本的小写十六进制 SHA-256。
issuerstring否对于无密钥签名,签名证书中记录的 OIDC 颁发者。有密钥签名时不存在。
modeconst “keyless” 或 const “keyed”是签名的验证方式。该集合是封闭的。允许的值:"keyless" — 依据一个签名证书验证,其身份和颁发者与策略信任的某一项匹配,该证书链接到策略固定的信任根,若策略未固定则链接到公益 Sigstore 根,且其签名由透明日志记录。"keyed" — 依据策略固定的公钥验证。

不允许其他属性。

RegistrySearchRecord

搜索匹配到的一条记录(按本地索引中保存的样子),以及其哪些版本已被发布的标记弃用。

属性类型必需描述
uristring是记录所解析自的引用。
namestring是实体名称。
versionstring是记录所对应的版本。
versionsstring[]否索引为此引用保存的每个版本。
kindstring否实体类型。
descriptionstring否实体的用途。
categorystring否实体发布所属的类别。
labelsmap of string否实体声明的标签。
pluginTypestring否插件记录所挂接的 socket。
capabilitiesstring[]否插件记录声明的能力。
manifestDigeststring否已发布 manifest 的摘要。
listingDigeststring否读取该记录的清单的摘要。
deprecationsobject[]否索引为此引用保存的弃用标记,每个都带有其涵盖的版本和经过验证的标记本身。
publishedPublishedVersion[]否索引为此引用保存的每个版本,顺序与 versions 相同;每个版本都带有构建索引时其标签解析到的 manifest 摘要;若构建索引所依据的信任策略验证了该版本自身的签名,则带有验证所得的签名者;若有记录,还带有发布日期及该日期的来源。记录中没有签名者的版本,不带有经该策略验证的签名,除此之外不作其他说明。为记录这些信息,只从 registry 读取 manifest、签名附件和发布日期附件;不获取任何实体的内容。
retractedstring[]否已被发布的标记弃用的版本。

不允许其他属性。

RegistrySearchIndex

一个被搜索主机的新鲜度。

属性类型必需描述
hoststring是其索引被搜索的主机。
lastUpdatedstring否索引上次刷新的时间。快照未携带时间时,该字段缺省而不是为零,因此调用方可以区分“未记录”与纪元时间。

不允许其他属性。

EffectiveConfigurationSetting

一项已解析的设置,以及它来自哪个文档。

属性类型必需描述
fieldstring是该设置。
valuestring是解析得到的值。
sourcestring是该值的来源。

不允许其他属性。

ImportedFile

导入写入的一个文件:一个草稿文档,或导入所写内容的记录。

属性类型必需描述
pathstring是该文件所在的位置,为相对于应答中 outputDir 的路径。
contentstring是该文件的文本。

不允许其他属性。

ImportDrift

同步使其与源保持一致的一个部分,或在 dryRun 下将会如此的部分。

属性类型必需描述
changestring是该部分如何漂移:added 表示源新增的部分;removed 表示源删除的部分;changed 表示源更改的部分。
filestring是该部分所在的草稿文件,为相对于应答中 outputDir 的路径。
keystring[]是从草稿 Aggregate 或 Release 顶层通向该部分的键,每个键一项,因此包含句点的键仍为一项。该部分为整个文件时为空。

不允许其他属性。

ImportOwed

草稿仍留空、任何源都无法提供、也没有任何答案提供的一个值。

属性类型必需描述
filestring是该值所在的草稿文件,为相对于答复的 outputDir 的路径。
keystring[]是从该文档顶部通向该值的键,每个键一个条目,因此包含句点的键仍是一个条目。以 answered 发送的答案通过这些键来指明该值。
questionstring是该值是什么:其 schema 的描述,否则为草稿在其键上方写的注释,否则为其 schema 所说明的可接受内容。
sensitive布尔值是该值是否属于机密;机密的答案指明机密的来源,且绝不包含机密本身。
secretAdvicestring否出现在机密的值上:其答案必须是什么,即向在终端回答它的人显示的那句话——或者,若以 answered 为其发送的答案被拒绝,则说明被拒绝的原因。

不允许其他属性。

ImportAnswered

针对答复的 owed 所列某个值的一个答案。

属性类型必需描述
filestring是该值所在的草稿文件,按 owed 所指出的。
keystring[]是通向该值的键,按 owed 所指出的。
answerstring是答案。空答案会使该值仍待提供。

不允许其他属性。

ImportDiagnostic

转换无法转换的一项内容。这些是转换最有用的输出,因此会完整报告,而不是简化为一个结论。

属性类型必需描述
severitystring是其严重程度。
messagestring是无法转换的内容。
codestring否该情况可引用的名称(如有)。

不允许其他属性。

ImportDecision

转换如何映射一个源节点:导入器权衡过的目录 Components、它选中的那个、原因,以及如何替换该选择。

属性类型必需描述
sourceNodeDecisionSourceNode是映射决策所针对的源节点。
candidatesImportCandidate[]否导入器为该节点权衡过的目录 Components,每个都附有其得分。未权衡任何 Component 时缺省。
chosenDecisionChoice否导入器为源节点所做的选择。未做选择的决策中不包含此项。
rationalestring否导入器做出该选择的原因,以其自己的措辞表述。未写原因时缺省。
swapHintstring否如何将该选择替换为另一方案,以导入器自己的措辞表述。未写时缺省。

不允许其他属性。

DecisionSourceNode

映射决策所针对的源节点。

属性类型必需描述
idstring是该节点在源中的标识符。
typestring是该节点的类型,按源中的命名。
paramsSummarystring是该节点参数的摘要,用于在决策旁显示。

不允许其他属性。

ImportCandidate

导入器为一个源节点权衡过的一个目录 Component。

属性类型必需描述
componentNamestring是该 Component 的名称。
scorenumber是该 Component 与节点的匹配程度,由导入器评分。
tierstring是该得分所属的匹配层级。
signalsCandidateSignals是导入器的每个信号对候选项得分的贡献。

不允许其他属性。

CandidateSignals

导入器的每个信号对候选项得分的贡献。

属性类型必需描述
tablenumber是映射表信号的贡献。
categorynumber是类别信号的贡献。
domainLabelsnumber是领域标签信号的贡献。
shapenumber是形状信号的贡献。
namenumber是名称信号的贡献。

不允许其他属性。

DecisionChoice

导入器为源节点所做的选择。未做选择的决策中不包含此项。

属性类型必需描述
targetstring是所选 Component 的名称:一个现有的目录 Component,或为该节点起草的 Component。
modestring是该选择的写入方式:作为对现有 Component 的引用,或作为新起草的 Component。
tierstring是该选择的匹配层级。

不允许其他属性。

LintFileFindings

约定检查在一个文档中发现的问题。

属性类型必需描述
filestring是该文档。
diagnosticsDiagnostic[] 或 null是其中的发现。

不允许其他属性。

PluginRetractionExclusion

一个可用但未被选中的版本。

属性类型必需描述
versionstring是被跳过的版本。
reasonstring否跳过的原因。

不允许其他属性。

PluginRetractionProvenance

有关哪些内容已弃用的信息来源。

属性类型必需描述
sourcestring是查询了什么。
lastUpdatedstring否其上次刷新的时间。

不允许其他属性。

PluginRetraction

弃用标记如何影响所固定的插件版本。

属性类型必需描述
referencestring是这些版本所属的引用。
selectedstring否被固定的版本。
excludedPluginRetractionExclusion[]否可用但被跳过的版本。
unscreenedstring否无法对照标记进行筛查的内容及原因。
provenancePluginRetractionProvenance否有关哪些内容已弃用的信息来源。

不允许其他属性。

PluginGeneratedDocument

一次生成产生的一个目录文档。

属性类型必需描述
pathstring是该文档所在的位置,为相对于工作区根目录的路径。
contentstring是该文档的文本。

不允许其他属性。

PluginCommandFlag

插件在其提供的命令上声明的一个标志。

属性类型必需描述
namestring是该标志的长名称。
shorthandstring否该标志的单字符别名(如有)。
descriptionstring否该标志的单行帮助文本。
typestring否该标志的值类型。
defaultstring否未传入该标志时使用的值。

不允许其他属性。

PluginCLICommand

插件提供的一个顶层命令动词。

属性类型必需描述
namestring是该命令动词。
descriptionstring否该命令的单行帮助文本。
flagsPluginCommandFlag[]否该命令的标志,按声明顺序排列。

不允许其他属性。

ConfigCapturedAttachment

冻结操作写入此工作区自身配置的一个附件。

属性类型必需描述
uristring否该附件解析所依据的引用。
capabilitystring否该附件所针对的能力。
functionstring否该附件被分派到的导出项。
rolestring否挂接运行时所处的角色,它决定了挂接可以输出什么。

不允许其他属性。

ConfigCapturedSocket

冻结操作写入的一个插槽,以及冻结到其上的附件。

属性类型必需描述
socketstring是该插槽。
fieldstring是该插槽写入其下的配置字段。
attachmentsConfigCapturedAttachment[] 或 null是冻结到其上的附件。

不允许其他属性。

ExplainErrorEntry

讲解某一情况的编写修复方法的一段已发布文字。

属性类型必需描述
headingstring是该段文字的标题。
bodystring是该段文字。

不允许其他属性。

SignedArtifact

一次签名所覆盖的一个已发布制品。

属性类型必需描述
referencestring是被签名的引用。
digeststring是被签名内容的摘要。

不允许其他属性。

DeprecationMarked

一次弃用所标记的一个已发布版本。

属性类型必需描述
referencestring是被标记的引用。
severityconst “warning” 或 const “error” 或 const “retracted”是标记的强度。允许的值:"warning" — 已弃用,处于两个建议级别中较弱的一级:选择版本时仍会被选中。"error" — 已弃用,处于两个建议级别中较强的一级:选择版本时仍会被选中。"retracted" — 已撤回:选择版本时会被排除。
issuedOnstring是该标记的签发时间。
digeststring是所发布标记的摘要。

不允许其他属性。

InitializeResult

会话为此客户端确定的内容,以及它从哪个配置层解析而来。

属性类型必需描述
capabilitiesServerCapabilities是守护进程在本会话中将执行的操作,依据客户端声明的处理能力协商确定。
workspaceRootstring是会话打开的工作区。
configSourcestring是会话从哪个配置层解析其设置。
workspaceMarkerstring否标识工作区根目录的文件(如有)。
versionstring是响应此会话的二进制文件的版本:与 aggrega version 对该二进制文件报告的值相同。它描述的是正在运行的进程,因此一旦启动守护进程的文件被替换,此值仍是正在运行的版本,而查询该文件得到的是替换它的版本。

不允许其他属性。

ValidateResult

检查发现了什么,以及检查了多少内容。

属性类型必需描述
diagnosticsDiagnostic[] 或 null是检查结果。检查未发现任何问题时,它为 null 而不是空列表。
checkedstring否检查了多少内容——一个文档,或工作区包含的全部内容。

不允许其他属性。

InvalidateResult

守护进程是否持有该文档的任何可丢弃内容。

属性类型必需描述
invalidated布尔值是是否丢弃了任何内容。

不允许其他属性。

DiagnosticsResult

守护进程已持有的该文档的检查结果。

属性类型必需描述
diagnosticsDiagnostic[] 或 null是检查结果。没有结果时,它为 null 而不是空列表。

不允许其他属性。

IrGraphResult

一个 Release 编译成的已解析图。

属性类型必需描述
graphany是图文档。作者声明为敏感的值会被隐去,除非请求通过 unredacted 要求返回它们;其他内容均按编译器的输出原样携带。其自身结构是图的公开契约,此处不再赘述。

不允许其他属性。

BuildResult

一次构建写入的内容。

属性类型必需描述
outputDirectorystring是产物写入的目录。
filesstring[] 或 null是已写入的产物,以相对于输出目录的路径表示。
noticesBuildNotice[]否构建希望调用方知道的、既非检查结果也非失败的任何信息。
dependencyResolutionDependencyResolutionReport否一次依赖解析所固定和获取的内容。

不允许其他属性。

BuildPreviewResult

一次构建本会写入的内容。由于未写入任何内容,因此没有可指明的输出目录。

属性类型必需描述
filesstring[] 或 null是写入本会生成的产物。
noticesBuildNotice[]否编译希望调用方知道的、既非检查结果也非失败的任何信息。

不允许其他属性。

EntityDefinitionResult

一个实体名称解析为什么,以及定义它的文档。从注册表引用读取的响应带有 published,而目录按名称解析的响应永远不带。

属性类型必需描述
kindstring是实体类型。
namestring是实体名称。
versionstring是解析得到的版本。
descriptionstring否文档对该实体用途的说明。
publishScopestring否实体的发布范围有多广。
filestring是定义它的文档。
authoredLengthinteger是编写的文档包含多少字节,以便客户端区分编写的文档与其解析后的渲染结果。
definitionstring是定义的文本。
publishedPublishedArtifact否一个注册表引用读取的内容:坐标、它如何保存实体,以及读取时经由的 manifest。只要此项存在,每个字段都存在。

不允许其他属性。

PublishedArtifact

一个注册表引用读取的内容:坐标、它如何保存实体,以及读取时经由的 manifest。只要此项存在,每个字段都存在。

属性类型必需描述
referencestring是被读取的注册表引用。
archive布尔值是坐标的字节是否为一个归档,实体文档从中解包而来。坐标直接保存实体文档本身时为 false。
mediaTypestring是manifest 声明的产物类型。
manifestDigeststring是读取实体时经由的 manifest 的摘要——在 @ 之后指明该值,即可再次精确读取相同的字节。

不允许其他属性。

ReleaseClosureResult

一个 Release 依赖的全部内容,即解析所达到的范围。它报告的是闭包,而不是由闭包派生的图:这是关于同一 Release 的另一份文档。

属性类型必需描述
releasestring是被检查的 Release。
aggregatestring是它部署的 Aggregate。
manifeststring是它解析时经由的 Manifest。
environmentstring是它指明的环境。
entitiesClosureEntity[] 或 null是闭包所达到的实体。
librariesClosureEntity[] 或 null是闭包所达到的库。
pluginsClosureEntity[] 或 null是闭包所达到的插件。
mappingDiagnosticsstring[] 或 null是解析 Manifest 的映射时给出的信息。
deprecationsstring[] 或 null是闭包遇到的弃用标记。

不允许其他属性。

ResolveDependenciesResult

一次依赖解析固定和获取的内容,以及它希望调用方知道的任何信息。报告自身的字段直接放在此响应上,而不是嵌套在其某个成员之下。

属性类型必需描述
lockfilestring是解析写入的锁文件,或校验时所比对的锁文件。
verified布尔值否该请求是否为校验;校验会比对已记录的锁文件,不写入锁文件、插件信任记录或 entity.lock。
entitiesClosureEntity[] 或 null是解析所固定的实体,或校验所比对的实体。
librariesClosureEntity[] 或 null是解析所固定的库,或校验所比对的库。
pluginsClosureEntity[] 或 null是解析所固定的插件,或校验所比对的插件。
sourceArtifactsinteger是获取的源制品数量。
trustedPluginsinteger是已固定的插件中带有已验证签名的数量。
toolchainToolchainReport否完成解析的编译器,以及它携带的插件。
externalInputsinteger是渲染所使用的外部输入中已获取的数量。
incompleteExternalInputsstring否在部分外部输入无法获取时,列出哪些无法获取。
noticesstring[]否解析希望调用方知道的任何信息。

不允许其他属性。

PinResult

固定步骤对实体旁的锁文件做了什么,或在试运行时会做什么。它是 aggrega/pin 的响应,运行了该步骤的发布会将其作为 pin 携带。

属性类型必需描述
entitystring是该步骤读取的实体文档,以相对于工作区根目录的路径表示。
kindstring是实体的种类,按其文档声明。
namestring是实体的名称,按其文档声明。
pinnable布尔值是此种类的实体是否读取锁文件会为其记录固定项的内容,Recipe 和 FeatureRecipe 会这样做。为 false 时,实体旁的任何内容均未被改动,changed 为 false,且 lock、removed、pins 和 content 不存在。
lockstring否该步骤写入或将写入的锁文件,以相对于工作区根目录的路径表示。
changed布尔值是锁文件是否发生了变化,或在试运行时是否会变化。锁文件已记录实体所需的每个固定项且保持逐字节不变时为 false。
removed布尔值否该变化是否为删除:实体不读取任何需要锁文件记录固定项的内容,因此其旁不保留锁文件。
dryRun布尔值否此项报告的是该步骤将会做什么,而不是已经做了什么。
pinsPinClassCount[]否该步骤之后(或试运行之后)锁文件持有的每类固定项的数量。锁文件可持有的每个类别都会列出,包括没有固定项的类别。
contentstring否试运行将写入的锁文件。锁文件将保持原样或被删除时,以及在每个非试运行的响应中,此项不存在。

不允许其他属性。

PinClassCount

锁文件持有的某一类固定项的数量。

属性类型必需描述
classstring是固定项的类别,使用指出缺失固定项的拒绝信息中的措辞——例如 remote source 或 imported file。
pinsinteger是锁文件持有的该类固定项的数量。

不允许其他属性。

CacheStatusResult

为此工作区服务的缓存中保存了什么。

属性类型必需描述
classesCacheClass[] 或 null是每个缓存及其保存的内容。
provenanceCacheProvenance[] 或 null是缓存的制品是以哪些身份获取的。
totalCountinteger是各缓存共保存多少条目。
totalSizeinteger是它们共占用多少字节。
totalSizeTextstring是同一总量,以便于人阅读的形式表示。
scopeCacheScope是缓存应答的影响范围。其中两类缓存由本机上的所有项目共享,因此每个缓存应答都会指明它涉及了哪些缓存——否则在某个工作区上打开的会话会被理解为只报告该工作区的情况。

不允许其他属性。

CachePruneResult

一次回收删除了什么、保留了什么,以及无法回收什么。

属性类型必需描述
removedCacheRemoval[] 或 null是被删除的内容。
heldOpenCacheRemoval[] 或 null是清理本应删除、但因另一进程正打开而保留原处的内容。只有 Windows 会拒绝删除已打开的文件,因此在其他平台上此项为空。这些条目既不计为已删除,也不计为已保留,其字节均不计入已回收量,之后的清理会回收它们;作为目录的条目可能已失去其中未被打开的文件。
retainedCountinteger是保留了多少条目。
reclaimedBytesinteger是回收了多少字节。
reclaimedBytesTextstring是以便于人阅读的形式表示的同一数值。
unattributedCountinteger是有多少条目没有任何持有者认领。
unattributedSizeinteger是这些条目占用多少字节。
unattributedSizeTextstring是以便于人阅读的形式表示的同一数值。
notPruneEligibleCacheShortfall[] 或 null是遗留了什么,以及如何回收它。
scopeCacheScope是缓存应答的影响范围。其中两类缓存由本机上的所有项目共享,因此每个缓存应答都会指明它涉及了哪些缓存——否则在某个工作区上打开的会话会被理解为只报告该工作区的情况。

不允许其他属性。

CacheEvictResult

回收至某一大小时删除了什么,以及还剩什么。

属性类型必需描述
withinCapBefore布尔值是已保存的内容是否本就未超出该大小,因而无需删除任何内容。
removedCacheRemoval[] 或 null是被删除的内容。
heldOpenCacheRemoval[] 或 null是回收本应删除、但因另一进程正打开而保留原处的内容;回收转而处理下一个最旧的条目。只有 Windows 会拒绝删除已打开的文件,因此在其他平台上此项为空。这些条目仍计入剩余字节,之后的回收可以删除它们。
totalBeforeinteger是回收前保存了多少字节。
totalBeforeTextstring是以便于人阅读的形式表示的同一数值。
reclaimedBytesinteger是回收了多少字节。
reclaimedBytesTextstring是以便于人阅读的形式表示的同一数值。
remainingBytesinteger是还剩多少字节。
remainingBytesTextstring是以便于人阅读的形式表示的同一数值。
capBytesinteger是回收的目标大小,以字节计。
capBytesTextstring是以便于人阅读的形式表示的同一大小。
scopeCacheScope是缓存应答的影响范围。其中两类缓存由本机上的所有项目共享,因此每个缓存应答都会指明它涉及了哪些缓存——否则在某个工作区上打开的会话会被理解为只报告该工作区的情况。

不允许其他属性。

CacheClearResult

清空缓存回收了多少。

属性类型必需描述
clearedCacheCleared[] 或 null是每个被清空的缓存。
reclaimedBytesinteger是回收了多少字节。
reclaimedBytesTextstring是以便于人阅读的形式表示的同一数值。
scopeCacheScope是缓存应答的影响范围。其中两类缓存由本机上的所有项目共享,因此每个缓存应答都会指明它涉及了哪些缓存——否则在某个工作区上打开的会话会被理解为只报告该工作区的情况。

不允许其他属性。

RegistryListResult

此工作区用于解析的注册表。

属性类型必需描述
registriesRegistry[] 或 null是每个已配置的注册表。
credentialStateIsMachineWide布尔值是为每个注册表报告的凭据是否存在,是否为整台机器范围而非工作区范围的事实。报告此项是为了避免会话范围的回答被理解为否认更广的影响范围。

不允许其他属性。

SearchResult

本地注册表索引为该搜索提供了什么。

属性类型必需描述
recordsRegistrySearchRecord[] 或 null是匹配的记录。
indexesRegistrySearchIndex[] 或 null是每个被搜索的主机及其索引上次刷新的时间。
missingIndexHostsstring[] 或 null是没有可供搜索的本地索引的已配置主机,以便对结果偏少作出说明,而不是留待推测。
stale布尔值是是否有被搜索的索引已陈旧到值得刷新。
registriesConfigured布尔值是是否配置了任何注册表,用以区分“没有匹配项”与“没有搜索任何内容”。

不允许其他属性。

RegistryAddResult

注册一个注册表写入了什么、写入何处,以及从该注册表本身读取了什么。

属性类型必需描述
hoststring是该条目所用键的主机名,不一定与请求中的写法相同。
scopeConfigWriteScope是写入的是哪个配置文档,以及其影响范围。请求指定了一个工作区,因此不加说明的应答会被理解为针对该工作区——而对于本机范围的写入,这种理解是错误的。
trustTrustFetchOutcome是读取 registry 所公布的信任策略的结果。这些结果分开表示,因为它们含义不同:采纳了所公布的策略;registry 未公布任何策略(这不算失败);以内置基线代替并固定;或者未尝试读取。在未公布任何策略的情况下,会同时说明该 registry 是否根本无法访问。

不允许其他属性。

RegistryRemoveResult

移除一个注册表写入了什么,以及写入何处。

属性类型必需描述
hoststring是条目被移除的主机。
scopeConfigWriteScope是写入的是哪个配置文档,以及其影响范围。请求指定了一个工作区,因此不加说明的应答会被理解为针对该工作区——而对于本机范围的写入,这种理解是错误的。

不允许其他属性。

RegistryUpdateResult

刷新本地索引按主机分别做了什么。

属性类型必需描述
hostsHostUpdate[] 或 null是刷新对每个主机做了什么。
failedstring[] 或 null是刷新未能完成的主机。
indexRootstring是索引写入的目录。
registriesConfigured布尔值是是否配置了任何注册表。
reachedRegistries布尔值是在此回答中始终为 true:刷新索引会访问注册表本身,而列出注册表和搜索则依据配置和本地索引作答。某个注册表实际是否可达,由 hosts 中其自身条目的 unreachable 说明。

不允许其他属性。

LogoutResult

移除了哪个已存储的凭据,以及该存储的影响范围。

属性类型必需描述
registrystring是凭据被移除的注册表。
scopeCredentialStoreScope是凭据变更的影响范围。该存储由本机上的所有项目以及访问相同注册表的所有其他工具共享,因此应答会报告这一点,而不是让人推断其仅作用于会话范围。

不允许其他属性。

PublishEntityResult

发布实体落地了什么内容,以及落在何处。先运行了 pin 步骤的发布还会以 pin 携带该步骤所做的操作;该步骤未运行时则不存在此项。

属性类型必需描述
referencestring是实体发布所用的引用。
tagstring是发布所用的标签。
kindstring是所发布的实体种类。
mediaTypestring是为所发布字节记录的媒体类型。
sizeinteger是发布了多少字节。
sizeTextstring是以便于人阅读的形式表示的同一大小。
pluginSizeinteger否随 Plugin 实体一同发布的插件模块占用多少字节。
pluginSizeTextstring否以便于人阅读的形式表示的同一大小。
digeststring是所发布内容的摘要。在试运行时,为发布相同内容将落地的摘要,仅根据内容计算:即 aggrega push --dry-run 打印的摘要。
signed布尔值是此次发布是否附加了签名:即发布前生成的签名,或者对于已发布的版本,附加该版本所缺少的签名。
alreadyPublished布尔值是相同的字节是否已存在,因而未上传任何内容。仅在其旁附加了该发布仍缺少的内容:其发布日期,以及在此次发布进行签名时的签名;signed 表示是否附加了签名。
dryRun布尔值是此结果报告的是发布将会落地的内容,而非实际落地的内容。
reachPublicationReach是一次发布所触及的范围。这些应答的影响完全超出本机——它们附加的内容就是该注册表的每个使用者所解析到的内容——因此每个应答都会列出它访问过的每个注册表,以及该调用是否在那里附加了任何内容。
pinPinResult否固定步骤对实体旁的锁文件做了什么,或在试运行时会做什么。它是 aggrega/pin 的响应,运行了该步骤的发布会将其作为 pin 携带。
wholeDirectorySourcestring否实体按编写形式的本地源,当其写为模板时存在。这样的源只有在 Release 填充模板后才能确定其目录,因此发布会携带实体目录中的所有文件,而不仅是实体所指定的文件。仅携带这些文件时不存在此项。
windowsUnusableEntriesstring[]否已发布归档中路径含有 Windows 无法按原样保存的部分的条目——即 Windows 为设备保留的名称,如 CON、AUX 或 NUL,不论字母大小写及其后的扩展名,或者以句点或空格结尾的部分——先列出实体文档自身的文件名,再列出它携带的文件。Windows 上的工作区会拒绝解包这些条目,因此无法使用该版本;发布是继续还是停止,与不存在这些条目时完全相同。没有此类条目时不存在此项,其中包括仅以其文档发布的实体。

不允许其他属性。

PublishArtifactResult

发布文件落地了什么内容,以及落在何处。

属性类型必需描述
referencestring是文件发布所用的引用。
tagstring是发布所用的标签。
mediaTypestring是为所发布字节记录的媒体类型。
sizeinteger是发布了多少字节。
sizeTextstring是以便于人阅读的形式表示的同一大小。
digeststring是所发布内容的摘要。
alreadyPublished布尔值是相同的字节是否已存在,因而未上传任何内容。仅在制品缺少发布日期时才在其旁附加发布日期。
dryRun布尔值是此结果报告的是发布将会落地的内容,而非实际落地的内容。
reachPublicationReach是一次发布所触及的范围。这些应答的影响完全超出本机——它们附加的内容就是该注册表的每个使用者所解析到的内容——因此每个应答都会列出它访问过的每个注册表,以及该调用是否在那里附加了任何内容。

不允许其他属性。

SignArtifactsResult

签名了什么,以及签名落在何处。

属性类型必需描述
signedSignedArtifact[] 或 null是每个已签名的引用。
reachPublicationReach是一次发布所触及的范围。这些应答的影响完全超出本机——它们附加的内容就是该注册表的每个使用者所解析到的内容——因此每个应答都会列出它访问过的每个注册表,以及该调用是否在那里附加了任何内容。

不允许其他属性。

DeprecateArtifactResult

什么被标记为已弃用,以及标记落在何处。

属性类型必需描述
markedDeprecationMarked[] 或 null是每个已标记的版本。
reachPublicationReach是一次发布所触及的范围。这些应答的影响完全超出本机——它们附加的内容就是该注册表的每个使用者所解析到的内容——因此每个应答都会列出它访问过的每个注册表,以及该调用是否在那里附加了任何内容。

不允许其他属性。

ResolveResult

光标下的对象在何处定义。

属性类型必需描述
locationnull 或 Location是其定义位置。光标下没有任何内容解析到定义时为 null。

不允许其他属性。

FindReferencesResult

光标下的对象在何处被引用。

属性类型必需描述
locationsLocation[] 或 null是每个引用它的位置。

不允许其他属性。

FindImplementationsResult

哪些文档实现了光标下的对象。

属性类型必需描述
locationsLocation[] 或 null是每个实现它的位置。

不允许其他属性。

HoverResult

关于光标下的对象要显示什么。

属性类型必需描述
contentsnull 或 MarkupContent是要显示的内容。光标下的内容没有可说明的信息时为 null。

不允许其他属性。

CompletionResult

光标处可以写入什么。

属性类型必需描述
itemsCompletionItem[] 或 null是每个可以写入的内容。

不允许其他属性。

CatalogIndexResult

工作区索引包含的每个实体,以及从工作区指向外部目录和文件、未为该索引读取的链接。

属性类型必需描述
entitiesCatalogEntity[] 或 null是每个实体。
unreadLinkedDirsstring[]是工作区根目录下指向根目录之外某个目录的每个链接,按链接本身所在位置相对于根目录命名,顺序与工作区的搜索顺序一致。根目录之外的目录不会被搜索,因此这些链接背后的文档都不会作为工作区自身的实体出现在 entities 中,列出实体的客户端可以据此说明原因。不列出的有:指向根目录内部某个目录的链接,该目录在其实际所在位置被搜索或排除;位于目录会被排除之处的链接,无论是因其位置、名称还是 .gitignore 而排除;无法解析的链接,因为它不指向任何地方或形成循环;以及在按某个 Release 给出的应答中,位于只有其他 Releases 读取的目录目录下的链接。工作区中没有此类链接时为空。
unreadLinkedFilesstring[]是工作区根目录下名称像 YAML 文件(自身名称以 .yaml 或 .yml 结尾)且指向根目录之外某个文件的每个链接,按链接本身所在位置相对于根目录命名,顺序与工作区的搜索顺序一致。无论此类文件声明了什么,都不会为索引读取它,因此它声明的实体不会作为工作区自身的实体出现在 entities 中,列出实体的客户端可以据此说明原因;工作区之外的实体通过配置的目录目录读取。不列出的有:指向工作区配置将其指定为 Release(作为 build.authoring_release 或 workspace.releases 的某个键)且确实声明了 Release 的文件的链接,该文件会被读取并在链接自身位置列入 entities;指向根目录内部某个文件的链接,该文件在链接自身位置被读取;被 .gitignore 排除的链接,或位于搜索所排除目录内的链接;不指向任何文件的链接,无论是指向目录(若指向根目录之外,由 unreadLinkedDirs 列出)、不指向任何地方,还是形成循环;以及在按某个 Release 给出的应答中,位于只有其他 Releases 读取的目录目录下的链接。若工作区配置文件(其自身的 .aggrega-config.yaml 或其旁边由 CI 拥有的覆盖文件)是指向工作区之外的链接,则无论搜索是否遇到它,都会在搜索列出的链接之后列出它:此时工作区的配置完全不会被读取,本应答是在没有任何配置的情况下读取的工作区自身索引,因此不会为其读取任何目录目录,并且由配置决定的每个请求(包括按某个 Release 给出的索引)都会以读取保留的条件被该工作区拒绝。工作区中没有此类链接时为空。

不允许其他属性。

AttachCandidatesResult

哪些 Features 可以附加到该实体,以及据以判断的标签;对于请求所指定的连接,还包括其 socket 声明的 slot,以及可以填充每个 slot 的 Features。

属性类型必需描述
nodestring是为其判断候选项的实体。
nodeLabelsmap of string 或 null是判断所依据的标签。
labelSourcestring是使用的是哪一组标签,这并非无关紧要:文档声明的标签是读取源文件所能看到的,而图节点的标签是构建本身据以判断的最终集合。基于后者计算的应答是对构建将如何执行的陈述。
candidatesSourcedEntityRef[] 或 null是每个可以附加的 Feature。
slotsSlotCandidacy[]否仅当请求指定了连接时出现:该连接的 socket 声明的每个 slot,按 Component 声明它们的顺序排列,并附有可以填充它的 Features。当该连接上没有可填充的 slot 时为空,此时由 noSlotReason 说明原因——客户端应读取该原因,而不是把空列表当作没有 Feature 匹配的 slot。
noSlotReasonconst “feature-created-connection” 或 const “ad-hoc-socket” 或 const “no-slot-declared”否仅当请求指定了连接且其上没有可填充的 slot 时出现:说明为何无法在该处附加任何内容。只要 socket 声明了 slot 就不出现。该集合是封闭的。允许的值:"feature-created-connection" — 该连接由一个 Feature 绘制,而附件只能写在由组件或 Release 绘制的连接上。"ad-hoc-socket" — 该 socket 不是 Component 所声明的,因此它没有声明可供连接填充的 slot。"no-slot-declared" — Component 声明了该 socket,但未在其上声明任何 slot。

不允许其他属性。

ConnectionCandidatesResult

该实体上的每个 socket 可以连接到哪些实体。

属性类型必需描述
nodestring是这些 socket 所属的实体。
adHocSocketsAccepted布尔值是是否仍可编写该实体自身定义中未预先声明的 socket。
socketsSocketCandidacy[] 或 null是每个 socket 以及可以连接到它的内容。

不允许其他属性。

InsertionPointResult

指定容器下的新条目在文档中应位于何处,以及客户端将其写入该处所需的信息:插入点本身、文本是否必须以换行开头、仍缺失的容器键,以及每行采用的缩进。

属性类型必需描述
filestring是该文档。
containerstring[] 或 null是在文档中通往该容器的路径。
positionEncodingstring是本应答中各位置所用的编码。
positionPosition是文档中的一个位置:一行以及该行内的字符偏移量,均从 0 开始计数。偏移量以会话打开时商定的编码单位计量,除非客户端请求其他编码,否则为 UTF-16。
precededByLineBreak布尔值是在该位置写入的文本是否必须以换行开头,因为该位置位于文档已有某行的末尾。仅当文档中没有可供该条目跟随的内容时为 false。
missingContainerKeysstring[] 或 null是文档中尚未包含的容器路径段,由外到内排列。每一段都必须作为单独的键写入,并比前一段多缩进一级,然后条目才能放入最内层的那一段中。当整个路径已经存在时为 null。
entryIndentinteger是条目自身第一行的起始列,从行首开始按空格数计算。
indentStepinteger是每一嵌套层级额外缩进的量。
indentStepMeasured布尔值是该缩进步长是否根据本文档自身的嵌套测得。为 false 时,文档中没有可供测量的嵌套,该步长是回退值,因此更愿意使用自己步长的客户端知道可以自行决定。
entryShapeconst “mapping” 或 const “sequence” 或 const “unknown”是容器承载其条目的形式,它决定条目自身文本的构成方式。该形式从文档中已有的容器读取,绝不根据容器的名称推断。该集合是封闭的。允许的值:"mapping" — 容器是一个块映射,因此追加到其中的条目是一个键及其值。"sequence" — 容器是一个块序列,因此追加到其中的条目是一个短横线及其值。"unknown" — 文档中没有该容器,或该容器中没有任何内容,因此条目采用何种形式由客户端决定。

不允许其他属性。

AttachmentContainerResult

图节点上(或请求所指定的连接上)的附加项属于哪个文档,以及位于该文档中的何处。

属性类型必需描述
nodestring是附件所针对的图节点。
filestring是该附加项所属的文档。
containerstring[] 或 null是在该文档中通往其所属位置的路径。

不允许其他属性。

ConnectionAtPositionResult

该位置所在条目对应的连接,或未报告连接的原因。两部分恰好出现一个:graphNode 与 connection 同时出现,或仅出现 noConnectionReason。位于条目内任意处(其别名、目标或附加项上)的位置都在该条目内,条目嵌套时取最内层的条目;位于 socket 自身键上、即其下所写条目之上的位置不在任何条目内。

属性类型必需描述
graphNodestring否其 component 绘制该连接的节点的 id,与编译后的图所用的键一致——即候选项请求和容器请求作为 graphNode 接收的值。
connectionConnectionCoordinate否该连接,由其 socket 和别名标识,并以 document 指明读取该位置的文档——即候选项请求和容器请求作为 connection 接收的值。
noConnectionReasonconst “no-connection-entry” 或 const “feature-created-connection” 或 const “unknown-connection”否仅在未报告连接时出现:说明原因。该集合是封闭的。允许的值:"no-connection-entry" — 该位置不在任何编写附件的条目上:既不是组件以其别名编写的、绘制连接的条目,也不是 Release 中的逐边条目。以目标列表形式编写的连接,以及由 Feature 自身块绘制的连接,都没有这样的条目。"feature-created-connection" — 该位置位于 Release 为某个由 Feature 绘制的连接编写的条目上,而附件只能写在由组件或 Release 绘制的连接上。"unknown-connection" — 该位置位于 Release 为编译后的图中不存在的连接编写的条目上。

不允许其他属性。

ReleaseCandidatesResult

工作区包含的 Releases,以及从工作区指向外部目录和文件、未为其读取的链接。

属性类型必需描述
releasesstring[] 或 null是每个 Release 文档。
lockfilesmap of string是所列每个 Release 的锁文件,以所列 Release 原样作为键。每个锁文件都是 pull 为该 Release 写入、构建时读取的文件,因此客户端直接读取其所在位置,而无需自行推算。工作区不包含任何 Release 时为空。
unreadLinkedDirsstring[]是工作区根目录下每个指向根目录外部目录的链接,以链接自身所在位置相对于根目录命名,按工作区的搜索顺序排列。根目录外的目录不会被搜索,因此仅能通过这些链接到达的 Release 不在 releases 中,提供 Releases 的客户端可以据此说明原因。不列出的有:指向根目录内目录的链接,该目录在其实际所在位置被搜索或被排除;位于目录会被排除之处的链接,无论是因其所在位置还是因其名称;以及无法解析的链接,因为它不指向任何地方或形成循环。工作区不包含此类链接时为空。
unreadLinkedFilesstring[]是工作区根目录下每个按 YAML 文件命名(自身名称以 .yaml 或 .yml 结尾)且指向根目录外部文件的链接,以链接自身所在位置相对于根目录命名,按工作区的搜索顺序排列。此类文件不会被读取,因此仅能通过这些链接到达的 Release 不在 releases 中,提供 Releases 的客户端可以据此说明原因。不读取文件就无法知道它是否为 Release,因此无论文件内容如何,每个此类链接都会被列出。不列出的有:指向工作区配置以 build.authoring_release 或 workspace.releases 的键指定为 Release 的文件的链接,该文件会被读取并在链接自身位置列入 releases;指向根目录内文件的链接,该文件会被读取;位于搜索所排除目录内的链接;以及不指向任何文件的链接,无论是指向目录(若其指向根目录外,由 unreadLinkedDirs 列出)、不指向任何地方,还是形成循环。作为指向工作区外部链接的工作区配置文件,即其自身的 .aggrega-config.yaml 或旁边由 CI 拥有的覆盖文件,无论搜索是否遇到,都会在搜索列出的链接之后列出:此时工作区配置完全不会被读取,本应答在无任何配置的情况下读取,因此配置通过链接指定的 Release 都不会列出,且由配置决定的每个请求都会以读取保持的条件对该工作区拒绝。工作区不包含此类链接时为空。

不允许其他属性。

ActiveReleaseResult

客户端默认应操作的 Release。工作区未指向任何 Release 是一种普通状态而非失败,因此在此连同尝试选择的过程一起报告,而不是作为错误抛出。

属性类型必需描述
releasestring是最终选定的 Release;未选定时为空。
lockfilestring否选定 Release 的锁文件:pull 为其写入、构建时读取的文件。未选定 Release 时不存在。
reasonstring否未选定 Release 的原因。
tracestring否选择过程的每个步骤及其发现,以便调用方了解哪个步骤本可以完成选择。

不允许其他属性。

EditDocumentResult

编辑写入了什么以及写入位置。写入之后,守护进程对该文档的读取结果会被丢弃,因此关于该文档的下一个应答将基于编辑产生的字节计算。

属性类型必需描述
filestring是被编辑的文档。
editstring是所应用的编辑。
containerstring[] 或 null是文档中到达编辑落点的路径。
createdContainersstring[] 或 null是编辑过程中必须创建的容器。
writtenstring[] 或 null是被写入的文档。
contentstring是组合后的文档,用于要求显示结果而非写入的请求。

不允许其他属性。

EffectiveConfigurationResult

工作区解析出的配置,以及每项设置来自哪个文档。

属性类型必需描述
layersstring[] 或 null是被合并的配置文档,按合并顺序排列。
settingsEffectiveConfigurationSetting[] 或 null是每项解析出的设置及其来源。

不允许其他属性。

ConfigInitResult

初始化配置写入了什么、写入位置,以及从注册表读取了什么。

属性类型必需描述
hoststring是为其初始化配置的注册表。
scopeConfigWriteScope是写入的是哪个配置文档,以及其影响范围。请求指定了一个工作区,因此不加说明的应答会被理解为针对该工作区——而对于本机范围的写入,这种理解是错误的。
trustTrustFetchOutcome是读取 registry 所公布的信任策略的结果。这些结果分开表示,因为它们含义不同:采纳了所公布的策略;registry 未公布任何策略(这不算失败);以内置基线代替并固定;或者未尝试读取。在未公布任何策略的情况下,会同时说明该 registry 是否根本无法访问。
written布尔值是文档是否已写入,而非交回给调用方自行放置。
existed布尔值否当文档已存在、注册表条目被合并到其中而非新建文档时存在且为 true。只有发送 force 的请求才会在已有文档上继续,因此对未发送 force 的请求的每个应答中都不存在该字段。
contentstring否文档文本,用于要求显示文档而非写入的请求。

不允许其他属性。

ConfigCaptureResult

冻结解析后的配置时向该工作区自身文档写入的内容。

属性类型必需描述
configFilestring是被写入的文档。它始终是该工作区自身的文档,因为其目的就是使单个工作区自包含。
workspaceRootstring是请求所指定的工作区。
captured布尔值是是否冻结了任何内容。
socketsConfigCapturedSocket[] 或 null是每个被冻结的 socket 及其附件。
catalogDirsstring[] 或 null是被冻结的目录(catalog)目录。

不允许其他属性。

ImportResult

转换外部源生成了什么,以及哪些内容无法转换。

属性类型必需描述
formatstring是被转换的源格式。
outputDirstring是应答中每个路径所相对的目录,也是文件写入的目录。
writtenstring[] 或 null是每个写入磁盘的文件,按写入顺序排列:先是草稿,然后是导入写入内容的记录。在 sync 下,仅包含 sync 更改的草稿,以及记录发生更改时的记录。在 dryRun 下为空。
filesImportedFile[] 或 null是请求写入的每个文件及其文本,无论是否在 dryRun 下:先是每个草稿,然后是导入写入内容的记录。在 sync 下,是 sync 更改的每个草稿及其新文本,若记录也发生更改则随后是记录,因此已同步的 sync 应答为空列表。
driftImportDrift[]是sync 已使其与源保持一致(或在 dryRun 下将会如此)的每个部分,按草稿列出它们的顺序排列;sync 删除的草稿文件也属其中,以不含键的方式移除。对于非 sync 请求、已同步的 sync 以及转换中止(不写入任何内容)的 sync,为空列表。
diagnosticsImportDiagnostic[] 或 null是无法转换的内容。
decisionsImportDecision[]是导入器如何映射每个源节点,按导入器的顺序并与其报告完全一致:据此可以了解转换在哪些地方做了猜测。在两种交付方式下均携带,无论转换是否中止;对于不报告任何决策的导入器为空列表。
owedImportOwed[]否草稿中仍留空、既无任何来源能够提供、也无任何回答提供的每个值,按草稿的写入顺序排列——即警告类发现所指出的值。每个回答都包含此项,草稿无所欠缺时为空列表。
halted布尔值是转换是否中止,而非带着发现结果完成。

不允许其他属性。

ScaffoldEntityResult

起草的起始文档、可运行示例的列表,或已写入的示例——每种形式都以其自身的字段作答,其他字段均不出现。

属性类型必需描述
kindstring否所起草的实体种类。起草时出现。
skeletonstring否起草文档的文本。起草时出现。
examplesScaffoldExample[]否文档发布的每个可运行示例,每个出现一次,按名称排序。在找到了示例的列出操作中出现。
examplestring否已写入的示例。写入时出现。
dirstring否示例被写入的目录,相对于工作区根目录,取请求所指定的名称,或在请求未指定时取示例的名称。写入时出现。
filesstring[]否写入的每个文件,相对于 dir 并以斜杠分隔,按文档中携带它们的顺序排列。写入时出现。
nextstring[]否示例页面给出的用于构建该示例的命令,按页面书写的原样逐行列出,包括注释:即其 Build 标题下的第一个 shell 代码块。页面未给出时不出现。
versionstring否读取示例所用的文档版本:若为该二进制文件发布了文档,则为二进制文件自身的版本,否则为在其之前发布的最新版本。写入时出现。

不允许其他属性。

ScaffoldExample

文档发布的一个可运行示例。

属性类型必需描述
namestring是示例的名称,请求将其作为 example 发送以写入该示例。
levelstring是示例页面为其声明的级别。
summarystring是示例页面的第一句话。

不允许其他属性。

LintResult

约定检查的发现,按严重程度计数,并按文档列出。针对每个 Release 各运行一次的全目录检查还会带有 passes;此时计数和文件涵盖所有轮次的总和。

属性类型必需描述
entitystring否请求指定了实体时,被检查的那一个实体。
releasestring否请求指定了 Release 时,其闭包被检查的那个 Release。
checkedinteger是检查了多少个文档。检查针对每个 Release 各运行一次时,为各轮次之和:被两个轮次读取的文档在每个轮次中各计一次。
findingsinteger是发现的总数。
errorsinteger是其中错误的数量。
warningsinteger是其中警告的数量。
infosinteger是其中提示信息的数量。
filesLintFileFindings[] 或 null是按文档列出的发现。
halted布尔值是检查是否中止,而不是带着发现完成。
passesLintPass[] 或 null否逐轮次给出的全目录检查;仅当工作区在 workspace.releases 下指定了 Releases、因而检查针对每个 Release 各运行一次时才出现。每个轮次说明其发现是针对哪些 Releases 得出的。对于未指定任何 Release 的工作区(它只在自己的目录上检查一次),以及对单个实体或某个 Release 闭包的检查,此项不出现。

不允许其他属性。

LintPass

在为其 Releases 各自提供目录目录的工作区中,全目录约定检查的一个轮次:该轮次所针对的 Releases、所读取的目录,以及在其中的发现。

属性类型必需描述
releasesstring[] 或 null是该轮次所针对的 Releases,每个都是相对于工作区根目录的路径。读取相同目录目录的 Releases 共享一个轮次。
catalogDirsstring[] 或 null是该轮次读取的目录目录,按搜索顺序排列;位于工作区根目录内的,均相对于根目录给出。若其 Releases 未读取任何目录目录则为空,此时该轮次未检查任何内容,也不会使其他轮次失败。
checkedinteger是该轮次检查了多少个文档。
findingsinteger是该轮次的发现数量。
errorsinteger是其中错误的数量。
warningsinteger是其中警告的数量。
infosinteger是其中提示信息的数量。
filesLintFileFindings[] 或 null是该轮次按文档列出的发现。

不允许其他属性。

PluginAddResult

挂接插件写入了什么、写在哪里,以及固定了哪个版本。

属性类型必需描述
typestring是插件所挂接的 socket。
identitystring否该挂接解析得到的标识。
uristring否该附件解析所依据的引用。
capabilitystring否该附件所针对的能力。
referencestring否固定的引用,包含版本。
scopePluginWriteScope是插件变更写入了哪个配置文档,以及其影响范围。命令扩展插槽自身的默认值是本机范围的文档,因此每个应答都会说明它写入了哪个文档。
written布尔值是配置文档是否已写入,而不是交还给调用方自行放置。
contentstring否配置文档的文本,用于要求展示而非写入该文档的请求。
retractionPluginRetraction否弃用标记如何影响所固定的插件版本。
withdrawn布尔值否当查询指明了被固定的版本,且本工作区信任的撤回声明已撤回该版本时为 true。指明的版本照样会被固定,因为指明它本身就是覆盖。否则不出现,而不出现并不表示该版本未被撤回:若无法读取指明版本的撤回标记,retraction.unscreened 会说明原因;未指明版本时,会选择已发布的最新版本,并由 retraction 报告撤回检查对这一选择得出的结论。

不允许其他属性。

PluginRemoveResult

解除挂接插件写入了什么,以及写在哪里。

属性类型必需描述
typestring是插件所挂接的 socket。
querystring是移除了哪个挂接。
scopePluginWriteScope是插件变更写入了哪个配置文档,以及其影响范围。命令扩展插槽自身的默认值是本机范围的文档,因此每个应答都会说明它写入了哪个文档。

不允许其他属性。

PluginSyncResult

将 Plugin 实体中由机器维护的记录与其模块对齐时所做的更改。

属性类型必需描述
entitystring是被对齐的 Plugin 实体文档。
hostFunctionsstring[] 或 null是模块声明其所需的宿主函数。
commandsPluginCLICommand[] 或 null是模块提供的命令。
changed布尔值是文档中是否确实有内容发生了变化。

不允许其他属性。

PluginGenCatalogResult

一次生成所产生的目录文档。

属性类型必需描述
documentsPluginGeneratedDocument[]否每个生成的文档及其文本。
noticesstring否生成过程希望调用方知晓的任何信息。
dryRun布尔值是文档是否被交还而非写入。

不允许其他属性。

ExplainErrorResult

编译器对某个情况的声明,以及讲解如何在编写时修复它的已发布段落。

属性类型必需描述
shortCodestring是该情况的短代码。
codestring是该情况的描述性名称。
messagestring是该情况被触发时所给出的信息。
entriesExplainErrorEntry[]否讲解修复方法的已发布段落。
referencestring是说明该情况的已发布地址。
notestring否无法获取已发布段落时,说明其缺失的原因。二进制文件本身声明的内容仍会给出。

不允许其他属性。

GetSchemaResult

某个类型的 schema,或者——在请求未指定类型时——可以指定哪些类型。这两种范围由同一个应答承载,而不是分成两个方法,因为“我可以指定什么”和“作者会为其中哪些编写文档”是同一个问题的两种范围,两个应答还必须保持一致。

属性类型必需描述
kindstring否该 schema 所对应的类型。
schemaany否schema 本身,按二进制文件所持有的原样传递。
kindsstring[]否该二进制文件可响应的每个标记。
entityKindsEntityKindDescriptor[]否作者会为其编写文档的较小集合,每一项都将请求所指定的标记与文档自身头部声明的类型配对。

不允许其他属性。

SkillsInstallResult

安装助手技能写入了什么,以及写入位置。

属性类型必需描述
skillstring是被写入的技能。
installedSkillsInstalledFolder[]是写入的每个技能文件夹,按请求指定助手的顺序排列。读取同一个共享文件夹的助手共用一个条目,因为技能只在那里写入一次。
scopeSkillFolderScope是技能安装的影响范围。请求指定一个工作区,因此一个什么都不说明的应答会被理解为仅涉及该工作区——而对于助手在每个项目中都会读取的用户级文件夹,这种理解是错误的。

不允许其他属性。

SkillsInstalledFolder

一次安装写入的一个技能文件夹。

属性类型必需描述
agentsstring[]是读取此文件夹的已指定助手的标识符,按请求指定它们的顺序排列。
folderstring是技能的文件夹,以绝对路径表示。
replaced布尔值是带有该技能每个写入副本都携带的注释行的副本(由先前的安装写入,或取自已发布的技能仓库)是否已存在并已被替换。该位置上不带此行的文件会被拒绝,而不是被替换。

不允许其他属性。

SkillsListResult

二进制文件附带的技能,以及安装可以为其写入这些技能的每个助手。不写入任何内容,也不访问任何地方。

属性类型必需描述
skillsSkillsListedSkill[]是二进制文件附带的每个技能,按固定顺序排列。
agentsSkillsListedAgent[]是安装知道其技能文件夹的每个助手,按标识符排序。

不允许其他属性。

SkillsListedSkill

二进制文件附带的一个技能。

属性类型必需描述
namestring是技能的名称,也是安装所写入文件夹的名称。
descriptionstring是助手何时使用该技能,以技能自身的声明为准。

不允许其他属性。

SkillsListedAgent

安装可以为其写入技能的一个助手,以及它从中读取技能的两个文件夹。

属性类型必需描述
idstring是请求用来指定该助手的标识符。
namestring是助手自身的名称。
projectFolderstring是助手从中读取项目技能的文件夹,相对于项目根目录并以斜杠分隔。项目级安装会在请求所指定的工作区中,将技能的文件夹写入其中。
userFolderstring是助手在每个项目中从中读取用户自身技能的文件夹,相对于主目录并以斜杠分隔。带 global 的安装会将技能的文件夹写入其中。

不允许其他属性。