# 需求:Python-环境统一收尾-uv-安装轨归-D-盘+手装包层归轨+正本与探针同步

状态: done(2026-10-27 已落地:统一→依赖审计→迁移验证→删退役,全链实证:六包搬家对账一致七包import过;Roaming\Python/Roaming\uv/kev.venv/死shim删后回读不存在;C回收6.68GB+D回收约7.9GB;注入用户环境env.py check 56项全绿;test_env 27过;TOOLCHAIN批7已记)
归属: 公司运营
来源: boss 直投(会话)
日期: 2026-10-26
建议: 做,正本 TOOLCHAIN-STANDARD 与实况对账发现两处半途:UV_PYTHON_INSTALL_DIR/UV_TOOL_DIR 未设(uv 解释器/工具轨仍压 C 盘 Roaming\uv 共约 505MB)、机器级手装包层无归属判据(Roaming\Python 6.0GB 且 10-26 当天还在增长);收口后 Python 轨单一口径并补探针防回潮

## 现状

> 以下全部为 2026-10-26 实测读数(探测命令与输出在当日 worklog 留痕)。

### 1. 解释器与数据轨实况

| 轨 | 位置 | 实测 | 消费者 |
|---|---|---|---|
| 系统宿主 Python | `C:\Python314`(167MB,choco python3.14 同轨) | 系统层 site-packages 仅 pip 10.4MB,干净;TOOLCHAIN-STANDARD §2 明留「保留 C 盘」 | 全工作区 11 个 venv 中 10 个的 `pyvenv.cfg home` 指它;py launcher 默认 3.14 |
| uv 解释器轨 | `C:\Users\lin\AppData\Roaming\uv\python`(318MB) | 6 个解释器目录:3.10 / 3.10.19 / 3.11 / 3.11.15 / 3.13 / 3.15a1 | **唯一 venv 消费者=kev\.venv(3.13.12,6,849MB)**——kev 判断模型线 2026-10-26 已整体退役,此 venv 成死重 |
| uv 全局工具轨 | `C:\Users\lin\AppData\Roaming\uv\tools`(186.7MB) | `uv tool list` 仅 kimi-cli v1.44.0 | shim 在 `%USERPROFILE%\.local\bin`(已在 User PATH) |
| uv 缓存 | `D:\dev\uv\cache` | `UV_CACHE_DIR` 已设(User 级)✓ | — |
| 手装包层(pip --user) | `C:\Users\lin\AppData\Roaming\Python\Python314`(**6,008.8MB / 66,054 文件**) | site-packages 5,976MB(torch 4,216MB 为大头,另有 transformers/cv2/playwright/ddddocr/scipy/pyarrow/imageio_ffmpeg)+Scripts 32.6MB;10-20/22/23/26 持续有装包动作(最新 2026-10-26 16:57:av+edge-tts) | boss 本机手跑的 AI 工具栈;**User PATH 含 `...\Roaming\Python\Python314\Scripts`**;仓内硬引用 1 处:`tools/bili_clips.py:19` 写死该目录下 imageio_ffmpeg 的 ffmpeg.exe(实测文件在);它是 `C:\Python314` 的默认 user-site(机器级未设 PYTHONUSERBASE,pip 因系统目录无写权限自动回退 --user) |
| agent 平台运行时 | AutoClaw vendor Python 3.13 | harness 进程注入 `PIP_USER=1`+`PYTHONUSERBASE=...\AutoClaw-official\toolchain\python`(其 site-packages 当前为空) | 平台资产,不在本机统一范围,本次不动 |

零头残留:`Roaming\Python\Python313`(0.7MB)、`Roaming\Python\share`(shell 补全)。pip 源配置单点 `%APPDATA%\pip\pip.ini`(tuna),两个解释器共用,无问题。

### 2. 与正本(TOOLCHAIN-STANDARD)对账出的缺口

- **缺口①(落地欠账)**:正本 §2 写明 `UV_PYTHON_INSTALL_DIR / UV_TOOL_DIR = D:\dev\uv\*`,User 级实测只设了 `UV_CACHE_DIR` 一条;`D:\dev\uv` 下只有 cache 空壳 → 解释器与全局工具两轨实际仍压在 C 盘。10-17 批 3 记了「清重复轨(…Roaming uv…)」,清的是 uv 本体重复安装,数据轨没动。
- **缺口②(判据空窗)**:正本 §1 只定「项目依赖禁裸 `pip install`」,机器级手装包(boss 手跑工具栈)没有任何归属判据;机器级未设 `PYTHONUSERBASE`,pip 权限回退自动落默认 `Roaming\Python`,长期野蛮生长且已有仓内硬引用耦合。
- 连带发现(不在本票范围,另行处置):`spindle\.venv-spike`(4,745MB,home 指 F 盘 ComfyUI embed 3.12.10)属 spike 实验区;`kev\.venv`(6,849MB)随 kev 线退役成死重。

### 3. 存量 venv 盘点(11 个,共 ≈14.2GB)

| venv | 大小 | pyvenv.cfg home | 判定 |
|---|---|---|---|
| boss_analyze\.venv / collector\.venv | 232+15MB | C:\Python314 | 现役,不动 |
| crawler\.venv | 553MB | C:\Python314 | 现役,不动 |
| crawler_platform\.venv | 170MB | C:\Python314 | 现役,不动 |
| **kev\.venv** | **6,849MB** | Roaming\uv\python\cpython-3.13(3.13.12) | **退役死重**,处置见待拍板点 2 |
| mir2-runner\.venv | 309MB | C:\Python314 | 现役,不动 |
| nebula\tools\llama-py | 11MB | C:\Python314 | 现役,不动 |
| one_media\.venv-analysis | 71MB | C:\Python314 | 现役,不动 |
| quantitative_trading\.venv | 453MB | C:\Python314 | 现役,不动 |
| spindle\.venv | 750MB | C:\Python314 | 现役,不动 |
| spindle\.venv-spike | 4,745MB | F:\ComfyUI embed(3.12.10) | spike 实验区,独立轨,不在本次范围 |

→ **关键推论:uv 解释器轨迁移是「空手搬家」**——6 个解释器没有现役消费者,不需要重装/改写任何现役 venv。

## 方案

> 执行纪律(同 2026-10-17 六批与 10-26 Kev 退役先例):动手前 `ops/wip_snapshot.py` 快照 + 相关机检取基线;删除逐字绝对路径零通配符,删后逐项回读;全程 worklog 认领/结注;commit 走「基建 commit 豁免」傍晚分单元入库。建议 boss 空闲时段执行(执行前查无 python 进程占用旧 site-packages;User 级环境变量只对新进程生效,已开终端需重开)。

### A. uv 两轨归 D(清正本欠账,约 15 分钟)

- **A1** User 级补设 `UV_PYTHON_INSTALL_DIR=D:\dev\uv\python`、`UV_TOOL_DIR=D:\dev\uv\tools`(与正本 §2 一字不差)。
- **A2** uv tool 迁移:`uv tool install --reinstall kimi-cli`(新 `UV_TOOL_DIR` 生效后即落新轨;shim 仍在 `.local\bin`,PATH 不动)→ 验证 `kimi --help`。需网络(走代理);不便联网时本步挂欠账,其余照做(见待拍板点 3)。
- **A3** 旧轨处置:`Roaming\uv\tools` 在 A2 验证后删;`Roaming\uv\python`(318MB)随待拍板点 2 一起删;`Roaming\uv\credentials`(登录凭据,≈0MB)原地保留。
- **A4** 复核:`uv python list --only-installed` 无 Roaming 路径;`uv tool list` 正常;`py -0p` 的 Astral 注册项消失或指新轨。

### B. 手装包层归轨(核心块,约 40 分钟)

- **B1** 定落点:User 级设 `PYTHONUSERBASE=D:\dev\python-user`(名字见待拍板点 1)。此后 3.14 的 user site=`D:\dev\python-user\Python314\site-packages`(Windows 形态 `%PYTHONUSERBASE%\Python<XY>\site-packages`,与 harness 注入的 toolchain 形态一致)。
- **B2** 搬家(两份并存窗口):`robocopy /E /MT:8 /L` 先预演核对文件数 ≈66,054,再实拷 `Roaming\Python\Python314` → `D:\dev\python-user\Python314`。Scripts 里的 exe shim 内嵌的是解释器绝对路径(C:\Python314\python.exe),与包目录位置无关,整体搬移安全。
- **B3** PATH:User PATH 条目 `Roaming\Python\Python314\Scripts` → `D:\dev\python-user\Python314\Scripts`(原值全文记入 worklog 以便回滚)。
- **B4** 逐项验证:新开 shell ①`python -m site` 的 USER_SITE 指新落点;②`python -c "import torch,cv2,transformers,ddddocr,imageio_ffmpeg,scipy,pyarrow"`;③`edge-tts --help`;④`rg -l "Roaming" D:\dev\python-user\Python314\site-packages -g "*.pth"` 应无命中,有命中者单独 `pip install --force-reinstall` 到新落点。
- **B5** 根治硬引用:`tools/bili_clips.py` 的 FFMPEG 常量改为 `imageio_ffmpeg.get_ffmpeg_exe()` 动态解析(消灭对落点的依赖,优于跟着搬家再改一次路径);跑 `probe_duration` 冒烟。
- **B6** 旧目录删除:`Roaming\Python` 整目录(含 Python314 6.0GB / Python313 0.7MB / share)——**删前**导出顶层包名+版本(dist-info)清单存 `ops/audits/` 作重建台账;删后逐项回读不存在。
- **B7** agent 行为不变确认:harness 进程注入的 PYTHONUSERBASE 覆盖 User 值,agent `pip --user` 仍落 AutoClaw toolchain(实测一次并留痕)。

### C. 正本与探针同步(必须同批,约 20 分钟)

- **C1** TOOLCHAIN-STANDARD §1 Python 行补一句:「机器级手装包(pip --user)唯一落点=PYTHONUSERBASE(见 §2);项目依赖仍禁裸 pip install」。
- **C2** §2 表:`UV_PYTHON_INSTALL_DIR/UV_TOOL_DIR` 行标注「批 7(2026-10-26)已设」;新增 `PYTHONUSERBASE → D:\dev\python-user` 行(治手装包层 6.0GB)。
- **C3** §3 收敛执行追加「批 7(2026-10-26)」记录(A/B/C 摘要 + 复验口径)。
- **C4** `ops/env.py` ITEMS:+2 envpath 探针(UV_PYTHON_INSTALL_DIR / UV_TOOL_DIR)+1 手装包层探针(落点存在且 `Roaming\Python` 不复存在,防回潮)。
- **C5** `ops/test_env.py` 同批补 fixture(ENV-STANDARD 纪律 5:环境变了先改探针再改结论)。
- **C6** 复验:`python ops/env.py check` 全绿;`python -m pytest ops/test_env.py -q` 过。

## 风险与回滚

| 风险 | 对冲 |
|---|---|
| 6GB 搬家中断 | robocopy 断点可重跑;旧目录在 B4 全绿前不删(两份并存窗口) |
| 个别包内嵌绝对路径(.pth / editable 安装) | B4 第④步专查;命中者单独 --force-reinstall,不扩大改动面 |
| uv 下载依赖网络(代理) | A2 仅 kimi-cli 一个包;失败则 A2 挂欠账不阻塞 A1/A3(python 轨)/B/C |
| 执行中 boss 进程占用旧 site-packages | 执行前盘 python 进程;并发认领协议已留痕,同刻仅本会话动环境 |
| 环境变量改动波及已开 shell | User 级变量仅新进程生效;执行完提醒 boss 重开终端 |
| 回滚路径 | 环境变量删掉即回默认;PATH 原值在 worklog;旧目录 B6 前原样在;B6 后可按 ops/audits/ 台账重装 |

## 验收标准(2026-10-27 00:39 实测勾验)

- [x] 三变量注册表读回:UV_PYTHON_INSTALL_DIR='D:\dev\uv\python'、UV_TOOL_DIR='D:\dev\uv\tools'、PYTHONUSERBASE='D:\dev\python-user'
- [x] USER_SITE 指 D:\dev\python-user\Python314\site-packages;torch/cv2/transformers/ddddocr/imageio_ffmpeg/scipy/pyarrow 七包 import 全过(torch/ffmpeg 解析路径均在新落点)
- [x] User PATH 已换根无 Roaming\Python 残留(机器级同条目非管理员未动,死条目无害已记录);edge-tts 7.3.1 实测从新 Scripts 出
- [x] bili_clips.py 改 imageio_ffmpeg.get_ffmpeg_exe() 动态解析(py_compile 过);全仓 rg 'Roaming[/\\](Python|uv)' 活引用仅剩本票与 worklog 历史记述
- [x] Roaming\Python、Roaming\uv\{python,tools}、Local\uv\cache、kev\.venv、5 个死 shim 全删且回读不存在;C 盘回收 6.68GB(可用 44.1GB),D 盘另回收 ≈7.9GB(kev 硬链接数据块=uv 缓存 7.84GB 清理)
- [x] TOOLCHAIN-STANDARD 三处更新(§1/§2/§3 批 7);注入用户环境 env.py check 全绿 56 项;ops/test_env.py 27 过
- [x] worklog 认领+结注留痕;删除台账落 ops/audits/2026-10-26-env-unify/(PATH 原值+209 包 dist-info 清单+81 Scripts 清单)

## 执行记录与 boss 决议(2026-10-26 深夜会话→2026-10-27 00:39 落地)

- **boss 拍板原文**:「统一环境,环境统一后,判断代码有依赖,依赖迁移完以后进行删除退役的环境」→ 全案批准;按此顺序执行:新轨设立→搬家对账→依赖审计(全仓 rg+11 个 pyvenv.cfg 全量对账+计划任务+shim 清点)→验证全绿→才动手删除。
- **偏差①A2 改判退役**:kimi-cli 迁移两次尝试失败,根因是上游依赖漂移(google-re2 需 MSVC 编译、pillow 12.2 仅 sdist),连钉回 1.44.0 也装不上;依赖审计实证 boss 在用的 `kimi` 来自 `.kimi-code\bin`(另一产品),uv tool 这套全仓零引用、shim 停在 2026-04/05 → 按「退役环境」删除(含 shim 五件)。
- **偏差②新轨保洁**:失败安装带进新轨的 3.15/3.15.0a6 解释器已 uninstall,新轨保持空净。
- **遗留(无害,已记录)**:机器级 PATH 的旧 Roaming\Python\Scripts 条目因本会话非管理员未清;boss 可在管理员 PowerShell 执行:`[Environment]::SetEnvironmentVariable('Path',(([Environment]::GetEnvironmentVariable('Path','Machine') -split ';' | Where-Object { $_ -notmatch 'Roaming\\\\Python' }) -join ';'),'Machine')`。
- **语境注意**:该层 Scripts 的 pip 系 CLI(edge-tts 等)依赖 PYTHONUSERBASE 在位——用户级已设,boss 新终端自动生效;agent harness shell 不带用户环境属平台行为,跑 env.py check 须按正本复验口径注入用户环境。