■中文 ■English

• 專案概述
• 重點特色
• 使用說明
• 開發須知
• 使用技術
• 專案結構
• 備註

基於 Groq API 的終端機 AI 程式編寫助手，支援多模型切換與指令系統。

• 多模型切換：內建 5 種 Groq 模型，透過 --model 指令即時切換
• 串流輸出：AI 回覆即時逐字顯示，可隨時以 Ctrl+C 中斷生成
• 指令系統：--help、--model、--exit 等前綴指令，操作與對話輸入明確分離
• 錯誤處理完整：涵蓋 API Key 失效、額度超限、網路中斷等常見錯誤，並提供對應提示

1. 下載本倉庫並解壓縮
2. 將 .env 檔案（內容參見開發須知）與 .exe 放在同一目錄下
3. 執行 AI-Coder_v1.exe

1. 完成開發須知中的安裝步驟
2. 將 .env 檔案放在 src/main.py 所在目錄下
3. 執行：

python src/main.py

1. 開始對話： 直接輸入文字並按下 Enter，即可送出提示詞給 AI
2. 切換模型：

   --model list          # 查看可用模型清單與對應編號
   --model now            # 查看目前使用中的模型
   --model <編號>          # 切換至指定編號的模型
   

3. 顯示說明文件：

   --help
   

4. 離開程式：

   --exit
   

   執行後會再次詢問確認（y/n），輸入 y 才會結束程式

1. 請先閱讀以下開發須知並遵守所用條款。
2. 請運行以下指令複製此倉庫至您的本地電腦：

git clone <本倉庫路徑>.git

3. 使用語言：
   • Python 3.12
4. 安裝必要工具：
   • Python 模組：於專案根目錄運行以下指令

     pip install -r requirements.txt
     

5. 環境變數設定：
   • 複製 .env.example 為 .env
   • 於 .env 中填入您的 Groq API Key：

     GROQ_API_KEY=your_api_key_here
     

   • 執行檔（.exe）與原始碼（src/main.py）皆需要 .env 放在同一目錄下才能正確啟用
6. 打包執行檔：
   • 專案已附上 main.spec，可直接運行：

     pyinstaller main.spec
     

7. 使用技術：請參見使用技術
8. 專案結構：請參見專案結構

• Groq API（groq）：呼叫大型語言模型進行對話生成，並以 stream=True 實現逐字輸出
• 資源路徑處理（resourcePath）：透過 sys.frozen 判斷執行環境（開發環境 / PyInstaller 打包後），確保 config/ 內資源檔案在兩種環境下皆能正確讀取
• 例外處理分層設計：針對 Groq API 各類錯誤（AuthenticationError、RateLimitError、APIConnectionError 等）與自訂例外（CommandArgsError、EnvFileNotFoundError 等）分別捕捉並提示
• 指令解析（checkCommand）：以 -- 前綴辨識指令輸入，與一般對話輸入分流處理
• python-dotenv：載入 .env 中的環境變數（GROQ_API_KEY）
• colorama：終端機文字上色，區分不同訊息類型（錯誤／警告／提示等）

AI-Coder/
├─assets/
│  └─v1.ico                     # 應用程式圖示
├─config/
│  ├─content-setting.txt        # AI 系統提示詞設定
│  ├─help.txt                   # --help 指令顯示內容
│  └─models.txt                 # --model list 指令顯示內容
├─src/
│  ├─basic.py                   # 資源路徑處理、訊息顯示函式
│  ├─cmds.py                    # 指令定義與處理邏輯
│  ├─colors.py                  # 終端機顏色主題設定
│  └─main.py                    # 主程式進入點、對話迴圈
├─.env.example                  # 環境變數範例檔
├─.gitignore
├─main.spec                     # PyInstaller 打包設定
├─README.md
└─requirements.txt              # Python 相依套件清單

• 維護者：294Ryan - Github
• 使用條款：AGPL-3.0
• <!> 敬請在本專案所用條款之允許範圍內進行使用。且任何因操作疏失或不當使用造成的後果請自負。

• Overview
• Key Features
• Usage
• Development Guide
• Technical Notes
• Project Structure
• Notes

A terminal-based AI coding assistant powered by the Groq API, supporting multi-model switching and a built-in command system.

• Multi-model switching: 5 built-in Groq models, switchable in real time via the --model command
• Streaming output: AI responses are printed token-by-token as they generate, and can be interrupted at any time with Ctrl+C
• Command system: ---prefixed commands (--help, --model, --exit) are clearly separated from regular chat input
• Comprehensive error handling: covers invalid/expired API keys, rate limits, network failures, and other common errors, each with a corresponding user-facing message

1. Download this repository and extract it
2. Place the .env file (see Development Guide) in the same directory as the .exe
3. Run AI-Coder_v1.exe

1. Complete the installation steps in Development Guide
2. Place the .env file in the same directory as src/main.py
3. Run:

python src/main.py

1. Start a conversation: Type your prompt and press Enter to send it to the AI
2. Switch models:

   --model list          # View available models and their index numbers
   --model now            # Show the currently active model
   --model <index>         # Switch to the model at the given index
   

3. Show help document:

   --help
   

4. Exit the program:

   --exit
   

   A confirmation prompt (y/n) will appear; the program only exits after entering y

1. Please read this guide fully before proceeding and comply with the license terms.
2. Clone this repository to your local machine:

git clone <this repository URL>.git

3. Language used:
   • Python 3.12
4. Install required tools:
   • Python packages: run the following in the project root

     pip install -r requirements.txt
     

5. Environment variable setup:
   • Copy .env.example to .env
   • Fill in your Groq API key:

     GROQ_API_KEY=your_api_key_here
     

   • Both the .exe and src/main.py require .env to be placed in the same directory in order to run correctly
6. Building the executable:
   • main.spec is included; build with:

     pyinstaller main.spec
     

7. Technical notes: see Technical Notes
8. Project structure: see Project Structure

• Groq API (groq): handles chat completions and uses stream=True for token-by-token output
• Resource path resolution (resourcePath): uses sys.frozen to detect whether the app is running from source or as a PyInstaller-packaged executable, ensuring files under config/ resolve correctly in both cases
• Layered exception handling: Groq API errors (AuthenticationError, RateLimitError, APIConnectionError, etc.) and custom exceptions (CommandArgsError, EnvFileNotFoundError, etc.) are each caught and handled separately
• Command parsing (checkCommand): identifies ---prefixed commands and routes them separately from regular chat input
• python-dotenv: loads environment variables (GROQ_API_KEY) from .env
• colorama: terminal text coloring to visually distinguish message types (error / warning / info, etc.)

AI-Coder/
├─assets/
│  └─v1.ico                     # Application icon
├─config/
│  ├─content-setting.txt        # AI system prompt configuration
│  ├─help.txt                   # Content shown by the --help command
│  └─models.txt                 # Content shown by the --model list command
├─src/
│  ├─basic.py                   # Resource path handling, message display functions
│  ├─cmds.py                    # Command definitions and handling logic
│  ├─colors.py                  # Terminal color theme configuration
│  └─main.py                    # Main entry point, chat loop
├─.env.example                  # Environment variable example file
├─.gitignore
├─main.spec                     # PyInstaller build configuration
├─README.md
└─requirements.txt              # Python dependency list

• Maintainer: 294Ryan - Github
• License: AGPL-3.0
• <!> Please use this product only within the scope permitted by the terms and conditions of this project. You are solely responsible for any consequences arising from operational errors or improper use.