feat(scripts): 添加 PEP 723 脚本元数据并修复 HTTP/2 伪头过滤问题

- 为 build_studio_urls.py 和 lookup_groups.py 添加 PEP 723 依赖声明
- 修复 HTTP/2 伪头导致 requests 抛 InvalidHeader 的问题
- 添加 CDP 端口连通性预检查及启动指引

docs/install-skills.md

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