output-contract-enforcer

输出契约强制器

在将 DAG 节点的输出传递给下游节点之前，验证其是否符合声明的 JSON 架构。这是让多 Agent DAG 可靠运行的关键。缺少这一步，下游节点就会收到不可预测的输入，导致 DAG 出错。

---

适用场景

✅ 适用于：

• 根据声明的架构验证节点输出
• 根据自然语言输出描述生成输出架构
• 调试下游节点拒绝其输入的原因
• 确保相连节点之间的契约兼容性

❌ 不适用于：

• 评估内容质量或正确性（使用 dag-quality）
• 评定技能质量（使用 skill-grader）
• DAG 之外的一般 JSON 架构工作

---

验证流程

flowchart TD
  O[Node output] --> P[Parse as JSON]
  P -->|Parse error| E1[FAIL: Not valid JSON]
  P -->|Valid JSON| S[Check against schema]
  S --> R{Required fields?}
  R -->|Missing| E2[FAIL: Missing required field X]
  R -->|Present| T{Type check?}
  T -->|Wrong type| E3[FAIL: Field X expected string, got number]
  T -->|Correct| C{Constraints?}
  C -->|Violated| E4[FAIL: Field X violates constraint Y]
  C -->|Met| V[PASS: Contract satisfied]

检查内容

检查项	示例	失败消息
JSON 可解析	{broken json	"Output is not valid JSON"
必填字段	缺少 status	"Missing required field: status"
字段类型	status: 42（预期为字符串）	"Field 'status' expected string, got number"
枚举值	status: "maybe"	"Field 'status' must be one of: pass, warn, fail"
字符串约束	summary: ""（minLength: 1）	"Field 'summary' must have minLength 1"
数字约束	score: 1.5（maximum: 1.0）	"Field 'score' must be ≤ 1.0"
数组约束	items: []（minItems: 1）	"Field 'items' must have at least 1 item"
嵌套对象	缺少子字段	"Field 'metadata.cost' is required"

标准输出契约

每个 DAG 节点都应生成符合此基础架构的输出（可扩展字段）：

{
  "type": "object",
  "required": ["status", "summary"],
  "properties": {
    "status": {
      "type": "string",
      "enum": ["pass", "warn", "fail"]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "description": "1-3 sentence description of what was produced"
    },
    "artifacts": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of files created or modified"
    },
    "data": {
      "type": "object",
      "description": "Node-specific output data (schema varies per node)"
    },
    "risks": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Remaining risks or assumptions"
    }
  }
}

契约兼容性检查

连接节点 A 的输出与节点 B 的输入时，请确认：

1. B 要求的每个字段都包含在 A 的输出架构中
2. 类型匹配（A 生成字符串，B 也预期字符串）
3. A 的输出约束与 B 的输入约束兼容
4. 如果 A 生成的可选字段是 B 的必填字段 → 不兼容

Node A output: { status: string, recommendations: string[] }
Node B input:  { status: string, recommendations: string[], priority: number }

Result: INCOMPATIBLE — Node B requires 'priority' but Node A doesn't produce it.
Fix: Add 'priority' to Node A's output, or add a transformer node between A and B.

---

架构生成

当节点描述为“生成带有优先级的建议列表”时，生成：

{
  "type": "object",
  "required": ["status", "summary", "data"],
  "properties": {
    "status": { "type": "string", "enum": ["pass", "warn", "fail"] },
    "summary": { "type": "string", "minLength": 1 },
    "data": {
      "type": "object",
      "required": ["recommendations"],
      "properties": {
        "recommendations": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": ["text", "priority"],
            "properties": {
              "text": { "type": "string" },
              "priority": { "type": "integer", "minimum": 1, "maximum": 5 }
            }
          }
        }
      }
    }
  }
}

---

反模式

完全没有契约

错误做法：节点生成没有架构约束的自由格式文本。 原因：下游节点无法可靠地解析输入，DAG 会很脆弱。 正确做法：每个节点都声明其输出架构。每次输出都要在传递给下游之前进行验证。

契约过于严格

错误做法：要求精确的字符数、特定格式，或依赖运行时上下文的字段值。 正确做法：约束结构（类型、必填字段），而不是内容。内容评估交由 dag-quality 处理。

忽略可选字段

错误做法：将所有字段都视为必填。 正确做法：仅将下游节点绝对需要的字段设为 required。其他字段均标为可选。