claude-trading-skills 边缘概念合成器实战:从检测票据到可复用 Edge Concept 的聚类、去重与导出就绪判定

原创2026-11-15 14:02:082,206 阅读
文章标签:金融科技AI 技能人工智能数据分析

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 给出了完整的端到端链路:

  1. edge-candidate-agent(--ohlcv)→ market_summary.json + anomalies.json + tickets/
  2. edge-hint-extractor(--market-summary、--anomalies)→ hints.yaml
  3. edge-concept-synthesizer(--tickets-dir、--hints)→ edge_concepts.yaml
  4. edge-strategy-designer(--concepts)→ strategy_drafts/*.yaml
  5. edge-strategy-reviewer(--drafts-dir)→ review.yaml(PASS/REVISE/REJECT)
  6. 若为 REVISE,则修订后重新评审,最多 2 轮
  7. 若为 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):

  1. 显式字段优先:若 hypothesis_type 去空白并小写后落在 8 个已知类型中,直接采用。因此 "Breakout"、" PANIC_REVERSAL " 都能正确归一(由测试 test_infer_hypothesis_type_case_insensitive 固定)。
  2. 关键词回退:把 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):

  1. 仅比较 hypothesis_type 相同的概念对,不同类型永不合并(由 test_dedup_different_hypothesis_never_merge 固定);
  2. 重叠度严格大于阈值才合并(代码为 > overlap_threshold),因此阈值 0.75 时重叠度恰为 0.75 不会合并;
  3. 合并后 current 被替换为新概念并继续与后续候选比较,merged_indices 保证每个概念最多被吸收一次;
  4. 返回合并计数,写入 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。

实操中最常见的两类“静默异常”需要特别留意:

  1. 概念数为 0 但票据很多:说明票据大量缺少 id 或 hypothesis_type,被 read_ticket() 跳过。用 grep -L "hypothesis_type" tickets/**/*.yaml 之类的方式快速定位。
  2. 概念被过度吸收: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。

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