📝 docs(playbook): add contributing and multi-language standards
Introduce C++ and Python docs/templates and split .agents rulesets by language (tsl/cpp/python). Move commit message guidance to CONTRIBUTING.md (full spec remains in docs/common/commit_message.md).
This commit is contained in:
parent
380228caca
commit
e504a689dc
|
|
@ -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,26 @@
|
|||
# 测试（Testing）
|
||||
|
||||
本文件定义代理在改动代码时的测试策略与要求。
|
||||
|
||||
## 1. 测试层级
|
||||
|
||||
- **单元测试**：验证函数/模块的独立行为。
|
||||
- **集成测试**：验证模块间交互与关键流程。
|
||||
- **回归测试**：防止已修复问题复发。
|
||||
|
||||
## 2. 何时补测试
|
||||
|
||||
- 新功能必须新增对应测试（若项目有测试体系）。
|
||||
- 修复 bug 必须先写/补回归用例（若项目有测试体系）。
|
||||
- 仅当改动纯文档/注释/格式时可不加测试。
|
||||
|
||||
## 3. 测试可维护性
|
||||
|
||||
- 一个用例只验证一个行为点。
|
||||
- 测试命名清晰，能从名字看出期望。
|
||||
- 避免依赖外部不稳定资源；必要时 mock/stub。
|
||||
|
||||
## 4. 运行与失败处理
|
||||
|
||||
- 若项目提供构建/冒烟命令（CMake），优先保证最小构建可通过。
|
||||
- 失败时优先定位改动相关原因，不修无关失败。
|
||||
|
|
@ -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/<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 ...`。
|
||||
|
|
@ -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 变更要显式说明影响与迁移方式。
|
||||
|
||||
|
|
@ -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. 验证
|
||||
|
||||
- 提供优化前后可复现的对比数据（基准、采样结果或压测报告）。
|
||||
- 若无测试体系，至少提供最小可运行的复现脚本/步骤。
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -0,0 +1,7 @@
|
|||
# Contributing
|
||||
|
||||
## Commit messages
|
||||
|
||||
Follow the repository commit message standard:
|
||||
|
||||
- `docs/common/commit_message.md`
|
||||
132
README.md
132
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/<lang>/`、更新 `.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/<lang>/` 与 `.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_NS>/`（默认 `.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>/` |
|
||||
| `AGENTS_NS` | `tsl` | 同步的规则集名/落地目录名：`.agents/<AGENTS_NS>/`（例如 `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/<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`）。
|
||||
|
||||
## 版本与贡献
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
|
|||
|
|
@ -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，保证命令可复现。
|
||||
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -24,7 +24,6 @@
|
|||
- 所有语法关键字统一使用全小写书写，例如 `if`、`for`、`class`、`function`、`unit`、`return` 等。
|
||||
- 调用内置/标准库方法时，推荐保持官方大小写形式（`aaBBCC`/lowerCamelCase），例如 `getSysParams("xxx")`。
|
||||
|
||||
|
||||
## 3. 类型命名（Type Names）
|
||||
|
||||
TSL 的顶层声明只有三种：`class`、`unit`、`function`。
|
||||
|
|
|
|||
|
|
@ -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 失败处理约定（必填）
|
||||
|
||||
- 只修复与本次改动直接相关的失败；无关失败在输出中说明并隔离。
|
||||
- 若某验证步骤无法执行（缺环境/缺凭证），必须明确写出原因与替代验证手段（例如最小复现脚本/手动检查清单）。
|
||||
|
|
@ -2,9 +2,14 @@
|
|||
setlocal enabledelayedexpansion
|
||||
|
||||
rem Sync standards snapshot to project root.
|
||||
rem - Copies <snapshot>\.agents -> <project-root>\.agents\tsl
|
||||
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"
|
||||
|
|
@ -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 <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 ^<your-prefix^> ^<standards-url^> ^<branch^> --squash
|
||||
echo Run: git subtree add --prefix docs/standards/playbook ^<standards-url^> ^<branch^> --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!
|
||||
)
|
||||
|
|
|
|||
|
|
@ -1,9 +1,17 @@
|
|||
# Sync standards snapshot to project root.
|
||||
# - Copies <snapshot>/.agents -> <project-root>/.agents/tsl
|
||||
# - 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.
|
||||
$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 <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
|
||||
|
||||
|
|
@ -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) {
|
||||
|
|
|
|||
|
|
@ -2,20 +2,26 @@
|
|||
set -eu
|
||||
|
||||
# Sync standards snapshot to project root.
|
||||
# - Copies <snapshot>/.agents -> <project-root>/.agents/tsl
|
||||
# - 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="$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 <your-prefix> <standards-url> <branch> --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 <standards-url> <branch> --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 <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"
|
||||
|
|
@ -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) {
|
||||
|
|
|
|||
|
|
@ -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