Files

dela cc7f5a4f32 feat: 初始化 cryptoHermes 行情网关 v1 MVP + harness 工程文档

Binance USDⓈ-M Futures 行情网关，给上游 Hermes 量化分析引擎提供单一聚合
接口 /v1/market/context（K 线 + funding + OI + 多空比 + taker volume）。
只读公共行情，不下单、不接私钥、不查账户。

## v1 实现范围（Milestone 1-5）

- Clean Architecture 4 层（controller/usecase/repo/entity），接口边界在
  internal/usecase/ports.go
- Binance Futures REST client（K 线 / ticker24h / funding / OI / 多空比
  / taker volume 共 9 个接口），全链路 string 价格避免 float64 精度问题
- TimescaleDB 5 张 hypertable（market_klines / funding_rates /
  open_interest / long_short_ratio / taker_buy_sell_volume），主键含
  时间维度，UpsertMany 幂等
- robfig/cron 定时采集（15m/1h/4h/1d/1w 多周期 K 线 + 衍生品 15 分钟
  落库），未收线 K 线 (close_time > now) 由 mapper/repo 双重过滤
- pkg/httpclient 统一限流（默认 20 req/s, burst 40）+ 重试，避免触发
  Binance 2400 weight/min IP 上限
- /v1/market/context 聚合接口：errgroup 并发拉 snapshot/funding/OI，DB
  K 线不足 200 根回源 Binance 异步补
- cmd/backfill CLI 支持指定 from/to 大段回填（Binance 历史 OI / 多空比
  官方只保留 30 天，必须自己存）
- Docker Compose + Makefile + golang-migrate，本地一键启

技术指标（support/resistance/Vegas/箱体）留待 v2，技术段返回空对象 +
warning 占位。

## Harness 工程文档

- AGENTS.md — AI agent 工作速查（10 个章节）
- ai/project-map.md — 仓库结构、扩展点、控制流
- ai/risk-guardrails.md — G1-G10 守卫规则（每条带可机械验证命令）
- ai/adr/0001-architecture-foundations.md — 9 条架构基础决策
- ai/task-templates.md — 6 种任务契约模板
- ai/harness-health.md — 当前 harness 健康度评估

3 个 grep 守卫已验证通过：controller / usecase 无具体实现依赖，全项目
无私钥/签名字段。

2026-05-24 17:20:51 +08:00

5.2 KiB

Raw Blame History

Harness Health — cryptoHermes

日期：2026-05-24 版本：v1 MVP 刚完成（Milestone 1-5）

按 he-maintainer 的 scoring rubric 评估当前 harness 工程状态。Rating: strong / partial / weak。

总览

维度	Rating	说明
项目地图清晰度	strong	`ai/project-map.md` 完整覆盖 Clean Arch 4 层 + 数据流 + 扩展点
验证命令可跑	strong	Makefile 全部命令在 README + AGENTS.md 双重列出
快速反馈环路	strong	`go build ./...` < 2s，`go vet ./...` < 1s，单包测试支持
任务契约质量	partial	模板已写（`ai/task-templates.md`），但还没有真实任务用过
守卫规则清晰度	strong	10 条 G1-G10，每条都有可机械验证命令
架构决策耐久度	strong	ADR 0001 记录 9 条核心决策；其他 ADR 等触发
Spec / test-plan	partial	还没有 specs/，因为 v1 没有需要 spec 的任务；v2 新数据源时必填
失败反馈环路	partial	AGENTS.md §10 写了升级时机，但还没有 `ai/risk-guardrails.md` 改动史可参考
文档 vs 代码对齐	strong	AGENTS.md / README / project-map 全部基于实际仓库结构
MEMORY / 长期上下文	n/a	本仓库无 `MEMORY.md`，按设计——长期知识在 `docs/dev.md` 和 `ai/` 文档中

总体：strong（MVP 完成时点适用），但有 2 个 partial：

task-templates 未经过真实任务校验
specs/ 目录还是空的（等 v2 需要时填）

已具备的工程基础

3 层 AI 文档系统：AGENTS.md（速查）→ ai/project-map.md（结构）→ ai/adr/（决策）。docs/dev.md 作为最详细的设计源头单独存在。
可机械验证的守卫：G1-G10 全部给了 grep / make 命令，没有靠 review 的软规则。
唯一的组合根：internal/app/app.go，DI 一处可见。
接口边界文件：internal/usecase/ports.go 是唯一定义对外接口的位置，新 agent 找接口去这里。
强约束 grep 在 AGENTS.md §6：每次 PR 都可以直接跑。

已识别的薄弱点

W1. task-templates 未经过实战

现状：模板已写完，但没有 PR 用过这些契约。影响：模板可能太严格或太松。 纠正时机：完成第一个非平凡 PR（比如 Milestone 6 的技术指标）后回看，调整模板。

W2. 还没有 work-status.md

现状：目前是单 agent / 单会话工作，不需要 work-status 协调。影响：暂无。 升级时机：开始 Milestone 6（技术指标）或 v2（新数据源）时，如果跨多次会话，建立 ai/work-status.md。

W3. CI 完全未搭建

现状：本地有 make test / go vet，但仓库无 GitHub Actions / GitLab CI。影响：守卫规则全靠人工跑 grep。 升级时机：合并第一个外部 PR 前，搭一个最小 CI（go build + go vet + grep 边界检查 + migration up/down）。

W4. 单元测试覆盖率未度量

现状：MVP 阶段重点是端到端可用，未补单测覆盖率。影响：refactor 时风险偏高。 升级时机：Milestone 6 引入指标计算（计算正确性 critical）前，先补 mapper / repo 的 table-driven 测试。

W5. 部分 docs/* 未提交到 git

现状：docs/dev.md 是 untracked（git status 显示 ?? docs/）。 纠正方式：本次 commit 一起加进来。

后续升级触发器

触发条件	应采取的动作
同一类错误第二次出现	加进 `ai/risk-guardrails.md`，给可验证命令
重大架构决策（换 HTTP 框架 / 引入 MQ / 跨服务通信）	写新 ADR
新增数据源（CoinGlass / ETF / CME）	必填 `ai/specs/<source>.md`
跨多次会话的长任务	写 `ai/work-status.md`
单测/集成测试出现 flake	加 test-plan，约定 retry / quarantine 策略
文档与代码出现漂移（grep 守卫失败但代码正常）	立刻同步，不要"以代码为准"绕开守卫

复评建议

3 个月后（约 2026-08）：复评本文件。若 v2 数据源工作启动，至少需要 1 份 spec + 可能新 ADR。
每次新 Milestone 完成时：跑一次 AGENTS.md §6 的 3 个 grep，确认边界未漂移。
新成员（agent 或人）首次提 PR 后：根据他们卡住的地方反向更新 AGENTS.md / project-map（"如果他们卡过这里，下一个人也会卡"）。

Harness 文件清单（截至本次 commit）

AGENTS.md                                  ← AI agent 速查
README.md                                  ← 用户向使用文档
docs/dev.md                                ← 完整设计文档（源头）
ai/project-map.md                          ← 仓库结构与扩展点
ai/risk-guardrails.md                      ← G1-G10 守卫规则
ai/adr/0001-architecture-foundations.md    ← 9 条架构基础决策
ai/task-templates.md                       ← 6 种任务模板
ai/harness-health.md                       ← 本文件

CLAUDE.md / GEMINI.md / .cursor/*.md 等其他 AI 工具的入口文件——暂不需要，因为这些工具都会读 AGENTS.md。如未来要差异化对待，再分裂。

5.2 KiB Raw Blame History Unescape Escape