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 | [email protected] 2025 猪哥云-灵阙企业级智能体平台

深度加工（NotebookLM 生成）

基于本文内容生成的 PPT 大纲、博客摘要、短视频脚本与 Deep Dive 播客，用于多场景复用

PPT 大纲（5-8 张幻灯片）点击展开

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

基于您提供的《Prompt Contract v1.1 - 智能体平台结构化合约系统》文章，我为您生成了一份 7 张幻灯片的 PPT 大纲，格式已按照要求输出：

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

系统概述：将传统的“散装提示词”全面升级为结构化合约方案 [1]。
可校验能力：提供 Envelope、Task 到 Result 的三层 Schema 严格校验 [1]。
可编译特性：通过 Prompt Compiler 自动注入锁存（locks）、负面提示（negative）及工具配置 [1]。
可回放保障：确保在相同的输入、种子（seed）和确定性级别下，输出产物保持一致 [1]。

幻灯片 2：系统核心架构设计

严格解析层 (Parse Layer)：仅允许合规格式，严格解析并禁止非 YAML/JSON 数据 [1]。
统一校验与路由：经过 Envelope 信封校验后，按照任务类型路由至图像、视频、PPT 或音频专属 Schema [1]。
提示词编译器 (Prompt Compiler)：应用内容差异（diff），生成 locks 并派生模型所需参数 [1]。
执行与结果验证：生成模型可执行指令交由 Agent Executor 处理，最后进行统一的 Result 输出校验 [1]。

幻灯片 3：系统四大核心概念

统一信封（Envelope）：所有请求必须包装在统一的 Envelope 中，明确版本、智能体、任务和上下文等字段 [1]。
四类智能体类型：支持 image（图像）、video（视频）、ppt（演示文稿）和 audio（音频）四类多模态智能体 [2]。
三种执行模式：支持新建（create）、基于现有产物差异编辑（edit/diff）以及只读分析（analyze）[2]。
确定性级别（Deterministic Level）：通过 low、mid、high 三个级别来控制 locks 的程度，平衡创意发挥与精确复现 [2]。

幻灯片 4：多模态智能体应用场景

图像生成与编辑：可通过 preserve 锁定主体身份、构图、光影及风格，实现精准的局部对象修改（如删除贴纸）[2, 3]。
视频创建：支持结构化定义时间轴（timeline）、镜头时长、摄影机运动轨迹和音效配置 [3, 4]。
PPT 生成：基于指定的设计系统（主题、字体缩放系数），将包含标题与组件数据的结构排版为演示文稿 [4]。
音频处理矩阵：覆盖情感化语音合成（TTS）、会议记录多说话人转录（Transcription）及具备特定流派和BPM的音乐生成 [4-6]。

幻灯片 5：API 端点与错误处理机制

核心执行端点：通过 POST /api/creative/execute 统一执行所有创意智能体任务 [6]。
标准请求与响应：请求体使用 Envelope v1.1 格式，成功响应则返回包含工件 ID 与元数据的 Result v1.1 格式 [6]。
细粒度错误反馈：错误响应会精确定位到校验失败的具体路径及原因（例如 missing prompt）[6, 7]。
错误代码体系：内置解析失败、校验失败、超时、速率限制等错误码，并明确标识该错误是否可重试 [7]。

幻灯片 6：质量闸门与最佳实践

Contract Tests（质量闸门）：通过严格解析测试、Schema 校验、禁止多余字符测试及可重复性验证保障系统稳定性 [7]。
启用严格模式：推荐始终在任务约束中设置 "strict": true 并匹配适当的确定性级别 [7]。
编辑与锁定规范：编辑模式下必须提供基础工件 ID (base_artifact_id)，并善用 preserve 锁定关键元素 [7]。
安全与预算控制：建议启用内容安全检查 (safe_mode)，并为工具执行设定合理的步数与 token 预算 (io_budget) [7]。

幻灯片 7：迁移指南与未来演进路线图

向后兼容与迁移：指引用户从传统的非结构化 prompt 请求，迁移到基于场景、操作和护栏配置的结构化 API 中 [7]。
v1.1 现状：目前已奠定基础 Schema 和 Compiler 编译器的核心能力 [7]。
v1.2 - v1.3 规划：后续路线将支持多模态输入（v1.2），并深度集成工作流编排（v1.3）[7]。
v2.0 长远目标：最终计划实现智能体实时流式输出，提升全链路响应体验 [7]。

博客摘要 + 核心看点点击展开

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

SEO 友好博客摘要
想要提升提示词工程的稳定性？本文深入解析智能体平台的 Prompt Contract v1.1 结构化合约系统 [1]。该方案将传统散装提示词全面升级，实现可校验（三层Schema校验）、可编译与可回放的强大能力 [1]。文章详细梳理了图像、视频、PPT及音频四类多模态智能体的应用场景 [2]，并提供详尽的API规范与工程最佳实践 [3, 4]，助您轻松实现高效、合规的智能体编排与落地。

3 条核心看点