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 many stages are 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 — stage-by-stage progress, 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 secrets），在每个阶段进行确认，并显示剩余阶段数量。它可用于配置第三方服务、运行一次性迁移，或是将项目从一种状态切换至另一种状态。

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 secret、两者皆有，或是无需写入——部分阶段仅为纯操作），以及（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

to the number of stages you wrote.

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

设置为你编写的阶段数量。

遵循模板设定的标准：在请求值之前先打开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。