Binance Trading Bot 工程宪章解析:四大核心不变量、CI 质量门禁与插件化策略架构
Binance Trading Bot 工程宪章解析:四大核心不变量、CI 质量门禁与插件化策略架构
本文以仓库根目录的 CLAUDE.md(仓库给编码 Agent 的"工程宪章")为骨架,完整解读
binance-trading-bot项目的架构原则、四大核心不变量、技术选型、必备命令、静态检查与 CI 质量门禁体系,并对照 extensibility.md、account-isolation.md、auth.md 以及策略插件契约、DB 作用域与迁移运行器等源码实现展开。读完本文,你将理解这个多账户量化交易平台的"规则手册"如何运作:为什么新增一个策略只需"新包 + 一行注册"、为什么账户隔离要靠编译期 branded 类型而非数据库 RLS、为什么 CI 必须通过 9 项质量门禁,以及哪些反模式是仓库明令拒绝的。
项目定位:单人运营、多账户、多配置档的可靠性优先交易平台
CLAUDE.md 开篇就给出了项目的精确自我定位:
binance-trading-bot:单运营者(single-operator)、多账户(multi-account)、多配置档(multi-profile)、可靠性优先(reliability-first)、移动优先(mobile-first)的 Binance 交易平台。
这句话拆开看,每一部分都对应一个明确的设计约束:
- single-operator:整个系统只有一个运营者账号(Better Auth 签名、
users表唯一索引、onboarding 单例),不存在多租户,这直接影响后文"无静态加密"的威胁模型取舍; - multi-account:一个运营者拥有 N 个一等公民 Binance 账户,每个账户 = 一对 API Key + 一个
binance_mode环境(testnet/live)+ 一条 user-data 流; - multi-profile:每个账户运行 N 个策略 profiles(配置档),共享该账户的钱包、Key 和用户数据流;
- reliability-first / mobile-first:是贯穿四条核心不变量的设计基调。
策略在项目中被明确定义为插件(plugin):Trailing-trade 是第一个、momentum 是第二个、rebalance 是第三个。策略的"事实源"(source of truth)在 packages/strategy/trailing-trade、packages/strategy/momentum、packages/strategy/rebalance,契约本体在 packages/strategy/core 与 docs/architecture/extensibility.md。仓库根目录的 README.md 将"Strategy-pluggable、Account-scoped profiles、Reliability-first"概括为三大特性,与宪章完全对齐。
架构原则:正确性优先,无历史包袱地重构
宪章第一条原则是 Correctness first:
写代码之前先确认设计是健全的:暴露取舍(surface tradeoffs)、选择能保住下述不变量(invariants)的最简方案、为任何版本/API 声明引用权威来源,宁可质疑也不要猜测。
由于项目当前是 Greenfield(绿地项目,尚未部署),没有向后兼容的历史债务,因此允许"偏好正确且可扩展的设计而非最小 diff"、允许自由重构,但两条限制仍然成立:不变量始终有效;开始一次大型重构前必须命名它(在 PR/commit 层面说清楚改的是什么)。这是整个仓库一切开发决策的总纲。
核心不变量一:可扩展性——策略与通知器都是插件
策略插件契约:@app/strategy-core
策略插件契约的规范定义在 packages/strategy/core/src/contract.ts,一个插件就是一个满足 Strategy<Config, State, Bundle, Events> 的对象。关键成员包括:
| 成员 | 用途 |
|---|---|
name / version / displayName / description |
身份标识:name 是注册表键,version 驱动状态迁移 |
capabilities |
声明 worker 必须喂养的基础设施(K 线区间、用户数据流、mini-ticker、KV 存储、bundle 提供者、operatorActions 子集) |
configSchema / overrideConfigSchema |
Zod 对象 schema,api 序列化为 JSON Schema 供 SPA 表单渲染 |
stateSchema / bundleSchema |
每 (profile, symbol) 状态切片与每 tick bundle 的 Zod schema |
events |
策略领域事件字典(事件类型 → zod payload 映射) |
defaultConfig |
新建 profile 向导用来预填编辑器的合法配置 |
tick |
纯函数 TickInput -> TickOutput,唯一的决策入口 |
tick() 是纯函数:不做 I/O、不读墙钟、不产生随机数(除了 TickInput 注入的 Clock 与 RNG);它接收一个 per-(profile, symbol) 状态切片,返回下一个切片加一组 Decision,所有副作用由 worker 而非策略执行。这是"策略可插拔"的根本前提——worker 对策略的具体意图词汇一无所知,只执行它产出的通用决策。
Decision 联合体:保持泛化的副作用语言
tick() 返回的决策定义在 packages/strategy/core/src/decision.ts,今天恰好包含这些变体:
| 变体 | 形状 | 效果 |
|---|---|---|
noop |
无载荷 | 本 tick 什么都不做 |
place-order |
{ intent, params } |
下单;intent.reason/intent.meta 归策略所有 |
cancel-order |
{ orderId, reason, symbol? } |
按 Binance 数字 id 撤单 |
replace-order |
{ cancelOrderId, reason, intent, params } |
一次 cancelReplace(STOP_ON_FAILURE)完成撤旧挂新 |
emit-event |
{ eventType, payload } |
发布类型化领域事件,泛化于策略的 events 映射 |
set-kv / delete-kv |
{ key, value? } |
写入/删除 per-profile KV 存储中的跨符号事实 |
宪章与 extensibility.md 都强调:Decision 联合体必须保持泛化——通用交易所请求形状(如 replace-order)属于联合体;策略专属副作用走 emit-event 的命名空间键,绝不新增策略专属变体;跨符号耦合走 set-kv/delete-kv。
注册表与"不得插件泄漏"门禁(invariant 1 的强制点)
宪章第一条不变量是这样表述的:
策略是
packages/strategy-core背后的插件;通知器提供者位于@app/notify的./providers/*子路径导出之后。apps/api/apps/worker绝不允许在注册表引导(registry bootstrap)之外导入任何具体的strategy-*包或@app/notify/providers/*提供者;apps/web可以导入策略包以获取类型化事件载荷。
也就是说:新增一个策略 = 新包 + 注册表条目;新增一个通知器 = 新提供者模块 + buildNotifyRegistry 条目——永远不需要改 apps/api / apps/worker。唯一允许点名具体策略的地方是 packages/strategy/registry/src/index.ts 的 buildStrategyRegistry()(registry.register(trailingTrade/momentum/rebalance) 三行),api 与 worker 在启动时各自调用它拿到完全一致的注册表;通知器侧对应 apps/api/src/notifiers.ts 的 notifyProviders = buildNotifyRegistry()。
这条不变量由 CI 脚本 scripts/ci/no-plugin-leak.sh 强制(对应 CLAUDE.md 中的 no-plugin-leak 门禁):它扫描两个 app 目录树的 .ts/.tsx 文件,检测任何直接导入具体插件包的行为;豁免名单只有注册表引导文件(strategies.ts/notifiers.ts)、apps/web 与 __tests__(测试本来就该直接驱动插件)。该门禁带空扫防呆(vacuity guard):如果扫描解析不到任何插件导入(注册表引导文件必然导入插件),门禁直接失败——"一个静默窄化的 walk 比没有门禁更糟"。
新增一个策略的实证路径(momentum 走过的)在 extensibility.md 中列了 5 步:新包 → 声明 capabilities → 在注册表加一行 → 加 golden-replay fixture 并断言 replayFixture diff = 0 → 把新 metric 名登记到 apps/worker/src/metrics/catalog.ts(未登记的名字会以无人监控的 label 导出的,strategy-metric-names.test.ts 会精确断言名字集合)。
核心不变量二:可靠性——Crash-only 与幂等作业
Reliability. Crash-only. Idempotent jobs. Per-account Binance-rate isolation. No silent failures.
四个要点分别落地为:
- Crash-only(只能崩溃恢复):worker 不依赖优雅停机清理状态,重启后从 DB 真相重新收敛;
- 幂等作业(Idempotent jobs):下单幂等靠确定性
clientOrderId(Binance 在首单未关闭前对同一clientOrderId去重);状态提交靠版本感知的乐观 CAS; - 按账户隔离 Binance 限速(Per-account rate isolation):不同账户不共享请求权重桶;
- 不允许静默失败(No silent failures):任何异常路径都必须可观测,要么重试要么告警。
宪章在 技术栈 一节进一步说明:worker 今天单副本(WORKER_REPLICAS=1),不用分布式锁;单执行语义由三重机制叠加——BullMQ jobId 合并、进程内 chainByKey、幂等 clientOrderId + 版本感知的 symbol_states CAS。弹性扩容(elastic-pool scale-out)的管道已合入但处于**休眠(dormant)**状态。这套"先做对、暂不横向扩展"的选择正是"正确性优先、最简方案"原则的体现。
核心不变量三:易用与响应式——移动优先的单人运营体验
Approachable & responsive. Solo operator, not a finance pro: plain language, gloss a trading term the first time it appears, never assume off-screen knowledge. Mobile-first — every view usable at 375×667 — then scale up.
- 面向单人运营者而非金融专业人士:用平实语言,交易术语第一次出现时必须加注释(gloss),不假设读者有屏幕之外的背景知识;
- 移动优先:每个视图在 375×667 的屏幕上都可用,然后向上扩展到桌面;
- 这一点贯穿产品细节:
reasonAttribution(策略决策原因 → 面向运营者的文案映射)让 SPA 的整个诊断漏斗由策略声明驱动(extensibility.md 中 invariant 1 的又一次落地)。
核心不变量四:按行作用域的账户隔离(branded types + 无 RLS)
第四条不变量是最具工程特色的部分,它主张隔离靠数据行作用域 + 编译期类型证明,而不是靠约定或数据库 RLS。
数据模型与双层作用域
- 模型:一个运营者(
users)→ 多个accounts→ 多个profiles;accounts.owner_id → users.id;每个账户持有一对 Binance Key、一个binance_mode、一条用户数据流;profiles.account_id把每个 profile 绑定到其账户,共享该账户的 Key/钱包/流。 - Branded 双层作用域:
AccountScope{db, operatorId, accountId}由scopeAccount铸造;ProfileScope{db, operatorId, accountId, profileId}由scopeProfile铸造;- 一次查询即证明所有权链条;
UserId与AccountId是不同的 branded 类型——把其中一个误放给另一个会直接编译失败。
访问规则与唯一的铸造入口
宪章规定:应用代码只能通过 profileRepo(...) / profileRepoFromScope(scope)(账户级表面如 api-keys 则用 accountRepo(...) / accountRepoFromScope)访问账户作用域数据,禁止手工 (db, operatorId, …) 参数穿线;每个作用域仓储函数第一个参数必须是 AccountScope/ProfileScope,而作用域只能由 scopeAccount/scopeProfile 铸造——所有权在编译期被证明恰好一次。平铺的 repo.<x> 只保留给运营者/全局函数(repo.users.*、repo.accounts.create/listForOwner、保留期清理等)。
路由约定同步配套:API 在 /api/accounts/:accountId/... 下,Web 在 /accounts/$accountId/... 下。
实现细节可对照 packages/db/src/repo/_scoped.ts:brand 键是模块私有的 unique symbol(运行时真实 Symbol,而非仅类型层面的 declare const),外部模块无法命名该键,因此手工构造的字面量既无法通过类型检查也无法通过强转;scopeProfile 在 profiles ⋈ accounts 单次 join 中完成 owner_id 校验后打上 brand;toAccountScope(ProfileScope) 是唯一被允许从"已证明的 profile 链"收窄出账户作用域的通道(订单对账是账户域事务,而驱动它的 tick 只持有 profile 作用域)。
强制机制:无 DB 侧 RLS
强制靠 packages/db/tests/repo/ast-check.test.ts 加跨账户集成测试,不做 DB 侧 RLS。相关架构文档是 docs/architecture/account-isolation.md——它详细讲解了 base-asset 互斥、quote 冲突互斥、profile/account 的销毁式删除语义与"订单 DETACH vs CASCADE"的差异。
策略状态:per-(profile, symbol) 切片 + per-profile KV
最后一条子规则约束策略状态:存储与 tick() 中的状态都是 per-(profile, symbol)——每个符号每个 tick 一个切片,不存在 profile 级宽状态对象。跨符号状态必须走 per-profile KV 存储:通过 set-kv/delete-kv 决策写入策略自有命名空间键,后续 tick 通过 TickInput.profileKv 读回合并快照(需用 capabilities.needsProfileKv 显式 opt-in)。KV 写入只会被兄弟符号在之后的 tick 读到,绝不在同一 tick 内生效(见 extensibility.md 的 State scope 小节)。
技术栈与仓库布局
宪章声明版本以 package.json/lockfiles 为准(命名只在此列),package.json 锁定了 bun@1.4.2、oxlint 1.86.0、turbo ^2.11.5、typescript ~7.0.2 等。技术选型一览:
| 层 | 选型 |
|---|---|
| 运行时 | Bun |
| Monorepo | Turborepo |
| CI | GitHub Actions + GitLab,都调用 scripts/ci/*.sh |
| 后端 | Hono |
| 前端 | Vite + React + TanStack Router/Query + Tailwind + shadcn/ui(PWA) |
| 图表 | lightweight-charts(金融图)、Recharts(非金融图) |
| 数据库 | Postgres + TimescaleDB,ORM Drizzle,迁移为手工编写 SQL + 校验和追踪运行器 |
| 缓存/队列 | Redis + BullMQ(ioredis,maxRetriesPerRequest: null) |
| 认证 | Better Auth(无 email/SMTP、无 2FA——单一主账户,见 auth.md) |
| 静态加密 | 无:Binance Key 与通知器密钥明文存储,靠运营者在 Binance 控制台对 Key 做 IP 白名单(威胁模型见 auth.md "Threat model") |
| 金额计算 | decimal.js:一切价格/数量/金额/余额/PnL 端到端都是 Decimal,number 只用于计数器/索引/毫秒时间戳;快照把 Decimal 序列化为字符串,策略在边界处复活 |
| 通知 | 可插拔 @app/notify 提供者(Slack 首个) |
| 技术指标 | 进程内 packages/indicators/rating(vendored MIT);worker 的 technicals-compute cron 本地计算评分,无外部扫描器 |
| 容器 | 单多阶段镜像(apps/server/Dockerfile),ROLE=all|api|worker|study 选择行为;apps/web 仅构建(api 同源托管 SPA);横向拆分用 docker-compose.scale.yml |
仓库布局:
apps/ api/ web/ worker/ server/ # server = ROLE 可选的入口(api + worker)
packages/
strategy/ core/ trailing-trade/ # core = 契约 + Executor;TT = 首个插件
indicators/ # 纯、Decimal 类型化的蜡烛/窗口数学
notify/ # @app/notify:契约 + 注册表 + providers/{slack,telegram,webhook}
binance/ db/ contracts/ config/
core/ # 共享运行时工具;子路径导出(./env, …)
deploy/compose/ scripts/ci/
值得注意的目录约定:packages/strategy/* 的目录分组只是文件系统层面的;npm 名保持扁平(@app/strategy-trailing-trade);@app/notify 是单包,提供者走子路径导出。
必备命令一览
宪章给出了 bun run 命令表(仓库根目录执行,package.json 中均有对应 script):
| 命令 | 用途 |
|---|---|
bun install |
安装 workspace 依赖 |
bun run dev |
通过 turbo 启动 api+web+worker |
bun run lint |
oxlint + 不变量门禁 + prettier,必须干净 |
bun run typecheck |
所有包执行 tsc --noEmit -b,必须干净 |
bun run test |
Vitest;各 workspace 覆盖率阈值在完整套件覆盖率车道按 COVERAGE_POLICY 分配 |
bun run test:e2e |
Playwright e2e |
bun run test:worker-integration |
笔记本上的 apps/worker 集成车道:在 TESTCONTAINERS=1 下临时起 Postgres + Redis,因此需要可达的 Docker daemon;没有时打印提示而不运行 |
bun run db:migrate |
应用手工编写的 SQL 迁移(校验和追踪运行器) |
bun run db:generate |
不使用——仓库手工编写 NNNN_*.sql |
bun run setup |
首次引导:从 .env.example 生成 .env + 迁移 |
bun run docs:install |
uv sync --group docs;在任何其他 docs:* 命令之前执行一次 |
bun run docs:build |
docs:gen --check + uv run mkdocs build --strict,即文档门禁 |
docker compose up |
本地栈:postgres、redis、一个 ROLE=all 应用 |
上手顺序(与 README.md 的 Quick start 一致):bun install → bun run setup(写 .env、拉起 Postgres+Redis、跑迁移)→ bun run dev,SPA 在 http://localhost:5173;想要全容器运行则用 bun run docker:dev(ROLE=all 在 http://localhost:53000)。
文档构建:uv 管理的 Python 环境
宪章专门强调:文档在 uv 管理的 Python 环境(pyproject.toml 的 <a href="https://link.gitcode.com/i/b7bd4244c682a098fdafc55e02bb128a" target="_blank">dependency-groups] docs)中构建,绝不用 PATH 上碰巧存在的 mkdocs。如果直接裸跑 mkdocs build --strict,会捡到一个无关的解释器并死在 The "<plugin>" plugin is not installed 上——这条报错意味着环境不对,而不是配置坏了,所以手工安装它点名的插件是错误修复。正确路径永远是走 bun run docs:build / docs:serve(内部经 uv run 调用 mkdocs),先 bun run docs:install(uv sync --group docs)创建该环境。文档站本身用 mkdocs 构建(见 [mkdocs.yml),内容主体在 docs 目录。
静态检查:oxlint 单一路径 + 不变量门禁
宪章规定 oxlint 是唯一的 lint 路径(配置见 .oxlintrc.json),并且是一次全仓 pass(单一调用而非按包),这样 import/no-cycle 能看到完整跨包模块图。插件组合为 correctness + typescript/import/oxc/react:
react开启是为了react/no-unstable-nested-components(在另一组件渲染体内声明的组件会让子树每渲染重挂载,在 WebKit 上夹住scrollTop);开启该插件会同时武装所有 reactcorrectness规则,所以react/exhaustive-deps被显式off(待处理存量违规)。- overrides 承载仓库不变量:
- 策略/指标纯度:
packages/strategy/*/src/**、packages/indicators/src/**、packages/discovery/src/**禁止Date/Math/process/performance全局,禁止fs/net/http/crypto/ioredis/pg/drizzle-orm导入(用注入的Clock/RNG替代,见 contract.ts 的Clock/RNG接口); - decimal.js 边界:
decimal.js在纯金钱数学包之外全局禁止导入(no-restricted-imports),第二个 override 又对金钱数学相关测试目录关闭该限制。
- 策略/指标纯度:
oxlint 表达不了的不变量由 scripts/ci/lint.sh 串联的 scripts/ci/*.sh 门禁承载(每个门禁几乎都先跑自己的 selftest,再跑真身,防止"门禁静默变窄")。清单包括:no-plugin-leak(不变量 1)、no-arbitrary-color-token、no-phantom-env-var、no-invalid-mermaid、no-undeclared-workspace-import、no-wider-metrics-sink(只有 apps/worker/src/metrics/catalog.ts 可声明 metrics 汇,第二个声明者会逃出目录清单)、no-unreviewed-tofixed(apps/web/src/** 下每个直接 .toFixed( 与固定两位 maximumFractionDigits 站点都登记在 scripts/ci/tofixed-inventory.json)、no-dropped-lint-rule(断言解析后的 oxlint 配置仍启用了承载不变量的规则)、no-backfilled-migration(新 NNNN_*.sql 必须取下一个未用编号,因为运行器按文件名顺序应用)、no-mutated-applied-migration(已发布的迁移不可变,只有固定摘要清单能看见漂移)、no-bun-version-skew(九个 Bun 版本固定点必须一致)、no-blind-walk(每个靠树遍历读取结论的门禁都必须使用 scripts/ci/lib/walk.mjs,其 collectOrExit 拒绝无锚点的根目录)。详细规则见 docs/contributing/coding-rules.md。
质量门禁:CI 必须通过的 9 项
宪章把 CI 质量门禁编号为 9 项,这里逐条展开关键细节:
- Lint 干净(见上文 lint 门禁);
- Typecheck 干净;
- 行为变化时文档必须同步更新——每一条论断都要可溯源到出处而非记忆;机器强制部分:
bun run docs:build(先docs:gen --check校验配置表与 env 变量参考,再uv run mkdocs build --strict)、no-invalid-mermaid.sh、no-stale-migration-doc.sh;叙事准确性仍属评审门禁; - 各 workspace 完整套件覆盖率阈值达标(packages/config/vitest/coverage-policy.js);
- 策略 golden-fixture 回放 diff = 0——对每个已捕获的真实 tick 回放断言零漂移,是防行为漂移的关键门禁;
- Playwright 车道全绿:
browser-bootstrap证明四个浏览器项目能启动;app-e2e启动一个自包含的ROLE=all栈对着 loopback Binance fixture 跑 P0 旅程,任何跳过或 fixture 未应答的 Binance 流量都算失败; bun run compose:build对每个 app 成功;- 迁移契约(详见下一节);
- JSDoc 质量是评审门禁而非 lint 门禁:每个导出或非平凡函数都要有含逐参数
@param、有返回值时带@returns的块注释;标签上方的散文写 WHY,每个标签解释该值意味着什么——禁止名字复读(@param symbol - The symbol)、禁止空白块;注释不许硬换行(一个段落一行、一个标签一行,与 prettier.config.mjs 对 Markdown 的proseWrap: 'never'同理——硬换行的散文会让每次编辑变成多行重排,diff 藏起真正改动的句子);换行只为了表意(列表、表格、ASCII 图保持断行)。
迁移契约:校验和追踪 + 编号不可回填
宪章对迁移有两条硬规则(packages/db/src/migrate.ts 是运行器实现,账本表为 _app_migrations):
- 已发布的迁移不可变:编辑一份已应用的
NNNN_*.sql(连改注释都算)会让它的 SHA-256 摘要漂移,把每个已迁移数据库楔死在该文件处,后续任何迁移都救不回来;重命名或删除它对运行器不可见(运行器按文件名作键),文件会作为新迁移重新应用并遗留旧账本行——静默的。改动已发布迁移的唯一正确方式是写一个新迁移;no-mutated-applied-migration强制执行(全新 DB 的套件看不到这两种情况),migrate-immutability.test.ts 固定这两个行为。 - 编号不可回填:新迁移取下一个未用编号,绝不取空号、字母后缀或
0001以下的号,因为文件名顺序就是应用顺序——no-backfilled-migration从目录列表(唯一能区分回填与全新树的事实源)强制执行。
为什么不用 drizzle-kit migrate?migrate.ts 的注释说明了原因:需要 drizzle-kit 无法表达的扩展、角色和 TimescaleDB hypertable/保留期 DDL;每份迁移是明文 SQL,已应用迁移的校验和记录在 _app_migrations 表。运行器还会用 session advisory lock 串行化并发迁移(对并行 vitest worker 共享测试 DB 的场景),并显式声明这是"迁移期 DB 锁而非运行时协调锁",不违反单副本无分布式锁不变量。
必须拒绝的反模式清单
宪章最后一节列出仓库明令拒绝的反模式,是理解架构取舍的浓缩清单:
- NotifyProvider 单一事实源:提供者形状住在
@app/notify;apps/api消费notifyProviders.describeAll(),绝不维护自己的提供者接口。 - 无分布式锁:禁用
redlock、intents:Redis 集合、软余额预留及等价物(scripts/ci/no-locks.sh 失败时会同时扫描packages/binance)。允许的共享 Redis 原语只有限速/可见性类(消费-衰减请求权重桶、自过期SET NX PX通知间隔节流)——无所有者、无释放/退还。 - 磁盘上无明文 API Key(Postgres 例外除外),且只在 auth.md 的缓解措施(单租户、运营者侧 Binance IP 白名单)之下;任何新存储面(备份、副本、导出、多租户)先要求静态加密。
LIVE_DEMO响应中无秘密:公共 demo 注入唯一运营者 id,任何未在requireNotDemo之后的路由都可匿名访问。凭据等价值(Binance API Key、通知器 webhook URL、bot token、auth header、AI 提供者 Key)绝不能序列化进任何响应体——在投影边界剥离(api-key →last4、ai-provider →has*布尔、notifiers 在secretFields声明秘密)。requireNotDemo是黑名单/纵深防御:新增的读秘密或写凭据路由默认暴露,必须同时加入拒绝清单与 apps/api/tests/routes/live-demo-guard.test.ts 的完备性断言。- 无投机式抽象:feature flag、"为将来"的间接层需要带具体消费者的已跟踪 issue。
- 金额数学 =
Decimal:packages/{strategy-*,indicators,contracts}下游禁止number(IEEE-754);decimal.js 导入边界由 lint 强制。 Decision联合体保持泛化(上文已述)。- 策略与指标是纯的:
packages/strategy-*/src/**与packages/indicators/src/**内无ioredis/pg/drizzle-orm/fs/net/http/crypto/Date/Math.random;tick()内无 I/O(worker 注入Clock和RNG);decimal.js允许。 - 注释写为什么,不写是什么:代码中无 Spec/Issue/Phase/
@see引用,这些归 commit 和 PR 管;CI 拒绝。 - 测试住在
<pkg>/__tests__/,绝不与src/并排;CI 拒绝。 - 新的共享运行时工具进
@app/core的新子路径,而不是新包——除非该工具有清晰的领域边界(strategy、notifier、binance、db、contracts)。
给开发者的行动清单
把宪章压缩成动手时的检查单:
- 涉及
apps/api或apps/worker时,绝不直接 import 具体strategy-*包或@app/notify/providers/*——只经过注册表引导文件(buildStrategyRegistry/buildNotifyRegistry); - 访问账户级数据只经作用域铸造(
scopeAccount/scopeProfile)与作用域仓储函数,不手工穿线(db, operatorId, …); - 金额一律
Decimal,字符串序列化跨越边界;策略/指标代码保持纯函数并注入Clock/RNG; - 改行为先改文档(配置表与 env 参考由
docs:gen --check强制,叙事靠评审);迁移遵守"编号不回填、已应用不可变"; - 提交前
bun run lint与bun run typecheck必须干净;JSDoc 注释不硬换行、写 WHY; - 新共享工具先进
@app/core新子路径;新测试放<pkg>/__tests__/。
这套宪章的价值在于:把"可靠性优先的多账户量化交易平台"这类宽泛目标,落成了一批可机械检查的规则(lint 门禁、CI 门禁、编译期 branded 类型、AST 检查、golden 回放 diff),让任何编码 Agent(Claude Code、Cursor、Codex……)在改代码前就拿到全部边界约束。它不承诺"赚多少钱",而是承诺"错误不会以静默的方式出现"——这正是 README 免责声明之外,代码层面真正可靠的那部分。