# TSL 文档入口

文档类型：检索页
是否可直接用于生成代码：否
是否含可直接照写示例：否
是否含不可照写反例：否
遇到不确定时：先按本文“任务路由”分层；语法问题看 [syntax/index.md](syntax/index.md)，函数库查询看 [reference/index.md](reference/index.md)，模块 / 集成看 [modules/index.md](modules/index.md)，项目执行问题回项目自身文档、`scripts/*` 入口脚本和 CI 配置

本入口只负责一件事：让智能体先判断主问题属于哪一层，再进入最相关的单个入口页。本套 TSL 文档面向智能体决策，不按人类教程组织；回答和生成代码时必须按流程读，不要凭语言相似性补全。

## 起手规则

1. 先判断主问题层：语法、函数库、模块 / 集成，还是项目执行。
2. 只进入命中的单个入口页；不要同时展开语法、业务、函数库、模块和工具链。
3. 如果要生成或修改 TSL 代码，先做文件模型初判；详细规则见 [syntax/02_core_model.md](syntax/02_core_model.md)：
   - 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据。
   - 用户未给后缀时，按交付目标判断：入口流程、脚本任务或一次性执行逻辑对应 `.tsl`；可复用函数、过程、类、模块或扩展对应 `.tsf`。
   - 仍不明确时先向用户确认，不要靠相似语言补全。
4. 写代码前找 `代码块身份：可直接照写示例`；遇到 `反例 / 不可照写`、输出片段或概念骨架必须避开。
5. 语法细节统一进入 [syntax/index.md](syntax/index.md) 后再分流；本页只保留跨层路由需要的最小提醒。
6. 本手册没有结论时，不要发明语法；改为向用户确认、记录文档缺口，或交由维护者补充文档结论。

## 元数据与证据标签

- 页头里的 `是否可直接用于生成代码` 只做页面级粗判断；如果页内已经给出 `代码块身份`，一律以块级标签为准。
- `是否可直接用于生成代码` 有三种值：`是`、`否`、`仅部分`；其中 `仅部分` 表示页内既有可直接参考的块，也有依赖多文件、查找路径或运行时环境的块，必须继续看块级标签。
- `是否含可直接照写示例` 只统计可直接照写的正向代码示例。
- `是否含不可照写反例` 只统计不可照写的负向例子。
- `代码块身份` 只使用固定词表：`可直接照写示例`、`输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。
- 如果还需要补充用途、限制或复用建议，单独写 `代码块说明`，不要把说明文字继续拼进 `代码块身份`。
- 如果页头里的 `遇到不确定时` 列出多个目标，普通专题页默认第一项是优先入口；总入口页例外，必须先按任务路由分层。

## 语法事实使用规则

- TSL 语法页面面向智能体生成代码；写成语法事实的内容就是生成依据，不再要求智能体自行证明。
- `可直接照写示例` 用于参考代码外形、语句顺序和块级结构。
- `输出片段` 只用于理解返回结果或错误形态，不作为代码照写。
- `反例 / 不可照写` 只用于避开对应写法，不反向推导新的语法。
- `配置片段 / 概念骨架` 只说明结构或配置位置，不代表可直接运行。
- 文档没有覆盖的写法不能生成；应向用户确认、记录文档缺口，或回到项目实际代码寻找证据。
- 执行环境细节不写进语法页；项目执行信息不能混入通用 TSL 事实。

## 任务路由

| 任务                                                                         | 先读哪里                                                                                   |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 我要系统入门 TSL                                                             | [syntax/index.md](syntax/index.md)                                                         |
| 我要先核对语言核心事实                                                       | [syntax/01_quickstart.md](syntax/01_quickstart.md)                                         |
| 我要写最短可运行骨架                                                         | [syntax/01_quickstart.md](syntax/01_quickstart.md)                                         |
| 我要判断“这句语法能不能写”                                                   | [syntax/index.md](syntax/index.md)                                                         |
| 我要核对较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界                    | [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页                                 |
| 我要核对高频误写 / 反例 / 负向边界                                           | [syntax/11_pitfalls.md](syntax/11_pitfalls.md)                                             |
| 我要查行情 / 财务 / 板块 / 选股等金融函数                                    | [reference/catalog/datawarehouse.md](reference/catalog/datawarehouse.md)                   |
| 我要用 Python 调 TSL 服务器函数或取金融数据                                  | [modules/pytsl_api.md](modules/pytsl_api.md)                                               |
| 我要写回测框架 / 读取回测结果                                                | [modules/tsbacktesting.md](modules/tsbacktesting.md)                                       |
| 我要看模块 / 集成 / 互操作入口                                               | [modules/index.md](modules/index.md)                                                       |
| 我要确认账户体系 / 真实接口 / 部署方式 / 脚本入口 / 环境变量 / CI / 验证命令 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；有项目文档时再看 [toolchain.md](toolchain.md) |
| 我要查函数库                                                                 | [reference/index.md](reference/index.md)                                                   |

## 路由冲突处理

- 如果一个问题同时涉及业务和语法，先按主问题分层。
- 如果主问题是业务实现，先走 `modules/`、`reference/catalog/datawarehouse.md` 或项目实际接口文档，语法只作辅证，不反过来吞掉业务入口。
- 如果主问题是语言写法，先走 `syntax/`，金融或模块页只作为示例和上下文。
- 如果主问题已经落到真实接入参数、账号来源、部署依赖、执行入口或权限模型，直接转“项目依赖 / 项目执行”确认，不继续在 `modules/`、`syntax/` 或模板型 `toolchain.md` 里兜圈子。

## 通用 TSL 语法骨架路径

只有主问题是语言写法、最短骨架或语法有效性时，才从本节起手；如果主问题是模块集成、函数库查询或项目执行，先回到“任务路由”。

1. 先看 [syntax/01_quickstart.md](syntax/01_quickstart.md) 的语言核心事实和最短骨架。
2. 再按 [syntax/index.md](syntax/index.md) 进入命中的语法专题。
3. 涉及反例、常见误写或负向边界时，看 [syntax/11_pitfalls.md](syntax/11_pitfalls.md)。

## 智能体提交前最低自检

1. 是否已经判断主问题属于语法、函数库、模块/集成或项目执行。
2. 如果要生成代码，是否已经确认 `.tsl` / `.tsf` 文件模型。
3. 是否优先参考了 `代码块身份：可直接照写示例`。
4. 是否避开了 `反例 / 不可照写`、输出片段和概念骨架。
5. 是否没有凭 Pascal、Python、JavaScript、TypeScript 或其它语言相似性补全 TSL 语法。
6. 是否没有把项目执行信息、账户体系、真实接口或验证命令写成通用 TSL 事实。
7. 仍不确定的地方是否明确说明，而不是隐藏在生成代码里。