Wizard（C31 改良版 = 原生功能 1:1 + 四条增强）

功能上与 mattpocock/skills 的 wizard 完全等价：生成一个交互式 bash 向导，逐 stage 领着人走完一个手动流程（配置第三方服务、一次性迁移、装机）。模板库（template.sh 的 stage/banner/open_url/pause/ask/ask_secret/confirm/write_env/set_secret/set_var 库）一字不动——STAGES 标记以上的库代码绝不手改。

第零条 · 适用性闸门（原生第一条，优先级最高）

Don't invoke this for steps the agent can perform itself.

动笔前先回答：这个流程里哪些步骤只有人能做？Agent 能自己执行的——本机 shell、SSH 可达的服务器、有凭据的 API——agent 直接执行，不产出向导。向导只覆盖人独占的步骤：网页后台登录、手机/物理设备操作、OTP/人脸、无凭据的第三方面板。

实证（2026-08-12 教训）：VPS 部署网络代理服务——scp/ssh/跑脚本全程 agent 可做（免密密钥在本地），agent 直接非交互代跑（ssh 无 TTY + printf 管道喂 stdin 应答 banner/confirm，confirm 闸门由 agent 依据证据判断）；向导只该覆盖手机端 v2rayNG 导入这种真·人手步骤。

流程（与原生一致）

1. Scope —— 圈定流程

读仓库先行（不许冷问）：.env*、README、docker-compose、框架配置、.github/workflows/*（每个 secrets.*/vars.* 引用都是向导必须产出的值）。迁移类任务：现态、目标态、两者之间的不可逆操作。

然后把 stage 清单展示给用户确认——用户可增删改。

Done when: 每个 stage 已命名排序，且每个捕获值都知道 (a) 从哪拿 (b) 写到哪（.env / GitHub secret / 都不写——有些 stage 纯动作）(c) 是否敏感（隐藏输入）。

2. Map —— 每个 stage 的路线

精确到 "Dashboard → Developers → API keys → Reveal test key → copy"。不确定的 UI 路径或命令 → 问用户或查文档，禁止编造不存在的步骤。

Done when: 每个 stage 都能让陌生人照着走完。

3. Author —— 写向导

复制 template.sh 到目标路径，逐 stage 写。用库函数：stage/say/step/open_url/ask/ask_secret/write_env/set_secret/set_var/pause/confirm，设 TOTAL_STAGES。规矩：先 open_url 再问值；敏感值用 ask_secret；每个持久化值 write_env；set_secret 只给 CI 真需要的；不可逆操作 confirm 守门；每 stage 一件事（清屏后只有当前步骤）。

4. Verify & hand off —— 验证与交付

• bash -n <script>；有 shellcheck 就跑
• chmod +x <script>
• 不要自己端到端跑交互式向导（会开浏览器、阻塞等人输入）——静态追踪替代：每个值从哪来→落到哪，set_secret 名与 CI 引用逐一对应
• 告诉用户怎么跑；可复用的装机路径才提交进 repo 并链进 README，一次性向导用完可弃

C31 四条增强（stage 作者区内叠加，不碰模板库）

1. 读仓库配置代替问人。 向导启动时先从 .env / .env.local / 配置文件推导一切可推导的值（项目 ref、URL、key 名）。人只回答机器推不出的东西。问一个能自己查到的问题 = 向导作者偷懒。

SUPABASE_URL_VAL=$(_existing SUPABASE_URL || true)   # _existing 是模板库自带
PROJECT_REF=$(printf '%s' "$SUPABASE_URL_VAL" | sed -E 's|https://([^.]+)\..*|\1|')

2. 产物自动上剪贴板。 需要人粘贴的东西（SQL、JSON、命令）由向导自动提取送进剪贴板——人只做 Ctrl-V。pbcopy / clip.exe / xclip / wl-copy 按平台探测，都没有才 warn 并给精确行号。

sed -n '106,151p' supabase/boardroom-schema.sql | clip.exe   # Windows

3. 自定位。 stages 区第一行永远是：

cd "$(dirname "${BASH_SOURCE[0]}")/.."   # 从任何目录调用都能跑

4. 机械验收收尾（最重要）。 人执行完手动步骤后，向导不许直接宣布成功——必须有一个验证 stage 用机器手段实测结果（REST 探针 / curl 状态码 / 命令输出断言），全部通过才进 finish；不过就明确报错退出。人不宣告成功，机器验证。

code=$(curl -s -o /dev/null -w "%{http_code}" "$URL/rest/v1/$t?select=*&limit=0" -H "apikey: $KEY" ...)
[[ "$code" == "200" ]] || { warn "未建成"; exit 1; }

验证失败的报错必须可见：禁止 cmd >/dev/null 2>&1 吞掉诊断输出——失败路径打印真实错误（if ! OUT=$(cmd 2>&1); then fail "$OUT"; fi），否则人只看到"失败"无从排查（2026-08-12 实证：xray run -test 报错被吞，真因是 xray x25519 输出格式变更导致私钥解析为空）。

验收必须走真实数据路径：探针类测试（无凭据连接被转发到伪装站）只能验证 fallback 路径，验证不了合法客户端握手——2026-08-12 实证：伪装站 <www.microsoft.com> 的 TLS 证书 8273B 超 Reality 8192B 硬限制（XTLS/Xray-core #6356），探针 HTTP 200 但所有真实客户端握手失败。向导的机械验收应以真实凭据回环实测（本地起临时客户端 → 隧道 → 出口 IP 断言），并且 systemctl restart 而非 enable --now（后者在服务已运行时不会重载新配置，导致运行进程用旧密钥）。

例外：agent 代跑（2026-08-12 实证）

当步骤全部 agent 可执行时，agent 可直接非交互代跑向导——ssh 无 TTY + printf 管道喂 stdin 应答 banner/confirm。这与"不要自己端到端跑"不冲突：后者指交互式向导（开浏览器/阻塞等）不该由 agent 跑；无交互路径下 agent 代跑是正解，confirm 闸门由 agent 依据证据判断（如"配置是安装器刚生成的"即可放行）。

Windows 注意事项（实证）

• 用户终端是 PowerShell：交付命令给 Git Bash 全路径形态 & "C:\Program Files\Git\bin\bash.exe" "<wizard 全路径>"——裸 bash 可能被 WSL 劫持
• 剪贴板用 clip.exe；模板库的 open_url 已兼容 explorer.exe

实证：某项目的 supabase-provision-wizard.sh（三张表部署，零提问、零手抄、机器验证收尾）；另一例：VPS 网络服务装机向导（agent 代跑全流程，含 nobody→root 回退）。