wizard

向导

向导（Wizard） 是一个 bash 脚本，逐步引导人类完成手动流程——这些流程手动做很繁琐，每次重新向 AI 解释也很麻烦。它会打开每个 URL，精确说明要点击什么和复制什么，捕获值，将其写入正确的位置（.env、GitHub secrets），在每个阶段确认，并显示剩余阶段数。它可能配置第三方服务、运行一次性迁移、或把项目从一个状态迁移到另一个状态。

便捷的 UX 已经由 template.sh 解决——分阶段显示进度、确认关卡、跨平台 URL 打开（含 WSL）、隐藏密文输入、幂等的 .env 写入、gh secret/gh variable 写入，以及一个结束汇总。你的工作只是界定流程范围并编写其阶段。 每个向导中 STAGES 标记上方的库代码都是相同的——这种一致性正是关键所在，永远不要手动编辑它。

向导默认是临时的——为一次运行而创建，保存在 scratch 或 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 → copy"。如果你不确定当前 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 中的每个值都被捕获并写入步骤 1 指定的位置，并且每个 set_secret 名称精确匹配 CI 中的 secrets.* 引用。
• 告诉用户如何运行它。如果这是一个可重复的设置路径，提交它并在 README 中链接，这样下一个人就能直接运行脚本，而不是求助 AI。