✨ feat(tsl-syntax-reference): harden retrieval and restructure pages

- flag weak candidates (no intent/heading/identifier/tag hit) and exit 2 when every candidate is weak: mis-hits used to be indistinguishable from real hits, so the retry-with-better-terms loop never fired - accept multiple ids per --section for batch fetch, failing atomically on any unknown id so a partial fetch cannot pass as complete - move query synonyms and page intent aliases to data/lexicon.json and enforce alias/page correspondence in --check; curation data no longer lives in the engine - document the weak-hit rule, batch fetch and prelude-once guidance in SKILL.md, with curation discipline in data/README.md - drop 11_pitfalls.md, renumber the trailing pages and spread retrieval tags across topics; lexicon keys are page filenames, so the renumbering and the new --check rule cannot land in separate commits
2026-07-29 15:45:47 +08:00
parent 37a3bf4b0c
commit 40a9885eb4
28 changed files with 1048 additions and 773 deletions
@@ -6,14 +6,6 @@

 回答“`if`、`case`、`for`、`while`、`repeat`、`break`、`continue`、`try`、`raise` 这些流程结构在 TSL 里到底怎么写，哪些写法可以直接生成”。

-## 智能体控制流判断流程
-
-1. 先判断任务需要条件分支、循环、`case`、异常处理还是调试跳转。
-2. `if` / `for` / `while` / `repeat` 优先照本页文档骨架写，不要套用其他 Pascal 方言。
-3. 生成带 `else` 的条件分支时，默认用 `begin ... end` 包住 `then` 和 `else` 分支，让分支内部语句正常以分号结尾；不要在 `else` 前提前加分号。
-4. `case` 可写成语句形态，也可写成赋值右侧的表达式形态；表达式形态的分支只能放单条表达式/单条语句，不写 `begin ... end` 语句段。
-5. 没有文档事实时不要发明控制流写法。
-
 ## 核心规则

 - `if ... then ... else ...` 默认写成块式分支：`then begin ... end else begin ... end`。
@@ -30,7 +22,7 @@
 - `exceptObject.errLine` 和 `exceptObject.errNo` 在 `except` 块中也可读。
 - `try ... finally ... end` 无论是否报错，都会先执行 `finally`；如果没有 `except` 吞掉错误，脚本仍会在 `finally` 之后报错终止。
 - `raise "message"` 是最小抛错写法。
- `goto`、`debugReturn`、`debugRunEnv`、计时和性能分析器这类“控制流补充工具”统一放到 [15_debug_and_profiler.md](15_debug_and_profiler.md)。
+- `goto`、`debugReturn`、`debugRunEnv`、计时和性能分析器这类“控制流补充工具”统一放到 [14_debug_and_profiler.md](14_debug_and_profiler.md)。

 ## 可直接照写示例

@@ -38,10 +30,12 @@

 - 条件表达式、比较、布尔值和普通赋值的事实见 [06_expressions_and_operators.md](06_expressions_and_operators.md)。
 - 函数里的控制流只按控制流语法处理；函数文件模型、返回值和参数规则见 [05_functions_and_calls.md](05_functions_and_calls.md)。
- `goto`、`debugReturn`、计时和性能分析器不在本页生成，相关事实见 [15_debug_and_profiler.md](15_debug_and_profiler.md)。
+- `goto`、`debugReturn`、计时和性能分析器不在本页生成，相关事实见 [14_debug_and_profiler.md](14_debug_and_profiler.md)。

 ### `if`、`while`、`repeat ... until`

+<!-- tags: 条件判断, 循环, 判断语句, 直到满足, 反复执行 -->
+
 代码块身份：可直接照写示例

 ```tsl
@@ -75,6 +69,8 @@ writeLn(counter);

 ### `for` 的几种主干写法

+<!-- tags: 循环写法, 遍历数组, 计数循环, 倒着循环, 遍历键值 -->
+
 最基础的递增循环：

 代码块身份：可直接照写示例
@@ -159,6 +155,8 @@ for i, value in numbers do

 ### `break` 与 `continue`

+<!-- tags: 跳出循环, 提前退出循环, 跳过本次, 结束循环 -->
+
 `break`：

 代码块身份：可直接照写示例
@@ -218,6 +216,8 @@ writeLn(sum);

 ### `case` 语句形态

+<!-- tags: 多分支, 分支判断, switch 怎么写, 多条件选择 -->
+
 普通分支：

 代码块身份：可直接照写示例
@@ -305,6 +305,8 @@ mid

 ### `try ... except`

+<!-- tags: 捕获异常, 出错处理, 抓错误, 异常不中断 -->
+
 代码块身份：可直接照写示例

 ```tsl
@@ -362,6 +364,8 @@ end

 ### `try ... finally`

+<!-- tags: 收尾处理, 无论如何都执行, 释放资源, 清理动作 -->
+
 正常路径：

 代码块身份：可直接照写示例
@@ -421,6 +425,8 @@ finally

 ### `raise`

+<!-- tags: 抛异常, 主动报错, 中断执行, 扔错误 -->
+
 代码块身份：可直接照写示例

 ```tsl