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 → 复制"。如果你并不确定当前的界面或确切命令，请直接说明，并询问用户或查阅文档：切勿编造可能并不存在的步骤。

完成标准： 每个阶段都能对应到陌生人也能照着执行的具体说明。

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；set_secret 只用于 CI 实际需要的值；在任何不可逆操作之前使用 confirm。每个 stage 都会清屏，因此屏幕上只显示当前步骤：每个阶段只专注一项任务，确保用户需要的内容不会滚动消失。不要修改标记上方的库代码。

4. 验证并交付

• 运行 bash -n <script>；如可用，运行 shellcheck。
• 运行 chmod +x <script>。
• 不要自行端到端运行它：它会打开浏览器并阻塞等待人工输入。改为静态检查：确认步骤 1 中的每个值都已被捕获并写入步骤 1 指定的位置，并且每个 set_secret 的名称都与 CI 中的 secrets.* 引用完全一致。
• 告知用户如何运行它。如果它是一条可重复执行的初始化路径，请将其提交，并在 README 中链接，以便下一位使用者直接运行脚本，而不必再询问 AI。