aiframe-agent-cli 1.0.0

package/README.md

@@ -0,0 +1,91 @@
+# AI Frame CLI (aiframe-cli)
+
+**AI Frame CLI** là một framework mạnh mẽ giúp bạn xây dựng, quản lý và thực thi các AI Agents thông qua các luồng công việc (Workflows) có cấu trúc. Nền tảng này cho phép thiết lập tự động hóa các tác vụ phức tạp bằng cách kết hợp sức mạnh của các mô hình ngôn ngữ lớn (LLMs), các công cụ dòng lệnh (CLI Tools), và cả các Local Agents (như Claude Code, Antigravity).
+
+Đặc biệt, AI Frame CLI hỗ trợ:
+- **TDD / SDD Natively**: Các bước trong workflow hỗ trợ `validation` và `max_retries` để ép AI phải tự sửa lỗi code cho đến khi qua bài test.
+- **Workflow Isolation**: Chế độ `isolate_workspace` sử dụng Git Worktree để cô lập vùng làm việc của tác nhân AI, đảm bảo tuyệt đối an toàn cho source code gốc của dự án.
+- **UI Dashboard**: Tích hợp sẵn giao diện Web kéo thả trực quan để quản lý Agent, Skill và theo dõi trạng thái Workflow theo thời gian thực.
+- **Tương thích cao**: Hỗ trợ gọi Agent và Skill từ các thư mục nằm ngoài dự án thông qua đường dẫn tuyệt đối.
+
+## 🚀 Cài đặt
+
+Yêu cầu: **Node.js >= 18.0.0**
+
+Bạn có thể cài đặt thư viện dưới dạng global:
+```bash
+npm install -g aiframe-cli
+```
+Hoặc chạy trực tiếp bằng `npx` mà không cần cài đặt:
+```bash
+npx aiframe-cli init
+```
+
+## 🛠 Cách sử dụng
+
+### 1. Khởi tạo dự án
+Để thiết lập cấu trúc thư mục AI Frame cho dự án hiện tại:
+```bash
+aiframe init
+# Hoặc: npx aiframe-cli init
+```
+Lệnh này sẽ tự động tạo thư mục `.aiframe/` với các thư mục con: `agents/`, `workflows/`, `tools/`, `skills/` và file cấu hình `config.yaml`. Một file `GUIDELINE.md` chi tiết cũng sẽ được sinh ra ở thư mục gốc để hướng dẫn bạn viết luồng.
+
+### 2. Định nghĩa Agent
+Tạo file `.aiframe/agents/coder.yaml`:
+```yaml
+name: "Coder Agent"
+provider: "cli"
+cli_command: ["antigravity", "chat", "-m", "agent", "{{prompt}}"]
+role: "Bạn là một Lập trình viên Senior..."
+```
+
+### 3. Thiết kế Workflow
+Tạo file `.aiframe/workflows/build_feature.yaml`:
+```yaml
+name: "Feature Builder"
+settings:
+  max_loop_limit: 3
+  isolate_workspace: true # Bật Shadow Workspace (Git Worktree) để giữ an toàn cho code!
+
+steps:
+  - name: "Implement Feature"
+    use: "agent/coder"
+    instruction: "Code tính năng Đăng nhập."
+    validation:
+      command: "npm run test" # Tự động chạy test, nếu lỗi AI tự sửa (Auto-Healing)
+      expect_exit_code: 0
+    max_retries: 3
+```
+
+### 4. Thực thi Workflow
+Đứng tại thư mục gốc của dự án và chạy:
+```bash
+aiframe run .aiframe/workflows/build_feature.yaml
+```
+
+### 5. Khởi chạy Giao diện Web (Dashboard)
+AI Frame đi kèm một giao diện Web cho phép bạn kéo thả Workflow và theo dõi tiến trình chạy trực quan:
+```bash
+aiframe ui -p 3000
+```
+Mở trình duyệt tại: `http://localhost:3000`
+
+## ⚙ Cấu hình nâng cao (Tuỳ biến LLM)
+Sửa file `.aiframe/config.yaml` để thiết lập API Keys:
+```yaml
+default_model: gemini-1.5-flash
+openai_api_key: env.OPENAI_API_KEY
+google_api_key: env.GOOGLE_API_KEY
+# Nếu muốn dùng local LLM:
+# default_model: ollama/llama3
+```
+
+## 📦 Các khái niệm cốt lõi
+- **Agents**: Đóng vai trò là nhân sự thực thi. Có thể chạy qua Cloud API hoặc CLI nội bộ của bạn.
+- **Workflows**: Danh sách các `steps` chạy tuần tự. Mỗi step có thể uỷ quyền cho một `agent`, chạy một `tool`, hoặc chạy lệnh bash.
+- **Skills**: Nơi lưu các file `.md` chứa kiến thức, hướng dẫn mà bạn muốn nạp vào cho Agent.
+- **Validation Auto-Healing**: Nếu một bước validation thất bại, AI Frame sẽ đưa lỗi (stderr) vào context của Agent và bắt nó làm lại cho tới khi thành công.
+
+## Bản quyền
+MIT License