131 lines
4.8 KiB
Markdown
131 lines
4.8 KiB
Markdown
---
|
||
name: "yt-download-place"
|
||
description: "在当前目录或指定路径创建 uv 项目工作区（git 仓库 + pyproject.toml + .venv + assets + data + .gitignore + uv.lock），作为 YouTube 下载类技能脚本的统一运行环境。当用户要求准备工作区/下载目录/新建 uv 项目、为 yt 技能装依赖（pandas/openpyxl/playwright/requests）备环境，或 uv/.venv 报错时使用。"
|
||
---
|
||
|
||
# yt-download-place：下载工作区
|
||
|
||
在目标目录落地一套标准 uv 项目结构，让其他 yt 技能（url-builder、groupid-lookup、csv-download）的脚本统一以 `uv run python <脚本>` 运行。一个工作区承载一批下载任务：`assets/` 存中间数据（需求清单、URL 清单、解析产物），`data/` 存最终下载数据（不进 git）。
|
||
|
||
目标目录 = 用户指定路径，未指定则用当前目录；目录不存在时先创建。目标结构：
|
||
|
||
```
|
||
<place>/
|
||
├── .git/
|
||
├── .venv/
|
||
├── assets/
|
||
├── data/
|
||
├── .gitignore
|
||
├── pyproject.toml
|
||
├── README.md
|
||
└── uv.lock
|
||
```
|
||
|
||
## 步骤 1：确认 uv 可用
|
||
|
||
```powershell
|
||
uv --version
|
||
```
|
||
|
||
失败时按顺序尝试，命中即停：
|
||
|
||
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 <子命令>` 改为 `python -m uv <子命令>`，其余不变。
|
||
3. **pip 兜底**：`pip install uv` 后回到第 2 条（pip 装的随当前 Python 立即可用）。
|
||
|
||
**完成判据**：`uv --version` 或 `python -m uv --version` 打印版本号。
|
||
|
||
## 步骤 2：搭建工作区骨架
|
||
|
||
在 `<place>` 下创建两个数据目录（两种 shell 写法二选一；路径统一正斜杠 + 引号，两边通用）：
|
||
|
||
```powershell
|
||
# PowerShell
|
||
New-Item -ItemType Directory -Force "<place>/assets", "<place>/data" | Out-Null
|
||
```
|
||
|
||
```bash
|
||
# Git Bash / zsh
|
||
mkdir -p "<place>/assets" "<place>/data"
|
||
```
|
||
|
||
写入三个文件（已存在则跳过，不覆盖）：
|
||
|
||
**pyproject.toml**
|
||
|
||
```toml
|
||
[project]
|
||
name = "yt-download-place"
|
||
version = "0.1.0"
|
||
requires-python = ">=3.10"
|
||
```
|
||
|
||
依赖不写在这里：四个必需包由步骤 3 的 `uv add` 统一补齐（单一来源，已存在 pyproject.toml 的工作区同样适用）。
|
||
|
||
**.gitignore**
|
||
|
||
```gitignore
|
||
# Python-generated files
|
||
__pycache__/
|
||
*.py[oc]
|
||
build/
|
||
dist/
|
||
wheels/
|
||
*.egg-info
|
||
|
||
# Virtual environments
|
||
.venv
|
||
.profile
|
||
bundle*.json
|
||
|
||
# Data folder
|
||
data/
|
||
```
|
||
|
||
**README.md**
|
||
|
||
```markdown
|
||
# yt-download-place
|
||
|
||
YouTube 下载工作区：assets/ 存中间数据，data/ 存下载数据（不入 git）。
|
||
技能脚本一律 `uv run python <脚本>` 运行。
|
||
```
|
||
|
||
**git 仓库**：`<place>/.git` 不存在时执行 `git init`；已是仓库则复用。
|
||
|
||
**完成判据**：`<place>` 下存在 `assets\`、`data\`、`pyproject.toml`、`.gitignore`、`README.md`、`.git`，且原有文件未被改动。
|
||
|
||
## 步骤 3：补齐依赖并同步环境
|
||
|
||
`<place>` 下执行：
|
||
|
||
```powershell
|
||
uv add pandas openpyxl playwright requests
|
||
```
|
||
|
||
- 必需包固定四件：`pandas`、`openpyxl`、`playwright`、`requests`——yt 技能脚本（url-builder、groupid-lookup、csv-download、auth-prep）运行的全部依赖。
|
||
- `uv add` 幂等：已满足的包直接跳过，缺失的写入 `pyproject.toml` 与 `uv.lock` 并同步 `.venv\`；首次准备自动创建 `.venv\`，本机无兼容 Python 时自动下载托管 Python（≥3.10）。
|
||
- 复用已有 `pyproject.toml`（非本模板）的工作区同样适用：只追加缺失的这四个包，其余依赖不动。
|
||
- `uv run` 会隐式同步；显式 `uv add` 是为了把缺包/依赖冲突一次性暴露。
|
||
|
||
**完成判据**：退出码 0，`<place>` 下出现 `.venv\` 与 `uv.lock`，且 `pyproject.toml` 的 `dependencies` 含这四个包。
|
||
|
||
## 步骤 4：验证并交付
|
||
|
||
```powershell
|
||
uv run python -c "import pandas, openpyxl, playwright, requests; print('env OK')"
|
||
```
|
||
|
||
**完成判据（全局）**：打印 `env OK`。向用户报告工作区路径，此后约定：
|
||
|
||
- 其他技能脚本都在 `<place>` 下用 `uv run python <脚本>` 执行；不裸调 `python`、不手动激活 venv、不向全局 pip 装依赖。
|
||
- 中间数据写 `<place>/assets/`，下载数据写 `<place>/data/`。
|
||
- 新增依赖：`uv add <包>`（唯一入口，禁止 pip 直装绕过 lock）。
|
||
|
||
## 排查
|
||
|
||
uv 不识别、国内镜像加速、`No solution found`、`.venv` 损坏重建、playwright 浏览器下载慢、无 uv 手动兜底等，查 [references/troubleshooting.md](references/troubleshooting.md)。
|