@jetcrab/pi-desk 1.1.12 → 1.1.16

package/src/server/l2_biz/plugin-management/l2-plugin-management.ts

@@ -97,6 +97,20 @@ interface L2PluginPackageMetadata {
 
 type L2PluginMutation = 'add' | 'update' | 'del' | 'enable' | 'disable'
 
+interface L2PluginMutationInput {
+  mutation: L2PluginMutation
+  source: string
+  operationSource: string
+  reinstall: boolean
+  options: Omit<L2PluginManagementInstallRequest, 'source'>
+}
+
+interface L2PluginPreparedMutation {
+  request: L4PiDeskPackageMaintenanceRequest | null
+  updateTag: string | null
+  pluginName: string | null
+}
+
 export interface L2PluginManagementWorkSessions {
   refreshPluginMessages: () => void
   runPluginRestart: <T>(operation: () => Promise<T>) => Promise<T>
@@ -402,6 +416,9 @@ export class L2PluginManagement {
     this.assertOpen()
     const results: L2PluginManagementBatchResponse['results'] = []
     const seen = new Set<string>()
+    const snapshot =
+      input.action === 'add' || input.action === 'update' ? await this.readSources() : null
+    const mutations: L2PluginMutationInput[] = []
     const items = input.action === 'add' ? input.items : input.sources.map((source) => ({ source }))
     for (const item of items) {
       try {
@@ -413,9 +430,9 @@ export class L2PluginManagement {
         seen.add(identity)
         if (input.action === 'add') {
           const { source: _source, ...options } = item
-          await this.reinstall(source, undefined, options)
+          mutations.push(this.acceptMutation('add', source, snapshot!, true, undefined, options))
         } else if (input.action === 'update') {
-          await this.update(source)
+          mutations.push(this.acceptMutation('update', source, snapshot!))
         } else if (input.action === 'del') {
           await this.del(source)
         } else {
@@ -426,6 +443,7 @@ export class L2PluginManagement {
         results.push({ source: item.source, error: errorMessage(error).slice(0, 4000) })
       }
     }
+    if (mutations.length > 0) this.enqueueMutations(mutations)
     return { snapshot: await this.readSnapshot(false), results }
   }
 
@@ -673,7 +691,13 @@ export class L2PluginManagement {
   }
 
   reload(mode?: 'normal' | 'basic'): Promise<L2PluginManagementSnapshot> {
-    if (this.activeSource) {
+    if (
+      this.activeSource ||
+      [...this.operations].some(
+        ([source, operation]) =>
+          operation.phase !== 'failed' && !this.deferredMaintenance.has(source)
+      )
+    ) {
       return Promise.reject(
         new L2PluginManagementOperationConflictError('维护仍在执行或等待，请先完成当前操作')
       )
@@ -691,14 +715,34 @@ export class L2PluginManagement {
     previousSource?: string,
     options: Omit<L2PluginManagementInstallRequest, 'source'> = {}
   ): Promise<L2PluginManagementSnapshot> {
+    this.assertOpen()
+    const snapshot = await this.readSources()
+    const input = this.acceptMutation(
+      mutation,
+      source,
+      snapshot,
+      reinstall,
+      previousSource,
+      options
+    )
+    this.enqueueMutations([input])
+    return this.readSnapshot(false)
+  }
+
+  private acceptMutation(
+    mutation: L2PluginMutation,
+    source: string,
+    snapshot: L4PiPluginSourceSnapshot,
+    reinstall = false,
+    previousSource?: string,
+    options: Omit<L2PluginManagementInstallRequest, 'source'> = {}
+  ): L2PluginMutationInput {
     this.assertOpen()
     if (isL4PiDeskSafeMode()) {
       throw new L2PluginManagementOperationConflictError(
         '基础模式不执行插件维护，请通过基础聊天修复或正常启动后维护'
       )
     }
-    const snapshot = await this.readSources()
-    this.assertOpen()
     const existing = snapshot.sources.find(
       (item) => l2PluginSourceIdentity(item.source) === l2PluginSourceIdentity(source)
     )
@@ -733,36 +777,66 @@ export class L2PluginManagement {
     this.operations.set(operationSource, { action: mutation, phase: 'queued', message: null })
     this.updates.clear(operationSource)
     this.updates.clear(source)
-    this.publish()
+    return { mutation, source, operationSource, reinstall, options }
+  }
+
+  private enqueueMutations(inputs: readonly L2PluginMutationInput[]): void {
     void this.runExclusive(async () => {
-      this.activeSource = operationSource
-      try {
-        await this.executeMutation(mutation, source, operationSource, reinstall, options)
-        if (!this.deferredMaintenance.has(operationSource)) this.operations.delete(operationSource)
-      } catch (error) {
-        this.setOperation(operationSource, 'failed', errorMessage(error))
-      } finally {
-        this.updates.clear(operationSource)
-        this.updates.clear(source)
-        this.sourceCache = null
-        this.activeSource = null
-        this.publish()
+      const startedAt = performance.now()
+      // 本批全部准备收尾后才写正式目录；错误按项收集，不让早退遗留预检进程。
+      const candidates = await Promise.all(
+        inputs.map(async (input) => {
+          try {
+            const prepared = await this.prepareMutation(input)
+            this.assertOpen()
+            this.setOperation(input.operationSource, 'queued', '候选检查完成，等待应用')
+            return { input, prepared }
+          } catch (error) {
+            this.setOperation(input.operationSource, 'failed', errorMessage(error))
+            return null
+          }
+        })
+      )
+      if (inputs.length > 1) {
+        console.info('[Pi Desk][PluginManagement] 批量并行准备收尾', {
+          count: inputs.length,
+          failedCount: candidates.filter((item) => item === null).length,
+          durationMs: Math.round(performance.now() - startedAt)
+        })
+      }
+      for (const candidate of candidates) {
+        if (!candidate) continue
+        const { input, prepared } = candidate
+        const { source, operationSource } = input
+        this.activeSource = operationSource
+        try {
+          this.assertOpen()
+          if (prepared) await this.executeMutation(input, prepared)
+          if (!this.deferredMaintenance.has(operationSource))
+            this.operations.delete(operationSource)
+        } catch (error) {
+          this.setOperation(operationSource, 'failed', errorMessage(error))
+        } finally {
+          this.updates.clear(operationSource)
+          this.updates.clear(source)
+          this.sourceCache = null
+          this.activeSource = null
+          this.publish()
+        }
       }
     }).catch((error: unknown) => {
-      if (!this.disposed) this.setOperation(operationSource, 'failed', errorMessage(error))
+      if (this.disposed) return
+      for (const input of inputs)
+        this.setOperation(input.operationSource, 'failed', errorMessage(error))
     })
-    return this.readSnapshot(false)
+    this.publish()
   }
 
-  private async executeMutation(
-    mutation: L2PluginMutation,
-    source: string,
-    operationSource: string,
-    reinstall: boolean,
-    options: Omit<L2PluginManagementInstallRequest, 'source'>
-  ): Promise<void> {
-    const runtime = getL4PiGlobalPluginRuntime()
-    const waiting = (reason: string): void => this.setOperation(operationSource, 'waiting', reason)
+  private async prepareMutation(
+    input: L2PluginMutationInput
+  ): Promise<L2PluginPreparedMutation | null> {
+    const { mutation, source, operationSource, reinstall, options } = input
+    this.assertOpen()
     const current = this.createPackageManager()
     this.throwSettingsErrors(current.settingsManager)
     const configured = current.packageManager
@@ -771,10 +845,12 @@ export class L2PluginManagement {
     const target = configured.find((item) => item.source === operationSource)
     let request: L4PiDeskPackageMaintenanceRequest | null = null
     let updateTag: string | null = null
+    let pluginName: string | null = null
     if (mutation !== 'enable' && mutation !== 'disable') {
       const packageRootError = await readL4PiPackageRootConsistencyError({
         agentDir: this.agentDir,
-        configured
+        configured,
+        repairSource: mutation === 'add' && reinstall ? operationSource : undefined
       })
       if (packageRootError) throw new L2PluginManagementPackageRootError(packageRootError)
       if (mutation !== 'add' && !target) throw new L2PluginManagementNotFoundError(source)
@@ -796,7 +872,7 @@ export class L2PluginManagement {
         const version = resolved.source.slice(resolved.source.lastIndexOf('@') + 1)
         if (!installed.version)
           throw new L2PluginManagementInvalidPackageError('无法读取插件已安装版本')
-        if (!isL2PluginNewerVersion(version, installed.version)) return
+        if (!isL2PluginNewerVersion(version, installed.version)) return null
       }
       request = {
         ...(npmName && mutation !== 'del' && (reinstall || target || mutation === 'update')
@@ -805,7 +881,22 @@ export class L2PluginManagement {
         ...('registry' in resolved && resolved.registry ? { registry: resolved.registry } : {})
       }
       if (mutation !== 'del')
-        await this.probeCandidate(resolved.source, operationSource, request.registry)
+        pluginName = await this.probeCandidate(resolved.source, request.registry)
+    }
+    return { request, updateTag, pluginName }
+  }
+
+  private async executeMutation(
+    input: L2PluginMutationInput,
+    prepared: L2PluginPreparedMutation
+  ): Promise<void> {
+    const { mutation, source, operationSource } = input
+    const { request, updateTag, pluginName } = prepared
+    const runtime = getL4PiGlobalPluginRuntime()
+    const waiting = (reason: string): void => this.setOperation(operationSource, 'waiting', reason)
+    if (request) {
+      // 先前项可能安装失败或注册同名插件，不能依赖并行准备时的旧结论。
+      this.assertPluginNameAvailable(pluginName, operationSource)
       if (updateTag) {
         setL4PiPluginUpdateTag(operationSource, updateTag, this.agentDir)
         this.updates.clear(operationSource)
@@ -820,6 +911,20 @@ export class L2PluginManagement {
     await runtime.withSourceIdle(
       operationSource,
       async () => {
+        if (request) {
+          const current = this.createPackageManager()
+          this.throwSettingsErrors(current.settingsManager)
+          const configured = current.packageManager
+            .listConfiguredPackages()
+            .filter((item) => item.scope === 'user')
+          const rootError = await readL4PiPackageRootConsistencyError({
+            agentDir: this.agentDir,
+            configured,
+            repairSource: mutation === 'add' && input.reinstall ? operationSource : undefined
+          })
+          if (rootError) throw new L2PluginManagementPackageRootError(rootError)
+        }
+        this.assertOpen()
         this.setOperation(
           operationSource,
           'applying',
@@ -997,11 +1102,7 @@ export class L2PluginManagement {
     return writing() && this.sourceCache ? this.sourceCache : snapshot
   }
 
-  private async probeCandidate(
-    source: string,
-    activeSource: string,
-    registry?: string
-  ): Promise<void> {
+  private async probeCandidate(source: string, registry?: string): Promise<string | null> {
     const root = join(this.stagingRoot, randomUUID())
     const stagingAgentDir = join(root, 'agent')
     const stagingCwd = join(root, 'workspace')
@@ -1031,7 +1132,8 @@ export class L2PluginManagement {
       await runL4PiPackageMaintenance({
         maintenance: { action: 'install', source, ...(registry ? { registry } : {}) },
         agentDir: stagingAgentDir,
-        cwd: stagingCwd
+        cwd: stagingCwd,
+        signal: this.lifetime.signal
       })
 
       this.assertOpen()
@@ -1047,7 +1149,12 @@ export class L2PluginManagement {
 
       await this.verifyPackageVersion(source, candidate.installedPath)
 
-      const diagnostics = await runL4PiPluginProbe(stagingCwd, stagingAgentDir, true)
+      const diagnostics = await runL4PiPluginProbe(
+        stagingCwd,
+        stagingAgentDir,
+        true,
+        this.lifetime.signal
+      )
       if (diagnostics.loadError) {
         throw new L2PluginManagementInvalidPackageError(diagnostics.loadError)
       }
@@ -1056,21 +1163,10 @@ export class L2PluginManagement {
         throw new L2PluginManagementInvalidPackageError(failed.error.message)
       }
 
-      const candidatePluginName = diagnostics.packages[0]?.pluginName
-      if (candidatePluginName) {
-        const conflict = getL4PiGlobalPluginRuntime()
-          .readDiagnostics()
-          .packages.find(
-            (item) => item.source !== activeSource && item.pluginName === candidatePluginName
-          )
-        if (conflict) {
-          throw new L2PluginManagementInvalidPackageError(
-            `pluginName 已由其他 Package 注册：${candidatePluginName}`
-          )
-        }
-      }
+      const candidatePluginName = diagnostics.packages[0]?.pluginName ?? null
       this.assertOpen()
       console.info('[Pi Desk][PluginManagement] 候选插件隔离预检通过', { source })
+      return candidatePluginName
     } catch (error) {
       if (error instanceof L2PluginManagementInvalidPackageError) throw error
       throw new L2PluginManagementInvalidPackageError(errorMessage(error))
@@ -1084,6 +1180,17 @@ export class L2PluginManagement {
     }
   }
 
+  private assertPluginNameAvailable(pluginName: string | null, source: string): void {
+    if (!pluginName) return
+    const conflict = getL4PiGlobalPluginRuntime()
+      .readDiagnostics()
+      .packages.some((item) => item.source !== source && item.pluginName === pluginName)
+    if (conflict)
+      throw new L2PluginManagementInvalidPackageError(
+        `pluginName 已由其他 Package 注册：${pluginName}`
+      )
+  }
+
   private restartWhenQuiet(mode?: 'normal' | 'basic'): Promise<L2PluginManagementSnapshot> {
     return this.workSessions.runPluginRestart(async () => {
       const runtime = getL4PiGlobalPluginRuntime()

package/src/server/l2_biz/work-session/l2-work-session-chat-runtime.ts

@@ -564,6 +564,11 @@ export class L2WorkSessionChatRuntime {
     return this.enqueueCommand(record, () => record.workSession.restoreQueuedMessages())
   }
 
+  setTitle(workSession: WorkSession, title: string): Promise<void> {
+    const record = this.recordFor(workSession)
+    return this.enqueueCommand(record, () => record.workSession.setTitle(title))
+  }
+
   setModel(input: L2ChatModelSetRequest): Promise<void> {
     const record = this.currentRecord(input.source)
     return this.enqueueCommand(record, () => record.workSession.setModel(input.model))

package/src/server/l2_biz/work-session/l2-work-session-manage.ts

@@ -59,12 +59,14 @@ import {
 import {
   L2CwdSchema,
   L2PiSessionIdSchema,
+  L2RenameWorkSessionRequestSchema,
   L2WorkIdSchema,
   L2WorkSessionListItemSchema,
   L2WorkSessionListResponseSchema,
   L2WorkSessionPinnedCountSchema,
   L2WorkSessionRecordSchema,
   L2WorkSessionRecordsSchema,
+  type L2RenameWorkSessionRequest,
   type L2WorkSessionListItem,
   type L2WorkSessionListResponse,
   type L2WorkSessionRecord,
@@ -560,6 +562,17 @@ export class WorkSessionManage {
     })
   }
 
+  renameWorkSession(inputValue: L2RenameWorkSessionRequest): Promise<void> {
+    const input = L2RenameWorkSessionRequestSchema.parse(inputValue)
+    return this.runExclusive(async () => {
+      await this.ensureHydrated()
+      const current = this.workSessionsById.get(input.workId)
+      if (!current) throw new WorkSessionNotFoundError(input.workId)
+      this.assertSessionBinding(current, input.sessionId)
+      await this.chat.setTitle(current, input.title)
+    })
+  }
+
   replaceWorkSession(
     workIdInput: string,
     historySessionInput?: { cwd: string; sessionId: string }

package/src/server/l3_modules/work-session/l3-work-session.ts

@@ -91,6 +91,10 @@ export class WorkSession {
     return this.runtime.restoreQueuedMessages()
   }
 
+  async setTitle(title: string): Promise<void> {
+    await this.runtime.setTitle(title)
+  }
+
   async setModel(input: WorkSessionModelInput): Promise<void> {
     await this.runtime.setModel(input)
   }

package/src/server/l4_foundation/model-settings/l4-model-settings-store.ts

@@ -31,6 +31,7 @@ import type {
   L4ModelPreset,
   L4ModelProviderConfig,
   L4ModelSelection,
+  L4ModelSettingsPreview,
   L4ModelSettingsReplaceInput
 } from './l4-model-settings-types'
 
@@ -99,17 +100,47 @@ function readJsonRecord(path: string): JsonRecord {
   return value
 }
 
-function writeJsonRecordAtomic(path: string, value: JsonRecord): void {
+function writeTextAtomic(path: string, content: string): void {
   mkdirSync(dirname(path), { recursive: true })
   const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`
   try {
-    writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8')
+    writeFileSync(temporaryPath, content, 'utf8')
     renameSync(temporaryPath, path)
   } finally {
     if (existsSync(temporaryPath)) unlinkSync(temporaryPath)
   }
 }
 
+function writeJsonRecordAtomic(path: string, value: JsonRecord): void {
+  writeTextAtomic(path, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+function writeRecordsWithRollback(files: Array<{ path: string; value: JsonRecord }>): void {
+  const originals = files.map(({ path }) => (existsSync(path) ? readFileSync(path, 'utf8') : null))
+  let written = 0
+  try {
+    for (const { path, value } of files) {
+      writeJsonRecordAtomic(path, value)
+      written += 1
+    }
+  } catch (cause) {
+    for (let index = written - 1; index >= 0; index -= 1) {
+      const path = files[index].path
+      const content = originals[index]
+      try {
+        if (content === null) unlinkSync(path)
+        else writeTextAtomic(path, content)
+      } catch (error) {
+        console.error('[Pi Desk][ModelSettings] 配置文件回滚失败', {
+          path,
+          message: error instanceof Error ? error.message : String(error)
+        })
+      }
+    }
+    throw cause
+  }
+}
+
 function serializeWrite<T>(task: () => Promise<T>): Promise<T> {
   const result = writeQueue.then(task, task)
   writeQueue = result.then(
@@ -592,10 +623,41 @@ async function assertConnectionCredentials(
   }
 }
 
-async function assertRemovalReferences(current: JsonRecord, candidate: JsonRecord): Promise<void> {
+async function prepareProjectDefaultChanges(
+  current: JsonRecord,
+  candidate: JsonRecord,
+  input: L4ModelSettingsReplaceInput,
+  runtime: ModelRuntime,
+  models: L4ModelOption[]
+): Promise<{
+  projectDefaults: L4ModelSettingsPreview['projectDefaults']
+  files: Array<{ path: string; value: JsonRecord }>
+}> {
+  const previousKeys = collectedModelKeys(current)
   const nextKeys = collectedModelKeys(candidate)
-  const removed = new Set([...collectedModelKeys(current)].filter((key) => !nextKeys.has(key)))
-  if (!removed.size) return
+  const removed = new Set([...previousKeys].filter((key) => !nextKeys.has(key)))
+  const replacements = new Map<string, L4ModelOption>()
+  for (const { from, to } of input.modelReplacements ?? []) {
+    const fromKey = collectedModelKey(from.provider, from.modelId)
+    const toKey = collectedModelKey(to.provider, to.modelId)
+    if (fromKey === toKey) throw new Error('模型替换来源和目标不能相同')
+    if (replacements.has(fromKey)) throw new Error('模型替换来源不能重复')
+    if (!previousKeys.has(fromKey) || !removed.has(fromKey)) {
+      throw new Error(`替换来源 ${from.provider}/${from.modelId} 必须是本次移除的已收录模型`)
+    }
+    const target = models.find(
+      (model) => model.provider === to.provider && model.modelId === to.modelId
+    )
+    if (!nextKeys.has(toKey) || !target) {
+      throw new Error(`替换目标 ${to.provider}/${to.modelId} 未收录或不可用`)
+    }
+    replacements.set(fromKey, target)
+  }
+  const result: {
+    projectDefaults: L4ModelSettingsPreview['projectDefaults']
+    files: Array<{ path: string; value: JsonRecord }>
+  } = { projectDefaults: [], files: [] }
+  if (!removed.size) return result
   for (const preset of normalizePresets(candidate)) {
     if (removed.has(collectedModelKey(preset.provider, preset.modelId))) {
       throw new Error(
@@ -606,17 +668,60 @@ async function assertRemovalReferences(current: JsonRecord, candidate: JsonRecor
   // 仅在移除模型时检查已知项目，不扫描文件系统寻找任意项目配置。
   const projects = await listL4PiDirectorySummaries(true)
   for (const { cwd } of projects) {
-    const settings = readJsonRecord(join(cwd, CONFIG_DIR_NAME, 'settings.json'))
+    const path = join(cwd, CONFIG_DIR_NAME, 'settings.json')
+    const settings = readJsonRecord(path)
     if (
-      typeof settings.defaultProvider === 'string' &&
-      typeof settings.defaultModel === 'string' &&
-      removed.has(collectedModelKey(settings.defaultProvider, settings.defaultModel))
+      !['defaultProvider', 'defaultModel', 'defaultThinkingLevel'].some((key) =>
+        Object.hasOwn(settings, key)
+      )
     ) {
+      continue
+    }
+    const merged = SettingsManager.create(cwd, getAgentDir())
+    const provider = merged.getDefaultProvider()
+    const modelId = merged.getDefaultModel()
+    if (!provider || !modelId || !removed.has(collectedModelKey(provider, modelId))) continue
+    const target = replacements.get(collectedModelKey(provider, modelId))
+    if (!target) {
       throw new Error(
-        `项目“${cwd}”仍将 ${settings.defaultProvider}/${settings.defaultModel} 设为默认模型，请先在“项目默认”中调整`
+        `项目“${cwd}”仍将 ${provider}/${modelId} 设为默认模型，请先在“项目默认”中调整`
       )
     }
+    const projectModels = await availableModelOptions(runtime, cwd, candidate)
+    if (
+      !projectModels.some(
+        (model) => model.provider === target.provider && model.modelId === target.modelId
+      )
+    ) {
+      throw new Error(`替换目标 ${target.provider}/${target.modelId} 在项目“${cwd}”中不可用`)
+    }
+    const from: L4ModelSelection = {
+      provider,
+      modelId,
+      thinkingLevel: merged.getDefaultThinkingLevel() ?? 'off'
+    }
+    const thinkingLevel = target.thinkingLevels.includes(from.thinkingLevel)
+      ? from.thinkingLevel
+      : target.thinkingLevels[0]
+    if (!thinkingLevel)
+      throw new Error(`替换目标 ${target.provider}/${target.modelId} 没有可用思考等级`)
+    const to: L4ModelSelection = {
+      provider: target.provider,
+      modelId: target.modelId,
+      thinkingLevel
+    }
+    result.projectDefaults.push({ cwd, from, to })
+    result.files.push({
+      path,
+      value: {
+        ...settings,
+        defaultProvider: to.provider,
+        defaultModel: to.modelId,
+        defaultThinkingLevel: to.thinkingLevel
+      }
+    })
   }
+  return result
 }
 
 export async function readL4ModelSettings(): Promise<{
@@ -654,37 +759,55 @@ export async function readL4ModelSettings(): Promise<{
   return result
 }
 
+async function prepareModelSettings(input: L4ModelSettingsReplaceInput): Promise<{
+  projectDefaults: L4ModelSettingsPreview['projectDefaults']
+  files: Array<{ path: string; value: JsonRecord }>
+}> {
+  const path = modelsPath()
+  let current: JsonRecord
+  try {
+    current = readJsonRecord(path)
+  } catch (error) {
+    if (input.nativeConfig === undefined) throw error
+    // 原生编辑是损坏配置的修复入口，不能要求旧文件先成功解析。
+    current = {}
+  }
+  let candidate: JsonRecord
+  if (input.nativeConfig !== undefined) {
+    candidate = input.nativeConfig
+  } else {
+    const currentRuntime = await ModelRuntime.create({ allowModelNetwork: false })
+    const error = currentRuntime.getError()
+    if (error) throw new Error(`当前模型配置不可用，请先通过原生配置修正：${error}`)
+    const defaults =
+      input.accountModels === undefined
+        ? currentRuntime
+        : await ModelRuntime.create({ modelsPath: null, allowModelNetwork: false })
+    candidate = mergeModelsRoot(current, input, currentRuntime, defaults)
+  }
+  const runtime = await validateModelsRoot(candidate)
+  const models = await availableModelOptions(runtime, undefined, candidate)
+  await assertConnectionCredentials(current, candidate, runtime)
+  assertPresetsValid(normalizePresets(candidate), models, normalizePresets(current))
+  const result = await prepareProjectDefaultChanges(current, candidate, input, runtime, models)
+  result.files.push({ path, value: candidate })
+  return result
+}
+
+export async function previewL4ModelSettings(
+  input: L4ModelSettingsReplaceInput
+): Promise<L4ModelSettingsPreview> {
+  return serializeWrite(async () => {
+    const { projectDefaults } = await prepareModelSettings(input)
+    return { projectDefaults }
+  })
+}
+
 export async function replaceL4ModelSettings(input: L4ModelSettingsReplaceInput): Promise<void> {
   await serializeWrite(async () => {
-    const path = modelsPath()
     try {
-      let current: JsonRecord
-      try {
-        current = readJsonRecord(path)
-      } catch (error) {
-        if (input.nativeConfig === undefined) throw error
-        // 原生编辑是损坏配置的修复入口，不能要求旧文件先成功解析。
-        current = {}
-      }
-      let candidate: JsonRecord
-      if (input.nativeConfig !== undefined) {
-        candidate = input.nativeConfig
-      } else {
-        const currentRuntime = await ModelRuntime.create({ allowModelNetwork: false })
-        const error = currentRuntime.getError()
-        if (error) throw new Error(`当前模型配置不可用，请先通过原生配置修正：${error}`)
-        const defaults =
-          input.accountModels === undefined
-            ? currentRuntime
-            : await ModelRuntime.create({ modelsPath: null, allowModelNetwork: false })
-        candidate = mergeModelsRoot(current, input, currentRuntime, defaults)
-      }
-      const runtime = await validateModelsRoot(candidate)
-      const models = await availableModelOptions(runtime, undefined, candidate)
-      await assertConnectionCredentials(current, candidate, runtime)
-      await assertRemovalReferences(current, candidate)
-      assertPresetsValid(normalizePresets(candidate), models, normalizePresets(current))
-      writeJsonRecordAtomic(path, candidate)
+      const { files } = await prepareModelSettings(input)
+      writeRecordsWithRollback(files)
     } catch (cause) {
       console.error('[Pi Desk][ModelSettings] 模型配置保存失败', {
         message: cause instanceof Error ? cause.message : String(cause)

package/src/server/l4_foundation/model-settings/l4-model-settings-types.ts

@@ -91,11 +91,21 @@ export interface L4ModelAccount {
   models: L4ModelConfig[]
 }
 
+export interface L4ModelReplacement {
+  from: { provider: string; modelId: string }
+  to: { provider: string; modelId: string }
+}
+
+export interface L4ModelSettingsPreview {
+  projectDefaults: Array<{ cwd: string; from: L4ModelSelection; to: L4ModelSelection }>
+}
+
 export type L4ModelSettingsReplaceInput =
   | {
       providers?: L4ModelProviderConfig[]
       presets?: L4ModelPreset[]
       accountModels?: L4AccountModelSelection[]
+      modelReplacements?: L4ModelReplacement[]
       nativeConfig?: never
     }
   | {
@@ -103,6 +113,7 @@ export type L4ModelSettingsReplaceInput =
       providers?: never
       presets?: never
       accountModels?: never
+      modelReplacements?: never
     }
 
 export interface L4ModelCatalogRequest {

package/src/server/l4_foundation/model-settings/l4-model-settings.ts

@@ -5,6 +5,7 @@ export {
   readL4ModelSettings,
   filterL4CollectedModels,
   readL4ProjectModelDefault,
+  previewL4ModelSettings,
   replaceL4ModelSettings,
   replaceL4ProjectModelDefault
 } from './l4-model-settings-store'