SurfSense 开源贡献指南从分支工作流到代码评审的完整实战手册【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense这篇指南面向想要为 SurfSense开源 NotebookLM 替代方案可通过一个平台、API 或 MCP Server 研究实时开放的互联网数据贡献代码、文档或想法的开发者。你将掌握该项目的贡献全流程三种贡献路径、main/dev分支保护模型、Docker 与手动两种开发环境搭建方式、pre-commit 自动化质量闸门Ruff、Biome、Bandit、Commitizen 等的真实配置以及从提 Issue 到 PR 合并的完整规范。所有结论均以本仓库实际文件CONTRIBUTING.md、.pre-commit-config.yaml、surfsense_backend/pyproject.toml、docker/docker-compose.dev.yml 等为事实依据。贡献前的准备三种主流参与路径在动手写代码之前SurfSense 建议你先加入官方社区保持同步Discord 社区承接最新动态、内部讨论与协作沟通随后根据自身情况选择下面三种路径之一1. 从 Roadmap 认领任务项目维护了一个公开 Roadmap上面有划分清晰的问题Issue与功能点可供认领。建议优先查找状态为Backlog或Ready的任务这两类通常是已确认可行、等待实现的工作项。2. 提议新功能如果你的想法不在 Roadmap 上按以下顺序推进先检索是否已有相同或相似的 Issue不存在则新建 Issue清楚描述功能或改进点等待维护者反馈与批准批准后即可开始准备 PR。3. 报告 Bug 或修复 Bug发现缺陷后创建 Issue 时务必包含四类关键信息复现步骤Steps to reproduce期望行为与实际行为Expected vs actual behavior环境详情操作系统、浏览器、版本号相关日志或截图logs / screenshots如果想直接动手修复同样欢迎——只需在 PR 中关联对应 Issue 即可。分支工作流main 由谁更新PR 必须打向哪里SurfSense 采用分支保护模型branch protection model保证main分支始终稳定分支用途谁可以合并main稳定 / 发布分支仅维护者从dev合并而来dev活跃开发与集成分支通过 contributor 的已批准 PRfeature/*、fix/*等个人工作分支贡献者向dev发起 PR三条必须遵守的铁律所有贡献者 PR 必须指向dev分支指向main的 PR 不会被接受main仅由维护者在准备发布时从dev合并更新创建功能/修复分支时始终基于最新的dev而不是main。从源码结构看这套模型配合后文介绍的自动化质量闸门pre-commit、CI共同构成了个人分支自由开发 →dev集成验证 → 维护者发布到main的渐进式发布链路。开发环境搭建前置条件与两种启动方式前置条件组件要求仓库中的实际依据Docker Docker Compose推荐使用或手动安装docker/docker-compose.dev.ymlNode.js文档要求 v18实际surfsense_web使用 Next.js 16 pnpm 10需要更新的 Node 版本见 surfsense_web/package.jsonPython文档要求 3.11实际pyproject.toml声明requires-python 3.12见 surfsense_backend/pyproject.tomlPostgreSQL需安装PGVector扩展compose 直接使用pgvector/pgvector:pg17镜像API Keys测试外部服务所需各连接器Reddit、YouTube、Instagram 等相关模块版本提示CONTRIBUTING.md 中写的 Node v18 / Python 3.11 是宽松下限仓库实际代码基于 Python 3.12 与 Next.js 16 构建配置项以仓库实际内容为准见 surfsense_backend/pyproject.toml。标准开发流程# 1. Fork 并克隆仓库 git clone https://github.com/your-username/SurfSense.git cd SurfSense # 2. 从 dev 创建自己的分支 git checkout dev git pull origin dev git checkout -b feature/your-feature-name方式 ADocker Compose 从源码构建推荐贡献者使用仓库根目录提供一套专门面向开发者的 compose 文件 docker/docker-compose.dev.yml它会从源码构建镜像并内置 pgAdmin、可观测性栈otel-lgtm等开发辅助工具与生产用的 docker/docker-compose.yml预构建镜像区分开docker compose -f docker/docker-compose.dev.yml up --build启动的关键服务及其职责来自 docker/docker-compose.dev.yml服务作用dbpgvector/pgvector:pg17挂载 docker/postgresql.conf健康检查pg_isreadymigrations短生命周期迁移容器执行alembic upgrade head并校验zero_publication逻辑复制 publication 与预期形状一致成功后退出 0redisredis:8-alpineCelery 的消息代理与结果后端backendFastAPI 后端端口 8000热挂载surfsense_backend/app源码到容器celery_worker/celery_beat后台任务 worker 与定时调度zero-cacheZero 实时同步缓存端口 4848依赖zero_publication已存在frontendNext.js 前端端口 3000pgadmin数据库管理面板端口 5050otel-lgtmGrafana Tempo Loki 一体化可观测性端口 3001值得注意的依赖顺序backend、celery_worker、celery_beat、zero-cache都通过depends_on ... condition: service_completed_successfully等待migrations成功迁移失败会中断整个栈避免 zero-cache 因 publication 漂移而崩溃重启。方式 B仅启动依赖服务跑在宿主机仓库还提供 docker/docker-compose.deps-only.yml只启动 Postgres、Redis、pgAdmin、Zero 与可选的 AzuriteAzure Blob 存储模拟器API、前端与 Celery 在宿主机运行# 从仓库根目录 docker compose -f docker/docker-compose.deps-only.yml up -d该文件头部注释还给出了宿主机侧的配置要点与本地 Celery 启动命令来自 docker/docker-compose.deps-only.yml后端.envDATABASE_URLpostgresqlasyncpg://postgres:postgreslocalhost:5432/surfsense后端.envCELERY_BROKER_URL/REDIS_APP_URL→redis://localhost:6379/0Web.envNEXT_PUBLIC_ZERO_CACHE_URLhttp://localhost:${ZERO_CACHE_PORT:-4848}# 本地 CeleryRedis 起来后在 surfsense_backend/ 下执行 uv run celery -A celery_worker.celery_app worker --loglevelinfo --concurrency1 --poolsolo --queuessurfsense,surfsense.connectors uv run celery -A celery_worker.celery_app beat --loglevelinfo⚠️ 关键注意事项deps-only 栈不构建后端镜像、也没有 migrations 服务。首次启动或拉取更新后必须先在本机执行cd surfsense_backend uv run alembic upgrade head再启动 zero-cache否则 zero-cache 会因找不到zero_publication发布而 crash-loop。配置服务配置 PostgreSQL 与 PGVector用上述 Docker 方式可免手动安装配置文件 ETL 服务Unstructured.io或LlamaIndex仓库pyproject.toml同时依赖unstructured[all-docs]、unstructured-client、langchain-unstructured与docling且 compose 中ETL_SERVICE默认值为DOCLING为要测试的外部服务添加 API Keys。项目结构三个核心组件与更多CONTRIBUTING.md 明确了 SurfSense 的三个主组件surfsense_backend/— Python/FastAPI 后端服务含 ETL 管道、索引管道、连接器、Agent、网关等见 surfsense_backend/appsurfsense_web/— Next.js Web 应用surfsense_web/appsurfsense_browser_extension/— 用于数据采集的浏览器扩展surfsense_browser_extension从仓库实际目录看项目远不止这三部分还包括surfsense_desktop/Electron 桌面端、surfsense_mcp/MCP Server、surfsense_obsidian/Obsidian 插件、surfsense_evals/评测脚本与数据以及docker/全套编排文件与scripts/版本号 bump 等工具。贡献前建议先通读对应子目录保持改动与既有模式一致。开发规范pre-commit 自动化质量闸门CONTRIBUTING.md 强调在开发前安装并配置 pre-commit hooks并理解提交时自动运行的检查。文档引用的独立指南文件./PRE_COMMIT.md在当前仓库中不存在实际的 pre-commit 配置位于仓库根目录 .pre-commit-config.yaml直接pre-commit install即可生效。它按阶段组织了一整套检查通用文件质量检查pre-commit/pre-commit-hooksv5.0.0check-yaml--multi --unsafe、check-json排除tsconfig.json与.vscode/*.json、check-tomlcheck-merge-conflict防止提交带冲突标记的文件check-added-large-files默认阈值--maxkb1024010MB防止误提交大文件debug-statements、check-case-conflict密钥泄露检测Yelp/detect-secretsv1.5.0使用--baseline .secrets.baseline基线文件并排除了*.env.example、tests/、alembic/versions/*.py、.github/workflows/*.yml、pnpm-lock.yaml、*.mdx、messages/*.json等白名单路径。Python 后端Ruffv0.12.5 Bandit1.8.6ruff与ruff-format只作用于^surfsense_backend/路径并排除测试文件lint 会自动--fixBandit 以 JSON 格式、--severity-level high --confidence-level high扫描安全缺陷排除tests/与alembic/。Ruff 的规则集在 surfsense_backend/pyproject.toml 中定义启用 pycodestyleE4/E7/E9、PyflakesF、isortI、pep8-namingN、pyupgradeUP、bugbearB、comprehensionsC4、printT20、simplifySIM与 Ruff 专属规则RUF行宽 88、目标 Python 3.12、格式化使用双引号。这与 CONTRIBUTING.md 要求的 PEP 8 Black 格式 在仓库中已演进为Ruff兼作 linter 与 formatter以实际配置为准。前端Biome 2.4.6以local hook方式运行见 .pre-commit-config.yamlcd surfsense_web npx biomejs/biome2.4.6 check --diagnostic-levelerror .格式化与 lint 规则集中在 biome.jsontab 缩进、行宽 100、LF 换行、双引号、强制分号semicolons: always、开启 import 自动排序organizeImports: on。注意surfsense_browser_extension的 Biome hook 当前在配置中以注释形式停用。提交信息校验commitizen-tools/commitizenv4.8.3commit-msg阶段强制使用Conventional Commits格式即 CONTRIBUTING.md 中的提交信息示例所对应的规范feat: add document search functionality fix: resolve pagination issue in chat history docs: update installation guide refactor: improve error handling in connectors全局配置default_stages: [pre-commit]、fail_fast: false意味着所有检查默认在 pre-commit 阶段执行但某一项失败不会阻止其余检查运行。Hook 的旁路--no-verify仅在必要时使用。代码风格速查后端Python PEP 8仓库实际以 Ruff 为准行宽 88前端TypeScript遵循现有代码模式Biome 强制格式格式化Ruff 负责 PythonBiome替代文档所述的 Prettier负责 TypeScript/JS/JSON/CSS测试要求新功能与 Bug 修复必须编写测试提交前确保既有测试全部通过API 端点需包含集成测试。仓库的测试体系佐证了这一点后端pyproject.toml配置 pytesttestpaths [tests]、asyncio_mode auto并声明了unit纯逻辑无需 DB/外部服务与integration需要真实 PostgreSQL两类 marker测试代码分布在 surfsense_backend/tests/unit 与 surfsense_backend/tests/integration前端使用 Playwright 做端到端测试脚本见 surfsense_web/package.jsontest:e2e、test:e2e:ui等配置在 surfsense_web/playwright.config.ts。分支命名从dev创建、名称有描述性feature/add-document-search fix/pagination-issue docs/update-contributing-guidePull Request 流程提交前检查清单与硬性要求提交 PR 之前先创建 Issue除非是微小修复Fork 仓库并从dev创建分支按开发规范完成修改充分测试如需更新文档打开指向dev分支的 PR。再次强调指向main的 PR 不会被评审或合并。若误开请将其 retarget 到dev。PR 的硬性要求目标分支必须是dev强制一个 PR 只做一个功能或修复保持聚焦在 PR 描述中关联相关 IssueUI 改动需附带截图或演示PR 标题与描述要清晰有信息量请求评审前确保CI 通过。代码评审从提交到合并的完整链路自动化检查必须通过CI/CD 流水线即上文 pre-commit 覆盖的质量关卡在 CI 中的延续至少一位维护者评审你的 PR及时、专业地处理反馈如被要求squash 提交以保持历史整洁合并成功即完成一次贡献。文档与代码注释的要求贡献时请同步维护文档资产新功能更新对应文档仓库文档集中在 docs 与 surfsense_web/content/docs复杂逻辑补充或更新代码注释后端改动同步更新 API 文档新功能提供示例。获取帮助与其他贡献方式遇到困难时按顺序尝试检索已有 Issue你的问题可能已有答案查阅官方文档在 Discord 社区提问若是 Bug 或功能请求创建 Issue。如果暂时不打算写代码仍有多种非代码贡献方式分享 SurfSense、在社区提供反馈、帮助 triage Issue 并验证 Bug 报告、改进文档与示例、撰写教程或博文。贡献者认可与 License所有贡献者都会获得认可出现在 release notes、列入贡献者名单、受邀加入贡献者专属 Discord 频道并有资格获得贡献者徽章。License 约定向 SurfSense 贡献即表示你的贡献将采用与项目相同的许可证LICENSE授权。至此从在哪认领任务到PR 如何被合并的完整贡献链路已经清晰。核心动作可以总结为一句话Fork → 从dev建分支 → 遵循 Ruff/Biome/Commitizen 等 pre-commit 关卡 → 写好测试 → 提交指向dev的 PR → 通过评审与 CI 后合入dev再由维护者发布到main。【免费下载链接】SurfSenseOpen-source NotebookLM alternative. Research the open web with live data(Reddit, YT, IG, TikTok, Indeed, Google Search, Maps etc) through one platform, API or MCP server. Join our Discord: https://discord.gg/ejRNvftDp9项目地址: https://gitcode.com/GitHub_Trending/su/SurfSense创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考