claude-trading-skills 数据血缘门禁实战:market-regime-daily 的 provenance 交接设计与实现
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:
- skills/market-breadth-analyzer/scripts/provenance_contract.py
- skills/uptrend-analyzer/scripts/provenance_contract.py
- skills/exposure-coach/scripts/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:
它做了三件重要的事:
- 组装
schema_version="1.0"的完整块,并把四个质量标志硬编码为False:adjusted、point_in_time、survivorship_free、corporate_actions_handled。这是“诚实声明”原则的实现——当前 CSV 数据源确实不具备这些保证,就明确写False,绝不猜测为True; - 自动附带
scope: "primary timeseries only; auxiliary source dates unverified",把“辅助数据源日期未经核实”这一限制固化进产物; - 调用
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 行)值得逐条记住:
- schema 校验:
validate_provenance(),任何错误一次性拼接成invalid data_provenance: ...; - run id 匹配:
run_id非空且block["run_id"] == run_id,否则data_provenance run_id does not match expected run; max_age_days合法性:显式排除bool(因为True是int子类),要求非负整数,否则max_age_days must be a nonnegative integer;- 评估时刻必须带时区:
_aware(evaluation, "evaluation"); retrieved_at必须是 UTC:retrieved.utcoffset() != timedelta(0)即报retrieved_at must be UTC(注意 schema 校验只要求“带时区”,UTC 是严格模式额外加的);retrieved_at <= evaluation:抓取时间不得晚于评估时刻,否则retrieved_at cannot be after evaluation;- 按
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 参数,先理解三者的角色:
- breadth 生产者:
python3 skills/market-breadth-analyzer/scripts/market_breadth_analyzer.py --output-dir <dir> --run-id <ID> - uptrend 生产者:
python3 skills/uptrend-analyzer/scripts/uptrend_analyzer.py --output-dir <dir> --run-id <ID>(默认输出目录为reports/) - 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” 的原因。
八、能力边界与后续演进
把这份计划当作设计参考时,需要记住它自陈的三重限制:
- 范围限制:只覆盖 breadth 与 uptrend 两个必需生产者,不为全部 FMP 生产者背书;
#297 remains open。 - 证明力限制:
run_id是调用方一致性标记,不是认证凭证,也不是 PIT 证明;point_in_time等标志保守为False,辅助源日期未验证;--top-risk等可选输入在门禁之外。 - 时间策略限制: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 如何把声明贯穿到重放执行边界。