Metadata-Version: 2.4
Name: vibe-package-manager
Version: 1.3.1
Summary: A package manager for managing SKILLs, SubAgents, and MCPs
Home-page: https://github.com/YOUR_USERNAME/vibe_package_manager
Author: Vibe Package Manager Team
Author-email: Vibe Package Manager Team <maintainer@example.com>
License: MIT
Project-URL: Homepage, https://github.com/YOUR_USERNAME/vibe_package_manager
Project-URL: Documentation, https://github.com/YOUR_USERNAME/vibe_package_manager#readme
Project-URL: Repository, https://github.com/YOUR_USERNAME/vibe_package_manager.git
Project-URL: Issues, https://github.com/YOUR_USERNAME/vibe_package_manager/issues
Keywords: package-manager,skills,agents,mcp,claude,iflow
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Software Distribution
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Requires-Dist: importlib-metadata>=1.0; python_version < "3.8"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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` 命令。

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

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

此后可以统一使用 `vpm upgrade`。

## 快速开始

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

**Git 来源：**

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

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

```json
{
  "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）：**

```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_tag` | 字符串 | 二选一 | Git 标签或分支名（与 `git` 配合使用） |
| `zip` | 字符串 | 二选一 | Zip 包的 URL 或本地文件路径（与 `git`+`git_tag` 互斥） |
| `type` | 字符串 | 是 | 必须是 `"SKILL"` |
| `path` | 字符串 | 否 | 要下载的非空相对子目录；Git 来源会远程归档该目录而不 clone |

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

#### SubAgent 类型

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

**Git 来源：**

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

**Zip 来源：**

```json
{
  "dependencies": {
    "code-reviewer": {
      "zip": "https://example.com/agents/code-reviewer.zip",
      "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_tag` | 字符串 | 二选一 | Git 标签或分支名（与 `git` 配合使用） |
| `zip` | 字符串 | 二选一 | Zip 包的 URL 或本地文件路径（与 `git`+`git_tag` 互斥） |
| `type` | 字符串 | 是 | 必须是 `"SUBAGENT"` |
| `path` | 字符串 | 否 | 要下载的非空相对子目录；Git 来源会远程归档该目录而不 clone |

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

安装所有依赖：

```bash
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 新版本
```

**选项说明：**
| 选项 | 说明 |
|------|------|
| `-c, --config` | 指定配置文件路径（默认搜索当前目录） |
| `-d, --debug` | 显示详细调试信息 |
| `--no-cleanup` | 安装前清理历史缓存，安装后保留本次临时目录用于调试 |
| `--continue-on-error` | 单个依赖失败时继续处理其他 |
| `--exclude SKILL` | 本次跳过指定 SKILL 并保留本地目录；可重复传入 |
| `--no-update-check` | 本次安装不检查 VPM 新版本 |

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

```bash
vpm install --exclude Askill --exclude Bskill
```

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

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

```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 最新稳定版：

```bash
vpm upgrade
```

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

### 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"
    },
    "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
