Wizard

向导 (Wizard)

向导（Wizard）是一个 Bash 脚本，它能一步步引导人类完成繁琐的手动操作流程——既免去了纯人工操作的枯燥，也省去了每次都要向 AI 重新解释的麻烦。它会打开各个 URL，明确告知点击和复制什么内容，捕获这些值并写入对应的位置（.env、GitHub secrets），在每个阶段进行确认，并显示剩余阶段数。它可以用来配置第三方服务、运行一次性迁移，或将项目从一种状态转换到另一种状态。

template.sh 已经提供了出色的交互体验：分阶段进度显示、确认关卡、跨平台 URL 打开（包括 WSL）、密码隐藏输入、幂等的 .env 更新（upsert）、gh secret/gh variable 写入以及结束时的总结。你的工作只是界定流程范围并编写各个阶段的内容。 STAGES 标记上方的库代码在每个向导中都是完全相同的；保持一致性至关重要：切勿手动修改它。

向导默认是临时性的：为单次运行而构建，保存在临时路径或 scripts/ 目录下，任务完成后即可删除。仅当用户需要将可复用的设置流程保留在仓库中时，才将其提交。

流程

1. 界定操作流程范围

梳理出人类必须执行的每一个手动步骤，以及沿途捕获的每一个值。先阅读仓库代码，不要毫无准备地直接发问：

• 对于环境配置：查看 .env、.env.example、.env.*、README、docker-compose*、框架配置文件以及 .github/workflows/*（其中引用的每个 secrets.* / vars.* 都是向导必须生成的值）。
• 对于迁移或状态转换：确认当前状态、目标状态以及两者之间的不可逆操作。

然后向用户展示按顺序排列的阶段列表以及每个阶段生成的值，并进行确认：用户可能会增加、删除或重新排序。

完成标准： 每个阶段都按顺序命名，并且对于捕获的每个值，你都知道：(a) 人类从何处获取该值；(b) 写入何处（.env、GitHub secret、两者兼有，或无需写入；某些阶段纯粹是操作步骤）；(c) 属于机密（隐藏输入）还是公开值。

2. 梳理各阶段的操作路径

为每个阶段编写人类需要遵循的精确路径：打开哪个 URL、在那里做什么、值显示在什么位置、填充到哪个变量：例如，“Dashboard → Developers → API keys → Reveal test key → 复制”。如果你不确定当前的 UI 界面或具体命令，请如实说明并询问用户或查阅文档：切勿凭空捏造可能不存在的步骤。

完成标准： 每个阶段都能转化为任何陌生人都能照着执行的具体指导。

3. 编写向导脚本

将 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 中的每个值都被捕获并写入了指定位置，且每个 set_secret 名称都与 CI 中的 secrets.* 引用完全匹配。
• 告知用户如何运行该脚本。如果这是一个可复用的设置流程，将其提交并链接到 README 中，以便后续人员直接运行脚本，而无需再询问 AI。