向导

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

愉悦的 UX 已由 [template.sh](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 → copy”。如果你确实不知道当前 UI 或确切命令，请说明这一点，并询问用户或查阅文档：绝不要发明可能不存在的步骤。

完成条件： 每个阶段都能追溯到陌生人可以遵循的具体指令。

3. 编写向导

将 template.sh 复制到目标路径。用一个 stage 替换示例阶段，每个步骤对应一个 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。