跳转至

消费文档受众边界系统规范

{
  "paths": [
    "packages/cli/assets/docs/**",
    "packages/**/*.doc.mjs",
    "packages/**/*.doc.*.mjs"
  ]
}

意图

Astryx 向调用方发布的文档服务于使用 Astryx 构建产品的人和代理。它通过 astryx docs、astryx search、组件、钩子和模板文档、--json API、生成的代理指南以及文档站点触达他们。调用方必须能够对他们读到的每项内容采取行动。关于构建 Astryx 本身的材料属于贡献者知识库。

本记录拥有通过那些消费面交付的每份文档的受众边界,包括集成贡献的文档。

非目标

  • 贡献者文档、知识记录和仓库说明。
  • 文档结构、图谱身份以及调用方文档的质量标准;这些由文档契约拥有。
  • 满足本契约的等效内部实现仍然有效。

要求

  • FR1 — 已发布文档面向调用方。 已发布文档的每个部分 MUST 描述调用方可使用或依赖的内容:用途和替代方案、API 和默认值、可观察行为及其保证、组合方式、调用方继承的成本和义务、主题定制接缝、迁移,或调用方可以依据公共证据应用于他们使用 Astryx 创建的产品面或产物的质量标准。
  • FR2 — 排除维护者流程。 已发布文档 MUST NOT 要求其读者为 Astryx 维护者生成证据、满足 Astryx 的内部评级或晋升标准、遵循 Astryx 的贡献生命周期,或运行 Astryx 自己的测试和 CI 工具。该材料归属于拥有该主题的贡献者面;若不存在特定面,则归属于贡献指南。它永远不会默认退回为已发布文档。
  • FR3 — 系统保证保持为保证。 调用方可依赖的系统行为事实 MUST 保留在已发布文档中,并作为对调用方的保证来陈述。例如,"主题目标一旦发布即保持稳定" 是面向调用方的;"审查者必须检查主题目标是否稳定" 则不是。对调用方事实的维护者式措辞,其修正方式是重写,而非移动。
  • FR4 — 分发受众不是读者角色。 文档的分发受众决定哪个编译包包含它,例如公共包或内部包。它 MUST NOT 允许维护者流程材料进入任何包。内部包仍然是面向使用 Astryx 构建产品的人的。
  • FR5 — 强制执行以所面向的读者为衡量对象。 把关 FR2 的自动化检查 MUST 按内容所面向的读者来分类,而非按某个词的出现来分类。在把关之前,它 MUST 在已发布语料库上显示零发现,并捕获至少一个真实违规。包含被标记术语的调用方指令(例如 "对 transform 进行动画以保持合成器提升")MUST 通过。每个发现 MUST 指明文档和章节,并说明该材料应归属何处。该检查 MUST 为合法的面向调用方的用途提供明确、可审查的豁免。
  • FR6 — 贡献的文档遵循相同边界。 集成贡献给消费面的文档 MUST 满足 FR1–FR4。集成编写参考 MUST 说明此规则。
  • FR7 — 共享调用方评分标准只有一个所有者。 已发布的 is-my-code-good 指南 MUST 拥有判断调用方创建的产品代码是否良好使用 Astryx 的共享标准。专业化评分标准 MAY 添加权重和针对特定产物的检查,但 MUST 链接到共享标准而不是重新定义它们。调用方评分标准 MUST 使用公共输入,并且 MUST 将缺失的证据报告为未检查,而不是通过。

平台支持

  • 支持的功能/引擎下限:Intent 中列出的每个消费文档面。
  • 不支持的行为:无。
  • 浏览器证据:不适用。

当前状态影响

已发布的主题目录有一个 README,它说明了调用方可操作测试、维护者写作的常见迹象,以及该材料的去向。仓库说明陈述了相同的受众。FR7 将共享的面向调用方评分标准分配给 is-my-code-good;其指南和专业化链接是本次仅规范变更之外的配套实现。目前还没有自动化检查强制执行受众边界。编写类型为文档图谱声明了一个分发受众字段,包含 public 和 internal 值;目前还没有任何东西读取它。FR4 将该字段与读者边界分开。

本次仅规范变更不改变任何运行时行为或已发布包,也不需要 Changeset。

验证

契约 验证方法 代表性状态 变更或失败预期
FR1–FR3 审查编译器枚举的每份已发布文档 组件、钩子、模板、主题、代理指南;以维护者措辞表述的调用方事实 某个章节面向维护者,或调用方保证被移除而非重写
FR4 编译后的公共包和内部包测试 公共文档、内部文档、标记为内部的维护者材料 维护者材料出现在任何包中
FR5 检查夹具以及对已发布语料库的运行 干净语料库、真实违规、包含被标记术语的调用方指令、豁免 语料库失败、违规通过、调用方指令失败,或豁免静默通过
FR6 集成文档夹具 针对维护者撰写的贡献主题 贡献文档绕过边界
FR7 文档图谱与评分标准审查 共享代码评分标准、专门化模板评分、缺失的渲染证据 共享标准有两个所有者、专门化未链接、或缺失证据通过

决策日志

DEC-1 — 调用者行动测试定义边界

参考: spec:AST-041/DEC-1 决策者: josephfarina,2026-09-23

已发布的文档会到达使用 Astryx 构建的智能体和使用者手中,每一个额外的章节都会耗费他们的注意力。测试的标准是:调用者是否会根据内容采取行动。系统保证即使听起来像流程描述,也能通过该测试,因此它们会为调用者重写,而不是被移走。

已否决:因为维护者材料准确而将其保留在已发布文档中;以及因为调用者保证以流程措辞表达而将其移出。

DEC-2 — 以所面向的读者来执行验证,并衡量精确度

参考: spec:AST-041/DEC-2 决策者: josephfarina,2026-09-23

噪声过大的检查会被抑制,而不是被采纳执行。门禁必须证明它既能捕获真正的违规,也能放行那些与维护者流程共享词汇的调用者指令。

已否决:以一份纯粹的词汇列表作为门禁,以及将按受众分发用作存放维护者材料的地方。

DEC-3 — 调用者拥有的质量审查保留在已发布文档中

参考: spec:AST-041/DEC-3 决策者: josephfarina,2026-10-09

使用 Astryx 构建产品的个人或智能体,可以依据公开标准对其自身产品代码进行评估并采取行动。is-my-code-good 指南拥有共享标准;特定工件指南链接到它,并只添加各自的检查或评分。缺失的证据仍然保持可见,而不会被当作通过。

已否决:将每个质量评分标准都视为维护者流程,以及将共享标准复制到每个特定工件指南中。

未决问题

无。

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