diff --git a/README.md b/README.md index 0e6f5fcd..d98b4c82 100644 --- a/README.md +++ b/README.md @@ -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 | `$` 触发或智能体判定 | 操作指南、最佳实践、工作流 | 指导具体怎么做 | -| Layer 3 | 按需读取特定章节 | 完整语言手册、代码风格、工具链 | 最终权威（冲突时以此为准） | +| 层级 | 加载方式 | 内容 | 作用 | +| ------- | -------------------------------- | -------------------------------------- | ------------------------------------- | +| Layer 1 | 自动，始终在上下文 | 核心约束、优先级、所有者路由和阻断规则 | 快速定位事实所有者并判断能做/不能做 | +| Layer 2 | `$` 触发或智能体判定 | 操作指南、工作流和可安装参考知识 | 执行任务或查询 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）： diff --git a/docs/index.md b/docs/index.md index 5f97b07e..6fb61eb2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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` diff --git a/docs/tsl/code_style.md b/docs/tsl/code_style.md index adc742fa..0afd2863 100644 --- a/docs/tsl/code_style.md +++ b/docs/tsl/code_style.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`（保持清晰优先；一旦分支变复杂就回退到块结构）： 代码块身份：配置片段 / 概念骨架 diff --git a/docs/tsl/index.md b/docs/tsl/index.md index f93c8ac4..49897ddb 100644 --- a/docs/tsl/index.md +++ b/docs/tsl/index.md @@ -6,11 +6,11 @@ 本表只做「任务 → 文档区」分流；区内细分交给各区 `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 事实 | -| 命名与代码风格：变量、函数、类型、文件取名，注释与代码组织 | 取名看 [naming.md](naming.md)；注释与组织看 [code_style.md](code_style.md) | 要查的是语法或函数事实 | -| 具体模块能力：Python 调 TSL、策略回测、微信通知/告警 | [modules/index.md](modules/index.md) | 只是纯语法或普通取数 | +| 任务信号 | 入口 | 阻断条件 | +| ---------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------- | +| 要生成或编写 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) | 只是纯语法或普通取数 | diff --git a/docs/tsl/naming.md b/docs/tsl/naming.md index 385ae36c..48df00bb 100644 --- a/docs/tsl/naming.md +++ b/docs/tsl/naming.md @@ -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` 可写结构。 diff --git a/docs/tsl/syntax/00_agent_index.json b/docs/tsl/syntax/00_agent_index.json deleted file mode 100644 index d1ba365a..00000000 --- a/docs/tsl/syntax/00_agent_index.json +++ /dev/null @@ -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)" - } - } -} diff --git a/docs/tsl/syntax/index.md b/docs/tsl/syntax/index.md index 11f5b966..1f81e25f 100644 --- a/docs/tsl/syntax/index.md +++ b/docs/tsl/syntax/index.md @@ -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 语法任务。 diff --git a/rulesets/tsl/index.md b/rulesets/tsl/index.md index f5b141c2..6d45bb3a 100644 --- a/rulesets/tsl/index.md +++ b/rulesets/tsl/index.md @@ -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` 缺失或不可用时，停止猜测函数名、签名、参数和返回值。 +- 工具链、模块或项目事实缺失时，停止相关执行与集成判断，并明确报告缺失项。 diff --git a/scripts/build_tsl_playbook.py b/scripts/build_tsl_playbook.py index 78d78dd6..16bb8f4e 100644 --- a/scripts/build_tsl_playbook.py +++ b/scripts/build_tsl_playbook.py @@ -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: diff --git a/skills/README.md b/skills/README.md index 724ca4af..80822287 100644 --- a/skills/README.md +++ b/skills/README.md @@ -9,13 +9,14 @@ ## 一方 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-api-reference` | 查询随 skill 分发的 TSL API 参考：按名精确查条目，或按中文关键词发现候选 | 写/审 TSL 时确认 builtin、dotnet、模块 API 的签名、参数、返回值和示例 | +| 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 @@ -23,48 +24,48 @@ 这些 skill 来自 `superpowers`，主要提供计划、执行、调试、验证和审查工作流。 -| Skill | 作用 | -| --- | --- | -| `using-superpowers` | 会话开始时判断并加载适用 skill | -| `brainstorming` | 需求澄清、方案讨论、设计文档产出 | -| `writing-plans` | 把设计或需求拆成可执行 implementation plan | -| `executing-plans` | 按已写好的 plan 执行任务 | -| `subagent-driven-development` | 用子 agent 按任务执行、审查和迭代 plan | -| `dispatching-parallel-agents` | 多个互不依赖问题并行分派 | -| `using-git-worktrees` | 需要隔离工作区时创建或使用 git worktree | -| `finishing-a-development-branch` | 开发分支完成后的合并、PR、保留或丢弃流程 | -| `test-driven-development` | 新功能、bugfix、重构前的 TDD 流程 | -| `systematic-debugging` | bug、测试失败、异常行为的根因定位流程 | -| `verification-before-completion` | 声称完成、修复或通过前的验证门禁 | -| `requesting-code-review` | 主动请求代码审查，通常用于任务完成或合并前 | -| `receiving-code-review` | 处理别人给出的 review 意见，判断采纳、反驳或澄清 | -| `writing-skills` | 创建、修改或验证 skill 的写作规范 | +| Skill | 作用 | +| -------------------------------- | ------------------------------------------------ | +| `using-superpowers` | 会话开始时判断并加载适用 skill | +| `brainstorming` | 需求澄清、方案讨论、设计文档产出 | +| `writing-plans` | 把设计或需求拆成可执行 implementation plan | +| `executing-plans` | 按已写好的 plan 执行任务 | +| `subagent-driven-development` | 用子 agent 按任务执行、审查和迭代 plan | +| `dispatching-parallel-agents` | 多个互不依赖问题并行分派 | +| `using-git-worktrees` | 需要隔离工作区时创建或使用 git worktree | +| `finishing-a-development-branch` | 开发分支完成后的合并、PR、保留或丢弃流程 | +| `test-driven-development` | 新功能、bugfix、重构前的 TDD 流程 | +| `systematic-debugging` | bug、测试失败、异常行为的根因定位流程 | +| `verification-before-completion` | 声称完成、修复或通过前的验证门禁 | +| `requesting-code-review` | 主动请求代码审查，通常用于任务完成或合并前 | +| `receiving-code-review` | 处理别人给出的 review 意见，判断采纳、反驳或澄清 | +| `writing-skills` | 创建、修改或验证 skill 的写作规范 | ### brooks-lint Suite Code review 和质量审查工具集，包含共享参考资料目录 `_shared`。 -| Skill | 作用 | -| --- | --- | -| `brooks-review` | 常规 PR / diff code review | -| `brooks-audit` | architecture audit、系统性结构问题审查 | -| `brooks-debt` | technical debt review | -| `brooks-health` | 项目健康度检查 | -| `brooks-sweep` | 扫描式问题发现 | -| `brooks-test` | 测试质量审查 | +| Skill | 作用 | +| --------------- | -------------------------------------- | +| `brooks-review` | 常规 PR / diff code review | +| `brooks-audit` | architecture audit、系统性结构问题审查 | +| `brooks-debt` | technical debt review | +| `brooks-health` | 项目健康度检查 | +| `brooks-sweep` | 扫描式问题发现 | +| `brooks-test` | 测试质量审查 | ### 代码库侦察与迁移 -| Skill | 作用 | -| --- | --- | -| `codebase-recon` | 通过 git 历史和代码结构做 risk scan、热点分析、重构前侦察 | -| `pathfinding` | 需求澄清和 confidence calibration | -| `codebase-migrate` | 大代码库迁移、多文件 refactor、分批变更与 CI 验证工作流 | +| Skill | 作用 | +| ------------------ | --------------------------------------------------------- | +| `codebase-recon` | 通过 git 历史和代码结构做 risk scan、热点分析、重构前侦察 | +| `pathfinding` | 需求澄清和 confidence calibration | +| `codebase-migrate` | 大代码库迁移、多文件 refactor、分批变更与 CI 验证工作流 | ### 其他 -| Skill | 作用 | -| --- | --- | -| `ui-ux-pro-max` | UI/UX 设计知识库，包含风格、配色、字体、组件和栈相关建议 | +| Skill | 作用 | +| --------------------- | ------------------------------------------------------------- | +| `ui-ux-pro-max` | UI/UX 设计知识库，包含风格、配色、字体、组件和栈相关建议 | | `karpathy-guidelines` | 写代码、审查、重构时降低 LLM 常见错误：保持简单、聚焦、可验证 | -| `uncle-bob-craft` | Clean Architecture、SOLID、设计模式误用和代码工匠实践审查 | +| `uncle-bob-craft` | Clean Architecture、SOLID、设计模式误用和代码工匠实践审查 | diff --git a/skills/tsl-syntax-reference/SKILL.md b/skills/tsl-syntax-reference/SKILL.md new file mode 100644 index 00000000..3fd522f6 --- /dev/null +++ b/skills/tsl-syntax-reference/SKILL.md @@ -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 环境不得混用、默认任选或自行回退。 diff --git a/skills/tsl-syntax-reference/agents/openai.yaml b/skills/tsl-syntax-reference/agents/openai.yaml new file mode 100644 index 00000000..c54a28cd --- /dev/null +++ b/skills/tsl-syntax-reference/agents/openai.yaml @@ -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." diff --git a/docs/tsl/syntax/01_quickstart.md b/skills/tsl-syntax-reference/references/01_quickstart.md similarity index 98% rename from docs/tsl/syntax/01_quickstart.md rename to skills/tsl-syntax-reference/references/01_quickstart.md index 6605ed7b..0f253ec3 100644 --- a/docs/tsl/syntax/01_quickstart.md +++ b/skills/tsl-syntax-reference/references/01_quickstart.md @@ -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` 后缀时，智能体如何按后缀组织代码；以及生成代码前必须先核对哪些语言硬规则。 diff --git a/docs/tsl/syntax/02_core_model.md b/skills/tsl-syntax-reference/references/02_core_model.md similarity index 97% rename from docs/tsl/syntax/02_core_model.md rename to skills/tsl-syntax-reference/references/02_core_model.md index 5bbd180c..f15a7f93 100644 --- a/docs/tsl/syntax/02_core_model.md +++ b/skills/tsl-syntax-reference/references/02_core_model.md @@ -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` 可复用声明文件，如何识别脚本语句区和声明区，以及为什么很多错误其实是“文件模型选错了”。 diff --git a/docs/tsl/syntax/03_values_and_literals.md b/skills/tsl-syntax-reference/references/03_values_and_literals.md similarity index 98% rename from docs/tsl/syntax/03_values_and_literals.md rename to skills/tsl-syntax-reference/references/03_values_and_literals.md index 7a5de2e4..85405fac 100644 --- a/docs/tsl/syntax/03_values_and_literals.md +++ b/skills/tsl-syntax-reference/references/03_values_and_literals.md @@ -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)；如果问题已经超出语法层，停止并交接给对应事实所有者 这一篇整理基本类型、字面量、数组、字符串、字符串编码边界与基础值模型，避免把值规则分散在函数或金融示例里。 diff --git a/docs/tsl/syntax/04_variables_and_constants.md b/skills/tsl-syntax-reference/references/04_variables_and_constants.md similarity index 97% rename from docs/tsl/syntax/04_variables_and_constants.md rename to skills/tsl-syntax-reference/references/04_variables_and_constants.md index 421560ec..cf033182 100644 --- a/docs/tsl/syntax/04_variables_and_constants.md +++ b/skills/tsl-syntax-reference/references/04_variables_and_constants.md @@ -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)；如果问题已经超出语法层，停止并交接给对应事实所有者 这一篇收拢变量与常量初始化规则。 diff --git a/docs/tsl/syntax/05_functions_and_calls.md b/skills/tsl-syntax-reference/references/05_functions_and_calls.md similarity index 99% rename from docs/tsl/syntax/05_functions_and_calls.md rename to skills/tsl-syntax-reference/references/05_functions_and_calls.md index 9aafce85..2872c7d9 100644 --- a/docs/tsl/syntax/05_functions_and_calls.md +++ b/skills/tsl-syntax-reference/references/05_functions_and_calls.md @@ -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` 声明边界、外部系统交互和业务函数库只在本页保留路由或最小边界。 diff --git a/docs/tsl/syntax/06_expressions_and_operators.md b/skills/tsl-syntax-reference/references/06_expressions_and_operators.md similarity index 99% rename from docs/tsl/syntax/06_expressions_and_operators.md rename to skills/tsl-syntax-reference/references/06_expressions_and_operators.md index d6a61635..14b42ef9 100644 --- a/docs/tsl/syntax/06_expressions_and_operators.md +++ b/skills/tsl-syntax-reference/references/06_expressions_and_operators.md @@ -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。 diff --git a/docs/tsl/syntax/07_control_flow.md b/skills/tsl-syntax-reference/references/07_control_flow.md similarity index 98% rename from docs/tsl/syntax/07_control_flow.md rename to skills/tsl-syntax-reference/references/07_control_flow.md index 62dd0d56..87cd29eb 100644 --- a/docs/tsl/syntax/07_control_flow.md +++ b/skills/tsl-syntax-reference/references/07_control_flow.md @@ -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)；如果问题已经超出语法层，停止并交接给对应事实所有者 这一篇只收录流程控制与异常控制，不讨论金融语义。 diff --git a/docs/tsl/syntax/08_objects_and_classes.md b/skills/tsl-syntax-reference/references/08_objects_and_classes.md similarity index 99% rename from docs/tsl/syntax/08_objects_and_classes.md rename to skills/tsl-syntax-reference/references/08_objects_and_classes.md index a3e8d1fb..0bfbfb5e 100644 --- a/docs/tsl/syntax/08_objects_and_classes.md +++ b/skills/tsl-syntax-reference/references/08_objects_and_classes.md @@ -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)；如果问题已经超出语法层，停止并交接给对应事实所有者 这一篇收拢面向对象语法，只保留语言层规则。 diff --git a/docs/tsl/syntax/09_units_and_scope.md b/skills/tsl-syntax-reference/references/09_units_and_scope.md similarity index 98% rename from docs/tsl/syntax/09_units_and_scope.md rename to skills/tsl-syntax-reference/references/09_units_and_scope.md index 5426f4ea..7e161fe5 100644 --- a/docs/tsl/syntax/09_units_and_scope.md +++ b/skills/tsl-syntax-reference/references/09_units_and_scope.md @@ -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)。 diff --git a/docs/tsl/syntax/10_runtime_context_and_with.md b/skills/tsl-syntax-reference/references/10_runtime_context_and_with.md similarity index 98% rename from docs/tsl/syntax/10_runtime_context_and_with.md rename to skills/tsl-syntax-reference/references/10_runtime_context_and_with.md index ab51c140..f7ffaa0b 100644 --- a/docs/tsl/syntax/10_runtime_context_and_with.md +++ b/skills/tsl-syntax-reference/references/10_runtime_context_and_with.md @@ -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(...)` 和全局缓存，不处理任何金融业务语义。 diff --git a/docs/tsl/syntax/11_pitfalls.md b/skills/tsl-syntax-reference/references/11_pitfalls.md similarity index 97% rename from docs/tsl/syntax/11_pitfalls.md rename to skills/tsl-syntax-reference/references/11_pitfalls.md index 699b3d92..1c7ee1a9 100644 --- a/docs/tsl/syntax/11_pitfalls.md +++ b/skills/tsl-syntax-reference/references/11_pitfalls.md @@ -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)；如果问题已经超出语法层，停止并交接给对应事实所有者 这一篇不讲新知识，只做反例索引。 diff --git a/docs/tsl/syntax/12_matrix_and_collections.md b/skills/tsl-syntax-reference/references/12_matrix_and_collections.md similarity index 98% rename from docs/tsl/syntax/12_matrix_and_collections.md rename to skills/tsl-syntax-reference/references/12_matrix_and_collections.md index 7e6fd4e9..9609b2c4 100644 --- a/docs/tsl/syntax/12_matrix_and_collections.md +++ b/skills/tsl-syntax-reference/references/12_matrix_and_collections.md @@ -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` 这类去重型集合关系。 diff --git a/docs/tsl/syntax/13_resultset_and_filters.md b/skills/tsl-syntax-reference/references/13_resultset_and_filters.md similarity index 97% rename from docs/tsl/syntax/13_resultset_and_filters.md rename to skills/tsl-syntax-reference/references/13_resultset_and_filters.md index 0dc3bd1f..f4308bf7 100644 --- a/docs/tsl/syntax/13_resultset_and_filters.md +++ b/skills/tsl-syntax-reference/references/13_resultset_and_filters.md @@ -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 查询语法，也不把去重型集合运算和业务选股逻辑混进来。 diff --git a/docs/tsl/syntax/14_ts_sql.md b/skills/tsl-syntax-reference/references/14_ts_sql.md similarity index 98% rename from docs/tsl/syntax/14_ts_sql.md rename to skills/tsl-syntax-reference/references/14_ts_sql.md index 30f7698b..f4c69f97 100644 --- a/docs/tsl/syntax/14_ts_sql.md +++ b/skills/tsl-syntax-reference/references/14_ts_sql.md @@ -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 模块事实所有者或项目实际接口。 ## 默认生成模板 diff --git a/docs/tsl/syntax/15_debug_and_profiler.md b/skills/tsl-syntax-reference/references/15_debug_and_profiler.md similarity index 97% rename from docs/tsl/syntax/15_debug_and_profiler.md rename to skills/tsl-syntax-reference/references/15_debug_and_profiler.md index d5f1863f..db34ed46 100644 --- a/docs/tsl/syntax/15_debug_and_profiler.md +++ b/skills/tsl-syntax-reference/references/15_debug_and_profiler.md @@ -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)；如果问题已经超出语法层，停止并交接给对应事实所有者 这一篇收拢本页明确的调试、计时、性能分析器和调用栈相关入口。 diff --git a/docs/tsl/syntax/16_lexical_structure_and_compile_options.md b/skills/tsl-syntax-reference/references/16_lexical_structure_and_compile_options.md similarity index 98% rename from docs/tsl/syntax/16_lexical_structure_and_compile_options.md rename to skills/tsl-syntax-reference/references/16_lexical_structure_and_compile_options.md index cfe1f044..70e6862a 100644 --- a/docs/tsl/syntax/16_lexical_structure_and_compile_options.md +++ b/skills/tsl-syntax-reference/references/16_lexical_structure_and_compile_options.md @@ -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)；如果问题已经超出语法层，停止并交接给对应事实所有者 这一篇吸收语法手册里“词法层”和“编译期开关”相关内容：标识符、注释、条件编译和依赖编译选项。 diff --git a/docs/tsl/syntax/17_types_and_conversions.md b/skills/tsl-syntax-reference/references/17_types_and_conversions.md similarity index 98% rename from docs/tsl/syntax/17_types_and_conversions.md rename to skills/tsl-syntax-reference/references/17_types_and_conversions.md index fedd8d96..75506482 100644 --- a/docs/tsl/syntax/17_types_and_conversions.md +++ b/skills/tsl-syntax-reference/references/17_types_and_conversions.md @@ -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)；如果问题已经超出语法层，停止并交接给对应事实所有者 这一篇吸收语言基础里“数据类型、初始值、弱类型行为、类型转换、复数类型”这一层。 diff --git a/docs/tsl/syntax/18_external_calls_and_threads.md b/skills/tsl-syntax-reference/references/18_external_calls_and_threads.md similarity index 97% rename from docs/tsl/syntax/18_external_calls_and_threads.md rename to skills/tsl-syntax-reference/references/18_external_calls_and_threads.md index 2886955f..377f3712 100644 --- a/docs/tsl/syntax/18_external_calls_and_threads.md +++ b/skills/tsl-syntax-reference/references/18_external_calls_and_threads.md @@ -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 回调和线程调用。 diff --git a/docs/tsl/syntax/19_namespace_libpath_and_unit_runtime.md b/skills/tsl-syntax-reference/references/19_namespace_libpath_and_unit_runtime.md similarity index 98% rename from docs/tsl/syntax/19_namespace_libpath_and_unit_runtime.md rename to skills/tsl-syntax-reference/references/19_namespace_libpath_and_unit_runtime.md index be313015..f138fd41 100644 --- a/docs/tsl/syntax/19_namespace_libpath_and_unit_runtime.md +++ b/skills/tsl-syntax-reference/references/19_namespace_libpath_and_unit_runtime.md @@ -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)。 diff --git a/docs/tsl/syntax/20_object_runtime_and_introspection.md b/skills/tsl-syntax-reference/references/20_object_runtime_and_introspection.md similarity index 98% rename from docs/tsl/syntax/20_object_runtime_and_introspection.md rename to skills/tsl-syntax-reference/references/20_object_runtime_and_introspection.md index 72d3d7b5..90b5f71c 100644 --- a/docs/tsl/syntax/20_object_runtime_and_introspection.md +++ b/skills/tsl-syntax-reference/references/20_object_runtime_and_introspection.md @@ -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) 为主线；本页只在用户明确需要运行时反射、内省、对象生命周期或弱引用能力时进入。 diff --git a/docs/tsl/syntax/21_builtin_runtime_objects.md b/skills/tsl-syntax-reference/references/21_builtin_runtime_objects.md similarity index 97% rename from docs/tsl/syntax/21_builtin_runtime_objects.md rename to skills/tsl-syntax-reference/references/21_builtin_runtime_objects.md index dd042fbf..5d08ae06 100644 --- a/docs/tsl/syntax/21_builtin_runtime_objects.md +++ b/skills/tsl-syntax-reference/references/21_builtin_runtime_objects.md @@ -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。 diff --git a/docs/tsl/syntax/22_matrix_deep_dive.md b/skills/tsl-syntax-reference/references/22_matrix_deep_dive.md similarity index 99% rename from docs/tsl/syntax/22_matrix_deep_dive.md rename to skills/tsl-syntax-reference/references/22_matrix_deep_dive.md index 0915eaa1..fd2a8186 100644 --- a/docs/tsl/syntax/22_matrix_deep_dive.md +++ b/skills/tsl-syntax-reference/references/22_matrix_deep_dive.md @@ -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)`。 代码块身份：反例 / 不可照写 diff --git a/docs/tsl/syntax/23_fmarray.md b/skills/tsl-syntax-reference/references/23_fmarray.md similarity index 98% rename from docs/tsl/syntax/23_fmarray.md rename to skills/tsl-syntax-reference/references/23_fmarray.md index fd3cdfa7..56d6d7c7 100644 --- a/docs/tsl/syntax/23_fmarray.md +++ b/skills/tsl-syntax-reference/references/23_fmarray.md @@ -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` 语法边界。 diff --git a/docs/tsl/syntax/24_object_overloads_and_iteration.md b/skills/tsl-syntax-reference/references/24_object_overloads_and_iteration.md similarity index 98% rename from docs/tsl/syntax/24_object_overloads_and_iteration.md rename to skills/tsl-syntax-reference/references/24_object_overloads_and_iteration.md index 7aa93f2c..74108e0f 100644 --- a/docs/tsl/syntax/24_object_overloads_and_iteration.md +++ b/skills/tsl-syntax-reference/references/24_object_overloads_and_iteration.md @@ -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` 这类矩阵关键字重载。 diff --git a/skills/tsl-syntax-reference/references/index.md b/skills/tsl-syntax-reference/references/index.md new file mode 100644 index 00000000..12e883f7 --- /dev/null +++ b/skills/tsl-syntax-reference/references/index.md @@ -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、命名、风格、工具链、模块集成和项目运行事实不属于本路由。命中这些任务时停止语法检索，只说明应交给对应事实所有者，不复制或猜测外部领域内容。 diff --git a/test/cli/test_install_skills.py b/test/cli/test_install_skills.py index e872c1d8..1e883684 100644 --- a/test/cli/test_install_skills.py +++ b/test/cli/test_install_skills.py @@ -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" diff --git a/test/cli/test_playbook_cli.py b/test/cli/test_playbook_cli.py index e20d6126..ce9e7f36 100644 --- a/test/cli/test_playbook_cli.py +++ b/test/cli/test_playbook_cli.py @@ -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: diff --git a/test/skill/tsl_syntax_evals.md b/test/skill/tsl_syntax_evals.md new file mode 100644 index 00000000..79e5ec9d --- /dev/null +++ b/test/skill/tsl_syntax_evals.md @@ -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`：会话看到其他场景输出、运行反馈、评分材料或隔离配置之外的事实源。 + +评测还应记录失败分类：触发失败、错误路由、未读主专题、文件模型错误、语法应用错误、越界编造和隔离污染。 diff --git a/test/test_deployment_routes_e2e.py b/test/test_deployment_routes_e2e.py index efd19be2..4b610af9 100644 --- a/test/test_deployment_routes_e2e.py +++ b/test/test_deployment_routes_e2e.py @@ -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): diff --git a/test/test_tsl_syntax_reference_skill.py b/test/test_tsl_syntax_reference_skill.py new file mode 100644 index 00000000..90df20eb --- /dev/null +++ b/test/test_tsl_syntax_reference_skill.py @@ -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 = "![local diagram](images/router.png)\n![remote](https://example.com/router.png)" + 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()