wizard

Wizard

Wizard 是一个 Bash 脚本，会逐步引导用户完成手动操作：这些操作手工执行起来很繁琐，每次都向 AI 重新解释也很麻烦。它会打开每个 URL，准确说明要点击和复制什么，收集相应的值，将它们写入正确的位置（.env、GitHub 密钥），在每个阶段进行确认，并显示还剩多少个阶段。它可以配置第三方服务、执行一次性迁移，或将项目从一种状态转换到另一种状态。

template.sh 已经解决了出色的用户体验问题——逐阶段显示进度、设置确认关卡、跨平台打开 URL（包括 WSL）、隐藏密钥输入、幂等地更新 .env、写入 gh secret/gh variable，以及最后的总结。你只需确定操作范围并编写各个阶段。 STAGES 标记上方的库在每个 wizard 中都完全相同；保持一致正是关键所在——切勿手动编辑。

Wizard 默认是临时的——为单次运行而创建，保存到临时目录或 scripts/ 路径中，任务完成后删除。只有当用户希望在仓库中保留可重复使用的设置流程时，才提交它。

流程

1. 确定操作范围

理清用户必须执行的每个手动步骤，以及过程中需要收集的每个值。先阅读仓库，不要一上来就询问：

• 对于设置：.env、.env.example、.env.*、README、docker-compose*、框架配置，以及 .github/workflows/*（每个 secrets.* / vars.* 引用都是 wizard 必须生成的值）。
• 对于迁移或转换：当前状态、目标状态，以及两者之间不可逆的操作。

然后向用户展示有序的阶段列表，以及每个阶段会生成的值，并进行确认——用户可能会添加、删除或调整顺序。

完成标准： 每个阶段都已按顺序命名；对于每个收集的值，你都知道（a）用户从哪里获取它，（b）它会写入哪里（.env、GitHub 密钥、两者，或不写入任何地方——有些阶段只执行操作），以及（c）它是否为机密（是否需要隐藏输入）。

2. 梳理每个阶段的操作路径

为每个阶段写出用户需要遵循的确切路径：要打开哪个 URL、在页面上要做什么、值显示在哪里、它对应哪个变量——例如：“Dashboard → Developers → API keys → Reveal test key → 复制”。如果你并不确定当前界面或确切命令，就说明情况并询问用户或查阅文档——绝不要编造可能不存在的步骤。

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

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。

---

改编自 mattpocock/skills，MIT © 2026 Matt Pocock。复制此文件时请保留此行。