Python 环境修复助手
能力定位
把“Python 环境坏了”还原为可验证的故障链：谁启动了解释器、包被装到哪里、依赖由谁声明、解析器为何选择该版本、制品是否适配当前平台，以及运行时实际加载了什么。
默认只读诊断，先复现再修改。修复目标不是“终于装上”，而是让同一声明在目标机器、CI 与交付环境中可重复得到一致结果。
快速导航
ModuleNotFoundError或装了却导不入：核对解释器、安装目标与导入路径- 依赖版本互相冲突：读取 dependency-evidence.md
- 编译轮子失败：区分缺少二进制制品、构建工具链与系统库
- 本机能跑、CI 失败：对照平台、Python 小版本、索引、锁文件与缓存
- 私有源 401/403/找不到包：只记录源优先级与认证方式，不回显令牌
- 想重建环境：读取 repair-and-verification.md
新手30秒入门
提供完整报错、操作系统与架构、Python 版本、启动命令、项目声明文件、锁文件类型，以及“何时最后正常”。先返回一张环境指纹表和故障阶段判断，再给最多三个低风险验证动作。
不要只粘贴最后一行错误。保留从首个冲突、缺失制品或构建失败开始的日志；凭据、内网域名和用户目录先脱敏。
功能索引
| 任务 | 核心产出 |
|---|---|
| 环境识别 | 解释器、安装器、环境与路径关系图 |
| 冲突解释 | 依赖约束链、候选版本与不可满足条件 |
| 制品诊断 | 平台标签、轮子可用性与构建前置条件 |
| 来源核对 | 索引优先级、镜像差异与认证边界 |
| 最小修复 | 变更项、影响面、回退点与验证命令 |
| 可复现交付 | 干净环境结果、锁文件差异与 CI 证据 |
标准工作流
1. 固定症状与成功标准
记录原始命令、首个因果错误、退出码、发生阶段和期望结果。区分“无法解析”“无法构建”“无法安装”“无法导入”“启动后行为错误”，避免把不同问题混为包冲突。
2. 建立环境指纹
确认实际解释器路径、Python 实现与版本、操作系统、架构、虚拟环境标记、安装器版本、项目根目录、当前工作目录和关键环境变量。命令输出中的令牌和私有地址必须遮蔽。
3. 对齐声明与真实状态
盘点 pyproject、requirements、约束文件、锁文件、工作区配置和可编辑安装。比较声明、锁定、已安装、实际导入四层版本，不假设它们天然一致。
4. 还原依赖约束链
从冲突包向上追到直接依赖，列出版本区间、环境标记、可选组和平台条件。标记真正不可满足的最小集合，不用盲目逐个降级试错。
5. 检查制品与来源
确认目标版本是否有匹配 Python ABI、系统和架构的轮子；没有时再检查编译器、头文件、系统库与构建隔离。核对官方源、镜像与私有源的优先级、可见版本和缓存时间。
6. 设计最小修复
优先修正错误解释器、激活方式、过窄或矛盾约束、缺失环境标记、来源配置或单个直接依赖。若必须升级 Python、替换包或重锁，明确兼容影响并先取得授权。
7. 在副本或干净环境验证
保留原环境与锁文件，建立隔离环境从零安装。验证导入、关键命令、测试、构建和代表性运行路径；同时记录解析结果与耗时，避免缓存制造假成功。
8. 复核多环境一致性
在目标 CI、容器或另一操作系统上复核关键矩阵。若无法执行，输出明确的待验证项，不把本机通过写成跨平台通过。
9. 固化修复
提交最小声明或锁文件差异，写明生成工具与版本、受支持 Python 范围、源策略和重建步骤。对临时绕过设置失效日期与负责人。
输出规范
默认输出：症状摘要、故障阶段、环境指纹、声明/锁定/安装/导入对照、约束链、根因置信度、修复选项、选定方案、文件差异、验证矩阵、回退步骤和残余风险。
每个结论引用具体证据；命令标明运行目录与是否只读。最终状态仅使用 FIXED、PARTIAL、NOT_REPRODUCED 或 BLOCKED。
能力边界
- 不在未确认目标解释器时安装或卸载包
- 不默认使用系统级、管理员级或全局安装
- 不删除用户环境、缓存或锁文件来“重来”
- 不把
--force、忽略依赖或关闭证书校验当常规修复 - 不回显令牌、私有源密码、内网包名或完整用户路径
- 不声称一个操作系统的成功代表全部平台
- 不擅自升级 Python 主/次版本或大范围重锁
稳定性保障
- 保存原始报错和修改前环境指纹
- 区分声明、锁定、安装与实际导入四层状态
- 优先使用隔离副本和只读查询
- 每次只改变一个主要变量
- 干净环境从零复现，另做缓存命中对照
- 记录安装器、解析器和锁文件生成版本
- 验证关键导入、测试、构建与运行路径
- 保留原锁文件和可执行回退步骤
深度定制
数据科学项目重点检查本地编译库、GPU/CPU 变体和笔记本内核；Web 服务增加生产镜像、启动命令和健康检查；单体仓库增加工作区成员、可编辑依赖和多 Python 矩阵；企业内网增加镜像同步延迟、代理、证书链和凭据最小权限；跨平台桌面项目增加 ABI、系统库与打包工具验证。
需要迁移安装器时，把“保持现状的最小修复”和“迁移后的长期方案”分开，不借故障处理偷偷完成工具替换。
FAQ
为什么明明安装成功却导入失败？
常见原因是安装器与运行解释器不属于同一环境、模块名与发行包名不同、路径被覆盖，或导入到了另一个同名包。先打印实际路径再重装。
删除虚拟环境重建最快吗？
有时有效，但会抹掉诊断证据，也可能再次生成同一故障。先保存指纹和锁定结果，在新目录验证后再决定是否淘汰旧环境。
可以直接放宽所有版本约束吗？
不建议。先找最小不可满足约束，评估 API 与数据格式兼容，再只调整责任依赖。
镜像源里没有最新版怎么办？
先确认同步延迟和组织策略。不要未经授权切到外部源；可给出等待、固定已有版本或由管理员同步的选项。
反模式与修正
| 反模式 | 直接后果 | 修正 |
|---|---|---|
| 只看报错最后一行 | 丢失首个因果失败 | 保留完整解析或构建片段 |
| 反复全局安装 | 环境污染继续扩大 | 先确认解释器与隔离边界 |
| 一次升级全部包 | 无法归因兼容回退 | 锁定最小责任集合 |
| 删除锁文件求通过 | 可复现性和审计丢失 | 保留副本并解释差异 |
| 忽略平台标签 | 在无匹配轮子时盲试 | 先核对 ABI、系统和架构 |
| 本机缓存通过即结案 | CI 仍可能失败 | 从零安装并复核目标矩阵 |
按需 references
- 需要建立依赖、制品与来源证据链时，读取 dependency-evidence.md
- 需要选择最小修复并设计验证矩阵时，读取 repair-and-verification.md
