Diagnosis Service

独立故障诊断 MCP 服务，作为可被任意业务服务接入的异常诊断中心：

• 业务服务通过 HTTP 推送异常日志。
• 诊断服务使用独立 MySQL 库 diagnosis_db 保存日志、服务注册、静态代码索引、历史工单和诊断报告。
• Codex、Claude Desktop 或其他 MCP 客户端可通过 /mcp 查询日志并生成诊断报告。
• demo-service/ 是随项目携带的外接测试服务，会随机制造 timeout 和空指针异常，用于验证接入链路。

Project Map

• app/: 诊断服务 FastAPI 应用。
  • main.py: HTTP API 和 MCP JSON-RPC 入口。
  • log_store.py: 日志写入、查询、统计和报告生成。
  • mcp_tools.py: MCP 工具定义和工具调用分发。
  • db.py: MySQL 访问层。
  • schemas.py: API DTO。
• demo-service/: 外部服务接入测试用例。
• infra/mysql/diagnosis_init.sql: 独立诊断库初始化脚本。
• scripts/: 本地链路冒烟测试和诊断静态数据导入脚本。
• docker-compose.yml: diagnosis-service、demo-service 一键运行，MySQL 连接外部 infra-stack。

APIs

Endpoint	Description
POST /api/logs	业务服务推送异常日志
GET /api/logs?service=&level=&trace_id=	查询异常日志
GET /api/logs/stats?hours=24	查询日志聚合统计
GET /api/services	查询已接入服务
POST /api/reports	生成诊断报告
GET /api/reports/{report_id}	查询诊断报告
POST /mcp	MCP JSON-RPC 工具入口
GET /health	健康检查

MCP Tools

• search_logs: 按服务、级别、traceId 和时间窗口查日志。
• search_code: 查询静态导入的代码符号。
• search_tickets: 查询相似历史故障工单。
• generate_report: 聚合日志、代码和工单证据生成诊断报告。
• get_report: 按报告 ID 查询报告。

Quick Start

cp .env.example .env
# 先启动外部 ai-agent-infra-stack，再启动诊断服务
docker compose up -d diagnosis-service demo-service
curl http://localhost:8200/health

推送一条异常：

curl -X POST http://localhost:8200/api/logs \
  -H 'Content-Type: application/json' \
  -d '{"service":"demo-service","level":"ERROR","trace_id":"tr_001","endpoint":"/api/order/1","exception_type":"TimeoutError","message":"order query timeout"}'

生成诊断报告：

curl -X POST http://localhost:8200/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"generate_report","arguments":{"service":"demo-service","trace_id":"tr_001"}}}'

运行 demo-service 外部接入验证：

for i in 1 2 3 4 5; do curl -s http://localhost:8300/api/order/$i || true; done
curl 'http://localhost:8200/api/logs?service=demo-service&page_size=10'

Local Development

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
DIAGNOSIS_MYSQL_DSN=mysql://agent:agent123@localhost:3306/diagnosis_db \
  uvicorn app.main:app --host 127.0.0.1 --port 8200 --reload

demo-service 本地启动：

cd demo-service
pip install -r requirements.txt
DIAGNOSIS_URL=http://localhost:8200 uvicorn app.main:app --host 127.0.0.1 --port 8300 --reload

Codex MCP Usage

把 MCP HTTP 入口配置到本地 Codex/其他 MCP 客户端时，服务地址使用：

http://localhost:8200/mcp

工具发现请求：

curl -X POST http://localhost:8200/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Environment

• DIAGNOSIS_MYSQL_DSN: 诊断库连接串，默认 mysql://agent:agent123@localhost:3306/diagnosis_db。
• DIAGNOSIS_URL: demo-service 推送诊断服务地址，默认 http://localhost:8200。
• SERVICE_NAME: demo-service 上报服务名，默认 demo-service。

Verification

python3 -m compileall app demo-service/app
bash scripts/smoke_test.sh

导入诊断静态数据：

python3 scripts/ingest_code.py --repo-dir demo-service --service demo-service
python3 scripts/ingest_tickets.py --ticket-dir datasets/tickets --service demo-service
python3 scripts/ingest_logs.py --log-dir datasets/logs --service demo-service