feat(tsl-syntax-reference): harden retrieval contracts

Add stable section IDs, structural and routing regressions, quickstart consistency checks, and CI enforcement.

BREAKING CHANGE: replace heading-derived Section IDs with explicit syntax-NN-NNN identifiers.
This commit is contained in:
csh
2026-07-31 10:05:15 +08:00
parent 21e688a436
commit 736d1a8ad7
30 changed files with 1635 additions and 137 deletions
@@ -4,10 +4,14 @@
## 本篇职责
<!-- section-id: syntax-14-001 -->
回答“`goto``debugReturn``debugRunEnv``mtic` / `mtoc``setProfiler``__line__``__stack_frame` 怎样写、会怎样表现”。
## 核心规则
<!-- section-id: syntax-14-002 -->
本页示例只说明调试与分析结构中的调用位置和源码外形。相关 API 的精确签名、参数、返回行为、平台 scope、目标环境或解释器可用性必须使用 `tsl-api-reference` skill 重新核对,不能由本页示例反推。
- `goto label_name;` 属于文档明确写法,但目标位置以 `label label_name; statement` 这种内联形式作为默认生成形态。
@@ -23,8 +27,12 @@
## 可直接照写示例
<!-- section-id: syntax-14-003 -->
### `goto`
<!-- section-id: syntax-14-004 -->
<!-- tags: 跳转, 跳出多重循环, 标签跳转 -->
代码块身份:可直接照写示例
@@ -91,6 +99,8 @@ writeLn("after");
### `debugReturn`
<!-- section-id: syntax-14-005 -->
<!-- tags: 中途看返回值, 调试返回, 提前打断 -->
代码块身份:可直接照写示例
@@ -114,6 +124,8 @@ end;
### `debugRunEnv` 与 `debugRunEnvDo`
<!-- section-id: syntax-14-006 -->
<!-- tags: 调试环境, 运行环境切换, 调试开关 -->
`debugRunEnv(0)` / `debugRunEnv(1)`
@@ -156,6 +168,8 @@ end;
### `mtic` 与 `mtoc`
<!-- section-id: syntax-14-007 -->
<!-- tags: 计时, 测耗时, 跑了多久, 秒表, 执行时间 -->
代码块身份:可直接照写示例
@@ -181,6 +195,8 @@ writeLn(elapsed2 >= 0);
### `setProfiler` 与 `getProfilerInfo`
<!-- section-id: syntax-14-008 -->
<!-- tags: 性能分析, 找瓶颈, profiler, 哪段最慢 -->
代码块身份:可直接照写示例
@@ -203,6 +219,8 @@ writeLn(length(info) > 0);
### `__line__` 与 `__stack_frame`
<!-- section-id: syntax-14-009 -->
<!-- tags: 当前行号, 调用栈, 堆栈信息, 报错在哪一行 -->
`__line__`
@@ -252,6 +270,8 @@ array(
## 禁止项
<!-- section-id: syntax-14-010 -->
- 不要把 `debugReturn` 当成普通函数 `return` 使用。
- 不要假设 `goto` 可以跨函数、跨脚本体或跳到单独成行的 `label`
- 不要给计时或性能分析器调用补未写入文档参数。