repository-standards 是一个面向已采用 .repo-standards/ 目录的项目所提供的技能,其作用是读取项目内已安装的仓库级规则,并在每次工作开始时报告 CLI 与标准是否有可用更新。该技能不自带规则,所有要求都来自所安装的规则。
一、用途
- 在项目任何工作开始时,报告仓库级规则与更新提示。
- 在修改文件前,查询该路径适用的规则。
- 检查 CLI 与标准两个版本锁定项的状态。
二、主要能力
- 仓库级规则查询:从项目 Git 根目录执行
.repo-standards/runtime/node_modules/.bin/repo-standards rules(不带路径),打印仅属于仓库级声明的规则,无需网络。若该命令失败:缺少运行时或 CLI_PIN_MISMATCH 时,按“Read the pins”部分恢复运行时后重试;ACTIVE_RUN 时读取 .repo-standards/rules/README.md 及其列出的覆盖整个仓库的已安装规则;NO_SELECTION 表示未安装规则,可继续;其他失败需报告诊断并解决后再继续。该类查询失败不会抑制更新提示,更新提示失败也不会抑制规则查询。 - 按路径查询规则:在项目 Git 根目录对每个将要修改的路径(包括新建或删除的文件)执行
.repo-standards/runtime/node_modules/.bin/repo-standards rules <path>,遵循其打印的规则。该查询包含仓库级规则,无需网络。 - 更新检查:执行
.repo-standards/runtime/node_modules/.bin/repo-standards outdated --json,该命令除被忽略的缓存外为只读操作,不要求干净工作区。若可执行文件缺失,运行npm ci --ignore-scripts --prefix .repo-standards/runtime重装固定运行时后再查;若因 CLI_PIN_MISMATCH 失败且消息给出重装命令,则从指定项目根目录执行该命令后重试。第二次仍失败或消息未给出重装命令时,报告两个锁定项均为 unknown 并附诊断,然后继续。 - 结果报告:对 cli 与 standards 两个锁定项分别报告——有更新时报告固定版本与最新版本,仅当某次更新检查已报告 updateClass 时才说明更新类别(exact 或 contextual),否则说明需通过检查确定;unknown 时报告 unknown 及原因代码与消息,查询失败不算错误,也不会中断当前工作;无更新时可报告为最新或省略。
- 更新执行:未经维护者指示,只提及可用更新并继续原计划工作,不检查也不启动更新;维护者要求更新时,通过 adopt 执行,作为与当前工作分离的独立变更,不与当前工作混在一起,运行不带源的 adopt 更新当前选择并遵循其打印的后续步骤,该运行从干净工作区开始,仅当其检查需要时才请求确认。
三、使用方式 以上命令均从采用该技能的项目的 Git 根目录运行。在采用或更新运行期间,rules 会报告 ACTIVE_RUN,此时只读取完整采用;该运行的上下文工作需阅读 .repo-standards/rules/README.md 及其为路径和整个仓库列出的已安装规则,运行的上下文工作请求也会列出每个声明已安装的规则。未安装规则的选取没有规则目录。
四、适用场景与限制 适用于已建立 .repo-standards/ 目录、需要统一仓库级规则的工程团队,可用于在开工与改文件前获取规则、检查版本更新。限制包括:技能本身不新增规则;规则查询无需网络,但更新检查依赖固定运行时;更新不会自动启动,须维护者明确指示;资料未说明支持的平台范围、收费方式和规则内容,暂未提供。