team/README.md

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、本地）共享同一套前置步骤：

# 克隆项目
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/.cache/，Dockerfile 构建时通过 --mount=type=bind 直接使用本地缓存，无需构建时访问外网。支持增量更新和校验。

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，常用项：

配置项	默认值	说明
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	内存限制

# 修改claude模型

vim ~/.claude/settings.json 
# 更改env内容来切换模型

minimax模型

  "env": {
    "ANTHROPIC_AUTH_TOKEN": "",
    "ANTHROPIC_BASE_URL": "https://api.minimaxi.com/anthropic",
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "ANTHROPIC_MODEL": "MiniMax-M2.7",
    "ANTHROPIC_SMALL_FAST_MODEL": "MiniMax-M2.7",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75",
    "CLAUDE_CODE_NO_FLICKER": "1"
  },

kimiMAX模型

  "env": {
    "ANTHROPIC_BASE_URL": "https://api.kimi.com/coding/",
    "ANTHROPIC_AUTH_TOKEN": "",
    "ANTHROPIC_MODEL": "kimi-k2.5",
    "ANTHROPIC_SMALL_FAST_MODEL": "kimi-k2.5",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "API_TIMEOUT_MS": "600000"
  },

智谱模型 API 调用 + Coding Plan

"env": {
    "ANTHROPIC_AUTH_TOKEN": "",
    "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/paas/v4/chat/completions", // 智谱如果使用 Coding Plan，需修改路径为：https://open.bigmodel.cn/api/anthropic
    "API_TIMEOUT_MS": "3000000",
    "CLAUDE_CODE_AUTO_COMPACT_WINDOW": "200000",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.7",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-5",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "75",
    "CLAUDE_CODE_NO_FLICKER": "1"
  },

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.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 命令行

cd .devcontainer
docker compose up -d
docker exec -it team bash

方式 C: 本地开发（不使用容器）

不使用容器时，需手动安装工具链（uv、nvm、jj 等）：

jj clone <仓库地址> workspace && cd workspace
uv python install 3.12
nvm install --lts

详细步骤见 docs/管理-开发环境搭建.md。

数据持久化

.devcontainer/.volumes/ 目录映射以下数据，容器重建不丢失：

目录	用途
.volumes/ssh/	SSH 密钥和配置
.volumes/claude/	Claude Code 配置（settings.json）
.volumes/jj/	jj 版本控制配置
.volumes/bin/	运行时脚本（runcc.sh）

3. 启动 Agent 团队

# 在 tmux 中启动 5 面板团队工作空间
/isos-tmux-team

布局如下：

+----------+----------------------+--------------------+
|          |  Pane 2  (后端)      |  Pane 3  (前端)    |
|  Pane 1  +----------------------+--------------------+
|  (项目)  |  Pane 4  (测试)      |  Pane 5  (对话)    |
|          |                      |                    |
+----------+----------------------+--------------------+

也可手动启动单个角色：

/isos-pm          # 项目经理
/isos-backend     # 后端开发
/isos-frontend    # 前端开发
/isos-test        # 测试工程师

4. 常用命令

# 提交并推送（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. 开发验证

# 服务端 (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 — 项目管理、里程碑、工作流程
2. docs/03-功能列表.md — 功能需求列表
3. docs/管理-Agent-Team分工及提示词.md — Agent 分工
4. team/tmux.md — tmux 协作规范

架构师

1. docs/07-系统架构.md — 系统架构图、模块划分
2. docs/08-数据库设计.md — 数据模型
3. docs/09-API契约.md — API 接口定义
4. docs/11-工程规范.md — 术语表、工程规范

产品经理

1. docs/01-用户需求.md — 用户需求、项目目标
2. docs/02-产品需求.md — 非功能性需求、约束
3. docs/04-用户故事.md — 用户故事

开发者

1. docs/管理-开发入门.md — 开发入门指引
2. docs/管理-开发环境搭建.md — 环境配置
3. team/svelte.md — Svelte 5 开发指南
4. team/desktop-编码规范.md — Desktop 编码规范
5. team/git.md / team/jj.md — 版本控制规范

测试工程师

1. docs/10-测试-方案.md — 测试策略（含各级别定义）
2. docs/测试-计划.md — 测试计划
3. docs/测试-用例.md — 测试用例
4. docs/测试-单元.md — 单元测试标准

运维工程师

1. docs/运维-部署实施.md — 部署方案
2. docs/运维-发布日志.md — 版本变更历史
3. docs/运维-故障排除.md — 问题排查
4. docs/运维-安全审计.md — 安全策略
5. docs/运维-性能基准.md — 性能基准

文档索引

完整文档目录见 docs/README.md，团队规范见 team/README.md。

核心约束

• 模块独立: apps/server 和 apps/desktop 各有独立环境，禁止跨模块代码引用，仅通过 API 通信
• 每个 PR 只改一个模块，标题格式：[模块] 描述
• 提交类型使用中文: 功能、修复、维护、文档 等，详见 team/git.md
• 禁止 AI 签名: 提交消息中不添加 Co-Authored-By 等标识
• 完整类型注解: mypy strict 模式，禁止 Any
• 文档文件中文命名: docs/ 下所有 .md 使用中文文件名

许可证

见 LICENSE。