Prompt Contract v1.1 - 智能体平台结构化合约系统

原创灵阙教研团队

A 推荐进阶 | 约 8 分钟阅读更新于 2025-12-25

AI 导读

Prompt Contract v1.1 - 智能体平台结构化合约系统可校验、可编译、可回放的提示词工程化方案概述 Prompt Contract v1.1 将传统的"散装提示词"升级为结构化合约，实现：可校验：三层 Schema 校验（Envelope → Task → Result）可编译：Prompt Compiler 自动注入 locks、negative、工具配置可回放：同...

Prompt Contract v1.1 - 智能体平台结构化合约系统

可校验、可编译、可回放的提示词工程化方案

概述

Prompt Contract v1.1 将传统的"散装提示词"升级为结构化合约，实现：

可校验：三层 Schema 校验（Envelope → Task → Result）
可编译：Prompt Compiler 自动注入 locks、negative、工具配置
可回放：同 input + seed + deterministic_level → 产物一致

架构设计

┌─────────────────────────────────────────────────────────────────┐
│                     Prompt Contract v1.1                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   用户请求 (YAML/JSON)                                           │
│        │                                                        │
│        ▼                                                        │
│   ┌──────────────┐                                              │
│   │ Parse Layer  │  严格解析，禁止非 YAML/JSON                    │
│   └──────┬───────┘                                              │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────┐                                              │
│   │ Envelope     │  统一信封校验                                  │
│   │ Validation   │  version, agent, task, context...            │
│   └──────┬───────┘                                              │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────┐     ┌─────────────────┐                      │
│   │ Task Schema  │ ──▶ │ image-task-1.1  │                      │
│   │ Routing      │     │ video-task-1.1  │                      │
│   └──────┬───────┘     │ ppt-task-1.1    │                      │
│          │             │ audio-task-1.1  │                      │
│          │             └─────────────────┘                      │
│          ▼                                                      │
│   ┌──────────────┐                                              │
│   │ Prompt       │  应用 diff, 生成 locks, 派生 negative         │
│   │ Compiler     │                                              │
│   └──────┬───────┘                                              │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────┐                                              │
│   │ Model        │  模型可执行指令                                │
│   │ Instruction  │                                              │
│   └──────┬───────┘                                              │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────┐                                              │
│   │ Agent        │  video / image / ppt 执行器                   │
│   │ Executor     │                                              │
│   └──────┬───────┘                                              │
│          │                                                      │
│          ▼                                                      │
│   ┌──────────────┐                                              │
│   │ Result       │  统一输出校验                                  │
│   │ Validation   │                                              │
│   └──────────────┘                                              │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

文件结构

packages/contracts/
├── envelope-1.1.json       # 统一信封 Schema
├── image-task-1.1.json     # 图像任务 Schema
├── video-task-1.1.json     # 视频任务 Schema
├── ppt-task-1.1.json       # PPT 任务 Schema
├── result-1.1.json         # 结果 Schema（含错误）
├── model-instruction-1.json # 编译输出 Schema
├── index.ts                # TypeScript 类型 + 校验器
├── compiler.ts             # Prompt Compiler
├── contract.test.ts        # Contract Tests
├── package.json
└── tsconfig.json

核心概念

1. Envelope（统一信封）

所有请求必须包装在 Envelope 中：

{
  "version": "1.1",
  "request_id": "req_img_001",
  "agent": { "type": "image", "mode": "edit" },
  "task": {
    "name": "remove_object",
    "constraints": { "strict": true, "deterministic_level": "high" }
  },
  "context": { "project": "...", "seed": 42, "memory": { "enabled": false } },
  "input": { /* Task-specific input */ },
  "edit_spec": { "strategy": "diff", "diff": [...] },
  "tooling": { "allowed_tools": ["render_image"], "io_budget": { "max_steps": 8 } },
  "output_spec": { "format": "json", "language": "zh-CN" },
  "policy": { "no_extra_text": true, "no_markdown": true }
}

2. 四类智能体

类型	用途	特点
`image`	图像生成/编辑	scene + edit + preserve
`video`	视频生成/编辑	timeline + shots + audio
`ppt`	演示文稿生成	deck + slides + components
`audio`	音频生成/处理	tts + music + sfx + transcription

3. 执行模式

模式	用途	edit_spec.strategy
`create`	新建	`none`
`edit`	编辑（基于现有产物）	`diff`
`analyze`	分析（只读）	`none`

4. 确定性级别

级别	用途	locks 程度
`low`	创意发挥	最少锁定
`mid`	默认平衡	中等锁定
`high`	精确复现	最大锁定

使用示例

图像编辑（删除贴纸）

{
  "version": "1.1",
  "request_id": "req_img_001",
  "agent": { "type": "image", "mode": "edit" },
  "task": {
    "name": "remove_sticker",
    "constraints": { "strict": true, "deterministic_level": "high" }
  },
  "input": {
    "scene": {
      "prompt": "A laptop on a desk",
      "style": "photorealistic",
      "camera": "35mm",
      "lighting": "soft daylight",
      "objects": ["laptop", "desk"]
    },
    "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": "red sticker", "location_hint": "bottom-right" },
          "fill": "continue laptop lid seamlessly",
          "guardrails": { "do_not_change": ["camera", "lighting"] }
        }
      }
    ]
  },
  "tooling": { "allowed_tools": ["render_image"], "io_budget": { "max_steps": 6 } }
}

视频创建（品牌片头）

version: "1.1"
request_id: "req_vid_001"
agent:
  type: "video"
  mode: "create"
task:
  name: "brand_bumper"
  constraints:
    strict: true
    deterministic_level: "mid"
input:
  timeline:
    duration_s: 5
    shots:
      - id: "s1"
        start_s: 0
        end_s: 5
        scene: "Dark background with particles"
        camera: "static"
        motion: "logo fades in"
        locks: { identity: true, style: true }
  render: { fps: 30, resolution: "1080p" }
  audio:
    music: "cinematic whoosh"
    sfx: ["whoosh at 0.7s"]
    voiceover: { enabled: false, script: "" }
  preserve:
    main_character_identity: "locked"
    color_grade: "locked"

PPT 创建

{
  "version": "1.1",
  "agent": { "type": "ppt", "mode": "create" },
  "task": { "name": "product_pitch", "constraints": { "strict": true, "deterministic_level": "mid" } },
  "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": "一站式智能体编排" } }],
        "speaker_notes": "开场介绍"
      }
    ],
    "assets": { "images": [], "charts": [] }
  }
}

音频创建（语音合成）

{
  "version": "1.1",
  "request_id": "req_audio_001",
  "agent": { "type": "audio", "mode": "create" },
  "task": {
    "name": "tts_generation",
    "constraints": { "strict": true, "deterministic_level": "mid" }
  },
  "context": {
    "project": "podcast",
    "user_locale": "zh-CN",
    "seed": 42,
    "memory": { "enabled": false }
  },
  "input": {
    "audio_type": "speech",
    "tts": {
      "text": "欢迎收听今天的播客节目，我是你们的主持人。",
      "voice": "female_warm",
      "language": "zh-CN",
      "speed": 1.0,
      "emotion": "happy",
      "style": "casual"
    },
    "render": {
      "format": "mp3",
      "quality": "high",
      "sample_rate": "44100",
      "channels": "stereo"
    }
  },
  "edit_spec": { "strategy": "none", "base_artifact_id": null, "diff": [] },
  "tooling": {
    "allowed_tools": ["synthesize_audio"],
    "io_budget": { "max_steps": 4, "max_tokens": 4000 }
  },
  "output_spec": { "format": "json", "schema": "result-1.1", "language": "zh-CN", "verbosity": "low" },
  "policy": { "no_extra_text": true, "no_markdown": true, "no_hidden_steps": true, "safe_mode": true }
}

音频分析（转录）

{
  "version": "1.1",
  "request_id": "req_audio_002",
  "agent": { "type": "audio", "mode": "analyze" },
  "task": {
    "name": "transcription",
    "constraints": { "strict": true, "deterministic_level": "high" }
  },
  "input": {
    "audio_type": "speech",
    "transcription": {
      "source_url": "https://storage.example.com/audio/meeting.mp3",
      "language": "zh-CN",
      "timestamps": true,
      "speaker_diarization": true,
      "punctuation": true
    },
    "render": {
      "format": "mp3",
      "quality": "standard"
    }
  }
}

音乐生成

version: "1.1"
request_id: "req_music_001"
agent:
  type: "audio"
  mode: "create"
task:
  name: "background_music"
  constraints:
    strict: true
    deterministic_level: "mid"
input:
  audio_type: "music"
  music:
    prompt: "轻松愉快的企业宣传片背景音乐，电子风格"
    genre: "electronic"
    mood: "uplifting"
    tempo_bpm: 120
    duration_s: 60
    instruments:
      - synth
      - piano
      - drums
  render:
    format: "wav"
    quality: "high"
    sample_rate: "48000"
  preserve:
    tempo: "locked"
    dynamics: "flexible"

API 端点

POST /api/creative/execute

执行创意智能体任务。

请求体：Envelope v1.1 格式的 JSON/YAML

响应体：Result v1.1 格式

成功响应：

{
  "result": {
    "artifact_id": "img_001",
    "artifact_type": "image",
    "metadata": {
      "seed": 42,
      "deterministic_level": "high",
      "duration_ms": 1234
    },
    "payload": { /* 任务特定输出 */ }
  }
}

错误响应：

{
  "error": {
    "code": "SCHEMA_VALIDATION_FAILED",
    "message": "Input validation failed",
    "details": [{ "path": "/input/scene", "reason": "missing prompt" }],
    "retryable": false
  }
}

错误代码

代码	含义	可重试
`PARSE_ERROR`	JSON/YAML 解析失败	否
`ENVELOPE_VALIDATION_FAILED`	信封校验失败	否
`TASK_VALIDATION_FAILED`	任务输入校验失败	否
`DIFF_APPLY_FAILED`	差分应用失败	否
`UNSUPPORTED_AGENT_TYPE`	不支持的智能体类型	否
`SAFETY_BLOCKED`	安全策略阻止	否
`TOOL_FAILURE`	工具执行失败	是
`TIMEOUT`	执行超时	是
`RATE_LIMITED`	速率限制	是

Contract Tests（质量闸门）

# 运行测试
cd packages/contracts
npm test

# 测试覆盖
# 1. Parse Test - 严格 YAML/JSON 解析
# 2. Schema Test - 三层 Schema 校验
# 3. No Extra Text Test - 禁止非结构字符
# 4. Replay Test - 可重复性验证

最佳实践

1. 始终使用严格模式

"task": {
  "constraints": { "strict": true, "deterministic_level": "mid" }
}

2. 编辑模式必须提供 base_artifact_id

"edit_spec": {
  "strategy": "diff",
  "base_artifact_id": "img_abc123",  // 必须
  "diff": [...]
}

3. 使用 preserve 锁定关键元素

"preserve": {
  "identity": "locked",      // 主体身份不变
  "composition": "locked",   // 构图不变
  "style": "locked"          // 风格不变
}

4. 设置合理的 io_budget

"tooling": {
  "io_budget": {
    "max_steps": 8,          // 最大步数
    "max_tokens": 8000       // 最大 token
  }
}

5. 启用 safe_mode

"policy": {
  "safe_mode": true          // 内容安全检查
}

迁移指南

从旧版 API 迁移

旧版（非结构化）：

{
  "prompt": "Remove the sticker from the laptop",
  "model": "dall-e-3"
}

新版（Prompt Contract v1.1）：

{
  "version": "1.1",
  "agent": { "type": "image", "mode": "edit" },
  "input": {
    "scene": { "prompt": "...", ... },
    "edit": {
      "operations": [{
        "op": "remove",
        "target": { "description": "sticker" },
        "fill": "...",
        "guardrails": { "do_not_change": [...] }
      }]
    }
  }
}

路线图

v1.1 - 基础 Schema + Compiler
v1.2 - 多模态输入支持
v1.3 - 工作流编排集成
v2.0 - 实时流式输出

猪哥云（四川）网络科技有限公司 | 合规网 www.hegui.com 猪哥云-数据产品部-Maurice | maurice_wen@proton.me 2025 猪哥云-灵阙企业级智能体平台