FinLens for Visual Studio Code

Dữ liệu chứng khoán Việt Nam, workflow Python, Jobs cục bộ và biểu đồ kỹ thuật trong cùng một workspace.

FinLens đưa quy trình nghiên cứu dữ liệu vào ngay trong VS Code: tìm đúng dataset, chèn lời gọi Python, kiểm tra đơn vị, xem trước kết quả và mở biểu đồ mà không phải chuyển liên tục giữa editor, tài liệu và trình duyệt.

Điểm nổi bật

Workspace FinLens trong thanh bên

Trang chủ tập trung trạng thái tài khoản, môi trường Python, phiên bản SDK và API key.
Dữ liệu tổ chức bề mặt API theo nhóm nghiệp vụ, có tìm kiếm và mô tả đơn vị.
Jobs lên lịch chạy file Python ngay trong workspace và giữ lại lịch sử output.
Click một job sẽ mở Jobs Studio trong Editor area để xem cấu hình và các lần chạy, thay vì phải đi qua chuỗi hộp thoại nhập liệu.
Các hành động thường dùng nằm ngay trên thanh tiêu đề và trong Command Palette.

Chèn code Python theo ngữ cảnh

Nhấn Ctrl+Alt+F (Cmd+Alt+F trên macOS) để chọn dataset và mã chứng khoán.
Tìm mã bằng ticker hoặc tên doanh nghiệp, kể cả khi gõ không dấu.
Hoạt động trong file .py và notebook.
Tự bổ sung import finlens và client = finlens.client() khi cần.
Không ghi API key trực tiếp vào code được sinh ra.
Khi lọc báo cáo theo quý, chọn Q1-Q4 thay vì nhập số thủ công. Extension sinh quarters=[...] và tự đặt period="quarterly" để tránh request mâu thuẫn.

Xem trước dữ liệu trong Editor

Mở bảng dữ liệu trực tiếp từ cây Dữ liệu mà chưa cần chạy file Python.
Sắp xếp, lọc và chọn số dòng hiển thị.
Header thể hiện đơn vị của từng cột để hạn chế nhầm VND, nghìn VND, điểm chỉ số hoặc khối lượng.
Chèn lại đúng lời gọi Python tương ứng từ panel xem trước.
Với Báo cáo tài chính, Preview yêu cầu chọn loại báo cáo và kỳ dữ liệu để request trực tiếp tới API có cùng ý nghĩa với lời gọi Python được sinh ra.

Biểu đồ kỹ thuật

Mở biểu đồ trong Editor area, không chiếm diện tích của thanh bên.
Panel biểu đồ là singleton: mở mã khác sẽ tái sử dụng tab hiện tại.
Giữ lại mã và khung thời gian khi phiên đăng nhập hết hạn.
Khi đăng xuất hoặc JWT không còn hợp lệ, iframe biểu đồ bị hủy và panel chuyển sang màn hình khóa; đăng nhập lại sẽ tiếp tục đúng ngữ cảnh trước đó.
Kiến trúc đã chuẩn bị để bổ sung thêm nhiều loại biểu đồ ngoài TradingView.

Jobs Python trong VS Code

Tạo lịch chạy một lần, theo phút/giờ, hằng ngày, hằng tuần hoặc cron 5 trường.
Chọn job trong sidebar để mở Jobs Studio trong Editor area: toolbar chạy/dừng/tạm dừng/xóa, tab Cấu hình và tab Lần chạy tách biệt.
Chạy bằng đúng Python interpreter đang được VS Code chọn, không dùng shell.
Xem output trực tiếp ở Output > FinLens Jobs và mở lại output của các lần chạy gần đây.
Lịch chỉ hoạt động khi VS Code và workspace đang mở; không chạy bù thời điểm đã lỡ.
Job yêu cầu đăng nhập FinLens và workspace đáng tin cậy. Đăng xuất, JWT hết hạn hoặc workspace mất trust sẽ dừng tiến trình đang chạy và hủy các lịch còn chờ.
API key chỉ được truyền vào tiến trình khi bạn chọn cho phép; không được lưu trong cấu hình job hoặc output.
Mỗi job đã lưu có thể gửi trạng thái kết thúc đến Telegram và Discord; các kênh hoạt động độc lập và có nút gửi thử ngay trong Jobs Studio.

Thông báo Telegram và Discord

Trong Thông báo kết quả, kết nối từng kênh cho job đang mở:

Telegram cần bot token và Chat ID hoặc @username nhận thông báo.
Discord cần Incoming Webhook URL của kênh nhận thông báo.

FinLens gửi tên job, trạng thái, nguồn kích hoạt, thời điểm và kết quả ngắn sau mỗi lần chạy kết thúc. Bot token, Chat ID và webhook URL được lưu riêng theo job trong VS Code SecretStorage; chúng không nằm trong workspace, output, lịch sử chạy hay code Python. Output của script và FinLens API key cũng không được gửi đến các kênh này.

Tham số truyền cho script

Trường Tham số dòng lệnh của script không phải là cấu hình của FinLens. Jobs chỉ chạy lệnh theo dạng:

python script.py <tham số của bạn>

Chỉ nhập tham số khi file Python của bạn tự đọc và xử lý chúng. Ví dụ --date và today được truyền nguyên vẹn thành python script.py --date today; ý nghĩa của chúng do script.py quyết định. Nếu file không hỗ trợ tham số dòng lệnh, để trống trường này.

Hỗ trợ khi viết code

Gợi ý ticker theo đúng tham số và nhóm dữ liệu đang gọi.
Hover trên biến kết quả để xem cấu trúc cột và đơn vị.
Cảnh báo các giá trị interval dễ nhầm, ví dụ 1m.
Bổ sung cho Pylance, không thay thế hoặc tạo completion trùng lặp.

Bắt đầu

Cài extension từ Visual Studio Marketplace hoặc chạy:
```
code --install-extension finlens.finlens
```
Mở biểu tượng FinLens trên Activity Bar và đăng nhập tài khoản FinLens.
Chạy FinLens: Chọn môi trường Python để chọn môi trường đã cài SDK.
Mở file Python hoặc notebook, nhấn Ctrl+Alt+F và chọn dữ liệu cần dùng.
Bấm biểu tượng bảng trong cây Dữ liệu để xem trước, hoặc chọn Mở biểu đồ để phân tích mã trong Editor area.
Khi cần tự động hóa trong phiên VS Code hiện tại, mở Jobs và chọn biểu tượng tạo mới để lên lịch một file Python trong workspace.

Để chạy code đã sinh trong Python:

pip install finlens

Đăng nhập và API key

FinLens sử dụng hai loại thông tin xác thực cho hai mục đích khác nhau:

Thông tin	Mục đích	Nơi lưu
Phiên tài khoản JWT	Trang chủ, Dữ liệu và biểu đồ	VS Code SecretStorage
FinLens API key	Gọi API dữ liệu và xem trước kết quả	VS Code SecretStorage

Biểu đồ chỉ nhận JWT của tài khoản, không nhận API key. Extension có thể cấp và lưu API key sau khi đăng nhập; bạn cũng có thể dùng lệnh FinLens: Nhập API key.

Lệnh thường dùng

Lệnh	Chức năng
`FinLens: Đăng nhập`	Đăng nhập bằng email hoặc Google
`FinLens: Chèn code…`	Chọn dataset và chèn lời gọi Python
`FinLens: Mở biểu đồ`	Chọn mã và mở workspace biểu đồ
`FinLens: Mở Jobs`	Mở danh sách job trong sidebar
`FinLens: Tạo job Python`	Mở Jobs Studio để cấu hình file Python và lịch chạy
`FinLens: Chọn môi trường Python`	Chọn interpreter dùng SDK FinLens
`FinLens: Kiểm tra cấu hình`	Hiển thị trạng thái SDK, API và môi trường
`FinLens: Đặt lại bố cục thanh bên`	Khôi phục Trang chủ và Dữ liệu về bố cục mặc định

Cấu hình chính

Setting	Mặc định	Mô tả
`finlens.python.features`	`full`	Bật đầy đủ gợi ý và chẩn đoán, chỉ chẩn đoán, hoặc tắt
`finlens.snippet.emitPreamble`	`true`	Tự thêm import và khởi tạo client khi cần
`finlens.snippet.unitsComment`	`true`	Thêm comment nhắc đơn vị vào code sinh ra
`finlens.preview.defaultRows`	`10`	Số dòng mặc định trong bảng xem trước
`finlens.sessionChannel`	`desktop`	Tách phiên VS Code khỏi phiên trình duyệt FinLens

Yêu cầu

Visual Studio Code 1.90.0 trở lên.
Python 3.11 trở lên và package finlens để chạy code được sinh ra.
Tài khoản FinLens và kết nối internet cho Dữ liệu, xem trước và biểu đồ.

Bảo mật

JWT và API key được lưu bằng VS Code SecretStorage, không nằm trong workspace settings.
Code được sinh không chứa API key.
URL iframe biểu đồ chỉ chấp nhận HTTPS, hoặc HTTP trên localhost khi phát triển.
Workspace không được phép ghi đè URL biểu đồ vì origin đó là nơi nhận JWT.
Khi phiên kết thúc, iframe biểu đồ bị tháo khỏi DOM thay vì chỉ bị che bằng CSS.
Jobs chỉ spawn interpreter với mảng tham số, không đi qua shell, và chỉ chạy file .py nằm trong workspace đã được tin cậy.

Lộ trình

Các phiên bản tiếp theo dự kiến mở rộng workspace với nhiều loại biểu đồ, watchlist, bảng giá, tin tức AI, báo cáo phân tích của công ty chứng khoán và báo cáo chuyên sâu của FinLens.

Hỗ trợ và phát triển

Truy cập finlens.vn để xem tài liệu và các kênh hỗ trợ.
Dùng lệnh FinLens: Kiểm tra cấu hình và mở Output > FinLens khi cần chẩn đoán.
Lịch sử thay đổi được hiển thị trong tab Changelog của extension trên Marketplace.