129 lines
7.1 KiB
Markdown
129 lines
7.1 KiB
Markdown
---
|
|
name: tsl-syntax-reference
|
|
description: "当用户需要编写、修改、审查或解释 TSL/TSF、TS-SQL、Tinysoft/天软脚本或公式，涉及 `.tsl` / `.tsf` 文件，排查 invalid statement 等语法错误，或核对语言与运行时结构规则时使用；包括你自认为已经确定的写法。不用于查询 API 签名或天软数据字典字段（改用 tsl-api-reference），也不用于选择解释器或运行方式（读取目标文件附近的 AGENTS.md）。"
|
|
---
|
|
|
|
# TSL Syntax Reference
|
|
|
|
## 唯一检索入口
|
|
|
|
输出任何 TSL/TSF 代码、或修改任何 `.tsl` / `.tsf` 文件前，先用随附的
|
|
`scripts/lookup.py` 取回事实。记忆里的 TSL 写法不构成依据，赋值符号、声明位置和
|
|
下标起点这类"看起来确定"的规则同样要取回。`<this-skill-dir>` 指本 `SKILL.md`
|
|
所在目录。
|
|
|
|
```bash
|
|
python <this-skill-dir>/scripts/lookup.py --help
|
|
```
|
|
|
|
构造任一命令前先运行上面的 `--help`。帮助输出独占动作、mode、参数范围、查询词、
|
|
弱命中、概念地图、前置章节、Owner Section、结构校验和退出码的命令契约；不要在本
|
|
文件中推断或复用旧参数。检索必须完成 `--query` 到 `--section` 两步，只有
|
|
`--section` 返回的正文可作为语法事实。`syntax-01-002` 是派生速查；命中其中规则后，
|
|
按紧邻规则的 `Owner Section` 取回真正拥有该事实的专题 Section。
|
|
|
|
## 代码块必须标注来源
|
|
|
|
给出的每个 TSL/TSF 代码块，紧随其后写一行来源标注，列出所依据的全部 Section ID：
|
|
|
|
```txt
|
|
来源：syntax-05-004（可直接照写示例），syntax-02-002
|
|
```
|
|
|
|
Section ID 抄自 `--section` 输出首部的 `Section ID:` 行。多个要素合成一个代码块时，
|
|
逐个列出，逗号分隔。身份按取回的正文分两种写法：
|
|
|
|
- 该 Section ID 提供了照写的代码围栏：在 ID 后用括号写出紧邻该围栏的
|
|
`代码块身份：` 值。
|
|
- 该 Section ID 只提供散文规则、正文里没有代码围栏（如
|
|
`syntax-02-002`）：只写 ID，不加括号。规则段落没有身份行，
|
|
这不是缺口。
|
|
|
|
写不出某个要素的 Section ID，说明该要素还没有取回：先补齐检索，再给代码。
|
|
|
|
不含代码块的语法解释同样要在相关结论后列出依据的 Section ID；多个结论来自不同
|
|
章节时逐项对应，不用一个 Section ID 为整段未取回的结论背书。
|
|
|
|
## 代码块身份
|
|
|
|
`--section` 正文里每个代码围栏前有一行 `代码块身份：`。身份决定这段代码能否进入
|
|
你的输出：
|
|
|
|
| 身份 | 允许的用法 |
|
|
| --------------------- | --------------------------------------------------------------------- |
|
|
| `可直接照写示例` | 作为源码外形照写，替换业务内容后使用；依赖的 API 仍按事实边界另行核对 |
|
|
| `反例 / 不可照写` | 只用于说明错误边界，不得作为实现出现在输出里 |
|
|
| `输出片段` | 只用于说明运行结果，不得当作源码 |
|
|
| `配置片段 / 概念骨架` | 只用于表达结构或配置意图，不得当作可运行代码 |
|
|
| `仅服务端可执行示例` | 只在对应服务端环境成立，不得当作通用本地示例 |
|
|
|
|
`--query` 的候选摘要不含身份行，身份只能从 `--section` 正文读取。这是必须走完第
|
|
二步的另一个原因。
|
|
|
|
同一个 section 常同时含多种身份（如示例代码后紧跟 `输出片段`）。身份按围栏逐个
|
|
对应，不按 section 整体判断；一个代码块的依据跨越多种身份时，按最严格的那条处理
|
|
——只要含 `反例 / 不可照写`，就不能照写。
|
|
|
|
## 缺口时停止
|
|
|
|
**🔴 CHECKPOINT · 🛑 STOP：确认以下缺口后停止生成，不输出含缺口要素的代码。**
|
|
|
|
出现下列任一情形，即为事实缺口：
|
|
|
|
**检索缺口** —— `--query` 改进查询词后仍无匹配；lookup 返回非零状态；`--section`
|
|
取回的正文没有支持当前结论；`--section` 正文里目标围栏前没有 `代码块身份：` 行。
|
|
|
|
**环境缺口** —— 目标运行时版本不明；项目路径、数据结构或运行参数等项目事实缺失；
|
|
`tsl-api-reference` 等依赖的 Skill 不可用。
|
|
|
|
缺口时的输出由三部分组成，按此顺序：
|
|
|
|
1. 已取回并可用的事实，只列 Section ID，不复述正文。
|
|
2. 缺失的具体要素，以及为它试过的查询词。
|
|
3. 需要用户提供什么，或需要哪个 Skill、哪份项目文档补齐。
|
|
|
|
不输出包含缺口要素的 TSL 代码，注释掉的、标 TODO 的和「仅供参考」的版本同样不
|
|
输出。一段代码里只要有一个要素没取回，整段都不给出，不交付「其余部分已验证」的
|
|
半成品。
|
|
|
|
不得改为下列任一做法：
|
|
|
|
- 手工浏览或顺序通读 `references/` 页面。
|
|
- 凭记忆、相似语言或猜测产生新的 TSL 写法。
|
|
- 用候选摘要或概念地图代替章节正文。
|
|
- 给出未标注来源的代码块。
|
|
|
|
## 事实边界
|
|
|
|
本 Skill 只拥有 TSL/TSF 的语言语法、文件模型、表达式、控制流、对象、运行时语言
|
|
结构和 TS-SQL 外形。混合请求先逐项拆分，只回答其中的语法部分。
|
|
|
|
API 名称、签名、参数、返回值、平台 scope、解释器可用性和金融取数事实属于
|
|
`tsl-api-reference` skill。准备面向用户交付的 TSL/TSF 代码时，按下面顺序处理：
|
|
|
|
1. 先枚举代码中除语言关键字和用户定义符号外的调用标识符。
|
|
2. 语言结构逐项用本 Skill 取回；每个 builtin/API 都逐项用 `tsl-api-reference` 取回
|
|
名称、签名和目标 scope。
|
|
3. 任一 API 依赖没有取回时，整段交付代码按「缺口时停止」处理；不能只给语法已查的
|
|
半成品，也不能凭语法页示例中的 API 名称补齐。
|
|
|
|
纯语法说明可以使用明确标为占位的用户定义调用来展示调用位置，而不必为该占位符查
|
|
API；但不得声称该占位调用的 API 行为或输出，也不得把真实 builtin/API 当成无需核对
|
|
的占位符。解释一旦包含真实 API 的签名、可用性、返回值、输出，或代码将面向用户
|
|
交付，就必须执行上面的 API 取回步骤。
|
|
|
|
## 运行方式不属于本 Skill
|
|
|
|
TSL 的运行方式、解释器路径、平台检测和环境选择都不是本 Skill 的事实。用户询问
|
|
如何运行 TSL，或需要实际执行 TSL 时，读取目标文件附近最近的 `AGENTS.md`、项目
|
|
脚本或 CI，并严格照其规定执行。
|
|
|
|
本 Skill 只能确认语法外形正确，不能确认代码在目标解释器上可运行。给出未经执行的
|
|
代码时，据此区分「语法已取回」与「运行时未验证」。用户未要求实际执行时，解释器
|
|
不可用是受支持状态，不构成事实缺口，也不要求提供可重放运行证据。
|
|
|
|
## 维护校验
|
|
|
|
维护本 Skill、参考页、词表或检索器时，先读 [`data/README.md`](data/README.md)，按其中
|
|
的 Section ID、派生规则、粒度和验证纪律执行。
|