carry/Prompt-Envelope-Protocol
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
28 Commits 1 Branch 0 Tags
main
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE

README.md

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

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

导出兼容

协议可无损导出为标准 OpenAI Chat Completions 格式（{ model, messages, tools }），确认此设计不是"另一种 agent 运行时"，而是一种对标准协议的格式化表达层。

技术实现

技术栈

层 选型
框架 React 18 + TypeScript
构建 Vite
样式 Tailwind CSS
图标 Lucide React
Markdown react-markdown + remark-gfm
测试 Vitest

MVP 范围

  • ✅ 纯前端 React 应用，无后端、无真实 LLM 调用
  • ✅ 6 个 Demo 场景（A–F），覆盖全部 Segment 类型
  • ✅ 双栏布局：对话视图 + 协议面板（实时 JSON 预览）
  • ✅ 双 Tab 协议面板：OpenAI Format / Raw Protocol，支持复制和下载
  • ✅ 4 个真实 Anthropic SKILL.md 文件加载 + parseSkillMarkdown() 自研解析器
  • ✅ 26 个单元测试覆盖导出逻辑和 SKILL.md 解析
  • ❌ 不接入真实 LLM API
  • ❌ 不做后端/数据库/用户认证

快速开始

git clone <this-repo>
cd hci
npm install
npm run dev       # 启动开发服务器 → http://localhost:5173
npm test          # 运行全部 26 个单元测试
npm run build     # 生产构建

文件概览

src/
├── types/protocol.ts              # 协议类型定义（11 种 Segment）
├── utils/
│   ├── export.ts                  # 导出 → OpenAI Chat Format
│   └── parseSkill.ts             # SKILL.md YAML 解析器（自研）
├── data/
│   ├── demos/                     # 6 个 Demo JSON 文件 + manifest
│   │   └── demos-loader.ts       # 运行时验证 + skill body 水合
│   ├── skills.ts                 # 8 个手写自定义 skill
│   ├── skills-loader.ts          # 4 个真实 Anthropic SKILL.md
│   └── skills/                   # SKILL.md 源文件
├── components/
│   ├── SegmentRenderer.tsx        # 按 kind 路由分发
│   ├── CollapsiblePanel.tsx       # 通用折叠容器
│   ├── MarkdownRenderer.tsx       # 共享 Markdown 渲染（所有文本组件）
│   ├── MessageList.tsx            # 消息预处理 + 列表
│   ├── MessageBubble.tsx          # 消息气泡容器
│   ├── SessionBar.tsx             # 会话变量横栏
│   ├── ProtocolPanel.tsx          # 右侧协议面板（双 Tab）
│   └── segments/                  # 11 个 Segment View 组件
├── context/ChatContext.tsx        # 全局状态
├── __tests__/
│   ├── export.test.ts            # 导出逻辑（~20 个用例）
│   └── parseSkill.test.ts        # SKILL.md 解析（7 个用例）
└── App.tsx                        # 顶层布局

设计反思

这个项目本质上在探索一个更根本的问题：当一条"聊天消息"背后实际是十几个上下文组件拼接而成的结构化文档，聊天界面该怎样诚实地呈现它？

传统的聊天界面诞生于"人对人"的隐喻——一个输入框，一个输出框。但当这个输入框背后连接的是一个拥有 system prompt、记忆、工具声明和变量注入的复杂 prompt 构造系统时，把一切封装在简单的 chat bubble 里就是在对用户撒谎。用户以为自己发送的是纯文本，实际被发送的是一份经过大量预处理的复合文档。

Prompt Envelope Protocol 尝试将"人机对话"的界面从隐藏复杂性的 textarea 升级为诚实可见的信息架构。让对话保持流畅，同时让 prompt 的真实组成变得可见。这不是一个关于"AI 在做什么"的设计——这是关于"你到底对 AI 说了什么"的设计。

Reference in New Issue View Git Blame Copy Permalink
S
Description
No description provided
Readme 248 KiB
Languages
TypeScript 99.3%
CSS 0.3%
HTML 0.2%
JavaScript 0.2%