Local Semantic Context — Truy xuất, AST chuẩn hóa và Code Graph

1 Tổng quan và hướng dẫn sử dụng

Semantic Context là tính năng tìm kiếm ngữ cảnh thông minh hoạt động hoàn toàn cục bộ trên máy tính người dùng, tích hợp sẵn bên trong ứng dụng ICD MCP Dashboard.

Đặc điểm nổi bật

Chạy hoàn toàn trên CPU cục bộ.
Không cần môi trường chạy Python hoặc Docker.
Không tải thêm dữ liệu từ Internet trong quá trình hoạt động.
Chỉ cập nhật các tệp thay đổi dựa trên mã băm BLAKE3.

Không phụ thuộc dịch vụ đám mây

Không dùng máy chủ mô hình bên ngoài.
Không phụ thuộc cơ sở dữ liệu vector đám mây như Pinecone hoặc Qdrant.
Không cần cài đặt SQLite thủ công.
Không lưu lịch sử truy vấn hoặc câu lệnh.

AST chuẩn hóa và Code Graph là lớp bổ sung sau lựa chọn

Sáu nhóm ngôn ngữ được chuẩn hóa về declaration, import và reference. Sau khi retrieval, xếp hạng và lựa chọn đã hoàn tất, Code Graph mới phân giải quan hệ quanh các symbol đã chọn. Lớp này không thay đổi phân đoạn, thứ tự, khoảng cách vector, điểm xếp hạng, ngân sách source hoặc nội dung mã nguồn trong Markdown.

2 Sơ đồ quy trình

Nhấp vào từng bước bên dưới để xem chi tiết thông số kỹ thuật xử lý.

Bước 1

Quét tệp an toàn

Áp dụng allowlist, giới hạn và chính sách đọc file dùng chung.

Bước 2

Tạo chunk và AST chuẩn hóa

Chunking giữ contract cũ; AST trích xuất declaration, import và reference.

Bước 3

Tạo vector nhúng

ONNX Runtime cục bộ tạo vector 384 chiều cho semantic chunks.

Bước 4

Cập nhật SQLite và graph sidecar

Lưu vector, chunk, symbol và edge theo content hash của từng file.

Bước 5

Truy xuất và xếp hạng

Lấy tối đa 96 vector candidate rồi rerank bằng tín hiệu semantic, lexical và cấu trúc.

Bước 6

Chọn và đóng băng kết quả

Chọn tối đa 12 chunk trong 64 KiB; cố định thứ tự, distance và source.

Bước 7

Phân giải Code Graph

Ánh xạ selected chunk sang symbol và chỉ giữ quan hệ project-local đủ tin cậy.

Bước 8

Xuất Markdown

Render source trước; chỉ nối graph section tối đa 6 KiB khi có relation hợp lệ.

3 Mô hình nhúng và giới hạn token

Đặc tả kỹ thuật của mô hình

Mô hình nền	sentence-transformers/all-MiniLM-L6-v2
Mã định danh nội bộ	AllMiniLML6V2Q
Tệp ONNX	model.onnx
Số chiều vector	384
Phương pháp gộp và lượng tử hóa	gộp trung bình / lượng tử hóa động
Số token đầu vào tối đa	128 token
Tiền tố truy vấn/đoạn nguồn	"" (chuỗi rỗng)
Thư viện môi trường chạy	libonnxruntime.dylib

Giới hạn token: đầu vào 128, phân đoạn 112, chồng lặp 16

Mỗi phân đoạn có tối đa 112 token; 16 token cuối có thể được lặp lại ở phân đoạn kế tiếp. Giới hạn 128 token là trần đầu vào của mô hình, không phải tổng bắt buộc của 112 và 16.

Phân đoạn A (token 1–112) 112 token

Nội dung phân đoạn A Trần mô hình: 128 token

Phân đoạn B (token 97–208) 112 token

Phần chồng lặp 97–112 (16 token) Nội dung mới: 96 token

Lưu ý khi vận hành: Đầu vào embedding giữ nguyên chunk.content và có thể bổ sung metadata an toàn trong giới hạn token. Declaration của AST, graph symbol key, edge và relation đã phân giải không được đưa vào embedding input.

Tài nguyên được đóng gói cùng ứng dụng (`src-tauri/assets/semantic/`)

model-manifest.json

model.onnx

tokenizer.json

libonnxruntime.dylib

4 Quét mã nguồn và quy tắc loại trừ tệp

Các phần mở rộng được lập chỉ mục (`APP_SOURCE_EXTENSIONS`)

Tối đa 2.000 tệp, tổng dung lượng 64 MiB

Thư mục bị loại trừ (`EXCLUDED_DIRECTORY_NAMES`)

Mọi thư mục có tên bắt đầu bằng dấu chấm (.git, .vscode, .config...) cùng các thư mục chứa thư viện phụ thuộc, bản dựng và dữ liệu sinh ra:

node_modules target vendor dist build coverage __pycache__ .venv assets public

Khôi phục khi WalkDir gặp lỗi

Lỗi thư mục gốc của dự án: Không tồn tại hoặc không phải thư mục hợp lệ → Dừng toàn bộ yêu cầu (SemanticError).

Lỗi tại một mục riêng lẻ: Không thể đọc một tệp hoặc thư mục con → Ghi nhận skipped_files += 1, thêm cảnh báo an toàn và tiếp tục quét.

5 Lưu trữ vector bằng SQLite và sqlite-vec

Cấu trúc bảng vector ảo

CREATE VIRTUAL TABLE IF NOT EXISTS 
semantic_vectors USING vec0(
    searchable boolean,
    embedding float[384]
);

Lưu trữ tại: <app-cache>/semantic/<project-hash>.sqlite (Trong đó project-hash là mã băm BLAKE3 của đường dẫn dự án đã chuẩn hóa).

Graph sidecar: các bảng graph_symbols và graph_edges nằm trong cùng cơ sở dữ liệu nhưng không tham gia vector retrieval. Freshness được kiểm soát theo content hash của từng file.

Điều phối truy cập đồng thời

Sử dụng hai khóa Mutex trong cấu trúc SemanticRuntimeState:

runtime: Mutex<Option<SemanticRuntime>>
Bảo vệ việc khởi tạo khi cần và tái sử dụng mô hình cùng bộ tách token.
operation_lock: Mutex<()>
Xử lý tuần tự toàn bộ tác vụ ngữ nghĩa từ lúc quét đến khi xếp hạng.

Thời gian chờ khi cơ sở dữ liệu đang bận: busy_timeout(5s).

6 Xếp hạng

Trọng số ngữ nghĩa

0.50

Trọng số từ khóa

0.35

Trọng số khoảng cách

0.70

Trọng số thứ hạng

0.30

Công thức tính điểm tổng hợp:

semantic_score = 0.70 × distance_score + 0.30 × rank_score

base_score = 0.50 × semantic_score + 0.35 × lexical_score

final_score = clamp(base_score + structural_adjustment, -1.0, 2.0)

Hiệu chỉnh cấu trúc: Điểm cộng hoặc trừ trực tiếp dựa trên tín hiệu như khớp chính xác tên ký hiệu, khai báo hàm hoặc khối impl thực tế, hằng số giới hạn, trừ điểm nếu chỉ chứa chú thích (-) hoặc câu lệnh import (-).

Ranh giới bắt buộc: Code Graph không được truyền vào rank_candidates() hoặc select_ranked_chunks*(). Graph chỉ được truy vấn sau khi selected chunks, thứ tự, vector distance và source byte budget đã được đóng băng.

7 AST chuẩn hóa và Code Graph

Lớp dữ liệu bổ sung giúp giải thích quan hệ quanh source đã được Semantic Context chọn.

AST chuẩn hóa

Các parser Tree-sitter chuyển cú pháp riêng của từng ngôn ngữ thành mô hình chung chỉ giữ dữ liệu cần cho Code Graph: declaration, import, reference và source range.

Rust TypeScript / TSX JavaScript / JSX Python C# Dart

Việc có AST không thay đổi semantic chunking: Rust tiếp tục dùng structured chunks; các nhóm ngôn ngữ còn lại tiếp tục dùng line-based fallback.

Quan hệ Code Graph

Tín hiệu AST	Quan hệ graph
Call / ConstructorCall	Calls
TypeUse / ValueUse	Uses
Extend	Extends
Implement	Implements
TestTarget	Tests
Import	Imports — lưu nhưng không render

Edge được nạp 256

Relation / symbol 3

Relation được render 10

Ngân sách graph riêng 6 KiB

Thứ tự không thể đảo ngược

Retrieve → Rank → Select → Freeze
                              ↓
                     Resolve Code Graph
                              ↓
            Render source → Append graph section

Cô lập lỗi

Lỗi AST hoặc graph không làm mất semantic source Markdown hợp lệ.
Graph không khớp content hash không được truy vấn.
Target mơ hồ bị bỏ thay vì suy đoán.
Không có relation hợp lệ thì toàn bộ graph section được bỏ qua.

Hợp đồng Markdown

# Semantic Context

## path/to/file.rs | `selected_symbol` | function | lines 10-40
```rust
// Nội dung source gốc của chunk đã chọn
```

## Code Graph Context for Selected Symbols

### `path/to/file.rs::selected_symbol`
- **Calls:** `target_symbol`
  `path/to/target.rs`

Phần source phía trước graph heading phải giữ nguyên byte-for-byte. Ngân sách graph được áp dụng riêng và không trừ vào giới hạn 64 KiB của source chunks.

8 Nguồn tham chiếu kỹ thuật

Các tệp mã nguồn dưới đây là nguồn đối chiếu chính khi nội dung tài liệu có mâu thuẫn.

Nội dung	Tệp mã nguồn tham chiếu

9 Các quyết định kiến trúc hiện tại

Chạy hoàn toàn cục bộ

Mô hình và ONNX Runtime được đóng gói trực tiếp cùng ứng dụng macOS/x86_64.

Mỗi dự án dùng một cơ sở dữ liệu SQLite

Tệp cơ sở dữ liệu riêng biệt theo mã băm đường dẫn gốc, tự động dọn dẹp bản ghi cũ.

Xử lý đồng thời an toàn

Toàn bộ luồng quét → index → retrieval → graph → render được bảo vệ bằng khóa Mutex operation_lock.

Bảo vệ thông tin đường dẫn

Cảnh báo trả về giao diện không chứa đường dẫn tuyệt đối hoặc thư mục cá nhân của người dùng.

Code Graph chỉ là hậu xử lý

Graph chạy sau final selection và không thay đổi chunk, thứ tự, distance, score, source budget hoặc source content.

Ưu tiên bỏ sót hơn liên kết sai

Resolver chỉ giữ target duy nhất, project-local và đủ tin cậy; relation mơ hồ được loại bỏ.

Local Semantic Context Tìm mã nguồn và giải thích quan hệ mã