Files

Sidney Zhang 9020752eed

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

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

2026-08-27 13:33:34 +08:00

5.4 KiB

Raw Blame History

技能安装说明（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 -NoProfile -ExecutionPolicy Bypass -File scripts\install-skills.ps1

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

参数	作用
`-Agent <名>`	目标 agent：`trae-cn`（默认）/ `zcode` / `all`
`-Skills <名1,名2>`	只安装指定的技能（按技能文件夹名，不区分大小写）；缺省=全部
`-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

脚本做了什么

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

验证

重启对应 agent（或新建会话）。
对话中直接提及技能名或相关意图，例如：
- 「帮我准备环境」→ 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 编写）。

5.4 KiB Raw Blame History Unescape Escape