feat: add decision calibration, prediction tracking, and reference routing

SKILL.md - Add triggers/mode to frontmatter for better skill routing - Add mandatory JSON decision skeleton before every trade - Add multi-source confirmation rule and common-mistakes guardrails - Add prediction logging to hourly review workflow - Restructure References into an explicit routing table CLAUDE.md - Add Reference routing table for agent context - Fix remaining Hermes-only wording in gate description references/user-data-layout.md - Add complete log schema: decisions, trades, predictions, errors - Document predictions_YYYYMMDD.jsonl for calibration feedback loop README.md - Mention prediction tracking in "Why it works" - Update runtime directory layout to include predictions.jsonl references/shim-templates.md - Show platform cron config usage examples
2026-04-16 03:03:25 +08:00
parent e75c54ca12
commit d1737cdcb8
5 changed files with 179 additions and 20 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -36,7 +36,7 @@ The framework is designed to minimize LLM invocations:
 1. A lightweight local Python precheck script decides whether market conditions have changed materially.
 2. If `should_analyze=false`, the cron job emits `[SILENT]` and exits.
 3. If `should_analyze=true`, the LLM performs deep analysis and may execute trades.
-4. An optional external gate (system crontab) can run the precheck every 5 minutes and trigger the Hermes cron only on true events.
+4. An optional external gate (system crontab) can run the precheck every 5 minutes and trigger the platform cron only on true events.

 See `SKILL.md` (sections "Low-cost cron architecture" and "Building your own gate") for the full pseudocode, file layout, state schema, and troubleshooting.

@@ -98,6 +98,21 @@ When modifying or adding trading scripts, these safeguards from `SKILL.md` must
  coinhunter probe bybit-ticker
  ```

+## Reference routing
+
+When working on Coin Hunter, read the relevant reference file at the right moment:
+
+| Task context | File to read |
+|--------------|--------------|
+| Active trade decision (mainstream coin) | `references/short-term-trading-framework.md` |
+| Active trade decision (meme coin) | `references/short-term-trading-framework.md` + `references/scam-signals.md` |
+| Data source conflict / ambiguity | `references/provider-playbook.md` |
+| Hourly review formatting | `references/review-template.md` |
+| Runtime state / log schema questions | `references/user-data-layout.md` |
+| Binance API / auto-trading setup | `references/auto-trading-guide.md` |
+| Output format / report templates | `references/output-templates.md` |
+| Proactive discovery scan workflow | `references/search-workflow.md` |
+
 ## When making changes

 - If you change `SKILL.md`, check whether `README.md` needs corresponding updates.
--- a/README.md
+++ b/README.md
@@ -29,6 +29,7 @@
 - **Portfolio-first rule** — every decision anchors to your real balances, average costs, and exchange state.
 - **Scientific checklist** — 6 mandatory questions (trend, volume, levels, BTC context, opportunity cost, time window) before every trade.
 - **Hourly self-review** — the bot critiques its own decisions, flags over-trading / hesitation, and tunes parameters.
+- **Prediction tracking** — every decision writes an auditable prediction to `logs/predictions_YYYYMMDD.jsonl`; the review loop scores accuracy and surfaces systematic bias.
 - **Ultra-low running cost** — a lightweight local **gate** filters noise; the LLM only wakes up when the market actually changes.

 ---
@@ -51,7 +52,7 @@ flowchart TD

 ### Key components

-All operations go through the installed `coinhunter` CLI. This skill provides the framework specification, reference playbooks, and Hermes cron shims.
+All operations go through the installed `coinhunter` CLI. This skill provides the framework specification, reference playbooks, and cross-platform cron shims.

 | Command | Purpose |
 |---------|---------|
@@ -216,6 +217,7 @@ Your **private runtime** lives under `~/.coinhunter/`:
 ├── logs/
 │   ├── decisions_YYYYMMDD.jsonl
 │   ├── trades_YYYYMMDD.jsonl
+│   ├── predictions_YYYYMMDD.jsonl
 │   ├── errors_YYYYMMDD.jsonl
 │   └── external_gate.log
 └── reviews/
--- a/SKILL.md
+++ b/SKILL.md
@@ -1,6 +1,14 @@
 ---
 name: Coin Hunter
-description: Hybrid short-term crypto trading system — combining mainstream coin scalping with meme-coin opportunistic rotation, backed by hourly review and continuous strategy iteration.
+description: Hybrid short-term crypto trading system — combining mainstream coin scalping with meme-coin opportunistic rotation, backed by hourly review, prediction tracking, and continuous strategy iteration.
+triggers:
+  - "分析这个币"
+  - "coinhunter"
+  - "交易决策"
+  - "review"
+  - "recap"
+  - "执行交易"
+mode: agent-assisted
 ---

 # Coin Hunter
@@ -50,6 +58,46 @@ Before executing or recommending any action, answer:

 Read `references/short-term-trading-framework.md` before every active decision pass.

+## Decision calibration (mandatory JSON skeleton)
+
+Before finalizing any HOLD / SELL_ALL / REBALANCE / BUY decision, output this JSON block. It forces alignment between reasoning and action.
+
+```json
+{
+  "decision": "HOLD",
+  "confidence": 0.75,
+  "primary_reason": "BTC regime bearish contradicts long bias",
+  "risk_reward": 0.8,
+  "time_horizon_hours": 4,
+  "stop_loss": 0.0,
+  "take_profit": 0.0,
+  "max_loss_pct": 0.07
+}
+```
+
+Rules:
+- `confidence` must be 0.0–1.0. If < 0.55, default to HOLD unless there is an urgent risk-off reason.
+- `risk_reward` must be ≥ 1.0 to justify a new entry.
+- `stop_loss` and `take_profit` must be explicit numbers (not "TBD").
+- Only after outputting this JSON may you proceed to `coinhunter exec`.
+
+## Multi-source confirmation rule
+
+A signal strengthens only when confirmed by **2 or more independent data sources**:
+- Price action + volume expansion on Bybit/Binance
+- Narrative heat on Twitter/X + DEX flow on DexScreener
+- CEX listing rumor from exchange announcement + on-chain holder growth
+
+If a signal comes from a **single source only**, downgrade confidence by 0.15–0.25.
+
+## Common mistakes to avoid
+
+- Do NOT estimate PnL from memory; always read `positions.json` first.
+- Do NOT chase a coin that only appears on a single tiny DEX with no social footprint.
+- Do NOT output a trade recommendation without stating the exact stop-loss level.
+- Do NOT ignore contradictory BTC/ETH regime shifts when evaluating altcoin setups.
+- Do NOT override the position-sizing table based on "gut feeling."
+
 ## Workflow

 ### Discovery & Scanning
@@ -63,16 +111,21 @@ Read `references/short-term-trading-framework.md` before every active decision p
 1. Read balances and positions.
 2. Pull market data for holdings and candidates.
 3. Run the 6-question scientific checklist.
-4. Decide: **HOLD** / **SELL_ALL** / **REBALANCE** / **BUY**.
-5. Execute via the CLI (`coinhunter exec ...`).
-6. Log the full decision context via the CLI execution.
+4. Output the **decision calibration JSON skeleton**.
+5. Decide: **HOLD** / **SELL_ALL** / **REBALANCE** / **BUY**.
+6. Execute via the CLI (`coinhunter exec ...`).
+7. Write a `prediction` entry to `~/.coinhunter/logs/predictions_YYYYMMDD.jsonl` with expected price range and validation timestamp.

 ### Review (every hour)
 1. Run `coinhunter recap` to analyze all decisions from the past hour.
 2. Compare decision prices to current prices.
-3. Flag patterns: missed runs, bad entries, over-trading, hesitation.
-4. Output recommendations for parameter or blacklist adjustments.
-5. Save the review report to `~/.coinhunter/reviews/`.
+3. Read `~/.coinhunter/logs/predictions_YYYYMMDD.jsonl` and score prediction accuracy:
+   - If price landed inside the predicted range → +1 calibrated point
+   - If price moved opposite to the predicted direction → flag systematic bias
+   - If stop-loss was hit faster than predicted → widen risk buffer or reduce position size
+4. Flag patterns: missed runs, bad entries, over-trading, hesitation.
+5. Output recommendations for parameter or blacklist adjustments.
+6. Save the review report to `~/.coinhunter/reviews/`.

 ## Auto-trading architecture

@@ -358,10 +411,17 @@ Use `references/review-template.md` structure:
 - Strategy adjustments recommended
 - Action items for next hour

-## References
+## Reference routing

-Read `references/provider-playbook.md` for data source selection.
-Read `references/user-data-layout.md` for private state management.
-Read `references/short-term-trading-framework.md` for the hybrid trading framework.
-Read `references/review-template.md` for hourly report formatting.
-Read `references/scam-signals.md` when evaluating meme coins.
+Read these files at the exact moments below. Do not skip them.
+
+| When | Read this |
+|------|-----------|
+| Before every active trade decision (mainstream) | `references/short-term-trading-framework.md` |
+| Before every active trade decision (meme) | `references/short-term-trading-framework.md` + `references/scam-signals.md` |
+| Data source conflict or ambiguity | `references/provider-playbook.md` |
+| Hourly review | `references/review-template.md` |
+| Setting up runtime state or logging schema | `references/user-data-layout.md` |
+| Deploying auto-trading or Binance API | `references/auto-trading-guide.md` |
+| Evaluating output format | `references/output-templates.md` |
+| Running proactive discovery scans | `references/search-workflow.md` |
--- a/references/shim-templates.md
+++ b/references/shim-templates.md
@@ -12,11 +12,11 @@ cp scripts/coinhunter_shim.py ~/.hermes/scripts/coinhunter_shim.py
 cp scripts/coinhunter_shim.py ~/.openclaw/scripts/coinhunter_shim.py
 ```

-Usage examples:
- `coinhunter_shim.py pre`
- `coinhunter_shim.py gate`
- `coinhunter_shim.py review`
- `coinhunter_shim.py rotate-log`
+Usage in platform cron configs:
+- `"script": "coinhunter_shim.py pre"` — lightweight gate / precheck
+- `"script": "coinhunter_shim.py gate"` — external gate runner
+- `"script": "coinhunter_shim.py review"` — review context generator
+- `"script": "coinhunter_shim.py rotate-log"` — log rotation helper

 The real business logic lives in the external `coinhunter` CLI package (installed from PyPI). This shim only delegates to it.

--- a/references/user-data-layout.md
+++ b/references/user-data-layout.md
@@ -157,6 +157,88 @@ Example:
 ### cache/
 Store disposable API results or normalized snapshots. Never treat this as source-of-truth portfolio state.

+## Logs directory
+
+Runtime logs live under `~/.coinhunter/logs/` as daily JSONL files:
+
+```text
+~/.coinhunter/logs/
+├── decisions_YYYYMMDD.jsonl
+├── trades_YYYYMMDD.jsonl
+├── predictions_YYYYMMDD.jsonl
+├── errors_YYYYMMDD.jsonl
+└── external_gate.log
+```
+
+### decisions_YYYYMMDD.jsonl
+One line per agent decision pass.
+
+```json
+{
+  "schema_version": "1.0",
+  "decision_id": "uuid",
+  "timestamp": "2026-04-16T12:00:00Z",
+  "decision": "HOLD",
+  "confidence": 0.75,
+  "primary_reason": "BTC regime bearish",
+  "positions_hash": "abc123"
+}
+```
+
+### trades_YYYYMMDD.jsonl
+One line per executed trade.
+
+```json
+{
+  "schema_version": "1.0",
+  "decision_id": "uuid",
+  "timestamp": "2026-04-16T12:00:00Z",
+  "symbol": "BTCUSDT",
+  "side": "BUY",
+  "quantity": 0.01,
+  "price": 65000.0,
+  "status": "filled"
+}
+```
+
+### predictions_YYYYMMDD.jsonl
+One line per prediction made during execution. Used by the hourly review to calibrate accuracy.
+
+```json
+{
+  "schema_version": "1.0",
+  "decision_id": "uuid",
+  "timestamp": "2026-04-16T12:00:00Z",
+  "symbol": "BTCUSDT",
+  "decision": "HOLD",
+  "predicted_price_low": 64000.0,
+  "predicted_price_high": 67000.0,
+  "predicted_direction": "neutral",
+  "validation_time": "2026-04-16T16:00:00Z",
+  "stop_loss": 63000.0,
+  "take_profit": 68000.0,
+  "confidence": 0.75
+}
+```
+
+Rules for predictions:
+- `validation_time` should be 4 hours after `timestamp` by default.
+- Review logic compares `validation_time` price against `predicted_price_low/high`.
+- Systematic directional misses should trigger parameter tuning recommendations.
+
+### errors_YYYYMMDD.jsonl
+One line per error or reconciliation mismatch.
+
+```json
+{
+  "schema_version": "1.0",
+  "decision_id": "uuid",
+  "timestamp": "2026-04-16T12:00:00Z",
+  "error_type": "api_timeout",
+  "message": "Binance fetch_balance timed out after 30s"
+}
+```
+
 ## Rules

 - Keep personal data only under `~/.coinhunter/`