claude-trading-skills 边缘概念合成器实战:从检测票据到可复用 Edge Concept 的聚类、去重与导出就绪判定
claude-trading-skills 边缘概念合成器实战:从检测票据到可复用 Edge Concept 的聚类、去重与导出就绪判定
在 Edge 研究流水线中,检测器(detector)产出的原始票据(ticket)往往数量多、颗粒细、彼此高度相似,直接把票据喂给策略设计器极易造成过拟合。edge-concept-synthesizer 正是在“检测”与“策略实现”之间插入的一层抽象:它把票据按假设类型、机制标签与市场状态聚类,提炼出带明确论点(thesis)与失效条件(invalidation)的概念对象 edge_concepts.yaml。读完后你将掌握该技能的输入输出契约、全部 CLI 参数的真实语义、概念去重的数学口径,以及 export_ready_v1 的判定链路,并能手工构造一套可运行的票据与提示数据完成端到端验证。
概念合成器在 Edge 研究流水线中的定位
该技能的官方说明非常明确:在检测与策略实现之间建立抽象层,聚类票据证据、总结反复出现的条件,并输出包含显式论点与失效逻辑的 edge_concepts.yaml(见 SKILL.md)。
在仓库级流水线编排中,它处于第三棒。项目根目录的 CLAUDE.md 给出了完整的端到端链路:
edge-candidate-agent(--ohlcv)→market_summary.json+anomalies.json+tickets/edge-hint-extractor(--market-summary、--anomalies)→hints.yamledge-concept-synthesizer(--tickets-dir、--hints)→edge_concepts.yamledge-strategy-designer(--concepts)→strategy_drafts/*.yamledge-strategy-reviewer(--drafts-dir)→review.yaml(PASS/REVISE/REJECT)- 若为 REVISE,则修订后重新评审,最多 2 轮
- 若为 PASS 且具备导出资格,则由
edge-candidate-agent export输出strategy.yaml+metadata.json
编排器侧的脚本映射也印证了这一位置:concepts 阶段直接调用 skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py(见 pipeline_flow.md)。这意味着你既可以单独运行它做研究,也可以完全交给 edge-pipeline-orchestrator 自动执行。
什么时候该用它
原文档列出的三个触发场景,本质上都指向同一个问题——证据与实现之间缺少中间层:
- 你手上有很多原始票据,需要机制层面的结构;
- 你希望避免“票据直连策略”的过拟合;
- 你需要在起草策略之前做一次概念级评审。
换句话说,只要你的研究对象是“一批形态各异的检测结果”而不是“单个交易信号”,就应该先经过这一层。
前置条件与输入契约
运行环境
- Python 3.9+
PyYAML(requirements.txt 声明PyYAML>=6.0,用于独立.skill安装场景)- 检测器输出的票据 YAML 目录(如
tickets/exportable、tickets/research_only) - 可选的
hints.yaml
值得注意的是:这是纯本地计算技能,不需要任何行情 API Key,所有聚类、统计、去重都在本地完成。
票据(ticket)的最小结构
脚本通过 discover_ticket_files() 对目标目录做递归 rglob("*.yaml") 扫描,因此 --tickets-dir 可以指向包含子目录的父目录。每个文件必须能被解析成字典,且同时含有 id 与 hypothesis_type 两个键,否则该文件会被静默跳过(见 synthesize_edge_concepts.py)。
被脚本实际使用的字段如下:
| 字段 | 作用 | 是否必需 |
|---|---|---|
id |
票据标识,写入 evidence.ticket_ids |
必需 |
hypothesis_type |
聚类第一维,同时决定论点、剧本与失效条件 | 必需 |
mechanism_tag |
聚类第二维,缺省 uncertain |
可选 |
regime |
聚类第三维,缺省 Unknown |
可选 |
priority_score |
计算 avg_priority_score,并决定输出排序 |
可选,非法值按 0.0 |
entry_family |
统计入口家族分布;值为 research_only 时不计入 |
可选 |
observation.symbol 或 symbol |
提取代表标的,输出 Top 10 | 可选 |
signal_definition.conditions / entry.conditions |
条件池,用于代表条件与去重 | 可选 |
date |
用于推导输出顶层的 as_of |
可选 |
条件收集的细节值得注意:ticket_conditions() 会同时读取 signal_definition.conditions 与 entry.conditions 两个位置并拼接到同一个列表,空字符串与空白项被过滤(见 synthesize_edge_concepts.py)。所以同一票据在两处写重复条件会抬高该条件在 representative_conditions 中的计数权重。
标的提取优先取 observation.symbol,回落到顶层 symbol,并统一大写(见 synthesize_edge_concepts.py)。
提示(hints)的两种合法形状
read_hints() 接受两种 YAML 形态:顶层直接是列表,或形如 {"hints": <a href="https://link.gitcode.com/i/722efbcca571bd4769e2c8caf7eb419f" target="_blank">...]} 的字典。其他类型会抛出 ConceptSynthesisError("hints file must be list or {hints: [...]} format");文件为空(解析为 None)则返回空列表而不报错(见 [synthesize_edge_concepts.py)。
标准契约与字段语义来自上游 hints_schema.md:
hints:
- title: "Breadth-supported breakout regime"
observation: "Risk-on regime with pct_above_ma50=0.65"
hypothesis_type: "breakout" # 可选
preferred_entry_family: "pivot_breakout" # 可选
symbols: ["NVDA", "AVGO"] # 可选
regime_bias: "RiskOn" # 可选
mechanism_tag: "behavior" # 可选
其中 title 是唯一被强制关注的字段:没有 title(或纯空白)的提示在提级时会被直接跳过,不会生成合成票据。
输出结构与完整 Schema
原文档对输出的描述是五项:概念簇、支撑统计、抽象论点、失效信号、导出就绪标志。参考 concept_schema.md 可以得到一份真实形态的产物:
generated_at_utc: "2026-02-22T12:00:00+00:00"
as_of: "2026-02-20"
source:
tickets_dir: "/tmp/edge-auto/tickets"
hints_path: "/tmp/hints.yaml"
ticket_file_count: 24
ticket_count: 24
concept_count: 3
concepts:
- id: edge_concept_breakout_behavior_riskon
title: Participation-backed trend breakout
hypothesis_type: breakout
mechanism_tag: behavior
regime: RiskOn
support:
ticket_count: 7
avg_priority_score: 71.2
symbols: ["XP", "NOK", "FTI"]
entry_family_distribution:
pivot_breakout: 7
representative_conditions:
- close > high20_prev
- rel_volume >= 1.5
# 仅当存在合成票据(--promote-hints)时出现:
# real_ticket_count: 5
# synthetic_ticket_count: 2
abstraction:
thesis: "When liquidity and participation expand ..."
invalidation_signals:
- Breakout fails quickly with volume contraction.
strategy_design:
playbooks: [trend_following_breakout, confirmation_filtered_breakout]
recommended_entry_family: pivot_breakout
export_ready_v1: true
evidence:
ticket_ids: [edge_auto_vcp_xp_20260220]
matched_hint_titles: [Breadth-supported breakout regime]
# 仅当存在合成票据时出现:
# synthetic_ticket_ids: [hint_promo_seasonal_buyback_0]
几个容易被忽略的顶层字段,其来源在源码中可精确追溯:
generated_at_utc:UTC 时间戳,且剥掉了微秒(replace(microsecond=0)),便于输出稳定对比;as_of:取所有票据date字段的最大值,无date则为null——它不是运行日期;source.ticket_file_count:扫描到的文件数;source.ticket_count:通过校验的票据数(含合成票据);source.dedup_enabled、source.overlap_threshold、source.dedup_merged_count:去重行为的可审计痕迹,--no-dedup时dedup_merged_count恒为 0;concept_count:最终保留的概念数。
source 块在启用 --promote-hints 时还会追加 promote_hints: true、real_ticket_count、synthetic_ticket_count;未启用时这三个键完全不存在(而非设为 false/0),这一向后兼容行为由测试 test_main_promote_hints_source_metadata 显式固定(见 test_synthesize_edge_concepts.py)。
快速命令:从最简到全功能
原文档给出的四条命令覆盖了典型用法,这里补齐每个参数的默认值与副作用。
最简形态(只给票据目录):
python3 skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py \
--tickets-dir /tmp/edge-auto/tickets \
--hints /tmp/edge-hints/hints.yaml \
--output /tmp/edge-concepts/edge_concepts.yaml \
--min-ticket-support 2
--min-ticket-support 2 表示聚类后票据数少于 2 的簇被丢弃,这是压制“单票据伪概念”的最直接手段。注意判定用的是 len(cluster_tickets) < max(args.min_ticket_support, 1),因此传入 0 或负数会被抬升为 1,永远不会出现“全部保留”的失控行为。
启用提示提级与合成配比上限:
python3 skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py \
--tickets-dir /tmp/edge-auto/tickets \
--hints /tmp/edge-hints/hints.yaml \
--output /tmp/edge-concepts/edge_concepts.yaml \
--promote-hints \
--max-synthetic-ratio 1.5
自定义去重阈值,或彻底关闭去重:
python3 skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py \
--tickets-dir /tmp/edge-auto/tickets \
--output /tmp/edge-concepts/edge_concepts.yaml \
--overlap-threshold 0.6
python3 skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py \
--tickets-dir /tmp/edge-auto/tickets \
--output /tmp/edge-concepts/edge_concepts.yaml \
--no-dedup
参数全表
下表由 parse_args() 逐项核对得出(见 synthesize_edge_concepts.py):
| 参数 | 类型 | 默认值 | 语义 |
|---|---|---|---|
--tickets-dir |
路径 | 必填 | 递归查找 .yaml 票据的根目录 |
--hints |
路径 | None |
可选提示文件;不存在时报错退出 |
--output |
路径 | reports/edge_concepts/edge_concepts.yaml |
输出 YAML,父目录自动创建 |
--min-ticket-support |
int | 1 |
概念保留所需的最小票据数,下限被钳到 1 |
--promote-hints |
flag | False |
将合格提示提级为合成票据参与聚类 |
--synthetic-priority |
float | 30.0 |
合成票据的 priority_score |
--max-synthetic-ratio |
float | None(不封顶) |
合成票据 / 真实票据 的上限比例 |
--overlap-threshold |
float | 0.75 |
概念去重的条件重叠阈值 |
--no-dedup |
flag | False |
关闭去重 |
--exportable-families |
字符串 | None |
逗号分隔,覆盖模块内置的可导出家族集合 |
--exportable-families 支持在命令行临时扩大或收窄“可导出”口径,例如只认 pivot_breakout:
python3 skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py \
--tickets-dir /tmp/edge-auto/tickets \
--output /tmp/edge-concepts/edge_concepts.yaml \
--exportable-families pivot_breakout
成功时脚本向 stdout 打印一行摘要,形如 [OK] concepts=3 synthetic_tickets=2 output=/path/to/edge_concepts.yaml(无合成票据时省略 synthetic_tickets 段),便于在编排器日志中定位。
聚类与抽象:三维键与九种假设类型
聚类键
cluster_key() 用三元组 (hypothesis_type, mechanism_tag, regime) 作为分桶依据,任一字段为空则分别回落到 unknown、uncertain、Unknown(见 synthesize_edge_concepts.py)。这就决定了一个关键事实:同一假设类型但不同机制或不同市场状态的票据不会进同一个概念,它们会在后续去重阶段才有机会合并。
概念 ID 由三元组经 sanitize_identifier() 拼接生成,规则是:非字母数字字符一律转下划线、连续下划线压缩、全小写,空结果回落为 concept(见 synthesize_edge_concepts.py)。因此 edge_concept_breakout_behavior_RiskOn 会变成 edge_concept_breakout_behavior_riskon。
假设类型 → 论点 / 剧本 / 失效条件
这是原文档只提到“抽象论点”“失效信号”而未展开的部分,也是本技能真正的知识沉淀所在。源码内置了四张映射表,全部集中声明在文件头部(见 synthesize_edge_concepts.py)。
hypothesis_type |
概念标题 | 策略剧本(playbooks) | 失效信号 |
|---|---|---|---|
breakout |
Participation-backed trend breakout | trend_following_breakout、confirmation_filtered_breakout |
突破后成交量收缩快速失败;广度转弱且相关性防御性抬升 |
earnings_drift |
Event-driven continuation drift | gap_continuation、post_event_drift |
事件次日收盘跌破事件日低点;第 1–2 日后量能确认消失 |
news_reaction |
Event overreaction and drift | event_drift_continuation、event_reversal |
1–2 个交易日内完全均值回归;确认过滤后无跟随 |
futures_trigger |
Cross-asset propagation | cross_asset_follow_through、mapped_basket_rotation |
期货冲击立即正常化;映射标的无方向敏感性 |
calendar_anomaly |
Seasonality-linked demand imbalance | seasonal_rotation、seasonal_overlay |
近年打破历史季节性;形态仅在流动性尾部存活 |
panic_reversal |
Shock overshoot mean reversion | shock_reversal、bounce_with_trend_filter |
冲击延伸且无企稳信号;反转仅出现在低流动性离群点 |
regime_shift |
Regime transition opportunity | regime_transition_probe |
广度与波动率迅速回归原状态;信号仅出现在孤立宏观事件中 |
sector_x_stock |
Leader-laggard sector relay | leader_laggard_pair、sector_relay_follow_through |
样本外领先滞后相关性崩塌;传导仅依赖一次性事件 |
research_hypothesis |
Unclassified edge hypothesis | research_probe |
样本外不可复现;成本吞掉边缘期望 |
以 breakout 为例,其论点是:当流动性参与度在正向市场状态下扩张时,价格突破结构性枢轴后的扩张可以持续多个交易时段。这类论点被设计成“机制描述”而非“参数描述”,正是为了避免把具体阈值硬编码进概念层。
若 hypothesis_type 落在上述九种之外(理论上只可能来自手工构造的票据,因为提级路径已做白名单校验),标题回落为 "{type} concept",剧本回落为 ["research_probe"],论点与失效条件回落到通用的“需显式验证 / 样本外不可复现 / 成本吃掉边缘”。
支撑统计块
build_concept() 为每个概念计算(见 synthesize_edge_concepts.py):
ticket_count:簇内票据总数(含合成票据);avg_priority_score:priority_score的算术平均,四舍五入到 2 位小数。非法或缺失值通过safe_float()视为 0.0,因此“大量无优先级票据”会显著拉低该值并影响最终排序;symbols:按出现频次取 Top 10,保留首次出现顺序;entry_family_distribution:入口家族计数,排除research_only与合成票据;representative_conditions:条件按Counter取最高频 6 条。
最终概念列表按 (avg_priority_score, ticket_count) 双键降序排序,所以高优先级、大样本的概念排在前面,便于人工评审时优先阅读。
提示提级:把研究线索变成可聚类的合成票据
当真实票据不足、或某些机制只有文字观察而没有检测器覆盖时,--promote-hints 可以让 hints.yaml 参与聚类。这是一条“受控的合成数据注入”通道,源码中的约束值得逐条理解。
假设类型推断
infer_hypothesis_type() 采用两级策略(见 synthesize_edge_concepts.py):
- 显式字段优先:若
hypothesis_type去空白并小写后落在 8 个已知类型中,直接采用。因此"Breakout"、" PANIC_REVERSAL "都能正确归一(由测试test_infer_hypothesis_type_case_insensitive固定)。 - 关键词回退:把
title与observation拼接小写,对每个类型统计关键词命中数,取命中最多者;并列时保留字典中先出现者(严格>比较)。全不命中则回落research_hypothesis。
关键词表(HYPOTHESIS_KEYWORDS)覆盖了各类型的典型措辞,例如 calendar_anomaly 关注 calendar、seasonal、buyback、blackout、rebalance、window;sector_x_stock 关注 sector、leader、laggard、relay、supply chain。
实践含义是:写提示时若不想依赖推断,就显式写 hypothesis_type;若依赖推断,则标题里带上领域关键词比写在 observation 里更容易稳定命中(两者权重相同,但标题通常更精炼)。
合成票据的字段生成规则
promote_hints_to_tickets() 为每条提示生成一张票据(见 synthesize_edge_concepts.py):
| 合成字段 | 取值规则 |
|---|---|
id |
hint_promo_ + 标题净化标识 + _ + 提示在列表中的索引 |
hypothesis_type |
上述推断结果 |
mechanism_tag |
提示的 mechanism_tag,空则 uncertain |
regime |
提示的 regime_bias,空则 Unknown |
entry_family |
仅当 preferred_entry_family 属于可导出家族集合时采纳,否则一律 research_only |
priority_score |
--synthetic-priority,默认 30.0 |
observation.symbol |
取 symbols 列表的第一个元素,大写 |
_synthetic |
恒为 True,内部标记,不写入最终 YAML 的可见字段名 |
索引取的是原始提示列表下标而非有效提示序号,因此跳过空标题后 ID 可能不连续(测试中 <Valid> 提示生成 hint_promo_valid_2)。
合成配比上限的真实算式
cap_synthetic_tickets() 的上限是 max(ceil(len(real_tickets) * max_ratio), 3),超出时按 priority_score 降序保留前若干条(见 synthesize_edge_concepts.py)。
注意这里存在一个常见误读:floor=3 是下限,意味着即使没有任何真实票据,也允许最多 3 条合成票据进入。测试 test_cap_synthetic_tickets_floor_applies 用 1 张真实票据 + 10 条合成、比例 1.5 得出保留 3 条,正是这一下限在起作用;而 3 张真实票据 × 1.5 得 ceil(4.5)=5,保留 5 条。
由于所有合成票据共享同一个 priority_score(默认 30.0),截断实际是按原顺序取前 N 条——若你的提示有优先级差异,应显式设置不同的 --synthetic-priority… 但这只作用于全局,无法逐条设置。想精确控制保留顺序,更稳妥的做法是预先在 hints.yaml 中排好序。
合成数据不会“伪造”导出资格
这是本技能最重要的防误导设计:build_concept() 在统计 entry_family_distribution 时显式跳过 is_synthetic 为真的票据,因此纯合成簇的该字段为空字典,recommended_entry_family 为 None,export_ready_v1 为 False(见 synthesize_edge_concepts.py)。
测试 test_build_concept_synthetic_only_not_export_ready 把这一行为钉死:即使合成票据的 entry_family 被写成 pivot_breakout,概念仍然不可导出(见 test_synthesize_edge_concepts.py)。同时 support 与 evidence 会分别记录 real_ticket_count、synthetic_ticket_count 与 synthetic_ticket_ids,让评审者一眼看出概念的证据构成。
概念去重:containment 口径与贪心合并
去重是本技能唯一带数学定义的环节,理解它才能正确调 --overlap-threshold。
重叠度定义
condition_overlap_ratio() 采用包含度(containment)而非 Jaccard:
overlap = |A ∩ B| / min(|A|, |B|)
条件先做去重与小写归一,任一集合为空则返回 0.0(见 synthesize_edge_concepts.py)。
这个口径的关键特性是非对称容忍:一个只有 3 条条件的概念,若这 3 条全被另一个含 4 条条件的概念覆盖,重叠度为 3/3 = 1.0,会被判为重复。若换成 Jaccard 就只有 0.75。也就是说,本设计倾向于“窄条件集被宽条件集吸收”。
合并触发条件
deduplicate_concepts() 是贪心两两扫描(见 synthesize_edge_concepts.py):
- 仅比较
hypothesis_type相同的概念对,不同类型永不合并(由test_dedup_different_hypothesis_never_merge固定); - 重叠度严格大于阈值才合并(代码为
> overlap_threshold),因此阈值 0.75 时重叠度恰为 0.75 不会合并; - 合并后
current被替换为新概念并继续与后续候选比较,merged_indices保证每个概念最多被吸收一次; - 返回合并计数,写入
source.dedup_merged_count。
由于阈值比较是严格的,如果希望“完全包含即合并”,可以传 --overlap-threshold 0.99 之类的值;但若要让重叠度 1.0 的也能合并,阈值必须小于 1.0。反过来,设为 1.0 会导致连完全相同的条件集都不合并,这一点在调参时容易踩坑。
合并后的字段归属
merge_concepts() 的规则逐项如下(见 synthesize_edge_concepts.py):
- 主概念选择:
ticket_count更多的一方成为primary;相等时保留参数顺序中的前者; - 论点与失效条件:完全继承
primary,不做融合——这保证抽象语义不被机械拼接破坏; - 机制标签:不同则按字母序用
+拼接,如behavior与flow合并为behavior+flow; - 平均优先级:按票据数加权平均,而非简单平均;
- 标的列表:保序并集(先主后次,去重);
- 入口家族分布:逐键求和;
- 代表条件:保序并集后截断到 6 条,与单簇构建的上限一致;
- 推荐入口家族:优先主概念的,为空则采纳次概念的,再据此重算
export_ready_v1; - 票据 ID:保序并集;
- 提示标题:排序去重并集;
- 概念 ID 重新生成:基于合并后的机制标签,因此
edge_concept_breakout_behavior_flow_riskon; - 溯源字段:新增
merged_from,记录被吸收概念的旧 ID。
merged_from 是审计关键——它让评审者能追溯“这个宽概念是由哪几个窄概念合出来的”,在怀疑过度合并时可以据此回退到 --no-dedup 重跑。
export_ready_v1 的完整判定链路
原文档只给出“导出就绪标志”这一句,实际判定涉及一个可配置的家族集合。
模块级默认集合为四个家族(见 synthesize_edge_concepts.py):
DEFAULT_EXPORTABLE_FAMILIES = {
"pivot_breakout",
"gap_up_continuation",
"panic_reversal",
"news_reaction",
}
判定流程是:统计入口家族分布(排除 research_only 与合成票据)→ 按频次从高到低找到第一个落在可导出集合中的家族(choose_recommended_entry_family())→ 若找到则 recommended_entry_family 为该家族且 export_ready_v1=True,否则为 None 与 False。
这里有个细节:选择逻辑是“遍历 most_common() 顺序,返回首个属于可导出集合的家族”,而不是“取可导出家族中频次最高者”。两者在多数场景等价,但当分布为 {research_only: 9, pivot_breakout: 2} 时——注意 research_only 根本没进 Counter——结果是 pivot_breakout。若分布为不可导出家族 A 频次 9、可导出家族 B 频次 2,由于 A 不在集合内被跳过,返回的仍是 B。
口径差异提醒:编排器的 pipeline_flow.md 声明“只有 pivot_breakout 与 gap_up_continuation 可导出到交易策略流水线”,而合成阶段默认集合含四个。若你希望概念的 export_ready_v1 与最终导出限制严格一致,应显式收窄:
--exportable-families pivot_breakout,gap_up_continuation
反之,若你在自建下游、需要放行 panic_reversal 与 news_reaction,就维持默认值。这个参数同时会被编排器透传给 concepts 阶段,因此编排模式下的口径调整也走同一入口。
与编排器的集成及参数透传
edge-pipeline-orchestrator 在 concepts 阶段组装的参数是(见 orchestrate_edge_pipeline.py):
--tickets-dir <tickets> --output <out>/concepts/edge_concepts.yaml
[--hints <out>/hints/hints.yaml] # 仅当 hints 阶段产物存在
[--promote-hints]
[--max-synthetic-ratio <N>]
[--overlap-threshold <F>]
[--no-dedup]
[--exportable-families <list>]
几点工程含义:
--hints是条件性传入的:如果 hints 阶段被跳过或未产出文件,concepts 阶段仍会运行,只是没有提示匹配与提级能力;- concepts 阶段在
--resume-from drafts或--review-only模式下整体跳过,所以这些参数在那两种模式下无效; --tickets-dir缺失时编排器直接抛EdgePipelineError("--tickets-dir or --from-ohlcv required for concepts stage"),不会静默降级。
产物落在 <output-dir>/concepts/edge_concepts.yaml,随后被 drafts 阶段以 --concepts 消费。下游 edge-strategy-designer 明确要求其输入是“由概念合成产出的 edge_concepts.yaml”,并从中读取 hypothesis_type、support.representative_conditions、strategy_design.export_ready_v1、strategy_design.recommended_entry_family 等字段(见 design_strategy_drafts.py)。这构成了一条稳固的契约:概念的 export_ready_v1 直接决定草稿是否为导出候选。
此外,edge-signal-aggregator 也能以通配形式消费多份概念产物(--edge-concepts reports/edge_concepts_*.yaml,见 edge-signal-aggregator 技能文档),这意味着按日期或按主题批量生成概念文件是受支持的用法。
错误处理与排障清单
脚本采用“显式失败 + 非零退出码”的策略,便于脚本化调用。四种已知失败路径:
| 触发条件 | 输出(stderr) | 退出码 |
|---|---|---|
--tickets-dir 不存在 |
[ERROR] tickets dir not found: <path> |
1 |
--hints 指定但文件不存在 |
[ERROR] hints file not found: <path> |
1 |
| 目录内无任何通过校验的票据 | [ERROR] no valid ticket files found |
1 |
全部概念被 --min-ticket-support 过滤掉 |
[ERROR] no concepts passed min-ticket-support filter |
1 |
对应源码位置见 synthesize_edge_concepts.py。
实操中最常见的两类“静默异常”需要特别留意:
- 概念数为 0 但票据很多:说明票据大量缺少
id或hypothesis_type,被read_ticket()跳过。用grep -L "hypothesis_type" tickets/**/*.yaml之类的方式快速定位。 - 概念被过度吸收:
source.dedup_merged_count明显偏大,且概念的merged_from列表很长。此时降低--overlap-threshold不会减少合并——注意方向是反的,阈值越低合并越多。想减少合并应提高阈值或直接--no-dedup。
手工构造一套可运行的最小样例
以下样例完全基于源码与测试中的真实字段构造,可直接跑通。
第一步,创建票据目录与两张票据:
# /tmp/tickets/t_breakout_xp.yaml
id: edge_auto_vcp_xp_20260220
hypothesis_type: breakout
mechanism_tag: behavior
regime: RiskOn
priority_score: 74.2
entry_family: pivot_breakout
observation:
symbol: XP
signal_definition:
conditions:
- close > high20_prev
- rel_volume >= 1.5
date: "2026-02-20"
# /tmp/tickets/t_breakout_nok.yaml
id: edge_auto_vcp_nok_20260220
hypothesis_type: breakout
mechanism_tag: behavior
regime: RiskOn
priority_score: 73.0
entry_family: pivot_breakout
observation:
symbol: NOK
signal_definition:
conditions:
- close > high20_prev
date: "2026-02-20"
第二步,创建提示文件:
# /tmp/hints.yaml
hints:
- title: Breadth-supported breakout regime
observation: Risk-on regime with broad participation
hypothesis_type: breakout
preferred_entry_family: pivot_breakout
regime_bias: RiskOn
mechanism_tag: behavior
第三步,运行:
python3 skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py \
--tickets-dir /tmp/tickets \
--hints /tmp/hints.yaml \
--output /tmp/out/edge_concepts.yaml \
--min-ticket-support 2
预期结果:输出 1 个概念,support.ticket_count = 2、support.avg_priority_score ≈ 73.6、symbols 为 ["XP", "NOK"]、entry_family_distribution 为 {pivot_breakout: 2}、strategy_design.export_ready_v1 = true,且 evidence.matched_hint_titles 包含该提示标题(提示的 regime_bias 与概念 regime 一致、preferred_entry_family 与推荐家族一致、symbols 未限制,三项匹配全通过)。
第四步,验证提级路径:
python3 skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py \
--tickets-dir /tmp/tickets \
--hints /tmp/hints.yaml \
--output /tmp/out/edge_concepts_promoted.yaml \
--promote-hints \
--max-synthetic-ratio 1.5
此时该提示会先被提级为 entry_family: pivot_breakout 的合成票据并并入同一簇,source 中出现 promote_hints: true、real_ticket_count: 2、synthetic_ticket_count: 1,support.ticket_count 变为 3,同时 support.real_ticket_count = 2、support.synthetic_ticket_count = 1、evidence.synthetic_ticket_ids 含 hint_promo_breadth_supported_breakout_regime_0。
由于合成票据不进入家族分布,entry_family_distribution 仍为 {pivot_breakout: 2},export_ready_v1 仍为 true——这正是“合成数据不能伪造导出资格、但可以扩充样本支撑”的设计意图。
测试覆盖与可验证行为
该技能的单测集中在 test_synthesize_edge_concepts.py,覆盖了本文提到的几乎所有边界:
- 假设类型推断:显式字段、大小写、未知值回退关键词、纯关键词、最终回退;
- 提级:基础字段、空标题跳过、最小提示的默认值(
uncertain/Unknown/research_only/ 自定义优先级); - 支撑统计:真实与合成计数分离、仅合成时不可导出、无合成时不写额外字段(向后兼容);
- 配比上限:正常截断、下限生效、无需截断、
main()级别生效; - 去重:包含度的相同/不相交/部分/空/大小写/非对称六个用例,合并的机制拼接、入口家族采纳、主概念保留、合成字段求和、ID 重生成,以及“不同假设类型永不合并”;
- 端到端:
--no-dedup的source标记、--overlap-threshold的透传与生效。
需要留意的是仓库自身的质量审计曾指出,该技能“尚缺少断言型错误路径/失败关闭测试,以及断言型输出 schema 一致性测试”(见 issue-496 审计文档)。因此上表的四种错误路径虽在源码中明确,但缺少对应单测保护——如果你要在生产流水线中依赖退出码,建议先手工验证一次。
使用建议小结
- 优先用
--min-ticket-support控制质量,而不是事后删概念;它作用在聚类阶段,能直接消灭单票据伪概念。 - 票据的
hypothesis_type与mechanism_tag要写准。这两个字段决定聚类粒度;写得太粗会把不同机制混在一簇,写得太细会产生大量需要靠去重才收敛的碎片概念。 - 改去重阈值前先看
source.dedup_merged_count。阈值降低会合并更多,方向与直觉相反。 - 把
--exportable-families与实际下游对齐。合成阶段默认四个家族、编排文档声明两个,口径不一致会让export_ready_v1=true的概念在导出阶段被拦下。 - 用
--promote-hints补充证据,不要用它补资格。合成票据被设计为永不计入家族分布,任何需要“可导出”的结论都必须由真实票据支撑。 - 检查
as_of是否等于你期望的日期。它取票据date最大值,缺失date就是null,不要误当成运行时间。
相关文件与参考:技能说明 SKILL.md、schema 契约 concept_schema.md、实现主体 synthesize_edge_concepts.py、上游提示契约 hints_schema.md、下游消费者 design_strategy_drafts.py、流水线编排 orchestrate_edge_pipeline.py。