TacitLab/coinhunter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: simplify CLI to data layer for AI-assisted trading

Browse Source 
Transform CoinHunter from an over-engineered auto-trading system into a
lightweight data-layer CLI paired with the coinbuddy AI Skill.

Key changes:
- Remove non-core commands: backtest, strategy, opportunity dataset/evaluate/optimize
- Add scan: rule-based market screening (zero token cost)
- Add analyze: multi-timeframe technical analysis for AI consumption
- Add watch: lightweight portfolio anomaly monitoring (zero token cost)
- Remove services: backtest, dataset, evaluation, research, strategy
- Add analyze_service with RSI, key levels, alerts, and AI-friendly summaries
- Add watch_portfolio with drawdown/spike/concentration/technical triggers
- Simplify config: remove research/dataset settings, add watch thresholds
- Update TUI rendering for analyze and watch outputs
- Update tests and CLAUDE.md for new architecture

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Tacit Lab
2026-04-27 16:35:33 +08:00
parent e4b2239bcd
commit 76c4129c8d
18 changed files with 600 additions and 3142 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
CLAUDE.md
View File

@@ -14,31 +14,36 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
## Architecture
CoinHunter V2 is a Binance-first crypto trading CLI with a flat, direct architecture:
CoinHunter is a **lightweight data-layer CLI** designed to pair with the `coinbuddy` AI Skill for crypto trading on Binance. The philosophy is **layered screening**: the CLI handles cheap rule-based filtering and monitoring, while the AI Skill handles expensive deep analysis on a small set of curated candidates.
- **`src/coinhunter/cli.py`** — Single entrypoint (`main()`). Uses `argparse` to parse commands and directly dispatches to service functions. There is no separate `commands/` adapter layer. Top-level commands include `init`, `config`, `account`, `market`, `buy`, `sell`, `portfolio`, `opportunity`, `strategy`, `backtest`, `catlog`, `upgrade`, and `completion`.
- **`src/coinhunter/services/`** — Contains all domain logic:
- `account_service.py` — balances, positions, overview
### CLI layer (data + execution)
- **`src/coinhunter/cli.py`** — Single entrypoint (`main()`). Uses `argparse` to parse commands and directly dispatches to service functions. Core commands: `init`, `config`, `account`, `market`, `buy`, `sell`, `portfolio`, `scan`, `analyze`, `watch`, `upgrade`, `catlog`, `completion`.
- **`src/coinhunter/services/`** — Domain logic:
- `account_service.py` — balances, positions
- `market_service.py` — tickers, klines, scan universe, symbol normalization
- `signal_service.py` — shared market signal scoring used by scan and portfolio analysis
- `portfolio_service.py` — held-position review and add/hold/trim/exit recommendations
- `signal_service.py` — shared market signal scoring (rule-based, zero token cost)
- `portfolio_service.py` — held-position review (`analyze_portfolio`) and lightweight anomaly monitoring (`watch_portfolio`)
- `trade_service.py` — spot order execution only
- `opportunity_service.py` — market scanning and entry/watch/skip recommendations
- `opportunity_dataset_service.py` — historical kline dataset collection for backtesting
- `opportunity_evaluation_service.py` — walk-forward evaluation and model-weight optimization
- `research_service.py` — external research signal providers for opportunity scoring
- `strategy_service.py` — combines opportunity scanning and portfolio analysis into unified buy/sell/hold trade signals
- `backtest_service.py` — walk-forward backtest engine using historical kline datasets with virtual cash and positions
- **`src/coinhunter/binance/spot_client.py`** — Thin wrapper around `binance.spot.Spot`. Normalizes request errors into `RuntimeError` and handles single/multi-symbol ticker responses.
- `opportunity_service.py` — market scanning (`scan_opportunities`) returning top-N candidates
- `analyze_service.py` — multi-timeframe deep technical analysis for AI consumption
- **`src/coinhunter/binance/spot_client.py`** — Thin wrapper around `binance.spot.Spot`. Normalizes request errors into `RuntimeError`.
- **`src/coinhunter/config.py`** — `load_config()`, `get_binance_credentials()`, `ensure_init_files()`.
- **`src/coinhunter/runtime.py`** — `RuntimePaths`, `get_runtime_paths()`, `print_json()`.
- **`src/coinhunter/runtime.py`** — `RuntimePaths`, `get_runtime_paths()`, `print_json()`, TUI rendering.
- **`src/coinhunter/audit.py`** — Writes JSONL audit events to dated files.
### AI layer (decision)
- **`coinbuddy` Skill** — Lives at `~/.claude/skills/coinbuddy/SKILL.md`. Governs how the AI interacts with the CLI:
- **Discovery flow:** `scan` → `analyze` → AI synthesis → user confirm → `trade`
- **Portfolio flow:** `watch` → flag NEED_REVIEW → `analyze` → AI synthesis → user confirm → `trade`
- The Skill always uses `--agent` for structured JSON consumption.
## Runtime and environment
User data lives in `~/.coinhunter/` by default (override with `COINHUNTER_HOME`):
- `config.toml` — runtime, binance, trading, signal, opportunity, and portfolio settings
- `config.toml` — runtime, binance, trading, signal, opportunity, portfolio, and watch settings
- `.env` — `BINANCE_API_KEY` and `BINANCE_API_SECRET`
- `logs/audit_YYYYMMDD.jsonl` — structured audit log
- `logs/dry-run/audit_YYYYMMDD.jsonl` — dry-run audit log
@@ -49,25 +54,29 @@ Run `coinhunter init` to generate the config and env templates.
- **Symbol normalization:** `market_service.normalize_symbol()` strips `/`, `-`, `_`, and uppercases the symbol. CLI inputs like `ETH/USDT`, `eth-usdt`, and `ETHUSDT` are all normalized to `ETHUSDT`.
- **Dry-run behavior:** Trade commands support `--dry-run`. If omitted, the default falls back to `trading.dry_run_default` in `config.toml`.
- **Client injection:** Service functions accept `spot_client` as a keyword argument. This enables easy unit testing with mocks.
- **Client injection:** Service functions accept `spot_client` as a keyword argument for easy unit testing with mocks.
- **Error handling:** `spot_client.py` catches `requests.exceptions.SSLError` and `RequestException` and re-raises as human-readable `RuntimeError`. The CLI catches all exceptions in `main()` and prints `error: {message}` to stderr with exit code 1.
- **Ticker API fallback:** `spot_client.ticker_stats()` uses `rolling_window_ticker` for symbol-specific queries and `ticker_24hr` for full-market scans (no symbols).
- **Output modes:** All commands support `--agent` for JSON output and `--doc` to print the command's output schema.
- **Watch rules:** `portfolio_service.watch_portfolio()` monitors held positions for anomalies (1h/24h drawdowns, spikes, concentration risk, technical score deterioration). This is pure rule-based and costs zero tokens.
- **Analyze design:** `analyze_service.analyze_symbols()` fetches multi-timeframe klines (1h, 4h, 1d) and produces an AI-friendly output with `summary`, `timeframes`, `key_levels`, `alerts`, and `signal_score`. It is designed for LLM consumption.
## CLI command reference
| Command | Purpose | Token cost |
|---------|---------|-----------|
| `coin scan` | Rule-based market scan, returns top-N candidates | 0 |
| `coin analyze <sym>` | Multi-timeframe deep technical analysis | 0 |
| `coin watch` | Portfolio anomaly monitoring | 0 |
| `coin portfolio` | Full portfolio scoring | 0 |
| `coin account` | Balances | 0 |
| `coin buy/sell` | Trade execution | 0 |
## Testing
Tests live in `tests/` and use `unittest.TestCase` with `unittest.mock.patch`. The test suite covers:
- `test_cli.py` — parser smoke tests and dispatch behavior
- `test_config_runtime.py` — config loading, env parsing, path resolution
- `test_account_market_services.py` — balance/position/ticker/klines logic with mocked clients
- `test_trade_service.py` — spot trade execution paths
- `test_opportunity_service.py` — portfolio and scan scoring logic
- `test_opportunity_dataset_service.py` — dataset collection and walk-forward evaluation
- `test_opportunity_evaluation_service.py` — model weight optimization
- `test_strategy_service.py` — combined signal generation logic
- `test_backtest_service.py` — historical backtest engine
Tests live in `tests/` and use `unittest.TestCase` with `unittest.mock.patch`. The test suite covers CLI parser smoke tests, config loading, service logic with mocked clients, and trade execution paths.
## Notes
- `AGENTS.md` in this repo is stale and describes a prior V1 architecture (commands/, smart executor, precheck, review engine). Do not rely on it.
- Removed in the V2 simplification: `backtest`, `strategy`, `opportunity dataset/evaluate/optimize`, `research_service` (CoinGecko). These were over-engineered for the AI-assisted trading flow and have been archived out of the core codebase.