diff --git a/.agents/auth.md b/.agents/cpp/auth.md similarity index 100% rename from .agents/auth.md rename to .agents/cpp/auth.md diff --git a/.agents/cpp/code_quality.md b/.agents/cpp/code_quality.md new file mode 100644 index 0000000..d776c72 --- /dev/null +++ b/.agents/cpp/code_quality.md @@ -0,0 +1,34 @@ +# 代码质量（Code Quality） + +本文件定义代理对代码质量的最低要求与审查清单（C++）。 + +## 1. 总体要求 + +- C++ 代码遵守 `docs/cpp/code_style.md` 与 `docs/cpp/naming.md`（在目标项目中通常 vendoring 到标准快照路径）。 +- 统一使用 `clang-format`（Google 基线）保持格式一致；不要手工“对齐排版”制造 diff 噪音。 +- 改动聚焦目标；避免“顺手重构”。 +- API 变更要显式说明影响与迁移方式。 +- 涉及三方依赖（例如 Conan）的改动必须说明动机、替代方案与影响面；默认不“顺手升级依赖”。 +- 涉及 C++ Modules 的改动（`.cppm` 或 `export module` 变更）必须同步更新构建系统的模块清单与相关 target 配置。 + +## 2. 可读性 + +- 复杂逻辑拆分为具名函数/类型；避免深层嵌套与重复代码。 +- 必要注释解释“为什么”而不是“做什么”。 + +## 3. 错误处理与资源管理 + +- 默认使用 RAII；避免裸 `new/delete`。 +- 失败路径必须可观测（返回值/异常/日志其一或按项目约定）。 + +## 4. 复杂度与规模 + +- 单函数尽量 ≤ 80 行；超过应说明原因或拆分（可按项目调整）。 +- 单次 PR 尽量小步提交，便于 review。 + +## 5. Review 清单 + +- 是否有无关改动？ +- 是否保持模块内风格一致？ +- 是否引入不必要的复杂度/依赖？ +- 是否有最小验证（构建/冒烟）步骤？ diff --git a/.agents/cpp/index.md b/.agents/cpp/index.md new file mode 100644 index 0000000..b3d5690 --- /dev/null +++ b/.agents/cpp/index.md @@ -0,0 +1,41 @@ +# C++ 代理规则集（.agents/cpp） + +本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（C++ 语言专属）。 + +## 范围与优先级 + +- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。 +- 当代理规则与 `docs` 发生冲突时： + 1. 安全/合规优先 + 2. 其次保持仓库现有一致性 + +## 代理工作原则 + +- 先理解目标与上下文，再动手改代码。 +- 修改要小而清晰；避免无关重构。 +- 不要引入新依赖或工具，除非明确要求。 + +## 子文档 + +- 安全与鉴权：`auth.md` +- 性能：`performance.md` +- 代码质量：`code_quality.md` +- 测试：`testing.md` + +## C++ 必要约定（必须遵守） + +- 语言标准：C++23（含 Modules）。 +- 格式化：统一使用 `clang-format`（Google 基线）；避免手工排版对齐造成 diff 噪音。 +- 文件与命名：遵守 `docs/cpp/` 下的规范（或目标项目 vendoring 的标准快照路径）。 +- Modules：module 名建议使用点分层级；每段用 `lower_snake_case`；module interface unit 推荐 `.cppm`。 +- Modules 工程：新增/删除/重命名 `.cppm` 或修改 `export module` 时，必须更新 CMake target 的模块 file-set/清单（否则构建容易漂移）。 +- Windows：不支持原生 Windows 开发环境；Windows 产物通过 Linux + Clang 交叉编译 profile 验证（profile 的 `[settings] os=Windows`）。 +- 依赖管理（如使用 Conan）：必须提供统一 preset（`conan-release`/`conan-debug`）；优先通过 `conan install` + `cmake --preset ...` 验证；如遇 Conan 家目录权限问题可临时设置 `CONAN_HOME=/tmp/conan-home`。 + +## 与开发规范的关系 + +- 在本仓库内：`docs/cpp/` 与 `docs/common/`。 +- 在目标项目内（若按 README 推荐的 subtree prefix `docs/standards/playbook`）： + - 代码风格：`docs/standards/playbook/docs/cpp/code_style.md` + - 命名规范：`docs/standards/playbook/docs/cpp/naming.md` + - 提交信息：`docs/standards/playbook/docs/common/commit_message.md` diff --git a/.agents/performance.md b/.agents/cpp/performance.md similarity index 100% rename from .agents/performance.md rename to .agents/cpp/performance.md diff --git a/.agents/cpp/testing.md b/.agents/cpp/testing.md new file mode 100644 index 0000000..dfb912a --- /dev/null +++ b/.agents/cpp/testing.md @@ -0,0 +1,26 @@ +# 测试（Testing） + +本文件定义代理在改动代码时的测试策略与要求。 + +## 1. 测试层级 + +- **单元测试**：验证函数/模块的独立行为。 +- **集成测试**：验证模块间交互与关键流程。 +- **回归测试**：防止已修复问题复发。 + +## 2. 何时补测试 + +- 新功能必须新增对应测试（若项目有测试体系）。 +- 修复 bug 必须先写/补回归用例（若项目有测试体系）。 +- 仅当改动纯文档/注释/格式时可不加测试。 + +## 3. 测试可维护性 + +- 一个用例只验证一个行为点。 +- 测试命名清晰，能从名字看出期望。 +- 避免依赖外部不稳定资源；必要时 mock/stub。 + +## 4. 运行与失败处理 + +- 若项目提供构建/冒烟命令（CMake），优先保证最小构建可通过。 +- 失败时优先定位改动相关原因，不修无关失败。 diff --git a/.agents/index.md b/.agents/index.md index 55d5f53..9fcce52 100644 --- a/.agents/index.md +++ b/.agents/index.md @@ -1,60 +1,11 @@ -# TSL Playbook 代理规则集（.agents/tsl） +# .agents（多语言规则集快照） -本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**。 +本目录用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**。 -在多语言项目中，推荐将本规则集放在目标项目的 `.agents/tsl/` 下（由 `scripts/sync_standards.*` 同步），并与其他语言规则集并行： +本仓库将规则按语言拆分为多个规则集快照： -- `.agents/tsl/`：TSL 标准规则集（本仓库提供） -- `.agents/cpp/`、`.agents/python/` 等：其他语言规则集（按需新增） +- `.agents/tsl/`：TSL 相关规则集（适用于 `.tsl`/`.tsf`） +- `.agents/cpp/`：C++ 相关规则集（C++23，含 Modules） +- `.agents/python/`：Python 相关规则集 -这些规则与 `docs/` 下的人类开发规范并行： - -- `docs/`：给人看的编码/命名/提交规范 -- `.agents/`：给代理看的任务边界、质量与安全要求 - -## 范围与优先级 - -- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。 -- 当代理规则与 `docs` 发生冲突时： - 1. 安全/合规优先 - 2. 其次保持仓库现有一致性 - -## 代理工作原则 - -- 先理解目标与上下文，再动手改代码。 -- 修改要小而清晰；避免无关重构。 -- 任何可能影响行为的改动都要补充或更新测试/示例（若项目有测试体系）。 -- 不要引入新依赖或工具，除非明确要求。 - -## 子文档 - -- 安全与鉴权：`auth.md` -- 性能：`performance.md` -- 代码质量：`code_quality.md` -- 测试：`testing.md` - -## 分类（本仓库现状） - -当前本规则集下的文件以 **跨语言通用规则** 为主（不绑定具体语言语法/工具链），但包含 TSL 代码在仓库里最容易踩坑的“语言级硬约束”，以避免代理在缺少上下文时写出不符合 TSL/TSF 约定的代码。 - -- `auth.md`：敏感信息/鉴权边界 -- `code_quality.md`：质量底线与 review 清单 -- `performance.md`：性能原则与验证 -- `testing.md`：测试策略 - -若项目需要更细的语言/模块专属代理要求，建议在更靠近源码的目录放置更具体的规则（例如 `src/.agents/`），或并行新增其他规则集（例如 `.agents/cpp/`）。 - -## TSL/TSF 必要约定（必须遵守） - -- `.tsl` 与 `.tsf` 都是 Tinysoft Language 源文件；修改它们时统一按 TSL 规范处理（不要把 `.tsf` 当成“另一种语言/无风格约束的脚本”）。 -- 文件级约束：一个文件只能有一个顶层声明，且文件基名必须与该顶层声明同名（推荐 `PascalCase`）；`.tsl` 顶层声明只能是 `function`。 -- 格式：空格缩进（默认 4 空格），关键字用小写，复杂分支/多语句分支用 `begin/end` 块表达结构。 -- 命名：类型/顶层函数/property 用 `PascalCase`；局部变量/参数用 `snake_case`；私有成员变量用 `snake_case_`。 - -## 与开发规范的关系 - -- 在本仓库内：`docs/tsl/` 与 `docs/common/`。 -- 在目标项目内：标准快照应 vendoring 到 `docs/standards/tsl/`，对应路径为： - - 代码风格：`docs/standards/tsl/docs/tsl/code_style.md` - - 命名规范：`docs/standards/tsl/docs/tsl/naming.md` - - 提交信息：`docs/standards/tsl/docs/common/commit_message.md` +目标项目落地时，通常通过 `scripts/sync_standards.*` 将某个规则集同步到目标项目根目录的 `.agents//`。 diff --git a/.agents/python/auth.md b/.agents/python/auth.md new file mode 100644 index 0000000..3194974 --- /dev/null +++ b/.agents/python/auth.md @@ -0,0 +1,15 @@ +# 安全与鉴权（Auth & Security） + +本文件定义代理在涉及鉴权/密钥/权限时必须遵守的最低要求（Python）。 + +## 基本原则 + +- 默认最小权限：避免使用全局管理员/Root 权限完成可在用户权限完成的事。 +- 不要提交任何密钥材料：token、私钥、证书、访问密钥、`.env` 中的真实值等。 +- 任何涉及加密/鉴权的实现变更必须说明威胁模型与兼容性影响。 + +## 常见风险与要求 + +- 输入校验：对外部输入（CLI 参数、环境变量、文件、网络数据）要做类型/范围校验，避免命令注入、路径穿越等问题。 +- 依赖安全：避免新增“来源不明”的依赖；如必须新增，需说明来源与版本锁定策略。 +- 日志脱敏：日志中不得输出凭据、个人敏感信息（PII）或可重放的签名/URL。 diff --git a/.agents/python/code_quality.md b/.agents/python/code_quality.md new file mode 100644 index 0000000..4dd8e61 --- /dev/null +++ b/.agents/python/code_quality.md @@ -0,0 +1,27 @@ +# 代码质量（Code Quality） + +本文件定义代理对代码质量的最低要求与审查清单（Python）。 + +## 1. 总体要求 + +- 改动聚焦目标；避免“顺手重构”。 +- API/行为变更要显式说明影响与迁移方式（尤其是脚本/CLI 输出与配置项）。 +- 保持仓库现有约定：优先复用既有结构、命名与工具配置（见 `docs/python/`）。 + +## 2. 可读性 + +- 复杂逻辑拆分为具名函数/模块；避免超长函数。 +- 尽量使用显式类型与数据结构表达意图（必要时补类型标注）。 +- 注释解释“为什么”，避免注释重复代码表述。 + +## 3. 错误处理 + +- 失败必须可观测：返回码/异常/日志至少一种要明确。 +- CLI/自动化脚本：遇到不可恢复错误应非零退出码。 + +## 4. Review 清单 + +- 是否引入了不必要的新依赖？ +- 是否遵循 `pyproject.toml` 与 lint 配置？ +- 是否对 I/O（文件/网络/数据库）失败路径做了处理？ +- 是否需要补测试或示例？ diff --git a/.agents/python/index.md b/.agents/python/index.md new file mode 100644 index 0000000..3cbbf57 --- /dev/null +++ b/.agents/python/index.md @@ -0,0 +1,40 @@ +# Python 代理规则集（.agents/python） + +本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（Python 语言专属）。 + +## 范围与优先级 + +- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。 +- 当代理规则与 `docs` 发生冲突时： + 1. 安全/合规优先 + 2. 其次保持仓库现有一致性 + +## 代理工作原则 + +- 先理解目标与上下文，再动手改代码。 +- 修改要小而清晰；避免无关重构。 +- 不要引入新依赖或工具，除非明确要求。 + +## 子文档 + +- 安全与鉴权：`auth.md` +- 性能：`performance.md` +- 代码质量：`code_quality.md` +- 测试：`testing.md` + +## Python 必要约定（必须遵守） + +- 代码风格基线：Google Python Style Guide。 +- 格式化与静态检查：优先使用仓库既有配置（`pyproject.toml`、`.flake8`、`.pylintrc`、`.pre-commit-config.yaml`）；不要在未沟通前切换到另一套工具链。 +- import 顺序：遵守 `isort profile = google`（若启用）。 +- 文档字符串：Google 风格（与 `.flake8`/团队约定对齐）。 +- 命名：遵循 `docs/python/style_guide.md` 中的约定；如与既有代码冲突，以局部一致性优先。 + +## 与开发规范的关系 + +- 在本仓库内：`docs/python/` 与 `docs/common/`。 +- 在目标项目内（若按 README 推荐的 subtree prefix `docs/standards/playbook`）： + - 代码风格：`docs/standards/playbook/docs/python/style_guide.md` + - 工具链：`docs/standards/playbook/docs/python/tooling.md` + - 配置说明：`docs/standards/playbook/docs/python/configuration.md` + - 提交信息：`docs/standards/playbook/docs/common/commit_message.md` diff --git a/.agents/python/performance.md b/.agents/python/performance.md new file mode 100644 index 0000000..f1e1b31 --- /dev/null +++ b/.agents/python/performance.md @@ -0,0 +1,15 @@ +# 性能（Performance） + +本文件定义代理在性能相关改动时的最低要求（Python）。 + +## 基本原则 + +- 先保证正确性与可读性，再做优化。 +- 优化前先定位瓶颈：避免盲目微优化。 +- 对可能影响性能的改动，说明复杂度变化与典型数据规模假设。 + +## 常见注意点 + +- 避免在热路径重复 I/O（文件读写、网络请求、重复解析）。 +- 对大列表/大文件处理优先采用流式处理与生成器。 +- 警惕 `O(n^2)` 循环、重复正则编译、重复 JSON/YAML 解析等。 diff --git a/.agents/python/testing.md b/.agents/python/testing.md new file mode 100644 index 0000000..cde0bcc --- /dev/null +++ b/.agents/python/testing.md @@ -0,0 +1,13 @@ +# 测试（Testing） + +本文件定义代理在测试相关工作的最低要求（Python）。 + +## 原则 + +- 优先增加与变更直接相关的测试（回归测试优先）。 +- 测试应可重复运行、无顺序依赖、尽量避免真实网络/真实环境依赖。 + +## 约定（模板） + +- 若项目使用 `pytest`：遵循 `pyproject.toml` 中的 `pytest.ini_options` 配置。 +- I/O 相关代码建议使用临时目录与 mock，避免污染工作区。 diff --git a/.agents/tsl/auth.md b/.agents/tsl/auth.md new file mode 100644 index 0000000..5adf24f --- /dev/null +++ b/.agents/tsl/auth.md @@ -0,0 +1,33 @@ +# 安全与鉴权（Auth） + +本文件定义代理在处理鉴权、安全、敏感数据相关任务时的边界与要求。 + +## 1. 基本原则 + +- **最小权限**：只使用完成任务所需的最低权限与最少数据。 +- **默认保守**：不确定是否敏感时按敏感处理。 +- **不扩散秘密**：任何 secret 只在必要范围内出现。 + +## 2. 凭证与敏感信息 + +- 不要在代码、日志、注释或文档中写入明文密钥、Token、密码。 +- 如需示例，使用占位符：``、``。 +- 避免把敏感信息打印到标准输出或错误日志。 + +## 3. 鉴权逻辑修改 + +- 修改鉴权/权限控制时必须说明： + - 变更动机 + - 风险评估 + - 兼容性/回滚方案 +- 默认保持旧行为兼容，除非明确要求破坏性变更。 + +## 4. 依赖与第三方 + +- 禁止无理由新增依赖，尤其是网络、加密、认证相关依赖。 +- 若必须新增，需在 PR 说明理由、替代方案与安全影响。 + +## 5. 审计与合规 + +- 任何涉及用户数据/权限边界的改动需可审计：代码清晰、注释说明“为什么”。 +- 发现潜在安全漏洞时，优先修复或明确标注 `FIXME(name): security risk ...`。 diff --git a/.agents/code_quality.md b/.agents/tsl/code_quality.md similarity index 87% rename from .agents/code_quality.md rename to .agents/tsl/code_quality.md index 980bfdf..ce2c014 100644 --- a/.agents/code_quality.md +++ b/.agents/tsl/code_quality.md @@ -1,10 +1,10 @@ # 代码质量（Code Quality） -本文件定义代理对代码质量的最低要求与审查清单。 +本文件定义代理对代码质量的最低要求与审查清单（TSL）。 ## 1. 总体要求 -- 对 `.tsl`/`.tsf` 文件一律按 TSL 规范处理（`.tsf` 也是 TSL 源文件）：遵守标准快照中的 `docs/tsl/code_style.md` 与 `docs/tsl/naming.md`（在目标项目中应 vendoring 到 `docs/standards/tsl/docs/tsl/`）。 +- 对 `.tsl`/`.tsf` 文件一律按 TSL 规范处理（`.tsf` 也是 TSL 源文件）：遵守标准快照中的 `docs/tsl/code_style.md` 与 `docs/tsl/naming.md`（在目标项目中通常 vendoring 到 `docs/standards/playbook/docs/tsl/`）。 - 改动聚焦目标；避免“顺手重构”。 - API 变更要显式说明影响与迁移方式。 diff --git a/.agents/tsl/index.md b/.agents/tsl/index.md new file mode 100644 index 0000000..ba3cae3 --- /dev/null +++ b/.agents/tsl/index.md @@ -0,0 +1,39 @@ +# TSL 代理规则集（.agents/tsl） + +本规则集用于存放 **AI/自动化代理在仓库内工作时必须遵守的规则**（TSL 语言专属）。 + +## 范围与优先级 + +- 作为仓库级基线规则集使用；更靠近代码目录的规则应更具体并可覆盖基线。 +- 当代理规则与 `docs` 发生冲突时： + 1. 安全/合规优先 + 2. 其次保持仓库现有一致性 + +## 代理工作原则 + +- 先理解目标与上下文，再动手改代码。 +- 修改要小而清晰；避免无关重构。 +- 任何可能影响行为的改动都要补充或更新测试/示例（若项目有测试体系）。 +- 不要引入新依赖或工具，除非明确要求。 + +## 子文档 + +- 安全与鉴权：`auth.md` +- 性能：`performance.md` +- 代码质量：`code_quality.md` +- 测试：`testing.md` + +## TSL/TSF 必要约定（必须遵守） + +- `.tsl` 与 `.tsf` 都是 Tinysoft Language 源文件；修改它们时统一按 TSL 规范处理（不要把 `.tsf` 当成“另一种语言/无风格约束的脚本”）。 +- 文件级约束：一个文件只能有一个顶层声明，且文件基名必须与该顶层声明同名（推荐 `PascalCase`）；`.tsl` 顶层声明只能是 `function`。 +- 格式：空格缩进（默认 4 空格），关键字用小写，复杂分支/多语句分支用 `begin/end` 块表达结构。 +- 命名：类型/顶层函数/property 用 `PascalCase`；局部变量/参数用 `snake_case`；私有成员变量用 `snake_case_`。 + +## 与开发规范的关系 + +- 在本仓库内：`docs/tsl/` 与 `docs/common/`。 +- 在目标项目内（若按 README 推荐的 subtree prefix `docs/standards/playbook`）： + - 代码风格：`docs/standards/playbook/docs/tsl/code_style.md` + - 命名规范：`docs/standards/playbook/docs/tsl/naming.md` + - 提交信息：`docs/standards/playbook/docs/common/commit_message.md` diff --git a/.agents/tsl/performance.md b/.agents/tsl/performance.md new file mode 100644 index 0000000..b76f73c --- /dev/null +++ b/.agents/tsl/performance.md @@ -0,0 +1,31 @@ +# 性能（Performance） + +本文件定义代理在做性能相关改动时的准则与检查项。 + +## 1. 目标与度量 + +- 明确性能目标：延迟、吞吐、内存、CPU、I/O 等。 +- 没有指标时不要盲目优化；先补充测量或基准。 + +## 2. 处理流程 + +1. 先定位瓶颈（profile/trace/log）。 +2. 再提出最小化改动方案。 +3. 最后用数据验证收益与副作用。 + +## 3. 优化准则 + +- 优先消除算法/结构性问题，再考虑微优化。 +- 避免引入复杂度换取小收益。 +- 性能优化不应牺牲可读性；必要时加注释说明权衡。 + +## 4. 常见风险 + +- 避免重复计算、无界缓存、隐式复制。 +- 注意热路径中的分配与 I/O。 +- 并发优化要考虑正确性与可测试性。 + +## 5. 验证 + +- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。 +- 若无测试体系，至少提供最小可运行的复现脚本/步骤。 diff --git a/.agents/testing.md b/.agents/tsl/testing.md similarity index 100% rename from .agents/testing.md rename to .agents/tsl/testing.md diff --git a/.gitattributes b/.gitattributes index 19916ec..c0f4849 100644 --- a/.gitattributes +++ b/.gitattributes @@ -19,6 +19,29 @@ *.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5e4b261 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,7 @@ +# Contributing + +## Commit messages + +Follow the repository commit message standard: + +- `docs/common/commit_message.md` diff --git a/README.md b/README.md index b09c344..b11292c 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# tsl-playbook +# playbook -TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则合集。 +Playbook：TSL（`.tsl`/`.tsf`）+ C++ + Python 工程规范与代理规则合集。 ## 目标 @@ -23,20 +23,29 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则 `docs/` 目录是给开发者阅读的工程规范，约束代码写法、命名与提交信息。 -- `docs/index.md`：文档导航（跨语言 common / TSL 专属）。 +- `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/` 目录是给自动化/AI 代理在本仓库内工作时遵守的规则快照，与 `docs/` 并行。 -- `.agents/index.md`：代理规则索引、适用范围与工作原则。 -- `.agents/auth.md`：安全与鉴权边界、敏感信息处理要求。 -- `.agents/performance.md`：性能优化原则、流程与验证要求。 -- `.agents/code_quality.md`：代码质量底线与 review 清单。 -- `.agents/testing.md`：测试策略与何时补测试。 +- `.agents/index.md`：规则集索引（多语言）。 +- `.agents/tsl/`：TSL 规则集（入口：`.agents/tsl/index.md`）。 +- `.agents/cpp/`：C++ 规则集（入口：`.agents/cpp/index.md`）。 ## 在其他项目中使用本 Playbook @@ -48,8 +57,8 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则 ```bash git subtree add \ - --prefix docs/standards/tsl \ - https://git.mytsl.cn/csh/tsl-playbook.git \ + --prefix docs/standards/playbook \ + https://git.mytsl.cn/csh/playbook.git \ main --squash ``` @@ -57,31 +66,44 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则 ```bash git subtree pull \ - --prefix docs/standards/tsl \ - https://git.mytsl.cn/csh/tsl-playbook.git \ + --prefix docs/standards/playbook \ + https://git.mytsl.cn/csh/playbook.git \ main --squash ``` #### 快速落地（最小 4 步） -在目标项目中按以下顺序执行即可完成落地（推荐固定使用 `--prefix docs/standards/tsl`）： +在目标项目中按以下顺序执行即可完成落地（推荐固定使用 `--prefix docs/standards/playbook`）： 1. 引入标准快照（见上文 `git subtree add`） -2. 同步到项目根目录（生成/更新 `.agents/tsl/`、更新 `.gitattributes`）： +2. 同步到项目根目录（生成/更新 `.agents//`、更新 `.gitattributes`）： ```bash - sh docs/standards/tsl/scripts/sync_standards.sh + 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` - - 标准文档可读：`docs/standards/tsl/docs/index.md` - - `.gitattributes` 包含区块：`# BEGIN tsl-playbook .gitattributes` / `# END tsl-playbook .gitattributes` + - （可选）C++ 规则入口可读：`.agents/cpp/index.md` + - 标准文档可读：`docs/standards/playbook/docs/index.md` + - `.gitattributes` 包含区块：`# BEGIN playbook .gitattributes` / `# END playbook .gitattributes` 4. 将同步产物纳入版本控制（目标项目建议提交）： - - `docs/standards/tsl/`（标准快照） + - `docs/standards/playbook/`（标准快照） - `.agents/tsl/`（落地规则集） - `.gitattributes`（managed block 更新） @@ -93,9 +115,14 @@ TSL Playbook：Tinysoft Language（`.tsl` / `.tsf`）工程规范与代理规则 #!/usr/bin/env sh set -eu -sh docs/standards/tsl/scripts/sync_standards.sh +sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp # sh docs/standards/python/scripts/sync_standards.sh -# sh docs/standards/cpp/scripts/sync_standards.sh +``` + +也可以直接一次同步多个规则集： + +```sh +sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp ``` #### 目录约定（建议） @@ -106,12 +133,13 @@ sh docs/standards/tsl/scripts/sync_standards.sh . ├── .agents/ │ ├── index.md # 多语言代理规则集索引（缺省时由脚本创建） -│ └── tsl/ # 从 Playbook 同步（仅覆盖该子目录） +│ ├── tsl/ # 从 Playbook 同步（仅覆盖该子目录） +│ └── cpp/ # 从 Playbook 同步（仅覆盖该子目录，按需） ├── .gitattributes # 从 Playbook 同步 ├── docs/ │ ├── standards/ │ │ └── tsl/ # git subtree 快照（只读） -│ │ ├── docs/ # common/ + tsl/ +│ │ ├── docs/ # common/ + tsl/ + cpp/ │ │ ├── .agents/ # 标准代理规则快照 │ │ ├── .gitattributes │ │ └── SOURCE.md # 记录来源版本/commit（项目自行维护） @@ -119,24 +147,24 @@ sh docs/standards/tsl/scripts/sync_standards.sh └── README.md # 说明遵循 standards ``` -根目录的 `.agents/tsl/` 与 `.gitattributes` 通过同步脚本获得： +根目录的 `.agents//` 与 `.gitattributes` 通过同步脚本获得： -- 说明：在 **本 playbook 仓库** 内脚本位于 `scripts/`；在 **目标项目** 里通过 `git subtree` 引入到 `docs/standards/tsl/` 后，脚本路径变为 `docs/standards/tsl/scripts/`。 +- 说明：在 **本 playbook 仓库** 内脚本位于 `scripts/`；在 **目标项目** 里通过 `git subtree` 引入到 `docs/standards/playbook/` 后，脚本路径变为 `docs/standards/playbook/scripts/`。 - 在目标项目里直接运行 Playbook 提供的脚本（子树快照里自带）： -- `docs/standards/tsl/scripts/sync_standards.sh`（推荐） -- `docs/standards/tsl/scripts/sync_standards.ps1`（推荐） -- `docs/standards/tsl/scripts/sync_standards.bat`（推荐） +- `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/tsl`，因为同步后的 `.agents/tsl/` 会引用该路径下的标准快照文档（`docs/standards/tsl/docs/...`）。 -注：默认同步到 `.agents/tsl/`；如需指定规则集名称，可通过环境变量 `AGENTS_NS`（例如 `AGENTS_NS=tsl`、`AGENTS_NS=common`）。 +注：建议固定使用 `--prefix docs/standards/playbook`，因为同步后的 `.agents/*/` 会引用该路径下的标准快照文档（`docs/standards/playbook/docs/...`）。 +注：默认同步到 `.agents/tsl/`；如需同步 C++ 规则集，推荐直接运行：`sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp`。 这样 clone 任意项目时都能直接读取规范文件，不依赖外部访问权限。 同步脚本行为（目标项目内的最终落地内容）： - 覆盖/更新：`.agents//`（默认 `.agents/tsl/`） -- 更新 `.gitattributes`：默认只维护 `# BEGIN tsl-playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制） +- 更新 `.gitattributes`：默认只维护 `# BEGIN playbook .gitattributes` 区块（可用 `SYNC_GITATTR_MODE=block|overwrite|skip` 控制） - 缺省创建：`.agents/index.md` - 覆盖前备份：写入同目录的 `*.bak.*`（或 Windows 下随机后缀） - 不修改：`.gitignore`（项目自行维护） @@ -147,7 +175,7 @@ sh docs/standards/tsl/scripts/sync_standards.sh | 变量名 | 默认值 | 说明 | | ------------------- | ------- | ------------------------------------------------------------------------------------------- | -| `AGENTS_NS` | `tsl` | 规则集落地目录名：`.agents//` | +| `AGENTS_NS` | `tsl` | 同步的规则集名/落地目录名：`.agents//`（例如 `tsl`、`cpp`） | | `SYNC_GITATTR_MODE` | `block` | `.gitattributes` 同步模式：`block` 仅维护 managed 区块；`overwrite` 全量覆盖；`skip` 不更新 | ### 方式二：手动复制快照 @@ -156,14 +184,14 @@ sh docs/standards/tsl/scripts/sync_standards.sh 步骤： -1. 在目标项目创建目录：`docs/standards/tsl/`。 +1. 在目标项目创建目录：`docs/standards/playbook/`。 2. 从本仓库复制以下内容到目标项目： - - `docs/` → `docs/standards/tsl/docs/`（包含 `docs/common/` 与 `docs/tsl/`） - - `.agents/` → `docs/standards/tsl/.agents/` - - `.gitattributes` → `docs/standards/tsl/.gitattributes` - - `scripts/` → `docs/standards/tsl/scripts/` + - `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/tsl/SOURCE.md` 记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。 +4. 在 `docs/standards/playbook/SOURCE.md` 记录本次复制的来源版本/日期（建议写 Playbook 的 commit hash）。 该方式没有自动同步能力，后续更新需重复上述复制流程。 @@ -180,12 +208,10 @@ sh docs/standards/tsl/scripts/sync_standards.sh 建议：仓库级规则尽量少且稳定；语言级规则各自独立，避免互相“污染”。 -本仓库提供的代理规则集（同步后位于目标项目的 `.agents/tsl/`）以**跨语言通用规则**为主，但包含 TSL/TSF 文件（`.tsl`/`.tsf`）的必要约定（避免代理在缺少上下文时写出不符合 TSL 约束的代码）： +本仓库提供两套代理规则集（同步后位于目标项目的 `.agents/tsl/` 与 `.agents/cpp/`）： -- `auth.md`：敏感信息/鉴权边界 -- `code_quality.md`：质量底线与 review 清单 -- `performance.md`：性能原则与验证 -- `testing.md`：测试策略 +- 两者都包含跨语言通用底线：`auth.md`、`code_quality.md`、`performance.md`、`testing.md` +- 并在 `index.md` 中叠加语言级“硬约束”（TSL/TSF 语法限制、C++23/Modules、Windows 支持等） 多语言项目推荐结构（示例：TSL + C++ + Python）： @@ -194,13 +220,12 @@ sh docs/standards/tsl/scripts/sync_standards.sh ├── .agents/ │ ├── index.md # 多语言索引（缺省时由脚本创建） │ ├── tsl/ # 由本 Playbook 同步（适用于 .tsl/.tsf） -│ ├── cpp/ # C++ 规则集（来自另一个 playbook 或项目自建） +│ ├── cpp/ # 由本 Playbook 同步（适用于 C++23/Modules） │ └── python/ # Python 规则集（同上） ├── .gitattributes # 行尾/文本规范（可由某个 playbook 同步） ├── docs/ │ ├── standards/ -│ │ ├── tsl/ # 本 Playbook 快照（git subtree/vendoring） -│ │ ├── cpp/ # C++ playbook 快照（可选） +│ │ ├── tsl/ # 本 Playbook 快照（git subtree/vendoring；包含 common/tsl/cpp） │ │ └── python/ # Python playbook 快照（可选） │ └── project/ # 项目自有文档（架构、ADR、运行方式等） ├── scripts/ @@ -230,7 +255,7 @@ macOS/Linux 示例（目标项目的 `scripts/sync_standards.sh`）： #!/usr/bin/env sh set -eu -sh docs/standards/tsl/scripts/sync_standards.sh +sh docs/standards/playbook/scripts/sync_standards.sh tsl cpp OVERLAY="docs/project/agents_overlay" if [ -d "$OVERLAY" ]; then @@ -242,9 +267,7 @@ fi PowerShell 示例（目标项目的 `scripts/sync_standards.ps1`）： ```powershell -$ErrorActionPreference = "Stop" - -& "docs/standards/tsl/scripts/sync_standards.ps1" +& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs tsl,cpp $overlay = "docs/project/agents_overlay" if (Test-Path $overlay) { @@ -257,10 +280,15 @@ if (Test-Path $overlay) { 当目标项目需要新增一门语言（例如 C++），建议按以下模板扩展： -- 文档：在目标项目增加 `docs/standards/cpp/docs/`（或另一个标准仓库 subtree），并在项目 `README.md`/`docs/index.md` 链接入口。 -- 代理规则：在目标项目增加 `.agents/cpp/`（与 `.agents/tsl/` 并行），只写 C++ 专属要求与工具链约束。 +- 文档： + - 若使用本 Playbook 自带的 C++ 规范：无需额外 subtree，直接使用 `docs/standards/playbook/docs/cpp/`，并在项目 `README.md`/`docs/index.md` 链接入口。 + - 若新增“本 Playbook 未覆盖的语言”：再引入对应语言的标准仓库（subtree/vendoring 到 `docs/standards//`）。 +- 代理规则： + - C++：运行 `sh docs/standards/playbook/scripts/sync_standards.sh cpp`（或 `& "docs/standards/playbook/scripts/sync_standards.ps1" -Langs cpp`），落地到 `.agents/cpp/`（与 `.agents/tsl/` 并行）。 + - 其他语言：在目标项目增加 `.agents//`（与 `.agents/tsl/` 并行），只写该语言专属要求与工具链约束。 - 同步策略：每个规则集只同步到对应子目录（例如 `.agents/cpp/`），避免覆盖整个 `.agents/`。 - CI/工具：按文件类型分别执行格式化、lint、测试（不要让 TSL 规则去约束 C++ 代码，反之亦然）。 + - C++ 补全：建议在项目根目录提供 `.clangd` 并指向正确的 `CompilationDatabase`（模板见 `templates/cpp/.clangd`）。 ## 版本与贡献 diff --git a/docs/common/commit_message.md b/docs/common/commit_message.md index 973d6d9..b4e66de 100644 --- a/docs/common/commit_message.md +++ b/docs/common/commit_message.md @@ -10,9 +10,9 @@ ## 2. 格式 -推荐使用以下结构（emoji 可选）： +推荐使用以下结构（emoji 可选，但建议默认带上以便快速扫读）： -``` +```txt :emoji: type(scope): subject body @@ -20,7 +20,7 @@ body footer ``` -- `emoji`：可选，位于首行行首；若使用，必须与 `type` 一一对应（见 4）。 +- `emoji`：可选，位于首行行首；若使用，必须与 `type` 一一对应（见 4）。为保持一致性，建议默认使用 emoji；若不使用则省略即可。 - `type`：变更类型，必须从 4 的对应表中选取。 - `scope`：可选，业务域/组件名（`lower_snake_case`），用于辅助定位影响范围。 - `subject`：一句话概述，使用祈使句/现在时，首字母小写，不加句号。 @@ -64,23 +64,23 @@ footer 本仓库采用固定的 `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:` | 发布/打版本标签 | +| 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` 类型。 @@ -146,7 +146,7 @@ MAJOR.MINOR.PATCH 带 emoji： -``` +```txt :sparkles: feat(order): add batch cancel api support canceling multiple orders in one request; keep old api unchanged. @@ -156,6 +156,6 @@ Refs: TSL-1234 不带 emoji： -``` +```txt refactor(order): simplify cancel flow ``` diff --git a/docs/cpp/clangd.md b/docs/cpp/clangd.md new file mode 100644 index 0000000..eaddff9 --- /dev/null +++ b/docs/cpp/clangd.md @@ -0,0 +1,23 @@ +# clangd 补全配置（`.clangd`） + +本章节提供 `clangd` 的推荐配置模板与落地要点（参考 `tsl-devkit/lsp-server/.clangd`）。 + +## 1. 目标 + +- 让 IDE/编辑器的 C++ 补全、跳转、诊断稳定可复现。 +- 优先依赖 `compile_commands.json`（由 CMake 生成），避免手写复杂编译参数。 + +## 2. 必要前提：生成 `compile_commands.json` + +- CMake：建议开启 `CMAKE_EXPORT_COMPILE_COMMANDS=ON`（本 Playbook 的 `templates/cpp/CMakeLists.txt` 已开启）。 +- 使用 preset 构建后，在对应 build 目录会生成 `compile_commands.json`： + - 例如：`build/windows-x86_64-clang-cross/Release/compile_commands.json` + +## 3. `.clangd` 模板 + +- 模板文件：`templates/cpp/.clangd` +- 关键字段：`CompileFlags.CompilationDatabase` 指向 build 目录（包含 `compile_commands.json` 的目录）。 + +## 4. Modules 注意事项（C++23） + +- 若新增/删除/重命名 `.cppm`，必须同步更新构建系统的模块清单（例如 CMake `FILE_SET CXX_MODULES`），否则 `compile_commands.json` 可能缺项，导致 clangd 补全/跳转不稳定。 diff --git a/docs/cpp/code_style.md b/docs/cpp/code_style.md new file mode 100644 index 0000000..4aecfd9 --- /dev/null +++ b/docs/cpp/code_style.md @@ -0,0 +1,72 @@ +# C++ 代码风格（Code Style） + +本章节规定 C++（C++23，含 Modules）代码的结构与格式约定。 + +## 1. 文件与组织 + +### 1.1 目录建议（项目落地） + +推荐将 C++ 代码放在独立目录（多语言项目便于隔离规则与工具）： + +```txt +cpp/ + include/ # 对外头文件（如项目仍使用头文件边界） + src/ # 实现文件与 module 实现单元 + modules/ # module interface / partition（如使用 modules） + tests/ # （可选）测试 + CMakeLists.txt +``` + +若项目不采用 `cpp/` 根目录，也应保持 include/src/modules 分层清晰。 + +### 1.2 文件扩展名约定 + +- 头文件：`.h`（Google 风格；若项目已统一 `.hpp`，以项目既有为准） +- 源文件：`.cc`（优先；`main` 入口建议使用 `main.cc`；若项目已统一 `.cpp`，以项目既有为准） +- Module Interface Unit：`.cppm`（推荐统一） +- Module Partition：`.cppm`（在文件名中体现分区，例如 `foo_part.cppm`） + +### 1.3 Modules 约定（C++23） + +- Module 名称建议使用“点分层级”组织，且每一段使用 `lower_snake_case`： + - 示例：`my_project.net.http` +- 文件路径与 module 名建议可映射（便于检索）： + - `cpp/modules/my_project/net/http.cppm` → `export module my_project.net.http;` +- 避免在同一模块内混用“头文件边界”和“模块边界”造成可见性混乱；对外 API 优先通过 `export` 暴露。 +- 工程约束：新增/删除/重命名 `.cppm`（或变更 `export module ...`）时，必须同步更新构建系统的模块清单（例如 CMake 的 `target_sources(FILE_SET CXX_MODULES ...)`），否则容易出现“本地能编、CI/他人机器不能编”的漂移。 + +## 2. 格式（Formatting） + +### 2.1 clang-format（必选） + +- 本仓库/标准默认：`clang-format` + Google 风格。 +- 建议在项目根目录提供 `.clang-format` 并纳入 CI/本地钩子。 +- 列宽建议与本 Playbook 其他语言保持一致：默认 100（可按项目调整，但要全仓一致）。 +- 模板：`templates/cpp/.clang-format`（参考 `tsl-devkit/lsp-server/.clang-format` 并做了最小化泛化）。 + +### 2.2 通用格式约定 + +- 缩进使用空格，单次缩进 4 空格（Google）。 +- 不做“空格对齐排版”（避免 diff 噪音），用缩进表达结构。 +- 头文件 include 顺序建议（从上到下）： + 1. 本文件对应头（如有） + 2. C 标准库 / C++ 标准库 + 3. 第三方库 + 4. 项目内其他头/模块导入 + +## 3. 头文件与可见性 + +- 头文件应可被独立 include（自包含）。 +- 对外接口放在 `include/`，实现细节放 `src/`。 +- 避免在头文件中引入沉重依赖；可用前置声明或 PImpl（按项目需要）。 + +## 4. 错误处理与资源管理 + +- 默认使用 RAII 管理资源；避免裸 `new/delete`。 +- 禁止吞异常/忽略错误；失败路径必须可观测（返回值/异常/日志其一或按项目约定）。 + +## 5. Windows 支持 + +- 本规范假设 **不做原生 Windows 开发环境支持**；Windows 产物通过 **Linux 上的 Clang 交叉编译工具链**获得（工具链路径/三元组等由项目的 Conan profile 或 toolchain 文件定义）。 +- 如需条件编译，优先用标准特性检测与最小化条件编译，并写清动机（例如 ABI/平台差异）。 +- 对路径、换行、编码、大小写敏感等行为要明确约束并在文档/测试中覆盖。 diff --git a/docs/cpp/dependencies_conan.md b/docs/cpp/dependencies_conan.md new file mode 100644 index 0000000..90bf3ca --- /dev/null +++ b/docs/cpp/dependencies_conan.md @@ -0,0 +1,79 @@ +# C++ 第三方依赖（Conan） + +本章节给出 Conan + CMake 的推荐落地方式（参考 `tsl-devkit/lsp-server/` 的实践）。 + +## 1. 基本约定 + +- 依赖清单使用 `conanfile.txt`（或项目统一的 `conanfile.py`）。 +- 本 Playbook 不内置“标准依赖集合/固定版本”；依赖选择与版本锁定由具体项目维护。 +- Conan：`2.x`（本 Playbook 假设 Conan 2；不保证 Conan 1 的兼容性） +- 生成器使用： + - `CMakeDeps` + - `CMakeToolchain` +- layout 使用：`cmake_layout`（让 build 目录结构稳定可预测） + +## 2. 目录与文件（建议） + +```txt +cpp/ + conanfile.txt + conan/ + profiles/ + --clang + windows--clang-cross + CMakeLists.txt + CMakeUserPresets.json + build/ # 本地/CI 生成，通常不入库 +``` + +## 3. Profile 命名与含义（规范） + +- Profile 文件名按“产物平台”为前缀，避免误读： + - `linux-...`：产物平台为 Linux（`[settings] os=Linux`） + - `windows-...`：产物平台为 Windows（`[settings] os=Windows`） +- 跨编译 profile 建议以 `-cross` 结尾（例如 `windows-x86_64-clang-cross`）。 +- “工具链版本”以 profile 的 `[settings] compiler.version` 为准；如同一仓库并存多版本 clang，可将版本体现在文件名中（例如 `linux-x86_64-clang20`）。 + +## 4. 安装与构建（推荐流程） + +在项目的 C++ 根目录（例如 `cpp/`）下： + +1. 安装依赖并生成工具链文件： + - `CONAN_HOME=/tmp/conan-home conan install . -pr:b=conan/profiles/linux-x86_64-clang -pr:h=conan/profiles/windows-x86_64-clang-cross -of build/windows-x86_64-clang-cross --build=missing` + - 若有 profile：`-pr:h=conan/profiles/<...> -pr:b=conan/profiles/<...>` +2. 配置 CMake： + - 直接指定 toolchain： + - `cmake -S . -B build/clang -G Ninja -DCMAKE_TOOLCHAIN_FILE=$PWD/build/clang/Release/generators/conan_toolchain.cmake` + - 或使用 Presets（推荐，见下节）： + - `cmake --preset conan-release` +3. 构建： + - `cmake --build --preset conan-release -j 8` + +提示：如遇到 Conan 缓存/家目录权限问题，可临时设置 `CONAN_HOME=/tmp/conan-home` 再执行。 + +## 5. CMake Presets（推荐做法） + +Conan 2 可以生成 CMake Presets（通常落在 `build/<...>/generators/CMakePresets.json`）。 + +推荐将一个稳定的 `CMakeUserPresets.json` 放进仓库并 include 生成文件（参考 `tsl-devkit/lsp-server/CMakeUserPresets.json`），例如： + +```json +{ + "version": 4, + "vendor": { "conan": {} }, + "include": ["build/clang-linux/Release/generators/CMakePresets.json"] +} +``` + +这样团队/CI 就可以统一使用： + +- 配置：`cmake --preset conan-release` +- 构建：`cmake --build --preset conan-release -j 8` +- 测试：`ctest --preset conan-release --output-on-failure` + +## 6. 模板文件（本 Playbook） + +- `templates/cpp/conanfile.txt` +- `templates/cpp/CMakeUserPresets.json` +- `templates/cpp/conan/profiles/linux-x86_64-clang` +- `templates/cpp/conan/profiles/windows-x86_64-clang-cross` diff --git a/docs/cpp/naming.md b/docs/cpp/naming.md new file mode 100644 index 0000000..923011b --- /dev/null +++ b/docs/cpp/naming.md @@ -0,0 +1,31 @@ +# C++ 命名规范（Naming） + +本章节以 Google C++ Style Guide 为基线，并补充模块化（Modules）相关的命名约定。 + +## 1. 总原则 + +- 一致性优先：以仓库现有风格为准，标准用于“无上下文/新代码”的默认选择。 +- 名字体现作用域与语义，不用 `tmp/data/info` 这类弱语义词。 + +## 2. 命名风格总览（默认） + +- 类型（class/struct/enum/using）：`PascalCase` +- 函数/方法：`PascalCase` +- 变量：`lower_snake_case` +- 成员变量：`lower_snake_case_`（尾随下划线，Google） +- 常量：`kPascalCase`（编译期/全局固定值） +- 命名空间：`lowercase` 或 `lower_snake_case`（按项目约定，建议全仓统一） + +## 3. 文件命名 + +- 文件名：`lower_snake_case`（与 Google 风格一致） +- 头文件：`foo_bar.h` +- 源文件：`foo_bar.cc` +- Module 文件：`foo_bar.cppm` + +## 4. Modules 命名 + +- Module 名使用点分层级：`..` +- 每一段建议用 `lower_snake_case`： + - 示例：`my_project.market.data_feed` +- 文件路径建议与 module 名可映射（便于检索与定位）。 diff --git a/docs/cpp/toolchain.md b/docs/cpp/toolchain.md new file mode 100644 index 0000000..f7a291f --- /dev/null +++ b/docs/cpp/toolchain.md @@ -0,0 +1,80 @@ +# C++ 工具链与验证命令（模板） + +本文件提供一份**通用占位模板**，用于在不同 C++ 项目中快速补齐“工具链与如何验证”的关键上下文。 + +## 1. 工具链（必填） + +### 1.1 编译器与标准 + +- C++ 标准：C++23（含 Modules） +- 编译器： + - 目标平台：Windows（通过 Linux 交叉编译） + - 主机平台：Linux + - 工具链：`clang <版本>`（交叉编译；具体 clang 可执行路径由 Conan profile 配置） + - 目标三元组（示例）：`x86_64-w64-mingw32` / `aarch64-w64-mingw32` + +### 1.2 构建系统 + +- CMake：`>= 4.0` +- 生成器： + - Linux：`Ninja` + +### 1.3 依赖管理（Conan，推荐） + +若项目使用 Conan 管理三方依赖，建议： + +- Conan：`2.x`（本 Playbook 假设 Conan 2；不保证 Conan 1 的兼容性） +- 使用 `conanfile.txt` + `CMakeDeps` + `CMakeToolchain` + `cmake_layout`（参考 `tsl-devkit/lsp-server/conanfile.txt`）。 +- 通过 `conan install` 生成工具链与（可选）CMake Presets，再用 `cmake --preset ...` 构建。 + +### 1.4 格式化（必选） + +- `clang-format`：`<项目自选并固定版本>` +- 兼容性策略： + - `.clang-format` 是唯一真相（推荐使用 `templates/cpp/.clang-format` 落地到项目根目录）。 + - 不同版本的 `clang-format` 可能对同一配置产生不同输出；项目应在 CI/开发环境中固定版本，避免格式漂移。 + - CI 推荐用 `clang-format --dry-run --Werror ` 做格式校验。 + +### 1.5 静态检查（暂不启用） + +- `clang-tidy`：暂不启用（若未来启用，写明版本、配置文件与运行命令） + +## 2. 验证命令（必填：把占位符替换成真实命令） + +### 2.1 最小构建（必须能跑） + +- Conan 生成（推荐，示例）： + - `CONAN_HOME=/tmp/conan-home conan install . -pr:b=conan/profiles/linux-x86_64-clang -pr:h=conan/profiles/windows-x86_64-clang-cross -of build/windows-x86_64-clang-cross --build=missing` +- 配置（示例）： + - `cmake --preset conan-release` +- 构建（示例）： + - `cmake --build --preset conan-release -j 8` + +### 2.2 运行冒烟（建议） + +- `build/ ` +- 或：`cmake --build build -t run_smoke`（如项目提供自定义 target） + +### 2.3 格式化检查（建议） + +- `clang-format -i `（本地） +- `clang-format --dry-run --Werror `（CI） + +### 2.4 失败处理约定（必填） + +- 只修复与本次改动直接相关的失败；无关失败记录并隔离。 +- 若某步骤无法执行（缺环境/缺权限），必须写出原因与替代验证（例如手动检查清单/最小复现工程）。 + +## 3. Presets（可选但强烈推荐） + +参考 `tsl-devkit` 的做法： + +- 将 `CMakeUserPresets.json` 纳入版本控制，并 `include` Conan 生成的 `build/.../generators/CMakePresets.json`。 +- 优点：统一 Windows/Linux/macOS 构建入口；Agent 也更容易用固定命令验证。 + +本 Playbook 约定： + +- **强制统一 preset 名称**：`conan-release` / `conan-debug`（项目必须提供这两个 preset；实现方式不限：可由 Conan 生成，也可由项目自建 `CMakePresets.json` 适配）。 +- `CMakeUserPresets.json` 不是强制标准，仅作为一种推荐落地方式（模板见 `templates/cpp/CMakeUserPresets.json`）。 + +不在本 Playbook 中强制规定工具链分发方式（例如某种特定打包形态）；只要求把交叉编译所需的 `compiler_executables`、triplet、system_name 等写进 Conan profile，保证命令可复现。 diff --git a/docs/index.md b/docs/index.md index 3101a0b..5960860 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,3 +11,18 @@ - TSL 源文件后缀同时包含：`.tsl`（脚本）与 `.tsf`（模块/库代码）。 - 代码风格：`tsl/code_style.md` - 命名规范：`tsl/naming.md` +- 工具链与验证命令（模板）：`tsl/toolchain.md` + +## C++（cpp） + +- 代码风格：`cpp/code_style.md` +- 命名规范：`cpp/naming.md` +- 工具链与验证命令（模板）：`cpp/toolchain.md` +- 第三方依赖（Conan）：`cpp/dependencies_conan.md` +- clangd 配置：`cpp/clangd.md` + +## Python（python） + +- 代码风格：`python/style_guide.md` +- 工具链：`python/tooling.md` +- 配置清单：`python/configuration.md` diff --git a/docs/python/configuration.md b/docs/python/configuration.md new file mode 100644 index 0000000..069ddd5 --- /dev/null +++ b/docs/python/configuration.md @@ -0,0 +1,65 @@ +# Python 配置清单（Configuration） + +本文件用于把 Python 工具配置“汇总说明”到一个可读入口。 + +注意：本 Playbook 将可复制模板放在 `templates/python/`；在目标项目落地时，这些文件通常需要复制到**项目根目录**（工具默认查找位置）： + +- `pyproject.toml` +- `.flake8` +- `.pylintrc` +- `.pre-commit-config.yaml` +- `.editorconfig` +- `.vscode/settings.json` + +## 1) `pyproject.toml` + +模板文件：`templates/python/pyproject.toml` + +- `tool.black` + - `line-length = 80` + - `target-version = ['py313']`（按项目 Python 版本调整） +- `tool.isort` + - `profile = "google"` + - `line_length = 80` + - `known_third_party` / `known_first_party`：按项目维护 +- `tool.mypy` + - `python_version = "3.13"`（按项目调整） + - `ignore_missing_imports = true`（对第三方二进制/无类型库更友好） +- `tool.pytest.ini_options` + - 测试发现与参数（若项目引入 `tests/` 会自动生效） + +## 2) `.flake8` + +模板文件：`templates/python/.flake8` + +- `max-line-length = 80` +- `docstring-convention = google` +- 与 `black` 冲突的规则已屏蔽（例如 `E203`、`W503`） + +## 3) `.pylintrc` + +模板文件：`templates/python/.pylintrc` + +- 命名风格：snake_case / PascalCase 等（对齐 Google Python 风格） +- `max-line-length = 80` +- `init-hook` 将项目根目录加入 `sys.path`（便于本地运行与检查；如项目不需要可移除） + +## 4) `.pre-commit-config.yaml` + +模板文件：`templates/python/.pre-commit-config.yaml` + +- 基础文本检查：尾随空格、文件末尾换行、YAML/TOML 基础校验 +- Python：`black`、`isort`、`flake8` + +## 5) `.editorconfig` + +模板文件：`templates/python/.editorconfig` + +- Python：4 空格缩进、行宽 80 +- 通用：UTF-8、LF、去尾随空格、文件末尾换行 + +## 6) `.vscode/settings.json` + +模板文件：`templates/python/.vscode/settings.json` + +- 保存即格式化、80 列标尺、默认使用 Black formatter、按需组织 import diff --git a/docs/python/style_guide.md b/docs/python/style_guide.md new file mode 100644 index 0000000..4fbcad8 --- /dev/null +++ b/docs/python/style_guide.md @@ -0,0 +1,14 @@ +# Python 代码风格（Google Python Style Guide） + +本 Playbook 的 Python 代码风格以 Google Python Style Guide 为基线（基于 PEP 8）： + +- Google Python Style Guide: https://google.github.io/styleguide/pyguide.html +- PEP 8: https://peps.python.org/pep-0008/ + +## 项目约定（Project Conventions） + +- 行宽：80（与 `black`/`flake8`/`pylint` 配置保持一致） +- docstring：Google 风格（与 `.flake8` 的 `docstring-convention = google` 对齐） +- import 顺序：使用 `isort` 的 `profile = google` + +当既有代码与本约定冲突时，优先保持局部一致性，逐步迁移。 diff --git a/docs/python/tooling.md b/docs/python/tooling.md new file mode 100644 index 0000000..38ce884 --- /dev/null +++ b/docs/python/tooling.md @@ -0,0 +1,36 @@ +# Python 工具链（Tooling） + +本 Playbook 推荐用以下工具保证代码一致性与质量： + +- `black`：格式化（行宽 80） +- `isort`：import 排序（Google profile） +- `flake8`：风格检查 + docstring 约定 +- `pylint`：静态检查（以 `.pylintrc` 为准，可按项目调整） +- `mypy`：类型检查（可选） +- `pytest`：测试（可选） +- `pre-commit`：在 `git commit` 前自动运行上述检查/格式化（可选，但推荐） + +## 常用命令（示例） + +安装工具（示例，按项目实际依赖管理方式调整）： + +```bash +python -m pip install black isort flake8 pylint mypy pytest pre-commit +``` + +格式化与检查（示例）： + +```bash +black . +isort . +flake8 . +pylint . +mypy . +pytest +``` + +启用 `pre-commit`（只需一次）： + +```bash +pre-commit install +``` diff --git a/docs/tsl/naming.md b/docs/tsl/naming.md index e9e5093..17ce989 100644 --- a/docs/tsl/naming.md +++ b/docs/tsl/naming.md @@ -24,7 +24,6 @@ - 所有语法关键字统一使用全小写书写，例如 `if`、`for`、`class`、`function`、`unit`、`return` 等。 - 调用内置/标准库方法时，推荐保持官方大小写形式（`aaBBCC`/lowerCamelCase），例如 `getSysParams("xxx")`。 - ## 3. 类型命名（Type Names） TSL 的顶层声明只有三种：`class`、`unit`、`function`。 diff --git a/docs/tsl/toolchain.md b/docs/tsl/toolchain.md new file mode 100644 index 0000000..4047bfc --- /dev/null +++ b/docs/tsl/toolchain.md @@ -0,0 +1,62 @@ +# TSL 工具链与验证命令（模板） + +本文件提供一份**通用占位模板**，用于在不同 TSL 项目中快速补齐“工具链与如何验证”的关键上下文。 + +使用方式： + +- 在具体项目中复制本模板并把占位符替换为真实信息； +- 或在项目文档中引用本模板，并在项目内提供对应的 `scripts/*` 统一入口脚本。 + +## 1. TSL 工具链 + +### 1.1 解释器/编译器（必填） + +- 工具名称：`` +- 可执行命令： + - macOS/Linux：``（例：`tsl` / `tslcli` / `sh scripts/tsl.sh`） + - Windows：``（例：`tsl.exe` / `tslcli.exe` / `powershell -File scripts/tsl.ps1`） +- 版本要求：`<固定版本或范围，例如：= 3.2.1 / >=3.2,<4.0>` +- 安装方式：`<内部安装包/路径/IDE 自带/CI 镜像等>` +- 推荐统一入口脚本：`scripts/tsl.{sh,ps1}`（封装参数与环境变量，避免每个任务重复猜测） + +### 1.2 运行环境（按需） + +- 必要环境变量：` ...` +- 外部依赖：`<数据库/服务/共享目录/网络权限/账户权限>` +- 运行约束： + - 是否允许联网：`` + - 是否需要许可证/凭证：`<说明如何在本地与 CI 提供；禁止写入仓库>` + +## 2. 验证命令 + +> 要求：改动完成后至少能跑通“最小冒烟”；若项目存在测试体系，尽量补到对应层级。 + +### 2.1 最小冒烟（必须能跑） + +- macOS/Linux：` run -- ` +- Windows：` run -- ` +- 或统一入口： + - `sh scripts/smoke.sh` + - `powershell -File scripts/smoke.ps1` + +### 2.2 单元测试（如有） + +- `sh scripts/test.sh` +- 或：` test ` +- 或：` run ` + +### 2.3 静态检查/格式化（如有） + +- `sh scripts/lint.sh` +- `sh scripts/format.sh` +- 或：` check ` / ` fmt ` + +### 2.4 构建/打包（如有） + +- `sh scripts/build.sh` +- 或：` build ` + +### 2.5 失败处理约定（必填） + +- 只修复与本次改动直接相关的失败；无关失败在输出中说明并隔离。 +- 若某验证步骤无法执行（缺环境/缺凭证），必须明确写出原因与替代验证手段（例如最小复现脚本/手动检查清单）。 diff --git a/scripts/sync_standards.bat b/scripts/sync_standards.bat index e8b53fc..48877ce 100644 --- a/scripts/sync_standards.bat +++ b/scripts/sync_standards.bat @@ -2,9 +2,14 @@ setlocal enabledelayedexpansion rem Sync standards snapshot to project root. -rem - Copies \.agents -> \.agents\tsl +rem - Copies \.agents\ -> \.agents\ rem - Updates \.gitattributes (managed block by default) rem Existing targets are backed up before overwrite. +rem +rem Multi rulesets: +rem sync_standards.bat tsl cpp +rem Notes: +rem - When syncing multiple rulesets, .gitattributes is synced only once (first ruleset). set "SCRIPT_DIR=%~dp0" for /f "delims=" %%R in ('git -C "%SCRIPT_DIR%" rev-parse --show-toplevel 2^>nul') do set "ROOT=%%R" @@ -12,7 +17,7 @@ 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=%SRC%\.agents" +set "AGENTS_SRC_ROOT=%SRC%\.agents" set "GITATTR_SRC=%SRC%\.gitattributes" set "AGENTS_NS=%AGENTS_NS%" if "%AGENTS_NS%"=="" set "AGENTS_NS=tsl" @@ -30,9 +35,43 @@ set "GITATTR_DST=%ROOT%\.gitattributes" set "SYNC_GITATTR_MODE=%SYNC_GITATTR_MODE%" if "%SYNC_GITATTR_MODE%"=="" set "SYNC_GITATTR_MODE=block" +rem Multi rulesets: only on outer invocation. +if "%SYNC_STANDARDS_INNER%"=="" ( + if not "%~1"=="" ( + set "FIRST=1" + set "SYNC_FIRST=%SYNC_GITATTR_MODE%" + for %%L in (%*) do ( + if "!FIRST!"=="1" ( + set "FIRST=0" + set "SYNC_STANDARDS_INNER=1" + set "AGENTS_NS=%%~L" + set "SYNC_GITATTR_MODE=!SYNC_FIRST!" + call "%~f0" + ) else ( + set "SYNC_STANDARDS_INNER=1" + set "AGENTS_NS=%%~L" + set "SYNC_GITATTR_MODE=skip" + call "%~f0" + ) + ) + exit /b 0 + ) +) + +set "AGENTS_SRC=%AGENTS_SRC_ROOT%\%AGENTS_NS%" +if not exist "%AGENTS_SRC%" ( + rem Backward-compatible fallback: older snapshots used \.agents\* directly. + if exist "%AGENTS_SRC_ROOT%\index.md" if exist "%AGENTS_SRC_ROOT%\auth.md" ( + set "AGENTS_SRC=%AGENTS_SRC_ROOT%" + ) else ( + echo ERROR: Standards snapshot not found at "%AGENTS_SRC%". + echo Hint: set AGENTS_NS to one of the subdirs under "%AGENTS_SRC_ROOT%" (e.g. tsl/cpp). + exit /b 1 + ) +) if not exist "%AGENTS_SRC%" ( echo ERROR: Standards snapshot not found at "%AGENTS_SRC%". - echo Run: git subtree add --prefix ^ ^ ^ --squash + echo Run: git subtree add --prefix docs/standards/playbook ^ ^ --squash exit /b 1 ) @@ -67,14 +106,16 @@ if not exist "%AGENTS_ROOT%\index.md" ( >> "%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/`、`.agents/python/` 等：其他语言的规则集（按需增加） + >> "%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 - `docs/standards/tsl/docs/tsl/`（TSL 人类开发规范快照，推荐 subtree/vendoring 到该路径） + >> "%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 ) @@ -110,8 +151,10 @@ if exist "%GITATTR_SRC%" ( ) rem block mode: maintain a managed block inside the destination file - set "BEGIN=# BEGIN tsl-playbook .gitattributes" - set "END=# END tsl-playbook .gitattributes" + 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%" ( @@ -139,8 +182,18 @@ if exist "%GITATTR_SRC%" ( 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! ) diff --git a/scripts/sync_standards.ps1 b/scripts/sync_standards.ps1 index ffd72da..3c5c8c3 100644 --- a/scripts/sync_standards.ps1 +++ b/scripts/sync_standards.ps1 @@ -1,9 +1,17 @@ # Sync standards snapshot to project root. -# - Copies /.agents -> /.agents/tsl +# - Copies /.agents/ -> /.agents/ # - Updates /.gitattributes (managed block by default) # Existing targets are backed up before overwrite. -$ErrorActionPreference = "Stop" +[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 @@ -11,20 +19,60 @@ $Root = (git -C $ScriptDir rev-parse --show-toplevel 2>$null) if (-not $Root) { $Root = (Get-Location).Path } $Root = (Resolve-Path $Root).Path -$AgentsSrc = Join-Path $Src ".agents" +$AgentsSrcRoot = Join-Path $Src ".agents" $GitAttrSrc = Join-Path $Src ".gitattributes" -if (-not (Test-Path $AgentsSrc)) { - throw "Standards snapshot not found at $AgentsSrc. Run git subtree add first (choose any prefix)." +if (-not (Test-Path $AgentsSrcRoot)) { + throw "Standards snapshot not found at $AgentsSrcRoot. Run: git subtree add --prefix docs/standards/playbook --squash" } $timestamp = Get-Date -Format "yyyyMMddHHmmss" +# Multi rulesets: only on the outer invocation. +if (-not $env:SYNC_STANDARDS_INNER -and $Langs -and $Langs.Count -gt 0) { + $oldInner = $env:SYNC_STANDARDS_INNER + $oldAgentsNs = $env:AGENTS_NS + $oldMode = $env:SYNC_GITATTR_MODE + + $syncModeFirst = $env:SYNC_GITATTR_MODE + if (-not $syncModeFirst) { $syncModeFirst = "block" } + + $first = $true + foreach ($ns in $Langs) { + if (-not $ns) { continue } + + $env:SYNC_STANDARDS_INNER = "1" + $env:AGENTS_NS = $ns + if ($first) { + $first = $false + $env:SYNC_GITATTR_MODE = $syncModeFirst + } else { + $env:SYNC_GITATTR_MODE = "skip" + } + + & $MyInvocation.MyCommand.Path + } + + $env:SYNC_STANDARDS_INNER = $oldInner + $env:AGENTS_NS = $oldAgentsNs + $env:SYNC_GITATTR_MODE = $oldMode + exit 0 +} + $AgentsNs = $env:AGENTS_NS if (-not $AgentsNs) { $AgentsNs = "tsl" } if ($AgentsNs -match '[\\/]' -or $AgentsNs -match '\.\.') { throw "Invalid AGENTS_NS=$AgentsNs" } +$AgentsSrc = Join-Path $AgentsSrcRoot $AgentsNs +if (-not (Test-Path $AgentsSrc)) { + # Backward-compatible fallback: older snapshots used /.agents/* directly. + if ((Test-Path (Join-Path $AgentsSrcRoot "index.md")) -and (Test-Path (Join-Path $AgentsSrcRoot "auth.md"))) { + $AgentsSrc = $AgentsSrcRoot + } else { + throw "Agents ruleset not found: $AgentsSrc (set AGENTS_NS to one of the subdirs under $AgentsSrcRoot, e.g. tsl/cpp)." + } +} $AgentsRoot = Join-Path $Root ".agents" $AgentsDst = Join-Path $AgentsRoot $AgentsNs @@ -56,14 +104,16 @@ if (-not (Test-Path $AgentsIndex)) { 建议约定： - `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`） -- `.agents/cpp/`、`.agents/python/` 等：其他语言的规则集（按需增加） +- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules） +- `.agents/python/` 等：其他语言的规则集（按需增加） 规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。 入口建议从： - `.agents/tsl/index.md`（TSL 规则集入口） -- `docs/standards/tsl/docs/tsl/`（TSL 人类开发规范快照，推荐 subtree/vendoring 到该路径） +- `.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" } @@ -92,8 +142,10 @@ if (Test-Path $GitAttrSrc) { break } "block" { - $begin = "# BEGIN tsl-playbook .gitattributes" - $end = "# END tsl-playbook .gitattributes" + $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" @@ -105,7 +157,7 @@ if (Test-Path $GitAttrSrc) { $dst = Get-Content -Path $bak -Raw } - $pattern = "(?ms)^" + [regex]::Escape($begin) + "\\R.*?^" + [regex]::Escape($end) + "\\R?" + $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) { diff --git a/scripts/sync_standards.sh b/scripts/sync_standards.sh index fd16178..9a56e35 100644 --- a/scripts/sync_standards.sh +++ b/scripts/sync_standards.sh @@ -2,20 +2,26 @@ set -eu # Sync standards snapshot to project root. -# - Copies /.agents -> /.agents/tsl +# - Copies /.agents/ -> /.agents/ # - Updates /.gitattributes (managed block by default) # Existing targets are backed up before overwrite. +# +# Multi rulesets: +# sh .../sync_standards.sh tsl cpp +# sh .../sync_standards.sh --langs tsl,cpp +# Notes: +# - When syncing multiple rulesets, .gitattributes is synced only once (first ruleset). SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)" SRC="$(CDPATH= cd -- "$SCRIPT_DIR/.." && pwd -P)" ROOT="$(git -C "$SCRIPT_DIR" rev-parse --show-toplevel 2>/dev/null || pwd)" ROOT="$(CDPATH= cd -- "$ROOT" && pwd -P)" -AGENTS_SRC="$SRC/.agents" +AGENTS_SRC_ROOT="$SRC/.agents" GITATTR_SRC="$SRC/.gitattributes" -if [ ! -d "$AGENTS_SRC" ]; then - echo "ERROR: Standards snapshot not found at $AGENTS_SRC" >&2 - echo "Run: git subtree add --prefix --squash" >&2 +if [ ! -d "$AGENTS_SRC_ROOT" ]; then + echo "ERROR: Standards snapshot not found at $AGENTS_SRC_ROOT" >&2 + echo "Run: git subtree add --prefix docs/standards/playbook --squash" >&2 exit 1 fi @@ -27,6 +33,38 @@ if [ "$SRC" = "$ROOT" ]; then 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 ""|*/*|*\\*|*..*) @@ -35,6 +73,18 @@ case "$AGENTS_NS" in ;; esac +AGENTS_SRC="$AGENTS_SRC_ROOT/$AGENTS_NS" +if [ ! -d "$AGENTS_SRC" ]; then + # Backward-compatible fallback: older snapshots used /.agents/* directly. + if [ -f "$AGENTS_SRC_ROOT/index.md" ] && [ -f "$AGENTS_SRC_ROOT/auth.md" ]; then + AGENTS_SRC="$AGENTS_SRC_ROOT" + else + echo "ERROR: agents ruleset not found: $AGENTS_SRC" >&2 + echo "Hint: set AGENTS_NS to one of the subdirs under $AGENTS_SRC_ROOT (e.g. tsl/cpp)." >&2 + exit 1 + fi +fi + AGENTS_ROOT="$ROOT/.agents" AGENTS_DST="$AGENTS_ROOT/$AGENTS_NS" mkdir -p "$AGENTS_ROOT" @@ -57,14 +107,16 @@ if [ ! -f "$AGENTS_INDEX" ]; then 建议约定： - `.agents/tsl/`：TSL 相关规则集（由 `sync_standards.*` 同步；适用于 `.tsl`/`.tsf`） -- `.agents/cpp/`、`.agents/python/` 等：其他语言的规则集（按需增加） +- `.agents/cpp/`：C++ 相关规则集（由 `sync_standards.*` 同步；适用于 C++23/Modules） +- `.agents/python/` 等：其他语言的规则集（按需增加） 规则发生冲突时，建议以“更靠近代码的目录规则更具体”为准。 入口建议从： - `.agents/tsl/index.md`（TSL 规则集入口） -- `docs/standards/tsl/docs/tsl/`（TSL 人类开发规范快照，推荐 subtree/vendoring 到该路径） +- `.agents/cpp/index.md`（C++ 规则集入口） +- `docs/standards/playbook/docs/`（人类开发规范快照：`tsl/`、`cpp/`、`python/`、`common/`） EOF echo "Created .agents/index.md" fi @@ -91,8 +143,10 @@ if [ -f "$GITATTR_SRC" ]; then fi ;; block) - begin="# BEGIN tsl-playbook .gitattributes" - end="# END tsl-playbook .gitattributes" + 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" @@ -107,7 +161,7 @@ if [ -f "$GITATTR_SRC" ]; then fi if [ -n "$src_dst" ]; then - awk -v begin="$begin" -v end="$end" -v src="$GITATTR_SRC" ' + 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 @@ -115,8 +169,8 @@ if [ -f "$GITATTR_SRC" ]; then print end } BEGIN { in_block=0; done=0 } - $0 == begin { in_block=1; if (!done) { emit_src(); done=1 } ; next } - $0 == end { in_block=0; next } + $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) { diff --git a/templates/cpp/.clang-format b/templates/cpp/.clang-format new file mode 100644 index 0000000..6f94096 --- /dev/null +++ b/templates/cpp/.clang-format @@ -0,0 +1,47 @@ +--- +Language: Cpp +BasedOnStyle: Google + +# Keep consistent with the repo-wide 100 char guidance (adjust per-project if needed). +ColumnLimit: 100 + +AccessModifierOffset: -4 +AlignEscapedNewlines: Left +AlignTrailingComments: false +AllowAllParametersOfDeclarationOnNextLine: false +AllowShortFunctionsOnASingleLine: All +AlwaysBreakTemplateDeclarations: Yes +BinPackArguments: false +BinPackParameters: false +BraceWrapping: + AfterCaseLabel: true + AfterUnion: true + AfterExternBlock: false +BreakBeforeTernaryOperators: false +BreakConstructorInitializers: AfterColon +BreakInheritanceList: AfterColon +CommentPragmas: "suppress" +ConstructorInitializerAllOnOneLineOrOnePerLine: true +Cpp11BracedListStyle: false +FixNamespaceComments: false +IncludeBlocks: Regroup +IncludeCategories: + - Regex: '^.*(precomp|pch|stdafx)' + Priority: -1 + - Regex: '^".*"' + Priority: 1 + - Regex: '^<.*>' + Priority: 2 + - Regex: '.*' + Priority: 3 +KeepEmptyLinesAtTheStartOfBlocks: false +MacroBlockBegin: "BEGIN_TEST_METHOD_PROPERTIES|BEGIN_MODULE|BEGIN_TEST_CLASS|BEGIN_TEST_METHOD" +MacroBlockEnd: "END_TEST_METHOD_PROPERTIES|END_MODULE|END_TEST_CLASS|END_TEST_METHOD" +NamespaceIndentation: All +PointerAlignment: Left +ReflowComments: false +SortIncludes: false +SpaceAfterTemplateKeyword: false +SpacesInAngles: false +SpacesInContainerLiterals: false + diff --git a/templates/cpp/.clangd b/templates/cpp/.clangd new file mode 100644 index 0000000..be8b66f --- /dev/null +++ b/templates/cpp/.clangd @@ -0,0 +1,25 @@ +CompileFlags: + # Point clangd to a CMake compilation database (compile_commands.json). + # + # Recommended: keep this aligned with your Conan/CMake preset output directory. + # Example (this playbook's default cross build folder): + CompilationDatabase: build/windows-x86_64-clang-cross/Release + +--- +If: + PathMatch: [.*\\.hpp, .*\\.hxx, .*\\.cpp, .*\\.cc, .*\\.cxx, .*\\.cppm, .*\\.ixx, .*\\.mpp] + +CompileFlags: + Add: + - "-std=c++23" + Compiler: clang++ + +--- +If: + PathMatch: [.*\\.h, .*\\.c] + +CompileFlags: + Add: + - "-std=c17" + Compiler: clang + diff --git a/templates/cpp/CMakeLists.txt b/templates/cpp/CMakeLists.txt new file mode 100644 index 0000000..3aeb578 --- /dev/null +++ b/templates/cpp/CMakeLists.txt @@ -0,0 +1,26 @@ +cmake_minimum_required(VERSION 4.2) + +# Enable C++23 Modules + (optional) `import std;` with experimental std module. +set(CMAKE_EXPERIMENTAL_CXX_IMPORT_STD "d0edc3af-4c50-42ea-a356-e2862fe7a444") + +project(app LANGUAGES C CXX) + +set(CMAKE_CXX_SCAN_FOR_MODULES ON) +set(CMAKE_CXX_EXTENSIONS OFF) +set(CMAKE_CXX_STANDARD 23) +set(CMAKE_CXX_STANDARD_REQUIRED ON) +set(CMAKE_CXX_MODULE_STD 1) +set(CMAKE_EXPORT_COMPILE_COMMANDS ON) + +# Toolchain-specific flags (libc++/runtime/linker/etc) should come from your Conan toolchain/profile. + +# Example: entrypoint built from main.cc; modules live in .cppm files. +add_executable(app main.cc) + +# If you use C++ Modules, list module interface units explicitly and keep this in sync: +# +# target_sources(app +# PRIVATE +# FILE_SET cxx_modules TYPE CXX_MODULES FILES +# modules/app.cppm +# ) diff --git a/templates/cpp/CMakeUserPresets.json b/templates/cpp/CMakeUserPresets.json new file mode 100644 index 0000000..e3b2c2a --- /dev/null +++ b/templates/cpp/CMakeUserPresets.json @@ -0,0 +1,9 @@ +{ + "version": 4, + "vendor": { + "conan": {} + }, + "include": [ + "build/windows-x86_64-clang-cross/Release/generators/CMakePresets.json" + ] +} diff --git a/templates/cpp/conan/profiles/linux-x86_64-clang b/templates/cpp/conan/profiles/linux-x86_64-clang new file mode 100644 index 0000000..43901b8 --- /dev/null +++ b/templates/cpp/conan/profiles/linux-x86_64-clang @@ -0,0 +1,24 @@ +# Linux (Clang) +# +# Profile naming convention (suggested): +# linux--clang +# If the repo only supports one clang version, you may omit the suffix. + +[settings] +os=Linux +arch=x86_64 +compiler=clang +compiler.version=20 +compiler.libcxx=libc++ +compiler.cppstd=23 +build_type=Release + +[conf] +# Prefer pinning the exact compiler executables to avoid PATH drift. +tools.build:compiler_executables={"c": "/usr/bin/clang", "cpp": "/usr/bin/clang++"} +tools.cmake.cmaketoolchain:generator=Ninja + +# Keep Conan's cmake_layout output stable and predictable. +tools.cmake.cmake_layout:build_folder=. +tools.cmake.cmake_layout:build_folder_vars=[] + diff --git a/templates/cpp/conan/profiles/windows-x86_64-clang-cross b/templates/cpp/conan/profiles/windows-x86_64-clang-cross new file mode 100644 index 0000000..b1058ff --- /dev/null +++ b/templates/cpp/conan/profiles/windows-x86_64-clang-cross @@ -0,0 +1,38 @@ +# Windows target cross (Clang) from Linux host +# +# IMPORTANT: +# - This profile describes the *output platform* (target), so [settings] os=Windows. +# - Use a "windows-..." prefix to avoid misleading readers into thinking the output is Linux. +# +# Profile naming convention (suggested): +# windows--clang-cross + +[settings] +os=Windows +arch=x86_64 +compiler=clang +compiler.version=20 +compiler.runtime=static +compiler.libcxx=libc++ +compiler.cppstd=23 +build_type=Release + +[conf] +# Configure your cross clang executables here (do NOT hardcode a specific distro name in docs). +tools.build:compiler_executables={"c": "/bin/x86_64-w64-mingw32-clang", "cpp": "/bin/x86_64-w64-mingw32-clang++"} + +# Tell Conan/CMake the target triple and platform. +tools.gnu:host_triplet=x86_64-w64-mingw32 +tools.cmake.cmaketoolchain:generator=Ninja +tools.cmake.cmaketoolchain:system_name=Windows +tools.cmake.cmaketoolchain:system_processor=x86_64 +tools.cmake.cmaketoolchain:system_version=11 + +# Keep Conan's cmake_layout output stable and predictable. +tools.cmake.cmake_layout:build_folder=. +tools.cmake.cmake_layout:build_folder_vars=[] + +[buildenv] +# Resource compiler (optional; adjust if your toolchain uses a different windres name/path). +RC=x86_64-w64-mingw32-windres + diff --git a/templates/cpp/conanfile.txt b/templates/cpp/conanfile.txt new file mode 100644 index 0000000..bc8190e --- /dev/null +++ b/templates/cpp/conanfile.txt @@ -0,0 +1,25 @@ +[requires] +# 本仓库是“模板/标准”仓库：默认不内置任何依赖版本。 +# 在具体项目中按需添加，并由项目自行锁版本（建议配合 lockfile / 版本策略）。 +# +# 示例（请按项目实际替换/增删）： +# fmt/12.0.0 +# spdlog/1.16.0 + +[generators] +CMakeDeps +CMakeToolchain + +[options] +# 示例（请按项目实际替换/增删）： +# spdlog/*:header_only=True +# fmt/*:header_only=True + +[layout] +cmake_layout + +# 参考命令（按项目 profile/路径调整）： +# CONAN_HOME=/tmp/conan-home conan install . -pr:b=conan/profiles/linux-x86_64-clang -pr:h=conan/profiles/windows-x86_64-clang-cross -of build/windows-x86_64-clang-cross --build=missing +# cmake --preset conan-release +# cmake --build --preset conan-release -j 8 +# ctest --preset conan-release --output-on-failure diff --git a/templates/python/.editorconfig b/templates/python/.editorconfig new file mode 100644 index 0000000..52910a3 --- /dev/null +++ b/templates/python/.editorconfig @@ -0,0 +1,26 @@ +# EditorConfig is awesome: https://EditorConfig.org +root = true + +[*] +charset = utf-8 +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true + +[*.py] +indent_style = space +indent_size = 4 +max_line_length = 80 + +[*.md] +max_line_length = off +trim_trailing_whitespace = false + +[*.{yml,yaml}] +indent_style = space +indent_size = 2 + +[*.json] +indent_style = space +indent_size = 2 + diff --git a/templates/python/.flake8 b/templates/python/.flake8 new file mode 100644 index 0000000..88b1ced --- /dev/null +++ b/templates/python/.flake8 @@ -0,0 +1,27 @@ +[flake8] +# 最大行长度（Google Style Guide 推荐 80） +max-line-length = 80 + +# 忽略的错误代码（与 black 等工具对齐） +ignore = + E203, # whitespace before ':' (与 black 冲突) + W503, # line break before binary operator (已过时的规则) + +exclude = + .git, + __pycache__, + .venv, + venv, + build, + dist, + *.egg-info, + .tox, + .pytest_cache + +max-complexity = 10 +show-source = True +show-pep8 = True +count = True + +docstring-convention = google + diff --git a/templates/python/.pre-commit-config.yaml b/templates/python/.pre-commit-config.yaml new file mode 100644 index 0000000..ac7b844 --- /dev/null +++ b/templates/python/.pre-commit-config.yaml @@ -0,0 +1,25 @@ +repos: + - repo: https://github.com/pre-commit/pre-commit-hooks + rev: v4.6.0 + hooks: + - id: end-of-file-fixer + - id: trailing-whitespace + - id: check-yaml + - id: check-toml + + - repo: https://github.com/psf/black + rev: 23.3.0 + hooks: + - id: black + args: ["--line-length", "80"] + + - repo: https://github.com/PyCQA/isort + rev: 5.12.0 + hooks: + - id: isort + + - repo: https://github.com/PyCQA/flake8 + rev: 6.0.0 + hooks: + - id: flake8 + diff --git a/templates/python/.pylintrc b/templates/python/.pylintrc new file mode 100644 index 0000000..d186d47 --- /dev/null +++ b/templates/python/.pylintrc @@ -0,0 +1,64 @@ +[MASTER] +jobs=0 +ignore=CVS,.git,__pycache__,.venv,venv +init-hook='import sys; sys.path.append(".")' + +[MESSAGES CONTROL] +disable= + C0103, # 变量名不符合命名规范（允许简短的变量名） + C0114, # 缺少模块文档字符串 + R0913, # 参数过多 + R0902, # 实例属性过多 + W0511, # TODO 注释 + +enable= + E, + W, + +[REPORTS] +output-format=colorized +reports=no + +[BASIC] +argument-naming-style=snake_case +attr-naming-style=snake_case +class-attribute-naming-style=any +class-naming-style=PascalCase +const-naming-style=UPPER_CASE +function-naming-style=snake_case +method-naming-style=snake_case +module-naming-style=snake_case +variable-naming-style=snake_case + +good-names=i,j,k,ex,Run,_,x,y,z,fd,id +docstring-min-length=5 + +[FORMAT] +max-line-length=80 +max-module-lines=1000 +indent-string=' ' +indent-after-paren=4 + +[DESIGN] +max-args=7 +max-attributes=10 +max-branches=15 +max-locals=20 +max-returns=6 +max-statements=50 +min-public-methods=1 + +[IMPORTS] +import-graph= +ext-import-graph= +int-import-graph= + +[CLASSES] +valid-metaclass-classmethod-first-arg=cls +valid-classmethod-first-arg=cls + +[EXCEPTIONS] +overgeneral-exceptions= + builtins.BaseException, + builtins.Exception + diff --git a/templates/python/.vscode/settings.json b/templates/python/.vscode/settings.json new file mode 100644 index 0000000..40df514 --- /dev/null +++ b/templates/python/.vscode/settings.json @@ -0,0 +1,14 @@ +{ + "editor.formatOnSave": true, + "editor.rulers": [80], + "[python]": { + "editor.defaultFormatter": "ms-python.black-formatter", + "editor.codeActionsOnSave": { + "source.organizeImports": "explicit" + } + }, + "python.analysis.typeCheckingMode": "basic", + "python.analysis.autoImportCompletions": true, + "python.formatting.provider": "none" +} + diff --git a/templates/python/pyproject.toml b/templates/python/pyproject.toml new file mode 100644 index 0000000..fbe032d --- /dev/null +++ b/templates/python/pyproject.toml @@ -0,0 +1,51 @@ +[tool.black] +# Black 代码格式化工具配置（模板） +line-length = 80 +target-version = ["py313"] +exclude = ''' +/( + \.git + | \.venv + | venv + | build + | dist + | __pycache__ + | \.egg-info +)/ +''' + +[tool.isort] +# isort 导入排序工具配置（模板） +profile = "google" +line_length = 80 +multi_line_output = 3 +lines_after_imports = 2 + +# 按项目需要填写/维护： +known_third_party = [] +known_first_party = [] + +skip = [".venv", "venv", "build", "dist"] + +[tool.mypy] +# MyPy 类型检查配置（可选，模板） +python_version = "3.13" +warn_unused_ignores = true +warn_redundant_casts = true +warn_return_any = true +disallow_untyped_defs = false +disallow_untyped_calls = false +ignore_missing_imports = true + +[tool.pytest.ini_options] +# pytest 测试配置（模板） +testpaths = ["tests"] +python_files = ["test_*.py", "*_test.py"] +python_classes = ["Test*"] +python_functions = ["test_*"] +addopts = "-v --tb=short --strict-markers" +markers = [ + "slow: marks tests as slow", + "integration: marks tests as integration tests", +] +