@zhin.js/scaffold-wizard 0.1.6 → 0.1.7

package/src/project-deps.ts

@@ -4,22 +4,62 @@ import path from 'node:path';
 import type { AISetupConfig } from './ai.js';
 import type { InitOptions } from './types.js';
 
-/** 新项目依赖默认接受 npm latest 漂移，避免脚手架维护固定版本表。 */
-export const MCP_SDK_VERSION = 'latest';
+/**
+ * User project dependency policy: scaffolded dependencies intentionally float to latest.
+ */
+export const AI_STACK_VERSIONS = {
+  '@zhin.js/agent': 'latest',
+  zod: 'latest',
+  ai: 'latest',
+  '@modelcontextprotocol/sdk': 'latest',
+  '@ai-sdk/openai': 'latest',
+  '@ai-sdk/anthropic': 'latest',
+  '@ai-sdk/google': 'latest',
+  '@ai-sdk/deepseek': 'latest',
+  '@ai-sdk/openai-compatible': 'latest',
+} as const;
 
-const AI_STACK_VERSION = 'latest';
-const ZOD_VERSION = 'latest';
-const VERCEL_AI_VERSION = 'latest';
+/** @deprecated 使用 AI_STACK_VERSIONS['@modelcontextprotocol/sdk'] */
+export const MCP_SDK_VERSION = AI_STACK_VERSIONS['@modelcontextprotocol/sdk'];
+
+const WIZARD_ALIAS_TO_SDK: Record<string, string> = {
+  openai: 'openai',
+  anthropic: 'anthropic',
+  deepseek: 'deepseek',
+  google: 'google',
+  gemini: 'google',
+  ollama: 'ollama',
+  moonshot: 'openai-compatible',
+  zhipu: 'openai-compatible',
+};
+
+const SDK_TO_NPM_PACKAGE: Record<string, keyof typeof AI_STACK_VERSIONS> = {
+  openai: '@ai-sdk/openai',
+  anthropic: '@ai-sdk/anthropic',
+  google: '@ai-sdk/google',
+  deepseek: '@ai-sdk/deepseek',
+  ollama: '@ai-sdk/openai-compatible',
+  'openai-compatible': '@ai-sdk/openai-compatible',
+};
 
 const PROVIDER_SDK_PACKAGES: Record<string, { pkg: string; version: string }> = {
-  openai: { pkg: '@ai-sdk/openai', version: 'latest' },
-  anthropic: { pkg: '@ai-sdk/anthropic', version: 'latest' },
-  google: { pkg: '@ai-sdk/google', version: 'latest' },
-  gemini: { pkg: '@ai-sdk/google', version: 'latest' },
-  deepseek: { pkg: '@ai-sdk/deepseek', version: 'latest' },
-  ollama: { pkg: '@ai-sdk/openai-compatible', version: 'latest' },
-  moonshot: { pkg: '@ai-sdk/openai-compatible', version: 'latest' },
-  zhipu: { pkg: '@ai-sdk/openai-compatible', version: 'latest' },
+  openai: { pkg: '@ai-sdk/openai', version: AI_STACK_VERSIONS['@ai-sdk/openai'] },
+  anthropic: { pkg: '@ai-sdk/anthropic', version: AI_STACK_VERSIONS['@ai-sdk/anthropic'] },
+  google: { pkg: '@ai-sdk/google', version: AI_STACK_VERSIONS['@ai-sdk/google'] },
+  gemini: { pkg: '@ai-sdk/google', version: AI_STACK_VERSIONS['@ai-sdk/google'] },
+  deepseek: { pkg: '@ai-sdk/deepseek', version: AI_STACK_VERSIONS['@ai-sdk/deepseek'] },
+  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'] },
+};
+
+/** @ai-sdk/* 主版本 ≥ threshold 时需 ai@7 */
+const AI7_REQUIRED_SDK_MAJOR: Record<string, number> = {
+  '@ai-sdk/openai-compatible': 3,
+  '@ai-sdk/openai': 4,
+  '@ai-sdk/anthropic': 4,
+  '@ai-sdk/google': 4,
+  '@ai-sdk/deepseek': 3,
 };
 
 function providerSdkPackage(provider?: string): { pkg: string; version: string } | undefined {
@@ -27,6 +67,147 @@ function providerSdkPackage(provider?: string): { pkg: string; version: string }
   return PROVIDER_SDK_PACKAGES[provider];
 }
 
+function inferSdkId(providerAlias: string, entry?: { sdk?: string }): string | undefined {
+  const explicit = entry?.sdk?.trim();
+  if (explicit) return explicit;
+  if (WIZARD_ALIAS_TO_SDK[providerAlias]) return WIZARD_ALIAS_TO_SDK[providerAlias];
+  if (SDK_TO_NPM_PACKAGE[providerAlias]) return providerAlias;
+  return undefined;
+}
+
+function packagesForSdkIds(sdkIds: Iterable<string>): Record<string, string> {
+  const deps: Record<string, string> = {};
+  for (const sdkId of sdkIds) {
+    const npmName = SDK_TO_NPM_PACKAGE[sdkId];
+    if (!npmName) continue;
+    deps[npmName] = AI_STACK_VERSIONS[npmName];
+  }
+  return deps;
+}
+
+function collectSdkPackagesFromSetup(ai: AISetupConfig): Record<string, string> {
+  const sdkIds = new Set<string>();
+  const agentProvider = ai.agentProvider ?? ai.defaultProvider;
+  if (agentProvider) {
+    const id = inferSdkId(agentProvider, ai.providers?.[agentProvider] as { sdk?: string });
+    if (id) sdkIds.add(id);
+  }
+  for (const [alias, entry] of Object.entries(ai.providers ?? {})) {
+    const id = inferSdkId(alias, entry as { sdk?: string });
+    if (id) sdkIds.add(id);
+  }
+  return packagesForSdkIds(sdkIds);
+}
+
+function collectSdkPackagesFromConfig(config: { ai?: unknown }): Record<string, string> {
+  const ai = config.ai;
+  if (!ai || typeof ai !== 'object' || Array.isArray(ai)) return {};
+  const rec = ai as Record<string, unknown>;
+  const providers = rec.providers as Record<string, { sdk?: string }> | undefined;
+  const sdkIds = new Set<string>();
+
+  if (providers) {
+    for (const [alias, entry] of Object.entries(providers)) {
+      const id = inferSdkId(alias, entry);
+      if (id) sdkIds.add(id);
+    }
+  }
+
+  const agents = rec.agents as Record<string, { provider?: string }> | undefined;
+  if (agents && providers) {
+    for (const agent of Object.values(agents)) {
+      if (!agent?.provider) continue;
+      const id = inferSdkId(agent.provider, providers[agent.provider]);
+      if (id) sdkIds.add(id);
+    }
+  }
+
+  if (sdkIds.size === 0) {
+    const alias = resolveDefaultProviderFromConfig(config);
+    if (alias) {
+      const id = inferSdkId(alias, providers?.[alias]);
+      if (id) sdkIds.add(id);
+    }
+  }
+
+  return packagesForSdkIds(sdkIds);
+}
+
+function parseMajor(versionSpec: string | undefined): number | undefined {
+  if (!versionSpec?.trim()) return undefined;
+  const match = versionSpec.trim().replace(/^[\^~>=<]+/, '').match(/^(\d+)/);
+  return match ? Number(match[1]) : undefined;
+}
+
+function getDeclaredPackageVersion(pkg: PackageJsonLike, name: string): string | undefined {
+  return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
+}
+
+function readInstalledMajor(cwd: string, packageName: string): number | undefined {
+  const pkgJson = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgJson)) return undefined;
+  try {
+    const req = createRequire(pkgJson);
+    const installed = req(`${packageName}/package.json`) as { version?: string };
+    return parseMajor(installed.version);
+  } catch {
+    return undefined;
+  }
+}
+
+function resolvePackageMajor(cwd: string, pkg: PackageJsonLike, packageName: string): number | undefined {
+  return readInstalledMajor(cwd, packageName) ?? parseMajor(getDeclaredPackageVersion(pkg, packageName));
+}
+
+export interface AiStackIncompatibility {
+  package: string;
+  reason: string;
+}
+
+export function findOutdatedAiStackInPackageJson(
+  pkg: PackageJsonLike,
+  required: Record<string, string>,
+): string[] {
+  const outdated: string[] = [];
+  for (const [name, minSpec] of Object.entries(required)) {
+    const declared = getDeclaredPackageVersion(pkg, name);
+    if (!declared) continue;
+    const declaredMajor = parseMajor(declared);
+    const minMajor = parseMajor(minSpec);
+    if (declaredMajor != null && minMajor != null && declaredMajor < minMajor) {
+      outdated.push(name);
+    }
+  }
+  return outdated;
+}
+
+export function findInstalledAiStackIncompatibilities(
+  cwd: string,
+  pkg: PackageJsonLike,
+): AiStackIncompatibility[] {
+  const aiMajor = resolvePackageMajor(cwd, pkg, 'ai');
+  if (aiMajor == null || aiMajor >= 7) return [];
+
+  const issues: AiStackIncompatibility[] = [];
+  if (aiMajor < 7) {
+    issues.push({
+      package: 'ai',
+      reason: 'ai@6 与 @ai-sdk/openai-compatible@3（v4 model spec）不兼容，请升级 ai 至 ^7.0.0',
+    });
+  }
+
+  for (const [name, threshold] of Object.entries(AI7_REQUIRED_SDK_MAJOR)) {
+    const major = resolvePackageMajor(cwd, pkg, name);
+    if (major == null || major < threshold) continue;
+    issues.push({
+      package: name,
+      reason: `${name}@${major} 需要 ai@7（当前 ai@${aiMajor}）`,
+    });
+  }
+
+  return issues;
+}
+
 /** 启用 AI 时将写入 package.json 的依赖名（用于向导提示与 CLI 输出） */
 export function listAIDependencyNames(provider?: string, options?: { includeMcp?: boolean }): string[] {
   const names = ['@zhin.js/agent', 'zod', 'ai'];
@@ -99,10 +280,14 @@ export function getRequiredAIDependenciesForConfig(config: { ai?: unknown }): Re
   const ai = config.ai as Record<string, unknown>;
   const setup: AISetupConfig = {
     enabled: true,
-    defaultProvider: resolveDefaultProviderFromConfig(config),
+    agentProvider: resolveDefaultProviderFromConfig(config),
+    providers: ai.providers as AISetupConfig['providers'],
     memoryMcp: aiConfigNeedsMcp(ai),
   };
-  const deps = getAIDependencies(setup);
+  const deps = {
+    ...getAIDependencies(setup),
+    ...collectSdkPackagesFromConfig(config),
+  };
   if (!aiConfigNeedsMcp(ai)) {
     delete deps['@modelcontextprotocol/sdk'];
   }
@@ -140,9 +325,25 @@ export interface AIDependencyDiagnosis {
   provider?: string;
   required: Record<string, string>;
   missingFromPackageJson: string[];
+  outdatedInPackageJson: string[];
+  incompatibleInstalled: AiStackIncompatibility[];
   notInstalled: string[];
 }
 
+export function packagesNeedingAiStackFix(diagnosis: AIDependencyDiagnosis): string[] {
+  const names = new Set<string>([
+    ...diagnosis.missingFromPackageJson,
+    ...diagnosis.outdatedInPackageJson,
+  ]);
+  for (const issue of diagnosis.incompatibleInstalled) {
+    names.add(issue.package);
+  }
+  if (diagnosis.incompatibleInstalled.some((issue) => issue.package !== 'ai')) {
+    names.add('ai');
+  }
+  return [...names];
+}
+
 export function diagnoseAIDependencies(
   cwd: string,
   config: { ai?: unknown },
@@ -153,6 +354,8 @@ export function diagnoseAIDependencies(
   const packageJsonPath = path.join(cwd, 'package.json');
   const packageJson = pkg ?? (fs.existsSync(packageJsonPath) ? fs.readJsonSync(packageJsonPath) as PackageJsonLike : {});
   const missingFromPackageJson = findMissingPackageDependencies(packageJson, required);
+  const outdatedInPackageJson = findOutdatedAiStackInPackageJson(packageJson, required);
+  const incompatibleInstalled = findInstalledAiStackIncompatibilities(cwd, packageJson);
   const declared = Object.keys(required).filter((name) => !missingFromPackageJson.includes(name));
   const notInstalled = findUnresolvedPackageInstalls(cwd, declared);
   return {
@@ -160,13 +363,15 @@ export function diagnoseAIDependencies(
     provider: resolveDefaultProviderFromConfig(config),
     required,
     missingFromPackageJson,
+    outdatedInPackageJson,
+    incompatibleInstalled,
     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'}`);
+export function formatAIDependencyFixCommand(packages: string[], required: Record<string, string>): string {
+  if (packages.length === 0) return 'pnpm install';
+  const specs = packages.map((name) => `${name}@${required[name] ?? 'latest'}`);
   return `pnpm add ${specs.join(' ')}`;
 }
 
@@ -177,17 +382,13 @@ export function getAIDependencies(ai?: AISetupConfig): Record<string, string> {
   if (!ai?.enabled) return {};
 
   const deps: Record<string, string> = {
-    '@zhin.js/agent': AI_STACK_VERSION,
-    zod: ZOD_VERSION,
-    ai: VERCEL_AI_VERSION,
-    '@modelcontextprotocol/sdk': MCP_SDK_VERSION,
+    '@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 sdk = providerSdkPackage(ai.defaultProvider);
-  if (sdk) {
-    deps[sdk.pkg] = sdk.version;
-  }
-
   return deps;
 }
 

package/src/stack-versions.generated.json

@@ -0,0 +1,48 @@
+{
+  "$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"
+  },
+  "aiStack": {
+    "@zhin.js/agent": "^1.0.1",
+    "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",
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  }
+}

package/src/upgrade-l4.ts

@@ -8,6 +8,7 @@ import {
   isAiEnabledInConfig,
   findMissingPackageDependencies,
   findUnresolvedPackageInstalls,
+  packagesNeedingAiStackFix,
 } from './project-deps.js';
 import { diagnoseOptionalPeers, formatOptionalPeerFixCommand, getOptionalPeerDependencies } from './optional-peers.js';
 
@@ -52,7 +53,7 @@ export function diagnoseUpgradeToL4(
   const optionalPeers = diagnoseOptionalPeers(cwd, config, packageJson);
 
   const missingAiDeps = ai
-    ? [...new Set([...ai.missingFromPackageJson, ...ai.notInstalled])]
+    ? [...new Set([...packagesNeedingAiStackFix(ai), ...ai.notInstalled])]
     : [...Object.keys(getRequiredAIDependenciesForConfig({ ai: { enabled: true } }))];
 
   if (!aiEnabled) {

package/src/zhin-stack-deps.ts

@@ -0,0 +1,252 @@
+import { createRequire } from 'node:module';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { DATABASE_PACKAGES } from './types.js';
+import type { PackageJsonLike } from './project-deps.js';
+import {
+  findMissingPackageDependencies,
+  findUnresolvedPackageInstalls,
+  isAiEnabledInConfig,
+} from './project-deps.js';
+
+/**
+ * User project dependency policy: scaffolded dependencies intentionally float to latest.
+ */
+export const ZHIN_STACK_VERSIONS = {
+  'zhin.js': 'latest',
+  '@zhin.js/cli': 'latest',
+  '@zhin.js/agent': 'latest',
+  '@zhin.js/database': 'latest',
+  '@zhin.js/host-router': 'latest',
+  '@zhin.js/host-api': 'latest',
+  '@zhin.js/client': 'latest',
+  '@zhin.js/contract': 'latest',
+  '@zhin.js/satori': 'latest',
+  '@zhin.js/speech': 'latest',
+  '@zhin.js/html-renderer': 'latest',
+  '@zhin.js/mcp': 'latest',
+  '@zhin.js/adapter-sandbox': 'latest',
+  '@zhin.js/adapter-dingtalk': 'latest',
+  '@zhin.js/adapter-discord': 'latest',
+  '@zhin.js/adapter-email': 'latest',
+  '@zhin.js/adapter-github': 'latest',
+  '@zhin.js/adapter-icqq': 'latest',
+  '@zhin.js/adapter-kook': 'latest',
+  '@zhin.js/adapter-lark': 'latest',
+  '@zhin.js/adapter-line': 'latest',
+  '@zhin.js/adapter-milky': 'latest',
+  '@zhin.js/adapter-napcat': 'latest',
+  '@zhin.js/adapter-onebot11': 'latest',
+  '@zhin.js/adapter-onebot12': 'latest',
+  '@zhin.js/adapter-qq': 'latest',
+  '@zhin.js/adapter-satori': 'latest',
+  '@zhin.js/adapter-slack': 'latest',
+  '@zhin.js/adapter-telegram': 'latest',
+  '@zhin.js/adapter-wechat-mp': 'latest',
+  '@zhin.js/adapter-wecom': 'latest',
+  '@zhin.js/adapter-weixin-ilink': 'latest',
+} as const;
+
+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;
+  const match = versionSpec.trim().replace(/^[\^~>=<]+/, '').match(/^(\d+)/);
+  return match ? Number(match[1]) : undefined;
+}
+
+function getDeclaredPackageVersion(pkg: PackageJsonLike, name: string): string | undefined {
+  return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
+}
+
+function readInstalledMajor(cwd: string, packageName: string): number | undefined {
+  const pkgJson = path.join(cwd, 'package.json');
+  if (!fs.existsSync(pkgJson)) return undefined;
+  try {
+    const req = createRequire(pkgJson);
+    const installed = req(`${packageName}/package.json`) as { version?: string };
+    return parseMajor(installed.version);
+  } catch {
+    return undefined;
+  }
+}
+
+function resolvePackageMajor(cwd: string, pkg: PackageJsonLike, packageName: string): number | undefined {
+  return readInstalledMajor(cwd, packageName) ?? parseMajor(getDeclaredPackageVersion(pkg, packageName));
+}
+
+function resolveStackVersion(packageName: string): string {
+  return ZHIN_STACK_VERSIONS[packageName as ZhinStackPackage] ?? 'latest';
+}
+
+function collectZhinPluginsFromConfig(config: Record<string, unknown>): string[] {
+  const plugins = Array.isArray(config.plugins)
+    ? config.plugins.filter((p): p is string => typeof p === 'string')
+    : [];
+  return [...new Set(plugins.filter((p) => p.startsWith('@zhin.js/')))];
+}
+
+/** create-zhin / minimal-bot 默认 Host 端口（避免与常见 8086 占用冲突） */
+export const DEFAULT_CREATE_BOT_HTTP_PORT = 8068;
+
+/** create-zhin 生成项目的 .npmrc（避免全局 strict-peer-dependencies 阻断 AI 栈安装） */
+export const CREATE_BOT_NPMRC = 'strict-peer-dependencies=false\n';
+
+/** create-zhin 生成项目的 pnpm 配置 */
+export function getCreateBotPnpmConfig(_aiEnabled?: boolean): Record<string, unknown> {
+  return {
+    onlyBuiltDependencies: ['esbuild'],
+  };
+}
+
+/** create-zhin-app 默认 bot 骨架依赖（不含适配器 / AI / 数据库驱动） */
+export function getCreateBotBaseDependencies(): Record<string, string> {
+  return {
+    'zhin.js': ZHIN_STACK_VERSIONS['zhin.js'],
+    '@zhin.js/cli': ZHIN_STACK_VERSIONS['@zhin.js/cli'],
+    '@zhin.js/host-router': ZHIN_STACK_VERSIONS['@zhin.js/host-router'],
+    '@zhin.js/client': ZHIN_STACK_VERSIONS['@zhin.js/client'],
+    '@zhin.js/host-api': ZHIN_STACK_VERSIONS['@zhin.js/host-api'],
+    '@zhin.js/contract': ZHIN_STACK_VERSIONS['@zhin.js/contract'],
+    '@zhin.js/satori': ZHIN_STACK_VERSIONS['@zhin.js/satori'],
+  };
+}
+
+/** 根据 zhin.config 推导应声明的 @zhin.js/* / zhin.js 依赖 */
+export function getRequiredZhinDependenciesForConfig(config: Record<string, unknown>): Record<string, string> {
+  const deps: Record<string, string> = {
+    'zhin.js': ZHIN_STACK_VERSIONS['zhin.js'],
+  };
+
+  for (const plugin of collectZhinPluginsFromConfig(config)) {
+    deps[plugin] = resolveStackVersion(plugin);
+  }
+
+  const database = config.database;
+  if (database && typeof database === 'object' && !Array.isArray(database)) {
+    deps['@zhin.js/database'] = ZHIN_STACK_VERSIONS['@zhin.js/database'];
+    const dialect = String((database as Record<string, unknown>).dialect ?? '');
+    const driver = DATABASE_PACKAGES[dialect as keyof typeof DATABASE_PACKAGES];
+    if (driver) {
+      deps[driver] = 'latest';
+    }
+  }
+
+  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;
+}
+
+export interface ZhinStackIncompatibility {
+  package: string;
+  reason: string;
+}
+
+export function findOutdatedZhinStackInPackageJson(
+  pkg: PackageJsonLike,
+  required: Record<string, string>,
+): string[] {
+  const outdated: string[] = [];
+  for (const [name, minSpec] of Object.entries(required)) {
+    const declared = getDeclaredPackageVersion(pkg, name);
+    if (!declared || declared === 'workspace:*') continue;
+    const declaredMajor = parseMajor(declared);
+    const minMajor = parseMajor(minSpec);
+    if (declaredMajor != null && minMajor != null && declaredMajor < minMajor) {
+      outdated.push(name);
+    }
+  }
+  return outdated;
+}
+
+export function findInstalledZhinStackIncompatibilities(
+  cwd: string,
+  pkg: PackageJsonLike,
+  config: Record<string, unknown>,
+): ZhinStackIncompatibility[] {
+  const issues: ZhinStackIncompatibility[] = [];
+  const zhinMajor = resolvePackageMajor(cwd, pkg, 'zhin.js');
+  const agentDeclared = getDeclaredPackageVersion(pkg, '@zhin.js/agent');
+  const aiEnabled = isAiEnabledInConfig(config);
+
+  if (zhinMajor != null && zhinMajor < 4 && (aiEnabled || agentDeclared)) {
+    issues.push({
+      package: 'zhin.js',
+      reason: 'zhin.js 4.x 才支持 @zhin.js/agent 与 AI 安装分层（ADR 0019），请升级 zhin.js',
+    });
+  }
+
+  if (aiEnabled && !agentDeclared) {
+    // missing 由 missingFromPackageJson 处理；此处只报版本组合问题
+  }
+
+  const agentMajor = resolvePackageMajor(cwd, pkg, '@zhin.js/agent');
+  if (agentMajor != null && agentMajor < 1 && aiEnabled) {
+    issues.push({
+      package: '@zhin.js/agent',
+      reason: '@zhin.js/agent 1.x 与 zhin.js 4.x / AI SDK 7 配套，请升级 @zhin.js/agent',
+    });
+  }
+
+  return issues;
+}
+
+export interface ZhinStackDiagnosis {
+  required: Record<string, string>;
+  missingFromPackageJson: string[];
+  outdatedInPackageJson: string[];
+  incompatibleInstalled: ZhinStackIncompatibility[];
+  notInstalled: string[];
+}
+
+export function packagesNeedingZhinStackFix(diagnosis: ZhinStackDiagnosis): string[] {
+  const names = new Set<string>([
+    ...diagnosis.missingFromPackageJson,
+    ...diagnosis.outdatedInPackageJson,
+  ]);
+  for (const issue of diagnosis.incompatibleInstalled) {
+    names.add(issue.package);
+  }
+  return [...names];
+}
+
+export function diagnoseZhinStackDependencies(
+  cwd: string,
+  config: Record<string, unknown>,
+  pkg?: PackageJsonLike,
+): ZhinStackDiagnosis {
+  const required = getRequiredZhinDependenciesForConfig(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 outdatedInPackageJson = findOutdatedZhinStackInPackageJson(packageJson, required);
+  const incompatibleInstalled = findInstalledZhinStackIncompatibilities(cwd, packageJson, config);
+  const declared = Object.keys(required).filter((name) => !missingFromPackageJson.includes(name));
+  const notInstalled = findUnresolvedPackageInstalls(cwd, declared);
+  return {
+    required,
+    missingFromPackageJson,
+    outdatedInPackageJson,
+    incompatibleInstalled,
+    notInstalled,
+  };
+}
+
+export function formatZhinStackFixCommand(packages: string[], required: Record<string, string>): string {
+  if (packages.length === 0) return 'pnpm install';
+  const specs = packages.map((name) => `${name}@${required[name] ?? 'latest'}`);
+  return `pnpm add ${specs.join(' ')}`;
+}