JinDaGe - ruchy MCP Details

article

README

🚀 ruchy

ruchy 是一种用于数据科学和科学计算的现代编程语言，具备自托管编译器、全面的工具集以及企业级的质量标准。

🚀 快速开始

启动交互式 REPL

ruchy

运行 Ruchy 脚本

ruchy script.ruchy
# 或者显式指定
ruchy run script.ruchy

编译为生产二进制文件

ruchy compile script.ruchy -o myapp

格式化代码

ruchy fmt src/

运行测试

ruchy test tests/

✨ 主要特性

自托管编译器：用 Rust 编写，具备完整的自举能力。
交互式 REPL：高级 REPL，支持语法高亮和自动补全。
WebAssembly 支持：可编译为 WASM，用于浏览器和边缘设备部署。
Notebook 集成：支持类似 Jupyter 的 Notebook，并带有测试框架。
类型系统：支持双向类型检查和类型推断。
包管理：通过 ruchy add 与 Cargo 集成，可使用超过 140K 个 crate。
质量优先：遵循丰田生产方式原则，代码达到 PMAT A+ 标准。
内存安全：生成的代码无不安全代码，所有代码线程安全。
Rust 并发：支持与 Rust 相同的并发机制，包括线程、async/await 和通道。

📦 安装指南

从 crates.io 安装

cargo install ruchy

安装支持 MCP 服务器的版本

cargo install ruchy --features mcp

从源代码构建

git clone https://github.com/paiml/ruchy
cd ruchy
cargo build --release

💻 使用示例

基础用法

// 变量
let x = 42
let name = "Ruchy"
println(f"Hello, {name}! x = {x}")

// 函数
fun add(a, b) {
    a + b
}
let result = add(10, 20)
println(f"10 + 20 = {result}")

// 模式匹配
let value = Some(5)
match value {
    Some(x) => println(f"Got {x}"),
    None => println("Nothing"),
}

// 集合
let numbers = [1, 2, 3, 4, 5]
println(f"Numbers: {numbers:?}")

高级用法 - 包管理

# 创建新的 Ruchy 项目并集成 Cargo
ruchy new my_project

# 从 crates.io 添加依赖
cd my_project
ruchy add serde
ruchy add tokio@1.0

# 添加开发依赖
ruchy add --dev proptest

# 构建项目（自动将 .ruchy 文件转译为 .rs）
ruchy build
ruchy build --release

# 运行项目
cargo run

高级用法 - DataFrame 数据科学特性

// 创建 DataFrame（通过 polars-rs 后端）
let df = dataframe::from_columns(vec![
    ("age", vec![25, 30, 35]),
    ("score", vec![95, 87, 92])
]).unwrap();

// 支持的操作（经过 200K+ 属性测试）
// - df.select("column_name")
// - df.filter(predicate)
// - df.sort_by("column", descending)
// - df.groupby("column")
// - df.sum(), mean(), min(), max(), std(), var()
// - df.join(other_df, "key_column")

📚 详细文档

语法实现状态

100% 完成 - 所有 89/89 个语法特性均已实现并验证（v3.94.0+）。

Ruchy 已实现全面的语法覆盖并进行了综合验证：

handler_expr (SPEC-001-J)：支持模式匹配的效果处理程序 - handle expr with { operation => body }
expression_roundtrip：通过 1,536+ 个属性测试用例验证了解析器/格式化器的等价性。

验证结果：

三种模式验证：26 个测试（解释器、转译、编译模式）
属性测试：11 个测试，包含 1,536+ 个随机测试用例
核心工具验证：10 个测试，验证了所有核心工具（检查、 lint、AST、格式化、运行、转译、编译、测试、覆盖率）
总计：47+ 个综合验证测试

所有语法特性在所有执行模式和工具中均可正常工作。完整规范请参阅 grammar/ruchy-grammar.yaml。

MCP 服务器

Ruchy 提供了一个模型上下文协议（MCP）服务器，该服务器向 Claude 和其他 MCP 客户端提供代码分析、评分、 lint 和转译功能。

安装

# 安装支持 MCP 的 Ruchy
cargo install ruchy --features mcp

配置

将以下内容添加到你的 Claude Desktop 配置文件中（macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "ruchy": {
      "command": "ruchy",
      "args": ["mcp"]
    }
  }
}

可用工具

Ruchy MCP 服务器提供 7 种工具：

ruchy-score：使用统一的 0.0 - 1.0 评分系统分析代码质量
ruchy-lint：实时代码 lint 检查，并提供自动修复建议
ruchy-format：格式化 Ruchy 源代码，支持可配置的样式
ruchy-analyze：全面的代码分析，包括 AST、指标和洞察
ruchy-eval：安全地评估 Ruchy 表达式
ruchy-transpile：将 Ruchy 代码转译为 Rust 代码
ruchy-type-check：对 Ruchy 表达式进行类型检查

使用方法

# 启动 MCP 服务器（通常由 Claude Desktop 调用）
ruchy mcp --verbose

更多详细信息，请参阅 docs/mcp-registry-publish.md。

CLI 命令

核心命令

ruchy - 启动交互式 REPL（无参数，类似 Deno 的用户体验）
ruchy <file> - 直接执行 Ruchy 脚本（立即解释执行）
ruchy run <file> - 执行 Ruchy 脚本（直接执行的别名）
ruchy -e "<code>" - 直接评估代码（例如：ruchy -e "println(1+1)"）
ruchy compile <file> - 编译为独立二进制文件
ruchy fmt <path> - 格式化代码（支持 --check 标志）

WebAssembly 相关命令

ruchy wasm compile <input> -o <output> - 编译为 WASM
ruchy wasm validate <module> - 验证 WASM 模块
ruchy wasm run <module> - 执行 WASM 模块

WASM 分发（v3.99.2+）： Ruchy 提供预构建的 WASM 二进制文件，用于浏览器和边缘设备部署：

# 构建 WASM 包（供维护者使用）
wasm-pack build --target web --no-default-features --features wasm-compile

# WASM 工件位置：
# - pkg/ruchy_bg.wasm (~3.1MB 优化后)
# - pkg/ruchy.js (JavaScript 绑定)
# - pkg/ruchy_bg.wasm.d.ts (TypeScript 定义)

浏览器使用示例：

<script type="module">
  import init, { WasmRepl } from './ruchy.js';

  await init();
  const repl = new WasmRepl();
  const result = repl.eval('1 + 2');
  console.log(result); // "3"
</script>

注意：WASM 构建不包含 HTTP 和文件 I/O 操作（浏览器沙箱中不可用）。

开发服务器

Ruchy 提供了一个一流的开发服务器，支持热重载、WASM 编译和优雅关闭（v3.105.0+）。

基本用法：

# 在端口 8080 上提供当前目录的服务
ruchy serve

# 在自定义端口上提供特定目录的服务
ruchy serve ./dist --port 3000

# 启用监视模式（文件更改时自动重启）
ruchy serve --watch

# 启用 WASM 热重载（保存 .ruchy 文件时自动编译为 .wasm）
ruchy serve --watch --watch-wasm

高级特性：

# 启用所有特性的完整开发模式
ruchy serve \
  --watch \                # 文件更改时自动重启
  --watch-wasm \           # 保存时将 .ruchy 文件编译为 .wasm
  --debounce 200 \         # 防抖延迟（毫秒，默认值：300）
  --verbose \              # 显示详细日志
  --pid-file server.pid    # 用于进程管理的 PID 文件

# 输出示例：
#   🚀 Ruchy Dev Server v3.105.0
#
#   ➜  Local:   http://127.0.0.1:8080
#   ➜  Network: http://192.168.1.100:8080
#   📁 Serving: ./dist
#   👀 Watching: ./dist/**/*
#   🦀 WASM: Hot reload enabled for .ruchy files
#
#   Ready Press Ctrl+C to stop

特性说明：

热重载：文件更改时自动重启服务器（可配置防抖）
WASM 编译：保存 .ruchy 文件时自动编译为 .wasm
优雅关闭：使用 Ctrl+C 进行干净的关闭（无需 kill -9）
网络访问：显示本地和网络 URL，方便移动测试
PID 管理：基于 RAII 的 PID 文件，自动清理
美观的用户体验：类似 Vite 的彩色输出和状态指示器
高性能：多线程异步运行时，优化的 TCP 设置

WASM 热重载工作流程：

# 1. 启动支持 WASM 监视的开发服务器
ruchy serve --watch --watch-wasm

# 2. 编辑 .ruchy 文件
# 保存 main.ruchy 时：
#   📝 Changed: main.ruchy
#   🦀 Compiling: main.ruchy
#   ✅ Compiled: main.wasm
#   ↻ Restarting server...

# 3. 浏览器自动重新加载新的 WASM

生产部署：

# 构建优化的 WASM 文件
ruchy wasm compile *.ruchy -o dist/ --opt-level 3

# 提供生产构建的服务（无监视模式）
ruchy serve ./dist --port 8080

Notebook 相关命令

ruchy notebook - 在 http://localhost:8080 上启动交互式 Notebook 服务器
ruchy notebook test <file> - 测试 Notebook 并生成覆盖率报告
ruchy notebook convert <input> <output> - 转换 Notebook 格式

Notebook 特性（v3.75.0+）：

状态持久化：变量和函数在单元格执行之间保持持久（SharedRepl）
线程安全：基于 Arc 的并发访问，使用 Mutex 同步
Markdown 支持：完整的 Markdown 渲染，具备 XSS 保护
加载/保存：基于 JSON 的 .rnb Notebook 格式
API 访问：RESTful API 位于 /api/execute、/api/render-markdown、/api/notebook/load、/api/notebook/save

测试相关命令

ruchy test run <path> - 运行测试，可选择生成覆盖率报告
ruchy test report - 生成测试报告（HTML/JSON/JUnit）

项目结构

ruchy/
├── src/
│   ├── frontend/       # 解析器和 AST
│   ├── middleend/      # 类型系统和推断
│   ├── backend/        # 代码生成和转译
│   ├── runtime/        # REPL 和解释器
│   ├── lsp/           # 语言服务器协议
│   └── wasm/          # WebAssembly 支持
├── tests/             # 集成测试
├── examples/          # 示例程序
└── docs/             # 文档

质量标准

本项目遵循严格的质量工程实践：

测试覆盖率：行覆盖率 46.41%，分支覆盖率 50.79%
变异测试：通过 cargo-mutants 实现 80% 以上的变异覆盖率（Sprint 8 目标）
复杂度限制：所有函数的圈复杂度 ≤10
零技术债务：不允许有 TODO/FIXME 注释
PMAT A+ 等级：通过自动化质量门强制实施
TDD 实践：采用测试优先的开发方法
线程安全：基于 Arc 的并发机制，经过 10K+ 次属性测试（v3.75.0+）
端到端测试：通过预提交钩子强制执行 21/21 个 Playwright 测试

变异测试策略

我们使用 cargo-mutants v25.3.1 进行实证测试质量验证：

增量测试：逐文件进行变异测试（5 - 30 分钟，而基线测试需 10 小时以上）
基于证据：测试针对实证分析确定的特定变异
模式识别：可复用的测试策略（匹配分支、边界、桩）
质量指标：所有模块的变异覆盖率目标为 80% 以上

# 对特定文件运行变异测试
cargo mutants --file src/frontend/parser/core.rs --timeout 300

# 对模块运行变异测试
cargo mutants --file "src/frontend/parser/*.rs" --timeout 600

# 查看变异测试结果
make mutation-test

开发相关

基本开发命令

# 运行测试
make test

# 检查覆盖率
make coverage

# 运行质量检查
make lint

# 构建文档
make doc

RuchyRuchy 调试工具

Ruchy 集成了 RuchyRuchy 调试工具包，提供高级调试功能：

源映射：Ruchy 到 Rust 转译调试的 1:1 行映射
时间旅行调试：记录 - 回放引擎，支持向后步进执行
性能验证：自动检测回归（验证时间 <6s）

设置方法：

# 将 ruchyruchy 克隆到同级目录
git clone https://github.com/paiml/ruchyruchy ../ruchyruchy

# 通过预提交钩子自动运行验证
# 手动验证：
./scripts/validate-debugging-tools.sh

预提交集成：每次提交时自动验证调试工具（3 项检查，总时间 <6s）。

详细文档请参阅 RuchyRuchy README。

WebAssembly 质量保证框架

项目包含一个全面的 WebAssembly 质量保证框架 v3.0，包含 4 个验证阶段：

# 运行完整的 QA 验证
make qa-framework

# 单个阶段
make qa-foundation    # 覆盖率和基础设施
make qa-browser       # 浏览器测试和 WASM 验证
make qa-quality       # 安全和复杂度分析
make qa-optimization  # 性能和回归测试

# 快速质量检查
make qa-security      # 安全分析
make qa-complexity    # 复杂度分析
make qa-dashboard     # 交互式质量仪表盘

# 查看所有 QA 命令
make qa-help

质量目标：

90% 分支覆盖率
每个函数的圈复杂度 ≤10
零安全漏洞
优化后的 WASM 二进制文件 <500KB
性能回归容忍度 <5%

文档资源

🔧 技术细节

安全性与并发

零不安全策略：Ruchy 从不生成不安全的 Rust 代码（GitHub Issue #132）。

默认线程安全

// 顶级可变变量自动线程安全
let mut counter = 0;

fun increment() {
    counter = counter + 1;  // ✅ Thread-safe (LazyLock<Mutex<T>>)
}

与 Rust 等效的并发机制

Ruchy 支持与 Rust 完全相同的并发机制 - 无抽象，直接 1:1 映射：

// 线程（与 Rust 相同）
let handle = std::thread::spawn(|| {
    println!("Hello from thread!");
    42
});
let result = handle.join().unwrap();

// Async/await (tokio)
async fun fetch_data(url: String) -> Result<String, Error> {
    let response = reqwest::get(url).await?;
    response.text().await
}

// 共享状态 (Arc<Mutex<T>>)
use std::sync::{Arc, Mutex};
let data = Arc::new(Mutex::new(vec![]));

// 通道 (mpsc)
use std::sync::mpsc;
let (tx, rx) = mpsc::channel();

安全保证：

✅ 生成的代码无不安全代码
✅ 所有全局变量使用 LazyLock<Mutex<T>>（线程安全）
✅ 内存安全（Rust 所有权 + 借用检查器）
✅ 无数据竞争（Send/Sync 特性强制）

详细文档请参阅 docs/CONCURRENCY.md。

DataFrame 数据科学特性

状态：DataFrame 实现约完成 80%，通过 200K+ 属性测试证明正确性

已实现的特性 ✅：

✅ DataFrame 创建和基本操作（通过 polars-rs）
✅ CSV 读写
✅ 谓词过滤（100K 属性测试 - 数学证明正确性）
✅ 分组聚合操作
✅ 聚合函数：sum、count、mean、min、max、std、var
✅ 排序（升序/降序，100K 属性测试 - 验证稳定排序）
✅ 连接（内连接）
✅ 导出：to_csv()、to_json()
✅ 选择和切片：select()、slice()、head()、tail()
✅ 元数据：shape()、columns()、rows()

测试质量：

137 个单元测试通过
200,000+ 次属性测试迭代（过滤 + 排序）
所有函数复杂度 ≤10（符合丰田生产方式）
全面的边界情况覆盖

示例 API（来自测试套件）：

// 注意：DataFrame API 主要在 Rust 级别进行测试
// 高级 Ruchy 语法正在开发中

// 创建 DataFrame（通过 polars-rs 后端）
let df = dataframe::from_columns(vec![
    ("age", vec![25, 30, 35]),
    ("score", vec![95, 87, 92])
]).unwrap();

// 支持的操作（经过 200K+ 属性测试）
// - df.select("column_name")
// - df.filter(predicate)
// - df.sort_by("column", descending)
// - df.groupby("column")
// - df.sum(), mean(), min(), max(), std(), var()
// - df.join(other_df, "key_column")

正在进行的工作：

用于 DataFrame 操作的高级 Ruchy 语法
高级连接类型（左连接、右连接、外连接）
多列分组
绘图集成

完整测试示例请参阅 tests/dataframe_*_properties.rs。

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

⚠️ 重要提示

Ruchy v3.94.0 不适合生产环境。虽然它展示了卓越的工程质量（TDG A-，3,987 个测试，极端 TDD），但缺乏生产使用所需的生态系统成熟度、安全审计和稳定性保证。预计达到生产就绪的时间为 18 - 30 个月。详细分析请参阅 docs/PRODUCTION-READINESS-ASSESSMENT.md。

适用场景：研究、教育、原型设计、实验 不适用场景：生产服务、关键任务系统、面向公众的产品

致谢

基于 Rust 和出色的 Rust 生态系统构建
受 Python 的表达性和 Rust 的安全性启发
借鉴丰田生产方式和 PMAT 方法论的质量实践

联系信息

作者：Noah Gift
仓库地址：github.com/paiml/ruchy
问题反馈：GitHub Issues