PolarDB Agent Express 一键对接钉钉飞书企业微信零代码部署AI Agent实战指南把 PolarDB 里的销售数据接进钉钉群让同事直接发一句“上个月华东区哪款产品卖得最好”机器人就能把 Top 3 列表返回出来——这个需求我去年用传统方式做了一周多今天用 PolarDB Agent Express从开数据库到群里能查到数据前后不到一个小时。这篇文章就把完整的部署过程、配置参数和我在钉钉、飞书、企业微信三个平台上踩过的坑全部写出来给准备做同类事情的同学一份可以直接抄的作业。先说清楚 Agent Express 是什么。它不是什么黑科技更不是重新发明轮子而是把“数据库—自然语言理解—IM 消息通道”这条链路上的所有基础设施都做好了你只需要在控制台里选好数据源、勾选允许访问的表、配置好钉钉机器人的回调地址剩下的事情——意图识别、SQL 生成、结果格式化、消息推送——都由平台层处理。对于已经用了 PolarDB 的业务团队来说这基本就是“给数据库配了一个听得懂人话的前台”而且不用自己维护任何后端服务。这篇文章适合谁看数据负责人、业务系统的运维、被老板要求“三天内做个 AI 助手”但又不想引入重型架构的同学。我会尽量把为什么这么做也讲透而不是只丢给你一堆按钮位置。1. 先搞懂 Agent Express 到底在替你做什么1.1 为什么“给数据库加个 AI 助手”这件事过去很别扭两年前我在另一个项目里做过类似的事在钉钉群里挂一个机器人同事可以查询订单数据。当时的技术栈是这样的——后端用 Python FastAPI 接收钉钉回调转发给 GPT 接口做意图识别再把结构化结果拼成 SQL 查 PolarDB最后把查询结果用 Markdown 格式回推到钉钉群。听起来不复杂但真正落地的时候才发现链条非常长。首先是意图识别用户说的是“上个月的退货情况”你到底要查的是退货数量、退货金额还是退货率这里需要维护一套 Prompt 模板还要针对不同的业务表反复调。然后是 SQL 生成的安全问题模型可能生成全表扫描的查询也可能生成带 DELETE 的危险语句你得在中间加一层 SQL 校验器。再然后是消息通道的怪癖钉钉自定义机器人的加签规则、飞书事件订阅的加密方式、企业微信的被动回复超时限制每一个平台都得单独适配。这整套东西做完前后花了一个多月还搭进去了一个后端开发和半个 DBA 的时间。更头疼的是后续维护业务表结构一调整Prompt 里的字段描述全要同步更新IM 平台升级接口文档回调服务又得跟着改。所以当我看到 Agent Express 能把这些环节全部内置、并且在控制台用勾选的方式完成配置时我的第一反应是这东西早该出了。1.2 Agent Express 的定位数据库和聊天窗口之间的“翻译层”用一句话概括Agent Express 在架构上充当了数据库和聊天窗口之间的翻译层。它运行在阿里云一侧由三个核心部分组成数据连接器负责跟 PolarDB 实例通信NL2SQL 引擎负责把用户的自然语言问题转换成可执行的查询消息连接器负责跟钉钉、飞书、企业微信的开放接口交互。当用户在企业微信群里问“今天有多少新订单”时消息链路是这样的企业微信服务器把消息推送到你配置的回调地址这个地址指向 Agent Express→ Agent Express 先做身份认证确认这是被允许的会话 → NL2SQL 引擎结合你预先配置的表结构描述把问题转换成 SQL → 查询 PolarDB → 结果经过格式化模块组装成企业微信支持的文本或卡片消息 → 推送到群里。整个过程对用户来说就像在和一个懂数据的同事聊天但背后每一步都可以在控制台里追踪日志。这个设计最聪明的地方在于它把最容易出错的“模型生成 SQL”和“IM 平台消息签名”两件事全部托管了。对业务方来说你不需要理解 NL2SQL 的 Prompt 工程细节也不需要了解钉钉加签算法你只需要管两件事允许哪些表被查询、允许哪些人使用这个机器人。这就是标题里“零代码”的真正含义——不是说没有代码而是不需要你写代码。1.3 它适合谁不适合谁使用一段时间后我的感受是 Agent Express 的边界非常清晰不是所有场景都适合它。适合的场景有这几类第一内部数据查询机器人运营、销售、财务在群里用自然语言查数据这是它最舒服的定位第二定时报表推送每天早上把昨天的经营数据推到钉钉群替代人工跑数的重复劳动第三轻量级数据答疑比如客服主管问“最近一周退款率最高的商品类目”不用去 BI 系统自己拖图表。如果你已经在使用 PolarDB且团队没有专职的 AI 应用开发人员Agent Express 几乎是零成本上手。不太适合的场景我也要直说如果你的 Agent 需要编排复杂的多步骤任务比如“查一下库存如果低于警戒线就自动发起采购申请”这种涉及外部系统写操作的流程Agent Express 不会是你最理想的载体它更擅长的是查询和汇报不是事务执行。另外如果你的数据源不止 PolarDB还需要同时查 MySQL、SQL Server、API 接口等也不适合硬套在这个工具上它核心支持的是 PolarDB 生态。搞清楚边界就不会在项目中期发现“这工具满足不了我”而返工。2. 部署前准备账号、数据库、Agent 和机器人配置2.1 开通 PolarDB 实例时要留意的几个参数我在测试时用的是 PolarDB MySQL 引擎8.0 版本。如果你手头还没有实例开通的时候有几个点建议提前规划好。地域选择很关键。我之前有个教训在一个靠近自己办公地点的地域建了数据库结果同事出差到外区访问延迟明显偏高。Agent Express 的消息回调链路本身就涉及 IM 平台服务器如果数据库地域离 IM 接入点太远整体响应时间会被拉长。建议选择你的主要用户所在的云地域一般企业内部使用直接选主办公地就近的地域即可。规格方面Agent Express 本身会消耗一部分查询资源但总体很轻。我的测试实例是 2 核 8GB 的 Serverless 形态查询并发不高的情况下完全够用。如果你现有的 PolarDB 已经在承担核心业务读写建议在配置 Agent Express 数据源时使用独立的只读节点或只读账号避免自然语言查询生成的 SQL 影响线上性能——这条后面在权限设计里还会展开。网络访问方式也建议提前决定。Agent Express 在同一 VPC 内访问 PolarDB 是最稳的链路走内网可以避免公网延迟和带宽限制。如果 PolarDB 实例和 Agent Express 不在同一个 VPC 里需要做云企业网打通或使用公网连接但公网连接会增加安全风险不推荐生产环境使用。2.2 在控制台创建 Agent 应用的关键选项进入 PolarDB 控制台找到“集群管理”在左侧菜单里能看到“Agent Express”入口。第一次使用的同学请注意这里不是在数据库实例页面上直接点而是要先创建一个 Agent 应用再把它跟具体的 PolarDB 集群做关联。创建应用的向导里核心就三步填写应用名称、选择关联实例、设置数据访问范围。应用名称建议起一个能表明业务含义的名字比如“销售数据助手”。这个名字会出现在推送到 IM 群里的消息署名位置如果多个部门共用一套系统命名规范能帮你省掉很多辨识成本。选择关联实例时系统会列出当前账号下有权限的 PolarDB 集群。这里要注意的是一个 Agent 应用可以关联多个实例但一个实例也可以被多个 Agent 应用关联你需要想清楚授权边界。比如财务相关的 Agent 和销售相关的 Agent如果都关联到同一个库上就要在下面的表权限和提示词层面做区分不然后果就是销售群里能问财务数据。数据访问范围这一步很关键系统会让你从选定的实例中勾选哪些库、哪些表可以被 Agent 查询。我强烈建议默认只勾选确实需要开放给聊天机器人使用的表和视图而不是直接选择“全部表”。后续也可以在应用详情里随时调整但初始范围收得越紧后面越安全。2.3 三个 IM 平台机器人的申请与回调配置这是整个部署过程里最容易让人烦躁的环节因为三个平台的开发者后台设计思路完全不一样。我把它们分开写。钉钉的做法是企业内部机器人。你需要在钉钉开发者后台创建一个“企业内部应用”然后在“机器人”选项卡里添加机器人。创建完成后你会拿到三个关键信息AppKey、AppSecret 和机器人编码。回调地址即消息接收地址需要填一个 HTTPS 的 URL这个 URL 由 Agent Express 生成在 Agent 应用详情页可以找到。钉钉支持加签模式建议开启Agent Express 控制台里会让你粘贴加签密钥然后它会在回调请求中自动处理签名逻辑。这里有个细节钉钉对回调 URL 有校验你必须先在钉钉后台填写 Agent Express 生成的 URL并且保证该 URL 能公网访问否则配置保存时会报错。飞书走的是“企业自建应用”加“事件订阅”的路线。在飞书开放平台创建应用后需要开启“机器人”能力然后在事件订阅里选择“接收消息”事件把 Agent Express 提供的回调地址填进去。飞书比钉钉多了一道加密配置你可以设置 Encrypt Key 和 Verification TokenAgent Express 的配置页会让你把这两个值填进去双向匹配后回调才生效。飞书的权限审核比较细你至少需要开通“读取用户发给机器人的单聊消息”和“获取群组中所有消息”这两个权限点否则机器人收不到消息。企业微信的逻辑稍有不同它更多依赖“自建应用”而不是独立的机器人。在企业微信管理后台的“应用管理”里创建自建应用后你会拿到 AgentId 和 Secret。接着需要在“企业可信 IP”里配置 Agent Express 服务所在服务器的出口 IP否则企微服务器会拒绝回调请求。这里我踩过一次坑配置了正确的回调地址但漏配可信 IP结果怎么调试都收不到消息后来翻文档才发现企微对可信 IP 是硬校验。三个平台的配置各有侧重我把它们整理成了速查表放在后面第 5.5 节方便对照。2.4 最小权限设计两种必须做好的隔离权限设计在“零代码”项目里最容易被人忽视因为看起来只是勾几个选项的事。但我强烈建议在一开始就做两件隔离。第一件是数据库账号隔离。不要使用 PolarDB 实例的管理员账号去配置 Agent Express 数据源应该单独创建一个只读权限的数据库账号。这个账号只需要有 SELECT 权限甚至连 SELECT 都可以限定在特定数据库上。我一般这样建CREATE USER agent_query% IDENTIFIED BY your_strong_password; GRANT SELECT ON sales_db.* TO agent_query%; FLUSH PRIVILEGES;这样即使 NL2SQL 模型生成了奇怪的 SQL也不可能执行 INSERT、UPDATE、DELETE 操作。这是底线不能省。第二件是表级别的访问范围隔离。在 Agent Express 的数据访问配置里把敏感表比如用户明细、薪资表排除在外。Agents 的 NL2SQL 是在控制台配置的表范围内生成语句的虽然模型也可能因为表结构相似而“联想”出未授权表的名字但由于数据库账号本身没有对应权限执行时会直接报错等于上了双保险。3. 一键对接实操从空白项目到钉钉群能查数据3.1 五分钟把 Agent 接到钉钉群假设你已经完成了第 2 节的准备工作这节我们走一遍完整对接流程。我以钉钉为例。第一步在 Agent Express 控制台打开你的 Agent 应用找到“IM 接入”选项卡平台类型选择“钉钉”然后把钉钉开放平台拿到的 AppKey、AppSecret、加签密钥依次填入。这个页面上会显示一个回调地址先复制下来切到钉钉开发者后台粘贴到机器人的“消息接收地址”里。保存后回到 Agent Express点击“验证连接”系统会向钉钉服务器发送一条测试消息如果积分正常钉钉机器人会回复一条欢迎语。第二步把机器人拉进一个内部测试群。钉钉机器人默认可以被添加到任意群但为了安全我建议单独建一个“数据助手测试群”先不要让全公司的人都看到脏数据。在群里 机器人输入“你好”如果配置正确机器人会回复一条说明自己能查询哪些数据的使用提示。第三步试一条真实数据查询。我在测试时输入的是“查询上个月每天的新增订单数”。Agent Express 后台会返回一条执行日志内容包括识别的意图、生成的 SQL、查询耗时、返回行数。如果你对结果不满意比如它查错了时间范围可以在日志里看到模型到底把“上个月”理解成了哪两个日期非常直观。整个流程走下来如果数据库和回调都正常十分钟以内完全可以完成。我第一次用时不小心把加签密钥填反了多花了五分钟排查后面版本控制台加了“一键测试”按钮体验就好了很多。3.2 飞书与企业微信的对接差异飞书和企微的步骤主体跟钉钉一样但有几个差异点我实际测试后觉得值得单独说明。飞书在“事件订阅”配置这一步最容易卡住。飞书要求回调地址能正确响应 URL 验证请求Agent Express 会自动处理但前提是你在飞书后台填写的 Encrypt Key 和 Verification Token 跟 Agent Express 里填的完全一致。我一开始在飞书后台把 Encrypt Key 留空但 Agent Express 里却填了一个随机值结果 URL 验证一直失败。解决办法很简单不用自己生成 Encrypt Key直接在 Agent Express 的飞书配置页点“一键生成”然后把生成的值完整复制到飞书后台即可。企业微信的差异主要在可信 IP 和消息类型上。可信 IP 配置我在前面提过不再重复。消息类型上企微机器人回复普通文本消息最稳妥Markdown 消息在企微里需要额外的 content type 声明而且不同客户端的渲染效果不一样——有同事在 Windows 客户端看不到表格但在手机端却正常。如果你的用户群里用企微客户端比较杂建议直接在 Agent Express 的输出格式里选择“纯文本”兼容性最好。飞书在消息样式的支持上更友好它原生支持富文本卡片Agent Express 输出的查询结果里带表格时在飞书里会被渲染成类似多维表格的样式可读性明显优于钉钉。如果你的团队同时在用飞书和钉钉想让两边体验一致可以在 Agent Express 里为每个平台独立设置输出格式我通常给飞书用卡片钉钉和企微用文本。3.3 配置数据查询白名单和“禁区”只让 Agent 连上数据库还不够你还需要定义它“能聊什么”。这里我用到了 Agent Express 里两个关键功能数据表白名单和禁用主题。数据表白名单在创建 Agent 关联实例时配置过但它是可以动态调整的。我建议按部门维度去划分。比如销售数据助手只开放销售订单表、客户表、产品表财务数据助手则开放收款流水表和成本表。表与表之间的关联关系也要提前设置好Agent Express 支持在元数据配置里维护外键关系这样模型才知道订单表的 customer_id 可以关联到客户表的 id。不配置关联关系的话多表查询的场景生成 SQL 时大概率会用 JOIN ON 拼错字段查出来的结果就是错的。禁用主题是防止 Agent 被带入敏感话题。比如用户问“这个销售团队的提成是多少”如果你不希望开放这块数据可以在配置中把“提成”“工资”“绩效”这类词加入禁用列表。加了之后Agent 在意图理解阶段就会直接拒绝回答并返回一句“该问题不在我可查询的范围内”。这个能力比单纯不开放表更实用因为即便某张表本身包含提成字段如果你忘记在表的开放范围里排除禁用词列表还能兜底。3.4 定时报表推送让 Agent 每天自动汇报除了被动回答问题Agent Express 还支持定时任务这是很多团队真正需要的“群机器人自动发报表”场景。在 Agent 应用详情页找到“定时任务”创建一个新任务需要配置三块内容执行计划、查询模板、推送目标。执行计划用 cron 表达式。比如每天早上 9 点执行一次表达式是0 0 9 * * ?。注意这里遵循的是 Quartz 风格的 cron而不是 Linux 的 5 位格式。我第一次用习惯性的 5 位格式写结果任务一直没有触发后来看文档才意识到多了秒位。查询模板需要你用自然语言写好“问题”但跟实时查询不同定时任务的查询模板是固定的。比如我设置的模板是“统计昨天每个产品类别的销售总金额按金额降序取前 10 名”每次执行时 Agent 都会按这个模板生成查询。如果你希望在报表里带日期可以在模板中写“昨天”Agent Express 执行时会自动替换成实际日期。推送目标选钉钉群的 Webhook。这里有个细节定时任务推送不需要你在群里 机器人它直接调用钉钉的自定义机器人 Webhook 把消息塞进群。但钉钉对自定义机器人有安全限制你在钉钉群里添加“自定义机器人”时安全设置建议勾选“加签”然后把加签密钥填到 Agent Express 的定时任务配置里否则消息会被钉钉拒绝。我实际测试时从创建定时任务到群里收到第一条报表大约花了三分钟其中大部分时间是等 cron 触发。4. 核心细节提示词、数据安全与成本控制4.1 提示词模板设计如何让 Agent 不“胡说”零代码不代表你完全不用管提示词。Agent Express 在背后用大模型做 NL2SQL但大模型的输出质量极大依赖于你对业务表结构的描述方式。控制台里提供了一个“数据字典”编辑入口这里才是真正需要投入时间的地方。我在配置销售数据助手时数据字典里是这么写的{ tables: [ { table_name: orders, business_name: 订单表, columns: [ {name: order_id, description: 订单唯一编号}, {name: customer_id, description: 下单客户编号关联 customers 表}, {name: amount, description: 订单金额单位元含运费}, {name: order_date, description: 下单时间DATETIME 类型}, {name: status, description: 订单状态pending 待支付paid 已支付cancelled 已取消} ] }, { table_name: products, business_name: 产品表, columns: [ {name: product_id, description: 产品编号}, {name: category, description: 产品类别如 手机、笔记本、配件}, {name: price, description: 销售单价单位元} ] } ] }关键在每一列的描述。否则模型很容易把“销售金额”和“订单金额”混为一谈或者忽略掉 amount 里包含运费这一事实。我见过一个例子用户问“净利润”但表里根本没有净利润字段模型强行用 amount 减了个什么数来算结果完全错误。数据字典里写好“该表没有净利润字段只有订单金额”Agent 在遇到净利润问题时会回答“暂不支持该指标”而不是瞎猜个结果。另外要在数据字典里写清楚字段取值范围。比如 status 只有三种值写进去之后用户问“有效订单”模型就会知道应该查 statuspaid不会把 pending 也算进去。这比你教用户怎么说更可靠。4.2 阈值参数设置别让一条查询拖垮数据库Agent Express 控制台里有一些参数看起来不起眼但生产环境用不好会很痛。我梳理了几个关键项参数名推荐值说明单次查询最大返回行数50超过部分不返回防止结果集过大导致 IM 消息超限查询超时时间10 秒超过后 Agent 返回“查询超时请缩小问题范围”并发查询数5同一 Agent 同时执行的查询上限防止多个用户同时发问压垮实例复杂查询开关关禁止生成多级子查询、跨多个表的复杂 JOIN复杂查询开关是最需要谨慎的。它关掉之后Agent 生成的 SQL 会尽量简单牺牲一部分问题覆盖面但换来了稳定性和安全性。我在初期是打开的结果有一次用户问“查询每个区域的销售额对比”模型生成了三层子查询把 PolarDB 的 CPU 瞬间拉高了 30%。关掉之后虽然面对复杂问题时回复“该问题太复杂请拆分为更具体的查询”但整体稳定性提升明显。如果你的团队里用户都是非技术人员复杂查询开关建议默认关闭。4.3 数据脱敏与审计企业微信里的敏感信息保护当 Agent 要被全公司使用时脱敏就不是可选项了。Agent Express 提供了“敏感字段脱敏”功能在数据字典里可以对指定列开启脱敏策略。我用它处理了客户手机号开启后查询结果里手机会显示成138****1234但数据库原始值不受影响。这比在 SQL 层做截断简单得多因为你不用改表结构也不用担心影响业务系统。审计日志是另一个容易忽略但必须启用的能力。Agent Express 会记录每一次查询的完整链路提问者身份、提问内容、生成的 SQL、实际执行的 SQL、返回结果行数、耗时。我把这些日志接入了云监控并设置了一个告警规则当单条 SQL 扫描行数超过 100 万行时触发告警基本能识别出全表扫描这类危险查询。遇到问题时这套日志能让你快速定位是哪位同事问了什么问题导致数据库抖动而不是让 DBA 拿着执行计划一个个猜。4.4 成本控制别让 AI 机器人在账单上“裸奔”Agent Express 的成本由两部分构成大模型调用的 Token 费用和 PolarDB 自身的查询资源消耗。前者容易被忽略因为零代码界面上你看不到 Token 数字但每个查询背后都在消耗 Token。控制成本的第一招是优化数据字典。数据字典里的内容每次调用模型时都会作为上下文注入写得越长Token 消耗越大。我见过有人把每个字段写了一段五百字的注释结果一次普通查询的输入 Token 直接飙升。正确的做法是精简但准确字段名、类型、一句话说明、取值范围。够用就行。第二招是合理配置缓存。Agent Express 有查询缓存同一自然语言问题在短时间内重复请求时会直接返回缓存结果不触发模型调用和数据库查询。企业内部很多问题就是高度重复的比如每天都有几个人问“昨天销售额”开启缓存后这部分流量完全免费。缓存的过期时间我设置成 10 分钟既能覆盖热问题又不会让数据太旧。第三招是限量。在 Agent 配置里你可以设置每日最大查询次数超过后自动拒绝服务并提示“今日配额已用完”。这样做看起来有点粗暴但能防止某个部门把机器人当成无限查询工具。我给内部测试环境设置的额度是每天 200 次生产环境根据不同部门的实际需求设置 500 到 1000 次。限额不是为了限制生产力而是为了让预算可控。5. 踩坑实录钉钉、飞书、企微高频问题清单5.1 钉钉 H5 应用报错 no permission info for action这个问题是我在配置过程中遇到的第一道坎。报错信息完整内容类似no permission info for action:device.audio.startrecord虽然看起来很吓人但其实跟 Agent Express 本身关系不大而是钉钉 H5 微应用权限声明的问题。如果你把 Agent 的 H5 页面嵌到了钉钉工作台里当用户点开页面时钉钉容器会拦截某些设备 API 的调用。默认情况下H5 页面没有权限调用麦克风、相机这类设备接口需要在钉钉开发者后台的“权限管理”里为应用申请对应权限点。像 startrecord 这种录音权限申请路径是钉钉开发者后台 → 你的应用 → 权限管理 → 搜索“录音” → 申请device.audio.startrecord权限并提交审核。审核通过后还要重新发布应用版本用户端才能生效。更隐蔽的情况是权限点已经开启但代码里用的是旧版 JSAPI。钉钉的 JSAPI 有新旧两套新版权限申请走的是企业自建应用的权限体系旧版可能需要额外配置。我当时的解决办法是升级到钉钉官方推荐的最新版 JSAPI并且在 Agent Express 的 H5 集成页面重新生成了鉴权配置问题才彻底消失。这里插一句如果只是让 Agent 在群聊里收发消息不会遇到这个问题只有在嵌入 H5 页面时才要走这套权限流程。5.2 钉钉扫码登录拿不到 code另一个高频问题是在对接钉钉扫码登录时回调页面里拿不到 code。这个场景常见于你想用钉钉身份登录 Agent 的 H5 管理后台而不是群聊机器人本身。拿不到 code 的原因通常有几个。第一你在钉钉开放平台填写的回调域名和实际页面的域名不一致。钉钉校验很严格只要域名不完全匹配包括协议和端口就会静默失败前端根本收不到回调参数。检查方法是在钉钉后台的应用列表里点“登录与授权”把“回调域名”一栏复制出来和浏览器地址栏逐字符比对。第二回调页面放到了本地开发环境测试。很多人习惯用http://localhost:8080/login做本地调试这在钉钉扫码登录里行不通因为 localhost 不在你的回调白名单里也不支持 HTTP 协议必须是 HTTPS。我当时就耗了大半天的本地调试后来老老实实部署到测试环境才顺利通过。第三前端使用了 history 路由模式回调时路由拦截把参数吃掉了。钉钉扫码登录是在 URL 后面直接拼?authCodexxx参数的如果你的前端路由配置了mode: history很可能会被框架当成路由路径处理而不去解析 query。解决办法是确保在回调路由里用window.location.search去解析参数不要依赖框架的路由 query 对象。5.3 鸿蒙系统钉钉浏览器 SSO 登录白屏这个问题的场景是用户用鸿蒙系统手机在钉钉内置浏览器里访问 SSO 登录页面结果白屏但在普通浏览器或 iOS 钉钉上正常。我排查下来白屏主要是两个原因叠加导致的。第一钉钉内置 WebView 的 UA 字符串在某些鸿蒙版本上不标准导致前端 JS 判断“是不是钉钉环境”时走了错误分支加载了不兼容的登录组件。第二SSO 使用的是 OAuth 流程跳转时依赖第三方 Cookie而鸿蒙版钉钉内置浏览器默认禁用了第三方 Cookie导致登录态无法保持。解决办法分两步。前端层面加一段 UA 兼容逻辑判断到鸿蒙系统时不走钉钉内置浏览器 JSAPI 判断分支而是直接跳转到系统浏览器授权。后端层面在 SSO 服务里添加响应头P3P: CPCURa ADMa DEVa PSAo PSDo OUR BUS UNI PUR INT DEM STA PRE COM这个老牌 header 能兼容部分 WebView 的 Cookie 写入策略。实测下来升级了这两处之后鸿蒙设备上的白屏问题基本消失了。如果你不想改代码还有一个应急方案让用户在钉钉里点击右上角菜单选择“在浏览器打开”SSO 流程走系统浏览器就能绕过白屏。但这不是长久之计体验上多了一步遇到较真的用户还是会投诉。5.4 Agent 回复超时和数据库连接超时的排查思路当你在群里问问题Agent 迟迟不回复最后来一句“查询超时”这种问题几乎每个人都遇到过。排查思路要分两层IM 消息超时和数据库执行超时。先说 IM 消息超时。钉钉、飞书、企业微信对回调接口的响应时间都有硬性要求钉钉一般是 5 秒企微是 5 秒飞书稍宽裕。如果你的 Agent 在这段时间内没回复平台会直接判定超时并且重试几次。Agent Express 处理这一类超时的方法是“先响应后处理”的异步机制收到消息后立即给 IM 平台返回一个“已收到”实际查询逻辑在后台执行查询完成后再主动推送结果。如果你发现 Agent 偶尔不回复大概率是异步推送环节出问题这时候去看 Agent Express 的执行日志重点关注“推送状态”是不是 success。再说数据库超时。我在第 4.2 节设置过查询超时时间 10 秒这是 Agent 执行查询的上限。但 10 秒内如果 PolarDB 本身有慢查询或者连接池满了一样会报超时。另一个常见的坑是 PolarDB 的连接数打满语料里偶发一个坏 SQL 长时间占用连接后面所有查询都排不上队。解决方法是给 Agent 专用的数据库账号设置单独的最大连接数并在 PolarDB 侧开启慢查询日志找到那些潜在的全表扫描语句通过加索引优化掉。-- 查看当前慢查询 SHOW SLOW LOG;如果慢查询集中在某张表通常是有索引没建上。比如我这边 orders 表按 order_date 查询最多加了idx_order_date之后慢查询数量直接降了七成。5.5 多平台配置对照速查表配置项钉钉飞书企业微信应用类型企业内部应用企业自建应用自建应用消息接收地址机器人回调地址事件订阅回调地址接收消息服务器 URL加签/加密加签密钥可选但建议Encrypt Key Verification Token不需要额外加签服务器 IP 白名单无要求无要求必须配置企业可信 IP消息类型纯文本 / Markdown纯文本 / 富文本卡片纯文本最稳权限点机器人发送消息权限读取消息、发送消息权限接收消息、发送消息权限调试入口后台“在线调试”工具开放平台“调试”工具管理后台“接收消息调试”这张表是我在实际配置过程中整理出来的三个平台的坑位不太一样。建议你对接前先逐一确认这些基础项能省掉大量排错时间。6. 性能调优与日常维护建议6.1 索引与慢查询优化让 Agent 的回复更快Agent 体验好不好的一个重要指标是回复速度。用户问一句话十秒钟才出结果体验会大打折扣。我在生产环境做的第一轮优化就是针对查询涉及的字段建立合适的索引。以销售数据助手为例最常被查询的维度是时间、产品类别、区域。我在订单表上建了联合索引(order_date, category)在客户表上建了(region, customer_id)索引。建索引之前一条“查询近七日华东区的订单量”大约耗时 2.3 秒建索引之后降到了 0.6 秒。对数据库来说一个索引轻松解决用户那边就是“秒回”和“等三秒”的差别。另一个实操经验是定期用慢查询日志反哺数据字典。当发现 Agent 经常查某个字段且速度慢就看执行计划是不是没走索引或者数据字典对字段描述导致模型选错了查询条件。这几件事联动起来AI 助手的整体体验才能持续变好。6.2 权限复核与数据字典更新的节奏Agent 上线之后不能当甩手掌柜。我的习惯是每两周做一次权限复核主要检查三件事表结构有没有变化、数据字典是否还准确、权限范围是否仍然符合当前业务需求。数据库表结构变了但数据字典没更新这是最隐蔽的坑。比如业务同事在产品表加了新字段“是否主推”但没有同步更新数据字典用户问“主推产品有哪些销量最高”Agent 很可能找不到“主推”对应的字段而生成错误的关联查询。Agent Express 有一个“同步表结构”按钮点击后会自动拉取最新的表结构但不会自动更新描述信息所以还是需要人工维护数据字典里的业务定义。权限复核环节我一般看审计日志里有没有出现被拒绝的敏感查询如果有就确认提出该问题的用户是不是被授权范围之外的人。内部环境下大多数人不会恶意访问但偶尔有项目组的人为了拿数据方便会尝试问一些越权的东西。权限收紧永远比放开容易原则是当你不确定时先不放权。6.3 我最后的几点体会把 PolarDB Agent Express 从零搭起来并稳定运行一段时间之后回头看的体会是零代码不等于零思考它省掉的是重复的工程劳动但替代不了你对业务的理解。数据字典的质量直接决定这个机器人是个“花瓶”还是真正能用的助手所以投入时间把字段描述写清楚、把取值范围标注全是这笔投入里回报率最高的一件事。第二是要舍得在日志和监控上花时间。Agent 背后是大模型大模型生成 SQL 偶尔确实会出错但如果审计日志和告警策略配置得当这些错误能在一个可控的范围内不会影响业务稳定性。第三是定期回来维护业务表结构会变用户问问题的方式会变Agent 的配置也要跟着迭代很少有人能一次配置一劳永逸。最后分享一个我个人的小习惯每次给 Agent 增加一个新表或新字段时我都会先自己发几轮问题试一遍比如试“这个字段能不能被正确识别”“多条件查询会不会选错列”。AI 助手这东西测试得越充分上线后给业务同事留下的第一印象就越好。第一印象坏了后面再优化同事也不爱用了。希望这篇实战笔记能让你少踩一些我踩过的坑更快把你们的 AI 数据助手跑起来。