wizard

name	wizard
description	生成交互式 Bash wizard，引导真人完成手动流程，例如第三方服务配置、一次性迁移或 A→B 状态转换；过程中打开 URL、捕获值、确认每一步，并写入 .env 文件和 GitHub Actions secrets。
disable-model-invocation	true

Wizard

Wizard 是一个 Bash script，逐步引导真人完成手动流程。此类流程由人工执行很繁琐，每次重新向 AI 解释同样麻烦。Wizard 会打开每个 URL，明确说明需要点击和复制的内容，捕获所需值，把它们写入正确位置（.env、GitHub secrets），在每个阶段进行确认，并显示剩余工作量。它可以配置第三方服务、执行一次性迁移，或把项目从一种状态转换到另一种状态。

完善的使用体验已经由 template.sh 处理：带剩余时间的进度显示、confirmation gates、跨平台 URL 打开（包括 WSL）、隐藏式 secret 输入、幂等的 .env upsert、gh secret/gh variable 写入，以及结束摘要。你的工作只有两项：界定流程范围，并编写各阶段内容。 STAGES 标记上方的 library 在所有 wizard 中完全一致；这种一致性本身就是目标，绝对不要手动修改它。

Wizard 默认是临时产物：为一次运行而创建，保存到 scratch 或 scripts/ 路径，任务完成后删除。只有当用户希望在仓库中保留一条可重复执行的配置路径时，才提交该脚本。

流程

1. 界定操作范围

确定真人必须执行的每个手动步骤，以及过程中需要捕获的每个值。先阅读仓库，不要在缺乏上下文时直接询问：

• 对于配置流程：读取 .env、.env.example、.env.*、README、docker-compose*、framework config 和 .github/workflows/*。其中每个 secrets.* / vars.* 引用都代表 wizard 必须生成的值。
• 对于迁移或状态转换：确认当前状态、目标状态，以及两者之间不可逆的操作。

随后向用户展示按顺序排列的 stages，以及每个 stage 产生的值，并请求确认。用户可以添加、删除或调整顺序。

完成条件： 每个 stage 都已按顺序命名；对于每个需要捕获的值，你都知道：(a) 真人从哪里取得它，(b) 写到哪里（.env、GitHub secret、两者都写，或不写入任何位置——部分 stages 只是执行动作），(c) 它是 secret（隐藏输入）还是 public。

2. 绘制每个 stage 的操作路径

为每个 stage 写出真人需要遵循的精确路径：打开哪个 URL、在那里执行什么、值显示在哪里、填入哪个变量。例如：“Dashboard → Developers → API keys → Reveal test key → copy”。你不了解当前 UI 或确切命令时，明确说明并询问用户，或查阅文档；不得编造可能不存在的步骤。

完成条件： 每个 stage 都有一组陌生人也能照着完成的具体指令。

3. 编写 wizard

将 template.sh 复制到目标路径。删除示例 stage，按依赖顺序为每个步骤添加一个 stage。使用 library 提供的 helpers：stage、say/step、open_url、ask/ask_secret、write_env、set_secret/set_var、pause/confirm。为 TOTAL_STAGES 和 TOTAL_MINUTES 设置诚实的估算值，它们用于计算剩余时间。

遵守 template 设定的质量标准：先打开 URL，再询问对应值；secret 一律使用 ask_secret；所有需要持久化的值都通过 write_env 写入；只有 CI 真正需要的值才调用 set_secret；执行任何不可逆操作前调用 confirm。每个 stage 都会清屏，让屏幕只保留当前步骤；因此一个 stage 只应包含一个聚焦任务，避免真人所需信息滚出屏幕。不要修改 marker 上方的 library。

4. 验证并交付

• 执行 bash -n <script>；系统提供 shellcheck 时也要运行。
• 执行 chmod +x <script>。
• 不要自行端到端运行；脚本会打开浏览器并阻塞等待真人输入。改为静态追踪：步骤 1 中的每个值都被捕获，并落到步骤 1 规定的位置；每个 set_secret 名称都与 CI 中某个 secrets.* 引用完全一致。
• 告诉用户如何运行。它是一条可重复使用的配置路径时，提交脚本，并从 README 链接过去，让下一位使用者直接运行脚本，无须再次询问 AI。