playbook/docs/tsl/index.md

TSL Index

文档类型：检索页 是否可直接用于生成代码：否 是否含已验证可执行示例：否 是否含已验证反例：否 遇到不确定时跳转到：syntax/index.md、finance/index.md、reference/index.md、modules/index.md、项目自身文档、scripts/* 入口脚本、CI 配置

这个入口文件只负责一件事：让新 session 先判断主问题属于哪一层，再进入最相关的单个入口页。

先记住这些规则

• 先读本文件，不要默认通读全部 TSL 文档。
• 语言怎么写的问题，先从 docs/tsl/syntax/ 开始。
• 指标、选股、回测和策略流程的问题，先从 docs/tsl/finance/ 开始；不要先把业务问题拆成纯语法问题。
• 某个函数怎么用、属于哪个函数库分类或目录，先从 docs/tsl/reference/ 开始。
• 现成模块、外部集成和互操作问题，先从 modules/index.md 开始。
• 账户体系、真实接口名、部署方式、脚本入口、权限模型、环境变量、CI、验证命令这类问题，先按“项目依赖 / 项目执行”处理；优先回项目自身文档、scripts/* 入口脚本、CI 配置。
• toolchain.md 不是 TSL 语法子类，而是项目执行类辅证页；只有当前项目已经补齐工具链与验证信息时才使用；如果这页仍是模板，不把它当主入口。
• 顶层主体优先按四类理解：松散语句、function / procedure、type Name = class、unit。
• 不要把顶层 function / procedure 定义和松散语句混在同一个文件模型里。
• 任何语法判断都先看正式语法页结论。
• 如果涉及较新写法、资料冲突或解释器差异，先回到 docs/tsl/syntax/index.md，再按主题跳到对应语法页；只有对应主题页仍然没有结论时，才本地用 tsl 验证。
• 如果涉及高频误写、反例或负向边界，优先回到 docs/tsl/syntax/12_pitfalls.md；只有结论缺失时，才本地用 tsl 验证。
• 模板、错误示例和输出片段不算可独立编译代码。

元数据与证据标签

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

新 session 起手规则

If / Then 路由

• If 问题在问“语言怎么写”，then 先从 syntax/index.md 开始。
• If 问题在问“指标 / 选股 / 回测怎么组织”，then 先从 finance/index.md 开始。
• If 问题在问“某个函数怎么用”或“函数属于哪个函数库分类 / 目录”，then 先从 reference/index.md 开始。
• If 问题在问“现成模块 / 集成 / 互操作”，then 先从 modules/index.md 开始。
• If 问题依赖项目实际接口、账户体系、部署方式、脚本入口、权限模型、环境变量、CI 或验证命令，then 不把它当通用 TSL 事实；优先回项目自身文档、scripts/* 入口脚本、CI 配置；只有当前项目已补齐时，才把 toolchain.md 当辅证页。
• If 问题在问“这句语法能不能写”，then 先从 syntax/index.md 开始。
• If 问题在问“较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界”，then 先看 syntax/index.md，再按主题跳到对应语法页。
• If 问题在问“高频误写 / 反例核对 / 负向边界”，then 先看 syntax/12_pitfalls.md。

Tie-Break

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

语言事实

• 可以先把 TSL 当成 Pascal 风格语言去理解：function、begin、end、unit、uses 都很接近；但这里只借外形，不默认继承 Pascal 的全部语义、库习惯和文件模型。
• 涉及赋值、function / procedure 外形、unit 骨架、命名参数、type Name = class、数组 / 字符串下标这类高频硬规则，统一以 syntax/02_quickstart.md 的“语言核心事实速查”为准；当前页只保留跨层路由所需的最小提醒。

写代码前先记住

• 写代码前先把高频硬规则收口到 syntax/02_quickstart.md，不要分别从入口页、介绍页和文件模型页拼接结论。
• 顶层主体仍优先按四类理解：松散语句、function / procedure、type Name = class、unit。
• 模板、错误示例和输出片段不算可独立编译代码；真正落代码时优先看块级 代码块身份。

手册建模规则

• 更可靠的识别方式是看顶层内容，而不是只看文件扩展名。
• 顶层允许出现 uses，但这里只把它当辅助语句，不把它当主体声明。
• 下游大量 program test; begin ... end. 形式，只作为自包含验证样例外壳，不作为这里归纳的正式顶层模型。

如果你马上要写 TSL

• 先看 syntax/02_quickstart.md
• 再看 syntax/index.md
• 然后看 syntax/12_pitfalls.md
• 最后按需补看相应专题页

最短跳转

当前任务	先读哪里
我要系统入门 TSL	syntax/index.md
我要先核对语言核心事实	syntax/02_quickstart.md
我要写最短可运行骨架	syntax/02_quickstart.md
我要判断“这句语法能不能写”	syntax/index.md
我要核对较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界	syntax/index.md，再按主题跳到对应语法页
我要核对高频误写 / 反例 / 负向边界	syntax/12_pitfalls.md
我要知道正式语法手册现在还差什么	syntax/coverage_map.md
我要写金融指标 / 选股 / 回测	finance/index.md
我要看模块 / 集成 / 互操作入口	modules/index.md
我要确认账户体系 / 真实接口 / 部署方式 / 脚本入口 / 环境变量 / CI / 验证命令	项目自身文档、scripts/* 入口脚本、CI 配置；当前项目已补齐时再看 toolchain.md
我要看回测框架模块	modules/tsbacktesting.md
我要看 Python 互操作	modules/tsl_python_interop.md
我要看微信消息推送	modules/wechat_message.md
我要看 Python API	modules/pytsl_api.md
我要查函数库	reference/index.md
当前项目已补齐工具链时，看工具链 / 项目执行辅证	toolchain.md
我要避开高频误写	syntax/12_pitfalls.md

进入之后怎么读

1. 先判断主问题属于语法、业务、函数库、模块/集成，还是项目依赖 / 项目执行。
2. 如果主问题是项目依赖 / 项目执行，直接回项目自身文档、scripts/* 入口脚本或 CI 配置；只有当前项目已经补齐时，才把 toolchain.md 当辅证。
3. 否则先进入一个最相关的入口页，不要同时展开多个层。
4. 当前页如果已经给出结论，先采用；准备编写时优先找已验证正例，再落代码；只有需要补充时再跳到相邻页。
5. 遇到“资料写法不一致”且偏较新写法、资料冲突或解释器差异时，先回 syntax/index.md 按主题跳到对应语法页。
6. 遇到“资料写法不一致”且偏高频误写、反例或负向边界时，先看 syntax/12_pitfalls.md。
7. 只有当前手册没有给出结论时，才写最小 .tsl / .tsf 例子并用 tsl 实测。