Contributing

贡献指南

本页帮助你在开始改代码前先踩稳边界：哪些地方能直接改，哪些地方要谨慎，以及提交前至少要做哪些验证。

开始之前建议先读什么

按顺序读这几页：

1. 构建指南
2. 架构概览
3. 仓库导览
4. HTTP API 与 CLI，如果你改的是自动化或控制相关功能

哪些目录可以直接改

本仓库内可直接维护

• src/app/
• src/platform/Platform/
• include/shijima-qt/
• src/app/core/shijima-engine/
• cmake/
• translations/
• src/docs/

说明：

• src/app/core/shijima-engine/ 虽然来源于上游引擎，但已经集成进当前仓库。
• 因为上游 libshijima 并不是这里的单独子模块，所以本仓库内确实可以直接修。

外部子模块，默认不要直接改

• libshimejifinder/
• cpp-httplib/

如果确实需要改这些目录，请先确认是否应该向上游提交，或至少在 PR 里明确解释原因。

当前代码组织约定

主题	约定
语言标准	C++17
源文件后缀	.cc
头文件	#pragma once
代码风格	4 空格缩进，延续现有 K&R 风格
头文件引用	项目头 shijima-qt/...，引擎头 <shijima/...>，平台头 Platform/...

大类通常用“主体 + 职责”拆分实现文件，例如：

• ManagerImportWorkflow.cc
• ManagerLifecycle.cc
• MascotWidgetRendering.cc
• MascotWidgetInteraction.cc

新增实现时，优先延续这个命名方式。

文档与翻译相关约定

当前仓库已经有简体中文翻译文件：

• translations/shijima-qt_zh_CN.ts

构建时会尝试编译翻译资源，但项目不会自动执行 lupdate 去覆盖手工维护的翻译源。

如果你修改了这些地方，应该同步检查文档：

• 用户可见命令或参数
• HTTP API 或 CLI 行为
• 构建步骤
• 平台支持说明
• 运行时错误语义

通常至少要同步这些位置中的相关条目：

• README.md
• README_EN.md
• src/docs/HTTP-API.md
• wiki 仓库页面

本地最低验证标准

提交前至少完成其中一套本机构建：

Windows MSVC

cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug -DQt6_DIR=<your-qt-path>
cmake --build build

Linux / macOS / Make 路径

CONFIG=debug make -j$(nproc)

如果你改了 CLI，建议至少额外验证：

• NeurolingsCE-cli --help
• NeurolingsCE-cli --version
• NeurolingsCE-cli --json --list

如果你改了模板导入或 API，请尽量补一轮实际运行验证，而不只是静态编译通过。

CI 当前会帮你检查什么

主仓库当前有两个 GitHub Actions 工作流：

• build-debug.yaml
• build-release.yaml

你至少应知道：

• PR 相关验证主要看 debug 构建
• 发布构建会覆盖 Windows、Linux、macOS 的打包路径
• Windows CI 是通过 Docker + MinGW 交叉编译，不是 Windows runner 本机构建

不要把 CI 当作第一轮发现明显错误的地方。本地先做最小验证，能大幅减少回滚成本。

提交流程建议

1. Fork 仓库并创建分支。
2. 先确保你能在本地完成一套构建。
3. 改动后做与改动范围相匹配的验证。
4. 如果改了接口、命令或用户路径，同时更新文档。
5. 在 PR 中明确写出“改了什么、为什么改、怎么验证的”。

适合贡献的方向

• Bug 修复
• 文档改进
• Linux 桌面环境兼容性提升
• CLI / 自动化体验提升
• 新语言翻译
• 渲染、内存与导入流程优化

提交信息建议

没有强制格式，但这些前缀更容易读：

• feat:
• fix:
• refactor:
• docs:
• i18n:

下一步阅读

• 仓库导览
• 架构概览
• 构建指南