Tub Viewer

TUB查看器——技术更新简报


一个多语言、多代理的人工智能网络应用程序，用于跟踪Azure、Dynamics 365、Microsoft 365、Power Platform和Security上的微软技术更新，由思维链推理和MCP集成管道提供支持。

建于 GitHub Copilot 在 代理商联盟@TechConnect 编程马拉松。

主页	搜索结果	导出菜单

______________________________________________________________________

✨ 特性

🔍 双模式导航

• 浏览模式 --从侧边栏中选择一个产品以查看分类更新
• 搜索模式 —Natural language queries like“告诉我这个月的更新信息”or“Azure breaking changes”

🧠 多步查询处理流水线（思维链）

查询通过 5步思维链推理流程 由GPT-4o提供动力：

1. 意图分类 --对查询意图进行分类（浏览/搜索/比较/总结）
2. 实体抽取 --通过LLM提取产品、周期、严重程度、关键字
3. 查询扩展 --解决缩写和歧义（例如“FO”→ “Dynamics 365财务与运营”）
4. 信心评分 --每个提取步骤都包括一个置信度得分（0-1）
5. 推理总结 --选择分析的自然语言解释

当 OPENAI_API_KEY 如果未配置，系统将优雅地降级为基于规则的NLP解析器（日语+英语），确保应用程序始终正常工作。

graph TD
    A[User Query] --> B[QueryAgent: Intent Classification]
    B --> C[QueryAgent: Entity Extraction]
    C --> D[QueryAgent: Query Expansion]
    D --> E[SearchAgent: Mock + Learn API]
    E --> F[RankingAgent: Relevance Scoring]
    F --> G{Evaluator: Quality Check}
    G -->|Score  E
    G -->|Score OK| I[Return Results + Reasoning Trace]

🤖 多代理架构（编排器工作模式）

搜索管道使用 多代理编排器 遵循Anthropic的“建立有效代理人”指导：

每个代理都键入了 Input/Output 接口，遵循SRP（单一职责原则），包括带请求ID跟踪的结构化日志记录。

🔄 评估与反馈循环

这 评估员代理 实现了一个自反射循环：

• 使用多因素评分（结果计数×相关性×覆盖率）评估结果质量
• 如果质量低于可配置的阈值(EVALUATOR_THRESHOLD):

1. 请求a 查询改写 来自GPT-4o（自反射模式） 1. 使用改进的查询重新解析和重新搜索 1. 使用更好的结果集（原始与改进）

• 最多重试1次 防止无限循环（快速失效原则）
• 评估结果包含在API对透明度的回应中

📊 推理跟踪UI

搜索结果包括 可折叠的推理跟踪面板 这可视化了：

• 管道执行 --每个代理步骤都有状态徽章和持续时间
• 思维链步骤 --所有5个带有置信条的CoT推理步骤
• 数据源细分 -模拟与学习API结果计数
• 相关性度量 --带有视觉条的平均和最高相关性得分
• 质量评估 --通过/失败状态和评估分数
• 请求ID --用于端到端跟踪和调试

✨ AI简报摘要

在对搜索结果进行排名后 简报摘要代理 生成执行摘要：

• 配置API密钥时，LLM-powered（GPT-4o）locale-aware摘要
• 基于规则的回退，统计突破性更改、新功能和改进
• 在结果列表上方显示为渐变卡

🌐 8语言支持

日语、英语、韩语、中文、西班牙语、法语、德语、葡萄牙语——所有UI文本都会动态切换。

📊 智能分类

更新自动分为3个严重级别：

• 🔴 重大变更/退休 --需要立即采取行动
• 🟡 新功能/更改 --推荐审查
• 🟢 改进/增强 --信息

📤 导出到Excel和PowerPoint

• Excel（.xlsx） --3页工作簿，包括摘要、完整更新列表（带过滤器和颜色编码）和专用的重大变更表
• PowerPoint（.pptx） --16:9演示文稿，包括标题幻灯片（统计卡）、严重性部分和每次更新的详细信息卡

🔗 MCP集成管道（模型上下文协议）

• Microsoft学习API --通过MCP SDK从learn.microsoft.com获取真实的文档更新
• 工作智商 --通过以下方式连接到M365租户数据（消息中心、电子邮件、公告） @microsoft/workiq MCP服务器
• 模拟数据来自 消息中心 模式（MCP源不可用时的回退）
• 用途 @modelcontextprotocol/sdk （stdio传输）适用于两个MCP客户端
• 3个数据源 并行搜索：模拟数据+学习API+WorkIQ
• 使用指数回退重试 -外部API调用重试最多2次（1秒，2秒延迟）
• 超时保护 --10秒中止信号，15秒WorkIQ超时

______________________________________________________________________

🏗️ 建筑

┌──────────────────────────────────────────────────────────────┐
│                        Next.js App                            │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │ Product     │  │ Search     │  │ Export     │             │
│  │ Selector    │  │ Bar (NLP)  │  │ Button     │             │
│  └─────┬──────┘  └─────┬──────┘  └─────┬──────┘             │
│        │               │               │                      │
│  ┌─────▼───────────────▼───────────────▼──────────────────┐  │
│  │              API Routes (Zod-validated inputs)          │  │
│  │  /api/updates  /api/search  /api/learn  /api/export/*  │  │
│  └──────┬──────────────┬──────────────────────────────────┘  │
│         │              │                                      │
│  ┌──────▼──────────────▼──────────────────────────────────┐  │
│  │        Multi-Agent Orchestrator Pipeline                │  │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │  │
│  │  │ Query    │→│ Search   │→│ Ranking  │→│Evaluator │ │  │
│  │  │ Agent    │ │ Agent    │ │ Agent    │ │ Agent    │ │  │
│  │  │(CoT/NLP)│ │(parallel)│ │(scoring) │ │(reflect) │ │  │
│  │  └────┬─────┘ └────┬─────┘ └──────────┘ └────┬─────┘ │  │
│  │       │             │                          │        │  │
│  │  ┌────▼─────┐ ┌─────▼─────────┐  ┌────────────▼─────┐ │  │
│  │  │ GPT-4o   │ │ Mock Data     │  │ Self-Reflection  │ │  │
│  │  │ (OpenAI) │ │ + Learn API   │  │ (Query Rewrite)  │ │  │
│  │  └──────────┘ └───────────────┘  └──────────────────┘ │  │
│  └────────────────────────────────────────────────────────┘  │
│                                                               │
│  ┌───────────────────────────────────────────────────────┐   │
│  │ Cross-cutting: Structured Logger │ Config │ Validators│   │
│  └───────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘

______________________________________________________________________

🚀 快速开始

# Clone
git clone https://github.com//tub-viewer.git
cd tub-viewer

# Install dependencies
npm install

# Configure environment (optional — app works without it)
cp .env.example .env
# Edit .env and add OPENAI_API_KEY for LLM reasoning

# Start dev server
npm run dev

# Open http://localhost:3000

先决条件

• Node.js 18+
• npm 9+
• OpenAI API密钥（可选-启用思维链推理）

______________________________________________________________________

⚙️ 配置（.env）

所有配置都通过具有合理默认值的环境变量进行管理。看 .env.example 查看完整列表。

配置集中在 src/lib/config.ts 具有类型安全访问器、验证和边界检查。

______________________________________________________________________

🧪 测试

使用全面的测试套件 Vitest 9个测试文件中有84个测试用例：

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage report
npm run test:coverage

测试覆盖率

______________________________________________________________________

🔒 安全和错误处理

安全标头

所有响应都包括通过以下方式硬化的HTTP标头 next.config.ts:

• X-Content-Type-Options: nosniff
• X-Frame-Options: DENY
• X-XSS-Protection: 1; mode=block
• Referrer-Policy: strict-origin-when-cross-origin
• Permissions-Policy: camera=(), microphone=(), geolocation=()

输入验证（Zod）

所有API端点都使用Zod模式验证输入：

• 查询长度限制（最多500个字符）
• 区域设置白名单（支持8种语言）
• 周期枚举验证
• 导出项目计数限制
• 具有字段级详细信息的结构化错误响应

错误处理和弹性

• 反应错误边界 --捕获渲染崩溃，并显示带有重试按钮的友好回退UI
• API速率限制 -搜索API上的窄窗口速率限制器（每个IP 30 req/min），具有429个响应和Retry-After标头
• 使用指数回退重试 -外部API调用重试最多2次（1s→ 2s)
• 优雅降级 --LLM不可用→ 基于规则的回退；了解API失败→ 仅模拟数据
• 超时保护 --所有外部通话均发出10秒中止信号
• 无内部错误泄漏 --错误响应返回安全消息，从不原始堆栈跟踪
• MCP客户端清理 --通过以下方式正确拆卸连接 closeMcpClients()

______________________________________________________________________

📊 测井和观测

结构化JSON日志记录 src/lib/logger.ts:

{
  "timestamp": "2026-02-14T01:00:00.000Z",
  "level": "info",
  "component": "Orchestrator",
  "message": "Multi-agent orchestrator completed",
  "requestId": "req_1707868800_a1b2c3",
  "durationMs": 1234,
  "data": { "resultCount": 15, "pipelineSteps": 4 }
}

特征：

• 日志级别：debug/info/warn/error（可通过以下方式配置 LOG_LEVEL)
• 请求ID跟踪：每个端到端关联请求的唯一ID
• 绩效衡量: withTiming() 异步操作分析实用程序
• 组件范围：每个模块都有自己的命名记录器实例

______________________________________________________________________

🛠️ 技术栈

______________________________________________________________________

📂 项目结构

src/
├── app/
│   ├── api/
│   │   ├── products/route.ts     # Product master data
│   │   ├── updates/route.ts      # Updates (mock + Learn MCP) with period filter
│   │   ├── search/route.ts       # Multi-agent orchestrated search
│   │   ├── learn/route.ts        # Microsoft Learn MCP integration
│   │   └── export/
│   │       ├── excel/route.ts    # Excel export
│   │       └── pptx/route.ts     # PowerPoint export
│   ├── layout.tsx
│   └── page.tsx                  # Main page (browse/search modes)
├── components/
│   ├── ProductSelector.tsx       # Accordion product list
│   ├── UpdateCard.tsx            # Severity-coded update card
│   ├── UpdateList.tsx            # Grouped update display
│   ├── SearchBar.tsx             # NLP search with suggestions (a11y + keyboard shortcuts: / to focus, Esc to clear)
│   ├── ExportButton.tsx          # Excel/PPTX dropdown (a11y: role=menu)
│   ├── ReasoningTrace.tsx        # Pipeline visualization + CoT steps + evaluation
│   ├── ErrorBoundary.tsx         # React error boundary with friendly fallback
│   ├── SkeletonLoader.tsx        # Loading skeleton for update cards
│   ├── LanguageSelector.tsx      # 8-language switcher
│   └── PeriodSelector.tsx        # Time range filter
└── lib/
    ├── agents/
    │   ├── orchestrator.ts       # Multi-agent pipeline coordinator
    │   ├── query-agent.ts        # Query analysis (LLM CoT + rule-based)
    │   ├── search-agent.ts       # Parallel multi-source search
    │   ├── ranking-agent.ts      # Relevance scoring & re-ranking
    │   └── evaluator.ts          # Quality check & self-reflection│   │   └── briefing-summary.ts   # AI executive summary (LLM + fallback)    ├── __tests__/
    │   ├── query-parser.test.ts  # 20 test cases
    │   ├── config-logger.test.ts # 12 test cases
    │   ├── validators.test.ts    # 11 test cases
    │   ├── mcp-client.test.ts    # 6 test cases
│   │   ├── products.test.ts      # 5 test cases
│   │   ├── ranking-agent.test.ts # 9 test cases
│   │   ├── evaluator.test.ts     # 8 test cases
│   │   ├── orchestrator.test.ts  # 8 test cases
│   │   └── rate-limiter.test.ts  # 5 test cases
    ├── rate-limiter.ts           # Sliding-window rate limiter
    ├── llm-query-analyzer.ts     # GPT-4o Chain-of-Thought engine
    ├── config.ts                 # Centralized env var management
    ├── logger.ts                 # Structured JSON logging
    ├── validators.ts             # Zod input validation schemas
    ├── types.ts                  # Types + i18n text (8 languages)
    ├── products.ts               # 21 products, 6 families
    ├── mock-data.ts              # Realistic MC-style data
    ├── query-parser.ts           # Rule-based NLP (fallback)
    └── mcp-client.ts             # MCP client with retry & timeout

______________________________________________________________________

🤖 GitHub副本使用情况

整个项目是使用 代理模式下的GitHub Copilot 在VS代码内：

1. 建筑设计 --Copilot设计了多代理管道、组件结构和数据流
2. 代码生成 --所有通过Copilot生成的Types/React组件
3. MCP集成 -Copilot配置的MCP SDK客户端和Microsoft Learn API连接
4. 多智能体系统 --在Copilot指导下实现的Orchestrator Workers模式
5. LLM集成 --用Copilot设计和构建思维链推理管道
6. NLP实现 --使用Copilot辅助构建的日语/英语NLP查询解析器
7. 测试 --使用Copilot生成的9个测试文件中的84个单元测试
8. 导出功能 --Copilot编码的ExcelJS和PptxGenJS文档生成
9. 错误处理 --Copilot添加的重试机制、Zod验证、结构化日志记录
10. 国际化 --由Copilot生成和维护的8语言UI文本

______________________________________________________________________

🎯 黑客马拉松赛道

轨道1：🎨 创意应用——GitHub Copilot

______________________________________________________________________

📜 免责声明

该项目是在代理商联盟@TechConnect黑客马拉松期间创建的。

______________________________________________________________________

📄 许可证

麻省理工学院