izittmarvin/agent-skills-zh/wizard

Wizard

Wizard 是一段 bash 脚本，逐步引导人完成手工做起来繁琐、每次向 AI 重新解释也繁琐的操作。它打开每个 URL，说明要点击和复制什么，捕获得到的值，写入应去的位置（.env、GitHub secrets），每个阶段都确认，并显示还剩几个阶段。它可以配置第三方服务、跑一次性迁移，或把项目从一种状态迁到另一种状态。

令人省心的交互已经由 template.sh 解决：分阶段进度、确认门、跨平台打开 URL（含 WSL）、隐藏输入密钥、幂等写入 .env、gh secret / gh variable 写入，以及结束摘要。你的工作只是界定流程，并编写各个阶段。 STAGES 标记以上的库在每个 wizard 中都相同；这种一致性本身就是目的：绝不要手改那一段。

Wizard 默认是一次性的：为单次运行构建，保存到 scratch 或 scripts/ 路径，事情做完后删除。只有用户希望仓库里留下可重复的开通路径时，才提交它。

流程

1. 界定流程

弄清人必须亲手完成的每一步，以及沿途要捕获的每个值。先读仓库，不要空问：

• 开通类：.env、.env.example、.env.*、README、docker-compose*、框架配置，以及 .github/workflows/*（每一处 secrets.* / vars.* 引用，都是 wizard 必须产出的值）。
• 迁移或切换类：当前状态、目标状态，以及两者之间不可逆的动作。

然后向用户展示有序的阶段列表和每个阶段产出的值，并确认：他们可以增加、删除或重排。

完成标准： 每个阶段都已按顺序列出名称；对每个捕获值都知道 (a) 人从哪里拿到它，(b) 写到哪里（.env、GitHub secret、两者都写，或不写入；有的阶段只是动作），以及 (c) 它是密钥（隐藏输入）还是公开值。

2. 画出每个阶段的路径

为每个阶段写出人要走的精确路径：打开哪个 URL、在那里做什么、值显示在哪里、填入哪个变量。例如 “Dashboard → Developers → API keys → Reveal test key → copy”。你并不真正知道当前界面或确切命令时，如实说明，询问用户或查阅文档：绝不要编造可能不存在的步骤。

完成标准： 每个阶段都能追溯到陌生人也能照做的具体说明。

3. 编写 wizard

把 template.sh 复制到目标路径。用按依赖顺序排列的 stage 替换示例阶段，每步一个。使用库提供的辅助函数：stage、say/step、open_url、ask/ask_secret、write_env、set_secret/set_var、pause/confirm。把 TOTAL_STAGES 设成你写的阶段数。

守住模板设定的标准：先打开 URL 再索要其中的值；密钥一律用 ask_secret；每个要持久化的值都走 write_env；只有 CI 真正需要的值才 set_secret；任何不可逆动作前都 confirm。每个 stage 会清屏，只留下当前步骤：一个阶段只做一件聚焦的事，避免人需要的内容滚出屏幕。不要改动标记以上的库。

4. 校验并交给用户

• 运行 bash -n <script>；环境有 shellcheck 时也跑一遍。
• chmod +x <script>。
• 不要自己从头到尾跑它：它会打开浏览器并卡在人工输入上。改为静态核对：第 1 步列出的每个值都被捕获，并落到第 1 步声明的位置；每个 set_secret 名称都与 CI 中的 secrets.* 引用完全一致。
• 告诉用户如何运行。若这是可重复的开通路径，提交脚本并从 README 链接过去，让下一个人跑脚本，而不是再问一遍 AI。