> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.alephant.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server.

# 使用指南与提示词

> 通过自然语言、工具模板和内置提示词使用 Alephant MCP

## 交互原则

要求 AI 助手使用 Alephant MCP 时：

1. **说明范围**：当前虚拟密钥、整个工作区、部门 UUID、代理 UUID 或成员 UUID。
2. **说明时间窗口**：共享使用量工具可使用 `24h`、`7d`、`30d` 或 `billing_cycle`；部分 Manager 分析还支持 `3m`、`6m` 和 `12m`。
3. **要求对实时数据使用工具**：请说“使用已启用的 Alephant MCP 工具；不要猜测。”
4. **明确确认写入操作**：创建密钥、更新预算、撤销密钥和设置预算策略均为 Manager 模式的写入操作。

## 自然语言示例

| 意图     | 示例                                 |
| ------ | ---------------------------------- |
| 使用量汇总  | “使用 Alephant MCP 展示当前计费周期的使用量汇总。”  |
| 每日趋势   | “使用 Alephant MCP 展示最近 7 天的每日成本趋势。” |
| 模型成本   | “使用 Alephant MCP 按模型拆分最近 30 天的支出。” |
| VK 范围  | “使用 Alephant MCP 告诉我虚拟密钥绑定到什么范围。”  |
| VK 预算  | “使用 Alephant MCP 展示本计费周期还剩多少预算。”   |
| 工作区仪表盘 | “使用 Alephant MCP 为工作区构建管理层仪表盘。”    |
| 成本异常   | “使用 Alephant MCP 诊断最近 30 天的成本异常。”  |
| 空闲资源   | “使用 Alephant MCP 查找空闲的虚拟密钥和代理。”    |
| 密钥管理   | “使用 Alephant MCP 列出所有虚拟密钥和预算。”     |
| 审计     | “运行 Alephant 本周的成本审计报告。”           |

## 命令模板

MCP 协议不会在聊天框中注册斜杠命令。这些模板是建议发送给助手的文本前缀。

### 共享工具

| 模板                                                                      | 常用工具                                           |
| ----------------------------------------------------------------------- | ---------------------------------------------- |
| `/alephant-usage Show usage summary for this billing cycle`             | `get_usage_summary`，参数为 `period=billing_cycle` |
| `/alephant-usage Total consumption and daily trend for the last 7 days` | `get_usage_summary`, `get_daily_costs`         |
| `/alephant-usage Cost by model for the last 30 days`                    | `get_cost_by_model`                            |
| `/alephant-models List currently available models`                      | `list_available_models`                        |
| `/alephant-health Check the Alephant connection`                        | `check_alephant_connection`                    |

### VK 模式

| 模板                                                            | 工具                       |
| ------------------------------------------------------------- | ------------------------ |
| `/alephant-vk What is the scope bound to my current key`      | `get_my_scope`           |
| `/alephant-vk How much budget is left for this billing cycle` | `get_my_budget`          |
| `/alephant-vk Show recent requests for this key`              | `get_my_recent_requests` |

### Manager 模式

| 模板                                                                                              | 常用工具                          |
| ----------------------------------------------------------------------------------------------- | ----------------------------- |
| `/alephant-mgr Workspace overview`                                                              | `get_workspace_overview`      |
| `/alephant-mgr Workspace budget status`                                                         | `get_workspace_budget_status` |
| `/alephant-mgr Real-time 24h dashboard`                                                         | `get_live_24h`                |
| `/alephant-mgr Usage time series for cost over 30 days`                                         | `get_usage_timeseries`        |
| `/alephant-mgr Seven-day sparkline trends`                                                      | `get_sparklines`              |
| `/alephant-mgr List all virtual keys and budgets`                                               | `list_virtual_keys`           |
| `/alephant-mgr Create a virtual key after I confirm label, master key, budget, and RPM`         | `create_virtual_key`          |
| `/alephant-mgr Update key [uuid] budget to [cents] and action [alert_only or block]`            | `update_key_budget`           |
| `/alephant-mgr Revoke key [uuid] after I confirm`                                               | `revoke_virtual_key`          |
| `/alephant-mgr List departments`                                                                | `list_departments`            |
| `/alephant-mgr Department [uuid] analytics for the last 30 days`                                | `get_department_analytics`    |
| `/alephant-mgr List agents`                                                                     | `list_agents`                 |
| `/alephant-mgr Agent [uuid] analytics for the last 7 days`                                      | `get_agent_analytics`         |
| `/alephant-mgr List members`                                                                    | `list_members`                |
| `/alephant-mgr Member [uuid] analytics for the last 30 days`                                    | `get_member_analytics`        |
| `/alephant-mgr Subscription and billing cycle info`                                             | `get_subscription_info`       |
| `/alephant-mgr Set workspace budget policy to [amount] cents with action [alert_only or block]` | `set_budget_policy`           |
| `/alephant-mgr Diagnose cost anomalies for the last 30 days`                                    | `diagnose_cost_anomaly`       |
| `/alephant-mgr Build executive dashboard`                                                       | `get_executive_dashboard`     |
| `/alephant-mgr Drill down workspace spend by department`                                        | `drill_down_spend`            |
| `/alephant-mgr Find idle keys and agents`                                                       | `find_idle_resources`         |
| `/alephant-mgr Compare [department, agent, or member] [uuid] current vs previous 30 days`       | `compare_entity_periods`      |

## 内置提示词

| 提示词                      | 模式           | 参数                 | 说明          |                             |                                  |                                      |
| ------------------------ | ------------ | ------------------ | ----------- | --------------------------- | -------------------------------- | ------------------------------------ |
| `cost_audit_report`      | VK + Manager | \`period=weekly    | monthly     | quarterly\`                 | 生成包含发现、明细、风险和建议的结构化 Markdown 审计。 |                                      |
| `cost_optimization`      | Manager      | \`focus=models     | departments | agents                      | general\`                        | 使用仪表盘、异常、下钻、比较、空闲资源和预算工具生成按优先级排列的建议。 |
| `workspace_health_check` | Manager      | \`urgency=quick    | thorough\`  | 根据紧急程度检查实时健康度、趋势、异常、成功率和延迟。 |                                  |                                      |
| `cost_deep_dive`         | Manager      | \`target=workspace | department  | agent`，可选 `target\_id\`     | 调查工作区、部门或代理支出的根因和影响。             |                                      |

示例请求：

> 使用 Alephant MCP 提示词 `cost_audit_report` 并设置 `period=weekly`。不要假定工具未返回的数据。

## 说明

* `get_usage_summary` 将 `total_tokens.input` 作为提示词/输入 token 返回，将 `total_tokens.output` 作为补全/输出 token 返回。
* 适用时，`get_cost_by_model` 会筛选为当前 VK 绑定的代理/成员范围；未绑定的密钥使用工作区范围。
* `get_my_recent_requests` 返回包含 `tokens_in`、`tokens_out`、`status`、`latency_ms` 和 `created_at` 的实时行。`degraded=true` 表示后端、Collector 或所请求范围无法提供实时行。
* 这些仅为响应行为澄清；MCP 工具架构保持不变。
* 此 MCP 构建中不提供 `get_request_logs`。
* Manager 复合工具可能调用多个 Alephant API 端点，并在某一步失败时返回部分元数据。
* 对于持久化仪表盘或图表，请在 MCP 工具识别出相关范围和时间窗口后使用 Alephant Cockpit UI。