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 表格、对比图）是否已标注？

示例：视觉设计订单班的特殊标注

# 五、分镜设计

| 镜号 | 生成图片 | 线稿图片 | 景别 | 时长 | ...

→ 这表示有一个 CSV 表格，展示 AIGC 分镜预览（线稿 → AI 生成图）

---

三、Agent 配置设计

1. 确定 Agent 数量和类型

步骤：

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

食品订单班示例（7个Agent）：

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）：

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 配置字段说明

{
  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）

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

标准模板：

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 的输出模板

{
  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

食品订单班图片示例：

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

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

视觉设计订单班特殊处理（AIGC对比）：

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

(3) 数据展示规范

财务数据格式：

{ type: 'info', content: '成本结构分析:' },
{ type: 'output', content: '  • 食材成本: 35% = 101.6万' },
{ type: 'output', content: '  • 租金成本: 12% = 34.8万' },
{ type: 'output', content: '  • 人工成本: 20% = 58.0万' },

时间安排格式：

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

人员配置格式：

{ type: 'success', content: '✓ 导演（6+1天）: 12,000元 - 全程在场' },
{ type: 'success', content: '✓ 制片PM（6+1天）: 9,000元 - 预算与协调' },

3. 完成序列（completionSequence）

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

标准模板：

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生成对比

示例：

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

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

展示策略：

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

示例：

{ 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. 多层级数据

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

展示原则：

• 先展示总数
• 再分类展示
• 使用缩进区分层级

示例：

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

---

六、图片路径规范

1. 路径格式

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

完整格式：

/data/订单班文档资料/[订单班名称]/notion文稿/image/[描述性文件名].jpg

示例：

// ✅ 正确（描述性文件名）
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 中添加：

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 脚本模板：

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. 基础模板

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 输出模板

{
  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. 查看文件结构

ls -la data/订单班文档资料/[订单班名称]/Agent_prompt/
ls -la data/订单班文档资料/[订单班名称]/agent头像/

2. 检查图片文件

find data/订单班文档资料/[订单班名称]/notion文稿/image -name "*.jpg"

3. 重命名图片（Python）

python3 /tmp/rename_images.py

4. 验证 TypeScript 语法

cd web_frontend/exhibition-demo
npm run build

---

最后更新

2025-10-01

版本历史

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