CANN Runtime API 模块拆分：四 PR 分批上库流程实战指南

CANN Runtime API 模块拆分四 PR 分批上库流程实战指南【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtimeCANN Runtime 仓库在按官方对外接口文档将巨型主Api/ApiImpl/decorator 链路拆分为独立ApiXxx/ApiImplXxxAPI 大类时采用独立文档 PR - 框架 PR - 路由 PR - 清理 PR的四 PR 分批上库模式保证每个阶段可独立编译、验证和回退。本文完整讲解这套上库流程的每条前置原则、分支与提交规范、阶段检查命令、PR 描述模板、CI 门禁口径以及三阶段代码 PR 各自的审查重点并结合仓库中 Event 拆分的真实批次event-batches.md说明落地方式。读完本文你将能够按仓库规范为 Runtime API 模块拆分规划、提交并验收一整套分批上库 PR。一、这套流程解决什么问题Runtime 长期演进后大量对外接口的 C API 入口集中在 src/runtime/api/api_c_*.cc 系列文件中实际实现则堆积在单一主Api、ApiImpl及其 decoratorapi_decorator.cc链路上。拆分工作的技术方法见 method.md其核心链路是官方 acl/aclrt 接口 - ACL 实现与 rt/rts 调用 - src/runtime/api/api_c*.cc C 入口 - 当前 Api 大类及成员函数 - ApiImpl/平台实现/对象实现 - CMake、stub、UT把一个官方模块拆成新ApiXxx大类如果一次性把所有改动压进一个 PR会产生巨型 diff既有新框架代码、C API 路由切换又有旧链路删除任何一步出问题都难以定位和回退。因此仓库规定业务上永远是框架 - 路由 - 清理三个串行阶段首次交付则固定为 4 个 PR文档 PR 三个代码阶段 PR每一个 PR 只包含一个阶段、一个清晰提交。以 Event 拆分为例见 event-batches.md首批 IPC Event 的落地就是框架 PR新增 api_event.hpp、api_impl_event.cc 等- 框架稳定化 - 路由 PRaclrtIpcGetEventHandle/aclrtIpcOpenEventHandle切到ApiEvent- 清理 PR删除主Api旧链路。三个代码阶段严格串行后一个 PR 必须基于前一个实际合入后的最新主线。二、前置原则一次只做一件事上库流程的第一步是确认以下 6 条前置原则它们决定了所有后续操作的口径首次交付固定为 4 个 PR独立文档 PR - 第一批框架 PR - 第一批路由 PR - 第一批清理 PR。三个代码业务阶段串行合入框架 - 路由 - 清理不允许并行推进或颠倒顺序。文档 PR 纯净只包含分析和方案交付件不混入源代码、CMake 或 UT 改动。基于实际主线每个阶段基于前一阶段实际合入后的最新origin/master不要长期堆叠在未合入提交上。单 PR 单阶段每个 PR 只包含一个阶段和一个清晰提交检视清理确有必要时使用窄 PR不混入下一阶段。权限边界推送、创建/更新 PR、发布评论或审批都需要用户明确授权Agent 不得擅自执行线上写操作。此外submission.md特别强调要保留用户工作区中的无关改动大改优先使用隔离 worktree避免reset/checkout等可能覆盖用户工作的操作。三、分支与提交建议每个阶段使用独立分支命名规则为docs/api-module-split-plan refactor/api-module-framework refactor/api-module-route refactor/api-module-cleanup建议的提交标题如下docs: 新增 Module API 拆分分析与计划 refactor: 新增 ApiModule 框架 refactor: 切换 Module API 调用链 refactor: 清理主 Api Module 旧链路若阶段一合入后检视提出确定的依赖收敛意见需要以窄补丁修复时可使用refactor: 清理 ApiModule 冗余依赖Event 拆分中实际采用的分支与提交与此一致event-batches.md例如框架稳定化 PR 只收敛头文件和具体实现依赖不改变业务路由因而提交标题明确为清理冗余依赖不属于新的业务阶段。四、准备阶段隔离 worktree 与精准提取改动创建分支前先确认工作区和远程状态git status --short git remote -v git fetch origin master为避免污染用户工作区建议在隔离目录中基于主线创建分支git worktree add isolated-path -b refactor/api-module-framework origin/mastersubmission.md明确规定不要使用会覆盖用户改动的 reset/checkout 操作。若此前有聚合分支例如包含完整三阶段验证的临时分支需要按文件和 hunk 精准提取本阶段内容而不是整体复制git diff --stat origin/master...aggregate-branch git diff origin/master...aggregate-branch -- path git add -p path git diff --cached --stat git diff --cached提交前必须确认暂存内容没有混入下一阶段接口也没有包含用户无关文件。这一步是单 PR 单阶段原则在 git 操作层面的落地git add -p允许逐 hunk 选择是避免跨阶段污染的主要手段。五、阶段提交检查每个阶段提交后至少执行以下三项检查git diff --check origin/master...HEAD git diff --stat origin/master...HEAD git log --oneline origin/master..HEADgit diff --check检查空白错误等低级问题git diff --stat核对变更文件清单是否落在本阶段范围内git log --oneline确认提交历史只有一个本阶段提交。随后按 risk-and-validation.md 执行对应验证。该文档给出了框架、路由、清理三个阶段的最小验证矩阵例如框架阶段要证明现有 C API 仍走旧路径路由阶段要证明新路径与旧路径行为等价且旧主Api方法尚未删除清理阶段要扫描全部旧符号残留并完成正式构建与多平台 UT。submission.md特别强调验证失败不能只写环境问题。要定位失败发生在改动前还是改动后是否进入目标源文件属于功能回归还是证据缺口。每个阶段的验证证据命令、目标、通过/失败数、失败原因都要真实记录不得以计划通过之类的表述代替实际结果。六、推送与创建 PR推送与创建 PR 只能在用户明确要求后进行完整流程为读取仓库gitcode-prSkill涉及 GitCode PR 时。读取当前.gitcode/PULL_REQUEST_TEMPLATE.zh-CN.md不要使用旧硬编码模板。推送当前阶段分支到用户指定 fork。创建目标为cann/runtime:master或用户明确指定分支的 PR。若代码发生变更后刷新已有 PR同步更新 PR 描述中的变更范围、风险、实际验证结果和剩余工作不得保留与最新代码不一致的旧描述。回读线上 PR 的 title、head/base、提交数、描述和最新 commit确认与本地一致。关键的时序约束是前一阶段 squash/no-merge 合入后下一阶段要基于实际主线提交刷新并重新执行完整阶段验证。submission.md提醒不要假设 PR head SHA 等于最终主线 SHA——合入过程可能经历 squash 或 rebase只有合入后的真实主线提交才可作为下一阶段基线。七、CI 门禁每个 PR 的可合入前提每个 PR 创建或刷新后都必须检查线上 CI文档 PR 与代码 PR 的门禁不同文档 PR适用的文档、格式、OAT 和仓库必选任务必须通过。框架、路由、清理 PR仓库必选任务和 CI 编译任务必须通过并结合阶段风险执行对应 UT。CI 失败时先定位并修复推送修复后同步更新 PR 描述再等待新一轮 CI。CI 未触发、仍在运行、编译目标被跳过或产物不可读时记录为证据缺口不得写成CI 编译通过。只有线上 CI 显示成功且目标编译任务确实执行才能将代码 PR 标记为可合入。三个代码 PR 严格串行前一代码 PR 实际合入且 CI 编译通过后下一代码 PR 才基于最新主线刷新、验证和提交。这与 risk-and-validation.md 的验收结论分类一致——必须明确区分已本地验证已由线上流水线验证因环境或权限未验证等状态CI 产物不可读时写证据缺口而非全部通过。八、PR 描述模板与填写要点PR 描述按仓库模板填充描述部分至少包含以下内容## 描述 本 PR 是 模块 API 大类拆分的 框架/路由/清理 阶段。 本批接口 - aclrtXxx - rtXxx - ApiXxx::Xxx 具体变更 - ... 行为等价说明 - C API 签名、参数校验、返回码、ErrMsg、profiling、Context/线程环境和产品支持保持不变。 本 PR 不包含 - 不切换/不删除下一阶段链路。 - 不整改 剩余接口原因是 跨模块依赖/后续批次。 剩余工作 - ...填写要点submission.md与 method.md 的一致要求本批接口逐条给出 C API - Runtime 入口 - 新ApiXxx::Xxx的映射这正是 method.md 端到端追踪的成果形态行为等价说明覆盖行为等价基线的关键维度C API 签名、参数校验顺序、返回码转换、ErrMsg、profiling begin/end、Context/线程环境以及产品支持矩阵标准、David/V201、tiny/arch5162、910B 等本 PR 不包含明确划清本阶段边界防止检视者误以为路由阶段会顺带清理旧链路剩余工作列出后续批次和暂缓原因。如何测试一节必须写实际执行结果包括命令、目标、通过数和未完成项不要预填计划结果。Checklist 只勾选真正完成的项目。这一口径贯穿整套流程任何计划验证预计通过性质的表述都不被接受。九、三阶段代码 PR 的审查重点三个代码阶段虽然共用同一套 PR 规范但各自的描述重点和验收证据不同。框架 PR框架阶段为第一批接口新增或扩展ApiXxx/ApiImplXxx、Runtime 生命周期、构建接入和直接 UT不切换任何 C API 路由。PR 描述必须强调现有 C API 未切路由对外行为没有变化列出 Runtime 生命周期改动、各产品 CMake/stub 源文件清单和直接 UT说明新增成员布局Runtime 新成员位置、虚函数变化与不支持产品语义。以 Event 拆分批次一为例event-batches.md框架阶段新增 api_event.hpp 与 api_impl_event.cc标准产品编译正式实现tiny/arch5162 继续编译 api_impl_event_stub.cc 中的 not-support 桩创建器api_impl_creator.cc按产品返回正确的动态类型。框架阶段合入后如检视提出高置信度的依赖收敛意见可用窄范围稳定化 PR 处理如 Event 的 PR 4219它仍属于框架稳定化不改变三阶段业务主线。路由 PR路由阶段只切换本批选中 C API 的入口到ApiXxx保留主Api旧方法。PR 描述必须列出切换的确切 C API 清单例如aclrtIpcGetEventHandle、aclrtIpcOpenEventHandle声明旧主Api方法仍保留、未删除给出路由证明通过隔离主Api实例证明 C API 确实进入ApiEvent提供新旧行为对比成功、空入参、非法 handle、Context/Device 异常、底层失败、feature-not-support、profiling、线程环境和环境/profiling 验证结果。路由阶段的风险点在于表面上切换、实际仍走残留路径因此 risk-and-validation.md 要求路由 UT 能隔离旧实例并证明参数、结果和输出写回的一致性。清理 PR清理阶段在前两阶段稳定后删除主Api、ApiImpl、decorator、平台 stub 和旧 UT 中的本批残留。PR 描述必须列出删除的 ApiImpl/decorator/platform/UT 范围声明只清理本批接口不扩展范围附残留扫描对主Api、ApiImpl、decorator、平台 override/stub、mock 和旧 UT 按确切符号执行rg扫描、正式构建和多平台 UT 结果。需要特别注意的是删除虚函数和 include 后各产品标准、910B、tiny、arch5162、cmodel 等必须均可编译和链接新虚实现文件一旦漏进某平台源列表就会出现 vtable undefined 符号。因此 event-batches.md 强调新增虚函数定义必须进入标准、David/V201、cmodel、tiny、arch5162、910B 及对应 UT 源列表只验证 common 目标不能证明其他平台无链接缺口。十、合入后收尾每个 PR 合入后都要执行收尾动作submission.md给出的清单如下记录实际主线提交和合入时间。更新后续阶段基线与 PR 描述。重新核对官方模块接口清单和剩余接口。将已完成项标为本批完成保留后续/暂缓原因。最后一阶段合入后确认在线 PR 描述、设计文档和主线代码一致。其中最后一条是关键的一致性收口只有在线 PR 描述、设计文档与主线代码三方一致才算一个模块批次的完整闭环。最后submission.md给出了一个重要的结论口径不得因为三个阶段完成就自动宣称整个官方模块已完成。只有接口全集均有明确归属和处理结论本批完成、后续整改、暂缓整改、无需整改时才能给出模块级完成结论。Event 拆分的状态汇报方式event-batches.md就是示例已合入批次一 IPC Event 进行中批次二查询、时间和标识 下一优先批次批次三 GetAvailEventNum、EventWorkModeSet/GetAPI 模块边界独立 依赖解耦后决策批次四 Event 同步Soma 成功后副作用 有条件推进批次五生命周期 暂缓批次六 Record/Reset 明确保留StreamWaitEvent、SetOpWaitTimeOut十一、配套资料与仓库依据拆分方法总纲method.md端到端映射、批次划分、行为等价基线、三阶段边界上库与验证标准risk-and-validation.md风险矩阵、分阶段最小验证、命令选择、验收结论口径Event 真实批次与后续计划event-batches.md22 个 ACL 接口、六个业务批次、三阶段 PR 编号模块拆分 Skill 主文档SKILL.md首次输出四 PR、执行流程、7 项文档交付件代码结构参考src/runtime/api/api_c_event.ccC 入口、api_event.hpp 与 impl/api_impl_event.cc、impl/api_impl_event_common.cc、impl/api_impl_event_stub.cc实现层次、impl/api_decorator.ccdecorator 链、impl/api_impl_creator.cc创建器官方接口文档对照docs/zh/api_ref/07_event_management.md用于交叉核对接口清单UT 与构建入口tests/ut/runtime、tests/build_ut.sh--utruntime --targetruntime_utest_api等目标【免费下载链接】runtime本项目提供CANN运行时组件和维测功能组件。项目地址: https://gitcode.com/cann/runtime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考