From 61059143e65ac3c40bec2f011d95754787062cbe Mon Sep 17 00:00:00 2001
From: hazeone <709547807@qq.com>
Date: Wed, 29 Oct 2025 22:28:13 +0800
Subject: [PATCH 1/5] rewrite configuration guide

---
 docs/CONFIGURATION_GUIDE.md     | 649 ++++++++++++++++++++++++++++----
 python/configs/ENV_VARIABLES.md | 412 --------------------
 2 files changed, 568 insertions(+), 493 deletions(-)
 delete mode 100644 python/configs/ENV_VARIABLES.md

diff --git a/docs/CONFIGURATION_GUIDE.md b/docs/CONFIGURATION_GUIDE.md
index 502ab54df..d0851b64f 100644
--- a/docs/CONFIGURATION_GUIDE.md
+++ b/docs/CONFIGURATION_GUIDE.md
@@ -1,136 +1,623 @@
 # Configuration Guide
 
-Configure ValueCell using environment variables in the `.env` file.
+The ValueCell project uses a **three-tier configuration system** to enable flexible deployment from development to production. This guide covers all aspects of configuring agents, providers, and models.
+
+## Configuration Priority
+
+ValueCell resolves configuration from multiple sources in this order (highest to lowest priority):
+
+1. **Environment Variables** - Runtime overrides (e.g., `OPENROUTER_API_KEY`)
+2. **.env File** - User-level configuration (in project root)
+3. **YAML Files** - System defaults (in `python/configs/`)
+
+This hierarchy allows you to:
+- Set provider credentials via `.env` without modifying code
+- Override settings at runtime via environment variables
+- Maintain sensible defaults in YAML files
 
 ## Quick Start
 
+### Step 1: Get API Keys
+
+ValueCell supports multiple LLM providers. Choose at least one:
+
+| Provider | Sign Up |
+|----------|---------|
+| **OpenRouter** | [openrouter.ai](https://openrouter.ai/) |
+| **SiliconFlow** | [siliconflow.cn](https://www.siliconflow.cn/) |
+| **Google** | [ai.google.dev](https://ai.google.dev/) |
+| **OpenAI** | [platform.openai.com](https://platform.openai.com/) |
+
+### Step 2: Configure .env File
+
+Copy the example file and add your API keys:
+
 ```bash
+# In project root
 cp .env.example .env
-# Edit .env with your settings, then restart the application
 ```
 
-## Configuration Reference
+Edit `.env` and add your credentials:
 
-### Agent settings
+```bash
+# OpenRouter (recommended for multi-model support)
+OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxx
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `AGENT_DEBUG_MODE` | false | Enables verbose debugging for agents and planners: logs prompts, tool calls, intermediate steps, and provider response metadata. Useful for diagnosing model behavior; disable in production. |
+# Or SiliconFlow (best for Chinese models and cost)
+SILICONFLOW_API_KEY=sk-xxxxxxxxxxxxx
 
-Typical use cases:
+# Or Google Gemini
+GOOGLE_API_KEY=AIzaSyDxxxxxxxxxxxxx
 
-- Investigate unexpected model output or planning decisions
-- Verify tool-call routing and inputs/outputs
-- Capture detailed traces during local development
+# Optional: Set primary provider (auto-detected if not set)
+PRIMARY_PROVIDER=openrouter
+```
 
-Enable it in your `.env`:
+### Step 3: Launch Application
 
 ```bash
-AGENT_DEBUG_MODE=true
+# macOS / Linux
+bash start.sh
+
+# Windows PowerShell
+.\start.ps1
 ```
 
-> [!CAUTION]
-> Debug mode may log raw prompts and tool payloads (potentially sensitive). It can also increase latency and log volume. Prefer enabling only on local/dev environments.
+The system will auto-detect available providers based on configured API keys.
 
-### Localization
+> **Note**: If you get database compatibility errors, delete these directories:
+> - `lancedb/`
+> - `valuecell.db`
+> - `.knowledgebase`
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `LANG` | en-US | Supported: en_US, en_GB, zh-Hans, zh-Hant |
-| `TIMEZONE` | America/New_York | IANA timezone format |
+---
 
-These values act as user preferences. Agents use them for response language, locale-aware formatting, and time conversions.
+## Configuration System Architecture
 
-### Model Providers
+### File Structure
 
-**Required API Keys:**
+```
+python/
+├── configs/
+│   ├── config.yaml                    # Main configuration
+│   ├── config.{environment}.yaml      # Environment-specific overrides
+│   ├── providers/
+│   │   ├── openrouter.yaml           # OpenRouter provider config
+│   │   ├── siliconflow.yaml          # SiliconFlow provider config
+│   │   └── other_provider.yaml
+│   ├── agents/
+│   │   ├── super_agent.yaml          # Super Agent configuration
+│   │   ├── research_agent.yaml       # Research Agent configuration
+│   │   └── auto_trading_agent.yaml   # Auto Trading Agent configuration
+│   ├── agent_cards/                  # UI metadata for agents
+│   └── locales/                      # Internationalization files
+└── valuecell/
+    └── config/
+        ├── constants.py              # Configuration constants
+        ├── loader.py                 # YAML loader with env var resolution
+        └── manager.py                # High-level configuration API
+```
 
-- `OPENROUTER_API_KEY` - Get from [openrouter.ai](https://openrouter.ai/)
-- `GOOGLE_API_KEY` - [Optional] Get from [Google AI Studio](https://aistudio.google.com/api-keys)
+### How Configuration Resolution Works
 
-**Note**:
+#### 1. Provider Configuration Loading
 
-- OpenRouter API keys are the primary path to LLM access; you can pick models on OpenRouter.
-- Gemini models are currently used only by the Planner and Research Agent. If `GOOGLE_API_KEY` is set, Planner and Research Agent will use Gemini native apis.
+When the system needs a model, it:
 
-> [!IMPORTANT]
-> On OpenRouter, the models `google/gemini-2.5-flash` and `google/gemini-2.5-pro` have compatibility issues at the moment. Prefer using a `GOOGLE_API_KEY` with Google AI Studio for Gemini, or select a stable alternative on OpenRouter.
+1. **Loads provider YAML** (e.g., `configs/providers/openrouter.yaml`)
+2. **Resolves `${VAR}` placeholders** in YAML using environment variables
+3. **Applies env variable overrides** (e.g., `OPENROUTER_API_KEY` overrides `connection.api_key`)
+4. **Returns ProviderConfig** object with resolved values
 
-**Model Selection:**
+**Example: OpenRouter Configuration**
 
-Role overview: the Planner is the central orchestrator (SuperAgent) that plans tasks and delegates to specialized agents (e.g., Research, Product).
+```yaml
+connection:
+  base_url: "https://openrouter.ai/api/v1"
+  api_key_env: "OPENROUTER_API_KEY"    # Specifies which env var to use
 
-| Variable | Default |
-|----------|---------|
-| `PLANNER_MODEL_ID` | google/gemini-2.5-flash |
-| `RESEARCH_AGENT_MODEL_ID` | google/gemini-2.5-flash |
-| `PRODUCT_MODEL_ID` | anthropic/claude-haiku-4.5 |
+default_model: "anthropic/claude-haiku-4.5"
+
+defaults:
+  temperature: 0.5
+  max_tokens: 4096
+```
+
+The system automatically reads `OPENROUTER_API_KEY` from `.env` or environment.
+
+#### 2. Agent Configuration Loading
+
+When you create an agent (e.g., `research_agent`), the system:
+
+1. **Loads agent YAML** (e.g., `configs/agents/research_agent.yaml`)
+2. **Resolves environment variable syntax** (`${VAR:default}`)
+3. **Applies environment variable overrides** via `env_overrides` map
+4. **Merges with global defaults** from `config.yaml`
+5. **Returns AgentConfig** object with complete configuration
+
+**Example: Agent Configuration**
+
+```yaml
+name: "Research Agent"
+enabled: true
+
+models:
+  primary:
+    model_id: "google/gemini-2.5-flash"
+    provider: "openrouter"
+    provider_models:
+      siliconflow: "Qwen/Qwen3-235B-A22B-Thinking-2507"
+      google: "gemini-2.5-flash"
+    parameters:
+      temperature: 0.7
+
+env_overrides:
+  RESEARCH_AGENT_MODEL_ID: "models.primary.model_id"
+  RESEARCH_AGENT_PROVIDER: "models.primary.provider"
+```
+
+This allows runtime overrides:
 
-> [!CAUTION]
-> Model ID formats differ by provider: OpenRouter uses `provider/model` (e.g., `openai/gpt-4o-mini`), while native APIs (e.g., Google) use provider-specific names (e.g., `gemini-2.5-flash`).
+```bash
+export RESEARCH_AGENT_MODEL_ID="anthropic/claude-3.5-sonnet"
+export RESEARCH_AGENT_PROVIDER="openrouter"
+# Now research agent uses Claude 3.5 Sonnet instead of Gemini
+```
+
+---
+
+## Detailed Configuration Reference
+
+### Global Configuration (`config.yaml`)
+
+The main configuration file sets system-wide defaults:
+
+```yaml
+models:
+  # Primary provider used if API keys from multiple providers are available
+  primary_provider: "openrouter"
+  
+  # Global default parameters (used by all models unless overridden)
+  defaults:
+    temperature: 0.5
+    max_tokens: 4096
+  
+  # Provider registry
+  providers:
+    openrouter:
+      config_file: "providers/openrouter.yaml"
+      api_key_env: "OPENROUTER_API_KEY"
+    siliconflow:
+      config_file: "providers/siliconflow.yaml"
+      api_key_env: "SILICONFLOW_API_KEY"
+    google:
+      config_file: "providers/google.yaml"
+      api_key_env: "GOOGLE_API_KEY"
+
+# Agent registry
+agents:
+  super_agent:
+    config_file: "agents/super_agent.yaml"
+  research_agent:
+    config_file: "agents/research_agent.yaml"
+  auto_trading_agent:
+    config_file: "agents/auto_trading_agent.yaml"
+```
+
+### Provider Configuration
+
+Each provider has its own YAML file in `configs/providers/`. Here's the structure:
+
+```yaml
+name: "Provider Display Name"
+provider_type: "provider_id"           # Used internally
+enabled: true                          # Can be disabled without deleting config
+
+# Connection details
+connection:
+  base_url: "https://api.example.com/v1"
+  api_key_env: "PROVIDER_API_KEY"      # Which env var to read
+  endpoint_env: "PROVIDER_ENDPOINT"    # Optional: for Azure-style endpoints
+
+# Default model when none specified
+default_model: "model-id"
+
+# Default parameters for all models from this provider
+defaults:
+  temperature: 0.7
+  max_tokens: 4096
+  top_p: 0.95
+
+# List of available models
+models:
+  - id: "model-id-1"
+    name: "Model Display Name"
+    context_length: 128000
+    max_output_tokens: 8192
+  
+  - id: "model-id-2"
+    name: "Another Model"
+    context_length: 256000
+
+# Embedding configuration (optional, not all providers support it)
+embedding:
+  default_model: "embedding-model-id"
+  
+  defaults:
+    dimensions: 1536
+    encoding_format: "float"
+  
+  models:
+    - id: "embedding-model-id"
+      name: "Embedding Model"
+      dimensions: 1536
+      max_input: 8192
+
+# Provider-specific configuration
+extra_headers:
+  HTTP-Referer: "https://valuecell.ai"
+  X-Title: "ValueCell"
+```
+
+### Agent Configuration
+
+Agent YAML files define how agents should be initialized. Key features:
+
+```yaml
+name: "Agent Display Name"
+enabled: true
+
+# Model configuration
+models:
+  # Primary reasoning model
+  primary:
+    model_id: "model-id"               # Can use provider prefix (e.g., "anthropic/claude-3.5-sonnet")
+    provider: "openrouter"             # Must be explicit (not auto-detected)
+    
+    # Fallback models for different providers
+    provider_models:
+      siliconflow: "qwen/qwen-max"
+      google: "gemini-2.5-flash"
+    
+    # Model-specific parameters (override provider defaults)
+    parameters:
+      temperature: 0.8
+      max_tokens: 8192
+  
+  # Optional: separate embedding model configuration
+  embedding:
+    model_id: "embedding-model-id"
+    provider: "siliconflow"
+    provider_models:
+      google: "gemini-embedding-001"
+    parameters:
+      dimensions: 2560
+
+# Map environment variables to config paths for runtime overrides
+env_overrides:
+  # Syntax: ENV_VAR -> config.path.to.value
+  AGENT_MODEL_ID: "models.primary.model_id"
+  AGENT_PROVIDER: "models.primary.provider"
+  AGENT_TEMPERATURE: "models.primary.parameters.temperature"
+  AGENT_MAX_TOKENS: "models.primary.parameters.max_tokens"
+  
+  # Embedding configuration
+  AGENT_EMBEDDER_MODEL: "models.embedding.model_id"
+  AGENT_EMBEDDER_PROVIDER: "models.embedding.provider"
+
+# API keys required by this agent
+api_keys:
+  news_api:
+    key_env: "NEWS_API_KEY"
+    required: false
+    description: "Optional: For enhanced news searching"
+
+# Agent capabilities
+capabilities:
+  web_search: true
+  web_crawl: true
+  session_management:
+    enabled: true
+    max_history_runs: 5
+  
+# Advanced settings
+advanced:
+  debug_mode: false
+  markdown_output: false
+  add_datetime_to_context: true
+  read_chat_history: true
+```
 
-### Embedding and RAG
+---
 
-Embeddings power the local knowledge base (RAG) for retrieval. ValueCell stores vectors in LanceDB under `lancedb/`, enabling semantic search over your research notes.
+## Provider Auto-Detection and Fallback
 
-> [!IMPORTANT]
-> For now, we support OpenAI compatible embedding services. Some embedding models have fixed dimensions. Set `EMBEDDER_DIMENSION` to the model’s exact output size; mismatches will cause runtime errors.
+### Auto-Detection
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `EMBEDDER_API_KEY` | Yes | API key |
-| `EMBEDDER_BASE_URL` | Yes | API base URL, (`https://api.openai.com/v1`, if not set) |
-| `EMBEDDER_MODEL_ID` | Yes | Model identifier (text-embedding-3-small, if not set) |
-| `EMBEDDER_DIMENSION` | Yes | Vector dimension (1568, if not set) |
+ValueCell automatically selects a primary provider based on available API keys:
+
+**Priority order** (if multiple providers have API keys):
+
+The selection logic is implemented in `python/valuecell/config/manager.py`:
+
+1. OpenRouter
+2. SiliconFlow
+3. Google
+4. Other configured providers
+
+Override this with an environment variable:
+
+```bash
+export PRIMARY_PROVIDER=siliconflow
+```
 
-Some useful exmaples:
+Or disable auto-detection:
 
 ```bash
-# Siliconflow
-EMBEDDER_BASE_URL=https://api.siliconflow.cn/v1/
-EMBEDDER_MODEL_ID=Qwen/Qwen3-Embedding-4B
-EMBEDDER_DIMENSION=2560
+export AUTO_DETECT_PROVIDER=false
 ```
 
-### Data Sources
+### Fallback Mechanism
+
+If the primary provider fails, ValueCell automatically tries fallback providers.
+
+**Fallback chain** (auto-populated from enabled providers):
+- All providers with valid API keys, except the primary provider
+- Stops at first successful model creation
+
+To override fallback providers:
+
+```bash
+export FALLBACK_PROVIDERS=siliconflow,google
+```
+
+To disable fallback:
+
+```bash
+# In agent YAML
+use_fallback: false
+```
+
+### Provider-Specific Model Mapping
+
+When using fallback, agents can specify which model to use for each provider:
+
+```yaml
+# In agent configuration
+models:
+  primary:
+    model_id: "anthropic/claude-haiku-4.5"
+    provider: "openrouter"
+    
+    # If OpenRouter fails, use these models for fallback providers
+    provider_models:
+      siliconflow: "zai-org/GLM-4.6"      # Similar capability
+      google: "gemini-2.5-flash"          # Fast and efficient
+```
+
+When fallback occurs:
+1. Try OpenRouter with `anthropic/claude-haiku-4.5`
+2. If fails, try SiliconFlow with `zai-org/GLM-4.6`
+3. If fails, try Google with `gemini-2.5-flash`
+
+---
 
-**Required:**
+## Environment Variables Reference
 
-- `SEC_EMAIL` - Your email (SEC API requirement). **Required if you use the Research Agent.**
-- `FINNHUB_API_KEY` - Get free key from [finnhub.io/register](https://finnhub.io/register)
+### Global Configuration
 
-**Optional:**
+```bash
+# Primary provider selection
+PRIMARY_PROVIDER=openrouter
+
+# Auto-detect provider from API keys (default: true)
+AUTO_DETECT_PROVIDER=true
+
+# Comma-separated fallback provider chain
+FALLBACK_PROVIDERS=siliconflow,google
+
+# Application environment
+APP_ENVIRONMENT=production
+```
+
+### Provider Credentials
+
+```bash
+# OpenRouter
+OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxx
+
+# SiliconFlow
+SILICONFLOW_API_KEY=sk-xxxxxxxxxxxxx
+
+# Google
+GOOGLE_API_KEY=AIzaSyDxxxxxxxxxxxxx
+
+# Azure OpenAI (if using Azure provider)
+AZURE_OPENAI_API_KEY=xxxxxxxxxxxxx
+AZURE_OPENAI_ENDPOINT=https://xxxxx.openai.azure.com/
+OPENAI_API_VERSION=2024-10-21
+```
+
+### Model Configuration
+
+```bash
+# Global model overrides
+PLANNER_MODEL_ID=anthropic/claude-3.5-sonnet
+EMBEDDER_MODEL_ID=openai/text-embedding-3-large
+
+# Research Agent
+RESEARCH_AGENT_MODEL_ID=google/gemini-2.5-flash
+RESEARCH_AGENT_PROVIDER=openrouter
+RESEARCH_AGENT_TEMPERATURE=0.8
+RESEARCH_AGENT_MAX_TOKENS=8192
+EMBEDDER_DIMENSION=3072
+
+# Super Agent
+SUPER_AGENT_MODEL_ID=anthropic/claude-haiku-4.5
+SUPER_AGENT_PROVIDER=openrouter
+
+# Auto Trading Agent
+AUTO_TRADING_AGENT_MODEL_ID=model-id
+AUTO_TRADING_AGENT_PROVIDER=openrouter
+```
+
+### Debugging
+
+```bash
+# Enable debug logging
+AGENT_DEBUG_MODE=true
+```
+
+---
+
+## Configuration Patterns
+
+### Pattern 1: Multi-Model Setup with Fallback
+
+**Use case**: High availability with cost optimization
+
+```bash
+# .env file
+OPENROUTER_API_KEY=sk-or-v1-xxxxx        # Primary: access to many models
+SILICONFLOW_API_KEY=sk-xxxxx             # Fallback: cost-effective
+GOOGLE_API_KEY=AIzaSyD-xxxxx             # Second fallback: specialized
+
+# config.yaml
+models:
+  primary_provider: "openrouter"          # Primary (best models)
+  # Fallback auto-populated as [siliconflow, google]
+```
+
+### Pattern 2: Specialized Models per Agent
+
+**Use case**: Optimize each agent for its task
+
+```yaml
+# In research_agent.yaml
+models:
+  primary:
+    provider: "openrouter"
+    model_id: "anthropic/claude-3.5-sonnet"  # Best for research
+    
+  embedding:
+    provider: "siliconflow"
+    model_id: "Qwen/Qwen3-Embedding-4B"      # Best embeddings
+```
+
+### Pattern 3: Development vs Production
+
+```bash
+# .env.development
+OPENROUTER_API_KEY=sk-or-v1-dev-xxxxx
+APP_ENVIRONMENT=development
+
+# .env.production  
+OPENROUTER_API_KEY=sk-or-v1-prod-xxxxx
+SILICONFLOW_API_KEY=sk-prod-xxxxx
+APP_ENVIRONMENT=production
+```
+
+Then create `config.production.yaml` with production-specific settings.
+
+### Pattern 4: Runtime Overrides
+
+**Use case**: A/B testing different models without code changes
+
+```bash
+# Script to test different models
+for model in "gpt-4o" "claude-3.5-sonnet" "gemini-2.5-flash"; do
+    echo "Testing: $model"
+    RESEARCH_AGENT_MODEL_ID="$model" python your_script.py
+done
+```
+
+---
+
+## For Developers
+
+### Configuration System Architecture
+
+The configuration system has three layers:
+
+1. **Loader Layer** (`valuecell/config/loader.py`)
+   - Reads YAML files
+   - Resolves `${VAR}` placeholders
+   - Applies environment variable overrides
+   - Implements caching
+
+2. **Manager Layer** (`valuecell/config/manager.py`)
+   - High-level configuration access
+   - Provider validation
+   - Model factory integration
+   - Fallback chain management
+
+3. **Factory Layer** (`valuecell/adapters/models/factory.py`)
+   - Creates actual model instances
+   - Provider-specific implementations
+   - Parameter merging
+   - Error handling and fallback
+
+
+### Creating a Model
+
+```python
+from valuecell.utils.model import get_model, get_model_for_agent
+
+# Use default configuration
+model = get_model("PLANNER_MODEL_ID")
+
+# Override with kwargs
+model = get_model("RESEARCH_AGENT_MODEL_ID", temperature=0.9, max_tokens=16384)
+
+# Get agent-specific model
+model = get_model_for_agent("research_agent", temperature=0.8)
+
+# Use specific provider
+from valuecell.utils.model import create_model_with_provider
+model = create_model_with_provider("openrouter", "anthropic/claude-3.5-sonnet")
+```
 
-- `XUEQIU_TOKEN` - From [xueqiu.com](https://xueqiu.com/) if Yahoo Finance is unstable
+### Adding a New Provider
 
-## Troubleshooting
+1. **Create provider YAML** (`configs/providers/my_provider.yaml`)
+2. **Implement provider class** in `valuecell/adapters/models/factory.py`
+3. **Register provider** in `ModelFactory._providers`
+4. **Add to config.yaml** provider registry
+5. **Add tests** for provider configuration
 
-**API Connection:**
+---
 
-- Verify `API_HOST` and `API_PORT`
-- Check if port is in use
-- Review firewall settings
+## Best Practices
 
-**Model Providers:**
+1. **Set API Keys in .env**
+   - Never commit API keys to version control
+   - Use `.gitignore` to exclude `.env`
+   - Use environment variables in CI/CD
 
-- Verify API keys are valid
-- Check model IDs are correct
-- Ensure sufficient credits
+2. **Use Provider Fallback**
+   - Configure multiple providers for reliability
+   - Specify `provider_models` in agents for consistent fallback
+   - Test fallback behavior before deployment
 
-**Data Sources:**
+3. **Monitor Configuration**
+   - Log configuration selection decisions
+   - Validate configuration on startup
+   - Alert on missing API keys in production
 
-- Set valid `SEC_EMAIL`
-- Try `XUEQIU_TOKEN` if Yahoo Finance fails
+4. **Version Your Configuration**
+   - Keep agent configurations in version control
+   - Document why specific models are chosen
+   - Review configuration changes in code review
 
-## Security
+5. **Optimize Costs**
+   - Use cheaper models for simple tasks
+   - Use faster models for real-time applications
+   - Monitor API usage and set spending limits
 
-- Never commit `.env` to version control
-- Rotate API keys regularly
-- Set file permissions: `chmod 600 .env`
-- Use secrets management in production
+---
 
-## Resources
+## Support
 
-- [OpenRouter API](https://openrouter.ai/docs)
-- [SEC EDGAR API](https://www.sec.gov/edgar/sec-api-documentation)
-- [Finnhub API](https://finnhub.io/docs/api)
+For configuration issues or questions:
+- Ask on [Discord Community](https://discord.com/invite/84Kex3GGAh)
+- Report bugs on [GitHub Issues](https://github.com/valuecell/valuecell/issues)
diff --git a/python/configs/ENV_VARIABLES.md b/python/configs/ENV_VARIABLES.md
deleted file mode 100644
index 3ebe9bda2..000000000
--- a/python/configs/ENV_VARIABLES.md
+++ /dev/null
@@ -1,412 +0,0 @@
-# Environment Variables Guide
-
-## Configuration Priority
-
-ValueCell uses a three-tier configuration system:
-
-1. **Environment Variables** (Highest Priority) - Runtime overrides
-2. **.env File** (Middle Priority) - User configuration
-3. **YAML Files** (Lowest Priority) - System defaults
-
-## Quick Start
-
-### Minimal Setup (OpenRouter Only)
-
-```bash
-# In your .env file
-OPENROUTER_API_KEY=sk-or-v1-your-key-here
-PROJECT_ROOT=/Users/yourusername/Project/valuecell
-```
-
-That's it! All agents will work with OpenRouter's default models.
-
-## Core Configuration
-
-### Application Settings
-
-```bash
-APP_ENVIRONMENT=development          # development, staging, production
-PROJECT_ROOT=/path/to/valuecell      # Project root directory
-DEBUG=false                          # Enable debug mode
-LOG_LEVEL=INFO                       # DEBUG, INFO, WARNING, ERROR
-```
-
-### Model Provider API Keys
-
-Setting a provider's API key enables all models from that provider.
-
-```bash
-# OpenRouter (Recommended - unified API for multiple providers)
-OPENROUTER_API_KEY=sk-or-v1-...
-YOUR_SITE_URL=https://github.com/ValueCell-ai/valuecell
-YOUR_SITE_NAME=ValueCell
-
-# Google Gemini
-GOOGLE_API_KEY=AIzaSy...
-
-# Azure OpenAI
-AZURE_OPENAI_API_KEY=...
-AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
-AZURE_OPENAI_API_VERSION=2024-10-21
-
-# OpenAI Direct
-OPENAI_API_KEY=sk-...
-
-# Anthropic Claude
-ANTHROPIC_API_KEY=sk-ant-...
-
-# DeepSeek
-DEEPSEEK_API_KEY=sk-...
-```
-
-## Agent-Specific Overrides
-
-### Research Agent
-
-Override model and parameters for the Research Agent:
-
-```bash
-RESEARCH_AGENT_MODEL_ID=anthropic/claude-3.5-sonnet
-RESEARCH_AGENT_PROVIDER=openrouter
-RESEARCH_AGENT_TEMPERATURE=0.8
-RESEARCH_AGENT_MAX_TOKENS=8192
-RESEARCH_AGENT_EMBEDDING_MODEL=text-embedding-3-small
-RESEARCH_AGENT_LOG_LEVEL=DEBUG
-```
-
-### SEC Agent
-
-```bash
-SEC_AGENT_MODEL_ID=google/gemini-2.5-flash
-SEC_AGENT_PROVIDER=openrouter
-SEC_AGENT_PARSER_MODEL=openai/gpt-4o-mini
-```
-
-### Trading Agent
-
-```bash
-TRADING_AGENT_MODEL_ID=openai/gpt-4o
-TRADING_AGENT_PROVIDER=openrouter
-```
-
-### Auto Trading Agent
-
-```bash
-AUTO_TRADING_AGENT_PARSER_MODEL=openai/gpt-4o-mini
-```
-
-## Third-Party Integration Configuration
-
-### TradingAgents
-
-```bash
-# LLM Provider
-TRADINGAGENTS_LLM_PROVIDER=openai
-TRADINGAGENTS_DEEP_THINK_LLM=o4-mini
-TRADINGAGENTS_QUICK_THINK_LLM=gpt-4o-mini
-TRADINGAGENTS_BACKEND_URL=https://api.openai.com/v1
-
-# Embeddings (Required if using OpenRouter)
-EMBEDDER_BASE_URL=https://api.openai.com/v1
-EMBEDDER_MODEL_ID=text-embedding-3-small
-
-# Analysis Parameters
-TRADINGAGENTS_MAX_DEBATE_ROUNDS=1
-TRADINGAGENTS_MAX_RISK_DISCUSS_ROUNDS=1
-TRADINGAGENTS_ONLINE_TOOLS=true
-```
-
-### AI-Hedge-Fund
-
-```bash
-AI_HEDGE_FUND_PARSER_MODEL_ID=openai/gpt-4o-mini
-```
-
-## Advanced Configuration
-
-### Provider Selection
-
-ValueCell automatically detects which provider to use based on available API keys.
-
-```bash
-# Auto-detection (default behavior)
-# Just set any provider's API key and it will be auto-selected
-# Priority: azure > openrouter > anthropic > google > deepseek
-
-# Disable auto-detection if needed
-AUTO_DETECT_PROVIDER=false
-
-# Explicitly override primary provider
-PRIMARY_PROVIDER=openrouter
-
-# Override fallback chain
-FALLBACK_PROVIDERS=google,anthropic
-```
-
-### Global Model Parameters
-
-```bash
-MODEL_TEMPERATURE=0.7
-MODEL_MAX_TOKENS=4096
-MODEL_TOP_P=1.0
-MODEL_TIMEOUT=60
-```
-
-### Server Configuration
-
-```bash
-API_HOST=0.0.0.0
-API_PORT=8000
-API_DEBUG=false
-CORS_ORIGINS=http://localhost:1420,http://localhost:3000
-```
-
-## Agent API Keys (Data Sources)
-
-Additional API keys for data sources (not model providers):
-
-```bash
-# Financial Data
-SEC_EDGAR_API_KEY=...
-FINANCIAL_DATASETS_API_KEY=...
-ALPHA_VANTAGE_API_KEY=...
-POLYGON_API_KEY=...
-FINNHUB_API_KEY=...
-
-# News APIs
-NEWS_API_KEY=...
-```
-
-## Usage Examples
-
-### Example 1: Default Setup (OpenRouter)
-
-```bash
-# .env
-OPENROUTER_API_KEY=sk-or-v1-abc123
-PROJECT_ROOT=/Users/you/valuecell
-```
-
-All agents use OpenRouter with default models from `providers/openrouter.yaml`.
-
-### Example 2: Override Research Agent to Use Claude
-
-```bash
-# .env
-OPENROUTER_API_KEY=sk-or-v1-abc123
-RESEARCH_AGENT_MODEL_ID=anthropic/claude-3.5-sonnet
-```
-
-Research Agent now uses Claude, other agents still use their defaults.
-
-### Example 3: Use Google Direct (Not via OpenRouter)
-
-```bash
-# .env
-GOOGLE_API_KEY=AIzaSy...
-RESEARCH_AGENT_PROVIDER=google
-RESEARCH_AGENT_MODEL_ID=gemini-2.5-pro
-```
-
-Research Agent connects directly to Google (bypassing OpenRouter).
-
-### Example 4: Production with Azure (Auto-Detection)
-
-```bash
-# .env
-APP_ENVIRONMENT=production
-AZURE_OPENAI_API_KEY=...
-AZURE_OPENAI_ENDPOINT=https://prod.openai.azure.com
-```
-
-Azure will be **automatically selected** as the primary provider (highest priority in auto-detection).
-All agents use Azure OpenAI by default without explicitly setting PRIMARY_PROVIDER.
-
-### Example 4b: Production with Azure (Explicit)
-
-```bash
-# .env
-APP_ENVIRONMENT=production
-AZURE_OPENAI_API_KEY=...
-AZURE_OPENAI_ENDPOINT=https://prod.openai.azure.com
-PRIMARY_PROVIDER=azure  # Optional: Explicit override disables auto-detection
-```
-
-Same result, but explicitly sets Azure (useful if you have multiple providers configured).
-
-### Example 5: High Temperature for Creative Research
-
-```bash
-# .env
-OPENROUTER_API_KEY=sk-or-v1-abc123
-RESEARCH_AGENT_TEMPERATURE=0.95
-RESEARCH_AGENT_MAX_TOKENS=16384
-```
-
-Override just the parameters, keep default model.
-
-## Provider Auto-Detection
-
-### How It Works
-
-ValueCell intelligently selects the best provider based on your configured API keys:
-
-1. **Check for explicit override**: If `PRIMARY_PROVIDER` is set, use it
-2. **Auto-detect from API keys**: Check which providers have valid API keys
-3. **Select by priority**: Choose the first available provider in this order:
-   - **Azure** (enterprise-grade, recommended for production)
-   - **OpenRouter** (unified API, easiest for development)
-   - **Anthropic** (direct Claude access)
-   - **Google** (direct Gemini access)
-   - **DeepSeek** (cost-effective alternative)
-4. **Fallback to config**: Use `primary_provider` from config.yaml
-
-### Examples
-
-**Scenario 1: Only OpenRouter key configured**
-```bash
-OPENROUTER_API_KEY=sk-or-...
-```
-→ Auto-selects: `openrouter`
-
-**Scenario 2: Both Azure and OpenRouter configured**
-```bash
-AZURE_OPENAI_API_KEY=...
-AZURE_OPENAI_ENDPOINT=https://...
-OPENROUTER_API_KEY=sk-or-...
-```
-→ Auto-selects: `azure` (higher priority)
-
-**Scenario 3: Multiple providers, explicit override**
-```bash
-AZURE_OPENAI_API_KEY=...
-OPENROUTER_API_KEY=...
-PRIMARY_PROVIDER=openrouter  # Force OpenRouter despite Azure being available
-```
-→ Uses: `openrouter` (explicit override wins)
-
-**Scenario 4: Disable auto-detection**
-```bash
-AZURE_OPENAI_API_KEY=...
-AUTO_DETECT_PROVIDER=false
-```
-→ Uses: `openrouter` (from config.yaml default)
-
-### Benefits
-
-- **Zero configuration**: Just add your API key, it works automatically
-- **Smart defaults**: Enterprise providers (Azure) preferred over unified APIs
-- **Flexible override**: Can always explicitly set provider if needed
-- **Transparent**: Logs show which provider was selected and why
-
-## Configuration Details
-
-### 1. YAML Defines Capabilities
-
-In `providers/openrouter.yaml`:
-
-```yaml
-default_model: "google/gemini-2.5-flash"
-models:
-  - id: "google/gemini-2.5-flash"
-    context_window: 1048576
-    cost_per_1m_tokens: 0.075
-```
-
-### 2. Agent YAML Sets Preferences
-
-In `agents/research_agent.yaml`:
-
-```yaml
-models:
-  primary:
-    model_id: "google/gemini-2.5-flash"
-    provider: "openrouter"
-    parameters:
-      temperature: 0.7
-      max_tokens: 8192
-```
-
-### 3. .env Overrides Everything
-
-```bash
-# User sets this, overrides agent YAML
-RESEARCH_AGENT_MODEL_ID=anthropic/claude-3.5-sonnet
-```
-
-### 4. Code Reads Final Config
-
-```python
-from valuecell.config.loader import load_agent_config
-
-config = load_agent_config("research_agent")
-# Returns merged config with all overrides applied
-model_id = config["models"]["primary"]["model_id"]
-# Result: "anthropic/claude-3.5-sonnet" (from .env)
-```
-
-## Benefits
-
-1. **Users**: Just set API keys in `.env`, everything works
-2. **Developers**: Pre-configure optimal settings in agent YAML
-3. **DevOps**: Override anything at runtime via environment variables
-4. **System**: Maintain provider capabilities in YAML registry
-
-## Troubleshooting
-
-### Agent Not Working?
-
-Check configuration priority:
-
-```bash
-# 1. Check if API key is set
-echo $OPENROUTER_API_KEY
-
-# 2. Validate agent config
-python -m valuecell.config.validate research_agent
-
-# 3. Check logs
-tail -f logs/*/backend.log
-```
-
-### Which Model Is Being Used?
-
-```python
-from valuecell.config.loader import load_agent_config
-
-config = load_agent_config("research_agent")
-print(f"Model: {config['models']['primary']['model_id']}")
-print(f"Provider: {config['models']['primary']['provider']}")
-```
-
-## Best Practices
-
-1. **Development**: Use free models from OpenRouter
-   ```bash
-   OPENROUTER_API_KEY=...
-   RESEARCH_AGENT_MODEL_ID=google/gemini-2.0-flash-exp:free
-   ```
-
-2. **Production**: Use reliable paid models
-   ```bash
-   OPENROUTER_API_KEY=...
-   RESEARCH_AGENT_MODEL_ID=google/gemini-2.5-flash
-   ```
-
-3. **Testing**: Override in CI/CD
-   ```bash
-   export RESEARCH_AGENT_MODEL_ID=mock-model
-   export PRIMARY_PROVIDER=mock
-   ```
-
-4. **Cost Control**: Use cheaper models for parsing
-   ```bash
-   SEC_AGENT_PARSER_MODEL=openai/gpt-4o-mini
-   ```
-
-## See Also
-
-- [config.yaml](config.yaml) - Main configuration
-- [providers/openrouter.yaml](providers/openrouter.yaml) - OpenRouter capabilities
-- [agents/research_agent.yaml](agents/research_agent.yaml) - Agent configuration
-

From 9307fc43da8bc61df4b9c2690d98457da6d059e1 Mon Sep 17 00:00:00 2001
From: hazeone <709547807@qq.com>
Date: Thu, 30 Oct 2025 11:50:11 +0800
Subject: [PATCH 2/5] Modify readme file

---
 README.ja.md      | 51 +++++++++++++++++++++++------------
 README.md         | 51 +++++++++++++++++++++++------------
 README.zh.md      | 69 ++++++++++++++++++++++++++++++-----------------
 README.zh_Hant.md | 60 ++++++++++++++++++++++++++++-------------
 4 files changed, 154 insertions(+), 77 deletions(-)

diff --git a/README.ja.md b/README.ja.md
index cc03ba8bf..2e7135fd0 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -33,9 +33,13 @@
 
 
 # ValueCell
-ValueCellは、金融アプリケーション向けのコミュニティ主導型マルチエージェントプラットフォームです。
+ValueCellは、金融アプリケーション向けのコミュニティ主導型マルチエージェントプロダクトです。私たちの目標は、世界最大の分散型金融エージェントコミュニティを構築することです。
 
-ポートフォリオ管理を支援するトップクラスの投資エージェントチームを提供します。
+ポートフォリオ管理を支援するトップクラスの投資エージェントチームを提供します。これにより、銘柄選別、リサーチ、追跡、および取引の完了を支援します。
+
+Discord コミュニティへのご参加をお待ちしています。使用中に発生した問題についてのご意見をお寄せいただき、さらに多くの開発者にご参加いただけますようお願いします🔥🔥🔥
+
+>注意: ValueCellチームメンバーがコミュニティ参加者に主動的に連絡することはありません。このプロジェクトは技術交流のみを目的としています。投資にはリスクが伴います。⚠️
 
 # スクリーンショット
 
@@ -63,16 +67,16 @@ ValueCellは、金融アプリケーション向けのコミュニティ主導
 
 
 ## マルチエージェントシステム
-- **DeepResearch Agent**: SECファイリングを自動的に取得・分析し、正確なデータインサイトと解釈可能なサマリーを生成
-- **Auto Trading Agent**: 複数の暗号資産とAI駆動の取引戦略
+- **DeepResearch Agent**: 株式の基本情報ドキュメントを自動的に取得・分析し、正確なデータインサイトと解釈可能なサマリーを生成
+- **Auto Trading Agent**: 複数の暗号資産とAI駆動の取引戦略をサポート、技術指標に基づいた自動取引を作成
 - **Trading Agents**: 市場分析、センチメント分析、ニュース分析、ファンダメンタル分析を担当するエージェント
 - **AI-Hedge-Fund**: エージェントが協力して包括的な金融インサイトを提供
 - **その他**: さらに多くのエージェントを計画中...
 
 ## 柔軟な統合
-- **複数のLLMプロバイダー**: OpenRouter、OpenAI、Anthropic、Google、Ollamaをサポート
+- **複数のLLMプロバイダー**: OpenRouter、SiliconFlow、GoogleおよびOpenAIをサポート
 - **人気の市場データ**: 米国市場、暗号市場、香港市場、中国市場など
-- **マルチエージェントフレームワーク対応**: A2AプロトコルによるLangchain、Agnoをサポート
+- **マルチエージェントフレームワーク対応**: A2AプロトコルによるLangchain、Agnoをサポート、研究開発の統合を行う
 
 # クイックスタート
 
@@ -104,18 +108,21 @@ ValueCellは包括的なWebインターフェースを備えたPythonベース
 
 ## 設定
 
+詳細な設定情報については、[CONFIGURATION_GUIDE](./docs/CONFIGURATION_GUIDE.md)を参照してください。
+
 ### モデルプロバイダー
 `.env`ファイルを編集して、お好みのモデルプロバイダーを設定してください:
 
-- **主なサポート**: [OpenRouter](https://openrouter.ai) - 現在、ほとんどのエージェントで主にサポートされているプロバイダー
-- **TradingAgents**はメモリの使用が必要です。OpenRouterをAPIキーとして使用する場合、Embeddingモデルのパラメータ設定が必要になります(OpenRouterはEmbeddingモデルをサポートしていないため)。TradingAgents/.env.exampleファイルを参照し、その設定をルートディレクトリの.envファイルにコピーしてください。
+- **シンプルセットアップ**: モデルプロバイダーの API キーのみを設定してください
 
+- **高度な設定**: リサーチタイプのエージェントの場合、より多くの環境変数を設定する必要があります。詳細は `.env.example` ファイルを参照してください
+
+- **公式推奨**: OpenRouter + 埋め込みモデルを提供する任意のサプライヤーを設定してください。理由：プロバイダー間のモデルの高速切り替えが可能であり、RAG+Memory AI機能を提供します。
 
-要件と好みに基づいて、お好みのモデルとプロバイダーを選択してください。
 
 ## アプリケーションの実行
 
-完全なアプリケーションスタック(フロントエンド、バックエンド、エージェント)を起動します:
+完全なアプリケーション(フロントエンド、バックエンド、エージェント)を起動します:
 
 ### Linux / Macos
 ```bash
@@ -139,14 +146,25 @@ bash start.sh
 ---
 
 **注意**: アプリケーションを実行する前に、すべての前提条件がインストールされ、環境変数が適切に設定されていることを確認してください。
+長期間更新がない場合は、プロジェクト内のデータベースファイル(`lancedb/`、`valuecell.db`、`.knowledgebase/`)を削除してから再起動できます。
+
 
+# 開発者
+
+すべての開発者をDiscordディスカッショングループに招待し、コミュニティのRoadMapと将来のコミュニティコントリビューター権利計画について定期的に交流します
+
+開発プロセスと標準の詳細については、[CONTRIBUTING.md](.github/CONTRIBUTING.md)を参照してください
 
 # ロードマップ
 
 ## 🤖 強化されたエージェント機能
+### 取引能力
+- **暗号通貨**: より多くの取引所をサポート
+- **証券**: AI証券取引を段階的にサポート
+
 ### 市場拡大
 - **ヨーロッパ市場**: FTSE、DAX、CAC 40などのヨーロッパ取引所のサポートを追加
-- **アジア市場**: 日経、ハンセン、上海総合指数、新興アジア市場へのカバレッジ拡大
+- **アジア市場**: 日経、新興アジア市場へのカバレッジ拡大
 - **商品市場**: 石油、金、銀、農産物の分析
 - **外国為替市場**: 主要通貨ペアとクロスカレンシー分析
 
@@ -160,9 +178,13 @@ bash start.sh
 - **スケジュールレポート**: 日次/週次/月次ポートフォリオサマリー
 - **イベント駆動型通知**: 決算発表、配当発表、規制変更
 - **カスタムトリガー**: ユーザー定義の条件としきい値
-- **マルチチャネル配信**: メール、SMS、Slack、Discord、Webhook統合
+- **マルチチャネル配信**: Discord と Webhook 統合
 
 ## ⚙️ 製品設定とパーソナライゼーション
+### マルチプラットフォーム製品
+- **デスクトップサポート**: デスクトップとクライアント機能を段階的にサポート
+- **データベースホットアップデート**: 互換性アップグレードの段階的サポート
+
 ### 国際化(i18n)
 - **多言語サポート**: 英語、中国語(簡体字/繁体字)、日本語、韓国語、スペイン語、フランス語
 - **ローカライズされた市場データ**: 地域固有の金融用語とフォーマット
@@ -172,8 +194,6 @@ bash start.sh
 ### トークンと認証管理
 - **APIキー管理**: サードパーティAPIキーの安全な保存とローテーション
 - **OAuth統合**: 主要な金融データプロバイダーのサポート
-- **レート制限**: インテリジェントなリクエストスロットリングとクォータ管理
-- **マルチテナントアーキテクチャ**: エンタープライズグレードのユーザー分離とセキュリティ
 
 ### ユーザー設定とカスタマイズ
 - **投資プロファイル**: リスク許容度、投資期間、戦略の好み
@@ -190,14 +210,11 @@ bash start.sh
 ## 🔧 ValueCell SDK開発
 ### コアSDK機能
 - **Python SDK**: エージェント統合とカスタマイズのための包括的なライブラリ
-- **REST APIラッパー**: 自動認証付きの簡易HTTPクライアント
 - **WebSocketサポート**: リアルタイムデータストリーミングと双方向通信
 
 ### エージェント統合フレームワーク
 - **プラグインアーキテクチャ**: サードパーティエージェントとツールの簡単な統合
 - **エージェントレジストリ**: コミュニティ貢献エージェントのマーケットプレイス
-- **カスタムエージェントビルダー**: ローコード/ノーコードエージェント作成ツール
-- **エージェントオーケストレーション**: ワークフロー管理とエージェント調整
 
 ### 開発者ツールとドキュメント
 - **インタラクティブAPIエクスプローラー**: ライブテスト機能付きSwagger/OpenAPIドキュメント
diff --git a/README.md b/README.md
index dfb670c72..24d442fe8 100644
--- a/README.md
+++ b/README.md
@@ -33,9 +33,13 @@
 
 
 # ValueCell
-ValueCell is a community-driven, multi-agent platform for financial applications.
+ValueCell is a community-driven, multi-agent platform for financial applications. Our mission is to build the world's largest decentralized financial agent community.
 
-It provides a team of TOP investment Agents to help manage your portfolio.
+It provides a team of TOP investment Agents to help you with stock selection, research, tracking, and even trading.
+
+Welcome to join our Discord community to share feedback and issues you encounter, and invite more developers to contribute 🔥🔥🔥
+
+>Note: ValueCell team members will never proactively contact community participants. This project is for technical exchange only. Investing involves risk. ⚠️
 
 # Screenshot
 
@@ -63,16 +67,16 @@ It provides a team of TOP investment Agents to help manage your portfolio.
 
 
 ## Multi-Agent System
-- **DeepResearch Agent**: Automatically retrieve and analyze SEC filings to generate accurate data insights and interpretable summaries
-- **Auto Trading Agent**: multiple crypto assets and AI-powered trading strategies
+- **DeepResearch Agent**: Automatically retrieve and analyze fundamental documents to generate accurate data insights and interpretable summaries
+- **Auto Trading Agent**: Support for multiple crypto assets and AI-powered trading strategies, creating automated trading based on technical indicators
 - **Trading Agents**: Agents work for market analysis, sentiment analysis, news analysis, and fundamentals analysis 
 - **AI-Hedge-Fund**: Agents collaborate to provide comprehensive financial insights
 - **Others**: More agents are in planning...
 
 ## Flexible Integrations
-- **Multiple LLM Providers**: Support OpenRouter, OpenAI, Anthropic, Google and Ollama 
+- **Multiple LLM Providers**: Support OpenRouter, SiliconFlow, Google and OpenAI 
 - **Popular Market Data**: Cover US market, Crypto market, Hong Kong market, China market and more
-- **Multi-Agent Framework Compatible**: Support Langchain, Agno by A2A Protocol
+- **Multi-Agent Framework Compatible**: Support Langchain, Agno by A2A Protocol for research and development integration
 
 # Quick Start
 
@@ -104,18 +108,23 @@ For optimal performance and streamlined development, we recommend installing the
 
 ## Configuration
 
+More detailed configuration information can be found at [CONFIGURATION_GUIDE](./docs/CONFIGURATION_GUIDE.md)
+
 ### Model Providers
-Configure your preferred model providers by editing the ⁠`.env` file:
+Configure your preferred model providers by editing the `.env` file:
+
+- **Simple Setup**: Just configure the model provider's API Key
+
+- **Advanced Configuration**: For research-type agents, you need to configure more environment variables. Please refer to the `.env.example` file for details.
 
-- **Primary Support**: [OpenRouter](https://openrouter.ai) - Currently the main supported provider for most agents
-- **TradingAgents** requires the use of Memory. If you use OpenRouter as API key, configuring the Embedding model parameters will be needed (since OpenRouter does not support Embedding models). Please refer to the TradingAgents/.env.example file and copy its configuration into the .env file located in the root directory.
+- **Official Recommendation**: Configure OpenRouter + any supplier that provides embedding models. Reason: This enables quick model switching across providers and provides RAG+Memory AI capabilities
   
 
 Choose your preferred models and providers based on your requirements and preferences.
 
 ## Running the Application
 
-Launch the complete application stack (frontend, backend, and agents):
+Launch the complete application (frontend, backend, and agents):
 
 ### Linux / Macos
 ```bash
@@ -132,6 +141,11 @@ bash start.sh
 - **Web UI**: Navigate to [http://localhost:1420](http://localhost:1420) in your browser
 - **Logs**: Monitor application logs at `logs/{timestamp}/*.log` for detailed runtime information of backend services and individual agents
 
+## Note
+
+Before running the application, ensure all prerequisites are installed and environment variables are properly configured.
+If it has been a long time since the last update, you can delete the database files in the project (`lancedb/`, `valuecell.db`, `.knowledgebase/`) and start again.
+
 ## Next Steps
 
 Once the application is running, you can explore the web interface to interact with ValueCell's features and capabilities.
@@ -144,9 +158,13 @@ Once the application is running, you can explore the web interface to interact w
 # Roadmap
 
 ## 🤖 Enhanced Agent Capabilities
+### Trading Capabilities
+- **Crypto**: Support more exchanges
+- **Securities**: Gradually support AI securities trading
+
 ### Market Expansion
 - **European Markets**: Add support for FTSE, DAX, CAC 40, and other European exchanges
-- **Asian Markets**: Expand coverage to Nikkei, Hang Seng, Shanghai Composite, and emerging Asian markets
+- **Asian Markets**: Expand coverage to Nikkei and emerging Asian markets
 - **Commodity Markets**: Oil, Gold, Silver, Agricultural products analysis
 - **Forex Markets**: Major currency pairs and cross-currency analysis
 
@@ -160,9 +178,13 @@ Once the application is running, you can explore the web interface to interact w
 - **Scheduled Reports**: Daily/weekly/monthly portfolio summaries
 - **Event-driven Notifications**: Earnings releases, dividend announcements, regulatory changes
 - **Custom Triggers**: User-defined conditions and thresholds
-- **Multi-channel Delivery**: Email, SMS, Slack, Discord, and webhook integrations
+- **Multi-channel Delivery**: Discord and webhook integrations
 
 ## ⚙️ Product Configuration & Personalization
+### Multi-platform Products
+- **Desktop Support**: Gradually support desktop and client capabilities
+- **Database Hot Updates**: Gradually support compatibility upgrades
+
 ### Internationalization (i18n)
 - **Multi-language Support**: English, Chinese (Simplified/Traditional), Japanese, Korean, Spanish, French
 - **Localized Market Data**: Region-specific financial terminology and formats
@@ -172,8 +194,6 @@ Once the application is running, you can explore the web interface to interact w
 ### Token & Authentication Management
 - **API Key Management**: Secure storage and rotation of third-party API keys
 - **OAuth Integration**: Support for major financial data providers
-- **Rate Limiting**: Intelligent request throttling and quota management
-- **Multi-tenant Architecture**: Enterprise-grade user isolation and security
 
 ### User Preferences & Customization
 - **Investment Profile**: Risk tolerance, investment horizon, and strategy preferences
@@ -190,14 +210,11 @@ Once the application is running, you can explore the web interface to interact w
 ## 🔧 ValueCell SDK Development
 ### Core SDK Features
 - **Python SDK**: Comprehensive library for agent integration and customization
-- **REST API Wrapper**: Simplified HTTP client with automatic authentication
 - **WebSocket Support**: Real-time data streaming and bidirectional communication
 
 ### Agent Integration Framework
 - **Plugin Architecture**: Easy integration of third-party agents and tools
 - **Agent Registry**: Marketplace for community-contributed agents
-- **Custom Agent Builder**: Low-code/no-code agent creation tools
-- **Agent Orchestration**: Workflow management and agent coordination
 
 ### Developer Tools & Documentation
 - **Interactive API Explorer**: Swagger/OpenAPI documentation with live testing
diff --git a/README.zh.md b/README.zh.md
index 00859b356..ccbc74e74 100644
--- a/README.zh.md
+++ b/README.zh.md
@@ -26,16 +26,20 @@
 
 <div align="center">
   <a href="README.md" style="color: gray;">English</a>
-  <a href="README.zh.md" style="color: gray;">中文（简体）</a>
-  <a href="README.zh_Hant.md" style="color: auto;">中文（繁體）</a>
+  <a href="README.zh.md" style="color: auto;">中文（简体）</a>
+  <a href="README.zh_Hant.md" style="color: gray;">中文（繁體）</a>
   <a href="README.ja.md" style="color: gray;">日本語</a>
 </div>
 
 
 # ValueCell
-ValueCell 是一个社区驱动的多智能体金融应用平台。
+ValueCell 是一个社区驱动的多智能体金融应用产品，我们的计划是打造全球最大的去中心化金融智能体社区
 
-它将为您提供顶级的投资智能体团队，帮助您管理投资组合。
+它将为您提供顶级的投资智能体团队，帮助您完成选股，调研，跟踪和交易
+
+欢迎大家加入Discord社区反馈使用中遇到的问题，以及更多开发者参与共建🔥🔥🔥
+
+>注意：ValueCell团队人员不会主动私信社区参与者，项目仅为技术交流使用，投资有风险。⚠️
 
 # 产品截图
 
@@ -64,16 +68,16 @@ ValueCell 是一个社区驱动的多智能体金融应用平台。
 
 
 ## 多智能体系统
-- **DeepResearch Agent**: 获取并分析股票的SEC文件，输出准确的数据、可解释性的总结
-- **Auto Trading Agent**: 支持多种加密资产和AI自动交易策略
+- **DeepResearch Agent**: 获取并分析股票的基本面文件，输出准确的数据、可解释性的总结
+- **Auto Trading Agent**: 支持多种加密资产和AI自动交易策略，依据技术指标创建自动化交易
 - **Trading Agents**：专门负责市场分析、情绪分析、新闻分析和基本面分析的智能体协同工作
 - **AI-Hedge-Fund**：智能体协作提供全面的金融洞察
 - **其他智能体**：更多智能体正在规划中...
 
 ## 灵活集成
-- **多种大语言模型提供商**：支持 OpenRouter、OpenAI、Anthropic、Google 和 Ollama
+- **多种大语言模型提供商**：支持 OpenRouter、SiliconFlow、Google 和 OpenAI
 - **热门市场数据**：覆盖美国市场、加密货币市场、香港市场、中国市场等
-- **多智能体框架兼容**：通过 A2A 协议，支持 Langchain、Agno 等主流Agent框架
+- **多智能体框架兼容**：通过 A2A 协议，支持 Langchain、Agno 等主流Agent框架，进行研发集成
 
 # 快速开始
 
@@ -101,47 +105,63 @@ ValueCell 是一个基于Python的应用程序，且有完备的前端操作页
    cp .env.example .env
    ```
    
-   使用您的API密钥和偏好设置编辑`.env`文件。此配置文件在所有智能体之间共享。详见 [配置指南](docs/CONFIGURATION_GUIDE.md)。
+   使用您的API密钥和偏好设置编辑`.env`文件。此配置文件在所有智能体之间共享。详见 [配置指南](docs/CONFIGURATION_GUIDE.md)
 
 ## 配置
 
+更多系统配置详情说明可以参考[CONFIGURATION_GUIDE](./docs/CONFIGURATION_GUIDE.md)
+
 ### 模型提供商
 通过编辑`.env`文件配置您首选的模型提供商：
 
-- **主要支持**：[OpenRouter](https://openrouter.ai) - 目前大多数智能体的主要支持提供商
-- **TradingAgents** 集成了Memory功能。如果您使用OpenRouter作为API密钥，需要配置嵌入模型参数（因为OpenRouter不支持嵌入模型）。请参考TradingAgents/.env.example文件，并将其配置复制到根目录的.env文件中。
-  
+- **简易配置**：仅需配置模型厂商API Key即可
+
+- **其他配置**：对于调研类型的Agent来说，需要配置更多环境变量，可以仔细阅读`.env.example`中的说明
 
-根据您的需求和使用模式选择首选的模型和提供商。
+- **官方推荐**：配置OpenRouter + 任意提供嵌入模型的供应商。原因：可以快速实现多厂商模型切换，以及RAG+Memory的AI能力
+  
 
 ## 运行应用程序
 
-启动完整的应用程序堆栈（前端、后端和智能体）：
+启动完整的应用程序（前端、后端和智能体）：
 
+### Linux / Macos
 ```bash
 bash start.sh
 ```
 
+### Windows (PowerShell)
+```powershell
+.\start.ps1
+```
+
 ## 访问界面
 
 - **Web UI**：在浏览器中导航到 [http://localhost:1420](http://localhost:1420)
 - **日志**：在 `logs/{timestamp}/*.log` 监控应用程序日志，获取后端服务和各个智能体的详细运行时信息
 
-## 最后
+## 注意
+
+运行应用程序前，请确保所有前提条件已安装且环境变量已正确配置
+如长时间没有更新可以删除项目中数据库文件`lancedb/`,`valuecell.db`, `.knowledgebase/`再进行启动
 
-应用程序运行后，您可以通过Web界面使用ValueCell中集成的Agents。
 
----
+# 开发者
 
-**注意**：运行应用程序前，请确保所有前提条件已安装且环境变量已正确配置。
+诚挚邀请每位开发者加入Discord讨论组，我们会定期交流社区RoadMap以及未来社区贡献者权益规划
 
+开发流程及标准详见:[CONTRIBUTING.md](.github/CONTRIBUTING.md)
 
 # Roadmap
 
 ## 🤖 增强智能体能力
+### 交易能力
+- **加密货币**：支持更多交易所
+- **证券**：逐步支持AI证券交易
+
 ### 市场扩展
 - **欧洲市场**：增加对富时指数、DAX、CAC 40和其他欧洲交易所的支持
-- **亚洲市场**：扩展对日经指数、恒生指数、上证综指和新兴亚洲市场的覆盖
+- **亚洲市场**：扩展对日经指数和新兴亚洲市场的覆盖
 - **大宗商品市场**：石油、黄金、白银、农产品分析
 - **外汇市场**：主要货币对和交叉货币分析
 
@@ -155,9 +175,13 @@ bash start.sh
 - **定期报告**：每日/每周/每月投资组合摘要
 - **事件驱动通知**：财报发布、股息公告、监管变化
 - **自定义触发器**：用户定义的条件和阈值
-- **多渠道推送**：邮件、短信、Slack、Discord和webhook集成
+- **多渠道推送**：Discord和webhook集成
 
 ## ⚙️ 产品配置与个性化
+### 多端产品化
+-- **客户端支持**：逐步支持桌面端、客户端能力
+-- **数据库热更新**：逐步支持兼容性升级
+
 ### 国际化 (i18n)
 - **多语言支持**：英语、中文（简体/繁体）、日语、韩语、西班牙语、法语
 - **本地化市场数据**：特定地区的金融术语和格式
@@ -167,8 +191,6 @@ bash start.sh
 ### 令牌和身份验证管理
 - **API密钥管理**：第三方API密钥的安全存储和轮换
 - **OAuth集成**：支持主要金融数据提供商
-- **速率限制**：智能请求节流和配额管理
-- **多租户架构**：企业级用户隔离和安全
 
 ### 用户偏好和自定义
 - **投资档案**：风险承受能力、投资期限和策略偏好
@@ -185,14 +207,11 @@ bash start.sh
 ## 🔧 ValueCell SDK开发
 ### 核心SDK功能
 - **Python SDK**：用于智能体集成和自定义的核心代码，衔接前后端
-- **REST API包装器**：具有自动身份验证的简化HTTP客户端
 - **WebSocket支持**：实时数据流和双向通信
 
 ### 智能体集成框架
 - **插件架构**：轻松集成第三方智能体和工具
 - **智能体注册表**：社区贡献智能体的市场
-- **自定义智能体构建器**：低代码/无代码智能体创建工具
-- **智能体编排**：工作流管理和智能体协调
 
 ### 开发者工具和文档
 - **交互式API浏览器**：带有实时测试的Swagger/OpenAPI文档
diff --git a/README.zh_Hant.md b/README.zh_Hant.md
index 7d6bf9501..10932929e 100644
--- a/README.zh_Hant.md
+++ b/README.zh_Hant.md
@@ -33,9 +33,13 @@
 
 
 # ValueCell
-ValueCell 是一個社群驅動的多智能體金融應用平台。
+ValueCell 是一個社群驅動的多智能體金融應用產品，我們的計劃是打造全球最大的去中心化金融智能體社群。
 
-它會為您提供頂尖的投資智能體團隊，協助您管理投資組合。
+它會為您提供頂尖的投資智能體團隊，協助您完成選股、調研、追蹤和交易。
+
+歡迎大家加入Discord社群反饋使用中遇到的問題，以及更多開發者參與共建🔥🔥🔥
+
+>注意：ValueCell團隊人員不會主動私信社群參與者，項目僅為技術交流使用，投資有風險。⚠️
 
 # 產品截圖
 
@@ -63,16 +67,16 @@ ValueCell 是一個社群驅動的多智能體金融應用平台。
 
 
 ## 多智能體系統
-- **DeepResearch Agent**：獲取並分析股票的 SEC 文件,輸出準確的數據與可解釋的總結
-- **Auto Trading Agent**：支援多種加密資產與 AI 自動交易策略
+- **DeepResearch Agent**：獲取並分析股票的基本面文件，輸出準確的數據與可解釋的總結
+- **Auto Trading Agent**：支援多種加密資產與 AI 自動交易策略，依據技術指標建立自動化交易
 - **Trading Agents**: 專責市場分析、情緒分析、新聞分析與基本面分析的智能體協同運作
 - **AI-Hedge-Fund**：智能體協作提供全面的金融洞見
-- **其他智能體**：更多智能體正在規劃中…
+- **其他智能體**：更多智能體正在規劃中...
 
 ## 彈性整合
-- **多家大型語言模型供應商**：支援 OpenRouter、OpenAI、Anthropic、Google 與 Ollama
+- **多家大型語言模型供應商**：支援 OpenRouter、SiliconFlow、Google 與 OpenAI
 - **熱門市場資料**：涵蓋美國市場、加密貨幣、香港市場、中國市場等
-- **多智能體框架相容**：透過 A2A 協議，支援 LangChain、Agno 等主流 Agent 框架
+- **多智能體框架相容**：透過 A2A 協議，支援 LangChain、Agno 等主流 Agent 框架，進行研發整合
 
 # 快速開始
 
@@ -104,22 +108,32 @@ ValueCell 是以 Python 為基礎的應用，並具備完整的前端操作介
 
 ## 設定
 
+更多系統設定詳情說明可以參考[CONFIGURATION_GUIDE](./docs/CONFIGURATION_GUIDE.md)
+
 ### 模型供應商
 透過編輯 `.env` 檔案來設定您偏好的模型供應商：
 
-- **主要支援**：[OpenRouter](https://openrouter.ai) - 目前為大多數智能體的主要支援供應商
-- **TradingAgents** 已整合記憶（Memory）功能。若使用 OpenRouter 作為 API 提供者，需配置嵌入模型參數（因 OpenRouter 本身不支援嵌入模型）。請參考 TradingAgents/.env.example 檔案，並將其設定複製到專案根目錄的 .env 檔案中。
+- **簡易配置**：僅需配置模型廠商 API Key 即可
+
+- **其他配置**：對於調研類型的 Agent 來說，需要配置更多環境變數，可以仔細閱讀 `.env.example` 中的說明
+
+- **官方推薦**：配置 OpenRouter + 任意提供嵌入模型的供應商。原因：可以快速實現多廠商模型切換，以及 RAG+Memory 的 AI 能力
   
-依據您的需求與使用模式選擇適合的模型與供應商。
 
 ## 啟動應用程式
 
-啟動完整應用堆疊（前端、後端與智能體）：
+啟動完整應用程式（前端、後端與智能體）：
 
+### Linux / Macos
 ```bash
 bash start.sh
 ```
 
+### Windows (PowerShell)
+```powershell
+.\start.ps1
+```
+
 ## 存取介面
 
 - **Web UI**：於瀏覽器開啟 [http://localhost:1420](http://localhost:1420)
@@ -132,14 +146,25 @@ bash start.sh
 ---
 
 **注意**：啟動應用程式前，請確認所有前置條件已安裝且環境變數正確設定。
+若長時間未有更新，可以刪除專案中的資料庫檔案 `lancedb/`、`valuecell.db`、`.knowledgebase/` 後重新啟動。
+
+
+# 開發者
 
+誠摯邀請每位開發者加入 Discord 討論組，我們會定期交流社群 RoadMap 以及未來社群貢獻者權益規劃
+
+開發流程及標準詳見:[CONTRIBUTING.md](.github/CONTRIBUTING.md)
 
 # 路線圖
 
 ## 🤖 強化智能體能力
+### 交易能力
+- **加密貨幣**：支援更多交易所
+- **證券**：逐步支援 AI 證券交易
+
 ### 市場擴展
 - **歐洲市場**：新增對富時指數、DAX、CAC 40 與其他歐洲交易所的支援
-- **亞洲市場**：擴展對日經指數、恆生指數、上證綜指與新興亞洲市場的覆蓋
+- **亞洲市場**：擴展對日經指數與新興亞洲市場的覆蓋
 - **大宗商品市場**：石油、黃金、白銀與農產品分析
 - **外匯市場**：主要貨幣對與交叉貨幣分析
 
@@ -153,9 +178,13 @@ bash start.sh
 - **定期報告**：每日／每週／每月投組摘要
 - **事件驅動通知**：財報發布、股息公告、監管變動
 - **自訂觸發器**：使用者自定義條件與閾值
-- **多通道推送**：Email、簡訊、Slack、Discord 與 webhook 整合
+- **多通道推送**：Discord 與 webhook 整合
 
 ## ⚙️ 產品設定與個人化
+### 多端產品化
+- **客戶端支援**：逐步支援桌面端、客戶端能力
+- **資料庫熱更新**：逐步支援相容性升級
+
 ### 國際化 (i18n)
 - **多語系支援**：英文、中文（簡體／繁體）、日文、韓文、西班牙文、法文
 - **在地化市場資料**：特定地區的金融術語與格式
@@ -165,8 +194,6 @@ bash start.sh
 ### 令牌與認證管理
 - **API 金鑰管理**：第三方 API 金鑰的安全儲存與輪換
 - **OAuth 整合**：支援主要金融資料供應商
-- **速率限制**：智慧請求節流與配額管理
-- **多租戶架構**：企業級使用者隔離與安全
 
 ### 使用者偏好與自訂
 - **投資檔案**：風險承受度、投資期間與策略偏好
@@ -183,14 +210,11 @@ bash start.sh
 ## 🔧 ValueCell SDK 開發
 ### 核心 SDK 功能
 - **Python SDK**：用於智能體整合與客製的核心程式，連接前後端
-- **REST API 包裝器**：具自動認證的簡化 HTTP 用戶端
 - **WebSocket 支援**：即時資料串流與雙向通訊
 
 ### 智能體整合框架
 - **外掛架構**：輕鬆整合第三方智能體與工具
 - **智能體註冊表**：社群貢獻智能體的市集
-- **自訂智能體建構器**：低代碼／無代碼的智能體建立工具
-- **智能體編排**：工作流程管理與智能體協調
 
 ### 開發者工具與文件
 - **互動式 API 瀏覽器**：含即時測試的 Swagger/OpenAPI 文件

From bc6c88d934da0003ade23c7433d3e2d4c2580d6c Mon Sep 17 00:00:00 2001
From: hazeone <709547807@qq.com>
Date: Thu, 30 Oct 2025 12:07:32 +0800
Subject: [PATCH 3/5] update contributing.md file

---
 .github/CONTRIBUTING.md | 15 ++++++++++++++-
 1 file changed, 14 insertions(+), 1 deletion(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 4359f7f0c..ce529d655 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -39,6 +39,12 @@ Feature requests are welcome! Please:
 
 We welcome code contributions! See the [Development Setup](#development-setup) section below to get started.
 
+***Reference Doc***
+
+> Multi-agent system architecture: [CORE_ARCHITECTURE](../docs/CORE_ARCHITECTURE.md)  
+> Configuration documentation: [CONFIGURATION_GUIDE](../docs/CONFIGURATION_GUIDE.md)
+
+
 ## Development Setup
 
 ### Prerequisites
@@ -68,6 +74,8 @@ Refer to [Configuration Guide](../docs/CONFIGURATION_GUIDE.md) for details.
 **Install backend dependencies:**
 
 ```bash
+# Install pytest dependencies for testing
+
 # Method 1: Using sync (recommended)
 cd python
 uv sync --extra dev
@@ -360,6 +368,9 @@ docs: update installation instructions
 ## Pull Request Process
 
 1. **Create a feature branch**
+   
+   Fork the project and use the `git clone` command to download it
+
 
    ```bash
    git checkout -b feat/your-feature-name
@@ -424,4 +435,6 @@ If you have questions:
 
 ---
 
-Thank you for contributing to ValueCell! 🚀
+Thank you for contributing to ValueCell! 🚀🚀🚀
+
+We will be launching a reward program for active contributors soon!🔥🔥🔥

From 0b545087d213426715a2739d150a363b8709487c Mon Sep 17 00:00:00 2001
From: hazeone <709547807@qq.com>
Date: Thu, 30 Oct 2025 13:17:07 +0800
Subject: [PATCH 4/5] add dev program

---
 .github/CONTRIBUTING.md | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index ce529d655..3c8ec9cae 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -425,6 +425,17 @@ docs: update installation instructions
 - Address any requested changes
 - Once approved, your PR will be merged
 
+## 🔥 ValueCell Dev Program
+
+Build with us & get rewarded. Land 3 commits in the last month, and we will contact you via our official email (public@valuecell.ai).
+
+You will get:
+
+**💰 $100 Cash for API Keys and AI Coding Subscription**
+
+**🚀 Become a core contributor and participate in the project's future profits**
+
+
 ## Questions?
 
 If you have questions:
@@ -437,4 +448,3 @@ If you have questions:
 
 Thank you for contributing to ValueCell! 🚀🚀🚀
 
-We will be launching a reward program for active contributors soon!🔥🔥🔥

From c422208e2811c9448ae3b5e3f59ca330ea3048ec Mon Sep 17 00:00:00 2001
From: hazeone <709547807@qq.com>
Date: Thu, 30 Oct 2025 13:20:49 +0800
Subject: [PATCH 5/5] remove additional config in configuration doc

---
 docs/CONFIGURATION_GUIDE.md | 21 ---------------------
 1 file changed, 21 deletions(-)

diff --git a/docs/CONFIGURATION_GUIDE.md b/docs/CONFIGURATION_GUIDE.md
index d0851b64f..928790787 100644
--- a/docs/CONFIGURATION_GUIDE.md
+++ b/docs/CONFIGURATION_GUIDE.md
@@ -305,27 +305,6 @@ env_overrides:
   AGENT_EMBEDDER_MODEL: "models.embedding.model_id"
   AGENT_EMBEDDER_PROVIDER: "models.embedding.provider"
 
-# API keys required by this agent
-api_keys:
-  news_api:
-    key_env: "NEWS_API_KEY"
-    required: false
-    description: "Optional: For enhanced news searching"
-
-# Agent capabilities
-capabilities:
-  web_search: true
-  web_crawl: true
-  session_management:
-    enabled: true
-    max_history_runs: 5
-  
-# Advanced settings
-advanced:
-  debug_mode: false
-  markdown_output: false
-  add_datetime_to_context: true
-  read_chat_history: true
 ```
 
 ---