✨ 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
This commit is contained in:
@@ -6,24 +6,12 @@
|
||||
|
||||
回答“如何正确声明 `function` 和 `procedure`、`.tsl` 脚本语句区如何调用后置函数声明、怎样使用参数修饰、普通函数默认参数与可变参数，以及哪些函数写法会直接编译失败”。
|
||||
|
||||
## 智能体函数/调用判断流程
|
||||
|
||||
1. 先判断目标文件是 `.tsl` 还是 `.tsf`；文件模型事实见 [02_core_model.md](02_core_model.md)。
|
||||
2. `.tsl` 中先写语句区，再把 `function` / `procedure` 声明放在后面；不要在声明区后面追加脚本语句。
|
||||
3. `.tsf` 中把顶层 `function` / `procedure` 当成模块 / 函数扩展声明；不要写成顺序执行入口。
|
||||
4. 用户只说“写一个函数”且没有指定 `procedure` 时，默认用 `function`。
|
||||
5. 只有用户明确要求 `procedure` / 过程时，才用 `procedure`；即使任务没有返回值，也默认用 `function`。
|
||||
6. 调用普通 TSL 函数时，命名参数只写 `name: value`；不要把 `name = value` 当成命名参数。
|
||||
7. 参数是否写回调用方要看 `const` / `var` / `{$varByRef-}` / `in` / `out`，不要默认按其他语言习惯推断。
|
||||
8. 默认参数先按普通函数规则处理；`unit interface` 或 `unit const` 默认值的事实见 [09_units_and_scope.md](09_units_and_scope.md)。
|
||||
9. 匿名函数和 TSL 函数值只按本页明确的 `call(f, ...)` / `##f(...)` 生成；`external`、原生函数指针包装、C 回调、线程和系统交互的事实见 [18_external_calls_and_threads.md](18_external_calls_and_threads.md)。
|
||||
10. 没有对应代码块时不要发明函数/调用写法；尤其不要把二进制函数、系统函数、TSL 函数值、原生函数指针和匿名函数都套成同一种调用语法。
|
||||
|
||||
## 核心规则
|
||||
|
||||
- 最稳妥的函数骨架仍然是 `function Name(...); begin ... end;`。
|
||||
- 用户提示词里的“函数”默认对应 `function`，不要自动改写成 `procedure`。
|
||||
- `procedure Name(...); begin ... end;` 只在用户明确要求 `procedure` / 过程时生成；不要因为没有返回值就自动改用 `procedure`。
|
||||
- `procedure` 头后不允许写返回类型；返回类型注解只用于 `function`。
|
||||
- 在 `.tsl` 文件模型层，脚本语句后可以接函数声明；语句区在前顺序执行，声明区在后提供函数/过程定义。见 [02_core_model.md](02_core_model.md)。
|
||||
- 在 `.tsf` 文件模型层，顶层 `function` / `procedure` 是模块/函数扩展声明；部署到解释器 `funcext` 后可被脚本直接调用。
|
||||
- 函数头后默认保留分号；不要为了简写主动省略。
|
||||
@@ -57,7 +45,7 @@
|
||||
- 匿名函数和 TSL 函数值的稳定调用方式仍是 `call(f, ...)` 或 `##f(...)`。
|
||||
- `f(...)` 这种“函数变量直接调用”写法不作为可写事实；无论 `f` 是匿名函数、`findFunction(...)` 还是 `thisFunction(...)` 返回的函数指针，都不要默认写成直调。
|
||||
- `::FuncName(...)` 可以指向全局/系统函数，用来绕过当前作用域里的同名局部函数。
|
||||
- `external`、原生函数指针包装、`makeInstance` / C 回调和线程调用的事实见 [18_external_calls_and_threads.md](18_external_calls_and_threads.md)。
|
||||
- `external`、原生函数指针包装、`makeInstance` / C 回调和线程调用的事实见 [17_external_calls_and_threads.md](17_external_calls_and_threads.md)。
|
||||
- 不要在 `.tsl` 的函数声明区之后继续追加脚本语句。
|
||||
|
||||
## 可直接照写示例
|
||||
@@ -67,10 +55,12 @@
|
||||
- 普通运行示例默认按 `.tsl` 脚本语句区书写；入口语句放前面，函数 / 过程 / 类型声明放在后置声明区。
|
||||
- `.tsf` 函数 / 过程示例只按可复用顶层声明理解，不要在 `.tsf` 里追加顺序执行入口语句。
|
||||
- `procedure` 示例只在用户明确要求 `procedure` / 过程时复制；普通“写函数”任务不要用。
|
||||
- `external`、原生函数指针包装、C 回调、线程、系统交互和二进制函数边界不在本页硬推断；相关事实见 [18_external_calls_and_threads.md](18_external_calls_and_threads.md) 或函数库文档。
|
||||
- `external`、原生函数指针包装、C 回调、线程、系统交互和二进制函数边界不在本页硬推断；相关事实见 [17_external_calls_and_threads.md](17_external_calls_and_threads.md) 或函数库文档。
|
||||
|
||||
### 基础函数 / 过程骨架
|
||||
|
||||
<!-- tags: 定义函数, 怎么写函数, 函数骨架, 最少几行, procedure 怎么写, 函数放哪里, 先调用后声明 -->
|
||||
|
||||
`.tsl` 语句区调用后置函数声明：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
@@ -151,6 +141,8 @@ end;
|
||||
|
||||
### 签名增强：参数类型与返回值类型注解
|
||||
|
||||
<!-- tags: 返回值类型, 声明返回类型, 参数标类型, 类型注解, 函数签名 -->
|
||||
|
||||
带参数类型和返回值类型：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
@@ -208,6 +200,8 @@ end;
|
||||
|
||||
### 参数传递方式
|
||||
|
||||
<!-- tags: 传引用, 按引用传, 引用传递, 传值, 按值传递, 改形参影响外面, 写回调用方, 出参, 入参, 只读参数, 不让函数改 -->
|
||||
|
||||
未修饰参数默认写回调用方：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
@@ -323,6 +317,8 @@ end;
|
||||
|
||||
### `return` 与 `exit`
|
||||
|
||||
<!-- tags: 返回值, 怎么返回结果, 结果返回, 提前结束, 提前返回, 中途退出函数, 无返回值退出 -->
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
|
||||
```tsl
|
||||
@@ -353,6 +349,8 @@ end;
|
||||
|
||||
### 调用增强：命名参数与混用规则
|
||||
|
||||
<!-- tags: 按参数名传, 命名实参, 关键字参数, 指定参数名, 位置参数混用 -->
|
||||
|
||||
命名参数调用：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
@@ -430,6 +428,8 @@ end;
|
||||
|
||||
### 默认参数
|
||||
|
||||
<!-- tags: 默认值, 可选参数, 参数省略, 不传就用默认 -->
|
||||
|
||||
默认值参数：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
@@ -514,6 +514,8 @@ function F(a, b = 100, c = default_value);
|
||||
|
||||
### 可变参数 `...`
|
||||
|
||||
<!-- tags: 任意多个参数, 不定参数, 变长参数, 参数个数不固定, 参数转发 -->
|
||||
|
||||
尾部可变参数：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
@@ -650,6 +652,8 @@ end;
|
||||
|
||||
### 匿名函数与函数指针
|
||||
|
||||
<!-- tags: lambda, 闭包, 函数当变量, 函数当参数, 回调, 函数指针, 把函数存起来 -->
|
||||
|
||||
匿名函数变量：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
@@ -771,6 +775,8 @@ writeLn(a(7, 8));
|
||||
|
||||
### `::` 指向全局函数
|
||||
|
||||
<!-- tags: 重名, 同名函数, 调全局的那个, 作用域冲突, 指定全局函数 -->
|
||||
|
||||
当当前作用域里有同名局部函数时，可以用 `::FuncName(...)` 指定去调全局/系统函数：
|
||||
|
||||
代码块身份：可直接照写示例
|
||||
@@ -807,7 +813,7 @@ end;
|
||||
|
||||
### 系统交互专题
|
||||
|
||||
`external`、原生函数指针包装、`makeInstance` / C 回调和线程调用，统一见 [18_external_calls_and_threads.md](18_external_calls_and_threads.md)。这一篇只保留“普通函数怎样定义和调用”的主线。
|
||||
`external`、原生函数指针包装、`makeInstance` / C 回调和线程调用，统一见 [17_external_calls_and_threads.md](17_external_calls_and_threads.md)。这一篇只保留“普通函数怎样定义和调用”的主线。
|
||||
|
||||
## 默认生成模板
|
||||
|
||||
|
||||
Reference in New Issue
Block a user