csh/playbook
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

📝 docs(tsl): align README with syntax skill, restructure roadmap as part-3

Browse Source 
- rewrite part-1 to reflect tsl-syntax-reference skill (lookup retrieval, layered table, dual-skill routing)
- fix fabricated section ID in README and SKILL.md examples (verified via --section)
- trim block-identity table, api-reference counts, and stale compare-phrasing
- promote roadmap to standalone part-3 with four directions incl. Agent Loop (planned)
- add deployment section (per-agent skills dirs) and AGENT_PRIMER.md primer

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
csh
2026-07-14 09:09:58 +08:00
co-authored by Claude Opus 4.8
parent c4d1efe02c
commit efd4b8e421
3 changed files with 345 additions and 143 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENT_PRIMER.md
+189
View File
@@ -0,0 +1,189 @@
# Agent 科普：Skill、Prompt 与 Loop
> 读懂 TSL Playbook 前的 5 分钟预备知识
很多人已经会用 AI 对话：输入一个问题，等待模型回答。但 **Agent（智能代理）不只是“更会聊天的模型”**。它能够读取资料、调用工具、观察结果，并根据任务进度继续行动。
要理解这种工作方式，先认识三个概念：
- **Skill**：Agent 处理某类任务时会打开的“说明书”。
- **Prompt**：某一次模型调用收到的任务、规则和上下文。
- **Loop**：让 Agent 根据真实反馈持续行动的控制机制。
---
## 第一部分：Skill —— 给 Agent 一套专业工作方法
### 什么是 Skill？
先看一个生活中的例子。
你让一个会做饭的人做红烧肉。如果只告诉他菜名，他可能会凭经验去做；如果再给他一张可靠的菜谱，上面写着要准备什么、先做什么、火候多大以及出问题时怎么办，他就更容易稳定地做好这道菜。
**对 Agent 来说，Skill 就像这张菜谱。** 它不是任务的最终答案，而是一份“怎样完成这类任务”的说明。它通常会告诉 Agent：
- 哪类任务要打开它；
- 第一步做什么，接下来做什么；
- 不确定时去哪里查；
- 可以使用哪些工具；
- 什么情况下应该停下来询问用户。
Skill 不会让模型突然变得更聪明，也不会改变模型本身。它只是让 Agent 在处理某类任务时有步骤可循、知道去哪里查，尽量少靠猜。
### Agent 什么时候会使用 Skill？
Agent 不会把所有 Skill 一直“摊在桌面上”。它通常先看一份简短目录，知道有哪些 Skill、每个 Skill 适合做什么。收到任务后，如果出现下面的情况，才会打开对应的 Skill：
- 用户明确点名某个 Skill；
- Agent 发现当前任务正好符合某个 Skill 的用途；
- 系统或项目规则要求这类任务必须使用指定 Skill。
这个动作发生在 Agent 真正回答或开始操作之前。同一个任务做到不同阶段时，也可能需要打开不同的 Skill。
打开 Skill 后，Agent 会照着里面的步骤工作，需要时再去查询资料或使用工具。
### Skill 如何工作？
```mermaid
flowchart LR
A([用户提出任务]) --> B[看看有哪些 Skill]
B --> C{找到合适的<br/>Skill 了吗}
C -->|用户点名 / 任务匹配 / 规则要求| D[打开对应 Skill]
D --> E[按照步骤工作]
E --> F[需要时查资料<br/>或使用工具]
F --> G([完成任务])
C -->|没有| H[用通用能力处理]
H --> G
classDef start fill:#e8f3f8,stroke:#2b7489,color:#173b48,stroke-width:2px;
classDef decision fill:#fff4dc,stroke:#c88719,color:#5b3a00,stroke-width:2px;
classDef skill fill:#f0eafd,stroke:#8250df,color:#3f2675,stroke-width:2px;
classDef action fill:#eaf2fd,stroke:#3178c6,color:#173f73,stroke-width:2px;
classDef done fill:#e8f6ec,stroke:#2ea043,color:#175c2d,stroke-width:2px;
class A start;
class C decision;
class B,D skill;
class E,F,H action;
class G done;
```
以 TSL Playbook 中的 `tsl-syntax-reference` 为例：当用户要求编写或解释 TSL 代码时，Agent 会先打开这个 Skill，按照里面的说明查询 TSL 语法资料，确认正确写法后再生成代码，而不是因为“TSL 看起来像 Pascal”就凭经验猜。
这个例子体现了 Skill 的核心价值：
> **Skill 不替 Agent 完成任务，而是告诉 Agent 如何更可靠地完成某一类任务。**
简单来说，**Skill 负责告诉 Agent“这类事情应该怎么做”**。任务发生变化时，Agent 可以在后续步骤中再使用新的 Skill。
---
## 第二部分：Prompt + Loop —— 从一次回答到持续完成任务
### Prompt 是什么？
Prompt 是一次模型调用所接收的输入，可能包括：
- 用户当前提出的任务；
- 系统规定的角色与行为边界；
- 已有的对话和执行历史；
- 工具返回的结果；
- 当前任务状态和剩余目标。
因此，**Prompt 不是模型调用本身，而是这次调用所使用的任务说明和上下文**。
一次性的 Prompt 通常是：用户输入任务，模型给出回答，然后结束。如果任务需要读取文件、修改代码、运行测试并根据报错继续修复，仅靠一次回答往往不够，这时就需要 Loop。
### 一次性 Prompt 与 Agent Loop 有什么不同？
```mermaid
flowchart LR
subgraph ONE[一次性 Prompt]
direction TB
P1[输入任务] --> P2[模型回答] --> P3([结束])
end
subgraph LOOP[Agent Loop]
direction TB
L1[设定目标] --> L2[观察当前状态]
L2 --> L3[决定下一步]
L3 --> L4[行动或调用工具]
L4 --> L5[更新状态]
L5 --> L6{目标完成了吗}
L6 -->|没有| L2
L6 -->|完成| L7([输出结果])
end
classDef prompt fill:#eaf2fd,stroke:#3178c6,color:#173f73,stroke-width:2px;
classDef loop fill:#f0eafd,stroke:#8250df,color:#3f2675,stroke-width:2px;
classDef decision fill:#fff4dc,stroke:#c88719,color:#5b3a00,stroke-width:2px;
classDef done fill:#e8f6ec,stroke:#2ea043,color:#175c2d,stroke-width:2px;
class P1,P2,L1 prompt;
class L2,L3,L4,L5 loop;
class L6 decision;
class P3,L7 done;
```
Loop 可以由用户手动推进，例如模型回答后，用户再说一句“继续”。在真正的 Agent 系统中，Loop 通常由外部程序管理：程序反复调用模型、执行工具并更新状态，直到任务完成、需要用户确认、发生错误或达到执行上限。
### Agent Loop 如何工作？
```mermaid
flowchart TD
A([用户给出目标]) --> B[读取当前状态]
B --> C[组装本轮 Prompt]
C --> D[调用模型]
D --> E{下一步是什么}
E -->|调用工具| F[执行工具]
F --> G[获得观察结果]
G --> H[更新状态与上下文]
H --> I{目标是否完成}
I -->|尚未完成| C
I -->|已经完成| J[验证结果]
E -->|可以直接完成| J
E -->|需要授权| K[请求用户确认]
K --> H
J -->|未通过| H
J -->|通过| L([输出结果并结束])
classDef start fill:#e8f3f8,stroke:#2b7489,color:#173b48,stroke-width:2px;
classDef prompt fill:#eaf2fd,stroke:#3178c6,color:#173f73,stroke-width:2px;
classDef model fill:#f0eafd,stroke:#8250df,color:#3f2675,stroke-width:2px;
classDef action fill:#fff4dc,stroke:#c88719,color:#5b3a00,stroke-width:2px;
classDef state fill:#f8eee7,stroke:#c96832,color:#6e2f10,stroke-width:2px;
classDef done fill:#e8f6ec,stroke:#2ea043,color:#175c2d,stroke-width:2px;
class A start;
class B,C prompt;
class D,E model;
class F,K action;
class G,H,I,J state;
class L done;
```
这里最容易误解的一点是：**Prompt 和 Loop 不是二选一，Prompt 就在 Loop 里面。**
Agent 每执行一轮，都会把新的观察结果和任务状态加入上下文，再组装下一轮 Prompt：
```text
Prompt 1 → 模型决策 → 执行工具 → 获得结果
↓
Prompt 2（加入新结果）← 更新任务状态
```
模型负责判断“下一步做什么”，外部程序负责真正运行 Loop、执行工具、保存状态和检查停止条件。模型本身不会在没有再次调用的情况下无限运行。
---
## 最后记住三句话
| 概念 | 一句话理解 |
| :--------- | :---------------------------------------------- |
| **Skill** | 为 Agent 提供某个领域可重复使用的专业工作方法。 |
| **Prompt** | 告诉模型这一轮知道什么、遵守什么、要做什么。 |
| **Loop** | 让 Agent 根据执行反馈不断决定下一步，直到停止。 |
三者组合起来，Agent 才能从“回答一个问题”进化为“持续完成一个任务”：
> **Skill 提供专业方法，Prompt 描述当前一步，Loop 推动任务向前。**
README.md
+155 -142
View File
@@ -10,7 +10,8 @@ _让 AI 写对 TSL —— 不靠"像 Pascal"的猜测，只靠可核对的文档
![docs](https://img.shields.io/badge/语法专题-24_篇-2b7489)
![funcs](https://img.shields.io/badge/函数索引-12455_条-3178c6)
![skill](https://img.shields.io/badge/Agent_Skill-tsl--api--reference-8250df)
![skill](https://img.shields.io/badge/Skill-tsl--syntax--reference-8250df)
![skill](https://img.shields.io/badge/Skill-tsl--api--reference-8250df)
![modules](https://img.shields.io/badge/模块集成-pyTSL_·_回测_·_微信-e37933)
</div>
@@ -24,7 +25,7 @@ _让 AI 写对 TSL —— 不靠"像 Pascal"的猜测，只靠可核对的文档
- [核心理念](#核心理念)
- [架构设计](#架构设计)
- [目录结构](#目录结构)
- [后续升级方向](#后续升级方向)
- 📦 **部署**：把 skill 装到不同 AI Agent
- 👤 **第二部分 · 多环境实测**（用户视角）
- [统一提示词](#统一提示词)
- [第一轮实测：Claude Code · Fable 5](#第一轮实测claude-code--fable-5)
@@ -32,6 +33,7 @@ _让 AI 写对 TSL —— 不靠"像 Pascal"的猜测，只靠可核对的文档
- [第三轮实测：Qwen 3.6-27B](#第三轮实测qwen-36-27b)
- [横向对比](#横向对比)
- [三轮小结](#三轮小结)
- 🔭 **第三部分 · 后续升级方向**（演进视角）
---
@@ -39,7 +41,7 @@ _让 AI 写对 TSL —— 不靠"像 Pascal"的猜测，只靠可核对的文档
## 🛠 第一部分 · 技术路径
**开发者视角 —— playbook 是什么、如何搭建、往哪演进**
**开发者视角 —— playbook 是什么、如何搭建**
</div>
@@ -49,7 +51,7 @@ _让 AI 写对 TSL —— 不靠"像 Pascal"的猜测，只靠可核对的文档
**TSL**（天软语言）是天软金融分析平台的专用编程语言，语法接近 Pascal，内置海量金融数据仓库函数（行情、财务、板块、选股、回测等）。它的三个特点，让通用大模型很容易写错：
- **语法冷门** —— 赋值用 `:=`、类定义要写 `type Name = class ... end;`、`.tsl` 有严格的"语句区在前、声明区在后"规则，与主流语言的直觉直接冲突。
- **语法冷门** —— 类定义要写成 `type Name = class ... end;`、内嵌 TS-SQL 的类 SQL 语句，大模型很容易踩坑。
- **函数量巨大** —— 数据仓库函数上万个，签名各异，模型凭记忆一定会编造参数。
- **文件模型敏感** —— `.tsl`（可执行脚本）与 `.tsf`（可复用声明）选错就直接编译失败。
@@ -61,68 +63,57 @@ _让 AI 写对 TSL —— 不靠"像 Pascal"的猜测，只靠可核对的文档
整个 playbook 建立在四条原则之上，贯穿所有文档——前三条是写进 `AGENTS.md` 的硬约束铁律，第四条是架构设计目标：
| 原则 | 含义 |
| :-- | :-- |
| 🚫 **禁止发明语法** | 无文档结论、文件模型不明或执行事实缺失时，**停止并确认**，绝不用 Pascal / Python / JS 的相似写法补全。 |
| 🎯 **首跳路由** | 任何 TSL 需求，第一跳统一进唯一入口，由入口分流到具体页，**不全目录搜索、不凭空猜路径**。 |
| 🧱 **块级证据** | 页面级元数据只做粗判断；落代码时以块级 `代码块身份` 为准 —— 只有标注 `可直接照写示例` 的代码块能当源码外形照抄。 |
| 💾 **Token 高效** | 分层索引 + 按需检索，相比通读全部文档估算可节省 **80–90%** 上下文开销。 |
| 原则 | 含义 |
| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🚫 **禁止发明语法** | 无文档结论、文件模型不明或执行事实缺失时，**停止并确认**，绝不用 Pascal / Python / JS 的相似写法补全。 |
| 🎯 **首跳路由** | 任何 TSL 需求都从 `AGENTS.md` 常驻闸门起步，语法找 `tsl-syntax-reference`、函数找 `tsl-api-reference`、其余回 `docs/tsl/index.md` 分流，**不全目录搜索、不凭空猜路径**。 |
| 🧱 **块级证据** | 候选摘要与概念地图只做粗判断；落代码时以 `--section` 正文里紧邻代码围栏的 `代码块身份` 为准 —— 只有标注 `可直接照写示例` 的块能当源码外形照抄。 |
| 💾 **Token 高效** | 分层索引 + 两段式按需检索，只把命中当前任务的事实载入上下文，不整包灌文档。 |
### 架构设计
playbook 是一个金字塔式的知识结构：顶部是**极简的硬约束**，中部是**分层的事实文档**，底部是**可执行的检索工具**。下面四小节自顶向下逐层拆解，最后由「首跳路由」把各层串成一条完整链路。
playbook 分三类构件：常驻的**硬约束**（`AGENTS.md`）、**分层的事实源**（语法与函数已外置为可分发的 skill，命名 / 风格 / 模块仍留在 `docs/` 文件里）、以及 skill 内**可执行的检索工具**（`lookup.py`）。下面先按事实源的职责分层，再逐一拆解两个 skill 的检索方式，最后由「首跳路由」把三类构件串成一条完整链路。
#### 分层知识库
文档按**职责**而非按目录平铺组织，每一层只回答自己那一层的问题：
| 层 | 位置 | 负责回答 | 不负责 |
| :-- | :-- | :-- | :-- |
| **硬约束层** | `AGENTS.md` | 铁律、首跳、阻断条件 | 完整语法（故意不复写） |
| **语法事实层** | `docs/tsl/syntax/` | 语言规则、文件模型、控制流、类、TS-SQL | 具体函数签名 |
| **模块集成层** | `docs/tsl/modules/` | pyTSL、策略回测、微信通知 API | 纯语法、通用取数 |
| **风格偏好层** | `code_style.md` `naming.md` | 命名与组织偏好 | 语法事实（明确声明"仅偏好"） |
| **函数事实层** | `tsl-api-reference` skill | 12455 个函数的名字 / 签名 / 参数 / 返回值 | 语言语法 |
| 层 | 载体 | 负责回答 | 不负责 |
| :------------- | :-------------------------------------- | :---------------------------------------- | :--------------------------- |
| **硬约束层** | `AGENTS.md`（仓库文件） | 铁律、首跳、阻断条件 | 完整语法（故意不复写） |
| **语法事实层** | `tsl-syntax-reference`（外置 skill） | 语言规则、文件模型、控制流、类、TS-SQL | 具体函数签名 |
| **函数事实层** | `tsl-api-reference`（外置 skill） | 12455 个函数的名字 / 签名 / 参数 / 返回值 | 语言语法 |
| **模块集成层** | `docs/tsl/modules/`（仓库文件） | pyTSL、策略回测、微信通知 API | 纯语法、通用取数 |
| **风格偏好层** | `code_style.md` `naming.md`（仓库文件） | 命名与组织偏好 | 语法事实（明确声明"仅偏好"） |
每个语法文档页头都带一组**机器可读的元数据**，让代理在读正文前就能判断能否照抄：
语法事实层与函数事实层都封装成 **Agent Skill**：由 `SKILL.md` 的 `description` 被模型模糊触发，正文规定"只经 `lookup.py` 检索、不手工通读参考页"的调用契约。以 `tsl-syntax-reference` 为例，检索分两步——先用 `--query` 拿候选与 Section ID，再用 `--section` 取回唯一事实正文：
```
文档类型：语法主线
是否可直接用于生成代码：是
是否含可直接照写示例：是
是否含不可照写反例：是
遇到不确定时：<指向下一跳的具体页>
```bash
# 第一步：--query 只返回紧凑候选 + Section ID（不含事实正文）
python skills/tsl-syntax-reference/scripts/lookup.py --query "命名参数 默认参数" --mode write
# 第二步：--section 精确取回该章节正文，才是可用的语法事实
python skills/tsl-syntax-reference/scripts/lookup.py --section "05_functions_and_calls--可直接照写示例--默认参数"
```
#### TSL 语法体系
`docs/tsl/syntax/` 用 **24 个专题**覆盖了 TSL 语言的方方面面，从最短骨架到矩阵深潜：
`tsl-syntax-reference` skill 的 `references/` 用 **24 个专题**覆盖了 TSL 语言的方方面面，从最短骨架到矩阵深潜：
| 主题簇 | 专题 |
| :-- | :-- |
| **入门与模型** | `01` 快速落代码 · `02` 文件模型（`.tsl`/`.tsf`）· `03` 值与字面量 · `04` 变量常量 |
| **函数与表达式** | `05` 函数与调用 · `06` 表达式运算符 · `07` 控制流 |
| **对象与模块** | `08` 类与对象 · `09` unit 与作用域 · `24` 算符/遍历重载 |
| **运行时** | `10` 运行时上下文与 with · `15` 调试与性能 · `20` 对象自省 · `21` 内置运行时对象 |
| **数据结构** | `12` 数组与集合 · `22` 矩阵深潜 · `23` FMArray · `13` 结果集过滤 |
| **数据查询** | `14` TS-SQL |
| 主题簇 | 专题 |
| :--------------- | :------------------------------------------------------------------------------------ |
| **入门与模型** | `01` 快速落代码 · `02` 文件模型（`.tsl`/`.tsf`）· `03` 值与字面量 · `04` 变量常量 |
| **函数与表达式** | `05` 函数与调用 · `06` 表达式运算符 · `07` 控制流 |
| **对象与模块** | `08` 类与对象 · `09` unit 与作用域 · `24` 算符/遍历重载 |
| **运行时** | `10` 运行时上下文与 with · `15` 调试与性能 · `20` 对象自省 · `21` 内置运行时对象 |
| **数据结构** | `12` 数组与集合 · `22` 矩阵深潜 · `23` FMArray · `13` 结果集过滤 |
| **数据查询** | `14` TS-SQL |
| **底层与互操作** | `16` 词法与编译选项 · `17` 类型转换 · `18` external/DLL/线程 · `19` namespace/Libpath |
| **避坑** | `11` 高频误写与反例 |
每一页都用**四种块级身份**给代码块打标签，这是"禁止发明语法"落地的关键：
| 代码块身份 | 能否照抄 | 用途 |
| :-- | :--: | :-- |
| ✅ `可直接照写示例` | **能** | 唯一可当源码外形的块 |
| ⚠️ `反例 / 不可照写` | 否 | 展示会编译/运行失败的写法 |
| 📤 `输出片段` | 否 | 只是运行结果 |
| 🔧 `配置片段 / 概念骨架` | 否 | 带 `<占位符>` 的模板 |
> **示例：** 语法页会明确告诉代理，`.tsl` 语句区可以调用后置的函数声明，但**在声明区后再追加脚本语句**是反例 —— 并附上真实报错 `invalid statement` 作为负向边界。
| **避坑** | `11` 高频误写与反例 |
#### tsl-api-reference Skill
上万个数据仓库函数无法塞进上下文，playbook 把它做成一个**可调用的 Agent Skill**：一个 `function_index.tsv`（**12455 条**：2404 个 builtin + 10051 个 dotnet）加一个 `lookup.py` 检索脚本。
上万个数据仓库函数无法塞进上下文，playbook 把它做成一个**可调用的 Agent Skill**：一个 `function_index.tsv` 加一个 `lookup.py` 检索脚本。
```bash
# 已知函数名 → 精确查签名、参数、返回值、示例
@@ -132,61 +123,54 @@ python skills/tsl-api-reference/scripts/lookup.py --name argmax
python skills/tsl-api-reference/scripts/lookup.py --kw 数组 排序
```
检索是**两段式**的：关键词查询先返回候选行（名字 + 一句话摘要），代理挑中后再用 `--name` 拉取该函数的完整文档块。函数文档本身分两大来源：
| 来源 | 分类 | 覆盖 |
| :-- | :--: | :-- |
| **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 名字大小写无关但下划线有意义**，查询时不得删下划线或改成驼峰。
检索是**两段式**的：关键词查询先返回候选行（名字 + 一句话摘要），代理挑中后再用 `--name` 拉取该函数的完整文档块。
#### 首跳路由机制
这是 playbook 最核心的设计。代理面对任何 TSL 需求，都遵循同一条决策链 —— 永远从固定入口开始，逐级收窄，而不是漫无目的地翻文档：
这是 playbook 最核心的设计。`AGENTS.md` 是常驻的硬约束闸门（禁止发明语法、先定文件模型、事实边界与阻断条件始终最先命中）；语法与函数两类事实各自封装成 skill，由 `description` 触发，命中后一律走 `lookup.py` 检索；命名 / 风格 / 模块集成才回到 `docs/tsl/index.md` 分流：
```mermaid
flowchart TD
A[用户提示词] --> B{AGENTS.md<br/>硬约束 + 首跳}
B -->|需要任何 TSL 事实| C[docs/tsl/index.md<br/>总入口]
C -->|写代码：先定文件模型与骨架| Q[syntax/01_quickstart.md<br/>快速落代码]
C -->|查语法/语言规则| D[syntax/index.md<br/>语法路由]
C -->|取金融数据/查函数| E[tsl-api-reference<br/>Skill]
C -->|模块集成| F[modules/index.md]
C -->|命名/风格| G[naming.md /<br/>code_style.md]
D --> H[24 个语法专题]
A[用户提示词] --> B{AGENTS.md<br/>常驻硬约束 + 事实边界}
B -->|语法 / 文件模型 / 控制流| D[tsl-syntax-reference<br/>Skill]
B -->|取金融数据 / 查函数| E[tsl-api-reference<br/>Skill]
B -->|命名 · 风格 · 模块集成| C[docs/tsl/index.md<br/>文档分流]
D -->|--map 冷启动<br/>--query 候选 → --section 正文| H[24 篇语法专题]
E -->|已知名 --name<br/>未知名 --kw| I[12455 条索引]
Q --> Z[✅ 落 .tsl / .tsf 代码]
H --> Z
C -->|命名/风格| G[naming.md /<br/>code_style.md]
C -->|模块集成| F[modules/index.md]
H --> Z[✅ 落 .tsl / .tsf 代码]
I --> Z
F --> Z
G --> Z
style B fill:#2b7489,color:#fff
style C fill:#3178c6,color:#fff
style D fill:#8250df,color:#fff
style E fill:#8250df,color:#fff
style Z fill:#2ea043,color:#fff
```
每个路由表都是**「任务信号 → 入口 → 阻断条件」**三列结构，多行命中时自上而下取第一个，且每一跳都带明确的"什么时候**不**该走这条"的阻断条件，避免过度泛化。
### 目录结构
```
playbook/
├── AGENTS.md # 顶层硬约束：铁律 + 首跳路由（不复写语法）
├── AGENTS.md # 常驻硬约束：铁律 + 事实边界 + fail-closed（不复写语法、不做首跳翻页）
├── docs/tsl/
│ ├── index.md # TSL 总入口：任务 → 文档区分流
│ ├── index.md # 命名/风格/模块的文档分流入口
│ ├── naming.md # 命名偏好（非语法事实）
│ ├── code_style.md # 代码风格偏好（非语法事实）
│ ├── toolchain.md # 工具链与验证命令模板
│ ├── syntax/ # 24 个语法专题 + index.md 路由
│ │ ├── 01_quickstart.md # ├─ 快速落代码 / 最小骨架
│ │ ├── 02_core_model.md # ├─ .tsl / .tsf 文件模型
│ │ ├── ... # ├─ 函数/类/控制流/矩阵/TS-SQL...
│ │ └── 24_object_overloads... # └─ 算符与遍历重载
│ └── modules/ # 模块集成：pyTSL / 回测 / 微信
├── scripts/ # 第二部分三轮实测产出的 .tsl 存档
└── skills/
├── tsl-syntax-reference/ # 语法检索 Skill（原 docs/tsl/syntax/）
│ ├── SKILL.md # ├─ 触发说明 + lookup 调用契约
│ ├── scripts/lookup.py # ├─ 两段式检索脚本（--query/--section/--map）
│ └── references/ # └─ 24 篇语法专题（母本）
│ ├── 01_quickstart.md # ├─ 快速落代码 / 最小骨架
│ ├── 02_core_model.md # ├─ .tsl / .tsf 文件模型
│ ├── ... # ├─ 函数/类/控制流/矩阵/TS-SQL...
│ └── 24_object_overloads# └─ 算符与遍历重载
└── tsl-api-reference/ # 函数检索 Skill
├── SKILL.md # ├─ 触发说明
├── scripts/lookup.py # ├─ 检索脚本
@@ -194,36 +178,27 @@ playbook/
└── references/codegen/ # └─ 函数完整文档块
```
### 后续升级方向
---
playbook 目前已覆盖语法、函数、模块三大知识面，下一步按优先级从高到低，围绕**架构演进、分类治理、覆盖广度、检索质量**四个方向推进：
## 部署
**🧩 架构演进 · 语法层 Skill 化**
- **方向** — 把 `syntax/` 的 24 篇知识页搬进独立 skill 作为 `references/`，由 `SKILL.md` 正文承载「任务信号 → 页 → 阻断条件」的首跳路由表，与 `tsl-api-reference` 对齐成统一的 skill 调用模型；`AGENTS.md` 保留为常驻硬约束闸门。
- **目的** — 让语法与函数两类知识统一走 skill 触发，获得可分发、可移植的标准打包单元，并降低对"先读 `AGENTS.md`、再照链接逐跳"这条隐式流程的依赖。
- **难点**
- **确定性 vs 模糊触发** — 纲领是可审计的有序路由 + 阻断条件，而 skill 靠 `description` 被模型模糊匹配触发；syntax 的"写代码"触发面与 api-reference 的"取数"高度重叠，有序消歧逻辑必须完整保留进 `SKILL.md` 正文，不能退化成模型猜测。
- **常驻不变量** — skill 是被触发的，替代不了 `AGENTS.md`「禁止发明语法 + 先定 `.tsl` / `.tsf` 文件模型」这条必须最先命中的硬约束，须防止自动触发把代理直接拽进语法页、跳过文件模型判断。
- **证据随迁不走样** — `可直接照写示例` 等块级身份标注要在目录搬迁后保持有效、不失链。
两个 skill 都是**自包含目录**（`SKILL.md` + `scripts/` + `references/` 或 `data/`），没有安装器：把目录整个拷进目标 agent 的个人 skills 目录即可，之后由各 agent 按 `SKILL.md` 的 `description` 自动发现、模糊触发。
**🗂 分类治理 · codegen 归类校准与全量可用性核验**
- **方向** — 复核 codegen 母本（builtin 10 类 / dotnet 21 类）的函数归类，纠正错分与 `misc` 兜底堆积（如 `equity/misc.md` 单页已累至 9252 行、759 个函数），填充或裁撤 builtin `finance` / `market` 两个空壳类目，让类目边界清晰；并对全部 12455 个函数逐一探针实测，给每个函数标注真实可用性状态。
- **目的** — 一方面让 `--kw` 关键词检索落在符合直觉的类目、候选更准；另一方面用实测的「可用 / 真缺失 / 参数不对」三态，取代"索引里有就默认能用"的假设，从源头杜绝把不可用函数写进生成代码。
- **难点**
- **重分类无生成器** — codegen 生成脚本只剩 `.pyc`，母本 md 已是产物；重新归类只能直接改 md 母本与 routes 并同步维护索引一致性，不能再靠重跑生成器。
- **可用性须真解释器** — 「可用」无法静态判定，须接真实 TSL 解释器对上万函数逐一探针（`toolchain.md` 的执行入口目前仍是模板占位），规模大、成本高。
- **假阴性要甄别** — 探针报错可能是"函数真缺失"，也可能只是"参数没给对"；两者须隔离区分（`special/pending` vs `special/unknown`），否则会把本可用的函数误标为不可用。
| Agent | 个人 skills 目录 |
| :------------------ | :------------------ |
| Claude Code | `~/.claude/skills/` |
| Codex CLI | `~/.codex/skills/` |
| 通用 `.agents` 约定 | `~/.agents/skills/` |
**📚 覆盖广度**
- 扩充 `modules/`：补充更多平台模块（数据落库、告警渠道、报表导出）的 API 事实页。
- 沉淀**场景配方库**（Recipe）：把"选股 → 回测 → 通知"这类高频端到端流程做成可照写的组合骨架。
- 为常见报错建立**反例 → 正确写法**的快速跳转索引，让避坑更即时。
```bash
# 以 Claude Code 为例，两个 skill 一起装（换成对应目录即可部署到其他 agent）
cp -r skills/tsl-syntax-reference skills/tsl-api-reference ~/.claude/skills/
**🔍 检索质量**
- 为 `function_index.tsv` 增加**参数类型实证**：当前仍有约 2600 个函数（builtin 246 / dotnet 2382）的参数声明为 `any`/`object`，需用 `dataType()` 逐一收紧。
- 引入**语义检索**（embedding），让"我想算个动量因子"这类模糊意图也能命中相关函数。
- 补齐关键词索引的中文近义词，降低 `--kw` 空命中率。
- 修复 `lookup.py` 跨环境输出编码（GBK/UTF-8）：第三轮实测中，乱码直接导致大量重复检索。
# 装好自检：无匹配或非零退出即说明目录不完整
python ~/.claude/skills/tsl-syntax-reference/scripts/lookup.py --check
```
要完整的 TSL 能力，两个 skill 需一起部署——`tsl-syntax-reference` 管语法事实，`tsl-api-reference` 管函数事实，缺一个都会在 `AGENTS.md` 的 fail-closed 规则下触发停止。
---
@@ -235,7 +210,7 @@ playbook 目前已覆盖语法、函数、模块三大知识面，下一步按
</div>
> 这一部分没有虚构：**同一条提示词，投给不同的 AI 编码环境，记录真实行为与产出。** 三轮实测：Claude Code · Fable 5、Codex CLI · GPT-5.5、Qwen 3.6-27B。
> **同一条提示词，投给不同的 AI 编码环境，记录真实行为与产出。** 三轮实测：Claude Code · Fable 5、Codex CLI · GPT-5.5、Qwen 3.6-27B。
### 统一提示词
@@ -257,14 +232,14 @@ playbook 目前已覆盖语法、函数、模块三大知识面，下一步按
**真实过程回放**（每一步都能对应第一部分的机制）：
| 步骤 | 考察点 | 实际行为 |
| :-- | :--: | :-- |
| 🧭 首跳照走 | — | 读 `AGENTS.md` → 进 `docs/tsl/index.md` 总入口 → 按路由取用快速落代码 / 控制流 / 数组集合三个语法页 |
| 🔍 函数全部查证 | ① | 调用 `tsl-api-reference` skill 逐一核实 `getAbkbyDate` · `lastTradeDay` · `stockZf8` · `appendArray` · `sortTableByField` —— **五个函数零编造** |
| 📖 语法照抄有据 | ② | 落码外形——`for ... in` 遍历、`array("Key": value)` 键表、`begin/end` 块——均见于取用三页的「可直接照写示例」，无文档外写法 |
| 📄 文件模型判对 | ③ | 一次性取数任务 → 按规则判为 `.tsl`，文件名自定，存档于 `scripts/main_board_top50_zf_claude.tsl` |
| ✅ 主动验证 | ④ | 本机解释器实测：键表构造、循环截断、排序等 builtin 逻辑全部跑通，整个文件编译通过 |
| 🗣 诚实报告边界 | ⑤ | 数据仓库函数离线环境没有（`function not found`），**如实说明需在天软客户端端到端确认，而不是谎称全部跑通** |
| 步骤 | 考察点 | 实际行为 |
| :-------------- | :----: | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| 🧭 首跳照走 | — | 读 `AGENTS.md` → 进 `docs/tsl/index.md` 总入口 → 按路由取用快速落代码 / 控制流 / 数组集合三个语法页 |
| 🔍 函数全部查证 | ① | 调用 `tsl-api-reference` skill 逐一核实 `getAbkbyDate` · `lastTradeDay` · `stockZf8` · `appendArray` · `sortTableByField` —— **五个函数零编造** |
| 📖 语法照抄有据 | ② | 落码外形——`for ... in` 遍历、`array("Key": value)` 键表、`begin/end` 块——均见于取用三页的「可直接照写示例」，无文档外写法 |
| 📄 文件模型判对 | ③ | 一次性取数任务 → 按规则判为 `.tsl`，文件名自定，存档于 `scripts/main_board_top50_zf_claude.tsl` |
| ✅ 主动验证 | ④ | 本机解释器实测：键表构造、循环截断、排序等 builtin 逻辑全部跑通，整个文件编译通过 |
| 🗣 诚实报告边界 | ⑤ | 数据仓库函数离线环境没有（`function not found`），**如实说明需在天软客户端端到端确认，而不是谎称全部跑通** |
**产出代码**（原样，已存档：[scripts/main_board_top50_zf_claude.tsl](scripts/main_board_top50_zf_claude.tsl)）：
@@ -314,14 +289,14 @@ return top50;
**真实过程回放：**
| 步骤 | 考察点 | 实际行为 |
| :-- | :--: | :-- |
| 🧭 首跳照走 | — | 读 `AGENTS.md` → 进 `docs/tsl/index.md` → 按路由取用 TS-SQL / 控制流 / 数组集合语法页，并核对 `toolchain.md` 确认验证入口仍是占位 |
| 🧗 Skill 未注册，自行接通 | — | `tsl-api-reference` 不在其会话技能清单里 —— 没有放弃也没有瞎编，循索引找到仓库内 `skills/tsl-api-reference/SKILL.md`，直接用 `python` 调起 `lookup.py` 完成检索 |
| 🔍 函数全部查证 | ① | `--kw` 圈定候选后逐一 `--name` 核实 `getAbkbyDate` · `stockZf3` · `yesterday` · `spec` · `specDate` · `sortTableByField` · `min` · `length` · `writeLn` |
| 📖 语法转页核对 | ② | 查 `MarketTable` 无此函数 → 正确判断它是数据表名，转 TS-SQL 语法页核对 `select ... end` 写法 |
| 🚫 证据驱动的弃用 | ① | 查到 `getTopN` 存在，但其文档记录示例运行报 `not found` —— **主动弃用**，改用文档已证明的 `order by ... desc` + 手动循环取前 50 |
| 🗣 诚实报告边界 | ④ ⑤ | PATH 中无 `tsl`/`tslcli`，无法真实运行 → 只做静态检查（无裸 `=` 赋值、无声明区、关键语句在位），并如实说明"没法做真实 TSL 运行验证" |
| 步骤 | 考察点 | 实际行为 |
| :------------------------ | :----: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🧭 首跳照走 | — | 读 `AGENTS.md` → 进 `docs/tsl/index.md` → 按路由取用 TS-SQL / 控制流 / 数组集合语法页，并核对 `toolchain.md` 确认验证入口仍是占位 |
| 🧗 Skill 未注册，自行接通 | — | `tsl-api-reference` 不在其会话技能清单里 —— 没有放弃也没有瞎编，循索引找到仓库内 `skills/tsl-api-reference/SKILL.md`，直接用 `python` 调起 `lookup.py` 完成检索 |
| 🔍 函数全部查证 | ① | `--kw` 圈定候选后逐一 `--name` 核实 `getAbkbyDate` · `stockZf3` · `yesterday` · `spec` · `specDate` · `sortTableByField` · `min` · `length` · `writeLn` |
| 📖 语法转页核对 | ② | 查 `MarketTable` 无此函数 → 正确判断它是数据表名，转 TS-SQL 语法页核对 `select ... end` 写法 |
| 🚫 证据驱动的弃用 | ① | 查到 `getTopN` 存在，但其文档记录示例运行报 `not found` —— **主动弃用**，改用文档已证明的 `order by ... desc` + 手动循环取前 50 |
| 🗣 诚实报告边界 | ④ ⑤ | PATH 中无 `tsl`/`tslcli`，无法真实运行 → 只做静态检查（无裸 `=` 赋值、无声明区、关键语句在位），并如实说明"没法做真实 TSL 运行验证" |
**产出代码**（原样，已存档：[scripts/main_board_top50_zf_codex.tsl](scripts/main_board_top50_zf_codex.tsl)）：
@@ -358,17 +333,17 @@ return result;
### 第三轮实测：Qwen 3.6-27B
> 环境：qwen3.6-27b（27B 开源模型，代理框架未注明）；提示词同样追加指定了输出路径 `scripts/main_board_top50_zf_qwen3.6-27b.tsl`；耗时未记录。
> 环境：qwen3.6-27b（27B 开源模型，代理框架 vscode-tsl）；提示词同样追加指定了输出路径 `scripts/main_board_top50_zf_qwen3.6-27b.tsl`；耗时未记录。
**真实过程回放：**
| 步骤 | 考察点 | 实际行为 |
| :-- | :--: | :-- |
| 🧭 首跳照走 | — | 读 `AGENTS.md` → 进 `docs/tsl/index.md` → 取用快速落代码 / TS-SQL 语法页，并直接调用 `lookup.py` 检索（其环境中文输出乱码，带病工作） |
| 🌀 文档缺口处反复打转 | ① | 盯上 `StockZf_No`（区间涨幅排名），但该函数的 `sort_by` / `return_type` 文档确实没给取值 —— 数十轮反复检索、重读同一页，**期间明确引用铁律"无文档结论……不发明语法"，始终拒绝猜参数**，最终绕开该函数 |
| ⚠️ 起念假设，又自行回撤 | ② | 中途多次想按"惯例"假设 `MarketTable` 的 `pre_close` 等字段名与 `refof`/`refsof` 用法，推演后自行放弃该路线，改用全部经查证的 `stockZf` 循环方案 |
| 🔍 最终函数全部有据 | ① | 落码只用查证过的 `yesterday` · `getAbkbyDate` · `setSysParam`/`PN_Stock` · `stockZf` · `drange` · `dateToStr` · `echo` |
| 🤐 收尾缺验证与边界声明 | ④ ⑤ | 产出后仅回读文件自查"逻辑看起来正确"，未做静态检查，也未声明"未经运行验证" —— 三轮中唯一没交代验证边界的 |
| 步骤 | 考察点 | 实际行为 |
| :---------------------- | :----: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🧭 首跳照走 | — | 读 `AGENTS.md` → 进 `docs/tsl/index.md` → 取用快速落代码 / TS-SQL 语法页，并直接调用 `lookup.py` 检索（其环境中文输出乱码，带病工作） |
| 🌀 文档缺口处反复打转 | ① | 盯上 `StockZf_No`（区间涨幅排名），但该函数的 `sort_by` / `return_type` 文档确实没给取值 —— 数十轮反复检索、重读同一页，**期间明确引用铁律"无文档结论……不发明语法"，始终拒绝猜参数**，最终绕开该函数 |
| ⚠️ 起念假设，又自行回撤 | ② | 中途多次想按"惯例"假设 `MarketTable` 的 `pre_close` 等字段名与 `refof`/`refsof` 用法，推演后自行放弃该路线，改用全部经查证的 `stockZf` 循环方案 |
| 🔍 最终函数全部有据 | ① | 落码只用查证过的 `yesterday` · `getAbkbyDate` · `setSysParam`/`PN_Stock` · `stockZf` · `drange` · `dateToStr` · `echo` |
| 🤐 收尾缺验证与边界声明 | ④ ⑤ | 产出后仅回读文件自查"逻辑看起来正确"，未做静态检查，也未声明"未经运行验证" —— 三轮中唯一没交代验证边界的 |
**产出代码**（原样，已存档：[scripts/main_board_top50_zf_qwen3.6-27b.tsl](scripts/main_board_top50_zf_qwen3.6-27b.tsl)）：
@@ -411,31 +386,69 @@ end;
**五个考察点：**
| 考察点 | Claude Code · Fable 5 | Codex CLI · GPT-5.5 | Qwen 3.6-27B |
| :-- | :-- | :-- | :-- |
| ① 函数真实性 | skill 逐一查证 5/5，零编造 | 全部查证，并依据文档负向记录弃用 `getTopN` | 全部查证；面对 `StockZf_No` 文档缺口拒绝编参数，绕路重来 |
| ② 语法证据 | 外形均见于取用三页的可照写示例 | `MarketTable` 判为表名后转 TS-SQL 页核对写法 | 拒绝按"惯例"假设字段名与 `refof` 用法，回撤改走已查证路线 |
| ③ 文件模型 | `.tsl` 判定正确（文件名自定） | `.tsl`（文件名由提示词给定，未构成考察） | `.tsl`（文件名由提示词给定，未构成考察） |
| ④ 自主验证 | 本机解释器实测 builtin 跑通、整文件编译通过 | 环境无解释器，静态检查 | 仅回读文件自查，无静态/运行验证 |
| ⑤ 边界诚实 | 明说 dotnet 函数需客户端确认 | 明说无法真实运行验证，列出静态证据 | 收尾未声明未验证状态 |
| 考察点 | Claude Code · Fable 5 | Codex CLI · GPT-5.5 | Qwen 3.6-27B |
| :----------- | :------------------------------------------ | :------------------------------------------- | :-------------------------------------------------------- |
| ① 函数真实性 | skill 逐一查证 5/5，零编造 | 全部查证，并依据文档负向记录弃用 `getTopN` | 全部查证；面对 `StockZf_No` 文档缺口拒绝编参数，绕路重来 |
| ② 语法证据 | 外形均见于取用三页的可照写示例 | `MarketTable` 判为表名后转 TS-SQL 页核对写法 | 拒绝按"惯例"假设字段名与 `refof` 用法，回撤改走已查证路线 |
| ③ 文件模型 | `.tsl` 判定正确（文件名自定） | `.tsl`（文件名由提示词给定，未构成考察） | `.tsl`（文件名由提示词给定，未构成考察） |
| ④ 自主验证 | 本机解释器实测 builtin 跑通、整文件编译通过 | 环境无解释器，静态检查 | 仅回读文件自查，无静态/运行验证 |
| ⑤ 边界诚实 | 明说 dotnet 函数需客户端确认 | 明说无法真实运行验证，列出静态证据 | 收尾未声明未验证状态 |
**额外观察与成本：**
| 维度 | Claude Code · Fable 5 | Codex CLI · GPT-5.5 | Qwen 3.6-27B |
| :-- | :-- | :-- | :-- |
| Skill 接入 | 已注册，直接调用 | 未注册 → 循路由自行找到 `lookup.py` 手动调用 | 未注册 → 手动调用（检索输出乱码，带病工作） |
| 交易日处理 | `lastTradeDay` 取最近交易日，周一跑正确落上周五 | `yesterday()` 日历昨天，逢周末可能取到无行情日 | `yesterday()` 与 `dt-1` 全日历日，三轮中最弱 |
| 检索效率 | 一次路由到位 | 一次路由到位 + 证据驱动取舍 | 在同一文档缺口反复打转数十轮 |
| 总耗时 | 16m57s | 9m21s | 未记录 |
| token | 自估：输入 15–20 万 / 输出 0.5–1 万 | 实测：18.5 万 = 15.9 万入 + 2.57 万出 | 自估：约 1.5–2.5 万（未计上下文重复，口径偏小） |
| 维度 | Claude Code · Fable 5 | Codex CLI · GPT-5.5 | Qwen 3.6-27B |
| :--------- | :---------------------------------------------- | :--------------------------------------------- | :---------------------------------------------- |
| Skill 接入 | 已注册，直接调用 | 未注册 → 循路由自行找到 `lookup.py` 手动调用 | 未注册 → 手动调用（检索输出乱码，带病工作） |
| 交易日处理 | `lastTradeDay` 取最近交易日，周一跑正确落上周五 | `yesterday()` 日历昨天，逢周末可能取到无行情日 | `yesterday()` 与 `dt-1` 全日历日，三轮中最弱 |
| 检索效率 | 一次路由到位 | 一次路由到位 + 证据驱动取舍 | 在同一文档缺口反复打转数十轮 |
| 总耗时 | 16m57s | 9m21s | 未记录 |
| token | 自估：输入 15–20 万 / 输出 0.5–1 万 | 实测：18.5 万 = 15.9 万入 + 2.57 万出 | 自估：约 1.5–2.5 万（未计上下文重复，口径偏小） |
> **对照说明：** ① 第二、三轮提示词在第一轮基础上各自追加了输出文件名，文件命名被显式给定；第一轮产出原名 `main_board_top50_zf.tsl`，存档时加 `_claude` 后缀以区分三轮；② 第二轮运行时仓库内已有本 README 的同题示例，模型读到过该片段（其后仍逐一核对了函数事实）；③ 三轮本地条件不同——第一轮机器装有离线 TSL 解释器，第二轮 PATH 无解释器，第三轮未尝试任何运行验证；④ 第三轮的代理框架与耗时未记录，token 为模型按"内容量"事后自估、未计多轮上下文重复携带——三轮 token 口径各不相同（实测 / 含缓存自估 / 内容量自估），不可直接横比。以上数字与行为仅作真实记录，不构成严格受控对比。
> **对照说明：** ① 第二、三轮提示词在第一轮基础上各自追加了输出文件名，文件命名被显式给定；第一轮产出原名 `main_board_top50_zf.tsl`，存档时加 `_claude` 后缀以区分三轮；② 第二轮运行时仓库内已有本 README 的同题示例，模型读到过该片段（其后仍逐一核对了函数事实）；③ 三轮本地条件不同——第一轮机器装有离线 TSL 解释器，第二轮 PATH 无解释器，第三轮未尝试任何运行验证；④ 第三轮的耗时未记录，token 为模型按"内容量"事后自估、未计多轮上下文重复携带——三轮 token 口径各不相同（实测 / 含缓存自估 / 内容量自估），不可直接横比。以上数字与行为仅作真实记录，不构成严格受控对比。
### 三轮小结
- **机制得到验证** —— skill 已注册、未注册自行接通、检索乱码带病工作三种接入条件下，三轮全部零函数编造；「禁止发明语法 + 首跳路由 + 块级证据」对 27B 开源小模型同样有约束力。
- **验证与诚实呈梯度** —— 三轮收尾分别是解释器实测、静态检查、无验证亦无声明；在 `toolchain.md` 执行入口实体化之前，「必须验证」写不成硬约束，收尾质量只能靠模型自觉。
- **实测暴露的文档债均已入计划** —— `StockZf_No` 参数取值缺失 →「检索质量 · 参数类型实证」；`equity/misc.md` 兜底堆积拖慢检索 →「分类治理」；`lookup.py` 输出编码 →「检索质量」。
- **实测暴露的文档债均已入计划** —— `StockZf_No` 参数取值缺失 →「检索质量 · 参数类型实证」；`equity/misc.md` 兜底堆积拖慢检索 →「分类治理」。
---
<div align="center">
## 🔭 第三部分 · 后续升级方向
**演进视角 —— 已到哪一步、下一步往哪走**
</div>
> 语法层已完成 Skill 化（`docs/tsl/syntax/` 24 篇搬入 `tsl-syntax-reference` skill，与 `tsl-api-reference` 对齐成统一的 lookup 调用模型）。playbook 已覆盖语法、函数、模块三大知识面，下一步围绕**分类治理、覆盖广度、检索质量、Agent Loop**四大方向推进。
### 🗂 分类治理 · codegen 归类校准与全量可用性核验
- **方向** — 复核 codegen 母本（builtin 10 类 / dotnet 21 类）的函数归类，纠正错分与 `misc` 兜底堆积（如 `equity/misc.md` 单页已累至 9252 行、759 个函数），填充或裁撤 builtin `finance` / `market` 两个空壳类目，让类目边界清晰；并对全部 12455 个函数逐一探针实测，给每个函数标注真实可用性状态。
- **目的** — 一方面让 `--kw` 关键词检索落在符合直觉的类目、候选更准；另一方面用实测的「可用 / 真缺失 / 参数不对」三态，取代"索引里有就默认能用"的假设，从源头杜绝把不可用函数写进生成代码。
- **难点**
- **规模大、纯手工** — 上万个函数逐一复核归类，只能手工搬运并同步维护索引一致性，工作量大且易漏。
- **可用性须真解释器** — 「可用」无法静态判定，须接真实 TSL 解释器对上万函数逐一探针（`toolchain.md` 的执行入口目前仍是模板占位），规模大、成本高。
- **假阴性要甄别** — 探针报错可能是"函数真缺失"，也可能只是"参数没给对"；两者须隔离区分（`special/pending` vs `special/unknown`），否则会把本可用的函数误标为不可用。
### 📚 覆盖广度
- 扩充 `modules/`：补充更多平台模块（比如 TS-OPI）的 API 事实页；整个 `modules/` 以后还需迁移到 `tsl-api-reference`。
- 沉淀**场景配方库**（Recipe）：把"选股 → 回测 → 通知"这类高频端到端流程做成可照写的组合骨架。
- 为常见报错建立**反例 → 正确写法**的快速跳转索引，让避坑更即时。
### 🔍 检索质量
- 为 `function_index.tsv` 增加**参数类型实证**：当前仍有约 2600 个函数（builtin 246 / dotnet 2382）的参数声明为 `any`/`object`，需用 `dataType()` 逐一收紧。
- 引入**语义检索**（embedding），让"我想算个动量因子"这类模糊意图也能命中相关函数。
- 为函数打**标签 / 近义词**（场景 · 资产 · 操作维度），降低 `--kw` 空命中率、让检索更精准更细致。
### 🔁 Agent Loop（规划中）
- 把「写 TSL → 跑解释器 → 拿报错 → 回查语法 / 函数 → 改 → 再跑」闭成自动循环，让验证成为流程本身，而不是靠模型自觉（详见 [AGENT_PRIMER.md](AGENT_PRIMER.md) 对 Loop 的说明）。
- 尚未规划落地方案，先作为方向记录。
---
skills/tsl-syntax-reference/SKILL.md
+1 -1
View File
@@ -29,7 +29,7 @@ python <this-skill-dir>/scripts/lookup.py --query "数组下标" --mode explain
`--query` 输出候选后，必须执行下面这种精确取回：
```bash
python <this-skill-dir>/scripts/lookup.py --section "05_functions_and_calls--可直接照写示例--基础函数-过程骨架"
python <this-skill-dir>/scripts/lookup.py --section "05_functions_and_calls--可直接照写示例--默认参数"
```
只有 `--section` 返回的章节正文可作为本次任务的语法事实来源；候选摘要和概念地图都不能直接支持代码结论。需要补充时改进查询词再次检索，不得绕过 lookup 手工打开或挑选 `references/` 页面。