background-agents贡献者指南Monorepo测试策略、lint复杂度约束与代码规范【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agentsbackground-agents 是一个开源的后台智能体background agents编码系统你发出提示词后AI 会话在云端沙箱中独立运行你可以合上电脑稍后回来审查 PR。本文带你完整走一遍这个 Monorepo 的贡献者指南——从环境搭建、三层测试策略到两个自研 lint 检查脚本和代码规范帮你快速提交第一个合格的 PR。 项目一览Monorepo 结构速览上图是 background-agents 的 Web 控制台左侧是会话与自动化列表右侧是向后台智能体下达任务的入口。整个仓库采用 npm workspaces Monorepo 组织核心包如下包语言/框架职责packages/control-planeTypeScript / Cloudflare Workers Durable Objects会话生命周期、WebSocket 流、GitHub 集成packages/webTypeScript / Next.js React用户界面、OAuth、实时会话面板packages/sandbox-runtimePython JS沙箱内智能体运行时packages/modal-infraPython 3.12 / Modal沙箱生命周期、快照、镜像构建packages/sharedTypeScript共享类型、鉴权工具、模型定义packages/slack-bot等TypeScript / Workers HonoSlack、GitHub、Linear 三方触发器架构上分为三层通过 WebSocket 串联Web 客户端 → Control Plane会话中枢→ Data PlaneModal 沙箱。改动前建议先通读 AGENTS.md 和 docs/HOW_IT_WORKS.md两者包含完整的架构说明与依赖图。 环境搭建一键安装与构建顺序克隆仓库后最快的上手路径git clone https://gitcode.com/GitHub_Trending/ba/background-agents cd background-agents bash .openinspect/setup.sh # 安装依赖、构建 shared 包、配置 husky 钩子也可以手动执行分步操作见 CONTRIBUTING.mdnpm install npm run build -w open-inspect/shared # ⚠️ shared 必须最先构建 npm run typecheck npm run lint npm test关键坑位open-inspect/shared是其他所有包的依赖改了共享类型后必须先构建它根目录npm run typecheck与npm run build已自动帮你处理了这个顺序见 package.json。环境要求 Node ≥ 22.13.0。 Monorepo 测试策略三层布局所有 TypeScript 包使用VitestPython 包使用pytest测试文件位置各有约定单元测试与源码同目录control-plane 单测src/**/*.test.ts运行在 Node 环境配置见 packages/control-plane/vitest.config.tsweb / slack-bot / linear-bot同样同目录src/**/*.test.tsgithub-bot例外单独放在test/*.test.tsmodal-infratests/test_*.py配合 pytest-asyncio按包运行测试非常直观npm test -w open-inspect/control-plane # 单测 npm test -w open-inspect/slack-bot cd packages/modal-infra pytest tests/ -v # Python 侧根目录 vitest.workspace.ts 把所有包的vitest.config.ts汇聚成一个工作区一条npm test全仓库跑完。集成测试在真实 workerd 运行时里跑control-plane 是本项目最重的部分它另有一层集成测试npm run test:integration -w open-inspect/control-plane配置在 packages/control-plane/vitest.integration.config.ts要点通过cloudflare/vitest-pool-workers的cloudflareTest()插件在真实 workerd 运行时中执行并绑定真实 D1terraform/d1/migrations/下的全部 SQL 迁移会自动应用无需手工建表pool-workers 按测试文件隔离 D1 存储同一文件内的用例共享一个 D1 实例因此务必在beforeEach/afterEach中调用cleanD1Tables()防止数据串染常用辅助函数在test/integration/helpers.tsinitSession()、queryDO()、seedEvents()给新手的核心建议涉及会话、调度、WebSocket 的改动光写单测不够补一个集成用例才能覆盖 Durable Object D1 的真实行为。Python 侧pytest ruff 双保险cd packages/modal-infra ruff check --fix ruff formatRuff 规则集中在 ruff.toml目标 Python 3.12、行宽 100启用了 bugbear、pyupgrade、type-checking 等规则组测试文件额外豁免了部分规则。 Lint 复杂度约束两个容易忽略的自研检查除了标准的eslint .与prettier这个仓库还有两个自研 lint 脚本CI 中都会执行lint:complexity —— 圈复杂度热区报告npm run lint:complexity # 文本报告 npm run lint:complexity -- --json # 结构化报告脚本 scripts/lint-complexity.mjs 用 ESLint 的complexity规则扫描全部packages/**/*.{ts,tsx}输出按复杂度排序的生产代码热区表。值得了解的三个设计决策热区阈值 20圈复杂度超过 20 的函数会被列入报告见 scripts/lint-complexity.mjs测试文件单独统计测试代码不计入生产热区表避免为了凑覆盖率写出的大函数污染报告仅报告、不阻断复杂度发现不影响退出码——它是一份持续观察的技术债仪表盘而不是硬门槛。提交大型重构前跑一次可以看看自己碰的模块是否已是热区lint:sql-portability —— 可移植 SQL 子集检查npm run lint:sql-portabilityscripts/lint-sql-portability.mjs 检查 control-plane 存储层的 SQL 是否踩了SQLite 专属语法因为 Postgres 是计划中的新引擎现在写一条 SQLite-only 语句将来就要付出迁移双胞胎的代价。被拦截的典型写法与可移植替代❌ 不要写✅ 请写成INSERT OR IGNORE / REPLACEON CONFLICT DO NOTHING / DO UPDATE SET?1、?2编号占位符顺序?按出现顺序绑定unixepoch()、strftime(...)在 TypeScript 里传Date.now()并格式化json_object(...)等 JSON 函数在 TS 中构造 JSON 再作为参数绑定AUTOINCREMENT、CREATE TRIGGER、PRAGMA应用层生成 ID / 在 store 里约束 / 留在引擎适配器中完整子集与易错点说明见 docs/PORTABLE_SQL.md。一个精巧的设计历史遗留的例外被逐条登记在 scripts/sql-portability-baseline.json 中写明具体文本与保留理由数量采用棘轮机制——新增一处会失败擅自删减一处也会失败确保技术债清单始终诚实。 代码规范与提交约定命名规范把单位写进名字里AGENTS.md 中最重要的几条约定Python 用秒TypeScript 用毫秒与各自生态一致Modal 的timeout收秒control-plane 全程_MS后缀禁止裸用timeoutPython 写timeout_secondsTypeScript 写timeoutMs/INACTIVITY_TIMEOUT_MS默认值只定义一次抽成命名常量到处 import注释里写Defaults to DEFAULT_SANDBOX_TIMEOUT_SECONDS而不是重复字面量Default: 7200顺手修坏味道把一个既有字段穿进新代码路径时若发现命名/单位本身有问题就在同一次改动中修掉而不是把问题扩散开ESLint 关键规则eslint.config.js 基于 typescript-eslint React Hooks几条会直接影响你代码的规则consistent-type-imports强制类型导入import typenpm run lint:fix可自动修复no-unused-vars下划线前缀的变量/参数被豁免no-explicit-any警告级尽量避免anyno-restricted-imports鉴权相关符号必须从子路径导入例如open-inspect/shared/auth而非包根——这是有意维护的模块边界报错信息会直接告诉你正确的导入路径提交前记得用npm run lint:fixnpm run format或者交给 huskylint-staged 会在 pre-commit 阶段对暂存的 TS/TSX 自动执行eslint --fixprettier --write对 Python 文件执行ruff check --fixruff format配置见 package.json。提交信息Conventional Commits使用规范化提交主题行控制在72 字符以内细节放 PR 描述而非 commit messagefeat: add new feature fix: resolve issue with X docs: update documentation refactor: restructure module chore: / test: ...✅ 常见踩坑清单提交 PR 前自查构建顺序改了open-inspect/shared却没先构建它下游包的类型检查会满屏报错GitHub App 私钥格式Cloudflare Workers 要求 PKCS#8用openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt转换Durable Object 新绑定需要两阶段 Terraform 部署先enable_durable_object_bindings false再置true没有 wrangler.tomlcontrol-plane 的配置由 Terraform 生成仓库里查不到是正常的Modal 部署在packages/modal-infra下先跑uv run python deploy.py --build-sandbox-image再uv run modal deploy deploy.py直接部署src/app.py不会导入任何函数模块标准 PR 检查单npm test全绿 →npm run lint通过 →npm run typecheck通过 → 两个自研 lint 脚本通过 → 文档同步更新。CI 在每次推送与 PR 上都会执行 lint、typecheck 与全量测试推送main还会按变更范围自动部署对应服务。延伸阅读贡献流程与 PR 规范CONTRIBUTING.md架构与会话生命周期docs/HOW_IT_WORKS.md可移植 SQL 子集详解docs/PORTABLE_SQL.mdControl Plane 测试与集成说明packages/control-plane/README.md准备好后从docs:或fix:类型的小 PR 开始就是融入 background-agents 社区的最佳方式。【免费下载链接】background-agentsAn open-source background agents coding system项目地址: https://gitcode.com/GitHub_Trending/ba/background-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考