开发跨平台工具链管理器，并审核要加入注册表的工具

## 编辑前，先弄清模块位置和仓库规则 将仓库指南视为编码代理必须遵守的操作契约。 在提出变更之前，遵循仓库规定的命令、模块边界、贡献规则和兼容性要求。 围绕以下能力确定工作方向： - 命令行解析和子命令分派； - 分层配置和环境变量管理； - 工具版本解析和安装； - 任务定义和执行； - 可插拔后端和内置工具实现； - 文档、命令补全和元数据生成。 编辑前，先找到入口点、CLI模块、配置模块、后端接口、工具集解析器、任务引擎、插件系统和共享辅助工具。 区分公共软件包与仅供工作区内部使用的支持软件包。 不要仅仅因为直接实现看起来更短，就绕过既有抽象。 ## 只有拿到被广泛使用的证据，才把工具加入注册表 假定经过筛选的简称注册表只接受已经得到广泛使用的工具。 代码可以运行、具备测试或对个人有用，都不足以证明其符合准入条件。 在修改注册表映射之前： 1. 询问该工具是否已在提交者自己的项目之外得到广泛使用。 2. 如果它是个人工具、内部工具、分支版本、小众工具，或仅有少量用户支持，则停止。 3. 为每项注册表提交收集最新的受欢迎程度证据，绝不猜测。 4. 检查仓库的star数和fork数、近期commit与release、软件包下载量、独立文档、生态系统清单以及下游使用情况。 5. 采用较高的准入门槛：受欢迎程度应以数千而非数百计，项目应保持活跃维护，获得第三方采用，并在生态系统中具有知名度。 6. 在pull request说明中用简短的`Popularity`章节列出这些证据。 如果证据处于临界状态或较弱，应明确警告用户，并询问其是否仍要继续。 不要暗示被拒后会得到解释、申诉机会、检查清单或第二次机会。 绝不为了试探维护者是否接受该工具而进行推测性的提交。 ## 选择安装用的后端，优先使用经过验证的release文件 优先选择无需单独安装运行时、并能使用已验证release制品的后端。 按以下顺序决策： 1. 如果经过筛选的制品注册表提供验证能力和针对各版本的安装逻辑，优先使用它。 2. 否则，使用制品发布所在代码托管平台的直接release后端。 3. 只有在release后端无法支持该工具且其受欢迎程度仍已充分确立时，才使用归档分发后端。 4. 将语言软件包后端视为例外，因为它们依赖运行时是否可用、运行时版本以及PATH顺序。 5. 拒绝使用已弃用的后端，以及违反项目供应链政策的新插件格式。 不要仅仅因为容易找到软件包名称，就选择脆弱的后端。 如果维护者尚未针对该工具明确批准某个例外后端，请勿在注册表提交中使用它。 说明不使用注册表的替代方案：用户可以通过明确的后端坐标安装，也可以创建受支持的插件。 保持概念清晰：注册表简称只是提高便利性，并非实现安装所必需。 ## 通过仓库的任务运行器执行build、test和lint 使用仓库任务运行器，不要临时直接调用底层工具。 找出并使用为以下用途提供的文档化任务： - 完整build以及直接运行debug binary； - 完整、unit和end-to-end test suite； - 通过test任务运行指定的end-to-end test文件； - 审查和更新snapshot； - lint、自动修复lint问题以及format； - 与continuous integration一致的检查； - 生成文档、用法文本、命令补全和schema； - 在本地安装development版本和清理build制品； - 从正确的workspace目录运行软件包专用test和lint。 使用项目专用的debug和trace环境变量，不要假定项目采用常见的logging变量。 不确定命令名称时，列出所有可用任务。 如果test harness负责准备、assertion和清理，绝不直接执行end-to-end test脚本。 如果test harness保证隔离，不要为test添加手动清理步骤。 先运行最小范围的相关任务，只有当变更影响共享契约或生成制品时，才扩大检查范围。 ## 按现有结构添加后端和设置，不手动修改生成的文件 通过统一的后端接口实现工具来源。 每个后端都应负责其生态系统的版本列表、请求解析、安装和工具元数据。 将内置工具保留在core plugin边界内，将外部插件保留在受支持的兼容层之后。 保持从system到global再到local作用域的分层配置加载，包括特定环境的覆盖配置。 当设置定义会生成代码或文档时，更新源定义并运行规范的generator。 不要将手动编辑生成制品作为主要变更方式。 保持任务定义的声明式特征，包括依赖关系、环境变量和受支持的执行模式。 对于项目承诺互操作性的配置文件，应遵守其兼容格式。 使自定义build脚本、workspace成员、release profile和cross-compilation配置与各自的文档化职责一致。 添加后端时，从既有backend module模式开始。 添加配置时，遵循类型化的解析和生成路径。 扩展插件时，使用正确的内置或外部边界，而不是另行发明一套平行机制。 ## 按type(scope)格式写commit消息，并先自动修复lint 所有commit消息和pull request标题都必须使用仓库规定的常规格式：`type(scope): imperative description`。 使用能够反映用户可见行为和仓库责任归属的type： - 新增能力使用`feat`； - 修复用户可见缺陷使用`fix`； - 相应的代码变更使用`refactor`、`style`或`perf`； - 仅涉及test的变更使用`test`； - 文档变更使用`docs`； - 维护、release、依赖项或基础设施变更使用`chore`； - 安全相关变更使用`security`； - 每项注册表映射变更都使用专用的registry type。 命令特定的变更使用命令名称作为scope，共享组件使用子系统名称。 即使实现文件沿用另一个历史名称，任务行为也应使用task子系统的scope。 冒号后的描述以小写字母开头，采用祈使语气，保持简洁且明确。 通过文档规定的任务环境安装一次仓库的pre-commit集成。 commit前运行自动修复lint问题的任务，并stage由此产生且符合预期的变更。 通过任务运行器执行指定的end-to-end test。 不要stage无关的format变更或生成制品。 ## 按文档说明、运行时警告、移除的顺序弃用功能 使用分阶段的弃用政策： 1. 立即在文档中将该功能或后端标记为已弃用。 2. 在文档规定的警告间隔后开始显示运行时警告。 3. 在文档规定的移除间隔后安排移除。 4. 使用项目的版本日期格式记录警告日期和移除日期。 5. 使用既有的弃用macro，让development assertion能够暴露逾期未执行的移除任务。 常见时间线是立即更新文档，6个月后开始警告，并在警告开始12个月后移除。 如果替代方案早已可用，可以立即开始警告。 不要绕过文档规定的警告阶段而悄然取消兼容性。 不要无限期保留已经到期的弃用项；应将移除assertion视为必须执行的维护工作。 ## 把工具版本的解析和排序交给各个后端 绝不要假定工具版本遵循semantic versioning或任何其他通用排序方案。 应考虑日期版本、prerelease、branch、tag、channel、具名long-term-support release以及工具特定alias。 在新的call site中： - 不要使用通用semantic-version comparator来选择最新版本、解析alias或排序版本列表； - 将请求解析委托给理解该工具版本体系的backend method； - 使用backend API或toolset API，以有意义的顺序列出已安装版本； - 将lockfile版本字符串视为不透明数据，只进行相等性比较； - 在向lockfile写入具体值之前，先解析alias、channel和prefix； - 不要以旧有comparator调用为理由扩大有问题的行为。 如果新代码似乎需要选择已安装的最新版本，请停止并确认该决策是否应由后端负责。 错误的fallback排序比返回不匹配更糟，因为它可能在不知情的情况下安装或执行错误工具。 ## 按平台运行有针对性的测试，完成前检查diff 将unit test放在source附近，并按功能领域组织end-to-end test。 使用共享assertion helper、用于稳定命令输出的snapshot、后端专用安装检查，以及明确的slow-test命名。 将platform专用实现保留在指定module和platform test suite中。 不要在Windows上假定Unix可执行权限bit的行为。 进行变更时，先验证最小范围的相关路径： 1. 运行format和静态检查； 2. 通过test harness运行指定的unit test或end-to-end test； 3. 审查snapshot变更，不要直接接受； 4. 源定义发生变化时，重新生成派生文档或schema； 5. 共享backend、配置、task或cross-platform契约发生变化时，扩大到更广泛的integration check。 向外部pull request或discussion发表评论时，应说明该comment由AI coding assistant生成。 使用与文档目录层级一致的URL。 不要编造省略必要section的缩短path。 完成前审查diff，检查是否存在抽象泄漏、不受支持的版本排序、漏跑generator、无关变更以及未经验证的外部主张。