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 无具体实现依赖，全项目 无私钥/签名字段。
This commit is contained in:
dela
103
ai/harness-health.md
Normal file
103
ai/harness-health.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# 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。如未来要差异化对待，再分裂。
|
||||
Reference in New Issue
Block a user