@zhin.js/scaffold-wizard 0.1.9 → 0.2.1

package/src/adapter.ts

@@ -5,12 +5,18 @@ 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';
+import { formatEnvValue } from './env.js';
 
 /** 一个待挂载的子插件实例（package.json zhin.plugins 清单 + zhin.config plugins.<instanceKey> 配置） */
 export interface AdapterPluginInstance {
@@ -32,7 +38,7 @@ export interface AdapterSetupResult {
 }
 
 // 适配器定义
-interface AdapterDefinition {
+export interface AdapterDefinition {
   name: string;
   value: string;
   package: string;
@@ -48,7 +54,7 @@ interface AdapterDefinition {
   fields: AdapterField[];
 }
 
-interface AdapterField {
+export interface AdapterField {
   key: string;
   message: string;
   type?: 'input' | 'password' | 'select';
@@ -56,9 +62,11 @@ interface AdapterField {
   required?: boolean;
   envKey?: string;       // 如果是敏感信息，对应的环境变量名
   choices?: { name: string; value: string }[];
+  /** 字段归属：endpoint 级（默认，进 endpoints[i]）或 shared（顶层共享字段） */
+  scope?: 'endpoint' | 'shared';
 }
 
-const ADAPTERS: AdapterDefinition[] = [
+export const ADAPTERS: AdapterDefinition[] = [
   {
     name: 'Sandbox (调试沙盒，默认)',
     value: 'sandbox',
@@ -80,6 +88,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' },
     ],
   },
   {
@@ -153,6 +163,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' },
     ],
   },
@@ -167,7 +179,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' },
     ],
   },
   {
@@ -182,6 +211,54 @@ const ADAPTERS: AdapterDefinition[] = [
     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',
@@ -194,7 +271,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' },
     ],
   },
   {
@@ -227,6 +323,18 @@ const ADAPTERS: AdapterDefinition[] = [
     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: [],
+  },
 ];
 
 /**
@@ -253,7 +361,7 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
         if (input.length === 0) return '至少选择一个适配器';
         return true;
       },
-      pageSize: 14,
+      pageSize: 22,
     }
   ]);
 
@@ -374,7 +482,7 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
     result.instances.push({
       package: adapterDef.package,
       instanceKey: adapterDef.value,
-      config: buildFieldBasedInstanceConfig(adapterDef.value, fieldValues),
+      config: buildFieldBasedInstanceConfig(adapterDef, fieldValues),
     });
   }
 
@@ -382,36 +490,56 @@ export async function configureAdapters(): Promise<AdapterSetupResult> {
 }
 
 /**
- * 字段式适配器（无自定义 configure）的实例配置整形，对齐各插件 schema.json：
- * - wechat-mp：webhookPath → path
- * - email：smtp/imap 平铺字段 → smtp/imap 嵌套对象
- * - 其余：字段直传
+ * 字段式适配器（无自定义 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` 兜底
  */
-function buildFieldBasedInstanceConfig(adapterValue: string, values: Record<string, any>): Record<string, unknown> {
-  if (adapterValue === 'wechat-mp') {
-    const { webhookPath, ...rest } = values;
-    return { ...rest, path: webhookPath ?? '/wechat/webhook' };
-  }
-  if (adapterValue === 'email') {
+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 {
-      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,
-      },
+      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 values;
+
+  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;
+    }
+  }
+  if (adapter.value === 'wechat-mp' && shared.webhookPath !== undefined) {
+    shared.path = shared.webhookPath;
+    delete shared.webhookPath;
+  }
+  if (!endpoint.name) {
+    endpoint.name = `${adapter.value}-bot`;
+  }
+  return { ...shared, endpoints: [endpoint] };
 }
 
 /**
@@ -423,7 +551,7 @@ export function generateAdapterEnvVars(result: AdapterSetupResult): string {
 
   const lines: string[] = ['', '# 适配器配置'];
   for (const [key, value] of entries) {
-    lines.push(`${key}=${value}`);
+    lines.push(`${key}=${formatEnvValue(value)}`);
   }
   return lines.join('\n');
 }
@@ -464,12 +592,14 @@ export function getAdapterSetupNotes(result: AdapterSetupResult): string[] {
       notes.push('Telegram polling: 本地开发可直接 pnpm dev，无需公网');
     }
     if (context === 'github') {
-      if (entry.webhook_secret) {
+      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 完成认证');
@@ -521,3 +651,10 @@ export function getAdapterDependencies(result: AdapterSetupResult): Record<strin
 
   return deps;
 }
+
+/**
+ * 按 npm 包名查找已知适配器定义（如 @zhin.js/adapter-telegram）
+ */
+export function findAdapterByPackage(packageName: string): AdapterDefinition | undefined {
+  return ADAPTERS.find(a => a.package === packageName || a.plugin === packageName);
+}

package/src/ai.ts

@@ -1,5 +1,6 @@
 import inquirer from 'inquirer';
 import chalk from 'chalk';
+import { formatEnvValue } from './env.js';
 
 export interface AISetupConfig {
   enabled: boolean;
@@ -103,6 +104,16 @@ export function providerSdkFor(name: string): string {
   }
 }
 
+/**
+ * openai-compatible sdk 在 runtime 无 baseUrl 无法建 provider
+ * （packages/im/ai sdk-provider-adapter 直接拒绝），这些 provider 的 baseUrl 必填，
+ * 向导预填官方地址。
+ */
+export const PROVIDER_DEFAULT_BASE_URLS: Readonly<Record<string, string>> = Object.freeze({
+  zhipu: 'https://open.bigmodel.cn/api/paas/v4',
+  moonshot: 'https://api.moonshot.cn/v1',
+});
+
 function defaultModelForProvider(driver: string): string {
   const entry = PROVIDERS.find(p => p.value === driver);
   return entry?.defaultModel ?? '';
@@ -192,7 +203,7 @@ export const RECOMMENDED_AI_DEFAULTS = {
 export async function configureAI(): Promise<AISetupConfig> {
   console.log('');
   console.log(chalk.blue('🤖 配置 AI 智能体'));
-  console.log(chalk.gray('  启用后将自动写入 package.json：@zhin.js/agent、zod、ai、所选 @ai-sdk/*、@modelcontextprotocol/sdk。'));
+  console.log(chalk.gray('  启用后将自动写入 package.json：@zhin.js/agent、zod、ai、所选 @ai-sdk/*（启用 memory MCP 时另加 @modelcontextprotocol/sdk）。'));
   console.log(chalk.gray('  会话持久化默认开启，将自动配置 SQLite 数据库（若尚未选择）。'));
 
   const { enableAI } = await inquirer.prompt([
@@ -253,6 +264,7 @@ export async function configureAI(): Promise<AISetupConfig> {
       models: [ollamaConfig.model.trim()],
     };
   } else {
+    const defaultBaseUrl = PROVIDER_DEFAULT_BASE_URLS[provider];
     const cloudConfig = await inquirer.prompt([
       {
         type: 'input',
@@ -272,8 +284,13 @@ export async function configureAI(): Promise<AISetupConfig> {
       {
         type: 'input',
         name: 'baseUrl',
-        message: '自定义 API 地址（留空使用官方默认）:',
-        default: '',
+        message: defaultBaseUrl
+          ? 'API 地址（该提供商 sdk 为 openai-compatible，baseUrl 必填）:'
+          : '自定义 API 地址（留空使用官方默认）:',
+        default: defaultBaseUrl ?? '',
+        validate: defaultBaseUrl
+          ? (input: string) => (input.trim() ? true : 'baseUrl 不能为空（openai-compatible 无默认地址）')
+          : undefined,
       }
     ]);
 
@@ -389,7 +406,7 @@ export function generateAIEnvVars(config: AISetupConfig): string {
   for (const [, providerConfig] of Object.entries(config.providers)) {
     const realKey = (providerConfig as any).__envApiKey;
     if (realKey) {
-      envVars.push(`AI_API_KEY=${realKey}`);
+      envVars.push(`AI_API_KEY=${formatEnvValue(realKey)}`);
     }
   }
 

package/src/apply.ts

@@ -10,21 +10,14 @@ import {
   getAdapterDependencies,
 } from './adapter.js';
 import { generateAIEnvVars, materializeAIConfig } from './ai.js';
+import { generateDatabaseEnvVars, mergeEnvText } from './env.js';
 import { ensureDatabaseForAdapters, ensureDatabaseForAI, getAIDependencies } from './project-deps.js';
-import { DEFAULT_CREATE_BOT_HTTP_PORT } from './zhin-stack-deps.js';
+import { DEFAULT_CREATE_BOT_HTTP_PORT, ZHIN_STACK_VERSIONS } from './zhin-stack-deps.js';
 import { packageToInstanceKey } from './project-config-plan.js';
 
-/**
- * @deprecated Plugin Runtime 由 CLI composition root 装配 Console/HTTP Host，
- * 不再需要在 plugins 清单中声明 host 插件；保留导出仅为兼容。
- */
-export const CONSOLE_HOST_PLUGINS = [
-  '@zhin.js/host-router',
-  '@zhin.js/host-api',
-] as const;
-
 export function applyDatabaseToConfig(config: Record<string, unknown>, database: DatabaseConfig): void {
-  config.database = database;
+  // 物化为可落盘对象：非 SQLite 连接参数引用 .env（${VAR}），明文密码不进配置文件
+  config.database = materializeDatabaseConfig(database);
 }
 
 /** 将 legacy 数组形式 plugins 归一化为新 runtime 的 instanceKey 映射 */
@@ -46,13 +39,63 @@ export function normalizePluginsMap(value: unknown): Record<string, unknown> {
 export function applyAdaptersToConfig(config: Record<string, unknown>, result: AdapterSetupResult): void {
   const plugins = normalizePluginsMap(config.plugins);
   for (const instance of result.instances) {
-    plugins[instance.instanceKey] = instance.config;
+    plugins[instance.instanceKey] = mergeAdapterInstanceConfig(
+      instance.instanceKey,
+      plugins[instance.instanceKey],
+      instance.config,
+    );
   }
   config.plugins = plugins;
   // legacy endpoints 列表不被 runtime 配置 schema 接受（additionalProperties: false）
   delete config.endpoints;
 }
 
+function endpointName(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;
+}
+
+/**
+ * 重跑向导时按实例合并配置而非整体覆盖：保留现有 endpoints 中 name 不冲突的项
+ * 与其他实例级键；被向导结果覆盖的 endpoints / 键在覆盖前打印提示。
+ */
+function mergeAdapterInstanceConfig(
+  instanceKey: string,
+  existing: unknown,
+  next: Record<string, unknown>,
+): Record<string, unknown> {
+  if (!existing || typeof existing !== 'object' || Array.isArray(existing)) return next;
+  const current = existing as Record<string, unknown>;
+  const dropped: string[] = [];
+
+  const merged: Record<string, unknown> = { ...current, ...next };
+
+  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 kept = currentEndpoints.filter((endpoint) => {
+      const name = endpointName(endpoint);
+      if (name != null && nextNames.has(name)) {
+        dropped.push(`endpoint "${name}"`);
+        return false;
+      }
+      return true;
+    });
+    merged.endpoints = [...nextEndpoints, ...kept];
+  }
+
+  for (const key of Object.keys(next)) {
+    if (key !== 'endpoints' && key in current) dropped.push(`键 "${key}"`);
+  }
+
+  if (dropped.length > 0) {
+    console.warn(`[zhin setup] plugins.${instanceKey} 的 ${dropped.join('、')} 已被向导结果覆盖`);
+  }
+  return merged;
+}
+
 export function applyAIToConfig(config: Record<string, unknown>, ai: AISetupConfig): void {
   config.ai = materializeAIConfig(ai);
 }
@@ -90,14 +133,17 @@ export async function appendWizardEnvVars(
   projectDir: string,
   adapters?: AdapterSetupResult,
   ai?: AISetupConfig,
+  database?: DatabaseConfig,
 ): Promise<void> {
   const extra =
+    (database ? generateDatabaseEnvVars(database) : '') +
     (adapters ? generateAdapterEnvVars(adapters) : '') +
     (ai ? generateAIEnvVars(ai) : '');
-  if (extra) {
+  if (extra.trim()) {
     const envPath = path.join(projectDir, '.env');
     const existing = (await fs.pathExists(envPath)) ? await fs.readFile(envPath, 'utf-8') : '';
-    await fs.writeFile(envPath, existing.replace(/\s*$/, '') + extra + '\n');
+    // 按 KEY 覆盖而非追加：重复运行向导幂等，不产生重复行
+    await fs.writeFile(envPath, mergeEnvText(existing, extra));
   }
 
   // 新 Plugin Runtime 通过 package.json zhin.plugins 清单挂载子插件，与依赖一起落盘
@@ -112,9 +158,47 @@ export function collectWizardDependencies(
   return {
     ...(options.adapters ? getAdapterDependencies(options.adapters) : {}),
     ...getAIDependencies(options.ai),
+    // tools/ 约定需要 @zhin.js/tool（与 create-zhin 路径对齐）
+    ...(options.ai?.enabled ? { '@zhin.js/tool': ZHIN_STACK_VERSIONS['@zhin.js/tool'] } : {}),
   };
 }
 
+/** 向导结果需要合并进 package.json zhin.features 的条目（与 create-zhin 路径对齐） */
+export function collectWizardFeatures(
+  options: Pick<InitOptions, 'ai'>,
+): Array<{ package: string; api: string }> {
+  return options.ai?.enabled ? [{ package: '@zhin.js/tool', api: '^1.0.0' }] : [];
+}
+
+/** 把 features 清单条目合并进项目 package.json 的 zhin.features（zhin setup 路径） */
+export async function mergeFeaturesIntoPackageJson(
+  projectDir: string,
+  entries: Array<{ package: string; api: string }>,
+): Promise<boolean> {
+  if (entries.length === 0) return false;
+  const pkgPath = path.join(projectDir, 'package.json');
+  if (!(await fs.pathExists(pkgPath))) return false;
+
+  const pkg = await fs.readJson(pkgPath);
+  const zhin = pkg.zhin && typeof pkg.zhin === 'object' && !Array.isArray(pkg.zhin)
+    ? pkg.zhin
+    : { protocol: 1, type: 'plugin', entry: './plugin.ts' };
+  const features: Array<{ package: string; api?: string }> = Array.isArray(zhin.features)
+    ? [...zhin.features]
+    : [];
+  let changed = false;
+  for (const entry of entries) {
+    if (features.some((item) => item?.package === entry.package)) continue;
+    features.push(entry);
+    changed = true;
+  }
+  if (!changed && pkg.zhin) return false;
+  zhin.features = features;
+  pkg.zhin = zhin;
+  await fs.writeJson(pkgPath, pkg, { spaces: 2 });
+  return true;
+}
+
 export async function mergeDependenciesIntoPackageJson(
   projectDir: string,
   deps: Record<string, string>,

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')}` : '';
+}