Claude Trading Skills 中的 Edge Concept Synthesizer:把检测票据抽象为可复用的交易边缘概念
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 章节内容一致,都是五步:
- 从自动检测输出中收集票据 YAML 文件。
- 可选地提供
hints.yaml用于上下文匹配。 - 运行
scripts/synthesize_edge_concepts.py。 - 对概念去重:合并同假设、条件重叠(containment)超过阈值的概念。
- 评审概念,只把高支持度的概念推进到策略起草阶段。
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²) 的贪心算法,规则有三条硬约束:
- 只允许 同
hypothesis_type的概念合并;跨假设类型即使条件完全相同也绝不合并(test_dedup_different_hypothesis_never_merge)。 - 重叠度必须 严格大于 阈值(
> overlap_threshold),等于阈值不触发。 - 一旦合并,被合并方索引标记,不再参与后续比较。
合并语义由 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. 实践建议清单
结合源码行为,给出几条能显著提升输出质量的配置建议:
- 先用
--no-dedup跑一次基线,记录原始概念数与dedup_merged_count,再决定阈值。默认 0.75 偏保守,适合你想保留细微机制差异的阶段。 --min-ticket-support与票据收集窗口匹配。日频单日检测通常难以形成 3 张以上同簇票据,跨多日累积票据后再要求更高支持度更合理。- hint 的
regime_bias必须与票据regime字符串完全一致,否则matched_hint_titles会为空——这常常被误判为“hint 没生效”。 - 需要严格 v1 导出时显式传
--exportable-families,把默认四族收窄到pivot_breakout,gap_up_continuation。 - 谨慎使用
--promote-hints于产出环节。纯 hint 概念不可导出是设计上的保护,但混合概念会带上合成票据,评审时必须查看real_ticket_count/synthetic_ticket_count判断证据强度。 - 关注
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,还能判断在什么情况下应该调整阈值、收窄可导出族,或者干脆回到票据生成阶段把证据补足。
相关文件速查:
- 技能说明:skills/edge-concept-synthesizer/SKILL.md
- 输出 schema:skills/edge-concept-synthesizer/references/concept_schema.md
- 合成脚本:skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py
- 单元测试:skills/edge-concept-synthesizer/scripts/tests/test_synthesize_edge_concepts.py
- 流水线数据契约:skills/edge-pipeline-orchestrator/references/pipeline_flow.md
- 下游草案设计:skills/edge-strategy-designer/SKILL.md