From da72d3f28c3d4768c28e55814eaf4f01a9c3c2b0 Mon Sep 17 00:00:00 2001
From: csh <caoshenghui@tinysoft.com.cn>
Date: Sun, 12 Jul 2026 11:29:41 +0800
Subject: [PATCH] :memo: docs(tsl-syntax): design lookup logic hardening

---
 ...syntax-reference-logic-hardening-design.md | 192 ++++++++++++++++++
 1 file changed, 192 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-07-12-tsl-syntax-reference-logic-hardening-design.md

diff --git a/docs/superpowers/specs/2026-07-12-tsl-syntax-reference-logic-hardening-design.md b/docs/superpowers/specs/2026-07-12-tsl-syntax-reference-logic-hardening-design.md
new file mode 100644
index 00000000..29f5c61a
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-12-tsl-syntax-reference-logic-hardening-design.md
@@ -0,0 +1,192 @@
+# TSL Syntax Reference 文档逻辑强化设计
+
+## 背景
+
+`tsl-syntax-reference` 已经形成清晰的单入口结构，但当前 `--query` 会直接返回整段正文。自然语言查询容易召回大节、输出数万字节，并把用户查询原样混入 Markdown。语法资料还会展示 API 调用，现有边界没有充分区分“语法外形示例”和“API 可用性事实”。
+
+本设计选择破坏式升级，不保留旧查询输出协议。目标是让 Skill 默认采用“紧凑检索候选 → 精确取回章节”的两阶段流程，并把事实边界、自然语言映射和维护校验收紧为可测试契约。
+
+## 目标
+
+- `--query` 默认只输出紧凑候选，不再输出章节正文。
+- `--section` 是唯一正文取回入口。
+- 用户查询永远作为不可信数据转义，不得改变输出结构。
+- 改善中文口语、同义词、短 ASCII 关键字和混合查询的召回质量。
+- 索引 H2、H3、H4，使具体反例可精确取回。
+- Section ID 对符号标题稳定且无静默冲突。
+- 明确语法示例中的 API 调用不拥有 API 签名、环境 scope 或可用性事实。
+- 概念地图只表达自然语言职责，不输出链接、代码或可照写语法。
+- `--check` 覆盖每页职责、标题层级、Section ID、代码块身份和地图完整性。
+- 用 Python 和文档测试验证全部改动，不运行 TSL。
+
+## 非目标
+
+- 不验证 TSL 示例能否编译或运行。
+- 不修改正在并发维护的 `tsl-api-reference` 资料、索引或 API 分类。
+- 不重写 24 篇参考资料的全部技术内容。
+- 不维持旧版 `--query` 的正文输出兼容性。
+- 不新增第三方搜索、分词或向量数据库依赖。
+
+## 用户流程
+
+### 自然语言起手
+
+1. 用户需求尚未映射到 TSL 概念时，运行 `lookup.py --map`。
+2. 使用用户原始术语、错误文本和地图提示词执行 `lookup.py --query ... --mode ...`。
+3. 查询结果只列出候选的 Section ID、来源页、标题路径、分数、命中理由和短摘要。
+4. 选择支持当前结论的候选后，用 `lookup.py --section <ID>` 取正文。
+5. 正文不足、版本不明、需要 API 或项目事实时停止并交接，不从其他语言或模型记忆补全。
+
+### 混合意图
+
+收到同时包含语法、API、命名、工具链或运行环境的请求时，先拆分事实所有者：
+
+- 语法外形、文件模型、表达式、控制流、对象和 TS-SQL 结构：本 Skill。
+- API 名称、签名、参数、返回值、平台 scope 与金融语义：`tsl-api-reference`。
+- 命名和风格：目标项目文档。
+- 执行命令、解释器和环境：最近的 `AGENTS.md`、项目脚本或 CI。
+
+询问“如何运行”与实际执行 TSL 一样，必须读取最近的项目指引。不同所有者给出的事实不能直接拼接成“可运行”结论；API scope 与目标解释器兼容性缺失时必须停止。
+
+## CLI 输出契约
+
+### `--query`
+
+输出固定结构：
+
+```text
+# TSL Syntax Candidates
+
+Mode: `write`
+Query: "已转义的单行 JSON 字符串"
+
+## Candidate 1
+Score: 80
+Section ID: `...`
+Source: `references/05_functions_and_calls.md`
+Heading: `可直接照写示例 > 基础函数 / 过程骨架`
+Why: `标题命中：函数；代码词命中：function`
+Summary: 一行纯文本摘要。
+```
+
+约束：
+
+- 不包含正文、代码围栏或绝对文件路径。
+- Query 使用 JSON 字符串编码，换行和控制字符不可生成 Markdown 结构。
+- 默认最多五个候选，仍允许 `--limit 1..10`。
+- 没有候选时 stderr 输出明确缺口并返回 2。
+- `write` 模式把两个必要前置章节作为候选置顶并标记 `Required: yes`，不展开正文。
+
+### `--section`
+
+- 返回一个完整章节正文及逻辑来源路径。
+- 不接受 `--mode`。
+- 找不到时返回 2 并列出最相近的 Section ID。
+
+### `--map`
+
+- 每个参考页恰好一条职责摘要。
+- 摘要必须是纯文本，不含 Markdown 链接、行内代码、代码围栏或可直接执行的完整语法。
+- 地图只帮助选择查询概念，不能作为生成代码的事实来源。
+
+## 检索设计
+
+### 分词与规范化
+
+- 继续使用 Unicode NFKC 和大小写折叠。
+- ASCII 标识符按完整 token 匹配，不使用任意子串匹配；`if` 不得命中 `TIniFile` 或 `ifCache`。
+- 中文保留连续词和二元词，但过滤高频口语停用词。
+- 维护一个小型、显式、可测试的领域同义词表，例如：
+  - `打印`、`打出来` → `输出`、`writeLn`
+  - `左连接` → `左联接`、`left join`
+  - `列表` → `数组`
+  - `复用文件` → `.tsf`、`unit`
+  - `性能瓶颈` → `计时`、`profiler`
+- 同义词只用于召回，不作为 TSL 事实输出。
+
+### 索引粒度
+
+- 建立 H2/H3/H4 层级栈，不再只索引 H2/H3。
+- H2/H3 聚合节仍可被检索，但候选优先选择更深、更具体的命中。
+- 同一页默认最多保留两个候选，避免五个名额被同一专题占满。
+- 标题精确命中、代码标识符命中、页标题命中和正文命中分别计分；输出实际排序所依据的总分。
+
+### Section ID
+
+- 标题符号在 slug 前显式编码：`*`、`**`、`[]` 等得到不同稳定片段。
+- 同一页生成相同 ID 时，`--check` 直接失败，不再按出现顺序静默追加 `-2`。
+- ID 由相对页名和完整标题路径组成；来源只显示 `references/<page>.md`。
+
+## 事实边界
+
+参考页可以在语法示例中使用 API 名称作为占位或观察手段，但必须遵守：
+
+- 示例只证明调用在该语法结构中的外形，不证明 API 的签名、返回值、平台 scope 或目标解释器可用性。
+- 需要依赖 API 结论时，答案必须重新查询 `tsl-api-reference`。
+- 参考页不得把 API 参数规格或平台分类声明为本 Skill 独占事实。
+- 输出、缓存、矩阵和运行时服务等现有交叉内容，通过 Skill 总边界和相关页面的局部说明统一澄清；本次不批量迁移 API 条目。
+
+## SKILL.md 与发现元数据
+
+- frontmatter 补充 `Tinysoft`、`天软`、`TS-SQL`、公式/策略脚本和常见语法报错触发词。
+- 主流程只展示两阶段检索命令。
+- 增加安全传参要求：不得未经引用把用户文本拼进 shell。
+- 增加混合意图检查表和 API scope × 解释器兼容性阻断条件。
+- “执行 TSL 前读取项目指引”扩展为“询问或执行 TSL 运行方式时”。
+- 保留五种代码块身份，但明确“可直接照写”只描述源码外形，不等于目标环境验证通过。
+
+## 校验设计
+
+`--check` 新增以下失败条件：
+
+- 参考页缺少唯一 H1。
+- 参考页缺少且仅缺少一个非空 `## 本篇职责`。
+- 概念地图页数与参考页数不一致。
+- Section ID 冲突。
+- 标题层级从 H2/H3/H4 非法跳级。
+- 地图摘要包含 Markdown 链接、代码围栏或为空。
+- 查询前置章节锚点缺失。
+
+现有代码块身份、围栏闭合、本地链接和人工路由协议检查继续保留。
+
+## 测试策略
+
+严格采用 RED → GREEN → REFACTOR，不运行 TSL。
+
+### 查询与安全
+
+- 查询中的换行、Markdown 标题、围栏和控制字符不能改变输出结构。
+- `--query` 输出不含章节正文、代码围栏或绝对路径。
+- `--section` 仍返回完整正文。
+- `if` 只命中独立关键字，不命中 `TIniFile`/`ifCache`。
+- “数据库左连接”召回 TS-SQL；“打出来”召回基础输出/函数示例。
+
+### 自然语言矩阵
+
+- 固化当前 24 条专题矩阵。
+- 最低门槛：Top-1 不低于 20/24，Top-5 为 24/24。
+- 对五个当前漏召回专题建立独立回归测试。
+- 增加混合意图、英文、错别字和 API 交接场景。
+
+### 结构与文档
+
+- 每页职责、H4 索引、符号 slug、ID 冲突和地图纯文本都有失败测试。
+- frontmatter 覆盖中英文发现关键词。
+- SKILL.md 必须明确两阶段检索、安全传参、事实边界和无 TSL 验证要求。
+
+## 迁移与发布
+
+- 这是明确的破坏式 CLI 变更；仓库内测试、评测说明和调用示例同步更新。
+- 不增加兼容开关、旧输出模式或弃用期。
+- 构建与安装流程继续复制同一 Skill 目录，不增加运行时依赖。
+- 验证命令仅包含 `lookup.py --check`、Python 单元/结构测试和相关构建/安装测试。
+
+## 验收标准
+
+- 所有新增测试先观察到预期失败，再由最小实现修复。
+- 24 条自然语言矩阵达到 Top-1 ≥ 20、Top-5 = 24。
+- 注入复现用例不再产生伪造 Markdown 标题或围栏。
+- 默认查询输出不超过 8KB，且不包含正文代码块。
+- 24 个参考页全部进入纯文本概念地图。
+- 目标 Skill、测试和路由文档通过 Python/文档校验。
+- 全程不运行 TSL，不修改 `tsl-api-reference` 文档树。