# 技能安装说明（Windows，多 agent）

把本项目 `skills\` 下的技能一键安装到各 agent 的用户级技能目录，安装后在任意项目的对话中都可触发。当前支持：

| `-Agent` 参数 | 目标目录 | 适用 agent |
|---|---|---|
| `trae-cn`（默认） | `%USERPROFILE%\.trae-cn\skills\` | Trae CN / Trae SOLO |
| `zcode` | `%USERPROFILE%\.zcode\skills\` | ZCode CLI |
| `all` | 上面全部目录 | 所有已登记 agent |

新增其他 agent 时在 `scripts\install-skills.ps1` 顶部 `$AgentTargets` 表里登记一行即可。

## 技能清单

| 技能 | 用途 |
|---|---|
| `uv-env-setup` | 用 uv 准备并维护 Python 运行环境（项目环境 / 单脚本 PEP 723 模式） |
| `yt-studio-url-builder` | 根据需求清单（CSV/Excel）批量生成 YouTube Studio 内容管理器 explore URL |
| `yt-studio-groupid-lookup` | 把一批群组名批量解析为 entity_id（groupId），并标注归属的内容所有者 |
| `youtube-studio-csv-download` | 复用已登录浏览器会话，脚本化下载 YouTube Studio 分析 CSV（zip） |

## 安装（傻瓜式）

双击运行：

```
scripts\install-skills.bat
```

看到 `全部安装成功` 及逐项 `[安装]` 即完成，按任意键关闭窗口。**默认安装全部技能到 trae-cn**；同名旧版自动备份到目标目录旁的 `skills-backup\`。

命令行等价方式（PowerShell / cmd 均可）：

```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-skills.ps1
```

### 可选参数（bat 与 ps1 均支持）

| 参数 | 作用 |
|---|---|
| `-Agent <名>` | 目标 agent：`trae-cn`（默认）/ `zcode` / `all` |
| `-Skills <名1,名2>` | 只安装指定的技能（按技能文件夹名，不区分大小写）；缺省=全部 |
| `-DryRun` | 只预览将安装/覆盖/备份的技能，不实际复制 |

示例：

```powershell
# 装到 ZCode
scripts\install-skills.bat -Agent zcode

# 全部目标只装这两个技能
scripts\install-skills.bat -Agent all -Skills yt-studio-url-builder,youtube-studio-csv-download

# 预览
scripts\install-skills.bat -Agent trae-cn -DryRun
```

## 脚本做了什么

1. 扫描项目 `skills\` 下每个包含 `SKILL.md` 的子目录（即可安装技能；缺 `SKILL.md` 的目录会提示「跳过」）。
2. 解析 `-Agent` 得到一个或多个目标目录；默认全部技能、-trae-cn。
3. 若带 `-Skills` 则只装指定的，并提示未找到的技能名。
4. 读取每个 `SKILL.md` 顶部的 `name`，与文件夹名比对——不一致或缺 `name` 时打警告（避免技能名歧义/旧名残留）。
5. 逐个复制到各目标目录；目标已存在同名技能时，先把旧版移动到该目标旁的 `skills-backup\<技能名>-<时间戳>\` 再装新版，不直接覆盖。
6. 逐个校验 SKILL.md 落盘并打印 `[安装]` / `[FAIL]`；有失败退出码 2。

安全性：脚本只处理本项目 `skills\` 中出现的技能，不会删除或改动目标技能目录下的其他技能；不修改任何 agent 配置文件。

## 各 agent 的差异与注意事项

- **Trae CN**：用户级技能目录即上表；重启 Trae CN 或新建会话后生效。
- **ZCode**：技能落在 `~\.zcode\skills\` 后由 ZCode 自动发现（本机会话中已验证）；新建会话后生效。zcode 环境里的同名工程技能可能遮蔽用户级技能，排查时注意优先级。
- **终端方言**：两个 agent 都可能在 PowerShell 或 Git Bash 里执行命令。所有 SKILL.md 的示例统一用正斜杠路径 + 引号写法，两边通用；uv-env-setup 提供 PATH 刷新的两种方言写法。
- **通用兜底**：无论哪个 agent，跑脚本前都先按 `uv-env-setup` 技能确认 uv 分支（项目环境 / 单脚本模式 / python -m uv 回退）。

## 验证

1. 重启对应 agent（或新建会话）。
2. 对话中直接提及技能名或相关意图，例如：
   - 「帮我准备环境」→ `uv-env-setup`
   - 「根据这份清单批量生成 Studio URL」→ `yt-studio-url-builder`
   - 「用我的 Chrome 会话下载这份分析 CSV」→ `youtube-studio-csv-download`

## 更新与卸载

- **更新**：项目技能有改动后，重新运行安装脚本（可加 `-Agent all` 同步所有目标；旧版自动备份）。
- **回滚**：把 `<目标目录旁>\skills-backup\<技能名>-<时间戳>\` 整个文件夹复制回对应技能目录。
- **卸载**：删除对应技能目录下的技能文件夹。
- **清理备份**：确认新版可用后，删除 skills-backup 整个文件夹。

## 常见问题

- **双击 bat 闪退**：在 PowerShell 中手动运行 `scripts\install-skills.bat` 查看报错；最常见原因是 `install-skills.ps1` 没有和 bat 放在同一目录。
- **PowerShell 执行策略受限**：bat 已带 `-ExecutionPolicy Bypass`；若组策略仍拦截，以管理员身份运行。
- **技能装了但不触发**：需重启对应 agent 或新建会话后生效；先用 `-DryRun` 确认装到了你所用 agent 的目录。
- **中文输出乱码**：`install-skills.ps1` 必须保持 UTF-8 with BOM 编码（重新编辑保存时注意）。

## 注意

- 运行时依赖不随技能安装：脚本型技能的 Python 依赖由两层机制承接——项目根 `pyproject.toml`（项目环境）或脚本头部 PEP 723 内联声明（单脚本模式），首次使用按 `uv-env-setup` 技能执行即可。
- 安装脚本仅支持 Windows（路径与命令均按 Windows 编写）。