8.9 KiB
8.9 KiB
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。
- Skill 包不包含
agents/openai.yaml等平台专用适配文件；通用发现元数据只写在SKILL.mdfrontmatter。
非目标
- 不验证 TSL 示例能否编译或运行。
- 不修改正在并发维护的
tsl-api-reference资料、索引或 API 分类。 - 不重写 24 篇参考资料的全部技术内容。
- 不维持旧版
--query的正文输出兼容性。 - 不新增第三方搜索、分词或向量数据库依赖。
用户流程
自然语言起手
- 用户需求尚未映射到 TSL 概念时，运行
lookup.py --map。 - 使用用户原始术语、错误文本和地图提示词执行
lookup.py --query ... --mode ...。 - 查询结果只列出候选的 Section ID、来源页、标题路径、分数、命中理由和短摘要。
- 选择支持当前结论的候选后，用
lookup.py --section <ID>取正文。 - 正文不足、版本不明、需要 API 或项目事实时停止并交接，不从其他语言或模型记忆补全。
混合意图
收到同时包含语法、API、命名、工具链或运行环境的请求时，先拆分事实所有者：
- 语法外形、文件模型、表达式、控制流、对象和 TS-SQL 结构：本 Skill。
- API 名称、签名、参数、返回值、平台 scope 与金融语义：
tsl-api-reference。 - 命名和风格：目标项目文档。
- 执行命令、解释器和环境：最近的
AGENTS.md、项目脚本或 CI。
询问“如何运行”与实际执行 TSL 一样，必须读取最近的项目指引。不同所有者给出的事实不能直接拼接成“可运行”结论；API scope 与目标解释器兼容性缺失时必须停止。
CLI 输出契约
--query
输出固定结构：
# 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、公式/策略脚本和常见语法报错触发词。 - 不新增 OpenAI、Claude、Gemini 等平台专用元数据；各运行时直接读取通用 frontmatter。
- 主流程只展示两阶段检索命令。
- 增加安全传参要求：不得未经引用把用户文本拼进 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文档树。