向导
向导 是一个 bash 脚本，它逐步引导人类完成一个手动流程——这个流程手动做既繁琐，每次都要重新向 AI 解释也令人厌烦。它会打开每个 URL，精确说明要点击和复制的内容，捕获这些值，将它们写入正确的位置（.env、GitHub 密钥），在每个阶段都进行确认，并显示剩余阶段数。它可能配置第三方服务、运行一次性迁移，或让项目从一个状态过渡到另一个状态。
令人愉悦的用户体验已经由 template.sh 解决：分阶段进度、确认关卡、跨平台 URL 打开（包括 WSL）、隐藏输入秘密、幂等的 .env 更新、gh secret/gh variable 写入，以及结束摘要。你的工作只是确定流程的范围并编写它的各个阶段。 每个向导中 STAGES 标记之上的库代码都是相同的；这种一致性正是关键：永远不要手动编辑它。
默认情况下，向导是临时的：为一次运行而构建，保存到临时目录或 scripts/ 路径，任务完成后删除。只有当用户希望有一个可重复的设置路径且该路径应存在于仓库中时，才将其提交。
流程
1. 确定流程范围
列出每个手动步骤——人类必须执行且每个被捕获的值都在其中。首先阅读仓库，不要凭空提问：
- 对于设置：
.env、.env.example、.env.*、README、docker-compose*、框架配置以及.github/workflows/*（每个secrets.*/vars.*引用都是向导必须产生的值）。 - 对于迁移或过渡：当前状态、目标状态以及两者之间不可逆的操作。
然后向用户展示排序后的阶段列表以及每个阶段产生的值，并确认：用户可以添加、删除或重新排序。
完成条件： 每个阶段都有名称且按顺序排列，对于每个被捕获的值，你知道 (a) 人类从哪里获取它，(b) 它写入到哪里（.env、GitHub 密钥、两者都写，或不写；有些阶段只是纯操作），以及 (c) 它是否是秘密（隐藏输入）还是公开的。
2. 规划每个阶段的路径
为每个阶段编写人类遵循的精确路径：要打开哪个 URL，在那里做什么，值在哪里显示，它填充哪个变量：例如“仪表板 → 开发者 → API 密钥 → 显示测试密钥 → 复制”。如果你实际上不知道当前的 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。