# TSL 智能体规则

文档类型：高优先级智能体决策规则
是否可直接用于生成代码：否
作用：控制智能体在阅读、修改、生成 TSL 代码前的判断顺序、文档路由、禁止行为和自检流程。

本文件不是 TSL 语法手册，也不是完整教程。智能体必须先按本文件判断任务类型，再进入对应的 `docs/tsl/` 页面查阅语法、函数库或模块集成信息。

生成 TSL 代码时，禁止凭 Pascal、Python、JavaScript、TypeScript 或其他语言的相似写法补全 TSL 语法。文档没有给出结论时，必须向用户确认、记录文档缺口，或改用文档已经写明的可照写示例，不得发明语法。

## 范围与优先级

- 本文件是仓库级 TSL 智能体高优先级规则。
- 更靠近代码目录的本地规则可以增加更严格的约束，但不能削弱本文件中的安全、文档事实和禁止发明语法规则。
- 本文件控制智能体行为和判断顺序，不替代 `docs/tsl/` 下的语法、函数库、模块集成或项目执行文档。
- 当本文件与 `docs/tsl/**` 冲突时，按以下顺序处理：
  1. 安全与凭据处理规则。
  2. 用户明确指令中关于目标、交付物、文件路径和风格偏好的部分。
  3. 本地目录规则中更具体且不削弱本文件安全、文档事实和禁止发明语法规则的部分。
  4. 本智能体规则集。
  5. TSL 语法/函数库事实文档。
  6. 现有项目代码模式。
- 用户明确指令不能覆盖安全规则、文档事实使用规则、禁止发明语法规则或 TSL 事实。如果用户要求生成未写入文档的语法，必须说明风险，并按用户意图将结果标注为示例或伪代码；不得把它包装成可运行 TSL 或可直接照写示例。
- 如果两个权威来源对 TSL 语法结论不一致，不要猜测。必须说明冲突，优先采用 `代码块身份：可直接照写示例`；当差异会影响生成代码正确性时，先向用户确认。

## 代码生成协议

生成或修改 TSL 代码前，智能体必须执行以下流程：

1. 识别用户交付目标：可执行脚本、可复用模块、语法解释、缺陷修复、重构、业务逻辑、函数查询或集成任务。
2. 识别文件模型：
   - 用户要求可执行脚本或入口流程时，使用 `.tsl`。
   - 用户要求可复用函数、过程、类、模块或扩展代码时，使用 `.tsf`。
   - 文件模型会影响正确性且需求不明确时，生成代码前向用户确认。
3. 路由到 `docs/tsl/` 下最小且最相关的权威文档。
4. 生成代码外形时，优先参考 `代码块身份：可直接照写示例`。
5. 避开任何标记为 `代码块身份：反例 / 不可照写` 的代码块。
6. 除非文档明确说明组合方式，否则不要把多个页面的片段拼成新的语法外形。
7. 没有文档结论时，不要发明语法；改为向用户确认或记录文档缺口。
8. 生成代码后，执行本文件中的最终 TSL 自检。

## TSL 核心事实

以下只保留高优先级提醒。完整文件模型看 `docs/tsl/syntax/02_core_model.md`；完整语法细节从 `docs/tsl/syntax/index.md` 分流。

- `.tsl` 在通用 TSL 规则中表示可执行脚本；如果项目把 `.tsl` 另作它用，必须先确认项目约定，不能反推为通用事实。
- `.tsf` 表示可复用函数、过程、类、模块或扩展文件；部署到解释器 `funcext` 后供脚本调用，部署、查找路径和文件名细节必须回到语法页或项目文档确认。
- 用户明确给出 `.tsl` 或 `.tsf` 后缀时，后缀是主要文件模型信号；未给后缀时先按交付目标初判，影响正确性且不明确就先确认。
- 入口流程、脚本任务或一次性任务默认 `.tsl`；可复用函数、过程、类、模块或扩展默认 `.tsf`；脚本内部封装函数或类不自动升级为 `.tsf`。
- 在 `.tsl` 中，可执行语句必须位于前部并按顺序执行；如果需要本文件内函数或类，声明区放在语句区之后，且声明区后不要继续追加脚本语句。
- 在 `.tsf` 中，只生成可复用顶层声明或 `unit`；不要写成顺序执行入口。
- 创建对象有两种方式：`new ClassName()` 最常用，`createObject(...)` 作为次选；需要字符串类名、类类型变量或跨 `unit` 路径时，更适合用 `createObject(...)`。
- 不要因为 Pascal、Python、JavaScript 或 TypeScript 支持某种写法，就假设 TSL 也支持。

## 任务路由

先路由任务，再阅读详细文档。不要把所有 TSL 相关请求都当成语法请求。

- 如果用户询问语言语法怎么写，先读 `docs/tsl/syntax/index.md`。
- 如果用户要求最短可运行骨架，先读 `docs/tsl/syntax/01_quickstart.md`。
- 如果用户询问某个语法形式是否有效，先读 `docs/tsl/syntax/index.md`，再进入最小匹配专题页。
- 如果用户询问常见误写、反例或不安全假设，先读 `docs/tsl/syntax/11_pitfalls.md`。
- 如果用户询问行情、财务、板块、选股等金融函数，先读 `docs/tsl/reference/catalog/datawarehouse.md`。
- 如果用户询问 Python 调 TSL 服务器函数、批量取数或异步取数，先读 `docs/tsl/modules/pytsl_api.md`。
- 如果用户询问回测框架、组合回测、交易流程或回测结果读取，先读 `docs/tsl/modules/tsbacktesting.md`。
- 如果用户询问某个内置函数或函数库函数怎么用，先读 `docs/tsl/reference/index.md`。
- 如果用户询问模块、集成、pyTSL、微信消息或回测模块，先读 `docs/tsl/modules/index.md`。
- 如果用户询问账户体系、真实服务端点、部署、脚本入口、环境变量、CI 或验证命令，把问题视为项目执行上下文；优先查项目文档、`scripts/*` 和 CI 配置，不要从通用 TSL 语法文档里猜。

### 路由冲突处理

- 如果一个任务同时涉及业务和语法，按用户的主要目标路由。
- 如果主要目标是业务行为，先读模块文档、函数事实页或项目实际接口文档，语法文档只做辅助。
- 如果主要目标是语言有效性，先读语法文档，业务或模块文档只作为示例和上下文。
- 如果任务依赖真实凭据、账户、部署或环境行为，不要发明项目事实；必须询问用户或检查项目专属文件。

## 文档入口

按目的选择来源，不要默认通读全部文档。

| 目的                          | 来源                                          | 性质       |
| ----------------------------- | --------------------------------------------- | ---------- |
| 顶层路由                      | `docs/tsl/index.md`                           | 决策入口   |
| 语法判断                      | `docs/tsl/syntax/index.md`                    | 语法入口   |
| 最短可运行骨架与核心事实      | `docs/tsl/syntax/01_quickstart.md`            | 语法入口   |
| 高频误写与反例                | `docs/tsl/syntax/11_pitfalls.md`              | 语法入口   |
| 数据仓库金融函数              | `docs/tsl/reference/catalog/datawarehouse.md` | 函数事实   |
| pyTSL / 服务器函数 / 批量取数 | `docs/tsl/modules/pytsl_api.md`               | 模块 API   |
| 回测框架与结果接口            | `docs/tsl/modules/tsbacktesting.md`           | 模块 API   |
| 模块与集成任务                | `docs/tsl/modules/index.md`                   | 集成入口   |
| 函数库查询                    | `docs/tsl/reference/index.md`                 | 函数库入口 |
| 本仓库格式偏好                | `docs/tsl/code_style.md`                      | 非语法事实 |
| 本仓库/作者命名偏好           | `docs/tsl/naming.md`                          | 非语法事实 |

## 文档事实使用策略

- 页面级元数据只是粗粒度信号。生成代码时，优先看代码块级别的 `代码块身份`。
- 优先参考标记为 `代码块身份：可直接照写示例` 的代码块。
- 永远不要复制标记为 `代码块身份：反例 / 不可照写` 的代码块作为可运行代码。
- `代码块身份：配置片段 / 概念骨架` 只能作为结构提示，不能当作可直接运行代码。
- `代码块身份：输出片段` 只能作为输出形态，不能当作源码。
- 模板、错误示例和输出片段都不是可独立编译代码。
- 如果某页没有覆盖请求所需语法外形的可直接照写示例，不要发明缺失语法；改为询问、记录文档缺口，或使用更简单且已有文档支持的写法。
- `code_style.md` 与 `naming.md` 只表达本仓库或作者风格偏好，不代表 TSL 语法事实。

## 安全规则

- 不得把明文密钥、密码、token、API key、cookie、私钥或真实凭据写入代码、日志、注释、示例、测试或文档。
- 如果用户提供真实敏感信息，不要复述；替换为 `<TOKEN>`、`<API_KEY>` 或 `<PASSWORD>` 等占位符。
- 如果现有代码中出现疑似敏感信息，必须明确标注风险，并避免把它复制到新代码或解释中。
- 修改鉴权、授权、权限检查、账户处理、交易权限、下单或生产执行路径时，必须说明动机和风险。
- 不确定某个值是否敏感时，按敏感信息处理。
- 不要发明账户 ID、服务端点、生产路径或凭据名称；必须使用项目专属文档，或向用户确认。
- 金融或交易任务中，除非用户明确要求且项目文档确认执行路径，否则不要生成会静默真实下单、改变账户状态或使用生产凭据的代码。
- 当任务可能影响真实交易或外部系统时，优先使用 dry-run、仿真、回测或显式确认流程。

## 修改纪律

- 改动必须小而聚焦，只服务于用户当前请求。
- 避免无关重构、格式刷屏或文档大改。
- 除非用户明确要求，不要新增依赖、工具、脚本或执行要求。
- 引入新模式前，先遵循现有项目风格、文件布局和命名习惯。
- 编辑 TSL 文档时，保留元数据字段和 `代码块身份` 标签，因为智能体路由依赖这些信息。
- 不要声称生成或修改后的代码已经验证，除非确实运行了对应命令或已有项目执行记录。

## 最终 TSL 自检

展示生成或修改后的 TSL 代码前，必须检查：

1. 任务是否路由到正确层：语法、函数库、模块集成或项目执行。
2. 文件模型是否正确：`.tsl` 用于可执行脚本，`.tsf` 用于可复用函数、过程、类、模块或扩展。
3. 对 `.tsl`，可执行语句是否位于本文件函数/类声明之前。
4. 对 `.tsl`，声明区之后是否没有继续追加可执行脚本语句。
5. 对 `.tsf`，代码是否是可复用顶层声明；文件名已知时，是否尊重文件基名与声明名关系。
6. 代码外形是否基于文档事实或 `代码块身份：可直接照写示例`。
7. 是否没有把 `反例 / 不可照写`、输出片段或概念骨架当作可运行代码复制。
8. 是否没有从其它语言家族发明 TSL 语法。
9. 是否没有猜测内置名、函数库函数、模块行为或项目事实。
10. 如果任务要求遵循本仓库风格，是否只把 `code_style.md` 和 `naming.md` 当作本仓库/作者偏好，而不是语法事实。
11. 是否没有引入密钥、凭据、生产端点或不安全的交易/账户行为。
12. 仍不确定的地方是否明确说明，而不是隐藏在生成代码里。