Helicone 开源 LLM 可观测性 Monorepo 工程指南从模块划分到 Agent 协作规范【免费下载链接】helicone Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 项目地址: https://gitcode.com/GitHub_Trending/he/heliconeHelicone 是一个开源的 LLM 可观测性平台本仓库采用 Yarn workspaces 管理的 monorepo 结构涵盖 Next.js 前端、TypeScript API 服务、Cloudflare Worker 代理、共享包以及基础设施配置。本文以仓库根目录的 AGENTS.md 为核心脉络面向希望参与该仓库开发、或希望理解大型 LLM 可观测性项目工程组织的开发者与 AI Agent系统讲解项目模块划分、构建测试命令、编码规范、测试体系、提交规范与安全配置并结合各工作区的 package.json 与源码结构给出可验证的落地点帮助读者快速上手贡献并保持代码库一致。一、Monorepo 结构与模块职责AGENTS.md 明确指出本仓库是由 Yarn workspaces 管理的 monorepo要求Node 20。根目录的 package.json 中workspaces字段定义了以下工作区workspaces: [bifrost, web, packages/*, valhalla/jawn, worker, e2e]每个应用/服务的职责如下目录类型职责web/Next.js 应用主控制台前端LLM 观测 Dashboardvalhalla/jawn/TypeScript API后端 API 服务Express TSOA处理数据查询、组织管理、计费等worker/Cloudflare WorkerLLM 请求拦截代理Proxy负责把请求转发给上游 Provider 并采集日志bifrost/站点/文档营销官网与文档站Next.jspackages/*共享包cost成本计算、filters过滤、llm-mapperProvider 映射、prompts提示词管理、pricing、secrets、common 等shared/共享代码跨服务共享的代理类型与工具函数sdk/SDKPython 与 TypeScript 客户端 SDKe2e/端到端测试面向 AI Gateway / 代理网关的端到端测试supabase/clickhouse/docker/examples/基础设施与示例数据库迁移、分析库、容器编排、集成示例根目录 package.json 的engines字段同样声明node: 20与 AGENTS.md 一致web/package.json中也能看到engines: { node: 20 }的重复约束。共享代码的演进值得注意的是AGENTS.md 将共享代码归纳为packages/*、shared/、sdk/三类。从实际仓库看packages/目录下除 cost、filters、llm-mapper、prompts 外还包括 pricing定价层级、secrets密钥管理、common通用工具等包packages/README.md 有更详细的包说明。web/package.json与valhalla/jawn/package.json中通过helicone-package/*依赖引用这些共享包例如helicone-package/cost、helicone-package/filters、helicone-package/llm-mapper、helicone-package/pricing、helicone-package/secrets这说明共享包是跨前后端复用的核心资产修改它们的影响面覆盖整个 monorepo。自动生成类型文件禁止手改AGENTS.md 特别列出了一批自动生成类型文件手动编辑会被覆盖且不应提交修改valhalla/jawn/src/tsoa-build/TSOA 自动生成的 OpenAPI/路由类型web/lib/clients/jawnTypes/前端根据 Jawn API 自动生成的客户端类型bifrost/lib/clients/jawnTypes/worker/supabase/database.types.tsweb/db/database.types.tshelicone-cron/src/db/database.types.tsvalhalla/jawn/src/lib/db/database.types.ts这些类型由genTypes.py见valhalla/jawn的 dev 脚本或 wrangler typegen见worker/package.json中的cf-typegen等工具在构建/开发时自动生成。在valhalla/jawn/package.json中可以看到dev脚本为concurrently nodemon nodemon -x python3 genTypes.py即启动开发服务时同步重新生成类型印证了这些文件的自动化来源。二、构建、测试与开发命令速查AGENTS.md 给出的命令均以 Yarn workspace 为单位执行下面补充实际 scripts 与路径验证。1. 安装依赖yarn在 monorepo 根目录执行一次即可安装所有工作区的依赖。yarn.lock位于仓库根目录。2. Lint 与修复yarn lint # 对 web 与 bifrost 依次执行 lint yarn lint:fix # 自动修复根目录 package.json 中lint脚本实际是对heliconeweb与bifrost两个 workspace 依次执行 lint任一失败则整体失败。worker的 lint 则由worker/package.json中的lint: tsc eslint --ext .js,.jsx,.ts,.tsx ./src独立定义先做 TypeScript 类型检查再做 ESLint。3. Web 应用主控制台yarn workspace helicone dev:local # 本地开发端口 3000 yarn workspace helicone build # 生产构建web/package.json中的实际脚本dev:local:next dev --turbo -p 3000dev:vercel env pull .env next dev --turbo -p 3000dev:better-auth:npx dotenv -e .env.better-auth -- next dev -p 3008使用 better-auth 认证的开发模式build:next buildpostbuild:next-sitemap构建后自动生成站点地图4. 后端 APIValhalla/Jawnyarn workspace helicone-api dev # 开发模式nodemon 热重载 genTypes yarn workspace helicone-api build # 生产构建tsup 打包valhalla/jawn/package.json中 dev 脚本会同时启动 nodemon 与类型生成还提供了dev:local、dev:us、dev:eu等按环境复制.env.*后启动的变体。start脚本为ts-node src/index.tsserve脚本运行构建产物dist/valhalla/jawn/src/index.js。5. WorkerCloudflare Workeryarn workspace helicone-worker dev # wrangler dev 本地开发 yarn workspace helicone-worker test # Vitest 测试worker/package.json中的测试脚本基于 Vitest并提供test:registryvitest registry-ts、test:debug等变体deploy使用wrangler deploycf-typegen生成 worker 配置类型。6. 共享包测试Packages在packages/下运行 Jest# 在 packages 目录内执行 npx jest # 运行特定测试例如成本注册表快照测试 npx jest __tests__/cost/registrySnapshots.test.tspackages/__tests__/cost/下已经存在的测试包括registrySnapshots.test.ts、modelCostFromRegistry.test.ts、usageProcessor.test.ts、model-parser.test.ts、sortAttemptsByPriority.test.ts、ensureOnlyOne.test.ts以及providers/子目录测试另有packages/__tests__/filters/与packages/__tests__/llm-mapper/分别覆盖过滤表达式与 LLM 映射器。7. Python 集成测试python tests/python_integration_tests.pytests/目录下还包含e2e_suite.py与requirements.txt仓库另在examples/、tests/test_data/中提供了对应测试数据。三、编码风格与命名约定AGENTS.md 明确了 TypeScript/React 的代码风格基线结合仓库实际可以进一步细化约定要求仓库佐证语言TypeScript / Reactweb/、valhalla/jawn/、worker/均为 TS 代码缩进2 空格各 TS/TSX 文件默认风格分号默认带分号ESLint Prettier 配置格式化Prettierweb/package.json、worker/package.json均有prettier依赖React 组件文件PascalCase.tsxweb/components/下组件命名工具函数camelCase.tsweb/lib/、packages/下工具文件测试文件*.test.ts位于__tests__/packages/__tests__/结构样式TailwindCSSweb依赖prettier-plugin-tailwindcss排序 classweb/package.json中同时存在prettier与prettier-plugin-tailwindcssESLint 门禁AGENTS.md 要求 ESLint 必须通过、PR 前修复所有警告。web的 lint 由next lint提供worker的 lint 额外叠加了tsc类型检查valhalla/jawn也依赖typescript-eslint体系。这意味着提交前至少应保证yarn lintweb bifrost与yarn workspace helicone-worker lintworker 含类型检查通过。四、测试体系与快照策略AGENTS.md 明确了三套测试框架并存Jestweb、packages、API、Vitestworker、Python 集成测试tests/。packages/cost强调快照测试packages/__tests__/cost/registrySnapshots.test.ts会动态扫描cost/models/authors/**/endpoints.ts将全部模型端点注册表与__snapshots__/目录中的快照比对防止成本配置被无意改动。这意味着修改任何模型成本配置时需要同步更新快照npx jest -u或等价操作。worker使用 Vitest cloudflare/vitest-pool-workers见worker/package.jsondevDependencies可以在本地模拟 Workers 运行时环境执行测试。valhalla/jawn使用 Jesttest:jawn脚本为npx jest --detectOpenHandles。e2e/是独立的端到端测试工作区e2e/package.json提供test、test:gateway、test:integration、test:rate-limit等细分脚本测试用例位于e2e/tests/下按nightly与on-push分组通过e2e/lib/中的 HTTP 客户端与测试辅助函数驱动真实网关。AGENTS.md 的测试建议是单元测试要有有意义断言适合场景用快照测试开 PR 前先在本地运行受影响工作区的测试。五、提交与 PR 规范Conventional Commits优先使用feat:、fix:、chore:、refactor:、docs:前缀示例格式为feat(web): add usage chart (#1234)。PR 内容清晰描述、关联 issue、UI 变更附截图、说明迁移脚本或环境变量更新。检查门禁lint、受影响工作区的 build、相关测试必须通过。根目录 package.json 的prepare: husky表明仓库通过 Husky 挂载 git hooks进一步保证提交前的代码质量检查。六、安全与配置注意事项AGENTS.md 的安全红线是绝不提交密钥以.env.example作为模板。仓库根目录存在 .env.example其中包含本地开发所需的完整占位配置VERCEL1 VERCEL_ENVdevelopment DATABASE_URLpostgresql://postgres:postgreslocalhost:54322/postgres NEXT_PUBLIC_SUPABASE_ANON_KEY... NEXT_PUBLIC_SUPABASE_URLhttp://localhost:54321 SUPABASE_SERVICE_KEY... SUPABASE_URLhttp://localhost:54321 NEXT_PUBLIC_HELICONE_RESTRICT_PROtrue NEXT_PUBLIC_BASE_PATHhttps://oai.helicone.ai/v1 NEXT_PUBLIC_HELICONE_JAWN_SERVICEhttp://localhost:8585 NEXT_PUBLIC_APP_URLhttps://us.helicone.ai注意示例中的 Supabase anon/service key 仅用于本地 Docker 环境对应docker/中的 supabase 容器默认值生产环境必须替换为真实密钥。各工作区还有独立的环境变量模板例如web/.env.example、valhalla/jawn/.env.example、docker/.env.example、examples/helicone-mcp/.env.example等开发时按需复制为.env.local或对应环境文件。按服务区分的密钥管理方式Webvercel env pull拉取远端环境变量或本地维护.env.local。Workerwrangler secret put NAME写入 Cloudflare 密钥与worker/wrangler.toml配合。数据库/配置参考 supabase/PostgreSQL 迁移、clickhouse/分析库迁移与 docker/ 进行本地搭建。七、Agent 协作规范面向 AI 编码助手的约束AGENTS.md 末尾专门为 AI Agent如 Claude Code 等给出了协作约定这也是本仓库工程治理的重要一环改动范围最小化只改动与任务相关的最小 workspace避免波及无关包。统一入口命令优先使用yarn workspace name cmd执行构建/测试/开发而不是在任意子目录直接运行裸命令。风格与验证保持代码风格一致提交前运行yarn lint并为改动补充针对性测试。从仓库现状看这些约束是有实际支撑的共享包packages/*被 web、API、worker 三方引用helicone-package/*在packages/中做修改时除了跑packages下的 Jest还应在受影响的上游 workspace 跑一次构建验证类型这与 CLAUDE.md 中修改 /packages 后运行npx jest __tests__/确保无回归的建议相互印证。八、快速上手从克隆到本地开发综合 AGENTS.md 与各工作区脚本一个典型的本地开发流程如下# 1. 克隆仓库并安装依赖Node 20 git clone https://gitcode.com/GitHub_Trending/he/helicone cd helicone yarn # 2. 按需启动各服务 yarn workspace helicone dev:local # Web 控制台端口 3000 yarn workspace helicone-api dev # 后端 API yarn workspace bifrost dev # 官网/文档站端口 3002 yarn workspace helicone-worker dev # Cloudflare Worker 代理 # 3. 质量检查 yarn lint # web bifrost yarn workspace helicone build # web 生产构建 yarn workspace helicone-worker test # worker 测试 npx jest __tests__/cost/registrySnapshots.test.ts # packages 快照测试数据库与分析库的本地环境可借助 docker/docker-compose.yml 启动Supabase 默认端口 54321/54322与.env.example中的 DATABASE_URL、SUPABASE_URL 对应。完成开发后按 Conventional Commits 提交并确保 lint、受影响 workspace 的 build 与相关测试全部通过再开 PR。结语AGENTS.md 是 Helicone 仓库的工程宪章它用最短的篇幅锁定了 monorepo 的模块边界、命令入口、风格基线、测试策略、提交规范、安全红线与 Agent 协作方式。配合各 workspace 的 package.json 与源码目录贡献者可以快速定位改动范围、选择正确的验证命令并以可被 CI 和 reviewer 接受的方式提交代码。对于希望在大型 LLM 可观测性项目中建立类似工程纪律的团队这份指南本身就是一份值得参考的 monorepo 治理样例。【免费下载链接】helicone Open source LLM observability platform. One line of code to monitor, evaluate, and experiment. YC W23 项目地址: https://gitcode.com/GitHub_Trending/he/helicone创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考