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

📝 docs(tsl): restructure agent-facing reference

Browse Source 
Rework TSL syntax, catalog, modules, and routing docs around deterministic agent lookup and generation.

Split large catalog pages into focused function fact pages, remove obsolete pending/verified/unavailable paths, and update consistency tests for the new structure.
This commit is contained in:
csh
2026-06-09 17:24:30 +08:00
parent 9c194170a1
commit 540b3c0a1b
192 changed files with 32929 additions and 13533 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tsl/index.md
+60 -111
View File
@@ -1,134 +1,83 @@
# TSL Index
# TSL 文档入口
文档类型：检索页
是否可直接用于生成代码：否
是否含已验证可执行示例：否
是否含已验证反例：否
遇到不确定时跳转到：[syntax/index.md](syntax/index.md)、[finance/index.md](finance/index.md)、[reference/index.md](reference/index.md)、[modules/index.md](modules/index.md)、项目自身文档、`scripts/*` 入口脚本、CI 配置
是否含可直接照写示例：否
是否含不可照写反例：否
遇到不确定时：先按本文“任务路由”分层；语法问题看 [syntax/index.md](syntax/index.md)，函数库查询看 [reference/index.md](reference/index.md)，模块 / 集成看 [modules/index.md](modules/index.md)，项目执行问题回项目自身文档、`scripts/*` 入口脚本和 CI 配置
这个入口文件只负责一件事：让 agent 先判断主问题属于哪一层，再进入最相关的单个入口页。这里的语法文档面向 agent 决策，不按人类教程组织；回答和生成代码时必须按流程读，不要凭语言相似性补全。
本入口只负责一件事：让智能体先判断主问题属于哪一层，再进入最相关的单个入口页。本套 TSL 文档面向智能体决策，不按人类教程组织；回答和生成代码时必须按流程读，不要凭语言相似性补全。
## 先记住这些规则
## 起手规则
- 先读本文件，不要默认通读全部 TSL 文档。
- 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，再根据用户交付目标判断。
- `.tsl` 是可执行脚本；`.tsf` 是部署到解释器 `funcext` 的模块/函数扩展文件。
- 写 `.tsl` 时按两段理解：语句区在前并按顺序执行；函数/类声明区在后，供前面的语句调用或运行时解析。
- 写 `.tsf` 时按模块/扩展理解；顶层函数部署到 `funcext` 后，`.tsl` 脚本可以直接调用。
- 语言怎么写的问题，先从 `docs/tsl/syntax/` 开始。
- 指标、选股、回测和策略流程的问题，先从 `docs/tsl/finance/` 开始；不要先把业务问题拆成纯语法问题。
- 某个函数怎么用、属于哪个函数库分类或目录，先从 `docs/tsl/reference/` 开始。
- 现成模块、外部集成和互操作问题，先从 [modules/index.md](modules/index.md) 开始。
- 账户体系、真实接口名、部署方式、脚本入口、权限模型、环境变量、CI、验证命令这类问题，先按“项目依赖 / 项目执行”处理；优先回项目自身文档、`scripts/*` 入口脚本、CI 配置。
- [toolchain.md](toolchain.md) 不是 TSL 语法子类，而是项目执行类辅证页；只有当前项目已经补齐工具链与验证信息时才使用；如果这页仍是模板，不把它当主入口。
- 生成 `.tsl` 代码时，优先从脚本语句区开始；如果关键词要求函数或类，把声明放在语句区之后。
- 不要在 `.tsl` 的函数/类声明区之后再追加新的脚本语句。
- 任何语法判断都先看正式语法页结论。
- 如果涉及较新写法、资料冲突或解释器差异，先回到 `docs/tsl/syntax/index.md`，再按主题跳到对应语法页；对应主题页仍然没有结论时，不要自行补语法。
- 如果涉及高频误写、反例或负向边界，优先回到 `docs/tsl/syntax/12_pitfalls.md`；结论缺失时不要把猜测写成语法事实。
- 模板、错误示例和输出片段不算可独立编译代码。
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 语法页面向 agent 生成代码；所有写成语法事实的代码库样例，必须先由维护者在项目验证环境中确认。
- 正向代码库样例只有在环境验证通过后，才能标成 `已验证可执行示例`；对应输出只能标成 `已验证输出片段`。
- 负向代码库样例只有在环境中确认失败形态后，才能标成 `反例 / 不可照写`。
- 未经过环境验证的写法不能写成语法事实；只能作为文档缺口、待验证项，或标成 `配置片段 / 概念骨架`。
- 验证过程不写进语法页；解释器路径、Docker、Windows、Ubuntu、环境变量和执行命令属于项目执行层，不能混入通用语法事实。
- agent 不需要自行执行验证；agent 只根据维护者已经写入文档的证据标签生成代码，遇到未覆盖写法时不要发明语法。
- TSL 语法页面面向智能体生成代码；写成语法事实的内容就是生成依据，不再要求智能体自行证明。
- `可直接照写示例` 用于参考代码外形、语句顺序和块级结构。
- `输出片段` 只用于理解返回结果或错误形态，不作为代码照写。
- `反例 / 不可照写` 只用于避开对应写法，不反向推导新的语法。
- `配置片段 / 概念骨架` 只说明结构或配置位置，不代表可直接运行。
- 文档没有覆盖的写法不能生成；应向用户确认、记录文档缺口，或回到项目实际代码寻找证据。
- 执行环境细节不写进语法页；项目执行信息不能混入通用 TSL 事实。
## 新 session 起手规则
## 任务路由
### Agent 读取流程
| 任务 | 先读哪里 |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 我要系统入门 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) |
1. 识别目标层：语法、金融业务、函数库、模块/集成、项目执行。
2. 识别用户指定的文件后缀；用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据。
3. 用户未给后缀时，按交付目标判断：可执行代码对应 `.tsl`，通用模块对应 `.tsf`；仍不明确时向用户确认。
4. 对 `.tsl`，先生成语句区；需要本文件函数/类时，再生成声明区。
5. 对 `.tsf`，生成模块/扩展声明；部署后的顶层函数可由脚本直接调用。
6. 只读取当前任务命中的单个入口页；不要同时展开语法、业务、函数库和工具链。
7. 生成代码前找 `代码块身份：已验证可执行示例`；遇到 `反例 / 不可照写` 必须避开。
## 路由冲突处理
### If / Then 路由
- 如果一个问题同时涉及业务和语法，先按主问题分层。
- 如果主问题是业务实现，先走 `modules/`、`reference/catalog/datawarehouse.md` 或项目实际接口文档，语法只作辅证，不反过来吞掉业务入口。
- 如果主问题是语言写法，先走 `syntax/`，金融或模块页只作为示例和上下文。
- 如果主问题已经落到真实接入参数、账号来源、部署依赖、执行入口或权限模型，直接转“项目依赖 / 项目执行”确认，不继续在 `modules/`、`syntax/` 或模板型 `toolchain.md` 里兜圈子。
- If 问题在问“语言怎么写”，then 先从 [syntax/index.md](syntax/index.md) 开始。
- If 问题在问“指标 / 选股 / 回测怎么组织”，then 先从 [finance/index.md](finance/index.md) 开始。
- If 问题在问“某个函数怎么用”或“函数属于哪个函数库分类 / 目录”，then 先从 [reference/index.md](reference/index.md) 开始。
- If 问题在问“现成模块 / 集成 / 互操作”，then 先从 [modules/index.md](modules/index.md) 开始。
- If 问题依赖项目实际接口、账户体系、部署方式、脚本入口、权限模型、环境变量、CI 或验证命令，then 不把它当通用 TSL 事实；优先回项目自身文档、`scripts/*` 入口脚本、CI 配置；只有当前项目已补齐时，才把 [toolchain.md](toolchain.md) 当辅证页。
- If 问题在问“这句语法能不能写”，then 先从 [syntax/index.md](syntax/index.md) 开始。
- If 问题在问“较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界”，then 先看 [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页。
- If 问题在问“高频误写 / 反例核对 / 负向边界”，then 先看 [syntax/12_pitfalls.md](syntax/12_pitfalls.md)。
## 通用 TSL 语法骨架路径
### Tie-Break
只有主问题是语言写法、最短骨架或语法有效性时，才从本节起手；如果主问题是模块集成、函数库查询或项目执行，先回到“任务路由”。
- If 一个问题同时涉及业务和语法，then 先按主问题分层。
- If 主问题是业务实现，then 先走 `finance/` 或 `modules/`，语法只作辅证，不反过来吞掉业务入口。
- If 主问题是语言写法，then 先走 `syntax/`，金融或模块页只作为示例和上下文。
- If 主问题已经落到真实接入参数、账号来源、部署依赖、执行入口或权限模型，then 直接转“项目依赖 / 项目执行”确认，不继续在 `modules/`、`syntax/` 或模板型 `toolchain.md` 里兜圈子。
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)。
### 语言事实
## 智能体提交前最低自检
- 可以先把 TSL 当成 Pascal 风格语言去理解：`function`、`begin`、`end`、`unit`、`uses` 都很接近；但这里只借外形，不默认继承 Pascal 的全部语义、库习惯和文件模型。
- 涉及赋值、`.tsl` 语句区 / 声明区、`.tsf` 模块、`function / procedure` 外形、`unit` 骨架、命名参数、`type Name = class`、数组 / 字符串下标这类高频硬规则，统一以 [syntax/02_quickstart.md](syntax/02_quickstart.md) 的“语言核心事实速查”为准；当前页只保留跨层路由所需的最小提醒。
#### 写代码前先记住
- 写代码前先把高频硬规则收口到 [syntax/02_quickstart.md](syntax/02_quickstart.md)，不要分别从入口页、介绍页和文件模型页拼接结论。
- `.tsl` 仍优先按“语句区在前、声明区在后”的脚本模型理解；`.tsf` 仍优先按部署到 `funcext` 的模块/扩展理解。
- 模板、错误示例和输出片段不算可独立编译代码；真正落代码时优先看块级 `代码块身份`。
### 手册建模规则
- 更可靠的识别方式是同时看任务目标和顶层内容，而不是只看文件扩展名。
- 顶层允许出现 `uses`，但这里只把它当辅助语句，不把它当主体声明。
- 下游大量 `program test; begin ... end.` 形式，只作为自包含验证样例外壳，不作为这里归纳的正式顶层模型。
## 如果你马上要写 TSL
- 先看 [syntax/02_quickstart.md](syntax/02_quickstart.md)
- 再看 [syntax/index.md](syntax/index.md)
- 然后看 [syntax/12_pitfalls.md](syntax/12_pitfalls.md)
- 最后按需补看相应专题页
## 最短跳转
| 当前任务 | 先读哪里 |
| ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| 我要系统入门 TSL | [syntax/index.md](syntax/index.md) |
| 我要先核对语言核心事实 | [syntax/02_quickstart.md](syntax/02_quickstart.md) |
| 我要写最短可运行骨架 | [syntax/02_quickstart.md](syntax/02_quickstart.md) |
| 我要判断“这句语法能不能写” | [syntax/index.md](syntax/index.md) |
| 我要核对较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界 | [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页 |
| 我要核对高频误写 / 反例 / 负向边界 | [syntax/12_pitfalls.md](syntax/12_pitfalls.md) |
| 我要知道正式语法手册现在还差什么 | [syntax/coverage_map.md](syntax/coverage_map.md) |
| 我要写金融指标 / 选股 / 回测 | [finance/index.md](finance/index.md) |
| 我要看模块 / 集成 / 互操作入口 | [modules/index.md](modules/index.md) |
| 我要确认账户体系 / 真实接口 / 部署方式 / 脚本入口 / 环境变量 / CI / 验证命令 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；当前项目已补齐时再看 [toolchain.md](toolchain.md) |
| 我要看回测框架模块 | [modules/tsbacktesting.md](modules/tsbacktesting.md) |
| 我要看 Python 互操作 | [modules/tsl_python_interop.md](modules/tsl_python_interop.md) |
| 我要看微信消息推送 | [modules/wechat_message.md](modules/wechat_message.md) |
| 我要看 Python API | [modules/pytsl_api.md](modules/pytsl_api.md) |
| 我要查函数库 | [reference/index.md](reference/index.md) |
| 当前项目已补齐工具链时，看工具链 / 项目执行辅证 | [toolchain.md](toolchain.md) |
| 我要避开高频误写 | [syntax/12_pitfalls.md](syntax/12_pitfalls.md) |
## 进入之后怎么读
1. 先判断主问题属于语法、业务、函数库、模块/集成，还是项目依赖 / 项目执行。
2. 如果主问题是项目依赖 / 项目执行，直接回项目自身文档、`scripts/*` 入口脚本或 CI 配置；只有当前项目已经补齐时，才把 [toolchain.md](toolchain.md) 当辅证。
3. 否则先进入一个最相关的入口页，不要同时展开多个层。
4. 当前页如果已经给出结论，先采用；准备编写时优先找已验证正例，再落代码；只有需要补充时再跳到相邻页。
5. 遇到“资料写法不一致”且偏较新写法、资料冲突或解释器差异时，先回 [syntax/index.md](syntax/index.md) 按主题跳到对应语法页。
6. 遇到“资料写法不一致”且偏高频误写、反例或负向边界时，先看 [syntax/12_pitfalls.md](syntax/12_pitfalls.md)。
7. 如果当前手册没有给出结论，不要发明语法；改为向用户确认、记录文档缺口，或等待维护者用项目环境补充已验证结论。
1. 是否已经判断主问题属于语法、函数库、模块/集成或项目执行。
2. 如果要生成代码，是否已经确认 `.tsl` / `.tsf` 文件模型。
3. 是否优先参考了 `代码块身份：可直接照写示例`。
4. 是否避开了 `反例 / 不可照写`、输出片段和概念骨架。
5. 是否没有凭 Pascal、Python、JavaScript、TypeScript 或其它语言相似性补全 TSL 语法。
6. 是否没有把项目执行信息、账户体系、真实接口或验证命令写成通用 TSL 事实。
7. 仍不确定的地方是否明确说明，而不是隐藏在生成代码里。