内容
# government-agent-platform
# 政务多智能体协同与治理平台
> Enterprise Multi-Agent Platform based on LangGraph + MCP + A2A + AgentOps + RAG
> 注意：前端界面全部由AI生成，请勿直接复制。
> **最近更新（2026-09-02）**：前端视觉重构（政务企业级设计系统 Trust & Authority——Light Navy 配色 + Plus Jakarta Sans + Lucide 风格 SVG 图标，替代全部 emoji）+ 完整 Docker 全栈验证（11 服务 healthy）。详见 [更新日志](#20-更新日志)。
---
<p align="center">
<img src="./docs/images/logo.svg" width="160" alt="GAP Logo">
</p>
## 项目简介
`government-agent-platform` 是一个面向政务业务场景设计的企业级多智能体协同平台。
平台围绕“高效办成一件事”场景，通过：
* **LangGraph** 构建可控 Agent 工作流
* **MCP(Model Context Protocol)** 标准化 Agent 工具调用
* **A2A(Agent-to-Agent)** 实现跨域 Agent 协作
* **RAG** 提供政策知识增强能力
* **AgentOps** 实现 Agent 全生命周期治理
构建了一套：
> 可编排、可观测、可评测、可治理的企业级 Agent Runtime 平台。
---
# 1. 背景与问题
传统政务智能化系统通常存在：
## 1.1 单Agent能力不足
单个LLM Agent同时承担：
* 意图理解
* 政策查询
* 材料审核
* 流程执行
容易导致：
* 推理混乱
* 幻觉增加
* 难以维护
---
## 1.2 系统接口割裂
真实业务中存在：
```
市场监管系统
消防系统
不动产系统
公积金系统
统一办件系统
```
不同系统：
* 接口不同
* 数据隔离
* 权限复杂
---
## 1.3 Agent缺少治理
生产环境需要解决：
* Agent调用链追踪
* 工具调用审计
* Prompt管理
* 自动评测
* 安全控制
因此设计：
```
Multi-Agent
+
Agent Governance
+
Evaluation Platform
```
---
# 2. 核心能力
## Multi-Agent协同
平台包含多个领域Agent：
| Agent | 职责 |
| ---------------- | ---------------------------------------- |
| Supervisor Agent | 全局任务规划 |
| Intent Agent | 用户意图识别（BERT 微调模型 + 关键词兜底 + LLM fallback） |
| Policy Agent | 政策知识检索 |
| Material Agent | 材料审核 |
| Workflow Agent | 流程执行 |
| Governance Agent | 安全治理 |
---
# 3. 系统架构
```
User
|
v
API Gateway
FastAPI
|
v
+---------------------+
| Supervisor Agent |
| LangGraph Runtime |
+---------------------+
|
+-----------------+----------------+
| | |
v v |
Intent Agent Policy Agent Material Agent
| | |
+-----------------+----------------+
|
v
Workflow Agent
|
v
+----------------+
| MCP Gateway |
+----------------+
| | |
v v v
Policy Material Workflow
MCP MCP MCP
Server Server Server
|
v
Business System
```
---
# 4. 技术架构
## 六层架构
```
L6 AgentOps治理层
Trace
Evaluation
Guardrail
Prompt Management
L5 A2A跨域协同层
Agent Communication
Async Task
Callback
L4 MCP工具能力层
Tool Discovery
Tool Calling
L3 专业Agent层
Policy
Material
Workflow
L2 Agent编排层
LangGraph
L1 接入层
FastAPI
```
---
# 5. LangGraph Agent编排
系统采用：
```
StateGraph
+
Node
+
Edge
+
Checkpoint
```
执行流程：
```
START
|
Supervisor
|
Intent Recognition
|
Task Planning
|
+----------------+
| |
Policy Material
Agent Agent
| |
+----------------+
|
Workflow Agent
|
Governance
|
END
```
---
# 6. MCP工具标准化
## 为什么引入MCP？
传统方式：
```python
agent
↓
import function
↓
API
```
问题：
* 强耦合
* 难扩展
* 难治理
---
采用：
```
Agent
↓
MCP Client (Bearer Token)
↓
MCP Gateway (JWT 认证 + RBAC)
↓
MCP Server
↓
Business Service
```
> **安全加固（2026-08-05）**：MCP Gateway 增加 JWT Bearer Token 验证 + RBAC 角色控制（`admin`/`agent` 角色方可调用工具），Client 自动携带认证 Header。
---
## MCP Server
### Policy MCP Server
提供：
```
search_policy
get_policy_detail
```
能力：
* Milvus检索
* BM25召回
* Reranker排序
---
### Material MCP Server
提供：
```
extract_entity
check_material
```
能力：
* OCR
* 信息抽取
* 材料校验
---
### Workflow MCP Server
提供：
```
create_case
query_status
```
能力：
* 办件创建
* 状态查询
---
# 7. A2A跨Agent协同
针对跨部门业务：
例如：
```
营业执照办理
↓
市场监管Agent
↓
消防Agent
↓
不动产Agent
```
采用：
```
A2A Connector
+
Async Task
+
Callback (HMAC 签名验证)
```
> **安全加固（2026-08-05）**：A2A 回调端点增加 HMAC-SHA256 签名验证 + ±300s 时间窗口防重放，防止伪造回调注入。外部 Agent 需使用共享密钥签名请求。
>
> **真实系统对接（2026-08-08）**：HTTP 回调链路端到端跑通 —— Connector 支持同步 completed / 异步 submitted 分流；Mock Server 异步模式（有 `callback_url` 时立即返回 submitted，后台执行 + HMAC 签名回调）；任务状态持久化到 `a2a_task` 表（`PostgresTaskStore` 写穿）；恢复路径改为 `task_id → source_trace_id(thread) → 最新 checkpoint`。Docker 内 `a2a-mock` 服务承载 housing/fund，外部真实系统把 `A2A_HOUSING_URL` / `A2A_FUND_URL` 换成真实端点即可接入。
任务生命周期：
```
Created
↓
Running
↓
Waiting
↓
Completed
```
---
# 8. AgentOps治理平台
## 全链路Trace
记录：
```json
{
"trace_id":"",
"agent":"",
"tool":"",
"latency":"",
"token_usage":""
}
```
---
## Guardrail安全
> **安全加固（2026-08-05）**：护栏前置到 LLM 前执行，注入/严重敏感词在到达 LLM 之前即被阻断。CORS 默认白名单模式（`localhost:12345,localhost:12421`），可通过 `.env` 配置。
支持：
### 输入检测
* 敏感词
* Prompt Injection
* PII
### 输出检测
* 信息泄露
* 内部错误
* 敏感字段
---
## PII脱敏
示例：
手机号：
```
138****1234
```
身份证：
```
110***********1234
```
邮箱：
```
u***@domain.com
```
---
# 9. 自动评测体系
> **最新更新（2026-08-04）**: trace_provider 已接入，支持真实 Agent 工作流执行并收集 trace 数据。
> Intent 数据集（3500 条）评测通过率 **99.5%**，BERT 模型 `source="bert"` 确认有效。
## 快速运行
```bash
# Intent 快速评测（BERT 本地推理，3500 条约 90 秒）
python -m governance.evaluation.runner run \
--version v0.2 \
--datasets intent_cases \
--run-real --output console
# 全流程评测（LangGraph + LLM API，需 --run-full-workflow）
python -m governance.evaluation.runner run \
--version v0.2 \
--datasets rag_cases,agent_cases \
--run-real --run-full-workflow
# LLM Judge 语义打分 + 数据库持久化
python -m governance.evaluation.runner run \
--version v0.2 \
--datasets rag_cases \
--run-real --run-full-workflow --use-llm --save-to-db
# 列出所有可用数据集
python -m governance.evaluation.runner list
# 对比两个版本
python -m governance.evaluation.runner compare --versions v0.1,v0.2
```
## RAG评测
指标：
| 指标 | 说明 | 评分方式 |
| ---------------- | ----- | ----------------------------- |
| Faithfulness | 回答真实性 | 规则（bigram Jaccard）/ LLM Judge |
| Answer Relevance | 答案相关性 | 规则（token overlap）/ LLM Judge |
| Context Recall | 上下文召回 | 规则（bigram overlap）/ LLM Judge |
---
## Agent评测
指标：
| 指标 | 说明 |
| ----------------- | ------- |
| Task Success Rate | 任务成功率 |
| Tool Accuracy | 工具选择准确率 |
| Latency | 响应耗时 |
| Step Count | 执行步骤 |
**综合评分权重**：task_success_rate 0.25 + tool_accuracy 0.15 + faithfulness 0.15 + answer_relevance 0.15 + context_recall 0.10 + intent_accuracy 0.10 + efficiency 0.10
---
# 10. Prompt管理
支持：
```
Prompt Registry
|
Version Control
|
Runtime Loading
```
避免：
```python
prompt="固定字符串"
```
---
# 11. 项目代码结构
```
gov_AP/
│
├── README.md # 项目说明（本文件）
├── CLAUDE.md # AI编码规范（Cursor/Claude Code/Copilot）
├── STRUCTURE.md # 详细文件清单和开发指引
├── .env.example # 环境变量模板
├── .gitignore # Git忽略规则
├── example.py # 文件头模板
├── docker-compose.yml # Docker编排（根目录，docker compose up 直接可用）
├── .dockerignore # Docker构建上下文排除
├── .streamlit/config.toml # Streamlit 主题/端口配置（浅色政务蓝主题）
│
├── agents/ # Agent层 — 6个专业Agent
│ ├── __init__.py # Agent注册中心
│ ├── supervisor/ # 全局任务规划
│ │ ├── agent.py # Supervisor核心
│ │ ├── planner.py # 任务拆解
│ │ ├── router.py # Agent路由
│ │ └── prompts.py # Prompt模板
│ ├── intent/ # 意图识别
│ │ ├── agent.py # Intent核心
│ │ ├── classifier.py # BERT分类器（微调模型自动加载，source="bert"）
│ │ ├── schema.py # 数据模型
│ │ └── prompts.py # Prompt模板
│ ├── policy/ # 政策检索
│ │ ├── agent.py # Policy核心
│ │ ├── schema.py # 数据模型
│ │ └── prompts.py # Prompt模板
│ ├── material/ # 材料审核
│ │ ├── agent.py # Material核心
│ │ ├── ocr.py # OCR识别
│ │ ├── extractor.py # 实体抽取
│ │ ├── validator.py # 规则校验
│ │ └── prompts.py # Prompt模板
│ ├── workflow/ # 流程执行
│ │ ├── agent.py # Workflow核心
│ │ └── prompts.py # Prompt模板
│ └── governance/ # 安全治理(旁路)
│ ├── agent.py # Governance核心
│ ├── security.py # 安全检测
│ ├── behavior.py # 行为分析
│ ├── optimizer.py # 自动优化
│ └── prompts.py # Prompt模板
│
├── orchestration/ # 编排层 — LangGraph工作流
│ └── langgraph/
│ ├── __init__.py # 包初始化
│ ├── state.py # AgentState共享状态
│ ├── graph.py # StateGraph构建
│ ├── nodes.py # 节点函数
│ ├── edges.py # 条件路由
│ ├── checkpointer.py # 状态持久化
│ └── runtime.py # 运行时安全控制
│
├── tools/ # 工具层 — MCP + A2A
│ ├── mcp/ # MCP协议(Agent→Tool)
│ │ ├── __init__.py # 包初始化 + 导出
│ │ ├── client.py # MCP客户端（Gateway/Direct双模）
│ │ ├── gateway.py # MCP网关（路由/审计/健康聚合）
│ │ ├── schema.py # 6 Tool Pydantic模型 + TOOL_REGISTRY
│ │ ├── start_servers.py # 一键启动所有MCP基础设施
│ │ └── servers/ # MCP Server
│ │ ├── policy_server/ # 政策查询服务 :12011
│ │ │ ├── server.py # FastAPI Server入口
│ │ │ └── tools.py # search_policy/get_policy_detail
│ │ ├── material_server/ # 材料审核服务 :12021
│ │ │ ├── server.py # FastAPI Server入口
│ │ │ └── tools.py # extract_entity/check_material
│ │ └── workflow_server/ # 流程执行服务 :12031
│ │ ├── server.py # FastAPI Server入口
│ │ └── tools.py # create_case/query_status
│ └── a2a/ # A2A协议(Agent→Agent)
│ ├── __init__.py # 包初始化
│ ├── connector.py # A2A连接器
│ ├── protocol.py # 通信协议
│ ├── task.py # 任务生命周期（状态机）
│ ├── task_store.py # 任务持久化（PostgreSQL 写穿 PostgresTaskStore）
│ ├── registry.py # Agent注册中心
│ ├── callback.py # 回调处理（HMAC 校验 + 恢复）
│ └── mock_agents/ # 模拟外部Agent
│ ├── server.py # HTTP Mock Server（12101/12111，支持异步回调）
│ ├── housing_agent.py # 不动产Agent
│ └── fund_agent.py # 公积金Agent
│
├── rag/ # 知识层 — RAG检索增强
│ ├── __init__.py # 包初始化
│ ├── embedding.py # BGE向量化
│ ├── retriever.py # 混合检索(Milvus+BM25)
│ ├── reranker.py # BGE重排序
│ ├── generator.py # LLM答案生成
│ └── knowledge_base.py # 知识库管理
│
├── governance/ # 治理层 — AgentOps
│ ├── __init__.py # 包初始化
│ ├── trace.py # 全链路追踪
│ ├── guardrail.py # 安全护栏(输入/输出)
│ ├── pii.py # PII脱敏
│ ├── monitor.py # Agent监控
│ ├── dashboard.py # 运维看板
│ └── evaluation/ # 自动评测
│ ├── __init__.py # 包初始化
│ ├── evaluator.py # 评测引擎（evaluate_from_cases/traces/db）
│ ├── metrics.py # 指标计算（RAG + Agent + Intent 复合评分）
│ ├── benchmark.py # 基准测试（GoldenDataset + BenchmarkRunner）
│ ├── runner.py # 评测流水线（CLI: run/compare/list + DB持久化）
│ ├── trace_provider.py # 真实trace提供者（BERT意图 / LangGraph全流程）
│ └── llm_adapter.py # LLM Judge适配器（BaseChatModel → score回调）
│
├── database/ # 数据层 — PostgreSQL
│ ├── __init__.py # 包初始化
│ ├── connection.py # 数据库连接
│ ├── models.py # ORM模型
│ ├── schemas.py # Pydantic序列化
│ └── migrations/ # Alembic迁移
│
├── backend/ # 接入层 — FastAPI
│ ├── __init__.py # 包初始化
│ ├── main.py # 应用入口
│ ├── config.py # 配置管理
│ ├── api/ # API路由
│ │ ├── __init__.py # 包初始化
│ │ ├── routes.py # 端点定义
│ │ ├── dependencies.py # 依赖注入
│ │ └── schemas.py # 请求/响应模型
│ ├── middleware/ # 中间件
│ │ ├── __init__.py # 包初始化
│ │ ├── auth.py # JWT认证
│ │ ├── rbac.py # 角色权限
│ │ ├── logging.py # 日志记录
│ │ └── tracing.py # 链路追踪
│ └── services/ # 业务服务
│ ├── __init__.py # 包初始化
│ └── agent_service.py # Agent编排服务
│
├── frontend/ # 前端层 — Streamlit 能力演示
│ ├── app.py # 导航入口（st.navigation + 8 st.Page）
│ ├── common.py # 公共工具（路径设置 + 异步执行）
│ ├── api_client.py # 后端 API 客户端（httpx，含 chat_with_fallback 降级）
│ ├── ui.py # 共享 UI 组件库（主题CSS/页头/指标卡/状态徽章/证据卡等）
│ ├── stub_chat.py # 本地 stub 对话（BERT 意图分类 + 政策模板 + PII 脱敏）
│ └── pages/ # 8 个功能页面
│ ├── home_page.py # 首页总览
│ ├── chat_page.py # 智能对话（API 优先 → stub 降级）
│ ├── intent_page.py # 意图识别演示
│ ├── policy_page.py # 政策检索演示
│ ├── material_page.py # 材料审核演示
│ ├── a2a_page.py # 跨域协同演示
│ ├── governance_page.py # 安全治理演示
│ └── dashboard_page.py # 运维看板
│
├── prompts/ # Prompt管理
│ ├── __init__.py # 包初始化
│ └── registry.py # Prompt注册中心(版本化)
│
├── cases/ # 评测用例
│ ├── __init__.py # 包初始化
│ ├── intent_cases.json # 意图分类用例
│ ├── rag_cases.json # RAG评测用例
│ ├── agent_cases.json # Agent评测用例
│ ├── security_cases.json # 安全评测用例
│ ├── business_license.json # 营业执照场景
│ ├── policy_query.json # 政策查询场景
│ └── workflow.json # 流程执行场景
│
├── deploy/ # 部署配置
│ ├── Dockerfile # API + MCP Server Docker 镜像
│ ├── docker-entrypoint.sh # API 容器入口（root 授权 bind mount → setpriv 降权 appuser）
│ ├── Dockerfile.mcp # MCP Gateway + 3 Servers 镜像（12001-12031）
│ ├── Dockerfile.agent # A2A Mock 外部 Agent 镜像（housing 12101 / fund 12111）
│ ├── Dockerfile.frontend # Streamlit 前端 Docker 镜像（轻量，仅 streamlit + httpx）
│ └── k8s/ # Kubernetes
│ ├── backend.yaml # 后端Deployment
│ ├── agent.yaml # Agent Runtime
│ ├── model.yaml # 模型服务(GPU)
│ ├── mcp.yaml # MCP Server
│ ├── postgres.yaml # 数据库
│ └── ingress.yaml # 入口配置
│
├── models/ # 模型文件（已 gitignore）
│ ├── README.md # 模型清单 + 下载说明
│ ├── embedding/ # BGE Embedding 模型
│ ├── reranker/ # BGE Reranker 模型
│ ├── intent/ # 意图分类 BERT 模型
│ └── fine_tuned/ # 微调产出版本
│
├── requirements/ # 依赖管理
│ ├── requirements.txt # 核心依赖
│ ├── requirements-dev.txt # 开发工具
│ ├── requirements-gpu.txt # GPU推理
│ └── requirements-ocr.txt # OCR能力
│
├── design-system/ # UI 设计规范
│ └── default/MASTER.md # 配色/字体/间距/组件规格/反模式
│
└── docs/ # 设计文档
├── ARCHITECTURE.md # 系统架构
├── AGENT_DESIGN.md # Agent设计
├── MCP_DESIGN.md # MCP协议设计
├── A2A_DESIGN.md # A2A通信设计
├── EVALUATION.md # 评测体系设计
├── DEPLOYMENT.md # 部署方案
└── PROJECT_ROADMAP.md # 演进路线
```
---
# 12. 技术栈
## Backend
* Python 3.12
* FastAPI
* Pydantic v2
## Agent
* LangChain 1.x
* LangGraph 1.x
## Protocol
* MCP 1.x
* A2A
## Knowledge
* Milvus
* BGE Embedding
* BGE Reranker
## Database
* PostgreSQL
* Redis
## Observability
* OpenTelemetry
* LangSmith
## Deployment
* Docker
* Docker Compose
---
# 13. 快速启动
## 环境
```bash
python >=3.12
```
## 端口约定
端口按组规划，组内 +10 步进、中间留 9 空位：
| 组 | 服务 | 端口 |
| --- | --- | --- |
| **MCP** | Gateway / Policy / Material / Workflow | **12001 / 12011 / 12021 / 12031** |
| **A2A** | housing / fund（Docker `a2a-mock`） | **12101 / 12111** |
| **数据库** | Redis / Milvus / Postgres | **12201 / 12211 / 12221** |
| **前端** | Streamlit | **12345**（固定） |
| **其他** | FastAPI API / Prometheus / Grafana / Alertmanager | **12401 / 12411 / 12421 / 12431** |
| A2A Callback | `/api/a2a/callback`（HMAC 校验，Docker 内 `http://api:12401`） | **api:12401** |
| OpenTelemetry | OTLP | **4319**（4317 + 2） |
---
## 安装
```bash
pip install -r requirements/requirements.txt
```
---
## 配置
```bash
cp .env.example .env
# 按需编辑 .env 中的 API Key 等配置
```
## 模型下载（可选）
系统在无模型时使用 stub 模式运行。需要真实推理时：
```bash
# 见 models/README.md 的详细说明
huggingface-cli download BAAI/bge-large-zh-v1.5 --local-dir models/embedding/bge-large-zh-v1.5
huggingface-cli download BAAI/bge-reranker-v2-m3 --local-dir models/reranker/bge-reranker-v2-m3
```
---
## 启动
### 推荐方式：Docker 后端 + 本地前端
这是功能最完整、最推荐的运行方式：
> **注意**：Docker 容器内 `localhost` 指向容器自身。如需容器内 API 访问宿主机 LLM 服务，请设置 `LLM_API_URL=http://host.docker.internal:8000/v1`（Docker Desktop）或宿主机实际 IP。
**第一步：启动 Docker 后端服务**
```bash
# 启动后端基础设施（API + MCP + PostgreSQL + Redis + Milvus）
docker compose up -d api
```
**第二步：启动本地前端**
```bash
# 本地运行完整 8 页前端（需 Python 依赖）
pip install -r requirements/requirements.txt
streamlit run frontend/app.py
```
访问 http://localhost:12345 即可使用全部 8 个功能页。
> **架构说明**：Docker 负责后端引擎（Agent 工作流 + RAG 检索 + 数据库），本地 Streamlit 负责前端展示。前后端分离，各司其职。
---
### 备选方式
**纯 Docker 部署（轻量前端，3 页可用）：**
```bash
# 构建并启动全部服务
docker compose up -d
# 仅重建前端（代码更新后）
docker compose build --no-cache frontend
docker compose up -d frontend
```
访问 http://localhost:12345，首页/智能对话/运维看板 3 页可用，其余 5 页显示本地运行指引。
**纯本地开发（无 Docker）：**
```bash
# 1. 启动 MCP 基础设施（可选，不启动则自动降级到 stub 模式）
python tools/mcp/start_servers.py --no-gateway
# 2. 启动主 API 服务
uvicorn backend.main:app --host 0.0.0.0 --port 12401 --reload
# 3. 启动前端
streamlit run frontend/app.py
```
---
### 前端页面可用性
| 页面 | Docker 前端 | 本地前端 | 说明 |
| -------- |:---------:|:----:| ----------------------------------------------- |
| 🏠 首页 | ✅ | ✅ | API 健康检查 + 看板概览 |
| 💬 智能对话 | ✅ | ✅ | API 优先 → stub 降级（后端离线时本地 BERT + 模板） |
| 📊 运维看板 | ✅ | ✅ | 纯 API 数据展示 |
| 🎯 意图识别 | ⚠️ | ✅ | 需 `agents/` 模块，Docker 中显示本地运行指引 |
| 📚 政策检索 | ⚠️ | ✅ | 需 `agents/policy/` + langchain，Docker 中显示本地运行指引 |
| 📋 材料审核 | ⚠️ | ✅ | 需 `agents/material/`，Docker 中显示本地运行指引 |
| 🤝 跨域协同 | ⚠️ | ✅ | 需 `tools/a2a/`，Docker 中显示本地运行指引 |
| 🛡️ 安全治理 | ⚠️ | ✅ | 需 `governance/`，Docker 中显示本地运行指引 |
> 💡 **设计原则**：Docker 前端镜像保持轻量（~200MB），仅包含 streamlit + httpx。依赖项目模块（agents/governance/tools）的页面在 Docker 中优雅降级为提示信息，引导用户本地运行 `streamlit run frontend/app.py` 获得完整体验。安全护栏（PII 脱敏、注入检测）在 Docker 中通过后端 Agent 工作流完整集成。
### MCP 架构说明
```
Agent (LangGraph Node)
│
├─ MCP Client ✅ (唯一通道: 经 Gateway 获取真实能力)
│ └─ Gateway (12001) ──→ Policy Server (12011)
│ Material Server (12021)
│ Workflow Server (12031)
│
└─ Stub 降级 ✅ (MCP 不可用时显式降级保留基本功能)
```
---
# 14. Demo场景
## 场景：开餐饮店
用户：
```
我想在成都开一家餐馆，需要什么？
```
流程：
```
Intent Agent
↓
识别:
business_license
↓
Policy Agent
↓
查询政策
↓
Material Agent
↓
检查材料
↓
Workflow Agent
↓
生成办理流程
↓
返回结果
```
---
# 15. 项目亮点
## 1. 从Chatbot升级为Agent Platform
不是：
```
LLM + Prompt
```
而是：
```
Agent Runtime
+
Tool Ecosystem
+
Governance
+
Evaluation
```
---
## 2. MCP标准化工具体系
实现：
* 工具解耦
* 动态发现
* 统一调用
---
## 3. A2A跨域Agent通信
支持：
* 异步任务
* 外部Agent调用
* 状态恢复
---
## 4. AgentOps治理闭环
实现：
```
执行
↓
记录
↓
评估
↓
优化
↓
迭代
```
---
# 16. 业务流程
## 16.1 总体链路
从用户请求到最终回答的完整业务链路：
```
User
│
├── POST /api/chat { "user_query": "我要开一家餐馆" }
│ │
│ ├── JWT 认证 + RBAC 鉴权
│ ├── trace_id 生成（UUID7）
│ └── create_initial_state(user_query, trace_id)
│
▼
AgentService.execute(state, graph)
│
│ ┌─────────────────────────────────────────────────────────────┐
│ │ AgentRuntime.execute_with_safeguards() │
│ │ · LoopDetector（6窗口 + 3连续相同tool → 重规划） │
│ │ · Step 限制（最大10步 → 优雅终止） │
│ │ · Timeout（60s → RuntimeTimeoutError） │
│ └─────────────────────────────────────────────────────────────┘
│
▼
START ──► supervisor_node ← 任务理解 + 拆解 + 路由
│
├──(无 intent)──► intent_node ← BERT → 关键词 → LLM
│ │ 三级分类
│ ▼
│ supervisor_node ← 二次回环规划
│
├──(查政策)──► policy_node ← MCP → Milvus BM25 Reranker
│ │ → LLM 生成 → evidence
│ ▼
│ specialist 回 supervisor
│
├──(审材料)──► material_node ← MCP → OCR → NER → 规则校验
│ │
│ ▼
│ specialist 回 supervisor
│
├──(办件)───► workflow_node ← MCP → create_case → 办件号
│ │
│ ▼
│ route_after_workflow
│ │
│ ┌─────┴─────┐
│ │ │
│ (有A2A需求) (无A2A需求)
│ │ │
│ ▼ │
│ a2a_node │
│ │ │ │
│ (异步)│ │(同步) │
│ 挂起 │ 直接 │
│ →END │ 返回 │
│ │ │
│ └────┬─────┘
│ ▼
└──────────► governance_node ← GuardrailRunner
│ · PII 脱敏
│ · 注入检测
│ · 敏感词过滤
│ · 输出过滤
▼
END ──► ChatResponse
{ answer, evidence, intent,
risk_level, execution_steps, elapsed_ms }
```
## 16.2 请求接入
1. **JWT 认证**：解析 `Authorization: Bearer <token>` → 提取 `user_id` + `role`（强制 Bearer Token，无旁路）
2. **RBAC 鉴权**：4角色（admin/operator/auditor/user）× 16权限，MCP Tool 级别鉴权 + Gateway 层 JWT 验证
3. **输入护栏前置**：在 LLM 调用前通过 `GuardrailRunner.run_input()` 检测注入/敏感词，命中即阻断（不消耗 Token）
4. **TraceId 生成**：UUID7（时间排序 + 全局唯一），注入 `RequestLoggingMiddleware` → 全链路日志携带
5. **State 初始化**：`create_initial_state(user_query, trace_id)` → 24字段 TypedDict，trace_id/user_query 覆写，空列表追加字段初始化
## 16.3 意图识别与任务规划
```
supervisor_node 进入
│
├── 首次：start_trace(user_query) ← 建立 trace 上下文
│
├── supervisor.orchestrate(state)
│ │
│ ├── 1. Planner._llm_plan(state) ← LLM 生成 task_plan
│ │ └── fallback: _rule_plan() ← 关键词模板
│ │
│ └── 2. Router.route(task) ← LLM + 规则混合
│ ├── 关键词匹配（优先）
│ ├── _infer_by_keyword()
│ └── _llm_route() （LLM fallback）
│
└── 输出: state["task_plan"] = [Task, ...]
每个 Task: {type, agent, description, status: PENDING}
```
Intent 节点：
- **BERT 模型推理**（已微调，`models/intent/bert-intent/`，10 标签 99.5% 准确率）→ 高置信度(>0.7)直接返回
- **关键词匹配**（18条规则）→ 中置信度(0.5-0.7)，BERT 不可用时兜底
- **LLM fallback** → 最低置信度(0.3)，最后手段
- 生产路径：`nodes.py` 中 `IntentClassifier()` 默认启用 BERT（`auto_load=True`）
Intent 回环：`intent_node → supervisor_node` 为**静态边**，意图识别后必回 supervisor 二次规划。
## 16.4 专业 Agent 执行
| 节点 | Agent | MCP Server | 工具 | 降级行为（真实优先） |
| --------------- | ------------- | ----------------------- | ------------------------------------ | ---------------------------- |
| `policy_node` | PolicyAgent | `policy_server:12011` | `search_policy`, `get_policy_detail` | 真实 RAG 检索（mode=rag/bm25），空结果显式降级 stub |
| `material_node` | MaterialAgent | `material_server:12021` | `extract_entity`, `check_material` | 真实 OCR + 字段抽取，失败返回明确错误 |
| `workflow_node` | WorkflowAgent | `workflow_server:12031` | `create_case`, `query_status` | PostgreSQL 落库办件（case 表） |
每节点执行后：
- `task_plan` 中对应 PENDING 任务 → `status: COMPLETED`
- MCP 调用记录写入 `mcp_history`（含 trace_id / server_name / tool_name / latency_ms / status）
- 异常捕获 → `state["error"]` 设置 → `route_after_specialist` 判断是否回 supervisor 重试（retry_count < 3）
## 16.5 A2A 跨域协同
当 workflow 完成后，`_needs_a2a(intent, user_query)` 检测：
- 关键词：房产/不动产/房屋/产权/公积金/住房基金
- 意图：`property_service` / `fund_query`
**异步模式（真实外部 Agent）**：
```python
# a2a_node 中
result = await a2a_connector.send_task(skill="query_property", ..., callback_url=settings.a2a_callback_url)
# result["mode"] == "http" 且 status == "submitted" → 异步等待回调
state["waiting_task_id"] = result["task_id"]
await checkpointer.suspend_for_a2a(thread_id, ..., a2a_task_id)
# → 路由到 END（LangGraph 本轮结束，checkpoint 已落 PostgreSQL）
# 外部 Agent 若同步返回 completed → 直接携带 artifact 继续，无需挂起
```
**回调恢复**：
```
外部 Agent 完成 → POST /api/a2a/callback { task_id, status, artifact, signature, timestamp }
（AuthMiddleware 放行；HMAC 签名校验，±300s 防重放）
→ A2ACallbackHandler.process_callback()
→ 任务状态机 submitted → working → completed（写穿 a2a_task 表）
→ checkpointer.resume_from_a2a(task_id)
← a2a_task 表按 task_id 取 source_trace_id(thread) → 最新 checkpoint（带重试）
→ 注入 external_result，保留 waiting_task_id
→ graph.ainvoke(resumed_state, config) ← 从断点恢复
→ a2a_node._handle_a2a_resume() ← 合并外部结果到 evidence + 标记任务完成
→ supervisor 汇总（含外部数据）→ governance_node → END
```
> **Docker 部署**：`docker compose up` 会同时启动 `a2a-mock`（housing 12101 / fund 12111），api 通过 `A2A_HOUSING_URL` / `A2A_FUND_URL` 指向它。外部真实系统只需把这两个地址换成真实 Agent 的 HTTP 端点即可（协议一致）。
**同步模式**：外部 Agent 快速返回 `completed` 时直接继续流程，无需挂起。**降级 stub 仅在显式开启（`a2a_allow_stub`）时生效**，生产默认禁止静默返回假结果，外部系统故障时任务状态可追踪、可重试。
## 16.6 安全护栏与最终回答
**护栏双层防护**（输入前置 + 输出后置）：
1. **输入护栏（LLM 前）** — `execute_agent()` 中 `GuardrailRunner.run_input(user_query)` 在 `graph.ainvoke` **之前**执行：PII 检测 + Prompt Injection（12种模式）+ 敏感词（10个）。命中即阻断，LLM 不接收恶意输入。
2. **输出护栏（governance_node）** — `GuardrailRunner.run_output(final_answer)`：错误泄露 + 密钥泄露（5种模式）+ Prompt 泄露（4种模式）
3. **PII 自动脱敏** — 手机 `138****1234`、身份证 `110***********1234`、邮箱 `u***@domain.com`、银行卡
4. **阻断决策** — 输入 injection → 立即阻断（不消耗 Token）；密钥泄露 → blocked + risk_level=HIGH/CRITICAL
5. **Trace 收口** — `end_trace()` 将全链路 span 写入 TraceRecorder
`route_after_governance`：
- `blocked=True` → END（安全阻断）
- `error` 且 `retry_count < 3` → supervisor_node（重试）
- 否则 → END（正常结束）
## 16.7 降级与容错
三级降级链：
| 层级 | 降级对象 | 触发条件 | 降级行为 |
| ------- | ------------- | -------------- | --------------------------------------------- |
| L1 基础设施 | PostgreSQL | 连接失败 | 内存模式运行（TraceRecorder / MetricsCollector 内存存储） |
| L1 基础设施 | Redis | 连接失败 | 无缓存模式（跳过 rate limit / session 缓存） |
| L1 基础设施 | Milvus | 连接失败 | BM25 关键词检索（纯内存 TF-IDF） |
| L2 模型层 | LLM API | 无 API Key / 超时 | 规则模板回答（模板引擎 + 关键词匹配） |
| L2 模型层 | BERT | 模型未加载 | 关键词匹配 fallback（18条规则） |
| L2 模型层 | PaddleOCR | 引擎缺失/失败 | 显式降级（生产禁止静默 mock，返回明确错误） |
| L3 协议层 | MCP Server | HTTP 不可达 | 显式降级到离线 stub（结果标注 mode=stub） |
| L3 协议层 | A2A Connector | 外部 Agent 不可达 | 显式降级（开关控制，生产默认禁止静默 fallback） |
---
# 17. 代码运行逻辑
## 17.1 图构建
`build_graph()` 在 `orchestration/langgraph/graph.py` 中构建 StateGraph：
| 组件 | 数量 | 详情 |
| --- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| 节点 | **7** | supervisor / intent / policy / material / workflow / a2a / governance |
| 静态边 | **2** | `START → supervisor_node`、`intent_node → supervisor_node` |
| 条件边 | **6** 组 | route_after_supervisor / route_after_specialist ×2(policy+material) / route_after_workflow / route_after_a2a / route_after_governance |
依赖注入一览：
| 参数 | 类型 | 注入节点 | 降级行为（真实优先） |
| --------------- | --------------------- | ---------------------------- | ------------------ |
| `llm` | `BaseChatModel` | 全部 7 节点 | 无 API Key 时纯 stub（关键词+规则） |
| `mcp_client` | `MCPClient` | policy / material / workflow | 真实检索/落库，失败显式降级 stub |
| `a2a_connector` | `A2AConnector` | a2a | HTTP 真实对接，失败显式降级（开关） |
| `checkpointer` | `BaseCheckpointSaver` | a2a（挂起/恢复） | 无持久化（不支持 A2A 异步） |
| `supervisor` | `SupervisorAgent` | supervisor | 自动用 llm 构建 |
所有节点通过 `async def _xxx_wrapper(state)` 闭包注入依赖后在 `graph.add_node()` 注册。
## 17.2 Node 执行流
| 节点 | 底层 Agent | 核心行为 | 注入依赖 | MCP / 降级 |
| ----------------- | --------------- | ------------------------------------------------------- | --------------------------- | ------------------ |
| `supervisor_node` | SupervisorAgent | `orchestrate(state)` → Planner 生成 task_plan → Router 决策 | llm, supervisor | 无 MCP、关键词 fallback |
| `intent_node` | IntentAgent | BERT → 关键词 → LLM 三级分类 | llm | stub 关键词匹配 |
| `policy_node` | PolicyAgent | MCP `search_policy` → 真实 RAG（Milvus+BM25+重排） | llm, mcp_client | 真实检索，空结果降级 stub |
| `material_node` | MaterialAgent | MCP `check_material` → 真实 OCR+NED | llm, mcp_client | 真实识别，失败返回明确错误 |
| `workflow_node` | WorkflowAgent | MCP `create_case` → PostgreSQL 落库办件 | llm, mcp_client | DB 落库（case 表） |
| `a2a_node` | A2AConnector | `send_task` → 挂起 OR 显式降级（开关控制） | a2a_connector, checkpointer | 生产默认禁止静默 fallback |
| `governance_node` | GuardrailRunner | PII + 注入 + 敏感词 + 输出过滤 | 无 | 异常时自动放行 |
每个节点执行前：
1. `update_current_agent(state, AgentName.X)` — 设置当前 Agent
2. `transition_to(state, NodeName.X)` — 记录当前节点
3. `start_trace()` 守卫（仅 supervisor 首次进入）
4. `AgentTracer.span()` 包裹核心逻辑（governance/supervisor/intent）
5. `record_agent_call()` — 成功 + 失败路径均记录 metrics
## 17.3 Edge 条件路由
| 路由函数 | 判定依据 | 可能目标 |
| ------------------------ | ------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
| `route_after_supervisor` | task_plan 状态：无 intent → intent；有 PENDING → 按 agent；全完成 → supervisor(合成) 或 governance | intent / policy / material / workflow / governance / supervisor |
| `route_after_specialist` | 先检查 error/risk，再复用 `route_after_supervisor` | 同上全量 + supervisor(重试) |
| `route_after_workflow` | waiting_task_id → END(挂起)；`_needs_a2a()` → a2a；全完成 → governance | a2a / governance / supervisor / END |
| `route_after_a2a` | waiting_task_id → END；有 error → supervisor；否则 → governance | governance / supervisor / END |
| `route_after_governance` | blocked → END；waiting → END；error 且 retry<3 → supervisor；否则 END | supervisor / END |
关键规则：
- **任务状态机驱动**：`task_plan` 中每个 Task 的 `status: PENDING → COMPLETED/FAILED`
- **意图回环**：intent 识别后必回 supervisor 二次规划（静态边保证）
- **提前进入治理**：`risk_level=high/critical` 时跳过后续任务，直接 governance
- **错误重试**：`state["error"]` 非空 + `retry_count < 3` → 回 supervisor 重新规划
## 17.4 状态管理
`AgentState`（TypedDict，24字段）分两类更新策略：
**覆盖更新（标量字段）**：
```
trace_id / user_query / intent / current_agent / current_node
final_answer / risk_level / safety_check / execution_metrics
waiting_task_id / external_result / policy_result / material_result
error / retry_count
```
**追加更新（列表字段 + Annotated reducer）**：
```
task_plan → _task_plan_reducer（按 id 合并）
messages → operator.add
tool_calls → _tool_calls_reducer（按 tool_call_id 合并）
mcp_history → append
a2a_tasks → append
evidence → append
error_history → append
```
3个自定义 reducer：
- `_task_plan_reducer`：按 `task["id"]` 合并（新 id 追加，已有 id 覆盖）
- `_tool_calls_reducer`：按 `tool_call_id` 去重合并
- `_append_reducer`：通用追加
## 17.5 治理集成
治理模块在 `nodes.py` 中的接线方式：
```
supervisor_node（首个节点）
├── get_current_trace() is None → start_trace(user_query)
└── AgentTracer.span(AGENT, supervisor) → 记录 orchestrate 调用
每个节点
├── AgentTracer.span(AGENT, node) 或 直接 time.perf_counter()
├── record_agent_call(agent, success, latency_ms, trace_id)
└── 异常路径同样 record_agent_call(success=False)
governance_node（末尾节点）
├── GuardrailRunner.run_input(user_query)
├── GuardrailRunner.run_output(final_answer)
├── detect_pii(user_query)
├── get_collector().record_guardrail_block()
└── finally: end_trace()
```
**Trace 层级结构**：
- `start_trace()` 建立 root trace（contextvars 协程安全传播）
- 每个 `AgentTracer.span()` 自动创建子 span（`parent_span_id` 自动继承）
- `end_trace()` 将全链路 span 写入 `TraceRecorder`（内存，可选 `flush_to_db()`）
**Metrics 指标收集**：
- `record_agent_call()` → Counter + Gauge + Histogram（agent/latency/tokens/steps）
- `record_tool_call()` → Counter + Histogram（tool 维度）
- `record_guardrail_block()` → Counter（按 guard_type + severity）
- 全量可用 `export_prometheus_metrics()` 输出 Prometheus 文本格式
## 17.6 降级容错链
```
┌─────────────────────────────────────────────────┐
│ AgentRuntime 安全护栏 │
│ · LoopDetector: 6窗口 + 3连续相同 → 中断 │
│ · StepLimiter: 10步 → RuntimeExceededError │
│ · Timeout: 60s → RuntimeTimeoutError │
└─────────────────┬───────────────────────────────┘
│
┌─────────────┼─────────────┐
▼ ▼ ▼
LLM MCP A2A
│ │ │
├─可用 ├─可用 ├─可用
│ real LLM │ MCP Server │ HTTP async
│ │ │
├─不可用 ├─不可用 ├─不可用
│ stub 模板 │ stub 回答 │ mock Agent
│ │ │
▼ ▼ ▼
最终回答 最终回答 外部结果
任何层异常 → set_error(state, msg)
→ route 判断 retry_count
→ <3: 回 supervisor 重规划
→ ≥3: 进入 governance 处理
```
---
# 18. 开发指南
> **Phase 1 完成** ✅ — 27个模块完成，系统可在无 LLM / 无 PostgreSQL 的 stub 模式下完整运行。
> **Phase 2 完成** ✅ — MCP Server + Tool Calling 体系就绪，6个Tool + 3个Server + Gateway + Client 全部实现。
> **Phase 3 完成** ✅ — A2A 跨域 Agent 协同 + Async Callback 体系就绪，7个A2A模块 + LangGraph集成完成。
> **Phase 3 增强（2026-08-08）** ✅ — A2A 真实系统对接：HTTP 回调链路端到端跑通（同步/异步分流、HMAC 签名回调、checkpoint 恢复）、任务状态持久化（`a2a_task` 表 + `PostgresTaskStore`）、Docker 化（`a2a-mock` 服务 + `Dockerfile.agent`），端到端「公积金查询」验证通过。
> 已建立 `models/` 模型目录（已 gitignore），端口统一偏移避免本地冲突。
## Phase 1 — LangGraph Runtime + Supervisor + RAG ✅
### 编排层 (orchestration/langgraph/) — 6/6 完成
```
✅ state.py — AgentState(24字段) + 10 Pydantic模型 + 6枚举 + 3 reducer + 9 helper（931行，117测试）
✅ graph.py — StateGraph构建（7节点 + 6组条件边 + 2静态边 + checkpointer注入）（250行）
✅ nodes.py — 6个Agent节点函数（336行）
✅ edges.py — 5个条件路由函数（145行）
✅ checkpointer.py — PostgreSQL Checkpointer + A2A挂起/恢复（310行）
✅ runtime.py — Runtime安全护栏 + LoopDetector + 3异常类（394行，22测试）
```
### Agent层 (agents/) — 24/24 完成
```
✅ __init__.py — AgentRegistry（register/get/list/health_check/unregister，126行）
✅ supervisor/prompts.py — 5套Prompt模板（133行）
✅ supervisor/planner.py — Planner（LLM+规则混合，5种intent模板，JSON容错，227行）
✅ supervisor/router.py — Router（4层策略，16条目路由表，155行）
✅ supervisor/agent.py — SupervisorAgent（4场景编排，3次重试，192行）
✅ intent/prompts.py — LLM分类模板 + few-shot示例（48行）
✅ intent/schema.py — 10个预定义IntentLabel + IntentResult（64行）
✅ intent/classifier.py — IntentClassifier（3级：BERT→关键词→LLM，18条关键词映射，支持本地模型，~185行）
✅ intent/agent.py — IntentAgent（130行）
✅ policy/prompts.py — RAG回答生成模板（27行）
✅ policy/schema.py — PolicyResult + PolicyEvidence（28行）
✅ policy/agent.py — PolicyAgent（LLM+模板双模式，5种业务回答，165行）
✅ material/prompts.py — 材料审核Prompt模板（Phase 2）
✅ material/ocr.py — OCREngine（PaddleOCR 真实引擎优先 + 显式降级，Phase 2）
✅ material/extractor.py — EntityExtractor（6种正则模式，PII脱敏，Phase 2）
✅ material/validator.py — MaterialValidator（5种业务材料清单，别名匹配，格式校验，Phase 2）
✅ material/agent.py — MaterialAgent（5种业务材料清单，规则校验，118行）
✅ workflow/agent.py — WorkflowAgent（MCP 落库办件，create_case/query_status，114行）
✅ governance/security.py — SecurityChecker（PII/注入/敏感词/泄露 4类检测，165行）
✅ governance/behavior.py — BehaviorAnalyzer（循环/步数/Token异常检测，93行）
✅ governance/optimizer.py — Optimizer（失败率/步数/延迟/Tool分析，127行）
✅ governance/agent.py — GovernanceAgent（编排安全+行为+优化，99行）
✅ material/ 真实OCR模型 — PaddleOCR接入（双模式：真实引擎 + stub fallback）
✅ material/ 真实NER模型 — BERT-NER接入（双模式：transformers pipeline + regex fallback）
```
### 后端层 (backend/) — 10/10 完成
```
✅ config.py — Settings（40+字段含模型路径+端口，pydantic-settings + lru_cache，~290行）
✅ main.py — FastAPI app factory + lifespan(db init/shutdown) + CORS + /health（129行）
✅ tools/logger.py — loguru 完整系统（531行，20测试）
✅ api/schemas.py — 10个Pydantic API模型（225行）
✅ api/dependencies.py — 5个DI函数（140行）
✅ api/routes.py — 5个API端点（/chat, /status, /a2a, /dashboard, /eval，244行）
✅ middleware/auth.py — JWT Bearer 强制认证（无有效 JWT 一律 401，无 X-User-Id 降级）+ Token生成（~170行）
✅ services/agent_service.py — AgentService（注册+执行+恢复，159行）
✅ middleware/rbac.py — RBAC权限（4角色+16权限+MCP Tool鉴权+FastAPI依赖注入，~390行）
✅ middleware/tracing.py — OpenTelemetry（Trace/Span创建、W3C传播、Agent/Tool instrumentation、NoOp降级，~440行）
```
### 模型存储 (models/) — 已完成
```
✅ models/README.md — 模型清单 + 3种下载方式 + 微调说明
✅ models/embedding/ — BGE Embedding 模型目录（~1.3GB，已 gitignore）
✅ models/reranker/ — BGE Reranker 模型目录（~2.3GB，已 gitignore）
✅ models/intent/ — 意图分类 BERT 模型目录（~400MB，已 gitignore）
✅ models/fine_tuned/ — 微调版本管理（intent-v1, ner 等）
```
### 数据库层 (database/) — 3/3 完成
```
✅ connection.py — async SQLAlchemy + session factory + get_db DI + init/close（104行）
✅ models.py — 6表ORM（Trace, Agent, Prompt, Evaluation, Checkpoint, A2ATask，310行）
✅ schemas.py — CRUD Pydantic模型（Create/Response，133行）
```
### RAG管线 (rag/) — 5/5 完成（已接入真实模型，Embedding/Milvus/Reranker 进程级常驻）
```
✅ embedding.py — EmbeddingEngine（BGE-large-zh-v1.5，支持本地路径加载，~100行）
✅ retriever.py — HybridRetriever（Milvus稠密 + BM25稀疏 + RRF融合，134行）
✅ reranker.py — Reranker（bge-reranker-v2-m3，支持本地路径加载，~85行）
✅ generator.py — Generator（LLM + 简单拼接双模式，evidence标注，113行）
✅ knowledge_base.py — KnowledgeBase（PDF/DOCX/TXT加载 → 切分 → 索引，173行）
```
---
## Phase 2 — MCP Server + Tool Calling ✅
> **完成日期**: 2026-07-30
> **架构**: Agent → MCPClient → MCPGateway (12001) → MCP Server (12011/12021/12031) → Business Logic
> **降级策略**: MCP 不可用时显式降级到 stub 模式（结果标注 mode），保证系统可用
### MCP 工具 Schema (tools/mcp/schema.py) — 1/1 完成
```
✅ schema.py — 6个Tool的Input/Output Pydantic模型 + TOOL_REGISTRY全局注册表（267行）
```
### MCP 基础设施 (tools/mcp/) — 3/3 完成
```
✅ client.py — MCPClient（HTTP连接池、工具发现缓存、Gateway/Direct双模fallback，212行）
✅ gateway.py — MCPGateway（路由转发、审计日志、Server健康聚合、FastAPI sub-app，153行）
✅ start_servers.py — 一键启动脚本（3个MCP Server + Gateway，55行）
```
### Policy MCP Server (tools/mcp/servers/policy_server/) — 2/2 完成
```
✅ tools.py — search_policy（7条政策语料库关键词匹配）+ get_policy_detail（文档详情查询）
✅ server.py — FastAPI MCP Server（:12011, /tools/list + /tools/call）
```
### Material MCP Server + Agent 补全 — 6/6 完成
**Agent 层**:
```
✅ agents/material/prompts.py — 材料审核 + 实体抽取Prompt模板
✅ agents/material/ocr.py — OCREngine（PaddleOCR 真实引擎优先 + 显式降级）
✅ agents/material/extractor.py — EntityExtractor（6种正则模式: 姓名/身份证/手机号/地址/事项/信用代码 + PII脱敏）
✅ agents/material/validator.py — MaterialValidator（5类业务材料清单、10+别名映射、身份证/手机号格式校验）
```
**MCP Server**:
```
✅ tools/mcp/servers/material_server/tools.py — extract_entity（OCR→实体抽取）+ check_material（Validator调用）
✅ tools/mcp/servers/material_server/server.py — FastAPI MCP Server（:12021）
```
### Workflow MCP Server (tools/mcp/servers/workflow_server/) — 2/2 完成
```
✅ tools.py — create_case（CASE_XXXXXXXX办件号生成）+ query_status（hash确定性状态）
✅ server.py — FastAPI MCP Server（:12031）
```
### LangGraph 集成更新 — 2/2 完成
```
✅ orchestration/langgraph/nodes.py — policy_node/material_node/workflow_node 接入 MCPClient，真实优先 + 显式降级 stub
✅ orchestration/langgraph/graph.py — build_graph() 新增 mcp_client 参数注入
```
---
## Phase 3 — A2A + Async Callback ✅
> **完成日期**: 2026-08-02
> **架构**: Agent → A2AConnector → External Agent (Mock/HTTP) → Callback → Checkpointer → Resume LangGraph
> **降级策略**: 外部 Agent 不可用时显式降级到 stub（本地 Mock Agent，生产默认禁止静默 fallback）
### A2A 协议 (tools/a2a/protocol.py) — 1/1 完成
```
✅ protocol.py — 6个Pydantic模型（AgentCard, A2AMessage, A2ATaskRequest, A2ATaskResponse, A2AStatusQuery, A2AStatusUpdate）
+ 2个枚举（A2AMessageType, AgentHealth）+ 复用 A2ATaskStatus/A2ATaskRecord（smoke test: 28 passed）
```
### A2A 任务管理 (tools/a2a/task.py) — 1/1 完成
```
✅ task.py — TaskStateMachine（状态机: CREATED→SUBMITTED→WORKING→COMPLETED/FAILED/TIMEOUT）
+ TaskStore（内存存储: create/get/update/delete/list_by_status）
+ InvalidTransitionError + 全局单例（smoke test: 27 passed）
```
### 外部 Agent 注册中心 (tools/a2a/registry.py) — 1/1 完成
```
✅ registry.py — ExternalAgentRegistry（register, discover, get_agent, health_check, list_all）
+ 技能索引（skill→Agent映射）+ initialize_default_agents 预注册（smoke test: 23 passed）
```
### A2A 连接器 (tools/a2a/connector.py) — 1/1 完成
```
✅ connector.py — A2AConnector（send_task→HTTP 真实对接, check_status, cancel_task）
+ httpx.AsyncClient HTTP连接池 + 超时/重试 + 显式降级开关（smoke test: 14 passed）
```
### A2A 回调处理器 (tools/a2a/callback.py) — 1/1 完成
```
✅ callback.py — A2ACallbackHandler（process_callback: 验证→更新状态→恢复LangGraph）
+ create_callback_router（FastAPI sub-router）+ 全局单例（smoke test: 18 passed）
```
### Mock 外部 Agent (tools/a2a/mock_agents/) — 2/2 完成
```
✅ housing_agent.py — HousingAgent（query_property: 3条模拟房产数据 + register_property）
+ 公积金关联查询 + 脱敏返回 + stub 便捷函数（smoke test: 18 passed）
✅ fund_agent.py — FundAgent（query_fund: 3条模拟公积金数据 + query_fund_detail: 提取记录+贷款测算）
+ stub 便捷函数（smoke test: 18 passed）
```
### LangGraph 集成 — 3/3 完成
```
✅ orchestration/langgraph/nodes.py — 新增 a2a_node（技能检测→A2A调用→挂起/恢复）+ 3个辅助函数
✅ orchestration/langgraph/edges.py — 新增 route_after_workflow + route_after_a2a + _needs_a2a 检测
✅ orchestration/langgraph/graph.py — build_graph() 新增 a2a_connector 参数 + a2a_node 节点注册 + 路由配置
```
### FastAPI 集成 — 3/3 完成
```
✅ backend/api/routes.py — /api/a2a/callback 实现真实回调处理 + _resume_agent_after_callback
✅ backend/api/dependencies.py — 新增 get_a2a_connector() DI + get_agent_graph() 注入 A2A/Checkpointer
✅ backend/services/agent_service.py — resume_from_checkpoint 完整实现（读取checkpoint→注入external_result→恢复执行）
```
---
## Phase 4 — Evaluation + Dashboard ✅
> **最新更新（2026-08-05）**: 安全加固完成 — 护栏前置 LLM、MCP 认证+RBAC、CORS 白名单、A2A Callback HMAC、30+ 处 logger.warning、端口文档统一。
> **上一更新（2026-08-04）**: trace_provider 已实现，`--run-real` 可运行真实 Agent 工作流收集 trace。
> Intent 评测：3500 条用例，BERT 推理，**3484/3500 passed（99.5%）**。
### 第一步：评测体系 (governance/evaluation/) ✅
```
✅ metrics.py → RAG指标（Faithfulness, Answer Relevance, Context Recall，~630行）
+ Agent指标（Task Success Rate, Tool Accuracy, Latency, Step Count）
+ 双模式评分：LLM语义评估 + 规则bigram启发式
✅ evaluator.py → 评测引擎（~490行）+ 3条评测路径（cases/traces/db）+ 版本对比
✅ benchmark.py → Golden Dataset加载器 + BenchmarkRunner 批量评测（~350行）
✅ runner.py → CI/CD评测流水线（CLI: run/compare/list + DB持久化，~900行）
✅ trace_provider.py → 真实trace提供者（BERT意图 + LangGraph全流程双路径）
✅ llm_adapter.py → LLM Judge适配器（BaseChatModel → (prompt)→str 回调）
```
### 第二步：治理基础设施 (governance/) ✅
```
✅ trace.py → OpenTelemetry集成（trace_id, span_id, agent, tool, latency, token，~520行）
+ TraceRecorder存储器 + AgentTracer装饰器/上下文管理器 + contextvars异步传播
✅ guardrail.py → 输入检测（PII/Injection/Sensitive）+ 输出过滤（Error/Secret/Prompt leak，~660行）
+ 12种注入模式检测 + 5种密钥泄露检测 + GuardrailRunner编排
✅ pii.py → PII脱敏（手机138****1234, 身份证110***********1234, 邮箱u***@domain.com，~360行）
+ 4种PII类型 + detect_pii/mask_pii/batch处理
✅ monitor.py → Prometheus指标暴露（agent_success_rate, agent_latency, tool_success_rate，~620行）
+ MetricsCollector收集器 + Counter/Gauge/Histogram + Prometheus文本格式导出
✅ dashboard.py → 运维看板数据API（Agent运行统计, 评测趋势, 版本对比，~450行）
+ DashboardDataProvider + 双模式（DB查询/Memory聚合）+ 系统健康检查 + 告警
```
### 第三步：Prompt管理 (prompts/) ✅
```
✅ registry.py → Prompt注册中心（版本化: Role/Goal/Constraints/Tools/Output Schema/Examples，~590行）
+ PromptTemplate结构化模板 + PromptRegistry注册中心
+ 6个Agent预置模板 + 版本激活/停用 + {{ var }}渲染 + DB持久化
```
---
## 19. 实现优先级总结
```
第零步（环境准备）:
.env.example → 编辑 .env（端口/密钥）
models/ → 按需下载 Embedding / Reranker / BERT 模型
第一优先级（让系统跑起来）:
orchestration/langgraph/state.py → graph.py → nodes.py → edges.py
agents/supervisor/agent.py → planner.py → router.py
backend/main.py → config.py → api/routes.py
第二优先级（让Agent有知识）:
rag/embedding.py → retriever.py → reranker.py → generator.py
agents/policy/agent.py
agents/intent/classifier.py → agent.py
第三优先级（让Agent能调工具）: ✅ Phase 2 完成
✅ tools/mcp/schema.py → client.py → gateway.py
✅ tools/mcp/servers/policy_server/server.py → tools.py
✅ tools/mcp/servers/material_server/server.py → tools.py
✅ tools/mcp/servers/workflow_server/server.py → tools.py
✅ agents/material/ocr.py → extractor.py → validator.py → prompts.py
✅ orchestration/langgraph/nodes.py → graph.py (MCP集成)
第四优先级（让系统可治理）: ✅ Phase 4 完成
✅ governance/trace.py → guardrail.py → pii.py → monitor.py → dashboard.py
✅ governance/evaluation/metrics.py → evaluator.py → benchmark.py → runner.py
✅ prompts/registry.py
第五优先级（跨域协同）:
tools/a2a/protocol.py → task.py → connector.py → callback.py
第六优先级（生产化）:
deploy/Dockerfile → docker-compose.yml（根目录）
governance/dashboard.py → monitor.py
```
---
# 20. 更新日志
## 🎨 2026-09-02 — 前端视觉重构（政务企业级设计系统）
基于 `ui-ux-pro-max` 设计智能 skill 对前端整体视觉重构，替代此前与浅色政务蓝主题冲突的旧设计系统（Smart Home/IoT + Dark OLED 分类错误）与 emoji 泛滥问题。
| 改动 | 文件 | 说明 |
| --- | --- | --- |
| 设计系统 | `design-system/default/MASTER.md` | 重写为 **Government Enterprise SaaS / Analytics Dashboard**（Trust & Authority 方向）：Light Navy 配色（Primary `#1E40AF` / Navy `#0F172A` / 背景 `#F6F8FB→#EFF6FF`）+ Plus Jakarta Sans + WCAG AA 对比 + 3px 焦点环 + reduced-motion |
| UI 组件库 | `frontend/ui.py` | 全量重写：内置 **Lucide 风格 SVG 图标字典（`_ICONS` 35+）**、设计 token 三态兼容（SVG 名/完整 SVG HTML/emoji 降级）；组件升级：page_header 渐变 icon 徽章、metric_card 新增 `icon` 参数、section_header SVG、architecture_diagram SVG 箭头、新增 `sidebar_brand`/`sidebar_user_card` |
| 导航入口 | `frontend/app.py` | 登录页改居中品牌 Hero（SVG government 渐变 logo）+ 侧边栏品牌区/用户卡片；`st.Page` 导航 icon 用 Material 图标语法 `:material/name:` |
| 8 个页面 | `frontend/pages/*.py` | 全部去装饰性 emoji 换 SVG 图标名；「选择示例」pills 默认值随 options 同步去 emoji（修复 `st.pills` default 不在 options 的 StreamlitAPIException） |
> 验证：Streamlit AppTest 登录页 + 导航 + 8 页面全部 PASS（修复 `st.pills` default bug）；`docker compose up -d --build frontend` 重建前端镜像，完整 11 服务 healthy，前端 `:12345` HTTP 200、API `:12401` admin/admin123 登录成功。
## 🏛️ 2026-08-13 — 里程碑 v3.0 发布
> 政务多智能体平台 v3.0 完成全部规划任务，正式进入里程碑节点。
>
> 定位：面向政务「高效办成一件事」场景的企业级多智能体协同与治理平台。
> 技术栈：Python 3.12 + FastAPI + LangGraph 1.x + MCP + A2A + RAG + AgentOps。
### 核心指标
| 指标 | 数值 |
| --- | --- |
| 代码规模 | 38,551 行 Python |
| 提交数 | 54 |
| 自动化测试 | **231** pytest + 端到端 **23/23** |
| 意图识别准确率 | BERT 微调 **99.5%**（3500 用例） |
| 性能优化 | LLM 二次请求 **18.4s → 0.26s**（缓存命中） |
| CI/CD | ruff lint + pytest + GHCR 镜像构建推送 |
| 可观测性 | Prometheus + Grafana + Alertmanager（4 条告警规则） |
### 架构五层（全部落地）
```
用户 → FastAPI Gateway → Supervisor Agent（LangGraph StateGraph 编排）
↓
Intent / Policy / Material / Workflow / A2A / Governance
↓
MCP Gateway（JWT+RBAC）
↓
policy / material / workflow 三个 MCP Server
```
- **Agent 层**：6 类 Agent（supervisor / intent / policy / material / workflow / governance）
- **编排层**：LangGraph 1.x StateGraph + PostgresCheckpointer + A2A 挂起/恢复
- **协议层**：MCP（3 Server 标准化工具）+ A2A（HMAC 签名回调 + PostgresTaskStore 持久化）
- **知识层**：BGE embedding/reranker + Milvus HNSW + BM25 混合检索 + RRF 融合
- **治理层**：PII 脱敏 / Prompt 注入 / 敏感词护栏前置 / AgentOps 全链路 Trace
### 已交付能力
| 阶段 | 内容 | 状态 |
| --- | --- | --- |
| P1 核心框架 | LangGraph 工作流 + FastAPI + AgentState + Trace | ✅ |
| P2 知识系统 | RAG 管线 + MCP 协议 + 3 Servers | ✅ |
| P3 跨域协同 | A2A 真实系统对接（异步回调 + 状态持久化 + Docker 化） | ✅ |
| P4 治理评测 | AgentOps + Evaluation 平台（DB/文件双通道） | ✅ |
| P5 性能 | LLM 缓存 / Milvus 索引调优 / SSE 流式 | ✅ |
| P6 前端 | 8 页 Streamlit + 多轮对话 + 历史持久化 + 中文修复 + stub 降级 | ✅ |
| P7 质量 | 231 测试 + 3 个真实 bug 修复 + ruff 全绿 | ✅ |
| P8 企业级 | 监控告警 + CI/CD + Docker 端口规范化（12001~12431） | ✅ |
### Docker 部署拓扑
```
api 12401 │ mcp-server 12001/12011/12021/12031 │ a2a-mock 12101/12111
postgres 12221 │ redis 12201 │ milvus 12211 │ frontend 12345
prometheus 12411 │ grafana 12421 │ alertmanager 12431
```
### 当前状态
- PLAN.md 全部任务 ✅ 完成
- 搁置项：政务领域 LLM/embedding 微调（无真实数据）、k8s 生产部署（无集群）
- 里程碑：tag `v3.0.0` + GitHub Release（2026-08-13）
---
## 2026-08-08 — 监控告警（Prometheus + Grafana）+ CI/CD（GitHub Actions）
### 监控告警
| 改动 | 文件 | 说明 |
| --- | --- | --- |
| `/metrics` 端点 | `backend/main.py` | 暴露 `MetricsCollector` 指标（agent 调用/成功/失败/延迟/token），免认证 |
| 认证放行 | `backend/middleware/auth.py` | `/metrics` 加入免认证路径 |
| Prometheus 配置 | `deploy/prometheus/prometheus.yml` | 抓取 `api:12401/metrics`，15s 间隔 |
| Grafana | `deploy/grafana/**` | 自动配置 Prometheus 数据源 + gov-agent 看板（请求速率/成功率/错误率/延迟分位/token） |
| Alertmanager | `deploy/prometheus/alert_rules.yml` + `deploy/alertmanager/` | 4 条告警规则（失败率>20%/p95延迟>5s/无流量/token激增），Alertmanager 12431 |
| docker-compose | 新增 `prometheus`(12411) + `grafana`(12421) + `alertmanager`(12431) | 全栈一键起 |
### CI/CD（GitHub Actions）
`.github/workflows/ci.yml`：
- `lint`：`ruff check .`
- `test`：`pytest tests/`（231 个，离线/DB-free）
- `build`：master push 时构建并推送 api 镜像到 GHCR（`ghcr.io/lack-jpg/gov_ap/api`，仓库名转小写）
- `e2e`：手动触发，docker compose 全栈跑 `scripts/e2e_integration_test.py`
### 其他
- `requirements.txt` 补 `langchain-openai`（修复测试收集 + api 镜像 LLM 模式）
- `pyproject.toml` ruff 规则收敛 + `ruff check --fix` 全量清理（127 自动修复 + F821/F841/F401/E741/B004/B007）
**验证**：`/metrics` 返回 agent 指标；Prometheus target UP 且能查 `agent_calls_total`；Grafana `:12421` 自动加载看板；e2e 23/23；`ruff check .` 全绿；231 pytest 通过。
## 2026-08-08 — 测试覆盖 + MCP 链路修复
### 测试覆盖（PLAN #10）
| 测试 | 文件 | 说明 |
| --- | --- | --- |
| governance 模块 | `tests/test_governance_agents.py`（33 项） | SecurityChecker / BehaviorAnalyzer / Optimizer / GovernanceAgent |
| 评测指标 | `tests/test_evaluation_metrics.py`（34 项） | RAG 三指标 + Agent 指标 + 意图准确率 + 综合评分 |
| 评测引擎 | `tests/test_evaluation_engine.py`（9 项） | evaluate_from_traces/cases/json、compare_versions、markdown、嵌套用例 |
| A2A connector | `tests/test_a2a_connector.py`（6→11 项） | check_status / cancel_task 各分支 |
| 端到端集成 | `scripts/e2e_integration_test.py`（23 断言） | docker compose 全栈：健康/单轮/多轮/历史/看板/SSE/评测，**23/23 通过** |
`pytest tests/` 累计 **231 通过**。
### MCP 链路修复（端到端测试发现）
| Bug | 修复 |
| --- | --- |
| MCP 容器缺 `python-jose` → Gateway JWT 校验 500 | `deploy/Dockerfile.mcp` 加 `python-jose` |
| MCP Gateway 认证失败（api 未带 JWT + mcp 用默认密钥）→ 401 | `backend/api/dependencies.py` 传 `admin` JWT；`docker-compose.yml` mcp-server 共享 `JWT_SECRET_KEY` |
| workflow 完成后直接进治理 → `final_answer` 空 | `orchestration/langgraph/edges.py` `route_after_workflow` 先回 supervisor 合成 |
## 2026-08-08 — 前端中文显示修复
修复本地/容器前端部分页面出现英文的问题：
| 改动 | 文件 | 说明 |
| --- | --- | --- |
| 隐藏 Streamlit 原生英文 UI | `frontend/ui.py` | CSS 隐藏 Deploy 按钮 / "Made with Streamlit" 页脚 / 汉堡菜单，侧边栏不再有英文元素 |
| 意图标签中文化 | `frontend/pages/intent_page.py` | 「意图」卡片改显示中文名，英文枚举值降级为次要灰色卡 |
| LLM 输出强制中文 | `agents/supervisor/prompts.py`、`agents/policy/prompts.py`、`rag/generator.py` | 三个 LLM 提示词明确「始终使用简体中文回答」，避免偶发英文输出 |
> 验证：8 个页面 AppTest 渲染全中文无报错；`pytest tests/` 93 通过。
## 2026-08-08 — A2A 真实系统对接 + 任务持久化 + Docker 化
### A2A HTTP 回调链路端到端跑通（真实系统对接）
| 改动 | 文件 | 说明 |
| --- | --- | --- |
| Connector 分流 | `tools/a2a/connector.py` | 解析 `A2ATaskResponse`：同步 completed 直接返回 artifact / 异步 submitted 等回调；新增 `default_callback_url` |
| Mock 异步模式 | `tools/a2a/mock_agents/server.py` | 有 `callback_url` 时立即返回 submitted，后台执行 + HMAC 签名回调；`--smoke` 扩展异步断言 |
| 回调放行 | `backend/middleware/auth.py` | `/api/a2a/callback` 走 HMAC 校验而非 JWT，AuthMiddleware 放行 |
| 状态机兼容 | `tools/a2a/callback.py` | 回调直接 completed 时先 submitted→working 再进终态 |
| 恢复修复 | `orchestration/langgraph/checkpointer.py` | `resume_from_a2a` 改为 task→source_trace_id→最新 checkpoint（带重试）；`_get_latest_checkpoint` 按自增 id 取最新 |
| 恢复流程 | `backend/api/routes.py` `_resume_agent_after_callback` | 保留 waiting_task_id 供 a2a_node 消费 external_result；`a2a_node` 用 Connector 的 task_id 记 state |
| A2A 可达性 | `agents/supervisor/planner.py` + `orchestration/langgraph/edges.py` | `fund_query`/`property_service` 规则模板补 workflow 步骤；路由在跨域意图任务全完成后进入 a2a_node（LLM/规则规划均可达） |
| a2a_tasks 状态 | `orchestration/langgraph/state.py` | 改为替换语义（原 append reducer 在恢复重放时列表翻倍） |
### A2A 任务持久化
| 改动 | 文件 | 说明 |
| --- | --- | --- |
| `a2a_task` 表 | `database/models.py` + `database/migrations/versions/0002_a2a_task.py` | 任务状态/artifact/source_trace_id 落库 |
| PostgresTaskStore | `tools/a2a/task_store.py`（新增） | 写穿式持久化：内存镜像 + 每任务 asyncio.Lock upsert + 启动 hydrate，DB 故障降级内存 |
| 任务模型 | `orchestration/langgraph/state.py` | `A2ATaskRecord` 增加 `source_trace_id`（= thread_id，供回调恢复定位 checkpoint） |
### Docker 化
- `deploy/Dockerfile.agent`（新增）+ `docker-compose.yml` 新增 `a2a-mock` 服务（housing 12101 / fund 12111）
- api 容器 env：`A2A_HOUSING_URL` / `A2A_FUND_URL` → `http://a2a-mock:*`，`A2A_CALLBACK_URL` → `http://api:12401`
- 配置化端点：`backend/config.py` 新增 `A2A_HOUSING_URL` / `A2A_FUND_URL`；`.env`/`.env.example` A2A 块更新（回调默认 `localhost:12401`）
**端到端验证**：「查询公积金余额」→ a2a_node → HTTP → a2a-mock 异步回调 → checkpoint 恢复 → 最终回答含外部公积金数据（账号 GJJ-0282023001234，余额 285,600.5 元）+ 政策引用；`a2a_task` 表落库 completed + artifact。`pytest tests/` 84 通过 + a2a 全部 smoke 通过。
## 2026-08-08 — 性能优化 + 前端完善
### 性能优化
| 改动 | 文件 | 说明 |
| --- | --- | --- |
| LLM 响应缓存 | `governance/llm_cache.py`（新增） | `LlmCache`（Redis 优先 `llmc:` + 内存 TTL 回退）+ `CachingChatOpenAI`（按渲染消息哈希键）；`get_agent_graph` 一处替换覆盖全部 6 个 LLM 调用点 |
| 缓存配置 | `backend/config.py` | `LLM_CACHE_ENABLED` / `LLM_CACHE_TTL` |
| Milvus 索引调优 | `rag/knowledge_base.py` + `rag/retriever.py` | 补 HNSW `create_index`（M/efConstruction/nlist 配置化 + `ensure_index`）；读配置 host/port（修复 19530/12211 不一致）+ `nprobe` 配置化 |
| Milvus 参数 | `backend/config.py` | `MILVUS_INDEX_M/EF_CONSTRUCTION/NLIST`、`MILVUS_SEARCH_NPROBE` |
| SSE 流式 | `backend/api/routes.py` `/api/chat/stream` + `backend/api/dependencies.py stream_agent` | `graph.astream(stream_mode="values")` 逐节点产出 SSE 事件（节点中文标签），前端实时显示进度 |
**实测**：相同问题二次请求 `18.4s → 0.26s`（LLM 缓存命中）。
### 前端完善
| 改动 | 文件 | 说明 |
| --- | --- | --- |
| 多轮对话 | `backend/api/routes.py` + `backend/api/dependencies.py execute_agent` | `conversation_id` 作 LangGraph `thread_id`；历史注入 `messages` + `conversation_history`，规划/汇总 LLM 参考前文 |
| 历史持久化 | `database/models.py` + 迁移 `0003_conversation.py` + `backend/services/conversation_service.py` | `conversation` / `conversation_message` 表 + CRUD；`POST/GET /api/conversations`、`GET /api/conversations/{id}/messages` |
| 前端会话 | `frontend/pages/chat_page.py` + `frontend/api_client.py` | `st.session_state` 消息 + 侧边栏会话列表/新对话/加载历史 |
| 可视化图表 | `backend/api/routes.py dashboard_overview` + `frontend/pages/dashboard_page.py` | 透出 `agent_stats`/`eval_trends`/`total_tokens`；Agent 调用/成功率/耗时/Token 柱状图、评测趋势折线、评分分布柱状图（streamlit 原生） |
**验证**：SSE 节点进度 + final 事件 ✅；两轮对话 4 条消息落库、会话列表/消息读取 ✅；看板 agent_stats/total_tokens 透出 ✅；LLM 缓存 Redis `llmc:*` 键 + 重复查询 70× 提速 ✅。`pytest tests/` **93 通过**。
## 2026-08-06 — 前端视觉升级 + Docker 容器启动修复 + 评测报告文件回退
### 前端视觉升级（浅色专业政务风）
基于 `/ui-ux-pro-max` 生成的政务设计系统（`design-system/default/MASTER.md`），三层改造让 8 页前端形成统一视觉语言：
| 改动 | 文件 | 说明 |
| --- | --- | --- |
| Streamlit 主题 | `.streamlit/config.toml` | 新增 `[theme]`：政务蓝 `#1E40AF` 主色 / 背景 `#F6F8FB` / 次背景 `#EFF6FF` / 正文 `#1F2A44` |
| 共享 UI 组件库 | `frontend/ui.py`（新增） | `inject_theme_css()` 全局主题 + `page_header` / `metric_card` / `status_badge` / `evidence_card` / `architecture_diagram` 等 11 个组件，全部基于 Streamlit 原生 API + 内联 CSS，零新增依赖 |
| 全局主题注入 | `frontend/app.py` | `set_page_config` 后调用 `ui.inject_theme_css()` |
| 逐页重构 | `frontend/pages/*.py`（8 页） | 统一页头/指标卡语义色/状态徽章/证据卡；首页 ASCII 架构图升级为 HTML 流程图；示例问题改 `st.pills`；去掉零散 emoji 装饰 |
| 设计规范 | `design-system/default/MASTER.md`（新增） | 配色/字体/间距/组件规格/反模式，供后续页面遵循 |
### Docker API 容器启动修复
**根因**：Windows Docker Desktop 把宿主机目录 bind mount 进容器后显示为 root 所有（`drwxr-xr-x`），非 root 用户（appuser, uid=1000）写不进 → loguru 创建日志文件 `PermissionError` → uvicorn lifespan 启动异常反复重启。
| 改动 | 文件 | 说明 |
| --- | --- | --- |
| 容器入口脚本 | `deploy/docker-entrypoint.sh`（新增） | root 启动 → `chown` 授权 `/app/{logger,data,models,evaluation_results}` → `setpriv` 降权为 appuser 执行 uvicorn（业务进程仍非 root） |
| Dockerfile | `deploy/Dockerfile` | 移除 `USER appuser`，改为 ENTRYPOINT 降权模式；入口脚本 `export HOME=/home/appuser` 修复 asyncpg 读 `/root/.postgresql` 的权限错误 |
| Compose 挂载 | `docker-compose.yml` | api 服务挂载 `./evaluation_results:/app/evaluation_results`（评测报告文件回退读取） |
### 评测报告文件回退
`/api/evaluation/report/{version}` 原先只读 PostgreSQL `evaluation` 表；benchmark runner 的 `--save-result`（写文件）与 `--save-to-db`（写库）是独立开关，只写了文件时 API 会返回 404/错误。
- **`backend/api/routes.py`**: 新增 `_load_benchmark_report_file()`，DB 无记录或 DB 不可用时回退读取 `evaluation_results/*.json`（按 JSON 内 `version` 字段匹配、取最新、按 dataset 用例数加权聚合），保证已有评测文件也能在看板展示。
## 2026-08-05 — 安全加固 + 认证重构 + Bug 修复
### LangGraph 1.x API 兼容
Docker 容器内 LangGraph 版本升级导致 4 项 API 不兼容，已全部适配：
- **`checkpointer.py`**: `aput()` 增加 `new_versions` 参数，`aput_writes()` 增加 `task_path` 参数，`self._serde` → `self.serde` 属性变更，`dumps_typed()`/`loads_typed()` 适配 `(encoding, bytes)` 元组格式
- **`edges.py`**: intent 任务跳过时标记 `SKIPPED`，`all_completed` 检查扩大为 `COMPLETED/FAILED/SKIPPED`，防止 supervisor ↔ intent 死循环
- **`dependencies.py`**: `execute_agent()` 增加通用 `except Exception` 兜底，避免未预期异常逃逸
### 安全加固
| 加固项 | 文件 | 说明 |
| ----------------- | --------------------------------- | ------------------------------------------------------------------------ |
| 护栏前置 LLM | `dependencies.py` | `GuardrailRunner.run_input()` 在 `graph.ainvoke` 前执行，注入/敏感词立即阻断 |
| MCP 认证+RBAC | `gateway.py`, `client.py` | Gateway 增加 JWT Bearer Token 验证 + `admin`/`agent` 角色控制，Client 携带认证 Header |
| CORS 白名单 | `config.py` | 默认值从 `"*"` 改为 `"localhost:12345,localhost:12421"` |
| A2A Callback HMAC | `routes.py`, `schemas.py` | HMAC-SHA256 签名验证 + ±300s 防重放窗口 |
| 端口文档统一 | `docker-compose.yml`, `config.py` | 修正 Redis 端口注释 6480→12201，补充容器内/本地开发的端口区分说明 |
### 认证体系重构
旧版认证存在两个问题：(1) `dependencies.py:get_user_id()` 直接从 `X-User-Id` Header 读取用户 ID，忽略 `AuthMiddleware` 已注入的 `request.state.user_id`；(2) `RBACMiddleware` 在 `AuthMiddleware` 之前执行（FastAPI LIFO 顺序），权限检查时 `request.state.user_role` 尚未设置。
修复：
- **`dependencies.py`**: `get_user_id()` 改为从 `request.state.user_id` 读取
- **`main.py`**: 调换 `RBACMiddleware` / `AuthMiddleware` 注册顺序，Auth 先执行设置身份，RBAC 后执行检查权限；`global_exception_handler` 不再拦截 `HTTPException`（401/403 由 Starlette 原样返回）
- **`auth.py`**: JWT 解码失败改为 `pass`（fallthrough 到 `X-User-Id` 降级），不再立即抛 401
- **`rbac.py`**: USER 角色增加 `DASHBOARD_VIEW` + `EVALUATION_VIEW` 权限
- **`api_client.py`**: 新增 `_headers()` 函数，同时发送 `Bearer Token` + `X-User-Id` 双重认证头，Docker 前端容器兼容
### 日志系统修复
- **`tools/logger.py`**: `LOG_DIR` 从相对路径 `"logger"` 改为基于项目根目录的绝对路径，支持 `GOV_LOG_DIR` 环境变量覆盖
- **`config.py`**: 新增 `log_dir` 配置项
- 30+ 处降级路径增加 `logger.warning()`，覆盖 DB/Redis/MCP/A2D 和安全事件
### 前端改进
- **`dashboard_page.py`**: cases JSON 兼容 `list[{_description, cases, ...}]` 和 `dict` 两种结构
- **`api_client.py`**: `chat_with_fallback()` 后端不可用时自动降级到本地 stub（BERT 意图 + 政策模板）+ 双重认证头
### 验证
```
pytest: 231/231 passed（截至 2026-08-08）
guardrail: 45/45 passed
state: 117/117 passed
a2a: 15/15 passed
端到端集成: 23/23 passed（docker 全栈）
logger smoke: 20/20 passed
chat e2e: restaurant_license / risk=low / 200 OK
dashboard: total_requests=6, success_rate=1.0, active_agents=4
```
---
# 项目定位总结
本项目目标不是构建一个简单智能问答机器人。
而是探索：
> 企业级多智能体应用如何通过标准协议、工程治理和自动评测实现可靠落地。
连接信息
猜你喜欢
暂无推荐服务器