LobeHub 仓库开发指南解读面向 AI 编码 Agent 的架构约定、命令工作流与 Skill 体系【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub导读LobeHub 是一个将 AI 团队编排为 7×24 小时自动化运营的 Agent 平台其开源仓库规模庞大src/features/下数千个文件、apps/与packages/承载桌面端、CLI、服务端与共享包。为了让人类开发者与 AI 编码 Agent 在同一套约束下高效协作仓库根目录的 AGENTS.md 定义了一套仓库级的开发宪章它规定了技术栈、目录分层、SPA 路由拆分方式、开发命令、Git 工作流、质量检查与 i18n 流程。阅读本文后你将掌握 LobeHub 仓库的分层架构心智模型、可复现的本地开发与质量验证命令以及仓库级规则 Skill 级细节的 Agent 协作范式。AGENTS.md 在仓库中的定位规则单一事实源在 LobeHub 中AGENTS.md 并不是一份摆设它是为在本开源仓库中工作的 AI 编码 Agent 准备的开发准则文档自述Guidelines for using AI coding agents in this opensource LobeHub repository。它与根目录的 CLAUDE.md 一类文档共同构成了 Agent 的上下文入口但分工明确AGENTS.md 拥有仓库级repository-wide的架构与工作流定义详细的实现规则下沉到 skills 中让每个规则只有一处事实来源。也就是说AGENTS.md 只回答仓库长什么样、规则是什么、命令怎么跑而怎么写一个符合规范的 React 组件、怎么拆分重领域页面这类具体实现细节被收敛到.agents/skills/目录下独立的 skill 文件中。仓库中实际维护着 60 个 skill如react、compose-atoms、spa-routes、deep-review、zustand、trpc-router等每个 skill 都自带 front-mattername/descriptiondescription 明确描述了该 skill 的适用触发场景方便 Agent 按需检索加载。这种顶层少而稳、细节多而专的分层正是该仓库 Agent 协作体系的核心设计。技术栈一览一份可验证的选型清单AGENTS.md 开篇即给出技术栈速览而这些声明都能在仓库中逐一印证关注点选型仓库佐证框架与语言Next.js React TypeScriptpackage.json 根依赖前端形态Next.js 内部承载 SPA路由由react-router-dom负责src/spa/routerUI 实现lobehub/ui、antd、antd-stylereact skill 中组件选型优先级国际化react-i18nextpackages/locales/src/default 下的 namespace 文件状态管理zustandsrc/store数据请求 / 类型安全后端SWR TRPCsrc/servicesORM / 测试Drizzle ORM PostgreSQLVitestpackages/database、各包vitest.config.mts这套选型的核心意图是类型安全贯穿前后端TRPC 提供端到端类型安全的 RPC 边界Drizzle ORM 让数据库 schema 与代码保持同构Vitest 则支撑起从单测到回归测试的统一验证。Agent Skills 体系何时必须先读再改AGENTS.md 明确要求在改动特定类型代码前必须先读取对应 skill避免 Agent 凭泛化经验行事React 与 TSX在编辑组件、组件状态、渲染边界或做 memoization 优化之前必须先读 .agents/skills/react/SKILL.md。该 skill 拥有组件选型、样式、状态局部化与渲染性能规则的所有权。重领域功能当需要把一个臃肿的 Viewer/Page 拆成可复用的片段page、portal、share、micro-app 等宿主时先读 .agents/skills/compose-atoms/SKILL.md。它的拆分原则是按可挂载能力拆分而不是按视觉区块拆分并且不得用readOnly/mode标志去隐藏未使用的工作——因为被隐藏的模块仍然会随宿主被导入并打包。以 react skill 为例其 组件优先级 是src/components项目内组件 →lobehub/ui/base-ui无头原语若有同名根导出禁止绕道 import 根导出→lobehub/ui根导出 → antd → 自定义实现最后手段。它还特别提醒一个常见坑import { Select } from lobehub/ui表面正常实际拿到的是 antd 背书的 Select应改用 base-ui。compose-atoms skill 则提出了模块图拆分module-graph split的判据一个 atom 是宿主被允许不挂载的最小单元。判断粒度时自问是否会有某个宿主想要其余部分却跳过这一块如果是它就该是 atom如果否就留在父组件里。其状态下沉原则sink state强调imports follow the hook——如果useStore/handleAccept还留在页面装配器上那么该模块及其全部依赖仍会被每个挂载此页面的宿主打包带走。需要强调的是若只是把单个组件切成更小的文件不应使用该 skill而应回归 react skill。目录结构四层清晰的职责划分AGENTS.md 给出了仓库级目录地图节选自其 Project Structure可归纳为四个层次lobehub/ ├── apps/ # 可独立运行的端 │ ├── desktop/ # Electron 桌面应用 │ ├── cli/ # LobeHub CLI │ └── server/ # 后端服务Hono 应用 服务端路由/服务 ├── packages/ # 共享包lobechat/* │ ├── database/ # 数据库 schema、模型、仓储 │ ├── agent-runtime/ # Agent 运行时 │ ├── locales/ # i18n 源packages/locales/src/default/ │ ├── env/ # env schema/envs/* 指向 packages/env/src/* │ └── ... ├── src/ # Web 应用壳层 │ ├── app/ # Next.js App Router路由壳 鉴权 │ ├── routes/ # SPA 页面段薄层委托给 features │ ├── spa/ # SPA 入口与路由配置 │ ├── store/ # Zustand stores │ ├── services/ # 客户端服务 │ ├── libs/ # 应用壳共享的客户端/服务端助手 │ └── ... └── e2e/ # E2E 测试Cucumber Playwright需要特别留意的是src/app/与src/的分工。前端业务并不全部走 Next.js 的页面路由而是采用Next.js 承载 SPA的混合形态src/app/(backend)只放后端路由壳src/app/spa/负责 SPA 的 HTML 模板服务src/app/spa-auth/提供 SSR 的鉴权 HTML 壳。真正的 SPA 页面段在src/routes/业务逻辑在src/features/。SPA 路由架构roots vs features 的拆分纪律这是 AGENTS.md 着墨最深、也是本次解读最值得展开的架构章节。LobeHub 明确采用roots vs features拆分路由树只放页面段业务逻辑与 UI 全部落在 features 中。要理解这一拆分需先认识三个目录各自的被允许内容src/spa/SPA 入口与路由配置src/spa 存放 SPA 入口文件entry.web.tsx、entry.mobile.tsx、entry.desktop.tsx、entry.popup.tsx另有entry.auth.tsx以及 React Router 配置目录 src/spa/router。路由配置放在入口旁正是为了避免与src/routes/混淆。router 目录中除了各平台的desktopRouter.config.*、mobileRouter.config.tsx、popupRouter.config.tsx还包含运行时支撑routePreloadRegistry.ts路由预加载注册表、useRouteSkeleton.ts路由骨架屏与tabRouter.tsxElectron 多标签的内存路由。src/routes/只允许薄页面段src/routes/roots下仅允许三类文件_layout/index.tsx或layout.tsx该段的布局配合Outlet /index.tsx或page.tsx该段页面入口[param]/index.tsx如[id]、[cronId]动态段页面。这些文件必须保持薄只能从/features/*import 并做组合不允许携带业务逻辑或重型 UI。仓库实际分组与 AGENTS.md 描述一致src/routes 下存在(main)、(mobile)、(desktop)、(popup)以及auth/、onboarding/等特殊流目录。src/features/按领域的业务组件业务组件按领域domain组织如Pages、Home、PageEditor而非按路由路径组织。布局块sidebar、header、body、hooks、领域特有 UI 都放在这里每个 feature 通过index.ts或index.tsx暴露清晰的公开导出。由于一个路由可使用多个 feature一个 feature 也可被多个路由复用因此不允许在src/routes/内新建features/文件夹。新增/变更 SPA 路由的标准流程AGENTS.md 给出了四条操作步骤结合 spa-routes skill 可以还原为完整动作在src/routes/中只添加委托给 features 的路由段文件layout page在src/features/Domain/下实现布局与页面内容并从该目录导出路由文件中用import { X } from /features/Domain或import Y from /features/Domain/...引入共享的桌面内容路由只注册一次公共 Web/Electron 路径、嵌套、metadata、懒加载器与preloadId值都放在 src/spa/router/desktopRouter.shared.tsx。在此基础上薄的 desktopRouter.config.tsx 与desktopRouter.config.desktop.tsx只承载运行时差异Web 直接挂载内容树而 Electron 保留精简根桩并通过 tabRouter.tsx 在每个标签页的内存 router 中挂载同一棵树。只有路由真正与平台相关时才把代码放进平台适配器。由 desktopRouter.sync.test.tsx 守护这一共享行为与显式差异——修改路由时保持该测试通过。从设计动机看这套薄 roots 厚 features 单一共享桌面路由约束本质上是为了让页面段只承担组合职责任何新增页面都无需复制逻辑也避免了同一段路由在 Web 与 Electron 两套配置中重复维护导致漂移。启动开发环境三套命令与 Debug Proxy 原理AGENTS.md 给出了三种启动方式按需选择# SPA dev 模式纯前端API 代理到 localhost:3010 bun run dev:spa # 全栈开发Next.js Vite SPA 并行 bun run dev # 独立 Hono 后端服务 pnpm --filter lobechat/server devdev:spa在根 package.json 中定义为vite即直接启动 Vite dev server 作为纯前端同一脚本族还有dev:spa:auth、dev:spa:mobile等变体通过环境变量切换形态。dev定义为tsx scripts/devStartupSequence.mts由 scripts/devStartupSequence.mts 编排 Next.js 与 Vite SPA 的并行启动。后端独立运行时走 pnpm workspace filter指向apps/serverlobechat/server其运行时代码都位于apps/server/src通过/server/*导入。值得展开的是Debug Proxy机制。dev:spa启动后终端会打印一条形如下面的 URLDebug Proxy: https://app.lobehub.com/_dangerous_local_dev_proxy?debug-hosthttp%3A%2F%2Flocalhost%3A9876这条 URL 对应仓库中的 public/_dangerous_local_dev_proxy.html该页面从查询参数读取debug-host默认回退到http://localhost:9876并通过sessionStorage记住调试目标。打开此 URL 后线上环境app.lobehub.com会把你的本地 Vite dev server 的 SPA 加载进在线页面从而让你带着真实的服务器配置获得 HMR——即用本地代码开发、用线上后端调试。后端架构约束业务代码不进路由壳AGENTS.md 对后端代码放置有三条硬约束后端运行时代码位于apps/server/src通过/server/*导入src/app/(backend)只放 Next.js 路由壳不得在其中添加后端业务逻辑Web 壳层的辅助代码属于src/libs/*或相应的src/app段而不是src/server。换言之Next.js 在这里扮演的是接线员而非业务宿主路由壳只负责把 HTTP 请求转交给apps/server中真正的 Hono 服务与 server routers/services。理解这一点对 Agent 尤其重要——否则很容易把业务逻辑写进 App Router 的 route handler破坏后续将 SPA 与后端分离部署的结构。Git 工作流与包管理约定仓库的协作节奏由分支模型与提交规范约束分支策略canary是开发分支对应云端生产main是发布分支定期从 canary cherry-pick。新分支应从canary创建PR 应指向canary。git pull使用 rebase。提交信息以 gitmoji 表情前缀开头。分支格式type/feature-name。包管理方面采用双工具分工pnpm 管依赖bun 跑 npm scriptsbunx 跑可执行的 npm 包。这与根 package.json 的 scripts 实际定义一致如check: bun run .agents/scripts/check/cli.ts。配套的 commitlint.config.mjs 与 renovate.json 分别约束提交规范与依赖自动化。质量检查bun run check的纪律AGENTS.md 规定了唯一的质量入口并反复强调别乱跑全量测试bun run check [changed-files...]该命令对应根 package.json 中check: bun run .agents/scripts/check/cli.ts实际执行体是 .agents/scripts/check 下的一组脚本cli.ts、lint.ts、collect.ts、exec.ts、routing.ts等其质量纪律包括回归测试是硬要求每个 bug 修复必须附带一个修复前失败、修复后通过的回归测试。唯一豁免是纯样式/CSS 修复选择器、hover、遮罩、间距、颜色——此时唯一可行的断言只能是对样式源码做字符串匹配这种断言不算是值得交付的回归测试可以跳过。单次单遍无选择器时lint test应在同一次check中完成不要为每个选择器分别开一遍。--lint/--test/--type用于收窄范围且可在一次运行内自由组合。默认文件集合 工作区全部改动staged unstaged untracked显式传入路径会覆盖默认集合。--lint会自动修复给定文件并把修复内容以 diff 形式打印方便审查改动。--test会为给定源文件自动发现相关测试并在最近的所属 vitest 配置下运行例如packages/database无需手动cd进包目录。--type运行全量类型检查。严禁直接bun run test——全量套件需要约 10 分钟。需要手动跑单测如单个文件或特殊 flag时先cd进所属包再执行例如cd packages/database bunx vitest run --silentpassed-only [file-path]。i18n 工作流人机分工的翻译管线LobeHub 的国际化采用源文件 两个手写语言 CI 兜底其余语言的三段式加 key在 packages/locales/src/default 下的 namespace 文件中添加如agent.ts、auth.ts。手写 en-US 与 zh-CN在同一个 PR内完成——先在packages/locales/src/default/*.ts编写英文源镜像到locales/en-US/再手工翻译locales/zh-CN/。其余语言交给 CI每日 CI 工作流 .github/workflows/auto-i18n.yml 会运行bun run i18n并自动开启翻译 PR。在翻译 PR 合并前缺失的语言 key 会回退到英文。只有当立刻需要翻译后的语言而非等待每日工作流时才手动运行bun run i18n根 package.json 中定义为npm run workflow:i18n lobe-i18n prettier -c --write locales/**。AGENTS.md 特别强调该命令很慢且需要OPENAI_API_KEY且不要手工翻译生成的 locales——因为下一个 CI 周期会覆盖它们。代码风格与代码审查给 Agent 与人类的共同尺子文件尺寸红线AGENTS.md 建议单个文件超过约 800 行时考虑拆分为多个文件抽取子组件、hooks、helpers 或 types。理由并非玄学而是更小、更聚焦的文件对人类和 Agent 都更友好——这与compose-atoms与react两个 skill 共同构成了对抗巨型文件的完整方案react skill 负责把小组件拆小compose-atoms 负责把重领域按可挂载能力切分。deep-review skill 与设计价值观审查 PR / diff / 分支改动之前应先读deep-reviewskill。普通审查请求使用其轻量模式一名独立评审者对照各维度的快速检查清单完整的多子 Agent 深度模式只在显式调用时启用。仓库中可见该 skill 的维度清单包括逻辑、安全性、性能、可观测性、发布风险、复用架构、AI 编码坏习惯等见 .agents/skills/deep-review/references/dimensions且按 reviewer 场景区分 claude-code / codex。同时在设计或评审用户可见流程空态/加载态/错误态、确认、异步反馈、按钮层级、大规模列表、选择器时应遵循 LobeHub 的设计价值观Natural / Meaningful / Certainty / Growth自然 / 意义感 / 确定性 / 成长完整定义见 DESIGN.md 与配套的 DESIGN.dark.md。这套价值观不只是口号仓库中 ux skill 对四个维度逐一展开例如 Growth生长性被定位为更长周期的视角在塑造一个功能如何演进的体验时用来权衡。DESIGN.md 本身则是一份主题化设计规范——主色与中性色均可由用户配置并解析为 CSS 变量lobe-vars。总结从 AGENTS.md 看 LobeHub 的工程化方法论纵观全文AGENTS.md 的价值不在于罗列规则而在于其分层治理的思路规则有明确的归属层仓库级架构/工作流留在 AGENTS.md实现细节下沉到 60 个按需加载的 skill避免上下文膨胀与规则互相打架架构分层服务于可挂载能力SPA 采用 Next.js 承载 roots/features 拆分 单一共享桌面路由使 Web、Electron、移动端、popup 等宿主各取所需验证链路刻意收窄用bun run check单命令 自动发现相关测试替代全量跑一遍把 10 分钟的全量套件变成日常开发的禁区i18n 采用人机分工英文与中英双语由开发者手写保证质量其余语种交给每日 CI 的自动翻译 PR 兜底。对于要在本仓库中工作的开发者与 Agent 而言AGENTS.md 就是第一份必读文档——它决定了你在哪个目录放代码、用哪条命令验证、以何种纪律提交。【免费下载链接】lobehub LobeHub is your Chief Agent Operator, organizing your agents into 7×24 operations by hiring, scheduling, and reporting on your entire AI team.项目地址: https://gitcode.com/GitHub_Trending/lo/lobehub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考