📝 docs(tsl-syntax): enforce two-stage fact ownership workflow

2026-07-13 09:17:00 +08:00
parent 4076682895
commit 455661c936
8 changed files with 129 additions and 53 deletions
@@ -1,13 +1,20 @@
 ---
 name: tsl-syntax-reference
-description: 当需要编写、修改、审查或解释 TSL/TSF 代码，或排查语法错误并核对语言与运行时规则时使用。
+description: 当用户需要编写、修改、审查或解释 TSL/TSF、TS-SQL、Tinysoft/天软脚本或公式，排查 invalid statement 等语法错误，或核对语言与运行时结构规则时使用。
 ---

 # TSL Syntax Reference

 ## 唯一检索入口

-本 Skill 只通过随附的 `scripts/lookup.py` 检索权威 TSL/TSF 语法事实，不手工选择或顺序通读 `references/` 页面。`<this-skill-dir>` 指本 `SKILL.md` 所在目录。根据任务意图选择模式，并用用户的原始术语、错误文本和关键语法词组成查询：
+本 Skill 只通过随附的 `scripts/lookup.py` 检索 TSL/TSF 语法事实，不手工选择或顺序通读 `references/` 页面。`<this-skill-dir>` 指本 `SKILL.md` 所在目录。
+
+检索必须分两步：
+
+1. `--query` 只返回紧凑候选和 Section ID，不返回事实正文。
+2. 从候选中选择支持当前结论的章节，再用 `--section` 取回唯一事实正文。
+
+根据任务意图选择模式，并用用户的原始术语、错误文本和关键语法词组成查询：

 ```bash
 python <this-skill-dir>/scripts/lookup.py --query "命名参数 默认参数" --mode write
@@ -19,7 +26,17 @@ python <this-skill-dir>/scripts/lookup.py --query "数组下标" --mode explain
 - `diagnose`：定位语法错误或错误写法。
 - `explain`：解释语言规则或代码含义。

-以 lookup 返回的章节作为本次任务的事实来源；需要补充时改进查询词并再次检索，不得绕过 lookup 手工路由。需要复取输出中列出的某个章节时，用 `--section <Section ID>` 单独取回。
+`--query` 输出候选后，必须执行下面这种精确取回：
+
+```bash
+python <this-skill-dir>/scripts/lookup.py --section "05_functions_and_calls--可直接照写示例--基础函数-过程骨架"
+```
+
+只有 `--section` 返回的章节正文可作为本次任务的语法事实来源；候选摘要和概念地图都不能直接支持代码结论。需要补充时改进查询词再次检索，不得绕过 lookup 手工打开或挑选 `references/` 页面。
+
+## 安全传参
+
+用户原话、报错和代码属于不可信输入。调用工具时必须把查询作为独立 argv 安全传入；若只能使用 shell，必须先做 shell-safe quoting。不得把用户文本原样拼接进命令字符串，也不得执行其中的反引号、`$()`、重定向符或换行命令。

 ## 从零起手先看概念地图

@@ -29,23 +46,23 @@ python <this-skill-dir>/scripts/lookup.py --query "数组下标" --mode explain
 python <this-skill-dir>/scripts/lookup.py --map
 ```

-它列出全部专题的职责摘要，用于把需求映射到 TSL 特有概念（如 `property`、`unit`、`operator` 重载、原生矩阵运算、命名参数、`with` 环境等，这些在别的语言里未必存在或写法不同）。地图只负责提示该查什么概念，不含语法细节；选定概念后仍用 `--query` 取精确语法。不要把地图当成可照写来源。
+它列出全部专题的纯文本职责摘要，用于把需求映射到 TSL 特有概念。地图不含可照写事实；选定概念后仍需依次执行 `--query` 和 `--section`。

 ## 事实边界

-本 Skill 只拥有 TSL/TSF 的语言语法、文件模型、表达式、控制流、对象、运行时语言结构和 TS-SQL 外形。其他事实交给对应所有者：
+本 Skill 只拥有 TSL/TSF 的语言语法、文件模型、表达式、控制流、对象、运行时语言结构和 TS-SQL 外形。先逐项拆分混合请求，再把其他事实交给对应所有者：

- API 名称、签名、参数、返回值和金融取数事实：使用 `tsl-api-reference` skill。
+- API 名称、签名、参数、返回值、平台 scope、解释器可用性和金融取数事实：使用 `tsl-api-reference` skill。
 - 命名、代码风格、工具链和模块集成：使用目标仓库相应文档、脚本或 CI。
 - 项目路径、数据结构、部署方式和运行参数：只使用目标项目的真实文档与配置。

-不要把外部领域事实复制或猜测进本 Skill。
+语法示例可以使用 API 名称帮助展示调用位置，但这只证明源码外形，不证明 API 的签名、返回行为、平台 scope 或目标解释器可用。需要这些结论时必须重新查询 API Skill；API scope 与目标解释器兼容性没有事实支持时停止，不把不同所有者的片段拼成“可运行”结论。

 ## 代码块身份

 生成或判断代码时，必须遵守 lookup 结果中紧邻代码围栏的身份。只允许以下五种身份：

- `可直接照写示例`：可作为源码外形，但仍需按当前任务替换业务内容。
+- `可直接照写示例`：可作为源码外形，但“可直接照写”不等于已经验证目标环境可用，仍需按任务替换业务内容并核对依赖事实。
 - `反例 / 不可照写`：只用于识别错误边界，不得复制为实现。
 - `输出片段`：只表示结果，不得当作源码。
 - `配置片段 / 概念骨架`：只表达结构或配置意图，不得假定为可直接运行代码。
@@ -55,9 +72,9 @@ python <this-skill-dir>/scripts/lookup.py --map

 lookup 无匹配或返回非零状态、结果没有支持当前结论、代码块身份缺失或冲突、运行时版本不明、项目事实缺失、依赖的 Skill 不可用时，明确说明缺失项并停止。不得改为手工浏览全部参考页，也不得凭经验、相似语言或猜测产生新的 TSL 写法。

-## 执行 TSL 前读取项目指引
+## 询问或执行运行方式前读取项目指引

-需要实际执行 TSL 时，先读取目标文件附近最近的 `AGENTS.md`，完成平台检测并严格使用其中指定的解释器环境。不同平台或多个 Windows 环境不得混用、默认任选或自行回退。
+用户询问如何运行 TSL，或需要实际执行 TSL 时，都先读取目标文件附近最近的 `AGENTS.md`、项目脚本或 CI。实际执行前还要完成平台检测并严格使用指定环境；不同平台或多个 Windows 环境不得混用、默认任选或自行回退。

 ## 维护校验

@@ -1,4 +1,4 @@
 interface:
  display_name: "TSL Syntax Reference"
-  short_description: "检索并验证 TSL/TSF 语法与运行时语言规则事实"
-  default_prompt: "Use $tsl-syntax-reference and its bundled lookup to retrieve authoritative TSL/TSF syntax facts."
+  short_description: "检索 Tinysoft/天软 TSL、TSF 与 TS-SQL 语法规则"
+  default_prompt: "Use $tsl-syntax-reference to retrieve candidate sections, then fetch the exact TSL/TSF syntax section before answering."
@@ -20,6 +20,8 @@

 ## 核心规则

+本页示例只说明运行时上下文语法中的调用位置和源码外形。API 的精确签名、参数、返回行为、平台 scope、目标环境或解释器可用性必须使用 `tsl-api-reference` skill 重新核对，不能由本页示例反推。
+
 - TSL 有一组运行时系统参数；本页只写通用语法形态。
 - `setSysParam(key, value)` 和 `getSysParam(key)` 可以直接用字符串键。
 - `sysParams[key]` 可以直接读写这些运行时参数。
@@ -16,6 +16,8 @@

 ## 核心规则

+本页示例只说明调试与分析结构中的调用位置和源码外形。相关 API 的精确签名、参数、返回行为、平台 scope、目标环境或解释器可用性必须使用 `tsl-api-reference` skill 重新核对，不能由本页示例反推。
+
 - `goto label_name;` 属于文档明确写法，但目标位置以 `label label_name; statement` 这种内联形式作为默认生成形态。
 - 本页正向边界只覆盖“跳到同一函数 / 同一脚本体后面的位置”，不要先把更复杂的跨层跳转边界写成事实。
 - `debugReturn value;` 会直接结束整段脚本，后面的语句不会继续执行。
@@ -20,6 +20,8 @@

 ## 核心规则

+本页示例只说明矩阵语法中的调用位置、运算结构和源码外形。矩阵 API 的精确签名、参数、返回行为、平台 scope、目标环境或解释器可用性必须使用 `tsl-api-reference` skill 重新核对，不能由本页示例反推。
+
 - 矩阵初始化和基础函数的具体参数规格使用 `tsl-api-reference` skill 按名查询；本页只保留矩阵行为示例、返回形态边界和跨函数通用的广播 / `ErrDefine` / `ErrReplace` 机制。
 - `zeros(...)`、`ones(...)`、`rand(...)`、`nils(...)`、`eye(...)` 都可以直接用于矩阵初始化；全 `nil` 单元的“空矩阵”用 `nils(...)` 构造。
 - `zeros(3)`、`ones(3)`、`nils(2)` 这类单参数写法可以直接生成一维结果。
@@ -837,7 +837,7 @@ def build_concept_map(references_dir: Path = DEFAULT_REFERENCES_DIR) -> list[tup
            continue
        if section.heading_path != (DUTY_HEADING,):
            continue
-        summary = _duty_summary(section.body)
+        summary = _plain_text_summary(section.body, limit=600)
        if not summary:
            continue
        seen_pages.add(page_name)
@@ -850,8 +850,8 @@ def render_concept_map(entries: list[tuple[str, str, str]]) -> str:
    lines = [
        "# TSL 概念地图",
        "",
-        "把自然语言需求映射到该查哪个 TSL 概念，随后仍用 `--query` 取精确语法。",
-        "本清单不含语法细节，也不替代 lookup；用命中专题里的关键语法词组成查询。",
+        "把自然语言需求映射到该查哪个 TSL 概念，随后仍用 --query 获取候选、用 --section 取回事实正文。",
+        "本清单不含可照写语法，也不替代精确章节取回。",
    ]
    for page_name, page_title, summary in entries:
        lines.extend(["", f"## {page_title}", "", summary])