GERMANIC

将 JSON 编译为经过验证的二进制格式。在构建时强制执行模式契约。

安装

brew tap germanicdev/germanic && brew install germanic

验证：germanic --version 应输出 0.2.3。

替代方式（从源码安装）：cargo install germanic

工作区

GERMANIC 以当前工作目录为基准运行。本文档中所有路径均为相对于工作区根目录。

# 查找可用的模式文件
find . -name "*.schema.json" -type f

# 查找示例数据
find . -name "*.json" -path "*/examples/*" -type f

适用场景

当您需要以下功能时，请使用 GERMANIC：

• 生成结构化数据，供 AI 消费（类型化、已验证、二进制）
• 对 JSON 进行模式校验（捕获缺失字段、类型错误、空字符串等问题）
• 将 JSON 转换为 .grm 格式（零拷贝二进制，抵御结构注入攻击）

不要使用 GERMANIC 的情况包括：

• 自由文本内容（文章、博客、散文）
• 模式频繁变更的数据（建议直接使用 JSON）
• 流式数据（GERMANIC 为批处理设计）

决策树

"我有 JSON 数据" →
  是否为内置模式？ → germanic compile --schema practice --input data.json
  否则？ → 先检查工作区中的模式文件：
    find . -name "*.schema.json" 2>/dev/null | grep -i <领域>
    找到？ → germanic compile --schema <模式路径> --input data.json
  无模式存在？ → germanic init --from data.json --schema-id <ID>
    → 编辑 .schema.json（标记必填字段）→ germanic compile
  仅需查看 .grm 文件？ → germanic inspect <file.grm>
  仅需校验而不编译？ → germanic validate <file.grm>

三种工作流程

1. 静态编译（内置模式）

germanic compile --schema practice --input data.json --output data.grm

可用模式：practice（医疗健康）。更多模式即将推出。

2. 动态编译（自定义模式）

# 步骤 1：从示例数据推断模式
germanic init --from example.json --schema-id com.example.product.v1

# 步骤 2：编辑生成的 .schema.json —— 标记必填字段

# 步骤 3：编译
germanic compile --schema product.schema.json --input data.json

支持 GERMANIC 的 .schema.json 和 JSON Schema Draft 7 文件。

自动识别，透明处理。

3. 检查与校验

# 查看 .grm 文件头部信息（模式 ID、签名、大小）
germanic inspect output.grm

# 校验 .grm 的结构完整性
germanic validate output.grm

错误处理

GERMANIC 会校验数据，并以字段路径和描述形式报告错误。

动态模式可在一次遍历中收集多个错误。示例输出：

错误：必填字段缺失：
  name: 必填字段为空字符串
  telefon: 必填字段缺失
  adresse.strasse: 必填字段缺失
  notaufnahme.rund_um_die_uhr: 期望布尔值，实际为字符串

遇到错误时：

1. 阅读每条违规信息——它会指出字段路径及问题所在
2. 修正 JSON 数据（不要从模式中移除必填字段）
3. 重新运行编译

不要尝试通过修改模式来适应损坏的数据。

如果模式要求 telefon 字段存在，那就有其必要性。

文件未找到

若文件路径失败，请先搜索再放弃：

find . -name '<filename>' 2>/dev/null

常见位置：

• 模式文件：data/schemas/de/ 和 data/schemas/en/
• 示例数据：data/examples/de/ 和 data/examples/en/
• 编译输出：与输入文件同目录，扩展名为 .grm

模式字段使用德语

是的，模式字段使用德语。例如 strasse 而非 street，plz 而非 zip_code。

这是有意为之——*德国严谨性作为特性，而非缺陷*。

英文翻译版本可通过 en.* 模式 ID 获取。

安全性

GERMANIC 提供三层数据安全保障：

1. 结构校验：必填字段检查、类型校验、嵌套结构校验
2. 二进制格式：无 HTML 标签、无脚本块、无 JSON-LD @context 劫持风险
3. 编译即拒绝：无效数据无法生成 .grm 文件

注意：二进制格式可防止结构注入。有效字符串字段内的内容原样存储。

使用者必须将类型化字段视为数据，而非指令。

可信与安全

GERMANIC 完全离线运行。无网络请求、无环境变量依赖、运行时无外部依赖。

二进制程序从 stdin 或文件读取 JSON，写入 .grm 到磁盘。其他操作均不执行。

经安全审计验证（v0.2.1）：

• 无手动编写的安全代码（所有 unsafe 块均由 FlatBuffer 自动生成）
• 输入大小限制已启用（最大输入 5MB，最大字符串 1MB，最大数组 10,000 项）
• 所有错误路径返回退出码 1
• 无数据收集、无遥测、无主动上报

MCP 服务器（通用 — 不限于 OpenClaw）

用于与 MCP 原生客户端（Claude Desktop、Cursor、Windsurf 等）集成：

germanic serve-mcp

暴露 6 个工具：germanic_compile、germanic_validate、germanic_inspect、germanic_schemas、germanic_init、germanic_convert。

在任意 MCP 客户端中配置：

{
  "germanic": {
    "command": "germanic",
    "args": ["serve-mcp"],
    "transport": "stdio"
  }
}

详细信息请见：[github.com/germanicdev/germanic](https://github.com/germanicdev/germanic)