@zhin.js/scaffold-wizard 0.1.8 → 0.2.0

package/src/adapter.ts

@@ -5,24 +5,39 @@ import {
   adapterDocsUrl,
   configureDiscordEndpoint,
   configureGitHubEndpoint,
+  configureMilkyBot,
+  configureNapcatBot,
   configureOneBot11Bot,
+  configureOneBot12Bot,
   configureQQBot,
+  configureSatoriBot,
   configureSlackEndpoint,
   configureTelegramEndpoint,
+  configureWeixinIlinkBot,
 } from './adapter-configurers.js';
 import { ZHIN_STACK_VERSIONS } from './zhin-stack-deps.js';
 
+/** 一个待挂载的子插件实例（package.json zhin.plugins 清单 + zhin.config plugins.<instanceKey> 配置） */
+export interface AdapterPluginInstance {
+  /** 适配器/插件包名，如 @zhin.js/adapter-sandbox */
+  package: string;
+  /** 运行时实例键，如 sandbox / telegram；同名包多实例时需区分 */
+  instanceKey: string;
+  /** 写入 zhin.config plugins.<instanceKey> 的配置（对齐该插件 schema.json） */
+  config: Record<string, unknown>;
+}
+
 export interface AdapterSetupResult {
   packages: string[];
   plugins: string[];
-  endpoints: Array<Record<string, any>>;
+  instances: AdapterPluginInstance[];
   envVars: Record<string, string>;
   /** 所选适配器需要 database 插件（如 GitHub 订阅/OAuth 表） */
   requiresDatabase?: boolean;
 }
 
 // 适配器定义
-interface AdapterDefinition {
+export interface AdapterDefinition {
   name: string;
   value: string;
   package: string;
@@ -38,7 +53,7 @@ interface AdapterDefinition {
   fields: AdapterField[];
 }
 
-interface AdapterField {
+export interface AdapterField {
   key: string;
   message: string;
   type?: 'input' | 'password' | 'select';
@@ -46,6 +61,8 @@ interface AdapterField {
   required?: boolean;
   envKey?: string;       // 如果是敏感信息，对应的环境变量名
   choices?: { name: string; value: string }[];
+  /** 字段归属：endpoint 级（默认，进 endpoints[i]）或 shared（顶层共享字段） */
+  scope?: 'endpoint' | 'shared';
 }
 
 const ADAPTERS: AdapterDefinition[] = [
@@ -56,7 +73,7 @@ const ADAPTERS: AdapterDefinition[] = [
     plugin: '@zhin.js/adapter-sandbox',
     needsHttp: true,
     description: '终端 + Remote Console 沙盒页，本地开发首选',
-    setupHint: '无需额外凭据；pnpm dev 后可在终端或 Console 沙盒页直接对话。',
+    setupHint: '无需额外凭据；pnpm dev（zhin runtime start）后可在 Console 沙盒页直接对话。',
     fields: [],
   },
   {
@@ -70,6 +87,8 @@ const ADAPTERS: AdapterDefinition[] = [
     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' },
     ],
   },
   {
@@ -143,6 +162,8 @@ const ADAPTERS: AdapterDefinition[] = [
     fields: [
       { key: 'appKey', message: 'App Key:', required: true, envKey: 'DINGTALK_APP_KEY' },
       { key: 'appSecret', message: 'App Secret:', required: true, type: 'password', envKey: 'DINGTALK_APP_SECRET' },
+      // schema endpoints[i] required 含 robotCode（主动发送 /robot/send 需要）
+      { key: 'robotCode', message: 'Robot Code:', required: true, envKey: 'DINGTALK_ROBOT_CODE' },
       { key: 'webhookPath', message: 'Webhook 路径:', default: '/dingtalk/webhook' },
     ],
   },
@@ -157,7 +178,24 @@ const ADAPTERS: AdapterDefinition[] = [
     fields: [
       { key: 'appId', message: 'App ID:', required: true, envKey: 'LARK_APP_ID' },
       { key: 'appSecret', message: 'App Secret:', required: true, type: 'password', envKey: 'LARK_APP_SECRET' },
-      { key: 'webhookPath', message: 'Webhook 路径:', default: '/lark/webhook' },
+      // schema 顶层共享字段（endpoints[i] 不含 webhookPath）
+      { key: 'webhookPath', message: 'Webhook 路径:', default: '/lark/webhook', scope: 'shared' },
+    ],
+  },
+  {
+    name: 'LINE',
+    value: 'line',
+    package: '@zhin.js/adapter-line',
+    plugin: '@zhin.js/adapter-line',
+    needsHttp: true,
+    description: 'LINE Messaging API',
+    setupHint: '在 LINE Developers Console 创建 Messaging API Channel；Webhook URL 需 HTTPS 公网可达，并关闭 Auto-reply。',
+    docUrl: adapterDocsUrl('line'),
+    fields: [
+      { key: 'channelSecret', message: 'Channel Secret:', required: true, type: 'password', envKey: 'LINE_CHANNEL_SECRET' },
+      { key: 'channelAccessToken', message: 'Channel Access Token:', required: true, type: 'password', envKey: 'LINE_CHANNEL_ACCESS_TOKEN' },
+      // schema 顶层共享字段（endpoints[i] 不含 webhookPath）
+      { key: 'webhookPath', message: 'Webhook 路径:', default: '/line/webhook', scope: 'shared' },
     ],
   },
   {
@@ -167,11 +205,59 @@ const ADAPTERS: AdapterDefinition[] = [
     plugin: '@zhin.js/adapter-onebot11',
     needsHttp: false,
     description: 'OneBot v11（ws 正向 / wss 反向）',
-    setupHint: 'connection: ws 连 OneBot 实现；connection: wss 反向连接（需 host-router）。',
+    setupHint: 'connection: ws 连 OneBot 实现；connection: wss 反向连接（由内置 HTTP Host 承接）。',
     docUrl: adapterDocsUrl('onebot11'),
     configure: configureOneBot11Bot,
     fields: [],
   },
+  {
+    name: 'OneBot v12',
+    value: 'onebot12',
+    package: '@zhin.js/adapter-onebot12',
+    plugin: '@zhin.js/adapter-onebot12',
+    needsHttp: false,
+    description: 'OneBot v12（ws / webhook / wss）',
+    setupHint: 'connection: ws 连 OneBot 实现；webhook / wss 由内置 HTTP Host 承接。',
+    docUrl: adapterDocsUrl('onebot12'),
+    configure: configureOneBot12Bot,
+    fields: [],
+  },
+  {
+    name: 'NapCat',
+    value: 'napcat',
+    package: '@zhin.js/adapter-napcat',
+    plugin: '@zhin.js/adapter-napcat',
+    needsHttp: false,
+    description: 'NapCat（OneBot 11 + NapCat 扩展）',
+    setupHint: 'connection: ws 连 NapCat（默认 ws://127.0.0.1:3001）；wss / http 由内置 HTTP Host 承接。',
+    docUrl: adapterDocsUrl('napcat'),
+    configure: configureNapcatBot,
+    fields: [],
+  },
+  {
+    name: 'Milky',
+    value: 'milky',
+    package: '@zhin.js/adapter-milky',
+    plugin: '@zhin.js/adapter-milky',
+    needsHttp: false,
+    description: 'Milky 协议（ws / sse / webhook / wss）',
+    setupHint: 'connection: ws 连协议端 ws(s)://baseUrl/event；webhook / wss 由内置 HTTP Host 承接。',
+    docUrl: adapterDocsUrl('milky'),
+    configure: configureMilkyBot,
+    fields: [],
+  },
+  {
+    name: 'Satori',
+    value: 'satori',
+    package: '@zhin.js/adapter-satori',
+    plugin: '@zhin.js/adapter-satori',
+    needsHttp: false,
+    description: 'Satori 聊天协议（ws / webhook）',
+    setupHint: 'connection: ws 连 Satori SDK（默认 http://127.0.0.1:5140）；webhook 由内置 HTTP Host 承接。',
+    docUrl: adapterDocsUrl('satori'),
+    configure: configureSatoriBot,
+    fields: [],
+  },
   {
     name: '微信公众号',
     value: 'wechat-mp',
@@ -184,7 +270,26 @@ const ADAPTERS: AdapterDefinition[] = [
       { key: 'appId', message: 'App ID:', required: true, envKey: 'WECHAT_APP_ID' },
       { key: 'appSecret', message: 'App Secret:', required: true, type: 'password', envKey: 'WECHAT_APP_SECRET' },
       { key: 'token', message: '验证 Token:', required: true, envKey: 'WECHAT_TOKEN' },
-      { key: 'webhookPath', message: 'Webhook 路径:', default: '/wechat/webhook' },
+      // schema 顶层共享字段名为 path（endpoints[i] 不含此项）
+      { key: 'webhookPath', message: 'Webhook 路径:', default: '/wechat/webhook', scope: 'shared' },
+    ],
+  },
+  {
+    name: '企业微信',
+    value: 'wecom',
+    package: '@zhin.js/adapter-wecom',
+    plugin: '@zhin.js/adapter-wecom',
+    needsHttp: true,
+    description: '企业微信自建应用',
+    setupHint: '管理后台创建自建应用并配置「接收消息」URL（需公网可达）；Token / EncodingAESKey 与后台一致。',
+    docUrl: adapterDocsUrl('wecom'),
+    fields: [
+      { key: 'corpId', message: 'Corp ID:', required: true, envKey: 'WECOM_CORP_ID' },
+      { key: 'agentSecret', message: '应用 Secret:', required: true, type: 'password', envKey: 'WECOM_AGENT_SECRET' },
+      { key: 'token', message: '回调 Token:', required: true, type: 'password', envKey: 'WECOM_TOKEN' },
+      { key: 'encodingAESKey', message: 'EncodingAESKey（43 字符）:', required: true, type: 'password', envKey: 'WECOM_AES_KEY' },
+      // schema 顶层共享字段（endpoints[i] 不含 webhookPath）
+      { key: 'webhookPath', message: '回调路径:', default: '/wecom/callback', scope: 'shared' },
     ],
   },
   {
@@ -211,12 +316,24 @@ const ADAPTERS: AdapterDefinition[] = [
     plugin: '@zhin.js/adapter-github',
     needsHttp: true,
     description: 'GitHub Issue/PR 聊天 + App 认证',
-    setupHint: 'GitHub App 或 gh CLI；Webhook 用 /pub/github/webhook；需 database 存订阅与 OAuth。',
+    setupHint: 'GitHub App 或 gh CLI；Webhook 由内置 HTTP Host 承接（默认 /github/webhook）；需 database 存订阅与 OAuth。',
     docUrl: adapterDocsUrl('github'),
     requiresDatabase: true,
     configure: configureGitHubEndpoint,
     fields: [],
   },
+  {
+    name: '微信 iLink（个人微信）',
+    value: 'weixin-ilink',
+    package: '@zhin.js/adapter-weixin-ilink',
+    plugin: '@zhin.js/adapter-weixin-ilink',
+    needsHttp: false,
+    description: '个人微信（iLink / ClawBot 灰度入口，长轮询，仅私聊）',
+    setupHint: '需最新版微信 + ClawBot 灰度资格；默认扫码绑定（bot_token 写入 .env），也可手动输入或放 data/weixin-ilink/<name>.json 侧车凭证文件。',
+    docUrl: adapterDocsUrl('weixin-ilink'),
+    configure: configureWeixinIlinkBot,
+    fields: [],
+  },
 ];
 
 /**
@@ -243,7 +360,7 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
         if (input.length === 0) return '至少选择一个适配器';
         return true;
       },
-      pageSize: 14,
+      pageSize: 22,
     }
   ]);
 
@@ -261,13 +378,13 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
     for (const adapter of httpAdapters) {
       console.log(chalk.gray(`    • ${adapter.name.split(' (')[0]}`));
     }
-    console.log(chalk.gray('    开发时可先用 Sandbox；上线前请确保 http 端口（默认 8086）可从平台回调。'));
+    console.log(chalk.gray('    开发时可先用 Sandbox；上线前请确保 http 端口（默认 8068）可从平台回调。'));
   }
 
   const result: AdapterSetupResult = {
     packages: [],
     plugins: [],
-    endpoints: [],
+    instances: [],
     envVars: {},
     requiresDatabase: false,
   };
@@ -287,10 +404,23 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
       result.requiresDatabase = true;
     }
 
-    if (adapterValue === 'sandbox') continue;
+    if (adapterValue === 'sandbox') {
+      // 对齐 examples/test-bot：Console 沙盒页与本地调试共用的默认 Endpoint
+      result.instances.push({
+        package: adapterDef.package,
+        instanceKey: 'sandbox',
+        config: {
+          endpoints: [{ context: 'sandbox', name: 'sandbox-bot', owner: 'sandbox-user' }],
+        },
+      });
+      continue;
+    }
 
     const hasConfig = adapterDef.configure || adapterDef.fields.length > 0;
-    if (!hasConfig) continue;
+    if (!hasConfig) {
+      result.instances.push({ package: adapterDef.package, instanceKey: adapterDef.value, config: {} });
+      continue;
+    }
 
     console.log('');
     console.log(chalk.yellow(`  📝 配置 ${adapterDef.name.split(' (')[0]} Bot`));
@@ -304,7 +434,7 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
 
     if (adapterDef.configure) {
       let markedDb = false;
-      const endpointConfig = await adapterDef.configure({
+      const instanceConfig = await adapterDef.configure({
         envVars: result.envVars,
         markRequiresDatabase: () => {
           markedDb = true;
@@ -312,13 +442,11 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
         },
       });
       if (markedDb) result.requiresDatabase = true;
-      result.endpoints.push(endpointConfig);
+      result.instances.push({ package: adapterDef.package, instanceKey: adapterDef.value, config: instanceConfig });
       continue;
     }
 
-    const endpointConfig: Record<string, any> = {
-      context: adapterDef.value,
-    };
+    const fieldValues: Record<string, any> = {};
 
     for (const field of adapterDef.fields) {
       const promptConfig: any = {
@@ -344,127 +472,108 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
       if (field.envKey) {
         // 敏感信息存 .env，配置引用环境变量
         result.envVars[field.envKey] = value || '';
-        endpointConfig[field.key] = `\${${field.envKey}}`;
+        fieldValues[field.key] = `\${${field.envKey}}`;
       } else {
-        endpointConfig[field.key] = value;
+        fieldValues[field.key] = value;
       }
     }
 
-    result.endpoints.push(endpointConfig);
+    result.instances.push({
+      package: adapterDef.package,
+      instanceKey: adapterDef.value,
+      config: buildFieldBasedInstanceConfig(adapterDef, fieldValues),
+    });
   }
 
   return result;
 }
 
 /**
- * 获取适配器配置需要写入 .env 的环境变量文本
+ * 字段式适配器（无自定义 configure）的实例配置整形，对齐各插件 schema.json 新格式：
+ * - endpoint 级字段（name + 凭据等，字段默认 scope: 'endpoint'）进 `endpoints: [{ name, ... }]`
+ * - scope: 'shared' 的字段（如 lark/wechat-mp 的 webhookPath）留顶层
+ * - wechat-mp：顶层字段名为 path（向导沿用 webhookPath 提问）
+ * - email：smtp/imap 平铺字段 → endpoint 内 smtp/imap 嵌套对象
+ * - 未单独询问 name 的适配器用 `<adapter>-bot` 兜底
  */
-export function generateAdapterEnvVars(result: AdapterSetupResult): string {
-  const entries = Object.entries(result.envVars);
-  if (entries.length === 0) return '';
-
-  const lines: string[] = ['', '# 适配器配置'];
-  for (const [key, value] of entries) {
-    lines.push(`${key}=${value}`);
+export function buildFieldBasedInstanceConfig(adapter: AdapterDefinition, values: Record<string, any>): Record<string, unknown> {
+  if (adapter.value === 'email') {
+    const user = values.user ?? '';
+    const password = values.password ?? '';
+    return {
+      endpoints: [{
+        name: 'email-bot',
+        smtp: {
+          host: values.smtpHost,
+          port: Number(values.smtpPort) || 465,
+          secure: true,
+          auth: { user, pass: password },
+        },
+        imap: {
+          host: values.imapHost,
+          port: Number(values.imapPort) || 993,
+          tls: true,
+          user,
+          password,
+        },
+      }],
+    };
   }
-  return lines.join('\n');
-}
 
-/**
- * 将 Endpoint 配置项格式化为 YAML 行
- */
-function appendYamlValue(lines: string[], key: string, value: unknown, indent: number): void {
-  const pad = '  '.repeat(indent);
-  if (value === undefined || value === null) return;
-
-  if (typeof value === 'object' && !Array.isArray(value)) {
-    lines.push(`${pad}${key}:`);
-    for (const [subKey, subValue] of Object.entries(value)) {
-      appendYamlValue(lines, subKey, subValue, indent + 1);
+  const endpoint: Record<string, unknown> = {};
+  const shared: Record<string, unknown> = {};
+  for (const field of adapter.fields) {
+    const value = values[field.key];
+    if (value === undefined) continue;
+    if (field.scope === 'shared') {
+      shared[field.key] = value;
+    } else {
+      endpoint[field.key] = value;
     }
-    return;
   }
-
-  if (Array.isArray(value)) {
-    lines.push(`${pad}${key}:`);
-    for (const item of value) {
-      if (typeof item === 'string') {
-        lines.push(`${pad}  - "${item}"`);
-      } else {
-        lines.push(`${pad}  - ${item}`);
-      }
-    }
-    return;
+  if (adapter.value === 'wechat-mp' && shared.webhookPath !== undefined) {
+    shared.path = shared.webhookPath;
+    delete shared.webhookPath;
   }
-
-  if (typeof value === 'boolean' || typeof value === 'number') {
-    lines.push(`${pad}${key}: ${value}`);
-    return;
+  if (!endpoint.name) {
+    endpoint.name = `${adapter.value}-bot`;
   }
-
-  lines.push(`${pad}${key}: ${value}`);
+  return { ...shared, endpoints: [endpoint] };
 }
 
 /**
- * 生成 YAML 格式的 endpoints 配置段
+ * 获取适配器配置需要写入 .env 的环境变量文本
  */
-export function generateEndpointsConfigYaml(result: AdapterSetupResult): string {
-  if (result.endpoints.length === 0) {
-    return `
-
-# Sandbox：Remote Console 打开「沙盒」页并通过 WebSocket 连接时自动创建 Endpoint
-endpoints: []
-`;
-  }
+export function generateAdapterEnvVars(result: AdapterSetupResult): string {
+  const entries = Object.entries(result.envVars);
+  if (entries.length === 0) return '';
 
-  const lines: string[] = ['', 'endpoints:'];
-  for (const entry of result.endpoints) {
-    const { context, ...config } = entry;
-    lines.push(`  - context: ${context}`);
-    for (const [key, value] of Object.entries(config)) {
-      appendYamlValue(lines, key, value, 2);
-    }
+  const lines: string[] = ['', '# 适配器配置'];
+  for (const [key, value] of entries) {
+    lines.push(`${key}=${value}`);
   }
-
   return lines.join('\n');
 }
 
 /**
- * 生成 TOML 格式的 endpoints 配置段
+ * 汇总适配器实例为 zhin.config `plugins.<instanceKey>` 配置映射（新 Plugin Runtime 格式）
  */
-export function generateEndpointsConfigToml(result: AdapterSetupResult): string {
-  if (result.endpoints.length === 0) return '';
-
-  const lines: string[] = [''];
-  for (const entry of result.endpoints) {
-    lines.push('[[endpoints]]');
-    for (const [key, value] of Object.entries(entry)) {
-      if (typeof value === 'string') {
-        lines.push(`${key} = "${escapeTomlString(value)}"`);
-      } else {
-        lines.push(`${key} = ${JSON.stringify(value)}`);
-      }
-    }
-    lines.push('');
-  }
-  return lines.join('\n');
-}
-
-function escapeTomlString(value: string): string {
-  let out = '';
-  for (const ch of value) {
-    if (ch === '"' || ch === '\\') out += `\\${ch}`;
-    else out += ch;
+export function collectAdapterPluginConfigs(result: AdapterSetupResult): Record<string, Record<string, unknown>> {
+  const plugins: Record<string, Record<string, unknown>> = {};
+  for (const instance of result.instances) {
+    plugins[instance.instanceKey] = instance.config;
   }
-  return out;
+  return plugins;
 }
 
 /**
- * 生成 JSON 格式的 endpoints 配置段
+ * 汇总适配器实例为 package.json `zhin.plugins` 清单条目
  */
-export function generateEndpointsConfigJSON(result: AdapterSetupResult): string {
-  if (result.endpoints.length === 0) return '';
-  return `  "endpoints": ${JSON.stringify(result.endpoints, null, 4).replace(/^/gm, '  ').trimStart()},`;
+export function collectAdapterPluginManifest(result: AdapterSetupResult): Array<{ package: string; instanceKey: string }> {
+  return result.instances.map((instance) => ({
+    package: instance.package,
+    instanceKey: instance.instanceKey,
+  }));
 }
 
 /**
@@ -472,21 +581,24 @@ export function generateEndpointsConfigJSON(result: AdapterSetupResult): string
  */
 export function getAdapterSetupNotes(result: AdapterSetupResult): string[] {
   const notes: string[] = [];
-  for (const entry of result.endpoints) {
-    const context = entry.context as string;
+  for (const instance of result.instances) {
+    const context = instance.instanceKey;
+    const entry = instance.config;
     if (context === 'telegram' && entry.polling === false) {
-      notes.push('Telegram Webhook: 确保 HTTPS 域名可从公网访问，且 webhook.port 已放行');
+      notes.push('Telegram Webhook: 确保 HTTPS 域名可从公网访问，且 http 端口已放行');
     }
     if (context === 'telegram' && entry.polling !== false) {
       notes.push('Telegram polling: 本地开发可直接 pnpm dev，无需公网');
     }
     if (context === 'github') {
-      if (entry.webhook_secret) {
-        notes.push('GitHub Webhook: App 设置 URL 为 https://<域名>/pub/github/webhook');
+      const endpoints = Array.isArray(entry.endpoints) ? entry.endpoints as Array<Record<string, unknown>> : [];
+      const firstEndpoint = endpoints[0] ?? {};
+      if (firstEndpoint.webhook_secret) {
+        notes.push('GitHub Webhook: App 设置 URL 为 https://<域名>/github/webhook');
       } else {
         notes.push('GitHub polling: 无 Webhook 时将轮询 Events API（默认 60s）');
       }
-      if (entry.app_id) {
+      if (firstEndpoint.app_id) {
         notes.push('GitHub App: 私钥路径需存在，且 App 已安装到目标仓库');
       } else {
         notes.push('GitHub gh CLI: 运行 gh auth login 完成认证');