AI 编程指令：Prompt Contract v1.1（全平台 YAML/JSON 硬约束）

v1.1 目标：
  • 把“提示词”升级为可校验、可编译、可回放的结构化合约（Contract）。
  • 所有输入/输出只允许严格 YAML 或严格 JSON，否则请求失败。
  • 支持三类智能体：video / image / ppt，统一 Envelope + 任务内 Schema。
  • 强制“编辑=差分（diff）”，降低漂移；强制“preserve locks”。

0) 硬约束（必须实现）

  • 禁止任何非 YAML/JSON 字符：输入与输出都必须可被严格解析（JSON 不允许 trailing commas；YAML 禁止多文档、锚点、引用外部）。
  • 双重校验：Parse → Envelope Schema → Task Schema → 输出 Schema → 再次 Parse（防夹带文本）。
  • additionalProperties: false：关键层级尽量关闭自由扩展，避免模型生成“多余字段”。
  • 错误也必须结构化：只能返回 {"error":{...}}（JSON）或等价 YAML。

1) 统一 Envelope v1.1（加入编排、工具、回放、diff）

{
  "version": "1.1",
  "request_id": "traceable-id",
  "timestamp_ms": 0,
  "agent": { "type": "video|image|ppt", "name": "string", "mode": "create|edit|analyze" },

  "task": {
    "name": "string",
    "intent": "string",
    "constraints": { "strict": true, "deterministic_level": "low|mid|high" }
  },

  "context": {
    "project": "string",
    "user_locale": "zh-CN|en-US",
    "seed": 123,
    "memory": { "enabled": false }
  },

  "input": { },

  "edit_spec": {
    "strategy": "none|diff",
    "base_artifact_id": "string-or-null",
    "diff": [
      { "op": "remove|add|replace|set", "path": "/...", "value": {} }
    ]
  },

  "tooling": {
    "allowed_tools": ["render_image", "render_video", "build_ppt", "web_fetch", "code_exec"],
    "io_budget": { "max_steps": 8, "max_tokens": 8000 }
  },

  "output_spec": {
    "format": "yaml|json",
    "schema": "schema-id-or-url",
    "language": "zh-CN|en-US",
    "verbosity": "low|medium|high"
  },

  "policy": {
    "no_extra_text": true,
    "no_markdown": true,
    "no_hidden_steps": true,
    "safe_mode": true
  }
}

1.1 Envelope JSON Schema（核心片段，建议你在仓库维护完整版本）

{
  "$schema":"https://json-schema.org/draft/2020-12/schema",
  "$id":"https://yourdomain/schemas/envelope-1.1.json",
  "type":"object",
  "additionalProperties":false,
  "required":["version","request_id","agent","task","context","input","edit_spec","tooling","output_spec","policy"],
  "properties":{
    "version":{"type":"string","const":"1.1"},
    "request_id":{"type":"string","minLength":6},
    "timestamp_ms":{"type":"integer","minimum":0},
    "agent":{
      "type":"object","additionalProperties":false,
      "required":["type","mode"],
      "properties":{
        "type":{"type":"string","enum":["video","image","ppt"]},
        "name":{"type":"string"},
        "mode":{"type":"string","enum":["create","edit","analyze"]}
      }
    },
    "task":{
      "type":"object","additionalProperties":false,
      "required":["name","constraints"],
      "properties":{
        "name":{"type":"string"},
        "intent":{"type":"string"},
        "constraints":{
          "type":"object","additionalProperties":false,
          "required":["strict","deterministic_level"],
          "properties":{
            "strict":{"type":"boolean","const":true},
            "deterministic_level":{"type":"string","enum":["low","mid","high"]}
          }
        }
      }
    },
    "context":{
      "type":"object","additionalProperties":false,
      "required":["project","user_locale","seed","memory"],
      "properties":{
        "project":{"type":"string"},
        "user_locale":{"type":"string","enum":["zh-CN","en-US"]},
        "seed":{"type":"integer"},
        "memory":{
          "type":"object","additionalProperties":false,
          "required":["enabled"],
          "properties":{"enabled":{"type":"boolean"}}
        }
      }
    },
    "input":{"type":"object"},
    "edit_spec":{
      "type":"object","additionalProperties":false,
      "required":["strategy","base_artifact_id","diff"],
      "properties":{
        "strategy":{"type":"string","enum":["none","diff"]},
        "base_artifact_id":{"type":["string","null"]},
        "diff":{
          "type":"array",
          "items":{
            "type":"object","additionalProperties":false,
            "required":["op","path","value"],
            "properties":{
              "op":{"type":"string","enum":["remove","add","replace","set"]},
              "path":{"type":"string","pattern":"^/"},
              "value":{}
            }
          }
        }
      }
    },
    "tooling":{
      "type":"object","additionalProperties":false,
      "required":["allowed_tools","io_budget"],
      "properties":{
        "allowed_tools":{"type":"array","items":{"type":"string"}},
        "io_budget":{
          "type":"object","additionalProperties":false,
          "required":["max_steps","max_tokens"],
          "properties":{
            "max_steps":{"type":"integer","minimum":1,"maximum":64},
            "max_tokens":{"type":"integer","minimum":256,"maximum":200000}
          }
        }
      }
    },
    "output_spec":{
      "type":"object","additionalProperties":false,
      "required":["format","schema","language","verbosity"],
      "properties":{
        "format":{"type":"string","enum":["yaml","json"]},
        "schema":{"type":"string","minLength":3},
        "language":{"type":"string","enum":["zh-CN","en-US"]},
        "verbosity":{"type":"string","enum":["low","medium","high"]}
      }
    },
    "policy":{
      "type":"object","additionalProperties":false,
      "required":["no_extra_text","no_markdown","no_hidden_steps","safe_mode"],
      "properties":{
        "no_extra_text":{"type":"boolean","const":true},
        "no_markdown":{"type":"boolean","const":true},
        "no_hidden_steps":{"type":"boolean","const":true},
        "safe_mode":{"type":"boolean"}
      }
    }
  }
}

2) “Prompt 编译器（Prompt Compiler）”——把输入合约编译为模型可用指令

原则：
  • 前端/用户只写合约（Envelope + input + diff），不直接写散装提示词。
  • 后端通过 Compiler 生成“模型指令”（仍是 JSON/YAML），并注入 lock/preserve、negative、camera、timeline 等稳定字段。
  • 所有编译产物要可回放：同 input + seed + deterministic_level → 产物一致（尽量）。

2.1 编译输出（建议统一为 ModelInstruction v1）

{
  "model_instruction_version":"1",
  "agent_type":"image|video|ppt",
  "mode":"create|edit|analyze",
  "locks": { "identity": true, "composition": true, "lighting": true, "style": true },
  "negative": ["string"],
  "payload": { "task_specific": {} }
}

2.2 Compiler 伪代码（你直接让 AI coder 按此实现）

function compile(envelope):
  assert parseStrictYamlOrJson(envelope.raw)
  env = parse(envelope.raw)

  validate(env, "envelope-1.1.json")

  // 1) Apply diff (if edit_spec.strategy == "diff")
  appliedInput = applyJsonPatchLike(env.input, env.edit_spec)

  // 2) Route Task Schema
  taskSchema = routeByAgentType(env.agent.type)  // image-task-1.1 | video-task-1.1 | ppt-task-1.1
  validate(appliedInput, taskSchema)

  // 3) Inject deterministic locks based on deterministic_level
  locks = makeLocks(env.task.constraints.deterministic_level, env.agent.mode, appliedInput)

  // 4) Produce ModelInstruction (still JSON/YAML)
  mi = {
    model_instruction_version: "1",
    agent_type: env.agent.type,
    mode: env.agent.mode,
    locks,
    negative: deriveNegative(appliedInput),
    payload: { task_specific: appliedInput }
  }

  // 5) Validate MI schema (optional but recommended)
  validate(mi, "model-instruction-1.json")

  return mi

3) 任务 Schema v1.1（更硬：加入 locks、可定位删除、时间轴、版式约束）

3.1 Image Task v1.1（删除/替换强定位：target + preserve + fill）

{
  "$id":"https://yourdomain/schemas/image-task-1.1.json",
  "type":"object",
  "additionalProperties":false,
  "required":["scene","render","edit","preserve"],
  "properties":{
    "scene":{
      "type":"object","additionalProperties":false,
      "required":["prompt","style","camera","lighting","objects"],
      "properties":{
        "prompt":{"type":"string","minLength":1},
        "style":{"type":"string"},
        "camera":{"type":"string"},
        "lighting":{"type":"string"},
        "objects":{"type":"array","items":{"type":"string"}}
      }
    },
    "render":{
      "type":"object","additionalProperties":false,
      "required":["size","num_outputs"],
      "properties":{
        "size":{"type":"string","enum":["512x512","768x768","1024x1024","1024x1536","1536x1024"]},
        "num_outputs":{"type":"integer","minimum":1,"maximum":8}
      }
    },
    "edit":{
      "type":"object","additionalProperties":false,
      "required":["operations"],
      "properties":{
        "operations":{
          "type":"array",
          "items":{
            "type":"object","additionalProperties":false,
            "required":["op","target","fill","guardrails"],
            "properties":{
              "op":{"type":"string","enum":["remove","replace","add"]},
              "target":{
                "type":"object","additionalProperties":false,
                "required":["description","location_hint"],
                "properties":{
                  "description":{"type":"string"},
                  "location_hint":{"type":"string","enum":["top-left","top-right","center","bottom-left","bottom-right","unknown"]}
                }
              },
              "fill":{"type":"string"},
              "guardrails":{
                "type":"object","additionalProperties":false,
                "required":["do_not_change"],
                "properties":{
                  "do_not_change":{"type":"array","items":{"type":"string"}}
                }
              }
            }
          }
        }
      }
    },
    "preserve":{
      "type":"object","additionalProperties":false,
      "required":["identity","composition","lighting","style","all_other_objects"],
      "properties":{
        "identity":{"type":"string","enum":["locked","flexible"]},
        "composition":{"type":"string","enum":["locked","flexible"]},
        "lighting":{"type":"string","enum":["locked","flexible"]},
        "style":{"type":"string","enum":["locked","flexible"]},
        "all_other_objects":{"type":"string","enum":["locked","flexible"]}
      }
    }
  }
}

3.2 Video Task v1.1（时间轴强约束：shots + per-shot locks + audio）

{
  "$id":"https://yourdomain/schemas/video-task-1.1.json",
  "type":"object",
  "additionalProperties":false,
  "required":["timeline","render","audio","preserve"],
  "properties":{
    "timeline":{
      "type":"object","additionalProperties":false,
      "required":["duration_s","shots"],
      "properties":{
        "duration_s":{"type":"number","minimum":1,"maximum":600},
        "shots":{
          "type":"array","minItems":1,
          "items":{
            "type":"object","additionalProperties":false,
            "required":["id","start_s","end_s","scene","camera","motion","locks"],
            "properties":{
              "id":{"type":"string"},
              "start_s":{"type":"number","minimum":0},
              "end_s":{"type":"number","minimum":0},
              "scene":{"type":"string"},
              "camera":{"type":"string"},
              "motion":{"type":"string"},
              "locks":{
                "type":"object","additionalProperties":false,
                "required":["identity","style"],
                "properties":{
                  "identity":{"type":"boolean"},
                  "style":{"type":"boolean"}
                }
              }
            }
          }
        }
      }
    },
    "render":{
      "type":"object","additionalProperties":false,
      "required":["fps","resolution"],
      "properties":{
        "fps":{"type":"integer","minimum":12,"maximum":60},
        "resolution":{"type":"string","enum":["720p","1080p","4k"]}
      }
    },
    "audio":{
      "type":"object","additionalProperties":false,
      "required":["music","sfx","voiceover"],
      "properties":{
        "music":{"type":"string"},
        "sfx":{"type":"array","items":{"type":"string"}},
        "voiceover":{
          "type":"object","additionalProperties":false,
          "required":["enabled","script"],
          "properties":{
            "enabled":{"type":"boolean"},
            "script":{"type":"string"}
          }
        }
      }
    },
    "preserve":{
      "type":"object","additionalProperties":false,
      "required":["main_character_identity","color_grade","composition"],
      "properties":{
        "main_character_identity":{"type":"string","enum":["locked","flexible"]},
        "color_grade":{"type":"string","enum":["locked","flexible"]},
        "composition":{"type":"string","enum":["locked","flexible"]}
      }
    }
  }
}

3.3 PPT Task v1.1（版式/组件强约束：layout tokens + components）

{
  "$id":"https://yourdomain/schemas/ppt-task-1.1.json",
  "type":"object",
  "additionalProperties":false,
  "required":["deck","slides","design_system","assets"],
  "properties":{
    "deck":{
      "type":"object","additionalProperties":false,
      "required":["title","language","purpose"],
      "properties":{
        "title":{"type":"string"},
        "language":{"type":"string","enum":["zh-CN","en-US"]},
        "purpose":{"type":"string","enum":["pitch","report","tutorial","demo","training"]}
      }
    },
    "design_system":{
      "type":"object","additionalProperties":false,
      "required":["theme","font_scale","density"],
      "properties":{
        "theme":{"type":"string"},
        "font_scale":{"type":"string","enum":["sm","md","lg"]},
        "density":{"type":"string","enum":["compact","normal","airy"]}
      }
    },
    "slides":{
      "type":"array","minItems":1,
      "items":{
        "type":"object","additionalProperties":false,
        "required":["id","layout","title","components","speaker_notes"],
        "properties":{
          "id":{"type":"string"},
          "layout":{"type":"string","enum":["title","section","content","two-column","image+text","chart","closing"]},
          "title":{"type":"string"},
          "components":{
            "type":"array",
            "items":{
              "type":"object","additionalProperties":false,
              "required":["type","data"],
              "properties":{
                "type":{"type":"string","enum":["bullets","paragraph","image","chart","table","quote","callout"]},
                "data":{"type":"object"}
              }
            }
          },
          "speaker_notes":{"type":"string"}
        }
      }
    },
    "assets":{
      "type":"object","additionalProperties":false,
      "required":["images","charts"],
      "properties":{
        "images":{"type":"array","items":{"type":"string"}},
        "charts":{"type":"array","items":{"type":"string"}}
      }
    }
  }
}

4) 强制“编辑=diff”规范（避免模型重写整份 input）

规则：
  • create：edit_spec.strategy = none
  • edit：edit_spec.strategy = diff 且必须提供 base_artifact_id + diff
  • diff 只允许操作白名单路径（如 /scene, /slides, /timeline 等），其余路径拒绝

4.1 diff 示例（删除图片中右下角贴纸）

{
  "strategy":"diff",
  "base_artifact_id":"img_abc123",
  "diff":[
    {"op":"add","path":"/edit/operations/0","value":{
      "op":"remove",
      "target":{"description":"small red sticker","location_hint":"bottom-right"},
      "fill":"continue the laptop lid material seamlessly",
      "guardrails":{"do_not_change":["face","hands","camera","lighting","all other objects"]}
    }},
    {"op":"set","path":"/preserve/all_other_objects","value":"locked"}
  ]
}

5) 输出层硬约束（模型返回必须可被强解析）

5.1 统一 Result 包装（建议所有 agent 输出都包一层）

{
  "result": {
    "artifact_id": "string",
    "artifact_type": "image|video|ppt",
    "metadata": { "seed": 0, "deterministic_level": "mid" },
    "payload": { }
  }
}

5.2 错误格式（唯一允许的失败输出）

{
  "error":{
    "code":"SCHEMA_VALIDATION_FAILED|DIFF_APPLY_FAILED|UNSUPPORTED_REQUEST|SAFETY_BLOCKED|TOOL_FAILURE",
    "message":"string",
    "details":[{"path":"/input/..","reason":"string"}]
  }
}

6) 质量闸门（必须做的自动化测试）

Contract Tests（建议写成 CI）：
  • Parse Test：随机 fuzz 输入，确保非 YAML/JSON 必失败；边界语法（YAML 多文档/锚点）必失败。
  • Schema Test：Envelope/Task/Result 三层 schema 全覆盖；additionalProperties 生效。
  • No Extra Text Test：输出前后加空格/换行可接受，但任何非结构字符（例如解释句子）必须失败。
  • Replay Test：同 input + seed + deterministic_level（high） → 产物 hash 尽量稳定。

7) 三个完整示例（你可直接复制到平台请求）

7.1 Image Edit（JSON）

{
  "version":"1.1",
  "request_id":"req_img_001",
  "timestamp_ms":0,
  "agent":{"type":"image","name":"image-agent","mode":"edit"},
  "task":{"name":"remove_object","intent":"remove sticker","constraints":{"strict":true,"deterministic_level":"high"}},
  "context":{"project":"agent-platform","user_locale":"zh-CN","seed":42,"memory":{"enabled":false}},
  "input":{
    "scene":{"prompt":"A laptop on a wooden desk, photorealistic","style":"photorealistic","camera":"35mm, shallow DOF","lighting":"soft daylight","objects":["laptop","desk","keyboard","mug"]},
    "render":{"size":"1024x1024","num_outputs":1},
    "edit":{"operations":[]},
    "preserve":{"identity":"locked","composition":"locked","lighting":"locked","style":"locked","all_other_objects":"locked"}
  },
  "edit_spec":{
    "strategy":"diff",
    "base_artifact_id":"img_abc123",
    "diff":[
      {"op":"add","path":"/edit/operations/0","value":{
        "op":"remove",
        "target":{"description":"small red sticker on laptop lid","location_hint":"bottom-right"},
        "fill":"continue the laptop lid material seamlessly",
        "guardrails":{"do_not_change":["camera","lighting","desk texture","all other objects"]}
      }}
    ]
  },
  "tooling":{"allowed_tools":["render_image"],"io_budget":{"max_steps":6,"max_tokens":8000}},
  "output_spec":{"format":"json","schema":"https://yourdomain/schemas/result-1.json","language":"zh-CN","verbosity":"low"},
  "policy":{"no_extra_text":true,"no_markdown":true,"no_hidden_steps":true,"safe_mode":true}
}

7.2 Video Create（YAML）

version: "1.1"
request_id: "req_vid_001"
timestamp_ms: 0
agent:
  type: "video"
  name: "video-agent"
  mode: "create"
task:
  name: "brand_bumper"
  intent: "5s logo bumper"
  constraints:
    strict: true
    deterministic_level: "mid"
context:
  project: "agent-platform"
  user_locale: "zh-CN"
  seed: 7
  memory:
    enabled: false
input:
  timeline:
    duration_s: 5
    shots:
      - id: "s1"
        start_s: 0
        end_s: 5
        scene: "Minimal dark background with subtle particles"
        camera: "static, center composition"
        motion: "particles slow drift, logo fades in"
        locks:
          identity: true
          style: true
  render:
    fps: 30
    resolution: "1080p"
  audio:
    music: "short cinematic whoosh"
    sfx: ["subtle whoosh at 0.7s"]
    voiceover:
      enabled: false
      script: ""
  preserve:
    main_character_identity: "locked"
    color_grade: "locked"
    composition: "locked"
edit_spec:
  strategy: "none"
  base_artifact_id: null
  diff: []
tooling:
  allowed_tools: ["render_video"]
  io_budget:
    max_steps: 8
    max_tokens: 12000
output_spec:
  format: "yaml"
  schema: "https://yourdomain/schemas/result-1.json"
  language: "zh-CN"
  verbosity: "low"
policy:
  no_extra_text: true
  no_markdown: true
  no_hidden_steps: true
  safe_mode: true

7.3 PPT Create（JSON）

{
  "version":"1.1",
  "request_id":"req_ppt_001",
  "timestamp_ms":0,
  "agent":{"type":"ppt","name":"ppt-agent","mode":"create"},
  "task":{"name":"product_pitch","intent":"10 slides pitch","constraints":{"strict":true,"deterministic_level":"mid"}},
  "context":{"project":"agent-platform","user_locale":"zh-CN","seed":99,"memory":{"enabled":false}},
  "input":{
    "deck":{"title":"智能体平台产品介绍","language":"zh-CN","purpose":"pitch"},
    "design_system":{"theme":"clean-tech","font_scale":"md","density":"normal"},
    "slides":[
      {"id":"1","layout":"title","title":"智能体平台","components":[{"type":"paragraph","data":{"text":"视频/图片/PPT 一体化智能体编排"}}],"speaker_notes":"开场 15 秒"},
      {"id":"2","layout":"content","title":"为什么需要硬约束提示词","components":[{"type":"bullets","data":{"items":["可校验","可回放","可灰度","可审计"]}}],"speaker_notes":"强调工程化"}
    ],
    "assets":{"images":[],"charts":[]}
  },
  "edit_spec":{"strategy":"none","base_artifact_id":null,"diff":[]},
  "tooling":{"allowed_tools":["build_ppt"],"io_budget":{"max_steps":10,"max_tokens":16000}},
  "output_spec":{"format":"json","schema":"https://yourdomain/schemas/result-1.json","language":"zh-CN","verbosity":"low"},
  "policy":{"no_extra_text":true,"no_markdown":true,"no_hidden_steps":true,"safe_mode":true}
}
落地建议（最小可用实现 MVP）：
  • 先把 v1.1 Envelope + 三个 Task Schema + Result Schema 落地，跑通 Parse/Validate/Route。
  • 再加 Compiler（locks 注入 + diff 应用）与 Contract Tests（CI）。
  • 最后把 deterministic_level 做成三档：low(更自由) / mid(默认) / high(强锁)。