6.2 KiB
Agent Note: 统一 GitHub 标签分类体系
Status: implemented
English | 中文
问题
PR（Pull Request）标签回答两个相互独立的问题：工作带来哪一类变更，以及会对哪些持久的仓库领域产生实质影响。混用这两个维度，或同时保留同义的无前缀标签与带命名空间的标签，都会使查询含义模糊；封闭的领域清单则会迫使新领域归入不准确的类别。
Issue 已有原生 Issue Type 和独立的来源分类体系。在这两类对象上复用 PR 类型或来源标签会产生重复元数据，并削弱每个标签族的含义。
决策
每项开放或已合并的 PR 都带有恰好一个规范的 kind/* 标签，以及至少一个表示实质受影响领域的 area/* 标签。未合并即关闭的 PR 保留经迁移的历史标签关系，但不会凭空补充缺失分类。管理用途的标签可以并存，但不能满足这两个维度中的任一个。
变更类型
类型集合封闭且互斥：
| 变更类型 | 含义 |
|---|---|
kind/feature |
新增行为或有意改变行为。 |
kind/bug-fix |
修正错误行为。 |
kind/doc |
以文档变更为主导意图。 |
kind/testing |
在不改变产品行为的前提下修改测试或测试基础设施。 |
kind/cleanup |
在保持行为不变的前提下，维护或简化实现或仓库流程。 |
kind/dependency |
在没有其他主导意图时更新依赖。 |
类型记录主导意图。配套测试、文档、清理或依赖调整不会盖过功能变更或缺陷修复这一主导意图。新增类型会改变这项分类契约，因此必须明确修改分类体系和政策。
仓库政策会拒绝不支持的 kind/* 值，并将统一过程中移除的所有别名列为保留名称：kind/bug、kind/documentation、feature、bug-fix、doc、cleanup、testing、dependencies、ci、cli、llm 和 web-search。精确保留这组已迁移的名称，可以防止过时的同义名称被重新创建成看似无关的管理用途标签。
领域
领域表示持久的语义领域，而不是临时专项、归属关系或偶然触及的每条路径。一项 PR 修改不同契约时带有多个领域标签，但不会用一个总括标签和一个较窄标签重复描述同一项契约。GitHub 上现行的 area/* 名称和说明定义当前清单；本记录定义选择规则，以及简短标签说明无法可靠容纳的非显然边界。
area/web覆盖浏览器与 Electron 图形界面，area/vscode覆盖编辑器扩展，area/api覆盖跨界面协议与各语言 SDK。area/planning覆盖目标、计划、待办和调度，area/workflow则覆盖可执行工作流与后台任务运行时。area/artifact有意合并产物、附件与多模态交付。只有当这些关注点再次需要独立评审或查询时，才有理由拆分标签。area/tools适用于通用注册表、schema 与执行契约。具体能力使用自身的领域标签，除非它还修改了这项通用契约。area/hooks表示 Claude Code 与 Codex 桥接，area/infra覆盖构建、发布、CI、仓库门禁、生成器、依赖与开发者工具，area/windows覆盖原生 Windows 产品支持，而不是 CI runner 的选型。
领域集合有意保持可扩展。当现有说明都无法如实涵盖一个持久且可复用的领域时，agent（智能体）无需另行批准，即可创建一个简洁的 area/<lowercase-kebab-case> 标签。agent 不得为单个 PR、偶然涉及的路径、临时项目、状态、个人或团队创建领域，并且必须在应用新标签后向请求者报告该标签及理由。仅为避免新增一个确有必要的领域标签而复用不准确的领域，不可接受。
Issue 与迁移
Issue 使用原生 Issue Type，而不是 kind/*；其 area/* 标签仍然可选。source/* 标签记录 Issue 来源，不适用于 PR。优先级、GitHub 默认标签和工作流触发器仍是相互独立的管理元数据。
迁移标签时，须先保留语义，再移除别名：先添加规范替代标签，核验可加标签对象，再移除废弃的标签关系。只有在所有 PR 和 Issue 都不再使用某个标签后才能将其删除，且绝不整组替换无关标签。
考虑过的替代方案
无前缀标签。 无前缀名称可以减少视觉噪声，但无法表明标签分类的是意图、领域、来源、优先级还是自动化用途。同时保留无前缀和带命名空间的同义标签，也会使查询和政策执行含义模糊。
不区分维度的单一标签集合。 某个标签存在，并不能证明意图和语义范围都经过了考虑。
仓库政策中的固定领域允许清单。 持久的仓库领域会演进。area/* 命名空间仍可机械识别，而现行说明承载可扩展清单。
按包或路径派生的领域。 领域描述跨越包边界的语义影响，而变更路径会包含偶然涉及的测试、文档和支持文件。
为每种交付载体或媒体生命周期单设标签。 浏览器与 Electron 交付共用一个图形界面领域，产物、附件与多模态交付目前也共用一个评审／查询领域。只有当拆分能恢复有用的独立分类时，才应在后续分类体系变更中进行。
用宽泛的实现标签取代语义领域。 一项具体能力并不只是其工具、接口、文件系统或进程实现。通用实现领域只在其自身契约变化时适用。
在 Issue 上使用类型标签。 原生 Issue Type 已负责这项分类；再用标签复制会造成漂移。
每个 PR 恰好一个领域。 内聚的变更可能对多个独立契约产生实质影响，丢弃次要领域会隐藏受影响范围。
后果
评审人和自动化流程可以分别查询意图、语义范围、来源、优先级和工作流触发条件。维护者必须阅读变更内容和现行标签说明，而不能根据标题前缀或路径推断分类。当某种类型或某条非显然的领域边界发生变化时，现行标签清单、本记录中的决策依据和政策执行必须同步更新；分类体系迁移还会产生明确的历史回填和验证成本。