Builder Contract và Quyền Sở Hữu Giai Đoạn
Hợp đồng tác giả quan trọng nhất trong PyneScript — giai đoạn nào sở hữu gì, và điều gì không bao giờ được vượt ranh giới giai đoạn.
Builder Contract và Quyền Sở Hữu Giai Đoạn#
Indicator contract#
- Bắt buộc:
indicator(...). - Bắt buộc:
build_indicator_frame(df, params)hoặc đường dẫn frame builder tương đương được runtime sử dụng. - Tùy chọn: khai báo plot tĩnh như
plot,hline,fill,plotshape,plotcandle. - Tùy chọn:
build_visuals(frame, params=None, ctx=None)cho visuals dạng đối tượng hoặc ATK bridge tùy chỉnh.
Strategy contract#
- Bắt buộc:
strategy(...). - Bắt buộc:
build_signal_frame(df, params). - Khuyến nghị:
build_trade_frame(signal_df, params, styles)trả vềbuild_mapped_trade_frame(signal_df). - Tùy chọn: khai báo visual hoặc
build_visuals(...), nhưng chỉ để render dữ liệu đã được chuẩn bị sẵn.
Bảng quyền sở hữu giai đoạn#
| Giai đoạn | Những gì thuộc về đây | Những gì không được xảy ra ở đây |
|---|---|---|
build_indicator_frame | Mọi tính toán indicator series, phân giải source, xử lý warmup, chuẩn bị visual_* theo hàng, cấu hình attrs tĩnh. | Các lệnh vẽ cuối cùng thông qua ctx.*. |
build_signal_frame | Logic signal, logic filter, các trường thực thi trade-frame chuẩn, chuẩn bị strategy visuals. | Chuẩn hóa order schema ngoài các helper chỉ ánh xạ. |
build_trade_frame | Chuẩn hóa chỉ ánh xạ, thường là build_mapped_trade_frame(...). | ta.*, request.*, rolling window, dataframe grouping, tính lại signal. |
build_visuals | Ánh xạ chỉ để render vào ctx.* hoặc ctx.atk.*. | Thay đổi frame, tính toán TA, lưu payload động full-frame cũ trong frame.attrs. |
Luồng dữ liệu nên chảy như thế nào#
Input -> hợp nhất params -> frame builder -> ánh xạ visual. Input định nghĩa giá trị mặc định. Params runtime ghi đè chúng. Frame builder tạo các column dataframe thuần. Chỉ sau khi các column đó tồn tại thì khai báo hoặc build_visuals mới nên sử dụng chúng.
Tại sao tách giai đoạn quan trọng#
Khi tính toán, trade mapping và render được trộn lẫn, script trở nên khó debug, khó phân chia và khó để runtime giữ nhất quán qua các lần tải lại chart. Việc tách giai đoạn không phải là lời khuyên về phong cách; đó là hợp đồng ổn định.
Library contract#
- Bắt buộc:
library(...). - Khuyến nghị: export các helper nhỏ, tái sử dụng được hoặc enum type.
- Không mong đợi:
build_indicator_frame,build_signal_framehoặc chart visuals. - Import thông qua
import_library(...)hoặclibrary_import(...).
Giữ code library xác định, hẹp và tái sử dụng được. Nó nên sở hữu logic helper như phân giải length, gán nhãn bias, helper chuyển đổi hoặc tiện ích signal dùng chung — không phải chart rendering hoặc strategy mapping.
Hướng dẫn đặt giai đoạn#
| Nếu bạn cần... | Đặt ở đây | Lý do |
|---|---|---|
Chọn giữa open, close, hl2 hoặc column source do người dùng chọn | build_indicator_frame hoặc build_signal_frame | Chọn source là phần của tính toán, không phải render. |
| Tính EMA, ATR, BBands, MACD hoặc bộ lọc xu hướng MTF | build_indicator_frame hoặc build_signal_frame | Mọi công việc TA và request thuộc về giai đoạn tính toán. |
Xuất entry_price, sl, tp | build_signal_frame | Strategy nên chuẩn bị đầy đủ các trường thực thi trước trade mapping. |
| Chuyển đổi column trade-frame chuẩn sang schema chuẩn hóa của runtime | build_trade_frame | Giai đoạn này tồn tại để chuẩn hóa, không phải cho logic trading mới. |
| Tạo dashboard table, zone box hoặc gói đối tượng từ payload đã chuẩn bị | build_visuals | Đây là render thuần túy dữ liệu đã được chuẩn bị sẵn. |
| Lưu trữ gói style tĩnh như màu table, chiều rộng, header hoặc label template | frame.attrs | Cấu hình tĩnh an toàn ở đây vì không phụ thuộc vào độ dài slice hiện tại. |
| Lưu trữ anchor x/y hàng cuối, đuôi dự kiến hoặc chỉ số phụ thuộc slice | Không nên lưu trữ hàng loạt trong frame.attrs | Các giá trị đó có thể bị lỗi thời khi runtime chỉ truyền một slice vào build_visuals. |
Quan trọng: Nếu bạn dùng frame.attrs cho visuals dạng đối tượng, chỉ lưu cấu hình tĩnh ở đó và tính toán giá trị động x, y, tail hoặc phụ thuộc slice từ frame thực tế được truyền vào build_visuals().
Quy tắc tác giả: chọn khai báo theo trách nhiệm runtime, không phải theo diện mạo visual. Một script vẽ arrow vẫn là indicator nếu nó không xuất các trường trade được ánh xạ. Một script có chart visuals sạch vẫn là strategy nếu mục đích của nó là ánh xạ thực thi.