Optimize CLI implementation using Cobra framework

CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+- **Professional CLI Framework**: Migrated from manual flag parsing to [Cobra](https://github.com/spf13/cobra), following best practices from [longbridge-terminal](https://github.com/longbridge/longbridge-terminal)
+- **Improved Help System**: Rich help text with examples for all commands
+- **Verbose Mode**: Global `--verbose` flag for detailed logging during operations
+- **Shell Completion**: Auto-generated completion scripts for bash, zsh, fish, and PowerShell
+- **Better Error Messages**: User-friendly error messages with emoji indicators (✓, ⚠, ❌, 🚀, 🛑, 🔧)
+- **Enhanced Makefile**:
+  - Default `make` now shows help (instead of building)
+  - New `dev-verbose` target for mock mode with verbose output
+  - Improved help with examples and version information
+
+### Changed
+- **Command Structure**:
+  - `longbridge-fs --version` instead of `longbridge-fs version`
+  - Consistent flag naming across all commands
+  - Better organized command hierarchy
+- **Controller Logging**: Enhanced with emoji indicators for better readability
+- **Init Command**: Now provides verbose output showing each created file/directory
+
+### Improved
+- CLI follows modern command-line interface conventions
+- Better integration with AI agents and scripting tools
+- More informative progress indicators during operations
+- Professional output formatting matching industry standards
+
+## Inspiration
+
+These improvements were inspired by the official [Longbridge Terminal CLI](https://github.com/longbridge/longbridge-terminal), which demonstrates best practices for building AI-native command-line tools for financial trading platforms.

Makefile

@@ -1,4 +1,4 @@
-.PHONY: build clean test run install
+.PHONY: build clean test run install init help
 
 # Go parameters
 GOCMD=go
@@ -23,6 +23,9 @@ VERSION=$(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 BUILD_TIME=$(shell date -u '+%Y-%m-%d_%H:%M:%S')
 LDFLAGS=-ldflags "-X main.Version=$(VERSION) -X main.BuildTime=$(BUILD_TIME)"
 
+# Default target
+.DEFAULT_GOAL := help
+
 all: clean deps build
 
 build:
@@ -45,8 +48,13 @@ deps:
 test:
 	$(GOTEST) -v ./...
 
+# Initialize file system (creates default directories)
+init: build
+	@echo "Initializing file system..."
+	$(BUILD_DIR)/$(BINARY_NAME) init --root ./fs
+
 run: build
-	@echo "Running controller..."
+	@echo "Running controller with real API..."
 	$(BUILD_DIR)/$(BINARY_NAME) controller --root ./fs --credential ./configs/credential
 
 install: build
@@ -59,8 +67,14 @@ uninstall:
 
 # Development helpers
 dev: build
+	@echo "Running controller in mock mode..."
 	$(BUILD_DIR)/$(BINARY_NAME) controller --root ./fs --mock
 
+# Run with verbose output
+dev-verbose: build
+	@echo "Running controller in mock mode with verbose output..."
+	$(BUILD_DIR)/$(BINARY_NAME) controller --root ./fs --mock --verbose
+
 fmt:
 	@echo "Formatting code..."
 	$(GOCMD) fmt ./...
@@ -78,16 +92,34 @@ docker-run:
 
 # Help
 help:
+	@echo "Longbridge FS - File system-based stock trading framework"
+	@echo ""
 	@echo "Usage: make [target]"
 	@echo ""
-	@echo "Targets:"
-	@echo "  build        Build the binary"
-	@echo "  clean        Clean build artifacts"
-	@echo "  deps         Download dependencies"
-	@echo "  test         Run tests"
-	@echo "  run          Run the controller"
-	@echo "  dev          Run in mock mode (no API)"
-	@echo "  install      Install to /usr/local/bin"
-	@echo "  fmt          Format code"
-	@echo "  lint         Lint code"
-	@echo "  help         Show this help"
+	@echo "Available targets:"
+	@echo "  build         Build the binary"
+	@echo "  clean         Clean build artifacts"
+	@echo "  deps          Download and tidy dependencies"
+	@echo "  test          Run tests"
+	@echo "  init          Initialize FS directory structure"
+	@echo "  run           Run controller with real API"
+	@echo "  dev           Run controller in mock mode (no API)"
+	@echo "  dev-verbose   Run controller in mock mode with verbose output"
+	@echo "  install       Install to /usr/local/bin"
+	@echo "  uninstall     Remove from /usr/local/bin"
+	@echo "  fmt           Format code"
+	@echo "  lint          Lint code (requires golangci-lint)"
+	@echo "  help          Show this help message"
+	@echo ""
+	@echo "Docker targets:"
+	@echo "  docker-build  Build Docker image"
+	@echo "  docker-run    Run Docker container"
+	@echo ""
+	@echo "Examples:"
+	@echo "  make build              # Build the binary"
+	@echo "  make init               # Initialize file system"
+	@echo "  make dev                # Run in mock mode"
+	@echo "  make run                # Run with real API"
+	@echo ""
+	@echo "Version: $(VERSION)"
+	@echo "Build time: $(BUILD_TIME)"

README.md

@@ -15,6 +15,7 @@ Longbridge FS 是一个基于文件系统的股票交易框架，通过读写文
 
 - **文件驱动** — 通过文件读写完成所有交易操作，AI Agent 无需学习 API
 - **AI 友好** — JSON 输出，天然适配 AI Agent 的文件操作能力
+- **专业 CLI** — 使用 Cobra 框架构建，提供现代化的命令行体验（参考 [longbridge-terminal](https://github.com/longbridge/longbridge-terminal) 官方实践）
 - **实时行情** — 支持 WebSocket 订阅，高效获取实时行情推送
 - **审计追踪** — 所有交易记录在 beancount 格式的 append-only 账本中
 - **盈亏追踪** — 自动生成 `pnl.json` 和 `portfolio.json`，实时追踪持仓盈亏
@@ -107,18 +108,62 @@ make run
 ### CLI 参数
 
 ```
-Usage: longbridge-fs <command> [options]
+Usage: longbridge-fs [command] [flags]
 
 Commands:
   init         初始化 FS 目录结构
   controller   启动交易控制器守护进程
+  help         获取任何命令的帮助
+  completion   生成 shell 自动补全脚本
 
-Options for controller:
+Global Flags:
+  -v, --verbose         启用详细输出
+  --version            显示版本信息
+
+查看子命令帮助:
+  longbridge-fs [command] --help
+```
+
+#### init 命令
+
+```
+初始化 FS 目录结构，创建必要的目录和默认配置文件
+
+Flags:
+  --root PATH           FS 根目录 (default: .)
+  -h, --help            显示帮助信息
+```
+
+#### controller 命令
+
+```
+启动交易控制器守护进程
+
+功能:
+  - 处理 beancount.txt 中的新订单
+  - 刷新账户状态和持仓
+  - 通过 WebSocket 更新实时行情
+  - 生成 PnL 和组合报告
+  - 执行风控规则（止损/止盈）
+  - 压缩历史账本到区块文件
+
+Flags:
   --root PATH           FS 根目录 (default: .)
   --interval DURATION   轮询间隔 (default: 2s)
   --credential FILE     凭证文件路径 (default: credential)
   --mock                Mock 模式，不调用 API (default: false)
   --compact-after N     每 N 笔执行后压缩归档, 0=禁用 (default: 10)
+  -h, --help            显示帮助信息
+
+示例:
+  # 真实 API 模式
+  longbridge-fs controller --root ./fs --credential ./configs/credential
+
+  # Mock 模式（无需 API）
+  longbridge-fs controller --root ./fs --mock
+
+  # 自定义轮询间隔
+  longbridge-fs controller --root ./fs --interval 5s --verbose
 ```
 
 ## 使用示例