#126-205 脚本权限保持设计文档

目录

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

1. 评审目标

确认 setup.py 在转换 shell 脚本换行符时只临时增加写权限，并在正常或异常路径
恢复原始权限，使 sdist/wheel 构建不再得到 write-only 源文件。

2. 问题与根因

原 crlf_to_lf() 调用：

os.chmod(file_path, stat.S_IWRITE)

该调用覆盖整个权限位，而不是只增加 owner write，导致脚本变为 0200。
setuptools 随后无法读取脚本，普通用户构建 sdist/wheel 失败。

3. PR 设计

读取 original_mode
  -> original_mode | owner-write
  -> 写入 LF 内容
  -> finally 恢复 original_mode

实现使用 stat.S_IMODE() 保存权限，避免把文件类型位混入 chmod。测试在临时项目
中创建带 CRLF 且权限为 0550 的三份脚本，执行真实 setup.py --name，同时断言：

• CRLF 被转换为 LF；
• 命令成功；
• 三份脚本权限逐项恢复为原值。

4. 正确性约束

• 只临时增加 owner write；
• 不删除原有 read/execute 位；
• 写入成功或异常退出都恢复权限；
• 不把所有文件写死为同一个固定 mode；
• 测试不依赖私有目录或真实安装环境。

5. 验收标准

• Python 3.8/3.10 目标测试通过；
• setup.py sdist bdist_wheel 成功；
• 源码和 sdist 脚本权限保持可读、可执行；
• wheel 产物不出现 0200；
• CLA、CI、安全与格式门禁通过。

6. 当前状态

2026-07-29 API 回读确认 !2219 open、mergeable，head 93bff630 的 CLA、文档和
主 CI 通过；#205 仍 open。代码候选已验证，但人工评审、合入和父任务验收仍待外部
完成。

7. 目标、非目标与约束

目标是在换行转换前后保持每个脚本的原始权限不变量。非目标是统一所有脚本为
0755、改变归档工具自身的权限规范化或重构 setuptools 流程。约束是成功和异常
路径都恢复权限，并兼容项目声明的 Python 范围。

8. 需求与评审意见追踪

9. 总体架构与职责边界

flowchart LR
    F["shell 脚本 / 原 mode"] -->|读取并保存| M["original_mode"]
    M -->|临时增加 owner write| W["CRLF → LF 写入"]
    W -->|finally 恢复| R["源码原 mode"]
    R -->|交给| B["setuptools 构建"]

crlf_to_lf() 只拥有转换期间的临时权限；源码策略和归档权限由各自层负责。

10. 代表性主流程

sequenceDiagram
    participant Setup as setup.py
    participant FS as 文件系统
    participant Build as setuptools
    Setup->>FS: 读取 original_mode
    Setup->>FS: 临时增加 owner write
    Setup->>FS: 写入 LF 内容
    Setup->>FS: finally 恢复 original_mode
    Setup->>Build: 开始 sdist / wheel
    Build-->>Setup: 返回构建结果

11. 关键类或组件关系

本项是函数级修复，没有新增类或公共接口。setup.py::crlf_to_lf 操作源码文件，
测试在临时项目调用真实 setup 路径，setuptools 再读取产物。

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

无需配置迁移。回滚会恢复 0200 风险。源码与 sdist 应保持原 0550；wheel 工具
可能增加 owner write 形成 0750，但仍必须可读、可执行且不得为 write-only。

#126-205 自验证报告

目录

• 1. 验证基线
• 2. 修复前复现
• 3. PR 目标验证
• 4. 产物权限
• 5. 兼容与门禁
• 6. 远端状态
• 7. 结论与限制
• 8. 验证范围
• 9. 不可变环境基线
• 10. 需求到验证矩阵
• 11. 自验证结果总览
• 12. 故障与负向链路
• 13. 兼容与迁移验证
• 14. 限制与提交方结论

1. 验证基线

2. 修复前复现

在未应用修复的基线执行：

python3.10 setup.py sdist bdist_wheel

观察：

构建退出码：1
错误：Permission denied: ascend_deployer/install.sh
三份目标脚本权限：0200

3. PR 目标验证

执行：

python3.8 -m pytest test/test_setup.py -q
python3.10 -m pytest test/test_setup.py -q
python3.10 setup.py sdist bdist_wheel

结果：

Python 3.8：1 passed
Python 3.10：1 passed
sdist：通过
wheel：通过

4. 产物权限

wheel 工具为归档内脚本增加 owner write 位；三类文件均可读、可执行，不再出现
0200。

5. 兼容与门禁

将 !2219 临时叠加到验证基线后，Python 3.8/3.10 目标测试和真实构建结果一致。
变更文件的 whitespace、Ruff、format、Pylint、Bandit、codespell、typos 和
git diff --check 通过。Python 3.6 只做语法解析检查，未进行真机运行。

6. 远端状态

2026-07-29 GitCode API 回读：

Issue #205：open；标签含 resolved、stale
PR !2219：open、mergeable
head：93bff630
门禁：CLA、docs CI、主 CI passed

7. 结论与限制

提交方证据支持修复前复现、修复后测试、真实构建及产物权限闭环。PR 尚未合入，
Issue 仍 open，因此不表述为维护者已验收。

8. 验证范围

覆盖未修复基线、Python 3.8/3.10 目标测试、真实 sdist/wheel、源码和产物 mode、
静态门禁及远端 CI。未覆盖 Python 3.6 运行时、Windows 权限语义或 PR 合入。

9. 不可变环境基线

实跑固定为 2026-07-21：dev@bcf91984、!2219 93bff630，
Python 3.8.8/3.10.20、setuptools 82.0.1、wheel 0.47.0。远端状态于
2026-07-29 回读。

10. 需求到验证矩阵

11. 自验证结果总览

12. 故障与负向链路

未修复基线直接展示权限覆盖后的失败。实现使用 finally 的设计覆盖写入异常；当前
报告保留的实跑主要证明正常转换和构建，若维护者要求应补显式注入写入异常的单测。

13. 兼容与迁移验证

Python 3.8/3.10 已运行；Python 3.6 仅语法解析。无需数据迁移；回滚会恢复原缺陷。
归档工具对 wheel mode 的调整不被误判为源码权限未恢复。

14. 限制与提交方结论

提交方结论是 !2219 在所列环境形成修复前复现、修复后测试、真实构建和权限检查
闭环。人工评审、合入和父任务验收仍待外部。