"添加前端模板和运行代码模块"

2026-06-01 13:43:09 +08:00
parent 24045274ad
commit 8092c4b1f8
587 changed files with 99761 additions and 0 deletions
--- a/qiming-run_code_rmcp/README_zh.md
+++ b/qiming-run_code_rmcp/README_zh.md
@@ -0,0 +1,335 @@
+# MCP 代码执行工具
+
+一个基于 Rust 的工具，提供命令行界面和 MCP（Model Context Protocol）服务器，用于在隔离环境中执行 JavaScript、TypeScript 和 Python 代码。
+
+**项目仓库：** <https://github.com/nuwax-ai/run_code_rmcp>
+
+[English](./README.md) | 中文
+
+## 功能特点
+
+- 在隔离环境中执行 JavaScript、TypeScript 和 Python 代码
+- **JavaScript/TypeScript**：由 Deno 运行时驱动
+- **Python**：由 `uv` 驱动，支持自动依赖管理
+- 使用 blake3 哈希自动缓存代码，加快重复执行速度
+- 支持 JavaScript 的 ESM 和 CommonJS 模块
+- 自动解析和安装 Python 依赖
+- 独立的日志捕获和执行结果处理
+- 提供命令行工具（`run_code_rmcp`）和 MCP 服务器（`script_runner`）两种使用方式
+
+## 安装方法
+
+### 安装命令行工具
+
+```bash
+# 克隆仓库
+git clone https://github.com/nuwax-ai/run_code_rmcp.git
+cd run_code_rmcp
+
+# 安装命令行工具 (run_code_rmcp)
+cargo install --path .
+
+# 或同时安装命令行工具和 MCP 服务器
+cargo install --path . --features mcp
+cargo install --path . --bin script_runner --features mcp
+```
+
+### 系统要求
+
+- **Rust**：1.85 或更高版本（用于构建）
+- **Deno**：JavaScript/TypeScript 执行必需
+- **uv**：Python 执行和依赖管理必需
+
+安装 Deno：
+```bash
+curl -fsSL https://deno.land/install.sh | sh
+```
+
+安装 uv：
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+## 使用方法
+
+### 命令行工具：run_code_rmcp
+
+`run_code_rmcp` 命令允许直接从命令行执行代码。
+
+#### 基本语法
+
+```bash
+run_code_rmcp [选项] <命令>
+```
+
+**选项：**
+- `--show-logs`：显示执行日志
+- `--clear-cache`：执行前清除缓存
+- `--use-mcp`：使用 MCP SDK 集成（需要 mcp feature）
+
+**命令：**
+- `js`：执行 JavaScript 代码
+- `ts`：执行 TypeScript 代码
+- `python`：执行 Python 代码
+- `clear-cache`：清除缓存文件
+
+#### 执行 JavaScript/TypeScript
+
+```bash
+# 执行 JavaScript 文件
+run_code_rmcp --show-logs js -f fixtures/test_js.js
+
+# 带参数执行
+run_code_rmcp --show-logs js -f fixtures/test_js_params.js -p '{"name":"User"}'
+
+# 执行 TypeScript
+run_code_rmcp --show-logs ts -f fixtures/test_ts.ts
+
+# 执行内联代码
+run_code_rmcp js -c "function handler() { return 'Hello!'; }"
+```
+
+#### 执行 Python
+
+```bash
+# 执行 Python 文件
+run_code_rmcp --show-logs python -f fixtures/test_python.py
+
+# 带参数执行
+run_code_rmcp --show-logs python -f fixtures/test_python_params.py -p '{"a":10, "b":20}'
+
+# 执行内联代码
+run_code_rmcp python -c "def handler(): return 'Hello from Python!'"
+```
+
+#### 缓存管理
+
+```bash
+# 清除所有缓存
+run_code_rmcp clear-cache --language all
+
+# 清除特定语言的缓存
+run_code_rmcp clear-cache --language python
+run_code_rmcp clear-cache --language js
+run_code_rmcp clear-cache --language ts
+
+# 执行前清除缓存
+run_code_rmcp --clear-cache js -f fixtures/test_js.js
+```
+
+### 作为 Rust 库使用
+
+```toml
+[dependencies]
+run_code_rmcp = { git = "https://github.com/nuwax-ai/run_code_rmcp.git" }
+```
+
+```rust
+use run_code_rmcp::{CodeExecutor, LanguageScript};
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // 执行 JavaScript
+    let js_result = CodeExecutor::execute_with_params_compat(
+        "function handler() { return {success: true}; }",
+        LanguageScript::Js,
+        None
+    ).await?;
+
+    // 执行 Python
+    let py_result = CodeExecutor::execute_with_params_compat(
+        "def handler(): return {'success': True}",
+        LanguageScript::Python,
+        None
+    ).await?;
+
+    Ok(())
+}
+```
+
+### MCP 服务器：script_runner
+
+`script_runner` 是一个 MCP 服务器，为 AI 助手提供代码执行工具。
+
+#### 启动服务器
+
+```bash
+# 启动 MCP 服务器
+script_runner
+
+# 启用详细日志
+script_runner --verbose
+```
+
+服务器通过 stdio 通信，等待 MCP 协议的 JSON 请求。
+
+#### 可用工具
+
+MCP 服务器提供以下工具：
+
+1. **run_javascript** - 执行 JavaScript 代码
+2. **run_typescript** - 执行 TypeScript 代码
+3. **run_python** - 执行 Python 代码
+
+每个工具接受：
+- `code`（字符串）：要执行的代码
+- `params`（对象，可选）：传递给 handler 函数的参数
+
+#### 与 AI 助手集成
+
+添加到你的 MCP 客户端配置（如 Claude Desktop）：
+
+```json
+{
+  "name": "script-runner",
+  "command": "script_runner",
+  "transport": "stdio"
+}
+```
+
+## 代码结构
+
+### Handler 函数
+
+脚本应定义一个返回结果的 handler 函数。
+
+#### JavaScript/TypeScript
+
+支持 `main` 和 `handler` 函数（main 优先）：
+
+```javascript
+// 这个函数优先级更高
+function main(input) {
+    console.log("使用 main 处理:", input);
+    return { result: "Hello from main!" };
+}
+
+// 如果没有定义 main，则使用这个函数
+function handler(input) {
+    console.log("使用 handler 处理:", input);
+    return { result: "Hello from handler!" };
+}
+```
+
+也支持 ESM 模块：
+
+```javascript
+import { serve } from "https://deno.land/std/http/server.ts";
+
+function handler(input) {
+    return { message: "ESM works!" };
+}
+```
+
+#### Python
+
+支持 `handler` 和 `main` 函数（handler 优先）：
+
+```python
+import pandas as pd
+
+# 这个函数优先级更高
+def handler(args):
+    print(f"处理中: {args}")
+    data = pd.DataFrame({"a": [1, 2, 3]})
+    return {"result": data.to_dict()}
+
+# 如果没有定义 handler，则使用这个函数
+def main(args):
+    return {"result": "使用 main 代替"}
+```
+
+### 参数传递
+
+参数会传递给 handler 函数：
+
+```bash
+run_code_rmcp js -f script.js -p '{"name": "User", "count": 42}'
+```
+
+在代码中：
+```javascript
+function handler(input) {
+    // input = { name: "User", count: 42 }
+    return `Hello ${input.name}, count: ${input.count}`;
+}
+```
+
+### Python 依赖
+
+Python 依赖会被自动检测并安装：
+
+```python
+import requests
+import pandas as pd
+
+def handler(args):
+    # 依赖会通过 uv 自动安装
+    response = requests.get("https://api.example.com")
+    data = pd.DataFrame(response.json())
+    return data.to_dict()
+```
+
+### 日志捕获
+
+所有控制台输出都会与返回值分开捕获：
+
+```javascript
+console.log("这是日志");
+console.log("这也是日志");
+
+function handler() {
+    return "这是结果";
+}
+```
+
+结果：
+```json
+{
+  "logs": ["这是日志", "这也是日志"],
+  "result": "这是结果",
+  "error": null
+}
+```
+
+## 开发
+
+```bash
+# 构建
+cargo build
+
+# 使用 cargo 运行
+cargo run -- --show-logs js -f fixtures/test_js.js
+
+# 运行测试
+cargo test
+
+# 使用 mcp feature 构建
+cargo build --features mcp
+
+# 使用 cargo 运行 MCP 服务器
+cargo run --bin script_runner --features mcp
+```
+
+## 环境预热
+
+项目包含预热函数来缓存常用依赖：
+
+```rust
+use run_code_rmcp::warm_up_all_envs;
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    // 预安装常用的 Python 和 JS/TS 依赖
+    warm_up_all_envs(None, None, None, None).await?;
+    Ok(())
+}
+```
+
+## 待办事项
+
+- [ ] TTS（文本转语音）功能 - 目前存在已知问题
+
+## 许可证
+
+本项目采用 Apache License 2.0 发布。详见根目录的 `LICENSE` 与 `NOTICE` 文件。