LobsterAI 开源贡献完整指南：桌面 AI Agent 开发环境、测试流水线与代码规范快速上手
LobsterAI 开源贡献完整指南：桌面 AI Agent 开发环境、测试流水线与代码规范快速上手
项目地址: https://gitcode.com/gh_mirrors/lo/LobsterAI LobsterAI 是网易有道开源的桌面级 AI Agent 应用（基于 Electron + React + OpenClaw），能完成数据分析、幻灯片、文档、视频与网络调研等真实工作。本文将带你快速完成 LobsterAI 开发环境搭建、跑通 Vitest 测试流水线，并掌握项目的 ESLint 代码规范 与 Conventional Commits 提交规范，帮助你从第一次 npm install 到提交第一个 PR 一路顺畅。
一键搭好开发环境：3 步开始贡献
环境要求清单
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Node.js | >=24.15.0 <25 | 由 package.json 的 engines 字段锁定 |
| npm | 随 Node 附带 | 无需额外安装 |
| Git | 最新版 | Windows 打包可能需要便携 Git：npm run setup:mingit |
拉取代码并安装依赖
git clone https://gitcode.com/gh_mirrors/lo/LobsterAI
cd LobsterAI
npm install
💡
npm install会自动执行patch-package与electron-builder install-app-deps（见 package.json 的postinstall），无需手动处理补丁。
首次启动：同步 OpenClaw 运行时
LobsterAI 的 Agent 能力由 OpenClaw 网关提供，版本锁定在 package.json 的 openclaw 字段中。
# 首次开发运行：自动构建/同步锁定版本的 OpenClaw 运行时，再启动应用
npm run electron:dev:openclaw
运行时构建完成后，日常开发只需一条命令（Vite 跑在 http://localhost:5175 + Electron）：
npm run electron:dev
如需指定本地 OpenClaw 源码路径或强制重建运行时，可参考 README_zh.md 中 OPENCLAW_SRC、OPENCLAW_FORCE_BUILD 等环境变量说明。
看懂架构：找到你要改的代码在哪
项目采用经典的 Electron 分层结构，完整模块地图见 AGENTS.md 的 Architecture Map：
| 目录 | 职责 | 典型入口 |
|---|---|---|
src/main/ | Electron 主进程：IPC、SQLite 持久化、OpenClaw 启动、IM 网关 | src/main/main.ts |
src/renderer/ | React + Redux Toolkit + Tailwind 渲染层 | src/renderer/App.tsx |
src/shared/ | 跨进程共享常量与类型（IPC 通道名、状态值） | src/shared/cowork/ |
src/scheduledTask/ | 定时任务模型、cron 服务与策略 | src/scheduledTask/cronJobService.ts |
tests/ | 独立测试目录 | tests/ |
📌 修改前先定位：Cowork 会话数据在 src/main/coworkStore.ts，OpenClaw 配置同步在 src/main/libs/openclawConfigSync.ts，架构细节可阅读 docs/architecture-openclaw-gui-cowork.md。
测试流水线：Vitest 是最小验证闭环
项目官方测试入口是 Vitest（package.json 中 "test": "vitest run"），GitHub CI 也是跑这条命令。
运行测试的 4 种姿势
# 1. 全量测试（CI 同款）
npm test
# 2. 按文件名过滤，只跑相关用例
npm test -- logger
npm test -- cowork
测试用例的发现规则定义在 vitest.config.ts：src/**/*.test.ts 与 tests/**/*.test.ts，运行环境为 node，超时 20 秒。
三条测试规范（新手最易踩坑）
- 新测试与源码同目录，命名为
xxx.test.ts，统一从 Vitest 导入describe / expect / test。 - 避免在测试中引入 Electron 专属 API（如
electron-log），应内联或抽取纯逻辑再测试。 tests/下存在基于 Node 内置node:test的遗留.test.mjs文件，不在默认npm test范围内，只有改动对应功能时才需显式运行：node --test tests/<file>.test.mjs。
UI / Electron 行为请用 npm run electron:dev 手动验证，参考 AGENTS.md 的 Testing 章节。
代码规范与质量门禁：一次通过 CI 的清单
ESLint：只对改动文件零容忍
CI 只对本次改动的 TypeScript 文件执行 lint（仓库存在历史 lint 债务，不要顺手全量清理）：
npx eslint --ext ts,tsx --report-unused-disable-directives --max-warnings 0 <files>
规则要点（完整配置见 eslint.config.mjs）：
- 启用
@typescript-eslintrecommended + React Hooks 规则 - 导入排序是 error 级：
simple-import-sort会自动要求导入按序排列 - 未使用变量告警，
_前缀参数/变量可豁免 - 禁止用宽泛的
eslint-disable绕过新引入的问题
字符串常量与 i18n 两条红线
- IPC 通道名、状态码、判别值禁止裸字符串，应集中在
as const对象中导出（示例见 AGENTS.md），跨进程常量统一放 src/shared/。 - 用户可见文案禁止硬编码，渲染层用 src/renderer/services/i18n.ts 的
t('key')，且必须同时补充 zh 和 en 两种翻译。
提交规范：Conventional Commits + Husky 钩子
项目通过 Husky 在提交时自动校验（.husky/commit-msg 调用 commitlint，规则继承 @commitlint/config-conventional，见 commitlint.config.mjs）：
feat(cowork): add streaming progress indicator
fix(sqlite): prevent duplicate session insert on retry
chore: bump version to 2026.6.18
- 分支命名用
feat/...或fix/...，commit message 使用英文 - 未经验证确认前不要擅自提交（参考 AGENTS.md）
提交 PR 前的自查清单 ✅
| 检查项 | 说明 |
|---|---|
| 改动文件 lint 通过 | --max-warnings 0 零告警 |
| 相关测试跑绿 | npm test -- <关键词> 过滤运行 |
| UI 改动附截图 | PR 描述中包含界面变化截图 |
| 主进程/IPC/runtime 改动 | 额外跑 npm run compile:electron 或 npm run build |
| 设计文档归档 | 按 specs/README.md 归入 features/、refactors/、bugfixes/，文件名 YYYY-MM-DD-<主题>.md |
| 无无关改动 | 提交前 review diff，避免顺手格式化/重构 |
💬 大文件改动请"小步收口"：若改动会显著增加超大文件的复杂度，先提出聚焦的抽取/重构方案，再经确认后实施（AGENTS.md）。
常用命令速查表
| 目的 | 命令 |
|---|---|
| 首次开发启动 | npm run electron:dev:openclaw |
| 日常开发启动 | npm run electron:dev |
| 生产构建 renderer | npm run build |
| 编译 Electron 主进程 | npm run compile:electron |
| 全量 lint | npm run lint |
| 跑测试 | npm test |
| 打包 macOS / Windows / Linux | npm run dist:mac / dist:win / dist:linux |
| 手动构建 OpenClaw 运行时 | npm run openclaw:runtime:host |
更多脚本细节见 package.json，完整开发流程说明见 README_zh.md。
社区一直在快速成长 🚀 —— 现在环境已就绪，选一个 good first issue，写一条符合规范的 commit，开始你的第一个 LobsterAI 贡献吧！
更多推荐
29
0- 0
已为社区贡献10条内容
所有评论(0)