@zhin.js/scaffold-wizard 1.1.5 → 1.1.7

package/src/apply.ts

@@ -2,9 +2,9 @@ import fs from 'fs-extra';
 import path from 'path';
 import yaml from 'yaml';
 import { readPluginConfigurationMap } from '@zhin.js/plugin-runtime';
+import { readApplicationPluginDeclaration } from '@zhin.js/runtime';
 import type { AdapterSetupResult, AISetupConfig, DatabaseConfig, InitOptions } from './types.js';
 import {
-  collectAdapterPluginConfigs,
   collectAdapterPluginManifest,
   generateAdapterEnvVars,
   getAdapterDependencies,
@@ -14,6 +14,7 @@ import { generateDatabaseEnvVars, mergeEnvText } from './env.js';
 import { getDatabaseDialectDefinition } from './database-definitions.js';
 import { ensureDatabaseForAdapters, ensureDatabaseForAI, getAIDependencies } from './project-deps.js';
 import { DEFAULT_CREATE_BOT_HTTP_PORT, ZHIN_STACK_VERSIONS } from './zhin-stack-deps.js';
+import { withScaffoldVersionRanges } from './stack-version-ranges.js';
 
 export function applyDatabaseToConfig(config: Record<string, unknown>, database: DatabaseConfig): void {
   // 物化为可落盘对象：非 SQLite 连接参数引用 .env（${VAR}），明文密码不进配置文件
@@ -28,15 +29,34 @@ export function clonePluginConfigurationMap(
 }
 
 export function applyAdaptersToConfig(config: Record<string, unknown>, result: AdapterSetupResult): void {
-  const plugins = clonePluginConfigurationMap(config);
   for (const instance of result.instances) {
-    plugins[instance.instanceKey] = mergeAdapterInstanceConfig(
-      instance.instanceKey,
-      plugins[instance.instanceKey],
-      instance.config,
-    );
+    const plugins = clonePluginConfigurationMap(config);
+    setPluginInstanceConfig(config, instance, mergeAdapterInstanceConfig(
+      instance.instanceKey, plugins[instance.instanceKey], instance.config,
+    ));
   }
-  config.plugins = plugins;
+  if (result.instances.length === 0) clonePluginConfigurationMap(config);
+}
+
+/** Writes one instance using the document's explicitly selected protocol. */
+export function setPluginInstanceConfig(
+  config: Record<string, unknown>,
+  instance: { instanceKey: string; package: string },
+  value: Record<string, unknown>,
+): void {
+  const declaration = readApplicationPluginDeclaration(config);
+  const existing = declaration.instances.find(item => item.instanceKey === instance.instanceKey);
+  if (existing && existing.package !== instance.package) {
+    throw new Error(`Plugin instance ${instance.instanceKey} already belongs to ${existing.package}`);
+  }
+  const next = {
+    ...config,
+    plugins: { ...(config.plugins as Record<string, string> | undefined), [instance.instanceKey]: instance.package },
+    [instance.instanceKey]: value,
+  };
+  readApplicationPluginDeclaration(next);
+  config.plugins = next.plugins;
+  config[instance.instanceKey] = value;
 }
 
 function endpointId(endpoint: unknown): string | undefined {
@@ -89,35 +109,6 @@ export function applyAIToConfig(config: Record<string, unknown>, ai: AISetupConf
   config.ai = materializeAIConfig(ai);
 }
 
-/** 把 zhin.plugins 清单条目合并进项目 package.json（zhin setup 路径） */
-export async function mergePluginManifestIntoPackageJson(
-  projectDir: string,
-  entries: Array<{ package: string; instanceKey: 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 manifest: Array<{ package: string; instanceKey: string }> = Array.isArray(zhin.plugins)
-    ? [...zhin.plugins]
-    : [];
-  let changed = false;
-  for (const entry of entries) {
-    if (manifest.some((item) => item?.instanceKey === entry.instanceKey)) continue;
-    manifest.push({ package: entry.package, instanceKey: entry.instanceKey });
-    changed = true;
-  }
-  if (!changed && pkg.zhin) return false;
-  zhin.plugins = manifest;
-  pkg.zhin = zhin;
-  await fs.writeJson(pkgPath, pkg, { spaces: 2 });
-  return true;
-}
-
 export async function appendWizardEnvVars(
   projectDir: string,
   adapters?: AdapterSetupResult,
@@ -135,10 +126,7 @@ export async function appendWizardEnvVars(
     await fs.writeFile(envPath, mergeEnvText(existing, extra));
   }
 
-  // 新 Plugin Runtime 通过 package.json zhin.plugins 清单挂载子插件，与依赖一起落盘
-  if (adapters) {
-    await mergePluginManifestIntoPackageJson(projectDir, collectAdapterPluginManifest(adapters));
-  }
+
 }
 
 export function collectWizardDependencies(
@@ -147,7 +135,7 @@ export function collectWizardDependencies(
   const databaseDriver = options.database
     ? getDatabaseDialectDefinition(options.database.dialect)?.driver
     : undefined;
-  return {
+  return withScaffoldVersionRanges({
     ...(options.adapters ? getAdapterDependencies(options.adapters) : {}),
     ...(databaseDriver ? { [databaseDriver.package]: databaseDriver.version } : {}),
     ...getAIDependencies(options.ai),
@@ -156,7 +144,7 @@ export function collectWizardDependencies(
       '@zhin.js/tool': ZHIN_STACK_VERSIONS['@zhin.js/tool'],
       '@zhin.js/prompt-section': ZHIN_STACK_VERSIONS['@zhin.js/prompt-section'],
     } : {}),
-  };
+  });
 }
 
 /** 向导结果需要合并进 package.json zhin.features 的条目（与 create-zhin 路径对齐） */
@@ -295,11 +283,11 @@ function applyLifeAssistantAiExtras(ai: Record<string, unknown>): Record<string,
 }
 
 /**
- * 构建新 Plugin Runtime 配置文档（顶层 http/database/ai + plugins.<instanceKey>）。
+ * 构建 v2 扁平主配置（plugins 包映射 + 顶层实例业务配置）。
  * 顶层键与 packages/im/runtime/src/config-composer.ts 的 effectiveSchema 对齐。
  */
 export function buildRuntimeConfigDocument(options: InitOptions): Record<string, unknown> {
-  const doc: Record<string, unknown> = {};
+  const doc: Record<string, unknown> = { configVersion: 2, plugins: {} };
 
   if (options.database) {
     doc.database = materializeDatabaseConfig(options.database);
@@ -317,7 +305,7 @@ export function buildRuntimeConfigDocument(options: InitOptions): Record<string,
     doc.ai = options.template === 'life-assistant' ? applyLifeAssistantAiExtras(ai) : ai;
   }
 
-  doc.plugins = options.adapters ? collectAdapterPluginConfigs(options.adapters) : {};
+  if (options.adapters) applyAdaptersToConfig(doc, options.adapters);
 
   return doc;
 }

package/src/database-definitions.ts

@@ -101,7 +101,7 @@ export const DATABASE_DIALECT_DEFINITIONS: readonly DatabaseDialectDefinition[]
     dialect: 'mongodb',
     name: 'MongoDB',
     description: '文档数据库',
-    verifiedServer: 'MongoDB 8',
+    verifiedServer: 'MongoDB 7',
     driver: { package: 'mongodb', version: '^7.5.0' },
     schema: {
       type: 'object',

package/src/decisions.ts

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import fs from 'fs-extra';
 import path from 'node:path';
 import { formatEnvValue, mergeEnvText } from './env.js';
-import { clonePluginConfigurationMap, mergeDependenciesIntoPackageJson, mergePluginManifestIntoPackageJson } from './apply.js';
+import { clonePluginConfigurationMap, mergeDependenciesIntoPackageJson, setPluginInstanceConfig } from './apply.js';
 import { isAiEnabledInConfig } from './project-deps.js';
 
 export const TYPESAFE_DECISION_PACKAGE = '@zhin.js/service-typesafe';
@@ -35,7 +35,7 @@ export async function configureTypeSafeDecisions(config: Readonly<Record<string,
     { type: 'input', name: 'model', message: 'Jev 模型（生产校准后建议固定版本）', default: 'jev-latest', validate: (value: string) => value.trim().length > 0 || '请输入模型名称' },
     { type: 'select', name: 'mode', message: 'Skill / Tool 推荐运行方式', default: 'shadow', choices: [ { name: 'shadow：观察建议，评估后再启用', value: 'shadow' }, { name: 'active：启用推荐，权限仍由 Zhin 校验', value: 'active' } ] },
   ]);
-  const reference = record(record(config.plugins)[answers.instanceKey]).apiKey;
+  const reference = record(clonePluginConfigurationMap(config)[answers.instanceKey]).apiKey;
   const existingVariable = typeof reference === 'string' ? /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(reference)?.[1] : undefined;
   return { ...answers, envVar: existingVariable ?? decisionKeyVariable(answers.instanceKey) };
 }
@@ -55,8 +55,7 @@ export function applyTypeSafeDecisionsToConfig(config: Record<string, unknown>,
   if (!/^[a-z][a-z0-9-]*$/.test(setup.instanceKey) || !setup.model.trim() || !setup.apiKey.trim()) throw new Error('Invalid TypeSafe setup configuration.');
   const plugins = clonePluginConfigurationMap(config);
   const existing = record(plugins[setup.instanceKey]);
-  plugins[setup.instanceKey] = { ...existing, apiKey: '${' + envVariable(setup) + '}', model: setup.model.trim(), timeoutMs: 10000, maxRetries: 2, enabled: true };
-  config.plugins = plugins;
+  setPluginInstanceConfig(config, { instanceKey: setup.instanceKey, package: TYPESAFE_DECISION_PACKAGE }, { ...existing, apiKey: '${' + envVariable(setup) + '}', model: setup.model.trim(), timeoutMs: 10000, maxRetries: 2, enabled: true });
   const ai = record(config.ai);
   const previousDecisions = record(ai.decisions);
   config.ai = { ...ai, decisions: {
@@ -72,13 +71,6 @@ export function applyTypeSafeDecisionsToConfig(config: Record<string, unknown>,
 
 export async function saveTypeSafeSetupDependencies(projectDir: string, setup: TypeSafeSetupConfig): Promise<void> {
   const variable = envVariable(setup);
-  const pkgPath = path.join(projectDir, 'package.json');
-  const pkg = await fs.readJson(pkgPath);
-  const existingManifest = record(pkg.zhin).plugins;
-  if (Array.isArray(existingManifest) && existingManifest.some(entry => record(entry).instanceKey === setup.instanceKey && record(entry).package !== TYPESAFE_DECISION_PACKAGE)) {
-    throw new Error('Decision plugin instance already belongs to another package; choose a different instanceKey.');
-  }
-  await mergePluginManifestIntoPackageJson(projectDir, [{ package: TYPESAFE_DECISION_PACKAGE, instanceKey: setup.instanceKey }]);
   await mergeDependenciesIntoPackageJson(projectDir, { [TYPESAFE_DECISION_PACKAGE]: '^1.0.0' });
   const envPath = path.join(projectDir, '.env');
   const envExists = await fs.pathExists(envPath);
@@ -116,14 +108,14 @@ export function diagnoseDecisionConfig(config: Readonly<Record<string, unknown>>
   // Nested Plugin owners are resolved from the actual runtime graph during activation.
   if (key.includes('/')) return issues;
   const pkg = record(packageJson);
-  const manifest = record(pkg.zhin).plugins;
-  const entries = Array.isArray(manifest) ? manifest.filter(entry => record(entry).instanceKey === key) : [];
-  if (entries.length !== 1) {
-    issues.push('决策插件实例未在 package.json#zhin.plugins 唯一声明。');
+  const declared = record(config.plugins);
+  if (typeof declared[key] !== 'string') {
+    issues.push('决策插件实例未在主配置 plugins 中声明。');
     return issues;
   }
-  if (record(entries[0]).package === TYPESAFE_DECISION_PACKAGE) {
-    const configForProvider = record(record(config.plugins)[key]);
+  if (Array.isArray(config.disable_plugins) && config.disable_plugins.includes(key)) issues.push('绑定的决策插件已停用。');
+  if (declared[key] === TYPESAFE_DECISION_PACKAGE) {
+    const configForProvider = record(config[key]);
     if (configForProvider.enabled === false) issues.push('绑定的 TypeSafe 插件已禁用。');
     if (typeof configForProvider.apiKey !== 'string' || !configForProvider.apiKey.trim()) issues.push('TypeSafe 插件缺少 apiKey 环境变量引用。');
     if (!Object.hasOwn({ ...record(pkg.dependencies), ...record(pkg.devDependencies) }, TYPESAFE_DECISION_PACKAGE)) issues.push('package.json 缺少 @zhin.js/service-typesafe 依赖。');

package/src/index.ts

@@ -70,6 +70,13 @@ export {
 } from './project-deps.js';
 export type { AiStackIncompatibility } from './project-deps.js';
 
+export {
+  FALLBACK_DEPENDENCY_RANGE,
+  scaffoldDependencyRange,
+  withScaffoldVersionRanges,
+} from './stack-version-ranges.js';
+export type { StackVersionRanges } from './stack-version-ranges.js';
+
 export {
   ZHIN_STACK_VERSIONS,
   DEFAULT_CREATE_BOT_HTTP_PORT,
@@ -128,7 +135,6 @@ export {
   collectWizardFeatures,
   mergeDependenciesIntoPackageJson,
   mergeFeaturesIntoPackageJson,
-  mergePluginManifestIntoPackageJson,
   finalizeWizardOptions,
   applyWizardOptionsToConfig,
   clonePluginConfigurationMap,

package/src/project-config-plan.ts

@@ -1,6 +1,9 @@
 import fs from 'fs-extra';
 import path from 'node:path';
 import yaml from 'yaml';
+import { createConfigDocument, readSourcePluginOrder } from '@zhin.js/config-file';
+import { readApplicationPluginDeclaration } from '@zhin.js/runtime';
+import { isDeepStrictEqual } from 'node:util';
 import {
   readPluginConfigurationMap,
   ROOT_CONFIG_FILE_NAMES,
@@ -32,6 +35,8 @@ export interface LoadedProjectConfig {
   format?: ProjectConfigFormat;
   config: Record<string, unknown>;
   writable: boolean;
+  /** Exact preview source: comments and declaration order are concurrency inputs. */
+  source?: string;
   message?: string;
 }
 
@@ -55,6 +60,7 @@ export interface ProjectConfigPlan {
   relativePath?: string;
   format?: ProjectConfigFormat;
   writable: boolean;
+  expectedSource?: string;
   before: Record<string, unknown>;
   after: Record<string, unknown>;
   mutations: string[];
@@ -128,9 +134,10 @@ export function loadProjectConfig(cwd = process.cwd(), configPath?: string): Loa
   }
 
   const content = fs.readFileSync(resolvedPath, 'utf8');
+  readSourcePluginOrder(content, format === 'json' ? 'JSON' : 'YAML');
   const config = parseConfig(content, format);
   try {
-    readPluginConfigurationMap(config, relativePath);
+    readApplicationPluginDeclaration(config, relativePath);
   } catch (error) {
     return {
       status: 'unsupported',
@@ -150,23 +157,25 @@ export function loadProjectConfig(cwd = process.cwd(), configPath?: string): Loa
     relativePath,
     format,
     config,
+    source: content,
     writable: true,
   };
 }
 
 function ensurePlugins(config: Record<string, unknown>, pluginsToAdd: readonly string[], mutations: string[]): void {
-  const plugins = { ...readPluginConfigurationMap(config) };
-  let changed = false;
+  const declaration = readApplicationPluginDeclaration(config);
+  const plugins = { ...(config.plugins as Record<string, string> | undefined) };
   for (const pkg of pluginsToAdd) {
     const instanceKey = packageToInstanceKey(pkg);
-    if (instanceKey in plugins) continue;
-    plugins[instanceKey] = {};
-    mutations.push(`added ${instanceKey} (${pkg}) to plugins`);
-    changed = true;
-  }
-  if (changed || config.plugins === undefined) {
-    config.plugins = plugins;
+    const existing = declaration.instances.find(item => item.instanceKey === instanceKey);
+    if (existing && existing.package !== pkg) throw new Error(`Plugin instance ${instanceKey} already belongs to ${existing.package}`);
+    if (!existing) {
+      plugins[instanceKey] = pkg;
+      mutations.push(`added ${instanceKey} (${pkg}) to plugins`);
+    }
   }
+  config.plugins = plugins;
+  readApplicationPluginDeclaration(config);
 }
 
 function ensureHttp(config: Record<string, unknown>, mutations: string[]): void {
@@ -332,6 +341,7 @@ export function createProjectConfigPlan(options: ProjectConfigPlanOptions): Proj
     relativePath: loaded.relativePath,
     format: loaded.format,
     writable: loaded.writable,
+    expectedSource: 'source' in loaded ? loaded.source : (loaded.configPath && fs.existsSync(loaded.configPath) ? fs.readFileSync(loaded.configPath, 'utf8') : undefined),
     before,
     after,
     mutations,
@@ -354,7 +364,25 @@ export function renderProjectConfigPatch(plan: ProjectConfigPlan): string {
 export async function applyProjectConfigPlan(plan: ProjectConfigPlan): Promise<boolean> {
   if (!plan.changed) return false;
   if (!plan.writable || !plan.configPath || !plan.format) return false;
-  await fs.writeFile(plan.configPath, serializeConfig(plan.after, plan.format));
+  const document = createConfigDocument(plan.configPath);
+  const snapshot = await document.readSource();
+  if ((plan.expectedSource !== undefined && snapshot.source !== plan.expectedSource) || !isDeepStrictEqual(snapshot.document, plan.before)) throw new Error('配置已在预览后发生变更，请重新生成配置计划。');
+  const keys = new Set([...Object.keys(plan.before), ...Object.keys(plan.after)]);
+  const patches = [...keys].filter(key => !isDeepStrictEqual(plan.before[key], plan.after[key])).flatMap(key => {
+    if (key === 'plugins') {
+      const before = plan.before.plugins as Record<string, string> | undefined;
+      const after = plan.after.plugins as Record<string, string> | undefined;
+      return [...new Set([...Object.keys(before ?? {}), ...Object.keys(after ?? {})])]
+        .filter(alias => before?.[alias] !== after?.[alias])
+        .map(alias => Object.hasOwn(after ?? {}, alias)
+          ? { op: 'set' as const, path: ['plugins', alias], value: after![alias] }
+          : { op: 'remove' as const, path: ['plugins', alias] });
+    }
+    return [Object.hasOwn(plan.after, key)
+      ? { op: 'set' as const, path: [key], value: plan.after[key] }
+      : { op: 'remove' as const, path: [key] }];
+  });
+  await (await document.prepare(snapshot, patches)).commit();
   return true;
 }
 

package/src/project-deps.ts

@@ -5,7 +5,9 @@ import type { AISetupConfig } from './ai.js';
 import type { InitOptions } from './types.js';
 
 /**
- * User project dependency policy: scaffolded dependencies intentionally float to latest.
+ * Diagnostic baseline for the AI stack (any declared version is accepted).
+ * Scaffolds write derived ranges instead of `latest`: `withScaffoldVersionRanges()` uses the
+ * `@zhin.js/agent` release version and the third-party ranges Zhin declares as peers.
  */
 export const AI_STACK_VERSIONS = {
   '@zhin.js/agent': 'latest',

package/src/stack-version-ranges.ts

@@ -0,0 +1,160 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parse as parseYaml } from 'yaml';
+
+/**
+ * Version ranges that scaffolds write into new bot projects instead of `latest`.
+ *
+ * They are derived from the real package versions of the release that ships this package:
+ * - published package: `prepack` writes `lib/stack-version-ranges.json` from the monorepo,
+ *   so the ranges match the versions released together with it;
+ * - inside the zhin monorepo (source / tests / local builds): read live from the workspace.
+ * Anything unknown keeps the `latest` fallback, so a scaffold never writes an invalid range.
+ */
+
+/** File written next to the compiled module at pack time. */
+export const STACK_VERSION_RANGES_FILE = 'stack-version-ranges.json';
+
+/** Written when no derived range is known for a package. */
+export const FALLBACK_DEPENDENCY_RANGE = 'latest';
+
+/** Zhin packages whose peerDependencies define the supported third-party AI stack. */
+const THIRD_PARTY_RANGE_SOURCES = ['@zhin.js/ai', '@zhin.js/agent'] as const;
+
+export interface StackVersionRanges {
+  readonly [packageName: string]: string;
+}
+
+interface WorkspaceManifest {
+  readonly name?: string;
+  readonly version?: string;
+  readonly private?: boolean;
+  readonly peerDependencies?: Record<string, string>;
+}
+
+function isZhinPackageName(name: string): boolean {
+  return name === 'zhin.js' || name.startsWith('@zhin.js/');
+}
+
+/** `1.2.3-beta.1` → `^1.2.3-beta.1`; anything that is not a version yields `undefined`. */
+export function caretRangeFromVersion(version: string | undefined): string | undefined {
+  if (typeof version !== 'string') return undefined;
+  const match = /^(\d+)\.(\d+)\.(\d+)(-[0-9A-Za-z.-]+)?$/u.exec(version.trim());
+  if (!match) return undefined;
+  return `^${match[0]}`;
+}
+
+function readManifest(directory: string): WorkspaceManifest | undefined {
+  const manifestPath = path.join(directory, 'package.json');
+  if (!fs.existsSync(manifestPath)) return undefined;
+  return JSON.parse(fs.readFileSync(manifestPath, 'utf8')) as WorkspaceManifest;
+}
+
+function workspacePackageDirectories(workspaceRoot: string): string[] {
+  const workspaceFile = path.join(workspaceRoot, 'pnpm-workspace.yaml');
+  const workspace = parseYaml(fs.readFileSync(workspaceFile, 'utf8')) as { packages?: unknown };
+  const patterns = Array.isArray(workspace.packages)
+    ? workspace.packages.filter((pattern): pattern is string => typeof pattern === 'string')
+    : [];
+  const directories: string[] = [];
+  for (const pattern of patterns) {
+    if (!pattern.endsWith('/*')) {
+      directories.push(path.join(workspaceRoot, pattern));
+      continue;
+    }
+    const parent = path.join(workspaceRoot, pattern.slice(0, -2));
+    if (!fs.existsSync(parent)) continue;
+    for (const entry of fs.readdirSync(parent, { withFileTypes: true })) {
+      if (entry.isDirectory()) directories.push(path.join(parent, entry.name));
+    }
+  }
+  return directories;
+}
+
+/**
+ * Collect ranges from a zhin monorepo checkout: `^<version>` for every published Zhin package,
+ * plus the third-party AI ranges Zhin itself declares as peers.
+ */
+export function collectStackVersionRanges(workspaceRoot: string): StackVersionRanges {
+  const ranges: Record<string, string> = {};
+  const manifestsByName = new Map<string, WorkspaceManifest>();
+  for (const directory of workspacePackageDirectories(workspaceRoot)) {
+    const manifest = readManifest(directory);
+    if (!manifest?.name) continue;
+    manifestsByName.set(manifest.name, manifest);
+    if (manifest.private === true) continue;
+    if (!isZhinPackageName(manifest.name)) continue;
+    const range = caretRangeFromVersion(manifest.version);
+    if (range) ranges[manifest.name] = range;
+  }
+  for (const sourceName of THIRD_PARTY_RANGE_SOURCES) {
+    const peers = manifestsByName.get(sourceName)?.peerDependencies ?? {};
+    for (const [peerName, peerRange] of Object.entries(peers)) {
+      if (isZhinPackageName(peerName)) continue;
+      if (peerRange.startsWith('workspace:')) continue;
+      ranges[peerName] ??= peerRange;
+    }
+  }
+  const sortedEntries = Object.entries(ranges).sort(([left], [right]) => left.localeCompare(right));
+  return Object.freeze(Object.fromEntries(sortedEntries));
+}
+
+/** Nearest ancestor that is the zhin monorepo root, if this module runs from a checkout. */
+export function findZhinWorkspaceRoot(startDirectory: string): string | undefined {
+  let directory = startDirectory;
+  for (;;) {
+    const isWorkspaceRoot = fs.existsSync(path.join(directory, 'pnpm-workspace.yaml'))
+      && fs.existsSync(path.join(directory, 'packages/toolkit/scaffold-wizard/package.json'));
+    if (isWorkspaceRoot) return directory;
+    const parent = path.dirname(directory);
+    if (parent === directory) return undefined;
+    directory = parent;
+  }
+}
+
+function readPackedRanges(moduleDirectory: string): StackVersionRanges | undefined {
+  const rangesFile = path.join(moduleDirectory, STACK_VERSION_RANGES_FILE);
+  if (!fs.existsSync(rangesFile)) return undefined;
+  return Object.freeze(JSON.parse(fs.readFileSync(rangesFile, 'utf8')) as StackVersionRanges);
+}
+
+let cachedRanges: StackVersionRanges | undefined;
+
+/** Ranges for this installation: packed file, then a live monorepo checkout, else none. */
+export function loadStackVersionRanges(): StackVersionRanges {
+  if (cachedRanges) return cachedRanges;
+  const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+  const packedRanges = readPackedRanges(moduleDirectory);
+  if (packedRanges) {
+    cachedRanges = packedRanges;
+    return cachedRanges;
+  }
+  const workspaceRoot = findZhinWorkspaceRoot(moduleDirectory);
+  cachedRanges = workspaceRoot ? collectStackVersionRanges(workspaceRoot) : Object.freeze({});
+  return cachedRanges;
+}
+
+/** Range to write for one package; `latest` only when no release version is known. */
+export function scaffoldDependencyRange(
+  packageName: string,
+  ranges: StackVersionRanges = loadStackVersionRanges(),
+): string {
+  return ranges[packageName] ?? FALLBACK_DEPENDENCY_RANGE;
+}
+
+/**
+ * Replace `latest` entries with derived ranges before a scaffold writes package.json.
+ * Explicit ranges (database drivers, tooling) and packages without a known version stay as they are.
+ */
+export function withScaffoldVersionRanges(
+  dependencies: Readonly<Record<string, string>>,
+  ranges: StackVersionRanges = loadStackVersionRanges(),
+): Record<string, string> {
+  const resolved: Record<string, string> = {};
+  for (const [packageName, range] of Object.entries(dependencies)) {
+    const isFloating = range === FALLBACK_DEPENDENCY_RANGE;
+    resolved[packageName] = isFloating ? scaffoldDependencyRange(packageName, ranges) : range;
+  }
+  return resolved;
+}

package/src/zhin-stack-deps.ts

@@ -5,9 +5,11 @@ import { DATABASE_DRIVER_VERSIONS, DATABASE_PACKAGES } from './types.js';
 import { findMissingPackageDependencies, findUnresolvedPackageInstalls, isAiEnabledInConfig, type PackageJsonLike } from './project-deps.js';
 
 /**
- * User project dependency policy: scaffolded Zhin packages intentionally float to latest.
+ * Diagnostic baseline for doctor / config check: any declared version of these packages is accepted
+ * (`latest`), so existing projects are never flagged because of a newer release.
+ * Scaffolds do not write these values as-is: `withScaffoldVersionRanges()` replaces `latest` with the
+ * caret range of the version released together with this package (see stack-version-ranges.ts).
  * Database drivers use the live-tested ranges declared by the database definitions.
- * WARNING: `latest` is not reproducible; pin Zhin package versions for production.
  */
 export const ZHIN_STACK_VERSIONS = {
   'zhin.js': 'latest',

package/src/stack-versions.generated.json

@@ -1,45 +0,0 @@
-{
-  "$comment": "Auto-generated by scripts/sync-scaffold-deps.mjs — do not edit; run pnpm sync:scaffold-deps",
-  "zhinStack": {
-    "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/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.5",
-    "ai": "^7.0.0",
-    "zod": "^4.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"
-  }
-}