MoonPromptSpec

面向 AI 应用的提示词规格校验与测试框架。仓库当前名为 moon_ai_guidekit，核心实现已经升级为 MoonPromptSpec：用 MoonBit 描述提示词模板、变量、测试用例和输出格式，并在提交前发现常见问题。

项目背景

很多 AI 应用前期看起来只需要几条 prompt，后面很快会遇到提示词资产难维护的问题。一个团队刚开始只有几条 prompt，后来会逐渐出现变量名不一致、示例输入漏字段、模板引用未声明变量、期望输出格式漂移等问题。人工复制粘贴时很难发现这些细节，等问题进入真实产品或运营内容之后，修改成本会变高。

MoonPromptSpec 把提示词当成可以被检查的规格文件。每条规格声明：

这个 prompt 面向谁；
模板里有哪些 {{variable}}；
每个变量的含义和是否必填；
至少一组测试输入；
期望输出格式，例如 plain_text、markdown、json、checklist。

第一批示例仍然放在县城、小镇和普通家庭的 AI 使用场景里，因为这些场景具体、易懂，适合验证“提示词规格化”这件事是否真的能帮到非技术用户。

已实现能力

PromptSpec、PromptVariable、PromptCase 数据模型。
必填字段、重复变量、重复 case、空测试用例检查。
模板变量扫描，识别 {{product}} 这类占位符。
模板引用变量和声明变量之间的双向校验。
测试用例输入字段校验，发现缺失输入和多余输入。
输出格式一致性检查。
Markdown 校验报告渲染。
.promptspec.md 示例文件和解析器草稿。
MoonBit 测试草案与 GitHub Actions CI。

示例规格

id: livestream
title: 农产品直播话术
audience: 农产品经营者
output_format: plain_text

variables:
  product: 产品名称
  selling_point: 产品核心卖点
  tone: 语气要求

template:
  请根据 {{product}}、{{selling_point}} 和 {{tone}}，
  生成一段适合直播间开场使用的口播稿。

cases:
  - id: basic
    product: 秭归脐橙
    selling_point: 新鲜采摘、酸甜平衡
    tone: 亲切、口语化
    expected_format: plain_text

MoonBit API 草案

let spec = @promptspec.spec(
  id="livestream",
  title="农产品直播话术",
  audience="农产品经营者",
  template="请根据 {{product}}、{{selling_point}} 和 {{tone}} 生成直播口播稿。",
  variables=[
    @promptspec.variable("product", "产品名称", true),
    @promptspec.variable("selling_point", "核心卖点", true),
    @promptspec.variable("tone", "语气要求", true),
  ],
  cases=[
    @promptspec.prompt_case(
      id="basic",
      inputs=[
        ("product", "秭归脐橙"),
        ("selling_point", "新鲜采摘、酸甜平衡"),
        ("tone", "亲切、口语化"),
      ],
      expected_format=@promptspec.PlainText,
    ),
  ],
  output_format=@promptspec.PlainText,
)

let report = @promptspec.validate_spec(spec)
let markdown = @promptspec.render_markdown_report(report)

计划中的命令行体验

moon-prompt-spec validate examples/xiaocheng
moon-prompt-spec report examples/xiaocheng/livestream.promptspec.md
moon-prompt-spec init promptspec

当前仓库先完成核心校验库和样例规格，后续补齐 CLI、更多解析规则和 Mooncakes 发布。

仓库链接

English Summary

MoonPromptSpec is a MoonBit toolkit for validating prompt specifications. It models prompt templates, variables, test fixtures, and output formats, then reports missing inputs, undeclared variables, unused declarations, and format drift before prompts are copied into AI applications.

开源许可

本项目采用 MIT License。