Files

dela 319e73d91f docs: v2.x 状态对齐 — dev.md 标废弃 + AGENTS/harness-health 更新

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）保持一致。

2026-05-25 10:43:24 +08:00

7.1 KiB

Raw Blame History

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. 验证命令（必做：改完代码至少跑前两个）

# 编译（最快反馈）
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 边界（自动可验证）

# 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. 关键技术约束（容易犯错）

价格精度：全链路用 string，落库时由 PG 转 NUMERIC(36,18)。禁止用 float64 存储或传递价格、成交量。
K线未收线丢弃：从 Binance 拉到的最新一根 K 线如果 close_time > now() 就不能入库。Repo 的 UpsertMany 会过滤 IsClosed=false，新代码也必须遵守。
Binance 历史 OI / 多空比官方只保留 30 天：必须依赖 collector 持续落库才能拿到长历史。
Rate limit：默认 20 req/s（config.Binance.RPS）。新增 collector 任务前估算 weight 预算（Binance 2400 weight/min IP 上限）。
国内网络：fapi.binance.com 直连不稳定，通过 HTTPS_PROXY 环境变量挂代理。
Upsert 幂等：5 张表的主键都包含时间维度，所有 repo 的 UpsertMany 使用 ON CONFLICT DO UPDATE，可安全重复执行。
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

7.1 KiB Raw Blame History Unescape Escape