feat: 新增 AI 指标报告助手与配置健康检查功能
- 新增 `ai-metrics-report` 技能,自动生成 AI 成功率、错误率与 Token 成本的综合报告,帮助评估智能助手表现。 - 新增 `config-audit` 技能,检查当前环境配置的完整性与可用性,输出健康检查报告,确保系统稳定运行。 - 相关脚本已实现,支持从项目根目录执行并输出结构化结果。
This commit is contained in:
92
.claude/skills/ai-metrics-report/SKILL.md
Normal file
92
.claude/skills/ai-metrics-report/SKILL.md
Normal file
@@ -0,0 +1,92 @@
|
||||
---
|
||||
Name: ai-metrics-report
|
||||
Description: 基于现有监控与分析模块,生成一份最近一段时间的 AI 成功率、错误率与 Token 成本的综合报告,用于评估 TSP 智能助手的整体表现。
|
||||
---
|
||||
|
||||
你是一个「AI 指标报告助手」,技能名为 **ai-metrics-report**。
|
||||
|
||||
你的职责:当用户希望了解一段时间内 AI 助手的表现(成功率、错误率、响应时间、Token 成本等)时,自动调用配套脚本,基于现有监控与分析模块,生成一份面向运营/技术同学都能看懂的综合报告。
|
||||
|
||||
---
|
||||
|
||||
## 一、触发条件(什么时候使用 ai-metrics-report)
|
||||
|
||||
当用户有类似需求时,应激活本 Skill,例如:
|
||||
|
||||
- 「帮我出一份最近 7 天 AI 调用表现的报告」
|
||||
- 「看一下最近 AI 的成功率和错误率」
|
||||
- 「近一周 Token 消耗和成本情况如何」
|
||||
- 「AI 现在效果怎么样,有没有明显波动」
|
||||
|
||||
---
|
||||
|
||||
## 二、总体流程
|
||||
|
||||
1. 从项目根目录执行脚本 `scripts/ai_metrics_report.py`;
|
||||
2. 读取脚本输出的结构化指标数据(JSON 或结构化文本);
|
||||
3. 将关键指标用自然语言转述,并做简要分析(例如是否达标、是否有波动);
|
||||
4. 如发现明显异常(高错误率 / 成本突增 / 成功率显著下降),给出 1~3 条排查或优化建议。
|
||||
|
||||
---
|
||||
|
||||
## 三、脚本调用规范
|
||||
|
||||
从项目根目录执行命令(可传入天数参数,默认 7 天):
|
||||
|
||||
```bash
|
||||
python .claude/skills/ai-metrics-report/scripts/ai_metrics_report.py --days 7
|
||||
```
|
||||
|
||||
脚本行为约定:
|
||||
|
||||
- 尝试复用现有模块:
|
||||
- `src.analytics.ai_success_monitor.AISuccessMonitor`(如提供聚合接口则优先使用);
|
||||
- `src.analytics.token_monitor.TokenMonitor.get_system_token_stats(days=...)`。
|
||||
- 至少输出以下信息(以 JSON 或清晰的文本格式打印到 stdout):
|
||||
- 时间范围(例如「最近 7 天」)
|
||||
- 会话类指标:
|
||||
- 总调用次数、成功调用次数、失败调用次数
|
||||
- 成功率、平均响应时间
|
||||
- Token/成本指标:
|
||||
- 总 Token 数
|
||||
- 总成本
|
||||
- 按模型维度的请求数占比(如 `qwen-plus-latest` 等)
|
||||
- 简单趋势:
|
||||
- 按天的调用次数与成本(可选)
|
||||
|
||||
你需要:
|
||||
|
||||
1. 运行脚本并捕获输出;
|
||||
2. 解析其中关键字段;
|
||||
3. 用 5~10 句中文自然语言,对用户生成一份「运营视角」的口头报告。
|
||||
|
||||
---
|
||||
|
||||
## 四、对用户的输出规范
|
||||
|
||||
当成功执行 `ai-metrics-report` 时,应返回如下结构的信息:
|
||||
|
||||
1. **时间范围与总体结论**
|
||||
- 例如:「最近 7 天,AI 总调用 1234 次,成功率约 96%,整体表现稳定。」
|
||||
2. **关键指标分项**
|
||||
- 成功率 / 错误率、平均响应时间;
|
||||
- 总 Token 使用量与总成本;
|
||||
- 主力模型(如 `qwen-plus-latest`)的占比;
|
||||
3. **趋势与风险提醒**
|
||||
- 若发现某几天错误率或成本异常升高,应指出并提醒。
|
||||
4. **建议(可选)**
|
||||
- 如「可以考虑优化 prompt 降低平均 Token」「错误集中在某业务接口,建议重点排查」等。
|
||||
|
||||
避免:
|
||||
|
||||
- 直接把原始 JSON 或 Python repr 整段贴给用户;
|
||||
- 输出过多技术细节,优先用业务/运营语言阐述。
|
||||
|
||||
---
|
||||
|
||||
## 五、反模式与边界
|
||||
|
||||
- 如脚本运行失败,应告诉用户「ai-metrics-report 脚本运行失败」,简要给出错误原因;
|
||||
- 不要直接访问数据库执行复杂 SQL,优先复用已有封装好的监控/统计接口;
|
||||
- 不要修改任何生产配置或监控阈值,仅进行只读分析和报告。
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
#!/usr/bin/env python
|
||||
# -*- coding: utf-8 -*-
|
||||
"""
|
||||
AI 指标报告脚本
|
||||
|
||||
聚合最近一段时间的 AI 使用与成本指标,供 ai-metrics-report Skill 调用。
|
||||
当前版本主要复用 TokenMonitor 的系统统计能力。
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def add_project_root_to_path():
|
||||
# 假定脚本位于 .claude/skills/ai-metrics-report/scripts/ 下
|
||||
script_path = Path(__file__).resolve()
|
||||
project_root = script_path.parents[4]
|
||||
if str(project_root) not in sys.path:
|
||||
sys.path.insert(0, str(project_root))
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Generate AI metrics report.")
|
||||
parser.add_argument(
|
||||
"--days",
|
||||
type=int,
|
||||
default=7,
|
||||
help="Number of days to include in the report (default: 7).",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
add_project_root_to_path()
|
||||
|
||||
from src.analytics.token_monitor import TokenMonitor
|
||||
|
||||
monitor = TokenMonitor()
|
||||
stats = monitor.get_system_token_stats(days=args.days) or {}
|
||||
|
||||
print(f"=== AI 指标报告(最近 {args.days} 天) ===\n")
|
||||
|
||||
total_tokens = stats.get("total_tokens", 0)
|
||||
total_cost = stats.get("total_cost", 0.0)
|
||||
total_requests = stats.get("total_requests", 0)
|
||||
successful_requests = stats.get("successful_requests", 0)
|
||||
failed_requests = stats.get("failed_requests", 0)
|
||||
success_rate = stats.get("success_rate", 0)
|
||||
|
||||
print("整体概览:")
|
||||
print(f" 总请求数 : {total_requests}")
|
||||
print(f" 成功请求数 : {successful_requests}")
|
||||
print(f" 失败请求数 : {failed_requests}")
|
||||
print(f" 成功率 : {success_rate:.2%}" if total_requests else " 成功率 : N/A")
|
||||
print(f" 总 Token 数量 : {total_tokens}")
|
||||
print(f" 总成本(估算) : {total_cost:.4f} 元")
|
||||
print()
|
||||
|
||||
# 模型使用分布
|
||||
model_usage = stats.get("model_usage", {})
|
||||
if model_usage:
|
||||
print("按模型维度的请求分布:")
|
||||
for model_name, count in model_usage.items():
|
||||
pct = (count / total_requests) * 100 if total_requests else 0
|
||||
print(f" - {model_name}: {count} 次 ({pct:.1f}%)")
|
||||
print()
|
||||
|
||||
# 按日期的成本趋势(如有)
|
||||
daily_usage = stats.get("daily_usage", {})
|
||||
if daily_usage:
|
||||
print("按日期的 Token 与成本(近几天):")
|
||||
# daily_usage: {date_str: {"tokens": ..., "cost": ...}}
|
||||
for date_str in sorted(daily_usage.keys()):
|
||||
day_data = daily_usage[date_str]
|
||||
tokens = day_data.get("tokens", 0)
|
||||
cost = day_data.get("cost", 0.0)
|
||||
print(f" {date_str}: tokens={tokens}, cost={cost:.4f} 元")
|
||||
print()
|
||||
|
||||
print("提示:")
|
||||
print(" - 成本与成功率仅基于 TokenMonitor 收集的调用记录进行估算;")
|
||||
print(" - 如需更细粒度的会话质量指标,可结合 analytics 模块或自定义报表。")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
|
||||
Reference in New Issue
Block a user