wizard

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Wizard

向导

A wizard is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (

.env

, GitHub secrets), confirms at every stage, and shows how much is left. It might configure third-party services, run a one-off migration, or move the project from one state to another.

The delightful UX is already solved by template.sh — progress with time-remaining, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent

.env

upserts,

gh secret

gh variable

writes, and a closing summary. Your job is only to scope the procedure and author its stages. The library above the

STAGES

marker is identical in every wizard; that consistency is the point — never hand-edit it.

A wizard is ephemeral by default — built for one run, saved to a scratch or

scripts/

path, deleted when the job's done. Commit it only when the user wants a repeatable setup path that should live in the repo.

向导是一款bash脚本，可逐步引导用户完成手动流程——这类流程手动操作繁琐，且每次向AI复述说明也十分麻烦。它会打开对应URL，明确告知用户点击和复制的内容，捕获所需值并写入指定位置（

.env

文件、GitHub密钥），在每个阶段进行确认，并展示剩余进度。它可用于配置第三方服务、执行一次性迁移，或是将项目从一种状态转换至另一种状态。

template.sh已解决了友好用户体验的问题——包含剩余时间进度显示、确认环节、跨平台URL打开（包括WSL）、隐藏式密钥输入、幂等性

.env

更新插入、

gh secret

gh variable

写入，以及结束总结。你的工作仅需梳理流程范围并编写各阶段内容。每个向导中

STAGES

标记上方的库代码完全一致，这种一致性是关键——切勿手动修改该部分代码。

向导默认是临时性的——为单次运行而创建，保存至临时目录或

scripts/

路径，任务完成后即可删除。仅当用户需要一个可重复执行的配置流程并希望将其存入代码仓库时，才需提交该脚本。

Process

流程

1. Scope the procedure

1. 梳理流程范围

Work out every manual step the human must take and every value that gets captured along the way. Read the repo first — don't ask cold:

For setup:
```
.env
```
,
```
.env.example
```
,
```
.env.*
```
,
```
README
```
,
```
docker-compose*
```
, framework config, and
```
.github/workflows/*
```
(every
```
secrets.*
```
/
```
vars.*
```
reference is a value the wizard must produce).
For a migration or transition: the current state, the target state, and the irreversible actions between them.

Then show the user the ordered list of stages and the values each produces, and confirm — they may add, drop, or reorder.

Done when: every stage is named in order, and for each captured value you know (a) where the human gets it, (b) where it's written (

.env

, a GitHub secret, both, or nowhere — some stages are pure actions), and (c) whether it's secret (hidden entry) or public.

梳理用户必须执行的每一个手动步骤，以及流程中需要捕获的所有值。先查阅代码仓库内容——不要凭空提问：

若为配置流程：查看
```
.env
```
、
```
.env.example
```
、
```
.env.*
```
、
```
README
```
、
```
docker-compose*
```
、框架配置文件，以及
```
.github/workflows/*
```
（所有
```
secrets.*
```
/
```
vars.*
```
引用的内容都是向导需要生成的值）。
若为迁移或状态转换流程：明确当前状态、目标状态，以及两者之间的不可逆操作。

随后向用户展示按顺序排列的阶段列表及每个阶段生成的值，并确认——用户可添加、删除或重新排序阶段。

完成标志： 所有阶段已按顺序命名，且对每个捕获的值明确：(a) 用户从何处获取该值；(b) 该值写入的位置（

.env

文件、GitHub密钥、两者皆有，或不写入——部分阶段仅为纯操作）；(c) 该值是否为机密（需隐藏输入）或公开。

2. Map each stage's journey

2. 规划每个阶段的操作路径

For each stage, write the precise path a human follows: which URL to open, what to do there, where a value is shown, which variable it fills — e.g. "Dashboard → Developers → API keys → Reveal test key → copy". Where you don't actually know the current UI or the exact command, say so and ask the user or check the docs — never invent steps that may not exist.

Done when: every stage traces to concrete instructions a stranger could follow.

为每个阶段编写用户需遵循的精确操作路径：打开哪个URL、在页面上执行哪些操作、值显示的位置、对应填充的变量——例如“控制台 → 开发者 → API密钥 → 显示测试密钥 → 复制”。若你不清楚当前UI或确切命令，请如实说明并询问用户或查阅文档——切勿编造可能不存在的步骤。

完成标志： 每个阶段的说明都具体明确，即使是陌生人也能遵循执行。

3. Author the wizard

3. 编写向导脚本

Copy

template.sh

to the target path. Replace the example stage with one

stage

per step, in dependency order. Use the library helpers —

stage

say

step

open_url

ask

ask_secret

write_env

set_secret

set_var

pause

confirm

— and set

TOTAL_STAGES

and

TOTAL_MINUTES

to honest estimates (this drives the time-remaining display).

Hold the bar the template sets: open the URL before asking for its value, use

ask_secret

for anything secret,

write_env

every persisted value,

set_secret

only the values CI actually needs, and

confirm

before any irreversible action. Each

stage

clears the screen so only the current step is visible — keep a stage to one focused task so nothing the human needs scrolls away. Don't touch the library above the marker.

将

template.sh

复制到目标路径。按依赖顺序，将示例阶段替换为每个步骤对应的

stage

。使用库中的辅助函数——

stage

、

say

step

、

open_url

、

ask

ask_secret

、

write_env

、

set_secret

set_var

、

pause

confirm

——并如实设置

TOTAL_STAGES

和

TOTAL_MINUTES

（这将驱动剩余时间显示）。

遵循模板设定的标准：在请求值之前先打开URL，对所有机密内容使用

ask_secret

，对所有需持久化的值使用

write_env

，仅为CI实际需要的值调用

set_secret

，并在执行任何不可逆操作前调用

confirm

。每个

stage

会清屏，仅显示当前步骤——每个阶段仅聚焦一项任务，确保用户所需内容无需滚动即可查看。切勿修改标记上方的库代码。

4. Verify and hand off

4. 验证并交付

```
bash -n <script>
```
; run
```
shellcheck
```
if available.
```
chmod +x <script>
```
.
Don't run it end-to-end yourself — it opens browsers and blocks on human input. Trace it statically instead: every value from step 1 is captured and lands where step 1 said, and every
```
set_secret
```
name exactly matches a
```
secrets.*
```
reference in CI.
Tell the user how to run it. If it's a repeatable setup path, commit it and link it from the README so the next person runs the script instead of asking an AI.

```
bash -n <script>
```
; 若有
```
shellcheck
```
工具则运行它。
```
chmod +x <script>
```
.
不要自行完整运行脚本——它会打开浏览器并等待用户输入。改为静态检查：确保步骤1中所有值都被捕获并写入指定位置，且每个
```
set_secret
```
的名称与CI中
```
secrets.*
```
的引用完全匹配。
告知用户如何运行脚本。若为可重复执行的配置流程，将其提交至仓库并在README中添加链接，以便后续用户直接运行脚本而非询问AI。