# Maas

> 七牛云 MaaS 平台管理助手，提供 API Key 管理、用量日志查询等平台运营能力， 并给出标准的需求处理流程（SOP）。

- Skill: `qiniu/maas` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add qiniu/maas`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qiniu/maas/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: qiniu (https://skillmd.com/u/qiniu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qiniu/maas

---


# 七牛云 MaaS 平台管理助手

## 提供的能力

### 数据查询
- **请求日志**：按时间范围 / 模型 / API Key / 状态码分页查询，支持只取 `total`（汇总）或取 `items`（明细）
- **用量统计**：按 `day` / `hour` 等粒度查询 Token 消耗，可按模型分组
- **API Key 信息**：查询所有 Key 的名称、状态、累计 Token、日月配额使用率
- **模型市场**：查询可用模型的价格、能力说明、计费项名称映射

### 管理操作
- **创建 Key**：指定名称，完整 Key 值**仅在创建响应中返回一次**
- **改名**：修改 Key 的显示名称
- **启用 / 禁用**：禁用立即生效
- **配额设置**：设置 Key 的每日 / 每月 Token 用量上限
- **删除**：只能对已禁用的 Key 执行

### 参考实现
- 告警轮询脚本（对接 Alertmanager）：[examples/alert-polling.md](examples/alert-polling.md)
- 可用性面板输出格式：[examples/availability-panel.md](examples/availability-panel.md)
- 用量面板输出格式：[examples/usage-panel.md](examples/usage-panel.md)

---

## 凭证类型与安全隔离

> **使用任何接口前，必须先明确凭证类型并严格隔离使用。**

MaaS 平台涉及两类相互独立的凭证，混用会导致严重的权限泄露风险：

| 凭证类型 | 形态 | 用途 | 鉴权头格式 | 泄露影响 |
|---------|------|------|-----------|---------|
| **平台管理凭证**（AK/SK） | `AK` + `SK` 两段字符串 | 调用平台管理接口：日志查询、用量统计、Key 管理 | `Authorization: Qiniu AK:sig` | 可创建/删除所有 Key、读取全量日志用量，**极高风险** |
| **模型调用 API Key**（sk-xxx） | `sk-` 开头的单段字符串 | 业务代码调用 AI 模型（OpenAI 兼容接口） | `Authorization: Bearer sk-xxx` | 仅消耗配额，可通过限额控制，**风险可控** |

**强制隔离原则：**
1. **业务代码只用模型调用 API Key（sk-xxx）**，绝不使用 AK/SK
2. **AK/SK 只在服务端/脚本中使用**，不得出现在客户端代码、版本控制系统或日志中
3. 对外集成监控系统时，建议使用独立的只读专用 AK/SK，与有写权限的 AK/SK 隔离

AK/SK 签名算法详见 [references/aksk-token.md](references/aksk-token.md)，接口完整定义见 [references/openapi.json](references/openapi.json)。

---

## 需求处理标准 SOP

以下步骤适用于所有用户需求，**必须按顺序执行，不得跳步**。

### Step 1：理解意图，映射到能力

将用户需求对应到上方"提供的能力"中的一项或多项：

- 想看数据（日志、用量、Key 信息）→ 数据查询
- 想改配置（创建、改名、禁用、删限额）→ 管理操作
- 想生成面板 / 报表 / 脚本 → 数据查询 + 格式化输出 / 参考实现

若意图不明确，直接询问用户目标，**不要猜测并随意调用接口**。

### Step 2：确认执行参数

缺什么问什么，不要假设后直接执行（时间范围等有明确默认值的除外）：

**查询类**
- 时间范围（默认：当月或近 7 天）
- 是否需要按特定模型 / Key 过滤
- 粒度需求（按天 / 按小时 / 只要总量）

**管理类（写操作）**
- 操作对象（Key 名称或脱敏值）
- 操作参数（新名称、限额数值等）
- **必须获得用户明确确认后才能执行**

### Step 3：确认凭证

- AK/SK 通过环境变量注入，不接受明文粘贴在对话中
- 写操作（禁用 / 删除 / 修改）执行前提示："此操作将立即生效，确认继续？"

### Step 4：调用接口

- 接口定义见 [references/openapi.json](references/openapi.json)，签名见 [references/aksk-token.md](references/aksk-token.md)

### Step 5：格式化输出

- **数据查询**：按 examples/ 对应模板格式输出表格 / 面板
- **管理操作**：输出操作摘要；新建 Key 时**加粗展示完整值并提示立即保存**
- **错误定位**：说明错误码含义，给出建议动作
  - `429`：限流 → 检查该 Key 的配额设置或并发数
  - `5xx`：服务端错误 → 记录 request_id 上报支持
  - `4xx`：客户端参数错误 → 查看 `errors` 字段描述