319e73d91f
dev.md 是 v1 设计稿但路线图已与 README 冲突；加废弃声明 + 优先级表，
指向 README / AGENTS / ai/adr 作为权威来源。AGENTS §2 与 harness-health
同步 v2.x 进度（Bollinger / Vegas / derivatives signal ✅；per-interval
完整化 + 箱体 + CI 未完）。README 路线图分段 v2.0/v2.x/v3，与 G12 守卫
扩白名单（derivatives_signal.go）保持一致。
175 lines
7.1 KiB
Markdown
175 lines
7.1 KiB
Markdown
# AGENTS.md — cryptoHermes 操作指南
|
||
|
||
本文件是 AI 编码代理在此仓库工作的最小操作手册。用户向文档见 `README.md`，harness 健康度见 `ai/harness-health.md`。
|
||
|
||
`docs/dev.md` 是 v1 初始设计稿，**路线图与当前状态判断不再以它为准**（见该文件顶部废弃声明）；其余章节作为设计源头仍可参考。
|
||
|
||
---
|
||
|
||
## 1. 项目定位（必读，决定可做与不可做）
|
||
|
||
cryptoHermes 是给上游 Hermes 量化分析引擎用的 **Binance Futures 行情网关**。
|
||
|
||
**只做**：
|
||
- 从 Binance USDⓈ-M Futures 公共接口拉行情、衍生品数据
|
||
- 落库到 TimescaleDB
|
||
- 通过 REST 把聚合后的市场上下文给 Hermes
|
||
|
||
**绝不做**（详见 `ai/risk-guardrails.md`）：
|
||
- 下单、撤单、查持仓
|
||
- 接入 API Key / Secret
|
||
- 任何账户级私有接口（签名请求）
|
||
- 钱包、托管、转账
|
||
- WebSocket 推送（v1 范围外）
|
||
|
||
---
|
||
|
||
## 2. 当前状态（2026-05-25）
|
||
|
||
- **v1 MVP**：✅ 已完成。`/v1/market/context` 可返回 K 线 / Funding / OI / 多空比 / Taker 主动量，cron 全部上线。
|
||
- **v2.0**：✅ 已完成。primary `1h` 周期的 Pivot S/R + P95/P5 区间 + LSR 穿越价位中位数；算法层 `indicator.go` 单测覆盖 ~98%，repo / mapper 关键路径有 pgxmock / table-driven 覆盖。
|
||
- **v2.x**：🟡 **进行中**。
|
||
- ✅ Bollinger（SMA20 + 2σ + Squeeze）、Vegas（EMA12/144/169 + 趋势）已落地并有单测（`internal/usecase/indicator.go` + `indicator_test.go`）。
|
||
- ✅ Derivatives signal（funding / OI / LSR → 语义化字段）已加（`derivatives_signal.go` + 表驱动测试）。
|
||
- ⚠️ per-interval 只到 `IntervalTechnicals`（BB + Vegas），**未升级到完整 `map[interval]TechnicalStructure`**（Support / Resistance / Range / LSLine 仍只在 primary `1h`）。是否升级需要 ADR 锁定决策。
|
||
- ⚠️ 箱体（per-interval 突破信号）未实现；目前只有顶层 `RangeHigh/Low` 沿用 v2.0 的 P95/P5。
|
||
- ❌ testcontainers 集成测试未起。
|
||
- ❌ CI（GitHub Actions / 任何托管 CI）未起，仓库无 `.github/`。harness-health W3 长期挂 partial。
|
||
- **v3**：未启动。`docs/coinglass/` 是 v3 的提前侦察（私有 API 解密 + endpoint 索引），**当前阶段不接入**，详见该目录 README。
|
||
|
||
详细路线图段以 `README.md` 末尾 "路线图" 为准。
|
||
|
||
---
|
||
|
||
## 3. 技术栈
|
||
|
||
| 类别 | 选型 |
|
||
|---|---|
|
||
| Go | 1.23（见 `go.mod`） |
|
||
| HTTP | Fiber v2 |
|
||
| DB | TimescaleDB on PG 16 |
|
||
| DB Driver | pgx v5 (pgxpool) |
|
||
| Scheduler | robfig/cron v3 |
|
||
| Config | cleanenv（yaml + env） |
|
||
| 限流 | `golang.org/x/time/rate` |
|
||
| Migration | golang-migrate CLI |
|
||
|
||
为什么是这套选型见 `ai/adr/0001-architecture-foundations.md`。
|
||
|
||
---
|
||
|
||
## 4. 仓库结构（参见 `ai/project-map.md`）
|
||
|
||
```
|
||
cmd/ 二进制入口（app / backfill）
|
||
config/ cleanenv 配置加载
|
||
internal/ 业务代码（不可被外部 import）
|
||
app/ 装配 DI、cron、graceful shutdown
|
||
controller/ Fiber 路由层
|
||
entity/ 纯业务实体
|
||
usecase/ 业务接口与编排（ports.go 是接口边界）
|
||
repo/ 外部依赖实现
|
||
webapi/binance/ Binance HTTP client
|
||
persistent/postgres/ 5 个 repository
|
||
worker/ collector 实现
|
||
migrations/ SQL（含 hypertable 转换）
|
||
pkg/ 项目内可复用基础设施（logger/httpclient/postgres）
|
||
docs/ 设计文档
|
||
ai/ harness 工程文档（本目录及子目录）
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 验证命令（必做：改完代码至少跑前两个）
|
||
|
||
```bash
|
||
# 编译（最快反馈）
|
||
go build ./...
|
||
|
||
# 静态分析
|
||
go vet ./...
|
||
|
||
# 单包测试
|
||
go test ./internal/<pkg>/...
|
||
|
||
# 全部测试
|
||
make test # 等价于 go test ./...
|
||
|
||
# 生产部署 / 架构守卫
|
||
make guard
|
||
|
||
# 启动（需要先 make docker-up && make migrate-up）
|
||
make run
|
||
```
|
||
|
||
**触碰 binance/mapper.go 或 entity/kline.go 之后**：必须确保对接 `Binance K线数组按下标解析` 的代码不被破坏（dev.md 第 9.2 节）。
|
||
|
||
**触碰任何 SQL migration 后**：本地必须重跑 `make migrate-down && make migrate-up` 验证 down/up 互逆。
|
||
|
||
---
|
||
|
||
## 6. Clean Architecture 边界（自动可验证）
|
||
|
||
```bash
|
||
# controller 不可直接 import binance/postgres
|
||
grep -r "repo/webapi/binance\|repo/persistent" internal/controller # 必须无输出
|
||
|
||
# usecase 不可直接 import binance/postgres
|
||
grep -r "repo/webapi/binance\|repo/persistent" internal/usecase # 必须无输出
|
||
|
||
# controller 不可直接编排 derivatives 多源查询（G11）
|
||
grep -rn "FundingRepo\|OIRepo\|LSRepo\|TakerRepo" internal/controller # 必须无输出
|
||
|
||
# 全项目不可出现签名 / 私钥相关字段
|
||
grep -ri "apikey\|x-mbx-apikey\|hmac\|secret_key\|api_secret" --include="*.go" . # 必须无输出（不算注释/文档里的"不接入"说明）
|
||
```
|
||
|
||
任何 PR 都应该满足以上四条。
|
||
|
||
---
|
||
|
||
## 7. 关键技术约束（容易犯错）
|
||
|
||
1. **价格精度**：全链路用 `string`，落库时由 PG 转 `NUMERIC(36,18)`。**禁止用 `float64` 存储或传递价格、成交量**。
|
||
2. **K线未收线丢弃**：从 Binance 拉到的最新一根 K 线如果 `close_time > now()` 就不能入库。Repo 的 `UpsertMany` 会过滤 `IsClosed=false`，新代码也必须遵守。
|
||
3. **Binance 历史 OI / 多空比官方只保留 30 天**：必须依赖 collector 持续落库才能拿到长历史。
|
||
4. **Rate limit**：默认 20 req/s（`config.Binance.RPS`）。新增 collector 任务前估算 weight 预算（Binance 2400 weight/min IP 上限）。
|
||
5. **国内网络**：`fapi.binance.com` 直连不稳定，通过 `HTTPS_PROXY` 环境变量挂代理。
|
||
6. **Upsert 幂等**：5 张表的主键都包含时间维度，所有 repo 的 `UpsertMany` 使用 `ON CONFLICT DO UPDATE`，可安全重复执行。
|
||
7. **Compose 部署约束**：`.env.example` 不给默认 DB 密码；宿主机端口只改 `APP_HOST_PORT`；容器内 `APP_PORT` 固定 8080；migration 必须在 app 前完成；`.dockerignore` 必须排除 `.env` / `.env.*`。
|
||
|
||
---
|
||
|
||
## 8. 任务模式
|
||
|
||
任何非平凡修改，建议先写一份微型任务契约（参见 `ai/task-templates.md`）：
|
||
|
||
```
|
||
objective: 要做的事，一句话
|
||
scope: 会改的文件 / 目录
|
||
out-of-scope: 不会动的范围
|
||
constraints: 受 ai/risk-guardrails.md 约束的哪几条
|
||
validation: 要跑哪些命令证明通过
|
||
acceptance: 如何判断完成
|
||
```
|
||
|
||
对于跨多个 Milestone 或需要新增数据源（CoinGlass、ETF Flow）的任务，必须先写 `ai/specs/<task>.md`。
|
||
|
||
---
|
||
|
||
## 9. 提交规范
|
||
|
||
- 一个 PR 改一类事。Repo 层、Binance 适配、usecase 编排不要混在一个 commit。
|
||
- Commit message 用中文或英文都行，但要写"为什么"。
|
||
- 不要在没有跑 `go build ./...` 和 `go vet ./...` 的情况下提交。
|
||
- `go.mod` 改动必须配套 `go.sum`（运行 `make tidy`）。
|
||
|
||
---
|
||
|
||
## 10. 何时升级 harness
|
||
|
||
- 同一类错误第二次出现 → 写进 `ai/risk-guardrails.md`
|
||
- 重大架构决策（换 HTTP 框架、引入消息队列、跨服务通信）→ 写 ADR
|
||
- 新增数据源（CoinGlass / ETF / CME）→ 必须有 `ai/specs/<source>.md` 才动手
|
||
- 跨多次会话的长任务 → 写 `ai/work-status.md`
|