commit eada742d75c6de8f5cd08a52b417937cf17c7936 Author: csh Date: Sun Dec 14 17:55:55 2025 +0800 Squashed 'docs/standards/playbook/' content from commit e504a68 git-subtree-dir: docs/standards/playbook git-subtree-split: e504a689dcf2e2fdeeb64097930347d504e68f5f diff --git a/.agents/cpp/auth.md b/.agents/cpp/auth.md new file mode 100644 index 0000000..5adf24f --- /dev/null +++ b/.agents/cpp/auth.md @@ -0,0 +1,33 @@ +# 安全与鉴权（Auth） + +本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。 + +## 1. 基本原则 + +- **最小权限**：只使用完成任务所需的最低权限与最少数据。 +- **默认保守**：不确定是否敏感时按敏感处理。 +- **不扩散秘密**：任何 secret 只在必要范围内出现。 + +## 2. 凭证与敏感信息 + +- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。 +- 如需示例，使用占位符：``、``。 +- 避免把敏感信息打印到标准输出或错误日志。 + +## 3. 鉴权逻辑修改 + +- 修改鉴权/权限控制时必须说明： + - 变更动机 + - 风险评估 + - 兼容性/回滚方案 +- 默认保持旧行为兼容，除非明确要求破坏性变更。 + +## 4. 依赖与第三方 + +- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。 +- 若必须新增，需在 PR 说明理由、替代方案与安全影响。 + +## 5. 审计与合规 + +- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。 +- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。 diff --git a/.agents/cpp/code_quality.md b/.agents/cpp/code_quality.md new file mode 100644 index 0000000..d776c72 --- /dev/null +++ b/.agents/cpp/code_quality.md @@ -0,0 +1,34 @@ +# 代码质量（Code Quality） + +本文件定义代理对代码质量的最低要求与审查清单（C++）。 + +## 1. 总体要求 + +- C++ 代码遵守 `docs/cpp/code_style.md` 与 `docs/cpp/naming.md`（在目标项目中通常 vendoring 到标准快照路径）。 +- 统一使用 `clang-format`（Google 基线）保持格式一致；不要手工“对齐排版”制造 diff 噪音。 +- 改动聚焦目标；避免“顺手重构”。 +- API 变更要显式说明影响与迁移方式。 +- 涉及三方依赖（例如 Conan）的改动必须说明动机、替代方案与影响面；默认不“顺手升级依赖”。 +- 涉及 C++ Modules 的改动（`.cppm` 或 `export module` 变更）必须同步更新构建系统的模块清单与相关 target 配置。 + +## 2. 可读性 + +- 复杂逻辑拆分为具名函数/类型；避免深层嵌套与重复代码。 +- 必要注释解释“为什么”而不是“做什么”。 + +## 3. 错误处理与资源管理 + +- 默认使用 RAII；避免裸 `new/delete`。 +- 失败路径必须可观测（返回值/异常/日志其一或按项目约定）。 + +## 4. 复杂度与规模 + +- 单函数尽量 ≤ 80 行；超过应说明原因或拆分（可按项目调整）。 +- 单次 PR 尽量小步提交，便于 review。 + +## 5. Review 清单 + +- 是否有无关改动？ +- 是否保持模块内风格一致？ +- 是否引入不必要的复杂度/依赖？ +- 是否有最小验证（构建/冒烟）步骤？ diff --git a/.agents/cpp/index.md b/.agents/cpp/index.md new file mode 100644 index 0000000..b3d5690 --- /dev/null +++ b/.agents/cpp/index.md @@ -0,0 +1,41 @@ +# C++ 代理规则集（.agents/cpp） + +本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（C++ 语言专属）。 + +## 范围与优先级 + +- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。 +- 当代理规则与 `docs` 发生冲突时： + 1. 安全/合规优先 + 2. 其次保持仓库现有一致性 + +## 代理工作原则 + +- 先理解目标与上下文，再动手改代码。 +- 修改要小而清晰；避免无关重构。 +- 不要引入新依赖或工具，除非明确要求。 + +## 子文档 + +- 安全与鉴权：`auth.md` +- 性能：`performance.md` +- 代码质量：`code_quality.md` +- 测试：`testing.md` + +## C++ 必要约定（必须遵守） + +- 语言标准：C++23（含 Modules）。 +- 格式化：统一使用 `clang-format`（Google 基线）；避免手工排版对齐造成 diff 噪音。 +- 文件与命名：遵守 `docs/cpp/` 下的规范（或目标项目 vendoring 的标准快照路径）。 +- Modules：module 名建议使用点分层级；每段用 `lower_snake_case`；module interface unit 推荐 `.cppm`。 +- Modules 工程：新增/删除/重命名 `.cppm` 或修改 `export module` 时，必须更新 CMake target 的模块 file-set/清单（否则构建容易漂移）。 +- Windows：不支持原生 Windows 开发环境；Windows 产物通过 Linux + Clang 交叉编译 profile 验证（profile 的 `[settings] os=Windows`）。 +- 依赖管理（如使用 Conan）：必须提供统一 preset（`conan-release`/`conan-debug`）；优先通过 `conan install` + `cmake --preset ...` 验证；如遇 Conan 家目录权限问题可临时设置 `CONAN_HOME=/tmp/conan-home`。 + +## 与开发规范的关系 + +- 在本仓库内：`docs/cpp/` 与 `docs/common/`。 +- 在目标项目内（若按 README 推荐的 subtree prefix `docs/standards/playbook`）： + - 代码风格：`docs/standards/playbook/docs/cpp/code_style.md` + - 命名规范：`docs/standards/playbook/docs/cpp/naming.md` + - 提交信息：`docs/standards/playbook/docs/common/commit_message.md` diff --git a/.agents/cpp/performance.md b/.agents/cpp/performance.md new file mode 100644 index 0000000..b76f73c --- /dev/null +++ b/.agents/cpp/performance.md @@ -0,0 +1,31 @@ +# 性能（Performance） + +本文件定义代理在做性能相关改动时的准则与检查项。 + +## 1. 目标与度量 + +- 明确性能目标：延迟、吞吐、内存、CPU、I/O 等。 +- 没有指标时不要盲目优化；先补充测量或基准。 + +## 2. 处理流程 + +1. 先定位瓶颈（profile/trace/log）。 +2. 再提出最小化改动方案。 +3. 最后用数据验证收益与副作用。 + +## 3. 优化准则 + +- 优先消除算法/结构性问题，再考虑微优化。 +- 避免引入复杂度换取小收益。 +- 性能优化不应牺牲可读性；必要时加注释说明权衡。 + +## 4. 常见风险 + +- 避免重复计算、无界缓存、隐式复制。 +- 注意热路径中的分配与 I/O。 +- 并发优化要考虑正确性与可测试性。 + +## 5. 验证 + +- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。 +- 若无测试体系，至少提供最小可运行的复现脚本/步骤。 diff --git a/.agents/cpp/testing.md b/.agents/cpp/testing.md new file mode 100644 index 0000000..dfb912a --- /dev/null +++ b/.agents/cpp/testing.md @@ -0,0 +1,26 @@ +# 测试（Testing） + +本文件定义代理在改动代码时的测试策略与要求。 + +## 1. 测试层级 + +- **单元测试**：验证函数/模块的独立行为。 +- **集成测试**：验证模块间交互与关键流程。 +- **回归测试**：防止已修复问题复发。 + +## 2. 何时补测试 + +- 新功能必须新增对应测试（若项目有测试体系）。 +- 修复 bug 必须先写/补回归用例（若项目有测试体系）。 +- 仅当改动纯文档/注释/格式时可不加测试。 + +## 3. 测试可维护性 + +- 一个用例只验证一个行为点。 +- 测试命名清晰，能从名字看出期望。 +- 避免依赖外部不稳定资源；必要时 mock/stub。 + +## 4. 运行与失败处理 + +- 若项目提供构建/冒烟命令（CMake），优先保证最小构建可通过。 +- 失败时优先定位改动相关原因，不修无关失败。 diff --git a/.agents/index.md b/.agents/index.md new file mode 100644 index 0000000..9fcce52 --- /dev/null +++ b/.agents/index.md @@ -0,0 +1,11 @@ +# .agents（多语言规则集快照） + +本目录用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**。 + +本仓库将规则按语言拆分为多个规则集快照： + +- `.agents/tsl/`：TSL 相关规则集（适用于 `.tsl`/`.tsf`） +- `.agents/cpp/`：C++ 相关规则集（C++23，含 Modules） +- `.agents/python/`：Python 相关规则集 + +目标项目落地时，通常通过 `scripts/sync_standards.*` 将某个规则集同步到目标项目根目录的 `.agents//`。 diff --git a/.agents/python/auth.md b/.agents/python/auth.md new file mode 100644 index 0000000..3194974 --- /dev/null +++ b/.agents/python/auth.md @@ -0,0 +1,15 @@ +# 安全与鉴权（Auth & Security） + +本文件定义代理在涉及鉴权/密钥/权限时必须遵守的最低要求（Python）。 + +## 基本原则 + +- 默认最小权限：避免使用全局管理员/Root 权限完成可在用户权限完成的事。 +- 不要提交任何密钥材料：token、私钥、证书、访问密钥、`.env` 中的真实值等。 +- 任何涉及加密/鉴权的实现变更必须说明威胁模型与兼容性影响。 + +## 常见风险与要求 + +- 输入校验：对外部输入（CLI 参数、环境变量、文件、网络数据）要做类型/范围校验，避免命令注入、路径穿越等问题。 +- 依赖安全：避免新增“来源不明”的依赖；如必须新增，需说明来源与版本锁定策略。 +- 日志脱敏：日志中不得输出凭据、个人敏感信息（PII）或可重放的签名/URL。 diff --git a/.agents/python/code_quality.md b/.agents/python/code_quality.md new file mode 100644 index 0000000..4dd8e61 --- /dev/null +++ b/.agents/python/code_quality.md @@ -0,0 +1,27 @@ +# 代码质量（Code Quality） + +本文件定义代理对代码质量的最低要求与审查清单（Python）。 + +## 1. 总体要求 + +- 改动聚焦目标；避免“顺手重构”。 +- API/行为变更要显式说明影响与迁移方式（尤其是脚本/CLI 输出与配置项）。 +- 保持仓库现有约定：优先复用既有结构、命名与工具配置（见 `docs/python/`）。 + +## 2. 可读性 + +- 复杂逻辑拆分为具名函数/模块；避免超长函数。 +- 尽量使用显式类型与数据结构表达意图（必要时补类型标注）。 +- 注释解释“为什么”，避免注释重复代码表述。 + +## 3. 错误处理 + +- 失败必须可观测：返回码/异常/日志至少一种要明确。 +- CLI/自动化脚本：遇到不可恢复错误应非零退出码。 + +## 4. Review 清单 + +- 是否引入了不必要的新依赖？ +- 是否遵循 `pyproject.toml` 与 lint 配置？ +- 是否对 I/O（文件/网络/数据库）失败路径做了处理？ +- 是否需要补测试或示例？ diff --git a/.agents/python/index.md b/.agents/python/index.md new file mode 100644 index 0000000..3cbbf57 --- /dev/null +++ b/.agents/python/index.md @@ -0,0 +1,40 @@ +# Python 代理规则集（.agents/python） + +本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（Python 语言专属）。 + +## 范围与优先级 + +- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。 +- 当代理规则与 `docs` 发生冲突时： + 1. 安全/合规优先 + 2. 其次保持仓库现有一致性 + +## 代理工作原则 + +- 先理解目标与上下文，再动手改代码。 +- 修改要小而清晰；避免无关重构。 +- 不要引入新依赖或工具，除非明确要求。 + +## 子文档 + +- 安全与鉴权：`auth.md` +- 性能：`performance.md` +- 代码质量：`code_quality.md` +- 测试：`testing.md` + +## Python 必要约定（必须遵守） + +- 代码风格基线：Google Python Style Guide。 +- 格式化与静态检查：优先使用仓库既有配置（`pyproject.toml`、`.flake8`、`.pylintrc`、`.pre-commit-config.yaml`）；不要在未沟通前切换到另一套工具链。 +- import 顺序：遵守 `isort profile = google`（若启用）。 +- 文档字符串：Google 风格（与 `.flake8`/团队约定对齐）。 +- 命名：遵循 `docs/python/style_guide.md` 中的约定；如与既有代码冲突，以局部一致性优先。 + +## 与开发规范的关系 + +- 在本仓库内：`docs/python/` 与 `docs/common/`。 +- 在目标项目内（若按 README 推荐的 subtree prefix `docs/standards/playbook`）： + - 代码风格：`docs/standards/playbook/docs/python/style_guide.md` + - 工具链：`docs/standards/playbook/docs/python/tooling.md` + - 配置说明：`docs/standards/playbook/docs/python/configuration.md` + - 提交信息：`docs/standards/playbook/docs/common/commit_message.md` diff --git a/.agents/python/performance.md b/.agents/python/performance.md new file mode 100644 index 0000000..f1e1b31 --- /dev/null +++ b/.agents/python/performance.md @@ -0,0 +1,15 @@ +# 性能（Performance） + +本文件定义代理在性能相关改动时的最低要求（Python）。 + +## 基本原则 + +- 先保证正确性与可读性，再做优化。 +- 优化前先定位瓶颈：避免盲目微优化。 +- 对可能影响性能的改动，说明复杂度变化与典型数据规模假设。 + +## 常见注意点 + +- 避免在热路径重复 I/O（文件读写、网络请求、重复解析）。 +- 对大列表/大文件处理优先采用流式处理与生成器。 +- 警惕 `O(n^2)` 循环、重复正则编译、重复 JSON/YAML 解析等。 diff --git a/.agents/python/testing.md b/.agents/python/testing.md new file mode 100644 index 0000000..cde0bcc --- /dev/null +++ b/.agents/python/testing.md @@ -0,0 +1,13 @@ +# 测试（Testing） + +本文件定义代理在测试相关工作的最低要求（Python）。 + +## 原则 + +- 优先增加与变更直接相关的测试（回归测试优先）。 +- 测试应可重复运行、无顺序依赖、尽量避免真实网络/真实环境依赖。 + +## 约定（模板） + +- 若项目使用 `pytest`：遵循 `pyproject.toml` 中的 `pytest.ini_options` 配置。 +- I/O 相关代码建议使用临时目录与 mock，避免污染工作区。 diff --git a/.agents/tsl/auth.md b/.agents/tsl/auth.md new file mode 100644 index 0000000..5adf24f --- /dev/null +++ b/.agents/tsl/auth.md @@ -0,0 +1,33 @@ +# 安全与鉴权（Auth） + +本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。 + +## 1. 基本原则 + +- **最小权限**：只使用完成任务所需的最低权限与最少数据。 +- **默认保守**：不确定是否敏感时按敏感处理。 +- **不扩散秘密**：任何 secret 只在必要范围内出现。 + +## 2. 凭证与敏感信息 + +- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。 +- 如需示例，使用占位符：``、``。 +- 避免把敏感信息打印到标准输出或错误日志。 + +## 3. 鉴权逻辑修改 + +- 修改鉴权/权限控制时必须说明： + - 变更动机 + - 风险评估 + - 兼容性/回滚方案 +- 默认保持旧行为兼容，除非明确要求破坏性变更。 + +## 4. 依赖与第三方 + +- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。 +- 若必须新增，需在 PR 说明理由、替代方案与安全影响。 + +## 5. 审计与合规 + +- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。 +- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。 diff --git a/.agents/tsl/code_quality.md b/.agents/tsl/code_quality.md new file mode 100644 index 0000000..ce2c014 --- /dev/null +++ b/.agents/tsl/code_quality.md @@ -0,0 +1,32 @@ +# 代码质量（Code Quality） + +本文件定义代理对代码质量的最低要求与审查清单（TSL）。 + +## 1. 总体要求 + +- 对 `.tsl`/`.tsf` 文件一律按 TSL 规范处理（`.tsf` 也是 TSL 源文件）：遵守标准快照中的 `docs/tsl/code_style.md` 与 `docs/tsl/naming.md`（在目标项目中通常 vendoring 到 `docs/standards/playbook/docs/tsl/`）。 +- 改动聚焦目标；避免“顺手重构”。 +- API 变更要显式说明影响与迁移方式。 + +## 2. 可读性 + +- 复杂逻辑拆分为具名函数/变量。 +- 避免深层嵌套与重复代码。 +- 必要注释解释“为什么”而不是“做什么”。 + +## 3. 错误处理 + +- 错误必须显式处理；禁止静默吞错。 +- 失败路径要可观测（返回/抛出/日志）。 + +## 4. 复杂度与规模 + +- 单函数尽量 ≤ 60 行；超过应说明原因或拆分。 +- 单次 PR 尽量小步提交，便于 review。 + +## 5. Review 清单 + +- 是否有无关改动？ +- 是否有清晰的动机与行为说明？ +- 是否保持模块内风格一致？ +- 是否需要补测试/示例？ diff --git a/.agents/tsl/index.md b/.agents/tsl/index.md new file mode 100644 index 0000000..ba3cae3 --- /dev/null +++ b/.agents/tsl/index.md @@ -0,0 +1,39 @@ +# TSL 代理规则集（.agents/tsl） + +本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（TSL 语言专属）。 + +## 范围与优先级 + +- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。 +- 当代理规则与 `docs` 发生冲突时： + 1. 安全/合规优先 + 2. 其次保持仓库现有一致性 + +## 代理工作原则 + +- 先理解目标与上下文，再动手改代码。 +- 修改要小而清晰；避免无关重构。 +- 任何可能影响行为的改动都要补充或更新测试/示例（若项目有测试体系）。 +- 不要引入新依赖或工具，除非明确要求。 + +## 子文档 + +- 安全与鉴权：`auth.md` +- 性能：`performance.md` +- 代码质量：`code_quality.md` +- 测试：`testing.md` + +## TSL/TSF 必要约定（必须遵守） + +- `.tsl` 与 `.tsf` 都是 Tinysoft Language 源文件；修改它们时统一按 TSL 规范处理（不要把 `.tsf` 当成“另一种语言/无风格约束的脚本”）。 +- 文件级约束：一个文件只能有一个顶层声明，且文件基名必须与该顶层声明同名（推荐 `PascalCase`）；`.tsl` 顶层声明只能是 `function`。 +- 格式：空格缩进（默认 4 空格），关键字用小写，复杂分支/多语句分支用 `begin/end` 块表达结构。 +- 命名：类型/顶层函数/property 用 `PascalCase`；局部变量/参数用 `snake_case`；私有成员变量用 `snake_case_`。 + +## 与开发规范的关系 + +- 在本仓库内：`docs/tsl/` 与 `docs/common/`。 +- 在目标项目内（若按 README 推荐的 subtree prefix `docs/standards/playbook`）： + - 代码风格：`docs/standards/playbook/docs/tsl/code_style.md` + - 命名规范：`docs/standards/playbook/docs/tsl/naming.md` + - 提交信息：`docs/standards/playbook/docs/common/commit_message.md` diff --git a/.agents/tsl/performance.md b/.agents/tsl/performance.md new file mode 100644 index 0000000..b76f73c --- /dev/null +++ b/.agents/tsl/performance.md @@ -0,0 +1,31 @@ +# 性能（Performance） + +本文件定义代理在做性能相关改动时的准则与检查项。 + +## 1. 目标与度量 + +- 明确性能目标：延迟、吞吐、内存、CPU、I/O 等。 +- 没有指标时不要盲目优化；先补充测量或基准。 + +## 2. 处理流程 + +1. 先定位瓶颈（profile/trace/log）。 +2. 再提出最小化改动方案。 +3. 最后用数据验证收益与副作用。 + +## 3. 优化准则 + +- 优先消除算法/结构性问题，再考虑微优化。 +- 避免引入复杂度换取小收益。 +- 性能优化不应牺牲可读性；必要时加注释说明权衡。 + +## 4. 常见风险 + +- 避免重复计算、无界缓存、隐式复制。 +- 注意热路径中的分配与 I/O。 +- 并发优化要考虑正确性与可测试性。 + +## 5. 验证 + +- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。 +- 若无测试体系，至少提供最小可运行的复现脚本/步骤。 diff --git a/.agents/tsl/testing.md b/.agents/tsl/testing.md new file mode 100644 index 0000000..6e11561 --- /dev/null +++ b/.agents/tsl/testing.md @@ -0,0 +1,26 @@ +# 测试（Testing） + +本文件定义代理在改动代码时的测试策略与要求。 + +## 1. 测试层级 + +- **单元测试**：验证函数/模块的独立行为。 +- **集成测试**：验证模块间交互与关键流程。 +- **回归测试**：防止已修复问题复发。 + +## 2. 何时补测试 + +- 新功能必须新增对应测试。 +- 修复 bug 必须先写/补回归用例。 +- 仅当改动纯文档/注释/格式时可不加测试。 + +## 3. 测试可维护性 + +- 一个用例只验证一个行为点。 +- 测试命名清晰，能从名字看出期望。 +- 避免依赖外部不稳定资源；必要时 mock/stub。 + +## 4. 运行与失败处理 + +- 本仓库未来若引入测试命令，需在此补充统一的运行方式。 +- 测试失败时优先定位改动相关原因，不修无关失败。 diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..c0f4849 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,57 @@ +# Ensure all text files use UTF-8 (by convention) and LF line endings. +# Line endings are normalized to LF in the repo and checked out as LF, +# regardless of OS/core.autocrlf settings. + +# Default: detect text automatically, enforce LF on checkout/commit. +* text=auto eol=lf + +# Explicit text types in this repo. +*.tsl text eol=lf +*.tsf text eol=lf +*.md text eol=lf +*.txt text eol=lf +*.json text eol=lf +*.yml text eol=lf +*.yaml text eol=lf +*.toml text eol=lf +*.ini text eol=lf +*.cfg text eol=lf +*.xml text eol=lf +*.csv text eol=lf +*.sh text eol=lf +*.py text eol=lf +*.pyi text eol=lf +*.pyx text eol=lf +*.pxd text eol=lf +*.pxi text eol=lf +*.c text eol=lf +*.h text eol=lf +*.cc text eol=lf +*.cpp text eol=lf +*.cxx text eol=lf +*.hh text eol=lf +*.hpp text eol=lf +*.hxx text eol=lf +*.inl text eol=lf +*.ipp text eol=lf +*.ixx text eol=lf +*.cppm text eol=lf +*.mpp text eol=lf +*.cmake text eol=lf +CMakeLists.txt text eol=lf +CMakePresets.json text eol=lf +*.clangd text eol=lf +.clangd text eol=lf + +# Binary files (no line-ending conversion). +*.png binary +*.jpg binary +*.jpeg binary +*.gif binary +*.ico binary +*.pdf binary +*.zip binary +*.7z binary +*.gz binary +*.tar binary +*.exe binary diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..ec2481e --- /dev/null +++ b/.gitignore @@ -0,0 +1,21 @@ +# ---> Vim +# Swap +[._]*.s[a-v][a-z] +!*.svg # comment out if you don't need vector files +[._]*.sw[a-p] +[._]s[a-rt-v][a-z] +[._]ss[a-gi-z] +[._]sw[a-p] + +# Session +Session.vim +Sessionx.vim + +# Temporary +.netrwhist +*~ +# Auto-generated tag files +tags +# Persistent undo +[._]*.un~ + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5e4b261 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,7 @@ +# Contributing + +## Commit messages + +Follow the repository commit message standard: + +- `docs/common/commit_message.md` diff --git a/README.md b/README.md new file mode 100644 index 0000000..b11292c --- /dev/null +++ b/README.md @@ -0,0 +1,296 @@ +# playbook + +Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合集。 + +## 目标 + +- 让代码**易读、易维护、易演进**。 +- 风格保持一致，减少无意义的差异。 +- 在不影响清晰度的前提下，尽量简洁。 + +## 原则 + +1. **可读性优先**：读代码的时间远大于写代码。 +2. **一致性优先**：同一仓库内保持一致比追求“最优风格”更重要。 +3. **遵从既有代码**：修改/扩展现有代码时优先沿用其局部风格。 + +## 适用范围 + +- 本指南适用于所有 TSL 相关仓库与脚本。 +- 当现有代码与本指南冲突时，**以保持局部一致性为优先**，逐步迁移。 + +## docs/（开发规范） + +`docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。 + +- `docs/index.md`：文档导航（跨语言 common / TSL / C++ / Python）。 +- `docs/common/commit_message.md`：提交信息与版本号规范（type/scope/subject/body/footer、可选 Emoji 图例、SemVer）。 +- `docs/tsl/code_style.md`：TSL 代码结构、格式、`begin/end` 代码块、注释与通用最佳实践。 +- `docs/tsl/naming.md`：TSL 命名规范（顶层声明、文件同名规则、变量/成员/property、常量、集合命名等）。 +- `docs/tsl/toolchain.md`：TSL 工具链与验证命令模板。 +- `docs/cpp/code_style.md`：C++ 代码风格（C++23/Modules）。 +- `docs/cpp/naming.md`：C++ 命名规范（Google 基线）。 +- `docs/cpp/toolchain.md`：C++ 工具链与验证命令模板。 +- `docs/cpp/dependencies_conan.md`：C++ Conan 依赖管理建议。 +- `docs/cpp/clangd.md`：clangd 补全配置建议（`.clangd`）。 +- `docs/python/style_guide.md`：Python 代码风格（Google 基线）。 +- `docs/python/tooling.md`：Python 工具链（black/isort/flake8/pylint/mypy/pytest/pre-commit）。 +- `docs/python/configuration.md`：Python 配置清单（落地时从 `templates/python/` 复制到项目根目录）。 +- `templates/cpp/`：C++ 落地模板（`.clang-format`、`conanfile.txt`、`CMakeUserPresets.json`、`CMakeLists.txt`）。 +- `templates/python/`：Python 落地模板（`pyproject.toml` 工具配置、`.flake8`、`.pylintrc`、`.pre-commit-config.yaml`、`.editorconfig`、`.vscode/settings.json`）。 + +## .agents/（代理规则） + +`.agents/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则快照，与 `docs/` 并行。 + +- `.agents/index.md`：规则集索引（多语言）。 +- `.agents/tsl/`：TSL 规则集（入口：`.agents/tsl/index.md`）。 +- `.agents/cpp/`：C++ 规则集（入口：`.agents/cpp/index.md`）。 + +## 在其他项目中使用本 Playbook + +由于本仓库需要内部权限访问，其他项目**不能仅用外链引用**；推荐把 Playbook 规范 vendoring 到项目内。 + +### 方式一：git subtree 同步（推荐） + +1. 在目标项目中首次引入： + + ```bash + git subtree add \ + --prefix docs/standards/playbook \ + https://git.mytsl.cn/csh/playbook.git \ + main --squash + ``` + +2. 后续同步更新： + + ```bash + git subtree pull \ + --prefix docs/standards/playbook \ + https://git.mytsl.cn/csh/playbook.git \ + main --squash + ``` + +#### 快速落地（最小 4 步） + +在目标项目中按以下顺序执行即可完成落地（推荐固定使用 `--prefix docs/standards/playbook`）： + +1. 引入标准快照（见上文 `git subtree add`） +2. 同步到项目根目录（生成/更新 `.agents//`、更新 `.gitattributes`）： + + ```bash + sh docs/standards/playbook/scripts/sync_standards.sh + ``` + + 同步 C++ 规则集（同一份快照，不同规则集）： + + ```bash + sh docs/standards/playbook/scripts/sync_standards.sh cpp + ``` + + 一次同步多个规则集（推荐，减少重复备份 `.gitattributes`）： + + ```bash + sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp + ``` + +3. 验收（任意满足其一即可）： + + - 目录存在：`.agents/tsl/` + - 规则入口可读：`.agents/tsl/index.md` + - （可选）C++ 规则入口可读：`.agents/cpp/index.md` + - 标准文档可读：`docs/standards/playbook/docs/index.md` + - `.gitattributes` 包含区块：`# BEGIN playbook .gitattributes` / `# END playbook .gitattributes` + +4. 将同步产物纳入版本控制（目标项目建议提交）： + - `docs/standards/playbook/`（标准快照） + - `.agents/tsl/`（落地规则集） + - `.gitattributes`（managed block 更新） + +#### 可选：项目包装脚本（多 playbook 串联） + +多语言项目建议在目标项目创建一个包装脚本（便于一键同步多个规则集）： + +```sh +#!/usr/bin/env sh +set -eu + +sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp +# sh docs/standards/python/scripts/sync_standards.sh +``` + +也可以直接一次同步多个规则集： + +```sh +sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp +``` + +#### 目录约定（建议） + +目标项目推荐采用以下结构（Playbook 快照与项目文档分离）： + +```txt +. +├── .agents/ +│ ├── index.md # 多语言代理规则集索引（缺省时由脚本创建） +│ ├── tsl/ # 从 Playbook 同步（仅覆盖该子目录） +│ └── cpp/ # 从 Playbook 同步（仅覆盖该子目录，按需） +├── .gitattributes # 从 Playbook 同步 +├── docs/ +│ ├── standards/ +│ │ └── tsl/ # git subtree 快照（只读） +│ │ ├── docs/ # common/ + tsl/ + cpp/ +│ │ ├── .agents/ # 标准代理规则快照 +│ │ ├── .gitattributes +│ │ └── SOURCE.md # 记录来源版本/commit（项目自行维护） +│ └── project/ # 目标项目自己的文档（非语言标准：架构/运行/ADR/使用说明/业务约定等） +└── README.md # 说明遵循 standards +``` + +根目录的 `.agents//` 与 `.gitattributes` 通过同步脚本获得： + +- 说明：在 **本 playbook 仓库** 内脚本位于 `scripts/`；在 **目标项目** 里通过 `git subtree` 引入到 `docs/standards/playbook/` 后，脚本路径变为 `docs/standards/playbook/scripts/`。 +- 在目标项目里直接运行 Playbook 提供的脚本（子树快照里自带）： +- `docs/standards/playbook/scripts/sync_standards.sh`（推荐，支持多语言参数） +- `docs/standards/playbook/scripts/sync_standards.ps1`（推荐，支持多语言参数） +- `docs/standards/playbook/scripts/sync_standards.bat`（推荐，支持多语言参数） +- 脚本会从快照目录同步到项目根目录，并先备份旧文件（`.bak.*`）。 + +注：建议固定使用 `--prefix docs/standards/playbook`，因为同步后的 `.agents/*/` 会引用该路径下的标准快照文档（`docs/standards/playbook/docs/...`）。 +注：默认同步到 `.agents/tsl/`；如需同步 C++ 规则集，推荐直接运行：`sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp`。 + +这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。 + +同步脚本行为（目标项目内的最终落地内容）： + +- 覆盖/更新：`.agents//`（默认 `.agents/tsl/`） +- 更新 `.gitattributes`：默认只维护 `# BEGIN playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制） +- 缺省创建：`.agents/index.md` +- 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀） +- 不修改：`.gitignore`（项目自行维护） + +#### 环境变量（可选） + +同步脚本支持以下可选环境变量（默认值可满足大多数项目）： + +| 变量名 | 默认值 | 说明 | +| ------------------- | ------- | ------------------------------------------------------------------------------------------- | +| `AGENTS_NS` | `tsl` | 同步的规则集名/落地目录名：`.agents//`（例如 `tsl`、`cpp`） | +| `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式：`block` 仅维护 managed 区块；`overwrite` 全量覆盖；`skip` 不更新 | + +### 方式二：手动复制快照 + +如果不使用 `git subtree`，也可以由有权限的人手动复制 Playbook 到目标项目中（适合规范不频繁更新或项目数量较少的情况）。 + +步骤： + +1. 在目标项目创建目录：`docs/standards/playbook/`。 +2. 从本仓库复制以下内容到目标项目： + - `docs/` → `docs/standards/playbook/docs/`（包含 `docs/common/`、`docs/tsl/`、`docs/cpp/`、`docs/python/`） + - `.agents/` → `docs/standards/playbook/.agents/` + - `.gitattributes` → `docs/standards/playbook/.gitattributes` + - `scripts/` → `docs/standards/playbook/scripts/` +3. 在目标项目根目录运行同步脚本，把 `.agents/tsl/` 与 `.gitattributes` 落到根目录（见上文脚本路径）。 +4. 在 `docs/standards/playbook/SOURCE.md` 记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。 + +该方式没有自动同步能力，后续更新需重复上述复制流程。 + +### 多语言项目落地（TSL + C++/其他语言） + +多语言项目建议把规范拆成两类： + +1. **仓库级（跨语言）共识**：对所有语言都成立的规则与流程。 + - 提交信息：`docs/common/commit_message.md` + - 行尾与文本规范：`.gitattributes` + - 代理最低要求：`.agents/*`（工作原则、质量底线、安全边界） +2. **语言级（Language-specific）规范**：只对某个语言成立的风格与工具。 + - 例如 TSL 的命名/文件顶层声明限制、C++ 的 `.clang-format/.clang-tidy`、Python 的 `ruff` 等。 + +建议：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相“污染”。 + +本仓库提供两套代理规则集（同步后位于目标项目的 `.agents/tsl/` 与 `.agents/cpp/`）： + +- 两者都包含跨语言通用底线：`auth.md`、`code_quality.md`、`performance.md`、`testing.md` +- 并在 `index.md` 中叠加语言级“硬约束”（TSL/TSF 语法限制、C++23/Modules、Windows 支持等） + +多语言项目推荐结构（示例：TSL + C++ + Python）： + +```txt +. +├── .agents/ +│ ├── index.md # 多语言索引（缺省时由脚本创建） +│ ├── tsl/ # 由本 Playbook 同步（适用于 .tsl/.tsf） +│ ├── cpp/ # 由本 Playbook 同步（适用于 C++23/Modules） +│ └── python/ # Python 规则集（同上） +├── .gitattributes # 行尾/文本规范（可由某个 playbook 同步） +├── docs/ +│ ├── standards/ +│ │ ├── tsl/ # 本 Playbook 快照（git subtree/vendoring；包含 common/tsl/cpp） +│ │ └── python/ # Python playbook 快照（可选） +│ └── project/ # 项目自有文档（架构、ADR、运行方式等） +├── scripts/ +│ └── sync_standards.sh # 项目包装脚本：依次调用各 playbook 的 sync +└── src/ # 源码目录（按项目实际情况） +``` + +规则优先级建议： + +- 同一项目内多个规则集并行放在 `.agents//`，不要互相覆盖。 +- 若某个子目录需要更具体规则（模块/子系统差异），在更靠近代码的目录放置更具体规则（例如 `src/foo/.agents/`），并以“离代码更近者优先”为准。 + +#### `.agents` 的覆盖/合并策略（可执行流程） + +同步脚本会同步到项目根目录的 `.agents/tsl/`（并不会覆盖 `.agents/` 下的其他语言目录）。若项目需要追加 C++ 等语言/模块专属规则，建议二选一： + +1. **推荐：子目录规则覆盖（无需改同步脚本）** + - 让本 Playbook 的规则集固定落在 `.agents/tsl/`，由同步脚本维护。 + - 在其他语言/模块目录下新增更具体规则，例如 `.agents/cpp/`、`cpp/.agents/`、`src/.agents/`。 +2. **Overlay 合并：项目维护叠加层并在同步后覆盖回去** + - 约定项目自定义规则放在 `docs/project/agents_overlay/`（不叫 `.agents`，避免被同步覆盖）。 + - 每次运行 `sync_standards.*` 后，再把 overlay 覆盖回 `.agents/tsl/`（建议封装成项目脚本）。 + +macOS/Linux 示例（目标项目的 `scripts/sync_standards.sh`）： + +```sh +#!/usr/bin/env sh +set -eu + +sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp + +OVERLAY="docs/project/agents_overlay" +if [ -d "$OVERLAY" ]; then + cp -R "$OVERLAY"/. ".agents/tsl/" + echo "Applied agents overlay." +fi +``` + +PowerShell 示例（目标项目的 `scripts/sync_standards.ps1`）： + +```powershell +& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs tsl,cpp + +$overlay = "docs/project/agents_overlay" +if (Test-Path $overlay) { + Copy-Item "$overlay\\*" ".agents\\tsl" -Recurse -Force + Write-Host "Applied agents overlay." +} +``` + +#### 扩展新语言（模板） + +当目标项目需要新增一门语言（例如 C++），建议按以下模板扩展： + +- 文档： + - 若使用本 Playbook 自带的 C++ 规范：无需额外 subtree，直接使用 `docs/standards/playbook/docs/cpp/`，并在项目 `README.md`/`docs/index.md` 链接入口。 + - 若新增“本 Playbook 未覆盖的语言”：再引入对应语言的标准仓库（subtree/vendoring 到 `docs/standards//`）。 +- 代理规则： + - C++：运行 `sh docs/standards/playbook/scripts/sync_standards.sh cpp`（或 `& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs cpp`），落地到 `.agents/cpp/`（与 `.agents/tsl/` 并行）。 + - 其他语言：在目标项目增加 `.agents//`（与 `.agents/tsl/` 并行），只写该语言专属要求与工具链约束。 +- 同步策略：每个规则集只同步到对应子目录（例如 `.agents/cpp/`），避免覆盖整个 `.agents/`。 +- CI/工具：按文件类型分别执行格式化、lint、测试（不要让 TSL 规则去约束 C++ 代码，反之亦然）。 + - C++ 补全：建议在项目根目录提供 `.clangd` 并指向正确的 `CompilationDatabase`（模板见 `templates/cpp/.clangd`）。 + +## 版本与贡献 + +- 本项目会持续迭代；变更以 PR 形式提交。 +- 新规则需包含动机、示例、迁移建议（如有）。 diff --git a/docs/common/commit_message.md b/docs/common/commit_message.md new file mode 100644 index 0000000..b4e66de --- /dev/null +++ b/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 +``` diff --git a/docs/cpp/clangd.md b/docs/cpp/clangd.md new file mode 100644 index 0000000..eaddff9 --- /dev/null +++ b/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 补全/跳转不稳定。 diff --git a/docs/cpp/code_style.md b/docs/cpp/code_style.md new file mode 100644 index 0000000..4aecfd9 --- /dev/null +++ b/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/平台差异）。 +- 对路径、换行、编码、大小写敏感等行为要明确约束并在文档/测试中覆盖。 diff --git a/docs/cpp/dependencies_conan.md b/docs/cpp/dependencies_conan.md new file mode 100644 index 0000000..90bf3ca --- /dev/null +++ b/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/ + --clang + windows--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` diff --git a/docs/cpp/naming.md b/docs/cpp/naming.md new file mode 100644 index 0000000..923011b --- /dev/null +++ b/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 名使用点分层级：`..` +- 每一段建议用 `lower_snake_case`： + - 示例：`my_project.market.data_feed` +- 文件路径建议与 module 名可映射（便于检索与定位）。 diff --git a/docs/cpp/toolchain.md b/docs/cpp/toolchain.md new file mode 100644 index 0000000..f7a291f --- /dev/null +++ b/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 ` 做格式校验。 + +### 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/ ` +- 或：`cmake --build build -t run_smoke`（如项目提供自定义 target） + +### 2.3 格式化检查（建议） + +- `clang-format -i `（本地） +- `clang-format --dry-run --Werror `（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，保证命令可复现。 diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..5960860 --- /dev/null +++ b/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` diff --git a/docs/python/configuration.md b/docs/python/configuration.md new file mode 100644 index 0000000..069ddd5 --- /dev/null +++ b/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 diff --git a/docs/python/style_guide.md b/docs/python/style_guide.md new file mode 100644 index 0000000..4fbcad8 --- /dev/null +++ b/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` + +当既有代码与本约定冲突时，优先保持局部一致性，逐步迁移。 diff --git a/docs/python/tooling.md b/docs/python/tooling.md new file mode 100644 index 0000000..38ce884 --- /dev/null +++ b/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 +``` diff --git a/docs/tsl/code_style.md b/docs/tsl/code_style.md new file mode 100644 index 0000000..e800b09 --- /dev/null +++ b/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 性能与可测试性 + +- 避免过早优化；先写清晰正确的代码，再用数据驱动优化。 +- 复杂逻辑要可测试：拆成纯函数或可注入依赖的模块。 diff --git a/docs/tsl/naming.md b/docs/tsl/naming.md new file mode 100644 index 0000000..17ce989 --- /dev/null +++ b/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_` 表达键语义：`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()` 形式。 +- 示例：`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++ 库、历史接口、跨语言互操作代码等。 diff --git a/docs/tsl/toolchain.md b/docs/tsl/toolchain.md new file mode 100644 index 0000000..4047bfc --- /dev/null +++ b/docs/tsl/toolchain.md @@ -0,0 +1,62 @@ +# TSL 工具链与验证命令（模板） + +本文件提供一份**通用占位模板**，用于在不同 TSL 项目中快速补齐“工具链与如何验证”的关键上下文。 + +使用方式： + +- 在具体项目中复制本模板并把占位符替换为真实信息； +- 或在项目文档中引用本模板，并在项目内提供对应的 `scripts/*` 统一入口脚本。 + +## 1. TSL 工具链 + +### 1.1 解释器/编译器（必填） + +- 工具名称：`` +- 可执行命令： + - macOS/Linux：``（例：`tsl` / `tslcli` / `sh scripts/tsl.sh`） + - Windows：``（例：`tsl.exe` / `tslcli.exe` / `powershell -File scripts/tsl.ps1`） +- 版本要求：`<固定版本或范围，例如：= 3.2.1 / >=3.2,<4.0>` +- 安装方式：`<内部安装包/路径/IDE 自带/CI 镜像等>` +- 推荐统一入口脚本：`scripts/tsl.{sh,ps1}`（封装参数与环境变量，避免每个任务重复猜测） + +### 1.2 运行环境（按需） + +- 必要环境变量：` ...` +- 外部依赖：`<数据库/服务/共享目录/网络权限/账户权限>` +- 运行约束： + - 是否允许联网：`` + - 是否需要许可证/凭证：`<说明如何在本地与 CI 提供；禁止写入仓库>` + +## 2. 验证命令 + +> 要求：改动完成后至少能跑通“最小冒烟”；若项目存在测试体系，尽量补到对应层级。 + +### 2.1 最小冒烟（必须能跑） + +- macOS/Linux：` run -- ` +- Windows：` run -- ` +- 或统一入口： + - `sh scripts/smoke.sh` + - `powershell -File scripts/smoke.ps1` + +### 2.2 单元测试（如有） + +- `sh scripts/test.sh` +- 或：` test ` +- 或：` run ` + +### 2.3 静态检查/格式化（如有） + +- `sh scripts/lint.sh` +- `sh scripts/format.sh` +- 或：` check ` / ` fmt ` + +### 2.4 构建/打包（如有） + +- `sh scripts/build.sh` +- 或：` build ` + +### 2.5 失败处理约定（必填） + +- 只修复与本次改动直接相关的失败；无关失败在输出中说明并隔离。 +- 若某验证步骤无法执行（缺环境/缺凭证），必须明确写出原因与替代验证手段（例如最小复现脚本/手动检查清单）。 diff --git a/scripts/sync_standards.bat b/scripts/sync_standards.bat new file mode 100644 index 0000000..48877ce --- /dev/null +++ b/scripts/sync_standards.bat @@ -0,0 +1,223 @@ +@echo off +setlocal enabledelayedexpansion + +rem Sync standards snapshot to project root. +rem - Copies \.agents\ -> \.agents\ +rem - Updates \.gitattributes (managed block by default) +rem Existing targets are backed up before overwrite. +rem +rem Multi rulesets: +rem sync_standards.bat tsl cpp +rem Notes: +rem - When syncing multiple rulesets, .gitattributes is synced only once (first ruleset). + +set "SCRIPT_DIR=%~dp0" +for /f "delims=" %%R in ('git -C "%SCRIPT_DIR%" rev-parse --show-toplevel 2^>nul') do set "ROOT=%%R" +if "%ROOT%"=="" set "ROOT=%cd%" +for %%I in ("%ROOT%") do set "ROOT=%%~fI" + +for %%I in ("%SCRIPT_DIR%..") do set "SRC=%%~fI" +set "AGENTS_SRC_ROOT=%SRC%\.agents" +set "GITATTR_SRC=%SRC%\.gitattributes" +set "AGENTS_NS=%AGENTS_NS%" +if "%AGENTS_NS%"=="" set "AGENTS_NS=tsl" +echo %AGENTS_NS%| findstr /r "[\\/]" >nul && ( + echo ERROR: invalid AGENTS_NS=%AGENTS_NS% + exit /b 1 +) +echo %AGENTS_NS%| findstr /c:".." >nul && ( + echo ERROR: invalid AGENTS_NS=%AGENTS_NS% + exit /b 1 +) +set "AGENTS_ROOT=%ROOT%\.agents" +set "AGENTS_DST=%AGENTS_ROOT%\%AGENTS_NS%" +set "GITATTR_DST=%ROOT%\.gitattributes" +set "SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE%" +if "%SYNC_GITATTR_MODE%"=="" set "SYNC_GITATTR_MODE=block" + +rem Multi rulesets: only on outer invocation. +if "%SYNC_STANDARDS_INNER%"=="" ( + if not "%~1"=="" ( + set "FIRST=1" + set "SYNC_FIRST=%SYNC_GITATTR_MODE%" + for %%L in (%*) do ( + if "!FIRST!"=="1" ( + set "FIRST=0" + set "SYNC_STANDARDS_INNER=1" + set "AGENTS_NS=%%~L" + set "SYNC_GITATTR_MODE=!SYNC_FIRST!" + call "%~f0" + ) else ( + set "SYNC_STANDARDS_INNER=1" + set "AGENTS_NS=%%~L" + set "SYNC_GITATTR_MODE=skip" + call "%~f0" + ) + ) + exit /b 0 + ) +) + +set "AGENTS_SRC=%AGENTS_SRC_ROOT%\%AGENTS_NS%" +if not exist "%AGENTS_SRC%" ( + rem Backward-compatible fallback: older snapshots used \.agents\* directly. + if exist "%AGENTS_SRC_ROOT%\index.md" if exist "%AGENTS_SRC_ROOT%\auth.md" ( + set "AGENTS_SRC=%AGENTS_SRC_ROOT%" + ) else ( + echo ERROR: Standards snapshot not found at "%AGENTS_SRC%". + echo Hint: set AGENTS_NS to one of the subdirs under "%AGENTS_SRC_ROOT%" (e.g. tsl/cpp). + exit /b 1 + ) +) +if not exist "%AGENTS_SRC%" ( + echo ERROR: Standards snapshot not found at "%AGENTS_SRC%". + echo Run: git subtree add --prefix docs/standards/playbook ^ ^ --squash + exit /b 1 +) + +if /I "%SRC%"=="%ROOT%" ( + echo Skip: snapshot root equals project root. + goto AfterGitAttr +) + +if not exist "%AGENTS_ROOT%" mkdir "%AGENTS_ROOT%" + +if exist "%AGENTS_DST%" ( + set "RAND=%RANDOM%" + pushd "%AGENTS_ROOT%" + ren "%AGENTS_NS%" "%AGENTS_NS%.bak.!RAND!" + popd + echo Backed up existing %AGENTS_NS% agents -> %AGENTS_NS%.bak.!RAND! +) + +xcopy "%AGENTS_SRC%\\*" "%AGENTS_DST%\\" /e /i /y >nul +if errorlevel 1 ( + echo ERROR: failed to copy .agents + exit /b 1 +) + +echo Synced .agents\%AGENTS_NS% from standards. + +if not exist "%AGENTS_ROOT%\index.md" ( + > "%AGENTS_ROOT%\index.md" echo # .agents（多语言） + >> "%AGENTS_ROOT%\index.md" echo. + >> "%AGENTS_ROOT%\index.md" echo 本目录用于存放仓库级/语言级的代理规则集。 + >> "%AGENTS_ROOT%\index.md" echo. + >> "%AGENTS_ROOT%\index.md" echo 建议约定： + >> "%AGENTS_ROOT%\index.md" echo. + >> "%AGENTS_ROOT%\index.md" echo - `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`） + >> "%AGENTS_ROOT%\index.md" echo - `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules） + >> "%AGENTS_ROOT%\index.md" echo - `.agents/python/` 等：其他语言的规则集（按需增加） + >> "%AGENTS_ROOT%\index.md" echo. + >> "%AGENTS_ROOT%\index.md" echo 规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。 + >> "%AGENTS_ROOT%\index.md" echo. + >> "%AGENTS_ROOT%\index.md" echo 入口建议从： + >> "%AGENTS_ROOT%\index.md" echo. + >> "%AGENTS_ROOT%\index.md" echo - `.agents/tsl/index.md`（TSL 规则集入口） + >> "%AGENTS_ROOT%\index.md" echo - `.agents/cpp/index.md`（C++ 规则集入口） + >> "%AGENTS_ROOT%\index.md" echo - `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`） + echo Created .agents\index.md +) + +:SyncGitAttr +if exist "%GITATTR_SRC%" ( + if /I "%SYNC_GITATTR_MODE%"=="skip" ( + echo Skip: .gitattributes sync ^(SYNC_GITATTR_MODE=skip^). + goto AfterGitAttr + ) + + if /I "%SYNC_GITATTR_MODE%"=="overwrite" ( + for %%I in ("%GITATTR_SRC%") do set "GITATTR_SRC_F=%%~fI" + for %%I in ("%GITATTR_DST%") do set "GITATTR_DST_F=%%~fI" + if /I "!GITATTR_SRC_F!"=="!GITATTR_DST_F!" ( + echo Skip: .gitattributes source equals destination. + goto AfterGitAttr + ) + + if exist "%GITATTR_DST%" ( + set "RAND=%RANDOM%" + set "BAK_NAME=.gitattributes.bak.!RAND!" + ren "%GITATTR_DST%" "!BAK_NAME!" + echo Backed up existing .gitattributes -> !BAK_NAME! + ) + copy /y "%GITATTR_SRC%" "%GITATTR_DST%" >nul + echo Synced .gitattributes from standards ^(overwrite^). + goto AfterGitAttr + ) + + if /I not "%SYNC_GITATTR_MODE%"=="block" ( + echo ERROR: invalid SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE% ^(use block^|overwrite^|skip^) + exit /b 1 + ) + + rem block mode: maintain a managed block inside the destination file + set "BEGIN=# BEGIN playbook .gitattributes" + set "END=# END playbook .gitattributes" + set "BEGIN_OLD=# BEGIN tsl-playbook .gitattributes" + set "END_OLD=# END tsl-playbook .gitattributes" + set "TMP_FILE=%TEMP%\\gitattributes.%RANDOM%.tmp" + + if exist "%GITATTR_DST%" ( + set "RAND=%RANDOM%" + set "BAK_NAME=.gitattributes.bak.!RAND!" + ren "%GITATTR_DST%" "!BAK_NAME!" + echo Backed up existing .gitattributes -> !BAK_NAME! + set "DST_IN=%ROOT%\\!BAK_NAME!" + ) else ( + set "DST_IN=" + ) + + set "IN_BLOCK=0" + set "DONE=0" + + if not "%DST_IN%"=="" ( + > "!TMP_FILE!" ( + for /f "usebackq delims=" %%L in ("!DST_IN!") do ( + set "LINE=%%L" + if "!LINE!"=="%BEGIN%" ( + if "!DONE!"=="0" ( + echo %BEGIN% + type "%GITATTR_SRC%" + echo %END% + set "DONE=1" + ) + set "IN_BLOCK=1" + ) else if "!LINE!"=="%BEGIN_OLD%" ( + if "!DONE!"=="0" ( + echo %BEGIN% + type "%GITATTR_SRC%" + echo %END% + set "DONE=1" + ) + set "IN_BLOCK=1" + ) else if "!LINE!"=="%END%" ( + set "IN_BLOCK=0" + ) else if "!LINE!"=="%END_OLD%" ( + set "IN_BLOCK=0" + ) else ( + if "!IN_BLOCK!"=="0" echo(!LINE! + ) + ) + if "!DONE!"=="0" ( + echo. + echo %BEGIN% + type "%GITATTR_SRC%" + echo %END% + ) + ) + ) else ( + > "!TMP_FILE!" ( + echo %BEGIN% + type "%GITATTR_SRC%" + echo %END% + ) + ) + + copy /y "!TMP_FILE!" "%GITATTR_DST%" >nul + del /q "!TMP_FILE!" >nul 2>nul + echo Updated .gitattributes from standards ^(managed block^). +) + +:AfterGitAttr +echo Done. +endlocal diff --git a/scripts/sync_standards.ps1 b/scripts/sync_standards.ps1 new file mode 100644 index 0000000..3c5c8c3 --- /dev/null +++ b/scripts/sync_standards.ps1 @@ -0,0 +1,179 @@ +# Sync standards snapshot to project root. +# - Copies /.agents/ -> /.agents/ +# - Updates /.gitattributes (managed block by default) +# Existing targets are backed up before overwrite. +[CmdletBinding()] +param( + # Sync multiple rulesets in one run: + # -Langs tsl,cpp + # -Langs @("tsl","cpp") + [Parameter(Mandatory = $false)] + [string[]]$Langs +) + +$ErrorActionPreference = "Stop" +$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path +$Src = (Resolve-Path (Join-Path $ScriptDir "..")).Path + +$Root = (git -C $ScriptDir rev-parse --show-toplevel 2>$null) +if (-not $Root) { $Root = (Get-Location).Path } +$Root = (Resolve-Path $Root).Path + +$AgentsSrcRoot = Join-Path $Src ".agents" +$GitAttrSrc = Join-Path $Src ".gitattributes" + +if (-not (Test-Path $AgentsSrcRoot)) { + throw "Standards snapshot not found at $AgentsSrcRoot. Run: git subtree add --prefix docs/standards/playbook --squash" +} + +$timestamp = Get-Date -Format "yyyyMMddHHmmss" + +# Multi rulesets: only on the outer invocation. +if (-not $env:SYNC_STANDARDS_INNER -and $Langs -and $Langs.Count -gt 0) { + $oldInner = $env:SYNC_STANDARDS_INNER + $oldAgentsNs = $env:AGENTS_NS + $oldMode = $env:SYNC_GITATTR_MODE + + $syncModeFirst = $env:SYNC_GITATTR_MODE + if (-not $syncModeFirst) { $syncModeFirst = "block" } + + $first = $true + foreach ($ns in $Langs) { + if (-not $ns) { continue } + + $env:SYNC_STANDARDS_INNER = "1" + $env:AGENTS_NS = $ns + if ($first) { + $first = $false + $env:SYNC_GITATTR_MODE = $syncModeFirst + } else { + $env:SYNC_GITATTR_MODE = "skip" + } + + & $MyInvocation.MyCommand.Path + } + + $env:SYNC_STANDARDS_INNER = $oldInner + $env:AGENTS_NS = $oldAgentsNs + $env:SYNC_GITATTR_MODE = $oldMode + exit 0 +} + +$AgentsNs = $env:AGENTS_NS +if (-not $AgentsNs) { $AgentsNs = "tsl" } +if ($AgentsNs -match '[\\/]' -or $AgentsNs -match '\.\.') { + throw "Invalid AGENTS_NS=$AgentsNs" +} +$AgentsSrc = Join-Path $AgentsSrcRoot $AgentsNs +if (-not (Test-Path $AgentsSrc)) { + # Backward-compatible fallback: older snapshots used /.agents/* directly. + if ((Test-Path (Join-Path $AgentsSrcRoot "index.md")) -and (Test-Path (Join-Path $AgentsSrcRoot "auth.md"))) { + $AgentsSrc = $AgentsSrcRoot + } else { + throw "Agents ruleset not found: $AgentsSrc (set AGENTS_NS to one of the subdirs under $AgentsSrcRoot, e.g. tsl/cpp)." + } +} +$AgentsRoot = Join-Path $Root ".agents" +$AgentsDst = Join-Path $AgentsRoot $AgentsNs + +if ($Src -ieq $Root) { + Write-Host "Skip: snapshot root equals project root." + Write-Host "Done." + exit 0 +} + +New-Item -ItemType Directory -Path $AgentsRoot -Force | Out-Null + +if (Test-Path $AgentsDst) { + $bak = (Join-Path $AgentsRoot "$AgentsNs.bak.$timestamp") + Move-Item $AgentsDst $bak + Write-Host "Backed up existing $AgentsNs agents -> $(Split-Path -Leaf $bak)" +} + +New-Item -ItemType Directory -Path $AgentsDst -Force | Out-Null +Copy-Item (Join-Path $AgentsSrc "*") $AgentsDst -Recurse -Force +Write-Host "Synced .agents/$AgentsNs from standards." + +$AgentsIndex = Join-Path $AgentsRoot "index.md" +if (-not (Test-Path $AgentsIndex)) { +@' +# .agents（多语言） + +本目录用于存放仓库级/语言级的代理规则集。 + +建议约定： + +- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`） +- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules） +- `.agents/python/` 等：其他语言的规则集（按需增加） + +规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。 + +入口建议从： + +- `.agents/tsl/index.md`（TSL 规则集入口） +- `.agents/cpp/index.md`（C++ 规则集入口） +- `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`） +'@ | Set-Content -Path $AgentsIndex -Encoding UTF8 + Write-Host "Created .agents/index.md" +} + +$GitAttrDst = Join-Path $Root ".gitattributes" +if (Test-Path $GitAttrSrc) { + $mode = $env:SYNC_GITATTR_MODE + if (-not $mode) { $mode = "block" } + switch ($mode.ToLowerInvariant()) { + "skip" { + Write-Host "Skip: .gitattributes sync (SYNC_GITATTR_MODE=skip)." + break + } + "overwrite" { + if ($GitAttrSrc -ieq $GitAttrDst) { + Write-Host "Skip: .gitattributes source equals destination." + break + } + if (Test-Path $GitAttrDst) { + $bak = "$GitAttrDst.bak.$timestamp" + Move-Item $GitAttrDst $bak + Write-Host "Backed up existing .gitattributes -> $bak" + } + Copy-Item $GitAttrSrc $GitAttrDst -Force + Write-Host "Synced .gitattributes from standards (overwrite)." + break + } + "block" { + $begin = "# BEGIN playbook .gitattributes" + $end = "# END playbook .gitattributes" + $beginOld = "# BEGIN tsl-playbook .gitattributes" + $endOld = "# END tsl-playbook .gitattributes" + $src = Get-Content -Path $GitAttrSrc -Raw + $block = $begin + "`r`n" + $src.TrimEnd() + "`r`n" + $end + "`r`n" + + $dst = "" + if (Test-Path $GitAttrDst) { + $bak = "$GitAttrDst.bak.$timestamp" + Move-Item $GitAttrDst $bak + Write-Host "Backed up existing .gitattributes -> $bak" + $dst = Get-Content -Path $bak -Raw + } + + $pattern = "(?ms)^(" + [regex]::Escape($begin) + "|" + [regex]::Escape($beginOld) + ")\\R.*?^(" + [regex]::Escape($end) + "|" + [regex]::Escape($endOld) + ")\\R?" + if ($dst -and ($dst -match $pattern)) { + $new = [regex]::Replace($dst, $pattern, $block) + } elseif ($dst) { + $new = $dst.TrimEnd() + "`r`n`r`n" + $block + } else { + $new = $block + } + + $new | Set-Content -Path $GitAttrDst -Encoding UTF8 + Write-Host "Updated .gitattributes from standards (managed block)." + break + } + default { + throw "Invalid SYNC_GITATTR_MODE=$mode (use block|overwrite|skip)" + } + } +} + +Write-Host "Done." diff --git a/scripts/sync_standards.sh b/scripts/sync_standards.sh new file mode 100644 index 0000000..9a56e35 --- /dev/null +++ b/scripts/sync_standards.sh @@ -0,0 +1,200 @@ +#!/usr/bin/env sh +set -eu + +# Sync standards snapshot to project root. +# - Copies /.agents/ -> /.agents/ +# - Updates /.gitattributes (managed block by default) +# Existing targets are backed up before overwrite. +# +# Multi rulesets: +# sh .../sync_standards.sh tsl cpp +# sh .../sync_standards.sh --langs tsl,cpp +# Notes: +# - When syncing multiple rulesets, .gitattributes is synced only once (first ruleset). + +SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)" +SRC="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)" +ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)" +ROOT="$(CDPATH= cd -- "$ROOT" && pwd -P)" +AGENTS_SRC_ROOT="$SRC/.agents" +GITATTR_SRC="$SRC/.gitattributes" + +if [ ! -d "$AGENTS_SRC_ROOT" ]; then + echo "ERROR: Standards snapshot not found at $AGENTS_SRC_ROOT" >&2 + echo "Run: git subtree add --prefix docs/standards/playbook --squash" >&2 + exit 1 +fi + +timestamp="$(date +%Y%m%d%H%M%S 2>/dev/null || echo bak)" + +if [ "$SRC" = "$ROOT" ]; then + echo "Skip: snapshot root equals project root." + echo "Done." + exit 0 +fi + +# Parse multi rulesets only on the outer invocation. +if [ "${SYNC_STANDARDS_INNER:-}" != "1" ]; then + langs="" + if [ "${1:-}" = "--langs" ]; then + langs="${2:-}" + shift 2 + fi + if [ -z "${langs:-}" ] && [ "$#" -gt 0 ]; then + langs="$*" + fi + if [ -n "${langs:-}" ]; then + sync_mode_first="${SYNC_GITATTR_MODE:-block}" + + first=1 + old_ifs="${IFS}" + IFS=', ' + set -- $langs + IFS="${old_ifs}" + + for ns in "$@"; do + [ -n "$ns" ] || continue + if [ "$first" -eq 1 ]; then + first=0 + SYNC_STANDARDS_INNER=1 AGENTS_NS="$ns" SYNC_GITATTR_MODE="$sync_mode_first" sh "$0" + else + SYNC_STANDARDS_INNER=1 AGENTS_NS="$ns" SYNC_GITATTR_MODE=skip sh "$0" + fi + done + exit 0 + fi +fi + +: "${AGENTS_NS:=tsl}" +case "$AGENTS_NS" in + ""|*/*|*\\*|*..*) + echo "ERROR: invalid AGENTS_NS=$AGENTS_NS" >&2 + exit 1 + ;; +esac + +AGENTS_SRC="$AGENTS_SRC_ROOT/$AGENTS_NS" +if [ ! -d "$AGENTS_SRC" ]; then + # Backward-compatible fallback: older snapshots used /.agents/* directly. + if [ -f "$AGENTS_SRC_ROOT/index.md" ] && [ -f "$AGENTS_SRC_ROOT/auth.md" ]; then + AGENTS_SRC="$AGENTS_SRC_ROOT" + else + echo "ERROR: agents ruleset not found: $AGENTS_SRC" >&2 + echo "Hint: set AGENTS_NS to one of the subdirs under $AGENTS_SRC_ROOT (e.g. tsl/cpp)." >&2 + exit 1 + fi +fi + +AGENTS_ROOT="$ROOT/.agents" +AGENTS_DST="$AGENTS_ROOT/$AGENTS_NS" +mkdir -p "$AGENTS_ROOT" + +if [ -e "$AGENTS_DST" ]; then + mv "$AGENTS_DST" "$AGENTS_ROOT/$AGENTS_NS.bak.$timestamp" + echo "Backed up existing $AGENTS_NS agents -> $AGENTS_NS.bak.$timestamp" +fi + +cp -R "$AGENTS_SRC" "$AGENTS_DST" +echo "Synced .agents/$AGENTS_NS from standards." + +AGENTS_INDEX="$AGENTS_ROOT/index.md" +if [ ! -f "$AGENTS_INDEX" ]; then + cat >"$AGENTS_INDEX" <<'EOF' +# .agents（多语言） + +本目录用于存放仓库级/语言级的代理规则集。 + +建议约定： + +- `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`） +- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules） +- `.agents/python/` 等：其他语言的规则集（按需增加） + +规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。 + +入口建议从： + +- `.agents/tsl/index.md`（TSL 规则集入口） +- `.agents/cpp/index.md`（C++ 规则集入口） +- `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`） +EOF + echo "Created .agents/index.md" +fi + +echo "Synced agents ruleset to $AGENTS_DST." + +GITATTR_DST="$ROOT/.gitattributes" +if [ -f "$GITATTR_SRC" ]; then + : "${SYNC_GITATTR_MODE:=block}" + case "$SYNC_GITATTR_MODE" in + skip) + echo "Skip: .gitattributes sync (SYNC_GITATTR_MODE=skip)." + ;; + overwrite) + if [ "$(CDPATH= cd -- "$(dirname -- "$GITATTR_SRC")" && pwd -P)/$(basename -- "$GITATTR_SRC")" = "$GITATTR_DST" ]; then + echo "Skip: .gitattributes source equals destination." + else + if [ -e "$GITATTR_DST" ]; then + mv "$GITATTR_DST" "$ROOT/.gitattributes.bak.$timestamp" + echo "Backed up existing .gitattributes -> .gitattributes.bak.$timestamp" + fi + cp "$GITATTR_SRC" "$GITATTR_DST" + echo "Synced .gitattributes from standards (overwrite)." + fi + ;; + block) + begin="# BEGIN playbook .gitattributes" + end="# END playbook .gitattributes" + begin_old="# BEGIN tsl-playbook .gitattributes" + end_old="# END tsl-playbook .gitattributes" + + if [ -e "$GITATTR_DST" ]; then + mv "$GITATTR_DST" "$ROOT/.gitattributes.bak.$timestamp" + echo "Backed up existing .gitattributes -> .gitattributes.bak.$timestamp" + fi + + tmp="${GITATTR_DST}.tmp.${timestamp}" + if [ -f "$ROOT/.gitattributes.bak.$timestamp" ]; then + src_dst="$ROOT/.gitattributes.bak.$timestamp" + else + src_dst="" + fi + + if [ -n "$src_dst" ]; then + awk -v begin="$begin" -v end="$end" -v begin_old="$begin_old" -v end_old="$end_old" -v src="$GITATTR_SRC" ' + function emit_src() { + print begin + while ((getline line < src) > 0) print line + close(src) + print end + } + BEGIN { in_block=0; done=0 } + $0 == begin || $0 == begin_old { in_block=1; if (!done) { emit_src(); done=1 } ; next } + $0 == end || $0 == end_old { in_block=0; next } + !in_block { print } + END { + if (!done) { + if (NR > 0) print "" + emit_src() + } + } + ' "$src_dst" >"$tmp" + else + { + printf "%s\n" "$begin" + cat "$GITATTR_SRC" + printf "\n%s\n" "$end" + } >"$tmp" + fi + + mv "$tmp" "$GITATTR_DST" + echo "Updated .gitattributes from standards (managed block)." + ;; + *) + echo "ERROR: invalid SYNC_GITATTR_MODE=$SYNC_GITATTR_MODE (use block|overwrite|skip)" >&2 + exit 1 + ;; + esac +fi + +echo "Done." diff --git a/templates/cpp/.clang-format b/templates/cpp/.clang-format new file mode 100644 index 0000000..6f94096 --- /dev/null +++ b/templates/cpp/.clang-format @@ -0,0 +1,47 @@ +--- +Language: Cpp +BasedOnStyle: Google + +# Keep consistent with the repo-wide 100 char guidance (adjust per-project if needed). +ColumnLimit: 100 + +AccessModifierOffset: -4 +AlignEscapedNewlines: Left +AlignTrailingComments: false +AllowAllParametersOfDeclarationOnNextLine: false +AllowShortFunctionsOnASingleLine: All +AlwaysBreakTemplateDeclarations: Yes +BinPackArguments: false +BinPackParameters: false +BraceWrapping: + AfterCaseLabel: true + AfterUnion: true + AfterExternBlock: false +BreakBeforeTernaryOperators: false +BreakConstructorInitializers: AfterColon +BreakInheritanceList: AfterColon +CommentPragmas: "suppress" +ConstructorInitializerAllOnOneLineOrOnePerLine: true +Cpp11BracedListStyle: false +FixNamespaceComments: false +IncludeBlocks: Regroup +IncludeCategories: + - Regex: '^.*(precomp|pch|stdafx)' + Priority: -1 + - Regex: '^".*"' + Priority: 1 + - Regex: '^<.*>' + Priority: 2 + - Regex: '.*' + Priority: 3 +KeepEmptyLinesAtTheStartOfBlocks: false +MacroBlockBegin: "BEGIN_TEST_METHOD_PROPERTIES|BEGIN_MODULE|BEGIN_TEST_CLASS|BEGIN_TEST_METHOD" +MacroBlockEnd: "END_TEST_METHOD_PROPERTIES|END_MODULE|END_TEST_CLASS|END_TEST_METHOD" +NamespaceIndentation: All +PointerAlignment: Left +ReflowComments: false +SortIncludes: false +SpaceAfterTemplateKeyword: false +SpacesInAngles: false +SpacesInContainerLiterals: false + diff --git a/templates/cpp/.clangd b/templates/cpp/.clangd new file mode 100644 index 0000000..be8b66f --- /dev/null +++ b/templates/cpp/.clangd @@ -0,0 +1,25 @@ +CompileFlags: + # Point clangd to a CMake compilation database (compile_commands.json). + # + # Recommended: keep this aligned with your Conan/CMake preset output directory. + # Example (this playbook's default cross build folder): + CompilationDatabase: build/windows-x86_64-clang-cross/Release + +--- +If: + PathMatch: [.*\\.hpp, .*\\.hxx, .*\\.cpp, .*\\.cc, .*\\.cxx, .*\\.cppm, .*\\.ixx, .*\\.mpp] + +CompileFlags: + Add: + - "-std=c++23" + Compiler: clang++ + +--- +If: + PathMatch: [.*\\.h, .*\\.c] + +CompileFlags: + Add: + - "-std=c17" + Compiler: clang + diff --git a/templates/cpp/CMakeLists.txt b/templates/cpp/CMakeLists.txt new file mode 100644 index 0000000..3aeb578 --- /dev/null +++ b/templates/cpp/CMakeLists.txt @@ -0,0 +1,26 @@ +cmake_minimum_required(VERSION 4.2) + +# Enable C++23 Modules + (optional) `import std;` with experimental std module. +set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "d0edc3af-4c50-42ea-a356-e2862fe7a444") + +project(app LANGUAGES C CXX) + +set(CMAKE_CXX_SCAN_FOR_MODULES ON) +set(CMAKE_CXX_EXTENSIONS OFF) +set(CMAKE_CXX_STANDARD 23) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_CXX_MODULE_STD 1) +set(CMAKE_EXPORT_COMPILE_COMMANDS ON) + +# Toolchain-specific flags (libc++/runtime/linker/etc) should come from your Conan toolchain/profile. + +# Example: entrypoint built from main.cc; modules live in .cppm files. +add_executable(app main.cc) + +# If you use C++ Modules, list module interface units explicitly and keep this in sync: +# +# target_sources(app +# PRIVATE +# FILE_SET cxx_modules TYPE CXX_MODULES FILES +# modules/app.cppm +# ) diff --git a/templates/cpp/CMakeUserPresets.json b/templates/cpp/CMakeUserPresets.json new file mode 100644 index 0000000..e3b2c2a --- /dev/null +++ b/templates/cpp/CMakeUserPresets.json @@ -0,0 +1,9 @@ +{ + "version": 4, + "vendor": { + "conan": {} + }, + "include": [ + "build/windows-x86_64-clang-cross/Release/generators/CMakePresets.json" + ] +} diff --git a/templates/cpp/conan/profiles/linux-x86_64-clang b/templates/cpp/conan/profiles/linux-x86_64-clang new file mode 100644 index 0000000..43901b8 --- /dev/null +++ b/templates/cpp/conan/profiles/linux-x86_64-clang @@ -0,0 +1,24 @@ +# Linux (Clang) +# +# Profile naming convention (suggested): +# linux--clang +# If the repo only supports one clang version, you may omit the suffix. + +[settings] +os=Linux +arch=x86_64 +compiler=clang +compiler.version=20 +compiler.libcxx=libc++ +compiler.cppstd=23 +build_type=Release + +[conf] +# Prefer pinning the exact compiler executables to avoid PATH drift. +tools.build:compiler_executables={"c": "/usr/bin/clang", "cpp": "/usr/bin/clang++"} +tools.cmake.cmaketoolchain:generator=Ninja + +# Keep Conan's cmake_layout output stable and predictable. +tools.cmake.cmake_layout:build_folder=. +tools.cmake.cmake_layout:build_folder_vars=[] + diff --git a/templates/cpp/conan/profiles/windows-x86_64-clang-cross b/templates/cpp/conan/profiles/windows-x86_64-clang-cross new file mode 100644 index 0000000..b1058ff --- /dev/null +++ b/templates/cpp/conan/profiles/windows-x86_64-clang-cross @@ -0,0 +1,38 @@ +# Windows target cross (Clang) from Linux host +# +# IMPORTANT: +# - This profile describes the *output platform* (target), so [settings] os=Windows. +# - Use a "windows-..." prefix to avoid misleading readers into thinking the output is Linux. +# +# Profile naming convention (suggested): +# windows--clang-cross + +[settings] +os=Windows +arch=x86_64 +compiler=clang +compiler.version=20 +compiler.runtime=static +compiler.libcxx=libc++ +compiler.cppstd=23 +build_type=Release + +[conf] +# Configure your cross clang executables here (do NOT hardcode a specific distro name in docs). +tools.build:compiler_executables={"c": "/bin/x86_64-w64-mingw32-clang", "cpp": "/bin/x86_64-w64-mingw32-clang++"} + +# Tell Conan/CMake the target triple and platform. +tools.gnu:host_triplet=x86_64-w64-mingw32 +tools.cmake.cmaketoolchain:generator=Ninja +tools.cmake.cmaketoolchain:system_name=Windows +tools.cmake.cmaketoolchain:system_processor=x86_64 +tools.cmake.cmaketoolchain:system_version=11 + +# Keep Conan's cmake_layout output stable and predictable. +tools.cmake.cmake_layout:build_folder=. +tools.cmake.cmake_layout:build_folder_vars=[] + +[buildenv] +# Resource compiler (optional; adjust if your toolchain uses a different windres name/path). +RC=x86_64-w64-mingw32-windres + diff --git a/templates/cpp/conanfile.txt b/templates/cpp/conanfile.txt new file mode 100644 index 0000000..bc8190e --- /dev/null +++ b/templates/cpp/conanfile.txt @@ -0,0 +1,25 @@ +[requires] +# 本仓库是“模板/标准”仓库：默认不内置任何依赖版本。 +# 在具体项目中按需添加，并由项目自行锁版本（建议配合 lockfile / 版本策略）。 +# +# 示例（请按项目实际替换/增删）： +# fmt/12.0.0 +# spdlog/1.16.0 + +[generators] +CMakeDeps +CMakeToolchain + +[options] +# 示例（请按项目实际替换/增删）： +# spdlog/*:header_only=True +# fmt/*:header_only=True + +[layout] +cmake_layout + +# 参考命令（按项目 profile/路径调整）： +# 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 +# ctest --preset conan-release --output-on-failure diff --git a/templates/python/.editorconfig b/templates/python/.editorconfig new file mode 100644 index 0000000..52910a3 --- /dev/null +++ b/templates/python/.editorconfig @@ -0,0 +1,26 @@ +# EditorConfig is awesome: https://EditorConfig.org +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.py] +indent_style = space +indent_size = 4 +max_line_length = 80 + +[*.md] +max_line_length = off +trim_trailing_whitespace = false + +[*.{yml,yaml}] +indent_style = space +indent_size = 2 + +[*.json] +indent_style = space +indent_size = 2 + diff --git a/templates/python/.flake8 b/templates/python/.flake8 new file mode 100644 index 0000000..88b1ced --- /dev/null +++ b/templates/python/.flake8 @@ -0,0 +1,27 @@ +[flake8] +# 最大行长度（Google Style Guide 推荐 80） +max-line-length = 80 + +# 忽略的错误代码（与 black 等工具对齐） +ignore = + E203, # whitespace before ':' (与 black 冲突) + W503, # line break before binary operator (已过时的规则) + +exclude = + .git, + __pycache__, + .venv, + venv, + build, + dist, + *.egg-info, + .tox, + .pytest_cache + +max-complexity = 10 +show-source = True +show-pep8 = True +count = True + +docstring-convention = google + diff --git a/templates/python/.pre-commit-config.yaml b/templates/python/.pre-commit-config.yaml new file mode 100644 index 0000000..ac7b844 --- /dev/null +++ b/templates/python/.pre-commit-config.yaml @@ -0,0 +1,25 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.6.0 + hooks: + - id: end-of-file-fixer + - id: trailing-whitespace + - id: check-yaml + - id: check-toml + + - repo: https://github.com/psf/black + rev: 23.3.0 + hooks: + - id: black + args: ["--line-length", "80"] + + - repo: https://github.com/PyCQA/isort + rev: 5.12.0 + hooks: + - id: isort + + - repo: https://github.com/PyCQA/flake8 + rev: 6.0.0 + hooks: + - id: flake8 + diff --git a/templates/python/.pylintrc b/templates/python/.pylintrc new file mode 100644 index 0000000..d186d47 --- /dev/null +++ b/templates/python/.pylintrc @@ -0,0 +1,64 @@ +[MASTER] +jobs=0 +ignore=CVS,.git,__pycache__,.venv,venv +init-hook='import sys; sys.path.append(".")' + +[MESSAGES CONTROL] +disable= + C0103, # 变量名不符合命名规范（允许简短的变量名） + C0114, # 缺少模块文档字符串 + R0913, # 参数过多 + R0902, # 实例属性过多 + W0511, # TODO 注释 + +enable= + E, + W, + +[REPORTS] +output-format=colorized +reports=no + +[BASIC] +argument-naming-style=snake_case +attr-naming-style=snake_case +class-attribute-naming-style=any +class-naming-style=PascalCase +const-naming-style=UPPER_CASE +function-naming-style=snake_case +method-naming-style=snake_case +module-naming-style=snake_case +variable-naming-style=snake_case + +good-names=i,j,k,ex,Run,_,x,y,z,fd,id +docstring-min-length=5 + +[FORMAT] +max-line-length=80 +max-module-lines=1000 +indent-string=' ' +indent-after-paren=4 + +[DESIGN] +max-args=7 +max-attributes=10 +max-branches=15 +max-locals=20 +max-returns=6 +max-statements=50 +min-public-methods=1 + +[IMPORTS] +import-graph= +ext-import-graph= +int-import-graph= + +[CLASSES] +valid-metaclass-classmethod-first-arg=cls +valid-classmethod-first-arg=cls + +[EXCEPTIONS] +overgeneral-exceptions= + builtins.BaseException, + builtins.Exception + diff --git a/templates/python/.vscode/settings.json b/templates/python/.vscode/settings.json new file mode 100644 index 0000000..40df514 --- /dev/null +++ b/templates/python/.vscode/settings.json @@ -0,0 +1,14 @@ +{ + "editor.formatOnSave": true, + "editor.rulers": [80], + "[python]": { + "editor.defaultFormatter": "ms-python.black-formatter", + "editor.codeActionsOnSave": { + "source.organizeImports": "explicit" + } + }, + "python.analysis.typeCheckingMode": "basic", + "python.analysis.autoImportCompletions": true, + "python.formatting.provider": "none" +} + diff --git a/templates/python/pyproject.toml b/templates/python/pyproject.toml new file mode 100644 index 0000000..fbe032d --- /dev/null +++ b/templates/python/pyproject.toml @@ -0,0 +1,51 @@ +[tool.black] +# Black 代码格式化工具配置（模板） +line-length = 80 +target-version = ["py313"] +exclude = ''' +/( + \.git + | \.venv + | venv + | build + | dist + | __pycache__ + | \.egg-info +)/ +''' + +[tool.isort] +# isort 导入排序工具配置（模板） +profile = "google" +line_length = 80 +multi_line_output = 3 +lines_after_imports = 2 + +# 按项目需要填写/维护： +known_third_party = [] +known_first_party = [] + +skip = [".venv", "venv", "build", "dist"] + +[tool.mypy] +# MyPy 类型检查配置（可选，模板） +python_version = "3.13" +warn_unused_ignores = true +warn_redundant_casts = true +warn_return_any = true +disallow_untyped_defs = false +disallow_untyped_calls = false +ignore_missing_imports = true + +[tool.pytest.ini_options] +# pytest 测试配置（模板） +testpaths = ["tests"] +python_files = ["test_*.py", "*_test.py"] +python_classes = ["Test*"] +python_functions = ["test_*"] +addopts = "-v --tb=short --strict-markers" +markers = [ + "slow: marks tests as slow", + "integration: marks tests as integration tests", +] +