@zhin.js/scaffold-wizard 0.1.3 → 0.1.5

package/src/adapter.ts

@@ -3,18 +3,18 @@ import chalk from 'chalk';
 import {
   ADAPTERS_DOCS_URL,
   adapterDocsUrl,
-  configureDiscordBot,
-  configureGitHubBot,
+  configureDiscordEndpoint,
+  configureGitHubEndpoint,
   configureOneBot11Bot,
   configureQQBot,
-  configureSlackBot,
-  configureTelegramBot,
+  configureSlackEndpoint,
+  configureTelegramEndpoint,
 } from './adapter-configurers.js';
 
 export interface AdapterSetupResult {
   packages: string[];
   plugins: string[];
-  bots: Array<Record<string, any>>;
+  endpoints: Array<Record<string, any>>;
   envVars: Record<string, string>;
   /** 所选适配器需要 database 插件（如 GitHub 订阅/OAuth 表） */
   requiresDatabase?: boolean;
@@ -33,7 +33,7 @@ interface AdapterDefinition {
   /** 文档：zhin.js.org/adapters/<slug>；索引见 ADAPTERS_DOCS_URL */
   docUrl?: string;
   requiresDatabase?: boolean;
-  configure?: (ctx: import('./adapter-configurers.js').BotConfigureContext) => Promise<Record<string, unknown>>;
+  configure?: (ctx: import('./adapter-configurers.js').EndpointConfigureContext) => Promise<Record<string, unknown>>;
   fields: AdapterField[];
 }
 
@@ -89,10 +89,10 @@ const ADAPTERS: AdapterDefinition[] = [
     package: '@zhin.js/adapter-kook',
     plugin: '@zhin.js/adapter-kook',
     needsHttp: true,
-    description: 'KOOK 语音平台 Bot',
-    setupHint: '在 KOOK 开发者中心创建 Bot 并复制 Token；需配置 Webhook 回调地址（公网或内网穿透）。',
+    description: 'KOOK 语音平台 Endpoint',
+    setupHint: '在 KOOK 开发者中心创建 Endpoint 并复制 Token；需配置 Webhook 回调地址（公网或内网穿透）。',
     fields: [
-      { key: 'token', message: 'KOOK Bot Token:', required: true, type: 'password', envKey: 'KOOK_TOKEN' },
+      { key: 'token', message: 'KOOK Endpoint Token:', required: true, type: 'password', envKey: 'KOOK_TOKEN' },
     ],
   },
   {
@@ -104,7 +104,7 @@ const ADAPTERS: AdapterDefinition[] = [
     description: 'Discord（Gateway 或 Interactions）',
     setupHint: 'Developer Portal 创建 Bot；Gateway 用 Token，Interactions 需 Application ID + Public Key。',
     docUrl: adapterDocsUrl('discord'),
-    configure: configureDiscordBot,
+    configure: configureDiscordEndpoint,
     fields: [],
   },
   {
@@ -116,7 +116,7 @@ const ADAPTERS: AdapterDefinition[] = [
     description: 'Telegram Bot（polling / webhook 可选）',
     setupHint: '@BotFather 获取 Token；polling 适合本地，webhook 需 HTTPS 公网域名。',
     docUrl: adapterDocsUrl('telegram'),
-    configure: configureTelegramBot,
+    configure: configureTelegramEndpoint,
     fields: [],
   },
   {
@@ -128,7 +128,7 @@ const ADAPTERS: AdapterDefinition[] = [
     description: 'Slack（Socket Mode 或 HTTP Events）',
     setupHint: 'Socket Mode 无需公网；HTTP 模式需配置 Event Subscriptions URL。',
     docUrl: adapterDocsUrl('slack'),
-    configure: configureSlackBot,
+    configure: configureSlackEndpoint,
     fields: [],
   },
   {
@@ -213,19 +213,19 @@ const ADAPTERS: AdapterDefinition[] = [
     setupHint: 'GitHub App 或 gh CLI；Webhook 用 /pub/github/webhook；需 database 存订阅与 OAuth。',
     docUrl: adapterDocsUrl('github'),
     requiresDatabase: true,
-    configure: configureGitHubBot,
+    configure: configureGitHubEndpoint,
     fields: [],
   },
 ];
 
 /**
- * 适配器选择与 Bot 配置引导向导
+ * 适配器选择与 Endpoint 配置引导向导
  */
 export async function configureAdapters(): Promise<AdapterSetupResult> {
   console.log('');
   console.log(chalk.blue('🔌 配置聊天适配器'));
   console.log(chalk.gray('  Sandbox 适合本地调试；生产环境请额外勾选目标 IM 平台。'));
-  console.log(chalk.gray('  带 Webhook 的适配器需要 Bot 可被公网访问（或使用内网穿透）。'));
+  console.log(chalk.gray('  带 Webhook 的适配器需要 Endpoint 可被公网访问（或使用内网穿透）。'));
 
   const { selectedAdapters } = await inquirer.prompt([
     {
@@ -266,7 +266,7 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
   const result: AdapterSetupResult = {
     packages: [],
     plugins: [],
-    bots: [],
+    endpoints: [],
     envVars: {},
     requiresDatabase: false,
   };
@@ -303,7 +303,7 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
 
     if (adapterDef.configure) {
       let markedDb = false;
-      const botConfig = await adapterDef.configure({
+      const endpointConfig = await adapterDef.configure({
         envVars: result.envVars,
         markRequiresDatabase: () => {
           markedDb = true;
@@ -311,11 +311,11 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
         },
       });
       if (markedDb) result.requiresDatabase = true;
-      result.bots.push(botConfig);
+      result.endpoints.push(endpointConfig);
       continue;
     }
 
-    const botConfig: Record<string, any> = {
+    const endpointConfig: Record<string, any> = {
       context: adapterDef.value,
     };
 
@@ -343,13 +343,13 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
       if (field.envKey) {
         // 敏感信息存 .env，配置引用环境变量
         result.envVars[field.envKey] = value || '';
-        botConfig[field.key] = `\${${field.envKey}}`;
+        endpointConfig[field.key] = `\${${field.envKey}}`;
       } else {
-        botConfig[field.key] = value;
+        endpointConfig[field.key] = value;
       }
     }
 
-    result.bots.push(botConfig);
+    result.endpoints.push(endpointConfig);
   }
 
   return result;
@@ -370,7 +370,7 @@ export function generateAdapterEnvVars(result: AdapterSetupResult): string {
 }
 
 /**
- * 将 bot 配置项格式化为 YAML 行
+ * 将 Endpoint 配置项格式化为 YAML 行
  */
 function appendYamlValue(lines: string[], key: string, value: unknown, indent: number): void {
   const pad = '  '.repeat(indent);
@@ -405,20 +405,20 @@ function appendYamlValue(lines: string[], key: string, value: unknown, indent: n
 }
 
 /**
- * 生成 YAML 格式的 bots 配置段
+ * 生成 YAML 格式的 endpoints 配置段
  */
-export function generateBotsConfigYaml(result: AdapterSetupResult): string {
-  if (result.bots.length === 0) {
+export function generateEndpointsConfigYaml(result: AdapterSetupResult): string {
+  if (result.endpoints.length === 0) {
     return `
 
-# Sandbox：Remote Console 打开「沙盒」页并通过 WebSocket 连接时自动创建 bot
-bots: []
+# Sandbox：Remote Console 打开「沙盒」页并通过 WebSocket 连接时自动创建 Endpoint
+endpoints: []
 `;
   }
 
-  const lines: string[] = ['', 'bots:'];
-  for (const bot of result.bots) {
-    const { context, ...config } = bot;
+  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);
@@ -429,15 +429,15 @@ bots: []
 }
 
 /**
- * 生成 TOML 格式的 bots 配置段
+ * 生成 TOML 格式的 endpoints 配置段
  */
-export function generateBotsConfigToml(result: AdapterSetupResult): string {
-  if (result.bots.length === 0) return '';
+export function generateEndpointsConfigToml(result: AdapterSetupResult): string {
+  if (result.endpoints.length === 0) return '';
 
   const lines: string[] = [''];
-  for (const bot of result.bots) {
-    lines.push('[[bots]]');
-    for (const [key, value] of Object.entries(bot)) {
+  for (const entry of result.endpoints) {
+    lines.push('[[endpoints]]');
+    for (const [key, value] of Object.entries(entry)) {
       if (typeof value === 'string') {
         lines.push(`${key} = "${value.replace(/"/g, '\\"')}"`);
       } else {
@@ -450,11 +450,11 @@ export function generateBotsConfigToml(result: AdapterSetupResult): string {
 }
 
 /**
- * 生成 JSON 格式的 bots 配置段
+ * 生成 JSON 格式的 endpoints 配置段
  */
-export function generateBotsConfigJSON(result: AdapterSetupResult): string {
-  if (result.bots.length === 0) return '';
-  return `  "bots": ${JSON.stringify(result.bots, null, 4).replace(/^/gm, '  ').trimStart()},`;
+export function generateEndpointsConfigJSON(result: AdapterSetupResult): string {
+  if (result.endpoints.length === 0) return '';
+  return `  "endpoints": ${JSON.stringify(result.endpoints, null, 4).replace(/^/gm, '  ').trimStart()},`;
 }
 
 /**
@@ -462,21 +462,21 @@ export function generateBotsConfigJSON(result: AdapterSetupResult): string {
  */
 export function getAdapterSetupNotes(result: AdapterSetupResult): string[] {
   const notes: string[] = [];
-  for (const bot of result.bots) {
-    const context = bot.context as string;
-    if (context === 'telegram' && bot.polling === false) {
+  for (const entry of result.endpoints) {
+    const context = entry.context as string;
+    if (context === 'telegram' && entry.polling === false) {
       notes.push('Telegram Webhook: 确保 HTTPS 域名可从公网访问，且 webhook.port 已放行');
     }
-    if (context === 'telegram' && bot.polling !== false) {
+    if (context === 'telegram' && entry.polling !== false) {
       notes.push('Telegram polling: 本地开发可直接 pnpm dev，无需公网');
     }
     if (context === 'github') {
-      if (bot.webhook_secret) {
+      if (entry.webhook_secret) {
         notes.push('GitHub Webhook: App 设置 URL 为 https://<域名>/pub/github/webhook');
       } else {
         notes.push('GitHub polling: 无 Webhook 时将轮询 Events API（默认 60s）');
       }
-      if (bot.app_id) {
+      if (entry.app_id) {
         notes.push('GitHub App: 私钥路径需存在，且 App 已安装到目标仓库');
       } else {
         notes.push('GitHub gh CLI: 运行 gh auth login 完成认证');

package/src/ai.ts

@@ -76,19 +76,22 @@ const PROVIDERS = [
   },
 ] as const;
 
-function providerApiFor(name: string): string {
+function providerSdkFor(name: string): string {
   switch (name) {
     case 'anthropic':
-      return 'anthropic-messages';
+      return 'anthropic';
     case 'google':
     case 'gemini':
-      return 'google-generative-ai';
+      return 'google';
     case 'ollama':
-      return 'ollama-chat';
-    case 'cloudflare':
-      return 'cloudflare-workers-ai';
+      return 'ollama';
+    case 'deepseek':
+      return 'deepseek';
+    case 'moonshot':
+    case 'zhipu':
+      return 'openai-compatible';
     default:
-      return 'openai-completions';
+      return 'openai';
   }
 }
 
@@ -127,7 +130,7 @@ export const RECOMMENDED_AI_DEFAULTS = {
 export async function configureAI(): Promise<AISetupConfig> {
   console.log('');
   console.log(chalk.blue('🤖 配置 AI 智能体'));
-  console.log(chalk.gray('  启用后将预装 @modelcontextprotocol/sdk，支持 MCP 与 memory 扩展。'));
+  console.log(chalk.gray('  启用后将自动写入 package.json：@zhin.js/agent、zod、ai、所选 @ai-sdk/*、@modelcontextprotocol/sdk。'));
   console.log(chalk.gray('  会话持久化默认开启，将自动配置 SQLite 数据库（若尚未选择）。'));
 
   const { enableAI } = await inquirer.prompt([
@@ -223,7 +226,7 @@ export async function configureAI(): Promise<AISetupConfig> {
 
   console.log('');
   console.log(chalk.blue('⚡ 配置 AI 触发方式'));
-  console.log(chalk.gray('  决定 Bot 何时自动调用大模型；命令（/ 开头）不会被 AI 拦截。'));
+  console.log(chalk.gray('  决定 Endpoint 何时自动调用大模型；命令（/ 开头）不会被 AI 拦截。'));
 
   const triggerConfig = await inquirer.prompt([
     {
@@ -348,7 +351,7 @@ export function generateAIConfigYaml(config: AISetupConfig): string {
   if (config.providers) {
     for (const [name, providerConfig] of Object.entries(config.providers)) {
       lines.push(`    ${name}:`);
-      lines.push(`      api: ${providerApiFor(name)}`);
+      lines.push(`      sdk: ${providerSdkFor(name)}`);
       if (providerConfig.apiKey) {
         lines.push(`      apiKey: ${providerConfig.apiKey}`);
       }

package/src/apply.ts

@@ -30,9 +30,9 @@ export function applyAdaptersToConfig(config: Record<string, unknown>, result: A
   }
   config.plugins = plugins;
 
-  const bots = Array.isArray(config.bots) ? [...config.bots as Record<string, unknown>[]] : [];
-  bots.push(...result.bots);
-  config.bots = bots;
+  const endpoints = Array.isArray(config.endpoints) ? [...config.endpoints as Record<string, unknown>[]] : [];
+  endpoints.push(...result.endpoints);
+  config.endpoints = endpoints;
 }
 
 export function applyAIToConfig(config: Record<string, unknown>, ai: AISetupConfig): void {

package/src/index.ts

@@ -5,9 +5,9 @@ export type { AdapterSetupResult } from './adapter.js';
 export {
   configureAdapters,
   generateAdapterEnvVars,
-  generateBotsConfigYaml,
-  generateBotsConfigJSON,
-  generateBotsConfigToml,
+  generateEndpointsConfigYaml,
+  generateEndpointsConfigJSON,
+  generateEndpointsConfigToml,
   getAdapterDependencies,
   getAdapterSetupNotes,
 } from './adapter.js';
@@ -34,6 +34,13 @@ export { configureDatabaseOptions } from './database.js';
 export {
   MCP_SDK_VERSION,
   getAIDependencies,
+  listAIDependencyNames,
+  formatAIDependencyHint,
+  isAiEnabledInConfig,
+  resolveDefaultProviderFromConfig,
+  getRequiredAIDependenciesForConfig,
+  diagnoseAIDependencies,
+  formatAIDependencyFixCommand,
   ensureDatabaseForAI,
   ensureDatabaseForAdapters,
 } from './project-deps.js';

package/src/project-deps.ts

@@ -1,17 +1,194 @@
+import { createRequire } from 'node:module';
+import fs from 'fs-extra';
+import path from 'node:path';
 import type { AISetupConfig } from './ai.js';
 import type { InitOptions } from './types.js';
 
 /** 与 monorepo 中 agent / test-bot 对齐的 MCP SDK 版本 */
 export const MCP_SDK_VERSION = '^1.29.0';
 
+const AI_STACK_VERSION = '^4.0.0';
+const ZOD_VERSION = '^4.0.0';
+const VERCEL_AI_VERSION = '^6.0.0';
+
+const PROVIDER_SDK_PACKAGES: Record<string, { pkg: string; version: string }> = {
+  openai: { pkg: '@ai-sdk/openai', version: '^3.0.0' },
+  anthropic: { pkg: '@ai-sdk/anthropic', version: '^3.0.0' },
+  google: { pkg: '@ai-sdk/google', version: '^3.0.0' },
+  gemini: { pkg: '@ai-sdk/google', version: '^3.0.0' },
+  deepseek: { pkg: '@ai-sdk/deepseek', version: '^1.0.0' },
+  ollama: { pkg: '@ai-sdk/openai-compatible', version: '^1.0.0' },
+  moonshot: { pkg: '@ai-sdk/openai-compatible', version: '^1.0.0' },
+  zhipu: { pkg: '@ai-sdk/openai-compatible', version: '^1.0.0' },
+};
+
+function providerSdkPackage(provider?: string): { pkg: string; version: string } | undefined {
+  if (!provider) return undefined;
+  return PROVIDER_SDK_PACKAGES[provider];
+}
+
+/** 启用 AI 时将写入 package.json 的依赖名（用于向导提示与 CLI 输出） */
+export function listAIDependencyNames(provider?: string, options?: { includeMcp?: boolean }): string[] {
+  const names = ['@zhin.js/agent', 'zod', 'ai'];
+  if (options?.includeMcp !== false) {
+    names.push('@modelcontextprotocol/sdk');
+  }
+  const sdk = providerSdkPackage(provider);
+  if (sdk && !names.includes(sdk.pkg)) {
+    names.push(sdk.pkg);
+  }
+  return names;
+}
+
+export function formatAIDependencyHint(provider?: string, options?: { includeMcp?: boolean }): string {
+  return listAIDependencyNames(provider, options).join(', ');
+}
+
+export interface PackageJsonLike {
+  dependencies?: Record<string, string>;
+  devDependencies?: Record<string, string>;
+}
+
+/** zhin.config 中是否启用了 AI（enabled 未显式 false 且存在 agents/providers） */
+export function isAiEnabledInConfig(config: { ai?: unknown }): boolean {
+  const ai = config.ai;
+  if (!ai || typeof ai !== 'object' || Array.isArray(ai)) return false;
+  const rec = ai as Record<string, unknown>;
+  if (rec.enabled === false) return false;
+  if (rec.enabled === true) return true;
+  const agents = rec.agents;
+  if (agents && typeof agents === 'object' && !Array.isArray(agents) && Object.keys(agents).length > 0) {
+    return true;
+  }
+  const providers = rec.providers;
+  if (providers && typeof providers === 'object' && !Array.isArray(providers) && Object.keys(providers).length > 0) {
+    return true;
+  }
+  return false;
+}
+
+export function resolveDefaultProviderFromConfig(config: { ai?: unknown }): string | undefined {
+  const ai = config.ai;
+  if (!ai || typeof ai !== 'object' || Array.isArray(ai)) return undefined;
+  const rec = ai as Record<string, unknown>;
+  const agents = rec.agents;
+  if (agents && typeof agents === 'object' && !Array.isArray(agents)) {
+    const zhin = (agents as Record<string, { provider?: string }>).zhin;
+    if (zhin?.provider) return String(zhin.provider);
+    const firstAgent = Object.values(agents as Record<string, { provider?: string }>)[0];
+    if (firstAgent?.provider) return String(firstAgent.provider);
+  }
+  const providers = rec.providers;
+  if (providers && typeof providers === 'object' && !Array.isArray(providers)) {
+    const first = Object.keys(providers as Record<string, unknown>)[0];
+    if (first) return first;
+  }
+  if (rec.defaultProvider != null) return String(rec.defaultProvider);
+  return undefined;
+}
+
+function aiConfigNeedsMcp(ai: Record<string, unknown>): boolean {
+  if (ai.memoryMcp === true) return true;
+  const servers = ai.mcpServers;
+  return Array.isArray(servers) && servers.length > 0;
+}
+
+/** 根据 zhin.config 的 ai 段推导应安装的 production 依赖 */
+export function getRequiredAIDependenciesForConfig(config: { ai?: unknown }): Record<string, string> {
+  if (!isAiEnabledInConfig(config)) return {};
+  const ai = config.ai as Record<string, unknown>;
+  const setup: AISetupConfig = {
+    enabled: true,
+    defaultProvider: resolveDefaultProviderFromConfig(config),
+    memoryMcp: aiConfigNeedsMcp(ai),
+  };
+  const deps = getAIDependencies(setup);
+  if (!aiConfigNeedsMcp(ai)) {
+    delete deps['@modelcontextprotocol/sdk'];
+  }
+  return deps;
+}
+
+export function findMissingPackageDependencies(
+  pkg: PackageJsonLike,
+  required: Record<string, string>,
+): string[] {
+  const declared = new Set([
+    ...Object.keys(pkg.dependencies ?? {}),
+    ...Object.keys(pkg.devDependencies ?? {}),
+  ]);
+  return Object.keys(required).filter((name) => !declared.has(name));
+}
+
+export function findUnresolvedPackageInstalls(cwd: string, packageNames: string[]): string[] {
+  const pkgJson = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgJson)) return [...packageNames];
+  const req = createRequire(pkgJson);
+  const missing: string[] = [];
+  for (const name of packageNames) {
+    try {
+      req.resolve(`${name}/package.json`);
+    } catch {
+      missing.push(name);
+    }
+  }
+  return missing;
+}
+
+export interface AIDependencyDiagnosis {
+  enabled: true;
+  provider?: string;
+  required: Record<string, string>;
+  missingFromPackageJson: string[];
+  notInstalled: string[];
+}
+
+export function diagnoseAIDependencies(
+  cwd: string,
+  config: { ai?: unknown },
+  pkg?: PackageJsonLike,
+): AIDependencyDiagnosis | null {
+  if (!isAiEnabledInConfig(config)) return null;
+  const required = getRequiredAIDependenciesForConfig(config);
+  const packageJsonPath = path.join(cwd, 'package.json');
+  const packageJson = pkg ?? (fs.existsSync(packageJsonPath) ? fs.readJsonSync(packageJsonPath) as PackageJsonLike : {});
+  const missingFromPackageJson = findMissingPackageDependencies(packageJson, required);
+  const declared = Object.keys(required).filter((name) => !missingFromPackageJson.includes(name));
+  const notInstalled = findUnresolvedPackageInstalls(cwd, declared);
+  return {
+    enabled: true,
+    provider: resolveDefaultProviderFromConfig(config),
+    required,
+    missingFromPackageJson,
+    notInstalled,
+  };
+}
+
+export function formatAIDependencyFixCommand(missing: string[], required: Record<string, string>): string {
+  if (missing.length === 0) return 'pnpm install';
+  const specs = missing.map((name) => `${name}@${required[name] ?? 'latest'}`);
+  return `pnpm add ${specs.join(' ')}`;
+}
+
 /**
- * AI 启用时预装 MCP SDK，避免 memoryMcp / mcpServers 运行时报 optional peer 缺失。
+ * AI 启用时安装 agent 栈 + 所选 provider 的 @ai-sdk/* + 可选 MCP SDK。
  */
 export function getAIDependencies(ai?: AISetupConfig): Record<string, string> {
   if (!ai?.enabled) return {};
-  return {
+
+  const deps: Record<string, string> = {
+    '@zhin.js/agent': AI_STACK_VERSION,
+    zod: ZOD_VERSION,
+    ai: VERCEL_AI_VERSION,
     '@modelcontextprotocol/sdk': MCP_SDK_VERSION,
   };
+
+  const sdk = providerSdkPackage(ai.defaultProvider);
+  if (sdk) {
+    deps[sdk.pkg] = sdk.version;
+  }
+
+  return deps;
 }
 
 /**

package/src/types.ts

@@ -6,6 +6,7 @@ export type { AdapterSetupResult } from './adapter.js';
 
 export interface InitOptions {
   name?: string;
+  template?: 'default' | 'life-assistant';
   config?: 'json' | 'yaml' | 'toml';
   runtime?: 'node' | 'bun';
   yes?: boolean;