Nghiên cứu tái lập

Câu trả lời trong khung chat khó kiểm lại. vnstock-mcp giữ lại bằng chứng: mỗi lần trợ lý gọi tool thành công, máy chủ ghi một dòng nhật ký gồm mã Python tương đương, số dòng, cột và nguồn gốc. Bạn đọc lại, xuất thành script và tự chạy.

Thư mục nghiên cứu

Mặc định ~/vnstock_research, đổi bằng biến VNSTOCK_MCP_WORKSPACE:

Text

~/vnstock_research/
  journal/<phiên>.jsonl          một dòng cho mỗi lần gọi thành công
  data/<tên>.csv|parquet|json    bảng do research_save ghi, kèm <tên>.meta.json
  scripts/<phiên>.py             script tái lập do research_journal ghi

vnstock-mcp workspace liệt kê bảng đã lưu và script. Tắt ghi nhật ký ra đĩa bằng VNSTOCK_MCP_JOURNAL=0.

Nhật ký và script

Tool	Làm gì
`research_journal(method="list")`	Các bước của phiên: `call_id`, tool, mã tương đương (rút gọn), số dòng, nguồn gốc
`research_journal(method="script")`	Ghép cả phiên thành một script Python; `save=true` ghi ra `scripts/`
`research_save(call_id, name)`	Ghi đủ một bảng (không bị cắt ở 60 dòng) ra `data/`, dạng `csv` hoặc `parquet`; kết quả mô hình ghi dạng JSON
`research_datasets`	Bảng đã lưu và mã đã tạo ra từng bảng

Script giữ đúng chuỗi phụ thuộc: bước sau tham chiếu bước trước bằng tên biến c1, c2…, hoặc bằng tên bảng bạn đã lưu. Một đoạn script:

Python

import pandas as pd
from vnstock import Market, cite
import vnstock_quant as vq

# c1 · market_equity · 2026-11-06T13:58:31+07:00 · 249 dòng
c1 = Market().equity("FPT").ohlcv(length="1Y", source="ssi")

# c4 · quant_ta · 2026-11-06T13:58:33+07:00 · 249 dòng
c4 = vq.ta.compute(c1, "rsi", length=14)

Hai điều cần biết khi chạy lại:

length="1Y" tính lùi từ ngày chạy. Cần cố định khung thời gian thì thay bằng start, end.
Script gọi đúng nguồn đã dùng, nên máy chạy lại cần khoá của nguồn đó (vnstock keys set <nguồn>).

Bảng của bạn

research_import nhập một bảng từ tệp có sẵn trên máy, trả call_id để các tool quant_* tính tiếp như bảng lấy qua vnstock. Tool chỉ đọc tệp trên máy, không nhận đường dẫn web.

Text

research_import(path="~/Downloads/gia_fpt.csv", sep=";", decimal=",", dayfirst=true,
                columns={"Ngày": "time", "Đóng cửa": "close", "Mở": "open", "Cao": "high",
                         "Thấp": "low", "KL": "volume"})                       → c1
quant_risk(method="sharpe_ratio", data="c1")

Tham số	Nghĩa
`path`	Tệp `.csv`, `.tsv`, `.txt`, `.xlsx`, `.xls`, `.parquet`, `.json`. Tối đa 200 MB (`VNSTOCK_MCP_IMPORT_MB`)
`columns`	Đổi tên cột của tệp sang tên `quant_*` dùng: `time`, `open`, `high`, `low`, `close`, `volume`
`sheet`	Excel: tên hoặc số thứ tự trang tính
`sep`, `thousands`, `decimal`	CSV: ký tự phân cách cột, hàng nghìn, thập phân. Số kiểu `1.234,5` thì `thousands="."`, `decimal=","`
`dayfirst`	Ngày viết kiểu `31/12/2025`

Tool kiểm chặt để số không bị đọc sai mà không ai biết:

cột giá còn là chữ thì báo lỗi kèm gợi ý thousands, decimal, không tự ép kiểu;
cột time đọc thành ngày; bảng chưa theo thứ tự thì được sắp tăng dần, và việc sắp được ghi vào mã tương đương;
ngày trùng, ô giá trống, có giá mà thiếu time hiện trong warnings;
tham số dùng sai loại tệp (sheet cho CSV, sep cho Parquet) bị báo lỗi, không bị bỏ qua.

provenance ghi đường dẫn tệp và 12 ký tự đầu của mã băm SHA-256: số liệu là của bạn, không gán cho nguồn nào. Mã băm cho biết tệp có bị sửa sau lần nhập không. Mã tương đương đọc lại đúng tệp đó với cùng tham số.

Báo cáo tài chính dạng PDF

Cần cài vnstock-mcp[pdf]. Bạn tự tải báo cáo về máy; các tool chỉ đọc tệp có sẵn, không tải gì từ web.

Tool	Làm gì
`research_pdf(method="inspect")`	Tệp là văn bản số hay bản quét, độ lệch giữa số trang in và trang thật, trang chứa bảng cân đối, kết quả kinh doanh, lưu chuyển tiền tệ, thuyết minh
`research_pdf(method="extract")`	Bóc bảng, văn bản (PDF số) hoặc xuất ảnh trang (PDF quét) để trợ lý đọc bằng thị giác
`research_bctc(method="standardize")`	Ánh xạ chỉ tiêu về từ điển VAS, kiểm phương trình kế toán và tổng con bằng cha; bảng `format="wide"` nạp thẳng cho `quant_fa`
`research_bctc(method="profile")`	Hồ sơ phân tích (`.md`) kèm bảng kiểm số học và thuyết minh
`research_bctc(method="guide")`	Khung bóc thuyết minh theo loại hình doanh nghiệp
`research_vas`	Tra từ điển chỉ tiêu VAS theo loại hình: doanh nghiệp (`DN`), ngân hàng (`TCTD`), công ty chứng khoán (`CTCK`), bảo hiểm (`DNPNT`)

Từ điển VAS được nạp từ vnstocks.com qua một phong bì có chữ ký số và chỉ giữ trong bộ nhớ của máy chủ.

Prompt dựng sẵn

Ứng dụng AI hỗ trợ prompt MCP sẽ thấy ba prompt:

Prompt	Dùng khi
`study_stock`	Tìm hiểu một mã: giá, báo cáo tài chính, chỉ số, rủi ro, có mã tương đương cho từng con số
`reproducible_study`	Trả lời một câu hỏi nghiên cứu và kết thúc bằng script tái lập
`bctc_deep_dive`	Đọc một báo cáo tài chính PDF trên máy: khảo sát, bóc bảng, chuẩn hoá, kiểm số học, lập hồ sơ