跳转至

MPSBoost Agent 工作规则

本文件位于 specs/，属于项目开发规则资产，不是普通用户入口。普通用户与 AI 使用入口 请看根目录 README.md 和 ai-skills/mps_boost_skill.md。

1. 最高优先级

本项目采用规格驱动开发（SDD）。specs/constitution.md 是项目宪法，specs/prd.md 是产品事实来源，模块设计规定实现边界，specs/tasks.zh-Hans.md 规定执行顺序。代码、测试、构建和发布均不得违反规格。

specs/tasks.zh-Hans.md 是完成状态的权威来源。英文 specs/tasks.md 必须作为文档站的 原地忠实翻译保留；任务文本或复选框状态变更时，必须在同一个 patch 中同步更新中英文 文件，保持双语矩阵一致。

优先级从高到低为：用户当前明确指令、项目宪法、已批准 PRD、模块设计、任务清单、代码实现。发现冲突时必须停止实现，先说明冲突并修正规格，不得自行选择更方便的解释。

2. SDD 工作顺序

任何模块必须按以下顺序推进：

  1. 阅读宪法、PRD、项目树和相关模块设计。
  2. 确认任务依赖、输入输出、错误语义和验收标准。
  3. 操作前说明新增、修改和删除的文件及预期效果。
  4. 获得用户确认后，使用 patch 完成一个内聚模块。
  5. 按规格编写真实实现及真实测试。
  6. 运行测试、静态检查和必要基准。
  7. 只有全部验收条件实际满足，才能在 tasks.md 将 [ ] 改为 [x]。
  8. 一个内聚模块一次 commit，便于审查和回退。

禁止先写代码再反向修改规格为代码辩护。

2.1 批量实现与分层验证

  • 当连续模块依赖关系明确、职责边界互不混淆，并且失败后能够按模块和依赖层准确 定位时，可以先完成多个内聚模块，再在批次末统一执行耗时较长的完整验证。
  • 批量实现不等于混合实现。每个模块仍须保持独立文件职责、唯一业务逻辑、清晰 diff 和可单独审查的输入输出契约；不得把多个语义揉进无法区分的公共函数或临时入口。
  • 每完成一个模块，至少执行与成本相称的快速静态检查、编译检查或定向测试，尽早发现 接口和依赖错误。干净 wheel、全量回归、真实 Metal、安装复验和远端版本矩阵等 昂贵验证可以在多个互不干扰的模块完成后集中执行一次。
  • 批次测试失败时，必须依据模块边界、调用链和最小复现定位根因，再 patch 对应模块； 禁止在多模块混合状态下盲目修改、增加第二套逻辑或用测试特判掩盖责任边界。
  • 在批次末的全部必需测试真实通过前，相关任务不得打勾，不得 commit、push、发布或 宣称完成。批量验证不得用于跳过测试、使用 mock、弱化断言或保留临时旁路。
  • 用户已经批准一个连续批次后，应先完成该批次全部代码、注释和测试文件，再进入集中 验证；不得因为实现过程中的单个文件完成而反复运行整套构建、完整测试或 benchmark。
  • 已经通过且未被后续改动影响的验证层不得机械重复。缺陷修复只运行能够覆盖根因和直接 依赖的定向检查；只有语义实现完成后运行一次批末完整本地验证，push 后由一次 CI 做 最终跨版本和真实设备验证。格式、注释或文档收尾不触发重复完整测试。
  • 若编译失败、真实测试失败或性能门未通过，可以在根因 patch 后重跑对应失败层；这属于 必需复验，不得扩散成与改动无关的全量重复测试，也不得用减少次数为由跳过失败复验。
  • 禁止为了形式上的“更保险”运行离谱数量的重复构建、测试、安装或 benchmark。某项已经 有明确成功证据，并且其代码、输入契约、依赖和运行环境均未受后续修改影响时，必须复用 该结果并视为仍然有效；不得再次运行。验证数量必须由实际风险和变更影响面决定。
  • 同一批准批次内能够安全组合的读取、静态检查、定向测试和验收命令，应合并为一次并行 或顺序执行并统一汇报，不得人为拆成大量小步骤增加确认次数。用户确认文件清单和批次 范围后，范围内的常规 patch 与验证无需逐文件、逐命令重复确认；只有扩大修改范围、安装 新工具、执行破坏性操作、发布外部版本或需要新的用户决策时才重新请求授权。

3. 文件修改规则

  • 新增和修改文件必须使用 patch。
  • 修改前必须说明文件清单、原因和预期效果，并等待明确确认。
  • 通常使用增量 patch；当文件超过 90% 需要变化时，可以用 patch 删除后重建，但必须事先说明理由。
  • 不得擅自删除、覆盖或回滚用户文件。
  • 不得为追求速度创建重复实现、临时旁路或第二套业务逻辑。

4. 实现质量

  • 必须遵循 SOLID 与 DRY。
  • 单一职责：API、算法、设备运行时、缓存、序列化和构建不得互相侵入。
  • 依赖倒置：训练核心依赖后端接口，不依赖具体设备对象。
  • 接口隔离：模块只暴露调用方真正需要的最小接口。
  • 开闭原则：新增目标函数或后端应通过扩展点完成，不修改无关模块。
  • 重复逻辑必须抽取到唯一实现；CPU 与 MPS 的数学语义共享同一规范和数据结构。
  • 不得加入 mock、占位成功路径、假性能数据或静默回退。
  • 不得通过修改、跳过、弱化或特判测试来让错误实现通过。
  • 不得留下无责任人、无任务编号的 TODO。若确需延期，必须先进入任务清单并写清验收条件。
  • 新增或重构后的单个代码文件默认目标不得超过 200 行；超过 300 行视为必须拆分的 硬警戒线。超过目标时，应优先按职责拆分为包目录或多个模块；确因 native binding、 格式声明或紧密耦合接口暂时超过时，必须说明原因并在同一开发阶段安排拆分，不得继续 向长文件堆功能。
  • 现有长文件新增功能时，应优先把稳定边界抽出为新模块，再接入原入口；不得为了省事 继续扩大巨型文件。拆分后的文件头、类注释、函数注释和关键实现注释必须使用英文。

5. 产品质量五原则

MPSBoost 必须以“最好的可交付产品”为目标，以下五项均为硬约束，不能为了其中一项无依据地牺牲其他项：

5.1 速度快

  • 优化端到端训练与预测，不只优化单个 kernel。
  • 性能测量必须包含输入转换、分箱、设备初始化、同步和缓存冷启动。
  • 使用统一内存、紧凑分箱、批量调度、局部直方图和 buffer 复用减少无效开销。
  • 每个性能优化必须有真实基准和正确性对照；没有证据的“优化”不得合并。
  • 小数据不适合 GPU 时必须明确说明适用边界，不伪造普遍加速结论。

5.2 容易安装

  • 支持平台必须提供预编译 wheel，默认安装命令只有 python -m pip install mpsboost。
  • 普通用户不得被要求安装重量级框架、系统包管理器、CMake、编译器或 shader 工具链。
  • wheel 必须包含匹配的 native extension 与 shader 资源，并在干净机器验证。
  • 安装失败必须给出明确平台、版本或架构原因，不允许晦涩的动态链接错误直接暴露给用户。

5.3 使用简单

  • 公共入口保持 estimator 风格，合理默认值应让常见任务无需底层配置即可运行。
  • 用户只看到 device="mps"，不需要理解内部 MPS primitive 与 Metal kernel 的分工。
  • 未知或冲突参数早失败；禁止静默忽略。
  • 日志默认简洁，可诊断模式提供设备、缓存和阶段耗时，但不得泄露敏感信息。

5.4 体积较小

  • 不引入仅为少量功能服务的重量级运行时依赖。
  • native extension、shader 和 Python 层只打包运行必需内容；测试、benchmark、规格、缓存和构建产物不得进入 wheel。
  • 发布前必须记录 wheel 解压前后体积并审计最大文件。
  • 重复资源必须消除；调试符号与发布二进制的处理必须在构建规格中明确。

5.5 权限最少

  • 训练和预测不得要求管理员权限、系统扩展、后台服务、网络访问或额外 entitlement。
  • 默认只读取用户显式提供的数据，只在用户缓存目录写入可重建缓存。
  • 导入包、查询版本和查询缓存路径不得创建文件或访问网络。
  • 不收集遥测，不上传数据、模型、设备标识或性能信息。
  • 发布和 CI 凭据采用最小权限，绝不进入源码、日志、wheel 或缓存。

5.6 验收要求

任何公开版本必须同时给出并通过：端到端性能报告、干净环境安装测试、最小使用示例、wheel 体积审计和权限/网络行为检查。任一项未通过，不得将发布任务标记完成。

6. 注释与落盘语言规范

v0/v1 历史代码和规格中的中文说明可以保留。进入 v2 及以后，新写或大幅修改的代码注释、 文件头说明、公共函数文档、关键实现说明、README、release notes、CI 文案和公开错误文档 必须使用英文。Agent 与用户对话继续使用中文。

specs 不强制就地翻译为英文。项目后续会使用 MkDocs 建立中英文站点，中文规格可以作为 源规格或历史规格保留；英文版本应通过独立文件、站点生成流程或明确的双语文档结构维护， 不得为了满足语言规则把现有 specs 粗暴整体翻译后覆盖。

每个代码文件必须包含文件头说明，至少写明：模块意图、职责边界、关键依赖和禁止事项。

每个公共类、公共函数和复杂内部函数必须有文档注释，说明：

  • 目的和使用场景；
  • 参数、返回值与异常；
  • 所有权、线程安全或副作用；
  • 关键不变量和数值语义。

复杂控制流、长表达式、并行归约、缓存失效、内存同步和不直观性能优化必须有关键点注释， 解释“为什么”，不能只机械复述代码。简单赋值无需机械注释。

7. 测试规则

  • 测试必须验证真实实现，不得只验证 mock。
  • CPU 参考与设备后端必须使用同一输入和相同模型语义。
  • 浮点容差必须有依据，不得为通过失败测试随意放宽。
  • 性能测试必须包含预处理、同步和端到端时间。
  • 修复缺陷必须先保留可复现测试，再修复实现。
  • 测试未运行或因环境阻塞时，必须如实说明，不得标记完成。

8. 工具与环境阻塞规则

  • 开工前必须检查当前模块所需的编译器、SDK、构建系统、依赖、真实设备、权限和测试工具。
  • 缺少任何必要工具时，必须立即停止相关实现或验证，并用中文向用户说明：缺少什么、为什么需要、建议安装方式、安装后如何验证。
  • 工具安装由用户执行或明确授权后执行；Agent 不得擅自安装系统工具、依赖或修改全局环境。
  • 禁止为了绕过缺失工具而降低规格、删除功能、改用 mock、伪造设备结果、跳过测试或提交未经验证的实现。
  • 禁止用临时脚本、硬编码输出、假后端或第二套低质量逻辑替代规格要求的正式方案。
  • 环境阻塞期间，对应任务必须保持 [ ]；只有真实工具链恢复并完成全部验收后才能打勾。
  • 若存在多个正式工具选项，应说明体积、稳定性、维护成本和许可证影响，由用户确认选择，不能默认选最快但质量较差的方案。
  • 工具命令失败时必须保留原始错误摘要，先判断根因；不得通过关闭校验、忽略错误码或扩大权限掩盖问题。

9. Git 与 commit

  • 只有用户明确授权时才能执行 Git 操作。
  • v0/v1 历史整理 commit 可以使用中文；v2 及以后 commit 标题和正文必须使用英文。
  • 一个 commit 只包含一个内聚模块。
  • 标题使用祈使式，清楚描述结果，不写“更新代码”等空泛内容。
  • 正文说明原因、关键设计和验证结果；总计不超过 10 行。
  • 提交前检查忽略文件、敏感信息、构建产物和 diff。
  • specs/ 与 specs/AGENTS.md 是项目规则资产，可以在用户明确要求时提交；凭据、缓存、本地 构建产物和临时验证环境不得提交。

推荐格式：

Add compact binned matrix validation

Validate uint8/uint16 bin ownership and feature bounds.
Keep CPU and MPS paths on the same matrix contract.
Validation: targeted unit tests passed.

10. 发布规则

  • 发布 artifact 必须来自已经测试的同一份构建产物，不得上传时重新构建。
  • 版本一经公开不得覆盖；修复使用新版本。
  • 正式发布前必须完成任务清单中的发布门。
  • 对外 README、包元数据和发布说明使用英文；v2 及以后代码注释和 commit 也使用英文。
  • 不得夸大功能或性能，不得把未实现能力写成可用。
  • 认证已经可用时不得重复登录；凭据不得输出或写入文件。

10.1 大模块交付与里程碑发布

  • 每完成一个任务清单定义的大模块，都必须形成一个内聚 commit、push GitHub，并由 CI 保存可安装 wheel artifact。v2 及以后 commit 使用英文。
  • 内部模块不得仅为“留痕”频繁上传 PyPI；PyPI 只发布用户能够实际感知和使用的完整里程碑。
  • S5 首个真实 estimator 通过验收后发布 0.2.0a0；S6 性能目标通过后发布 0.2.0b0；S7 稳定性通过后发布 0.2.0rc0；完整发布门通过后发布 0.2.0。
  • PyPI 版本遵循 PEP 440，已发布版本永不覆盖或复用。需要修复时递增对应预发布编号或补丁版本。
  • GitHub commit、CI artifact 与 PyPI artifact 必须可追溯到同一源码状态；上传时不得重新构建。
  • 上传前必须报告确切版本、文件名、大小、SHA-256 和测试结果；上传后必须从正式 PyPI 在全新环境安装并运行真实验收测试。