Agent-n8n/.serena/memories/02_终端模拟开发指南.md

终端模拟内容开发指南 (2025-10-03 更新)

最新进展 (2025-10-03)

• ✅ 已完成9个订单班的终端模拟：wenlu, food, finance, logistics, manufacturing, dev, civil, energy, health
• ✅ 剩余3个订单班待开发：design, chemical, environment
• ✅ TSX格式已完全替代JSON文件加载方式
• ✅ 统一管理器 index.ts 实现动态导入机制

开发流程

1. 前期准备

• 阅读文档资料：仔细阅读 /data/订单班文档资料/{订单班名}/notion文稿 下的文档
• 分析图片备注：查看文档中图片的插入位置和备注说明，理解图片与内容的对应关系
• 检查资源文件：确认 agent头像、Agent_prompt、image 文件夹是否完整
• 参考已完成订单班：查看 finance.ts、logistics.ts、manufacturing.ts 等已完成的优秀案例

2. Agent设计原则

Agent数量规划

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

Agent配置要素

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

命名规范

• 文件名：{orderClassId}.ts（如 finance.ts）
• 函数名：{orderClassId}Simulation（如 financeSimulation）
• 变量名：{orderClassId}Agents（如 financeAgents）
• orderClassId：与 orderClasses.json 中的 id 完全一致

3. 内容结构设计

启动序列（startupSequence）

目的：营造项目启动氛围，介绍项目背景

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的具体工作内容和成果

标准结构：

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

目的：项目总结和成果展示

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设计师或前端开发的输出中
• 数据分析图：放在数据分析或测试的输出中
• 流程图：放在系统架构师或项目经理的输出中

图片插入格式

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

图片路径规范 (重要)

• ✅ 正确：/data/订单班文档资料/{订单班}/notion文稿/image/{图片名}.jpg
• ✅ 确保图片文件存在且路径正确
• ✅ 如遇图片显示问题，检查软链接：web_frontend/exhibition-demo/public/data/订单班文档资料

5. 内容撰写技巧

信息密度控制

• 每个Agent输出3-5个工作模块
• 每个模块2-4个具体工作项
• 避免过于冗长的描述

专业术语使用

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

成果量化表达

• 好的示例：

  • ✓ 前端开发完成（65个组件，28个页面）
  • ✓ 接口性能：平均响应时间200ms
  • ✓ 测试通过率：98.5%

• 避免的表达：

  • ✓ 前端开发完成
  • ✓ 性能很好
  • ✓ 测试基本通过

分隔符使用

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

6. 开发实例参考

已完成的优秀案例

财经商贸（finance.ts）：

• 9个Agent：从市场调研到内容运营全流程
• 25张图片：涵盖产品设计、内容创作、平台运营
• 特色：电商全链路流程展示，内容营销深度实践

交通物流（logistics.ts）：

• 8个Agent：AGV调度系统完整开发流程
• 10张图片：系统架构、调度算法、界面设计
• 特色：技术架构深度展示，算法优化亮点突出

智能制造（manufacturing.ts）：

• 9个Agent：智能分拣系统全周期开发
• 15张图片：硬件集成、控制系统、测试验证
• 特色：软硬件结合，制造业专业性强

智能开发（dev.ts）：

• 9个Agent：教育平台完整开发
• 9张图片：数据库设计、界面原型、功能演示
• 特色：前后端分离架构，微服务实践

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 中注册：

// 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命令快速检查：

# 查看文档资料结构
ls -la "/data/订单班文档资料/{订单班}/"

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

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

# 检查orderClasses.json中的配置
grep -A 15 '"id": "{orderClassId}"' web_frontend/exhibition-demo/src/data/orderClasses.json

# 编译检查
cd web_frontend/exhibition-demo && pnpm type-check

# 测试运行
cd web_frontend/exhibition-demo && pnpm preview

12. 已完成订单班一览 (2025-10-03)

订单班	文件	Agent数	图片数	状态	特色
文旅	wenlu.ts	7	8	✅	展会策划完整流程
食品	food.ts	7	25	✅	轻食品牌创业方案
财经商贸	finance.ts	9	25	✅	电商全链路运营
交通物流	logistics.ts	8	10	✅	AGV调度系统
智能制造	manufacturing.ts	9	15	✅	智能分拣系统
智能开发	dev.ts	9	9	✅	教育平台开发
土木水利	civil.ts	8	11	✅	防洪堤加固工程
能源	energy.ts	9	16	✅	光伏检测系统
大健康	health.ts	7	8	✅	AI心理咨询平台
视觉设计	design.ts	-	-	⏳	待开发
化工	chemical.ts	-	-	⏳	待开发
环保	environment.ts	-	-	⏳	待开发

---

备注：本指南基于9个已完成订单班的开发经验总结，适用于所有订单班的终端模拟内容开发。最新更新时间：2025-10-03