跳转至

完整多选择器查找回执系统规范

意图

代理有时知道几个必须检查的确切主题。为每个主题重复运行一次 CLI 过程会浪费设置工作,并且很容易在成功的调用之间漏掉失败。接受多个选择器的查找会返回一个完整、有序的回执:每个请求的选择器都有一行,歧义保持可见,退出状态会说明每次查找是否都已解析。

本记录拥有针对独立精确选择器进行 CLI 查找的可观察批量契约与采纳规则。FR11 E1-E5 是唯一的资格测试。符合条件的只读查找默认采纳批处理;不符合条件的命令保留其现有语法。查找现有的权威仍然拥有选择器的含义、单个选择器如何解析,以及为一个已解析主题返回的数据。

非目标

  • 将自由文本搜索变为批量。一个搜索查询中的词语仍然是一个查询。
  • 将此只读查找契约应用于变更、流式或监视会话、比较、范围,或其位置参数构成一个表达式或有序工作流的命令。
  • 更改现有 CLI 对零个或一个位置选择器的响应,或现有编程式对省略参数和字符串参数的响应。
  • 对候选进行排名或在歧义身份之间做出选择。
  • 添加全局选项、配置键、环境变量或网络来源。
  • 更改未通过 E1-E5 的命令上预先存在的批量响应。仅凭 .batch 后缀并不会使该响应成为 AST-053 回执。
  • 满足此契约的等效内部实现仍然有效。

需求

  • FR1 — 批量选择是显式且可发现的。 采纳命令 MUST 在生成的帮助和清单条目中将其选择器位置记录为可变参数,并在其编程式 API 中记录为可接受的数组。没有任何隐藏控件启用此行为。
  • FR2 — 每个被接受的选择器都会得到一行。 在调用级验证之后,批量回执 MUST 为每个提供的选择器恰好包含一个结果行,按输入顺序排列。重复的选择器仍为重复行。当聚合工作将超过已记录的有限边界时,命令 MAY 在解析之前拒绝整个请求;该拒绝使用普通的顶层 ERR_INVALID_ARGUMENT 错误封装,CLI 退出码为 1,并且不发出任何批量。已接受的批量 MUST NOT 截断或去重选择器。
  • FR3 — 每行都说明其结果。 每行 MUST 精确回显选择器并标识一种状态:found、not_found、ambiguous 或 error。
  • FR4 — 已找到行保留单次查找的含义。 found 行 MUST 在 result 下携带与编程式 API 在使用相同控件和响应基础字段时单独为该选择器返回的相同类型化响应。spec:AST-047 FR10 决定命令是否已采纳可导航输出,其 FR7 定义采纳后的 links 字段。单结果链接保持与其行嵌套。仅当命令自身的 AST-047 采纳权威将回执定义为节点时,外层回执才携带链接;AST-053 不合成移动。调用者不会仅从批量专用字段重构单个结果。
  • FR5 — 歧义是数据,绝不是猜测。 当多个身份可以满足一个选择器时,该行 MUST 为 ambiguous,并列出拥有目录公开的每个有效候选及其稳定身份字段。查找 MUST NOT 选择第一个候选,也不得静默偏好某个命名空间、提供商或软件包。
  • FR6 — 每个选择器的失败保留在回执中。 not_found 或 error 行 MUST 携带相同的单选择器查找使用的稳定错误代码、其人类可读的错误,以及任何结构化建议。在请求被接受为批量之后,每个选择器的失败 MUST NOT 变成顶层错误、消失或变成空成功。只有在任何选择器可以解析之前适用于调用的验证或设置失败,才使用普通的顶层错误封装。
  • FR7 — 精确限定符不会降级匹配。 当选择器携带由查找拥有的精确限定符(如软件包版本或修订版)时,它仅针对该精确主题解析。带有另一个限定符的近似身份为 not_found,可以指向拥有的发现或下一步操作命令,并且绝不会被用作看似合理的替代品。
  • FR8 — 完整回执先于失败。 CLI MUST 发出每一行,然后在任何行不是 found 时以 1 退出。文本和 JSON 模式使用相同的退出状态。编程式 API 返回完整的类型化回执,并将进程退出策略留给其调用者。
  • FR9 — 现有基数和位置含义保持稳定。 对于采纳命令,零个选择器保留命令现有的零选择器行为(无论是浏览还是错误);一个选择器保留其现有的成功或错误响应;两个或更多选择器使用批量判别符。只有拥有的选择器位置变为可变参数。其他位置参数保持其现有的关系和顺序。在编程式 API 中,省略的参数保留其现有行为,字符串请求一个结果,数组在所有数组长度(包括零和一)下都请求批量。
  • FR10 — 文本是批量的投影。 人类可读输出 MUST 通过共享格式化程序词汇表公开计数以及每行的选择器、状态和状态特定字段。外层响应字段保留在回执上,嵌套单个结果的字段保留在该行中;嵌套链接 MUST NOT 被提升到回执。文本 MUST NOT 发明命令特定的表格,也不得省略 JSON 携带的字段。
  • FR11 — 资格只有一个测试。 当且仅当以下五个条件全部成立时,命令才有资格:
  • E1: 它是只读的,其选择器位置接受一个精确的稳定主题;
  • E2: 选择器独立解析,它们之间没有关系或顺序,并且相同的选项和其他位置参数适用于每一个;
  • E3: 每个结果都是有限的,且命令可以在退出前返回完整的已接受回执;
  • E4: 一个已记录的聚合工作边界可以在每个受支持的选项和投影模式下安全地接受至少两个选择器,并且解析该集合不会增加副作用;以及
  • E5: 选择器是命令的最后一个位置参数,因此使其可变不会重新解释后续的位置参数。 在本记录生效后接纳且满足 E1-E5 的命令 MUST 在其首次公开发布之前采纳此契约。满足 E1-E5 的现有命令 SHOULD 在不改变其零选择器和单选择器契约的情况下迁移。如果任何条件失败,该命令就不符合资格。
  • FR12 — 每个采纳者使用一个批量词汇表。 判别符 MUST 为 <subject>.batch,其中 <subject> 是命令单结果响应所使用的稳定主题族。在 architecture:cli-surface INV2 下,type 携带该判别符,{count, results} 是 data 负载。共享 CLI 响应基础 MUST 拥有并发布 BatchResponse 和 BatchRow,用于该负载和四种行状态;主题 API 模块使用其候选类型和单结果类型特化这些类型。采纳者 MUST NOT 发明同义的判别符、状态或行字段名称。不符合资格命令上预先存在的批量响应保留其命令拥有的契约,并且不会仅仅因为其判别符以 .batch 结尾就声称符合 AST-053。
  • FR13 — 接纳记录分类。 AST-042 下的命令接纳 MUST 针对 E1-E5 对选择器位置进行分类。顶层命令的排除 MUST 在当前命令拥有记录中指明失败的条件;草稿不算数。子命令的排除 MUST 在其接纳拉取请求中按照 AST-042 现有的代码所有者批准门槛指明该条件。在类型化接纳元数据落地后,其 CommandDoc MUST 保留相同的分类。在该元数据和仓库检查落地之前,FR11 和本需求是在审查中而非机械地强制执行。

平台支持

  • 受支持的功能/引擎基线:所属 CLI 命令已支持的所有运行时。
  • 不支持的行为:无。不符合条件的命令保留其现有语法。
  • 浏览器证据:不适用;这是 CLI 与编程式 API 的契约。

采用与推广

FR11 E1-E5 规定了资格条件。典型采用者是 get、show、inspect 以及对精确身份的状态式读取。以下示例说明了失败条件;它们不能替代 E1-E5 测试:

  • 自由文本搜索或发现在 E1 上失败,因为多个词构成一个查询;
  • create、update、delete、apply 或其他变更在 E1 和 E4 上失败,因为它们需要独立的事务和部分写入语义;
  • compare、diff、range、pipeline 或 workflow 命令在 E2 上失败,因为参数位置定义的是关系而非独立对象;
  • watch、shell、stream 或交互式命令在 E3 上失败,因为它们不会返回一个有限的回执;
  • 在选择器之后跟随另一个位置参数的命令在当前语法中无法满足 E5;以及
  • 无法在每种受支持模式下安全接受至少两个选择器的查找在 E4 上失败。

采用该契约时一次一个命令:

  1. 在 AST-042 纳入期间,将所属的选择器位置对照 E1-E5 进行分类。完全按照 FR13 的要求记录任何排除项。
  2. 定义并记录聚合工作量上限,包括选择器数量和任何命令特定的成本维度。它必须能在每种受支持模式下安全接受至少两个选择器。在解析之前,以顶级 ERR_INVALID_ARGUMENT 和 CLI 退出码 1 拒绝超出该上限的工作;切勿截断已接受的批次。
  3. 保留现有的零选择器与单选择器行为及最小基数。只让所属的选择器位置变为可变参数;不要重新解释其他位置参数。
  4. 无论数组长度如何,都要用数组明确表达编程式批次意图。使用共享的批次响应和行类型、<subject>.batch 鉴别器,以及每个 found.result 下现有的单选择器响应。
  5. 保留外层和嵌套的 response-base 字段,然后将每个现有的读取投影和选项应用于每个 found 行。不要交付一个仅限批次的精简详情面。
  6. 添加生成的帮助、manifest/API 文档(包括 exitCodes)、可搜索的指南、真实的文本和 JSON 回执,以及针对超出上限的拒绝、空数组与单元素 API 数组、顺序、重复、全部找到、混合、全部失败、歧义、response-base 字段和每种投影的确定性覆盖。

当前状态影响

组件查找仍然是指定的首个采用者。其运行时实现将独立于本规范修订落地,并且在声称合规之前 MUST 应用 FR1-FR12。CLI browse 和单选择器响应类型保持不变;编程式调用者通过省略参数请求目录,通过字符串请求单个结果,通过数组请求批次。architecture:cli-surface 继续拥有外层信封、格式化器词汇表、生成的帮助以及 API 与 CLI 的一致性。

AST-042 将 E1-E5 分类纳入命令准入流程,以满足 FR13。下一推广阶段将类型化分类添加到 CommandDoc 和生成的 manifest,然后对所有现有的精确选择器位置进行分类。这些公共命令文档和 manifest 成为权威清单。后续变更将迁移每个符合条件的命令族。外部调度不具权威性,其引用不会进入此公共仓库。每个命令自身的当前权威继续拥有选择器语法、单结果数据以及任何已记录的排除项。

验证

契约 验证 代表性状态 变更或失败预期
FR1 生成的帮助和 manifest 测试;FunctionDoc 契约测试 一个选择器位置变为可变参数 批次输入存在于代码中,但帮助、manifest 或 API 文档中没有它
FR2, FR3 编程式 API 与 CLI 批次测试 最小有用界限;超出上限的拒绝;顺序;重复;混合结果 已接受的选择器被重排、去重、丢弃,或未产生状态
FR4 批次与单结果及 response-base 比较 详情、链接和每种受支持的聚焦投影 某个 found 行与相同的单选择器结果不同
FR5 歧义已安装身份夹具 一个名称有两个有效的包所有者 选择了其中一个所有者,或遗漏了某个候选者
FR6, FR7 缺失、格式错误、未知包和版本不匹配夹具 建议存在与缺失;安装了另一个版本 选择器失败逃出回执、丢失代码,或使用另一个限定符
FR8 文本与 JSON 进程测试 全部找到;一个失败;多个失败 输出在第一次失败时停止,或未解析的批次未以退出码 1 退出
FR9 CLI 基数、位置参数含义与 API 输入形态测试 零浏览/错误;一;多;空数组和单元素数组 现有基数改变、另一个位置参数成为选择器,或数组形态漂移
FR10 文本投影与可导航输出测试 每种行状态;带链接和不带链接的外层字段 文本省略了 JSON 字段、移动了嵌套链接,或使用了未注册的输出格式
FR11 AST-042 准入审查 E1-E5 合格采用者;顶层及子命令排除项 一个合格的新命令仅支持单选,或某个排除项未指明失败条件
FR12 共享 JSON/类型契约与清单测试 <subject>.batch;每一个共享行状态 采用者自创判别符、状态或行字段
FR13 知识引用、拉取请求与类型化元数据审查 当前顶层记录;子命令证据;草稿排除项 准入跳过分类,或对其层级使用了错误证据

决策日志

DEC-1 — 批次是完整的有序回执

Reference: spec:AST-053/DEC-1 Decider: josephfarina, 2026-10-01

批次查寻旨在减少重复的过程性工作,同时不隐藏任何已接受请求的处理结果,因此已接受的选择器保持一一对应且保持顺序,包括重复项。与工作负载相关的拒绝发生在批次解析之前,且不会返回部分回执。

已否决:在第一次未命中时就让已接受的批次失败,这会丢失后续答案;丢弃失败的选择器,这会让部分工作看起来已完成;或在解析开始后截断过大的请求。

DEC-2 — 歧义时列出候选

Reference: spec:AST-053/DEC-2 Decider: josephfarina, 2026-10-01

未限定的身份可能属于多个命名空间、提供方或软件包。回执会公开每一个有效候选,以便调用方使下一次查寻变得精确。

已否决:优先级或首匹配选择,这会将目录顺序变成未记录的答案。

DEC-3 — 未解析的行使 CLI 在输出后失败

Reference: spec:AST-053/DEC-3 Decider: josephfarina, 2026-10-01

自动化需要进程状态来表明每个请求的查寻是否都已解析,同时回执仍然有助于一次性修复所有失败,因此任何未解析的行都会在输出后以退出码 1 退出。

已否决:因为部分行成功就退出码为 0,这会把不完整的工作报告为成功;以及在失败时不输出回执,这会迫使反复调用。

DEC-4 — 输入形态使批次意图明确

Reference: spec:AST-053/DEC-4 Decider: josephfarina, 2026-10-01

现有 CLI 调用方保留他们已在解析的零选择器和单选择器行为。编程式调用方通过省略参数或传入字符串来选择这些路径,并通过数组选择完整的批次回执。空数组和单元素数组仍然是批次,因此过滤选择器列表绝不会改变响应类型。

已否决:让数组的响应取决于其长度,这会在调用方过滤选择器时改变显式批次调用的形态;以及对字符串总是返回批次,这会改变现有调用方所依赖的稳定 JSON 形态。

DEC-5 — 独立的只读查寻默认按批次进行

Reference: spec:AST-053/DEC-5 Decider: josephfarina, 2026-10-01

重复的过程设置和分散的失败,是所有满足 E1-E5 的查寻(而不仅仅是组件文档)所共有的。在此记录生效之后获得准入的命令,会在其首个公开版本中采用共享的批次词汇。现有合格命令逐条迁移,且不改变零选择器和单选择器行为。

已否决:让采用完全可选,这会让每个命令产生不同的批处理模型;以及让每个多参数命令都成为批次,这会破坏那些参数并非独立只读主体的搜索查询、变更操作、比较、工作流和交互式会话。

未决问题

无。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx