diff --git a/README.md b/README.md index ad5da73e8..36e3e1e7d 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Squad +[English](README.md) | [中文版](README.zh.md) + **AI agent teams for any project.** One command. A team that grows with your code. [![Status](https://img.shields.io/badge/status-alpha-blueviolet)](#status) diff --git a/README.zh.md b/README.zh.md new file mode 100644 index 000000000..eab148813 --- /dev/null +++ b/README.zh.md @@ -0,0 +1,258 @@ +# Squad (AI 开发小队) + +**为任何项目打造的 AI 智能体团队。** 一行命令，拥有一个随代码同步成长的开发团队。 + +[![状态](https://img.shields.io/badge/status-alpha-blueviolet)](#status) +[![平台](https://img.shields.io/badge/platform-GitHub%20Copilot-blue)](#what-is-squad) + +> ⚠️ **Alpha 预览版** — Squad 仍处于实验阶段。API 和命令行工具可能在版本更迭中发生变化。我们会在 [CHANGELOG.md](CHANGELOG.md) 中记录重大变更。 + +--- + +## 什么是 Squad? + +Squad 通过 GitHub Copilot 为你提供一支 AI 开发团队。只需描述你正在构建的内容，即可获得一支由专家组成的小队 —— 前端、后端、测试、组长 —— 它们以文件形式存在于你的仓库中。它们能够跨会话持久存在，学习你的代码库，共享决策，并且用得越多就越聪明。 + +这不仅仅是一个“戴着不同帽子”的聊天机器人。团队中的每个成员都在独立的上下文中运行，只读取属于自己的知识库，并将学到的内容写回。 + +--- + +## 快速开始 + +### 1. 创建项目 + +```bash +mkdir my-project && cd my-project +git init +``` + +**✓ 验证：** 运行 `git status` — 你应该看到 "No commits yet"。 + +### 2. 安装 Squad + +```bash +npm install -g @bradygaster/squad-cli +squad init +``` + +**✓ 验证：** 检查项目中是否创建了 `.squad/team.md`。 + +**或者使用 npx (无需安装)：** `npx @bradygaster/squad-cli` — 如果是从旧版本升级，请参考 [迁移指南](https://bradygaster.github.io/squad/docs/get-started/migration/)。 + +### 3. 登录 GitHub (用于 Issue、PR 和监控) + +```bash +gh auth login +``` + +**✓ 验证：** 运行 `gh auth status` — 你应该看到 "Logged in to github.com"。 + +### 4. 开启 Copilot 开启工作 + +``` +copilot --agent squad --yolo +``` + +> **为什么使用 `--yolo`？** Squad 在典型会话中会进行大量工具调用。不使用该选项，Copilot 会提示你逐一批准每一个调用。 + +**在 VS Code 中**，打开 Copilot Chat 并选择 **Squad** 智能体。 + +然后输入： + +``` +I'm starting a new project. Set up the team. +Here's what I'm building: a recipe sharing app with React and Node. +（我正在启动一个新项目。请组建团队。我要构建的是一个基于 React 和 Node 的食谱分享应用。） +``` + +**✓ 验证：** Squad 会返回团队成员建议。输入 `yes` 确认 —— 它们就准备好开工了。 + +Squad 会提议一个团队 —— 每个成员的名字都来自一个持久化的主题演员表（Cast）。你只需说 **yes**，它们就位。 + +--- + +## 所有命令 (15 条指令) + +| 命令 | 功能描述 | +|---------|-------------| +| `squad init` | **初始化** — 在当前目录初始化 Squad（幂等操作 — 可安全运行多次）；别名：`hire`；使用 `--global` 在个人目录初始化，`--mode remote ` 开启双根模式 | +| `squad upgrade` | 将 Squad 相关文件更新至最新版；绝不会触动你的团队状态；别名：`upgrade`；使用 `--migrate-directory` 可将 `.ai-team/` 重命名为 `.squad/` | +| `squad status` | 显示当前活跃的小队及其状态 | +| `squad triage` | 监控 Issue 并自动分发给团队成员（别名：`watch`, `loop`）；使用 `--interval ` 设置轮询频率（默认 10 分钟） | +| `squad copilot` | 添加/移除 Copilot 编码智能体 (@copilot)；使用 `--off` 移除，`--auto-assign` 开启自动分配 | +| `squad doctor` | 检查环境配置并诊断问题（别名：`heartbeat`） | +| `squad link ` | 连接到远程团队仓库 | +| `squad shell` | 显式启动交互式 Shell | +| `squad export` | 将小队状态导出为可移植的 JSON 快照 | +| `squad import ` | 从导出文件导入小队状态 | +| `squad plugin marketplace add\|remove\|list\|browse` | 管理插件市场 | +| `squad upstream add\|remove\|list\|sync` | 管理上游 Squad 源码 | +| `squad nap` | 上下文清理 — 压缩、剪枝、归档；使用 `--deep` 进行深度压缩，`--dry-run` 预览更改 | +| `squad aspire` | 打开 Aspire 仪表盘以进行可观测性监控 | +| `squad scrub-emails [directory]` | 从状态文件中移除电子邮件地址（默认目录：`.squad/`） | + +--- + +## 交互式 Shell + +厌倦了每次都输入 `squad` 加命令？进入交互式 Shell。 + +### 进入 Shell + +```bash +squad +``` + +不带任何参数。只需输入 `squad`。你会看到提示符： + +``` +squad > +``` + +你现在已经连接到了你的团队。直接和它们对话。 + +### Shell 命令 + +所有 Shell 命令均以 `/` 开头： + +| 命令 | 功能描述 | +|---------|-------------| +| `/status` | 检查团队状态及当前进度 | +| `/history` | 查看近期消息记录 | +| `/agents` | 列出所有团队成员 | +| `/sessions` | 列出已保存的会话 | +| `/resume ` | 恢复之前的会话 | +| `/version` | 显示版本号 | +| `/clear` | 清屏 | +| `/help` | 显示所有命令 | +| `/quit` | 退出 Shell (或 Ctrl+C) | + +### 与智能体对话 + +使用 `@智能体名称` (不区分大小写) 或使用逗号的自然语言： + +``` +squad > @Keaton, 分析这个项目的架构 +squad > McManus, 为我们的新特性写一篇博客 +squad > 构建登录页面 +``` + +协调员（Coordinator）会将消息路由给正确的智能体。多个智能体可以并行工作 —— 你可以实时看到进度。 + +--- + +## 智能体并行工作 —— 你只需在准备好时验收 + +Squad 并不遵循人类的作息。当你下达任务时，协调员会启动每一个可以立即开始工作的智能体。 + +``` +你: "团队，构建登录页面" + + 🏗️ Lead (组长) — 正在分析需求... ⎤ + ⚛️ Frontend (前端) — 正在构建登录表单... ⎥ 全部同时 + 🔧 Backend (后端) — 正在设置认证接口... ⎥ 并行启动 + 🧪 Tester (测试) — 正在编写测试用例... ⎥ + 📋 Scribe (书记员) — 正在记录一切... ⎦ +``` + +当智能体完成工作后，协调员会立即链式启动后续任务。如果你走开了，回来时会看到完整的记录： + +- **`decisions.md`** — 每个智能体所做的每一项决策 +- **`orchestration-log/`** — 启动了什么，为什么启动，以及发生了什么 +- **`log/`** — 完整的会话历史，支持搜索 + +**知识跨会话积累。** 智能体每次工作时，都会将学到的经验写入其 `history.md`。经过几次会话后，智能体将熟悉你的规范、偏好和架构。它们不再询问已经回答过的问题。 + +**这一切都在 git 中。** 任何克隆你仓库的人都能获得这支团队 —— 以及它们积累的所有知识。 + +--- + +## 会创建哪些文件？ + +``` +.squad/ +├── team.md # 花名册 — 团队成员 +├── routing.md # 路由规则 — 谁处理什么任务 +├── decisions.md # 共享大脑 — 团队决策 +├── ceremonies.md # 冲刺仪式配置 +├── casting/ +│ ├── policy.json # 选角配置 +│ ├── registry.json # 持久化名称注册表 +│ └── history.json # 使用历史 +├── agents/ +│ ├── {name}/ +│ │ ├── charter.md # 身份、专长、语调 +│ │ └── history.md # 它们对你的项目的了解 +│ └── scribe/ +│ └── charter.md # 静默记忆管理器 +├── skills/ # 从工作中压缩出的技能 +├── identity/ +│ ├── now.md # 团队当前焦点 +│ └── wisdom.md # 可复用的模式 +└── log/ # 会话历史 (可搜索的归档) +``` + +**提交此文件夹。** 你的团队和名字将持久化。任何克隆仓库的人都能看到同一批“演员”。 + +--- + +## 核心架构：可编程智能体运行时 (SDK) + +Squad 的关键在于 **SDK 编排 (v0.6+)**：规则是代码，会话是对象，路由经过编译，工具在运行前经过验证。 + +``` +Router.matchRoute(message) → { agent: 'Keaton', priority: 'high' } +TypeScript 清楚地知道哪个智能体将运行，拥有什么权限。 +HookPipeline 在工具执行前运行文件写入守卫。 +没有解释，没有歧义。只有代码。 +``` + +### 自定义工具 + +- **`squad_route`** — 将任务移交给另一个智能体。 +- **`squad_decide`** — 记录团队决策。每个智能体在开工前都会阅读 `decisions.md`。 +- **`squad_memory`** — 追记智能体历史。 +- **`squad_status`** — 查询会话池状态。 +- **`squad_skill`** — 读写智能体技能。技能是压缩后的经验知识。 + +### 钩子流水线 (Hook Pipeline) + +规则不再存在于提示词中，而是在工具执行前运行。 +- **文件写入守卫**：限制智能体只能写入 `src/`, `.squad/`, `docs/` 等安全区域。 +- **PII 脱敏**：自动漂白敏感信息（如电子邮件），防止其泄露给模型。 +- **评审者锁定**：如果测试员拒绝了代码，原作者无法私自修改，必须由另一评审者处理。 +- **用户询问速率限制**：防止智能体因等待用户输入而停滞。 + +--- + +## 技术栈 + +| 组件 | 版本 | 原因 | +|------|---------|-----| +| **Node.js** | ≥ 20.0.0 | 稳定的异步支持及强大的 TypeScript 生态 | +| **TypeScript** | 5.7+ | 所有工具、会话、钩子均具备完整类型定义 | +| **@github/copilot-sdk** | v0.1.8+ | 实时智能体流式传输与工具执行 | +| **Vitest** | 3.0+ | 快速并行的测试运行器 | +| **esbuild** | 0.25+ | 高效打包与死代码消除 | + +--- + +## 已知局限性 + +- **Alpha 阶段** — API 和文件格式可能变更。 +- **Node 20+** — 必须使用 Node.js 20.0.0 或更高版本。 +- **GitHub Copilot CLI & VS Code** — 支持在命令行和编辑器中使用。 +- **必需 `gh` CLI** — 许多功能依赖于 `gh auth login`。 +- **能力随使用而增长** — 初始会话能力有限，随着历史积累而变强。 + +--- + +## 参与贡献 + +详见 [CONTRIBUTING.md](CONTRIBUTING.md)。 + +--- + +## 许可证 + +MIT