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

aggrega edit-document

对文档应用一次有界的结构化编辑,保留其未触及的每个字节

概要

aggrega edit-document <edit> <file> [flags]

说明

Apply one bounded structured edit to a document in the workspace.
The edit is named first and the document second. One call adds one entry under one container, or sets one scalar, and it can do nothing else:
add-component add a component instance under a components container
attach-feature attach a Feature to the node you name
wire-edge wire a connection inside one of that node's sockets
set-value set one value on that node
There is no edit that deletes, replaces a block you already wrote, reorders anything, or writes bytes you supply verbatim. The edits this command applies are add-component, attach-feature, wire-edge, set-value, and a name outside that set is refused rather than interpreted.
Name the node with --node, once per path segment, from the document root. It is a segment at a time rather than one dotted string because a dot is a legal character in a name you type, so a joined path could address a key nobody wrote and the entry would be created there rather than refused:
aggrega edit-document add-component app.yaml \
--node spec --node components --name web --value example/service
aggrega edit-document wire-edge app.yaml \
--node spec --node components --node web \
--socket database --name db --value spec.components.store
For add-component the path names the components container itself, because the entry being added is the node. For the other three it names the node the edit is about, and the container follows from the edit.
--name is the key the entry is written under: the instance name, the attachment's name, the connection's alias, or the value's key. --value is what that entry carries, and what it means follows from the edit — the entity the entry requests, the node a connection points at, or the scalar a value is set to. It is read as a YAML scalar, so --value 3 sets a number, --value true a boolean, and --value '"3"' the string; omitting it sets nothing at all.
Every byte the edit does not touch survives. The document is parsed only to locate the container and the line its block ends at, so comments, blank lines, quoting style, folded and literal scalars and the trailing-newline shape all carry through, and the nesting step is measured from the document's own indentation rather than imposed. The same request against the same document produces the same bytes.
The result has to be a document you could have typed, and that is what the write is gated on: the composed document is checked against its own kind's schema and reaches disk only if that passes. A request that would produce something the schema refuses is refused, naming the property the schema would not admit and where, and the file is left byte-for-byte as it was — so a refused edit is indistinguishable from one never attempted and you can retry a corrected request against the document you started with.
An entry that is already there, carrying what you asked for, is a no-op. An entry of that name carrying something else is refused rather than replaced.
--dry-run does everything the plain command does except write: the edited document goes to standard output as content, naming the file it is for, and nothing is created — for a caller that puts the result in front of someone before it is saved. Every other behaviour is the write's, the schema gate included, so a request the write would refuse is refused under --dry-run too and its exit code predicts the write's. Without it the document is written.
Whether what you wire is semantically admissible is not decided here. Whether a socket is one the producer declares, or whether a Feature's applicability is satisfied, is what aggrega validate answers.

标志

标志默认值描述
--dry-runfalse执行除写入之外的所有操作:将编辑后的文档作为内容返回,注明其对应的文件,不创建也不修改任何内容。其他所有行为都与写入相同,包括 schema 检查。不使用此标志时,文档会被写入
--name—新条目写入时所用的键:component 实例名称、附件名称、连接的别名,或值的键
--node[]从文档根节点到编辑所针对节点的结构路径中的一个段。每个段重复一次,最外层在前。它每次接受一个段而不是一个点分路径,因为点是你输入的名称中的合法字符,因此拼接后的路径可能指向一个没有人写过的键
--socket—连接所在的依赖插槽。仅在 wire-edge 时读取,其他情况下忽略
--value—条目携带的内容,按 YAML 标量读取。其含义取决于编辑:条目所请求的实体、连接所指向的节点,或值被设置成的标量

功能说明

aggrega edit-document <edit> <file> 对你工作区中的一个文档应用一次结构化编辑,并让其未触及的每个字节都保持你写下时的原样。先指定编辑,再指定文档:

Terminal window
aggrega edit-document add-component storefront.aggregate.yaml \
--node spec --node components \
--name checkout --value core/api-server:1.0.0

它适用于你希望直接编辑文件、而不是被告知在哪里编辑的情况。如果你自己持有缓冲区和撤销历史,aggrega serve 会报告一个位置,让你自己放置文本;而此命令会组织条目并将其写入。

该文档必须是你的工作区所包含的文档。 可以相对于工作区根目录指定它,也可以使用其绝对路径;位于工作区之外的文档会被拒绝,且不会读取或写入任何内容,无论它是直接这样写出的,还是通过一个指向工作区之外的链接到达的——无论是指向该文件的链接,还是路径上某个本身是链接的目录。编辑会先读取文档再将其写回,因此位于此类链接之后的文档是工作区并不持有的文件,拒绝信息会说明这一点:

the document named leads outside the workspace through a link, and an edit is only applied to a document the workspace carries: "shared/storefront.aggregate.yaml"

要编辑保存在其他位置的文档,请在包含该文档的工作区中运行此命令。语言服务器和助手工具的编辑也遵循同一规则,因为三者应用的是同一种编辑。其文档是你输入的、被限定在工作区内的那一个路径,详见工作区边界。

一次调用,一个条目,且编辑集合是封闭的

共有四种编辑,没有其他编辑:

编辑添加的内容
add-componentcomponents 容器下的一个组件实例
attach-feature你所指定节点上的一个 Feature 附加项
wire-edge该节点某个依赖插槽内的一个连接
set-value你所指定节点上的一个值

**没有任何编辑会删除内容、替换你已写好的块、重新排序任何内容,或原样写入你提供的字节。**这正是整个设计本身,而非对设计的限制:四种之外的名称根本无法通过该命令执行任何操作,因此它并不是一个换了更窄名字的文件写入器。集合之外的名称会被拒绝,而不会被解释执行。

如果条目已经存在且包含你所请求的内容,则该编辑不执行任何操作——命令会说明这一点,并且不写入任何内容:

storefront.aggregate.yaml already carries that entry; nothing was written

如果同名条目包含的是其他内容,则会被拒绝而不是被替换,因为替换你写过的内容不属于这四种编辑。

以路径指定节点,每次一个段

从文档根开始,路径的每个段重复一次 --node,最外层在前:

Terminal window
aggrega edit-document wire-edge storefront.aggregate.yaml \
--node spec --node components --node web \
--socket database --name replica --value store

它有意每次接受一个段,而不是一条用点分隔的路径,原因在于正确性。 点是你输入的名称中的合法字符,因此文档之外的任何东西都无法区分结构上的点和名称内部的点。拼接起来的路径看起来正确,却会指向一个没有人写过的键——而且由于 add-component 可能创建文档中不存在的容器,该条目会落在这个凭空产生的键下,而不是被拒绝。分段消除了这种歧义,而不是把它转移到别处。

对于 add-component,路径指定的是 components 容器本身,因为要添加的条目就是该节点。对于其他三种编辑,路径指定的是编辑所针对的节点,容器由编辑本身决定:attachment 放在该节点的 features 下,connection 放在其 uses 及你指定的 socket 下,值放在其 values 下。

--name 是条目写入时所用的键——实例名、attachment 的名称、connection 的别名或值的键。--socket 仅在 wire-edge 时读取,其他情况下忽略。

值保留其字符所带的类型

--value 按 YAML 标量读取,与你把这些字符直接写进文档时的读取方式相同:

Terminal window
aggrega edit-document set-value storefront.aggregate.yaml \
--node spec --node components --node web --name workers --value 4
values:
replicas: 3
workers: 4

因此,--value 4 设置一个数字,--value true 设置一个布尔值,而 --value '"4"' 设置字符串 4——在这里加引号表示“这是文本”,与在文档中完全一样。省略 --value 则不设置任何内容。映射或序列会被拒绝,因为写入它们相当于添加一个块,而这不属于四种编辑之一。

你未编辑的一切都会保留,相同的请求产生相同的字节

解析文档只是为了定位容器及其块结束所在的行;条目在行级别渲染并拼接。注释、空行、引号风格、折叠与字面标量、模板表达式以及末尾换行的形态都原样保留,嵌套缩进步长根据文档自身的缩进测得,而不是强加的——因此条目会沿用你已在使用的风格。

给定相同的文档和相同的请求,每次产生的字节都相同。因此你可以比较两次运行的结果,评审时一次编辑也只对应一个 diff。

结果必须是你本可以手写出来的文档

写入以此为门槛。 组合后的文档会按其自身 kind 的 schema 进行校验,该 schema 从文档中读取而非由你提供,只有校验通过,字节才会写入磁盘。如果某个请求会产生 schema 拒绝的内容,该请求就会被拒绝,并指出 schema 不接受的属性及其位置:

the edit was refused because the resulting document would not be valid, and nothing
was written: document envelope validation failed (Release, at prod.release.yaml);
15:7: spec.components.web.values: … unexpected property: "values"

文件保持逐字节不变,而且写入本身是原子的,因此被拒绝或被中断的编辑与从未尝试过的编辑没有区别,你可以针对最初的文档重试修正后的请求。这也是此处不重述任何编写规则的原因:要求 Release 文档携带开发者值,会被同一个 schema 拒绝,正如它会拒绝手写的同样文档。

语义上是否可接受不在此处判定。 某个依赖 socket 是否由生产方声明,或某个 Feature 的适用条件是否满足,属于构建时执行的解析过程。因此你可以指定本命令从未见过的连接,Aggregate 也可以编写其目录实体未预先声明的 socket;而跨 socket 可以消费什么,仍由生产方声明。需要回答这个问题时,请运行 aggrega validate 并指定一个 Release。

保存前查看结果

--dry-run 执行普通命令所做的一切,唯独不写入:编辑后的文档作为内容输出到标准输出,并注明它对应的文件,不会创建任何东西:

Terminal window
aggrega edit-document attach-feature storefront.aggregate.yaml \
--node spec --node components --node web \
--name tls --value core/tls:1.0.0 --dry-run
documents:
- path: storefront.aggregate.yaml
content: |
# The storefront application.
...

**不加该标志时,文档会被写入。**默认行为是写入,因为此命令的产物是一份编辑后的文档,而产出文档的命令理应交付它——未对交付方式作任何说明的请求会直接编辑该文件。

其他所有行为都与写入相同,包括验证关卡。如果某次编辑的结果会被 schema 拒绝,那么在 --dry-run 下同样会被拒绝,指出同一个属性,并让文件保持原样——因此试运行得到的退出码就是写入时本会得到的退出码。

从编辑器或助手执行同样的编辑

无论由哪个入口应用编辑,产生的字节都相同。驱动 aggrega serve 的编辑器通过 aggrega/editDocument 调用它,通过 aggrega mcp 连接的 AI 助手则通过该命令在那里暴露的工具调用它。条目在同一处完成组合、拼接和校验把关,每个入口只是通向它的一层薄入口——因此你在终端中编辑的文档与编辑器替你编辑的文档逐字节完全相同。

各入口唯一的区别在于读取哪些字节。此命令和会话方法都读取磁盘上的文件,从不读取未保存的缓冲区:从缓冲区写入,会以应用一个条目为名,把你尚未保存的内容写进页面。请先保存,再编辑。

示例

在 Aggregate 的顶层添加一个组件实例:

Terminal window
aggrega edit-document add-component storefront.aggregate.yaml \
--node spec --node components --name checkout --value core/api-server:1.0.0

将一个 Feature 附加到在子系统内编写的组件上:

Terminal window
aggrega edit-document attach-feature storefront.aggregate.yaml \
--node spec --node subsystems --node billing --node components --node ledger \
--name audit-log --value core/observability/audit-log:1.0.0

为在子系统内编写的组件设置一个值:

Terminal window
aggrega edit-document set-value storefront.aggregate.yaml \
--node spec --node subsystems --node billing --node components --node ledger \
--name replicas --value 5

在写入任何内容之前检查结果:

Terminal window
aggrega edit-document wire-edge storefront.aggregate.yaml \
--node spec --node components --node web \
--socket cache --name sessions --value redis --dry-run

要在指定容器之前查明某个条目属于哪个容器,以及在不应用任何内容的情况下读取某个位置,请参阅 aggrega serve。