Odysseus 贡献指南从分支模型、本地环境搭建到 PR 审查规范的完整实践【免费下载链接】odysseusSelf-hosted AI workspace.项目地址: https://gitcode.com/gh_mirrors/ody/odysseus本篇技术文章基于 Odysseus自托管 AI 工作区仓库的 CONTRIBUTING.md 展开系统讲解项目双分支模型dev/main的协作方式、Docker 与手动两种本地开发环境搭建、最小化检查命令的选取以及视觉风格与常量使用等代码规范。读完之后你可以按照项目维护者期望的格式提交可审查、可测试、可合并的贡献并理解这些规范背后的源码依据。分支模型所有 PR 一律指向devOdysseus 采用两条分支的协作模型见 CONTRIBUTING.mddev—— 所有 PR 的落地分支。此处内容可能处于变动中维护者会频繁使用 merge 按钮main—— 用户实际运行的版本由维护者挑选并测试每次发布时以 fast-forward 方式同步到dev的一个稳定提交。由此衍生出三条关键约定PR 必须开向dev而不是main。仓库的默认分支即devgit branch可见origin/HEAD - origin/devGitHub 的 base 下拉框默认值也是dev。如果误开到main直接在 PR 页点击 Edit 修改 base 即可无需 rebase。克隆仓库的用户默认落在dev上想运行经过挑选的稳定版本克隆后执行git checkout main。维护节奏上main的内容是策展 测试过的因此面向用户的稳定性问题应基于main的某个提交复现。开始贡献前的约定在动手之前CONTRIBUTING.md 提出了四条前置规则开新 issue 前先搜索已有的 issue 和 PR避免重复一个 PR 只做一个 bug 修复或一个功能除非 issue 本身讨论的就是结构调整否则避免大范围重写、纯格式化改动或大量移动文件大功能先在 issue 中描述实现思路再动手。本地环境搭建方式一Docker推荐路径Docker 是日常测试的推荐方式环境文件模板为 .env.examplegit clone 本项目仓库地址 cd odysseus cp .env.example .env docker compose up -d --build.env.example 中已注释好各配置项的用途例如LLM_HOST默认localhost与LLM_HOSTS逗号分隔的多个推理后端主机用于模型发现会扫描包括 Ollama 11434 在内的常见端口OLLAMA_BASE_URL/LM_STUDIO_URLDocker 环境下访问宿主机推理后端时的可选地址OPENAI_API_KEY仅在使用 OpenAI 模型时需要注释明确要求不要提交真实 key。docker-compose.yml 中宿主机端口映射为${APP_BIND:-127.0.0.1}:${APP_PORT:-7000}:7000——容器内始终监听 7000宿主机端口由APP_PORT控制这也是后文常量规范的落点之一。方式二手动 Python 安装3.11python3 -m venv venv source venv/bin/activate pip install -r requirements.txt python -m uvicorn app:app --host 127.0.0.1 --port 7000需要注意 CONTRIBUTING.md 中的明确声明Windows 未被主动测试当前 Linux 上的 Docker 或 Linux/macOS 手动安装是更稳妥的路径。运行检查只跑与改动相关的最小集合项目要求贡献者为自己的改动运行最小相关检查并在 PR 描述中说明跑了什么无法运行的检查要如实说明。基础三件套python -m pytest python -m py_compile app.py routes/*.py src/*.py node --check static/js/file-you-changed.jspytest覆盖 tests/ 下的 Python 测试py_compile快速验证入口与全部路由、核心源码可编译node --check只对你改动的static/js/模块做语法检查避免全量跑无关节点。涉及 Docker 的改动追加docker compose config docker compose up -d --build docker compose logs --tail120 odysseus聚焦测试按领域标签跑子集当改动集中在某个功能域时不必跑全量套件。仓库提供了聚焦测试选择器 tests/run_focus.py它基于 tests/conftest.py 在收集期动态注册的area_*/sub_*分类标记工作只构造 pytest 命令、不改变任何测试行为tests/run_focus.py --area security tests/run_focus.py --area services --sub-area cookbook tests/run_focus.py --fastCI 侧也提供了对应的 Focused test guidance 报告作业见 .github/workflows/ci.yml在 PR 上列出与改动相关的测试路径供参考而阻塞性检查仍以现有 CI 为准。测试编写规范本身由 tests/TESTING_STANDARD.md 定义辅助函数用法见 tests/README.md这两份文档对测试该怎么写的约束同样适用于贡献者。Pull Request 的合格要素一个好的 PR按 CONTRIBUTING.md 的标准应包含对 bug 或功能的简短说明改动涉及的文件或模块范围手动测试步骤或来自实际运行应用而非仅测试套件的自动化测试结果UI 改动附截图或短视频关联 issue 链接例如Fixes #123。核心原则是keep PRs small混合无关清理、格式化、重构与行为变更的大 PR 会显著增加审查难度。仓库还有配套的自动化门禁.github/workflows/pr-description-check.yml 对非 Bot 发起的 PR 校验描述与标题.github/workflows/issue-description-check.yml 对 issue 描述做同样的检查。给 LLM Agent 的专门约定如果你正驱动一个 AI 编码代理Devin、Cursor、OpenHands、Claude Code 等操作本仓库请先开 issue 描述问题而不是直接提 PR。与项目视觉风格或贡献格式不符的批量 agent 生成 PR 会被关闭且不进入审查——即便底层修复本身是正确的。视觉风格规范不改代码外观的许可同样重要Odysseus 有刻意为之的视觉风格CONTRIBUTING.md 明确忽略该风格的 PR 无论代码多正确都会被关闭且不合并。凡改动应用看起来的样子按钮、图标、字体、颜色、间距、布局、CSS、HTML、SVG或任何向 DOM 绘制内容的static/js/模块提交前必须本地运行应用并在浏览器中查看——类型检查和单元测试不够附上运行中应用的截图或短视频涉及移动端还要附移动端截图匹配既有视觉语言具体包括复用已有 CSS 变量--red、--fg、--bg、--card、--border等不引入新的颜色值、字号或间距单位复用已有的按钮、输入框、卡片、边框类名不要为相似组件另造一套样式UI 和代码中禁止 Unicode emoji使用与 static/index.html 中既有一致风格的单色内联 SVG或纯文本主 UI 文本使用等宽字体Fira Code字体文件在 static/fonts/static/js/theme.js中定义为 mono 字体族不要覆盖深色主题是默认任何浅色模式改动必须走既有主题系统不得硬编码。不新增平行组件应用里已有类似 widget 时扩展它而不是重写一个。这些规则与源码可互相印证。static/style.css 顶部声明了核心变量深色主题为--bg: #282c34、--fg: #9cdef2、--border: #355a66、--red: #e06c75浅色主题则通过同名变量的另一组赋值实现如--bg: #f5f5f5这正是浅色模式必须走主题系统的机制来源static/js/theme.js中mono: Fira Code, monospace的映射也证实了等宽字体的唯一入口。判断不确定一个改动是否属于视觉改动时文档给出的默认答案永远是是的附截图。代码规范路径与常量是唯一事实源CONTRIBUTING.md 中最有含金量的一节是常量规范其核心论点项目已经通过常量或 helper 暴露的值禁止在别处硬编码——硬编码字面量会随时间漂移、在非默认部署下出错并重新引入已修复的 bug。文件系统路径三条禁止事项不得用Path(__file__)...拼出源码树内的可写路径不得硬编码/app/...不得使用相对data/...字符串。每个持久化文件/目录在 src/constants.py 中都有命名常量。对照源码可以看到这一设计是真实的DATA_DIR是唯一读取ODYSSEUS_DATA_DIR环境变量的地方src/constants.pyDATA_DIR os.getenv(ODYSSEUS_DATA_DIR, get_default_data_dir())其下按功能分片定义了AUTH_FILE、USER_PREFS_FILE、SETTINGS_FILE、TTS_CACHE_DIR、CHROMA_DIR、VAULT_FILE、APP_DB等几十个命名常量src/constants.py。规范由此给出具体操作准则持久化路径一律 import 命名常量使用不要本地用os.path.join(DATA_DIR, x.json)或DATA_DIR / x.json重新推导DATA_DIR本身只用于没有固定名称的动态路径例如按 owner 划分的文件若某个数据文件/目录还没有常量先往 src/constants.py 添加一个注意部署差异Docker 中源码树只读而原生运行时/app/...不存在因此目录创建要做保护让不可写路径优雅降级而不是在 import 时崩溃。core/constants.py 的角色也值得注意它现在只是一个向后兼容的 shim全部符号重新导出自src.constants模块 docstring 解释了历史上两份副本曾各自漂移、core侧版本落后的教训这印证了单一事实源规范是项目用真实事故换来的。内部 API / loopback 地址不要硬编码http://localhost:7000应使用src.constants中的internal_api_base()。其解析顺序src/constants.py为ODYSSEUS_INTERNAL_BASE—— 显式覆盖例如 TLS 代理之后APP_PORT—— 组装为http://127.0.0.1:$APP_PORT与 docker-compose.yml 的端口注入一致兜底http://127.0.0.1:7000旧版默认值。这解释了为什么硬编码 localhost:7000在改了APP_PORT的部署里会悄悄失效。其他数值端口、上限、模型列表等已有常量就复用没有且值在多处使用时新增常量而不是复制字面量。需要而尚不存在的常量/helper一律加到 src/constants.py路径与配置的唯一事实源再 import。提交信息规范Conventional Commits提交信息采用 Conventional Commits 格式type(scope): summary例如fix(search): ... feat(notes): ... docs(contributing): ...常用 type 包括fix、feat、refactor、docs、test、chore、ci。要求主题行短小且用祈使句为什么改写入 body当它不明显时。Issue 报告规范Bug 报告必须包含安装方式Docker / 手动 Python / WSL 等、操作系统与浏览器相关时、精确复现步骤、期望与实际行为、日志/截图/终端输出。模型服务类问题额外要求后端类型Ollama、vLLM、SGLang、llama.cpp、LM Studio 等、模型名、GPU/CPU 与操作系统、Cookbook 任务日志或服务端日志。CONTRIBUTING.md 同时给出负面清单只有 help、does not work 或无上下文的截图的 issue 可能以不可操作关闭——这与 .github/workflows/issue-description-check.yml 的自动描述检查形成呼应。安全不要在 issue 或 PR 中粘贴 secret、API key、私有日志、个人文档或公网 IP安全漏洞报告按 SECURITY.md 的流程走而不是公开 issue。SECURITY.md 开头的定位值得贡献者牢记Odysseus 是拥有高权限本地能力的自托管 AI 工作区不应作为公开、未认证的服务运行。小结把 CONTRIBUTING.md 的规范浓缩为一张检查清单PR 开向dev一个 PR 一件事Docker 或 Linux/macOS 手动环境里真实跑起应用按改动面跑最小检查必要时用 tests/run_focus.py 聚焦并在 PR 中说明视觉改动必附截图且只复用既有 CSS 变量与组件所有路径/端口走 src/constants.py 的命名常量与internal_api_base()提交信息遵循 Conventional Commits。满足这些条件的贡献才符合这个项目focused, easy to review, and easy to test的筛选标准。【免费下载链接】odysseusSelf-hosted AI workspace.项目地址: https://gitcode.com/gh_mirrors/ody/odysseus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考