claude-trading-skills 投资组合管理技能实战:Alpaca MCP 全账户分析与离线持仓复核
claude-trading-skills 投资组合管理技能实战:Alpaca MCP 全账户分析与离线持仓复核
Portfolio Manager 是 claude-trading-skills 仓库中负责“组合层”决策的 Claude Code Skill,它把证券账户持仓数据变成资产配置、分散度、风险、个股与再平衡五个维度的结构化报告。本文以官方技能文档为主线,完整拆解它的两条数据通路(Alpaca MCP 全账户分析与无凭据的离线 CSV / 持仓快照复核)、七步工作流、输入输出契约,并结合仓库源码解释校验规则、数值精度与对账门禁的实现细节。读完后你应能独立跑通离线复核、正确配置 Alpaca MCP、并在 core-portfolio-weekly 之前完成只读对账。
1. 技能定位:一个技能,两条能力边界
该技能的核心描述是:通过 Alpaca MCP Server 拉取实时持仓,再做资产配置、风险指标、个股评估、分散度与再平衡建议的综合分析,并生成带可执行结论的组合报告(见 SKILL.md)。
需要特别注意仓库对该技能做了明确的能力分档,这也是理解后续所有命令的前提:
| 通路 | 数据来源 | 是否需要凭据 | 能算什么 | 不能算什么 |
|---|---|---|---|---|
离线持仓复核(portfolio-holdings-review) |
本地 CSV 或已保存的 Alpaca /v2/positions JSON |
不需要 | 毛持仓权重、单仓位未实现盈亏 | 账户权益、现金、杠杆、行业/beta、历史收益、股息健康、交易建议 |
全账户分析(core-portfolio-weekly 等) |
Alpaca MCP Server 或 REST fallback | 需要 Alpaca 凭据 | 上述全部组合级指标 | 不下单、不修改交易论点 |
代码里把这条边界写进了输出本身:离线报告的 limitations 列表逐条声明“权重基于毛持仓价值而非账户权益”“现金、杠杆、行业/beta、历史收益与交易建议不可用”“无券商访问、无订单执行、不改动 trader-memory”,实现位置见 review_csv.py。这是让 Agent 与 LLM 能正确引用该报告的关键设计——结论自带适用范围。
何时触发这个技能
文档列出的触发语句覆盖了组合级请求:分析我的组合、复核当前持仓、我的资产配置是什么、检查组合风险、是否需要再平衡、评估我的持仓、组合业绩回顾、该买该卖哪些股票,以及任何涉及组合层面分析或管理的请求。
反过来,两类场景应当明确拒绝或转交:
- 只有本地文件、不想暴露账户凭据 → 走
portfolio-holdings-review,不要伪装成全账户分析; - 需要行业配置、杠杆、股息审查、交易建议 → 必须走带对账门禁的全账户流程。
2. 前置条件:三条数据通路
2.1 离线 CSV / 快照通路(无凭据)
适合用本地 USD 股票持仓快照做一次轻量配置复核。要求提供真实输入路径和一个带时区的快照时间戳;技能本身不校验价格、归属、完整性或新鲜度。文档明确提示:Navigator 只是“推荐”这条工作流,它不会读取或检查你的文件,实际执行必须由 --input 与 --as-of 驱动。
同时必须遵守:个人持仓与生成的报告留在本地,不要提交或上传。
2.2 Alpaca MCP Server(全账户分析)
全账户分析要求 MCP Server 已配置并连接,它提供当前持仓、账户权益与购买力、历史持仓与成交、持仓标的市场数据。技能消费的 MCP 工具是:
get_account_info—— 账户权益、购买力、现金余额;get_positions—— 全部持仓的数量、成本基础、市值;get_portfolio_history—— 历史业绩序列;- 以及用于报价与基本面的行情工具。
若 MCP 未连接,技能应说明依赖并给出 references 中的配置步骤(alpaca-mcp-setup.md)。
2.3 REST fallback 连接自检
定时任务(Hermes 计划任务)里即使有凭据,MCP 工具也可能不暴露。为此技能提供了 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
脚本行为可从源码确认(check_alpaca_connection.py):
- 只从环境变量读取
ALPACA_API_KEY/ALPACA_SECRET_KEY/ALPACA_PAPER,缺一即打印配置指引并以1退出; ALPACA_PAPER默认为true,据此在https://paper-api.alpaca.markets与https://api.alpaca.markets之间切换;- 请求超时固定 30 秒,账户端点要求响应包含
status、account_number、equity、cash、buying_power、portfolio_value; - 账户号经
mask_identifier()脱敏为****加末四位后输出; - 401 会提示“凭据无效 / 纸面密钥配了实盘 URL / 密钥已撤销”,403 提示权限不足,网络异常单独归类;
- 只有账户与持仓端点都成功才返回 0,且不写报告文件、不下单。
安全约束:先用纸面凭据,切勿把密钥写进报告或提交到仓库。
3. 快速开始
原文给出的最小命令是:
# 测试 Alpaca 连接
python3 skills/portfolio-manager/scripts/check_alpaca_connection.py
# 组合分析由 Claude 通过 Alpaca MCP 工具完成
# 配置见 portfolio-manager/references/alpaca-mcp-setup.md
需要注意:check_alpaca_connection.py 依赖 requests,仓库在 requirements.txt 中声明了 requests>=2.31.0 作为独立 .skill 包安装时的运行依赖。若未安装,脚本会打印 pip install -r .../requirements.txt 并以 2 退出——这是国内镜像/离线环境下最常见的失败点之一。
离线路径则完全没有第三方依赖,仅用标准库,Python 3.9+ 即可运行。
4. 七步工作流详解
Step 1:抓取组合数据
1.1 账户信息:账户权益(组合总市值)、现金余额、购买力、账户状态。 1.2 当前持仓:代码、持有数量、平均成本、当前价、当前市值、未实现盈亏(金额与百分比)、仓位占组合比例。 1.3 组合历史(可选):历史权益曲线、时间加权收益、回撤分析。
MCP 与 REST 的端点、请求头对照被抽到独立参考文件里,避免 SKILL.md 膨胀(alpaca-data-fetch.md):paper 为 https://paper-api.alpaca.markets/v2/account、/v2/positions、/v2/account/portfolio/history,live 为 https://api.alpaca.markets/...,请求头是 APCA-API-KEY-ID 与 APCA-API-SECRET-KEY。
定时任务兜底纪律(这是很多自动化组合复盘的坑):
- 数据来源必须标注为
Alpaca REST fallback,不能冒充 MCP; - 仍要校验多头市值加现金是否与权益大致对账;
- 若
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生成税务规划输入,并在账户类型或持有期窗口缺失时标注为降级结果。
数据校验四项:所有持仓代码有效;市值之和近似等于账户权益;检查陈旧或已失效持仓;处理零股、期权、加密等边界情况。
Step 2:持仓数据补全
对每个持仓补充三类信息:
- 行情:实时/延时报价、日均成交量与流动性、52 周区间、市值;
- 基本面:行业与板块分类、P/E、P/B、股息率等估值指标、近期财报与财务健康、分析师评级与目标价、重大新闻;
- 技术面:20/50/200 日均线趋势、相对强度、支撑阻力、RSI/MACD 等动量指标。
Step 3:组合层分析
3.1 资产配置按四个维度横向切分:资产类别(股票/固收/现金/另类)、行业(并对比 S&P 500 等行业权重识别集中风险)、市值分布(大盘/中盘/小盘、超大盘集中度)、地域(美国/国际发达/新兴市场)。
3.2 分散度:头部持仓合计权重;单仓超过 10–15% 需标记;用 HHI 量化集中度;行业集中超过 30–40% 需标记;大仓位之间的相关性是否造成“伪分散”;持仓数量最优区间为 15–30 只(少于 10 只欠分散、多于 50 只过度分散)。
HHI 的计算口径在参考文件中给出:HHI = Σ(w_i × 100)²,并配了判别表——低于 1000 为低集中,1000–1800 为中等,1800–2500 为高,2500 以上很高,4000 以上极度集中。文档还给了一个 5 持仓示例(30/25/20/15/10)算出 2250,属于高集中(diversification-principles.md)。
3.3 风险:波动率(以各仓 beta 加权得到组合 beta、单仓波动、有历史数据时的组合标准差)、下行风险(历史最大回撤、当前距峰值回撤、显著浮亏仓位)、风险集中(beta > 1.5 的高波动标的占比、投机/未盈利公司占比、杠杆使用)、尾部风险(黑天鹅暴露、单票集中、行业事件风险)。
3.4 业绩:绝对收益(整体未实现盈亏、涨幅前 5、跌幅后 5)、时间加权收益(YTD、1/3/5 年年化、对比基准)、仓位级统计(盈亏家数比、平均盈利幅度、平均亏损幅度、接近 52 周高/低点的仓位)。
Step 4:重点个股分析
只对权重最大的 10–15 只做深度分析,五个子项:论点验证(当初为何建仓、论点是否兑现或破坏、近期公司动态)、估值(当前指标、历史区间、同业对比,给出高估/合理/低估判断)、技术健康度(趋势方向、相对均线位置、支撑阻力、动量状态)、仓位规模(当前权重是否匹配信心与风险)、行动建议。
行动建议是四个动词,必须显式使用:HOLD(仓位合适、论点完好)、ADD(低配且机会增强)、TRIM(超配或估值透支)、SELL(论点破坏或有更优机会)。
Step 5:再平衡建议
先识别触发条件:偏离目标权重的仓位、需要调整的行业/资产类别、超配待减、低配待加、资本利得等税务影响。
再产出计划:
- TRIM:超阈值偏离、涨幅过大估值偏高、集中度超过 15–20%、论点破坏;
- ADD:低配的行业或资产类别、高信心但当前低配、能改善分散度的新机会;
- 现金部署:现金超过组合 10% 时建议投放,并按机会与配置缺口排序。
优先级排序统一为四级:Immediate(降低风险,如削减集中仓位)、High(配置漂移 > 10%)、Medium(漂移 5–10%)、Low(微调与机会型调整)。
参考文件给出了更细的阈值体系:漂移 <3% 仅观察、3–5% 可选、5–10% 建议再平衡、>10% 立即执行;单票 >15% 立即削减、>20% 紧急削减;任一仓位达到目标权重两倍时应复核并倾向削减(rebalancing-strategies.md、asset-allocation.md)。阈值法、日历法、混合法(推荐:季度检查 + 漂移 >5% 才动手)、现金流法与战术法的取舍也在同一份参考中展开。
Step 6:生成组合报告
报告以 Markdown 落盘到仓库根目录,文件名固定为 portfolio_analysis_YYYY-MM-DD.md。完整骨架从执行摘要到附录定义在 report-section-templates.md:执行摘要、持仓总览、资产配置、分散度分析、风险评估、业绩回顾、个股分析、再平衡建议、行动项、附录全持仓。同一文件还提供各节的输出模板(资产配置、分散度、风险、业绩、个股、再平衡),文档强调模板中的数值为示意值,不是真实数据。
Step 7:交互式追问
常见追问的应答口径集中在 follow-up-and-advanced.md,包括税务亏损收割、股息收入、相关性与情景分析等进阶话题,以及按分析类型分组的示例提问。
5. 离线持仓复核:命令与输入契约
这是文档中最“可直接跑”的部分,也是最容易被误用的部分。仓库根目录下执行:
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
如果使用打包后的独立 .skill 目录,则在解压目录内执行:
python3 scripts/review_csv.py \
--input assets/fictional_holdings.csv \
--as-of 2026-10-20T12:00:00Z --output-dir reports
自带的 fixture 是虚构 USD 股票,用于验证离线可执行;换成自己的文件时,必须提供真实的源快照时间戳——脚本不会验证价格、归属、完整性或新鲜度,也从不抓取行情。
5.1 CSV 输入契约
UTF-8(可选 BOM)、单行表头、逗号分隔、最多 10,000 条持仓。必需表头:symbol,asset_type,quantity,direction,price,currency;可选表头:cost_basis,account。表头顺序任意;未知、缺失、重复表头均为错误;每条记录的字段数必须与表头宽度一致。
| 字段 | 契约 |
|---|---|
| symbol | 去除首尾空格并转大写;[A-Z][A-Z0-9.-]{0,23}。由操作者保证它确实指向目标标的 |
| asset_type | 必须为 equity;期权、期货等其他品种不支持 |
| quantity | 正数股数,支持零股 |
| direction | 必须为 LONG 或 SHORT;数量恒为正 |
| price | 正数的快照每股价格,由操作者提供 |
| currency | 必须为 USD;不支持汇率换算 |
| cost_basis | 可选,非负的每股取得成本;空白或缺失表示未知。不含费用、股息与税务调整 |
| account | 可选但会被忽略,报告前丢弃。一次只复核一个账户,绝不能用该列推断账户完整性 |
数值规则相当严格:纯无符号十进制表示,最多 32 个字符、最多 12 位小数、不得超过 1e12;指数、正负号、空白、NaN、infinity、数量或价格为零都非法;成本基础允许为 0。归一化后重复的 symbol(包括不同税批或一多一空两行)会被拒绝——必须人工合并为单一持仓,不允许为了让校验通过而对冲净额。空文件或仅有表头也会失败,因为该工具无法证明“账户是空的”。
这些规则在源码中一一对应(review_csv.py、review_csv.py):正则 [0-9]+(?:\.[0-9]{1,12})? 限制数字形态与小数位,value > Decimal("1e12") 与 value < 0 拦截越界,symbol 用 [A-Z][A-Z0-9.-]{0,23} 校验并放进 seen 集合去重,direction 只接受 LONG/SHORT,asset_type != "equity" or currency != "USD" 直接报错。
5.2 保存的 Alpaca 持仓快照
同一套受限分析也能吃“从 /v2/positions 端点保存下来的 JSON 列表”。保存动作由你现有的只读券商连接完成,该命令本身不连接 Alpaca:
python3 skills/portfolio-manager/scripts/review_csv.py \
--input skills/portfolio-manager/assets/fictional_alpaca_positions.json \
--input-format alpaca-json --as-of 2026-10-20T12:00:00Z --output-dir reports
只有下列字段进入共用校验器/计算器:
| Alpaca 字段 | 必需映射 |
|---|---|
symbol |
字符串,按 CSV 规则归一化与校验 |
asset_class |
字符串,必须为 us_equity,映射为 equity |
qty |
字符串;side=long 时严格为正,side=short 时严格为负;其无符号量级遵循 CSV 数值限制 |
side |
字符串,必须为 long 或 short,映射为 LONG/SHORT |
current_price |
字符串,正当的美元每股价格,最多 12 位小数,映射为 price |
avg_entry_price |
可选字符串,非负每股成本,最多 12 位小数,映射为 cost_basis;null、空串或缺失表示不可用 |
currency |
若提供必须为 USD;未提供的 us_equity 快照按 USD 处理 |
其余字段一律忽略,包括账户/资产 ID、名称、券商口径合计、cost_basis(那是仓位总额而非每股价格)、权重与券商算好的盈亏。缺失每股成本保持“不可用”,适配器不会用仓位总额反推。数字必须是 JSON 字符串而非浮点数,以免精度被静默改写。
源码层面,适配器先把原生结构逐条转换成 CSV 行再复用同一套逻辑,从而保证两种输入的计算结果完全一致(review_csv.py):它校验 symbol/asset_class/qty/side/current_price 必须都是字符串,拒绝非 us_equity 或非 USD,short 的数量必须以 - 开头并去掉负号后交给无符号契约,long 之外的值报错;最后把来源标记改写为 alpaca_positions_snapshot。诊断信息还会把 invalid price / invalid cost_basis 改写为原生字段名 current_price / avg_entry_price,行号也从 CSV 的 1-based 行号折算成 position N(review_csv.py)。
5.3 共用输出契约
两种格式都写出 portfolio_csv_review.json 与 portfolio_csv_review.md 到输出目录,并覆盖同名旧报告。历史文件名不代表输入来源,必须读 provenance.source;想保留历史请换新目录。
退出码约定:校验错误返回 1,向 stderr 输出带行号/字段上下文的安全诊断,且不生成任何报告;参数错误返回 2;I/O 错误返回 1,若写到一半失败应丢弃两份文件后重跑。已存在的报告不能证明最近一次调用成功。
JSON 结构由 holdings-review.schema.json 定义(schema_version: 1、report_type: holdings_allocation_only、additionalProperties: false):
provenance:source为local_csv或alpaca_positions_snapshot,as_of为 UTC 时间戳且必须以Z或+00:00结尾,freshness: operator_asserted——这是操作者给的源快照时间,不是伪造的抓取时间;gross_holdings_value:所有仓位quantity × price之和;net_holdings_value:带符号合计(空头为负)。两者都不是账户权益;positions:按规范化 symbol 排序,含direction、quantity、price、currency、可空cost_basis、gross_market_value、net_market_value、gross_weight_pct、可空unrealized_pnl。所有小数以字符串形式输出以保留精度;权重以毛持仓价值为分母,四舍五入到 6 位小数百分比,因此可能不等于 100;unrealized_pnl:quantity × (price − cost_basis),空头反号;成本未知则为null,Markdown 中渲染为unavailable。不输出合计盈亏;limitations:显式列出不可用的分析与集成边界。
用两个虚构 fixture 可以手算验证一致性:FICTA 持有 2.5 股、现价 20、成本 15 → 毛值 50,权重 62.5%,浮盈 2.5 × (20−15) = 12.5;FICTB 空 1 股、现价 30、成本 40 → 毛值 30,权重 37.5%,浮盈 −1 × (30−40) = 10。合计毛值 80、带符号净值 20。测试 test_cli_fixture_is_offline_and_redacts_errors 正是断言 gross_holdings_value == "80",并同时验证空网络访问、错误信息不含输入文件名、校验失败时不创建输出目录(test_review_csv.py)。
实现上还有两个值得注意的工程细节:
- 定点精度:计算放在
localcontext()里并把prec设为 80,理由是行数上限 10,000、单字段上限 1e12 且最多 12 位小数,乘积与求和在 80 位十进制有效数字内可以精确表示,只有权重比值需要舍入(review_csv.py)。这解释了为什么报告里的数字是字符串而不是浮点数。 - 不覆盖输入:写报告前会检查目标路径与输入是否同一文件(含
samefile与软链接解析),并用NamedTemporaryFile+replace()原子落盘(review_csv.py)。test_output_alias_cannot_destroy_input与test_symlink_loop_has_safe_diagnostic覆盖了这类破坏性边界。
6. 每周复核前的只读对账门禁
全账户流程里最容易出问题的环节不是分析,而是“券商实际持仓”和“交易者记忆里记录的论点生命周期”对不上。技能为此提供了一个离线、手工准备、只读的门禁:在抓取持仓之后、做配置/再平衡复核之前运行。它永不下单、不修改论点、不静默修复差异。
6.1 准备两份可比的快照
需要按固定 JSON 契约准备两份本地文件,虚构示例如下(position-reconciliation.md):
{
"schema_version": 1,
"account_scope": "paper_demo",
"as_of": "2026-10-09T12:00:00Z",
"complete": true,
"positions": [
{"symbol": "FICTA", "asset_type": "equity", "direction": "LONG", "quantity": "0.125"}
]
}
关键要求:
- 两份文件必须使用相同的完整账户范围与相同快照时刻;账户用非敏感别名,绝不用账号本身;
as_of必须带时区(等价偏移可接受),且是真实抓取瞬间,不是论点创建日期;抓取期间若有变动需重新抓取,不允许把旧数据贴上新时间戳绕开门禁; - 只有在确认所选账户内全部未平仓股票持仓都被表示(包括记忆里没有的仓位)之后才可置
complete: true;positions: []表示“已验证的空账户”,而不是“导出失败”; - 券商的股票/ETF 持仓映射为
symbol、asset_type: equity、显式LONG/SHORT与正的剩余股数绝对值;若券商用负数编码空头,先确认其方向字段一致再取绝对值,符号冲突必须人工解决;现金省略;不能为了通过而省略不支持的期权、加密或期货——只要出现这类工具,这个仅限股票的设防门禁就不再适用,必须转人工复核; - 交易者记忆侧要取 ACTIVE 与 PARTIALLY_CLOSED 两种状态。
thesis_store.py list(或query()/list_active())返回的是轻量索引项而非完整持仓记录,只用list_active()还会漏掉部分平仓。流程是:先跑只读的doctor检查文件/索引一致性,再枚举两种状态、用get/get()载入完整论点、用validate_thesis()校验;不要在这个门禁里执行rebuild-index; - 记忆侧映射:
ticker→ symbol,方向固定为 LONG(当前股票生命周期仅多头),position.shares_remaining→ quantity。绝不能用原始position.shares代表已减仓的剩余量;老的 ACTIVE 记录若缺剩余数量,必须人工解决而不是随便兜底。排除 IDEA、ENTRY_READY、CLOSED、INVALIDATED;期货以合约计,此处不支持;不要把记忆里额外的position.direction字段当成股票的权威方向; - trader-memory 目前没有原生账户归属,操作者必须逐条确认论点属于该账户,归属含糊即阻断复核;重复 symbol(包括反向)一律拒绝,多论点同标的、分账户记录必须人工归并,不得静默求和或长短对冲;
- 数量可用 JSON 数字或十进制字符串(字符串保留零股精度),接受区间为 1e-12 到 1e12 股、最多 64 字符;零、负数、布尔、非有限值与缺失都会阻断门禁。symbol 与标的身份(改名、多股份类别)需人工确认。
6.2 运行对账
python3 skills/portfolio-manager/scripts/reconcile_positions.py \
--broker reports/broker-normalized.json \
--memory reports/memory-normalized.json \
--output-dir reports/portfolio-reconciliation
命令只读本地文件,向指定目录写 reconciliation_report.json 与 reconciliation_report.md,并把 JSON 打印到 stdout;省略 --output-dir 则只输出到标准输出;两份输入文件保持不变。报告仍含敏感的数量与账户别名,必须私有保存,不要提交真实快照或报告。
6.3 状态语义
报告级状态:
| 状态 | 含义 | 门禁结果 |
|---|---|---|
| MATCH | 每个股票都一致,含两个已验证的空账户 | 核实来源后可以继续配置复核 |
| REVIEW_REQUIRED | 快照合法但至少有一项差异 | 停止并复核 |
| INVALID_INPUT | 不完整、格式错误、重复、不支持或不兼容的输入 | 停止;不写任何报告文件 |
条目级状态:
| 状态 | 含义 |
|---|---|
| MATCH | 剩余数量与方向一致 |
| BROKER_ONLY | 券商有仓、记忆无对应持仓 |
| MEMORY_ONLY | 记忆里未平仓、券商已无 |
| QUANTITY_MISMATCH | 剩余股数不同 |
| DIRECTION_MISMATCH | 多空方向不同 |
缺失的数量与方向在 JSON 中为 null,Markdown 中显示为 -。条目按 symbol 排序,十进制数量以字符串输出、不做舍入或容差;若方向与数量同时不同,方向优先,但两者都保留在报告中。只有 can_continue: true 才返回 0;差异、非法输入或写报告失败返回 1;参数错误返回 2。非法输入仍会打印 requires_review: true、can_continue: false 的 JSON。
源码印证了这些语义:reconcile() 先构造一个“默认失败”的报告骨架(status: INVALID_INPUT、can_continue: False),任何校验异常都只填 errors 并原样返回,因此失败是闭合的(reconcile_positions.py)。差异分类的判定顺序依次是 MEMORY_ONLY、BROKER_ONLY、DIRECTION_MISMATCH、QUANTITY_MISMATCH、MATCH,与文档的描述完全一致(reconcile_positions.py)。读取失败被归类为“文件不存在 / 读错误 / 编码错误(期望 UTF-8)/ 非法 JSON / 重复 JSON 键 / 嵌套过深”,且诊断不泄露路径与内容(reconcile_positions.py);_unique_object 与 parse_float=Decimal 的组合保证重复键和浮点精度都不会被悄悄吞掉。写报告前同样有“不得覆盖输入快照”的检查(reconcile_positions.py)。
重要限定:MATCH 依赖操作者对完整性、账户归属与新鲜度的断言,工具无法验证实时数据,也无法发现故意做成不完整的规范化导出;can_continue 只允许人工配置复核,从不授权下单或自动修改论点。差异应通过另行复核的券商或记忆生命周期操作修复,然后重新抓取再比对。
6.4 自动化现状
这份门禁目前是“离线比对工具 + 文档化的人工流程”。自动券商导出、自动完整记忆导出与账户归属、机器强制的回放门禁仍属于 Issue #493 的后续工作。core-portfolio-weekly 已有的回放 fixture 覆盖的是更早的持仓/配置/股息/再平衡/日志契约,它们不会执行或验证这个新的对账门禁;那些历史回放通过只能作为回归证据。
7. 分析框架:目标配置与风险画像
技能内置四档投资者画像的目标配置模型(target-allocations.md):保守(保本与收入导向)、稳健(增长与收入平衡)、成长(长期资本增值)、激进(最大增长、高风险承受力)。每个模型都给出资产类别目标、行业指引、市值分布、地域配置与仓位规模规则。以保守档为例,其资产配置树形示例如:
Total Portfolio Allocation:
├── Equities: 30%
│ ├── US Stocks: 20%
│ ├── International Developed: 7%
│ └── Emerging Markets: 3%
├── Fixed Income: 55%
│ ├── Investment Grade Bonds: 30%
│ ├── Government Bonds: 20%
│ └── High Yield Bonds: 5%
├── Cash & Equivalents: 10%
└── Alternatives (Optional): 5%
当用户没有明确配置策略时,这些模型作为对比基准使用。
若用户的目标配置未知,则用 risk-profile-questionnaire.md 的问卷框架,从年龄、投资期限、当前实际配置(反映真实偏好)、持仓类型(保守还是投机)等线索推断合适画像。注意推断要有依据,报告里应说明这是推断而非用户声明。
8. 输出规范:让报告可被机器引用
文档对文风与呈现提出了可检验的要求:
- 语气:客观分析、建议必须带清晰理由、承认市场预测的不确定性、在乐观与风险意识之间平衡、尽可能量化;
- 数据呈现:对比与指标用表格、配置与收益用百分比、绝对金额用美元、全文格式一致;
- 建议清晰度:显式动作动词(TRIM/ADD/HOLD/SELL)、由实时仓位与当前价格推导出的具体数量、优先级标签、逐条理由;
- 可视化描述:把配置拆解按饼图口径描述、行业权重按柱状图口径描述、趋势用 ↑ ↓ → 方向标记。
这套规范的价值不止于可读性:当报告被 Agent 或 LLM 二次消费时,固定的动词、优先级枚举与百分比口径本身就是结构化信号。
9. 错误处理矩阵
| 情形 | 应有行为 |
|---|---|
| Alpaca MCP 未连接 | 全账户分析说明依赖并给出配置步骤;本地持仓复核改走 portfolio-holdings-review 与 CSV/快照契约,并先声明其不可用的账户级分析再解释结果 |
| API 返回数据不完整 | 用已有数据继续,在报告中注明局限,对缺失仓位建议人工核验 |
| 持仓数据疑似陈旧 | 标记问题,建议刷新连接或检查 Alpaca 状态,继续分析但给出警示 |
| 用户没有任何持仓 | 承认空组合,转为组合构建指导而非分析,可建议用 value-dividend-screener 或 us-stock-analysis 找标的 |
文档对第一条尤其强调顺序:先声明能力缺失,再解读数字。这与离线报告内嵌 limitations 的做法同源——避免读者把毛权重当成账户暴露。
10. 隐私边界与免责声明
隐私方面(csv-holdings-review.md):没有网络、券商访问、订单、记忆修改或对账门禁;输入文件名/路径、账户字段与 ID 都被排除在脚本诊断与输出之外。但报告本身仍包含可能敏感的持仓、数量与成本数据,必须本地保存、不得提交或上传。这是字段最小化而非匿名化;CLI 参数与路径可能残留在 shell 历史里;永远不要把密钥放进命令、CSV 或保存的 JSON。
所有报告都应附上两段免责声明:
本分析仅供信息参考,不构成投资建议。投资决策应基于个人情况、风险承受能力与财务目标。历史业绩不保证未来结果。做出投资决策前请咨询合格的财务顾问。
数据准确性取决于 Alpaca API 与第三方行情源。关键信息请独立核实。税务影响仅为估算,具体请咨询税务专业人士。
11. 回放与测试:这些约束是被验证过的
仓库为这条纯离线通路准备了原生回放:replay.yaml 固定时间戳 2026-10-20T12:05:00+00:00,输入为 replay-inputs/holdings.csv 与 replay-inputs/context.json,单步执行器 portfolio_holdings_review、executor_mode: native_cli、gate_policy: continue,产物分别对应 JSON 与 Markdown 两种角色,并区分 required-only 与 full-path 两个变体。
执行器实现(steps_portfolio_holdings.py)体现了这条通路的三条硬约束:
- 不消费上游产物——若
consumed非空直接抛ReplayError,因为离线复核不接任何前置分析; - 强制虚构输入——上下文必须含
fictional与as_of,且fictional is not True时拒绝运行,防止真实持仓被当作回放数据; - 只调用 CLI、不碰券商与日志——它用
sys.executable调review_csv.py,再把portfolio_csv_review.json/.md复制为阶段产物,全程没有 broker 或 journal 步骤。
测试矩阵也把边界钉死了:CSV 侧覆盖小数多空精确值、缺成本时的 unavailable、非法输入不回显私有值、数值上下限、零值规则、带时区时间戳、10,000 行上限、输出别名不得破坏输入、软链接循环的安全诊断(test_review_csv.py);Alpaca 适配侧覆盖两种输入计算结果完全一致、原生字段非法时不回显、空头数量符号、必需字段、畸形/空快照、重复 symbol 与行数上限、可选每股成本、零点盈亏、诊断字段名改写、共享 JSON Schema 覆盖两种报告、CLI 离线且沿用既有输出名(test_review_alpaca.py);对账侧覆盖各状态分类、两个空账户与等价时间戳、非法数量、不完整/不兼容记忆、重复身份、排序确定性与不修改输入、CLI 不触网、非法输入不落盘、拒绝覆盖输入、硬链接防护、读失败分类、缺失值保持 JSON null(test_reconcile_positions.py)。
12. 建议的使用路径
- 第一次接触:用自带虚构 fixture 跑一遍离线复核,确认 Python 版本与输出目录行为,再读 JSON 里的
limitations理解边界; - 日常轻量复核:把自己的券商导出整理成 CSV(或在只读连接下保存
/v2/positions响应),提供真实--as-of,每次写入新的输出目录以保留历史; - 每周核心组合:配置 Alpaca MCP;先跑连接自检,再抓账户与持仓,跑
reconcile_positions.py通过门禁后才进入配置/再平衡分析; - 定时任务:明确标注
Alpaca REST fallback,用权益作分母复核暴露与杠杆,涉及股息或税务时把规范化输入交给对应技能而不是写成叙述; - 产出报告:按 report-section-templates.md 的骨架组织,保持动作动词与优先级枚举一致,并附上免责声明。
更多上下文可参考工作流总览中的 Offline Holdings Review 一节,以及技能源码目录 skills/portfolio-manager。