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

📝 docs(tsl): clarify syntax constraints and enhance test infrastructure

Browse Source 
- Add TSF file naming constraint to syntax/02_core_model.md
- Clarify semicolon rules: syntax facts vs style preferences
- Separate control flow end semicolon rules (syntax allows both)
- Add function body semicolon requirements to syntax/05_functions_and_calls.md
- Move style preferences to code_style.md (control flow end semicolons)
- Remove cross-references from syntax docs to maintain independence
- Enhance Gitea workflow emoji for better CI output readability
- Fix CI test path from tests/ to test/
- Organize agent test results under test/agent/result/ directory
- Add complete Chinese translation of test cases (test_cases_zh.md)
- Clean up .gitignore to use unified test/agent/result/ directory
- Remove obsolete agent test artifacts (REPORTS_LOCATION.md, old results)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
csh
2026-06-21 17:04:50 +08:00
co-authored by Claude Opus 4.6
parent 6026401907
commit 8b93311cae
138 changed files with 7018 additions and 1705 deletions
Download Patch File Download Diff File Expand all files Collapse all files
rulesets/cpp/index.md
-7
View File
@@ -22,13 +22,6 @@
- Modules 工程：模块名点分层 `lower_snake_case`；接口文件 `.cppm`；修改 `export module` 必须更新 CMake module file-set
- 构建与依赖：Conan 需提供 `conan-release`/`conan-debug`；`conan install` + `cmake --preset ...`；Windows 通过 Linux + Clang 交叉编译验证
## 安全红线（不可触碰）
- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key
- 避免内存不安全操作：悬垂指针、双重释放、越界访问
- 禁用不安全函数（`strcpy`, `sprintf`, `gets` 等）
- 修改鉴权/权限逻辑必须说明动机与风险
## 权威来源
- 代码风格：`docs/cpp/code_style.md`
rulesets/markdown/index.md
+2 -1
View File
@@ -28,5 +28,6 @@
## 适用范围
- 仅适用于 `.md` 文件
- 本规则集仅适用于 Markdown 格式整理任务（代码块格式化、语言标识补全等）
- 内容更新任务（如维护 memory-bank、编写 Plan、更新文档正文）按对应任务类型的规则执行
- 涉及代码内容时，遵循对应语言的 `.agents` 规则
rulesets/python/index.md
-7
View File
@@ -22,13 +22,6 @@
- 命名：模块/包 `lower_with_under.py`；类 `CapWords`；函数/变量 `lower_with_under`；常量 `UPPER_WITH_UNDER`；私有 `_private`
- Docstring：Google 风格；公共模块/类/函数/方法必须写
## 安全红线（不可触碰）
- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key
- 不得使用 `eval()` / `exec()` 处理不可信输入
- 修改鉴权/权限逻辑必须说明动机与风险
- 不确定是否敏感时按敏感信息处理
## 权威来源
- 代码风格：`docs/python/style_guide.md`
rulesets/tsl/index.md
+28 -124
View File
@@ -2,140 +2,44 @@
文档类型：高优先级智能体决策规则
是否可直接用于生成代码：否
作用：控制智能体在阅读、修改、生成 TSL 代码前的判断顺序、文档路由、禁止行为和自检流程。
作用：控制智能体在阅读、修改、生成 TSL 代码前的判断顺序、首跳路由和禁止行为。
本文件不是 TSL 语法手册，也不是完整教程。智能体必须先按本文件判断任务类型，再进入对应的 `docs/tsl/` 页面查阅语法、函数库或模块集成信息。
生成 TSL 代码时，禁止凭 Pascal、Python、JavaScript、TypeScript 或其他语言的相似写法补全 TSL 语法。文档没有给出结论时，必须向用户确认、记录文档缺口，或改用文档已经写明的可照写示例，不得发明语法。
## 范围与优先级
- 本文件是仓库级 TSL 智能体高优先级规则。
- 更靠近代码目录的本地规则可以增加更严格的约束，但不能削弱本文件中的安全、文档事实和禁止发明语法规则。
- 本文件控制智能体行为和判断顺序，不替代 `docs/tsl/` 下的语法、函数库、模块集成或项目执行文档。
- 当本文件与 `docs/tsl/**` 冲突时，按以下顺序处理：
1. 安全与凭据处理规则。
2. 用户明确指令中关于目标、交付物、文件路径和风格偏好的部分。
3. 本地目录规则中更具体且不削弱本文件安全、文档事实和禁止发明语法规则的部分。
4. 本智能体规则集。
5. TSL 语法/函数库事实文档。
6. 现有项目代码模式。
- 用户明确指令不能覆盖安全规则、文档事实使用规则、禁止发明语法规则或 TSL 事实。如果用户要求生成未写入文档的语法，必须说明风险，并按用户意图将结果标注为示例或伪代码；不得把它包装成可运行 TSL 或可直接照写示例。
- 如果两个权威来源对 TSL 语法结论不一致，不要猜测。必须说明冲突，优先采用 `代码块身份：可直接照写示例`；当差异会影响生成代码正确性时，先向用户确认。
- 本文件不是 TSL 语法手册；是仓库级 TSL Layer 1，只放硬约束、首跳路由和阻断条件。
- 更靠近代码目录的规则可以更严格，但不能削弱安全、文档事实和禁止发明语法规则。
- TSL 事实以 `docs/tsl/**`、项目自身文档和块级 `代码块身份` 为准；本文件不复写完整语法。
- 用户明确指令不能覆盖安全规则、文档事实使用规则或禁止发明语法规则。
## 代码生成协议
生成或修改 TSL 代码前，智能体必须执行以下流程：
1. 识别用户交付目标：可执行脚本、可复用模块、语法解释、缺陷修复、重构、业务逻辑、函数查询或集成任务。
2. 识别文件模型：
- 用户要求可执行脚本或入口流程时，使用 `.tsl`。
- 用户要求可复用函数、过程、类、模块或扩展代码时，使用 `.tsf`。
- 文件模型会影响正确性且需求不明确时，生成代码前向用户确认。
3. 路由到 `docs/tsl/` 下最小且最相关的权威文档。
4. 生成代码外形时，优先参考 `代码块身份：可直接照写示例`。
5. 避开任何标记为 `代码块身份：反例 / 不可照写` 的代码块。
6. 除非文档明确说明组合方式，否则不要把多个页面的片段拼成新的语法外形。
7. 没有文档结论时，不要发明语法；改为向用户确认或记录文档缺口。
8. 生成代码后，执行本文件中的最终 TSL 自检。
- 先识别交付目标：可执行脚本、可复用模块、语法解释、缺陷修复、业务逻辑、函数查询、模块集成或项目执行。
- 生成或修改代码前先判断 `.tsl` / `.tsf`；文件模型影响正确性且需求不明时先确认。
- 代码外形只参考 `docs/tsl/**` 中可直接照写的示例代码块。
- `反例 / 不可照写`、`输出片段`、`配置片段 / 概念骨架` 不得当作源码照写。
- 禁止凭 Pascal、Python、JavaScript、TypeScript 或其他语言的相似写法补全 TSL 语法。
- 无文档结论、文件模型不明或项目执行事实缺失时停止，不发明语法。
## TSL 核心事实
以下只保留高优先级提醒。完整文件模型看 `docs/tsl/syntax/02_core_model.md`；完整语法细节从 `docs/tsl/syntax/index.md` 分流。
- `.tsl` 在通用 TSL 规则中表示可执行脚本；如果项目把 `.tsl` 另作它用，必须先确认项目约定，不能反推为通用事实。
- `.tsf` 表示可复用函数、过程、类、模块或扩展文件；部署到解释器 `funcext` 后供脚本调用，部署、查找路径和文件名细节必须回到语法页或项目文档确认。
- 用户明确给出 `.tsl` 或 `.tsf` 后缀时，后缀是主要文件模型信号；未给后缀时先按交付目标初判，影响正确性且不明确就先确认。
- 入口流程、脚本任务或一次性任务默认 `.tsl`；可复用函数、过程、类、模块或扩展默认 `.tsf`；脚本内部封装函数或类不自动升级为 `.tsf`。
- 在 `.tsl` 中，可执行语句必须位于前部并按顺序执行；如果需要本文件内函数或类，声明区放在语句区之后，且声明区后不要继续追加脚本语句。
- 在 `.tsf` 中，只生成可复用顶层声明或 `unit`；不要写成顺序执行入口。
- 创建对象有两种方式：`new ClassName()` 最常用，`createObject(...)` 作为次选；需要字符串类名、类类型变量或跨 `unit` 路径时，更适合用 `createObject(...)`。
- 不要因为 Pascal、Python、JavaScript 或 TypeScript 支持某种写法，就假设 TSL 也支持。
- `.tsl` / `.tsf` 后缀由用户指定时，后缀优先。
- 未指定后缀时：入口流程、脚本任务或一次性任务初判 `.tsl`；可复用函数、过程、类、模块或扩展初判 `.tsf`。
- `.tsl` 代码需要本文件内函数或类时，先写可执行语句区，再写声明区；声明区后不要继续追加脚本语句。
- `.tsf` 只按可复用顶层声明或 `unit` 组织，不写顺序执行入口。
- 对象创建、函数调用、`unit`、运行时上下文、TS-SQL 和矩阵等细节只从对应专题页取事实。
## 任务路由
先路由任务，再阅读详细文档。不要把所有 TSL 相关请求都当成语法请求。
- 如果用户询问语言语法怎么写，先读 `docs/tsl/syntax/index.md`。
- 如果用户要求最短可运行骨架，先读 `docs/tsl/syntax/01_quickstart.md`。
- 如果用户询问某个语法形式是否有效，先读 `docs/tsl/syntax/index.md`，再进入最小匹配专题页。
- 如果用户询问常见误写、反例或不安全假设，先读 `docs/tsl/syntax/11_pitfalls.md`。
- 如果用户询问行情、财务、板块、选股等金融函数，先读 `docs/tsl/reference/catalog/datawarehouse.md`。
- 如果用户询问 Python 调 TSL 服务器函数、批量取数或异步取数，先读 `docs/tsl/modules/pytsl_api.md`。
- 如果用户询问回测框架、组合回测、交易流程或回测结果读取，先读 `docs/tsl/modules/tsbacktesting.md`。
- 如果用户询问某个内置函数或函数库函数怎么用，先读 `docs/tsl/reference/index.md`。
- 如果用户询问模块、集成、pyTSL、微信消息或回测模块，先读 `docs/tsl/modules/index.md`。
- 如果用户询问账户体系、真实服务端点、部署、脚本入口、环境变量、CI 或验证命令，把问题视为项目执行上下文；优先查项目文档、`scripts/*` 和 CI 配置，不要从通用 TSL 语法文档里猜。
### 路由冲突处理
- 如果一个任务同时涉及业务和语法，按用户的主要目标路由。
- 如果主要目标是业务行为，先读模块文档、函数事实页或项目实际接口文档，语法文档只做辅助。
- 如果主要目标是语言有效性，先读语法文档，业务或模块文档只作为示例和上下文。
- 如果任务依赖真实凭据、账户、部署或环境行为，不要发明项目事实；必须询问用户或检查项目专属文件。
## 文档入口
按目的选择来源，不要默认通读全部文档。
| 目的 | 来源 | 性质 |
| ----------------------------- | --------------------------------------------- | ---------- |
| 顶层路由 | `docs/tsl/index.md` | 决策入口 |
| 语法判断 | `docs/tsl/syntax/index.md` | 语法入口 |
| 最短可运行骨架与核心事实 | `docs/tsl/syntax/01_quickstart.md` | 语法入口 |
| 高频误写与反例 | `docs/tsl/syntax/11_pitfalls.md` | 语法入口 |
| 数据仓库金融函数 | `docs/tsl/reference/catalog/datawarehouse.md` | 函数事实 |
| pyTSL / 服务器函数 / 批量取数 | `docs/tsl/modules/pytsl_api.md` | 模块 API |
| 回测框架与结果接口 | `docs/tsl/modules/tsbacktesting.md` | 模块 API |
| 模块与集成任务 | `docs/tsl/modules/index.md` | 集成入口 |
| 函数库查询 | `docs/tsl/reference/index.md` | 函数库入口 |
| 本仓库格式偏好 | `docs/tsl/code_style.md` | 非语法事实 |
| 本仓库/作者命名偏好 | `docs/tsl/naming.md` | 非语法事实 |
| 任务信号 | 首跳入口 |
| -------------------------------------------- | --------------------------------------------- |
| 语法、文件模型、最短骨架、反例 | `docs/tsl/index.md` |
| 行情、财务、板块、选股等金融函数 | `docs/tsl/reference/catalog/datawarehouse.md` |
| 通用函数库函数名、参数、返回值 | `docs/tsl/reference/index.md` |
| Python 调 TSL、服务器函数、批量或异步取数 | `docs/tsl/modules/pytsl_api.md` |
| 回测框架、组合回测、读取回测结果 | `docs/tsl/modules/tsbacktesting.md` |
| 模块、集成、互操作、微信消息 | `docs/tsl/modules/index.md` |
| 账户、真实接口、部署、脚本入口、环境变量、CI | 项目文档、`scripts/*`、CI 配置 |
## 文档事实使用策略
- 页面级元数据只是粗粒度信号。生成代码时，优先看代码块级别的 `代码块身份`。
- 优先参考标记为 `代码块身份：可直接照写示例` 的代码块。
- 永远不要复制标记为 `代码块身份：反例 / 不可照写` 的代码块作为可运行代码。
- `代码块身份：配置片段 / 概念骨架` 只能作为结构提示，不能当作可直接运行代码。
- `代码块身份：输出片段` 只能作为输出形态，不能当作源码。
- 模板、错误示例和输出片段都不是可独立编译代码。
- 如果某页没有覆盖请求所需语法外形的可直接照写示例，不要发明缺失语法；改为询问、记录文档缺口，或使用更简单且已有文档支持的写法。
- `code_style.md` 与 `naming.md` 只表达本仓库或作者风格偏好，不代表 TSL 语法事实。
## 安全规则
- 不得把明文密钥、密码、token、API key、cookie、私钥或真实凭据写入代码、日志、注释、示例、测试或文档。
- 如果用户提供真实敏感信息，不要复述；替换为 `<TOKEN>`、`<API_KEY>` 或 `<PASSWORD>` 等占位符。
- 如果现有代码中出现疑似敏感信息，必须明确标注风险，并避免把它复制到新代码或解释中。
- 修改鉴权、授权、权限检查、账户处理、交易权限、下单或生产执行路径时，必须说明动机和风险。
- 不确定某个值是否敏感时，按敏感信息处理。
- 不要发明账户 ID、服务端点、生产路径或凭据名称；必须使用项目专属文档，或向用户确认。
- 金融或交易任务中，除非用户明确要求且项目文档确认执行路径，否则不要生成会静默真实下单、改变账户状态或使用生产凭据的代码。
- 当任务可能影响真实交易或外部系统时，优先使用 dry-run、仿真、回测或显式确认流程。
## 修改纪律
- 改动必须小而聚焦，只服务于用户当前请求。
- 避免无关重构、格式刷屏或文档大改。
- 除非用户明确要求，不要新增依赖、工具、脚本或执行要求。
- 引入新模式前，先遵循现有项目风格、文件布局和命名习惯。
- 编辑 TSL 文档时，保留元数据字段和 `代码块身份` 标签，因为智能体路由依赖这些信息。
- 不要声称生成或修改后的代码已经验证，除非确实运行了对应命令或已有项目执行记录。
## 最终 TSL 自检
展示生成或修改后的 TSL 代码前，必须检查：
1. 任务是否路由到正确层：语法、函数库、模块集成或项目执行。
2. 文件模型是否正确：`.tsl` 用于可执行脚本，`.tsf` 用于可复用函数、过程、类、模块或扩展。
3. 对 `.tsl`，可执行语句是否位于本文件函数/类声明之前。
4. 对 `.tsl`，声明区之后是否没有继续追加可执行脚本语句。
5. 对 `.tsf`，代码是否是可复用顶层声明；文件名已知时，是否尊重文件基名与声明名关系。
6. 代码外形是否基于文档事实或 `代码块身份：可直接照写示例`。
7. 是否没有把 `反例 / 不可照写`、输出片段或概念骨架当作可运行代码复制。
8. 是否没有从其它语言家族发明 TSL 语法。
9. 是否没有猜测内置名、函数库函数、模块行为或项目事实。
10. 如果任务要求遵循本仓库风格，是否只把 `code_style.md` 和 `naming.md` 当作本仓库/作者偏好，而不是语法事实。
11. 是否没有引入密钥、凭据、生产端点或不安全的交易/账户行为。
12. 仍不确定的地方是否明确说明，而不是隐藏在生成代码里。
- 页面级元数据只做粗判断；生成代码时以块级 `代码块身份` 为准。
- `code_style.md` 与 `naming.md` 只表达风格偏好，不代表 TSL 语法事实。
- 真实凭据、账户、生产端点、交易权限和下单行为必须来自项目上下文；缺失时不得猜测。
rulesets/typescript/index.md
-7
View File
@@ -24,13 +24,6 @@
- 异步：优先 `async/await`；避免裸 `.then()` 链；错误必须处理
- JavaScript 质量底线：必须通过 ESLint；推荐启用 `@ts-check` + JSDoc 做静态检查
## 安全红线（不可触碰）
- 不得在代码/日志/注释中写入明文密钥、密码、Token、API Key
- 不得使用 `eval()` / `new Function()` 处理不可信输入
- 不得直接拼接用户输入到 SQL/命令/HTML（防注入/XSS）
- 修改鉴权/权限逻辑必须说明动机与风险
## 权威来源
- 代码风格：`docs/typescript/code_style.md`