📝 docs(tsl): rebuild canonical syntax and routing manual
This commit is contained in:
@@ -0,0 +1,59 @@
|
||||
# Backtest And Trade Flow
|
||||
|
||||
文档类型：业务骨架
|
||||
是否可直接用于生成代码：否
|
||||
是否含已验证可执行示例：否
|
||||
是否含已验证反例：否
|
||||
遇到不确定时跳转到：项目实际接口定义、[../modules/tsbacktesting.md](../modules/tsbacktesting.md)、[selection_and_signal_patterns.md](selection_and_signal_patterns.md)、[../syntax/index.md](../syntax/index.md)
|
||||
|
||||
这一篇收拢回测、组合、交易与结果读取流程。
|
||||
|
||||
## 这一篇解决什么问题
|
||||
|
||||
回答“回测对象如何组织、交易流程如何设置、结果怎样取出和解释”。
|
||||
|
||||
## 必须记住的规则
|
||||
|
||||
- 回测流程属于业务框架使用，不属于语言层语法。
|
||||
- 在回测场景里，先分清“框架对象怎么配置”和“语法怎么写”是两件不同的事。
|
||||
- 本层只给业务流程骨架，不给回测对象 API 真值。
|
||||
- 本层优先解释流程、对象职责和结果读取入口。
|
||||
- 如果问题已经落到回测对象创建方式、交易数据入口名、结果接口真值或项目封装差异，停止在 finance / modules 层继续推断，直接回项目实际接口定义。
|
||||
|
||||
## 最小任务骨架
|
||||
|
||||
1. 先确认回测对象类型、周期、资金和组合类型。
|
||||
2. 再确认项目侧是否已经封装好最小可用对象模型、交易输入入口和结果读取链路。
|
||||
3. 然后配置交易约束、价格口径、费用和基准。
|
||||
4. 再准备交易输入：目标权重、成交明细或其他框架要求的输入数据。
|
||||
5. 再执行回测。
|
||||
6. 最后按任务读取净值、成交、持仓和绩效结果。
|
||||
|
||||
## 进入前先回答的问题
|
||||
|
||||
- 你做的是比例类组合，还是数量类组合。
|
||||
- 你需要哪些交易约束、费用模型和基准口径。
|
||||
- 结果要给人看，还是要交给后续分析 / 执行链路。
|
||||
|
||||
## 结果读取骨架
|
||||
|
||||
- 这里说的是结果类型，不是保证存在的接口名；任何读取方法都先以项目实际接口定义为准。
|
||||
- 读净值 / 收益率时间序列。
|
||||
- 读成交 / 调仓结果。
|
||||
- 读持仓、资产和绩效指标。
|
||||
- 读基准或扩展结果时，先确认对应接口是否已经在项目里封装好。
|
||||
|
||||
## 常见误判
|
||||
|
||||
- 把回测框架的字段和方法误当成 TSL 语言内建语法。
|
||||
- 在没确认组合类型、资金约束和结果接口前，就直接复制零散片段。
|
||||
- 只看到 `BackTest()`，就跳过交易输入准备和结果读取设计。
|
||||
- 把“概念流程”误写成“独立可编译模板”。
|
||||
|
||||
## 跳转指引
|
||||
|
||||
- finance 总入口：见 [entry_decision.md](entry_decision.md)
|
||||
- 参考现有回测资料：见 [../modules/tsbacktesting.md](../modules/tsbacktesting.md)
|
||||
- 具体字段、交易数据入口、结果接口真值或项目封装差异：回项目实际接口定义
|
||||
- 选股与信号：见 [selection_and_signal_patterns.md](selection_and_signal_patterns.md)
|
||||
- 回到语言层：见 [../syntax/index.md](../syntax/index.md)
|
||||
@@ -0,0 +1,58 @@
|
||||
# Finance Entry Decision
|
||||
|
||||
文档类型：检索页
|
||||
是否可直接用于生成代码：否
|
||||
是否含已验证可执行示例：否
|
||||
是否含已验证反例：否
|
||||
遇到不确定时跳转到：[market_data_context.md](market_data_context.md)、[../syntax/index.md](../syntax/index.md)、[../reference/index.md](../reference/index.md)
|
||||
|
||||
这里是金融层的入口决策页，不是代码页。它只解决“业务任务该往哪一层跳”，不重新定义语言基础语法。
|
||||
|
||||
## 这一篇解决什么问题
|
||||
|
||||
回答“什么时候应该进入 finance 层、进入后先去哪个业务主题页，以及什么时候该回到 syntax / reference 层”。
|
||||
|
||||
## 必须记住的规则
|
||||
|
||||
- finance 只解释业务任务怎样组织，不解释语言规则本身。
|
||||
- finance 可以给出“语法 + 金融函数结合示例”，但不拥有语言规则的解释权。
|
||||
- 不需要先通读完整 syntax；先进入最相关的业务主题页，需要时再回补语法或函数查阅。
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 你在问市场数据语境、序列/指标组织、选股/信号任务、回测/交易流程。
|
||||
- 你已经知道自己在做金融任务，但还没决定应该先读哪一篇业务页。
|
||||
- 你需要业务层的“任务骨架”，而不是单条语法结论。
|
||||
|
||||
## 进入 finance 前至少要掌握什么
|
||||
|
||||
- 知道 TSL 的最短骨架怎么写：见 [../syntax/02_quickstart.md](../syntax/02_quickstart.md)
|
||||
- 知道当前文件属于哪种顶层模型：见 [../syntax/03_core_model.md](../syntax/03_core_model.md)
|
||||
- 知道高频误写不要怎么踩：见 [../syntax/12_pitfalls.md](../syntax/12_pitfalls.md)
|
||||
|
||||
## 进入后先去哪里
|
||||
|
||||
- 如果你要先理解市场数据从哪里来、脚本运行在什么语境里：去 [market_data_context.md](market_data_context.md)
|
||||
- 如果你要先理清序列、指标、逐 bar 计算和窗口依赖：去 [series_and_indicator_model.md](series_and_indicator_model.md)
|
||||
- 如果你要组织选股条件、筛选条件、信号输出：去 [selection_and_signal_patterns.md](selection_and_signal_patterns.md)
|
||||
- 如果你要配置回测对象、交易流程和结果读取：去 [backtest_and_trade_flow.md](backtest_and_trade_flow.md)
|
||||
|
||||
## 什么时候回到别的层
|
||||
|
||||
- 如果问题变成“这句语法怎么写”：回 [../syntax/index.md](../syntax/index.md)
|
||||
- 如果问题变成“这个函数在哪个目录、怎么查签名”：回 [../reference/index.md](../reference/index.md)
|
||||
- 如果问题变成“现成模块或互操作能力怎么接”：回 [../modules/index.md](../modules/index.md)
|
||||
|
||||
## 常见误判
|
||||
|
||||
- 把金融数据上下文误当成语言通用规则。
|
||||
- 还没澄清业务任务类型，就先去补读整套 syntax。
|
||||
- 把 finance 页里的任务骨架误当成独立可编译模板。
|
||||
|
||||
## 跳转指引
|
||||
|
||||
- 市场数据语境：见 [market_data_context.md](market_data_context.md)
|
||||
- 序列与指标模型：见 [series_and_indicator_model.md](series_and_indicator_model.md)
|
||||
- 选股与信号：见 [selection_and_signal_patterns.md](selection_and_signal_patterns.md)
|
||||
- 回测与交易：见 [backtest_and_trade_flow.md](backtest_and_trade_flow.md)
|
||||
- 回到语法层：见 [../syntax/index.md](../syntax/index.md)
|
||||
@@ -0,0 +1,32 @@
|
||||
# Finance Index
|
||||
|
||||
文档类型：检索页
|
||||
是否可直接用于生成代码：否
|
||||
是否含已验证可执行示例：否
|
||||
是否含已验证反例：否
|
||||
遇到不确定时跳转到：[../syntax/index.md](../syntax/index.md)（优先）、[market_data_context.md](market_data_context.md)、[../reference/index.md](../reference/index.md)
|
||||
|
||||
这里是业务层入口。只讨论金融任务如何使用 TSL，不重讲基础语法。
|
||||
|
||||
## 先看这 5 条
|
||||
|
||||
- 如果你的问题是“语言怎么写”，不要留在 finance，回到 [../syntax/index.md](../syntax/index.md)。
|
||||
- 如果你的问题是“某个金融任务怎么组织”，从下面最接近的业务主题开始。
|
||||
- [entry_decision.md](entry_decision.md) 是入口决策页，不是代码页。
|
||||
- 先进入 finance 的业务主题页；只有业务页需要补语法或函数细节时，再回到语法手册或函数查阅层。
|
||||
- 只进入一个最相关的主题文件，需要时再跳到相邻主题。
|
||||
|
||||
## 按任务跳转
|
||||
|
||||
| 当前任务 | 先读哪里 |
|
||||
| --- | --- |
|
||||
| 先判断是否该进入业务层 | [entry_decision.md](entry_decision.md)（决策页，不是代码页） |
|
||||
| 理解市场数据上下文与运行场景 | [market_data_context.md](market_data_context.md) |
|
||||
| 理解序列、指标、时序计算模型 | [series_and_indicator_model.md](series_and_indicator_model.md) |
|
||||
| 写选股、信号、筛选表达模式 | [selection_and_signal_patterns.md](selection_and_signal_patterns.md) |
|
||||
| 写回测对象、交易流程、结果读取 | [backtest_and_trade_flow.md](backtest_and_trade_flow.md) |
|
||||
|
||||
## 切换到别的层
|
||||
|
||||
- 回到语法层：见 [../syntax/index.md](../syntax/index.md)
|
||||
- 回到函数库查找层：见 [../reference/index.md](../reference/index.md)
|
||||
@@ -0,0 +1,40 @@
|
||||
# Market Data Context
|
||||
|
||||
文档类型：业务骨架
|
||||
是否可直接用于生成代码：否
|
||||
是否含已验证可执行示例：否
|
||||
是否含已验证反例：否
|
||||
遇到不确定时跳转到：[series_and_indicator_model.md](series_and_indicator_model.md)、[../syntax/index.md](../syntax/index.md)、[../modules/tsbacktesting.md](../modules/tsbacktesting.md)
|
||||
|
||||
本页用于判断金融脚本运行时的数据语境，不提供独立语法模板。
|
||||
|
||||
这一篇整理金融场景中的市场数据语境与执行环境。
|
||||
|
||||
## 这一篇解决什么问题
|
||||
|
||||
回答“金融脚本运行时的数据上下文是什么、哪些概念属于业务层而不是语言层”。
|
||||
|
||||
## 必须记住的规则
|
||||
|
||||
- 这里讨论的是市场数据语境，不是语言语法。
|
||||
- 当问题变成“`if` / `function` / `array` 怎么写”时，应回到 syntax 层。
|
||||
- 当问题变成“当前 bar、序列窗口、市场字段从哪里来”时，才留在 finance 层。
|
||||
|
||||
## 适用边界
|
||||
|
||||
- 本文不新增语法规则，语法仍以 `docs/tsl/syntax/` 为准。
|
||||
|
||||
## 为什么这里不放独立示例
|
||||
|
||||
- 本文不放单独的语法示例，避免把业务上下文误写成语言规则。
|
||||
|
||||
## 常见误写
|
||||
|
||||
- 把市场数据上下文误当成所有 TSL 文件默认自带的语言能力。
|
||||
- 在还没确认数据语境前，先去排查语法。
|
||||
|
||||
## 跳转指引
|
||||
|
||||
- 回到语法层：见 [../syntax/03_core_model.md](../syntax/03_core_model.md)
|
||||
- 看指标与序列：见 [series_and_indicator_model.md](series_and_indicator_model.md)
|
||||
- 参考现有业务资料：见 [../modules/tsbacktesting.md](../modules/tsbacktesting.md)
|
||||
@@ -0,0 +1,51 @@
|
||||
# Selection And Signal Patterns
|
||||
|
||||
文档类型：业务骨架
|
||||
是否可直接用于生成代码：否
|
||||
是否含已验证可执行示例：否
|
||||
是否含已验证反例：否
|
||||
遇到不确定时跳转到：[series_and_indicator_model.md](series_and_indicator_model.md)、[backtest_and_trade_flow.md](backtest_and_trade_flow.md)、[../syntax/index.md](../syntax/index.md)
|
||||
|
||||
这一篇收拢选股、筛选和信号生成的业务模式。
|
||||
|
||||
## 这一篇解决什么问题
|
||||
|
||||
回答“如何把条件表达和金融筛选任务组织成稳定的选股/信号脚本”。
|
||||
|
||||
## 必须记住的规则
|
||||
|
||||
- 选股和信号属于业务层模式，不是通用语言规则。
|
||||
- 语言层只回答“条件怎么写”；finance 层回答“这些条件怎样组成选股/信号任务”。
|
||||
- 如果问题开始变成某个基础运算符怎么写，应回到 syntax 层。
|
||||
|
||||
## 任务骨架
|
||||
|
||||
1. 先写条件表达：澄清你在筛什么、比较什么、窗口是多少。
|
||||
2. 再生成信号：决定输出是布尔筛选、买卖信号，还是评分 / 排序结果。
|
||||
3. 最后整理结果输出：决定是输出标的列表、信号列、分数字段，还是交给下游回测。
|
||||
|
||||
## 常见任务形态
|
||||
|
||||
- 单次筛选：给定条件，输出满足条件的标的集合。
|
||||
- 连续信号：按时间推进，逐 bar 产生买入 / 卖出 / 持有信号。
|
||||
- 评分排序：先算分，再做阈值过滤、排名或分组。
|
||||
|
||||
## 写之前先决定
|
||||
|
||||
- 条件是在“当前 bar 是否成立”，还是“最近 N 个 bar 的模式是否成立”。
|
||||
- 信号是即时使用，还是要保存成后续回测 / 执行的输入。
|
||||
- 输出面向人看，还是面向下游框架消费。
|
||||
|
||||
## 常见误判
|
||||
|
||||
- 把一个业务筛选范式误写成“所有 TSL 都应这样写”的基础语法结论。
|
||||
- 不区分“条件表达成立”与“选股任务组织合理”这两件事。
|
||||
- 还没确认输出形式，就先把条件堆成很长的单条表达式。
|
||||
- 把筛选条件、信号生成和结果输出混写在一个不可拆分的大块里。
|
||||
|
||||
## 跳转指引
|
||||
|
||||
- 指标与序列：见 [series_and_indicator_model.md](series_and_indicator_model.md)
|
||||
- 市场上下文：见 [market_data_context.md](market_data_context.md)
|
||||
- 回测与交易：见 [backtest_and_trade_flow.md](backtest_and_trade_flow.md)
|
||||
- 基础语法：见 [../syntax/index.md](../syntax/index.md)
|
||||
@@ -0,0 +1,53 @@
|
||||
# Series And Indicator Model
|
||||
|
||||
文档类型：业务骨架
|
||||
是否可直接用于生成代码：否
|
||||
是否含已验证可执行示例：否
|
||||
是否含已验证反例：否
|
||||
遇到不确定时跳转到：[market_data_context.md](market_data_context.md)、[selection_and_signal_patterns.md](selection_and_signal_patterns.md)、[../syntax/index.md](../syntax/index.md)
|
||||
|
||||
这一篇处理金融序列与指标计算模式。
|
||||
|
||||
## 这一篇解决什么问题
|
||||
|
||||
回答“指标、序列、逐 bar 计算和相关金融表达方式如何组织，以及 AI 应该先建立什么样的业务心智模型”。
|
||||
|
||||
## 必须记住的规则
|
||||
|
||||
- 序列与指标属于业务模型，不属于通用语法。
|
||||
- 当你需要解释循环、表达式、数组和字符串时，应回到 syntax 层。
|
||||
- 当你需要解释“指标如何依赖历史序列”时，才留在这里。
|
||||
|
||||
## 输入上下文
|
||||
|
||||
- 先确认标的、周期、起止区间和复权口径。
|
||||
- 先确认你在处理“单值输入”还是“逐 bar 序列输入”。
|
||||
- 先确认指标依赖多少历史窗口，以及窗口未满时如何处理。
|
||||
|
||||
## 逐 bar 心智模型
|
||||
|
||||
- 每个 bar 只应使用当前 bar 及其之前已经可见的信息。
|
||||
- 先准备输入序列，再计算当前 bar 的指标值，最后再决定当前 bar 的输出。
|
||||
- 不要把后面的 bar 结果回填到前面的 bar。
|
||||
- 不要把“能写成一个表达式”误解成“就不需要业务上下文”。
|
||||
|
||||
## 窗口依赖
|
||||
|
||||
- 任何均线、滚动统计、历史比较，先写清窗口长度。
|
||||
- 窗口未满前，先决定是跳过、返回空值，还是走 warm-up 逻辑。
|
||||
- 多条序列一起参与计算时，先确认时间轴是否对齐。
|
||||
- 当结果依赖前值时，先确认你是在做“当前 bar 计算”还是“状态延续”。
|
||||
|
||||
## 常见误判
|
||||
|
||||
- 把指标写法误当成“TSL 基础表达式”的定义来源。
|
||||
- 在没有澄清数据频率、窗口和上下文前，就直接抽象成通用语法规则。
|
||||
- 把未来数据混进当前 bar 的计算里。
|
||||
- 先写公式，再补上下文，导致窗口长度和序列来源都不明确。
|
||||
|
||||
## 跳转指引
|
||||
|
||||
- 市场数据上下文：见 [market_data_context.md](market_data_context.md)
|
||||
- 选股与信号：见 [selection_and_signal_patterns.md](selection_and_signal_patterns.md)
|
||||
- 回测与交易：见 [backtest_and_trade_flow.md](backtest_and_trade_flow.md)
|
||||
- 表达式与控制流语法：见 [../syntax/07_expressions_and_operators.md](../syntax/07_expressions_and_operators.md) 与 [../syntax/08_control_flow.md](../syntax/08_control_flow.md)
|
||||
Reference in New Issue
Block a user