一个运行在 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 自动将摘要发布为评论

---

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

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

# 构建并推送自定义镜像
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 的创建与评论场景

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

---

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

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

执行流程：

1. Agent 识别到状态相关问题，加载 maimai-status-query skill
2. 执行 python3 scripts/query_maimai_status.py
3. 脚本调用 Uptime Kuma 状态页 API：
   • /api/status-page/maimai — 获取监控组、公告、维护信息
   • /api/status-page/heartbeat/maimai — 获取心跳数据（可用率、ping）
4. 脚本对原始数据做归一化处理：心跳状态分类（在线/不稳定/离线/维护中）、近期波动分析、平均 ping 计算
5. 输出结构化的纯文本或 JSON 报告
6. 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 分支来触发镜像更新。

---

.cnb.yml 中的 NPC stage 必须配置 type: npc:go，否则 Agent 的文本输出不会自动发布为评论。没有此配置时，Agent 只会在流水线日志中输出，用户在 Issue/PR 评论区看不到回复。

cnbcool/default-npc-agent:latest 基于 Alpine Linux，包管理器是 apk 而非 apt-get。安装依赖时注意使用正确的命令。

如果 skill 脚本依赖 Python 等运行时，必须在 Dockerfile 中安装，否则 Agent 执行脚本会报 command not found，然后回退用 curl 手动调 API，效率低且输出不理想。