Project AIRI 开发环境搭建与首次贡献从 Fork 到第一个 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/airiProject AIRImoeru-ai/airi是一个以让虚拟角色进入现实世界为目标的开源项目旨在复刻 Neuro-sama 的能力支持实时语音聊天、Minecraft / Factorio 游玩并提供 Web、macOS、Windows 多端支持。本指南以仓库内 贡献指南 为骨架结合仓库根目录的 package.json、pnpm-workspace.yaml 与 AGENTS.md 等源码级证据带你走完从建立本地开发环境、Fork 克隆、安装依赖、提交代码到创建第一个 Pull Request 的完整流程。读完本文你将能够在本地运行这一 pnpm Turbo 单体仓库并按照项目规范提交一份合格的首个贡献。适用范围说明本指南面向需要修改源码、文档或设计资源的贡献者。若只是想使用 AIRI请从「用户手册」开始应用内自带的调试与诊断工具可参阅 开发者工具 文档。前置准备开始前需要准备以下三样工具Git分布式版本控制工具用于克隆代码与提交变更Node.js 当前 LTS 版本项目运行与构建的基础运行时CorepackNode.js 官方随新版一并提供的包管理器版本管理工具用于激活仓库指定的 pnpm 版本。为什么需要 Corepack因为 Project AIRI 是一个大型 pnpm workspace 单体仓库pnpm-workspace.yaml 中声明了packages/**、apps/**、server/**等十余个工作区根 package.json 通过packageManager: pnpm11.24.0精确锁定 pnpm 版本。corepack enable后执行pnpm时 Node.js 会自动按仓库声明启用对应版本避免因全局 pnpm 版本不一致导致pnpm-lock.yaml冲突。Windows 平台相关设置Windows 用户推荐使用 scoop 包管理器在 PowerShell 中依次执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression然后通过scoop安装git和 Node.jsscoop install git nodejs最后通过 Corepack 启用仓库指定的 pnpm 版本corepack enablemacOS 环境配置在 Terminal或 iTerm2、Ghostty、Kitty 等终端中通过 Homebrew 安装git和nodebrew install git node同样执行 Corepack 启用corepack enableLinux 环境配置打开终端从 Node.js 官网安装当前 LTS 版本再参考 Git 官网的 Linux 页面安装git最后启用 Corepackcorepack enable注意Node.js 必须为当前 LTS 版本。仓库使用 TypeScript 6、Vite 8、Vitest 4 等较新的工具链见 pnpm-workspace.yaml 的 catalog 声明过旧的 Node.js 版本无法满足运行要求。如果你之前已经参与并贡献过本项目如果你此前已经克隆过仓库并做过贡献可以跳过Fork / 克隆步骤直接同步上游更新并把自己的分支变基到最新maingit fetch --all git switch main git pull upstream main --rebase如果手头有开发/工作分支请按如下方式同步至最新主分支git switch your-branch-name git rebase main为什么强调 rebase 而不是 merge从 AGENTS.md 的 PR/Workflow 一节可以看到项目明确要求 Rebase pulls即用变基而非合并来拉取更新以保证提交历史线性、整洁便于维护者审查。Fork 本项目由于外部贡献者没有主仓库的写入权限需要先在 moeru-ai/airi 页面右上角点击Fork按钮将仓库复制一份到自己的 GitHub 账户下。之后的所有提交都会推送到这个 fork 副本再通过 Pull Request 合并回上游。克隆本项目将 fork 得到的仓库克隆到本地注意 URL 中的用户名要替换成你自己的 GitHub 用户名git clone https://github.com/your-github-username/airi.git cd airi提示如果这是你第一次贡献本项目还需要把上游upstream即官方仓库添加为远程源后续才能拉取最新代码并回推改动git remote add upstream https://github.com/moeru-ai/airi.git创建你自己的工作分支永远不要直接在main上提交改动。创建一条独立的工作分支分支名建议遵循username/feat/short-name的命名习惯AGENTS.md 中的 PR/Workflow 规范git switch -c your-branch-name安装依赖项Project AIRI 采用 pnpm workspace 组织所有包依赖安装命令如下corepack enable pnpm install执行pnpm install时有两个值得注意的细节postinstall 自动构建内部包根 package.json 声明了postinstall: pnpm exec simple-git-hooks pnpm run build:packages即安装完成后会自动安装 git hooks见下文提交前验证并通过 Turbo 构建全部packages/*内部包pnpm overrides 与补丁pnpm-workspace.yaml 中对mineflayer-pathfinder、pixi-live2d-display等依赖应用了位于 patches 目录的补丁这是项目为了适配 Minecraft 机器人、Live2D 渲染等特殊场景而做的依赖层修正。可选安装 antfu/ni 简化脚本命令推荐全局安装 antfu/ni 来简化命令输入corepack enable npm i -g antfu/ni安装后你可以用ni替代pnpm install、npm install和yarn install用nr替代pnpm run、npm run和yarn run。你无需费心选择包管理器ni会根据仓库锁定文件自动适配。例如本文后续的命令都可以用nr dev:docs、nr lint nr typecheck来执行。本地开发常用命令速查依赖装好后即可开始本地开发。以下是根 package.json 中定义的核心脚本命令用途pnpm dev启动 Stage Web浏览器版开发服务器pnpm dev:tamagotchi启动桌面端Electron开发环境详见 桌面端开发pnpm dev:pocket:ios/dev:pocket:android启动移动端Capacitor开发环境pnpm dev:docs在本地预览 VitePress 文档站详见 文档站开发pnpm lint运行 moeru-lint 静态检查等价于moeru-lint .pnpm typecheck通过 Turbo 对全部 packages/apps/server 工作区执行类型检查pnpm test:run运行所有项目的 Vitest 测试套件pnpm build通过 Turbo 构建全部工作区产物如果你只修改某个子包的代码AGENTS.md 建议使用工作区过滤器来缩小任务范围例如pnpm -F proj-airi/stage-tamagotchi typecheck pnpm -F proj-airi/stage-web build这样既能快速验证改动也能避免全量构建耗费时间。提交代码Commit提交前验证提交前请确保代码已通过 Lint静态分析器和类型安全检查pnpm lint pnpm typecheck这两条命令的意义在于pnpm lint执行moeru-lint .对全仓库进行 ESLint 检查与代码格式化校验。根 package.json 中lint:fix: moeru-lint --fix .可以自动修复格式问题pnpm typecheck通过turbo run typecheck并行检查packages/*、apps/*、server/**与docs全部工作区等价于对每个包运行tscvue-tsc能捕获跨包的类型错误。此外仓库通过simple-git-hooks在提交前自动运行nano-staged对暂存文件执行moeru-lint --fix见根 package.json 的simple-git-hooks与nano-staged配置。也就是说即使你忘了手动 lint提交时也会收到格式修正这进一步保证了进入仓库的代码风格一致。执行提交git add changed-files git commit -m your-commit-message提交信息请遵循Conventional Commits规范。AGENTS.md 明确给出了示例格式feat(package name): add runner reconnect backoff例如fix(stage-web): correct provider dropdown resetdocs: clarify desktop developer tools usagefeat(plugin-sdk): expose new hooks同时注意 AGENTS.md 中明确禁止使用 gitmoji 表情符号gitmoji is prohibited。将代码推送至 fork 仓库git push -u origin your-branch-name-u参数会建立本地分支与远程分支的跟踪关系之后再次推送只需git push。推送完成后你应该能在 GitHub 上看到自己的分支。创建拉取请求Pull Request前往 moeru-ai/airi 页面按以下步骤创建 Pull Request点击Pull requests按钮再点击New pull request按钮选择Compare across forks链接然后选择你自己 fork 的代码仓库检查并确认你的改动无误后点击Create pull request按钮完成创建。创建 PR 时建议在描述中AGENTS.md 的要求说明以下内容改了什么summary of changes如何测试的tested with which commands例如pnpm -F proj-airi/stage-web typecheck后续计划follow-ups。好欸搞定了~恭喜你成功地为本项目提交了首次贡献现在可以等待项目的维护人员来审核你的拉取请求啦。如果审查提出了修改意见请修复问题后重新运行相关检查、推送更新并在评论中附上验证证据AGENTS.md 中同样对此有明确约定。面向贡献者的更多资源开发者工具理解和使用桌面端「系统 → 开发者」中的诊断与验证工具Context Flow、WebSocket Inspector、Screen Capture 等适合复现问题或排查 Bug 时阅读文档站开发在本地编写、预览和验证 VitePress 文档包括新增中文页面时如何在docs/.vitepress/config.ts的zh-Hanssidebar 中添加入口桌面端开发运行、检查和构建 Electron 桌面端apps/stage-tamagotchi并了解共享代码应优先放入packages/stage-ui的约定设计指南面向设计师的参考资源与工具该章节仍在完善中AGENTS.md面向 Agent 与人类贡献者的仓库级开发规范涵盖 TypeScript 编码约束、模块设计原则、IPC/Eventa 用法、i18n 术语表维护与 PR 工作流是深入了解本项目工程文化的第一手资料README.md项目总览包含 Stage Web / Tamagotchi / Pocket 三端的开发命令与架构图。最后提醒一点提交 PR 前请确保改动范围聚焦、单一避免在一次 PR 中混入无关重构——这与 AGENTS.md 中 Keep changes scoped 的原则一致也是让维护者快速完成 review 的最佳方式。【免费下载链接】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），仅供参考