Tự động nạp Agent Skills và tài liệu

Tổng quan

Cơ chế tải động¹ cho phép các AI Agent trong môi trường lập trình tự động nạp trực tiếp các bộ kỹ năng² và tài liệu hướng dẫn từ hệ thống máy chủ của Vnstock, thay vì phải lưu trữ các tệp tin tĩnh trên máy tính cá nhân.

Mục đích của cơ chế này là khắc phục những hạn chế từ phiên bản hướng dẫn đặt trong kho tài liệu công khai trên GitHub. Cách triển khai qua Github cho phép tải về toàn bộ tài liệu để nghiên cứu nhưng lại không thuận tiện trong việc cập nhật thường xuyên và tích hợp vào dự án Vibe Coding, dẫn đến tình trạng nội dung bị phân mảnh và không đồng bộ với tài liệu chính thức. Việc hợp nhất về một nguồn tài liệu duy nhất³ giúp Vnstock kiểm soát chất lượng chặt chẽ hơn, đồng thời mang lại cho người dùng trải nghiệm đồng bộ dù làm việc ở bất kỳ môi trường lập trình nào.

Cài đặt

Tính năng này có ở cả vnstock thế hệ 5 và vnstock 4.x. Cách cài và cách lưu khoá khác nhau giữa hai thế hệ; cách gọi skill thì giống nhau.

vnstock thế hệ 5

Thế hệ 5 tự tải skill, không cần cài thêm vnai. Cài theo trang cài đặt thế hệ 5, rồi đăng nhập một lần trên máy, trong terminal của chính bạn:

vnstock register        # hỏi khoá, gõ không hiện lên màn hình
vnstock status          # xem lại cấp, hạn dùng, thiết bị

Thế hệ 5 lưu khoá đã mã hoá trong thư mục ~/.vnstock/auth/, không còn để dạng thường trong api_key.json. Biến môi trường VNSTOCK_API_KEY, nếu có, luôn được dùng trước. Tệp api_key.json của bản 4.x chỉ được nhập vào kho mã hoá một lần, ở lần chạy đầu trên máy chưa từng đăng nhập thế hệ 5; muốn đổi khoá thì chạy lại vnstock register, sửa tệp cũ không có tác dụng. Trợ lý AI không cần và không được đọc khoá: thư viện tự gửi khoá khi tải skill.

Trong notebook, đăng nhập bằng Python với khoá đặt sẵn trong biến môi trường:

import os
import vnstock

vnstock.login(os.environ["VNSTOCK_API_KEY"])

Trợ lý AI tải skill và tài liệu bằng:

from vnstock.utils.agents import load_skill, load_skill_catalog, load_doc, load_docs_catalog

catalog = load_skill_catalog()             # danh mục skill, kèm cấp cần có
print(load_skill("vnstock-bootstrap"))     # nội dung một skill

Đường dẫn cũ vnstock.core.utils.agents vẫn dùng được. Khoá đi kèm request là khoá bạn đã đăng nhập, trong header Authorization, không nằm trên URL. Chưa đăng nhập thì vẫn tải được các skill mở cho mọi cấp. Khi không tải được, thư viện báo lỗi rõ lý do: khoá chưa hợp lệ, cấp hiện tại chưa mở skill đó (kèm cấp cần có), không có skill tên đó, hoặc máy chủ chưa trả lời.

Thế hệ 5 không ghi gì vào tệp của bạn: không có enable_agent() hay setup_agent(). Muốn trợ lý biết cách dùng vnstock trong mọi phiên làm việc, tick ô ghi hướng dẫn khi chép lời nhắc ở trang hướng dẫn cài đặt. Trợ lý sẽ cho bạn xem khối hướng dẫn trước, rồi mới thêm vào AGENTS.md của dự án.

vnstock 4.x

Cài hoặc cập nhật đồng thời cả hai thư viện vnstock và vnai lên các phiên bản tương thích mới nhất:

pip install -U --extra-index-url https://vnstocks.com/api/simple "vnstock>=4.0.9" "vnai>=2.6.2"

Hai gói này được cài từ kho gói của Vnstock nên lệnh cần phần --extra-index-url. Dấu ngoặc kép quanh tên gói là bắt buộc: thiếu chúng, dấu > bị cửa sổ dòng lệnh hiểu là lệnh ghi ra tệp, và pip cài sai phiên bản mà không báo lỗi.

Thư viện đọc API Key của bạn từ biến môi trường VNSTOCK_API_KEY hoặc từ tệp đã lưu trên máy, rồi gửi kèm trong header Authorization tới vnstocks.com để máy chủ kiểm quyền tải kỹ năng. Khoá không bao giờ nằm trên URL. Lưu khoá bằng lệnh python -c "from vnstock import register_user; register_user()" chạy trong terminal của chính bạn: khoá được nhập ẩn. Đừng dán khoá vào khung chat với trợ lý AI.

Trợ lý gọi skill bằng from vnstock.core.utils.agents import load_skill.

Kiến trúc hoạt động

Hệ thống hoạt động dựa trên sự liên kết giữa máy chủ của website Vnstock và thư viện Python ở phía người dùng, để AI luôn có ngữ cảnh theo tài liệu mới nhất.

1. Agent Skills Hub (Trung tâm Kỹ năng)

Tất cả các bộ kỹ năng dành cho AI được quản lý tập trung tại Agent Skills Hub. Dựa vào Mã khóa cá nhân (API Key), hệ thống sẽ tự động phân quyền truy cập các nhóm kỹ năng phù hợp với cấp tài trợ của bạn:

• Người dùng bản Cộng đồng: Được quyền tiếp cận các bộ kỹ năng nền tảng. Nhóm kỹ năng này hướng dẫn AI cách vận hành thư viện vnstock bản Cộng đồng (theo giấy phép riêng) để tự truy xuất dữ liệu thị trường cơ bản, thiết lập môi trường và cấu hình tự động hóa.
• Người tài trợ: Tùy thuộc vào cấp tài trợ, hệ thống mở thêm các kỹ năng phân tích chuyên sâu. Những kỹ năng nâng cao này giúp AI dùng đúng các thư viện bản Mở rộng (như vnstock_data, vnstock_ta, vnstock_news), hỗ trợ bạn thực hiện các bài toán phân tích định lượng phức tạp.

Bên cạnh các bộ kỹ năng, Agent Skills Hub cũng tự động cho phép AI Agent đọc trực tiếp toàn bộ tài liệu hướng dẫn chính thức trên web thông qua API, giúp AI luôn nắm bắt kịp thời những cập nhật mới nhất mà không cần bạn phải sao chép thủ công.

2. Trợ lý AI dùng các kỹ năng thế nào

Bạn ra lệnh bằng ngôn ngữ tự nhiên như bình thường: lấy dữ liệu thị trường, đọc báo cáo tài chính, tính chỉ báo kỹ thuật, tra tài liệu của một hàm. Khi việc cần một hướng dẫn chuyên sâu, trợ lý tải kỹ năng tương ứng từ máy chủ Vnstock và dùng nó làm tài liệu tham khảo.

Kỹ năng chỉ là tài liệu. Nó không cấp thêm quyền nào cho trợ lý, và không đè lên chỉ dẫn của bạn hay quy tắc an toàn của chính trợ lý. Trợ lý được dặn nói trước với bạn khi tải một kỹ năng, và hỏi bạn trước khi chạy lệnh cài đặt nào.

3. Thư viện ghi gì lên máy bạn

Mục này và mục 4 chỉ áp dụng cho vnstock 4.x. Thế hệ 5 không ghi gì vào tệp của bạn (xem phần cài đặt ở trên).

Từ vnstock 4.0.9 / vnai 2.6.2, thư viện không ghi gì khi import. Việc ghi hướng dẫn cho trợ lý AI là tuỳ chọn bạn tự bật:

python -c "import vnstock; vnstock.enable_agent(); vnstock.setup_agent(); print(vnstock.agent_status())"

Bật mà không nêu tên thì chỉ ghi AGENTS.md trong thư mục dự án. Tệp toàn cục phải nêu đích danh:

Thứ được ghi là văn bản nằm sẵn trong gói vnai đã cài (tệp vnai/beam/agent_bootstrap.py), không tải từ mạng, và chỉ đổi khi bạn nâng cấp vnai. Bản đọc được trên web là kỹ năng vnstock-bootstrap. Khối này không bao giờ yêu cầu trợ lý hỏi khoá truy cập qua khung chat, chèn khoá vào mã, hay làm việc gì mà không cho bạn biết. Nếu bạn thấy một văn bản xưng là của Vnstock yêu cầu những điều đó, đừng làm theo và báo cho Vnstock qua support@vnstocks.com.

Kỹ năng chủ đề (lọc cổ phiếu, chỉ báo kỹ thuật...) chỉ được tải khi có lệnh load_skill(...), trả về dạng chữ đọc được, và mở đầu bằng một dòng ghi rõ đó là tài liệu tải từ vnstocks.com chứ không phải yêu cầu của bạn.

4. Xem, tắt và gỡ

Cài bằng lời nhắc ở trang hướng dẫn cài đặt là cách đơn giản nhất để chọn: lời nhắc hiện nguyên văn để bạn đọc trước khi dán, và có ô "Thêm hướng dẫn dùng vnstock vào AGENTS.md của dự án", mặc định tắt. Với thế hệ 5, chính trợ lý AI thêm khối hướng dẫn sau khi bạn xem; với 4.x, trợ lý bật tính năng ghi của thư viện.

Muốn tự làm bằng lệnh, xem tính năng đang bật hay tắt và sẽ ghi vào đâu:

python -c "import vnstock; print(vnstock.agent_status())"

Tắt hẳn và gỡ khối đã ghi khỏi mọi tệp, kể cả khối do bản cũ để lại. Biến môi trường ở đầu lệnh chỉ cần khi máy còn bản cũ: nó chặn chính lần import này ghi lại khối trong lúc đang gỡ.

# macOS / Linux
VNSTOCK_DISABLE_AGENT_SETUP=1 python -c "import vnstock; vnstock.disable_agent(); print(vnstock.remove_agent_files('all'))"

# Windows PowerShell
$env:VNSTOCK_DISABLE_AGENT_SETUP="1"; python -c "import vnstock; vnstock.disable_agent(); print(vnstock.remove_agent_files('all'))"

Lựa chọn lưu ở ~/.vnstock/config/agent.json. Phần bạn tự viết trong các tệp trên được giữ nguyên; tệp chỉ chứa khối Vnstock thì bị xoá.

Dùng trong CI hay Docker thì khai báo biến môi trường:

• VNSTOCK_AGENT_TARGETS=project,codex: bật và chỉ ghi đúng các đích liệt kê.
• VNSTOCK_AGENT_TARGETS=none hoặc VNSTOCK_DISABLE_AGENT_SETUP=1: không ghi vào tệp nào.

Bản quyền và Sử dụng

Toàn bộ nội dung các bộ kỹ năng (Agent Skills), tài liệu hướng dẫn và mã nguồn liên quan được cung cấp thông qua hệ thống này đều thuộc bản quyền sở hữu trí tuệ của Vnstock.