@zhin.js/scaffold-wizard 0.1.5 → 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';
 
-/** 与 monorepo 中 agent / test-bot 对齐的 MCP SDK 版本 */
-export const MCP_SDK_VERSION = '^1.29.0';
+/**
+ * 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 = '^4.0.0';
-const ZOD_VERSION = '^4.0.0';
-const VERCEL_AI_VERSION = '^6.0.0';
+/** @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: '^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' },
+  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

@@ -0,0 +1,103 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import type { PackageJsonLike } from './project-deps.js';
+import {
+  diagnoseAIDependencies,
+  formatAIDependencyFixCommand,
+  getRequiredAIDependenciesForConfig,
+  isAiEnabledInConfig,
+  findMissingPackageDependencies,
+  findUnresolvedPackageInstalls,
+  packagesNeedingAiStackFix,
+} from './project-deps.js';
+import { diagnoseOptionalPeers, formatOptionalPeerFixCommand, getOptionalPeerDependencies } from './optional-peers.js';
+
+export interface UpgradeToL4Diagnosis {
+  ai: ReturnType<typeof diagnoseAIDependencies>;
+  optionalPeers: ReturnType<typeof diagnoseOptionalPeers>;
+  missingAiDeps: string[];
+  missingOptionalPeers: string[];
+  fixCommand: string;
+  configSnippets: string[];
+}
+
+const L4_CONFIG_SNIPPETS = [
+  '# --- L4 可选多模态（取消注释并安装 optional peer）---',
+  '# ai:',
+  '#   multimodal:',
+  '#     audio:',
+  '#       strategy: transcribe   # 需 @zhin.js/speech',
+  '# speech:',
+  '#   stt:',
+  '#     provider: ollama',
+  '#     model: whisper',
+  '#   tts:',
+  '#     provider: edge',
+  '# htmlRenderer:',
+  '#   width: 540',
+];
+
+/** minimal-bot → full-bot / L4 升级诊断 */
+export function diagnoseUpgradeToL4(
+  cwd: string,
+  config: Record<string, unknown>,
+  pkg?: PackageJsonLike,
+): UpgradeToL4Diagnosis {
+  const packageJsonPath = path.join(cwd, 'package.json');
+  const packageJson = pkg ?? (fs.existsSync(packageJsonPath)
+    ? fs.readJsonSync(packageJsonPath) as PackageJsonLike
+    : {});
+
+  const aiEnabled = isAiEnabledInConfig(config);
+  const ai = aiEnabled ? diagnoseAIDependencies(cwd, config, packageJson) : null;
+  const optionalPeers = diagnoseOptionalPeers(cwd, config, packageJson);
+
+  const missingAiDeps = ai
+    ? [...new Set([...packagesNeedingAiStackFix(ai), ...ai.notInstalled])]
+    : [...Object.keys(getRequiredAIDependenciesForConfig({ ai: { enabled: true } }))];
+
+  if (!aiEnabled) {
+    const required = getRequiredAIDependenciesForConfig({ ai: { enabled: true } });
+    const fromPkg = findMissingPackageDependencies(packageJson, required);
+    const declared = Object.keys(required).filter((n) => !fromPkg.includes(n));
+    const notInstalled = findUnresolvedPackageInstalls(cwd, declared);
+    missingAiDeps.push(...fromPkg, ...notInstalled);
+  }
+
+  const missingOptionalPeers: string[] = [];
+  for (const peer of [optionalPeers.speech, optionalPeers.htmlRenderer]) {
+    if (!peer?.required) continue;
+    missingOptionalPeers.push(
+      ...peer.missingFromPackageJson,
+      ...peer.notInstalled.filter((n) => !peer.missingFromPackageJson.includes(n)),
+    );
+  }
+
+  const fixParts: string[] = [];
+  if (!aiEnabled || missingAiDeps.length > 0) {
+    const required = ai?.required ?? getRequiredAIDependenciesForConfig({ ai: { enabled: true } });
+    fixParts.push(formatAIDependencyFixCommand(
+      [...new Set(missingAiDeps)],
+      required,
+    ));
+  }
+  for (const peer of [optionalPeers.speech, optionalPeers.htmlRenderer]) {
+    if (peer && (peer.missingFromPackageJson.length > 0 || peer.notInstalled.length > 0)) {
+      fixParts.push(formatOptionalPeerFixCommand(peer));
+    }
+  }
+
+  return {
+    ai,
+    optionalPeers,
+    missingAiDeps: [...new Set(missingAiDeps)],
+    missingOptionalPeers: [...new Set(missingOptionalPeers)],
+    fixCommand: fixParts.join(' && '),
+    configSnippets: L4_CONFIG_SNIPPETS,
+  };
+}
+
+export function getUpgradeToL4Dependencies(config: Record<string, unknown>): Record<string, string> {
+  const deps = getRequiredAIDependenciesForConfig({ ai: { enabled: true } });
+  return { ...deps, ...getOptionalPeerDependencies(config) };
+}