portfolio-manager

投资组合管理器

概述

通过集成 Alpaca MCP Server 获取实时持仓数据，分析和管理投资组合，并进行全面分析，涵盖资产配置、分散化、风险指标、个别持仓评估和再平衡建议。生成包含可执行见解的详细投资组合报告。

完整的经纪账户分析通过 MCP 使用 Alpaca 的 API 获取实时投资组合数据。另有单独的有限版 CSV 配置审查，可离线使用；它不提供完整的经纪账户分析或工作流。

使用时机

当用户提出以下请求时，调用此技能：

• “分析我的投资组合”
• “审查我当前的持仓”
• “我的资产配置是什么？”
• “检查我的投资组合风险”
• “我应该重新平衡投资组合吗？”
• “评估我的持仓”
• “审查投资组合表现”
• “我应该买入或卖出哪些股票？”
• 任何涉及投资组合级别分析或管理的请求

前提条件

有限版离线 CSV 审查

若要在无需凭据的情况下审查本地 USD 股票持仓快照，请阅读 references/csv-holdings-review.md，并在指定明确的 数据源时间戳后运行 scripts/review_csv.py。使用随附的虚构 CSV 验证离线执行。 此操作仅生成总配置和各持仓的未实现盈亏；无法衡量账户敞口、杠杆或历史表现。请将个人 持仓和报告保留在本地。此有限模式下，不要获取经纪账户数据，也不要继续完整 工作流。导航器／工作流集成尚未发布。

Alpaca MCP Server 设置（完整经纪账户分析）

完整的经纪账户分析要求配置并连接 Alpaca MCP Server。MCP Server 可提供以下信息：

• 当前投资组合持仓
• 账户权益和购买力
• 历史持仓和交易
• 所持证券的市场数据

使用的 MCP Server 工具：

• get_account_info - 获取账户权益、购买力和现金余额
• get_positions - 获取所有当前持仓，包括数量、成本基础和市值
• get_portfolio_history - 获取历史投资组合表现数据
• 用于价格报价和基本面的市场数据工具

如果未连接 Alpaca MCP Server，请告知用户，并提供 references/alpaca-mcp-setup.md 中的设置说明。

REST 备用连接检查

从仓库根目录运行连接检查。请先使用模拟账户凭据； 切勿将凭据粘贴到报告中，也不要将其提交到仓库。

export ALPACA_API_KEY="<alpaca-key-id>"
export ALPACA_SECRET_KEY="<alpaca-secret-key>"
export ALPACA_PAPER="true"
uv run python skills/portfolio-manager/scripts/check_alpaca_connection.py

该命令会将已脱敏的诊断摘要写入标准输出，并且仅在账户和持仓端点均成功时 返回零。它不会创建报告文件或下单。

工作流

步骤 1：通过 Alpaca MCP 或 REST 备用方案获取投资组合数据

如果 Alpaca MCP Server 工具可用，请使用这些工具收集当前投资组合信息。在定时 Hermes 作业中，即使已提供 Alpaca 凭据，MCP 工具也可能不可用；遇到这种情况时，请使用 ALPACA_API_KEY、ALPACA_SECRET_KEY 和 ALPACA_PAPER 直接调用 Alpaca REST API。

1.1 获取账户信息：

Preferred: use mcp__alpaca__get_account_info to fetch:
- Account equity (total portfolio value)
- Cash balance
- Buying power
- Account status

Fallback REST endpoints:
- paper: https://paper-api.alpaca.markets/v2/account
- live:  https://api.alpaca.markets/v2/account
Headers:
- APCA-API-KEY-ID=$ALPACA_API_KEY
- APCA-API-SECRET-KEY=$ALPACA_SECRET_KEY

1.2 获取当前持仓：

Preferred: use mcp__alpaca__get_positions to fetch all holdings:
- Symbol ticker
- Quantity held
- Average entry price (cost basis)
- Current market price
- Current market value
- Unrealized P&L ($ and %)
- Position size as % of portfolio

Fallback REST endpoints:
- paper: https://paper-api.alpaca.markets/v2/positions
- live:  https://api.alpaca.markets/v2/positions

1.3 获取投资组合历史记录（可选）：

Preferred: use mcp__alpaca__get_portfolio_history for performance analysis:
- Historical equity values
- Time-weighted return calculation
- Drawdown analysis

Fallback REST endpoint:
- /v2/account/portfolio/history

定时作业备用方案规范：

• 明确标注数据来源为 Alpaca REST fallback，而非 MCP。
• 使用 ALPACA_PAPER=true 选择模拟交易端点；否则使用实盘端点。
• 仍需验证多头市值加现金大致等于账户权益；如果 long_market_value > equity，则突出说明保证金／杠杆情况。
• 对于每周核心投资组合定时任务，除了使用总市值作为分母，还要使用账户权益计算敞口：gross_long_exposure = long_market_value / equity、cash_pct = cash / equity；当总敞口明显高于 100% 或现金为负时，明确标记为保证金融资的投资组合。当账户存在杠杆时，不要仅使用多头总敞口作为分母，以免行业权重看起来无异常。
• 当请求强调股息持仓或强制审查触发条件时，根据实时持仓构建规范化监控输入，并交给 kanchi-dividend-review-monitor，而不是仅将股息审查作为叙述性章节处理。如果请求提供账户所在地备注，则还要为 kanchi-dividend-us-tax-accounting 构建税务规划输入；如果无法获取账户类型或持有期窗口，则将其标记为降级。

数据验证：

• 验证所有持仓都具有有效的股票代码
• 确认市值总和与账户权益大致相符
• 检查是否存在过时或非活跃持仓
• 处理边缘情况（零碎股、期权、受支持时的加密货币）

在每周资产配置审查前核对持仓

对于 core-portfolio-weekly，请遵循 references/position-reconciliation.md 中的说明，通过 scripts/reconcile_positions.py 对比完整的券商快照与 ACTIVE / PARTIALLY_CLOSED 记忆快照。生成 JSON 和 Markdown 核对报告。如果 can_continue 为 false，或无法确认快照的完整性、账户归属或时效性，则停止资产配置和再平衡审查。保留差异以供人工处理；绝不要通过核对流程下单或修改投资论点。这是一个离线、人工准备的关卡；现有的每周回放测试夹具尚未执行此流程。

步骤 2：补充持仓数据

为投资组合中的每项持仓收集额外的市场数据和基本面信息：

2.1 当前市场数据：

• 实时或延迟行情报价
• 每日成交量和流动性指标
• 52 周价格区间
• 市值

2.2 基本面数据： 使用 WebSearch 或可用的市场数据 API 获取：

• 行业和子行业分类
• 关键估值指标（P/E、P/B、股息率）
• 近期财报和财务健康指标
• 分析师评级和目标价
• 近期新闻和重大动态

2.3 技术分析：

• 价格趋势（20 天、50 天、200 天移动平均线）
• 相对强度
• 支撑位和阻力位
• 动量指标（如有 RSI、MACD）

步骤 3：投资组合层面分析

使用参考文件中的框架，对投资组合进行全面分析：

3.1 资产配置分析

阅读 references/asset-allocation.md，了解配置框架

从多个维度分析当前配置：

按资产类别：

• 股票与固定收益、现金、另类资产的对比
• 根据用户的风险承受能力档案，与目标配置进行对比
• 评估配置是否符合投资目标

按行业：

• 科技、医疗保健、金融、消费等
• 识别行业集中风险
• 与基准行业权重进行对比（例如 S&P 500）

按市值：

• 大盘股、中盘股和小盘股的分布
• 超大盘股集中度
• 市值多元化评分

按地区：

• 美国、国际市场和新兴市场
• 评估本土集中风险

输出格式（示例值）：

## Asset Allocation

### Current Allocation vs Target
| Asset Class | Current | Target | Variance |
|-------------|---------|--------|----------|
| US Equities | 70.0% | 60.0% | +10.0 pp |

### Sector Breakdown
[Pie chart description or table with sector percentages]

### Top 10 Holdings
| Rank | Symbol | % of Portfolio | Sector |
|------|--------|----------------|--------|
| 1 | AAPL | 8.5% | Technology |

3.2 多元化分析

阅读 references/diversification-principles.md，了解多元化理论

评估投资组合的多元化质量：

持仓集中度：

• 识别主要持仓及其合计权重
• 如果任何单一持仓占投资组合的比例超过 10-15%，则标记
• 计算赫芬达尔-赫希曼指数（HHI），用于衡量集中度

行业集中度：

• 识别主要行业
• 如果任何行业占投资组合的比例超过 30-40%，则标记
• 与基准行业多元化程度进行对比

相关性分析：

• 估算主要持仓之间的相关性
• 识别高度相关的持仓（可能存在冗余）
• 评估实际的多元化收益

持仓数量：

• 个人投资组合的最佳范围：15-30 只股票
• 如果多元化不足（少于 10 只股票）或过度多元化（超过 50 只股票），则标记

输出（示例值）：

## Diversification Assessment

**Concentration Risk:** [Low / Medium / High]
- Top 5 holdings represent 42% of portfolio
- Largest single position: AAPL at 12%

**Sector Diversification:** [Excellent / Good / Fair / Poor]
- Dominant sector: Technology at 31%
- [Assessment of balance across sectors]

**Position Count:** [Optimal / Under-diversified / Over-diversified]
- Total positions: 18 stocks
- [Recommendation]

**Correlation Concerns:**
- [List any highly correlated position pairs]
- [Diversification improvement suggestions]

3.3 风险分析

阅读 references/portfolio-risk-metrics.md，了解风险衡量框架

计算并解读关键风险指标：

波动性指标：

• 估算投资组合贝塔（持仓贝塔的加权平均值）
• 各持仓的波动率
• 投资组合标准差（如果有历史数据）

下行风险：

• 最大回撤（根据投资组合历史数据）
• 当前相对于峰值的回撤
• 存在重大未实现亏损的持仓

风险集中度：

• 高波动性股票（贝塔 > 1.5）所占比例
• 投机性／未盈利公司所占比例
• 杠杆使用情况（如适用）

尾部风险：

• 对潜在黑天鹅事件的敞口
• 单只股票集中风险
• 行业特定事件风险

输出（示例值）：

## Risk Assessment

**Overall Risk Profile:** [Conservative / Moderate / Aggressive]

**Portfolio Beta:** 1.12 (vs market at 1.00)
- Interpretation: Portfolio is [more/less] volatile than market

**Maximum Drawdown:** -14.2% (from $125,000 to $107,250)
- Current drawdown from peak: -6.3%

**High-Risk Positions:**
| Symbol | % of Portfolio | Beta | Risk Factor |
|--------|----------------|------|-------------|
| NVDA | 11% | 1.65 | High volatility |

**Risk Concentrations:**
- 31% in a single sector (Technology)
- 18% in stocks with beta above 1.5
- [Other concentration risks]

**Risk Score:** 68/100 (Medium risk)

3.4 绩效分析

使用可用数据评估投资组合绩效：

绝对回报：

• 投资组合整体未实现盈亏（美元和百分比）
• 绩效最佳的持仓（按涨幅百分比排序的前 5 名）
• 绩效最差的持仓（按跌幅百分比排序的后 5 名）

时间加权回报（如果有历史数据）：

• 年初至今回报
• 1 年、3 年、5 年年化回报
• 与基准（S&P 500、相关指数）进行对比

持仓层面的绩效：

• 盈利持仓与亏损持仓的比例
• 盈利持仓的平均涨幅
• 亏损持仓的平均跌幅
• 接近 52 周高点／低点的持仓

输出（示例值）：

## Performance Review

**Total Portfolio Value:** $100,000
**Total Unrealized P&L:** $8,500 (+9.3%)
**Cash Balance:** $5,000 (5% of portfolio)

**Best Performers:**
| Symbol | Gain | Position Value |
|--------|------|----------------|
| AAPL | +22.4% | $12,240 |

**Worst Performers:**
| Symbol | Loss | Position Value |
|--------|------|----------------|
| INTC | -12.0% | $6,600 |

**Performance vs Benchmark (illustrative values):**
- Portfolio return: +9.3%
- S&P 500 return: +7.8%
- Alpha: +1.5 percentage points

第 4 步：个股分析

针对关键持仓（按投资组合权重排名前 10-15 名），进行详细分析：

阅读 references/position-evaluation.md，了解持仓分析框架。

针对每项重要持仓：

4.1 验证当前投资逻辑：

• 最初为何建立该持仓？（如用户提供的背景中有相关信息）
• 投资逻辑是否已兑现或失效？
• 公司近期发展和新闻

4.2 估值评估：

• 当前估值指标（P/E、P/B 等）
• 与历史估值区间比较
• 与行业同类公司比较
• 评估为高估／合理／低估

4.3 技术面状况：

• 价格趋势（上升、下降、横盘）
• 股价相对于移动平均线的位置
• 支撑位和阻力位
• 动能状态

4.4 持仓规模：

• 当前占投资组合的权重
• 根据投资信心和风险，持仓规模是否合适？
• 相对于理想权重是超配还是低配？

4.5 操作建议：

• 持有 - 持仓规模合适，且投资逻辑依然成立
• 加仓 - 把握机会时持仓仍偏低，投资逻辑正在增强
• 减仓 - 持仓超配或估值已偏高
• 卖出 - 投资逻辑已失效，其他机会更好

每项持仓的输出（示例值）：

### AAPL - Apple Inc. (8.5% of portfolio)

**Position Details:**
- Shares: 50
- Avg Cost: $150.00
- Current Price: $170.00
- Market Value: $8,500
- Unrealized P/L: $1,000 (+13.3%)

**Fundamental Snapshot:**
- Sector: [Sector]
- Market Cap: $3.2T
- P/E: 31.4 | Dividend Yield: 0.5%
- Recent developments: [Key news or earnings]

**Technical Status:**
- Trend: [Uptrend / Downtrend / Sideways]
- Price vs 50-day MA: Above by 4.2%
- Support: $162.00 | Resistance: $176.00

**Position Assessment:**
- **Thesis Status:** [Intact / Weakening / Broken / Strengthening]
- **Valuation:** [Undervalued / Fair / Overvalued]
- **Position Sizing:** [Optimal / Overweight / Underweight]

**Recommendation:** [HOLD / ADD / TRIM / SELL]
**Rationale:** [1-2 sentence explanation]

第 5 步：再平衡建议

阅读 references/rebalancing-strategies.md，了解再平衡方法。

生成具体的再平衡建议：

5.1 确定再平衡触发条件：

• 持仓权重明显偏离目标值
• 需要调整的行业／资产类别配置
• 需要减仓的超配持仓（超过阈值）
• 需要加仓的低配领域（低于阈值）
• 税务考量（资本利得的影响）

5.2 制定再平衡计划：

需要减仓的持仓：

• 超配持仓（偏离目标值超过阈值）
• 大幅上涨的股票（存在估值方面的担忧）
• 占投资组合比例超过 15-20% 的集中持仓
• 投资逻辑已失效的持仓

需要加仓的持仓：

• 低配的行业或资产类别
• 当前低配但投资信心较高的持仓
• 有助于改善分散化的新机会

现金配置：

• 如果现金过多（占投资组合比例超过 10%），建议投入使用
• 根据机会和配置缺口确定优先顺序

5.3 排定优先级： 按优先级对再平衡操作排序：

1. 立即 - 降低风险（减持过度集中的持仓）
2. 高优先级 - 配置明显偏离（与目标值相差超过 10%）
3. 中优先级 - 配置中度偏离（与目标值相差 5-10%）
4. 低优先级 - 微调和机会性调整

输出（示例值）：

## Rebalancing Recommendations

### Summary
- **Rebalancing Needed:** [Yes / No / Optional]
- **Primary Reason:** [Concentration risk / Sector drift / Cash deployment / etc]
- **Estimated Trades:** 2 sell orders, 3 buy orders

### Recommended Actions

#### HIGH PRIORITY: Risk Reduction
**TRIM NVDA** from 18% to 12% of portfolio
- **Shares to Sell:** 25 shares (about $3,000)
- **Rationale:** [Overweight / Valuation extended / etc]
- **Tax Impact:** $600 capital gain (estimate)

#### MEDIUM PRIORITY: Asset Allocation
**ADD investment-grade bond exposure**
- **Target:** Increase from 10% to 20%
- **Suggested Securities:** [Select liquid securities that fit the user's mandate]
- **Amount to Invest:** About $10,000

#### CASH DEPLOYMENT
**Current Cash:** $5,000 (5% of portfolio)
- **Recommendation:** [Deploy / Keep for opportunities / Reduce to target]
- **Suggested Allocation:** [Distribution across sectors/stocks]

### Implementation Plan
1. [First action - highest priority]
2. [Second action]
3. [Third action]
...

**Timing Considerations:**
- [Tax year-end planning / Earnings season / Market conditions]
- [Suggested phasing if applicable]

第 6 步：生成投资组合报告

创建完整的 Markdown 报告，并保存到代码库根目录：

文件名： portfolio_analysis_YYYY-MM-DD.md

报告结构：

# Portfolio Analysis Report

**Account:** [Account type if available]
**Report Date:** 2026-07-25
**Portfolio Value:** $100,000
**Total P&L:** $8,500 (+9.3%)

---

## Executive Summary

[3-5 bullet points summarizing key findings]
- Overall portfolio health assessment
- Major strengths
- Key risks or concerns
- Primary recommendations

---

## Holdings Overview

[Summary table of all positions]

---

## Asset Allocation
[Section from Step 3.1]

---

## Diversification Analysis
[Section from Step 3.2]

---

## Risk Assessment
[Section from Step 3.3]

---

## Performance Review
[Section from Step 3.4]

---

## Position Analysis
[Detailed analysis of top 10-15 positions from Step 4]

---

## Rebalancing Recommendations
[Section from Step 5]

---

## Action Items

**Immediate Actions:**
- [ ] [Action 1]
- [ ] [Action 2]

**Medium-Term Actions:**
- [ ] [Action 3]
- [ ] [Action 4]

**Monitoring Priorities:**
- [ ] [Watch list item 1]
- [ ] [Watch list item 2]

---

## Appendix: Full Holdings

[Complete table with all positions and metrics]

第 7 步：后续互动

做好回答后续问题的准备：

常见问题：

“为什么应该卖出 [SYMBOL]？”

• 说明具体问题（估值、投资逻辑失效、持仓集中）
• 提供支持数据
• 如适用，提供替代持仓建议

“我应该改买什么？”

• 建议可改善配置的具体股票
• 说明这些股票如何弥补投资组合的缺口
• 简要说明投资逻辑

“我最大的风险是什么？”

• 找出主要风险因素（持仓集中、行业暴露、波动性）
• 量化风险
• 建议缓解策略

“我的投资组合与 [benchmark] 相比如何？”

• 比较配置、行业权重和风险指标
• 突出主要差异
• 评估这些差异是否合理

“我应该现在再平衡，还是等等？”

• 考虑市场状况、税务影响和交易成本
• 说明建议时机及理由

“你能更详细地分析 [specific position] 吗？”

• 如有需要，使用 us-stock-analysis 技能进行深入分析
• 将分析结果结合投资组合的整体情况

分析框架

目标配置模板

此技能包含适用于不同投资者类型的参考配置模型：

阅读 references/target-allocations.md，了解详细模型：

• 保守型（保本，注重收入）
• 稳健型（兼顾增长与收入）
• 成长型（长期资本增值）
• 激进型（追求最大增长，风险承受能力高）

每个模型均包括：

• 资产类别目标（股票／债券／现金／另类资产）
• 行业指引
• 市值分布
• 地域配置
• 持仓规模规则

当用户未指定配置策略时，可将这些模型作为比较基准。

风险状况评估

如果用户的目标配置未知，请根据以下信息评估适当的风险状况：

• 年龄（如有提及）
• 投资期限（如有提及）
• 当前配置（反映偏好）
• 持仓类型（保守型股票与投机型股票）

阅读 references/risk-profile-questionnaire.md，了解评估框架

输出指南

语气和风格：

• 客观、善于分析
• 提供可执行的建议，并清楚说明理由
• 承认市场预测存在不确定性
• 兼顾乐观态度与风险意识
• 尽可能量化

数据呈现：

• 使用表格对比数据和指标
• 使用百分比表示配置和回报
• 使用美元金额表示绝对值
• 在整份报告中保持格式一致

建议清晰度：

• 明确使用行动动词（减持、增持、持有、卖出）
• 根据实时持仓规模和当前价格给出具体数量
• 标明优先级（立即、高、中、低）
• 为每项建议提供支持理由

可视化描述：

• 描述配置明细时，仿佛是在制作饼图
• 用相当于条形图的方式描述行业权重
• 使用方向指示符（↑ ↓ →）展示业绩趋势

资源

分析期间按需加载以下参考资料：

references/alpaca-mcp-setup.md

• 适用情形：用户需要帮助设置 Alpaca MCP Server
• 内容：安装说明、API 密钥配置、MCP 服务连接步骤、故障排除

references/asset-allocation.md

• 适用情形：分析投资组合配置或制定再平衡计划
• 内容：资产配置理论、不同风险状况下的最优配置、行业配置指引、再平衡触发条件

references/diversification-principles.md

• 适用情形：评估投资组合的分散化水平
• 内容：现代投资组合理论基础、相关性概念、最优持仓数量、集中度风险阈值、分散化指标

references/portfolio-risk-metrics.md

• 适用情形：计算风险评分或解读波动性
• 内容：贝塔计算、标准差、夏普比率、最大回撤、风险价值（VaR）、风险调整后回报指标

references/position-evaluation.md

• 适用情形：分析单项持仓，以决定买入／持有／卖出
• 内容：持仓分析框架、投资论点验证清单、持仓规模指引、卖出纪律标准

references/rebalancing-strategies.md

• 适用情形：制定再平衡建议
• 内容：再平衡方法（日历法、阈值法、战术法）、税务优化策略、交易成本考量、执行时机

references/target-allocations.md

• 适用情形：需要用于对比的基准配置
• 内容：适用于保守型／稳健型／成长型／激进型投资者的模型投资组合、行业目标范围、市值分布

references/risk-profile-questionnaire.md

• 适用情形：用户未指定风险承受能力或目标配置
• 内容：风险评估问题、评分方法、风险状况分类

错误处理

如果未连接 Alpaca MCP Server：

1. 告知用户需要集成 Alpaca
2. 提供 references/alpaca-mcp-setup.md 中的设置说明
3. 提供替代方案：手动输入数据（不太理想，需用户提供持仓 CSV）

如果 API 返回的数据不完整：

• 使用现有数据继续分析
• 在报告中注明限制
• 建议手动核实缺失的持仓

如果持仓数据似乎过时：

• 标记此问题
• 建议刷新连接或查看 Alpaca 状态
• 继续分析，但注明结果可能存在偏差

如果用户没有持仓：

• 确认其投资组合为空
• 改为提供投资组合构建指导，而非分析
• 建议使用 value-dividend-screener 或 us-stock-analysis 寻找股票投资思路

高级功能

税损收割机会

识别适合进行税损收割的未实现亏损持仓：

• 亏损超过 5% 的持仓
• 考虑持有期（避免触发洗售规则）
• 建议替代证券（相似但并非实质上相同）

股息收入分析

针对持有派息股票的投资组合：

• 估算年度股息收入
• 股息增长率走势
• 股息覆盖率和可持续性
• 长期持仓的成本收益率

相关性矩阵

针对持有 5-20 个仓位的投资组合：

• 估算主要持仓之间的相关性
• 识别冗余持仓（相关性 >0.8）
• 建议改进分散投资

情景分析

模拟投资组合在不同情景下的表现：

• 牛市（股票升值 20%）
• 熊市（股票下跌 20%）
• 行业轮动（科技股走弱，价值股走强）
• 利率上升（对成长股和债券的影响）

示例查询

基本投资组合评估：

• “分析我的投资组合”
• “评估我的持仓”
• “我的投资组合表现如何？”

资产配置分析：

• “我的资产配置是什么？”
• “我的科技股仓位是否过于集中？”
• “显示我的行业分布”

风险评估：

• “我的投资组合风险是否过高？”
• “我的投资组合 Beta 是多少？”
• “我的主要风险是什么？”

再平衡：

• “我应该再平衡吗？”
• “我应该买入或卖出什么？”
• “我该如何改善分散投资？”

表现：

• “我表现最好和最差的持仓是什么？”
• “与市场相比，我的表现如何？”
• “哪些股票表现好，哪些表现差？”

特定持仓：

• “我应该卖出 [SYMBOL] 吗？”
• “[SYMBOL] 在我的投资组合中是否占比过高？”
• “我应该如何处理 [SYMBOL]？”

限制与免责声明

在所有报告中加入：

本分析仅供参考，不构成财务建议。投资决策应根据个人情况、风险承受能力和财务目标做出。过往表现不代表未来结果。做出投资决策前，请咨询合格的财务顾问。

数据准确性取决于 Alpaca API 和第三方市场数据来源。请独立核实关键信息。税务影响仅为估算；如需具体指导，请咨询税务专业人士。