alantech/marsha

Marsha – 由 LLM 驱动的「编程语言」

是什么 – Marsha 允许你用一种小型的、类似 Markdown 的方式描述一个数据处理任务。你声明输入和输出的「类型」，编写简短的自然语言说明，并提供少量输入-输出示例。Marsha 编译器将此规范发送给 LLM（默认使用 OpenAI 的 API，但任何兼容的端点均可），生成 Python 代码，运行示例作为测试，并返回一个可直接运行的脚本。

核心理念

• 声明式语法 – .mrsh 文件看起来像 Markdown。类型使用 CSV 风格的表格定义，函数通过 # func … 标题声明，后接描述和示例块。
• 基于示例的测试 – 你提供的示例会成为测试套件，编译器用它来验证生成的代码，从而降低输出出错的可能性。
• LLM 作为后端编译器 – 将规范转换为 Python 的重载工作由 LLM 完成。你可以通过配置、命令行标志或环境变量选择模型。
• 即用型输出 – 生成的 Python 代码包含一个微型 CLI 包装器（或简单的 REST 服务器），因此你可以直接从终端调用编译后的函数。

如何使用

1. 从仓库安装包：

   uv pip install git+https://github.com/alantech/marsha
   

2. 使用 Marsha 语法（类型定义、# func … 块、描述和示例）编写 my_task.mrsh 文件。
3. 编译它：

   python -m marsha my_task.mrsh
   

   该命令会联系配置的 LLM，生成 Python 代码，运行测试，并写出结果脚本。
4. 以 CLI 工具或小型 Web 服务的形式运行生成的脚本：

   python -m my_task --help          # 查看生成的 CLI 选项
   python -m my_task -s 8080         # 启动 REST 服务器
   

配置 – Marsha 从标准操作系统位置（Linux 上为 ~/.config/marsha/config.json 等）读取 JSON 配置文件。你可以设置 api_base、api_key、model 和 model_strong。环境变量（OPENAI_ORG、OPENAI_SECRET_KEY/OPENAI_API_KEY）可用于默认的 OpenAI 后端。--api-base 和 --model 标志可在命令行上覆盖这些设置。

命令行选项（精选亮点）：

• -q – 仅生成代码，跳过修正阶段（更便宜，但可靠性较低）。
• -a N – 尝试最多 N 次编译，失败时重试。
• -n N – 每次尝试运行 N 个并行的 LLM「思考路径」；第一个成功路径获胜。
• --exclude-main-helper – 排除自动生成的 CLI 包装器。
• --exclude-sanity-check – 跳过 Marsha 定义的初始一致性检查。
• -s – 将编译统计信息写入文件。

路线图亮点

• 将平均正确率提升至 90% 以上。
• 添加编辑器的语法高亮插件。
• 支持 Python 以外的目标语言。
• 引入模块系统和「反编译器」，可将现有 Python 代码还原为 Marsha 语法。
• 构建可视化 GUI 编辑器和更丰富的调试辅助工具。

适用人群 – 希望以更高层次、基于示例的方式生成小型数据处理脚本（如 pandas 流水线）但不想逐行手写代码的开发者，且愿意在测试驱动监督下让 LLM 生成实现。