Agent-n8n/.serena/memories/terminal_simulation_creation_best_practices.md

# 终端模拟文件创建最佳实践

## 概述
本文档记录创建订单班终端模拟文件（terminalSimulations）的标准流程和最佳实践，基于食品和视觉设计两个订单班的实际处理经验总结。

## 一、文件位置规范

### 存放目录
```
web_frontend/exhibition-demo/src/data/terminalSimulations/
├── index.ts           # 类型定义和导出
├── food.ts            # 食品订单班
├── visualDesign.ts    # 视觉设计订单班
└── [其他订单班].ts
```

### 为什么放在 src/data/ 而不是 public/data/？
- **src/data/** 存放 TypeScript 代码和配置逻辑
- **public/data/** 存放图片、文档等静态资源
- 终端模拟文件是 TypeScript 代码，会被打包，因此放在 src/data/

---

## 二、创建前的准备工作

### 1. 文档资料准备
必须确保以下资料完整：

```
data/订单班文档资料/[订单班名称]/
├── notion文稿/
│   ├── [主文档].md              # 核心文档
│   └── image/                   # 图片资源（已重命名为描述性名称）
├── Agent_prompt/                # Agent 提示词文件
│   ├── Agent1.md
│   ├── Agent2.md
│   └── ...
└── agent头像/                   # Agent 头像图片
    ├── Agent1.jpg
    ├── Agent2.jpg
    └── ...
```

**关键要求**：
- ✅ 图片文件名必须是**描述性名称**（如：店面图片_正门.jpg）
- ✅ Markdown 文档中的图片引用必须与实际文件名一致
- ✅ Agent_prompt 文件数量必须与 agent头像 数量一致

### 2. 文档内容审查

**检查清单**：
- [ ] 是否有清晰的章节结构？
- [ ] 每个章节对应的图片是否有明确标注？
- [ ] 是否有关键数据（预算、时间、数量等）？
- [ ] 特殊内容（如 CSV 表格、对比图）是否已标注？

**示例**：视觉设计订单班的特殊标注
```markdown
# 五、分镜设计

| 镜号 | 生成图片 | 线稿图片 | 景别 | 时长 | ...
```
→ 这表示有一个 CSV 表格，展示 AIGC 分镜预览（线稿 → AI 生成图）

---

## 三、Agent 配置设计

### 1. 确定 Agent 数量和类型

**步骤**：
1. 检查 `Agent_prompt/` 文件夹中的提示词文件数量
2. 阅读每个提示词文件，理解 Agent 职责
3. 按照文档章节顺序或工作流程顺序排列

**食品订单班示例**（7个Agent）：
```typescript
const foodAgents: Agent[] = [
  { id: 'food_market_analyst', name: '餐饮市场调研专家', icon: '📊' },
  { id: 'food_brand_designer', name: '餐饮品牌设计专家', icon: '🎨' },
  { id: 'food_location_decorator', name: '餐厅选址装修专家', icon: '🏗️' },
  { id: 'food_menu_developer', name: '菜品研发专家', icon: '👨‍🍳' },
  { id: 'food_operation_expert', name: '轻食店经营管理专家', icon: '🍽️' },
  { id: 'food_team_manager', name: '餐饮团队人员管理专家', icon: '👥' },
  { id: 'food_finance_advisor', name: '财务预算专家', icon: '💰' }
];
```

**视觉设计订单班示例**（5个Agent）：
```typescript
const visualDesignAgents: Agent[] = [
  { id: 'visual_project_director', name: '客户对接-项目总监', icon: '🎬' },
  { id: 'visual_screenwriter', name: '编剧', icon: '✍️' },
  { id: 'visual_director', name: '导演', icon: '🎥' },
  { id: 'visual_storyboard_artist', name: '分镜师', icon: '🎨' },
  { id: 'visual_production_manager', name: '制片主任', icon: '📋' }
];
```

### 2. Agent 配置字段说明

```typescript
{
  id: 'unique_agent_id',              // 唯一标识，建议格式：[订单班]_[职责]
  name: 'Agent显示名称',               // 与提示词文件名一致
  icon: '🎨',                         // 合适的emoji图标
  avatar: '/data/订单班文档资料/[订单班]/agent头像/[Agent].jpg',
  model: 'GPT-4',                     // AI 模型名称（可随意分配）
  role: '简短职责描述',                // 3-5个词概括职责
  status: 'waiting',                  // 初始状态固定为 waiting
}
```

### 3. Agent 顺序原则

**按工作流程顺序**：
- ✅ **食品订单班**：市场调研 → 品牌设计 → 选址装修 → 菜品研发 → 运营管理 → 人员管理 → 财务预算
- ✅ **视觉设计订单班**：客户对接 → 编剧 → 导演 → 分镜师 → 制片主任

**原则**：
- 前期准备 Agent 在前（调研、策划、设计）
- 执行落地 Agent 在中（实施、制作、拍摄）
- 收尾总结 Agent 在后（财务、验收、交付）

---

## 四、内容创作策略

### 1. 启动序列（startupSequence）

**目的**：营造系统初始化的氛围

**标准模板**：
```typescript
startupSequence: [
  { type: 'info', content: '🚀 启动[项目名称]生成系统...' },
  { type: 'system', content: '初始化多Agent协作框架' },
  { type: 'success', content: '✓ 系统核心加载完成' },
  { type: 'system', content: '加载专业知识库: [领域1]/[领域2]/[领域3]' },
  { type: 'progress', content: '████████████████████ 100%', duration: 1500 },
  { type: 'success', content: '✓ 知识库加载完成' },
  { type: 'info', content: '连接行业数据源...' },
  { type: 'system', content: '├─ [数据源1]' },
  { type: 'system', content: '├─ [数据源2]' },
  { type: 'system', content: '├─ [数据源3]' },
  { type: 'system', content: '└─ [数据源4]' },
  { type: 'success', content: '✓ 数据源连接成功' },
  { type: 'warning', content: '⚡ 检测到需求: [项目核心需求]' },
  { type: 'info', content: '核心特点: [差异化定位/亮点]' },
  { type: 'info', content: '正在分配[N]位专业Agent...' },
]
```

**时长建议**：10-15条消息

### 2. Agent 输出序列（agentSequence）

**结构设计原则**：

#### (1) 每个 Agent 的输出模板
```typescript
{
  agent: () => agents[0],  // 当前 Agent
  outputs: [
    // 1. 开场白（必须）
    { type: 'system', content: '[图标] [Agent名称] 正在[动作]...' },
    
    // 2. 工作说明（必须）
    { type: 'info', content: '[工作内容概述]' },
    
    // 3. 进度条（可选，用于长时间任务）
    { type: 'progress', content: '分析中...', duration: 1000 },
    
    // 4. 核心结果（3-8条）
    { type: 'success', content: '✓ [关键成果1]' },
    { type: 'success', content: '✓ [关键成果2]' },
    
    // 5. 详细输出（可选，用于列表数据）
    { type: 'output', content: '  • [明细项1]' },
    { type: 'output', content: '  • [明细项2]' },
    
    // 6. 图片展示（核心亮点）
    {
      type: 'image',
      content: '[图标] [图片标题]',
      imageSrc: '/data/订单班文档资料/[订单班]/notion文稿/image/[图片名].jpg',
      imageAlt: '[图片描述]'
    },
    
    // 7. 总结（必须）
    { type: 'success', content: '✓ [Agent工作总结]' },
  ]
}
```

#### (2) 图片使用策略

**原则**：
- ✅ 每个 Agent 至少展示 1-3 张关键图片
- ✅ 图片必须与当前 Agent 的工作内容紧密相关
- ✅ 图片顺序遵循文档章节顺序
- ✅ 使用描述性的 `content` 和 `imageAlt`

**食品订单班图片示例**：
```typescript
// 市场调研专家 → 市场宣传图
{
  type: 'image',
  content: '📊 市场宣传营销策略',
  imageSrc: '/data/订单班文档资料/食品/notion文稿/image/市场宣传营销.jpg',
  imageAlt: '青莳轻食市场定位与营销'
}

// 品牌设计专家 → 品牌Logo
{
  type: 'image',
  content: '🏷️ 青莳品牌LOGO设计',
  imageSrc: '/data/订单班文档资料/食品/notion文稿/image/品牌LOGO.jpg',
  imageAlt: '青莳轻食品牌Logo'
}
```

**视觉设计订单班特殊处理（AIGC对比）**：
```typescript
// 分镜师展示线稿 → AI生成对比
{
  type: 'image',
  content: '📐 镜头4-线稿图',
  imageSrc: '/data/订单班文档资料/视觉设计/notion文稿/分镜/线稿图片/xxx.jpg',
  imageAlt: '传统乐器表演场景线稿'
},
{
  type: 'image',
  content: '🎬 镜头4-AI生成图',
  imageSrc: '/data/订单班文档资料/视觉设计/notion文稿/分镜/生成图片/xxx.jpg',
  imageAlt: 'AI生成的表演场景最终效果'
}
```

#### (3) 数据展示规范

**财务数据格式**：
```typescript
{ type: 'info', content: '成本结构分析:' },
{ type: 'output', content: '  • 食材成本: 35% = 101.6万' },
{ type: 'output', content: '  • 租金成本: 12% = 34.8万' },
{ type: 'output', content: '  • 人工成本: 20% = 58.0万' },
```

**时间安排格式**：
```typescript
{ type: 'info', content: '拍摄时间表:' },
{ type: 'output', content: '  • D1: 勘景与报批（机位/日光测绘）' },
{ type: 'output', content: '  • D2: 开篇·江南序曲（晨雾窗口）' },
```

**人员配置格式**：
```typescript
{ type: 'success', content: '✓ 导演（6+1天）: 12,000元 - 全程在场' },
{ type: 'success', content: '✓ 制片PM（6+1天）: 9,000元 - 预算与协调' },
```

### 3. 完成序列（completionSequence）

**目的**：总结整个项目的核心亮点和交付成果

**标准模板**：
```typescript
completionSequence: [
  { type: 'system', content: '=' .repeat(70) },
  { type: 'success', content: '🎉 [项目名称] 生成完成！' },
  { type: 'system', content: '=' .repeat(70) },
  { type: 'info', content: '' },
  
  // 1. 核心竞争优势（3-6条）
  { type: 'info', content: '🎯 核心竞争优势:' },
  { type: 'success', content: '✓ [优势1]' },
  { type: 'success', content: '✓ [优势2]' },
  
  // 2. 财务亮点（3-5条）
  { type: 'info', content: '💰 财务亮点:' },
  { type: 'success', content: '✓ [财务指标1]' },
  { type: 'success', content: '✓ [财务指标2]' },
  
  // 3. 风险管理/创新亮点（可选）
  { type: 'info', content: '🎨 AIGC技术创新:' },
  { type: 'output', content: '  • [创新点1]' },
  
  // 4. 交付物清单
  { type: 'info', content: '📋 交付物清单:' },
  { type: 'output', content: '  1. [交付物1]' },
  
  // 5. 文件保存位置
  { type: 'success', content: '✅ 完整方案已保存至: /projects/[路径].pdf' },
  { type: 'info', content: '📄 附件包含: [附件列表]' },
]
```

**时长建议**：20-30条消息

---

## 五、特殊内容处理

### 1. CSV 表格数据

**场景**：视觉设计订单班的分镜表

**处理方式**：
- 不直接展示完整表格
- 提取关键镜头展示（3-5个代表性镜头）
- 配合图片展示线稿 → AI生成对比

**示例**：
```typescript
{ type: 'success', content: '✓ 镜头1: 远景/无人机/24mm - 俯瞰古镇屋顶' },
{ type: 'success', content: '✓ 镜头2: 中景/滑轨/50mm - 夕阳下古亭' },
```

### 2. 对比内容（如 AIGC 分镜）

**展示策略**：
1. 先说明创新点（"AIGC辅助分镜预览"）
2. 展示线稿图片
3. 展示AI生成图片
4. 简短说明镜头内容

**示例**：
```typescript
{ type: 'info', content: 'AIGC分镜对比展示（线稿 → AI生成）:' },
{
  type: 'image',
  content: '📐 镜头4-线稿图',
  imageSrc: '/path/to/sketch.jpg',
  imageAlt: '场景线稿'
},
{
  type: 'image',
  content: '🎬 镜头4-AI生成图',
  imageSrc: '/path/to/ai_generated.jpg',
  imageAlt: 'AI生成最终效果'
},
{ type: 'output', content: '  → 中景/手持稳定器 - 场景描述' },
```

### 3. 多层级数据

**场景**：预算明细、人员配置、设备清单

**展示原则**：
- 先展示总数
- 再分类展示
- 使用缩进区分层级

**示例**：
```typescript
{ type: 'success', content: '✓ 总预算: 273,800元' },
{ type: 'info', content: '成本结构分解:' },
{ type: 'output', content: '  • 前期: 19,000元' },
{ type: 'output', content: '  • 拍摄人力: 82,900元' },
```

---

## 六、图片路径规范

### 1. 路径格式

**固定前缀**：`/data/订单班文档资料/`

**完整格式**：
```
/data/订单班文档资料/[订单班名称]/notion文稿/image/[描述性文件名].jpg
```

**示例**：
```typescript
// ✅ 正确（描述性文件名）
imageSrc: '/data/订单班文档资料/食品/notion文稿/image/店面图片_正门.jpg'

// ❌ 错误（通用文件名）
imageSrc: '/data/订单班文档资料/食品/notion文稿/image/图片_01.jpg'
```

### 2. 图片文件名规范

**命名原则**：
- ✅ 使用描述性名称（如：市场宣传营销.jpg）
- ✅ 中文命名可接受
- ✅ 使用下划线分隔（如：店面图片_正门.jpg）
- ❌ 避免通用名称（如：图片_01.jpg）
- ❌ 避免 UUID 或乱码

**重命名流程**（如果遇到通用文件名）：
1. 阅读 Markdown 文档，理解每张图片对应的内容
2. 创建图片映射表（旧名 → 新名）
3. 使用 Python 脚本批量重命名
4. 更新 Markdown 中的图片引用

---

## 七、质量检查清单

### 创建前检查
- [ ] Agent 数量与提示词文件一致
- [ ] Agent 头像文件都存在
- [ ] 图片文件名都是描述性的
- [ ] Markdown 文档结构清晰
- [ ] 关键数据已标记（预算、时间、数量）

### 创建中检查
- [ ] Agent 顺序符合工作流程
- [ ] 每个 Agent 至少有 1 张图片
- [ ] 图片路径正确（以 /data/ 开头）
- [ ] 数据格式一致（缩进、符号）
- [ ] 进度条 duration 合理（800-1500ms）

### 创建后检查
- [ ] TypeScript 无语法错误
- [ ] 所有图片路径可访问
- [ ] Agent 配置字段完整
- [ ] 内容逻辑连贯
- [ ] 总时长合理（3-5分钟模拟效果）

---

## 八、常见问题与解决方案

### 问题1：图片加载失败（ERR_CONNECTION_REFUSED）

**原因**：
- `public/data/订单班文档资料` 是软链接
- Vite 默认不允许访问项目外部文件

**解决方案**：
在 `vite.config.ts` 中添加：
```typescript
export default defineConfig({
  server: {
    fs: {
      allow: ['..'],  // 允许访问父目录
    },
  },
  preview: {
    fs: {
      allow: ['..'],
    },
  },
})
```

### 问题2：Agent 数量与文档不匹配

**症状**：
- 终端模拟只有 6 个 Agent
- 但 Agent_prompt 文件夹有 7 个提示词文件

**解决方案**：
1. 检查 `Agent_prompt/` 文件夹
2. 逐个阅读提示词文件
3. 确保每个 Agent 都在 `agents` 数组中
4. 检查是否有 Agent 被错误合并

### 问题3：图片文件名不规范

**症状**：
- 图片名称为 `图片_01.jpg`、`图片_02.jpg`
- Markdown 中也是通用名称

**解决方案**：
1. 阅读 Markdown 文档上下文
2. 创建映射表：`图片_01.jpg → 店面图片_正门.jpg`
3. 使用 Python 批量重命名
4. 更新 Markdown 引用

**Python 脚本模板**：
```python
import os
import shutil

image_map = {
    "图片_01.jpg": "店面图片_正门.jpg",
    "图片_02.jpg": "店内场景_用餐区.jpg",
}

IMAGE_DIR = "/path/to/image/"
for old_name, new_name in image_map.items():
    old_path = os.path.join(IMAGE_DIR, old_name)
    new_path = os.path.join(IMAGE_DIR, new_name)
    if os.path.exists(old_path):
        shutil.move(old_path, new_path)
```

### 问题4：特殊字符编码问题

**症状**：
- 文件名包含 URL 编码（如：%E9%9D%99%E5%B8%A7）
- Bash 脚本处理中文失败

**解决方案**：
- 使用 Python 而不是 Bash
- 使用 `urllib.parse.unquote()` 解码
- 指定 `encoding='utf-8'`

---

## 九、代码模板

### 1. 基础模板

```typescript
import { Agent } from '@/store/demoStore';
import { SimulationData, TerminalLine } from './index';

// [订单班名称]订单班专属Agent配置
const [变量名]Agents: Agent[] = [
  {
    id: '[订单班]_[agent1]',
    name: '[Agent1名称]',
    icon: '🎨',
    avatar: '/data/订单班文档资料/[订单班]/agent头像/[Agent1].jpg',
    model: 'GPT-4',
    role: '[简短职责]',
    status: 'waiting',
  },
  // ... 更多 Agents
];

export const [变量名]Simulation = (): SimulationData => ({
  orderClassId: '[订单班id]',
  orderClassName: '[订单班名称]',
  projectTitle: '[项目标题]',
  agents: [变量名]Agents,

  startupSequence: [
    // 启动序列
  ],

  agentSequence: [
    // Agent 输出序列
  ],

  completionSequence: [
    // 完成序列
  ]
});
```

### 2. Agent 输出模板

```typescript
{
  agent: () => agents[0],
  outputs: [
    { type: 'system', content: '[图标] [Agent名称] 正在[动作]...' },
    { type: 'info', content: '[工作内容]' },
    { type: 'progress', content: '[进度描述]...', duration: 1000 },
    { type: 'success', content: '✓ [成果1]' },
    { type: 'success', content: '✓ [成果2]' },
    {
      type: 'image',
      content: '[图标] [图片标题]',
      imageSrc: '/data/订单班文档资料/[订单班]/notion文稿/image/[图片].jpg',
      imageAlt: '[图片描述]'
    },
    { type: 'success', content: '✓ [总结]' },
  ]
}
```

---

## 十、实战案例对比

### 案例1：食品订单班

**特点**：
- 7个 Agent（市场→品牌→选址→菜品→运营→人员→财务）
- 图片类型：店面、菜品、人员、流程
- 数据类型：财务预算、营收预测、成本结构

**处理重点**：
- 图片重命名（25张从通用名改为描述性名称）
- Agent 顺序调整（分离品牌设计和选址装修）
- 财务数据精确呈现（50万投资，290万营收）

### 案例2：视觉设计订单班

**特点**：
- 5个 Agent（总监→编剧→导演→分镜→制片）
- 图片类型：古镇风光、分镜对比、设备清单
- 特殊内容：CSV 分镜表、AIGC 线稿→生成对比

**处理重点**：
- AIGC 分镜展示（线稿图 + AI生成图成对展示）
- 分镜表简化（17个镜头选取 4-5 个代表性展示）
- 六大篇章结构（古镇→文化→美食→湿地→农业→夜游）

---

## 十一、协作与记忆

### 1. 记录到 Serena

每次完成一个订单班的终端模拟创建后，应记录：
- Agent 配置思路
- 特殊内容处理方式
- 遇到的问题和解决方案

### 2. 跨订单班借鉴

**可复用**：
- Agent 配置结构
- 启动/完成序列模板
- 图片展示策略
- 数据格式规范

**需定制**：
- Agent 数量和职责
- 图片内容和顺序
- 特殊内容处理
- 项目特色亮点

---

## 十二、持续优化

### 1. 收集反馈

- 用户观看终端模拟的反馈
- 图片展示效果
- 内容节奏是否合理
- Agent 顺序是否清晰

### 2. 迭代改进

- 调整 Agent 输出时长
- 优化图片展示顺序
- 增加/减少数据细节
- 改进特殊内容展示

---

## 附录：工具和命令

### 1. 查看文件结构
```bash
ls -la data/订单班文档资料/[订单班名称]/Agent_prompt/
ls -la data/订单班文档资料/[订单班名称]/agent头像/
```

### 2. 检查图片文件
```bash
find data/订单班文档资料/[订单班名称]/notion文稿/image -name "*.jpg"
```

### 3. 重命名图片（Python）
```bash
python3 /tmp/rename_images.py
```

### 4. 验证 TypeScript 语法
```bash
cd web_frontend/exhibition-demo
npm run build
```

---

## 最后更新
2025-10-01

## 版本历史
- v1.0 (2025-10-01): 基于食品和视觉设计两个订单班的实践总结