Astryx 知识契约体系Knowledge Contracts人机协作的设计系统决策记录与评审架构【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryxAstryx 是一个fully customizable and agent ready的开源设计系统而知识契约knowledge contracts正是支撑其 Agent 协作、大规模评审和长期演进的核心机制。本文基于仓库中的架构记录 knowledge-contracts.md完整讲解 Astryx 如何把人类已做过的决策沉淀为可检索、可验证、可复用的契约记录如何通过 19 条不变量INV保证一条事实只有一个所有者、评审如何对每一个公共变更给出preserves / settled / violates / novel-human / out-of-scope五种结论以及写契约、冲突仲裁、变更耦合和 8 条已裁决决策DEC-1DEC-8的完整规则。读完本文你将掌握这套知识记录系统的数据模型、权威状态机、评审工作流和配套校验工具并能在自己的组件或主题变更中按契约流程落地。为什么需要知识契约Astryx 把组件、主题、设计规范和系统决策同时交给人类维护者与 Agent 共同演进。没有沉淀机制时评审者面对一个 Pull Request 只能反复翻阅历史记录回答两个问题某个行为人类是否已经做过决定这个 PR 是否在制造一个需要人类介入的新决定知识契约的目标就是让评审者无需重读旧 PR就能回答这两个问题已决定的直接引用未决定的明确升级给人类。从源码结构看这套系统由记录、模板、schema、校验脚本和 CI 门禁五层构成共同保证文档不会仅靠惯例保持 current。系统模型不同事实放在不同地方Astryx 的核心理念是不同的事实放在不同的位置避免任何一层成为什么都装的大杂烩。文档定义的事实归属如下记录类型承载内容存放位置依据 Owning code 一节Component contracts组件契约单个组件承诺的聚合行为Core/Lab 组件根目录下的PublicName.spec.mdModule contracts模块契约独立可缔约的公共 hook、插件、工具或子系统私有实现助手无需记录同一组件根目录下嵌套至少一层的PublicName.spec.mdFamily contracts家族契约兄弟组件共享的行为docs/families/Design specs设计规范人类拥有的视觉与交互决策含跨主题对比度/无障碍判定方法论docs/design/Theme specs主题规范单个主题包的意图、继承基础、token/调色板映射、必需配对/状态、例外、测量凭证、已知缺口、兼容性与产物packages/themes/theme/theme.spec.mdSystem specs系统规范跨组件、跨主题或改变架构的决策docs/specs/Consumer docs消费者文档props、示例与用法各组件目录下的*.doc.mjsAudit records审计记录当前证据与发现Wiki 中的component-scores.json自动化数据仓库评审者从变更代码出发只跟随问题所需的链接changed code or theme source → nearest current component, module, or theme contract → relevant family or design requirement → architecture or system decision only when referenced → mapped tests and audit evidence当新情况落在某条既有人类决策声明的范围内时评审者直接应用该决策而无需再次提问跨主题的 API、词汇、继承、校验、编译器行为与产物策略属于架构/系统记录人类跨主题对比度方法论属于设计记录而单主题自身的映射与例外只属于该主题包内的主题记录——这就是一条事实只有一个所有者INV2在目录结构上的体现。权威状态机每条记录必然处于三种权威状态之一draft对评审有用但不是规则current已被明确批准可以安全依赖archived仅保留历史有替换记录时链接到替换者。只有current记录指导实现与评审INV1。模板永远只产出 draft空白模板文本绝不等于已批准的决策INV5。19 条边界与不变量INV1–INV19knowledge-contracts 文档用 19 条不变量把整个系统的规则显式化。逐条理解它们是掌握本系统的关键不变量一句话语义INV1只有current记录指导实现与评审INV2一条事实只有一个所有者契约之间不得互相拷贝内容INV3既有决策可复用命中即引用不再追问人类INV4新判断必须显式无现行决策、决策冲突或决策本属人类时评审必须询问人类INV5空白模板不是政策模板只产生 draftINV6结构性变更按类型演进新增/移除某类型的必填字段需新建 schema 版本并在同一 PR 内迁移该类型全部活跃记录仅改模板措辞无需迁移INV7只有纯规范变更才走轻量 CI变更的每个文件都必须是 component/module/family/design/theme/system 规范之一INV8私有操作保持私有公共记录不得指名或链接私有发布/自动化系统INV9current 记录之间没有隐式优先级更新、更窄、更局部的记录不会静默覆盖另一条 current 记录INV10记录描述理想行为而非 PR 判决不因任何单一实现变更而存在不批准/拒绝具体 PRPR 与 issue 只能作为非权威示例出现INV11每个公共增量必须有权威结论每次公共 API 更新与公共行为变更在验收前必须匹配已提交的 current 权威INV12审计状态只有一个自动化数据仓库component-scores.json是当前分数与未决发现的运营来源未激活的PublicName.audit.json约定已退役INV13作者在创建权威前必须先搜索按拟议 canonical owner/id、受影响路径、导出符号与语义术语搜索现行记录与开放的 PRINV14current 权威按声明限定范围claim-scoped只批准记录所有权边界内明确声明的条目不得把窄决策扩展为相邻未缔约行为INV15契约向单一可落地的意图收敛作者声明主意图评审分别分类每个可观察增量可分离的违规/新决策增量先移除或拆分INV16规范治理生成的评审上下文只提供信息Agent 生成的摘要、清单、测试、截图、测量与建议只能证明符合/矛盾/缺陷不得发明方向或升级权威结论INV17缺失的评审上下文保持问题绑定先读 PR 与现行权威只填补缺失上下文用三个 why 追溯问题INV18产品契约保留实现自由新契约不得规定内部模块、文件名、算法、存储布局、CI 拓扑除非该机制本身是刻意公开的契约INV19自动化规范评审服务于人类决策涉及产品契约的 PR 在人类 owner 裁决前必须收到书面咨询分析但自动化不得批准、采纳或使契约变为 current这些不变量不只是纸面规则它们在 scripts/check-knowledge.mjs 与 check-knowledge.test.mjs 中有直接实现。例如validateAgainstSchema()强制 current 记录必须携带非空owners、review_triggers、verified_by且approved_by必须命中授权 owner、approved_at必须符合YYYY-MM-DDINV1 与审批元数据validateSchemaEvolution()读取git ls-tree校验 schema 的 append-only 性质版本化 schema 不可删除、不可修改新版本号必须递增INV6validateComponentModuleRelationships()双向校验 component 与 module 记录的modules列表与parent_component字段必须互相一致module 必须与父组件位于同一组件根Owning code 的结构规则。评审结论的五种分类对照现行权威评审把每个公共增量独立归类为五种结果preserves该增量恰好恢复或保持现行权威未添加超出它的公共 API 或行为settled一条既有 current 人类决策恰好覆盖该增量并被引用violates该增量与现行权威矛盾novel-human现行权威未解决该公共 API、行为、所有权、兼容性或设计增量out-of-scope该增量属于另一个组件、模块、家族、系统或产品。preserves与settled进入正常正确性评审实现与证据也通过才可批准violates收到 request-changes采用最小的符合性修复修改或移除违规增量评审不会为了救回矛盾的实现而推荐写一份规范可分离的novel-human附带改动从主意图中移除或拆分只有当novel-human是主意图、与主意图不可分割、或作者/owner 明确选择推进时才进入私有人类暂缓private human hold。一条 draft 记录永远无法清除评审缺口——只有经核验的 current 契约或适用决策才能产生preserves或settled。写规范与契约从搜索到 200 行软上限写作前必做三件事搜索现行记录中该行为、公共符号、受影响路径与拟议 canonical owner/id搜索开放 PR 中相同的 owner 路径、符号与语义术语更新 canonical owner 或与重叠工作协调——只有当该事实有独立 owner 时才新建记录并在 PR 摘要中解释为何既有 owner 无法容纳它对应 INV13 与 DEC-3。写作规则用熟悉的词和短小直接的句子每条规则只陈述一次并紧挨控制它的条件与例外只契约正在决策的语义切片把相邻行为声明为非目标或未缔约缺口不要为了让记录变成current而填满它分支/状态矩阵适合用可读表格呈现绝不为了缩短记录而删除契约内容。文档特别强调plain language 必须保留规范力度、谓词、基数、默认值、兼容性、权威、owner、ID、证据状态与决策状态。only、every、consistently、current、records、owns、delegates、inherits这类限定词与权威动词是契约语义而非润色改写时不得丢弃、泛化、弱化或升级它们重塑一条规则时要让其动作、激活条件、例外/非目标、owner 与证据状态与它们所限定的主张保持在同一行或同一项目符号中。200 行软上限单个规范记录尽量控制在 200 行以内但这不是 schema 规则、验证门、删除目标或迁移已接受历史的理由。超过时先删除真正重复的内容、在语义不变的前提下精简措辞、用可读表格或列表、并按 INV2 链接真正共享的权威仍超长就保留内容并在 PR 评审中说明原因。不得为凑数而压缩表格——人类可扫描性优先。同一条规则更平白的形式文档给出了一个稠密段落 → 平白表格的经典示范。稠密写法Whenitemscontains exactly one visible item, the component MUST announce that item exactly once; whenitemscontains zero or more than one visible item, it MUST NOT announce an item, and consumers that omititemsMUST retain the existing silent behavior.平白表格ConditionRequired behavioritemsis omittedMUST keep the existing silent behavior.Exactly one visible item is presentMUST announce that item exactly once.Zero or more than one is presentMUST NOT announce an item.平白版本改变的是形状不是含义——这正是契约写作的验收标准。评审前的检查清单对照来源比对编辑后的文本确认上述每项契约属性仍然显式存在确认每条规则的动作、条件、限定词、例外/非目标、owner、权威动词与证据状态都保持显式并紧贴其所限定的主张确认表格与列表改善了可扫描性而没有隐藏内容若超过 200 行说明为何需要额外空间。当 current 记录互相矛盾时draft 只是上下文不可能与 current 政策冲突按事实范围识别 canonical owner聚合组件行为、独立公共模块行为、家族行为、设计表征、单主题语义/映射、跨主题架构、消费者用法或审计证据若两条 current 记录主张不同评审停止——不按新旧、路径远近或具体程度选择记录一个novel-human缺口对应 DEC-1通过修改 canonical owner 并移除被拷贝的主张来解决缺口刻意例外由该 owner 记录受影响的记录链接它而非重述系统规范决策可以授权该变更但在评审者依赖之前当前 owning 契约必须在同一个 PR中完成修改。变更耦合文档不会仅靠惯例保持 current任何 component/module/family/design/theme/architecture 记录要成为current仓库必须支撑以下流程记录指明会影响它的代码面与验证它的检查触及该代码面的 PR 触发聚焦的契约评审评审从 PR 声明的主意图出发把每个公共增量独立归类为preserves / settled / violates / novel-human / out-of-scope五选一preserves与settled进入正常正确性评审实现与证据通过才可批准violates收到 request-changes 与最小符合性修复不把换规范当作默认修复手段可分离的novel-human附带改动从主意图中移除或拆分评审可以要求收缩而不裁决该附带改动的语义Bug 修复只在恢复既有 current 权威且不改变超出该契约的公共 API/行为时才是preserves任何可分离的 API、视觉、布局或交互附带改动走第 5/6 步视觉修正只要被现行组件/家族/设计/主题或客观无障碍权威精确覆盖即可归为preserves或settled但必须用真实渲染证据证明受影响状态与代表性未变状态新视觉表征始终是novel-human审计新鲜度由同一代码与测试关系计算相关代码变更不可能让审计看起来还是最新的。审计存储迁移是独立的契约变更需要版本化数据契约、对既有 wiki 行的自动化转换与对账、过渡期命名的事实源、sandbox 读取器切换与回滚证据——仓库内的逐组件本地文件本身不构成迁移方案呼应 INV12。契约优先于升级Contract before escalation评审与构建应收敛到能够落地的最小理想变更陈述 PR 的主意图并划分其可观察增量对每个增量应用现行权威——即使组件记录没有枚举精确的涂色既有设计与客观标准也可以结算一个视觉修正对矛盾使其符合或移除它不要提议修改规范除非改变政策本身是刻意且独立可评审的目标对未结算但可分离的增量移除或拆分继续主变更不要要求贡献者顺带解决相邻系统设计只升级一个幸存且有意的novel-human增量且只记录该增量所需的精确决策相邻模块行为可以保持未缔约。可操作的评审结果要点名该可落地收缩的验收标准而不只是报告缺少权威。记录一条新的人类决策贡献者用普通 PR 语言说明预期行为与主意图并响应评审无需了解仓库的规范系统评审者或 Agent 应用上面的收缩路径只有幸存且有意的novel-human问题继续推进贡献者不自行发明答案或规定无关的相邻行为授权 owner 在 PR 评审中作答维护者或 Agent 把该裁决记录进 canonical owning 记录优先在同一个 PR 内提交当维护者能更新分支时若无法更新贡献者分支则在其下打开一个小型关联规范 PR待该决策落地后 rebase 实现方向被接受则贡献者按需更新代码方向被拒绝则移除或修改被拒实现仅在边界意义重大且很可能再现时才记录被拒替代方案最终提交使先前的批准失效——owner 在记录与实现一致后批准精确 head对应 DEC-2。如果没有接受任何实现方向就关闭贡献者 PR维护者拥有的规范 PR 仅当该裁决独立有用时才保留。评审评论只是对话证据检入的记录才是 canonical 决策。何时值得记录满足其一即应记录为 durable outcome而非评审转录改变或澄清了某 component/module/family/system 的所有权边界建立了未来工作必须保留的需求或禁令拒绝了一个意义重大且很可能再现的替代方案。一个 prop 名、实现机制或废弃 PR 中失败的视觉实验除非本身通过此测试否则留在评审历史里。只有当裁决改变的是超出贡献者变更的共享契约、应独立落地或复用时才使用单独的底层规范 PR实现 PR 再 rebase 到该决策上。六组实战示例文档原文场景结果处理NumberInput 修改步进数学现行契约说最终操作 clamp 到min/max映射测试仍通过preserves继续正常正确性评审无需人类提问新的 NumberInput 路径使用此前已批准的相同变换顺序settled引用该DEC后继续正常评审包导出的 context 改变了必需函数参数而现行契约保留了早期操作形状violates请求最小符合性修改新兼容性政策是独立提案不是默认修复滚动溢出修复同时引入新的 hover 披露溢出恢复走 layout 权威披露无权威则移除或拆分不要让 bug 修复去规定整个交互模块Selector 以移除空指示器空间为主意图但现行决策未说选项标签是否必须对齐novel-human私有暂缓由 owner 裁决精确对齐契约产品为家族拥有的输入布局规则请求一次性 width propout-of-scope路由到家族契约而非创建组件专属 API源码与工作流中的所有权结构记录该放哪Owning codeAGENTS.md 把评审者指向最窄的相关记录组件记录是 Core 或 Lab 组件根的直接子级PublicName.spec.md公开名通常与根目录同名父/成员例外需要该根目录中精确的顶层或完整内联消费者文档条目公共语义模块记录嵌套在同一根目录下至少一层且父组件的modules列表与模块的parent_component字段必须一致hidden、fixture、test、生成、构建产物、覆盖、依赖与*.generated.spec.md路径被发现与 PR 路由一致忽略由 knowledge-paths.cjs 实现见 knowledge-paths.test.mjsWikicomponent-scores.json是当前运营审计数据仓库历史PublicName.audit.json预留从未获得 schema 或活跃记录已按 INV12 退役packages/themes/theme/theme.spec.md是该包主题的 canonical 记录docs/themes/README.md 仅是指南与索引——check-knowledge.mjs 的discoverThemeRecordCandidates()会对任何放在docs/themes下的.md主题记录直接报错docs/schemas/knowledge/v1/v2/v3.json定义必需结构schema 通过extends组合、按 append-only 版本演进scripts/check-knowledge.mjs 校验模板、记录与审批元数据check-knowledge.test.mjs用夹具验证每条路径change-scope.cjs 识别纯规范记录变更只有 spec 记录、theme 记录、architecture 记录等路径才算 spec-onlyspec-owner-gate.yml 把审批绑定到精确的 PR head主题审批来自.github/ENGOWNERS与.github/DESIGNOWNERS的并集记录元数据从不自我授权工作流仅对纯规范变更启用自动合并。一个真实的落地示例是 Banner.spec.md其 frontmatter 声明authority: current、approved_by: cixzhang、review_triggers: [public-api, layout, theming]、verified_by指向组件测试、theming 测试与 check-knowledge 脚本并在architecture字段链接architecture:public-component-api、architecture:component-theming-surface、architecture:theme-compilation——正是组件记录不拷贝架构内容、只链接其 ownerINV2的直观体现。仓库内另有docs/specs/下大量系统规范如 AST-001AST-034、docs/families/ 家族契约与 docs/design/ 设计规范共同构成这套知识体系组件的消费者文档则由各目录下的*.doc.mjs如Button/Button.doc.mjs承载与.spec.md职责分离。八条已裁决决策DEC-1DEC-8文档末尾的决策日志是这套系统自身已做过的人类决定每条都标注 Reference、Decider 与被拒绝的替代方案DEC-1 — Current-record conflicts do not resolve by precedenceReference:architecture:knowledge-contracts/DEC-1Decider:cixzhang,2026-08-30current 记录不会因为更新、更窄或更接近代码而覆盖另一条 current 记录。评审停止、识别 canonical owner 并在那里解决冲突其他记录链接该 owning 决策而非拷贝它。被拒绝静默选择最新或最具体的记录因为那会把文档顺序变成未经评审的系统政策。DEC-2 — New rulings normally stay in the contributor pull requestReference:architecture:knowledge-contracts/DEC-2Decider:cixzhang,2026-08-30人类裁决通常在暴露缺口的那个 PR 内讨论贡献者负责说明意图与修改代码维护者与评审 Agent 负责规范系统可行时在同一分支记录裁决无法更新贡献者分支时用小型关联底层规范 PR被拒实现被移除或修改仅当被拒替代方案保护意义重大的边界不再被争论时才记录它最终精确 head 审批证明决策与实现一致。被拒绝要求 owner 为每条裁决都开第二个 PR因为那会把答案与变更分离并增加多余评审工作。DEC-3 — Search overlapping authority before writingReference:architecture:knowledge-contracts/DEC-3Decider:cixzhang,2026-09-07起草新记录或实质扩展记录前搜索现行记录与开放 PR 时要用比标题更多的东西canonical owner/id、受影响路径、导出符号与语义行为术语。事实已属于某 owner 时扩展或投射该 owner仅当存在独立事实边界时才新建记录并解释既有 owner 为何无法容纳。被拒绝只搜索文件名或已落地的记录——语义重叠可能使用不同标题开放工作可能已在落地前改变同一 owner开放 PR 协调工作并提供证据但不成为权威。DEC-4 — Contraction precedes new authorityReference:architecture:knowledge-contracts/DEC-4Decider:cixzhang,2026-09-11当本可评审的变更携带可分离的矛盾或未决决策时移除或拆分该增量并让主意图继续前进。仅当幸存增量是刻意作为持久行为推进时才推荐规范而不是因为评审发现了相邻的不完整。被拒绝把每个未缔约附带改动都变成规范项目那会让窄修复吸收无关设计工作并使贡献者失去可落地的路径。DEC-5 — Current approval is claim-scopedReference:architecture:knowledge-contracts/DEC-5Decider:cixzhang,2026-09-11current 记录只授权其所有权边界内明确声明的主张可以刻意让相邻行为保持未缔约。评审者不把current当作整个组件或公共模块已完全规范的认证也不在应用窄的已批准决策前要求无关覆盖。被拒绝要求一个窄视觉或行为决策去契约命名模块的每个 API、组合、无障碍与实现事实。DEC-6 — Product specs govern; generated review context informsReference:architecture:knowledge-contracts/DEC-6Decider:cixzhang,2026-09-12已提交的 current 产品记录决定预期行为。评审从这些主张出发用生成的上下文、清单、测试、截图、测量与建议仅证明符合、矛盾或具体缺陷生成的完整性与绿色检查永不创造权威或升级权威结论。当 PR 或现行记录让上下文隐式时评审可以通过三个 why 追溯问题、把解决方案映射回问题、点名附带改动来填补缺口这些解释在被 canonical 产品 owner 记录为 current 行为之前始终只是上下文。被拒绝把完整的评审表单、有说服力的影响故事或通过的验证矩阵当作产品方向的替代来源。DEC-7 — Product specs contract behavior, not internal architectureReference:architecture:knowledge-contracts/DEC-7Decider:cixzhang,2026-09-12新的或实质修订的产品规范陈述符合实现必须满足的可观察契约并让等效的内部实现保持自由。只有当调用方或互操作系统刻意把某机制当作公共行为依赖时才指名该精确机制否则内部所有权与接缝属于架构记录验证仍是证据而非规定的 CI/测试拓扑。该规则前瞻适用既有 current 记录在被命名的人类 owner 迁移前保留其显式权威。被拒绝仅因为某实现提供了决策证据就把成功原型的模块图、算法、清单、日志、锁、事务设计、文件系统布局或 CI 任务提升为产品需求。DEC-8 — Spec review is advisory analysis for the human ownerReference:architecture:knowledge-contracts/DEC-8Decider:cixzhang,2026-09-12规范评审的自动化不止于把变更路由给人类它先产出书面的、有证据支撑的反馈——canonical owner、既有与重叠主张、所有权冲突、主张范围、错位的架构内容与精确的契约编辑建议。该分析帮助人类 owner 检查决策但绝不替代 owner 的批准或成为权威。被拒绝因为检查全绿就自动批准规范或只返回需要人类却不给 owner 提供评审者已掌握的契约与所有权分析。验证与实施文档的 Verification 一节把不变量映射到具体证据与失败信号核心几组如下InvariantEvidenceFailure signalINV1, INV6scripts/check-knowledge.test.mjs未批准的 current 记录或未迁移的活跃记录通过校验INV5, INV7.github/scripts/change-scope.test.mjs模板、schema、指南、架构、代码变更、不安全重命名或截断列表被当作纯规范变更审批跟随当前 head.github/scripts/spec-owner-decision.test.mjs对另一提交的批准清除了门禁、自封 owner 成为审批者、或错误的 owner 组批准了 current 主题记录INV3, INV4, INV11盲审历史基准blinded historical review benchmark评审重问已决决策、发明新决策、批准未决公共增量、或把矛盾当作 preservesINV10记录内容与评审处置夹具规范给 PR 下判决或评审把 PR 链接当作权威INV13盲审写作夹具 重叠搜索收据作者制造平行权威、只搜已落地记录或文件名、漏掉 canonical owner 上的开放工作、或把开放 PR 当作权威INV14, INV15窄决策与混合意图评审夹具当前视觉切片被迫契约整个模块、可分离附带改动阻塞修复、或评审只报告缺口而无落地修复INV16, INV17规范优先评审与缺失上下文夹具生成的清单完整性覆盖权威、评审发明产品方向、重述已有上下文、或漏掉无关附带改动与受影响调用方状态INV18规范评审机制分析 owner 迁移收据新/修订产品规范要求私有机制却不证明其公开性、静默使既有 current 记录失效、或把被触及的架构措辞留在产品契约中INV19规范评审所有权冲突收据 人类决策自动化批准产品契约、遗漏 current/open owner 重叠、漏掉冲突或架构泄漏、或只返回人类暂缓而无书面的可操作分析当前实施缺口文档明确承认目前还没有检入的门禁能证明开放 PR 搜索已被执行。在该门禁存在前PR 摘要必须记录搜索词、canonical owner/路径、以及已检查的重叠开放工作。对开发者的落地建议编辑知识记录或模板后运行pnpm check:knowledgeAGENTS.md 的 Validation 一节它会执行上述整套校验涉及纯规范记录变更时change-scope.cjs 与 spec-owner-gate.yml 会决定走轻量 CI 还是完整 CI、以及是否需要 owner 对精确 head 的审批。理解这套契约系统就等于掌握了在 Astryx 中让每个公共增量都有权威结论、让每条人类决策都能被 Agent 复用的完整协作协议。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考