LobeHub 的 GEMINI.md：Gemini CLI 上下文文件、AGENTS.md 开发规范与 Agent Skills 软链装配机制

人工智能AI 应用大模型AI Agent多智能体工具调用前端后端【免费下载链接】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 仓库根目录的 GEMINI.md 为主体拆解它作为 Gemini CLI 上下文文件的单点委托写法完整展开其引用的 AGENTS.md 中的技术栈、代码归属、开发流程与质量门禁等规范并结合 skillWiring.ts 源码说明 LobeHub 如何用一套.agents/skills符号链接机制让多套 AI 编码助手共享同一份技能库。读完后你将掌握在 LobeHub 这类大型 Monorepo 中为 Gemini CLI 配置上下文的最小成本方案以及如何复用仓库既有的开发、测试与验收规范。GEMINI.md 上下文文件一行指令的委托式写法GEMINI.md 全文只有一条有效指令Please follow instructions ./AGENTS.mdGemini CLI 支持在仓库级上下文文件GEMINI.md中用语法引用其他本地文件被引用的文件内容会随上下文一并加载。LobeHub 没有把开发规范直接写在GEMINI.md里而是把全部规范收敛到 AGENTS.md再由GEMINI.md一行委托。这种做法的收益是单一事实来源single source of truth——仓库同时服务 Claude Code、Codex、Cursor、Gemini CLI 等多套编码助手规范只维护一份任何工具接入都只需一个指针文件。从源码结构看这个指针角色还被工具链显式识别skillWiring.ts 中 Gemini 适配器的探测信号正是.gemini目录或GEMINI.md文件本身仓库里存在GEMINI.md即会被判定为当前仓库使用了 Gemini CLI从而触发后续的 skills 软链装配下文详述。AGENTS.md 核心规范一技术栈与代码归属技术栈AGENTS.md 开篇声明的栈如下这是所有贡献者包括 AI Agent必须遵守的实现前提层选型框架Next.js 16 React 19 TypeScript路由形态Next.js 内部嵌 SPA使用react-router-domUIlobehub/ui、antd、antd-style国际化react-i18next状态管理zustand数据请求 / 后端接口SWR / TRPC类型安全后端数据层Drizzle ORM PostgreSQL测试Vitest代码归属地图Code OwnershipAGENTS.md 给出了一张分层职责表核心边界是哪一层放什么代码apps/server/src后端运行时、routers 与 services统一通过/server/*导入src/app/(backend)只允许放 Next.js 路由壳禁止在此放业务逻辑。src/appNext.js 的 HTML/认证壳Web 壳辅助代码放src/libs或对应 app 段不进src/server。src/spaSPA 入口与 React Router 配置src/routes只放组合src/features的薄页面段业务 UI 与逻辑必须按领域放在 features 中。src/services与src/store客户端 API 服务与 Zustand 状态。apps/desktop、apps/cliElectron 与 CLI 应用packages/放共享代码文档列出 database、agent-runtime、locales 等。e2e基于 Cucumber Playwright 的端到端测试配置见 cucumber.config.js。一条容易踩坑的 SPA 路由约束修改 SPA 路由前先读spa-routes技能通用 Web/Electron 路径、metadata、懒加载器与preloadId应一次性注册在src/spa/router/desktopRouter.shared.tsxdesktopRouter.config*.tsx只保留平台差异并保持desktopRouter.sync.test.tsx通过不要在src/routes里创建features目录。Agent Skills 体系一套技能软链到所有助手目录AGENTS.md 明确分工AGENTS.md拥有仓库级架构与工作流细粒度实现规则放在 skills 中使其有唯一事实来源。技能库的物理位置是.agents/skills/仓库当前内置了 45 个技能目录如react、project-overview、compose-atoms、spa-routes、deep-review、zustand、data-fetching-architecture等。skillWiring.ts 的装配机制装配逻辑在 skillWiring.ts 中实现。该文件维护一张适配器Harness表L37-L50助手接收目录探测信号skills 子目录Claude Code.claude/skillsCLAUDE.md、.claudeskillsCodex.codex/skills.codexskillsCursor.cursor/skills.cursorskillsGemini CLI.gemini/skills.gemini、GEMINI.mdskillsOpenCode.opencode/skill.opencode、opencode.json(.c)skillRoo Code / Windsurf.roo/skills/.windsurf/skills同名目录skills装配规则linkOneHarness保证幂等与不破坏用户数据目标路径已是符号链接且指向.agents/skills→ 返回already不做任何事目标是真实目录用户可能在此存放助手私有技能→绝不覆盖只把当前技能单独软链进去linked-single否则创建harnessDir/skills - ../.agents/skills的相对符号链接L101-L107。当前仓库的实际状态印证了这套机制.gemini/skills与.claude/skills都是指向../.agents/skills的符号链接即一次安装/更新所有助手目录同步生效linkHarnessSkills 的注释原话。文件头注释还说明Codex、Cursor、Gemini CLI、Copilot/VS Code 与 Amp 本身就能直接读.agents/skills软链只为那些不能原生扫描该目录的助手兜底。技能的使用约定AGENTS.md 规定了技能与任务的触发关系React / TSX编辑组件、组件状态、渲染边界或记忆化之前先读react技能.agents/skills/react/SKILL.md它拥有组件选型、样式、状态局部性与渲染性能规则。重型领域功能拆分把臃肿的 Viewer/Page 拆成可复用件page / portal / share / micro-app前读compose-atoms技能——按可挂载能力拆分而非视觉分区并且不要用readOnly/mode开关隐藏未使用的逻辑。仓库地图定位代码层时读project-overview技能SKILL.md其中强调所列目录是关键位置精选图而非穷举树实际操作应对真实目录执行ls。acceptance 技能其源码托管在 lobehub/acceptance 仓库默认分支本地提交副本位于.agents/skills/acceptance/用bun apps/cli/src/index.ts acceptance update更新仓库特定的验收配置保留在.agents/acceptance/含 PROJECT.md、PROCESS.md 等文件。开发环境三种启动方式与 Debug ProxyAGENTS.md 给出三种官方启动姿势# SPA dev 模式仅前端API 代理到 localhost:3010 bun run dev:spa # 全栈开发Next.js Vite SPA 并发 bun run dev # 独立 Hono 后端服务 pnpm --filter lobechat/server dev对照 package.json 可核实这些脚本的真实落点dev:spa就是vitedev实际执行tsx scripts/devStartupSequence.mts见 devStartupSequence.mts即启动序列由独立脚本编排。dev:spa启动后终端会打印一个Debug Proxy地址Debug Proxy: https://app.lobehub.com/_dangerous_local_dev_proxy?debug-hosthttp%3A%2F%2Flocalhost%3A9876打开该 URL 即可把本地 Vite 开发服务器构建的 SPA 加载到线上环境中用真实服务端配置做带 HMR 的本地联调。仓库根目录下存在对应的 public/_dangerous_local_dev_proxy.html 页面入口。AGENTS.md 同时强调该代理是开发便利设施而非验收面——它让本地前端跑在生产后端、生产源站和生产数据之上产品验收必须在一个真正运行待交付分支的环境中进行具体用哪个面参见 .agents/acceptance/PROJECT.md 第 4 节。Git 工作流与包管理分支策略canary是开发分支对应云生产环境main是发布分支周期性从 canary cherry-pick。新分支从canary切出PR 目标也是canary。拉取方式git pull使用 rebase。提交信息gitmoji 前缀分支命名type/feature-name。包管理pnpm管理依赖、bun运行 npm scripts、bunx运行可执行的 npm 包。质量门禁bun run check统一入口是bun run check [changed-files...]对应package.json中的bun run .agents/scripts/check/cli.ts核心规则AGENTS.md回归测试要求每个 bug 修复都要有一个修复前失败、修复后通过的回归测试唯一可行断言是样式表源码字符串的纯样式/CSS 修复可跳过。选择器组合不带选择器 lint 相关测试--lint、--test、--type可自由组合。默认作用域是所有已暂存、未暂存与未跟踪的变更显式传入路径则覆盖该作用域。lint 自动修复会改文件需要审查它输出的 diff。测试使用最近的拥有方 Vitest 配置执行--type对整个仓库执行bun run type-check。永远不要直接跑bun run test那会执行全量测试套件。type-check 的实现bun run type-check实际执行bun --check --tsconfig-override tsconfig.type-check.json见 package.json 与 tsconfig.type-check.json即 Bun 内建类型检查器要求 Bun ≥ 1.4.3。--alint为可选项packages/alint/提供模型驱动规则覆盖 eslint 无法表达的判断类问题需要先配置 providerbun run alint:setup其发现项是修复或在 PR 中给出理由的警告。单包测试进入拥有方包目录执行例如cd packages/database bunx vitest run --silentpassed-only [file-path]。验收Acceptance与 i18n 流程产品验收是否触发产品验收由acceptance技能判定——打开 PR 或把 PR 标记为 ready 只是这个决策的检查点不是重跑验证的触发器。豁免范围纯文档/说明变更、无产品行为变化的纯重构或工具链变更、gitlink-only 同步gitlink 同步需链接上游变更及其既有验收。渲染 UI 文案的变更含 locale key 与翻译属于产品行为变化不在豁免之列——只断言 key 存在的测试无法证明页面真的渲染了文本。已有覆盖交付行为的验收应直接复用报告与证据只在本地时用lh acceptance run ingest检查并上传已发布则复用链接不要为了拿报告 URL 而重跑产品。需要验收时把已发布的https://app.lobehub.com/acceptance/id链接写进 PR 正文测试、lint、type-check 仍是独立的质量门禁不能替代产品验收。国际化新 key 加到packages/locales/src/default/的对应命名空间文件如 agent.ts。en-US 与 zh-CN 必须人工随同一 PR 交付英文源写在packages/locales/src/default/*.ts镜像到locales/en-US/locales/zh-CN/人工翻译。其余语言交给每日 CI 工作流AGENTS.md 指向.github/workflows/auto-i18n.yml它执行bun run i18n并自动开翻译 PR缺失的 locale key 在该 PR 合并前回退到英文。bun run i18npackage.json中为npm run workflow:i18n lobe-i18n prettier -c --write locales/**只在需要立即要出翻译产物时手动运行——它很慢且需要OPENAI_API_KEY且不要手改生成的 locale 文件。代码风格与评审约定文件体量单文件超过约 800 行时考虑拆分为多文件抽取子组件、hooks、helpers 或类型——小而聚焦的文件对人、对 Agent 都友好。代码评审评审 PR/diff/分支前先读deep-review技能普通评审请求走它的 light 模式单个独立评审者对照维度清单完整多子 Agent 深度模式只在显式调用时运行。设计价值观设计或评审用户可见流程空/加载/错误态、确认、异步反馈、按钮层级、大规模列表、选择器时遵循ux技能中定义的 LobeHub 设计价值观——Natural / Meaningful / Certainty / Growth自然 / 意义感 / 确定性 / 成长视觉 token 与文案语气见 DESIGN.md。小结LobeHub 的 GEMINI.md 本身只有一行./AGENTS.md委托指令但它示范了一种可复用的多 AI 助手接入模式规范单点收敛AGENTS.md→ 指针文件一行委托GEMINI.md 等→ 技能库目录统一 符号链接装配.agents/skills经 skillWiring.ts 铺到各助手目录。配合仓库既有的bun run check质量门禁、canary/main分支策略与 acceptance 验收流程任何通过GEMINI.md接入的 Gemini CLI 会话从第一次上下文加载起就运行在完整的 LobeHub 工程约束之内。赞分享人工智能AI 应用大模型AI Agent多智能体工具调用前端后端【免费下载链接】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点击查看免费下载相关推荐Sunshine 游戏串流完整指南从安装配对到首次串流Sunshine 游戏串流完整指南从安装配对到首次串流 Sunshine 是一款自托管游戏串流主机专门配合 Moonlight 客户端工作。它在你自己的电脑音视频后端ZCode CLI 工程开发规范从 AGENTS.md 到跨平台 Coding Agent 工具链的落地实践ZCode CLI 工程开发规范从 AGENTS.md 到跨平台 Coding Agent 工具链的落地实践 ZCode CLI 是 Z.ai 开源的 TypLobeHub Page Agent 架构解析PageEditor 文档编辑 Agent 的上下文注入与结构化工具调用机制LobeHub Page Agent 架构解析PageEditor 文档编辑 Agent 的上下文注入与结构化工具调用机制 Page Agent 是 Lobe人工智能AI 应用大模型AI Agent多智能体工具调用前端后端上一篇OpenProject终极指南5大核心功能打造高效项目管理体系下一篇如何快速使用智能二维码工具3个高效技巧指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考