第 12 章 插件系统设计

npm install eslint-plugin-react

// vite.config.ts
import vue from '@vitejs/plugin-vue'
export default defineConfig({
  plugins: [vue()],
})

// src/core/plugin-manager.ts
export interface RepoxPlugin {
  name: string
  version: string
  description?: string
  // 注册命令
  registerCommands?: (program: Command) => void
  // 生命周期钩子
  hooks?: {
    beforeCommand?: (commandName: string) => Promise<void> | void
    afterCommand?: (commandName: string) => Promise<void> | void
    beforeScan?: () => Promise<void> | void
    afterScan?: (result: unknown) => Promise<void> | void
    beforeCommit?: (message: string) => Promise<string> | string
    afterCommit?: () => Promise<void> | void
  }
}

// src/core/plugin-manager.ts
export async function executeHook(
  plugins: RepoxPlugin[],
  hookName: keyof NonNullable<RepoxPlugin['hooks']>,
  ...args: unknown[]
): Promise<void> {
  for (const plugin of plugins) {
    const hook = plugin.hooks?.[hookName]
    if (typeof hook === 'function') {
      try {
        logger.debug(`执行 Hook: ${plugin.name}.${hookName}`)
        await (hook as (...a: unknown[]) => unknown)(...args)
      } catch (error) {
        logger.warn(
          `插件 ${plugin.name} 的 ${hookName} Hook 执行失败: ${error instanceof Error ? error.message : ''}`
        )
      }
    }
  }
}

// 在 commit 命令中
let message = generatedMessage
for (const plugin of plugins) {
  if (plugin.hooks?.beforeCommit) {
    message = await plugin.hooks.beforeCommit(message)
  }
}
// message 现在可能已经被插件修改过了

// src/core/plugin-manager.ts
function getPluginDir(): string {
  return path.join(getGlobalConfigDir(), 'plugins')
}

export function installPlugin(name: string): void {
  const fullName = name.startsWith('repox-plugin-') ? name : `repox-plugin-${name}`
  const pluginDir = getPluginDir()
  fs.mkdirSync(pluginDir, { recursive: true })
 
  logger.info(`安装插件 ${fullName}...`)
 
  try {
    execSync(`npm install ${fullName} --prefix "${pluginDir}"`, {
      stdio: 'pipe',
      encoding: 'utf-8',
    })
  } catch (error) {
    throw new Error(`插件 ${fullName} 安装失败。请确认包名是否正确。`)
  }
 
  const installed = getInstalledPluginNames()
  if (!installed.includes(fullName)) {
    installed.push(fullName)
    updateManifest(installed)
  }
 
  logger.success(`插件 ${fullName} 安装成功`)
}

{
  "plugins": [
    "repox-plugin-feishu",
    "repox-plugin-gitlab"
  ]
}

export async function loadPlugins(): Promise<RepoxPlugin[]> {
  const installed = getInstalledPluginNames()
  const pluginDir = getPluginDir()
  const plugins: RepoxPlugin[] = []
 
  for (const name of installed) {
    try {
      const pluginPath = path.join(pluginDir, 'node_modules', name)
      const pkg = JSON.parse(
        fs.readFileSync(path.join(pluginPath, 'package.json'), 'utf-8')
      )
      const mainFile = pkg.main || 'index.js'
      const mainPath = path.join(pluginPath, mainFile)
 
      if (!fs.existsSync(mainPath)) {
        logger.warn(`插件 ${name} 入口文件不存在: ${mainFile}`)
        continue
      }
 
      const mod = await import(mainPath)
      const plugin: RepoxPlugin = mod.default || mod
      plugin.name = plugin.name || name
      plugin.version = plugin.version || pkg.version
      plugins.push(plugin)
      logger.debug(`已加载插件: ${name}@${plugin.version}`)
    } catch (error) {
      logger.warn(
        `插件 ${name} 加载失败: ${error instanceof Error ? error.message : '未知错误'}`
      )
    }
  }
 
  return plugins
}

// ESM default export
export default { name: 'feishu', version: '1.0.0', ... }
 
// CommonJS module.exports
module.exports = { name: 'feishu', version: '1.0.0', ... }

repox plugin install feishu    # 安装（自动补全为 repox-plugin-feishu）
repox plugin list              # 列出已安装插件
repox plugin uninstall feishu  # 卸载

// 扩展后的钩子签名
interface HookContext {
  config: RepoxConfig
  cwd: string
  // 插件可以往 meta 里写数据
  meta: Map<string, unknown>
}
 
hooks?: {
  beforeCommand?: (ctx: HookContext, commandName: string) => Promise<void> | void
}

node --experimental-permission --allow-fs-read="/home/user" dist/index.js

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 .claude/hooks/validate-bash.py"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "command": "terminal-notifier -message \"$CLAUDE_NOTIFICATION\""
      }
    ]
  }
}

// .repoxrc
{
  "hooks": {
    "afterCommit": "curl -X POST https://webhook.example.com -d '{\"event\": \"commit\"}'"
  }
}

// src/commands/plugin.ts
export function registerPluginCommand(program: Command): void {
  const plugin = program
    .command('plugin')
    .description('管理 repox 插件')
 
  // repox plugin install <name>
  plugin
    .command('install <name>')
    .alias('add')
    .description('安装插件（如 repox plugin install feishu）')
    .action((name: string) => {
      installPlugin(name)
    })
 
  // repox plugin uninstall <name>
  plugin
    .command('uninstall <name>')
    .alias('remove')
    .description('卸载插件')
    .action((name: string) => {
      uninstallPlugin(name)
    })
 
  // repox plugin list
  plugin
    .command('list')
    .alias('ls')
    .description('列出已安装的插件')
    .option('-f, --format <format>', '输出格式', 'table')
    .action((options) => {
      const format = options.format as OutputFormat
      const plugins = listPlugins()
 
      if (plugins.length === 0) {
        logger.info('没有安装任何插件')
        logger.info(`运行 ${chalk.cyan('repox plugin install <name>')} 安装插件`)
        return
      }
 
      if (format === 'json') {
        logger.plain(JSON.stringify(plugins, null, 2))
        return
      }
 
      logger.title(`已安装插件 (${plugins.length} 个)`)
      const rows = plugins.map((p) => [
        p.name,
        p.version,
        p.description || chalk.gray('(无描述)'),
      ])
      logger.plain(formatList(['名称', '版本', '描述'], rows, format))
    })
}

repox-plugin-feishu/
├── package.json
├── tsconfig.json
├── src/
│   └── index.ts
└── dist/
    └── index.js

{
  "name": "repox-plugin-feishu",
  "version": "1.0.0",
  "description": "repox 飞书通知插件 — commit 后自动发送群消息",
  "main": "dist/index.js",
  "type": "module",
  "keywords": ["repox-plugin", "feishu", "lark"],
  "peerDependencies": {
    "repox": ">=0.1.0"
  }
}

import type { RepoxPlugin } from 'repox'
 
const WEBHOOK_ENV = 'FEISHU_WEBHOOK_URL'
 
const plugin: RepoxPlugin = {
  name: 'repox-plugin-feishu',
  version: '1.0.0',
  description: '飞书通知插件',
 
  hooks: {
    afterCommit: async () => {
      const webhookUrl = process.env[WEBHOOK_ENV]
      if (!webhookUrl) {
        // 没配置 webhook 就静默跳过，不报错
        return
      }
 
      try {
        await fetch(webhookUrl, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({
            msg_type: 'text',
            content: {
              text: `[repox] 新的 commit 已提交，项目目录: ${process.cwd()}`,
            },
          }),
        })
      } catch {
        // 通知失败不应该影响 commit 流程
        console.warn('飞书通知发送失败')
      }
    },
 
    beforeCommit: (message: string) => {
      // 可以在这里校验 commit message 格式
      // 比如要求 feat: / fix: / chore: 前缀
      if (!/^(feat|fix|chore|docs|refactor|test|style|perf|ci|build|revert):/.test(message)) {
        console.warn('⚠ commit 消息不符合 conventional commits 规范')
      }
      return message // 不修改，只警告
    },
  },
}
 
export default plugin

# 安装插件
repox plugin install feishu
 
# 设置环境变量
export FEISHU_WEBHOOK_URL="https://open.feishu.cn/open-apis/bot/v2/hook/xxxxx"
 
# 正常使用 repox commit，插件自动生效
repox commit

// repox-plugin-template/index.ts
import type { Command } from 'commander'
 
export default {
  name: 'repox-plugin-example',
  version: '0.1.0',
 
  // 注册自定义命令
  registerCommands(program: Command) {
    program
      .command('example')
      .description('示例插件命令')
      .action(() => {
        console.log('Hello from plugin!')
      })
  },
 
  // 生命周期钩子
  hooks: {
    beforeCommand(commandName: string) {
      console.log(`即将执行命令: ${commandName}`)
    },
  },
}