🐛 fix(tsl-syntax-reference): route derived rules and bound section size
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: tsl-syntax-reference
|
||||
description: 当用户需要编写、修改、审查或解释 TSL/TSF、TS-SQL、Tinysoft/天软脚本或公式，涉及 `.tsl` / `.tsf` 文件，排查 invalid statement 等语法错误，或核对语言与运行时结构规则时使用。
|
||||
description: "当用户需要编写、修改、审查或解释 TSL/TSF、TS-SQL、Tinysoft/天软脚本或公式，涉及 `.tsl` / `.tsf` 文件，排查 invalid statement 等语法错误，或核对语言与运行时结构规则时使用；包括你自认为已经确定的写法。不用于查询 API 签名或天软数据字典字段（改用 tsl-api-reference），也不用于选择解释器或运行方式（读取目标文件附近的 AGENTS.md）。"
|
||||
---
|
||||
|
||||
# TSL Syntax Reference
|
||||
@@ -12,67 +12,15 @@ description: 当用户需要编写、修改、审查或解释 TSL/TSF、TS-SQL
|
||||
下标起点这类"看起来确定"的规则同样要取回。`<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
|
||||
python <this-skill-dir>/scripts/lookup.py --query "invalid statement 声明区" --mode diagnose
|
||||
python <this-skill-dir>/scripts/lookup.py --query "数组下标" --mode explain
|
||||
python <this-skill-dir>/scripts/lookup.py --help
|
||||
```
|
||||
|
||||
- `write`：编写或修改代码。
|
||||
- `diagnose`：定位语法错误或错误写法。
|
||||
- `explain`：解释语言规则或代码含义。
|
||||
|
||||
用 `--limit N`（1..10，默认 5）控制返回的查询候选条数。
|
||||
|
||||
`--mode write` 会在查询候选之前额外附加 `Required: yes` 的前置章节（文件模型与
|
||||
语言核心事实速查）。它们不占 `--limit` 预算，也不是本次查询的命中结果：先按它们
|
||||
核对文件模型和硬规则，再从 `Required: no` 的候选里挑选支持当前结论的章节。前置
|
||||
章节在同一任务内取回一次即可；后续 `--query` 重复列出它们时，不必再次 `--section`。
|
||||
其中 `syntax-01-002` 是从专题页逐条派生的强制速查，不是另一份完整事实源；生成结论
|
||||
仍要取回拥有该规则的专题 Section。
|
||||
|
||||
`--query` 输出候选后，必须执行下面这种精确取回。多个已选定的 Section ID 可以
|
||||
一次传入：
|
||||
|
||||
```bash
|
||||
python <this-skill-dir>/scripts/lookup.py --section "syntax-05-004" "syntax-02-002"
|
||||
```
|
||||
|
||||
只有 `--section` 返回的章节正文可作为本次任务的语法事实来源；候选摘要和概念地图都不能直接支持代码结论。需要补充时改进查询词再次检索。
|
||||
|
||||
## 构造查询词
|
||||
|
||||
从用户原话中提取错误原文、TSL 标识符和单一语法要素名；保留这些词在用户原话中的
|
||||
写法，不传完整句，也不自行翻译成猜测术语。脚本会自动处理两类词，不必手工调整：
|
||||
|
||||
- 中文口语词自动扩展到 TSL 术语（如"打印"→输出/writeLn，"列表"→数组，
|
||||
"程序慢"→性能分析）。保留提取词的原写法即可。
|
||||
- `tsl`、`tsf`、`tinysoft`、`debug`、`please` 这几个词不参与逐词匹配，
|
||||
但可能整体把查询导向某个专题页。无结果时靠加这类词补救没有用，改为换更具体的
|
||||
语法要素名。`program` 是真实 TSL 关键字，会参与精确匹配。
|
||||
|
||||
## 弱命中视同无匹配
|
||||
|
||||
候选里的 `Weak: yes` 表示该节没有任何强信号命中（意图短语、标题、标识符、
|
||||
标签），只靠正文低分撞词进入候选。弱候选不作为选择对象：
|
||||
|
||||
- 候选全部为弱命中时，lookup 返回 rc=2，按无匹配处理——改进查询词重试，
|
||||
仍全弱即为事实缺口。
|
||||
- 个别候选为弱命中、其余为强命中时，只从强命中里挑选。
|
||||
|
||||
没有 `Weak` 行的候选也不等于相关：词面命中不代表该节支持当前结论，仍要按
|
||||
Summary 判断后再取回正文核对。
|
||||
构造任一命令前先运行上面的 `--help`。帮助输出独占动作、mode、参数范围、查询词、
|
||||
弱命中、概念地图、前置章节、Owner Section、结构校验和退出码的命令契约；不要在本
|
||||
文件中推断或复用旧参数。检索必须完成 `--query` 到 `--section` 两步，只有
|
||||
`--section` 返回的正文可作为语法事实。`syntax-01-002` 是派生速查；命中其中规则后，
|
||||
按紧邻规则的 `Owner Section` 取回真正拥有该事实的专题 Section。
|
||||
|
||||
## 代码块必须标注来源
|
||||
|
||||
@@ -145,32 +93,6 @@ Section ID 抄自 `--section` 输出首部的 `Section ID:` 行。多个要素
|
||||
- 用候选摘要或概念地图代替章节正文。
|
||||
- 给出未标注来源的代码块。
|
||||
|
||||
## 查询词无从下手时先取概念地图
|
||||
|
||||
若需求只有自然语言、无法从中取出 TSL 概念词或错误文本来构造 `--query`，先运行：
|
||||
|
||||
```bash
|
||||
python <this-skill-dir>/scripts/lookup.py --map
|
||||
```
|
||||
|
||||
它列出全部专题的纯文本职责摘要，用于把需求映射到 TSL 特有概念。地图不含可照写事实；从地图取得概念词后，仍按上面的两步执行 `--query` 和 `--section`。
|
||||
|
||||
## 退出码
|
||||
|
||||
| 退出码 | 含义 | 处理方式 |
|
||||
| ------ | --------------------------------------------------------------------- | ------------------------------------------------------- |
|
||||
| 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 的语言语法、文件模型、表达式、控制流、对象、运行时语言
|
||||
@@ -202,12 +124,5 @@ TSL 的运行方式、解释器路径、平台检测和环境选择都不是本
|
||||
|
||||
## 维护校验
|
||||
|
||||
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`。
|
||||
维护本 Skill、参考页、词表或检索器时，先读 [`data/README.md`](data/README.md)，按其中
|
||||
的 Section ID、派生规则、粒度和验证纪律执行。
|
||||
|
||||
Reference in New Issue
Block a user