📝 docs(tsl): restructure agent-facing reference
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:
+48
-130
@@ -1,148 +1,66 @@
|
||||
# Syntax Index
|
||||
# TSL 语法入口
|
||||
|
||||
文档类型：检索页
|
||||
是否可直接用于生成代码：否
|
||||
是否含已验证可执行示例：否
|
||||
是否含已验证反例：否
|
||||
遇到不确定时跳转到：[02_quickstart.md](02_quickstart.md)（优先）、[03_core_model.md](03_core_model.md)、[07_expressions_and_operators.md](07_expressions_and_operators.md)、[09_objects_and_classes.md](09_objects_and_classes.md)、[12_pitfalls.md](12_pitfalls.md)
|
||||
是否含可直接照写示例：否
|
||||
是否含不可照写反例：否
|
||||
遇到不确定时：先按本文“按任务跳转”做语法层分流；写最短骨架看 [01_quickstart.md](01_quickstart.md)，判断文件模型看 [02_core_model.md](02_core_model.md)，判断表达式看 [06_expressions_and_operators.md](06_expressions_and_operators.md)，判断类/对象看 [08_objects_and_classes.md](08_objects_and_classes.md)，核对反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)。
|
||||
|
||||
这里是 TSL 语法手册入口。只处理“agent 应该怎样识别并生成语言写法”，不处理金融业务语义。本文档不是人类教程；它给 agent 提供判断顺序、关键词分流和可靠示例入口。
|
||||
本页只做语法层路由。生成代码时不要顺序读完整套语法文档；先判断任务命中哪一类，再进入最小专题页。
|
||||
|
||||
## 元数据读法
|
||||
## 元数据与代码块身份
|
||||
|
||||
- 页头里的 `是否可直接用于生成代码` 是页面级粗判断；真正落代码时，优先看每个代码块自己的 `代码块身份`。
|
||||
- `是否可直接用于生成代码` 有三种值：`是`、`否`、`仅部分`；其中 `仅部分` 表示这一页同时含有可直接参考的代码块，以及依赖多文件、查找路径或运行时环境的代码块。
|
||||
- `是否含已验证可执行示例` 只表示这一页存在已跑通的正向代码示例。
|
||||
- `是否含已验证反例` 只表示这一页存在已经确认不能照写的负例。
|
||||
- `代码块身份` 固定只用四种值：`已验证可执行示例`、`已验证输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。
|
||||
- 如果代码块后面还有用途或限制说明，会单独写成 `代码块说明`，不继续混进 `代码块身份`。
|
||||
- 如果页头里的 `遇到不确定时跳转到` 给出多个目标，默认第一项是优先入口，后面的目标用于分流或补证。
|
||||
- 页头 `是否可直接用于生成代码` 只做页面级粗判断；落代码时以块级 `代码块身份` 为准。
|
||||
- `代码块身份` 固定只用四种值：`可直接照写示例`、`输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。
|
||||
- 普通语法专题页的 `遇到不确定时` 先按候选页继续判断，仍不命中再回本语法入口页；本页例外，必须先按“按任务跳转”分流。
|
||||
|
||||
## 这本手册怎么读
|
||||
## 智能体语法判断流程
|
||||
|
||||
- 默认先走“Agent 判断流程”和“按任务跳转”，不要先顺序读完整套。
|
||||
- 只有刻意系统学习时，才按下面的“推荐读法”顺序进入。
|
||||
- 当前这套正式语法手册不再只覆盖主线入门，而是负责完整吸收旧 8 个语言章节。
|
||||
|
||||
## Agent 判断流程
|
||||
|
||||
1. 先识别用户是否已经给出 `.tsl` / `.tsf` 后缀；给出后缀时，后缀就是判断依据。
|
||||
2. 未给后缀时，再按交付目标判断：可执行代码对应 `.tsl`，通用模块对应 `.tsf`；仍不明确时向用户确认。
|
||||
3. 如果是 `.tsl`，按可执行脚本处理：先写语句区，语句按顺序执行；需要函数/类时，把声明区放在语句区之后。
|
||||
4. 如果是 `.tsf`，按模块/函数扩展处理：生成可部署到解释器 `funcext` 的声明；部署后脚本可以直接调用暴露的顶层函数。
|
||||
5. 再识别关键词属于值/变量、函数、类、unit、表达式、控制流、运行时、TS-SQL 或其他专题。
|
||||
6. 只进入关键词命中的最小页面；写代码前优先复制已验证可执行示例的结构，不要从多个页面拼接未经验证的新骨架。
|
||||
7. 遇到反例、解释器差异或资料冲突时，先按 [12_pitfalls.md](12_pitfalls.md) 和对应专题页收口；仍无结论时不要发明语法。
|
||||
|
||||
## 如果你马上要写 TSL
|
||||
|
||||
1. [02_quickstart.md](02_quickstart.md)（先看语言核心事实速查和最短骨架）
|
||||
2. [03_core_model.md](03_core_model.md)
|
||||
3. [06_functions_and_calls.md](06_functions_and_calls.md)
|
||||
4. [12_pitfalls.md](12_pitfalls.md)
|
||||
5. 涉及较新写法时，按主题跳到对应专题页
|
||||
|
||||
## 推荐读法
|
||||
|
||||
1. [01_introduction.md](01_introduction.md)
|
||||
2. [02_quickstart.md](02_quickstart.md)
|
||||
3. [03_core_model.md](03_core_model.md)
|
||||
4. [04_values_and_literals.md](04_values_and_literals.md)
|
||||
5. [05_variables_and_constants.md](05_variables_and_constants.md)
|
||||
6. [06_functions_and_calls.md](06_functions_and_calls.md)
|
||||
7. [07_expressions_and_operators.md](07_expressions_and_operators.md)
|
||||
8. [08_control_flow.md](08_control_flow.md)
|
||||
9. [09_objects_and_classes.md](09_objects_and_classes.md)
|
||||
10. [10_units_and_scope.md](10_units_and_scope.md)
|
||||
11. [11_runtime_context_and_with.md](11_runtime_context_and_with.md)
|
||||
12. [12_pitfalls.md](12_pitfalls.md)
|
||||
13. [13_matrix_and_collections.md](13_matrix_and_collections.md)
|
||||
14. [14_resultset_and_filters.md](14_resultset_and_filters.md)
|
||||
15. [15_ts_sql.md](15_ts_sql.md)
|
||||
16. [16_debug_and_profiler.md](16_debug_and_profiler.md)
|
||||
这条顺序对应“先建立整体读法，再写值、变量、函数、表达式、流程，随后进入类、unit、运行时边界，再按需进入进阶专题”。
|
||||
|
||||
编号说明：主线 `01-16`，深水 `18-32`，无 `17` 号正文页；历史 `17` 号位保留为空。
|
||||
|
||||
## 深水专题
|
||||
|
||||
以下专题默认不要预读。只有主线页不够、或者任务已经明确命中对应场景时，再进入。
|
||||
|
||||
| 专题 | 什么时候进入 |
|
||||
| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
|
||||
| [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md) | 只有涉及注释规则、条件编译、编译选项或词法边界时才读 |
|
||||
| [19_types_and_conversions.md](19_types_and_conversions.md) | 只有涉及显式类型、转换规则或类型兼容问题时才读 |
|
||||
| [20_strings_and_text.md](20_strings_and_text.md) | 只有涉及字符串处理、编码或文本细节时才读 |
|
||||
| [21_external_calls_and_threads.md](21_external_calls_and_threads.md) | 只有涉及 `external`、DLL、线程或外部调用时才读 |
|
||||
| [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) | 只有涉及 `namespace`、`Libpath`、unit 运行时或查找路径时才读 |
|
||||
| [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) | 只有涉及对象运行时、自省或反射能力时才读 |
|
||||
| [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md) | 只有涉及内置运行时对象时才读 |
|
||||
| [25_set_operations.md](25_set_operations.md) | 只有涉及集合运算专题时才读 |
|
||||
| [26_matrix_deep_dive.md](26_matrix_deep_dive.md) | 只有涉及矩阵运算且 [13_matrix_and_collections.md](13_matrix_and_collections.md) 不够用时才读 |
|
||||
| [27_fmarray.md](27_fmarray.md) | 只有涉及 `FMArray` 专题时才读 |
|
||||
| [28_ts_sql_core.md](28_ts_sql_core.md) | 只有开始写 TS-SQL 核心语法时才读 |
|
||||
| [29_ts_sql_advanced.md](29_ts_sql_advanced.md) | 只有 TS-SQL 基础页不够、问题进入进阶能力时才读 |
|
||||
| [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) | 只有涉及网格计算、运行时服务或全局缓存时才读 |
|
||||
| [31_complex_and_weakref.md](31_complex_and_weakref.md) | 只有涉及复数或弱引用时才读 |
|
||||
| [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | 只有涉及对象算符重载或遍历重载时才读 |
|
||||
|
||||
这组页面承担旧 8 章里没有被主线正文完整吃掉的深水内容，目标是让新 session 只靠 `docs/tsl/syntax/` 就能覆盖旧语法章节，但默认首跳仍应先走主线页。
|
||||
1. 先判断文件模型；完整规则看 [02_core_model.md](02_core_model.md)。
|
||||
2. 用户已给 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，入口流程或一次性脚本初判为 `.tsl`，可复用交付物初判为 `.tsf`。
|
||||
3. 文件模型会影响正确性且目标不明确时，先向用户确认。
|
||||
4. 识别关键词属于值/变量、函数、类、unit、表达式、控制流、运行时、TS-SQL 或进阶专题。
|
||||
5. 只进入命中的最小页面；写代码前优先参考该页的可直接照写示例。
|
||||
6. 命中反例或负向边界时，先看 [11_pitfalls.md](11_pitfalls.md) 和对应专题页；仍无结论时不要发明语法。
|
||||
|
||||
## 按任务跳转
|
||||
|
||||
| 当前任务 | 先读哪里 |
|
||||
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| 先建立整体读法 | [01_introduction.md](01_introduction.md) |
|
||||
| 写最短骨架 | [02_quickstart.md](02_quickstart.md) |
|
||||
| 判断顶层模型 / 文件模型 | [03_core_model.md](03_core_model.md) |
|
||||
| 写值、数组、字符串 | [04_values_and_literals.md](04_values_and_literals.md) |
|
||||
| 写变量、常量、显式声明 | [05_variables_and_constants.md](05_variables_and_constants.md) |
|
||||
| 写 `function` / `procedure`、参数修饰、默认参数、命名参数、变参、`external` | [06_functions_and_calls.md](06_functions_and_calls.md) |
|
||||
| 写赋值、比较、`if` 表达式 | [07_expressions_and_operators.md](07_expressions_and_operators.md) |
|
||||
| 写 `?.` 等较新表达式 | [07_expressions_and_operators.md](07_expressions_and_operators.md) |
|
||||
| 写条件、循环、异常控制 | [08_control_flow.md](08_control_flow.md) |
|
||||
| 写类、继承、property、静态字段 | [09_objects_and_classes.md](09_objects_and_classes.md) |
|
||||
| 写 `unit` / `uses` | [10_units_and_scope.md](10_units_and_scope.md) |
|
||||
| 写运行时环境参数、`SysParams[...]`、`#Func() with array(...)` | [11_runtime_context_and_with.md](11_runtime_context_and_with.md) |
|
||||
| 先避开高频误写 | [12_pitfalls.md](12_pitfalls.md) |
|
||||
| 写数组扩展、键表、矩阵样数据 | [13_matrix_and_collections.md](13_matrix_and_collections.md) |
|
||||
| 写结果集过滤专题 | [14_resultset_and_filters.md](14_resultset_and_filters.md) |
|
||||
| 写 TS-SQL 专题 | [15_ts_sql.md](15_ts_sql.md) |
|
||||
| 看调试与 profiler 专题 | [16_debug_and_profiler.md](16_debug_and_profiler.md) |
|
||||
| 看词法、注释、编译选项 | [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md) |
|
||||
| 看类型与转换 | [19_types_and_conversions.md](19_types_and_conversions.md) |
|
||||
| 看字符串与编码专题 | [20_strings_and_text.md](20_strings_and_text.md) |
|
||||
| 看 `external`、DLL 与多线程 | [21_external_calls_and_threads.md](21_external_calls_and_threads.md) |
|
||||
| 看 `namespace`、单元运行时、`Libpath`、查找路径 | [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) |
|
||||
| 看对象运行时和反射 | [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) |
|
||||
| 看运行时内置对象 | [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md) |
|
||||
| 看集合运算 | [25_set_operations.md](25_set_operations.md) |
|
||||
| 看矩阵深水专题 | [26_matrix_deep_dive.md](26_matrix_deep_dive.md) |
|
||||
| 看 `FMArray` | [27_fmarray.md](27_fmarray.md) |
|
||||
| 看 TS-SQL 基础 | [28_ts_sql_core.md](28_ts_sql_core.md) |
|
||||
| 看 TS-SQL 进阶 | [29_ts_sql_advanced.md](29_ts_sql_advanced.md) |
|
||||
| 看网格计算与全局缓存 | [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) |
|
||||
| 看复数与弱引用 | [31_complex_and_weakref.md](31_complex_and_weakref.md) |
|
||||
| 看对象算符与遍历重载 | [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) |
|
||||
| 看较新表达式或表达式边界 | [07_expressions_and_operators.md](07_expressions_and_operators.md) |
|
||||
| 看较新对象能力或类边界 | [09_objects_and_classes.md](09_objects_and_classes.md) |
|
||||
| 看资料冲突 / 解释器差异 | 先留在当前页，对照上面的主线与深水进入条件后，再按主题进入相应页面 |
|
||||
| 看高频误写 / 反例 / 负向边界 | [12_pitfalls.md](12_pitfalls.md) |
|
||||
| 看正式语法手册当前覆盖范围与成熟度 | [coverage_map.md](coverage_map.md) |
|
||||
| 任务 | 先读哪里 |
|
||||
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
||||
| 写最短骨架 / 语言核心事实 | [01_quickstart.md](01_quickstart.md) |
|
||||
| 判断 `.tsl` / `.tsf`、顶层语句区、声明区、文件模型 | [02_core_model.md](02_core_model.md) |
|
||||
| 写值、数组、字符串、字符串编码边界 | [03_values_and_literals.md](03_values_and_literals.md) |
|
||||
| 写变量、常量、显式声明 | [04_variables_and_constants.md](04_variables_and_constants.md) |
|
||||
| 写 `function` / `procedure`、参数、默认参数、命名参数、变参 | [05_functions_and_calls.md](05_functions_and_calls.md) |
|
||||
| 写赋值、比较、条件表达式、较新表达式、运算符边界 | [06_expressions_and_operators.md](06_expressions_and_operators.md) |
|
||||
| 写条件、循环、异常控制 | [07_control_flow.md](07_control_flow.md) |
|
||||
| 写类、继承、property、静态字段、较新对象能力或类边界 | [08_objects_and_classes.md](08_objects_and_classes.md) |
|
||||
| 写 `unit` / `uses` | [09_units_and_scope.md](09_units_and_scope.md) |
|
||||
| 写运行时环境参数、`sysParams[...]`、`with array(...)`、网格调用或全局缓存 | [10_runtime_context_and_with.md](10_runtime_context_and_with.md) |
|
||||
| 核对高频误写 / 反例 / 负向边界 | [11_pitfalls.md](11_pitfalls.md) |
|
||||
| 写数组扩展、键表、集合运算、矩阵样数据 | [12_matrix_and_collections.md](12_matrix_and_collections.md) |
|
||||
| 写结果集过滤专题 | [13_resultset_and_filters.md](13_resultset_and_filters.md) |
|
||||
| 写 TS-SQL 专题 | [14_ts_sql.md](14_ts_sql.md) |
|
||||
| 看调试与性能分析器专题 | [15_debug_and_profiler.md](15_debug_and_profiler.md) |
|
||||
| 看注释、条件编译、编译选项或词法边界 | [16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md) |
|
||||
| 看显式类型、转换规则、复数 | [17_types_and_conversions.md](17_types_and_conversions.md) |
|
||||
| 看 `external`、DLL 与多线程 | [18_external_calls_and_threads.md](18_external_calls_and_threads.md) |
|
||||
| 看 `namespace`、`Libpath`、unit 运行时、查找路径 | [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md) |
|
||||
| 看对象运行时、自省、反射、弱引用 | [20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md) |
|
||||
| 看运行时内置对象 | [21_builtin_runtime_objects.md](21_builtin_runtime_objects.md) |
|
||||
| 看矩阵进阶专题 | [22_matrix_deep_dive.md](22_matrix_deep_dive.md) |
|
||||
| 看 `FMArray` | [23_fmarray.md](23_fmarray.md) |
|
||||
| 看对象算符重载或遍历重载 | [24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md) |
|
||||
|
||||
## 旧 8 章在正式手册中的落点
|
||||
## 入口禁止项
|
||||
|
||||
- `01_language_basics.md`：主线落在 `01` `03` `04` `05` `07` `11` `13`，深水落在 `18` `19` `20`
|
||||
- `02_control_flow.md`：主线落在 `08`，调试与性能补充落在 `16`
|
||||
- `03_functions.md`：主线落在 `06`，系统交互补充落在 `21`
|
||||
- `04_modules_and_namespace.md`：主线落在 `10`，单元运行时与查找路径补充落在 `22`
|
||||
- `05_object_model.md`：主线落在 `09`，运行时 / 内置对象 / 重载补充落在 `23` `24` `32`
|
||||
- `06_extended_syntax.md`：主线入口在 `13` `14` `15`，深水落在 `25` `26` `27` `28` `29`
|
||||
- `07_debug_and_profiler.md`：入口在 `16`，服务层运行时补充落在 `30`
|
||||
- `08_new_generation.md`：表达式与对象主线落在 `07` `09`，复数 / 弱引用 / 对象重载落在 `31` `32`
|
||||
- 不要跳过“智能体语法判断流程”和“按任务跳转”直接顺序读完整套。
|
||||
- 不要把本入口页当成可直接生成代码的语法事实页。
|
||||
- 不要从多个专题页拼接未写入文档的新骨架；生成前优先使用单页里的可直接照写示例。
|
||||
- 不要把数据仓库函数查询、模块集成或项目执行问题留在语法层处理。
|
||||
|
||||
## 切换到别的层
|
||||
|
||||
- 业务问题：见 [../finance/index.md](../finance/index.md)
|
||||
- 数据仓库金融函数：见 [../reference/catalog/datawarehouse.md](../reference/catalog/datawarehouse.md)
|
||||
- 模块 / 集成 / 互操作：见 [../modules/index.md](../modules/index.md)
|
||||
- 函数库查找：见 [../reference/index.md](../reference/index.md)
|
||||
|
||||
Reference in New Issue
Block a user