binance-trading-bot 贡献指南:从工程不变量到 CI 门禁的完整实践

原创2026-10-11 22:21:381,761 阅读
文章标签:金融科技后端前端任务调度人工智能

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 门禁而非锦上添花。机器强制手段包括:

注意文档构建运行在 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 是全部静态门禁的总调度,结构上大致分四层:

  1. 行走完整性自检先行:先跑 walk-lib.selftest.sh 与 no-blind-walk.selftest.sh,再跑 no-blind-walk.sh。原因是几乎所有门禁都依赖对源码树的一次遍历(walk),一个悄悄收窄的遍历会"自信地报 OK";自检保证遍历仍能覆盖规则保护的目标模块(统一走 scripts/ci/lib/walk.mjs 的 collectOrExit,拒绝没有锚点文件的根)。
  2. 不变量门禁(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 等。
  3. 多文件分析:bunx oxlint 做单次全仓库扫描(而非按包逐次),这样 import/no-cycle 能看到跨包的完整模块图;随后 bunx prettier --check . 校验格式。
  4. 指标与告警一致性: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 是被这个项目欢迎的唯一形态。

登录后查看全文
binance-trading-bot