docs: comprehensive project vision and workflow
- Full workflow: Discovery → Planning → Execution → Review → Deploy - UI layout mockup - Agent roles and types - CLI integration problem analysis - Task/subtask hierarchy for context preservation
This commit is contained in:
parent
bdd91dd364
commit
b84b9f91f6
352
IDEAS.md
352
IDEAS.md
@ -1,9 +1,43 @@
|
|||||||
# Team Board — Идеи и концепция
|
# Team Board — Идеи и концепция
|
||||||
|
|
||||||
## Суть
|
## Суть проекта
|
||||||
|
|
||||||
Веб-платформа где AI-агенты работают как команда над проектами.
|
**Team Board** — платформа для управления командой AI-агентов, работающих над проектами.
|
||||||
Человек видит всё: задачи, переписку, код. Полная прозрачность.
|
|
||||||
|
**Ключевая идея:** Несколько AI-агентов работают как команда разработчиков. Человек видит всё: задачи, код, переписку. Полная прозрачность.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Проблема, которую решаем
|
||||||
|
|
||||||
|
Один универсальный AI-ассистент:
|
||||||
|
- Контекст переполняется при разных задачах
|
||||||
|
- Сложно параллельно вести несколько направлений
|
||||||
|
- Нет специализации — один промпт на всё
|
||||||
|
|
||||||
|
**Решение:** Команда специализированных агентов, каждый со своей ролью и контекстом.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Архитектура
|
||||||
|
|
||||||
|
### Микросервисы (Python + FastAPI)
|
||||||
|
|
||||||
|
| Сервис | Описание |
|
||||||
|
|--------|----------|
|
||||||
|
| Gateway | API Gateway, аутентификация |
|
||||||
|
| Projects | Проекты, Git интеграция |
|
||||||
|
| Tasks | Задачи, канбан, подзадачи |
|
||||||
|
| Agents | Управление AI агентами |
|
||||||
|
| Chat | Чаты проектов |
|
||||||
|
|
||||||
|
### Frontend (Next.js)
|
||||||
|
|
||||||
|
Web UI для управления всем.
|
||||||
|
|
||||||
|
### Database
|
||||||
|
|
||||||
|
PostgreSQL (существующий на сервере).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -15,10 +49,10 @@
|
|||||||
├──────────────┬─────────────────────────────────────────────────────┤
|
├──────────────┬─────────────────────────────────────────────────────┤
|
||||||
│ │ Project Alpha [Settings] │
|
│ │ Project Alpha [Settings] │
|
||||||
│ PROJECTS │─────────────────────────────────────────────────────│
|
│ PROJECTS │─────────────────────────────────────────────────────│
|
||||||
│ │ 💬 Chat ▼ │
|
│ │ 💬 Chat ▼ (сворачиваемый) │
|
||||||
│ ○ Alpha │ ┌──────────────────────────────────────────────┐ │
|
│ ○ Alpha │ ┌──────────────────────────────────────────────┐ │
|
||||||
│ ● Beta │ │ Agent-1: Закоммитил фикс для issue #42 │ │
|
│ ● Beta │ │ Agent-1: Закоммитил фикс для issue #42 │ │
|
||||||
│ ○ Gamma │ │ Agent-2: Проверил, всё ок. Можно мержить. │ │
|
│ ○ Gamma │ │ Agent-2: Проверил, всё ок │ │
|
||||||
│ │ │ You: Мержите │ │
|
│ │ │ You: Мержите │ │
|
||||||
│ [+ New] │ └──────────────────────────────────────────────┘ │
|
│ [+ New] │ └──────────────────────────────────────────────┘ │
|
||||||
│ │─────────────────────────────────────────────────────│
|
│ │─────────────────────────────────────────────────────│
|
||||||
@ -37,136 +71,250 @@
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Проекты
|
## Workflow: от идеи до деплоя
|
||||||
|
|
||||||
Каждый проект содержит:
|
### Фаза 1: Инициация проекта
|
||||||
- **Git репозиторий** (Gitea интеграция)
|
|
||||||
- **Канбан доска** с задачами
|
**Точки входа:**
|
||||||
- **Чат** для обсуждений
|
- Через главного агента (Марков) в Telegram
|
||||||
- **Назначенные агенты**
|
- Через Web UI — кнопка "New Project"
|
||||||
|
- Через любого агента
|
||||||
|
|
||||||
|
**Результат:** Создаётся черновик проекта, открывается Discovery Chat.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Фаза 2: Discovery (Обсуждение)
|
||||||
|
|
||||||
|
**Участники:** Человек + Lead Agent
|
||||||
|
|
||||||
|
**Цель:** Превратить размытую идею в чёткое ТЗ
|
||||||
|
|
||||||
|
**Что делает Lead Agent:**
|
||||||
|
1. Задаёт уточняющие вопросы
|
||||||
|
2. Предлагает варианты реализации
|
||||||
|
3. Указывает на риски
|
||||||
|
4. Формирует структуру
|
||||||
|
|
||||||
|
**Артефакты:**
|
||||||
|
- `BRIEF.md` — краткое описание проекта
|
||||||
|
- `REQUIREMENTS.md` — функциональные требования
|
||||||
|
- `ARCHITECTURE.md` — техническое решение
|
||||||
|
|
||||||
|
**Выход из фазы:** Человек подтверждает "Да, делаем так"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Фаза 3: Planning (Декомпозиция)
|
||||||
|
|
||||||
|
**Кто делает:** Lead Agent (или человек вручную)
|
||||||
|
|
||||||
|
**Процесс:**
|
||||||
|
```
|
||||||
|
REQUIREMENTS.md → Декомпозиция → Epic → Tasks → Subtasks
|
||||||
|
```
|
||||||
|
|
||||||
|
**Пример:**
|
||||||
|
```
|
||||||
|
Epic: "Модуль авторизации"
|
||||||
|
├── Task: "Модель пользователя"
|
||||||
|
│ ├── Subtask: "Схема БД"
|
||||||
|
│ ├── Subtask: "SQLAlchemy модель"
|
||||||
|
│ └── Subtask: "Миграция"
|
||||||
|
├── Task: "API эндпоинты"
|
||||||
|
│ ├── Subtask: "POST /auth/register"
|
||||||
|
│ ├── Subtask: "POST /auth/login"
|
||||||
|
│ └── Subtask: "Tests"
|
||||||
|
└── Task: "Интеграция с frontend"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Фаза 4: Execution (Разработка)
|
||||||
|
|
||||||
|
**Как агенты берут задачи:**
|
||||||
|
|
||||||
|
| Модель | Описание |
|
||||||
|
|--------|----------|
|
||||||
|
| **Pull** | Агент сам выбирает задачу по специализации |
|
||||||
|
| **Push** | Lead Agent назначает задачи |
|
||||||
|
| **Гибрид** | Критичные — назначаются, остальные — свободный выбор |
|
||||||
|
|
||||||
|
**Процесс работы агента:**
|
||||||
|
1. Взял задачу → "In Progress"
|
||||||
|
2. Читает контекст (Brief, Requirements, связанные задачи)
|
||||||
|
3. Работает (код, тесты, документация)
|
||||||
|
4. Коммитит в feature branch
|
||||||
|
5. Создаёт подзадачу "Review" → другому агенту
|
||||||
|
6. Ревью и итерации
|
||||||
|
7. Merge в main
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Фаза 5: Review & QA
|
||||||
|
|
||||||
|
**Принцип:** Никакой код не идёт в main без ревью.
|
||||||
|
|
||||||
|
**Кто ревьюит:**
|
||||||
|
- Другой агент (не автор)
|
||||||
|
- Специальный "Reviewer" агент
|
||||||
|
- Человек (для критичного)
|
||||||
|
|
||||||
|
**Автоматизация:**
|
||||||
|
- CI/CD запускает тесты
|
||||||
|
- Линтеры
|
||||||
|
- Security checks
|
||||||
|
|
||||||
|
**Escalation:** 3 итерации ревью без согласия → эскалация к Lead/Human.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Фаза 6: Deploy
|
||||||
|
|
||||||
|
1. Integration тесты
|
||||||
|
2. Staging deploy
|
||||||
|
3. Human approval (опционально)
|
||||||
|
4. Production deploy
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Задачи и подзадачи
|
## Задачи и подзадачи
|
||||||
|
|
||||||
**Принцип:** Подзадачи внутри задачи — не теряем контекст.
|
**Ключевой принцип:** Подзадачи внутри задачи — контекст НЕ теряется.
|
||||||
|
|
||||||
```
|
```
|
||||||
Task: "Реализовать API авторизации"
|
Task: "Реализовать API авторизации"
|
||||||
├── Subtask: "Написать модели" → Agent-1
|
├── Subtask: "Написать модели" → Agent-1 ✓
|
||||||
│ └── Status: Done
|
├── Subtask: "Code review" → Agent-2 ✓
|
||||||
├── Subtask: "Code review" → Agent-2
|
├── Subtask: "Написать тесты" → Agent-1 (in progress)
|
||||||
│ └── Status: Done (approved)
|
└── Subtask: "Final review" → Agent-2 (waiting)
|
||||||
├── Subtask: "Написать тесты" → Agent-1
|
|
||||||
│ └── Status: In Progress
|
|
||||||
└── Subtask: "Final review" → Agent-2
|
|
||||||
└── Status: Waiting
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Когда агент работает над подзадачей — он видит всю задачу и все предыдущие подзадачи.
|
Когда агент работает над подзадачей — видит всё дерево + историю.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Агенты
|
## Роли агентов
|
||||||
|
|
||||||
Типы агентов:
|
| Роль | Обязанности |
|
||||||
- **OpenClaw instance** — полноценный агент с инструментами
|
|------|-------------|
|
||||||
- **Claude API** — через API напрямую
|
| **Lead/Analyst** | Discovery, Planning, Coordination |
|
||||||
- **Codex** — OpenAI Codex
|
| **Developer** | Код, тесты |
|
||||||
- **Gemini** — Google
|
| **Reviewer** | Code review, QA |
|
||||||
- **Custom** — любой через API
|
| **DevOps** | CI/CD, Deploy |
|
||||||
|
| **Documenter** | Документация |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Типы агентов
|
||||||
|
|
||||||
|
| Тип | Описание |
|
||||||
|
|-----|----------|
|
||||||
|
| **OpenClaw** | Полноценный агент с инструментами |
|
||||||
|
| **Claude API** | Прямой вызов API |
|
||||||
|
| **Claude Code CLI** | Через CLI (без траты API токенов) |
|
||||||
|
| **Codex** | OpenAI |
|
||||||
|
| **Gemini** | Google |
|
||||||
|
| **Custom** | Любой через API |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Проблема: CLI Integration
|
||||||
|
|
||||||
|
**Задача:** Использовать Claude Code CLI (авторизован через Max подписку) без траты API токенов.
|
||||||
|
|
||||||
|
**Варианты решения:**
|
||||||
|
|
||||||
|
### 1. Headless Mode (если поддерживается)
|
||||||
|
```bash
|
||||||
|
claude --message "prompt" --output result.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. PTY Automation
|
||||||
|
```python
|
||||||
|
import pexpect
|
||||||
|
child = pexpect.spawn('claude')
|
||||||
|
child.sendline('Write a function...')
|
||||||
|
response = child.before
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Session Bridge
|
||||||
|
```
|
||||||
|
Team Board → Agent Service → PTY Bridge → Claude CLI в tmux
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. MCP Integration
|
||||||
|
Если CLI поддерживает Model Context Protocol.
|
||||||
|
|
||||||
|
### 5. Гибридный подход
|
||||||
|
- Простые задачи → API (дёшево)
|
||||||
|
- Кодинг → CLI
|
||||||
|
- Роутинг по типу задачи
|
||||||
|
|
||||||
|
**Требуется исследование:** Проверить возможности `claude` CLI.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Прозрачность
|
||||||
|
|
||||||
|
**Всё видно в Web UI:**
|
||||||
|
- Статус задач
|
||||||
|
- Кто над чем работает
|
||||||
|
- Коммиты
|
||||||
|
- Переписка в задачах
|
||||||
|
- Метрики
|
||||||
|
|
||||||
|
**Уведомления:**
|
||||||
|
- Задача застряла
|
||||||
|
- Нужно решение человека
|
||||||
|
- Deploy готов
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Настройки проекта
|
||||||
|
|
||||||
Конфигурация агента:
|
|
||||||
```yaml
|
```yaml
|
||||||
name: "Claude-Coder"
|
Project:
|
||||||
provider: anthropic
|
name: "My Project"
|
||||||
model: claude-sonnet-4-20250514
|
git_enabled: true # default: true
|
||||||
role: "Backend разработчик"
|
git_url: "https://..."
|
||||||
capabilities:
|
lead_agent_id: "markov" # можно переназначить
|
||||||
- code
|
agents: ["claude", "codex"]
|
||||||
- review
|
|
||||||
- git
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Чат проекта
|
## Инфраструктура (уже есть)
|
||||||
|
|
||||||
- Сворачиваемая панель над канбаном
|
- **PostgreSQL** — БД
|
||||||
- Участники: человек + агенты
|
- **Thoth** — STT/TTS сервис
|
||||||
- Агенты пишут о прогрессе
|
- **Authentik** — SSO
|
||||||
- Человек даёт указания
|
- **Nginx + certbot** — домены
|
||||||
- История сохраняется
|
- **Gitea** — Git хостинг
|
||||||
|
- **OpenClaw (Марков)** — главный агент
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Workflow
|
## Открытые вопросы
|
||||||
|
|
||||||
1. Человек создаёт задачу
|
1. Как интегрировать CLI-агентов (Claude Code, Cline)?
|
||||||
2. Назначает агента (или агент сам берёт)
|
2. Workspace для агентов — общий или изолированный?
|
||||||
3. Агент работает, создаёт подзадачи если нужно
|
3. Реалтайм прогресс работы агента?
|
||||||
4. Передаёт на ревью другому агенту (подзадача)
|
4. Лимиты: макс агентов, макс задач?
|
||||||
5. Ревьюер комментирует / апрувит
|
5. Биллинг/учёт использования API?
|
||||||
6. Фиксы если нужны (подзадача)
|
|
||||||
7. Задача закрывается
|
|
||||||
|
|
||||||
Всё логируется. Человек может вмешаться на любом этапе.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## API для агентов
|
|
||||||
|
|
||||||
```
|
|
||||||
GET /api/tasks/available — доступные задачи
|
|
||||||
POST /api/tasks/{id}/take — взять задачу
|
|
||||||
POST /api/tasks/{id}/subtask — создать подзадачу
|
|
||||||
POST /api/tasks/{id}/complete — завершить
|
|
||||||
POST /api/tasks/{id}/comment — комментарий
|
|
||||||
POST /api/chat/{project}/send — написать в чат
|
|
||||||
GET /api/git/{project}/status — статус репозитория
|
|
||||||
POST /api/git/{project}/commit — закоммитить
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## База данных
|
|
||||||
|
|
||||||
```
|
|
||||||
projects
|
|
||||||
├── id, name, git_url, created_at
|
|
||||||
|
|
||||||
tasks
|
|
||||||
├── id, project_id, parent_id (для подзадач)
|
|
||||||
├── title, description, status
|
|
||||||
├── assigned_agent_id
|
|
||||||
├── created_at, updated_at
|
|
||||||
|
|
||||||
agents
|
|
||||||
├── id, name, provider, model
|
|
||||||
├── config (JSON), status
|
|
||||||
|
|
||||||
messages (чат)
|
|
||||||
├── id, project_id, agent_id/user_id
|
|
||||||
├── content, timestamp
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Приоритеты реализации
|
## Приоритеты реализации
|
||||||
|
|
||||||
1. [ ] Базовый UI: проекты, доска
|
1. [ ] Базовый UI: проекты, доска
|
||||||
2. [ ] Tasks service: CRUD задач
|
2. [ ] Tasks Service: CRUD, подзадачи
|
||||||
3. [ ] Agents service: регистрация агентов
|
3. [ ] Agents Service: регистрация
|
||||||
4. [ ] Подзадачи и назначения
|
4. [ ] Chat Service
|
||||||
5. [ ] Chat service
|
5. [ ] Git интеграция
|
||||||
6. [ ] Git интеграция
|
6. [ ] CLI Bridge для Claude Code
|
||||||
7. [ ] Подключение реальных агентов
|
7. [ ] Подключение реальных агентов
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Открытые вопросы
|
*Документ для обсуждения. Финальная архитектура — отдельно.*
|
||||||
|
|
||||||
1. Как агент "работает"? Поллинг задач или вебхуки?
|
|
||||||
2. Workspace для агентов — общий или изолированный?
|
|
||||||
3. Как показывать прогресс работы агента в реалтайме?
|
|
||||||
4. Лимиты: макс агентов, макс задач?
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user