📦 deps(standards): vendor playbook
This commit is contained in:
commit
dbdde4ed48
|
|
@ -0,0 +1,33 @@
|
||||||
|
# 安全与鉴权（Auth）
|
||||||
|
|
||||||
|
本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。
|
||||||
|
|
||||||
|
## 1. 基本原则
|
||||||
|
|
||||||
|
- **最小权限**：只使用完成任务所需的最低权限与最少数据。
|
||||||
|
- **默认保守**：不确定是否敏感时按敏感处理。
|
||||||
|
- **不扩散秘密**：任何 secret 只在必要范围内出现。
|
||||||
|
|
||||||
|
## 2. 凭证与敏感信息
|
||||||
|
|
||||||
|
- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。
|
||||||
|
- 如需示例，使用占位符：`<TOKEN>`、`<PASSWORD>`。
|
||||||
|
- 避免把敏感信息打印到标准输出或错误日志。
|
||||||
|
|
||||||
|
## 3. 鉴权逻辑修改
|
||||||
|
|
||||||
|
- 修改鉴权/权限控制时必须说明：
|
||||||
|
- 变更动机
|
||||||
|
- 风险评估
|
||||||
|
- 兼容性/回滚方案
|
||||||
|
- 默认保持旧行为兼容，除非明确要求破坏性变更。
|
||||||
|
|
||||||
|
## 4. 依赖与第三方
|
||||||
|
|
||||||
|
- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。
|
||||||
|
- 若必须新增，需在 PR 说明理由、替代方案与安全影响。
|
||||||
|
|
||||||
|
## 5. 审计与合规
|
||||||
|
|
||||||
|
- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。
|
||||||
|
- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。
|
||||||
|
|
@ -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 清单
|
||||||
|
|
||||||
|
- 是否有无关改动？
|
||||||
|
- 是否保持模块内风格一致？
|
||||||
|
- 是否引入不必要的复杂度/依赖？
|
||||||
|
- 是否有最小验证（构建/冒烟）步骤？
|
||||||
|
|
@ -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`
|
||||||
|
|
@ -0,0 +1,31 @@
|
||||||
|
# 性能（Performance）
|
||||||
|
|
||||||
|
本文件定义代理在做性能相关改动时的准则与检查项。
|
||||||
|
|
||||||
|
## 1. 目标与度量
|
||||||
|
|
||||||
|
- 明确性能目标：延迟、吞吐、内存、CPU、I/O 等。
|
||||||
|
- 没有指标时不要盲目优化；先补充测量或基准。
|
||||||
|
|
||||||
|
## 2. 处理流程
|
||||||
|
|
||||||
|
1. 先定位瓶颈（profile/trace/log）。
|
||||||
|
2. 再提出最小化改动方案。
|
||||||
|
3. 最后用数据验证收益与副作用。
|
||||||
|
|
||||||
|
## 3. 优化准则
|
||||||
|
|
||||||
|
- 优先消除算法/结构性问题，再考虑微优化。
|
||||||
|
- 避免引入复杂度换取小收益。
|
||||||
|
- 性能优化不应牺牲可读性；必要时加注释说明权衡。
|
||||||
|
|
||||||
|
## 4. 常见风险
|
||||||
|
|
||||||
|
- 避免重复计算、无界缓存、隐式复制。
|
||||||
|
- 注意热路径中的分配与 I/O。
|
||||||
|
- 并发优化要考虑正确性与可测试性。
|
||||||
|
|
||||||
|
## 5. 验证
|
||||||
|
|
||||||
|
- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。
|
||||||
|
- 若无测试体系，至少提供最小可运行的复现脚本/步骤。
|
||||||
|
|
@ -0,0 +1,26 @@
|
||||||
|
# 测试（Testing）
|
||||||
|
|
||||||
|
本文件定义代理在改动代码时的测试策略与要求。
|
||||||
|
|
||||||
|
## 1. 测试层级
|
||||||
|
|
||||||
|
- **单元测试**：验证函数/模块的独立行为。
|
||||||
|
- **集成测试**：验证模块间交互与关键流程。
|
||||||
|
- **回归测试**：防止已修复问题复发。
|
||||||
|
|
||||||
|
## 2. 何时补测试
|
||||||
|
|
||||||
|
- 新功能必须新增对应测试（若项目有测试体系）。
|
||||||
|
- 修复 bug 必须先写/补回归用例（若项目有测试体系）。
|
||||||
|
- 仅当改动纯文档/注释/格式时可不加测试。
|
||||||
|
|
||||||
|
## 3. 测试可维护性
|
||||||
|
|
||||||
|
- 一个用例只验证一个行为点。
|
||||||
|
- 测试命名清晰，能从名字看出期望。
|
||||||
|
- 避免依赖外部不稳定资源；必要时 mock/stub。
|
||||||
|
|
||||||
|
## 4. 运行与失败处理
|
||||||
|
|
||||||
|
- 若项目提供构建/冒烟命令（CMake），优先保证最小构建可通过。
|
||||||
|
- 失败时优先定位改动相关原因，不修无关失败。
|
||||||
|
|
@ -0,0 +1,11 @@
|
||||||
|
# .agents（多语言规则集快照）
|
||||||
|
|
||||||
|
本目录用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**。
|
||||||
|
|
||||||
|
本仓库将规则按语言拆分为多个规则集快照：
|
||||||
|
|
||||||
|
- `.agents/tsl/`：TSL 相关规则集（适用于 `.tsl`/`.tsf`）
|
||||||
|
- `.agents/cpp/`：C++ 相关规则集（C++23，含 Modules）
|
||||||
|
- `.agents/python/`：Python 相关规则集
|
||||||
|
|
||||||
|
目标项目落地时，通常通过 `scripts/sync_standards.*` 将某个规则集同步到目标项目根目录的 `.agents/<lang>/`。
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# 安全与鉴权（Auth & Security）
|
||||||
|
|
||||||
|
本文件定义代理在涉及鉴权/密钥/权限时必须遵守的最低要求（Python）。
|
||||||
|
|
||||||
|
## 基本原则
|
||||||
|
|
||||||
|
- 默认最小权限：避免使用全局管理员/Root 权限完成可在用户权限完成的事。
|
||||||
|
- 不要提交任何密钥材料：token、私钥、证书、访问密钥、`.env` 中的真实值等。
|
||||||
|
- 任何涉及加密/鉴权的实现变更必须说明威胁模型与兼容性影响。
|
||||||
|
|
||||||
|
## 常见风险与要求
|
||||||
|
|
||||||
|
- 输入校验：对外部输入（CLI 参数、环境变量、文件、网络数据）要做类型/范围校验，避免命令注入、路径穿越等问题。
|
||||||
|
- 依赖安全：避免新增“来源不明”的依赖；如必须新增，需说明来源与版本锁定策略。
|
||||||
|
- 日志脱敏：日志中不得输出凭据、个人敏感信息（PII）或可重放的签名/URL。
|
||||||
|
|
@ -0,0 +1,27 @@
|
||||||
|
# 代码质量（Code Quality）
|
||||||
|
|
||||||
|
本文件定义代理对代码质量的最低要求与审查清单（Python）。
|
||||||
|
|
||||||
|
## 1. 总体要求
|
||||||
|
|
||||||
|
- 改动聚焦目标；避免“顺手重构”。
|
||||||
|
- API/行为变更要显式说明影响与迁移方式（尤其是脚本/CLI 输出与配置项）。
|
||||||
|
- 保持仓库现有约定：优先复用既有结构、命名与工具配置（见 `docs/python/`）。
|
||||||
|
|
||||||
|
## 2. 可读性
|
||||||
|
|
||||||
|
- 复杂逻辑拆分为具名函数/模块；避免超长函数。
|
||||||
|
- 尽量使用显式类型与数据结构表达意图（必要时补类型标注）。
|
||||||
|
- 注释解释“为什么”，避免注释重复代码表述。
|
||||||
|
|
||||||
|
## 3. 错误处理
|
||||||
|
|
||||||
|
- 失败必须可观测：返回码/异常/日志至少一种要明确。
|
||||||
|
- CLI/自动化脚本：遇到不可恢复错误应非零退出码。
|
||||||
|
|
||||||
|
## 4. Review 清单
|
||||||
|
|
||||||
|
- 是否引入了不必要的新依赖？
|
||||||
|
- 是否遵循 `pyproject.toml` 与 lint 配置？
|
||||||
|
- 是否对 I/O（文件/网络/数据库）失败路径做了处理？
|
||||||
|
- 是否需要补测试或示例？
|
||||||
|
|
@ -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`
|
||||||
|
|
@ -0,0 +1,15 @@
|
||||||
|
# 性能（Performance）
|
||||||
|
|
||||||
|
本文件定义代理在性能相关改动时的最低要求（Python）。
|
||||||
|
|
||||||
|
## 基本原则
|
||||||
|
|
||||||
|
- 先保证正确性与可读性，再做优化。
|
||||||
|
- 优化前先定位瓶颈：避免盲目微优化。
|
||||||
|
- 对可能影响性能的改动，说明复杂度变化与典型数据规模假设。
|
||||||
|
|
||||||
|
## 常见注意点
|
||||||
|
|
||||||
|
- 避免在热路径重复 I/O（文件读写、网络请求、重复解析）。
|
||||||
|
- 对大列表/大文件处理优先采用流式处理与生成器。
|
||||||
|
- 警惕 `O(n^2)` 循环、重复正则编译、重复 JSON/YAML 解析等。
|
||||||
|
|
@ -0,0 +1,13 @@
|
||||||
|
# 测试（Testing）
|
||||||
|
|
||||||
|
本文件定义代理在测试相关工作的最低要求（Python）。
|
||||||
|
|
||||||
|
## 原则
|
||||||
|
|
||||||
|
- 优先增加与变更直接相关的测试（回归测试优先）。
|
||||||
|
- 测试应可重复运行、无顺序依赖、尽量避免真实网络/真实环境依赖。
|
||||||
|
|
||||||
|
## 约定（模板）
|
||||||
|
|
||||||
|
- 若项目使用 `pytest`：遵循 `pyproject.toml` 中的 `pytest.ini_options` 配置。
|
||||||
|
- I/O 相关代码建议使用临时目录与 mock，避免污染工作区。
|
||||||
|
|
@ -0,0 +1,33 @@
|
||||||
|
# 安全与鉴权（Auth）
|
||||||
|
|
||||||
|
本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。
|
||||||
|
|
||||||
|
## 1. 基本原则
|
||||||
|
|
||||||
|
- **最小权限**：只使用完成任务所需的最低权限与最少数据。
|
||||||
|
- **默认保守**：不确定是否敏感时按敏感处理。
|
||||||
|
- **不扩散秘密**：任何 secret 只在必要范围内出现。
|
||||||
|
|
||||||
|
## 2. 凭证与敏感信息
|
||||||
|
|
||||||
|
- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。
|
||||||
|
- 如需示例，使用占位符：`<TOKEN>`、`<PASSWORD>`。
|
||||||
|
- 避免把敏感信息打印到标准输出或错误日志。
|
||||||
|
|
||||||
|
## 3. 鉴权逻辑修改
|
||||||
|
|
||||||
|
- 修改鉴权/权限控制时必须说明：
|
||||||
|
- 变更动机
|
||||||
|
- 风险评估
|
||||||
|
- 兼容性/回滚方案
|
||||||
|
- 默认保持旧行为兼容，除非明确要求破坏性变更。
|
||||||
|
|
||||||
|
## 4. 依赖与第三方
|
||||||
|
|
||||||
|
- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。
|
||||||
|
- 若必须新增，需在 PR 说明理由、替代方案与安全影响。
|
||||||
|
|
||||||
|
## 5. 审计与合规
|
||||||
|
|
||||||
|
- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。
|
||||||
|
- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。
|
||||||
|
|
@ -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 清单
|
||||||
|
|
||||||
|
- 是否有无关改动？
|
||||||
|
- 是否有清晰的动机与行为说明？
|
||||||
|
- 是否保持模块内风格一致？
|
||||||
|
- 是否需要补测试/示例？
|
||||||
|
|
@ -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`
|
||||||
|
|
@ -0,0 +1,31 @@
|
||||||
|
# 性能（Performance）
|
||||||
|
|
||||||
|
本文件定义代理在做性能相关改动时的准则与检查项。
|
||||||
|
|
||||||
|
## 1. 目标与度量
|
||||||
|
|
||||||
|
- 明确性能目标：延迟、吞吐、内存、CPU、I/O 等。
|
||||||
|
- 没有指标时不要盲目优化；先补充测量或基准。
|
||||||
|
|
||||||
|
## 2. 处理流程
|
||||||
|
|
||||||
|
1. 先定位瓶颈（profile/trace/log）。
|
||||||
|
2. 再提出最小化改动方案。
|
||||||
|
3. 最后用数据验证收益与副作用。
|
||||||
|
|
||||||
|
## 3. 优化准则
|
||||||
|
|
||||||
|
- 优先消除算法/结构性问题，再考虑微优化。
|
||||||
|
- 避免引入复杂度换取小收益。
|
||||||
|
- 性能优化不应牺牲可读性；必要时加注释说明权衡。
|
||||||
|
|
||||||
|
## 4. 常见风险
|
||||||
|
|
||||||
|
- 避免重复计算、无界缓存、隐式复制。
|
||||||
|
- 注意热路径中的分配与 I/O。
|
||||||
|
- 并发优化要考虑正确性与可测试性。
|
||||||
|
|
||||||
|
## 5. 验证
|
||||||
|
|
||||||
|
- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。
|
||||||
|
- 若无测试体系，至少提供最小可运行的复现脚本/步骤。
|
||||||
|
|
@ -0,0 +1,26 @@
|
||||||
|
# 测试（Testing）
|
||||||
|
|
||||||
|
本文件定义代理在改动代码时的测试策略与要求。
|
||||||
|
|
||||||
|
## 1. 测试层级
|
||||||
|
|
||||||
|
- **单元测试**：验证函数/模块的独立行为。
|
||||||
|
- **集成测试**：验证模块间交互与关键流程。
|
||||||
|
- **回归测试**：防止已修复问题复发。
|
||||||
|
|
||||||
|
## 2. 何时补测试
|
||||||
|
|
||||||
|
- 新功能必须新增对应测试。
|
||||||
|
- 修复 bug 必须先写/补回归用例。
|
||||||
|
- 仅当改动纯文档/注释/格式时可不加测试。
|
||||||
|
|
||||||
|
## 3. 测试可维护性
|
||||||
|
|
||||||
|
- 一个用例只验证一个行为点。
|
||||||
|
- 测试命名清晰，能从名字看出期望。
|
||||||
|
- 避免依赖外部不稳定资源；必要时 mock/stub。
|
||||||
|
|
||||||
|
## 4. 运行与失败处理
|
||||||
|
|
||||||
|
- 本仓库未来若引入测试命令，需在此补充统一的运行方式。
|
||||||
|
- 测试失败时优先定位改动相关原因，不修无关失败。
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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~
|
||||||
|
|
||||||
|
|
@ -0,0 +1,7 @@
|
||||||
|
# Contributing
|
||||||
|
|
||||||
|
## Commit messages
|
||||||
|
|
||||||
|
Follow the repository commit message standard:
|
||||||
|
|
||||||
|
- `docs/common/commit_message.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/<lang>/`、更新 `.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/<lang>/` 与 `.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_NS>/`（默认 `.agents/tsl/`）
|
||||||
|
- 更新 `.gitattributes`：默认只维护 `# BEGIN playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制）
|
||||||
|
- 缺省创建：`.agents/index.md`
|
||||||
|
- 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀）
|
||||||
|
- 不修改：`.gitignore`（项目自行维护）
|
||||||
|
|
||||||
|
#### 环境变量（可选）
|
||||||
|
|
||||||
|
同步脚本支持以下可选环境变量（默认值可满足大多数项目）：
|
||||||
|
|
||||||
|
| 变量名 | 默认值 | 说明 |
|
||||||
|
| ------------------- | ------- | ------------------------------------------------------------------------------------------- |
|
||||||
|
| `AGENTS_NS` | `tsl` | 同步的规则集名/落地目录名：`.agents/<AGENTS_NS>/`（例如 `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/<lang>/`，不要互相覆盖。
|
||||||
|
- 若某个子目录需要更具体规则（模块/子系统差异），在更靠近代码的目录放置更具体规则（例如 `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/<lang>/`）。
|
||||||
|
- 代理规则：
|
||||||
|
- C++：运行 `sh docs/standards/playbook/scripts/sync_standards.sh cpp`（或 `& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs cpp`），落地到 `.agents/cpp/`（与 `.agents/tsl/` 并行）。
|
||||||
|
- 其他语言：在目标项目增加 `.agents/<lang>/`（与 `.agents/tsl/` 并行），只写该语言专属要求与工具链约束。
|
||||||
|
- 同步策略：每个规则集只同步到对应子目录（例如 `.agents/cpp/`），避免覆盖整个 `.agents/`。
|
||||||
|
- CI/工具：按文件类型分别执行格式化、lint、测试（不要让 TSL 规则去约束 C++ 代码，反之亦然）。
|
||||||
|
- C++ 补全：建议在项目根目录提供 `.clangd` 并指向正确的 `CompilationDatabase`（模板见 `templates/cpp/.clangd`）。
|
||||||
|
|
||||||
|
## 版本与贡献
|
||||||
|
|
||||||
|
- 本项目会持续迭代；变更以 PR 形式提交。
|
||||||
|
- 新规则需包含动机、示例、迁移建议（如有）。
|
||||||
|
|
@ -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
|
||||||
|
```
|
||||||
|
|
@ -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 补全/跳转不稳定。
|
||||||
|
|
@ -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/平台差异）。
|
||||||
|
- 对路径、换行、编码、大小写敏感等行为要明确约束并在文档/测试中覆盖。
|
||||||
|
|
@ -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`
|
||||||
|
|
@ -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 名可映射（便于检索与定位）。
|
||||||
|
|
@ -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，保证命令可复现。
|
||||||
|
|
@ -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`
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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`
|
||||||
|
|
||||||
|
当既有代码与本约定冲突时，优先保持局部一致性，逐步迁移。
|
||||||
|
|
@ -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
|
||||||
|
```
|
||||||
|
|
@ -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 性能与可测试性
|
||||||
|
|
||||||
|
- 避免过早优化；先写清晰正确的代码，再用数据驱动优化。
|
||||||
|
- 复杂逻辑要可测试：拆成纯函数或可注入依赖的模块。
|
||||||
|
|
@ -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++ 库、历史接口、跨语言互操作代码等。
|
||||||
|
|
@ -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 失败处理约定（必填）
|
||||||
|
|
||||||
|
- 只修复与本次改动直接相关的失败；无关失败在输出中说明并隔离。
|
||||||
|
- 若某验证步骤无法执行（缺环境/缺凭证），必须明确写出原因与替代验证手段（例如最小复现脚本/手动检查清单）。
|
||||||
|
|
@ -0,0 +1,223 @@
|
||||||
|
@echo off
|
||||||
|
setlocal enabledelayedexpansion
|
||||||
|
|
||||||
|
rem Sync standards snapshot to project root.
|
||||||
|
rem - Copies <snapshot>\.agents\<AGENTS_NS> -> <project-root>\.agents\<AGENTS_NS>
|
||||||
|
rem - Updates <project-root>\.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 <snapshot>\.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 ^<standards-url^> ^<branch^> --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
|
||||||
|
|
@ -0,0 +1,179 @@
|
||||||
|
# Sync standards snapshot to project root.
|
||||||
|
# - Copies <snapshot>/.agents/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
|
||||||
|
# - Updates <project-root>/.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 <url> <branch> --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 <snapshot>/.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."
|
||||||
|
|
@ -0,0 +1,200 @@
|
||||||
|
#!/usr/bin/env sh
|
||||||
|
set -eu
|
||||||
|
|
||||||
|
# Sync standards snapshot to project root.
|
||||||
|
# - Copies <snapshot>/.agents/<AGENTS_NS> -> <project-root>/.agents/<AGENTS_NS>
|
||||||
|
# - Updates <project-root>/.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 <standards-url> <branch> --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 <snapshot>/.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."
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
@ -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
|
||||||
|
# )
|
||||||
|
|
@ -0,0 +1,9 @@
|
||||||
|
{
|
||||||
|
"version": 4,
|
||||||
|
"vendor": {
|
||||||
|
"conan": {}
|
||||||
|
},
|
||||||
|
"include": [
|
||||||
|
"build/windows-x86_64-clang-cross/Release/generators/CMakePresets.json"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
|
@ -0,0 +1,24 @@
|
||||||
|
# Linux (Clang)
|
||||||
|
#
|
||||||
|
# Profile naming convention (suggested):
|
||||||
|
# linux-<arch>-clang<major>
|
||||||
|
# If the repo only supports one clang version, you may omit the <major> 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=[]
|
||||||
|
|
||||||
|
|
@ -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-<arch>-clang<major>-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": "<TOOLCHAIN_ROOT>/bin/x86_64-w64-mingw32-clang", "cpp": "<TOOLCHAIN_ROOT>/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
|
||||||
|
|
||||||
|
|
@ -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
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
@ -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"
|
||||||
|
}
|
||||||
|
|
||||||
|
|
@ -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",
|
||||||
|
]
|
||||||
|
|
||||||
Loading…
Reference in New Issue