simple-mcp-server

Simple 语言

Simple 是一门可自托管的语言及工具链，将易读的类 Python 表层语法与编译器集成测试、文档、架构规则和面向裸机的执行路径相结合。

该仓库的涵盖范围格外广泛：语言、编译器、解释器、加载器、测试运行器、文档生成、可追溯性工具、由 SDN 支持的项目数据库、编辑器工具，以及面向硬件的测试流程都整合在一起。

快速导航： 特色功能 | 功能状态 | 快速开始 | 语言基础 | 示例 | 编辑器插件 | 文档

---

特色功能

• 自托管的分阶段工具链：前端、类型分析、借用检查、后端、驱动程序、解释器和加载器的实际源码层都位于仓库中。
• 验证原生工作流：SSpec 测试、SPipe 运行器/文档生成流程、可执行文档 SDoctest、覆盖率、可追溯性检查和生成的规范文档，都是工具链的一部分，而非后加的功能。
• MDSOC 架构支持：虚拟胶囊、清单以及支持架构感知的仓库结构都是一等概念。
• 易于解析的宏系统：宏定义、展开、验证和卫生性都是编译器功能，而非令编辑器难以处理的文本替换。
• 面向数学的语法块：m{}、loss{} 和 nograd{} 是已实现的语法，支持解析、求值、五种渲染后端（文本、调试、Unicode、LaTeX、Markdown）以及编辑器集成（查询/LSP 悬停提示、VSCode 高亮/预览、Neovim 行内 Unicode 预览及隐藏显示）。基于 torch 的 C/LLVM 推广范围内，自动微分路径已完整实现。
• 由 SDN 支持的文本数据库：测试、待办事项、仪表板和其他项目元数据均通过仓库原生的 SDN 数据流存储。
• 多种执行路径：解释器、加载器、SMF/模块加载以及面向原生/LLVM 的编译路径共存于同一系统中。
• 面向裸机的构建与测试流程：QEMU、半主机、MMIO 邮箱、远程裸机流程以及由适配器支持的硬件通道（8 个权威通道）都已融入仓库。
• 支持工具的语言规则：Tree-sitter 集成、原始公共 API lint、可追溯性工具和语言统计都是平台的一部分。
• 各受支持界面共享 UI 契约：基于 HTTP 的统一测试协议（Protocol V1）使用 UITestClient 驱动 Web 后端和 TUI-Web 代理，共享 handle_test_request 处理器，并通过跨界面契约测试套件验证。契约：doc/04_architecture/shared_ui_contract.md

功能状态亮点

已实现且可放心宣传：

• SSpec 测试、SPipe 运行器／文档生成器、SDoctest、覆盖率、可追溯性检查和生成的规格文档
• SPipe 模拟策略：系统测试中禁止模拟、仅 HAL 模式和自定义模式
• 可自托管的分阶段编译器、解释器和加载器架构
• MDSOC 清单和面向架构的项目结构
• 带验证和卫生机制、便于解析器处理的宏
• Tree-sitter 大纲／查询工具
• 由 SDN 支持的项目、测试和待办数据库
• 原语公共 API lint 检查，以及语义包装器／单位类型模式
• 借用检查基础设施
• 监视模式和自动构建支持
• 基于 mmap 的加载器支持和可执行内存连接机制
• 裸机构建／测试连接机制，以及感知主机环境的远程裸机工作流
• 针对受支持 ABI 子集的 C/C++ 双向 SFFI：导出、导入、回调跳板、布局验证和往返证明测试

已实现，但最好附带限定说明：

• 对已声明的公共矩阵，LLVM 全系列闭环已完成：每一行 llvm-lib 和 llvm 后端均明确标记为 stable 或 unsupported，不存在含糊的中间状态。rust-llvm 仍是仅用于引导的种子路径，不属于公共系列的范围声明
• 对受支持的验证子集，Lean 验证工作流已完成：确定性 Lean 生成、证明产物清单、Lean/Lake 检查、缓存失效处理和验证状态报告。契约：doc/04_architecture/lean_verification_contract.md。报告：doc/09_report/lean_verification_complete_2026-04-04.md
• GC 和无 GC 运行时系列：5 个公共系列（common、nogc_sync_mut、nogc_async_mut、gc_async_mut、nogc_async_mut_noalloc），具备编译器边界强制执行、解释器警告和目标预设映射。支持矩阵：doc/04_architecture/runtime_family_support_matrix.md
• Web 后端和 TUI-web 代理之间共享 UI 契约（Protocol V1）：共享处理器、结构化错误模型、稳定元素 ID、跨界面契约套件——但这是共享测试协议，并非完整统一的 UI 渲染层
• 远程裸机执行有 8 条权威通道（3 条稳定通道 + 5 条感知主机环境的通道，其中包括 GHDL 半主机和邮箱模拟），但依赖硬件的通道仍需感知主机和开发板环境，并非普遍完备。通道矩阵：doc/08_tracking/lane_matrix.md

已在限定范围内实现：

• m{} / loss{} / nograd{} 已在推广的、基于 torch 的 C/LLVM 范围内完整实现，包括反向传播、分离输入失败处理和 nograd{} 恢复语义。其他后端仍暂缓支持
• AOP 提供基于谓词的切点（execution、within、attr）、确定性的 before/after/around 通知、作为默认后端的编译期织入，以及作用域内的运行时拦截。支持矩阵：doc/05_design/aop_support_matrix.md
• VHDL 后端可将有文档说明的、面向硬件的 Simple 子集编译为可综合的 VHDL-2008，并通过 GHDL 分析／展开进行验证。遇到不支持的构造时严格快速失败。两条 GHDL RV32 模拟通道已投入运行：半主机（基于 GDB，使用 ARM 半主机陷阱）和邮箱（不依赖调试器，MMIO 地址为 0x80FF0000，通过 ram_sentinel 收集结果）。支持矩阵：doc/04_architecture/vhdl_support_matrix.md。邮箱协议：doc/04_architecture/ghdl_rv32_mailbox_protocol.md 已实现：
• 主要源码和编译后的 CLI 界面已启用反空壳／反桩代码检查（simple lint、simple verify quality）。所有面向公众的验证套件（SFFI、T32 硬件、编译器／运行时／系统）现已通过检查。剩余欠账仅在延期处理的 OS／GPU／实验性领域——所有活跃界面均已清理完毕。

请参阅 doc/report/unique_features.md，了解基于证据的审计结果。

---

运行时系列

Simple 根据分配、可变性和并发需求，将标准库划分为不同的运行时系列：

系列	分配	可变性	异步	使用场景
common	堆（默认）	不可变	否	纯函数、数学、文本、编码
nogc_sync_mut	堆／arena／池	可变	否	文件 I/O、网络、FFI、数据库
nogc_async_mut	堆	可变	是	异步 I/O、线程、Actor、生成器
gc_async_mut	GC 管理	可变	是	GPU/CUDA、ML 流水线
nogc_async_mut_noalloc	仅栈	可变	是	裸机、嵌入式、RTOS

编译器会强制执行系列边界：在无 GC 上下文中导入 GC 模块会产生诊断警告。目标预设（Baremetal、Hosted、EmbeddedWithHeap）会自动将模块解析限制为兼容的系列。

高级用途：nogc_async_immut 提供持久数据结构，并支持无锁并发。

完整契约请参阅运行时系列支持矩阵，当前注意事项请参阅已知限制。

---

快速开始

安装

你将获得：

• 完整的 Simple 编译器和工具链源码
• 标准库和生成的规范手册
• 开发工具，包括 MCP 服务、LSP 和调试器界面

当前 Beta 版本请使用源码检出。该操作还会初始化文档和测试使用的示例及工具子模块：

git clone --recurse-submodules https://github.com/ormastes/simple.git
cd simple
export PATH="$PWD/bin:$PATH"
simple --version

对于已有的检出目录：

git submodule sync --recursive
git submodule update --init --recursive

注意： Rust 仍作为引导种子和宿主基础设施存在。只要仓库能够用 Simple 实现，产品编译器、库和工具的开发工作就应继续使用 Simple；不要将“纯 Simple”理解为“当前检出目录中没有 Rust 源码”。

源码规模

快照生成于 2026-04-23，统计了现有已跟踪的 .spl、.rs、.c、.h、.s、.S 和 .asm 文件。统计不包含空行和仅含注释的行；包含 examples/ 中的代码；不包含供应商和第三方源码。

语言	文件数	非注释代码行数	src/ 代码行数	examples/ 代码行数	test/ 代码行数	其他代码行数
Simple	13,286	1,780,334	887,121	158,796	712,254	22,163
Rust	1,633	411,106	409,852	11	0	1,243
C	158	73,854	14,953	58,859	36	6
汇编	60	4,758	1,554	3,173	31	0
总计	15,137	2,270,052	1,313,480	220,839	712,321	23,412

从源码构建（仅限开发者）

仅当你想修改运行时时才需要：

scripts/setup/setup.shs
bin/simple build bootstrap

封装脚本背后的直接命令：

src/compiler_rust/target/bootstrap/simple --version
bin/simple build bootstrap
sha256sum bootstrap/simple_stage2 bootstrap/simple_stage3

当前的引导流程和剩余的纯 Simple 自举说明，请参阅 doc/02_requirements/app/build/bootstrap.md 和 doc/03_plan/compiler/bootstrap/pure_simple_bootstrap_stage2_remaining_2026-05-04.md。

启用 GPU 支持进行构建

simple build --release --features=vulkan

编写你的第一个程序

# hello.spl
>>> fn main() -> i64:
...     0  # Entry point, returns exit code

# Run it
simple hello.spl
echo $?  # Prints: 0

---

CLI 用法

simple 命令的工作方式类似 Python：

Usage:
  simple                      Start interactive REPL
  simple <file.spl>           Run source file
  simple <file.smf>           Run compiled binary
  simple -c "code"            Run code string; statement snippets print only program output
  simple compile <src> [-o <out>]  Compile to SMF
  simple watch <file.spl>     Watch and auto-recompile

Build System (Self-Hosting):
  simple build                Build the project (debug)
  simple build --release      Release build (optimized)
  simple build --bootstrap    Bootstrap build (minimal 9.3MB)
  simple build test           Run all tests
  simple build coverage       Generate coverage reports
  simple build lint           Run linter (clippy)
  simple build fmt            Format code (rustfmt)
  simple build check          Run all quality checks
  simple build clean          Clean build artifacts
  simple build --help         Show all build options

Options:
  -h, --help     Show help
  -v, --version  Show version
  -c <code>      Run code string
  --gc-log       Enable verbose GC logging
  --gc=off       Disable garbage collection

示例

# Interactive REPL
simple
>>> 1 + 2
3
>>> x = 10
>>> x * 5
50
>>> exit

# Run a program
echo "main = 42" > hello.spl
simple hello.spl
echo $?  # Exit code: 42

# Compile to binary
simple compile hello.spl
simple hello.smf  # Run the compiled binary

# Watch mode (auto-recompile on changes)
simple watch app.spl

---

语言基础

变量和类型

# Variables - immutable by default, mutable with var
>>> x = 10
>>> x
10
>>> var y = 20
>>> y
20
>>> PI = 3.14159
>>> PI
3.14159

# Type inference works automatically
>>> count = 100
>>> count
100

# Basic types inferred
>>> a = 42
>>> a
42
>>> pi = 3.14159
>>> flag = true
>>> flag
true

# String interpolation default
>>> name = "world"
>>> msg = "Hello, {name}!"
>>> print msg
Hello, world!

控制流

# If/else with indentation
>>> var x = 5
>>> if x > 0:
...     print "positive"
... elif x < 0:
...     print "negative"
... else:
...     print "zero"
positive

# Loops
>>> for i in 0..3:
...     print i
0
1
2

>>> while x > 3:
...     x = x - 1
>>> x
3

函数

>>> fn add(a: i64, b: i64) -> i64:
...     a + b  # Implicit return

>>> fn greet(greeting: text):
...     print "Hello, {greeting}!"

# Function calls
>>> sum = add(1, 2)
>>> sum
3
>>> greet("Alice")
Hello, Alice!

# Lambdas with backslash
>>> double = \x: x * 2
>>> nums = [1, 2, 3, 4, 5]
>>> evens = nums.filter(\x: x % 2 == 0)
>>> evens
[2, 4]

结构体和类

# Structs (value types)
struct Point:
    x: f64
    y: f64

p = Point(x: 1.0, y: 2.0)

# Classes (reference types)
class Person:
    name: text
    age: i64

    fn greet():
        print "Hi, {self.name}!"

alice = Person(name: "Alice", age: 30)
alice.greet()

集合

# Arrays - short form (no val)
>>> nums = [1, 2, 3, 4, 5]
>>> first = nums[0]
>>> first
1

# Collection methods
>>> count = nums.len()
>>> count
5

# Dictionary (short form)
>>> scores = {"alice": 100, "bob": 85}
>>> alice_score = scores["alice"]
>>> alice_score
100

# Filter with lambda
>>> odds = nums.filter(\x: x % 2 == 1)
>>> odds
[1, 3, 5]
>>> big_nums = nums.filter(\x: x > 3)
>>> big_nums
[4, 5]

# Tuples
>>> pair = (1, "hello")
>>> num = pair.0
>>> num
1
>>> msg = pair.1
>>> msg
"hello"

# List comprehensions
>>> squared = [x * x for x in 0..5]
>>> squared
[0, 1, 4, 9, 16]
>>> evens = [x for x in nums if x % 2 == 0]
>>> evens
[2, 4]

单位类型（后缀字面量）

类型安全的单位可避免混用不兼容的值：

# Define measurement unit families with postfix syntax
unit length(base: f64):
    mm = 0.001, cm = 0.01, m = 1.0, km = 1000.0

unit velocity(base: f64) = length / time:
    mps = 1.0, kmph = 0.2777777777777778, mph = 0.44704
# The standards-backed catalog records km/h canonically as kilometre / hour
# with exact factor 5/18 relative to m/s.

# Define nominal wrappers with postfix syntax
newunit UserId: i64 as uid
newunit OrderId: i64 as oid

# Usage with postfix literals
height = 175_cm              # Length type
width = 10_cm + 5_mm         # Auto-converts to same base
speed = 200_kmph             # Velocity type
distance = 42_km             # Length type

# Type safety - compile error:
# bad = height + speed       # Error: can't add Length + Velocity

# Semantic IDs prevent mix-ups
user = 42_uid                # UserId
order = 100_oid              # OrderId
# wrong: UserId = 100_oid    # Error: OrderId ≠ UserId

# Computed units
travel_time = distance / speed    # Returns Time type
print("ETA: {travel_time.to_min()} minutes")

模式匹配

enum Shape:
    Circle(radius: f64)
    Rectangle(width: f64, height: f64)
    Square(side: f64)
    Triangle(base: f64, height: f64)

# Pattern matching with case syntax
fn area(s: Shape) -> f64:
    match s:
        case Circle(r):
            3.14159 * r * r  # Implicit return
        case Rectangle(w, h):
            w * h
        case Square(side):
            side * side
        case Triangle(b, h):
            0.5 * b * h

# Preferred arrow syntax (shorter)
fn perimeter(s: Shape) -> f64:
    match s:
        | Circle(r) -> 2.0 * 3.14159 * r
        | Rectangle(w, h) -> 2.0 * (w + h)
        | Square(side) -> 4.0 * side
        | Triangle(a, b, c) -> a + b + c

# Pattern matching with nil (not None)
fn get_radius(opt: Option<f64>) -> f64:
    match opt:
        | Some(r) -> r
        | nil -> 0.0  # Use nil instead of None

适合解析器的宏

简单宏采用契约优先设计，可通过 LL(1) 解析——IDE 无需展开宏即可提供自动补全：

# Macro declares what it introduces in the contract header
macro define_counter(NAME: Str const) -> (
  returns result: (init: Int, step: Int),
  intro counter_fn: enclosing.class.fn "{NAME}Counter"(start: Int) -> Int
):
  const_eval:
    const init = 0
    const step = 1

  emit counter_fn:
    fn "{NAME}Counter"(start: Int) -> Int:
      start + step

# Usage - IDE knows about UserCounter before expansion
class Demo:
  define_counter!("User")

  fn run() -> Int:
    self.UserCounter(10)  # Autocomplete works!

内置宏：

# Print with formatting
println!("Hello, {name}!")           # Print with newline
print!("Value: {x}")                 # Print without newline

# Debug output with source location
dbg!(expression)                     # Prints: [file:line] expression = value

# Assertions
assert!(condition)                   # Panic if false
assert_eq!(a, b)                     # Panic if a != b
assert_ne!(a, b)                     # Panic if a == b

# Collections
nums = vec![1, 2, 3, 4, 5]           # Create vector
formatted = format!("x={x}")         # Format string without printing

# Panic with message
panic!("Something went wrong: {err}")

常量展开宏（生成多个函数）：

# Generate accessor functions for each axis
macro gen_axes(BASE: Str const, N: Int const) -> (
  intro axes:
    for i in 0 .. N:
      enclosing.class.fn "{BASE}{i}"(v: Vec[N]) -> Int
):
  emit axes:
    for i in 0 .. N:
      fn "{BASE}{i}"(v: Vec[N]) -> Int:
        v[i]

# Usage: generates x(), y(), z() accessors
class Point3D:
  gen_axes!("axis_", 3)  # Creates axis_0, axis_1, axis_2

AOP 与面向切面编程

基于谓词的切入点，默认采用编译时织入作为执行模型：

# Before advice — runs before matching functions
on pc{ execution(* handle_request(..)) } use log_entry before priority 10

# After advice — runs after successful return
on pc{ execution(* save(..)) & attr(audited) } use audit_write after_success priority 20

# Around advice — wraps function with proceed() contract
on pc{ within(services.*) } use trace_around around priority 50

# Architecture rules — enforce layer dependencies at compile time
forbid pc{ within(hal.*) } "HAL cannot depend on services"
allow  pc{ within(services.*) } "Services can use HAL"

支持的选择器： execution(*)、within(*)、attr(*)，支持 &（与）、|（或）、!（非）运算符。 通知类型： before、after_success、after_error、around（恰好调用一次 proceed）。 排序： 优先级（降序）> 特异性 > 名称的字典序。 零开销： 未定义切面时，不会生成织入元数据。 运行时拦截： 作用域限定、仅可选择启用，在 release 构建中禁用。

完整契约请参阅 AOP 支持矩阵。

SDN 配置

简单数据表示法——一种简洁、令牌高效的配置文件格式：

# app.sdn - Application configuration
app:
    name: MyService
    version: 2.1.0

server:
    host: 0.0.0.0
    port: 8080
    workers: 4

# Inline arrays and dicts
features = [auth, logging, metrics]
database = {driver: postgres, host: localhost, port: 5432}

# Named tables - compact tabular data
rate_limits |endpoint, requests, window|
    /api/login, 5, 60
    /api/search, 100, 60
    /api/upload, 10, 300

在 Simple 中加载 SDN：

config = sdn::load("app.sdn")
print("Server port: {config.server.port}")

SDoctest

可执行示例属于持续维护的测试范围。Simple 同时支持演示代码块和经过验证的 sdoctest 代码块；sdoctest 适用于必须运行并匹配输出的示例。

>>> factorial(5)
120
>>> factorial(0)
1

## Stack data structure with LIFO semantics
struct Stack:
    items: [i64]

var s = Stack(items: [])
s.items.push(1)
s.items.push(2)
print s.items.len()  # 2

运行 SDoctest 示例：

simple test --sdoctest README.md      # Run verified examples in Markdown/docs
simple test --spl-doctest src/math.spl # Run file-local source-comment doctests
simple test --sdoctest --tag slow     # Filter by tag

--doctest 仍作为兼容性别名接受，但对于已实现的执行路径，--sdoctest 是更清晰的名称。 在规范的发布命令中，位置参数 test 仅用于选择 spec 树。 --whole 仍会从 config/sdoctest.sdn 中发现 Markdown 文件，并从生产代码的 src/lib、src/compiler 和 src/app 根目录中发现注释里的 sdoctest。

函数式更新运算符（->）

# The -> operator calls a method and assigns result back
var data = load_data()
data->normalize()        # data = data.normalize()
data->filter(min: 0)     # data = data.filter(min: 0)

# Chaining
data->normalize()->filter(min: 0)->save("out.txt")

GPU 计算

import std.gpu

# GPU kernel style 1: #[gpu] with explicit bounds check
#[gpu]
fn vector_add_kernel(a: []f32, b: []f32, result: []f32):
    idx = gpu.global_id(0)           # Global thread index
    if idx < len(result):
        result[idx] = a[idx] + b[idx]

# GPU kernel style 2: @simd with auto bounds handling
@simd
fn vector_scale(data: []f32, scale: f32):
    val i = this.index()             # Global linear index (same as gpu.global_id())
    data[i] = data[i] * scale        # Bounds auto-handled

# Host function - runs on CPU
fn main():
    device = gpu.Device()

    # Allocate and upload data
    a = [1.0, 2.0, 3.0, 4.0]
    b = [5.0, 6.0, 7.0, 8.0]

    buf_a = device.alloc_buffer(a)
    buf_b = device.alloc_buffer(b)
    buf_result = device.alloc_buffer<f32>(4)

    # Launch kernel
    device.launch_1d(vector_add_kernel, [buf_a, buf_b, buf_result], 4)

    # Download results
    device.sync()
    result = device.download(buf_result)
    # result = [6.0, 8.0, 10.0, 12.0]

GPU 线程索引器：

#[gpu]
fn matrix_multiply(A: []f32, B: []f32, C: []f32, N: u32):
    # Multi-dimensional indexing
    val row = gpu.global_id(0)       # First dimension
    val col = gpu.global_id(1)       # Second dimension

    # Thread group (workgroup) info
    val local_row = gpu.local_id(0)  # Index within workgroup
    val group_row = gpu.group_id(0)  # Workgroup index

    # Alternative @simd style
    # val(row, col) = this.index()  # Tuple for 2D
    # vallocal_idx = this.thread_index()
    # valgroup_idx = this.group_index()

    if row < N and col < N:
        var sum = 0.0_f32
        for k in 0..N:
            sum += A[row * N + k] * B[k * N + col]
        C[row * N + col] = sum

GPU 示例： 请参阅 examples/gpu/vulkan/，了解向量加法、矩阵乘法、归约和图像模糊示例。

---

文档

按主题分类的快速链接

主题	说明	链接
文档中心	编号文档索引	doc/README.md
语言规范	可执行规范和生成的规范	doc/06_spec/README.md
指南	实用操作指南	doc/07_guide/README.md
计划	实施路线图	doc/03_plan/README.md
研究	设计探索	doc/01_research/README.md
架构	系统设计原则	doc/04_architecture/README.md
跟踪	Bug、测试和待办事项跟踪	doc/08_tracking/README.md
报告	会话和里程碑报告	doc/09_report/README.md
深度学习	神经网络和 GPU 计算	doc/07_guide/deep_learning/deep_learning.md

核心文档

入门：

• 文档中心 - 编号文档树的当前入口
• 入门指南 - 项目设置和初始步骤
• 语法快速参考 - 官方公开语法速查表
• 测试指南 - 测试工作流和命令概览

语言参考：

• 语法指南 - 表层语法和示例
• 类型系统指南 - 类型、可变性和用法
• 模块系统指南 - 导入、包和布局
• 标准库指南 - 标准库的组织方式和用法

GPU 计算：

• 深度学习指南 - 纯 Simple、面向模型和训练工作流
• GPU 编程指南 - 面向后端和内核的 GPU 用法
• GPU API - GPU API 参考
• LLVM 后端架构 - 后端实现细节

开发：

• 构建指南 - 构建 Simple 和常见工作流
• 测试指南 - 测试运行器的行为和标志
• SSpec 场景手册指南 - step(...)、内联场景、捕获和生成的手册样式
• Mock 策略指南 - 系统测试中的 Mock 禁用策略和测试级别强制要求
• 覆盖率指南 - 覆盖率、SDoctest 和强制要求
• MCP 工具指南 - MCP 注册和用法

高级功能：

• 宏系统 - 可执行宏规范和状态
• AOP 支持矩阵 - 支持的选择器、通知类型、后端和错误代码
• SDN 格式 - Note/SDN 存储和索引格式
• SDoctest - 文档测试和经过验证的示例
• 功能文档 - 生成的功能文档产物格式

---

示例

深度学习示例

Simple 提供了多个深度学习示例，涵盖纯 Simple、模型训练和面向 GPU 的工作流：

纯 Simple 神经网络：

# XOR neural network training
bin/simple examples/pure_nn/xor_training_example.spl

# Linear regression (learns y = 2x + 1)
bin/simple examples/pure_nn/simple_regression.spl

# Iris flower classification
bin/simple examples/pure_nn/iris_classification.spl

MedGemma 韩语微调：

# Progressive LoRA training to prevent catastrophic forgetting
bin/simple examples/medgemma_korean/run_all.spl

CUDA 编程：

# Direct CUDA C API - multi-GPU, streams, events
bin/simple examples/cuda/basic.spl

请参阅深度学习指南，了解当前文档。

其他示例

examples/ 目录包含其他可运行的示例：

示例	描述
cli_demo.spl	命令行参数解析
file_async_basic.spl	异步文件 I/O 操作
ui_todo_app.spl	跨平台 UI 应用程序
vulkan_triangle.spl	使用 Vulkan 进行 GPU 渲染
async_tcp_echo_server.spl	异步 TCP 网络通信

运行示例：

bin/simple examples/cli_demo.spl

---

SSpec 场景手册

功能和系统文档由可执行的 SSpec .spl 场景生成。SPipe 是相关的运行器/文档生成流程；SSpec 是编写风格：编写易读的 step("...") 操作，在同一场景中保留可执行断言，并让文档生成器生成简洁的手册步骤，同时折叠源代码。

示例 1：TUI 选择

此示例遵循 test/03_system/gui/editor_controller_spec.spl 中测试的真实 Code Actions 选择器流程：填充可选择面板、选择一行，并按 Enter 应用。将交互与其可见的选择约定放在一起。

use std.spec.{describe, expect, it, step}

describe "Code action picker":
  it "selects and applies the requested repair":
    # @req REQ-EDITOR-CODE-ACTION-001
    val actions = [
      ["First fix", "Rename first now"],
      ["Second fix", "Rename second now"]
    ]
    step("Open the Code Actions menu")
    step("Select \"Second fix\"")
    val selected_index = 1
    step("Press Enter to apply the selected action")
    expect(actions[selected_index][0]).to_equal("Second fix")
    expect(actions[selected_index][1]).to_equal("Rename second now")

生成的操作手册：

1. Open the Code Actions menu
2. Select "Second fix"
3. Press Enter to apply the selected action

示例 2：表格输出

此内容摘自仪表板 HTML 渲染系统规范 test/03_system/feature/app/web_dashboard/dashboard_render_spec.spl。这是一份相同的表格形式契约，可用于压缩、存储/NVMe、安全性和 HTML 测试报告：列保持稳定，行具有代表性，并对生成的内容进行断言。

use std.spec.{describe, expect, it, step}
use app.dashboard.render.table.{render_html_table}

describe "Artifact verification table":
  it "renders each artifact result as a table row":
    val headers = ["Artifact", "Integrity", "Status"]
    val rows = [
      ["firmware.bin", "sha256", "passed"],
      ["policy.sdn", "signature", "blocked"]
    ]
    step("Render the artifact verification table")
    val html = render_html_table(headers, rows)
    step("Verify the blocked policy result remains visible")
    expect(html).to_contain("policy.sdn")
    expect(html).to_contain("blocked")

生成的 QA 证据可以保留紧凑的表格结果：

Artifact     | Integrity | Status
firmware.bin | sha256    | passed
policy.sdn   | signature | blocked

Given_*、When_* 和 Then_* 助手命名是旧式风格。新建 SSpec 手册时请使用 step("...")。请参阅 SSpec 场景手册指南。

生成的文档存放在 doc/06_spec/ 下的编号文档树中。Docgen 会镜像测试路径，但会去掉开头的 test/ 组件；例如， test/03_system/plan_acceptance/evidence_showcase_spec.spl 会生成 doc/06_spec/03_system/plan_acceptance/evidence_showcase_spec.md。

---

语法与规范

语言语法

Simple 当前的语言参考资料分为两类：面向用户说明的指南树，以及用于可执行或生成式参考资料的规范树。

当前参考文档：

• 语法速查 - 面向公众语言的快速参考
• 语法指南 - 面向用户的语言讲解
• 语言规范索引 - 当前生成的规范索引
• 语法规范 - 语法覆盖的规范产物
• 类型规范 - 类型系统覆盖的规范产物
• 模块规范 - 模块系统覆盖的规范产物

语法速查：

# Top-level
program ::= statement*

# Statements
statement ::= function_def | class_def | struct_def | enum_def
            | import_stmt | export_stmt | expr_stmt

# Expressions (Pratt parser)
expr ::= literal | identifier | binary_op | unary_op
       | call | index | field_access | lambda
       | if_expr | match_expr | block

# Types
type ::= identifier | array_type | tuple_type | fn_type
       | optional_type | result_type | generic_type

# Literals
literal ::= integer | float | string | bool | array | dict | tuple

规范索引

当前规范和指南资料按编号整理在文档树中：

核心语言：

• 语法规范 - 面向语法的规范资料
• 类型规范 - 类型系统规范资料
• 数据结构规范 - 数据结构覆盖范围
• 函数规范 - 函数与模式匹配
• Trait 规范 - Trait 与实现
• 内存规范 - 所有权与借用
• 模块规范 - 导入/导出系统

高级功能：

• 并发规范 - 异步与并发行为
• 元编程规范 - 宏与装饰器
• 宏规范 - 宏专属的可执行覆盖
• 能力效应 - 能力/效应系统
• 标准库指南 - 标准库结构与用法
• SFFI 指南 - 互操作指南
• 外部原生库 - 可选的宿主库集成

测试与工具：

• 测试指南 - 测试运行器与匹配器
• SSpec 场景手册指南 - 根据可执行规范生成的场景手册
• 覆盖率指南 - 覆盖率与 SDoctest 强制要求
• Lint 指南 - Lint 规则与工作流
• MCP 指南 - MCP 工作流与注册

GPU 与平台：

• GPU 编程指南 - GPU 用法
• 深度学习指南 - 面向模型的示例
• 裸机指南 - 平台与裸机工作流

有关当前文档入口，请参阅 doc/README.md、doc/06_spec/README.md 和 doc/07_guide/README.md。

---

项目结构

simple/
├── bin/                      # CLI wrappers and admitted binaries
│   ├── simple                # Main CLI
│   └── release/              # Release binaries by target
│
├── src/                      # Product source
│   ├── app/                  # CLI, build, MCP, LSP, test runner, tools
│   ├── compiler/             # Numbered compiler layers
│   │   ├── 00.common/        # Shared compiler contracts and cache keys
│   │   ├── 10.frontend/      # Lexer, parser, AST, desugaring
│   │   ├── 50.mir/           # Lowered intermediate representation
│   │   ├── 70.backend/       # Native, LLVM, C, WASM, and linker backends
│   │   ├── 80.driver/        # Build driver and incremental cache
│   │   │   └── cache/reference/ # Reverse-reference scheduling and receipts
│   │   ├── 95.interp/        # Interpreter execution layer
│   │   └── 99.loader/        # Module resolution, loading, and JIT instantiation
│   ├── compiler_rust/        # Rust seed bootstrap compiler
│   ├── lib/                  # Standard library, imported as use std.X
│   ├── runtime/              # Native runtime and support libraries
│   └── verification/         # Formal verification
│
├── test/                     # Executable specifications
│   ├── 01_unit/              # Unit tests
│   ├── 02_integration/       # Integration tests
│   ├── 03_system/            # System and feature tests
│   ├── 04_smoke/             # Fast product smoke tests
│   └── 05_perf/              # Performance tests
│
├── doc/                      # Numbered lifecycle documentation
│   ├── 01_research/          # Research
│   ├── 02_requirements/      # Requirements
│   ├── 03_plan/              # Plans
│   ├── 04_architecture/      # Architecture
│   ├── 05_design/            # Detail design
│   ├── 06_spec/              # Generated/manual SSpec documents
│   └── 07_guide/             # User and contributor guides
│
├── .scv/quarantine/          # Ignored local SCV/JIT/root artifacts
└── build/                    # Ignored output, bootstrap artifacts, and scratchpad probes

增量编译与解释器边界

src/compiler/80.driver/cache/reference/ 下的反向引用记录会将变更的声明和构件映射到已知的使用者。构建驱动程序利用它们选择失效和复用候选项；加载器则使用相同的依赖事实进行调度。当回执和缓存键匹配时，这些记录可以让增量编译更具针对性，但不会改变语言语义，也不会将解释器运行转变为原生编译。解释器执行仍由 src/compiler/95.interp/ 负责。

准入模型和当前证据限制记录在反向引用协调计划中。

---

开发

构建

# Debug build
simple build

# Release build
simple build --release

# With GPU support
simple build --release --features=vulkan

# Bootstrap build (minimal 9.3MB)
simple build --bootstrap

测试

完整测试套件快照（2026-02-14）：4,067/4,067 通过

Simple 采用广泛的测试策略，涵盖规范测试、SDoctest、覆盖率和系统测试通道。以下数据来自链接的 2026-02-14 报告：

# All tests (4,067 tests in 17.4 seconds)
simple test

# Run specific test file
simple test path/to/spec.spl

# With verbose output
simple test --verbose

# Coverage reports
simple build coverage

测试覆盖：

• 核心解释器：227 项测试
• 编译器：306 项测试
• 标准库：428 项测试
• 应用程序：142 项测试
• 库（ML、Physics、Game）：185 项测试
• 集成与覆盖率：2,779 项测试

性能：

• 总执行时间：17.4 秒
• 平均每项测试：4.3ms
• 所有测试均可确定且运行迅速

性能配置：

• 语言配置：scripts/check/check-cross-language-perf.shs 生成 doc/09_report/cross_language_perf_2026-06-06.md
• GUI 配置：tools/gui_perf_bench/run_all_benchmarks.shs 生成 doc/09_report/gui_perf_benchmark_2026-06-06.md
• 启动/TUI 配置：scripts/check/check-startup-size-performance-audit.shs 在 doc/09_report/startup_size_performance_audit_2026-05-27.md 中记录 TUI 启动数据行

详细测试分析请参阅 doc/09_report/session/full_test_suite_results_2026-02-14.md。

代码质量

# Check before commit (fmt + lint + test)
simple build check

# Full check (includes coverage + duplication)
simple build check --full

# Format code
simple build fmt

# Lint
simple build lint

---

AI 工具（MCP、LSP、插件）

Simple 附带 MCP 服务、LSP 服务和 Claude Code 插件，全部以 Simple 编写。

安装 Simple MCP 服务

Simple MCP 服务提供基于仓库的工具，用于代码诊断、VCS、构建、测试、调试及相关工作流。如需了解当前注册详情，请参考仓库脚本和指南文档，而不要依赖此处硬编码的数量。

# From a repo checkout — register with Claude Code
claude mcp add simple-mcp -- \
  /absolute/path/to/simple/bin/simple \
  /absolute/path/to/simple/src/app/mcp/main.spl

# Or use the project .mcp.json (auto-detected by Claude Code)
sh config/mcp/install.shs

安装 Simple MCP 插件

simple-mcp Claude 插件是一个仓库检出插件。请从 Simple 仓库检出目录安装；它不是独立的可移植运行时套件。

claude plugin marketplace add tools/claude-plugin/marketplace
claude plugin install simple-mcp@simple-local

该插件会从仓库根目录启动 bin/simple_mcp_server。

安装 Simple LSP 插件

Simple 语言服务为 .spl / .shs 文件提供补全、悬停、转到定义、诊断和语义令牌。

# From a repo checkout
claude plugin marketplace add tools/claude-plugin/marketplace
claude plugin install simple-lsp@simple-local

二进制文件完整路径： bin/simple run src/app/lsp/main.spl

同时安装（快速设置）

cd /path/to/simple

# 1. MCP server
sh config/mcp/install.shs

# 2. LSP plugin
claude plugin marketplace add tools/claude-plugin/marketplace
claude plugin install simple-lsp@simple-local

提示词示例

安装 MCP 服务和 LSP 插件后，可在 Claude Code 中试用以下提示词：

> "Run the linter on src/app/cli/main.spl and fix any warnings"

> "Show me all unused variables in the compiler frontend"

> "Run the unit tests for the SDN parser"

> "Build the project in release mode and show the result"

> "What does the function `parse_expression` in the parser do?"

> "Find all TODO items in the codebase"

> "Check the doc coverage for the standard library"

> "Debug why test/01_unit/lib/common/value_spec.spl is failing"

---

编辑器插件

VSCode 扩展

功能齐全的扩展，支持 Tree-sitter 高亮、LSP 集成和数学块。

cd src/app/vscode_extension
npm install && npm run compile && npm run package
code --install-extension simple-language-0.1.0.vsix

主要功能：

• 语义语法高亮（由 Tree-sitter 提供支持）
• LSP：补全、悬停、跳转到定义、诊断
• 数学块高亮，支持 m{}、loss{}、nograd{} 以及嵌套大括号
• 测试 CodeLens：在 describe/it/context/sdoctest 块的侧边栏显示“运行测试/文件/文档测试”箭头
• AI 驱动的补全和聊天（需要 GitHub Copilot）

完整文档请参阅 src/app/vscode_extension/README.md。

Neovim 插件

-- lazy.nvim
{ "nicholasgasior/simple.nvim", ft = "simple", opts = {} }

-- Or from project checkout
vim.opt.rtp:prepend("/path/to/simple/src/app/nvim_plugin")
require("simple").setup()

主要功能：

• 支持自动检测的 LSP 集成
• 数学块隐藏并以内联 Unicode 预览（frac(1,2) -> (1)/(2)，alpha -> α，sqrt(x) -> √(x)）
• 测试 lens：在测试块旁显示“运行”虚拟文本
• Tree-sitter 查询（高亮、折叠、文本对象、注入）
• 简洁视图（折叠至签名）

完整文档请参阅 src/app/nvim_plugin/README.md。

---

TRACE32 工具

适用于 Lauterbach TRACE32 调试器的 MCP 服务、CMM 语言服务端和命令行工具。完整文档请参阅 examples/10_tooling/trace32_tools/README.md。

仓库管理的容器流程以无头模式运行，并使用 t32mciserver。其中不包含捆绑的 TRACE32 GUI 兼容库；厂商运行时文件必须来自本地 /opt/t32 安装。

主要生命周期封装器：

scripts/t32q.shs build
scripts/t32q.shs on
scripts/t32q.shs wait
scripts/t32q.shs ping
scripts/t32q.shs reopen
scripts/t32q.shs off

GUI 容器重新打开路径：

scripts/t32q.shs gui-on
scripts/t32q.shs gui-reopen
scripts/t32q.shs off

gui-on 使用带主机 X11 转发的 Docker/Podman TRACE32 GUI 路径，因此需要真实的主机 X11 会话（DISPLAY、/tmp/.X11-unix，通常还需要 XAUTHORITY）。如需快速诊断，请使用：

scripts/t32q.shs doctor

Hello-world 固件冒烟测试：

scripts/t32_semihost_hello.shs --board stm32wb
scripts/t32_semihost_hello.shs --board stm32h7
scripts/t32_semihost_hello.shs --board stm32wb --build-only

可选：安装 T32 MCP 服务

这些 TRACE32 MCP 服务不会通过默认项目 MCP 设置安装。 仅在实际使用 TRACE32 工具时，才手动注册它们。

cd /path/to/simple

# T32 MCP — controls live TRACE32 debug sessions (23 tools)
claude mcp add t32-mcp -- \
  /absolute/path/to/simple/bin/simple \
  /absolute/path/to/simple/examples/10_tooling/trace32_tools/t32_mcp/main.spl

# T32 LSP MCP — CMM script analysis, no hardware needed (6 tools)
claude mcp add t32-lsp-mcp -- \
  /absolute/path/to/simple/bin/simple \
  /absolute/path/to/simple/examples/10_tooling/trace32_tools/t32_lsp_mcp/main.spl

二进制文件完整路径：

• T32 MCP：bin/simple run examples/10_tooling/trace32_tools/t32_mcp/main.spl
• T32 LSP MCP：bin/simple run examples/10_tooling/trace32_tools/t32_lsp_mcp/main.spl

安装 CMM LSP 插件

claude plugin marketplace add tools/claude-plugin/marketplace
claude plugin install cmm-lsp@simple-local

二进制文件完整路径： bin/simple run examples/10_tooling/trace32_tools/cmm_lsp/mod.spl --lsp

T32 提示词示例

> "Parse this CMM script and check for errors: config/t32/stm32h7_gdb_start.cmm"

> "Connect to TRACE32 on localhost:20000 and read the CPU registers"

> "Show me all labels and macros defined in my CMM script"

> "Convert this GUI PRACTICE script to CLI batch mode"

> "Check if my CMM script has any undefined macros or unreachable code"

> "Set a breakpoint at main, run to it, and show local variables"

> "What TRACE32 commands are available for memory access?"

> "Auto-complete suggestions for 'Data.LOAD' in my CMM script"

---

参与贡献

开发指南请参阅 CLAUDE.md，AI Agent 指引请参阅 AGENTS.md。

文档结构：

• 规范位于 doc/06_spec/（语言支持的内容）
• 指南位于 doc/07_guide/（功能的使用方法）
• 研究位于 doc/01_research/（决策的原因和过程）
• 计划位于 doc/03_plan/（实现路线图）
• 报告位于 doc/09_report/（会话摘要和完成报告）

---

许可证

Apache License 2.0。请参阅 LICENSE。

捆绑的第三方运行时组件及再分发声明列于 THIRD_PARTY_NOTICES.md。

发行包中也包含 THIRD_PARTY_NOTICES.md。

---

资源

官方文档：

• 文档中心 - 编号文档树的入口
• 语言规范 - 当前规范索引
• 用户指南 - 实用教程

快速参考：

• 语法快速参考
• 类型系统指南
• GPU 计算指南

开发：

• 架构概览
• 功能文档
• 实现计划