向导

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

那份令人愉悦的 UX 已经被 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。