etf-intent-gate

ETF Intent Gate（ETF投研平台前置意图识别网关）

为"用户请求 → 多Agent并行投研分析"架构提供网关级前置安全与意图校验：只有校验通过才下发下游Agent，不通过直接返回标准化应答，避免下游Agent被脏输入污染、跑错方向或浪费算力。

何时使用

• 用户正在搭建 ETF/行业/指数投研平台，聊天请求需要分发到多个业务Agent（宏观/事件/政策/估值/资金）并行处理
• 需要在分发前拦截：非法字符、prompt注入、违规索要投资建议的query
• 需要把口语化决策问句（"芯片可以买吗"）改写为客观投研指令（约束下游Agent不输出买卖建议）
• 需要按意图裁剪Agent调度（用户只问政策 → 只跑政策agent，省算力）

核心设计（6阶段流水线）

1. 规则预处理（不调LLM，高性能）：清洗零宽/控制字符、script/SQL/markdown/prompt注入payload；长度校验（<2 或 >2000字符拦截）；两级黑名单（block级：稳赚/必涨/内幕；warning级：梭哈/全仓仅打标）
2. LLM意图识别：固定JSON Schema输出7种intent_type（etf_industry_research / platform_qa / chat_greeting / malicious_injection / illegal_content / investment_advice_request / unknown_intent），本地强校验不允许自由文本
3. 业务边界校验：7种意图分支路由——放行（warning强制加免责声明）、平台问答、闲聊引导、注入/违规阻断、投资建议拒绝（区分口语化"可以买吗"=改写放行 vs 索要保本点位=拦截）
4. 防注入二次校验：对改写后的query检测5类注入特征，命中直接覆盖为拦截
5. 路由与埋点：转发场景输出调度器任务上下文（standard_query + agent_allow_list + risk_warning）；单行JSON结构化埋点日志
6. 异常降级：LLM超时/解析失败 → conservative（默认拦截，推荐金融平台）/ loose（放行打intent_parse_failed标）双模式可配

安全核心约束：下游Agent永远只使用改写后的 standard_query，禁止透传用户原始query。

安装与运行

# 1. 安装依赖（Python 3.11+）
pip install -r requirements.txt

# 2. 配置LLM（任意OpenAI兼容服务：GLM/DeepSeek/通义等）
cp .env.example .env
# 编辑 .env 填入：
#   INTENT_LLM_API_KEY=你的key
#   INTENT_LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4  （示例：智谱）
#   INTENT_LLM_MODEL=glm-4-flash
# 不配置时自动进入mock模式（本地规则模拟意图），可先跑通链路

# 3. 启动网关服务
uvicorn app.api:app --host 127.0.0.1 --port 8300

调用接口

POST /api/v1/intent/check
Content-Type: application/json

{"query": "芯片行业可以买吗？"}

返回示例（放行场景）：

{
  "request_id": "ffc571a3...",
  "action": "forward",
  "risk_level": "warning",
  "intent_type": "etf_industry_research",
  "result": {
    "standard_query": "对芯片行业做ETF相关投研分析，涵盖宏观、行业事件、产业政策、估值、资金面维度，仅输出客观事实与数据，不给出买入卖出投资决策建议",
    "risk_warning": true,
    "agent_allow_list": ["宏观agent", "事件agent", "政策agent", "估值agent", "资金agent"]
  }
}

拦截场景返回 action: "intercept"，并附 reply_to_user 直接返回给聊天框；action: "platform_qa" 表示路由到平台问答模块而非投研Agent。

一键自测

# 先启动服务（终端1），然后：
python examples/manual_test.py   # 10个典型case自动比对
python -m pytest tests/ -v       # 23个pytest，无需启动服务

集成约定（下游调度器必须遵守）

• 调度器只把 result.standard_query 和 result.entity_extract 传给业务Agent
• original_user_query 仅日志留存，不流入业务Agent
• risk_warning: true 时汇总结果页强制追加投资风险免责声明
• 下游Agent侧仍需二次校验，禁止输出买卖建议（多层防御）

文件结构

etf-intent-gate/
├── SKILL.md            # 本文件
├── requirements.txt    # Python依赖（fastapi/uvicorn/httpx/pydantic等）
├── .env.example        # LLM配置模板
├── app/                # 核心实现（6阶段流水线）
│   ├── preprocess.py   # 阶段1：规则引擎
│   ├── prompts.py      # 阶段2：意图识别System Prompt
│   ├── llm_client.py   # 阶段2：OpenAI兼容调用+mock模式
│   ├── pipeline.py     # 阶段3-6：边界校验/防注入/路由/降级
│   └── api.py          # FastAPI网关入口+埋点
├── tests/              # 23个pytest用例
├── examples/           # 10case一键自测脚本
└── references/         # 设计文档

详细文档

• 设计思路与踩坑要点见 references/design.md