📦 deps(tsl): sync tsl-playbook from a71480a4

Source-Commit: a71480a4ae

skills/tsl-syntax-reference/SKILL.md

@@ -24,7 +24,7 @@ description: 当用户需要编写、修改、审查或解释 TSL/TSF、TS-SQL
 根据任务意图选择模式：
 
 ```bash
-python <this-skill-dir>/scripts/lookup.py --query "命名参数 默认参数" --mode write
+python <this-skill-dir>/scripts/lookup.py --query "命名参数" --mode write
 python <this-skill-dir>/scripts/lookup.py --query "invalid statement 声明区" --mode diagnose
 python <this-skill-dir>/scripts/lookup.py --query "数组下标" --mode explain
 ```
@@ -39,23 +39,25 @@ python <this-skill-dir>/scripts/lookup.py --query "数组下标" --mode explain
 语言核心事实速查）。它们不占 `--limit` 预算，也不是本次查询的命中结果：先按它们
 核对文件模型和硬规则，再从 `Required: no` 的候选里挑选支持当前结论的章节。前置
 章节在同一任务内取回一次即可；后续 `--query` 重复列出它们时，不必再次 `--section`。
+其中 `syntax-01-002` 是从专题页逐条派生的强制速查，不是另一份完整事实源；生成结论
+仍要取回拥有该规则的专题 Section。
 
 `--query` 输出候选后，必须执行下面这种精确取回。多个已选定的 Section ID 可以
 一次传入：
 
 ```bash
-python <this-skill-dir>/scripts/lookup.py --section "05_functions_and_calls--可直接照写示例--基础函数-过程骨架" "02_core_model--文件模型核心规则"
+python <this-skill-dir>/scripts/lookup.py --section "syntax-05-004" "syntax-02-002"
 ```
 
 只有 `--section` 返回的章节正文可作为本次任务的语法事实来源；候选摘要和概念地图都不能直接支持代码结论。需要补充时改进查询词再次检索。
 
 ## 构造查询词
 
-查询词由用户原话里的术语、报错原文和目标语法要素名组成。脚本会自动处理两类词，
-不必手工调整：
+从用户原话中提取错误原文、TSL 标识符和单一语法要素名；保留这些词在用户原话中的
+写法，不传完整句，也不自行翻译成猜测术语。脚本会自动处理两类词，不必手工调整：
 
 - 中文口语词自动扩展到 TSL 术语（如"打印"→输出/writeLn，"列表"→数组，
-  "程序慢"→性能分析）。用户怎么说就怎么传。
+  "程序慢"→性能分析）。保留提取词的原写法即可。
 - `tsl`、`tsf`、`tinysoft`、`program`、`debug`、`please` 这几个词不参与逐词匹配，
   但可能整体把查询导向某个专题页。无结果时靠加这类词补救没有用，改为换更具体的
   语法要素名。
@@ -77,7 +79,7 @@ Summary 判断后再取回正文核对。
 给出的每个 TSL/TSF 代码块，紧随其后写一行来源标注，列出所依据的全部 Section ID：
 
 ```txt
-来源：05_functions_and_calls--可直接照写示例--基础函数-过程骨架（可直接照写示例），02_core_model--文件模型核心规则
+来源：syntax-05-004（可直接照写示例），syntax-02-002
 ```
 
 Section ID 抄自 `--section` 输出首部的 `Section ID:` 行。多个要素合成一个代码块时，
@@ -86,7 +88,7 @@ Section ID 抄自 `--section` 输出首部的 `Section ID:` 行。多个要素
 - 该 Section ID 提供了照写的代码围栏：在 ID 后用括号写出紧邻该围栏的
   `代码块身份：` 值。
 - 该 Section ID 只提供散文规则、正文里没有代码围栏（如
-  `02_core_model--文件模型核心规则`）：只写 ID，不加括号。规则段落没有身份行，
+  `syntax-02-002`）：只写 ID，不加括号。规则段落没有身份行，
   这不是缺口。
 
 写不出某个要素的 Section ID，说明该要素还没有取回：先补齐检索，再给代码。
@@ -96,13 +98,13 @@ Section ID 抄自 `--section` 输出首部的 `Section ID:` 行。多个要素
 `--section` 正文里每个代码围栏前有一行 `代码块身份：`。身份决定这段代码能否进入
 你的输出：
 
-| 身份 | 允许的用法 |
-| --- | --- |
-| `可直接照写示例` | 作为源码外形照写，替换业务内容后使用；依赖的 API 仍按事实边界另行核对 |
-| `反例 / 不可照写` | 只用于说明错误边界，不得作为实现出现在输出里 |
-| `输出片段` | 只用于说明运行结果，不得当作源码 |
-| `配置片段 / 概念骨架` | 只用于表达结构或配置意图，不得当作可运行代码 |
-| `仅服务端可执行示例` | 只在对应服务端环境成立，不得当作通用本地示例 |
+| 身份                  | 允许的用法                                                            |
+| --------------------- | --------------------------------------------------------------------- |
+| `可直接照写示例`      | 作为源码外形照写，替换业务内容后使用；依赖的 API 仍按事实边界另行核对 |
+| `反例 / 不可照写`     | 只用于说明错误边界，不得作为实现出现在输出里                          |
+| `输出片段`            | 只用于说明运行结果，不得当作源码                                      |
+| `配置片段 / 概念骨架` | 只用于表达结构或配置意图，不得当作可运行代码                          |
+| `仅服务端可执行示例`  | 只在对应服务端环境成立，不得当作通用本地示例                          |
 
 `--query` 的候选摘要不含身份行，身份只能从 `--section` 正文读取。这是必须走完第
 二步的另一个原因。
@@ -150,26 +152,38 @@ python <this-skill-dir>/scripts/lookup.py --map
 
 ## 退出码
 
-| 退出码 | 含义 | 处理方式 |
-| --- | --- | --- |
-| 0 | 查询或取回成功 | 读取输出并继续两步流程 |
-| 1 | `--check` 发现参考页问题，或参考目录内没有可校验的参考页 | 修复参考页，或检查 `--references-dir` 路径与 skill 安装 |
-| 2 | 参数不合法、`--query` 无匹配或候选全部为弱命中、`--section` ID 不存在 | 见下 |
+| 退出码 | 含义                                                                  | 处理方式                                                |
+| ------ | --------------------------------------------------------------------- | ------------------------------------------------------- |
+| 0      | 查询或取回成功                                                        | 读取输出并继续两步流程                                  |
+| 1      | `--check` 发现参考页问题，或参考目录内没有可校验的参考页              | 修复参考页，或检查 `--references-dir` 路径与 skill 安装 |
+| 2      | 参数不合法、`--query` 无匹配或候选全部为弱命中、`--section` ID 不存在 | 见下                                                    |
 
 `--section` ID 不存在时，脚本会在 stderr 打印最接近的若干 Section ID；从中挑选正确 ID 重试，不要凭猜测拼写 ID。一次传入多个 ID 时只要有一个不存在就不返回任何正文，修正后整批重试。
 
 `--query` 无匹配或候选全部为 `Weak: yes` 时改进查询词重试。仍无强命中即为事实缺口：按上面「缺口时停止」处理。
 
+`--map`、`--query`、`--section`、`--check` 共用安装前置检查。参考目录不存在或没有
+参考页时，任何动作都以 rc=1 报告路径/安装错误；这不属于事实零命中，不能靠改查询词
+重试。
+
 ## 事实边界
 
 本 Skill 只拥有 TSL/TSF 的语言语法、文件模型、表达式、控制流、对象、运行时语言
 结构和 TS-SQL 外形。混合请求先逐项拆分，只回答其中的语法部分。
 
 API 名称、签名、参数、返回值、平台 scope、解释器可用性和金融取数事实属于
-`tsl-api-reference` skill。语法示例里可以出现 API 名称来展示调用位置，但这只证明
-源码外形，不证明该 API 的签名、返回行为、平台 scope 或在目标解释器上可用；需要这
-些结论时查 API skill，没有事实支持时按「缺口时停止」处理，不把两个 skill 的片段
-拼成「可运行」结论。
+`tsl-api-reference` skill。准备面向用户交付的 TSL/TSF 代码时，按下面顺序处理：
+
+1. 先枚举代码中除语言关键字和用户定义符号外的调用标识符。
+2. 语言结构逐项用本 Skill 取回；每个 builtin/API 都逐项用 `tsl-api-reference` 取回
+   名称、签名和目标 scope。
+3. 任一 API 依赖没有取回时，整段交付代码按「缺口时停止」处理；不能只给语法已查的
+   半成品，也不能凭语法页示例中的 API 名称补齐。
+
+纯语法说明可以使用明确标为占位的用户定义调用来展示调用位置，而不必为该占位符查
+API；但不得声称该占位调用的 API 行为或输出，也不得把真实 builtin/API 当成无需核对
+的占位符。解释一旦包含真实 API 的签名、可用性、返回值、输出，或代码将面向用户
+交付，就必须执行上面的 API 取回步骤。
 
 ## 运行方式不属于本 Skill
 
@@ -178,10 +192,17 @@ TSL 的运行方式、解释器路径、平台检测和环境选择都不是本
 脚本或 CI，并严格照其规定执行。
 
 本 Skill 只能确认语法外形正确，不能确认代码在目标解释器上可运行。给出未经执行的
-代码时，据此区分「语法已取回」与「运行时未验证」。
+代码时，据此区分「语法已取回」与「运行时未验证」。用户未要求实际执行时，解释器
+不可用是受支持状态，不构成事实缺口，也不要求提供可重放运行证据。
 
 ## 维护校验
 
-改动本 Skill、参考页、`data/` 词表或 lookup 实现后运行 `scripts/lookup.py --check`
-校验参考页结构与词表覆盖，rc=0 才算通过。口语同义词和页级意图短语维护在
-`data/lexicon.json`，策展纪律见 `data/README.md`。
+Section ID 来自标题下的显式 `<!-- section-id: ... -->` 元数据，不从标题派生；改标题
+时保留原 ID。新增章节时分配新 ID，不重排或复用旧 ID。
+
+改动本 Skill、参考页、`data/` 词表或 lookup 实现后，先运行
+`scripts/lookup.py --check` 校验显式 ID、标题层级、quickstart 派生规则、代码块身份、
+链接与词表页覆盖。在本 playbook 仓库维护时，再从仓库根目录运行
+`python -m unittest test.test_tsl_syntax_reference -v` 校验检索排序、退出码和 CLI
+行为。`--check` 只是结构检查，不证明检索排序、事实语义或示例运行结果。口语同义词
+和页级意图短语维护在 `data/lexicon.json`，策展纪律见 `data/README.md`。