vibe-package-manager 1.2.4

A package manager for managing SKILLs, SubAgents, and MCPs

Vibe 包管理器

Vibe Package Manager (vpm) 是一个用于管理 AI 助手 SKILL、SubAgent 和 MCP 的包管理工具，支持 Claude Code、iFlow CLI、Qoder 和 Codex 等 AI 编程助手。

功能特性

• 版本管理: 跟踪和管理 SKILL 与 SubAgent 的版本
• 依赖解析: 支持语义化版本控制（^ 符号表示兼容版本）
• 多代理支持: 一次配置，安装到多个 AI 助手（支持 Claude、iFlow、Qoder、Codex）
• Git 集成: 从 Git 仓库克隆和安装包
• Zip 支持: 从 URL 或本地 zip 包安装（无需 Git）
• MCP 安装: 安装 Model Context Protocol 服务器扩展
• 递归依赖: SubAgent 可以声明自己的依赖
• 循环依赖检测: 自动检测并防止循环依赖
• 配置验证: 验证配置文件和版本兼容性
• 幂等操作: 多次运行安全无副作用

安装

pipx install vibe-package-manager

or

python3 -m pip install vibe-package-manager

安装完成后，可以使用 vpm 命令。

快速开始

1. 创建配置文件

在项目根目录创建 vibe_package.json：

{
    "target_agents": [
        "claude",
        "iflow",
        "qoder"
    ],
    "dependencies": {
        "fetch": {
            "command": "npx",
            "args": ["-y", "@iflow-mcp/fetch@1.0.2"],
            "type": "MCP"
        },
        "docx": {
            "git": "https://github.com/ComposioHQ/awesome-claude-skills.git",
            "git_tag": "master",
            "path": "document-skills/docx",
            "type": "SKILL"
        },
        "awesome-agent": {
            "git": "https://github.com/vijaythecoder/awesome-claude-agents.git",
            "git_tag": "main",
            "path": "agents/core",
            "type": "SUBAGENT"
            
        }
    }
}

2. 验证配置

vpm validate

3. 安装依赖

vpm install

vibe_package.json 配置详解

基本结构

{
  "target_agents": ["claude", "iflow", "qoder"],
  "dependencies": {}
}

参数说明

参数	类型	必填	说明
target_agents	数组	是	目标 AI 助手列表，可选值：claude、iflow、qoder、codex
dependencies	对象	是	依赖包定义，键为包名，值为配置对象

target_agents

指定要安装到的 AI 助手列表：

• claude - Claude Code
• iflow - iFlow CLI
• qoder - Qoder CLI
• codex - OpenAI Codex

dependencies

定义要安装的依赖包，支持三种类型：SKILL、SUBAGENT、MCP。

SKILL 类型

从 Git 仓库或 Zip 包安装 SKILL。每个 SKILL 必须指定 git+git_tag 或 zip 其中一种来源（不可同时使用）。 Git 来源会浅克隆 git_tag 指向的最新快照；配置 path 时使用稀疏检出，只下载并安装目标子目录。

Git 来源：

{
  "dependencies": {
    "code-improver": {
      "git": "https://github.com/example/code-improver-skill.git",
      "git_tag": "v1.0.0",
      "type": "SKILL"
    }
  }
}

Zip 来源（URL 或本地路径）：

{
  "dependencies": {
    "my-skill-remote": {
      "zip": "https://example.com/skills/my-skill-v1.0.0.zip",
      "type": "SKILL"
    },
    "my-skill-local": {
      "zip": "./packages/my-skill.zip",
      "type": "SKILL",
      "path": "src"
    }
  }
}

多 SKILL 仓库（使用 path）：

{
  "dependencies": {
    "markdown-optimize": {
      "git": "https://github.com/example/ai-skills.git",
      "git_tag": "v1.0.0",
      "type": "SKILL",
      "path": "markdown_optimize"
    },
    "python-optimize": {
      "git": "https://github.com/example/ai-skills.git",
      "git_tag": "v1.0.0",
      "type": "SKILL",
      "path": "python_optimize"
    }
  }
}

SKILL 参数说明：

参数	类型	必填	说明
git	字符串	二选一	Git 仓库地址（与 git_tag 配合使用）
git_tag	字符串	二选一	Git 标签或分支名（与 git 配合使用）
zip	字符串	二选一	Zip 包的 URL 或本地文件路径（与 git+git_tag 互斥）
type	字符串	是	必须是 "SKILL"
path	字符串	否	解压/克隆后的子目录路径

SKILL 仓库结构：

skill-repo/
└── SKILL.md          # 必须包含元数据

SubAgent 类型

从 Git 仓库或 Zip 包安装 SubAgent。来源规则与 SKILL 相同（git+git_tag 或 zip 二选一）。

Git 来源：

{
  "dependencies": {
    "code-reviewer": {
      "git": "https://github.com/example/code-reviewer-agent.git",
      "git_tag": "main",
      "type": "SUBAGENT"
    }
  }
}

Zip 来源：

{
  "dependencies": {
    "code-reviewer": {
      "zip": "https://example.com/agents/code-reviewer.zip",
      "type": "SUBAGENT"
    }
  }
}

多 SubAgent 仓库（使用 path）：

{
  "dependencies": {
    "code-reviewer": {
      "git": "https://github.com/example/agents-repo.git",
      "git_tag": "main",
      "type": "SUBAGENT",
      "path": "reviewers/code-reviewer"
    },
    "doc-reviewer": {
      "git": "https://github.com/example/agents-repo.git",
      "git_tag": "main",
      "type": "SUBAGENT",
      "path": "reviewers/doc-reviewer"
    }
  }
}

SubAgent 参数说明：

参数	类型	必填	说明
git	字符串	二选一	Git 仓库地址（与 git_tag 配合使用）
git_tag	字符串	二选一	Git 标签或分支名（与 git 配合使用）
zip	字符串	二选一	Zip 包的 URL 或本地文件路径（与 git+git_tag 互斥）
type	字符串	是	必须是 "SUBAGENT"
path	字符串	否	解压/克隆后的子目录路径

SubAgent 仓库结构：

subagent-repo/
├── agent.md                  # 主代理定义文件
└── vibe_package.json         # 可选：SubAgent 自己的依赖

SubAgent 递归依赖：

SubAgent 可以在自己的仓库中声明 vibe_package.json：

{
  "target_agents": ["parent"],
  "dependencies": {
    "helper-skill": {
      "git": "https://github.com/example/helper-skill.git",
      "git_tag": "main",
      "type": "SKILL"
    }
  }
}

使用 "target_agents": ["parent"] 或 [] 继承父配置的 target_agents。

MCP 类型

安装 Model Context Protocol 服务器。

例子：

{
  "dependencies": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "type": "MCP"
    },
    "fetch-mcp": {
      "command": "npx",
      "args": ["-y", "@iflow-mcp/fetch@1.0.2"],
      "type": "MCP"
    }
  }
}

MCP 参数说明：

参数	类型	必填	说明
command	字符串	是	要执行的命令
args	数组	是	命令参数数组
type	字符串	是	必须是 "MCP"

MCP 安装行为：

• 自动移除同名已存在的 MCP
• 根据代理类型使用正确的命令格式
• 显示安装输出和结果

SKILL.md 和 SubAgent.md 元数据

每个 SKILL 或 SubAgent 需要在 markdown 文件中定义元数据：

---
name: package-name
description: 包的描述说明
version: 1.0.0
support_agents:
  iflow: "1.0.0"
  claude: "^2.0.0"
  qoder: "^1.0.0"
---

内容...

元数据字段说明

字段	类型	必填	说明
name	字符串	建议	包的唯一标识名
description	字符串	建议	包的描述说明
version	字符串	推荐	版本号，语义化版本格式
support_agents	对象	推荐	支持的代理及版本要求

version 字段

使用语义化版本号（SemVer）：主版本.次版本.修订号

示例：

• 1.0.0 - 初始版本
• 1.2.3 - 有新增功能
• 2.0.0 - 不兼容的 API 变更

support_agents 字段

定义支持的 AI 助手及其版本要求：

support_agents:
  iflow: "1.0.0"      # 精确版本 1.0.0
  claude: "^2.0.0"    # >= 2.0.0 且 < 3.0.0
  qoder: "^1.0.0"     # >= 1.0.0 且 < 2.0.0
  codex: "^1.0.0"     # >= 1.0.0 且 < 2.0.0

版本匹配规则：

• 精确版本："1.0.0" - 必须完全匹配
• ^ 符号："^2.0.0" - 兼容版本，>= 2.0.0 且 < 3.0.0
• 0.x 特殊规则："^0.2.0" - >= 0.2.0 且 < 0.3.0

版本号提取： VPM 会自动从版本字符串中提取数字部分：

• "2.1.79-20260319.1" → 提取为 2.1.79
• "v1.0.0" → 提取为 1.0.0
• "1.2.3-alpha" → 提取为 1.2.3

警告信息： 如果缺少 version 或 support_agents 字段，VPM 会显示警告但继续安装：

[SKILL 'code-improver'] Warning: Agent 'qoder' is not in support_agents. Supported agents: ['iflow', 'claude']

VPM 命令用法

vpm install

安装所有依赖：

vpm install                    # 基本安装
vpm install -c config.json     # 指定配置文件
vpm install --debug            # 启用调试日志
vpm install --no-cleanup       # 清理历史缓存，保留本次安装的临时目录
vpm install --continue-on-error # 出错时继续处理其他依赖

选项说明：

选项	说明
-c, --config	指定配置文件路径（默认搜索当前目录）
-d, --debug	显示详细调试信息
--no-cleanup	安装前清理历史缓存，安装后保留本次临时目录用于调试
--continue-on-error	单个依赖失败时继续处理其他

默认情况下，VPM 会在安装前清理旧的 .vibe_package，并在安装成功、失败或中断后再次清理。 如果临时目录因权限或文件占用无法删除，安装会返回失败并显示残留路径，避免缓存静默堆积。

vpm validate

验证配置文件：

vpm validate                   # 验证 vibe_package.json
vpm validate -c config.json    # 验证指定配置文件

vpm --version

显示版本信息：

vpm --version
vpm -v

完整配置示例

{
  "target_agents": ["claude", "iflow", "qoder"],
  "dependencies": {
    "code-improver": {
      "git": "https://github.com/example/code-improver-skill.git",
      "git_tag": "v1.0.0",
      "type": "SKILL"
    },
    "markdown-optimize": {
      "git": "https://github.com/example/ai-skills.git",
      "git_tag": "v1.0.0",
      "type": "SKILL",
      "path": "markdown_optimize"
    },
    "zip-skill": {
      "zip": "https://example.com/skills/my-skill-v1.0.0.zip",
      "type": "SKILL"
    },
    "local-skill": {
      "zip": "./packages/local-skill.zip",
      "type": "SKILL"
    },
    "code-reviewer": {
      "git": "https://github.com/example/code-reviewer-agent.git",
      "git_tag": "main",
      "type": "SUBAGENT"
    },
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "type": "MCP"
    },
    "fetch-mcp": {
      "command": "npx",
      "args": ["-y", "@iflow-mcp/fetch@1.0.2"],
      "type": "MCP"
    }
  }
}

安装过程说明

SKILL 安装流程

1. 获取源码到 .vibe_package/skills/[SKILL_NAME]/（Git 克隆 或 Zip 下载解压）
2. 处理单目录仓库结构
3. 移除 .git 目录（如有）
4. 验证 SKILL.md 存在
5. 读取并验证元数据（version, support_agents）
6. 检查与目标代理的版本兼容性
7. 复制到目标目录：.claude/skills/、.iflow/skills/、.qoder/skills/

SubAgent 安装流程

1. 获取源码到 .vibe_package/agents/[SUBAGENT_NAME]/（Git 克隆 或 Zip 下载解压）
2. 移除 .git 目录（如有）
3. 查找根目录下的 markdown 文件
4. 从第一个 markdown 文件读取元数据
5. 检查版本兼容性
6. 复制所有 markdown 文件到目标目录
7. 检查 vibe_package.json 并递归安装依赖

MCP 安装流程

1. 检查是否已存在同名 MCP
2. 如存在则先移除：{agent} mcp remove "{mcp_name}"
3. 安装新 MCP：
   • claude/iflow: claude mcp add-json "{name}" "{config}"
   • qoder: qodercli mcp add {name} -- {command} {args}
4. 显示安装结果

项目结构

vibe_package_manager/
├── src/vibe_pm/
│   ├── __init__.py
│   ├── cli.py                   # CLI 入口
│   ├── config_parser.py         # 配置解析
│   ├── version_utils.py         # 版本工具
│   ├── skill_sync.py            # SKILL 同步
│   ├── subagent_sync.py         # SubAgent 同步
│   └── mcp_installer.py         # MCP 安装
├── vibe_package.schema.json     # JSON Schema
├── vibe_package.example.json    # 示例配置
├── pyproject.toml               # 包配置
└── README.md                    # 本文件

系统要求

• Python 3.8+
• Git
• PyYAML

许可证

MIT License

Copyright (c) 2026 Vibe Package Manager Team