wizard

Files (3)

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

SKILL.md (first lines)

# 向导

一个**向导**是一个 bash 脚本，一步一步引导人类走过一段手工流程——那种手工做起来乏味、每次向 AI 重新解释又乏味的流程。它打开每个 URL、说清楚要点击和复制什么、捕获这些值、把它们写到它们该去的地方（`.env`、GitHub 密钥）、在每个阶段确认，并显示还剩多少阶段。它可能配置第三方服务、运行一次性迁移，或把项目从一个状态移到另一个状态。

那份令人愉悦的 UX 已经被 [template.sh](template.sh) 解决了——逐阶段进度、确认关卡、跨平台的 URL 打开（包括 WSL）、隐藏式密钥输入、幂等的 `.env` upsert、`gh secret`/`gh variable` 写入，以及一段收尾摘要。**你的工作只是界定流程的范围并撰写它的各个阶段。** `STAGES` 标记之上的那段库在每个向导里都是相同的；那份一致性正是重点所在——绝不手工编辑它。

一个向导默认是短暂的——为一次运行而建，保存到一个临时或 `scripts/` 路径，活儿干完就删。只有当用户想要一条应当活在仓库里的可重复设置路径时才 commit 它。

## 流程

### 1. 界定流程范围

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

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

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

**完成的标志：** 每个阶段都按顺序命名了，而且对每个捕获的值你都知道 (a) 人类从哪里得到它，(b) 它被写到哪里（`.env`、一个 GitHub 密钥、两者都写，或哪儿都不写——有些阶段是纯动作），以及 (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.*` 引用。
- 告诉用户如何运行它。如果它是一条可重复的设置路径，就 commit 它并从 README 链接它，好让下一个人运行这个脚本而不是问 AI。

From WenWuZhiDao/mattpocock-skills-zh, MIT.

More from WenWuZhiDao/mattpocock-skills-zh