Ads Brain Planning Gate Validation 1.0.0

规划 Agent 门禁与校验协议

1. 定位

本 Skill 定义规划 Agent 新框架下的通用门禁与校验协议。

当前阶段只做内容层定义：

• 不接入 agent-card.json。
• 不新增 Java Guard 服务。
• 不替换已有校验工具。
• 不直接调用执行 Tool。

本 Skill 供 ads-brain-planning-pipeline、ads-brain-planning-create-pipeline、ads-brain-planning-optimize-pipeline 引用。

---

2. 概念定义

---

3. 五层门禁与校验

Capability Gate
  ↓
Scenario Gate
  ↓
Business Guard
  ↓
Payload Validation
  ↓
Execution Gate

---

4. 统一规则模型

每条规则都应能映射成以下结构。

{
  "rule_id": "string",
  "rule_type": "capability_gate | scenario_gate | business_guard | payload_validation | execution_gate",
  "capability": "create | optimize | common",
  "stage": "string",
  "severity": "block | warn | route | ask | pass",
  "condition": "string",
  "result": {
    "allowed": true,
    "blocked_reason": "string | null",
    "warnings": [],
    "route_hint": "string | null",
    "required_clarifications": [],
    "next_action": "confirm_execution | ask_clarification | unsupported | no_action | continue"
  }
}

---

5. GateValidationResult

所有门禁与校验最终归一成 GateValidationResult。

{
  "allowed": true,
  "final_decision": "pass | block | warn | ask | route",
  "blocked_reasons": [],
  "warnings": [],
  "route_hint": null,
  "required_clarifications": [],
  "next_action": "continue",
  "applied_rules": [
    {
      "rule_id": "string",
      "decision": "pass | block | warn | ask | route",
      "reason": "string"
    }
  ]
}

合并优先级：

block > ask > route > warn > pass

---

6. Capability Gate

---

7. Scenario Gate

7.1 创编场景门禁

7.2 优化场景门禁

---

8. 场景化 Guard

部分 Guard 只在特定场景触发，不能全局必跑。

8.1 设计原则

1. 先识别场景，再触发 Guard。
2. 未命中场景时，Guard 结果为 skipped。
3. 需要 Tool/RPC/Evidence 的 Guard 只有命中触发条件才执行。
4. skipped 必须记录原因，不能等同于 passed。
5. Guard 消费 scenario_tags，不要反复让模型猜。

8.2 Guard 输出结构

{
  "guard_name": "string",
  "triggered": true,
  "status": "passed | blocked | warned | routed | skipped",
  "skip_reason": "string | null",
  "decision_reason": "string",
  "payload": {}
}

8.3 场景化 Guard 表

8.4 scenario_tags

上下文归一化阶段应生成 scenario_tags：

{
  "scenario_tags": [
    "simple_create",
    "lead_generation",
    "draft_plan_optimize",
    "diagnosis_intent",
    "budget_changed"
  ],
  "scenario_confidence": {
    "lead_generation": "high",
    "diagnosis_intent": "medium"
  }
}

---

9. 控制规则目录

本协议是新框架中门禁与校验的统一控制面。创编和优化 Pipeline 只需要消费这里定义的 rule / guard / validation，不需要在各自正文中重复发明控制规则。

9.1 创编控制规则

9.2 优化控制规则

9.3 需要补充的通用输出校验

当前协议层建议新增一个逻辑校验项：

---

10. Business Guard

---

11. Payload Validation

校验原则：

1. 缺字段但可安全默认：warn，并写入 assumptions。
2. 缺字段且不能安全默认：ask。
3. 字段非法且不可修复：block。
4. 字段非法但可修复：修复后记录 warnings。

---

12. Execution Gate

---

13. blocked_reason 枚举

---

14. next_action 枚举

---

15. 接入建议

当前阶段：

• 只作为内容层协议被其他新 Pipeline Skill 引用。
• 不要求 Java 强制执行。
• 不要求 agent-card 暴露。

后续可分阶段接入：

1. Prompt 文档接入。
2. 结构化输出协议接入。
3. JSON/YAML 规则配置接入。
4. Java Guard 服务接入。
5. 测试与观测接入。