Project AIRI 开发环境搭建与首次贡献：从 Fork 到第一个 Pull Request 的完整指南

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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi

Project AIRI（moeru-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 版本：项目运行与构建的基础运行时；
• Corepack：Node.js 官方随新版一并提供的包管理器版本管理工具，用于激活仓库指定的 pnpm 版本。

为什么需要 Corepack？因为 Project AIRI 是一个大型 pnpm workspace 单体仓库（pnpm-workspace.yaml 中声明了packages/**、apps/**、server/**等十余个工作区），根 package.json 通过"packageManager": "pnpm@11.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.js：

scoop install git nodejs

最后通过 Corepack 启用仓库指定的 pnpm 版本：

corepack enable

macOS 环境配置

在 Terminal（或 iTerm2、Ghostty、Kitty 等终端）中，通过 Homebrew 安装git和node：

brew install git node

同样执行 Corepack 启用：

corepack enable

Linux 环境配置

打开终端，从 Node.js 官网安装当前 LTS 版本，再参考 Git 官网的 Linux 页面安装git，最后启用 Corepack：

corepack enable

注意：Node.js 必须为当前 LTS 版本。仓库使用 TypeScript 6、Vite 8、Vitest 4 等较新的工具链（见 pnpm-workspace.yaml 的 catalog 声明），过旧的 Node.js 版本无法满足运行要求。

如果你之前已经参与并贡献过本项目

如果你此前已经克隆过仓库并做过贡献，可以跳过"Fork / 克隆"步骤，直接同步上游更新，并把自己的分支变基到最新main：

git 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时有两个值得注意的细节：

1. postinstall 自动构建内部包：根 package.json 声明了"postinstall": "pnpm exec simple-git-hooks && pnpm run build:packages"，即安装完成后会自动安装 git hooks（见下文"提交前验证"），并通过 Turbo 构建全部packages/*内部包；
2. 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 中定义的核心脚本：

如果你只修改某个子包的代码，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全部工作区，等价于对每个包运行tsc+vue-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 reset
• docs: clarify desktop developer tools usage
• feat(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：

1. 点击Pull requests按钮；
2. 再点击New pull request按钮；
3. 选择Compare across forks链接；
4. 然后选择你自己 fork 的代码仓库；
5. 检查并确认你的改动无误后，点击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-sama's altitude. Capable of realtime voice chat, Minecraft, Factorio playing. Web / macOS / Windows supported.项目地址: https://gitcode.com/GitHub_Trending/ai/airi