125 lines
4.5 KiB
Markdown
125 lines
4.5 KiB
Markdown
- 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 团队协作规范 |
|