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           # 长期记忆