From f22c9f8aebb369fd118a429f2f4db928654451f2 Mon Sep 17 00:00:00 2001
From: carry <luokairui@carry.fit>
Date: Sun, 7 Jun 2026 13:56:46 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0=20CLAUDE.md=20?=
 =?UTF-8?q?=E6=96=87=E4=BB=B6=EF=BC=8C=E6=8F=90=E4=BE=9B=E9=A1=B9=E7=9B=AE?=
 =?UTF-8?q?=E6=8C=87=E5=AF=BC=E5=92=8C=E6=9E=B6=E6=9E=84=E6=A6=82=E8=BF=B0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CLAUDE.md | 93 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 93 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..94f87ef
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+**项目语言：中文。所有注释、文档、commit message、UI 文案均使用中文。**
+
+## 项目概述
+
+HCI 课程设计项目：**Prompt Envelope Protocol** — 一套让 LLM 上下文在聊天界面中可见的协议与 UI。
+
+核心思想：每条聊天消息由若干带类型的 **Segment** 组成（而非原始文本）。每种 Segment 有独立的视觉呈现，让 system prompt、memory、tools、skills、变量、文档、多媒体成为可见的一等元素，而非隐藏的上下文。
+
+MVP 为纯前端 React 应用，使用 mock 数据演示。无后端、无真实 LLM 调用。
+
+## 命令
+
+```bash
+npm run dev          # Vite 开发服务器 → http://localhost:5173
+npm run build        # tsc 类型检查 + vite 构建
+npm test             # vitest 运行全部测试（17 个，位于 export.test.ts）
+npx vitest run src/__tests__/export.test.ts  # 运行单个测试文件
+```
+
+## 架构
+
+### 数据模型 (`src/types/protocol.ts`)
+
+`PromptEnvelope { version, model, messages: Message[] }` — 顶层协议文档。
+
+`Message { id, role: "system"|"user"|"assistant", segments: Segment[], timestamp }` — 单条聊天消息。
+
+`Segment` 是基于 `kind` 的可辨识联合类型，共 11 种变体：`text`、`static_var`、`system_prompt`、`memory`、`skills`、`tool_overview`、`tool_call_request`、`tool_call_result`、`document`、`long_text`、`media`。
+
+部分 Segment 类型（MemorySegment、SkillSegment）有可选 `description` 字段，用于在 UI 中解释这些项的用途。
+
+ToolItem 有可选 `schema` 字段（JSON Schema 对象），在工具总览面板中可展开查看。
+
+### 渲染管线
+
+```
+SegmentRenderer (按 segment.kind 分发)
+  ├─ TextSegmentView        → MarkdownRenderer（react-markdown + GFM）
+  ├─ StaticVarBadge         → 蓝色内联 pill 标签
+  ├─ SystemPromptView       → CollapsiblePanel（灰色，默认折叠）
+  ├─ MemoryView             → CollapsiblePanel（紫色，默认折叠）
+  ├─ SkillsView             → CollapsiblePanel（绿色，默认折叠）
+  ├─ ToolOverviewView       → CollapsiblePanel（橙色，默认折叠，可展开 JSON Schema）
+  ├─ ToolCallRequestView    → 深色终端风格代码块，参数以标签化键值行展示
+  ├─ ToolCallResultView     → 绿色/红色状态条（失败时默认展开，成功时默认折叠）
+  ├─ DocumentCard           → 文件图标 + 文件名 + 大小 + 摘要预览
+  ├─ LongTextView           → 折叠态展示前2行预览 + 展开态用 MarkdownRenderer 渲染
+  └─ MediaView              → 图标 + 类型标签 + alt 文本
+```
+
+`CollapsiblePanel` 是共享折叠容器组件。折叠/展开状态通过 `useState(segment.collapsed)` 管理——协议数据提供默认值，UI 控制运行时切换。
+
+`MarkdownRenderer` 封装 `react-markdown` + `remark-gfm`。所有 HTML 元素（h1–h4、p、code、pre、table、blockquote 等）均有自定义 Tailwind 样式，针对聊天气泡内嵌场景做了紧凑化处理。
+
+### 状态管理
+
+`ChatContext`（`src/context/ChatContext.tsx`）持有当前 `envelope` 和 `activeDemo` 索引。切换 Demo 场景时替换整个 envelope。ChatInput 已禁用（MVP 无真实输入）。
+
+### 导出管线 (`src/utils/export.ts`)
+
+`exportToOpenAIFormat(envelope)` 输出 OpenAI 兼容 JSON，结构为 `{ model, messages, tools? }`：
+
+- 结构性 Segment（`system_prompt`、`memory`、`skills`、`tool_overview`）提取为一条 `role: "system"` 的头部消息
+- `tool_overview` 的 items 转为顶层 `tools` 数组（OpenAI function-calling 格式）
+- `tool_call_request` → 带 `tool_calls` 数组的 assistant 消息；`tool_call_result` → `role: "tool"` 消息
+- `static_var` 展开为变量值
+- `text` 和 `long_text` 原文输出
+- `media` 用 `altText` 作为回退文本
+- `segmentToText()` 对结构性/tool Segment 返回 `null`——它们在消息级别统一处理
+
+### Demo 数据 (`src/data/demos.ts`)
+
+4 个场景，从 0 开始索引。默认激活索引 3（场景 D——综合场景，覆盖全部 9 种 Segment）。每个场景是一个完整的 `PromptEnvelope`，对话内容为中文。
+
+### 颜色系统
+
+| 颜色   | 对应 Segment                          |
+|--------|--------------------------------------|
+| 蓝色   | `static_var`                         |
+| 灰色   | `system_prompt`                      |
+| 紫色   | `memory`                             |
+| 绿色   | `skills`                             |
+| 橙色   | `tool_overview`                      |
+| 深色   | `tool_call_request`（代码块）          |
+| 绿/红  | `tool_call_result`（成功/失败）        |
+
+### 布局
+
+双栏：左侧 `ChatView`（MessageList + ChatInput），右侧 `ProtocolPanel`（实时 OpenAI Format JSON 视图，支持复制/下载）。顶栏有 Demo 场景切换按钮。