csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(tsl-api): resolve backtesting return contract

Browse Source
This commit is contained in:
csh
2026-08-25 13:16:45 +08:00
parent d1568c02cd
commit 9c8d77e1c4
7 changed files with 834 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tsl/modules/tsbacktesting.md
+43 -31
View File
@@ -30,7 +30,7 @@ end;
function MyBackTesting.GetTradeOrder(vEndT); override;
begin
return -1;
return array(); // 占位：实际策略替换为目标持仓或交易明细
end;
function RunBackTest(begT, endT);
@@ -54,8 +54,9 @@ end;
返回规则：
- `GetTradeOrder(vEndT)` 返回二维数组：表示当前时点的目标持仓或交易明细。
- `GetTradeOrder(vEndT)` 返回空数组：比例类组合表示完全清仓。
- `GetTradeOrder(vEndT)` 返回 `-1`：表示当前时点不调仓或不交易。
- 数量类组合返回空数组：表示当前时点没有交易。
- 比例类组合返回空数组：表示完全清仓。
- 比例类某个调仓日不调仓：返回非数组控制值。
## 回测开发流程
@@ -76,21 +77,25 @@ end;
## 交易数据字段
下表把标准字段要求与框架允许的省略默认分开：`标准非空` 表示标准输入形状要求，`配置/省略规则` 表示配置替代或兼容默认。
### 比例类组合字段
`FGroupType := 1` 时，`GetTradeOrder(vEndT)` 返回目标持仓和目标比例。
| 字段 | 必填 | 接收类型 | 说明 |
| --------------- | ---- | ---------- | -------------------------------------------------------- |
| 字段 | 标准非空 | 接收类型 | 配置/省略规则 |
| --------------- | -------- | ---------- | -------------------------------------------------------- |
| `截止日` | 是 | `DateTime` | 通常等于 `vEndT` |
| `代码` | 是 | 字符串 | 目标持仓证券代码 |
| `方向` | 是 | 整数 | `1` 多单；`0` 空单；缺省时按多单处理 |
| `比例(%)` | 是 | 数值 | 目标持仓比例；`FRateType <> -1` 时可由框架按配比方式计算 |
| `成交价` | 否 | 数值 | 比例类通常由 `FPriceType` 或 `FPriceRateTo0` 决定 |
| `乘数` | 否 | 数值 | 默认 `1` |
| `保证金比例(%)` | 否 | 数值 | 默认 `100` |
| `开仓费率(%)` | 是 | 数值 | 开仓费率；股票、基金常见默认 `0.1` |
| `平仓费率(%)` | 是 | 数值 | 平仓费率；期货常见默认 `0.01` |
| `方向` | 是 | 整数 | `1` 多单；`0` 空单；兼容省略时默认多单 |
| `比例(%)` | 是 | 数值 | `FRateType := -1` 时必须提供；其它配比方式由框架计算 |
| `成交价` | 否 | 数值 | 通常由 `FPriceType` 获取；自定义成交价时必须提供 |
| `乘数` | 否 | 数值 | 省略时按品种或默认 `1` |
| `保证金比例(%)` | 否 | 数值 | 省略时按品种或默认 `100` |
| `开仓费率(%)` | 是 | 数值 | 省略时使用品种默认费率 |
| `平仓费率(%)` | 是 | 数值 | 省略时使用品种默认费率 |
`名称` 可出现在用户导入数据或示例中，但不属于比例类必需契约字段。
比例类方向值：
@@ -111,21 +116,23 @@ end;
`FGroupType := 2` 时，`GetTradeOrder(vEndT)` 返回交易明细。
| 字段 | 必填 | 接收类型 | 说明 |
| ----------------- | -------- | ---------- | -------------------------------------------------- |
| 字段 | 标准非空 | 接收类型 | 配置/省略规则 |
| ----------------- | -------- | ---------- | ------------------------------------------------------------ |
| `截止日` | 是 | `DateTime` | 通常等于 `vEndT` |
| `代码` | 是 | 字符串 | 交易证券代码 |
| `方向` | 是 | 整数 | `1` 多单；`0` 空单；缺省时按多单处理 |
| `动作` | 是 | 整数 | `0` 开仓；`1` 平仓；缺省时按开仓处理 |
| `成交量` | 条件必填 | 数值 | `FOpenVolType := 1` 或 `FCloseVolType := 1` 时提供 |
| `资金` | 条件必填 | 数值 | `FOpenVolType := 2` 时提供 |
| `剩余资金占比(%)` | 条件必填 | 数值 | `FOpenVolType := 3` 时提供 |
| `平仓数量占比(%)` | 条件必填 | 数值 | `FCloseVolType := 2` 时提供 |
| `成交价` | 是 | 数值 | 交易成交价 |
| `乘数` | 否 | 数值 | 默认 `1` |
| `保证金比例(%)` | 否 | 数值 | 默认 `100` |
| `费率(%)` | 条件必填 | 数值 | `FFeeType := 1` 时提供 |
| `费用` | 条件必填 | 数值 | `FFeeType := 2` 时提供；只适合数量类 |
| `方向` | 是 | 整数 | `1` 多单；`0` 空单；兼容省略时默认多单 |
| `动作` | 是 | 整数 | `0` 开仓；`1` 平仓；兼容省略时默认开仓 |
| `成交量` | 是 | 数值 | 固定成交量时提供；期权动作 `0`、`32`、`33` 必须提供 |
| `成交价` | 是 | 数值 | 标准交易明细应提供；系统价可由 `FPriceType` 取得，自定义时必须提供 |
| `乘数` | 否 | 数值 | 省略时按品种或默认值处理 |
| `保证金比例(%)` | 否 | 数值 | 省略时按品种或默认值处理 |
| `费率(%)` | 是 | 数值 | `FFeeType := 1`；省略时使用品种默认费率 |
| `资金` | 条件 | 数值 | 开仓且 `FOpenVolType := 2` |
| `剩余资金占比(%)` | 条件 | 数值 | 开仓且 `FOpenVolType := 3` |
| `平仓数量占比(%)` | 条件 | 数值 | 平仓且 `FCloseVolType := 2` |
| `费用` | 条件 | 数值 | `FFeeType := 2` 时直接提供单笔费用；只适合数量类 |
`FOpenVolType`/`FCloseVolType` 决定成交量替代字段：开仓模式为 `2/3` 时分别提供 `资金`/`剩余资金占比(%)`，平仓模式为 `2` 时提供 `平仓数量占比(%)`，这些模式下不再把 `成交量` 作为用户输入列。`名称` 只属于常见导入/展示列，不是数量类必需契约字段。
数量类方向和动作：
@@ -151,17 +158,19 @@ end;
| 字段 | 必填 | 接收类型 | 说明 |
| ------------------- | -------- | ---------- | -------------------------------------------------------- |
| `组 ID` | 是 | 字符串 | 同一组合内成分合约使用同一个组 ID |
| `组 ID` | 是 | 字符串 | 未构成组合时为空；同一组合内成分合约使用同一个组 ID |
| `截止日` | 是 | `DateTime` | 交易时点 |
| `代码` | 是 | 字符串 | 期权或期货合约代码 |
| `方向` | 是 | 整数 | `1` 权利仓或多单；`0` 义务仓或空单 |
| `动作` | 是 | 整数 | `0` 开仓；`1` 平仓；`32` 构建期权组合；`33` 解锁期权组合 |
| `成交价` | 是 | 数值 | 构建、解锁交易中可为任意大于 `0` 的实数 |
| `成交量` | 是 | 数值 | 合约数量 |
| `费率(%)` 或 `费用` | 条件必填 | 数值 | 由 `FFeeType` 决定 |
| `成交量` | 条件必填 | 数值 | 动作 `0`、`32`、`33` 必须提供；动作 `1` 可改用平仓占比 |
| `费率(%)` 或 `费用` | 条件字段 | 数值 | 由 `FFeeType` 决定；动作 `32/33` 时对应值为 `0` |
| `乘数` | 否 | 数值 | 按品种设置 |
| `保证金比例(%)` | 否 | 数值 | 按品种设置 |
| `组合类型` | 条件必填 | 字符串 | 组合策略标识，如 `CNSJC`、`STD` 等 |
| `组合类型` | 否 | 字符串 | 组合策略标识，如 `CNSJC`、`STD`；单腿或未识别时可为空 |
同一组合必须返回全部成分合约，且各行的 `组 ID`、`动作`、`成交量` 相同。
期权组合动作：
@@ -232,6 +241,7 @@ end;
| `5` | 等股数 | 按等股数分配 |
| `6` | 流通市值平方根加权 | 按流通市值平方根分配 |
| `7` | 总市值平方根加权 | 按总市值平方根分配 |
| `8` | 剩余资金等比例分配 | 先处理平仓，再把剩余资金等分给开仓证券 |
`FPriceRateTo0` 取值：
@@ -396,7 +406,7 @@ obj.FBMOption := 0;
用途：获取当前时点目标持仓或交易明细。
参数个数：1
返回值：二维数组、空数组或 `-1`。
返回值：通常为二维数组；比例类当前调仓日不调仓时，可返回非数组控制值。
| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
| -------- | ------- | ---- | ---------- | ----------------------------------------------------------------- |
@@ -407,6 +417,8 @@ obj.FBMOption := 0;
- 必须在子类中重写。
- 不要在 `GetTradeOrder(vEndT)` 中修改 `vEndT`。
- 如果要使用历史区间，从 `vEndT` 推导，例如 `stockzf(incMonth(vEndT, -1), vEndT)`。
- 数量类空数组表示当前时点无交易；比例类空数组表示完全清仓。
- 比例类当前调仓日不调仓时返回非数组控制值。
### 可重写方法
@@ -606,7 +618,7 @@ obj.FBMOption := 0;
| 情况 | 生成处理 |
| ------------------------------ | ----------------------------------------------------------------- |
| 只有“写回测框架”，没有策略逻辑 | 生成 `TSBackTesting` 子类骨架，`GetTradeOrder(vEndT)` 先返回 `-1` |
| 只有“写回测框架”，没有策略逻辑 | 生成 `TSBackTesting` 子类骨架，比例类 `GetTradeOrder(vEndT)` 使用空数组占位 |
| 没有证券池、调仓规则或交易明细 | 只生成框架和参数入口，不生成具体交易信号 |
| 没有期权需求 | 使用比例类或数量类普通字段，不加入期权组合字段 |
| `FGroupType := 1` | `GetTradeOrder(vEndT)` 返回目标持仓和目标比例字段 |
skills/tsl-api-reference/data/framework_index.json
+423 -4
View File
@@ -98,11 +98,46 @@
},
{
"api": "tsBackTesting.FGroupType",
"role": "candidate_mode_discriminator",
"role": "return_schema_discriminator",
"contract_evidence_required": true,
"evidence": [
"module/ts-backtesting.md#fgrouptype"
]
},
{
"api": "tsBackTesting.FRateType",
"role": "ratio_allocation_mode",
"evidence": [
"module/ts-backtesting.md#fratetype"
]
},
{
"api": "tsBackTesting.FPriceType",
"role": "execution_price_mode",
"evidence": [
"module/ts-backtesting.md#fpricetype"
]
},
{
"api": "tsBackTesting.FFeeType",
"role": "fee_input_mode",
"evidence": [
"module/ts-backtesting.md#ffeetype"
]
},
{
"api": "tsBackTesting.FOpenVolType",
"role": "quantity_open_size_mode",
"evidence": [
"module/ts-backtesting.md#fopenvoltype"
]
},
{
"api": "tsBackTesting.FCloseVolType",
"role": "quantity_close_size_mode",
"evidence": [
"module/ts-backtesting.md#fclosevoltype"
]
}
],
"hooks": [
@@ -198,10 +233,394 @@
"contracts": [
{
"id": "ts-backtesting-trade-order",
"status": "incomplete",
"status": "resolved",
"callback": "tsBackTesting.GetTradeOrder",
"reason": "The reference states target holdings or trade details but does not yet define the mode-specific record fields.",
"required_next_step": "Resolve the configuration-to-return-schema mapping before generating callback fields.",
"mode_discriminator": {
"api": "tsBackTesting.FGroupType"
},
"return_schemas": [
{
"id": "ratio-target-holdings",
"when": {
"FGroupType": "1"
},
"result_kind": "target_holdings",
"record_shape": "table_array",
"fields": [
{
"name": "截止日",
"type": "date_time",
"required": true,
"pdf_non_empty": true
},
{
"name": "代码",
"type": "string",
"required": true,
"pdf_non_empty": true
},
{
"name": "方向",
"type": "integer",
"required": false,
"default": "1",
"pdf_non_empty": true,
"values": {
"0": "short",
"1": "long"
}
},
{
"name": "比例(%)",
"type": "numeric",
"pdf_non_empty": true,
"required_when": [
{
"field": "FRateType",
"equals": [
"-1"
]
}
]
},
{
"name": "成交价",
"type": "numeric",
"pdf_non_empty": false,
"required_when": [
{
"field": "FPriceType",
"equals": [
"-1"
]
}
],
"description": "Provide when FPriceType=-1; otherwise the framework selects the execution price."
},
{
"name": "乘数",
"type": "numeric",
"required": false,
"pdf_non_empty": false,
"default": "1_or_instrument_default"
},
{
"name": "保证金比例(%)",
"type": "numeric",
"required": false,
"pdf_non_empty": false,
"default": "100_or_instrument_default"
},
{
"name": "开仓费率(%)",
"type": "numeric",
"required": false,
"pdf_non_empty": true,
"used_when": [
{
"field": "FFeeType",
"equals": [
"1"
]
}
],
"fallback": "tsBackTesting.StockFee"
},
{
"name": "平仓费率(%)",
"type": "numeric",
"required": false,
"pdf_non_empty": true,
"used_when": [
{
"field": "FFeeType",
"equals": [
"1"
]
}
],
"fallback": "tsBackTesting.StockFee"
}
],
"alternate_returns": [
{
"type": "empty_array",
"meaning": "clear_all_positions"
},
{
"type": "non_array",
"meaning": "skip_current_rebalance",
"documented_examples": [
-1,
1
]
}
],
"evidence": [
"module/ts-backtesting.md#gettradeorderv_end_t"
]
},
{
"id": "quantity-trade-details",
"when": {
"FGroupType": "2"
},
"result_kind": "trade_details",
"record_shape": "table_array",
"fields": [
{
"name": "截止日",
"type": "date_time",
"required": true,
"pdf_non_empty": true
},
{
"name": "代码",
"type": "string",
"required": true,
"pdf_non_empty": true
},
{
"name": "方向",
"type": "integer",
"required": false,
"default": "1",
"pdf_non_empty": true,
"values": {
"0": "short",
"1": "long"
}
},
{
"name": "动作",
"type": "integer",
"required": true,
"compat_default": "0",
"pdf_non_empty": true,
"values": {
"0": "open",
"1": "close",
"32": "build_option_group",
"33": "unlock_option_group"
}
},
{
"name": "成交量",
"type": "numeric",
"pdf_non_empty": true,
"required_when": [
{
"field": "FOpenVolType",
"equals": [
"1"
],
"record_when": {
"动作": [
"0"
]
}
},
{
"field": "FCloseVolType",
"equals": [
"1"
],
"record_when": {
"动作": [
"1"
]
}
}
],
"record_required_when": {
"动作": [
"32",
"33"
]
}
},
{
"name": "成交价",
"type": "numeric",
"pdf_non_empty": true,
"required_when": [
{
"field": "FPriceType",
"equals": [
"-1"
]
}
],
"record_required_when": {
"动作": [
"32",
"33"
]
},
"record_constraint_when": {
"动作": {
"32": "greater_than_zero",
"33": "greater_than_zero"
}
}
},
{
"name": "资金",
"type": "numeric",
"required_when": [
{
"field": "FOpenVolType",
"equals": [
"2"
],
"record_when": {
"动作": [
"0"
]
}
}
]
},
{
"name": "剩余资金占比(%)",
"type": "numeric",
"required_when": [
{
"field": "FOpenVolType",
"equals": [
"3"
],
"record_when": {
"动作": [
"0"
]
}
}
]
},
{
"name": "平仓数量占比(%)",
"type": "numeric",
"required_when": [
{
"field": "FCloseVolType",
"equals": [
"2"
],
"record_when": {
"动作": [
"1"
]
}
}
]
},
{
"name": "乘数",
"type": "numeric",
"required": false,
"pdf_non_empty": false,
"default": "1_or_instrument_default"
},
{
"name": "保证金比例(%)",
"type": "numeric",
"required": false,
"pdf_non_empty": false,
"default": "100_or_instrument_default"
},
{
"name": "费率(%)",
"type": "numeric",
"pdf_non_empty": true,
"used_when": [
{
"field": "FFeeType",
"equals": [
"1"
]
}
],
"record_value_when": {
"动作": {
"32": 0,
"33": 0
}
},
"fallback": "tsBackTesting.StockFee"
},
{
"name": "费用",
"type": "numeric",
"pdf_non_empty": false,
"required_when": [
{
"field": "FFeeType",
"equals": [
"2"
]
}
],
"record_value_when": {
"动作": {
"32": 0,
"33": 0
}
}
},
{
"name": "组 ID",
"type": "string",
"pdf_non_empty": true,
"required": false,
"applies_when": "option_group_strategy",
"required_in_extension": true,
"description": "Required as a non-empty shared identifier for option-group rows; empty for ungrouped single-leg rows."
},
{
"name": "组合类型",
"type": "string",
"pdf_non_empty": false,
"required": false,
"applies_when": "option_group_strategy",
"description": "Option strategy identifier such as CNSJC or STD; may be empty for single-leg or unrecognized combinations."
}
],
"record_rules": [
{
"when": "option_group_strategy",
"rule": "Return all component contracts for a group; rows in the same group share 组 ID, 动作, and 成交量."
},
{
"when": {
"动作": [
"0",
"32",
"33"
]
},
"rule": "Option-group opening, construction, and unlock records use a concrete 成交量; action 1 may instead use 平仓数量占比(%)."
},
{
"when": {
"动作": [
"0"
]
},
"rule": "Option-group opening (action 0) uses FOpenVolType=1; fixed-amount and remaining-funds modes are not supported for this action."
}
],
"alternate_returns": [
{
"type": "empty_array",
"meaning": "no_trade_at_current_time"
}
],
"evidence": [
"module/ts-backtesting.md#gettradeorderv_end_t"
]
}
],
"evidence": [
"module/ts-backtesting.md#gettradeorderv_end_t"
]
skills/tsl-api-reference/data/function_index.tsv
+6 -4
View File
@@ -2658,6 +2658,7 @@ FClearCycle module ts-timing-evaluation FClearCycle module/ts-timing-evaluation.
FClose_N1 module ts-statistical-arbitrage FClose_N1 module/ts-statistical-arbitrage.md fclose_n1 上侧平仓标准差倍数 field instance public tsStatisticalArbitrage tsStatisticalArbitrage.FClose_N1
FClose_N2 module ts-statistical-arbitrage FClose_N2 module/ts-statistical-arbitrage.md fclose_n2 下侧平仓标准差倍数 field instance public tsStatisticalArbitrage tsStatisticalArbitrage.FClose_N2
FCloseFeeRate module ts-timing-evaluation FCloseFeeRate module/ts-timing-evaluation.md fclosefeerate 平仓费率(%) 0 field instance public tsTimingEvaluation tsTimingEvaluation.FCloseFeeRate
FCloseVolType module ts-backtesting FCloseVolType module/ts-backtesting.md fclosevoltype 数量类组合平仓数量模式 1：固定成交量法；2：可平仓数量占比法 field instance public tsBackTesting tsBackTesting.FCloseVolType
FcLowestFee module ts-backtesting FcLowestFee module/ts-backtesting.md fclowestfee 平仓最低费用 5.0 field instance public tsBackTesting tsBackTesting.FcLowestFee
FCombinations module ts-backtest-overfit-prob FCombinations module/ts-backtest-overfit-prob.md fcombinations 生成的子集组合 field instance public tsBacktestOverfitProb tsBacktestOverfitProb.FCombinations
FComFactorArr module ts-hg-data-process FComFactorArr module/ts-hg-data-process.md fcomfactorarr 合成因子库 array() field instance public ts_HGDataProcess ts_HGDataProcess.FComFactorArr
@@ -2782,7 +2783,7 @@ FFaRet module ts-factor-portfolio-optimizer FFaRet module/ts-factor-portfolio-op
FFaRets module ts-factor-portfolio-optimizer FFaRets module/ts-factor-portfolio-optimizer.md ffarets 因子收益序列 field instance public tsFactorPortfolioOptimizer tsFactorPortfolioOptimizer.FFaRets
FFeature module ts-persistence-of-fund FFeature module/ts-persistence-of-fund.md ffeature 基金业绩指标 field instance public ts_PersistenceOfFund ts_PersistenceOfFund.FFeature
FFeeRate module derivatives-analysis FFeeRate module/derivatives-analysis/option-delta-hedging.md ffeerate 交易费率百分比，默认值为 0 field instance public opDeltaHedging opDeltaHedging.FFeeRate
FFeeType module ts-backtesting FFeeType module/ts-backtesting.md ffeetype 费用类别 1：费率法 field instance public tsBackTesting tsBackTesting.FFeeType
FFeeType module ts-backtesting FFeeType module/ts-backtesting.md ffeetype 费用类别 1：费率法；2：费用法。比例类只能使用费率法；数量类可使用费率法或费用法 field instance public tsBackTesting tsBackTesting.FFeeType
FFeeType2 module ts-backtesting FFeeType2 module/ts-backtesting.md ffeetype2 比例类费率 1： 历史明细中查找开、 平仓费率 field instance public tsBackTesting tsBackTesting.FFeeType2
FfhExchangeRatetype module ts-backtesting FfhExchangeRatetype module/ts-backtesting.md ffhexchangeratetype 分红汇率类型 2：对应市场结算汇率中间价 field instance public tsBackTesting tsBackTesting.FfhExchangeRatetype
ffi_es dotnet financial ffi_es(w_p, x, f, delta, confidence_interval) dotnet/financial/financial_engineering-risk_model-application-risk_analysis-algorithm_layer.md ffi_es 金融 金融工程 风险模型 应用 风险分析 算法层 返回 获取 ES 返回期望损失ES function ffi_es
@@ -2824,7 +2825,7 @@ fgRight builtin graph fgRight() builtin/graph.md fgright 图形对象 图形 图
fgRightDown builtin graph fgRightDown() builtin/graph.md fgrightdown 图形对象 图形 图表 graph 对象 实例 object 右下 function fgRightDown
fgRightUp builtin graph fgRightUp() builtin/graph.md fgrightup 图形对象 图形 图表 graph 对象 实例 object 右上 function fgRightUp
FGroups module ts-multi-factor FGroups module/ts-multi-factor.md fgroups 五分位 field instance public tsMultiFactor tsMultiFactor.FGroups
FGroupType module ts-backtesting FGroupType module/ts-backtesting.md fgrouptype 组合类型 1：比例类组合 field instance public tsBackTesting tsBackTesting.FGroupType
FGroupType module ts-backtesting FGroupType module/ts-backtesting.md fgrouptype 组合类型 1：比例类组合；2：数量类组合。期权不支持比例类回测 field instance public tsBackTesting tsBackTesting.FGroupType
FGroupType module ts-multi-factor FGroupType module/ts-multi-factor.md fgrouptype 分组方式 1：百分位 field instance public tsMultiFactor tsMultiFactor.FGroupType
fgUp builtin graph fgUp() builtin/graph.md fgup 图形对象 图形 图表 graph 对象 实例 object 上 function fgUp
Fh dotnet math Fh dotnet/math/optimization.md fh 二次型 field instance public tsOptimizer tsOptimizer.Fh
@@ -3149,6 +3150,7 @@ footerValue dotnet base footerValue(t, from_col, tocol, average_col_field, _type
FOpen_N1 module ts-statistical-arbitrage FOpen_N1 module/ts-statistical-arbitrage.md fopen_n1 上侧开仓标准差倍数 field instance public tsStatisticalArbitrage tsStatisticalArbitrage.FOpen_N1
FOpen_N2 module ts-statistical-arbitrage FOpen_N2 module/ts-statistical-arbitrage.md fopen_n2 下侧开仓标准差倍数 field instance public tsStatisticalArbitrage tsStatisticalArbitrage.FOpen_N2
FOpenFeeRate module ts-timing-evaluation FOpenFeeRate module/ts-timing-evaluation.md fopenfeerate 开仓费率(%) 0 field instance public tsTimingEvaluation tsTimingEvaluation.FOpenFeeRate
FOpenVolType module ts-backtesting FOpenVolType module/ts-backtesting.md fopenvoltype 数量类组合开仓数量模式 1：固定成交量法；2：固定金额法；3：剩余资金占比法 field instance public tsBackTesting tsBackTesting.FOpenVolType
FOPMaturityDate module derivatives-analysis FOPMaturityDate module/derivatives-analysis/option-instrument-indicators.md fopmaturitydate 到期月份序号；0 为全部，1 为近月，2 为次近月，依次类推 field instance public ts_Options_Screening ts_Options_Screening.FOPMaturityDate
FOPPZID module derivatives-analysis FOPPZID module/derivatives-analysis/option-instrument-indicators.md foppzid 期权品种或标的代码；空字符串表示不按品种筛选 field instance public ts_Options_Screening ts_Options_Screening.FOPPZID
FOpsId module ts-ops FOpsId module/ts-ops.md fopsid 服务标识 TS-OPS 服务 ID property instance public opsServer opsServer.FOpsId
@@ -3189,7 +3191,7 @@ FPriceRateTo0 module ts-backtesting FPriceRateTo0 module/ts-backtesting.md fpric
FPriceStep module bond-research FPriceStep module/bond-research/bond-price-segmentation.md fpricestep 价格频数分布步长，单位为元，默认 10 field instance public cb_PriceAndDeadlineData cb_PriceAndDeadlineData.FPriceStep
FPriceType module bond-research FPriceType module/bond-research/bond-price-segmentation.md fpricetype 统计最高价和最低价时使用的价格类型；0 为收盘价，1 为当日最高价或最低价 field instance public cb_PriceAndDeadlineData cb_PriceAndDeadlineData.FPriceType
FPriceType module factor-research FPriceType module/factor-research/index-chip-factors.md fpricetype 指数均价算法；支持算术平均、成交量加权、成交金额加权及调整后的成交量加权 field instance public ts_IndexChipDistribution ts_IndexChipDistribution.FPriceType
FPriceType module ts-backtesting FPriceType module/ts-backtesting.md fpricetype 成交价类别 3：日均价 field instance public tsBackTesting tsBackTesting.FPriceType
FPriceType module ts-backtesting FPriceType module/ts-backtesting.md fpricetype 成交价类别 -1：用户自定义；1：时点价格；2：收盘价；3：日均价；4：开盘价；5：系统昨收 field instance public tsBackTesting tsBackTesting.FPriceType
FpriceType module ts-multi-factor FpriceType module/ts-multi-factor.md fpricetype 成交价类别 2：收盘价 field instance public tsMultiFactor tsMultiFactor.FpriceType
FPrincDZ module ts-hg-risk-pca FPrincDZ module/ts-hg-risk-pca.md fprincdz 主成分对照 见 FPrincDZ 默认值 field instance public ts_HGRiskPCA ts_HGRiskPCA.FPrincDZ
FPurchaseRatio module fund-research FPurchaseRatio module/fund-research/fixed-amount-investment.md fpurchaseratio 申购费率，单位为百分比 field instance public ts_AIPBackTesting ts_AIPBackTesting.FPurchaseRatio
@@ -3229,7 +3231,7 @@ frameStocksMark_GetGrouptail module strategy-selection-tools frameStocksMark_Get
frameupdate dotnet base frameupdate(left, right, ons, type) dotnet/base/array.md frameupdate 数组 数据表 更新 缺失值 merge update table 按键字段用右表补充或更新左表中的缺失值，并直接修改左表 function frameupdate
framevaluecounts dotnet base framevaluecounts(data, countfieldname, iforder) dotnet/base/array.md framevaluecounts 数据表-计数 function framevaluecounts
FRateType module quick-back-testing FRateType module/quick-back-testing.md fratetype 比例类组合资金分配方式 4：等权重 field instance public quickBackTesting quickBackTesting.FRateType
FRateType module ts-backtesting FRateType module/ts-backtesting.md fratetype 比例类组合资金分配方式 4：等权重 field instance public tsBackTesting tsBackTesting.FRateType
FRateType module ts-backtesting FRateType module/ts-backtesting.md fratetype 比例类组合资金分配方式；-1：用户自定义比例；0/1/4/5/6/7 为系统配比；8：剩余资金等比例分配；默认 4：等权重 field instance public tsBackTesting tsBackTesting.FRateType
FRateType module ts-future-multifactor FRateType module/ts-future-multifactor.md fratetype 比例类型 4(等权) field instance public tsFutureMultiFactor tsFutureMultiFactor.FRateType
FRateType module ts-multi-factor FRateType module/ts-multi-factor.md fratetype 个股资金分配方法 4：等权重 field instance public tsMultiFactor tsMultiFactor.FRateType
FRatio module tinysoft-strategies FRatio module/tinysoft-strategies/market-cap-rotation.md fratio 买卖费率百分比，默认值为 0.1 field instance public tsLargeAndSmallTurning tsLargeAndSmallTurning.FRatio
Can't render this file because it is too large.
skills/tsl-api-reference/references/codegen/module/ts-backtesting.md
+85 -5
View File
@@ -42,7 +42,7 @@
声明：field
组合类型 1：比例类组合
组合类型 1：比例类组合；2：数量类组合。期权不支持比例类回测
可见性：`public`
@@ -82,7 +82,7 @@
声明：field
成交价类别 3：日均价
成交价类别 -1：用户自定义；1：时点价格；2：收盘价；3：日均价；4：开盘价；5：系统昨收
可见性：`public`
@@ -92,7 +92,27 @@
声明：field
费用类别 1：费率法
费用类别 1：费率法；2：费用法。比例类只能使用费率法；数量类可使用费率法或费用法
可见性：`public`
类型：integer
### `FOpenVolType`
声明：field
数量类组合开仓数量模式 1：固定成交量法；2：固定金额法；3：剩余资金占比法
可见性：`public`
类型：integer
### `FCloseVolType`
声明：field
数量类组合平仓数量模式 1：固定成交量法；2：可平仓数量占比法
可见性：`public`
@@ -102,7 +122,7 @@
声明：field
比例类组合资金分配方式 4：等权重
比例类组合资金分配方式；-1：用户自定义比例；0/1/4/5/6/7 为系统配比；8：剩余资金等比例分配；默认 4：等权重
可见性：`public`
@@ -631,7 +651,67 @@ return ret;
| --------- | --------- | -------------- |
| `v_end_t` | date_time | 日期，当前时点 |
返回：array
返回：通常为 `array`；比例类当前调仓日不调仓时，可返回非数组控制值
返回契约
`GetTradeOrder(v_end_t)` 的返回值是框架回调输入，不是固定列集合；记录字段由
`FGroupType` 及数量、费用和成交价配置共同决定。每行是二维数组中的一条记录。
比例类组合（`FGroupType := 1`）返回目标持仓记录：
| 字段 | 类型 | 标准非空 | 配置/省略规则 |
| --------------- | ---------- | -------- | ------------------------------------------------------ |
| `截止日` | `date_time` | 是 | 当前调仓时点，通常等于 `v_end_t` |
| `代码` | `string` | 是 | 目标持仓证券代码 |
| `方向` | `integer` | 是 | `1` 多单；`0` 空单；兼容省略时默认多单 |
| `比例(%)` | `numeric` | 是 | `FRateType := -1` 必须提供；系统配比时由框架计算 |
| `成交价` | `numeric` | 否 | 通常由 `FPriceType` 获取；自定义成交价时必须提供 |
| `乘数` | `numeric` | 否 | 省略时按品种或默认 `1` |
| `保证金比例(%)` | `numeric` | 否 | 省略时按品种或默认 `100` |
| `开仓费率(%)` | `numeric` | 是 | 省略时使用品种默认费率 |
| `平仓费率(%)` | `numeric` | 是 | 省略时使用品种默认费率 |
`名称` 可出现在用户导入数据或范例中，但不属于比例类必需契约字段。
数量类组合（`FGroupType := 2`）返回交易明细记录：
| 字段 | 类型 | 标准非空 | 配置/省略规则 |
| ------------------- | ---------- | -------- | ------------------------------------------------------ |
| `截止日` | `date_time` | 是 | 当前交易时点，通常等于 `v_end_t` |
| `代码` | `string` | 是 | 交易证券代码 |
| `方向` | `integer` | 是 | `1` 多单；`0` 空单；兼容省略时默认多单 |
| `动作` | `integer` | 是 | `0` 开仓；`1` 平仓；兼容省略时默认开仓 |
| `成交量` | `numeric` | 是 | 固定成交量时提供；期权动作 `0/32/33` 必须提供 |
| `成交价` | `numeric` | 是 | 标准交易明细应提供；系统价 `FPriceType` 可代取，自定义时必须提供 |
| `乘数` | `numeric` | 否 | 省略时按品种或默认值处理 |
| `保证金比例(%)` | `numeric` | 否 | 省略时按品种或默认值处理 |
| `费率(%)` | `numeric` | 是 | `FFeeType := 1`；省略时使用品种默认费率 |
| `资金` | `numeric` | 条件 | 开仓且 `FOpenVolType := 2` |
| `剩余资金占比(%)` | `numeric` | 条件 | 开仓且 `FOpenVolType := 3` |
| `平仓数量占比(%)` | `numeric` | 条件 | 平仓且 `FCloseVolType := 2` |
| `费用` | `numeric` | 条件 | `FFeeType := 2`；只适合数量类，直接提供单笔费用 |
`FOpenVolType`/`FCloseVolType` 决定成交量替代字段：开仓模式为 `2/3` 时分别提供 `资金`/`剩余资金占比(%)`，平仓模式为 `2` 时提供 `平仓数量占比(%)`。这些模式下不应再把 `成交量` 当作用户输入列。
`名称` 可出现在导入数据或范例中，但不属于数量类必需契约字段。
期权组合扩展（数量类专用）：
| 字段 | 类型 | 规则 |
| ---------- | -------- | ---- |
| `组 ID` | `string` | 组合策略数据必有；未构成组合时为空字符串；同一组合的所有成分合约使用同一值 |
| `组合类型` | `string` | 组合策略标识，如 `CNSJC`、`STD`；未识别或单腿时可为空 |
- `动作 := 32` 表示申请构建组合，`动作 := 33` 表示组合解锁；框架后续可能标准化为 `34/35` 调入/调出数据。
- 对一个组合必须提供所有成分合约，且这些行的 `组 ID`、`动作`、`成交量` 相同。
- 期权动作 `0`、`32`、`33` 使用固定成交量法；动作 `1` 可使用固定成交量或可平仓数量占比法。
- 采用费率法时动作 `32/33` 的 `费率(%)` 为 `0`；采用费用法时对应 `费用` 为 `0`。
控制返回：
- 数量类在当前时点无交易时返回空数组。
- 比例类返回空数组表示完全清仓；比例类某个调仓日不调仓时返回非数组控制值，不要将其解释为交易字段。
### `GetTA(v_end_t)`
skills/tsl-api-reference/scripts/framework_lookup.py
+143 -1
View File
@@ -2,6 +2,7 @@
"""Library for validating and resolving evidence-backed framework profiles."""
import json
from copy import deepcopy
from pathlib import Path
from lookup import (
@@ -87,6 +88,17 @@ def validate_source_ids(data, rows):
errors.append(
f"{section}[{entry_index}].evidence references unknown source {source}"
)
if section == "contracts" and isinstance(entry, dict):
for schema_index, schema in enumerate(
entry.get("return_schemas", [])
):
for source in evidence_set(schema):
if source not in known_sources:
errors.append(
f"contracts[{entry_index}].return_schemas"
f"[{schema_index}].evidence references unknown source "
f"{source}"
)
return errors
@@ -209,6 +221,54 @@ def validate_framework(framework, rows, codegen_root, index):
f"{framework['qualified_name']}.contracts[{contract_index}] "
f"references unknown source {source}"
)
if not isinstance(contract, dict) or contract.get("status") != "resolved":
continue
discriminator = contract.get("mode_discriminator")
if not isinstance(discriminator, dict) or not discriminator.get("api"):
errors.append(
f"{framework['qualified_name']}.contracts[{contract_index}] resolved "
"contracts must contain mode_discriminator.api"
)
continue
configured_apis = {
normalize(entry.get("api", ""))
for entry in framework.get("configuration", [])
if isinstance(entry, dict)
}
if normalize(discriminator["api"]) not in configured_apis:
errors.append(
f"{framework['qualified_name']}.contracts[{contract_index}]."
f"mode_discriminator.api {discriminator['api']!r} is not a "
"configuration member"
)
schemas = contract.get("return_schemas")
if not isinstance(schemas, list) or not schemas:
errors.append(
f"{framework['qualified_name']}.contracts[{contract_index}] resolved "
"contracts must contain return_schemas"
)
continue
discriminator_field = discriminator["api"].rsplit(".", 1)[-1]
seen_values = set()
for schema_index, schema in enumerate(schemas):
path = (
f"{framework['qualified_name']}.contracts[{contract_index}]."
f"return_schemas[{schema_index}]"
)
if not isinstance(schema, dict):
errors.append(f"{path} must be an object")
continue
value = schema.get("when", {}).get(discriminator_field)
if value is None or str(value).strip() == "":
errors.append(f"{path}.when must select {discriminator_field}")
elif str(value) in seen_values:
errors.append(f"{path}.when duplicates {discriminator_field}={value}")
else:
seen_values.add(str(value))
if not isinstance(schema.get("fields"), list) or not schema["fields"]:
errors.append(f"{path}.fields must be a non-empty array")
if not evidence_set(schema):
errors.append(f"{path}.evidence must contain at least one source id")
return errors
@@ -225,6 +285,47 @@ def validate_index(data, rows, codegen_root):
return errors
def contract_mode_mapping(contract, configuration_api):
discriminator = contract.get("mode_discriminator", {})
return (
contract.get("status") == "resolved"
and normalize(discriminator.get("api", "")) == normalize(configuration_api)
and isinstance(contract.get("return_schemas"), list)
)
def resolved_contract_packet(contract, config):
packet = deepcopy(contract)
discriminator = packet.get("mode_discriminator")
packet["selected_return_schema"] = None
if not isinstance(discriminator, dict) or not discriminator.get("api"):
return packet
field = discriminator["api"].rsplit(".", 1)[-1]
schemas = packet.get("return_schemas", [])
values = [
str(schema.get("when", {}).get(field))
for schema in schemas
if schema.get("when", {}).get(field) is not None
]
packet["mode_discriminator"] = {
**discriminator,
"field": field,
"values": values,
}
if field in config:
requested = str(config[field])
packet["selected_return_schema"] = next(
(
schema
for schema in schemas
if str(schema.get("when", {}).get(field)) == requested
),
None,
)
return packet
def scaffold_packet(framework, config):
configured_names = {
entry["api"].rsplit(".", 1)[-1]
@@ -245,7 +346,15 @@ def scaffold_packet(framework, config):
}
)
for entry in framework["configuration"]:
if entry.get("contract_evidence_required") and entry["api"].rsplit(".", 1)[-1] in config:
field = entry["api"].rsplit(".", 1)[-1]
if not entry.get("contract_evidence_required") or field not in config:
continue
mapped_contracts = [
contract
for contract in framework["contracts"]
if contract_mode_mapping(contract, entry["api"])
]
if not mapped_contracts:
diagnostics.append(
{
"code": "CONTRACT_MODE_UNRESOLVED",
@@ -258,6 +367,29 @@ def scaffold_packet(framework, config):
"source_ids": entry.get("evidence", []),
}
)
continue
requested = str(config[field])
available = {
str(schema.get("when", {}).get(field))
for contract in mapped_contracts
for schema in contract.get("return_schemas", [])
if schema.get("when", {}).get(field) is not None
}
if requested not in available:
diagnostics.append(
{
"code": "CONTRACT_MODE_UNKNOWN",
"severity": "error",
"message": (
f"{entry['api']}={requested!r} has no recorded return schema."
),
"next_action": (
"Use one of the documented mode values: "
+ ", ".join(sorted(available))
),
"source_ids": entry.get("evidence", []),
}
)
contract_status = "resolved"
for contract in framework["contracts"]:
if contract.get("status") != "resolved":
@@ -271,6 +403,15 @@ def scaffold_packet(framework, config):
"source_ids": contract.get("evidence", []),
}
)
contracts = [
resolved_contract_packet(contract, config)
for contract in framework["contracts"]
]
if any(
diagnostic["code"] in {"CONTRACT_MODE_UNKNOWN", "CONTRACT_MODE_UNRESOLVED"}
for diagnostic in diagnostics
):
contract_status = "incomplete"
return {
"status": "resolved",
"scaffold_status": "resolved",
@@ -285,6 +426,7 @@ def scaffold_packet(framework, config):
"state_apis": framework["state_apis"],
"execution": framework["execution"],
"result_apis": framework["result_apis"],
"contracts": contracts,
"diagnostics": diagnostics,
"evidence": framework.get("evidence", []),
}
skills/tsl-api-reference/workflows/class-and-framework.md
+2
View File
@@ -38,6 +38,8 @@ python <this-skill-dir>/scripts/class_lookup.py \
- `scaffold_status=resolved` 只表示生命周期和成员引用完整。
- `contract_status` 不是 `resolved` 时，必须按 `diagnostics` 补齐模式与返回 schema 证据，
并停止生成回调字段。
- `contract_status=resolved` 时，`contracts[].return_schemas` 给出全部已验证模式；传入
`--config` 命中模式后，`contracts[].selected_return_schema` 给出当前配置对应的字段契约。
Framework Profile 只描述 API 协议，不定义 TSL 语法或代码结构。解析后的 Framework
Contract Packet 仅作为已验证的 API 事实输出。
test/test_tsl_api_framework.py
+128 -7
View File
@@ -633,7 +633,7 @@ class TslApiFrameworkTests(unittest.TestCase):
packet = json.loads(result.stdout)
self.assertEqual("resolved", packet["profile_status"])
self.assertEqual("resolved", packet["profile"]["scaffold_status"])
self.assertEqual("incomplete", packet["profile"]["contract_status"])
self.assertEqual("resolved", packet["profile"]["contract_status"])
self.assertEqual(
["construct", "configure", "schedule", "callback", "execute", "inspect"],
[phase["phase"] for phase in packet["profile"]["lifecycle"]],
@@ -770,7 +770,7 @@ class TslApiFrameworkTests(unittest.TestCase):
packet = json.loads(result.stdout)
profile = packet["profile"]
self.assertEqual("resolved", profile["scaffold_status"])
self.assertEqual("incomplete", profile["contract_status"])
self.assertEqual("resolved", profile["contract_status"])
self.assertEqual(
["construct", "configure", "schedule", "callback", "execute", "inspect"],
[phase["phase"] for phase in profile["lifecycle"]],
@@ -779,12 +779,21 @@ class TslApiFrameworkTests(unittest.TestCase):
["tsBackTesting.GetTradeOrder"],
[hook["api"] for hook in profile["hooks"] if hook["required"]],
)
self.assertEqual([], profile["diagnostics"])
self.assertEqual(
"CONTRACT_INCOMPLETE",
profile["diagnostics"][0]["code"],
["tsBackTesting.GetTradeOrder"],
[contract["callback"] for contract in profile["contracts"]],
)
self.assertEqual(
{
"api": "tsBackTesting.FGroupType",
"field": "FGroupType",
"values": ["1", "2"],
},
profile["contracts"][0]["mode_discriminator"],
)
def test_candidate_discriminator_does_not_invent_a_mode(self):
def test_candidate_discriminator_resolves_ratio_schema(self):
result = run_script(
CLASS_LOOKUP,
"--class",
@@ -799,12 +808,124 @@ class TslApiFrameworkTests(unittest.TestCase):
packet = json.loads(result.stdout)
profile = packet["profile"]
self.assertEqual({"FGroupType": "1"}, profile["configured_values"])
self.assertEqual("incomplete", profile["contract_status"])
self.assertEqual("resolved", profile["contract_status"])
self.assertEqual([], profile["diagnostics"])
schema = profile["contracts"][0]["selected_return_schema"]
self.assertEqual("1", schema["when"]["FGroupType"])
self.assertEqual(
["截止日", "代码"],
[field["name"] for field in schema["fields"] if field.get("required")],
)
self.assertEqual(
[-1, 1],
schema["alternate_returns"][1]["documented_examples"],
)
self.assertTrue(
all(
field.get("pdf_non_empty")
for field in schema["fields"]
if field["name"] in {"截止日", "代码", "方向", "比例(%)"}
)
)
self.assertEqual(
"FRateType",
next(
field["required_when"]
for field in schema["fields"]
if field["name"] == "比例(%)"
)[0]["field"],
)
def test_candidate_discriminator_resolves_quantity_schema(self):
result = run_script(
CLASS_LOOKUP,
"--class",
"tsBackTesting",
"--config",
"FGroupType=2",
"--format",
"json",
)
self.assertEqual(0, result.returncode, result.stderr)
profile = json.loads(result.stdout)["profile"]
self.assertEqual("resolved", profile["contract_status"])
self.assertEqual([], profile["diagnostics"])
schema = profile["contracts"][0]["selected_return_schema"]
self.assertEqual("2", schema["when"]["FGroupType"])
self.assertIn(
"CONTRACT_MODE_UNRESOLVED",
"动作",
[field["name"] for field in schema["fields"] if field.get("required")],
)
self.assertEqual(
["empty_array"],
[item["type"] for item in schema["alternate_returns"]],
)
self.assertEqual(
{"组 ID", "组合类型"},
{
field["name"]
for field in schema["fields"]
if field["name"] in {"组 ID", "组合类型"}
},
)
action = next(field for field in schema["fields"] if field["name"] == "动作")
self.assertEqual("0", action["compat_default"])
volume = next(field for field in schema["fields"] if field["name"] == "成交量")
self.assertEqual(
["32", "33"],
volume["record_required_when"]["动作"],
)
self.assertEqual(
"FOpenVolType",
next(
field["required_when"]
for field in schema["fields"]
if field["name"] == "资金"
)[0]["field"],
)
def test_unknown_discriminator_value_is_reported(self):
result = run_script(
CLASS_LOOKUP,
"--class",
"tsBackTesting",
"--config",
"FGroupType=3",
"--format",
"json",
)
self.assertEqual(0, result.returncode, result.stderr)
profile = json.loads(result.stdout)["profile"]
self.assertEqual("incomplete", profile["contract_status"])
self.assertIsNone(profile["contracts"][0]["selected_return_schema"])
self.assertIn(
"CONTRACT_MODE_UNKNOWN",
{item["code"] for item in profile["diagnostics"]},
)
def test_get_trade_order_reference_records_mode_specific_fields(self):
result = run_script(
API_LOOKUP,
"--name",
"tsBackTesting.GetTradeOrder",
)
self.assertEqual(0, result.returncode, result.stderr)
self.assertIn("FGroupType := 1", result.stdout)
self.assertIn("FGroupType := 2", result.stdout)
self.assertIn("`比例(%)`", result.stdout)
self.assertIn("`剩余资金占比(%)`", result.stdout)
self.assertIn("非数组", result.stdout)
def test_quantity_mode_discriminators_are_indexed_members(self):
for name in ("tsBackTesting.FOpenVolType", "tsBackTesting.FCloseVolType"):
with self.subTest(name=name):
result = run_script(API_LOOKUP, "--name", name)
self.assertEqual(0, result.returncode, result.stderr)
self.assertNotIn("No TSL API named", result.stdout)
def test_unknown_configuration_is_reported(self):
result = run_script(
CLASS_LOOKUP,