Vnstock Bootstrap Instruction

Khi bạn nhờ các trợ lý AI (như Claude Code, Cursor, ChatGPT hay Antigravity) cài đặt thư viện hoặc viết mã phân tích với vnstock, rắc rối hay gặp nhất là AI tự suy đoán theo dữ liệu huấn luyện cũ: cài nhầm gói vào Python hệ thống làm lỗi môi trường, trộn lẫn cú pháp của bản cũ (3.x/4.x) với thế hệ 5 (5.x), hoặc bảo bạn dán thẳng khoá API cá nhân vào khung trò chuyện.

Kỹ năng Khởi tạo môi trường Vnstock (vnstock-bootstrap) là bộ hướng dẫn nền tảng giúp trợ lý AI của bạn nắm rõ cách thiết lập môi trường ảo, kiểm tra đúng phiên bản thư viện đang có trên máy và tuân thủ các nguyên tắc an toàn trước khi bắt đầu viết mã cùng bạn.

Kỹ năng này giúp gì cho bạn?

• Thiết lập môi trường Python chuẩn xác ngay từ lần đầu: Hướng dẫn trợ lý AI kiểm tra Python trên máy (từ 3.10 trở lên), tạo môi trường ảo riêng biệt (~/.venv hoặc ~/.venv5x) và tích hợp sẵn vào Jupyter Notebook để bạn mở lên là chạy được ngay.
• Tránh lỗi trộn lẫn giữa vnstock thế hệ 5 và dòng cũ: Trước khi cài đặt hay viết bất kỳ dòng lệnh nào, trợ lý AI sẽ tự kiểm tra xem máy bạn đang cài phiên bản nào và dự án hiện tại đang viết theo cú pháp nào để dùng đúng hàm tương ứng, không tự ý cài đè làm hỏng code cũ của bạn.
• Bảo vệ an toàn cho khoá API cá nhân: Giữ nguyên tắc không bao giờ hỏi khoá API trong khung trò chuyện, không in khoá ra màn hình và không viết cứng khoá vào tệp mã nguồn. Khi cần đăng nhập, trợ lý sẽ hướng dẫn bạn tự chạy lệnh nhập ẩn trong terminal của mình (vnstock register).
• Luôn tôn trọng quyền kiểm soát của bạn: Trợ lý AI hiển thị rõ lệnh dự kiến chạy và hỏi ý kiến bạn trước khi cài đặt gói mới hay ghi quy tắc vào tệp AGENTS.md của dự án.

Khi nào bạn nên dùng?

• Khi bạn mới bắt đầu thiết lập máy tính để sử dụng hệ sinh thái Vnstock theo phong cách Vibe Coding cùng trợ lý AI.
• Khi bạn mở một dự án mới và muốn trợ lý AI hiểu ngay quy ước gọi hàm của vnstock thế hệ 5 mà không phải nhắc lại từng lỗi cú pháp.

Cách bật và gỡ hướng dẫn cho trợ lý AI trong dự án

• Trên thế hệ 5 (vnstock 5.x): Thư viện không tự ghi bất kỳ tệp nào vào đĩa cứng khi import. Nếu bạn muốn trợ lý AI ghi nhớ quy tắc dùng Vnstock cho dự án hiện tại, hãy yêu cầu trợ lý chép khối hướng dẫn vào tệp AGENTS.md của dự án (trợ lý sẽ cho bạn xem nội dung trước khi ghi). Khi muốn gỡ, chỉ cần xoá khối đó khỏi AGENTS.md.
• Trên dòng cũ (vnstock 4.0.9+ / vnai 2.6.2+): Khi cần bật cho dự án hiện tại, bạn có thể chạy:

import vnstock
vnstock.enable_agent()   # chỉ ghi vào AGENTS.md của dự án hiện tại
vnstock.setup_agent()

Để tắt và xoá tệp hướng dẫn trên dòng cũ: gọi vnstock.disable_agent() rồi vnstock.remove_agent_files('all').

Thông tin kỹ thuật & Tệp đi kèm

• Cấp quyền lợi cần có: Cộng đồng (Free)

Tên tệp	Vai trò
SKILL.md	Quy tắc xác định thế hệ thư viện, bảng đối chiếu lệnh cài đặt/đăng nhập/import và nguyên tắc bảo mật khoá API
references/env-setup.md	Hướng dẫn chi tiết từng bước tạo môi trường ảo, tích hợp kernel Jupyter (Python (Vnstock 5)) và xử lý lỗi thường gặp trên macOS/Linux/Windows

Tài liệu tham khảo

Xem thêm hướng dẫn dành cho người mới tại: Hướng dẫn Vibe Coding

---

Lịch sử cập nhật

• [4.3.0] - Gộp tài liệu thiết lập môi trường chi tiết vào references/env-setup.md (load_skill("vnstock-bootstrap", component="reference:env-setup.md")) và bổ sung cách gọi python -m vnstock trên Windows khi PATH chưa có thư mục Scripts.
• [4.0.0] - Trợ lý phải xác định thế hệ thư viện (thế hệ 5 hay bản cũ 4.x) trước khi cài, đăng nhập hay viết mã. Bổ sung lệnh cài, đăng nhập, thư viện bổ sung và cách gỡ của thế hệ 5; giữ hướng dẫn bản cũ trong mục riêng.
• [3.0.0] - Khối hướng dẫn chuyển sang tuỳ chọn người dùng tự bật: thư viện không ghi gì khi import, không ghi vào tệp toàn cục nếu bạn không nêu tên, và văn bản đóng gói sẵn trong vnai.
• [2.0.0] - Viết lại theo nguyên tắc minh bạch: chỉ áp dụng khi việc đang làm liên quan tới vnstock, trợ lý hỏi trước khi chạy lệnh và không bao giờ xin khoá truy cập qua khung trò chuyện.