直接回复未走 Chat 优化的踩坑复盘（STAR）

背景

在一次编排改造后，用户输入“帮我查今天的炉次生产情况”，系统返回了：

工具参数需要补充/修正（缺少参数: fnCode）…

这类回复有两个问题：

• 对话体验差：像在看内部错误，不像助手对话。
• 信息暴露风险：把内部参数名（fnCode）直接暴露给用户。

本文只记录编排与文案层面的坑和改造，不包含联调过程。

STAR 复盘

S（Situation）

当时的流程是：

• plan 识别到缺参后输出 CLARIFY。
• clarify 节点直接把内部校验信息拼成最终文案。

结果是“系统内部视角”直接到达用户侧：

• 缺参错误码和参数键名进入用户回答。
• 没有一层统一的“面向用户话术”收口。

T（Task）

目标不是修某一个字段（比如只处理 fnCode），而是做通用化治理：

• RESPOND 与 CLARIFY 都走统一对话出口。
• 参数校验结果结构化保留，但用户文案脱敏。
• 避免硬编码问句匹配或字段名特判，保持可扩展。

A（Action）

本次动作拆成三步。

1. 图路由收口到 chat 节点

• 将 RESPOND/CLARIFY 都路由到 chat 节点。
• chat 负责统一生成用户可见回复。
• 好处是把“决策”与“表达”分离：plan 决策，chat 表达。

2. 内部校验与用户文案分层

• 保留结构化校验结果（missing/unknown/tool unavailable）。
• 用户文案层不再透传内部错误码和字段键名。
• 缺参提示优先用 schema 提供的业务标签（如 x-userLabel、x-clarifyTemplate）。

3. 去字段名硬编码

• 删除按参数键名猜测的文案逻辑。
• 统一依赖工具 schema 元数据驱动。
• 当 schema 没有足够标签时，回退到通用友好话术。

R（Result）

改造后的效果：

• 缺参时输出“请补充炉号信息后继续”这类业务友好文案。
• 不再出现 fnCode、missing_arg:* 这类内部信息。
• 对话链路更一致：No tool 与 Clarify 都由 chat 节点收口。
• 回归测试覆盖了“文案脱敏”和“可见流不泄露内部信息”的路径。

关键收益

1. 体验收益：回复从“系统报错风格”回到“助手对话风格”。
2. 安全收益：减少 prompt 与内部参数结构外泄面。
3. 维护收益：表达层集中到 chat，后续改文案不需要改多个节点。
4. 扩展收益：新增工具参数时，优先改 schema 元数据，不改编排核心。

踩坑总结

这次问题的根因不是某个字段，而是边界错位：

• 把内部校验信息当成用户沟通内容直接输出。

一个简单但有效的原则是：

• 内部状态与外部文案必须分层。
• 编排节点输出结构化状态，用户侧只消费经过策略化包装的文本。

这条原则在工具调用、澄清提问、失败回退三个场景都适用。