SKILL.md
七牛云 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 |
仅消耗配额，可通过限额控制，风险可控 |
强制隔离原则：
- 业务代码只用模型调用 API Key（sk-xxx），绝不使用 AK/SK
- AK/SK 只在服务端/脚本中使用，不得出现在客户端代码、版本控制系统或日志中
- 对外集成监控系统时，建议使用独立的只读专用 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 字段描述