@mrtrinhvn/ag-kit 1.0.7 → 1.0.9

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/llm-routing-quirks/SKILL.md +41 -0
  2. package/.agent/skills/mini-antigravity-injection/SKILL.md +12 -10
  3. package/package.json +1 -1
  4. package/template/.agent/skills/llm-routing-quirks/SKILL.md +41 -0
  5. package/template/.agent/skills/mini-antigravity-injection/SKILL.md +12 -10
package/.agent/skills/llm-routing-quirks/SKILL.md ADDED
@@ -0,0 +1,41 @@
1
+ ---
2
+ description: "Kinh nghiệm xương máu khi định tuyến LLM: 9Router (Gemini) vs Ollama (Bartowski/Reasoning)"
3
+ skills: ["clean-code"]
4
+ ---
5
+
6
+ # LLM Routing Quirks (Kinh Nghiệm Phẫu Thuật Não LLM)
7
+
8
+ Tài liệu này lưu trữ những **chú ý sinh tử (quirks)** khi gọi các model LLM khác nhau trong kiến trúc Antigravity Orchestrator. Nó được đúc kết từ quá trình cày cuốc miệt mài vá lỗi của Quản Đốc AI và Sếp.
9
+
10
+ Nếu bạn đang viết Agent hoặc Script gọi LLM, **BẮT BUỘC ĐỌC** để tránh hệ thống bị đơ, văng lỗi JSON hoặc model bị "ngu" đi.
11
+
12
+ ---
13
+
14
+ ## 1. 9Router & Gemini (Cloud Models - API tương thích OpenAI)
15
+
16
+ **Mô hình áp dụng:** `ag/gemini-3-flash`, `ag/gemini-pro-1.5`, v.v.
17
+
18
+ ### Các Quy tắc Vàng:
19
+ 1. **JSON Format:** ĐƯỢC PHÉP (và nên) sử dụng `response_format: { type: 'json_object' }` để ép model trả về cục JSON chuẩn chỉ. Gemini xử lý JSON format tự nhiên rất tốt.
20
+ 2. **Stream Override (Lỗi SSE):** Mặc dù truyền `stream: false`, 9Router đôi khi BỊ LỖI và vẫn trả về luồng Server-Sent Events (SSE) (các dòng `data: {...}\n\ndata: [DONE]`).
21
+ 👉 **Cách Fix:** Code call API (`axios.post`) phải luôn chuẩn bị sẵn tinh thần parse cả 2 trường hợp: JSON Object bình thường VÀ Chuỗi SSE gộp lại. (Xem hàm `OrchestratorBrain.callAI`).
22
+ 3. **Timeout Threshold:** Bắt buộc đặt `timeout` cao (ví dụ: `120000ms` - 2 phút). Đừng set quá thấp (30s), vì proxy API Cloud thường xuyên bị trễ nhịp do routing.
23
+
24
+ ---
25
+
26
+ ## 2. Ollama & Bartowski (Local Reasoning Models - Chạy Offline)
27
+
28
+ **Mô hình áp dụng:** `hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M`, `DeepSeek-R1`, các model có thẻ `<think>`.
29
+
30
+ ### Các Quy tắc Vàng (SINH TỬ):
31
+ 1. **🔥 TUYỆT ĐỐI KHÔNG DÙNG TÍNH NĂNG ÉP JSON:** KHÔNG BAO GIỜ truyền `format: "json"` vào request của Ollama đối với các Reasoning Models!
32
+ - **Vì sao?** Các reasoning models cần viết tư duy vào thẻ `<think>...</think>` trước khi ra kết quả. Việc ép JSON sẽ làm hệ thống của Ollama cắt gọt thẻ suy nghĩ của nó, khiến model bị "ngăn não", sinh ra ảo giác (hallucination), trả về rác (token rác) hoặc phá hỏng format JSON cuối cùng.
33
+ 2. **Xử lý Thẻ `<think>` Thủ Công:** Khi model trả về chuỗi text, ta phải chủ động dùng Regex để bóc mảng `<think>...</think>` ra rồi mới quăng phần còn lại vào `JSON.parse()`.
34
+ - Code mài giũa: `str.replace(/<think>[\s\S]*?<\/think>/g, '').trim()`
35
+ 3. **Mở Hộp Sọ (Context Window - `num_ctx`):** Mặc định Ollama cấp `num_ctx` rất bé (2048 token) để tiết kiệm VRAM. Với các Task Orchestration quăng cả lịch sử chat và code, **BẮT BUỘC** phải truyền `"options": { "num_ctx": 4096 }` (hoặc 8192) vào `axios.post`. Nếu không, Ollama sẽ ngắt đuôi JSON làm sập hệ thống.
36
+ 4. **Tên Model Mặc Định:** Chú ý khi tải model HuggingFace từ Ollama (ví dụ `ollama run hf.co/bartowski/...`), Ollama sẽ giữ NGHIÊM NGẶT toàn bộ đường dẫn làm `ID Model`. Luôn truyền full tên vào trường `model` (ví dụ `model: "hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M"`).
37
+
38
+ ---
39
+
40
+ ## 3. Khuyến nghị Tự Chữa Lành (Mini-Antigravity Check)
41
+ Bất cứ khi nào gọi API nội bộ (để tự sửa mã) và nhận cảnh báo `SKIP Lỗi LLM` (tức 9Router bị câm), hệ thống không được gọi lại chính thằng sụp mạng, mà phải rẽ nhánh BẮN THẲNG LỆNH GỌI OLLAMA LOCALLY (tắt bypass Router) để bảo tồn mạng sống.
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.7",
3
+ "version": "1.0.9",
4
4
  "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
5
5
  "main": "index.js",
6
6
  "bin": {
package/template/.agent/skills/llm-routing-quirks/SKILL.md ADDED
@@ -0,0 +1,41 @@
1
+ ---
2
+ description: "Kinh nghiệm xương máu khi định tuyến LLM: 9Router (Gemini) vs Ollama (Bartowski/Reasoning)"
3
+ skills: ["clean-code"]
4
+ ---
5
+
6
+ # LLM Routing Quirks (Kinh Nghiệm Phẫu Thuật Não LLM)
7
+
8
+ Tài liệu này lưu trữ những **chú ý sinh tử (quirks)** khi gọi các model LLM khác nhau trong kiến trúc Antigravity Orchestrator. Nó được đúc kết từ quá trình cày cuốc miệt mài vá lỗi của Quản Đốc AI và Sếp.
9
+
10
+ Nếu bạn đang viết Agent hoặc Script gọi LLM, **BẮT BUỘC ĐỌC** để tránh hệ thống bị đơ, văng lỗi JSON hoặc model bị "ngu" đi.
11
+
12
+ ---
13
+
14
+ ## 1. 9Router & Gemini (Cloud Models - API tương thích OpenAI)
15
+
16
+ **Mô hình áp dụng:** `ag/gemini-3-flash`, `ag/gemini-pro-1.5`, v.v.
17
+
18
+ ### Các Quy tắc Vàng:
19
+ 1. **JSON Format:** ĐƯỢC PHÉP (và nên) sử dụng `response_format: { type: 'json_object' }` để ép model trả về cục JSON chuẩn chỉ. Gemini xử lý JSON format tự nhiên rất tốt.
20
+ 2. **Stream Override (Lỗi SSE):** Mặc dù truyền `stream: false`, 9Router đôi khi BỊ LỖI và vẫn trả về luồng Server-Sent Events (SSE) (các dòng `data: {...}\n\ndata: [DONE]`).
21
+ 👉 **Cách Fix:** Code call API (`axios.post`) phải luôn chuẩn bị sẵn tinh thần parse cả 2 trường hợp: JSON Object bình thường VÀ Chuỗi SSE gộp lại. (Xem hàm `OrchestratorBrain.callAI`).
22
+ 3. **Timeout Threshold:** Bắt buộc đặt `timeout` cao (ví dụ: `120000ms` - 2 phút). Đừng set quá thấp (30s), vì proxy API Cloud thường xuyên bị trễ nhịp do routing.
23
+
24
+ ---
25
+
26
+ ## 2. Ollama & Bartowski (Local Reasoning Models - Chạy Offline)
27
+
28
+ **Mô hình áp dụng:** `hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M`, `DeepSeek-R1`, các model có thẻ `<think>`.
29
+
30
+ ### Các Quy tắc Vàng (SINH TỬ):
31
+ 1. **🔥 TUYỆT ĐỐI KHÔNG DÙNG TÍNH NĂNG ÉP JSON:** KHÔNG BAO GIỜ truyền `format: "json"` vào request của Ollama đối với các Reasoning Models!
32
+ - **Vì sao?** Các reasoning models cần viết tư duy vào thẻ `<think>...</think>` trước khi ra kết quả. Việc ép JSON sẽ làm hệ thống của Ollama cắt gọt thẻ suy nghĩ của nó, khiến model bị "ngăn não", sinh ra ảo giác (hallucination), trả về rác (token rác) hoặc phá hỏng format JSON cuối cùng.
33
+ 2. **Xử lý Thẻ `<think>` Thủ Công:** Khi model trả về chuỗi text, ta phải chủ động dùng Regex để bóc mảng `<think>...</think>` ra rồi mới quăng phần còn lại vào `JSON.parse()`.
34
+ - Code mài giũa: `str.replace(/<think>[\s\S]*?<\/think>/g, '').trim()`
35
+ 3. **Mở Hộp Sọ (Context Window - `num_ctx`):** Mặc định Ollama cấp `num_ctx` rất bé (2048 token) để tiết kiệm VRAM. Với các Task Orchestration quăng cả lịch sử chat và code, **BẮT BUỘC** phải truyền `"options": { "num_ctx": 4096 }` (hoặc 8192) vào `axios.post`. Nếu không, Ollama sẽ ngắt đuôi JSON làm sập hệ thống.
36
+ 4. **Tên Model Mặc Định:** Chú ý khi tải model HuggingFace từ Ollama (ví dụ `ollama run hf.co/bartowski/...`), Ollama sẽ giữ NGHIÊM NGẶT toàn bộ đường dẫn làm `ID Model`. Luôn truyền full tên vào trường `model` (ví dụ `model: "hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M"`).
37
+
38
+ ---
39
+
40
+ ## 3. Khuyến nghị Tự Chữa Lành (Mini-Antigravity Check)
41
+ Bất cứ khi nào gọi API nội bộ (để tự sửa mã) và nhận cảnh báo `SKIP Lỗi LLM` (tức 9Router bị câm), hệ thống không được gọi lại chính thằng sụp mạng, mà phải rẽ nhánh BẮN THẲNG LỆNH GỌI OLLAMA LOCALLY (tắt bypass Router) để bảo tồn mạng sống.
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)