claude-trading-skills 离线持仓复核实战:`review_csv.py` 的 CSV 与 Alpaca 快照契约全解
claude-trading-skills 离线持仓复核实战:review_csv.py 的 CSV 与 Alpaca 快照契约全解
portfolio-manager 技能除了依赖 Alpaca MCP 的完整券商分析路径外,还提供了一条完全离线、零凭证的轻量通道:把本地 USD 股票持仓快照交给 review_csv.py,得到总持仓市值、符号化净市值、每只标的的毛权重与逐仓未实现盈亏。本文以技能参考文档 csv-holdings-review.md 为骨架,完整继承其输入/输出契约,并结合 review_csv.py、holdings-review.schema.json 与配套测试,逐层拆解校验规则、数值精度、退出码与隐私边界的实现细节。
1. 这条路径解决什么问题,又明确不解决什么
在 SKILL.md 中,portfolio-manager 的主线流程是「MCP 取数 → 行业/市值/地域配置分析 → 分散度与风险指标 → 个股点评 → 再平衡建议」,全部以券商账户数据为前提。而离线复核是它的受限子集:
| 维度 | 完整券商分析(core-portfolio-weekly) |
离线受限复核(portfolio-holdings-review) |
|---|---|---|
| 数据来源 | Alpaca MCP / REST,实时账户数据 | 本地 CSV 或已保存的 Alpaca /v2/positions JSON |
| 凭证要求 | 需要 API Key 与账户权限 | 不需要任何凭证,不发网络请求 |
| 输出 | 配置、风险、绩效、再平衡建议 | 毛/净持仓市值、毛权重、逐仓未实现盈亏 |
| 账户口径 | 以 equity 为分母,可识别杠杆 | 以总持仓市值为分母,无法反映账户暴露 |
| 前置门禁 | 需要 broker ↔ trader-memory 对账(reconcile_positions.py) |
无对账门禁,也不得替代对账 |
文档对此的表述非常克制:脚本「不校验价格、所有权、完整性与新鲜度」,并且「永不获取行情」。换句话说,它做的是在你给定的假设下做确定性算术,而不是替你判断数据是否可信。
运行前提(与原文档一致):仓库根目录执行,Python 3.9+,脚本只使用标准库(argparse / csv / io / json / re / sys / tempfile / datetime / decimal / pathlib),因此不需要安装任何第三方依赖,也不需要设置环境变量。
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 目录(通过 skill-packages/portfolio-manager.skill 解包得到的结构),命令改为在该目录内执行:
python3 scripts/review_csv.py --input assets/fictional_holdings.csv \
--as-of 2026-10-20T12:00:00Z --output-dir reports
内置 fixture fictional_holdings.csv 只包含两只虚构 USD 股票,用于验证「离线可跑通」。对自己真实数据使用时,--as-of 必须填写该快照真实产生的时间,因为后续所有报告都会把它标记为 operator_asserted(操作者断言),而不是脚本探测到的时间。
2. 命令行参数与执行模型
main() 用单个 argparse.ArgumentParser 定义参数,四个选项语义明确:
| 参数 | 必填 | 类型 / 取值 | 默认 | 说明 |
|---|---|---|---|---|
--input |
是 | Path |
无 | 本地 CSV 或本地 JSON 快照;以 utf-8-sig 打开,兼容 UTF-8 BOM |
--as-of |
是 | 字符串,时区感知 ISO 时间戳 | 无 | 快照来源时间,支持 Z 后缀或显式偏移 |
--input-format |
否 | csv | alpaca-json |
csv |
仅对「已保存的 Alpaca 持仓」才切换 |
--output-dir |
否 | Path |
reports |
两个报告文件的写出目录,不存在会自动创建 |
执行链路的顺序值得注意:
- 打开输入流(
utf-8-sig+newline="",避免 CSV 模块处理换行时出错); - 若
--input-format alpaca-json,先json.load,再交给适配器;否则直接build_report; - 校验全部通过后才创建输出目录并写文件;
- 写文件采用
tempfile.NamedTemporaryFile(dir=output_dir, delete=False)+Path.replace()的原子替换。
第 3、4 步的先后顺序直接决定了原文档中「验证错误不产生任何报告」这一承诺:所有 CsvError 都在目录创建之前抛出,因此一次失败的运行不会留下半截产物。
2.1 防止覆盖输入文件
脚本在写报告前做了一次别名检查:如果 portfolio_csv_review.json 或 .md 与 --input 解析为同一路径(Path.resolve() 相等,或 Path.samefile() 成立,后者可捕获硬链接),就直接报错 output must not overwrite the input file。测试 test_review_csv.py 中的 test_output_alias_cannot_destroy_input 正是用 os.link() 构造硬链接来验证这一点——源文件内容在失败后保持不变。
3. CSV 输入契约
3.1 文件形态
UTF-8 CSV(可选 BOM)、一行表头、逗号分隔、最多 10,000 条持仓。必填表头为 symbol,asset_type,quantity,direction,price,currency;可选表头为 cost_basis,account。表头顺序任意,但以下三种情况都视为错误:未知表头、缺失表头、重复表头;每一行的字段数必须与表头宽度一致。
源码中的判定是一行集合运算:
if (
len(headers) != len(set(headers))
or not REQUIRED <= set(headers)
or not set(headers) <= REQUIRED | OPTIONAL
):
raise CsvError("invalid CSV headers; see the documented holdings schema")
这条约束也顺带解释了为什么不能「用别的列名凑合」:REQUIRED 与 OPTIONAL 都是硬编码常量,任何额外的列(例如 market_value、sector)都会让整个文件被拒绝。如果你想补充信息,应放在报告之外的笔记里,而不是扩展 CSV 表头。
3.2 字段级契约
| 字段 | 契约 |
|---|---|
| symbol | 去除首尾空格后转大写;须匹配 [A-Z][A-Z0-9.-]{0,23}。操作者需自行确认它确实指向预期标的。 |
| asset_type | 必须严格等于 equity;期权、期货及其他品种不支持。 |
| quantity | 正股数,支持小数股。 |
| direction | 必须严格是 LONG 或 SHORT;数量恒为正数。 |
| price | 正的单股快照价格,由操作者提供。 |
| currency | 必须严格等于 USD;不提供汇率换算。 |
| cost_basis | 可选,非负的单股买入价;留空/缺失表示未知。不含费用、分红与税务调整。 |
| account | 可选且被忽略的字段,在生成报告前丢弃。一次只复核一个账户;绝不能用它推断账户完整性。 |
account 的处理最能体现「字段最小化」的设计意图:它被允许出现在表头中(方便你直接导出券商视图),但在 build_report 里从头到尾没有被读取,因此不可能进入 JSON 或 Markdown。测试用 assert "private-account" not in json.dumps(result) + render_markdown(result) 把这条约束钉死。
3.3 数字语法与边界
plain unsigned decimal: [0-9]+(\.[0-9]{1,12})?
长度上限:32 字符
数值上限:1e12
不接受:指数、正负号、空白、NaN、Infinity
quantity/price 不得为 0;cost_basis 允许为 0
_number() 的实现把「字符串形态」和「数值范围」分成两道关卡:先用正则挡住科学计数法与符号,再用 Decimal 判断有限性与上界。
if len(raw) > 32 or not re.fullmatch(r"[0-9]+(?:\.[0-9]{1,12})?", raw):
raise CsvError(label)
value = Decimal(raw)
if not value.is_finite() or value > Decimal("1e12") or value < 0:
raise CsvError(label)
if not zero and value == 0:
raise CsvError(label)
注意这里用的是 Decimal 而非 float,这正是文档强调「小数股支持」却不担心精度漂移的原因。报告中的数值反向序列化时统一走 _text():整数不带小数点,带小数时去掉尾随 0("62.500000" → "62.5"),零统一输出 "0"。测试还专门覆盖了 "-0" 这类负零场景,保证短仓盈亏为 0 时输出无符号的 "0"。
3.4 重复标的必须人工合并
大小写与空格归一后(" ficta " → FICTA)出现重复 symbol 即报错 duplicate symbol; consolidate lots manually。文档的立场很明确:不要为了绕过校验而把对冲仓位净额化。如果你确实持有同一标的的多个税批次,先在自己的持仓台账里合并成单一意图持仓,再喂给脚本。同理,direction 分开写成 long/short 两行也会撞上这条重复检查。
空文件与仅有表头的文件同样失败(CSV must contain at least one holding)——脚本不能据此断言「账户为空」。
3.5 行数上限与精度余量
行数检查发生在循环内部:enumerate(reader, 2) 从第 2 行(首条数据)起编号,index > 10001 即触发 CSV row limit is 10000 holdings。也就是说 10,000 行数据是允许区间。
源码注释给出了一条值得记录的设计推理:
# At most 10,000 rows, fields <= 1e12 with <=12 fractional digits:
# products/sums fit exactly in 80 digits; only weight ratios are rounded.
with localcontext() as ctx:
ctx.prec = 80
10,000 × 1e12 × 1e12 的乘积量级仍在 80 位十进制精度内,因此 quantity × price 与累加求和都是精确的,唯一被舍入的是权重比值(quantize(Decimal("0.000001")))。测试用 1000000000000 的数量与价格验证了这一点:毛市值输出为精确的 "1000000000000000000000030",没有出现科学计数法或进位误差。
4. 已保存的 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
内置的 fictional_alpaca_positions.json 与 CSV fixture 描述的是同一组持仓,因此两条命令的结果在计算字段上完全一致。
4.1 字段映射
只有下列字段会进入公共的 CSV 校验/计算器:
| Alpaca 字段 | 必填映射 |
|---|---|
symbol |
字符串,按 CSV symbol 规则归一化与校验 |
asset_class |
字符串,必须为 us_equity,映射为 equity |
qty |
字符串;side=long 时严格为正,side=short 时严格为负;其绝对值遵循 CSV 数值限制 |
side |
字符串,必须为 long 或 short,映射为 LONG / SHORT |
current_price |
字符串,正的 USD 单股价格,最多 12 位小数,映射为 price |
avg_entry_price |
可选字符串,非负单股买入价,最多 12 位小数,映射为 cost_basis;null、空串或缺失表示不可得 |
currency |
若提供必须为 USD;未提供该字段的 us_equity 快照按 USD 处理 |
适配器的实现思路是「先归一化,再复用」:把原生 JSON 逐条转换成一张内存中的 CSV(io.StringIO + csv.writer),然后调用同一个 build_report,最后只改写 provenance.source。这意味着校验规则、算术精度与排序行为不可能在两套格式之间发生漂移——测试 test_equivalent_positions_share_exact_calculations_and_distinct_sources 直接断言除 provenance 外的所有键值相等。
4.2 短仓符号的双重校验
qty 的符号必须与 side 自洽。适配器先剥掉短仓的负号,再让无符号数值走 CSV 契约:
side = position["side"]
quantity = position["qty"]
if side == "short":
if not quantity.startswith("-"):
raise CsvError(f"position {index}: short qty must be negative")
quantity = quantity[1:]
elif side != "long":
raise CsvError(f"position {index}: side must be long or short")
try:
_number(quantity, index, "qty")
except CsvError as exc:
raise CsvError(f"position {index}: invalid qty") from exc
这段顺序很关键:先判断符号是否匹配,再校验绝对值。测试里 "-0"、"+1"、"--1"、"-NaN"、"-1e100"、"- 1" 全部被拒,说明「负号 + 非法数字」不会因为剥符号而被悄悄放行。所有数值字段都要求是 JSON 字符串而非 float,避免解析阶段就把精度改掉;qty: 2.5 或 qty: true 都会失败。
4.3 被忽略的字段,以及一条容易踩的坑
除上表字段以外,账户/资产 ID、名称、券商汇总值、权重、券商侧 P&L 全部丢弃。其中最容易误解的是 cost_basis:在 Alpaca 原始响应里它往往是仓位总成本,而脚本需要的是单股价格。适配器因此完全不读该字段,缺失 avg_entry_price 时就保持「不可得」,绝不会用总成本反推单股成本。测试 test_optional_per_share_basis_and_fractional_short 专门塞入 "cost_basis": "999999" 来验证它不产生影响。
此外,输入必须是非空、最多 10,000 个对象的列表,重复归一化 symbol 与 CSV 同样被拒绝,as_of 也必须时区感知。文档最后一句提醒尤其重要:用当前保存的快照去做历史时点分析,得到的不是 point-in-time 数据——输入与诊断本身不能证明该响应是最新的、完整的或真实的。
5. 共享的受限输出契约
默认的 --input-format csv 保留了既有命令、JSON schema 与文件名。两种格式都会在输出目录写入 portfolio_csv_review.json 与 portfolio_csv_review.md,并覆盖同名旧报告。文件名沿用了历史命名,并不标识输入来源——请阅读 provenance.source 判断;想保留历史就换一个新目录。
5.1 退出码与诊断
| 情形 | 退出码 | 行为 |
|---|---|---|
校验错误(CsvError) |
1 | 向 stderr 输出带行/字段上下文的脱敏诊断,不创建任何报告 |
| 参数错误(argparse) | 2 | 参数用法错误 |
I/O 错误(OSError / UnicodeError / RuntimeError) |
1 | 统一提示「检查编码与权限」;若写入中途失败,丢弃两个报告文件后重跑 |
| 成功 | 0 | stdout 打印 Offline holdings review written (JSON and Markdown). |
诊断消息一律不包含用户提供的值:CsvError 的子类注释写着 "Safe input diagnostic without user-provided values"。当 --input 指向不存在的私有文件名,或 --output-dir 是一个符号链接环时,stderr 只会给出通用提示。测试 test_symlink_loop_has_safe_diagnostic 与 test_cli_fixture_is_offline_and_redacts_errors 都在断言 "private" 不出现在输出中。「已有报告存在」也不能证明最近一次调用成功——因为失败时旧文件可能原封不动。
5.2 JSON 结构
结构 schema 是 holdings-review.schema.json(JSON Schema 2020-12),运行时输入校验负责强制本文所述的数值边界与算术。报告本身是 schema_version: 1 + report_type: holdings_allocation_only:
provenance:source为local_csv或alpaca_positions_snapshot,as_of为 UTC 时间(schema 用pattern: "(?:Z|\\+00:00)$"约束),freshness恒为operator_asserted。这是操作者提供的来源快照时间,不是伪造的抓取时间。gross_holdings_value:所有仓位的quantity × price之和。net_holdings_value:带符号求和(空头为负)。两者都不是账户净值。positions:按 symbol 排序,包含asset_type、direction、quantity、price、currency、可空cost_basis、gross_market_value、net_market_value、gross_weight_pct与可空unrealized_pnl。所有小数值都是字符串以保精度;权重以毛持仓市值为分母,保留六位小数百分比,因此四舍五入后可能不完全等于 100。unrealized_pnl:quantity × (price − cost_basis),空头符号反向。成本未知则为null,Markdown 中渲染为unavailable。不输出合计 P&L。limitations:显式列出不可用的分析与集成边界。
5.3 用 fixture 手算一遍
| symbol | direction | quantity | price | cost_basis | 毛市值 | 毛权重 | 未实现盈亏 |
|---|---|---|---|---|---|---|---|
| FICTA | LONG | 2.5 | 20 | 15 | 50 | 62.5% | 2.5 × (20 − 15) = 12.5 |
| FICTB | SHORT | 1 | 30 | 40 | 30 | 37.5% | 1 × (30 − 40) = −10 → 反向 = 10 |
毛市值 80,净市值 50 − 30 = 20,权重分母是 80 而非 20。这与仓库中的黄金文件 replay-run/01_holdings_allocation_report.md 完全一致;短仓盈亏为正,是因为该仓位「以 40 卖出、当前 30」,属于浮盈,符号反转在 build_report 中由 sign * quantity * (price - basis) 一步完成。
5.4 Markdown 渲染
render_markdown() 只渲染已校验字段,绝不写输入文件名或 account 列。标题随来源切换:local_csv 为 # Offline CSV holdings review,快照为 # Offline saved-position holdings review;正文含一行 Source: …; as-of: … (operator asserted)、毛/净市值两行、六列表格,最后附 ## Limitations 六条。这也是唯一一处两种输入格式输出不同的地方(连同 provenance.source)。
5.5 明确不可用的分析
现金、净值、保证金/杠杆、行业配置、Beta、历史收益、股息健康度与交易建议全部不可得。文档给出了一条容易被忽视的警告:在杠杆账户里,以毛持仓市值为分母的权重看起来很温和,但它既不是账户暴露,也不构成交易授权。完整券商报告有更宽的契约,这个受限契约不能替代它。
源码中的 LIMITATIONS 常量把这层边界写进了每一份报告:
LIMITATIONS = [
"Local snapshot assertions only; identity, completeness and price freshness are unverified.",
"USD equities only. Weights use gross holdings value, not account equity.",
"Cash, leverage, sector/beta, historical returns and trading recommendations are unavailable.",
"P&L is per position only; missing per-share cost basis means unavailable, not zero.",
"No broker access, order execution, or trader-memory changes. Not a reconciliation gate.",
"Limited portfolio-holdings-review path only; full brokerage review requires reconciliation.",
]
6. 隐私与工作流边界
脚本不联网、不访问券商、不下单、不改记忆、也不做对账门禁。输入文件名/路径、account 字段与各类 ID 都被排除在诊断与输出之外。但报告仍然包含可能敏感的持仓、数量与成本数据:请把输入与报告留在本地,不要提交或上传个人数据。这是字段最小化,不是匿名化;CLI 参数与路径还可能留在 shell 历史里。永远不要在命令、CSV 或保存的 JSON 中传递密钥。
集成层面,portfolio-holdings-review 工作流与 Navigator 的本地文件路径都使用这套受限复核。Navigator 只推荐工作流,并不读取或校验你的文件;实际执行必须提供 --input 与一个明确的 --as-of,并且可能因不支持的格式或格式错误而拒绝。它的原生 replay 使用虚构持仓并执行同一个 CLI(见 steps_portfolio_holdings.py,其中还会强制 context["fictional"] is True),不发起券商请求,也不写 journal 或 trader-memory 记录。更宽的 core-portfolio-weekly 仍需 broker/memory 对账与券商访问权限——不要绕过那道门禁,也不要把一份 CSV 配置报告当成完成的全账户复核。
工作流定义本身(portfolio-holdings-review.yaml)把两个手动输入写成了强制项:holdings_input(schema 指向本文档)与 source_as_of(「操作者指定、时区感知的快照时间;不推断新鲜度或完整性」),并在 when_not_to_run 中逐条列出不适用场景。
7. 常见失败原因速查
以下诊断文本均可在 review_csv.py 中检索到,括号内是触发条件:
| 诊断 | 触发条件与处理 |
|---|---|
invalid CSV headers; see the documented holdings schema |
表头重复、缺必填列或出现未知列;只保留六个必填 + 两个可选项 |
row N: wrong field count |
该行字段数与表头不一致,常见于单元格内漏写逗号或引号未闭合 |
row N: invalid equity symbol |
symbol 归一化后不满足 [A-Z][A-Z0-9.-]{0,23},如含 [、NUL 字符或非 ASCII |
row N: duplicate symbol; consolidate lots manually |
同一标的出现多次(含大小写/空格差异、多税批次、多空两行) |
row N: only USD equity holdings are supported |
asset_type 非 equity 或 currency 非 USD |
row N: direction must be LONG or SHORT |
写了 BUY/SELL 等业务动词 |
row N: invalid quantity / invalid price / invalid cost_basis |
出现符号、指数、空白、NaN、Infinity、超过 1e12 或超过 12 位小数;quantity/price 为 0 |
CSV must contain at least one holding |
空文件或仅有表头 |
CSV row limit is 10000 holdings |
数据行超过 10,000 |
malformed CSV or field exceeds parser limit |
csv.Error,如未闭合引号或单字段过大 |
as-of must be a timezone-aware ISO timestamp |
传了 2026-10-20 或 2026-10-20T12:00:00 这类无时区时间 |
output must not overwrite the input file |
输出路径与输入同文件(同路径或硬链接) |
Alpaca 快照路径的诊断会被重写成快照自身的语汇:row 2 变成 position 1,invalid price 变成 invalid current_price,invalid cost_basis 变成 invalid avg_entry_price。这由 _alpaca_diagnostic() 完成,测试 test_diagnostics_use_one_position_number_and_native_names 固定了 position 2: invalid current_price 这类精确文案。因此排错时请按「你实际输入的那种格式」去对照上表,不要把 row N 和 position N 混为一谈(前者是 CSV 物理行号,后者从 1 开始)。
8. 建议的使用姿势
- 一次一个账户。把导出范围收敛到单一账户,避免在无对账能力的前提下产生跨账户混淆。
- 为每次运行分配唯一输出目录,例如
reports/holdings-2026-10-20/。脚本会覆盖同名报告,用目录隔离历史比事后追溯更可靠。 - 如实填写
--as-of。它不会让数据变「新鲜」,但会让报告中的freshness: operator_asserted有据可查。 - 把
limitations一并交付。这份报告是配置视图与逐仓盈亏,不是风险报告;引用结论时连同六条限制一起转述,避免被误读为账户暴露或交易许可。 - 需要完整结论时回到对账路径。先按 position-reconciliation.md 用
reconcile_positions.py比较券商与 ACTIVE / PARTIALLY_CLOSED 记忆快照,can_continue为真后再进入分配与再平衡评审;离线 CSV 复核不承担这一步。
把 review_csv.py 当作一台契约严格的十进制计算器,而不是一个数据可信度裁判——理解它的边界,正是这条离线通道能安全用于真实持仓记录的前提。