wizard

name	wizard
description	生成一个交互式 bash 向导，引导人工用户完成一个手动流程——第三方设置、一次性迁移、A→B 状态转换——打开 URL、捕获值、确认每一步，并写入 .env 文件和 GitHub Actions secrets。
disable-model-invocation	true

Wizard

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

出色的 UX 已经由 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 secret、两者都有、或无处——某些阶段是纯操作），以及 (c) 它是密钥（隐藏输入）还是公开的。

2. 映射每个阶段的路径

对于每个阶段，写出人工用户遵循的精确路径：打开哪个 URL、在那里做什么、某个值在哪里显示、它填入哪个变量——例如"Dashboard → Developers → API keys → Reveal test key → 复制"。当你实际不确定当前 UI 或确切命令时，明确说明并询问用户或查阅文档——永远不要编造可能不存在的步骤。

完成标准： 每个阶段都对应一个陌生人也能遵循的具体操作指引。

3. 编写向导

将 template.sh 复制到目标路径。用每个步骤一个 stage 替换示例阶段，按依赖顺序排列。使用库辅助函数——stage、say/step、open_url、ask/ask_secret、write_env、set_secret/set_var、pause/confirm——并将 TOTAL_STAGES 和 TOTAL_MINUTES 设置为诚实的估算值（这驱动剩余时间显示）。

保持模板设定的标准：在请求输入值之前先打开 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。