Squashed 'docs/standards/playbook/' content from commit e504a68

git-subtree-dir: docs/standards/playbook
git-subtree-split: e504a689dcf2e2fdeeb64097930347d504e68f5f

docs/common/commit_message.md

@@ -0,0 +1,161 @@
+# 提交信息规范（Commit Messages）
+
+提交信息用于清晰表达变更意图、范围和原因，便于回溯与自动化发布。
+
+## 1. 目标
+
+- 让每次提交都能被独立理解。
+- 支持快速定位问题与版本回滚。
+- 可被工具解析（变更日志/发布流程）。
+
+## 2. 格式
+
+推荐使用以下结构（emoji 可选，但建议默认带上以便快速扫读）：
+
+```txt
+:emoji: type(scope): subject
+
+body
+
+footer
+```
+
+- `emoji`：可选，位于首行行首；若使用，必须与 `type` 一一对应（见 4）。为保持一致性，建议默认使用 emoji；若不使用则省略即可。
+- `type`：变更类型，必须从 4 的对应表中选取。
+- `scope`：可选，业务域/组件名（`lower_snake_case`），用于辅助定位影响范围。
+- `subject`：一句话概述，使用祈使句/现在时，首字母小写，不加句号。
+- `body`：可选，说明动机、关键实现、影响面；每行建议 ≤ 72 字符。
+- `footer`：可选，关联任务/缺陷号，或 `BREAKING CHANGE:` 说明不兼容变更。
+
+不使用 emoji 时，首行直接写 `type(scope): subject` 即可。
+
+## 3. 约定
+
+### 3.1 一次提交的边界
+
+- 一个提交对应一个**逻辑变更**，而不是一个文件或一个模块。
+- 可以同时修改多个 `unit/class/function`，只要它们属于同一逻辑变更。
+- **允许合并的情况**：联动修改是变更所必需的同步/适配（不一起提会导致编译失败、测试失败或行为不一致）。
+  - 例：改了 A 的接口签名，同时更新 B 的调用点。
+- **应当拆分的情况**：改动彼此独立，仅是“顺手优化/无关重构/额外功能”。
+  - 例：在修复 A 的 bug 时顺便重构 B 的内部实现。
+- 实用判断：
+  1. 这次提交能用一句话概括吗？若需要两句话，考虑拆分。
+  2. 若只回滚其中一部分，系统还能保持正确吗？不能则不拆。
+  3. 每个提交是否都能保持可运行/可构建/测试不更坏？做不到则合并。
+
+### 3.2 大模块重构的提交拆分
+
+当重构整个模块并影响到其他模块时，建议按“可回滚的小步”拆分提交：
+
+1. **前置整理**：仅做无行为影响的清理（重命名、抽函数、补注释/类型、补测试）。
+2. **核心重构**：在模块内部做结构调整，尽量保持对外接口不变；必要时加适配层。
+3. **迁移调用方**：逐步把其他模块迁移到新接口/新行为上。
+4. **清理旧接口**：确认无人使用后再删除适配层/旧代码。
+
+若重构为破坏性变更，优先采用“两阶段”：先引入新接口并兼容旧接口（deprecated），迁移完成后再删除旧接口。
+
+### 3.3 其他约定
+
+- `subject` 尽量 ≤ 72 字符；必要时用 `body` 补充细节。
+- `body/footer` 说明“为什么改、影响什么”，而不是复述代码。
+
+## 4. 提交类型与 Emoji 对应
+
+本仓库采用固定的 `type`/emoji 一一对应关系；使用 emoji 时必须使用对应的那一个，不得错配。
+
+| type        | emoji（预览 / 代码）                          | 说明                      |
+| ----------- | --------------------------------------------- | ------------------------- |
+| `init`      | :tada: `:tada:`                               | 初始化/首次发布           |
+| `feat`      | :sparkles: `:sparkles:`                       | 新功能                    |
+| `fix`       | :bug: `:bug:`                                 | Bug 修复                  |
+| `perf`      | :rocket: `:rocket:`                           | 性能优化                  |
+| `refactor`  | :recycle: `:recycle:`                         | 重构（行为不变）          |
+| `style`     | :art: `:art:`                                 | 代码样式/格式（行为不变） |
+| `docs`      | :memo: `:memo:`                               | 文档更新                  |
+| `test`      | :white_check_mark: `:white_check_mark:`       | 测试新增/修正             |
+| `deps`      | :package: `:package:`                         | 依赖更新                  |
+| `security`  | :lock: `:lock:`                               | 安全修复                  |
+| `deprecate` | :warning: `:warning:`                         | 废弃/弃用标记             |
+| `remove`    | :wastebasket: `:wastebasket:`                 | 删除功能/代码             |
+| `chore`     | :wrench: `:wrench:`                           | 构建/配置/工具/维护性改动 |
+| `contrib`   | :busts_in_silhouette: `:busts_in_silhouette:` | 贡献者/致谢相关           |
+| `release`   | :bookmark: `:bookmark:`                       | 发布/打版本标签           |
+
+注：`:white_check_mark:` 为补充图例，用于 `test` 类型。
+
+如需新增新的 `type`，必须同时补充对应 emoji 与说明。
+
+---
+
+## 5. 版本号规范（SemVer）
+
+遵循语义化版本规范。
+
+### 5.1 格式
+
+```txt
+MAJOR.MINOR.PATCH
+```
+
+### 5.2 字段说明
+
+| 字段      | 说明     | 何时递增           |
+| --------- | -------- | ------------------ |
+| **MAJOR** | 主版本号 | 不兼容的 API 修改  |
+| **MINOR** | 次版本号 | 向后兼容的功能新增 |
+| **PATCH** | 修订号   | 向后兼容的问题修正 |
+
+### 5.3 更新规则
+
+- **MAJOR（主版本）**：破坏性变更，不向后兼容。递增后 MINOR 和 PATCH 重置为 0。
+- **MINOR（次版本）**：新增功能但保持兼容。递增后 PATCH 重置为 0。
+- **PATCH（修订）**：仅修复 bug，不新增功能。
+
+### 5.4 示例
+
+```txt
+1.0.0    # 首个稳定版
+1.1.0    # 新增功能
+1.1.1    # Bug 修复
+2.0.0    # 破坏性变更
+```
+
+### 5.5 Pre-release 版本
+
+```txt
+1.0.0-alpha.1
+1.0.0-beta
+1.0.0-rc.1
+1.0.0
+```
+
+### 5.6 初始开发阶段
+
+```txt
+0.1.0    # 初始版本
+0.2.0    # API 未稳定
+1.0.0    # 首个稳定版
+```
+
+注意：`0.x.x` 版本可以随时破坏兼容性。
+
+---
+
+## 6. 示例
+
+带 emoji：
+
+```txt
+:sparkles: feat(order): add batch cancel api
+
+support canceling multiple orders in one request; keep old api unchanged.
+
+Refs: TSL-1234
+```
+
+不带 emoji：
+
+```txt
+refactor(order): simplify cancel flow
+```

docs/cpp/clangd.md

@@ -0,0 +1,23 @@
+# clangd 补全配置（`.clangd`）
+
+本章节提供 `clangd` 的推荐配置模板与落地要点（参考 `tsl-devkit/lsp-server/.clangd`）。
+
+## 1. 目标
+
+- 让 IDE/编辑器的 C++ 补全、跳转、诊断稳定可复现。
+- 优先依赖 `compile_commands.json`（由 CMake 生成），避免手写复杂编译参数。
+
+## 2. 必要前提：生成 `compile_commands.json`
+
+- CMake：建议开启 `CMAKE_EXPORT_COMPILE_COMMANDS=ON`（本 Playbook 的 `templates/cpp/CMakeLists.txt` 已开启）。
+- 使用 preset 构建后，在对应 build 目录会生成 `compile_commands.json`：
+  - 例如：`build/windows-x86_64-clang-cross/Release/compile_commands.json`
+
+## 3. `.clangd` 模板
+
+- 模板文件：`templates/cpp/.clangd`
+- 关键字段：`CompileFlags.CompilationDatabase` 指向 build 目录（包含 `compile_commands.json` 的目录）。
+
+## 4. Modules 注意事项（C++23）
+
+- 若新增/删除/重命名 `.cppm`，必须同步更新构建系统的模块清单（例如 CMake `FILE_SET CXX_MODULES`），否则 `compile_commands.json` 可能缺项，导致 clangd 补全/跳转不稳定。

docs/cpp/code_style.md

@@ -0,0 +1,72 @@
+# C++ 代码风格（Code Style）
+
+本章节规定 C++（C++23，含 Modules）代码的结构与格式约定。
+
+## 1. 文件与组织
+
+### 1.1 目录建议（项目落地）
+
+推荐将 C++ 代码放在独立目录（多语言项目便于隔离规则与工具）：
+
+```txt
+cpp/
+  include/              # 对外头文件（如项目仍使用头文件边界）
+  src/                  # 实现文件与 module 实现单元
+  modules/              # module interface / partition（如使用 modules）
+  tests/                # （可选）测试
+  CMakeLists.txt
+```
+
+若项目不采用 `cpp/` 根目录，也应保持 include/src/modules 分层清晰。
+
+### 1.2 文件扩展名约定
+
+- 头文件：`.h`（Google 风格；若项目已统一 `.hpp`，以项目既有为准）
+- 源文件：`.cc`（优先；`main` 入口建议使用 `main.cc`；若项目已统一 `.cpp`，以项目既有为准）
+- Module Interface Unit：`.cppm`（推荐统一）
+- Module Partition：`.cppm`（在文件名中体现分区，例如 `foo_part.cppm`）
+
+### 1.3 Modules 约定（C++23）
+
+- Module 名称建议使用“点分层级”组织，且每一段使用 `lower_snake_case`：
+  - 示例：`my_project.net.http`
+- 文件路径与 module 名建议可映射（便于检索）：
+  - `cpp/modules/my_project/net/http.cppm` → `export module my_project.net.http;`
+- 避免在同一模块内混用“头文件边界”和“模块边界”造成可见性混乱；对外 API 优先通过 `export` 暴露。
+- 工程约束：新增/删除/重命名 `.cppm`（或变更 `export module ...`）时，必须同步更新构建系统的模块清单（例如 CMake 的 `target_sources(FILE_SET CXX_MODULES ...)`），否则容易出现“本地能编、CI/他人机器不能编”的漂移。
+
+## 2. 格式（Formatting）
+
+### 2.1 clang-format（必选）
+
+- 本仓库/标准默认：`clang-format` + Google 风格。
+- 建议在项目根目录提供 `.clang-format` 并纳入 CI/本地钩子。
+- 列宽建议与本 Playbook 其他语言保持一致：默认 100（可按项目调整，但要全仓一致）。
+- 模板：`templates/cpp/.clang-format`（参考 `tsl-devkit/lsp-server/.clang-format` 并做了最小化泛化）。
+
+### 2.2 通用格式约定
+
+- 缩进使用空格，单次缩进 4 空格（Google）。
+- 不做“空格对齐排版”（避免 diff 噪音），用缩进表达结构。
+- 头文件 include 顺序建议（从上到下）：
+  1. 本文件对应头（如有）
+  2. C 标准库 / C++ 标准库
+  3. 第三方库
+  4. 项目内其他头/模块导入
+
+## 3. 头文件与可见性
+
+- 头文件应可被独立 include（自包含）。
+- 对外接口放在 `include/`，实现细节放 `src/`。
+- 避免在头文件中引入沉重依赖；可用前置声明或 PImpl（按项目需要）。
+
+## 4. 错误处理与资源管理
+
+- 默认使用 RAII 管理资源；避免裸 `new/delete`。
+- 禁止吞异常/忽略错误；失败路径必须可观测（返回值/异常/日志其一或按项目约定）。
+
+## 5. Windows 支持
+
+- 本规范假设 **不做原生 Windows 开发环境支持**；Windows 产物通过 **Linux 上的 Clang 交叉编译工具链**获得（工具链路径/三元组等由项目的 Conan profile 或 toolchain 文件定义）。
+- 如需条件编译，优先用标准特性检测与最小化条件编译，并写清动机（例如 ABI/平台差异）。
+- 对路径、换行、编码、大小写敏感等行为要明确约束并在文档/测试中覆盖。

docs/cpp/dependencies_conan.md

@@ -0,0 +1,79 @@
+# C++ 第三方依赖（Conan）
+
+本章节给出 Conan + CMake 的推荐落地方式（参考 `tsl-devkit/lsp-server/` 的实践）。
+
+## 1. 基本约定
+
+- 依赖清单使用 `conanfile.txt`（或项目统一的 `conanfile.py`）。
+- 本 Playbook 不内置“标准依赖集合/固定版本”；依赖选择与版本锁定由具体项目维护。
+- Conan：`2.x`（本 Playbook 假设 Conan 2；不保证 Conan 1 的兼容性）
+- 生成器使用：
+  - `CMakeDeps`
+  - `CMakeToolchain`
+- layout 使用：`cmake_layout`（让 build 目录结构稳定可预测）
+
+## 2. 目录与文件（建议）
+
+```txt
+cpp/
+  conanfile.txt
+  conan/
+    profiles/
+      <platform>-<arch>-clang
+      windows-<arch>-clang-cross
+  CMakeLists.txt
+  CMakeUserPresets.json
+  build/               # 本地/CI 生成，通常不入库
+```
+
+## 3. Profile 命名与含义（规范）
+
+- Profile 文件名按“产物平台”为前缀，避免误读：
+  - `linux-...`：产物平台为 Linux（`[settings] os=Linux`）
+  - `windows-...`：产物平台为 Windows（`[settings] os=Windows`）
+- 跨编译 profile 建议以 `-cross` 结尾（例如 `windows-x86_64-clang-cross`）。
+- “工具链版本”以 profile 的 `[settings] compiler.version` 为准；如同一仓库并存多版本 clang，可将版本体现在文件名中（例如 `linux-x86_64-clang20`）。
+
+## 4. 安装与构建（推荐流程）
+
+在项目的 C++ 根目录（例如 `cpp/`）下：
+
+1. 安装依赖并生成工具链文件：
+   - `CONAN_HOME=/tmp/conan-home conan install . -pr:b=conan/profiles/linux-x86_64-clang -pr:h=conan/profiles/windows-x86_64-clang-cross -of build/windows-x86_64-clang-cross --build=missing`
+   - 若有 profile：`-pr:h=conan/profiles/<...> -pr:b=conan/profiles/<...>`
+2. 配置 CMake：
+   - 直接指定 toolchain：
+     - `cmake -S . -B build/clang -G Ninja -DCMAKE_TOOLCHAIN_FILE=$PWD/build/clang/Release/generators/conan_toolchain.cmake`
+   - 或使用 Presets（推荐，见下节）：
+     - `cmake --preset conan-release`
+3. 构建：
+   - `cmake --build --preset conan-release -j 8`
+
+提示：如遇到 Conan 缓存/家目录权限问题，可临时设置 `CONAN_HOME=/tmp/conan-home` 再执行。
+
+## 5. CMake Presets（推荐做法）
+
+Conan 2 可以生成 CMake Presets（通常落在 `build/<...>/generators/CMakePresets.json`）。
+
+推荐将一个稳定的 `CMakeUserPresets.json` 放进仓库并 include 生成文件（参考 `tsl-devkit/lsp-server/CMakeUserPresets.json`），例如：
+
+```json
+{
+  "version": 4,
+  "vendor": { "conan": {} },
+  "include": ["build/clang-linux/Release/generators/CMakePresets.json"]
+}
+```
+
+这样团队/CI 就可以统一使用：
+
+- 配置：`cmake --preset conan-release`
+- 构建：`cmake --build --preset conan-release -j 8`
+- 测试：`ctest --preset conan-release --output-on-failure`
+
+## 6. 模板文件（本 Playbook）
+
+- `templates/cpp/conanfile.txt`
+- `templates/cpp/CMakeUserPresets.json`
+- `templates/cpp/conan/profiles/linux-x86_64-clang`
+- `templates/cpp/conan/profiles/windows-x86_64-clang-cross`

docs/cpp/naming.md

@@ -0,0 +1,31 @@
+# C++ 命名规范（Naming）
+
+本章节以 Google C++ Style Guide 为基线，并补充模块化（Modules）相关的命名约定。
+
+## 1. 总原则
+
+- 一致性优先：以仓库现有风格为准，标准用于“无上下文/新代码”的默认选择。
+- 名字体现作用域与语义，不用 `tmp/data/info` 这类弱语义词。
+
+## 2. 命名风格总览（默认）
+
+- 类型（class/struct/enum/using）：`PascalCase`
+- 函数/方法：`PascalCase`
+- 变量：`lower_snake_case`
+- 成员变量：`lower_snake_case_`（尾随下划线，Google）
+- 常量：`kPascalCase`（编译期/全局固定值）
+- 命名空间：`lowercase` 或 `lower_snake_case`（按项目约定，建议全仓统一）
+
+## 3. 文件命名
+
+- 文件名：`lower_snake_case`（与 Google 风格一致）
+- 头文件：`foo_bar.h`
+- 源文件：`foo_bar.cc`
+- Module 文件：`foo_bar.cppm`
+
+## 4. Modules 命名
+
+- Module 名使用点分层级：`<root>.<subsystem>.<component>`
+- 每一段建议用 `lower_snake_case`：
+  - 示例：`my_project.market.data_feed`
+- 文件路径建议与 module 名可映射（便于检索与定位）。

docs/cpp/toolchain.md

@@ -0,0 +1,80 @@
+# C++ 工具链与验证命令（模板）
+
+本文件提供一份**通用占位模板**，用于在不同 C++ 项目中快速补齐“工具链与如何验证”的关键上下文。
+
+## 1. 工具链（必填）
+
+### 1.1 编译器与标准
+
+- C++ 标准：C++23（含 Modules）
+- 编译器：
+  - 目标平台：Windows（通过 Linux 交叉编译）
+  - 主机平台：Linux
+  - 工具链：`clang <版本>`（交叉编译；具体 clang 可执行路径由 Conan profile 配置）
+  - 目标三元组（示例）：`x86_64-w64-mingw32` / `aarch64-w64-mingw32`
+
+### 1.2 构建系统
+
+- CMake：`>= 4.0`
+- 生成器：
+  - Linux：`Ninja`
+
+### 1.3 依赖管理（Conan，推荐）
+
+若项目使用 Conan 管理三方依赖，建议：
+
+- Conan：`2.x`（本 Playbook 假设 Conan 2；不保证 Conan 1 的兼容性）
+- 使用 `conanfile.txt` + `CMakeDeps` + `CMakeToolchain` + `cmake_layout`（参考 `tsl-devkit/lsp-server/conanfile.txt`）。
+- 通过 `conan install` 生成工具链与（可选）CMake Presets，再用 `cmake --preset ...` 构建。
+
+### 1.4 格式化（必选）
+
+- `clang-format`：`<项目自选并固定版本>`
+- 兼容性策略：
+  - `.clang-format` 是唯一真相（推荐使用 `templates/cpp/.clang-format` 落地到项目根目录）。
+  - 不同版本的 `clang-format` 可能对同一配置产生不同输出；项目应在 CI/开发环境中固定版本，避免格式漂移。
+  - CI 推荐用 `clang-format --dry-run --Werror <files...>` 做格式校验。
+
+### 1.5 静态检查（暂不启用）
+
+- `clang-tidy`：暂不启用（若未来启用，写明版本、配置文件与运行命令）
+
+## 2. 验证命令（必填：把占位符替换成真实命令）
+
+### 2.1 最小构建（必须能跑）
+
+- Conan 生成（推荐，示例）：
+  - `CONAN_HOME=/tmp/conan-home conan install . -pr:b=conan/profiles/linux-x86_64-clang -pr:h=conan/profiles/windows-x86_64-clang-cross -of build/windows-x86_64-clang-cross --build=missing`
+- 配置（示例）：
+  - `cmake --preset conan-release`
+- 构建（示例）：
+  - `cmake --build --preset conan-release -j 8`
+
+### 2.2 运行冒烟（建议）
+
+- `build/<app_or_tool> <args>`
+- 或：`cmake --build build -t run_smoke`（如项目提供自定义 target）
+
+### 2.3 格式化检查（建议）
+
+- `clang-format -i <files...>`（本地）
+- `clang-format --dry-run --Werror <files...>`（CI）
+
+### 2.4 失败处理约定（必填）
+
+- 只修复与本次改动直接相关的失败；无关失败记录并隔离。
+- 若某步骤无法执行（缺环境/缺权限），必须写出原因与替代验证（例如手动检查清单/最小复现工程）。
+
+## 3. Presets（可选但强烈推荐）
+
+参考 `tsl-devkit` 的做法：
+
+- 将 `CMakeUserPresets.json` 纳入版本控制，并 `include` Conan 生成的 `build/.../generators/CMakePresets.json`。
+- 优点：统一 Windows/Linux/macOS 构建入口；Agent 也更容易用固定命令验证。
+
+本 Playbook 约定：
+
+- **强制统一 preset 名称**：`conan-release` / `conan-debug`（项目必须提供这两个 preset；实现方式不限：可由 Conan 生成，也可由项目自建 `CMakePresets.json` 适配）。
+- `CMakeUserPresets.json` 不是强制标准，仅作为一种推荐落地方式（模板见 `templates/cpp/CMakeUserPresets.json`）。
+
+不在本 Playbook 中强制规定工具链分发方式（例如某种特定打包形态）；只要求把交叉编译所需的 `compiler_executables`、triplet、system_name 等写进 Conan profile，保证命令可复现。

docs/index.md

@@ -0,0 +1,28 @@
+# 文档导航（Docs Index）
+
+本仓库文档按“跨语言共识 / 语言专属”分层组织，便于在多语言项目中扩展与复用。
+
+## 跨语言（common）
+
+- 提交信息与版本号：`common/commit_message.md`
+
+## TSL（tsl）
+
+- TSL 源文件后缀同时包含：`.tsl`（脚本）与 `.tsf`（模块/库代码）。
+- 代码风格：`tsl/code_style.md`
+- 命名规范：`tsl/naming.md`
+- 工具链与验证命令（模板）：`tsl/toolchain.md`
+
+## C++（cpp）
+
+- 代码风格：`cpp/code_style.md`
+- 命名规范：`cpp/naming.md`
+- 工具链与验证命令（模板）：`cpp/toolchain.md`
+- 第三方依赖（Conan）：`cpp/dependencies_conan.md`
+- clangd 配置：`cpp/clangd.md`
+
+## Python（python）
+
+- 代码风格：`python/style_guide.md`
+- 工具链：`python/tooling.md`
+- 配置清单：`python/configuration.md`

docs/python/configuration.md

@@ -0,0 +1,65 @@
+# Python 配置清单（Configuration）
+
+本文件用于把 Python 工具配置“汇总说明”到一个可读入口。
+
+注意：本 Playbook 将可复制模板放在 `templates/python/`；在目标项目落地时，这些文件通常需要复制到**项目根目录**（工具默认查找位置）：
+
+- `pyproject.toml`
+- `.flake8`
+- `.pylintrc`
+- `.pre-commit-config.yaml`
+- `.editorconfig`
+- `.vscode/settings.json`
+
+## 1) `pyproject.toml`
+
+模板文件：`templates/python/pyproject.toml`
+
+- `tool.black`
+  - `line-length = 80`
+  - `target-version = ['py313']`（按项目 Python 版本调整）
+- `tool.isort`
+  - `profile = "google"`
+  - `line_length = 80`
+  - `known_third_party` / `known_first_party`：按项目维护
+- `tool.mypy`
+  - `python_version = "3.13"`（按项目调整）
+  - `ignore_missing_imports = true`（对第三方二进制/无类型库更友好）
+- `tool.pytest.ini_options`
+  - 测试发现与参数（若项目引入 `tests/` 会自动生效）
+
+## 2) `.flake8`
+
+模板文件：`templates/python/.flake8`
+
+- `max-line-length = 80`
+- `docstring-convention = google`
+- 与 `black` 冲突的规则已屏蔽（例如 `E203`、`W503`）
+
+## 3) `.pylintrc`
+
+模板文件：`templates/python/.pylintrc`
+
+- 命名风格：snake_case / PascalCase 等（对齐 Google Python 风格）
+- `max-line-length = 80`
+- `init-hook` 将项目根目录加入 `sys.path`（便于本地运行与检查；如项目不需要可移除）
+
+## 4) `.pre-commit-config.yaml`
+
+模板文件：`templates/python/.pre-commit-config.yaml`
+
+- 基础文本检查：尾随空格、文件末尾换行、YAML/TOML 基础校验
+- Python：`black`、`isort`、`flake8`
+
+## 5) `.editorconfig`
+
+模板文件：`templates/python/.editorconfig`
+
+- Python：4 空格缩进、行宽 80
+- 通用：UTF-8、LF、去尾随空格、文件末尾换行
+
+## 6) `.vscode/settings.json`
+
+模板文件：`templates/python/.vscode/settings.json`
+
+- 保存即格式化、80 列标尺、默认使用 Black formatter、按需组织 import

docs/python/style_guide.md

@@ -0,0 +1,14 @@
+# Python 代码风格（Google Python Style Guide）
+
+本 Playbook 的 Python 代码风格以 Google Python Style Guide 为基线（基于 PEP 8）：
+
+- Google Python Style Guide: https://google.github.io/styleguide/pyguide.html
+- PEP 8: https://peps.python.org/pep-0008/
+
+## 项目约定（Project Conventions）
+
+- 行宽：80（与 `black`/`flake8`/`pylint` 配置保持一致）
+- docstring：Google 风格（与 `.flake8` 的 `docstring-convention = google` 对齐）
+- import 顺序：使用 `isort` 的 `profile = google`
+
+当既有代码与本约定冲突时，优先保持局部一致性，逐步迁移。

docs/python/tooling.md

@@ -0,0 +1,36 @@
+# Python 工具链（Tooling）
+
+本 Playbook 推荐用以下工具保证代码一致性与质量：
+
+- `black`：格式化（行宽 80）
+- `isort`：import 排序（Google profile）
+- `flake8`：风格检查 + docstring 约定
+- `pylint`：静态检查（以 `.pylintrc` 为准，可按项目调整）
+- `mypy`：类型检查（可选）
+- `pytest`：测试（可选）
+- `pre-commit`：在 `git commit` 前自动运行上述检查/格式化（可选，但推荐）
+
+## 常用命令（示例）
+
+安装工具（示例，按项目实际依赖管理方式调整）：
+
+```bash
+python -m pip install black isort flake8 pylint mypy pytest pre-commit
+```
+
+格式化与检查（示例）：
+
+```bash
+black .
+isort .
+flake8 .
+pylint .
+mypy .
+pytest
+```
+
+启用 `pre-commit`（只需一次）：
+
+```bash
+pre-commit install
+```

docs/tsl/code_style.md

@@ -0,0 +1,123 @@
+# TSL 代码风格（Code Style）
+
+本章节规定 TSL 代码的结构与格式约定。
+
+## 1. 文件与组织
+
+- 一个文件只做一件事；职责明确。
+- 文件名使用 `PascalCase`，并与文件内唯一的顶层声明同名（语法要求）。扩展名按类型使用 `.tsl`/`.tsf`（两者都属于 TSL 源文件，风格规则一致）。
+- 避免循环依赖；公共能力下沉到可复用模块。
+- 同类代码按“对外 API → 核心实现 → 辅助工具 → 测试/示例”的顺序组织。
+
+## 2. 格式（Formatting）
+
+### 2.1 缩进与空白
+
+- 使用**空格缩进**，禁止 Tab。
+- 默认缩进 **4 个空格**；继续缩进保持与上层语义一致。
+- 行尾不留空格；文件以换行符结尾。
+- 逻辑块之间用空行分隔，不要用空行堆砌。
+
+### 2.2 行宽与换行
+
+- 单行建议不超过 **100 字符**；超过时应换行以保持可读性。
+- 换行遵循“**断在运算符后**、对齐到语义层级”的原则。
+- 长字符串/URL 可适当超出，但避免影响阅读。
+
+### 2.3 begin/end 与代码块
+
+- 代码块使用统一的块结构（示例为伪代码，按 TSL 语法调整）：
+
+```tsl
+if cond then
+begin
+    DoSomething()
+end
+else
+begin
+    DoOther()
+end
+```
+
+- 多语句分支使用 `begin/end` 包裹：在 `then/else` 后换行写 `begin`，`end` 单独成行。
+- `else/elseif` 等分支关键字另起一行，与上一块的 `end` 对齐。
+
+### 2.4 运算符与分隔符
+
+- 二元运算符两侧加空格：`a + b`、`x == y`。
+- 一元运算符不加空格：`!flag`、`-value`。
+- 逗号后加空格：`f(a, b, c)`。
+- 不要为了对齐而插入多余空格；让格式由缩进表达结构。
+
+### 2.5 控制流
+
+- 多语句分支必须使用 `begin/end`；单语句分支可省略 `begin/end`，写成单行（如 `if cond then stmt`）。
+- 复杂条件拆分为具名布尔变量或小函数。
+- 早返回优于深层嵌套：
+
+```tsl
+if !ok then return err
+// main path
+```
+
+## 3. 注释（Comments）
+
+注释用于解释**为什么**以及必要的背景，而不是重复代码。
+
+### 3.1 文件级注释
+
+- 文件开头说明用途、主要职责、关键依赖/约束。
+- 若文件实现某个对外 API，写明入口与预期行为。
+
+### 3.2 函数/接口注释
+
+- 对外可见的函数必须写注释，包含：
+  - 做什么（行为）
+  - 入参/返回值含义（必要时含单位、范围）
+  - 关键副作用与异常情况
+- 注释使用完整句子，末尾带标点。
+
+### 3.3 行内注释
+
+- 用于解释复杂逻辑、非直观边界条件、性能/安全考量。
+- 避免“显而易见注释”：
+
+```tsl
+count = count + 1  // bad: obvious
+```
+
+### 3.4 TODO/FIXME
+
+- 统一格式：`TODO(name): ...` / `FIXME(name): ...`
+- 写清原因和期望修复方向，而非“留个坑”。
+
+## 4. 代码实践（Best Practices）
+
+### 4.1 变量与常量
+
+- 默认使用不可变/只读（如语法支持 `const` 或等价机制）。
+- 变量声明与第一次使用尽量靠近。
+- 避免隐藏式类型转换与隐式全局。
+
+### 4.2 函数设计
+
+- 函数参数建议显式写类型注解，提升可读性与工具检查能力。
+- 无返回值函数显式标注返回类型为 `void`。
+
+```tsl
+function Func(a: string; b: ClassName): void;
+```
+
+- 单一职责；函数过长说明拆分点已出现（建议 ≤ 40–60 行）。
+- 参数顺序：输入参数在前，输出/回调在后。
+- 尽量避免超过 5 个参数；必要时封装为对象（class/unit）。
+
+### 4.3 错误处理
+
+- 错误必须显式处理：返回错误、抛出异常或记录并降级（按项目约定）。
+- 不要吞掉异常/错误；必须加注释说明原因。
+
+### 4.4 性能与可测试性
+
+- 避免过早优化；先写清晰正确的代码，再用数据驱动优化。
+- 复杂逻辑要可测试：拆成纯函数或可注入依赖的模块。

docs/tsl/naming.md

@@ -0,0 +1,151 @@
+# TSL 命名规范（Naming）
+
+本仓库命名规则与 Google C++ Style Guide 对齐：通过名字的“形状”快速判断实体类型（类型/函数/变量/常量等），减少阅读成本。
+
+## 1. 选名原则
+
+- **可读一致**：名字清晰可读，并随可见范围调整具体程度。
+- **少用生僻缩写**：能写全称就写全称。
+- **驼峰/帕斯卡中的缩写规则**：缩写（首字母缩写/词组缩写）在 `PascalCase`/`camelCase` 中**按一个单词处理**，写成“首字母大写其余小写”，不要写一串全大写。
+  - 示例：`UserId`（不是 `UserID`）、`UrlTable`（不是 `URLTable`）、
+    `StartRpcServer`（不是 `StartRPCServer`）、`HttpClient`（不是 `HTTPClient`）。
+- **避免无意义词**：如 `data`、`info`、`tmp`、`handle` 等。
+
+## 2. 命名风格总览
+
+对于以下规则，“单词”指英文中不带空格的词。
+
+- `snake_case`：全小写，下划线分隔单词，用于普通变量/参数等；私有类成员变量在此基础上末尾加下划线。
+- `PascalCase`（`UpperCamelCase`）：每个单词首字母大写，无下划线，用于类型、顶层函数/方法、property，以及（少量）公有成员字段。
+
+**大小写与关键字约定**
+
+- TSL 语言大小写无关，但本指南仍要求按约定使用大小写以提升可读性；不要用仅大小写不同的名字区分不同实体。
+- 所有语法关键字统一使用全小写书写，例如 `if`、`for`、`class`、`function`、`unit`、`return` 等。
+- 调用内置/标准库方法时，推荐保持官方大小写形式（`aaBBCC`/lowerCamelCase），例如 `getSysParams("xxx")`。
+
+## 3. 类型命名（Type Names）
+
+TSL 的顶层声明只有三种：`class`、`unit`、`function`。
+
+- **类（class）与单元（unit）**使用 `PascalCase`，不带下划线。
+- **顶层函数（function）**使用 `PascalCase`，详见函数命名章节。
+- 示例：`UserAccount`、`OrderUnit`、`LoadMarketData()`。
+
+## 4. 文件命名与顶层声明（File Names）
+
+TSL 的语法要求：每个文件只能有一个顶层声明，且**文件基名必须与该顶层声明名字一致**。
+
+- 顶层声明可能是 `class`、`unit` 或 `function`（见类型命名）。
+- `.tsl` 脚本文件：顶层声明只能是 `function`，因此文件基名 = 顶层函数名。
+- `.tsf` 代码文件：顶层声明可为 `class`/`unit`/`function`，文件基名需与之同名。
+  - 注：`.tsf` 也是 TSL 源文件，命名/风格与 `.tsl` 遵循同一套规则。
+
+命名建议：
+
+- 基名统一使用 `PascalCase`，与顶层声明的推荐写法一致。
+- 示例：
+  - `LoadMarketData.tsl` 中定义 `function LoadMarketData(...)`.
+  - `UserAccount.tsf` 中定义 `type UserAccount = class ... end;`.
+  - `DocxEnumerations.tsf` 中定义 `unit DocxEnumerations; ... end.`
+
+注：TSL 大小写无关，实际编译时按大小写比较不会出错，但仍应保持文件名与声明名的推荐写法一致以便检索与协作。
+
+## 5. 变量命名（Variable Names）
+
+### 5.1 普通变量与参数
+
+- **局部变量、函数参数、非成员变量**使用 `snake_case`。
+- 若参数名与 TSL 关键字冲突导致编译失败，使用前导下划线的 `snake_case` 作为例外，例如 `_type`、`_unit`。
+- 前导下划线 `_` **仅用于上述关键字冲突的参数场景**，不要用于其他局部变量、成员变量、函数/类型/单元名称或全局变量。
+- 示例：`table_name`、`max_retry_count`、`user_id`。
+
+### 5.2 类成员（Class Data Members）
+
+- **私有成员变量**使用 `snake_case_`（尾随下划线）。
+- 尾随下划线 `_` **仅用于私有成员变量**，不要用于局部变量、参数、公有成员字段、property 名称或顶层全局变量。
+- **公有成员变量**若必须存在，使用 `PascalCase`；但**不推荐外部直接访问公有字段**。
+- 对外暴露的成员优先使用 **property**：
+  - property 名称使用 `PascalCase`（视为对外 API）。
+  - property 的 `read/write` 指向真实成员（通常为私有 `snake_case_`）。
+- 示例：
+
+```tsl
+type User = class
+public
+    property UserId read user_id_ write user_id_;
+private
+    user_id_;
+end;
+```
+
+### 5.3 全局/静态变量
+
+- 不推荐使用顶层全局/静态可变变量；优先封装到 `unit`/`class` 中，通过函数或 property 访问。
+- 若必须声明顶层全局/静态变量，使用 `g_snake_case` 前缀显式标识其全局性质，例如 `g_user_cache`、`g_market_state`。
+- 全局/静态常量仍按常量规则使用 `kPascalCase`。
+
+### 5.4 布尔变量
+
+- 使用 `is_ / has_ / can_ / should_` 等前缀表达语义。
+- 示例：`is_ready`、`has_error`、`can_retry`。
+
+### 5.5 短名例外
+
+- 在极小作用域内可用习惯短名：`i`、`j`、`n`、`t` 等。
+- 作用域一旦扩大，必须改为有含义的名字。
+
+### 5.6 集合与复数命名（Collections）
+
+- **数组/列表/可迭代集合**使用复数名词的 `snake_case`：`users`、`order_items`。
+- 若复数形式不直观或为不可数名词，使用后缀明确类型：`news_list`、`price_items`。
+- **映射/字典（key→value）**使用 `snake_case` 并加后缀 `_map`，必要时可用 `_by_<key>` 表达键语义：`user_map`、`price_by_symbol`。
+- **集合/去重集合**使用后缀 `_set`：`user_id_set`、`symbol_set`。
+
+## 6. 常量命名（Constant Names）
+
+- **编译期/全局期固定的常量**使用 `kPascalCase`，以 `k` 开头。
+- 示例：`kDaysInAWeek`、`kAndroid8_0_0`。
+- 对于**局部 const 但值来自参数/运行时**的变量：
+  - 可用普通变量名 `snake_case`；
+  - 不要用 `k` 前缀误导读者认为其全局固定。
+
+### 6.1 单元枚举模拟（Unit Enumerations）
+
+TSL 没有内置 `enum`，推荐使用 `unit` + `const` 在 `interface` 区域模拟枚举集合。
+
+- `unit` 名称使用 `PascalCase`，建议以 `Enumerations`/`Enums` 结尾表达用途。
+- 枚举值使用 `const` 定义并放在 `interface` 中；命名优先沿用外部/业务域既有前缀与风格（属于例外场景）。
+
+示例：
+
+```tsl
+unit DocxEnumerations;
+interface
+
+    // WdAlertLevel
+    const wdAlertsAll = -1;
+end.
+```
+
+## 7. 函数与方法命名（Function Names）
+
+- 所有**普通**函数/方法（包含 `public`/`private`）均使用 `PascalCase`。
+- **特殊函数/运算符重载为语法固定名，必须使用全小写**：
+  - 构造/初始化函数：`create`。
+  - 析构/释放函数：`destroy`。
+  - 运算符重载：`operator+()` 等，按语法使用小写 `operator<op>()` 形式。
+- 示例：`AddTableEntry()`、`DeleteUrl()`、`OpenFileOrDie()`。
+- **推荐使用 property 语法**对外暴露访问器：property 名 `PascalCase`，`read/write` 绑定成员变量（见类成员章节）。
+- 不推荐新增显式 getter/setter；仅当 property 无法表达语义时，才使用 getter/setter，命名可与字段同形的 `snake_case`（如 `count()`、`set_count(x)`）。
+
+## 8. 宏与编译期开关（Macro Names）
+
+- 能不用宏就不用。
+- 必须使用时，命名为全大写加下划线，并带项目/业务前缀：
+  - `TSL_ROUND(x)`、`TSL_ENABLE_FOO`。
+
+## 9. 例外（Exceptions）
+
+- 当命名需要与外部既有 API/协议保持一致时，可沿用对方风格。
+- 例如对接 C/C++ 库、历史接口、跨语言互操作代码等。

docs/tsl/toolchain.md

@@ -0,0 +1,62 @@
+# TSL 工具链与验证命令（模板）
+
+本文件提供一份**通用占位模板**，用于在不同 TSL 项目中快速补齐“工具链与如何验证”的关键上下文。
+
+使用方式：
+
+- 在具体项目中复制本模板并把占位符替换为真实信息；
+- 或在项目文档中引用本模板，并在项目内提供对应的 `scripts/*` 统一入口脚本。
+
+## 1. TSL 工具链
+
+### 1.1 解释器/编译器（必填）
+
+- 工具名称：`<tsl/tslcli/内部工具名>`
+- 可执行命令：
+  - macOS/Linux：`<command>`（例：`tsl` / `tslcli` / `sh scripts/tsl.sh`）
+  - Windows：`<command>`（例：`tsl.exe` / `tslcli.exe` / `powershell -File scripts/tsl.ps1`）
+- 版本要求：`<固定版本或范围，例如：= 3.2.1 / >=3.2,<4.0>`
+- 安装方式：`<内部安装包/路径/IDE 自带/CI 镜像等>`
+- 推荐统一入口脚本：`scripts/tsl.{sh,ps1}`（封装参数与环境变量，避免每个任务重复猜测）
+
+### 1.2 运行环境（按需）
+
+- 必要环境变量：`<TSL_HOME> <TSL_LIB_PATH> <LICENSE_PATH> ...`
+- 外部依赖：`<数据库/服务/共享目录/网络权限/账户权限>`
+- 运行约束：
+  - 是否允许联网：`<yes/no>`
+  - 是否需要许可证/凭证：`<说明如何在本地与 CI 提供；禁止写入仓库>`
+
+## 2. 验证命令
+
+> 要求：改动完成后至少能跑通“最小冒烟”；若项目存在测试体系，尽量补到对应层级。
+
+### 2.1 最小冒烟（必须能跑）
+
+- macOS/Linux：`<tsl> run <path/to/SmokeTest.tsl> -- <args>`
+- Windows：`<tsl.exe> run <path\\to\\SmokeTest.tsl> -- <args>`
+- 或统一入口：
+  - `sh scripts/smoke.sh`
+  - `powershell -File scripts/smoke.ps1`
+
+### 2.2 单元测试（如有）
+
+- `sh scripts/test.sh`
+- 或：`<tsl> test <tests/>`
+- 或：`<tsl> run <path/to/TestRunner.tsf>`
+
+### 2.3 静态检查/格式化（如有）
+
+- `sh scripts/lint.sh`
+- `sh scripts/format.sh`
+- 或：`<tsl> check <src/>` / `<tsl> fmt <src/>`
+
+### 2.4 构建/打包（如有）
+
+- `sh scripts/build.sh`
+- 或：`<tsl> build <project-file>`
+
+### 2.5 失败处理约定（必填）
+
+- 只修复与本次改动直接相关的失败；无关失败在输出中说明并隔离。
+- 若某验证步骤无法执行（缺环境/缺凭证），必须明确写出原因与替代验证手段（例如最小复现脚本/手动检查清单）。