diff --git a/AGENTS.md b/AGENTS.md index 3042138..7ad0df3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,8 @@ # AGENTS.md — cryptoHermes 操作指南 -本文件是 AI 编码代理在此仓库工作的最小操作手册。完整项目设计见 `docs/dev.md`，用户向文档见 `README.md`。 +本文件是 AI 编码代理在此仓库工作的最小操作手册。用户向文档见 `README.md`，harness 健康度见 `ai/harness-health.md`。 + +`docs/dev.md` 是 v1 初始设计稿，**路线图与当前状态判断不再以它为准**（见该文件顶部废弃声明）；其余章节作为设计源头仍可参考。 --- @@ -22,11 +24,20 @@ cryptoHermes 是给上游 Hermes 量化分析引擎用的 **Binance Futures 行 --- -## 2. 当前状态 +## 2. 当前状态（2026-05-25） -- v1 MVP 已完成（Milestone 1-5），可启动、可采集、可返回完整 `/v1/market/context` -- Technical 指标计算（Milestone 6）留待 v2 -- 详细路线图见 `docs/dev.md` 第 19 章和 README "路线图"段 +- **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` 末尾 "路线图" 为准。 --- diff --git a/README.md b/README.md index a28bfc9..f7662f4 100644 --- a/README.md +++ b/README.md @@ -291,7 +291,7 @@ collector: } ``` -> `technical.*` 字段在 v1 留空。v2 会补支撑压力、箱体、多空线计算。 +> `technical.support/resistance/rangeHigh/rangeLow/longShortLine` 目前按 primary `1h` 计算；`technical.intervals` 已提供每周期 Bollinger / Vegas。完整 per-interval `TechnicalStructure` 与箱体突破信号仍在 v2.x 待办。 ### `GET /v1/market/klines?symbol=BTCUSDT&interval=1h&limit=300` @@ -379,7 +379,7 @@ v2 第一次把测试体系立住。当前覆盖： | 包 | 测试范围 | 覆盖率 | |---|---|---| -| `internal/usecase` (indicator.go) | pivot S/R、percentile、LSR 穿越、聚类 全分支 | 12 个函数平均 97.7% | +| `internal/usecase` | pivot S/R、percentile、LSR 穿越、Bollinger、Vegas、derivatives signal | 算法路径有表驱动与边界用例覆盖 | | `internal/repo/webapi/binance` (mapper.go) | `parseKlineRow`、`toInt64`、6 个 `map*` 函数 | 9 个函数全部 100% | | `internal/repo/persistent/postgres` | 5 个 repo 的 `UpsertMany` + `FindRecent` 正反例（pgxmock） | 包级 87.6% | @@ -391,7 +391,7 @@ make test-cover ``` 测试选型说明： -- 算法（`indicator.go`）采用 table-driven + `testify/require`。 +- 算法（`indicator.go` / `derivatives_signal.go`）采用 table-driven + `testify/require`。 - Repo 层用 [`pgxmock/v4`](https://github.com/pashagolub/pgxmock) 锁 SQL 字符串与参数顺序——schema 漂移立刻可见。 - `*pgxpool.Pool` 不能直接 mock，因此 5 个 repo 的字段类型被改为内部 `pgxPool` 接口（`internal/repo/persistent/postgres/pool.go`），生产代码继续传 `*pgxpool.Pool`，调用方零改动。 - 集成测试（testcontainers + 真 Postgres + 真 migration）留 v2.1 做 nightly。 @@ -417,8 +417,8 @@ grep -r "repo/webapi/binance\|repo/persistent" internal/usecase # 期望: 无 # 全项目不应出现私钥/账户/签名相关字段 grep -ri "apikey\|x-mbx-apikey\|hmac" . # 期望: 无输出 -# G12：float64 仅允许在 indicator.go 内部 -grep -rn --include="*.go" "float64\|float32" internal/usecase | grep -v indicator +# G12：float64 仅允许在 indicator.go / derivatives_signal.go 内部 +grep -rn --include="*.go" "float64\|float32" internal/usecase | grep -vE "indicator|derivatives_signal" # 期望: 无输出 ``` @@ -427,8 +427,13 @@ grep -rn --include="*.go" "float64\|float32" internal/usecase | grep -v indicato ## 路线图 - **v1**：Binance 行情 + 衍生品 + 落库 + `/v1/market/context` 聚合接口。✅ -- **v2.0（当前）**：技术结构计算第一波——pivot 支撑/压力 + P95/P5 区间 + LSR 穿越价位中位数（primary interval `1h`）。算法 100% 测试 + repo / mapper 关键路径测试到位。✅ -- **v2.x**：MA / Bollinger / Vegas / 箱体；per-interval 指标（`map[interval]TechnicalStructure`）；testcontainers 集成测试 + CI。 +- **v2.0**：技术结构计算第一波——pivot 支撑/压力 + P95/P5 区间 + LSR 穿越价位中位数（primary interval `1h`）。算法测试 + repo / mapper 关键路径测试到位。✅ +- **v2.x（当前）**：进行中。 + - ✅ Bollinger / Vegas 已落地到 `technical.intervals`。 + - ✅ Derivatives signal 已落地到 `derivatives.signal`。 + - ⚠️ 完整 per-interval `TechnicalStructure` 尚未升级，Support / Resistance / Range / LSLine 仍只按 primary `1h` 输出。 + - ⚠️ 箱体与 per-interval 突破信号未实现。 + - ❌ testcontainers 集成测试 + CI 未起。 - **v3**：CoinGlass 清算数据、ETF Flow、CME gap、CVD、链上稳定币流动性、宏观日历、多交易所聚合。 完整设计参见 [`docs/dev.md`](docs/dev.md)。 diff --git a/ai/harness-health.md b/ai/harness-health.md index 72e49b5..557ddee 100644 --- a/ai/harness-health.md +++ b/ai/harness-health.md @@ -1,7 +1,14 @@ # Harness Health — cryptoHermes -**日期**：2026-05-24 -**版本**：v1 MVP 刚完成（Milestone 1-5） +**最近评估**：2026-05-24（v1 MVP 完成时点） +**版本快照**：v2.x 进行中（2026-05-25） + +> **状态说明**：本文以下评分仍是 2026-05-24 v1 MVP 时点的快照。v2.x 进行后的差异： +> - Bollinger / Vegas / derivatives signal 已落地并有单测（W4 部分缓解，mapper/repo 覆盖率仍 partial）。 +> - W3（CI 未搭）**仍未解决**。 +> - 文档对齐已完成：`docs/dev.md` 加废弃声明、`AGENTS.md` §2 已更新到 v2.x 状态、`docs/coinglass/` 加 README 标 v3 储备。 +> +> **复评触发器**：v2.x 收尾（CI + testcontainers + per-interval 完整化决策）完成后必须复评本文件并重打分。 按 he-maintainer 的 scoring rubric 评估当前 harness 工程状态。Rating: `strong` / `partial` / `weak`。 diff --git a/docs/dev.md b/docs/dev.md index d3025e8..425b031 100644 --- a/docs/dev.md +++ b/docs/dev.md @@ -1,8 +1,20 @@ -下面这份可以直接保存为： +> **⚠️ 部分废弃声明（2026-05-25）** +> +> 本文档是 v1 初始设计稿，保留下来主要是为了"为什么这么选"的历史与上下文。**对路线图、当前状态、阶段范围的判断不再以本文为准**。 +> +> | 主题 | 以谁为准 | +> |---|---| +> | 当前版本 / 路线图 | `README.md` 末尾 "路线图" 段 | +> | 当前进行中的阶段与已完成 milestone | `AGENTS.md` §2 "当前状态" | +> | harness 工程健康度与未完事项 | `ai/harness-health.md` | +> | 架构与精度边界决策 | `ai/adr/0001-*.md`、`ai/adr/0002-*.md` | +> | 守卫规则 | `ai/risk-guardrails.md`（G1–G13） | +> +> 第 19 章（"v2: CoinGlass / v3: ETF Flow / v4: CME"）与 README 路线图（v2.x = MA/Bollinger/Vegas/箱体；v3 = CoinGlass + ETF + CME + …）**冲突，以 README 为准**。 +> +> 其余章节（数据模型、Binance 字段解析、SQL schema 设计、Clean Arch 分层动机）仍有参考价值，可作为设计源头阅读，但需自行用代码与 ADR 校核是否仍现状成立。 -```text -docs/development.md -``` +--- # Hermes Market Data Gateway 开发文档