基于多AI Agent与文件共享的外贸自动化协作平台OpenExt实战-洪萨配资

1. 项目概述：一个基于多AI Agent的外贸自动化协作平台

最近在折腾一个挺有意思的项目，叫OpenExt。本质上，它是一个为外贸团队设计的自动化协作平台，但它的实现方式比较新颖——不是传统的、写死的业务流程自动化，而是基于一个叫OpenClaw的框架，搭建了一个由六个AI Agent组成的“虚拟团队”。这六个Agent各有专长，像销售主管、供应链主管、运营主管、财务主管、人事专员，还有一个总协调官。它们通过读写共享文件夹里的几个Markdown文件来传递信息和协作，共同完成从收到客户询盘，到生成报价、评估供应链、安排生产、核算利润的全链路处理。最酷的是，整个过程可以通过一个Web Dashboard实时可视化，你能像看一场足球比赛直播一样，看到每个“队员”的实时状态和整个流程的推进。

这个项目吸引我的地方在于，它把当下热门的AI Agent协作理念，落地到了一个非常具体、有痛点的业务场景里。外贸业务链条长、环节多、沟通成本高，一个询盘下来，销售、采购、生产、财务可能得来回拉好几个群，发无数封邮件。OpenExt试图用一组分工明确的AI来模拟这个协作过程，让机器去处理信息收集、初步判断和流程推进这些重复性工作，把人解放出来去做更复杂的决策和客户沟通。对于中小型外贸团队或者SOHO创业者来说，如果能把这个系统跑起来，效率提升会非常明显。

整个技术栈选型也很“现代派”。后端Agent运行环境用Docker容器封装，确保了一致性和可移植性；AI模型接入了MiniMax的API，兼顾了效果和成本；前端Dashboard用Next.js + TypeScript构建，提供了清晰直观的可视化界面。无论是想学习多Agent系统设计，还是想为自己的业务找一个自动化提效的解决方案，这个项目都提供了非常完整的参考。接下来，我就结合自己的部署和测试经验，把这个项目的核心设计、实操细节以及踩过的坑，给大家掰开揉碎了讲清楚。

2. 系统架构与核心设计思路拆解

2.1 为什么是“文件共享”式的协作？

刚接触这个项目时，我第一个疑问就是：为什么Agent之间要用读写Markdown文件这种方式来通信？这听起来有点“原始”，不像常见的通过消息队列（如RabbitMQ）或者直接API调用来得“高级”。

深入琢磨和实测后，我发现这个设计其实非常巧妙，解决了多Agent系统里的几个核心难题。

首先是状态持久化与可观测性。每个Agent的工作结果，都白纸黑字地写进了status.md这样的文件里。这意味着，在任何时刻，你都可以直接打开这个文件，看到整个系统的“快照”。这对于调试和监控来说是黄金般的体验。如果Agent之间通过内存中的消息或者复杂的数据库条目来通信，一旦某个环节出错，状态就丢失了，排查起来如同大海捞针。而文件，是最直观、最易读的持久化介质。Dashboard也正是通过轮询读取这些文件，才能实现近乎实时的状态可视化。

其次是降低了Agent间的耦合度。每个Agent只需要关心两件事：从特定文件（如goal.md）读取自己的任务输入，以及将自己的输出按照固定格式写入另一个文件（如status.md）。它不需要知道其他Agent的IP地址、API端点，也不需要处理网络通信的复杂性。这种基于共享工作空间（Workspace）的协作模式，非常类似于一个团队共用一块白板（Workspace文件夹），每个人（Agent）上去写下自己的进展和结论。架构上清晰、简洁，也易于扩展。如果你想新增一个“法务审核”Agent，只需要让它学会去读status.md里的报价和合同条款，然后把审核意见写进去就行，完全不用改动其他Agent的代码。

最后是它为人类参与留下了接口。文件是人类和机器都能轻松理解的东西。作为管理者，你完全可以手动编辑goal.md来下达一个紧急任务，或者直接修改plan.md来调整执行顺序。这种灵活性在纯API驱动的黑盒系统里是很难实现的。文件共享机制在AI与人类之间搭建了一座透明的桥梁。

当然，这种设计也有其代价，主要在于需要处理文件读写冲突（虽然本项目通过Coordinator调度一定程度上规避了）和确保严格的格式规范。但在这个特定场景下，利远大于弊。

2.2 核心组件交互流程全景

理解了文件协作的思想，我们再来看一张简化的数据流图，它描绘了从用户提交任务到最终产出结果的全过程：

用户/Dashboard提交任务 | v 写入 goal.md | v Coordinator Agent 读取 goal.md | v 制定计划 -> 写入 plan.md | v 调度子Agent (sales_lead, supply_lead...) | | | v v v 各Agent执行专业任务 | | | v v v 将结果写入 status.md 对应区块 | v Coordinator 汇总 status.md | v 更新 MEMORY.md (知识沉淀) | v Dashboard 轮询读取所有文件并可视化

1. 任务触发层：起点是用户通过Dashboard的Web界面提交一段自然语言描述的任务，比如“1000件收纳箱询盘，预算1万美金，20天交期”。Dashboard的后端API（/api/task）会将这个描述写入workspace/goal.md文件，并清空status.md和plan.md，为新一轮协作做好准备。

2. 协调与调度层：coordinatorAgent被配置为监控goal.md文件的变化。一旦发现新任务，它立即启动。它的核心工作是“拆解与调度”：首先，理解goal.md中的需求；然后，生成一个具体的执行计划写入plan.md（通常是一个Markdown待办列表）；接着，利用OpenClaw框架提供的sessions_send工具，按照计划顺序，异步地调用sales_lead（销售主管）、supply_lead（供应链主管）等专业Agent。

3. 专业执行层：各个专业Agent被唤醒后，会去读取goal.md了解全局任务，并查看status.md了解当前进展。然后，它们运用自身的人设（定义在agents/*/identity.md中）和AI能力，执行专业判断。例如，sales_lead会基于产品、数量、预算，结合市场常识，生成一份包含单价、总价、付款方式的初步报价。执行完毕后，它必须严格按照规范，将结果以特定格式追加到status.md文件中。

4. 状态汇聚与持久层：所有子Agent都将自己的输出写入同一个status.md文件。coordinator会持续监控这个文件，当它判断所有必要步骤都已完成（或超时），便会进行信息汇总，并将本次任务的关键结果和学到的经验（比如“某供应商对于1000件以下的订单报价偏高”）归档到MEMORY.md中。这个文件相当于团队的长期记忆库，可供未来任务参考。

5. 可视化呈现层：Dashboard作为一个独立的Next.js应用，以固定的时间间隔（默认15秒）调用/api/workspace接口。这个接口会读取workspace/目录下的所有Markdown文件，不仅返回原始内容，更关键的是通过一套解析逻辑（在parseWorkspace.ts中），将半结构化的文本转化为前端可以直接渲染的JSON数据，如Agent状态列表、计划进度百分比、分类日志等，最终呈现给用户一个直观的可视化界面。

整个架构体现了“关注点分离”的思想：AI Agent只管业务逻辑处理和文件读写；Dashboard只管状态可视化和用户交互；而文件系统则充当了可靠、透明的中间媒介。这种设计使得每个部分都可以独立开发、测试和升级。

3. 从零开始：环境部署与核心配置详解

3.1 基础环境准备与一键启动

这个项目的一大优点是依赖清晰，利用Docker做到了开箱即用。你不需要在本地安装Python、Node.js等环境，一切都在容器内。

第一步：获取代码与关键配置首先，将项目代码克隆到本地。接着，最核心的一步是配置环境变量。项目提供了一个.env.example模板，你需要复制它并填入你自己的MiniMax API Key。

git clone <项目仓库地址> OpenExt cd OpenExt cp .env.example .env # 现在，用你喜欢的文本编辑器打开 .env 文件 # 找到 MINIMAX_API_KEY= 这一行，填入你在 minimax.chat 平台申请的API Key # 其他配置如数据库密码可以暂时保持默认

注意：关于MiniMax API Key：这是整个系统的“燃料”。你需要去MiniMax的官网注册账号并创建API Key。通常新用户会有一定额度的免费 tokens 供测试。请务必妥善保管这个Key，不要泄露或提交到公开仓库。

第二步：运行一键启动脚本项目提供了一个非常方便的脚本scripts/start-openclaw.sh。执行它，它会帮你完成所有脏活累活：

bash scripts/start-openclaw.sh

这个脚本依次执行了以下操作：

检查环境变量：确认.env文件中的MINIMAX_API_KEY已设置，否则会报错提示。
初始化Workspace：运行scripts/init-workspace.sh，确保workspace/目录下存在goal.md,status.md等五个必需的Markdown文件（如果不存在则创建）。
启动Docker服务：使用docker compose up -d启动所有定义在docker-compose.yml中的服务，包括：
- openclaw：运行AI Agent的核心后端服务。
- postgres： PostgreSQL数据库，用于存储OpenClaw的会话状态。
- redis： Redis缓存，用作消息队列。
- dashboard： Next.js可视化前端。
健康检查：脚本会等待一段时间，并检查关键服务（特别是openclaw）的容器是否健康运行。

如果一切顺利，你将在终端看到所有容器成功启动的提示。此时，打开浏览器访问http://localhost:3000，就应该能看到OpenExt的Dashboard界面了。

第三步：验证与快速演示Dashboard顶部状态栏显示“● Live”绿色，就说明系统已就绪。为了快速感受整个协作流程，项目还提供了一个演示脚本：

bash scripts/demo-collaboration.sh

这个脚本会模拟用户提交一个“1000件收纳箱，预算1万美金，20天交期”的询盘任务。你可以在Dashboard上实时观察到coordinator如何激活，plan.md中计划如何生成，以及sales_lead、supply_lead等Agent如何依次启动、执行任务，并将结果写入status.md。整个过程大约需要1-2分钟，是理解系统运作最直观的方式。

3.2 核心配置文件深度解析

一键脚本很方便，但要真正驾驭这个系统，必须理解其核心配置。主要涉及三个文件：.env，openclaw.json和docker-compose.yml。

.env– 环境密钥与变量这是所有敏感信息和环境相关配置的入口。除了必须的MINIMAX_API_KEY，还有几个值得关注的选项：

# .env 文件示例 MINIMAX_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx POSTGRES_PASSWORD=openclaw_pass # PostgreSQL数据库密码，按需修改以增强安全 TELEGRAM_BOT_TOKEN= # 如果你需要Telegram机器人通知功能，在此填入Bot Token

实操心得：建议在测试阶段，将.env文件加入.gitignore，避免误提交。生产部署时，应使用更安全的密钥管理方式，如Docker Secrets或云服务商的密钥管理服务。

openclaw.json– AI Agent大脑的配置这个文件定义了OpenClaw框架本身的行为，是所有Agent的“总指挥部”。其核心结构如下：

{ "workspace": "./workspace", // 指定共享工作区目录 "llm": { "provider": "minimax", // 指定使用的LLM提供商 "apiKeyEnv": "MINIMAX_API_KEY" // 从哪个环境变量读取API Key }, "agents": [ // 定义系统中所有的Agent { "id": "coordinator", "model": "minimax-m2.1", // 使用的模型 "identityPath": "./agents/coordinator/identity.md", // 角色定义文件 "tools": ["sessions_send", "read_file", "write_file", "list_files", "get_session_status"] // 可用的工具 }, { "id": "sales_lead", "model": "minimax-m2.5-highspeed", // 销售Agent使用高速模型 "identityPath": "./agents/sales_lead/identity.md", "tools": ["read_file", "write_file"] } // ... 其他Agent配置 ], "server": { "port": 18789 // OpenClaw服务的API端口 } }

关键配置解析：

模型选择：coordinator负责复杂的任务拆解和调度，使用了能力更强的minimax-m2.1模型。而sales_lead需要快速响应客户询盘，因此使用了minimax-m2.5-highspeed高速模型，在保证基本质量的前提下追求更低延迟。你可以根据成本和性能需求调整。
工具授权：tools字段决定了Agent能做什么。只有coordinator拥有sessions_send工具，因此它是唯一的调度者。其他Agent通常只具备read_file和write_file权限，这符合最小权限原则，保证了系统的秩序。
身份定义：每个Agent的identityPath指向一个Markdown文件，里面用自然语言描述了这个Agent的角色、职责、行为准则。这是塑造Agent专业行为的关键。例如，sales_lead的identity.md里会写“你是一名经验丰富的外贸销售主管，擅长快速分析客户询盘并给出有竞争力的报价...”。

docker-compose.yml– 服务编排蓝图这个文件定义了四个服务如何协同工作。理解它有助于故障排查和自定义部署。

version: '3.8' services: openclaw: build: . ports: - "18789:18789" # 将容器内的18789端口映射到主机，可供外部调用（如Dashboard） environment: - MINIMAX_API_KEY=${MINIMAX_API_KEY} # 注入环境变量 volumes: - ./workspace:/app/workspace # 挂载共享工作区 - ./agents:/app/agents # 挂载Agent身份定义 - ./openclaw.json:/app/openclaw.json # 挂载主配置 depends_on: - postgres - redis dashboard: build: ./ui/dashboard ports: - "3000:3000" volumes: - ./workspace:/app/workspace # 关键：Dashboard也需要读写同一个workspace目录 environment: - NODE_ENV=production postgres: image: postgres:15-alpine environment: POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-openclaw_pass} volumes: - postgres_data:/var/lib/postgresql/data # 数据持久化卷 redis: image: redis:7-alpine volumes: - redis_data:/var/lib/redis/data volumes: postgres_data: redis_data:

关键点解析：

卷挂载（Volumes）：这是实现文件共享协作的物理基础。openclaw服务和dashboard服务都将宿主机的./workspace目录挂载到了各自容器内的/app/workspace路径。这样，两个独立的容器进程才能访问和修改同一组文件。
网络互通：默认情况下，docker-compose会为这些服务创建一个共同的网络，openclaw服务可以通过服务名（如postgres、redis）直接访问数据库和缓存，无需知道IP地址。
依赖关系：openclaw服务depends_on了postgres和redis，确保数据库先启动。但注意，这仅保证容器启动顺序，不保证服务就绪。一键启动脚本中的“健康检查”就是为了解决真正的就绪问题。

3.3 常见部署问题与排查

即使有一键脚本，部署过程中也可能遇到问题。这里记录几个我踩过的坑和解决方法。

问题一：Dashboard显示● Down，无法连接OpenClaw。这是最常见的问题，意味着前端无法访问后端的OpenClaw API（端口18789）。

排查步骤：
1. 检查容器状态：运行docker compose ps。确认openclaw容器的状态是“Up”而不是“Exit”或“Restarting”。
2. 查看容器日志：运行docker compose logs openclaw。这里通常会有错误信息。最常见的原因是.env文件中的MINIMAX_API_KEY未设置或无效。日志中可能会显示“Authentication Error”或“Invalid API Key”。
3. 检查端口占用：确认本地18789端口没有被其他程序占用。可以运行lsof -i:18789(Mac/Linux) 或netstat -ano | findstr :18789(Windows) 查看。
4. 检查网络：在openclaw容器内部，它监听的是0.0.0.0:18789。确保docker-compose.yml中端口映射正确（"18789:18789"）。
解决方案：
- 如果API Key错误，修正.env文件后，重启服务：docker compose restart openclaw。
- 如果是端口冲突，修改docker-compose.yml中openclaw的端口映射，例如改为"28789:18789"，同时需要修改Dashboard的配置（如果它硬编码了18789地址，通常不会，因为它通过Docker网络访问）。

问题二：提交任务时报错“Workspace目录为只读”。Dashboard的/api/task接口在尝试写入goal.md时失败。

原因：在docker-compose.yml中，dashboard服务的volumes挂载配置被错误地加上了:ro（只读）标志，或者宿主机上的workspace目录权限不足，导致容器内的进程无法写入。
解决方案：
1. 检查docker-compose.yml，确保dashboard的卷挂载行是- ./workspace:/app/workspace，而不是- ./workspace:/app/workspace:ro。
2. 检查宿主机上workspace目录的权限：ls -ld workspace。确保当前用户有读写权限。必要时用chmod命令调整。
3. 修改配置后，需要重建dashboard容器以生效：docker compose up -d --build dashboard。

问题三：Agent执行后，Dashboard状态长时间不更新。你通过日志看到Agent已经运行完毕，但Dashboard上对应的Agent卡片还是“待命”状态。

排查步骤：
1. 直接查看文件：在终端执行cat workspace/status.md。看看Agent的输出是否已经成功写入。这是最直接的验证方式。
2. 检查写入格式：Agent写入status.md的格式必须严格遵循[agent_id] 状态：状态文本的规范。例如[sales_lead] 状态：已完成。如果写成了sales_lead状态：完成或者[sales_lead] status: done，Dashboard的解析器就无法识别，导致状态更新失败。
3. 手动刷新Dashboard：点击Dashboard顶部的“↻ 刷新”按钮，强制前端立即重新拉取数据，排除浏览器缓存或自动轮询延迟的问题。
4. 检查Dashboard日志：运行docker compose logs -f dashboard，查看前端服务是否有解析错误。
解决方案：
- 如果文件内容为空，说明Agent没有成功执行或写入，需要检查openclaw的日志。
- 如果格式错误，需要修改对应Agent的identity.md文件中的提示词（Prompt），明确指示其必须使用规定的格式输出。这是调试Agent行为的关键环节。

4. 核心机制：Workspace文件规范与Agent协作逻辑

4.1 Workspace文件：多Agent通信的“协议”

Workspace目录下的五个Markdown文件，是整个系统的中枢神经。它们不仅是存储介质，更是定义了Agent之间、Agent与人类之间严格的通信协议。理解这个协议，是进行二次开发或故障诊断的基础。

goal.md– 任务发令枪这个文件由人类（通过Dashboard）或外部系统写入，是启动整个协作流程的触发器。内容相对自由，但建议结构清晰。

# Goal - 客户询盘 ## 任务信息 - **提交时间**: 2024-05-27 14:30:00 - **客户来源**: 阿里巴巴国际站 - **优先级**: 高 ## 任务内容 客户询价5000套无线蓝牙耳机，目标市场欧洲，要求有CE认证。客户给出的目标单价是15美元/套，期望30天内交货。请团队评估可行性并提供报价方案。

注意事项：coordinatorAgent会读取这个文件的全部内容作为上下文。因此，除了核心需求，你也可以加入背景信息、客户历史记录（从MEMORY.md中复制过来）、特殊要求等，帮助AI做出更准确的判断。避免在此文件中使用过于模糊或矛盾的描述。

status.md– 实时状态公告板这是最重要的文件，所有执行Agent都必须严格遵守其格式。它本质上是一个键值对列表，但用Markdown的无序列表呈现。

# Status - 任务执行状态 [coordinator] 状态：进行中 - 当前步骤: 等待财务核算结果 - 已完成的子任务: sales_lead, supply_lead, ops_lead [sales_lead] 状态：已完成 - 产品名称: 无线蓝牙耳机 TWS-2024 - 报价单价: 14.80 USD/套 - 报价总价: 74,000 USD (5000套) - 建议付款方式: 30%定金，70%见提单副本付款 - 备注: 价格已包含标准包装，不含特殊Logo印刷。 [supply_lead] 状态：已完成 - 推荐供应商: 深圳鑫科电子 - 采购单价: 11.20 USD/套 (含税) - 最小起订量: 1000套 - 备货周期: 12天 - 认证情况: 已确认具备CE、RoHS认证 [ops_lead] 状态：已完成 - 生产排期: 15天 - 物流方案: 海运拼箱 (深圳盐田港至荷兰鹿特丹港) - 预计物流时间: 22天 - 总交期预估: 37天 (生产15天 + 物流22天) - 预警: 总交期超出客户期望7天。 [finance_lead] 状态：进行中 - 当前步骤: 核算净利润与汇率风险

格式强制要求与解析逻辑：

Agent标识行：必须以[agent_id] 状态：开头，后面紧跟状态文本。方括号内的agent_id必须与openclaw.json和AGENT_DEFINITIONS中的定义完全一致。冒号必须是中文全角冒号：。
状态文本：决定了Dashboard中Agent卡片的颜色。解析器识别关键词：
- 完成、已完成-> 绿色
- 进行中、处理中、核算中-> 蓝色
- 异常、失败、错误-> 红色
- 其他任何文本 -> 灰色（待命）
字段行：每个字段以-（减号加空格）开头，后面跟字段名: 字段值。字段名和值之间用冒号和空格分隔。解析器会提取这些键值对，显示在Dashboard的Agent卡片上。
多个Agent：一个status.md文件中可以包含多个Agent的区块，解析器会按顺序识别并全部渲染。

plan.md– 可视化进度条由coordinator生成，是一个Markdown任务列表。Dashboard会解析其中的复选框[ ]和[x]来计算完成百分比。

# Plan - 任务执行计划 1. [x] 接收并解析客户询盘任务 (goal.md) 2. [x] 制定本任务协作计划 3. [x] 调用销售主管(sales_lead)生成初步报价 4. [x] 调用供应链主管(supply_lead)评估货源与成本 5. [x] 调用运营主管(ops_lead)评估生产与物流 6. [ ] 调用财务主管(finance_lead)核算利润与风险 7. [ ] 汇总所有结果，生成最终报告并更新团队记忆(MEMORY.md)

提示：coordinator的identity.md中需要明确指示它使用这种格式来生成计划。你也可以自定义计划模板，只要保持是Markdown复选框列表，前端的解析逻辑就能处理。

log.md– 系统运行日记用于记录非业务性的系统事件，如Agent调用开始/结束、异常错误、重试信息等。格式相对简单。

# log.md — 异常与操作日志 [INFO] 2024-05-27 14:30:05 新任务已提交，目标：5000套蓝牙耳机询盘。 [INFO] 2024-05-27 14:30:15 coordinator 开始处理任务。 [WARN] 2024-05-27 14:32:10 supply_lead 调用供应商接口超时，首次重试。 [ERROR] 2024-05-27 14:32:30 supply_lead 供应商接口持续无响应，标记为异常。 [INFO] 2024-05-27 14:33:00 coordinator 检测到supply_lead异常，尝试备用方案。

日志级别[INFO]、[WARN]、[ERROR]、[DEBUG]会被Dashboard用不同颜色高亮显示，便于快速定位问题。

MEMORY.md– 团队知识库用于沉淀跨任务的知识和经验。格式最为自由，通常用二级标题##来划分不同的记忆段落。

# MEMORY.md — 团队长期记忆 ## 团队成员与职责 | Agent ID | 角色 | 擅长领域 | |----------|------|----------| | sales_lead | 销售主管 | 快速报价、客户沟通、谈判条款 | | supply_lead | 供应链主管 | 供应商寻源、成本分析、备货周期 | ## 2024-05-27 - 5000套蓝牙耳机询盘总结 - **最终结果**: 因交期无法满足客户要求（需37天 vs 客户要求30天），订单未成交。 - **经验教训**: - 鑫科电子产品质量稳定但交期较长，对于急单需提前预警。 - 欧洲航线海运时间波动大，报价时应增加缓冲期。 - **客户反馈**: 客户对价格满意，但交期是硬性要求，已建议其寻找现货或空运方案。

MEMORY.md的内容可以被未来的任务引用。你可以在新的goal.md中写道：“参考上次蓝牙耳机项目的经验，本次客户对交期非常敏感，请优先考虑交期短的供应商。”这样能为AI提供宝贵的上下文。

4.2 Agent身份定义与行为塑造

每个Agent的行为，主要由其identity.md文件塑造。这个文件就是给AI模型的“角色扮演”提示词（Prompt）。写得好，Agent就专业；写得模糊，Agent就可能胡言乱语或格式错误。

以sales_lead（销售主管）为例，一个有效的identity.md可能包含：

# 身份：外贸销售主管 你是一名有10年经验的外贸销售总监，专注于家居用品、电子消费品和轻工产品。你深谙国际贸易规则，擅长成本核算和快速报价。 ## 你的核心职责 1. 分析客户询盘，识别产品、数量、预算、交期等关键信息。 2. 基于当前市场行情、产品成本、合理利润率和公司政策，生成一份具有竞争力的初步报价单。 3. 报价需清晰、专业，并包含必要的商务条款。 ## 工作流程与输出规范 1. **输入**：你会读到`workspace/goal.md`文件中的客户询盘内容。 2. **分析**：仔细分析客户需求，如有模糊之处，基于你的经验做出合理假设，并在输出中说明。 3. **输出**：你必须将你的分析结果，严格按照以下格式，写入`workspace/status.md`文件： [sales_lead] 状态：已完成 - 产品名称: [你识别的产品名称] - 报价单价: [计算出的单价，包含货币单位，如 12.50 USD/件] - 报价总价: [单价*数量，如 12,500 USD] - 付款方式: [你建议的付款方式，如 30% TT deposit, 70% against B/L copy] - 预计交期: [你根据生产和物流估算的交期，如 25 days] - 备注: [任何额外的说明，如价格有效期、最小起订量、认证情况等] **重要！**：状态必须写“已完成”。字段名必须使用中文冒号“：”。确保数字格式易读（如使用千位分隔符）。你的输出将直接呈现给客户，务必专业、准确。

设计心得：

明确指令：告诉AI“必须”做什么，使用“严格遵循以下格式”等强约束词语。
提供范例：在Prompt中直接给出期望的输出格式范例，效果远好于抽象描述。
设定边界：明确说明输入源（goal.md）和输出目标（status.md），防止AI臆想不存在的接口。
注入领域知识：在身份描述中融入行业术语和常见做法（如付款方式“TT against B/L”），能显著提升AI回复的专业性。
迭代优化：首次定义后，通过观察Agent的实际输出，反复调整identity.md的措辞。如果Agent总是漏掉某个字段，就在Prompt里强调它；如果格式总错，就把范例写得更清楚。

4.3 Coordinator：虚拟团队的“项目经理”

coordinator是这个多Agent系统的“大脑”和“调度中心”。它的identity.md最为复杂，需要定义其调度逻辑。

一个基础的coordinator身份描述会包括：

角色：资深项目经理，负责分解任务、分配资源、监督进度、汇总成果。
输入监听：持续监控workspace/goal.md文件，任何新内容都视为新任务。
计划制定：收到新任务后，首先分析需求，然后创建一个详细的、分步骤的执行计划，写入workspace/plan.md。计划通常是一个待办列表。
Agent调度：根据计划，使用sessions_send工具，按顺序或并行地调用其他Agent（如sales_lead,supply_lead）。它会等待一个Agent完成（状态变为“已完成”）或超时后，再决定是否调用下一个。
状态监控：持续读取workspace/status.md，跟踪每个子Agent的进度。
结果汇总与归档：当所有必要步骤完成或达到终止条件时，从status.md中提取关键信息，生成一份总结报告，并更新workspace/MEMORY.md，记录本次任务的经验教训。

它的强大之处在于，整个协作流程不是硬编码的，而是由这个“AI项目经理”根据每次任务的具体情况动态规划和调整的。这比固定的工作流引擎要灵活得多。

5. Dashboard可视化前端的开发与定制

5.1 架构解析：Next.js API路由与文件解析

Dashboard不是一个简单的静态页面，它是一个全功能的Next.js应用，其核心是提供实时数据给前端界面。关键在于/api/workspace这个API路由。

API路由 (/api/workspace/route.ts)当Dashboard前端需要更新数据时，它会向这个接口发起GET请求。该接口的核心工作是：

读取物理文件：使用Node.js的fs模块，读取workspace/目录下的五个Markdown文件。
调用解析引擎：将读取到的原始文件内容，传递给位于lib/parseWorkspace.ts中的解析函数。
返回结构化JSON：将解析后的数据（Agent状态列表、计划进度、日志数组、记忆片段）与原始内容一起，打包成JSON返回给前端。

这种设计分离了关注点：解析逻辑是纯TypeScript函数，不依赖UI框架，易于单元测试；API路由负责I/O和HTTP通信；前端组件只负责渲染数据。

解析引擎 (lib/parseWorkspace.ts)这是Dashboard的“大脑”，负责将半结构化的Markdown文本转化为结构化的数据对象。它的解析逻辑直接决定了前端显示是否正确。我们深入看一个关键函数parseStatusMd：

export function parseStatusMd(content: string): ParsedAgent[] { const lines = content.split('\n'); const agents: ParsedAgent[] = []; let currentAgent: ParsedAgent | null = null; for (const line of lines) { // 1. 匹配Agent标识行，如 [sales_lead] 状态：已完成 const agentMatch = line.match(/^\[([^\]]+)\]\s*状态：\s*(.+)$/); if (agentMatch) { if (currentAgent) agents.push(currentAgent); // 保存上一个Agent const [, agentId, statusText] = agentMatch; const definition = AGENT_DEFINITIONS.find(a => a.agentId === agentId); currentAgent = { agentId, displayName: definition?.displayName || agentId, emoji: definition?.emoji || '❓', status: mapStatusTextToStatus(statusText), // 将文本映射为‘completed‘，‘pending‘等 statusText, fields: {}, // 初始化字段对象 formatError: false }; continue; } // 2. 匹配字段行，如 - 单价: 9.50 USD/件 if (currentAgent && line.startsWith('- ')) { const fieldMatch = line.match(/^-\s*([^:]+):\s*(.+)$/); if (fieldMatch) { const [, key, value] = fieldMatch; currentAgent.fields[key.trim()] = value.trim(); } else { // 如果匹配失败，说明格式不符合规范 currentAgent.formatError = true; } } } if (currentAgent) agents.push(currentAgent); return agents; }

解析逻辑要点：

正则表达式是关键：它使用严格的正则来匹配[agent_id] 状态：xxx和- 字段名: 字段值。任何偏差（如空格数量、冒号全半角）都可能导致解析失败。这也是为什么Agent输出格式必须严格。
状态映射：mapStatusTextToStatus函数将中文状态文本映射为内部枚举（如‘completed‘, ‘running‘, ‘error‘），用于决定UI颜色。
字段提取：所有匹配到的字段会被收集到一个fields对象中，前端可以自由地将其渲染为表格、列表或卡片。
错误处理：formatError标志位用于在前端提示用户“该Agent的输出格式可能有问题”，这是一个非常实用的调试辅助功能。

AGENT_DEFINITIONS数组定义了系统中所有已知的Agent，用于提供显示名和图标。当你新增一个Agent时，必须在此处注册，否则Dashboard无法识别和正确显示它。

5.2 功能扩展：如何新增一个自定义Agent

假设你的外贸业务需要增加一个“质检主管”（qc_lead）Agent，负责评估产品质检标准和出具质检报告。以下是完整的添加步骤：

第一步：创建Agent身份定义在agents/目录下新建qc_lead文件夹，并在其中创建identity.md文件。

# 身份：外贸质检主管 你是一名严谨的产品质检专家，熟悉各类消费品（特别是电子、家居、纺织品）的国际质检标准（如CE, FCC, CPSC, REACH等）。 ## 你的职责 1. 根据产品类型，判断其需要通过的强制性认证和检测项目。 2. 评估完成这些质检所需的时间和预估成本。 3. 识别潜在的质量风险点。 ## 工作流程 1. 阅读`goal.md`了解产品信息，阅读`status.md`了解当前报价和供应商信息。 2. 进行质检评估。 3. 将结果按以下格式写入`status.md`： [qc_lead] 状态：已完成 - 所需认证: CE, RoHS, FCC (Class B) - 预估质检时间: 7个工作日 - 预估质检费用: 800 USD - 主要风险点: 电池部分需符合UN38.3测试，供应商需提供相关证明。 - 建议: 订单确认后应立即启动认证流程，以免影响交货。

第二步：在OpenClaw主配置中注册Agent编辑openclaw.json文件，在agents数组中添加新Agent的配置。

{ "id": "qc_lead", "model": "minimax-m2.1", // 使用通用模型即可 "identityPath": "./agents/qc_lead/identity.md", "tools": ["read_file", "write_file"] // 赋予读写文件的权限 }

第三步：在Dashboard解析器中注册Agent编辑ui/dashboard/lib/parseWorkspace.ts文件，找到AGENT_DEFINITIONS数组，添加新Agent的定义。

export const AGENT_DEFINITIONS: AgentDefinition[] = [ // ... 已有的定义 { agentId: 'qc_lead', // 必须与openclaw.json和status.md中的ID一致 displayName: '质检主管', emoji: '🔬', // 选一个合适的图标 description: '负责产品质检标准评估与风险分析' } ];

第四步：更新Coordinator的调度逻辑你需要修改coordinator的identity.md，告诉它在什么情况下应该调用新的qc_lead。通常在计划（plan.md）中加入一步，例如在供应链评估之后，财务核算之前，加入“调用质检主管评估质检要求”。

第五步：重启服务并测试

# 重启openclaw服务以加载新Agent配置 docker compose restart openclaw # 如果有修改Dashboard代码，可能需要重启或重建dashboard服务 docker compose restart dashboard # 或者如果修改了ts文件，需要重新构建 docker compose up -d --build dashboard

重启后，提交一个包含复杂产品（如带电池的电子产品）的询盘任务，观察coordinator是否会调度qc_lead，以及qc_lead的输出是否能正确显示在Dashboard上。

5.3 状态监控与问题排查实战

Dashboard不仅是展示界面，更是强大的监控和调试工具。

利用日志标签页 (🚨 日志)：当系统行为异常时，第一时间查看这里的log.md内容。ERROR级别的日志会高亮显示，直接指向问题根源。例如，如果看到[ERROR] sessions_send to sales_lead failed: Timeout，就知道是调用销售Agent时出现了超时，可能是网络问题或模型API响应慢。

利用原始文件标签页 (📊 原始文件)：这是高级调试的利器。当Dashboard显示的状态与你预期不符时，可以在这里直接查看原始的Markdown文件内容。你可以清晰地看到：

goal.md里的任务描述是否准确？
status.md里各个Agent的输出格式是否完全正确？（比如冒号是不是全角？）
plan.md里的计划步骤是否合理？
MEMORY.md里是否积累了有用的信息？

很多时候，问题就出在Agent没有严格遵守输出格式上。通过查看原始文件，你可以快速定位是哪个Agent的identity.md提示词需要优化。

手动干预与测试：你甚至可以在这个标签页里直接编辑这些Markdown文件（如果Dashboard挂载的目录有写权限），然后点击刷新，来模拟某个Agent的输出，或者手动下达一个新任务。这对于测试Dashboard的解析逻辑和UI响应非常有用。

系统健康检查 (/api/system)： Dashboard顶部的状态栏信息，来源于/api/system接口。这个接口会去探测OpenClaw服务的健康状态（通常是向它的API端口发送一个HTTP请求），并获取当前活跃的会话和Token使用情况。如果这里显示“Down”，基本可以确定是后端OpenClaw服务没有正常运行，需要去检查Docker容器日志。

6. 进阶：生产环境考量与性能优化

6.1 从Demo到生产：安全与稳定性加固

当前的一键部署脚本非常适合本地开发和演示，但要用于实际业务，还需要做一些加固。

1. 密钥管理：绝对不要将包含API Key的.env文件提交到代码仓库。在生产环境（如云服务器），建议使用：

Docker Secrets：如果你使用Docker Swarm，这是管理敏感信息的最佳实践。
云平台密钥管理服务：如AWS Secrets Manager, Azure Key Vault, GCP Secret Manager。在docker-compose.yml中通过环境变量引用这些服务提供的密钥。
环境变量注入：在服务器上通过export命令设置环境变量，或在CI/CD流程中注入。

2. 网络与安全：

限制端口暴露：docker-compose.yml中，openclaw服务映射了18789端口到主机，这是为了Dashboard能访问。在生产环境，如果Dashboard和OpenClaw部署在同一台机器或同一Docker网络中，可以移除这个端口映射，仅通过Docker内部网络通信，更安全。
为PostgreSQL和Redis设置密码：示例中使用了默认密码。生产环境务必使用强密码，并考虑将PostgreSQL的端口（5432）不映射到主机，仅限容器内部访问。
启用HTTPS：为Dashboard（端口3000）配置SSL证书，可以通过Nginx反向代理实现，避免数据在传输中被窥探。

3. 数据持久化：示例中已经为PostgreSQL和Redis配置了Docker卷（postgres_data,redis_data），这能保证容器重启后数据不丢失。确保这些卷被备份到安全的位置。

4. 日志收集与监控：

集中式日志：将Docker容器的日志导出到ELK（Elasticsearch, Logstash, Kibana）或Loki等日志聚合系统，便于搜索和分析历史问题。
应用性能监控：可以给OpenClaw服务添加简单的健康检查接口，并利用Prometheus和Grafana来监控API调用延迟、Token消耗速率等指标。

6.2 性能优化与成本控制

1. 模型选择与成本： OpenExt默认使用MiniMax的模型。m2.1和m2.5-highspeed的定价不同。coordinator的调度和决策逻辑相对复杂，使用能力更强的m2.1是合理的。但对于sales_lead这类输出格式固定、逻辑相对简单的Agent，可以尝试切换到更小、更快的模型（如果MiniMax提供的话），甚至可以考虑使用本地部署的小模型（如Qwen2.5-7B-Instruct），但这需要修改OpenClaw框架的LLM接入层。核心思路是：根据Agent任务的复杂度和对响应速度的要求，分级选用模型，优化整体成本。

2. 异步与并行优化：目前coordinator的调度在示例中可能是顺序的。在实际业务中，有些步骤可以并行。例如，supply_lead（供应链）和ops_lead（运营）的评估，在获得产品基本信息后就可以同时进行。你可以在coordinator的identity.md中设计更复杂的并行调度逻辑，利用OpenClaw的sessions_send同时发起多个调用，从而缩短整个流程的端到端时间。

3. 缓存策略：对于一些相对静态的信息，比如常见产品的市场均价、固定供应商的基准报价、标准物流路线时效等，可以设计一个缓存机制。例如，让Agent在查询前先检查MEMORY.md或一个专门的cache.md文件中是否有近期可用的数据，避免每次都调用LLM进行重复计算，既能加快响应，也能节省Token。

4. 超时与重试机制：在openclaw.json中，可以配置每个Agent调用的超时时间。对于网络调用LLM API，设置一个合理的超时（如30秒）并配置重试次数（如2次），可以提高系统的健壮性，避免因单次API临时故障导致整个流程卡住。

6.3 扩展思路：与其他系统集成

OpenExt本身是一个独立的协作平台，但其价值可以通过集成进一步放大。

1. 与外部业务系统集成：

CRM/ERP集成：可以通过扩展coordinator的能力，或增加一个专门的integration_agent，使其能够调用外部系统的API。例如，从CRM中读取客户历史信息写入goal.md作为上下文；或者将最终生成的报价单自动推送到ERP系统创建销售订单。
邮件集成：增加一个email_agent，当协作流程到达某个节点（如报价生成完毕）时，自动给客户发送一封格式优美的报价邮件。

2. 多渠道任务接入：除了Dashboard网页提交任务，项目已经预留了Telegram Bot的接入点（通过--profile telegram启动）。你可以类似地扩展出：

邮件监听：部署一个服务监听特定邮箱，将收到的询盘邮件自动解析并写入goal.md。
API网关：对外提供一个标准的REST API，让其他软件系统可以直接向OpenExt派发任务。

3. 工作流自定义与版本控制：将agents/*/identity.md和openclaw.json等配置文件纳入Git版本控制。这样，你可以为不同的产品线、不同的客户群体创建不同的分支，拥有定制化的Agent团队和协作流程。通过CI/CD管道，实现配置的自动化测试和部署。

这个项目提供了一个极其灵活和强大的多Agent协作框架。它的核心价值不在于解决某一个具体的外贸报价问题，而在于展示了一种基于文件共享和LLM驱动的、高度可解释和可定制的自动化协作范式。你可以将这套模式应用到客服工单处理、内容创作流水线、内部审批流程等无数场景中。理解其精髓后，剩下的就是结合你自己的业务需求，去设计和培养你的“AI员工团队”了。