Astryx 贡献指南深度解读：PR 意图、公共 API 与 CLI 约定全解析

Astryx 贡献指南深度解读PR 意图、公共 API 与 CLI 约定全解析【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx导读本篇文章以 Astryx 开源设计系统仓库中的 docs/contributing/README.md 及其指向的三份贡献指南为核心系统讲解在 Astryx 仓库中提交高质量贡献的完整方法论如何为一个 Pull Request 选择唯一主意图与对应模板、如何设计与评审一个公共组件 API、以及如何向packages/cli命令面新增命令与参数。读完本文你将掌握 Astryx 的知识契约knowledge contract评审五分类、API 命名语法、Callback 与 Action 的编排规则以及 CLI 的 JSON 信封与错误码约定并能在实际贡献中直接落地这些规范。这三份指南把 Astryx 仓库现有的所有者记录owner records转化为可执行的贡献步骤。它们不创建政策也不替代架构记录、规范、family 契约或组件契约——理解这一点是读懂本文的前提。一、贡献指南的定位与总览docs/contributing/README.md是贡献指南的入口它明确界定了这些指南的性质它们将 Astryx 当前的所有者记录转化为实践步骤它们不创建政策也不替代架构architecture、规范specifications、family 契约family contracts或组件契约component contracts。入口页指向三份核心指南构成贡献流程的三大支柱指南主题适用场景Pull request intents选择一个主意图、使用匹配模板、提供正确证据任何 Pull RequestAPI conventions塑造、提出、实现与评审公共组件 API涉及公共 API 的改动CLI conventions提出、实现与评审packages/cli命令面改动涉及 CLI 的改动这三份指南并非孤立文档它们背后有完整的架构支撑知识契约 定义了五种评审结果与处置方式公共组件 API 架构 定义了稳定组件的公共契约不变量CLI 表面架构 定义了 CLI 的运行模型与 19 条不变量。下面逐一深入。二、Pull Request一次只有一个主意图2.1 核心原则一个 Pull Request 应该为一个原因做出一个可评审的改动。选择与主意图匹配的模板支持性测试和文档归属该意图但无关的 API、视觉、布局、行为或政策改动不属于它。GitHub 默认使用默认模板。要选择其他模板可以在新建 PR 的 URL 上追加?templatefile.md或者从仓库的.github/PULL_REQUEST_TEMPLATE/目录复制对应文件到 PR 描述中。仓库中确认存在七份模板bug-fix.md、visual-update.md、new-feature.md、documentation.md、specification.md、maintenance.md、other.md见 .github/PULL_REQUEST_TEMPLATE/。2.2 主意图与最低证据矩阵pull-requests.md给出了完整的意图 → 模板 → 最低证据映射表这是每个 PR 作者必须对照的核心表格主意图模板最低证据恢复损坏的行为bug-fix.md复现、预期权威expected authority、前后结果对比、未变化的代表性路径修正或有意改变外观visual-update.md当前视觉权威或所有者决策、真实浏览器的前后像素对比、相关状态矩阵新增能力new-feature.md用户需求、当前规范、完整公共差异public delta、行为与兼容性证据修正贡献者或消费者文档documentation.md读者影响、事实来源、渲染或生成结果记录持久决策specification.md精确的未决主张、已搜索的现有权威、决策、被拒绝的备选方案、明确的非目标改变工具、测试、CI 或仓库维护maintenance.md运维问题、失败证明、成功证明、产品行为不变其他other.md主意图、用户或维护者影响、权威、证据2.3 只解释权威未说清的内容Pull Request 与当前记录是上下文的第一来源不要把它们的摘要再复制一遍。只需填补缺失的部分用三个为什么追溯问题为什么发生、为什么损害受影响的任务、为什么这种损害重要将拟议方案以及每一个主要/支持性差异映射回该问题移除或拆分一个贡献不清晰的搭车改动tagalong说明谁受影响、在何种受支持状态下、该改动启用或阻止了什么行为当公共 API 改变时展示代表性的改动前后调用点callsites、默认值与兼容性以及调用者必须做出的每一个额外决策。这些解释帮助评审者应用当前权威它们不创建权威。产品行为仍归相应的组件、模块、family、设计、主题、架构或系统记录所有。API 调用者负担遵循spec:AST-002即 AST-002 公共 API 准入与运行形态。2.4 保持意图原子化在请求评审前将每个可观察差异分区为三类主要Primary这个 PR 存在的原因支持性Supporting使主要改动完整所需的证据或文档搭车Tagalong可独立移除的行为、视觉、API、布局、政策或清理。移除或拆分搭车改动。一个 bug 修复不会因为旁边的控件也能改进而变成功能一个功能也不会因为同一个文件已打开就吸收无关清理。2.5 规范最后使用而非最先评审应产生能落地的最大理想改动smallest ideal change对每个差异应用当前的组件、模块、family、设计、主题、架构和系统权威若差异违反当前权威则使其符合或移除它——不要为了挽救实现而提议修改规范若差异未定但可分离则移除或拆分它继续评审主意图仅为团队想推进的、存续的、有意的持久决策提出规范。当前记录只治理其所有权边界内的显式主张。它并不意味着整个命名的组件或模块已被完全规定。2.6 视觉修正与公共仓库边界视觉改动不自动需要新规范。当当前组件、family、设计、主题或客观无障碍权威已经确定了确切结果时它可以作为修正进行展示该权威用真实浏览器像素验证受影响状态并附上代表性的未变化状态。新的视觉表征、主观方向或交互模型仍属设计决策应放入独立的规范或经所有者评审的视觉更新而不是挂在 bug 修复上。最后公共仓库边界描述、截图、提交、测试和规范记录都是公开的。不要包含内部链接、标识符、主机名、工具或运维上下文。三、API 约定塑造公共组件 API 的完整流程api-conventions.md用于在评审前塑造公共组件 API。它是实用投影不创建政策若与当前所有者记录冲突遵循所有者记录并修正本指南。仓库中的本指南是维护中的贡献者参考——公共 wiki 应链接到这里而不是保留第二份副本。3.1 从所有者开始只使用 front matter 中标注authority: current的记录。当链接到或容易找到时先读最窄的所有者。人类贡献者不需要理解或编辑规范系统也能贡献评审者与维护者负责路由新决策并记录最终裁决。所有者的查找顺序组件的Name.spec.md当其存在于 packages/core/src/ 代码旁的组件根目录时拥有组件行为docs/families/ 下的当前契约拥有兄弟组件共享的行为当前架构与已接受的系统决策拥有跨组件规则。从 公共组件 API 架构、知识契约 与 AST-002公共 API 准入与运行形态 开始。owners字段指明谁可以解决缺失决策。组件源码及其公共index.ts拥有已发布 API组件的.doc.mjs拥有精确的消费者语法与参考材料组件规范拥有本地语义 API 含义与保证包括其明确共同拥有的公共 hooks 或工具。3.2 语义契约与语法参考分离每个面向公共的 API 新增或语义变化都会更新其规范的所有者记录。只有当组件规范拥有变化的组件本地语义或明确共同拥有公共 hook/工具时才更新组件规范。所有者记录描述调用者意味着什么、观察到什么、可以依赖什么.doc.mjs仍是签名、props/参考表和消费者用法的权威。不要把语义契约变成第二份语法目录。组件规范继承其当前 family 契约中的每一条适用规则只记录组件本地概念、新增和显式例外。例外要链接到批准它的决策而不是复制或重写 family 规则。组件规范可以共同拥有一个并置的公共 hook 或工具当这种拥有是显式时。其本地语义契约覆盖输入与选项含义、默认值、无效值、不支持的组合输出与操作可观察结果与保证副作用、身份、生命周期、资源所有权与清理相关时。组件规范不拥有的公共表面要链接到不同的规范所有者。3.3 命名语法一次只命名一个概念这是公共 API 形状的核心共享语法表表面约定示例组件无前缀 PascalCaseButton、TextInputProps 类型ComponentPropsButtonProps公共 hookuseNameusePopover布尔状态isNameisDisabled布尔能力hasNamehasClear非受控布尔默认defaultIsName或defaultHasNamedefaultIsOpen同步回调onVerbonChange消歧回调onVerbScopeonSidebarCollapsedChange过渡 ActionverbActionchangeAction、clickAction逻辑方向start或endstartIcon、paddingEnd使用回调作用域前缀仅当动词可能指向多个部分时。仅当原生属性原样透传如htmlName时使用html前缀组件拥有该概念时保留更清晰的语义名。字符串值使用camelCase。一个公共输入在其完整值域和每个被接受的输入形态上必须有一个稳定的语义责任。其名称和类型必须披露调用者拥有的含义。一个语义输入可以派生多个视觉细节当它们形成一个内聚、命名的结果时。例如语义status或variant可以同时拥有色调与符号——这不是重载输入。拒绝一个 prop当其值或输入形态改变了它控制的轴或消费者需要实现知识才能预测它控制哪些轴。若两个轴由调用者独立拥有用独立输入表示并防止冲突组合若系统拥有它们的协调暴露语义概念并派生细节而不是以color等机制命名输入。平行输入不得创建隐藏的条件优先级——覆盖仅在名称、类型与每种组合下的行为形成显式连贯契约时才有效且无效或冲突状态须在 FR15AST-002 需求 下被防止。3.4 模块与工具函数按结果命名为公共模块与工具函数选择动词时依据其主要的调用者可观察结果与副作用。区分构造、检查、查找、转换、注册与保证状态不要用一个内部步骤命名公共函数每个公共能力保持一个可调用角色。下表是仓库级导出审计repository-wide export audit支持的动词角色节选核心行动词公共模块/工具角色边界define*构造或规范化并返回一个被支持消费者使用的持久类型值校验可以是前置条件仅检查或不变身份不是定义validate*/check*检查输入并返回结构化结果说明哪些失败被返回、哪些条件抛出create*构造或初始化调用者使用的运行时值、状态对象、源码、配置或视图结果可被规范化仅检查不是创建build*从部件组装复合配置或产物本行覆盖模块工具不覆盖 CLI 命令命名generate*从给定输入派生新聚合或序列化输出命名生成的结果不要隐藏无关变更resolve*从输入、选项、上下文或注册表中选出并返回具体值记录回退与缺失值行为parse*将外部或字符串表示转换为类型化/结构化表示公共契约说明无效输入返回null、返回结果还是抛出format*序列化值或产生展示文本而不改变源值影响输出时包含 locale、模式或回退行为get*读取或投影请求的值而不改变其来源包含注册表查找与确定性投影不暗示持久化is*/has*返回布尔谓词或类型守卫需要原因/警告/多个发现时使用结构化检查register*添加或替换共享注册表状态注册是显式副作用ensure*幂等地建立缺失的所需状态名称必须披露函数可能创建或变更的状态/资源use*暴露可读 context/状态并拥有 React 生命周期/副作用的 React hook遵循 Rules of Hooks非 hook 工具不得使用use*reset*将共享状态清除或恢复到文档基线受影响状态与目标消费者范围必须显式expand*将紧凑配置或表示转换为其更完整派生形式展开不暗示持久化merge*将兼容输入组合为一个返回值或组合行为说明优先级与冲突行为这些角色有当前仓库证据支持不是允许先挑一个熟悉的动词再让实现去适配。检查导出签名、实现、测试、消费者文档、受支持调用点与发布历史将记录的例外限定到拥有模块而不是削弱整个仓库的动词。不要静默重命名已发布的失配项。通过显式弃用与迁移保持兼容然后仅在已批准的兼容边界处移除或改变旧契约。3.5 Callback 与 ActionCallback 同步报告事件Action 启动感知过渡transition-aware的工作。Action 名称永远不以on开头。changeAction不取代onChange。组件可以支持其一或两者。两者都存在时先运行 callback再运行 Action除非组件的公共事件契约允许消费者取消它。api-conventions.md给出了可运行示例interface SearchInputProps { value: string; onChange?: ( value: string, event: React.ChangeEventHTMLInputElement, ) void; changeAction?: ( value: string, event: React.ChangeEventHTMLInputElement, ) void | Promisevoid; } const [, startTransition] React.useTransition(); function handleChange(event: React.ChangeEventHTMLInputElement) { const nextValue event.currentTarget.value; onChange?.(nextValue, event); if (changeAction !event.defaultPrevented) { startTransition(() changeAction(nextValue, event)); } }不要命名为onChangeAction。不要按类别要求每个输入回调必需性遵循组件的可用状态、控件与无障碍契约。当组件与消费者处理同一 React 事件时刻意组合处理器。仅当公共契约承诺preventDefault()会取消内建行为时才把消费者放在前面const handleClick composeEventHandlers(onClickProp, selectItem);若未承诺取消则保留组件的必需行为并在契约与测试中声明该顺序。3.6 DOM props、样式与 refs仅当组件拥有一个稳定的 DOM 元素时才扩展BaseProps见 packages/core/src/BaseProps.ts。只协调子元素或返回多个无关根的组件应暴露其实际拥有的更小契约。对于拥有 DOM 的组件用契约元素类型化BaseProps并将ref作为 React 19 prop 接受用Omit移除与组件概念冲突的原生名称将中性的data-*、ARIA、DOM 与事件 props 转发到契约元素保护组件拥有的 role、无障碍与行为 props 不被覆盖合并xstyle、className与style而不是选择其一。export interface PanelProps extends BasePropsHTMLDivElement { ref?: React.RefHTMLDivElement; children: React.ReactNode; } export function Panel({ children, ref, xstyle, className, style, ...rest }: PanelProps) { return ( div ref{ref} {...mergeProps( themeProps(panel), stylex.props(styles.root, xstyle), className, style, )} {...rest} {children} /div ); }在展开rest之前解构样式与自有处理器。双方需要同一事件时使用composeEventHandlers。在rest之后设置组件拥有的契约 props使展开顺序不能改变语义。3.7 开放视觉词汇表与封闭轴组件主题化表面 仅当轴是视觉的、且不可用的自定义值有一个独立于活动主题的安全确定性基线时才允许主题可扩展的 prop 轴。Heading.type符合条件因为必需的Heading.level提供了该基线Icon.size不符合——选择回退尺寸会静默改变几何、对齐或组合。行为、结构、放置、方向与状态机轴保持封闭。主题可以在封闭轴上重定义已有值但不能新增一个。被接纳的主题可扩展词汇表在组件子路径 barrel 中使用公共*Map接口prop 类型从其键派生// packages/core/src/Button/index.ts export interface ButtonVariantMap { primary: true; secondary: true; ghost: true; destructive: true; } // packages/core/src/Button/Button.tsx export type ButtonVariant keyof ButtonVariantMap;主题可以通过astryxdesign/core/Button的模块增强module augmentation添加被接纳的视觉值。组件契约或治理系统规范与聚焦测试必须展示无匹配主题规则时的回退共享结构守卫只检查公共 map、themeProps()反射与主题化元数据。不要假设嵌套的theme.components.button.variants形状。遵循当前 主题创作契约 进行组件目标与 style-key 覆盖。3.8 槽位与组合当内容或子行为有自己的契约时优先组合。命名槽位接受完整的子元素并直接渲染它AppShell topNav{TopNav items{items} /} sideNav{SideNav sections{sections} /} /不要把SideNav的状态或回调上提到AppShell让它们留在拥有它们的子元素上。仅当父组件必须提供条目数据或上下文时使用 render function。有限独立轴使用 prop而不是一次性产品配方。高层组合的新 prop 门槛高于工具组件——添加 prop 前先检查子元素、槽位、主题目标、样式逃生舱、父布局或现有 context 是否已经拥有该区分。3.9 API 提案门proposal gate识别当前权威后对改动分类。知识契约的变更耦合 拥有五种结果及处置preserves、settled、violates、novel-human、out-of-scope。本指南应用这些结果不重新定义它们。缺陷修复仅在恢复当前契约或标准且不超出该权威添加公共 API 或公共行为时才是preserves。为损坏状态提供聚焦回归证据与代表性的未变化状态。任何额外的公共差异都通过知识契约独立分类。对于声称的 API 新增或语义行为变更评审有四个阶段盘点公共差异Inventory the public delta陈述精确的语义 before → after按范围识别规范所有者包含从受支持包路径可达的支持声明、类型、context 字段、hook 返回、默认值与可观察行为。应用 API 准入Apply API admission拒绝组件可派生的公共选择、值/输入形态会改变受控轴的公共输入、平行输入间的隐藏条件优先级、以及同一语义动作的平行公共/包内部操作。内聚的语义 status/variant 可在公共含义稳定且披露时派生多个视觉细节。一个模块内保持一个规范操作名另一个操作需要真正不同的调用者拥有意图与契约。应用当前权威Apply current authority遵循知识契约拥有的结果与处置。草稿是有用的评审上下文但不是政策不能通过门。exact-head 所有者讨论或批准是决策证据已接受的决策在实现被接受前必须作为current提交到规范记录中。评审实现正确性Review implementation correctness当前权威确定公共契约后验证精确实现头、回归证据、兼容性、迁移、文档与代表性的未变化状态。机械清单与回执可以盘点差异并证明读了哪份当前记录——它们只是证据不选择语义也不分配 PR 处置。3.10 API 提案清单每个面向公共的 API PR 的最低可读摘要Owner链接规范的所有者记录并说明其权威。组件本地语义只用组件规范family、架构或系统记录拥有变化语义时用它们。若所有者在 PR 前是草稿或缺失命名预期所有者。Semantic before → after用一句话陈述调用者可见的含义与保证。Classification按知识契约命名preserves、settled、violates、novel-human或out-of-scope。Representative syntax仅当公共语法变化时包含组件的.doc.mjs仍是完整语法/参考权威。请求评审前证明调用者拥有展示两个其他方面相同但需要不同结果的情形、调用者为何知道区别、组件为何不能派生它——这是 AST-002 DEC-1公共 props 需要不可派生的调用者区分 中的准入规则。保持每个输入责任稳定遍历完整值域、每个被接受输入形态与平行输入的每种组合。更新语义所有者更新或添加规范的所有者记录记录输入、选项、默认值、无效值与不支持组合、输出、操作、保证与相关生命周期/资源义务而不复制继承规则。防止破坏状态使静态可知的无效组合在可行时不可表示否则记录校验或警告或安全回退。检查操作唯一性一个模块内一个语义动作的公共与包内部形式使用相同规范名。检查共享语法覆盖名称、可选性、callback/Action 顺序、取消、ref 目标、DOM 透传以及每个字符串轴是开放还是封闭。开放轴必须命名并测试其安全的无主题回退。保护兼容性陈述默认值与可观察行为已发布破坏性变更包含迁移。API 证据一起提交消费者用法或文档承诺变化时同一 PR 中更新消费者文档、公共导出、聚焦运行时与类型测试以及代表性集成覆盖。若应用当前约定后仍有两三个可行形态使用 API 仲裁API Arbitration流程比较相关情形下的真实消费者代码把证据放进 PR请所有者决定维护者或评审代理将最终裁决记录到拥有规范中。3.11 常见评审异味review smells公共 API 改动在其规范所有者记录中没有语义差异评审者只能从实现或语法推断含义同一语义动作在公共与包内部使用不同操作名一个公共输入对某些值/形态控制一个轴、对其他值控制额外轴平行输入创建条件覆盖却没有每种组合的显式契约或冲突状态预防prop 暴露组件可从状态、内容、布局、context 或平台派生的值高层组件积累调优 props 或复制子组件状态等价概念使用不同名称如onChangeAction而非changeActionAction 抑制其 callback或处理器顺序意外移除承诺的消费者取消路径因为假设所有输入都必需而要求 callback合格的主题可扩展视觉值是封闭联合、轴开放而无安全无主题回退、或行为/结构/放置/方向/状态机轴被开放给增强对无单一稳定契约元素的组件应用BaseProps或接受的 DOM props 从未到达该元素xstyle、className、style、ref 或事件处理器被展开顺序丢弃或破坏父组件包装槽内容或镜像属于被槽化子元素的 props提案发明嵌套的theme.components.button.variants层把绿色文档解析器当作完整 API 证明——解析与选择性漂移检查不证明导出可达性、运行时行为、ref 目标、透传、处理器组合、兼容性或完整文档覆盖。当一份当前记录与另一份冲突时停止不按新旧或具体程度选择——按知识契约路由到规范所有者。四、CLI 约定为 Agent 设计的命令面cli-conventions.md把 CLI 表面架构转化为改变packages/cli时应遵循的步骤。它不创建政策与 docs/architecture/cli-surface.md 冲突时架构记录获胜。4.1 CLI 为谁而设计调用者是 Agent。它在子进程中运行 CLI、读取--json并据此行动没有人在旁观看。阅读文本输出的人是被支持的读者永远不是设计服务的调用者。两条推论解决大多数争论CLI 不得阻碍 Agent 的流程无提示、无确认、无提问。无法完成的命令返回带错误码的 errorAgent 可分支与可执行的建议。输出数据优先--json是事实来源。文本输出是同一批值的投影由格式化器formatters产生。4.2 CLI 的度量标准给 Agent 访问一切有助于用 Astryx 构建的东西存在哪些组件与模板、它们做什么、如何用、面前代码有什么问题、以及改变该代码的工具。CLI 的度量是该表面的覆盖度与深度而非命令数量。最有价值的工作是让现有命令回答得更好。4.3 新增命令先批准、四条件齐备新命令在编写前需要packages/cli代码所有者批准。.github/CODEOWNERS 是所有者的事实来源。先开提案命令是永久概念——它出现在 help、manifest、README 与每个 Agent 的速查表中移除它是破坏性变更。命令在以下四者同时成立时才赢得一席之地它回答 Agent 在用 Astryx 构建时真正会问的问题——而不是 CLI 碰巧能暴露的函数没有现有命令可以通过加深来回答它——加深是默认选项。只有先说出你要扩展的命令以及为什么扩展它是错的才去够新命令它是一件工作——如果摘要需要和字那就是两条命令其结果值得作为数据返回——如果有用输出是给人看的散文那是文档主题不是命令。任一条件不满足通常应该做成一个 flag、一个子命令或一个文档主题。4.4 新增 flag宽松但有纪律Flag 比命令宽容不需要提案。但它们不免费每个 flag 都是 Agent 必须知道的分支以及必须有人保持工作的组合。好 flag 的标准收窄或重定向命令已做的工作——绝不赋予第二项工作默认值是大多数时候的正确答案——flag 的存在是为了逃离默认值而不是达到有用行为调用者必须传它才有合理结果说明默认值错了是布尔关闭或带值——默认为 true 的布尔 flag 是命名错误的 opt-out改名为 opt-out改变命令产生的内容——只改变同一结果呈现方式的 flag 属于全局集--json、--detail、--lang不属于你的命令不是变通方案——若 flag 存在是为了让调用者绕开缺陷修复缺陷有封闭的组合矩阵——见下文这是人们常跳过的检查。如果 flag 改变了命令是什么它就是子命令。4.5 组合矩阵Composition matrix落一个 flag 前把它与该命令上每个已有 flag 配对并为每个单元格做决定。只有三种合法答案每个单元格必须有一个它们组合——且测试证明之它们一起被拒绝——带清晰消息与代码它们不能共存——因为另一条规则已经拒绝会到达它们的组合。未决定的单元格就是缺陷。它作为没人选择的行为发布Agent 会比人先发现它。4.6 同名 flag一个名称是整个 CLI 上的承诺。两条规则相同的 flag 名处处含义相同、拼写相同——没有任何其他东西可以占用某个 flag 名表达另一想法没有命令因兄弟命令有某 flag 而被迫携带它——对齐的是含义不是存在性。4.7 输出使用共享函数绝不裸console.log绝不调用console.log。每条路径都已提供你要使用机器结果jsonOut({type, data, meta?})错误jsonError(message, suggestions, code)/AstryxError标题、散文、列表section()、text()、list()一条或多条记录record(obj, opts)、records(arr, opts)代码示例code(source)打印以上任意项emit(...blocks)JSON 必须隐藏的杂谈humanLog()、humanWarn()emit只接受渲染器产生的Block裸字符串无法编译。保持文本字段名与 JSON 键一一对应——文本输出是信封envelope的视图不是独立设计。实现位于 packages/cli/clients/cli/formatters/index.mjsjsonOut/jsonError/humanLog/humanWarn位于 packages/cli/foundation/response/json.mjs。从源码看json.mjsJSON 信封契约有四个保证每次--json输出都是单个有效信封成功{apiVersion, type, data}错误{apiVersion, error, code, suggestions?}不支持--json的命令在任何副作用前被拒绝--json模式下人类杂谈被抑制humanLog/humanWarn是 no-op未捕获的 throw 变成 JSON 错误信封而非原始堆栈。API_VERSION当前为 1暴露在每个信封上供消费者协商。4.8 错误每个失败都带代码没有现有代码合适时向foundation/response/error-codes.mjs即 packages/cli/foundation/response/error-codes.mjs添加一个。代码格式为ERR_SUBJECT[_QUALIFIER]按主体分组只追加append-only一旦发布代码永不移除、永不重新定义含义。消息可以随时改进措辞但绝不让调用者匹配消息。源码中的ERROR_CODES是Object.freeze冻结集合覆盖解析/派发如ERR_UNKNOWN_COMMAND、ERR_INVALID_OPTION、运行时如ERR_NODE_VERSION、ERR_CORE_INCOMPATIBLE、查找如ERR_UNKNOWN_COMPONENT、ERR_AMBIGUOUS_THEME、文件系统如ERR_PATH_TRAVERSAL、ERR_WRITE_FAILED、主题构建、升级、GitHub CLI、博客 RSS 与布局表达式等类别。在 Agent 有明显下一步的地方附加suggestions——近似名称、列出合法值的命令。4.9 每个命令都带文档命令没有name.doc.mjs中的CommandDoc就不算完成。填写summary、description、args、options各带描述、examples、exitCodes与related。Help 文本、README 表格与 manifest 都由它生成——未记录的 flag 是隐形 flag。至少给出一个 Agent 真正会运行的示例包括一个--json示例。4.10 标记进行中的工作部分表面未完成而今天上面没有任何标记。调用者无法区分已定型命令与仍在塑形的命令。落地一个尚不可依赖的命令或子命令时标记它并在文档中说明预期还会变化什么。将未标记的命令视为稳定改变其输出形态或 flag 从此就是破坏性变更。4.11 打开 PR 前的检查清单新命令代码所有者批准了提案每个命令一个文件带兄弟文档文件--json返回一个信封type匹配 API 函数每个失败路径带代码新代码只追加、从不编辑无console.log所有人话输出走格式化器文本字段名与 JSON 键匹配退出码在有/无--json时相同组合矩阵封闭每对组合有测试、被拒绝有消息、或不能共存你写的任何路径都通过assertWithin文档列出新 flag、一个示例与退出码不可依赖时标记为进行中。4.12 常见评审异味只有维护者才会传的 flag——这是调试工具别放进表面摘要含和字的新命令——那是两条命令因为另一命令有 flag 而添加 flag——存在性不必对齐含义必须没人决定的组合单元格——flag PR 中最常见的缺陷调用点发明的代码——代码住在唯一冻结表里字符串拼接构建的文本输出——一个发布内就会偏离 JSON--json输出缺少文本输出展示的内容——文本是投影不可能比 JSON 更丰富让 Agent检查你的配置的错误消息——说出文件名、键与期望值或给出建议默认值是无帮助答案的 flag——Agent 不会发现它。五、支撑体系知识契约与评审流程api-conventions.md引用的知识契约是整个贡献流程的裁判系统。它回答两个问题人类已经决定了什么行为这个 PR 是否在做一个需要人的新决定每个记录要么是draft评审有用但不是规则、current已显式批准、可安全依赖、要么是archived保留历史并链接到替代者。只有current记录指导实现与评审。每次公共 API 更新与公共行为变化在验收前都必须匹配到已提交的当前权威分类为五种结果之一preserves精确差异恢复或保留当前权威且未超出它添加公共 API 或行为settled现有当前人类决定覆盖该精确差异并被引用violates精确差异与当前权威矛盾novel-human无当前权威解决该精确公共 API、行为、所有权、兼容性或设计差异out-of-scope另一组件、模块、family、系统或产品拥有它。preserves与settled进入正常正确性评审violates以最小合规补救请求变更改变或移除违规差异可分离的novel-human搭车项从主意图移除或拆分。草稿记录不能清除评审缺口——只有已验证的current契约或适用决策能产生preserves或settled。契约先于升级contract before escalation陈述主意图并分区差异 → 对每个差异应用当前权威 → 矛盾则使其合规或移除 → 未定但可分离则移除/拆分 → 只为存续的、有意的novel-human差异升级。评审结论命名该落地就绪收缩的验收标准而不仅仅是报告权威缺失。新人类决策的记录路径是贡献者以普通 PR 语言解释意图并响应评审不需要懂规范系统→ 评审者/代理应用收缩路径 → 授权所有者评审回答 → 维护者/代理将该裁决记录到规范的所有者记录中同一分支提交优先不能更新贡献者分支时在其下开一个小链接规范 PR 并 rebase 实现→ 最终提交使先前批准失效所有者批准记录与实现一致后的精确 heads。若未接受任何实现方向关闭贡献者 PR。评审评论是对话证据签入记录才是规范决策。六、快速上手如何开始一次合规贡献将全部约定浓缩为贡献者的最小行动序列读入口从 docs/contributing/README.md 定位你的改动类型——PR 意图、API 或 CLI。找权威确定改动的公共面行为归组件/family 契约语义归规范消费者语法归.doc.mjs命令面归 CLI 架构。只依赖authority: current的记录从最窄的所有者读起。定意图用第二节的表格选主意图与模板.github/PULL_REQUEST_TEMPLATE/写下 primary/supporting/tagalong 分区移除搭车项。套命名与形态规则API 改动对照命名语法表与 Callback/Action 顺序CLI 改动对照共享输出函数表、错误码表与组合矩阵。按知识契约分类preserves/settled/violates/novel-human/out-of-scope之一附上语义 before → after 与所有者。一起提交证据实现、聚焦测试、消费者文档与代表性未变化状态在同一 PR 中然后请求评审。结语Astryx 的贡献体系围绕三个强约束运转一个 PR 一个主意图、公共 API 一次只命名一个概念、CLI 为无人在场的 Agent 设计。这套方法论的独特之处在于它将记录当作一等公民——组件、family、架构与系统记录是唯一权威评审与工具只应用和验证它们而提案、测试与截图只是证据。理解并遵循这三份指南意味着你的贡献不仅更快通过评审也以可被后续 Agent 与维护者检索的规范形态沉淀进仓库。相关机制、模板与源码均可在上文链接的仓库路径中继续深入查阅。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考