Wizard 是一个生成 bash 交互式向导的技能。所谓向导，是一个逐步引导真人完成手动流程的 bash 脚本；这类流程手工做很繁琐，每次向 AI 重新讲解也同样繁琐。向导会逐个打开 URL，明确说明点击和复制的位置，捕获填写的值，把它们写到该去的地方（.env、GitHub secrets），在每个阶段进行确认，并显示还剩多少阶段。它可用于配置第三方服务、执行一次性迁移，或把项目从一个状态迁移到另一个状态。
良好的交互体验已由 template.sh 解决：分阶段进度、确认关卡、跨平台打开 URL（包括 WSL）、隐藏式密钥输入、幂等的 .env 写入更新、gh secret/gh variable 写入，以及结束摘要。使用者的工作只是界定流程范围并编写各阶段。STAGES 标记之上的库在每个向导中都相同，这种一致性正是要点：永远不要手动编辑它。
向导默认是临时的：为单次运行而构建，保存到临时或 scripts/ 路径，任务完成后删除。只有当用户希望保留一条应存在于仓库中的可重复配置路径时，才提交它。
使用流程
- 界定流程范围
梳理出真人必须执行的每一个手动步骤，以及过程中捕获的每一个值。先阅读仓库，不要凭空提问：
对于配置类：.env、.env.example、.env.、README、docker-compose、框架配置，以及 .github/workflows/（每一处 secrets. / vars.* 引用都是向导必须产出的值）。
对于迁移或状态转换：当前状态、目标状态，以及两者之间不可逆的操作。
然后向用户展示有序的阶段列表及每个阶段产出的值，并确认：用户可以添加、删减或重排。
完成标准：每个阶段都按顺序命名；对于每个捕获的值，你都知道 (a) 真人从哪里获取它，(b) 它写到哪里（.env、GitHub secret、两者，或都不写；有些阶段只是纯操作），(c) 它是密钥（隐藏输入）还是公开值。
- 规划每个阶段的路径
为每个阶段写出真人遵循的精确路径：打开哪个 URL、在那里做什么、值显示在哪里、填入哪个变量，例如“Dashboard → Developers → API keys → Reveal test key → copy”。对于你并不真正了解当前 UI 或确切命令的地方，要明确说明并向用户询问或查阅文档：绝不要编造可能不存在的步骤。
完成标准：每个阶段都能追溯到陌生人也能照做的具体说明。
- 编写向导
把 template.sh 复制到目标路径。用每个步骤一个阶段替换示例阶段，按依赖顺序排列。使用库中的辅助函数：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；在任何不可逆操作之前先确认。每个阶段都清屏，只显示当前步骤：让一个阶段只聚焦一项任务，避免用户需要的内容滚出屏幕。不要改动标记之上的库。
- 验证与交付
bash -n <script>；如可用则运行 shellcheck。
chmod +x <script>。
不要自己端到端运行：它会打开浏览器并阻塞等待人工输入。改为静态追踪：第 1 步中的每个值都被捕获并落到第 1 步指定的地方，每个 set_secret 名称都精确匹配 CI 中的 secrets.* 引用。
ENV_FILE 应被 gitignore：当它未被忽略时，库的 write_env 会在首次写入前询问；但把 ENV_FILE 设为非默认路径的向导必须指向仓库忽略的文件。
告诉用户如何运行它。如果这是一条可重复的配置路径，就提交它并从 README 链接，让下一个人运行脚本而不是询问 AI。