CookieGli

CookieGli

Bộ công cụ nén ngữ cảnh kiến trúc, chỉ mục mã nguồn và phân tích tác động thay đổi Thuần Python stdlib • Không thư viện phụ thuộc ngoài • Chạy ổn định trên Windows, Linux, macOS

---

Mục Lục

• [1. Giới Thiệu & Vấn Đề Giải Quyết](#1-giới-thiệu--vấn-đề-giải-quyết)
• [2. Kiến Trúc Hoạt Động](#2-kiến-trúc-hoạt-động)
• [3. Các Tính Năng Cốt Lõi](#3-các-tính-năng-cốt-lõi)
• [3.1. Semantic Code Skeletonizer & Focus-Symbol Mode](#31-semantic-code-skeletonizer--focus-symbol-mode)
• [3.2. Chỉ Mục Biểu Tượng B-Tree & Toàn Văn SQLite FTS5 BM25+](#32-chỉ-mục-biểu-tượng-b-tree--toàn-văn-sqlite-fts5-bm25)
• [3.3. Động Cơ Ngữ Cảnh Hai Tầng (Two-Tier Boost Engine) & Hiệu Chuẩn Suy Luận 2026](#33-động-cơ-ngữ-cảnh-hai-tầng-two-tier-boost-engine--hiệu-chuẩn-suy-luận-2026)
• [3.4. Phân Tích Lan Truyền Thay Đổi (Git Blast Radius & Test Targeting)](#34-phân-tích-lan-truyền-thay-đổi-git-blast-radius--test-targeting)
• [3.5. Chưng Cất Lỗi Tự Động (Autonomous Error & Traceback Distiller)](#35-chưng-cất-lỗi-tự-động-autonomous-error--traceback-distiller)
• [3.6. Bản Đồ Kiến Trúc Dự Án (Project AST Genome) & Chuẩn Hóa Token-0](#36-bản-đồ-kiến-trúc-dự-án-project-ast-genome--chuẩn-hóa-token-0)
• [3.7. Hỗ Trợ Dự Án Monorepo Phân Cấp](#37-hỗ-trợ-dự-án-monorepo-phân-cấp)
• [3.8. Bộ Nhớ Kinh Nghiệm Thích Ứng (Darwin Memory Pool)](#38-bộ-nhớ-kinh-nghiệm-thích-ứng-darwin-memory-pool)
• [3.9. Khung Học Hỏi Thích Ứng & Căn Chỉnh Ý Định (Continuous Evolution Harness & Developer Alignment)](#39-khung-học-hỏi-thích-ứng--căn-chỉnh-ý-định-continuous-evolution-harness--developer-alignment)
• [4. Số Liệu Kiểm Định Thực Nghiệm](#4-số-liệu-kiểm-định-thực-nghiệm)
• [5. Cài Đặt & Bắt Đầu Nhanh](#5-cài-đặt--bắt-đầu-nhanh)
• [6. Tra Cứu Lệnh CLI](#6-tra-cứu-lệnh-cli)
• [7. Cấu Hình MCP Server (Model Context Protocol)](#7-cấu-hình-mcp-server-model-context-protocol)
• [8. Kiểm Thử & Đảm Bảo Chất Lượng](#8-kiểm-thử--đảm-bảo-chất-lượng)
• [9. Giấy Phép](#9-giấy-phép)

---

1. Giới Thiệu & Vấn Đề Giải Quyết

Khi làm việc trong các dự án phần mềm có quy mô vừa và lớn, việc duyệt và thao tác mã nguồn thường gặp phải các giới hạn kỹ thuật:

• Quá tải kích thước ngữ cảnh (Context Bloat): Đọc toàn bộ các file mã nguồn thô tiêu tốn hàng chục ngàn token cho mỗi lượt xử lý, gây lãng phí băng thông, tăng độ trễ và làm loãng thông tin quan trọng.
• Tra cứu biểu tượng tốn kém: Sử dụng regex grep trên toàn bộ cây thư mục tốn nhiều tài nguyên đĩa và dễ trả về kết quả nhiễu khi dự án phình to.
• Khó xác định phạm vi ảnh hưởng khi sửa code: Khi thay đổi một module, rất khó biết chính xác những thành phần nào phụ thuộc vào nó và cần chạy những bài test nào, dẫn đến việc phải chạy lại toàn bộ test suite lớn và sinh ra log thừa thãi.
• Mất dấu kinh nghiệm xử lý lỗi: Các giải pháp khắc phục sự cố, sửa lỗi cú pháp hay quy tắc dự án sau khi hoàn thành thường bị phân tán, không được lưu trữ có cấu trúc để tái sử dụng.

CookieGli là bộ công cụ dòng lệnh và giao thức MCP gọn nhẹ, tập trung vào:

1. Rút gọn mã nguồn giữ cấu trúc (Skeletonization): Giữ nguyên khai báo class, interface, method signatures, decorators, type annotations và gấp gọn phần thân logic giúp giảm 75% đến 92% dung lượng văn bản.
2. Chỉ mục B-Tree tra cứu nhanh: Lưu trữ vị trí symbol, chữ ký hàm, docstring trong SQLite WAL với độ trễ tìm kiếm dưới 0.1ms.
3. Phân tích tác động đồ thị ngược (Blast Radius): Dự đoán chính xác các file bị ảnh hưởng khi có git diff và chỉ điểm đúng test suite tối thiểu cần chạy.
4. Tự động trích xuất bài học từ traceback: Phân tích stack trace từ Python, Node/Jest, Go, Rust và diff sửa lỗi thành quy tắc thực chiến có đánh số điểm tin cậy Bayesian.
5. Khung học hỏi thích ứng & căn chỉnh ý định (Continuous Evolution Harness): Càng làm việc, Agent càng hiểu thói quen của developer, tự động học phong cách code và anti-pattern qua phản hồi tự nhiên (Anh/Việt), đo lường chỉ số Bayesian Alignment IQ và tự động hiệu chuẩn hành vi theo 4 giai đoạn trưởng thành của dự án.
6. Thuần Python chuẩn (Zero Dependencies): Chạy trực tiếp từ Python 3.9+ mà không cần cài đặt thêm thư viện bên ngoài qua pip.

---

2. Kiến Trúc Hoạt Động

               Mã nguồn dự án (Python, TS/JS, Go, Rust, Java, C#, C++)
                                      │
                                      ▼
                        ┌───────────────────────────┐
                        │   AstScanner (AST + Regex) │
                        └─────────────┬─────────────┘
                                      │
                ┌─────────────────────┼─────────────────────┐
                │                     │                     │
                ▼                     ▼                     ▼
     ┌─────────────────────┐┌───────────────────┐┌─────────────────────┐
     │ Inverted Symbol     ││ Code Skeletonizer ││ Git Blast Radius    │
     │ Index (SQLite BTree)││ & Focus-Symbol    ││ (Ingress Dependency)│
     │ Latency  rút gọn 1 dòng -> loại bỏ docstring hàm phụ -> gộp phương thức nội bộ) để đảm bảo không vượt quá ngân sách token quy định.

### 3.2. Chỉ Mục Biểu Tượng B-Tree & Toàn Văn SQLite FTS5 BM25+
* **B-Tree Index ( Kích hoạt **100% Prefix Cache Read Discount** (giảm 90% chi phí trên GPT-6 Astra, GPT-5.6 Sol, Claude Opus 5, Gemini 3.7 Flash, Kimi K3, DeepSeek-V4).
* **Layer 2: Dynamic Task Tail (`), kết hợp BM25 symbol matching + Code Skeletonizer giữ verbatim hàm focus + Blast Radius test targeting. Tự động cân bằng code fences markdown khi cắt tỉa.
* **Hiệu chuẩn suy luận 2026 (Reasoning Calibration):** Tự động điều chỉnh `effort=low/medium/high` theo `blast_depth` để tiết kiệm token suy luận đắt đỏ ($15–$50/M) của các frontier models.

### 3.4. Phân Tích Lan Truyền Thay Đổi (Git Blast Radius & Test Targeting)
* **Đảo ngược đồ thị phụ thuộc (Forward-to-Ingress):** Xây dựng danh sách các file trực tiếp và gián tiếp phụ thuộc vào một module hoặc symbol bất kỳ.
* **Tự động nhận diện thay đổi:** Đọc trạng thái sửa đổi thông qua `git status --porcelain` an toàn hoặc tự động đối chiếu `mtime` trên cache SQLite khi không có môi trường Git.
* **Khoanh vùng kiểm thử chính xác (Surgical Test Targeting):** Ánh xạ từ các module bị thay đổi sang đúng các file test tương ứng, tự động đề xuất câu lệnh chạy kiểm thử tối thiểu thay vì chạy toàn bộ test suite, giảm đến 80% dung lượng log kiểm thử thừa.

### 3.5. Chưng Cất Lỗi Tự Động (Autonomous Error & Traceback Distiller)
* **Bộ bóc tách traceback 3 tầng:** Nhận diện và trích xuất khung lỗi từ Python (`unittest`, `pytest`, `Traceback`), Node.js/Jest stack traces, cũng như Go/Rust panics.
* **Nhận diện mẫu sửa lỗi:** Phân tích git diff hoặc mô tả sửa lỗi (như bổ sung kiểm tra None/Null, fallback mặc định, chuẩn hóa đường dẫn, kiểm tra biên mảng).
* **Tự động tạo quy tắc và lưu trữ:** Tổng hợp thành quy tắc bài học Darwin có gắn nhãn phạm vi (`core.cache`, `git.blast`, `engine.ast`...), tính điểm tin cậy ban đầu qua công thức Laplace Smoothing và hỗ trợ khôi phục tự động các quy tắc cũ nếu lỗi tái diễn.

### 3.6. Bản Đồ Kiến Trúc Dự Án (Project AST Genome) & Chuẩn Hóa Token-0
* Tạo bản tóm tắt cấu trúc toàn dự án chỉ trong phạm vi dưới 600 tokens.
* Chuẩn hóa bất biến Token 0: loại bỏ timestamp động, bảo toàn byte-stability để duy trì tỷ lệ cache hit cao nhất.
* Bao gồm: kiến trúc công nghệ, điểm vào (entry points), ma trận phụ thuộc, các class/hàm trung tâm và hotspot kiến trúc.

### 3.7. Hỗ Trợ Dự Án Monorepo Phân Cấp
* **Tier-1 Root Cluster Map (= 3.9 (kiểm thử từ Python 3.9 đến 3.14).
* Hoàn toàn không cần cài đặt thêm thư viện qua pip.

### Tải dự án
```bash
git clone https://github.com/LoveCookieee-java/CookieGli.git
cd CookieGli

Các ví dụ sử dụng cơ bản

1. Khởi tạo một lệnh duy nhất (One-Command Bootstrap):

# Quét mã nguồn, nạp SQLite B-Tree & FTS5 BM25 index, và đồng bộ Layer 1 tĩnh:
python cli/cookiegli.py boost --init

**2. Sinh lát cắt ngữ cảnh động cho tác vụ lập trình ( [--focus SYM] [--max-tokens N] [--json] | Nén cấu trúc file mã nguồn hoặc tập trung vào một symbol. | | symbol | symbol [query] [--type TYPE] [--exact] [--limit N] [--json] | Tra cứu vị trí, chữ ký và tài liệu của biểu tượng từ B-Tree index. | | blast | blast [--diff] [--file FILE] [--symbol SYM] [--max-depth N] [--json] | Phân tích danh sách file phụ thuộc và khoanh vùng kiểm thử cần chạy. | | distill | distill [--traceback STR] [--file FILE] [--diff DIFF] [--fix FIX] [--auto-register] [--sync] | Bóc tách traceback, tổng hợp bài học và tự động lưu trữ kinh nghiệm. | | genome | genome build [path] [--max-tokens N] [--save PATH] | Quét mã nguồn và xuất bản đồ kiến trúc dự án tổng quát ( [--limit N] | Tra cứu toàn văn BM25+ chuẩn công nghiệp trên SQLite FTS5 (<0.5ms). | | harness | harness status / feedback / eval / history | Quản lý độ trưởng thành (Project Maturity), học phản hồi tự nhiên (Anh/Việt) và đo Bayesian Alignment IQ. | | sync | sync [--target TARGET] [--root PATH] | Đồng bộ vào claude, codex, antigravity, cursor, windsurf hoặc all. | | mcp | mcp [--profile standard\|full] [--name NAME] [--root PATH] | Khởi chạy máy chủ MCP qua giao thức STDIO JSON-RPC 2.0 (mặc định profile: full - CookieGli_Full). |

---

7. Cấu Hình MCP Server: CookieGli_Full (All-in-One Architecture)

CookieGli cung cấp kiến trúc MCP hợp nhất CookieGli_Full với hệ thống gắn nhãn phân loại danh mục (Domain Category Namespacing) và tài nguyên hướng dẫn mcp://cookiegli/guide nhằm giúp các AI Agent (GPT-6 Astra, Claude Opus 5, Gemini 3.8 Flash, Kimi K3, DeepSeek-V4) phân biệt và kích hoạt công cụ chuẩn xác 100%, không bị nhầm lẫn, trùng lặp hay bỏ sót.

7.1. Danh Sách Công Cụ & Nhãn Phân Loại (Domain Namespaces)

• [00_CENTRAL_DISPATCH] cookiegli_full: Cổng điều phối đa hình trung tâm nhận action và params, tự động định tuyến tới tất cả các tool con.
• [01_TASK_BOOST] cookiegli_boost: Lối vào ưu tiên số 1 khi bắt đầu tác vụ lập trình/gỡ lỗi. Sinh trọn vẹn ngữ cảnh Layer 2 (<600t) gồm BM25 symbols + skeleton focus + ngân sách suy luận 2026.
• [01_TASK_CONTEXT] cookiegli_synthesize_context: Trích xuất lát cắt ngữ cảnh theo từ khóa tác vụ cụ thể.
• [02_SYMBOL_IR] cookiegli_search: Tra cứu toàn văn theo độ tương đồng ngữ nghĩa bằng SQLite FTS5 Okapi BM25+.
• [02_SYMBOL_BTREE] cookiegli_find_symbols: Tra cứu tức thì B-Tree index (<0.05ms) cho tên định danh chính xác (class, function, method).
• [03_CODE_SKELETON] cookiegli_get_skeleton: Gấp gọn mã nguồn xung quanh, giữ nguyên văn 100% hàm trọng tâm (focus_symbol).
• [04_IMPACT_ANALYSIS] cookiegli_blast_radius: Phân tích đồ thị phụ thuộc ngược và chỉ điểm bộ kiểm thử tối thiểu cần chạy.
• [05_ERROR_DISTILLER] cookiegli_distill_lesson: Tự động bóc tách traceback/diff thành bài học Darwin có tính điểm tin cậy Bayesian ROI.
• [06_ARCHITECTURE] cookiegli_get_genome: Nạp bản đồ kiến trúc Layer 1 tĩnh của toàn bộ dự án (<600t).
• [07_DARWIN_MEMORY] cookiegli_darwin_record & cookiegli_darwin_search: Ghi nhớ và truy vấn kinh nghiệm kỹ thuật theo Bayesian Laplace ROI.
• [08_TARGET_SYNC] cookiegli_sync: Đồng bộ bản đồ kiến trúc và bộ nhớ kinh nghiệm vào CLAUDE.md, AGENTS.md, .cursorrules, .windsurfrules.
• [09_HARNESS] cookiegli_harness_status: Lấy dashboard trạng thái độ trưởng thành dự án, chỉ số Bayesian Alignment IQ, các thói quen đang kích hoạt và anti-pattern guards.
• [09_HARNESS] cookiegli_harness_feedback: Tiếp nhận và bóc tách nhận xét sửa đổi của developer bằng tiếng Việt hoặc Anh để cập nhật thói quen hoặc chặn anti-pattern.
• [09_HARNESS] cookiegli_harness_eval: Đánh giá toàn diện mức độ tuân thủ, độ phù hợp (fitness status) và tỷ lệ zero-defect của Agent.

7.2. Ma Trận Hướng Dẫn Ra Quyết Định Của Agent (Agent Disambiguation Matrix)

| Tình Huống Của Agent | Công Cụ Chuẩn Cần Gọi | Tại Sao Dùng Tool Này? | Tool KHÔNG Nên Dùng Lẫn | | :--- | :--- | :--- | :--- | | Bắt đầu một task code mới | cookiegli_boost | Sinh trọn vẹn ngữ cảnh Layer 2 (<600t): symbol BM25 + skeleton + targeted tests + reasoning budget 2026. | Không gọi rời rạc skeleton + symbol nếu chưa boost. | | Muốn tìm hàm/class theo từ khóa tự nhiên | cookiegli_search | Dùng SQLite FTS5 Okapi BM25+ toàn văn, xếp hạng theo độ tương đồng ngữ nghĩa. | Không dùng cookiegli_find_symbols khi chỉ nhớ từ khóa mang máng. | | Biết rõ tên hàm/class chính xác | cookiegli_find_symbols | Dùng SQLite B-Tree index với cờ exact=true, truy xuất siêu tốc <0.05ms. | Không dùng BM25 khi cần khớp chính xác 1 định danh. | | Cần sửa code 1 hàm cụ thể trong file | cookiegli_get_skeleton | Truyền focus_symbol="ten_ham", giữ nguyên văn hàm cần sửa, gập toàn bộ hàm xung quanh để tiết kiệm token. | Không đọc toàn bộ file thô (raw dump). | | Chuẩn bị sửa code hoặc sau khi sửa code | cookiegli_blast_radius | Phân tích đồ thị phụ thuộc ngược, chỉ điểm đúng file test cần chạy. | Không chạy toàn bộ test suite khổng lồ. | | Khi gặp lỗi test / traceback / compiler error | cookiegli_distill_lesson | Bóc tách traceback, tạo bài học Darwin, gán nhãn scope và tính điểm Bayesian ROI. | Không tự sửa mà quên lưu kinh nghiệm. | | Khi developer góp ý / nhắc nhở cách code | cookiegli_harness_feedback | Bóc tách nhận xét tự nhiên (Anh/Việt) thành preference / anti-pattern để tự động ghi nhớ mãi mãi. | Không chỉ "vâng dạ" trong chat mà quên nạp vào harness memory. | | Kiểm tra độ trưởng thành dự án & Alignment IQ | cookiegli_harness_status hoặc cookiegli_harness_eval | Trả về dashboard 4-phase maturity score, Alignment IQ, tỷ lệ tuân thủ và danh sách active guards. | Không đoán mò giai đoạn phát triển của dự án. | | Vào repo lạ hoặc bắt đầu session mới | cookiegli_get_genome | Nạp Layer 1 bản đồ kiến trúc tĩnh (<600t). | Không quét thủ công từng thư mục. | | Muốn dùng 1 tool duy nhất điều phối tất cả | cookiegli_full | Truyền action tương ứng, máy chủ tự xử lý và trả về kết quả chuẩn hóa. | Dành cho các client chỉ hỗ trợ ít tool slots. |

7.3. Tài Nguyên Chỉ Dẫn Tích Hợp (MCP Resources)

Máy chủ hỗ trợ tài nguyên hệ thống qua MCP:

• URI: mcp://cookiegli/guide
• MIME Type: text/markdown
• Nội dung: Cẩm nang quyết định và quy tắc disambiguation hoàn chỉnh, giúp AI Agent tự động đọc hiểu khi kết nối.

7.4. Mẫu Cấu Hình JSON Cho Client MCP

Cấu hình máy chủ CookieGli_Full trong file MCP client (AntiGravity, Claude Desktop, Cursor, Windsurf):

{
  "mcpServers": {
    "CookieGli_Full": {
      "command": "python",
      "args": [
        "E:/AI/Glimax/cli/cookiegli.py",
        "mcp",
        "--profile",
        "full",
        "--root",
        "E:/AI/Glimax"
      ]
    }
  }
}

---

8. Kiểm Thử & Đảm Bảo Chất Lượng

Dự án đi kèm bộ kiểm thử toàn diện với 179 bài test tự động, sử dụng trực tiếp thư viện unittest tích hợp sẵn trong Python:

python -m unittest discover -s tests -v

Kết quả kiểm thử chuẩn:

Ran 179 tests in 3.593s

OK (179/179 Tests Passed - 0 Failures, 0 Regressions)

Kiểm thử bao phủ đầy đủ:

• Khung học hỏi liên tục (Harness Engine), bóc tách phản hồi tự nhiên (Anh/Việt), tính toán Bayesian Alignment IQ và chuyển pha trưởng thành dự án.
• Trích xuất AST và phương thức trên Python, TypeScript, Go, Rust, Java.
• Cơ chế khóa file và chỉ mục B-Tree / FTS5 BM25+ trên SQLite WAL.
• Nén 4 tầng của bộ tạo skeleton và kiểm tra thụt lề chuẩn.
• Đồ thị phụ thuộc ngược và thuật toán BFS chống lặp chu trình.
• Phân giải traceback đa nền tảng và cơ chế tự động khôi phục quy tắc cũ.

---

9. Giấy Phép

Dự án được phát hành theo giấy phép mã nguồn mở [MIT License](LICENSE) © 2026 LoveCookieee (KhoaSuperT1).

Tự do sử dụng, chỉnh sửa và tích hợp vào các dự án phần mềm cá nhân cũng như thương mại.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: LoveCookieee-java
• Source: LoveCookieee-java/CookieGli
• License: MIT

Install and usage instructions live in the source repository linked above.