# 快速开始指南

## 安装

### 方式 1：从源码安装

```bash
git clone git@gitlab.alibaba-inc.com:harness_engineering/vibe_package_manager.git
cd vibe_package_manager
pip install -e .
```

### 方式 2：通过 pip 安装（发布后）

```
pipx install vibe-package-manager
```

or

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

## 基本用法

### 1. 创建 vibe_package.json

复制示例文件：

```bash
cp vibe_package.example.json vibe_package.json
```

编辑 `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 参数说明

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

## 依赖类型示例

### SKILL 示例

```json
{
  "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"
    }
  }
}
```

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `git` | 字符串 | 是 | Git 仓库地址 |
| `git_tag` | 字符串 | 是 | Git 标签或分支名 |
| `type` | 字符串 | 是 | 必须是 `"SKILL"` |
| `path` | 字符串 | 否 | 仓库内子目录路径 |

### SubAgent 示例

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

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `git` | 字符串 | 是 | Git 仓库地址 |
| `git_tag` | 字符串 | 是 | Git 标签或分支名 |
| `type` | 字符串 | 是 | 必须是 `"SUBAGENT"` |
| `path` | 字符串 | 否 | 仓库内子目录路径 |

### MCP 示例

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

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

## 创建自己的 SKILL

1. 创建 Git 仓库
2. 添加 `SKILL.md` 文件，包含元数据：

```markdown
---
name: my-skill
description: 我的 SKILL 描述
version: 1.0.0
support_agents:
  iflow: "1.0.0"
  claude: "^2.0.0"
  qoder: "^1.0.0"
---

你的 SKILL 内容...
```

3. 打标签：`git tag v1.0.0`
4. 推送到 GitHub
5. 添加到 `vibe_package.json`

## 创建自己的 SubAgent

1. 创建 Git 仓库
2. 添加 markdown 文件（如 `my-agent.md`）：

```markdown
---
name: my-agent
description: 我的 Agent 描述
version: 1.0.0
support_agents:
  iflow: "1.0.0"
  claude: "^2.0.0"
  qoder: "^1.0.0"
tools: Read, Write, Bash
model: inherit
---

你的 Agent 指令...
```

3. 打标签：`git tag v1.0.0`
4. 推送到 GitHub
5. 添加到 `vibe_package.json`

## version 和 support_agents 字段

### version 字段

使用语义化版本号：

```yaml
version: 1.0.0
```

### support_agents 字段

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

```yaml
support_agents:
  iflow: "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

## 命令选项

```bash
vpm install                    # 安装所有依赖
vpm install --debug            # 启用调试日志
vpm install --no-cleanup       # 保留 .vibe_package 临时目录
vpm install --continue-on-error # 出错时继续处理其他依赖
vpm validate                   # 验证 vibe_package.json
vpm validate -c path/to/config.json  # 验证指定配置文件
vpm --version                  # 显示版本
```

## 故障排除

### 找不到 Git
确保 Git 已安装并添加到 PATH。

### 权限错误
某些操作可能需要管理员权限，特别是安装 MCP 时。

### 版本警告
版本兼容性警告不会阻止安装，但建议查看并更新版本。

## 下一步

- 阅读完整的 [README.md](README.md) 了解详细文档
- 查看 [examples](examples/) 目录中的示例
