跳转至

CLI 命令准入与编程接口对等系统规范

{
  "paths": ["packages/cli/clients/cli/**", "packages/cli/api/**"]
}

意图

智能体通过 Astryx CLI 的帮助文档、清单以及自身笔记来学习它,并通过编程式 API 编写相同的操作脚本。每个已发布的命令、子命令和选项都会成为智能体所依赖的表层,移除其中任何一项都属于破坏性变更。在编写代码之前,贡献者需要知道新行为应归属于现有命令、新选项、新子命令还是新的顶层命令,以及每一类各自需要满足什么条件。

本记录规定每种 CLI 表层在加入之前需要满足什么条件,规定每条命令都是对一个已有文档且经过测试的编程函数的一层薄封装,并规定人类可读输出可以使用的词汇表。

非目标

  • 命令、API、适配器和格式化器代码的位置,以及哪些模块可以读取环境。architecture:cli-surface 的 INV20–INV23 负责这部分结构。
  • 可发现性、环境变量、全局选项和配置。spec:AST-017 的 FR14–FR20 负责这些规则。
  • 对移除、重命名、行为变更、弃用或不兼容修复的分类。spec:AST-017 负责兼容性和发布生命周期。
  • JSON 封装、错误码和生成的帮助文档。architecture:cli-surface 的 INV2、INV3 和 INV7 负责这些内容。
  • 满足本契约的等价内部实现仍然有效。

要求

  • FR1 — 每条命令都是对一个编程函数的一层薄封装。 每个执行操作的命令或子命令 MUST 通过调用从 @astryxdesign/cli/api 导出的一个函数来执行该操作。在收到相同输入时,该函数 MUST 执行相同的操作并返回与命令在 --json 下输出相同的结果。命令只增加参数解析、渲染和退出状态;渲染 MAY 依据 CLI 的调用方式(例如包管理器的运行前缀)来组织提示语。它 MUST NOT 读取项目状态、更改文件、联系网络或产生该函数不会产生的结果字段或效果。仅对子命令进行分组的命令可豁免,仅描述 CLI 本身的命令(例如 help、version 或能力清单)也可豁免。此要求点名 @astryxdesign/cli/api,是因为自动化依据 spec:AST-017 FR14 依赖它。
  • FR2 — 编程式 API 有文档并被测试。 从 @astryxdesign/cli/api 导出的每个函数 MUST 有参考文档,说明其参数、每个选项及其默认值、结果类型、可能返回的错误码以及至少一个示例。测试 MUST 覆盖每个已记录的选项、每个结果类型和每个已记录的错误码,并且在该行为被移除时 MUST 失败。每条命令还 MUST 有运行 CLI 并检查其 --json 结果、人类可读输出和退出状态的测试,至少覆盖一次成功和一次失败。
  • FR3 — 人类可读输出使用统一的共享词汇表。 人类可读输出 MUST 只使用生成的帮助文档中的块类型:Record、Section、List、Text 和 Code。Text 块承载散文。条目和字段值 MUST 使用 Record、Section 或 List 块,绝不能使用命令自行用字符构建的列或表。在文档来源中编写的内容,例如参考文档中的标题或表格,遵循同样的规则。命令 MUST NOT 定义自己的输出格式。当现有块无法在不丢失读者所需信息的情况下表达输出时(例如表格太大而无法作为 Record 阅读),答案是新增一个共享块类型,而不是命令特定的渲染器。新的块类型会改变每条命令的输出,因此它 MUST 由该证据证明其合理性,MUST 对每条命令可用,并且 MUST 在同一个变更中出现在生成的帮助文档中。
  • FR4 — 新表层按层级准入。 每个新增项在合并之前 MUST 通过其层级的测试。

    • 顶层命令。 新的 astryx <command> MUST 引用一份当前的系统规范来授权它,并由批准所有者(知识模式 approvalOwners 中列出的所有者)批准。该规范 MUST 说明消费者或智能体提出的、现有命令无法回答的问题;最接近回答该问题的现有命令,以及为什么扩展该命令是错误的;该命令的唯一职责(表述中不能出现“和”);为什么其结果应是数据而非散文,散文属于文档主题;以及 FR1 所要求的函数。
    • 子命令。 新的子命令 MUST 保持在其父命令的唯一职责之内。其 pull request MUST 说明它回答的问题、为什么父命令上的选项或现有子命令无法回答该问题,以及 FR1 所要求的函数。CLI 包的代码所有者 MUST 批准它。
    • 选项。 现有命令上的新选项 MUST 满足 FR5 和 spec:AST-017 FR14–FR15。常规审查即可。

      未通过其层级测试的行为不会在该层级获得准入。它转而成为选项、子命令、文档主题或对现有命令的改进。

  • FR5 — 选项可预测地改变命令产出的内容。 选项 MUST 收窄或重定向其命令已经在做的工作,MUST NOT 给命令增加第二个职责。其默认值 MUST 是对大多数调用者而言正确的结果。布尔选项 MUST 默认为关;默认开启的行为应有具名的 opt-out,而不是默认为 true 的标志。只改变同一结果呈现方式的选项属于全局呈现选项,MUST 满足 spec:AST-017 FR15。选项名称 MUST 在每个拥有该选项的命令上含义相同、拼写相同,且任何命令不得因为兄弟命令有某个选项而跟着携带它。选项 MUST NOT 为了绕开缺陷而存在。命令上的每一对选项 MUST 有确定的结果:它们可组合且有测试证明,或者它们一起被拒绝并返回稳定错误码,或者已有其他规则阻止这对组合。

  • FR6 — 移动表层也属于准入。 重命名命令、将行为移入新命令或将子命令提升为顶层命令都属于在新层级的准入,MUST 通过该层级的测试。移除和重命名同样遵循 spec:AST-017 FR1–FR8 和 FR31:移除操作通过带 [breaking] Changeset 的已声明 minor 版本发布,而当下一个版本是 patch 时,命令会先被弃用(FR28)。
  • FR7 — 精确查找的准入先对批处理分类。 在编写代码之前,每个具有精确选择器位置的命令或子命令 MUST 依据 spec:AST-053 FR11 E1-E5 对该位置进行分类。符合条件的表层 MUST 在其首个公开版本中使用 AST-053 的批处理契约。不符合条件的顶层命令 MUST 引用一份当前的命令持有记录,指明失败的条件;草稿不能使该例外获得准入。不符合条件的子命令 MUST 在其准入 pull request 中指明该条件,并仍然遵循 FR4 的代码所有者批准门槛。在类型化的准入元数据落地后,其 CommandDoc MUST 保留相同的分类。现有符合条件的命令遵循 AST-053 的增量迁移规则。隐藏选项 MUST NOT 使批处理变为可选加入,也不得绕过此分类。

平台支持

  • 支持的功能/引擎下限:每个受支持的 CLI 运行时。
  • 不支持的行为:无。
  • 浏览器证据:不适用。

当前状态影响

architecture:cli-surface INV20–INV21 将 FR1–FR3 带入代码:API 主体的布局、适配器作为主体访问环境的唯一通道、精简命令处理器,以及封闭的格式化工具包。contributing:cli-conventions 为贡献者重述了 FR4 和 FR5。它尚未重述 FR7,且 CommandDoc 没有类型化的 AST-053 资格字段;在那里落地该规则并添加仓库检查,是已知的、将另行落地的强制实施缺口。

CLI 有 17 个顶层命令。28 个命令和子命令的命令文档指明了它们所调用的函数。已知缺口(本记录不为这些缺口分配迁移任务):

  • component、discover、layout、search、template 和 theme 处理器自行读取项目状态或文件(FR1);
  • theme 处理器用字符绘制其目标表格,docs 处理器用自己的代码渲染作者书写的标题和表格(FR3);两者都应成为 FR3 下一种共享块类型的候选,而不是两个命令渲染器;
  • 多个 API 主体在适配器之外读取或写入环境,并且 integration 主体保留了没有叶子节点的扁平模块(architecture:cli-surface INV20–INV21);
  • 14 个导出函数的参考文档(其中大多数位于 integration 主体内)未说明它们可能返回的错误码(FR2);
  • 结构检查确认每个 API 主体至少有一个参考文档、typedef 文件和测试,但并不确认每个导出函数或命令都被覆盖(FR2)。

目前尚无自动化检查强制实施 FR1、FR2 的逐函数部分、FR3、FR4、FR5、FR7、architecture:cli-surface INV21,或 INV22 和 INV23 的大部分内容。审查会将它们应用于每一个新变更;在自动化检查落地之前,新的违规只会在审查中失败。上述检查以及上述缺口的关闭将作为独立的变更落地。

本规范变更不改变任何运行时行为,也不改动已发布的包,因此不需要 Changeset。

验证

契约 验证 代表性状态 变更或失败预期
FR1 来自清单的命令清单,与 @astryxdesign/cli/api 导出匹配;在同一输入上成对运行 CLI 与 API 每个可执行命令和子命令;一个组;该清单 某个命令没有导出的函数,或者输出了其函数不会输出的字段或效果
FR2 每个导出项的参考文档清单;逐函数测试;命令级 CLI 测试 每个选项、结果类型和已记录的错误码;每个命令一个成功与一个失败场景 移除一个已记录的行为后,所有测试仍然通过
FR3 每个命令的文本输出快照;帮助快照 每种块类型;一个条目列表;一个形如表格的结果 命令输出了已记录块之外的布局,或者新的块类型未出现在帮助中
FR4, FR6 准入的拉取请求及其引用的授权依据 顶层命令、子命令、选项、重命名、提升 顶层命令在没有当前规范的情况下落地,或子命令在没有说明理由并获代码所有者批准的情况下落地
FR5 每个命令的选项组合测试 每个选项对;一个布尔默认值;一个共享选项名 某个选项对没有已决定的结果、布尔值默认开启,或一个名称有两种含义
FR7 依据 AST-053 E1-E5 及其层级证据进行的准入审查 合格的新查找;顶层和子命令排除项;草案 一个合格的界面只能是单一形态,或某个排除项缺少其层级所需的证据

决策日志

DEC-1 — 命令是编程 API 之上的薄层

参考: spec:AST-042/DEC-1
决策者: josephfarina,2026-09-24

每个操作由一个函数拥有。运行命令的代理和通过脚本调用 API 的代理会得到相同的结果,并且该行为在其所在位置被测试一次。命令只负责把参数转换为调用,并把结果转换为输出。

已拒绝:在命令处理器中实现行为,以及仅由命令提供的特性。这两者都会偏离 API,且自动化无法触及它们。

DEC-2 — 每个命令统一输出词汇表

参考: spec:AST-042/DEC-2
决策者: josephfarina,2026-09-24

代理用 grep 检索文本输出,而人则阅读它。一小组块类型让每个命令的输出可预测,并使其保持为 JSON 结果的一种视图。

已拒绝:逐命令渲染器以及用字符绘制的表格。它们会偏离 JSON 结果,也会彼此偏离,而且每一种都是一种代理必须单独学习的格式。

DEC-3 — 准入门槛随持久性分级

Reference: spec:AST-042/DEC-3 Decider: josephfarina, 2026-09-24

顶级命令是每个代理工作集中的永久概念,因此需要来自审批负责人的当前规范。子命令位于某个命令的职责范围内,因此说明用例并获得代码所有者批准即可。选项只会收窄命令已有的工作范围,因此选项规则和常规审查就足够了。

已否决:为每次新增都设置同一道门槛,这要么会阻碍小型选项,要么会让顶级命令过于轻易进入;以及为了让行为更容易被发现而新增顶级命令,因为在 spec:AST-017 FR14 下,帮助和文档已经能让行为被发现。

DEC-4 — 精确查找在准入期间对批处理进行分类

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

批处理形态是查找公开界面的一部分,因此在实现之前,准入阶段会应用 AST-053 E1-E5。证据仍遵循 DEC-3 的持久性分级:顶级命令需要当前记录,子命令需要拉取请求和代码所有者批准;当类型化元数据落地后,CommandDoc 会保留结果。

已否决:允许每个符合条件的命令保持仅单条模式,或将批处理隐藏在某个选项后面,这会让等效的只读查找拥有不同的自动化契约;以及为每个子命令排除项都要求新增系统记录,这会破坏分级门槛。

弃用与清理说明

这些表格向读者描述弃用和移除;某个移除的准入门槛是已声明的小版本及其 [breaking] Changeset(spec:AST-017 FR31)。

DEP-0006 — 弃用 astryx layout 命令组

字段 值
id DEP-0006
cleanup CLN-0006
package @astryxdesign/cli
surface CLI 命令组:astryx layout(expand、check、grammar),其三种 JSON 响应类型(layout.expand、layout.check、layout.grammar),以及来自 @astryxdesign/cli 的编程式 API 导出 layoutExpand、layoutCheck、layoutGrammar
old contract 压缩的 XLE/XLO 表达式被解析、验证并展开为 XDS TSX;带规范表面回显的表达式验证;带别名表的语法速查表
replacement astryx build 会选择最接近的模板作为起点。astryx template <name> <path> 会为它搭建脚手架。astryx docs layout 会讲解布局原则(脚手架、结构、间距、断点)。
warning 人类可读模式:每次调用在 stderr 输出一行,指明 DEP-0006 和替代命令。JSON 模式:响应信封中的 meta.deprecations 数组,每个条目为 {id, replacements},与文档化的信封模式匹配。
migration 非机械化。XLE/XLO 表达式语言在替代命令中没有源码级等价物。请使用 astryx build 找到合适的模板,使用 astryx template <name> 为它搭建脚手架,然后直接编辑搭建后的代码。
codemod 无 — 空操作:表达式是临时输入,不是 codemod 可重写的持久化源码。
downstream 受维护的 agent 文档将 build 作为入口进行讲解。布局指南(astryx docs layout)不受影响。
direct authority spec:AST-042(CLI 命令准入和编程式对等性)
state deprecated

CLN-0006 — 移除 astryx layout 命令组

字段 值
id CLN-0006
lifecycle DEP-0006
delta 移除命令注册、API 导出(layoutExpand、layoutCheck、layoutGrammar)、CLI 绑定、命令文档、测试,以及 layout.* 响应类型。
rollback 使用最终补丁基线中的相同 API、响应类型和测试,重新注册命令组。
state pending — 随声明的次要版本及其 [breaking] Changeset 一起落地。

开放问题

无。

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