📝 docs(tsl-syntax): design lookup logic hardening
This commit is contained in:
@@ -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` 文档树。
|
||||
Reference in New Issue
Block a user