feat(scripts): 添加 PEP 723 脚本元数据并修复 HTTP/2 伪头过滤问题
- 为 build_studio_urls.py 和 lookup_groups.py 添加 PEP 723 依赖声明 - 修复 HTTP/2 伪头导致 requests 抛 InvalidHeader 的问题 - 添加 CDP 端口连通性预检查及启动指引
This commit is contained in:
@@ -1,61 +1,95 @@
|
||||
---
|
||||
name: "uv-env-setup"
|
||||
description: "用 uv 准备并维护本项目 Python 运行环境（pyproject.toml → uv sync → uv run）。当用户提到环境准备/环境初始化/装依赖/重建 venv，脚本报 ModuleNotFoundError（pandas/openpyxl/playwright），.venv 缺失或损坏，或首次运行 scripts/、skills/*/scripts/ 下的 Python 脚本时使用。"
|
||||
description: "用 uv 准备并维护本项目与各技能脚本的 Python 运行环境（项目环境 uv sync / 单脚本 PEP 723 模式）。当用户提到环境准备/装依赖/重建 venv、脚本报 ModuleNotFoundError（pandas/openpyxl/playwright），或 uv/.venv 不可用时使用。"
|
||||
---
|
||||
|
||||
# uv 运行环境准备
|
||||
|
||||
本项目所有 Python 脚本共用一套 uv 管理的环境：根目录 `pyproject.toml` 是依赖的**唯一事实来源**，`uv sync` 落地 `.venv\`，`uv run` 执行脚本（自动使用该环境，免激活、免手装依赖）。
|
||||
三种运行形态共用一个入口 `uv run`：
|
||||
|
||||
## 步骤 1：确认 uv 可用
|
||||
- **项目环境**：在含 `pyproject.toml` 的项目根运行 `scripts/` 或整套技能。根 `pyproject.toml` 是依赖唯一事实来源，`uv sync` 落地 `.venv\`，`uv run` 免激活执行。
|
||||
- **单脚本模式**：脱离项目仓库单独运行某个技能脚本（如技能安装到用户级目录后跨项目使用）。三个脚本头部都带 PEP 723 内联依赖声明（`# /// script ... ///`），`uv run <脚本路径>` 会自动建缓存环境并装依赖，无需任何项目文件。
|
||||
- **无 uv 回退链**：uv 完全不可用时按固定顺序降级，见步骤 1。
|
||||
|
||||
先按下表选分支，再执行对应步骤。
|
||||
|
||||
| 你的情况 | 分支 |
|
||||
|---|---|
|
||||
| 在本项目目录内跑任何脚本 | A：项目环境 |
|
||||
| 技能已安装到用户级目录（如 `~\.trae-cn\skills\`、`~\.zcode\skills\`），当前目录没有 pyproject.toml | B：单脚本模式 |
|
||||
| `uv` 命令无法识别 | 先走步骤 1 的回退链，再回到 A/B |
|
||||
|
||||
**完成判据（全局）**：最终用于跑业务脚本的那条命令成功打印结果，且不是靠裸 `python` 碰运气。
|
||||
|
||||
## 步骤 1：确认 uv 可用（含回退链）
|
||||
|
||||
```powershell
|
||||
uv --version
|
||||
```
|
||||
|
||||
未安装时任选其一（Windows）：
|
||||
失败时**按顺序**尝试，命中即停：
|
||||
|
||||
- `winget install astral-sh.uv`
|
||||
- `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
|
||||
- `pip install uv`
|
||||
1. **会话内刷新 PATH 再试**（刚装完 uv、不想重开终端）：
|
||||
- PowerShell：`$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")`
|
||||
- Git Bash / zsh：`export PATH="$PATH:$HOME/.local/bin"`
|
||||
- cmd：重开终端（cmd 无法可靠刷新）
|
||||
2. **`python -m uv --version`**：只要 uv 以模块存在就可用。此后把本文所有 `uv <子命令>` 都替换为 `python -m uv <子命令>`，其余不变。
|
||||
3. **`pip install uv` 装上后回到第 2 条**（winget/官方脚本安装的 uv 对新会话才生效，pip 装的立即随当前 Python 可用）。
|
||||
|
||||
装完重开终端使 PATH 生效。
|
||||
**完成判据**：`uv --version` 或 `python -m uv --version` 打印出版本号；若走了第 2 条，记下后续命令都要带 `-m uv`。
|
||||
|
||||
**完成判据**：`uv --version` 打印出版本号。
|
||||
## 步骤 2A：项目环境同步
|
||||
|
||||
## 步骤 2：同步依赖
|
||||
|
||||
项目根目录（`pyproject.toml` 所在处）执行：
|
||||
项目根（`pyproject.toml` 所在处）执行：
|
||||
|
||||
```powershell
|
||||
uv sync
|
||||
```
|
||||
|
||||
- 首次运行自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright）。
|
||||
- 首次自动创建 `.venv\` 并安装全部依赖（pandas、openpyxl、playwright、requests）。
|
||||
- 本机无兼容 Python 时，uv 自动下载托管 Python（`requires-python = ">=3.10"`）。
|
||||
- `uv run` 本身也会隐式同步；显式 `uv sync` 是为了在跑脚本前把依赖错误一次性暴露出来。
|
||||
- `uv run` 会隐式同步；显式 `uv sync` 是为了把依赖错误一次性暴露。
|
||||
|
||||
**完成判据**：命令退出码 0，且项目根出现 `.venv\` 目录。
|
||||
**完成判据**：退出码 0，且项目根出现 `.venv\` 目录。
|
||||
|
||||
## 步骤 2B：单脚本模式（无项目文件）
|
||||
|
||||
对任意一个技能脚本直接：
|
||||
|
||||
```powershell
|
||||
uv run "C:/Users/<you>/.trae-cn/skills/yt-studio-url-builder/scripts/build_studio_urls.py" --help
|
||||
```
|
||||
|
||||
- uv 读脚本头部的 PEP 723 声明，自动缓存专用环境（默认仅 pandas/openpyxl，或含 playwright）。
|
||||
- 环境、路径写法用正斜杠 `/`，在 PowerShell、Git Bash、cmd 中都合法。
|
||||
- 首次运行某脚本会下载其依赖，耗时略长属正常现象。
|
||||
|
||||
**完成判据**：脚本按预期输出（`--help` 打印用法 / `--selftest` 打印 selftest OK），无需 `.venv` 或 pyproject.toml。
|
||||
|
||||
## 步骤 3：验证
|
||||
|
||||
项目环境下三条自检：
|
||||
|
||||
```powershell
|
||||
uv run python -c "import pandas, openpyxl, playwright; print('env OK')"
|
||||
uv run python skills\youtube-studio-csv-download\scripts\youtube_export_download.py --selftest
|
||||
uv run python skills\yt-studio-url-builder\scripts\build_studio_urls.py --help
|
||||
uv run python -c "import pandas, openpyxl, playwright, requests; print('env OK')"
|
||||
uv run python skills/youtube-studio-csv-download/scripts/youtube_export_download.py --selftest
|
||||
uv run python skills/yt-studio-groupid-lookup/scripts/lookup_groups.py --selftest
|
||||
```
|
||||
|
||||
**完成判据**：三条命令均成功——打印 `env OK`、`selftest OK`、脚本的用法帮助。
|
||||
**完成判据**：打印 `env OK` 与两条 `selftest OK`。
|
||||
|
||||
## 其他技能如何使用本环境
|
||||
|
||||
- 统一在项目根目录用 `uv run python <脚本> [参数]` 执行，uv 自动向上定位 `pyproject.toml` 并复用其环境。
|
||||
- 不用裸 `python`（依赖 PATH 碰运气），不手动激活 venv，不 `pip install` 到全局。
|
||||
- 四个业务技能（url-builder、groupid-lookup、csv-download）的 SKILL.md 默认**本技能已跑通**；它们给出的 `uv run python <脚本>` 命令按所选分支执行即可。
|
||||
- 统一不裸调 `python`、不手动激活 venv、不向全局 `pip install` 依赖。
|
||||
- 各 agent（trae-cn / zcode 等）的终端方言不同：示例中的调用统一写成对两者都安全的形态——正斜杠路径 + 引号包裹；确需 shell 特有能力时区分 PowerShell 与 bash 写法，不要混用。
|
||||
|
||||
## 新增依赖
|
||||
|
||||
改 `pyproject.toml` 的 `dependencies`（唯一入口），再 `uv sync` 更新 `uv.lock`。禁止 `pip install` / `uv pip install` 直装——绕过 lock，环境不可复现。
|
||||
- 项目环境：改根 `pyproject.toml` 的 `dependencies`（唯一入口）后 `uv sync` 更新 `uv.lock`。
|
||||
- 单脚本模式：改脚本头部 PEP 723 的 `dependencies`，下次 `uv run` 自动生效。
|
||||
- 两个来源不要混着加同一依赖，防止版本漂移；禁止绕过声明直装。
|
||||
|
||||
## 排查
|
||||
|
||||
网络慢/超时、uv 安装失败、`.venv` 损坏重建、多版本 Python 冲突等，查 [references/troubleshooting.md](references/troubleshooting.md)。
|
||||
网络慢/超时、镜像配置、`.venv` 损坏重建、uv 安装方式差异、无 uv 手动兜底等，查 [references/troubleshooting.md](references/troubleshooting.md)。
|
||||
|
||||
@@ -1,9 +1,20 @@
|
||||
# 环境排查
|
||||
|
||||
## uv 安装与 PATH
|
||||
## uv 不识别（按序排查）
|
||||
|
||||
- **`uv: command not found` / 无法识别**：装完未重开终端，PATH 未生效；重开终端或手动刷新 `$env:Path`。
|
||||
- **winget 安装失败**：改用官方脚本 `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`，或 `pip install uv`。
|
||||
1. **刚装完、当前会话不认识**：会话内刷新 PATH——
|
||||
- PowerShell：`$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")`
|
||||
- Git Bash / zsh：`export PATH="$PATH:$HOME/.local/bin"`
|
||||
- cmd：重开终端。
|
||||
2. **试试模块入口**：`python -m uv --version`。可用则后续所有 `uv <子命令>` 都换成 `python -m uv <子命令>`。
|
||||
3. **用 pip 兜底安装**：`pip install uv` 后回到第 2 条，立即生效（winget/官方脚本方式要等新终端）。
|
||||
4. **彻底没有 Python/uv**：先装 Python 3.10+（或让 `uv` 官方脚本一并装好托管 Python），再走第 3 条。
|
||||
|
||||
## 无 pyproject.toml 的目录跑脚本
|
||||
|
||||
- 脚本头部带 PEP 723 声明（`# /// script ... ///`），直接 `uv run <脚本>` 即可，uv 自动建缓存环境。
|
||||
- 报「无法解析依赖/找不到脚本」时：确认路径存在且为正斜杠写法；确认脚本头部声明未被删改。
|
||||
- 需要重建缓存环境：删除 `%LOCALAPPDATA%\uv\cache\environments-v2` 下对应目录（或整体清 `uv cache clean`）后重试。
|
||||
|
||||
## 网络与镜像（国内环境）
|
||||
|
||||
@@ -28,6 +39,14 @@ default = true
|
||||
- **lock 与 pyproject 不一致**：`uv.lock` 过期，`uv sync` 会自动更新；若报 lock 损坏，删除 `uv.lock` 后重新 `uv sync`。
|
||||
- **`requires-python` 不满足**：本机 Python 全部低于 3.10。让 uv 自动下载即可：`uv sync -p 3.12`（或省略，uv 自选）。
|
||||
|
||||
## 已有 .venv 但缺 pyproject.toml
|
||||
|
||||
历史环境是手动 `pip install` 搭的，不是 uv 管理：
|
||||
|
||||
1. 在项目根新建 `pyproject.toml`，`dependencies` 写全实际用到的包（参考现有 .venv 里 `pip list`）。
|
||||
2. `requires-python` 与现有解释器大版本一致（如 `">=3.12"`），避免 uv 另下新 Python。
|
||||
3. `uv sync` 让 uv 接管该 `.venv` 并生成 `uv.lock`。
|
||||
|
||||
## .venv 损坏 / 重建
|
||||
|
||||
症状：`uv run` 报奇怪的导入错误、DLL 加载失败，或 `.venv` 被移动过。
|
||||
@@ -39,10 +58,20 @@ uv sync
|
||||
|
||||
## playwright 相关
|
||||
|
||||
- **`ModuleNotFoundError: playwright`**：环境未同步。项目根执行 `uv sync`，或直接用 `uv run python <脚本>`（隐式同步）。
|
||||
- **`ModuleNotFoundError: playwright`**：环境未同步。项目根执行 `uv sync`，或直接用 `uv run python <脚本>`；单脚本模式下直接 `uv run <脚本>`（PEP 723 自动装）。详见 SKILL.md 步骤 1 回退链。
|
||||
- **复用系统 Chrome/Edge 无需 `playwright install`**：只有用 uv 环境内置 Chromium 时才需要 `uv run playwright install chromium`。
|
||||
- **`playwright install` 下载浏览器慢**：`$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright"` 后重试。
|
||||
|
||||
## 无 uv 的最终兜底
|
||||
|
||||
uv 完全装不上时，用标准库 venv 手动搭（仅应急，失去 lock 可复现性）：
|
||||
|
||||
```powershell
|
||||
python -m venv .venv
|
||||
.venv\Scripts\python.exe -m pip install pandas openpyxl playwright requests
|
||||
# 此后所有命令用 .venv\Scripts\python.exe 替代 uv run python
|
||||
```
|
||||
|
||||
## 与全局环境隔离
|
||||
|
||||
- 本项目所有命令都经 `uv run`，不会污染全局 site-packages。
|
||||
|
||||
Reference in New Issue
Block a user