mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Adjusted documentation
This commit is contained in:
Renn F
@@ -0,0 +1,233 @@
|
||||
# Multi-Agent Workspace Architecture
|
||||
|
||||
This document describes the workspace structure that enables multiple AI agents to work on the same project in parallel without conflicts.
|
||||
|
||||
## Overview
|
||||
|
||||
Each agent gets their own git clone (workspace) of a project. This allows:
|
||||
|
||||
- **Parallel development**: Multiple agents working on different tasks simultaneously
|
||||
- **No file conflicts**: Each agent has their own working tree
|
||||
- **Independent branches**: Agents can be on different branches
|
||||
- **Scoped permissions**: Agents only have access to their own workspace
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```
|
||||
{workspaces_root}/
|
||||
└── {project-slug}/
|
||||
└── {team}/
|
||||
└── {agent-slug}/
|
||||
└── [git repository files]
|
||||
```
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
/data/workspaces/
|
||||
├── roboco/ # Project: roboco
|
||||
│ ├── backend/ # Team: backend
|
||||
│ │ ├── be-dev-1/ # Agent: be-dev-1
|
||||
│ │ │ ├── .git/
|
||||
│ │ │ ├── roboco/
|
||||
│ │ │ └── ...
|
||||
│ │ └── be-dev-2/ # Agent: be-dev-2
|
||||
│ │ ├── .git/
|
||||
│ │ ├── roboco/
|
||||
│ │ └── ...
|
||||
│ ├── frontend/ # Team: frontend
|
||||
│ │ ├── fe-dev-1/
|
||||
│ │ └── fe-dev-2/
|
||||
│ └── uxui/ # Team: uxui
|
||||
│ └── ux-dev-1/
|
||||
│
|
||||
└── roboco-panel/ # Project: roboco-panel
|
||||
├── frontend/
|
||||
│ ├── fe-dev-1/
|
||||
│ └── fe-dev-2/
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Environment Variables
|
||||
|
||||
| Variable | Default | Description |
|
||||
|----------|---------|-------------|
|
||||
| `ROBOCO_WORKSPACES_ROOT` | `/data/workspaces` | Root directory for all workspaces |
|
||||
| `ROBOCO_WORKSPACE_AUTO_CLONE` | `true` | Auto-clone repos on first access |
|
||||
| `ROBOCO_WORKSPACE_CLONE_TIMEOUT` | `300` | Clone timeout in seconds |
|
||||
|
||||
### Example `.env`
|
||||
|
||||
```bash
|
||||
ROBOCO_WORKSPACES_ROOT=/data/workspaces
|
||||
ROBOCO_WORKSPACE_AUTO_CLONE=true
|
||||
ROBOCO_WORKSPACE_CLONE_TIMEOUT=300
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. Workspace Resolution
|
||||
|
||||
When an agent makes a git/test API request:
|
||||
|
||||
```
|
||||
Agent: be-dev-1 (team: backend)
|
||||
Project: roboco
|
||||
→ Workspace: /data/workspaces/roboco/backend/be-dev-1/
|
||||
```
|
||||
|
||||
### 2. Auto-Clone
|
||||
|
||||
If `ROBOCO_WORKSPACE_AUTO_CLONE=true` and workspace doesn't exist:
|
||||
|
||||
1. Create parent directories
|
||||
2. Clone from project's `git_url`
|
||||
3. Checkout `default_branch`
|
||||
|
||||
### 3. API Flow
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────────┐ ┌──────────────────┐
|
||||
│ Agent │────▶│ API Endpoint │────▶│ WorkspaceService│
|
||||
│ (be-dev-1) │ │ (git/test) │ │ │
|
||||
└─────────────┘ └─────────────────┘ └──────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────┐ ┌──────────────────┐
|
||||
│ X-Agent-ID │ │ Resolve path: │
|
||||
│ X-Agent-Role│ │ /workspaces/ │
|
||||
│ X-Agent-Team│ │ roboco/ │
|
||||
└─────────────┘ │ backend/ │
|
||||
│ be-dev-1/ │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
## API Endpoints
|
||||
|
||||
### WorkspaceService Methods
|
||||
|
||||
```python
|
||||
from roboco.services.workspace import get_workspace_service
|
||||
|
||||
service = get_workspace_service(db)
|
||||
|
||||
# Get workspace path
|
||||
path = service.get_workspace_path("roboco", "backend", "be-dev-1")
|
||||
# → Path("/data/workspaces/roboco/backend/be-dev-1")
|
||||
|
||||
# Resolve from agent UUID
|
||||
path = await service.resolve_workspace("roboco", agent_uuid)
|
||||
|
||||
# Ensure workspace exists (clone if needed)
|
||||
path = await service.ensure_workspace(
|
||||
project_slug="roboco",
|
||||
agent_id=agent_uuid,
|
||||
git_url="git@github.com:org/roboco.git",
|
||||
default_branch="main"
|
||||
)
|
||||
|
||||
# List all workspaces for a project
|
||||
workspaces = await service.list_workspaces("roboco")
|
||||
# [{"team": "backend", "agent": "be-dev-1", "path": "...", "exists": True}, ...]
|
||||
|
||||
# Delete workspace (use with caution)
|
||||
deleted = await service.delete_workspace("roboco", agent_uuid)
|
||||
```
|
||||
|
||||
## Git Workflow
|
||||
|
||||
### Branch Naming
|
||||
|
||||
Each agent works on task-specific branches:
|
||||
|
||||
```
|
||||
{type}/{team}/{task-id-first-8-chars}
|
||||
|
||||
Examples:
|
||||
- feature/backend/abc12345 (be-dev-1 on Task ABC12345)
|
||||
- fix/backend/def67890 (be-dev-2 on Task DEF67890)
|
||||
- feature/frontend/ghi11223 (fe-dev-1 on Task GHI11223)
|
||||
```
|
||||
|
||||
### Parallel Work Example
|
||||
|
||||
```
|
||||
be-dev-1 workspace:
|
||||
└── branch: feature/backend/task-001
|
||||
└── Working on user authentication
|
||||
|
||||
be-dev-2 workspace:
|
||||
└── branch: fix/backend/task-002
|
||||
└── Fixing database connection issue
|
||||
|
||||
(Both agents work simultaneously, no conflicts)
|
||||
```
|
||||
|
||||
## Backwards Compatibility
|
||||
|
||||
The system maintains backwards compatibility with the legacy `workspace_path` field on Projects:
|
||||
|
||||
1. If `agent_id` is provided → Use multi-agent workspace resolution
|
||||
2. If `agent_id` is `None` → Fall back to `project.workspace_path`
|
||||
|
||||
This allows gradual migration from single-workspace to multi-agent workspaces.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### For PMs
|
||||
|
||||
1. **Register projects** with `git_url` - workspaces are created automatically
|
||||
2. **Don't set `workspace_path`** on projects - let the system manage workspaces
|
||||
3. **Assign tasks to specific agents** - each gets their own workspace
|
||||
|
||||
### For Developers (Agents)
|
||||
|
||||
1. **Always work in your workspace** - don't access other agents' workspaces
|
||||
2. **Commit frequently** - your workspace is yours alone
|
||||
3. **Create PRs** - merge through the standard PR process
|
||||
|
||||
### For Operations
|
||||
|
||||
1. **Set `ROBOCO_WORKSPACES_ROOT`** to a location with sufficient disk space
|
||||
2. **Consider NFS/shared storage** for multi-node deployments
|
||||
3. **Monitor disk usage** - workspaces can grow large
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Workspace Not Found
|
||||
|
||||
```
|
||||
WorkspaceError: Agent not found: be-dev-1
|
||||
```
|
||||
|
||||
**Solution**: Ensure the agent exists in the database with correct team.
|
||||
|
||||
### Clone Failed
|
||||
|
||||
```
|
||||
WorkspaceError: Failed to clone repository: Permission denied
|
||||
```
|
||||
|
||||
**Solution**: Ensure the RoboCo service has SSH keys configured for git access.
|
||||
|
||||
### Disk Space
|
||||
|
||||
```
|
||||
WorkspaceError: No space left on device
|
||||
```
|
||||
|
||||
**Solution**: Clean up old workspaces or expand storage:
|
||||
|
||||
```python
|
||||
# Delete workspace for an agent
|
||||
await service.delete_workspace("roboco", agent_uuid)
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
1. **Workspace Isolation**: Agents should only access their own workspaces
|
||||
2. **Git Credentials**: Store SSH keys securely, don't expose in workspaces
|
||||
3. **File Permissions**: Ensure appropriate Unix permissions on workspace directories
|
||||
4. **Network Access**: Workspaces need network access for git operations
|
||||
Reference in New Issue
Block a user