Topics

#ai-agent #akshare #china-stock-market #data-analysis #financial-analysis #financial-analysis-tools #python #stock-analysis-with-python

Language breakdown

No language data available.

▸ Files click to expand

README

Nexus财务智能体

基于 Yutu-Agent 框架构建的智能财务分析系统，专为A股市场设计。通过标准化工具库和智能缓存机制，提供稳定、高效的财务数据分析能力，彻底解决AI代码生成的错误和token消耗问题。

📦 Claude Skill 仓库: Nexus-caiwu-skill - 适配 Claude Code 的技能包，支持直接对话式财务分析

🌟 核心特性

🚀 零代码生成错误

标准化工具库：所有财务计算由预构建工具完成，AI无需编写计算代码
稳定可靠：经过充分测试的财务算法，确保计算准确性
错误率降低80%：从30-40%降至5-10%

💰 显著降低成本

Token消耗减少60-70%：从5000-8000降至1500-2500 tokens
分析速度提升50-60%：从45-60秒降至15-25秒
智能缓存：避免重复数据获取，自动检测新财报

📊 完整分析能力

财务比率计算：盈利能力、偿债能力、运营效率、成长能力
趋势分析：多年趋势分析、CAGR计算、增长率分析
健康评估：综合评分、风险等级、投资建议
自动报告：HTML格式专业分析报告

🎯 解决的核心问题

传统AI财务分析的痛点

❌ AI生成代码错误率高（30-40%）
❌ Token消耗巨大（5000-8000）
❌ 分析结果不一致
❌ 依赖复杂的数据处理代码

我们的解决方案

✅ 专用数据获取工具：稳定获取AKShare财务数据
✅ 标准化分析工具库：零代码生成的财务计算
✅ 智能Agent分工：数据获取→分析计算→结果解读
✅ 完整质量保证：缓存机制、错误处理、性能优化

🚀 快速开始

环境配置

# 克隆项目
git clone https://github.com/hhhh124hhhh/Nexus-caiwu-agent
cd Nexus-caiwu-agent
安装依赖
uv sync --all-extras --all-packages --group dev
激活虚拟环境
Linux/macOS:
source ./.venv/bin/activate
Windows:
.\.venv\Scripts\activate
设置环境变量（参考 .env.example）
Linux/macOS:
export UTULLMTYPE="yourllmtype"
export UTULLMMODEL="your_model"
export UTULLMAPIKEY="yourapi_key"
export UTULLMBASEURL="yourbase_url"
Windows:
set UTULLMTYPE=yourllmtype
set UTULLMMODEL=your_model
set UTULLMAPIKEY=yourapi_key
set UTULLMBASEURL=yourbase_url

运行智能分析

# 进入示例目录
cd examples/stock_analysis
启动财务分析智能体（支持流式输出）【适合深度分析】
python main.py --stream
或者使用uv运行chat模式（快速模式）【适合快速分析】
uv run scripts/clichat.py --stream --configname agents/examples/stockanalysisfinal
启动Web模式
uv run examples/stockanalysis/mainweb.py
选择分析任务或输入自定义需求
例如：分析陕西建工(600248.SH)最新财报数据

📁 项目架构

Nexus-caiwu-agent/
├── utu/
│   ├── tools/
│   │   ├── aksharefinancialtool.py          # AKShare数据获取工具（智能缓存）
│   │   ├── financialanalysistoolkit.py      # 标准化财务分析工具库
│   │   └── enhancedpythonexecutor_toolkit.py # 增强代码执行器
│   └── agents/
├── configs/
│   ├── agents/examples/
│   │   └── stock_analysis.yaml                 # 智能体配置（标准化工具）
│   └── tools/
│       ├── aksharefinancialdata.yaml        # 数据获取工具配置
│       └── financial_analysis.yaml            # 财务分析工具配置
├── examples/
│   └── stock_analysis/
│       ├── main.py                             # 主程序入口（支持流式输出）
│       ├── stockanalysisexamples.json         # 分析任务示例
│       ├── teststandardizedanalysis.py       # 集成测试
│       └── STANDARDIZEDANALYSISGUIDE.md     # 详细使用指南
└── README.md

🛠️ 核心组件

1. 数据获取层：AKShareFinancialDataTool

位置：utu/tools/aksharefinancialtool.py

from utu.tools.aksharefinancialtool import getfinancialreports
获取完整财务报表（带智能缓存）
financialdata = getfinancial_reports("600248", "陕西建工")
返回：{'income': 利润表, 'balance': 资产负债表, 'cashflow': 现金流量表}
获取关键指标
metrics = getkeymetrics(financial_data)
获取趋势数据
trend = gethistoricaltrend(financial_data)

核心特性：

🔄 智能缓存：同一家公司数据只获取一次
🆕 增量更新：自动检测新财报并更新缓存
🛡️ 错误处理：多重备用机制确保数据获取成功
⚡ 高性能：缓存命中时毫秒级响应

2. 分析计算层：StandardFinancialAnalyzer

位置：utu/tools/financialanalysistoolkit.py

from utu.tools.financialanalysistoolkit import (
    calculate_ratios, 
    analyze_trends, 
    assess_health, 
    generate_report
)
计算财务比率（零代码生成）
ratios = calculateratios(financialdata)
返回：{'profitability': {...}, 'solvency': {...}, 'efficiency': {...}, 'growth': {...}}
分析趋势
trends = analyzetrends(financialdata, 4)
返回：{'revenue': {...}, 'profit': {...}, 'growth_rates': {...}}
评估健康
health = assess_health(ratios, trends)
返回：{'overallscore': 85.2, 'risklevel': '低风险', 'recommendations': [...]}
生成完整报告
report = generatereport(financialdata, "陕西建工")

核心功能：

📊 全面比率计算：盈利能力、偿债能力、运营效率、成长能力
📈 智能趋势分析：CAGR计算、趋势方向判断、波动率分析
🏥 健康评估系统：综合评分、风险等级、个性化建议
📄 自动报告生成：HTML格式、专业术语、投资建议

3. 智能体系统

Agent分工设计

DataAgent (数据获取专家)
    ↓ 专用AKShare工具
DataAnalysisAgent (数据分析专家) 
    ↓ 标准化分析工具
FinancialAnalysisAgent (财务分析专家)
    ↓ 深度解读
ChartGeneratorAgent & ReportAgent
    ↓ 可视化和报告

核心优势

🎯 职责明确：每个Agent专注自己的专业领域
🔄 标准化流程：避免AI代码生成的不确定性
📊 结果一致：稳定的算法确保输出质量
💡 智能协作：Agent间无缝配合完成复杂分析

📈 分析能力详解

财务比率计算

# 盈利能力
{
    'grossprofitmargin': 25.6,    # 毛利率
    'netprofitmargin': 8.2,      # 净利率  
    'roe': 12.4,                   # 净资产收益率
    'roa': 6.8                     # 总资产收益率
}
偿债能力
{
    'current_ratio': 1.5,           # 流动比率
    'debttoasset_ratio': 65.2     # 资产负债率
}
运营效率
{
    'asset_turnover': 0.8           # 总资产周转率
}
成长能力
{
    'revenue_growth': 15.3          # 营业收入增长率
}

趋势分析

{
    'revenue': {
        'years': 4,
        'cagr': 12.5,               # 复合年增长率
        'trend_direction': '上升',
        'latest_revenue': 150.2     # 最新营收（亿元）
    },
    'profit': {
        'years': 4,
        'cagr': 18.3,
        'trend_direction': '上升',
        'latest_profit': 12.8       # 最新利润（亿元）
    }
}

健康评估

{
    'overall_score': 78.5,          # 综合评分（0-100）
    'risk_level': '中等风险',        # 风险等级
    'strengths': [                   # 优势
        '盈利能力良好',
        '运营效率稳定'
    ],
    'weaknesses': [                  # 劣势
        '负债率偏高'
    ],
    'recommendations': [             # 建议
        '建议控制负债规模',
        '优化资产结构'
    ]
}

🔧 配置说明

智能体配置文件

位置：configs/agents/examples/stock_analysis.yaml

# 数据获取Agent
DataAgent:
  agent:
    instructions: |-
      你是专业的财务数据获取专家。使用专用的AKShare工具获取财报数据，不要生成Python代码。
      
      核心工具：
      - getfinancialreports: 获取完整财务报表
      - getkeymetrics: 提取关键财务指标
数据分析Agent  
DataAnalysisAgent:
  agent:
    instructions: |-
      财务数据分析专家。使用标准化分析工具进行财务分析，避免编写计算代码。
      
      核心工具：
      - calculate_ratios: 计算所有标准财务比率
      - analyze_trends: 分析财务数据趋势
      - assess_health: 评估财务健康状况

工具配置文件

位置：configs/tools/financial_analysis.yaml

# 分析参数设置
analysis_settings:
  trend_years: 4                    # 趋势分析年数
  industry_benchmarks:             # 行业基准
    construction: "construction"
    technology: "technology"
  
  # 财务健康评估权重
  health_weights:
    profitability: 0.3              # 盈利能力
    solvency: 0.3                   # 偿债能力
    efficiency: 0.2                 # 运营效率
    growth: 0.2                     # 成长能力

🧪 测试验证

集成测试

# 运行完整集成测试
cd examples/stock_analysis
python teststandardizedanalysis.py

测试覆盖：

✅ 工具集成测试
✅ 财务比率计算准确性
✅ 趋势分析功能完整性
✅ 健康评估算法可靠性
✅ 报告生成格式正确性
✅ 性能对比测试

性能基准

| 指标 | 传统方式 | 标准化工具 | 改善幅度 | |------|----------|------------|----------| | Token消耗 | 5000-8000 | 1500-2500 | -60~70% | | 错误率 | 30-40% | 5-10% | -80% | | 分析时间 | 45-60秒 | 15-25秒 | -50~60% | | 一致性 | 低 | 高 | 显著提升 |

📚 使用示例

基础使用

from utu.tools.aksharefinancialtool import getfinancialreports
from utu.tools.financialanalysistoolkit import generate_report
一键生成完整分析报告
report = generate_report(
    getfinancialreports("600248", "陕西建工"), 
    "陕西建工"
)
print(f"健康评分: {report['healthassessment']['overallscore']}") print(f"风险等级: {report['healthassessment']['risklevel']}")

批量分析

# 分析多只股票
stocks = [
    ("600248", "陕西建工"),
    ("600519", "贵州茅台"), 
    ("000858", "五粮液")
]
for code, name in stocks:     report = generatereport(getfinancial_reports(code, name), name)     print(f"{name}: {report['healthassessment']['risklevel']}")

自定义分析

# 深度财务分析
financialdata = getfinancial_reports("600248", "陕西建工")
计算特定指标
ratios = calculateratios(financialdata)
profitability = ratios['profitability']
分析趋势
trends = analyzetrends(financialdata, 5)
revenue_cagr = trends['revenue']['cagr']
评估健康状况
health = assess_health(ratios, trends)
recommendations = health['recommendations']

🔍 支持的市场

A股市场全覆盖

上海主板：600xxx, 601xxx, 602xxx, 603xxx, 605xxx
深圳主板：000xxx, 001xxx
创业板：300xxx
科创板：688xxx
北交所：8xxx, 43xxx

数据源

AKShare：主要数据源，提供全面的A股财务数据
智能缓存：本地缓存系统，支持增量更新
备用机制：多重数据源保障，确保分析连续性

🛡️ 质量保证

数据质量

✅ 数据清洗：自动处理缺失值和异常值
✅ 格式标准化：统一的数据格式和命名规范
✅ 验证机制：多重数据验证确保准确性

算法质量

✅ 标准化算法：经过验证的财务计算公式
✅ 行业基准：支持多行业基准对比
✅ 风险评估：科学的健康评估模型

系统质量

✅ 错误处理：完善的异常处理机制
✅ 性能优化：智能缓存和批量处理
✅ 日志监控：完整的操作日志和错误追踪

📖 详细文档

📚 标准化分析指南：详细使用说明
🔧 配置文件说明：完整的配置选项
🧪 测试用例：集成测试示例
💡 最佳实践：实际应用案例

🤝 技术支持

如果您在使用过程中遇到问题或有改进建议，请通过以下方式联系我们：

📧 Email: hhhh124hhhh@qq.com
🐛 Bug反馈: 请提供详细的错误日志和复现步骤
💡 功能建议: 欢迎提出新的分析需求或改进建议

📄 开源协议

本项目采用 MIT 协议开源，详见 LICENSE 文件。

🙏 致谢

AKShare - 优秀的金融数据源
Pandas - 数据处理利器
Matplotlib & Seaborn - 数据可视化

🎯 核心价值总结

传统AI财务分析 → 标准化工具财务分析

| 问题 | 解决方案 | 效果 | |------|----------|------| | 代码生成错误多 | 预构建标准化工具 | ✅ 错误率降低80% | | Token消耗巨大 | 避免代码生成 | ✅ 成本降低60-70% | | 分析不一致 | 统一算法标准 | ✅ 结果稳定性高 | | 处理速度慢 | 智能缓存优化 | ✅ 速度提升50-60% | | 依赖数据质量 | 多重数据验证 | ✅ 数据可靠性高 |

立即体验标准化财务分析的魅力！ 🚀

🔄 最新更新

📊 main.py 支持流式输出

在最新版本中，我们为 main.py 添加了流式输出功能，可以实时显示分析过程的详细执行步骤：

# 使用 --stream 参数启用流式输出
python main.py --stream
输出示例：
>> 计划阶段:
   分析: 需要分析陕西建工(600248.SH)的最新财报数据，包括财务比率、趋势分析和健康评估
   任务列表:
     1. 获取陕西建工的财务数据 (负责智能体: DataAgent)
     2. 分析财务数据 (负责智能体: DataAnalysisAgent)
     3. 生成最终报告 (负责智能体: FinancialAnalysisAgent)
>> 工作阶段 - 任务: 获取陕西建工的财务数据
   输出: 已成功获取陕西建工(600248.SH)的财务数据
>> 工作阶段 - 任务: 分析财务数据
   输出: 已完成财务数据分析，包括比率计算、趋势分析和健康评估
>> 报告阶段:
   最终报告: 陕西建工(600248.SH)的财务分析已完成...

💬 cli_chat.py 保持单一智能体模式

为了便于快速上下文切换，cli_chat.py 现在保持单一智能体模式，专注于提供简洁高效的交互体验：

# 使用单一智能体模式，支持快速上下文切换
uv run scripts/clichat.py --stream --configname agents/examples/stockanalysisfinal
输出示例：
财务分析智能体已启动，输入 'exit', 'quit' 或 'q' 退出。
请输入您的问题: 分析陕西建工的最新财报
>> 工具调用: getfinancialreports
>> 工具调用: calculate_ratios
>> 工具调用: analyze_trends
>> 工具调用: assess_health
分析完成，陕西建工的综合评分为78.5分，属于中等风险水平。
请输入您的问题: