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

工作区边界

工作区是由项目根目录标记的目录树——即配置中 workspace: 块所在的根目录、--workspace-root 指定的根目录、编辑器打开的文件夹,或助手的 服务器启动时所基于的目录。Aggrega 自行读取和写入的一切内容都限定在该目录树内, 除非你或工作区配置指定了树外的位置。工作区内的符号链接 可以指向机器上的任何位置,因此链接不会仅仅因为位于工作区内就被视为工作区的一部分: 关键在于它指向哪里。

本页完整阐述该规则。各个入口的页面—— 命令行、 语言服务器和 助手工具——分别说明其各自的请求如何遵循该规则。

工作区内包含什么

当一个路径中已存在的最深部分在跟随其链接后是工作区根目录或位于其下方时,该路径就在工作区内——根目录自身的链接也以同样方式跟随,因此通过其自身链接到达的工作区仍然包含其下方的一切。

通过链接打开的根目录,就是该链接指向的工作区。 无论你打开的文件夹本身是一个链接,还是经由其上层的某个链接到达,Aggrega 列出、读取和写入的内容都与在该链接指向的工作区中完全相同——其中的 Releases、文档和锁文件——并以同样方式判断其中的每个链接。回答中的每个路径仍从给定的根目录开始书写——编辑器打开的文件夹、你输入的 --workspace-root、shell 显示的当前工作目录——因此你看到的内容与你正在使用的路径一致。

这一种解读涵盖所有类型的路径:

  • 决定路径的是它指向何处,而不是它的写法。 当 shared 是指向别处某个目录的链接时,./shared/app.yaml 位于工作区之外,尽管它的每个部分都写在工作区内。请求参数仍可要求自己的写法——例如相对于根目录的路径——其所在页面会说明这一点;那是关于该参数的规则,而不是关于边界的规则。
  • 尚不存在的路径,按通往它的各级目录来判定。 如果 dist 是一个指向工作区外部的链接,那么构建即将在其下创建的文件 在写入之前就已位于工作区之外。
  • 不指向任何地方或形成循环的链接,不算存在的东西。 此时改为判断包含它的目录,且不会跟随任何内容去查明该链接原本要指向何处。如果这样的链接恰好位于即将创建文件的位置,还会检查它所指向的位置,因为文件将落在那里。
  • 指向工作区内其他位置的链接照常跟随。 只有指向外部的链接才会被拦住。

该规则只判断路径在磁盘上指向何处,别无其他。它不读取任何值,也不从名称推断任何内容。

指向外部的路径会发生什么,取决于它是哪一类路径。共有三种结果。

列为未读取

在 Aggrega 列出工作区内容的地方,指向外部的链接不会被读取,列表会说明这一点。 编辑器提供以供选择的 Releases、实体索引以及编辑器从中获取的补全和候选项,还有助手的 list-releases 和 list-entities,都不会搜索工作区之外的目录,也不会读取工作区之外的文件,无论该文件声明了什么——因此编辑器在此类链接下显示的实体不会被列为工作区自己的实体。Release 列表和实体列表按每个此类链接在工作区中的位置为其命名,而不是按它指向的位置:在语言服务器上是 unreadLinkedDirs 和 unreadLinkedFiles,在助手工具上是 unread_linked_dirs 和 unread_linked_files。指向配置在 catalog_dirs 下列出的目录、其下的目录或配置所指定的 Release 的链接不会被列出:配置已经到达了该位置——列出的目录连同其下的一切都会被读取——如下文例外情况所述。作为指向外部的链接的 .gitignore 也不会被读取,因此机器上其他位置的文件永远不会决定工作区中哪些文档被搜索。作为指向外部的链接的工作区配置文件同样会被列入未读取的文件:这些列表仍会为该工作区作答,按未配置任何内容的方式读取,而由配置决定的每个请求都会中止,如下文工作区自身的配置所述。

拒绝

请求中指定的路径,若调用方不是亲自输入它的机器所有者,则会被拒绝。 除下文例外情况外,编辑器向 aggrega serve 发出的请求中指定给服务器读写的每个路径,以及助手向通过 HTTP 访问的服务器指定的每个路径,都必须指向工作区内部;指向外部的路径会被拒绝,不读取也不写入任何内容,拒绝信息会指出该参数,具体见各接口的页面。文档编辑在所有接口上都以这种方式被拒绝,包括命令行——参见文档编辑保持在内部。

中止

当某个操作会自行通过指向外部的链接进行读写时,它会停止。 这些是产品自行推算出的路径,而不是你指定的路径,默默跳过其中一个可能改变构建的含义,因此每种情况都会停止操作,指出该链接及其指向的位置,并使链接指向的位置保持原样:

  • 查找所读取的内容——目录目录下的文档,或者位于按标识指定其 Aggregate 或 Manifest 的 Release 旁边的文档,或者位于以同样方式指定其所扩展 Manifest 的 Manifest 旁边的文档。操作所指定的 Release 或 Manifest 本身不属于这些文档:它在被指定的位置读取——参见通过链接指定的 Release 或 Manifest。 跳过此类链接的查找可能会从后面的目录中解析出另一个同名实体来代替它,因此构建、拉取、验证、读取目录的检查、对单个 Release 或整个目录的 lint,以及编辑器和助手发出的构建、预览、绘图、验证、lint 或描述 Release 的请求,都会在解析或检查任何内容之前停止: E0321。
  • Release 的锁文件——在 Release 旁边读取,为构建、拉取、验证、lint、检查、aggrega cache prune 以及编辑器和助手的请求提供解析所依据的固定版本。它在读取位置受到的约束与写入位置完全相同,因此作为指向外部的链接的锁文件会使上述每项操作停止,而不是向它们提供保存在机器其他位置的固定版本: E0321。
  • 在实体旁边读取的文件——你固定或发布的实体所在目录中的其他文档(读取它们以判断是否有其他实体共享该目录),以及目录目录中 Plugin 实体加载所用的已构建 .wasm。每个文件都只从实体自身文档被读取时所在的目录内部读取:工作区、你在工作区之外指定的目录目录,或你在工作区之外指定的文档所在的目录。因此,其中作为指向外部的链接的文件会使 aggrega pin、aggrega push(包括试运行)、执行固定的拉取以及编辑器和助手的固定与发布停止——未读取的文档可能正是造成冲突的实体——并使加载该插件的构建或拉取停止,而不是运行保存在机器其他位置的字节: E0321。
  • 制品缓存——Aggrega 从 artifact_cache_dir 下的缓存中读取的一切:缓存的实体、插件或库及其旁边的清单、源归档及其元数据、固定的外部输入、签名包和注册表的本地搜索索引,以及 aggrega cache status、aggrega cache prune 和 aggrega cache clear 列出的每个工作区条目。缓存只从缓存目录内部读取,即写入它的位置,因此其中任何指向该目录外部的链接——无论指向工作区的其他位置还是其他任何地方——都会使构建、拉取、验证、搜索、这三个缓存命令中的每一个,以及编辑器和助手读取缓存的请求停止,而不是向它们提供保存在缓存不拥有的位置的字节——包括已按记录的摘要校验过的内容,因为摘要说明的是字节是什么,而不是可以从哪里读取。aggrega inspect 打印的弃用提示不决定任何事情,因此不在此列。清理(prune)或清除(clear)遇到缓存自身的某个目录是此类链接,或缓存目录本身是指向工作区外部的链接时,会将其视为它将要执行的删除,在列出任何内容之前以 E0320 处理: E0321。
  • 源所获取的仓库——拉取为 git-repository 源归档的检出。检出是一个独立的目录,因此仓库携带的链接只有在其指向位置位于仓库内部时才会按其指向的内容归档;指向仓库外部的链接可能触及运行拉取的机器上的任何文件,它会使拉取停止,指出该链接及其指向的位置,且不缓存任何内容——module_subdir 本身是此类链接时也是如此: E0321。 拉取停止后检出即被删除,因此消息按链接在仓库中的位置为其命名,并给出源所指定的仓库和修订版本。按字面写法向上越出仓库的 module_subdir 会在获取仓库之前被拒绝,因此检出旁边的任何内容都不会被读取: E0307。
  • 你导入的目录中的文件——aggrega import、助手的导入工具以及会话的 aggrega/import 在给定一个目录时,会读取该目录中由导入器的文件模式选中的文件。无论该目录位于何处,它都是一个独立的根——参见 你导入的目录——因此这些文件中若有一个链接指向该目录之外,或有一个指向目录的链接通向该目录之外,导入都会在读取该目录的任何文件之前停止,并指出该链接: E0321。
  • 工作区自身的配置——从根目录一直到命令运行所在目录的每一个 .aggrega-config.yaml,以及位于其中任一文件旁边的流水线 .aggrega-config-append-ci.yaml。每个读取配置的命令、语言服务器和助手的工具都会先于其他任何内容读取配置,因此这些文件中若有一个是指向外部的链接,就会让它们在此处停止,而不是让它们基于剩余部分拼成的配置运行:E0321。从不读取配置的 aggrega 命令——version、help、completion、explain、get-schema、起草初始文档时的 scaffold、skills list、plugin run-local、plugin sync、auth token 和 logout——会照常运行,并给出指出该链接的警告。scaffold --example 会读取配置,以获取默认注册表和签名策略,并像其他所有读取配置者一样在此处停止。语言服务器以及通过自身流通信的助手服务器仍会在这样的工作区上启动,以便列出其中的内容:Release 列表和实体列表会给出结果,读取时不使用任何 catalog 目录,也不使用其他任何配置,并在未读取的链接中列出该文件。由配置决定的其他每个请求——构建、预览、生成图、验证、lint、描述、生效配置、默认 Release——都会以 E0321 中止并指出该链接;被要求通过 HTTP 监听的助手服务器也是如此,因为其地址和授权本应由配置设定。
  • 操作写入或删除的内容——构建的输出目录、其边界目录以及写入其中的每个文件、跟踪记录;Release 的锁文件及其旁边的插件信任记录;entity.lock;命令写入的工作区配置文件;工件缓存,以及拉取所填充的或 aggrega cache clear 和 aggrega cache prune 所清空的缓存各部分;导入写入的草稿以及 aggrega plugin gen-catalog 写入的 Plugin 实体;还有编辑器记录默认 Release 所用的 .aggrega/active-release 标记,由语言服务器代为写入。否则,一个作为链接的 dist 会把“重新构建输出”变成删除机器上其他位置的某个目录: E0320。
  • 文档通过路径指定的内容——参见文档中写出的引用: E0324。
  • 实体声明的内容——路径经过某个目录的 source: 或 $import:,而该目录是指向实体自身目录之外的链接;否则发布时会把这些内容以实体内部的名称携带出去: E0304。

无论操作由谁发起——命令行、编辑器,还是通过任一传输方式连接的助手——这些规则都适用,因为该路径属于工作区和产品,而不属于调用者。

文档中写下的引用

Release 和 Manifest 可以通过路径指向另一个文件:Release 中写作 ./… 或 ../… 的 aggregate: 和 manifest:、它的 extends:、Manifest 中写作路径的 extends:,以及 Release 的 parameters: { $import: … }。工作区中的文档以这种方式只能访问工作区内的文件——按字面写法就跳出工作区的路径会被拒绝;按字面写法留在工作区内、但途中遇到指向外部的链接的路径同样会被拒绝。对于这两种路径,都不会从其指向的文件中读取任何内容。

你克隆的工作区带有其作者写下的引用,因此如果只限制你指定的内容,却放任文档随后指向的任何位置,那么边界只需一个 ../ 就会被突破。当文档需要存放在别处的实体时,它应指定实体的名称而不是文件——aggregate: payments——并由工作区配置列出存放该实体的目录。名称是被查找的,而不是被跟随的,因此在这里从不会被拒绝。

位于工作区之外、因你指定而被接纳的 Release 或 Manifest,只能访问其自身目录中的文件——参见例外只能访问它所指定的目录,不会更远。

例外情况及各自的理由

属于以下类别之一的路径,无论是否位于工作区内,都按其指向处理。每一项都是一类路径,而不是一份位置列表,并且各自出于其自身的理由成为例外。

  • 工作区配置所指定的内容。 其目录目录——catalog_dirs 和 catalog_dirs_append,作用于工作区或 workspace.releases 下的某个 Release——以 workspace.releases 为键的 Release 文件、build.authoring_release、插件挂载的本地 .wasm 及其 with.sources 下的文件、mcp.tls.cert_file、mcp.tls.key_file、 mcp.authorization.jwks_file、注册表固定的信任根,以及越出工作区根目录的 artifact_cache_dir。在配置中指定路径,是工作区有意访问自身之外内容的方式:它只写一次,随项目保存,任何审查项目的人都能读到。工作区按约定使用的 catalog 目录,在配置列出它或你通过 --catalog 传入它时视为已指定——或者配置列出、你传入它所指向的位置(无论以何种写法),或该位置之上的某个目录,此时会通过你指定的目录读取一次那里的内容。仅因存在而被读取时,它是工作区自身的内容,因此一个指向工作区之外的链接形式的 catalog,在你指定它或它指向的位置之前不会被读取。
  • 你在命令行中输入的路径。 aggrega build --release ../other/release.yaml、 --catalog /srv/shared-catalog、--output-dir、要校验、lint、固定或发布的文件:每一个都按其指向使用——下文所述的文档编辑除外。命令运行所在的机器归你所有,你本就能读写自己会输入的任何内容,因此把你限制在某个目录中毫无意义。
  • 助手通过进程自身的标准流指定的路径。 在你的机器上启动 aggrega mcp 的客户端以你的身份运行,其宿主通常还会为它提供自己的文件和 shell 工具,因此它指定的路径会像你亲自输入的一样被采用——参见两种助手传输方式。
  • 产品的机器级存储——全局配置文件、已编译模块存储、插件描述符缓存、文档包以及注册表凭据存储。它们属于机器而不属于任何工作区,因此没有工作区持有它们。
  • 在对话框中选取、在原处读取的文件或目录。 编辑器会以绝对路径发送:注册表注册的密钥文件或信任根、aggrega/import 所转换的描述——一个文件,或由导入器读取其中文件的目录——以及 aggrega/pluginGenCatalog 为之生成实体的模块及其旁边的覆盖文件。每一项都由人选定,无论其保存在何处。它们只会被读取:请求写入的任何内容都不会写到以这种方式选定的路径。以这种方式选取的目录被限制在其自身之内,与你导入的每个目录一样。
  • 编辑器中打开的文档。 对它进行校验、请求或丢弃其诊断信息、悬停、补全、解析,以及在其中查找引用和实现,都根据编辑器发送的内容作答,因此不会在指定它的路径上读取任何文件,该路径也绝不会因其指向而被拒绝。确实从磁盘读取文档的请求属于上文所述的被拒绝的那一类。

命令行中输入的路径和机器级存储完全不受评判;其余各项按其类别放行,而绝不取决于恰好携带它们的请求。

例外只到达它所指定的目录,不会更远

你在工作区之外指定的目录,对于其下读取或写入的一切而言,自成一个根。 目录本身按你指定的方式使用——若它是链接,则跟随到其指向之处——而其下指向该目录之外的链接,与工作区内的链接受到完全相同的约束:在列举时不被读取,并使查找或写入中止。因此,你在工作区之外列出的目录目录、你传给 aggrega plugin gen-catalog 或 aggrega import 的输出目录,以及越出工作区的 artifact_cache_dir,都各自把其下的内容限制在自身之内。若你指定的目录位于工作区内,则以工作区为根——你导入的目录除外,它无论位于何处都自成一个根。

你指定的目录,在其下放置任何内容之前,会先相对于你运行命令所在的文件夹进行解析。 你传给 aggrega import 的输出目录若以相对路径输入,即为你运行命令所在文件夹中的同名文件夹;在 Windows 上单独指定的驱动器——D:——即为该驱动器上的当前文件夹。目录会先转为完整路径,每个文件都放在该完整路径之下,因此名称以分隔符开头的文件,例如 \notes.txt,会落在你指定的目录内,而不是驱动器的顶层,命令报告的目录也就是实际写入的目录。

你在工作区之外指定的 Release 或 Manifest,是同一规则在文件上的体现:它自身所在的目录即为根,因此它通过路径指定的内容——以及其 extends: 链所到达的每个 Release 所指定的内容——都必须留在该目录内。与其 Aggregate 和 Manifest 放在一起的 Release 可以从任何位置构建;采用常见 releases/ 布局、指定 ../aggregates/app.yaml 的 Release,则应从其自身的工作区构建。

通过链接指定的 Release,在链接指向之处读取,在你指定它之处解析。 以 --release release.yaml 输入、而 release.yaml 是指向别处文件的链接时——或以这种方式在 workspace.releases 下指定,或作为 build.authoring_release 指定——该 Release 从链接指向的位置读取。它通过标识或路径指定的 Aggregate 和 Manifest,会在链接旁边、即你指定它的目录中查找,并被限制在该目录的根内:工作区,或者当该目录位于工作区之外时为目录本身。其 lockfile 同样在链接旁边读取和写入,绝不在链接指向之处。该 Release 不属于其自身查找在旁边遇到的文档,因此绝不会中止该查找;而放在它旁边、作为指向外部链接的另一个 Release 仍会中止查找。通过链接单独检查的 Manifest,也以同样方式读取和解析。

制品缓存目录无论位于何处,都自成一个根。 缓存保存的一切只在缓存目录内写入、读取和删除,因此缓存自身的某个目录或其中的文件,若是指向缓存目录之外的链接,就会被拦截——即使它指向工作区内的其他位置——而指向缓存目录内其他位置的链接则会被跟随。缓存目录本身位于何处,根据其值的写法判断。若写在工作区根目录内——包括默认的 .aggrega/cache——它就是工作区自身的目录:作为链接指向工作区内其他位置的缓存目录会被跟随,而指向工作区之外的则会被拒绝,读取和写入皆然。若写成越出工作区的形式(../shared-cache),它就是配置所指定的目录,在其指向之处读取和写入。

你导入的目录

你导入的目录本身就是一个根,无论它位于何处——在工作区内与在工作区外都一样,这正是它与你在工作区内指定的其他所有目录的不同之处。 aggrega import、助手的导入工具以及会话的 aggrega/import 会将该目录中的每个文件按其在该目录中的位置交给导入器,因此交给导入器的内容只会从该目录内部读取。受到判定的是导入将要从中获取内容的对象:指向导入器某个模式所选中文件的链接(在格式由识别而非指定得出时,适用任一导入器的模式),以及指向目录的链接,后者永远不会被进入。其中指向该目录之外的链接会在读取任何文件之前被拒绝,即使它指向工作区内的其他位置;而被选中的、指向该目录内其他位置文件的链接,会在其指向处以链接自身的名称被读取。没有任何模式选中的文件链接既不受判定,也不会被读取。目录本身按你指定的方式使用,若它是一个链接,则会跟随到其指向的位置。

文档编辑停留在内部

aggrega edit-document、语言服务器的文档编辑和插入点,以及助手的 edit-document 和 insertion-point,只作用于工作区所包含的文档。位于工作区之外的文档,无论是按所写路径还是通过指向工作区外的链接,在每个入口上都会被拒绝,不读取也不写入任何内容——包括在你指定的路径原本会被采纳的情况下。

两种助手传输方式

aggrega mcp 以两种方式提供相同的工具,边界在两者之间有所不同,因为调用方不同。

  • 通过进程自身的流,客户端在你的机器上启动服务器,因此一次调用就相当于你在命令行上输入:路径参数可以是绝对路径,可以位于工作区之外,调用可以指定自己的 workspace_root 和 catalog_dirs,并且会提供在独立进程中运行 aggrega 命令的工具。只有调用所指定的路径会按指定的方式得到遵从。该操作随后自行读取和写入的内容,则按终端上的方式受到约束:列举不会经由指向外部的链接读取,文档写入的引用不会离开工作区,写入也不会经过被链接的输出目录或缓存目录。工作区内容可能引导助手请求什么,因此在这些工具是助手访问你文件的唯一途径的主机上,你克隆的工作区中的某个文档仍可能引导助手指定工作区之外的路径,并使其被读取或写入;在助手无需先询问你即可执行的操作 中,你可以设置它在未经提示时能做多少事。
  • 通过 HTTP,调用方并不拥有服务器所运行的机器。工作区是服务器启动时所基于的那个,并在服务器的整个生命周期内保持不变;每个路径参数都被限制在其中,按上文方式判定;指定 workspace_root 或 catalog_dirs 的调用,或选择主机上所保存签名密钥的调用, 会被拒绝;运行 aggrega 命令的工具也不会提供。拒绝信息会指出该参数,并按发送时的原样引用相对值,但既不指出工作区根目录,也不指出路径原本会指向何处。

当某项操作被拒绝或中止时

你看到的情况应对方法
列表在未读取的条目中列出了一个链接用链接所指内容的副本替换该链接;或者,对于存放在别处的实体,将链接指向的目录列在 catalog_dirs 下;对于存放在别处的 Release,将其列在 workspace.releases 下或设为 build.authoring_release。
E0321,通过链接从目录库目录或 Release 的目录向外读取将链接指向的目录列为目录库目录,或通过 --catalog 传入,而不是经由其下的链接访问它;或者用副本替换该链接。若该链接就是按约定命名的 catalog 本身,则列出 catalog 或它指向的目录,或通过 --catalog 传入其中之一。
E0321 出现在 Release 的锁文件上删除该链接并重新拉取该 Release,这会在其旁边写入一个新的锁文件。锁文件没有其他存放位置。
E0321 出现在实体旁边的文件上用文件本身替换该链接:将作为实体的文档移到单独的目录中,并将构建出的 .wasm 放在其 Plugin 实体旁边,而不是放置指向它的链接。
E0321 出现在配置文件上用存放在工作区内的副本替换该链接。在多个工作区之间共享的配置,可通过 --config 或 AGGREGA_CONFIG 将其指定为全局配置文件来读取,它位于各工作区自身的文件之下。
E0321 出现在制品缓存上删除该链接;拉取操作会重新填充缓存。若要将缓存放在别处,请将 artifact_cache_dir 设为该目录,并写成相对于工作区根目录的路径(../shared-cache),而不是使用链接。
E0321 出现在所获取仓库中的链接上该链接已提交在源所指定的仓库中——消息会按其在仓库中的位置指出它:请在那里修改——使其指向仓库内部,或提交文件本身——并指定包含该修改的修订版本。
E0321 出现在你导入的目录中的链接上在该目录中保留文件本身而不是指向它的链接,或者导入链接所指向的目录。你导入的目录无论位于何处,都只从其内部读取。
E0307 出现在 module_subdir 上指定仓库内的一个目录:该值可以深入仓库顶层之下,但不能向上越出顶层。
E0320,通过链接进行写入或删除删除消息指出的链接,或使其指向消息指出的目录内部的某处,然后重新运行该操作。这并非由你的实体文件导致。
E0324,引用指向外部通过 metadata.name 指定存放在别处的 Aggregate,并列出其目录库目录;将 Manifest、extends: 所指定的 Release 以及参数文件保存在工作区内——或者,对于你从外部指定的文档,保存在其自身所在的目录中;或者在同时包含这两个文档的目录上打开工作区。
E0304,通过链接获取的内容在实体自身的目录中,用链接所指内容的副本替换该链接。
语言服务器请求因路径指向外部而被拒绝发送工作区内相对于其根目录的路径。要访问存放在工作区外的 Release,需在配置中指定它(列在 workspace.releases 下或设为 build.authoring_release),并在请求中指定工作区内指向它的链接——即 Release 列表所给出的位置。
通过 HTTP 的助手调用因路径而被拒绝发送相对于服务器所服务工作区根目录的路径;若拒绝信息给出了某个绝对路径的相对写法,请发送该写法。
文档编辑被拒绝编辑工作区所包含的文档;不会经由链接编辑位于别处的文档。

另请参阅

  • 配置 — 上述每项设置写在何处,以及其中的相对 路径如何解析。
  • aggrega serve 和 aggrega mcp — 每个请求和工具,以及 其中哪些参数指定路径。
  • 致命中止 — 上述每种情况的完整条目。