119 lines
3.6 KiB
Markdown
119 lines
3.6 KiB
Markdown
# 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
|