wizard

Wizard

向导是一个 Bash 脚本，用于引导用户完成手动操作流程。它会打开每个 URL，说明要点击和复制的内容，收集值，将这些值写入指定位置，并显示进度。它可以用于配置第三方服务、执行一次性迁移，或将项目从一种状态转换为另一种状态。

template.sh 提供分阶段进度、确认关卡、跨平台 URL 打开（包括 WSL）、隐藏式密钥输入、幂等的 .env 更新、gh secret/gh variable 写入，以及结束摘要。确定流程范围并编写各阶段，不要手动编辑 STAGES 标记上方的共享库。

默认情况下，向导是临时的：将其保存到临时路径，供本次运行使用。如果用户希望在仓库中保留可重复使用的设置流程，请按照项目的脚本约定保存，并说明如何运行。可重复使用不代表授权提交；只有用户授权后才能提交。

流程

1. 确定流程范围

明确所请求的设置、迁移或转换所需的步骤和值。在询问用户之前，先阅读相关的仓库上下文：

• 对于设置：查看相关的环境示例、README 说明、服务和框架配置，以及 CI 工作流。使用 secrets.* / vars.* 引用来确定哪些地方会使用本次设置所需的值；无关的引用不会扩大向导的范围。在适当情况下复用现有配置，而不是再次收集凭据。仅在需要时检查包含密钥的文件，且不要泄露其中的值。
• 对于迁移或转换：明确当前状态、目标状态，以及两者之间不可逆的操作。

复用对话中已经确定的流程和决策。阶段大纲可以作为进度更新，不需要再次征求批准。只针对会实质影响流程、目标或所收集值的未决选择提问；在这些选择尚未确定时，继续准备彼此独立的阶段。用户会运行完成后的脚本，因此应在 confirm 关卡中批准重要操作；不要自行运行该脚本。

完成标准： 每个阶段都已按顺序命名，并且对每个收集的值，你都知道：（a）用户从何处获取；（b）写入何处（.env、GitHub 密钥、两者或不写入任何位置；某些阶段仅执行操作）；（c）该值是否为密钥（是否使用隐藏式输入）或公开值。

2. 梳理每个阶段的操作路径

针对每个阶段，写出用户要遵循的精确路径：要打开哪个 URL、在那里要做什么、值显示在哪里，以及它对应填入哪个变量。例如：“控制面板 → 开发者 → API 密钥 → 显示测试密钥 → 复制”。如果你并不清楚当前界面或确切命令，请如实说明并询问用户或查阅文档：不要编造可能不存在的步骤。

完成标准： 每个阶段都有具体的操作说明，陌生人也能照着完成。

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，相关 GitHub 配置使用 set_secret/set_var。不要仅仅因为有对应的辅助函数，就将一个值写入其他目标。

每次执行不可逆操作之前，都要显示其目标和后果，并要求 confirm 成功后才能执行。若用户拒绝确认，必须跳过或中止该操作；横幅中的就绪暂停不能替代确认。即使用户已授权准备脚本，也要保留这些执行门槛。

每个 stage 和 finish 都会等待按 Enter，然后清屏，因此用户可以在下一阶段开始前阅读当前阶段的确认提示和警告。每个阶段只处理一项明确任务，确保其显示的所有内容都能在屏幕上完整呈现。不要改动标记上方的库代码。

4. 验证并交付

• 运行 bash -n <script>；如果有 shellcheck，也运行它。
• 运行 chmod +x <script>。
• 不要自行端到端运行脚本：它会打开浏览器，并等待用户输入。请改为静态追踪：确认所需值已被捕获或复用、每次写入都到达预期目标、CI 密钥和变量名称与相关使用方一致，并且用户拒绝确认后不可执行不可逆操作。
• 交付脚本及其运行说明，指出其 gh 写入操作针对哪个仓库（即脚本运行所在目录对应的仓库），并说明哪些关键阶段需要用户确认。完成意味着所请求的脚本已准备好供用户运行；不要声称设置或迁移已经执行。