feat: Prompt Envelope Protocol MVP

- 定义 11 种 Segment 类型(text, static_var, system_prompt, memory, skills, tool_overview, tool_call_request/result, document, long_text, media)
- 每种 Segment 有独立的颜色编码和折叠交互
- 通用 CollapsiblePanel + SegmentRenderer 路由架构
- 4 个 Demo 场景覆盖全部 9 种上下文类型
- 导出为 OpenAI Chat Completions Format(model + messages + tools)
- tool_overview -> 请求级 tools[](含 JSON Schema)
- tool_call_request -> assistant.tool_calls[]
- tool_call_result -> tool-role message(ID 配对)
- 17 个单元测试全部通过
- React 18 + TypeScript + Vite + Tailwind CSS
This commit is contained in:
carry
2026-06-07 13:44:36 +08:00
commit a9881eac26
34 changed files with 5833 additions and 0 deletions
+624
View File
@@ -0,0 +1,624 @@
import type { PromptEnvelope } from '../types/protocol'
export interface DemoScenario {
id: string
label: string
description: string
envelope: PromptEnvelope
}
const now = Date.now()
// ============================================================
// Scenario A: Simple chat + system prompt + memory
// ============================================================
const demoA: PromptEnvelope = {
version: '1.0',
model: 'gpt-4-turbo',
messages: [
{
id: 'a-1',
role: 'system',
segments: [
{
kind: 'system_prompt',
content: `你是 HCI 课程设计助手。你帮助学生对聊天界面的信息架构进行批判性思考。
回答应简洁、有结构,鼓励学生从用户体验角度分析问题。
如果学生对某个概念不清楚,用通俗的例子解释,不要用术语堆砌。`,
collapsed: true,
},
{
kind: 'memory',
items: [
{
title: '用户背景',
content: '设计系研二学生,正在做 HCI 课程设计,关注 LLM 交互的透明性',
},
{
title: '偏好',
content: '喜欢简洁的表达,反感术语堆砌。倾向用图示辅助理解。',
},
{
title: '上次对话',
content: '讨论过 chatbox UI 过度封装的问题,确认了 9 种需要区分的 prompt 类型',
},
],
collapsed: true,
},
{
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'],
},
},
{
name: 'get_example',
description: '获取 UI 设计案例截图和说明',
parameters: 'topic: string, count?: number',
schema: {
type: 'object',
properties: {
topic: { type: 'string', description: '设计主题' },
count: { type: 'number', description: '案例数量' },
},
required: ['topic'],
},
},
],
collapsed: true,
},
],
timestamp: now - 300000,
},
{
id: 'a-2',
role: 'user',
segments: [
{
kind: 'static_var',
name: 'user_name',
value: '小明',
},
{
kind: 'text',
content: '你好,我想讨论一下我设计的聊天协议方案。你觉得 9 种 prompt 类型的分类合理吗?',
},
],
timestamp: now - 240000,
},
{
id: 'a-3',
role: 'assistant',
segments: [
{
kind: 'text',
content:
'我觉得你的 9 种分类很全面!从信息架构的角度看,你已经覆盖了 LLM 上下文的三个主要来源:\n\n1. **静态配置**(变量、system prompt\n2. **能力声明**skills、tools\n3. **动态输入**(文档、长文本、多模态)\n\n加上工具调用的过程性信息,形成了一个完整的上下文可见性模型。这种分类本身就值得在课程设计中展开讨论。',
},
],
timestamp: now - 180000,
},
],
}
// ============================================================
// Scenario B: Tool call flow (request → result)
// ============================================================
const demoB: PromptEnvelope = {
version: '1.0',
model: 'gpt-4-turbo',
messages: [
{
id: 'b-1',
role: 'system',
segments: [
{
kind: 'system_prompt',
content:
'你是一个数据分析助手,可以使用 Python 工具进行数据查询和可视化。',
collapsed: true,
},
{
kind: 'tool_overview',
items: [
{
name: 'run_query',
description: '执行 SQL 查询',
parameters: 'sql: string',
schema: {
type: 'object',
properties: {
sql: { type: 'string', description: 'SQL 查询语句' },
},
required: ['sql'],
},
},
{
name: 'plot_chart',
description: '生成图表',
parameters: 'type: string, data: object, output_format?: string',
schema: {
type: 'object',
properties: {
type: { type: 'string', enum: ['line', 'bar', 'scatter'], description: '图表类型' },
title: { type: 'string', description: '图表标题' },
x_label: { type: 'string', description: 'X 轴标签' },
y_label: { type: 'string', description: 'Y 轴标签' },
data: { type: 'array', description: '数据点数组' },
output_format: { type: 'string', enum: ['png', 'svg'], description: '输出格式' },
},
required: ['type', 'data', 'output_format'],
},
},
{
name: 'fetch_data',
description: '获取远程数据',
parameters: 'url: string, format: string',
schema: {
type: 'object',
properties: {
url: { type: 'string', description: '数据 URL' },
format: { type: 'string', enum: ['json', 'csv'], description: '数据格式' },
},
required: ['url', 'format'],
},
},
],
collapsed: true,
},
],
timestamp: now - 200000,
},
{
id: 'b-2',
role: 'user',
segments: [
{
kind: 'text',
content: '帮我看看过去一周的用户注册数据,按天统计,用折线图展示趋势。',
},
],
timestamp: now - 180000,
},
{
id: 'b-3',
role: 'assistant',
segments: [
{
kind: 'text',
content: '好的,我先查询数据库获取注册数据。',
},
{
kind: 'tool_call_request',
toolName: 'run_query',
arguments: {
sql: `SELECT DATE(created_at) as date, COUNT(*) as count
FROM users
WHERE created_at >= DATE('now', '-7 days')
GROUP BY DATE(created_at)
ORDER BY date`,
},
collapsed: false,
},
],
timestamp: now - 160000,
},
{
id: 'b-4',
role: 'assistant',
segments: [
{
kind: 'tool_call_result',
toolName: 'run_query',
success: true,
result: `[
{"date": "2026-06-01", "count": 42},
{"date": "2026-06-02", "count": 38},
{"date": "2026-06-03", "count": 55},
{"date": "2026-06-04", "count": 47},
{"date": "2026-06-05", "count": 61},
{"date": "2026-06-06", "count": 73},
{"date": "2026-06-07", "count": 58}
]`,
collapsed: true,
},
],
timestamp: now - 140000,
},
{
id: 'b-5',
role: 'assistant',
segments: [
{
kind: 'text',
content: '查询成功。现在生成折线图——',
},
{
kind: 'tool_call_request',
toolName: 'plot_chart',
arguments: {
type: 'line',
title: 'Daily User Registrations (Past 7 Days)',
x_label: 'Date',
y_label: 'New Users',
data: [
{ date: '06-01', count: 42 },
{ date: '06-02', count: 38 },
{ date: '06-03', count: 55 },
{ date: '06-04', count: 47 },
{ date: '06-05', count: 61 },
{ date: '06-06', count: 73 },
{ date: '06-07', count: 58 },
],
},
collapsed: false,
},
],
timestamp: now - 130000,
},
{
id: 'b-6',
role: 'assistant',
segments: [
{
kind: 'tool_call_result',
toolName: 'plot_chart',
success: false,
result: 'Error: plot_chart requires "output_format" parameter (png | svg). Please retry with format specified.',
collapsed: false,
},
],
timestamp: now - 120000,
},
],
}
// ============================================================
// Scenario C: Long text + document + image
// ============================================================
const longArticleContent_C = '# 大语言模型交互中的上下文透明性问题\n\n## 摘要\n\n近年来,以 ChatGPT 为代表的对话式 AI 产品迅速普及。然而,这些产品的交互设计普遍存在"上下文不透明"的问题——用户无法了解模型在生成回复时参考了哪些信息、使用了哪些工具、被施加了怎样的约束。\n\n## 1. 问题定义\n\n当前的聊天界面(chatbox UI)将 LLM 的完整上下文封装在黑盒之中。用户看到的是一个"魔法对话框":输入问题,得到回答。但这个过程掩盖了大量关键信息:\n\n- **System Prompt**:模型的行为准则和角色设定,直接决定了回复的风格和边界\n- **User Memory**:跨对话持久化的用户信息,可能包含过时或不准确的记忆\n- **Tools & Skills**:模型可调用的外部能力,用户可能完全不知道它们的存在\n- **Variable Injection**:模板变量在用户不知情的情况下被替换为具体值\n\n这种不透明性导致了一系列用户体验问题:信任缺失、纠错困难、意外行为难以解释。\n\n## 2. 设计目标\n\n本文提出一套"Prompt Envelope Protocol"——一种结构化的 prompt 表达格式,使得:\n\n1. 每种上下文元素都有明确的视觉呈现\n2. 用户可以按需展开或折叠细节\n3. 协议可以无损导出为标准 API 格式\n4. 视觉语言保持简约,不增加认知负荷\n\n## 3. 核心设计原则\n\n### 3.1 信息密度梯度\n\n核心对话文本始终可见,元信息默认折叠。用户不会在每次对话中都被无关的 system prompt 和工具列表淹没。\n\n### 3.2 颜色编码系统\n\n每种上下文类型有独立的颜色标记,形成可学习的视觉语言:\n- 蓝色 = 变量\n- 灰色 = 系统指令\n- 紫色 = 用户记忆\n- 绿色 = 技能\n- 橙色 = 工具\n\n### 3.3 协议即视图\n\n折叠状态存储在协议数据中而非 UI 状态中。这意味着相同的协议数据在任何渲染器下都产生相同的视图——协议本身就是 view model。'
const demoC: PromptEnvelope = {
version: '1.0',
model: 'gpt-4-turbo',
messages: [
{
id: 'c-1',
role: 'system',
segments: [
{
kind: 'system_prompt',
content:
'你是文档审阅助手。帮助用户分析长文档、提取要点、回答关于文档内容的问题。',
collapsed: true,
},
{
kind: 'skills',
items: [
{ name: 'summarize', description: '生成文档摘要' },
{ name: 'translate', description: '翻译文档内容' },
{ name: 'qa', description: '基于文档回答具体问题' },
],
collapsed: true,
},
],
timestamp: now - 150000,
},
{
id: 'c-2',
role: 'user',
segments: [
{
kind: 'text',
content: '帮我审阅这篇论文草稿,看看结构上有什么问题:',
},
{
kind: 'long_text',
content: longArticleContent_C,
charCount: longArticleContent_C.length,
collapsed: true,
},
{
kind: 'document',
fileName: 'hci-paper-draft.pdf',
mimeType: 'application/pdf',
snippet:
'# 大语言模型交互中的上下文透明性问题\n\n## 摘要\n\n近年来,以 ChatGPT 为代表的对话式 AI 产品迅速普及。然而,这些产品的交互设计普遍存在"上下文不透明"的问题——用户无法了解模型在生成回复时参考了哪些信息...',
sizeBytes: 245760,
},
{
kind: 'media',
mediaType: 'image',
url: '',
altText: '论文框架图:Context Layers 分层示意图',
},
],
timestamp: now - 120000,
},
{
id: 'c-3',
role: 'assistant',
segments: [
{
kind: 'text',
content:
'我读完了你的草稿。整体框架很清晰,但有几个建议:\n\n1. **第3节的设计原则**是目前最强的部分,可以考虑将这部分提前到第2节\n2. "信息密度梯度"这个概念很有原创性,建议在摘要中就提及\n3. 缺少用户研究部分——如果你有做可用性测试的计划,可以加一节"4. 评估方法"\n4. 颜色编码系统部分写得很好,可以加一个视觉化的表格来展示颜色-类型映射\n\n需要我展开其中某一点吗?',
},
],
timestamp: now - 60000,
},
],
}
// ============================================================
// Scenario D: Comprehensive — all 9 segments
// ============================================================
const comprehensiveArticleContent = '在过去的18个月里,我们对127名LLM聊天产品用户进行了纵向研究。研究分为三个阶段:基线观察期(3个月)、干预实验期(6个月)、后续跟踪期(9个月)。在干预实验期,我们为实验组用户提供了一套上下文可视化工具,包括:system prompt查看面板、memory编辑界面、tool call实时展示和long text折叠功能。对照组使用标准的聊天界面。\n\n实验组在以下维度上表现出显著改善:\n- 任务完成率提升 23.4%p < 0.01\n- 纠错响应时间缩短 41.7%p < 0.001\n- 用户信任度评分从 3.2/5 提升至 4.1/5\n- 对话轮次平均减少 2.8 轮(更高效的信息交换)\n\n这些结果表明上下文透明性不仅仅是"nice to have"的设计细节,而是直接影响LLM交互效率的关键因素。特别是在以下场景中效果最为显著:\n1. 长文档分析:用户能够看到哪些文档片段被模型引用\n2. 多工具调用:工具链的可视化帮助用户理解推理过程\n3. 跨会话任务:memory可见性减少重复说明\n\n我们建议将上下文透明性作为LLM聊天产品的基础设计原则,而非可选特性。'
const demoD: PromptEnvelope = {
version: '1.0',
model: 'gpt-4-turbo',
messages: [
// --- System message with all structural segments ---
{
id: 'd-1',
role: 'system',
segments: [
{
kind: 'system_prompt',
content: `你是 Claude,一个 HCI 研究助手。你的角色是帮助学生批判性地思考聊天界面的设计问题。
核心原则:
- 鼓励从用户体验角度分析,而非技术实现角度
- 用具体例子说明抽象概念
- 如果学生的方案有改进空间,以提问的方式引导而非直接批评
- 始终记住你拥有工具调用、skills 和跨对话 memory 能力,但不必每次都全部用到`,
collapsed: true,
},
{
kind: 'memory',
items: [
{
title: '用户身份',
content: '小明,设计系研二,HCI 方向。正在做课程设计项目。',
},
{
title: '项目背景',
content: '设计一个透明化 LLM 上下文的聊天协议。已确定了 9 种 prompt 类型的分类方案。',
},
{
title: '沟通偏好',
content: '喜欢用图示和表格辅助理解。反感过度术语化。需要看到具体例子。',
},
{
title: '上次进度',
content: '用户已确认了 MVP 范围:Web 应用,数据协议+视觉规范,可导出 OpenAI Format。',
},
],
collapsed: true,
},
{
kind: 'skills',
items: [
{ name: 'deep-research', description: '深度研究 — 多源搜索、交叉验证、生成引用报告' },
{ name: 'code-review', description: '审查代码变更,发现正确性问题和简化机会' },
{ name: 'simplify', description: '审查代码的复用性、简洁性和效率,并应用修复' },
{ name: 'verify', description: '运行应用并观察行为来验证变更是否正确' },
],
collapsed: true,
},
{
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'],
},
},
{
name: 'read_file',
description: '读取文件内容',
parameters: 'path: string',
schema: {
type: 'object',
properties: {
path: { type: 'string', description: '文件路径' },
},
required: ['path'],
},
},
{
name: 'fetch_url',
description: '获取网页内容并转为 markdown',
parameters: 'url: string',
schema: {
type: 'object',
properties: {
url: { type: 'string', description: '网页 URL' },
},
required: ['url'],
},
},
{
name: 'run_code',
description: '在沙箱中执行代码',
parameters: 'language: string, code: string',
schema: {
type: 'object',
properties: {
language: { type: 'string', enum: ['python', 'javascript', 'r'], description: '编程语言' },
code: { type: 'string', description: '代码内容' },
},
required: ['language', 'code'],
},
},
],
collapsed: true,
},
],
timestamp: now - 600000,
},
// --- User message 1 ---
{
id: 'd-2',
role: 'user',
segments: [
{
kind: 'static_var',
name: 'user_name',
value: '小明',
},
{
kind: 'text',
content: '你好!我在准备课程设计的文献综述部分。我找到了一篇相关的研究报告,帮我分析一下它是否可以支持我的论点。',
},
{
kind: 'long_text',
content: comprehensiveArticleContent,
charCount: comprehensiveArticleContent.length,
collapsed: true,
},
{
kind: 'document',
fileName: 'context-transparency-study-2025.pdf',
mimeType: 'application/pdf',
snippet:
'DOI: 10.1145/3613904.3642000\n\nContext Transparency in LLM-Powered Chat Interfaces: A Longitudinal Study with 127 Users\n\nIn the past 18 months, we conducted a longitudinal study...',
sizeBytes: 2457600,
},
{
kind: 'media',
mediaType: 'image',
url: '',
altText: 'Fig 3: 实验组 vs 对照组任务完成率对比图(p<0.01',
},
],
timestamp: now - 500000,
},
// --- Assistant response ---
{
id: 'd-3',
role: 'assistant',
segments: [
{
kind: 'text',
content: '这是一篇非常有力的参考文献!它恰恰支持了你的核心论点——上下文透明性是"基础设计原则,而非可选特性"。',
},
],
timestamp: now - 480000,
},
// --- Assistant tool call ---
{
id: 'd-4',
role: 'assistant',
segments: [
{
kind: 'tool_call_request',
toolName: 'search',
arguments: {
query: 'LLM context transparency HCI chat interface user study 2024 2025',
limit: 5,
},
collapsed: false,
},
],
timestamp: now - 470000,
},
{
id: 'd-5',
role: 'assistant',
segments: [
{
kind: 'tool_call_result',
toolName: 'search',
success: true,
result: `Found 5 results:
1. "Transparent AI: Designing Explainable Chat Interfaces" — CHI 2024
→ 提出了"分层透明度"框架,与本项目的"信息密度梯度"高度一致
2. "User Mental Models of LLM Context" — CSCW 2025
→ 发现 78% 的用户低估了 system prompt 对输出的影响
3. "Folding as a Visual Strategy for Complex Chat UIs" — DIS 2024
→ 验证了折叠/展开对降低认知负荷的效果
4. "Beyond the Black Box: Visualizing LLM Reasoning in Chat" — TOCHI 2025
→ 工具调用可视化的用户研究,与本项目的 tool call request/result 设计一致
5. "Memory-Aware Interfaces for Persistent LLM Interactions" — IUI 2025
→ 讨论了用户记忆的可编辑性和可遗忘性`,
collapsed: true,
},
],
timestamp: now - 450000,
},
// --- Assistant final response ---
{
id: 'd-6',
role: 'assistant',
segments: [
{
kind: 'text',
content: `搜索结果显示,你的研究方向和当前学术界的热点高度一致。以下是我对文献支持度的评估:
**强相关(可直接引用):**
- 第2篇(CSCW 2025)直接量化了用户对 LLM 上下文的理解不足——这是你"问题定义"部分的关键论据
- 第3篇(DIS 2024)为你的"折叠设计"提供了实证基础
**建议阅读方向:**
- 第1篇的"分层透明度"框架可以与你的 9 种类型分类做对比讨论
- 第5篇的 memory 可编辑性可能是你下一个值得探索的方向
这篇研究报告 + 这5篇文献构成了一个很好的文献基础。需要我帮你整理成引用格式吗?`,
},
],
timestamp: now - 400000,
},
],
}
export const demos: DemoScenario[] = [
{
id: 'a',
label: '场景 A',
description: '基础对话 + System Prompt + Memory',
envelope: demoA,
},
{
id: 'b',
label: '场景 B',
description: '工具调用:请求 → 执行(成功 & 失败)',
envelope: demoB,
},
{
id: 'c',
label: '场景 C',
description: '长文本 + 文档附件 + 多模态',
envelope: demoC,
},
{
id: 'd',
label: '场景 D ⭐',
description: '综合:全部 9 种 Segment',
envelope: demoD,
},
]