From efd4b8e421d91fe216a7365291c47f23400c12e1 Mon Sep 17 00:00:00 2001 From: csh Date: Tue, 14 Jul 2026 09:09:58 +0800 Subject: [PATCH] :memo: docs(tsl): align README with syntax skill, restructure roadmap as part-3 - 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) --- AGENT_PRIMER.md | 189 +++++++++++++++++ README.md | 297 ++++++++++++++------------- skills/tsl-syntax-reference/SKILL.md | 2 +- 3 files changed, 345 insertions(+), 143 deletions(-) create mode 100644 AGENT_PRIMER.md diff --git a/AGENT_PRIMER.md b/AGENT_PRIMER.md new file mode 100644 index 00000000..42e43814 --- /dev/null +++ b/AGENT_PRIMER.md @@ -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{找到合适的
Skill 了吗} + C -->|用户点名 / 任务匹配 / 规则要求| D[打开对应 Skill] + D --> E[按照步骤工作] + E --> F[需要时查资料
或使用工具] + 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 推动任务向前。** diff --git a/README.md b/README.md index 258f3f23..9534fb15 100644 --- a/README.md +++ b/README.md @@ -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) @@ -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 是什么、如何搭建** @@ -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
硬约束 + 首跳} - B -->|需要任何 TSL 事实| C[docs/tsl/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 个语法专题] + A[用户提示词] --> B{AGENTS.md
常驻硬约束 + 事实边界} + B -->|语法 / 文件模型 / 控制流| D[tsl-syntax-reference
Skill] + B -->|取金融数据 / 查函数| E[tsl-api-reference
Skill] + B -->|命名 · 风格 · 模块集成| C[docs/tsl/index.md
文档分流] + D -->|--map 冷启动
--query 候选 → --section 正文| H[24 篇语法专题] E -->|已知名 --name
未知名 --kw| I[12455 条索引] - Q --> Z[✅ 落 .tsl / .tsf 代码] - H --> Z + C -->|命名/风格| G[naming.md /
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 目前已覆盖语法、函数、模块三大知识面，下一步按 -> 这一部分没有虚构：**同一条提示词，投给不同的 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` 兜底堆积拖慢检索 →「分类治理」。 + +--- + +
+ +## 🔭 第三部分 · 后续升级方向 + +**演进视角 —— 已到哪一步、下一步往哪走** + +
+ +> 语法层已完成 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 的说明）。 +- 尚未规划落地方案，先作为方向记录。 --- diff --git a/skills/tsl-syntax-reference/SKILL.md b/skills/tsl-syntax-reference/SKILL.md index c8cbf442..d4dc10a2 100644 --- a/skills/tsl-syntax-reference/SKILL.md +++ b/skills/tsl-syntax-reference/SKILL.md @@ -29,7 +29,7 @@ python /scripts/lookup.py --query "数组下标" --mode explain `--query` 输出候选后，必须执行下面这种精确取回： ```bash -python /scripts/lookup.py --section "05_functions_and_calls--可直接照写示例--基础函数-过程骨架" +python /scripts/lookup.py --section "05_functions_and_calls--可直接照写示例--默认参数" ``` 只有 `--section` 返回的章节正文可作为本次任务的语法事实来源；候选摘要和概念地图都不能直接支持代码结论。需要补充时改进查询词再次检索，不得绕过 lookup 手工打开或挑选 `references/` 页面。