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

📝 docs(markdown): format tracked markdown and drop stale templates

This commit is contained in:
csh 2026-05-18 16:06:21 +08:00
parent 2325409f53
commit c1702a667a
16 changed files with 184 additions and 421 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
SKILLS.md
View File

@ -5,9 +5,9 @@
支持的平台： 支持的平台：
| 平台 | skills 目录 | | 平台 | skills 目录 |
| --- | --- | | ----------- | ------------------- |
| Codex CLI | `~/.agents/skills/` | | Codex CLI | `~/.agents/skills/` |
| Claude Code | `~/.claude/skills/` | | Claude Code | `~/.claude/skills/` |
> 提示：本仓库将 skills 以可分发的形式放在 `codex/skills/`，并提供脚本一键安装到对应平台目录。 > 提示：本仓库将 skills 以可分发的形式放在 `codex/skills/`，并提供脚本一键安装到对应平台目录。
@ -54,9 +54,9 @@ codex/skills/
最终安装到本机后，对应路径为： 最终安装到本机后，对应路径为：
| 平台 | 路径 | | 平台 | 路径 |
| --- | --- | | ----------- | ---------------------------------------- |
| Codex CLI | `~/.agents/skills/<skill-name>/SKILL.md` | | Codex CLI | `~/.agents/skills/<skill-name>/SKILL.md` |
| Claude Code | `~/.claude/skills/<skill-name>/SKILL.md` | | Claude Code | `~/.claude/skills/<skill-name>/SKILL.md` |
--- ---

83
data/tsl_reference_catalog_source/index.md
View File

@ -1,83 +0,0 @@
# TSL函数
> 本文档对应的正式检索入口见 [docs/tsl/reference/catalog/index.md](../../docs/tsl/reference/catalog/index.md)
TSL函数包含数学、系统、基础、图形等通用函数，适用于各种TSL脚本开发场景。
## 目录
### 数学与计算
- **[数学函数](./math.md)** (14,396行)
- 数值计算、常用数学函数、位运算函数
- 三角函数、角度量转换、双曲线函数
- 指数对数函数、随机数、统计函数
### 系统与平台
- **[系统相关函数](./system.md)** (1,647行)
- 系统信息、环境变量、进程控制
- 内存管理、性能监控
- **[平台函数](./platform.md)** (553行)
- 平台特定功能、系统调用
- **[客户端函数](./client.md)** (409行)
- 客户端交互、界面控制
### 基础功能
- **[基础函数](./base.md)** (10,660行)
- 字符串处理、数组操作、日期时间
- 类型转换、条件判断、数据结构
- 文件操作、流程控制
- **[图形函数](./graphics.md)** (698行)
- 绘图、图表、可视化
### 资源与交互
- **[资源访问函数](./resource.md)** (4,897行)
- 文件读写、数据库访问、网络通信
- 配置文件、资源管理
- **[第三方交互函数](./third_party.md)** (610行)
- 第三方库调用、外部程序交互
### 工具函数
- **[压缩和解压函数](./compression.md)** (108行)
- 数据压缩、解压缩、归档
- **[信息摘要及编码](./digest_encoding.md)** (172行)
- 哈希算法、加密、编码转换
## 快速索引
### 常用函数分类
| 功能类别 | 文件 | 典型函数示例 |
| ---------- | ---------------------------- | --------------------------------------- |
| 数学计算 | [math.md](./math.md) | Abs, Sqrt, Sin, Cos, Log, Exp, Round... |
| 字符串处理 | [base.md](./base.md) | Len, Mid, Left, Right, Trim, Replace... |
| 日期时间 | [base.md](./base.md) | Now, Date, Time, DateAdd, DateDiff... |
| 文件操作 | [resource.md](./resource.md) | FileExists, ReadFile, WriteFile... |
| 数组操作 | [base.md](./base.md) | Array, UBound, LBound, Sort... |
| 类型转换 | [base.md](./base.md) | CStr, CInt, CFloat, CBool... |
## 使用提示
1. **数学函数**：`math.md` 包含了所有数学计算相关的函数，是数值处理的基础
2. **基础函数**：`base.md`
最为常用，包含了字符串、数组、日期时间等日常开发必需的函数
3. **资源访问**：`resource.md` 涉及文件、数据库、网络等外部资源的访问
4. **搜索建议**：在当前目录（`data/tsl_reference_catalog_source/`）使用全局搜索查找特定函数
---
**返回**: [docs/tsl/reference/catalog/index.md](../../docs/tsl/reference/catalog/index.md)

14
docs/tsl/finance/index.md
View File

@ -18,13 +18,13 @@
## 按任务跳转 ## 按任务跳转
| 当前任务 | 先读哪里 | | 当前任务 | 先读哪里 |
| --- | --- | | ------------------------------ | -------------------------------------------------------------------- |
| 先判断是否该进入业务层 | [entry_decision.md](entry_decision.md)（决策页，不是代码页） | | 先判断是否该进入业务层 | [entry_decision.md](entry_decision.md)（决策页，不是代码页） |
| 理解市场数据上下文与运行场景 | [market_data_context.md](market_data_context.md) | | 理解市场数据上下文与运行场景 | [market_data_context.md](market_data_context.md) |
| 理解序列、指标、时序计算模型 | [series_and_indicator_model.md](series_and_indicator_model.md) | | 理解序列、指标、时序计算模型 | [series_and_indicator_model.md](series_and_indicator_model.md) |
| 写选股、信号、筛选表达模式 | [selection_and_signal_patterns.md](selection_and_signal_patterns.md) | | 写选股、信号、筛选表达模式 | [selection_and_signal_patterns.md](selection_and_signal_patterns.md) |
| 写回测对象、交易流程、结果读取 | [backtest_and_trade_flow.md](backtest_and_trade_flow.md) | | 写回测对象、交易流程、结果读取 | [backtest_and_trade_flow.md](backtest_and_trade_flow.md) |
## 切换到别的层 ## 切换到别的层

36
docs/tsl/index.md
View File

@ -80,25 +80,25 @@
## 最短跳转 ## 最短跳转
| 当前任务 | 先读哪里 | | 当前任务 | 先读哪里 |
| --- | --- | | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| 我要系统入门 TSL | [syntax/index.md](syntax/index.md) | | 我要系统入门 TSL | [syntax/index.md](syntax/index.md) |
| 我要先核对语言核心事实 | [syntax/02_quickstart.md](syntax/02_quickstart.md) | | 我要先核对语言核心事实 | [syntax/02_quickstart.md](syntax/02_quickstart.md) |
| 我要写最短可运行骨架 | [syntax/02_quickstart.md](syntax/02_quickstart.md) | | 我要写最短可运行骨架 | [syntax/02_quickstart.md](syntax/02_quickstart.md) |
| 我要判断“这句语法能不能写” | [syntax/index.md](syntax/index.md) | | 我要判断“这句语法能不能写” | [syntax/index.md](syntax/index.md) |
| 我要核对较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界 | [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页 | | 我要核对较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界 | [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页 |
| 我要核对高频误写 / 反例 / 负向边界 | [syntax/12_pitfalls.md](syntax/12_pitfalls.md) | | 我要核对高频误写 / 反例 / 负向边界 | [syntax/12_pitfalls.md](syntax/12_pitfalls.md) |
| 我要知道正式语法手册现在还差什么 | [syntax/coverage_map.md](syntax/coverage_map.md) | | 我要知道正式语法手册现在还差什么 | [syntax/coverage_map.md](syntax/coverage_map.md) |
| 我要写金融指标 / 选股 / 回测 | [finance/index.md](finance/index.md) | | 我要写金融指标 / 选股 / 回测 | [finance/index.md](finance/index.md) |
| 我要看模块 / 集成 / 互操作入口 | [modules/index.md](modules/index.md) | | 我要看模块 / 集成 / 互操作入口 | [modules/index.md](modules/index.md) |
| 我要确认账户体系 / 真实接口 / 部署方式 / 脚本入口 / 环境变量 / CI / 验证命令 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；当前项目已补齐时再看 [toolchain.md](toolchain.md) | | 我要确认账户体系 / 真实接口 / 部署方式 / 脚本入口 / 环境变量 / CI / 验证命令 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；当前项目已补齐时再看 [toolchain.md](toolchain.md) |
| 我要看回测框架模块 | [modules/tsbacktesting.md](modules/tsbacktesting.md) | | 我要看回测框架模块 | [modules/tsbacktesting.md](modules/tsbacktesting.md) |
| 我要看 Python 互操作 | [modules/tsl_python_interop.md](modules/tsl_python_interop.md) | | 我要看 Python 互操作 | [modules/tsl_python_interop.md](modules/tsl_python_interop.md) |
| 我要看微信消息推送 | [modules/wechat_message.md](modules/wechat_message.md) | | 我要看微信消息推送 | [modules/wechat_message.md](modules/wechat_message.md) |
| 我要看 Python API | [modules/pytsl_api.md](modules/pytsl_api.md) | | 我要看 Python API | [modules/pytsl_api.md](modules/pytsl_api.md) |
| 我要查函数库 | [reference/index.md](reference/index.md) | | 我要查函数库 | [reference/index.md](reference/index.md) |
| 当前项目已补齐工具链时，看工具链 / 项目执行辅证 | [toolchain.md](toolchain.md) | | 当前项目已补齐工具链时，看工具链 / 项目执行辅证 | [toolchain.md](toolchain.md) |
| 我要避开高频误写 | [syntax/12_pitfalls.md](syntax/12_pitfalls.md) | | 我要避开高频误写 | [syntax/12_pitfalls.md](syntax/12_pitfalls.md) |
## 进入之后怎么读 ## 进入之后怎么读

18
docs/tsl/modules/index.md
View File

@ -28,13 +28,13 @@
## 最短跳转 ## 最短跳转
| 当前任务 | 先读哪里 | | 当前任务 | 先读哪里 |
| --- | --- | | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| 我要看回测框架 | [tsbacktesting.md](tsbacktesting.md) | | 我要看回测框架 | [tsbacktesting.md](tsbacktesting.md) |
| 我要看 Python 互操作 | [tsl_python_interop.md](tsl_python_interop.md) | | 我要看 Python 互操作 | [tsl_python_interop.md](tsl_python_interop.md) |
| 我要看微信消息推送 | [wechat_message.md](wechat_message.md) | | 我要看微信消息推送 | [wechat_message.md](wechat_message.md) |
| 我要看 Python API | [pytsl_api.md](pytsl_api.md) | | 我要看 Python API | [pytsl_api.md](pytsl_api.md) |
| 我要确认模块的真实接入参数 / 账号来源 / 部署依赖 / 脚本入口 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；当前项目已补齐时再看 [../toolchain.md](../toolchain.md) | | 我要确认模块的真实接入参数 / 账号来源 / 部署依赖 / 脚本入口 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；当前项目已补齐时再看 [../toolchain.md](../toolchain.md) |
| 我要回到业务主线 | [../finance/index.md](../finance/index.md) | | 我要回到业务主线 | [../finance/index.md](../finance/index.md) |
| 我要回到语法主线 | [../syntax/index.md](../syntax/index.md) | | 我要回到语法主线 | [../syntax/index.md](../syntax/index.md) |
| 我要查函数库 | [../reference/index.md](../reference/index.md) | | 我要查函数库 | [../reference/index.md](../reference/index.md) |

10
docs/tsl/modules/tsl_python_interop.md
View File

@ -17,11 +17,11 @@
## 怎么选路 ## 怎么选路
| 场景 | 先选哪条路 | 最小前置条件 | 常见失败点 | | 场景 | 先选哪条路 | 最小前置条件 | 常见失败点 |
| --- | --- | --- | --- | | ----------------------------------- | -------------------------- | ------------------------------------------------------- | ---------------------------------------------------- |
| Python 作为主控，远程执行或调用 TSL | Python 调 TSL | Python 环境、TSLPy 模块、可用连接方式（COM / 远程登录） | 位数不一致、环境变量没配好、服务器未登录 | | Python 作为主控，远程执行或调用 TSL | Python 调 TSL | Python 环境、TSLPy 模块、可用连接方式（COM / 远程登录） | 位数不一致、环境变量没配好、服务器未登录 |
| TSL 脚本里需要调用现有 Python 代码 | TSL 调 Python | TSL 与 Python 位数一致、`PYTHONHOME` 等环境正确 | Python 环境未就绪、模块找不到、网格场景不支持 | | TSL 脚本里需要调用现有 Python 代码 | TSL 调 Python | TSL 与 Python 位数一致、`PYTHONHOME` 等环境正确 | Python 环境未就绪、模块找不到、网格场景不支持 |
| 落地服务器侧长期提供 Python 能力 | 落地服务器开启 Python 服务 | 服务端环境、部署权限、可维护的脚本入口 | 服务端环境和本地环境不一致、依赖未部署、运行权限不足 | | 落地服务器侧长期提供 Python 能力 | 落地服务器开启 Python 服务 | 服务端环境、部署权限、可维护的脚本入口 | 服务端环境和本地环境不一致、依赖未部署、运行权限不足 |
## 结构索引 ## 结构索引

24
docs/tsl/reference/catalog/index.md
View File

@ -11,18 +11,18 @@
## 模块目录 ## 模块目录
| 模块 | 分类页 | 范围 | 函数数 | | 模块 | 分类页 | 范围 | 函数数 |
| --- | --- | --- | --- | | -------------- | ---------------------------------------- | ---------------------------------------------- | ------ |
| 基础函数 | [base.md](base.md) | 字符串、数组、日期时间、类型转换与常用基础能力 | 574 | | 基础函数 | [base.md](base.md) | 字符串、数组、日期时间、类型转换与常用基础能力 | 574 |
| 数学函数 | [math.md](math.md) | 数值计算、统计分析、矩阵处理与数学算法 | 518 | | 数学函数 | [math.md](math.md) | 数值计算、统计分析、矩阵处理与数学算法 | 518 |
| 系统相关函数 | [system.md](system.md) | 数据类型、表达式调用、性能与运行时能力 | 57 | | 系统相关函数 | [system.md](system.md) | 数据类型、表达式调用、性能与运行时能力 | 57 |
| 资源访问函数 | [resource.md](resource.md) | 文件、数据库、网络与外部资源访问 | 136 | | 资源访问函数 | [resource.md](resource.md) | 文件、数据库、网络与外部资源访问 | 136 |
| 平台函数 | [platform.md](platform.md) | 平台相关功能与系统接口 | 19 | | 平台函数 | [platform.md](platform.md) | 平台相关功能与系统接口 | 19 |
| 客户端函数 | [client.md](client.md) | 客户端交互、界面控制与前端协作能力 | 19 | | 客户端函数 | [client.md](client.md) | 客户端交互、界面控制与前端协作能力 | 19 |
| 图形函数 | [graphics.md](graphics.md) | 图表、绘图与可视化相关函数 | 27 | | 图形函数 | [graphics.md](graphics.md) | 图表、绘图与可视化相关函数 | 27 |
| 压缩和解压函数 | [compression.md](compression.md) | 压缩、解压与归档能力 | 5 | | 压缩和解压函数 | [compression.md](compression.md) | 压缩、解压与归档能力 | 5 |
| 信息摘要及编码 | [digest_encoding.md](digest_encoding.md) | 哈希、摘要、编码与转换能力 | 7 | | 信息摘要及编码 | [digest_encoding.md](digest_encoding.md) | 哈希、摘要、编码与转换能力 | 7 |
| 第三方交互函数 | [third_party.md](third_party.md) | 第三方库与外部程序交互能力 | 8 | | 第三方交互函数 | [third_party.md](third_party.md) | 第三方库与外部程序交互能力 | 8 |
## 说明 ## 说明

14
docs/tsl/reference/index.md
View File

@ -25,10 +25,10 @@
## 按任务跳转 ## 按任务跳转
| 当前任务 | 先读哪里 | | 当前任务 | 先读哪里 |
| --- | --- | | ---------------- | ------------------------------------------ |
| 查函数库入口 | [catalog/index.md](catalog/index.md) | | 查函数库入口 | [catalog/index.md](catalog/index.md) |
| 直接按模块查函数 | [catalog/index.md](catalog/index.md) | | 直接按模块查函数 | [catalog/index.md](catalog/index.md) |
| 回到语法层 | [../syntax/index.md](../syntax/index.md) | | 回到语法层 | [../syntax/index.md](../syntax/index.md) |
| 回到金融层 | [../finance/index.md](../finance/index.md) | | 回到金融层 | [../finance/index.md](../finance/index.md) |
| 回到模块层 | [../modules/index.md](../modules/index.md) | | 回到模块层 | [../modules/index.md](../modules/index.md) |

14
docs/tsl/syntax/02_quickstart.md
View File

@ -30,16 +30,16 @@
## 术语对照 ## 术语对照
- 文档里出现的“顶层 `function / procedure`”“顶层函数骨架”“顶层函数定义体”，指的是同一类顶层模型：文件以顶层 `function` / `procedure` 为主体。 - 文档里出现的“顶层 `function / procedure`”“顶层函数骨架”“顶层函数定义体”，指的是同一类顶层模型：文件以顶层 `function` / `procedure` 为主体。
- 文档里出现的 ``class function`` 和“类方法”，指的是同一件事：前者是代码关键字写法，后者是中文描述。 - 文档里出现的 `class function` 和“类方法”，指的是同一件事：前者是代码关键字写法，后者是中文描述。
## 先选哪一种骨架 ## 先选哪一种骨架
| 当前任务 | 起手骨架 | | 当前任务 | 起手骨架 |
| --- | --- | | ------------------------------ | ------------------- |
| 只写一段一次性脚本逻辑 | 顶层松散语句 | | 只写一段一次性脚本逻辑 | 顶层松散语句 |
| 先沉淀一个可复用逻辑块 | 顶层 `function` | | 先沉淀一个可复用逻辑块 | 顶层 `function` |
| 需要对象状态、字段、方法 | `type Name = class` | | 需要对象状态、字段、方法 | `type Name = class` |
| 需要把接口和实现组织进一个模块 | `unit` | | 需要把接口和实现组织进一个模块 | `unit` |
默认建议： 默认建议：

20
docs/tsl/syntax/coverage_map.md
View File

@ -16,16 +16,16 @@
## 8 章吸收总表 ## 8 章吸收总表
| 旧章节 | 主线页 | 专题页 | 说明 | | 旧章节 | 主线页 | 专题页 | 说明 |
| --- | --- | --- | --- | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `01_language_basics.md` | [01_introduction.md](01_introduction.md), [03_core_model.md](03_core_model.md), [04_values_and_literals.md](04_values_and_literals.md), [05_variables_and_constants.md](05_variables_and_constants.md), [07_expressions_and_operators.md](07_expressions_and_operators.md), [11_runtime_context_and_with.md](11_runtime_context_and_with.md), [13_matrix_and_collections.md](13_matrix_and_collections.md) | [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md), [19_types_and_conversions.md](19_types_and_conversions.md), [20_strings_and_text.md](20_strings_and_text.md) | 语言基础主干在主线，词法 / 类型 / 字符串边界放进深水专题 | | `01_language_basics.md` | [01_introduction.md](01_introduction.md), [03_core_model.md](03_core_model.md), [04_values_and_literals.md](04_values_and_literals.md), [05_variables_and_constants.md](05_variables_and_constants.md), [07_expressions_and_operators.md](07_expressions_and_operators.md), [11_runtime_context_and_with.md](11_runtime_context_and_with.md), [13_matrix_and_collections.md](13_matrix_and_collections.md) | [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md), [19_types_and_conversions.md](19_types_and_conversions.md), [20_strings_and_text.md](20_strings_and_text.md) | 语言基础主干在主线，词法 / 类型 / 字符串边界放进深水专题 |
| `02_control_flow.md` | [08_control_flow.md](08_control_flow.md) | [16_debug_and_profiler.md](16_debug_and_profiler.md) | 控制流在主线，调试与 profiler 单列专题 | | `02_control_flow.md` | [08_control_flow.md](08_control_flow.md) | [16_debug_and_profiler.md](16_debug_and_profiler.md) | 控制流在主线，调试与 profiler 单列专题 |
| `03_functions.md` | [06_functions_and_calls.md](06_functions_and_calls.md) | [21_external_calls_and_threads.md](21_external_calls_and_threads.md) | 普通函数在主线，`external` / 动态库 / 线程放进专题 | | `03_functions.md` | [06_functions_and_calls.md](06_functions_and_calls.md) | [21_external_calls_and_threads.md](21_external_calls_and_threads.md) | 普通函数在主线，`external` / 动态库 / 线程放进专题 |
| `04_modules_and_namespace.md` | [10_units_and_scope.md](10_units_and_scope.md) | [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) | `unit` / `uses` 在主线，运行时查找路径与 `Libpath` 放进专题 | | `04_modules_and_namespace.md` | [10_units_and_scope.md](10_units_and_scope.md) | [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) | `unit` / `uses` 在主线，运行时查找路径与 `Libpath` 放进专题 |
| `05_object_model.md` | [09_objects_and_classes.md](09_objects_and_classes.md) | [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md), [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md), [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | 类基础语法在主线，运行时 / 内置对象 / 重载能力拆到专题 | | `05_object_model.md` | [09_objects_and_classes.md](09_objects_and_classes.md) | [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md), [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md), [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | 类基础语法在主线，运行时 / 内置对象 / 重载能力拆到专题 |
| `06_extended_syntax.md` | [13_matrix_and_collections.md](13_matrix_and_collections.md), [14_resultset_and_filters.md](14_resultset_and_filters.md), [15_ts_sql.md](15_ts_sql.md) | [25_set_operations.md](25_set_operations.md), [26_matrix_deep_dive.md](26_matrix_deep_dive.md), [27_fmarray.md](27_fmarray.md), [28_ts_sql_core.md](28_ts_sql_core.md), [29_ts_sql_advanced.md](29_ts_sql_advanced.md) | 主线先建立数组 / 结果集 / TS-SQL 入口，集合 / 矩阵 / FMArray / TS-SQL 深水内容进入专题 | | `06_extended_syntax.md` | [13_matrix_and_collections.md](13_matrix_and_collections.md), [14_resultset_and_filters.md](14_resultset_and_filters.md), [15_ts_sql.md](15_ts_sql.md) | [25_set_operations.md](25_set_operations.md), [26_matrix_deep_dive.md](26_matrix_deep_dive.md), [27_fmarray.md](27_fmarray.md), [28_ts_sql_core.md](28_ts_sql_core.md), [29_ts_sql_advanced.md](29_ts_sql_advanced.md) | 主线先建立数组 / 结果集 / TS-SQL 入口，集合 / 矩阵 / FMArray / TS-SQL 深水内容进入专题 |
| `07_debug_and_profiler.md` | [16_debug_and_profiler.md](16_debug_and_profiler.md) | [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) | 调试入口在主线，运行时服务与全局缓存单列专题 | | `07_debug_and_profiler.md` | [16_debug_and_profiler.md](16_debug_and_profiler.md) | [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) | 调试入口在主线，运行时服务与全局缓存单列专题 |
| `08_new_generation.md` | [07_expressions_and_operators.md](07_expressions_and_operators.md), [09_objects_and_classes.md](09_objects_and_classes.md) | [31_complex_and_weakref.md](31_complex_and_weakref.md), [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | 较新语法相关内容已分散吸收到表达式 / 对象主线，复数 / 弱引用 / 对象重载保留在专题 | | `08_new_generation.md` | [07_expressions_and_operators.md](07_expressions_and_operators.md), [09_objects_and_classes.md](09_objects_and_classes.md) | [31_complex_and_weakref.md](31_complex_and_weakref.md), [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | 较新语法相关内容已分散吸收到表达式 / 对象主线，复数 / 弱引用 / 对象重载保留在专题 |
## 读取原则 ## 读取原则

114
docs/tsl/syntax/index.md
View File

@ -50,7 +50,7 @@
14. [14_resultset_and_filters.md](14_resultset_and_filters.md) 14. [14_resultset_and_filters.md](14_resultset_and_filters.md)
15. [15_ts_sql.md](15_ts_sql.md) 15. [15_ts_sql.md](15_ts_sql.md)
16. [16_debug_and_profiler.md](16_debug_and_profiler.md) 16. [16_debug_and_profiler.md](16_debug_and_profiler.md)
这条顺序对应“先建立整体读法，再写值、变量、函数、表达式、流程，随后进入类、unit、运行时边界，再按需进入进阶专题”。 这条顺序对应“先建立整体读法，再写值、变量、函数、表达式、流程，随后进入类、unit、运行时边界，再按需进入进阶专题”。
编号说明：主线 `01-16`，深水 `18-32`，无 `17` 号正文页；历史 `17` 号位保留为空。 编号说明：主线 `01-16`，深水 `18-32`，无 `17` 号正文页；历史 `17` 号位保留为空。
@ -58,67 +58,67 @@
以下专题默认不要预读。只有主线页不够、或者任务已经明确命中对应场景时，再进入。 以下专题默认不要预读。只有主线页不够、或者任务已经明确命中对应场景时，再进入。
| 专题 | 什么时候进入 | | 专题 | 什么时候进入 |
| --- | --- | | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md) | 只有涉及注释规则、条件编译、编译选项或词法边界时才读 | | [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md) | 只有涉及注释规则、条件编译、编译选项或词法边界时才读 |
| [19_types_and_conversions.md](19_types_and_conversions.md) | 只有涉及显式类型、转换规则或类型兼容问题时才读 | | [19_types_and_conversions.md](19_types_and_conversions.md) | 只有涉及显式类型、转换规则或类型兼容问题时才读 |
| [20_strings_and_text.md](20_strings_and_text.md) | 只有涉及字符串处理、编码或文本细节时才读 | | [20_strings_and_text.md](20_strings_and_text.md) | 只有涉及字符串处理、编码或文本细节时才读 |
| [21_external_calls_and_threads.md](21_external_calls_and_threads.md) | 只有涉及 `external`、DLL、线程或外部调用时才读 | | [21_external_calls_and_threads.md](21_external_calls_and_threads.md) | 只有涉及 `external`、DLL、线程或外部调用时才读 |
| [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) | 只有涉及 `namespace`、`Libpath`、unit 运行时或查找路径时才读 | | [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) | 只有涉及 `namespace`、`Libpath`、unit 运行时或查找路径时才读 |
| [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) | 只有涉及对象运行时、自省或反射能力时才读 | | [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) | 只有涉及对象运行时、自省或反射能力时才读 |
| [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md) | 只有涉及内置运行时对象时才读 | | [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md) | 只有涉及内置运行时对象时才读 |
| [25_set_operations.md](25_set_operations.md) | 只有涉及集合运算专题时才读 | | [25_set_operations.md](25_set_operations.md) | 只有涉及集合运算专题时才读 |
| [26_matrix_deep_dive.md](26_matrix_deep_dive.md) | 只有涉及矩阵运算且 [13_matrix_and_collections.md](13_matrix_and_collections.md) 不够用时才读 | | [26_matrix_deep_dive.md](26_matrix_deep_dive.md) | 只有涉及矩阵运算且 [13_matrix_and_collections.md](13_matrix_and_collections.md) 不够用时才读 |
| [27_fmarray.md](27_fmarray.md) | 只有涉及 `FMArray` 专题时才读 | | [27_fmarray.md](27_fmarray.md) | 只有涉及 `FMArray` 专题时才读 |
| [28_ts_sql_core.md](28_ts_sql_core.md) | 只有开始写 TS-SQL 核心语法时才读 | | [28_ts_sql_core.md](28_ts_sql_core.md) | 只有开始写 TS-SQL 核心语法时才读 |
| [29_ts_sql_advanced.md](29_ts_sql_advanced.md) | 只有 TS-SQL 基础页不够、问题进入进阶能力时才读 | | [29_ts_sql_advanced.md](29_ts_sql_advanced.md) | 只有 TS-SQL 基础页不够、问题进入进阶能力时才读 |
| [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) | 只有涉及网格计算、运行时服务或全局缓存时才读 | | [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) | 只有涉及网格计算、运行时服务或全局缓存时才读 |
| [31_complex_and_weakref.md](31_complex_and_weakref.md) | 只有涉及复数或弱引用时才读 | | [31_complex_and_weakref.md](31_complex_and_weakref.md) | 只有涉及复数或弱引用时才读 |
| [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | 只有涉及对象算符重载或遍历重载时才读 | | [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | 只有涉及对象算符重载或遍历重载时才读 |
这组页面承担旧 8 章里没有被主线正文完整吃掉的深水内容，目标是让新 session 只靠 `docs/tsl/syntax/` 就能覆盖旧语法章节，但默认首跳仍应先走主线页。 这组页面承担旧 8 章里没有被主线正文完整吃掉的深水内容，目标是让新 session 只靠 `docs/tsl/syntax/` 就能覆盖旧语法章节，但默认首跳仍应先走主线页。
## 按任务跳转 ## 按任务跳转
| 当前任务 | 先读哪里 | | 当前任务 | 先读哪里 |
| --- | --- | | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 先建立整体读法 | [01_introduction.md](01_introduction.md) | | 先建立整体读法 | [01_introduction.md](01_introduction.md) |
| 写最短骨架 | [02_quickstart.md](02_quickstart.md) | | 写最短骨架 | [02_quickstart.md](02_quickstart.md) |
| 判断顶层模型 / 文件模型 | [03_core_model.md](03_core_model.md) | | 判断顶层模型 / 文件模型 | [03_core_model.md](03_core_model.md) |
| 写值、数组、字符串 | [04_values_and_literals.md](04_values_and_literals.md) | | 写值、数组、字符串 | [04_values_and_literals.md](04_values_and_literals.md) |
| 写变量、常量、显式声明 | [05_variables_and_constants.md](05_variables_and_constants.md) | | 写变量、常量、显式声明 | [05_variables_and_constants.md](05_variables_and_constants.md) |
| 写 `function` / `procedure`、参数修饰、默认参数、命名参数、变参、`external` | [06_functions_and_calls.md](06_functions_and_calls.md) | | 写 `function` / `procedure`、参数修饰、默认参数、命名参数、变参、`external` | [06_functions_and_calls.md](06_functions_and_calls.md) |
| 写赋值、比较、`if` 表达式 | [07_expressions_and_operators.md](07_expressions_and_operators.md) | | 写赋值、比较、`if` 表达式 | [07_expressions_and_operators.md](07_expressions_and_operators.md) |
| 写 `?.` 等较新表达式 | [07_expressions_and_operators.md](07_expressions_and_operators.md) | | 写 `?.` 等较新表达式 | [07_expressions_and_operators.md](07_expressions_and_operators.md) |
| 写条件、循环、异常控制 | [08_control_flow.md](08_control_flow.md) | | 写条件、循环、异常控制 | [08_control_flow.md](08_control_flow.md) |
| 写类、继承、property、静态字段 | [09_objects_and_classes.md](09_objects_and_classes.md) | | 写类、继承、property、静态字段 | [09_objects_and_classes.md](09_objects_and_classes.md) |
| 写 `unit` / `uses` | [10_units_and_scope.md](10_units_and_scope.md) | | 写 `unit` / `uses` | [10_units_and_scope.md](10_units_and_scope.md) |
| 写运行时环境参数、`SysParams[...]`、`#Func() with array(...)` | [11_runtime_context_and_with.md](11_runtime_context_and_with.md) | | 写运行时环境参数、`SysParams[...]`、`#Func() with array(...)` | [11_runtime_context_and_with.md](11_runtime_context_and_with.md) |
| 先避开高频误写 | [12_pitfalls.md](12_pitfalls.md) | | 先避开高频误写 | [12_pitfalls.md](12_pitfalls.md) |
| 写数组扩展、键表、矩阵样数据 | [13_matrix_and_collections.md](13_matrix_and_collections.md) | | 写数组扩展、键表、矩阵样数据 | [13_matrix_and_collections.md](13_matrix_and_collections.md) |
| 写结果集过滤专题 | [14_resultset_and_filters.md](14_resultset_and_filters.md) | | 写结果集过滤专题 | [14_resultset_and_filters.md](14_resultset_and_filters.md) |
| 写 TS-SQL 专题 | [15_ts_sql.md](15_ts_sql.md) | | 写 TS-SQL 专题 | [15_ts_sql.md](15_ts_sql.md) |
| 看调试与 profiler 专题 | [16_debug_and_profiler.md](16_debug_and_profiler.md) | | 看调试与 profiler 专题 | [16_debug_and_profiler.md](16_debug_and_profiler.md) |
| 看词法、注释、编译选项 | [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md) | | 看词法、注释、编译选项 | [18_lexical_structure_and_compile_options.md](18_lexical_structure_and_compile_options.md) |
| 看类型与转换 | [19_types_and_conversions.md](19_types_and_conversions.md) | | 看类型与转换 | [19_types_and_conversions.md](19_types_and_conversions.md) |
| 看字符串与编码专题 | [20_strings_and_text.md](20_strings_and_text.md) | | 看字符串与编码专题 | [20_strings_and_text.md](20_strings_and_text.md) |
| 看 `external`、DLL 与多线程 | [21_external_calls_and_threads.md](21_external_calls_and_threads.md) | | 看 `external`、DLL 与多线程 | [21_external_calls_and_threads.md](21_external_calls_and_threads.md) |
| 看 `namespace`、单元运行时、`Libpath`、查找路径 | [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) | | 看 `namespace`、单元运行时、`Libpath`、查找路径 | [22_namespace_libpath_and_unit_runtime.md](22_namespace_libpath_and_unit_runtime.md) |
| 看对象运行时和反射 | [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) | | 看对象运行时和反射 | [23_object_runtime_and_introspection.md](23_object_runtime_and_introspection.md) |
| 看运行时内置对象 | [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md) | | 看运行时内置对象 | [24_builtin_runtime_objects.md](24_builtin_runtime_objects.md) |
| 看集合运算 | [25_set_operations.md](25_set_operations.md) | | 看集合运算 | [25_set_operations.md](25_set_operations.md) |
| 看矩阵深水专题 | [26_matrix_deep_dive.md](26_matrix_deep_dive.md) | | 看矩阵深水专题 | [26_matrix_deep_dive.md](26_matrix_deep_dive.md) |
| 看 `FMArray` | [27_fmarray.md](27_fmarray.md) | | 看 `FMArray` | [27_fmarray.md](27_fmarray.md) |
| 看 TS-SQL 基础 | [28_ts_sql_core.md](28_ts_sql_core.md) | | 看 TS-SQL 基础 | [28_ts_sql_core.md](28_ts_sql_core.md) |
| 看 TS-SQL 进阶 | [29_ts_sql_advanced.md](29_ts_sql_advanced.md) | | 看 TS-SQL 进阶 | [29_ts_sql_advanced.md](29_ts_sql_advanced.md) |
| 看网格计算与全局缓存 | [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) | | 看网格计算与全局缓存 | [30_runtime_services_and_global_cache.md](30_runtime_services_and_global_cache.md) |
| 看复数与弱引用 | [31_complex_and_weakref.md](31_complex_and_weakref.md) | | 看复数与弱引用 | [31_complex_and_weakref.md](31_complex_and_weakref.md) |
| 看对象算符与遍历重载 | [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) | | 看对象算符与遍历重载 | [32_object_overloads_and_iteration.md](32_object_overloads_and_iteration.md) |
| 看较新表达式或表达式边界 | [07_expressions_and_operators.md](07_expressions_and_operators.md) | | 看较新表达式或表达式边界 | [07_expressions_and_operators.md](07_expressions_and_operators.md) |
| 看较新对象能力或类边界 | [09_objects_and_classes.md](09_objects_and_classes.md) | | 看较新对象能力或类边界 | [09_objects_and_classes.md](09_objects_and_classes.md) |
| 看资料冲突 / 解释器差异 | 先留在当前页，对照上面的主线与深水进入条件后，再按主题进入相应页面 | | 看资料冲突 / 解释器差异 | 先留在当前页，对照上面的主线与深水进入条件后，再按主题进入相应页面 |
| 看高频误写 / 反例 / 负向边界 | [12_pitfalls.md](12_pitfalls.md) | | 看高频误写 / 反例 / 负向边界 | [12_pitfalls.md](12_pitfalls.md) |
| 看正式语法手册当前覆盖范围与成熟度 | [coverage_map.md](coverage_map.md) | | 看正式语法手册当前覆盖范围与成熟度 | [coverage_map.md](coverage_map.md) |
## 旧 8 章在正式手册中的落点 ## 旧 8 章在正式手册中的落点

44
templates/memory-bank/architecture.template.md
View File

@ -1,44 +0,0 @@
# 架构设计
<!--
填写指南：
- 【必填】：项目启动前必须填写
- 【可选】：按需填写，可随项目发展补充
- 小项目可只填核心模块，架构图可后补
-->
## 整体架构
<!-- 【可选】项目成熟后补充 -->
```txt
{{ARCHITECTURE_DIAGRAM}}
```
## 核心模块
<!-- 【必填】至少列出主要模块 -->
### {{MODULE_1}}
**职责**：{{MODULE_1_DESC}}
## 关键约束
<!-- 【可选】 -->
- {{CONSTRAINT_1}}
## 扩展点
<!-- 【可选】大项目建议填写 -->
### {{EXTENSION_1}}
**步骤**：
1. {{STEP_1}}
---
**最后更新**：{{DATE}}

62
templates/memory-bank/tech-stack.template.md
View File

@ -1,62 +0,0 @@
# 技术栈与工具链
<!--
填写指南：
- 【必填】：项目启动前必须填写
- 【可选】：按需填写，可随项目发展补充
- 未填写的占位符保持原样或删除整行
-->
## 核心技术
<!-- 【必填】 -->
**文件类型**：{{FILE_TYPES}}
## 项目结构
<!-- 【必填】 -->
```text
{{PROJECT_NAME}}/
├── {{DIR_1}}/ # {{DIR_1_DESC}}
└── memory-bank/ # 项目上下文
```
## 开发环境
<!-- 【必填】至少填写运行测试命令 -->
**必需工具**：
- {{TOOL_1}}
**运行测试**：
```bash
{{TEST_CMD}}
```
## 依赖管理
<!-- 【可选】 -->
**外部依赖**：
- {{EXTERNAL_DEP_1}}
## 测试策略
<!-- 【可选】大项目建议填写 -->
**测试类型**：
- {{TEST_TYPE_1}}
**验证标准**：
- {{PASS_CONDITION_1}}
---
**最后更新**：{{DATE}}

62
templates/prompts/README.md
View File

@ -1,6 +1,6 @@
# 提示词库 # 提示词入口
本目录包含 AI 代理的工作流程参考模板。 本目录包含 AI 代理的工作流入口模板，用于把任务路由到合适的执行路径。
## 目录结构 ## 目录结构
@ -8,44 +8,62 @@
prompts/ prompts/
├── README.md # 本文件 ├── README.md # 本文件
├── system/ ├── system/
│ └── agent-behavior.md # 工作模式参考 │ └── agent-behavior.md # 工作流入口
├── coding/ ├── coding/
│ ├── clarify.md # 需求澄清模板 │ ├── clarify.md # 需求澄清模板
│ ├── review.md # 复盘总结模板 │ ├── verify-change.md # 变更验证模板
│ ├── close-task.md # 本轮收尾模板
│ ├── update-memory.md # 回写记忆模板
│ └── code-review.md # MR/PR 代码评审流程 │ └── code-review.md # MR/PR 代码评审流程
└── meta/
└── prompt-generator.md # 元提示词生成器
``` ```
## 使用方式 ## 使用方式
| 模板 | 触发场景 | | 模板 | 触发场景 |
| ----------------------- | ------------------------------ | | --------------------- | -------------------- |
| **agent-behavior.md** | 切换工作模式（探索/开发/调试） | | **agent-behavior.md** | 选择工作流入口 |
| **clarify.md** | 需求不明确时澄清 | | **clarify.md** | 需求不明确时澄清 |
| **review.md** | Plan 完成后复盘总结 | | **verify-change.md** | 声称完成前做验证 |
| **code-review.md** | 执行 MR/PR 代码评审 | | **close-task.md** | 本轮工作收尾 |
| **prompt-generator.md** | 创建新的专用提示词 | | **update-memory.md** | 上下文变化后回写记忆 |
| **code-review.md** | 执行 MR/PR 代码评审 |
## 工作流程 ## 工作流程
``` ```text
需求不清 → clarify.md 需求不清 → clarify.md
↓ ↓
头脑风暴 → $brainstorming skill 入口约束 → using-superpowers
↓ ↓
生成计划 → $writing-plans skill → docs/plans/*.md 头脑风暴 → $brainstorming skill → docs/superpowers/specs/*-design.md
↓ ↓
执行计划 → AGENT_RULES 主循环（`main_loop.py claim/finish` 留痕） spec 完成后 → `playbook.py -record-spec <path> -progress memory-bank/progress.md`
↓
生成计划 → $writing-plans skill → docs/superpowers/plans/*.md
↓
plan 完成后 → `playbook.py -record-plan <path> -progress memory-bank/progress.md`
↓
领取计划 → `main_loop.py claim`
↓
执行计划 → `$executing-plans`
↓
代码类任务 → `karpathy-guidelines` + `.agents/` + `AGENT_RULES.md`
↓
写回状态 → `main_loop.py finish`
↓
更新摘要 → update-memory.md
↓
验证改动 → verify-change.md
↓
本轮收尾 → close-task.md
↓ ↓
代码评审（有 MR/PR 时）→ code-review.md 代码评审（有 MR/PR 时）→ code-review.md
↓
完成复盘 → review.md
↓
沉淀提示词 → prompt-generator.md（可选）
``` ```
> **核心规则在 `AGENT_RULES.md`**，第三方 skills 只负责规划；执行与留痕必须走 `main_loop.py claim/finish`。 > `prompts/` 是入口层；核心规则在 `AGENT_RULES.md`，
> 长期记忆在 `memory-bank/`，状态留痕必须走
> `playbook.py -record-spec/-record-plan` 与
> `main_loop.py claim/finish`。
--- ---

12
templates/prompts/coding/code-review.template.md
View File

@ -69,12 +69,12 @@ gh pr diff <PR_NUMBER>
## AI 与人工的分工 ## AI 与人工的分工
| 维度 | 负责方 | 说明 | | 维度 | 负责方 | 说明 |
| ---- | ------ | ---- | | -------------------------- | ------------- | ------------------------------------- |
| Bug、逻辑漏洞、安全问题 | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 | | Bug、逻辑漏洞、安全问题 | **AI + 人工** | AI 负责初筛与证据收集，结论需人工复核 |
| 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳 | | 代码清晰度、KISS、单一职责 | **AI + 人工** | AI 提供候选问题，人工决定是否采纳 |
| 架构合理性、业务对齐 | **人工** | AI 反馈少且准确率低，需人工把关 | | 架构合理性、业务对齐 | **人工** | AI 反馈少且准确率低，需人工把关 |
| 兼容性、历史债务、战略取舍 | **人工** | 依赖背景知识，AI 难以判断 | | 兼容性、历史债务、战略取舍 | **人工** | 依赖背景知识，AI 难以判断 |
> 规则：AI 结论必须附文件路径、行号或可复现依据；缺少证据时按待确认假设处理。 > 规则：AI 结论必须附文件路径、行号或可复现依据；缺少证据时按待确认假设处理。
> >

66
templates/prompts/coding/review.template.md
View File

@ -1,66 +0,0 @@
# 复盘模板
<!--
用途：Plan 或阶段完成后的回顾总结
触发：主循环汇总报告时、阶段性工作完成时
-->
## 何时使用
- 一批 Plan 执行完毕后
- 阶段性工作告一段落
- 遇到重大阻塞需要总结
---
## 复盘格式
```markdown
# 复盘: [日期/阶段名称]
## 完成情况
### 已完成
- [x] Plan 1: 简述
- [x] Plan 2: 简述
### 阻塞
- [ ] Plan 3: 阻塞原因
### 跳过
- [ ] Plan 4: 跳过原因
## 关键发现
### 做得好的
- 发现1
- 发现2
### 待改进
- 问题1 → 建议改进方式
- 问题2 → 建议改进方式
## 决策记录
| 决策 | 理由 | 影响 |
|------|------|------|
| 决策1 | 为什么 | 影响范围 |
## 下一步
- [ ] 待处理事项1
- [ ] 待处理事项2
```
---
## 复盘原则
- **客观记录**：如实记录完成/阻塞/跳过
- **提取经验**：总结做得好的和待改进的
- **决策留痕**：重要决策记录到 decisions.md
- **明确下一步**：列出后续待处理事项
---
**最后更新**：{{DATE}}