252 lines
7.7 KiB
Markdown
252 lines
7.7 KiB
Markdown
# 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 🦀 构建，追求可靠性与性能 |