✨ 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
@@ -1,6 +1,6 @@
 # TSL unit 与作用域

-这一篇只讲“怎么写和怎么调用 `unit`”。`namespace`、查找路径、`unit` 生命周期、`tsl.conf` 与运行时入口统一放到 [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)。
+这一篇只讲“怎么写和怎么调用 `unit`”。`namespace`、查找路径、`unit` 生命周期、`tsl.conf` 与运行时入口统一放到 [18_namespace_libpath_and_unit_runtime.md](18_namespace_libpath_and_unit_runtime.md)。

 ## 本篇职责

@@ -12,15 +12,6 @@
 - 多个 `unit` 里有同名接口时，未限定调用到底命中谁
 - 怎样显式指定要调用哪个 `unit` 的接口

-## 智能体 unit/作用域判断流程
-
-1. 先判断当前交付是 `.tsl` 可执行脚本、`.tsf` 扩展模块，还是 `unit` 文件。
-2. `unit` 文件只描述可复用单元；脚本入口仍放在 `.tsl`。
-3. `uses` 必须放在普通语句之前；普通语句后不要再追加顶层 `uses`。
-4. 默认参数、接口段、实现段和作用域边界只照本页文档明确形态写。
-5. `unit` 生命周期、命名空间、查找路径、`tsl.conf` 和命令行查找路径参数的事实见 [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)。
-6. 没有对应代码块时不要发明 unit/作用域写法。
-
 ## 核心规则

 - `unit` 是完整的顶层主体；常见完整形态是 `unit Name; interface ... implementation ... end.`。
@@ -38,12 +29,14 @@
 - 只写在 `implementation` 里的函数，对 `unit` 外部不可见。
 - 出现重名接口时，未限定调用按 `uses` 从后往前解析；最后一个 `uses` 的同名接口优先。
 - 要显式指定某个 `unit` 的接口，可以用 `UnitA.Ping()`、`unit(UnitA).Ping()` 或 `call("UnitA.Ping")`。
- `unit` 生命周期、接口状态、命名空间和查找路径细节见 [19_namespace_libpath_and_unit_runtime.md](19_namespace_libpath_and_unit_runtime.md)。
+- `unit` 生命周期、接口状态、命名空间和查找路径细节见 [18_namespace_libpath_and_unit_runtime.md](18_namespace_libpath_and_unit_runtime.md)。

 ## 示例与行为

 ### 最小 `unit`

+<!-- tags: 怎么写 unit, 模块怎么定义, unit 骨架, 接口段实现段 -->
+
 代码块身份：可直接照写示例

 ```tsl
@@ -78,6 +71,8 @@ end.

 ### 简写 `unit`

+<!-- tags: 省略 interface, 最简 unit, 不写接口段 -->
+
 代码块身份：可直接照写示例

 ```tsl
@@ -109,6 +104,8 @@ end.

 ### 顶层、函数体、类体里的 `uses`

+<!-- tags: 怎么引入别的文件, 导入模块, uses 写在哪, 引用其他 unit -->
+
 沿用同一个 `DemoUnit.tsf`，分别看顶层、函数体、类体三种 `uses` 位置：

 代码块身份：配置片段 / 概念骨架
@@ -162,6 +159,8 @@ end;

 ### `uses` 的位置限制

+<!-- tags: uses 放错地方, 为什么导入失败, 引入语句必须第一行 -->
+
 代码块身份：反例 / 不可照写

 ```text
@@ -209,6 +208,8 @@ end;

 ### `interface` 段 `uses` 和 `implementation` 段 `uses`

+<!-- tags: 接口段导入, 实现段导入, 导入放哪一段 -->
+
 代码块身份：配置片段 / 概念骨架
 代码块说明：多文件结构骨架；依赖 `unit` 查找路径，不是可直接复制的单文件最小示例。

@@ -288,6 +289,8 @@ writeLn(obj.FromImplementation());

 ### 接口声明与实现段分离

+<!-- tags: 声明和实现分开, 对外暴露哪些, 接口里写什么 -->
+
 代码块身份：可直接照写示例

 ```tsl
@@ -329,6 +332,8 @@ end.

 ### 实现段私有函数

+<!-- tags: 内部函数, 不对外暴露, 私有函数怎么写 -->
+
 代码块身份：配置片段 / 概念骨架
 代码块说明：多文件结构骨架；依赖 `unit` 查找路径，不是可直接复制的单文件最小示例。

@@ -375,6 +380,8 @@ writeLn(PrivateFunc());

 ### 重名解析与限定调用

+<!-- tags: 两个模块同名函数, 冲突了怎么调, 限定名调用, 指定哪个 unit -->
+
 重名函数最小对照：

 代码块身份：配置片段 / 概念骨架