2025年12月12日 星期五

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。

張貼者： Frankie 於 中午12:30 0 意見
標籤： , ,

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)
張貼者： Frankie 於 中午12:30 0 意見

2025年11月27日 星期四

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)
張貼者： Frankie 於 中午12:01 0 意見
標籤： , , , , , , ,

2024年9月9日 星期一

git - 修改某個 commit 點的內容

上次只是需要改之前某個點的修改訊息，

這次連 commit 的內容都要改！！！

還好也是有辦法可以修改的。

 1.首先先把目前的內容 Stash 起來。

$ cd [專案目錄]
$ git stash

2.接著將 HEAD 移動到你要修改的點。

例如要修改B點，所以要先取得A的 commit id，

A-B-C-D-E-F-G-stash

$ git rebase [A commit id] --interactive

3.然後會出現如下的畫面，然後將 B 的 pick 改成 edit 


接下來畫面會顯示如下，

提示你可以開始 amend 你的點，

做完之後再 rebase --continue 就可以了。



參考：【[Git] 修改之前某次 commit 日志和内容】

張貼者： Frankie 於 上午11:35 0 意見
標籤：

2024年8月29日 星期四

git - 修改從最後一個 commit 點到之前某個 commit 點的 commit 訊息

有需求需要將一整條的 commit message 修改，
然後又不想建一個新的 branch 、 cherry pick，
這時候可以下指令修改。

過程如下：
指令是 rebase ， 
HEAD~3 表示從 HEAD 的位置開始的三個 commit 點，包含 HEAD 的 commit 點。
$ cd [專案目錄]
$ git rebase -i HEAD~3

將要修改的 commit 點的 pick 改成 reword。

提示：
  1. 按 i 進入編輯模式，編輯完後，按 Esc 離開編輯模式。
  2. 按:進入指令模式，在指令模式下輸入 wq。:


接著會一個一個跳出 reword 的 commit 點的 message 讓你修改，
修改方式如上面提示一樣。

全部都改完之後就算完成了。



張貼者： Frankie 於 上午11:28 0 意見
標籤：

2024年8月14日 星期三

SQL - 為何使用 CROSS APPLY

 其實我本人一直都是慣用標準的 SQL 語法，

因為在跨DB時的相容性高；

但難免需要改到其他人寫的 SQL ，

一直以來對於 CROSS APPLY 都很懷疑，

為何要寫 CROSS APPLY ？

今天花了點時間查證一下，

第一：

基本上 CROSS APPLY, OUTER APPLY 相等於 JOIN, LEFT JOIN，

但在需要 JOIN RETURN TABLE 的 UDF 時，

如果需要傳入其他 TABLE 的欄位當條件時就只能用 APPLY。

參考資料【理解 SQL Server 的 CROSS APPLY 和 OUTER APPLY 査詢 - 第 2 部分】

SELECT E.Id, E.Name, E.CountryName, TD.Name, E.CountryName

           FROM EMPLOYEE AS E

    CROSS APPLY GetDept(E.CountryName) TD

第二：

如果 JOIN 有複雜的條件的時候，

CROSS APPLY 的表現會比 JOIN 好，

參考資料【When should I use CROSS APPLY over INNER JOIN?】

CROSS APPLY works better on things that have no simple JOIN condition.

This one selects 3 last records from t2 for each record from t1:

SELECT  t1.*, t2o.*
FROM    t1
CROSS APPLY
        (
        SELECT  TOP 3 *
        FROM    t2
        WHERE   t2.t1_id = t1.id
        ORDER BY
                t2.rank DESC
        ) t2o

It cannot be easily formulated with an INNER JOIN condition.

You could probably do something like that using CTE's and window function:

WITH    t2o AS
        (
        SELECT  t2.*, ROW_NUMBER() OVER (PARTITION BY t1_id ORDER BY rank) AS rn
        FROM    t2
        )
SELECT  t1.*, t2o.*
FROM    t1
INNER JOIN
        t2o
ON      t2o.t1_id = t1.id
        AND t2o.rn <= 3

, but this is less readable and probably less efficient.

張貼者： Frankie 於 中午12:05 0 意見
標籤：
訂閱： 意見 (Atom)