claude-trading-skills 组合报告模板详解:Portfolio Manager 七大输出区块的字段语义、阈值与落地写法

原创2026-11-15 22:06:591,820 阅读
文章标签:金融科技AI 技能人工智能数据分析

claude-trading-skills 组合报告模板详解:Portfolio Manager 七大输出区块的字段语义、阈值与落地写法

本篇围绕 claude-trading-skills 中 portfolio-manager 技能的《Report Section Templates》,逐个拆解资产配置、多元化、风险、业绩、单仓位、再平衡与整篇报告骨架这七个 Markdown 输出模板:不止于“照抄模板”,而是把每个字段的来源计算、阈值分档和源码级调用链讲清楚,让你写出的组合报告既符合技能约定,又能被复核与引用。

一、这份模板文件在技能中的位置

skills/portfolio-manager/references/report-section-templates.md 开篇就声明了自己的身份:

Output templates for the portfolio report sections, moved verbatim from SKILL.md.

也就是说,它是从 SKILL.md 中“原样搬出”的输出片段集合,目的是让主技能文档保持精简,而把渲染层的格式契约单独沉淀。这带来两个直接后果:

  1. 模板不是可选装饰。SKILL.md 的 Step 3.1、3.2、3.3、3.4、Step 4、Step 5、Step 6 都以“Read references/report-section-templates.md(section xxx)”的方式显式引用它,属于工作流的强制渲染步骤;
  2. 模板与计算文档分工明确。模板只规定“长什么样”,不规定“怎么算”。真正决定数值的口径来自 asset-allocation.md、diversification-principles.md、portfolio-risk-metrics.md、position-evaluation.md 与 rebalancing-strategies.md。

模板与工作流步骤的对应关系可以整理成下表:

模板小节 触发步骤 上级框架文档 输出粒度
Asset Allocation output template Step 3.1 references/asset-allocation.md 组合级
Diversification Assessment output template Step 3.2 references/diversification-principles.md 组合级
Risk Assessment output template Step 3.3 references/portfolio-risk-metrics.md 组合级
Performance Review output template Step 3.4 无独立框架文件(口径见 Step 3.4 正文) 组合级
Per-position output template Step 4 references/position-evaluation.md 单仓位级
Rebalancing Recommendations output template Step 5 references/rebalancing-strategies.md 行动级
Step 6: Portfolio Analysis Report structure Step 6 汇总以上全部 文档级骨架

另外,resource-index.md 提供了“何时加载哪个参考文件”的索引表,SKILL.md 的 Resources 一节要求先读该索引再决定加载内容——这是控制上下文成本的设计,模板文件同样按需加载。

二、模板里的“illustrative values”是什么意思

七份模板中有六份带示例数字(如 AAPL 8.5%、beta 1.12、Risk Score 68/100)。SKILL.md 在每次引用模板时都写明 Output (illustrative values) 或 Output Format (illustrative values),Performance Review 模板内部更直接标注 Performance vs Benchmark (illustrative values)。

这是一个重要的事实边界,落地时必须遵守:

  • 示例数字用于演示字段位置与量纲,不是基准值、不是目标值,更不能当作某只标的的真实数据引用;
  • 除示例数字外,模板中的字段名、单位、正负号方向才是契约。例如 Variance 必须写成 +10.0 pp(百分点),而不是 +10.0%;Maximum Drawdown 必须带负号;
  • 报告最终必须附带免责声明。SKILL.md 的 Limitations and Disclaimers 一节规定 “Include in all reports”,即两段固定声明(非投资建议 + 数据准确性/税费估算声明)属于每份报告的必需组成部分,模板骨架中虽未展开,但不能省略。

三、Asset Allocation 模板:先统一量纲,再谈维度

原文模板完整如下:

## 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 |

这个只有三小节的模板,背后对应 Step 3.1 要求的四个分析维度:

  • By Asset Class:Stocks / Fixed Income / Cash / Alternatives,与用户风险画像的目标配置比较;
  • By Sector:识别行业集中度,并与基准(如 S&P 500)行业权重对照;
  • By Market Cap:Large / Mid / Small 分布,警惕超大盘集中;
  • By Geography:US / International / Emerging,评估本土集中风险。

模板用 Current Allocation vs Target 三列表承载第一个维度,用 Sector Breakdown(“饼图描述或表格”二者取一)承载行业维度,用 Top 10 Holdings 承载集中度;市值与地域维度在模板中没有固定表,属于允许自行扩展的维度。若补一张市值分布表,字段命名建议与第一张表保持一致(Current / Target / Variance),以维持全篇可解析性。

Variance 的取值语义由 asset-allocation.md 的 Rebalancing Thresholds 表定义,模板中的 +10.0 pp 恰好落在最严重一档:

Allocation Drift Action Priority
<3% Monitor, no action needed None
3-5% Consider rebalancing (optional) Low
5-10% Rebalance recommended Medium
>10% Rebalance immediately High

这也解释了为什么模板示例选了 70/60:它不是随手写的一个数,而是刻意落在“必须立即再平衡”的边界之外,用来示范最需要动作的场景。

目标配置从哪里来?asset-allocation.md 给出了四档风险画像的完整区间,例如 Growth 画像为股票 75-90%、债券 10-20%、现金 2-5%、另类 0-10%;Conservative 为股票 20-40%、债券 50-70%、现金 10-20%。SKILL.md 的 Target Allocation Templates 一节说明,当用户未指定目标配置时,用这些模型作为比较基准;若连风险画像都未知,则先走 risk-profile-questionnaire.md 的评估框架。因此 Target 列要么来自用户显式目标,要么来自画像模型,不允许留空或凭空填写。

四、Diversification Assessment 模板:三类定性评级 + 一条相关性线索

原文模板:

## 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]

它的结构是“一个定性评级 + 两条量化证据 + 一段建议”,四个区块各自对应 diversification-principles.md 中的明确阈值:

1) Concentration Risk(Low / Medium / High)

证据行 Top 5 holdings represent 42% 对应 Top 5 集中度分档:<25% 分散良好、25-40% 中度集中、40-60% 高度集中、>60% 过度集中。42% 落在 High 档,因此模板把评级写成 High 是自洽的。第二行 Largest single position: AAPL at 12% 对应单仓位分档:10-15% 为 High、建议 trim(除非极高确信度);15-20% 为 Very High,应立即 trim。

模板把“评级”放在前面、“证据”放在后面,这个顺序有实际价值:Agent 或 LLM 在检索报告时,能优先命中 Concentration Risk: High 这样的标签,而不必解析表格。

2) Sector Diversification(Excellent / Good / Fair / Poor)

证据行 Dominant sector: Technology at 31% 对应行业分档:25-30% 为中度超配、30-40% 为高度超配(建议 trim)、>40% 为过度集中。31% 刚越过 30% 线,属于“需要说明理由”的区间。同时 SKILL.md Step 3.2 的另一条规则是“任何单一行业超过 30-40% 即标记”,与该分档一致。

3) Position Count(Optimal / Under-diversified / Over-diversified)

模板示例 Total positions: 18 stocks 恰好落在推荐区间内(SKILL.md Step 3.2 写的是 15-30 只;diversification-principles.md 的边际分散收益表给出:30 只约消除 90% 非系统性风险,50 只约 93%,100 只约 95%)。低于 10 只应判 Under-diversified,高于 50 只判 Over-diversified。若组合是 ETF 而非个股,判据换成 5-10 只分散型基金。

4) Correlation Concerns

这是唯一没有量化门槛的区块,因为 Step 3.2 只要求“估计主要仓位之间的相关性、识别高度相关持仓(潜在冗余)”。可用的解释性标尺在 diversification-principles.md:平均两两相关系数 <0.3 优秀、0.3-0.5 良好、0.5-0.7 一般(典型股票组合)、>0.7 差。文中还提醒“危机中相关性趋于 1”,因此该区块的结论应写成“关注项”而非“风险已量化”。

值得单独提出的还有 HHI:SKILL.md Step 3.2 明确要求“Calculate Herfindahl-Hirschman Index (HHI) for concentration measurement”,但这份 Diversification 模板里没有 HHI 字段。HHI 的公式与分档在 diversification-principles.md 与 portfolio-risk-metrics.md 中重复给出:

HHI = Σ(w_i × 100)²

分档为 <1000 低集中、1000-1800 中度、1800-2500 高度、>2500 极高、>4000 极端。落地时的合理做法是把 HHI 作为 Position Count 区块的补充证据行(例如 HHI: 2250 (High concentration)),而不是另开一个与模板冲突的小节。

五、Risk Assessment 模板:把“市值回撤”和“当前回撤”分开

原文模板:

## 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)

Portfolio Beta 的算法来自 portfolio-risk-metrics.md,有两种等价表达:

β = Cov(R_portfolio, R_market) / Var(R_market)
或按持仓加权估计:
β = Σ(w_i × β_i)

后者正是 SKILL.md Step 3.3 所写的 “weighted average of position betas”,也让模板中的 High-Risk Positions 表可以直接服务 Beta 计算:NVDA 11% @ 1.65 贡献 0.1815。该文档还给出一个可复用的完整算例(40% SPY β=1.0、30% QQQ β=1.2、20% VNQ β=0.9、10% TLT β=0.3 → 组合 β=0.97),说明“加权求和”这一步的口径。

1.12 的解释方向要写对:β>1 表示组合比市场更波动,市场下跌 10% 时组合约下跌 11.2%(文档示例即 β=1.2 → 12%)。模板特意把 (vs market at 1.00) 写在同一行,是为了让读者不必回查基准。

回撤的双口径是本模板最容易被误写的地方:

  • Maximum Drawdown: -14.2% (from $125,000 to $107,250) 是按公式 (Trough - Peak) / Peak 算出的历史最大峰值到谷值;(107,250 − 125,000) / 125,000 = −14.2%,与文档公式示例结构一致(文档示例为 150k→105k = −30%);
  • Current drawdown from peak: -6.3% 是从最近峰值到当前值,属于实时风险监控指标,文档给出的分档是:-1%~-5% 正常回调、-5%~-10% 需复核仓位、-10%~-20% 需评估调整、>-20% 进入熊市区间、需考虑再平衡。

两者绝不可互相替代:最大回撤用于回答“这套配置历史上最坏能有多差、我的风险承受力够不够”,当前回撤用于回答“现在要不要动手”。

Risk Score 68/100 的计算结构在 portfolio-risk-metrics.md 的 Composite Risk Score 一节定义得非常明确:

Risk Score =
  (Volatility Score × 30%) +
  (Beta Score × 20%) +
  (Drawdown Score × 25%) +
  (Concentration Score × 25%)

四个分项均按 0-100 打分,例如 Beta 分项 1.0-1.3 → 40-60 分,Max DD 10-20% → 20-40 分,HHI 2000-2500 → 60-80 分。要注意一处表述差异:模板示例把 68 标注为 Medium risk,而风险指标文档的汇总表把 60-80 归为 High(适合成长型投资者)。两份文件出自不同章节的语境,落地时应先选定一张分档表,并在同一份报告内保持一致——这是模板使用中最容易产生自相矛盾的地方。

Risk Concentrations 的三条示例行也各自有出处:31% in a single sector 对应行业超配线,18% in stocks with beta above 1.5 对应 SKILL.md Step 3.3 的 “Percentage in high-volatility stocks (beta > 1.5)”,第三行留给杠杆使用、投机/未盈利公司占比等尾风险项。

六、Performance Review 模板:注意百分比的分母

原文模板:

## 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

三个头部字段的量纲必须分开写:Total Portfolio Value 用美元、Total Unrealized P&L 用“美元(百分比)”、Cash Balance 用“美元(占组合百分比)”。

这里有一个容易被忽略的算术细节:$8,500 (+9.3%) 若要成立,分母必须是成本基准约 $91,500(8,500 / 91,500 ≈ 9.29%),而不是当前市值 $100,000(那会得到 +8.5%)。因此写报告时要么明确“P&L% 以成本为分母”,要么统一改用市值口径并同步改写数字,不能两者混用。

Best / Worst Performers 表沿用 SKILL.md Step 3.4 的“按涨跌幅取前 5 / 后 5”规则,但模板只列 1 行示例;实际报告应按 Top 5 / Bottom 5 展开。第三张表把组合收益、基准收益和 Alpha 分成三行,并用 percentage points 明确“Alpha 是百分点差”而非百分比——+9.3% 与 +7.8% 的差是 +1.5 pp,写成 +1.5% 会引入量纲错误。

模板中“vs Benchmark”被标注为 illustrative,原因是基准数据依赖外部行情来源;SKILL.md Step 3.4 把时间加权收益(YTD / 1Y / 3Y / 5Y 年化)列为 “if history available”,说明没有历史序列时该部分应明确标注不可用,而不是估算填充。

七、Per-position 模板:把四因子评估压缩成一张卡片

原文模板:

### 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]

标题行的 8.5% 与 Position Details 的 $8,500 是同一条信息的两种表达(8,500 / 100,000),这类自洽性在模板中反复出现,也意味着生成报告后应做一次交叉校验。

Position Details 五个字段全部可由持仓数据直接推导:Market Value = Shares × Current Price(50 × 170 = 8,500);Unrealized P/L = Shares × (Current Price − Avg Cost)(50 × 20 = 1,000),百分比以成本为分母(1,000 / 7,500 ≈ 13.3%)。这与离线审阅脚本 review_csv.py 中 unrealized_pnl 的计算方式一致,只是脚本额外处理了空头符号反转:

"unrealized_pnl": _text(sign * quantity * (price - basis)) if basis is not None else None

Technical Status 对应 Step 4.3 的要求(趋势、均线相对位置、支撑阻力、动量状态)。模板只保留最典型的三项,因为 SKILL.md 的 Output Guidelines 要求“量化优先”,而无数据支撑的指标描述容易变成空话。

Position Assessment 三行是决策的核心输入,直接映射 position-evaluation.md 的四因子模型(Thesis Validation 40%、Valuation 30%、Position Sizing 20%、Relative Opportunity 10%):

Thesis Status 判据 Action Bias
Strengthening 基本面改善、逻辑加速 Consider ADD
Intact 符合预期 HOLD
Weakening 出现隐忧、逻辑部分受损 Consider TRIM
Broken 逻辑失效、基本面恶化 SELL

Valuation 的 Undervalued / Fair / Overvalued 同样有映射:低于历史均值与同业、低 PEG → ADD;与历史及同业一致 → HOLD;高于历史区间、溢价同业、高 PEG → TRIM。Position Sizing 则对应 SKILL.md Step 4.4 与仓位分档表(高确信度 8-12%/上限 15%,中等 5-8%/上限 10%,低确信度 2-5%/上限 7%;>20% 为 Excessive)。

最后两行是动作与理由:Recommendation 只能取四个动作词之一,Rationale 限 1-2 句。这个“动作词 + 短理由”的格式不是排版偏好,而是 SKILL.md Output Guidelines 的硬要求:

Explicit action verbs (TRIM, ADD, HOLD, SELL);Specific quantities derived from live position sizes and current prices;Priority levels;Supporting rationale for each recommendation.

即:动作词、具体数量、优先级、理由是推荐的四要素,模板中数量被移到再平衡小节,理由留在卡片里。

模板只覆盖 “top 10-15 by portfolio weight”(Step 4 明示),小仓位只需出现在 Holdings Overview 与 Appendix,不必逐只展开——否则报告长度会与本就不推荐的 50+ 持仓结构一起失控。

八、Rebalancing 模板:三级优先级 + 可执行算路

原文模板:

## 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]

Summary 三行是决策前置:Rebalancing Needed 的 Yes/No/Optional 直接由漂移阈值决定(<3% 无需动作、3-5% 可选、5-10% 建议、>10% 立即),Primary Reason 在 Step 5.1 的触发条件里取值(偏离目标权重、行业/资产类别需调整、超配需削减、低配需补充、税负考量),Estimated Trades 用“N sell orders, M buy orders”给出执行规模。

三级优先级对应 Step 5.3 的排序规则:Immediate(风险削减)→ High(>10% 偏离)→ Medium(5-10% 偏离)→ Low(微调与机会性动作),而正文只用 HIGH / MEDIUM / CASH DEPLOYMENT 三个小标题,把 Immediate 并入 HIGH PRIORITY 的“Risk Reduction”语义中。

TRIM 的算路是本模板最值钱的部分,可以完全复现:

目标市值 = 组合总值 × 目标权重
当前市值 = 组合总值 × 当前权重
应卖金额 = 当前市值 − 目标市值
应卖股数 = 应卖金额 / 当前价格

用模板数字反推,可得组合总值约 $50,000:NVDA 18% = $9,000;目标 12% = $6,000;差额 $3,000;若现价 $120,则 $3,000 / 120 = 25 股。这与模板的 25 shares (about $3,000) 完全吻合。这个反推过程也说明:“about” 只能出现在金额侧,股数侧必须由当期价格算出整数。同样的公式在 position-evaluation.md 的 Rebalancing Calculation 一节有等价写法(从 18% 削到 10% 的算例)。

Tax Impact 是估算项,模板用 (estimate) 显式标注,与 SKILL.md 免责声明中的 “Tax implications are estimates only” 呼应。rebalancing-strategies.md 补充了节税执行顺序:优先在税优账户(IRA/401k)内再平衡、税账户优先卖高成本批次、用新增资金代替卖出。

ADD 与 CASH DEPLOYMENT 的写法差异值得注意:前者写 Target: Increase from 10% to 20% + Amount to Invest: About $10,000(同样隐含组合约 $100,000),后者写 Current Cash: $5,000 (5% of portfolio) + 三选一的处置建议。这与 Step 5.2 的规则一致——现金超过组合 10% 时应提出部署建议,否则在“保留机会”和“降到目标”之间做选择。

Implementation Plan 与 Timing Considerations 是模板的收口:前者按优先级编号,后者提示税年规划、财报季、市场环境与分批执行。这两块把“分析结论”转成“可执行清单”,也是整份报告中唯一需要跨小节引用优先级的段落。

九、Step 6:整篇报告的骨架与写作顺序

原始结构:

# 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]

这个骨架有三层设计意图:

  1. 抬头四字段 + 分隔线:Account / Report Date / Portfolio Value / Total P&L 构成报告的身份与时效锚点。Account 标注 “if available”,与离线模式只做字段最小化的做法一致;Report Date 决定“这份结论属于哪一天”。
  2. 主体八节固定顺序:Executive Summary → Holdings → Allocation → Diversification → Risk → Performance → Position → Rebalancing。顺序是“总—分—总”的收敛结构:先给结论,再逐层下钻到单仓位,最后回到行动。这个顺序也是 Step 3/4/5 的天然执行顺序,因此模板可以逐节注明 “Section from Step 3.1” 之类的来源标注——报告是可追溯的拼装,而不是重写。
  3. Action Items 用 Markdown 任务列表:- [ ] 复选框让报告可以直接当检查表用,且分为 Immediate / Medium-Term / Monitoring 三组,与再平衡优先级形成呼应但不等同(Monitoring 组是观察项,不需要立即交易)。

文件命名与落盘位置由 Step 6 规定:portfolio_analysis_YYYY-MM-DD.md,保存到仓库根目录。这与离线模式的 portfolio_csv_review.md 是两套不同产物,不能混用命名。

十、模板与“完整经纪分析 / 离线有限审阅”两套数据源的衔接

portfolio-manager 有两条数据路径,模板的可用字段范围随之不同:

路径 A:完整经纪分析(Alpaca MCP 或 REST 回退)

SKILL.md Step 1 要求通过 get_account_info、get_positions、get_portfolio_history 等 MCP 工具或 REST 回退端点取数,并做数据校验:符号有效、市值合计近似等于账户权益、排除陈旧仓位、处理碎股/期权/加密等边界。只有拿到账户权益、现金与历史序列,才能填满 Risk 模板的 Beta、最大回撤、当前回撤与 Risk Score,以及 Performance 模板的现金占比与基准对比。

调度任务(scheduled job)场景下 MCP 工具可能不可用,SKILL.md 要求改用 REST 并在报告中标注来源为 Alpaca REST fallback,同时保持口径一致:

gross_long_exposure = long_market_value / equity
cash_pct = cash / equity

这条规则的意义正是为了避免模板被误读:如果用毛市值做分母,杠杆账户的行业权重会显得“很健康”,而真实风险被掩盖。因此资产配置模板虽然有 % of Portfolio 字段,其分母定义必须在报告开头说清。

路径 B:离线有限审阅(CSV 或保存的 Alpaca positions JSON)

portfolio-holdings-review 走的是 review_csv.py,无需凭证、不联网、不写交易记忆。它输出的 Markdown 是另一套更窄的结构,而非本模板:

# Offline CSV holdings review

Source: local_csv; as-of: 2026-10-20T12:00:00+00:00 (operator asserted)

Gross holdings value (USD): 80
Signed net holdings value (USD): 20

| Symbol | Direction | Quantity | Gross value USD | Gross weight % | Unrealized P&L USD |
|---|---|---|---|---|---|
| FICTA | LONG | 2.5 | 50 | 62.5 | 12.5 |
| FICTB | SHORT | 1 | 30 | 37.5 | 10 |

## Limitations
- Local snapshot assertions only; identity, completeness and price freshness are unverified.
...

它缺少的正是模板中最“值钱”的几块:现金、杠杆/权益、行业与 Beta、历史收益、股息健康度、交易建议。因此 csv-holdings-review.md 明确规定:不能把 CSV 配置报告当作“已完成完整账户评审”,core-portfolio-weekly 仍需经纪与记忆对账闸门(见 position-reconciliation.md)。

一个可直接复现的验证命令(来自 SKILL.md 与 csv-holdings-review.md):

python3 skills/portfolio-manager/scripts/review_csv.py \
  --input skills/portfolio-manager/assets/fictional_holdings.csv \
  --as-of 2026-10-20T12:00:00Z --output-dir reports/holdings-demo

该仓库自带的 replay.yaml 用同一份虚构输入做离线回放,其 golden 输出 01_holdings_allocation_report.md 正是上面这段 Markdown——可以用来确认“模板字段”与“脚本实际渲染字段”的差异边界。

同时要注意 JSON 契约的两处细节:权重按毛持仓值计算并四舍五入到 6 位小数,因此舍入后的权重可能不精确等于 100;cost_basis 缺失时 unrealized_pnl 为 null(渲染为 unavailable),且不输出聚合 P&L。这与模板中 Unrealized P&L: $1,000 (+13.3%) 的“单仓位 + 组合合计”写法形成对照:聚合值只在完整路径下由账户数据给出。

十一、落地清单:生成一份可被引用、可被复核的报告

把上面的口径压缩成一张自查表,写完报告后逐项过一遍:

结构与格式

  • [ ] 抬头四字段齐全,Report Date 为生成日,Portfolio Value 与 Total P&L 口径(市值/成本)已注明;
  • [ ] 八节顺序为 Executive Summary → Holdings → Allocation → Diversification → Risk → Performance → Position → Rebalancing,节间用 --- 分隔;
  • [ ] 每个组合级小节使用了对应模板的字段名与单位(pp、%、$、负号方向);
  • [ ] 单仓位卡片数量控制在权重前 10-15 名,其余进 Appendix;
  • [ ] Action Items 使用 - [ ] 且分为 Immediate / Medium-Term / Monitoring;
  • [ ] 两份免责声明已附(非投资建议;数据准确性/税费估算)。

数值自洽

  • [ ] Variance 与目标配置、漂移阈值表一致(>10% 必须进入立即再平衡);
  • [ ] Top 5 集中度、最大单仓、主导行业三项与对应分档表的评级一致;
  • [ ] Beta 为加权求和结果,且建议附一行计算依据;
  • [ ] 最大回撤与当前回撤分别标注、未混用;
  • [ ] Risk Score 的四分项权重(30/20/25/25)与所选分档表版本一致(注意 68 分在模板与指标文档中的等级差异);
  • [ ] TRIM/ADD 的股数与金额可由“组合总值 × 权重差 ÷ 现价”反推;
  • [ ] P&L 百分比的分母(成本 vs 市值)全篇统一;Alpha 使用 percentage points。

来源与边界

  • [ ] 数据源已标注(Alpaca MCP / Alpaca REST fallback / local_csv / alpaca_positions_snapshot);
  • [ ] 使用权益作分母计算敞口,杠杆账户显式标注 long_market_value > equity;
  • [ ] 所有示例性数字已替换为真实取数,未把 illustrative values 当结论;
  • [ ] 离线模式报告未宣称具备现金、杠杆、行业、Beta、历史收益与交易建议能力;
  • [ ] 完整路径经过持仓对账闸门,can_continue 为 false 时停止配置与再平衡评审。

写作风格

  • [ ] 语气客观、量化优先、承认预测不确定性(SKILL.md Output Guidelines);
  • [ ] 推荐使用显式动作词(HOLD / ADD / TRIM / SELL)并附 1-2 句理由;
  • [ ] 图表位置用文字描述(饼图/柱状图等价描述),不依赖无法渲染的二进制资源。

十二、小结

report-section-templates.md 表面是七段 Markdown 片段,实质是 portfolio-manager 的输出接口定义:它把 Step 3 到 Step 6 的分析结论固化成字段名、量纲、评级枚举和优先级分档,使同一套阈值文档(资产配置漂移、集中度分档、风险评分权重、四因子权重)能够被一致地渲染。理解这份模板的关键不在背诵表格,而在三点:字段背后的公式(Beta 加权、HHI 平方和、回撤双口径、TRIM 股数换算)、评级背后的阈值表,以及 illustrative values 与真实数据的边界。把这三层对齐,报告才既符合技能契约,也能被后续的 Agent、LLM 与人工复核真正检索、引用和验证。

登录后查看全文
claude-trading-skills