页面参考 · 28 / 29
QuantCraft 文档参考
QuantCraft 附带两种互补的文档：你在 IDE 内阅读的应用内主题，以及随产品捆绑、提供更深入 API 细节的策略参考 Markdown。它们共同描述了如何编写策略、运行回测和使用 IDE。这些网页文档镜像了其中许多主题——请从简介或入门开始。
在应用中哪里阅读文档
- 在主应用中打开 QuantCraft。
- 展开右侧边栏（如果它已折叠）。
- 打开 Documentation 标签页（与 QuantCraft AI 并列）。
你会看到一个可搜索的主题索引。在搜索框中输入，可按标题、摘要或内嵌关键词（例如 on_finish、PaperAccount、chart_indicator_series）进行筛选。
点击主题卡片即可打开完整文章。使用 Back 返回索引。
主题索引（应用内）
主题分为两个部分，与 Documentation 侧边栏一致。
Getting started
| 主题 | 你将学到什么 |
|---|---|
| 基本面数据 | 财务报表数据、以日期为键的表、基本面数据如何与 K 线对齐，以及如何在策略中读取。 |
| Fama-French 因子 | 通过 fama_french.qc 获取全球月度 FF3/FF5 因子收益（Premium；没有回调参数）。 |
| 日历数据 | 股息、拆股、财报日期和申报文件（calendar 回调参数，仅限回测），以及模拟中的公司行动。 |
| 账户 | PaperAccount：回测期间提供的余额、头寸、订单、盈亏和业绩指标。 |
| 生命周期 | 回调顺序：on_init、on_bar、on_tick、可选的 on_timer（仅限前向）、on_finish——包括多标的基础知识和可选的完整序列 on_finish(bars)。 |
Reference
| 主题 | 你将学到什么 |
|---|---|
| 输入参数 | 声明 quantcraft.inputs.params、类型，以及数值如何从运行对话框（回测、批量前向、图表前向）提供。 |
| 运行预设（.qcs） | 将运行对话框的设置保存为工作区中的 .qcs 文件并重新加载。 |
| 调试 | Debug Run 与 Debug Test、断点、单步执行、调用栈和变量。 |
| AutoTrading | 算法和智能体的本地前向运行、New Bulk / Agent Bulk Run，以及监控批量／图表作业。 |
| QuantCloud | 当你的电脑关机时，在云端运行器上进行批量前向运行（桌面端用户指南）。 |
| 智能体 | Trading、Test 和 Optimization 智能体；手动或使用 AI Builder 构建节点图；暴露的参数与优化；在模拟账户上回测，通过已连接券商前向／实盘；.qca 导入／导出。 |
| QuantCraft AI | IDE 的 AI 聊天、连接模型（AI → API Providers）、筛选器工具、AI Tools、MCP 服务器，以及智能体中的 AI Prompt 节点。 |
| QuantCraft Tools | AI 可调用的内置只读市场工具（聊天、AI Prompt 节点、Test / Optimization 智能体）。 |
| OHLCV | K 线的形态（OhlcvBarView）、加载器（已连接券商与 B2）、时间范围，以及在回调中使用 K 线数据。 |
| 指标序列 | 在回测结果图表上构建 chart_indicator_series 叠加层（折线、柱状图、窗格）。 |
索引中任何尚未打开完整文章的卡片，在界面中会标注为 Soon。
应用内文档与你的工作流程的关系
在 IDE 中进行操作时，可使用这张快速对照表：
| 你想要… | 从这里开始 |
|---|---|
| 配置标的、日期、基本面数据并运行模拟 | 策略生命周期 + OHLCV；然后是运行代码（Test）和测试结果。 |
| 确定头寸规模、止损，或读取夏普／回撤 | 账户模型 |
| 让用户无需编辑代码即可调整阈值 | 输入参数 |
| 在权益图表上绘制自定义序列 | 指标序列 |
| 混用价格与申报文件／报表 | 基本面数据 |
| 混用价格与全球因子收益 | Fama-French 因子 |
| 对股息／拆股做出反应，或围绕财报日期做防范 | 日历数据——calendar 回调参数、days_to_earnings、公司行动 |
| 组合主时间周期和副时间周期 | OHLCV 与 K 线数据——Additional timeframes + rt.get_bar |
| 复用回测或前向对话框的设置 | 运行预设（.qcs） |
| 在某一行暂停并检查变量 | 调试 |
| 在你自己的机器上前向运行算法 | AutoTrading |
| 在远程运行器上运行算法 | QuantCloud |
| 用可视化节点构建自动化 | 智能体 |
应用内文章是为策略作者和 IDE 用户撰写的。这些公开文档不涵盖面向服务器运维人员的 QuantCloud 部署。
策略导入
每个导入都写成 quantcraft.*，模块名不带后缀（例如 quantcraft.inputs，而不是 quantcraft.inputs_module）。较旧的 ide.* 和 quantcraft.*_module 路径仍然可以解析，quantcraft.backtest.* 也是如此——这是该包在被重命名为 quantcraft.process.* 之前的旧名称——所以现有策略无需更改即可继续运行——但不要针对它们编写新代码。
| 主要导入 | 你可能会看到的旧路径 | 用途 |
|---|---|---|
quantcraft.process.runtime | quantcraft.backtest.runtime, ide.backtest.runtime | account、chart_indicators、qc_fundamentals、qc_fama_french、qc_calendar、get_bar（通过 import quantcraft.runtime as rt） |
quantcraft（Timeframe） | — | 用于 rt.get_bar(Timeframe.DAILY, shift=1) 的时间周期枚举（主周期和附加周期） |
quantcraft.runtime | — | 与 quantcraft.process.runtime 是同一个模块，拼写更短——使用 import quantcraft.runtime as rt 获取 rt.get_bar 和运行时句柄 |
quantcraft.timeframes | — | Timeframe 枚举（也可用 from quantcraft import Timeframe） |
quantcraft.inputs | ide.inputs_module, quantcraft.inputs_module | 来自运行对话框的 params |
quantcraft.process.ohlcv | quantcraft.backtest.ohlcv, ide.backtest.ohlcv_module, quantcraft.backtest.ohlcv_module | QcOhlcv、qc_ohlcv |
quantcraft.fundamentals | ide.fundamentals_module, quantcraft.fundamentals_module | QcFundamentals |
quantcraft.fama_french | ide.factors_module | QcFamaFrench、fama_french.qc |
quantcraft.account | quantcraft.process.account, quantcraft.backtest.account, ide.account_module, quantcraft.account_module | PaperAccount、OpenPosition |
quantcraft.process.indicator_series | quantcraft.backtest.indicator_series, ide.backtest.indicator_series_module, quantcraft.backtest.indicator_series_module | ChartIndicatorSeries、coerce_chart_time |
quantcraft.calendar_module | — | BacktestCalendar——启用日历数据时作为 calendar 回调参数传入；参见日历数据。这是唯一保留 _module 后缀的模块——不存在 quantcraft.calendar。 |
quantcraft.cross_sectional | — | 全范围的排名／z 分数——参见下文 |
quantcraft.process | — | clamp_indicator_period |
较短的重新导出也可用：quantcraft.indicator_series、quantcraft.account。对于 Fama-French，请优先使用 from quantcraft import fama_french，并在回调内部读取 fama_french.qc。
Fama-French 行访问：dataset["rows"] 是一个 YYYYMM → 值的 dict，不是列表。请使用 .row(...) 或 .rows_chronological(...)；latest_row(...) 仅限前向运行（在回测中它是前视——参见 Fama-French 因子）。不要使用 rows[0] / rows[-1]。
请勿在策略脚本中使用 quantcraft.b2.*（价格和基本面加载器背后的数据下载层）或 quantcraft.ai_assistant.* 之类的内部包——它们是内部辅助，不是策略 API。不要把 quantcraft.process.ohlcv（策略 OHLCV API）与 quantcraft.b2.ohlcv（内部数据层）混淆。
横截面辅助函数
quantcraft.cross_sectional 提供向量化的辅助函数，用于一次比较多个标的（numpy）：stack_field、latest_return、latest_sma、latest_std、latest_rsi、rank、zscore、demean、winsorize，以及 ColumnarBarArena。
import quantcraft.runtime as rt
import quantcraft.cross_sectional as xs
def on_bar(bar_index, bar, symbol=None):
syms, close = xs.stack_field(rt.qc_ohlcv_by_symbol, "close")
momentum = xs.latest_return(close, 20) # per-symbol 20-bar return
score = dict(zip(syms, xs.rank(momentum))) # rank in [0, 1]按所写内容仅适用于前向／批量运行。在回测中，
rt.qc_ohlcv_by_symbol保存着每个标的的完整加载范围，所以那里的“最新”指的是测试的最后一根 K 线——前视。在回测中，请在运行遍历 K 线时从各标的的bar收集其收盘价，并把这些数组传给辅助函数。
模块句柄与导入名称
quantcraft.process.runtime 和 quantcraft.fama_french 是模块别名，所以属性访问读取的是实时的会话值：
import quantcraft.process.runtime as rt
import quantcraft.fama_french as ff
rt.account # this run's PaperAccount
rt.chart_indicators # this run's collector
ff.qc # this run's Fama-French loader其他一切都按值重新导出名称，所以 from ... import <name> 绑定的是导入时取得的快照。
对于引擎在每次运行中分配的句柄，引擎会在加载根算法文件之后重新绑定这些名称，所以 from ... import 的形式在那里是安全的——针对它重新绑定的那些名称：
- 回测 / Debug Test：
account、chart_indicators、get_bar、qc_ohlcv、qc_ohlcv_by_symbol、qc_ohlcv_by_tf、qc_fundamentals、qc_fama_french、qc_calendar。 - **前向运行：**仅
account、qc_fundamentals和qc_fama_french——所以对chart_indicators和 OHLCV 句柄，在那里请使用rt.<name>。
# Fine in the root algo file — the engine rebinds these after loading your script
from quantcraft.process.runtime import account, qc_fundamentals, qc_fama_french拆分的辅助模块则不同：它在同一进程中的多次运行之间一直缓存在 sys.modules 中，因此导入的名称会保留首次导入时当前会话的句柄——对下一次运行（前向／批量）来说已经过时。在辅助模块中，请导入模块并使用属性访问：
# helpers/signals.py — always read through the module
import quantcraft.process.runtime as rt
def record(sym, t, value):
rt.chart_indicators.add(...) # live handle for *this* runfrom quantcraft.inputs import params 是例外：params 是一个其值每次运行都会变化的实时对象，所以 from 形式在任何地方都安全——参见输入参数。
随附的策略参考（Markdown）
对于逐行的模块行为、回调契约和引擎细节，产品还在 quantcraft-dev 捆绑包下包含了 Markdown（概念上就是“QuantCraft 策略参考”）。典型的目录如下：
| 文档 | 重点 |
|---|---|
| IMPORTS | quantcraft.* 导入路径（包括 quantcraft.cross_sectional）、仍为现有脚本解析的旧 ide.* / quantcraft.backtest.* 路径，以及模块句柄与导入名称 |
| BACKTEST_README | 回测包的高层概览 |
| BACKTEST_ENGINE | 引擎编排、配置、回调、结果载荷 |
| BACKTEST_MODULE | 来自 IDE 的 WebSocket 回测入口 |
| IDE_BACKTEST_RUNNER | 位于 Python 服务旁边的子进程运行器 |
| RUNTIME | 运行时全局变量：account、chart_indicators、get_bar / 主周期和附加周期；按会话的句柄和 rt.<name> 访问 |
| INPUTS_MODULE | 来自运行对话框的 params 连接 |
| RUN_CONFIG_QCS | .qcs 运行预设格式及跨对话框映射 |
| ACCOUNT_MODULE | PaperAccount 交易 API、佣金／滑点 |
| OHLCV_MODULE | QcOhlcv 加载器、回调中的 bar、副时间周期 |
| INDICATOR_SERIES_MODULE | 图表序列载荷和辅助函数 |
| FUNDAMENTALS_MODULE | 基本面数据 JSON 结构与 API |
| FAMA_FRENCH | 全球 Fama-French 因子 / fama_french.qc / YYYYMM 行字典 |
| CALENDAR_MODULE | 股息、拆股、财报日期（calendar 回调参数）；模拟中的公司行动——用户页面是日历数据 |
| DEBUGGING | Debug Run / Debug Test、断点、调用栈和变量——用户页面是调试 |
| AUTO_TRADING | 本地前向运行（算法 + 智能体批量）和 New Run 对话框——用户页面是 AutoTrading |
| QUANT_CLOUD | 云端运行器上的算法批量前向作业——用户页面是 QuantCloud |
| AGENTS | Trading / Test / Optimization 智能体、AI Builder、模拟 Test 与通过已连接券商的前向／实盘——用户页面是智能体 |
| AI_ASSISTANT | IDE 的 AI 聊天、模型提供商、筛选器工具、AI Tools、MCP 服务器——用户页面是 QuantCraft AI |
| QUANTCRAFT_TOOLS | 面向 AI 的内置只读市场工具——用户页面是 QuantCraft Tools |
| SCREENER | 无代码和 Python 筛选、预设、由筛选器驱动的运行——用户页面是 Screener |
| POSSIBLE_ERRORS | 常见错误与修复——用户页面是可能的错误 |
这些文件面向需要精确名称和契约的策略作者。像 BACKTEST_MODULE（WebSocket 回测入口）和 IDE_BACKTEST_RUNNER（子进程运行器）这样的高级主题包含在捆绑包中供贡献者使用，但不是主要的用户路径。IDE 中的 QuantCraft AI 已预加载这些材料，使回答与已发布的模块保持一致。
QuantCraft 中的其他帮助入口
这些不属于 Documentation 标签页，但属于面向用户的同一个“参考生态”：
- QuantCraft AI——用自然语言提问；回答可以引用同一个开发语料库。在 AI → API Providers 下连接模型（你自己的密钥，或 QuantCraft Premium／托管选项）。
- 导入与导出——在磁盘和工作区之间移动
.py（及相关）文件。 - 测试结果——回测之后的权益图表、指标、交易和 HTML 导出。
搜索技巧
- 优先使用代码中出现的短词元：
on_finish、params、chart_indicator_series、coerce_chart_time、pane_id。 - 如果没有匹配项，请清空搜索——索引会按部分列出每个主题。
- 跨主题的想法（例如“基本面数据 +
on_bar”）通常需要两篇文章：打开基本面数据了解数据结构，再打开策略生命周期了解何时可用。
文档历史
应用内文档与策略运行时一起维护。当 Python 模块或回测载荷发生变化时，应用内主题和随附的 Markdown 会一同更新，使示例和名称保持同步。策略导入示例全程使用不带后缀的 quantcraft.* 路径书写；较旧的 ide.*_module 和 quantcraft.*_module 路径仅作为阅读现有脚本的辅助而记录。