财务报表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://api.yk-global.com/v1/verify
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`)

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://api.yk-global.com/v1/verify |

错误处理

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

安全说明

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