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/pip 安装方式并升级到最新稳定版

安装

pipx install vibe-package-manager

or

python3 -m pip install vibe-package-manager

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

从旧版本首次升级到包含自升级能力的版本时，仍需按原安装方式执行一次：

pipx upgrade vibe-package-manager
# 或
python3 -m pip install --upgrade vibe-package-manager

此后可以统一使用 vpm upgrade。

快速开始

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 - 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 来源配置 path 时通过远程归档一次性下载目标子目录，不会 clone 仓库或创建 .git；同一仓库和版本的多个 path 会合并下载。未配置 path 时为兼容旧配置，仍会浅克隆并安装仓库根目录。 远端必须支持 git archive --remote（GitLab SSH 已支持）；归档失败时 VPM 会直接报错，不会自动回退为完整 clone。此时请改用可访问的分支/标签，或配置 zip 来源。

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 参数说明：

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 参数说明：

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 参数说明：

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"
---

内容...

元数据字段说明

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 # 出错时继续处理其他依赖
vpm install --exclude Askill   # 本次保留本地 Askill，不从远程覆盖
vpm install --no-update-check  # 本次安装不检查 VPM 新版本

选项说明：

多个临时排除项可以重复传入：

vpm install --exclude Askill --exclude Bskill

SKILL 名称按 vibe_package.json 的 dependencies 键精确匹配。被排除的 SKILL 不会下载、校验、复制或上报，其现有 Agent 目录保持不变。

需要在本机长期保留开发中的 SKILL 时，可在安装目标目录创建不会提交到 Git 的 .vpm.local.json：

{
  "install": {
    "exclude": ["Askill", "Bskill"]
  }
}

本地配置与命令行 --exclude 取并集。未使用 -c 时，安装目标目录是找到的 vibe_package.json 所在目录；使用 -c 时，安装目标目录是执行命令时的当前 目录。.vpm.local.json 格式无效会终止安装，避免保护规则被静默忽略。

默认情况下，VPM 会在安装前清理旧的 .vibe_package，并在安装成功、失败或中断后再次清理。 如果临时目录因权限或文件占用无法删除，安装会返回失败并显示残留路径，避免缓存静默堆积。 vpm install 会以 [TIME] 输出配置解析、Agent 检测、远程归档下载、每个依赖、各依赖类型汇总、安装上报、VPM 更新检查、两阶段清理和完整安装的耗时。总耗时包含安装前与安装后的两次环境清理；使用 --no-cleanup 时第二阶段会标记为 [skipped]。

默认最多每 24 小时从 PyPI 检查一次 VPM 最新稳定版，只显示提醒，不会在安装依赖时自动升级。网络检查有 2 秒硬超时；检查后会明确提示已是最新版、本地版本更高，或给出 vpm upgrade 升级命令。检查失败不会影响安装；失败结果缓存 1 小时。除 --no-update-check 外，也可以设置 VPM_DISABLE_UPDATE_CHECK=1，在 CI 或离线环境中关闭检查。

vpm upgrade

升级 VPM 到 PyPI 最新稳定版：

vpm upgrade

VPM 会识别当前安装是否由 pipx 或 pip 管理，并调用对应升级命令。源码、Git 直装和 editable 安装不会被自动切换到 PyPI，命令会给出手动更新提示。升级不会自动使用 sudo、--user、--break-system-packages，也不会安装预发布版本。

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