wizard

向导

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

精细的用户体验已由 template.sh 解决——逐阶段显示进度、确认关卡、跨平台打开 URL（包括 WSL）、隐藏输入 secrets、以幂等方式更新 .env、通过 gh secret/gh variable 写入，以及最终摘要。你的工作只是界定流程范围并编写各个阶段。 STAGES 标记上方的库在所有向导中都完全相同；这种一致性正是重点——切勿手动编辑它。

向导默认是临时的——用于单次执行，保存在临时路径或 scripts/ 中，并在工作完成后删除。只有当用户希望在仓库中保留一套可重复使用的设置流程时，才将向导提交到仓库。

流程

1. 界定流程范围

梳理用户需要执行的所有手动步骤，以及流程中会捕获的所有值。先阅读仓库——不要凭空提问：

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

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

准备就绪的标准： 所有阶段均已按顺序命名；对于每个捕获的值，你都知道 (a) 用户从哪里获取该值，(b) 该值要写入哪里（.env、GitHub secret、两者，或不写入任何位置——有些阶段只是执行操作），以及 (c) 该值是否为 secret（需要隐藏输入）或公开值。

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

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

准备就绪的标准： 每个阶段都能转化为具体指示，让陌生人也能照着完成。

3. 编写向导

将 template.sh 复制到目标路径。将示例阶段替换为按依赖顺序排列的 stage 步骤。使用库中的 helper——stage、say/step、open_url、ask/ask_secret、write_env、set_secret/set_var、pause/confirm——并将 TOTAL_STAGES 设为你编写的阶段数。

保持模板确立的标准：先打开 URL，再索取对应的值；所有 secret 都使用 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。