tracking-crypto-portfolio

加密货币投资组合追踪

概述

此技能提供全面的加密货币投资组合追踪功能，包括：

• 实时估值：CoinGecko 提供的当前价格
• 持仓明细：每种资产的数量、价值和配置比例
• 盈亏追踪：根据成本基础计算未实现盈亏
• 配置分析：类别明细和集中度提示
• 多种导出格式：表格、JSON、CSV

主要功能：

• 追踪多种资产的持仓
• 计算投资组合的美元总价值
• 识别超配仓位（集中度风险）
• 导出数据，供分析工具和报税使用

先决条件

使用此技能前，请确保：

1. 已安装 Python 3.8+
2. 可使用 requests 库：pip install requests
3. 可连接互联网，以访问 CoinGecko API
4. 已准备好包含持仓的投资组合 JSON 文件

投资组合文件格式

创建一个投资组合文件（例如，holdings.json）：

{
  "name": "My Portfolio",
  "holdings": [
    {"coin": "BTC", "quantity": 0.5, "cost_basis": 25000},
    {"coin": "ETH", "quantity": 10, "cost_basis": 2000},
    {"coin": "SOL", "quantity": 100}
  ]
}

字段：

• coin：代币符号（BTC、ETH 等）——必填
• quantity：持有数量——必填
• cost_basis：每枚代币的平均买入价（可选，用于计算盈亏）
• acquired：购入日期（可选，用于记录）

使用说明

步骤 1：判断用户意图

确定用户需要哪类投资组合信息：

• 快速查看：总价值和主要持仓
• 持仓列表：所有仓位的完整明细
• 详细分析：配置比例、盈亏和风险提示
• 导出：用于外部工具的 JSON 或 CSV

步骤 2：执行投资组合追踪

使用相应选项运行追踪器：

# Quick portfolio summary
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json

# Full holdings breakdown
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --holdings

# Detailed analysis with P&L and allocations
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --detailed

# Export to JSON
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format json --output portfolio_export.json

# Export to CSV
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format csv --output portfolio.csv

步骤 3：呈现结果

整理并说明投资组合数据：

• 突出显示投资组合总价值
• 强调 24h 和 7d 的变化
• 说明配置比例
• 标记任何集中度风险
• 在详细模式下，说明盈亏计算方式

命令行选项

选项	说明	默认值
--portfolio	投资组合 JSON 文件的路径	必填
--holdings	显示所有持仓明细	false
--detailed	显示包含盈亏的完整分析	false
--sort	排序方式：value、allocation、name、change	value
--format	输出格式（table、json、csv）	table
--output	输出文件路径	stdout
--threshold	配置比例警告阈值	25%
--verbose	启用详细输出	false

配置比例阈值

默认情况下，配置比例 > 25% 的仓位会被标记：

配置比例	风险等级	操作
< 10%	低	正常仓位
10-25%	中	密切关注
25-50%	高	考虑重新平衡
> 50%	极高	存在显著的集中度风险

输出

表格格式（默认）

==============================================================================
  CRYPTO PORTFOLIO TRACKER                          Updated: 2026-01-14 15:30
==============================================================================

  PORTFOLIO SUMMARY: My Portfolio
------------------------------------------------------------------------------
  Total Value:    $125,450.00 USD
  24h Change:     +$2,540.50 (+2.07%)
  7d Change:      +$8,125.00 (+6.92%)
  Holdings:       8 assets

  TOP HOLDINGS
------------------------------------------------------------------------------
  Coin     Quantity      Price         Value      Alloc   24h
  BTC      0.500     $95,000.00   $47,500.00    37.9%   +2.5%
  ETH      10.000     $3,200.00   $32,000.00    25.5%   +1.8%
  SOL      100.000      $180.00   $18,000.00    14.4%   +4.2%

  ⚠ CONCENTRATION WARNING: BTC (37.9%) exceeds 25% threshold

==============================================================================

JSON 格式

{
  "portfolio_name": "My Portfolio",
  "total_value_usd": 125450.00,
  "change_24h": {"amount": 2540.50, "percent": 2.07},
  "holdings": [
    {
      "coin": "BTC",
      "quantity": 0.5,
      "price_usd": 95000,
      "value_usd": 47500,
      "allocation_pct": 37.9,
      "change_24h_pct": 2.5
    }
  ],
  "meta": {
    "timestamp": "2026-01-14T15:30:00Z",
    "holdings_count": 8
  }
}

错误处理

详见 {baseDir}/references/errors.md，了解完整的错误处理信息。

错误	原因	解决方案
未找到投资组合文件	路径无效	检查文件路径是否存在
JSON 无效	文件格式错误	验证 JSON 语法
未找到代币	未知符号	检查符号拼写，使用标准符号
API 请求受限	请求过多	等待后重试，或使用缓存

示例

详见 {baseDir}/references/examples.md，查看详细示例。

快速示例

# Basic portfolio check
python {baseDir}/scripts/portfolio_tracker.py --portfolio ~/crypto/holdings.json

# Show all holdings sorted by allocation
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --holdings --sort allocation

# Detailed analysis with 15% threshold
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --detailed --threshold 15

# Export for tax software
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format csv --output tax_export.csv

# JSON export for trading bot
python {baseDir}/scripts/portfolio_tracker.py --portfolio holdings.json --format json --output portfolio_data.json

资源

• CoinGecko API：https://www.coingecko.com/en/api —— 免费的加密货币市场数据
• 投资组合架构：完整的投资组合文件格式请参阅 PRD.md
• 配置：可用选项请参阅 {baseDir}/config/settings.yaml
• 集成示例请参阅 {baseDir}/references/examples.md