市场监管系统

消防系统

不动产系统

公积金系统

统一办件系统

Multi-Agent
+
Agent Governance
+
Evaluation Platform

                         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

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

StateGraph
+
Node
+
Edge
+
Checkpoint

START
 |
Supervisor
 |
Intent Recognition
 |
Task Planning
 |
+----------------+
|                |
Policy        Material
Agent         Agent
|                |
+----------------+
        |
 Workflow Agent
        |
 Governance
        |
       END

Agent
↓
MCP Client (Bearer Token)
↓
MCP Gateway (JWT 认证 + RBAC)
↓
MCP Server
↓
Business Service

search_policy
get_policy_detail

extract_entity
check_material

create_case
query_status

营业执照办理
↓
市场监管Agent
↓
消防Agent
↓
不动产Agent

A2A Connector
+
Async Task
+
Callback (HMAC 签名验证)

Created
 ↓
Running
 ↓
Waiting
 ↓
Completed

138****1234

110***********1234

u***@domain.com

Prompt Registry
       |
Version Control
       |
Runtime Loading

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            # 演进路线

Agent (LangGraph Node)
    │
    ├─ MCP Client ✅ (唯一通道: 经 Gateway 获取真实能力)
    │   └─ Gateway (12001) ──→ Policy Server (12011)
    │                          Material Server (12021)
    │                          Workflow Server (12031)
    │
    └─ Stub 降级 ✅ (MCP 不可用时显式降级保留基本功能)

我想在成都开一家餐馆，需要什么？

Intent Agent
↓
识别:
business_license
↓
Policy Agent
↓
查询政策
↓
Material Agent
↓
检查材料
↓
Workflow Agent
↓
生成办理流程
↓
返回结果

LLM + Prompt

Agent Runtime
+
Tool Ecosystem
+
Governance
+
Evaluation

执行
↓
记录
↓
评估
↓
优化
↓
迭代

 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 }

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}

外部 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

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

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

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()

┌─────────────────────────────────────────────────┐
│                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 处理

✅ 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测试）

✅ __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）

✅ 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/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 等）

✅ 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行）

✅ 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行）

✅ schema.py                   — 6个Tool的Input/Output Pydantic模型 + TOOL_REGISTRY全局注册表（267行）

✅ client.py                   — MCPClient（HTTP连接池、工具发现缓存、Gateway/Direct双模fallback，212行）
✅ gateway.py                  — MCPGateway（路由转发、审计日志、Server健康聚合、FastAPI sub-app，153行）
✅ start_servers.py            — 一键启动脚本（3个MCP Server + Gateway，55行）

✅ tools.py                    — search_policy（7条政策语料库关键词匹配）+ get_policy_detail（文档详情查询）
✅ server.py                   — FastAPI MCP Server（:12011, /tools/list + /tools/call）

✅ 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+别名映射、身份证/手机号格式校验）

✅ tools/mcp/servers/material_server/tools.py  — extract_entity（OCR→实体抽取）+ check_material（Validator调用）
✅ tools/mcp/servers/material_server/server.py — FastAPI MCP Server（:12021）

✅ tools.py                    — create_case（CASE_XXXXXXXX办件号生成）+ query_status（hash确定性状态）
✅ server.py                   — FastAPI MCP Server（:12031）

✅ orchestration/langgraph/nodes.py  — policy_node/material_node/workflow_node 接入 MCPClient，真实优先 + 显式降级 stub
✅ orchestration/langgraph/graph.py  — build_graph() 新增 mcp_client 参数注入

✅ protocol.py                — 6个Pydantic模型（AgentCard, A2AMessage, A2ATaskRequest, A2ATaskResponse, A2AStatusQuery, A2AStatusUpdate）
                                 + 2个枚举（A2AMessageType, AgentHealth）+ 复用 A2ATaskStatus/A2ATaskRecord（smoke test: 28 passed）

✅ task.py                    — TaskStateMachine（状态机: CREATED→SUBMITTED→WORKING→COMPLETED/FAILED/TIMEOUT）
                                 + TaskStore（内存存储: create/get/update/delete/list_by_status）
                                 + InvalidTransitionError + 全局单例（smoke test: 27 passed）

✅ registry.py                — ExternalAgentRegistry（register, discover, get_agent, health_check, list_all）
                                 + 技能索引（skill→Agent映射）+ initialize_default_agents 预注册（smoke test: 23 passed）

✅ connector.py               — A2AConnector（send_task→HTTP 真实对接, check_status, cancel_task）
                                 + httpx.AsyncClient HTTP连接池 + 超时/重试 + 显式降级开关（smoke test: 14 passed）

✅ callback.py                — A2ACallbackHandler（process_callback: 验证→更新状态→恢复LangGraph）
                                 + create_callback_router（FastAPI sub-router）+ 全局单例（smoke test: 18 passed）

✅ 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）

✅ 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 节点注册 + 路由配置

✅ 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→恢复执行）

✅ 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 回调）

✅ 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聚合）+ 系统健康检查 + 告警

✅ registry.py   → Prompt注册中心（版本化: Role/Goal/Constraints/Tools/Output Schema/Examples，~590行）
                   + PromptTemplate结构化模板 + PromptRegistry注册中心
                   + 6个Agent预置模板 + 版本激活/停用 + {{ var }}渲染 + DB持久化

第零步（环境准备）:
  .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

用户 → FastAPI Gateway → Supervisor Agent（LangGraph StateGraph 编排）
                            ↓
                    Intent / Policy / Material / Workflow / A2A / Governance
                            ↓
                       MCP Gateway（JWT+RBAC）
                            ↓
              policy / material / workflow 三个 MCP Server

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

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