跳转至

Astryx 知识地图

此目录保存维护者知识,这些知识必须与其所管理的代码一同可审查。消费者文档仍保留在组件 .doc.mjs 文件和 packages/cli/assets/docs/ 中。

位置

  • architecture/:已交付的系统、其边界及不变量。
  • contributing/:实用的贡献者工作流程,由项目当前所有者记录而不取代它们。
  • design/:由人维护的视觉与交互规范。
  • themes/:包本地主题规范的指南与索引。
  • families/:兄弟组件共享的契约。
  • specs/:重要的已提议或已交付系统变更及其决策。
  • specs/components/:组件与模块契约,每个组件一个文件夹。
  • templates/knowledge/:编写模板。模板从不与记录混放。
  • schemas/knowledge/:模板与记录的版本化结构要求。

每个组件在所有包和平台上的记录都集中存放在一个文件夹 specs/components/<ComponentRoot>/ 中,该文件夹以保存组件代码的文件夹命名。该目录树与由 scripts/component-packages.cjs 注册的包的源代码树镜像对应:

  • 目录布局包(core、lab)存放 packages/<package>/src/<ComponentRoot>/,其记录为 specs/components/<ComponentRoot>/<PublicName>.spec.md;
  • 扁平包(charts、richtext、vega)存放 packages/<package>/src/<PublicName>.tsx,其记录为 specs/components/<PublicName>/<PublicName>.spec.md;
  • 平台实现的记录作为 specs/components/<ComponentRoot>/<PublicName>.<language>.spec.md 与核心记录并排放置,例如 specs/components/Avatar/Avatar.swift.spec.md。

<PublicName> 通常与根目录匹配;像 NavMenu/NavHeadingMenu.spec.md 这样的公共成员,只有在该根目录中存在声明相同公共名称的完全匹配的顶级或完整内联消费者文档条目时才有效。在扁平包中,公共命名导出和对应的 TSX 模块定义了组件边界。当两个包保留同名文件夹时,记录归属于持有其代码的包。

可独立契约化的公共 hooks、插件、工具和子系统使用 kind: module 记录,命名为 <PublicName>.spec.md,位于同一组件文件夹至少下一级目录中,通常在 modules/(specs/components/Dialog/modules/DialogHeader.spec.md)或插件自己的文件夹(specs/components/Table/plugins/rowStatus/useTableRowStatus.spec.md)中。子目录不必与模块代码所在位置匹配;查找通过代码的文件名或其 verified_by 证据定位记录。其规范 ID 为 module:<ParentComponent>/<PublicName>;模块的 parent_component 与父组件的 modules 列表必须一致。私有转换辅助工具不需要记录。

组件记录发现和 PR 路由会忽略隐藏路径段、*.generated.spec.md,以及 fixture、test、generated、build-output、coverage 和 node_modules 目录。这些文件不是知识记录,也不属于仅规范变更。主题契约与包放在一起,位于 packages/themes/<theme>/<theme>.spec.md。

权威性

每条知识记录都声明 authority: draft | current | archived。

  • draft 文档不是策略;未解决的证据和所有者决策以阻塞项形式记录在文档中。
  • 首次提升为 current 需要文档元数据中记录的明确所有者批准。任何当前的 .github/ENGOWNERS 成员均可批准所有记录类型;当前的设计和主题记录以及规范性设计资产也接受当前的 .github/DESIGNOWNERS 成员。遗留的 v1 owners 元数据仅为描述性,不授予批准权。
  • 创建、更改或归档 current 记录的拉取请求会等待审查门禁 review-required,直到所有者使用 /approve-spec <full-sha> 或通过审查(architecture:knowledge-contracts DEC-14)批准其内容。仅草稿记录无需所有者批准。
  • 只有 current 文档指导实现与审查。
  • 规范描述持久且理想的行为,独立于任何单个拉取请求。拉取请求和 issue 只能以明确的非权威示例、历史证据或参考资料形式出现。规范的存在目的绝不是批准、拒绝、分类、指定或授权某个特定的拉取请求。
  • 在创建或实质性扩展记录之前,请按规范所有者/ID、受影响的路径和导出符号以及语义行为术语,搜索当前记录和已打开的拉取请求。默认扩展或投影现有规范所有者;只有在存在不同的事实边界时才创建新记录,并说明原因。
  • 当前记录仅依赖其他当前记录。modules 和 parent_component 是结构性所有权链接,因此它们可以连接活跃的草稿/当前记录,而不会使草稿行为具有权威性。其他草稿关系列在候选记录上;提升会在所有者审查下更新受影响的回链。
  • archived 文档声明 archive_reason(superseded、withdrawn 或 historical),并在存在替代时链接 superseded_by。

模板与模式

模板用于创建文档;模式使现有文档在结构上保持一致。两者有意分开:

  • template_version 记录用于创建文档的编写形式。
  • schema_version 记录文档必须满足的契约。
  • 编辑性的模板更改只能递增 template_version。
  • 添加或更改必需的元数据或章节会创建新的 schema_version;已发布的模式文件不可变。
  • 每个活跃记录(draft 或 current)必须使用定义其类型的最新模式。添加新类型不会迁移无关记录;结构性更改现有类型仅迁移该类型的活跃记录。已归档记录可以保留仍已检入的较旧模式。

已发布的 schema 版本可以扩展更早的 schema。checker 会组合该链,并跟踪定义了每种记录类型的最新版本。因此,新的类型是增量式的;修改现有类型只会迁移该类型。

可选的 review-applicability:v1 JSON 块可以将记录中的选定 claims 路由为横切审查基线。这是一个与 anatomy-theming:v1 一样独立版本化的元数据叠加层,因此添加它不会改变记录类型所需的形状,也不会迁移未选择加入的记录。该块必须声明 scope: "global",并将每个语义触发器映射到同一条记录中的一个或多个精确 claim ID。校验会拒绝畸形、空、重复或过期的 claim 路由。路由要求被审查的 head,验证所提供的 base authority 提交是其 origin/main 合并基线,只包含 authority: current 记录,并且只返回匹配的 claims;草稿记录和不匹配的路由会被省略。

可选的 path-applicability:v1 JSON 块列出一条记录在没有 placement、path 字段、name 或继承链接覆盖时所治理的仓库路径:{"paths": ["apps/docsite/**"]}。这些模式是相对于仓库的 glob:** 是跨越任意深度的完整段,* 匹配单个段内,? 匹配一个字符。与 review-applicability:v1 一样,它是独立版本化的叠加层,因此选择加入不会迁移记录类型。模式必须以一个字面路径段开头。校验会拒绝畸形、不安全、重复、覆盖整个仓库以及无法匹配的模式。匹配只会将路径定位到记录;claim 作用域和优先级不变。当一条当前记录无法从任何本身不是记录的被跟踪路径到达时,pnpm check:knowledge 也会失败(architecture:knowledge-contracts INV25 和 INV26)。

新的记录类型应优先使用一个类型化的关系列表,而不是并行字段。如果 system-spec 在未来收到 schema 修订,请将其旧版 affects_* 字段替换为一个类型化的 affects 列表,其中包含诸如 architecture:*、family:*、theme:* 和 contributing:* 之类的 ID;此 PR 不会改变 v1 system-spec 的形状。

运行 pnpm specs:for <path> 可列出与任何仓库路径关联的当前记录:记录自身的 placement、applies_to 和 verified_by 条目、family 和 design 成员关系、affects_consumer_docs ID、文件在其文本(而非记录路径内)中引用的 system-spec 编号,以及这些记录继承的引用。只有可见的记录会被追踪,因此除非传入 --include-draft,草稿绝不会添加链接。作用域限定为单个 claim 或 decision 的引用(spec:AST-NNN/FR3)会列出该 claim,而不是整条记录。决定某条关联记录的 specs 会单独列出,匹配的组件和模块的触发器所路由的全局 claims 也会单独列出(与 review-global-baselines.mjs 筛选出的内容相同)。使用 --diff origin/main(或 --diff <base>..<head>)时,它会读取变更,在未指定任何文件时列出其文件,并将新增行匹配其所属记录 concerns 的 claims 排在前面。默认视图列出 claims 和关联的记录 ID;--records 显示每条记录如何关联。没有关联记录的路径会被报告为未关联。记录从工作树读取,因此在 pull-request 分支上,结果包含该分支提议的记录,且不构成审查权威。pnpm specs:for --unrouted 列出没有治理记录的被跟踪文件;--unreached 列出没有其他路径到达的当前记录。

运行 pnpm check:knowledge 以校验模板和记录。纯 spec-record pull request 不会添加 Changesets,因为它们不会发布包变更。

可见性

本仓库及其 wiki 是公开的。内部操作、凭据、服务、路由、调度和私有恢复流程都保留在受访问控制的私有空间中,不得在此处命名或链接。

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