diff --git a/CLAUDE.md b/CLAUDE.md index 5f35168..82e2a62 100644 --- 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. diff --git a/README.md b/README.md index 3eb11f4..7bf6dde 100644 --- 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/ diff --git a/SKILL.md b/SKILL.md index dd59abf..922e931 100644 --- 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` | diff --git a/references/shim-templates.md b/references/shim-templates.md index c419495..41f9d9a 100644 --- 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. diff --git a/references/user-data-layout.md b/references/user-data-layout.md index 0963a87..596ec77 100644 --- 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/`