Sidney Zhang
9020752eed
- 为 build_studio_urls.py 和 lookup_groups.py 添加 PEP 723 依赖声明 - 修复 HTTP/2 伪头导致 requests 抛 InvalidHeader 的问题 - 添加 CDP 端口连通性预检查及启动指引
103 lines
5.4 KiB
Markdown
103 lines
5.4 KiB
Markdown
# 技能安装说明（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 编写）。
|