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

按顺序读这几页:

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 里明确解释原因。

大类通常用"主体 + 职责"拆分实现文件,例如:

• 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 仓库页面

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

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

CONFIG=debug make -j$(nproc)

如果你改了 CLI,建议至少额外验证:

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

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

主仓库当前有两个 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:

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