Claude Trading Skills 中的 Edge Concept Synthesizer:把检测票据抽象为可复用的交易边缘概念

原创2026-11-14 13:44:212,177 阅读
文章标签:金融科技AI 技能人工智能数据分析

Claude Trading Skills 中的 Edge Concept Synthesizer:把检测票据抽象为可复用的交易边缘概念

Edge Concept Synthesizer 是 claude-trading-skills 仓库中负责“抽象层”的技能:它把 edge-candidate-agent 产出的大量检测票据(tickets)与 edge-hint-extractor 产出的线索(hints)聚类、去重,并综合成 edge_concepts.yaml——每条概念都带有可证伪的 thesis、明确的失效信号(invalidation_signals)以及可用的策略剧本(playbooks)。读完本文,你将掌握该技能的输入契约、全部 CLI 参数、聚类与去重算法细节、输出 schema 的每个字段含义,以及它如何把概念交接给 edge-strategy-designer 与 edge-pipeline-orchestrator。


1. 技能定位:在“检测”与“策略实现”之间插入一层抽象

原文档对该技能的定位非常明确:在检测与策略实现之间创建一层抽象(abstraction layer)。它聚类票据证据、总结反复出现的条件,并输出带有显式 thesis 与失效逻辑的 edge_concepts.yaml。

这个定位解决了一个具体工程问题:自动检测器会围绕单一标的、单一交易日不断生成票据(例如某天 XP 的 VCP 突破、某天 TSLA 的新闻过度反应)。如果直接把“一张票据”翻译成“一个策略”,模型就会把噪音当成规律——这正是原文档所说的 ticket-to-strategy overfitting(票据到策略的过拟合)。概念层通过把票据按机制维度分组,把“这只股票今天涨了”提升为“在风险偏好环境下,参与度驱动的突破可以延续数日”这样的可检验假设。

从仓库结构看,概念合成是拆分式工作流(split workflow)的第三个阶段:

auto_detect → tickets/*.yaml
    ↓
hints → hints.yaml
    ↓
concepts → edge_concepts.yaml      ← 本技能
    ↓
drafts → strategy_drafts/*.yaml
    ↓
review / revision loop
    ↓
export → strategies/<candidate_id>/

这条链路的阶段与脚本映射在 pipeline_flow.md 中被固定下来,其中 concepts 阶段明确对应 synthesize_edge_concepts.py。edge-candidate-agent 也把 skills/edge-concept-synthesizer 列为推荐拆分工作流的第 2 步。


2. 适用场景(When to Use)

原文档列出三条判断标准,可直接作为是否引入该技能的前置决策依据:

  • 你有一堆原始票据,却缺少机制层面的结构:票据数量多但彼此孤立,无法回答“这些信号背后是不是同一个机制”。
  • 你想避免票据到策略的直接过拟合:不希望每条检测结果都被机械地转成一个策略草案。
  • 你需要在策略起草之前进行概念级评审:把“该不该做这个方向”和“具体怎么做”拆成两次决策。

如果你只有一两条票据,或者已经有稳定的 edge_concepts.yaml,那么直接进入 edge-strategy-designer 更合理——概念层在票据数量足以形成簇(cluster)时才产生价值。


3. 环境准备与前置条件

原文档给出的前置条件,结合 requirements.txt 与源码,可以精确化如下:

项目 要求 依据
Python 3.9+ 原文档;源码使用 from __future__ import annotations 与 frozenset[str] 风格注解
依赖 PyYAML>=6.0 requirements.txt
票据目录 检测器输出目录(tickets/exportable、tickets/research_only) 原文档
线索文件 hints.yaml,可选 原文档

注意依赖文件中的注释说明:该依赖用于独立 .skill 安装场景,并由 scripts/check_skill_deps.py 校验。也就是说,如果你通过 skill-packages/edge-concept-synthesizer.skill 单独安装,PyYAML 是唯一需要额外确认的运行时依赖。

安装与检查:

# 在仓库根目录直接运行(推荐,便于与兄弟技能共享路径)
python3 -c "import yaml; print(yaml.__version__)"

# 或安装打包版本(仓库只读,仅安装到本地环境)
# skill-packages/edge-concept-synthesizer.skill

4. 快速上手:五步工作流与完整命令

原文档的 Quick Start 与 Workflow 章节内容一致,都是五步:

  1. 从自动检测输出中收集票据 YAML 文件。
  2. 可选地提供 hints.yaml 用于上下文匹配。
  3. 运行 scripts/synthesize_edge_concepts.py。
  4. 对概念去重:合并同假设、条件重叠(containment)超过阈值的概念。
  5. 评审概念,只把高支持度的概念推进到策略起草阶段。

4.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 \
  --min-ticket-support 2

--min-ticket-support 2 的含义是:只有被 2 张及以上票据支撑的簇才会被保留。源码中的过滤发生在聚类之后、去重之前:

for key, cluster_tickets in grouped.items():
    if len(cluster_tickets) < max(args.min_ticket_support, 1):
        continue

因此该参数是控制概念“样本充分性”的第一道闸门,也是抑制单票据噪音最直接的手段。

4.2 启用 hint 提升与合成票据上限

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

--promote-hints 会把合格的 hint 转换成“合成票据”(synthetic ticket),从而让只有线索、还没有真实检测证据的想法也能形成概念——但会用 real_ticket_count / synthetic_ticket_count 明确标注证据构成,并且这类概念不会被判定为可导出。

4.3 自定义去重阈值,或完全关闭去重

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

阈值 0.6 比默认 0.75 更激进(更容易触发合并);--no-dedup 则用于诊断——当你想确认“概念数量偏少是不是去重造成的”,先关掉它对比一次是最快的方式。


5. 全部 CLI 参数详解

原文档没有给出参数表,但源码的 parse_args() 定义了完整的界面。下表把每个参数的默认值、边界行为与实际影响对应到实现:

参数 类型 / 默认值 说明与实现影响
--tickets-dir 必填,目录 通过 rglob("*.yaml") 递归发现票据;不存在则报 [ERROR] tickets dir not found 并返回 1
--hints 可选,文件路径 不存在则报 [ERROR] hints file not found 并返回 1
--output 默认 reports/edge_concepts/edge_concepts.yaml 父目录会被自动创建(mkdir(parents=True, exist_ok=True))
--min-ticket-support int,默认 1 簇内票据数低于该值即丢弃;源码用 max(value, 1) 兜底,传 0 或负数等价于 1
--promote-hints 开关,默认关 开启后调用 promote_hints_to_tickets() 生成合成票据
--synthetic-priority float,默认 30.0 合成票据的 priority_score;低于真实票据常见分值,排序时自然靠后
--max-synthetic-ratio float,默认 None 合成票据上限 = max(ceil(real_count × ratio), 3);不传则不设上限
--overlap-threshold float,默认 0.75 去重的条件包含度阈值,比较时使用严格的 >
--no-dedup 开关,默认关 关闭去重,source.dedup_merged_count 记为 0
--exportable-families 逗号分隔字符串,默认 None 覆盖模块级 DEFAULT_EXPORTABLE_FAMILIES,直接影响 export_ready_v1

5.1 --exportable-families 与默认可导出族的差异

源码中模块级默认值是四个族:

DEFAULT_EXPORTABLE_FAMILIES = {
    "pivot_breakout",
    "gap_up_continuation",
    "panic_reversal",
    "news_reaction",
}

而下游 pipeline_flow.md 的 “Exportable Entry Families” 只列出 pivot_breakout 与 gap_up_continuation。pipeline_if_v1.md 同样说明 v1 仅支持这两个族,并各自要求携带 vcp_detection 或 gap_up_detection 块。

因此在使用更严格的导出前置条件时,应显式收窄:

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,gap_up_continuation

这段差异值得明确记录在流程文档里:export_ready_v1: true 表示“在本技能的族配置下被认为可导出”,最终能否导出仍由 export_candidate.py 的接口校验决定。


6. 输入契约一:票据(ticket)YAML

源码的 read_ticket() 采取“宽松读取、最小校验”的策略:

payload = yaml.safe_load(path.read_text())
if not isinstance(payload, dict):
    return None
if "id" not in payload or "hypothesis_type" not in payload:
    return None
return payload

也就是说,只有 id 与 hypothesis_type 是硬性要求,缺失即被静默跳过(不会报错,只会在最终 ticket_count 上体现差异)。

6.1 影响概念构建的字段

字段 读取位置 作用
id build_concept() 进入 evidence.ticket_ids;缺失则不入证据列表
hypothesis_type cluster_key() 聚类键第一维
mechanism_tag cluster_key() 聚类键第二维,空值归为 uncertain
regime cluster_key() 聚类键第三维,空值归为 Unknown
priority_score build_concept() 参与 avg_priority_score 计算,并决定排序
entry_family build_concept() 计入 entry_family_distribution;research_only 与合成票据被排除
observation.symbol 或顶层 symbol ticket_symbol() 统计代表标的,取 top 10
signal_definition.conditions ticket_conditions() 代表性条件来源之一
entry.conditions ticket_conditions() 代表性条件来源之二
date main() 用于推导输出的 as_of(取最大值)
_synthetic build_concept() 标记合成票据,影响证据计数与可导出性

一个可直接使用的票据示例(与测试夹具一致):

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"

字段语义与 research_ticket_schema.md 一致:id、hypothesis_type、entry_family 为必填,mechanism_tag、regime、entry、exit 等为可选。该 schema 还提供两条最小示例(pivot breakout 与 gap continuation),可直接作为票据模板。

6.2 目录布局建议

因为发现逻辑是递归的,tickets/exportable 与 tickets/research_only 可以放在同一父目录下同时被扫描:

/tmp/edge-auto/tickets/
├── exportable/
│   └── edge_auto_vcp_xp_20260220.yaml
└── research_only/
    └── edge_auto_news_reaction_tsla_20260220.yaml

这种布局也解释了为什么概念层能同时看到“可导出族”和“仅研究族”的票据:可导出性并不是在读取阶段过滤,而是在概念层通过 entry_family 统计与 export_ready_v1 判断来体现。


7. 输入契约二:可选的 hints.yaml

read_hints() 支持两种顶层结构,并显式拒绝其他形态:

# 形式一:列表
- title: Breadth-supported breakout regime
  observation: Breadth expanding with participation
  symbols: [XP, NOK]
  regime_bias: RiskOn
  mechanism_tag: behavior
  preferred_entry_family: pivot_breakout
  hypothesis_type: breakout

# 形式二:带 hints 键的字典
generated_at_utc: "2026-02-22T12:00:00+00:00"
hints:
  - title: Sector rotation into industrials
    observation: Tech underperforming while industrials show relative strength
    symbols: [CAT, DE, GE]
    regime_bias: Neutral
    mechanism_tag: flow
    preferred_entry_family: pivot_breakout
    hypothesis_type: sector_x_stock

若文件内容既不是列表也不是字典,会抛出 ConceptSynthesisError("hints file must be list or {hints: [...]} format") 并以返回码 1 退出。列表中的非字典项会被过滤掉。

第二个示例的字段集合与 edge-pipeline-orchestrator SKILL.md 中“Claude Code LLM-Augmented Workflow”章节给出的 hint 写法完全一致,说明 hints.yaml 是跨技能共享的稳定契约。


8. 核心机制一:三维聚类与概念构建

8.1 聚类键

def cluster_key(ticket):
    hypothesis = str(ticket.get("hypothesis_type", "unknown")).strip() or "unknown"
    mechanism = str(ticket.get("mechanism_tag", "uncertain")).strip() or "uncertain"
    regime = str(ticket.get("regime", "Unknown")).strip() or "Unknown"
    return hypothesis, mechanism, regime

三元组 (hypothesis_type, mechanism_tag, regime) 构成聚类键。这个设计的经济学含义是:同一假设、同一机制、同一市场环境下的票据才被认为在讲同一件事。breakout + behavior + RiskOn 与 breakout + flow + RiskOn 会先形成两个独立概念,再由去重阶段决定是否合并——这解释了为什么 --overlap-threshold 是必要的第二道工序。

8.2 概念 ID 的生成与清洗

concept_id = sanitize_identifier(f"edge_concept_{hypothesis}_{mechanism}_{regime}")

sanitize_identifier() 把所有非字母数字字符替换为下划线,压缩连续下划线,全部小写;若结果为空则回退为 concept。因此 RiskOn 会变成 riskon,schema 示例中的 edge_concept_breakout_behavior_riskon 正是这条规则的结果。

8.3 支持度统计块(support)

build_concept() 会逐票据累积四类统计:

  • ticket_count:簇内票据总数(含合成票据)。
  • avg_priority_score:priority_score 的算术平均,四舍五入到 2 位;非数值经 safe_float() 按 0 处理。
  • symbols:按出现频次取前 10 个标的(Counter.most_common(10))。
  • entry_family_distribution:仅统计非合成且非 research_only 的 entry_family。
  • representative_conditions:所有条件按出现频次取前 6 条。

real_ticket_count / synthetic_ticket_count 只在存在合成票据时写入,这是有意设计的向后兼容:测试 test_build_concept_without_synthetic_omits_breakdown 明确断言全真实票据时不出现这两个键。

8.4 假设类型到概念的映射表

这是本技能最实质的“知识资产”:源码用四张字典把 hypothesis_type 映射到标题、thesis、剧本与失效信号。完整梳理如下(依据 synthesize_edge_concepts.py 中的 HYPOTHESIS_TO_TITLE / HYPOTHESIS_TO_THESIS / HYPOTHESIS_TO_PLAYBOOKS / HYPOTHESIS_TO_INVALIDATIONS):

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
news_reaction Event overreaction and drift event_drift_continuation、event_reversal
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

对应的失效信号同样是预置的,这使每条概念天生具备可证伪性:

hypothesis_type 失效信号(invalidation_signals)
breakout 突破迅速失败并伴随量能收缩;广度走弱且相关性防御性上升
earnings_drift 事件后一日收盘跌破事件日低点;第 1–2 日后量能确认消失
news_reaction 反应在 1–2 个交易日内完全均值回归;确认过滤后无跟随
futures_trigger 期货冲击立即回归正常;映射股票无方向性敏感度
calendar_anomaly 近年打破历史季节性模式;模式只在流动性尾部存活
panic_reversal 冲击在无稳定信号下继续延伸;反转只在低流动性离群样本出现
regime_shift 广度与波动率迅速回归原状态;信号只出现在孤立宏观事件中
sector_x_stock 样本外领先滞后相关性崩塌;传导仅依赖一次性事件
research_hypothesis 样本外不复现;成本吞噬边缘期望

breakout 的 thesis 值得单独引用,因为它是整个抽象层最典型的表达:

When liquidity and participation expand during a positive regime, price expansion above structural pivots can persist for multiple sessions.

注意这句话里没有任何个股名称、价格或日期——它描述的是条件与持续性的关系,这正是“抽象”的可操作定义。

8.5 可导出性的判定

recommended_entry_family = choose_recommended_entry_family(entry_counter, families)
export_ready_v1 = recommended_entry_family in families

choose_recommended_entry_family() 按出现次数从高到低遍历 entry_family_distribution,返回第一个属于可导出族的值;若无可返回 None。

由于 entry_counter 只累加非合成、非 research_only 的票据,一项重要的安全性质随之成立:纯 hint 提升出来的概念永远不可导出。测试 test_build_concept_synthetic_only_not_export_ready 对此做了显式断言——即使合成票据的 entry_family 是 pivot_breakout,结果仍是 export_ready_v1: False、recommended_entry_family: None、entry_family_distribution: {}。

同理,news_reaction 票据若 entry_family 为 research_only,概念就是研究探针(test_build_concept_for_news_reaction_is_research_only)。

8.6 hint 与概念的上下文匹配

match_hint_titles() 用三条“空值即通配”的规则把 hint 关联到概念:

symbol_match  = not hint_symbols or bool(symbol_set.intersection(hint_symbols))
regime_match  = not hint_regime or hint_regime == regime
family_match  = recommended_entry_family is None or hint_family is None \
                or hint_family == recommended_entry_family

三条全真时把 hint 的 title 收入 evidence.matched_hint_titles,最终去重排序并截断到 10 条。注意 regime 比较是字符串精确匹配(大小写敏感),因此 hint 中写 RiskOn 与票据中的 RiskOn 才能对上;写 risk_on 则不会匹配。这是实际使用中最容易踩的坑之一。


9. 核心机制二:hint 提升为合成票据

启用 --promote-hints 后,promote_hints_to_tickets() 会对每条 hint 执行四步转换。

9.1 假设类型推断

def infer_hypothesis_type(hint):
    explicit = hint.get("hypothesis_type")
    if isinstance(explicit, str) and explicit.strip().lower() in KNOWN_HYPOTHESIS_TYPES:
        return explicit.strip().lower()
    text = (str(hint.get("title", "")) + " " + str(hint.get("observation", ""))).lower()
    ...

优先使用显式字段(大小写不敏感、去空格后需落在白名单内);否则对 title + observation 做关键词计分,取命中数最多的一类;若完全没有命中,回退到 research_hypothesis。关键词表(HYPOTHESIS_KEYWORDS)例如:

假设类型 关键词
breakout breakout、pivot、participation、high20
earnings_drift earnings、drift、post-event、post_event、pead
calendar_anomaly calendar、seasonal、buyback、blackout、rebalance、window
panic_reversal panic、reversal、shock、overshoot、mean-reversion、bounce
regime_shift regime、transition、inflection、shift、rotation、breadth divergence
sector_x_stock sector、leader、laggard、relay、supply chain

测试覆盖了这条路径的三种情形:显式白名单命中(含大小写与空格)、显式值非法时回退关键词(hypothesis_type: momentum + 标题含 breakout → breakout)、以及完全无匹配时回退 research_hypothesis。concept_schema.md 也把 research_hypothesis 明确定义为“hint 提升票据在关键词推断失败时的兜底值”。

9.2 字段归一与 ID 生成

mechanism = str(hint.get("mechanism_tag", "")).strip() or "uncertain"
regime    = str(hint.get("regime_bias", "")).strip() or "Unknown"
entry_family = hint["preferred_entry_family"] if 在 families 内 else "research_only"
ticket_id = f"{SYNTHETIC_TICKET_PREFIX}{sanitize_identifier(title)}_{idx}"

要点:

  • 空标题(或纯空白)的 hint 直接跳过,不产生票据。
  • preferred_entry_family 必须落在当前可导出族集合内,否则降级为 research_only。
  • ID 前缀固定为 hint_promo_,加上标题清洗结果与 hint 在文件中的序号,因此同名 hint 不会碰撞。
  • observation.symbol 取 symbols 列表的第一个元素并大写。

9.3 合成票据上限

limit = max(math.ceil(len(real_tickets) * max_ratio), floor)   # floor 默认 3

这把“LLM 生成的想法可以补充证据但不能主导证据”写成了硬约束。以测试为例:2 张真实票据配 --max-synthetic-ratio 1.5,上限为 max(ceil(3.0), 3) = 3,8 条 hint 只保留 3 条(按 priority_score 降序取头部)。

floor=3 的意义在于:当真实票据为 0 或 1 张时,ceil(1 × 1.5) = 2 不足以形成有意义的对比,因此允许最多 3 条合成票据作为“探针”存在。

9.4 证据隔离

main() 在写出 source 块时会记录:

source:
  promote_hints: true
  real_ticket_count: 1
  synthetic_ticket_count: 1

即使 --promote-hints 开着但没有任何 hint 文件,promote_hints: true 与 synthetic_ticket_count: 0 也都会写入(test_main_promote_hints_zero_promotions),这让下游可以准确区分“未开启提升”与“开启了但没有提升”。


10. 核心机制三:概念去重(containment overlap)

原文档只写了一句话:“合并同假设且条件重叠(containment > threshold)的概念”。源码给出了完整定义。

10.1 重叠度定义

def condition_overlap_ratio(conds_a, conds_b) -> float:
    if not conds_a or not conds_b:
        return 0.0
    set_a = {c.strip().lower() for c in conds_a}
    set_b = {c.strip().lower() for c in conds_b}
    intersection = len(set_a & set_b)
    return intersection / min(len(set_a), len(set_b))

关键性质:

  • 是包含度(containment),不是 Jaccard。分母是 min(|A|,|B|),所以小子集完全被大集合包含时得分为 1.0。测试 test_overlap_ratio_asymmetric_containment 断言 4 条 ⊇ 3 条 返回 1.0。
  • 大小写与首尾空白的归一化在比较时完成,所以 Close > MA50 与 close > ma50 视为同一条件。
  • 任一方为空直接返回 0.0,避免除零并防止“空条件概念”被误合并。

10.2 贪心配对与合并

deduplicate_concepts() 是 O(n²) 的贪心算法,规则有三条硬约束:

  1. 只允许 同 hypothesis_type 的概念合并;跨假设类型即使条件完全相同也绝不合并(test_dedup_different_hypothesis_never_merge)。
  2. 重叠度必须 严格大于 阈值(> overlap_threshold),等于阈值不触发。
  3. 一旦合并,被合并方索引标记,不再参与后续比较。

合并语义由 merge_concepts() 定义,行为如下表:

维度 合并策略
主/次判据 ticket_count 更多者为主(相等时前者为主)
ticket_count 两者相加
avg_priority_score 按票据数加权平均,保留 2 位
symbols 并集,保序去重
mechanism_tag 不同则按字典序拼接为 a+b(如 behavior+flow)
entry_family_distribution 按族累加
representative_conditions 并集去重,截断 6 条
recommended_entry_family 主优先,缺失时取次
export_ready_v1 用合并后的族重新判定
title / abstraction 完全沿用主概念(thesis 与失效信号不变)
evidence.ticket_ids 并集保序
evidence.matched_hint_titles 集合并集后排序
id 用合并后的 mechanism 重新生成
merged_from 记录被合并方原 ID

因为 title、thesis、playbooks 都取自主概念,合并只会改变“支持度与证据范围”,不会改变“这个概念的叙述”。测试 test_merge_concepts_keeps_primary 明确断言 thesis 保持主概念版本。

一个容易忽略的细节:merge_concepts() 不会合并 regime,而是保留主概念的 regime。由于同一 hypothesis_type 下不同 regime 也可能条件高度重叠,合并后可能出现“概念登记的 regime 只是主概念那一个”的情况。若你依赖 regime 做下游分组,建议用较高阈值或先按 regime 分区处理。

10.3 合并计数可观测

去重结果会写入输出的 source 块:

source:
  dedup_enabled: true
  overlap_threshold: 0.75
  dedup_merged_count: 2

--no-dedup 时 dedup_enabled: false 且 dedup_merged_count: 0(test_main_no_dedup_flag)。这是判断“阈值是否调过头”的第一手指标:dedup_merged_count 骤增通常意味着阈值偏低。


11. 输出文件:edge_concepts.yaml 逐字段解析

concept_schema.md 给出了规范的完整示例,以下在其基础上补上源码生成逻辑的注释:

generated_at_utc: "2026-02-22T12:00:00+00:00"     # UTC、秒级精度、去掉微秒
as_of: "2026-02-20"                                # 所有票据 date 的最大值,无 date 则为 null
source:
  tickets_dir: "/tmp/edge-auto/tickets"
  hints_path: "/tmp/hints.yaml"                   # 未提供时为 null
  ticket_file_count: 24                            # 发现的 .yaml 文件数(含被跳过的)
  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
      # 仅当存在合成票据时出现
      # 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]

11.1 顶层字段

  • generated_at_utc:datetime.now(timezone.utc).replace(microsecond=0).isoformat(),因此是带时区偏移的 ISO 8601。
  • as_of:从票据的 date 字段取最大值,用于声明这批证据的“数据截止日”;无任何票据带 date 时写 null。
  • source:可追溯性的核心。ticket_file_count 与 ticket_count 的差值直接暴露“有多少 YAML 因缺少 id 或 hypothesis_type 被跳过”。

11.2 排序规则

concepts.sort(
    key=lambda item: (
        safe_float(item.get("support", {}).get("avg_priority_score")),
        safe_float(item.get("support", {}).get("ticket_count")),
    ),
    reverse=True,
)

先按平均优先级降序,再按票据数降序。 这意味着一个“票据少但优先级都很高”的概念会排在“票据多但优先级平平”的概念前面。如果你希望优先看支持度,需要在评审脚本里自行重排。

11.3 设计约束

concept_schema.md 的 “Design Rule” 明确了三条契约:

  • 抽象必须同时包含 thesis 与显式的 invalidation_signals——没有失效信号的概念不构成可检验假设。
  • export_ready_v1 只有在推荐族当前被 pipeline 接口 v1 支持时才应为 true。
  • hypothesis_type 合法取值就是前述九种,其中 research_hypothesis 是关键词推断失败时的兜底。

12. 错误处理与退出码

main() 的失败路径全部返回 1,并输出到 stderr,格式统一为 [ERROR] ...:

触发条件 消息
--tickets-dir 不存在 [ERROR] tickets dir not found: <path>
--hints 指向的文件不存在 [ERROR] hints file not found: <path>
没有任何通过校验的票据 [ERROR] no valid ticket files found
所有簇都被 --min-ticket-support 过滤掉 [ERROR] no concepts passed min-ticket-support filter
hints 文件结构非法 [ERROR] hints file must be list or {hints: [...]} format

成功路径输出:

[OK] concepts=3 synthetic_tickets=2 output=/tmp/edge-concepts/edge_concepts.yaml

synthetic_tickets= 段仅在存在合成票据时出现,便于在流水线日志里一眼确认是否发生了 hint 提升。

这两个“空结果”错误在实践中经常出现:no valid ticket files found 通常是票据目录里放了 JSON 或扩展名不是 .yaml;no concepts passed min-ticket-support filter 则多是 --min-ticket-support 设得比最大簇还大。


13. 与上下游技能的衔接

13.1 上游:票据与线索

  • 票据来自 edge-candidate-agent 的自动检测,产物包括 tickets/exportable/*.yaml 与 tickets/research_only/*.yaml(见 edge-candidate-agent SKILL.md 的 Output 章节)。
  • 线索来自 edge-hint-extractor,其默认输出路径为 reports/edge_hint_extractor/hints.yaml,并支持 --llm-ideas-cmd 或 --llm-ideas-file 两种增强方式(二者互斥),详见 edge-hint-extractor SKILL.md。

13.2 下游:策略草案设计

概念文件的直接消费者是 edge-strategy-designer。它读取 edge_concepts.yaml,按 --risk-profile(conservative / balanced / aggressive)为每条概念生成变体,并用 HYPOTHESIS_EXIT_OVERRIDES 针对假设类型调整止损、盈亏比、时间止损与移动止损,同时把盈亏比下限钳制在 RR_FLOOR=1.5。命令形如:

python3 skills/edge-strategy-designer/scripts/design_strategy_drafts.py \
  --concepts /tmp/edge-concepts/edge_concepts.yaml \
  --output-dir /tmp/strategy-drafts \
  --exportable-tickets-dir /tmp/exportable-tickets \
  --risk-profile conservative

这解释了 strategy_design.playbooks 与 recommended_entry_family 为什么必须存在于概念输出中:它们就是下游选变体与校准退出参数的输入。

13.3 编排层:一键跑通全链路

edge-pipeline-orchestrator 按仓库路径解析各兄弟技能,并以子进程方式串联。与概念层相关的可选参数直接透传:

  • --max-synthetic-ratio N:合成票据上限(N × 真实票据数,下限 3)
  • --overlap-threshold F:去重条件重叠阈值(默认 0.75)
  • --no-dedup:关闭去重

完整模式示例:

python3 scripts/orchestrate_edge_pipeline.py \
  --tickets-dir path/to/tickets/ \
  --llm-ideas-file llm_hints.yaml \
  --promote-hints \
  --as-of 2026-02-28 \
  --max-synthetic-ratio 1.5 \
  --strict-export \
  --output-dir reports/edge_pipeline/

需要特别注意编排文档中的限制说明:--llm-ideas-file 与 --promote-hints 只在完整流水线运行时生效;--resume-from drafts 与 --review-only 会跳过 hints/concepts 阶段,因此这两个参数会被忽略。当产物目录中出现 concepts/edge_concepts.yaml 时:

output-dir/
├── pipeline_run_manifest.json
├── tickets/
├── hints/hints.yaml
├── concepts/edge_concepts.yaml
├── drafts/*.yaml
└── ...

13.4 最终导出

只有同时满足“评审 PASS + export_ready_v1: true + 可导出 entry family”的草案才会被导出为 strategies/<candidate_id>/strategy.yaml 与 metadata.json。而接口 v1 的硬约束(validation.method: full_sample、risk.risk_per_trade 在 (0, 0.10]、signals.entry.conditions 非空等)由 validate_candidate.py 在导出前后校验,详见 pipeline_if_v1.md。


14. 验证与自测

该技能的单元测试集中在 test_synthesize_edge_concepts.py,覆盖了本文提到的几乎所有分支,可直接作为行为规范的“可执行文档”:

测试主题 代表性用例
可导出性判定 test_build_concept_for_breakout_is_export_ready、test_build_concept_for_news_reaction_is_research_only
假设类型推断 test_infer_hypothesis_type_from_explicit_field、..._rejects_unknown_explicit、..._from_keywords、..._fallback
hint 提升 ..._basic、..._skips_empty_title、..._defaults
合成票据隔离 test_build_concept_with_synthetic_tickets、test_build_concept_synthetic_only_not_export_ready、test_build_concept_without_synthetic_omits_breakdown
合成上限 test_cap_synthetic_tickets_limits_count、..._floor_applies、..._no_truncation_needed
重叠度 test_overlap_ratio_partial、..._case_insensitive、..._asymmetric_containment、..._one_empty
合并语义 test_merge_concepts_basic、..._entry_family_adoption、..._synthetic_fields、..._id_regeneration
去重策略 test_dedup_high_overlap_merge、test_dedup_keeps_distinct、test_dedup_different_hypothesis_never_merge
CLI 元数据 test_main_promote_hints_source_metadata、test_main_max_synthetic_ratio、test_main_no_dedup_flag、test_main_overlap_threshold_effect

测试通过 conftest.py 把 scripts/ 目录插入 sys.path,因此可以直接 import synthesize_edge_concepts as sec 调用内部函数——这也意味着文中涉及的函数名都是稳定的可调用接口,可用于你自己的诊断脚本。


15. 实践建议清单

结合源码行为,给出几条能显著提升输出质量的配置建议:

  1. 先用 --no-dedup 跑一次基线,记录原始概念数与 dedup_merged_count,再决定阈值。默认 0.75 偏保守,适合你想保留细微机制差异的阶段。
  2. --min-ticket-support 与票据收集窗口匹配。日频单日检测通常难以形成 3 张以上同簇票据,跨多日累积票据后再要求更高支持度更合理。
  3. hint 的 regime_bias 必须与票据 regime 字符串完全一致,否则 matched_hint_titles 会为空——这常常被误判为“hint 没生效”。
  4. 需要严格 v1 导出时显式传 --exportable-families,把默认四族收窄到 pivot_breakout,gap_up_continuation。
  5. 谨慎使用 --promote-hints 于产出环节。纯 hint 概念不可导出是设计上的保护,但混合概念会带上合成票据,评审时必须查看 real_ticket_count / synthetic_ticket_count 判断证据强度。
  6. 关注 ticket_file_count 与 ticket_count 的差额。差额大说明存在缺 id 或 hypothesis_type 的票据,属于上游数据质量问题,应在 edge-candidate-agent 侧修正。

16. 小结

Edge Concept Synthesizer 用一个约 850 行的单文件脚本,把“票据堆”变成“可证伪的机制假设”:三维聚类保证同一概念内部机制一致,九类假设映射为 thesis 与失效信号,containment 去重消除机制重叠的重复概念,合成票据上限与 export_ready_v1 判定把“想法”和“可导出策略”严格分开。理解这些源码级细节后,你不仅能正确调用 synthesize_edge_concepts.py,还能判断在什么情况下应该调整阈值、收窄可导出族,或者干脆回到票据生成阶段把证据补足。

相关文件速查:

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