mai — 舞萌 DX 服务器状态查询 NPC

一个运行在 CNB 平台上的 NPC，用于查询 AWMC 舞萌 DX 服务器实时状态。

在任何 CNB 仓库的 Issue 或 PR 中 @mai 即可触发查询：


@HUST_losyi/mynpc(mai) 服务器现在什么状态
@HUST_losyi/mynpc(mai) 舞萌维护了吗

仓库结构


.
├── .cnb/
│   └── settings.yml          # NPC 角色定义（人设、头像、prompt）
├── .codebuddy/skills/
│   └── maimai-status-query/
│       ├── SKILL.md           # Skill 描述与使用指引
│       ├── agents/
│       │   └── openai.yaml    # Skill 接口配置
│       └── scripts/
│           └── query_maimai_status.py  # 查询脚本
├── .cnb.yml                   # 流水线配置（构建镜像 + NPC 事件绑定）
├── Dockerfile                 # 自定义 NPC 运行镜像
├── assets/
│   └── gongwei.png            # NPC 头像
└── npc搭建指南.md              # CNB NPC 通用搭建教程

架构概览


用户在 Issue/PR @mai
        │
        ▼
CNB 触发 NPC 事件流水线
        │
        ▼
拉取自定义镜像（含 skill + python3）
        │
        ▼
npc:go 内置任务启动 Agent
        │
        ▼
Agent 加载 maimai-status-query skill
        │
        ▼
执行 python3 scripts/query_maimai_status.py
        │
        ▼
脚本调用 AWMC Uptime Kuma API 获取实时数据
        │
        ▼
Agent 整理数据，输出格式化摘要
        │
        ▼
npc:go 自动将摘要发布为评论

关键配置详解

1. NPC 角色定义（`.cnb/settings.yml`）


npc:
  roles:
    - name: mai
      avatar:
        src: /assets/gongwei.png
      prompt: |
        你是「mai」，一个专注于舞萌（maimai）DX 服务器状态查询的助手。
        ...

name：角色名，用于 @仓库路径(角色名) 中的角色名匹配
avatar.src：头像，支持仓库内相对路径或外部 URL
prompt：Agent 的系统提示词，定义行为和风格

2. 流水线配置（`.cnb.yml`）


# 构建并推送自定义镜像
main:
  push:
    - services:
        - docker
      stages:
        - name: build and push
          script: |
            docker build -t ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest .
            docker push ${CNB_DOCKER_REGISTRY}/${CNB_REPO_SLUG_LOWERCASE}:latest

# NPC 任务定义
.npc_task: &npc_task
  - docker:
      image: ${CNB_DOCKER_REGISTRY}/${CNB_NPC_SLUG_LOWERCASE}:latest
    stages:
      - name: npc go
        type: npc:go            # 关键：NPC 内置任务，自动将 Agent 输出发布为评论

# 角色与事件绑定
mai:
  issue@npc: *npc_task
  issue.comment@npc: *npc_task
  pull_request@npc: *npc_task
  pull_request.comment@npc: *npc_task

要点：

main.push：推送到 main 分支时自动构建并推送 Docker 镜像
type: npc:go：必须配置，这是 NPC 内置任务，负责启动 Agent 并自动将输出作为评论发布。缺少此项会导致 Agent 输出不会显示为评论
image 使用 CNB_NPC_SLUG_LOWERCASE 变量，确保引用的是 NPC 仓库自身构建的镜像
mai 下的四个事件覆盖了 Issue 和 PR 的创建与评论场景

3. 自定义镜像（`Dockerfile`）


FROM cnbcool/default-npc-agent:latest

# 安装 Python3（skill 查询脚本依赖）
RUN apk add --no-cache python3

# 内置 maimai-status-query skill
COPY .codebuddy/skills/ /root/.codebuddy/skills/

要点：

基础镜像是 Alpine Linux（不是 Debian），用 apk 而非 apt-get
Python3 是查询脚本的运行依赖
Skill 文件 COPY 到 /root/.codebuddy/skills/，Agent 启动时会自动加载该目录下的所有 skill

Skill 工作流程

maimai-status-query

这是本 NPC 的核心 skill，负责查询 AWMC 舞萌 DX 服务器状态。

触发条件：用户询问服务器状态、是否维护、是否在线、可用率、延迟等问题时

执行流程：

Agent 识别到状态相关问题，加载 maimai-status-query skill
执行 python3 scripts/query_maimai_status.py
脚本调用 Uptime Kuma 状态页 API：
- /api/status-page/maimai — 获取监控组、公告、维护信息
- /api/status-page/heartbeat/maimai — 获取心跳数据（可用率、ping）
脚本对原始数据做归一化处理：心跳状态分类（在线/不稳定/离线/维护中）、近期波动分析、平均 ping 计算
输出结构化的纯文本或 JSON 报告
Agent 阅读报告后，用简洁中文总结关键信息回复用户

脚本参数：


python3 scripts/query_maimai_status.py              # 默认查询
python3 scripts/query_maimai_status.py --json        # JSON 格式输出
python3 scripts/query_maimai_status.py --recent-minutes 30   # 调整近期分析窗口

状态判定逻辑：

条件	状态
连续 N 次（默认 3）心跳 status=0	离线
最近一次心跳 status=0 或 2	不稳定
最近一次心跳 status=3	维护中
其他	在线

构建与部署流程


git push → main 分支
    │
    ▼
CNB 触发 main.push 流水线
    │
    ▼
docker build → 构建自定义镜像（含 python3 + skill）
    │
    ▼
docker push → 推送到 CNB 内部镜像仓库
    │
    ▼
下次 @mai 触发 NPC 事件时，拉取最新镜像执行

镜像只在推送到 main 分支时构建。Skill 或 Dockerfile 修改后需要 push 一次 main 分支来触发镜像更新。