📝 docs(tsl): restructure agent-facing reference

Rework TSL syntax, catalog, modules, and routing docs around deterministic agent lookup and generation.

Split large catalog pages into focused function fact pages, remove obsolete pending/verified/unavailable paths, and update consistency tests for the new structure.
This commit is contained in:
csh
2026-06-09 17:24:30 +08:00
parent 9c194170a1
commit 540b3c0a1b
192 changed files with 32929 additions and 13533 deletions
+16 -16
View File
@@ -1,20 +1,20 @@
# TSL 代码风格Code Style
# TSL 代码风格
文档类型:规范
文档类型:风格偏好
是否可直接用于生成代码:仅部分
是否含已验证可执行示例:否
是否含已验证反例:否
遇到不确定时跳转到[naming.md](naming.md)、[syntax/index.md](syntax/index.md)、[toolchain.md](toolchain.md)
是否含可直接照写示例:否
是否含不可照写反例:否
遇到不确定时:[naming.md](naming.md)、[syntax/index.md](syntax/index.md)、[toolchain.md](toolchain.md)
章节规定 TSL 代码的结构与格式约定
页记录本仓库代码风格偏好,不代表 TSL 语法事实
以下出现的 `<TOKEN>``<...>`、模板占位和单独标成 `反例 / 不可照写` 的块,只用于说明风格或反例,不等于可直接复制的源码字面量。
本页里的 `反例 / 不可照写` 仅表示风格上的不推荐写法,不等于语法主线里“已验证会编译失败/运行失败”的反向边界;因此页头里的 `是否含已验证反例` 仍保持为 `否`
本页里的 `反例 / 不可照写` 仅表示风格上的不推荐写法,不等于语法主线里“会编译失败/运行失败”的反向边界;因此页头里的 `是否含不可照写反例` 仍保持为 `否`
相关文档:
- 命名规范`docs/tsl/naming.md`
- 命名偏好`docs/tsl/naming.md`
- 工具链与验证命令(模板):`docs/tsl/toolchain.md`
## 1. 文件与组织
@@ -81,11 +81,11 @@
```tsl
if cond then
begin
DoSomething()
DoSomething();
end
else
begin
DoOther()
DoOther();
end
```
@@ -173,7 +173,7 @@ if !ok then return err;
不推荐这样写:
代码块身份:反例 / 不可照写
代码块说明:风格反例,不是已验证语法反例。
代码块说明:风格反例,不是语法主线反例。
```tsl
count := count + 1; // obvious
@@ -265,7 +265,7 @@ function Func(a: string; b: ClassName): void;
不推荐这样写:
代码块身份:反例 / 不可照写
代码块说明:风格反例,不是已验证语法反例。
代码块说明:风格反例,不是语法主线反例。
```tsl
function ExportReport(
@@ -324,11 +324,11 @@ function ExportReport(path: string; rows: array; options: ExportOptions): void;
function ReadOptionalCache(path: string);
begin
try
return LoadCacheValue(path)
return LoadCacheValue(path);
except
// best-effort: cache 仅用于提速,失败不应影响主流程
RecordCacheWarning(path)
return nil
RecordCacheWarning(path);
return nil;
end
end;
```
@@ -351,6 +351,6 @@ function ParseConfig(text: string): array;
function LoadConfig(path: string): array;
begin
text := LoadConfigText(path);
return ParseConfig(text)
return ParseConfig(text);
end;
```