AI-Agent-Team - 完整学习教程

教程级别： 从零到一 预计学习时间： 3-4 小时 前置知识： 命令行基础（中级）、Claude Code 基本使用、npm/Node.js 基础

环境搭建指南

系统要求

• 操作系统：macOS 12+、Ubuntu 20.04+、Windows 10+（需 PowerShell 5.0+）
• Node.js 版本：18.0 或更高
• Claude Code：已安装并配置（claude --version 可正常运行）
• 磁盘空间：至少 50MB（含内置向量模型）

安装步骤

# 1. 确认 Node.js 和 Claude Code 已安装
node --version
claude --version

# 2. 全局安装 AI-Agent-Team
npm install -g ai-agent-team

# 3. 初始化配置（全局模式，推荐）
ai-agent-team init

# 4. 启用 Thread Manager MCP Server（将路径替换为你的实际项目路径）
claude mcp add thread-manager node "$HOME/.claude/skills/thread-manager/dist/index.js"

注意事项： - 步骤 3 的 ai-agent-team init 必须执行，否则智能体配置文件不会被创建。 - 步骤 4 的路径需要根据实际安装位置调整。如果使用项目本地初始化，路径为 ./.claude/skills/thread-manager/dist/index.js。 - macOS/Linux 用户也可以使用 Shell 脚本安装：curl -fsSL https://raw.githubusercontent.com/peterfei/ai-agent-team/main/install.sh | bash

验证安装

# 重启 Claude Code
claude

# 在 Claude Code 中测试智能体命令
/pm "测试连接"

# 测试 Thread Manager
/threads

执行结果：

# /pm "测试连接" 应返回 PM 角色的响应
# /threads 应返回线程列表（初次安装为空列表）

第一部分：入门篇

1.1 理解智能体角色（Agent Roles）

概念讲解：

AI-Agent-Team 提供了 6 个预配置的智能体角色，每个角色对应真实软件团队中的一个职位。这些角色通过 .claude/agents/ 目录下的 Markdown 文件定义，包含角色描述、职责范围和行为规范。

6 个角色及其对应命令：

代码示例：

# 在 Claude Code 中调用产品经理智能体
/pm "分析一个在线书店系统的核心功能需求"

# 调用前端开发智能体
/fe "设计在线书店的首页布局，包括搜索栏、分类导航和推荐列表"

# 调用后端开发智能体
/be "设计在线书店的图书搜索 API，支持按书名、作者、分类搜索"

# 调用测试工程师智能体
/qa "设计图书搜索 API 的测试用例，包括正常搜索、空结果、特殊字符等场景"

# 调用 DevOps 智能体
/ops "设计在线书店的 Docker 部署方案，包括前端、后端和数据库容器"

# 调用技术负责人智能体
/tl "评审在线书店的微服务架构设计，评估技术选型合理性"

执行结果：

# 每个命令会以对应角色的视角和专业术语回答
# 例如 /pm 会输出产品需求文档格式的内容
# 例如 /qa 会输出测试用例表格

练习题： 1. 使用 /pm 分析一个你正在开发的项目需求，观察输出格式与直接使用 Claude Code 的区别。 2. 分别用 /fe 和 /be 对同一功能进行前端和后端设计，对比两个角色的视角差异。

1.2 理解快捷命令映射（Command Mapping）

概念讲解：

快捷命令（如 /pm、/fe）是通过 .claude/commands/ 目录下的 Markdown 文件实现的。每个命令文件内部引用对应的智能体配置文件，将用户的简短命令转换为完整的智能体调用。

了解这个映射机制很重要，因为它是自定义和扩展的基础。

代码示例：

查看命令映射文件的内容：

# 查看 PM 命令映射文件
cat ~/.claude/commands/pm.md

# 查看 FE 命令映射文件
cat ~/.claude/commands/fe.md

执行结果：

# pm.md 文件内容示例（简化）：
# 加载 product_manager 智能体配置
# 将用户输入作为任务传递给 PM 角色

# fe.md 文件内容示例（简化）：
# 加载 frontend_dev 智能体配置
# 将用户输入作为任务传递给前端开发角色

练习题： 1. 查看 6 个命令映射文件的内容，理解命令到智能体的映射关系。 2. 尝试直接使用 Claude Code 的智能体调用方式（而非快捷命令）调用 PM 角色。

1.3 使用 CLI 工具调用智能体

概念讲解：

除了在 Claude Code 交互界面中使用快捷命令外，AI-Agent-Team 还提供了独立的 CLI 工具，可以直接从命令行调用智能体。这种方式适合集成到 Shell 脚本或自动化工作流中。

代码示例：

# 使用 CLI 工具调用 PM（macOS/Linux）
~/.claude/agents/cli.sh pm "分析电商平台的核心功能"

# 使用中文名称调用
~/.claude/agents/cli.sh 产品经理 "分析电商平台的核心功能"

# 使用 CLI 工具调用后端开发
~/.claude/agents/cli.sh backend "设计用户注册 API"

# 使用中文名称调用
~/.claude/agents/cli.sh 后端 "设计用户注册 API"

# Windows 用户使用 PowerShell
# .\.claude\agents\cli.ps1 pm "分析电商平台的核心功能"

执行结果：

# CLI 工具会显示彩色输出界面
# 包含智能体名称、任务描述和下一步建议
# 实际 AI 响应会在 Claude Code 中生成

注意事项： - CLI 工具仅提供命令行界面包装，实际的 AI 处理仍由 Claude Code 完成。 - CLI 支持中英文智能体名称映射（如 pm 和 产品经理 都指向 PM 角色）。

练习题： 1. 使用 CLI 工具分别调用 3 个不同的智能体角色，观察输出格式。 2. 尝试在 Shell 脚本中串联调用多个智能体（如先 PM 分析需求，再 BE 设计 API）。

第二部分：进阶篇

2.1 Thread Manager 线程管理

详细讲解：

Thread Manager 是 AI-Agent-Team 的核心差异化组件。它通过 MCP Server 为 Claude Code 提供了持久化的对话记忆和多任务线程管理能力。

核心功能： - 线程创建：通过 /pm-start、/fe-start 等命令创建角色专属线程 - 线程切换：通过 /thread switch 在不同任务之间切换，自动恢复上下文 - 线程查看：通过 /threads 查看所有活跃线程的状态 - 语义搜索：通过自然语言查询历史消息，基于本地向量嵌入

代码示例：

# 创建产品经理任务线程（自动初始化 PM 角色）
/pm-start "设计用户认证系统"

# 创建后端开发线程（同时进行多个任务）
/be-start "实现 JWT 认证 API"

# 创建前端开发线程
/fe-start "设计登录页面组件"

# 查看所有活跃线程
/threads

# 切换到后端开发线程（完整恢复上下文）
/thread switch <thread-id>

# 查看当前线程详情
/thread info

执行结果：

# /pm-start 输出：
# ✅ 线程已创建：pm-user-auth-20251212
# 📋 角色：产品经理
# 📝 任务：设计用户认证系统
# 💾 对话将自动保存

# /threads 输出：
# 📋 活跃线程列表：
# 1. pm-user-auth (产品经理) - 15 条消息
# 2. be-jwt-api (后端开发) - 8 条消息
# 3. fe-login-page (前端开发) - 3 条消息

# /thread switch 输出：
# ✅ 已切换到线程：be-jwt-api
# 📋 已恢复 8 条历史消息
# 📁 已恢复 3 个文件变更记录

注意事项： - Thread Manager 必须通过 claude mcp add thread-manager 命令注册后才能使用。如果 /threads 命令不可用，说明 MCP Server 未正确配置。 - 线程数据存储在本地 SQLite 数据库中，路径通常为 .claude/skills/thread-manager/data/。 - 切换线程时会重置上下文窗口，只加载当前线程的历史消息，避免 Token 浪费。

练习题： 1. 创建 3 个不同角色的任务线程，然后在它们之间切换，验证上下文恢复是否正确。 2. 关闭 Claude Code 并重新打开，检查之前的线程是否仍然存在。

2.2 语义搜索历史消息

详细讲解：

Thread Manager v2.0.1 引入了基于向量嵌入的语义搜索能力。所有对话消息在存储时会自动通过 Xenova/all-MiniLM-L6-v2 模型生成向量表示，后续可通过自然语言查询进行语义匹配检索。

与关键词搜索的区别：语义搜索理解意图。例如搜索"之前讨论的登录方案"可以匹配到包含"身份验证机制设计"的消息。

代码示例：

# 在当前线程中搜索历史消息
"帮我找一下之前讨论的数据库设计方案"

# 跨线程搜索所有历史记录
"搜索所有关于 API 认证token 的讨论"

# 搜索特定时间段的消息
"查找上周关于部署策略的讨论"

执行结果：

# 语义搜索会返回最相关的历史消息片段
# 🔍 搜索结果（来自线程 be-jwt-api）：
# [2025-12-10] 后端开发：JWT token 结构设计...
# - 使用 RS256 算法签名
# - token 有效期 24 小时
# - refresh token 有效期 7 天

注意事项： - 语义搜索使用本地模型（Xenova/all-MiniLM-L6-v2），无需联网，但模型主要针对英文优化。中文查询的检索精度可能低于英文。 - 首次使用时模型需要初始化，可能有短暂的延迟。 - 向量嵌入的维度为 384 维（all-MiniLM-L6-v2 的输出维度），适合中小规模数据。

练习题： 1. 在一个线程中讨论某个技术话题，然后在新线程中通过语义搜索找回之前的讨论。 2. 分别用中文和英文查询同一内容，对比检索结果的相关性。

2.3 使用实用技能（Skills）

详细讲解：

AI-Agent-Team 提供了 4 个实用技能，扩展 Claude Code 的日常使用场景。这些技能存放在 .claude/skills/ 目录下，每个技能包含 SKILL.md 描述文件和配套脚本。

代码示例：

# === DrawNote - 可视化笔记 ===
# 生成彩色手写笔记风格的信息图
"请用彩色手写笔记风格生成 'React Hooks 生命周期' 的信息图"

# 生成科技风格的技术架构图
"请用科技创新风格创建 '微服务架构设计模式' 的流程图"

# === TidyMyDesktop - 桌面整理 ===
# 整理桌面（dry-run 模式先预览）
"帮我预览整理桌面的计划，不实际执行"

# 实际整理桌面
"帮我整理桌面，按文件类型分类"

# 整理指定目录
"帮我整理下载文件夹"

# === Changelog Generator - 变更日志 ===
# 生成 HTML 格式的变更日志
changelog-generate generate --all --format html

# 生成 Markdown 格式
changelog-generate generate --all --format markdown

# 创建 GitHub Release
changelog-generate release --github-release

# === SoftCopyright - 软著材料 ===
# 生成软件著作权申请材料
"帮我生成这个项目的软件著作权申请材料"

# 指定项目路径
"帮我生成 /path/to/project 的软著材料"

执行结果：

# DrawNote 输出：
# 📝 已生成信息图：drawnote_20251212_143000.html
# 📸 已生成截图：drawnote_20251212_143000.png

# TidyMyDesktop 输出：
# 📊 整理报告：
# - 应用程序：15 个 → 分类到 Applications/
# - 文档：8 个 → 分类到 Documents/
# - 图片：12 个 → 分类到 Images/
# - 其他：5 个 → 保持原位

# Changelog Generator 输出：
# 📝 已生成变更日志：CHANGELOG.html
# 包含 23 个 commit，4 个版本

# SoftCopyright 输出：
# 📄 已生成：软件说明书.html
# 📄 已生成：源代码文档.html
# 📊 源码统计：45 个文件，3200 行代码

注意事项： - DrawNote 依赖 Playwright 进行截图，首次使用需要安装浏览器引擎（npx playwright install chromium）。 - TidyMyDesktop 的 dry-run 模式只预览不执行，建议始终先 dry-run 确认后再实际执行。 - Changelog Generator 需要在 Git 仓库中运行，且需要至少一个 commit。 - SoftCopyright 生成的 HTML 文件需要通过浏览器打印为 PDF，页眉页脚会自动添加。

练习题： 1. 使用 DrawNote 为你当前正在学习的技术主题生成一张信息图。 2. 使用 TidyMyDesktop 的 dry-run 模式分析你的下载文件夹，查看分类计划。

第三部分：高级篇

3.1 自定义智能体配置

详细讲解：

AI-Agent-Team 的 6 个预定义角色是通用模板。在实际项目中，你可能需要创建自定义角色，例如数据科学家、安全工程师或 UI 设计师。自定义方法很简单：复制现有的智能体配置文件并修改。

代码示例：

# 1. 复制一个现有智能体配置作为模板
cp ~/.claude/agents/backend_dev.md ~/.claude/agents/data_scientist.md

# 2. 编辑新智能体配置文件
# 使用你喜欢的编辑器打开 data_scientist.md

编辑 ~/.claude/agents/data_scientist.md：

# 数据科学家（Data Scientist）

## 角色描述
你是一位资深数据科学家，专注于数据分析、机器学习模型开发和数据可视化。

## 核心职责
- 数据清洗和特征工程
- 机器学习模型选择和训练
- 数据可视化分析
- 实验设计和 A/B 测试

## 技术栈
- Python: pandas, scikit-learn, PyTorch
- 数据可视化: matplotlib, seaborn, plotly
- SQL 数据查询
- Jupyter Notebook

## 输出格式
- 分析报告使用 Markdown 格式
- 代码示例使用 Python
- 模型评估包含精确率、召回率、F1 等指标

创建对应的快捷命令 ~/.claude/commands/ds.md：

请以数据科学家的身份处理以下任务。
使用数据科学领域的专业知识和方法论。

# 3. 验证新智能体
claude
# 在 Claude Code 中使用：
/ds "分析这个销售数据的趋势和季节性模式"

执行结果：

# 自定义数据科学家智能体会以数据科学的专业视角回答
# 包含数据清洗建议、模型选择方案和可视化图表描述

注意事项： - 自定义智能体的 Markdown 文件命名会影响命令名称。例如 data_scientist.md 对应的命令取决于 commands 目录下的映射文件。 - 配置文件的内容会被 Claude Code 作为 System Prompt 加载，应避免包含敏感信息。 - 如果使用项目本地初始化（./.claude/），自定义配置只对当前项目生效。

3.2 Thread Manager 数据管理

详细讲解：

Thread Manager 的数据存储在本地 SQLite 数据库中。了解数据结构有助于备份、迁移和排查问题。

代码示例：

# 查看 Thread Manager 数据目录
ls ~/.claude/skills/thread-manager/data/

# 备份 Thread Manager 数据库
cp ~/.claude/skills/thread-manager/data/threads.db ~/threads_backup_$(date +%Y%m%d).db

# 查看数据库中的线程数量
sqlite3 ~/.claude/skills/thread-manager/data/threads.db "SELECT COUNT(*) FROM threads;"

# 查看所有线程的概要信息
sqlite3 ~/.claude/skills/thread-manager/data/threads.db \
  "SELECT id, agent_name, title, created_at FROM threads ORDER BY created_at DESC;"

# 迁移旧数据（如果从旧版本升级）
cd ~/.claude/skills/thread-manager
npm run migrate

执行结果：

# 数据目录内容：
# threads.db    - 主数据库文件
# embeddings/   - 向量嵌入缓存目录

# 线程数量：
# 12

# 线程概要：
# abc123|pm|用户认证系统|2025-12-10T10:00:00
# def456|be|JWT API 开发|2025-12-10T14:30:00
# ghi789|fe|登录页面|2025-12-11T09:00:00

注意事项： - SQLite 数据库文件不支持多进程并发写入。如果同时运行多个 Claude Code 实例访问同一个数据库，可能出现锁冲突。 - 数据库文件会随着使用不断增长，建议定期备份和清理不再需要的旧线程。 - 向量嵌入数据占用了大部分存储空间，清理旧线程会同时释放嵌入数据。

3.3 最佳实践

1. 任务描述要具体：为智能体提供清晰、具体的任务描述，包含技术栈、约束条件和期望输出格式。
2. 善用线程管理：为每个独立任务创建单独的线程，避免在单个线程中混合多个不相关的任务。
3. 先 dry-run 再执行：对于 TidyMyDesktop 等会修改文件系统的技能，始终先使用 dry-run 模式预览。
4. 定期备份数据：Thread Manager 的 SQLite 数据库包含所有对话历史，建议纳入常规备份。
5. 按需自定义角色：预定义角色是通用模板，根据项目实际需求调整智能体的 System Prompt 可以显著提升输出质量。

第四部分：实战项目

项目需求

使用 AI-Agent-Team 构建一个完整的博客系统开发工作流，涵盖从需求分析到部署的全流程。该项目需要：

1. PM 角色分析博客系统核心需求
2. Tech Lead 设计技术架构
3. 后端开发实现 RESTful API
4. 前端开发实现博客界面
5. QA 工程师设计测试方案
6. DevOps 工程师规划部署方案

同时使用 Thread Manager 管理跨角色的任务线程，使用 DrawNote 生成系统架构可视化。

项目设计

用户需求
  │
  ├─ /pm-start → 产品经理分析需求 → 输出需求文档
  │
  ├─ /tl → 技术负责人评审架构 → 输出技术方案
  │
  ├─ /be-start → 后端开发实现 API → 输出代码
  │
  ├─ /fe-start → 前端开发实现界面 → 输出代码
  │
  ├─ /qa-start → 测试工程师测试 → 输出测试报告
  │
  └─ /ops → DevOps 部署 → 输出部署方案

运用的知识点： - 智能体角色调用（1.1 节） - Thread Manager 线程管理（2.1 节） - 实用技能 DrawNote（2.3 节）

完整实现代码

# ==========================================
# 第一步：创建 PM 线程进行需求分析
# ==========================================

# 在 Claude Code 中执行
/pm-start "设计一个个人博客系统，需要支持文章发布、Markdown 编辑、标签分类、评论功能和 RSS 订阅"

# PM 输出需求文档后，保存到线程

# ==========================================
# 第二步：Tech Lead 设计技术架构
# ==========================================

/tl "基于 PM 的需求分析，设计博客系统的技术架构。技术栈：React + Node.js + PostgreSQL。评估是否需要引入缓存层和搜索服务"

# ==========================================
# 第三步：创建后端开发线程
# ==========================================

/be-start "基于技术架构，实现博客系统的核心 RESTful API。包括：
1. 用户认证（JWT）
2. 文章 CRUD（支持 Markdown）
3. 标签管理
4. 评论系统
5. RSS 订阅生成
使用 Express.js + PostgreSQL，包含数据库迁移脚本"

# ==========================================
# 第四步：创建前端开发线程
# ==========================================

/fe-start "基于后端 API 设计，实现博客前端界面。包括：
1. 文章列表页（分页、标签筛选）
2. 文章详情页（Markdown 渲染）
3. 文章编辑器（实时预览）
4. 评论组件
5. 响应式设计
使用 React + Tailwind CSS"

# ==========================================
# 第五步：创建 QA 线程
# ==========================================

/qa-start "设计博客系统的完整测试方案。包括：
1. API 接口测试（Postman/Newman）
2. 前端组件测试（React Testing Library）
3. 端到端测试（Cypress）
4. 性能测试（Lighthouse）
5. 安全测试（OWASP Top 10 检查清单）"

# ==========================================
# 第六步：查看所有线程进度
# ==========================================

/threads

# ==========================================
# 第七步：DevOps 部署方案
# ==========================================

/ops "设计博客系统的生产部署方案。包括：
1. Docker Compose 编排（前端、后端、数据库、Redis）
2. Nginx 反向代理配置
3. SSL 证书自动续期
4. CI/CD 流水线（GitHub Actions）
5. 监控和日志（Prometheus + Grafana）"

# ==========================================
# 第八步：使用 DrawNote 生成系统架构图
# ==========================================

"请用科技创新风格生成博客系统的微服务架构信息图，包含前端、后端 API、数据库、缓存、反向代理和 CI/CD 流水线"

# ==========================================
# 第九步：切换线程回顾各角色产出
# ==========================================

# 切换到 PM 线程回顾需求
/thread switch <pm-thread-id>

# 切换到后端线程检查 API 实现
/thread switch <be-thread-id>

# 切换到 QA 线程查看测试报告
/thread switch <qa-thread-id>

代码解析

1. 智能体角色调用（1.1 节知识点）：项目使用了全部 6 个智能体角色（PM、TL、BE、FE、QA、Ops），每个角色在其专业领域内提供深度分析和代码输出。/pm-start、/be-start、/fe-start、/qa-start 命令同时创建线程和初始化角色。

2. Thread Manager 线程管理（2.1 节知识点）：通过 /threads 查看所有任务线程的进度，通过 /thread switch 在不同线程之间切换，每次切换都完整恢复该线程的上下文。这解决了多任务并行开发时的上下文管理问题。

3. 实用技能 DrawNote（2.3 节知识点）：使用 DrawNote 技能生成系统架构的可视化信息图，帮助团队成员快速理解系统设计。输出的 HTML 和 PNG 文件可直接用于文档和演示。

扩展挑战

1. 添加自定义角色：创建一个"技术文档工程师"角色（Technical Writer），专门负责根据各角色的产出编写统一的 API 文档和用户手册。
2. 数据迁移自动化：编写 Shell 脚本，将 Thread Manager 中的各角色产出自动提取为独立的 Markdown 文件，按目录结构组织。
3. 多项目线程管理：在 Thread Manager 中同时管理两个不同项目的线程，验证线程隔离和上下文恢复的可靠性。

第五部分：常见问题与排查指南

常见错误及解决方案

调试技巧

1. 检查配置文件是否正确安装：运行 ls ~/.claude/agents/ 确认 6 个智能体配置文件存在。如果文件缺失，重新运行 ai-agent-team init。

2. 验证 MCP Server 运行状态：在 Claude Code 中执行 /threads 命令。如果返回线程列表（即使是空的），说明 MCP Server 正常运行。如果报错，检查 claude mcp list 确认 thread-manager 已注册。

3. 分层排查智能体问题：先用 claude -p "测试连接" 验证 Claude Code 本身正常工作，再用 /pm "测试" 验证智能体配置加载正确，最后测试 Thread Manager 等高级功能。

第六部分：学习路线推荐

官方文档推荐阅读顺序

1. GitHub README - 安装指南和功能概览（重点：3 步安装流程和验证方法）
2. 项目结构说明 - 理解 .claude/ 目录结构（重点：agents、commands、skills 三个目录的作用）
3. Thread Manager 使用指南 - 线程管理和语义搜索（重点：线程创建、切换和搜索命令）
4. 工作流程示例 - 完整开发流程演示（重点：角色协作模式）
5. 最佳实践 - 使用技巧和注意事项（重点：任务描述规范和迭代式开发）
6. CHANGELOG.md - 版本更新记录

推荐进阶资源

• Claude Code 官方文档 - Custom Agents - 深入理解 .claude/agents/ 配置格式和高级用法
• Claude Code 官方文档 - Plugins - 学习如何构建自己的 Claude Code 插件，理解 Skills 和 MCP Server 的完整机制
• Awesome Claude Code Subagents - 社区贡献的 100+ Claude Code 自定义智能体集合，可从中获取灵感和配置模板