/// 快速开始

Squad 文档

Squad 是一个 token-efficient 的多智能体编排框架，为 Claude Code 和 Cursor IDE 设计。通过智能路由和串行执行，Squad 帮助你高效地协调专业 AI 智能体完成开发任务。

✅ 多 IDE 支持
  • Claude Code - 完整支持
  • Cursor IDE - 完整支持
  • 自动检测 - Squad 在运行时自动识别 IDE 环境

安装指南

安装方法

# 克隆仓库
git clone https://github.com/yourusername/squad.git
cd squad

# 安装
./install.sh

# 验证安装
ls ~/.claude/rules/00-squad-core.md
安装器会执行以下操作：
  1. 同时安装到 Claude Code (~/.claude/) 和 Cursor IDE (~/.cursor/)
  2. 复制规则、智能体和命令到两个 IDE 目录
  3. 在 ~/.squad/ 创建共享的路由配置
  4. 可选：为两个 IDE 添加文件权限

首次配置

运行配置向导：

/squad config

选择：

  • 语言 - 中文或 English
  • 权限级别 - Conservative（保守）、Balanced（平衡）或 Autonomous（自主）

第一个任务

持久模式（推荐）

# 进入持久模式
/squad

# 现在所有消息自动路由
修复登录按钮                    → 💻 @工程师:前端
优化数据库查询                   → 💻 @工程师:后端
查找认证代码                     → 🔍 @研究员:代码库

# 退出持久模式
/exit

单次模式

# 执行一次任务后退出
/squad 修复登录按钮

# 手动指定智能体
/squad @engineer:backend 优化查询
/// 核心概念

架构概览

Squad 采用简洁的串行执行模型，通过智能路由将任务分配给最合适的智能体：

用户请求
    ↓
路由器（任务分析）
    ↓
智能体选择（带标签）
    ↓
串行执行
    ↓
结果聚合

核心原则

  • Token 效率优先 - 串行执行而非并行，最小化 token 消耗
  • 智能路由 - 关键词匹配自动选择最优智能体
  • 专业分工 - 每个智能体专注于特定领域
  • 渐进复杂性 - 从简单开始，按需扩展

路由机制

工作原理

Squad 分析你的任务描述，通过关键词匹配自动路由到合适的智能体：

任务: "修复登录按钮"
  ↓
检测关键词: [按钮, 登录, 修复]
  ↓
匹配: frontend（按钮 → UI 工作）
  ↓
路由: 工程师:前端 💻
  ↓
使用前端专用指令执行

路由优先级

优先级 方法 示例
1 手动指定 /squad @engineer:frontend 添加暗色模式
2 关键词匹配 自动检测 "按钮" → frontend
3 默认回退 无法匹配 → Engineer:fullstack

路由可见性

每个任务执行前都会显示路由决策：

/squad 修复登录按钮

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ SQUAD | 路由决策
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💻 @工程师:前端
   原因: UI 按钮实现
   预期: 修复登录按钮对齐问题

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
详细模式

使用 --verbose 标志查看详细的路由分析过程：

/squad --verbose 修复登录按钮

标签系统

标签允许每个智能体拥有多个专业化变体，无需创建新的智能体。这样可以保持智能体数量少，同时提供精细的控制。

标签示例

智能体 标签 用途
设计师 ui 视觉设计和 UI 一致性
ux 用户体验和交互设计
accessibility 无障碍和 WCAG 合规
工程师 frontend UI/UX、组件、样式
backend API、数据库、服务器逻辑
fullstack 通用实现（默认）
测试员 unit 单元测试
integration 集成测试
e2e 端到端测试

持久模式

持久模式让你一次激活 Squad，然后持续使用，无需每次都输入 /squad。这是推荐的使用方式。

工作原理

/squad (无参数)
    ↓
进入持久模式
    ↓
所有用户输入 → 自动路由到 Squad
    ↓
/exit
    ↓
退出持久模式

优势

  • ✅ 一次激活，持续使用
  • ✅ 自然的对话流程
  • ✅ 无需每次输入 /squad
  • ✅ 适合长时间开发会话
注意

在持久模式下，Squad 会检查每条消息是否以 / 开头。如果是命令，则正常处理；否则自动路由到 Squad。

/// 智能体详解

4 个专业智能体

🎨
设计师 / Designer
设计评估专家

负责设计评估、UX 审查和无障碍审计。你的设计顾问，确保视觉一致性、用户体验质量和 WCAG 合规性。

ui ux accessibility

模型: Haiku (高性价比)

工具: Read, Glob, Grep (只读)

触发关键词

  • UI: design review, visual design, color scheme, typography
  • UX: user experience, user flow, interaction, usability
  • Accessibility: a11y, contrast, screen reader, WCAG
  • 中文: 设计评审, 视觉设计, 用户体验, 无障碍

使用示例

# UI 设计评审
/squad @designer:ui 评审登录页面设计

# UX 用户体验分析
/squad @designer:ux 分析购物车流程的用户体验

# 无障碍审查
/squad @designer:accessibility 检查按钮的对比度和 ARIA 标签
🔍
研究员 / Researcher
代码情报专家

探索代码库、搜索文件、分析架构。你的侦察专家，在行动前发现模式、理解依赖关系并收集情报。

codebase documentation

模型: Haiku (高性价比)

工具: Read, Glob, Grep, WebSearch

触发关键词

  • explore, find, search, understand, analyze, investigate
  • 中文: 探索, 查找, 搜索, 理解, 分析, 调查

使用示例

# 探索代码库
/squad 查找用户认证的实现位置

# 分析架构
/squad @researcher:codebase 分析支付模块的依赖关系

# 查找文档
/squad @researcher:documentation 找到 API 参考文档
💻
工程师 / Engineer
代码实现专家

实现功能、修复 Bug、编写代码。你的实战专家，精通前端、后端和全栈操作。完成任务。

frontend backend fullstack

模型: Sonnet (默认) / Opus (复杂任务)

工具: Read, Write, Edit, Bash, Glob, Grep

触发关键词

  • General: implement, add, create, build, fix, update, refactor
  • Frontend: ui, button, page, component, style, css, react, vue
  • Backend: api, database, query, server, endpoint, sql, auth
  • 中文: 实现, 添加, 创建, 修复, 更新, 重构

使用示例

# 前端开发
/squad @engineer:frontend 添加暗色模式切换按钮

# 后端开发
/squad @engineer:backend 优化用户查询的数据库性能

# 全栈开发
/squad 实现密码重置功能
🚦
测试员 / Tester
质量保证专家

运行测试、验证构建、确保质量。你的 QA 专家，通过单元测试、集成测试和端到端测试协议验证每次部署。

unit integration e2e

模型: Haiku (高性价比)

工具: Read, Bash, Glob

触发关键词

  • test, verify, check, validate, run tests, build
  • 中文: 测试, 验证, 检查, 运行测试, 构建

使用示例

# 单元测试
/squad @tester:unit 运行 auth 模块的单元测试

# 集成测试
/squad @tester:integration 测试支付流程的集成

# 端到端测试
/squad @tester:e2e 运行登录到结账的完整流程测试
/// 技能系统

16+ 专业技能模块

Skills 是智能体可以调用的专业化工具。与智能体（处理完整工作流）不同，Skills 提供聚焦的实用功能。

什么是 Skills?

Skills 是可扩展、即插即用的专业化能力模块。智能体根据任务需求动态调用相应的 Skills，实现更强大和灵活的功能。

前端设计类 (7个)

frontend-design
创建独特、生产级前端界面，高设计质量
web-artifacts-builder
构建复杂多组件 HTML artifacts (React, Tailwind, shadcn/ui)
canvas-design
创建美观的视觉艺术 (.png, .pdf)
algorithmic-art
使用 p5.js 创建算法艺术
theme-factory
为 artifacts 应用主题样式 (10+ 预设主题)
brand-guidelines
应用 Anthropic 官方品牌色和字体
slack-gif-creator
创建优化的 Slack 动画 GIF

文档处理类 (5个)

doc-coauthoring
结构化文档协作工作流
pdf
PDF 操作工具包（提取、创建、合并、表单）
xlsx
电子表格创建、编辑和分析
docx
Word 文档创建、编辑和跟踪更改
pptx
演示文稿创建、编辑和分析

开发工具类 (4个)

webapp-testing
使用 Playwright 测试本地 Web 应用
mcp-builder
构建高质量 MCP 服务器
skill-creator
创建有效的 Squad Skills
keybindings-help
自定义键盘快捷键

其他工具 (2个)

translate
智能翻译（代码、文档、学术论文）
internal-comms
内部沟通模板和格式
/// 命令参考

所有命令

/squad

进入持久模式或执行单次任务

语法

# 进入持久模式
/squad

# 单次执行
/squad [任务描述]

# 手动指定智能体和标签
/squad @[智能体]:[标签] [任务描述]

# 选项
/squad --verbose [任务]     # 显示详细路由分析
/squad --help               # 显示帮助信息
/squad --lang zh            # 使用中文（当前命令）

示例

# 自动路由
/squad 修复登录按钮

# 手动指定
/squad @researcher 查找认证代码
/squad @engineer:backend 优化数据库
/squad @tester:unit 运行测试

/squad config

交互式配置向导

配置内容

  • 语言偏好 - 中文或 English
  • 权限级别 - Conservative, Balanced, Autonomous
/squad config

/squad reflect

分析性能并提出改进建议

功能

  • 分析对话表现（哪些做得好/可以改进）
  • 识别改进机会
  • 生成高置信度建议（低回归风险）
  • 谨慎应用批准的更改
  • 完整备份和回滚支持
# 反思和改进
/squad reflect

# 回滚到之前的版本
/squad rollback abc123

/exit

退出 Squad 持久模式

别名

/exit
/quit
/squad exit
/// 配置指南

配置 Squad

语言设置

Squad 原生支持中文和英文。

通过配置向导

/squad config

通过命令

# 切换到中文
/squad set-lang zh

# 切换到英文
/squad set-lang en

手动编辑

编辑 ~/.squad/config.yaml：

language: zh  # en | zh

权限级别

Squad 支持三种权限级别来控制智能体的自主程度：

🛡️ Conservative (保守)

理念: 安全第一，手动控制

行为

  • ✋ 每次文件操作前询问
  • ✋ 所有命令执行前询问
  • ✋ Git 操作前询问
  • ✅ 自动允许只读操作

适用于: 学习、关键项目、严格变更管理

⚖️ Balanced (平衡) - 推荐

理念: 信任但验证关键操作

行为

  • ✅ 自动允许常见操作（创建/编辑文件、运行测试、git commit）
  • ✋ 删除文件前询问
  • ✋ Git push 前询问
  • ✋ 破坏性命令前询问

适用于: 日常开发、大多数项目

🚀 Autonomous (自主)

理念: 全自动化，最小干预

行为

  • ✅ 自动允许所有操作
  • ⚠️ 详细日志记录
  • 🛟 破坏性操作前自动备份
  • 📝 清晰的提交信息

适用于: 长期项目（24+ 小时）、原型开发

⚠️ 谨慎使用 - 需要高信任度

设置权限级别

# 通过配置向导
/squad config

# 或手动编辑
# ~/.squad/config.yaml
language: zh
permission_level: balanced
permission_level: balanced  # conservative | balanced | autonomous

permissions:
  allow_file_create: true
  allow_file_edit: true
  allow_file_delete: false
  allow_git_commit: true
  allow_git_push: false
  allow_commands: true
  allow_destructive_commands: false
  allow_config_changes: false

路由规则自定义

编辑 ~/.squad/router.yaml 自定义路由规则：

engineer:
  frontend:
    keywords:
      - ui
      - button
      - page
      - component
      - style
      - css
      - html
      - react
      - vue
  backend:
    keywords:
      - api
      - database
      - query
      - server
      - endpoint
      - sql
      - auth
  fullstack:
    default: true

researcher:
  codebase:
    keywords:
      - explore
      - find
      - search
      - understand
      - analyze
    default: true
  documentation:
    keywords:
      - docs
      - readme
      - manual
      - guide

tester:
  unit:
    keywords:
      - test
      - verify
      - check
    default: true
  integration:
    keywords:
      - integration
      - api test
  e2e:
    keywords:
      - e2e
      - end-to-end
      - selenium
可扩展性

添加你自己的关键词、模式和规则。未来版本将支持正则表达式模式和置信度评分。

/// 使用场景

实战示例

场景 1: 探索代码库

/squad 查找用户认证的实现位置

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ SQUAD | 路由决策
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔍 @研究员:代码库
   原因: 需要定位和分析认证相关代码
   预期: 返回认证模块文件列表和流程概览

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# 研究员执行搜索...

✓ 任务完成 (12 秒)

📋 认证实现位置:
  - src/auth/login.ts:42 (主要逻辑)
  - src/middleware/auth.ts:15 (中间件)
  - src/api/auth.ts:23 (API 端点)

架构概览:
  登录流程: login.ts → 验证凭据 → 生成 JWT
  中间件: 每个受保护路由验证 token
  API: /api/auth/login, /api/auth/logout, /api/auth/refresh

场景 2: 实现新功能

/squad @engineer:frontend 添加暗色模式切换按钮

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ SQUAD | 路由决策
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💻 @工程师:前端
   原因: UI 组件实现，需要前端开发技能
   预期: 可交互的主题切换按钮，支持本地存储

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# 工程师开始实现...

▶ 实现中...
  ├─ 创建 ThemeToggle.tsx 组件
  ├─ 添加样式和动画效果
  ├─ 集成到 Header 组件
  └─ 添加 localStorage 持久化

✓ 任务完成 (45 秒)

文件变更:
✓ src/components/ThemeToggle.tsx (新建)
✓ src/components/Header.tsx (已修改)
✓ src/styles/themes.css (已修改)

功能说明:
- 点击按钮切换亮色/暗色模式
- 使用 localStorage 保存用户偏好
- 平滑过渡动画 (0.3s ease)

场景 3: 运行测试

/squad 运行所有测试

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▸ SQUAD | 路由决策
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🚦 @测试员:单元
   原因: 验证代码质量和测试覆盖率
   预期: 所有测试通过 + 覆盖率报告

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# 测试员执行测试套件...

▶ 执行中...
  ├─ 运行单元测试
  ├─ 运行集成测试
  └─ 生成覆盖率报告

✓ 任务完成 (23 秒)

测试结果:
  总计: 42 个测试
  通过: 42 ✅
  失败: 0

覆盖率:
  语句: 87.3%
  分支: 82.1%
  函数: 91.5%
  行: 86.8%

构建: ✅ 成功

场景 4: 多任务工作流

# 进入持久模式
/squad

# 1. 探索代码库
查找用户认证的实现           → 🔍 @研究员:代码库

# 2. 设计新功能
评审暗色模式设计方案          → 🎨 @设计师:界面

# 3. 实现功能
添加暗色模式切换按钮          → 💻 @工程师:前端

# 4. 运行测试
运行前端单元测试              → 🚦 @测试员:单元

# 5. 完成
/exit

准备开始？

安装 Squad，激活你的 AI 小队，主导开发流程。

GitHub 仓库 返回首页