向导
向导是一个 bash 脚本，它一步一步领着人走完一段手工流程——这段流程手动做很烦，每次向 AI 重新解释也很烦。它会逐个打开 URL，明确说出该点什么、该复制什么，把取到的值收集起来，写到它们该在的地方（.env、GitHub 密钥），在每一段都要人确认，并显示还剩几段。它可能用来配置第三方服务、执行一次性迁移，或者把项目从一种状态搬到另一种状态。
这套好用的交互已经由 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 密钥、两者都写，还是哪里都不写——有些阶段纯粹是动作），以及 (c) 它是密钥（隐藏输入）还是公开的。
2. 理清每个阶段的路径
为每个阶段写出人要走的确切路径：打开哪个 URL、在那里做什么、值显示在哪里、它填进哪个变量：例如「Dashboard → Developers → API keys → Reveal test key → copy」。如果你其实并不了解当前的界面或确切的命令，就明说，并去问用户或查文档：绝不要编造可能不存在的步骤。
完成判据： 每个阶段都能追溯到陌生人也能照着做的具体指引。
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.*引用完全一致。 - 告诉用户怎么跑它。如果这是一条可重复使用的配置路径，就把它提交进去，并从 README 链接过去，让下一个人直接跑脚本，而不是去问 AI。
