Astryx Architecture Records 编写指南用标准模板沉淀可验证的系统架构契约【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx本文围绕 Astryx 开源设计系统中docs/templates/knowledge/architecture.md这份架构记录模板展开讲解如何以标准化的 Frontmatter 元数据与固定七节结构把某个系统区域的职责边界、不变量、变更耦合与验证方式写成可被机器校验、可被评审引用的知识记录。读完本文你将掌握 Astryx 知识体系中architecture类记录的完整编写方法字段含义、authority 生命周期、schema 与模板版本分离机制、以及如何借助pnpm check:knowledge与docs/architecture/下已生效记录如 Theme application、Theme compilation对齐写作。架构记录Architecture Record是什么在 Astryx 中docs/目录维护着一套必须与它所治理的代码一起评审的维护者知识maintainer knowledge入口见 docs/README.md。其中architecture/目录专门存放以现在时描述已发布系统的记录它们不是提案也不允许把尚未发布的功能当作现状来写。架构记录回答两类问题见 docs/architecture/knowledge-contracts.md 的 Purpose某个行为人类已经做了什么决策当前这个改动是否引入了需要人类介入的新决策它的边界是架构记录只拥有系统内部的职责、接缝seams与满足决策规格deciding specs所需的机制绝不能超出既有决策去扩大可观察的产品契约模板正文第 25 行的注释明确了这个约束。与之配套的权威来源还包括docs/architecture/README.md说明记录以现在时书写、draft起步、经 owner 批准后成为current、归档记录保留上下文并说明不再治理的原因docs/specs/README.md说明系统规格system spec何时适用、只有current记录具有权威性docs/schemas/knowledge/v1.json 及 v2、v3定义每种记录 kind 的结构要求。模板的位置与整体结构模板位于 docs/templates/knowledge/architecture.md。模板与已发布的记录严格隔离——模板永远不存放在记录之中见 docs/README.md 的 Placement 约定Templates never live among records。模板以 YAML Frontmatter 开头正文包含 7 个##二级小节顺序固定小节职责Purpose本架构区域存在的目的System model系统模型、职责划分与关键机制Boundaries and invariants边界与不变量INV1、INV2…Change coupling代码变更如何触发对本架构的评审、哪些检查证明其仍然有效Owning code拥有各职责的代码路径或公共模块清单Deciding specs支撑本架构的决策规格引用Verification不变量 ↔ 证据 ↔ 失效信号 的映射表这 7 个小节是 schema v1 中architecturekind 的requiredSections见 docs/schemas/knowledge/v1.json 第 102-110 行。模板的小节顺序必须与 schema 完全一致scripts/check-knowledge.mjs 第 987-993 行会对模板做严格比对template section order must exactly match the schema。Frontmatter 元数据一份架构记录的身份证模板第 1-15 行定义了 13 个必填 Frontmatter 字段schema v1 将其列为requiredFrontmatterdocs/schemas/knowledge/v1.json 第 87-101 行。逐个说明字段含义取值/要求schema_version记录必须满足的结构契约版本当前architecture为1由 docs/schemas/knowledge/v1.json 定义template_version创建该文档所用模板的形式版本当前为1由 docs/templates/knowledge/versions.json 记录kind记录类型architectureid全局唯一标识形如architecture:surface如architecture:theme-applicationauthority权威状态draft/current/archived三选一archive_reason归档原因仅 archived 必填取值superseded/withdrawn/historicalsuperseded必须同时填写superseded_bysuperseded_by取代本记录的记录 id被取代时必填approved_by批准人current必填且必须是授权 ownerapproved_at批准日期current必填格式YYYY-MM-DDowners维护者current记录要求非空列表applies_to本记录治理的代码路径current记录要求非空列表verified_by验证本记录的测试或检查current记录要求非空列表deciding_specs决策规格引用形如spec:AST-000/DEC-0校验器对current记录的约束可以在 scripts/check-knowledge.mjs 第 1027-1057 行看到current记录要求owners、applies_to、verified_by非空currentNonEmptyFieldsapproved_by必须命中授权 ownerschema 中的approvalOwners即cixzhang与imdreamrunnerapproved_at必须匹配^\d{4}-\d{2}-\d{2}$。字段填写的两个关键原则current批准是声明范围的claim-scoped见 docs/architecture/knowledge-contracts.md 的 DEC-5——current只批准记录在其明确声明的所有权边界内的断言不承诺该组件/模块的每个行为都已规格化。评审不得把一条狭窄决策扩展成相邻未契约的行为。记录元数据不能自我授权主题theme类记录的批准权来自.github/ENGOWNERS与.github/DESIGNOWNERS的提交并集而不是记录里写的owners字段见 docs/README.md 的 Authority 一节。七个必填小节怎么写结合已生效记录逐节拆解以 docs/architecture/theme-application.mdarchitecture:theme-applicationauthority: current为范例它是模板的最佳实践样本。Purpose一句话说清存在理由Purpose 描述为什么要存在这个架构区域通常用应该should句式描述系统行为承诺。例如 theme-application 的 Purpose无论在普通内容、嵌套主题区域、portal 还是非 CSS 消费者中用户都应看到一致的主题挂载多个 provider 不得产生重复样式也不得让一个 provider 移除另一个仍在使用的样式。它同时会声明本记录不拥有什么如本记录不拥有主题创作、token 定义、编译器输出明确事实边界。System model以输入→机制→输出描述系统模型System model 用现在时描述核心机制。theme-application 的写法值得借鉴Theme接收DefinedTheme、颜色模式与 children按名称注册主题未预构建的主题向 web 编译器请求 CSS 并挂载到文档已构建built的主题则假定消费者已加载样式表不再编译或注入用主题名与颜色模式包裹 children根 provider 还会把当前主题名与显式明暗模式写到html嵌套 provider 不改动htmluseTheme正常情况下通过 React context 读取最近的 provider无 provider 上下文时独立 React root 或 fallback viewport走共享 fallback根Theme写html属性 →useTheme读取并每文档共享一个 observer → 在共享注册表中按名查找主题对象MediaTheme将局部表面标记为 dark/light/auto/off编译后的主题 CSS 据此切换表面 token 而保留父主题的组件规则AppShell复用同一套 provider/root-fallback 身份路径解析命名移动端导航宽度点。这段描述的价值在于它把正常 portal 保留 provider 上下文、fallback 无法恢复独立 React root 中的嵌套 provider这类边界情况显式写清楚避免后续实现产生歧义。Boundaries and invariants把契约写成可验证的不变量这是模板的灵魂小节。每条不变量以INVn — 名称的格式列出用加粗强调谓词动词句式是什么在发布的系统中必须始终为真。theme-application 的 10 条不变量示范了良好的粒度INV1 — The nearest provider wins.子节点读取最近的 Theme context 与 CSS scopeINV2 — Only the root provider changeshtml.嵌套 provider 只作用于局部不能改变浏览器 chrome 或 portal 级主题身份INV4 — Built themes are not compiled again.已构建主题使用已加载样式表跳过运行时样式生成与注入INV5 — Runtime styles are shared safely.多个 provider 使用同一未构建主题时共享一份文档级样式集仅当没有挂载的 provider 还需要时才移除INV7 — System mode follows the platform.system解析为当前亮/暗偏好且不向html写强制模式。编写时注意不变量应当可以证伪——每条都能在 Verification 表中找到对应证据与失效信号。模板第 25 行的注释强调架构记录绝不扩大产品契约所以不变量只写本区域负责的事实。Change coupling声明什么改动必须连带评审什么Change coupling 回答本架构如何保持有效。theme-application 的做法是逐条列出耦合关系provider 嵌套改动 → 必须测试 root、nested、portal 与清理行为样式生命周期改动 → 测试两个 provider 共用同一主题、卸载其一不影响另一个根属性改动 → 一起测试浏览器模式、portal 可达性与无 provider hooksuseThemefallback 改动 → 同时测试 provider 与无 provider 路径并确认 provider 消费者不会创建 document observerMediaTheme改动 → 测试 dark/light/auto/off/fallback/子节点身份不变运行时编译改动 → 先归属共享编译器并与静态构建路径对比。scripts/check-knowledge.mjs 会校验verified_by中的测试路径确实存在因此这里的描述必须与仓库中的真实测试对应。Owning code明确每份职责的代码归属Owning code 以- path or public module — responsibility的列表格式声明谁拥有什么。例如 theme-application 的 Owning codeTheme.tsx拥有 provider 作用域、运行时样式生命周期与根文档同步themeRegistry.ts拥有按名称查找主题的服务端安全逻辑useTheme.ts拥有 provider 访问与无 provider 消费者共享的 root fallback其观测/订阅逻辑保持单一归属MediaTheme.tsx拥有局部明暗表面上下文AppShell.tsx消费最近的生效宽度映射。theme-compilation 记录docs/architecture/theme-compilation.md则把归属延伸到 CLI 侧packages/cli/api/theme/build/build.mjs负责保存与打包编译后的 CSScore-interception.mjs负责捕获创作输入与生成轴元数据。这种运行时 CLI 双侧归属的写法正是模板Owning code想表达的完整所有权边界。Deciding specs引用而非复述决策Deciding specs 只做引用例如- spec:AST-012/DEC-1 — 可观察行为决策。它是决策的唯一来源架构记录绝不把实现证据当作产品权威模板第 39 行明确这一点。决策规格本体存放在 docs/specs/ 下如spec:AST-012Theme adaptations的决策 1-4 定义了 AppShell 消费的固定宽度点词汇与有序 adaptation 块spec:AST-006的决策定义了主题本地 token 的命名与校验。校验器scripts/check-knowledge.mjs 第 1383-1400 行会解析deciding_specs与references引用确认目标 id 存在且为current——current记录不得依赖非current引用。Verification不变量 → 证据 → 失效信号 的映射表模板收尾是一个三列表格这是整份记录可验证性的落点。theme-application 的示例InvariantEvidenceFailure signalINV1, INV2, INV3Theme.test.tsx与 portal/root fixtures嵌套 provider 改变了html或 portal 内容找不到根主题INV4, INV5运行时注入与清理测试已构建主题注入了 CSS重复 provider 产生重复 CSS或一次卸载移除了共享样式INV6, INV7useTheme.test.tsxprovider 消费者观测 DOM、fallback observer 泄漏、或 system 模式解析错误INV8MediaTheme.dom.test.tsx表面模式替换了主题、丢失父组件规则、或重挂载子节点INV10AppShell.test.tsx命名点忽略最近主题或把相等当作移动端写表的三条经验一条证据可覆盖多条不变量失效信号必须是可观察的失败而非实现细节证据路径要与 docs/architecture/theme-application.md 中verified_by字段保持一致的仓库路径。Authority 生命周期draft → current → archived模板 Frontmatter 的authority字段承载完整生命周期规则集中在 docs/README.md 的 Authority 一节与 docs/architecture/knowledge-contracts.mddraft仅用于评审参考不是规则未解决的证据与 owner 决策以 blocker 形式记录在文档内current经显式 owner 批准可安全依赖只有current记录指导实现与评审archived保留历史上下文声明archive_reason存在替代记录时链接superseded_by。提升为current的硬性要求校验器 scripts/check-knowledge.mjs 第 1027-1057 行强制执行owners、applies_to、verified_by均为非空列表approved_by是授权 ownercixzhang或imdreamrunnerdesign 记录还接受 DESIGNOWNERStheme 记录接受 ENGOWNERS ∪ DESIGNOWNERS 的提交并集approved_at为YYYY-MM-DD格式使用定义该 kind 的最新 schema 版本。纯规格记录的 PR 不产生 Changeset不发布包变更会等待spec-owner-approval状态当批准人与 PR 作者为同一人时需在 PR 中评论/approve-spec full-head-sha任何新提交都会使该批准失效。模板版本与 Schema 版本为什么两者分离docs/templates/knowledge/versions.json 记录了每种 kind 的当前template_versionarchitecture 为 1。而 docs/schemas/knowledge/ 下的 v1/v2/v3 定义每种 kind 的结构契约。两者的分工见 docs/README.md 的 Templates and schemas 一节template_version记录用于创建文档的写作形式编辑性模板改动只递增它schema_version记录必须满足的结构契约新增或修改必填元数据/小节就产生新 schema 版本已发布的 schema 文件不可变append-only见 scripts/check-knowledge.mjs 第 1073-1099 行的validateSchemaEvolution版本化 schema 禁止删除与修改只能新增更高版本并迁移活跃记录。template_version必须是不大于当前版本的整数第 952-958 行schema_version必须精确匹配记录 kind 对应的最新 schema第 960-965 行active kind records must use latest schema_version。实际演进路径v1 定义了 component/family/architecture/system-spec/implementation-plan/design 六种 kindv2 通过extends: 1追加themekind模板 theme-spec.mdv3 通过extends: 2修订component并新增modulekind。schema 组合逻辑见composeKnowledgeSchemas第 1149-1184 行。用真实案例对照从模板到 current 记录把模板与 docs/architecture/theme-application.md 逐节对照可以总结出从空模板到生效记录的写作路径填 Frontmatterid: architecture:theme-application、authority: current、owners: [cixzhang, imdreamrunner]、applies_to列出 5 个治理路径如packages/core/src/theme/Theme.tsx、verified_by列出 5 个测试文件、deciding_specs: [spec:AST-012/DEC-1]写 Purpose声明一致性承诺与不做什么写 System model以编号步骤描述 provider 挂载、编译注入、fallback 观测、MediaTheme 与 AppShell 的完整链路提炼不变量把 system model 中的每项承诺转成 INV1-INV10写 Change coupling按可改动面nesting/style-lifetime/root-attribute/fallback/MediaTheme/runtime compilation组织评审触发条件列 Owning code逐一映射Theme.tsx、themeRegistry.ts、useTheme.ts、MediaTheme.tsx、AppShell.tsx补 Verification 表为每组不变量指定证据与失效信号。注意 docs/architecture/theme-compilation.md 还示范了一个重要写法——Known conformance and verification gaps当已发布行为尚未完全符合批准契约时如前缀无关的 localTokens 尚未实现、私有--_*输入未端到端拒绝、嵌套伪类声明绕过 derived 展开要明确列出为已发布缺陷shipped defects而非提议行为。这保持了契约是权威、实现是证据的纪律。验证与落地pnpm check:knowledge所有模板与记录的结构合规性由 scripts/check-knowledge.mjs 验证仓库文档明确建议运行pnpm check:knowledge该脚本validateKnowledgeRoot第 1186-1404 行实际完成的检查包括组合版本化 schema确认每种 kind 使用其最新 schema校验模板template_version必须等于当前版本、字段必须全部在 schema 中、小节顺序必须与 schema 完全一致校验每条记录必填 Frontmatter、必填小节、authority 合法性、current的非空字段与批准元数据、id 全局唯一校验引用deciding_specs与references指向的 id 必须存在且为current校验组件/模块记录的双向归属图模块的parent_component与父组件的modules列表必须互相一致校验主题记录的存放位置必须精确为packages/themes/theme/theme.spec.md。通过--base revision参数还可以用 git 历史验证 schema 演进append-only 约束。这解释了为什么 docs/templates/knowledge/architecture.md 这样的空表单本身不是政策——模板只创建 draft评审与检索绝不能把模板文本当作已批准的 Astryx 决策docs/architecture/knowledge-contracts.md 的 INV5。编写规范与可读性要求docs/architecture/knowledge-contracts.md 的 Writing specifications and contracts 一节给出写作层面的硬约束适用于包括 architecture 在内的所有记录 kind使用熟悉的词与短句规则只陈述一次并与控制它的条件、例外放在一起只契约正在决策的语义切片相邻行为明确标注为非目标或未契约缺口能用表格提升扫描效率的地方用表格但绝不为了缩短记录而删除契约内容only、every、consistently、current、records、owns、delegates、inherits等限定词与权威动词是契约语义而非润色重写时不得丢弃、弱化或升级单条规格记录尽量不超过 200 行这是软性可读性上限而非 schema 规则先删除真正的重复、压缩无意义的散文、用表格与列表、按 INV2 链接共享权威若仍超限则保留内容并在 PR 评审中说明原因写记录前必须搜索既有 current 记录与开放 PR按 canonical owner/id、受影响路径与导出符号、语义行为词默认扩展既有 owner仅当事实边界确实不同且能解释为什么既有 owner 无法容纳时才新建记录DEC-3。评审时每个公开 delta 会被分类为preserves/settled/violates/novel-human/out-of-scope五种结果之一只有preserves与settled进入正常正确性评审violates要求最小符合性修复可分离的novel-human附加项从主意图中移除或拆分避免让一次窄修复吸收无关的系统设计工作。总结Astryx 的 docs/templates/knowledge/architecture.md 不是一份可以填空交差的普通模板而是与 docs/schemas/knowledge/v1.json、scripts/check-knowledge.mjs、docs/templates/knowledge/versions.json 以及 docs/architecture/ 下的已生效记录共同构成的知识治理闭环。掌握它的关键是记住三条主线结构由 schema 锁定七节固定顺序、13 个必填字段、权威由批准产生draft→current→archivedcurrent才指导评审、契约与实现分离架构记录描述可观察行为与内部接缝编译与挂载只是使用其输出。以 docs/architecture/theme-application.md 和 docs/architecture/theme-compilation.md 为范本你就能为任何系统区域写出同样具备Purpose → System model → Invariants → Change coupling → Owning code → Deciding specs → Verification完整闭环的架构记录。【免费下载链接】astryxAn open source design system thats fully customizable and agent ready项目地址: https://gitcode.com/GitHub_Trending/as/astryx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考