From f59388f69a9e1c40c7e466203dc4225950018b3b Mon Sep 17 00:00:00 2001 From: Tacit Lab Date: Wed, 15 Apr 2026 21:31:08 +0800 Subject: [PATCH] docs: refresh README with current architecture and beautified title --- README.md | 378 +++++++++++++++++++++++++++--------------------------- 1 file changed, 187 insertions(+), 191 deletions(-) diff --git a/README.md b/README.md index 78b5852..b8ee897 100644 --- a/README.md +++ b/README.md @@ -1,161 +1,149 @@ -# coinhunter-cli + + +

+
+ CoinHunter CLI +

- The executable CLI layer for CoinHunter.
- Runtime-safe trading operations, precheck orchestration, review tooling, and market probes. + Runtime-safe trading operations, precheck orchestration, review tooling, and market probes.

- Python - Status - Architecture + + + +

-## 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.