Chuyển từ bản 0.5
Mục lục
Trang này viết cho vnstock_mcp v1.0.0rc1, bản thử nghiệm. Tên hàm, tham số và cột dữ liệu có thể còn đổi trước ngày phát hành; khi cài, ghi rõ số phiên bản như ở trang Cài đặt. Bản đang phát hành chính thức là v0.4.0, xem tài liệu bản đó.
Trang này dành cho người đang dùng vnstock-mcp 0.5.0, chạy trên vnstock thế hệ 5. Bản 1.0.0rc1 chạy trên
vnstock 6. Ý tưởng cốt lõi giữ nguyên: trợ lý gọi đúng hàm của thư viện, nối bước bằng call_id, ghi mỗi bước thành
mã Python, xuất script tái lập. Phần đổi nhiều nhất là cách dữ liệu đến: thế hệ 6 truy xuất Open API bằng khoá bạn
đăng ký ở từng nguồn, và bạn chọn nguồn cho mỗi lời gọi.
Thứ tự nên làm
- Cài bản
1.0.0rc1vào một môi trường ảo riêng, giữ nguyên môi trường đang chạy bản 0.5. - Đăng ký khoá ở nguồn bạn định dùng, cất bằng
vnstock keys set <nguồn>. - Lưu quy tắc nguồn mặc định:
vnstock-mcp sources use <nguồn chính> <nguồn dự phòng>. - Chạy
vnstock-mcp doctor, rồivnstock-mcp --setup <ứng dụng> --writetừ môi trường mới để ứng dụng trỏ sang bản mới. - Khởi động lại ứng dụng AI, thử vài câu hỏi quen thuộc, đối chiếu với bản cũ trước khi bỏ bản 0.5.
Cài cạnh bản 0.5
vnstock-mcp 1.0.0rc1 kéo theo vnstock 6, cùng tên gói với vnstock thế hệ 5. Cài vào môi trường đang chạy
bản 0.5 sẽ thay cả hai.
# môi trường mới cho thế hệ 6
python -m venv ~/.venv_vnstock6 && source ~/.venv_vnstock6/bin/activate
pip install -U --extra-index-url https://vnstocks.com/api/packages \
"vnstock-mcp[quant]==1.0.0rc1" "vnstock==6.0.0rc3" "vnstock-oapi==0.1.0rc2"
# môi trường cũ: ghim bản 0.5 để không bị nâng nhầm
pip install "vnstock-mcp<1"Cấu hình của ứng dụng AI trỏ tới đường dẫn tuyệt đối của lệnh vnstock-mcp. Muốn quay lại bản 0.5 thì chạy
vnstock-mcp --setup <ứng dụng> --write từ môi trường cũ; --write sao lưu tệp cấu hình trước khi ghi. Tài khoản
Vnstock dùng chung, không phải đăng nhập lại.
Điều gì giữ, điều gì đổi
| Bản 0.5 | Bản 1.0.0rc1 | |
|---|---|---|
| Thư viện dữ liệu | vnstock thế hệ 5, cài riêng | vnstock 6 và vnstock-oapi, là phụ thuộc bắt buộc |
| Dữ liệu đến từ đâu | Theo cấp tài khoản Vnstock | Open API của nguồn, bằng khoá của bạn. Dữ liệu không phân cấp |
| Chọn nguồn | Thư viện có nguồn mặc định | Không có nguồn mặc định: tham số source trên mọi tool dữ liệu, hoặc quy tắc bạn lưu |
| Tool hiện ra | Theo cấp tài khoản | Tool dữ liệu theo khoá nguồn trên máy; tool tính toán theo cấp quyền của vnstock_quant |
vnstock_quant | Cài riêng, bản 0.x | Extra [quant], bản 1.0.0rc1 |
| Dòng lệnh | Chỉ có tham số --doctor, --setup, --profile… | Thêm lệnh onboard, status, doctor, setup, sources, tools, call, workspace, serve và giao diện tương tác. Tham số cũ vẫn dùng được |
| Kết quả | call_id, code, provenance, các dòng gần nhất | Như cũ, thêm warnings (cảnh báo của thư viện). code dài được rút gọn trong câu trả lời, nhật ký giữ đủ |
| Lời gọi quá thời gian | Báo hết giờ; gọi lại khi phép tính cũ chưa xong sẽ gửi thêm yêu cầu tới nguồn | StillRunning: gọi lại cùng tham số thì chờ đúng phép tính đang chạy, không gửi thêm yêu cầu |
| Thư mục nghiên cứu | ~/vnstock_research | Như cũ |
| Hồ sơ tool | minimal, research, data, full | Như cũ |
| Biến môi trường | VNSTOCK_MCP_* | Như cũ, thêm VNSTOCK_MCP_IMPORT_MB |
| Hạn dùng bản phát hành | 30 ngày với bản thử nghiệm, 365 ngày với bản chính thức |
Tool thêm
| Tool | Làm gì |
|---|---|
quant_backtest | Chạy thử chiến lược theo luật thị trường Việt Nam: một mã, danh mục, dò tham số, walk-forward, Monte Carlo |
quant_returns | Bảng lợi suất nhiều mã, đầu vào cho tối ưu danh mục |
quant_prices | Giá điều chỉnh theo sự kiện doanh nghiệp |
quant_micro | Vi cấu trúc trên dữ liệu khớp lệnh |
market_global_index | Chỉ số chứng khoán quốc tế |
research_sources | Nguồn dùng được trên máy, nguồn đọc được từng loại dữ liệu |
research_import | Nhập bảng từ tệp trên máy |
research_pdf, research_bctc, research_vas | Đọc và chuẩn hoá báo cáo tài chính dạng PDF, tra từ điển VAS |
quant_ta, quant_fa nhận thêm source; quant_fa nhận thêm price_source và estimate_shares. quant_portfolio
và quant_backtest nhận refs để lấy tham số từ kết quả trước (Tính toán và chạy thử chiến
lược).
Tool bỏ hoặc tạm chưa hiện
| Bản 0.5 | Bản 1.0.0rc1 | Dùng thay |
|---|---|---|
research_normalize, research_benchmark | Bỏ | Chuẩn hoá dữ liệu là việc của vnstock 6. Bảng lấy từ nơi khác: nhập bằng research_import với columns |
research_universe | Bỏ | research_vas cho từ điển chỉ tiêu VAS |
macro_economy, macro_currency, macro_global | Chưa hiện | Chưa có nguồn Open API nào đọc được |
insights_flow, insights_sentiment | Chưa hiện | Khối ngoại, tự doanh: market_equity foreign_flow, proprietary_flow; với chỉ số: market_index |
retail_exchange_rate | Chưa hiện | Chưa có nguồn Open API nào đọc được |
Tool chưa hiện vẫn có trong mã; khi vnstock 6 có kết nối mới, bản sau sẽ tự mở.
Giá trị method đổi
| Tool | Bỏ | Thêm |
|---|---|---|
fundamental_equity | ratio, note, financial_health | Chỉ số tài chính tính bằng quant_fa, có công thức |
reference_company | officers, subsidiaries, affiliate, capital_history | |
reference_equity | price_limits, status | |
reference_market | Gọi không kèm method | status, sessions, trading_days |
reference_fund | fee_structure, reports | |
market_equity | odd_lot | active_flow, expected_price, summary |
market_index | foreign_flow, proprietary_flow | |
market_etf | summary | |
market_board | odd_lot | foreign_room |
market_fund | holdings, asset_allocation, industry_allocation, dividends |
Prompt
| Bản 0.5 | Bản 1.0.0rc1 |
|---|---|
study_stock, reproducible_study | Giữ |
market_overview, macro_dashboard | Bỏ, vì dữ liệu vĩ mô và thống kê thị trường chưa có nguồn Open API |
Thêm bctc_deep_dive: đọc báo cáo tài chính PDF trên máy |
Script và bảng đã lưu
- Bảng đã lưu trong
~/vnstock_research/data/đọc được ở bản mới, theo tên (data="ten_bang"). - Script tái lập của bản 0.5 gọi
vnstockthế hệ 5 và không ghi nguồn. Chạy chúng trong môi trường cũ. Script của bản mới ghi rõsourcecho từng lời gọi. - Nhật ký của hai bản nằm chung
journal/, mỗi phiên một tệp.
Dữ liệu và kết quả có thể khác
- Bảng của thế hệ 6 dựng lại từ phản hồi Open API của nguồn bạn chọn. Một số cột thế hệ 5 có thì thế hệ 6 không có khi
không nguồn chính thức nào gửi;
warningsghi mã thay đổi (SCH-…) và đường dẫn tới mô tả. - Hai nguồn có thể trả số khác nhau cho cùng một mã. Mã tương đương ghi nguồn để bạn biết số đến từ đâu.
- Chỉ số định giá (P/E, P/B, EPS) của
quant_facần số cổ phiếu; Open API chưa có số này theo ngày, nên cầnestimate_shares=truevà là số ước tính.
So sánh chi tiết thư viện giữa hai thế hệ: Chuyển đổi của vnstock 6.