📝 docs(tsl): align agent-facing guidance

2026-05-28 19:12:34 +08:00
parent c48354e0cb
commit d8eb418277
63 changed files with 1921 additions and 371 deletions
@@ -16,10 +16,22 @@

 ## TSL 核心约定（不可违反）

- 文件结构：一文件一顶层声明；文件名 = 声明名；`.tsl` 仅 `function`，`.tsf` 可 `function/class/unit`
+- 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，再根据用户交付目标判断。
+- `.tsl` 是可执行脚本：语句区按顺序执行；如果需要函数/类，放在脚本语句后的函数/类声明区。
+- `.tsf` 是模块/函数扩展文件：部署到解释器 `funcext` 后，脚本可直接调用其中暴露的顶层函数。
 - 格式：4 空格缩进；关键字小写；多语句用 `begin/end`
 - 命名：类型/函数/property `PascalCase`；变量/参数 `snake_case`；私有 `snake_case_`；常量 `kPascalCase`

+## agent 判断流程
+
+1. 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据。
+2. 用户未给后缀时，先判断交付目标是可执行代码还是通用模块；可执行代码对应 `.tsl`，通用模块对应 `.tsf`。
+3. 交付目标仍不明确时向用户确认，不要替用户发明文件形态。
+4. 写 `.tsl` 时，先生成顺序执行的语句区；调用本脚本内函数时，函数声明写在语句区之后。
+5. 写 `.tsf` 时，只生成模块/扩展声明；顶层函数部署到解释器 `funcext` 后才可被脚本直接调用。
+6. 如果关键词命中业务、函数库、模块集成或项目执行信息，按 `docs/tsl/index.md` 分流，不把所有问题都当语法问题。
+7. 不确定时先找已验证可执行示例、反例页和对应专题页；没有文档结论时不要发明语法，改为向用户确认或记录文档缺口。
+
 ## 安全红线（不可触碰）

 - 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key