Financial Report AI

SKILL.md

---
name: financial-report-ai-pro
description: "财务报表AI解读 — 上传 Excel/CSV/PDF 财务报表，AI 自动生成经营分析报告（收入结构/成本异常/利润/现金流/资产负债/KPI/异常预警）。支持 Free/Standard/Pro/Max 套餐体系，Token 验证接入 geo-api.yk-global.com/validate。触发词：财务报表、财务分析、报表解读、利润表、资产负债表、现金流量表"
---

# 财务报表AI解读 (financial-report-ai-pro)

上传 Excel/CSV/PDF 财务报表 → AI 自动解读数据 → 生成经营分析报告。

## 架构概览

```
用户上传文件
    ↓
index.js (入口，路由分发)
    ↓
src/handlers/
  ├── skill_invoke.js    ← 核心分析引擎调度
  ├── file_upload.js     ← 文件上传处理
  └── message_handler.js ← 文本对话处理
    ↓
src/services/
  ├── token_validator.js   ← Token 验证 + 5分钟缓存
  ├── file_parser.py        ← Excel/CSV/PDF 解析
  └── report_generator.py   ← AI 分析 + Markdown 渲染
```

## Token 验证

- **Endpoint**: `POST https://geo-api.yk-global.com/validate`
- **Header**: `Authorization: Bearer {api_key}`
- **Body**: `{}`
- **响应**: `{ valid: boolean, plan: string }`
- **降级策略**: 网络错误 → FREE tier，不阻断使用
- **缓存**: 验证结果本地 SHA256 哈希缓存，TTL 5 分钟

## 套餐体系

| 套餐 | 价格 | 次数 | 分析维度 | 图表 | 格式 |
|------|------|------|---------|------|------|
| Free | 免费 | 3次/月 | 基础3项 | ❌ | CSV/Excel |
| Standard | ¥29/月 | 50次/月 | 10项 | 5种 | CSV/Excel/PDF |
| Pro | ¥99/月 | 300次/月 | 全部 | 15种 | 全部 |
| Max | ¥299/月 | 无限 | 全部 | 全部 | 全部 |

## 核心功能实现

### 1. 文件解析 (`file_parser.py`)

- **CSV**: `pandas.read_csv`，dtype=str，fillna=""
- **Excel**: `pd.ExcelFile`，自动检测所有 sheet
- **PDF**: `pdfplumber`，提取文本+表格
- 返回: `{ headers, rows, shape, raw_sample }`

### 2. AI 分析 (`report_generator.py`)

- **Prompt 模板**: 7维度结构化分析
- **调用方式**: OpenAI-compatible API (Bearer token)，不绑定特定 provider
- **降级**: 无 API Key 或调用失败 → 基础数据报告
- **输出**: JSON (analysis) + Markdown (markdown_report)

### 3. Token 验证 (`token_validator.js`)

```javascript
validateToken(apiKey) → { valid: bool, plan: string, features: {} }
getPlanLimits(plan)   → { monthly, formats, dimensions, charts }
```

## 分析维度

| # | 维度 | Free | Standard | Pro | Max |
|---|------|------|----------|-----|-----|
| 1 | 收入结构分析 | ✅ | ✅ | ✅ | ✅ |
| 2 | 成本异常检测 | ✅ | ✅ | ✅ | ✅ |
| 3 | 利润分析 | ✅ | ✅ | ✅ | ✅ |
| 4 | 现金流分析 | ❌ | ✅ | ✅ | ✅ |
| 5 | 资产负债分析 | ❌ | ✅ | ✅ | ✅ |
| 6 | KPI达成分析 | ❌ | ✅ | ✅ | ✅ |
| 7 | 异常预警 | ❌ | ✅ | ✅ | ✅ |

## AI 模型配置

用户自行配置 API Key，Skill 不绑定、不推荐、不限定具体模型。
推荐使用 OpenAI GPT-4o / Claude / DeepSeek 等支持 function calling 的模型。

支持的 Provider（通过模型名自动识别 endpoint）：
- OpenAI (`api.openai.com/v1`)
- DeepSeek (`api.deepseek.com/v1`)
- Anthropic (`api.anthropic.com/v1`) — 使用 Anthropic API 格式
- 阿里通义 (`dashscope.aliyuncs.com`)
- MiniMax (`api.minimax.chat/v1`)

## 输出格式

**Markdown 报告**包含：
- 收入结构分析表
- 成本异常检测结果
- 利润分析指标
- 现金流分析
- 资产负债结构
- KPI达成情况
- 🔴🟠🟡 三级异常预警
- 整体经营评价

## 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `OPENCLAW_SKILL_DIR` | Skill 根目录（用于 token 缓存） | `__dirname/..` |
| `VALIDATE_ENDPOINT` | Token 验证 URL | `https://geo-api.yk-global.com/validate` |

## 错误处理

- 文件格式不支持 → 明确提示支持的格式列表
- 文件解析失败 → 返回具体解析错误行/原因
- AI API 错误 → 降级到基础报告，不阻断用户
- Token 无效/过期 → 降级到 FREE tier

## 安全说明

- Token 验证使用 SHA256 哈希缓存，不存储原始 Key
- 所有文件处理后即时清理，不持久化
- AI 分析在用户本地执行，无数据传输