让 Agent 动手前先“听懂人话”：意图识别插件的设计与实践

在构建面向业务的自主 Agent 时，许多团队最常遇到的"翻车"场景往往不在于模型的能力上限，而在于理解偏差。当把一个复杂、开放的任务交给大模型时，它最擅长的是"天马行空地生成"，最不擅长的恰恰是"严谨确认边界"。

为了让 Agent 在真正执行代码、调用工具排查系统前建立可靠的确定性边界，我们为轻量级 Agent 运行时 dsh 构建了意图识别插件 dsh-intent。本文梳理其背后的设计取舍、核心机制与落地实践。

一、Agent 翻车的根源：确定性边界缺失

在真实业务场景中，未经意图约束的 Agent 通常会陷入三类典型陷阱：

模糊指令直接臆测：用户输入"优化下这段逻辑"或"帮忙看看这个页面"，模型在未确认目标环境、范围和预期结果的前提下便直接盲目修改，导致大量无效交付。
缺乏领域黑话上下文 ：企业内部往往存在大量特定缩写与代号（如 biz-module 代表业务公共模块，demo-tenant 代表联调沙箱租户）。通用模型冷启动时无法理解这些缩写，从第一步理解就发生偏移。
超范围任务硬着头皮接：面对明显超出职责边界的诉求（例如让排查 Agent 去开发新页面），模型倾向于"讨好型作答"，产生幻觉并给出不可行甚至危险的操作。

核心洞察 ：模型天然适合处理发散性推理，但"确认边界、参数完整性校验、超范围拒识"这类决策必须由确定性逻辑接管。

二、设计思路：分层治理与零额外开销

dsh-intent 采用"通用能力常驻、领域能力按需激活"的双层架构：

通用层（零配置常驻）：自动注入项目内置词汇表（Glossary），并在遇到歧义时触发通用的澄清提示门控。
领域层（声明式按需加载） ：当项目根目录下存在 intents.yml 规则文件时激活，执行闭集意图分类 与槽位补全（Slot Filling）。

核心取舍与技术决策

零额外 LLM 调用的分类回收

业界常见的意图识别方案通常会在主链路前加挂一次前置分类 Prompt。这种做法带来了额外的 Token 开销与首字延迟。

dsh-intent 选择借宿主模型原本的单次推理顺手回收分类结果 ：插件向运行时注册 report_intent 工具，模型在单次决策流中调用该工具完成意图打标。插件在本地接管结果并执行校验（Spec 校验、缺槽重算、拒识判定），实现零额外网络往返与零显式调用开销。
Fail-Open 弹性容错与无感激活

在 Pre-step 阶段，插件每轮至多提醒一次"优先明确分类"，但绝不通过硬 Reject 阻断流程；若项目未声明 intents.yml，相关工具与拦截器完全不挂载，运行时行为与基础环境保持严格一致，平滑兼容老项目。

三、运行时行为：客户问题排查 Agent 实战

结合"轻量 Agent 架构"以及运维排查优先落地的战略，我们通过一个前端故障排查场景完成了端到端验证。该机制固化了四类标准交互行为：

交互行为	典型用户输入	判定与执行逻辑	终端呈现
① 自我边界探查 (Meta)	"你目前支持排查哪些问题类型？知道哪些术语？"	识别为 `meta` 意图，不误判为超范围，输出当前支持清单与已知词汇。	明确告知支持白屏、接口 405/502、权限异常等场景，并解释相关业务简称。
② 闭集意图分类	"客户报表详情页出现白屏"	模型触发 `report_intent`，准确归类至 `white_screen` 意图。	准确定位目标排查路径，不再横向发散。
③ 槽位补全引导 (Slot Filling)	"报表白屏了" (缺少必要上下文)	插件校验必填参数（租户 ID、环境、报错页面 URL），检测到缺失后进入引导模式。	逐步追问："请提供租户标识（例如 `tenant_demo_01`）"，参数收齐后才进入排查工具调用。
④ 超范围意图拒识 (Graceful Refusal)	"帮我重构并开发一个新的订单列表页"	判定为 `unsupported` 意图，阻断执行，并给出明确且礼貌的边界提示。	"抱歉，开发新功能超出排查范围。我主要负责页面故障排查。建议联系业务研发同学。"

YAML

复制代码

# intents.yml 配置样例（脱敏）
version: "1.0"
intents:
  - id: white_screen
    description: "用户前端页面出现白屏、无法加载内容"
    slots:
      - name: tenant_id
        required: true
        description: "客户租户标识"
      - name: env
        required: true
        options: ["prod", "staging", "test"]
      - name: target_url
        required: false
        description: "问题页面 URL"
  - id: api_error
    description: "接口报错，例如 404, 405, 502 等 HTTP 异常"
    slots:
      - name: status_code
        required: true
      - name: endpoint
        required: true

这种机制让领域 Agent 的开发者无需深究复杂的 Prompt 工程，只需通过配置文件声明"业务有哪些意图"以及"每个意图需要什么参数"，即可获得稳定、可控的入口层防护。

四、质量度量：离线评测框架 (Scorer)

为避免 Agent 上线"全靠感觉，测试全靠手工"，插件内置了一套离线评估器（Scorer），通过批量跑测用例集来量化模型对意图的掌控力：

Top-1 准确率（Classification Accuracy）：衡量模型将正常任务映射到预期意图分类的比例。
拒识准确率（Rejection Accuracy） ：衡量模型将非支持任务判定为 unsupported 的准确率。对生产环境而言，拒识不准意味着 Agent 要么乱执行危险操作，要么把正常的业务需求错误拦截。

槽位完整率（Slot Completeness Rate）：在分类正确的用例中，必要参数被成功抽取或主动追问收齐的比例，决定了后续排查链路是否具备充足上下文。

复制代码

                  ┌─────────────────────────┐
                  │ 评测用例集 (Test Suite) │
                  └────────────┬────────────┘
                               │
               ┌───────────────┴───────────────┐
               ▼                               ▼
     [有效业务场景输入]               [越界 / 恶意模糊输入]
               │                               │
               ▼                               ▼
      Top-1 分类准确率                 拒识准确率 (Rejection)
               │
               ▼
      槽位完整率 (Slot Filling)

在测试集构建上，建议优先建立冷启动阶段的 Baseline 数据集（包含典型意图的正例、不同缺参组合的追问用例，以及覆盖相近领域的边界负例），在持续迭代模型或调整 Prompt 时实现回归自测。

总结与演进

将"意图识别"与"边界校验"剥离为标准化插件，核心目的在于解耦 Agent 的理解层与执行层：

运行时插件负责提供脚手架、注入领域术语、校验槽位状态；
宿主模型专注在既定规则框架内完成语义推断；
业务开发者只需专注于定义业务规则（intents.yml）与底层工具链。

让 Agent 在动手之前先把话听懂、把边界划清，是轻量级 Agent 架构走向企业严肃业务落地至关重要的一步。