dsh-vscode-mode 0.14.3 → 0.14.4

package/src/mcp.ts

@@ -13,6 +13,49 @@ import {
 import type { MpcConfig, MpcServer, MpcTool } from './shared/mcp.js'
 import type { Ctx } from './store.js'
 import { checkMcpName } from './mcpProject.js'
+import { runtimeOf } from './mcpRuntime.js'
+
+/**
+ * Compare the official tool-name namespaces without guessing the longest prefix.
+ * @public @author ddj 2026年10月08号
+ * @param left First server name.
+ * @param right Second server name.
+ * @returns Whether distinct names generate overlapping public tool names.
+ */
+export function nameOverlap(left: string, right: string): boolean {
+  return left !== right && (left.startsWith(right + '__') || right.startsWith(left + '__'))
+}
+
+/**
+ * Collect known global and project namespaces without opening connections.
+ * @public @author ddj 2026年10月08号
+ * @param ctx Host context.
+ * @returns Distinct server names used for fail-closed attribution.
+ */
+export function mcpNames(ctx: Ctx): Set<string> {
+  const names = new Set(runtimeOf(ctx).owners().keys())
+  for (const entry of entriesOf(ctx)) {
+    const name = entry.options?.config?.serverName
+    if (typeof name === 'string') names.add(name)
+  }
+  return names
+}
+
+const edits = new WeakMap<object, Promise<unknown>>()
+
+/**
+ * Serialize profile/project edits together to preserve files and cross-scope name reservations.
+ * @public @author ddj 2026年10月08号
+ * @param ctx Host owner.
+ * @param action Validated configuration operation.
+ * @returns Operation result; a rejection never poisons the next edit.
+ */
+export function mcpEdit<T>(ctx: Ctx, action: () => Promise<T>): Promise<T> {
+  const owner = ctx.root ?? ctx
+  const next = (edits.get(owner) ?? Promise.resolve()).then(action, action)
+  edits.set(owner, next)
+  return next
+}
 
 export { LEGACY_PROJECT_PREFIX, MCP_PACKAGE, PROJECT_ENTRY_PREFIX, isProjectEntryId }
 
@@ -46,7 +89,11 @@ export function toolsOf(ctx: Ctx, serverName: string, agent?: any): MpcTool[] {
   const visible = view?.visible
   if (!(visible instanceof Map)) return []
   const prefix = `mcp__${serverName}__`
-  return [...visible.entries()].filter(([name]) => String(name).startsWith(prefix)).map(([name, definition]) => ({
+  const namespaces = mcpNames(ctx)
+  namespaces.add(serverName)
+  const belongs = (name: string) => name.startsWith(prefix)
+    && [...namespaces].filter((server) => name.startsWith('mcp__' + server + '__')).length === 1
+  return [...visible.entries()].filter(([name]) => belongs(String(name))).map(([name, definition]) => ({
     name: String(name).slice(prefix.length),
     description: typeof definition?.description === 'string' ? definition.description : undefined,
   }))
@@ -76,6 +123,20 @@ export function mergeSecrets(next: Record<string, unknown>, previous: Record<str
   return merged
 }
 
+/**
+ * Merge editable transport fields while retaining advanced settings and secret values.
+ * @public @author ddj 2026年10月08号
+ * @param previous Last saved configuration.
+ * @param config Submitted transport configuration.
+ * @returns Detached configuration without fields belonging to the old transport.
+ */
+export function mergeMcp(previous: Record<string, unknown>, config: MpcConfig): Record<string, unknown> {
+  const next = mergeSecrets({ ...previous, ...config }, previous)
+  const stale = config.transport === 'stdio' ? ['url', 'headers'] : ['command', 'args', 'cwd', 'env']
+  for (const key of stale) delete next[key]
+  return next
+}
+
 /**
  * Summarize a global entry without treating plugin activation as a successful handshake.
  * @public @author ddj 2026年09月28号
@@ -103,11 +164,40 @@ export function serverOf(ctx: Ctx, entry: any): MpcServer {
   }
 }
 
-/** 校验 MCP 配置。 */
+/**
+ * Validate transport fields before any loader or source mutation.
+ * @public @author ddj 2026年10月08号
+ * @param config Submitted configuration.
+ * @throws Error for unsupported transport or malformed endpoint/arguments/maps.
+ */
 export function validateConfig(config: MpcConfig): void {
-  if (!/^[A-Za-z0-9_-]{1,32}$/.test(config.serverName)) throw new Error('serverName 只能包含字母、数字、下划线和连字符（最多 32 位）')
-  if (config.transport === 'stdio' && !config.command?.trim()) throw new Error('stdio MCP 必须填写 command')
-  if (config.transport === 'streamable-http' && !/^https?:\/\//.test(config.url ?? '')) throw new Error('HTTP MCP 必须填写 http(s) URL')
+  if (!config || typeof config !== 'object') throw new Error('MCP 配置必须是对象')
+  if (typeof config.serverName !== 'string' || !/^[A-Za-z0-9_-]{1,32}$/.test(config.serverName)) throw new Error('serverName 只能包含字母、数字、下划线和连字符（最多 32 位）')
+  if (!['stdio', 'streamable-http'].includes(config.transport)) throw new Error('不支持的 MCP transport')
+  if (config.transport === 'stdio') {
+    if (typeof config.command !== 'string' || !config.command.trim()) throw new Error('stdio MCP 必须填写 command')
+    if (config.args !== undefined && (!Array.isArray(config.args) || config.args.some((arg) => typeof arg !== 'string'))) throw new Error('MCP args 必须是字符串数组')
+    if (config.cwd !== undefined && typeof config.cwd !== 'string') throw new Error('MCP cwd 必须是字符串')
+    validatePairs(config.env, 'env')
+  } else {
+    let url: URL
+    try { url = new URL(config.url ?? '') } catch { throw new Error('HTTP MCP 必须填写有效 http(s) URL') }
+    if (!['http:', 'https:'].includes(url.protocol) || !url.hostname || url.username || url.password) throw new Error('HTTP MCP 必须填写有效 http(s) URL，凭据请使用请求头')
+    validatePairs(config.headers, 'headers')
+  }
+}
+
+/**
+ * Validate an optional string-valued map without coercing malformed input.
+ * @private @author ddj 2026年10月08号
+ * @param values Submitted map.
+ * @param field Field used in the diagnostic.
+ * @throws Error for non-object or non-string values.
+ */
+function validatePairs(values: unknown, field: string): void {
+  if (values === undefined) return
+  if (!values || typeof values !== 'object' || Array.isArray(values)
+    || Object.entries(values).some(([key, value]) => !key || typeof value !== 'string')) throw new Error('MCP ' + field + ' 必须是字符串字典')
 }
 
 /** 列出全局（profile）MCP 服务，过滤掉新旧格式的项目级条目。 */
@@ -123,13 +213,18 @@ export function listMcp(ctx: Ctx): { servers: MpcServer[] } {
  * @returns Masked server status; project name collisions reject before writing.
  */
 export async function saveMcp(ctx: Ctx, config: MpcConfig): Promise<MpcServer> {
+  return mcpEdit(ctx, () => saveGlobal(ctx, config))
+}
+
+/** @private @author ddj 2026年10月08号 @param ctx Host services. @param config Configuration. @returns Saved status; validation failures do not write. */
+async function saveGlobal(ctx: Ctx, config: MpcConfig): Promise<MpcServer> {
   validateConfig(config)
   await checkMcpName(ctx, config.serverName)
   const loader = ctx.get('loader')
   if (!loader) throw new Error('缺少 loader 服务')
   const existing = entriesOf(ctx).find((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? '')) && entry.options?.config?.serverName === config.serverName)
   const previous = existing?.options?.config ?? {}
-  const next = mergeSecrets({ ...previous, ...config }, previous)
+  const next = mergeMcp(previous, config)
   if (existing) {
     await loader.update(existing.id, { config: next })
     return serverOf(ctx, loader.resolve(existing.id))
@@ -138,33 +233,46 @@ export async function saveMcp(ctx: Ctx, config: MpcConfig): Promise<MpcServer> {
   return serverOf(ctx, loader.resolve(id))
 }
 
-/** 删除 MCP 服务。 */
-export async function removeMcp(ctx: Ctx, id: string): Promise<void> {
+/** @private @author ddj 2026年10月08号 @param ctx Host services. @param id Global identity. @returns Loader and verified global entry. @throws Missing service, entry or wrong scope. */
+function globalEntry(ctx: Ctx, id: string): { loader: any; entry: any } {
   const loader = ctx.get('loader')
   if (!loader) throw new Error('缺少 loader 服务')
   const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id)
   if (!entry) throw new Error('MCP 服务不存在')
-  await loader.remove(entry.id)
+  if (isProjectEntryId(String(entry.id ?? entry.options?.id ?? ''))) throw new Error('项目 MCP 必须通过项目入口操作')
+  return { loader, entry }
+}
+
+/** @public @author ddj 2026年10月08号 @param ctx Host services. @param id Global identity. @returns Persisted removal, serialized with all settings writes. */
+export async function removeMcp(ctx: Ctx, id: string): Promise<void> {
+  /** @private @author ddj 2026年10月08号 @returns Loader removal after scope validation. */
+  const remove = async () => {
+    const { loader, entry } = globalEntry(ctx, id)
+    await loader.remove(entry.id)
+  }
+  return mcpEdit(ctx, remove)
 }
 
-/** 切换 MCP 服务启用状态。 */
+/** @public @author ddj 2026年10月08号 @param ctx Host services. @param id Global identity. @param enabled Desired state. @returns Persisted status after serialized toggle. */
 export async function toggleMcp(ctx: Ctx, id: string, enabled: boolean): Promise<MpcServer> {
-  const loader = ctx.get('loader')
-  if (!loader) throw new Error('缺少 loader 服务')
-  const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id)
-  if (!entry) throw new Error('MCP 服务不存在')
-  await loader.update(entry.id, { disabled: !enabled })
-  return serverOf(ctx, loader.resolve(entry.id))
+  /** @private @author ddj 2026年10月08号 @returns Loader status after toggle. */
+  const toggle = async () => {
+    const { loader, entry } = globalEntry(ctx, id)
+    await loader.update(entry.id, { disabled: !enabled })
+    return serverOf(ctx, loader.resolve(entry.id))
+  }
+  return mcpEdit(ctx, toggle)
 }
 
-/** 重新加载 MCP 服务。 */
+/** @public @author ddj 2026年10月08号 @param ctx Host services. @param id Global identity. @returns Loader status after serialized refresh. */
 export async function refreshMcp(ctx: Ctx, id: string): Promise<MpcServer> {
-  const loader = ctx.get('loader')
-  if (!loader) throw new Error('缺少 loader 服务')
-  const entry = entriesOf(ctx).find((candidate) => String(candidate.id) === id)
-  if (!entry) throw new Error('MCP 服务不存在')
-  await loader.update(entry.id, { config: { ...(entry.options?.config ?? {}) } })
-  return serverOf(ctx, loader.resolve(entry.id))
+  /** @private @author ddj 2026年10月08号 @returns Loader status after refresh. */
+  const refresh = async () => {
+    const { loader, entry } = globalEntry(ctx, id)
+    await loader.update(entry.id, { config: { ...(entry.options?.config ?? {}) } })
+    return serverOf(ctx, loader.resolve(entry.id))
+  }
+  return mcpEdit(ctx, refresh)
 }
 
 export type { MpcConfig, MpcServer }

package/src/mcpIsolation.ts

@@ -1,7 +1,7 @@
 /** Project MCP visibility, instruction shadows, and execution guards. @author ddj 2026年09月28号 */
 import { posix, win32 } from 'node:path'
 import { LEGACY_PROJECT_PREFIX, entryHash, isProjectEntryId } from './compat.js'
-import { entriesOf } from './mcp.js'
+import { entriesOf, mcpNames } from './mcp.js'
 import { hashWorkspace } from './mcpProject.js'
 import { runtimeOf } from './mcpRuntime.js'
 import type { Ctx } from './store.js'
@@ -101,6 +101,7 @@ export function guardMcp(ctx: Ctx, exec: any): string | undefined {
   const server = callServer(exec)
   const owners = serverOwners(ctx)
   const current = runtimeOf(ctx).workspace(exec.agent)
+  if (!RESOURCE_TOOLS.has(name) && [...mcpNames(ctx)].filter((key) => name.startsWith('mcp__' + key + '__')).length > 1) return '已拒绝：MCP 命名空间冲突，无法确认工具归属'
   const owned = RESOURCE_TOOLS.has(name) ? [...owners].filter(([key]) => key === server)
     : [...owners].filter(([key]) => name.startsWith('mcp__' + key + '__'))
   if (!owned.some(([, owner]) => owner !== current)) return undefined

package/src/mcpProject.ts

@@ -1,6 +1,7 @@
 /** Project MCP configuration; .mcp.json is the source of truth. @author ddj 2026年09月28号 */
 import { createHash } from 'node:crypto'
-import { PROJECT_ENTRY_PREFIX, entriesOf, mergeSecrets, validateConfig } from './mcp.js'
+import { PROJECT_ENTRY_PREFIX, entriesOf, mergeMcp, validateConfig, nameOverlap, listMcp, mcpEdit } from './mcp.js'
+
 import { isProjectEntryId } from './compat.js'
 import { clearLegacy, runtimeOf } from './mcpRuntime.js'
 import type { ProjectDef } from './mcpRuntime.js'
@@ -8,6 +9,7 @@ import type { MpcConfig, MpcProject, MpcServer } from './shared/mcp.js'
 import type { Ctx } from './store.js'
 
 const FILE_NAME = '.mcp.json'
+const projectStates = new WeakMap<object, Map<string, { fileError?: string; missingDir?: boolean }>>()
 
 /**
  * Require an exact registered workspace before any project file mutation.
@@ -54,7 +56,18 @@ export function projectEntryId(workspacePath: string, serverName: string): strin
 }
 
 /**
- * Read the complete source document; only ENOENT denotes an absent configuration.
+ * Identify an absent target using official host and legacy Node filesystem codes.
+ * @private @author ddj 2026年10月08号
+ * @param error Filesystem failure; messages and class identity are not authoritative.
+ * @returns Whether the backend explicitly reports a missing target.
+ */
+function isMissingFile(error: unknown): boolean {
+  const code = (error as { code?: unknown } | null)?.code
+  return code === 'FS_NOT_FOUND' || code === 'ENOENT'
+}
+
+/**
+ * Read the complete source document; only missing-target codes denote an absent configuration.
  * @private @author ddj 2026年09月28号
  * @param ctx Host filesystem.
  * @param workspacePath Registered workspace path.
@@ -68,7 +81,7 @@ async function readProjectJson(ctx: Ctx, workspacePath: string): Promise<Record<
   try {
     text = await fs.readText(target)
   } catch (error) {
-    if ((error as { code?: string })?.code === 'ENOENT') return {}
+    if (isMissingFile(error)) return {}
     throw new Error('.mcp.json 读取失败：' + String(error))
   }
   let data: unknown
@@ -108,7 +121,14 @@ export function serversOf(data: Record<string, unknown>): Record<string, Record<
  */
 export function configFromDef(def: Record<string, unknown> | undefined, serverName: string): MpcConfig | null {
   if (!def) return null
-  const transport = typeof def.url === 'string' ? 'streamable-http' : 'stdio'
+  if (def.transport !== undefined && !['stdio', 'streamable-http'].includes(def.transport as string)) throw new Error('不支持的 MCP transport：' + serverName)
+  if (def.args !== undefined && (!Array.isArray(def.args) || def.args.some((arg) => typeof arg !== 'string'))) throw new Error('MCP args 必须是字符串数组：' + serverName)
+  for (const field of ['env', 'headers']) {
+    const values = def[field]
+    if (values !== undefined && (!values || typeof values !== 'object' || Array.isArray(values)
+      || Object.values(values).some((value) => value === null || !['string', 'number', 'boolean'].includes(typeof value)))) throw new Error('MCP ' + field + ' 必须是标量字典：' + serverName)
+  }
+  const transport = def.transport as MpcConfig['transport'] | undefined ?? (typeof def.url === 'string' ? 'streamable-http' : 'stdio')
   const config: MpcConfig = { serverName, transport }
   if (transport === 'stdio') {
     config.command = typeof def.command === 'string' ? def.command : ''
@@ -150,16 +170,19 @@ async function writeProjectJson(ctx: Ctx, workspacePath: string, data: Record<st
  * @returns Completion; throws on collision or an unreadable competing source document.
  */
 export async function checkMcpName(ctx: Ctx, serverName: string, workspacePath?: string): Promise<void> {
-  const conflict = 'serverName "' + serverName + '" 已被另一个 MCP 使用（全局或其他项目），请换一个名称'
+  /** @private @author ddj 2026年10月08号 @param other Existing name. @param sameOwner Whether updates share ownership. @throws Error for ambiguous namespaces. */
+  const checkName = (other: string, sameOwner: boolean): void => {
+    if (nameOverlap(serverName, other)) throw new Error('MCP 命名空间冲突：' + serverName + ' / ' + other + '，请避免 __ 前缀交叠')
+    if (other === serverName && !sameOwner) throw new Error('serverName "' + serverName + '" 已被另一个 MCP 使用（全局或其他项目），请换一个名称')
+  }
   for (const entry of entriesOf(ctx)) {
-    const project = isProjectEntryId(String(entry.id ?? entry.options?.id ?? ''))
-    if (project || workspacePath === undefined) continue
-    if (entry.options?.config?.serverName === serverName) throw new Error(conflict)
+    if (isProjectEntryId(String(entry.id ?? entry.options?.id ?? ''))) continue
+    const name = entry.options?.config?.serverName
+    if (typeof name === 'string') checkName(name, workspacePath === undefined)
   }
   for (const ws of ctx.get('workspaceRegistry')?.list?.() ?? []) {
-    if (ws.path === workspacePath) continue
     const servers = serversOf(await readProjectJson(ctx, ws.path))
-    if (Object.hasOwn(servers, serverName)) throw new Error(conflict)
+    for (const name of Object.keys(servers)) checkName(name, ws.path === workspacePath)
   }
 }
 
@@ -232,9 +255,13 @@ async function projectOf(ctx: Ctx, workspacePath: string, title: string): Promis
     missingDir = !info || info.type !== 'directory'
     if (!missingDir) await reconcileProject(ctx, workspacePath)
   } catch (error) {
-    missingDir = (error as { code?: string })?.code === 'ENOENT' || undefined
+    missingDir = isMissingFile(error) || undefined
     fileError = String(error)
   }
+  const owner = ctx.root ?? ctx
+  const states = projectStates.get(owner) ?? new Map()
+  states.set(workspacePath, { missingDir, fileError })
+  projectStates.set(owner, states)
   return { workspacePath, title, servers: runtimeOf(ctx).views(workspacePath), source: 'project', missingDir, fileError }
 }
 
@@ -250,6 +277,21 @@ export async function listProjects(ctx: Ctx): Promise<{ projects: MpcProject[] }
   return { projects }
 }
 
+/**
+ * Read the current ledger only; polling never reconciles files or starts connections.
+ * @public @author ddj 2026年10月08号
+ * @param ctx Host services.
+ * @returns Masked global/project snapshots with last configuration diagnostics.
+ */
+export function mcpSnapshot(ctx: Ctx): { servers: MpcServer[]; projects: MpcProject[] } {
+  const states = projectStates.get(ctx.root ?? ctx)
+  const projects: MpcProject[] = (ctx.get('workspaceRegistry')?.list?.() ?? []).map((ws: { path: string; title?: string }) => ({
+    workspacePath: ws.path, title: ws.title ?? '', source: 'project' as const,
+    servers: runtimeOf(ctx).views(ws.path), ...states?.get(ws.path),
+  }))
+  return { ...listMcp(ctx), projects }
+}
+
 /**
  * Merge editable fields while retaining advanced fields and unchanged masked credentials.
  * @private @author ddj 2026年09月28号
@@ -258,12 +300,10 @@ export async function listProjects(ctx: Ctx): Promise<{ projects: MpcProject[] }
  * @returns Enabled source definition without runtime-only keys or stale transport fields.
  */
 function mergeDefinition(previous: Record<string, unknown>, config: MpcConfig): Record<string, unknown> {
-  const next = mergeSecrets({ ...previous, ...config }, previous)
+  const next = mergeMcp(previous, config)
   delete next.serverName
   delete next.transport
   delete next.disabled
-  const stale = config.transport === 'stdio' ? ['url', 'headers'] : ['command', 'args', 'cwd', 'env']
-  for (const key of stale) delete next[key]
   return next
 }
 
@@ -277,6 +317,11 @@ function mergeDefinition(previous: Record<string, unknown>, config: MpcConfig):
  * @returns Updated project view; invalid sources or conflicts reject before writing.
  */
 export async function projectSave(ctx: Ctx, workspacePath: string, serverName: string, config: MpcConfig): Promise<MpcProject> {
+  return mcpEdit(ctx, () => saveProject(ctx, workspacePath, serverName, config))
+}
+
+/** @private @author ddj 2026年10月08号 @param ctx Host services. @param workspacePath Owner. @param serverName Namespace. @param config Editable fields. @returns Persisted project status. */
+async function saveProject(ctx: Ctx, workspacePath: string, serverName: string, config: MpcConfig): Promise<MpcProject> {
   const workspace = requireWorkspace(ctx, workspacePath)
   validateConfig({ ...config, serverName })
   await checkMcpName(ctx, serverName, workspacePath)
@@ -297,6 +342,11 @@ export async function projectSave(ctx: Ctx, workspacePath: string, serverName: s
  * @returns Updated project view; write failures leave active configuration intact.
  */
 export async function projectRemove(ctx: Ctx, workspacePath: string, serverName: string): Promise<MpcProject> {
+  return mcpEdit(ctx, () => removeProject(ctx, workspacePath, serverName))
+}
+
+/** @private @author ddj 2026年10月08号 @param ctx Host services. @param workspacePath Owner. @param serverName Namespace. @returns Project after persisted removal. */
+async function removeProject(ctx: Ctx, workspacePath: string, serverName: string): Promise<MpcProject> {
   const workspace = requireWorkspace(ctx, workspacePath)
   const data = await readProjectJson(ctx, workspacePath)
   const servers = serversOf(data)
@@ -316,6 +366,11 @@ export async function projectRemove(ctx: Ctx, workspacePath: string, serverName:
  * @returns Updated project view, including retained disabled definitions.
  */
 export async function projectToggle(ctx: Ctx, workspacePath: string, serverName: string, enabled: boolean): Promise<MpcProject> {
+  return mcpEdit(ctx, () => toggleProject(ctx, workspacePath, serverName, enabled))
+}
+
+/** @private @author ddj 2026年10月08号 @param ctx Host services. @param workspacePath Owner. @param serverName Namespace. @param enabled Desired state. @returns Project after persisted toggle. */
+async function toggleProject(ctx: Ctx, workspacePath: string, serverName: string, enabled: boolean): Promise<MpcProject> {
   const workspace = requireWorkspace(ctx, workspacePath)
   const data = await readProjectJson(ctx, workspacePath)
   const servers = serversOf(data)
@@ -337,6 +392,11 @@ export async function projectToggle(ctx: Ctx, workspacePath: string, serverName:
  * @returns Updated project view; disabled or idle definitions stay connection-free.
  */
 export async function projectRefresh(ctx: Ctx, workspacePath: string, serverName: string): Promise<MpcProject> {
+  return mcpEdit(ctx, () => refreshProject(ctx, workspacePath, serverName))
+}
+
+/** @private @author ddj 2026年10月08号 @param ctx Host services. @param workspacePath Owner. @param serverName Namespace. @returns Refreshed project status without racing edits. */
+async function refreshProject(ctx: Ctx, workspacePath: string, serverName: string): Promise<MpcProject> {
   const workspace = requireWorkspace(ctx, workspacePath)
   const data = await readProjectJson(ctx, workspacePath)
   if (!Object.hasOwn(serversOf(data), serverName)) throw new Error('项目中不存在该 MCP')

package/src/mcpRuntime.ts

@@ -114,7 +114,7 @@ export class McpRuntime {
     const update = async () => {
       this.projects.set(path, defs)
       this.changed()
-      for (const [agent, record] of this.agents) await this.syncAgent(agent, record, refresh)
+      for (const [agent, record] of this.agents) await this.syncAgent(agent, record, this.workspace(agent) === path ? refresh : undefined)
       this.changed()
     }
     return this.enqueue(update)
@@ -196,7 +196,7 @@ export class McpRuntime {
     const defs = this.projects.get(path ?? '') ?? new Map<string, ProjectDef>()
     for (const [name, instance] of record.instances) {
       const def = defs.get(name)
-      if (def?.enabled && instance.key === JSON.stringify(def.config) && name !== refresh) continue
+      if (def?.enabled && instance.path === path && instance.key === JSON.stringify(def.config) && name !== refresh) continue
       await this.stopOne(record, name)
     }
     for (const [name, def] of defs) {
@@ -206,6 +206,21 @@ export class McpRuntime {
     }
   }
 
+  /**
+   * Cache successful module loads while allowing explicit refresh after transient failures.
+   * @private @author ddj 2026年10月08号
+   * @returns Official plugin module; load failures propagate to the instance diagnostic.
+   */
+  private async getModule(): Promise<any> {
+    const loading = this.module ??= this.load()
+    try {
+      return await loading
+    } catch (error) {
+      if (this.module === loading) this.module = undefined
+      throw error
+    }
+  }
+
   /**
    * Mount the official plugin through agent.ctx; ACTIVE is not connection evidence.
    * @private @author ddj 2026年09月28号
@@ -219,7 +234,7 @@ export class McpRuntime {
     const instance: Instance = { key: JSON.stringify(config), path }
     record.instances.set(config.serverName, instance)
     try {
-      const officialMcp = await (this.module ??= this.load())
+      const officialMcp = await this.getModule()
       if (!record.live || this.stopped) return
       const global = entriesOf(this.ctx).find((entry) => !isProjectEntryId(String(entry.id ?? entry.options?.id ?? '')) && entry.options?.config?.serverName === config.serverName)
       if (global) throw new Error('serverName 已被全局 MCP 使用：' + config.serverName)

package/src/rpc.ts

@@ -33,7 +33,7 @@ import { restoreFile, revertCall, revertHunk, revertHunks, type Result } from '.
 import { rulesList, rulesRead, rulesRemove, rulesSave, rulesToggle } from './rules.js'
 import { isSnippetFilePath, snippetsEntries, snippetsList, snippetsRead, snippetsRemove, snippetsSave } from './snippets.js'
 import { listMcp, refreshMcp, removeMcp, saveMcp, toggleMcp } from './mcp.js'
-import { listProjects, projectRefresh, projectRemove, projectSave, projectToggle } from './mcpProject.js'
+import { listProjects, projectRefresh, projectRemove, projectSave, projectToggle, mcpSnapshot } from './mcpProject.js'
 import { normalizeFileOpenTool, FILE_OPEN_DEFAULT, FILE_OPEN_SETTINGS_NS, sectionOf, updateSection } from './fileOpenSettings.js'
 import { INTEGRATION_BASE_DEFAULT } from './shared/integration.js'
 import { shellMenuRegister, shellMenuRemove, shellMenuStatus } from './integrate.js'
@@ -1165,6 +1165,7 @@ export function buildHandlers(
       return { ok: true, from: r.from, to: r.to }
     },
     'mcp.list': async () => ({ ok: true, ...listMcp(ctx) }),
+    'mcp.snapshot': async () => ({ ok: true, ...mcpSnapshot(ctx) }),
     'mcp.save': async (args) => {
       try { return { ok: true, server: await saveMcp(ctx, args.config) } }
       catch (error) { return { ok: false, error: String(error) } }

package/src/shared/mcpStatus.ts

@@ -0,0 +1,30 @@
+import type { MpcServer } from './mcp.js'
+
+type ServerStatus = Pick<MpcServer, 'enabled' | 'status'>
+export type McpTone = 'connected' | 'connecting' | 'disabled' | 'error' | 'neutral'
+
+/**
+ * @public
+ * @author ddj 2026年10月08号
+ * @description Display lifecycle evidence; enabled only expresses configuration intent, not connectivity.
+ * @param server Server lifecycle snapshot.
+ * @returns User-facing status label.
+ */
+export function statusOf(server: ServerStatus): string {
+  if (!server.enabled || server.status === 'disabled') return '已禁用'
+  const labels = { connected: '在线', connecting: '装配中', configured: '已配置，等待会话', unverified: '已加载，连接未确认', error: '错误' }
+  return labels[server.status] ?? '状态未知'
+}
+
+/**
+ * @public
+ * @author ddj 2026年10月08号
+ * @description Use neutral styling unless lifecycle evidence explicitly identifies online, loading or error.
+ * @param server Server lifecycle snapshot.
+ * @returns CSS tone, independent of configuration-enabled state.
+ */
+export function statusTone(server: ServerStatus): McpTone {
+  if (!server.enabled || server.status === 'disabled') return 'disabled'
+  if (server.status === 'connected' || server.status === 'connecting' || server.status === 'error') return server.status
+  return 'neutral'
+}

package/src/shared/rpc.ts

@@ -386,6 +386,7 @@ export interface RpcRequestMap {
   'edrv.fsCopy': { sessionId?: string; from: string; toDir: string }
   'edrv.fsMove': { sessionId?: string; from: string; toDir: string }
   'mcp.list': {}
+  'mcp.snapshot': {}
   'mcp.save': { config: MpcConfig }
   'mcp.remove': { id: string }
   'mcp.toggle': { id: string; enabled: boolean }
@@ -545,6 +546,7 @@ export interface RpcOkMap {
   'edrv.fsCopy': { from: string; to: string }
   'edrv.fsMove': { from: string; to: string }
   'mcp.list': { servers: MpcServer[] }
+  'mcp.snapshot': { servers: MpcServer[]; projects: MpcProject[] }
   'mcp.save': { server: MpcServer }
   'mcp.remove': object
   'mcp.toggle': { server: MpcServer }