# Vibe 包管理器

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

## 功能特性

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

## 安装
```
pipx install vibe-package-manager
```

or

```
python3 -m pip install vibe-package-manager
```

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

## 快速开始

### 1. 创建配置文件

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

```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. 验证配置

```bash
vpm validate
```

### 3. 安装依赖

```bash
vpm install
```

## vibe_package.json 配置详解

### 基本结构

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

### 参数说明

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

### target_agents

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

- `claude` - Claude Code
- `iflow` - iFlow CLI
- `qoder` - Qoder CLI

### dependencies

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

#### SKILL 类型

从 Git 仓库安装 SKILL 包。

**例子：**

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

**多 SKILL 仓库（使用 path）：**

```json
{
  "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 标签或分支名 |
| `type` | 字符串 | 是 | 必须是 `"SKILL"` |
| `path` | 字符串 | 否 | 仓库内子目录路径，用于多 SKILL 仓库 |

**SKILL 仓库结构：**
```
skill-repo/
└── SKILL.md          # 必须包含元数据
```

#### SubAgent 类型

从 Git 仓库安装 SubAgent 包。

**例子：**

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

**多 SubAgent 仓库（使用 path）：**

```json
{
  "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 标签或分支名 |
| `type` | 字符串 | 是 | 必须是 `"SUBAGENT"` |
| `path` | 字符串 | 否 | 仓库内子目录路径 |

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

**SubAgent 递归依赖：**

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

```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 服务器。

**例子：**

```json
{
  "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 文件中定义元数据：

```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 助手及其版本要求：

```yaml
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
```

**版本匹配规则：**
- 精确版本：`"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

安装所有依赖：

```bash
vpm install                    # 基本安装
vpm install -c config.json     # 指定配置文件
vpm install --debug            # 启用调试日志
vpm install --no-cleanup       # 保留 .vibe_package 目录
vpm install --continue-on-error # 出错时继续处理其他依赖
```

**选项说明：**
| 选项 | 说明 |
|------|------|
| `-c, --config` | 指定配置文件路径（默认搜索当前目录） |
| `-d, --debug` | 显示详细调试信息 |
| `--no-cleanup` | 保留临时目录用于调试 |
| `--continue-on-error` | 单个依赖失败时继续处理其他 |

### vpm validate

验证配置文件：

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

### vpm --version

显示版本信息：

```bash
vpm --version
vpm -v
```

## 完整配置示例

```json
{
  "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"
    },
    "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. 克隆 Git 仓库到 `.vibe_package/skills/[SKILL_NAME]/`
2. 处理单目录仓库结构
3. 移除 `.git` 目录
4. 验证 `SKILL.md` 存在
5. 读取并验证元数据（version, support_agents）
6. 检查与目标代理的版本兼容性
7. 复制到目标目录：`.claude/skills/`、`.iflow/skills/`、`.qoder/skills/`

### SubAgent 安装流程

1. 克隆 Git 仓库到 `.vibe_package/agents/[SUBAGENT_NAME]/`
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
