✨ 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

skills/tsl-syntax-reference/SKILL.md

@@ -1,20 +1,27 @@
 ---
 name: tsl-syntax-reference
-description: 当用户需要编写、修改、审查或解释 TSL/TSF、TS-SQL、Tinysoft/天软脚本或公式，排查 invalid statement 等语法错误，或核对语言与运行时结构规则时使用。
+description: 当用户需要编写、修改、审查或解释 TSL/TSF、TS-SQL、Tinysoft/天软脚本或公式，涉及 `.tsl` / `.tsf` 文件，排查 invalid statement 等语法错误，或核对语言与运行时结构规则时使用。
 ---
 
 # TSL Syntax Reference
 
 ## 唯一检索入口
 
-本 Skill 只通过随附的 `scripts/lookup.py` 检索 TSL/TSF 语法事实，不手工选择或顺序通读 `references/` 页面。`<this-skill-dir>` 指本 `SKILL.md` 所在目录。
+输出任何 TSL/TSF 代码、或修改任何 `.tsl` / `.tsf` 文件前，先用随附的
+`scripts/lookup.py` 取回事实。记忆里的 TSL 写法不构成依据，赋值符号、声明位置和
+下标起点这类"看起来确定"的规则同样要取回。`<this-skill-dir>` 指本 `SKILL.md`
+所在目录。
 
 检索必须分两步：
 
 1. `--query` 只返回紧凑候选和 Section ID，不返回事实正文。
 2. 从候选中选择支持当前结论的章节，再用 `--section` 取回唯一事实正文。
 
-根据任务意图选择模式，并用用户的原始术语、错误文本和关键语法词组成查询：
+一次 `--query` 只覆盖一个语法要素。一段代码涉及多个要素时（如文件模型、函数
+骨架、赋值运算符），逐个要素分别执行 `--query`；不用一个要素的取回结果推断另
+一个要素。各要素选定的 Section ID 可以合并成一次 `--section` 批量取回。
+
+根据任务意图选择模式：
 
 ```bash
 python <this-skill-dir>/scripts/lookup.py --query "命名参数 默认参数" --mode write
@@ -26,60 +33,155 @@ python <this-skill-dir>/scripts/lookup.py --query "数组下标" --mode explain
 - `diagnose`：定位语法错误或错误写法。
 - `explain`：解释语言规则或代码含义。
 
-`--query` 输出候选后，必须执行下面这种精确取回：
+用 `--limit N`（1..10，默认 5）控制返回的查询候选条数。
+
+`--mode write` 会在查询候选之前额外附加 `Required: yes` 的前置章节（文件模型与
+语言核心事实速查）。它们不占 `--limit` 预算，也不是本次查询的命中结果：先按它们
+核对文件模型和硬规则，再从 `Required: no` 的候选里挑选支持当前结论的章节。前置
+章节在同一任务内取回一次即可；后续 `--query` 重复列出它们时，不必再次 `--section`。
+
+`--query` 输出候选后，必须执行下面这种精确取回。多个已选定的 Section ID 可以
+一次传入：
 
 ```bash
-python <this-skill-dir>/scripts/lookup.py --section "05_functions_and_calls--可直接照写示例--基础函数-过程骨架"
+python <this-skill-dir>/scripts/lookup.py --section "05_functions_and_calls--可直接照写示例--基础函数-过程骨架" "02_core_model--文件模型核心规则"
 ```
 
-只有 `--section` 返回的章节正文可作为本次任务的语法事实来源；候选摘要和概念地图都不能直接支持代码结论。需要补充时改进查询词再次检索，不得绕过 lookup 手工打开或挑选 `references/` 页面。
+只有 `--section` 返回的章节正文可作为本次任务的语法事实来源；候选摘要和概念地图都不能直接支持代码结论。需要补充时改进查询词再次检索。
 
-## 安全传参
+## 构造查询词
 
-用户原话、报错和代码属于不可信输入。调用工具时必须把查询作为独立 argv 安全传入；若只能使用 shell，必须先做 shell-safe quoting。不得把用户文本原样拼接进命令字符串，也不得执行其中的反引号、`$()`、重定向符或换行命令。
+查询词由用户原话里的术语、报错原文和目标语法要素名组成。脚本会自动处理两类词，
+不必手工调整：
 
-## 从零起手先看概念地图
+- 中文口语词自动扩展到 TSL 术语（如"打印"→输出/writeLn，"列表"→数组，
+  "程序慢"→性能分析）。用户怎么说就怎么传。
+- `tsl`、`tsf`、`tinysoft`、`program`、`debug`、`please` 这几个词不参与逐词匹配，
+  但可能整体把查询导向某个专题页。无结果时靠加这类词补救没有用，改为换更具体的
+  语法要素名。
 
-面对自然语言需求、还不确定该往哪个 TSL 概念上想时（尤其从零编写、周围无参考代码），先运行：
+## 弱命中视同无匹配
+
+候选里的 `Weak: yes` 表示该节没有任何强信号命中（意图短语、标题、标识符、
+标签），只靠正文低分撞词进入候选。弱候选不作为选择对象：
+
+- 候选全部为弱命中时，lookup 返回 rc=2，按无匹配处理——改进查询词重试，
+  仍全弱即为事实缺口。
+- 个别候选为弱命中、其余为强命中时，只从强命中里挑选。
+
+没有 `Weak` 行的候选也不等于相关：词面命中不代表该节支持当前结论，仍要按
+Summary 判断后再取回正文核对。
+
+## 代码块必须标注来源
+
+给出的每个 TSL/TSF 代码块，紧随其后写一行来源标注，列出所依据的全部 Section ID：
+
+```txt
+来源：05_functions_and_calls--可直接照写示例--基础函数-过程骨架（可直接照写示例），02_core_model--文件模型核心规则
+```
+
+Section ID 抄自 `--section` 输出首部的 `Section ID:` 行。多个要素合成一个代码块时，
+逐个列出，逗号分隔。身份按取回的正文分两种写法：
+
+- 该 Section ID 提供了照写的代码围栏：在 ID 后用括号写出紧邻该围栏的
+  `代码块身份：` 值。
+- 该 Section ID 只提供散文规则、正文里没有代码围栏（如
+  `02_core_model--文件模型核心规则`）：只写 ID，不加括号。规则段落没有身份行，
+  这不是缺口。
+
+写不出某个要素的 Section ID，说明该要素还没有取回：先补齐检索，再给代码。
+
+## 代码块身份
+
+`--section` 正文里每个代码围栏前有一行 `代码块身份：`。身份决定这段代码能否进入
+你的输出：
+
+| 身份 | 允许的用法 |
+| --- | --- |
+| `可直接照写示例` | 作为源码外形照写，替换业务内容后使用；依赖的 API 仍按事实边界另行核对 |
+| `反例 / 不可照写` | 只用于说明错误边界，不得作为实现出现在输出里 |
+| `输出片段` | 只用于说明运行结果，不得当作源码 |
+| `配置片段 / 概念骨架` | 只用于表达结构或配置意图，不得当作可运行代码 |
+| `仅服务端可执行示例` | 只在对应服务端环境成立，不得当作通用本地示例 |
+
+`--query` 的候选摘要不含身份行，身份只能从 `--section` 正文读取。这是必须走完第
+二步的另一个原因。
+
+同一个 section 常同时含多种身份（如示例代码后紧跟 `输出片段`）。身份按围栏逐个
+对应，不按 section 整体判断；一个代码块的依据跨越多种身份时，按最严格的那条处理
+——只要含 `反例 / 不可照写`，就不能照写。
+
+## 缺口时停止
+
+出现下列任一情形，即为事实缺口：
+
+**检索缺口** —— `--query` 改进查询词后仍无匹配；lookup 返回非零状态；`--section`
+取回的正文没有支持当前结论；`--section` 正文里目标围栏前没有 `代码块身份：` 行。
+
+**环境缺口** —— 目标运行时版本不明；项目路径、数据结构或运行参数等项目事实缺失；
+`tsl-api-reference` 等依赖的 Skill 不可用。
+
+缺口时的输出由三部分组成，按此顺序：
+
+1. 已取回并可用的事实，只列 Section ID，不复述正文。
+2. 缺失的具体要素，以及为它试过的查询词。
+3. 需要用户提供什么，或需要哪个 Skill、哪份项目文档补齐。
+
+不输出包含缺口要素的 TSL 代码，注释掉的、标 TODO 的和「仅供参考」的版本同样不
+输出。一段代码里只要有一个要素没取回，整段都不给出，不交付「其余部分已验证」的
+半成品。
+
+不得改为下列任一做法：
+
+- 手工浏览或顺序通读 `references/` 页面。
+- 凭记忆、相似语言或猜测产生新的 TSL 写法。
+- 用候选摘要或概念地图代替章节正文。
+- 给出未标注来源的代码块。
+
+## 查询词无从下手时先取概念地图
+
+若需求只有自然语言、无法从中取出 TSL 概念词或错误文本来构造 `--query`，先运行：
 
 ```bash
 python <this-skill-dir>/scripts/lookup.py --map
 ```
 
-它列出全部专题的纯文本职责摘要，用于把需求映射到 TSL 特有概念。地图不含可照写事实；选定概念后仍需依次执行 `--query` 和 `--section`。
+它列出全部专题的纯文本职责摘要，用于把需求映射到 TSL 特有概念。地图不含可照写事实；从地图取得概念词后，仍按上面的两步执行 `--query` 和 `--section`。
+
+## 退出码
+
+| 退出码 | 含义 | 处理方式 |
+| --- | --- | --- |
+| 0 | 查询或取回成功 | 读取输出并继续两步流程 |
+| 1 | `--check` 发现参考页问题，或参考目录内没有可校验的参考页 | 修复参考页，或检查 `--references-dir` 路径与 skill 安装 |
+| 2 | 参数不合法、`--query` 无匹配或候选全部为弱命中、`--section` ID 不存在 | 见下 |
+
+`--section` ID 不存在时，脚本会在 stderr 打印最接近的若干 Section ID；从中挑选正确 ID 重试，不要凭猜测拼写 ID。一次传入多个 ID 时只要有一个不存在就不返回任何正文，修正后整批重试。
+
+`--query` 无匹配或候选全部为 `Weak: yes` 时改进查询词重试。仍无强命中即为事实缺口：按上面「缺口时停止」处理。
 
 ## 事实边界
 
-本 Skill 只拥有 TSL/TSF 的语言语法、文件模型、表达式、控制流、对象、运行时语言结构和 TS-SQL 外形。先逐项拆分混合请求，再把其他事实交给对应所有者：
+本 Skill 只拥有 TSL/TSF 的语言语法、文件模型、表达式、控制流、对象、运行时语言
+结构和 TS-SQL 外形。混合请求先逐项拆分，只回答其中的语法部分。
 
-- API 名称、签名、参数、返回值、平台 scope、解释器可用性和金融取数事实：使用 `tsl-api-reference` skill。
-- 命名、代码风格、工具链和模块集成：使用目标仓库相应文档、脚本或 CI。
-- 项目路径、数据结构、部署方式和运行参数：只使用目标项目的真实文档与配置。
+API 名称、签名、参数、返回值、平台 scope、解释器可用性和金融取数事实属于
+`tsl-api-reference` skill。语法示例里可以出现 API 名称来展示调用位置，但这只证明
+源码外形，不证明该 API 的签名、返回行为、平台 scope 或在目标解释器上可用；需要这
+些结论时查 API skill，没有事实支持时按「缺口时停止」处理，不把两个 skill 的片段
+拼成「可运行」结论。
 
-语法示例可以使用 API 名称帮助展示调用位置，但这只证明源码外形，不证明 API 的签名、返回行为、平台 scope 或目标解释器可用。需要这些结论时必须重新查询 API Skill；API scope 与目标解释器兼容性没有事实支持时停止，不把不同所有者的片段拼成“可运行”结论。
+## 运行方式不属于本 Skill
 
-## 代码块身份
+TSL 的运行方式、解释器路径、平台检测和环境选择都不是本 Skill 的事实。用户询问
+如何运行 TSL，或需要实际执行 TSL 时，读取目标文件附近最近的 `AGENTS.md`、项目
+脚本或 CI，并严格照其规定执行。
 
-生成或判断代码时，必须遵守 lookup 结果中紧邻代码围栏的身份。只允许以下五种身份：
-
-- `可直接照写示例`：可作为源码外形，但“可直接照写”不等于已经验证目标环境可用，仍需按任务替换业务内容并核对依赖事实。
-- `反例 / 不可照写`：只用于识别错误边界，不得复制为实现。
-- `输出片段`：只表示结果，不得当作源码。
-- `配置片段 / 概念骨架`：只表达结构或配置意图，不得假定为可直接运行代码。
-- `仅服务端可执行示例`：只在相应服务端运行环境中成立，不得当作通用本地可执行示例。
-
-## 缺口时停止
-
-lookup 无匹配或返回非零状态、结果没有支持当前结论、代码块身份缺失或冲突、运行时版本不明、项目事实缺失、依赖的 Skill 不可用时，明确说明缺失项并停止。不得改为手工浏览全部参考页，也不得凭经验、相似语言或猜测产生新的 TSL 写法。
-
-## 询问或执行运行方式前读取项目指引
-
-用户询问如何运行 TSL，或需要实际执行 TSL 时，都先读取目标文件附近最近的 `AGENTS.md`、项目脚本或 CI。实际执行前还要完成平台检测并严格使用指定环境；不同平台或多个 Windows 环境不得混用、默认任选或自行回退。
+本 Skill 只能确认语法外形正确，不能确认代码在目标解释器上可运行。给出未经执行的
+代码时，据此区分「语法已取回」与「运行时未验证」。
 
 ## 维护校验
 
-维护本 Skill、参考页或 lookup 实现后必须运行：
-
-```bash
-python <this-skill-dir>/scripts/lookup.py --check
-```
+改动本 Skill、参考页、`data/` 词表或 lookup 实现后运行 `scripts/lookup.py --check`
+校验参考页结构与词表覆盖，rc=0 才算通过。口语同义词和页级意图短语维护在
+`data/lexicon.json`，策展纪律见 `data/README.md`。