283 lines
10 KiB
Markdown
283 lines
10 KiB
Markdown
# ISOS Agent Teams
|
||
|
||
通用 AI Agent Teams 软件研发模板，支持多角色 AI Agent（Claude Code / GLM）在 tmux 中并行协作开发。
|
||
|
||
## 项目简介
|
||
|
||
ISOS 是一套基于 Claude Code 的多人 Agent 协作开发框架：
|
||
|
||
- **项目经理** 分发任务、跟踪进度
|
||
- **后端开发** 实现 FastAPI + SQLite 服务端
|
||
- **前端开发** 实现 Svelte 5 + PyWebView 桌面端
|
||
- **测试工程师** 编写全级别测试并分析覆盖率
|
||
- **对话监控** 实时跟踪各 Agent 的输入/输出
|
||
|
||
所有角色在 tmux 面板中并行运行，通过共享任务列表和消息系统协调。
|
||
|
||
## 技术栈
|
||
|
||
| 组件 | 技术 | 说明 |
|
||
|------|------|------|
|
||
| 语言 | Python 3.12+ / TypeScript | 后端 Python，前端 TypeScript |
|
||
| 包管理 | uv / npm | Python 用 uv，前端用 nvm + npm |
|
||
| 服务端 | FastAPI + SQLite | REST API、数据存储 |
|
||
| 桌面端 | PyWebView + Svelte 5 | 本地 UI、SQLite |
|
||
| 版本控制 | Jujutsu (jj) | 与 git 并存，主分支 `trunk` |
|
||
| 协作工具 | tmux + Claude Code | 多面板并行 Agent |
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
docs/ # 项目文档（需求、设计、架构、测试、运维）
|
||
team/ # 团队规范（Git、jj、Svelte、tmux）
|
||
scripts/ # 工具脚本（tmux 团队空间、监控、消息通知）
|
||
.claude/ # Claude Code 配置
|
||
agents/ # Agent 角色定义
|
||
commands/ # 斜杠命令
|
||
prompts/ # 角色提示词
|
||
member/ # 成员对话记录
|
||
memory/ # 跨会话经验记忆
|
||
tasks/ # 任务文档
|
||
specs/ # speckit 功能规格
|
||
.specify/ # speckit 配置
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 1. 环境准备（必须）
|
||
|
||
所有开发方式（VS Code Dev Containers、docker-compose、本地）共享同一套前置步骤：
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone <仓库地址> workspace && cd workspace/.devcontainer
|
||
|
||
# ① 创建环境配置（首次必须）
|
||
cp .env.example .env
|
||
|
||
# ② 编辑 .env，至少修改以下配置:
|
||
# - GIT_USER_NAME / GIT_USER_EMAIL — Git 用户信息
|
||
# - API_KEY — 智谱 GLM API 密钥（可选，留空则跳过认证配置）
|
||
# - DOCKER_GID — 宿主机 docker 组 GID（getent group docker | cut -d: -f3）
|
||
# - CONTAINER_USER_UID / GID — 与宿主机用户一致（id -u / id -g）
|
||
|
||
# ③ 预下载构建资源（首次必须，后续按需增量更新）
|
||
bash download-resources.sh
|
||
```
|
||
|
||
#### download-resources.sh 资源预下载
|
||
|
||
[`download-resources.sh`](.devcontainer/download-resources.sh) 预下载所有网络资源到 `.devcontainer/.cache/`，Dockerfile 构建时通过 `--mount=type=bind` 直接使用本地缓存，**无需构建时访问外网**。支持增量更新和校验。
|
||
|
||
```bash
|
||
bash download-resources.sh # 下载全部资源（首次必须）
|
||
bash download-resources.sh --skip-extensions # 跳过 VSCode 扩展（节省时间）
|
||
bash download-resources.sh --force-update # 强制更新所有包
|
||
bash download-resources.sh --cleanup-only # 仅清理旧版本包
|
||
```
|
||
|
||
预下载的资源包括：
|
||
|
||
| 资源 | 用途 |
|
||
|------|------|
|
||
| uv + Python 3.12 | Python 包管理器和运行时 |
|
||
| nvm + Node.js 22 | 前端运行时和包管理 |
|
||
| npm 全局包 | Claude Code、Playwright MCP、TypeScript 等 |
|
||
| Google Chrome | Playwright headed 模式和 chrome-devtools-mcp |
|
||
| jj (Jujutsu) | 版本控制工具 |
|
||
| VSCode 扩展 (.vsix) | 20+ 开发扩展离线包 |
|
||
| spec-kit | speckit 规格工具 |
|
||
| Claude 插件市场 | claude-plugins-official、Svelte、superpowers 等 |
|
||
|
||
所有资源版本在 `.env` 中配置（`UV_VERSION`、`NODE_VERSION`、`CHROME_VERSION` 等），更新版本后重新运行脚本即可。
|
||
|
||
#### .env 配置参考
|
||
|
||
完整配置见 [`.devcontainer/.env.example`](.devcontainer/.env.example)，常用项：
|
||
|
||
| 配置项 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| `GIT_USER_NAME` | `arno` | Git 用户名 |
|
||
| `GIT_USER_EMAIL` | — | Git 邮箱 |
|
||
| `API_KEY` | 空 | 智谱 GLM API 密钥 |
|
||
| `DOCKER_ENABLED` | `false` | 是否启用容器内 Docker |
|
||
| `DOCKER_GID` | `984` | 宿主机 docker 组 GID |
|
||
| `CONTAINER_USER_UID` | `1000` | 容器用户 UID |
|
||
| `CONTAINER_USER_GID` | `1000` | 容器用户 GID |
|
||
| `DISPLAY_ON_HOST` | `false` | GUI 输出到宿主机（仅 Linux） |
|
||
| `CONTAINER_CPUS` | `6` | CPU 核心数限制 |
|
||
| `CONTAINER_MEMORY` | `16G` | 内存限制 |
|
||
|
||
### 2. 启动开发环境
|
||
|
||
资源下载完成后，选择以下任一方式启动：
|
||
|
||
#### 方式 A: VS Code Dev Containers（推荐）
|
||
|
||
1. 安装 VS Code 扩展 `ms-vscode-remote.remote-containers`
|
||
2. 在 VS Code 中打开项目根目录
|
||
3. `Ctrl+Shift+P` → `Dev Containers: Open Folder in Container...`
|
||
4. VS Code 自动读取 [`.devcontainer/devcontainer.json`](.devcontainer/devcontainer.json) 构建、启动容器并安装扩展
|
||
|
||
`devcontainer.json` 核心配置：
|
||
|
||
| 配置 | 说明 |
|
||
|------|------|
|
||
| `dockerComposeFile` | 组合 `docker-compose.yml` + `docker-compose.display.yml`（X11 转发） |
|
||
| `service: app` | 使用 `app` 服务 |
|
||
| `postCreateCommand` | 容器创建后自动执行 `.devcontainer/post-create.sh`（配置 Git、jj、Claude Code、MCP、插件等） |
|
||
| `customizations.vscode.extensions` | 预装 Claude Code、Ruff、Playwright、Mermaid 等 20+ 扩展 |
|
||
|
||
#### 方式 B: docker-compose 命令行
|
||
|
||
```bash
|
||
cd .devcontainer
|
||
docker compose up -d
|
||
docker exec -it team bash
|
||
```
|
||
|
||
#### 方式 C: 本地开发（不使用容器）
|
||
|
||
不使用容器时，需手动安装工具链（uv、nvm、jj 等）：
|
||
|
||
```bash
|
||
jj clone <仓库地址> workspace && cd workspace
|
||
uv python install 3.12
|
||
nvm install --lts
|
||
```
|
||
|
||
详细步骤见 [`docs/管理-开发环境搭建.md`](docs/管理-开发环境搭建.md)。
|
||
|
||
#### 数据持久化
|
||
|
||
`.devcontainer/.volumes/` 目录映射以下数据，容器重建不丢失：
|
||
|
||
| 目录 | 用途 |
|
||
|------|------|
|
||
| `.volumes/ssh/` | SSH 密钥和配置 |
|
||
| `.volumes/claude/` | Claude Code 配置（settings.json） |
|
||
| `.volumes/jj/` | jj 版本控制配置 |
|
||
| `.volumes/bin/` | 运行时脚本（runcc.sh） |
|
||
|
||
### 3. 启动 Agent 团队
|
||
|
||
```bash
|
||
# 在 tmux 中启动 5 面板团队工作空间
|
||
/isos-tmux-team
|
||
```
|
||
|
||
布局如下：
|
||
|
||
```
|
||
+----------+----------------------+--------------------+
|
||
| | Pane 2 (后端) | Pane 3 (前端) |
|
||
| Pane 1 +----------------------+--------------------+
|
||
| (项目) | Pane 4 (测试) | Pane 5 (对话) |
|
||
| | | |
|
||
+----------+----------------------+--------------------+
|
||
```
|
||
|
||
也可手动启动单个角色：
|
||
|
||
```bash
|
||
/isos-pm # 项目经理
|
||
/isos-backend # 后端开发
|
||
/isos-frontend # 前端开发
|
||
/isos-test # 测试工程师
|
||
```
|
||
|
||
### 4. 常用命令
|
||
|
||
```bash
|
||
# 提交并推送（jj 工作流）
|
||
/isos-pr
|
||
|
||
# 文档相关
|
||
/isos-doc-需求 # 需求文档
|
||
/isos-doc-架构 # 架构文档
|
||
/isos-doc-设计 # 设计文档
|
||
/isos-doc-测试 # 测试文档
|
||
/isos-doc-运维 # 运维文档
|
||
|
||
# 工具
|
||
/isos-tmux-monitor # tmux 监控面板
|
||
/isos-pdf2md # PDF 转 Markdown
|
||
/isos-md-export # Markdown 导出 docx/pdf
|
||
```
|
||
|
||
### 5. 开发验证
|
||
|
||
```bash
|
||
# 服务端 (cd apps/server)
|
||
uv run mypy src/ --strict
|
||
uv run pytest
|
||
ruff format --check . && ruff check .
|
||
|
||
# 桌面端 (cd apps/desktop)
|
||
uv run mypy src/ --strict
|
||
uv run pytest
|
||
ruff format --check . && ruff check .
|
||
```
|
||
|
||
## 角色阅读指引
|
||
|
||
### 项目经理
|
||
|
||
1. [`docs/12-管理-项目.md`](docs/12-管理-项目.md) — 项目管理、里程碑、工作流程
|
||
2. [`docs/03-功能列表.md`](docs/03-功能列表.md) — 功能需求列表
|
||
3. [`docs/管理-Agent-Team分工及提示词.md`](docs/管理-Agent-Team分工及提示词.md) — Agent 分工
|
||
4. [`team/tmux.md`](team/tmux.md) — tmux 协作规范
|
||
|
||
### 架构师
|
||
|
||
1. [`docs/07-系统架构.md`](docs/07-系统架构.md) — 系统架构图、模块划分
|
||
2. [`docs/08-数据库设计.md`](docs/08-数据库设计.md) — 数据模型
|
||
3. [`docs/09-API契约.md`](docs/09-API契约.md) — API 接口定义
|
||
4. [`docs/11-工程规范.md`](docs/11-工程规范.md) — 术语表、工程规范
|
||
|
||
### 产品经理
|
||
|
||
1. [`docs/01-用户需求.md`](docs/01-用户需求.md) — 用户需求、项目目标
|
||
2. [`docs/02-产品需求.md`](docs/02-产品需求.md) — 非功能性需求、约束
|
||
3. [`docs/04-用户故事.md`](docs/04-用户故事.md) — 用户故事
|
||
|
||
### 开发者
|
||
|
||
1. [`docs/管理-开发入门.md`](docs/管理-开发入门.md) — 开发入门指引
|
||
2. [`docs/管理-开发环境搭建.md`](docs/管理-开发环境搭建.md) — 环境配置
|
||
3. [`team/svelte.md`](team/svelte.md) — Svelte 5 开发指南
|
||
4. [`team/desktop-编码规范.md`](team/desktop-编码规范.md) — Desktop 编码规范
|
||
5. [`team/git.md`](team/git.md) / [`team/jj.md`](team/jj.md) — 版本控制规范
|
||
|
||
### 测试工程师
|
||
|
||
1. [`docs/10-测试-方案.md`](docs/10-测试-方案.md) — 测试策略（含各级别定义）
|
||
2. [`docs/测试-计划.md`](docs/测试-计划.md) — 测试计划
|
||
3. [`docs/测试-用例.md`](docs/测试-用例.md) — 测试用例
|
||
4. [`docs/测试-单元.md`](docs/测试-单元.md) — 单元测试标准
|
||
|
||
### 运维工程师
|
||
|
||
1. [`docs/运维-部署实施.md`](docs/运维-部署实施.md) — 部署方案
|
||
2. [`docs/运维-发布日志.md`](docs/运维-发布日志.md) — 版本变更历史
|
||
3. [`docs/运维-故障排除.md`](docs/运维-故障排除.md) — 问题排查
|
||
4. [`docs/运维-安全审计.md`](docs/运维-安全审计.md) — 安全策略
|
||
5. [`docs/运维-性能基准.md`](docs/运维-性能基准.md) — 性能基准
|
||
|
||
## 文档索引
|
||
|
||
完整文档目录见 [`docs/README.md`](docs/README.md)，团队规范见 [`team/README.md`](team/README.md)。
|
||
|
||
## 核心约束
|
||
|
||
- **模块独立**: `apps/server` 和 `apps/desktop` 各有独立环境，禁止跨模块代码引用，仅通过 API 通信
|
||
- **每个 PR 只改一个模块**，标题格式：`[模块] 描述`
|
||
- **提交类型使用中文**: `功能`、`修复`、`维护`、`文档` 等，详见 [`team/git.md`](team/git.md)
|
||
- **禁止 AI 签名**: 提交消息中不添加 `Co-Authored-By` 等标识
|
||
- **完整类型注解**: mypy strict 模式，禁止 `Any`
|
||
- **文档文件中文命名**: `docs/` 下所有 `.md` 使用中文文件名
|
||
|
||
## 许可证
|
||
|
||
见 [LICENSE](LICENSE)。
|