---
name: wizard
description: 生成一个交互式 bash 向导，引导人类完成只有他们能执行的步骤。适用于配置基础设施、设置凭证或 CI 密钥、操作不熟悉的第三方面板、或执行一次性迁移或切换。不要让代理替自己执行本应由人类完成的步骤。
---

# 向导

**向导（Wizard）** 是一个 bash 脚本，逐步引导人类完成手动流程——这些流程手动做很繁琐，每次重新向 AI 解释也很麻烦。它会打开每个 URL，精确说明要点击什么和复制什么，捕获值，将其写入正确的位置（`.env`、GitHub secrets），在每个阶段确认，并显示剩余阶段数。它可能配置第三方服务、运行一次性迁移、或把项目从一个状态迁移到另一个状态。

便捷的 UX 已经由 [template.sh](template.sh) 解决——分阶段显示进度、确认关卡、跨平台 URL 打开（含 WSL）、隐藏密文输入、幂等的 `.env` 写入、`gh secret`/`gh variable` 写入，以及一个结束汇总。**你的工作只是界定流程范围并编写其阶段。** 每个向导中 `STAGES` 标记上方的库代码都是相同的——这种一致性正是关键所在，永远不要手动编辑它。

向导默认是临时的——为一次运行而创建，保存在 scratch 或 `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 → copy"。如果你不确定当前 UI 或确切命令，请说明并询问用户或查阅文档——永远不要编造可能不存在的步骤。

**完成条件：** 每个阶段都能追溯到具体的指令，让一个陌生人也能照着做。

### 3. 编写向导

将 `template.sh` 复制到目标路径。将示例阶段替换为每个步骤一个 `stage`，按依赖顺序排列。使用库辅助函数——`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`，在任何不可逆操作前使用 `confirm`。每个 `stage` 都会清屏，使当前步骤成为唯一可见内容——让一个阶段只做一件事，这样人类需要的东西就不会滚出视野。不要触碰标记上方的库代码。

### 4. 验证并移交

- `bash -n <script>`；如果可用则运行 `shellcheck`。
- `chmod +x <script>`。
- 不要自己端到端运行——它会打开浏览器并阻塞等待人类输入。改为静态跟踪：步骤 1 中的每个值都被捕获并写入步骤 1 指定的位置，并且每个 `set_secret` 名称精确匹配 CI 中的 `secrets.*` 引用。
- 告诉用户如何运行它。如果这是一个可重复的设置路径，提交它并在 README 中链接，这样下一个人就能直接运行脚本，而不是求助 AI。