# 🔍 PingCode 项目健康度监控

> 让 PM 在 Claude Code 或 IM 群里一眼看清项目状态 —— 聚合、风控、自动告警。

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://python.org)
[![License](https://img.shields.io/badge/License-MIT-green)](LICENSE)

## 这是什么？

对接 **PingCode Open API**，提供两个入口：

| 入口 | 场景 | 实现 |
|------|------|------|
| **MCP Server** | PM 在 Claude Code 里直接对话查询 | `fastmcp` stdio 模式，5 个工具 |
| **IM 机器人** | PM 在企微/钉钉群里 @bot 查询 | `FastAPI` + 钉钉 Stream WebSocket |

同一套代码、同一份配置，两种输出格式（Markdown 表格 vs 群聊简短消息）。

```
┌──────────────┐     ┌──────────────────────────┐     ┌──────────────┐
│  Claude Code │────▶│  MCP Server (stdio)      │────▶│              │
│  (PM 本地)   │     │  src/server.py           │     │              │
└──────────────┘     └──────────────────────────┘     │   PingCode   │
                                                       │   Open API   │
┌──────────────┐     ┌──────────────────────────┐     │              │
│  钉钉/企微群 │────▶│  Bot (HTTP + Stream)     │────▶│              │
│  (群里 @bot) │     │  src/bot.py              │     │              │
└──────────────┘     └──────────────────────────┘     └──────────────┘
                            │
                            ▼
                     ┌──────────────┐
                     │  Web 管理后台 │
                     │  :8080/admin │
                     └──────────────┘
```

## 功能一览

### 5 个 MCP 工具

| 工具 | 用途 | 例 |
|------|------|-----|
| `list_pingcode_projects` | 列出所有项目 | "看看有哪些项目" |
| `get_project_health` | 项目健康度仪表盘 | "XX项目 状态怎么样" |
| `get_sprint_status` | Sprint / 迭代进度 | "XX项目 冲刺进度" |
| `get_risk_items` | 风险项明细 | "哪些逾期了" |
| `query_work_items` | 灵活查询 | "张三有哪些未完成的 task" |

### 群机器人能力

- 在企微/钉钉群里 `@机器人 XX项目 健康度` → 自动回复
- 支持模糊项目名匹配（"储能BMS" → 自动找到对应项目）
- 可选 DeepSeek AI 兜底（规则匹配不上时用自然语言理解）
- 风险自动推送（red/yellow → 群里弹告警）

### Web 管理后台

浏览器打开 `http://localhost:8080/admin`：
- PingCode 认证配置 + 一键测试连接
- 健康度阈值、状态标签自定义
- 通知推送、Bot、隧道、AI 所有配置
- 保存即时生效，无需重启

## 快速开始

### 1. 安装

```bash
git clone https://github.com/YOUR_USER/pingcode-health-mcp.git
cd pingcode-health-mcp

# 推荐：使用虚拟环境
python -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate

pip install -e .
```

### 2. 配置

**三种方式任选一种：**

```bash
# 方式 A: CLI 配置向导（推荐新手）
python -m src.setup

# 方式 B: Web 管理后台（推荐有桌面环境）
python -m src.bot
# → 浏览器会自动打开 http://localhost:8080/admin
# → 在页面上填写 PingCode 凭证，点击"保存配置"

# 方式 C: 手动编辑
cp config.example.yaml config.yaml
# 编辑 config.yaml，填写 pingcode.client_id 和 client_secret
```

### 3. 连接 Claude Code

编辑项目根目录的 `.claude/mcp.json`（或 Claude Code 全局设置）：

```json
{
  "mcpServers": {
    "pingcode-health": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/pingcode-health-mcp",
      "description": "PingCode 项目健康度监控"
    }
  }
}
```

重启 Claude Code，就可以直接问 "帮我看看 XX 项目的健康度"。

### 4. 部署到服务器（Bot 用）

```bash
# 上传代码到服务器
scp -r . user@your-server:/opt/pingcode-health/

# SSH 到服务器，运行部署脚本
ssh user@your-server
cd /opt/pingcode-health
sudo bash deploy/setup.sh

# 填写配置后启动
sudo systemctl start pingcode-bot
```

## 项目结构

```
pingcode-health-mcp/
├── README.md
├── pyproject.toml              # 依赖 + 入口点
├── config.example.yaml         # 配置模板
├── .env.example                # 环境变量模板
├── mcp.md                      # 需求文档
├── setup.py                    # CLI 配置向导入口
│
├── src/
│   ├── server.py               # MCP Server — 5 个 tool
│   ├── pingcode_client.py      # PingCode API — OAuth2 认证 + 分页 + 缓存
│   ├── health.py               # 健康度聚合引擎 — 统计 + 风险评级
│   ├── notifier.py             # Webhook 推送 — 企微/钉钉/飞书
│   ├── bot.py                  # Bot HTTP 服务 + Web 管理后台
│   ├── dingtalk_stream_bot.py  # 钉钉 Stream 模式机器人
│   ├── dingtalk_crypto.py      # 钉钉加解密
│   ├── config.py               # 配置管理 — YAML + 环境变量
│   ├── models.py               # 数据模型
│   ├── tunnel.py               # 内网穿透 — cloudflared / ngrok
│   └── setup.py                # CLI 配置向导
│
├── tests/
│   └── test_health.py
│
└── deploy/
    └── setup.sh                # Ubuntu 部署脚本 + systemd
```

## 配置参考

| 配置项 | 环境变量 | config.yaml | 必填 |
|--------|----------|-------------|:---:|
| Client ID | `PINGCODE_CLIENT_ID` | `pingcode.client_id` | ✅ |
| Client Secret | `PINGCODE_CLIENT_SECRET` | `pingcode.client_secret` | ✅ |
| Base URL | `PINGCODE_BASE_URL` | `pingcode.base_url` | ❌ |
| Webhook URL | `NOTIFICATION_WEBHOOK_URL` | `notification.webhook_url` | ❌ |
| 通知类型 | `NOTIFICATION_TYPE` | `notification.type` | ❌ |
| 钉钉 AppKey | `DINGTALK_APP_KEY` | `bot.dingtalk_app_key` | ❌ |
| 钉钉 AppSecret | `DINGTALK_APP_SECRET` | `bot.dingtalk_app_secret` | ❌ |
| AI API Key | `DEEPSEEK_API_KEY` | `ai.api_key` | ❌ |
| 监听端口 | `PORT` | `bot.port` | ❌ |

## 常见问题

**Q: PingCode Client ID / Secret 在哪找？**
登录 [PingCode 开放平台](https://open.pingcode.com) → 应用管理 → 创建"自研应用" → 选择 OAuth2 client_credentials 模式 → 复制凭证。

**Q: 钉钉回调 URL 验证失败？**
确保事件订阅和消息接收都切换为 **Stream 模式**（不要混用 HTTP 模式），且"开发管理" Tab 中没有残留的 HTTP 地址配置。

**Q: MCP Server 连不上？**
检查 `config.yaml`（或环境变量）中 `client_id` 和 `client_secret` 是否已填写。运行 `python -m src.setup` 可诊断。

**Q: 内网 Bot 怎么让企微/钉钉回调到？**
在 `config.yaml` 中设置 `tunnel.enabled: true`，Bot 启动时自动启动 cloudflared / ngrok 隧道。

**Q: 需要监控多个项目的健康度？**
`list_pingcode_projects` 列出所有项目 → 用 `project_id` 逐个查，或让 AI 批量调用。

## License

MIT