refactor: 插件类型改为名称后缀 _ui 推断，新增市场数据缓存

yuWorm · yuWorm · commit 2f7df798d01e · 2026-03-21T20:54:45.000+08:00
- 插件类型判断从配置 type 字段改为按名称后缀 _ui 推断（web/server）
- 创建前端插件时自动追加 _ui 后缀并提示用户
- 插件市场数据新增本地缓存，网络失败时自动回退
- 移除未使用的 searchPlugins/filterByTag 导出
- 修复 create 流程中 config.database 潜在的 undefined 崩溃

Made-with: Cursor
diff --git a/src/commands/plugin/add.ts b/src/commands/plugin/add.ts
@@ -1,11 +1,13 @@
 // plugin/add.ts — 插件添加
 import * as clack from '@clack/prompts'
 import chalk from 'chalk'
+import { basename } from 'path'
 import { t } from '../../lib/i18n.js'
 import { requireProjectDir, fatal } from '../../lib/errors.js'
-import { fetchPluginMarketData, searchPlugins, filterByType } from '../../lib/plugin-market.js'
+import { fetchPluginMarketData, filterByType, getMarketPluginType } from '../../lib/plugin-market.js'
 import { installFromMarket, installFrontendPlugin, installBackendPlugin, runPnpmInstall } from '../../lib/plugin-install.js'
 import type { PluginData } from '../../types/plugin.js'
+import { inferPluginType } from '../../types/plugin.js'
 
 /**
  * fba plugin add — 添加插件
@@ -73,12 +75,18 @@ export async function pluginMarketFlow(projectDir: string) {
 
   let plugins: PluginData[]
   try {
-    plugins = await fetchPluginMarketData()
+    const result = await fetchPluginMarketData()
+    plugins = result.data
+    if (result.fromCache) {
+      loadSpinner.stop(`${t('pluginMarketTitle')} (${plugins.length} ${t('pluginCount')})`)
+      clack.log.warn(chalk.yellow(t('pluginMarketCacheUsed')))
+    } else {
+      loadSpinner.stop(`${t('pluginMarketTitle')} (${plugins.length} ${t('pluginCount')})`)
+    }
   } catch (e: any) {
     loadSpinner.stop(chalk.red(`${t('pluginLoadFailed')}: ${e.message}`))
     return
   }
-  loadSpinner.stop(`${t('pluginMarketTitle')} (${plugins.length} ${t('pluginCount')})`)
 
   // 类型过滤
   const typeFilter = await clack.select({
@@ -99,7 +107,7 @@ export async function pluginMarketFlow(projectDir: string) {
     options: filtered.map((p, i) => ({
       value: i,
       label: `${p.plugin.summary}`,
-      hint: `v${p.plugin.version} | ${p.plugin.type} | @${p.plugin.author}`,
+      hint: `v${p.plugin.version} | ${getMarketPluginType(p)} | @${p.plugin.author}`,
     })),
     required: false,
   })
@@ -111,18 +119,18 @@ export async function pluginMarketFlow(projectDir: string) {
 
   // 安装
   clack.log.step(t('pluginInstalling'))
-  const result = await installFromMarket(projectDir, selectedPlugins)
+  const installResult = await installFromMarket(projectDir, selectedPlugins)
 
-  for (const name of result.success) {
+  for (const name of installResult.success) {
     clack.log.success(chalk.green(`✓ ${name}`))
   }
-  for (const name of result.failed) {
+  for (const name of installResult.failed) {
     clack.log.error(chalk.red(`✗ ${name}`))
   }
 
   // 如果安装了前端插件，询问 pnpm install
-  const hasWebPlugins = selectedPlugins.some(p => p?.plugin.type === 'web')
-  if (hasWebPlugins && result.success.length > 0) {
+  const hasWebPlugins = selectedPlugins.some(p => getMarketPluginType(p) === 'web')
+  if (hasWebPlugins && installResult.success.length > 0) {
     const doPnpm = await clack.confirm({ message: t('pluginPnpmInstall') })
     if (!clack.isCancel(doPnpm) && doPnpm) {
       await runPnpmInstall(projectDir)
diff --git a/src/commands/plugin/create.ts b/src/commands/plugin/create.ts
@@ -8,7 +8,7 @@ import { requireProjectDir } from '../../lib/errors.js'
 import { getFrontendPluginDir, getBackendPluginDir } from '../../lib/config.js'
 import { renderTemplate, type TemplateVars } from '../../lib/template.js'
 import { gitInit } from '../../lib/git.js'
-import { VALID_TAGS, VALID_DATABASES, type ServerPluginLevel } from '../../types/plugin.js'
+import { VALID_TAGS, VALID_DATABASES, type ServerPluginLevel, ensureWebPluginName } from '../../types/plugin.js'
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml'
 import { readFileSync, writeFileSync } from 'fs'
 
@@ -61,30 +61,40 @@ export async function pluginCreateAction(options: { project?: string }) {
     }),
   }, { onCancel: () => process.exit(0) })
 
-  const vars: TemplateVars = {
-    name: config.name,
-    summary: config.summary,
-    version: config.version,
-    description: config.description,
-    author: config.author,
-  }
-
   const typesToCreate: Array<'web' | 'server'> = config.type === 'all'
     ? ['web', 'server']
     : [config.type as 'web' | 'server']
 
   for (const pluginType of typesToCreate) {
+    // 前端插件必须以 _ui 结尾
+    let pluginName = config.name
+    if (pluginType === 'web') {
+      const result = ensureWebPluginName(pluginName)
+      pluginName = result.name
+      if (result.appended) {
+        clack.log.info(chalk.cyan(`${t('pluginNameAutoSuffix')}: ${pluginName}`))
+      }
+    }
+
+    const vars: TemplateVars = {
+      name: pluginName,
+      summary: config.summary,
+      version: config.version,
+      description: config.description,
+      author: config.author,
+    }
+
     const targetDir = pluginType === 'web'
-      ? join(getFrontendPluginDir(projectDir), config.name)
-      : join(getBackendPluginDir(projectDir), config.name)
+      ? join(getFrontendPluginDir(projectDir), pluginName)
+      : join(getBackendPluginDir(projectDir), pluginName)
 
     if (existsSync(targetDir)) {
       clack.log.warn(chalk.yellow(`${t('pluginDirExists')}: ${targetDir}`))
       continue
     }
 
     const createSpinner = clack.spinner()
-    createSpinner.start(`${t('pluginCreating')} ${pluginType}: ${config.name}`)
+    createSpinner.start(`${t('pluginCreating')} ${pluginType}: ${pluginName}`)
 
     try {
       // 1. 渲染模板
@@ -106,8 +116,9 @@ export async function pluginCreateAction(options: { project?: string }) {
           parsed.plugin.description = config.description
           parsed.plugin.author = config.author
           parsed.plugin.tags = config.tags
-          if (config.database.length > 0) {
-            parsed.plugin.database = config.database
+          const database = config.database as string[] | undefined
+          if (database && database.length > 0) {
+            parsed.plugin.database = database
           }
         }
         writeFileSync(tomlPath, stringifyToml(parsed), 'utf-8')
diff --git a/src/lib/i18n.ts b/src/lib/i18n.ts
@@ -150,6 +150,8 @@ const messages = {
     pluginTableVersion: "版本",
     pluginTableAuthor: "作者",
     pluginTotal: "共计",
+    pluginNameAutoSuffix: "前端插件名称已自动添加 _ui 后缀",
+    pluginMarketCacheUsed: "网络不可用，使用本地缓存数据",
 
     // Completion
     createSuccess: "项目创建成功!",
@@ -398,6 +400,8 @@ const messages = {
     pluginTableVersion: "Version",
     pluginTableAuthor: "Author",
     pluginTotal: "Total",
+    pluginNameAutoSuffix: "Frontend plugin name auto-appended with _ui suffix",
+    pluginMarketCacheUsed: "Network unavailable, using local cache",
 
     createSuccess: "Project created successfully!",
     nextSteps: "Next steps",
diff --git a/src/lib/plugin-install.ts b/src/lib/plugin-install.ts
@@ -6,9 +6,10 @@ import { run } from './process.js'
 import { gitClone, removeGitDir } from './git.js'
 import { getFrontendPluginDir, getBackendPluginDir, getBackendDir, getFrontendDir } from './config.js'
 import type { InstalledPlugin, PluginInfo, PluginData } from '../types/plugin.js'
+import { inferPluginType } from '../types/plugin.js'
 
 /**
- * 扫描已安装的插件
+ * 扫描已安装的插件（通过名称后缀 _ui 判断类型）
  */
 export function scanInstalledPlugins(projectDir: string): InstalledPlugin[] {
   const plugins: InstalledPlugin[] = []
@@ -20,7 +21,7 @@ export function scanInstalledPlugins(projectDir: string): InstalledPlugin[] {
       const tomlPath = join(frontendPluginDir, dir, 'plugin.toml')
       const info = readPluginToml(tomlPath)
       if (info) {
-        plugins.push({ name: dir, dir: join(frontendPluginDir, dir), type: 'web', info })
+        plugins.push({ name: dir, dir: join(frontendPluginDir, dir), type: inferPluginType(dir), info })
       }
     }
   }
@@ -32,7 +33,7 @@ export function scanInstalledPlugins(projectDir: string): InstalledPlugin[] {
       const tomlPath = join(backendPluginDir, dir, 'plugin.toml')
       const info = readPluginToml(tomlPath)
       if (info) {
-        plugins.push({ name: dir, dir: join(backendPluginDir, dir), type: 'server', info })
+        plugins.push({ name: dir, dir: join(backendPluginDir, dir), type: inferPluginType(dir), info })
       }
     }
   }
@@ -114,7 +115,7 @@ export async function installBackendPlugin(
 }
 
 /**
- * 从插件市场数据安装多个插件
+ * 从插件市场数据安装多个插件（通过名称后缀 _ui 判断类型）
  */
 export async function installFromMarket(
   projectDir: string,
@@ -123,21 +124,17 @@ export async function installFromMarket(
   const success: string[] = []
   const failed: string[] = []
 
-  const webPlugins = plugins.filter(p => p.plugin.type === 'web')
-  const serverPlugins = plugins.filter(p => p.plugin.type === 'server')
-
-  // 安装前端插件
-  for (const p of webPlugins) {
+  for (const p of plugins) {
     const name = basename(p.git.path) || p.plugin.summary
-    const ok = await installFrontendPlugin(projectDir, p.git.url, name, p.git.branch)
-    if (ok) success.push(name)
-    else failed.push(name)
-  }
+    const type = inferPluginType(name)
+
+    let ok: boolean
+    if (type === 'web') {
+      ok = await installFrontendPlugin(projectDir, p.git.url, name, p.git.branch)
+    } else {
+      ok = await installBackendPlugin(projectDir, { repoUrl: p.git.url })
+    }
 
-  // 安装后端插件
-  for (const p of serverPlugins) {
-    const ok = await installBackendPlugin(projectDir, { repoUrl: p.git.url })
-    const name = basename(p.git.path) || p.plugin.summary
     if (ok) success.push(name)
     else failed.push(name)
   }
diff --git a/src/lib/plugin-market.ts b/src/lib/plugin-market.ts
@@ -1,59 +1,76 @@
 // plugin-market.ts — 插件市场数据获取 & 解析
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { homedir } from 'os'
 import { ofetch } from 'ofetch'
+import { basename } from 'path'
 import type { PluginData } from '../types/plugin.js'
+import { inferPluginType } from '../types/plugin.js'
 
 const PLUGIN_DATA_URL =
   'https://raw.githubusercontent.com/fastapi-practices/plugins/refs/heads/master/plugins-data.ts'
 
-/**
- * 从远程获取并解析插件市场数据
- */
-export async function fetchPluginMarketData(): Promise<PluginData[]> {
-  const content = await ofetch(PLUGIN_DATA_URL, { responseType: 'text' })
+const CACHE_PATH = join(homedir(), '.fba-plugins-cache.json')
+
+// ─── 缓存 ───
 
-  // 提取 pluginDataList 数组 JSON
-  const match = content.match(/pluginDataList[^=]*=\s*(\[[\s\S]*\])/)
-  if (!match?.[1]) {
-    throw new Error('Failed to parse plugin market data: pluginDataList not found')
+function readCache(): PluginData[] | null {
+  if (!existsSync(CACHE_PATH)) return null
+  try {
+    return JSON.parse(readFileSync(CACHE_PATH, 'utf-8')) as PluginData[]
+  } catch {
+    return null
   }
+}
 
+function writeCache(data: PluginData[]): void {
   try {
-    // TS 文件中的值本身就是合法 JSON
-    return JSON.parse(match[1]) as PluginData[]
-  } catch (e) {
-    throw new Error(`Failed to parse plugin data JSON: ${e}`)
+    writeFileSync(CACHE_PATH, JSON.stringify(data), 'utf-8')
+  } catch {
+    // 缓存写入失败不影响主流程
   }
 }
 
+// ─── 数据获取 ───
+
 /**
- * 按关键词搜索插件
+ * 从远程获取并解析插件市场数据，失败时回退到本地缓存
+ *
+ * @returns `{ data, fromCache }` — fromCache 为 true 时说明使用了缓存
  */
-export function searchPlugins(plugins: PluginData[], query: string): PluginData[] {
-  if (!query.trim()) return plugins
-  const q = query.toLowerCase()
-  return plugins.filter(p => {
-    const plugin = p.plugin
-    return (
-      plugin.summary.toLowerCase().includes(q) ||
-      plugin.description.toLowerCase().includes(q) ||
-      plugin.author.toLowerCase().includes(q) ||
-      plugin.tags?.some(t => t.toLowerCase().includes(q))
-    )
-  })
+export async function fetchPluginMarketData(): Promise<{ data: PluginData[]; fromCache: boolean }> {
+  try {
+    const content = await ofetch(PLUGIN_DATA_URL, { responseType: 'text' })
+
+    const match = content.match(/pluginDataList[^=]*=\s*(\[[\s\S]*\])/)
+    if (!match?.[1]) {
+      throw new Error('pluginDataList not found')
+    }
+
+    const data = JSON.parse(match[1]) as PluginData[]
+    writeCache(data)
+    return { data, fromCache: false }
+  } catch {
+    const cached = readCache()
+    if (cached) return { data: cached, fromCache: true }
+    throw new Error('Failed to fetch plugin market data and no local cache available')
+  }
 }
 
 /**
- * 按 tag 过滤插件
+ * 按 type 过滤插件（基于 git.path 名称推断类型）
  */
-export function filterByTag(plugins: PluginData[], tag: string): PluginData[] {
-  if (!tag || tag === 'all') return plugins
-  return plugins.filter(p => p.plugin.tags?.includes(tag as any))
+export function filterByType(plugins: PluginData[], type: string): PluginData[] {
+  if (!type || type === 'all') return plugins
+  return plugins.filter(p => {
+    const name = basename(p.git.path)
+    return inferPluginType(name) === type
+  })
 }
 
 /**
- * 按 type 过滤插件
+ * 根据市场插件的 git.path 推断插件类型
  */
-export function filterByType(plugins: PluginData[], type: string): PluginData[] {
-  if (!type || type === 'all') return plugins
-  return plugins.filter(p => p.plugin.type === type)
+export function getMarketPluginType(p: PluginData): 'web' | 'server' {
+  return inferPluginType(basename(p.git.path))
 }
diff --git a/src/types/plugin.ts b/src/types/plugin.ts
@@ -60,9 +60,22 @@ export type PluginTag = 'ai' | 'mcp' | 'agent' | 'auth' | 'storage' | 'notificat
 export type DatabaseType = 'mysql' | 'postgresql'
 export type ServerPluginLevel = 'app' | 'ext'
 
+export const PLUGIN_WEB_SUFFIX = '_ui'
+
 export const VALID_TAGS: PluginTag[] = ['ai', 'mcp', 'agent', 'auth', 'storage', 'notification', 'task', 'payment', 'other']
 export const VALID_DATABASES: DatabaseType[] = ['mysql', 'postgresql']
 
+/** 根据名称后缀推断插件类型：以 _ui 结尾为 web 插件，否则为 server 插件 */
+export function inferPluginType(name: string): PluginType {
+  return name.endsWith(PLUGIN_WEB_SUFFIX) ? 'web' : 'server'
+}
+
+/** 确保 web 插件名称以 _ui 结尾，返回是否进行了自动追加 */
+export function ensureWebPluginName(name: string): { name: string; appended: boolean } {
+  if (name.endsWith(PLUGIN_WEB_SUFFIX)) return { name, appended: false }
+  return { name: `${name}${PLUGIN_WEB_SUFFIX}`, appended: true }
+}
+
 /** 已安装的本地插件信息 */
 export interface InstalledPlugin {
   name: string
