GEMINI.md 主要內容

核心功能

• 默認使用 Persistent Kernel（use_kernel=True）
• 使用者說「重置」時用 reset_kernel()

對話開始檢查清單

1. kernel_status() - 確認 kernel 狀態
2. recall() - 載入長期記憶
3. list_files() - 瞭解現有資產

技術偏好

• 爬蟲優先用 requests + BeautifulSoup
• 開啟網頁用 webbrowser.open()

### kernel_server.py 說明
這是背景執行的 **Persistent Kernel 進程**，無需手動啟動：

┌──────────────────┐ socket ┌──────────────────┐ │ PyRunner_MCP.py │ ◄───────────► │ kernel_server.py │ │ (MCP Server) │ 127.0.0.1:9999 │ (Python Kernel) │ └──────────────────┘ └──────────────────┘ │ ▼ global_namespace = {} （變量都存在這裡）

** 安全防護（Auto-Safe Mode）**：
- **Unified Process Core**：所有子進程（Python/Pip/Shell）皆由統一核心驅動，強制輸出重定向與環境淨化。
- **Deadlock Immunity**：徹底解決 Windows 下因 Pipe Buffer 滿載或 DLL 鎖定導致的死鎖問題。
- **Auto Monkey Patch**：自動攔截 `yfinance` 等庫的多線程行為，確保 Kernel 穩定。

> 💡 **使用建議**
> 
> 現在推薦所有任務都使用 `use_kernel=True`（Direct Kernel Mode）。系統已內建防護，無需再擔心死鎖問題。

## ✨ 主要特性
### 核心特色：Persistent Kernel
類似 **Jupyter Notebook** 的體驗，但在命令列中：
- 載入 10GB 的 DataFrame 一次，後續分析不用重讀
- import 大型套件（pandas、torch）一次，後續執行秒開
- 變量、函數、類都持續存在
### 其他特性
- **執行 Python 代碼**：在持久化的 Kernel 中執行，變量跨多次執行保留
- **管理 Python 套件**：快速檢查、自動安裝依賴
- **語義化搜索腳本**：用描述和標籤找出之前寫的腳本
- **長期記憶**：記住你的偏好、專案背景、常用指令
- **執行 Shell 命令**：Git clone、pip install、系統指令

## 📦 安裝指南
### 安裝步驟
```bash
# 1. Clone 項目
git clone https://github.com/YOUR_USERNAME/PyRunner_MCP.git
cd PyRunner_MCP

# 2. 安裝依賴
pip install fastmcp psutil

💻 使用示例

基礎用法

# 第一次執行
你: 載入 sales.csv
AI: save_and_run("load.py", "import pandas as pd; df = pd.read_csv('sales.csv')", use_kernel=True)
✓ 成功

# 第二次執行（df 還在！）
你: 顯示前 5 行
AI: save_and_run("show.py", "print(df.head())", use_kernel=True)
✓ [顯示 DataFrame]

# 不用重讀 CSV！

高級用法

# 查看狀態
kernel_status()
# 🟢 KERNEL 狀態
# ├─ 運行時間: 15 分 32 秒
# ├─ 變量數量: 8 個
# └─ 記憶體使用: 45.2 MB

# 檢視變量
inspect_kernel_vars()
# 📦 KERNEL 變量（共 3 個）
# ├─ df (DataFrame, 15.2 MB)
# ├─ model (Sequential, 102.5 MB)
# └─ config (dict, 1.2 KB)

# 重置
reset_kernel()
# 🔄 Kernel 已重置，所有變量已清空

語義化搜索

search_workspace("PTT 爬蟲")
# → fetch_ptt.py (相關度:4) [crawler, ptt]
#   爬取 PTT 八卦版最新文章

📚 詳細文檔

為什麼需要這個？

2025 年的 AI 工具已經很強大

核心差異：Persistent Kernel

┌─────────────────────────────────────────────────────────────┐
│  Gemini CLI / Copilot          PyRunner MCP                 │
│  ─────────────────────          ────────────                │
│  每次執行 = 全新進程            變量跨執行保留                 │
│                                                             │
│  x = 100  ──執行──►  x 消失     x = 100  ──執行──►  x 還在   │
│  print(x) ──執行──►   錯誤      print(x) ──執行──►   100     │
└─────────────────────────────────────────────────────────────┘

功能對比

獨特優勢

1. stdout/stderr 重定向（不會卡住）

問題：執行 SSH 連接、ping 監控、網絡爬蟲等長時間任務時，原生工具可能因 pipe buffer 滿載而卡住。 PyRunner 解決方案：

# 輸出自動重定向到檔案，不會阻塞
stdout → temp/stdout.txt
stderr → temp/stderr.txt

適用場景：

• SSH 遠端執行（netmiko、paramiko）
• 網絡監控（ping、traceroute）
• 大量輸出的爬蟲任務
• 循環任務和 daemon

2. 套件檢查極速（微秒級）

# 直接在 MCP 進程內檢查，不啟動 subprocess
check_packages("pandas numpy torch")
# ✓ 已安裝: pandas, numpy
# ✗ 未安裝: torch

3. 記憶系統（結構化 JSON）

remember("使用者偏好 Black 格式化", category="preference")
remember("Project X 的 API: https://api.x.com", category="project")

recall("API")  # 只找相關記憶

4. Shell 命令淨化環境

run_shell("git clone https://github.com/xxx/yyy")

自動處理：

• GIT_TERMINAL_PROMPT=0（禁用互動提示）
• GIT_LFS_SKIP_SMUDGE=1（跳過大檔案）
• 統一工作目錄（BASE_DIR）

適用場景

適合 PyRunner MCP

• 數據分析：讀取 10GB CSV 一次，後續分析不用重讀
• 機器學習：載入模型一次，反覆測試推論
• 交互式開發：類 Jupyter Notebook 的 CLI 體驗
• 大量獨立腳本：用 metadata 管理和搜索

不適合（用原生工具更好）

• 完整專案開發（有 src/, tests/ 結構）→ Copilot @workspace
• 團隊協作、PR review、CI/CD → GitHub Copilot Workspace
• 多語言專案 → 原生 Gemini CLI

🛠️ 完整工具列表

🔧 技術細節

專案結構

PyRunner_MCP/
├── PyRunner_MCP.py       # MCP Server 主程式
├── kernel_server.py      # Persistent Kernel 進程
├── GEMINI.md             # AI 行為指南
├── workspace/            # 腳本儲存區
│   ├── *.py              # Python 腳本
│   └── *.meta.json       # Metadata（搜索用）
├── temp/                 # 暫存（stdout/stderr）
└── memory.json           # 長期記憶