fix: add start args, avoid port conflict (#27)

* fix: add start args, avoid port confict

Author: qin-ctx

CONTRIBUTING.md

@@ -29,7 +29,7 @@ Thank you for your interest in contributing to MineContext! We welcome contribut
    uv sync
 
    # Run commands in the uv environment
-   uv run python -m opencontext.cli start
+   uv run opencontext start
    ```
 
    **Option 2: Using traditional venv**
@@ -44,10 +44,13 @@ Thank you for your interest in contributing to MineContext! We welcome contribut
    **If using uv:**
    ```bash
    # Start with default configuration
-   uv run python -m opencontext.cli start
+   uv run opencontext start
 
    # Start with custom config
-   uv run python -m opencontext.cli start --config /path/to/config.yaml
+   uv run opencontext start --config /path/to/config.yaml
+
+   # Start with custom port (useful for avoiding conflicts)
+   uv run opencontext start --port 8000
    ```
 
    **If using traditional venv:**
@@ -56,12 +59,20 @@ Thank you for your interest in contributing to MineContext! We welcome contribut
    source venv/bin/activate  # On Windows: venv\Scripts\activate
 
    # Start with default configuration
-   python -m opencontext.cli start
+   opencontext start
 
    # Start with custom config
-   python -m opencontext.cli start --config /path/to/config.yaml
+   opencontext start --config /path/to/config.yaml
+
+   # Start with custom port
+   opencontext start --port 8000
    ```
 
+   **Available startup options:**
+   - `--config`: Path to configuration file
+   - `--host`: Host address (overrides config file)
+   - `--port`: Port number (overrides config file)
+
 ## How to Contribute
 
 ### Reporting Issues

README.md

@@ -285,20 +285,20 @@ server:
   debug: false
 
 embedding_model:
-  provider: doubao  # 选项: openai, doubao
+  provider: doubao  # options: openai, doubao
   api_key: your-api-key
   model: doubao-embedding-large-text-240915
 
 vlm_model:
-  provider: doubao  # 选项: openai, doubao
+  provider: doubao  # options: openai, doubao
   api_key: your-api-key
   model: doubao-seed-1-6-flash-250828
 
 capture:
   enabled: true
   screenshot:
-    enabled: true # 开启截图捕获
-    capture_interval: 5  # 截图间隔（秒）
+    enabled: true # enable screenshot capture
+    capture_interval: 5  # capture interval in seconds
 ```
 
 2. **Prompt Templates** (`config/prompts_*.yaml`):
@@ -309,18 +309,28 @@ capture:
 
 ```bash
 # Start with default configuration
-uv run python -m opencontext.cli start
+uv run opencontext start
 
 # Start with custom config
-uv run python -m opencontext.cli start --config /path/to/config.yaml
+uv run opencontext start --config /path/to/config.yaml
+
+# Start with custom port (useful for avoiding conflicts)
+uv run opencontext start --port 8000
 ```
 
+**Available Options:**
+- `--config`: Path to configuration file
+- `--host`: Host address (default: from config or `localhost`)
+- `--port`: Port number (default: from config or `8000`)
+
+**Priority**: Command-line arguments > Config file > Default values
+
 Alternatively, you can activate the virtual environment manually:
 
 ```bash
 source .venv/bin/activate  # On Windows: .venv\Scripts\activate
 pip install -e .
-python -m opencontext.cli start
+opencontext start --port 8000
 ```
 
 ## 👥 Community

README_zh.md

@@ -309,18 +309,28 @@ capture:
 
 ```bash
 # 使用默认配置启动
-uv run python -m opencontext.cli start
+uv run opencontext start
 
 # 使用自定义配置启动
-uv run python -m opencontext.cli start --config /path/to/config.yaml
+uv run opencontext start --config /path/to/config.yaml
+
+# 使用自定义端口启动
+uv run opencontext start --port 8000
 ```
 
+**可用选项：**
+- `--config`：配置文件路径
+- `--host`：主机地址（默认：配置文件中的值或 `localhost`）
+- `--port`：端口号（默认：配置文件中的值或 `8000`）
+
+**优先级**：命令行参数 > 配置文件 > 默认值
+
 或者，你也可以手动激活虚拟环境：
 
 ```bash
 source .venv/bin/activate  # Windows系统: .venv\Scripts\activate
 pip install -e .
-python -m opencontext.cli start
+opencontext start --port 8000
 ```
 
 ## 👥 社区

build.sh

@@ -14,9 +14,14 @@ if ! command -v python3 &> /dev/null; then
     exit 1
 fi
 
-# 2. Install dependencies from requirements.txt
-echo "--> Installing dependencies from requirements.txt..."
-python3 -m pip install -r requirements.txt
+# 2. Check for uv and install dependencies
+if command -v uv &> /dev/null; then
+    echo "--> Using uv to install dependencies..."
+    uv sync
+else
+    echo "--> uv not found, using pip to install from pyproject.toml..."
+    python3 -m pip install -e .
+fi
 
 # 3. Install PyInstaller if not present
 if ! python3 -c "import PyInstaller" 2>/dev/null; then
@@ -58,48 +63,14 @@ if [ -f "dist/$EXECUTABLE_NAME" ] || [ -f "dist/$EXECUTABLE_NAME.exe" ]; then
         echo "⚠️ Warning: 'config' directory not found."
     fi
 
-    # Create a start script for the packaged application
-    echo "--> Creating start script in 'dist/'..."
-    cat > dist/start.sh << 'EOF'
-#!/bin/bash
-# OpenContext Start Script
-
-# Get the directory where the script is located
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-
-# Change to the script's directory to ensure paths are correct
-cd "$SCRIPT_DIR"
-
-# --- Configuration ---
-# Please replace 'your_api_key' with your actual API key before running.
-export CONTEXT_API_KEY='your_api_key'
-
-# --- Start Application ---
-EXECUTABLE="./main"
-if [ -f "$EXECUTABLE" ]; then
-    echo "Starting OpenContext..."
-    "$EXECUTABLE" start "$@"
-elif [ -f "$EXECUTABLE.exe" ]; then
-    echo "Starting OpenContext..."
-    "$EXECUTABLE.exe" start "$@"
-else
-    echo "❌ Error: Main executable not found in the current directory."
-    exit 1
-fi
-EOF
-
-    chmod +x dist/start.sh
-
     echo
-    echo "🚀 To run the application:"
-    echo "   cd dist/"
-    echo "   # IMPORTANT: Edit start.sh to set your CONTEXT_API_KEY"
-    echo "   ./start.sh"
+    echo "✅ Build complete!"
+    echo
+    echo "To run:"
+    echo "  cd dist && ./main start"
+    echo
+    echo "Options: --port 9000 | --host 0.0.0.0 | --config config/config.yaml"
     echo
-    echo "Alternatively, run the executable directly:"
-    echo "   # (Make sure to set the CONTEXT_API_KEY environment variable first)"
-    echo "   ./dist/main start"
-
 else
     echo "❌ Build failed. Check the PyInstaller logs above for errors."
     exit 1

opencontext/cli.py

@@ -121,60 +121,40 @@ def start_web_server(context_lab_instance: OpenContext, host: str, port: int, wo
 
 def parse_args() -> argparse.Namespace:
     """Parse command line arguments.
-    
+
     Returns:
         Parsed command line arguments
     """
     parser = argparse.ArgumentParser(
         description="OpenContext - Context capture, processing, storage and consumption system"
     )
-    
+
     subparsers = parser.add_subparsers(dest="command", help="Available commands")
-    
+
     # Start command
-    start_parser = subparsers.add_parser("start", help="Start OpenContext")
+    start_parser = subparsers.add_parser("start", help="Start OpenContext server")
     start_parser.add_argument(
-        "-c", "--config", 
-        type=str, 
+        "--config",
+        type=str,
         help="Configuration file path"
     )
     start_parser.add_argument(
-        "--workers",
-        type=int,
-        default=1,
-        help="Number of worker processes (default: 1)"
+        "--host",
+        type=str,
+        help="Host address (overrides config file)"
     )
-
-    # Initialize command  
-    init_parser = subparsers.add_parser("init", help="Initialize configuration")
-    init_parser.add_argument(
-        "-o", "--output", 
-        type=str, 
-        default="./config/config.yaml", 
-        help="Output configuration file path"
-    )
-    
-    # Web command
-    web_parser = subparsers.add_parser("web", help="Start web interface")
-    web_parser.add_argument(
-        "--host", 
-        type=str, 
-        default="localhost",
-        help="Host address"
-    )
-    web_parser.add_argument(
-        "--port", 
-        type=int, 
-        default=8080,
-        help="Port number"
+    start_parser.add_argument(
+        "--port",
+        type=int,
+        help="Port number (overrides config file)"
     )
-    web_parser.add_argument(
+    start_parser.add_argument(
         "--workers",
         type=int,
         default=1,
         help="Number of worker processes (default: 1)"
     )
-    
+
     return parser.parse_args()
 
 
@@ -214,10 +194,10 @@ def _run_headless_mode(lab_instance: OpenContext) -> None:
 
 def handle_start(args: argparse.Namespace) -> int:
     """Handle the start command.
-    
+
     Args:
         args: Parsed command line arguments
-        
+
     Returns:
         Exit code (0 for success, 1 for failure)
     """
@@ -231,9 +211,10 @@ def handle_start(args: argparse.Namespace) -> int:
 
     web_config = lab_instance.config.get("web", {})
     if web_config.get("enabled", True):
-        host = web_config.get("host", "localhost")
-        port = web_config.get("port", 8080)
-        
+        # Command line arguments override config file
+        host = args.host if args.host else web_config.get("host", "localhost")
+        port = args.port if args.port else web_config.get("port", 8000)
+
         try:
             logger.info(f"Starting web server on {host}:{port}")
             workers = getattr(args, 'workers', 1)
@@ -243,7 +224,7 @@ def handle_start(args: argparse.Namespace) -> int:
             lab_instance.shutdown()
     else:
         _run_headless_mode(lab_instance)
-    
+
     return 0
 def _setup_logging(config_path: Optional[str]) -> None:
     """Setup logging configuration.
@@ -261,21 +242,21 @@ def _setup_logging(config_path: Optional[str]) -> None:
 
 def main() -> int:
     """Main entry point.
-    
+
     Returns:
         Exit code (0 for success, non-zero for failure)
     """
     args = parse_args()
-    
+
     # Setup logging first
-    _setup_logging(args.config)
-    
+    _setup_logging(getattr(args, 'config', None))
+
     logger.debug(f"Command line arguments: {args}")
-    
+
     if not args.command:
-        logger.error("No command specified. Use --help for usage information.")
+        logger.error("No command specified. Use 'opencontext start' or 'opencontext --help' for usage.")
         return 1
-    
+
     if args.command == "start":
         return handle_start(args)
     else:

pyproject.toml

@@ -41,6 +41,9 @@ dependencies = [
     "imagehash",
 ]
 
+[project.scripts]
+opencontext = "opencontext.cli:main"
+
 [project.urls]
 Homepage = "https://github.com/volcengine/MineContext"
 Repository = "https://github.com/volcengine/MineContext"