Backgroud（背景信息）

新软件架构重构已完成、架构图已评审确定，参考 architecture-brief.md §3 软件分层逻辑。目前 HCCL 仓 src/ops 算子层软件目录与软件架构图存在差异：

• op_common 下 executor、template 平铺，未收拢到统一的"算法"概念下
• topo 目录内混装两类内容：topo match 实现（topo_match_*）与拓扑信息（topo/topo_host），且整体挂在 op_common 通用组件层下
• scatter 算子目录用 algo，与其他算子的 executor/template 命名不一致
• 各算子目录二级结构与 op_common 未严格对齐

现状（master）：

src/ops/op_common   executor / inc / selector / template / topo + op_common.cc 等 Host 侧主流实现
src/ops/all_reduce  executor / op_graph / selector / template + all_reduce_op.cc
src/ops/scatter     algo / executor / selector / template + scatter_op.cc

不做的代价是架构与代码长期背离，后续算子开发无统一目录范式。

Origin（信息来源）

社区自规划（系统方案工程师），软件需求与方案设计已评审定稿。

Benefit / Necessity（价值/作用）

• 统一软件架构约束，使代码目录与已评审的软件架构图保持一致
• 为后续通信算子开发提供统一的目录范式，形成"选择-算法-模板"三段式职责内聚
• topo 拆分归位：topo match 作为拓扑匹配算法实现归入 algorithm/topo_match（与 executor/template 平级），与代码引用事实吻合；拓扑信息独立保留在 topo_info
• 消除 scatter 等算子的命名偏差，降低开发者认知成本

Design（设计方案）

一、目录结构

1. op_common 引入 algorithm 子目录，内部包含 executor、template；原 op_common/executor、op_common/template 整体迁入
2. op_common/selector 保留；op_common.cc 等 Host 侧主流实现保留在 op_common 根目录；op_common/inc 本期不动
3. 各通信算子目录作为 op_common 的派生实现，一、二级目录结构与 op_common 严格一致
4. 已有的 algo 目录更名为 algorithm，内部分为 executor 和 template
5. 每个算子目录提供统一命名的主入口文件（如 allreduce.cc）

二、topo 拆分调整

1. 原 topo 目录中的 topo match 内容（topo_match_*.cc/h）迁入 op_common/algorithm/topo_match/（与 executor、template 平级）
2. 原 topo 目录重命名为 topo_info，保留 topo.cc/topo.h、topo_host.cc/topo_host.h 等拓扑信息文件
3. 确认后更新相关头文件引用与依赖

三、配套工作

• 更新构建配置（CMake / BUILD 文件等）
• 全仓适配新的目录与头文件路径
• 相关单元测试、集成测试的调整与验证
• topo 相关变更的文档刷新

目标目录结构（src/ops 部分）：

src/ops
├── op_common                           # 算子通用组件（基座）
│   ├── algorithm                       # 【新增】算法子目录
│   │   ├── executor                    #   算法执行器（原 op_common/executor 整体迁入）
│   │   ├── topo_match                  #   【迁入】原 op_common/topo 中 topo match 内容（topo_match_*）
│   │   └── template                    #   算法模板（原 op_common/template 整体迁入）
│   ├── selector                        # 算法选择器（保留）
│   ├── topo_info                       # 【重命名】原 op_common/topo，保留 topo/topo_host 等拓扑信息文件
│   └── op_common.cc 等 Host 侧主流实现  # 保留在 op_common 根目录
└── all_reduce / all_gather / …         # 各通信算子（op_common 的派生实现）
    └── 一、二级目录结构与 op_common 严格一致

本期范围外（不在本 issue 交付）：

• interface_graph_mode 相关内容（拆分、重命名及 pkg_inc 包间头目录新增）——本期不调整，待后续专门调整
• op_graph 子目录调整（暂缓）
• selector/algorithm 插件式扩展挂载点
• 目录权限管控（目录结构确定后单独再做）

验收参考：

• 原 op_common/executor、op_common/template 内容整体迁入 op_common/algorithm/ 且无残留
• 原 op_common/topo/ 中 topo match 内容（topo_match_*.cc/h）整体迁入 op_common/algorithm/topo_match/ 且无残留；原目录重命名为 op_common/topo_info/ 并保留 topo/topo_host 等拓扑信息文件；全仓无 op_common/topo 路径残留引用
• scatter 等算子 algo 更名为 algorithm（内含 executor/template）；抽查各算子二级目录集合与 op_common 一致
• 每个算子目录提供统一命名的主入口文件
• CMake/BUILD 全部更新，全仓 include 路径适配无编译错误，bash build.sh --ut、bash build.sh --st 通过
• topo 相关架构文档同步刷新

约束：结构重构型变更，代码逻辑零改动；不涉及 include/ 对外公共头，不涉及对 hcomm 依赖通道（common/hcomm_dlsym）；依赖方向不变——topo match 迁入 algorithm（与 executor/template 平级）后其消费方（各算子 executor、selector 的 cost_model 等）引用关系与现状一致，无新增反向依赖。

工作量估计：0.1k。