OpenPackage 深度探究：AI 編程的跨平台插件管理系統

OpenPackage 是一個開源的 CLI 工具，旨在解決 AI 編程工具生態的碎片化問題。它提供了一套統一的插件系統，讓開發者可以跨 AI 編程平台（如 Cursor、Claude Code、Windsurf 等）重用規則、指令、子代理等配置。

一、為什麼需要 OpenPackage？

當前 AI 編程工具面臨三個核心問題：

問題描述
散落各地規則、指令、子代理分散在不同專案中，難以复用
規格割裂個人與團隊的 spec 沒有版本控制，逐漸失去一致性
平台綁定熟悉的 workflow 只能在單一平台上使用

OpenPackage 的解決方案是將 AI 編程配置打包成可版本化、跨平台兼容的 packages，讓同一套規則可以在任何專案、任何團隊、任何平台上使用。

二、核心功能總覽

# 安裝 CLI
npm install -g opkg

# 初始化工作區為 package
opkg init <package-name>

# 保存文件到本地 registry
opkg save <package>

# 安裝 package 到專案
opkg install <package>

# 跨平台同步
opkg save essentials .cursor/commands/essentials
# 自動生成並同步到 .claude/, .opencode/ 等目錄

支援的 AI 編程平台

平台目錄規則指令代理技能
Cursor.cursor/rules/commands/--
Claude Code.claude/rules/commands/agents/skills/
Windsurf.windsurf/rules/---
Roo Code.roo/-commands/--
OpenCode.opencode/-command/agent/-
Factory.factory/-commands/droids/-
Kilo Code.kilocode/rules/workflows/--
Kiro.kiro/steering/---
Qwen Code.qwen/--agents/-
Codex.codex/-prompts/--
Antigravity.agent/rules/workflows/--
Augment Code.augment/rules/commands/--
Warp.warp/----

三、Package 結構

OpenPackage 的 package 採用以下目錄結構：

<package>/
├── .openpackage/
│   ├── package.yml     # 必要：Package 清單
│   ├── rules/          # 規則文件
│   ├── commands/       # 斜杠指令文件
│   ├── agents/         # 子代理文件
│   └── skills/         # Claude Code 技能文件
├── specs/              # 技術規格文件（可選）
├── docs/               # 文檔（可選）
├── README.md           # 說明文件
└── AGENTS.md           # 平台根文件

package.yml 範例

name: typescript-essentials
version: 1.0.0
description: TypeScript 開發最佳實踐規則集
author: Your Name
license: MIT
keywords:
  - typescript
  - rules
dependencies:
  - javascript-basics@^1.0.0

四、核心架構設計

4.1 平台抽象層

OpenPackage 使用**通用目錄（universal directories）**來抽象不同平台的差異：

// platforms.jsonc 中的定義
{
  "cursor": {
    "rootDir": ".cursor",
    "subdirs": [
      { "universalDir": "rules", "platformDir": "rules", "exts": [".mdc", ".md"] },
      { "universalDir": "commands", "platformDir": "commands", "exts": [".md"] }
    ]
  },
  "claude": {
    "rootDir": ".claude",
    "rootFile": "CLAUDE.md",
    "subdirs": [
      { "universalDir": "rules", "platformDir": "rules", "exts": [".md"] },
      { "universalDir": "commands", "platformDir": "commands", "exts": [".md"] }
    ]
  }
}

這種設計讓同一個 package 可以自動適配不同平台的目錄結構。

4.2 Package 管理器

class PackageManager {
  // 從 registry 加載 package
  async loadPackage(name: string, version?: string): Promise<Package>

  // 保存到本地 registry
  async savePackage(pkg: Package): Promise<void>

  // 版本解析與範圍匹配
  async resolveVersionRange(range: string): Promise<string>

  // 刪除 package
  async deletePackage(name: string): Promise<void>
}

4.3 依賴解析系統

OpenPackage 支援 package 依賴關係：

# package.yml
name: fullstack-nextjs
version: 1.0.0
dependencies:
  - typescript@^1.0.0
  - react-best-practices@^2.0.0
  - tailwindcss@^1.0.0

CLI 會自動解析依賴樹，確保版本兼容性。

4.4 安裝模式

支援三種安裝模式：

模式描述
合併模式覆蓋已存在的文件
選擇模式互動式選擇要安裝的文件
保留模式保留本地修改的文件

五、使用場景

5.1 跨專案复用規則

# 在當前專案保存規則
opkg save typescript .cursor/rules/typescript

# 在新專案安裝
opkg install typescript

5.2 模組化 package 組合

# 創建不同領域的 package
opkg save typescript .cursor/rules/typescript
opkg save nextjs .cursor/rules/nextjs
opkg save nestjs .cursor/rules/nestjs
opkg save mongodb .cursor/rules/mongodb

# 在 NextJS 專案組合使用
opkg install typescript nextjs

# 在 NestJS 專案組合使用
opkg install typescript nestjs mongodb

5.3 團隊協作

# 登入並推送 package 到遠程 registry
opkg login
opkg push team-standards

# 團隊成員安裝
opkg pull team-standards
opkg install team-standards

六、與其他方案的比較

特性OpenPackageClaude Code Plugins無插件方案
開源✅❌-
跨平台兼容✅ 13+ 平台❌ 單一平台-
版本控制✅❌❌
依賴管理✅❌❌
內容同步✅ 自動❌❌
無需 API Key✅❌-
無需 MCP✅❌-

七、進階功能

7.1 自定義平台配置

可以透過 platforms.jsonc 覆蓋內建平台定義：

{
  "custom": {
    "name": "Custom Platform",
    "rootDir": ".custom",
    "subdirs": [
      { "universalDir": "rules", "platformDir": "rules", "exts": [".md"] }
    ]
  }
}

配置合併順序：本地 > 全局 > 內建

7.2 擴展名轉換

Cursor 使用 .mdc 作為規則文件擴展名，而其他平台使用 .md。OpenPackage 自動處理轉換：

{
  "cursor": {
    "subdirs": [{
      "universalDir": "rules",
      "platformDir": "rules",
      "exts": [".mdc", ".md"],
      "transformations": [
        { "packageExt": ".md", "workspaceExt": ".mdc" }
      ]
    }]
  }
}

7.3 部分安裝

支援只安裝 package 中的部分文件：

opkg install package --select
# 互動式選擇要安裝的文件

八、本地開發流程

# 1. 初始化 package
opkg init my-rules

# 2. 添加規則文件
opkg add my-rules .cursor/rules/

# 3. 保存到本地 registry（預發布）
opkg save my-rules

# 4. 打包發布版本
opkg pack my-rules

# 5. 測試安裝
opkg install my-rules

九、專案結構

OpenPackage/
├── bin/
│   └── openpackage          # CLI 入口腳本
├── src/
│   ├── commands/            # CLI 命令實現
│   │   ├── init.ts
│   │   ├── save.ts
│   │   ├── install.ts
│   │   ├── uninstall.ts
│   │   ├── push.ts
│   │   ├── pull.ts
│   │   └── ...
│   ├── core/
│   │   ├── platforms.ts     # 平台定義與映射
│   │   ├── package.ts       # Package 管理
│   │   ├── registry.ts      # 本地 registry
│   │   ├── dependency-resolver.ts  # 依賴解析
│   │   └── install/         # 安裝邏輯
│   ├── utils/               # 工具函數
│   └── index.ts             # CLI 入口
├── platforms.jsonc          # 內建平台定義
├── package.json
└── tests/                   # 測試套件

十、總結

OpenPackage 的核心價值在於：

  1. 解耦配置與平台：將 AI 編程配置從特定平台中抽離
  2. 版本化與复用：讓有價值的規則與 workflow 可以追蹤版本並跨專案使用
  3. 統一生態：連接割裂的 AI 編程工具生態

隨著 AI 編程工具的快速發展，OpenPackage 提供了一個必要的抽象層，確保開發者的知識資產不會被单一平台鎖定。

參考資源