wizard

Files (3)

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

SKILL.md (first lines)

# Wizard

**Wizard** 是一个 bash 脚本，一步一步带人走完手工做起来乏味、每次向 AI 再解释也乏味的手动流程。它打开每个 URL，精确说出要点击和复制什么，捕获这些值，写到该写的地方（`.env`、GitHub secrets），每阶段都确认，并显示还剩多少阶段。它可能配置第三方服务、跑一次性迁移，或把项目从一种状态迁到另一种。

令人愉悦的 UX 已由 [template.sh](template.sh) 解决——按阶段进度、确认闸门、跨平台打开 URL（包括 WSL）、隐藏的 secret 输入、幂等的 `.env` upserts、`gh secret`/`gh variable` 写入，以及收尾摘要。**你的工作只是界定流程并编写其阶段。** `STAGES` 标记之上的库在每个 wizard 里都相同；这种一致性就是重点——永远不要手改它。

Wizard 默认是短暂的——为跑一次而建，存到 scratch 或 `scripts/` 路径，活干完就删。只有用户想要应活在仓库里的可重复 setup 路径时才 commit 它。

## 流程

### 1. 界定流程

弄清人必须采取的每一步手工操作，以及沿途捕获的每个值。先读仓库——不要冷问：

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

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

**完成条件：** 每个阶段按顺序命名，并且对每个捕获的值你知道 (a) 人从哪拿到它，(b) 它写到哪（`.env`、GitHub secret、两者，或无处可写——有些阶段是纯动作），以及 (c) 它是 secret（隐藏输入）还是公开的。

### 2. 映射每个阶段的旅程

对每个阶段，写下人要走的精确路径：打开哪个 URL、在那里做什么、值显示在哪、它填入哪个变量——例如 "Dashboard → Developers → API keys → Reveal test key → copy"。你并不真正知道当前 UI 或确切命令时，说出来并问用户或查文档——永远不要发明可能不存在的步骤。

**完成条件：** 每个阶段都能追溯到陌生人也能跟着走的具体说明。

### 3. 编写 wizard

把 `template.sh` 复制到目标路径。用按依赖顺序的每个步骤一个 `stage` 替换示例阶段。使用库辅助函数——`stage`、`say`/`step`、`open_url`、`ask`/`ask_secret`、`write_env`、`set_secret`/`set_var`、`pause`/`confirm`——并把 `TOTAL_STAGES` 设为你写的阶段数。

守住模板设定的标准：在询问其值之前打开 URL，任何 secret 用 `ask_secret`，每个持久化的值用 `write_env`，只对 CI 真正需要的值用 `set_secret`，任何不可逆动作前 `confirm`。每个 `stage` 清屏，这样只有当前步骤可见——把一个阶段保持为一件聚焦的任务，以免人需要的东西滚出屏幕。不要动标记之上的库。

### 4. 核实并交接

- `bash -n <script>`；若有 `shellcheck` 就跑。
- `chmod +x <script>`。
- 不要自己端到端跑它——它会打开浏览器并阻塞等人输入。改为静态追踪：步骤 1 的每个值都被捕获并落到步骤 1 所说的地方，每个 `set_secret` 名称精确匹配 CI 中的 `secrets.*` 引用。
- 告诉用户如何运行。若它是可重复的 setup 路径，commit 它并从 README 链过去，这样下一个人跑脚本而不是问 AI。

From shenjunjian/matt-skill-cn, MIT.

More from shenjunjian/matt-skill-cn