向导
- 作者仓库星标 0
- 作者更新于 2026年8月24日 14:19
- 作者仓库 skills
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @mattpocock · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需手动接入
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- WSL · Docker
- 运行环境要求
- Docker
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 命令执行
- 读取环境变量
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# 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](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.
## Process
### 1. Scope the procedure
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.
### 2. Map each stage's journey
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.
### 3. Author the wizard
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`. 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.
### 4. Verify and hand off
- `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.
章节与文件索引
按说明文件中的顺序排列。
1. 程序范围
2. 绘制每个阶段的旅程
3. 编写向导
4. 验证并移交
文件/命令 -> .env · gh secret · gh variable · STAGES · scripts/ · .env.example · .env.* · README
内容校验值 -> a818e556ab31
当前原文的自动摘译,尚未人工审校。
1. 程序范围
计算出人类必须采取的每个手动步骤以及在此过程中捕获的每个值。首先阅读存储库,不要问冷:对于设置:
.env,.env.example,.env.*,README,docker-compose*,框架配置和.github/workflows/*(每个secrets.*/vars.*引用都是向导必须生成的值)。对于迁移或转换:当前状态、目标状态以及它们之间的不可逆操作。2. 绘制每个阶段的旅程
对于每个阶段,写下人类遵循的精确路径:打开哪个 URL、在那里做什么、显示值的位置、填充哪个变量:例如“仪表板→开发人员→API密钥→显示测试密钥→复制”。如果您实际上不知道当前的 UI 或确切的命令,请说出来并询问用户或检查文档:永远不要发明可能不存在的步骤。完成时间:每个阶段都可以追溯到陌生人可以遵循的具体指示。
3. 编写向导
将
template.sh复制到目标路径。 按照依赖顺序,将示例阶段替换为每步一个stage。4. 验证并移交
bash -n <script>;运行shellcheck(如果可用)。chmod +x <script>。不要自己端到端地运行它:它会打开浏览器并阻止人工输入。相反,以静态方式跟踪它:捕获步骤 1 中的每个值并将其落在步骤 1 所说的位置,并且每个set_secret名称与 CI 中的secrets.*引用完全匹配。告诉用户如何运行它。如果它是可重复的设置路径,请提交它并从自述文件链接它,以便下一个人运行脚本而不是询问人工智能。