81 lines
4.1 KiB
Markdown
81 lines
4.1 KiB
Markdown
# 技能安装说明（Windows）
|
||
|
||
把本项目 `skills\` 下的技能一键安装到 Trae CN 的用户级技能目录 `%USERPROFILE%\.trae-cn\skills\`，安装后在任意项目的对话中都可触发。
|
||
|
||
## 技能清单
|
||
|
||
| 技能 | 用途 |
|
||
|---|---|
|
||
| `uv-env-setup` | 用 uv 准备并维护本项目 Python 运行环境（`uv sync` / `uv run`） |
|
||
| `yt-studio-url-builder` | 根据需求清单（CSV/Excel）批量生成 YouTube Studio 内容管理器 explore URL |
|
||
| `youtube-studio-csv-download` | 复用已登录浏览器会话，脚本化下载 YouTube Studio 分析 CSV（zip） |
|
||
| `yt-studio-groupid-lookup` | 把一批群组名批量解析为 entity_id（groupId），并标注归属的内容所有者 |
|
||
|
||
## 安装（傻瓜式）
|
||
|
||
双击运行：
|
||
|
||
```
|
||
scripts\install-skills.bat
|
||
```
|
||
|
||
看到 `全部安装成功` 及逐项 `[OK]` 即完成，按任意键关闭窗口。**默认安装全部技能**；同名旧版自动备份到 `~/.trae-cn/skills-backup/`。
|
||
|
||
命令行等价方式（PowerShell / cmd 均可）：
|
||
|
||
```powershell
|
||
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-skills.ps1
|
||
```
|
||
|
||
### 可选参数（bat 与 ps1 均支持）
|
||
|
||
| 参数 | 作用 |
|
||
|---|---|
|
||
| `-Skills <名1,名2>` | 只安装指定的技能（按技能文件夹名，不区分大小写）；缺省=全部 |
|
||
| `-DryRun` | 只预览将安装/覆盖/备份的技能，不实际复制 |
|
||
|
||
示例：
|
||
|
||
```powershell
|
||
scripts\install-skills.bat -Skills yt-studio-url-builder,youtube-studio-csv-download
|
||
scripts\install-skills.bat -DryRun
|
||
```
|
||
|
||
## 脚本做了什么
|
||
|
||
1. 扫描项目 `skills\` 下每个包含 `SKILL.md` 的子目录（即可安装技能；缺 `SKILL.md` 的目录会提示「跳过」）。
|
||
2. **默认安装全部技能**；若带 `-Skills` 则只装指定的，并提示未找到的技能名。
|
||
3. 读取每个 `SKILL.md` 顶部的 `name`，与文件夹名比对——不一致或缺 `name` 时打警告（避免技能名歧义/旧名残留）。
|
||
4. 逐个复制到 `%USERPROFILE%\.trae-cn\skills\`；目标已存在同名技能时，先把旧版移动到 `%USERPROFILE%\.trae-cn\skills-backup\<技能名>-<时间戳>\` 再装新版，不直接覆盖。
|
||
5. 逐个校验并打印 `[OK]` / `[FAIL]`；全部成功退出码 0，失败退出码 2。
|
||
6. 带 `-DryRun` 时只打印将安装/覆盖/备份的技能清单，不做任何修改。
|
||
|
||
安全性：脚本只处理本项目 `skills\` 中出现的技能，不会删除或改动 `.trae-cn\skills\` 下的其他技能；不修改任何 Trae CN 配置文件。
|
||
|
||
## 验证
|
||
|
||
1. 重启 Trae CN（或新建会话）。
|
||
2. 对话中直接提及技能名或相关意图，例如：
|
||
- 「帮我准备环境」→ `uv-env-setup`
|
||
- 「根据这份清单批量生成 Studio URL」→ `yt-studio-url-builder`
|
||
- 「用我的 Chrome 会话下载这份分析 CSV」→ `youtube-studio-csv-download`
|
||
|
||
## 更新与卸载
|
||
|
||
- **更新**：项目技能有改动后，重新双击 `install-skills.bat`（旧版自动备份）。
|
||
- **回滚**：把 `%USERPROFILE%\.trae-cn\skills-backup\<技能名>-<时间戳>\` 整个文件夹复制回 `%USERPROFILE%\.trae-cn\skills\<技能名>\`。
|
||
- **卸载**：删除 `%USERPROFILE%\.trae-cn\skills\` 下对应技能文件夹。
|
||
- **清理备份**：确认新版可用后，删除 `%USERPROFILE%\.trae-cn\skills-backup\` 整个文件夹。
|
||
|
||
## 常见问题
|
||
|
||
- **双击 bat 闪退**：在 PowerShell 中手动运行 `scripts\install-skills.bat` 查看报错；最常见原因是 `install-skills.ps1` 没有和 bat 放在同一目录。
|
||
- **PowerShell 执行策略受限**：bat 已带 `-ExecutionPolicy Bypass`；若组策略仍拦截，以管理员身份运行。
|
||
- **技能装了但不触发**：需重启 Trae CN 或新建会话后生效；确认对话窗口正常加载。
|
||
- **中文输出乱码**：`install-skills.ps1` 必须保持 UTF-8 with BOM 编码（重新编辑保存时注意）。
|
||
|
||
## 注意
|
||
|
||
- 运行时依赖不随技能安装：两个脚本型技能的 Python 依赖（pandas、openpyxl、playwright）由项目根 `pyproject.toml` 统一管理，首次使用按 `uv-env-setup` 技能执行 `uv sync` 即可。
|
||
- 安装脚本仅支持 Windows（路径与命令均按 Windows 编写）。
|