@jetcrab/pi-desk 1.1.23-dev → 1.1.24-dev

package/docs/commands.md

@@ -71,6 +71,8 @@
 
 接纳后结束当前轮；宿主等本会话完全空闲后重载，再通知并唤醒本会话。重载可能重建插件内存状态、使缓存失效，配置和工具声明变化也可能影响提示词缓存。
 
-插件管理只等待目标来源必要的在途调用，不冻结常规聊天。完成通知表示包和宿主能力已应用；新建会话使用最新工具配置，已有原生 Pi 会话不自动重载。Node/Browser 替换会重新挂载目标插件界面，旧调用可能失效；结果未知的副作用请求不自动重发。
+插件管理最多等待目标来源的在途调用 15 秒；超过时仅该项维护失败，可稍后手动重试，不冻结常规聊天或阻止后续其他来源维护。完成通知表示包和宿主能力已应用；新建会话使用最新工具配置，已有原生 Pi 会话不自动重载。Node/Browser 替换会重新挂载目标插件界面，旧调用可能失效；结果未知的副作用请求不自动重发。
 
-需要重启时按插件管理界面的维护流程处理，以最终结果为准。
+维护期间或失败后允许目标包暂时缺失。会话跳过缺失或版本不符的包，明确的单插件加载/启动错误在插件管理中保留诊断，不因此让其他正常插件一起降级。聊天订阅、刷新和重连不等待包维护或插件初始化；未就绪的模型与插件状态稍后同步。修复包后按需重载目标会话，不自动重载已有会话。
+
+需要重启时按插件管理界面的维护流程处理，只延后受影响来源，以最终结果为准。

package/docs/plugins.md

@@ -339,4 +339,6 @@ try {
 
 ## 更新生效
 
+包维护不阻塞聊天订阅、刷新或其他会话。缺失或版本不符的包会被跳过，导入/工厂失败的入口不加载；Pi 生命周期回调和插件 Provider 注册的明确错误保留在插件管理诊断中，不升级为整会话失败。正常扩展继续加载。此隔离不终止同步死循环，也不回滚插件已发生的外部副作用；整体初始化超时仍可能使当前会话回退基础聊天，不阻塞其他会话的历史同步。
+
 `plugins install/reload` 应用 Node/Browser 能力；目标插件活动视图重挂，旧 Browser Owner 失效。现有 Native 会话不自动重载，新 UI 可能连接旧会话方法，需兼容既有消息和方法数据；需要现有会话加载当前原生代码时使用 `session reload`。热加载无法处理的资源按宿主已有重启流程处理，不把重新挂载界面当作后端任务已停止。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jetcrab/pi-desk",
-  "version": "1.1.23-dev",
+  "version": "1.1.24-dev",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",

package/src/server/l1_entry/api/l1-plugin-management-route.ts

@@ -15,7 +15,6 @@ import {
   L2PluginManagementInvalidPackageError,
   L2PluginManagementNotFoundError,
   L2PluginManagementOperationConflictError,
-  L2PluginManagementPackageRootError,
   L2PluginManagementRestartPendingError,
   L2PluginManagementRestartUnavailableError
 } from '@server/l2_biz/plugin-management/l2-plugin-management'
@@ -43,9 +42,6 @@ function pluginOperationError(error: unknown, action: string): Response {
   ) {
     return createL4ApiErrorResponse(409, error.message)
   }
-  if (error instanceof L2PluginManagementPackageRootError) {
-    return createL4ApiErrorResponse(409, error.message, error.rootError.i18n)
-  }
   if (error instanceof L2PluginReloadBlockedError) {
     return createL4ApiErrorResponse(409, error.message, {
       key: 'errors:pluginReloadBlocked',

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

@@ -136,13 +136,6 @@ export class L2PluginManagementInvalidPackageError extends Error {
   }
 }
 
-export class L2PluginManagementPackageRootError extends Error {
-  constructor(readonly rootError: L4PiPackageRootConsistencyError) {
-    super(rootError.message)
-    this.name = 'L2PluginManagementPackageRootError'
-  }
-}
-
 export class L2PluginManagementRestartPendingError extends Error {
   constructor() {
     super('已有插件操作需要重启完成')
@@ -845,12 +838,6 @@ export class L2PluginManagement {
     let updateTag: string | null = null
     let pluginName: string | null = null
     if (mutation !== 'enable' && mutation !== 'disable') {
-      const packageRootError = await readL4PiPackageRootConsistencyError({
-        agentDir: this.agentDir,
-        configured,
-        repairSource: mutation === 'add' && reinstall ? operationSource : undefined
-      })
-      if (packageRootError) throw new L2PluginManagementPackageRootError(packageRootError)
       if (mutation !== 'add' && !target) throw new L2PluginManagementNotFoundError(source)
       this.setOperation(operationSource, 'checking', '正在确认插件版本和下载源')
       const candidate = this.candidateSource(source, target?.installedPath)
@@ -899,29 +886,11 @@ export class L2PluginManagement {
         setL4PiPluginUpdateTag(operationSource, updateTag, this.agentDir)
         this.updates.clear(operationSource)
       }
-      if (this.deferredMaintenance.size > 0) {
-        this.deferredMaintenance.set(operationSource, request)
-        waiting('等待重启后完成安装维护')
-        return
-      }
     }
     this.assertOpen()
     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,
@@ -957,7 +926,8 @@ export class L2PluginManagement {
               await runL4PiPackageMaintenance({
                 maintenance: request!,
                 agentDir: this.agentDir,
-                cwd: this.packageManagerCwd
+                cwd: this.packageManagerCwd,
+                signal: this.lifetime.signal
               })
               if (mutation !== 'del') await this.verifyInstalledPackage(request!.source)
             })
@@ -1372,11 +1342,8 @@ export class L2PluginManagement {
     if (!force && this.capabilityCache) return this.capabilityCache
 
     try {
-      this.capabilityCache = await runL4PiPackageRootExclusive(() => {
-        this.assertOpen()
-        if (!force && this.capabilityCache) return Promise.resolve(this.capabilityCache)
-        return runL4PiPluginCapabilityProbe(this.cwd, this.agentDir)
-      })
+      this.assertOpen()
+      this.capabilityCache = await runL4PiPluginCapabilityProbe(this.cwd, this.agentDir)
       this.publish()
       console.info('[Pi Desk][PluginManagement] 插件能力盘点完成', {
         packageCount: this.capabilityCache.packages.length,

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

@@ -20,7 +20,6 @@ import {
   resolveL4PluginInstall
 } from '@server/l4_foundation/pi/l4-pi-plugin-registry'
 import type { L4PiPluginSource } from '@server/l4_foundation/pi/l4-pi-plugin-sources'
-import { runL4PiPackageRootExclusive } from '@server/l4_foundation/pi/l4-pi-package-root-gate'
 
 const UPDATE_CACHE_TTL_MS = 5 * 60 * 1000
 const UPDATE_CACHE_MAX_ENTRIES = 128
@@ -163,9 +162,7 @@ export class L2PluginUpdates {
             cwd: this.cwd,
             settingsManager
           })
-          const updates = await runL4PiPackageRootExclusive(() =>
-            manager.checkForAvailableUpdates()
-          )
+          const updates = await manager.checkForAvailableUpdates()
           const value: L2PluginUpdateStatus = {
             ...empty,
             updateAvailable: updates.some((item) => item.scope === 'user')

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

@@ -359,17 +359,19 @@ export class L2WorkSessionChatRuntime {
 
   prepareSource(sourceInput: L2ChatSource): Promise<void> {
     const record = this.currentRecord(sourceInput)
-    return this.enqueueCommand(record, () => this.syncRecordRuntime(record))
+    // 快照读取不能排在重载、原生命令或插件初始化等修改操作后面。
+    return this.syncRecordRuntime(record)
   }
 
   private async syncRecordRuntime(record: L2WorkSessionChatRecord): Promise<void> {
     const source = record.source
+    const version = record.sourceEventVersion
     const runtime = await getL4PiWorkSessionRuntime(source.sessionId).readChatRuntime()
     const nextRuntime = L2ChatRuntimeSchema.parse({
       ...runtime,
       presentationMode: record.state.runtime.presentationMode
     })
-    if (!this.isCurrentSource(source)) return
+    if (!this.isCurrentSource(source) || record.sourceEventVersion !== version) return
     if (!sameRuntime(record.state.runtime, nextRuntime))
       this.applySourceEvent(source, { type: 'runtime_update', runtime: nextRuntime })
   }

package/src/server/l4_foundation/pi/l4-pi-chat-worker.ts

@@ -769,7 +769,22 @@ export class L4PiChatWorker {
     return () => this.listeners.delete(listener)
   }
 
-  async getRuntime(): Promise<L4PiChatRuntimeSnapshot> {
+  async getRuntime(waitForInitialization = true): Promise<L4PiChatRuntimeSnapshot> {
+    if (!waitForInitialization) {
+      if (this.disposed) throw new Error('Pi chat worker has been disposed')
+      // 订阅/重连先交付当前快照；初始化结果沿已有 runtime_changed 独立推送。
+      if (!this.session && !this.sessionLifecycle) {
+        void this.ensureSession().catch((cause: unknown) => {
+          if (this.disposed || this.session) return
+          this.initializationError = (cause instanceof Error ? cause.message : String(cause)).slice(
+            0,
+            32_000
+          )
+          this.emit({ type: 'runtime_changed', runtime: this.runtimeSnapshot() })
+        })
+      }
+      return this.runtimeSnapshot()
+    }
     const initialization = this.ensureSession()
     let release = (): void => undefined
     const interaction = new Promise<void>((resolve) => {

package/src/server/l4_foundation/pi/l4-pi-package-root-consistency.ts

@@ -37,7 +37,6 @@ async function directoryExists(path: string): Promise<boolean> {
 export async function readL4PiPackageRootConsistencyError(input: {
   agentDir: string
   configured: readonly L4PiConfiguredPackageLocation[]
-  repairSource?: string
 }): Promise<L4PiPackageRootConsistencyError | null> {
   const npmPackages = input.configured.flatMap((item) => {
     const name = npmPackageName(item.source)
@@ -63,14 +62,12 @@ export async function readL4PiPackageRootConsistencyError(input: {
     }
   }
 
-  // 重装失败仍保留 Pi 声明；仅显式重装的目标可以缺失，安装根本身仍须可读。
-  const repairName = input.repairSource ? npmPackageName(input.repairSource) : null
-  const requiredPackages = npmPackages.filter((item) => item.name !== repairName)
-  const expected = new Set(requiredPackages.map((item) => item.name))
+  // 只用于管理页诊断，不作为其他插件操作或聊天的前置条件。
+  const expected = new Set(npmPackages.map((item) => item.name))
   const actual = new Set(Object.keys(dependencies))
   const missing = [...expected].filter((name) => !actual.has(name))
   const missingDirectories: string[] = []
-  for (const { name, item } of requiredPackages) {
+  for (const { name, item } of npmPackages) {
     if (!item.installedPath || !(await directoryExists(item.installedPath))) {
       missingDirectories.push(name)
     }

package/src/server/l4_foundation/pi/l4-pi-package-root-gate.ts

@@ -1,6 +1,6 @@
 import 'server-only'
 
-/** 只保护安装目录的读写；扩展工厂和生命周期不能持有此锁。 */
+/** 只串行安装目录写入；只读发现、聊天与扩展生命周期不得等待此锁。 */
 export function runL4PiPackageRootExclusive<T>(operation: () => Promise<T>): Promise<T> {
   const previous = globalThis.__piDeskPackageRootTail ?? Promise.resolve()
   const result = previous.then(operation, operation)

package/src/server/l4_foundation/pi/l4-pi-plugin-owner-runtime.ts

@@ -411,8 +411,12 @@ export class L4PiPluginOwnerRuntime {
     }
     this.cancelRecovery(source)
     this.maintainingSources.add(source)
+    const deadline = performance.now() + 15_000
     try {
       while (this.owners.some((owner) => owner.source === source && owner.activeCalls.size > 0)) {
+        if (performance.now() >= deadline) {
+          throw new Error(`插件 ${source} 的在途调用未在15秒内结束，本次维护失败，可稍后手动重试`)
+        }
         onWaiting(`插件 ${source} 仍有调用正在执行`)
         await delay(250, undefined, { signal: lifetime })
       }

package/src/server/l4_foundation/pi/l4-pi-plugin-sources.ts

@@ -160,7 +160,11 @@ export async function discoverL4PiPluginSources(
 
   try {
     // 显式 skip，列清单不能触发缺失包安装、扩展导入或 AgentSession。
-    const resolved = await manager.resolve(async () => 'skip')
+    const resolved = await manager.resolve(async (source) => {
+      const item = sources.get(source)
+      if (item) item.error ??= '插件包未安装或版本不匹配'
+      return 'skip'
+    })
     for (const item of sources.values()) item.hasPiResources = false
     for (const resource of [
       ...resolved.extensions,

package/src/server/l4_foundation/pi/l4-pi-session-initialization.ts

@@ -32,7 +32,7 @@ import { L4PiUiRuntime } from './l4-pi-ui-runtime'
 const INITIALIZATION_TIMEOUT_MS = 60_000
 const CLEANUP_TIMEOUT_MS = 1_500
 const MAX_RETIRED_INITIALIZATIONS = 4
-const retiredInitializations = new Set<Promise<unknown>>()
+const retiredInitializations = new WeakMap<L4PiSessionResources, Set<Promise<unknown>>>()
 const STALE_MESSAGE = 'Pi 会话实例已失效，不能继续访问当前会话'
 
 interface InitializationOptions {
@@ -57,6 +57,7 @@ export class L4PiSessionInitialization {
   readonly ui: L4PiUiRuntime
   private readonly manager: SessionManager
   private readonly sessionId: string
+  private readonly retired: Set<Promise<unknown>>
   private active = true
   private accessRevoked = false
   private session: AgentSession | null = null
@@ -68,6 +69,9 @@ export class L4PiSessionInitialization {
 
   constructor(private readonly options: InitializationOptions) {
     this.sessionId = options.sessionManager.getSessionId()
+    // 只限制同一工作会话的重复尝试，不能因其他会话的插件清理挂起而拒绝加载。
+    this.retired = retiredInitializations.get(options.resources) ?? new Set()
+    retiredInitializations.set(options.resources, this.retired)
     this.ui = options.ui ?? new L4PiUiRuntime()
     this.capabilities = new L4PiCapabilityRuntime(options.readCapabilities)
     this.plugins = new L4PiSessionPluginRuntime({
@@ -116,29 +120,20 @@ export class L4PiSessionInitialization {
   async reload(): Promise<void> {
     this.assertActive()
     const session = await this.start()
-    let failure: Error | null = null
-    this.onLifecycleError = (error) => {
-      failure ??= error
-    }
     this.setStage('重载 Pi 配置')
-    try {
-      await session.reload({
-        beforeSessionStart: async () => {
-          this.assertActive()
-          this.validateResources(
-            session.resourceLoader,
-            session.settingsManager.drainErrors().map(({ error }) => ({
-              type: 'error',
-              message: error.message
-            }))
-          )
-        }
-      })
-      this.assertActive()
-      if (failure) throw failure
-    } finally {
-      this.onLifecycleError = null
-    }
+    await session.reload({
+      beforeSessionStart: async () => {
+        this.assertActive()
+        this.validateResources(
+          session.resourceLoader,
+          session.settingsManager.drainErrors().map(({ error }) => ({
+            type: 'error',
+            message: error.message
+          }))
+        )
+      }
+    })
+    this.assertActive()
   }
 
   setStage(stage: string): void {
@@ -154,11 +149,8 @@ export class L4PiSessionInitialization {
   private async initialize(refreshResources: boolean): Promise<AgentSession> {
     const startedAt = performance.now()
     this.assertActive()
-    if (
-      this.options.mode === 'normal' &&
-      retiredInitializations.size >= MAX_RETIRED_INITIALIZATIONS
-    ) {
-      throw new Error('尚未结束的插件初始化或关闭任务过多，请重启服务后再加载插件')
+    if (this.options.mode === 'normal' && this.retired.size >= MAX_RETIRED_INITIALIZATIONS) {
+      throw new Error('当前会话尚未结束的插件初始化或关闭任务过多，可先使用其他会话')
     }
     const failure = new Promise<never>((_, reject) => {
       this.onLifecycleError = reject
@@ -244,7 +236,7 @@ export class L4PiSessionInitialization {
           )
         : Promise.resolve()
     const cleanup = Promise.allSettled([this.execution, shutdown])
-    retiredInitializations.add(cleanup)
+    this.retired.add(cleanup)
     const timer = setTimeout(() => {
       console.warn('[Pi Desk][PiSession] 旧实例仍在后台清理，不阻塞基础聊天', {
         sessionId: this.sessionId,
@@ -255,7 +247,7 @@ export class L4PiSessionInitialization {
     timer.unref()
     void cleanup.then(() => {
       clearTimeout(timer)
-      retiredInitializations.delete(cleanup)
+      this.retired.delete(cleanup)
     })
   }
 
@@ -271,9 +263,13 @@ export class L4PiSessionInitialization {
     resourceLoader: ResourceLoader,
     diagnostics: AgentSessionServices['diagnostics']
   ): void {
-    const failures = resourceLoader
-      .getExtensions()
-      .errors.map(({ path, error }) => `${error}\n插件入口：${path}`)
+    // Pi 已将失败入口排除；保留局部诊断，不把其余可用扩展一起作废。
+    for (const { path, error } of resourceLoader.getExtensions().errors) {
+      const message = `${error}\n插件入口：${path}`
+      reportL4PiPluginNativeDiagnostic(this.options.cwd, message)
+      console.warn('[Pi Desk][PiSession] 已跳过失败扩展', { cwd: this.options.cwd, message })
+    }
+    const failures: string[] = []
     for (const diagnostic of diagnostics) {
       if (diagnostic.type === 'error') failures.push(diagnostic.message)
       else console.info('[Pi Desk][PiSession] 初始化诊断', { cwd: this.options.cwd, ...diagnostic })
@@ -369,7 +365,7 @@ export class L4PiSessionInitialization {
           sessionId: this.sessionId,
           message: diagnostic
         })
-        this.onLifecycleError?.(new Error(diagnostic))
+        reportL4PiPluginNativeDiagnostic(this.options.cwd, diagnostic)
         if (error.event === 'session_tree' || error.event === 'session_before_tree') {
           this.session?.extensionRunner
             .getUIContext()

package/src/server/l4_foundation/pi/l4-pi-session-resources.ts

@@ -16,7 +16,7 @@ import {
   type SourceInfo
 } from '@earendil-works/pi-coding-agent'
 import { clearL4PiPluginCodeCache, loadL4PiDeskPluginEntry } from './l4-pi-plugin-module-loader'
-import { runL4PiPackageRootExclusive } from './l4-pi-package-root-gate'
+import { reportL4PiPluginNativeDiagnostic } from './l4-pi-plugin-native-diagnostic'
 import { createL4PiPluginDisabledFilter } from './l4-pi-plugin-disabled'
 
 type LoaderOptions = ConstructorParameters<typeof DefaultResourceLoader>[0]
@@ -93,15 +93,8 @@ export class L4PiSessionResources {
       onProgress?.('等待已选择的插件资源准备完成')
       return this.selection
     }
-    onProgress?.(`等待插件资源队列\n工作目录：${cwd}`)
-    const queuedAt = performance.now()
-    this.selection = runL4PiPackageRootExclusive(() => {
-      const durationMs = Math.round(performance.now() - queuedAt)
-      if (durationMs >= 1000) {
-        console.info('[Pi Desk][PluginResources] 插件资源队列等待结束', { cwd, durationMs })
-      }
-      return this.discover(cwd, agentDir, settings, onProgress)
-    })
+    // 维护允许暂时缺包；只读发现不能排在 npm 网络操作后面。
+    this.selection = this.discover(cwd, agentDir, settings, onProgress)
     return this.selection
   }
 
@@ -122,7 +115,10 @@ export class L4PiSessionResources {
     })
     const paths = await runLoadStage('发现已配置的插件与资源', onProgress, () =>
       manager.resolve(async (source) => {
-        throw new Error(`插件包未安装：${source}`)
+        const message = `插件包未安装或版本不匹配，已跳过：${source}`
+        reportL4PiPluginNativeDiagnostic(cwd, message)
+        console.warn('[Pi Desk][PluginResources]', { cwd, message })
+        return 'skip'
       })
     )
     const disabled = await createL4PiPluginDisabledFilter(agentDir, manager, settings)
@@ -307,25 +303,30 @@ export class L4PiSessionResources {
       }
     })
     const runtime = resourceLoader.getExtensions().runtime
+    const reportProviderError = (extensionPath: string, cause: unknown): void => {
+      const message = `${extensionPath}: ${String(cause)}`
+      reportL4PiPluginNativeDiagnostic(cwd, message)
+      diagnostics.push({ type: 'warning', message })
+    }
     for (const { name, config, extensionPath } of runtime.pendingProviderRegistrations) {
       try {
         modelRuntime.registerProvider(name, config)
       } catch (cause) {
-        diagnostics.push({ type: 'error', message: `${extensionPath}: ${String(cause)}` })
+        reportProviderError(extensionPath, cause)
       }
     }
     for (const { provider, extensionPath } of runtime.pendingNativeProviderRegistrations) {
       try {
         modelRuntime.registerNativeProvider(provider)
       } catch (cause) {
-        diagnostics.push({ type: 'error', message: `${extensionPath}: ${String(cause)}` })
+        reportProviderError(extensionPath, cause)
       }
     }
     for (const { definition, extensionPath } of runtime.pendingVirtualModelRegistrations) {
       try {
         modelRuntime.registerVirtualModel(definition)
       } catch (cause) {
-        diagnostics.push({ type: 'error', message: `${extensionPath}: ${String(cause)}` })
+        reportProviderError(extensionPath, cause)
       }
     }
     runtime.pendingProviderRegistrations = []

package/src/server/l4_foundation/pi/l4-pi-work-session-runtime.ts

@@ -215,7 +215,7 @@ export class L4PiWorkSessionRuntime {
 
   async readChatRuntime(): Promise<L4PiChatRuntimeSnapshot> {
     this.assertActive()
-    return this.chatWorker.getRuntime()
+    return this.chatWorker.getRuntime(false)
   }
 
   async readModelContext(): Promise<L4PiModelContext> {