StudioLift/skills/yt-download-place/SKILL.md

name, description

name	description
yt-download-place	在当前目录或指定路径创建 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 可用

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
New-Item -ItemType Directory -Force "<place>/assets", "<place>/data" | Out-Null

# Git Bash / zsh
mkdir -p "<place>/assets" "<place>/data"

写入三个文件（已存在则跳过，不覆盖）：

pyproject.toml

[project]
name = "yt-download-place"
version = "0.1.0"
requires-python = ">=3.10"

依赖不写在这里：四个必需包由步骤 3 的 uv add 统一补齐（单一来源，已存在 pyproject.toml 的工作区同样适用）。

.gitignore

# Python-generated files
__pycache__/
*.py[oc]
build/
dist/
wheels/
*.egg-info

# Virtual environments
.venv
.profile
bundle*.json

# Data folder
data/

README.md

# 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> 下执行：

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：验证并交付

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。