需要人工完成基础设施配置、凭据/CI secret…

用 bash wizard 把只有人工能执行、又需要反复解释的手动流程变成逐步交互式脚本

适用场景

解决思路

1. 界定 wizard 的范围：列出人工必须执行的每个手动步骤，以及沿途需要捕获的每个值。
2. 先阅读仓库，不要直接冷启动询问用户：检查 `.env`、`.env.example`、`.env.*`、`README`、`docker-compose*`、框架配置和 `.github/workflows/*`。
3. 在 `.github/workflows/*` 中，每个 `secrets.*` / `vars.*` 引用都对应一个 wizard 必须产出的值。
4. 若流程是迁移或切换，先确定当前状态、目标状态，以及两者之间的不可逆操作。
5. 向用户展示按顺序排列的阶段列表，以及每个阶段会产出哪些值，并请用户确认。
6. 允许用户增加、删除或重排阶段。
7. 界定完成的判断标准：每个阶段都已按顺序命名，且对每个捕获值都知道：a) 用户从哪里获取它，b) 写入哪里（`.env`、GitHub secret、两者都写，或不写入；有些阶段只是纯操作），c) 它是 secret（隐藏输入）还是 public。
8. 为每个阶段规划人的操作路径：写清楚打开哪个 URL、在该页面做什么、值显示在哪里、填入哪个变量。
9. 把路径写成具体指令，例如：Dashboard → Developers → API keys → Reveal test key → copy。
10. 如果不确定当前 UI 或确切命令，明确说明并询问用户或查阅文档；绝不编造可能不存在的步骤。
11. 阶段规划的完成标准：每个阶段都能追溯到陌生人也能照做的具体指令。
12. 把 `template.sh` 复制到目标路径。
13. 用每个步骤一个 `stage` 替换示例阶段，并按依赖顺序排列。
14. 使用库提供的 helper：`stage`、`say`/`step`、`open_url`、`ask`/`ask_secret`、`write_env`、`set_secret`/`set_var`、`pause`/`confirm`。
15. 设置 `TOTAL_STAGES` 为你实际写出的阶段数量。
16. 保持模板设定的标准：在请求某个值之前先 `open_url` 打开对应 URL。
17. 对任何 secret 都使用 `ask_secret` 进行隐藏输入。
18. 对每个需要持久化的值都用 `write_env` 写入。
19. 只用 `set_secret` 写入 CI 实际需要的值。
20. 在任何不可逆操作之前使用 `confirm` 确认。
21. 每个 `stage` 会清屏，只显示当前步骤；让一个阶段只聚焦一个任务，避免用户需要的信息滚动消失。
22. 不要手改 `STAGES` 标记上方的库代码。
23. 验证脚本：运行 `bash -n <script>`；如果可用，运行 `shellcheck`。
24. 运行 `chmod +x <script>` 赋予脚本可执行权限。
25. 不要自己端到端运行脚本：它会打开浏览器并阻塞等待人工输入。
26. 改为静态追踪：确认步骤 1 中每个值都被捕获，并落到步骤 1 指定的位置；确认每个 `set_secret` 名称与 CI 中的 `secrets.*` 引用完全匹配。
27. 告诉用户如何运行该脚本。
28. 如果这是可重复的 setup 路径，提交脚本，并在 `README` 中链接它，让下一个人直接运行脚本，而不是再问 AI。
29. 默认把 wizard 当作一次性脚本：保存到 scratch 或 `scripts/` 路径，任务完成后删除。
30. 仅当用户希望仓库中保留可重复的 setup 路径时才提交它。
31. 使用 `template.sh` 已提供的 UX：阶段进度、确认门、跨平台 URL 打开（含 WSL）、隐藏 secret 输入、幂等 `.env` upsert、`gh secret`/`gh variable` 写入、结尾总结。
32. 你的职责仅限于界定流程和编写各阶段，不要重新实现 UX 库。

适用边界 · 注意事项

• 当这些步骤可由 agent 自己完成时，不要生成 wizard。