# AI Feature Consulting Agent — 项目架构文档

> 最后更新: 2026-04-14

---

## 1. 项目总览

这是一个 **RAG (Retrieval-Augmented Generation)** 架构的 AI 咨询 Agent，专门回答 Microsoft Teams 功能领域的 PM 咨询问题。核心能力：

- 基于 **219 条真实 PM 咨询 Q&A 记录** 做知识检索
- 调用 **GPT-5.4 (Azure OpenAI)** 生成有引用、可转发的专业回答
- 自动分类、质量自评、置信度评估、升级路由

---

## 2. 目录结构

```
AI Feature Consulting Agent/
├── src/
│   ├── api/
│   │   └── main.py              # FastAPI 入口，定义所有 HTTP 端点
│   ├── agent/
│   │   ├── consulting_agent.py  # 核心 Agent 编排引擎（8 步 pipeline）
│   │   ├── prompts.py           # 所有 LLM prompt 模板（0.1 步长评分）
│   │   └── prompts_half_step.py # 0.5 步长评分 prompt（业界标准）
│   ├── knowledge/
│   │   ├── retriever.py         # 本地知识库加载 + RAG 检索
│   │   ├── parallel_retriever.py # 多源并行检索（KB + Web + Copilot + ADO + Learn）
│   │   ├── web_search.py        # Web 搜索（Microsoft Learn / Graph / Teams）
│   │   ├── copilot_search.py    # Copilot / Graph Search（内部 M365 文档）
│   │   ├── ado_client.py        # Azure DevOps 工作项检索
│   │   ├── learn_client.py      # Microsoft Learn 文档检索
│   │   └── cli_relay.py         # Copilot CLI 中继（Deep mode）
│   ├── models/
│   │   └── schemas.py           # Pydantic 数据模型（请求/响应/知识记录）
│   └── utils/
│       ├── config.py            # 环境变量配置（Pydantic Settings）
│       ├── llm_client.py        # ★ LLM 调用层（Azure OpenAI Entra ID 认证）
│       ├── split_dataset.py     # 数据集分层拆分（train/test）
│       └── evaluate.py          # 测试集评估脚本
├── config/
│   └── agent_config.py          # Feature area 元数据、质量阈值、路由规则
├── data/
│   ├── documents/               # 原始 Markdown Q&A 数据文件（219 条）
│   ├── train.json               # 训练集（189 条）— Agent 检索用
│   ├── test.json                # 测试集（47 条）— 评估用，不参与检索
│   ├── gold_standard.md         # Gold Standard 测试集（20 条）
│   ├── gold_eval_results.json   # LLM Mode 评测结果
│   ├── cli_mode_eval_results.json  # CLI Mode 评测结果
│   └── studio_eval_results.json    # Copilot Studio 评测结果
├── static/
│   └── index.html               # 前端 Web UI（单页应用）
├── .env                         # 环境变量（Azure OpenAI Entra ID）
├── requirements.txt             # Python 依赖
└── README.md
```

---

## 3. 双模式架构（Standard + Deep）

前端通过 Mode 选择器决定走哪条链路：

```
用户浏览器 (localhost:8000)
    │
    ├── [Standard 模式] POST /ask ──────────► LLM Mode Pipeline
    │                                         (GPT-5.4 + RAG)
    │
    └── [Deep 模式]    POST /ask/deep ──────► CLI Mode Pipeline
                                              (Copilot CLI → Claude Opus 4.6)
```

---

### 3.1 Standard 模式 — LLM Mode (POST /ask)

**模型**: GPT-5.4 (Azure OpenAI) | **延迟**: ~120-250s | **知识源**: Local KB + Web + ADO + Learn

```
┌─────────────────────────────────────────────────────────┐
│  ConsultingAgent (src/agent/consulting_agent.py)        │
│                                                         │
│  Step 1: _classify_question()                           │
│     └── LLM → { feature_area, question_type }           │
│                                                         │
│  Step 2: parallel_retriever.retrieve()                  │
│     ├── ① Local KB (train.json, 189 条) → Top-5        │
│     ├── ② Web Search (Microsoft Learn) → Top-2         │
│     ├── ③ ADO Client (工作项) → Top-2                  │
│     └── ④ Learn Client (文档 API) → Top-2              │
│                                                         │
│  Step 3: get_high_rated_examples() → 2 条 few-shot     │
│                                                         │
│  Step 4: _generate_answer() → draft_answer + citations  │
│                                                         │
│  Step 5: _self_evaluate() → 质量门控（最多重试 2 次）    │
│                                                         │
│  Step 6: _assess_confidence() → HIGH/MEDIUM/LOW         │
│                                                         │
│  Step 7: _build_escalation() (仅 LOW 时)                │
│  Step 8: Build CandidateFAQ                             │
│                                                         │
│  → AgentResponse (JSON)                                 │
└────────────────────┬────────────────────────────────────┘
                     │  GPT-5.4 × 4 次调用
                     ▼
         ┌─────────────────────────┐
         │  Azure OpenAI           │
         │  Entra ID 认证          │
         │  Model: gpt-5-4        │
         └─────────────────────────┘
```

---

### 3.2 Deep 模式 — CLI Mode (POST /ask/deep)

**模型**: Claude Opus 4.6 (Copilot CLI) | **延迟**: ~50-250s | **知识源**: Local KB + MCP 工具

```
┌─────────────────────────────────────────────────────────┐
│  CLIRelay (src/knowledge/cli_relay.py)                  │
│                                                         │
│  1. _retrieve_kb_context(question)                      │
│     └── Local KB 检索 Top-5 → 注入 prompt               │
│                                                         │
│  2. _build_prompt_sync()                                │
│     └── 指令 + KB 上下文 + MCP 搜索指令 + 问题          │
│                                                         │
│  3. subprocess("copilot -p <prompt>")                   │
│     └── Claude Opus 4.6 + MCP 工具:                     │
│         ├── SharePoint 文档搜索                          │
│         ├── Teams 聊天记录搜索                           │
│         ├── Outlook 邮件搜索                             │
│         ├── OneDrive 文件搜索                            │
│         └── Web 搜索                                     │
│                                                         │
│  4. 解析输出 → draft_answer                             │
│     └── CLI 不可用时 → fallback 到 Standard 模式        │
└─────────────────────────────────────────────────────────┘
```

---

### 3.3 两种模式对比

| 维度 | Standard (LLM Mode) | Deep (CLI Mode) |
|------|:-:|:-:|
| **底层 LLM** | GPT-5.4 | Claude Opus 4.6 |
| **知识源** | Local KB + Web + ADO + Learn | Local KB + MCP 工具全集 |
| **能否搜索内部文档** | ❌ | ✅ SharePoint/Teams/Outlook |
| **延迟** | ~120-250s | ~50-250s |
| **Pipeline** | 8 步闭环（含自评+置信度） | 单次 CLI 调用 |
| **评测加权分** | 3.51 | **4.52** |
| **适用场景** | 日常快速回复 | 需要内部文档的复杂问题 |


## 4. LLM 是怎么调的？

### 4.1 统一走 OpenAI SDK

不管后端是 Azure OpenAI 还是 GitHub Models，都用 **`openai` Python SDK**，只是初始化参数不同：

```python
# Azure OpenAI (Entra ID 认证，当前使用)
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default"
)
client = AsyncAzureOpenAI(
    azure_endpoint="https://xxx.openai.azure.com/",
    azure_ad_token_provider=token_provider,
    api_version="2024-10-21",
)

# GitHub Models（备用方案）
client = AsyncOpenAI(
    base_url="https://models.inference.ai.azure.com",
    api_key=github_token,
)
```

### 4.2 每次提问触发 4 次 LLM 调用

| 调用 | System Prompt | 目的 | 返回格式 |
|------|--------------|------|---------|
| ① 分类 | `CLASSIFIER_SYSTEM_PROMPT` | 识别 feature_area + question_type | JSON |
| ② 生成 | `ANSWER_SYSTEM_PROMPT` | 基于 RAG 上下文生成回答 | Markdown |
| ③ 自评 | `SELF_EVAL_SYSTEM_PROMPT` | 7 条质量标准门控 | JSON |
| ④ 置信 | `CONFIDENCE_SYSTEM_PROMPT` | 4 维评分 + HIGH/MEDIUM/LOW | JSON |

### 4.3 Token 自动获取

```
优先级: .env AZURE_OPENAI_API_KEY → .env GITHUB_TOKEN → `gh auth token` 命令
```

当前项目使用 **Azure OpenAI (GPT-5.4)**，通过 Entra ID 认证（无需 API Key）。配置 GitHub Models 后可自动切换为备用方案。

---

## 5. RAG 检索是怎么做的？

**3 层知识架构**，不用向量数据库：

```
输入: 用户问题 "How to enable transcription?"
  │
  ├── Layer ① 本地 KB (train.json, 189 条)
  │     ├── 按 feature_area 过滤
  │     ├── 按 rating ≥ 3.0 过滤
  │     ├── 关键词重叠打分 + rating 加权
  │     └── 取 Top-5
  │
  ├── Layer ② Web 搜索 (Microsoft Learn / Graph / Teams 站点)
  │     ├── 关键词匹配 → 抓取对应文档页面
  │     └── 提取相关片段, 取 Top-2
  │
  └── Layer ③ Copilot / Graph Search (内部 M365 文档, 需配置)
        └── 当前未启用 (需设备合规 + Graph API 权限)
```

### 数据加载优先级

```
启动时:
  data/train.json 存在？ → 加载 189 条训练数据（推荐）
  否则 → 解析 data/documents/sox_*.md 全部 219 条
```

---

## 6. 前后端怎么打通的？

```
┌──────────────┐     HTTP      ┌──────────────────────────┐
│  浏览器       │ ◄──────────► │  FastAPI (port 8000)      │
│  index.html   │              │                          │
│  (static/)    │              │  GET  /          → UI    │
│               │              │  GET  /health    → 状态  │
│  fetch()  ────┼── POST ────► │  POST /ask       → Standard 模式  │
│               │   /ask       │  POST /ask/deep  → Deep 模式     │
│               │              │    (Copilot CLI 中继)             │
│               │              │  GET  /stats     → 统计  │
│               │              │  GET  /feature-areas     │
└──────────────┘              └──────────────────────────┘
```

- **前端**: 纯 HTML + CSS + Vanilla JS，无构建步骤
- **后端**: FastAPI 通过 `FileResponse` 直接 serve `static/index.html`
- **CORS**: 全开 (`allow_origins=["*"]`)
- **通信**: 标准 JSON REST API，前端用 `fetch()` 调用

---

## 7. 关于 MCP（Model Context Protocol）

当前项目 **没有直接使用 MCP**。以下是集成路径说明：

### 7.1 当前架构 vs MCP

| 项目 | 当前实现 | MCP 实现 |
|------|---------|---------|
| LLM 调用 | `openai` SDK 直连 | 通过 MCP Server 代理 |
| 知识检索 | 本地 Python 关键词检索 | 可封装为 MCP Tool |
| Agent 编排 | 自己写的 8 步 pipeline | 可用 MCP 的 Tool/Resource 协议 |

### 7.2 如果要接 MCP

**方案 A: 把 Agent 暴露为 MCP Server**

```
Copilot / MCP Client
    │
    │  MCP Protocol (stdio/SSE)
    ▼
MCP Server (包装 ConsultingAgent)
    ├── Tool: ask_question(question, feature_area?)
    ├── Tool: search_knowledge(query, area?)
    ├── Resource: feature-areas
    └── Resource: knowledge-stats
```

**方案 B: 让 Agent 调用外部 MCP Tools**

```
ConsultingAgent
    │
    ├── LLMClient (现有) → GPT-5.4
    ├── KnowledgeRetriever (现有) → 本地数据
    └── MCP Client (新增) → 调用外部 MCP Server
        ├── SharePoint MCP → 检索实时文档
        ├── IcM MCP → 查询工单
        └── Teams MCP → 搜索历史聊天
```

### 7.3 GitHub Models 本身就是 MCP 兼容的

当前项目通过 Azure OpenAI 调用 GPT-5.4。如果需要切换到 MCP 托管的模型，只需修改 `LLMClient` 的配置。

---

## 8. 配置参考 (.env)

```bash
# === LLM 后端 (Azure OpenAI, Entra ID 认证) ===
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_KEY=              # 留空，使用 Entra ID 认证
AZURE_OPENAI_DEPLOYMENT=gpt-5-4
AZURE_OPENAI_API_VERSION=2024-10-21
AZURE_OPENAI_TENANT_ID=your-tenant-id

# === Agent 参数 ===
CONFIDENCE_THRESHOLD=0.75
MAX_CITATIONS=5
ESCALATION_ENABLED=true
LOG_LEVEL=INFO
```

---

## 9. 关键技术栈

| 层 | 技术 | 用途 |
|---|---|---|
| 前端 | HTML + CSS + Vanilla JS | 聊天 UI |
| API | FastAPI + Uvicorn | HTTP 服务 |
| LLM | openai SDK (async) | 调用 GPT-5.4 |
| LLM 后端 | Azure OpenAI (Entra ID) | 模型推理 |
| 数据模型 | Pydantic v2 | 请求/响应验证 |
| 知识检索 | 多源并行 RAG (本地 KB + Web + ADO + Learn + Copilot CLI) | 检索 |
| 配置 | pydantic-settings + .env | 环境变量 |
| 评估 | 自研 evaluate.py | 分类准确率 / 检索召回率 / 质量分 |

---

## 10. 启动命令

```bash
cd "C:\coding\AI Feature Consulting Agent"
.venv\Scripts\activate
python -m src.api.main
# → http://localhost:8000  (Web UI)
# → http://localhost:8000/docs  (Swagger API 文档)
```

---

## 11. 评估结果 (Gold Standard, 20 条)

三模型对比评测（Judge: Claude Opus 4.6, Step=0.5）：

| 维度 | Copilot Studio | LLM Mode | CLI Mode | 最优 |
|------|:-:|:-:|:-:|:-:|
| Accuracy (40%) | 4.10 | 3.62 | **4.55** | CLI |
| Fitness (25%) | 4.35 | 3.52 | **4.60** | CLI |
| Actionability (20%) | 4.38 | 3.62 | **4.62** | CLI |
| Traceability (15%) | 4.03 | 3.05 | **4.17** | CLI |
| **Weighted** | 4.21 | 3.51 | **4.52** | CLI |

详细评测报告见 `data/model_comparison_report_half.md`。