wizard

Files (3)

• SKILL.md
• openai.yaml · agents/
• template.sh

SKILL.md (first lines)

# Wizard

**Wizard** 是一段 bash 脚本，逐步引导人完成手工做起来繁琐、每次向 AI 重新解释也繁琐的操作。它打开每个 URL，说明要点击和复制什么，捕获得到的值，写入应去的位置（`.env`、GitHub secrets），每个阶段都确认，并显示还剩几个阶段。它可以配置第三方服务、跑一次性迁移，或把项目从一种状态迁到另一种状态。

令人省心的交互已经由 [template.sh](template.sh) 解决：分阶段进度、确认门、跨平台打开 URL（含 WSL）、隐藏输入密钥、幂等写入 `.env`、`gh secret` / `gh variable` 写入，以及结束摘要。**你的工作只是界定流程，并编写各个阶段。** `STAGES` 标记以上的库在每个 wizard 中都相同；这种一致性本身就是目的：绝不要手改那一段。

Wizard 默认是一次性的：为单次运行构建，保存到 scratch 或 `scripts/` 路径，事情做完后删除。只有用户希望仓库里留下可重复的开通路径时，才提交它。

## 流程

### 1. 界定流程

弄清人必须亲手完成的每一步，以及沿途要捕获的每个值。先读仓库，不要空问：

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

然后向用户展示有序的阶段列表和每个阶段产出的值，并确认：他们可以增加、删除或重排。

**完成标准：** 每个阶段都已按顺序列出名称；对每个捕获值都知道 (a) 人从哪里拿到它，(b) 写到哪里（`.env`、GitHub secret、两者都写，或不写入；有的阶段只是动作），以及 (c) 它是密钥（隐藏输入）还是公开值。

### 2. 画出每个阶段的路径

为每个阶段写出人要走的精确路径：打开哪个 URL、在那里做什么、值显示在哪里、填入哪个变量。例如 “Dashboard → Developers → API keys → Reveal test key → copy”。你并不真正知道当前界面或确切命令时，如实说明，询问用户或查阅文档：绝不要编造可能不存在的步骤。

**完成标准：** 每个阶段都能追溯到陌生人也能照做的具体说明。

### 3. 编写 wizard

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

From iZiTTMarvin/agent-skills-zh, MIT.

More from iZiTTMarvin/agent-skills-zh