@mrtrinhvn/ag-kit 1.0.10 → 1.0.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -46,6 +46,11 @@ Thay vì đoán mò Code trong 1 lần như trước đây (One-Shot), Lõi Bác
|
|
|
46
46
|
### 3. Giao Kèo Docstring Định Danh (Docstring Identity Pact)
|
|
47
47
|
- Ép Prompt của Bác Sĩ: Khai báo đa dòng ở đầu file Code mới: Sửa dòng nào? Tại sao sửa? Tuân thủ triết lý gì?
|
|
48
48
|
|
|
49
|
+
### 4. Khóa Máy Trạng Thái Cấp Phép & Tương Tác (Auth-First Interactive Gateway)
|
|
50
|
+
- **Quy tắc Vàng:** TUYỆT ĐỐI không mở toang cửa mổ xẻ Source Code trong các cuộc hội thoại thông thường. Mọi lệnh yêu cầu chữa mã nguồn (hoặc Lệnh Phá hủy Ký ức) bắt buộc phải đi qua 1 **Trạm Kiểm Duyệt Mật Khẩu** (Vd: `/heal`, `/healplan`, `/forget`).
|
|
51
|
+
- **Luồng Fast-Track (`/heal`):** Gõ lệnh -> Hỏi Pass -> Nhập Pass chuẩn -> Cấp Thẻ bài (`hasMutationLicense = true`), Bác sĩ tự mổ, tự test Sandbox, và vả Hot-Reload tự động.
|
|
52
|
+
- **Luồng Tương Tác Khám Bệnh (`/healplan`):** Gõ lệnh -> Hỏi Pass -> Nhập Pass chuẩn -> Bác Sĩ chỉ được lập Phác Đồ (`hasMutationLicense = false`) và ói ra 2 Nút bấm: `[✅ Proceed]` và `[❌ Cancel]`. User được quyền **Chat qua lại** ép Bác Sĩ đổi Phác Đồ nhiều lần đến khi ưng ý. Khi User bấm `Proceed`, Hệ thống bốc toàn bộ Context đắp cho Đại Đặc vụ để cấy ghép Code cuối cùng.
|
|
53
|
+
|
|
49
54
|
### 5. Nạp Nóng (Hot-Reload) & Sổ Ghi Chép Chung (Evolution Ledger)
|
|
50
55
|
- **Git Backup:** Ghi `.bak`, commit Git.
|
|
51
56
|
- **Hot-Reload:** Tự xoá cache (`require.cache` trong JS) nạp RAM trực tiếp.
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: telegram-agentic-gateway
|
|
3
|
+
description: Tiêu chuẩn Giao tiếp Telegram (Telegram Gateway) cho các Agentic Projects. Cung cấp bộ lệnh chuẩn mực (Core Commands) để Quản lý Agent, Quản lý Ký ức và Cấp phép Tự Chữa Lành (Self-Healing).
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# KỸ NĂNG: XÂY DỰNG TRẠM ĐIỀU HÀNH TELEGRAM (Telegram Agentic Gateway)
|
|
7
|
+
|
|
8
|
+
Khi User yêu cầu "Tạo kênh giao tiếp Telegram" hoặc "Làm cho dự án này điều khiển được qua Telegram giống Quản Đốc", bạn (AI) phải thiết kế một `TelegramGateway` tuân thủ nghiêm ngặt **Tiêu chuẩn Giao tiếp lõi** dưới đây.
|
|
9
|
+
|
|
10
|
+
Một Telegram Gateway chuẩn mực không chỉ là bot chat lăng nhăng, mà phải là một **Trạm Chỉ Huy (Command Center)** với các lệnh System-level.
|
|
11
|
+
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
## PHẦN A: BỘ LỆNH QUẢN TRỊ CƠ BẢN (Core Management Commands)
|
|
15
|
+
Bất kỳ dự án Agentic nào cũng phải có 4 lệnh sinh tồn sau:
|
|
16
|
+
|
|
17
|
+
1. **`🚀 /start` (Ping Khởi Động)**
|
|
18
|
+
- **Tác dụng:** Kiểm tra kết nối xem Lõi AI của dự án có đang thức không. Trả về thông số môi trường hiện tại (Vd: "Bot đang chạy Port 20130, kết nối 9Router ổn định").
|
|
19
|
+
|
|
20
|
+
2. **`📊 /status` (Camera Giám Sát)**
|
|
21
|
+
- **Tác dụng:** Liệt kê toàn bộ các Agent (Đặc vụ/Sandbox) ĐANG CHẠY NGẦM trong hệ thống.
|
|
22
|
+
- **Giao diện:** Phải trả về Inline Keyboard (Nút bấm) ứng với từng Sandbox để User có thể chọc vào xem Log hoặc Tương tác trực tiếp với Agent đó.
|
|
23
|
+
|
|
24
|
+
3. **`🏭 /spawn <mô_tả>` (Sinh Trực Tiếp Đặc Vụ)**
|
|
25
|
+
- **Tác dụng:** Ép hệ thống tách 1 luồng độc lập, đẻ ra 1 Sandbox riêng biệt đi làm cái task `<mô_tả>` ở background, không làm kẹt luồng chat hiện tại của User.
|
|
26
|
+
|
|
27
|
+
4. **`💀 /kill <agent_id>` (Kill-Switch Lệnh Bài Tử thần)**
|
|
28
|
+
- **Tác dụng:** Lệnh Tối Cao. Nếu một Sandbox chạy tốn token, bị kẹt (loop), hoặc làm sai định hướng, User gõ lệnh này Hệ thống BẮT BUỘC phải force-kill Process/Thread của Agent đó ngay lập tức để giải phóng RAM.
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
## PHẦN B: TRÍ NHỚ PHÂN NHIỆM (Topic-Based Memory Isolation)
|
|
33
|
+
Khác lập trình Bot thông thường chỉ lấy `chat.id`, một **Agentic Gateway** tiêu chuẩn BẮT BUỘC phải cô lập trí nhớ dựa trên Telegram Topics (Threads).
|
|
34
|
+
- Nếu User nhắn trong Group Telegram có tính năng Topics: Phải trích xuất `msg.message_thread_id` để làm định danh Ký ức (Vd: `topic-1234.json`).
|
|
35
|
+
- Nếu User nhắn Private: Dùng `chat.id` (Vd: `chat-5678.json`).
|
|
36
|
+
- Nhờ vậy, 1 Group Telegram có thể hoạt động hệt như 1 cái Trello/Kanban Board: Mỗi Topic là 1 Luồng Công Việc riêng biệt, Agent nhớ chính xác bối cảnh của từng file/lỗi đang thảo luận mà không bị chập cheng trí nhớ (Cross-Topic Hallucination).
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## PHẦN C: BỘ LỆNH QUẢN LÝ KÝ ỨC (Cognitive Management)
|
|
41
|
+
Mỗi Topic/Chat trên Telegram sẽ sinh ra 1 File Ký ức lưu Context. Bắt buộc phải có lệnh dọn dẹp cống rãnh:
|
|
42
|
+
|
|
43
|
+
5. **`🧹 /forget` (Hỏa Thiêu Hồ Sơ)**
|
|
44
|
+
- **Tác dụng:** Xóa vĩnh viễn File JSON lịch sử chat (Ký ức ngắn hạn) của Topic/Thread hiện tại.
|
|
45
|
+
- **CẢNH BÁO TỐI THƯỢNG:** Chỉ được phép xóa file JSON Session. TUYỆT ĐỐI KHÔNG ĐƯỢC thiết kế lệnh `/forget` gọi các hàm xóa Vector Database (Ký ức dài hạn dùng chung của dự án) vì sẽ làm toàn bộ Hệ thống Đại Tướng bị mất trí nhớ!
|
|
46
|
+
- **Bảo mật:** Vì lệnh này mang tính phá hủy dữ liệu, **BẮT BUỘC** phải chặn lại bằng Máy Trạng Thái Cấp Phép (Auth-First) yêu cầu nhập `Password` mới được thi hành.
|
|
47
|
+
|
|
48
|
+
---
|
|
49
|
+
|
|
50
|
+
## PHẦN D: BỘ LỆNH TIẾN HÓA VÀ CHỮA LÀNH (Self-Healing Mappers)
|
|
51
|
+
Để Dự án có thể tự vá lỗi source code của nó (cần kết hợp với skill `mini-antigravity-injection`), Telegram Gateway phải chứa 2 lệnh Cấp Phép Mổ:
|
|
52
|
+
|
|
53
|
+
6. **`🏥 /heal <triệu_chứng>` (Tiền Trảm Hậu Tấu)**
|
|
54
|
+
- **Tác dụng:** Bypass bước duyệt phác đồ.
|
|
55
|
+
- **Luồng hoạt động:** Nhận lệnh -> Trạng thái chờ Pass -> Nhập Pass đúng -> Cấp quyền (`hasMutationLicense = true`) -> Agent tự tìm Lỗi -> Tự Mổ code -> Tự Test Sandbox -> Tự Hot-reload -> Báo kết quả cuối cùng.
|
|
56
|
+
|
|
57
|
+
7. **`📋 /healplan <triệu_chứng>` (Khám Bệnh Kê Đơn - Tương Tác)**
|
|
58
|
+
- **Tác dụng:** Lập phác đồ, cấm chạm vào code thật.
|
|
59
|
+
- **Luồng hoạt động:** Nhận lệnh -> Trạng thái chờ Pass -> Nhập Pass đúng -> Agent đi khám bệnh -> Nhả ra Phác Đồ + 2 Nút Bấm `[✅ Proceed]` và `[❌ Cancel]`.
|
|
60
|
+
- User có thể chat qua lại để sửa bản Phác đồ ròng rã cả ngày. Lúc nào ưng ý bấm `Proceed`, Hệ thống bốc Context lôi Agent ra chém đè Code!
|
|
61
|
+
|
|
62
|
+
---
|
|
63
|
+
|
|
64
|
+
## PHẦN E: KIẾN TẠO HẠ TẦNG & HƯỚNG DẪN ÔNG CHỦ (User Setup Instructions)
|
|
65
|
+
Khi bạn (AI) code xong cái `TelegramGateway` cho dự án, nghĩa vụ của bạn CƯƠNG QUYẾT phải xuất ra một bảng hướng dẫn `Markdown` dặn dò Ông Chủ (User) cách thiết lập Telegram để chọn 1 trong 2 chế độ chơi:
|
|
66
|
+
|
|
67
|
+
1. **Chế Độ Bệnh Viện Đa Khoa (Group Multi-Topics - Khuyên dùng):**
|
|
68
|
+
- Hướng dẫn User tạo 1 Group Telegram mới.
|
|
69
|
+
- Thêm con Bot vào Group và cấp quyền Admin.
|
|
70
|
+
- **ĐẶC BIỆT QUAN TRỌNG:** Nhắc User phải vào Cài đặt Group (Group Settings) -> Bật tính năng **"Topics"** (Diễn đàn).
|
|
71
|
+
- Giải thích cho User: Mỗi khi có 1 "Bệnh nhân" (Lỗi/Tính năng mới), User tạo một cái Topic mới trong Group đó. Bot sẽ phân luồng Ký ức cực mượt theo từng Topic.
|
|
72
|
+
|
|
73
|
+
2. **Chế Độ Phòng Khám Tư (Private Single Chat):**
|
|
74
|
+
- Hướng dẫn User chỉ cần nhấp vào Bot và nhắn tin trực tiếp (DM).
|
|
75
|
+
- Nhắc User dùng lệnh `/forget` nếu muốn đổi chủ đề để tránh Bot bị chập Ký ức.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
## TỔNG KẾT TRIỂN KHAI
|
|
80
|
+
*(Ghi chú cho AI)*: Khi code Node.js/Python cho bot, bạn TỰ ĐỘNG đăng ký toàn bộ 7 lệnh này vào Bot Menu (`bot.setMyCommands(...)` trong Telegram API) để User chỉ việc gõ dấu `/` là Menu gợi ý hiện ra đầy đủ và chuyên nghiệp!
|