Vnstock Logo

Lưu trữ dữ liệu, đọc BCTC và tái lập mã nguồn

Cộng đồngvnstock_mcp v1.0.0

Mục lục

Tám công cụ research_* mở sẵn ở bản Cộng đồng và không cần khóa nguồn nào. Mỗi lần trợ lý AI gọi công cụ thành công, máy chủ ghi một dòng nhật ký gồm đoạn mã Python tương đương, số dòng, danh sách cột và nguồn gốc dữ liệu. Bạn đọc lại được, lưu được bảng gốc và xuất cả buổi làm việc thành kịch bản Python để tự chạy.

Quy trình gồm bốn bước: lấy dữ liệu (từ tệp trên máy hoặc từ nguồn đã có khóa) → nối sang bước tính bằng call_id → lưu bảng cần giữ → xuất kịch bản Python của cả phiên. Không phải chép số liệu từ khung trò chuyện sang tệp mã.

1. Thư mục nghiên cứu (~/vnstock_research)

Mặc định mọi tệp nằm ở ~/vnstock_research (đổi bằng biến VNSTOCK_MCP_WORKSPACE):

Text
~/vnstock_research/
  journal/<phiên>.jsonl          # Một dòng nhật ký cho mỗi lần gọi công cụ thành công
  data/<tên>.csv|parquet|json    # Bảng do research_save lưu, kèm tệp <tên>.meta.json
  scripts/<phiên>.py             # Kịch bản Python do research_journal xuất

Gõ vnstock-mcp workspace để xem các bảng và kịch bản đã có. Muốn tắt ghi nhật ký xuống đĩa, đặt VNSTOCK_MCP_JOURNAL=0.

2. Nhật ký phiên và kịch bản Python

Công cụViệc làm
research_journal(method="list")Liệt kê các bước đã chạy trong phiên: call_id, tên công cụ, mã Python rút gọn, số dòng, nguồn gốc.
research_journal(method="script")Ghép cả phiên thành một kịch bản Python; thêm save=true để ghi tệp .py vào scripts/.
research_save(call_id, name)Ghi trọn mọi dòng của bảng (không bị cắt ở 60 dòng hiển thị) vào data/ dạng csv hoặc parquet; kết quả mô hình ghi dạng json.
research_datasetsLiệt kê bảng đã lưu và đoạn mã đã tạo ra từng bảng.

Kịch bản xuất ra giữ đúng thứ tự phụ thuộc: bước sau tham chiếu kết quả bước trước qua biến c1, c2… hoặc tên bảng đã lưu. Ví dụ một phiên chỉ dùng tệp trên máy:

Python
import pandas as pd
import vnstock
import vnstock_quant as vq

vnstock.compat.use("v6")

# c1 · research_import · 250 dòng
c1 = pd.read_csv("/Users/<tên_máy>/data/fpt_ohlcv.csv")

# c2 · quant_ta · 250 dòng
c2 = vq.ta.compute(c1, "rsi", length=14)

Hai lưu ý khi tự chạy lại kịch bản:

  • Khoảng thời gian tương đối như length="1Y" tính lùi từ ngày chạy lại. Muốn cố định khung lịch sử, đổi sang start và end.
  • Bước nào lấy dữ liệu từ nguồn thì kịch bản gọi đúng source đã dùng, nên máy chạy lại cũng cần khóa của nguồn đó (vnstock keys set <nguồn>).

3. Nạp bảng riêng từ máy (research_import)

research_import đọc tệp có sẵn trên máy (CSV tải từ nơi khác, bảng Excel tự tổng hợp, tệp Parquet) vào phiên và cấp call_id để quant_ta, quant_backtest tính tiếp như bảng lấy từ vnstock. Công cụ chỉ đọc tệp cục bộ, không nhận đường dẫn internet. Đây là cách làm việc chính khi bạn chưa có khóa nguồn nào.

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_ta(indicator="rsi", length=14, data="c1")
Tham sốÝ nghĩa
pathTệp .csv, .tsv, .txt, .xlsx, .xls, .parquet hoặc .json trên máy; tối đa 200 MB (đổi bằng VNSTOCK_MCP_IMPORT_MB).
columnsÁnh xạ tên cột trong tệp sang tên chuẩn: time, open, high, low, close, volume.
sheetRiêng tệp Excel: tên hoặc số thứ tự trang tính.
sep, thousands, decimalRiêng tệp CSV: ký tự tách cột, tách hàng nghìn, dấu thập phân. Số kiểu Việt Nam 1.234,5 thì truyền thousands=".", decimal=",".
dayfirsttrue khi ngày viết theo thứ tự ngày/tháng/năm (31/12/2025).

Để không đọc sai số liệu một cách âm thầm:

  • Cột giá còn là chuỗi sau khi đọc thì công cụ dừng và gợi ý chỉnh thousands, decimal, không tự ép kiểu.
  • Cột time được chuyển về kiểu thời gian; bảng chưa xếp theo thời gian thì được xếp tăng dần và thao tác đó ghi vào code.
  • Ngày trùng, ô giá trống, có giá mà thiếu thời gian đều được liệt kê trong warnings.
  • Truyền tham số của định dạng khác (sheet cho CSV, sep cho Parquet) thì báo lỗi rõ ràng.

provenance của bảng nhập ghi đường dẫn tệp và 12 ký tự đầu của mã băm SHA-256, để biết tệp gốc có bị sửa sau lần nhập không.

4. Đọc báo cáo tài chính từ tệp PDF

Cài thêm vnstock-mcp[pdf] để trợ lý bóc tách và kiểm tra số học BCTC PDF ngay trên máy:

Công cụViệc làm
research_pdf(method="inspect")Nhận diện PDF văn bản số hay bản quét, độ lệch số trang in với số trang tệp, vị trí các trang Bảng cân đối kế toán, Kết quả kinh doanh, Lưu chuyển tiền tệ, Thuyết minh.
research_pdf(method="extract")Bóc bảng và văn bản (PDF văn bản số) hoặc xuất ảnh trang (PDF quét) để trợ lý đọc bằng thị giác.
research_bctc(method="standardize")Ánh xạ các dòng vừa bóc về từ điển VAS, kiểm phương trình cân đối kế toán.
research_bctc(method="profile"), research_bctc(method="guide")Lập hồ sơ phân tích (.md) kèm bảng kiểm số học; khung hướng dẫn đọc thuyết minh theo loại hình doanh nghiệp.
research_vasTra từ điển chỉ tiêu VAS theo 4 mẫu: sản xuất kinh doanh (DN), tổ chức tín dụng (TCTD), công ty chứng khoán (CTCK), bảo hiểm (DNPNT).

Ở bản Cộng đồng, từ điển VAS dùng cho research_vas và research_bctc là bản rút gọn: ba báo cáo chính chỉ giữ chỉ tiêu cấp 1, không có phần thuyết minh. Từ điển được tải từ vnstocks.com qua một phong bì có chữ ký số và chỉ giữ trong bộ nhớ của máy chủ trong phiên.

5. Mẫu quy trình dựng sẵn (MCP Prompts)

Trên ứng dụng AI hỗ trợ MCP Prompts, bản Cộng đồng có sẵn mẫu bctc_deep_dive: đọc một tệp BCTC PDF trên máy từ đầu đến cuối (khảo sát trang, bóc bảng, chuẩn hóa về VAS, kiểm số học, lập hồ sơ phân tích) và kết thúc bằng kịch bản Python. Mẫu nào cần công cụ chưa mở trên máy thì tự ẩn: market_overview và macro_dashboard hiện khi nguồn bạn đã lưu khóa hỗ trợ đủ các công cụ mà mẫu cần; bản Mở rộng có thêm study_stock và reproducible_study.

Bước tiếp theo