carry/Prompt-Envelope-Protocol

Fork 0

Files

T

carry bce0f40f0c feat: 更新 README.md，重构 Prompt Envelope Protocol 方案，明确协议层与 UI 层的设计原则及 Segment 类型

2026-06-09 15:52:59 +08:00

13 KiB

Raw Permalink Blame History

Prompt Envelope Protocol

让 LLM 上下文在聊天界面中可见、可读、可理解。

问题：Prompt 被过度封装，用户不知道真正的输入是什么

以 ChatGPT、Claude 为代表的 AI 聊天产品已拥有数亿用户。这些产品的交互界面模拟的是「人对人」的对话——一个输入框，一段回复。用户看到自己打了一句话，AI 回了一句话。

但模型真正收到的，远不止这句话。

在用户输入的文本被发送给 LLM 之前，系统在后台拼接了大量的上下文：

System Prompt —— 决定了回复的风格、边界、角色设定
User Memory —— 跨对话持久化的用户画像，在每次请求时被注入
Tools & Skills 的声明 —— 函数签名、JSON Schema、触发条件的完整描述
模板变量的值 —— {{user_name}} 被替换为"小明"，但用户看到的是变量名还是值？

对于普通用户，这可能无所谓。但对于需要精确控制模型行为的进阶用户（开发者、研究者、prompt engineer），这种不透明是致命的：

你精心设计了一段 prompt，但不知道 system prompt 是否和它冲突
你修改了一条 memory，但不确定新的值是否真的被注入了每一次请求
你添加了一个 tool，但看不到它的 schema 在上下文中以什么形式出现
你粘贴了一篇长论文，但不知道全文都被包含还是被截断
你看到 AI 回复了错误结果，但无法排查是哪个上下文片段导致了问题

界面上看起来是「一句话的对话」，实际发送给模型的是一份由十几个组件拼接而成的结构化文档。 聊天 UI 对这一切做了完全的封装——把复杂的 prompt 构造过程包装成了一个简单的 textarea。

这个问题不是"看不到 AI 的推理过程"，而是"看不到自己的输入到底是什么"。

设计问题

当前的聊天界面将 prompt 构造的复杂性过度封装在单一输入框中。用户以为自己发送的是文本，实际发送的是一个经过层层拼接的复合体。界面模拟的是"人说了一句话"的隐喻，但模型侧的真实情况是"一份多来源、多类型、多优先级的结构化上下文文档"。

HCI 告诉我们：界面的信息架构应该反映系统的心智模型。当用户不知道模型真正收到了什么，他们就无法调试、无法精确控制、无法建立信任。

方案：Prompt Envelope Protocol

本项目的答案是两层设计：

协议层 —— 一种结构化的数据格式，用带类型的 Segment 描述 LLM 上下文
UI 层 —— 一个参考实现，展示协议如何被渲染为可读的聊天界面

协议：每条消息 = Segments 的有序列表

协议定义的不是"聊天文本"，而是上下文的结构化描述。一条消息不再是字符串，而是若干带明确 kind 的 Segment：

一条消息不是 "你好，帮我审阅这篇论文"
而是：
  ├─ text segment          "你好，帮我审阅这篇论文"
  ├─ long_text segment     [论文全文，1423 字]
  ├─ document segment      paper-draft.pdf (2.3MB)
  └─ media segment         image: 图3 实验组vs对照组

每个 Segment 的 kind 字段声明了"这是一段什么"，其余字段携带数据本身。协议只关心 types 和 structure，不关心颜色、折叠、布局——那是 UI 层的决策。

UI：每种类型有独立视觉呈现

在本项目的参考实现中，每种 Segment 被渲染为不同的视觉组件。例如 system prompt 是折叠面板，工具请求是代码块，变量在会话横栏中展示。但这只是一种可能的 UI，协议本身与视觉无关。

设计原则

协议原则：

原则	说明
类型明确	每种上下文有独立的 Segment kind，无一物混在文本中
可导出	协议可无损导出为标准 OpenAI Chat Format，不被本项目 UI 绑定
自描述	协议数据不依赖外部渲染逻辑——kind 字段即语义标签

UI 原则（本项目的参考实现）：

原则	说明
信息密度梯度	核心对话文本优先可见；元信息默认折叠
颜色编码	不同类型用不同颜色辅助区分，形成可学习的视觉语言
折叠默认值在数据中	segment 的 `collapsed` 字段指定默认状态，保证数据自足

协议：11 种 Segment 类型

通过对主流 LLM 聊天产品的逆向分析，我们识别出 LLM 上下文中 11 种需要区分类型的信息。每种在协议中对应一个 Segment kind。

text

用户和 AI 的直接对话文本。协议中最基本的 Segment。

{ kind: 'text', content: string }

static_var

会话级模板变量，在对话开始时被替换为具体值。协议中携带变量名和展开后的值，使替换关系可见。

{ kind: 'static_var', name: string, value: string, description?: string }

system_prompt

模型的行为准则和角色设定。协议中为完整文本内容，可标记折叠默认状态。

{ kind: 'system_prompt', content: string, collapsed: boolean }

memory

跨对话持久化的用户信息，以标题-内容条目组织。协议中为记忆项列表。

{ kind: 'memory', items: MemoryItem[], collapsed: boolean, description?: string }

skills

模型可调用的技能，遵循 Anthropic SKILL.md 规范。协议中每项包含 name、description（L1 始终在上下文）和 body（L2 触发时加载的 Markdown 正文）。

{ kind: 'skills', items: SkillItem[], collapsed: boolean, description?: string }

tool_overview

模型可用的工具清单。每项包含名称、描述、参数摘要和可选的 JSON Schema 定义。

{ kind: 'tool_overview', items: ToolItem[], collapsed: boolean }

tool_call_request

模型发起的工具调用。协议中携带函数名和参数键值对。

{ kind: 'tool_call_request', toolName: string, arguments: Record<string, unknown>, collapsed: boolean }

tool_call_result

工具调用的执行结果。协议中标记成功/失败状态和结果文本。

{ kind: 'tool_call_result', toolName: string, result: string, success: boolean, collapsed: boolean }

document

用户上传的文件。协议中存储文件名、MIME 类型、大小和文本预览，可附带解析后的完整内容。

{ kind: 'document', fileName: string, mimeType: string, snippet: string, sizeBytes: number, parsedContent?: string }

long_text

用户粘贴的长篇文本素材。协议中携带完整内容和字符数，可标记折叠默认状态。

{ kind: 'long_text', content: string, charCount: number, collapsed: boolean }

media

图片、音频、视频等多模态内容。协议中记录媒体类型、URL 和替代文本。

{ kind: 'media', mediaType: 'image'|'audio'|'video', url: string, altText?: string }

UI 参考实现：差异化视觉呈现

以上是协议层——定义了什么信息存在、以什么结构存在。以下是本项目为协议做的参考 UI。颜色、折叠行为、布局都是 UI 决策，不是协议规范。

Segment	UI 处理	交互
`text`	正文渲染，支持 Markdown	无交互
`static_var`	提取到对话区顶部的会话变量横栏，不在气泡内	纯展示
`system_prompt`	折叠面板，灰色标记，标注行数	点击展开
`memory`	折叠面板，紫色标记，展开为标题-内容列表	点击展开
`skills`	折叠面板，绿色标记，每项支持渐进式披露（L1 名称+描述 → L2 body）	逐层点击展开
`tool_overview`	折叠面板，橙色标记，每项可独立展开 JSON Schema	点击展开
`tool_call_request`	深色终端风格代码块，参数以标签化键值行展示	默认展开；长值折叠
`tool_call_result`	绿色（成功）/ 红色（失败）状态条	成功默认折叠，失败默认展开
`document`	文件卡片：图标 + 文件名 + 大小 + 文本预览	可展开 AI 解析内容
`long_text`	折叠态前 2 行预览 + 字数标签	点击展开全文
`media`	图片有 URL 时可渲染缩略图；其他类型图标占位	加载失败回退为图标

完整类型定义见 src/types/protocol.ts。

协议格式

Prompt Envelope（顶层文档）

interface PromptEnvelope {
  version: '1.0'
  model?: string            // 导出时使用的模型名
  messages: Message[]
}

Message（单条消息）

interface Message {
  id: string
  role: 'system' | 'user' | 'assistant' | 'tool'
  segments: Segment[]       // 有序的片段列表
  timestamp: number
}

Segment（片段联合类型）

每种 Segment 有独有的 kind 字段，标识其语义类型：

text | static_var | system_prompt | memory | skills |
tool_overview | tool_call_request | tool_call_result |
document | long_text | media