claude-trading-skills 离线持仓复核实战:`review_csv.py` 的 CSV 与 Alpaca 快照契约全解

原创2026-11-15 21:30:561,415 阅读
文章标签:金融科技AI 技能人工智能数据分析

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 两个报告文件的写出目录,不存在会自动创建

执行链路的顺序值得注意:

  1. 打开输入流(utf-8-sig + newline="",避免 CSV 模块处理换行时出错);
  2. 若 --input-format alpaca-json,先 json.load,再交给适配器;否则直接 build_report;
  3. 校验全部通过后才创建输出目录并写文件;
  4. 写文件采用 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. 建议的使用姿势

  1. 一次一个账户。把导出范围收敛到单一账户,避免在无对账能力的前提下产生跨账户混淆。
  2. 为每次运行分配唯一输出目录,例如 reports/holdings-2026-10-20/。脚本会覆盖同名报告,用目录隔离历史比事后追溯更可靠。
  3. 如实填写 --as-of。它不会让数据变「新鲜」,但会让报告中的 freshness: operator_asserted 有据可查。
  4. 把 limitations 一并交付。这份报告是配置视图与逐仓盈亏,不是风险报告;引用结论时连同六条限制一起转述,避免被误读为账户暴露或交易许可。
  5. 需要完整结论时回到对账路径。先按 position-reconciliation.md 用 reconcile_positions.py 比较券商与 ACTIVE / PARTIALLY_CLOSED 记忆快照,can_continue 为真后再进入分配与再平衡评审;离线 CSV 复核不承担这一步。

把 review_csv.py 当作一台契约严格的十进制计算器,而不是一个数据可信度裁判——理解它的边界,正是这条离线通道能安全用于真实持仓记录的前提。

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