#126-204 发布包能力一致性设计文档

目录

• 1. 评审目标
• 2. 问题边界
• 3. PR 设计
• 4. 方案取舍
• 5. 验收标准
• 6. 当前状态与限制
• 7. 目标、非目标与约束
• 8. 需求与评审意见追踪
• 9. 总体架构与职责边界
• 10. 代表性主流程
• 11. 关键类或组件关系
• 12. 兼容、迁移与版本策略

1. 评审目标

确认配套版本配置应作为显式运行时包数据，并由回归测试保护
ascend-download --show-releases 的“展示后直接退出”语义。

2. 问题边界

中文资料已经指导在线安装用户执行：

ascend-download --show-releases

但 PyPI 最新公开版本 7.3.0 不识别该参数，wheel 也没有
ascend_deployer/downloader/release_config.json。代码 PR 可以保护后续构建，
但不能追溯修改已发布的 7.3.0。

3. PR 设计

!2220 修改两个文件：

1. setup.py 显式声明：

   package_data={
       'ascend_deployer': ['downloader/release_config.json'],
   }
   

2. test/st/test_release_package.py：

   • 调用 CLI 的 --show-releases 路径；
   • 断言 show_releases() 被调用一次；
   • 断言不会继续调用下载逻辑；
   • 通过 AST 读取 setup() 的 package_data，避免依赖源码排版。

4. 方案取舍

A/B 构建显示，当前 dev 即使没有 !2220，也可能通过
MANIFEST.in + include_package_data=True 把配置文件带入 wheel。

因此 !2220 的准确价值是：

• 把运行时数据依赖从隐式打包行为变为显式契约；
• 防止未来 MANIFEST 或 setuptools 行为变化造成漏包；
• 保护 CLI 展示完成后不进入下载流程。

它不是当前 dev wheel 携带配置文件的唯一必要条件，也不能代替正式发版。

5. 验收标准

• 新增测试在项目支持的 Python 版本上通过；
• wheel 包含 release_config.json；
• 全新环境安装后 ascend-download --show-releases 返回 0；
• CI、CLA 和安全门禁通过；
• 新版本发布后对真实 PyPI 安装路径再次回归。

6. 当前状态与限制

2026-07-29 API 回读确认 !2220 open、mergeable，当前 head 的 CLA、文档和主 CI
通过；#204 仍 open。PyPI 官方 API 同日确认最新版仍为 7.3.0，所以用户侧发布
闭环仍是外部待办。

7. 目标、非目标与约束

目标是让运行时配置的打包意图和 CLI 返回语义可被测试。非目标是声称 !2220 是
当前 dev 唯一打包机制、追溯修改 PyPI 7.3.0 或替维护者执行发版。约束是保持现有
CLI 参数和输出兼容，并承认 MANIFEST.in 的现有作用。

8. 需求与评审意见追踪

9. 总体架构与职责边界

flowchart LR
    S["源码配置"] -->|由 setup.py / MANIFEST 声明| W["wheel"]
    W -->|安装到| E["隔离环境"]
    E -->|执行| C["ascend-download --show-releases"]
    C -->|读取| J["release_config.json"]
    C -->|展示后返回| U["用户"]

仓库负责构建契约与回归；发布流程负责上传新版本；PyPI 用户路径负责最终验证。

10. 代表性主流程

sequenceDiagram
    participant Build as 构建
    participant Wheel as wheel
    participant CLI as ascend-download
    participant Config as release_config.json
    Build->>Wheel: 打包显式运行时数据
    Wheel->>CLI: 安装命令入口
    CLI->>Config: 读取配套版本
    Config-->>CLI: 返回版本表
    CLI-->>CLI: 展示后直接返回

11. 关键类或组件关系

setup.py 和 MANIFEST.in 共同影响包内容；ascend_download.py 负责参数分支；
download_util.show_releases() 消费配置。!2220 不增加公共接口。

12. 兼容、迁移与版本策略

无需用户配置迁移。合入后必须通过新版本号发布；旧 7.3.0 保持原行为。回滚会移除
显式声明和测试，但当前隐式打包链可能仍让构建通过，因此门禁需同时核对声明和行为。

#126-204 自验证报告

目录

• 1. 验证基线
• 2. 公开发布物验证
• 3. PR 目标测试
• 4. 构建与安装验证
• 5. A/B 对照
• 6. 远端状态
• 7. 结论与限制
• 8. 验证范围
• 9. 不可变环境基线
• 10. 需求到验证矩阵
• 11. 自验证结果总览
• 12. 故障与负向链路
• 13. 兼容与迁移验证
• 14. 限制与提交方结论

1. 验证基线

2. 公开发布物验证

在隔离环境安装当时及当前仍为最新版的 ascend-deployer==7.3.0：

wheel 包含 release_config.json：否
ascend-download --show-releases 退出码：2
错误：unrecognized arguments: --show-releases

2026-07-29 再次通过 PyPI 官方 JSON API 确认最新版仍是 7.3.0；本轮没有重新安装
wheel，因此命令行为沿用 2026-07-21 的实跑证据。

3. PR 目标测试

执行：

python3.8 -m pytest test/st/test_release_package.py -q
python3.10 -m pytest \
  test/st/test_release_package.py test/st/test_download.py -q

结果：

Python 3.8：2 passed，1 warning
Python 3.10：20 passed，2 warnings

警告是既有依赖的弃用提示。

4. 构建与安装验证

将 !2219 和 !2220 临时叠加到验证基线后：

sdist/wheel 构建：通过
wheel 包含 release_config.json：是
全新环境安装：通过
ascend-download --show-releases：退出码 0

5. A/B 对照

对照证明 !2220 是显式契约和回归保护，不应被描述为当前 dev 成功打包的唯一原因。

6. 远端状态

2026-07-29 GitCode API 回读：

Issue #204：open；标签含 resolved、stale
PR !2220：open、mergeable
head：7664d34a
门禁：CLA、docs CI、主 CI passed

7. 结论与限制

提交方证据支持 PR 候选的测试、构建和安装后 CLI 行为。PR 尚未合入，新 PyPI
版本也未发布，因此不能把 #204 写成用户侧最终闭环。

8. 验证范围

覆盖 PyPI 7.3.0 实装行为、!2220 目标测试、与 !2219 联合构建、隔离安装、CLI
E2E 和 A/B。未覆盖新版本发布后的公开安装、所有 Python 小版本或生产镜像。

9. 不可变环境基线

实跑固定为 2026-07-21：dev@bcf91984、!2220 7664d34a，
Python 3.8.8/3.10.20、setuptools 82.0.1、wheel 0.47.0。远端与 PyPI 版本状态于
2026-07-29 回读。

10. 需求到验证矩阵

11. 自验证结果总览

12. 故障与负向链路

旧 PyPI exit 2 是公开负向基线；A/B 对照否定“只有 package_data 才能成功”的过强
因果；回归测试还断言展示后不进入下载逻辑，防止成功输出后继续产生副作用。

13. 兼容与迁移验证

Python 3.8/3.10 目标测试通过，隔离安装后 CLI 返回 0。没有数据迁移；版本迁移依赖
发布新包。Python 3.6 未实跑。

14. 限制与提交方结论

提交方结论是 !2220 的显式契约和防回归价值有证据支持。它尚未合入或发布，不能
称为 #204 的公开用户侧最终闭环。