@zhin.js/scaffold-wizard 0.1.5 → 0.1.7

package/lib/zhin-stack-deps.js

@@ -0,0 +1,202 @@
+import { createRequire } from 'node:module';
+import fs from 'fs-extra';
+import path from 'node:path';
+import { DATABASE_PACKAGES } from './types.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',
+};
+const HOST_CONSOLE_PLUGINS = new Set([
+    '@zhin.js/host-router',
+    '@zhin.js/host-api',
+]);
+function parseMajor(versionSpec) {
+    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, name) {
+    return pkg.dependencies?.[name] ?? pkg.devDependencies?.[name];
+}
+function readInstalledMajor(cwd, packageName) {
+    const pkgJson = path.join(cwd, 'package.json');
+    if (!fs.existsSync(pkgJson))
+        return undefined;
+    try {
+        const req = createRequire(pkgJson);
+        const installed = req(`${packageName}/package.json`);
+        return parseMajor(installed.version);
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolvePackageMajor(cwd, pkg, packageName) {
+    return readInstalledMajor(cwd, packageName) ?? parseMajor(getDeclaredPackageVersion(pkg, packageName));
+}
+function resolveStackVersion(packageName) {
+    return ZHIN_STACK_VERSIONS[packageName] ?? 'latest';
+}
+function collectZhinPluginsFromConfig(config) {
+    const plugins = Array.isArray(config.plugins)
+        ? config.plugins.filter((p) => 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) {
+    return {
+        onlyBuiltDependencies: ['esbuild'],
+    };
+}
+/** create-zhin-app 默认 bot 骨架依赖（不含适配器 / AI / 数据库驱动） */
+export function getCreateBotBaseDependencies() {
+    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) {
+    const deps = {
+        '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.dialect ?? '');
+        const driver = DATABASE_PACKAGES[dialect];
+        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']) {
+            deps[pkg] = ZHIN_STACK_VERSIONS[pkg];
+        }
+    }
+    return deps;
+}
+export function findOutdatedZhinStackInPackageJson(pkg, required) {
+    const outdated = [];
+    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, pkg, config) {
+    const issues = [];
+    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 function packagesNeedingZhinStackFix(diagnosis) {
+    const names = new Set([
+        ...diagnosis.missingFromPackageJson,
+        ...diagnosis.outdatedInPackageJson,
+    ]);
+    for (const issue of diagnosis.incompatibleInstalled) {
+        names.add(issue.package);
+    }
+    return [...names];
+}
+export function diagnoseZhinStackDependencies(cwd, config, pkg) {
+    const required = getRequiredZhinDependenciesForConfig(config);
+    const packageJsonPath = path.join(cwd, 'package.json');
+    const packageJson = pkg ?? (fs.existsSync(packageJsonPath)
+        ? fs.readJsonSync(packageJsonPath)
+        : {});
+    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, required) {
+    if (packages.length === 0)
+        return 'pnpm install';
+    const specs = packages.map((name) => `${name}@${required[name] ?? 'latest'}`);
+    return `pnpm add ${specs.join(' ')}`;
+}
+//# sourceMappingURL=zhin-stack-deps.js.map

package/lib/zhin-stack-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zhin-stack-deps.js","sourceRoot":"","sources":["../src/zhin-stack-deps.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/scaffold-wizard",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Shared interactive scaffold wizard for create-zhin-app and @zhin.js/cli",
   "type": "module",
   "main": "./lib/index.js",
@@ -18,13 +18,15 @@
   ],
   "dependencies": {
     "chalk": "^5.6.2",
-    "fs-extra": "^11.3.5",
-    "inquirer": "^14.0.2"
+    "fs-extra": "^11.3.6",
+    "inquirer": "^14.0.2",
+    "smol-toml": "^1.7.0",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",
-    "@types/inquirer": "^9.0.7",
-    "@types/node": "^25.9.2",
+    "@types/inquirer": "^9.0.10",
+    "@types/node": "^26.1.0",
     "typescript": "^6.0.3"
   },
   "engines": {

package/src/adapter.ts

@@ -10,6 +10,7 @@ import {
   configureSlackEndpoint,
   configureTelegramEndpoint,
 } from './adapter-configurers.js';
+import { ZHIN_STACK_VERSIONS } from './zhin-stack-deps.js';
 
 export interface AdapterSetupResult {
   packages: string[];
@@ -519,7 +520,7 @@ export function getAdapterDependencies(result: AdapterSetupResult): Record<strin
           deps[name] = version;
         }
       } else {
-        deps[pkg] = 'latest';
+        deps[pkg] = ZHIN_STACK_VERSIONS[pkg as keyof typeof ZHIN_STACK_VERSIONS] ?? 'latest';
       }
     } else {
       deps[pkg] = 'latest';

package/src/ai.ts

@@ -3,8 +3,16 @@ import chalk from 'chalk';
 
 export interface AISetupConfig {
   enabled: boolean;
+  agentProvider?: string;
+  /** @deprecated Use agentProvider. Kept for one compatibility cycle. */
   defaultProvider?: string;
-  providers?: Record<string, { apiKey?: string; host?: string; models?: string[]; baseUrl?: string }>;
+  providers?: Record<string, {
+    sdk?: string;
+    apiKey?: string;
+    host?: string;
+    models?: string[];
+    baseUrl?: string;
+  }>;
   sessions?: { useDatabase: boolean; maxHistory: number; expireMs: number };
   context?: { enabled: boolean; maxRecentMessages: number; summaryThreshold: number; keepAfterSummary: number };
   agent?: {
@@ -76,7 +84,7 @@ const PROVIDERS = [
   },
 ] as const;
 
-function providerSdkFor(name: string): string {
+export function providerSdkFor(name: string): string {
   switch (name) {
     case 'anthropic':
       return 'anthropic';
@@ -100,6 +108,60 @@ function defaultModelForProvider(driver: string): string {
   return entry?.defaultModel ?? '';
 }
 
+export function resolveAISetupAgentProvider(config: Pick<AISetupConfig, 'agentProvider' | 'defaultProvider' | 'providers'>): string {
+  return config.agentProvider
+    ?? config.defaultProvider
+    ?? Object.keys(config.providers ?? {})[0]
+    ?? 'openai';
+}
+
+function resolveAISetupAgentModel(config: AISetupConfig, providerAlias: string): string {
+  return config.providers?.[providerAlias]?.models?.[0]
+    ?? defaultModelForProvider(providerAlias)
+    ?? '';
+}
+
+export function materializeAIConfig(config: AISetupConfig): Record<string, unknown> {
+  const providerAlias = resolveAISetupAgentProvider(config);
+  const providers: Record<string, Record<string, unknown>> = {};
+
+  for (const [name, providerConfig] of Object.entries(config.providers ?? {})) {
+    const clean: Record<string, unknown> = {
+      sdk: providerConfig.sdk ?? providerSdkFor(name),
+    };
+    if (providerConfig.apiKey) clean.apiKey = providerConfig.apiKey;
+    if (providerConfig.host) clean.host = providerConfig.host;
+    if (providerConfig.models) clean.models = providerConfig.models;
+    if (providerConfig.baseUrl) clean.baseUrl = providerConfig.baseUrl;
+    providers[name] = clean;
+  }
+
+  if (Object.keys(providers).length === 0) {
+    providers[providerAlias] = { sdk: providerSdkFor(providerAlias) };
+  }
+
+  const agent: Record<string, unknown> = {
+    provider: providerAlias,
+  };
+  const model = resolveAISetupAgentModel(config, providerAlias);
+  if (model) agent.model = model;
+
+  const obj: Record<string, unknown> = {
+    providers,
+    agents: {
+      zhin: agent,
+    },
+    sessions: config.sessions,
+    context: config.context,
+    agent: config.agent,
+    trigger: config.trigger ? { ...config.trigger } : undefined,
+    memoryMcp: config.memoryMcp ?? false,
+    mcpServers: config.mcpServers ?? [],
+  };
+
+  return Object.fromEntries(Object.entries(obj).filter(([, value]) => value !== undefined));
+}
+
 export const RECOMMENDED_AI_DEFAULTS = {
   sessions: {
     useDatabase: true,
@@ -292,7 +354,7 @@ export async function configureAI(): Promise<AISetupConfig> {
 
   return {
     enabled: true,
-    defaultProvider: provider,
+    agentProvider: provider,
     providers: {
       [provider]: providerConfig,
     },
@@ -340,7 +402,7 @@ export function generateAIEnvVars(config: AISetupConfig): string {
 export function generateAIConfigYaml(config: AISetupConfig): string {
   if (!config.enabled) return '';
 
-  const providerAlias = config.defaultProvider || Object.keys(config.providers ?? {})[0] || 'openai';
+  const providerAlias = resolveAISetupAgentProvider(config);
 
   const lines: string[] = [
     '',
@@ -351,7 +413,7 @@ export function generateAIConfigYaml(config: AISetupConfig): string {
   if (config.providers) {
     for (const [name, providerConfig] of Object.entries(config.providers)) {
       lines.push(`    ${name}:`);
-      lines.push(`      sdk: ${providerSdkFor(name)}`);
+      lines.push(`      sdk: ${providerConfig.sdk ?? providerSdkFor(name)}`);
       if (providerConfig.apiKey) {
         lines.push(`      apiKey: ${providerConfig.apiKey}`);
       }
@@ -370,9 +432,7 @@ export function generateAIConfigYaml(config: AISetupConfig): string {
     }
   }
 
-  const zhinModel = defaultModelForProvider(providerAlias)
-    || config.providers?.[providerAlias]?.models?.[0]
-    || '';
+  const zhinModel = resolveAISetupAgentModel(config, providerAlias);
   lines.push('  agents:');
   lines.push('    zhin:');
   lines.push(`      provider: ${providerAlias}`);
@@ -436,13 +496,13 @@ export function generateAIConfigToml(config: AISetupConfig): string {
   const lines: string[] = [
     '',
     '[ai]',
-    `defaultProvider = "${config.defaultProvider}"`,
     `memoryMcp = ${config.memoryMcp ?? false}`,
   ];
 
   if (config.providers) {
     for (const [name, providerConfig] of Object.entries(config.providers)) {
       lines.push('', `[ai.providers.${name}]`);
+      lines.push(`sdk = "${providerConfig.sdk ?? providerSdkFor(name)}"`);
       if (providerConfig.apiKey) lines.push(`apiKey = "${providerConfig.apiKey}"`);
       if (providerConfig.host) lines.push(`host = "${providerConfig.host}"`);
       if (providerConfig.models?.length) {
@@ -452,6 +512,12 @@ export function generateAIConfigToml(config: AISetupConfig): string {
     }
   }
 
+  const providerAlias = resolveAISetupAgentProvider(config);
+  lines.push('', '[ai.agents.zhin]');
+  lines.push(`provider = "${providerAlias}"`);
+  const zhinModel = resolveAISetupAgentModel(config, providerAlias);
+  if (zhinModel) lines.push(`model = "${zhinModel}"`);
+
   if (config.trigger) {
     lines.push('', '[ai.trigger]');
     lines.push(`respondToAt = ${config.trigger.respondToAt}`);
@@ -493,29 +559,7 @@ export function generateAIConfigToml(config: AISetupConfig): string {
 export function generateAIConfigJSON(config: AISetupConfig): string {
   if (!config.enabled) return '';
 
-  const obj: any = {
-    defaultProvider: config.defaultProvider,
-    providers: {},
-    sessions: config.sessions,
-    context: config.context,
-    agent: config.agent,
-    trigger: config.trigger ? {
-      ...config.trigger,
-    } : undefined,
-    memoryMcp: config.memoryMcp ?? false,
-    mcpServers: config.mcpServers ?? [],
-  };
-
-  if (config.providers) {
-    for (const [name, providerConfig] of Object.entries(config.providers)) {
-      const clean: any = {};
-      if (providerConfig.apiKey) clean.apiKey = providerConfig.apiKey;
-      if (providerConfig.host) clean.host = providerConfig.host;
-      if (providerConfig.models) clean.models = providerConfig.models;
-      if (providerConfig.baseUrl) clean.baseUrl = providerConfig.baseUrl;
-      obj.providers[name] = clean;
-    }
-  }
+  const obj = materializeAIConfig(config);
 
   return `"ai": ${JSON.stringify(obj, null, 4).replace(/^/gm, '  ').trimStart()}`;
 }

package/src/apply.ts

@@ -2,7 +2,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import type { AdapterSetupResult, AISetupConfig, DatabaseConfig, InitOptions } from './types.js';
 import { generateAdapterEnvVars, getAdapterDependencies } from './adapter.js';
-import { generateAIEnvVars } from './ai.js';
+import { generateAIEnvVars, materializeAIConfig } from './ai.js';
 import { ensureDatabaseForAdapters, ensureDatabaseForAI, getAIDependencies } from './project-deps.js';
 
 /** Host 插件（Webhook / Console 必需） */
@@ -36,7 +36,7 @@ export function applyAdaptersToConfig(config: Record<string, unknown>, result: A
 }
 
 export function applyAIToConfig(config: Record<string, unknown>, ai: AISetupConfig): void {
-  config.ai = ai;
+  config.ai = materializeAIConfig(ai);
 }
 
 export async function appendWizardEnvVars(

package/src/index.ts

@@ -32,6 +32,7 @@ export {
 export { configureDatabaseOptions } from './database.js';
 
 export {
+  AI_STACK_VERSIONS,
   MCP_SDK_VERSION,
   getAIDependencies,
   listAIDependencyNames,
@@ -41,9 +42,61 @@ export {
   getRequiredAIDependenciesForConfig,
   diagnoseAIDependencies,
   formatAIDependencyFixCommand,
+  packagesNeedingAiStackFix,
+  findOutdatedAiStackInPackageJson,
+  findInstalledAiStackIncompatibilities,
   ensureDatabaseForAI,
   ensureDatabaseForAdapters,
 } from './project-deps.js';
+export type { AiStackIncompatibility } from './project-deps.js';
+
+export {
+  ZHIN_STACK_VERSIONS,
+  DEFAULT_CREATE_BOT_HTTP_PORT,
+  CREATE_BOT_NPMRC,
+  getCreateBotBaseDependencies,
+  getCreateBotPnpmConfig,
+  getRequiredZhinDependenciesForConfig,
+  diagnoseZhinStackDependencies,
+  formatZhinStackFixCommand,
+  packagesNeedingZhinStackFix,
+  findOutdatedZhinStackInPackageJson,
+  findInstalledZhinStackIncompatibilities,
+} from './zhin-stack-deps.js';
+export type { ZhinStackDiagnosis, ZhinStackIncompatibility } from './zhin-stack-deps.js';
+
+export {
+  SPEECH_PACKAGE,
+  HTML_RENDERER_PACKAGE,
+  ADAPTERS_PREFER_HTML_IMAGE,
+  diagnoseOptionalPeers,
+  formatOptionalPeerFixCommand,
+  getOptionalPeerDependencies,
+} from './optional-peers.js';
+export type { OptionalPeerDiagnosis, OptionalPeersDiagnosis } from './optional-peers.js';
+
+export {
+  diagnoseUpgradeToL4,
+  getUpgradeToL4Dependencies,
+} from './upgrade-l4.js';
+export type { UpgradeToL4Diagnosis } from './upgrade-l4.js';
+
+export {
+  loadProjectConfig,
+  createProjectConfigPlan,
+  renderProjectConfigPatch,
+  applyProjectConfigPlan,
+  migrateAiLegacyConfig,
+  diagnoseConsoleConfig,
+  applyConsoleConfigFixes,
+} from './project-config-plan.js';
+export type {
+  LoadedProjectConfig,
+  ProjectConfigFormat,
+  ProjectConfigPlan,
+  ProjectConfigPlanOptions,
+  ConsoleConfigDiagnosis,
+} from './project-config-plan.js';
 
 export {
   CONSOLE_HOST_PLUGINS,

package/src/optional-peers.ts

@@ -0,0 +1,149 @@
+import fs from 'fs-extra';
+import path from 'node:path';
+import type { PackageJsonLike } from './project-deps.js';
+import {
+  findMissingPackageDependencies,
+  findUnresolvedPackageInstalls,
+} from './project-deps.js';
+
+export const SPEECH_PACKAGE = '@zhin.js/speech';
+export const HTML_RENDERER_PACKAGE = '@zhin.js/html-renderer';
+
+/** 默认 html/markdown policy 为 image 的 adapter context 名 */
+export const ADAPTERS_PREFER_HTML_IMAGE = new Set([
+  'kook',
+  'qq',
+  'weixin-ilink',
+  'email',
+]);
+
+export interface OptionalPeerDiagnosis {
+  packageName: string;
+  required: boolean;
+  reason: string;
+  missingFromPackageJson: string[];
+  notInstalled: string[];
+}
+
+export interface OptionalPeersDiagnosis {
+  speech?: OptionalPeerDiagnosis;
+  htmlRenderer?: OptionalPeerDiagnosis;
+}
+
+function readSpeechStrategy(config: Record<string, unknown>): string | undefined {
+  const ai = config.ai;
+  if (!ai || typeof ai !== 'object' || Array.isArray(ai)) return undefined;
+  const multimodal = (ai as Record<string, unknown>).multimodal;
+  if (!multimodal || typeof multimodal !== 'object' || Array.isArray(multimodal)) return undefined;
+  const audio = (multimodal as Record<string, unknown>).audio;
+  if (!audio || typeof audio !== 'object' || Array.isArray(audio)) return undefined;
+  const strategy = (audio as Record<string, unknown>).strategy;
+  return strategy != null ? String(strategy) : undefined;
+}
+
+function configUsesHtmlImageAdapter(config: Record<string, unknown>): boolean {
+  const plugins = Array.isArray(config.plugins)
+    ? config.plugins.filter((p): p is string => typeof p === 'string')
+    : [];
+  for (const plugin of plugins) {
+    for (const ctx of ADAPTERS_PREFER_HTML_IMAGE) {
+      if (plugin.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;
+    const context = (ep as Record<string, unknown>).context;
+    if (typeof context === 'string' && ADAPTERS_PREFER_HTML_IMAGE.has(context)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function diagnosePeer(
+  cwd: string,
+  pkg: PackageJsonLike,
+  packageName: string,
+  required: boolean,
+  reason: string,
+): OptionalPeerDiagnosis | undefined {
+  if (!required) return undefined;
+  const requiredDeps = {
+    [packageName]: 'latest',
+  };
+  const missingFromPackageJson = findMissingPackageDependencies(pkg, requiredDeps);
+  const declared = [packageName].filter((n) => !missingFromPackageJson.includes(n));
+  const notInstalled = findUnresolvedPackageInstalls(cwd, declared);
+  return {
+    packageName,
+    required: true,
+    reason,
+    missingFromPackageJson,
+    notInstalled,
+  };
+}
+
+/** 按 zhin.config 推断 optional peer（speech / html-renderer）是否应安装 */
+export function diagnoseOptionalPeers(
+  cwd: string,
+  config: Record<string, unknown>,
+  pkg?: PackageJsonLike,
+): OptionalPeersDiagnosis {
+  const packageJsonPath = path.join(cwd, 'package.json');
+  const packageJson = pkg ?? (fs.existsSync(packageJsonPath)
+    ? fs.readJsonSync(packageJsonPath) as PackageJsonLike
+    : {});
+
+  const speechRequired =
+    config.speech != null && typeof config.speech === 'object'
+    || readSpeechStrategy(config) === 'transcribe';
+
+  const htmlRendererRequired =
+    config.htmlRenderer != null && typeof config.htmlRenderer === 'object'
+    || configUsesHtmlImageAdapter(config);
+
+  const speech = diagnosePeer(
+    cwd,
+    packageJson,
+    SPEECH_PACKAGE,
+    speechRequired,
+    speechRequired
+      ? (readSpeechStrategy(config) === 'transcribe'
+        ? 'ai.multimodal.audio.strategy 为 transcribe'
+        : '已配置 speech:')
+      : '',
+  );
+
+  const htmlRenderer = diagnosePeer(
+    cwd,
+    packageJson,
+    HTML_RENDERER_PACKAGE,
+    htmlRendererRequired,
+    htmlRendererRequired
+      ? (config.htmlRenderer != null
+        ? '已配置 htmlRenderer:'
+        : 'adapter 出站 policy 使用 html/markdown→image')
+      : '',
+  );
+
+  return { speech, htmlRenderer };
+}
+
+export function formatOptionalPeerFixCommand(diagnosis: OptionalPeerDiagnosis): string {
+  const missing = [
+    ...diagnosis.missingFromPackageJson,
+    ...diagnosis.notInstalled.filter((n) => !diagnosis.missingFromPackageJson.includes(n)),
+  ];
+  const unique = [...new Set(missing)];
+  if (unique.length === 0) return 'pnpm install';
+  return `pnpm add ${unique.map((n) => `${n}@latest`).join(' ')}`;
+}
+
+export function getOptionalPeerDependencies(config: Record<string, unknown>): Record<string, string> {
+  const peers = diagnoseOptionalPeers(process.cwd(), config);
+  const deps: Record<string, string> = {};
+  if (peers.speech?.required) deps[SPEECH_PACKAGE] = 'latest';
+  if (peers.htmlRenderer?.required) deps[HTML_RENDERER_PACKAGE] = 'latest';
+  return deps;
+}