桌面应用开发工具【免费下载链接】vicinaeA focused launcher for your desktop - native, fast, extensible项目地址https://gitcode.com/gh_mirrors/vi/vicinae点击查看免费下载Vicinae 是一个基于 QtQuick 的原生桌面启动器command palette仓库以 C 承担业务逻辑、QML 承担界面呈现并用 React/TypeScript 驱动扩展 API。本文以仓库根目录的 CONTRIBUTING.md 为骨架结合 AGENTS.md、根目录 Makefile、.clang-format、.clang-tidy 及src/server下的内置命令实现完整讲解向 Vicinae 提交 bug 报告与代码贡献时必须遵循的规范Issue 提交流程、代码通用准则、clang-format/clang-tidy格式化与静态检查体系以及针对 AI 生成代码的评审口径。读完本文你将清楚掌握如何提交一份会被认真对待的 Issue和如何写出能通过评审的 C/QML/TypeScript 补丁。一、总览贡献的两种途径Vicinae 的贡献者指南开宗明义这份文档包含你在贡献之前无论是以 bug 报告还是代码的形式必须遵循的一组准则。仓库本身是 C23 QML 的多平台项目Linux / macOS / Windows其开发工作流在不同平台上有明确分工UNIX 系使用make dev进入开发模式Windows 使用cmake --preset windows-relwithdebinfo仅在必要时才做完整 debug 构建。这两条开发入口同时记录在 AGENTS.md 中与贡献指南中的所有提交的代码都需要本地测试直接呼应任何补丁在提交前都应先在对应平台的开发模式下完成构建与验证。二、提交 Issue 的正确姿势2.1 Issue 追踪与查重所有 Issue 都通过仓库内置的 GitHub Issue 追踪器管理。如果拿不准自己的问题是否值得开一个新 Issue可以选择先创建 GitHub Discussion 或加入 Discord 服务器讨论避免污染 Issue 列表。在打开 Issue 之前务必先做一次快速搜索确认自己没有创建重复条目——这是开源仓库维护者最在意的基本礼仪之一。2.2 遵循 Issue 模板与内置报告命令提交时请确保遵循仓库提供的 Issue 模板。指南特别强调bug 类 Issue 应优先使用 Vicinae 内置的 Report Bug 命令直接提交除非该 bug 导致 Vicinae 服务器无法启动。这一要求在源码中有完整实现。report-bug-command.hpp 定义了内置命令report-bugid 为report-bug名称为 Report a Vicinae Bug其作用是用预填好的相关信息跳转到 Vicinae 的 Issue 创建页面它还接收一个可选的title参数并带有create issue关键字便于搜索命中。预填信息来自 bug-report-url.hpp 中的ISSUE_TEMPLATE会自动拼接以下系统信息让维护者无需反复追问环境细节Version版本号与 Build info构建信息来自generated/version.hProvenance来源渠道OS操作系统与 QT PlatformDE桌面环境来自internal/os-release.hpp模板正文还固定包含 Describe the bug、To Reproduce、Expected behavior 等小节。也就是说用内置命令提交 bug 时版本、OS、桌面环境等关键环境信息会被自动带出你只需要描述复现步骤与预期行为即可。该命令的入口在设置页的 About 页面AboutSettingsPage.qml 中Settings.reportBug()底层的reportBug()实现在 settings-window.cpp。2.3 扩展 bug 与安全问题走专门通道如果 bug 涉及官方 Vicinae 扩展商店中发布的扩展应在其扩展仓库vicinaehq/extensions中提交 Issue而不是主仓库——主仓库的 Issue 只跟踪 Vicinae 本体的问题。如果怀疑是严重的安全问题不要直接开公开 Issue应通过 vicinaehq 组织页面上列出的联系邮箱私下联系维护团队。三、贡献代码的通用准则3.1 Less is more小步提交指南的第一条原则直白而实用Less is more——每一行新代码都意味着项目额外的维护成本体量巨大的 PR 被接受的概率更低尤其是那些包含重大架构决策、且之前从未讨论过的改动。因此如果你打算做一个大改动建议先加入 Discord 服务器在 dev 频道中与维护者充分讨论后再动手。这既能避免方向性返工也能让后续评审更顺畅。3.2 本地测试是硬性要求所有提交的代码都需要在本地测试通过。构建说明与开发技巧见官方文档的 build 页面如前所述开发入口在 UNIX 上为make dev在 Windows 上为cmake --preset windows-relwithdebinfoAGENTS.md。注意仓库是只读的这里的构建与测试指的是在你自己的本地工作副本中进行。四、格式化与 Lint硬性门槛Vicinae 的格式化体系是分语言、多工具、可一键执行的语言/文件格式化工具触发方式C.cpp/.hpp/.mmclang-formatmake format内部clang-format目标QML.qmlqmlformatmake format内部qmlformat目标TypeScriptsrc/typescriptbiome format --writemake format内部tsfmt目标4.1 clang-format代码风格的唯一标准格式化统一由仓库根目录的.clang-format文件规定所有贡献必须尊重该格式。根目录 .clang-format 的关键配置为BasedOnStyle: LLVM——以 LLVM 风格为基础ColumnLimit: 110——单行最长 110 列AllowShortIfStatementsOnASingleLine: true、AllowShortBlocksOnASingleLine: Always、AllowShortFunctionsOnASingleLine: All——允许短语句/代码块/函数单行书写SortIncludes: false——头文件不自动排序include 顺序规则见下文 4.4。你可以运行make format一次性格式化整个项目的所有文件大多数现代 IDE 也能根据.clang-format自动拾取规则并在保存时自动格式化。对照 Makefile 可以看到clang-format目标的真实行为它遍历./src下所有*.cpp、*.hpp、*.mm文件按-n 10 -P $(NPROC)并行调用clang-format -i原地改写。如果想要只检查不改写CI / 提交前自检场景可运行make check-format它对同样范围的文件执行clang-format --dry-run -Werror任一文件格式漂移即返回非零退出码Makefile。4.2 需要跳过的文件.clang-format-ignore部分 vendored 依赖与生成代码不应被重新格式化它们记录在根目录 .clang-format-ignore 中包括src/lib/common/include/common/CLI11.hpp第三方 CLI 库src/lib/emoji/include/emoji/generated/*等生成目录src/server/src/lib/toml.hpp需要注意.clang-format-ignore只有clang-format 18才被支持。Windows 下的格式化脚本 scripts/format.ps1 对此专门做了版本兜底优先使用$env:CLANG_FORMAT覆盖其次寻找 VS 2022 自带的 LLVM若 PATH 上的版本低于 18 则尝试切换并输出警告旧版本会误改生成文件、造成无谓的 diff。4.3 Windows 贡献者scripts/format.ps1Windows 用户没有 GNU make / POSIX shell 时可以运行 PowerShell 脚本 scripts/format.ps1 作为make format的等价物pwsh scripts/format.ps1 # 原地格式化整个源码树 pwsh scripts/format.ps1 -Check # 仅校验 C 格式等价 make check-format漂移时以非零退出码失败该脚本同样覆盖 clang-formatC、qmlformatQML与 biomeTypeScript三段并以批处理方式每批 40 个文件调用工具以规避 Windows 命令行长度限制。4.4 注释纪律指南对注释的态度非常明确把注释数量控制在严格的最低限度好代码不需要大量注释。但也有例外如果你觉得自己的解决方案不理想、可以改进或者依赖某种奇怪的 hack那么用注释记录下来是被鼓励的。项目目前不使用文档生成器因此不需要为生成文档而写注释。AGENTS.md 进一步细化了编码风格中的注释与书写规则QObject 类中Q_OBJECT、Q_PROPERTY、Q_INVOKABLE、signals按顺序放在类顶部include 顺序系统头文件在前本地头文件在后头文件保护统一使用#pragma once字符串类型内部用std::stringQString只出现在 Qt 边界常量使用UPPER_SNAKE_CASE。4.5 clang-tidy新代码必须通过仓库最近才添加了.clang-tidy配置文件目前并未全局强制启用——因为还有大量代码尚未迁移。但新代码必须对照这些规则检查。多数 IDE 仅凭.clang-format/.clang-tidy文件的存在就能自动提供对应的智能提示intellisense。从根目录 .clang-tidy 可以看到这套检查体系的取向WarningsAsErrors将所有告警视为错误唯一豁免bugprone-unchecked-optional-access启用的检查族包括bugprone-*、concurrency-*、cppcoreguidelines-*、google-global-names-in-headers、misc-*、modernize-*、performance-*、portability-*、readability-*等同时针对项目实际逐条关闭了不合适的子规则如cppcoreguidelines-avoid-magic-numbers、readability-magic-numbers、modernize-use-trailing-return-type等CheckOptions中强制了命名规范类/结构体/枚举使用CamelCase函数使用camelBack.clang-tidyHeaderFilterRegex排除了 vendored 的CLI11、toml、rang头文件。关于 lint 违规的豁免策略AGENTS.md 给出了更细的指引个别违规在特定场景下可被接受应使用//NOLINTBEGIN(rule)与//NOLINTEND(rule)成对注释包裹行内//NOLINT注释一般不被鼓励格式化后可能错位失效若 NOLINT 指令本身无效例如 STL 内部误报才考虑在本地.clang-tidy配置中显式关闭对应检查。4.6 别忘了 QML 与 TypeScript虽然 CONTRIBUTING.md 只点名了clang-format但完整的make formatMakefile实际上串联了三段qmlformat tsfmt clang-format。其中 QML 还有独立的make qmllint用于运行 linterAGENTS.mdQML 内的 JavaScript 应尽量使用 ES6 语法且逻辑只服务于呈现关注点metrics 计算、hover 信号等。TypeScript 部分统一由biome format --write .格式化Makefile。五、AI 生成代码的处理政策CONTRIBUTING.md 对 AI 生成代码给出了非常明确的态度核心要点如下AI 生成代码与普通代码一视同仁上述所有规则本地测试、格式、lint同样适用没有任何豁免。AI 不能替代真正的理解与测试指南原文是 dont be lazy别偷懒。不遵守指南的懒 AI PR将被直接拒绝。PR 描述尽量简洁没有人会去读你写的长篇大论描述应直奔主题。披露使用情况良好实践如果贡献大部分由 AI 生成建议在 PR 中注明使用了哪个模型或工具——这有助于维护者评估与复核。结合前文 4.5 节可以理解背后的工程逻辑Vicinae 的clang-tidy检查族bugprone-*、cppcoreguidelines-*、performance-*等本质上就是为捕获 AI 代码常见的看似正确实则危险的模式而设因此新代码必须通过 clang-tidy 规则对 AI 生成代码尤为关键。六、总结一份合格贡献的检查清单综合 CONTRIBUTING.md 与仓库实现提交前可以对照这份清单自查是否为重复 Issue是否遵循 Issue 模板bug 是否通过 Vicinae 内置 Report Bug 命令提交除非服务器无法启动扩展相关 bug 是否已转到扩展仓库大改动是否已在 dev 频道提前讨论过代码是否在本地UNIX 用make devWindows 用cmake --preset windows-relwithdebinfo完成构建与测试是否运行了make formatWindows 用pwsh scripts/format.ps1并通过make check-format或-Check新代码是否通过了.clang-tidy规则检查必要时用NOLINTBEGIN/END成对豁免注释是否精简到最小、是否只在解释非理想方案/hack时使用若为 AI 生成代码是否真实理解并测试过、PR 描述是否简洁、是否注明了所用模型遵循这些约定你的 Issue 和 PR 就能以维护者最习惯的形态进入评审流程这也是 Vicinae 社区能保持代码少而精、评审可负担这一工程文化的基础。赞分享桌面应用开发工具【免费下载链接】vicinaeA focused launcher for your desktop - native, fast, extensible项目地址https://gitcode.com/gh_mirrors/vi/vicinae点击查看免费下载相关推荐Containerization 项目贡献指南从 Issue 提交到 PR 合并的完整流程与工程规范Containerization 项目贡献指南从 Issue 提交到 PR 合并的完整流程与工程规范 本文是 Containerization一个在 App容器运行时虚拟化云原生STK高级技巧如何通过Modal与BandedWG创建专业级合成音色STK高级技巧如何通过Modal与BandedWG创建专业级合成音色 在音乐制作和音频开发领域专业级合成音色的创建往往需要复杂的算法和精细的参数调整。 Sy音频处理音频有限状态机在Gin Web中的应用轻松实现复杂审批流程的终极指南有限状态机在Gin Web中的应用轻松实现复杂审批流程的终极指南 在现代化的企业应用中审批流程管理是每个业务系统都绕不开的核心需求。无论是请假申请、报销审批创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考