Skill

核心功能

InvestorClaw 是一个确定性优先（deterministic-first）的本地投资组合分析工具，通过 Docker 容器运行，提供 20 个 MCP 工具/REST 端点，覆盖持仓分析、绩效计算、债券分析、行业分布、再平衡优化等全流程。

主要能力：

• 持仓快照：自动识别 Schwab/Fidelity/Vanguard 等券商导出的 CSV/XLS/PDF 文件
• 绩效指标：Sharpe 比率、Sortino 比率、最大回撤、风险调整后收益
• 债券分析：久期计算、收益率曲线（FRED 数据）、债券阶梯结构
• 行业分布： sector breakdown、集中度分析
• 再平衡与优化：目标配置情景模拟、效率前沿
• 市场数据：实时报价、分析师评级、持仓相关新闻

使用模式：
用户通过自然语言提问（如"我的投资组合表现如何？"），portfolio_ask 工具自动路由至 ic-engine 执行确定性计算，再由配置的 LLM（默认 Together AI gemma-4-31B）将签名信封数据合成为叙事回答。

技术架构：

• 容器化部署（~600MB 镜像），绑定本地端口 18090（MCP+REST）和 18092（Web 仪表板）
• 数据完全本地：持仓文件、计算中间状态、API 密钥均不离开主机
• 仅用户问题和计算结果摘要发送至 LLM 提供商
• 支持多数据源回退：yfinance（免费）、Finnhub（60次/分钟）、Massive（付费，200+持仓必需）

显著优点

1. 隐私优先设计：所有原始持仓数据、账户信息、成本基础均保留在本地 Docker 卷，仅脱敏后的计算指标外出
2. 金融计算专业：内置债券久期、收益率曲线、Sortino 比率等专业指标，非通用 LLM 估算
3. 确定性输出：计算结果经 HMAC 签名，可验证非 LLM 虚构
4. 券商兼容广：支持主流美国券商导出格式，自动识别并清洗（去除账号/SSN）
5. 灵活的 LLM 选择：默认 Together AI（低成本 ~$0.0008/1K tokens），支持本地 Ollama、OpenAI 等替代
6. 状态持久化：升级时通过 portfolio_export/portfolio_import 迁移，API 密钥支持 scrypt+AES-256-GCM 加密备份

潜在缺点与局限

1. 冷启动耗时：200+ 持仓组合首次初始化需 5-15 分钟（yfinance 限速）；Massive 付费密钥可缓解
2. 部署门槛高：必须用户自行安装 Docker，预创建 portfolios/ 目录（权限敏感），对非技术用户不友好
3. 密钥依赖：叙事功能强制需要 TOGETHER_API_KEY 或等效 LLM 密钥，无密钥时仅返回 stub 目录
4. 数据源限制：免费层存在速率限制（Finnhub 60次/分钟、Alpha Vantage 25次/天），大组合需付费升级
5. 单用户架构：localhost 绑定设计，无多用户隔离，不适合团队共享
6. 维护复杂度：需自行管理 Docker 容器生命周期、监控初始化状态、处理版本升级

适合人群

• 隐私敏感型投资者：不愿将持仓数据上传至云端券商或第三方分析平台
• 技术能力较强的个人投资者：熟悉 Docker/命令行，能管理本地服务
• 专业级分析需求者：需要精确债券计算、风险指标，不满于券商 App 的基础图表
• 多券商账户整合用户：需跨 Schwab/Fidelity/Vanguard 等统一视图
• 合规/审计场景：需要 HMAC 签名的可验证计算结果

常规风险

1. 配置错误风险：未预创建 portfolios/ 目录导致权限失败，容器进入 init_state=failed
2. 数据过期风险：缓存 TTL 60秒（新闻30秒），快速波动市场下数据可能滞后，需显式调用 portfolio_refresh
3. API 密钥泄露风险：keys.env 以 0600 模式存储，但备份文件若 passphrase 薄弱可被暴力破解
4. 依赖服务中断：yfinance/FRED 等免费服务变更接口可能导致数据获取失败
5. 升级中断风险：跨主机迁移时需手动处理加密备份，操作不当导致密钥丢失
6. 误读风险：叙事由 LLM 生成，虽有签名信封验证，但用户可能混淆"计算正确"与"投资建议"（明确声明仅教育用途）

核心用法

InvestorClaw 是一款面向个人投资者和财务顾问的本地化投资组合分析技能。用户通过 Docker Compose 一键部署后，将券商导出的持仓文件（CSV/XLS/PDF）放入指定目录，即可通过自然语言对话获取专业级分析。核心入口为 portfolio_ask 工具，支持"我的组合表现如何""帮我优化 60/40 配置"等任意问题。引擎采用确定性优先架构：所有数值计算在本地 Python 环境中完成，生成 HMAC 签名的结构化数据信封，再由配置的 LLM 合成自然语言叙事，确保数字可追溯、不可编造。

系统包含 20 个 MCP 工具，覆盖初始化状态轮询、持仓快照、数据刷新、API 密钥管理、响应历史审计等全流程。容器默认自动初始化（IC_INITIALIZE_ON_BOOT=1），200 标的组合冷启动约 60-200 秒，后续查询秒级响应。支持多种安装方式：ClawHub 一键安装、Claude Code 插件、或手动 Docker Compose。

显著优点

隐私优先的本地架构：所有持仓数据、成本 basis、账户信息均保留在本地 Docker 卷，不上传至任何云服务。PII 在导入时即脱敏处理，仅向 LLM 提供商发送计算后的指标摘要，符合 GDPR 数据最小化原则。

金融级确定性计算：基于 FINOS CDM 5.x 合规的 ic-engine 核心，支持夏普比率、索提诺比率、债券久期与到期收益率、FRED 收益率曲线、行业配置热力图、再平衡情景模拟等专业指标。计算结果经 HMAC 签名，可审计验证。

灵活的多源数据整合：内置 yfinance、Frankfurter（欧洲央行汇率）、Treasury Fiscal Data 等免费源，同时支持 Finnhub、Massive、Alpha Vantage、NewsAPI 等付费/免费 API 的分层配置。大型组合（200+ 标的）推荐配置 Massive 避免雅虎速率限制。

完善的密钥生命周期：API 密钥通过 REST/MCP 端点管理，持久化至 mode 0600 文件，支持 scrypt+AES-256-GCM 加密备份与跨主机迁移。无需重启即可热更新配置。

成本优化的模型路由：默认采用 Together AI Gemma-4-31B（$0.0008/1K tokens）处理叙事合成，支持本地 Ollama 离线运行，也可对接 Claude Code 实现零额外成本的双模型验证架构（Haiku 叙事 + Sonnet 校验）。

潜在缺点与局限性

部署复杂度高于纯 SaaS：需本地 Docker 环境，首次拉取 ~600MB 镜像，对非技术用户存在门槛。Windows 用户需配置 WSL2 后端，ARM 架构虽支持但性能略逊于 x86。

冷启动延迟明显：大型组合首次初始化需 5-15 分钟（受限于外部 API 速率），虽可通过 IC_INITIALIZE_ON_BOOT 预加载缓解，但仍显著慢于云端实时服务。

外部 API 依赖导致不稳定：免费层 yfinance 存在匿名查询全局速率限制，200+ 标的同时刷新易触发 HTTP 429。无付费密钥时，新闻数据 TTL 仅 30 秒，高频查询易 stale。

叙事质量依赖 LLM 配置：无 TOGETHER_API_KEY 时降级为 stub 目录摘要，失去自然语言交互价值。本地 Ollama 需 16GB+ 显存支撑 Gemma-4-31B 流畅推理。

功能边界明确为分析型：不支持交易执行、不连接券商 API、不提供投资建议，仅输出教育性分析。需要实际下单的用户需另行操作。

适合的目标群体

• 高净值个人投资者：持仓复杂（债券、多账户、多币种），需离线聚合分析且重视隐私
• 独立理财顾问（RIAs）：需为客户生成合规的持仓报告，保留本地审计痕迹
• 量化研究员与金融工程学生：需可复现、可验证的指标计算管道，用于策略回测验证
• 企业财务与司库团队：管理员工持股计划或企业年金组合，需内部部署满足 IT 安全政策
• 隐私敏感型技术用户：拒绝将完整持仓上传至 Betterment、Personal Capital 等云端理财工具

常规风险

性能风险：子进程超时 1800s、P1 并行阶段超时 600s，超大规模组合或网络抖动可能导致查询失败。建议监控 portfolio_initialize_status 流式端点掌握进度。

依赖项风险：容器绑定特定 Python/ic-engine 版本，升级需替换整镜像。compose down -v 会清空加密卷，务必先执行 portfolio_keys_backup。

密钥泄露风险：keys.env 虽权限严格，但宿主机 root 仍可读取。共享机器建议启用加密备份机制，避免明文密钥留存。

数据新鲜度风险：默认缓存 TTL 60s（新闻 30s），快速市场波动期间可能返回过期数据。用户需显式请求"refresh"或配置更激进的刷新策略。

模型幻觉风险：尽管引擎计算确定，但 LLM 叙事仍可能误述百分比或混淆指标定义。建议高 stakes 场景启用 Claude Code 的验证器模式交叉检查。

许可证合规风险：引擎 Apache 2.0 + 分发件 MIT-0 允许自由商用，但金融数据提供商 API 有各自 ToS 限制，需确认自用/商用场景下的数据使用授权。