binance-trading-bot 贡献指南:从工程不变量到 CI 门禁的完整实践
binance-trading-bot 贡献指南:从工程不变量到 CI 门禁的完整实践
本文以仓库根目录的 CONTRIBUTING.md 为骨架,结合 AGENTS.md(工程章程)与 scripts/ci/lint.sh 等源码级证据,系统讲解向 binance-trading-bot 提交代码的完整流程:需要遵守的核心不变量、本地环境搭建、提交前必须通过的检查、Conventional Commits 提交规范,以及 CI 机器强制执行的各类门禁。读完你可以明确"什么样的 PR 会被合并",并能在本地复现 CI 的全部检查。
贡献流程总览:小而聚焦优先
binance-trading-bot 是一个单运营者维护的爱好项目(single-operator hobby project)。这意味着:
- 小而聚焦的 PR 会被合并;大型投机性 PR 通常不会。 如果你想做较大的改动,请先开一个 issue 说明意图,在投入时间之前先就方案形态达成一致。
- 安全漏洞不通过 Issue/PR 上报,而是遵循仓库根目录的 SECURITY.md 流程处理。
- Issue 与 PR 的提交通往上游 GitHub 仓库(
github.com/chrisleekr/binance-trading-bot,即本镜像的原始来源),具体地址以 CONTRIBUTING.md 原文为准。
一个 PR 能否合并,决定性因素是它是否违反仓库的"工程不变量"(invariants)。 无论代码本身多好,违反不变量就不会合并。这些不变量是工程章程的核心,全部记录在 AGENTS.md 中,是任何编码 Agent(Claude Code、Cursor、Codex 等)和人类贡献者的共同约束。
开工之前:必读工程章程与核心不变量
在动手写代码前,必须先通读 AGENTS.md。其中几条"承重墙"级不变量直接决定你的代码是否会被合并:
1. 策略是插件(Strategies are plugins)
添加一个策略意味着新建一个 package 加一条 registry 注册项,绝不修改 apps/api 或 apps/worker 的应用代码。从源码结构看,这一设计已被严格执行:
- 策略包集中在 packages/strategy/ 下,当前有
core(契约 + Executor)、trailing-trade、momentum、rebalance、registry等; - 注册的唯一入口是 packages/strategy/registry/src/index.ts 中的
buildStrategyRegistry(),它从@app/strategy-core创建 registry,并依次注册三个具体策略; - apps/api/src/strategies.ts 只是用
createApiStrategyRegistry(buildStrategyRegistry())包一层门面,负责 SPA 描述序列化,不直接 import 任何具体策略包。
配套的 scripts/ci/no-plugin-leak.sh 门禁扫描 apps/ 与 packages/ 的 import 位置,禁止出现 @app/strategy-*(除 -core 与 -backtest)和 @app/notify/providers/* 的越权导入,只允许 registry 引导文件豁免。
2. 钱一律是 Decimal
每一个价格、数量、金额、余额、盈亏都必须端到端使用 decimal.js 的 Decimal;number 只允许用于计数器、索引和毫秒时间戳。这条规则由 lint 强制执行:
- .oxlintrc.json 中
no-restricted-imports全局禁止apps/packages代码导入decimal.js,但 money-math 相关包(packages/money、packages/contracts、packages/strategy/*/__tests__等)通过overrides显式豁免; - 连 wire 层的序列化也是品牌化字符串
DecimalString,见 packages/contracts/src/decimal.ts,并有 scripts/ci/no-decimal-tostring-cast.sh 拒绝x.toString() as DecimalString这类手写强转; - docs/contributing/coding-rules.md 的 "Money on the wire" 一节详述了为什么
Decimal#toString()在toExpNeg/toExpPos阈值外会输出科学计数法(如3.6e-7),必须用asDecimalString等toFixed()格式化工厂保证纯十进制。
3. 策略与指标是纯函数
在 tick() 内部不允许任何 I/O、Date、Math.random;worker 会注入 Clock 和 RNG。这一点在 .oxlintrc.json 的 overrides 中写得非常直白:对 packages/strategy/*/src/**/*.ts、packages/indicators/src/**/*.ts、packages/discovery/src/**/*.ts 启用 no-restricted-globals(禁 Date、Math、process、performance)和 no-restricted-imports(禁 fs、net、http、crypto、ioredis、pg、drizzle-orm 等)。唯一的例外是 packages/strategy/core/src/replay.ts,被 excludeFiles 排除。策略的输出是一组纯数据决策,见 packages/strategy/core/src/decision.ts 中类型化的 Decision 联合:noop / place-order / cancel-order / replace-order / emit-event / set-kv / delete-kv。
4. 测试必须放在 <package>/__tests__/
测试绝不与 src/ 并列摆放。CI 通过 scripts/ci/no-colocated-tests.sh 扫描 apps/ 与 packages/ 下 */src/*.test.* 的路径,一旦命中即以 "co-located tests found under src/" 报错退出。理由在该脚本注释中写明:测试混进 src/ 会进入生产 tsc 依赖图并被带进发布的 dist 树。本仓库所有包(如 packages/contracts/tests/、apps/api/tests/)都遵守这一约定。
5. 注释说"为什么",不说"是什么"
代码注释不得携带 Issue / Spec / Phase / @see 引用——那段历史由 commit 与 PR 拥有。AGENTS.md 还补充了一条更细的规则:注释不要硬换行(hard-wrap),一段话一行,因为硬换行会让后续每次编辑都变成多行 reflow,diff 中真正改动的句子反而被淹没。这是 prettier.config.mjs 中 proseWrap: 'never' 的理由。
本地环境搭建
前置条件:
- Bun 运行时。CONTRIBUTING.md 原文写 "Bun 1.3+",但以仓库实际为准:根 package.json 声明
packageManager: bun@1.4.2、engines.bun: ">=1.4"。注意bun.lock的格式在 1.4 发生了变化,旧运行时会把 lockfile 倒写回旧版本(见 scripts/setup.ts 中requiredBunFloor()的注释)——所以请使用 1.4 或更高版本。还有 scripts/ci/no-bun-version-skew.sh 门禁要求仓库内九处 Bun 版本 pin 全部一致。 - Docker + compose 插件。scripts/setup.ts 启动时会用
docker --version和docker compose version分别校验二者。
依次执行三条命令:
bun install
bun run setup # 写入 .env,启动 Postgres + Redis,执行迁移
bun run dev # 同时启动 api + web + worker
bun run setup 是幂等的首次引导脚本,内部流程(scripts/setup.ts)依次为:校验 Bun 版本与 Docker → 从 .env.example 复制生成 .env(若已有则跳过;首次生成后提示你填写 DATABASE_URL/REDIS_URL/WEB_ORIGIN 并设置 AUTH_SECRET,例如 openssl rand -hex 32)→ bun install → docker compose up -d --wait postgres redis(本地 override 将 Postgres/Redis 发布到 55432/56379,避开常用端口)→ 对 DATABASE_URL/REDIS_URL 派生 TCP 端点做就绪探测 → bun run db:migrate。启动完成后,SPA 位于 http://localhost:5173。
提交 PR 前:三项必须全绿
以下三项在本地必须干净,CI 跑的是完全相同的一组命令,本地失败意味着 CI 必然失败:
bun run lint # oxlint + 仓库不变量门禁 + prettier
bun run typecheck # tsc --noEmit -b 全包范围
bun run test # vitest
两个容易浪费时间的关键陷阱
陷阱一:Turbo 缓存会掩盖失败。 turbo.json 中 test 任务有输出缓存(coverage/**、test-results/**),命中缓存时既不会暴露覆盖率失败,也不会暴露 prettier 失败。需要信任结果时使用:
bun run test --force
同理 bun run lint --force、bun run typecheck --force 在需要绕过缓存时同样适用。
陷阱二:改了 packages/contracts 后存在构建顺序依赖。 必须先 build --force 再 typecheck --force,否则你会对着过期的声明文件做类型检查。这是因为 turbo.json 中 typecheck 与 test 都 dependsOn: ["^build"]——下游包的类型检查依赖上游(如 contracts)已生成的最新声明。
行为变更必须同步更新文档
如果你改变了行为,必须在同一个 PR 里更新文档——这是 CI 门禁而非锦上添花。机器强制手段包括:
bun run docs:build:先docs:gen --check(校验docs/_generated/config/下的配置表与 env 参考与 zod schema /ENV_CATALOGUE一致),再uv run mkdocs build --strict(任何失效链接都会失败);- scripts/ci/no-invalid-mermaid.sh、scripts/ci/no-stale-migration-doc.sh 等专项门禁;
- 具体约定见 docs/contributing/coding-rules.md 的 "Documentation accuracy":每个具体论断必须能追溯到一个源码/配置出处,未验证的论断不允许发布。
注意文档构建运行在 uv 托管的 Python 环境里(见 pyproject.toml 的 [dependency-groups] docs),绝不要直接对 PATH 上的某个 mkdocs 执行 mkdocs build——那会用到无关的解释器并报 "The plugin is not installed"。正确做法是先 bun run docs:install(即 uv sync --group docs),再通过 bun run docs:build / bun run docs:serve 间接调用 mkdocs。
提交与 PR 规范:Conventional Commits
仓库通过 commitlint.config.mjs(extends @commitlint/config-conventional)强制执行 Conventional Commits 规范。PR 标题会被 lint,因为它最终会成为 squash 合并后的 commit subject,因此 PR 标题本身也要遵守同一格式。三个官方示例:
feat(worker): retry a partially filled order once before cancelling
fix(web): stop the symbol rail flickering on reconnect
docs: correct the backtest metric definitions
规则要点:
- subject 控制在 100 字符以内;
- 在 body 中解释"为什么"(why),diff 本身已经展示了"做了什么"(what);
- 与代码注释规则一致:提交信息与 PR 正文才是承载 issue/spec 历史的地方,不要在代码注释里重复。
另外,husky + lint-staged(lint-staged.config.js)会在提交阶段自动对 *.{ts,tsx,js,jsx,mjs,cjs} 跑 oxlint --fix 与 prettier --write(对 *.{json,md,yml,yaml} 先过滤符号链接再 prettier,因为 CLAUDE.md、AGENT.md、GEMINI.md 是指向 AGENTS.md 的软链,prettier 3 对显式传入的符号链接会硬报错)。
深入了解:bun run lint 究竟在跑什么
scripts/ci/lint.sh 是全部静态门禁的总调度,结构上大致分四层:
- 行走完整性自检先行:先跑
walk-lib.selftest.sh与no-blind-walk.selftest.sh,再跑no-blind-walk.sh。原因是几乎所有门禁都依赖对源码树的一次遍历(walk),一个悄悄收窄的遍历会"自信地报 OK";自检保证遍历仍能覆盖规则保护的目标模块(统一走 scripts/ci/lib/walk.mjs 的collectOrExit,拒绝没有锚点文件的根)。 - 不变量门禁(shell gate):
no-plugin-leak(策略/通知插件隔离)、no-locks(禁止 redlock 等分布式锁)、no-publish-hazard(发布安全)、no-arbitrary-color-token、no-phantom-env-var、no-unreviewed-tofixed(scripts/ci/tofixed-inventory.json 登记的每一个.toFixed(站点)、no-undeclared-workspace-import、no-backfilled-migration与no-mutated-applied-migration(迁移编号与校验和不可变性)、no-bun-version-skew、no-stale-migration-doc、no-stale-config-table、no-stale-env-contract、no-colocated-tests等。 - 多文件分析:
bunx oxlint做单次全仓库扫描(而非按包逐次),这样import/no-cycle能看到跨包的完整模块图;随后bunx prettier --check .校验格式。 - 指标与告警一致性:
no-phantom-alert-metric(Prometheus 规则只允许引用仓库确实发射的系列)与promtool-lint。
每个 shell 门禁几乎都配有对应的 *.selftest.sh 自检,且自检先于门禁运行——因为 set -e 会在第一个失败处中止,自检负责区分"规则文件写错了"还是"解析器回归了"。AGENTS.md 中明确要求:一个从未在必须拒绝的树上驱动过的门禁,还不算任何证据。
覆盖率:按工作区阈值与 lane 绑定
bun run test 之外还有覆盖率门槛。 packages/config/vitest/coverage-policy.js 为每个工作区配置了 lines/branches 百分比下限,并将每个活的阈值绑定到运行该工作区完整套件的 CI lane(unit / integration / worker-integration / db-isolation 各自产出独立 lcov 工件,由 coverage-merge 归一化合并)。因此本地跑测试时,务必让对应 lane 的 COVERAGE_LANE 环境变量与 CI 一致,否则阈值不会被实际校验。
许可条款
通过向本仓库提交贡献,即表示你同意你的贡献按 Apache-2.0 授权,这也是整个项目的许可证(见 LICENSE)。提交即视为接受该条款。
小结
向 binance-trading-bot 贡献的完整心法可以压缩成一句话:先读 AGENTS.md 守住五条不变量(策略插件化、Money=Decimal、纯函数 tick、__tests__ 目录、why-comments),本地用 --force 复现 CI 的 lint/typecheck/test 三绿,行为变更同 PR 更新文档,PR 标题遵守 Conventional Commits 且不超过 100 字符,最后接受 Apache-2.0 授权。小步快跑的聚焦 PR 是被这个项目欢迎的唯一形态。