📝 docs(tsl): rebuild canonical syntax and routing manual

2026-04-22 16:59:20 +08:00
parent 3ed5052e61
commit 96b705b00b
83 changed files with 46446 additions and 323 deletions
@@ -0,0 +1,40 @@
+# Modules Index
+
+文档类型：检索页
+是否可直接用于生成代码：否
+是否含已验证可执行示例：否
+是否含已验证反例：否
+遇到不确定时跳转到：[tsbacktesting.md](tsbacktesting.md)、[tsl_python_interop.md](tsl_python_interop.md)、[../finance/index.md](../finance/index.md)、项目自身文档、`scripts/*` 入口脚本、CI 配置
+
+这里处理“现成模块、外部集成和互操作”，不处理基础语法教学，也不替代金融业务主线。
+
+模块摘要页只负责确认能力边界和选路，不负责给出项目账户体系、真实接口名、部署方式、权限模型或脚本入口的真值。
+
+## If / Then 路由
+
+- If 问题在问“策略回测框架怎么组织、怎么取结果”，then 先读 [tsbacktesting.md](tsbacktesting.md)。
+- If 问题在问“TSL 和 Python 怎样双向调用或嵌入”，then 先读 [tsl_python_interop.md](tsl_python_interop.md)。
+- If 问题在问“微信消息怎样发送、查询状态”，then 先读 [wechat_message.md](wechat_message.md)。
+- If 问题在问“官方 Python SDK / pyTSL 客户端怎么用”，then 先读 [pytsl_api.md](pytsl_api.md)。
+- If 问题在问模块的真实接入参数、账号来源、部署依赖、权限模型或脚本入口，then 这已经不是模块能力识别；优先回项目自身文档、`scripts/*` 入口脚本、CI 配置，必要时再把对应模块页当边界说明。
+
+## Tie-Break
+
+- If 主问题是业务流程、选股逻辑或回测指标组织，then 先回 [../finance/index.md](../finance/index.md)。
+- If 主问题是现成模块或集成能力，then 先留在 `modules/`；语法只作辅证。
+- If 主问题已经落到 TSL 通用函数库签名或通用语法参数细节，then 再回 [../reference/index.md](../reference/index.md) 或对应语法页。
+- If 主问题已经落到模块专属 API / SDK 参数细节，then 先回对应模块页，并以该页指向的官方文档、项目文档或调用侧文档为准。
+- If 主问题已经落到真实接入参数、账号来源、部署依赖、权限模型或执行入口，then 退出模块摘要层，直接转项目依赖确认。
+
+## 最短跳转
+
+| 当前任务 | 先读哪里 |
+| --- | --- |
+| 我要看回测框架 | [tsbacktesting.md](tsbacktesting.md) |
+| 我要看 Python 互操作 | [tsl_python_interop.md](tsl_python_interop.md) |
+| 我要看微信消息推送 | [wechat_message.md](wechat_message.md) |
+| 我要看 Python API | [pytsl_api.md](pytsl_api.md) |
+| 我要确认模块的真实接入参数 / 账号来源 / 部署依赖 / 脚本入口 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；当前项目已补齐时再看 [../toolchain.md](../toolchain.md) |
+| 我要回到业务主线 | [../finance/index.md](../finance/index.md) |
+| 我要回到语法主线 | [../syntax/index.md](../syntax/index.md) |
+| 我要查函数库 | [../reference/index.md](../reference/index.md) |
@@ -1,5 +1,15 @@
 # 天软 pyTSL 接口使用说明

+文档类型：模块摘要
+是否可直接用于生成代码：仅部分
+是否含已验证可执行示例：否
+是否含已验证反例：否
+遇到不确定时跳转到：项目级部署文档、官方 pyTSL 详细接口文档、[tsl_python_interop.md](tsl_python_interop.md)、[index.md](index.md)
+
+本页用于确认 pyTSL 的接入方向和最小链路，不替代项目级部署文档或完整接口手册。
+
+- 如果登录方式、凭证来源、环境变量、部署入口、连接上下文或返回结构没有确认，不继续生成接入代码，直接回项目级部署文档或官方 pyTSL 详细接口文档。
+
 ## 定位

 - 官方 Python SDK，面向取数/执行/批量/异步与数据转换。
@@ -17,6 +27,12 @@
 - `pip install tspytsl`（在线安装）
 - 离线安装与手动部署

+## 同步 / 异步怎么选
+
+- 同步：任务短、交互简单、立即取结果时优先用 `pyTSL.Client`。
+- 异步：任务长、需要并发或批量调度时再看 `pyTSL.AsyncClient` 与 `async_util`。
+- 如果只是先打通最小链路，先用同步客户端，不要一开始就上异步。
+
 ## 核心类与模块

 - `pyTSL.Client`：同步客户端
@@ -35,8 +51,31 @@
 - `EncodeStream` / `DecodeStream`
 - `DataFrameToTSArray`

+## 最小成功路径
+
+1. 先回项目级部署文档确认登录方式、凭证来源、环境变量和部署入口。
+2. 安装 `tspytsl`。
+3. 创建 `pyTSL.Client(...)`。
+4. 调 `login()` 登录。
+5. 用 `query(...)`、`exec(...)` 或 `call(...)` 执行任务。
+6. 从返回结果里读取你真正需要的内容；常见起手是 `result.dataframe()`。
+7. 完成后显式 `logout()`。
+
+## 返回结果与失败处理
+
+- 常见返回会落在 `TSResultValue` 这一层；真正用之前，先确认你要的是表格、标量还是其他结构。
+- 最小起手路径可以先看 `result.dataframe()` 是否符合预期，再扩展到别的读取方式。
+- 登录、查询和退出应当成对出现；不要把长期未退出的连接当默认用法。
+- 如果失败，先检查安装、登录上下文、查询语句和返回结构，再决定是否切到异步客户端。
+- 如果还不能确认登录方式、凭证来源或返回结构，不继续扩展接入代码，先回项目级部署文档和官方接口文档。
+
 ## 示例（Python）

+示例里的 `"user"` / `"password"` 只表示调用外形，不代表项目里的真实登录方式或凭证来源。
+
+代码块身份：配置片段 / 概念骨架
+代码块说明：可参考最小链路，不是已验证可执行示例。
+
 ```python
 import pyTSL

@@ -1,66 +1,53 @@
 # 策略回测框架 TSBackTesting

-## 定位
+文档类型：模块摘要
+是否可直接用于生成代码：否
+是否含已验证可执行示例：否
+是否含已验证反例：否
+遇到不确定时跳转到：项目实际接口定义、[../finance/backtest_and_trade_flow.md](../finance/backtest_and_trade_flow.md)、[index.md](index.md)

- 提供统一的策略回测框架（股票/期货/期权/组合等），覆盖资金、交易约束、清算与绩效输出。
+本页不足以直接生成回测代码，只用于确认回测任务的组织顺序，以及哪些地方必须回到项目实际接口定义继续核对。

-## 结构索引
+- 只要任务已经进入对象创建、交易输入入口、结果读取方法或项目封装差异，就先停止生成，直接回项目实际接口定义，不要先拼调用链。

- 策略回测流程
- 成员变量
- 成员方法
- 查询用接口
- 回测范例
- 债券品种回测说明
- 期权组合策略回测说明
- 常见问题
+## 适用场景

-## 回测流程概览
+- 任务已经进入“回测框架怎么配置、怎么执行、怎么读结果”。
+- 你处理的是组合型任务，而不是单纯的表达式或单次筛选。
+- 你已经知道自己要做比例类组合还是数量类组合，或者正在先判断这件事。

- 组合类型选择 → 交易数据准备 → 回测执行 → 结果查询与分析。
+## 当前只确认的范围

-## 组合类型
+- 当前页已经确认的范围是：对象名 `TSBackTesting`、典型任务顺序、组合类型差异、常见字段组和常见结果接口类别。
+- 下面出现的字段名和结果接口名，只用于检索候选和理解类别，不是可以直接假定存在的项目接口真值。
+- 任务顺序可以先按这条主线理解：组合类型选择 → 交易数据准备 → 回测执行 → 结果查询与分析。
+- 组合类型先按两类理解：比例类组合提供目标权重，数量类组合提供成交量或成交价等交易明细。
+- 常见字段组可以先按以下几类检索：
+  - 时间与周期：`FBegT`、`FEndT`、`FCycle`
+  - 组合类型：`FGroupType`
+  - 资金与价格：`FIniCash`、`FPriceType`、`FPriceType1..4`
+  - 交易约束：`FNoZT`、`FNoDT`、`FMinVol`、`FMinAmount`、`FMaxVolPercent`、`FMaxAmountPercent`
+  - 费用与分红：`FFeeType`、`FlowestFeeType`、`FDividendType`
+  - 基准与输出：`FBMType`、`FBMDetail`、`FBMOption`、`FHFDataOutPut`
+- 常见结果接口可以先按以下类别检索：`GetTimeSeries`、`GetTradeOrder`、`GetNetAssetValue` / `GetAssetData` / `GetHoldData`、`GetPercent`、`GetIRRReturn`、`ReturnBenchmark`。

- 比例类组合：提供目标权重。
- 数量类组合：提供成交量/成交价等交易明细。
+## 任务骨架（非代码模板）

-## 关键成员变量（分组摘要）
+1. 先判断任务属于比例类组合还是数量类组合。
+2. 然后先回到项目实际接口定义，确认最小可用对象模型、对象创建方式、最小必填项和交易数据输入入口。
+3. 再确认起止时间、组合类型和初始资金是不是项目里的最小必填项。
+4. 执行回测。
+5. 最后先按项目实际接口定义确认结果读取链路，再读取净值时间序列、成交结果或持仓结果，再补看绩效指标。

- **时间与周期**：`FBegT`、`FEndT`、`FCycle`
- **组合类型**：`FGroupType`（比例类/数量类）
- **资金与价格**：`FIniCash`、`FPriceType`、`FPriceType1..4`
- **交易约束**：`FNoZT`、`FNoDT`、`FMinVol`、`FMinAmount`、`FMaxVolPercent`、`FMaxAmountPercent`
- **费用与分红**：`FFeeType`、`FlowestFeeType`、`FDividendType`
- **期权与期货特性**：`FOptionRs`、`FMainFutureMap`
- **基准与输出**：`FBMType`、`FBMDetail`、`FBMOption`、`FHFDataOutPut`
+## 不要猜的部分

-> 详细取值及说明以实际接口定义为准。
+- 当前页没有确认的范围是：对象创建方式、最小必填字段的强制集合、交易数据入口名、最小输入结构、结果读取完整链路。
+- 如果没有项目实际接口定义，不要根据本页直接写 `new TSBackTesting()`、`SetTradeData(...)` 或其他具体调用链。
+- 各字段可选值和更细接口，以实际接口定义为准；当前页只负责告诉你要核对哪些位置，不负责补全细节。

-## 关键成员方法（常用）
+## 跳转指引

- `BackTest`：执行回测
- `GetTimeSeries`：返回净值/收益率时间序列
- `GetTradeOrder`：返回调仓/成交数据
- `GetNetAssetValue` / `GetAssetData` / `GetHoldData`：资产与持仓
- `GetPercent`、`GetIRRReturn`、`ReturnBenchmark`：绩效指标
- `GetClearancePrice` / `GetIntVol` / `GetOtherData`：扩展查询
-
-## 最小流程示例（概念化）
-
-```tsl
-// 1) 初始化参数
-backtest := new TSBackTesting();
-backtest.FBegT := 20240101T;
-backtest.FEndT := 20241231T;
-backtest.FGroupType := 1; // 比例类
-backtest.FIniCash := 1000000;
-
-// 2) 设置交易数据（比例类：目标持仓）
-// backtest.SetTradeData(trade_data);
-
-// 3) 执行回测
-backtest.BackTest();
-
-// 4) 获取结果
-return backtest.GetTimeSeries();
-```
+- 业务组织问题：见 [../finance/backtest_and_trade_flow.md](../finance/backtest_and_trade_flow.md)
+- 具体字段、交易数据入口、对象创建方式和结果接口真值：回项目实际接口定义
+- 回到模块入口：见 [index.md](index.md)
+- 只在需要查 TSL 通用函数归类时，才回 [../reference/index.md](../reference/index.md)
@@ -1,10 +1,28 @@
 # 天软平台和 Python 的交互

+文档类型：模块摘要
+是否可直接用于生成代码：否
+是否含已验证可执行示例：否
+是否含已验证反例：否
+遇到不确定时跳转到：项目级部署文档、对应官方文档、[pytsl_api.md](pytsl_api.md)、[index.md](index.md)
+
+本页用于接入决策和最小链路确认，不替代项目级部署文档。
+
+- 如果登录方式、凭证来源、位数、环境变量、连接通道或部署入口没有确认，不继续生成接入代码，直接回项目级部署文档或对应官方文档。
+
 ## 摘要

 - 覆盖三类交互：Python 调用 TSL、TSL 调用 Python、落地服务器开启 Python 服务。
 - 提供 COM/远程登录两种路径，以及 `PyRun`/`PyCall` 体系。

+## 怎么选路
+
+| 场景 | 先选哪条路 | 最小前置条件 | 常见失败点 |
+| --- | --- | --- | --- |
+| Python 作为主控，远程执行或调用 TSL | Python 调 TSL | Python 环境、TSLPy 模块、可用连接方式（COM / 远程登录） | 位数不一致、环境变量没配好、服务器未登录 |
+| TSL 脚本里需要调用现有 Python 代码 | TSL 调 Python | TSL 与 Python 位数一致、`PYTHONHOME` 等环境正确 | Python 环境未就绪、模块找不到、网格场景不支持 |
+| 落地服务器侧长期提供 Python 能力 | 落地服务器开启 Python 服务 | 服务端环境、部署权限、可维护的脚本入口 | 服务端环境和本地环境不一致、依赖未部署、运行权限不足 |
+
 ## 结构索引

 - 支持版本
@@ -17,9 +35,12 @@

 ## Python 调用 TSL（核心步骤）

-1. 配置环境变量（天软目录、Python 目录）。
-2. 加载 TSLPy 模块（直接加载或修改包名）。
-3. 选择连接方式（COM / 远程登录）。
+1. 先确认项目级部署文档里的天软目录、Python 目录、位数、连接通道和登录方式。
+2. 配置环境变量（天软目录、Python 目录）。
+3. 加载 TSLPy 模块（直接加载或修改包名）。
+4. 选择连接方式（COM / 远程登录）。
+5. 登录服务器后，再执行 `RemoteExecute` / `RemoteCallFunc`。
+6. 完成后显式断开连接。

 ## 主要接口（Python 侧）

@@ -35,12 +56,38 @@
 - `PyCall`（调用 Python 函数，支持命名参数）
 - `PyError` / `PyRelease` / `PyEnsure`

+## TSL 调用 Python（核心步骤）
+
+1. 先回项目级部署文档确认位数、`PYTHONHOME`、解释器路径和可用模块。
+2. 用 `PyEnsure` 确认 Python 运行时已经就绪。
+3. 需要把输入传给 Python 时，先用 `PyPutVar` 放入变量。
+4. 选择执行方式：执行整段脚本用 `PyRun`，直接调函数用 `PyCall`。
+5. 需要取回结果时，再用 `PyGetVar` 读取输出变量。
+6. 失败时先看 `PyError`，结束后显式 `PyRelease`。
+
+## 最小前置条件
+
+- Python 与 TSL 位数必须一致。
+- 多版本 Python 需同步设置 `PYTHONHOME`。
+- 落地前先决定是谁主控：Python 主控还是 TSL 主控。
+
 ## do Python 方式

 - 适合快速执行 Python 脚本，省去显式接口调用。

+## 落地服务器开启 Python 服务（核心步骤）
+
+1. 先回项目级部署文档确认服务入口、部署权限、依赖目录和守护方式。
+2. 在服务器上准备与项目要求一致的 Python 运行时和依赖包。
+3. 放置一个稳定的 Python 脚本或服务入口，先只承载一条最小调用链。
+4. 按项目约定把这个入口接到天软侧的调用路径或调度入口。
+5. 用最小请求先验证“能启动、能调用、能返回”，再扩展业务逻辑。
+6. 再补日志、重启方式和运维监控；如果这些入口还没确认，不继续生成部署代码。
+
 ## 注意事项（精简）

 - Python 与 TSL 位数必须一致。
 - 多版本 Python 需同步设置 `PYTHONHOME`。
 - TSL 调 Python 不支持网格调用。
+- 出现调用失败时，优先先检查环境、位数和登录状态，再排查业务逻辑。
+- 如果登录方式、凭证来源、位数、环境变量、连接通道或部署入口任一没有确认，不继续生成接入代码。
@@ -1,6 +1,14 @@
 # 发送微信消息使用说明

-## 摘要
+文档类型：模块摘要
+是否可直接用于生成代码：仅部分
+是否含已验证可执行示例：否
+是否含已验证反例：否
+遇到不确定时跳转到：调用侧账户体系文档、项目实际接口说明、[index.md](index.md)
+
+本页用于确认接口名称、参数含义和风险边界，不替代项目级接入文档。
+
+## 适用场景

 - 通过“天软科技服务号”向微信客户端发送模板消息。
 - 支持同步/异步发送，异步可用消息 ID 查询状态。
@@ -22,6 +30,7 @@
 ## 参数说明（模板消息）

 - `userid`：绑定账户后获取的用户标识（必需）。
+- `username`：查询异步发送状态时使用的用户名 / 账户标识；当前页只确认查询接口需要它，具体来源以项目实际账户体系或调用侧约定为准。如果调用侧拿不到该值，当前页不支持生成状态查询代码。
 - `url`：详情地址（必需，可为空字符串）。
 - `title`：模板消息标题（必需）。
 - `first`：副标题（一般需要）。
@@ -35,8 +44,23 @@

 - 同步：阻塞等待结果，适合紧急通知。
 - 异步：立即返回，适合非紧急通知；用 `get_wechat_message_status` 查询。
+- 如果你无法确认 `username` 的来源，不要自行猜测；先回调用侧或账户体系文档确认。

-## 示例（TSL）
+## 当前只确认的范围
+
+- 当前页已经确认的范围是：发送接口名、异步发送会返回消息 ID、状态查询接口需要 `userid` + `username` + `wechat_message_id`。
+- 当前页没有确认的范围是：`username` 的正式来源、不同模板关键字的完整映射、项目侧的统一封装方式。
+
+## 不要猜的部分
+
+- 不要把 `"username"` 当成可用实参，也不要凭空拼接账户名。
+- 如果调用侧没有提供 `username`，当前页只支持生成发送代码，不支持生成状态查询代码。
+- `k1..k6` 的含义随模板类型变化；需要和具体模板一起核对。
+
+## 发送示例（配置片段，可参考参数组织）
+
+代码块身份：配置片段 / 概念骨架
+代码块说明：可参考参数组织，不是已验证可执行示例。

 ```tsl
 // 定义参数
@@ -55,6 +79,9 @@ echo send_wechat_message(user_id, url, title, first, remark, keyword_1, keyword_

 // 异步发送
 wechat_message_id := send_wechat_message_async(user_id, url, title, first, remark, keyword_1, keyword_2);
-// 获取结果
-echo get_wechat_message_status(user_id, "username", wechat_message_id);
 ```
+
+## 状态查询示例
+
+- 当前页不提供状态查询代码块。
+- 只有在调用侧已经明确提供 `username` 来源时，才继续生成 `get_wechat_message_status(...)` 调用。