From 296ea0fc400623223e1a6bd20b3dd93997764791 Mon Sep 17 00:00:00 2001 From: csh Date: Wed, 8 Jul 2026 12:49:31 +0800 Subject: [PATCH] :memo: docs(tsl): apply README review fixes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - builtin 分类 12 类 -> 10 类，注明 finance/market 空壳类目并纳入分类治理方向 - 首跳 mermaid 拆分「写代码 / 查语法」两条边，与 docs/tsl/index.md 实际路由一致 - TOC 补齐第二部分各小节锚点；Token 高效改标为设计目标（估算） - 目录树补 scripts/ 存档行；对照说明记录第一轮产出加 _claude 后缀的改名 - 横向对比「5/5」改为「skill 逐一查证 5/5」统一口径 Co-Authored-By: Claude Fable 5 --- README.md | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index aa016a32..60ad2f0e 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,11 @@ _让 AI 写对 TSL —— 不靠"像 Pascal"的猜测，只靠可核对的文档 - [目录结构](#目录结构) - [后续升级方向](#后续升级方向) - 👤 **第二部分 · 实际场景**（用户视角） - - [同一条提示词 · 多环境实测](#统一提示词) + - [统一提示词](#统一提示词) + - [第一轮实测：Claude Code · Fable 5](#第一轮实测claude-code--fable-5) + - [第二轮实测：Codex CLI · GPT-5.5](#第二轮实测codex-cli--gpt-55) + - [第三轮实测：Qwen 3.6-27B](#第三轮实测qwen-36-27b) + - [横向对比](#横向对比) --- @@ -54,14 +58,14 @@ _让 AI 写对 TSL —— 不靠"像 Pascal"的猜测，只靠可核对的文档 ### 核心理念 -整个 playbook 建立在四条铁律之上，它们贯穿所有文档： +整个 playbook 建立在四条原则之上，贯穿所有文档——前三条是写进 `AGENTS.md` 的硬约束铁律，第四条是架构设计目标： | 原则 | 含义 | | :-- | :-- | | 🚫 **禁止发明语法** | 无文档结论、文件模型不明或执行事实缺失时，**停止并确认**，绝不用 Pascal / Python / JS 的相似写法补全。 | | 🎯 **首跳路由** | 任何 TSL 需求，第一跳统一进唯一入口，由入口分流到具体页，**不全目录搜索、不凭空猜路径**。 | | 🧱 **块级证据** | 页面级元数据只做粗判断；落代码时以块级 `代码块身份` 为准 —— 只有标注 `可直接照写示例` 的代码块能当源码外形照抄。 | -| 💾 **Token 高效** | 分层索引 + 按需检索，相比通读全部文档可节省 **80–90%** 上下文开销。 | +| 💾 **Token 高效** | 分层索引 + 按需检索，相比通读全部文档估算可节省 **80–90%** 上下文开销。 | ### 架构设计 @@ -131,7 +135,7 @@ python skills/tsl-api-reference/scripts/lookup.py --kw 数组 排序 | 来源 | 分类 | 覆盖 | | :-- | :--: | :-- | -| **builtin**（语言内置） | 12 类 | math(636) · base(560) · language(441) · external · resource · graphics · document · gui · system … | +| **builtin**（语言内置） | 10 类 | math(636) · base(560) · language(441) · external · resource · misc · graphics · document · gui · system（另有 finance / market 两个空壳类目，暂无函数） | | **dotnet**（数据仓库） | 21 类 | sector(2405) · equity(1967) · fund(1561) · fundamentals · market_data · bond · quant · macro · futures … | Skill 还内置了防幻觉规则：**不从记忆或相似语言推断签名；TSL 名字大小写无关但下划线有意义**，查询时不得删下划线或改成驼峰。 @@ -144,13 +148,15 @@ Skill 还内置了防幻觉规则：**不从记忆或相似语言推断签名； flowchart TD A[用户提示词] --> B{AGENTS.md
硬约束 + 首跳} B -->|需要任何 TSL 事实| C[docs/tsl/index.md
总入口] - C -->|写代码/语言规则| D[syntax/index.md
语法路由] + C -->|写代码：先定文件模型与骨架| Q[syntax/01_quickstart.md
快速落代码] + C -->|查语法/语言规则| D[syntax/index.md
语法路由] C -->|取金融数据/查函数| E[tsl-api-reference
Skill] C -->|模块集成| F[modules/index.md] C -->|命名/风格| G[naming.md /
code_style.md] D --> H[24 个语法专题] E -->|已知名 --name
未知名 --kw| I[12455 条索引] - H --> Z[✅ 落 .tsl / .tsf 代码] + Q --> Z[✅ 落 .tsl / .tsf 代码] + H --> Z I --> Z F --> Z @@ -178,6 +184,7 @@ playbook/ │ │ ├── ... # ├─ 函数/类/控制流/矩阵/TS-SQL... │ │ └── 24_object_overloads... # └─ 算符与遍历重载 │ └── modules/ # 模块集成：pyTSL / 回测 / 微信 +├── scripts/ # 第二部分三轮实测产出的 .tsl 存档 └── skills/ └── tsl-api-reference/ # 函数检索 Skill ├── SKILL.md # ├─ 触发说明 @@ -199,7 +206,7 @@ playbook 目前已覆盖语法、函数、模块三大知识面，下一步按 - **证据随迁不走样** — `可直接照写示例` 等块级身份标注要在目录搬迁后保持有效、不失链。 **🗂 分类治理 · codegen 归类校准与全量可用性核验** -- **方向** — 复核 codegen 母本（builtin 12 类 / dotnet 21 类）的函数归类，纠正错分与 `misc` 兜底堆积（如 `equity/misc.md` 单页已累至 9252 行、759 个函数），让类目边界清晰；并对全部 12455 个函数逐一探针实测，给每个函数标注真实可用性状态。 +- **方向** — 复核 codegen 母本（builtin 10 类 / dotnet 21 类）的函数归类，纠正错分与 `misc` 兜底堆积（如 `equity/misc.md` 单页已累至 9252 行、759 个函数），填充或裁撤 builtin `finance` / `market` 两个空壳类目，让类目边界清晰；并对全部 12455 个函数逐一探针实测，给每个函数标注真实可用性状态。 - **目的** — 一方面让 `--kw` 关键词检索落在符合直觉的类目、候选更准；另一方面用实测的「可用 / 真缺失 / 参数不对」三态，取代"索引里有就默认能用"的假设，从源头杜绝把不可用函数写进生成代码。 - **难点** - **重分类无生成器** — codegen 生成脚本只剩 `.pyc`，母本 md 已是产物；重新归类只能直接改 md 母本与 routes 并同步维护索引一致性，不能再靠重跑生成器。 @@ -388,7 +395,7 @@ end; | 观察维度 | Claude Code · Fable 5 | Codex CLI · GPT-5.5 | Qwen 3.6-27B | | :-- | :-- | :-- | :-- | | Skill 接入 | 已注册，直接调用 | 未注册 → 循路由自行找到 `lookup.py` 手动调用 | 未注册 → 手动调用（检索输出乱码，带病工作） | -| 函数真实性 | 5/5 全部查证，零编造 | 全部查证，并依据文档负向记录弃用 `getTopN` | 全部查证；面对 `StockZf_No` 文档缺口拒绝编参数，绕路重来 | +| 函数真实性 | skill 逐一查证 5/5，零编造 | 全部查证，并依据文档负向记录弃用 `getTopN` | 全部查证；面对 `StockZf_No` 文档缺口拒绝编参数，绕路重来 | | 交易日处理 | `lastTradeDay` 取最近交易日，周一跑正确落上周五 | `yesterday()` 日历昨天，逢周末可能取到无行情日 | `yesterday()` 与 `dt-1` 全日历日，三轮中最弱 | | 文件模型 | `.tsl` 判定正确 | `.tsl`（提示词给定文件名） | `.tsl`（提示词给定文件名） | | 自主验证 | 本机解释器实测 builtin 跑通、整文件编译通过 | 环境无解释器，静态检查 | 仅回读文件自查，无静态/运行验证 | @@ -397,7 +404,7 @@ end; | 总耗时 | 16m57s | 9m21s | 未记录 | | token | 自估：输入 15–20 万 / 输出 0.5–1 万 | 实测：18.5 万 = 15.9 万入 + 2.57 万出 | 自估：约 1.5–2.5 万（未计上下文重复，口径偏小） | -> **对照说明：** ① 第二、三轮提示词在第一轮基础上各自追加了输出文件名，文件命名被显式给定；② 第二轮运行时仓库内已有本 README 的同题示例，模型读到过该片段（其后仍逐一核对了函数事实）；③ 三轮本地条件不同——第一轮机器装有离线 TSL 解释器，第二轮 PATH 无解释器，第三轮未尝试任何运行验证；④ 第三轮的代理框架与耗时未记录，token 为模型按"内容量"事后自估、未计多轮上下文重复携带——三轮 token 口径各不相同（实测 / 含缓存自估 / 内容量自估），不可直接横比。以上数字与行为仅作真实记录，不构成严格受控对比。 +> **对照说明：** ① 第二、三轮提示词在第一轮基础上各自追加了输出文件名，文件命名被显式给定；第一轮产出原名 `main_board_top50_zf.tsl`，存档时加 `_claude` 后缀以区分三轮；② 第二轮运行时仓库内已有本 README 的同题示例，模型读到过该片段（其后仍逐一核对了函数事实）；③ 三轮本地条件不同——第一轮机器装有离线 TSL 解释器，第二轮 PATH 无解释器，第三轮未尝试任何运行验证；④ 第三轮的代理框架与耗时未记录，token 为模型按"内容量"事后自估、未计多轮上下文重复携带——三轮 token 口径各不相同（实测 / 含缓存自估 / 内容量自估），不可直接横比。以上数字与行为仅作真实记录，不构成严格受控对比。 ---