| 文件 | 最后提交记录 | 最后更新时间 |
|---|---|---|
docs: 采纳 rpm/deb 安装指南第三轮检视意见修复 Co-authored-by: sinat_31531339<yuanyue23@huawei.com> # message auto-generated for no-merge-commit merge: !582 merge docs/rpm-deb-guide-review-round3 into master docs: 采纳 rpm/deb 安装指南第三轮检视意见修复 Created-by: sinat_31531339 Commit-by: sinat_31531339 Merged-by: cann-robot Description: ## 描述 本 PR 承接已合入的 PR #581（docs: 补充 rpm/deb 包安装指南并更新 README），落实其评审过程中第三轮检视意见（3 条，均采纳），仅修改 docs/zh/package_install.md 与 docs/en/package_install.md 两文件（+30/-24，中英文同步）。逐条对应： 1. **场景一条件与 dpkg/rpm 底层命令能力对齐**：dpkg -i / rpm -ivh 仅校验本机包数据库、不做软件源解析，场景一条件由"CANN 依赖由 rpm/deb 软件源满足"改为"CANN 依赖已通过 deb/rpm 包安装并登记在本机包管理器数据库"（概述表与安装/重装命令块注释共 3 处/语言）；并新增能力说明——若需由软件源解析并安装依赖，可改用 apt install ./<deb>（deb 系）或 dnf|yum|zypper install ./<rpm>（按发行版选择，未实测已在文中标注）。 2. **运行方式区分安装验证与完整功能**："绝对路径调用无需环境变量"收窄为仅适用于安装验证（--help、模块导入等浅验证，已实测）；采集、解析、profiling 等完整功能执行前需先加载本机 CANN 环境变量（source <CANN安装路径>/set_env.sh，与 .run 包使用方式一致）。 3. **卸载行为条件化**：原"卸载完全清理、无残留"的无条件表述收窄为——卸载清理本包自身文件与符号链接，共享路径仅在无其它 CANN 包占用时删除空目录（依据 var/ascend_package_db.info 注册信息与 prerm 脚本 rmdir 仅删空目录的语义）；安装根目录 /usr/local/Ascend/cann-<cann_version> 仅在本工具单独安装时一并移除（该场景实测零残留），共用前缀时保留且不影响其它 CANN 包。 ## 关联的Issue 无 ## 测试 文档改动，验证依据内部证据记录（.omo/evidence/task-12-review-round3-rpm-deb-package-docs.md）摘要： - 场景一旧表述"软件源满足"在中英文两文件 0 命中（grep 实跑）； - set_env.sh 在中英文两文件均命中（各 2 处，运行方式区分表述双语同位）； - 条件化卸载表述（"未被其它 CANN 包"/"not shared with other CANN packages"）双语同位（zh L137 / en L137）； - 中英文命令块一致性检查通过（awk 提取代码块并剔除注释行后 diff 为空，实际命令逐条一致）； - pre-commit 钩子全绿（trailing-whitespace / end-of-file / typos / codespell / OAT 合规扫描均通过）； - 卸载/运行方式表述依据 build/prerm 脚本实读（cleanup_parent_dirs 逐级 rmdir 仅删空目录、ascend_package_db.info 组件注册判定）与既有实装证据（单独安装场景卸载零残留、dpkg -i 依赖不满足时无源拉取）。 ## 文档更新 - docs/zh/package_install.md / docs/en/package_install.md：场景一表述修正 + apt/dnf 源解析能力说明、运行方式区分（安装验证 vs 完整功能）、卸载行为条件化（中英文成对同步，+30/-24）。 ## 类型标签 - [ ] 🐛 Bug 修复 - [ ] ✨ 新特性 - [ ] ⚡ 性能优化 - [ ] ♻️ 重构 - [ ] 🧪 测试 - [ ] 📦 构建/CI - [ ] 🔧 配置变更 - [x] 📝 文档更新 - [ ] ⬆️ 依赖升级 - [ ] 🔒 安全修复 - [ ] 🧹 代码清理 - [ ] ❓ 其他，请描述： ## 核对清单 - [x] 我的代码遵循了项目的代码风格 - [x] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [x] 我在标题中使用了合适的类型标签（如：feat:, fix:） - [x] 我已经详细阅读了贡献指南（CONTRIBUTING.md） See merge request: cann/oam-tools!582 | 3 天前 | |
docs: 优化 README 结构，新增组件功能介绍与项目架构 Co-authored-by: sinat_31531339<yuanyue23@huawei.com> # message auto-generated for no-merge-commit merge: !393 merge docs/optimize-readme-structure into master docs: 优化 README 结构，新增组件功能介绍与项目架构 Created-by: sinat_31531339 Commit-by: sinat_31531339 Merged-by: cann-robot Description: ## 描述 本 PR 优化 README 文档结构，参考业界通用做法（PyTorch、Prometheus、Ansible 等顶级开源项目），在环境搭建之前先介绍项目信息，使用户能够快速了解项目定位、核心功能与架构。 ## 变更内容 ### 结构优化 - **删除 logo 图片，用文字标题替代**：移除 docs/figures/oam-tools.svg 引用，用 # OAM-Tools + 副标题替代 - **新增「项目简介」章节**：定位 + 核心价值 + 适用场景 - **新增「核心特性」章节**：四大组件功能表格（asys/msaicerr/msprof/hccl_test），一目了然 - **新增「项目架构」章节**：架构说明 + 增强目录结构（标注各模块职责） - **新增「快速开始」章节**：3 步极简示例（环境准备→编译→安装） - **合并「安装」与「验证」**为「安装与验证」章节，含独立小节 - **「相关文档」增强**为组件文档表格 + 其他文档链接 ### 保留的修复 - 保留 pre-commit 章节的 oat-py 修复（#135）：OAT 检查已改用 Python 版 oat-py，无需 Java/Maven ### 中英文同步 - README.md（中文）与 README_en.md（英文）结构完全同步，12 个章节一一对应 ## 优化前后结构对比 | 序号 | 优化前 | 优化后 | |------|--------|--------| | 1 | 标题 + Logo 图片 | 标题 + 文字 + 徽章 | | 2 | 概述（一句话） | 📖 项目简介（定位+价值+场景） | | 3 | 支持的硬件环境 | ✨ 核心特性（组件功能表格） | | 4 | 环境准备 | 🏗️ 项目架构（架构说明+目录结构） | | 5 | 目录结构 | 🚀 快速开始（3步示例） | | 6 | 源码编译 | 🧩 支持的硬件环境 | | 7 | 安装 | 🔧 源码编译 | | 8 | 验证 | 📦 安装与验证 | | 9 | 功能运行示例 | ▶️ 功能运行示例 | | 10 | Pre-commit | 🅿️ Pre-commit | | 11 | 相关文档 | 📚 相关文档（表格） | | 12 | 相关信息 | ℹ️ 相关信息 | ## 变更类型 请选择本次引入的变更类型（勾选对应项）： - [x] 📝 文档内容更新 ## 如何测试 1. 检查 logo 图片引用已删除： bash grep -c "oam-tools.svg" README.md README_en.md # 应为 0 2. 检查四大组件功能介绍存在： bash grep -E 'asys|msaicerr|msprof|hccl_test' README.md | head -5 3. 检查章节结构完整（应有 12 个二级标题）： bash grep -c "^## " README.md # 应为 12 ## 核对清单 - [x] 我的代码遵循了项目的代码风格 - [x] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [x] 我在标题中使用了合适的类型标签（docs:） - [x] 我已经详细阅读了贡献指南（CONTRIBUTING.md） ## 其他信息 参考业界最佳实践研究（PyTorch、Prometheus、Ansible、gRPC、Git 等顶级开源项目 README 结构），未添加"最新消息"章节——顶级项目均保持 README 为稳定技术参考，频繁变动的新闻放在 Wiki/Release Notes 中。 See merge request: cann/oam-tools!393 | 2 个月前 | |
docs: 采纳 rpm/deb 安装指南第三轮检视意见修复 Co-authored-by: sinat_31531339<yuanyue23@huawei.com> # message auto-generated for no-merge-commit merge: !582 merge docs/rpm-deb-guide-review-round3 into master docs: 采纳 rpm/deb 安装指南第三轮检视意见修复 Created-by: sinat_31531339 Commit-by: sinat_31531339 Merged-by: cann-robot Description: ## 描述 本 PR 承接已合入的 PR #581（docs: 补充 rpm/deb 包安装指南并更新 README），落实其评审过程中第三轮检视意见（3 条，均采纳），仅修改 docs/zh/package_install.md 与 docs/en/package_install.md 两文件（+30/-24，中英文同步）。逐条对应： 1. **场景一条件与 dpkg/rpm 底层命令能力对齐**：dpkg -i / rpm -ivh 仅校验本机包数据库、不做软件源解析，场景一条件由"CANN 依赖由 rpm/deb 软件源满足"改为"CANN 依赖已通过 deb/rpm 包安装并登记在本机包管理器数据库"（概述表与安装/重装命令块注释共 3 处/语言）；并新增能力说明——若需由软件源解析并安装依赖，可改用 apt install ./<deb>（deb 系）或 dnf|yum|zypper install ./<rpm>（按发行版选择，未实测已在文中标注）。 2. **运行方式区分安装验证与完整功能**："绝对路径调用无需环境变量"收窄为仅适用于安装验证（--help、模块导入等浅验证，已实测）；采集、解析、profiling 等完整功能执行前需先加载本机 CANN 环境变量（source <CANN安装路径>/set_env.sh，与 .run 包使用方式一致）。 3. **卸载行为条件化**：原"卸载完全清理、无残留"的无条件表述收窄为——卸载清理本包自身文件与符号链接，共享路径仅在无其它 CANN 包占用时删除空目录（依据 var/ascend_package_db.info 注册信息与 prerm 脚本 rmdir 仅删空目录的语义）；安装根目录 /usr/local/Ascend/cann-<cann_version> 仅在本工具单独安装时一并移除（该场景实测零残留），共用前缀时保留且不影响其它 CANN 包。 ## 关联的Issue 无 ## 测试 文档改动，验证依据内部证据记录（.omo/evidence/task-12-review-round3-rpm-deb-package-docs.md）摘要： - 场景一旧表述"软件源满足"在中英文两文件 0 命中（grep 实跑）； - set_env.sh 在中英文两文件均命中（各 2 处，运行方式区分表述双语同位）； - 条件化卸载表述（"未被其它 CANN 包"/"not shared with other CANN packages"）双语同位（zh L137 / en L137）； - 中英文命令块一致性检查通过（awk 提取代码块并剔除注释行后 diff 为空，实际命令逐条一致）； - pre-commit 钩子全绿（trailing-whitespace / end-of-file / typos / codespell / OAT 合规扫描均通过）； - 卸载/运行方式表述依据 build/prerm 脚本实读（cleanup_parent_dirs 逐级 rmdir 仅删空目录、ascend_package_db.info 组件注册判定）与既有实装证据（单独安装场景卸载零残留、dpkg -i 依赖不满足时无源拉取）。 ## 文档更新 - docs/zh/package_install.md / docs/en/package_install.md：场景一表述修正 + apt/dnf 源解析能力说明、运行方式区分（安装验证 vs 完整功能）、卸载行为条件化（中英文成对同步，+30/-24）。 ## 类型标签 - [ ] 🐛 Bug 修复 - [ ] ✨ 新特性 - [ ] ⚡ 性能优化 - [ ] ♻️ 重构 - [ ] 🧪 测试 - [ ] 📦 构建/CI - [ ] 🔧 配置变更 - [x] 📝 文档更新 - [ ] ⬆️ 依赖升级 - [ ] 🔒 安全修复 - [ ] 🧹 代码清理 - [ ] ❓ 其他，请描述： ## 核对清单 - [x] 我的代码遵循了项目的代码风格 - [x] 我已对代码进行了自测 - [x] 我已更新了相关的文档 - [x] 我在标题中使用了合适的类型标签（如：feat:, fix:） - [x] 我已经详细阅读了贡献指南（CONTRIBUTING.md） See merge request: cann/oam-tools!582 | 3 天前 |