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

docs: refresh README with current architecture and beautified title

Browse Source
This commit is contained in:
Tacit Lab
2026-04-15 21:31:08 +08:00
parent a61c329496
commit f59388f69a
1 changed files with 187 additions and 191 deletions
Download Patch File Download Diff File Expand all files Collapse all files

378
README.md
View File

@@ -1,161 +1,149 @@
# coinhunter-cli
<!--
╔══════════════════════════════════════════════════════════════════════════════╗
║ ║
║ ██████╗ ██╗ ██╗██╗███╗ ██╗██╗ ██╗██╗ ██╗███╗ ██╗████████╗███████╗██████╗ ║
║ ██╔════╝ ██║ ██║██║████╗ ██║██║ ██║██║ ██║████╗ ██║╚══██╔══╝██╔════╝██╔══██╗ ║
║ ██║ ██║ ██║██║██╔██╗ ██║███████║██║ ██║██╔██╗ ██║ ██║ █████╗ ██████╔╝ ║
║ ██║ ╚██╗ ██╔╝██║██║╚██╗██║██╔══██║██║ ██║██║╚██╗██║ ██║ ██╔══╝ ██╔══██╗ ║
║ ╚██████╗ ╚████╔╝ ██║██║ ╚████║██║ ██║╚██████╔╝██║ ╚████║ ██║ ███████╗██║ ██║ ║
║ ╚═════╝ ╚═══╝ ╚═╝╚═╝ ╚═══╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚═╝ ╚══════╝╚═╝ ╚═╝ ║
║ ║
║ The Executable CLI Layer for CoinHunter ║
║ ║
╚══════════════════════════════════════════════════════════════════════════════╝
-->
<h1 align="center">
<br>
<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=28&duration=3000&pause=1000&color=F7B93E&center=true&vCenter=true&width=435&lines=CoinHunter+CLI;Trade+Smarter+%E2%9A%A1+Execute+Faster" alt="CoinHunter CLI" />
</h1>
<p align="center">
<strong>The executable CLI layer for CoinHunter.</strong><br/>
Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.
<strong>Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.</strong>
</p>
<p align="center">
<img alt="Python" src="https://img.shields.io/badge/python-3.10%2B-blue" />
<img alt="Status" src="https://img.shields.io/badge/status-active%20development-orange" />
<img alt="Architecture" src="https://img.shields.io/badge/architecture-runtime%20%2B%20commands%20%2B%20services-6f42c1" />
<a href="#"><img src="https://img.shields.io/badge/python-3.10%2B-3776ab?style=flat-square&logo=python&logoColor=white" /></a>
<a href="#"><img src="https://img.shields.io/badge/status-active%20development-22c55e?style=flat-square" /></a>
<a href="#"><img src="https://img.shields.io/badge/architecture-cli%20%2B%20commands%20%2B%20services-8b5cf6?style=flat-square" /></a>
<a href="#"><img src="https://img.shields.io/badge/tests-needed-ef4444?style=flat-square" /></a>
</p>
## Why this repo exists
---
CoinHunter is evolving from a loose bundle of automation scripts into a proper installable command-line tool.
## What is this?
This repository is the tooling layer:
`coinhunter-cli` is the **executable tooling layer** for CoinHunter — an installable Python CLI that handles trading operations, market probes, precheck orchestration, and review workflows.
- Code and executable behavior live here.
- User runtime state lives in `~/.coinhunter/` by default.
- Hermes skills can call this CLI instead of embedding large script collections.
- Runtime paths can be overridden with `COINHUNTER_HOME`, `HERMES_HOME`, `COINHUNTER_ENV_FILE`, and `HERMES_BIN`.
| Layer | Responsibility | Location |
|-------|----------------|----------|
| **CLI** | Top-level command router | `cli.py` |
| **Commands** | Thin argument adapters | `commands/` |
| **Services** | Orchestration & execution logic | `services/` |
| **Runtime** | Paths, env, locks, config | `runtime.py` |
| **User Data** | State, logs, reviews, positions | `~/.coinhunter/` |
In short:
> **Separation of concerns:** Code lives in this repo. Your data lives in `~/.coinhunter/`. Strategy and prompting live in Hermes skills.
- `coinhunter-cli` = tool
- CoinHunter skill = strategy / workflow / prompting layer
- `~/.coinhunter` = user data, logs, state, reviews
---
## Current architecture
## Project Structure
```text
coinhunter-cli/
├── src/coinhunter/
│ ├── cli.py # top-level command router
│ ├── runtime.py # runtime paths + env loading
│ ├── doctor.py # diagnostics
│ ├── paths.py # runtime path inspection
│ ├── commands/ # thin CLI adapters
│ ├── services/ # orchestration / application services
│ └── *.py # compatibility modules + legacy logic under extraction
└── README.md
src/coinhunter/
├── cli.py # Unified command router
├── runtime.py # Runtime paths + env loading
├── logger.py # Structured logging utilities
├── commands/ # CLI adapters (thin, stateless)
│ ├── precheck.py
│ ├── smart_executor.py
│ ├── check_api.py
│ ├── doctor.py
│ ├── external_gate.py
│ ├── init_user_state.py
│ ├── market_probe.py
│ ├── paths.py
│ ├── review_context.py
│ ├── review_engine.py
│ └── rotate_external_gate_log.py
├── services/ # Orchestration & domain logic
│ ├── exchange_service.py
│ ├── portfolio_service.py
│ ├── trade_execution.py
│ ├── smart_executor_service.py
│ ├── smart_executor_parser.py
│ ├── execution_state.py
│ ├── precheck_service.py
│ ├── precheck_constants.py # thresholds & paths
│ ├── time_utils.py # UTC/local time helpers
│ ├── data_utils.py # json, hash, float, symbol norm
│ ├── state_manager.py # state load/save/sanitize
│ ├── market_data.py # exchange, OHLCV, metrics
│ ├── candidate_scoring.py # coin selection & scoring
│ ├── snapshot_builder.py # precheck snapshot construction
│ ├── adaptive_profile.py # trigger profile builder
│ ├── trigger_analyzer.py # trigger analysis core
│ ├── precheck_analysis.py # failure payloads
│ ├── precheck_snapshot.py # snapshot facade
│ ├── precheck_state.py # state facade
│ └── precheck_core.py # backward-compat export facade
├── precheck.py # Backward-compat root facade
├── smart_executor.py # Backward-compat root facade
└── *.py # Other compat / utility modules
```
The repo is actively being refactored toward a cleaner split:
- `commands/` → argument / CLI adapters
- `services/` → orchestration and application workflows
- `runtime/` → paths, env, files, locks, config
- future `domain/` → trading and precheck core logic
## Implemented command/service splits
The first extraction pass is already live:
- `smart-executor` → `commands.smart_executor` + `services.smart_executor_service`
- `precheck` → `commands.precheck` + `services.precheck_service`
- root modules are compatibility facades only:
- `src/coinhunter/precheck.py`
- `src/coinhunter/smart_executor.py`
- `precheck` internals now live in dedicated service modules:
- `services.precheck_core`
- `services.precheck_state`
- `services.precheck_snapshot`
- `services.precheck_analysis`
This keeps behavior stable while giving the codebase a cleaner landing zone for deeper refactors.
---
## Installation
Dedicated user-local install:
### Quick user install
```bash
./scripts/install_local.sh
```
This creates:
Creates:
- Virtualenv: `~/.local/share/coinhunter-cli/venv`
- Launcher: `~/.local/bin/coinhunter`
- app environment: `~/.local/share/coinhunter-cli/venv`
- launcher: `~/.local/bin/coinhunter`
The launcher behaves like a normal installed CLI and simply forwards into the dedicated virtualenv.
Editable install for development:
### Editable dev install
```bash
pip install -e .
```
Run directly after install:
Verify:
```bash
coinhunter --help
coinhunter --version
```
Short aliases are available for the most common commands. The original long-form command names remain supported for backward compatibility.
---
## Quickstart
## Command Reference
Initialize user state:
### Short aliases (recommended)
```bash
coinhunter init
coinhunter diag # runtime diagnostics
coinhunter paths # print resolved paths
coinhunter api-check # validate exchange credentials
coinhunter precheck # run precheck snapshot + trigger analysis
coinhunter exec bal # print balances as JSON
coinhunter exec overview # account overview as JSON
coinhunter exec hold # record a HOLD decision
coinhunter exec buy ENJUSDT 50 # buy $50 of ENJUSDT
coinhunter exec flat ENJUSDT # sell entire ENJUSDT position
coinhunter exec rotate PEPEUSDT ETHUSDT # rotate exposure
coinhunter gate # external gate orchestration
coinhunter review 12 # generate review context (last 12h)
coinhunter recap 12 # generate review report (last 12h)
coinhunter probe bybit-ticker BTCUSDT # market probe
coinhunter rotate-log # rotate external gate logs
```
Inspect runtime wiring:
```bash
coinhunter paths
coinhunter diag
```
Validate exchange credentials:
```bash
coinhunter api-check
```
Run precheck / gate plumbing:
```bash
coinhunter precheck
coinhunter precheck --mark-run-requested "external-gate queued cron run"
coinhunter precheck --ack "analysis finished"
coinhunter gate
```
Inspect balances or execute trading actions:
```bash
coinhunter exec bal
coinhunter exec overview
coinhunter exec hold
coinhunter exec buy ENJUSDT 50
coinhunter exec flat ENJUSDT
coinhunter exec rotate PEPEUSDT ETHUSDT
```
Preferred `exec` verbs are `bal`, `overview`, `hold`, `buy`, `flat`, and `rotate`.
Legacy forms remain supported for backward compatibility: `balances`, `balance`, `acct`, `status`, `sell-all`, `sell_all`, and `rebalance`.
Generate review data:
```bash
coinhunter review 12
coinhunter recap 12
```
Probe external market data:
```bash
coinhunter probe bybit-ticker BTCUSDT
coinhunter probe bybit-klines BTCUSDT 60 20
```
Long-form equivalents still work:
### Legacy long forms (still supported)
```bash
coinhunter doctor
@@ -168,109 +156,117 @@ coinhunter external-gate
coinhunter rotate-external-gate-log
```
Supported top-level commands and aliases remain:
### All supported commands
- `check-api` / `api-check`
- `doctor` / `diag`
- `external-gate` / `gate`
- `init`
- `market-probe` / `probe`
- `paths`
- `precheck`
- `review-context` / `review`
- `review-engine` / `recap`
- `rotate-external-gate-log` / `rotate-gate-log` / `rotate-log`
- `smart-executor` / `exec`
| Canonical | Aliases |
|-----------|---------|
| `check-api` | `api-check` |
| `doctor` | `diag` |
| `external-gate` | `gate` |
| `init` | — |
| `market-probe` | `probe` |
| `paths` | — |
| `precheck` | — |
| `review-context` | `review` |
| `review-engine` | `recap` |
| `rotate-external-gate-log` | `rotate-gate-log`, `rotate-log` |
| `smart-executor` | `exec` |
## Runtime model
---
Default layout:
## Quickstart
```text
~/.coinhunter/
├── accounts.json
├── config.json
├── executions.json
├── notes.json
├── positions.json
├── watchlist.json
├── logs/
├── reviews/
└── state/
```
Credential loading:
- Binance credentials are read from `~/.hermes/.env` by default.
- `COINHUNTER_ENV_FILE` can point to a different env file.
- `hermes` is resolved from `PATH` first, then `~/.local/bin/hermes`, unless `HERMES_BIN` overrides it.
## Useful commands
### Diagnostics
Initialize runtime state:
```bash
coinhunter init
```
Inspect the environment:
```bash
coinhunter diag
coinhunter paths
coinhunter diag
```
Validate API keys:
```bash
coinhunter api-check
```
### Trading and execution
```bash
coinhunter exec bal
coinhunter exec overview
coinhunter exec hold
coinhunter exec buy ENJUSDT 50
coinhunter exec flat ENJUSDT
coinhunter exec rotate FROMUSDT TOUSDT
```
### Precheck and orchestration
Run the precheck workflow:
```bash
coinhunter precheck
coinhunter gate
coinhunter rotate-gate-log
coinhunter rotate-log
coinhunter precheck --ack "analysis completed"
```
### Review and market research
Run the external gate:
```bash
coinhunter review 12
coinhunter recap 12
coinhunter probe bybit-ticker BTCUSDT
coinhunter gate
```
## Development notes
---
This project is intentionally moving in small, safe refactor steps:
## Runtime Model
1. Separate runtime concerns from hardcoded paths.
2. Move command dispatch into thin adapters.
3. Introduce orchestration services.
4. Extract reusable domain logic from large compatibility modules.
5. Keep cron / Hermes integration stable during migration.
Default data layout:
That means some compatibility modules still exist, but the direction is deliberate.
```text
~/.coinhunter/
├── config.json
├── positions.json
├── accounts.json
├── watchlist.json
├── notes.json
├── executions.json
├── logs/
├── reviews/
├── cache/
└── state/
├── precheck_state.json
└── external_gate.lock
```
## Near-term roadmap
Credential resolution:
- Extract more logic from `smart_executor.py` into dedicated execution / portfolio services.
- Continue shrinking `precheck.py` by moving snapshot and analysis internals into reusable modules.
- Add `domain/` models for positions, signals, and trigger analysis.
- Add tests for runtime paths, precheck service behavior, and CLI stability.
- Evolve toward a more polished installable CLI workflow.
- Binance API keys are read from `~/.hermes/.env` by default.
- Override with `COINHUNTER_ENV_FILE`.
- Override home with `COINHUNTER_HOME` or `HERMES_HOME`.
- `hermes` binary is resolved from `PATH`, then `~/.local/bin/hermes`, unless `HERMES_BIN` is set.
---
## Development Status
The codebase is actively maintained and refactored in small, safe steps.
**Recently completed:**
- ✅ Unified CLI entrypoint with short aliases
- ✅ Extracted `smart-executor` into `commands/` + `services/`
- ✅ Extracted `precheck` into 9 focused service modules
- ✅ Migrated all active command modules into `commands/`
- ✅ Removed dead `auto-trader` command
- ✅ Backward-compatible root facades preserved
**Next priorities:**
- 🧪 Add pytest coverage for runtime paths, state manager, and trigger analyzer
- 🔧 Extract `review_engine.py` core logic into `services/`
- 🔧 Unify output contract (JSON-first with `--pretty` option)
- 🔧 Add basic CI (lint + compileall + pytest)
---
## Philosophy
CoinHunter should become:
CoinHunter is evolving toward:
- more professional
- more maintainable
- safer to operate
- easier for humans and agents to call
- less dependent on prompt-only correctness
- **Professional execution** — scientific position sizing, not moonshot gambling
- **Maintainable architecture** — clear boundaries between CLI, services, and domain logic
- **Safer operations** — dry-run, validation gates, and explicit decision logging
- **Agent-friendly interfaces** — stable JSON outputs and predictable command contracts
- **Less dependence on prompt-only correctness** — logic belongs in code, not just in system prompts
This repo is where that evolution happens.