Vnstock Master Skill

Khi dùng các công cụ AI chung (như ChatGPT, Claude, Cursor hay Antigravity) để phân tích chứng khoán với Python, bạn thường mất rất nhiều thời gian giải thích lại từ đầu cách gọi hàm vnstock, cách đặt ngưỡng lọc hay cách trình bày báo cáo.

Bộ Kỹ năng AI của Vnstock (vnstock-agent-skills) giải quyết vấn đề đó bằng cách trang bị sẵn cho trợ lý AI những quy trình mẫu, kịch bản Python và tệp cấu hình chuẩn hoá (config.yaml) chạy trực tiếp trên máy tính của bạn:

Dành cho người mới bắt đầu hoặc đang xây dựng công cụ: Trợ lý AI biết cách tự thiết lập môi trường ảo, chọn kiến trúc dự án, nâng cấp mã nguồn lên thế hệ 5, vẽ biểu đồ trực quan và giữ lịch sử Git an toàn.
Dành cho quy trình nghiên cứu định kỳ (10 bước liên hoàn): Từ đánh giá bức tranh vĩ mô, lọc ra 20–30 mã theo dõi, tính chỉ báo kỹ thuật, nhận diện các mẫu hình định lượng, cho tới chuẩn hoá danh mục đang nắm giữ, đo rủi ro mở và ghi nhật ký thống kê kết quả thực thi của chính bạn.

Danh mục kỹ năng theo cấp

Cộng đồng (Free)

Các kỹ năng nền tảng giúp bạn thiết lập môi trường, chuyển đổi mã nguồn, dựng ứng dụng và trực quan hoá dữ liệu:

Kỹ năng	Mô tả
vnstock-bootstrap	Xác định thế hệ thư viện, thiết lập môi trường ảo và quy tắc làm việc với trợ lý AI
solution-architect	Chọn cấu trúc dự án và mẫu mã nguồn (Script, Notebook, Streamlit, FastAPI/PySide6)
migration-assistant	Đối chiếu và chuyển đổi mã nguồn từ dòng cũ (3.x/4.x, `vnstock_data`) sang thế hệ 5
charting-expert	Vẽ biểu đồ giá, khối lượng và thống kê trực quan bằng Matplotlib, Seaborn & `vnstock_ezchart`
news-crawler	Theo dõi danh sách bài viết mới từ RSS/Sitemap bằng `vnstock_news`
pipeline-cli	Vận hành thư mục dữ liệu Parquet/CSV cục bộ và tác vụ tải theo lô qua `vnstock_pipeline`

Bronze

Cấp Bronze bao gồm quyền sử dụng bản Mở rộng trên thư viện, kèm kỹ năng quản lý lịch sử mã nguồn khi làm việc cùng trợ lý AI:

Kỹ năng	Mô tả
git-master	Giữ lịch sử Git của dự án sạch, an toàn và dễ rà soát khi trợ lý AI sửa mã
+ Toàn bộ kỹ năng cấp Free	Được bao gồm đầy đủ

Silver

Bổ sung bộ 3 kỹ năng phân tích thị trường, sàng lọc cổ phiếu và tính chỉ báo kỹ thuật theo bộ tham số tiêu chuẩn:

Kỹ năng	Mô tả
macro-analyzer	Tổng hợp dữ liệu vĩ mô, liên thị trường và gắn nhãn trạng thái thị trường (`Market Regime`)
market-screener	Lọc và xếp hạng cổ phiếu theo tiêu chí cơ bản, thanh khoản và xu hướng giá (`Trend Template`)
indicator-calculator	Tính bộ chỉ báo kỹ thuật (`RSI`, `MACD`, `Bollinger`, `ADX`, `OBV`...) và đánh dấu mã chạm ngưỡng kỹ thuật
+ Toàn bộ kỹ năng cấp Bronze	Được bao gồm đầy đủ

Golden

Bổ sung trọn bộ kỹ năng nhận diện mẫu hình định lượng, chuẩn hoá danh mục, ghi nhật ký hiệu suất và tuỳ chỉnh tệp cấu hình config.yaml theo quy tắc riêng của bạn:

Kỹ năng	Mô tả
signal-detector	Nhận diện 4 mẫu hình định lượng theo quy tắc toán học, chấm điểm chất lượng và tính mốc giá tham chiếu
portfolio-extractor	Đọc và chuẩn hoá danh mục đang nắm giữ từ văn bản, bảng biểu hoặc ảnh chụp màn hình
performance-journal	Ghi nhật ký vị thế đã đóng (20 trường) và tính 10 chỉ số thống kê mô tả theo kỳ
strategy-tuner	Thống kê kết quả lịch sử theo từng mẫu hình trong nhật ký và chỉ ra điểm lệch so với quy tắc đã khai
config-manager	Quản lý, kiểm tra hợp lệ và lưu lịch sử thay đổi cho các tham số trong `config.yaml`
emergency-protocol	Đối chiếu số đo danh mục và thị trường với các ngưỡng cảnh báo bạn tự đặt trong `config.yaml`
+ Toàn bộ kỹ năng cấp Silver	Được bao gồm đầy đủ (kèm quyền tuỳ chỉnh `config.yaml`)

Diamond

Bổ sung kỹ năng đo lường rủi ro danh mục hiện có và quyền tuỳ chỉnh toàn bộ tham số cấp hệ thống:

Kỹ năng	Mô tả
risk-manager	Đo tỷ trọng vị thế, rủi ro mở tổng hợp (`portfolio heat`) và mức độ tập trung ngành so với hạn mức bạn tự khai
+ Toàn bộ kỹ năng cấp Golden	Được bao gồm đầy đủ
+ Cấu hình cấp hệ thống (`system-level config`)	Cho phép tuỳ chỉnh cả các tham số cấu trúc nâng cao trong `config-manager`

Nguyên tắc thực thi dành cho trợ lý AI

Đọc kỹ tài liệu tổng quan này trước khi tải hoặc chạy bất kỳ kỹ năng thành phần nào.
Xác định thế hệ thư viện trước mọi việc khác (xem mục ngay bên dưới). Thế hệ 5 (vnstock 5.x) và dòng cũ (vnstock 3.x/4.x) dùng chung tên gói vnstock nhưng khác nhau về lệnh cài đặt, cách đăng nhập, dòng import, thư viện bổ sung và cách báo lỗi. Không tự ngầm định.
Sử dụng hàm load_skill() với đúng đường dẫn import của thế hệ đã xác định để tải nội dung kỹ năng khi cần.
Chỉ giữ nội dung kỹ năng được bảo vệ trong bộ nhớ của phiên làm việc — không ghi hay sao chép nội dung kỹ năng ra tệp trên đĩa cứng.
Không tự suy diễn tên hàm, tham số hoặc hành vi ngoài những gì đã được mô tả trong tài liệu.

Xác định thế hệ thư viện

Chạy lệnh kiểm tra trong đúng môi trường Python mà người dùng đang sử dụng (môi trường ảo hoặc kernel của Notebook, không phải Python mặc định của hệ điều hành):

python -c "import importlib.metadata as m; print(m.version('vnstock'))"

Phiên bản bắt đầu bằng 5. $\rightarrow$ thế hệ 5.
Phiên bản bắt đầu bằng 3. hoặc 4. $\rightarrow$ dòng cũ. Sự hiện diện của vnstock_data, vnai hoặc vnstock_installer trong môi trường cũng là dấu hiệu của dòng cũ.
Chưa cài đặt $\rightarrow$ mặc định cài mới theo thế hệ 5 (phát hành chính thức từ 15/10/2026), trừ khi người dùng yêu cầu giữ dòng cũ.

Đồng thời kiểm tra cả mã nguồn trong dự án: các cụm from vnstock_data, from vnstock_ta, Vnstock().stock(, register_user, vnai là mã viết cho dòng cũ. Nếu môi trường và mã nguồn lệch thế hệ, hãy dừng lại và hỏi người dùng muốn chuyển mã sang thế hệ 5 (dùng kỹ năng migration-assistant) hay tạo môi trường ảo riêng cho dòng cũ. Không cài hai thế hệ chung một môi trường ảo vì bản cài sau sẽ ghi đè bản cài trước. Luôn báo ngắn gọn cho người dùng biết đã xác định thế hệ nào và dựa trên dấu hiệu gì.

Hạng mục	Thế hệ 5 (`vnstock` 5.x)	Dòng cũ (`vnstock` 3.x/4.x)
Cài đặt thư viện lõi	`python -m pip install -U --extra-index-url https://vnstocks.com/api/packages vnstock`	`python -m pip install -U --extra-index-url https://vnstocks.com/api/simple vnstock vnai`
Phụ thuộc đi kèm	Python 3.10+ và `pandas`; không cần `vnai`, không cần trình cài riêng	`vnai`, `vnii`; thành viên tài trợ dùng `vnstock_installer==3.1.3` hoặc `vnstock-cli-installer.run`
Đăng nhập khoá API	Người dùng tự chạy `vnstock register` trong terminal (nhập ẩn)	`register_user()`
Kiểm tra tài khoản	`vnstock status`, `vnstock usage`, `vnstock doctor`	Chạy lại `register_user()` và chọn `N`
Thư viện bổ sung	`vnstock install --list`, sau đó `vnstock install` (cài theo cấp của khoá API)	Qua trình cài đặt riêng theo cấp tài trợ
Dòng `import` dữ liệu	`from vnstock import Market, Reference, Fundamental, ...` cho mọi cấp	Bản Cộng đồng: `from vnstock import ...`; cấp tài trợ: `from vnstock_data import ...`
Chỉ báo & định lượng	`vnstock_quant`	`vnstock_ta`
Hàm tải kỹ năng AI	`from vnstock.utils.agents import load_skill`	`from vnstock.core.utils.agents import load_skill`
Tài liệu tra cứu	https://vnstocks.com/docs/vnstock	https://vnstocks.com/docs/vnstock

Bảng đối chiếu đầy đủ (bao gồm vnstock_news, vnstock_pipeline, xử lý ngoại lệ và cập nhật phiên bản) nằm trong kỹ năng vnstock-bootstrap.

Hướng dẫn tải nội dung kỹ năng

Yêu cầu trước khi tải

Môi trường Python đã cài vnstock thế hệ 5, hoặc vnstock >= 4.0.8 nếu dùng dòng cũ.
Khoá API đã được đăng ký trên máy: dùng vnstock register (thế hệ 5) hoặc register_user() (dòng cũ).
Cấp tài trợ còn hiệu lực tương ứng với kỹ năng cần tải.

Cách gọi `load_skill()`

from vnstock.utils.agents import load_skill          # Thế hệ 5
# from vnstock.core.utils.agents import load_skill   # Dòng cũ (4.x)

# Tải hướng dẫn chính (SKILL.md) của một kỹ năng
skill_content = load_skill("macro-analyzer")

# Tải tệp cấu hình mẫu (config.yaml)
config = load_skill("macro-analyzer", component="config")

# Tải kịch bản thực thi đi kèm
script = load_skill("macro-analyzer", component="script:run_market_analyzer.py")

# Tải tài liệu tham chiếu phụ trợ
ref = load_skill("vnstock-bootstrap", component="reference:env-setup.md")

Kiểm tra trạng thái khoá API

Trên thế hệ 5, người dùng chạy trực tiếp trong terminal:

vnstock status

Trên dòng cũ:

from vnstock.core.utils.auth import check_status

check_status()

Đăng ký khoá API trên máy (khi chưa đăng nhập)

Trợ lý AI không bao giờ hỏi khoá API qua khung trò chuyện. Người dùng tự chạy trong terminal của mình:

vnstock register   # Thế hệ 5 (nhập khoá ẩn)

Hoặc trên dòng cũ:

from vnstock.core.utils.auth import register_user

register_user()

Bảng chọn nhanh kỹ năng theo nhu cầu

Công việc cần thực hiện	Kỹ năng sử dụng	Cấp quyền lợi cần có
Khởi tạo môi trường ảo & xác định thế hệ thư viện	`vnstock-bootstrap`	Free
Chọn cấu trúc ứng dụng (Script, Notebook, Streamlit, API)	`solution-architect`	Free
Chuyển đổi mã nguồn từ `vnstock` 4.x / `vnstock_data` 3.x sang thế hệ 5	`migration-assistant`	Free
Vẽ biểu đồ tài chính và thống kê tĩnh bằng Matplotlib / Seaborn	`charting-expert`	Free
Theo dõi tin tức tài chính từ RSS / Sitemap bằng `vnstock_news`	`news-crawler`	Silver (công khai hướng dẫn ở Free)
Tổ chức thư mục dữ liệu Parquet/CSV và chạy tác vụ tải theo lô	`pipeline-cli`	Golden (công khai hướng dẫn ở Free)
Giữ lịch sử Git gọn, an toàn khi trợ lý AI sửa mã	`git-master`	Bronze
Tổng hợp vĩ mô, liên thị trường & gắn nhãn trạng thái thị trường	`macro-analyzer`	Silver
Sàng lọc và xếp hạng cổ phiếu theo tiêu chí cơ bản & xu hướng giá	`market-screener`	Silver
Tính bộ chỉ báo kỹ thuật (`RSI`, `MACD`, `BB`...) & đánh dấu mã chạm ngưỡng	`indicator-calculator`	Silver
Nhận diện 4 mẫu hình định lượng theo quy tắc toán học & tính mốc tham chiếu	`signal-detector`	Golden
Đọc và chuẩn hoá danh mục đang nắm giữ từ văn bản / bảng / ảnh chụp	`portfolio-extractor`	Golden
Ghi nhật ký vị thế đã đóng (20 trường) & tính 10 chỉ số thống kê mô tả	`performance-journal`	Golden
Rà soát thống kê lịch sử theo từng mẫu hình trong nhật ký	`strategy-tuner`	Golden
Cá nhân hoá tham số trong `config.yaml` & lưu lịch sử thay đổi	`config-manager`	Golden
Đối chiếu danh mục & thị trường với các ngưỡng cảnh báo tự đặt	`emergency-protocol`	Golden
Đo tỷ trọng vị thế, rủi ro mở tổng hợp (`portfolio heat`) & tập trung ngành	`risk-manager`	Diamond

Thứ tự phối hợp trong quy trình phân tích 10 bước

Các kỹ năng phân tích được thiết kế để đọc/ghi dữ liệu nối tiếp nhau qua các tệp chuẩn hoá trong thư mục data/processed/ và data/reports/ trên máy của bạn:

1. macro-analyzer       → Gắn nhãn bối cảnh thị trường (Market Regime)         [Silver]
2. market-screener      → Lọc danh sách mã theo dõi theo tiêu chí đã khai      [Silver]
3. indicator-calculator → Tính chỉ báo kỹ thuật, đánh dấu mã chạm ngưỡng       [Silver]
4. signal-detector      → Rà soát 4 mẫu hình định lượng & tính mốc tham chiếu  [Golden]
5. portfolio-extractor  → Đọc và chuẩn hoá danh mục đang nắm giữ               [Golden]
6. risk-manager         → Đo rủi ro danh mục so với hạn mức đã khai            [Diamond]
7. performance-journal  → Ghi nhận vị thế đã đóng & tính thống kê mô tả        [Golden]
8. emergency-protocol   → Báo khi chỉ số thị trường/danh mục chạm ngưỡng đặt   [Golden]
9. strategy-tuner       → Thống kê lịch sử theo mẫu hình trên nhật ký đã có    [Golden]
10. config-manager      → Kiểm tra hợp lệ & cập nhật tham số trong config.yaml [Golden]

Điểm cuối tra cứu danh mục (dạng máy đọc)

Để lấy danh sách toàn bộ kỹ năng ở định dạng JSON:

GET https://vnstocks.com/api/skills/catalog

Phạm vi kỹ năng và quyền tuỳ chỉnh cấu hình theo cấp

Cấp tài trợ	Kỹ năng sử dụng được	Quyền tuỳ chỉnh `config.yaml`
Free	6 hướng dẫn công khai (`vnstock-bootstrap`, `solution-architect`, `migration-assistant`, `charting-expert`, `news-crawler`, `pipeline-cli`)	Không áp dụng
Bronze	+ `git-master`	Không áp dụng
Silver	+ 3 kỹ năng phân tích cốt lõi (`macro-analyzer`, `market-screener`, `indicator-calculator`)	Dùng cấu hình tiêu chuẩn (chỉ đọc)
Golden	+ 6 kỹ năng nâng cao (`signal-detector`, `portfolio-extractor`, `performance-journal`, `strategy-tuner`, `emergency-protocol`, `config-manager`)	Tuỳ chỉnh các tham số cho phép cá nhân hoá (`customizable_keys`)
Diamond	+ `risk-manager`	Tuỳ chỉnh toàn bộ tham số, bao gồm cả khoá cấu trúc cấp hệ thống (`system_level_keys`)

Tuyên Bố Miễn Trừ Trách Nhiệm

Tuyên bố miễn trừ trách nhiệm: Bộ kỹ năng này là tài liệu mẫu cho quy trình nghiên cứu và tự động hoá phân tích của riêng bạn, để bạn tham khảo và tuỳ chỉnh. Nội dung và kết quả từ các kỹ năng này không cấu thành tư vấn hay khuyến nghị đầu tư. Bạn tự đối soát dữ liệu và tự chịu trách nhiệm về quyết định đầu tư của mình; Vnstock chịu trách nhiệm mô tả trung thực phần mềm và sửa lỗi ở lớp kết nối, chuẩn hoá.

⚖️ Thoả thuận cấp phép người dùng cuối (EULA)

Bản quyền đối với bộ công cụ, mã nguồn và tài liệu kỹ năng kèm theo thuộc về dự án Vnstock. Phần mềm và tài liệu được bảo hộ bởi luật bản quyền cùng các điều ước quốc tế về sở hữu trí tuệ.

Thông tin cấp phép

Người được cấp phép (Licensee): {{USER_NAME}}
Email đăng ký: {{USER_EMAIL}}
Phạm vi giấy phép: Sử dụng cho nghiên cứu và dự án cá nhân của người đăng ký; không tái phân phối dưới mọi hình thức.

Tóm tắt điều khoản sử dụng

Quyền sử dụng cho nghiên cứu cá nhân: Người được cấp phép có quyền sử dụng và tích hợp bộ kỹ năng vào quy trình nghiên cứu, phân tích dữ liệu và tự động hoá cá nhân trên thiết bị đã đăng ký. Bạn được phép tuỳ biến các tệp cấu hình (config.yaml) phục vụ nhu cầu riêng, nhưng không trích xuất hay sửa đổi mã nguồn lõi của gói phần mềm được bảo vệ.
Không tái phân phối và thương mại hoá: Nghiêm cấm mọi hành vi sao chép, chia sẻ công khai, phát tán, bán lại hoặc cấp phép lại nội dung kỹ năng được bảo vệ (nguyên bản hoặc đã chỉnh sửa) cho bên thứ ba dưới bất kỳ hình thức nào.
Miễn trừ trách nhiệm đầu tư: Bộ kỹ năng được cung cấp như tài liệu và công cụ kỹ thuật hỗ trợ nghiên cứu cá nhân, không cấu thành tư vấn tài chính hay khuyến nghị mua bán chứng khoán. Khi làm việc cùng trợ lý AI, người dùng có trách nhiệm tự kiểm chứng dữ liệu và kết quả tính toán trước khi đưa ra quyết định của riêng mình.
Bảo vệ quyền sở hữu trí tuệ: Mọi hành vi vi phạm thoả thuận cấp phép sẽ dẫn đến việc thu hồi quyền truy cập khoá API và chấm dứt giấy phép sử dụng theo quy định.

Lịch sử cập nhật

[1.2.0] - Bổ sung kỹ năng git-master từ cấp Bronze trở lên; bổ sung đầy đủ solution-architect và migration-assistant vào bảng danh mục; chuẩn hoá mô tả của toàn bộ 17 kỹ năng theo đúng phạm vi thực tế.
[1.1.0] - Bổ sung bước xác định thế hệ thư viện (thế hệ 5 hay dòng cũ 3.x/4.x) trước khi cài đặt, đăng nhập, import hay gọi load_skill().
[1.0.0] - Khởi tạo tài liệu điều phối kỹ năng.