Project AIRI 贡献指南本地开发环境搭建与首次 Pull Request 提交全流程【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi本篇指南基于 Project AIRI 官方贡献文档Development Setup and Your First Contribution整理而成面向希望为 AIRI 提交源码、文档或设计资源修改的开发者完整覆盖从环境准备、Fork/Clone、依赖安装到提交 PR 的每一步。读完本文你将能够在本地跑通 AIRI 的 pnpm monorepo 开发环境通过 lint 与类型检查并提交你的第一个 Pull Request。仓库仅作只读参考所有命令均在本地执行。适用范围的界定贡献文档明确限定了本节的读者对象想要修改源码、文档或设计资源的贡献者。如果你只是想使用 AIRI应当直接参考用户手册如果你关心的是桌面应用内建的调试工具请参见 Desktop Developer Tools 说明。这意味着「贡献者工作流」与「终端用户操作」是两条完全不同的路径本文只讨论前者。前置条件开始之前你需要准备三样基础工具工具作用说明Git版本控制与 PR 流程各平台安装方式不同见下文mise运行时版本管理也可使用任何能读取.tool-versions的版本管理器Corepack启用 pnpm 等包管理器随近期 Node.js 版本内置AIRI 在仓库根目录的.tool-versions中锁定 Node.js 版本本文写作时文档记录为 24.13.0当前仓库快照中的实际值为nodejs 26.7.0请以仓库内文件的实际内容为准。克隆后应安装锁定的版本而不是依赖系统包管理器自带的 Node.js——这是保证本地行为与 CI 一致的关键。Windows 环境准备打开 PowerShell。安装scoopSet-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression用 Scoop 安装 Git 与 misescoop install git misemacOS 环境准备打开 Terminal、iTerm2、Ghostty、Kitty 或任意终端。用 Homebrew 安装 Git 与 misebrew install git miseLinux 环境准备打开终端。按照 Git 官方 Linux 安装说明安装 Git。使用适合你发行版的包或安装方式安装 mise。先了解仓库形态pnpm monorepo在动手之前值得先对仓库结构有个整体认知这决定了后续所有命令的写法。Project AIRI 是一个典型的 pnpm workspace monorepo根目录 package.json 声明了工作区范围pnpm-workspace.yaml 中列出packages/**、plugins/**、integrations/**、services/**、examples/**、docs/**、engines/**、apps/**、server/**等目录。核心应用包括apps/stage-webWeb 应用Vue 3 Viteapps/stage-tamagotchiElectron 桌面应用apps/stage-pocketCapacitor 移动端Kotlin/Swiftpackages/stage-ui、packages/stage-ui-three、packages/stage-shared跨端共享的业务组件与状态docsVitePress 文档站。正因为是 monorepo根目录提供了一批统一的 scriptdev、dev:docs、dev:tamagotchi、lint、typecheck、build等而针对单个包的命令则使用 pnpm 的-F 包名过滤写法。理解这一点后面所有的命令都能对号入座。如果你之前已经贡献过如果你已经克隆过仓库先不要急着重新克隆而是把本地分支与上游同步到最新git fetch --all git switch main git pull upstream main --rebase如果手上已有一个工作分支同样用 rebase 方式从main更新git switch your-branch-name git rebase main注意upstream指向的是 Project AIRI 原仓库而origin指向你 Fork 出来的副本。只有首次贡献过的人才需要配置upstream见下文。Fork 项目进入项目仓库页面点击右上角的Fork按钮在你的账号下创建一份副本。Fork 的意义在于你没有原仓库的写权限通过 Fork → PR 的路径维护者可以在合并前审查你的改动。克隆你的 Fork将 Fork 得到的仓库克隆到本地将your-github-username替换为你的 GitHub 用户名如果你是基于本仓库的镜像工作也可以将地址替换为对应的克隆地址git clone https://github.com/your-github-username/airi.git cd airi创建工作分支在主分支之外单独开一条工作分支是保证main干净、方便日后 rebase 的标准做法git switch -c your-branch-name安装依赖在仓库根目录依次执行以下命令先安装.tool-versions记录的 Node.js 版本并校验再启用 Corepack最后用 pnpm 安装依赖mise install mise exec -- node --version mise exec -- corepack enable mise exec -- pnpm install其中node --version输出的版本号必须与.tool-versions一致。以下各节示例默认你的 shell 已激活 mise即mise exec --的 shim 模式否则所有包管理器命令都要通过mise exec --包裹例如mise exec -- pnpm typecheck。值得一提的是pnpm install之后仓库会自动完成两件额外的事根 package.json 的postinstall脚本会执行simple-git-hooks安装 Git 钩子并运行pnpm run build:packages构建工作区内所有 packages。也就是说依赖安装的同时 Git 提交钩子与本地包构建已就绪这正是后面「提交前验证」环节能自动拦截问题的基础。可选安装 antfu/ni 简化命令antfu/ni是一套包管理器命令的统一封装可避免记忆pnpm/npm/yarn的差异mise exec -- npm install --global antfu/ni安装后用ni替代pnpm install、npm install或yarn install用nr替代pnpm run、npm run或yarn run。ni会自动识别当前仓库使用的包管理器本仓库为 pnpm因此无论仓库用哪种管理器你的命令写法都保持不变。提交你的修改提交前验证lint 与类型检查AIRI 要求改动在提交前通过静态检查。从仓库根目录运行pnpm lint pnpm typecheck这两条命令在根 package.json 中的真实定义值得留意pnpm lint实际执行的是moeru-lint .底层由 alint.config.ts 驱动对**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}执行 JS/TS 推荐规则集pnpm typecheck使用pnpm -rF... --parallel typecheck对packages/**、apps/**、server/**、docs并行执行类型检查其中proj-airi/stage-tamagotchi等应用还叠加了vue-tsc检查。如果你安装了antfu/ni也可以写成nr lint nr typecheck另外根 package.json 的simple-git-hooks配置了pre-commit钩子每次git commit前会执行pnpm nano-staged对暂存文件自动运行moeru-lint --fix。这意味着提交时刻还会有一层自动修复兜底但这不代表你可以跳过手动的pnpm lint与pnpm typecheck——钩子只处理暂存文件且类型检查仍需显式执行。创建提交将改动加入暂存区并提交git add changed-files git commit -m your-commit-message推送你的分支git push -u origin your-branch-name推送成功后你的分支就会出现在你 Fork 的仓库页面上可以进行 PR 了。如果是首次贡献记得先把 Project AIRI 原仓库添加为upstream远端git remote add upstream https://github.com/moeru-ai/airi.git这样后续就能用前文「老贡献者」一节中的git pull upstream main --rebase保持同步。创建 Pull Request打开 Project AIRI 仓库页面按以下步骤操作点击Pull requests点击New pull request点击Compare across forks跨 Fork 比较选择你的 Fork 与工作分支审阅改动内容后点击Create pull request。至此你的第一个 PR 就提交成功了接下来只需等待维护者审查。建议在 PR 描述中简要说明改动动机、影响范围以及本地 lint/typecheck 的通过情况能显著提升被合入的效率。提交前的一站式检查清单把全流程浓缩成一张可对照的清单.tool-versions中锁定的 Node.js 版本已通过mise install安装且node --version一致corepack enable已执行pnpm 可用pnpm install完成postinstall 已自动装好 Git 钩子并构建 packages已在独立工作分支上开发main保持干净pnpm lint与pnpm typecheck全部通过已git push -u origin branch并基于main创建 PR深入与本主题相关的其他贡献子主题贡献文档目录下还有几份与本指南直接衔接的专题文档可作为下一步阅读文档站开发文档内容按语言放在docs/content/locale下本地预览用pnpm dev:docs单独校验用pnpm -F proj-airi/docs typecheck与pnpm -F proj-airi/docs build。新增英文页面时还需把它加进 docs/.vitepress/config.ts 的en侧边栏否则页面只能通过 URL 访问而不会出现在导航中Web 应用开发Web 应用位于apps/stage-web开发命令为pnpm dev或更显式的pnpm dev:web校验命令为pnpm -F proj-airi/stage-web typecheck与pnpm -F proj-airi/stage-web build桌面应用开发Electron 应用位于apps/stage-tamagotchi开发命令为pnpm dev:tamagotchi校验命令为pnpm -F proj-airi/stage-tamagotchi typecheck与pnpm -F proj-airi/stage-tamagotchi build。改动桌面页面前应先确认相关组件或状态是否已存在于packages/stage-ui——Web 与桌面共用的逻辑应尽量下沉到共享包桌面开发者工具桌面版Settings → System → Developer页面内建了大量诊断工具IO Tracer、Lag Visualizer、WebSocket Inspector、Context Flow、Plugin Host Debug、Screen Capture / Vision Capture 等用于复现问题、开发功能与采集诊断信息是贡献者排查问题时的得力助手。结语从环境准备到 PR 合入AIRI 的贡献流程与绝大多数 pnpm monorepo 项目一致但有几个 AIRI 特有的细节需要牢记以.tool-versions锁定 Node.js 版本、通过mise与 Corepack 管理运行时、提交前必须通过moeru-lint与全仓类型检查、Web 与桌面共用逻辑优先放在packages/stage-ui。掌握这套流程后无论是修 bug、加功能还是改进文档你都能以最低摩擦完成首个贡献。【免费下载链接】airi Self hosted, you-owned Grok Companion, a container of souls of waifu, cyber livings to bring them into our worlds, wishing to achieve Neuro-samas altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考