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/availability-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/openapi.json。

---

需求处理标准 SOP

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

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

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

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

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

Step 2：确认执行参数

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

查询类

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

管理类（写操作）

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

Step 3：确认凭证

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

Step 4：调用接口

• 接口定义见 references/openapi.json，签名见 references/aksk-token.md

Step 5：格式化输出

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