news 2026/9/20 22:48:02

如何用Open Mercato AI Playground调试智能体：Playground完整指南

作者头像

张小明

前端开发工程师

1.2k 24
文章封面图
如何用Open Mercato AI Playground调试智能体：Playground完整指南

如何用Open Mercato AI Playground调试智能体：Playground完整指南

【免费下载链接】open-mercatoThe AI-Engineering Foundation Framework for CRM/ERP and commerce: open-source TypeScript, with multi-tenancy, RBAC, events and domain modules already decided as conventions and specs, so Cursor, Claude Code and Codex build features instead of re-deciding architecture. Start with 80% done.项目地址: https://gitcode.com/GitHub_Trending/op/open-mercato

Open Mercato 是一款面向 CRM/ERP 与商务场景的开源 AI 工程基础框架，其内置的AI Playground是调试智能体（AI Agent）最快的"沙盒"：无需搭建任何宿主页面，你就能端到端地运行、对话、检查工具调用和提示词覆盖效果。本文将用零基础友好的方式，带你走完 Playground 的完整使用流程：打开入口、选择智能体、跑通聊天与结构化输出两种模式，并读懂调试面板里的每一处细节。

一、什么是 Open Mercato AI Playground

AI Playground 是一个交互式调试页面，它会列出当前应用里所有已注册的 AI 智能体，让你直接在浏览器里验证：

  • 智能体能否正常响应（模型、Provider 是否配置正确）
  • 工具白名单（allowed tools）是否按预期生效
  • 租户级提示词覆盖（prompt override）是否即时生效，无需重启
  • 智能体循环（agentic loop）每一步使用了哪个模型、调用了哪些工具、为什么停止

页面由 AiPlaygroundPageClient.tsx 实现，官方文档见 playground.mdx。

二、快速打开 Playground：入口与权限

Playground 的访问路径固定为：

/backend/config/ai-assistant/playground

🔐唯一前提：当前用户需要具备ai_assistant.settings.manage特性（feature）。这个权限在 page.meta.ts 中声明——如果你打开页面看不到内容，先确认角色是否被授予了该特性。

三、选择智能体：一张信息卡片看懂全部配置

进入页面后，顶部的Agent 选择器会列出所有聚合进ai-agents.generated.ts的智能体。选中某个智能体后，信息卡片会立刻显示它的关键配置：

字段含义
Module智能体所属模块，如customers
Execution modechat（默认对话模式）或object（结构化输出模式）
Mutation policy写操作策略，如read-only
Allowed tools该智能体可用的工具数量

选择器还会驱动调试面板中显示的系统提示词、工具白名单和变更策略，所以换智能体后请留意面板内容是否同步更新。

卡片下方还有Model Resolution 面板，显示本次会话实际解析出的 Provider、模型 ID、Base URL 和来源（如env_default、allowlist_fallback）。这是排查"到底哪个模型在干活"的第一步。

四、Chat 模式：像聊天一样调试智能体

当智能体声明executionMode: 'chat'（默认值）时，Playground 会渲染一个完整的<AiChat>实例，并预注册了四张变更审批卡片（mutation preview、field diff、confirmation、result）。

直接输入问题发送即可。几个实用细节：

  • 任务计划（Task Plan）：如果智能体开启了taskPlan: { enabled: true }，你会在原始工具调用行之上看到实时的任务清单，步骤会从pending→running→done推进
  • 附件上传：若智能体的acceptedMediaTypes非空，输入框旁会出现内联附件上传器
  • 会话隔离：每个会话拥有稳定的conversationId，重复请求会被幂等去重

官方推荐的冒烟测试（可直接照做）：

  1. 选择customers.account_assistant或customers.deal_analyzer
  2. 提问：Find deals assigned to Joe and summarize the useful matches.
  3. 验证任务计划先于工具结果出现、对应步骤走到done、且内部meta.update_task_plan行不会暴露给操作者

五、Object 模式：预览结构化输出

切换到Object mode标签页，聊天框会变成 JSON 输入编辑器 + 结果面板，适合调试executionMode: 'object'的智能体（例如 catalog 模块 中的商品属性抽取器）。

  • 运行后，运行时会自动用agent.output.schema校验返回对象，违规项会内联标出
  • 结果区还会展示 finish reason 与输入/输出 token 用量
  • 展开 "Last request payload" 可看到实际发出的请求体，方便复现问题

⚠️ 注意：chat 类智能体切到 Object 标签会显示"模式不可用"提示，反之亦然——这是正常行为，请选中匹配模式的智能体。

六、调试面板：读懂每一处细节

打开右上角的Debug panel开关后，面板会展示调度器为当前会话做出的完整解析结果，这正是 Playground 的"杀手锏"：

面板内容你能确认什么
Model id + Provider id实际生效的模型（含覆盖来源）
Resolved tool list工具名、isMutation标记、requiredFeatures，验证白名单
Prompt section map每个提示词分节的来源：default/override/placeholder
Tool call + result log实时流式展示每次工具调用与结果
Loop trace最近一轮每一步的模型、工具调用、repairToolCall修复尝试、总 token 和停止原因

Loop trace 的停止原因取值包括stepCountIs、hasToolCall、loop_budget_exceeded、finish-reason:stop|tool-calls|length、aborted——排查"智能体为什么中途停下"时全靠它。

💡典型用法：在 Agent Settings 页面 保存新的提示词覆盖后，无需重启任何服务，直接回到 Playground 发一条消息，就能通过 Prompt section map 确认覆盖已送达运行时。

另外，如果租户在设置中打开了Disable agentic loop急停开关，Playground 会在输入框上方显示LoopDisabledBanner，此时智能体会被折叠为单次模型调用——若你看到"循环突然没了"，先检查这里。

七、Playground vs 页面内嵌 ：何时用哪个

场景推荐
编写智能体、迭代提示词覆盖、QA 工具白名单✅ Playground
真实用户流程（依赖页面上下文的智能体）✅ 页面内嵌<AiChat>

原因很简单：Playground不会传入真实的pageContext，依赖resolvePageContext的智能体在 Playground 里会看到空白上下文。所以最终验收仍需在目标页面完成。

八、键盘快捷键与常见问题排查

快捷键与全局<AiChat>保持一致：

快捷键动作
Cmd/Ctrl + Enter发送消息（Object 模式下提交 JSON）
Escape中止进行中的请求
Shift + Enter换行

遇到异常时，对照 developer-guide.mdx 的常见陷阱表：

现象可能原因解决
智能体不出现在 Playground没跑yarn generate，或文件不在模块根目录移到根目录后重新生成
调度器返回 403requiredFeatures不在用户 ACL 中补进acl.ts并在setup.ts授权，刷新结构缓存
工具对模型"隐身"不在allowedTools中或工具名拼错显式加入白名单（名称区分大小写）
no_provider_configured未配置任何 Provider 环境变量配置ANTHROPIC_API_KEY/OPENAI_API_KEY等

九、参考资料

  • Playground 官方文档：apps/docs/docs/framework/ai-assistant/playground.mdx
  • 页面实现：AiPlaygroundPageClient.tsx
  • 智能体契约与示例：agents.mdx、customers/ai-agents.ts
  • 提示词/策略覆盖：settings.mdx
  • AI 框架总览：overview.mdx

掌握以上流程后，你的智能体调优闭环就完整了：改配置 → Playground 验证 → 页面内嵌验收。

【免费下载链接】open-mercatoThe AI-Engineering Foundation Framework for CRM/ERP and commerce: open-source TypeScript, with multi-tenancy, RBAC, events and domain modules already decided as conventions and specs, so Cursor, Claude Code and Codex build features instead of re-deciding architecture. Start with 80% done.项目地址: https://gitcode.com/GitHub_Trending/op/open-mercato

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

版权声明: 本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若内容造成侵权/违法违规/事实不符，请联系邮箱：809451989@qq.com进行投诉反馈，一经查实，立即删除！
网站建设 2026/9/20 22:47:35

Claude Code vs Codex：同一把 TaoToken Key 跑 AES-GCM 封装

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */#content_views .toc,/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */#content_views.markdown_views > p:empty:has(+ .toc),#content_views.markdown_views …

作者头像 李华
网站建设 2026/9/20 22:45:17

ChatTTS-ui 语音合成音色定制：10分钟拿到3种选音色方法

ChatTTS-ui 语音合成音色定制&#xff1a;10分钟拿到3种选音色方法 【免费下载链接】ChatTTS-ui 一个简单的本地网页界面&#xff0c;使用ChatTTS将文字合成为语音&#xff0c;同时支持对外提供API接口。A simple native web interface that uses ChatTTS to synthesize text i…

作者头像 李华
网站建设 2026/9/20 22:45:13

油猴脚本装完不生效？从匹配规则到CSP的完整排查指南

油猴脚本装好了&#xff0c;脚本也显示“安装成功”&#xff0c;打开网页却一动不动——这个情况我见得太多了。不管是 Tampermonkey 还是 Violentmonkey&#xff0c;凡是折腾过用户脚本的人&#xff0c;十有八九都栽过这个跟头。明明安装步骤没毛病&#xff0c;油猴扩展也在工…

作者头像 李华
网站建设 2026/9/20 22:44:54

QQ空间历史说说导出：免费开源工具的完整使用指南

QQ空间历史说说导出&#xff1a;免费开源工具的完整使用指南 【免费下载链接】GetQzonehistory 获取QQ空间发布的历史说说 项目地址: https://gitcode.com/GitHub_Trending/ge/GetQzonehistory 为什么几年的QQ空间说说自己翻不到 想找一条几年前发的说说&#xff0c;从…

作者头像 李华
网站建设 2026/9/20 22:44:48

@mdx-js/vue 完全指南：在 Vue 项目中用 Context 为 MDX 注入组件

mdx-js/vue 完全指南&#xff1a;在 Vue 项目中用 Context 为 MDX 注入组件 【免费下载链接】mdx Markdown for the component era 项目地址: https://gitcode.com/gh_mirrors/md/mdx mdx-js/vue 是 MDX 官方生态中面向 Vue 的 context 组件提供器&#xff0c;它基于 Vu…

作者头像 李华