feat: 添加 Prompt Envelope Protocol 设计文档，定义协议结构与数据模型

2026-06-08 21:17:59 +08:00
parent d04c85d959
commit 31099d479c
1 changed files with 591 additions and 0 deletions
@@ -0,0 +1,591 @@
+# Prompt Envelope Protocol 设计文档
+
+> **版本**：1.0
+> **更新日期**：2026 年 6 月 8 日
+
+---
+
+## 1. 概述
+
+**Prompt Envelope Protocol** 是一套让 LLM 上下文在聊天界面中可见化的协议与 UI 系统。
+
+传统聊天应用中，system prompt、memory、tools、skills、文档等上下文对用户是**不可见**的——它们被框架悄悄拼接到 prompt 中，用户无法知晓模型"看到了什么"。Prompt Envelope 将每条聊天消息拆解为若干带类型的 **Segment**，每种 Segment 有独立的视觉呈现，让隐藏的上下文成为可见的一等元素。
+
+### 核心理念
+
+```
+传统模式：                      Prompt Envelope：
+┌─────────────┐                 ┌──────────────────────┐
+│  原始文本     │                 │  Message              │
+│  (用户不可见  │                 │ ├─ 🔵 变量 badge       │
+│   的上下文)   │                 │ ├─ 📋 System Prompt   │
+└─────────────┘                 │ ├─ 🧠 Memory          │
+                                │ ├─ 🛠️ Tools           │
+                                │ ├─ ⚡ Skills          │
+                                │ └─ 💬 Text            │
+                                └──────────────────────┘
+```
+
+### 适用场景
+
+- 调试 LLM 行为——理解模型为什么给出某个回复
+- 教育——展示 LLM 上下文的组成结构
+- HCI 研究——探索上下文透明性对用户体验的影响
+- 协议标准化——跨平台、跨模型的统一上下文表示
+
+---
+
+## 2. 数据模型
+
+协议采用三层结构：**Envelope → Message → Segment**。
+
+```
+PromptEnvelope                    ← 顶层信封
+├─ version: "1.0"                ← 协议版本
+├─ model?: string                ← 模型名称
+└─ messages: Message[]           ← 消息列表
+    ├─ Message                   ← 单条消息
+    │  ├─ id: string             ← 唯一标识
+    │  ├─ role: Role             ← system | user | assistant | tool
+    │  ├─ segments: Segment[]    ← Segment 列表
+    │  └─ timestamp: number      ← Unix epoch 毫秒
+    └─ ...
+```
+
+### 2.1 PromptEnvelope（顶层信封）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `version` | `"1.0"` | ✓ | 协议版本号 |
+| `model` | `string` | | 模型名称，如 `gpt-4-turbo`、`claude-opus-4-8` |
+| `messages` | `Message[]` | ✓ | 消息列表，至少 1 条 |
+
+### 2.2 Message（消息）
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | `string` | ✓ | 消息唯一标识（如 `a-1`、`b-3`） |
+| `role` | `"system" \| "user" \| "assistant" \| "tool"` | ✓ | 消息角色 |
+| `segments` | `Segment[]` | ✓ | Segment 列表，至少 1 个 |
+| `timestamp` | `number` | ✓ | Unix epoch 毫秒时间戳 |
+
+### 2.3 Segment（段落）
+
+Segment 是基于 `kind` 字段的**可辨识联合类型**，共 11 种。每个 Segment 对应 LLM 上下文中的一类信息，在 UI 中有独立的视觉呈现。
+
+| kind | 含义 | 视觉组件 | 颜色标识 |
+|------|------|---------|---------|
+| `text` | 普通文本消息 | `MarkdownRenderer` | — |
+| `static_var` | 会话级静态变量 | `StaticVarBadge` | 蓝色 |
+| `system_prompt` | System Prompt 内容 | `SystemPromptView` | 灰色 |
+| `memory` | 长期记忆条目 | `MemoryView` | 紫色 |
+| `skills` | 可用 Skills 列表 | `SkillsView` | 绿色 |
+| `tool_overview` | 工具声明（JSON Schema） | `ToolOverviewView` | 橙色 |
+| `tool_call_request` | 工具调用请求 | `ToolCallRequestView` | 深色终端 |
+| `tool_call_result` | 工具调用结果 | `ToolCallResultView` | 绿/红 |
+| `document` | 上传的文档 | `DocumentCard` | — |
+| `long_text` | 长文本片段 | `LongTextView` | — |
+| `media` | 图片/音频/视频 | `MediaView` | — |
+
+---
+
+## 3. Segment 类型详细规范
+
+### 3.1 TextSegment — 普通文本
+
+最基本的文本消息，使用 Markdown 渲染。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"text"` | ✓ | |
+| `content` | `string` | ✓ | Markdown 格式文本 |
+
+```json
+{ "kind": "text", "content": "你好，我想讨论一下我的协议方案。" }
+```
+
+### 3.2 StaticVarSegment — 静态变量
+
+会话级配置变量，在 system prompt 中以 `{{name}}` 模板占位符展开。变量本身在 UI 中以蓝色 pill 标签呈现，让用户看到模型"感知"到的配置。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"static_var"` | ✓ | |
+| `name` | `string` | ✓ | 模板变量名，如 `current_date` |
+| `value` | `string` | ✓ | 展开后的值，如 `2026年6月7日` |
+| `description` | `string` | | 变量的用途说明 |
+
+```json
+{
+  "kind": "static_var",
+  "name": "current_date",
+  "value": "2026年6月7日",
+  "description": "当前对话日期，注入到 System Prompt 模板中"
+}
+```
+
+**模板展开规则**：System prompt 中的 `{{current_date}}` 会被替换为 `2026年6月7日`。展开发生在导出阶段（`exportToOpenAIFormat`），UI 中同时显示原始模板和变量值。
+
+### 3.3 SystemPromptSegment — System Prompt
+
+模型的系统指令。UI 中用灰色 CollapsiblePanel 包裹，默认折叠——体现其"后台配置"的语义。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"system_prompt"` | ✓ | |
+| `content` | `string` | ✓ | System Prompt 全文，可含 `{{var}}` 模板 |
+| `collapsed` | `boolean` | ✓ | 默认折叠状态 |
+
+```json
+{
+  "kind": "system_prompt",
+  "content": "当前日期：{{current_date}}\n回复语言：{{language}}\n\n你是 HCI 课程设计助手...",
+  "collapsed": true
+}
+```
+
+### 3.4 MemorySegment — 记忆
+
+模型的长期记忆，存储关于用户的持久化信息。UI 中用紫色 CollapsiblePanel 包裹。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"memory"` | ✓ | |
+| `description` | `string` | | 简短解释 memory 的用途 |
+| `items` | `MemoryItem[]` | ✓ | 记忆条目列表 |
+| `collapsed` | `boolean` | ✓ | 默认折叠状态 |
+
+**MemoryItem**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `title` | `string` | ✓ | 记忆标题，如"用户身份" |
+| `content` | `string` | ✓ | 记忆内容 |
+
+```json
+{
+  "kind": "memory",
+  "description": "以下是从过往对话中总结的关于你的信息...",
+  "items": [
+    { "title": "用户背景", "content": "设计系研二学生，正在做 HCI 课程设计" }
+  ],
+  "collapsed": true
+}
+```
+
+### 3.5 SkillsSegment — 技能
+
+模型可调用的内置能力（slash commands）。遵循 Anthropic SKILL.md 规范的渐进式披露机制：
+
+- **L1**：`name` + `description` — 始终在上下文中可见
+- **L2**：`body` — skill 被触发时才加载的完整指令
+
+UI 中用绿色 CollapsiblePanel 包裹。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"skills"` | ✓ | |
+| `description` | `string` | | 解释 skills 是什么 |
+| `items` | `SkillItem[]` | ✓ | Skill 列表 |
+| `collapsed` | `boolean` | ✓ | 默认折叠 |
+
+**SkillItem**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | `string` | ✓ | Skill 名称（L1） |
+| `description` | `string` | ✓ | 一句话描述（L1） |
+| `body` | `string` | | 完整指令 Markdown（L2，触发时注入） |
+
+> **注意**：JSON 协议文件中 skills segment 只包含 `name` + `description`（L1 层）。`body` 由运行时加载器从技能注册表补全，**不属于协议数据本身**。body 仅在 skill 被触发时由 agent 框架注入上下文。
+
+```json
+{
+  "kind": "skills",
+  "description": "Skills 是模型可调用的内置能力...",
+  "items": [
+    { "name": "deep-research", "description": "深度研究 — 多源搜索、交叉验证、生成引用报告" },
+    { "name": "code-review", "description": "代码审查 — 发现正确性 bug 和简化/效率优化机会" }
+  ],
+  "collapsed": true
+}
+```
+
+### 3.6 ToolOverviewSegment — 工具声明
+
+声明模型可调用的工具列表及其 JSON Schema。UI 中用橙色 CollapsiblePanel 包裹，每个 Tool 可展开查看 Schema。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"tool_overview"` | ✓ | |
+| `items` | `ToolItem[]` | ✓ | 工具列表 |
+| `collapsed` | `boolean` | ✓ | |
+
+**ToolItem**：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | `string` | ✓ | 工具名称 |
+| `description` | `string` | ✓ | 功能描述 |
+| `parameters` | `string` | ✓ | 人类可读的参数摘要 |
+| `schema` | `object` | | JSON Schema 对象 |
+
+```json
+{
+  "kind": "tool_overview",
+  "items": [
+    {
+      "name": "search",
+      "description": "搜索学术文献和设计案例",
+      "parameters": "query: string, limit?: number",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "query": { "type": "string", "description": "搜索关键词" },
+          "limit": { "type": "number", "description": "返回结果数量上限" }
+        },
+        "required": ["query"]
+      }
+    }
+  ],
+  "collapsed": true
+}
+```
+
+### 3.7 ToolCallRequestSegment — 工具调用请求
+
+模型发起工具调用的记录。UI 中以深色终端风格代码块呈现，参数以标签化键值行展示。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"tool_call_request"` | ✓ | |
+| `toolName` | `string` | ✓ | 被调用的工具名称 |
+| `arguments` | `object` | ✓ | 调用参数（键值对） |
+| `collapsed` | `boolean` | ✓ | 默认展开（`false`） |
+
+```json
+{
+  "kind": "tool_call_request",
+  "toolName": "search",
+  "arguments": { "query": "LLM context transparency HCI", "limit": 5 },
+  "collapsed": false
+}
+```
+
+### 3.8 ToolCallResultSegment — 工具调用结果
+
+工具调用的返回结果。UI 中成功时显示绿色状态条（默认折叠），失败时显示红色状态条（默认展开）。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"tool_call_result"` | ✓ | |
+| `toolName` | `string` | ✓ | 工具名称 |
+| `result` | `string` | ✓ | 返回结果文本 |
+| `success` | `boolean` | ✓ | 调用是否成功 |
+| `collapsed` | `boolean` | ✓ | 成功时 `true`，失败时 `false` |
+
+```json
+{
+  "kind": "tool_call_result",
+  "toolName": "search",
+  "success": true,
+  "result": "Found 5 results:\n\n1. \"Transparent AI...\" — CHI 2024...",
+  "collapsed": true
+}
+```
+
+### 3.9 DocumentSegment — 文档
+
+用户上传的文档。UI 中显示文件图标、文件名、大小、内容摘要。可点击「查看解析」展开 AI 对文档的结构化提取结果。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"document"` | ✓ | |
+| `fileName` | `string` | ✓ | 文件名 |
+| `mimeType` | `string` | ✓ | MIME 类型 |
+| `snippet` | `string` | ✓ | 前 200 字符预览 |
+| `sizeBytes` | `number` | ✓ | 文件大小（字节） |
+| `parsedContent` | `string` | | AI 提取的结构化内容（Markdown） |
+
+```json
+{
+  "kind": "document",
+  "fileName": "2026-Q2-智能助手市场报告.pdf",
+  "mimeType": "application/pdf",
+  "sizeBytes": 2845000,
+  "snippet": "# 2026 年 Q2 智能助手市场研究报告\n\n## 摘要\n\n2026 年 Q2 全球智能助手市场规模预计达到 187 亿美元...",
+  "parsedContent": "## 文档概览\n\n| 字段 | 内容 |\n..."
+}
+```
+
+### 3.10 LongTextSegment — 长文本
+
+超长文本片段（如日志、研究论文全文），折叠态展示前 2 行预览 + 字符数。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"long_text"` | ✓ | |
+| `content` | `string` | ✓ | 全文内容 |
+| `charCount` | `number` | ✓ | 字符总数 |
+| `collapsed` | `boolean` | ✓ | 默认 `true`（折叠） |
+
+```json
+{
+  "kind": "long_text",
+  "content": "192.168.1.10 - - [07/Jun/2026:10:15:23 +0800] \"GET /api/users HTTP/1.1\" 200 1234\n...",
+  "charCount": 2375,
+  "collapsed": true
+}
+```
+
+### 3.11 MediaSegment — 多媒体
+
+图片、音频或视频。UI 中显示类型图标 + 媒体类型标签 + alt 文本。
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `kind` | `"media"` | ✓ | |
+| `mediaType` | `"image" \| "audio" \| "video"` | ✓ | 媒体类型 |
+| `url` | `string` | ✓ | 媒体文件 URL |
+| `altText` | `string` | | 替代文本描述 |
+
+```json
+{
+  "kind": "media",
+  "mediaType": "image",
+  "url": "https://cataas.com/cat",
+  "altText": "用户上传的图片"
+}
+```
+
+---
+
+## 4. Skills 系统
+
+Skills 遵循 Anthropic SKILL.md 规范的**渐进式披露**机制。
+
+### 4.1 SKILL.md 格式
+
+```markdown
+---
+name: webapp-testing
+description: Toolkit for testing local web applications using Playwright.
+---
+
+# Web Application Testing
+
+To test local web applications, write native Python Playwright scripts.
+...
+```
+
+YAML frontmatter 提供 `name` + `description`，Markdown body 是完整指令正文。
+
+### 4.2 层级模型
+
+| 层级 | 内容 | 何时可见 | 上下文大小 |
+|------|------|---------|-----------|
+| L1 | `name` + `description` | 始终在上下文中 | ~100 词 |
+| L2 | `body`（完整指令） | Skill 被触发时加载 | 建议 <500 行 |
+
+### 4.3 协议中的表示
+
+JSON 协议文件的 skills segment **仅包含 L1 数据**（`name` + `description`）。Skill body 由运行时加载器从技能注册表（`skills.ts` / `skills-loader.ts`）按名称查询并补全。
+
+**理由**：body 不属于 system prompt 范畴——它不会被立刻发送给模型。body 仅在 skill 被触发时由 agent 框架注入上下文，其展示也由框架逻辑控制。
+
+### 4.4 两类 Skill 源
+
+| 来源 | 文件 | 数量 | 说明 |
+|------|------|------|------|
+| 手写 | `src/data/skills.ts` | 8 个 | 自定义 skill（code-review、deep-research、verify 等） |
+| SKILL.md 解析 | `src/data/skills-loader.ts` | 4 个 | 从真实 Anthropic SKILL.md 文件解析（webapp-testing、pdf、doc-coauthoring、mcp-builder） |
+
+---
+
+## 5. 导出管线
+
+### 5.1 OpenAI Chat Completions 格式映射
+
+`exportToOpenAIFormat(envelope)` 将 PromptEnvelope 导出为 OpenAI 兼容的请求体。
+
+```
+{ model, messages: OpenAIMessage[], tools?: OpenAITool[] }
+```
+
+| Protocol Segment | OpenAI 表示 |
+|-----------------|------------|
+| `text` | `message.content`（string） |
+| `static_var` | 展开为变量值，出现在 content 中 |
+| `system_prompt` | `system` role 消息的 content |
+| `memory` | `system` role 消息的 content（格式化为 `- title: content`） |
+| `skills` | `system` role 消息的 content（格式化为 `- /name: description`） |
+| `tool_overview` | `system` 消息的 content + 顶层 `tools[]` 数组 |
+| `tool_call_request` | assistant 消息，带 `tool_calls[]` |
+| `tool_call_result` | `tool` role 消息，带 `tool_call_id` |
+| `document` | `[Document: name (size)]\nsnippet` |
+| `long_text` | content 原文 |
+| `media` | 图片 → `image_url` content part；音频/视频 → altText 回退 |
+
+### 5.2 关键导出行为
+
+**结构性 Segment 聚合**：system_prompt、memory、skills 等结构性 segment 被合并为一条 `role: "system"` 头部消息。
+
+**静态变量模板展开**：system prompt 中的 `{{var}}` 占位符在导出时被替换为实际值。`static_var` 本身不写入 content。
+
+**多模态消息**：当 user 消息包含 `media` segment（图片）时，`content` 输出为 `OpenAIContentPart[]` 数组：
+```json
+{
+  "role": "user",
+  "content": [
+    { "type": "text", "text": "这张图片是什么？" },
+    { "type": "image_url", "image_url": { "url": "https://cataas.com/cat" } }
+  ]
+}
+```
+
+纯文本消息保持 `content: string` 格式不变，向后兼容。
+
+**工具调用配对**：`tool_call_request` 和 `tool_call_result` 通过 `tool_call_id` 配对，按 toolName 建立 FIFO 队列匹配。
+
+---
+
+## 6. JSON 协议文件格式
+
+### 6.1 文件结构
+
+```
+src/data/demos/
+├── manifest.json                  # 场景索引
+├── demo-a.json ~ demo-f.json      # 6 个 Demo 场景
+├── prompt-envelope.schema.json    # JSON Schema
+├── demos.ts                       # 聚合入口
+└── demos-loader.ts                # 加载器
+```
+
+### 6.2 最小合法示例
+
+```json
+{
+  "version": "1.0",
+  "model": "gpt-4-turbo",
+  "messages": [
+    {
+      "id": "msg-1",
+      "role": "system",
+      "segments": [
+        {
+          "kind": "system_prompt",
+          "content": "你是一个有用的助手。",
+          "collapsed": true
+        }
+      ],
+      "timestamp": 1780897800000
+    },
+    {
+      "id": "msg-2",
+      "role": "user",
+      "segments": [
+        { "kind": "text", "content": "你好！" }
+      ],
+      "timestamp": 1780897900000
+    },
+    {
+      "id": "msg-3",
+      "role": "assistant",
+      "segments": [
+        { "kind": "text", "content": "你好！有什么可以帮助你的吗？" }
+      ],
+      "timestamp": 1780898000000
+    }
+  ]
+}
+```
+
+### 6.3 设计约束
+
+| 约束 | 说明 |
+|------|------|
+| 字段名 | camelCase，与 TypeScript 类型一致 |
+| 时间戳 | Unix epoch 毫秒（绝对时间），不使用相对偏移 |
+| 折叠默认值 | 由 `collapsed` 字段指定，协议数据作为初始值，UI 可运行时切换 |
+| Skill body | 不入协议，由加载器按 name 从注册表补全 |
+
+### 6.4 JSON Schema
+
+`prompt-envelope.schema.json` 提供完整的 JSON Schema（Draft 2020-12）校验：
+
+- `version` 必须为 `"1.0"`
+- `messages` 非空
+- `role` 仅限 `system` / `user` / `assistant` / `tool`
+- `kind` 必须是 11 种之一
+- 每种 Segment 的必填字段约束
+- memory / skills / tool_overview 的 `items` 非空
+
+VSCode 可通过 `$schema` 引用自动补全和实时校验。
+
+---
+
+## 7. 视觉设计规范
+
+### 7.1 颜色系统
+
+| 颜色 | HEX | 对应 Segment | 语义 |
+|------|-----|-------------|------|
+| 蓝色 | `#3B82F6` | `static_var` | 配置/变量 |
+| 灰色 | `#6B7280` | `system_prompt` | 后台指令 |
+| 紫色 | `#8B5CF6` | `memory` | 持久记忆 |
+| 绿色 | `#10B981` | `skills` | 能力/技能 |
+| 橙色 | `#F59E0B` | `tool_overview` | 工具/接口 |
+| 深色 | `#1F2937` | `tool_call_request` | 代码/执行 |
+| 绿色（成功） | `#22C55E` | `tool_call_result` | 成功 |
+| 红色（失败） | `#EF4444` | `tool_call_result` | 失败 |
+
+### 7.2 折叠策略
+
+| Segment | 默认状态 | 理由 |
+|---------|---------|------|
+| `system_prompt` | 折叠 | 后台配置，非主要阅读内容 |
+| `memory` | 折叠 | 参考信息，按需查看 |
+| `skills` | 折叠 | 工具列表，按需展开 |
+| `tool_overview` | 折叠 | Schema 细节冗长 |
+| `tool_call_request` | **展开** | 调用过程需要可见 |
+| `tool_call_result`（成功） | 折叠 | 结果正常 |
+| `tool_call_result`（失败） | **展开** | 错误信息需要立即关注 |
+| `long_text` | 折叠 | 默认仅显示预览 |
+| `text` | N/A | 始终可见 |
+
+### 7.3 布局
+
+双栏布局：
+- **左侧**：`ChatView` — 聊天气泡列表，每条消息渲染其 Segments
+- **右侧**：`ProtocolPanel` — 双 tab（OpenAI Format / Raw Protocol），显示导出的 JSON，支持复制和下载
+- **顶栏**：Demo 场景切换按钮
+
+---
+
+## 8. Demo 场景
+
+| 索引 | ID | 场景 | 内容 |
+|------|----|------|------|
+| 0 | a | 场景 A | 基础对话 + System Prompt + Memory |
+| 1 | b | 场景 B | 工具调用：请求 → 执行（成功 & 失败） |
+| 2 | c | 场景 C 📄 | 文档解析：点击「查看解析」看 AI 提取内容 |
+| 3 | d | 场景 D ⭐ | 多模态对话：图片识别（猫） |
+| 4 | f | 场景 F 📁 | 真实 Anthropic Skills |
+| 5 | e | 场景 E 🔍 | 日志分析：异常检测 + 安全审计 + 性能分析 |
+
+默认激活场景 F（索引 4）。
+
+---
+
+## 9. 相关资源
+
+| 资源 | 路径 |
+|------|------|
+| 类型定义 | `src/types/protocol.ts` |
+| 导出逻辑 | `src/utils/export.ts` |
+| JSON Schema | `src/data/demos/prompt-envelope.schema.json` |
+| 加载器 | `src/data/demos/demos-loader.ts` |
+| 场景数据 | `src/data/demos/demo-*.json` |
+| Skills 注册表 | `src/data/skills.ts` / `src/data/skills-loader.ts` |
+| 渲染组件 | `src/components/SegmentRenderer.tsx` |