claude-trading-skills 数据血缘门禁实战:market-regime-daily 的 provenance 交接设计与实现

原创2026-11-14 21:38:021,858 阅读
文章标签:金融科技AI 技能人工智能数据分析

claude-trading-skills 数据血缘门禁实战:market-regime-daily 的 provenance 交接设计与实现

市场状态(market regime)类技能的价值完全取决于输入数据“是不是同一时刻、同一口径”的。claude-trading-skills 在 Issue #297 中给出的答案,是一个版本化、可校验、可失败关闭的 data_provenance 交接契约。本文以该仓库的 issue-297-regime-provenance.md 为骨架,结合 provenance_contract.py、validate_provenance.py、calculate_exposure.py、replay.yaml 与相关测试,完整还原这条“生产者如实声明 → 消费者严格校验 → 回放确定性验证”的链路。读完后你可以独立复现严格模式的命令行调用、理解每一项时间语义检查的判定顺序,并清楚这套门禁的能力边界在哪里。

一、问题定义与边界:为什么只做“必需的交接”

该计划文档的第一节就把范围钉死了:P1 级 Issue #297 只取一个经 owner 批准的、有界(bounded)的端到端切片,基线提交为 b29c6df。在动手前检查了当时开启的 PR #571–#575 以及既有 worktree,明确要求避开它们涉及的 FMP 客户端、market-top 实现与 03 golden、打包基础设施与 CI hooks。

这一取舍直接决定了后续所有设计:

  • 本次实现的是必需的 breadth / uptrend 交接,而不是全部 FMP 生产者;文档明确写到 “#297 remains open”,即契约本身仍处于未完成的演进状态;
  • 不涉及交易执行,也不做 live 写入,因此所有校验失败都必须表现为“不产出新报告”,而不是任何形式的自动修复;
  • 由于不触碰 market-top 的 03 产物,重放侧要求 03 golden 保持字节一致,这是回归安全的核心约束。

换句话说,这是一次“缩小范围换取端到端可信”的工程决策:先让一条主链路(breadth + uptrend → exposure)具备可验证的数据血缘,再逐步推广。

二、契约层:一份 stdlib-only 的 vendored 校验器

2.1 为什么是“三份完全相同”的文件

三个技能各自保留一份 provenance_contract.py:

这不是疏忽,而是 skill 包的部署形态决定的:每个 skill 要能被单独打包、单独导入、单独运行,因此不能依赖仓库根目录的共享模块。仓库用字节级一致性替代代码复用,三份文件的 MD5 完全一致:

md5sum skills/exposure-coach/scripts/provenance_contract.py \
       skills/market-breadth-analyzer/scripts/provenance_contract.py \
       skills/uptrend-analyzer/scripts/provenance_contract.py
# 474697b359c8e1cf080d090e9e807a68  (三者输出相同)

文件头部注释也把这条约定写成了契约:“Vendored identically in the three market-regime skills. Keep schema validation compatible with scripts/validate_provenance.py; strict policy is separate.” 关键点在于严格策略与 schema 校验分离——共享的 schema 校验函数必须与仓库级 scripts/validate_provenance.py 保持行为兼容,而面向 market-regime-daily 的严格门禁逻辑只存在于 vendored 副本中,不污染通用校验器。

该模块只使用标准库(datetime、typing、urllib.parse、zoneinfo),这也是它能被安全 vendored 的前提:不引入任何第三方依赖,不会与各 skill 的 requirements.txt 冲突。

2.2 Schema 1.0 的字段矩阵

SCHEMA_VERSION = "1.0",必填字段由 REQUIRED_FIELDS 元组集中定义:

字段 类型约束 语义
schema_version 非空字符串,且须等于契约版本 契约版本,当前固定 "1.0"
provider 非空字符串 数据提供方,FMP 场景通常为 fmp
endpoint 非空字符串 产生该行数据的具体端点/数据集
retrieved_at 带时区的 ISO-8601 时间戳 抓取实际发生时刻,严格模式要求 UTC
as_of YYYY-MM-DD 日期或带时区时间戳 数据描述的业务日期,而非报告生成时间
timezone 合法 IANA 时区名 数据申报所依据的报告时区
adjusted 布尔 是否做拆股/分红调整
point_in_time 布尔 是否无前视(point-in-time)
survivorship_free 布尔 是否包含已退市标的
corporate_actions_handled 布尔 返回行是否已处理公司行为

校验规则由 validate_provenance() 实现,返回错误字符串列表,空列表才代表通过。除必填检查外还有几处值得注意的实现细节:

  • 未知字段被有意放行,源码注释写明 “Unknown fields are intentionally permitted so the contract can be extended.” 这使得 run_id、scope、auxiliary_sources 这类扩展字段可以安全附加,而不会破坏 1.0 兼容性;
  • 布尔字段拒绝真值:_is_bool 使用 isinstance(value, bool),因此 "true"、1 都会被判为非法,错误信息还特别提示 “state honestly, e.g. False”,即不知道就必须写 False 而不是省略;
  • 时区必须真实存在:通过 ZoneInfo(block["timezone"]) 实例化,捕获 KeyError/ValueError。中文读者常犯的错误是写 "CST"、"EST" 这类缩写,它们不是合法 IANA 名称,会被直接拒绝;
  • retrieved_at 必须带时区:_is_iso_datetime 解析后强制 parsed.tzinfo is not None,裸时间戳 2026-01-15T13:08:00 不通过。

2.3 build_provenance():生产者的唯一入口

生产者不应手写字典,而是调用:

def build_provenance(*, provider, endpoint, retrieved_at, as_of, run_id,
                     timezone_name="America/New_York") -> dict:

它做了三件重要的事:

  1. 组装 schema_version="1.0" 的完整块,并把四个质量标志硬编码为 False:adjusted、point_in_time、survivorship_free、corporate_actions_handled。这是“诚实声明”原则的实现——当前 CSV 数据源确实不具备这些保证,就明确写 False,绝不猜测为 True;
  2. 自动附带 scope: "primary timeseries only; auxiliary source dates unverified",把“辅助数据源日期未经核实”这一限制固化进产物;
  3. 调用 validate_provenance() 自检,并在 run_id 为空时抛 ValueError。生产者侧的第一道防线由此建立:如果主数据的 as_of 缺失或格式非法(例如取到 None),build_provenance 会直接抛错,进程终止,而不是吐出一份血缘残缺的报告。

此外还有 safe_source_url(),用于在 endpoint 中保留来源身份但剥离敏感信息:

urlunsplit((parsed.scheme, host, parsed.path, "", ""))

即丢弃 query 与 fragment,并按需给 IPv6 主机加方括号。这样即便 URL 里带了 API token 查询参数,也不会被写进报告。

三、生产者改造:让 as_of 说真话

3.1 breadth 分析器

在 market_breadth_analyzer.py 中,新增参数与血缘构造如下:

parser.add_argument("--run-id", default=None, help="Shared workflow run identifier")
...
provenance = build_provenance(
    provider="trader-monty" if args.detail_url == DEFAULT_DETAIL_URL else "custom-csv",
    endpoint=safe_source_url(args.detail_url),
    retrieved_at=datetime.now(timezone.utc).isoformat(),
    as_of=detail_rows[-1].get("Date"),
    run_id=args.run_id or uuid4().hex,
)

provenance["auxiliary_sources"] = [
    {"endpoint": safe_source_url(args.summary_url), "as_of_verified": False}
]

这里体现了计划文档第 2 条的全部要求:

  • --run-id 缺省时用 uuid4().hex 生成唯一的 run id,保证单次运行至少自洽;
  • retrieved_at 在抓取成功之后取 datetime.now(timezone.utc),而不是程序启动时刻;
  • as_of 取主数据最后一行的实际日期 detail_rows[-1]["Date"],绝不使用报告时钟;
  • provider 会根据是否使用默认 URL 自动降级为 custom-csv,避免把自定义数据源冒充成官方源;
  • 辅助数据源(summary CSV)只登记 endpoint,并显式标注 as_of_verified: False——登记但不认证;
  • 若主数据为空则更早处已 sys.exit(1);若 Date 字段缺失/非法,则由 build_provenance 抛错拒绝。

该模块注释还明确“不改变金融打分”,所以 6 个组件的权重逻辑、check_data_freshness 的告警语义都保持原样。

3.2 uptrend 分析器

uptrend_analyzer.py 结构一致:

parser.add_argument("--run-id", default=None, help="Shared workflow run identifier")
...
provenance = build_provenance(
    provider="trader-monty",
    endpoint=TIMESERIES_URL,
    retrieved_at=datetime.now(timezone.utc).isoformat(),
    as_of=latest_all.get("date") if latest_all else None,
    run_id=args.run_id or uuid4().hex,
)
provenance["auxiliary_sources"] = [{"endpoint": SECTOR_SUMMARY_URL, "as_of_verified": False}]

区别在于 as_of 来自 get_latest_all() 的 date,辅助源为 sector summary 工作表;sector summary 抓取失败只 WARN(部分组件走默认值),但主时间序列失败即退出——这与“主数据必须存在”的门禁前提一致。

3.3 两个 SKILL.md 的用法约定

两份技能文档都把调用方式写成了显式约束:market-breadth-analyzer/SKILL.md 与 uptrend-analyzer/SKILL.md 都要求“把同一个 run id 传给两个必需的 producer”,并说明 run id 是调用方提供的一致性标记,而非身份认证。

四、消费者侧:exposure-coach 的严格门禁

4.1 命令行接口与前置校验

calculate_exposure.py 在原有输入参数之外新增四个开关:

parser.add_argument("--require-provenance", action="store_true")
parser.add_argument("--run-id")
parser.add_argument("--as-of", help="Timezone-aware evaluation timestamp")
parser.add_argument("--max-age-days", type=int, default=3)
args = parser.parse_args()
if args.require_provenance and (not args.run_id or not args.as_of):
    parser.error("strict mode requires --run-id and --as-of")

要点:

  • --require-provenance 是选择性加入,默认关闭,因此旧调用方式完全兼容;
  • 一旦开启,--run-id 与 --as-of 变为强制,缺失时在加载任何文件之前就以 parser.error 退出(退出码 2);
  • --max-age-days 默认 3,表示“3 个日历日”的保守策略——文档明确它不是交易所节假日日历,遇到长假需要调用方显式放宽。

4.2 校验发生的时机与顺序

关键实现顺序是:先加载输入 → 再跑门禁 → 最后才计算分数与创建输出目录。

lineage = None
if args.require_provenance:
    try:
        lineage = validate_market_inputs(
            breadth_data, uptrend_data,
            run_id=args.run_id,
            evaluation=args.as_of,
            max_age_days=args.max_age_days,
        )
    except ValueError as exc:
        parser.error(str(exc))

parser.error 会立刻以非零码终止,因此失败时不会走到后面的 args.output_dir.mkdir() 和文件写入,历史产物保持原样。这正是计划文档要求的 “Reject invalid inputs before output creation; preserve existing output.”

4.3 validate_handoff() 的判定树

单项交接的校验顺序(见 provenance_contract.py 第 145–174 行)值得逐条记住:

  1. schema 校验:validate_provenance(),任何错误一次性拼接成 invalid data_provenance: ...;
  2. run id 匹配:run_id 非空且 block["run_id"] == run_id,否则 data_provenance run_id does not match expected run;
  3. max_age_days 合法性:显式排除 bool(因为 True 是 int 子类),要求非负整数,否则 max_age_days must be a nonnegative integer;
  4. 评估时刻必须带时区:_aware(evaluation, "evaluation");
  5. retrieved_at 必须是 UTC:retrieved.utcoffset() != timedelta(0) 即报 retrieved_at must be UTC(注意 schema 校验只要求“带时区”,UTC 是严格模式额外加的);
  6. retrieved_at <= evaluation:抓取时间不得晚于评估时刻,否则 retrieved_at cannot be after evaluation;
  7. 按 as_of 的两种形态分流:
    • 日期形态(YYYY-MM-DD):先把 retrieved 转换到 block["timezone"] 声明的报告时区,取其日期作为“抓取业务日”,要求 business_date <= 该日期;随后 age = (评估时刻在同一报告时区的日期 - business_date).days,age > max_age_days 即 primary data is stale;
    • 时间戳形态:要求 as_of <= retrieved,且 (evaluation - as_of).total_seconds() > max_age_days * 86400 即过期。

第 7 条是整份契约最容易踩坑的地方,它精确回答了两个问题:“业务日期”必须按数据申报时区比较,而“绝对时刻”必须按真实瞬时比较。前者避免了 America/New_York 与 UTC 跨日导致的误判,后者避免了用日历天数近似秒数带来的边界偏差。计划文档对此的表述是 “Compare business dates in the declared reporting timezone; datetime as_of uses actual instant.”

4.4 双向必填与错误前缀

validate_market_inputs() 要求 breadth 与 uptrend 同时存在,并对每个输入分别校验:

for name, payload in (("breadth", breadth), ("uptrend", uptrend)):
    if not isinstance(payload, dict):
        raise ValueError(name + " input is required in strict mode")
    try:
        accepted[name] = validate_handoff(payload.get("data_provenance"), ...)
    except ValueError as exc:
        raise ValueError(name + ": " + str(exc)) from exc

因此报错信息天然带输入名前缀,例如 breadth: primary data is stale,调用方能一眼定位是哪个上游产物过期。

4.5 输出中的血缘与“边界清单”

严格模式通过后,结果里会多一个 input_lineage 块:

{
  "input_lineage": {
    "run_id": "daily-20261017-unique",
    "evaluation_at": "2026-10-17T13:00:00Z",
    "max_age_days": 3,
    "accepted_inputs": { "breadth": { "...": "完整 provenance 块" },
                          "uptrend": { "...": "完整 provenance 块" } },
    "boundaries": [
      "quality flags are conservative, not independently verified",
      "auxiliary source dates are not verified",
      "optional top-risk and other inputs are outside this gate",
      "run_id is a caller consistency marker, not authentication or PIT proof"
    ]
  }
}

这四条 boundaries 不是装饰性文案,而是明确了门禁的证伪范围:

  • 四个质量标志是保守写死 False,并未被独立核实;
  • 辅助源(summary CSV、sector summary)的日期未经验证;
  • --top-risk、--ftd、--theme、--sector、--institutional、--regime 等可选输入不在门禁内,它们可以缺失或过期而不影响通过;
  • 同 run id 只是调用方提供的一致性标记,不构成身份认证,也不构成 point-in-time 证明。

最后一条尤其重要:这套机制能防“拿昨天的数据冒充今天的”,但不能防恶意伪造。文档也据此把结论限制在 “rollout scope, conservative freshness policy and replay boundaries” 之内。

五、重放侧:required_provenance 声明与 golden 约束

5.1 spec 中的声明方式

examples/workflows/market-regime-daily/replay.yaml 只在第 1、2 步声明血缘要求,第 3、4 步不带:

steps:
  - step: 1
    required_provenance: [market_breadth_report]
    executor: market_regime_breadth
    output_files:
      market_breadth_report:
        canonical: 01_market_breadth_report.json
  - step: 2
    required_provenance: [uptrend_report]
    executor: market_regime_uptrend
    output_files:
      uptrend_report:
        canonical: 02_uptrend_report.json
  - step: 3
    executor: market_regime_top_risk
    ...
variants:
  required-only:
    enabled_steps: [1, 2, 4]
    golden_dir: sample-run
  full-path:
    enabled_steps: [1, 2, 3, 4]
    golden_dir: sample-run-full-path

对应 schema 定义在 replay-spec.schema.json。两个变体共享第 1、2 步,因此血缘检查在两个 golden 目录里都会被执行到。

5.2 manifest 侧的静态校验

scripts/workflow_replay_pkg/manifest.py 在加载 spec 时对 required_provenance 做三条硬约束:

for artifact_id in replay_step.get("required_provenance", []):
    roles = replay_step["output_files"].get(artifact_id)
    canonical = roles.get("canonical") if roles else None
    if not canonical or Path(canonical).suffix.lower() not in {".json", ".yaml", ".yml"}:
        raise ReplayError(... "must name a produced artifact with a canonical JSON/YAML file")
    previous_step = provenance_declaration_owners.get(artifact_id)
    if previous_step is not None:
        raise ReplayError(f"duplicate required_provenance declaration for artifact {artifact_id!r}: ...")

即:必须指向本步骤自己产出的、有 canonical JSON/YAML 文件的工件;同一个工件不能被重复声明。前一条防止“声明了别人的产物”,后一条防止歧义。执行期 scripts/workflow_replay_pkg/execution.py 会把声明反转为 artifact_id → step number 的映射,供后续在生产者/消费者边界上做校验。

5.3 fixture 必须“诚实虚构”

计划文档第 4 条要求:“Its existing component fixtures remain honestly fictional”。这不是一句口号,golden 文件里就是这么写的:

"data_provenance": {
  "schema_version": "1.0",
  "provider": "fictional-fixture",
  "endpoint": "market-regime-breadth-component-fixture",
  "retrieved_at": "2026-01-15T13:08:00+00:00",
  "as_of": "2026-01-14T21:00:00+00:00",
  "timezone": "America/New_York",
  "run_id": "fictional-market-regime-daily-run-001",
  "scope": "fictional component fixture only; provider fetch not executed",
  "adjusted": false,
  "point_in_time": false,
  "survivorship_free": false,
  "corporate_actions_handled": false
}

四个特征齐备:fixture provider 名、固定 retrieved_at(与 fixed_timestamp: "2026-01-15T13:08:00+00:00" 对齐)、fixture as_of、全 False 标志,外加显式 scope 说明“未执行 provider 抓取”。消费者产物 04_exposure_decision.json 中的 input_lineage.accepted_inputs 则原样收录了 breadth 与 uptrend 两块,构成可核对的接受链路。

5.4 只重生 01/02/04,03 必须字节一致

计划文档第 4 条限定:只在两个变体重生 01/02/04 与 manifest,03 保持字节一致。这与开篇的“避开 market-top 实现/03 golden”相呼应——门禁改造不应波及未被纳入范围的产物。同时 “Exercise strict consumer CLI and compare native recomputation” 表示重放既要跑真正的严格 CLI,又要与本地重算结果比对,避免 golden 只是被机械覆盖。

六、验证矩阵与实测结果

6.1 三层测试覆盖

计划文档第 5 节列出的验证面,分别落在这些文件中:

  • 生产者语义:对两个真实 producer main 的 mock-fetch 测试,确认 source / date / retrieval / run 四个字段的来源正确;
  • 消费者行为:scripts/tests/test_market_regime_provenance.py 以参数化用例覆盖 missing、run、stale、future、timezone、schema 六种拒绝路径,并断言输出目录里原有的 old.json 内容未被改动:
assert result.returncode != 0
assert "error:" in result.stderr
assert list(output.iterdir()) == [marker]
assert marker.read_text() == "old"
  • 兼容性与分数不变:test_strict_cli_success_and_legacy_schema 分别以严格/非严格两种模式跑同一份输入,断言 composite_score、exposure_ceiling_pct、recommendation、component_scores 完全一致,唯一的差异是 input_lineage 是否存在:
assert ("input_lineage" in decision) == strict
  • 重放边界:test_replay_rejects_invalid_producer_semantics_and_keeps_publication 通过 monkeypatch 篡改生产者返回值(删掉 data_provenance、改 run_id、把 as_of 改成 2025-01-01),断言重放抛 ReplayError 且已发布目录保持原状;test_required_handoff_declarations 则锁定 spec 中只有第 1、2 步声明血缘。
  • 声明传播:scripts/tests/test_workflow_replay_provenance.py 覆盖“声明在每一个边界上都能存活”、重复声明报错、以及缺失/偏移 as_of/run 的情形。

此外还应验证“打包后的独立导入”(packaged standalone imports),因为 vendored 副本只有在 skill 被单独安装时才是唯一实现。

6.2 结果读数

计划文档 “Results” 一节记录的实际数据:

项目 结果
计划审查 第 1 轮独立审查通过,无需修改
代码审查 第 1 轮发现文档化调用缺少 mkdir,已修复;第 2 轮通过,无遗留问题
独立测试 42 项通过,另加三个抽取出的独立包 CLI 检查
breadth 技能套件 170 通过(95.21% 覆盖率)
uptrend 技能套件 233 通过(91.64%)
exposure 技能套件 138 通过(87.38%)
三个 vendored helper 覆盖率 均 100%
provenance/replay 定向套件 136 通过
golden 比对 两个变体全部匹配;03 top-risk golden 与基线字节一致

“三个 vendored helper 覆盖率 100%” 是这份结果里最有信息量的一行:它说明字节一致的三份副本都被各自技能套件完整执行过,而不是只测了其中一份。

代码审查第 1 轮发现的 mkdir 缺失,正是本文示例命令里出现的 args.output_dir.mkdir(parents=True, exist_ok=True)——如果不预先创建输出目录,严格模式的示例调用会在写文件阶段失败。这个细节也提醒我们:文档里的命令必须真实跑过。

七、可复现的端到端调用

以下流程完全基于仓库现有 CLI 参数,先理解三者的角色:

  1. breadth 生产者:python3 skills/market-breadth-analyzer/scripts/market_breadth_analyzer.py --output-dir <dir> --run-id <ID>
  2. uptrend 生产者:python3 skills/uptrend-analyzer/scripts/uptrend_analyzer.py --output-dir <dir> --run-id <ID>(默认输出目录为 reports/)
  3. exposure 消费者:python3 skills/exposure-coach/scripts/calculate_exposure.py --breadth <path> --uptrend <path> --require-provenance --run-id <ID> --as-of <tz-aware-ts> --max-age-days 3 --output-dir <dir>

关键纪律(来自 exposure-coach/SKILL.md “Strict provenance for market-regime-daily” 一节):

  • 两个 producer 必须收到完全相同的唯一 run ID;
  • 传给 --breadth / --uptrend 的必须是它们实际打印出的精确 JSON 路径,不能假设文件名;
  • --as-of 是带时区的评估瞬时,不是用来覆盖源数据业务日期的“补丁”;把它写成过去的日期不会让过期数据通过,只会让你自己的评估时刻错位;
  • 默认 3 个日历日是保守策略,跨长假需显式调大,因为门禁不读交易日历;
  • 失败会在报告产出前停止,因此输出目录里的旧报告不会被半成品覆盖。
mkdir -p out
python3 skills/market-breadth-analyzer/scripts/market_breadth_analyzer.py \
  --output-dir out --run-id daily-20261017-unique
python3 skills/uptrend-analyzer/scripts/uptrend_analyzer.py \
  --output-dir out --run-id daily-20261017-unique
python3 skills/exposure-coach/scripts/calculate_exposure.py \
  --breadth out/market_breadth_<stamp>.json \
  --uptrend out/uptrend_<stamp>.json \
  --require-provenance \
  --run-id daily-20261017-unique \
  --as-of 2026-10-17T13:00:00Z \
  --max-age-days 3 \
  --output-dir out

若想单独核验某个产物的血缘块是否合法,可用仓库级校验器:

python3 scripts/validate_provenance.py --file out/market_breadth_<stamp>.json
python3 scripts/validate_provenance.py --stdin < block.json

它支持 .json / .yaml / .yml,退出码 0 表示合法、1 表示非法、2 表示 I/O 或解析错误。注意它只做 schema 校验,不做 run id 匹配、UTC 强制与时效判定——那些属于严格模式的职责,这也是 provenance_contract.py 头部注释强调 “strict policy is separate” 的原因。

八、能力边界与后续演进

把这份计划当作设计参考时,需要记住它自陈的三重限制:

  1. 范围限制:只覆盖 breadth 与 uptrend 两个必需生产者,不为全部 FMP 生产者背书;#297 remains open。
  2. 证明力限制:run_id 是调用方一致性标记,不是认证凭证,也不是 PIT 证明;point_in_time 等标志保守为 False,辅助源日期未验证;--top-risk 等可选输入在门禁之外。
  3. 时间策略限制:3 天是基于日历日的保守默认值,不感知节假日与半日市;需要更贴合交易日的策略时,应结合 docs/dev/market-calendar-contract.md 描述的市场日历契约另作设计,而不是调整本门禁的语义。

工程手法上,这次切片留下了几个可复用的模式:用字节一致的多份 vendored 副本换取可独立部署、把“诚实为 False”硬编码进构造函数、在创建任何输出之前完成全部拒绝、用 boundaries 字段主动声明门禁证伪范围、以及以字节级 golden 约束把改动钉死在允许的产物范围内。这些比“加一个校验函数”更值得借鉴。

进一步阅读建议从 docs/dev/data-provenance-contract.md 的契约全文开始,再对照 scripts/validate_provenance.py 与三份 vendored 合约实现,最后看 scripts/workflow_replay_pkg/manifest.py、scripts/workflow_replay_pkg/execution.py 如何把声明贯穿到重放执行边界。

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