Onyx 仓库 AI Agent 开发指南从环境初始化到多子项目协作的完整规范【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer本文以 Onyx原 Danswer开源仓库根目录的AGENTS.md为核心骨架系统梳理 AI Agent 在此仓库中工作的全部规范Python 依赖管理、测试密钥解析、本地调试入口、四层测试体系、Celery 任务约束、统一错误处理、计划文档格式与写作规范。读完本文你将能在 Onyx 仓库中独立完成从环境搭建、代码编写、测试验证到提交计划的完整闭环并理解这些规范背后的源码实现依据。一、Onyx 项目知识库概览这份文档在说什么Onyx原 Danswer是一个开源 Gen-AI 与 Enterprise Search 平台连接公司文档、应用与人员采用模块化架构同时提供 MIT 许可的 Community Edition 与 Enterprise Edition。根目录的AGENTS.md名为 PROJECT KNOWLEDGE BASE项目知识库是 AI Agent 在此仓库工作的总入口与总纲它不重复各子项目的细则而是给出全局性的关键注意事项KEY NOTES并逐级指向backend/、web/、mobile/三个子项目的专属 Agent 规范文件。整份文档的定位可以概括为四句话环境共识所有 Onyx 服务默认视为正在运行Python 依赖由uv管理的.venv提供入口共识调用后端 API 一律走前端代理http://localhost:3000/api/...而非直连:8080质量共识前后端全量严格类型标注代码注释简短且只保留长期有效信息协作共识写计划、写测试、写提交信息都遵循统一格式与简化技术英语。文档明确提示每个子项目都有自己的AGENTS.md在对应目录工作前必须先阅读——这是 Onyx 仓库分层治理的核心思想。二、环境初始化uv 虚拟环境与依赖同步仓库根目录的AGENTS.md第一条关键注意事项就是 Python 依赖管理所有 Python 依赖存放在仓库根目录由uv管理的虚拟环境.venv中若.venv尚不存在执行uv sync --frozen创建--frozen表示严格按uv.lock锁定版本安装不更新锁文件随后执行source .venv/bin/activate激活。从 CONTRIBUTING.md 可知更完整的初始化链路仓库要求Python 3.133.14 尚不被支持因为onnxruntime与 CUDAtorch尚未发布 3.14 wheel并建议显式创建虚拟环境uv venv .venv --python 3.13 source .venv/bin/activate uv sync之所以用uv sync --frozen而非pip install -r requirements.txt是因为仓库根目录维护了uv.lock锁文件与pyproject.toml配套锁文件可以保证团队成员与 CI 环境得到逐字节一致的依赖解析结果。前端web/与移动端mobile/则分别使用bun.lock管理 Node 依赖。如何验证服务在运行AGENTS.md假设所有 Onyx 服务均已启动。验证手段是检查backend/log目录api_server、web_server、celery_X等所有服务都会把日志 tail 到backend/log/service_name_debug.log文件中。若日志持续产生输出即说明服务正常。三、测试密钥的解析顺序aws_secrets.py的降级策略测试中需要的 API Key 等敏感信息统一由backend/tests/utils/aws_secrets.py解析解析顺序严格固定进程环境变量当前 shell 中已存在的os.environgitignore 的.vscode/.env文件通过复制.vscode/env_template.txt创建backend/AGENTS.md中的 pytest 命令也依赖它AWS Secrets Manager需要先执行aws sso login完成认证。从源码看其实现位于 _get_local_secrets先用os.environ.get(key.value)读环境变量再用dotenv_values(_DOTENV_PATH)读.vscode/.env该路径由os.path.join从文件所在目录向上回退三层得到_DOTENV_PATH实际指向仓库根目录的.vscode/.env。若本地仍未解析到则进入 _get_aws_secrets通过 boto3 以AWS BatchGetSecretValue批量拉取单次请求上限 20 个 secret IDAWS 区域默认us-east-2。测试用例通过pytest.mark.secrets(TestSecret.X)声明自己需要哪些密钥测试框架在收集阶段汇总所有标记再由 session 级 fixture 统一解析。文档明确要求如果某个你需要的密钥仍无法解析应询问用户而不是跳过测试——这保证了测试的完整性与可复现性。四、本地调试的既定入口AGENTS.md给出了三个高频操作入口1. Playwright 前端探索使用 Playwright 探索前端时使用固定账号登录用户名admin_userexample.com密码TestPassword123!该管理员用户由 Playwright 全局 setup 创建见web/tests/e2e/constants.ts。若该账号尚不存在可通过注册页注册——第一个注册的用户自动成为管理员。应用入口为http://localhost:3000。2. PostgreSQL 连接在宿主 checkout 或 devcontainer 中均可使用PGPASSWORD${POSTGRES_PASSWORD:-password} psql -h ${POSTGRES_HOST:-localhost} -U postgres -c SQL若宿主机没有psql客户端则降级为 docker exec注意Agent shell 没有 TTY因此不能加-itdocker exec onyx-relational_db-1 psql -U postgres -c SQL3. 后端调用一律走前端对后端发起调用时始终经由前端代理。例如调用http://localhost:3000/api/persona而不是http://localhost:8080/api/persona。这一约定确保认证、CSRF 等中间层逻辑不会因为绕过前端而被意外跳过。五、仓库布局与子项目分层规范技术栈总览层次技术选型后端Python 3.13、FastAPI、SQLAlchemy、Alembic、Celery前端Next.js 16、React 19、TypeScript、Tailwind CSS数据库PostgreSQL关系库 Redis缓存检索OpenSearch 支撑的关键词 向量文档索引认证OAuth2、SAML、多 Provider 支持AI/MLLangChain、LiteLLM、多种 embedding 模型三个子项目的规范边界backend/FastAPI 应用 Celery Worker。onyx/是 Community Edition 核心ee/镜像其目录结构承载 Enterprise 特性alembic/存放迁移脚本tests/为测试套件。专属规范见 backend/AGENTS.md。web/Next.js 前端。规范同时覆盖desktop/Tauri 壳。见 web/AGENTS.md。mobile/React Native Expo 应用。见 mobile/AGENTS.md。值得注意移动端与 Web 在多个关键点上完全不同——无 DOM、使用 NativeWind而非 Web 的 Tailwind、使用 expo-router、RN 原生组件因此不能假设 Web 规范适用于移动端。例如移动端间距类的数字直接等于像素px-24 24px而 Web 是 Tailwind 阶梯刻度p-6 1.5rem 24px两套命名体系物理尺寸相同但写法不同从 Web 移植组件时必须做N × 4的换算。文档还提醒不要依赖文档来获取完整包清单用ls直接浏览目录树更可靠。六、代码质量门槛pre-commit 与严格类型# 安装并运行 pre-commit 钩子 pre-commit install pre-commit run --all-files # 更快的做法只对你改动的文件运行 pre-commit run --files path [path ...]两条全局性 NOTE全量严格类型标注Python 与 TypeScript 皆如此。从 CONTRIBUTING.md 可知后端用ty check做静态类型检查uv run ty check前端用oxlint/oxfmt前端 oxlint 规则甚至对getattr这类会逃过类型检查器的写法做了专项禁止ods check-getattr动态查找必须附# ods: ignore[getattr]注释并给出简短理由。代码注释保持简短只保留长期有效的信息避免为当下此刻写一次性注释。七、写作规范ASD-STE100 简化技术英语AGENTS.md的 Writing 一节适用于所有输出文本文档、提交信息、PR 描述、报告与回复。核心规则来自 ASD-STE100简化技术英语只使用已批准词汇每个词只有一个含义一个概念用一个词表达不用两个词描述同一事物写短句指令性语句不超过 20 个词用主动语态写 Turn the switch不写 The switch must be turned写短段落每段只讲一个主题代码注释聚焦于长期有效或面向未来读者的信息。八、四层测试体系从单元到 E2EOnyx 的测试分为 4 类全部命令与指南位于 backend/AGENTS.md共享 fixture 与细节见 backend/tests/README.md。总体原则是优先写集成测试。测试类型前提假设典型场景运行命令单元测试Unit不假设任何 Onyx/外部服务可用外部交互用unittest.mock打桩复杂孤立模块如citation_processing.pyuv run pytest -xv backend/tests/unit外部依赖单元测试External Dependency UnitPostgres、Redis、MinIO/S3、OpenSearch 均在运行、OpenAI 可调用但 Onyx 容器不运行直接调用被测函数需要最小化 mock 但又要验证内部行为的场景uv run --env-file .vscode/.env pytest backend/tests/external_dependency_unit集成测试Integration对真实 Onyx 部署运行不可 mock 任何内容标准集成验证按目录级别并行uv run --env-file .vscode/.env pytest backend/tests/integrationPlaywright E2E全部服务运行含 Web Server需要显著前后端协调的场景cd web bun run playwright TEST_NAME要点补充真实 LLM 调用选廉价快速档OpenAI 用gpt-5-mini禁用gpt-4o/gpt-4o-miniAnthropic 用claude-haiku-4-5集成测试写完后应优先调用backend/tests/integration/common_utils中现成的 Manager 类而非直接requests调 API且优先用conftest.py的 fixture如admin_userfixture而不是自己UserManager.create(...)两个标杆示例confluence_group_sync 外部依赖测试 与 chat_stream 流式端点集成测试Playwright 命令使用bun run playwright脚本展开为playwright test避免bunx/npx静默拉取未固定版本的 Playwright。九、Celery 后台任务八类 Worker 与任务约束从 backend/AGENTS.md 与源码目录backend/onyx/background/celery/apps/可以相互印证 Onyx 的异步任务体系。Worker 应用分别定义在 app_base.py、primary.py、docfetching.py 等文件中周期调度表集中在 beat_schedule.py。Worker职责primary协调核心后台任务connector 管理与删除、文档索引同步、剪枝检查、LLM 模型更新、用户文件同步docfetching从 connector 拉取文档、派生 docprocessing 任务对卡死 connector 做 watchdogdocprocessing索引流水线upsert 文档到 Postgres、切块、经 model server 做 embedding、写块到文档索引、更新元数据light快速轻量操作元数据同步、权限 upsert、checkpoint/索引尝试清理heavy资源密集型操作剪枝、文档权限同步、外部组同步、CSV 生成monitoring系统健康监控与指标采集user_file_processing用户上传文件索引与项目同步scheduled_tasks执行用户排程Craft的任务运行beat周期任务调度器使用DynamicTenantScheduler支持多租户关键事实与硬性约束所有 Worker 使用线程池而非进程池——因此 Celery 的 time limit 特性被静默禁用、不会生效超时逻辑必须在任务内部自行实现多租户DynamicTenantScheduler会为每个 Beat 任务显式追加tenant_id到 kwargs直接发送任务时必须自行传播TenantAwareTask在缺少该字段时静默回退到默认 schema任务路由任务路由到命名队列并携带独立的高/中/低优先级OnyxCeleryQueues/OnyxCeleryPriority定义在 constants.py优先级为HIGHEST0到LOWEST的递增枚举Redis 协调进程间通信任务状态与元数据存在 PostgreSQL定义任务一律用shared_task而非celery_app任务放在background/celery/tasks/或ee/background/celery/tasks下必须设置过期时间发送任何任务都必须提供expires无论是来自 beat 调度还是其他任务否则可能导致任务队列无界增长——这是不可接受的。beat_schedule.py中的BEAT_EXPIRES_DEFAULT 15 * 6015 分钟就是为周期任务设计的默认过期值Worker 无热重载修改 Celery worker 后必须请用户重启 worker代码改动不会自动生效。十、数据库迁移Alembic 的标准操作所有alembic命令都必须在backend/目录alembic.ini所在处通过uv run执行# 标准迁移自托管 uv run alembic upgrade head # 多租户迁移Enterprise uv run alembic -n schema_private upgrade head创建迁移uv run alembic revision -m description uv run alembic -n schema_private revision -m description迁移内容需手工编写写入上面命令生成的 alembic 文件。仓库中 alembic/versions 目录下的数百个迁移文件即这一流程的产物命名遵循哈希_描述格式。另有一条数据库代码放置红线所有 DB 操作必须放在backend/onyx/db/backend/ee/onyx/db目录下不得在这些目录之外执行查询。十一、统一错误处理OnyxError取代HTTPException后端规范要求一律抛出onyx.error_handling.exceptions.OnyxError而非HTTPException严禁硬编码状态码严禁直接使用starlette.status/fastapi.status常量。从源码看OnyxError 接受OnyxErrorCode枚举、可选detail与status_code_overrideOnyxErrorCode 的每个成员是(error_code_string, http_status_code)二元组——error_code_string是稳定的机器可读标识如UNAUTHENTICATED、INVALID_TOKEN、NOT_FOUND供 API 消费方精确匹配。全局 FastAPI 异常处理器会把OnyxError统一转换为{error_code: ..., detail: ...}的 JSON 响应从而消除样板代码并保证全后端错误处理一致。from onyx.error_handling.error_codes import OnyxErrorCode from onyx.error_handling.exceptions import OnyxError # ✅ 推荐 raise OnyxError(OnyxErrorCode.NOT_FOUND, Session not found) # ✅ 推荐——无需附加消息 raise OnyxError(OnyxErrorCode.UNAUTHENTICATED) # ✅ 推荐——转发上游服务的动态状态码 raise OnyxError(OnyxErrorCode.BAD_GATEWAY, detail, status_code_overrideupstream_status) # ❌ 错误——直接使用 HTTPException raise HTTPException(status_code404, detailSession not found)新增错误类别时先在backend/onyx/error_handling/error_codes.py中定义不要临时发明 ad-hoc 错误码。十二、LLM 集成与可观测性每一次调用都必须打标签Onyx 的 LLM 调用统一经 LiteLLM模型按功能chat、search、embeddings可配置。可观测性上有一条硬规则每一次 LLM、embedding、rerank、图像生成、语音STT/TTS与意图分类调用都必须打开一个 generation span并使用LLMFlow注册表中的值打标签注册表见backend/onyx/tracing/flows.py。走LLM子类的调用llm_generation_span(llm..., flowLLMFlow.X, input_messages...)绕过LLM抽象、直接调用 provider SDK /litellm/ model_server HTTP 的调用traced_llm_call(flowLLMFlow.X, model..., provider..., input_messages...)。规则要点给新操作插桩前先添加新的LLMFlow枚举值禁止传裸字符串Flow 标签命名操作如IMAGE_EDIT、RERANK而非 providerprovider 信息放在model_config[model_provider]onyx/llm/tracing_wrap.py中的自动包裹回退逻辑会对未显式打 span 就到达LLM.invoke/LLM.stream的调用发出LLMFlow.UNTAGGED_INVOKE/UNTAGGED_STREAM哨兵标签——这些哨兵会出现在监控仪表板上意味着缺少插桩应修复调用点而非依赖回退机制。十三、日志约定在编写集成测试或进行 live 测试curl / playwright时可访问backend/log/service_name_debug.log获取日志。所有 Onyx 服务api_server、web_server、celery_X都会把日志 tail 到这个文件。十四、安全注意事项永远不要把 API Key 或密钥提交进仓库.vscode/.env位于 gitignore 中正是为本地密钥准备的使用加密的 credential 存储来保存 connector 凭据新功能遵循现有 RBAC 模式。十五、制定计划plans目录的必备要素当在plans目录gitignored不存在则创建编写计划时至少包含以下元素Issues to Address要解决的问题——此次变更的目标。Important Notes重要说明——调研过程中发现的、对实现重要的信息。Implementation strategy实现策略——实现变更的高层思路。Tests测试——计划编写哪些单元尽量少用、外部依赖单元、集成与 Playwright 测试来验证正确行为。不要过度测试通常一个变更只需要一种测试类型。明确禁止包含Timeline时间线、Rollback plan回滚计划。其他约束上述是最小清单可自由补充不要在计划中写代码保持高层抽象但可以引用某些文件或函数写计划前务必先做调研探索代码库相关部分。这一节与 CONTRIBUTING.md 的Trunk-based development呼应PR 真实改动不超过 500 行、频繁合并到 main、大功能用 feature flag 增量发布、flag 生命周期要短、在 API/UI 入口层打 flag 而非深入业务逻辑并且两个 flag 状态都要测试。十六、最佳实践索引根目录AGENTS.md明确除本文内容外代码库贡献的最佳实践完整清单见 CONTRIBUTING.md 的 Engineering Best Practices 一节Agent 需要理解并遵守其中的内容。该节覆盖原则与协作1-way / 2-way door 决策、一致性优先于正确、只修自己碰到的坏实践、不堆砌功能风格与可维护性在逻辑边界处写注释、异常要 fail loudly响亮失败而非静默跳过、避免过度 try/except、尽可能严格类型化、优先组合与函数式风格、用cast处理松散类型接口、避免魔法数字与魔法字符串性能与正确性避免长时间持有资源DB session、锁、connector 中任何随输入无界增长的内存结构必须周期性做尺寸检查OOM 常表现为缺失 celery tasks、不引入新的 async/event loop 代码仓库约定Pydantic 模型放models.py、DB 接口放db/、LLM prompt 放prompts/、API 路由放server/任何新增 TODO 必须附带负责人姓名/用户名或 issue 编号避免模块级 import 副作用不要把命令行脚本与可导入模块混为一谈。十七、快速参考核心路径速查表用途仓库相对路径项目总规范本文主题AGENTS.md后端规范Celery/迁移/测试/错误处理backend/AGENTS.md前端规范Opal 组件/样式/i18nweb/AGENTS.md移动端规范RN Expomobile/AGENTS.md贡献与工程最佳实践CONTRIBUTING.md测试密钥解析backend/tests/utils/aws_secrets.py统一错误码backend/onyx/error_handling/error_codes.py统一异常类型backend/onyx/error_handling/exceptions.pyCelery Worker 应用backend/onyx/background/celery/appsCelery Beat 调度表backend/onyx/background/celery/tasks/beat_schedule.py队列与优先级定义backend/onyx/configs/constants.py数据库迁移脚本backend/alembic/versions结语Onyx 仓库的根目录AGENTS.md是一份小而全的 Agent 协作协议它以 10 个要点覆盖了从环境准备到安全红线的最关键约定再以分层引用把测试、Celery、错误处理、前端组件、移动端特殊性等纵深规范分派到各子项目文档。对于想要参与这个开源 AI 平台的开发者与 AI Agent 而言先读透这一份文件再按需进入对应子项目的AGENTS.md是最高效的入手路径——它能帮你避开直连 8080 绕过认证任务不设 expires 导致队列膨胀提交未类型化的代码这类高频坑把精力集中在真正有价值的功能实现上。【免费下载链接】danswerOpen Source AI Platform - AI Chat with advanced features that works with every LLM项目地址: https://gitcode.com/GitHub_Trending/da/danswer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考