📝 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).
2025-12-14 17:32:50 +08:00
parent 380228caca
commit e504a689dc
47 changed files with 1521 additions and 162 deletions
@@ -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",
+]
+