---
name: wizard
description: 用于为外部配置、凭据、CI 密钥或人工迁移生成交互式设置向导（setup wizard）。
---

# 向导

**向导**是一个 bash 脚本，引导人一步步完成手动流程。这类流程手动操作很繁琐，每次重新向 AI 解释也很繁琐。向导会打开每个 URL，说明点击哪里、复制什么，收集输入的值，写入对应位置（`.env`、GitHub secrets），在每个阶段请求确认，并显示剩余阶段数。它可以用于配置第三方服务、执行一次性迁移，或把项目从一种状态迁移到另一种状态。

[template.sh](template.sh) 已经实现了好用的交互体验：分阶段进度、确认步骤、跨平台打开 URL（包括 WSL）、隐藏密钥输入、幂等写入 `.env`、通过 `gh secret` 和 `gh variable` 写入、结束时汇总。**你的工作只是梳理流程并编写各个阶段。** `STAGES` 标记之上的库代码在每个向导中完全相同，这种一致性正是它的价值：库代码保持原样，只编辑标记之下的部分。

向导默认是一次性的：为一次运行而写，保存在临时目录或 `scripts/` 中，事情完成后删除。只有用户需要一条保留在仓库中、可重复执行的配置流程时，才提交它。

## 过程

### 1. 梳理流程

弄清人必须完成的每个手动步骤，以及过程中需要收集的每个值。先阅读仓库，不要一开始就提问：

- 配置类：`.env`、`.env.example`、`.env.*`、`README`、`docker-compose*`、框架配置，以及 `.github/workflows/*`（其中每个 `secrets.*` 和 `vars.*` 引用都是向导必须产出的值）。
- 迁移或切换类：当前状态、目标状态，以及两者之间不可逆的操作。

然后向用户展示阶段的顺序清单，以及每个阶段产出的值，并请用户确认：用户可能会增加、删除或调整顺序。

**完成条件：** 每个阶段都已按顺序命名；对每个要收集的值，你都知道：(a) 人从哪里获得它；(b) 它写到哪里（`.env`、GitHub secret、两者都写，或都不写；有些阶段只是执行操作）；(c) 它是否是密钥（需要隐藏输入）。

### 2. 写清每个阶段的操作路径

为每个阶段写出人要执行的具体路径：打开哪个 URL、在页面上做什么、值显示在哪里、填入哪个变量。例如“控制台 → 开发者 → API 密钥 → 显示测试密钥 → 复制”。不确定当前 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 <脚本>`；有 `shellcheck` 时也运行它。
- 用户在 Windows 上时，告诉用户在 Git Bash 或 WSL 中运行脚本，不在 PowerShell 或 cmd 中运行。Claude Code 在 Windows 上本身依赖 Git Bash，通常已经安装。
- 运行 `chmod +x <脚本>`。
- 端到端运行交给人完成：它会打开浏览器，并阻塞等待人的输入。你负责静态检查：第 1 步列出的每个值都会被收集，并写入第 1 步指定的位置；每个 `set_secret` 的名称都与 CI 中的 `secrets.*` 引用完全一致。
- 告诉用户如何运行。如果它是可重复执行的配置流程，提交脚本并在 README 中链接，让下一个人直接运行脚本，而不必再询问 AI。