拆解 claude-trading-skills 的 required-only 重放提示词:market-regime-daily 离线执行契约与验证原理
拆解 claude-trading-skills 的 required-only 重放提示词:market-regime-daily 离线执行契约与验证原理
examples/workflows/market-regime-daily/sample-run/prompt.md 是 claude-trading-skills 中一个只有三句话的提示词文件,但它并非随手写下的笔记,而是确定性重放工具链自动生成的“执行契约说明书”。读懂它,就能理解 market-regime-daily 工作流如何在完全离线、使用虚构数据的前提下,跑完市场宽度、上升趋势与仓位姿态三步,并产出可逐字节比对的黄金样例(golden)。本文逐句拆解这段提示词的三条约束,并结合 replay.yaml、执行器源码与测试用例,说明每一步在代码里究竟做了什么、为什么必须这样做,以及两条变体为何得到完全不同的结论。
prompt.md 的原文与它在仓库中的位置
文件全文只有三句话,另加一个标题:
# Prompt: required-only market-regime-daily replay
Replay this workflow with the bundled fictional input data. This is not investment advice and must not submit orders or call live APIs.
Skip every optional step.
它的同级目录 sample-run/ 还包含 01_market_breadth_report.json、02_uptrend_report.json、04_exposure_decision.json 与 manifest.yaml。换句话说,prompt.md 并不是人可以自由发挥的输入,而是与产物一起被写入磁盘、被清单引用的规范性描述。
这一点可以在生成代码中得到印证。重放工具在写清单时会调用 _write_manifest,把 prompt: "prompt.md" 写进 manifest.yaml,并用 _prompt_text 生成提示词全文。该函数对 market-regime-daily 有专门分支,full-path 变体的那一句是“Include the optional fixture-backed market-top score before running the native exposure posture CLI.”,而 required-only 变体统一输出“Skip every optional step.”——也就是说,prompt.md 的第三句是由变体名机械决定的,而不是人工撰写:
- 提示词生成逻辑:execution.py
market-regime-daily专属分支:execution.py- 清单写入
prompt字段:execution.py
正因如此,sample-run/manifest.yaml 里的 prompt: prompt.md 与 optional_steps_skipped 是互相印证的一对字段:前者说明“这份产物是按哪条指令生成的”,后者说明“因此第 3 步没有被执行”。
第一句约束:使用内置虚构数据重放
“Replay this workflow with the bundled fictional input data.”
“bundled fictional input data”指的是 replay.yaml 的 inputs 段所指向的三个组件打分 fixture:
schema_version: 1
workflow_id: market-regime-daily
fixed_timestamp: "2026-01-15T13:08:00+00:00"
inputs:
market_breadth_components: replay-inputs/breadth-components.json
market_uptrend_components: replay-inputs/uptrend-components.json
market_top_risk_components: replay-inputs/top-risk-components.json
完整规范见 replay.yaml。三个 fixture 并不是任意 JSON,而必须满足一套显式校验,实现位于 _validate_market_component_fixture(steps_market_regime.py):
- 必须包含
schema_version、kind、as_of、max_age_days、component_scores、data_availability、warning_flags七个顶层字段; schema_version必须为1,kind必须与文件名语义一致(breadth/uptrend/top_risk);max_age_days必须是0..30之间的整数(布尔值被显式排除);as_of不得晚于fixed_timestamp,且时效不得超过max_age_days;component_scores、data_availability的键集合必须与MARKET_COMPONENT_CONFIG中声明的 canonical 组件集合完全相等;- 每个组件分数必须是
0..100的有限数; data_availability中任一项为false,直接判定“证据不足”并终止。
canonical 组件集合集中定义在 constants.py:
| kind | 产出 artifact | 对应 skill | 组件集合 | warning_flags |
|---|---|---|---|---|
breadth |
market_breadth_report |
market-breadth-analyzer |
breadth_level_trend、ma_crossover、cycle_position、bearish_signal、historical_percentile、divergence |
无 |
uptrend |
uptrend_report |
uptrend-analyzer |
market_breadth、sector_participation、sector_rotation、momentum、historical_context |
late_cycle、high_spread、divergence |
top_risk |
top_risk_report |
market-top-detector |
distribution_days、leading_stocks、defensive_rotation、breadth_divergence、index_technical、sentiment |
无 |
此外 _load_market_fixture_set 还要求所有 fixture 共享同一个 as_of,否则报错 market component fixtures must use one consistent as_of timestamp。这条规则的意义在于:后续的血缘校验按单一时间点计算新鲜度,如果三份 fixture 各自带不同日期,input_lineage 就会失真。
实际 fixture 的取值可以直接查看 breadth-components.json 与 uptrend-components.json:as_of 均为 2026-01-14T21:00:00+00:00,max_age_days 为 2,相对 fixed_timestamp 恰好一天出头,因此能通过新鲜度检查。
第二句约束:不是投资建议、不下单、不调用实时 API
“This is not investment advice and must not submit orders or call live APIs.”
这句话在实现层面被拆成两层落实。
第一层是离线输入契约。 重放报告的 network_policy 固定为 offline-input-required;执行器在调用 Exposure Coach 子进程时不传入任何 provider 或 API key 相关参数,并且会从环境变量中剔除含有 API_KEY、TOKEN、SECRET、PASSWORD、PROXY 字样的键(见 constants.py)。测试用例显式验证了这一点:注入 REPLAY_API_KEY 与 HTTPS_PROXY 后捕获子进程环境,断言命令中不含 --api-key、环境中不含相关变量(test_workflow_replay_market_regime.py)。
需要强调的是,这只是一个离线输入契约,不是操作系统级网络沙箱。examples/workflows/market-regime-daily/README.md 对此有明确表述:harness 只保证不传凭据、不传 provider 标志,并不拦截进程的网络栈。
第二层是决策门的语义。 在 replay.yaml 中,四个步骤的 gate_policy 分别是:
steps:
- step: 1
required_provenance: [market_breadth_report]
executor: market_regime_breadth
executor_mode: native_api
gate_policy: continue
- step: 2
required_provenance: [uptrend_report]
executor: market_regime_uptrend
executor_mode: native_api
gate_policy: continue
- step: 3
executor: market_regime_top_risk
executor_mode: native_api
gate_policy: continue
- step: 4
executor: market_regime_exposure
executor_mode: native_cli
gate_policy: record_only
gate_policy 的合法取值受工作流定义约束:只有 decision_gate: true 的步骤才允许使用 record_only、continue、halt 三者之一,其余步骤只能是 continue(校验逻辑见 manifest.py)。market-regime-daily 的第 4 步在 workflows/market-regime-daily.yaml 中正是唯一的决策门,它提出的是“新开波段风险应当 allow、restrict 还是 cash-priority”,而重放把该门处理为 record_only:记录姿态,不追认权限、不触发下单。工作流的 when_not_to_run 也写明 exposure_decision 是 posture 而非指令。
第三句约束:跳过所有可选步骤
“Skip every optional step.”
工作流中唯一被标记为可选的是第 3 步 market-top-detector(workflows/market-regime-daily.yaml 中 optional: true)。它被跳过会产生两处可见痕迹:
- 目录里没有
03_top_risk_report.json; manifest.yaml的optional_steps_skipped记录:
optional_steps_skipped:
- step: 3
skill: market-top-detector
reason: required-only executable replay
这条记录由 _write_manifest 生成:凡是工作流里 optional: true 且当前变体为 required-only 的步骤,都会带上固定 reason 文本(execution.py)。
更重要的是,跳过必须是真正的解耦,而不是“读了但不用”。测试对此有专门断言:把 market_top_risk_components 覆盖成一个非 JSON 的坏文件后,required-only 变体依然正常完成,步骤序列为 <a href="https://link.gitcode.com/i/0b25440a60b901c849d15d2f5913ba5a" target="_blank">1, 2, 4]([test_workflow_replay_market_regime.py)。这说明 fixture 校验是按需加载的——_load_market_fixture_set 的 kinds 参数只选择当前步骤真正需要的类型。
两条变体的结果差异与数值来源
replay.yaml 的 variants 段定义了两个变体的启用步骤与黄金目录:
| 变体 | 启用步骤 | 黄金目录 | 姿态结论 |
|---|---|---|---|
required-only |
1 → 2 → 4 | sample-run |
REDUCE_ONLY,LOW 置信度,天花板 47% |
full-path |
1 → 2 → 3 → 4 | sample-run-full-path |
NEW_ENTRY_ALLOWED,MEDIUM 置信度,天花板 57% |
这些数字不是装饰,而是可以从 Exposure Coach 源码精确复算的。
权重与缺失惩罚
calculate_exposure.py 定义了八个输入的权重与三个关键输入:
WEIGHTS = {
"regime": 0.25, "top_risk": 0.20, "breadth": 0.15, "uptrend": 0.15,
"institutional": 0.10, "sector": 0.05, "theme": 0.05, "ftd": 0.05,
}
CRITICAL_INPUTS = {"regime", "top_risk", "breadth"}
calculate_composite_score 只在提供了分数的输入之间做加权平均,然后对每个缺失的关键输入扣 10 分(calculate_exposure.py)。于是:
- required-only:breadth 66、uptrend 71。加权和 = 66×0.15 + 71×0.15 = 20.55,权重和 = 0.30,归一化后 68.5;缺失关键输入为
regime、top_risk两个,扣 20 → 48.5,与 04_exposure_decision.json 中的composite_score一致。 - full-path:top_risk fixture 的
composite_score为 38.0(见 03_top_risk_report.json),而extract_top_risk_score对它做了反向映射100 - 38 = 62(因为高天顶风险应折算为低安全分);加权和 = 9.9 + 10.65 + 62×0.20 = 32.95,权重和 = 0.50,归一化 65.9;缺失关键输入只剩regime,扣 10 → 55.9。
这也解释了 04_exposure_decision.json 中 component_scores 的 top_risk_score: 62 与上游报告里的 38.0 为什么数值不同:一个是“安全度”,一个是“风险度”。
天花板、建议与置信度
determine_exposure_ceiling是分段线性映射(calculate_exposure.py)。48.5 落在35..50区间:int(30 + (48.5-35)×1.3) = 47;55.9 落在50..65区间:int(50 + (55.9-50)×1.3) = 57。determine_recommendation的判定顺序是:composite < 30或top_risk < 25→CASH_PRIORITY;composite < 50、top_risk < 40、或缺失关键输入数 ≥ 2 →REDUCE_ONLY;否则NEW_ENTRY_ALLOWED(calculate_exposure.py)。required-only 同时命中composite < 50与missing_critical = 2,full-path 因提供了 top_risk 才被放行。determine_confidence规则为:提供数 ≥ 6 且无关键缺失 →HIGH;提供数 ≥ 4 或关键缺失 ≤ 1 →MEDIUM;否则LOW(calculate_exposure.py)。故 2 个输入 + 2 个关键缺失得LOW,3 个输入 + 1 个关键缺失得MEDIUM。determine_participation要求 uptrend 与 breadth 均 ≥ 50 才判BROAD(calculate_exposure.py),71 与 66 同时满足,因此两条变体都是BROAD。bias由于regime_name为Unknown且无 theme/sector/institutional 输入,回落到NEUTRAL。
rationale 文本同样由规则拼接而非模板填空:generate_rationale 会依据参与度、top_risk 阈值、关键缺失清单和建议类型逐句追加(calculate_exposure.py)。这就解释了为什么 required-only 的说明里出现“Missing critical inputs (regime, top_risk) reduce confidence.”,而 full-path 只提到 regime。
执行链:提示词背后真正运行的代码
replay.yaml 中每个步骤声明了一个 executor 与 executor_mode。validate_spec 会交叉校验:executor_mode 必须与执行器注册表中登记的 mode 一致,否则报错(manifest.py)。本工作流的映射关系是:
| 步骤 | executor | 模式 | 底层动作 |
|---|---|---|---|
| 1 | market_regime_breadth |
native_api |
调用 market-breadth-analyzer 的 scorer.calculate_composite_score 与 report_generator.generate_json_report |
| 2 | market_regime_uptrend |
native_api |
同上,改用 uptrend-analyzer,并额外传入 warning_flags |
| 3 | market_regime_top_risk |
native_api |
同上,改用 market-top-detector |
| 4 | market_regime_exposure |
native_cli |
以子进程运行 skills/exposure-coach/scripts/calculate_exposure.py |
前三步:组件打分复算
_market_regime_component 的流程是“加载模块 → 计算 → 写报告 → 读回校验 → 重新序列化”(steps_market_regime.py):
- 通过
_load_module_from_path动态加载目标 skill 的scorer.py与report_generator.py,而不是通过 import 路径,避免不同 skill 之间的模块名冲突; - 调用
scorer.calculate_composite_score,并校验返回必须是字典、必须是有限值、composite_score必须落在0..100; - 组装分析对象:
metadata.generated_at固定为fixed_timestamp,metadata.data_mode标记为fictional offline component fixture,provenance.execution_mode标记为native_api,并列出三条fixture_boundaries; - 调用
generate_json_report落盘; - 把落盘结果读回,用
_validate_market_report与重新计算出的期望对象做全等比较,任何差异都报does not match native scorer recomputation; - 由于原生报告写入器不保证末尾换行,harness 会用自己的 canonical JSON 形式重新写一遍,保证黄金样例稳定。
uptrend 类型会额外带 warning_flags 参数,forward 给原生打分器;这正是 fixture 中 divergence: true 能在 02_uptrend_report.json 里变成 active_warnings 条目(“SECTOR DIVERGENCE WARNING”)的原因。
第四步:CLI 调用与双重复算
_market_regime_exposure 在调用 CLI 之前做了三件预防工作(steps_market_regime.py):
- 消费者集合校验:期望的 artifact 集合是
{market_breadth_report, uptrend_report},若存在top_risk_report则加入;多一个少一个都报unexpected artifacts。 - 交接件再验证:每个被消费的 JSON 都要重新走一遍
_validate_market_report,与“从同批 fixture 重新计算”的结果对齐。这防止了中途被篡改的交接件流入下一步。 - 组装命令:
--breadth、--uptrend(full-path 追加--top-risk)、--output-dir、--json-only、--require-provenance、--run-id fictional-market-regime-daily-run-001、--as-of <fixed_timestamp>。
CLI 执行后还有第二道复算:_expected_exposure_decision 直接在进程内导入 calculate_exposure 模块,用同一组抽取函数、同一套 determine_* 规则算出期望结果,再与 CLI 写出的唯一报告做键集合与值域全等比较,并且要求恰好一份 exposure_posture_*.json。也就是说,第 4 步既是“跑真实 CLI”,也是“用真实 API 自证”。
血缘门:--require-provenance 具体检查什么
--require-provenance 不是形式开关。启用后 calculate_exposure.py 会把 --run-id、--as-of、--max-age-days 交给 validate_market_inputs,缺任一参数都会让 argparse 直接报错退出(calculate_exposure.py)。
该函数的实现位于 provenance_contract.py,关键检查链路如下:
build_provenance生成的血缘块必须能通过validate_provenance,其中timezone必须是合法 IANA 时区(如America/New_York);run_id必须非空且与期望值完全相等——它是一个调用方一致性标记,不是认证;retrieved_at必须是 UTC 时间,且不得晚于评估时刻;as_of不得晚于retrieved_at;若as_of是纯日期,则按报告时区换算业务日后比较;- 超过
max_age_days即判定primary data is stale。
在重放侧,_market_analysis 只给 breadth 与 uptrend 注入 data_provenance(steps_market_regime.py),并把 scope 覆写为“fictional component fixture only; provider fetch not executed”。top_risk 不带血缘块,这与血缘门本身“optional top-risk and other inputs are outside this gate”的边界声明一致——该边界文本会原样出现在最终 04_exposure_decision.json 的 input_lineage.boundaries 里。
这里有一个容易误解的细节:fixture 中的 max_age_days 是 2,而 _expected_exposure_decision 调用 validate_market_inputs 时传入的是 3。两者作用于不同层级——前者约束fixture 组件证据相对固定时间戳的时效,后者约束血缘交接件相对评估时刻的时效。由于 as_of 只比 fixed_timestamp 早约 16 小时,两者都能轻松通过。
失败即不发布:事务性语义
这段提示词的隐含要求是“确定性”:同样的输入必须得到逐字节相同的输出,任何异常都不得污染已有目录。实现上分为三层。
第一层:步骤内 fail-closed。 校验失败会抛出 ReplayError,覆盖的情形包括 as_of 晚于固定时间戳(错误信息含 later)、过期(stale)、分数越界(<= 100)、组件不可用(insufficient component evidence)、非有限值(finite)、as_of 不一致(consistent as_of)。测试逐一注入了这些变异,并断言输出目录中除哨兵文件 keep.txt 外没有任何新增(test_workflow_replay_market_regime.py)。
第二层:artifact 封印。 每个步骤产出的文件都会被计算摘要并记入 sealed_artifact_digests;后续步骤不允许替换已封印的 artifact(replaced sealed artifacts);全部步骤结束后再比对一次,不一致即报 final artifact integrity mismatch。测试通过在第 4 步之后篡改 recommendation 为 TAMPERED 来验证这一拦截。
第三层:目录级事务。 _publish_tree 先把暂存目录复制到目标同级的候选临时目录,再用 os.replace 原子替换,替换前把已有目标移入备份;提交成功才清理备份,失败则回滚(execution.py)。generate 子命令使用的 _publish_trees_transactionally 更进一步:多条变体作为一个整体提交,任一失败则逆序回滚全部。
另外,_validate_runtime_output 会拒绝把输出写到受保护路径,包括仓库根、规范文件本身、规范所在目录、各输入文件的父目录,以及两个变体的 golden_dir(manifest.py)。这样 --output-dir 就不可能意外覆盖黄金样例或 fixture。
值得一提的是,原生 API 的失败也被逐一覆盖:打分器抛异常、返回非映射、返回 NaN、返回 101、报告写入抛错、报告写出非法内容,六种注入情形都不会产生发布(同文件 test_native_api_failures_do_not_publish)。CLI 侧的“缺失报告 / 多份报告 / 非法 JSON / 结构不符 / 数值不符”五种劣化输出同样被拦截。
复现步骤
从仓库根目录执行以下命令即可分别得到两个变体,并用 check 验证黄金样例仍然当前:
python3 scripts/workflow_replay.py run \
--spec examples/workflows/market-regime-daily/replay.yaml \
--variant required-only \
--output-dir /tmp/market-regime-required
python3 scripts/workflow_replay.py run \
--spec examples/workflows/market-regime-daily/replay.yaml \
--variant full-path \
--output-dir /tmp/market-regime-full
python3 scripts/workflow_replay.py check
命令说明:
run --spec --variant --output-dir:三个参数均为必填,--variant的取值受VARIANTS(required-only/full-path)限制,非法取值报unknown replay variant(cli.py)。check:在临时目录重新生成全部变体并与黄金样例比对,发现差异时向 stderr 打印Workflow replay drift detected:并以退出码 1 结束;一致时输出Workflow replay goldens are current.。- 输出目录必须是目录而非文件,且不得与受保护路径重叠;这一点在
run之前就已校验,不会等到写盘阶段才失败。
check 的比对之所以有意义,是因为第 1~3 步的报告末尾被重新序列化为 canonical JSON,第 4 步的 generated_at 会被显式覆写为 fixed_timestamp(canonical["generated_at"] = spec["fixed_timestamp"])。没有这两处处理,datetime.now(timezone.utc) 产生的实时时间戳会让黄金比对永远失败。
与 guided runner 的区别
仓库里还有一条面向学习的路径:scripts/run_market_regime_daily.py。它与本文讨论的确定性重放目标相似、机制不同,值得区分:
| 维度 | 确定性重放(本文) | guided runner |
|---|---|---|
| 入口 | scripts/workflow_replay.py run |
scripts/run_market_regime_daily.py |
| 决策处理 | gate_policy: record_only 自动记录 |
终端交互输入 allow / restrict / cash-priority |
| 第 4 步调用方式 | 运行 Exposure Coach CLI | 调用原生 Python API |
| 产物形态 | 固定四份 JSON + manifest.yaml + prompt.md |
运行目录内含 manifest.json、journal.json、inputs/*.json |
| 是否支持续跑 | 每次重新生成 | 支持 --status / --resume,带 .lock |
| 决策 diff | 无 | 可选,仅对虚构 fixture 生效 |
两者的共同点是都严格离线、都使用 2026-01-15T13:08:00+00:00 这个固定时间点、都不触碰真实交易记忆状态。guided runner 的日志只做本地交接(delivery: handoff_only),并不投递到 trader-memory-core;确定性重放的产物也不投递,二者都只是证据。
证据边界与适用前提
理解这份提示词时,必须接受它自带的限制声明,它们被原样写入 manifest.yaml 的 execution_evidence_limitations(execution.py):
- 不执行 provider 抓取:
breadth、uptrend、top_risk的数据获取路径完全未运行; - 不执行单个组件计算器:fixture 直接给出 0~100 的分项分数,上游各项指标如何算出未被覆盖;
- 不覆盖实时 API 失败路径:网络超时、限流、字段漂移都不在测试范围内;
INSUFFICIENT_EVIDENCE不是这三个 skill 的字面契约:重放用等效的 fail-closed 规则代替,即组件必须齐全、可用、有限、在 0~100 内、相对固定时间戳新鲜,且与其他 fixture 日期一致;- 第 4 步是真实 CLI,前三步是 fixture 喂给原生 API:这是“工作流交接证据”,不等于对每个 skill 的生产级验证。
因此,sample-run/ 与 sample-run-full-path/ 的正确定位是:给定这组虚构组件分数时,market-regime-daily 的衔接、复算、血缘与姿态推导是否与实现一致。它们不是当日市场判断,更不是买卖信号;47% 与 57% 这两个天花板数字只对应 2026-01-15 那组虚构输入,与任何真实持仓无关。若修改了 fixture、执行器、工作流 YAML 或相关原生脚本,就必须用 generate 重新生成黄金样例,否则 check 会如实报出漂移。