# Wizard > 生成一个交互式 Bash 向导脚本，引导人类逐步完成只有他们才能执行的操作。适用于配置基础设施、设置凭据或 CI 密钥、操作陌生的第三方控制台，或运行一次性迁移/切换。对于 Agent 自身即可完成的步骤，请勿调用此功能。 - Skill: `zoujindougithub/wizard` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add zoujindougithub/wizard` - Raw SKILL.md: https://api.skillmd.com/api/skills/zoujindougithub/wizard/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: zoujindouGithub (https://skillmd.com/u/zoujindougithub) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/zoujindougithub/wizard --- # 向导 (Wizard) **向导**（Wizard）是一个 Bash 脚本，它能一步步引导人类完成繁琐的手动操作流程——既免去了纯人工操作的枯燥，也省去了每次都要向 AI 重新解释的麻烦。它会打开各个 URL，明确告知点击和复制什么内容，捕获这些值并写入对应的位置（`.env`、GitHub secrets），在每个阶段进行确认，并显示剩余阶段数。它可以用来配置第三方服务、运行一次性迁移，或将项目从一种状态转换到另一种状态。 [template.sh](template.sh) 已经提供了出色的交互体验：分阶段进度显示、确认关卡、跨平台 URL 打开（包括 WSL）、密码隐藏输入、幂等的 `.env` 更新（upsert）、`gh secret`/`gh variable` 写入以及结束时的总结。**你的工作只是界定流程范围并编写各个阶段的内容。** `STAGES` 标记上方的库代码在每个向导中都是完全相同的；保持一致性至关重要：切勿手动修改它。 向导默认是临时性的：为单次运行而构建，保存在临时路径或 `scripts/` 目录下，任务完成后即可删除。仅当用户需要将可复用的设置流程保留在仓库中时，才将其提交。 ## 流程 ### 1. 界定操作流程范围 梳理出人类必须执行的每一个手动步骤，以及沿途捕获的每一个值。先阅读仓库代码，不要毫无准备地直接发问： - 对于环境配置：查看 `.env`、`.env.example`、`.env.*`、`README`、`docker-compose*`、框架配置文件以及 `.github/workflows/*`（其中引用的每个 `secrets.*` / `vars.*` 都是向导必须生成的值）。 - 对于迁移或状态转换：确认当前状态、目标状态以及两者之间的不可逆操作。 然后向用户展示按顺序排列的阶段列表以及每个阶段生成的值，并进行确认：用户可能会增加、删除或重新排序。 **完成标准：** 每个阶段都按顺序命名，并且对于捕获的每个值，你都知道：(a) 人类从何处获取该值；(b) 写入何处（`.env`、GitHub secret、两者兼有，或无需写入；某些阶段纯粹是操作步骤）；(c) 属于机密（隐藏输入）还是公开值。 ### 2. 梳理各阶段的操作路径 为每个阶段编写人类需要遵循的精确路径：打开哪个 URL、在那里做什么、值显示在什么位置、填充到哪个变量：例如，“Dashboard → Developers → API keys → Reveal test key → 复制”。如果你不确定当前的 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