Glass 项目贡献指南：从 Issue 认领到 PR 合并的完整协作流程与本地开发环境搭建

人工智能AI 应用交互助手本地部署语音【免费下载链接】glassDigital Mind Extension项目地址https://gitcode.com/gh_mirrors/glass21/glass点击查看免费下载Glassby Pickle是一款开源的 Digital Mind Extension 桌面应用它常驻桌面、实时感知屏幕与音频上下文并通过 Ask、实时会议纪要等功能把日常操作转化为结构化知识。本文基于仓库根目录的 CONTRIBUTING.md 撰写系统梳理 Glass 的贡献工作流Issue → 认领 → Fork → 开发 → PR并深入拆解本地构建、代码风格与架构约束让无论是首次接触开源的新手good first issue还是想深入改动核心逻辑的开发者都能按部就班地完成一次高质量合入。读完本文你将掌握如何通过/assign命令认领任务、如何按规范命名分支与提交 PR、如何正确搭建 Node.js 20 开发环境并跑通npm run setup/npm run lint以及新代码必须遵守的架构设计约定。一、贡献工作流从 Issue 到合并的五个步骤Glass 的贡献流程以 Issue 为起点、以 PR 合入为终点全程围绕 GitHub 原生协作机制展开。完整链路如下1. 发现或创建 Issue所有开发工作都必须从 Issue 开始它是讨论新想法、跟踪进度的中心载体。浏览现有 Issue前往仓库的 Issues 页面查找感兴趣的任务。如果你是新手优先选择带有good first issue标签的任务——这类问题通常范围清晰、涉及模块少适合熟悉代码库和贡献流程。创建新 Issue如果发现未报告的 Bug 或想提出新功能请使用仓库自带的 Issue 模板创建新 Issue把问题背景、复现步骤、期望行为描述清楚便于维护者评估。2. 认领 Issue防止重复劳动在动手编码之前必须认领 Issue避免多人同时开发同一任务造成冲突。操作方式非常直接在目标 Issue 下留言并输入命令/assign仓库的 GitHub Bot 会自动把 Issue 分配给你。当你的头像出现在页面右侧的Assignees受理人区域时就表示认领成功可以正式开始开发。3. Fork 仓库并创建分支认领完成后开始搭建本地开发环境Fork把上游仓库 fork 到自己的 GitHub 账号下。Clone将 fork 后的仓库克隆到本地。创建分支基于main分支拉出新分支分支命名务必清晰便于维护者通过名字快速判断改动意图新功能feat/short-description例如feat/user-login-uiBug 修复fix/short-description例如fix/header-rendering-bug4. 开发与质量要求编写代码时需同时满足两类要求代码风格与质量项目使用Prettier和ESLint维护一致的代码风格提交前必须通过 lint 检查详见下文代码风格与 Lint一节。架构与设计模式所有新代码必须与项目既有架构保持一致。在做出重大改动前务必先阅读 Design Patterns Guide——这是仓库内唯一的架构权威文档规定了数据逻辑集中、Repository 双库实现、AI Provider 工厂化、Schema 单一来源、敏感数据默认加密等六条核心原则详见下文开发前必读项目架构约束。5. 创建 Pull Request代码完成并自测通过后向原仓库的main分支发起 PR填写 PR 模板提交时会自动加载 PR 模板请在模板中清晰概括你的改动内容与动机。关联 Issue强制要求在 PR 描述中必须包含一行Closes #XXX例如Closes #123将该 PR 与它解决的 Issue 绑定这是合入的硬性条件。等待 Code Review维护者会对代码进行审查、给出反馈通过后即可合并。二、本地开发环境前置条件与工具链在开始开发前请确保以下工具已安装工具说明下载地址Node.js v20.x.x主开发运行时版本必须为 20.xnodejs.orgPython构建原生依赖与本地 AI 工具链需要python.orgBuild Tools for Visual Studio仅 Windows 用户需要用于编译原生依赖visualstudio.microsoft.com必须使用 Node.js 20.x.x这是为了避免原生依赖native dependencies出现构建错误——仓库底层大量使用better-sqlite3本地 SQLite、keytar系统密钥链等需要编译的原生模块见 package.json版本不匹配会直接导致编译失败。# 检查当前 Node.js 版本 node --version # 如需安装 Node.js 20.x.x推荐使用 nvm # curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash # nvm install 20 # nvm use 20三、Setup 与构建一条命令跑通全栈仓库在根目录 package.json 中封装了完整的初始化脚本npm run setup该命令等价于依次执行根目录npm install→ 进入pickleglass_web子目录安装依赖并执行npm run buildNext.js 构建→ 返回根目录npm start启动 Electron 应用。其中npm start会先执行build:renderer通过 build.js 用 esbuild 打包渲染进程再以electron .启动应用pickleglass_web是仓库内置的 Next.js Web 看板前端账户管理与云端数据查看其构建脚本定义在 pickleglass_web/package.json。提交代码前务必确保能完成一次完整的生产构建即npm run buildbuild:all渲染进程 Web 构建再经 electron-builder 打包见 package.json。开发过程中若只想增量构建渲染进程可运行npm run watch:renderernode build.js --watch。四、Linting提交前的质量闸门npm run lint该命令对应 package.json 中的eslint --ext .ts,.tsx,.js .会从仓库根目录递归检查所有 TypeScript.ts/.tsx与 JavaScript.js文件。如果 lint 报错必须在提交前修复否则无法通过 CI 或维护者审查。关于风格约定仓库根目录的 .prettierrc 给出了明确的格式化基线semi: true—— 语句必须带分号tabWidth: 4—— 缩进宽度为 4 空格printWidth: 150—— 单行最大宽度 150 字符singleQuote: true—— 字符串优先使用单引号trailingComma: es5—— 遵循 ES5 风格的尾随逗号规则bracketSpacing: true、arrowParens: avoid、endOfLine: lf。同时注意pickleglass_webNext.js 前端的 ESLint 走的是另一套配置其 devDependencies 中引入了eslint与eslint-config-next见 pickleglass_web/package.json并通过next lint检查见 pickleglass_web/package.json所以改 Web 前端代码时也要对 Next.js 特有的 lint 规则保持敏感。五、开发前必读项目架构约束Design PatternsCONTRIBUTING 明确要求所有新代码与项目架构保持一致并在重大改动前阅读 Design Patterns Guide。以下六条核心原则是你在写任何一行代码前都应当内化的约束数据逻辑集中Centralized Data Logic所有数据持久化逻辑都集中在Electron 主进程内UI 层渲染进程与 Web 看板一律禁止直接访问数据源。按 Feature 组织模块Feature-Based Modularity代码按功能域组织在src/features/下新功能应自包含在自己的目录中例如src/features/listen/、src/features/ask/。双数据库 RepositoryDual-Database Repositories数据访问层采用 Repository 模式每个处理用户数据的 Repository 都必须同时提供本地SQLite与云端Firebase两套实现且暴露完全一致的接口。典型例子见 src/features/ask/repositories/ 下的sqlite.repository.js与firebase.repository.js成对文件。AI Provider 工厂化AI Provider AbstractionAI 模型交互用Factory Pattern抽象新增一个 LLM Provider 只需在src/common/ai/providers/下新建符合基类接口的模块如 openai.js、gemini.js、anthropic.js、ollama.js并在 factory.js 中注册即可其余代码零改动。Schema 单一来源Single Source of Truth本地 SQLite 数据库的 Schema 只定义在一处——src/common/config/schema.js。任何数据库结构变更都必须同步更新该文件。默认加密Encryption by Default所有敏感用户数据API Key、对话标题、转录文本、AI 摘要等在持久化到 Firebase 之前必须加密该能力由createEncryptedConverter这个 Firestore helper 自动处理相关实现可追溯 src/common/repositories/firestoreConverter.js。此外主进程内部采用Service-Repository分层View*View.js/HTML只负责渲染与交互、保持无脑Service*Service.js承载业务逻辑Repository*.repository.js是唯一允许直接接触sqliteClient/firebaseClient的层。功能专属的 Service/Repository 放在所属 feature 目录下跨功能共享的如authService则放在src/common/services/或src/common/repositories/。这套约束在 src/bridge/featureBridge.js 中体现得非常直观所有 IPC 通道都只做收请求 → 调 Service这一件事例如settings:getPresets直接委托settingsService.getPresets()、check-system-permissions委托permissionService.checkSystemPermissions()数据访问细节永远不会泄漏到 UI 层。你在新增功能时应遵循同样的模式业务逻辑放进 ServiceIPC 桥接注册到 featureBridge数据库访问收敛到 Repository。六、贡献前的注意事项以文档为纲本文全部命令与流程以仓库根目录 CONTRIBUTING.md 为准更详细的架构解读可继续阅读 Design Patterns Guide 与 重构计划后者记录了windowManager.js业务逻辑向各 Service 与featureBridge.js迁移的进行中工作改动相关模块前建议先过一遍。认领约束未经/assign认领直接提交的 PR 可能因与在途工作冲突而被退回务必先认领再开发。构建自测推送前至少跑通npm run setup依赖 构建与npm run lint代码质量再考虑完整生产构建。环境差异Windows 用户需额外安装 Build Tools for Visual Studio且 Node 必须锁定 20.x 以规避原生依赖编译错误。结语Glass 的贡献流程是一条标准、完整的开源协作闭环/assign认领避免冲突Fork 命名分支保证主干干净Closes #XXX建立可追溯的 Issue-PR 关联npm run setup与npm run lint守住构建与质量底线而 Design Patterns 则确保每一个新功能都长在既定的架构骨架上。按照本文的顺序走完一遍你就能以最小的摩擦为这个项目贡献第一行代码。赞分享人工智能AI 应用交互助手本地部署语音【免费下载链接】glassDigital Mind Extension项目地址https://gitcode.com/gh_mirrors/glass21/glass点击查看免费下载相关推荐gh-dash 贡献指南从 Issue 到 PR 的完整协作工作流与本地开发环境搭建gh dash 贡献指南从 Issue 到 PR 的完整协作工作流与本地开发环境搭建 本篇技术指南面向希望为 gh dash一款不打断你工作流的 Git开发工具CLI研发协作Lingo.dev 贡献指南从 Issue 认领到 PR 合并的完整开发流程Lingo.dev 贡献指南从 Issue 认领到 PR 合并的完整开发流程 本文以 Lingo.dev 开源仓库本地镜像位于 GitHub_Trendin开发工具AI 应用前端OpenAssistant 贡献实战指南从认领 Issue 到合入 PR 的完整工作流与开发者环境搭建OpenAssistant 贡献实战指南从认领 Issue 到合入 PR 的完整工作流与开发者环境搭建 OpenAssistant 是一个面向社区的开源对话式人工智能大模型强化学习微调数据标注后端前端上一篇如何不装 Steam 玩局域网联机SteamEmulator 上手教程下一篇91160-cli自动抢健康160号源不用手动刷页面创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考