@zhin.js/scaffold-wizard 0.2.0 → 0.2.2

package/src/env.ts

@@ -0,0 +1,113 @@
+import type { DatabaseConfig } from './types.js';
+
+/**
+ * dotenv 值格式化：含 `#` / 空白 / 引号 / 反斜杠 / 换行 时用双引号包裹并转义，
+ * 避免未转义值截断注释或破坏行解析（所有 .env 生成点统一走这里）。
+ */
+export function formatEnvValue(value: unknown): string {
+  const raw = value == null ? '' : String(value);
+  if (raw !== '' && !/[#"'\\\s]/.test(raw)) return raw;
+  return `"${raw
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\r/g, '\\r')
+    .replace(/\n/g, '\\n')}"`;
+}
+
+const ENV_KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)=/;
+
+/**
+ * 幂等合并 .env 内容：extra 中出现的 KEY 覆盖 existing 同名行（原位替换），
+ * 新 KEY 连同其段落注释追加到文末。重复执行结果不变。
+ */
+export function mergeEnvText(existing: string, extra: string): string {
+  const entries: Array<{ comment?: string; key: string; line: string }> = [];
+  let pendingComment: string | undefined;
+  for (const rawLine of extra.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    if (line.startsWith('#')) {
+      pendingComment = line;
+      continue;
+    }
+    const match = ENV_KEY_LINE.exec(line);
+    if (!match) continue;
+    entries.push({ comment: pendingComment, key: match[1], line });
+    pendingComment = undefined;
+  }
+  const out = existing.split('\n');
+  if (entries.length === 0) {
+    return existing.replace(/\s*$/, '') + (existing.trim() ? '\n' : '');
+  }
+  const byKey = new Map(entries.map((entry) => [entry.key, entry]));
+  const consumed = new Set<string>();
+  for (let index = 0; index < out.length; index += 1) {
+    const match = ENV_KEY_LINE.exec(out[index].trim());
+    if (match && byKey.has(match[1])) {
+      out[index] = byKey.get(match[1])!.line;
+      consumed.add(match[1]);
+    }
+  }
+  const fresh = entries.filter((entry) => !consumed.has(entry.key));
+  if (fresh.length > 0) {
+    while (out.length > 0 && out[out.length - 1].trim() === '') out.pop();
+    if (out.length > 0) out.push('');
+    let lastComment: string | undefined;
+    for (const entry of fresh) {
+      if (entry.comment && entry.comment !== lastComment) out.push(entry.comment);
+      lastComment = entry.comment;
+      out.push(entry.line);
+    }
+  }
+  return out.join('\n').replace(/\s*$/, '') + '\n';
+}
+
+/** 生成数据库连接环境变量（连接参数落 .env，配置文件只引用 ${VAR}）。 */
+export function generateDatabaseEnvVars(config: DatabaseConfig): string {
+  const envVars: string[] = [];
+
+  switch (config.dialect) {
+    case 'mysql':
+      envVars.push(
+        '# MySQL 数据库配置',
+        `DB_HOST=${formatEnvValue(config.host || 'localhost')}`,
+        `DB_PORT=${formatEnvValue(config.port || 3306)}`,
+        `DB_USER=${formatEnvValue(config.user || 'root')}`,
+        `DB_PASSWORD=${formatEnvValue(config.password || '')}`,
+        `DB_DATABASE=${formatEnvValue(config.database || 'zhin_bot')}`
+      );
+      break;
+    case 'pg':
+      envVars.push(
+        '# PostgreSQL 数据库配置',
+        `DB_HOST=${formatEnvValue(config.host || 'localhost')}`,
+        `DB_PORT=${formatEnvValue(config.port || 5432)}`,
+        `DB_USER=${formatEnvValue(config.user || 'postgres')}`,
+        `DB_PASSWORD=${formatEnvValue(config.password || '')}`,
+        `DB_DATABASE=${formatEnvValue(config.database || 'zhin_bot')}`
+      );
+      break;
+    case 'mongodb':
+      envVars.push(
+        '# MongoDB 数据库配置',
+        `DB_URL=${formatEnvValue(config.url || 'mongodb://localhost:27017')}`,
+        `DB_NAME=${formatEnvValue(config.dbName || 'zhin_bot')}`
+      );
+      break;
+    case 'redis':
+      envVars.push(
+        '# Redis 数据库配置',
+        `REDIS_HOST=${formatEnvValue(config.socket?.host || 'localhost')}`,
+        `REDIS_PORT=${formatEnvValue(config.socket?.port || 6379)}`,
+        `REDIS_PASSWORD=${formatEnvValue(config.password || '')}`,
+        `REDIS_DB=${formatEnvValue(config.database ?? 0)}`
+      );
+      break;
+    case 'sqlite':
+    default:
+      // SQLite 不需要额外的环境变量
+      break;
+  }
+
+  return envVars.length > 0 ? `\n\n${envVars.join('\n')}` : '';
+}

package/src/index.ts

@@ -1,8 +1,10 @@
 export type { InitOptions, DatabaseConfig } from './types.js';
 export { DATABASE_PACKAGES } from './types.js';
 
-export type { AdapterSetupResult, AdapterPluginInstance } from './adapter.js';
+export type { AdapterSetupResult, AdapterPluginInstance, AdapterDefinition } from './adapter.js';
 export {
+  ADAPTERS,
+  findAdapterByPackage,
   configureAdapters,
   buildFieldBasedInstanceConfig,
   generateAdapterEnvVars,
@@ -31,6 +33,12 @@ export {
 
 export { configureDatabaseOptions } from './database.js';
 
+export {
+  formatEnvValue,
+  mergeEnvText,
+  generateDatabaseEnvVars,
+} from './env.js';
+
 export {
   AI_STACK_VERSIONS,
   MCP_SDK_VERSION,
@@ -100,13 +108,14 @@ export type {
 } from './project-config-plan.js';
 
 export {
-  CONSOLE_HOST_PLUGINS,
   applyDatabaseToConfig,
   applyAdaptersToConfig,
   applyAIToConfig,
   appendWizardEnvVars,
   collectWizardDependencies,
+  collectWizardFeatures,
   mergeDependenciesIntoPackageJson,
+  mergeFeaturesIntoPackageJson,
   mergePluginManifestIntoPackageJson,
   finalizeWizardOptions,
   applyWizardOptionsToConfig,

package/src/optional-peers.ts

@@ -46,6 +46,15 @@ function configUsesHtmlImageAdapter(config: Record<string, unknown>): boolean {
       if (plugin.includes(`adapter-${ctx}`)) return true;
     }
   }
+  // 新 runtime 配置形态：plugins 为 instanceKey → 配置 的映射，instanceKey 即适配器 context
+  if (config.plugins && typeof config.plugins === 'object' && !Array.isArray(config.plugins)) {
+    for (const instanceKey of Object.keys(config.plugins as Record<string, unknown>)) {
+      if (ADAPTERS_PREFER_HTML_IMAGE.has(instanceKey)) return true;
+      for (const ctx of ADAPTERS_PREFER_HTML_IMAGE) {
+        if (instanceKey.includes(`adapter-${ctx}`)) return true;
+      }
+    }
+  }
   const endpoints = Array.isArray(config.endpoints) ? config.endpoints : [];
   for (const ep of endpoints) {
     if (!ep || typeof ep !== 'object' || Array.isArray(ep)) continue;

package/src/project-config-plan.ts

@@ -12,8 +12,6 @@ const CONFIG_CANDIDATES = [
   'zhin.config.toml',
   'zhin.config.ts',
 ] as const;
-/** @deprecated Plugin Runtime 由 CLI 装配 Console Host，无需在配置中声明；仅用于 legacy 数组配置诊断 */
-const CONSOLE_HOST_PLUGINS = ['@zhin.js/host-router', '@zhin.js/host-api'] as const;
 const SANDBOX_PLUGIN = '@zhin.js/adapter-sandbox';
 const LEGACY_AI_PROVIDER_FIELDS = ['driver', 'api', 'preset', 'spec'] as const;
 
@@ -66,7 +64,6 @@ export interface ProjectConfigPlan {
 }
 
 export interface ConsoleConfigDiagnosis {
-  missingHostPlugins: string[];
   missingSandboxPlugin: boolean;
   missingConsoleOrigin: boolean;
   missingHttpToken: boolean;
@@ -344,10 +341,6 @@ export function createProjectConfigPlan(options: ProjectConfigPlanOptions): Proj
   const mutations: string[] = [];
 
   if (loaded.status === 'loaded' || options.config) {
-    if (options.ensureConsole && Array.isArray(after.plugins)) {
-      // legacy 数组形态：host 插件仍需写入列表（旧项目行为不变）
-      ensurePlugins(after, CONSOLE_HOST_PLUGINS, mutations);
-    }
     if (options.ensureSandbox) {
       ensurePlugins(after, [SANDBOX_PLUGIN], mutations);
     }
@@ -406,7 +399,6 @@ export function diagnoseConsoleConfig(config: Record<string, unknown>): ConsoleC
     // legacy 数组形式配置
     const plugins = config.plugins.filter((p): p is string => typeof p === 'string');
     return {
-      missingHostPlugins: CONSOLE_HOST_PLUGINS.filter((plugin) => !plugins.includes(plugin)),
       missingSandboxPlugin: !plugins.includes(SANDBOX_PLUGIN),
       missingConsoleOrigin: !hasConsoleOrigin(corsOrigins.filter((origin): origin is string => typeof origin === 'string')),
       missingHttpToken: typeof http.token !== 'string' || http.token.trim().length === 0,
@@ -418,7 +410,6 @@ export function diagnoseConsoleConfig(config: Record<string, unknown>): ConsoleC
     ? config.plugins as Record<string, unknown>
     : {};
   return {
-    missingHostPlugins: [],
     missingSandboxPlugin: !('sandbox' in plugins),
     missingConsoleOrigin: !hasConsoleOrigin(corsOrigins.filter((origin): origin is string => typeof origin === 'string')),
     missingHttpToken: typeof http.token !== 'string' || http.token.trim().length === 0,

package/src/project-deps.ts

@@ -51,6 +51,7 @@ const PROVIDER_SDK_PACKAGES: Record<string, { pkg: string; version: string }> =
   ollama: { pkg: '@ai-sdk/openai-compatible', version: AI_STACK_VERSIONS['@ai-sdk/openai-compatible'] },
   moonshot: { pkg: '@ai-sdk/openai-compatible', version: AI_STACK_VERSIONS['@ai-sdk/openai-compatible'] },
   zhipu: { pkg: '@ai-sdk/openai-compatible', version: AI_STACK_VERSIONS['@ai-sdk/openai-compatible'] },
+  'openai-compatible': { pkg: '@ai-sdk/openai-compatible', version: AI_STACK_VERSIONS['@ai-sdk/openai-compatible'] },
 };
 
 /** @ai-sdk/* 主版本 ≥ threshold 时需 ai@7 */
@@ -211,7 +212,7 @@ export function findInstalledAiStackIncompatibilities(
 /** 启用 AI 时将写入 package.json 的依赖名（用于向导提示与 CLI 输出） */
 export function listAIDependencyNames(provider?: string, options?: { includeMcp?: boolean }): string[] {
   const names = ['@zhin.js/agent', 'zod', 'ai'];
-  if (options?.includeMcp !== false) {
+  if (options?.includeMcp === true) {
     names.push('@modelcontextprotocol/sdk');
   }
   const sdk = providerSdkPackage(provider);
@@ -314,7 +315,11 @@ export function findUnresolvedPackageInstalls(cwd: string, packageNames: string[
     try {
       req.resolve(`${name}/package.json`);
     } catch {
-      missing.push(name);
+      // exports map 未暴露 ./package.json（ERR_PACKAGE_PATH_NOT_EXPORTED，如 zhin.js）
+      // 时 resolve 必炸，退到 node_modules 文件系统判断（pnpm 顶层 symlink 可直达）。
+      if (!fs.existsSync(path.join(cwd, 'node_modules', name, 'package.json'))) {
+        missing.push(name);
+      }
     }
   }
   return missing;
@@ -376,7 +381,8 @@ export function formatAIDependencyFixCommand(packages: string[], required: Recor
 }
 
 /**
- * AI 启用时安装 agent 栈 + 所选 provider 的 @ai-sdk/* + 可选 MCP SDK。
+ * AI 启用时安装 agent 栈 + 所选 provider 的 @ai-sdk/*。
+ * `@modelcontextprotocol/sdk` 仅在 memoryMcp / mcpServers 时写入（与 doctor 对齐）。
  */
 export function getAIDependencies(ai?: AISetupConfig): Record<string, string> {
   if (!ai?.enabled) return {};
@@ -385,9 +391,13 @@ export function getAIDependencies(ai?: AISetupConfig): Record<string, string> {
     '@zhin.js/agent': AI_STACK_VERSIONS['@zhin.js/agent'],
     zod: AI_STACK_VERSIONS.zod,
     ai: AI_STACK_VERSIONS.ai,
-    '@modelcontextprotocol/sdk': AI_STACK_VERSIONS['@modelcontextprotocol/sdk'],
     ...collectSdkPackagesFromSetup(ai),
   };
+  const needsMcp = ai.memoryMcp === true
+    || (Array.isArray(ai.mcpServers) && ai.mcpServers.length > 0);
+  if (needsMcp) {
+    deps['@modelcontextprotocol/sdk'] = AI_STACK_VERSIONS['@modelcontextprotocol/sdk'];
+  }
 
   return deps;
 }

package/src/stack-versions.generated.json

@@ -1,48 +1,46 @@
 {
   "$comment": "Auto-generated by scripts/sync-scaffold-deps.mjs — do not edit; run pnpm sync:scaffold-deps",
   "zhinStack": {
-    "zhin.js": "^4.1.0",
-    "@zhin.js/cli": "^1.0.91",
-    "@zhin.js/agent": "^1.0.1",
-    "@zhin.js/database": "^1.0.74",
-    "@zhin.js/host-router": "^2.0.1",
-    "@zhin.js/host-api": "^2.0.3",
-    "@zhin.js/client": "^2.0.3",
-    "@zhin.js/contract": "^1.0.1",
-    "@zhin.js/satori": "^1.0.15",
-    "@zhin.js/speech": "^1.0.1",
-    "@zhin.js/html-renderer": "^1.0.1",
-    "@zhin.js/mcp": "^4.0.0",
-    "@zhin.js/adapter-sandbox": "^5.0.3",
-    "@zhin.js/adapter-dingtalk": "^4.0.0",
-    "@zhin.js/adapter-discord": "^5.0.0",
-    "@zhin.js/adapter-email": "^3.0.0",
-    "@zhin.js/adapter-github": "^3.0.0",
-    "@zhin.js/adapter-icqq": "^6.0.0",
-    "@zhin.js/adapter-kook": "^5.0.0",
-    "@zhin.js/adapter-lark": "^4.0.0",
-    "@zhin.js/adapter-line": "^2.0.0",
-    "@zhin.js/adapter-milky": "^3.0.0",
-    "@zhin.js/adapter-napcat": "^3.0.0",
-    "@zhin.js/adapter-onebot11": "^4.0.0",
-    "@zhin.js/adapter-onebot12": "^3.0.0",
-    "@zhin.js/adapter-qq": "^5.0.0",
-    "@zhin.js/adapter-satori": "^3.0.0",
-    "@zhin.js/adapter-slack": "^4.0.0",
-    "@zhin.js/adapter-telegram": "^5.0.0",
-    "@zhin.js/adapter-wechat-mp": "^3.0.0",
-    "@zhin.js/adapter-wecom": "^2.0.0",
-    "@zhin.js/adapter-weixin-ilink": "^3.0.0"
+    "zhin.js": "^5.0.0",
+    "@zhin.js/cli": "^2.0.0",
+    "@zhin.js/agent": "^1.0.5",
+    "@zhin.js/database": "^1.0.77",
+    "@zhin.js/client": "^2.1.0",
+    "@zhin.js/contract": "^1.0.5",
+    "@zhin.js/satori": "^1.0.16",
+    "@zhin.js/speech": "^2.0.0",
+    "@zhin.js/html-renderer": "^2.0.0",
+    "@zhin.js/mcp": "^5.0.0",
+    "@zhin.js/adapter-sandbox": "^6.0.0",
+    "@zhin.js/adapter-dingtalk": "^5.0.0",
+    "@zhin.js/adapter-discord": "^6.0.0",
+    "@zhin.js/adapter-email": "^4.0.0",
+    "@zhin.js/adapter-github": "^4.0.0",
+    "@zhin.js/adapter-icqq": "^7.0.0",
+    "@zhin.js/adapter-kook": "^6.0.0",
+    "@zhin.js/adapter-lark": "^5.0.0",
+    "@zhin.js/adapter-line": "^3.0.0",
+    "@zhin.js/adapter-milky": "^5.0.0",
+    "@zhin.js/adapter-napcat": "^5.0.0",
+    "@zhin.js/adapter-onebot11": "^5.0.0",
+    "@zhin.js/adapter-onebot12": "^4.0.0",
+    "@zhin.js/adapter-qq": "^6.0.0",
+    "@zhin.js/adapter-satori": "^4.0.0",
+    "@zhin.js/adapter-slack": "^5.0.0",
+    "@zhin.js/adapter-telegram": "^6.0.0",
+    "@zhin.js/adapter-wechat-mp": "^4.0.0",
+    "@zhin.js/adapter-wecom": "^3.0.0",
+    "@zhin.js/adapter-weixin-ilink": "^4.0.0"
   },
   "aiStack": {
-    "@zhin.js/agent": "^1.0.1",
+    "@zhin.js/agent": "^1.0.5",
     "ai": "^7.0.0",
     "zod": "^4.0.0",
-    "@ai-sdk/openai": "^4.0.0",
-    "@ai-sdk/anthropic": "^4.0.0",
-    "@ai-sdk/google": "^4.0.0",
-    "@ai-sdk/deepseek": "^3.0.0",
-    "@ai-sdk/openai-compatible": "^3.0.0",
+    "@ai-sdk/openai": "^4.0.8",
+    "@ai-sdk/anthropic": "^4.0.9",
+    "@ai-sdk/google": "^4.0.9",
+    "@ai-sdk/deepseek": "^3.0.5",
+    "@ai-sdk/openai-compatible": "^3.0.5",
     "@modelcontextprotocol/sdk": "^1.29.0"
   }
 }

package/src/zhin-stack-deps.ts

@@ -20,8 +20,6 @@ export const ZHIN_STACK_VERSIONS = {
   '@zhin.js/component': 'latest',
   '@zhin.js/core': 'latest',
   '@zhin.js/tool': 'latest',
-  '@zhin.js/host-router': 'latest',
-  '@zhin.js/host-api': 'latest',
   '@zhin.js/client': 'latest',
   '@zhin.js/contract': 'latest',
   '@zhin.js/satori': 'latest',
@@ -52,11 +50,6 @@ export const ZHIN_STACK_VERSIONS = {
 
 export type ZhinStackPackage = keyof typeof ZHIN_STACK_VERSIONS;
 
-const HOST_CONSOLE_PLUGINS = new Set([
-  '@zhin.js/host-router',
-  '@zhin.js/host-api',
-]);
-
 function parseMajor(versionSpec: string | undefined): number | undefined {
   if (!versionSpec?.trim()) return undefined;
   if (versionSpec === 'workspace:*') return undefined;
@@ -115,17 +108,13 @@ export function getCreateBotPnpmConfig(_aiEnabled?: boolean): Record<string, unk
   };
 }
 
-/** create-zhin-app Plugin Runtime 骨架 production 依赖（不含适配器 / AI / 数据库驱动） */
+/**
+ * create-zhin-app Plugin Runtime 骨架 production 依赖（不含适配器 / AI / 数据库驱动）。
+ * Stable Features（adapter/command/component/middleware）由 `@zhin.js/core` 的 `package.json#zhin.features` 继承；创作面 API 经 `zhin.js/*` 便利入口。
+ */
 export function getCreateBotBaseDependencies(): Record<string, string> {
   return {
     'zhin.js': ZHIN_STACK_VERSIONS['zhin.js'],
-    '@zhin.js/plugin-runtime': ZHIN_STACK_VERSIONS['@zhin.js/plugin-runtime'],
-    '@zhin.js/runtime': ZHIN_STACK_VERSIONS['@zhin.js/runtime'],
-    '@zhin.js/adapter': ZHIN_STACK_VERSIONS['@zhin.js/adapter'],
-    '@zhin.js/command': ZHIN_STACK_VERSIONS['@zhin.js/command'],
-    '@zhin.js/component': ZHIN_STACK_VERSIONS['@zhin.js/component'],
-    '@zhin.js/core': ZHIN_STACK_VERSIONS['@zhin.js/core'],
-    '@zhin.js/satori': ZHIN_STACK_VERSIONS['@zhin.js/satori'],
   };
 }
 
@@ -149,13 +138,6 @@ export function getRequiredZhinDependenciesForConfig(config: Record<string, unkn
     }
   }
 
-  const usesHost = collectZhinPluginsFromConfig(config).some((p) => HOST_CONSOLE_PLUGINS.has(p));
-  if (usesHost) {
-    for (const pkg of ['@zhin.js/host-router', '@zhin.js/host-api'] as const) {
-      deps[pkg] = ZHIN_STACK_VERSIONS[pkg];
-    }
-  }
-
   return deps;
 }