TowerWatch Ops Agent

一个构建在 TowerWatch（网络质量监控项目）之上的智能体层，旨在演示企业级智能体工程闭环所需的三种能力：评估套件、成本/延迟感知的模型选择和工具检索。一个仓库，一个连贯的故事：

“我拿自己的公开监控项目，围绕它构建了企业所需的智能体层：一个带有明确 SLI 的插桩 MCP 服务器、一个能在 CI 中捕获种子回归的评估框架、一个成本感知的模型路由器，以及 具有可测量选择精度的语义工具检索。”

概览

• 运行时： Python 3 + FastMCP，使用 uv 管理。

• 领域： TowerWatch 的网络监控数据，以智能体工具的形式暴露。

• 传输： 优先 stdio；无状态可流式 HTTP 作为延伸目标。

• 可观测性： 从第一次工具调用起使用 OpenTelemetry，接入 Prometheus/Grafana 技术栈。

• 工具面： 七个工具——query_metrics、analyze_window、compare、query_log_events、get_monitor_status、get_runbook、run_speedtest。契约见 docs/design/。

• 状态： 🟡 阶段 1 进行中——服务器可运行，七个工具中已构建一个；目前尚未满足任何阶段 1 验收标准。参见 状态。

为什么做这个项目

它填补了“我读过关于智能体评估和路由的文章”和“我亲手构建并测量了它”之间的空白。每一件产物——评估表、基准数字、precision@k 图表——都是亲自收集的数字，而非来自研究的论断。领域数据来自作者已经拥有的真实项目，所以这个故事是“我扩展了自己的生产级系统”，而不是“我照着教程做了一遍”。

整个构建遵循作者自己的智能体协作原则：每个阶段的完成定义都是一组可独立检查的产物——一条能运行的命令、一个存在的文件、一个能渲染的仪表盘。没有“相信我，它能用”这回事。

Related MCP server: production-grade-mcp-agentic-system

三个阶段

整个项目是一次构建，分为三个严格排序的阶段。完整规格位于 docs/specs/；构建计划是索引。需求是在规划过程中预先定义、并作为契约被遵循的——先有规格，工具契约由规格推导而来，ADR 记录了塑造工具面的每一个决策。

顺序是严格的： 阶段 2 的评估为阶段 3 的路由器打分。不要重排。横切层是例外——它增量落地，不阻塞任何内容。

仓库布局

towerwatch-ops-agent/
├── README.md                       # this file — human-facing
├── CLAUDE.md                       # agent-facing anchor (read first if you're an agent)
├── pyproject.toml                  # PEP 621 single source of truth — deps, tooling config
├── docs/
│   ├── architecture.md             # intended shape (stub — not built yet)
│   ├── specs/                      # the governing build plan + 4 requirement specs
│   ├── design/                     # locked tool contracts (00–11) — authoritative
│   ├── adr/                        # architecture decision records
│   └── production-path.md          # personal-scale choices vs. enterprise needs
├── src/towerwatch_ops_agent/       # server, config, domain/, tools/, telemetry/
├── tests/                          # pytest suite — 95 tests
├── fixtures/stub/                  # hand-authored stub corpus (not the real one)
└── RATIONALE.md                    # deliberate choices that read as defects

快速开始

服务器可运行并提供 query_metrics。其余六个工具尚未构建。

# From repo root. uv manages the environment and lockfile.
uv sync                            # create .venv, install deps from pyproject.toml
uv run python -m towerwatch_ops_agent   # (Phase 1) launch the MCP server over stdio

（阶段 1）使用 MCP Inspector 交互式测试服务器：

npx @modelcontextprotocol/inspector uv run python -m towerwatch_ops_agent

状态

🟡 阶段 1 进行中。 MCP 服务器通过 stdio 运行，并针对一个 fixture 端到端提供 query_metrics。阶段 1 的五项验收标准尚未满足任何一项——门禁清单见 spec-phase1-mcp-server.md。

已构建并运行：

• 目录骨架、pyproject.toml、.gitignore、MIT 许可证

• README、CLAUDE.md（含约束性不变量）、架构桩

• 构建计划及 docs/specs/ 中的全部四份需求规格

• 已锁定的工具契约——docs/design/ 00–11：约定、七份工具文档、技能接口、span 模式、fixture 清单、评估设计

• ADR——docs/adr/，工具面背后的决策记录

• MCP 服务器 + 组合根——server.py、config.py、stdio 传输

• query_metrics——7 个工具中的第 1 个，强制使用 data_status 信封

• FixtureClient + 清单加载器——ADR-0002 的双模式接缝，仅 fixture 侧

• Span 插桩——每次工具调用一个 span，从结构上排除密钥

• CI 工作流——在每个 PR 分支头部运行 ruff、format、pyright、pytest

• RATIONALE.md——记录那些刻意选择，否则审阅者会当作缺陷报告

已推迟（尚未构建——阶段门禁见 CLAUDE.md）：

• 其余六个工具——analyze_window、compare、query_log_events、get_monitor_status、get_runbook、run_speedtest

• GrafanaCloudClient——DataClient 协议的实时端

• 精选 fixture 语料库——fixtures/stub/ 是一个手工编写的双窗口桩，仅用于验证格式，并非真正的确定性语料库

• OTel 导出器 + SLI 仪表盘——span 已发出但无处可去；没有 MeterProvider，因此没有持续时间直方图

• def_tokens.md——工具定义 token 预算测量（脚本已存在，从未运行）

• bench.md——跨模型成本/延迟基准

• 阶段 2——评估框架 + CI + 种子回归演示

• 阶段 3——模型路由器 + 语义工具检索

• .claude/skills/ 下的仓库内技能——diagnose-rca、evidence-pack，以及首次手动走通时创建的黄金路径技能（add-tool、run-evals）

• 可测量的上手评估（docs/onboarding-eval.md）——阶段 1 之后首次运行

面向 AI 助手

如果你是在这个仓库中工作的智能体，请先阅读 CLAUDE.md。它包含阶段顺序、无状态门禁工作标准，以及“已存在什么 vs 仍是桩”的明确地图，这样你就不会去推理尚不存在的代码。RATIONALE.md 记录了那些一眼看上去像缺陷的刻意选择——在报告缺陷之前先读它。