Wizard

Wizard

一个向导（wizard）是一个 bash 脚本，逐步引导人类走完一套手动流程 —— 这套流程既繁琐到不想手动做，又繁琐到不想每次都向 AI 重新解释一遍。它打开每一个 URL，准确说出要点击和复制什么，捕获这些值，把它们写到该去的地方（.env、GitHub secrets），在每个阶段都进行确认，并显示还剩多少。它可能用于配置第三方服务、运行一次性迁移，或把项目从一个状态移到另一个状态。

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

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

流程

1. 界定流程范围

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

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

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

完成的标志：每个阶段都按顺序命名了，且对于每一个被捕获的值，你都知道 (a) 人类从哪里获得它，(b) 它被写到哪里（.env、一个 GitHub secret、两者、或哪里都不写 —— 有些阶段是纯动作），以及 (c) 它是否为 secret（隐藏式输入）还是公开的。

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 和 TOTAL_MINUTES 设为诚实的估计（这驱动剩余时间显示）。

守住模板设定的标准：在询问某个值之前先打开它的 URL、对任何 secret 使用 ask_secret、对每一个需要持久化的值使用 write_env、只对 CI 真正需要的值使用 set_secret、在任何不可逆的动作之前使用 confirm。每个 stage 都会清屏，使得只有当前步骤可见 —— 让一个阶段专注于一个任务，这样人类需要看的东西都不会滚走。不要触碰标记之上的库。

4. 验证并交接

• bash -n ；如果可用就运行 shellcheck。
• chmod +x 。
• 别自己端到端地运行它 —— 它会打开浏览器并阻塞等待人类输入。改为静态地追踪它：第 1 步中的每一个值都被捕获、并落到第 1 步所说的地方，且每一个 set_secret 名称都与 CI 中的一个 secrets.* 引用完全匹配。
• 告诉用户如何运行它。如果它是一条可重复的设置路径，就提交它并从 README 链接过去，好让下一个人运行这个脚本而不是去问 AI。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: WenWuZhiDao
• Source: WenWuZhiDao/mattpocock-skills-zh
• License: MIT

Install and usage instructions live in the source repository linked above.