@zhin.js/scaffold-wizard 0.2.3 → 0.2.5

package/src/adapter-configurers.ts

@@ -22,10 +22,10 @@ export interface EndpointConfigureContext {
 export async function configureTelegramEndpoint(ctx: EndpointConfigureContext): Promise<Record<string, unknown>> {
   console.log(chalk.gray('     文档: ' + adapterDocsUrl('telegram')));
 
-  const { endpointName } = await inquirer.prompt([
+  const { endpointId } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'endpointName',
+      name: 'endpointId',
       message: '  Endpoint 标识名称:',
       default: 'telegram-bot',
       validate: (v: string) => (v.trim() ? true : '名称不能为空'),
@@ -61,10 +61,10 @@ export async function configureTelegramEndpoint(ctx: EndpointConfigureContext):
     },
   ]);
 
-  // schema：polling / webhook 为顶层共享字段；name / token 为 endpoint 级
+  // schema：polling / webhook 为顶层共享字段；id / token 为 endpoint 级
   const config: Record<string, unknown> = {
     polling: transport === 'polling',
-    endpoints: [{ name: endpointName.trim(), token: '${TELEGRAM_TOKEN}' }],
+    endpoints: [{ id: endpointId.trim(), token: '${TELEGRAM_TOKEN}' }],
   };
 
   if (transport === 'webhook') {
@@ -106,10 +106,10 @@ export async function configureGitHubEndpoint(ctx: EndpointConfigureContext): Pr
   console.log(chalk.gray('     文档: ' + adapterDocsUrl('github')));
   ctx.markRequiresDatabase();
 
-  const { endpointName } = await inquirer.prompt([
+  const { endpointId } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'endpointName',
+      name: 'endpointId',
       message: '  Endpoint 标识名称:',
       default: 'github-bot',
       validate: (v: string) => (v.trim() ? true : '名称不能为空'),
@@ -137,7 +137,7 @@ export async function configureGitHubEndpoint(ctx: EndpointConfigureContext): Pr
 
   // schema：app_id / private_key / webhook_secret 为 endpoint 级；webhook_path / poll_interval 为顶层共享字段
   const endpointConfig: Record<string, unknown> = {
-    name: endpointName.trim(),
+    id: endpointId.trim(),
   };
   const sharedConfig: Record<string, unknown> = {};
 
@@ -267,19 +267,19 @@ export async function configureOneBot11Bot(ctx: EndpointConfigureContext): Promi
     },
   ]);
 
-  const { endpointName } = await inquirer.prompt([
+  const { endpointId } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'endpointName',
+      name: 'endpointId',
       message: '  Endpoint 标识名称:',
       default: 'onebot-bot',
       validate: (v: string) => (v.trim() ? true : '名称不能为空'),
     },
   ]);
 
-  // schema：connection 为顶层共享字段；name / url / path / access_token 为 endpoint 级
+  // schema：connection 为顶层共享字段；id / url / path / access_token 为 endpoint 级
   const endpointConfig: Record<string, unknown> = {
-    name: endpointName.trim(),
+    id: endpointId.trim(),
   };
 
   if (connection === 'ws') {
@@ -351,7 +351,7 @@ export async function configureQQBot(ctx: EndpointConfigureContext): Promise<Rec
   ctx.envVars.QQ_APP_ID = credentials.appID.trim();
   ctx.envVars.QQ_SECRET = credentials.secret;
 
-  const { mode, sandbox } = await inquirer.prompt([
+  const { mode, sandbox, botKind } = await inquirer.prompt([
     {
       type: 'select',
       name: 'mode',
@@ -368,16 +368,45 @@ export async function configureQQBot(ctx: EndpointConfigureContext): Promise<Rec
       message: '  沙箱环境 (sandbox)?',
       default: false,
     },
+    {
+      type: 'select',
+      name: 'botKind',
+      message: '  公域 / 私域（决定频道消息 intents；群聊两边都有）:',
+      choices: [
+        {
+          name: 'public — 公域（频道仅 @；+ 群聊/私聊）',
+          value: 'public',
+        },
+        {
+          name: 'private — 私域（频道全量消息；+ 群聊/私聊；公域勿选）',
+          value: 'private',
+        },
+      ],
+      default: 'public',
+    },
   ]);
 
-  // schema：mode / sandbox 为顶层共享字段；name / appid / secret 为 endpoint 级
+  const sharedIntents = [
+    'GROUP_AND_C2C_EVENT',
+    'GUILDS',
+    'GUILD_MEMBERS',
+    'DIRECT_MESSAGE',
+  ];
+  const intents =
+    botKind === 'private'
+      ? [...sharedIntents, 'GUILD_MESSAGES']
+      : [...sharedIntents, 'PUBLIC_GUILD_MESSAGES'];
+
+  // schema：mode / sandbox 可顶层共享；botKind / intents 写在 endpoint，与扫码绑定一致
   return {
     mode,
     sandbox,
     endpoints: [{
-      name: credentials.name.trim(),
+      id: credentials.name.trim(),
       appid: '${QQ_APP_ID}',
       secret: '${QQ_SECRET}',
+      botKind,
+      intents,
     }],
   };
 }
@@ -398,10 +427,10 @@ export async function configureDiscordEndpoint(ctx: EndpointConfigureContext): P
     },
   ]);
 
-  const { endpointName, token } = await inquirer.prompt([
+  const { endpointId, token } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'endpointName',
+      name: 'endpointId',
       message: '  Endpoint 标识名称:',
       default: 'discord-bot',
       validate: (v: string) => (v.trim() ? true : '名称不能为空'),
@@ -415,10 +444,10 @@ export async function configureDiscordEndpoint(ctx: EndpointConfigureContext): P
   ]);
   ctx.envVars.DISCORD_TOKEN = token;
 
-  // schema：connection / applicationId / publicKey / interactionsPath 为顶层共享字段；name / token 为 endpoint 级
+  // schema：connection / applicationId / publicKey / interactionsPath 为顶层共享字段；id / token 为 endpoint 级
   const config: Record<string, unknown> = {
     connection,
-    endpoints: [{ name: endpointName.trim(), token: '${DISCORD_TOKEN}' }],
+    endpoints: [{ id: endpointId.trim(), token: '${DISCORD_TOKEN}' }],
   };
 
   if (connection === 'interactions') {
@@ -467,10 +496,10 @@ export async function configureSlackEndpoint(ctx: EndpointConfigureContext): Pro
     },
   ]);
 
-  const { endpointName, token, signingSecret } = await inquirer.prompt([
+  const { endpointId, token, signingSecret } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'endpointName',
+      name: 'endpointId',
       message: '  Endpoint 标识名称:',
       default: 'slack-bot',
       validate: (v: string) => (v.trim() ? true : '名称不能为空'),
@@ -492,9 +521,9 @@ export async function configureSlackEndpoint(ctx: EndpointConfigureContext): Pro
   ctx.envVars.SLACK_BOT_TOKEN = token;
   ctx.envVars.SLACK_SIGNING_SECRET = signingSecret;
 
-  // schema：socketMode 为顶层共享字段；name / token / signingSecret / appToken 为 endpoint 级
+  // schema：socketMode 为顶层共享字段；id / token / signingSecret / appToken 为 endpoint 级
   const endpointConfig: Record<string, unknown> = {
-    name: endpointName.trim(),
+    id: endpointId.trim(),
     token: '${SLACK_BOT_TOKEN}',
     signingSecret: '${SLACK_SIGNING_SECRET}',
   };
@@ -534,19 +563,19 @@ export async function configureNapcatBot(ctx: EndpointConfigureContext): Promise
     },
   ]);
 
-  const { endpointName } = await inquirer.prompt([
+  const { endpointId } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'endpointName',
+      name: 'endpointId',
       message: '  Endpoint 标识名称:',
       default: 'napcat-bot',
       validate: (v: string) => (v.trim() ? true : '名称不能为空'),
     },
   ]);
 
-  // schema：connection 为顶层共享字段；name / url / path / http_url / post_path / access_token 为 endpoint 级
+  // schema：connection 为顶层共享字段；id / url / path / http_url / post_path / access_token 为 endpoint 级
   const endpointConfig: Record<string, unknown> = {
-    name: endpointName.trim(),
+    id: endpointId.trim(),
   };
 
   if (connection === 'ws') {
@@ -626,19 +655,19 @@ export async function configureOneBot12Bot(ctx: EndpointConfigureContext): Promi
     },
   ]);
 
-  const { endpointName } = await inquirer.prompt([
+  const { endpointId } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'endpointName',
+      name: 'endpointId',
       message: '  Endpoint 标识名称:',
       default: 'onebot12-bot',
       validate: (v: string) => (v.trim() ? true : '名称不能为空'),
     },
   ]);
 
-  // schema：connection 为顶层共享字段；name / url / path / api_url / access_token 为 endpoint 级
+  // schema：connection 为顶层共享字段；id / url / path / api_url / access_token 为 endpoint 级
   const endpointConfig: Record<string, unknown> = {
-    name: endpointName.trim(),
+    id: endpointId.trim(),
   };
 
   if (connection === 'ws') {
@@ -719,10 +748,10 @@ export async function configureMilkyBot(ctx: EndpointConfigureContext): Promise<
     },
   ]);
 
-  const { endpointName, baseUrl } = await inquirer.prompt([
+  const { endpointId, baseUrl } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'endpointName',
+      name: 'endpointId',
       message: '  Endpoint 标识名称:',
       default: 'milky-bot',
       validate: (v: string) => (v.trim() ? true : '名称不能为空'),
@@ -736,9 +765,9 @@ export async function configureMilkyBot(ctx: EndpointConfigureContext): Promise<
     },
   ]);
 
-  // schema：connection 为顶层共享字段；name / baseUrl / path / access_token 为 endpoint 级
+  // schema：connection 为顶层共享字段；id / baseUrl / path / access_token 为 endpoint 级
   const endpointConfig: Record<string, unknown> = {
-    name: endpointName.trim(),
+    id: endpointId.trim(),
     baseUrl: baseUrl.trim(),
   };
 
@@ -787,10 +816,10 @@ export async function configureSatoriBot(ctx: EndpointConfigureContext): Promise
     },
   ]);
 
-  const { endpointName, baseUrl } = await inquirer.prompt([
+  const { endpointId, baseUrl } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'endpointName',
+      name: 'endpointId',
       message: '  Endpoint 标识名称:',
       default: 'satori-bot',
       validate: (v: string) => (v.trim() ? true : '名称不能为空'),
@@ -804,9 +833,9 @@ export async function configureSatoriBot(ctx: EndpointConfigureContext): Promise
     },
   ]);
 
-  // schema：connection 为顶层共享字段；name / baseUrl / token / path 为 endpoint 级
+  // schema：connection 为顶层共享字段；id / baseUrl / token / path 为 endpoint 级
   const endpointConfig: Record<string, unknown> = {
-    name: endpointName.trim(),
+    id: endpointId.trim(),
     baseUrl: baseUrl.trim(),
   };
 
@@ -839,6 +868,142 @@ export async function configureSatoriBot(ctx: EndpointConfigureContext): Promise
   return { connection, endpoints: [endpointConfig] };
 }
 
+/**
+ * ICQQ（QQ 非官方协议）配置向导 —— 直连 @icqqjs/icqq，引导用户配置
+ * 登录凭据、设备平台、签名服务等参数。
+ */
+export async function configureIcqqBot(ctx: EndpointConfigureContext): Promise<Record<string, unknown>> {
+  console.log(chalk.gray('     文档: ' + adapterDocsUrl('icqq')));
+  console.log(chalk.gray('     直连 @icqqjs/icqq 协议库，启动时自动登录'));
+
+  const basic = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'id',
+      message: '  QQ 号（uin）:',
+      validate: (v: string) => /^\d+$/.test(v.trim()) ? true : 'QQ 号必须为纯数字',
+    },
+    {
+      type: 'input',
+      name: 'master',
+      message: '  主人 QQ 号（master，/approve 等管理命令）:',
+      validate: (v: string) => /^\d+$/.test(v.trim()) ? true : '主人 QQ 号必须为纯数字',
+    },
+  ]);
+
+  const { loginMethod } = await inquirer.prompt([
+    {
+      type: 'select',
+      name: 'loginMethod',
+      message: '  登录方式:',
+      choices: [
+        { name: '扫码登录（无需密码，推荐）', value: 'qrcode' },
+        { name: '密码登录', value: 'password' },
+      ],
+      default: 'qrcode',
+    },
+  ]);
+
+  let password: string | undefined;
+  if (loginMethod === 'password') {
+    const { pwd } = await inquirer.prompt([
+      {
+        type: 'password',
+        name: 'pwd',
+        message: '  QQ 密码:',
+        validate: (v: string) => (v.trim() ? true : '密码不能为空'),
+      },
+    ]);
+    ctx.envVars[`ICQQ_PASSWORD_${basic.id.trim()}`] = pwd;
+    password = `\${ICQQ_PASSWORD_${basic.id.trim()}}`;
+  }
+
+  const { platform } = await inquirer.prompt([
+    {
+      type: 'select',
+      name: 'platform',
+      message: '  登录设备平台:',
+      choices: [
+        { name: 'Android 手机（默认）', value: 1 },
+        { name: 'Android 平板 (aPad)', value: 2 },
+        { name: 'Android 手表 (Watch)', value: 3 },
+        { name: 'MacOS (iMac)', value: 4 },
+        { name: 'iPad', value: 5 },
+        { name: 'Tim', value: 6 },
+      ],
+      default: 2,
+    },
+  ]);
+
+  const { signApiAddr } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'signApiAddr',
+      message: '  签名服务器地址（留空则尝试用本地 @icqqjs/qqsign）:',
+      default: '',
+    },
+  ]);
+
+  const { wantAdvanced } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'wantAdvanced',
+      message: '  配置高级选项（数据目录、QQNT、协议版本等）？',
+      default: false,
+    },
+  ]);
+
+  const advanced: Record<string, unknown> = {};
+  if (wantAdvanced) {
+    const opts = await inquirer.prompt([
+      {
+        type: 'input',
+        name: 'ver',
+        message: '  协议版本号（留空使用9.1.70）:',
+        default: '9.1.70',
+      },
+      {
+        type: 'input',
+        name: 'dataDir',
+        message: '  数据存储目录（留空使用默认）:',
+        default: `data/icqq/${basic.id.trim()}`,
+      },
+      {
+        type: 'confirm',
+        name: 'qqnt',
+        message: '  使用 QQNT 协议？',
+        default: true,
+      },
+      {
+        type: 'confirm',
+        name: 'cacheGroupMember',
+        message: '  缓存群员列表？（群多时占内存较大）',
+        default: true,
+      },
+    ]);
+    if (opts.ver?.trim()) advanced.ver = opts.ver.trim();
+    if (opts.dataDir?.trim()) advanced.dataDir = opts.dataDir.trim();
+    if (!opts.qqnt) advanced.qqnt = false;
+    if (!opts.cacheGroupMember) advanced.cacheGroupMember = false;
+  }
+
+  ctx.envVars.ICQQ_ACCOUNT = basic.id.trim();
+
+  const endpointConfig: Record<string, unknown> = {
+    id: basic.id.trim(),
+    ...(password ? { password } : {}),
+    ...advanced,
+  };
+
+  const sharedConfig: Record<string, unknown> = {
+    master: basic.master.trim(),
+    ...(platform !== 1 ? { platform } : {}),
+    ...(signApiAddr?.trim() ? { signApiAddr: signApiAddr.trim() } : {}),
+  };
+
+  return { ...sharedConfig, endpoints: [endpointConfig] };
+}
+
 /**
  * 微信 iLink（个人微信 / ClawBot）配置：默认走扫码绑定 —— 终端展示二维码，
  * 微信扫码确认后 bot_token 写入 .env（`WEIXIN_ILINK_TOKEN`），
@@ -848,10 +1013,10 @@ export async function configureWeixinIlinkBot(ctx: EndpointConfigureContext): Pr
   console.log(chalk.gray('     文档: ' + adapterDocsUrl('weixin-ilink')));
   console.log(chalk.gray('     需最新版微信 + ClawBot 灰度资格（仅私聊）'));
 
-  const { endpointName } = await inquirer.prompt([
+  const { endpointId } = await inquirer.prompt([
     {
       type: 'input',
-      name: 'endpointName',
+      name: 'endpointId',
       message: '  Endpoint 标识名称:',
       default: 'weixin-bot',
       validate: (v: string) => (v.trim() ? true : '名称不能为空'),
@@ -875,7 +1040,7 @@ export async function configureWeixinIlinkBot(ctx: EndpointConfigureContext): Pr
     const scanned = await tryQrLogin(ctx);
     if (scanned) {
       return {
-        endpoints: [{ name: endpointName.trim(), botToken: '${WEIXIN_ILINK_TOKEN}' }],
+        endpoints: [{ id: endpointId.trim(), botToken: '${WEIXIN_ILINK_TOKEN}' }],
       };
     }
     console.log(chalk.yellow('     扫码未完成，降级为手动输入 bot_token'));
@@ -891,7 +1056,7 @@ export async function configureWeixinIlinkBot(ctx: EndpointConfigureContext): Pr
   ]);
   ctx.envVars.WEIXIN_ILINK_TOKEN = token.trim();
   return {
-    endpoints: [{ name: endpointName.trim(), botToken: '${WEIXIN_ILINK_TOKEN}' }],
+    endpoints: [{ id: endpointId.trim(), botToken: '${WEIXIN_ILINK_TOKEN}' }],
   };
 }
 

package/src/adapter.ts

@@ -5,6 +5,7 @@ import {
   adapterDocsUrl,
   configureDiscordEndpoint,
   configureGitHubEndpoint,
+  configureIcqqBot,
   configureMilkyBot,
   configureNapcatBot,
   configureOneBot11Bot,
@@ -82,15 +83,16 @@ export const ADAPTERS: AdapterDefinition[] = [
     value: 'icqq',
     package: '@zhin.js/adapter-icqq',
     plugin: '@zhin.js/adapter-icqq',
+    extraDeps: {
+      '@icqqjs/icqq': 'latest',
+      '@icqqjs/qqsign': 'latest',
+    },
     needsHttp: false,
-    description: '非官方 QQ 协议，需本地登录',
-    setupHint: '先安装 icqq CLI 并登录：pnpm dlx icqq login <QQ号>，登录态保存在 ~/.icqq/。',
+    description: '非官方 QQ 协议，直连 @icqqjs/icqq',
+    setupHint: '直连 @icqqjs/icqq 协议库，支持扫码或密码登录；建议配置签名服务以提高稳定性。',
     docUrl: adapterDocsUrl('icqq'),
-    fields: [
-      { key: 'name', message: 'QQ 号（与 icqq login 时一致）:', required: true, envKey: 'ICQQ_ACCOUNT' },
-      // schema 顶层 required: master（所有 endpoint 共享）
-      { key: 'master', message: '主人 QQ 号（master，/approve 等管理命令）:', required: true, scope: 'shared' },
-    ],
+    configure: configureIcqqBot,
+    fields: [],
   },
   {
     name: 'QQ 官方',
@@ -411,7 +413,7 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
         package: adapterDef.package,
         instanceKey: 'sandbox',
         config: {
-          endpoints: [{ context: 'sandbox', name: 'sandbox-bot', owner: 'sandbox-user' }],
+          endpoints: [{ context: 'sandbox', id: 'sandbox-bot', owner: 'sandbox-user' }],
         },
       });
       continue;
@@ -491,11 +493,11 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
 
 /**
  * 字段式适配器（无自定义 configure）的实例配置整形，对齐各插件 schema.json 新格式：
- * - endpoint 级字段（name + 凭据等，字段默认 scope: 'endpoint'）进 `endpoints: [{ name, ... }]`
+ * - endpoint 级字段（id + 凭据等，字段默认 scope: 'endpoint'）进 `endpoints: [{ id, ... }]`
  * - scope: 'shared' 的字段（如 lark/wechat-mp 的 webhookPath）留顶层
  * - wechat-mp：顶层字段名为 path（向导沿用 webhookPath 提问）
  * - email：smtp/imap 平铺字段 → endpoint 内 smtp/imap 嵌套对象
- * - 未单独询问 name 的适配器用 `<adapter>-bot` 兜底
+ * - 未单独询问 id 的适配器用 `<adapter>-bot` 兜底
  */
 export function buildFieldBasedInstanceConfig(adapter: AdapterDefinition, values: Record<string, any>): Record<string, unknown> {
   if (adapter.value === 'email') {
@@ -503,7 +505,7 @@ export function buildFieldBasedInstanceConfig(adapter: AdapterDefinition, values
     const password = values.password ?? '';
     return {
       endpoints: [{
-        name: 'email-bot',
+        id: 'email-bot',
         smtp: {
           host: values.smtpHost,
           port: Number(values.smtpPort) || 465,
@@ -536,8 +538,8 @@ export function buildFieldBasedInstanceConfig(adapter: AdapterDefinition, values
     shared.path = shared.webhookPath;
     delete shared.webhookPath;
   }
-  if (!endpoint.name) {
-    endpoint.name = `${adapter.value}-bot`;
+  if (!endpoint.id) {
+    endpoint.id = `${adapter.value}-bot`;
   }
   return { ...shared, endpoints: [endpoint] };
 }

package/src/apply.ts

@@ -50,14 +50,14 @@ export function applyAdaptersToConfig(config: Record<string, unknown>, result: A
   delete config.endpoints;
 }
 
-function endpointName(endpoint: unknown): string | undefined {
+function endpointId(endpoint: unknown): string | undefined {
   if (!endpoint || typeof endpoint !== 'object' || Array.isArray(endpoint)) return undefined;
-  const name = (endpoint as Record<string, unknown>).name;
-  return typeof name === 'string' ? name : undefined;
+  const id = (endpoint as Record<string, unknown>).id;
+  return typeof id === 'string' ? id : undefined;
 }
 
 /**
- * 重跑向导时按实例合并配置而非整体覆盖：保留现有 endpoints 中 name 不冲突的项
+ * 重跑向导时按实例合并配置而非整体覆盖：保留现有 endpoints 中 id 不冲突的项
  * 与其他实例级键；被向导结果覆盖的 endpoints / 键在覆盖前打印提示。
  */
 function mergeAdapterInstanceConfig(
@@ -74,9 +74,9 @@ function mergeAdapterInstanceConfig(
   const currentEndpoints = Array.isArray(current.endpoints) ? current.endpoints : [];
   const nextEndpoints = Array.isArray(next.endpoints) ? next.endpoints : [];
   if (currentEndpoints.length > 0 && nextEndpoints.length > 0) {
-    const nextNames = new Set(nextEndpoints.map(endpointName));
+    const nextNames = new Set(nextEndpoints.map(endpointId));
     const kept = currentEndpoints.filter((endpoint) => {
-      const name = endpointName(endpoint);
+      const name = endpointId(endpoint);
       if (name != null && nextNames.has(name)) {
         dropped.push(`endpoint "${name}"`);
         return false;

package/src/zhin-stack-deps.ts

@@ -18,7 +18,10 @@ export const ZHIN_STACK_VERSIONS = {
   '@zhin.js/adapter': 'latest',
   '@zhin.js/command': 'latest',
   '@zhin.js/component': 'latest',
+  '@zhin.js/console-contract': 'latest',
   '@zhin.js/core': 'latest',
+  '@zhin.js/layout': 'latest',
+  '@zhin.js/page': 'latest',
   '@zhin.js/tool': 'latest',
   '@zhin.js/client': 'latest',
   '@zhin.js/contract': 'latest',