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 — Идеи и концепция
|
||||
|
||||
## Суть
|
||||
## Суть проекта
|
||||
|
||||
Веб-платформа где 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] │
|
||||
│ PROJECTS │─────────────────────────────────────────────────────│
|
||||
│ │ 💬 Chat ▼ │
|
||||
│ │ 💬 Chat ▼ (сворачиваемый) │
|
||||
│ ○ Alpha │ ┌──────────────────────────────────────────────┐ │
|
||||
│ ● Beta │ │ Agent-1: Закоммитил фикс для issue #42 │ │
|
||||
│ ○ Gamma │ │ Agent-2: Проверил, всё ок. Можно мержить. │ │
|
||||
│ ○ Gamma │ │ Agent-2: Проверил, всё ок │ │
|
||||
│ │ │ You: Мержите │ │
|
||||
│ [+ New] │ └──────────────────────────────────────────────┘ │
|
||||
│ │─────────────────────────────────────────────────────│
|
||||
@ -37,136 +71,250 @@
|
||||
|
||||
---
|
||||
|
||||
## Проекты
|
||||
## Workflow: от идеи до деплоя
|
||||
|
||||
Каждый проект содержит:
|
||||
- **Git репозиторий** (Gitea интеграция)
|
||||
- **Канбан доска** с задачами
|
||||
- **Чат** для обсуждений
|
||||
- **Назначенные агенты**
|
||||
### Фаза 1: Инициация проекта
|
||||
|
||||
**Точки входа:**
|
||||
- Через главного агента (Марков) в 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 авторизации"
|
||||
├── Subtask: "Написать модели" → Agent-1
|
||||
│ └── Status: Done
|
||||
├── Subtask: "Code review" → Agent-2
|
||||
│ └── Status: Done (approved)
|
||||
├── Subtask: "Написать тесты" → Agent-1
|
||||
│ └── Status: In Progress
|
||||
└── Subtask: "Final review" → Agent-2
|
||||
└── Status: Waiting
|
||||
├── Subtask: "Написать модели" → Agent-1 ✓
|
||||
├── Subtask: "Code review" → Agent-2 ✓
|
||||
├── Subtask: "Написать тесты" → Agent-1 (in progress)
|
||||
└── Subtask: "Final review" → Agent-2 (waiting)
|
||||
```
|
||||
|
||||
Когда агент работает над подзадачей — он видит всю задачу и все предыдущие подзадачи.
|
||||
Когда агент работает над подзадачей — видит всё дерево + историю.
|
||||
|
||||
---
|
||||
|
||||
## Агенты
|
||||
## Роли агентов
|
||||
|
||||
Типы агентов:
|
||||
- **OpenClaw instance** — полноценный агент с инструментами
|
||||
- **Claude API** — через API напрямую
|
||||
- **Codex** — OpenAI Codex
|
||||
- **Gemini** — Google
|
||||
- **Custom** — любой через API
|
||||
| Роль | Обязанности |
|
||||
|------|-------------|
|
||||
| **Lead/Analyst** | Discovery, Planning, Coordination |
|
||||
| **Developer** | Код, тесты |
|
||||
| **Reviewer** | Code review, QA |
|
||||
| **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
|
||||
name: "Claude-Coder"
|
||||
provider: anthropic
|
||||
model: claude-sonnet-4-20250514
|
||||
role: "Backend разработчик"
|
||||
capabilities:
|
||||
- code
|
||||
- review
|
||||
- git
|
||||
Project:
|
||||
name: "My Project"
|
||||
git_enabled: true # default: true
|
||||
git_url: "https://..."
|
||||
lead_agent_id: "markov" # можно переназначить
|
||||
agents: ["claude", "codex"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Чат проекта
|
||||
## Инфраструктура (уже есть)
|
||||
|
||||
- Сворачиваемая панель над канбаном
|
||||
- Участники: человек + агенты
|
||||
- Агенты пишут о прогрессе
|
||||
- Человек даёт указания
|
||||
- История сохраняется
|
||||
- **PostgreSQL** — БД
|
||||
- **Thoth** — STT/TTS сервис
|
||||
- **Authentik** — SSO
|
||||
- **Nginx + certbot** — домены
|
||||
- **Gitea** — Git хостинг
|
||||
- **OpenClaw (Марков)** — главный агент
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
## Открытые вопросы
|
||||
|
||||
1. Человек создаёт задачу
|
||||
2. Назначает агента (или агент сам берёт)
|
||||
3. Агент работает, создаёт подзадачи если нужно
|
||||
4. Передаёт на ревью другому агенту (подзадача)
|
||||
5. Ревьюер комментирует / апрувит
|
||||
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. Как интегрировать CLI-агентов (Claude Code, Cline)?
|
||||
2. Workspace для агентов — общий или изолированный?
|
||||
3. Реалтайм прогресс работы агента?
|
||||
4. Лимиты: макс агентов, макс задач?
|
||||
5. Биллинг/учёт использования API?
|
||||
|
||||
---
|
||||
|
||||
## Приоритеты реализации
|
||||
|
||||
1. [ ] Базовый UI: проекты, доска
|
||||
2. [ ] Tasks service: CRUD задач
|
||||
3. [ ] Agents service: регистрация агентов
|
||||
4. [ ] Подзадачи и назначения
|
||||
5. [ ] Chat service
|
||||
6. [ ] Git интеграция
|
||||
2. [ ] Tasks Service: CRUD, подзадачи
|
||||
3. [ ] Agents Service: регистрация
|
||||
4. [ ] Chat Service
|
||||
5. [ ] Git интеграция
|
||||
6. [ ] CLI Bridge для Claude Code
|
||||
7. [ ] Подключение реальных агентов
|
||||
|
||||
---
|
||||
|
||||
## Открытые вопросы
|
||||
|
||||
1. Как агент "работает"? Поллинг задач или вебхуки?
|
||||
2. Workspace для агентов — общий или изолированный?
|
||||
3. Как показывать прогресс работы агента в реалтайме?
|
||||
4. Лимиты: макс агентов, макс задач?
|
||||
*Документ для обсуждения. Финальная архитектура — отдельно.*
|
||||
|
||||
Loading…
Reference in New Issue
Block a user