Code-mapper: Công cụ CLI miễn phí giúp giảm mức sử dụng token của LLM trên mọi cơ sở mã.

code-mapper Tạo tệp PROJECT_CONTEXT.md nhỏ gọn để các mô hình ngôn ngữ lớn (LLM) có thể hiểu toàn bộ cơ sở mã chỉ trong một lần đọc, thay vì năm mươi lần. Khi một LLM mở một dự án chưa biết, nó sẽ đọc từng tệp để xây dựng một mô hình tinh thần. Đối với một dự án 4.000 dòng, quá trình này tiêu tốn khoảng 21.000 token trước khi một dòng mã nào được viết. code-mapper thay thế việc quét này bằng một tệp cấu trúc duy nhất, nắm bắt cùng một bức tranh kiến trúc trong khoảng 4.700 token – giảm 78%. $ python code_mapper.py ./my-project ✓ Đã tạo: my-project/PROJECT_CONTEXT.md Số tệp đã phân tích: 40 (python×40) Số lớp: 20 | Số hàm: 123 Kích thước đầu ra: 18.846 ký tự (~4.711 token) Số dòng mã nguồn: ~4.210 (~21.050 token để đọc thô) Tiết kiệm token: ~78% Nội dung được tạo Một tệp PROJECT_CONTEXT.md duy nhất với bốn phần: Cấu trúc tệp my-project/ ├── src/ ├── api/ └── router.py └── core/ └── engine.py └── tests/ └── test_engine.py Sơ đồ lớp classDiagram class Engine { +config: dict +run() +stop() +__init__() } class BaseEngine["«abstract» BaseEngine"] { +run() } BaseEngine <|-- Engine : extends Đang tải Biểu đồ phụ thuộc module graph TD router --> engine engine --> config Đang tải Chỉ mục ký hiệu **`src/core/engine.py`** `python` > Công cụ xử lý cốt lõi cho việc thực thi tác vụ không đồng bộ. - `«abstract» class BaseEngine` — Lớp cơ sở cho tất cả các công cụ - `class Engine(BaseEngine)` — Triển khai công cụ sản xuất phương thức: `run`, `stop`, `reload` - `async def create_engine(config: dict) → Engine` — Hàm tạo đối tượng Điểm chuẩn Dự án Số dòng mã nguồn Chi phí token thô code-mapper Tiết kiệm Nhỏ (~800 dòng) ~777 ~3.885 ~595 85% Trung bình (~400 dòng) ~379 ~1.895 ~522 72% Lớn (~4.200 dòng) ~4.210 ~21.050 ~4.711 78% Lớn (~4.600 dòng) ~4.649 ~23.245 ~6.056 74% Cài đặt Không có phụ thuộc nào ngoài Python 3.9+. # Sao chép vào thư mục script toàn cục mkdir -p ~/.claude/scripts cp code_mapper.py ~/.claude/scripts/ # Hoặc chỉ chạy tại chỗ python code_mapper.py ./your-project Tác nhân Claude Code (tùy chọn) Để sử dụng nó như một tác nhân phụ của Claude Code (@code-mapper map this project): mkdir -p your-project/.claude/agents/scripts cp agent.md your-project/.claude/agents/code-mapper.md cp code_mapper.py your-project/.claude/agents/scripts/ Cách sử dụng # Cơ bản — ghi PROJECT_CONTEXT.md vào bên trong dự án python code_mapper.py ./my-project # Đường dẫn đầu ra tùy chỉnh python code_mapper.py ./my-project -o .claude/PROJECT_CONTEXT.md # In ra stdout (xem trước / chuyển hướng) python code_mapper.py ./my-project --stdout # Ánh xạ chỉ một thư mục con (kho lưu trữ đơn lớn) python code_mapper.py ./my-project/src/api -o .claude/context_api.md Đoạn mã CLAUDE.md được khuyến nghị: ## Bắt đầu phiên Đọc `.claude/PROJECT_CONTEXT.md` trước khi khám phá bất kỳ tệp nguồn nào. Tạo lại bằng `python ~/.claude/scripts/code_mapper.py .` sau khi thêm module hoặc lớp. Ngôn ngữ được hỗ trợ Ngôn ngữ Trình phân tích cú pháp Độ chính xác Python Module ast tích hợp Chính xác TypeScript / JavaScript Biểu thức chính quy (Regex) Cao Java Biểu thức chính quy (Regex) Cao Go Biểu thức chính quy (Regex) Cao Rust Biểu thức chính quy (Regex) Cao C# Biểu thức chính quy (Regex) Cao Ruby / PHP / Kotlin / Swift / C++ Biểu thức chính quy (Regex) Trung bình Python cung cấp đầu ra phong phú nhất (thuộc tính có kiểu, docstring, phát hiện @dataclass và @abstractmethod). Tất cả các ngôn ngữ khác trích xuất hệ thống phân cấp lớp, các hàm công khai và mối quan hệ nhập thông qua biểu thức chính quy – chính xác đối với các mẫu mã tiêu chuẩn. Tại sao lại là Mermaid + Chỉ mục ký hiệu? Ba lựa chọn thay thế phổ biến đã được đánh giá: Phương pháp Chi phí token Tốc độ hiểu của LLM Bao gồm API công khai Đọc tất cả các tệp nguồn Cao nhất (cơ sở) Chậm nhất Có Kết xuất toàn bộ kho lưu trữ (đóng gói tất cả các tệp) Tương tự như cơ sở Chậm Có Chỉ đồ thị phụ thuộc mã Trung bình Trung bình Một phần UML/PlantUML thô Gấp 2–3 lần Mermaid Chậm hơn Có Mermaid + chỉ mục ký hiệu Thấp nhất Nhanh nhất Có Mermaid được chọn vì đây là định dạng hình ảnh có mật độ token cao nhất (hiệu quả hơn tới 24 lần so với các định dạng sơ đồ XML/JSON) và các mô hình ngôn ngữ lớn (LLM) hiện đại được đào tạo rộng rãi trên đó. Chỉ mục ký hiệu bao gồm những gì sơ đồ không thể hiện được — chữ ký hàm chính xác và chuỗi tài liệu (docstring) cho phép LLM gọi đúng phương thức mà không cần đọc các triển khai. So sánh đầy đủ với số lượng token thực tế: METHOD_COMPARISON.md Xử lý các cơ sở mã lớn Đối với các dự án có hơn 10.000 dòng, hãy ánh xạ các thư mục con một cách độc lập: # Chỉ phần phụ trợ (Backend) python code_mapper.py ./src/backend -o .claude/context_backend.md # Chỉ phần giao diện người dùng (Frontend) python code_mapper.py ./src/frontend -o .claude/context_frontend.md Chỉ tải ngữ cảnh liên quan đến tác vụ hiện tại của bạn. Xem USAGE_GUIDE.md để biết chiến lược đầy đủ cho cơ sở mã lớn. Các tệp code-mapper/ ├── code_mapper.py — Tập lệnh chính (chạy tập lệnh này) ├── agent.md — Định nghĩa tác nhân phụ Claude Code ├── README.md — Tệp này ├── USAGE_GUIDE.md — Hướng dẫn sử dụng đầy đủ (dự án mới/hiện có/lớn) └── METHOD_COMPARISON.md — So sánh chi phí token so với các phương pháp thay thế Yêu cầu Python 3.9+ Không có gói bên thứ ba Đóng góp Mọi đóng góp đều được hoan nghênh. Một số lĩnh vực có thể cải thiện công cụ: Phân tích cú pháp JS/TS tốt hơn — thay thế biểu thức chính quy (regex) bằng một trình phân tích cú pháp cây cú pháp trừu tượng (AST) phù hợp (ví dụ: thông qua tiến trình con của Node.js hoặc liên kết tree-sitter) sẽ làm cho sơ đồ lớp và chỉ mục ký hiệu chính xác cho TypeScript như hiện tại đối với Python. Hỗ trợ ngôn ngữ mới — việc thêm các mẫu cho các ngôn ngữ chưa được hỗ trợ (Scala, Dart, Elixir, v.v.) rất đơn giản: thêm các mục vào ba từ điển mẫu trong RegexParser. Cắt bớt cơ sở mã lớn thông minh hơn — tự động xếp hạng các ký hiệu theo tần suất chúng được tham chiếu (kiểu PageRank, tương tự như cách aider thực hiện) để đầu ra nằm trong giới hạn token mà không cần cắt tỉa thủ công. Hỗ trợ tệp cấu hình — một tệp .codemapper.yml cho mỗi dự án để đặt các quy tắc bỏ qua, giới hạn token và đường dẫn đầu ra. Móc nối IDE/trình chỉnh sửa — tự động tạo lại PROJECT_CONTEXT.md khi lưu tệp trong VS Code hoặc JetBrains. Để đóng góp: phân nhánh kho lưu trữ, thực hiện thay đổi của bạn và mở một yêu cầu kéo (pull request). Không có yêu cầu đóng góp nào ngoài việc duy trì ràng buộc không phụ thuộc (chỉ thư viện chuẩn Python cho tập lệnh cốt lõi). Giấy phép Dự án này là mã nguồn mở và miễn phí sử dụng, sửa đổi và phân phối lại — không có hạn chế giấy phép.