Astryx 组件契约规范用 component-spec 模板承载 Agent 可读的设计系统知识【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAstryx 是一个fully customizable and agent ready的开源设计系统。为了让人与 Agent 都能准确回答这个组件承诺了什么行为、哪些行为已经由人拍板、哪些还需要人来决策Astryx 建立了一套结构化的知识记录体系其中组件契约Component Contract是最核心的一类记录。本文以 docs/templates/knowledge/component-spec.md 为骨架结合 docs/schemas/knowledge/v3.json、scripts/check-knowledge.mjs 与真实组件记录 packages/core/src/Stack/Stack.spec.md 等仓库证据完整讲解组件契约模板的每一个 frontmatter 字段、每一个章节的写作意图、theming anatomy 块的机器校验规则以及从 draft 到 current 的权威流转流程。读完本文你将能够识别组件契约在知识体系中的定位照着模板为任意 Astryx 组件起草一份可通过仓库校验的契约理解校验脚本对结构与语义的强制约束从而写出既规范又不会越界的内容。组件契约在知识体系中的定位Astryx 的知识记录knowledge records遵循一件事只有一个权威所有者的原则把不同事实放在不同记录里见 docs/architecture/knowledge-contracts.md**组件契约component spec**描述某个组件对外承诺的聚合行为aggregate behavior**模块契约module spec**描述由某个组件拥有的、可独立缔约的公共 hook、插件、工具或子系统私有实现辅助函数不需要记录**家族契约family spec**描述一组兄弟组件共享的行为**设计规格design spec**记录人类拥有的视觉与交互决策包括跨主题的可访问性与对比度方法论**主题规格theme spec**记录单个主题包的意图、继承基底、token/调色板映射、必需配对与状态、例外、实测回执、已知缺口与产物**系统规格system spec**记录跨越组件或主题、或改变架构的决策**消费者文档consumer docs*.doc.mjs**解释 props、示例与用法**审计记录audit records**持有当前证据与发现。组件契约既不是 prop 表格也不是消费者教程更不是实现步骤。它回答的是知识契约体系的第一性问题这个组件承诺了什么以及这里是否出现了一个需要人类拍板的新决策。模板 component-spec.md 就是为回答这些问题而设计的填空表单而authority字段决定了这张表单的效力draft仅用于评审、不是规则current是显式批准、可安全依赖的规范archived保留历史并链接到替代记录。模板与 schema 的版本对齐机制模板头部schema_version: 3、template_version: 4并非装饰。Astryx 的校验逻辑要求模板与 schema 严格对齐docs/schemas/knowledge/v3.json 声明 component 类记录的模板路径为docs/templates/knowledge/component-spec.md并列出该类的全部必需 frontmatter 字段与必需章节docs/templates/knowledge/versions.json 维护每种记录模板的当前版本号component 为 4scripts/check-knowledge.mjs 会解析模板本身校验其template_version必须等于 versions.json 中该类的版本、章节顺序必须与 schema 完全一致一旦发现模板字段缺失于 schema 或章节顺序漂移就会报错并要求提升 schema 版本并迁移所有活跃记录。从validateSchemaEvolution的实现可以看到docs/schemas/knowledge 下的版本化 schema 是只追加、不可变的旧版本 schema 被删除或改动都会直接失败新增版本号必须大于历史最高版本scripts/check-knowledge.mjs。这意味着组件契约模板的结构演进必须走新增 vN schema 迁移活跃记录的显式路径而不是随手改模板。Frontmatter一份组件契约的身份证明模板的 YAML frontmatter 定义了记录的身份、归属与权威状态这些字段全部由 schema 强制要求docs/schemas/knowledge/v3.json 中requiredFrontmatter列出的 18 项字段含义约束schema_version记录遵循的 schema 版本必须等于某个存在的 schema 文件活跃记录必须使用该类最新版本template_version记录遵循的模板版本正整数不得高于该类当前模板版本kind记录种类componentid记录唯一标识必须匹配^component:[A-Z][A-Za-z0-9]*$且必须与文件名对应如Stack.spec.md的 id 必须是component:Stackauthority权威状态draft/current/archived三选一archive_reason归档原因归档记录必须给出 schema 允许的原因superseded_by替代记录superseded类归档必须填写approved_by/approved_at批准人与日期仅current记录要求批准人必须是授权所有者日期格式YYYY-MM-DDowners记录所有者current记录必须非空review_triggers触发评审的维度模板默认[public-api, behavior, layout, theming, accessibility]current记录必须非空verified_by验证记录的方式current记录必须非空典型值为测试文件或仓库级校验脚本modules该组件拥有的模块记录必须解析到活跃的 module 记录且模块的parent_component必须回指本组件families所属家族如family:layout-primitivesdesign_specs关联设计规格形如design:surfacearchitecture关联架构记录如architecture:component-theming-surfacecontributing关联贡献规范形如contributing:surfacesystem_specs关联系统规格形如spec:AST-000/DEC-0id与文件位置的绑定关系由validateComponentModuleRelationships强制组件记录必须是其组件根目录的直接子文件如 packages/core/src/Stack/Stack.spec.md嵌套在组件根目录之下的记录则必须是kind: modulescripts/check-knowledge.mjs。平铺包flat package中的组件记录 id 还必须对应一个真实的公共具名导出与 TSX 模块防止记录与代码脱节。verified_by在真实记录里会列出具体验证载体。以 Stack 为例packages/core/src/Stack/Stack.spec.md它指向Stack.test.tsx、StackItem.test.tsx、themingTargets.test.ts与scripts/check-knowledge.mjs让评审者能顺着验证链核对契约主张。Intent先交代组件存在的理由模板第一个章节Intent只有一句注释指引写清楚这个组件为什么存在它承担的系统级职责是什么而消费者用法归*.doc.mjs。这是知识边界的第一道分界线契约描述系统层面的职责与承诺用法教程留在消费者文档。Stack 的真实 Intent 是很好的范例packages/core/src/Stack/Stack.spec.md一句话说明组件职责沿一条 flex 轴排列调用方内容一句说明 StackItem 的可选包裹作用再明确声明本 draft 只记录当前解剖与主题所有权不改变布局、padding、targets 或公共 API——把记录的改动范围收窄到最小语义切片。Compatibility and migration兼容性事实登记这一节用四行填空记录组件的兼容性事实模板要求Released default preservedyes/no/not yet releasedCompatibility class说明兼容性影响的具体范围Controlled/uncontrolled behaviorunchanged或陈述状态转变Migration decision指向组件级 DEC 或系统规格链接。消费者迁移指引属于消费者文档与发布说明契约本身只登记事实不替消费者做教程。Stack 示例填写为additive documentation only并明确 runtime、DOM、styling、targets、公共 API 均不变这属于preserves型变更的典型陈述。Ownership boundary先划清拥有什么、不拥有什么模板要求用两个清单回答边界问题Owns本组件承诺的职责例如 Stack 拥有容器与stacktheming target、可选 StackItem 包裹层与stack-itemtheming targetDoes not own / non-goals明确不属于本组件的职责并指出其真正所有者是family:family、component:Other还是产品调用点。Stack 的 non-goals 值得注意packages/core/src/Stack/Stack.spec.md内容由调用方拥有Stack 的 padding 目前是本地行为不参与 container-padding 协议对应 docs/architecture/container-padding.md新的布局、padding 或响应式行为不是本契约目标。知识契约体系明确要求只缔约正在决策的语义切片把相邻行为声明为 non-goal 或未缔约缺口而不是为了凑满current而顺手填写无关内容。Public concepts概念表而非 prop 表模板用注释强调这里是概念不是 prop 表消费者语法与默认值仍留在Name.doc.mjs。概念表按下列列组织列含义Concept组件局部语义概念的名称Closed values or states该概念的闭合取值集合或状态Meaning语义含义Availability by variant/orientation/state在哪些变体/方向/状态下对外暴露Default默认值Owner通常为component:Name或委托的家族/模块Stabilitystable或experimentalInvalid-value behaviorreject/ignore/fallback表只记录组件局部的语义概念、新增点与例外继承当前家族的既有规则若某个公共 hook、插件、工具或子系统有独立契约则在modules中列出其module:Name/PublicName记录并把 API、行为、可访问性、优先级与证据放在那里遵循spec:AST-002而不复制系统规则。Behavioral and layout contract行为不变量的证据链这是模板中最重要的工程化章节其设计意图写在注释里draft 需求必须注明依据避免把观察到的代码误当成有意的决策而一份current契约不允许存在未决行。行为表用四列组织ID需求编号FR1、FR2 …Candidate invariant以 The component MUST … 形式陈述的不变量Basis依据来源如既有 DEC、文档化承诺、标准、当前行为或提案Draft review statesettled已定、verify待验证或human decision需人决策。Stack 契约的行为表是教科书式的写法packages/core/src/Stack/Stack.spec.mdFR1–FR4 每一条都带 BasisCurrent source, docs, tests, and family与 Draft review stateVerified current behavior; no new behavior decided明确区分记录既有事实与制定新规则。该章节还包含四个子块各有专属语义Allowed variationAV列出变化了也不算回归的维度Representative states用State / Required invariant / Allowed variation三列表格刻画关键状态Transformation and precedence orderORD记录必须保持的变换管线与顺序例如 snap → round → clampPerformance and resourcesPR记录必须长期成立的测量、渲染、监听器、观察器或初始化约束——当前测量值属于审计记录本节只持有持久约束与其验证目标。Accessibility contract可访问性义务模板将其压缩为一个列表AR1 — obligation每条以 The component MUST … 陈述。可访问性契约只登记义务本身具体实现与验证证据归验证映射与审计记录。Design relationships设计要求的落点映射设计关系表把解剖部件或状态映射到设计要求列包括Anatomy or state解剖角色或状态Design requirement形如design:surface/DR1Representation authorityprescribed已规定、human-selected人选定或unsettled未定Hierarchy roleprominent或supportingComponent contract关联的 FR/AR 引用。模板特意强调组件实现设计要求但不复制其理由unsettled的表示仍属人类决策设计原则不允许 Agent 擅自替人发明答案。Stack 的设计关系表packages/core/src/Stack/Stack.spec.md把容器、Item、Content 三个角色分别映射到 FR1/FR4、FR2、FR1/FR2/FR3形成解剖、设计、行为三者之间的可追踪链路。Theming anatomy可机器校验的主题化映射Design relationships下的三级子块Theming anatomy是模板中唯一带版本化机器协议的部分其注释明确这是维护者元数据不得复制进 ComponentDoc、生成的 docsite 数据、CLI/MCP 输出或消费者文案。它要求必须恰好包含一个!-- anatomy-theming:v1 --标记后接 JSON 代码块JSON 的每个键必须与Name.doc.mjs中精确的英文解剖名一一对应不多不少target 名必须省略astryx-前缀并使用 kebab-case如stack-item每个解剖部件必须且只能声明四种处置disposition之一。四种处置的语义对应 scripts/check-knowledge.mjs 中的THEMING_DISPOSITIONS处置含义示例target本组件拥有该解剖部件的主题 targetStack container: {target: stack}inherits继承父级或根 targetinherited part: {inherits: parent-or-root-target}delegatesTo委托给其他组件/家族的主题 target{delegatesTo: {owner: component:Owner, target: target}}none当前不可达必须给出事实理由{none: {reason: intentional: …}}none的理由必须以intentional:、reachability-gap:或unsettled:开头并跟一段事实描述。校验脚本会交叉检查三类约束映射键与消费者文档解剖名完全一致target/inherits引用的 target 必须存在于组件文档的当前 target 清单中每个当前 target 必须至少有一个target处置的解剖条目防止 target 无人认领。delegatesTo还会进一步用 CLI 的主题化 target 清单与活跃家族记录验证委托目标确实由被委托者拥有scripts/check-knowledge.mjs。Stack 的主题化映射是target与none的典型组合packages/core/src/Stack/Stack.spec.md容器映射到stackItem 映射到stack-item而 Content 声明intentional: none——因为调用方内容保留自己的主题所有权Stack 不施加内容级 target。这正体现了none的语义intentional 说明这不是可达性缺口而是有意的边界。Family and system relationships向外引用而非复制frontmatter 负责列出结构性的modules链接本节只保留current的家族、设计、架构与系统关系。模板给出两条关系陈述范式module:Name/PublicName拥有独立的公共模块契约本组件拥有聚合的模块协议、顺序与组合family:family-name拥有共享概念本组件采纳或刻意偏离。候选家族或设计记录只在自己的记录上列出拟议成员不得仅为反向链接而修改既有组件契约。Stack 的关系节packages/core/src/Stack/Stack.spec.md指向family:layout-primitives共享方向/对齐/间距/尺寸/padding 词汇与两个架构记录明确共享知识放家族机制知识放架构。Verification map契约主张的证据闭环验证映射表把每条契约行绑定到具体证据列包括ContractFR/AR 编号Verification测试或浏览器证据Representative states覆盖的代表性状态Mutation or failure expectation写出删掉该行为会使什么失败Audit section形如audit:Name/section的审计段落。Mutation or failure expectation是这条映射的灵魂它要求作者预演回归场景例如 Stack 写的是Removing the container/content or changing shipped local padding fails existing tests.packages/core/src/Stack/Stack.spec.md。这使契约不只是文档而是一张可执行的验收网验证映射只要求足以证明主张的证据不授权特定的实现或 CI 拓扑。Decision log记录决策而非评审纪要Decision log只记录持久的边界或需求不记录评审过程只有当被拒绝的备选方案后果重大且可能重演时才保留。每条 DEC 的格式为DEC-N — 决策标题Referencecomponent:Name/DEC-NDecider决策人与日期正文理由与用户影响Rejected:可选被拒方案及原因。知识契约体系明确规定什么值得入录docs/architecture/knowledge-contracts.md改变或澄清了组件/模块/家族/系统边界确立了未来工作必须保留的需求或禁令拒绝了后果重大且可能重演的备选方案。纯粹的 prop 命名、实现机制或废弃 PR 的失败视觉实验一律留在评审历史里。Open questions 与 Content boundary显式的不完备Open questions用OQ1 — questioncheckable | human-design | human-api显式列出待决问题问题类型标注了解决方式可校验、需人类设计、或需人类 API 决策。Content boundary是每份契约的收尾声明本文件不复制消费者 prop 表与示例、当前审计结果、实现步骤或家族/系统规则只链接到它们的所有者。这呼应了知识契约体系的核心不变量 INV2——一个事实只有一个所有者。从模板到 approved权威状态与变更耦合模板本身只是一张填空表单而知识契约体系明确INV5——空白模板不是政策搜索与评审永远不得把模板文本当作已批准的 Astryx 决策。一份 draft 记录只有通过变更耦合流程才可能成为currentdocs/architecture/knowledge-contracts.md记录命名可影响它的代码表面与验证检查触碰该表面的 PR 触发聚焦契约评审评审从 PR 声明的首要意图出发把每个公共增量分别归类为五种结果之一preserves保持现状、settled已有当前决策覆盖、violates违反当前权威、novel-human无权威、需人决策、out-of-scope归其他所有者preserves与settled进入正常正确性评审violates要求最小合规修正改掉或移除违规增量可分离的novel-human附带物从首要意图中移除或拆分只有幸存且有意为之的novel-human增量才进入人工决策被授权所有者给出裁决后由维护者或 Agent 把裁决写回权威记录最终提交使先前的批准失效所有者对记录与实现一致后的精确 head 重新批准。这套流程配合 scripts/check-knowledge.mjs 的自动化校验模板/记录结构、id 唯一性、组件-模块双向归属、theming anatomy 映射、delegatesTo 委托、schema 演化构成了人机协作缔约的闭环机器保证结构与引用的完整性人类保证语义的权威性。写作规范模板在实战中的注意事项综合模板注释与 docs/architecture/knowledge-contracts.md 的写作规则起草组件契约时应遵守使用熟悉的词与短句每条规则只陈述一次并紧邻控制它的条件与例外保持限定词与权威动词的语义精度only、every、consistently、current、owns、delegates、inherits等词在改写中不得被删减、泛化、弱化或升级单条规格记录尽量不超过 200 行这是软性可读性上限而非 schema 规则超限时先删除真正的重复、压缩无意义冗词、用表格或列表提升可扫读性仍超限则保留内容并在 PR 评审中说明原因绝不通过压缩表格来刷行数用易读的表格承载分支或状态矩阵绝不为了缩短记录而删除契约内容用平实语言改写同一规则时改变的是形态而非语义——例如把一段密集陈述改写为条件表items省略时保持静默行为 / 恰有一个可见项时必须恰好播报一次 / 零个或多余一个时不得播报语义逐字保留。小结component-spec.md不是一份普通的文档模板而是 Astryx 知识契约体系的缔约表单frontmatter 提供身份与权威元数据Intent/Ownership boundary划清语义边界Behavioral and layout contract用带依据的 FR 行记录不变量Theming anatomy用版本化的 JSON 协议把主题化职责机器可读化Verification map用删掉它就失败的预期把主张钉死在测试上Decision log与Open questions显式区分已决与待决。三者共同保证任何评审者无论人类还是 Agent都能在不重读历史 PR 的前提下回答——哪些行为已被人类决定这次改动是否引入了需要人类的新决策。从 docs/templates/knowledge/component-spec.md 出发对照 docs/schemas/knowledge/v3.json、docs/architecture/knowledge-contracts.md 与 packages/core/src/Stack/Stack.spec.md 这一真实范本你就可以为任何组件起草一份结构合规、边界清晰、证据闭环的契约记录。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考