From 13a1072c6fa2f0ab29bdcca4cda4fcdd04f159fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?so=E9=99=88?= Date: Fri, 20 Feb 2026 23:53:48 +0800 Subject: [PATCH] Sikuwa first commit --- .gitee/pipelines/ci.yml | 44 + .github/CODEOWNERS | 32 + .github/ISSUE_TEMPLATE/bug_report.md | 61 ++ .github/ISSUE_TEMPLATE/feature_request.md | 51 + .github/PULL_REQUEST_TEMPLATE.md | 89 ++ .github/workflows/ci.yml | 75 ++ .github/workflows/docs.yml | 39 + .gitignore | 59 + CHANGELOG.md | 184 ++++ CONTRIBUTING.md | 450 ++++++++ LICENSE | 675 ++++++++++++ LICENSE.CHINESE | 56 + README.md | 496 +++++++++ README_GITEE.md | 462 ++++++++ SECURITY.md | 78 ++ __init__.py | 8 + __main__.py | 24 + babel.cfg | 8 + builder.py | 1192 +++++++++++++++++++++ cli.py | 829 ++++++++++++++ compile_translations.py | 14 + compiler.py | 771 +++++++++++++ config.py | 528 +++++++++ cpp_cache/CMakeLists.txt | 37 + cpp_cache/__init__.py | 241 +++++ cpp_cache/pysmartcache.cpp | 80 ++ cpp_cache/pysmartcache_minimal.cpp | 150 +++ cpp_cache/pysmartcache_simple.cpp | 221 ++++ cpp_cache/setup.py | 30 + cpp_cache/smart_cache.cpp | 393 +++++++ cpp_cache/smart_cache.h | 153 +++ cpp_cache/smart_cache_minimal.cpp | 69 ++ cpp_cache/smart_cache_minimal.h | 46 + cpp_cache/smart_cache_simple.cpp | 214 ++++ cpp_cache/smart_cache_simple.h | 77 ++ i18n.py | 77 ++ i18n/__init__.py | 34 + i18n/locales/en_US/LC_MESSAGES/sikuwa.mo | Bin 0 -> 4111 bytes i18n/locales/en_US/LC_MESSAGES/sikuwa.po | 210 ++++ i18n/sikuwa.pot | 211 ++++ incremental/__init__.py | 84 ++ incremental/analyzer.py | 396 +++++++ incremental/compiler_integration.py | 322 ++++++ incremental/core.py | 778 ++++++++++++++ incremental/cpp/CMakeLists.txt | 45 + incremental/cpp/incremental_core.cpp | 777 ++++++++++++++ incremental/cpp/incremental_core.h | 283 +++++ incremental/cpp/pybind_incremental.cpp | 130 +++ incremental/demo.py | 295 +++++ incremental/smart_cache.py | 556 ++++++++++ incremental/tests/__init__.py | 2 + incremental/tests/test_incremental.py | 360 +++++++ log.py | 491 +++++++++ nuitka_loader.py | 68 ++ parser.py | 317 ++++++ sikuwa.toml | 47 + sikuwa_native_example.toml | 100 ++ 57 files changed, 13519 insertions(+) create mode 100644 .gitee/pipelines/ci.yml create mode 100644 .github/CODEOWNERS create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/ci.yml create mode 100644 .github/workflows/docs.yml create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 LICENSE.CHINESE create mode 100644 README.md create mode 100644 README_GITEE.md create mode 100644 SECURITY.md create mode 100644 __init__.py create mode 100644 __main__.py create mode 100644 babel.cfg create mode 100644 builder.py create mode 100644 cli.py create mode 100644 compile_translations.py create mode 100644 compiler.py create mode 100644 config.py create mode 100644 cpp_cache/CMakeLists.txt create mode 100644 cpp_cache/__init__.py create mode 100644 cpp_cache/pysmartcache.cpp create mode 100644 cpp_cache/pysmartcache_minimal.cpp create mode 100644 cpp_cache/pysmartcache_simple.cpp create mode 100644 cpp_cache/setup.py create mode 100644 cpp_cache/smart_cache.cpp create mode 100644 cpp_cache/smart_cache.h create mode 100644 cpp_cache/smart_cache_minimal.cpp create mode 100644 cpp_cache/smart_cache_minimal.h create mode 100644 cpp_cache/smart_cache_simple.cpp create mode 100644 cpp_cache/smart_cache_simple.h create mode 100644 i18n.py create mode 100644 i18n/__init__.py create mode 100644 i18n/locales/en_US/LC_MESSAGES/sikuwa.mo create mode 100644 i18n/locales/en_US/LC_MESSAGES/sikuwa.po create mode 100644 i18n/sikuwa.pot create mode 100644 incremental/__init__.py create mode 100644 incremental/analyzer.py create mode 100644 incremental/compiler_integration.py create mode 100644 incremental/core.py create mode 100644 incremental/cpp/CMakeLists.txt create mode 100644 incremental/cpp/incremental_core.cpp create mode 100644 incremental/cpp/incremental_core.h create mode 100644 incremental/cpp/pybind_incremental.cpp create mode 100644 incremental/demo.py create mode 100644 incremental/smart_cache.py create mode 100644 incremental/tests/__init__.py create mode 100644 incremental/tests/test_incremental.py create mode 100644 log.py create mode 100644 nuitka_loader.py create mode 100644 parser.py create mode 100644 sikuwa.toml create mode 100644 sikuwa_native_example.toml diff --git a/.gitee/pipelines/ci.yml b/.gitee/pipelines/ci.yml new file mode 100644 index 0000000..becd7ae --- /dev/null +++ b/.gitee/pipelines/ci.yml @@ -0,0 +1,44 @@ +# Gitee Go 流水线配置 +# 文档: https://gitee.com/help/articles/4295 + +name: gitee-go-pipeline + +displayName: 'Sikuwa CI Pipeline' + +triggers: + push: + - matchType: BRANCH + branch: master + - matchType: BRANCH + branch: develop + pull_request: + - matchType: BRANCH + branch: master + +stages: + - name: test + displayName: '测试阶段' + strategy: naturally + trigger: auto + executor: + type: node-pool + labels: + - linux + steps: + - step: execute@python + name: setup_python + displayName: '设置 Python 环境' + pythonVersion: '3.10' + + - step: execute@shell + name: install_deps + displayName: '安装依赖' + script: | + python -m pip install --upgrade pip + pip install click tomli tomli-w nuitka pytest + + - step: execute@shell + name: run_tests + displayName: '运行测试' + script: | + pytest tests/ -v diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..43baf10 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,32 @@ +# CODEOWNERS +# 代码所有者配置 +# 文档: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# 默认所有者 +* @FORGE24 + +# 核心模块 +/sikuwa/builder.py @FORGE24 +/sikuwa/compiler.py @FORGE24 +/sikuwa/config.py @FORGE24 +/sikuwa/cli.py @FORGE24 + +# 增量编译模块 +/sikuwa/incremental/ @FORGE24 + +# C++ 扩展 +/sikuwa/cpp_cache/ @FORGE24 + +# 国际化 +/sikuwa/i18n/ @FORGE24 + +# 文档 +/docs/ @FORGE24 +*.md @FORGE24 + +# CI/CD 配置 +/.github/ @FORGE24 +/.gitee/ @FORGE24 + +# 测试 +/tests/ @FORGE24 diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..3aaf9c4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,61 @@ +--- +name: Bug 报告 +about: 报告问题以帮助改进项目 +title: '[BUG] ' +labels: bug +assignees: '' +--- + +## 环境信息 + +| 项目 | 值 | +|:---|:---| +| 操作系统 | | +| Python 版本 | | +| Sikuwa 版本 | | +| Nuitka 版本 | | + +## 问题描述 + +### 预期行为 + +清晰描述预期的行为。 + +### 实际行为 + +清晰描述实际发生的行为。 + +## 复现步骤 + +1. 执行命令 '...' +2. 配置 '...' +3. 查看 '...' +4. 出现错误 + +## 配置文件 + +如适用，请提供 `sikuwa.toml` 配置文件内容： + +```toml +# 粘贴配置文件内容 +``` + +## 日志信息 + +``` +# 粘贴相关日志或错误信息 +``` + +## 截图 + +如适用，添加截图以帮助说明问题。 + +## 其他信息 + +任何其他相关的上下文信息。 + +## 检查清单 + +- [ ] 已搜索现有 Issue，确认问题未被报告 +- [ ] 已使用最新版本测试 +- [ ] 已提供完整的复现步骤 diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..b730ee1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,51 @@ +--- +name: 功能请求 +about: 提出新功能或改进建议 +title: '[FEATURE] ' +labels: enhancement +assignees: '' +--- + +## 功能描述 + +清晰简洁地描述所需的功能。 + +## 使用场景 + +描述此功能将解决什么问题或满足什么需求。 + +## 期望方案 + +描述期望的解决方案或实现方式。 + +## 备选方案 + +描述考虑过的其他替代方案。 + +## 实现建议 + +如有技术实现建议，请在此描述： + +```python +# 示例代码或伪代码 +``` + +## 相关资源 + +- 参考链接 +- 相关文档 +- 类似项目实现 + +## 优先级评估 + +| 指标 | 评估 | +|:---|:---| +| 影响范围 | 低 / 中 / 高 | +| 实现难度 | 低 / 中 / 高 | +| 紧迫程度 | 低 / 中 / 高 | + +## 检查清单 + +- [ ] 已搜索现有 Issue，确认功能未被请求 +- [ ] 已考虑功能的向后兼容性 +- [ ] 愿意参与此功能的开发（如适用） diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..9d96c11 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,89 @@ +## 变更描述 + +简要描述本次 Pull Request 的变更内容。 + +## 变更类型 + +请勾选适用的选项： + +- [ ] Bug 修复 (fix) +- [ ] 新功能 (feat) +- [ ] 文档更新 (docs) +- [ ] 代码重构 (refactor) +- [ ] 性能优化 (perf) +- [ ] 测试相关 (test) +- [ ] 构建/CI (build/ci) +- [ ] 其他 (chore) + +## 关联 Issue + +Closes #(issue number) + +## 变更详情 + +### 主要变更 + +- 变更点 1 +- 变更点 2 +- 变更点 3 + +### 技术说明 + +如需要，提供技术实现的详细说明。 + +## 测试说明 + +描述如何测试这些变更： + +1. 测试步骤 1 +2. 测试步骤 2 +3. 预期结果 + +### 测试覆盖 + +- [ ] 添加了单元测试 +- [ ] 添加了集成测试 +- [ ] 手动测试通过 + +## 截图/录屏 + +如适用，添加截图或录屏展示变更效果。 + +## 检查清单 + +### 代码质量 + +- [ ] 代码符合项目风格规范 +- [ ] 通过 `black` 格式化检查 +- [ ] 通过 `mypy` 类型检查 +- [ ] 无 linting 错误 + +### 测试 + +- [ ] 所有现有测试通过 +- [ ] 添加了必要的新测试 +- [ ] 测试覆盖率未降低 + +### 文档 + +- [ ] 更新了相关代码注释 +- [ ] 更新了 README（如需要） +- [ ] 更新了 CHANGELOG（如需要） +- [ ] 更新了 API 文档（如需要） + +### 兼容性 + +- [ ] 向后兼容 +- [ ] 已考虑跨平台兼容性 +- [ ] 无破坏性变更（或已在 CHANGELOG 中说明） + +## 其他说明 + +任何其他需要审查者注意的信息。 + +## 审查要点 + +请审查者重点关注： + +1. 关注点 1 +2. 关注点 2 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..2d20711 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,75 @@ +name: CI + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main ] + +jobs: + test: + name: Test (Python ${{ matrix.python-version }} on ${{ matrix.os }}) + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest, macos-latest] + python-version: ['3.8', '3.9', '3.10', '3.11', '3.12'] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install click tomli tomli-w nuitka pytest pytest-cov + + - name: Run tests + run: | + pytest tests/ -v + + lint: + name: Lint + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.10' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install black isort + + - name: Check formatting + run: | + black --check . --exclude='.venv|build|dist' || true + isort --check . --skip=.venv --skip=build --skip=dist || true + + release: + name: Release + runs-on: ubuntu-latest + needs: test + if: startsWith(github.ref, 'refs/tags/v') + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Create GitHub Release + uses: softprops/action-gh-release@v1 + with: + generate_release_notes: true + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..2ddf1b9 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,39 @@ +name: Documentation + +on: + push: + branches: [ main ] + paths: + - 'docs/**' + - 'sikuwa/**' + - 'README.md' + +jobs: + build-docs: + name: Build Documentation + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.10' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -e ".[docs]" + + - name: Build documentation + run: | + cd docs + make html + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..39721af --- /dev/null +++ b/.gitignore @@ -0,0 +1,59 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +*.pyd + +# Distribution / Build +dist/ +build/ +*.egg-info/ +*.egg +*.whl + +# Virtual Environment +.venv/ +venv/ +ENV/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo + +# Sikuwa Build Outputs +sikuwa_logs/ +sikuwa_build/ +*.exe +*.dll + +# C/C++ Build +*.o +*.obj +*.lib +*.a +CMakeCache.txt +CMakeFiles/ +cmake_install.cmake +Makefile + +# Cache +.smart_cache/ +*.cache +.mypy_cache/ +.pytest_cache/ + +# OS +.DS_Store +Thumbs.db +desktop.ini + +# Logs +*.log + +# Temporary +*.tmp +*.bak +*~ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..cf7d92c --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,184 @@ +# 更新日志 + +本文档记录 Sikuwa 项目的所有重要变更。 + +格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)， +版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 + +--- + +## [未发布] + +### 计划中 + +- WebAssembly 编译目标支持 +- 远程分布式编译 +- 编译配置可视化工具 + +--- + +## [1.3.0] - 2026-01-31 + +### 新增 + +- **Native 编译模式**: 支持 Python 到 C/C++ 的转换，通过 GCC/G++ 编译为原生二进制 + - 生成通用动态链接库 (.dll/.so) + - 不依赖 Python 专用格式 (.pyd) + - 支持静态链接选项 + - 可保留生成的 C/C++ 源码用于审计 + +- **增量编译系统**: 实现"指哪编哪"的精确编译 + - 函数级粒度的变更检测 + - 依赖关系图追踪 + - 编译缓存持久化 + - 并行编译支持 + +- **C++ 智能缓存扩展**: 高性能缓存实现 + - 基于 pybind11 的 Python 绑定 + - LRU 缓存策略 + - 内存映射文件支持 + +- **国际化支持 (i18n)** + - 内置中英文支持 + - 基于 Babel 的翻译框架 + - 可扩展的语言包机制 + +- **新增 CLI 命令** + - `sikuwa doctor`: 环境诊断 + - `sikuwa validate`: 配置验证 + +### 变更 + +- 重构日志系统，支持多级别日志输出 +- 优化构建流程，减少不必要的文件操作 +- 改进配置文件解析，支持更复杂的嵌套结构 + +### 修复 + +- 修复 Windows 平台路径处理问题 +- 修复大型项目编译时的内存溢出问题 +- 修复并行编译时的竞态条件 +- 修复 TOML 配置中特殊字符解析错误 + +### 性能 + +- 增量编译场景下构建速度提升 60% +- 缓存命中时跳过重复计算 +- 优化依赖分析算法复杂度 + +--- + +## [1.2.0] - 2025-10-15 + +### 新增 + +- 初始公开发布 +- 基于 Nuitka 的构建系统 +- TOML 配置文件支持 +- 跨平台构建 (Windows/Linux/macOS) +- Standalone 和 OneFile 模式 +- 资源文件打包 + +### CLI 命令 + +- `sikuwa build`: 构建项目 +- `sikuwa clean`: 清理构建文件 +- `sikuwa init`: 初始化配置 +- `sikuwa info`: 显示项目信息 +- `sikuwa version`: 显示版本 + +### 配置选项 + +- 项目基本信息配置 +- Nuitka 编译选项 +- 平台特定配置 +- 数据文件包含 + +--- + +## [1.1.0] - 2025-08-20 + +### 新增 + +- 插件系统支持 +- 自定义构建钩子 + +### 变更 + +- 重构配置管理模块 + +### 修复 + +- 修复依赖检测遗漏问题 + +--- + +## [1.0.0] - 2025-06-01 + +### 新增 + +- 项目初始版本 +- 基础构建功能 +- 命令行界面原型 + +--- + +## 版本对比 + +| 版本 | 发布日期 | 主要特性 | +|:---|:---|:---| +| 1.3.0 | 2026-01-31 | Native 模式、增量编译、i18n | +| 1.2.0 | 2025-10-15 | 公开发布、完整 CLI | +| 1.1.0 | 2025-08-20 | 插件系统 | +| 1.0.0 | 2025-06-01 | 初始版本 | + +--- + +## 迁移指南 + +### 从 1.2.x 升级到 1.3.x + +**配置文件变更** + +新增 `[sikuwa.native]` 配置节，用于 Native 编译模式： + +```toml +# 新增配置 +[sikuwa.native] +cc = "gcc" +cxx = "g++" +output_dll = true +output_exe = true +``` + +**CLI 变更** + +`build` 命令新增参数： + +```bash +# 新增 -m/--mode 参数 +sikuwa build -m native + +# 新增 --keep-c-source 参数 +sikuwa build -m native --keep-c-source +``` + +**API 变更** + +- `BuildConfig` 类新增 `compiler_mode` 属性 +- `BuildConfig` 类新增 `native_options` 属性 +- 新增 `NativeCompilerOptions` 数据类 + +--- + +## 链接 + +- [GitHub Releases](https://github.com/FORGE24/Sikuwa/releases) +- [Gitee Releases](https://gitee.com/FORGE24/Sikuwa/releases) +- [PyPI](https://pypi.org/project/sikuwa/) + +[未发布]: https://github.com/FORGE24/Sikuwa/compare/v1.3.0...HEAD +[1.3.0]: https://github.com/FORGE24/Sikuwa/compare/v1.2.0...v1.3.0 +[1.2.0]: https://github.com/FORGE24/Sikuwa/compare/v1.1.0...v1.2.0 +[1.1.0]: https://github.com/FORGE24/Sikuwa/compare/v1.0.0...v1.1.0 +[1.0.0]: https://github.com/FORGE24/Sikuwa/releases/tag/v1.0.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..7c4bc8d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,450 @@ +# 贡献指南 + +感谢您对 Sikuwa 项目的关注。本文档将指导您如何参与项目贡献。 + +--- + +## 目录 + +- [行为准则](#行为准则) +- [如何贡献](#如何贡献) +- [开发环境](#开发环境) +- [代码规范](#代码规范) +- [提交规范](#提交规范) +- [Pull Request 流程](#pull-request-流程) +- [问题反馈](#问题反馈) + +--- + +## 行为准则 + +参与本项目时，请遵守以下原则： + +- 尊重所有贡献者 +- 保持专业、友善的交流方式 +- 接受建设性的批评和建议 +- 专注于项目的最佳利益 + +--- + +## 如何贡献 + +### 贡献类型 + +| 类型 | 说明 | +|:---|:---| +| 报告 Bug | 通过 Issue 报告发现的问题 | +| 功能建议 | 提出新功能或改进建议 | +| 代码贡献 | 提交代码修复或新功能 | +| 文档改进 | 完善项目文档 | +| 测试用例 | 补充单元测试或集成测试 | + +### 贡献流程 + +``` +1. Fork 仓库 +2. 创建分支 +3. 编写代码 +4. 运行测试 +5. 提交更改 +6. 创建 PR +7. 代码审查 +8. 合并代码 +``` + +--- + +## 开发环境 + +### 环境要求 + +| 组件 | 版本 | +|:---|:---| +| Python | >= 3.7 | +| pip | >= 21.0 | +| Git | >= 2.0 | + +### 环境搭建 + +**1. Fork 并克隆仓库** + +```bash +# GitHub +git clone https://github.com//Sikuwa.git + +# Gitee +git clone https://gitee.com//Sikuwa.git + +cd Sikuwa +``` + +**2. 创建虚拟环境** + +```bash +# Windows +python -m venv .venv +.venv\Scripts\activate + +# Linux/macOS +python3 -m venv .venv +source .venv/bin/activate +``` + +**3. 安装依赖** + +```bash +pip install click tomli tomli-w nuitka pytest +``` + +**4. 验证安装** + +```bash +python -m sikuwa --version +pytest tests/ -v +``` + +### 开发依赖 + +``` +click>=8.0 +tomli>=2.0 (Python < 3.11) +tomli-w>=1.0 +nuitka>=2.0 +pytest>=7.0 +``` + +--- + +## 代码规范 + +### Python 代码风格 + +遵循 PEP 8 规范，并满足以下要求： + +**格式化** + +```bash +# 使用 black 格式化代码 +black sikuwa/ + +# 使用 isort 排序导入 +isort sikuwa/ +``` + +**类型注解** + +所有公共函数和方法必须包含类型注解： + +```python +def build_project( + config: BuildConfig, + platform: Optional[str] = None, + verbose: bool = False +) -> bool: + """构建项目""" + ... +``` + +**文档字符串** + +使用 Google 风格的 docstring： + +```python +def compile_module(source: Path, output: Path) -> CompileResult: + """编译单个模块。 + + Args: + source: 源文件路径 + output: 输出文件路径 + + Returns: + CompileResult: 编译结果对象 + + Raises: + CompileError: 编译失败时抛出 + """ + ... +``` + +### 命名规范 + +| 类型 | 规范 | 示例 | +|:---|:---|:---| +| 模块 | 小写下划线 | `smart_cache.py` | +| 类 | 大驼峰 | `SikuwaBuilder` | +| 函数/方法 | 小写下划线 | `build_project` | +| 常量 | 大写下划线 | `MAX_RETRY_COUNT` | +| 私有成员 | 单下划线前缀 | `_internal_method` | + +### 代码检查 + +提交前运行代码检查： + +```bash +# 类型检查 +mypy sikuwa/ + +# 代码风格检查 +black --check sikuwa/ +isort --check sikuwa/ + +# 运行测试 +pytest tests/ -v --cov=sikuwa +``` + +--- + +## 提交规范 + +### 提交信息格式 + +``` +(): + + + +