معماری سیستم Nexel Agent
بازطراحی
clash.py— تبدیل یک نمونه اولیه تک‌فایلی به یک پلتفرم Agent محلی، ماژولار و سمت‌سرور.
سند مرجع معماری: هر تغییر معماری مهم باید ابتدا در این سند ثبت و به‌روزرسانی شود.
۱. چرا بازطراحی؟
clash.py یک نمونه اولیه قدرتمند با حدود ۱۲٬۰۲۰ خط کد در یک فایل است، اما از نظر معماری به محدودیت‌های خود رسیده است:
| مشکل | پیامد |
|---|---|
| حلقه Agent داخل مرورگر اجرا می‌شود | با Refresh صفحه، اجرای چندمرحله‌ای از بین می‌رود |
| کل UI با حدود ۸٬۹۰۰ خط داخل یک رشته Python قرار دارد | Lint و Debug دشوار است و تفکیک وظایف وجود ندارد |
| Session و Database وجود ندارد | چند تب می‌توانند با هم Race Condition ایجاد کنند و وضعیت سمت‌سرور ذخیره نمی‌شود |
run_python بدون Sandbox اجرا می‌شود |
کد به محیط کاربر و متغیرهای محیطی، از جمله Secretها، دسترسی کامل دارد |
| Tool Call با Brace Scanning پارس می‌شود | روش شکننده است و مستعد خطا و ناسازگاری بین لیست‌های ابزار است |
| Authentication، Rate Limit و Audit وجود ندارد | هر Process محلی می‌تواند عملیات اجرا کند بدون اینکه ردپای مناسبی باقی بماند |
چیزهایی که حفظ می‌کنیم
الگوهای موفق نسخه اولیه Nexel حفظ خواهند شد:
-
محدودسازی مسیر با
safe_path -
قرارداد ضدتوهم: Nexel فقط زمانی موفقیت ذخیره‌سازی را اعلام کند که خود ابزار آن را تأیید کرده باشد
-
Snapshot قبل و بعد از ویرایش
-
Read-back Verification بعد از تغییر فایل
-
ارائه راهنمایی Follow-up پس از هر نتیجه ابزار
۲. اصول طراحی
۲.۱ حلقه Agent سمت‌سرور
مرورگر فقط نقش نمایشگر و Client را دارد.
حلقه اصلی Nexel Agent در سمت‌سرور اجرا می‌شود و اجرای آن قابل:
-
Checkpoint
-
Resume
-
Audit
-
Monitoring
است.
۲.۲ قراردادهای مرکزی
فایل:
core/models.py
تنها منبع حقیقت برای Data Contractهای مشترک است.
هیچ ماژول Core نباید برای تعریف مدل‌های مشترک به server.py وابسته باشد.
۲.۳ ایزوله‌سازی Session
هر Session محیط خصوصی خودش را دارد:
Session
├── Private Directory
├── Workspace
├── History
└── Metadata
Sessionها نباید به‌صورت ضمنی به Workspace یا Memory مربوط به Session دیگر دسترسی داشته باشند.
۲.۴ سیاست متمرکز، اجرای محدود
تصمیم امنیتی توسط:
Policy Engine
گرفته می‌شود.
اجرای واقعی توسط:
Sandbox
محدود می‌شود.
و همه عملیات مهم توسط:
Audit
ثبت می‌شوند.
۲.۵ معماری تدریجی
قابلیت‌های پیشرفته مانند:
-
Docker
-
Embeddings
-
MCP
-
Providerهای مختلف مدل
به‌صورت Adapter پیاده‌سازی می‌شوند و برای آن‌ها Fallback در نظر گرفته می‌شود.
Nexel نباید برای اجرای قابلیت‌های پایه به این امکانات وابسته باشد.
۲.۶ سازگاری Python 3.9+
پروژه باید با Python 3.9 و نسخه‌های جدیدتر سازگار باشد.
نباید از Syntaxهایی استفاده شود که در Python 3.9 وجود ندارند.
مثلاً:
# نادرست برای Python 3.9
str | None
# جایگزین
Optional[str]
همچنین استفاده از match/case نیز انجام نمی‌شود.
۳. ساختار پکیج
nexel-agent/
├── clash.py
│
├── nexel_agent/
│ ├── __init__.py
│ ├── server.py
│ │
│ ├── core/
│ │ ├── __init__.py
│ │ ├── models.py
│ │ ├── sessions.py
│ │ ├── context.py
│ │ ├── router.py
│ │ ├── planner.py
│ │ └── orchestrator.py
│ │
│ ├── tools/
│ │ ├── __init__.py
│ │ ├── base.py
│ │ ├── filesystem.py
│ │ └── code.py
│ │
│ ├── memory/
│ │ ├── __init__.py
│ │ ├── store.py
│ │ └── cache.py
│ │
│ ├── safety/
│ │ ├── __init__.py
│ │ ├── policy.py
│ │ ├── sandbox.py
│ │ ├── approvals.py
│ │ └── audit.py
│ │
│ └── web/
│ └── static/
│ └── index.html
│
├── tests/
├── ARCHITECTURE.md
├── ARCHITECTURE.fa.md
└── README.md
نقش فایل‌های اصلی
clash.py
پیاده‌سازی اولیه و مرجع است و در طول Migration دست‌نخورده باقی می‌ماند.
nexel_agent/server.py
سرور اصلی Nexel.
nexel_agent/core/
منطق مرکزی Agent.
nexel_agent/tools/
ابزارهای قابل فراخوانی توسط Agent.
nexel_agent/memory/
حافظه بلندمدت، Retrieval و Cache.
nexel_agent/safety/
تمام لایه‌های امنیتی.
۴. جریان اجرای Nexel Agent
کاربر
│
│ POST /api/sessions/{sid}/runs
│ { "goal": "..." }
▼
AgentOrchestrator.run()
│
├── 1. Planner → TaskPlan
│
└── 2. Checkpoint
│
▼
حلقه Stepها
│
├── 3. ContextManager.build()
│ ↓
│ پیام‌های Token-Aware
│
├── 4. ModelRouter
│ ↓
│ انتخاب مدل + Stream
│
├── 5. PolicyEngine.evaluate(tool_call)
│
│ ├── NEEDS_APPROVAL
│ │ ↓
│ │ توقف و انتظار تصمیم کاربر
│ │
│ ├── DENY
│ │ ↓
│ │ ToolResult(denied)
│ │
│ └── ALLOW
│ ↓
│
├── 6. ToolRegistry.execute()
│ ↓
│ Sandbox
│
├── 7. Audit.log()
│ ↓
│ ToolResult
│ ↓
│ بازگرداندن به Model
│
└── 8. Memory.remember()
│
▼
پایان
│
├── RunStatus = completed
├── RUN_FINISHED
└── خلاصه در Memory
۵. ماژول‌های Core
۵.۱ core/models.py
این فایل تنها محل تعریف قراردادهای مشترک Nexel است.
مدل‌های اصلی:
AgentMessage
ToolCall
ToolResult
ToolSpec
StepEvent
PolicyDecision
ApprovalRequest
TaskPlan
MemoryRecord
AuditRecord
این فایل نباید شامل منطق اجرایی باشد.
وظیفه آن فقط تعریف ساختار داده‌ها و قراردادهای بین ماژول‌هاست.
۵.۲ core/sessions.py
Session
هر Session شامل موارد زیر است:
-
id -
دایرکتوری خصوصی
-
workspace_root -
تاریخچه گفتگو
-
Metadata
-
وضعیت اجرای Agent
نمونه ساختار:
sessions/
└── session_xxxxx/
├── workspace/
├── history.db
├── checkpoints/
└── metadata.json
SessionStore
ذخیره‌سازی Sessionها بر پایه SQLite انجام می‌شود.
وظایف:
-
ایجاد Session
-
خواندن Session
-
به‌روزرسانی Session
-
ذخیره وضعیت
-
عملیات اتمی
-
Cleanup Sessionهای قدیمی
۵.۳ core/context.py
ContextManager وظیفه مدیریت Context مدل را دارد.
قابلیت‌ها
-
شمارش تقریبی Token
-
پشتیبانی اختیاری از
tiktoken -
حفظ System Message
-
حفظ جدیدترین پیام‌ها
-
فشرده‌سازی بخش میانی History
-
خلاصه‌سازی تدریجی
-
محدود کردن Context بر اساس Token Budget
ساختار:
History
│
├── System Messages
│
├── Older Messages
│ ↓
│ Summarization
│
└── Recent Messages
↓
Final Context
به‌جای محدود کردن Context صرفاً بر اساس تعداد کاراکتر، Nexel از Token Budget استفاده می‌کند.
۵.۴ core/router.py
ModelRouter وظیفه انتخاب مدل مناسب را بر اساس نوع کار برعهده دارد.
مثلاً:
{
"classify": "light-model",
"plan": "light-model",
"generate": "large-model"
}
مسئولیت‌ها
-
انتخاب مدل
-
Stream کردن پاسخ
-
Retry
-
Fallback
-
مدیریت خطای Provider
-
ارتباط با Ollama
-
امکان اضافه‌کردن Providerهای دیگر
معماری Router:
ModelRouter
│
┌─────────────┼─────────────┐
│ │ │
▼ ▼ ▼
Ollama Provider A Provider B
۵.۵ core/planner.py
Planner هدف کاربر را به یک TaskPlan تبدیل می‌کند.
قابلیت‌ها
-
دریافت Goal
-
تجزیه کار
-
ایجاد DAG
-
تعیین وابستگی‌ها
-
استفاده از مدل سبک
-
Fallback بدون مدل
نمونه:
Goal
│
▼
Task A
│
▼
Task B
│
├── depends_on: [A]
▼
Task C
└── depends_on: [B]
در صورت نبود Model مناسب:
Goal
↓
Single Step Task
به‌عنوان Fallback استفاده می‌شود.
۵.۶ core/orchestrator.py
این ماژول قلب Nexel Agent است.
مسئولیت‌ها
-
اجرای حلقه Agent
-
مدیریت
max_steps -
مدیریت Token Budget
-
تشخیص تکرار
-
تشخیص خطاهای متوالی
-
Checkpoint در هر Step
-
انتشار
StepEvent -
Pause و Resume
-
مدیریت Approval
-
Reflection
-
Verification
-
هماهنگی Memory
-
هماهنگی Audit
چرخه اجرای یک Run
RUN_CREATED
↓
PLANNING
↓
CHECKPOINTED
↓
RUNNING
↓
TOOL_CALL
↓
POLICY_CHECK
│
├── DENIED
│
├── APPROVAL_REQUIRED
│
└── ALLOWED
↓
TOOL_EXECUTION
↓
TOOL_RESULT
↓
MODEL CONTINUES
↓
VERIFICATION
↓
REFLECTION
↓
NEXT STEP / DONE
۶. سیستم ابزارها
۶.۱ ToolRegistry
تمام ابزارها از طریق یک Registry مرکزی مدیریت می‌شوند.
مسئولیت‌ها
-
ثبت ابزار
-
حذف ابزار
-
Lookup
-
Alias Resolution
-
تولید Schema
-
تولید Tool List برای Model
-
اجرای Tool
-
ایجاد
ToolContext
این طراحی جلوی Drift بین چند لیست دستی ابزار را می‌گیرد.
۶.۲ ابزارهای پایه
Nexel به‌صورت پایه از ابزارهای زیر پشتیبانی می‌کند:
list_files
read_file
write_file
edit_file
delete_file
run_python
search_files
validate_python
۶.۳ ToolContext
هر ابزار یک Context کنترل‌شده دریافت می‌کند که شامل اطلاعات موردنیاز مانند:
-
Session
-
Workspace
-
Run
-
Tool metadata
-
Policy metadata
-
Execution metadata
است.
ابزارها نباید مستقیماً محدودیت‌های Policy یا Sandbox را دور بزنند.
۷. ایزوله‌سازی فایل‌ها
تمام عملیات فایل باید از مسیر:
safe_path
عبور کنند.
فرآیند:
Requested Path
↓
resolve()
↓
workspace_root
↓
relative_to()
↓
Allowed / Rejected
هر مسیر خارج از Workspace باید رد شود.
به‌عنوان مثال:
workspace/
├── app.py
├── src/
└── data/
نباید امکان دسترسی به:
/etc/
/home/other-user/
/Users/another-user/
از طریق Toolهای Session وجود داشته باشد.
۸. Memory
۸.۱ memory/store.py
این ماژول حافظه بلندمدت Nexel را مدیریت می‌کند.
قابلیت‌ها
-
SQLite
-
Vector Storage
-
Cosine Similarity
-
Embeddings اختیاری
-
Fallback بدون Embeddings
-
ذخیره نکات مهم
-
ذخیره خلاصه Run
-
ذخیره اطلاعات Snapshot
۸.۲ Retrieval
معماری عمومی:
Query
↓
Embedding
↓
Vector Search
↓
Relevant Memories
↓
ContextManager
↓
Model
در صورت نبود Embedding Provider:
Query
↓
Normalized Search
↓
Fallback Retrieval
۸.۳ memory/cache.py
Semantic Cache برای جلوگیری از اجرای دوباره درخواست‌های مشابه استفاده می‌شود.
مراحل:
Query
↓
Normalize
↓
Stable Hash
↓
Cache Lookup
↓
Hit / Miss
Cache باید Session-aware باشد تا داده خصوصی یک Session به Session دیگری نشت نکند.
۹. سیستم امنیتی
۹.۱ safety/policy.py
PolicyEngine مرجع اصلی تصمیم‌های امنیتی است.
دسته‌های نمونه:
filesystem.read
filesystem.write
filesystem.delete
code.execute
network.access
process.spawn
environment.read
نتیجه ارزیابی:
ALLOW
DENY
NEEDS_APPROVAL
۹.۲ Policy Flow
Tool Call
↓
PolicyEngine
│
├── DENY
│
├── NEEDS_APPROVAL
│
└── ALLOW
↓
Tool
ابزارها نباید تصمیم امنیتی مستقل بگیرند.
۹.۳ safety/sandbox.py
تمام اجرای Code باید از Sandbox عبور کند.
Sandbox باید شامل موارد زیر باشد:
-
Scratch Directory
-
Environment ایزوله
-
Timeout
-
محدودیت Output
-
محدودیت Resource
-
کنترل Process
-
دسترسی محدود به فایل‌ها
۹.۴ Docker Adapter
Docker یک قابلیت اختیاری است.
معماری:
Code Request
↓
Sandbox Interface
│
├── Local Restricted Runtime
│
└── Docker Runtime
نبود Docker نباید باعث از کار افتادن قابلیت‌های اصلی Nexel شود.
۹.۵ safety/approvals.py
برای عملیات حساس، Nexel اجرای Agent را متوقف می‌کند و منتظر تصمیم کاربر می‌ماند.
وضعیت‌های Approval:
PENDING
APPROVED
DENIED
EXPIRED
یک ApprovalRequest می‌تواند شامل:
-
Request ID
-
Session ID
-
Run ID
-
Tool
-
Action
-
Reason
-
Expiration
-
Current State
باشد.
۹.۶ safety/audit.py
تمام عملیات مهم ثبت می‌شوند.
Audit شامل:
Allowed Operations
Denied Operations
Approval Requests
Tool Executions
Tool Failures
Policy Decisions
Session Events
Model Actions
حتی عملیات Reject شده نیز باید در Audit ثبت شوند.
۱۰. سرور Nexel
server.py
سرور اصلی Nexel با FastAPI ساخته می‌شود.
وظایف:
-
HTTP API
-
WebSocket
-
SSE
-
Session Management
-
Run Management
-
Approval API
-
Authentication
-
Rate Limiting
-
Async Task Execution
-
Health Checks
-
Logging
-
Metrics
۱۱. REST API
مسیرهای اصلی:
POST /api/sessions
GET /api/sessions/{sid}
DELETE /api/sessions/{sid}
POST /api/sessions/{sid}/runs
GET /api/sessions/{sid}/runs/{rid}
POST /api/sessions/{sid}/runs/{rid}/resume
POST /api/sessions/{sid}/runs/{rid}/cancel
GET /api/sessions/{sid}/events
GET /api/approvals
POST /api/approvals/{aid}/approve
POST /api/approvals/{aid}/deny
۱۲. Streaming
Nexel دو روش اصلی برای Streaming دارد.
SSE
مناسب برای دریافت رویدادهای یک‌طرفه:
RUN_CREATED
STEP_STARTED
MODEL_OUTPUT
TOOL_CALL
TOOL_RESULT
APPROVAL_REQUIRED
STEP_FINISHED
RUN_FINISHED
RUN_FAILED
WebSocket
برای Dashboardهای Interactive و ارتباط Bidirectional استفاده می‌شود.
۱۳. Authentication
سرور Nexel باید از API Key استفاده کند.
نمونه:
Authorization: Bearer
یا هر روش احراز هویت معادل که توسط تنظیمات سیستم تعیین شود.
API Key نباید:
-
وارد Prompt مدل شود
-
در Tool Output نمایش داده شود
-
در Log عمومی ثبت شود
۱۴. Rate Limiting
Rate Limit به‌صورت Per-Key اعمال می‌شود.
معیارها می‌توانند شامل موارد زیر باشند:
Requests / Minute
Runs / Minute
Concurrent Runs
Tool Executions
مقادیر باید قابل تنظیم باشند.
۱۵. Event Model
کل اجرای Nexel از طریق Eventهای ساختاریافته قابل مشاهده است.
مثال:
{
"type": "TOOL_RESULT",
"run_id": "run_123",
"step": 4,
"tool": "read_file",
"status": "success",
"timestamp": "2026-09-30T12:00:00Z"
}
Client پس از اتصال مجدد باید بتواند وضعیت Run را از روی Eventها بازسازی کند.
۱۶. Checkpoint و Resume
در هر Step مهم، وضعیت Agent ذخیره می‌شود.
Checkpoint می‌تواند شامل موارد زیر باشد:
Run State
Current Step
Task Plan
Conversation State
Tool Results
Pending Approval
Token Usage
Errors
Metadata
در صورت Restart شدن Process:
Server Restart
↓
Load Session
↓
Load Checkpoint
↓
Resume
Run نباید با Restart شدن سرور از صفر شروع شود؛ مگر اینکه Checkpoint معتبری وجود نداشته باشد.
۱۷. Verification Loop
بعد از عملیات مهم مانند تغییر فایل یا تولید Code، Nexel نتیجه را Verification می‌کند.
الگوی استاندارد:
EDIT
↓
SAVE
↓
READ BACK
↓
VALIDATE
↓
TEST / LINT
↓
PASS → CONTINUE
FAIL → REPAIR
این روش اصل مهم ضدتوهم و صحت عملیات را حفظ می‌کند.
۱۸. Self-Reflection
Nexel می‌تواند پس از عملیات مهم یک Reflection Step اجرا کند.
Reflection بررسی می‌کند:
آیا هدف کاربر محقق شد؟
آیا Tool نتیجه مورد انتظار را تولید کرد؟
آیا Verification لازم است؟
آیا Tool دیگری باید اجرا شود؟
آیا Plan نیاز به اصلاح دارد؟
Reflection باید محدود شود توسط:
max_steps
token_budget
retry_limit
repeat_detection
تا Infinite Loop ایجاد نشود.
۱۹. Repeat Detection
Nexel رفتارهای تکراری و بی‌نتیجه را تشخیص می‌دهد.
برای نمونه:
Same Tool
+
Same Arguments
+
Same Failure
یا:
Same Response Pattern
در چنین شرایطی Agent می‌تواند:
Stop
Retry Differently
Request Approval
Return Controlled Failure
۲۰. Token Budget
هر Run دارای Token Budget مشخص است.
بودجه میان بخش‌های مختلف تقسیم می‌شود:
Planning
Context Construction
Model Generation
Reflection
Tool Result Processing
با نزدیک شدن به سقف Token:
ContextManager
↓
Compaction
↓
Reduced Context
و در صورت پایان کامل بودجه، Run به‌صورت کنترل‌شده پایان می‌یابد.
۲۱. Observability
Nexel باید رفتار Agent را قابل اندازه‌گیری کند.
شاخص‌های اصلی:
Run Duration
Tool Duration
Model Latency
Token Usage
Errors
Retries
Policy Decisions
Approval Latency
Active Sessions
Concurrent Runs
Cache Hit Rate
همچنین Logهای ساختاریافته برای Debug و Monitoring استفاده می‌شوند.
۲۲. Snapshot و Rollback
قبل از تغییرات حساس یا مخرب، Nexel یک Snapshot ایجاد می‌کند.
Workspace
│
├── Snapshot A
│
├── Edit
│
├── Verification
│
└── Snapshot B
قابلیت‌ها:
-
مقایسه Before / After
-
Rollback
-
مشاهده تاریخچه تغییرات
-
بازیابی پس از Edit ناموفق
این سیستم لزوماً به Git وابسته نیست و می‌تواند با یک مکانیزم داخلی پیاده‌سازی شود.
۲۳. Import / Export
Nexel می‌تواند Session یا Project را به یک Bundle قابل انتقال تبدیل کند.
Bundle می‌تواند شامل:
Session Metadata
Workspace Files
Conversation History
Task Plan
Run History
Snapshots
Memory Entries
Configuration
Secretها به‌صورت پیش‌فرض نباید Export شوند.
۲۴. Plugin SDK
Nexel باید امکان توسعه Toolها توسط Pluginها را داشته باشد.
هر Plugin می‌تواند موارد زیر را تعریف کند:
name
description
input schema
output schema
permissions
execution handler
aliases
نمونه:
class NexelTool:
name = "example"
description = "Example Nexel tool"
def schema(self):
...
def execute(self, context, arguments):
...
Plugin همیشه باید از مسیر زیر عبور کند:
Plugin
↓
ToolRegistry
↓
PolicyEngine
↓
Sandbox
↓
Audit
Plugin نباید بتواند این مسیر را دور بزند.
۲۵. پشتیبانی MCP
MCP به‌صورت Adapter اختیاری پیاده‌سازی می‌شود.
Nexel ToolRegistry
│
├── Native Nexel Tools
│
└── MCP Adapter
│
└── External MCP Servers
ابزارهای MCP ابتدا به قرارداد داخلی Nexel تبدیل می‌شوند و سپس تحت همان Policy و Audit قرار می‌گیرند.
۲۶. ۳۰ قابلیت مدرن — نقشه پیاده‌سازی
| # | قابلیت | ماژول مسئول | وضعیت |
|---|---|---|---|
| 1 | حلقه Orchestration سمت‌سرور | core/orchestrator.py |
✅ |
| 2 | Native Structured Tool Calling | core/orchestrator.py |
✅ |
| 3 | Multi-Model Routing | core/router.py |
✅ |
| 4 | تجزیه Task به DAG | core/planner.py |
✅ |
| 5 | Self-Reflection Loop | core/orchestrator.py |
✅ |
| 6 | Intelligent Context Compaction | core/context.py |
✅ |
| 7 | Long-Term Memory + RAG | memory/store.py |
✅ |
| 8 | اجرای موازی Toolها | core/orchestrator.py |
✅ |
| 9 | Semantic Code Search | tools/ |
✅ |
| 10 | Verification Loop | core/orchestrator.py |
✅ |
| 11 | Sessionهای ایزوله + SQLite | core/sessions.py |
✅ |
| 12 | Checkpoint + Resume | core/orchestrator.py |
✅ |
| 13 | API Key + Authentication | server.py |
✅ |
| 14 | Rate Limiting بر اساس Key | server.py |
✅ |
| 15 | Async Task Queue | server.py |
✅ |
| 16 | Semantic Cache | memory/cache.py |
✅ |
| 17 | Real-Time WebSocket | server.py |
✅ |
| 18 | Watch Mode | core/ |
🔶 |
| 19 | Scheduled Tasks | core/ |
🔶 |
| 20 | Plugin SDK | tools/ |
✅ |
| 21 | Sandboxed Code Execution | safety/sandbox.py |
✅ |
| 22 | Centralized Policy Engine | safety/policy.py |
✅ |
| 23 | Human-in-the-Loop | safety/approvals.py |
✅ |
| 24 | Complete Audit Log | safety/audit.py |
✅ |
| 25 | Git-like Snapshot + Rollback | memory/store.py |
✅ |
| 26 | Retry + Model Fallback | core/router.py |
✅ |
| 27 | Token Budget Manager | core/orchestrator.py |
✅ |
| 28 | Observability | server.py |
✅ |
| 29 | Import / Export Bundle | tools/ |
✅ |
| 30 | MCP Support | tools/ |
🔶 |
✅ = در پیاده‌سازی پایه فعال
🔶 = اسکلت یا Adapter با فعال‌سازی تدریجی
۲۷. مدل امنیتی
مرز اعتماد
تمام مسیرهای فایل باید از:
safe_path
عبور کنند.
روند کلی:
resolve()
+
relative_to()
هر مسیر خارج از Workspace باید رد شود.
اجرای Code
Code هرگز نباید به‌صورت مستقیم اجرا شود.
روند:
PolicyEngine
↓
Sandbox
↓
Controlled Runtime
Sandbox مسئول محدودسازی:
-
فایل‌ها
-
Environment
-
زمان اجرا
-
خروجی
-
Resource
-
Process
است.
تصمیم متمرکز
فقط PolicyEngine مجاز به تعیین یکی از وضعیت‌های زیر است:
ALLOW
DENY
NEEDS_APPROVAL
Toolها نباید این تصمیم را دور بزنند.
Audit
همه عملیات امنیتی مهم باید ثبت شوند:
Allowed
Denied
Approval Requested
Tool Execution
Sandbox Failure
Filesystem Change
Model Action
Human Approval
عملیات حساس یا مخرب بالقوه تا دریافت تأیید صریح کاربر متوقف می‌شوند.
هیچ Approval ضمنی نباید فرض شود.
۲۸. مدیریت خطا
Nexel باید در تمام لایه‌ها Fail Gracefully داشته باشد.
خطای Model
Primary Model
↓ Failure
Fallback Model
↓ Failure
Controlled Run Failure
خطای Tool
Tool Error
↓
ToolResult(error)
↓
Model receives structured failure
↓
Retry / Alternative Strategy / Finish
Restart سرور
Server Restart
↓
Load Session
↓
Load Checkpoint
↓
Resume
۲۹. سیاست سازگاری
نسخه هدف:
Python 3.9+
موارد ممنوع:
str | None
جایگزین:
Optional[str]
همچنین:
match / case
استفاده نمی‌شود.
APIها و Dependencyهای جدید نیز باید در صورت نیاز دارای Fallback باشند.
۳۰. نیازمندی‌های Runtime
نصب:
pip install -r requirements.txt
Dependencyهای اصلی:
fastapi
uvicorn
pydantic
httpx
Dependencyهای اختیاری:
tiktoken
numpy
embedding providers
docker SDK
pytest
وابستگی‌های اختیاری نباید باعث از کار افتادن هسته Nexel شوند.
۳۱. اجرای Nexel
اجرای سرور:
uvicorn nexel_agent.server:app --host 127.0.0.1 --port 5000
آدرس پیش‌فرض:
http://127.0.0.1:5000
۳۲. اتصال به Ollama
Ollama اختیاری است.
تنظیم پیش‌فرض:
OLLAMA_URL=http://127.0.0.1:11434
روند اتصال:
Nexel
↓
ModelRouter
↓
Ollama
↓
Local Model
در صورت در دسترس نبودن Ollama، سرور همچنان باید اجرا شود.
در این حالت اجزای زیر همچنان قابل تست هستند:
Sessions
Checkpoints
Policies
Sandbox
Tool Registry
Audit
Events
Approvals
Memory
اما برای تولید واقعی پاسخ مدل، حداقل یک Model Provider باید فعال باشد.
۳۳. معماری Local-First
Nexel با رویکرد Local-First طراحی می‌شود.
اهداف اصلی:
-
اجرای محلی
-
Workspace محلی
-
Session Storage محلی
-
پشتیبانی از Local Model
-
عدم وابستگی اجباری به Cloud
-
Providerهای قابل تعویض
-
Sandboxهای قابل تعویض
در نتیجه Nexel می‌تواند به‌عنوان یک محیط مستقل برای توسعه‌دهندگان و Agentها اجرا شود.
۳۴. قواعد معماری غیرقابل‌مذاکره
قانون ۱ — مرورگر Agent نیست
Browser نباید مالک حلقه اجرای اصلی باشد.
قانون ۲ — دسترسی بدون محدودیت به فایل ممنوع است
هر مسیر باید از:
safe_path
عبور کند.
قانون ۳ — اجرای مستقیم Code ممنوع است
هر اجرای Code باید از:
Policy
+
Sandbox
عبور کند.
قانون ۴ — ادعای موفقیت بدون تأیید ابزار ممنوع است
Nexel نباید عملیاتی را موفق اعلام کند مگر اینکه Tool مربوطه موفقیت را صراحتاً گزارش کرده باشد.
قانون ۵ — همه عملیات مهم قابل Audit هستند
حتی درخواست‌های Denied نیز باید ثبت شوند.
قانون ۶ — Sessionها کاملاً ایزوله هستند
Session نباید بتواند به Workspace یا Memory خصوصی Session دیگری دسترسی غیرمجاز داشته باشد.
قانون ۷ — Contractها مرکزی هستند
تمام مدل‌های مشترک در:
core/models.py
تعریف می‌شوند.
قانون ۸ — قابلیت‌های پیشرفته باید Fallback داشته باشند
Docker، Embeddings، MCP و Providerهای جایگزین نباید باعث شوند هسته Nexel بدون آن‌ها از کار بیفتد.
۳۵. استراتژی Migration
بازطراحی باید تدریجی باشد و نباید یک Rewrite کامل و یک‌باره انجام شود.
Phase 1 — استخراج Contractها
ایجاد:
core/models.py
و انتقال تمام Data Modelهای مشترک.
Phase 2 — استخراج Sessionها
ایجاد:
core/sessions.py
و انتقال State به SQLite.
Phase 3 — استخراج Toolها
انتقال ابزارها به:
tools/
و ایجاد ToolRegistry.
Phase 4 — افزودن Safety
ایجاد:
safety/policy.py
safety/sandbox.py
safety/approvals.py
safety/audit.py
Phase 5 — انتقال Agent Loop به Server
پیاده‌سازی:
core/orchestrator.py
و تبدیل Browser به Client مشاهده‌کننده از طریق WebSocket/SSE.
Phase 6 — افزودن Planner و Router
ایجاد:
core/planner.py
core/router.py
Phase 7 — افزودن Context و Memory
ایجاد:
core/context.py
memory/store.py
memory/cache.py
Phase 8 — حذف UI داخل Python String
UI از clash.py جدا شده و به:
web/static/index.html
منتقل می‌شود.
الگوهای UX اثبات‌شده نسخه قدیمی تا حد امکان حفظ می‌شوند.
Phase 9 — Compatibility Layer
فایل:
clash.py
به‌عنوان Reference Implementation باقی می‌ماند.
تا زمانی که Nexel جدید به Feature Parity نرسیده است، نسخه اصلی نباید حذف شود.
۳۶. معیار تکمیل پروژه
بازطراحی Nexel زمانی عملیاتی محسوب می‌شود که:
✓ اجرای Agent کاملاً سمت‌سرور باشد
✓ Refresh مرورگر اجرای Run را متوقف نکند
✓ Sessionها در SQLite ذخیره شوند
✓ Runها Checkpoint شوند
✓ Runها قابل Resume باشند
✓ Tool Callها ساختاریافته باشند
✓ Toolها از Registry مرکزی استفاده کنند
✓ دسترسی فایل‌ها Workspace-Confined باشد
✓ اجرای Python Sandbox شده باشد
✓ Policy مرکزی وجود داشته باشد
✓ عملیات حساس قابلیت Approval داشته باشند
✓ عملیات مهم Audit شوند
✓ Model Routing دارای Fallback باشد
✓ Context به‌صورت Token-Aware مدیریت شود
✓ Memory بین Runها باقی بماند
✓ عملیات مهم Verification شوند
✓ Client بتواند به Run در حال اجرا دوباره متصل شود
✓ WebSocket/SSE فعال باشد
✓ API Key Authentication فعال باشد
✓ Rate Limiting فعال باشد
✓ قابلیت‌های اختیاری دارای Fallback باشند
✓ Python 3.9+ پشتیبانی شود
✓ clash.py به‌عنوان Reference حفظ شود
۳۷. معماری نهایی Nexel
┌──────────────────────┐
│ Browser │
│ Nexel Dashboard │
└──────────┬───────────┘
│
HTTP / SSE / WebSocket
│
▼
┌──────────────────────┐
│ Nexel Server │
│ FastAPI │
└──────────┬───────────┘
│
┌──────────────┴──────────────┐
│ │
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ AgentOrchestrator │ │ SessionStore │
│ Agent Loop │ │ SQLite │
└──────────┬──────────┘ └─────────────────────┘
│
┌──────────┼───────────┐
│ │ │
▼ ▼ ▼
┌────────┐ ┌─────────┐ ┌──────────┐
│ Planner│ │ Context │ │ Router │
└────────┘ └─────────┘ └────┬─────┘
│
▼
┌─────────────────┐
│ LLM Provider │
│ Ollama / Other │
└────────┬────────┘
│
▼
Structured Tool Call
│
▼
┌──────────────────────┐
│ Policy Engine │
└──────────┬───────────┘
│
┌───────────────┼───────────────┐
│ │ │
▼ ▼ ▼
DENY NEEDS_APPROVAL ALLOW
│ │
▼ ▼
┌────────────┐ ┌──────────────┐
│ Approval │ │ ToolRegistry │
└────────────┘ └──────┬───────┘
│
▼
┌─────────────┐
│ Sandbox │
└──────┬──────┘
│
▼
┌─────────────┐
│ Tool / Code │
└──────┬──────┘
│
┌──────────────┴──────────────┐
│ │
▼ ▼
Audit Log Tool Result
│ │
└──────────────┬──────────────┘
▼
AgentOrchestrator
│
┌─────────────┴─────────────┐
▼ ▼
Memory Checkpoint
۳۸. هویت پروژه
محصول
Nexel
Agent
Nexel Agent
نوع معماری
Local-First, Server-Side, Modular Agent Platform
Runtime اصلی
Python 3.9+
Web Framework
FastAPI
ذخیره‌سازی
SQLite
مدل محلی
Ollama — اختیاری
ارتباط
HTTP + WebSocket + SSE
امنیت
Policy Engine + Sandbox + Human Approval + Audit
Nexel Agent معماری هدف پروژه است.
clash.pyپیاده‌سازی مرجع اولیه باقی می‌ماند و در طول Migration نباید بدون دلیل معماری مشخص تغییر کند.
