f3dc4d0939
为什么：原 controller handler 在 HTTP 层同时承担了 4 项 usecase 职责 （多源拼装、错误降级策略、limit 硬编码、响应结构组装），违反了 "controller 只做参数解析 + 调用 + 序列化" 的边界。等后续给衍生品加 缓存 / taker volume / 数据质量字段时，HTTP 层会持续变厚。 改动： - 新增 internal/usecase/market_query.go: MarketQueryUsecase.GetDerivatives() 并发拉 current funding/OI + 串行查历史 + 错误聚合为 warnings 返回 - /derivatives handler 退化到 4 行；MarketDeps / restapi.Deps 同步收窄 - /klines 保持直查 KlineRepo（thin query，G11 例外） - 新增 G11 守卫：grep "FundingRepo|OIRepo|LSRepo|TakerRepo" internal/controller 破坏性 API 变更（/derivatives 响应）： - 删除 funding.error / openInterest.error - 新增顶层 warnings: []string 顶层 symbol / funding / openInterest / longShortRatio / takerBuySellVolume 保持。 harness 同步： - AGENTS.md §6 加 G11 grep - ai/project-map.md 加 market_query.go + /derivatives 数据流分支 - ai/task-templates.md T6 加"破坏性变体"分支（本次重构暴露了原假设过严） - ai/harness-health.md W1 记一次轻量验证 + 守卫数 10→11 验收: go build / go vet / G6 grep / G11 grep 全绿。
5.5 KiB
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 | 11 条 G1-G11，每条都有可机械验证命令 |
| 架构决策耐久度 | 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 的技术指标）后回看，调整模板。
2026-05-24 更新：/derivatives controller→usecase 重构（抽 MarketQueryUsecase、新增 G11）算一次轻量验证。发现 T6 "API 响应字节级一致" 假设过严——抽离 usecase 时合理地把 sub-object error 字段升级成顶层 warnings 数组，已在 T6 加"破坏性变体"分支。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。如未来要差异化对待，再分裂。