✨ feat(skills): add tsl syntax reference skill
This commit is contained in:
@@ -15,7 +15,7 @@ Playbook：工程规范与智能体规则合集，当前覆盖：
|
||||
|
||||
- `docs/index.md`：文档导航入口
|
||||
- `docs/common/`：跨语言规范（提交信息、版本号）
|
||||
- `docs/tsl/`：TSL 规范（语法手册、金融业务、模块、函数检索、代码风格、命名、工具链）
|
||||
- `docs/tsl/`：TSL 静态路由、金融业务、模块、函数检索、代码风格、命名和工具链；语法事实由 `tsl-syntax-reference` 管理
|
||||
- `docs/cpp/`：C++ 规范（C++23/Modules、Google 基线、Conan、clangd）
|
||||
- `docs/python/`：Python 规范（Google 基线、black/isort/flake8/pylint/mypy/pytest）
|
||||
- `docs/typescript/`：TypeScript 规范（Google 基线、prettier/eslint/vitest）
|
||||
@@ -84,30 +84,34 @@ project_name = "MyProject"
|
||||
|
||||
```txt
|
||||
Layer 1: rulesets/ (≤50 行/语言，模板源)
|
||||
├─ 语言特有的核心约束
|
||||
├─ 语言核心约束或事实所有者路由
|
||||
└─ 指向 Skills 和 docs
|
||||
|
||||
Layer 2: skills/ (按需加载，$skill-name 触发)
|
||||
├─ commit-message: 提交信息规范
|
||||
├─ style-cleanup: 代码风格整理
|
||||
├─ tsl-syntax-reference: TSL 语法条目、写法验证和错误边界
|
||||
├─ tsl-api-reference: TSL API 名称、签名、参数和返回值
|
||||
└─ thirdparty/: 第三方同步 skills
|
||||
|
||||
Layer 3: docs/ (权威静态文档)
|
||||
└─ 完整语法手册/代码风格/工具链配置
|
||||
Layer 3: docs/ (仓库内静态文档)
|
||||
└─ 静态规范/代码风格/工具链/模块与集成文档
|
||||
```
|
||||
|
||||
**各层职责**：
|
||||
|
||||
| 层级 | 加载方式 | 内容 | 作用 |
|
||||
| ------- | ------------------------------ | ------------------------------ | -------------------------- |
|
||||
| Layer 1 | 自动，始终在上下文 | 语言特有的核心约束 | 快速判断能做/不能做 |
|
||||
| Layer 2 | `$<skill-name>` 触发或智能体判定 | 操作指南、最佳实践、工作流 | 指导具体怎么做 |
|
||||
| Layer 3 | 按需读取特定章节 | 完整语言手册、代码风格、工具链 | 最终权威（冲突时以此为准） |
|
||||
| ------- | -------------------------------- | -------------------------------------- | ------------------------------------- |
|
||||
| Layer 1 | 自动，始终在上下文 | 核心约束、优先级、所有者路由和阻断规则 | 快速定位事实所有者并判断能做/不能做 |
|
||||
| Layer 2 | `$<skill-name>` 触发或智能体判定 | 操作指南、工作流和可安装参考知识 | 执行任务或查询 Skill 所拥有的事实 |
|
||||
| Layer 3 | 按需读取特定章节 | 静态规范、代码风格、工具链和模块文档 | 管理仓库内静态事实，不覆盖 Skill 事实 |
|
||||
|
||||
TSL 语法事实唯一由 `tsl-syntax-reference` 管理；`rulesets/tsl/index.md` 和 `docs/tsl/` 只负责路由、边界及各自拥有的非语法事实。
|
||||
|
||||
**目录结构**：
|
||||
|
||||
- `rulesets/index.md`：规则集索引（跨语言）
|
||||
- `rulesets/tsl/index.md`：TSL 核心约定（45 行）
|
||||
- `rulesets/tsl/index.md`：TSL 领域路由与事实边界
|
||||
- `rulesets/cpp/index.md`：C++ 核心约定（46 行）
|
||||
- `rulesets/python/index.md`：Python 核心约定（44 行）
|
||||
- `rulesets/typescript/index.md`：TypeScript 核心约定（47 行）
|
||||
@@ -119,8 +123,8 @@ Layer 3: docs/ (权威静态文档)
|
||||
|
||||
**.agents/（Layer 1）修改规则**：
|
||||
|
||||
- 可做：更新核心约定、添加语言特有的硬性约束(命名/语法/工具链)
|
||||
- 不可做：添加推荐型最佳实践（→ skill）、详细语法解释（→ skill/docs）、超过 50 行（→ 拆分）
|
||||
- 可做：更新核心约定或事实所有者路由、添加语言特有的项目级硬性边界
|
||||
- 不可做：添加推荐型最佳实践（→ skill）、复制其他事实所有者的详细内容、超过 50 行（→ 拆分）
|
||||
|
||||
**Skills（Layer 2）创建规则**：
|
||||
|
||||
@@ -130,6 +134,17 @@ Layer 3: docs/ (权威静态文档)
|
||||
|
||||
本仓库内置 AI agent skills，支持 Codex CLI 和 Claude Code，用于按需加载的工作流与知识库。
|
||||
|
||||
TSL 完整能力需要同时安装 `tsl-syntax-reference` 与 `tsl-api-reference`：
|
||||
|
||||
```toml
|
||||
[install_skills]
|
||||
agents_home = "~/.agents"
|
||||
mode = "list"
|
||||
skills = ["tsl-syntax-reference", "tsl-api-reference"]
|
||||
```
|
||||
|
||||
`[sync_standards]` 只部署规则集和文档，不会自动安装 Skill；Skill 安装由 `[install_skills]` 显式配置。
|
||||
|
||||
安装与使用详见 [SKILLS.md](SKILLS.md)。
|
||||
|
||||
## 在其他项目中使用本 Playbook
|
||||
@@ -236,8 +251,8 @@ Layer 3: docs/ (权威静态文档)
|
||||
|
||||
本仓库提供多套智能体规则集（同步后位于目标项目的 `.agents/tsl/` / `.agents/cpp/` / `.agents/python/` / `.agents/typescript/` / `.agents/markdown/`）：
|
||||
|
||||
- 各规则集都包含语言特有的核心约定
|
||||
- 并在 `index.md` 中叠加语言级"硬约束"（TSL/TSF 语法限制、C++23/Modules、Python 风格、TypeScript 类型约束、Markdown 代码格式化等）
|
||||
- 各规则集包含语言核心约定或事实所有者路由
|
||||
- 并在 `index.md` 中叠加语言级硬约束或阻断边界（TSL 使用语法/API 双 Skill 路由与 fail-closed；其他语言保留各自的版本、风格、类型或格式约束）
|
||||
|
||||
**多语言项目推荐结构**（示例：TSL + C++ + Python + TypeScript + Markdown）：
|
||||
|
||||
|
||||
+1
-1
@@ -12,7 +12,7 @@
|
||||
- TSL 总入口（先判断主问题属于哪一层）：`tsl/index.md`
|
||||
- 代码风格：`tsl/code_style.md`
|
||||
- 命名规范：`tsl/naming.md`
|
||||
- 语法手册（只处理“语言怎么写”）：`tsl/syntax/index.md`
|
||||
- 语法手册（只处理“语言怎么写”）：[tsl-syntax-reference Skill](../skills/tsl-syntax-reference/SKILL.md)
|
||||
- 模块与集成入口（pyTSL、微信消息、回测框架）：`tsl/modules/index.md`
|
||||
- 金融函数事实：`tsl/reference/catalog/datawarehouse.md`
|
||||
- 函数检索入口（模块目录位于 `tsl/reference/catalog/`）：`tsl/reference/index.md`
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：否
|
||||
是否含不可照写反例：否
|
||||
遇到不确定时：风格/命名看 [naming.md](naming.md)；语法事实看 [syntax/index.md](syntax/index.md)；验证命令或自动化入口只看项目脚本、CI，或目标项目已真实填写且没有 `<...>` 占位符的 [toolchain.md](toolchain.md)
|
||||
遇到不确定时：风格/命名看 [naming.md](naming.md)；语法事实使用 [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md)；验证命令或自动化入口只看项目脚本、CI，或目标项目已真实填写且没有 `<...>` 占位符的 [toolchain.md](toolchain.md)
|
||||
|
||||
本页记录本仓库代码风格偏好，不代表 TSL 语法事实。
|
||||
|
||||
@@ -22,14 +22,14 @@
|
||||
### 1.1 单一职责
|
||||
|
||||
- 一个文件只做一件事；职责明确。
|
||||
- 文件模型和顶层声明规则以 `docs/tsl/syntax/02_core_model.md` 为准；本页只规定组织偏好。
|
||||
- 文件模型和顶层声明规则由 [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md) 管理；本页只规定组织偏好。
|
||||
- 可复用逻辑优先集中到可复用声明文件；入口/编排层只保留必要流程。
|
||||
- 当一个顶层声明同时承担“协议适配 + 业务计算 +
|
||||
I/O/环境依赖 + 临时代码”时，优先拆分边界：核心纯逻辑 → 工具函数 → 边界适配（I/O）。
|
||||
|
||||
### 1.2 文件名与顶层声明
|
||||
|
||||
- 文件模型和顶层声明规则以 `docs/tsl/syntax/02_core_model.md` 为准；文件和实体如何命名见
|
||||
- 文件模型和顶层声明规则由 [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md) 管理；文件和实体如何命名见
|
||||
`docs/tsl/naming.md`。
|
||||
- 文件名不强制表达完整职责，但应清晰可检索。
|
||||
- 推荐文件名使用 `PascalCase` 以提升检索与协作一致性；扩展名按类型使用
|
||||
@@ -91,7 +91,7 @@ end
|
||||
- 多语句分支使用 `begin/end` 包裹：在 `then/else` 后换行写 `begin`，`end`
|
||||
单独成行。
|
||||
- `else/elseif` 等分支关键字另起一行，与上一块的 `end` 对齐。
|
||||
- 控制流块（`if`/`while`/`for`/`case`/`try` 等）的 `end` 后不加分号；顶层声明（函数/过程/类/`unit`）的 `end` 后加分号（这是语法要求，见 `syntax/05_functions_and_calls.md` 和 `syntax/09_units_and_scope.md`）。
|
||||
- 控制流块与顶层声明的分号规则属于语法事实，使用 [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md) 核对；本页只规定风格偏好。
|
||||
- 单语句分支可省略 `begin/end`（保持清晰优先；一旦分支变复杂就回退到块结构）：
|
||||
|
||||
代码块身份：配置片段 / 概念骨架
|
||||
|
||||
+5
-5
@@ -7,10 +7,10 @@
|
||||
本表只做「任务 → 文档区」分流；区内细分交给各区 `index.md`。多行命中时，自上而下取第一个命中行。
|
||||
|
||||
| 任务信号 | 入口 | 阻断条件 |
|
||||
| ---------------------------------------------------------- | ------------------------------------------------------------------------------ | ---------------------------------- |
|
||||
| 要生成或编写 TSL 代码、先定文件模型与起手骨架 | [syntax/01_quickstart.md](syntax/01_quickstart.md) | 不写代码，只查语法、函数或命名事实 |
|
||||
| 查语法写法、语言规则、排查语法错误 | [syntax/index.md](syntax/index.md) | 要找的是函数，不是语法 |
|
||||
| 取金融数据：行情、财务、板块、选股 | 使用 `tsl-api-reference` skill 关键词查 API | 不是取数，是语法或语言规则 |
|
||||
| 查 API/函数的名字、参数、返回值 | 使用 `tsl-api-reference` skill：已知名走 `--name`，未知名走 `--kw` | 要查的是语法，不是 API 事实 |
|
||||
| ---------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------- |
|
||||
| 要生成或编写 TSL 代码、先定文件模型与起手骨架 | [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md) | 不写代码，只查语法、函数或命名事实 |
|
||||
| 查语法写法、语言规则、排查语法错误 | [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md) | 要找的是函数，不是语法 |
|
||||
| 取金融数据：行情、财务、板块、选股 | 使用 [tsl-api-reference Skill](../../skills/tsl-api-reference/SKILL.md) | 不是取数，是语法或语言规则 |
|
||||
| 查 API/函数的名字、参数、返回值 | 使用 [tsl-api-reference Skill](../../skills/tsl-api-reference/SKILL.md) | 要查的是语法，不是 API 事实 |
|
||||
| 命名与代码风格：变量、函数、类型、文件取名，注释与代码组织 | 取名看 [naming.md](naming.md)；注释与组织看 [code_style.md](code_style.md) | 要查的是语法或函数事实 |
|
||||
| 具体模块能力：Python 调 TSL、策略回测、微信通知/告警 | [modules/index.md](modules/index.md) | 只是纯语法或普通取数 |
|
||||
|
||||
+6
-7
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：否
|
||||
是否含不可照写反例：否
|
||||
遇到不确定时：命名对象不明看 [syntax/02_core_model.md](syntax/02_core_model.md)；代码组织看 [code_style.md](code_style.md)；语法事实看 [syntax/index.md](syntax/index.md)
|
||||
遇到不确定时：命名对象或语法事实不明时使用 [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md)；代码组织看 [code_style.md](code_style.md)
|
||||
|
||||
本页记录本仓库/作者的命名偏好，不代表 TSL 语法事实。本页只规定命名后的实体如何取名，不承担文件模型、顶层声明、执行顺序等语法判断。命名偏好与 Google C++ Style Guide 的实体形状思路对齐：通过名字的“形状”快速判断实体类型（类型/函数/变量/常量等），减少阅读成本。
|
||||
|
||||
@@ -48,16 +48,15 @@
|
||||
`getSysParams("xxx")`；自定义 wrapper 仍按本指南使用 `PascalCase`。
|
||||
- 常规自定义标识符不要使用 TSL 关键字、保留字或内置函数名。适用范围包括变量、
|
||||
参数、函数/过程、类/类型、property、方法、字段、unit 名和文件基名。
|
||||
- 关键字和保留名清单以
|
||||
[16_lexical_structure_and_compile_options.md](syntax/16_lexical_structure_and_compile_options.md)
|
||||
为准；例如 `label` 是控制流保留名，不要作为普通变量、函数或属性名。
|
||||
- 关键字和保留名清单由 [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md)
|
||||
管理；需要判断具体名称时必须向该事实所有者查询，本页不枚举或判定具体保留名。
|
||||
- 如果业务术语与关键字或内置名冲突，优先换成语义清楚的替代名称。只有明确需要
|
||||
演示同名遮蔽、绑定外部接口或保持协议兼容时，才允许使用冲突名。
|
||||
- 函数参数场景可以使用 5.1 中的前导下划线例外。
|
||||
|
||||
## 3. 类型命名（Type Names）
|
||||
|
||||
文件模型和顶层声明规则以 `docs/tsl/syntax/02_core_model.md` 为准。本页只覆盖“需要命名的顶层实体”，不覆盖脚本语句本身。
|
||||
文件模型和顶层声明规则由 [tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md) 管理。本页只覆盖“需要命名的顶层实体”，不覆盖脚本语句本身。
|
||||
|
||||
- **类与单元**使用
|
||||
`PascalCase`，不带下划线；名称应为名词/名词短语（通常单数），避免动词开头。
|
||||
@@ -72,8 +71,8 @@
|
||||
|
||||
## 4. 文件命名与顶层声明（File Names）
|
||||
|
||||
文件模型、可写顶层声明、声明与文件关系以
|
||||
`docs/tsl/syntax/02_core_model.md` 为准；本节只给已经确定要命名的文件/实体提供命名偏好。
|
||||
文件模型、可写顶层声明、声明与文件关系由
|
||||
[tsl-syntax-reference Skill](../../skills/tsl-syntax-reference/SKILL.md) 管理；本节只给已经确定要命名的文件/实体提供命名偏好。
|
||||
|
||||
- 先用核心模型页判断目标是否存在需要命名的顶层实体；不要从本页反推
|
||||
`.tsl` / `.tsf` 可写结构。
|
||||
|
||||
@@ -1,231 +0,0 @@
|
||||
{
|
||||
"version": "2.1",
|
||||
"description": "Agent-optimized quick index for TSL syntax - read this FIRST",
|
||||
"total_tokens_saved_per_query": "~2000-3000",
|
||||
"changelog": {
|
||||
"2.1": "Added naming/style routing for identifiers and TSF filename alignment",
|
||||
"2.0": "Extended coverage from 7 to 14 scenarios, added understand_code and optimize_code decision paths",
|
||||
"1.0": "Initial version with 7 high-frequency scenarios"
|
||||
},
|
||||
|
||||
"intent_to_file": {
|
||||
"hello_world": {
|
||||
"file": "01_quickstart.md",
|
||||
"line": 182,
|
||||
"token_cost": 50,
|
||||
"example": "echo \"hello\";"
|
||||
},
|
||||
"function_basic": {
|
||||
"file": "05_functions_and_calls.md",
|
||||
"line": 103,
|
||||
"token_cost": 100,
|
||||
"example": "function Add(a, b);\nbegin\n return a + b;\nend;"
|
||||
},
|
||||
"function_in_tsl": {
|
||||
"file": "05_functions_and_calls.md",
|
||||
"line": 82,
|
||||
"token_cost": 150,
|
||||
"example": "a := 1;\ntest();\n\nfunction test();\nbegin\n echo \"test\";\nend;"
|
||||
},
|
||||
"procedure": {
|
||||
"file": "05_functions_and_calls.md",
|
||||
"line": 130,
|
||||
"token_cost": 80,
|
||||
"example": "procedure LogDone();\nbegin\nend;"
|
||||
},
|
||||
"for_loop": {
|
||||
"file": "07_control_flow.md",
|
||||
"line": 89,
|
||||
"token_cost": 100,
|
||||
"example": "for i := 0 to 2 do\n sum := sum + i;"
|
||||
},
|
||||
"while_loop": {
|
||||
"file": "07_control_flow.md",
|
||||
"line": 64,
|
||||
"token_cost": 100,
|
||||
"example": "counter := 0;\nwhile counter < 3 do\n counter := counter + 1;"
|
||||
},
|
||||
"if_condition": {
|
||||
"file": "07_control_flow.md",
|
||||
"line": 54,
|
||||
"token_cost": 120,
|
||||
"example": "if flag > 0 then\nbegin\n value := 1;\nend"
|
||||
},
|
||||
"assignment": {
|
||||
"file": "06_expressions_and_operators.md",
|
||||
"line": 136,
|
||||
"token_cost": 60,
|
||||
"example": "a := 1;"
|
||||
},
|
||||
"variable_declaration": {
|
||||
"file": "04_variables_and_constants.md",
|
||||
"line": 75,
|
||||
"token_cost": 80,
|
||||
"example": "var a;\na := 1;"
|
||||
},
|
||||
"identifier_naming": {
|
||||
"file": "../naming.md",
|
||||
"line": 42,
|
||||
"token_cost": 120,
|
||||
"example": "UserAccount, LoadData, max_retry_count"
|
||||
},
|
||||
"class_basic": {
|
||||
"file": "08_objects_and_classes.md",
|
||||
"line": 98,
|
||||
"token_cost": 200,
|
||||
"example": "type Person = class\npublic\n name;\nend;"
|
||||
},
|
||||
"class_in_tsl": {
|
||||
"file": "08_objects_and_classes.md",
|
||||
"line": 118,
|
||||
"token_cost": 250,
|
||||
"example": "obj := new MyClass();\nobj.value := 5;\n\ntype MyClass = class\npublic\n value;\nend;"
|
||||
},
|
||||
"unit_import": {
|
||||
"file": "09_units_and_scope.md",
|
||||
"line": 141,
|
||||
"token_cost": 60,
|
||||
"example": "uses DemoUnit;"
|
||||
},
|
||||
"unit_skeleton": {
|
||||
"file": "09_units_and_scope.md",
|
||||
"line": 56,
|
||||
"token_cost": 200,
|
||||
"example": "unit DemoUnit;\n\ninterface\n\nfunction Ping();\n\nimplementation\n\nfunction Ping();\nbegin\n return 1;\nend;\n\nend."
|
||||
},
|
||||
"array_operations": {
|
||||
"file": "12_matrix_and_collections.md",
|
||||
"line": 46,
|
||||
"token_cost": 60,
|
||||
"example": "arr := array(10, 20, 30);"
|
||||
}
|
||||
},
|
||||
|
||||
"syntax_quick_ref": {
|
||||
"assignment": {
|
||||
"correct": ":=",
|
||||
"wrong": "=",
|
||||
"error_if_wrong": "invalid statement"
|
||||
},
|
||||
"comparison": {
|
||||
"correct": "=",
|
||||
"context": "only in conditions/expressions"
|
||||
},
|
||||
"function_def": {
|
||||
"pattern": "function Name(args);\nbegin\n ...\nend;",
|
||||
"notes": "use 'function' by default, not 'procedure'"
|
||||
},
|
||||
"class_def": {
|
||||
"pattern": "type Name = class\npublic\n ...\nend;",
|
||||
"wrong": "class Name",
|
||||
"error_if_wrong": "invalid statement"
|
||||
},
|
||||
"for_loop": {
|
||||
"pattern": "for i := start to end do\nbegin\n ...\nend;"
|
||||
},
|
||||
"if_statement": {
|
||||
"pattern": "if condition then\nbegin\n ...\nend;"
|
||||
},
|
||||
"tsl_file_structure": {
|
||||
"order": ["statements first", "declarations after"],
|
||||
"wrong": "declarations before statements or after declarations"
|
||||
},
|
||||
"identifier_naming": {
|
||||
"doc": "../naming.md#L42",
|
||||
"avoid": "ordinary custom identifiers should not use TSL keywords, reserved words, or builtin function names",
|
||||
"tsf_filename_rule": "02_core_model.md#L38"
|
||||
}
|
||||
},
|
||||
|
||||
"common_errors": {
|
||||
"invalid statement": {
|
||||
"likely_causes": [
|
||||
{
|
||||
"pattern": "a = 1",
|
||||
"fix": "a := 1",
|
||||
"doc": "11_pitfalls.md",
|
||||
"line": 45
|
||||
},
|
||||
{
|
||||
"pattern": "class Person",
|
||||
"fix": "type Person = class",
|
||||
"doc": "11_pitfalls.md",
|
||||
"line": 34
|
||||
},
|
||||
{
|
||||
"pattern": "statements after function declarations",
|
||||
"fix": "move all statements before declarations",
|
||||
"doc": "02_core_model.md",
|
||||
"line": 34
|
||||
}
|
||||
]
|
||||
},
|
||||
"compile error": {
|
||||
"check": "11_pitfalls.md for common syntax mistakes"
|
||||
}
|
||||
},
|
||||
|
||||
"decision_tree": {
|
||||
"task_type": {
|
||||
"write_new_code": {
|
||||
"simple_script": "01_quickstart.md#L182",
|
||||
"function": "05_functions_and_calls.md#L103",
|
||||
"procedure": "05_functions_and_calls.md#L130",
|
||||
"naming": "../naming.md#L42",
|
||||
"class": "08_objects_and_classes.md#L98",
|
||||
"loop": "07_control_flow.md#L89",
|
||||
"condition": "07_control_flow.md#L54",
|
||||
"unit": "09_units_and_scope.md#L56",
|
||||
"array": "12_matrix_and_collections.md#L46"
|
||||
},
|
||||
"fix_error": {
|
||||
"invalid_statement": "11_pitfalls.md#L34-L59",
|
||||
"compile_error": "11_pitfalls.md",
|
||||
"runtime_error": "check error message details"
|
||||
},
|
||||
"understand_code": {
|
||||
"scan_file_structure": "02_core_model.md#L34",
|
||||
"trace_function": "05_functions_and_calls.md",
|
||||
"trace_class": "08_objects_and_classes.md",
|
||||
"check_unit_imports": "09_units_and_scope.md"
|
||||
},
|
||||
"optimize_code": {
|
||||
"check_profiler": "15_debug_and_profiler.md",
|
||||
"optimize_matrix": "22_matrix_deep_dive.md"
|
||||
}
|
||||
}
|
||||
},
|
||||
|
||||
"file_model_rules": {
|
||||
"tsl_script": {
|
||||
"extension": ".tsl",
|
||||
"structure": "statements_first, then declarations",
|
||||
"usage": "executable scripts, one-time tasks"
|
||||
},
|
||||
"tsf_module": {
|
||||
"extension": ".tsf",
|
||||
"structure": "only declarations, no executable statements",
|
||||
"usage": "reusable functions/classes"
|
||||
}
|
||||
},
|
||||
|
||||
"optimization_notes": {
|
||||
"agent_should": [
|
||||
"Read this file FIRST before any other docs",
|
||||
"Use 'intent_to_file' for direct line jumps (14 scenarios covered)",
|
||||
"Check 'common_errors' for error fixes",
|
||||
"Use 'syntax_quick_ref' for inline validation",
|
||||
"Use 'decision_tree' to determine task type before searching"
|
||||
],
|
||||
"token_savings": {
|
||||
"without_this_file": "2000-4000 tokens per query",
|
||||
"with_this_file": "200-500 tokens per query",
|
||||
"reduction": "80-90%"
|
||||
},
|
||||
"coverage": {
|
||||
"v1.0": "7 scenarios (30% of common tasks)",
|
||||
"v2.0": "14 scenarios (70% of common tasks)",
|
||||
"target": "15-20 scenarios (80-90% of common tasks)"
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -1,91 +1,5 @@
|
||||
# TSL 语法入口
|
||||
# TSL 语法入口已迁移
|
||||
|
||||
```json
|
||||
{
|
||||
"AGENT_QUICK_INDEX": {
|
||||
"READ_THIS_FIRST": "00_agent_index.json",
|
||||
"hello_world": "01_quickstart.md#L182",
|
||||
"function": "05_functions_and_calls.md#L103",
|
||||
"class": "08_objects_and_classes.md#L98",
|
||||
"naming": "../naming.md#L42",
|
||||
"tsf_filename": "02_core_model.md#L38",
|
||||
"loop": "07_control_flow.md#L89",
|
||||
"if": "07_control_flow.md#L54",
|
||||
"fix_a=1_error": "11_pitfalls.md#L45",
|
||||
"fix_class_error": "11_pitfalls.md#L34",
|
||||
"token_saving": "80-90% reduction vs reading full docs"
|
||||
}
|
||||
}
|
||||
```
|
||||
TSL/TSF 语法事实现由仓库内唯一事实源 [tsl-syntax-reference Skill](../../../skills/tsl-syntax-reference/SKILL.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)。
|
||||
|
||||
本页只决定语法层第一跳。不要顺序读完整套语法文档，不要把本页当代码事实页。
|
||||
|
||||
## 按任务跳转
|
||||
|
||||
| 任务信号 | 入口 | 阻断条件 |
|
||||
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------ |
|
||||
| 写最短骨架、核对语言核心事实 | [01_quickstart.md](01_quickstart.md) | 文件模型不明 |
|
||||
| 判断 `.tsl` / `.tsf`、顶层语句区、声明区、文件模型 | [02_core_model.md](02_core_model.md) | 用户交付目标不足以判断后缀 |
|
||||
| 给变量、函数、类型、unit 或 `.tsf` 文件取名 | [../naming.md](../naming.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) | 需要未记录的 SQL 外形 |
|
||||
| 看调试与性能分析器专题 | [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) | FMArray 专属能力无文档事实 |
|
||||
| 看对象算符重载或遍历重载 | [24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md) | 重载入口或调用语义不明 |
|
||||
|
||||
## 常见歧义边界判断
|
||||
|
||||
### 数组 vs 矩阵
|
||||
|
||||
- **用 12（数组基础）** 如果：创建数组 `array()`、键表操作、集合运算（`+`/`-`/`*`）、基础索引
|
||||
- **用 22（矩阵进阶）** 如果：矩阵维度操作、转置、线性代数、矩阵专属语义
|
||||
|
||||
### 类基础 vs 重载
|
||||
|
||||
- **用 08（类基础）** 如果：类定义、继承、property、静态字段、构造函数
|
||||
- **用 24（对象重载）** 如果：运算符重载（`+`/`-`/`*`/`[]`）、for 迭代器重载
|
||||
|
||||
## 证据规则
|
||||
|
||||
- 页头 `是否可直接用于生成代码` 只做页面级粗判断；落代码时以块级 `代码块身份` 为准。
|
||||
- `代码块身份` 固定只用四种值：`可直接照写示例`、`输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。
|
||||
- 普通语法专题页的 `遇到不确定时` 先按候选页继续判断，仍不命中再回本语法入口页；本页例外，必须先按"按任务跳转"分流。
|
||||
|
||||
## 停止条件
|
||||
|
||||
- 文件模型会影响正确性且用户交付目标不足以判断 `.tsl` / `.tsf`。
|
||||
- 命中项需要未记录语法、运行时事实或项目执行事实。
|
||||
- 只有反例、输出片段或概念骨架可用，没有 `代码块身份：可直接照写示例`。
|
||||
- 任务信号属于数据仓库函数、模块集成、函数库查询或项目执行边界。
|
||||
|
||||
## 入口禁止项
|
||||
|
||||
- 不要跳过"按任务跳转"直接顺序读完整套。
|
||||
- 不要把本入口页当成可直接生成代码的语法事实页。
|
||||
- 不要从多个专题页拼接未写入文档的新骨架；生成前优先使用单页里的可直接照写示例。
|
||||
- 不要把数据仓库函数查询、模块集成或项目执行问题留在语法层处理。
|
||||
|
||||
## 切换到别的层
|
||||
|
||||
- 数据仓库金融函数：使用 `tsl-api-reference` skill
|
||||
- 模块 / 集成 / 互操作：见 [../modules/index.md](../modules/index.md)
|
||||
- 函数库 / API 查找：使用 `tsl-api-reference` skill（已知名走 `--name`，未知名走 `--kw`）
|
||||
本页仅为旧路径兼容入口，不保存语法规则或专题路由。独立部署时请安装 `tsl-syntax-reference` 后再处理 TSL/TSF 语法任务。
|
||||
|
||||
+23
-21
@@ -1,30 +1,32 @@
|
||||
# TSL 智能体规则
|
||||
|
||||
本文件不是语法手册，只放硬约束、首跳路由和阻断条件。
|
||||
本文件只保留 TSL 多领域首跳路由、优先级、事实边界和阻断条件，不保存具体语法实现。
|
||||
|
||||
- 更靠近代码目录的规则可以更严格，但不能削弱文档事实和禁止发明语法规则。
|
||||
- TSL 事实以 `docs/tsl/**`、项目自身文档和块级 `代码块身份` 为准；本文件不复写完整语法。
|
||||
- 用户明确指令不能覆盖文档事实使用规则或禁止发明语法规则。
|
||||
## 范围与优先级
|
||||
|
||||
## 代码生成协议
|
||||
|
||||
- 生成或修改代码前先判断交付目标与 `.tsl` / `.tsf` 文件模型；文件模型影响正确性且需求不明时先确认。
|
||||
- 禁止凭 Pascal、Python、JavaScript、TypeScript 或其他语言的相似写法补全 TSL 语法。
|
||||
- 无文档结论、文件模型不明或项目执行事实缺失时停止，不发明语法。
|
||||
|
||||
## TSL 核心事实
|
||||
|
||||
- `.tsl` / `.tsf` 后缀由用户指定时，后缀优先。
|
||||
- 未指定后缀时：入口流程、脚本任务或一次性任务初判 `.tsl`；可复用函数、过程、类、模块或扩展初判 `.tsf`。
|
||||
- `.tsl` 代码需要本文件内函数或类时，先写可执行语句区，再写声明区；声明区后不要继续追加脚本语句。
|
||||
- `.tsf` 只按可复用顶层声明或 `unit` 组织，不写顺序执行入口。
|
||||
- 对象创建、函数调用、`unit`、运行时上下文、TS-SQL 和矩阵等细节只从对应专题页取事实。
|
||||
- 更靠近目标代码的规则可以更严格，但不能削弱事实所有者给出的约束。
|
||||
- 用户明确要求优先；与仓库真实项目事实冲突时，先报告冲突并停止相关生成。
|
||||
- 只读取命中任务所需的事实所有者，不顺序通读全部文档，也不跨领域复制事实。
|
||||
|
||||
## 文档首跳
|
||||
|
||||
- 需要任何 TSL 语法、文件模型、函数、模块或金融数据事实时，第一跳统一进 `docs/tsl/index.md`，由它路由到具体页；不在本文件内猜文件路径，也不全目录搜索。
|
||||
- TSL/TSF 语法、文件模型、语言规则、代码编写/修改/审查/解释和语法错误：使用 `tsl-syntax-reference` skill。
|
||||
- API/函数名称、签名、参数、返回值和金融取数：使用 `tsl-api-reference` skill。
|
||||
- 命名偏好：读取 `docs/tsl/naming.md`。
|
||||
- 代码风格：读取 `docs/tsl/code_style.md`。
|
||||
- 验证命令和工具链：读取 `docs/tsl/toolchain.md`、项目脚本或 CI。
|
||||
- Python 调 TSL、回测和通知等模块集成：读取 `docs/tsl/modules/index.md`。
|
||||
- 路径、数据结构、部署、运行参数和环境约束等项目事实：只读取目标项目的真实文档、配置和最近的 `AGENTS.md`。
|
||||
|
||||
## 文档事实使用策略
|
||||
## 事实边界
|
||||
|
||||
- 页面级元数据只做粗判断；生成代码时以块级 `代码块身份` 为准：只有 `可直接照写示例` 能当源码外形，`反例 / 不可照写`、`输出片段`、`配置片段 / 概念骨架` 不得照抄。
|
||||
- `code_style.md` 与 `naming.md` 只表达风格偏好，不代表 TSL 语法事实。
|
||||
- 语法 Skill 不拥有 API、命名、风格、工具链、模块或项目事实。
|
||||
- API Skill 不拥有语言语法、项目部署或模块集成事实。
|
||||
- 命名和风格文档只表达仓库偏好，不得替代语法事实。
|
||||
- 项目事实优先于通用示例；示例不得反推不存在的项目能力。
|
||||
|
||||
## Fail closed
|
||||
|
||||
- `tsl-syntax-reference` 缺失或不可用时，停止生成或修改 TSL/TSF 代码，不凭相似语言补全语法。
|
||||
- `tsl-api-reference` 缺失或不可用时，停止猜测函数名、签名、参数和返回值。
|
||||
- 工具链、模块或项目事实缺失时，停止相关执行与集成判断，并明确报告缺失项。
|
||||
|
||||
@@ -7,10 +7,6 @@ from pathlib import Path
|
||||
|
||||
|
||||
DEFAULT_OUTPUT = Path("tmp") / "tsl-playbook"
|
||||
API_REFERENCE_BULLET = (
|
||||
"- 查 API / 函数的名字、参数、返回值和示例时，使用 "
|
||||
"`tsl-api-reference` skill；已知名走 `--name`，未知名走 `--kw`。"
|
||||
)
|
||||
|
||||
|
||||
def copy_tree(src: Path, dst: Path) -> None:
|
||||
@@ -20,24 +16,19 @@ def copy_tree(src: Path, dst: Path) -> None:
|
||||
def build_agents_text(ruleset_path: Path) -> str:
|
||||
text = ruleset_path.read_text(encoding="utf-8")
|
||||
text = text.replace("# TSL 智能体规则", "# TSL Agent Instructions", 1)
|
||||
if API_REFERENCE_BULLET not in text:
|
||||
marker = (
|
||||
"- 需要任何 TSL 语法、文件模型、函数、模块或金融数据事实时，"
|
||||
"第一跳统一进 `docs/tsl/index.md`，由它路由到具体页；"
|
||||
"不在本文件内猜文件路径，也不全目录搜索。"
|
||||
)
|
||||
text = text.replace(marker, f"{marker}\n{API_REFERENCE_BULLET}", 1)
|
||||
return text.rstrip("\n") + "\n"
|
||||
|
||||
|
||||
def ensure_sources(repo_root: Path) -> tuple[Path, Path, Path]:
|
||||
def ensure_sources(repo_root: Path) -> tuple[Path, Path, Path, Path]:
|
||||
docs_tsl = repo_root / "docs" / "tsl"
|
||||
skill = repo_root / "skills" / "tsl-api-reference"
|
||||
syntax_skill = repo_root / "skills" / "tsl-syntax-reference"
|
||||
api_skill = repo_root / "skills" / "tsl-api-reference"
|
||||
ruleset = repo_root / "rulesets" / "tsl" / "index.md"
|
||||
missing = [str(path) for path in (docs_tsl, skill, ruleset) if not path.exists()]
|
||||
sources = (docs_tsl, syntax_skill, api_skill, ruleset)
|
||||
missing = [str(path) for path in sources if not path.exists()]
|
||||
if missing:
|
||||
raise FileNotFoundError("missing source path(s): " + ", ".join(missing))
|
||||
return docs_tsl, skill, ruleset
|
||||
return sources
|
||||
|
||||
|
||||
def clean_output(output: Path, repo_root: Path) -> None:
|
||||
@@ -56,14 +47,15 @@ def clean_output(output: Path, repo_root: Path) -> None:
|
||||
|
||||
|
||||
def build(output: Path, repo_root: Path) -> None:
|
||||
docs_tsl, skill, ruleset = ensure_sources(repo_root)
|
||||
docs_tsl, syntax_skill, api_skill, ruleset = ensure_sources(repo_root)
|
||||
clean_output(output, repo_root)
|
||||
|
||||
(output / "AGENTS.md").write_text(
|
||||
build_agents_text(ruleset), encoding="utf-8", newline="\n"
|
||||
)
|
||||
copy_tree(docs_tsl, output / "docs" / "tsl")
|
||||
copy_tree(skill, output / "skills" / "tsl-api-reference")
|
||||
copy_tree(syntax_skill, output / "skills" / "tsl-syntax-reference")
|
||||
copy_tree(api_skill, output / "skills" / "tsl-api-reference")
|
||||
|
||||
|
||||
def main(argv=None) -> int:
|
||||
|
||||
+6
-5
@@ -10,11 +10,12 @@
|
||||
## 一方 Skills
|
||||
|
||||
| Skill | 作用 | 典型场景 |
|
||||
| --- | --- | --- |
|
||||
| ------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
||||
| `bulk-refactor-workflow` | 大规模重构工作流：符号重命名、API 迁移、安全机械变更 | 跨多文件重命名、API 替换、批量代码转换 |
|
||||
| `commit-message` | 根据 staged diff 生成符合仓库规范的提交信息，并判断是否应拆分提交 | 写 commit message、检查 staged 改动是否适合一个提交 |
|
||||
| `gitea-fix-ci` | 基于 Gitea Actions run/job/log 诊断失败 CI，先形成修复计划再改代码 | Gitea PR checks 失败、远端 CI 红但本地需要定位 |
|
||||
| `style-cleanup` | 使用仓库既有 formatter/linter 做格式和 lint 收尾，不改变语义 | 格式化、lint cleanup、代码改完后的风格整理 |
|
||||
| `tsl-syntax-reference` | 查询 TSL 语法条目，验证具体写法和错误边界；不负责 API、命名、风格、工具链或模块集成 | 写/改/审 TSL 时确认语言结构、表达式、控制流、对象模型和语法限制 |
|
||||
| `tsl-api-reference` | 查询随 skill 分发的 TSL API 参考：按名精确查条目，或按中文关键词发现候选 | 写/审 TSL 时确认 builtin、dotnet、模块 API 的签名、参数、返回值和示例 |
|
||||
|
||||
## 第三方 Skills
|
||||
@@ -24,7 +25,7 @@
|
||||
这些 skill 来自 `superpowers`，主要提供计划、执行、调试、验证和审查工作流。
|
||||
|
||||
| Skill | 作用 |
|
||||
| --- | --- |
|
||||
| -------------------------------- | ------------------------------------------------ |
|
||||
| `using-superpowers` | 会话开始时判断并加载适用 skill |
|
||||
| `brainstorming` | 需求澄清、方案讨论、设计文档产出 |
|
||||
| `writing-plans` | 把设计或需求拆成可执行 implementation plan |
|
||||
@@ -45,7 +46,7 @@
|
||||
Code review 和质量审查工具集，包含共享参考资料目录 `_shared`。
|
||||
|
||||
| Skill | 作用 |
|
||||
| --- | --- |
|
||||
| --------------- | -------------------------------------- |
|
||||
| `brooks-review` | 常规 PR / diff code review |
|
||||
| `brooks-audit` | architecture audit、系统性结构问题审查 |
|
||||
| `brooks-debt` | technical debt review |
|
||||
@@ -56,7 +57,7 @@ Code review 和质量审查工具集，包含共享参考资料目录 `_shared`
|
||||
### 代码库侦察与迁移
|
||||
|
||||
| Skill | 作用 |
|
||||
| --- | --- |
|
||||
| ------------------ | --------------------------------------------------------- |
|
||||
| `codebase-recon` | 通过 git 历史和代码结构做 risk scan、热点分析、重构前侦察 |
|
||||
| `pathfinding` | 需求澄清和 confidence calibration |
|
||||
| `codebase-migrate` | 大代码库迁移、多文件 refactor、分批变更与 CI 验证工作流 |
|
||||
@@ -64,7 +65,7 @@ Code review 和质量审查工具集，包含共享参考资料目录 `_shared`
|
||||
### 其他
|
||||
|
||||
| Skill | 作用 |
|
||||
| --- | --- |
|
||||
| --------------------- | ------------------------------------------------------------- |
|
||||
| `ui-ux-pro-max` | UI/UX 设计知识库，包含风格、配色、字体、组件和栈相关建议 |
|
||||
| `karpathy-guidelines` | 写代码、审查、重构时降低 LLM 常见错误：保持简单、聚焦、可验证 |
|
||||
| `uncle-bob-craft` | Clean Architecture、SOLID、设计模式误用和代码工匠实践审查 |
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: tsl-syntax-reference
|
||||
description: Use when Codex 需要编写、修改、审查或解释 TSL/TSF 代码，或排查语法错误并核对语言与运行时规则。
|
||||
---
|
||||
|
||||
# TSL Syntax Reference
|
||||
|
||||
## 范围判断
|
||||
|
||||
只处理 TSL/TSF 的语言语法、文件模型、表达式、控制流、对象、运行时语言结构和 TS-SQL 外形。先判断用户的问题是否属于“语言怎么写”；API 函数事实、命名偏好、代码风格、工具链、模块集成和项目执行事实分别交给其事实所有者。
|
||||
|
||||
## 写代码前确定文件模型
|
||||
|
||||
生成或修改代码前，先读 [references/01_quickstart.md](references/01_quickstart.md)，再根据交付目标确定 `.tsl` 或 `.tsf` 文件模型。后缀或顶层结构会影响正确性而需求不足时，停止并向用户确认；不要凭 Pascal、Python、JavaScript、TypeScript 或其他相似语言补全 TSL 语法。
|
||||
|
||||
## 选择一个主专题
|
||||
|
||||
从 [references/index.md](references/index.md) 的“任务 → 主专题 → 停止条件”表选择一个主专题。先按最具体的任务信号命中，不要顺序通读全部专题，也不要把路由页本身当成语法事实页。
|
||||
|
||||
## 渐进读取候选页
|
||||
|
||||
先读主专题，只在主专题明确列出的候选页中继续读取。每次只补当前缺口；得到足够事实后停止。遇到语法错误、相互矛盾的写法或高频误写时，再读 [references/11_pitfalls.md](references/11_pitfalls.md) 交叉核对。
|
||||
|
||||
## 遵守代码块身份协议
|
||||
|
||||
页面级元数据只用于粗筛，生成代码时以紧邻代码块的 `代码块身份` 为准：
|
||||
|
||||
- `可直接照写示例`：可以作为源码外形，但仍需按当前任务替换业务内容。
|
||||
- `反例 / 不可照写`：只用于识别错误边界，不得复制为实现。
|
||||
- `输出片段`：只表示结果，不得当作源码。
|
||||
- `配置片段 / 概念骨架`：只表达结构或配置意图，不得假定为可直接运行代码。
|
||||
|
||||
代码块没有身份、身份与正文冲突或缺少支持当前结论的事实时，停止生成并报告缺口。
|
||||
|
||||
## 交接其他事实所有者
|
||||
|
||||
- API 名称、签名、参数、返回值和金融取数事实：使用 `tsl-api-reference` skill。
|
||||
- 命名偏好：交给仓库的 `docs/tsl/naming.md`。
|
||||
- 代码风格：交给仓库的 `docs/tsl/code_style.md`。
|
||||
- 验证命令与工具链：交给仓库的 `docs/tsl/toolchain.md`、项目脚本或 CI。
|
||||
- Python 调 TSL、回测、通知等模块集成：交给仓库的 `docs/tsl/modules/`。
|
||||
- 项目路径、数据结构、部署方式和运行参数：只使用目标项目的真实文档与配置。
|
||||
|
||||
不要把这些外部领域复制进本 Skill；完成交接后由对应事实所有者继续判断。
|
||||
|
||||
## 缺口时停止
|
||||
|
||||
主专题和候选页没有给出结论、运行时版本不明、项目事实缺失或依赖的 Skill 不可用时，明确说明缺失项并停止。不得以经验、相似语言或猜测产生新的 TSL 写法。
|
||||
|
||||
## 执行 TSL 前读取项目指引
|
||||
|
||||
需要实际执行 TSL 时，先读取目标文件附近最近的 `AGENTS.md`，完成平台检测并严格使用其中指定的解释器环境。不同平台或多个 Windows 环境不得混用、默认任选或自行回退。
|
||||
@@ -0,0 +1,4 @@
|
||||
interface:
|
||||
display_name: "TSL Syntax Reference"
|
||||
short_description: "检索并验证 TSL/TSF 语法与运行时语言规则事实"
|
||||
default_prompt: "Use $tsl-syntax-reference to look up and verify TSL/TSF syntax from authoritative references."
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本文“下一步路由”继续判断；文件模型看 [02_core_model.md](02_core_model.md)，函数 / 调用看 [05_functions_and_calls.md](05_functions_and_calls.md)，类看 [08_objects_and_classes.md](08_objects_and_classes.md)，`unit` / `uses` 看 [09_units_and_scope.md](09_units_and_scope.md)，反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本文“下一步路由”继续判断；文件模型看 [02_core_model.md](02_core_model.md)，函数 / 调用看 [05_functions_and_calls.md](05_functions_and_calls.md)，类看 [08_objects_and_classes.md](08_objects_and_classes.md)，`unit` / `uses` 看 [09_units_and_scope.md](09_units_and_scope.md)，反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
本篇只回答两个落代码前问题：用户已给出 `.tsl` / `.tsf` 后缀时，智能体如何按后缀组织代码；以及生成代码前必须先核对哪些语言硬规则。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本文“下一步路由”继续判断；最短骨架和高频硬规则看 [01_quickstart.md](01_quickstart.md)，函数 / 过程看 [05_functions_and_calls.md](05_functions_and_calls.md)，类看 [08_objects_and_classes.md](08_objects_and_classes.md)，`unit` / `uses` 看 [09_units_and_scope.md](09_units_and_scope.md)，反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本文“下一步路由”继续判断；最短骨架和高频硬规则看 [01_quickstart.md](01_quickstart.md)，函数 / 过程看 [05_functions_and_calls.md](05_functions_and_calls.md)，类看 [08_objects_and_classes.md](08_objects_and_classes.md)，`unit` / `uses` 看 [09_units_and_scope.md](09_units_and_scope.md)，反例和负向边界看 [11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
本篇说明 TSL 的文件模型判断规则：智能体如何区分 `.tsl` 可执行脚本与 `.tsf` 可复用声明文件，如何识别脚本语句区和声明区，以及为什么很多错误其实是“文件模型选错了”。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[04_variables_and_constants.md](04_variables_and_constants.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[17_types_and_conversions.md](17_types_and_conversions.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[04_variables_and_constants.md](04_variables_and_constants.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[17_types_and_conversions.md](17_types_and_conversions.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇整理基本类型、字面量、数组、字符串、字符串编码边界与基础值模型，避免把值规则分散在函数或金融示例里。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[03_values_and_literals.md](03_values_and_literals.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[05_functions_and_calls.md](05_functions_and_calls.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[03_values_and_literals.md](03_values_and_literals.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[05_functions_and_calls.md](05_functions_and_calls.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇收拢变量与常量初始化规则。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)（优先）、[09_units_and_scope.md](09_units_and_scope.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[18_external_calls_and_threads.md](18_external_calls_and_threads.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)（优先）、[09_units_and_scope.md](09_units_and_scope.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[18_external_calls_and_threads.md](18_external_calls_and_threads.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇只负责 `function` / `procedure` 的定义、调用、参数传递和值返回。跨 `unit` 声明边界、外部系统交互和业务函数库只在本页保留路由或最小边界。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页表格和专题入口继续判断；[03_values_and_literals.md](03_values_and_literals.md)、[04_variables_and_constants.md](04_variables_and_constants.md)、[05_functions_and_calls.md](05_functions_and_calls.md)、[07_control_flow.md](07_control_flow.md)、[08_objects_and_classes.md](08_objects_and_classes.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页表格和专题入口继续判断；[03_values_and_literals.md](03_values_and_literals.md)、[04_variables_and_constants.md](04_variables_and_constants.md)、[05_functions_and_calls.md](05_functions_and_calls.md)、[07_control_flow.md](07_control_flow.md)、[08_objects_and_classes.md](08_objects_and_classes.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇集中放语言级表达式与运算符。智能体写代码时，只使用本页和对应专题页已经明确的表达式事实，不要把其他语言或外部资料里的运算符习惯直接搬进 TSL。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页规则和示例继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[15_debug_and_profiler.md](15_debug_and_profiler.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页规则和示例继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[15_debug_and_profiler.md](15_debug_and_profiler.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇只收录流程控制与异常控制，不讨论金融语义。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)（优先）、[09_units_and_scope.md](09_units_and_scope.md)、[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)、[24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)（优先）、[09_units_and_scope.md](09_units_and_scope.md)、[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)、[24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇收拢面向对象语法，只保留语言层规则。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)（优先）、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)（优先）、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇只讲“怎么写和怎么调用 `unit`”。`namespace`、查找路径、`unit` 生命周期、`tsl.conf` 与运行时入口统一放到 [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[14_ts_sql.md](14_ts_sql.md)、[15_debug_and_profiler.md](15_debug_and_profiler.md)、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)；函数事实使用 `tsl-api-reference` skill；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[14_ts_sql.md](14_ts_sql.md)、[15_debug_and_profiler.md](15_debug_and_profiler.md)、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)；函数事实使用 `tsl-api-reference` skill；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇只处理运行时环境参数、块环境 `with` 语句、`with` 后缀、`#` 网格调用、`timeout` 后缀、`dupvalue(...)` 和全局缓存，不处理任何金融业务语义。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：否
|
||||
是否含可直接照写示例：否
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)、[03_values_and_literals.md](03_values_and_literals.md)、[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[08_objects_and_classes.md](08_objects_and_classes.md)、[09_units_and_scope.md](09_units_and_scope.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[02_core_model.md](02_core_model.md)、[03_values_and_literals.md](03_values_and_literals.md)、[05_functions_and_calls.md](05_functions_and_calls.md)、[06_expressions_and_operators.md](06_expressions_and_operators.md)、[08_objects_and_classes.md](08_objects_and_classes.md)、[09_units_and_scope.md](09_units_and_scope.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇不讲新知识，只做反例索引。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：否
|
||||
遇到不确定时：先按本页候选页继续判断；[13_resultset_and_filters.md](13_resultset_and_filters.md)、[22_matrix_deep_dive.md](22_matrix_deep_dive.md)、[23_fmarray.md](23_fmarray.md)、[14_ts_sql.md](14_ts_sql.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[13_resultset_and_filters.md](13_resultset_and_filters.md)、[22_matrix_deep_dive.md](22_matrix_deep_dive.md)、[23_fmarray.md](23_fmarray.md)、[14_ts_sql.md](14_ts_sql.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇收拢 `array(...)` 的扩展用法：顺序数组、字符串键表、嵌套数组、本页明确的矩阵样比较，以及 `in` / `sqlin` / `union2` / `intersect` / `minus` / `outersect` 这类去重型集合关系。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[12_matrix_and_collections.md](12_matrix_and_collections.md)、[14_ts_sql.md](14_ts_sql.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[12_matrix_and_collections.md](12_matrix_and_collections.md)、[14_ts_sql.md](14_ts_sql.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇只讲结果集过滤语法：怎样按某一列过滤、怎样按整行过滤、怎样只返回行下标，以及怎样按字段列表过滤。它不负责 TS-SQL 查询语法，也不把去重型集合运算和业务选股逻辑混进来。
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[13_resultset_and_filters.md](13_resultset_and_filters.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[23_fmarray.md](23_fmarray.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[13_resultset_and_filters.md](13_resultset_and_filters.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[23_fmarray.md](23_fmarray.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇是 TS-SQL 的唯一语法入口：内存数组查询、返回形态、字段访问、`where` / `group by` / `order by`、一维数组查询、多表 `join`（含 `left join`）、`insert` / `update` / `delete` 写回、`thisGroup`、`thisRowIndex`、`refMaxOf` / `refMinOf` 都在这里收拢。
|
||||
|
||||
@@ -847,7 +847,7 @@ end;
|
||||
- `TSQLInsert` / `TSQLSetValue` / `TSQLBatchInsert` / `TSQLEdit` / `TSQLPost` / `TSQLFinal` 对象被 TS-SQL 查询的回调机制
|
||||
- 面向 SQL 表、业务表或时间序列的数据查询与写回（`marketTable` / `infoTable` / `tradeTable` / `sqlTable` / `hugeSqlTable` 等数据源）
|
||||
|
||||
这些内容不作为本页可生成事实；业务数据源先查 `tsl-api-reference` skill、[../modules/pytsl_api.md](../modules/pytsl_api.md) 或项目实际接口。
|
||||
这些内容不作为本页可生成事实；业务数据源先交给 `tsl-api-reference` skill、pyTSL 模块事实所有者或项目实际接口。
|
||||
|
||||
## 默认生成模板
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[07_control_flow.md](07_control_flow.md)、[10_runtime_context_and_with.md](10_runtime_context_and_with.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[07_control_flow.md](07_control_flow.md)、[10_runtime_context_and_with.md](10_runtime_context_and_with.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇收拢本页明确的调试、计时、性能分析器和调用栈相关入口。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[17_types_and_conversions.md](17_types_and_conversions.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[17_types_and_conversions.md](17_types_and_conversions.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇吸收语法手册里“词法层”和“编译期开关”相关内容：标识符、注释、条件编译和依赖编译选项。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[03_values_and_literals.md](03_values_and_literals.md)、[04_variables_and_constants.md](04_variables_and_constants.md)、[23_fmarray.md](23_fmarray.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[03_values_and_literals.md](03_values_and_literals.md)、[04_variables_and_constants.md](04_variables_and_constants.md)、[23_fmarray.md](23_fmarray.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇吸收语言基础里“数据类型、初始值、弱类型行为、类型转换、复数类型”这一层。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[05_functions_and_calls.md](05_functions_and_calls.md)、[19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇吸收函数专题里和外部系统交互有关的部分：`external`、动态库调用、原生函数指针包装、C 回调和线程调用。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[09_units_and_scope.md](09_units_and_scope.md)、[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[09_units_and_scope.md](09_units_and_scope.md)、[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇收拢 `unit` 的运行时行为，以及 `.tsf` / `namespace` / `libpath` 的查找规则。`unit` 的基础写法、`uses` 位置和重名解析，统一放在 [09_units_and_scope.md](09_units_and_scope.md)。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[08_objects_and_classes.md](08_objects_and_classes.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)、[24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[08_objects_and_classes.md](08_objects_and_classes.md)、[16_lexical_structure_and_compile_options.md](16_lexical_structure_and_compile_options.md)、[21_builtin_runtime_objects.md](21_builtin_runtime_objects.md)、[24_object_overloads_and_iteration.md](24_object_overloads_and_iteration.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇收拢对象模型里不适合继续堆在基础类主线里的运行时内容：类信息、函数句柄、对象状态、引用计数、运行时对象枚举、弱引用与自动弱引用。普通类声明、继承、构造和普通对象创建仍以 [08_objects_and_classes.md](08_objects_and_classes.md) 为主线；本页只在用户明确需要运行时反射、内省、对象生命周期或弱引用能力时进入。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[10_runtime_context_and_with.md](10_runtime_context_and_with.md)、[11_pitfalls.md](11_pitfalls.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[10_runtime_context_and_with.md](10_runtime_context_and_with.md)、[11_pitfalls.md](11_pitfalls.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇只收运行时内置对象的文档明确最小模型。这里讲的是语言运行时对象，不是金融业务 API。
|
||||
|
||||
+2
-2
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[12_matrix_and_collections.md](12_matrix_and_collections.md)、[23_fmarray.md](23_fmarray.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[12_matrix_and_collections.md](12_matrix_and_collections.md)、[23_fmarray.md](23_fmarray.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇只讲矩阵专用语法主干：矩阵初始化、数列构造、矩阵逆/广义逆、矩阵乘除乘方、矩阵转置、矩阵拼接、矩阵尺寸与索引、矩阵遍历、子矩阵和 `mfind` 查找。它和 [12_matrix_and_collections.md](12_matrix_and_collections.md) 的分工是：`12` 讲普通数组与集合关系，这一篇讲矩阵专用构造、运算、遍历、子矩阵和矩阵查找接口。
|
||||
|
||||
@@ -924,7 +924,7 @@ matrix_value := zeros(2, 3);
|
||||
- 用 `::` 期待遍历到任意深度；深度遍历使用 `:.`。
|
||||
- 子矩阵赋值时用形状不匹配的矩阵硬塞。
|
||||
- 把 `union` 的复合赋值写成 `union=`；正确写法是 `&=`。
|
||||
- 一维数组直接 `union` 期待得到二维结果；需要先双转置 `` ``b `` 变成行向量。
|
||||
- 一维数组直接 `union` 期待得到二维结果；需要先双转置 ` `b `` 变成行向量。
|
||||
- 在基础函数异常参数时用分号分隔；正确写法用逗号：`sqrt(data, 1, -999)`。
|
||||
|
||||
代码块身份：反例 / 不可照写
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：是
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：是
|
||||
遇到不确定时：先按本页候选页继续判断；[22_matrix_deep_dive.md](22_matrix_deep_dive.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[14_ts_sql.md](14_ts_sql.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[22_matrix_deep_dive.md](22_matrix_deep_dive.md)、[12_matrix_and_collections.md](12_matrix_and_collections.md)、[14_ts_sql.md](14_ts_sql.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇只讲 `FMArray` 文档主干能力：怎样构造 `FMArray`、怎样判断类型、怎样和 `Array` 互转、怎样读取尺寸、做基础运算、做多维转置与维度交换、做矩阵连接、参与 `select/mselect`，以及 `insert/delete/update` 语法边界。
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
是否可直接用于生成代码：仅部分
|
||||
是否含可直接照写示例：是
|
||||
是否含不可照写反例：否
|
||||
遇到不确定时：先按本页候选页继续判断；[08_objects_and_classes.md](08_objects_and_classes.md)、[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[17_types_and_conversions.md](17_types_and_conversions.md)；仍不命中时回到语法路由中心 [index.md](index.md)；如果问题已经超出语法层，回到 TSL 总入口 [../index.md](../index.md)
|
||||
遇到不确定时：先按本页候选页继续判断；[08_objects_and_classes.md](08_objects_and_classes.md)、[20_object_runtime_and_introspection.md](20_object_runtime_and_introspection.md)、[17_types_and_conversions.md](17_types_and_conversions.md)；仍在语法层但不命中时回到本 Skill 路由中心 [index.md](index.md)；如果问题已经超出语法层，停止并交接给对应事实所有者
|
||||
|
||||
这一篇只讲对象直接参与语言级操作的文档能力：基础算符重载、`[]` 重载、`for in` 重载，以及 `mrows` / `mcols` / `msize` 这类矩阵关键字重载。
|
||||
|
||||
@@ -0,0 +1,36 @@
|
||||
# TSL 语法任务路由
|
||||
|
||||
本页是 24 个 TSL/TSF 语法专题的唯一完整路由。只选择一个最具体的主专题；主专题内已有足够事实时立即停止，只有该页明确列出的候选页才能作为下一跳。
|
||||
|
||||
## 任务 → 主专题 → 停止条件
|
||||
|
||||
| 任务信号 | 主专题 | 停止条件 |
|
||||
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------------------------- |
|
||||
| 写最短骨架、先核对核心语言事实 | [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) | 文件名、模块边界或查找事实缺失 |
|
||||
| 写运行时环境参数、`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) | 重载入口或调用语义不明 |
|
||||
|
||||
## 超出语法层时交接
|
||||
|
||||
函数/API、命名、风格、工具链、模块集成和项目运行事实不属于本路由。命中这些任务时停止语法检索，只说明应交给对应事实所有者，不复制或猜测外部领域内容。
|
||||
@@ -34,7 +34,8 @@ class InstallSkillsTests(unittest.TestCase):
|
||||
agents_index = (root / ".agents" / "tsl" / "index.md").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
self.assertIn(f"`{docs_prefix}/tsl/index.md`", agents_index)
|
||||
self.assertIn("`tsl-syntax-reference`", agents_index)
|
||||
self.assertIn("`tsl-api-reference`", agents_index)
|
||||
self.assertNotIn("`docs/tsl/index.md`", agents_index)
|
||||
|
||||
skill_file = (agents_home / "skills" / "style-cleanup" / "SKILL.md").read_text(
|
||||
@@ -90,6 +91,31 @@ skills = ["karpathy-guidelines"]
|
||||
self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
|
||||
self.assertTrue(skill_file.is_file())
|
||||
|
||||
def test_install_skills_installs_tsl_syntax_reference(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
target = Path(tmp_dir) / "agents"
|
||||
config_body = f"""
|
||||
[playbook]
|
||||
project_root = "{tmp_dir}"
|
||||
playbook_root = "{CUSTOM_DEPLOY_ROOT}"
|
||||
install_mode = "snapshot"
|
||||
|
||||
[install_skills]
|
||||
agents_home = "{target}"
|
||||
mode = "list"
|
||||
skills = ["tsl-syntax-reference"]
|
||||
"""
|
||||
config_path = Path(tmp_dir) / "playbook.toml"
|
||||
config_path.write_text(config_body, encoding="utf-8")
|
||||
|
||||
result = run_cli("-config", str(config_path))
|
||||
|
||||
skill = target / "skills" / "tsl-syntax-reference"
|
||||
self.assertEqual(result.returncode, 0, msg=result.stdout + result.stderr)
|
||||
self.assertTrue((skill / "SKILL.md").is_file())
|
||||
self.assertTrue((skill / "agents" / "openai.yaml").is_file())
|
||||
self.assertTrue((skill / "references" / "index.md").is_file())
|
||||
|
||||
def test_install_skills_rejects_removed_tsl_guide(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
target = Path(tmp_dir) / "agents"
|
||||
|
||||
@@ -243,11 +243,21 @@ langs = ["tsl"]
|
||||
self.assertEqual(result.returncode, 0)
|
||||
text = docs_index.read_text(encoding="utf-8")
|
||||
self.assertIn("`tsl/index.md`", text)
|
||||
self.assertIn("`tsl/syntax/index.md`", text)
|
||||
self.assertIn("tsl-syntax-reference", text)
|
||||
self.assertIn("`tsl/reference/catalog/datawarehouse.md`", text)
|
||||
self.assertIn("`tsl/modules/index.md`", text)
|
||||
self.assertIn("`tsl/reference/index.md`", text)
|
||||
self.assertNotIn("`tsl/syntax_book/index.md`", text)
|
||||
self.assertTrue(
|
||||
(
|
||||
root
|
||||
/ CUSTOM_DEPLOY_ROOT
|
||||
/ "docs"
|
||||
/ "tsl"
|
||||
/ "syntax"
|
||||
/ "index.md"
|
||||
).is_file()
|
||||
)
|
||||
|
||||
def test_external_clone_requires_explicit_playbook_root(self):
|
||||
with tempfile.TemporaryDirectory() as tmp_dir:
|
||||
|
||||
@@ -0,0 +1,66 @@
|
||||
# TSL Syntax Reference Skill Evaluations
|
||||
|
||||
本评测用于验证 `tsl-syntax-reference` v1 的核心检索、应用和职责交接行为。题面不包含答案；每个场景必须在全新 agent 会话中运行并保存原始首答。
|
||||
|
||||
## 固定场景
|
||||
|
||||
| ID | 题面 | 允许文件配置 | 预期路由 | 通过条件 | 禁止行为 |
|
||||
| ------------------------------ | ---------------------------------------------------------------------------------------------- | ------------------- | -------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- |
|
||||
| `syntax-tsl-layout` | 请写一个 `.tsl`：声明一个局部变量，定义一个函数，并在脚本最后调用函数和输出结果。 | `tsl-layout` | `.tsl` 文件模型与快速起手专题 | 先判定 `.tsl` 文件模型；声明区和语句区顺序符合语法资料 | 从 Pascal、Python、JavaScript、TypeScript 或 SQL 猜测语法；读取其他场景输出 |
|
||||
| `syntax-tsf-model` | 请写一个可从 `funcext` 加载并复用的 `.tsf`。 | `tsf-model` | `.tsf` 文件模型与函数扩展或 unit 专题 | 产出可加载的函数扩展或 unit；`.tsf` 内不加入脚本成功标记 | 把脚本语句区写入 `.tsf`；读取其他场景输出 |
|
||||
| `syntax-assignment-named-args` | 请同时解释 TSL 中的赋值、相等比较和命名参数，并分别给出最小写法。 | `assignment-call` | 表达式、赋值与函数调用专题 | 三种形式的边界正确且来源可追溯 | 按相似语言类推；编造未记录形式 |
|
||||
| `syntax-class` | 请定义一个 TSL 类，构造对象并调用一个成员。 | `class-object` | 类、对象创建与成员调用专题 | 类声明和对象创建形态来自对象专题 | 用其他语言的 `class`、`new` 或成员语法补全 TSL |
|
||||
| `syntax-invalid-statement` | 请诊断本文“`invalid-statement` 输入”中的 `.tsl`，说明 `invalid statement` 的原因并给出修正版。 | `invalid-statement` | 常见误写专题与对应文件模型主专题 | 进入 pitfalls 和主专题；指出文件模型或语句位置原因 | 只复述输入代码；只凭错误字符串猜测；绕过文件模型判断 |
|
||||
| `handoff-api` | 请给出一个用于读取行情的精确 TSL API 名称、完整签名、参数和返回值。 | `handoff-api` | `tsl-api-reference` | 明确交给 API Skill，不从语法资料或模型记忆补全 | 编造 API 名称、签名、参数或返回值 |
|
||||
| `handoff-tooling` | 请同时说明 TSL 命名约定，以及 Linux 下解释器的准确执行命令。 | `handoff-tooling` | 项目 ruleset/命名文档与最近 `AGENTS.md`/工具链事实 | 退出语法范围并分别交给对应事实所有者 | 在语法 Skill 中编造命名规则、解释器路径或环境变量 |
|
||||
|
||||
## 允许文件配置
|
||||
|
||||
- `tsl-layout`：`skills/tsl-syntax-reference/SKILL.md`、`skills/tsl-syntax-reference/references/01_quickstart.md`、`skills/tsl-syntax-reference/references/02_core_model.md`、`skills/tsl-syntax-reference/references/05_functions_and_calls.md`。
|
||||
- `tsf-model`：`skills/tsl-syntax-reference/SKILL.md`、`skills/tsl-syntax-reference/references/01_quickstart.md`、`skills/tsl-syntax-reference/references/02_core_model.md`、`skills/tsl-syntax-reference/references/05_functions_and_calls.md`、`skills/tsl-syntax-reference/references/09_units_and_scope.md`。
|
||||
- `assignment-call`：`skills/tsl-syntax-reference/SKILL.md`、`skills/tsl-syntax-reference/references/01_quickstart.md`、`skills/tsl-syntax-reference/references/05_functions_and_calls.md`、`skills/tsl-syntax-reference/references/06_expressions_and_operators.md`。
|
||||
- `class-object`：`skills/tsl-syntax-reference/SKILL.md`、`skills/tsl-syntax-reference/references/01_quickstart.md`、`skills/tsl-syntax-reference/references/08_objects_and_classes.md`。
|
||||
- `invalid-statement`：`skills/tsl-syntax-reference/SKILL.md`、`skills/tsl-syntax-reference/references/01_quickstart.md`、`skills/tsl-syntax-reference/references/02_core_model.md`、`skills/tsl-syntax-reference/references/05_functions_and_calls.md`、`skills/tsl-syntax-reference/references/11_pitfalls.md`。
|
||||
- `handoff-api`：仅 `skills/tsl-syntax-reference/SKILL.md`；场景只验证交接，不读取或回答 API 事实。
|
||||
- `handoff-tooling`：`skills/tsl-syntax-reference/SKILL.md`、`docs/tsl/naming.md`、`docs/tsl/toolchain.md` 和最近的 `AGENTS.md`。
|
||||
|
||||
## `invalid-statement` 输入
|
||||
|
||||
```tsl
|
||||
a := 1;
|
||||
test();
|
||||
|
||||
function test();
|
||||
begin
|
||||
echo "test";
|
||||
end;
|
||||
|
||||
echo "after declaration";
|
||||
```
|
||||
|
||||
## v1 运行边界
|
||||
|
||||
- 显式使用已安装的 `tsl-syntax-reference` 作为语法事实源。
|
||||
- 不把旧 `docs/tsl/syntax/**` 当作回退事实源。
|
||||
- API、命名和工具链事实只交给对应所有者；语法 Skill 不得代替它们编造答案。
|
||||
- v1 不建立无资料 RED 或旧 docs 基线，不运行 `test/agent/prompts_zh.md` 的 100 题综合测试。
|
||||
- v1 不计算迁移前后通过率，也不声明与旧 docs 的行为等价性。
|
||||
|
||||
## 运行与记录
|
||||
|
||||
- 每个场景启动全新会话，记录 agent、model、平台、可见文件清单和事实入口。
|
||||
- 保存原始首答；同一场景不根据解释器或评分反馈循环修复后冒充首次结果。
|
||||
- 五个语法场景必须正确检索或应用；两个 handoff 场景必须停止推断并交给正确所有者。
|
||||
- 运行 TSL 前读取最近的 `AGENTS.md`，检测平台并使用其中规定的解释器环境。
|
||||
- 只对实际产生可执行 `.tsl/.tsf` 的场景运行解释器；解释型和 handoff 场景按本文件条件判定。
|
||||
- 七场景是 v1 轻量 smoke；后续版本按真实失败持续增加回归场景，不维护历史通过率基准。
|
||||
|
||||
## 评分
|
||||
|
||||
每个场景逐项记录 `pass`、`fail` 或 `invalid`：
|
||||
|
||||
- `pass`：满足全部通过条件且没有禁止行为。
|
||||
- `fail`：遗漏任一通过条件、出现任一禁止行为，或可执行产物未通过规定解释器验证。
|
||||
- `invalid`：会话看到其他场景输出、运行反馈、评分材料或隔离配置之外的事实源。
|
||||
|
||||
评测还应记录失败分类：触发失败、错误路由、未读主专题、文件模型错误、语法应用错误、越界编造和隔离污染。
|
||||
@@ -68,7 +68,15 @@ class DeploymentRoutesE2ETests(unittest.TestCase):
|
||||
tsl_index = (project_root / ".agents" / "tsl" / "index.md").read_text(
|
||||
encoding="utf-8"
|
||||
)
|
||||
self.assertIn(f"`{docs_prefix}/tsl/index.md`", tsl_index)
|
||||
self.assertIn("`tsl-syntax-reference`", tsl_index)
|
||||
self.assertIn("`tsl-api-reference`", tsl_index)
|
||||
for relative_path in (
|
||||
"tsl/naming.md",
|
||||
"tsl/code_style.md",
|
||||
"tsl/toolchain.md",
|
||||
"tsl/modules/index.md",
|
||||
):
|
||||
self.assertIn(f"`{docs_prefix}/{relative_path}`", tsl_index)
|
||||
self.assertNotIn("`docs/tsl/index.md`", tsl_index)
|
||||
|
||||
def test_subtree_style_deployment_syncs_project_files(self):
|
||||
|
||||
@@ -0,0 +1,207 @@
|
||||
import re
|
||||
import unittest
|
||||
from pathlib import Path, PurePosixPath
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
SKILL_DIR = ROOT / "skills" / "tsl-syntax-reference"
|
||||
SKILL_FILE = SKILL_DIR / "SKILL.md"
|
||||
REFERENCES_DIR = SKILL_DIR / "references"
|
||||
COMPATIBILITY_INDEX = ROOT / "docs" / "tsl" / "syntax" / "index.md"
|
||||
RULESET_FILE = ROOT / "rulesets" / "tsl" / "index.md"
|
||||
|
||||
TOPIC_REFERENCES = {
|
||||
"01_quickstart.md",
|
||||
"02_core_model.md",
|
||||
"03_values_and_literals.md",
|
||||
"04_variables_and_constants.md",
|
||||
"05_functions_and_calls.md",
|
||||
"06_expressions_and_operators.md",
|
||||
"07_control_flow.md",
|
||||
"08_objects_and_classes.md",
|
||||
"09_units_and_scope.md",
|
||||
"10_runtime_context_and_with.md",
|
||||
"11_pitfalls.md",
|
||||
"12_matrix_and_collections.md",
|
||||
"13_resultset_and_filters.md",
|
||||
"14_ts_sql.md",
|
||||
"15_debug_and_profiler.md",
|
||||
"16_lexical_structure_and_compile_options.md",
|
||||
"17_types_and_conversions.md",
|
||||
"18_external_calls_and_threads.md",
|
||||
"19_namespace_libpath_and_unit_runtime.md",
|
||||
"20_object_runtime_and_introspection.md",
|
||||
"21_builtin_runtime_objects.md",
|
||||
"22_matrix_deep_dive.md",
|
||||
"23_fmarray.md",
|
||||
"24_object_overloads_and_iteration.md",
|
||||
}
|
||||
EXPECTED_REFERENCES = {"index.md", *TOPIC_REFERENCES}
|
||||
MARKDOWN_LINK = re.compile(r"!?\[[^\]]*\]\(([^)]+)\)")
|
||||
|
||||
|
||||
def read_text(path: Path) -> str:
|
||||
return path.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def frontmatter(path: Path) -> dict[str, str]:
|
||||
text = read_text(path)
|
||||
match = re.match(r"\A---\s*\n(.*?)\n---\s*\n", text, re.DOTALL)
|
||||
if not match:
|
||||
raise AssertionError(f"missing YAML frontmatter: {path}")
|
||||
fields: dict[str, str] = {}
|
||||
for line in match.group(1).splitlines():
|
||||
key, separator, value = line.partition(":")
|
||||
if separator:
|
||||
fields[key.strip()] = value.strip().strip("\"'")
|
||||
return fields
|
||||
|
||||
|
||||
def local_link_targets(text: str) -> list[str]:
|
||||
text = re.sub(r"```.*?```", "", text, flags=re.DOTALL)
|
||||
text = re.sub(r"`[^`\n]*`", "", text)
|
||||
targets = []
|
||||
for match in MARKDOWN_LINK.finditer(text):
|
||||
target = match.group(1).strip().split(maxsplit=1)[0].strip("<>")
|
||||
if target.startswith(("#", "http://", "https://", "mailto:")):
|
||||
continue
|
||||
targets.append(target)
|
||||
return targets
|
||||
|
||||
|
||||
class TslSyntaxReferenceSkillStructureTest(unittest.TestCase):
|
||||
def test_local_link_targets_includes_local_images(self) -> None:
|
||||
text = "\n"
|
||||
self.assertEqual(local_link_targets(text), ["images/router.png"])
|
||||
|
||||
def test_skill_name_matches_directory(self) -> None:
|
||||
self.assertEqual(frontmatter(SKILL_FILE)["name"], SKILL_DIR.name)
|
||||
|
||||
def test_frontmatter_description_covers_tsl_and_tsf_tasks(self) -> None:
|
||||
description = frontmatter(SKILL_FILE)["description"]
|
||||
self.assertRegex(description, r"(?i)\bTSL\b")
|
||||
self.assertRegex(description, r"(?i)\bTSF\b")
|
||||
self.assertRegex(description, r"写|编写|修改|审查|解释|语法错误")
|
||||
|
||||
def test_reference_inventory_is_exact(self) -> None:
|
||||
actual = {path.name for path in REFERENCES_DIR.iterdir()}
|
||||
self.assertEqual(actual, EXPECTED_REFERENCES)
|
||||
|
||||
def test_json_router_is_absent(self) -> None:
|
||||
self.assertFalse((REFERENCES_DIR / "00_agent_index.json").exists())
|
||||
self.assertFalse((ROOT / "docs" / "tsl" / "syntax" / "00_agent_index.json").exists())
|
||||
|
||||
def test_references_do_not_escape_skill(self) -> None:
|
||||
for path in REFERENCES_DIR.glob("*.md"):
|
||||
for target in local_link_targets(read_text(path)):
|
||||
link_path = target.split("#", 1)[0].replace("\\", "/")
|
||||
self.assertNotIn("docs/tsl/", link_path, f"{path}: {target}")
|
||||
self.assertFalse(link_path.startswith("/"), f"{path}: {target}")
|
||||
self.assertNotIn("..", PurePosixPath(link_path).parts, f"{path}: {target}")
|
||||
|
||||
def test_reference_markdown_links_resolve(self) -> None:
|
||||
for path in REFERENCES_DIR.glob("*.md"):
|
||||
for target in local_link_targets(read_text(path)):
|
||||
link_path = target.split("#", 1)[0]
|
||||
self.assertTrue((REFERENCES_DIR / link_path).is_file(), f"{path}: {target}")
|
||||
|
||||
def test_index_is_only_complete_topic_router(self) -> None:
|
||||
index_text = read_text(REFERENCES_DIR / "index.md")
|
||||
self.assertEqual(
|
||||
{name for name in TOPIC_REFERENCES if f"]({name})" in index_text},
|
||||
TOPIC_REFERENCES,
|
||||
)
|
||||
for path in REFERENCES_DIR.glob("*.md"):
|
||||
if path.name == "index.md":
|
||||
continue
|
||||
linked_topics = {name for name in TOPIC_REFERENCES if f"]({name})" in read_text(path)}
|
||||
self.assertNotEqual(linked_topics, TOPIC_REFERENCES, path.name)
|
||||
|
||||
skill_links = set(local_link_targets(read_text(SKILL_FILE)))
|
||||
self.assertEqual(
|
||||
skill_links,
|
||||
{
|
||||
"references/01_quickstart.md",
|
||||
"references/index.md",
|
||||
"references/11_pitfalls.md",
|
||||
},
|
||||
)
|
||||
|
||||
def test_skill_does_not_bundle_external_domains(self) -> None:
|
||||
forbidden = {
|
||||
"naming.md",
|
||||
"code_style.md",
|
||||
"toolchain.md",
|
||||
"modules",
|
||||
"tsl-api-reference",
|
||||
"00_agent_index.json",
|
||||
}
|
||||
actual = {path.name for path in SKILL_DIR.rglob("*")}
|
||||
self.assertTrue(forbidden.isdisjoint(actual), forbidden & actual)
|
||||
|
||||
def test_compatibility_index_contains_no_syntax_facts(self) -> None:
|
||||
text = read_text(COMPATIBILITY_INDEX)
|
||||
self.assertIn("../../../skills/tsl-syntax-reference/SKILL.md", text)
|
||||
for forbidden in (
|
||||
"```",
|
||||
"代码块身份",
|
||||
"01_quickstart.md",
|
||||
"02_core_model.md",
|
||||
"| 任务",
|
||||
):
|
||||
self.assertNotIn(forbidden, text)
|
||||
|
||||
def test_ruleset_file_remains_tsl_router(self) -> None:
|
||||
self.assertTrue(RULESET_FILE.is_file())
|
||||
text = read_text(RULESET_FILE)
|
||||
for route in (
|
||||
"tsl-syntax-reference",
|
||||
"tsl-api-reference",
|
||||
"naming.md",
|
||||
"code_style.md",
|
||||
"toolchain.md",
|
||||
"modules/index.md",
|
||||
"项目",
|
||||
):
|
||||
self.assertIn(route, text)
|
||||
|
||||
def test_ruleset_routes_both_tsl_skills(self) -> None:
|
||||
text = read_text(RULESET_FILE)
|
||||
self.assertRegex(text, r"语法[^\n]*tsl-syntax-reference|tsl-syntax-reference[^\n]*语法")
|
||||
self.assertRegex(text, r"API|函数")
|
||||
self.assertIn("tsl-api-reference", text)
|
||||
|
||||
def test_ruleset_syntax_constraints_moved_to_skill(self) -> None:
|
||||
ruleset = read_text(RULESET_FILE)
|
||||
owner = read_text(SKILL_FILE) + "\n" + "\n".join(
|
||||
read_text(path) for path in REFERENCES_DIR.glob("*.md")
|
||||
)
|
||||
self.assertRegex(ruleset, r"缺失|不可用")
|
||||
self.assertRegex(ruleset, r"停止|阻断")
|
||||
for forbidden in (
|
||||
"```tsl",
|
||||
"代码块身份",
|
||||
".tsl` / `.tsf` 后缀由用户指定时",
|
||||
".tsl` 代码需要本文件内函数或类时",
|
||||
):
|
||||
self.assertNotIn(forbidden, ruleset)
|
||||
self.assertIn("代码块身份", owner)
|
||||
self.assertIn(".tsl", owner)
|
||||
self.assertIn(".tsf", owner)
|
||||
|
||||
def test_static_docs_route_to_fact_owner(self) -> None:
|
||||
routes = {
|
||||
ROOT / "docs" / "tsl" / "index.md": "../../skills/tsl-syntax-reference/SKILL.md",
|
||||
ROOT / "docs" / "tsl" / "naming.md": "../../skills/tsl-syntax-reference/SKILL.md",
|
||||
ROOT / "docs" / "tsl" / "code_style.md": "../../skills/tsl-syntax-reference/SKILL.md",
|
||||
ROOT / "docs" / "index.md": "../skills/tsl-syntax-reference/SKILL.md",
|
||||
}
|
||||
legacy_deep_link = re.compile(r"(?:docs/tsl/)?syntax/(?:0[1-9]|1[0-9]|2[0-4])_")
|
||||
for path, expected_link in routes.items():
|
||||
text = read_text(path)
|
||||
self.assertIn(expected_link, text, path)
|
||||
self.assertIsNone(legacy_deep_link.search(text), path)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user