# 意图识别层(通用前置)多角度论证

> 来源:intent-analysis 子代理 8 维度论证 + WebSearch 10 业界佐证 + devflow 源码核验。
> 纯架构论证,不改代码。供架构决策。

## 核心结论

1. **方向正确**:意图识别作为通用前置层(每消息),服务四下游(工具预选/模型路由/上下文策略/审批预估)——业界共识(TianPan/NVIDIA/LangChain 佐证),用户洞察准确。
2. **当前不急**:devflow 29 工具处于业界"产品派不做意图层"临界点(Claude Code <20 工具不分类 / OpenAI 原生 tool_choice 非前置),痛点不致命(未到 417 工具崩 20% 线)。
3. **近期建议**:精简工具描述降 token(零架构改动,立即可做)。
4. **中期触发**(工具>40 或多模型用户):上**方式 A 规则**(零延迟零成本纯赚),落 `intent.rs` + tool domain 标签。
5. **远期升级**(工具>80 或 MCP):**方式 D 两阶段**(规则兜底 + Flash 分类),警惕 Tool RAG 生产退化(《340 Tools》反例)。
6. **落地约束**:意图层只在 `agentic/mod.rs` loop 入口生效一次,不进 loop 体;输出"子集扩充+模型建议"非"硬性裁剪";None fallback 全量零回归。
7. **架构兼容**:与双轨/审计/provider 工厂三高杠杆零冲突;`coordinator.rs` 空壳保留 B 路线多 Agent,意图层独立落 `intent.rs`。

## 痛点量化(现状)

- **工具全量下发**:`agentic/mod.rs:423 tool_definitions()` 全 29 工具 schema 每消息塞 request,~6000-8000 token/消息(中位估算)。
- **模型路由静态化**:`router.rs:56-63` TaskRequirements 硬编码 needs_tool_use=true/modalities=[Text],闲聊和写代码走同模型。
- **coordinator.rs 空壳**:B 路线占位(L5-30),意图识别无落脚点。
- **上下文策略纯阈值**:`agentic/mod.rs:513-641` 自动压缩按 token>budget*0.6,不按意图。

## 实现方式对比

| 方式 | 延迟 | token | 准确 | 推荐 |
|---|---|---|---|---|
| A.规则/关键词 | <1ms | 0 | 中(中文意图,覆盖70%+) | ⭐ 近期 |
| B.embedding | 10-50ms | 0+1次embedding | 中 | ✗ ROI低(单用户桌面) |
| C.fast model | 300-800ms | ~200-500 | 高 | 中期补(盈亏工具>40+多模型) |
| D.两阶段(A+C) | 混合 | 混合 | 高 | ⭐ 远期 |

## 收益量化(方式 A 规则,中期)

- 工具子集降 token:29→8-12 子集,**省 4000-5000 token/消息,降幅 60%**。
- 模型路由省成本:60% 闲聊→Flash(¥0.0014/M)/ 40% 工具→Plus(¥5/M),**混合均价降 60%**(多模型用户)。
- 决策准确:工具数 <10 时 LLM 选错概率显著降(反推 417→20% 数据)。
- 审批预估前置:前端预判 High 风险,提前提示。

## 盈亏平衡(方式 C fast model)

| 维度 | 阈值 | devflow 现状 | 值得上 C? |
|---|---|---|---|
| 工具数 | >40 | 29 | 临界,即将 |
| 多模型 | 用户配 Flash+Plus | 多数单 provider | 多数无收益 |
| 延迟容忍 | 接受 +500ms 首字 | 流式敏感 | 负面 |

**结论**:方式 A 规则零成本纯赚(近期可上);方式 C 盈亏在"工具>40 且多模型"之后。

## 风险 + fallback

| 风险 | 缓解 |
|---|---|
| 意图误判(漏工具) | **子集扩充非裁剪**(project+file 兜底,18 工具仍<29) |
| 单点故障 | None fallback 全量工具(零回归) |
| 延迟敏感 | 方式 A 无延迟;C 需并行/异步预热 |
| Flash 超时/非法 | fallback 全量/规则结果 |

**关键设计原则**:意图层是"加权推荐"非"硬性裁剪";None 时全量(现状)零回归。

## 业界佐证(WebSearch 10 来源)

**学术/框架派**(主张前置意图层):
- TianPan《Intent Classification Layer》(417 工具崩 20%,论证需专用前置层)
- NVIDIA AIQ《Intent Classifier》(单次 LLM 多输出:意图+元响应+判定)
- Medium《Intent-to-Action Layer》(prompt→intent→structure→policy→route→tools→execution)
- LangChain《Context Engineering》(RAG 工具描述,只发相关工具)
- Red Hat《Tool RAG》(企业级工具扩展解法)

**产品派**(工具可控时不做前置):
- OpenAI function calling(tool_choice 是"约束"非"前置分类",意图责任留开发者)
- Claude Code 子代理(任务级路由,非消息级;<20 核心工具不做意图层)

**反例(警惕)**:《OpenAI 340 Tools 生产案例》——语义工具选择初期有效但准确率随时间退化,需持续监控。

**定价**:智谱 GLM Plus ¥5/M vs Flash ¥0.0014/M(500倍差,意图路由省钱空间)。

## devflow 整合(改动面)

| 模块 | 现状 | 接入点 | 改动 |
|---|---|---|---|
| coordinator.rs | B 路线空壳 | 保留(多Agent) | 不动 |
| **intent.rs**(新增) | — | 意图识别落点 | ~200 行(规则引擎+Intent 枚举) |
| tool_registry.rs | tool_definitions() 全量 | 加 tool_definitions_subset(intent) + 工具 domain 标签 | ~50 行 + 29 register 加 domain |
| agentic/mod.rs | loop 外 tool_defs | loop 入口插意图识别 | ~30 行(入口加调用) |
| router.rs | 静态 TaskRequirements | 意图→TaskRequirements 构造 | agentic 构造点改,router 不动 |

**总计 ~300-400 行,中等改动**。与双轨/审计/provider 工厂零冲突。

## 分阶段路径(触发条件)

```
近期(29工具,单provider):精简工具描述(零架构),储备设计(本文档)
中期(工具>40 或多模型):方式A规则(intent.rs + domain标签 + subset + 模型路由)
远期(工具>80 或MCP):方式D两阶段(A规则兜底+C Flash分类),警惕Tool RAG退化
```

## Sources

- [TianPan Intent Classification](https://tianpan.co/blog/2026-04-16-intent-classification-agent-routers)
- [NVIDIA AIQ Intent Classifier](https://docs.nvidia.com/aiq-blueprint/2.0.0/architecture/agents/intent-classifier.html)
- [LangChain Context Engineering](https://www.langchain.com/blog/context-engineering-for-agents)
- [Red Hat Tool RAG](https://next.redhat.com/2025/11/26/tool-rag-the-next-breakthrough-in-scalable-ai-agents/)
- [OpenAI 340 Tools 反例](https://pub.towardsai.net/openai-function-calling-works-great-until-you-have-340-tools-12-tenants-real-production-traffic-fe02da116e39)
- [Claude Code Subagents](https://www.builder.io/blog/claude-code-subagents)
- [OpenAI Function Calling](https://developers.openai.com/api/docs/guides/function-calling)
- [智谱定价](https://open.bigmodel.cn/pricing)
