@mrtrinhvn/ag-kit 1.0.2 → 1.0.5

package/bin/cli.js

@@ -24,10 +24,11 @@ function copyRecursiveSync(src, dest) {
   }
 }
 
+const pkg = require('../package.json');
 program
   .name('ag-kit')
   .description('Trí khôn Lập trình Phổ quát - AI Agent Initialization Framework')
-  .version('1.0.0');
+  .version(pkg.version);
 
 program.command('init')
   .description('Install .agent folder into your project')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtrinhvn/ag-kit",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
   "main": "index.js",
   "bin": {

package/template/.agent/skills/cli-generator/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: cli-generator
+description: Meta-skill enabling the Agent to automatically convert local software, repositories, or APIs into structured CLI tools using HKUDS/CLI-Anything.
+---
+
+# CLI-Generator (Meta-Skill)
+
+> 🔴 **CRITICAL**: This is a Meta-Skill. It gives you (the AI Agent) the ability to forge your own tools to solve complex constraints.
+
+## When to Use
+
+Use this skill when:
+- The user asks you to interact with a complex local GUI software (e.g., GIMP, OBS).
+- You are working with a messy, undocumented local API or scripting repository that is too brittle to run manually via ad-hoc scripts.
+- You need a dedicated CLI tool to perform repetitive tasks reliably, but none exists.
+
+## The Forging Process
+
+When you decide you need a new CLI tool for a given `TARGET_DIR` (the source code of the application), follow exactly these steps:
+
+### 1. Install CLI-Anything (If not already installed)
+Check if `cli-anything` is available in your PATH. If not, install it globally:
+```bash
+pip install cli-anything
+```
+*(If the package is not on PyPI, clone `https://github.com/HKUDS/CLI-Anything` and run `pip install -e .`)*
+
+### 2. Run the Generator Pipeline
+Navigate to a neutral workspace or the target, and run the automated generation pipeline:
+```bash
+cli-anything --source /absolute/path/to/TARGET_DIR
+```
+*Note: This process analyzes the source code and generates the harness. It may take several minutes and uses the underlying LLM's API tokens.*
+
+### 3. Integrate the Forged Skill into `ag-kit`
+The pipeline will generate a new Python package (e.g., `cli-anything-targetname`) and automatically produce a `SKILL.md` file within its package directory (usually `cli_anything/<software>/skills/SKILL.md`).
+You MUST locate this generated `SKILL.md` and copy it into the user's `ag-kit` workspace:
+```bash
+mkdir -p .agent/skills/<targetname-cli>
+cp /path/to/generated/SKILL.md .agent/skills/<targetname-cli>/SKILL.md
+```
+
+### 4. Self-Update
+Once the new `SKILL.md` is in place, you (or any other agent using this repository like GravityClaw / Openclaw) will instantly possess the knowledge to use the newly forged CLI tool. Proceed to solve the user's original objective using the new tool natively.
+
+## Anti-Patterns
+- ❌ **Manual wrappers**: Do NOT try to manually write a CLI harness or wrappers if `cli-anything` can automate it perfectly.
+- ❌ **Token waste**: Do NOT run the generator repeatedly on the same source code. Generate the CLI once, store the `SKILL.md`, and reuse the tool.

package/template/.agent/skills/knowledge-management/SKILL.md

@@ -16,7 +16,7 @@ allowed-tools: Read, Write, Glob, Grep
 
 ### Mandatory Read Before Action
 Before interacting with any third-party API, database schema, or core system component, you **MUST** search the `.agent/knowledge/` directory for existing documentation. 
-*Example: Before coding a DNSE WebSocket feature, read `.agent/knowledge/integrations/dnse_api.md` to get the exact channels and payload structures.*
+*Example: Before coding a payment integration feature, read `.agent/knowledge/integrations/stripe_api.md` to get the exact webhooks and payload structures.*
 
 ### Mandatory Proactive Updates (Zero Prompting Rule)
 When you successfully:
@@ -60,7 +60,7 @@ When modifying a feature or fixing a bug, ask yourself:
 **PRINCIPLE:** Context should be scoped locally to reduce token bloat and prevent the AI from hallucinating across unrelated domains. Do not stuff all documentation into a monolithic global file.
 
 ### Sub-Directory Contexts
-When working within a specific module (e.g., `backend/app/services/` or `frontend/src/components/`), you should:
+When working within a specific module (e.g., `packages/core/services/` or `apps/web/components/`), you should:
 1. **Check for Local Context:** Look for a `CONTEXT.md` or `README.md` file *within that specific directory* before starting work.
-2. **Context Routing:** Leave pointers in central documentation (like `.agent/knowledge/architecture.md`) that route the AI to these deep local files. (e.g., `-> For trading engine logic, see backend/app/services/CONTEXT.md`).
+2. **Context Routing:** Leave pointers in central documentation (like `.agent/knowledge/architecture.md`) that route the AI to these deep local files. (e.g., `-> For payment processing logic, see packages/core/billing/CONTEXT.md`).
 3. **Local Updates:** When making fundamental changes to a localized component, create or update its local `CONTEXT.md` instead of polluting the global knowledge base. Keep local context files under 100 lines.

package/template/.agent/skills/memory-architecture/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: memory-architecture
+description: >
+  Hệ thống Bộ nhớ Đồ thị Đa Tầng (Multi-layered Graph Memory) cho Agent.
+  Hợp nhất giữa Progressive Disclosure (L1, L2, L3) và Temporal Knowledge Graph (Node-Edge).
+---
+
+# Multi-layered Graph Memory Architecture
+
+> 🔴 **CRITICAL RULE**: Trí nhớ của Agent không còn là Text phẳng. Nó là một **Đồ thị Tri thức Đa tầng (Graph)** cho phép "Zoom-out" nhìn toàn cảnh và "Zoom-in" đọc chi tiết lõi.
+
+---
+
+## 1. Nguyên tắc cốt lõi: 3 Tầng Ký ức (L1/L2/L3)
+
+```text
+L1 (Zoom Out) → session_summary & Core_Nodes  — "Toàn cảnh dự án, các khái niệm lõi"
+L2 (Mid)      → category-indexed & Edges      — "Mạng lưới quan hệ, mạch sự kiện"
+L3 (Zoom In)  → detail_record & Solutions     — "Chi tiết lỗi, code snippet gốc"
+```
+
+---
+
+## 2. Hình thái Dữ liệu cấp thấp (Node-Edge Graph)
+
+Mọi dữ liệu trong tầng L1/L2/L3 đều được lưu dưới dạng Đồ thị (Graph):
+
+### A. NODES (Hạt nhân Kiến thức)
+Các khái niệm định danh tĩnh. Vd: `[Node:DB_PORT] => 5432 (Energy: 100)`
+
+### B. EDGES / EPISODES (Mạch Câu chuyện)
+Luồng sự kiện liên kết. Vd: `[Node:USER] --(muốn mở port)--> [Node:DB_PORT]`
+
+### Progressive Disclosure (Tiết kiệm Token):
+Thay vì load toàn bộ Memory, hệ thống truy vấn tự động theo dạng Phóng to/Thu nhỏ:
+1. **Search (Zoom Out):** Chỉ lấy mỏ neo 1-2 Node lõi + Quan hệ (L1/L2) (Tốn rất ít token).
+2. **Details (Zoom In):** Nếu AI cần phân tích sâu 1 đoạn code phức tạp, gọi L3 (Token cao hơn nhưng cực kỳ chính xác).
+
+---
+
+## 3. Vòng đời Trí nhớ (Biocybernetic Lifecycle)
+
+1. **Temporal Decay (Phai mờ):** Mỗi Node và Edge có `Energy`. Bị hao hụt tự động mỗi 24h. L1 siêu bền, L3 hao nhanh.
+2. **Reinforcement (Củng cố):** Mỗi lần "bò" (traversal) qua Node, Energy phục hồi.
+3. **Consolidation (Ngủ):** Cứ đêm đến, AI gộp các mạch nhớ L3/L2 rườm rà thành 1 Node L1 khái quát siêu bền.
+4. **Forgetting (Quên lãng):** Node có `Energy < 0` HOẶC mồ côi (không ai gọi tới) sẽ BỊ XOÁ (Quét rác sinh học).
+
+---
+
+## 4. Bảng Phân loại Khối Lượng Ký ức
+
+| Target / Kiểu Node | Tầng | Giải thích | Energy Khởi tạo | Mức độ Tự Phân Hủy (Decay) |
+|---|---|---|---|---|
+| `session_summary` | L1 | Toàn cảnh phiên làm việc | 100 | Lâu dài (Gần như không) |
+| `Core_Fact` | L1 | Cấu hình, IP, Convention cốt lõi | 100 | Gần như không |
+| `User_Pref` | L2 | Thói quen user | 80 | Cực chậm |
+| `project_context` | L2 | Ngữ cảnh dự án hiện tại | 80 | Trung hạn (Cập nhật đổi version) |
+| `Episode_Edge` | L2 | "Hôm qua đã làm gì" | 30 | Nhanh (Rất mau phai mờ) |
+| `error_solution` | L3 | Bug log + Code fix cụ thể | 50 | Trung bình (Công nghệ đổi -> Xóa) |
+
+---
+
+## 5. Workflow Tương tác Trí Nhớ (Mô phỏng GraphRAG)
+
+### KHI BẮT ĐẦU task mới (Retrieve):
+```text
+1. Bắn 1 tia Vector Search thả mỏ neo vào Đồ thị (Tìm L1/L2).
+2. Khôi phục lại Mạch Câu Chuyện bằng cách "Bò" dọc theo Edges lân cận (BFS).
+3. Nếu cần code chính xác của 1 Bug, gọi lệnh lấy Detail (L3).
+```
+
+### KHI KẾT THÚC task (Commit):
+❌ **Sai:** Lưu text rác `memory_save("Fix xong bug X")` vào trong hư không.
+✅ **Đúng:** 
+```text
+1. Khởi tạo Node mới: Node[Fix_CORS] = "Thiếu accept headers"
+2. Nối Mạch: Node[Env_Prod] --(gặp lỗi)=> Node[Fix_CORS]
+3. (Tùy chọn) Gắn thêm Detail record vào L3 nếu fix cực phức tạp cần giữ code snippet.
+```
+
+---
+
+## 6. Anti-Patterns Kịch Độc
+
+```text
+❌ Gọi L3 load toàn bộ chi tiết khi không cần thiết (Tràn token).
+❌ Cố gắng chèn 200 dòng code vào Tên của Node (Node chỉ giữ Context lõi, Code đẩy xuống L3).
+❌ Tạo Node rác không gán Edge quan hệ. (Garbage Collector sẽ chém thẳng tay).
+```
+
+---
+
+## 7. Giao thức Tự động Dịch chuyển Ký ức (Self-Migration Protocol)
+
+> **Dành cho các AI Agent hoạt động trong dự án cũ (Legacy Projects) vừa được cập nhật `ag-kit` thông qua `npx`.**
+
+Khi bạn (AI) nhận thức được mình đang ở trong một dự án đã có sẵn dữ liệu ký ức cũ (chứa trong các file `.jsonl` hoặc `memory.db` phẳng), bạn **CÓ TRÁCH NHIỆM TỰ ĐỘNG** thực hiện quá trình "Memory Migration" (Dịch chuyển Ký ức) mà không cần User yêu cầu, theo các bước sau:
+
+1. **Phát hiện:** Dùng lệnh đọc file hoặc MCP để quét nội dung các ký ức cũ trong thư mục `data/memories/` (nếu có).
+2. **Băm nhỏ (Chunking & Entity Extraction):** Phân tích các đoạn log cũ xem chúng nói về chủ đề gì (vd: Lịch sử fix bug, Convention code cũ, Sở thích User).
+3. **Tái cấu trúc (Graph Construction):**
+   - Từ các đoạn text đó, rút trích ra các `Nodes` cốt lõi mang tính sự thật (Core Facts).
+   - Thiết lập các `Edges` (Mạch kết nối) mô tả luồng logic giữa các Nodes đó.
+4. **Lưu trữ (Commit):** Lưu bộ Graph vừa tạo vào cơ sở dữ liệu mới (thông qua `GraphMemoryTool` nếu dự án đã hỗ trợ, hoặc lưu ngược lại bằng `memory_save` dưới cấu trúc **Pseudo-Graph** cực đoan: `[Node:A] --[rel]--> [Node:B]` nếu nền tảng chưa được nâng cấp DB SQLite).
+
+Bằng giao thức này, kiến thức của dự án sẽ KHÔNG BAO GIỜ bị đứt gãy sau khi cập nhật kiến trúc. Mọi ký ức quá khứ sẽ tự động "tiến hóa" thành dạng Đồ thị tương lai!
+

package/template/.agent/skills/systematic-debugging/SKILL.md

@@ -114,7 +114,7 @@ When executing long chains of tool calls (especially when searching, indexing, o
 
 ❌ **Random changes** - "Maybe if I change this..."
 ❌ **Ignoring evidence** - "That can't be the cause"
-❌ **Assuming Data/API is dead** - Concluding an API endpoint is removed or data is unavailable just because a simple test failed (e.g., testing outside trading hours). ALWAYS check official documentation or sample SDK code before declaring an API dead.
+❌ **Assuming Data/API is dead** - Concluding an API endpoint is removed or data is unavailable just because a simple test failed (e.g., testing outside of service hours or without proper auth). ALWAYS check official documentation or sample SDK code before declaring an API dead.
 ❌ **Assuming** - "It must be X" without proof
 ❌ **Not reproducing first** - Fixing blindly
 ❌ **Stopping at symptoms** - Not finding root cause