若Marketplace服务异常，需依次验证API配置、启用契约同步、配置会话隔离、透出交易状态、调试链路追踪。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您希望在 HermesAgent 生态中启用数据交易能力，但 Marketplace 服务无法正常接入或响应异常，则可能是由于 Marketplace API 认证失败、网络策略限制或契约版本不匹配所致。以下是解决此问题的步骤：
一、验证 Marketplace API 接入配置
该步骤用于确认 HermesAgent 与 Marketplace 之间的基础连接参数是否正确，包括端点地址、API Key 权限范围及认证方式是否符合 Marketplace v1.3 契约规范。
1、打开 HermesPlatformConfiguration 配置文件，定位 marketplace 配置节。
2、检查 endpoint 字段是否指向有效的 Marketplace 公网地址，例如 https://marketplace.hermes.nous/api/v1。
3、确认 apiKey 字段值已通过 Marketplace 控制台生成，并具备 data:read data:write 权限。
4、验证 authMethod 是否设为 bearer-jwt，且对应 JWT 签发方（issuer）与 Marketplace 所要求的完全一致。
二、启用 Marketplace 数据契约同步机制
该步骤确保 HermesAgent 运行时能动态加载 Marketplace 提供的数据产品 Schema 和定价策略，避免因本地缓存过期导致交易请求被拒绝。
1、在 HermesCliProvider 初始化流程中，调用 marketplace/sync ACP 协议方法。
2、设置同步触发条件为 on-startup 和 every-6h，防止长时间运行后 Schema 脱离最新版本。
3、检查 StdioAcpTransport 日志中是否出现 [marketplace] sync completed: 12 schemas, 8 pricing rules 类似成功标记。
4、若同步失败，需手动执行 curl -X POST http://localhost:8080/acp/marketplace/sync -H "Authorization: Bearer $TOKEN" 进行诊断。
三、配置 CliAcpSessionPool 的 Marketplace 会话隔离策略
该步骤防止 Marketplace 数据交易请求与其他 Agent 任务共享同一 ACP 子进程，规避内存污染与上下文混淆风险。
1、在 CliAcpSessionPool 初始化参数中，添加 sessionType: marketplace 标识。
2、为 Marketplace 专用会话池单独设置最大并发数 maxConcurrentSessions: 3，避免高并发下单导致 Marketplace 限流。
3、确保每个 Marketplace 会话启动时注入环境变量 HERMES_MARKETPLACE_MODE=true。
4、验证子进程启动命令是否包含 --marketplace-mode 参数，例如 hermes-acp --marketplace-mode --config /etc/hermes/marketplace.yaml。
四、实现前端 ExecutorAvatar 的 Marketplace 交易状态透出
该步骤使用户可在 HagiCode 前端界面实时感知数据交易进度，包括上架审核、支付确认与交付完成等关键节点。
1、在 ExecutorAvatar 组件中引入 MarketplaceStatusBadge 子组件。
2、通过 SignalR 订阅 marketplace/transaction/{txId}/status 主题，接收服务端推送的状态变更事件。
3、将接收到的 status 字段映射为前端语义化标签，例如 pending_review → 审核中、payment_confirmed → 支付成功。
4、当 status 变更为 delivery_complete 时，自动触发 downloadDataPackage 方法并禁用重复下载按钮。
五、调试 Marketplace 数据交易失败的链路追踪
该步骤用于快速定位交易失败发生在哪一环节，涵盖从前端发起、ACP 协议转发、Marketplace 服务处理到最终回调的全路径。
1、在 HermesGrain 中启用 ACP 请求级 traceId 注入，确保每个 marketplace/buy 请求携带唯一 X-Hermes-Trace-ID 头。
2、在 Marketplace 服务日志中搜索该 traceId，确认是否收到请求及返回的 HTTP 状态码与 body 内容。
3、若 Marketplace 侧无日志记录，检查 StdioAcpTransport 是否将请求正确序列化为 ACP 格式，重点验证 method 字段是否为 marketplace/buy，而非拼写错误的 marketplace/purchase。
4、若 Marketplace 返回 400 错误，提取 response body 中的 validationErrors 字段，比对 dataProductId 是否存在于当前同步的 Schema 列表中。
