# ISOS Agent Teams 软件研发模板

通用 Agent Teams 软件研发项目模板，支持多角色 AI Agent 并行协作开发。

## 目录结构

```
docs/           # 项目文档
specs/          # speckit 功能规格
.specify/       # speckit 配置
```

**模块独立性**: 各模块完全独立，禁止跨模块代码引用，仅通过 API 通信。

## 技术栈

> 以下为推荐技术栈，具体项目可根据需求调整。

| 组件   | 推荐技术             | 约束       |
| ------ | -------------------- | ---------- |
| 语言   | Python 3.12+         | 强制       |
| 包管理 | uv                   | 强制       |
| 服务端 | FastAPI              | 推荐       |
| 桌面端 | PyWebView + Svelte 5 | 推荐       |
| 数据库 | SQLite 3.45+         | 推荐       |
| 容器化 | Docker               | 服务端推荐 |

## 编码规范

### 格式化

- **缩进**: 4 空格 | **行长度**: 100 字符
- **格式化**: `ruff format` | **Lint**: `ruff check`

### 命名约定

- `PascalCase`: 类名、类型、异常
- `snake_case`: 函数、方法、变量、模块
- `UPPER_SNAKE_CASE`: 常量

### 类型注解

- 必须使用完整类型注解，mypy strict 模式
- 禁止使用 `Any` 类型

### 注释规范

- 使用 Google 风格 docstring
- 公共函数和类必须有文档字符串

### 字符串规范

- 用户可见字符串：双引号 | 代码内部：单引号

## Svelte 开发

完整指南见 [`team/svelte.md`](../../team/svelte.md)。核心流程：
1. `list-sections` → `get-documentation` → 编码 → `svelte-autofixer` 验证
2. `.svelte` 文件优先使用 svelte-file-editor 子代理

## 验证步骤

```bash
# 类型检查
uv run mypy src/ --strict

# 测试
uv run pytest

# 代码质量
ruff format --check . && ruff check .
```

## 模块说明

> 根据实际项目调整以下模块定义。

| 模块    | 职责               | 入口            |
| ------- | ------------------ | --------------- |
| Server  | REST API、数据存储 | `apps/server/`  |
| Desktop | UI、本地存储       | `apps/desktop/` |

## 开发工作流

### speckit 集成

```
/speckit.specify → spec.md → /speckit.plan → plan.md → /speckit.tasks → tasks.md → /speckit.implement
```

### 版本控制

- **版本控制**: Jujutsu (jj)，并存模式（`.jj` + `.git` 并存）
- **分支**: Trunk-Based Development，主分支 `trunk`
- **PR 约束**: 每个 PR 只能改动一个模块
- **PR 标题**: `[模块] 描述`，如 `[server] 添加用户认证 API`
- **提交类型**: 使用中文类型（功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并），完整列表见 `team/git.md`
- **详细规范**: `team/git.md`（提交规范）、`team/jj.md`（jj 命令对照）

## 关键文档

| 文档                  | 用途                         |
| --------------------- | ---------------------------- |
| `docs/01-用户需求.md` | 用户需求、项目目标、验收标准 |
| `docs/03-功能列表.md` | 功能需求（FR）列表           |
| `docs/02-产品需求.md` | 非功能性需求、约束           |
| `docs/06-设计-UX.md`  | 用户体验设计、交互模式       |
| `docs/05-设计-UI.md`  | UI 界面设计                  |
| `team/git.md`         | Git 提交规范、分支策略       |
| `team/jj.md`          | jj 命令对照表                |
| `team/svelte.md`      | Svelte 5 开发完整指南        |
| `team/tmux.md`        | tmux 团队协作规范            |
| `team/mermaid.md`     | Mermaid ER图兼容性规范       |
| `team/mirrors.md`     | 国内镜像源配置               |

---

**最后更新**: 2026-04-19