@mrtrinhvn/ag-kit 1.0.8 → 1.0.10

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.
Files changed (5) hide show
  1. package/.agent/skills/cognitive-session/SKILL.md +28 -0
  2. package/.agent/skills/mini-antigravity-injection/SKILL.md +12 -10
  3. package/package.json +1 -1
  4. package/template/.agent/skills/cognitive-session/SKILL.md +28 -0
  5. package/template/.agent/skills/mini-antigravity-injection/SKILL.md +12 -10
package/.agent/skills/cognitive-session/SKILL.md ADDED
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: "Cognitive Session Manager"
3
+ description: "Kiến trúc Quản lý Trí nhớ Phân Nhiệm (Topic-based Memory) và Rọn Rác Ký Ức (Garbage Collection) cho các Hàng đợi Tác vụ."
4
+ ---
5
+
6
+ # THE COGNITIVE SESSION MANAGER: THIẾT KẾ BỘ NHỚ THEO PHIÊN
7
+
8
+ Toàn bộ các Lõi LLM-Agents (Orchestrator hoặc Sub-Agents Doctor) tuyệt đối không được dùng chung một mảng `ChatHistory` tĩnh nằm trên RAM. Đây là hành vi chống mô-đun (anti-pattern) sẽ dẫn đến rò rỉ trí nhớ và nhầm lẫn bối cảnh.
9
+
10
+ Bạn **BẮT BUỘC** phải tuân thủ Kiến trúc Ký Ức Phân Hạch (Fission Memory) sau đây:
11
+
12
+ ## 1. File-Based Isolation (Nguyên lý Thùng Chứa Độc Lập)
13
+ Bất cứ khi nào Agent nhận được một luồng chat mới hoặc một sự cố mới (Crash), hãy gán cho nó một ID duy nhất:
14
+ - Tương tác với Khách hàng: `topic-<threadId>` hoặc `chat-<userId>`
15
+ - Tương tác nội bộ (Doctor Box): `doc-heal-<target>-<timestamp>`
16
+
17
+ Tất cả Lịch sử Suy nghĩ (Thoughts), Tool Calls, và Lỗi của Session đó phải lưu xuống Ổ cứng (Ví dụ: `.data/sessions/topic-123.json`) thông qua `SessionManager.ts`.
18
+
19
+ ## 2. Ephemeral Injection (Giới Hạn Tầm Nhìn)
20
+ Mỗi lần khởi tạo LLM Prompt, chỉ được phép nạp **6 đến 10 tin nhắn gần nhất** từ File JSON của Session đó vào `ContextWindow` làm Working Memory. Nếu nạp quá nhiều, LLM (đặc biệt là model local như Nvidia/Groq) sẽ bị đuối Token và sinh ra ảo giác.
21
+
22
+ ## 3. Lệnh Tử Hình Ký Ức (Garbage Collection)
23
+ Ký ức của Session là rác sau khi tác vụ hoàn thành. Khi hệ thống nhận lệnh `/close`, `/end`, `/forget` từ User, hoặc khi Bác Sĩ Sub-Agent chạy pass xong Unit Test:
24
+ - Hệ thống phải gọi hàm `SessionManager.destroySession(sessionId)` nhằm dùng hàm `fs.unlink()` Xóa Vĩnh Viễn file JSON của Session đó khỏi ổ đĩa.
25
+ - Hành động này giữ cho dự án siêu nhẹ nhàng vĩnh viễn, giải phóng mặt bằng cho các Topic khác.
26
+
27
+ ## Tóm gọn Nguyên tắc
28
+ "Cấp ID -> Ghi vào Ổ Cứng -> Giới hạn RAM lúc Suy Nghĩ -> Hoàn tất -> Đốt sạch Hồ sơ."
package/.agent/skills/mini-antigravity-injection/SKILL.md CHANGED
@@ -32,16 +32,18 @@ Khi bạn (AI) tự động tạo code `SelfHealingService` cho dự án mới,
32
32
  ### 1. Cơ Chế Bơm Kiến Thức Vĩ Mô (Skill & DNA Injection)
33
33
  - Code tự động đọc các file nguyên tắc lập trình của dự án (`.agent/GEMINI.md`, `clean-code/SKILL.md`...) và TIÊM vào System Prompt của LLM Bác Sĩ Cục Bộ. Đảm bảo nó code đúng văn phong của Antigravity.
34
34
 
35
- ### 2. Định Luật Cạn Kiệt Gen (Exhaustion Trigger)
36
- - Hệ thống bắt Stack Trace. Nếu lỗi Tool/Code gãy 3 lần (Vòng lặp bất tận) -> Kích Hoạt Tiểu-Antigravity chữa cháy tự động.
37
-
38
- ### 3. Hộp Cát Tử Thần (Sandbox) & Lá Chắn Ngữ Nghĩa (Semantic Shield)
39
- Tuyệt đối KHÔNG đẩy code vừa sinh thẳng vào Môi trường Thực Chiến.
40
- - **Phase 1 (Doctor):** Dùng prompt áp dụng `5-Whys` tìm Root Cause và viết mới lại file Code.
41
- - **Phase 2 (Syntax Test):** Build/Compile Dry-run qua trình biên dịch (VD: `tsc --noEmit`).
42
- - **Phase 3 (Semantic Shield):** Cốt lõi của sự Khôn ngoan! Hệ thống tự rà file Unit Test đi kèm (`*.spec.ts` hoặc `*.test.ts`). Chạy **Test Ngữ Nghĩa (Logic)** với file mới. Nếu Logic tính toán sai (dù cú pháp đúng) -> Đánh sập nhánh đó, cấm Hot-Reload.
43
-
44
- ### 4. Giao Kèo Docstring Định Danh (Docstring Identity Pact)
35
+ ## 2. Lõi Đột Biến Cấp Khẩn Cơ Sở (Agentic Healing Sandbox)
36
+
37
+ Thay vì đoán mò Code trong 1 lần như trước đây (One-Shot), Lõi Bác Sĩ giờ đây được tiến hóa thành **Sub-Agentic Healing**:
38
+ 1. **Meta-Sandbox (Chroot):** Copy file bị lỗi ra `/tmp/ag-workspace-${doctorId}/` để cách ly hoàn toàn với source code.
39
+ 2. **Triệu hồi Sub-Agent:** Gọi ngược `AgentRuntime.execute()` cấp cho Bác sĩ các quyền (Bash, Read/Write file). Bác sĩ sẽ tự đi vòng quanh ổ cứng, tự dịch TypeScript (`npx tsc`) để test lỗi cho đến khi Pass 100%.
40
+ 3. **3 Khóa Đỏ Chế Ngự (Red Locks):**
41
+ - **Chống Đệ Quy (Depth Limit):** Bác sĩ không được cấp quyền gọi lệnh vá lỗi để đẻ ra Bác sĩ khác.
42
+ - **Kill-Switch:** Nếu Bác sĩ ảo giác (ngáo) gõ lặp lại 1 lệnh lỗi 2 lần, tự động Force Kill và Rollback.
43
+ - **Giới hạn lặp:** Bác sĩ chỉ có 10 vòng lặp (10 attempts) để cứu bệnh nhân.
44
+ 4. **Semantic Shield:** Sau khi Bác Sĩ báo cáo "Finish", luồng gốc mới chạy `Unit Test` trên file Sandbox đó. Vượt qua Unit Test mới được phép Hot-Reload đè vào Source Code chính!
45
+
46
+ ### 3. Giao Kèo Docstring Định Danh (Docstring Identity Pact)
45
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ì?
46
48
 
47
49
  ### 5. Nạp Nóng (Hot-Reload) & Sổ Ghi Chép Chung (Evolution Ledger)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mrtrinhvn/ag-kit",
3
- "version": "1.0.8",
3
+ "version": "1.0.10",
4
4
  "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
5
5
  "main": "index.js",
6
6
  "bin": {
package/template/.agent/skills/cognitive-session/SKILL.md ADDED
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: "Cognitive Session Manager"
3
+ description: "Kiến trúc Quản lý Trí nhớ Phân Nhiệm (Topic-based Memory) và Rọn Rác Ký Ức (Garbage Collection) cho các Hàng đợi Tác vụ."
4
+ ---
5
+
6
+ # THE COGNITIVE SESSION MANAGER: THIẾT KẾ BỘ NHỚ THEO PHIÊN
7
+
8
+ Toàn bộ các Lõi LLM-Agents (Orchestrator hoặc Sub-Agents Doctor) tuyệt đối không được dùng chung một mảng `ChatHistory` tĩnh nằm trên RAM. Đây là hành vi chống mô-đun (anti-pattern) sẽ dẫn đến rò rỉ trí nhớ và nhầm lẫn bối cảnh.
9
+
10
+ Bạn **BẮT BUỘC** phải tuân thủ Kiến trúc Ký Ức Phân Hạch (Fission Memory) sau đây:
11
+
12
+ ## 1. File-Based Isolation (Nguyên lý Thùng Chứa Độc Lập)
13
+ Bất cứ khi nào Agent nhận được một luồng chat mới hoặc một sự cố mới (Crash), hãy gán cho nó một ID duy nhất:
14
+ - Tương tác với Khách hàng: `topic-<threadId>` hoặc `chat-<userId>`
15
+ - Tương tác nội bộ (Doctor Box): `doc-heal-<target>-<timestamp>`
16
+
17
+ Tất cả Lịch sử Suy nghĩ (Thoughts), Tool Calls, và Lỗi của Session đó phải lưu xuống Ổ cứng (Ví dụ: `.data/sessions/topic-123.json`) thông qua `SessionManager.ts`.
18
+
19
+ ## 2. Ephemeral Injection (Giới Hạn Tầm Nhìn)
20
+ Mỗi lần khởi tạo LLM Prompt, chỉ được phép nạp **6 đến 10 tin nhắn gần nhất** từ File JSON của Session đó vào `ContextWindow` làm Working Memory. Nếu nạp quá nhiều, LLM (đặc biệt là model local như Nvidia/Groq) sẽ bị đuối Token và sinh ra ảo giác.
21
+
22
+ ## 3. Lệnh Tử Hình Ký Ức (Garbage Collection)
23
+ Ký ức của Session là rác sau khi tác vụ hoàn thành. Khi hệ thống nhận lệnh `/close`, `/end`, `/forget` từ User, hoặc khi Bác Sĩ Sub-Agent chạy pass xong Unit Test:
24
+ - Hệ thống phải gọi hàm `SessionManager.destroySession(sessionId)` nhằm dùng hàm `fs.unlink()` Xóa Vĩnh Viễn file JSON của Session đó khỏi ổ đĩa.
25
+ - Hành động này giữ cho dự án siêu nhẹ nhàng vĩnh viễn, giải phóng mặt bằng cho các Topic khác.
26
+
27
+ ## Tóm gọn Nguyên tắc
28
+ "Cấp ID -> Ghi vào Ổ Cứng -> Giới hạn RAM lúc Suy Nghĩ -> Hoàn tất -> Đốt sạch Hồ sơ."
package/template/.agent/skills/mini-antigravity-injection/SKILL.md CHANGED
@@ -32,16 +32,18 @@ Khi bạn (AI) tự động tạo code `SelfHealingService` cho dự án mới,
32
32
  ### 1. Cơ Chế Bơm Kiến Thức Vĩ Mô (Skill & DNA Injection)
33
33
  - Code tự động đọc các file nguyên tắc lập trình của dự án (`.agent/GEMINI.md`, `clean-code/SKILL.md`...) và TIÊM vào System Prompt của LLM Bác Sĩ Cục Bộ. Đảm bảo nó code đúng văn phong của Antigravity.
34
34
 
35
- ### 2. Định Luật Cạn Kiệt Gen (Exhaustion Trigger)
36
- - Hệ thống bắt Stack Trace. Nếu lỗi Tool/Code gãy 3 lần (Vòng lặp bất tận) -> Kích Hoạt Tiểu-Antigravity chữa cháy tự động.
37
-
38
- ### 3. Hộp Cát Tử Thần (Sandbox) & Lá Chắn Ngữ Nghĩa (Semantic Shield)
39
- Tuyệt đối KHÔNG đẩy code vừa sinh thẳng vào Môi trường Thực Chiến.
40
- - **Phase 1 (Doctor):** Dùng prompt áp dụng `5-Whys` tìm Root Cause và viết mới lại file Code.
41
- - **Phase 2 (Syntax Test):** Build/Compile Dry-run qua trình biên dịch (VD: `tsc --noEmit`).
42
- - **Phase 3 (Semantic Shield):** Cốt lõi của sự Khôn ngoan! Hệ thống tự rà file Unit Test đi kèm (`*.spec.ts` hoặc `*.test.ts`). Chạy **Test Ngữ Nghĩa (Logic)** với file mới. Nếu Logic tính toán sai (dù cú pháp đúng) -> Đánh sập nhánh đó, cấm Hot-Reload.
43
-
44
- ### 4. Giao Kèo Docstring Định Danh (Docstring Identity Pact)
35
+ ## 2. Lõi Đột Biến Cấp Khẩn Cơ Sở (Agentic Healing Sandbox)
36
+
37
+ Thay vì đoán mò Code trong 1 lần như trước đây (One-Shot), Lõi Bác Sĩ giờ đây được tiến hóa thành **Sub-Agentic Healing**:
38
+ 1. **Meta-Sandbox (Chroot):** Copy file bị lỗi ra `/tmp/ag-workspace-${doctorId}/` để cách ly hoàn toàn với source code.
39
+ 2. **Triệu hồi Sub-Agent:** Gọi ngược `AgentRuntime.execute()` cấp cho Bác sĩ các quyền (Bash, Read/Write file). Bác sĩ sẽ tự đi vòng quanh ổ cứng, tự dịch TypeScript (`npx tsc`) để test lỗi cho đến khi Pass 100%.
40
+ 3. **3 Khóa Đỏ Chế Ngự (Red Locks):**
41
+ - **Chống Đệ Quy (Depth Limit):** Bác sĩ không được cấp quyền gọi lệnh vá lỗi để đẻ ra Bác sĩ khác.
42
+ - **Kill-Switch:** Nếu Bác sĩ ảo giác (ngáo) gõ lặp lại 1 lệnh lỗi 2 lần, tự động Force Kill và Rollback.
43
+ - **Giới hạn lặp:** Bác sĩ chỉ có 10 vòng lặp (10 attempts) để cứu bệnh nhân.
44
+ 4. **Semantic Shield:** Sau khi Bác Sĩ báo cáo "Finish", luồng gốc mới chạy `Unit Test` trên file Sandbox đó. Vượt qua Unit Test mới được phép Hot-Reload đè vào Source Code chính!
45
+
46
+ ### 3. Giao Kèo Docstring Định Danh (Docstring Identity Pact)
45
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ì?
46
48
 
47
49
  ### 5. Nạp Nóng (Hot-Reload) & Sổ Ghi Chép Chung (Evolution Ledger)