📝 docs(tsl): rebuild canonical syntax and routing manual
This commit is contained in:
@@ -26,11 +26,14 @@ Playbook：工程规范与代理规则合集，当前覆盖：
|
||||
|
||||
- `docs/index.md`：文档导航（跨语言 common / TSL / C++ / Python / TypeScript / Markdown）。
|
||||
- `docs/common/commit_message.md`：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。
|
||||
- `docs/tsl/index.md`：TSL canonical 入口（语法 / 金融 / 模块 / 函数检索四层）。
|
||||
- `docs/tsl/code_style.md`：TSL 代码结构、格式、`begin/end`
|
||||
代码块、注释与通用最佳实践。
|
||||
- `docs/tsl/naming.md`：TSL 命名规范（顶层声明、文件同名规则、变量/成员/property、常量、集合命名等）。
|
||||
- `docs/tsl/syntax_book/index.md`：TSL 语法手册（整理自原始语法/机制目录册；函数库位于
|
||||
`docs/tsl/syntax_book/function/`，按需检索）。
|
||||
- `docs/tsl/syntax/index.md`：TSL 语法手册。
|
||||
- `docs/tsl/finance/index.md`：TSL 金融业务层入口（指标、选股、回测与业务流程问题）。
|
||||
- `docs/tsl/modules/index.md`：TSL 模块层入口（pyTSL、微信消息、Python 互操作、回测框架）。
|
||||
- `docs/tsl/reference/index.md`：TSL 函数检索入口（模块目录位于 `docs/tsl/reference/catalog/`）。
|
||||
- `docs/tsl/toolchain.md`：TSL 工具链与验证命令模板。
|
||||
- `docs/cpp/code_style.md`：C++ 代码风格（C++23/Modules）。
|
||||
- `docs/cpp/naming.md`：C++ 命名规范（Google 基线）。
|
||||
@@ -112,7 +115,6 @@ Layer 1: rulesets/ (≤50 行/语言，模板源)
|
||||
└─ 指向 Skills 和 docs
|
||||
|
||||
Layer 2: codex/skills/ (按需加载，$skill-name 触发)
|
||||
├─ tsl-guide: TSL 渐进式语法教学
|
||||
├─ commit-message: 提交信息规范
|
||||
├─ style-cleanup: 代码风格整理
|
||||
└─ bulk-refactor-workflow: 批量重构流程
|
||||
@@ -162,9 +164,7 @@ Layer 3: docs/ (权威静态文档)
|
||||
|
||||
本仓库内置一组 Codex CLI skills（见 `codex/skills/`），用于按需加载的工作流与知识库。
|
||||
|
||||
**核心 Skills**：
|
||||
|
||||
- **`$tsl-guide`**：TSL/TSF 语法完整指南（基础/高级/函数库/最佳实践）
|
||||
TSL 相关问题直接查阅 `rulesets/tsl/index.md` 与 `docs/tsl/`。
|
||||
|
||||
**通用 Skills**：
|
||||
|
||||
@@ -177,22 +177,29 @@ Layer 3: docs/ (权威静态文档)
|
||||
|
||||
## 在其他项目中使用本 Playbook
|
||||
|
||||
由于本仓库需要内部权限访问，其他项目**不能仅用外链引用**；推荐把 Playbook 规范 vendoring 到项目内，并用统一入口执行。
|
||||
由于本仓库需要内部权限访问，其他项目**不能仅用外链引用**；推荐把 Playbook 规范部署到项目内，并用统一入口执行。
|
||||
|
||||
### 快速决策：我应该用哪种方式？
|
||||
|
||||
| 你的情况 | 推荐方式 | 优势 |
|
||||
| ---------------------------------- | ------------------------------- | ------------------------------- |
|
||||
| 新项目，需要持续同步更新 | 方式一：git subtree | 可随时拉取最新标准，版本可追溯 |
|
||||
| 只需要一次性引入，不常更新 | 方式二：手动复制快照 | 简单直接，无需 git subtree 知识 |
|
||||
| 只需要部分语言（且希望快照也裁剪） | 方式三：CLI 裁剪复制（vendor） | 快照只包含所需语言（更小） |
|
||||
| **不确定？** | **方式一：git subtree（推荐）** | 最灵活，后续可随时同步更新 |
|
||||
| 你的情况 | 推荐方式 | 优势 |
|
||||
| --- | --- | --- |
|
||||
| 新项目，需要持续同步更新 | 方式一：`git subtree` | 标准留在项目内，后续可拉取更新 |
|
||||
| 不想把 Playbook 以 subtree 嵌进仓库，但仍要把标准部署到项目内 | 方式二：外部 clone 后执行部署 | Playbook 仓库与业务仓库解耦，部署根目录可配置 |
|
||||
| **不确定？** | **方式一：`git subtree`（推荐）** | 项目内可见、版本可追溯、使用路径最稳定 |
|
||||
|
||||
---
|
||||
|
||||
### TL;DR - 30 秒快速开始
|
||||
|
||||
以 TSL 为例：
|
||||
先区分三个路径概念：
|
||||
|
||||
- `project_root`：目标项目根目录。
|
||||
- `deploy_root`：相对于 `project_root` 的项目内目标目录。
|
||||
- 外部 clone 出来的 Playbook 路径，例如 `C:/tools/playbook`：只是执行部署脚本的位置，不是外部 clone 出来的 Playbook 仓库路径对应的部署目标。
|
||||
|
||||
以 TSL 为例，Playbook 在项目内的默认部署根是 `docs/standards/playbook`；如果你把 `deploy_root` 改成 `custom/playbook`，则部署结果会落到 `<project_root>/custom/playbook`，文档和脚本入口也会跟着变成 `custom/playbook/docs/...`、`custom/playbook/scripts/...`。
|
||||
|
||||
#### 方式一：`git subtree`
|
||||
|
||||
```bash
|
||||
# 1. 引入标准快照
|
||||
@@ -255,38 +262,51 @@ git commit -m ":package: deps(playbook): add tsl standards"
|
||||
|
||||
---
|
||||
|
||||
### 方式二：手动复制快照
|
||||
### 方式二：外部 clone 后执行部署
|
||||
|
||||
如果不使用 git subtree，也可手动复制快照到目标项目：
|
||||
如果你不想把 Playbook 以 `git subtree` 嵌进目标项目，可以把 Playbook clone 到项目外部，再由该 clone 直接把标准部署进目标项目。
|
||||
|
||||
1. 创建目录：`docs/standards/playbook/`。
|
||||
2. 复制 Playbook 快照内容（建议使用方式三生成裁剪快照）。
|
||||
3. 在项目根执行统一入口：
|
||||
1. 先在任意位置 clone Playbook：
|
||||
|
||||
```bash
|
||||
python docs/standards/playbook/scripts/playbook.py -config playbook.toml
|
||||
git clone https://git.mytsl.cn/csh/playbook.git C:/tools/playbook
|
||||
```
|
||||
|
||||
---
|
||||
2. 在目标项目根创建 `playbook.toml`，并用 `deploy_root` 指定项目内的部署根。例如：
|
||||
|
||||
### 方式三：CLI 裁剪复制（按语言，离线）
|
||||
- `project_root` 写目标项目根目录。
|
||||
- `deploy_root` 写目标项目内的相对路径。
|
||||
- 不要把外部 clone 的 `C:/tools/playbook` 这类路径写进 `deploy_root`；那只是你执行脚本的位置。
|
||||
|
||||
当你希望只 vendoring 需要的语言规范（例如只需要 `tsl` + `cpp`）时：
|
||||
```toml
|
||||
[playbook]
|
||||
project_root = "."
|
||||
deploy_root = "custom/playbook"
|
||||
|
||||
```toml
|
||||
# playbook.toml
|
||||
[playbook]
|
||||
project_root = "/path/to/target-project"
|
||||
[vendor]
|
||||
langs = ["tsl"]
|
||||
|
||||
[vendor]
|
||||
langs = ["tsl", "cpp"]
|
||||
```
|
||||
[sync_standards]
|
||||
langs = ["tsl"]
|
||||
|
||||
```bash
|
||||
python scripts/playbook.py -config playbook.toml
|
||||
```
|
||||
[sync_rules]
|
||||
|
||||
该动作仅生成裁剪快照，不会隐式同步 `.agents/` 或 `.gitattributes`；后续请用 `sync_standards` 明确落地。
|
||||
[sync_memory_bank]
|
||||
project_name = "MyProject"
|
||||
```
|
||||
|
||||
3. 在目标项目根执行外部 clone 里的统一入口：
|
||||
|
||||
```bash
|
||||
python C:/tools/playbook/scripts/playbook.py -config playbook.toml
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- 这里的 `[vendor]` 是“把 Playbook 快照部署进目标项目”的执行步骤，不是第三种正式部署路线。
|
||||
- `deploy_root` 永远表示目标项目内的部署目录；它不是外部 clone 出来的 Playbook 仓库路径。
|
||||
- 外部 clone 场景下必须显式填写 `deploy_root`；脚本不会替你补默认部署目录。
|
||||
- 如果 `deploy_root = "custom/playbook"`，部署后的项目内入口会是 `custom/playbook/scripts/playbook.py`、`custom/playbook/docs/index.md`。
|
||||
|
||||
---
|
||||
|
||||
@@ -320,10 +340,12 @@ python scripts/playbook.py -config playbook.toml
|
||||
│ ├── typescript/ # TypeScript/JavaScript 规则集（同上）
|
||||
│ └── markdown/ # Markdown 规则集（仅代码格式化）
|
||||
├── .gitattributes # 行尾/文本规范
|
||||
├── docs/
|
||||
│ ├── standards/
|
||||
│ │ └── playbook/ # 本 Playbook 快照（git subtree/vendoring）
|
||||
│ └── project/ # 项目自有文档（架构、ADR、运行方式等）
|
||||
├── <deploy_root>/ # 本 Playbook 在项目内的部署根（默认 docs/standards/playbook）
|
||||
│ ├── docs/
|
||||
│ ├── rulesets/
|
||||
│ ├── scripts/
|
||||
│ └── templates/
|
||||
├── docs/project/ # 项目自有文档（架构、ADR、运行方式等）
|
||||
├── playbook.toml # 统一入口配置
|
||||
└── src/ # 源码目录（按项目实际情况）
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user