📝 docs(tsl): align agent-facing guidance

docs/tsl/index.md

@@ -6,22 +6,26 @@
 是否含已验证反例：否
 遇到不确定时跳转到：[syntax/index.md](syntax/index.md)、[finance/index.md](finance/index.md)、[reference/index.md](reference/index.md)、[modules/index.md](modules/index.md)、项目自身文档、`scripts/*` 入口脚本、CI 配置
 
-这个入口文件只负责一件事：让新 session 先判断主问题属于哪一层，再进入最相关的单个入口页。
+这个入口文件只负责一件事：让 agent 先判断主问题属于哪一层，再进入最相关的单个入口页。这里的语法文档面向 agent 决策，不按人类教程组织；回答和生成代码时必须按流程读，不要凭语言相似性补全。
 
 ## 先记住这些规则
 
 - 先读本文件，不要默认通读全部 TSL 文档。
+- 用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据；未给后缀时，再根据用户交付目标判断。
+- `.tsl` 是可执行脚本；`.tsf` 是部署到解释器 `funcext` 的模块/函数扩展文件。
+- 写 `.tsl` 时按两段理解：语句区在前并按顺序执行；函数/类声明区在后，供前面的语句调用或运行时解析。
+- 写 `.tsf` 时按模块/扩展理解；顶层函数部署到 `funcext` 后，`.tsl` 脚本可以直接调用。
 - 语言怎么写的问题，先从 `docs/tsl/syntax/` 开始。
 - 指标、选股、回测和策略流程的问题，先从 `docs/tsl/finance/` 开始；不要先把业务问题拆成纯语法问题。
 - 某个函数怎么用、属于哪个函数库分类或目录，先从 `docs/tsl/reference/` 开始。
 - 现成模块、外部集成和互操作问题，先从 [modules/index.md](modules/index.md) 开始。
 - 账户体系、真实接口名、部署方式、脚本入口、权限模型、环境变量、CI、验证命令这类问题，先按“项目依赖 / 项目执行”处理；优先回项目自身文档、`scripts/*` 入口脚本、CI 配置。
 - [toolchain.md](toolchain.md) 不是 TSL 语法子类，而是项目执行类辅证页；只有当前项目已经补齐工具链与验证信息时才使用；如果这页仍是模板，不把它当主入口。
-- 顶层主体优先按四类理解：松散语句、`function / procedure`、`type Name = class`、`unit`。
-- 不要把顶层 `function / procedure` 定义和松散语句混在同一个文件模型里。
+- 生成 `.tsl` 代码时，优先从脚本语句区开始；如果关键词要求函数或类，把声明放在语句区之后。
+- 不要在 `.tsl` 的函数/类声明区之后再追加新的脚本语句。
 - 任何语法判断都先看正式语法页结论。
-- 如果涉及较新写法、资料冲突或解释器差异，先回到 `docs/tsl/syntax/index.md`，再按主题跳到对应语法页；只有对应主题页仍然没有结论时，才本地用 `tsl` 验证。
-- 如果涉及高频误写、反例或负向边界，优先回到 `docs/tsl/syntax/12_pitfalls.md`；只有结论缺失时，才本地用 `tsl` 验证。
+- 如果涉及较新写法、资料冲突或解释器差异，先回到 `docs/tsl/syntax/index.md`，再按主题跳到对应语法页；对应主题页仍然没有结论时，不要自行补语法。
+- 如果涉及高频误写、反例或负向边界，优先回到 `docs/tsl/syntax/12_pitfalls.md`；结论缺失时不要把猜测写成语法事实。
 - 模板、错误示例和输出片段不算可独立编译代码。
 
 ## 元数据与证据标签
@@ -34,8 +38,27 @@
 - 如果还需要补充用途、限制或复用建议，单独写 `代码块说明`，不要把说明文字继续拼进 `代码块身份`。
 - 如果页头里的 `遇到不确定时跳转到` 列出多个目标，默认第一项是优先入口，后面的目标只用于分流或补证。
 
+## 维护者入文档前验证
+
+- TSL 语法页面向 agent 生成代码；所有写成语法事实的代码库样例，必须先由维护者在项目验证环境中确认。
+- 正向代码库样例只有在环境验证通过后，才能标成 `已验证可执行示例`；对应输出只能标成 `已验证输出片段`。
+- 负向代码库样例只有在环境中确认失败形态后，才能标成 `反例 / 不可照写`。
+- 未经过环境验证的写法不能写成语法事实；只能作为文档缺口、待验证项，或标成 `配置片段 / 概念骨架`。
+- 验证过程不写进语法页；解释器路径、Docker、Windows、Ubuntu、环境变量和执行命令属于项目执行层，不能混入通用语法事实。
+- agent 不需要自行执行验证；agent 只根据维护者已经写入文档的证据标签生成代码，遇到未覆盖写法时不要发明语法。
+
 ## 新 session 起手规则
 
+### Agent 读取流程
+
+1. 识别目标层：语法、金融业务、函数库、模块/集成、项目执行。
+2. 识别用户指定的文件后缀；用户已给出 `.tsl` / `.tsf` 后缀时，后缀就是判断依据。
+3. 用户未给后缀时，按交付目标判断：可执行代码对应 `.tsl`，通用模块对应 `.tsf`；仍不明确时向用户确认。
+4. 对 `.tsl`，先生成语句区；需要本文件函数/类时，再生成声明区。
+5. 对 `.tsf`，生成模块/扩展声明；部署后的顶层函数可由脚本直接调用。
+6. 只读取当前任务命中的单个入口页；不要同时展开语法、业务、函数库和工具链。
+7. 生成代码前找 `代码块身份：已验证可执行示例`；遇到 `反例 / 不可照写` 必须避开。
+
 ### If / Then 路由
 
 - If 问题在问“语言怎么写”，then 先从 [syntax/index.md](syntax/index.md) 开始。
@@ -57,17 +80,17 @@
 ### 语言事实
 
 - 可以先把 TSL 当成 Pascal 风格语言去理解：`function`、`begin`、`end`、`unit`、`uses` 都很接近；但这里只借外形，不默认继承 Pascal 的全部语义、库习惯和文件模型。
-- 涉及赋值、`function / procedure` 外形、`unit` 骨架、命名参数、`type Name = class`、数组 / 字符串下标这类高频硬规则，统一以 [syntax/02_quickstart.md](syntax/02_quickstart.md) 的“语言核心事实速查”为准；当前页只保留跨层路由所需的最小提醒。
+- 涉及赋值、`.tsl` 语句区 / 声明区、`.tsf` 模块、`function / procedure` 外形、`unit` 骨架、命名参数、`type Name = class`、数组 / 字符串下标这类高频硬规则，统一以 [syntax/02_quickstart.md](syntax/02_quickstart.md) 的“语言核心事实速查”为准；当前页只保留跨层路由所需的最小提醒。
 
 #### 写代码前先记住
 
 - 写代码前先把高频硬规则收口到 [syntax/02_quickstart.md](syntax/02_quickstart.md)，不要分别从入口页、介绍页和文件模型页拼接结论。
-- 顶层主体仍优先按四类理解：松散语句、`function / procedure`、`type Name = class`、`unit`。
+- `.tsl` 仍优先按“语句区在前、声明区在后”的脚本模型理解；`.tsf` 仍优先按部署到 `funcext` 的模块/扩展理解。
 - 模板、错误示例和输出片段不算可独立编译代码；真正落代码时优先看块级 `代码块身份`。
 
 ### 手册建模规则
 
-- 更可靠的识别方式是看顶层内容，而不是只看文件扩展名。
+- 更可靠的识别方式是同时看任务目标和顶层内容，而不是只看文件扩展名。
 - 顶层允许出现 `uses`，但这里只把它当辅助语句，不把它当主体声明。
 - 下游大量 `program test; begin ... end.` 形式，只作为自包含验证样例外壳，不作为这里归纳的正式顶层模型。
 
@@ -108,4 +131,4 @@
 4. 当前页如果已经给出结论，先采用；准备编写时优先找已验证正例，再落代码；只有需要补充时再跳到相邻页。
 5. 遇到“资料写法不一致”且偏较新写法、资料冲突或解释器差异时，先回 [syntax/index.md](syntax/index.md) 按主题跳到对应语法页。
 6. 遇到“资料写法不一致”且偏高频误写、反例或负向边界时，先看 [syntax/12_pitfalls.md](syntax/12_pitfalls.md)。
-7. 只有当前手册没有给出结论时，才写最小 `.tsl` / `.tsf` 例子并用 `tsl` 实测。
+7. 如果当前手册没有给出结论，不要发明语法；改为向用户确认、记录文档缺口，或等待维护者用项目环境补充已验证结论。