使用说明

基于人工智能的Azure DevOps助手（后端）

一个后端系统，为Azure DevOps中的会话式人工智能增强工作流提供动力。此项目提供REST和WebSocket API，用于使用用户提供的个人访问令牌（PAT）与Azure DevOps Board集成。AI功能可以使用OpenRouter.AI或OpenAI等LLM提供商启用。

建筑

高级系统设计

Frontend (Chat UI)
       |
       v
   Backend API <-----> Azure DevOps (PAT)
       |
       v
   AI/LLM Service (OpenRouter, OpenAI, etc.)

组件

Express/Node.js API服务器： 暴露REST和Socket。IO端点
Azure DevOps集成： 每个会话/请求使用用户提供的个人访问令牌（PAT）
人工智能服务（可选）： 连接到LLM提供商以进行自然语言查询和工作流建议
无状态后端： 没有代币的持久存储；每个请求处理的所有身份验证

特性

工作项管理

创建、更新、重新分配和描述用户故事、问题和任务
在冲刺之间移动工作项
按ID查看工作项详细信息

Sprint和董事会观点

获取当前冲刺状态
最近所有冲刺的概述
按冲刺、类型和状态列出和过滤项目

智能搜索与查询

按关键字搜索工作项
按类型、状态和冲刺进行筛选
查找未分配的项目、子任务和链接的错误

人工智能能力

询问有关冲刺和积压的自然语言问题
AI生成的冲刺和板的摘要
风险和阻断剂识别
规划重点建议

入门指南

先决条件

Node.js v14或更高版本（用于本地开发）
npm或纱线
Docker和Docker Compose（用于Docker部署）
Azure DevOps组织和项目
具有工作项读/写权限的Azure DevOps个人访问令牌（PAT）
（可选）用于AI功能的OpenRouter/OpenAI API密钥

安装和设置

选项1：本地开发（无Docker）

步骤1：克隆存储库

git clone https://github.com/your-username/azure-devops-chatbot-backend.git
cd azure-devops-chatbot-backend

步骤2：安装依赖项

npm install

步骤3：配置环境变量

复制示例环境文件并对其进行配置：

cp .env.example .env

编辑 .env 使用您的配置文件：

# Server Configuration
PORT=3001
NODE_ENV=development
LOG_LEVEL=info

# CORS Configuration (optional)
CORS_ORIGIN=*

# Azure DevOps Configuration (Optional - can be provided per request via headers)
AZURE_ORG_URL=https://dev.azure.com/your-org
AZURE_PROJECT=your-project-name

# Azure DevOps PAT for MCP Server (Required for MCP server only)
AZURE_DEVOPS_PAT=your-azure-devops-personal-access-token

# AI Service Configuration (Optional)
OPENROUTER_API_KEY=your-openrouter-api-key
OPENAI_API_KEY=your-openai-api-key

# Application URL
APP_URL=http://localhost:3001

重要提示：

对于 REST API：Azure DevOps PAT根据请求通过以下方式提供 Authorization: Bearer <pat> 头球

对于 MCP服务器: AZURE_DEVOPS_PAT 必须设置 .env 文件

AZURE_ORG_URL 和 AZURE_PROJECT 如果通过请求标头提供，则是可选的

步骤4：启动服务器

启动主API服务器：

npm start

服务器将在以下时间运行 http://localhost:3001 默认情况下。

自动重新加载的开发模式：

npm run dev

启动MCP服务器（单独进程）：

npm run mcp

处于开发模式的MCP服务器：

npm run mcp:dev

步骤5：验证安装

检查服务器是否正在运行：

curl http://localhost:3001/api/health

预期响应：

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "service": "azure-devops-chatbot-backend"
}

选项2：Docker部署

步骤1：克隆存储库

git clone https://github.com/your-username/azure-devops-chatbot-backend.git
cd azure-devops-chatbot-backend

步骤2：配置环境变量

创建一个 .env 项目根目录中的文件：

cp .env.example .env

编辑 .env 使用您的配置（请参阅下面的环境变量部分）。

步骤3：使用Docker构建和运行

选项A：使用Docker Compose（推荐）

# Build and start the container
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

选项B：直接使用Docker

# Build the Docker image
docker build -t azure-devops-backend .

# Run the container
docker run -d \
  --name azure-devops-backend \
  -p 3001:3001 \
  --env-file .env \
  -v $(pwd)/logs:/app/logs \
  azure-devops-backend

# View logs
docker logs -f azure-devops-backend

# Stop the container
docker stop azure-devops-backend
docker rm azure-devops-backend

步骤4：验证安装

curl http://localhost:3001/api/health

环境变量

完整的环境变量参考

创建一个 .env 项目根目录中的文件。您可以从以下位置复制 .env.example:

cp .env.example .env

服务器配置

变量	必填	默认	描述
`PORT`	没有	`3001`	服务器将运行的端口
`NODE_ENV`	没有	`development`	环境模式(`development`, `production`)
`LOG_LEVEL`	没有	`info`	日志记录级别(`error`, `warn`, `info`, `debug`)
`CORS_ORIGIN`	没有	`*`	CORS允许的来源（使用 `*` 对于所有或特定域）
`APP_URL`	没有	`http://localhost:3001`	应用程序URL（用于OpenRouter API）

Azure DevOps配置

变量	必填	描述
`AZURE_ORG_URL`	可选*	Azure DevOps组织URL（例如。， `https://dev.azure.com/your-org`)
`AZURE_PROJECT`	可选*	Azure DevOps项目名称
`AZURE_DEVOPS_PAT`	MCP需要	Azure DevOps个人访问令牌（MCP服务器需要）

注：

对于 REST API: AZURE_ORG_URL 和 AZURE_PROJECT 可以通过请求标头提供(x-org-url, x-project)或环境变量

对于 REST API：PAT根据请求通过以下方式提供 Authorization: Bearer <pat> 头球

对于 MCP服务器: AZURE_DEVOPS_PAT, AZURE_ORG_URL，以及 AZURE_PROJECT 必须在环境变量中设置

AI服务配置（可选）

变量	必填	描述
`OPENROUTER_API_KEY`	可选	用于AI功能的OpenRouter API密钥
`OPENAI_API_KEY`	可选	用于AI功能的OpenAI API密钥

注： AI API密钥也可以在REST API端点的请求主体中为每个请求提供。

按用例划分的环境变量

仅适用于REST API（无MCP）

PORT=3001
NODE_ENV=development
LOG_LEVEL=info

# Optional: Default values (can be overridden via headers)
AZURE_ORG_URL=https://dev.azure.com/your-org
AZURE_PROJECT=your-project-name

# Optional: AI features
OPENROUTER_API_KEY=your-key
OPENAI_API_KEY=your-key

注： PAT根据请求通过以下方式提供 Authorization 头球

仅适用于MCP服务器

PORT=3001
NODE_ENV=development

# Required for MCP Server
AZURE_DEVOPS_PAT=your-azure-devops-pat
AZURE_ORG_URL=https://dev.azure.com/your-org
AZURE_PROJECT=your-project-name

# Optional: AI features
OPENROUTER_API_KEY=your-key
OPENAI_API_KEY=your-key

对于REST API和MCP服务器

PORT=3001
NODE_ENV=development
LOG_LEVEL=info
CORS_ORIGIN=*
APP_URL=http://localhost:3001

# Required for MCP Server, optional defaults for REST API
AZURE_DEVOPS_PAT=your-azure-devops-pat
AZURE_ORG_URL=https://dev.azure.com/your-org
AZURE_PROJECT=your-project-name

# Optional: AI features
OPENROUTER_API_KEY=your-key
OPENAI_API_KEY=your-key

创建Azure DevOps PAT

转到Azure DevOps： https://dev.azure.com/{your-org}
点击您的个人资料图片→ 安全
点击 个人访问令牌 → +新令牌
配置令牌：
- 名字: Azure DevOps Assistant
- 组织：选择您的组织
- 过期：设置适当的过期时间
- 范围：选择 工作项（读写）
点击创建并复制令牌（您将不会再看到它）

运行服务

API主服务器

主API服务器提供REST端点和WebSocket支持。

开始：

npm start

开发模式：

npm run dev

使用Docker：

docker-compose up -d

MCP服务器

MCP服务器作为一个单独的进程运行，用于与AI助手集成。

开始：

npm run mcp

开发模式：

npm run mcp:dev

注： MCP服务器通过stdio进行通信，通常由MCP兼容客户端（Claude Desktop、Cursor等）启动，而不是直接运行。看 docs.md 获取客户端集成说明。

快速入门示例

本地开发

# 1. Clone and install
git clone <repository-url>
cd azure-devops-chatbot-backend
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env with your values

# 3. Start the server
npm run dev

# 4. Test the API
curl http://localhost:3001/api/health

Docker部署

# 1. Clone repository
git clone <repository-url>
cd azure-devops-chatbot-backend

# 2. Configure environment
cp .env.example .env
# Edit .env with your values

# 3. Start with Docker Compose
docker-compose up -d

# 4. Check logs
docker-compose logs -f

# 5. Test the API
curl http://localhost:3001/api/health

测试API端点

# Health check (no auth required)
curl http://localhost:3001/api/health

# Get work item (requires PAT in header)
curl http://localhost:3001/api/workitems/12345 \
  -H "Authorization: Bearer <your-pat>" \
  -H "x-org-url: https://dev.azure.com/your-org" \
  -H "x-project: your-project"

API 参考

所有端点都需要 Authorization: Bearer <azure-pat> 除非另有说明。

健康检查

方法	端点	描述
得到	`/api/health`	检查API运行状况

工作项API

方法	端点	描述	参数
职位	`/api/workitems`	创建新工作项	`type`, `title`, `description`, `sprint`
得到	`/api/workitems/:id`	按ID获取工作项的详细信息	`id`
补丁	`/api/workitems/:id/state`	更新工作项的状态	`id`, `newState`
补丁	`/api/workitems/:id/sprint`	将工作项移动到另一个sprint	`id`, `sprintId`
得到	`/api/workitems`	列出/过滤/搜索所有工作项	`type`, `sprint`, `state`, `keywords`
得到	`/api/workitems/:id/children`	列出工作项的子任务	`id`
得到	`/api/workitems/:id/linked-bugs`	列出与工作项链接的错误	`id`

Sprint API

方法	端点	描述	参数
得到	`/api/sprints/current`	获取当前冲刺的摘要	-
得到	`/api/sprints`	查看所有冲刺的概述	-
得到	`/api/sprints/:sprintId/items`	列出特定冲刺中的项目	`sprintId`, `type`

搜索和查询API

方法	端点	描述	参数
得到	`/api/search`	使用关键字搜索工作项	`query`, `type`, `state`, `sprint`

未分配的查询

方法	端点	描述
得到	`/api/workitems/unassigned/todo`	以“待办事项”状态列出未分配的项目

AI驱动的API

方法	端点	描述	正文参数
职位	`/api/ai/query`	NLP/自然语言查询	`question`, `context`, `openrouter_api_key` （可选）
职位	`/api/ai/summarize`	人工智能驱动的Sprint/Board摘要	`scope`, `id`, `openrouter_api_key` （可选）
职位	`/api/ai/suggestions/risks`	人工智能生成的风险识别	`sprintId` （可选）， `openrouter_api_key` （可选）
职位	`/api/ai/suggestions/focus`	人工智能规划/重点建议	`context`, `openrouter_api_key` （可选）

注：对于AI端点，您可以包括 openrouter_api_key 在POST主体中，用于每个用户/提供商的LLM选择。

WebSocket事件（Socket.IO）

后端通过Socket提供实时通信。IO在 /socket.io.

客户端→ 服务器事件

authenticate –发送PAT和会话的可选AI密钥
chat_message –发送聊天信息
devops_action –触发工作项/冲刺动作
ai_query –发送自然语言/AI查询

服务器→ 客户端事件

response –实时响应操作/查询
error –错误/事件报告
status_update –长期运行操作的进度更新

安全

无持久存储 PAT或AI密钥；每个会话的所有令牌都在内存中/无状态
所有操作均使用用户提供的PAT（最小特权原则）执行
PAT的范围应包括 工作项（只读/写）
使用 HTTPS/TLS 用于生产部署
验证并净化所有用户输入
建议生产限速

部署

支持平台

Azure应用服务
AWS EC2/弹性Beanstalk
谷歌云平台
维塞尔
Heroku
码头工人
任何Node.js兼容平台

Docker部署

看安装和设置有关Docker的详细说明，请参阅上文。

快速Docker命令：

# Using Docker Compose (recommended)
docker-compose up -d

# Using Docker directly
docker build -t azure-devops-backend .
docker run -d -p 3001:3001 --env-file .env --name azure-devops-backend azure-devops-backend

环境配置

所有配置都应使用环境变量。永远不要硬编码秘密。看环境变量部分以供完整参考。

项目结构

azure-devops-chatbot-backend/
├── src/
│   ├── routes/
│   │   ├── workitems.js
│   │   ├── sprints.js
│   │   ├── search.js
│   │   └── ai.js
│   ├── services/
│   │   ├── azureDevOps.js
│   │   └── aiService.js
│   ├── middleware/
│   │   ├── auth.js
│   │   └── errorHandler.js
│   ├── mcp/
│   │   └── server.js
│   ├── utils/
│   │   ├── logger.js
│   │   └── helpers.js
│   └── index.js
├── .env
├── .gitignore
├── package.json
├── docs.md
└── README.md

许可证

MIT许可证

贡献

欢迎拉取请求！对于重大更改，请先打开一个问题来讨论您想要更改的内容。

支持

对于问题或疑问，请打开GitHub问题或联系维护人员。

备注

该后端专为基于聊天的前端UI而设计，用户可以在其中直接输入他们的PAT
API和套接字是无状态和安全的
要启用AI功能，请通过前端或环境提供OpenRouter/OpenAI API密钥
后端不持久存储任何用户凭据或令牌

使用说明

基于人工智能的Azure DevOps助手（后端）

目录

建筑

高级系统设计

组件

特性

工作项管理

Sprint和董事会观点

智能搜索与查询

人工智能能力

入门指南

先决条件

安装和设置

选项1：本地开发（无Docker）

步骤1：克隆存储库

步骤2：安装依赖项

步骤3：配置环境变量

步骤4：启动服务器

步骤5：验证安装

选项2：Docker部署

步骤1：克隆存储库

步骤2：配置环境变量

步骤3：使用Docker构建和运行

步骤4：验证安装

环境变量

完整的环境变量参考

服务器配置

Azure DevOps配置

AI服务配置（可选）

按用例划分的环境变量

仅适用于REST API（无MCP）

仅适用于MCP服务器

对于REST API和MCP服务器

创建Azure DevOps PAT

运行服务

API主服务器

MCP服务器

快速入门示例

本地开发

Docker部署

测试API端点

API 参考

健康检查

工作项API

Sprint API

搜索和查询API

未分配的查询

AI驱动的API

WebSocket事件（Socket.IO）

客户端→ 服务器事件

服务器→ 客户端事件

安全

部署

支持平台

Docker部署

环境配置

项目结构

许可证

贡献

支持

备注

相关 MCP

学术论文搜索与下载服务

Qdrant向量搜索MCP服务器

MCP命令执行服务

AI工作流管理工具

提示模板管理服务器

对象存储MCP服务器