csh/tsl-devkit
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
3d83740f88b6aaba6962256be517656496b83f25
tsl-devkit/docs/tsl/index.md
T
csh 3d83740f88 Squashed 'docs/standards/playbook/' changes from c3f8137..25d895d 
25d895d 🐛 fix(gitea_workflow): clean up temp repos after job steps
2bc3b11 🐛 fix(gitea_workflow): clean up temporary repo dirs in workflows
98c3f30 📝 docs(agent_rules): allow plan execution on current branch
16c7230 📝 docs(prompts): define custom verify layering
8efc4dd 🐛 fix(skills): quote commit-message description
bc8498f 🐛 fix(ci): install tomli for gitea tests
55cda3b 🐛 fix(tests): report missing toml parser clearly
c0729c7 🐛 fix(playbook): import Optional for cli compatibility
63e24bf 📦 deps(skills): sync thirdparty skills
d2f9356 🐛 fix(ci): isolate gitea workflow repos
588b81d 🐛 fix(ci): inline gitea workflow bootstrap
e0b1c3a ♻️ refactor(skills): standardize first-party skill contracts
2c5050d ♻️ refactor(skills): rename repo skills source dir
f049dfb 📦 deps(skills): drop duplicate first-party superpowers skills
234b335 ✨ feat(workflow): add superpowers planning and execution state tracking
c1702a6 📝 docs(markdown): format tracked markdown and drop stale templates
2325409 📝 docs(markdown): clarify optional markdownlint usage
214c44e 🔧 chore(markdown): add markdownlint baseline and lint fixes
a22b324 📝 docs(templates): add execution and memory-bank prompt templates
223a797 📝 docs(templates): update README for Claude Code and current features
4ac8672 📝 docs: simplify README + platform-agnostic tools + auto-create local rules
2431c9d 📝 docs: add claude_md config and use cross-platform paths
d64b248 📝 docs: fix README.md inaccuracies and add Claude Code info
c8d6bf2 🐛 fix(playbook): use relative paths in CLAUDE.md when not at project root
6518f0f ✨ feat(playbook): auto-create CLAUDE.md with path discovery
6ec9a45 ✨ feat(skills): add skill_link symlink support + platform-agnostic prompt
9f8b6b5 📝 docs: update README and config example for Claude Code support
79cff6c 📝 docs(skills): add Claude Code platform support
452c6f5 ✨ feat(playbook): auto-inject AGENTS.md into CLAUDE.md
e1dbf3c 🐛 fix(skills): remove dual-path from commit-message skill
f3a7259 🔧 chore(ci): use prepare_repo.sh in both workflows
da08212 🔧 chore(ci): extract prepare_repo.sh and clean up workflows
7ade85e 🗑️ remove(tsl): drop syntax_book/, data/ source and build script
f94dba0 ♻️ refactor(skills): update playbook.py and tests for thirdparty/ layout
b3df412 ♻️ refactor(skills): separate thirdparty skills into thirdparty/ subdirectory
64950e7 📦 deps(skills): sync thirdparty skills
a2e3cb0 ✨ feat(playbook): add no_backup deploy controls
8609d59 🐛 fix(docs): repair reference catalog source links
956da11 🐛 fix(playbook): publish hidden ci test fixes
3f67754 📦 deps(skills): sync thirdparty skills
08ca87b 📦 deps(skills): add karpathy thirdparty sync
96b705b 📝 docs(tsl): rebuild canonical syntax and routing manual
3ed5052 📦 deps(skills): sync thirdparty skills
60108dd 📦 deps(skills): sync thirdparty skills
da85d4e 🐛 fix(thirdparty): prune nested project snapshots
a2a697e 📦 deps(skills): sync thirdparty skills
9df610a 🐛 fix(thirdparty): exclude duplicated superpowers skills
33dd5bb 🐛 fix(thirdparty): preserve optional manifest fields
91b0ea7 🐛 fix(thirdparty): preserve manifest during snapshot update
2e26f98 🔧 chore(thirdparty): generalize skills sync pipeline
5b9c1e3 📦 deps(skills): sync superpowers
2f2d34a 📝 docs(readme): normalize subtree command spacing
62db7db 🐛 fix(ci): serialize superpowers update and sync
3463223 🐛 fix(ci): use literal superpowers sync paths
48f6de8 📦 deps(skills): sync superpowers
4b23529 🔧 chore(ci): merge superpowers update and sync workflow
a56d75b 📦 deps(skills): sync superpowers
84bcefa 🔧 chore(ci): use ci[bot] commit author name
00a07e5 📦 deps(skills): sync superpowers
7b84daf 🐛 fix(templates): enforce main loop progress tracking
51373d7 🔧 chore(ci): automate superpowers sync workflow
eaaa39c 🐛 fix(ci): prevent stale superpowers sync from restoring skills block
79755c6 📦 deps(skills): sync superpowers
836d878 📦 deps(skills): sync superpowers
8216c9f 📦 deps(skills): sync superpowers
9439505 🐛 fix(playbook): address reported repo issues

git-subtree-dir: docs/standards/playbook
git-subtree-split: 25d895d8b3f56624ccfe99ad7289e9eb49e0f316
2026-05-24 13:04:14 +08:00

112 lines
11 KiB
Markdown
Raw Blame History

# TSL Index
文档类型：检索页
是否可直接用于生成代码：否
是否含已验证可执行示例：否
是否含已验证反例：否
遇到不确定时跳转到：[syntax/index.md](syntax/index.md)、[finance/index.md](finance/index.md)、[reference/index.md](reference/index.md)、[modules/index.md](modules/index.md)、项目自身文档、`scripts/*` 入口脚本、CI 配置
这个入口文件只负责一件事：让新 session 先判断主问题属于哪一层，再进入最相关的单个入口页。
## 先记住这些规则
- 先读本文件，不要默认通读全部 TSL 文档。
- 语言怎么写的问题，先从 `docs/tsl/syntax/` 开始。
- 指标、选股、回测和策略流程的问题，先从 `docs/tsl/finance/` 开始；不要先把业务问题拆成纯语法问题。
- 某个函数怎么用、属于哪个函数库分类或目录，先从 `docs/tsl/reference/` 开始。
- 现成模块、外部集成和互操作问题，先从 [modules/index.md](modules/index.md) 开始。
- 账户体系、真实接口名、部署方式、脚本入口、权限模型、环境变量、CI、验证命令这类问题，先按“项目依赖 / 项目执行”处理；优先回项目自身文档、`scripts/*` 入口脚本、CI 配置。
- [toolchain.md](toolchain.md) 不是 TSL 语法子类，而是项目执行类辅证页；只有当前项目已经补齐工具链与验证信息时才使用；如果这页仍是模板，不把它当主入口。
- 顶层主体优先按四类理解：松散语句、`function / procedure`、`type Name = class`、`unit`。
- 不要把顶层 `function / procedure` 定义和松散语句混在同一个文件模型里。
- 任何语法判断都先看正式语法页结论。
- 如果涉及较新写法、资料冲突或解释器差异，先回到 `docs/tsl/syntax/index.md`，再按主题跳到对应语法页；只有对应主题页仍然没有结论时，才本地用 `tsl` 验证。
- 如果涉及高频误写、反例或负向边界，优先回到 `docs/tsl/syntax/12_pitfalls.md`；只有结论缺失时，才本地用 `tsl` 验证。
- 模板、错误示例和输出片段不算可独立编译代码。
## 元数据与证据标签
- 页头里的 `是否可直接用于生成代码` 只做页面级粗判断；如果页内已经给出 `代码块身份`，一律以块级标签为准。
- `是否可直接用于生成代码` 有三种值：`是`、`否`、`仅部分`；其中 `仅部分` 表示页内既有可直接参考的块，也有依赖多文件、查找路径或运行时环境的块，必须继续看块级标签。
- `是否含已验证可执行示例` 只统计已经跑通、可以直接参考外形的正向代码示例。
- `是否含已验证反例` 只统计已经确认不能照写的负向例子。
- `代码块身份` 只使用固定词表：`已验证可执行示例`、`已验证输出片段`、`反例 / 不可照写`、`配置片段 / 概念骨架`。
- 如果还需要补充用途、限制或复用建议，单独写 `代码块说明`，不要把说明文字继续拼进 `代码块身份`。
- 如果页头里的 `遇到不确定时跳转到` 列出多个目标，默认第一项是优先入口，后面的目标只用于分流或补证。
## 新 session 起手规则
### If / Then 路由
- If 问题在问“语言怎么写”，then 先从 [syntax/index.md](syntax/index.md) 开始。
- If 问题在问“指标 / 选股 / 回测怎么组织”，then 先从 [finance/index.md](finance/index.md) 开始。
- If 问题在问“某个函数怎么用”或“函数属于哪个函数库分类 / 目录”，then 先从 [reference/index.md](reference/index.md) 开始。
- If 问题在问“现成模块 / 集成 / 互操作”，then 先从 [modules/index.md](modules/index.md) 开始。
- If 问题依赖项目实际接口、账户体系、部署方式、脚本入口、权限模型、环境变量、CI 或验证命令，then 不把它当通用 TSL 事实；优先回项目自身文档、`scripts/*` 入口脚本、CI 配置；只有当前项目已补齐时，才把 [toolchain.md](toolchain.md) 当辅证页。
- If 问题在问“这句语法能不能写”，then 先从 [syntax/index.md](syntax/index.md) 开始。
- If 问题在问“较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界”，then 先看 [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页。
- If 问题在问“高频误写 / 反例核对 / 负向边界”，then 先看 [syntax/12_pitfalls.md](syntax/12_pitfalls.md)。
### Tie-Break
- If 一个问题同时涉及业务和语法，then 先按主问题分层。
- If 主问题是业务实现，then 先走 `finance/` 或 `modules/`，语法只作辅证，不反过来吞掉业务入口。
- If 主问题是语言写法，then 先走 `syntax/`，金融或模块页只作为示例和上下文。
- If 主问题已经落到真实接入参数、账号来源、部署依赖、执行入口或权限模型，then 直接转“项目依赖 / 项目执行”确认，不继续在 `modules/`、`syntax/` 或模板型 `toolchain.md` 里兜圈子。
### 语言事实
- 可以先把 TSL 当成 Pascal 风格语言去理解：`function`、`begin`、`end`、`unit`、`uses` 都很接近；但这里只借外形，不默认继承 Pascal 的全部语义、库习惯和文件模型。
- 涉及赋值、`function / procedure` 外形、`unit` 骨架、命名参数、`type Name = class`、数组 / 字符串下标这类高频硬规则，统一以 [syntax/02_quickstart.md](syntax/02_quickstart.md) 的“语言核心事实速查”为准；当前页只保留跨层路由所需的最小提醒。
#### 写代码前先记住
- 写代码前先把高频硬规则收口到 [syntax/02_quickstart.md](syntax/02_quickstart.md)，不要分别从入口页、介绍页和文件模型页拼接结论。
- 顶层主体仍优先按四类理解：松散语句、`function / procedure`、`type Name = class`、`unit`。
- 模板、错误示例和输出片段不算可独立编译代码；真正落代码时优先看块级 `代码块身份`。
### 手册建模规则
- 更可靠的识别方式是看顶层内容，而不是只看文件扩展名。
- 顶层允许出现 `uses`，但这里只把它当辅助语句，不把它当主体声明。
- 下游大量 `program test; begin ... end.` 形式，只作为自包含验证样例外壳，不作为这里归纳的正式顶层模型。
## 如果你马上要写 TSL
- 先看 [syntax/02_quickstart.md](syntax/02_quickstart.md)
- 再看 [syntax/index.md](syntax/index.md)
- 然后看 [syntax/12_pitfalls.md](syntax/12_pitfalls.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/index.md](syntax/index.md) |
| 我要核对较新写法 / 新能力并入 / 资料冲突 / 解释器版本边界 | [syntax/index.md](syntax/index.md)，再按主题跳到对应语法页 |
| 我要核对高频误写 / 反例 / 负向边界 | [syntax/12_pitfalls.md](syntax/12_pitfalls.md) |
| 我要知道正式语法手册现在还差什么 | [syntax/coverage_map.md](syntax/coverage_map.md) |
| 我要写金融指标 / 选股 / 回测 | [finance/index.md](finance/index.md) |
| 我要看模块 / 集成 / 互操作入口 | [modules/index.md](modules/index.md) |
| 我要确认账户体系 / 真实接口 / 部署方式 / 脚本入口 / 环境变量 / CI / 验证命令 | 项目自身文档、`scripts/*` 入口脚本、CI 配置；当前项目已补齐时再看 [toolchain.md](toolchain.md) |
| 我要看回测框架模块 | [modules/tsbacktesting.md](modules/tsbacktesting.md) |
| 我要看 Python 互操作 | [modules/tsl_python_interop.md](modules/tsl_python_interop.md) |
| 我要看微信消息推送 | [modules/wechat_message.md](modules/wechat_message.md) |
| 我要看 Python API | [modules/pytsl_api.md](modules/pytsl_api.md) |
| 我要查函数库 | [reference/index.md](reference/index.md) |
| 当前项目已补齐工具链时，看工具链 / 项目执行辅证 | [toolchain.md](toolchain.md) |
| 我要避开高频误写 | [syntax/12_pitfalls.md](syntax/12_pitfalls.md) |
## 进入之后怎么读
1. 先判断主问题属于语法、业务、函数库、模块/集成，还是项目依赖 / 项目执行。
2. 如果主问题是项目依赖 / 项目执行，直接回项目自身文档、`scripts/*` 入口脚本或 CI 配置；只有当前项目已经补齐时，才把 [toolchain.md](toolchain.md) 当辅证。
3. 否则先进入一个最相关的入口页，不要同时展开多个层。
4. 当前页如果已经给出结论，先采用；准备编写时优先找已验证正例，再落代码；只有需要补充时再跳到相邻页。
5. 遇到“资料写法不一致”且偏较新写法、资料冲突或解释器差异时，先回 [syntax/index.md](syntax/index.md) 按主题跳到对应语法页。
6. 遇到“资料写法不一致”且偏高频误写、反例或负向边界时，先看 [syntax/12_pitfalls.md](syntax/12_pitfalls.md)。
7. 只有当前手册没有给出结论时，才写最小 `.tsl` / `.tsf` 例子并用 `tsl` 实测。
Reference in New Issue View Git Blame Copy Permalink