# netanalysis-agent **Repository Path**: ai_lab/netanalysis-agent ## Basic Information - **Project Name**: netanalysis-agent - **Description**: 一个能跑的「运营商网分分析助手」，让学员直观体验三个核心概念 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-20 - **Last Updated**: 2026-08-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 运营商网络数据分析 · 垂类 Agent 实战演示 **目标**：用一个能跑的「运营商网分分析助手」，让学员直观体验三个核心概念—— **function call（模型自主调工具） / MCP（工具标准化接入） / skill（能力包化）**。 **数据**：全部为脚本生成的模拟数据，不接入现网、不含真实隐私。 --- ## 0. 这个 Demo 教什么（三个核心概念） 很多材料把三者混为一谈，这里把它们拆开、各自独立、可逐一观察： | 概念 | 在网分助手里的角色 | 学员看到什么 | |---|---|---| | **function call** | 「动作」：模型理解问题后**自主决定调哪个工具、填什么参数** | 终端显示 Skill 路由、reference 加载和 `[mcp] 调用 ...` 日志 | | **MCP** | 「工具接入层」：工具以**标准协议**暴露，agent 经协议调用，不直接 import | server 是独立进程；换数据源只换 server，agent 一行不动 | | **Skill** | 「能力包」：metadata 负责触发，`SKILL.md` 定义做法，reference 保存按需细节 | 启动只读 name/description，输入触发后才加载正文和相关 reference | 一句话定位：**System Prompt 管所有请求都必须遵守的角色和边界，Skill 管特定任务怎么做，MCP 提供标准化查证能力，function call 是模型在运行时作出的动作**。 ### 三者协作架构 ``` 用户问题 │ ▼ ┌──────────────────────────┐ │ Agent 加载 system_prompt.md │ └─────────────┬────────────┘ │ Skill name + description ▼ ┌──────────────────────────┐ │ LLM 调用 select_skills │ └─────────────┬────────────┘ │ 只加载已选 SKILL.md ▼ ┌──────────────────────────┐ │ 按需 load_skill_reference │ └─────────────┬────────────┘ │ function calling / MCP ▼ ┌──────────────────┐ 查询 │ MCP Server │──────────► netanalysis.db (SQLite) │ (mcp_server/ │ │ server.py) │ │ 暴露 6 个工具 │ └──────────────────┘ ``` > 为什么这样设计：传统做法是 agent 直接 `import` 一堆函数，工具与 agent 强耦合、换数据源要改 agent。MCP 把工具变成「可插拔的标准服务」，skill 把「能力」变成「可分发文件」，function calling 才是运行时真正发生的动作。学员看清这三层，才算真正理解 Agent 工程。 --- ## 1. 整体架构与目录 ``` netanalysis-llm-demo/ ├── generate_demo.py # 生成演示数据（SQLite 库 + schema.sql + seed_data.sql） ├── verify.py # 验证数据可支撑演示 ├── netanalysis.db # SQLite 演示库（产物） ├── schema.sql # 建表语句（含字段中文注释） ├── seed_data.sql # 演示数据 INSERT ├── sample_queries.sql # 可直接跑的示例 SQL ├── requirements.txt # 核心依赖：mcp / openai / PyYAML ├── examples/ # 可选对照教学材料（独立依赖） ├── mcp_server/ # 【MCP】工具服务层 │ ├── server.py # MCP server（mcp 2.x MCPServer），暴露 6 个工具 │ └── test_server.py # 离线验证 server（不依赖 LLM） ├── agent/ # 【function call】Agent 编排层 │ ├── system_prompt.md # 基础角色、边界与 Skill 加载协议 │ ├── skill_registry.py # metadata 发现与安全渐进加载 │ ├── run.py # Skill 路由 + function calling + MCP client │ └── test_run.py # 路由/加载/故障护栏离线回归 ├── skills/ # 3 个可语义触发的项目级 Skill ├── evals/ # 20 条真实模型语义评估 ├── README.md └── AGENTS.md ``` --- ## 2. 环境与安装（Windows / Linux / macOS） 本项目 Agent 部分需 `mcp`（2.x）、`openai` 和解析 Skill metadata 的 `PyYAML`，基础数据生成仅用标准库。 ### 2.1 安装 Python（3.10 及以上） `mcp 2.x` 要求 Python 3.10+；本项目已在 Python 3.13.12 验证。使用 3.8/3.9 会在安装依赖时失败。 - **Windows**：`winget install Python.Python.3.12`（安装时勾选 Add Python to PATH）；或 python.org 下载包 - **Linux**：`sudo apt update && sudo apt install -y python3 python3-venv python3-pip` - **macOS**：`brew install python`（系统自带版本偏旧） 验证：`python3 --version` ### 2.2 SQLite - Python 的 `sqlite3` 模块是标准库，**无需 pip 安装**。验证：`python3 -c "import sqlite3; print(sqlite3.sqlite_version)"` - 可选装命令行 CLI：Windows `winget install SQLite.SQLite`；Linux `sudo apt install -y sqlite3`；macOS `brew install sqlite3` ### 2.3 安装依赖 ```bash cd netanalysis-llm-demo python3 -m venv .venv .venv/bin/python3 -m pip install -r requirements.txt ``` Windows 将 `.venv/bin/python3` 替换为 `.venv\Scripts\python.exe`。`examples/` 为可选对照材料，需要时再安装 `examples/requirements.txt`。 ### 2.4 推荐 IDE 推荐使用 **TraeCode CN** 或 **CodeBuddy CN**：二者均可直接打开本仓库、在终端内使用项目 `.venv` 运行命令，并调试 Agent 与 MCP 链路。 - **TraeCode CN**（字节跳动）： - **CodeBuddy CN**（腾讯）： --- ## 3. 快速开始 ```bash # 1) 生成演示数据（175 小区 × 8 周） .venv/bin/python3 generate_demo.py # 2) 离线验证 agent ↔ MCP 链路（无需 API key！） .venv/bin/python3 agent/run.py --self-test # 3) 配置真实 LLM（演示必须接真模型，做真实 function calling） export OPENAI_API_KEY=sk-xxx export OPENAI_BASE_URL=https://api.deepseek.com # 或任意兼容网关（DeepSeek/通义/本地 vLLM） export OPENAI_MODEL=deepseek-v4-flash # 4) 跑起来 .venv/bin/python3 agent/run.py # 交互模式 .venv/bin/python3 agent/run.py --query "福清掉话最高的小区是哪个？" # 单次提问 .venv/bin/python3 agent/run.py --query "福清掉话最高的小区是哪个？" \ --trace-file /tmp/netanalysis-trace.jsonl # 同时保存结构化轨迹 ``` `--self-test` 不连真实 LLM，验证 System Prompt、Skill metadata 注册和「agent → MCP server → SQLite」链路。真实 `--query` 会打印如下日志： ```text [system] 应用基础提示词 [skill-registry] 提供 3 个 Skill metadata [skill-router] 选择: network-kpi-analysis [skill] 已加载正文 [skill-reference] 已按需加载 ranking.md [mcp] 调用 list_metrics(...) [mcp] 调用 query_weekly_kpi(...) ``` 授课前建议运行完整离线回归： ```bash .venv/bin/python3 verify.py .venv/bin/python3 mcp_server/test_server.py .venv/bin/python3 agent/test_run.py .venv/bin/python3 agent/run.py --self-test ``` 真实模型语义评估： ```bash .venv/bin/python3 evals/run_evals.py --limit 5 # 冒烟 .venv/bin/python3 evals/run_evals.py # 完整 20 条 ``` 周报时间口径统一为 `[week_start, week_start + 7天)`：KPI 取该周，投诉只统计当周记录，告警统计到周末仍未闭环的记录。 --- ## 4. 数据模型 | 表 | 类型 | 说明 | |---|---|---| | `dim_region` | 维度 | 区县 / 网格 | | `dim_cell` | 维度 | 小区（CGI、频段、站型、经纬度、入网日期） | | `dim_metric` | 语义层 | 指标字典：中文名、单位、方向(up/down)、预警/优秀阈值、释义 | | `fact_cell_weekly` | 事实 | 小区周指标**宽表**：掉话率/接通率/切换/PRB/用户数/流量… | | `fact_alarm` | 事实 | 告警（类型、等级、描述、闭环时间） | | `fact_complaint` | 事实 | 用户投诉（区域、类型、用户数、详情） | 字段中文注释见 `schema.sql`。`fact_cell_weekly` 用宽表（每行=某小区某周全部指标），让 function calling 生成 SQL 时可直接 `ORDER BY drop_call_rate DESC`，避免 pivot 出错。 --- ## 5. MCP 暴露的工具（与 Skill 对齐） `server.py` 用 mcp 2.x 的 `MCPServer` 暴露 6 个工具，每个带中文 description 与 JSON Schema 参数： - `list_metrics(keyword?)` —— 从 `dim_metric` 查询指标代码、单位、方向和阈值 - `query_weekly_kpi(week_start?, region?, metric, top, order)` —— 小区周指标排行 - `get_cell_detail(cell_name, weeks=8)` —— 单小区近 N 周趋势 - `list_alarms(cell_name?, only_open=True)` —— 告警查询 - `list_complaints(region?, cell_name?, limit=20)` —— 投诉查询 - `get_weekly_report(week_start?)` —— 异常小区清单（当周指标 + 周末未闭环告警 + 当周投诉） agent 启动时经 MCP 拉取这些工具的 schema，自动转成 OpenAI function calling 格式——**新增工具只需在 server 加一个 `@mcp.tool()`，agent 无需改动**。 `dim_metric` 是指标语义的唯一事实来源：排行工具先用它验证列名，周报也从它读取阈值。Skill 不再重复写死指标阈值。 --- ## 6. 演示剧本（数据已注入故事） | 小区 | 异常类型 | 演示说法 | 主要 Skill | |---|---|---|---| | 福清_003 | 掉话率 4.11%（持续恶化） | 排名时只加载 ranking；问原因时关联 2 告警 + 3 投诉 | KPI / 故障诊断 | | 仓山_006 | 接通率 99.6%→97.08%（断崖） | 趋势加载 trend；问原因时追溯已闭环设备告警 | KPI / 故障诊断 | | 鼓楼_010 | 下行 PRB 93.7%（容量） | 语义层将「拥塞」对齐到下行 PRB，再给出容量线索 | KPI / 故障诊断 | | 长乐_004 | 上行干扰致质差 | KPI、上行干扰告警与语音质差投诉形成证据链 | 故障诊断 | --- ## 7. 学员观察点（演示时重点看这些） 1. **看 System Prompt**：启动时无条件加载 `agent/system_prompt.md`，它只放通用身份、安全边界和加载协议。 2. **看 Skill 触发**：排名、故障原因、周报会选择不同 Skill；复合问题可同时选择多个。 3. **看渐进加载**：启动只读 metadata；选中后加载 `SKILL.md`；排名、趋势、证据链和周报只读各自需要的 reference。 4. **看 function call**：观察 `select_skills`、`load_skill_reference` 和 MCP 工具调用，它们都是模型实际选择的动作。 5. **看 MCP 解耦**：server 是独立进程，Agent 通过协议自动发现 6 个工具。 6. **看语义层**：「拥塞」「掉话」等业务语言会先通过 `list_metrics` 对齐为指标代码和阈值。 7. **看失败边界**：写操作、精确预测、非法参数和工具超时都有可行动的拒绝或错误提示。 --- ## 8. 当前验证状态 - 离线：数据故事线、6 个 MCP 工具、System Prompt、Skill 路由、渐进加载、越界防护和故障路径全部通过。 - 真实模型：`glm-5.2` 在 2026-08-20 完整运行 20 条语义评估，20/20 通过。详细结果见 `evals/results/latest.json`。 - 这是当次真实运行结果，不代表换模型、换网关或多次重复后仍必然 100%。 ## 9. 边界提醒 - 本 Demo 不替代实时预测/大规模聚合/硬规则判断（归传统分析栈）。 - LLM 定位「参谋」：生成工具调用与报告，确定性查证由 MCP server 执行。 - 接真实数据前必须做：数据脱敏、权限分级、工具调用白名单（防越权查询）。 - function calling 依赖模型支持；演示前确认所选模型/网关支持 `tools` 参数。 ## 10. 基于python的Agent项目实践建议 1. 建议每个项目有独立的虚拟环境：使用全局python环境可能导致依赖版本冲突，产生各类奇怪的问题。 > Windows环境： > a.如何安装虚拟环境：直接在workbuddy中创建新任务，选择本地项目目录，直接发命令“帮我创建python虚拟环境”；或者自己在cmd下执行“c:/path/to/python.exe -m venv .venv” > b.激活虚拟环境：默认情况下在Trae上打开新的terminal会自动激动，如果没激活的话，打开cmd窗口，执行：.venv/Scripts/activate.bat 2. 创建AGENTS.md文件：这是整个项目的宪法，AI启动任何一个新对话时，都会自动加载这个文件的内容，与这个项目有关的，基本不会变化的规矩、约束、约定都建议在这里写上（比如，命名规范、开发流程、回答风格等） 3. 创建.agents/skills目录（先创建.agents目录，然后在.agents目录下创建skills子目录），所有以该项目有关的skill都放在这个skills目录下，避免将所有skill都放在全局目录下（~/.workbuddy/skills）,会浪费token 4. 建议基于git来进行文档版本管理：万一AI做错事了（乱改、乱删），你还可以通过git进行还原，但不要将API-KEY等涉及私密的信息，或者与本地环境有关的信息（比如.venv）等文件上传git，可通过.gitignore文件进行过滤（参考本项目的样例）