| 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。