- Always reply in Chinese

# ISOS Agent Teams 软件研发模板

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

> 完整项目规范见 [`.claude/CLAUDE.md`](./.claude/CLAUDE.md)

## 目录结构

```
apps/
├── server/     # 服务端应用 (FastAPI + SQLite)
├── desktop/    # 桌面端应用 (PyWebView + Svelte + SQLite)
docs/           # 项目文档
specs/          # speckit 功能规格
.specify/       # speckit 配置
memory/        # 跨会话记忆（经验、偏好、历史）
```

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

## 核心约束

- **语言**: Python 3.12+ / TypeScript (前端)
- **框架**: FastAPI (服务端) + Svelte 5 + PyWebView (桌面端)
- **数据库**: SQLite 3.45+
- **包管理**: uv（Python）/ nvm + npm（前端）
- **版本控制**: Jujutsu (jj)，主分支 `trunk`
- **提交类型**: 必须使用中文（功能、修复、维护...），详见 `team/git.md`

## 技术栈

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

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

## 关键架构约束

- **模块独立**: `apps/server` 和 `apps/desktop` 各有独立的 `.venv`、`uv.lock`、`pyproject.toml`。禁止跨模块代码引用，仅通过 API 通信
- **每个 PR 只能改动一个模块**（server 或 desktop），标题格式：`[模块] 描述`

## 命令（必须 cd 到对应 app 目录执行）

```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 .  # 代码质量
```

## 编码规范

### 格式化

- **缩进**: 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 子代理

## 开发工作流

### speckit 集成

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

### 版本控制

- **版本控制**: Jujutsu (jj)，并存模式（`.jj` + `.git` 并存）
- **分支**: Trunk-Based Development，主分支 `trunk`
- **提交类型**: 使用中文类型（功能、修复、维护、文档、重构、测试、格式、性能、构建、安全、依赖、清理、配置、规格、合并），完整列表见 `team/git.md`

## 关键文档

| 文档                                       | 用途                             |
| ------------------------------------------ | -------------------------------- |
| [`.claude/CLAUDE.md`](./.claude/CLAUDE.md) | 完整编码规范、模块说明、验证步骤 |
| `docs/01-用户需求.md`                      | 用户需求、项目目标、验收标准     |
| `docs/03-功能列表.md`                      | 功能需求（FR）列表               |
| `docs/02-产品需求.md`                      | 非功能性需求、约束               |
| `docs/05-设计-UI.md`                       | UI 界面设计                      |
| `docs/06-设计-UX.md`                       | 用户体验设计                     |
| `team/git.md`                              | Git 提交规范、分支策略           |
| `team/jj.md`                               | jj 命令对照表                    |
| `team/svelte.md`                           | Svelte 5 开发完整指南            |
| `team/tmux.md`                             | tmux 团队协作规范                |