@aiyiran/myclaw 1.0.29 → 1.0.31

package/index.js

@@ -236,6 +236,15 @@ function runNew() {
   }
 }
 
+// ============================================================================
+// 向导系统（统一入口）
+// ============================================================================
+
+function runWeixin() {
+  const { runWeixin } = require('./wizards/index');
+  runWeixin();
+}
+
 // ============================================================================
 // WSL2 安装 (独立模块)
 // ============================================================================
@@ -519,6 +528,9 @@ function showHelp() {
   console.log('用法:');
   console.log('  myclaw <command>');
   console.log('');
+  console.log('向导 (交互式):');
+  console.log('  weixin     微信接入向导（步骤引导 + 教学说明）');
+  console.log('');
   console.log('命令:');
   console.log('  install    安装 OpenClaw 服务');
   console.log('  status     简化版状态查看（学生友好）');
@@ -532,11 +544,11 @@ function showHelp() {
   console.log('  help       显示帮助信息');
   console.log('');
   console.log('示例:');
+  console.log('  myclaw weixin          # 打开微信接入向导');
   console.log('  myclaw install         # 安装 OpenClaw');
   console.log('  myclaw status          # 查看状态');
   console.log('  myclaw new helper      # 创建名为 helper 的 Agent');
   console.log('  myclaw open            # 打开默认控制台');
-  console.log('  myclaw open http://... # 打开指定 URL');
   console.log('  myclaw patch           # 注入 UI 扩展');
   console.log('  myclaw restart         # 重启 Gateway');
   console.log('');
@@ -552,6 +564,8 @@ console.log(colors.blue + 'MyClaw v' + version + colors.nc);
 
 if (!command || command === 'help' || command === '--help' || command === '-h') {
   showHelp();
+} else if (command === 'weixin') {
+  runWeixin();
 } else if (command === 'install') {
   runInstall();
 } else if (command === 'status') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiyiran/myclaw",
-  "version": "1.0.29",
+  "version": "1.0.31",
   "description": "",
   "main": "index.js",
   "bin": {
@@ -13,5 +13,11 @@
   },
   "keywords": [],
   "author": "",
-  "license": "ISC"
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^4.1.2"
+  },
+  "engines": {
+    "node": ">=16"
+  }
 }

package/wizards/commons/gateway.steps.json

@@ -0,0 +1,52 @@
+{
+  "restart": {
+    "id": "restart-gateway",
+    "icon": "🔄",
+    "label": "重启 Gateway",
+    "type": "action",
+    "command": {
+      "exec": "openclaw gateway restart",
+      "display": "openclaw gateway restart"
+    },
+    "teach": {
+      "title": "重启 Gateway 使配置生效",
+      "description": "重启 OpenClaw 核心服务，让之前的所有配置变更生效。\n\nGateway 是 OpenClaw 的「大脑」，它在启动时读取配置。\n修改配置（如安装插件、启用插件）后，\n需要重启让 Gateway 加载最新配置。\n\n类比：改了系统设置后，有时候需要重启才能生效。",
+      "look_for": "重启后 Gateway 运行中，控制台地址 http://127.0.0.1:18789",
+      "tip": "⏳ 重启期间短暂不可用，请等待几秒钟再继续。"
+    }
+  },
+
+  "check-health": {
+    "id": "check-gateway-health",
+    "icon": "🔍",
+    "label": "检查 Gateway 运行状态",
+    "type": "check",
+    "command": {
+      "exec": "openclaw health",
+      "display": "openclaw health"
+    },
+    "teach": {
+      "title": "检查 Gateway 是否正在运行",
+      "description": "检查 OpenClaw Gateway 的健康状态。\n\n返回 OK 说明 Gateway 正常运行，\n返回错误说明 Gateway 未启动或出现问题。",
+      "look_for": "输出 OK 或类似健康状态提示",
+      "tip": "🔒 只读检查，可以随时运行。"
+    }
+  },
+
+  "check-status": {
+    "id": "check-openclaw-status",
+    "icon": "📊",
+    "label": "查看 OpenClaw 完整状态",
+    "type": "check",
+    "command": {
+      "exec": "openclaw status",
+      "display": "openclaw status"
+    },
+    "teach": {
+      "title": "查看 OpenClaw 完整运行状态",
+      "description": "显示 OpenClaw 所有组件的运行状态，\n包括 Gateway、已加载插件、已连接渠道等。",
+      "look_for": "查看各组件状态是否正常",
+      "tip": "🔒 只读命令，可以随时查看。"
+    }
+  }
+}

package/wizards/configs/weixin/bind.config.json

@@ -0,0 +1,153 @@
+{
+  "id": "weixin-bind",
+  "title": "微信多账号绑定",
+  "subtitle": "为每个微信账号绑定专属的 Agent",
+
+  "steps": [
+    {
+      "id": "check-before-bind",
+      "icon": "🔍",
+      "label": "查看当前账号列表",
+      "type": "check",
+      "command": {
+        "exec": "openclaw channels status",
+        "display": "openclaw channels status"
+      },
+      "teach": {
+        "title": "查看当前已登录的账号列表",
+        "description": "在开始绑定之前，先看看当前哪些微信账号已经登录。\n\n这条命令会列出所有已登录的渠道账号，以及它们当前\n绑定到哪个 Agent（如果已绑定的话）。\n\n从这里你可以确认账号ID（--account 参数的值），\n后续绑定步骤会用到。",
+        "look_for": "每行显示一个账号，记下账号ID（通常是一串标识符）",
+        "tip": "🔒 只读操作，可以随时运行查看最新状态。"
+      }
+    },
+    {
+      "id": "login-account-1",
+      "icon": "📱",
+      "label": "扫码登录第一个微信账号",
+      "type": "interactive",
+      "command": {
+        "exec": "openclaw channels login --channel openclaw-weixin",
+        "display": "openclaw channels login --channel openclaw-weixin"
+      },
+      "teach": {
+        "title": "扫码登录第一个微信账号",
+        "description": "每个微信账号需要单独扫码登录，系统会为它创建一个独立的账号条目。\n\n这一步登录「第一个微信账号」（比如用于课堂答疑的账号）。\n\n操作步骤：\n  1. 打开手机微信（第一个账号）\n  2. 扫描终端里的二维码\n  3. 手机上点击「确认授权」",
+        "look_for": "登录成功后，系统会显示新的账号条目（记下账号ID）",
+        "tip": "📱 确保手机是你想绑定的第一个账号，不要用错手机。"
+      }
+    },
+    {
+      "id": "login-account-2",
+      "icon": "📱",
+      "label": "扫码登录第二个微信账号",
+      "type": "interactive",
+      "command": {
+        "exec": "openclaw channels login --channel openclaw-weixin",
+        "display": "openclaw channels login --channel openclaw-weixin"
+      },
+      "teach": {
+        "title": "扫码登录第二个微信账号",
+        "description": "现在登录「第二个微信账号」（比如用于生活助手的账号）。\n\n这条命令和第一步相同，但登录的是不同的微信账号，\n系统会自动识别并创建新的独立账号条目。\n\n操作步骤：\n  1. 打开手机微信（第二个账号）\n  2. 扫描终端里的二维码\n  3. 手机上点击「确认授权」",
+        "look_for": "看到第二个账号条目出现在列表中",
+        "tip": "📱 换另一部手机（或另一个微信账号）来扫码。"
+      }
+    },
+    {
+      "id": "check-accounts",
+      "icon": "🔍",
+      "label": "查看账号列表（确认登录成功）",
+      "type": "check",
+      "capture": "accounts_output",
+      "command": {
+        "exec": "openclaw channels status",
+        "display": "openclaw channels status"
+      },
+      "teach": {
+        "title": "确认两个账号都已登录",
+        "description": "再次查看账号列表，确认两个微信账号都已成功登录。\n\n在这一步，你需要从输出中：\n  1. 找到第一个账号的「账号ID」\n  2. 找到第二个账号的「账号ID」\n\n后面的绑定步骤（第 5、6 步）的 --account 参数就填这些ID。\n\n✅ 这一步的输出会被记录，绑定时可直接参考。",
+        "look_for": "两个账号都出现在列表中，状态为 connected",
+        "tip": "📋 详细看输出，记录账号ID，避免后续填写出错。"
+      }
+    },
+    {
+      "id": "bind-account-1",
+      "icon": "🔗",
+      "label": "绑定账号1 → Agent",
+      "type": "input",
+      "requires": ["check-accounts"],
+      "show_capture": "accounts_output",
+      "command": {
+        "template": "openclaw channels bind --channel openclaw-weixin --account {{account}} --agent {{agent}}",
+        "display":  "openclaw channels bind --channel openclaw-weixin --account {{account}} --agent {{agent}}"
+      },
+      "inputs": [
+        {
+          "key": "account",
+          "label": "账号1 的账号ID",
+          "hint": "从上一步（步骤4）的输出中找到第一个账号的标识符",
+          "placeholder": "例如：wx_123456789"
+        },
+        {
+          "key": "agent",
+          "label": "要绑定到的 Agent 名称",
+          "hint": "填写你已创建的 Agent 名称（使用 myclaw status 可查看）",
+          "placeholder": "例如：blog、helper、assistant"
+        }
+      ],
+      "teach": {
+        "title": "将账号1绑定到指定 Agent",
+        "description": "这条命令将第一个微信账号与指定的 Agent 绑定。\n\n绑定后，从这个微信账号发来的消息，\n都会由对应的 Agent 来处理和回复。\n\n命令中的两个参数：\n  --account  指定要绑定的微信账号ID\n  --agent    指定负责处理消息的 Agent 名称",
+        "look_for": "看到绑定成功的提示",
+        "tip": "💡 绑定是永久的，除非你重新执行绑定命令修改。"
+      }
+    },
+    {
+      "id": "bind-account-2",
+      "icon": "🔗",
+      "label": "绑定账号2 → Agent",
+      "type": "input",
+      "requires": ["check-accounts"],
+      "show_capture": "accounts_output",
+      "command": {
+        "template": "openclaw channels bind --channel openclaw-weixin --account {{account}} --agent {{agent}}",
+        "display":  "openclaw channels bind --channel openclaw-weixin --account {{account}} --agent {{agent}}"
+      },
+      "inputs": [
+        {
+          "key": "account",
+          "label": "账号2 的账号ID",
+          "hint": "从步骤4的输出中找到第二个账号的标识符",
+          "placeholder": "例如：wx_987654321"
+        },
+        {
+          "key": "agent",
+          "label": "要绑定到的 Agent 名称",
+          "hint": "填写另一个 Agent 的名称（与账号1绑定的不同）",
+          "placeholder": "例如：classroom、assistant"
+        }
+      ],
+      "teach": {
+        "title": "将账号2绑定到另一个 Agent",
+        "description": "这条命令将第二个微信账号绑定到另一个 Agent。\n\n多账号绑定的典型用法：\n  - 账号1 → Agent「blog」   ← 处理博客读者的问题\n  - 账号2 → Agent「classroom」← 处理学生课堂问题\n\n每个微信账号有自己专属的对话上下文和 Agent 配置。",
+        "look_for": "看到绑定成功的提示",
+        "tip": "💡 两个账号绑定的 Agent 不同，这正是多账号的意义所在。"
+      }
+    },
+    {
+      "id": "verify-bindings",
+      "icon": "✅",
+      "label": "验证绑定结果",
+      "type": "check",
+      "command": {
+        "exec": "openclaw channels status",
+        "display": "openclaw channels status"
+      },
+      "teach": {
+        "title": "验证所有账号的绑定情况",
+        "description": "最后查看账号状态，确认绑定配置正确。\n\n如果配置成功，你应该能看到：\n  - 账号1 → Agent 名称A\n  - 账号2 → Agent 名称B\n\n如果某个账号绑定不对，重新执行对应的绑定步骤（第5或第6步）。",
+        "look_for": "每个账号后面显示了正确的 Agent 名称",
+        "tip": "🎉 绑定完成后，从不同微信账号发消息，对应 Agent 会自动回复！"
+      }
+    }
+  ]
+}

package/wizards/configs/weixin/index.config.json

@@ -0,0 +1,117 @@
+{
+  "id": "weixin",
+  "title": "微信接入向导",
+  "subtitle": "引导你一步步完成微信通道的接入配置",
+
+  "steps": [
+    {
+      "id": "check-plugins",
+      "icon": "🔍",
+      "label": "查看微信插件状态",
+      "type": "check",
+      "command": {
+        "exec": "openclaw plugins list",
+        "display": "openclaw plugins list"
+      },
+      "teach": {
+        "title": "查看微信插件状态",
+        "description": "列出系统中当前已安装的所有 OpenClaw 插件。\n\nOpenClaw 通过「插件」来支持不同平台（微信、飞书、钉钉等），\n每个插件负责一个平台的通信协议。",
+        "look_for": "在输出中查找 openclaw-weixin，有就说明插件已安装",
+        "tip": "🔒 只读操作，不修改任何配置，可以随时查看。"
+      }
+    },
+    {
+      "id": "check-channels",
+      "icon": "🔍",
+      "label": "查看渠道连接状态",
+      "type": "check",
+      "command": {
+        "exec": "openclaw channels list",
+        "display": "openclaw channels list"
+      },
+      "teach": {
+        "title": "查看所有渠道的连接状态",
+        "description": "列出系统中所有已配置的「渠道（Channel）」。\n\n渠道是平台账号与 OpenClaw 的实际连接通道：\n  - 插件 = 能力（知道怎么对接微信）\n  - 渠道 = 连接（你的微信账号已登录并在线）\n\n两者都需要就绪，微信功能才能正常运行。",
+        "look_for": "查找 openclaw-weixin，状态是否为 connected",
+        "tip": "🔒 只读操作，不修改任何配置，可以随时查看。"
+      }
+    },
+    {
+      "id": "install-plugin",
+      "icon": "📦",
+      "label": "安装微信插件",
+      "type": "action",
+      "command": {
+        "exec": "openclaw plugins install \"@tencent-weixin/openclaw-weixin\"",
+        "display": "openclaw plugins install \"@tencent-weixin/openclaw-weixin\""
+      },
+      "teach": {
+        "title": "安装微信插件",
+        "description": "从官方源下载并安装微信通道插件。\n\n这条命令做了三件事：\n  1. 找到 @tencent-weixin/openclaw-weixin 插件包\n  2. 从官方源下载插件代码\n  3. 安装到 OpenClaw 插件目录\n\n整个接入流程只需安装一次，重新登录时不需要重复执行。",
+        "look_for": "看到 installed successfully 或类似成功提示",
+        "tip": "⚠️  需要网络连接，首次下载可能需要一点时间，请耐心等待。"
+      }
+    },
+    {
+      "id": "enable-plugin",
+      "icon": "⚙️",
+      "label": "启用微信插件",
+      "type": "action",
+      "command": {
+        "exec": "openclaw config set plugins.entries.openclaw-weixin.enabled true",
+        "display": "openclaw config set plugins.entries.openclaw-weixin.enabled true"
+      },
+      "teach": {
+        "title": "启用微信插件",
+        "description": "将微信插件的「启用状态」写入 OpenClaw 配置文件。\n\n安装插件 ≠ 启用插件。这类似于：\n  - 安装 = 把软件下载到电脑\n  - 启用 = 打开这个软件的开关\n\n这条命令修改了配置文件中的一个开关：\n  plugins.entries.openclaw-weixin.enabled = true",
+        "look_for": "命令无报错即为成功，配置通常立即生效",
+        "tip": "💡 安装和启用是两个独立步骤，缺一不可。"
+      }
+    },
+    {
+      "id": "login-weixin",
+      "icon": "📱",
+      "label": "扫码登录微信",
+      "type": "interactive",
+      "command": {
+        "exec": "openclaw channels login --channel openclaw-weixin",
+        "display": "openclaw channels login --channel openclaw-weixin"
+      },
+      "teach": {
+        "title": "扫码登录微信账号",
+        "description": "将你的微信账号与 OpenClaw 渠道绑定。\n\n执行后终端会显示一个二维码，操作步骤：\n  1. 打开手机微信\n  2. 点击右上角「+」→「扫一扫」\n  3. 扫描终端里的二维码\n  4. 手机上点击「确认授权」\n\n重新连接时，只需重复这一步，不需要重装插件。",
+        "look_for": "终端显示「登录成功」或类似提示",
+        "tip": "📱 准备好手机，扫码后在手机上点击确认才算完成。"
+      }
+    },
+    { "$ref": "../../commons/gateway.steps.json#restart" },
+    {
+      "id": "verify",
+      "icon": "✅",
+      "label": "验证微信接入是否成功",
+      "type": "check",
+      "command": {
+        "exec": "openclaw channels list",
+        "display": "openclaw channels list"
+      },
+      "teach": {
+        "title": "验证微信是否成功接入",
+        "description": "再次查看渠道列表，确认微信已正常连接。\n\n这和第 2 步用的是同一条命令，但现在应该能看到：\n  - openclaw-weixin 出现在列表中\n  - 状态显示为 connected（已连接）\n\n如果状态还是 disconnected，可能需要重新扫码（步骤 5）。",
+        "look_for": "openclaw-weixin 的状态为 connected ✅",
+        "tip": "🎉 如果看到 connected，恭喜完成微信接入！"
+      }
+    },
+    {
+      "id": "multi-account",
+      "icon": "👥",
+      "label": "多账号绑定（进阶）",
+      "type": "submenu",
+      "submenu": "./bind.config.json",
+      "teach": {
+        "title": "微信多账号绑定",
+        "description": "如果你需要让多个微信账号分别对接不同的 Agent，\n可以进入这个子向导完成配置。\n\n适用场景：\n  - 一个 Agent 负责课堂答疑（账号A）\n  - 另一个 Agent 负责生活助手（账号B）\n\n普通接入不需要这一步，完成步骤 1-7 即可。",
+        "tip": "💡 按 Enter 进入子向导，按 q 随时返回此页面。"
+      }
+    }
+  ]
+}

package/wizards/index.js

@@ -0,0 +1,32 @@
+'use strict';
+
+/**
+ * wizards/index.js
+ * ────────────────────────────────────────────────────────
+ * 所有向导的统一入口
+ *
+ * 新增向导只需：
+ *   1. 在 configs/ 下建目录，写 index.config.json
+ *   2. 在这里 `startWizard(path.join(...))` 注册一个入口函数
+ */
+
+const path             = require('path');
+const { WizardRunner } = require('./runner/wizard-runner');
+const { loadConfig }   = require('./runner/config-loader');
+
+function startWizard(configPath) {
+  const config = loadConfig(configPath);
+  new WizardRunner(config).run();
+}
+
+// ── 各向导入口 ────────────────────────────────────────────────
+
+function runWeixin() {
+  startWizard(path.join(__dirname, 'configs/weixin/index.config.json'));
+}
+
+// 未来扩展示例：
+// function runGateway() { startWizard(path.join(__dirname, 'configs/gateway/index.config.json')); }
+// function runAgent()   { startWizard(path.join(__dirname, 'configs/agent/index.config.json'));   }
+
+module.exports = { runWeixin };

package/wizards/runner/config-loader.js

@@ -0,0 +1,89 @@
+'use strict';
+
+/**
+ * config-loader.js
+ * ──────────────────────────────────────────────────────────
+ * Wizard config 加载器
+ *
+ * 功能：
+ *   1. 加载 JSON config 文件并注入 _dir（用于解析相对路径）
+ *   2. 展开 steps 中的 $ref 引用（指向公共步骤片段）
+ *
+ * $ref 格式：
+ *   { "$ref": "../../commons/gateway.steps.json#restart" }
+ *       ↑ 文件路径（相对于当前 config 所在目录）   ↑ 步骤 key
+ *
+ *   如果不加 #key，则将整个文件的值视为步骤（需是数组或对象）。
+ *
+ * 公共步骤文件格式（commons/xxx.steps.json）：
+ *   {
+ *     "restart": { ...step对象... },
+ *     "check-health": { ...step对象... }
+ *   }
+ */
+
+const path = require('path');
+
+/**
+ * 加载并解析 wizard config
+ * @param {string} configPath - 绝对路径
+ * @returns {Object} 解析后的 config（steps 已展开 $ref）
+ */
+function loadConfig(configPath) {
+  // delete require cache 确保每次都重新读取（方便开发调试）
+  delete require.cache[require.resolve(configPath)];
+
+  const raw     = require(configPath);
+  const baseDir = path.dirname(configPath);
+
+  const steps = _expandSteps(raw.steps || [], baseDir);
+
+  return { ...raw, steps, _dir: baseDir };
+}
+
+/**
+ * 展开 steps 数组中的 $ref 项
+ */
+function _expandSteps(steps, baseDir) {
+  const result = [];
+
+  for (const step of steps) {
+    if (step.$ref) {
+      const expanded = _resolveRef(step.$ref, baseDir);
+      if (Array.isArray(expanded)) {
+        result.push(...expanded);
+      } else {
+        result.push(expanded);
+      }
+    } else {
+      result.push(step);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 解析单个 $ref 字符串
+ * @param {string} ref - "path/to/file.json#key"
+ * @param {string} baseDir - 当前 config 所在目录
+ */
+function _resolveRef(ref, baseDir) {
+  const [filePart, key] = ref.split('#');
+  const absPath = path.resolve(baseDir, filePart);
+
+  // 每次都清缓存，保持公共步骤文件可热更新
+  delete require.cache[require.resolve(absPath)];
+  const file = require(absPath);
+
+  if (key) {
+    if (!file[key]) {
+      throw new Error(`[config-loader] $ref "${ref}" 中找不到 key "${key}"`);
+    }
+    return file[key];
+  }
+
+  return file;
+}
+
+module.exports = { loadConfig };

package/wizards/runner/input-prompt.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * input-prompt.js
+ * ─────────────────────────────────────────────────────
+ * 通用「参数填写」交互模块
+ *
+ * 用于 input 类型的步骤：执行命令前需要用户填写动态参数。
+ * 暂时退出 raw mode → 用 readline 逐个收集参数 → 恢复 raw mode。
+ *
+ * 可复用于任何需要在 TUI 会话中收集用户输入的场景。
+ */
+
+const readline = require('readline');
+const chalk    = require('chalk');
+const { hr, W } = require('./render');
+
+/**
+ * 收集一组用户输入参数
+ *
+ * @param {Array<InputDef>} inputs
+ *   InputDef: { key, label, hint?, placeholder? }
+ * @returns {Promise<Object>} - { [key]: value }
+ */
+async function collectInputs(inputs) {
+  // 退出 raw mode，使 readline 能正常接收输入
+  process.stdin.setRawMode(false);
+
+  const values = {};
+
+  for (const input of inputs) {
+    values[input.key] = await _ask(input);
+  }
+
+  // 恢复 raw mode
+  // readline.close() 内部会 pause stdin，必须显式 resume 否则后续监听失效
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+
+  return values;
+}
+
+/**
+ * 显示单个参数的输入提示并等待用户输入
+ */
+function _ask(input) {
+  return new Promise(resolve => {
+    const rl = readline.createInterface({
+      input:    process.stdin,
+      output:   process.stdout,
+      terminal: true,
+    });
+
+    // Ctrl+C 优雅处理：恢复 raw mode 后退出
+    rl.on('SIGINT', () => {
+      rl.close();
+      // 恢复 raw mode，然后退出程序
+      try { process.stdin.setRawMode(true); } catch (_) {}
+      console.log('');
+      console.log('  ' + chalk.cyan('已取消。再见！👋'));
+      console.log('');
+      process.exit(0);
+    });
+
+    // 显示 hint
+    if (input.hint) {
+      console.log('  ' + chalk.dim('💡 ' + input.hint));
+    }
+    if (input.placeholder) {
+      console.log('  ' + chalk.dim('   例如：' + input.placeholder));
+    }
+
+    rl.question(
+      '  ' + chalk.bold.white(input.label) + chalk.dim('：'),
+      answer => {
+        rl.close();
+        resolve(answer.trim() || '');
+      }
+    );
+  });
+}
+
+/**
+ * 用参数值替换命令模板中的 {{key}} 占位符
+ *
+ * @param {string} template - 含 {{key}} 的模板字符串
+ * @param {Object} values   - { key: value }
+ * @returns {string}
+ */
+function fillTemplate(template, values) {
+  return template.replace(/\{\{(\w+)\}\}/g, (_, key) => {
+    return values[key] !== undefined ? values[key] : `<${key}>`;
+  });
+}
+
+module.exports = { collectInputs, fillTemplate };

package/wizards/runner/render.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * render.js
+ * ─────────────────────────────────────────
+ * 通用渲染工具
+ *
+ * W 改为动态读取终端宽度（getW），每次 render 时实时计算，
+ * 支持终端窗口 resize 后自动适配。
+ */
+
+const chalk = require('chalk');
+
+/**
+ * 获取当前终端宽度（限制在 50~80 之间）
+ */
+function getW() {
+  const cols = process.stdout.columns;
+  if (!cols || cols < 50) return 66; // 无法获取或过窄时使用默认值
+  return Math.min(cols - 2, 80);
+}
+
+function hr(char = '─', w) {
+  return char.repeat(w || getW());
+}
+
+function cls() {
+  process.stdout.write('\x1b[2J\x1b[H');
+}
+
+/**
+ * 多行文本缩进
+ */
+function indent(text, prefix = '  ') {
+  return text.split('\n').map(l => prefix + l).join('\n');
+}
+
+/**
+ * 步骤状态标签
+ */
+const BADGE = {
+  check:   () => chalk.bgCyan.black('  查看  '),
+  pending: () => chalk.bgGray.white(' 未执行 '),
+  done:    () => chalk.bgGreen.black(' ✓ 完成 '),
+  error:   () => chalk.bgRed.white('  ✗ 失败  '),
+  submenu: () => chalk.bgMagenta.white(' ▸ 子向导 '),
+  input:   () => chalk.bgYellow.black(' 填参数 '),
+};
+
+/**
+ * 渲染命令行（自动折行）
+ */
+function renderCommand(display) {
+  if (!display) return;
+  const W = getW();
+  const maxLen = W - 10;
+
+  if (display.length <= maxLen) {
+    console.log('  ' + chalk.bgBlack.cyan(' $ ') + chalk.bgBlack.white(' ' + display + ' '));
+    return;
+  }
+
+  // 按空格拆词后贪心折行
+  const words = display.split(' ');
+  const lines = [];
+  let   cur   = '';
+
+  for (const word of words) {
+    const next = cur ? cur + ' ' + word : word;
+    if (next.length > maxLen && cur) {
+      lines.push(cur);
+      cur = word;
+    } else {
+      cur = next;
+    }
+  }
+  if (cur) lines.push(cur);
+
+  lines.forEach((line, i) => {
+    const prefix = i === 0
+      ? chalk.bgBlack.cyan(' $ ')
+      : chalk.bgBlack.dim('   ');
+    console.log('  ' + prefix + chalk.bgBlack.white(' ' + line + ' '));
+  });
+}
+
+module.exports = { getW, hr, cls, indent, BADGE, renderCommand };

package/wizards/runner/wizard-runner.js

@@ -0,0 +1,541 @@
+'use strict';
+
+/**
+ * wizard-runner.js
+ * ──────────────────────────────────────────────────────────────
+ * 通用 TUI 向导引擎
+ *
+ * ── 支持的 step 类型 ──────────────────────────────────────────
+ *   check       只读查询（execSync，可反复运行）
+ *   action      有副作用的操作（execSync）
+ *   interactive 需要终端交互（spawnSync + inherit stdio，如扫码）
+ *   input       执行前需填写动态参数（collectInputs + fillTemplate）
+ *   submenu     进入子向导（栈式导航，q 键返回上一级）
+ *
+ * ── step 扩展字段 ────────────────────────────────────────────
+ *   requires: ["step-id"]   执行前检查前置步骤是否已完成
+ *   capture: "var_name"     执行后把输出存入 context.captures
+ *   show_capture: "var_name" input 步骤填参前展示指定 capture 作为参考
+ *
+ * ── 交互快捷键 ───────────────────────────────────────────────
+ *   ↑ ↓         上下移动光标
+ *   1-9         数字快速跳转到对应步骤
+ *   Enter       执行当前步骤
+ *   q / Ctrl+C  退出（子向导返回上一级）
+ *
+ * ── 共享 Context ─────────────────────────────────────────────
+ *   父子向导共用同一个 context 对象：
+ *     context.captures: { [var_name]: string }  输出捕获
+ *
+ * ── 栈式导航 ─────────────────────────────────────────────────
+ *   顶级向导：q → 退出程序
+ *   子向导：opts.onExit 回调父级，键盘控制权归还父级
+ */
+
+const path   = require('path');
+const chalk  = require('chalk');
+const { execSync, spawnSync } = require('child_process');
+
+const { getW, hr, cls, indent, BADGE, renderCommand } = require('./render');
+const { collectInputs, fillTemplate }                  = require('./input-prompt');
+const { loadConfig }                                   = require('./config-loader');
+
+// ─────────────────────────────────────────────────────────────
+
+class WizardRunner {
+  /**
+   * @param {Object} config         - wizard config（含 steps[]，已由 config-loader 处理）
+   * @param {Object} [opts]
+   * @param {Function} [opts.onExit]  - 有值 = 子向导模式，退出时回调父级
+   * @param {Object} [opts.context]   - 共享 context（父子向导共用）
+   */
+  constructor(config, opts = {}) {
+    this.config   = config;
+    this.steps    = config.steps;
+    this.cursor   = 0;
+    this._busy    = false;
+    this.onExit   = opts.onExit   || null;
+    this._handler = null;
+    this._resizeHandler = null;
+
+    // 共享 context（父子向导共用同一对象）
+    this.context = opts.context || { captures: {} };
+
+    // 初始化每步状态
+    this.statuses = {};
+    this.steps.forEach(s => {
+      if      (s.type === 'check')   this.statuses[s.id] = 'check';
+      else if (s.type === 'submenu') this.statuses[s.id] = 'submenu';
+      else                           this.statuses[s.id] = 'pending';
+    });
+  }
+
+  // ── 渲染：主界面 ────────────────────────────────────────────
+
+  render() {
+    cls();
+    const W = getW();
+    const { config, steps, cursor, statuses } = this;
+    const isChild = !!this.onExit;
+
+    console.log('');
+
+    if (isChild) {
+      console.log(
+        '  ' + chalk.dim('← q 返回') + '  ' +
+        chalk.bold.cyan('⚡ ' + config.title)
+      );
+    } else {
+      console.log('  ' + chalk.bold.cyan('⚡ ' + config.title));
+    }
+    console.log('  ' + chalk.gray(config.subtitle || ''));
+    console.log('');
+
+    // 步骤列表
+    const navHint = isChild
+      ? chalk.dim(' ( ↑↓/数字 移动    Enter 执行    q 返回 )')
+      : chalk.dim(' ( ↑↓/数字 移动    Enter 执行    q 退出 )');
+
+    console.log('  ' + chalk.bold('步骤列表') + navHint);
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+
+    steps.forEach((step, i) => {
+      const sel   = i === cursor;
+      const arrow = sel ? chalk.cyan.bold('▶') : ' ';
+      const num   = chalk.dim(String(i + 1).padStart(2) + '.');
+      const label = sel ? chalk.bold.white(step.label) : chalk.white(step.label);
+      const badge = (BADGE[statuses[step.id]] || BADGE.pending)();
+
+      // requires 未满足时显示锁定标记
+      const locked = this._isLocked(step);
+      const lockMark = locked ? chalk.dim(' 🔒') : '';
+
+      console.log(`  ${arrow} ${num} ${step.icon}  ${label}${lockMark}  ${badge}`);
+    });
+
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+    console.log('');
+
+    // 说明区
+    const step  = steps[cursor];
+    const teach = step.teach;
+
+    console.log('  ' + chalk.bold.yellow('📖 步骤说明'));
+    console.log('');
+    console.log('  ' + chalk.bold.white('【' + teach.title + '】'));
+    console.log('');
+    console.log(indent(teach.description, '  '));
+    console.log('');
+
+    // 命令预览 or 子向导提示
+    if (step.type === 'submenu') {
+      console.log('  ' + chalk.magenta('▸  按 Enter 进入子向导'));
+    } else if (step.type === 'input') {
+      console.log('  ' + chalk.dim('命令模板（参数待填写）：'));
+      renderCommand(step.command.template);
+    } else if (step.command) {
+      console.log('  ' + chalk.dim('执行命令：'));
+      renderCommand(step.command.display || step.command.exec);
+    }
+    console.log('');
+
+    if (teach.look_for) {
+      console.log('  ' + chalk.dim('👀 执行后观察：') + chalk.yellow(teach.look_for));
+      console.log('');
+    }
+    if (teach.tip) {
+      console.log('  ' + chalk.dim('💡 ') + chalk.gray(teach.tip));
+      console.log('');
+    }
+
+    // requires 提示（主界面也显示）
+    if (this._isLocked(step)) {
+      const missing = this._getMissingRequires(step);
+      console.log('  ' + chalk.yellow('🔒 建议先完成：'));
+      missing.forEach(id => {
+        const idx = this.steps.findIndex(s => s.id === id);
+        const s   = this.steps[idx];
+        console.log('  ' + chalk.dim('   → 步骤 ' + (idx + 1) + '：' + (s ? s.label : id)));
+      });
+      console.log('');
+    }
+  }
+
+  // ── 执行步骤（分发） ─────────────────────────────────────────
+
+  async executeStep(idx) {
+    const step = this.steps[idx];
+
+    // requires 前置检查
+    if (this._isLocked(step)) {
+      const ok = await this._showRequiresWarning(step);
+      if (!ok) { this.render(); return; }
+    }
+
+    switch (step.type) {
+      case 'submenu': return this._openSubmenu(step);
+      case 'input':   return this._executeInputStep(step);
+      default:        return this._executeCommandStep(step);
+    }
+  }
+
+  // ── requires 相关 ────────────────────────────────────────────
+
+  _isLocked(step) {
+    return this._getMissingRequires(step).length > 0;
+  }
+
+  _getMissingRequires(step) {
+    if (!step.requires || !step.requires.length) return [];
+    return step.requires.filter(id => this.statuses[id] !== 'done');
+  }
+
+  async _showRequiresWarning(step) {
+    const W       = getW();
+    const missing = this._getMissingRequires(step);
+
+    cls();
+    console.log('');
+    console.log('  ' + chalk.bold.yellow('🔒 前置步骤未完成'));
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+    console.log('');
+    console.log('  建议在执行「' + chalk.bold(step.label) + '」之前先完成：');
+    console.log('');
+
+    missing.forEach(id => {
+      const idx = this.steps.findIndex(s => s.id === id);
+      const s   = this.steps[idx];
+      console.log('  ' + chalk.yellow('  → 步骤 ' + (idx + 1) + '：' + (s ? s.label : id)));
+    });
+
+    console.log('');
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+    console.log(
+      '  ' + chalk.dim('按 Enter 仍然继续') +
+      chalk.dim('  |  按 q 返回先完成前置步骤')
+    );
+
+    return this._waitConfirm();
+  }
+
+  // ── submenu：进入子向导 ──────────────────────────────────────
+
+  async _openSubmenu(step) {
+    const baseDir    = this.config._dir || __dirname;
+    const configPath = path.resolve(baseDir, step.submenu);
+    const subConfig  = loadConfig(configPath);
+
+    this._removeKeyboard();
+
+    const sub = new WizardRunner(subConfig, {
+      context: this.context,   // 共享同一个 context
+      onExit: () => {
+        this._setupKeyboard();
+        this.render();
+      },
+    });
+
+    sub.run();
+  }
+
+  // ── 普通命令步骤 ─────────────────────────────────────────────
+
+  async _executeCommandStep(step) {
+    const W     = getW();
+    const teach = step.teach;
+
+    cls();
+    console.log('');
+    console.log('  ' + chalk.bold.cyan('▶ 执行：' + step.icon + '  ' + step.label));
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+    console.log('');
+    console.log('  ' + chalk.bold.yellow('📋 执行前说明'));
+    console.log('');
+    console.log(indent(teach.description, '  '));
+    console.log('');
+    console.log('  ' + chalk.bold('将要执行的命令：'));
+    console.log('');
+    renderCommand(step.command.display || step.command.exec);
+    console.log('');
+
+    if (step.type === 'interactive') {
+      console.log('  ' + chalk.yellow('⚠️  此步骤是交互式操作（如显示二维码），将接管终端'));
+      console.log('');
+    }
+
+    // capture 提示
+    if (step.capture) {
+      console.log('  ' + chalk.cyan('📥 执行结果将被记录，供后续步骤参考使用'));
+      console.log('');
+    }
+
+    if (teach.tip) {
+      console.log('  ' + chalk.dim('💡 ') + chalk.gray(teach.tip));
+      console.log('');
+    }
+
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+    console.log('  ' + chalk.dim('按 Enter 开始执行  |  按 q 取消'));
+
+    const ok = await this._waitConfirm();
+    if (!ok) { this.render(); return; }
+
+    await this._runCommand(step, step.command.exec || step.command.display);
+  }
+
+  // ── input 步骤：填参数后执行 ─────────────────────────────────
+
+  async _executeInputStep(step) {
+    const W     = getW();
+    const teach = step.teach;
+
+    // 第一页：说明 + 模板
+    cls();
+    console.log('');
+    console.log('  ' + chalk.bold.cyan('▶ 执行：' + step.icon + '  ' + step.label));
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+    console.log('');
+    console.log('  ' + chalk.bold.yellow('📋 执行前说明'));
+    console.log('');
+    console.log(indent(teach.description, '  '));
+    console.log('');
+    console.log('  ' + chalk.bold('命令模板（需要填写参数）：'));
+    console.log('');
+    renderCommand(step.command.template);
+    console.log('');
+
+    if (teach.tip) {
+      console.log('  ' + chalk.dim('💡 ') + chalk.gray(teach.tip));
+      console.log('');
+    }
+
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+    console.log('  ' + chalk.dim('按 Enter 开始填写参数  |  按 q 取消'));
+
+    const ok = await this._waitConfirm();
+    if (!ok) { this.render(); return; }
+
+    // 第二页：参考信息 + 填写参数
+    cls();
+    console.log('');
+    console.log('  ' + chalk.bold.cyan('📝 填写参数：' + step.label));
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+
+    // 如果有 show_capture，展示参考信息（教学重点）
+    if (step.show_capture) {
+      const captured = this.context.captures[step.show_capture];
+      if (captured && captured.trim()) {
+        console.log('');
+        console.log('  ' + chalk.bold.yellow('📋 参考信息（来自上一步执行结果）：'));
+        console.log('  ' + chalk.gray(hr('─', W - 4)));
+        // 显示捕获的输出（限制 30 行，避免超出屏幕）
+        const lines = captured.split('\n').filter(l => l.trim());
+        const shown = lines.slice(0, 30);
+        shown.forEach(l => console.log('  ' + chalk.dim(l)));
+        if (lines.length > 30) {
+          console.log('  ' + chalk.dim('... 输出已截断，共 ' + lines.length + ' 行'));
+        }
+        console.log('  ' + chalk.gray(hr('─', W - 4)));
+      } else {
+        console.log('');
+        console.log('  ' + chalk.yellow('⚠️  暂无参考信息（建议先执行对应的查看步骤）'));
+      }
+    }
+
+    console.log('');
+
+    const values    = await collectInputs(step.inputs);
+    const actualCmd = fillTemplate(step.command.template, values);
+
+    // 第三页：确认最终命令
+    cls();
+    console.log('');
+    console.log('  ' + chalk.bold.cyan('✅ 确认执行：' + step.icon + '  ' + step.label));
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+    console.log('');
+    console.log('  ' + chalk.bold('已填入参数，将要执行：'));
+    console.log('');
+    renderCommand(actualCmd);
+    console.log('');
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+    console.log(
+      '  ' + chalk.dim('按 ') + chalk.bold.green('y') +
+      chalk.dim(' 确认执行  |  按其他键取消（防止误触）')
+    );
+
+    const finalOk = await this._waitYesConfirm();
+    if (!finalOk) { this.render(); return; }
+
+    await this._runCommand({ ...step, type: 'action' }, actualCmd);
+  }
+
+  // ── 实际运行命令 ─────────────────────────────────────────────
+
+  async _runCommand(step, cmdStr) {
+    const W = getW();
+    cls();
+    console.log('');
+    console.log('  ' + chalk.bold.cyan('⚡ 正在执行：' + step.label));
+    console.log('  ' + chalk.dim('$ ' + cmdStr));
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+    console.log('');
+    console.log('  ' + chalk.dim('↓ 命令输出 ↓'));
+    console.log('');
+
+    process.stdin.setRawMode(false);
+
+    let success = false;
+
+    try {
+      if (step.capture) {
+        // 捕获 stdout，同时透传 stdin/stderr
+        const result = spawnSync(cmdStr, {
+          shell:  true,
+          stdio:  ['inherit', 'pipe', 'inherit'],
+          encoding: 'utf8',
+        });
+        const output = result.stdout || '';
+        process.stdout.write(output);                    // 显示给学生看
+        this.context.captures[step.capture] = output;   // 同时存起来
+        success = result.status === 0;
+      } else if (step.type === 'interactive') {
+        const r = spawnSync(cmdStr, { shell: true, stdio: 'inherit' });
+        success = r.status === 0;
+      } else {
+        execSync(cmdStr, { shell: true, stdio: 'inherit' });
+        success = true;
+      }
+    } catch { success = false; }
+
+    process.stdin.setRawMode(true);
+    process.stdin.resume(); // 命令执行完毕后确保 stdin 处于 flowing 状态
+    this.statuses[step.id] = success ? 'done' : 'error';
+
+
+    // ── 成功后光标自动推进到下一步 ──
+    if (success && this.cursor < this.steps.length - 1) {
+      this.cursor++;
+    }
+
+    console.log('');
+    console.log('  ' + chalk.gray(hr('─', W - 4)));
+
+    if (success) {
+      console.log('  ' + chalk.bold.green('✓ 执行完成！'));
+      if (step.teach?.look_for) {
+        console.log('  ' + chalk.yellow('👆 观察上方输出：' + step.teach.look_for));
+      }
+      if (step.capture) {
+        console.log('  ' + chalk.cyan('📥 输出已记录，后续步骤可作为参考'));
+      }
+      if (this.cursor > 0) {
+        const next = this.steps[this.cursor];
+        console.log('  ' + chalk.dim('→ 下一步：' + next.icon + ' ' + next.label));
+      }
+    } else {
+      console.log('  ' + chalk.bold.red('✗ 执行遇到问题，请查看上方错误信息'));
+    }
+
+    console.log('');
+    console.log('  ' + chalk.dim('按任意键返回步骤列表...'));
+
+    await this._waitAnyKey();
+    this.render();
+  }
+
+  // ── 键盘管理 ─────────────────────────────────────────────────
+
+  _onData(buf) {
+    if (this._busy) return;
+    const k = buf.toString();
+
+    // 数字快速跳转（1-9）
+    const num = parseInt(k, 10);
+    if (!isNaN(num) && num >= 1 && num <= this.steps.length) {
+      this.cursor = num - 1;
+      this.render();
+      return;
+    }
+
+    if      (k === '\x1b[A')                          { this.cursor = Math.max(0, this.cursor - 1); this.render(); }
+    else if (k === '\x1b[B')                          { this.cursor = Math.min(this.steps.length - 1, this.cursor + 1); this.render(); }
+    else if (k === '\r' || k === '\n')                { this._busy = true; this.executeStep(this.cursor).finally(() => { this._busy = false; }); }
+    else if (k === 'q' || k === 'Q' || k === '\x03') { this.exit(); }
+  }
+
+  _setupKeyboard() {
+    this._handler = buf => this._onData(buf);
+    process.stdin.on('data', this._handler);
+  }
+
+  _removeKeyboard() {
+    if (this._handler) {
+      process.stdin.removeListener('data', this._handler);
+      this._handler = null;
+    }
+  }
+
+  // Enter/空格/任意非 q 键 → 确认
+  _waitConfirm() {
+    return new Promise(resolve => {
+      process.stdin.once('data', buf => {
+        const k = buf.toString();
+        resolve(k !== 'q' && k !== 'Q' && k !== '\x03');
+      });
+    });
+  }
+
+  // 严格确认：只接受 y/Y 键（用于 input 步骤的最终执行确认）
+  // 规避 readline 关闭后残留 Enter 误触发的问题
+  _waitYesConfirm() {
+    return new Promise(resolve => {
+      const handler = (buf) => {
+        const k = buf.toString().toLowerCase();
+        // 过滤掉残留的 Enter/换行（来自 readline）
+        if (k === '\r' || k === '\n' || k === '\r\n') return;
+        process.stdin.removeListener('data', handler);
+        resolve(k === 'y');
+      };
+      process.stdin.on('data', handler);
+    });
+  }
+
+  _waitAnyKey() {
+    return new Promise(resolve => process.stdin.once('data', resolve));
+  }
+
+  // ── 入口 & 退出 ──────────────────────────────────────────────
+
+  run() {
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    this._setupKeyboard();
+
+    // 终端 resize 时自动重绘
+    this._resizeHandler = () => this.render();
+    process.stdout.on('resize', this._resizeHandler);
+
+    this.render();
+  }
+
+  exit() {
+    this._removeKeyboard();
+
+    // 清理 resize 监听
+    if (this._resizeHandler) {
+      process.stdout.removeListener('resize', this._resizeHandler);
+      this._resizeHandler = null;
+    }
+
+    if (this.onExit) {
+      this.onExit();
+    } else {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      console.log('\n  ' + chalk.cyan('再见！👋') + '\n');
+      process.exit(0);
+    }
+  }
+}
+
+module.exports = { WizardRunner };