Metadata-Version: 2.4
Name: deep-agent-cli
Version: 1.0.0
Summary: Hệ thống trợ lý lập trình tự trị tối tân trên giao diện CLI
Home-page: https://github.com/tonda/AiCodingAgents
Author: DeepMind Pair Programmer
Author-email: support@deepagent.cli
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: yaml~=0.2.5
Requires-Dist: pyyaml~=6.0.3
Requires-Dist: pydantic~=2.13.4
Requires-Dist: deepagents~=0.6.2
Requires-Dist: langgraph~=1.2.0
Requires-Dist: langchain-openai~=1.2.1
Requires-Dist: langchain-anthropic~=1.4.3
Requires-Dist: dotenv~=0.9.9
Requires-Dist: python-dotenv~=1.2.2
Requires-Dist: langchain-google-genai~=4.2.2
Requires-Dist: langchain-ollama~=1.1.0
Requires-Dist: langchain-core~=1.4.0
Requires-Dist: rich~=15.0.0
Dynamic: author
Dynamic: author-email
Dynamic: home-page
Dynamic: requires-python

# 🤖 AI Coding Agent (Deep Agent CLI)

Hệ thống trợ lý lập trình tự trị (Autonomous Coding Agent) chuyên nghiệp trên nền tảng giao diện dòng lệnh (CLI). Hệ thống được xây dựng trên mô hình kiến trúc MVC, áp dụng các nguyên tắc hướng đối tượng sâu sắc, thiết kế tối ưu hóa module và hỗ trợ tích hợp linh hoạt đa nền tảng LLM (Multi-Provider).

Hệ thống có khả năng tự động đọc hiểu mã nguồn, phân tích lỗi, refactor, viết code và tương tác với các công cụ hệ thống dưới sự kiểm soát an toàn của con người (Human-in-the-loop).

---

## 🎯 Các Tính Năng Nổi Bật

*   **Multi-Provider Support (Tách biệt LLM Logic):** Không phụ thuộc vào bất kỳ nhà cung cấp LLM cụ thể nào. Mọi mô hình được chuẩn hóa qua `LLMFactory` (hỗ trợ **Google Gemini**, **OpenAI**, **Anthropic**, và các mô hình cục bộ qua **Ollama**).
*   **Giao Diện CLI Premium (Thư viện Rich):** Trải nghiệm người dùng cao cấp với banner chào mừng, các bảng thông tin trực quan, hiển thị chi tiết các cuộc gọi công cụ (tool call), kết quả trả về dưới dạng bảng/panel màu sắc phong phú (phối màu kiểu HSL hài hòa), và kết xuất nội dung Markdown hoàn hảo.
*   **Cơ chế Suy nghĩ và Stream thời gian thực:** Hiển thị trực tiếp luồng suy nghĩ của Agent (tách biệt với kết quả trả về) theo cơ chế truyền phát (stream) thời gian thực với màu sắc đặc trưng.
*   **Human-in-the-loop (HIL) - Phê duyệt an toàn:** Tự động phát hiện và ngắt khi Agent gọi các công cụ nhạy cảm. Giao diện CLI hiển thị bảng yêu cầu phê duyệt tương tác trực quan cho phép người dùng **Cho phép (Approve)** hoặc **Từ chối (Reject)** kèm lời nhắn/lý do hướng dẫn cụ thể.
*   **Quản lý cấu hình động:** Thay đổi trực tiếp LLM Provider, Model, API Key và độ sáng tạo (Temperature) ngay trên dòng lệnh thông qua các lệnh Slash (`/`). Cấu hình tự động đồng bộ hóa xuống tệp môi trường `.env`.
*   **Lưu trữ Checkpoint thông minh:** Sử dụng `CheckpointFactory` để duy trì và khôi phục trạng thái hội thoại. Hỗ trợ lưu trữ tạm thời trong bộ nhớ (`MemorySaver`) và lưu trữ bền vững qua cơ sở dữ liệu (`SqliteSaver`).
*   **Fault Tolerance (Chống lỗi toàn diện):** Sử dụng các khối bảo vệ `try-except` xung quanh tất cả các tương tác LLM và luồng thực thi Agent, đảm bảo CLI hoạt động liên tục, ổn định và không bị crash đột ngột khi xảy ra sự cố mạng hoặc lỗi nhà cung cấp.
*   **Ngắt luồng bằng phím tắt:** Hỗ trợ ngắt luồng suy nghĩ hoặc thao tác đang chạy bất cứ lúc nào bằng phím tắt `Ctrl + C` một cách an toàn mà không làm sập ứng dụng.

---

## 🏗️ Kiến Trúc Hệ Thống (Software Architecture)

Hệ thống được tổ chức chặt chẽ theo hai trục chính: **Kiến trúc Dịch vụ & Factory ở Backend** và **Mô hình MVC ở Frontend CLI**.

```mermaid
graph TD
    subgraph UI (Mô hình MVC)
        ChatView[ChatView - Giao diện Rich] <--> ChatController[ChatController - Điều phối]
        ChatController <--> ChatModel[ChatModel - Trạng thái CLI]
    end

    subgraph Services (Singleton Services)
        ChatController <--> ChatService[ChatService - Quản lý hội thoại]
        ChatController <--> ConfigService[ConfigService - Quản lý cấu hình]
    end

    subgraph Core (Hệ thống cốt lõi)
        ConfigService --> DeepAgentFactory[DeepAgentFactory]
        DeepAgentFactory --> LLMFactory[LLMFactory - Tạo LLM]
        DeepAgentFactory --> CheckpointFactory[CheckpointFactory - Lưu trạng thái]
        DeepAgentFactory --> DeepAgent[DeepAgent - Thực thể Agent chính]
        ChatService --> DeepAgent
    end

    LLMFactory --> OpenAI[OpenAI Provider]
    LLMFactory --> Anthropic[Anthropic Provider]
    LLMFactory --> Google[Google Provider]
    LLMFactory --> Ollama[Ollama Provider]

    CheckpointFactory --> Memory[InMemory Saver]
    CheckpointFactory --> SQLite[SQLite Saver]
```

### 1. Mô hình MVC của Giao Diện
*   **`ChatModel` (Model):** Lưu giữ trạng thái hiện tại của phiên hội thoại (ID luồng hội thoại `thread_id`, trạng thái hoạt động, danh sách hành động chờ phê duyệt, lịch sử hội thoại CLI).
*   **`ChatView` (View):** Chịu trách nhiệm render dữ liệu và tương tác ra màn hình console bằng thư viện `rich`. View hoàn toàn không chứa logic nghiệp vụ.
*   **`ChatController` (Controller):** Đóng vai trò là cầu nối, bắt các sự kiện đầu vào từ người dùng, gọi các dịch vụ nghiệp vụ (Services) tương ứng để xử lý và cập nhật Model, từ đó ra lệnh cho View cập nhật giao diện hiển thị.

### 2. Các Dịch Vụ Nghiệp Vụ (Core Services)
*   **`ConfigService` (Singleton):** Quản lý cấu hình hệ thống bao gồm Provider, Model, API Key, Temperature. Quản lý vòng đời khởi tạo của Agent. Tự động cập nhật các thay đổi vào file `.env` một cách an toàn mà không phá vỡ cấu trúc nguyên bản của file.
*   **`ChatService` (Singleton):** Xử lý giao tiếp trực tiếp với Agent. Quản lý việc stream luồng suy nghĩ thông qua phương thức `agent.stream`, trích xuất các yêu cầu phê duyệt công cụ (interrupts), truyền phát kết quả và gửi quyết định phản hồi (resume) của người dùng trở lại Agent.

### 3. Các Lớp Khởi Tạo (Factories)
*   **`LLMFactory`:** Cung cấp interface thống nhất để khởi tạo thực thể `BaseChatModel` của LangChain cho từng nhà cung cấp khác nhau qua kỹ thuật nạp chậm (Lazy Import) nhằm tối ưu tài nguyên.
*   **`CheckpointFactory`:** Khởi tạo công cụ lưu trữ checkpoint trạng thái hội thoại (`MemorySaver` hoặc `SqliteSaver`) dựa trên cấu hình hệ thống.
*   **`DeepAgentFactory`:** Đọc cấu hình prompts hệ thống (`config.yml`) và danh sách các subagent (`subagent.yml`) để lắp ráp hoàn chỉnh một thực thể `DeepAgent` tích hợp.

---

## 📂 Cấu Trúc Thư Mục (Folder Structure)

```text
AiCodingAgents/
├── app/
│   ├── core/
│   │   ├── agent/
│   │   │   ├── __init__.py
│   │   │   └── deep_agent.py          # Lớp Factory chế tạo DeepAgent tự trị
│   │   ├── checkpoint/
│   │   │   ├── __init__.py
│   │   │   └── factory.py             # Quản lý lưu trữ trạng thái (Memory/SQLite)
│   │   ├── LLM/
│   │   │   ├── __init__.py
│   │   │   ├── factory.py             # Factory Pattern cho phép khởi tạo đa LLM
│   │   │   ├── google_provider.py     # Thiết lập riêng cho mô hình Google
│   │   │   ├── openai_provider.py     # Thiết lập riêng cho mô hình OpenAI
│   │   │   ├── anthropic_provider.py  # Thiết lập riêng cho mô hình Anthropic
│   │   │   └── ollama_provider.py     # Thiết lập riêng cho mô hình Ollama chạy Local
│   │   └── __init__.py
│   ├── service/
│   │   ├── __init__.py
│   │   ├── ChatService.py             # Điều phối hội thoại, HIL và stream (Singleton)
│   │   └── ConfigService.py           # Quản lý cấu hình hệ thống và file .env (Singleton)
│   └── __init__.py
├── config/
│   ├── sys-prompt/                    # Thư mục lưu trữ prompts chi tiết
│   ├── v0/                            # Cấu hình v0 (mặc định)
│   │   ├── config.yml                 # Chứa system prompt của Agent chính
│   │   └── subagent.yml               # Định nghĩa các subagent hỗ trợ
│   └── v1/                            # Cấu hình v1 nâng cao
│       ├── config.yml
│       └── subagent.yml
├── ui/
│   ├── controllers/
│   │   └── ChatController.py          # Lớp điều phối sự kiện và CLI loop (Controller)
│   ├── models/
│   │   └── ChatModel.py               # Lưu trữ trạng thái phiên hoạt động (Model)
│   ├── views/
│   │   └── ChatView.py                # Hiển thị giao diện Rich ra console (View)
│   └── __init__.py
├── .env                               # Tệp cấu hình các biến môi trường
├── main.py                            # Điểm khởi chạy ứng dụng chính
├── GEMINI.md                          # Tài liệu hướng dẫn & Quy tắc của dự án
└── README.md                          # Hướng dẫn sử dụng này
```

---

## 🛠️ Hướng Dẫn Cài Đặt & Cấu Hình

### 1. Yêu Cầu Hệ Thống
*   **Ngôn ngữ:** Python 3.11 trở lên
*   **Hệ điều hành:** Hỗ trợ tốt trên cả Windows, macOS và Linux.

### 2. Cài Đặt Thư Viện
Hãy chắc chắn rằng bạn đã kích hoạt môi trường ảo (virtual environment) trước khi cài đặt các thư viện cần thiết:

```bash
pip install -r requirements.txt
```
*(Nếu chưa có file requirements.txt, bạn cần cài đặt các thư viện lõi: `langchain`, `langgraph`, `rich`, `pydantic`, `pyyaml`, `python-dotenv` và các package của provider tương ứng như `langchain-google-genai`, `langchain-openai`, `langchain-anthropic`)*

### 3. Thiết Lập Biến Môi Trường
Tạo một file `.env` tại thư mục gốc của dự án với nội dung như sau:

```env
# Nhà cung cấp và Model mặc định khi khởi chạy
DEFAULT_PROVIDER=google
DEFAULT_MODEL=models/gemma-4-31b-it
CONFIG_PATH=config/v0

# Các khóa API nhà cung cấp (Thay thế bằng khóa thực tế của bạn)
GOOGLE_API_KEY=AIzaSy...
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

---

## 🚀 Hướng Dẫn Sử Dụng

Khởi chạy ứng dụng trực tiếp bằng câu lệnh sau:

```bash
python main.py
```

### 💡 Các Lệnh Điều Hướng CLI (Slash Commands)
Ngay trong khung chat của CLI, bạn có thể nhập các lệnh bắt đầu bằng ký tự gạch chéo `/` để điều khiển ứng dụng nhanh chóng:

| Lệnh | Chi tiết | Ví dụ |
| :--- | :--- | :--- |
| `/help` | Hiển thị bảng hướng dẫn các câu lệnh khả dụng. | `/help` |
| `/config` | Xem chi tiết cấu hình hiện tại (Provider, Model, Temp, Thread ID). | `/config` |
| `/provider <tên>` | Thay đổi LLM Provider (google, openai, anthropic, ollama). | `/provider openai` |
| `/model <tên>` | Thay đổi Model của provider hiện tại. | `/model gpt-4o` |
| `/apikey <khóa>` | Cập nhật API Key mới cho provider đang hoạt động. | `/apikey sk-xxxx...` |
| `/temp <số>` | Thiết lập lại độ sáng tạo Temperature (từ `0.0` đến `2.0`). | `/temp 0.5` |
| `/history` | Xem lại toàn bộ tiến trình lịch sử trò chuyện trong thread hiện tại. | `/history` |
| `/clear` | Xóa sạch màn hình console và in lại banner hệ thống. | `/clear` |
| `/exit` hoặc `/quit`| Thoát ứng dụng CLI an toàn. | `/exit` |

### 🛑 Trải Nghiệm Quy Trình Human-in-the-loop (HIL)
Khi Agent yêu cầu thực hiện hành động hệ thống bị ngắt (do cấu hình trong `subagent.yml` chỉ định các tool thuộc nhóm `interrupt_on`), CLI sẽ kích hoạt bảng quản lý phê duyệt:

1.  Hệ thống hiển thị **Tên Công cụ**, **ID Yêu cầu** và chi tiết **Tham số truyền vào**.
2.  Yêu cầu lựa chọn:
    *   Nhập `a` hoặc `approve` để **Đồng ý** cho phép công cụ thực thi.
    *   Nhập `r` hoặc `reject` để **Từ chối** không cho phép công cụ chạy.
3.  Hệ thống sẽ hỏi thêm **Lời nhắn gửi cho Agent** (nếu Phê duyệt) hoặc **Lý do từ chối** (nếu Từ chối). Nội dung này sẽ được trả lại đầy đủ cho Agent để điều chỉnh hành vi suy nghĩ ở bước kế tiếp.

---

## 🧠 Nguyên Tắc Phát Triển & Mở Rộng Hệ Thống (Dành Cho Nhà Phát Triển)

Để đảm bảo hệ thống duy trì được tính nhất quán và kiến trúc chuẩn mực khi mở rộng:

1.  **Thiết kế Hướng đối tượng (OOP):** Tất cả các thành phần logic mới phải được tổ chức trong các Class có trách nhiệm rõ ràng. Áp dụng chuẩn Design Pattern (Factory, Singleton, v.v.).
2.  **Mở rộng LLM Provider:** Khi tích hợp một provider mới, hãy tạo một file cấu hình provider riêng biệt trong `app/core/LLM/` (ví dụ: `my_provider.py`) chứa hàm khởi tạo trả về đối tượng kế thừa từ `BaseChatModel`. Sau đó đăng ký provider mới trong `LLMFactory` tại `app/core/LLM/factory.py`. Không import hoặc khởi tạo trực tiếp mô hình ở ngoài Factory.
3.  **Bảo vệ mã nguồn (Clean Code & Fault Tolerance):** Sử dụng các khối kiểm soát lỗi `try-except` khi giao tiếp với các module không ổn định hoặc các dịch vụ bên ngoài (LLM, File IO). Giữ nguyên các ghi chú, docstring gốc của mã nguồn khi refactor.
4.  **Chỉnh sửa Giao diện CLI:** Khi muốn bổ sung tính năng giao diện, hãy tuân thủ mô hình MVC. Trạng thái lưu trữ tại `ChatModel`, logic render tại `ChatView` và luồng điều khiển xử lý tại `ChatController`. Đọc kỹ file mô tả hành vi của các service nếu có trước khi tích hợp API.
