AI - vs code + Cline 筆記

在 Cline 這種自主程式碼代理（Agentic）的工作流程中，模型收到的「系統提示（System Prompt）」和「工具調用格式」決定了其推理和執行任務的成功率。

針對您的需求，我整理了以下關於 Ollama Modelfile 的最佳實踐和優化範本，以確保 DeepSeek R1 32B 和 Qwen 2.5 Coder 32B 在 Cline 中發揮最強的推理和編碼能力。

由於 Cline 會發送自己的複雜指令，因此我們的目標是：

1. 移除模型預設的「聊天」指令。

2. 明確告訴模型它是一個「Code Agent」並需要「思考」，以強化它的推理能力。

---

🚀 適用於 Cline 的 Ollama Modelfile 最佳化範本

您可以為您選擇的模型創建一個自定義版本，將以下內容儲存為一個名為 Modelfile 的文件。

1. DeepSeek R1 32B 的推理強化 Modelfile

模型名稱： deepseek-r1-cline-agent

目標： 強化 DeepSeek R1 的邏輯推理（Reasoning）能力，讓它能更好地處理 Cline 的多步驟規劃。

程式碼片段

# 假設您已經下載了 deepseek-r1:32b
FROM deepseek-r1:32b 

# 核心系統提示：設定模型角色並要求 Chain-of-Thought (思維鏈)
SYSTEM """
你是一個自主程式碼代理 (Autonomous Coding Agent)。你的任務是嚴格遵循使用者的指令，並透過一系列步驟來完成複雜的程式碼修改和系統規劃。

**指令遵循要求:**
1. **先思考 (THINKING):** 在採取任何行動之前，**務必**使用中文或英文在 `<thinking>` 和 `</thinking>` 標籤內說明你的邏輯推理、任務分解和下一步的行動計劃。
2. **工具調用 (TOOL USE):** 嚴格遵循 Cline 或你所使用的 Agent 框架提供的工具調用格式。
3. **最終結果 (OUTPUT):** 只有在完成所有步驟後，才提供最終的程式碼或文字。
"""

# 設定參數以提高推理質量和輸出完整性
PARAMETER temperature 0.1
PARAMETER top_k 40
PARAMETER top_p 0.9
PARAMETER num_ctx 8192  # 確保足夠的上下文長度

2. Qwen 2.5 Coder 32B 的編碼穩定 Modelfile

模型名稱： qwen25-coder-cline-agent

目標： 保持 Qwen Coder 在程式碼生成上的高穩定性，同時加入 Agentic 任務所需的思考步驟。

程式碼片段

# 假設您已經下載了 qwen2.5-coder:32b-instruct
FROM qwen2.5-coder:32b-instruct 

# 核心系統提示：設定模型角色並強調程式碼輸出
SYSTEM """
你是一個高度專業的程式碼生成和編輯代理 (Code Generation and Editing Agent)。你的首要任務是產生正確、可運行的程式碼。

**工作流程準則:**
1. **分析與規劃 (PLANNING):** 使用 `<plan>` 和 `</plan>` 標籤，簡潔地規劃你的步驟。這能確保多輪任務的連貫性。
2. **高效執行 (EXECUTION):** 專注於程式碼輸出，減少冗餘的解釋。
3. **工具調用 (TOOL USE):** 嚴格遵循宿主環境（如 Cline）的工具和指令格式來操作文件或執行命令。
"""

# 設定參數
PARAMETER temperature 0.2  # 程式碼任務可稍微提高溫度以鼓勵創造性解法
PARAMETER top_k 40
PARAMETER top_p 0.9
PARAMETER num_ctx 8192

---

🔧 如何在 Ollama 中應用 Modelfile

1. 創建 Modelfile： 將您選擇的範本內容貼上到一個名為 Modelfile 的文件中（例如，在您的家目錄或任何方便的位置）。

2. 創建自定義模型： 開啟終端機，導航到 Modelfile 所在的路徑，並執行以下命令：

   • 若選擇 DeepSeek R1：

     Bash

     ollama create deepseek-r1-cline-agent -f Modelfile
     

   • 若選擇 Qwen 2.5 Coder：

     Bash

     ollama create qwen25-coder-cline-agent -f Modelfile
     

3. 在 Cline 中使用： 打開 VS Code 的 Cline 設定：

   • 選擇 Ollama 作為 API Provider。

   • 在 Model ID 欄位中，填寫您剛才創建的新模型名稱 (deepseek-r1-cline-agent 或 qwen25-coder-cline-agent)。

透過這種方式，您就可以確保模型在執行 Cline 的複雜 Agentic 任務時，能最大化其推理和指令遵循能力，從而有效減少或消除您提到的警告。

建議您先嘗試使用 DeepSeek R1 的 Modelfile，它在「邏輯規劃」上的先天優勢，對處理 Cline 的「警告」會更有幫助。

「雙模型策略」完美地結合了兩個模型的優勢：

• DeepSeek R1 32B (Plan Mode): 利用其卓越的邏輯推理和思維鏈（CoT）能力來分解複雜的任務。

• Qwen 2.5 Coder 32B (Act Mode): 利用其在編碼基線測試上的高精確度來執行代碼生成和編輯任務。

然而，在目前的 Cline / Ollama 標準設定中，實現動態切換模型是有技術難度的。

透過自定義的 Modelfile，我們可以強制 DeepSeek R1 32B 在保持其強大邏輯推理能力的同時，採用 Qwen Coder 嚴謹、簡潔的程式碼輸出風格。

這能讓單一模型在 Cline 的 Agentic 工作流中，同時兼顧 Plan（規劃）和 Act（執行）的優勢。

---

🛠️ DeepSeek R1 混合代理 Modelfile

請將以下內容儲存為一個名為 Modelfile 的文件。

模型名稱： deepseek-r1-hybrid-agent

程式碼片段

# 以 DeepSeek R1 32B 作為基礎模型
FROM deepseek-r1:32b 

# 核心系統提示：設定模型的雙重角色
SYSTEM """
你是一個雙模式的自主程式碼代理 (Dual-Mode Autonomous Code Agent)：一個嚴謹的規劃者和一個精確的程式碼生成器。你的目標是提供最高品質的代碼解決方案。

**模式準則 (同時滿足 Plan & Act 的要求):**

1. **規劃與推理 (Plan Mode - DeepSeek R1 Style):**
   * 對於複雜或多步驟任務，**務必**使用 `<thinking>` 和 `</thinking>` 標籤詳細說明你的邏輯推理、任務分解和下一步行動計劃。這是你內部審核的過程。

2. **程式碼輸出 (Act Mode - Qwen Coder Style):**
   * 當你生成程式碼或修改文件內容時，你的輸出必須是**簡潔、最小化的 (Minimalist)**。
   * **嚴格遵守 Markdown 程式碼區塊 (```) 的格式。**
   * **禁止**使用不必要的序言，例如：「以下是程式碼」、「請查看我的解決方案」或「我已完成」等文字。程式碼區塊前後應保持極簡。

3. **指令遵循：** 嚴格遵循宿主環境（如 Cline）提供的任何工具調用格式。
"""

# 參數調整：傾向於精確度 (低溫) 和高吞吐量 (大上下文)
PARAMETER temperature 0.15  # 略高於 0.1，以鼓勵推理，但仍保持精確
PARAMETER top_k 40
PARAMETER top_p 0.9
PARAMETER num_ctx 12288  # 提高上下文至 12K 或更高 (依據您的 24GB VRAM 狀況)

應用步驟

1. 創建模型： 在終端機中，導航到包含您 Modelfile 的目錄，然後執行：

   Bash

   ollama create deepseek-r1-hybrid-agent -f Modelfile
   

2. 在 Cline 中設定： 將 Cline 的 Model ID 設定為您新創建的名稱：deepseek-r1-hybrid-agent。

透過這個混合 Modelfile，您應該能同時享受到 DeepSeek R1 的優異規劃能力和 Qwen Coder 的輸出質量。

雖然 Cline 在「自主代理（Agentic）」模式上非常強大，但它的配置和模型限制（如您遇到的警告）確實可能造成困擾。

針對您擁有 NVIDIA 5090 24GB VRAM 和 Ollama Server 的強大本地環境，我為您推薦以下幾個在 VS Code 上能與本地 LLM 完美整合，且在編程輔助功能上表現優異的擴充套件：

🌟 頂級本地 LLM 程式碼輔助擴充套件

擴充套件名稱	核心功能	本地 LLM 支援	適合您的情境
1. Continue	多步驟 RAG / 程式碼協作	原生支援 Ollama	最推薦的 Cline 替代品。 專注於程式碼塊的修改、基於整個專案的問答（RAG），可以執行多步驟指令。
2. CodeGPT	通用程式碼聊天 / 專案上下文	支援 Ollama (透過 Custom API)	優秀的通用程式碼聊天和文件問答工具。適合單回合的 Q&A、解釋、重構。
3. Local LLM	純粹的本地 API 連接	專為本地模型設計	如果您只需要一個簡單的聊天介面來和您的 Ollama 模型互動，這是最簡單的選擇。

---

1. Continue (最強力的替代品)

Continue 是目前社群公認在本地 LLM 整合方面做得最好的 VS Code 擴充套件之一。它和 Cline 一樣，可以處理複雜、多步驟的任務，但介面更為直觀且配置更靈活。

• 專長：

  • 程式碼感知（RAG）： 能夠意識到您正在查看的檔案、選取的程式碼，以及整個專案的上下文。

  • 多步驟指令： 您可以輸入「檢查 foo.py 中的錯誤，並使用 bar.js 中的格式重構它」。

  • 原生 Ollama 支援： 配置非常簡單，直接指向您的 Ollama Server 即可。

• 配置優勢： 您可以將您配置好的 deepseek-r1-hybrid-agent 模型直接填入 Continue 的設定中，利用其強大的推理能力。

2. CodeGPT

CodeGPT 是一個非常成熟的程式碼聊天擴充套件。它最初專注於 OpenAI 等 API，但現在也提供了彈性的自定義 API 選項。

• 專長：

  • 多功能選單： 內建許多預設指令，例如「解釋程式碼」、「重構」、「查找 Bug」。

  • 自定義 Prompt： 允許您為不同的任務創建和儲存自己的 Prompt Template。

  • 操作簡便： 介面易於上手，適合日常的程式碼問答和快速修改。

• 配置方法： 在 CodeGPT 的設定中，選擇 Custom API 或 Ollama 選項，然後輸入您的 http://192.168.1.106:11434 地址。

總結推薦

如果您希望獲得最接近 Cline 的功能（多步驟、專案感知），並且想充分利用 DeepSeek R1 的推理能力，我強烈建議您試用 Continue。

AI - 自訂環境 LLM Agent 部署指南

自訂環境 LLM Coding Agent 部署指南 (Win11 Host + WSL2 Docker 混合架構)

本文件專為您的特定混合環境設計。在此架構中，運算核心 (Ollama) 與開發核心 (Agent/C#) 運行於 Windows Host，而服務設施 (GitLab/WebUI) 運行於 WSL2 Docker。

您的環境配置確認：

• Host IP: 192.168.1.106 (DHCP 動態，建議使用自動解析策略)

• Ollama: Windows Native (:11434)

• GitLab: WSL2 Docker (:8929)

• Open WebUI: WSL2 Docker (:4000)

• Agent (本腳本): 將運行於 Windows Native (以便操作 C# SDK 與檔案系統)

🗺️ 第一部分：總體步驟大綱

階段	步驟名稱	執行環境	目的
0	IP 連線策略配置	PowerShell/Docker	(關鍵) 決定並設定 IP 自動解析機制，解決 DHCP 變動問題
I	環境連線檢查	PowerShell (Win)	確認 Windows 能連線到 WSL2 中的 GitLab 與 WebUI
II	GitLab 驗證配置	瀏覽器/PowerShell	(必需) 取得 PAT 以進行 API 呼叫，並選擇 Git 操作的驗證方式
III	Agent 工作區建置	PowerShell (Win)	在 Windows 上建立 Python Venv 與 C# 專案目錄
IV	部署 Agent 服務	PowerShell (Win)	設定 .env 並啟動 Flask API (綁定 0.0.0.0 以供容器存取)
V	整合測試	WebUI & PowerShell	設定 WebUI Tool Calling 並執行端對端測試

📁 第二部分：資料夾結構圖

1. 系統服務 (WSL2 Ubuntu 內部)

這部分由您的 Docker 管理，Windows 端只需知道連接埠。

• GitLab: localhost:8929

• Open WebUI: localhost:4000

2. 使用者開發工作區 (Windows C 槽使用者目錄)

注意： Agent 必須運行在 Windows 上，才能直接呼叫 dotnet CLI 並修改 Windows 檔案系統上的 C# 專案。

C:\Users\<USERNAME>\
└── LLM_Coding_Agent\
    ├── .env                <-- [設定] 指向 localhost:8929 (GitLab) 和 192.168.1.106 (Ollama)
    │
    ├── Agent_Scripts\      <-- [核心] Python Agent 程式碼
    │   └── agent_api.py    <-- Flask API (需設定 host='0.0.0.0')
    │
    ├── Code_Project\       <-- [專案] C# WinForm 原始碼
    │   ├── .git/
    │   └── WinFormApp/
    │
    └── venv\               <-- [環境] Python 虛擬環境

💻 第三部分：詳細指令與驗證機制

階段 0：動態 IP 連線策略配置 (關鍵步驟)

針對 DHCP 環境，請選擇以下一種方式來確保連線穩定，避免 IP 變動導致服務中斷。

方式 A：自動解析 (強烈推薦)

利用 Docker 的 Host Gateway 功能，讓容器透過固定名稱連線到 Windows Host。

1. 修改 Open WebUI 的啟動指令： 在 WSL2 Ubuntu 中啟動 Docker 容器時，必須加入 --add-host=host.docker.internal:host-gateway 參數。

   # (在 WSL2 Ubuntu 中執行)
   (WSL2 Bash) $ docker run -d -p 4000:8080 \
     --add-host=host.docker.internal:host-gateway \
     -v open-webui:/app/backend/data \
     --name open-webui \
     --restart always \
     ghcr.io/open-webui/open-webui:main
   

2. 連線設定變更： 以後在 Open WebUI 設定連線時，一律使用：

   • Ollama: http://host.docker.internal:11434

   • Agent API: http://host.docker.internal:5000

方式 B：手動修改 (僅作備用)

若不重新建立容器，則需在每次 IP 變動時執行：

1. 在 Windows PowerShell 執行 ipconfig 查詢新 IP (例如 192.168.1.X)。

2. 進入 Open WebUI -> 設定 -> 更新連線 URL 為新 IP。

階段 I：環境連線檢查

執行身分： Windows 使用者 (PowerShell)

步驟	指令 / 操作	意圖與參數說明	驗證機制 (Validation)
I.1	檢查 Ollama PS C:\Users\<USERNAME>> curl http://localhost:11434 (若報錯請用 PS C:\Users\<USERNAME>> iwr http://localhost:11434)	意圖： 檢查 Ollama 服務是否在 Windows Host 上運行。 參數： http://localhost:11434 為 Ollama 服務的預設位址。iwr (Invoke-WebRequest) 是 PowerShell 原生別名。	回傳包含 "Ollama is running" 的訊息。
I.2	檢查 GitLab (Docker) PS C:\Users\<USERNAME>> (iwr -Uri http://localhost:8929/users/sign_in).StatusCode	意圖： 檢查 Windows Host 是否能連線到 WSL2 Docker 中的 GitLab 服務並取得 HTTP 狀態碼。StatusCode 用於擷取結果。	回傳狀態碼 200 或 302 (代表連線成功)。
I.3	檢查 WebUI (Docker) PS C:\Users\<USERNAME>> (iwr -Uri http://localhost:4000).StatusCode	意圖： 檢查 Windows Host 是否能連線到 WSL2 Docker 中的 Open WebUI 服務並取得 HTTP 狀態碼。StatusCode 用於擷取結果。	回傳狀態碼 200 或 302 (代表連線成功)。

階段 II：GitLab 驗證配置

執行身分： 瀏覽器操作

步驟	說明	驗證機制 (Validation)
II.1 (必需)	生成 Personal Access Token (PAT) 原因：PAT 絕對必需用於 Agent 呼叫 GitLab REST API (創建專案、MR)。 開啟 http://localhost:8929，登入您的帳號。 點擊頭像 -> Preferences -> Access Tokens。 新增 Token，Scope 勾選 api，Role 選 Maintainer。 複製此 Token (例如 glpat-abcdefg)。	取得 Token 字串。
II.2 (可選)	設定 Git 操作驗證方式 您的 Agent 預設使用 PAT 搭配 HTTP/S 進行 git push (詳見 agent_api.py 程式碼)。 若堅持使用 SSH： 您必須確保 Windows Host 的 Git 環境已正確設定 SSH Key，並在 Agent 執行前手動修改 agent_api.py 中 create_gitlab_project 工具設定的 Remote URL 為 SSH 格式 (此步驟較複雜，不建議)。	確認您已將 PAT 貼入 .env 檔案的 GITLAB_PAT 欄位。

階段 III：Agent 工作區建置

執行身分： Windows 使用者 (PowerShell)

步驟	指令 / 操作	意圖與參數說明	驗證機制 (Validation)
III.1	PS C:\Users\<USERNAME>> cd ~ PS C:\Users\<USERNAME>> mkdir LLM_Coding_Agent; cd LLM_Coding_Agent PS C:\Users\<USERNAME>\LLM_Coding_Agent> mkdir Agent_Scripts Code_Project	cd ~: 切換到使用者根目錄 (C:\Users\<USERNAME>)。 mkdir LLM_Coding_Agent: 建立主工作目錄。 cd LLM_Coding_Agent: 進入工作目錄。 mkdir Agent_Scripts Code_Project: 建立兩個子目錄。Agent_Scripts：存放 Python 程式碼；Code_Project：存放 C# 專案。	dir 確認目錄建立。
III.2	PS C:\Users\<USERNAME>\LLM_Coding_Agent> python -m venv venv PS C:\Users\<USERNAME>\LLM_Coding_Agent> .\venv\Scripts\Activate.ps1 (venv) PS C:\Users\<USERNAME>\LLM_Coding_Agent> pip install flask langchain langchain-ollama python-dotenv pyodbc requests	python -m venv venv: 建立名為 venv 的 Python 虛擬環境。-m venv 參數指示 Python 執行 venv 模組。 .\venv\Scripts\Activate.ps1: 啟動虛擬環境 (PowerShell 專用)。 pip install ...: 安裝 Agent 運作所需的所有 Python 套件。	(venv) 出現；安裝無錯誤。
III.3	(venv) PS C:\Users\<USERNAME>\LLM_Coding_Agent> cd Code_Project (venv) PS C:\Users\<USERNAME>\LLM_Coding_Agent\Code_Project> dotnet new winforms -n WinFormApp (venv) PS C:\Users\<USERNAME>\LLM_Coding_Agent\Code_Project> git init (venv) PS C:\Users\<USERNAME>\LLM_Coding_Agent\Code_Project> git add . (venv) PS C:\Users\<USERNAME>\LLM_Coding_Agent\Code_Project> git commit -m "Init"	cd Code_Project: 進入專案目錄。 dotnet new winforms -n WinFormApp: 使用 dotnet CLI 建立一個名為 WinFormApp 的 C# WinForms 應用程式。-n 參數指定專案名稱。 git init: 在當前目錄初始化一個 Git 倉庫。 git add .: 將所有檔案加入暫存區。. 表示當前目錄下的所有變更。 git commit -m "Init": 提交初始版本。-m 參數用於提供提交訊息。	git log 顯示一筆提交。

階段 IV：部署 Agent 服務

執行身分： Windows 使用者 (PowerShell)

1. 建立設定檔 .env

在 LLM_Coding_Agent 根目錄建立檔案 .env。 注意： Agent 運行在 Windows 上，它看 Windows 服務用 localhost，它看 WSL2 服務也用 localhost (因為 Windows localhost 會自動轉發到 WSL2)。

# Agent (Win) 連線到 GitLab (WSL2 Docker)
# 在 Windows 端存取 WSL2 服務可直接用 localhost:8929
GITLAB_URL=http://localhost:8929
GITLAB_PAT=你的_glpat_token_貼在這裡

# Agent (Win) 連線到 Ollama (Win)
OLLAMA_BASE_URL=http://localhost:11434

# 資料庫 (可選)
SQL_SERVER=(localdb)\MSSQLLocalDB

2. 部署程式碼 agent_api.py

將文件末尾的 附錄：Python Agent 核心程式碼 存檔至 Agent_Scripts\agent_api.py。

3. 啟動 API

# (若您當前不在 LLM_Coding_Agent 根目錄，請先 cd)
(venv) PS C:\Users\<USERNAME>\LLM_Coding_Agent> .\venv\Scripts\Activate.ps1
# 意圖：再次確保 Python 虛擬環境已啟用。
# 參數：無。

(venv) PS C:\Users\<USERNAME>\LLM_Coding_Agent> python Agent_Scripts\agent_api.py
# 意圖：執行 Agent 的 Flask API 程式，啟動服務。
# 參數：Agent_Scripts\agent_api.py 是要執行的 Python 腳本路徑。

import os
import subprocess
from flask import Flask, request, jsonify
# === LangChain 導入修正 (修正 AgentExecutor ImportError) ===
# 錯誤原因：在某些較新的 LangChain 版本中，AgentExecutor 被移至 langchain.agents.base
from langchain.agents import create_tool_calling_agent
from langchain.agents.base import AgentExecutor
# =========================================================
from langchain_core.prompts import ChatPromptTemplate
from langchain_ollama import Ollama
from langchain.tools import tool
from dotenv import load_dotenv
import pyodbc
import requests
import json
# 載入 .env
load_dotenv()
# --- 網路設定 ---
# 讀取環境變數，若無則使用預設值
OLLAMA_BASE_URL = os.getenv("OLLAMA_BASE_URL", "http://localhost:11434")
MODEL_NAME = "deepseek-coder:33b-instruct"
GITLAB_URL = os.getenv("GITLAB_URL", "http://localhost:8929")
GITLAB_PAT = os.getenv("GITLAB_PAT")
SQL_SERVER = os.getenv("SQL_SERVER")
# 專案路徑 (Windows 格式)
PROJECT_ROOT = os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'Code_Project')
app = Flask(__name__)
current_project_id = None
# --- 工具集 (Tools) ---
@tool
def create_gitlab_project(name: str, description: str = "", visibility: str = "private") -> str:
    """創建 GitLab 專案並更新本地 Git Remote。PAT 用於 API 驗證。"""
    global current_project_id
    if not GITLAB_PAT: return "錯誤：缺少 GITLAB_PAT (PAT 必需用於 API 呼叫)"
    
    url = f"{GITLAB_URL}/api/v4/projects"
    headers = {'Private-Token': GITLAB_PAT, 'Content-Type': 'application/json'}
    data = {'name': name, 'description': description, 'visibility': visibility, 'namespace_id': 1}
    
    try:
        # Agent 在 Windows 上，可以直接連 localhost:8929
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        info = response.json()
        current_project_id = str(info['id'])
        
        # 取得 Repo URL
        raw_url = info['http_url_to_repo']
        
        # 確保 URL 是 Windows Host 可以連線的格式 (使用 localhost:8929)
        # 此處是 PAT + HTTP 方式進行 Git Push/Pull
        repo_url = raw_url.replace("[http://gitlab.example.com](http://gitlab.example.com)", "http://localhost:8929") 
        if "localhost:8929" not in repo_url:
             # 如果 raw_url 已經是正確的 ip/port 則不需替換，若不是則嘗試修正
             pass 
        # 將 PAT 塞入 URL (Http Basic Auth)
        # 格式: http://oauth2:TOKEN@localhost:8929/root/repo.git
        auth_repo_url = repo_url.replace("http://", f"http://oauth2:{GITLAB_PAT}@")
        # Git 操作：設定 Remote URL
        try:
            # 嘗試修改 remote
            subprocess.run(['git', 'remote', 'set-url', 'origin', auth_repo_url], cwd=PROJECT_ROOT, check=True, capture_output=True)
        except:
            # 若無 remote 則新增
            subprocess.run(['git', 'remote', 'add', 'origin', auth_repo_url], cwd=PROJECT_ROOT, check=True, capture_output=True)
            
        return f"專案建立成功 ID: {current_project_id}"
    except Exception as e:
        return f"建立失敗: {e}"
@tool
def execute_local_git_command(command: str) -> str:
    """執行本地 Git 指令"""
    try:
        res = subprocess.run(['git'] + command.split(), cwd=PROJECT_ROOT, capture_output=True, text=True, check=True)
        return f"Git 輸出: {res.stdout}"
    except subprocess.CalledProcessError as e:
        return f"Git 錯誤: {e.stderr}"
@tool
def push_to_gitlab_remote(branch_name: str) -> str:
    """Push 到遠端"""
    try:
        res = subprocess.run(['git', 'push', 'origin', branch_name], cwd=PROJECT_ROOT, capture_output=True, text=True, check=True)
        return f"Push 成功: {res.stdout}"
    except subprocess.CalledProcessError as e:
        return f"Push 失敗: {e.stderr}"
@tool
def write_file_to_project(filepath: str, content: str) -> str:
    """寫入檔案"""
    path = os.path.join(PROJECT_ROOT, filepath)
    os.makedirs(os.path.dirname(path), exist_ok=True)
    with open(path, 'w', encoding='utf-8') as f: f.write(content)
    return f"寫入: {filepath}"
@tool
def create_gitlab_merge_request(title: str, source_branch: str, target_branch: str = "main") -> str:
    """建立 MR。PAT 必需用於 API 驗證。"""
    if not current_project_id: return "無專案 ID"
    url = f"{GITLAB_URL}/api/v4/projects/{current_project_id}/merge_requests"
    headers = {'Private-Token': GITLAB_PAT, 'Content-Type': 'application/json'}
    data = {'source_branch': source_branch, 'target_branch': target_branch, 'title': title}
    try:
        res = requests.post(url, headers=headers, json=data)
        return f"MR 建立成功: {res.json().get('web_url', 'unknown')}"
    except Exception as e:
        return f"MR 失敗: {e}"
@tool
def execute_sql_script(sql_query: str) -> str:
    """連接 SQL Server 執行查詢"""
    if not SQL_SERVER: return "錯誤：未設定 SQL_SERVER。"
    conn_str = f"Driver={{ODBC Driver 17 for SQL Server}};Server={SQL_SERVER};Database=master;Trusted_Connection=yes;"
    try:
        conn = pyodbc.connect(conn_str)
        cursor = conn.cursor()
        cursor.execute(sql_query)
        if sql_query.strip().upper().startswith('SELECT'):
            rows = cursor.fetchall()
            conn.close()
            return f"查詢結果: {rows}"
        conn.commit()
        conn.close()
        return "SQL 執行成功。"
    except Exception as e:
        return f"SQL 錯誤: {e}"
# --- Agent 啟動 ---
def create_agent():
    llm = Ollama(model=MODEL_NAME, base_url=OLLAMA_BASE_URL)
    tools = [create_gitlab_project, execute_local_git_command, push_to_gitlab_remote, write_file_to_project, create_gitlab_merge_request, execute_sql_script]
    
    prompt = ChatPromptTemplate.from_messages([
        ("system", "你是 C# 開發 Agent。若需新專案請先調用 create_gitlab_project。"),
        ("user", "{input}"),
        ("placeholder", "{agent_scratchpad}")
    ])
    
    agent = create_tool_calling_agent(llm, tools, prompt)
    return AgentExecutor(agent=agent, tools=tools, verbose=True)
agent_executor = create_agent()
@app.route('/run_task', methods=['POST'])
def run_task():
    data = request.json
    user_input = data.get('prompt')
    if not user_input: return jsonify({"status": "error"}), 400
    try:
        res = agent_executor.invoke({"input": user_input})
        return jsonify({"status": "success", "result": res['output']})
    except Exception as e:
        return jsonify({"status": "error", "message": str(e)}), 500
if __name__ == '__main__':
    print(f"Agent 監聽中: 0.0.0.0:5000 (允許來自 WSL2 容器連線)")
    # 關鍵：host='0.0.0.0' 允許外部 (包含 WSL2 容器) 連線
    app.run(host='0.0.0.0', port=5000)

AI - 本地 LLM Coding Agent 部署指南 (Win11 + Docker GitLab 雙帳號版)

 

本地 LLM Coding Agent 部署指南 (Win11 + Docker GitLab 雙帳號版)

本文件整合了在 Windows 11 筆電上建立「口語/文字驅動程式開發 Agent」的完整步驟。 此架構利用 NVIDIA 5090 的強大算力，結合 Ollama 與 Docker，實現從需求輸入到 GitLab 專案創建、程式碼提交、MR 建立的全自動化流程。

🗺️ 第一部分：總體步驟大綱

階段	步驟名稱	執行環境	執行頻率	目的
I	基礎設施準備	Windows (Admin)	僅需一次	安裝 Docker Desktop, Ollama, Git, .NET SDK
II	GitLab 與模型配置	Docker & Ollama	僅需一次	啟動本地 GitLab 容器，下載 DeepSeek Coder 模型
III	隔離工作區建置	各自帳號的 PowerShell	每個帳號各做一次	建立 Python Venv, 設定獨立的 .env (含 PAT)
IV	C# 專案初始化	各自帳號的 PowerShell	每個帳號各做一次	建立基礎 C# WinForm 專案結構
V	啟動服務與執行	PowerShell & WebUI	每次開發時	啟動 Agent API, Open WebUI, 執行自動化開發任務

📁 第二部分：資料夾結構圖

1. 系統共享資源 (C 槽根目錄)

此目錄存放 GitLab 容器的資料庫與儲存庫，所有使用者共用此服務。

C:\
└── gitlab_data\        <-- [共享] GitLab 容器的永續儲存空間
    ├── config\
    ├── data\
    └── logs\

2. 使用者隔離工作區 (各自的 User Home 目錄)

注意： 個人帳號與網域帳號需分別在其 Home 目錄下建立此結構。

C:\Users\<USERNAME>\
└── LLM_Coding_Agent\
    ├── .env                <-- [關鍵隔離] 存放該使用者的 GitLab PAT 和初始設定
    │
    ├── Agent_Scripts\      <-- [獨立] Python Agent 核心程式碼
    │   └── agent_api.py    <-- Flask API 啟動檔 (程式碼附於文件末尾)
    │
    ├── CSharp_Project\     <-- [獨立] C# 專案操作區
    │   ├── .git/
    │   └── WinFormApp/     <-- 實際的 C# 程式碼
    │
    └── venv\               <-- [獨立] Python 虛擬環境

💻 第三部分：詳細指令與驗證機制

階段 I：基礎設施準備 (系統共享)

執行身分： 具有管理員權限的 Windows 帳號。

步驟	環境	指令 / 操作	驗證機制 (Validation)
I.1	GUI	安裝 Docker Desktop 下載並安裝 Docker Desktop for Windows。 注意：安裝完成後請確保設定中開啟 WSL 2 backend。	PowerShell: docker --version 應顯示 Docker版本號。
I.2	GUI	安裝 Ollama (Desktop) 下載並安裝 Ollama Windows版。	PowerShell: ollama -v 應顯示 Ollama 版本號。
I.3	PowerShell	安裝開發工具 winget install Microsoft.Git -e winget install Microsoft.DotNet.SDK.8 -e	PowerShell: git --version dotnet --list-sdks 確認皆已安裝。
I.4	PowerShell	建立資料目錄 mkdir C:\gitlab_data	檔案總管: 確認 C 槽有 gitlab_data 資料夾。

階段 II：GitLab 與模型配置 (系統共享)

執行身分： 管理員或任何能執行 Docker 的帳號。

步驟	環境	指令 / 操作	驗證機制 (Validation)
II.1	PowerShell	啟動 GitLab 容器 docker run --detach --hostname localhost --publish 8080:80 --name gitlab --restart always --volume C:/gitlab_data/config:/etc/gitlab --volume C:/gitlab_data/logs:/var/log/gitlab --volume C:/gitlab_data/data:/var/opt/gitlab gitlab/gitlab-ce:latest	PowerShell: docker ps 應看到 gitlab 容器狀態為 Up。
II.2	Browser	配置 GitLab (需等待 5-15分鐘啟動) 1. 開啟 http://localhost:8080 2. 設定 root 密碼並登入。 3. 關鍵： 進入 User Settings -> Access Tokens，生成一個 Personal Access Token (PAT)，權限勾選 api。	瀏覽器: 成功登入並取得 PAT 字串 (例如 glpat-xxxxxx)。
II.3	PowerShell	下載 LLM 模型 ollama run deepseek-coder:33b-instruct	PowerShell: ollama list 應看到 deepseek-coder 模型。

階段 III：隔離工作區建置 (各自執行)

執行身分： 分別在「個人帳號」與「網域帳號」登入後執行。

步驟	環境	指令 / 操作	驗證機制 (Validation)
III.1	PowerShell	建立目錄與虛擬環境 cd ~ mkdir LLM_Coding_Agent; cd LLM_Coding_Agent mkdir Agent_Scripts CSharp_Project python -m venv venv .\venv\Scripts\Activate.ps1	PowerShell: 命令列前方出現 (venv)。
III.2	(venv) PowerShell	安裝 Python 套件 pip install flask langchain langchain-ollama python-dotenv pyodbc requests	PowerShell: 無錯誤訊息，顯示安裝成功。
III.3	Editor	建立 .env 設定檔 在 LLM_Coding_Agent 根目錄建立 .env 檔案，內容如下： GITLAB_URL=http://localhost:8080 GITLAB_PAT=你的_專屬_PAT_貼在這裡 SQL_SERVER=(localdb)\MSSQLLocalDB	手動檢查: 確認檔案存在，且 PAT 是該帳號專屬的。
III.4	Editor	部署 Agent 程式碼 將本文末尾附錄的 Python 程式碼存檔為 Agent_Scripts\agent_api.py。	手動檢查: 確認檔案已建立。

階段 IV：C# 專案初始化 (各自執行)

執行身分： 分別在兩個帳號下執行。

步驟	環境	指令 / 操作	驗證機制 (Validation)
IV.1	PowerShell	建立 C# 專案 cd LLM_Coding_Agent\CSharp_Project dotnet new winforms -n WinFormApp	PowerShell: dir 應看到 WinFormApp 資料夾。
IV.2	PowerShell	Git 初始化 git init git add . git commit -m "Initial structure" (註：不需要手動加 remote，Agent 會自動處理)	PowerShell: git log 應看到一筆 commit。

階段 V：啟動服務與執行 (日常操作)

執行身分： 當下要進行開發的帳號。

步驟	環境	指令 / 操作	驗證機制 (Validation)
V.1	PowerShell	啟動 Agent API (後端) cd LLM_Coding_Agent .\venv\Scripts\Activate.ps1 python Agent_Scripts\agent_api.py	PowerShell: 顯示 Running on http://127.0.0.1:5000。
V.2	PowerShell	啟動 Open WebUI (前端) docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui --restart always ghcr.io/open-webui/open-webui:main	PowerShell: docker ps 顯示 open-webui 運作中。
V.3	Browser	WebUI 操作 1. 開啟 http://localhost:3000。 2. 確保已設定 Tool Calling 指向 Flask API。 3. 輸入指令： "我要開發一個計算機功能。請先在 GitLab 建立名為 Calculator_App 的私有專案。然後在 WinFormApp/Program.cs 加入註釋 '// Start'，提交到 feat-calc 分支並建立 MR。"	GitLab (localhost:8080): 看到新專案 Calculator_App 被建立，且有一個新的 Merge Request。 PowerShell (V.1視窗): 看到 Agent 依序呼叫 create_gitlab_project -> write_file -> git 等工具的 Log。

🐍 附錄：Python Agent 核心程式碼 (agent_api.py)

請將以下程式碼複製並儲存至 Agent_Scripts\agent_api.py。

import os
import subprocess
from flask import Flask, request, jsonify
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate
from langchain_ollama import Ollama
from langchain.tools import tool
from dotenv import load_dotenv
import pyodbc
import requests
import json

# 載入 .env 檔案
load_dotenv()

# --- 設定 ---
OLLAMA_BASE_URL = "http://localhost:11434"
MODEL_NAME = "deepseek-coder:33b-instruct" 
# 設定專案根目錄位置
PROJECT_ROOT = os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'CSharp_Project')

# 從 .env 讀取設定
GITLAB_URL = os.getenv("GITLAB_URL")
GITLAB_PAT = os.getenv("GITLAB_PAT")
SQL_SERVER = os.getenv("SQL_SERVER")

# 初始化 Flask
app = Flask(__name__)

# 用來暫存當前操作的 GitLab Project ID
current_project_id = None

# --- 工具定義 (Tools) ---

@tool
def create_gitlab_project(name: str, description: str = "", visibility: str = "private") -> str:
    """
    使用 GitLab API 創建新專案。必須在開始新功能開發前調用此工具。
    成功後會自動將本地 Git remote 設定為新專案的 URL。
    name: 專案名稱 (如 'My-App')。
    """
    global current_project_id
    if not GITLAB_PAT or not GITLAB_URL:
        return "錯誤：缺少 GitLab PAT 或 URL。"

    url = f"{GITLAB_URL}/api/v4/projects"
    headers = {'Private-Token': GITLAB_PAT, 'Content-Type': 'application/json'}
    data = {'name': name, 'description': description, 'visibility': visibility, 'namespace_id': 1} # 預設 namespace 1 (root)
    
    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        project_info = response.json()
        current_project_id = str(project_info['id'])
        repo_url = project_info['http_url_to_repo']
        
        # 更新本地 Git Remote
        try:
            subprocess.run(['git', 'remote', 'set-url', 'origin', repo_url], cwd=PROJECT_ROOT, check=True, capture_output=True)
        except subprocess.CalledProcessError:
            try:
                subprocess.run(['git', 'remote', 'add', 'origin', repo_url], cwd=PROJECT_ROOT, check=True, capture_output=True)
            except:
                pass # 忽略錯誤，可能 remote 已存在
        
        return f"專案創建成功 ID: {current_project_id}, URL: {repo_url}"
    except Exception as e:
        return f"創建專案失敗: {e}"

@tool
def execute_local_git_command(command: str) -> str:
    """執行本地 Git 命令 (如 'add .', 'commit -m "msg"'). 不含 push。"""
    try:
        result = subprocess.run(['git'] + command.split(), cwd=PROJECT_ROOT, capture_output=True, text=True, check=True)
        return f"Git 執行成功: {result.stdout}"
    except subprocess.CalledProcessError as e:
        return f"Git 錯誤: {e.stderr}"

@tool
def push_to_gitlab_remote(branch_name: str) -> str:
    """執行 'git push origin <branch>' 推送至遠端。需先 Commit。"""
    try:
        result = subprocess.run(['git', 'push', 'origin', branch_name], cwd=PROJECT_ROOT, capture_output=True, text=True, check=True)
        return f"Push 成功: {result.stdout}"
    except subprocess.CalledProcessError as e:
        return f"Push 失敗: {e.stderr}"

@tool
def write_file_to_project(filepath: str, content: str) -> str:
    """在 C# 專案中寫入檔案。filepath 為相對路徑。"""
    full_path = os.path.join(PROJECT_ROOT, filepath)
    os.makedirs(os.path.dirname(full_path), exist_ok=True)
    try:
        with open(full_path, 'w', encoding='utf-8') as f:
            f.write(content)
        return f"寫入成功: {filepath}"
    except Exception as e:
        return f"寫入失敗: {e}"

@tool
def create_gitlab_merge_request(title: str, source_branch: str, target_branch: str = "main") -> str:
    """在 GitLab 創建 Merge Request。需在 Push 後調用。"""
    if not GITLAB_PAT or not current_project_id:
        return "錯誤：缺少 PAT 或尚未創建專案 (無 Project ID)。"

    url = f"{GITLAB_URL}/api/v4/projects/{current_project_id}/merge_requests"
    headers = {'Private-Token': GITLAB_PAT, 'Content-Type': 'application/json'}
    data = {'source_branch': source_branch, 'target_branch': target_branch, 'title': title}
    
    try:
        response = requests.post(url, headers=headers, json=data)
        response.raise_for_status()
        return f"MR 創建成功: {response.json()['web_url']}"
    except Exception as e:
        return f"MR 創建失敗: {e}"

@tool
def execute_sql_script(sql_query: str) -> str:
    """連接 SQL Server 執行查詢。"""
    if not SQL_SERVER: return "錯誤：未設定 SQL_SERVER。"
    conn_str = f"Driver={{ODBC Driver 17 for SQL Server}};Server={SQL_SERVER};Database=master;Trusted_Connection=yes;"
    try:
        conn = pyodbc.connect(conn_str)
        cursor = conn.cursor()
        cursor.execute(sql_query)
        if sql_query.strip().upper().startswith('SELECT'):
            rows = cursor.fetchall()
            conn.close()
            return f"查詢結果: {rows}"
        conn.commit()
        conn.close()
        return "SQL 執行成功。"
    except Exception as e:
        return f"SQL 錯誤: {e}"

# --- Agent 初始化 ---
def create_agent():
    llm = Ollama(model=MODEL_NAME, base_url=OLLAMA_BASE_URL)
    tools = [create_gitlab_project, execute_local_git_command, push_to_gitlab_remote, write_file_to_project, create_gitlab_merge_request, execute_sql_script]
    
    system_prompt = (
        "您是 C# 開發 Agent。請根據指令自主調用工具完成任務。"
        "若需要新專案，請務必先調用 create_gitlab_project。"
        "標準流程：建專案 -> 寫檔 -> Git Add/Commit -> Git Push -> 建立 MR。"
    )
    
    prompt = ChatPromptTemplate.from_messages([
        ("system", system_prompt),
        ("user", "{input}"),
        ("placeholder", "{agent_scratchpad}")
    ])
    
    agent = create_tool_calling_agent(llm, tools, prompt)
    return AgentExecutor(agent=agent, tools=tools, verbose=True)

agent_executor = create_agent()

# --- API Route ---
@app.route('/run_task', methods=['POST'])
def run_task():
    data = request.json
    user_input = data.get('prompt')
    if not user_input: return jsonify({"status": "error"}), 400
    try:
        response = agent_executor.invoke({"input": user_input})
        return jsonify({"status": "success", "result": response['output']})
    except Exception as e:
        return jsonify({"status": "error", "message": str(e)}), 500

if __name__ == '__main__':
    print(f"Agent 啟動於 C# 專案路徑: {PROJECT_ROOT}")
    app.run(host='127.0.0.1', port=5000)