# AI编码助手包管理器

`包管理器` `AI助手` `Claude Code` `Git` `Rust` `依赖管理`

# AGPM - AI智能体包管理器

> ⚠️ **测试版软件**：本项目正在积极开发中，在生产环境中使用请谨慎。

一个面向 AI 编码助手（Claude Code、OpenCode 等）的 Git 包管理器，通过基于锁文件的依赖管理实现可复现的安装，类似于 Cargo。

## 功能特性

- 📦 **基于锁文件的依赖管理** - 像 Cargo 一样实现可复现安装
- 🌐 **基于 Git 的分发** - 从任意 Git 仓库安装
- 🚀 **无中心注册表** - 完全去中心化方案
- 🤖 **多工具支持** - Claude Code、OpenCode（alpha）及自定义工具
- 🔧 **七种资源类型** - 智能体、代码片段、命令、脚本、钩子、MCP 服务器、技能（alpha）
- 🎯 **模式匹配依赖** - 使用 glob 模式批量安装
- 🖥️ **跨平台** - 支持 Windows、macOS 和 Linux
- 🔄 **传递依赖** - 自动依赖解析
- 📝 **Markdown 模板** - 支持依赖嵌入和项目文件过滤的动态内容生成（可选）
- 📊 **Token 计数** - 基于 BPE 的近似 Token 数统计，用于资源追踪

## 快速开始

### 安装

```bash
# macOS/Linux 通过 Homebrew
brew install aig787/homebrew-agpm/agpm-cli

# 所有平台通过 Cargo
cargo install agpm-cli

# 预构建二进制文件
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/aig787/agpm/releases/latest/download/agpm-installer.sh | sh
```

更多选项和平台特定说明请参阅[安装指南](docs/installation.md)。

### 基本用法

```bash
# 初始化新项目
agpm init

# 安装依赖
agpm install

# 检查更新
agpm outdated

# 更新依赖
agpm update

# 列出已安装的资源
agpm list
```

### 示例配置文件

```toml
# agpm.toml
[sources]
community = "https://github.com/aig787/agpm-community.git"

[agents]
# Claude Code 智能体（默认）
rust-expert = { source = "community", path = "agents/rust-expert.md", version = "v1.0.0" }

# OpenCode 智能体（alpha）
assistant-oc = { source = "community", path = "agents/assistant.md", version = "v1.0.0", tool = "opencode" }

[snippets]
# 共享代码片段（默认：.agpm/snippets/）
react-hooks = { source = "community", path = "snippets/react-hooks.md", version = "~1.2.0" }

[commands]
deploy = { source = "community", path = "commands/deploy.md", version = "v2.0.0" }

[skills]
# 基于目录的专业技能包（alpha）
rust-helper = { source = "community", path = "skills/rust-helper", version = "v1.0.0" }
```

更多完整示例请参阅 [docs/examples/](docs/examples/)。

## 核心命令

| 命令 | 描述 |
|-----------------|---------------------------------------------------|
| `agpm init` | 初始化新项目 |
| `agpm install` | 从 agpm.toml 安装依赖 |
| `agpm update` | 在版本约束范围内更新依赖 |
| `agpm outdated` | 检查可用更新 |
| `agpm upgrade` | 将 AGPM 自身升级到最新版本 |
| `agpm migrate` | 从旧版 AGPM 迁移到最新格式 |
| `agpm list` | 列出已安装的资源 |
| `agpm tree` | 显示带 Token 数量的依赖树 |
| `agpm validate` | 验证配置文件和依赖 |
| `agpm add` | 添加源或依赖 |
| `agpm remove` | 移除源或依赖 |
| `agpm config` | 管理全局配置 |
| `agpm cache` | 管理 Git 缓存 |

运行 `agpm --help` 查看完整命令参考，或查阅[命令参考文档](docs/command-reference.md)。

## 进度显示

AGPM 通过简洁专业的界面提供安装进度的实时可见性：

### 安装阶段

```
⠁ 同步源
✓ 源同步完成 (0.8s)

⠂ 解析依赖
✓ 已解析 500 个依赖 (1.2s)

⠄ 安装资源 (127/500 完成)
  → agents/helper-122
  → agents/helper-123
  → agents/helper-124
  → snippets/example-45
  → commands/lint-67
  → agents/helper-125
  → agents/helper-126

✓ 已安装 500 个资源 (12.3s)
  ✓ 300 个智能体
  ✓ 150 个代码片段
  ✓ 50 个命令

✓ 完成安装 (0.2s)

  已安装 500 个资源
  已配置 2 个 MCP 服务器
```

### 功能特点

- **活动窗口**：显示当前正在处理的资源（5-10 行）
- **实时更新**：资源的出现和完成实时展示
- **耗时信息**：每个阶段显示持续时间，便于性能分析
- **输出有界**：无论依赖数量多少，终端始终保持整洁
- **资源摘要**：按资源类型（智能体、代码片段等）显示最终汇总
- **专业展示**：简洁输出，无表情符号前缀

## 资源类型

AGPM 管理七种类型的资源，安装到 `agpm/` 子目录，便于 gitignore 管理：

- **智能体** - AI 助手配置（`.claude/agents/agpm/`、`.opencode/agent/agpm/`）
- **代码片段** - 可复用代码模板（`.agpm/snippets/`）
- **命令** - 斜杠命令（`.claude/commands/agpm/`、`.opencode/command/agpm/`）
- **脚本** - 可执行自动化文件（`.claude/scripts/agpm/`）
- **钩子** - 基于事件的自动化（→ `.claude/settings.local.json`）
- **MCP 服务器** - 模型上下文协议服务器（→ `.mcp.json`、`opencode.json`）
- **技能** - 基于目录的专业技能包（`.claude/skills/`）🚧 **Alpha**

详细信息请参阅[资源指南](docs/resources.md)。

## 模板功能

AGPM 为 Markdown 资源的动态内容生成提供了强大的模板功能：

### 依赖内容嵌入

嵌入来自 AGPM 依赖的版本化内容：

```markdown
---
agpm.templating: true
dependencies:
  snippets:
    - path: snippets/rust-patterns.md
      name: rust_patterns
---
# Rust 代码审查员

## 共享模式
{{ agpm.deps.snippets.rust_patterns.content }}
```

### 项目文件过滤

读取并嵌入项目特定文件（团队文档、公司规范）：

```markdown
---
agpm.templating: true
---
# 团队智能体

## 公司风格指南
{{ 'project/styleguide.md' | content }}

## 团队规范
{{ 'docs/conventions.txt' | content }}
```

**核心特性**：
- 🔒 **安全**：路径验证防止路径遍历攻击
- 📁 **仅限文本文件**：`.md`、`.txt`、`.json`、`.toml`、`.yaml`
- 🔄 **递归**：项目文件可引用其他项目文件（最深 10 层）
- 🎯 **组合使用**：支持同时使用依赖内容和项目文件

完整文档和示例请参阅[模板指南](docs/templating.md)。

## 文档

| 指南 | 描述 |
|-------|-------------|
| [安装指南](docs/installation.md) | 所有安装方式和系统要求 |
| [用户指南](docs/user-guide.md) | 入门指引和基本工作流 |
| [命令参考](docs/command-reference.md) | 完整命令语法和选项 |
| [多工具支持](docs/multi-tool-support.md) | 管理多个 AI 助手的资源 |
| [依赖指南](docs/dependencies.md) | 版本约束、冲突和传递依赖 |
| [资源指南](docs/resources.md) | 使用不同资源类型 |
| [配置指南](docs/configuration.md) | 全局配置、认证和补丁 |
| [配置文件参考](docs/manifest-reference.md) | 完整 agpm.toml 结构说明 |
| [版本控制指南](docs/versioning.md) | 版本约束和 Git 引用 |
| [模板指南](docs/templating.md) | 使用 Tera 进行动态内容生成 |
| [架构文档](docs/architecture.md) | 技术细节和设计决策 |
| [示例](docs/examples/) | 示例配置和使用场景 |
| [常见问题](docs/faq.md) | 常见问题解答 |
| [技能指南](docs/skills-guide.md) | 基于目录的专业技能包 |
| [故障排查](docs/troubleshooting.md) | 常见问题及解决方案 |

## 系统要求

- **Rust 1.85.0+**（从源码构建时需要）
- **Git 2.0+**（用于仓库操作）

## 贡献

欢迎贡献代码！详情请参阅[贡献指南](CONTRIBUTING.md)。

## 支持

- 🐛 [问题追踪](https://github.com/aig787/agpm/issues)
- 💬 [讨论区](https://github.com/aig787/agpm/discussions)
- 📖 [文档](docs/user-guide.md)

## 许可证

MIT 许可证 - 详情请参阅 [LICENSE.md](LICENSE.md)。

---

使用 Rust 🦀 构建，追求可靠性与性能