Open-Agent开源AI Agent贡献者指南如何玩转Yarn Berry Monorepo并提交你的第一个PR【免费下载链接】open-agentOpen-source alternative to Claude Agent SDK, ChatGPT Agents, and Manus.项目地址: https://gitcode.com/gh_mirrors/op/open-agentOpen-Agent 是一个开源 AI Agent 项目Claude Agent SDK、ChatGPT Agents 和 Manus 的开源替代方案支持多智能体协作与自托管部署。本篇贡献者指南将带你在 10 分钟内搞定 Yarn Berry Monorepo 环境顺利提交你的第一个 PR。项目官方明确欢迎一切贡献Open issues or pull requests — no bureaucracy, just collaboration. 无论你是想修一个 Typo、改进前端界面还是打磨 Rust 原生模块这份指南都能让你快速上手。上图来自仓库 blocksuite/playground/public/ 目录是编辑器 playground 中用于调试卡片渲染的测试素材跑起来后你会在演示页面里看到它。一、动手前5 分钟认识 Open-Agent MonorepoOpen-Agent 是一个典型的Yarn BerryYarn 4Monorepo用 package.json 中的workspaces声明了四大区块目录作用技术栈blocksuite/编辑器内核笔记、画布、数据表Lit TypeScriptpackages/frontend/Web 前端与 Electron 桌面端React Rspack Electronpackages/backend/服务端与 Rust 原生模块NestJS Prisma Rusttools/内部 CLI、提交规范、工具库TypeScript想深入了解架构可以从这几个入口文件看起快速上手文档tools/public/dev.md自定义 CLIoa命令tools/cli/核心逻辑在 tools/cli/src/oa.ts测试工作区配置vitest.workspace.ts二、环境准备Node Yarn Berry Rust 一键就位1. 安装依赖工具打开终端确认你的环境满足以下要求版本均已写死在仓库配置中照抄即可工具版本要求依据文件Node.js18–22推荐 22.16.0.nvmrcYarn4.9.1Berry仓库已内置package.json 的packageManager字段Rust1.87.0rust-toolchain.tomlDocker Compose最新版Orbstack 更佳tools/public/dev.md小贴士使用nvm管理 Node 版本执行nvm install nvm use即可自动读取 .nvmrc 切到 22.16.0。2. 克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/op/open-agent cd open-agent yarn仓库通过 package.json 中的packageManager: yarn4.9.1声明了 Yarn 版本配合 .yarnrc.yml 中yarnPath指向的内置发行版即使你本机是 Yarn 1 也能无缝切换到Yarn Berry无需额外安装。首次执行yarn会自动触发 package.json 中的postinstall脚本先运行yarn oa init生成 Monorepo 工作所需文件再初始化 Husky 提交钩子。三、本地跑起来从 Docker 到yarn dev六步走按照 tools/public/dev.md 的流程6 步即可在本地看到完整应用安装依赖yarn上一步已完成启动后端依赖把.docker/dev/compose.yml.example复制为docker-compose.yml然后docker compose -f ./.docker/dev/compose.yml up配置环境变量在仓库根目录或 packages/backend/server/ 下创建.env按需填入数据库、AI 模型 API Key 等构建 Rust 原生模块只需一次yarn oa afk/server-native build可选数据库迁移(cd packages/backend/server yarn prisma migrate dev)启动开发服务器yarn dev启动成功后 Web 应用http://localhost:8080⚙️ 服务端GraphQLhttp://localhost:3010/graphql 登录时的邮箱验证码会发送到本地 MailHoghttp://localhost:8025如果端口被占用可调整OPEN_AGENT_SERVER_PORT或修改 packages/frontend/app/rspack.config.js 中的 devServer 端口。四、效率神器oa CLI 让 Monorepo 操作更简单仓库自带了一个强大的 Monorepo CLI源码见 tools/cli/用法详见 tools/cli/README.md常用命令yarn oa -h # 查看全部帮助 yarn oa init # 重新生成 Monorepo 工作文件 yarn oa clean --dist --rust # 清理构建产物 yarn oa web dev # 指定工作区跑 dev 脚本也可以直接使用 package.json 里定义的组合脚本yarn dev # 同时启动前端 服务端 yarn dev:web # 只启动 afk/app 前端 yarn dev:server # 只启动 NestJS 后端五、提交 PR 前必过质量检查清单 ✅这是贡献流程中最关键的一步——先自检再提交。提交前请务必在仓库根目录执行pre-commit run --all-files它背后是一整套自动化保障体系检查项命令说明ESLintyarn lint:eslint基于 eslint.config.mjs含 React、TS、排序等规则格式化yarn lint:prettierPrettier 全仓格式统一快速 Lintyarn lint:ox基于 Rust 的 oxlint秒级反馈类型检查yarn typechecktsc -b全项目类型构建单元测试yarn testVitest 全量运行详见 vitest.config.ts此外还有三层自动关卡帮你把关Husky lint-staged.husky/pre-commit 钩子在每次git commit时只对暂存文件跑 PrettierTS/JS和 taploTOML、cargo fmtRust规则见 package.json。Conventional Commits提交信息需符合规范如feat:、fix:、docs:、chore:配置见 tools/commitlint/package.json。PR 标题 LintCI 中的 pr-title-lint.yml 会校验你的 PR 标题是否符合 Conventional Commits 规范标题不合格会被直接拦截请特别注意六、提交你的第一个 PR完整流程 万事俱备下面是新手最顺畅的路径选任务从简单的开始——修复文档错字、补充测试、改进 UI 文案都是绝佳的破冰贡献拉新分支git checkout -b fix/my-first-change修改代码动手吧小步提交更容易被 review本地自检pre-commit run --all-filesyarn typecheckyarn test规范提交git commit -m fix: 修正 dev.md 中的启动说明推送并发起 PR推送到你的 fork 仓库再向主仓库发起 Pull Request标题用 Conventional Commits 格式 遇到问题先在 issue 区搜索或加入项目 Discord 社区提问维护者们对新手非常友好。七、新手常见问题 FAQQ1yarn报错说 Node 版本不对项目要求node 23见 package.json用nvm use 22切换即可。Q2Yarn Berry 和经典 Yarn 有什么区别Yarn Berry4.x是官方新架构使用零安装 PnP 方案通过packageManager字段自举版本由 .yarnrc.yml 精确锁定团队协作更稳定。Q3我只想改前端需要装 Rust 吗需要。postinstall会构建原生模块源码在 packages/backend/native/一次性构建后即可缓存。Q4改了blocksuite/下的文件要跑哪些测试yarn test会按 vitest.workspace.ts 自动覆盖根目录和 blocksuite 下所有vitest.config.ts也可用yarn test:ui打开可视化界面调试。下一步跑通本地环境后建议通读 README.md 中的部署章节再挑一个你感兴趣的小 issue 开始你的第一个 PR。祝你在 Open-Agent 的开源 AI Agent 之旅中玩得开心✨【免费下载链接】open-agentOpen-source alternative to Claude Agent SDK, ChatGPT Agents, and Manus.项目地址: https://gitcode.com/gh_mirrors/op/open-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Open-Agent开源AI Agent贡献者指南：如何玩转Yarn Berry Monorepo并提交你的第一个PR
Open-Agent开源AI Agent贡献者指南如何玩转Yarn Berry Monorepo并提交你的第一个PR【免费下载链接】open-agentOpen-source alternative to Claude Agent SDK, ChatGPT Agents, and Manus.项目地址: https://gitcode.com/gh_mirrors/op/open-agentOpen-Agent 是一个开源 AI Agent 项目Claude Agent SDK、ChatGPT Agents 和 Manus 的开源替代方案支持多智能体协作与自托管部署。本篇贡献者指南将带你在 10 分钟内搞定 Yarn Berry Monorepo 环境顺利提交你的第一个 PR。项目官方明确欢迎一切贡献Open issues or pull requests — no bureaucracy, just collaboration. 无论你是想修一个 Typo、改进前端界面还是打磨 Rust 原生模块这份指南都能让你快速上手。上图来自仓库 blocksuite/playground/public/ 目录是编辑器 playground 中用于调试卡片渲染的测试素材跑起来后你会在演示页面里看到它。一、动手前5 分钟认识 Open-Agent MonorepoOpen-Agent 是一个典型的Yarn BerryYarn 4Monorepo用 package.json 中的workspaces声明了四大区块目录作用技术栈blocksuite/编辑器内核笔记、画布、数据表Lit TypeScriptpackages/frontend/Web 前端与 Electron 桌面端React Rspack Electronpackages/backend/服务端与 Rust 原生模块NestJS Prisma Rusttools/内部 CLI、提交规范、工具库TypeScript想深入了解架构可以从这几个入口文件看起快速上手文档tools/public/dev.md自定义 CLIoa命令tools/cli/核心逻辑在 tools/cli/src/oa.ts测试工作区配置vitest.workspace.ts二、环境准备Node Yarn Berry Rust 一键就位1. 安装依赖工具打开终端确认你的环境满足以下要求版本均已写死在仓库配置中照抄即可工具版本要求依据文件Node.js18–22推荐 22.16.0.nvmrcYarn4.9.1Berry仓库已内置package.json 的packageManager字段Rust1.87.0rust-toolchain.tomlDocker Compose最新版Orbstack 更佳tools/public/dev.md小贴士使用nvm管理 Node 版本执行nvm install nvm use即可自动读取 .nvmrc 切到 22.16.0。2. 克隆仓库并安装依赖git clone https://gitcode.com/gh_mirrors/op/open-agent cd open-agent yarn仓库通过 package.json 中的packageManager: yarn4.9.1声明了 Yarn 版本配合 .yarnrc.yml 中yarnPath指向的内置发行版即使你本机是 Yarn 1 也能无缝切换到Yarn Berry无需额外安装。首次执行yarn会自动触发 package.json 中的postinstall脚本先运行yarn oa init生成 Monorepo 工作所需文件再初始化 Husky 提交钩子。三、本地跑起来从 Docker 到yarn dev六步走按照 tools/public/dev.md 的流程6 步即可在本地看到完整应用安装依赖yarn上一步已完成启动后端依赖把.docker/dev/compose.yml.example复制为docker-compose.yml然后docker compose -f ./.docker/dev/compose.yml up配置环境变量在仓库根目录或 packages/backend/server/ 下创建.env按需填入数据库、AI 模型 API Key 等构建 Rust 原生模块只需一次yarn oa afk/server-native build可选数据库迁移(cd packages/backend/server yarn prisma migrate dev)启动开发服务器yarn dev启动成功后 Web 应用http://localhost:8080⚙️ 服务端GraphQLhttp://localhost:3010/graphql 登录时的邮箱验证码会发送到本地 MailHoghttp://localhost:8025如果端口被占用可调整OPEN_AGENT_SERVER_PORT或修改 packages/frontend/app/rspack.config.js 中的 devServer 端口。四、效率神器oa CLI 让 Monorepo 操作更简单仓库自带了一个强大的 Monorepo CLI源码见 tools/cli/用法详见 tools/cli/README.md常用命令yarn oa -h # 查看全部帮助 yarn oa init # 重新生成 Monorepo 工作文件 yarn oa clean --dist --rust # 清理构建产物 yarn oa web dev # 指定工作区跑 dev 脚本也可以直接使用 package.json 里定义的组合脚本yarn dev # 同时启动前端 服务端 yarn dev:web # 只启动 afk/app 前端 yarn dev:server # 只启动 NestJS 后端五、提交 PR 前必过质量检查清单 ✅这是贡献流程中最关键的一步——先自检再提交。提交前请务必在仓库根目录执行pre-commit run --all-files它背后是一整套自动化保障体系检查项命令说明ESLintyarn lint:eslint基于 eslint.config.mjs含 React、TS、排序等规则格式化yarn lint:prettierPrettier 全仓格式统一快速 Lintyarn lint:ox基于 Rust 的 oxlint秒级反馈类型检查yarn typechecktsc -b全项目类型构建单元测试yarn testVitest 全量运行详见 vitest.config.ts此外还有三层自动关卡帮你把关Husky lint-staged.husky/pre-commit 钩子在每次git commit时只对暂存文件跑 PrettierTS/JS和 taploTOML、cargo fmtRust规则见 package.json。Conventional Commits提交信息需符合规范如feat:、fix:、docs:、chore:配置见 tools/commitlint/package.json。PR 标题 LintCI 中的 pr-title-lint.yml 会校验你的 PR 标题是否符合 Conventional Commits 规范标题不合格会被直接拦截请特别注意六、提交你的第一个 PR完整流程 万事俱备下面是新手最顺畅的路径选任务从简单的开始——修复文档错字、补充测试、改进 UI 文案都是绝佳的破冰贡献拉新分支git checkout -b fix/my-first-change修改代码动手吧小步提交更容易被 review本地自检pre-commit run --all-filesyarn typecheckyarn test规范提交git commit -m fix: 修正 dev.md 中的启动说明推送并发起 PR推送到你的 fork 仓库再向主仓库发起 Pull Request标题用 Conventional Commits 格式 遇到问题先在 issue 区搜索或加入项目 Discord 社区提问维护者们对新手非常友好。七、新手常见问题 FAQQ1yarn报错说 Node 版本不对项目要求node 23见 package.json用nvm use 22切换即可。Q2Yarn Berry 和经典 Yarn 有什么区别Yarn Berry4.x是官方新架构使用零安装 PnP 方案通过packageManager字段自举版本由 .yarnrc.yml 精确锁定团队协作更稳定。Q3我只想改前端需要装 Rust 吗需要。postinstall会构建原生模块源码在 packages/backend/native/一次性构建后即可缓存。Q4改了blocksuite/下的文件要跑哪些测试yarn test会按 vitest.workspace.ts 自动覆盖根目录和 blocksuite 下所有vitest.config.ts也可用yarn test:ui打开可视化界面调试。下一步跑通本地环境后建议通读 README.md 中的部署章节再挑一个你感兴趣的小 issue 开始你的第一个 PR。祝你在 Open-Agent 的开源 AI Agent 之旅中玩得开心✨【免费下载链接】open-agentOpen-source alternative to Claude Agent SDK, ChatGPT Agents, and Manus.项目地址: https://gitcode.com/gh_mirrors/op/open-agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
