ERDL —— 面向 AI Agent 的确定性规则

中文 | English

最后更新：2026-09-06 — 双语拆分：README.md 为英文版，中文版移至 README.zh-CN.md

🚀 欢迎 POC —— 欢迎你在自己的环境中试用本项目概念验证。需要技术支持？随时联系 [email protected]。

Entity-Rule Definition Language · 实体规则定义语言

ERDL 是一种确定性、声明式的规则格式，用于 AI Agent 行为治理。 一份规范、一棵规范树、一个哈希 —— 跨实现逐字节验证一致。

ERDL 以 when → then 决策的形式，用 YAML/JSON 表达实体结构与行为规则。 它是一门语言 —— 实现中立、跨平台、可证明一致：同一条规则、同一份输入， 在任何符合规范的实现上都产出逐字节一致的结果与哈希。

为什么需要 ERDL？

| 问题 | ERDL 的解法 | |---------|-------------------| | LLM 输出是概率性的 | 确定性 when → then 护栏，在模型之外求值 —— 安全边界从不押在提示词上 | | 规则语义在各实现间漂移 | 318 条 JCS + SHA-256 向量，强制逐字节一致 | | 合规要求审计轨迹 | 每一次求值都产出可密码学验证的哈希 | | 业务人员看不懂代码 | 三个投影面（Simple / Expression / 决策表）编译到同一棵语义树 |

已验证的一致性

ERDL 的语义由一套跨实现向量集钉死（见 erdl-vectors）。独立的、 仅凭规范实现的 runner 用自建 JCS 重算每一条向量 —— 不依赖参考代码， 不读答案文件。

| 层 | 向量数 | 状态 | |-------|---------|--------| | 决策哈希（DO v1.5） | 78 | ✅ Node.js（参考实现）· ✅ Go（norviq-go）· ✅ Python（concordia-python） | | 表达投影（V-ENGINE） | 240 | ✅ Node.js（参考实现）· ✅ Python（concordia-python-expression） |

形式化验证

向量证明的是你采样到的情形。erdl-formal 证明其余全部 —— 它把 ERDL 表达内核编译为 SMT（Z3），在所有输入上验证 规则永不报错、永不失败放行、永不漏拦。完整覆盖 34 节点 / E1–E12， 反例可以直接回放到本参考引擎。

快速开始（30 秒）

npm install @openoba/erdl

# refund.erdl.yaml
protocol: "erdl/v2"
version: "2.1.0"
metadata:
  name: "refund-guard"
  decision: ALLOW
  category: coding
rules:
  - name: "SEC-001-refund-limit"
    description: "Refunds over 5000 require human approval"
    priority: 10
    when:
      logic: AND
      conditions:
        - field: "tool.name"
          operator: eq
          value: "issue_refund"
        - field: "tool.args.amount"
          operator: gt
          value: 5000
    then: REQUEST_HUMAN
    message: "Refund amount over 5000, human approval required"

import { loadErdlFile, Evaluator } from '@openoba/erdl'

// 1. 从 YAML 文件加载规则
const { rules, metadata } = loadErdlFile('refund.erdl.yaml')

// 2. 对事实对象求值（兜底决策从 metadata 注入）
const result = new Evaluator().evaluate(
  rules,
  { tool: { name: 'issue_refund', args: { amount: 8000 } } },
  { fallbackDecision: metadata.decision },
)
console.log(result.decision) // 'REQUEST_HUMAN'

本包提供文档加载器（loadErdlFile / parseErdlDocument）、求值引擎、 34 节点表达树内核、规则校验、YAML 序列化与模板引擎。 格式详见规范，完整 API 参考见 API.md。

规范

• erdl-language-spec-v2.1.md — 中文规范（权威）
• erdl-language-spec-v2.1.en.md — English specification

社区

• CONTRIBUTING.md — 参与贡献（环境搭建、编码标准、PR 流程）。
• CODE_OF_CONDUCT.md — 社区行为准则。
• SECURITY.md — 漏洞报告。
• DEVELOPMENT.md — 开发工具链与路线图。

仓库结构

.
├── README.md                 # English README
├── README.zh-CN.md              # 中文 README（本文件）
├── erdl-language-spec-v2.1.md              # 中文规范（权威）
├── erdl-language-spec-v2.1.en.md           # English specification
├── API.md                    # API 参考
├── CHANGELOG.md              # 发布历史（Keep a Changelog）
├── CHANGELOG.zh-CN.md           # release history (Keep a Changelog)
├── CONTRIBUTING.md           # 贡献指南
├── CODE_OF_CONDUCT.md        # 行为准则
├── SECURITY.md               # 安全策略
├── DEVELOPMENT.md            # 开发工具链 + 路线图
├── LICENSE                   # MIT
├── NOTICE.md                 # 商标声明
├── package.json / tsconfig.json / vitest.config.ts
└── src/
    ├── index.ts              # 公开 API 入口
    ├── erdl-loader.ts        # YAML 文档加载器（parseErdlDocument / loadErdlFile）
    ├── evaluator.ts          # 求值引擎
    ├── erdl-schema.ts        # 单一事实源（决策 / 运算符 / 分类）
    ├── rule-definition.ts    # 核心类型定义
    ├── rule-validator.ts     # 规则校验
    ├── rule-yaml-serializer.ts  # RuleDefinition → §2.1 YAML
    ├── rule-quality-gate.ts  # 加载期质量门禁
    ├── template-engine.ts    # 模板引擎
    ├── field-contracts.ts    # 字段契约 + display_name
    ├── fn-registry.ts        # 函数委派注册表
    ├── guard-state-manager.ts  # 有状态运算符（within/rate）状态
    ├── op-sem-registry.ts/.yaml  # 操作语义注册表
    ├── safe-regex.ts         # 防 ReDoS 正则
    ├── clock.ts / date-utils.ts  # 时间 + 日期工具
    └── expr-tree/            # 34 节点表达树内核
        ├── node-types.ts     # ExprNode + 34 种节点类型
        ├── evaluator.ts      # 树求值器（E1–E12）
        ├── gloss.ts          # 自然语言投影（gloss）
        ├── s-expression.ts   # S-表达式序列化
        ├── simple-compiler.ts  # Simple 30 运算符编译
        ├── rule-to-expr.ts   # when → 树编译
        ├── canonical.ts      # 规范形
        ├── fixed-point.ts    # 定点有理数算术
        ├── limits.ts         # 资源限制（E4）
        ├── normalize.ts      # NFC 规范化
        ├── grade.ts          # 规则分级（A/B/C）
        ├── decision-table.ts # 决策表编译
        ├── eval-trace.ts / eval-warning.ts  # 求值轨迹 + 警告
        └── *.spec.ts         # 测试套件

鸣谢

决议语义（§7.1 的 ring / override / catch-all）在成形过程中受益于外部 review。其中 ANP2 Network（dev.to/anp2network）对裁决层做了两轮精确、可复现的 review，指出了「空条件（catch-all）规则不得改写显式决议」这一语义边界（现 §7.1 第 6 条）及其在引擎与 SMT 验证层的对应缺口。每一处都推进到「补 spec + 修引擎 + 补证明」。

RavindraAnnam（github.com/RavindraAnnam）提供了一次横跨裁决层与求值层的四部分 review，并借此直指「确定性内核」宣称中最难坚守的边界——有状态算子（within/rate）。他的发现（状态突变的 temporal_state 证据缺口、total_evaluated 计数漂移、裁决证明「有界 vs 无界」的措辞）每一项都推动了一次修复；其中有状态算子的发现，更是直接催生了针对状态算子语义的专项研究。此外，他在 A2A Discussion #2031 中提出的四条运行时权威不变式——权威不放大（authority non-amplification）、溯源连续（provenance continuity）、窄化继承（narrow-only constraint inheritance）、传递撤销（transitive revocation）——演化成了 INV-01~INV-05 委托权威安全备忘，并成为 OpenOBA 多 Agent 治理方向的基础。

Erik Newton (Concordia)（github.com/eriknewton）构建了首个独立的表达层 runner——一个仅凭 spec + 契约实现的 v2.1 表达内核 Python 实现（34 节点 + Simple 30 + 决策表 + gloss）——并与参考引擎交叉验证。他的 RESULTS.md 记录了 16 处 spec 歧义（A1–A16），其中四处暴露了现已修复的真实缺口：errored 求值错误标志（§7.2 E3 / §7.3(a)）、结果对象 number 编码（定点字符串，spec E2 定点字符串序列化）、比较-vs-算术的类型不匹配分界（§7.3(a)）、约束-vs-求值向量分类。他的 runner 还敲定了两处 spec 文本留白的解读——rate 超限边界（§5.2）与类型不匹配比较静默 false（§7.3(a)）。

许可证

MIT © 2026 深圳市秒镜科技有限公司 (Shenzhen Miaojing Technology Co., Ltd.)

商标：ERDL™ 是深圳市秒镜科技有限公司的商标。MIT 许可仅覆盖版权， 不授予任何商标权利。详见 NOTICE.md。