Agent-n8n/.serena/memories/terminal-simulation-development-guide.md

# 终端模拟内容开发指南

## 开发流程

### 1. 前期准备
- **阅读文档资料**：仔细阅读 `/data/订单班文档资料/{订单班名}/notion文稿` 下的文档
- **分析图片备注**：查看文档中图片的插入位置和备注说明，理解图片与内容的对应关系
- **检查资源文件**：确认 `agent头像`、`Agent_prompt`、`image` 文件夹是否完整

### 2. Agent设计原则

#### Agent数量规划
- 根据项目复杂度确定Agent数量（通常6-10个）
- 覆盖项目全生命周期的关键角色
- 确保每个Agent有明确的职责边界

#### Agent配置要素
```typescript
{
  id: 'unique_identifier',        // 唯一标识符（蛇形命名）
  name: '中文角色名',              // 显示名称
  icon: '📋',                      // emoji图标
  avatar: '/data/订单班文档资料/{订单班}/agent头像/{角色名}.jpg',
  model: 'GPT-4',                  // 模型名称
  role: '简短的职责描述',          // 一句话职责
  status: 'waiting',               // 初始状态
}
```

#### 命名规范
- **文件名**：`{orderClassId}.ts`（如 `developer.ts`）
- **函数名**：`{orderClassId}Simulation`（如 `developerSimulation`）
- **变量名**：`{orderClassId}Agents`（如 `developerAgents`）
- **orderClassId**：与 orderClasses.json 中的 id 完全一致

### 3. 内容结构设计

#### 启动序列（startupSequence）
目的：营造项目启动氛围，介绍项目背景

```typescript
startupSequence: [
  { type: 'system', content: '初始化{项目类型}开发环境...' },
  { type: 'system', content: '加载项目需求：{项目名称}' },
  { type: 'info', content: '核心信息1' },
  { type: 'info', content: '核心信息2' },
  { type: 'system', content: '' },  // 空行分隔
  { type: 'system', content: '正在组建{N}人团队...' },
  { type: 'success', content: '✓ {Agent1}就位' },
  // ... 所有Agent就位确认
  { type: 'system', content: '' },
  { type: 'system', content: '开始多Agent协作流程...' },
  { type: 'system', content: '════════════════════════════════════' },
]
```

#### Agent执行序列（agentSequence）
目的：展示每个Agent的具体工作内容和成果

**标准结构**：
```typescript
{
  agent: () => {orderClassId}Agents[index],
  outputs: [
    { type: 'info', content: '{icon} {Agent名}开始{动作}...' },
    { type: 'system', content: '' },
    
    // 工作内容展示
    { type: 'output', content: '{工作模块标题}:' },
    { type: 'output', content: '  • {具体工作项1}' },
    { type: 'output', content: '  • {具体工作项2}' },
    { type: 'system', content: '' },
    
    // 图片插入（如果有）
    { type: 'image', imageSrc: '/data/订单班文档资料/{订单班}/notion文稿/image/{图片名}.jpg', imageAlt: '{图片说明}' },
    { type: 'system', content: '' },
    
    // 成果总结
    { type: 'success', content: '✓ {成果1}' },
    { type: 'success', content: '✓ {成果2}' },
  ]
}
```

#### 完成序列（completionSequence）
目的：项目总结和成果展示

```typescript
completionSequence: [
  { type: 'system', content: '════════════════════════════════════' },
  { type: 'system', content: '' },
  { type: 'success', content: '🎉 {项目名}圆满完成！' },
  { type: 'system', content: '' },
  { type: 'output', content: '项目成果总结:' },
  { type: 'output', content: '  • {成果亮点1}' },
  { type: 'output', content: '  • {成果亮点2}' },
  { type: 'system', content: '' },
  { type: 'output', content: '交付物清单:' },
  { type: 'output', content: '  ✓ {交付物1}' },
  { type: 'output', content: '  ✓ {交付物2}' },
  { type: 'system', content: '' },
  { type: 'success', content: '感谢{N}位Agent的协作，{项目名}已成功上线！' },
  { type: 'system', content: '════════════════════════════════════' },
]
```

### 4. 图片插入技巧

#### 图片位置选择
- **概念/架构图**：放在介绍该概念/架构的Agent输出中
- **界面设计图**：放在UI设计师或前端开发的输出中
- **数据分析图**：放在数据分析或测试的输出中
- **流程图**：放在系统架构师或项目经理的输出中

#### 图片插入格式
```typescript
{ type: 'image', imageSrc: '/data/订单班文档资料/{订单班}/notion文稿/image/{图片名}.jpg', imageAlt: '{简短描述}' },
{ type: 'system', content: '' },  // 图片后加空行
```

#### 图片与内容的对应关系
根据文档分析建立映射：
- **首页.jpg** → 数据库架构/系统架构部分
- **用户信息后台数据.jpg** → 用户系统设计
- **课程信息后台数据.jpg** → 课程系统设计
- **API配置界面.jpg** → 接口设计/后端开发
- **注册界面.jpg** → 用户认证/前端开发
- **课程直播间.jpg** → 直播系统/互动功能

### 5. 内容撰写技巧

#### 信息密度控制
- 每个Agent输出3-5个工作模块
- 每个模块2-4个具体工作项
- 避免过于冗长的描述

#### 专业术语使用
- 使用行业通用术语（如 Vue3、Spring Cloud、JWT）
- 避免过于晦涩的技术细节
- 数字要具体（如"10万+并发"而非"大量用户"）

#### 成果量化表达
- **好的示例**：
  - ✓ 前端开发完成（65个组件，28个页面）
  - ✓ 接口性能：平均响应时间200ms
  - ✓ 测试通过率：98.5%
  
- **避免的表达**：
  - ✓ 前端开发完成
  - ✓ 性能很好
  - ✓ 测试基本通过

#### 分隔符使用
- 使用空行 `{ type: 'system', content: '' }` 分隔不同模块
- 使用分隔线 `════════════════════════════════════` 标记重要节点

### 6. 开发实例参考

#### 智能开发订单班（developer.ts）
**文档结构**：
- 6大章节：项目概述、功能模块、数据库设计、开发实现、测试、运维
- 9张图片：首页、用户数据、智能分析、课程数据、课程内容、直播间、注册界面、热门课程、API配置

**Agent设计**：
1. 需求文档撰写专员 - 需求调研与文档输出
2. 产品经理 - 产品规划与功能设计
3. 平台架构师 - 技术架构与数据库设计
4. UI设计师 - 界面设计与交互体验
5. 前端开发工程师 - Vue3前端开发
6. 后端开发工程师 - Spring Cloud后端开发
7. 软件测试工程师 - 功能/性能/安全测试
8. DEMO生成助手 - 演示原型与文档生成
9. 项目经理 - 项目总结与成果汇报

**图片分配**：
- 产品经理：首页.jpg
- 平台架构师：用户信息后台数据.jpg、课程信息后台数据.jpg
- UI设计师：注册界面.jpg、热门课程.jpg、课程直播间.jpg
- 前端开发工程师：课程内容.jpg
- 后端开发工程师：API配置界面.jpg
- 软件测试工程师：智能学习数据分析.jpg

### 7. 常见问题

#### Q1: Agent数量如何确定？
A: 根据项目规模和文档内容：
- 小型项目（如轻食品牌）：5-7个Agent
- 中型项目（如教育平台）：8-10个Agent
- 大型项目（如AGV系统）：10-12个Agent

#### Q2: 图片应该放在哪个Agent？
A: 遵循"谁产出谁展示"原则：
- 数据库设计图 → 架构师
- 界面设计图 → UI设计师或前端工程师
- API文档图 → 后端工程师
- 测试报告图 → 测试工程师

#### Q3: 如何避免内容重复？
A: 每个Agent聚焦自己的职责：
- 需求分析师：需求调研、文档撰写
- 产品经理：功能规划、原型设计
- 架构师：技术选型、架构设计
- 开发工程师：具体实现、代码编写
- 测试工程师：测试执行、问题发现
- 项目经理：进度管理、成果总结

#### Q4: 输出内容的详细程度？
A: 保持"概览+亮点"原则：
- 不要列举所有细节
- 突出关键技术点和创新点
- 用数据说话（如"65个组件"比"很多组件"更好）

### 8. 注册流程

完成文件创建后，需要在 `index.ts` 中注册：

```typescript
// 1. 导入
import { {orderClassId}Simulation } from './{orderClassId}';

// 2. 注册到映射表
export const simulationMap: Record<string, SimulationGenerator> = {
  // ... 其他订单班
  {orderClassId}: {orderClassId}Simulation,
};
```

### 9. 验证清单

创建完成后检查：
- [ ] 文件命名符合规范（{orderClassId}.ts）
- [ ] Agent数量与 agentCount 一致
- [ ] 所有头像路径正确
- [ ] 图片路径正确且图片存在
- [ ] orderClassId 与 orderClasses.json 一致
- [ ] 已在 index.ts 中正确注册
- [ ] TypeScript 编译无错误

### 10. 最佳实践总结

✅ **DO（推荐做法）**：
- 深入阅读文档，理解项目全貌
- 图片与文字内容强关联
- 使用具体数字量化成果
- 每个Agent职责清晰、不重叠
- 使用空行和分隔符优化阅读体验

❌ **DON'T（避免做法）**：
- 不看文档凭想象编写内容
- 随意插入图片，与内容无关
- 使用模糊表述（如"很好"、"很多"）
- Agent职责重叠或遗漏关键角色
- 内容冗长、缺少分段

### 11. 工具函数提示

在开发过程中可以使用以下bash命令快速检查：

```bash
# 查看文档资料结构
ls -la "/path/to/订单班文档资料/{订单班}/"

# 查看图片文件
ls -la "/path/to/订单班文档资料/{订单班}/notion文稿/image/"

# 查看agent头像
ls -la "/path/to/订单班文档资料/{订单班}/agent头像/"

# 检查orderClasses.json中的配置
grep -A 15 '"id": "{orderClassId}"' orderClasses.json
```

---

**备注**：本指南基于智能开发订单班（developer.ts）的开发经验总结，适用于所有订单班的终端模拟内容开发。