工作区排查

uv 不识别（按序排查）

刚装完、当前会话不认识：会话内刷新 PATH——
- PowerShell：$env:Path = [Environment]::GetEnvironmentVariable("Path","Machine") + ";" + [Environment]::GetEnvironmentVariable("Path","User")
- Git Bash / zsh：export PATH="$PATH:$HOME/.local/bin"
- cmd：重开终端。
试试模块入口：python -m uv --version。可用则后续所有 uv <子命令> 都换成 python -m uv <子命令>。
用 pip 兜底安装：pip install uv 后回到第 2 条，立即生效（winget/官方脚本方式要等新终端）。
彻底没有 Python/uv：先装 Python 3.10+（或让 uv 官方脚本一并装好托管 Python），再走第 3 条。

uv sync / uv run 拉包慢或超时时，临时切换清华镜像：

$env:UV_DEFAULT_INDEX = "https://pypi.tuna.tsinghua.edu.cn/simple"
uv sync

要持久化则写入工作区 pyproject.toml：

[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

No solution found / 依赖解析冲突：dependencies 里的版本约束互相矛盾（含 uv add 追加的包与既有约束冲突）。放宽或修正 pyproject.toml 后重试。
缺必需包：pyproject.toml 里没有 pandas/openpyxl/playwright/requests（常见于复用已有项目）。工作区根执行 uv add pandas openpyxl playwright requests 补齐（幂等）。
lock 与 pyproject 不一致：uv.lock 过期，uv sync / uv add 会自动更新；若报 lock 损坏，删除 uv.lock 后重新 uv sync。
requires-python 不满足：本机 Python 全部低于 3.10。让 uv 自动下载即可：uv sync -p 3.12（或省略，uv 自选）。

症状：uv run 报奇怪的导入错误、DLL 加载失败，或 .venv 被移动过。工作区根执行：

Remove-Item -Recurse -Force .venv
uv sync

ModuleNotFoundError: playwright（或其他必需包缺失）：环境未同步或缺包。工作区根执行 uv add pandas openpyxl playwright requests 补齐，或直接用 uv run python <脚本>。
复用系统 Chrome/Edge 无需 playwright install：只有用工作区内置 Chromium 时才需要 uv run playwright install chromium。
playwright install 下载浏览器慢：$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright" 后重试。

技能脚本头部带 PEP 723 内联依赖声明（# /// script ... ///），在无 pyproject.toml 的目录直接 uv run <脚本> 也可运行，uv 自动建缓存环境：

报「无法解析依赖/找不到脚本」时：确认路径存在且为正斜杠写法；确认脚本头部声明未被删改。
需要重建缓存环境：删除 %LOCALAPPDATA%\uv\cache\environments-v2 下对应目录（或整体 uv cache clean）后重试。
批量/长期使用仍建议按 SKILL.md 建正式工作区，避免缓存环境碎片化。

uv 完全装不上时，用标准库 venv 手动搭（仅应急，失去 lock 可复现性）：

python -m venv .venv
.venv\Scripts\python.exe -m pip install pandas openpyxl playwright requests
# 此后所有命令用 .venv\Scripts\python.exe 替代 uv run python