From 5b97ed53229a56b0234ce66e8112edc67b64bcc6 Mon Sep 17 00:00:00 2001 From: csh Date: Mon, 22 Dec 2025 12:14:11 +0800 Subject: [PATCH] :memo: docs(tsl): clarify syntax references --- .agents/tsl/index.md | 2 ++ AGENTS.md | 6 ++++++ README.md | 1 + docs/index.md | 1 + docs/tsl/syntax_book/index.md | 22 ++++++++++++++++++++++ 5 files changed, 32 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/tsl/syntax_book/index.md diff --git a/.agents/tsl/index.md b/.agents/tsl/index.md index ba3cae3..4283a08 100644 --- a/.agents/tsl/index.md +++ b/.agents/tsl/index.md @@ -26,6 +26,8 @@ ## TSL/TSF 必要约定（必须遵守） - `.tsl` 与 `.tsf` 都是 Tinysoft Language 源文件；修改它们时统一按 TSL 规范处理（不要把 `.tsf` 当成“另一种语言/无风格约束的脚本”）。 +- 语法权威来源：以 `docs/tsl/syntax_book/index.md` 为准；如与其他说明冲突，以语法手册为准。 +- 为避免上下文膨胀：不要整份加载 `docs/tsl/syntax_book/function.md`，只按需检索与引用相关片段。 - 文件级约束：一个文件只能有一个顶层声明，且文件基名必须与该顶层声明同名（推荐 `PascalCase`）；`.tsl` 顶层声明只能是 `function`。 - 格式：空格缩进（默认 4 空格），关键字用小写，复杂分支/多语句分支用 `begin/end` 块表达结构。 - 命名：类型/顶层函数/property 用 `PascalCase`；局部变量/参数用 `snake_case`；私有成员变量用 `snake_case_`。 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..feb1a42 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,6 @@ +# Agent Instructions (playbook) + +请以 `.agents/` 下的规则为准： + +- 入口：`.agents/index.md` +- 语言规则：`.agents/tsl/index.md`、`.agents/cpp/index.md`、`.agents/python/index.md` diff --git a/README.md b/README.md index e5d9e33..c2f59c9 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,7 @@ Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合 - `docs/common/commit_message.md`：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。 - `docs/tsl/code_style.md`：TSL 代码结构、格式、`begin/end` 代码块、注释与通用最佳实践。 - `docs/tsl/naming.md`：TSL 命名规范（顶层声明、文件同名规则、变量/成员/property、常量、集合命名等）。 +- `docs/tsl/syntax_book/index.md`：TSL 语法手册（整理自原始语法/机制目录册；`function.md` 建议按需检索）。 - `docs/tsl/toolchain.md`：TSL 工具链与验证命令模板。 - `docs/cpp/code_style.md`：C++ 代码风格（C++23/Modules）。 - `docs/cpp/naming.md`：C++ 命名规范（Google 基线）。 diff --git a/docs/index.md b/docs/index.md index 5960860..be6783a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,6 +11,7 @@ - TSL 源文件后缀同时包含：`.tsl`（脚本）与 `.tsf`（模块/库代码）。 - 代码风格：`tsl/code_style.md` - 命名规范：`tsl/naming.md` +- 语法手册（TSL语法；`function.md` 建议按需检索）：`tsl/syntax_book/index.md` - 工具链与验证命令（模板）：`tsl/toolchain.md` ## C++（cpp） diff --git a/docs/tsl/syntax_book/index.md b/docs/tsl/syntax_book/index.md new file mode 100644 index 0000000..35a9bf7 --- /dev/null +++ b/docs/tsl/syntax_book/index.md @@ -0,0 +1,22 @@ +# TSL 语法手册 + +本手册由原始语法/机制内容整理而来，已拆分为独立章节，阅读不再依赖外部跳转。 + +定位与边界： + +- 本手册关注：语法结构、关键字、语言机制（函数/控制流/unit/class/异常/矩阵/TS-SQL/集合等）。 +- 本手册不覆盖：数学/统计教程等教学内容；函数库的详细 API 说明集中在 `function.md`。 +- 代码风格与命名属于工程规范：见 `docs/tsl/code_style.md`、`docs/tsl/naming.md`。 +- 为避免上下文膨胀，`function.md` 建议按需检索与引用相关片段。 + +## 目录 + +- [01 语言基础](01_language_basics.md) +- [02 控制流与异常](02_control_flow.md) +- [03 函数](03_functions.md) +- [04 单元/命名空间/函数文件](04_modules_and_namespace.md) +- [05 对象模型（class/unit）](05_object_model.md) +- [06 扩展语法（矩阵/集合/结果集过滤/TS-SQL）](06_extended_syntax.md) +- [07 运行时与性能工具](07_debug_and_profiler.md) +- [08 高级语言（新一代）](08_new_generation.md) +- [TSL 函数大全）](function.md)