Aggrega 视图
拓扑图在其自己的面板中打开,详见拓扑图;Commands 面板上的按钮所运行的命令详见命令。
Aggrega 活动栏视图 — 按阅读顺序排列的四个面板:Commands、Registries、Catalog 和 Plugins。其余三个面板列出你的配置和工作区所包含的内容,每个面板的开头都是作用于其所列内容的操作,以带标签的行的形式位于列表顶部;其他所有操作都是 Commands 面板上带标签的按钮,因此每个操作都只有一个查找的位置。作用于某个特定注册表、实体或插件的操作位于该项所在的行上。
Commands 面板顶部有三个单行条目,标明编辑器当前作用的对象 — 先是 Project folder,然后是 Aggrega workspace,然后是 Release — 每一行都会打开各自的选择器。中间一行的名称以缩写形式显示为 Agg. worksp.,以便每一行的值能占用更多的面板宽度;其悬停提示会给出完整名称 Aggrega workspace,所有与它相关的消息也是如此。它们的值排在同一列中,位于三个标签中最宽的那个之后;如果面板太窄,放不下该标签,标签会以省略号截断,而不会把面板向侧面撑开,该行的悬停提示仍会说明它是哪一行。它们按此顺序排列,是因为每一行都位于其上一行之内,这种排列方式直接展示了这一点,而无需解释。中间一行保留产品名称(无论是否缩写),因为单独的“工作区”已经指代窗口中打开的那组文件夹。Aggrega workspace 行标明语言服务器所锚定的文件夹,Release 列表正是相对于它计算的;悬停在其上会显示完整路径,并且当它与你打开的文件夹不同时,也会给出你打开的那个文件夹 — 这样你就能弄清楚为什么提供的 Releases 恰好是这些。如果窗口中恰好只打开了一个文件夹,Project folder 行的悬停提示会说明它是唯一的一个,而不是让你去打开一个只有一项的列表,并在结尾说明在这种情况下点击该行会提供什么 — 打开一个文件夹,或向窗口添加一个文件夹 — 如果没有选择任何 Release,且尚未读取此 Aggrega 工作区所提供的内容,悬停提示会如实说明,而不是去猜测。如果某一层级什么都不包含,悬停提示会指明摆脱该状态的方法,而不是让你去选择:未选择任何内容和没有可选择的内容读起来不同,因为只有前者是一个等待你做出的决定。对于不包含任何 Aggrega 工作区的项目,解决办法是打开一个包含工作区的文件夹或新建一个;对于不包含任何 Release 的 Aggrega 工作区,解决办法是改在另一个工作区中工作或起草一个 Release。

Aggrega workspace 行和 Release 行的右侧各有一个 +,位于行旁而不是行上:按下该行会在现有的项中进行选择,按下 + 则会进入新建流程。Release 的 + 打开的起草流程与 Catalog 面板顶部的 Draft entity 相同,只是种类已经确定:它只询问名称,提示文字也会说明正在为一个 Release 命名。Project folder 行没有这个按钮 — 创建项目文件夹是你的编辑器的事,而不是 Aggrega 的事。
如果你的 Aggrega 工作区不是你打开的文件夹 — 它位于该文件夹之上,或在其内部 — Aggrega workspace 行还会带有另一个控件,用于将该工作区作为你的项目文件夹打开。它只是提供给你,而不会替你执行;它的名称既说明它通向哪里,也说明代价:打开文件夹会重新加载窗口,因此语言服务器和本扩展都会重新启动,窗口中所有未保存的内容也会随之丢失。如果你打开的文件夹本身就是 Aggrega 工作区,则没有什么可打开的,该控件也不会显示。
当窗口打开的文件夹所属的 Aggrega 工作区位于该文件夹之外时 — 既不是该文件夹,也不在其内部 — 编辑器还会在一个对话框中说明这一点,你需要先关闭它才能继续:对话框以 Aggrega is using a workspace from outside the folder you opened. 开头,下面是一行 Aggrega workspace: 和一行 Project folder:,分别给出两者的完整路径。它的按钮有 Open workspace (reloads the window),它会像该行自身的控件一样将 Aggrega 工作区作为你的项目文件夹打开;Continue here,它关闭对话框且不做任何更改;以及 Don’t show again for this folder。以其他任何方式关闭对话框 — 按 Escape 键,或使用其自带的关闭控件 — 都等同于 Continue here。在每个窗口中,该对话框针对一个文件夹出现一次;如果该文件夹所属的 Aggrega 工作区发生变化,它会再次出现;选择 Continue here 后,它不会再出现,直到窗口重新加载或再次打开,届时它会再次出现。Don’t show again for this folder 会针对该窗口记住,并在你重新打开窗口时恢复,因此该对话框不会再针对该文件夹出现。这三个选项都不会消除事实本身:只要工作区位于你的文件夹之外,Aggrega workspace 行的值右侧就会带有一个警告标记,悬停在该行上会显示与对话框相同的标题和相同的两个路径。位于你所打开文件夹内部的 Aggrega 工作区并不在其之外,因此不会弹出对话框,其所在行也没有标记和这样的标题;悬停在该行上仍会显示你打开的文件夹,将工作区作为你的项目文件夹打开的控件也仍会显示。
除非编辑器的 window.dialogStyle 设置为 custom,否则该对话框由你的操作系统绘制,因此默认情况下它遵循桌面的主题而不是编辑器的主题,任何扩展都无法改变它的外观;当 window.dialogStyle 设置为 custom 时,编辑器会使用自己的主题绘制它。
无论你已附加了什么,点击 Aggrega workspace 行都会打开选择列表,即使只有一个工作区或一个都没有也是如此:选择器列出你的 Project folder 所能到达的 Aggrega 工作区 — 从它向上逐级查找,并在其内部的所有内容中查找 — 每个工作区以其自身的根目录命名;最后一项是一种到达窗口根本没有打开的文件夹的方式:Choose another folder Aggrega recognises…,或者在选择器没有可列出的工作区时为 Choose a folder Aggrega recognises…。之所以有最后这一项,是因为可到达的范围受窗口所包含内容的限制:你的编辑器只会在你打开的文件夹中搜索,因此位于其他位置的工作区只能通过添加其文件夹来到达,没有更短的途径。只要向上查找找到了起点,语言服务器就会立即启动,而不会等待该搜索完成,因此窗口可能先完成附加,片刻之后才报告还有第二个工作区可以到达 — 选择器中的列表会在搜索返回时跟上。此窗口上次工作所在的 Aggrega 工作区也会立即被重新采用,包括你在 Project folder 内部选择的工作区,因为编辑器直接询问该工作区自身的标记,而不是等待搜索;只有当该标记已经消失,或不再标记你的 Project folder 所能到达的工作区时,该选择才会被放弃,并且会通知你。选择另一项会将语言服务器移到那里,并且无论该项是从当前使用的同一文件夹到达还是从另一个文件夹到达,都会告知你;选择已在使用的项则不会重启任何东西,并会告知编辑器已在何处工作:Aggrega: the editor already works in ⟨path⟩.,其中完整写出工作区根目录。同时从两个打开的文件夹到达的同一个 Aggrega 工作区是一个条目,也只算一个:发现过程是向上攀升的,因此上一级的根目录会代表其下方的每个文件夹,而去问这些文件夹中哪一个包含该工作区,将是一个有两个正确答案的问题。
点击 Project folder 行会打开同类的选择:窗口中已打开的文件夹,各自以其路径命名,最后是两种到达窗口未打开文件夹的方式。Open folder… 通过编辑器的文件夹对话框(其按钮显示为 Open)请你选择一个文件夹,并在此窗口中打开所选文件夹,替换窗口中已打开的内容,与编辑器自身的 Open Folder 相同。这会重新加载窗口,该条目的描述会事先说明;如果编辑器无法打开该文件夹,会告知你。Add folder to this window… 以同样方式询问,按钮显示为 Add,并将所选文件夹添加到窗口中已打开的文件夹之后,作为编辑器工作所基于的文件夹:你是在此行上选择它的,因此该行直接显示它而不会再次询问,提供的 Aggrega 工作区就是它所能到达的那些。在已基于工作区文件打开的窗口中,该文件夹会就地加入其中,并告知你编辑器现在基于它工作。窗口中已打开的文件夹不会被再次添加,并会告知你;如果编辑器拒绝该文件夹,也会告知你,编辑器继续基于原来的文件夹工作。不做选择就关闭任一对话框不会改变任何内容。
向只有一个文件夹或没有文件夹的窗口添加文件夹,会使该窗口成为多根工作区,编辑器通过重启其扩展(包括本扩展)来完成这一点,在 dev container 等远程窗口中则通过重新加载窗口来完成。如果扩展重启时欢迎页处于打开状态,它会在原位置重新绘制,因此窗口仍只有一个页面,且该页面反映窗口当前的状态。Add folder to this window… 和 Aggrega 工作区选择器的最后一个条目都会以这种添加结束,因此在选择其中任何一个会导致这种情况时,其描述会事先说明。该工作区对编辑器来说是新的,启动时不带你离开的那个窗口所记住的内容,只保留添加操作本身给出的那一个答案:通过 Add folder to this window… 添加的文件夹就是那里的 Project folder,而通过 Aggrega 工作区选择器的最后一个条目或欢迎页的 Use a folder that already has one 选择的 Aggrega 工作区就是那里的 Aggrega 工作区。你之前选择的 Release,以及你曾要求对话框不再显示的那些文件夹,都留在你离开的那个窗口中。
你的选择会为该窗口记住,并在重新打开时恢复,它决定下方那一行提供什么——提供的 Aggrega 工作区就是该文件夹所能到达的那些。到达不等于包含:由于发现过程向上查找,一个文件夹到达的工作区往往是其上层文件夹,因此选择仓库的某个子目录,仍会提供仓库本身的工作区。只打开一个文件夹时无需选择,该行直接显示它。打开多个文件夹且未选择任何一个时,该行显示 none selected,提供的 Aggrega 工作区是整个窗口所能到达的那些。如果只有一个,或其中之一是此窗口上次工作的那个,语言服务器就在那里启动;如果有多个且都未被记住,则在你选择一个之前不会启动,状态栏的 Choose Aggrega workspace… 和一条通知会请你选择。语言服务器自行停止或启动失败时,Project folder 行仍显示你的文件夹——你的工作区仍处于选中状态,报告服务器状态的是语言服务器指示器。
这些行下方的操作按你要做的事分组:Build(validate、lint、build、preview、graph)、Dependencies(pull)、Author(import、inspect)、Publish(push、sign、deprecate)和 Configuration(show config、cache)。
Commands 旁边有:Registries 面板,以 Add registry 和 Update index 开头,列出生效配置所声明的每个注册表;Catalog 面板,以 Search catalog 和 Draft entity 开头,列出工作区可见的实体;以及 Plugins 面板,以 Add plugin 和 Generate entities 开头,列出内置和已配置的 Wasm 插件。这些首行是面板自身列表的一部分:每一行都带有标签和图标,因此无需指向任何东西即可看到,按下它即运行该操作,折叠面板时它会随其余内容一起收起。无论下方列表显示什么,它们都在那里——包括列表显示未配置任何内容时,那正是你要添加第一项的时候,以及列表显示没有可用的 Aggrega 工作区时。某一行尚无法运行时,它会留在原处,并在名称旁说明原因,用词与 Commands 面板对同一状态的描述相同,按下它不会运行任何操作。这三个面板的标题栏中都还有一个刷新按钮,它重新读取该列表,除此之外别无其他——放在那里的操作会是一个没有标签、需要悬停才能发现的图标。Validate、build、preview build 和 lint 的结果报告到 Problems 面板;基于命令行的操作将其输出流式写入 Aggrega 输出通道。

Commands 面板
-
一个设置界面,从齿轮图标进入 — Commands 面板右上角有一个齿轮图标,它会打开编辑器自身的设置,并筛选到本扩展。扩展没有自己的第二个设置页面,因此每项偏好只有一个存放位置和一个写入位置。每项偏好都属于你,而不属于项目;参见设置。
-
Commands 面板的两种形态 —
aggrega.operations.layout在buttons(默认值)和sections之间选择:前者中每个操作都是一个连续流中的带标签按钮,完全没有分组标题;后者中每个分组都是一个在其标题下展开的部分,面板显示的内容取决于你保持展开的部分。两种形态包含相同的分组和相同的操作,顺序也相同;该设置改变的是分组的绘制方式,而从不改变存在哪些操作。在两种形态中,Project folder、Aggrega workspace 和 Release 行都位于所有操作之上,因此关闭某个部分永远不会拿走那些说明操作将作用于什么的事实。在sections中,Build 旁边的插入符号是位于其下方的独立一行,在其 V 形箭头前显示 Build options,因此不会被误读为一个可展开的部分。更改该设置会重绘已打开的面板,不会重启任何东西。Commands 面板打开时在侧边栏中所占的份额比它旁边的三个面板更大——在高 900 像素的窗口中,足以在侧边栏默认宽度下显示其完整的流;此后编辑器会为每个工作区保留各面板的高度,因此侧边栏此前已布局过的工作区会保留其原有高度。 -
提供选择的按钮会在自身旁边呈现该选择 — 对于按下后会询问作用于哪一个或哪个实体的操作,其选择以你所按按钮旁边的菜单形式呈现,而不是以占据整个窗口的对话框呈现:Cache… 提供四种缓存操作,Inspect 和 Push 提供工作区可见的实体。菜单在按钮下方或上方打开,取决于面板哪一侧空间更大,且高度不超过该空间,因此永远不会超出面板边缘——比空间更长的列表在菜单内部滚动——而其名称,即它在选择什么,在你滚动时始终位于顶部。无论面板位于何处都是如此,包括停靠在较矮的侧边栏中。菜单只能通过按下按钮到达,而不能通过 Tab 键到达,因此无论面板包含多少菜单,它仍只占一个停靠点。在菜单内,方向键在选项之间移动,Enter 选取当前所在的选项;输入会缩小列表——匹配的是选项名称或其下方那行文字的片段,菜单会说明还剩多少项——Backspace 撤销你输入的内容,Escape 关闭菜单并将焦点放回按钮上,而在其他任何地方按下——在面板中或编辑器中的其他任何位置——会关闭菜单且不运行任何东西。相同的操作也在编辑器的命令索引中,那里没有可供菜单在旁边打开的按钮,因此从那里调用时,每个操作都会以一个供你挑选的列表提出问题。

-
需要请求选项的菜单会说明它正在读取 — Inspect 和 Push 打开的菜单在语言服务器回答工作区包含哪些实体之前是空的,而这一读取会显示进度并且可以停止。两者打开时都会显示一行说明正在读取,并在答案到达时填充,而不是空着打开:空的选项列表读作什么都没有,这与请稍候是不同的答案。读取进行期间你输入的内容,在选项到达后仍然生效。如果没有可提供的内容——没有该操作能够指明的实体——菜单会关闭,并显示一条说明此情况的消息,与从命令索引运行该操作时得到的消息相同,而不是显示一个空菜单。
-
选择与同意始终是不同的行为 — 菜单是你说明哪一个的地方,它从不附带确认。三种会删除内容的缓存操作在你做出选择后仍会弹出模态确认,指明该操作涉及的缓存;生成 Plugin 实体在写入之前也仍会确认。确认值得它带来的打断:把确认合并到内联列表中,会让一次误点就清空缓存。已发布目录搜索保留其筛选列表,你在编辑每个维度后都会回到该列表,因为菜单不适合每次回答后都要重新进入的东西。
-
每种形态中分隔各分组的方式 — 在流式形态中,分组之间不绘制任何东西:分组决定按钮出现的顺序,而顺序就是承载分组的全部,因此面板不会把宽度花在分隔线上。在分区形态中,Publish 分组上方带一条分隔线,因为它的操作会改变每个解析该目录的人所得到的内容,而其余操作只作用于本机——这是性质上的差异,值得标记一次,而且有一个分组框可供标记。
-
窄面板会换行,而不是截断或横向滚动 — 流会按宽度需要占用任意多行,且没有固定的换行位置:加宽面板,按钮就会重新排列到更少的行上。每个按钮的标签只有操作名称,说明放在其悬停提示中,因此每一行能容纳尽可能多的操作。没有任何东西隐藏在横向手势之后,也没有标签被截短。
-
每个操作在运行前都会询问所需的内容 — 面板能看出不可运行的操作会留在原处,呈灰色,并说明原因:悬停在其上会指明缺少什么,屏幕阅读器会以相同原因将其播报为不可用。它不会被移除,因为在按钮流中移除一个按钮会使其他按钮移到你的指针下方,此时按下就会落在与片刻前不同的东西上——这也是为什么在 Build 无法运行时,Build 旁边的插入符号仍留在其旁边,随之变灰,给出相同的原因且不打开任何东西。有两种情况会使控件变灰:作用于 Release 的操作需要选中一个 Release,运行
aggrega二进制文件的操作需要一个已锚定的工作区文件夹来运行。只需要语言服务器的操作在服务器停止时不会变灰——按下时它会报告编译器自身的消息,而指明该状态的地方是状态栏。推送、签名和弃用都会先询问其对象:推送提供 Catalog 面板所列、且在工作区中有文档的实体,而签名和弃用则询问对注册表中已有制品的引用,因为这正是这两者所修改的。弃用还会询问严重程度和原因,这是编译器所要求的,而编译器无法在编辑器内部向你询问。拉取针对所选的 Release 运行,而不询问对象。位于 Registries、Catalog 和 Plugins 面板顶部的操作以同样的方式询问:添加注册表会询问主机以及要写入哪个配置文件,添加插件会询问其类型所需的两三个问题,生成 Plugin 实体会询问要涵盖什么以及写到哪里,已发布目录搜索会打开一个你在运行前组装的筛选列表,起草实体会先询问种类,然后询问名称。除 Draft entity 外,每一项都需要一个已锚定的工作区文件夹,因此没有该文件夹时,每个这样的行都会在其名称旁说明这一点,按下也不会运行任何东西——你会在回答任何问题之前而不是之后得知。Draft entity 只需要语言服务器,因此永远不会被绘制为无法运行。
注册表、编目和 Plugins 面板
-
注册表面板详情 — 每一行列出注册表的主机、已配置的别名、哪个注册表是默认注册表、从该注册表拉取的制品是否要求签名,以及该主机的凭据是否存在。读取列表不会联系任何注册表:凭据状态只报告是否存在,因此它表示凭据存在,而不表示注册表会接受该凭据。
作用于整个集合的操作是面板的前两行 — 添加注册表,以及会更新每个已配置注册表的可搜索索引的更新索引 — 而作用于单个注册表的操作位于该注册表所在的行上:仅为它更新索引、移除其已存储的凭据,以及移除该注册表。面板自身的标题栏只有刷新。
添加注册表和移除注册表都会询问要修改哪个配置文件,并首先提供这台机器上所有项目共享的全局文件,因为除非你另有指定,这两个操作都会写入该文件;另一个选项是本项目自己的配置文件。两者结束时都会指出实际修改的文件以及该文件的影响范围,这些信息取自编译器实际执行的操作,而不是所请求的内容。语言服务器在启动时读取其配置,因此这两个操作之后都会在不询问的情况下重启语言服务器,待其恢复后会重新读取面板和欢迎页面的注册表步骤:你添加的注册表会出现在列表中,或者你移除的注册表会消失,无需重新加载或刷新。重启后的服务器读取了该更改后,结束消息会补充说明更改现已生效;如果重启失败,则不会补充,因为此时更改已写入文件但尚未生效。
移除注册表和移除凭据都会先请你确认,并且都会说明更改的影响范围:注册表的确认会指出你所选的文件,因此从全局文件中删除条目会被描述为影响所有通过该文件进行解析的项目,而从本项目自己的文件中删除条目则被描述为不影响任何其他项目;凭据则会从共享的凭据存储中删除,注册表条目保持不变。移除凭据不提供文件选择,因为凭据存储由这台机器上的所有项目共享,没有可写入的按项目形式。
构建索引会显示进度并且可以停止,它也是这些操作中唯一提供“取消”按钮的操作。按下该按钮会终止遍历本身,而不仅仅是编辑器的等待,构建结束时会说明已被停止。每个注册表的记录只在其自身的遍历完成后才写入,因此被停止的构建会保留已完成遍历的注册表的索引,而正在遍历的注册表则保持其之前的索引不变 — 因此这是停止,而不是撤销。运行到结束的构建会指出从多少个注册表索引了多少个实体,以及索引写入的目录,这表明刷新不会改变本机上其他项目进行解析时所依赖的任何内容;无法索引的注册表会连同编译器自身给出的原因一起列出:无法访问的注册表会被说明为未能访问 — 在该原因之前显示 无法访问 ⟨注册表⟩: — 而已响应但以其他方式失败的注册表,例如其仓库列表出现重复的注册表(这会终止该注册表的遍历,而不是再次循环跟随,同时其他注册表仍会继续索引),会被说明为无法索引;结尾句会将这两组分开列出。更新单个无法访问的注册表的索引也以同样的方式结束,将其指明为未能访问。
添加注册表同样会访问网络,因为它会获取注册表公布的信任策略,并且不提供“取消”按钮;无论哪种情况,结束时都会指出它写入的文件。无法访问的注册表会在该结束消息中被指明为未能访问,并置于编译器自身给出的原因之前,而不是被说成未公布任何策略 — 官方 hub 也是如此,此时其条目会带有内置的基线。如果官方 hub 以外的注册表未公布信任策略或无法访问 — 或者在工作区离线时因无法获取任何策略而被拒绝 — 结束消息之后会出现一个问题,提议手动固定一个策略,提供的内容与命令行的
--identity和--key在这种情况下接受的内容完全一致:无密钥身份(每个写作identity=issuer,一次输入一个)、在文件对话框中选择的公钥文件、两者皆有,或两者皆无。你提供的内容会在同一文件中为同一主机重新注册,该结束消息会说明条目现在带有哪种策略,而不会重复身份或文件;格式错误的身份,或者无法读取或不是公钥的密钥文件,会以编译器自身的拒绝结束。对非公钥文件的拒绝会指出编译器期望的内容,并省略文件所包含的内容,因此误选的私钥既不会出现在通知中,也不会出现在 Aggrega 输出通道中。在任一提示中按 Escape,或选择“两者皆无”,都不会固定任何内容,生效的是命令行在未提供这两个标志时所保留的状态。已固定其公布策略的注册表,以及使用内置基线的官方 hub,不会被询问。移除注册表、移除凭据和读取列表都不会联系任何注册表。面板不提供登录注册表的操作,因为该命令从终端读取密码,而按钮背后没有终端 — 请在终端中运行它,然后按刷新。
-
编目面板详情 — 工作区可见的实体,按种类分组在各自的标题下,每一行列出实体及其声明的标签,工具提示中显示其 apiVersion 和描述。这些行来自两个位置,每一行都会注明来自哪里。由工作区中的文档声明的实体会在工具提示中显示该文档的路径,单击该行会打开该文件。从编目目录解析的实体 — 即工作区根目录下的
catalog/目录,以及你的配置在workspace.releases下为所选 Release 指定的目录,或者在未为其指定任何目录或未选择任何 Release 时,在workspace.catalog_dirs下为整个工作区指定的目录 — 会标记为来自该处且不带路径:工作区中没有它自己的文件,因此该行会指出它的来源,而不是提供一个无处可去的单击。列表属于所选的 Release:位于你的配置仅为其他 Releases 指定的目录下的文档不会出现在其中,因此当每个 Release 都从自己的目录读取同一实体的一个变体时,面板只列出所选 Release 的变体。未选择任何 Release 时,会列出工作区中的每个文档。未声明
kind:或metadata.name:的文档不会列出,正是这一点使面板成为实体的索引,而不是文件的索引。语言服务器不会通过指向工作区之外的链接读取任何实体——无论是指向外部目录的链接,还是以 YAML 文件命名、指向外部文件的链接——因此这类链接背后的实体都不会被列出,尽管编辑器的文件树会显示它。唯一的例外是工作区配置以
build.authoring_release或以workspace.releases的键所指定的 Release,它会通过其链接被读取,并列在链接本身所在的位置。列表省略此类链接时,会在列表之后用单独一行说明:通过此链接到达的实体未列出,因为它指向 Aggrega 工作区之外: 后接该链接相对于工作区的路径——如有多个,则为 通过这些链接到达的实体未列出,因为每个链接都指向 Aggrega 工作区之外: ,先列出指向目录的链接,再列出指向文件的链接。将指针悬停在该行上可看到完整的句子,因为较长的路径在行中会被截断。选中某个 Release 时,位于只有其他 Releases 才读取的编目目录中的链接不会被指明,因为其背后的内容本来就不会为该 Release 列出。该列表是语言服务器自己的应答,因此它列出的实体与编译器读取的相同——包括编辑器中未保存的缓冲区,它们优先于磁盘上的字节——并按服务器发送的顺序呈现,而不会在这里重新排序。面板会在以下情况下自行重新读取列表:语言服务器变为可应答时,所选 Release 变化时,窗口所打开文件夹中的某个
.yaml文档在磁盘上被创建、修改或删除时——无论是由编辑器、终端还是检出操作造成——以及编辑器关闭某个 YAML 文档时。只有在语言服务器丢弃了它为该文件保留的内容之后,面板才会请求列表,因此在编辑器中打开时被删除的文件会离开列表,而不是根据编辑器最后发送的副本被报告;在缓冲区中重命名后未保存就关闭的文档会按磁盘上的状态重新列出;一连串此类更改和关闭只会触发一次读取。编辑器在释放文档时才关闭它,而它并不保证在文档标签页关闭的那一刻就这样做,因此根据标签页已关闭的文档的文本生成的行可能会一直保留,直到编辑器关闭该文档。面板不会自行跟随你的输入。仍在未保存缓冲区中的更改会在你在该文档中暂停输入后发送给语言服务器——每个打开的文档各自等待自己的暂停,因此在一个文档中输入永远不会耽搁另一个——并在此后下一次读取列表时显示。按下面板的刷新按钮时,会按编辑器在你按下那一刻所持有的内容为每个打开的文档读取列表,无论距你上一次按键或撤销有多短:尚未发送的更改会立即发送,并且只有在语言服务器对截至按下时发送给它的每一项更改都作出应答后,才会请求列表。整个被删除的文件夹会在下一次读取列表时或按下刷新时显示,因为编辑器可能将其报告为对该文件夹的一次更改,而不是对其中每个文档的一次更改。搜索已发布的编目是该面板的第一行 Search catalog:它会询问筛选条件,并复制你所选内容的引用。起草新实体是第二行 Draft entity:它以可选列表的形式询问种类,并在标签页中打开起始文档,而不向磁盘写入任何内容。该面板自己的标题栏只有刷新按钮。作用于单个实体的操作位于该实体的行上,并且只有当编译器针对该行的种类接受某个操作时,该行才会提供它。每个操作接受哪些种类,是语言服务器自己的应答,每次都会随列表重新读取,因此这些行跟随你正在运行的编译器,而不是扩展中维护的列表。查看实体解析为什么,是唯一无需打开行菜单即可使用的操作:它按实体名称定位实体,而每一行都带有名称,因此无论工作区是否包含该实体的文档,只要编译器能将名称解析为该种类的实体,行上都会提供该操作,而且它不会更改任何内容。
验证实体、检查其发布约定以及发布实体都需要实体的路径,因此只有当行的实体由本工作区中的文档声明时才会提供这些操作;从已配置的编目目录解析出的行在本工作区中没有可提供给它们的路径,因此这些操作不会在这样的行上提供,而不是作为只会报告缺少参数的控件提供。在这三项中,检查发布约定会在每一个这样的行上提供。验证只在编译器能单独检查该种类文档的地方提供:例如,Aggregate 位于编目目录中时会与整个编目一起检查,并与部署它的 Release 一起检查,因此它的行不提供验证。验证按所选 Release 的条件检查实体,就像在终端中运行
aggrega validate <path> --release <Release>那样,因此实体所引用的内容——Recipe 所实现的 Component、其架构所组合的库——会通过该 Release 构建时所依据的编目目录来解析;未选择 Release 时,则通过工作区自己的编目目录解析。发布只在该种类的文档会单独发布的地方提供,因此不包括 Plugin(其发布还会绑定其可执行文件),也不包括 Manifest 或 Release,二者都不会被发布。如果语言服务器没有说明哪些操作接受某行的种类,这些行仍会列出,带有文档的行只提供约定检查;如果请求该应答失败,原因会写入 Aggrega 输出通道。发布会先请你确认,并说明更改影响到的范围:实体会以其自己声明的版本打包并推送,任何从该注册表拉取该版本的人都会解析到已发布的内容。发布也是这些操作中唯一会改变本机以外任何内容的操作;两项检查和查看操作不写入任何内容,也不发布任何内容。这四项操作都会显示进度并可停止。
-
Plugins 面板详情 — 每一行列出插件、其类型和版本,以及插件带有就绪状态时的就绪状态。编译器无法解析或描述的插件会被标记并保留其自己的行,编译器的消息显示在工具提示中,因此它永远不会被误认为正在工作的插件。工具提示还会列出附件来自的配置键、其能力、其输入种类、其边界及其导出——只显示列表实际报告的内容。
作用于整个集合的操作是面板的前两行——Add plugin,以及 Generate entities(写入 Plugin 编目实体)——面板自己的标题栏只有刷新按钮。添加时会以可选列表的形式询问插件类型,然后询问该类型所需的另一个答案:
provider绑定所服务的能力,或governance附件所绑定的角色,最后询问要在已配置注册表中搜索的名称,该名称必须恰好解析为该类型的一个插件;附件会写入本项目的工作区配置。添加是这里唯一会访问网络的操作,因为它会搜索注册表,所以它会显示进度并可停止。如果插件的某个已发布版本已被撤回,添加结束时会说明这一点,而不是留待你去发现:已撤回且未被选中的版本、针对每个版本记录的原因,以及撤回记录的读取来源和最后更新时间,只显示编译器报告的内容——如果这些记录根本无法读取,则会改为说明这一点,并附上编译器自己给出的原因,这与没有任何版本被撤回是不同的答案。生成编目实体时,同样以可选列表的形式询问是涵盖编译器内置的所有插件还是本机上的一个插件制品,然后询问要合并的编写覆盖层以及要写入的目录,并在写入前确认:每个实体都写入由其插件的类型、名称和版本派生的路径,因此该路径上已有的同一插件同一版本的实体会被替换。
删除插件的操作位于该插件的行上。它会先请你确认,并说明它写入哪个配置文件,因为这取决于插件的类型——
cli插件从本机所有工作区共享的全局配置中删除,其他所有类型则从本项目自己的配置中删除——并且它只操作配置文本,因此不会删除本机上的其他任何内容。只有编译器有应答的已配置插件才提供删除:编译器内置的插件根本不是配置条目,而无法被解析或描述的附件到达时不带类型,而删除操作除引用外还需要类型——因此在这些行上不提供删除,而不是提供一个只会报告缺少参数的控件。面板不提供添加cli插件的操作,因为安装它需要在终端中确认其声明的能力,而按钮背后没有终端——请在终端中运行它,然后按刷新。也不提供同步插件实体的机器所有记录的操作:它需要实体文件和.wasm制品这两个路径,而一行不会指明其中任何一个。 -
已发布 catalog 搜索 — 在已配置的 registry 中搜索 catalog 实体,并复制一个引用以粘贴到 Aggregate 中。搜索通过单个列表来缩小范围,其中每个分面都显示其当前值:与名称和描述匹配的自由文本、一个或多个实体种类、一个标签选择器(类别是一个标签)、一个或多个插件能力、一个插件插槽,以及返回结果数量的上限。保持不动的分面不缩小任何范围。你设置的内容会被保留:下一次搜索会以上一次留下的筛选条件打开,无论上一次是运行了、没有匹配,还是编辑后被关闭,因此再次缩小范围只需一次编辑,而不必重新输入整个筛选条件。Reset search filter 是紧挨 Search 上方的那一行,它会将每个分面恢复为不缩小任何范围,并在不搜索的情况下带你回到列表;其描述会列出它将清除的分面,或者说明没有设置任何内容。筛选条件仅在扩展于该窗口中运行期间保留,不存储在任何地方——它不在任何设置中,因此另一个窗口从它自己的筛选条件开始搜索,而重新加载窗口,或任何其他重新启动编辑器扩展的操作,都会从空的筛选条件开始。搜索读取由
aggrega registry update(即 Registries 面板中的 Update index)写入的本地索引,不访问任何网络,因此尚未构建索引的 registry 不会被搜索。输出通道会在该 registry 自己的行上说明这一点,并附带 Update index 以构建其索引;在单独一行上说明某个索引已过时,并附带 Update index 以刷新它;在配置了这类 registry 的情况下没有匹配结果的搜索,会列出它搜索过的 registry 和未搜索的 registry;而当没有任何已配置的 registry 有索引时,搜索会报告编译器自己的消息,其中指明要运行的步骤。