claude-trading-skills 深度解析:Edge Concept Synthesizer 如何把检测器票据抽象为可复用的 Edge Concept
claude-trading-skills 深度解析:Edge Concept Synthesizer 如何把检测器票据抽象为可复用的 Edge Concept
在 claude-trading-skills 的 edge 研究链路中,edge-concept-synthesizer 承担一个非常关键的“中间层”角色:它把 detector 产出的零散 ticket 与 hints.yaml 聚类、抽象成带明确 thesis(论点)与 invalidation_signals(失效信号)的 edge_concepts.yaml,让后续的策略设计不再直接面对单条观察。读完本文,你将能独立准备输入数据、正确使用全部 CLI 参数、读懂并校验输出契约,并理解聚类、去重、hint 提升等底层逻辑的具体实现方式。
本文以日文版技能文档 docs/ja/skills/edge-concept-synthesizer.md 为主线,并结合技能主文档 skills/edge-concept-synthesizer/SKILL.md、输出格式参考 concept_schema.md、核心脚本 synthesize_edge_concepts.py 以及单元测试 test_synthesize_edge_concepts.py 逐层展开。
1. 技能概述:在“检测”和“策略实现”之间造一层抽象
技能文档给出的定位非常直接:在检测与策略实现之间创建抽象层。该技能会聚类 ticket 证据、汇总重复出现的条件,并输出包含显式 thesis 与失效逻辑的 edge_concepts.yaml。
这样设计的原因,在仓库的 edge 体系设计文档 docs/internal/edge_candidate_agent_design.md 中被明确成一条原则:
観察と戦略実装を直結させない(抽象化レイヤー必須)——不要让观察与策略实现直接相连,抽象层是必需的。
因此整个 edge 流水线被拆成四段:
edge-hint-extractor → hints.yaml (观察结构化为提示)
edge-concept-synthesizer → edge_concepts.yaml(提示/票据抽象为概念)
edge-strategy-designer → strategy_drafts/* (概念转为策略草稿)
edge-candidate-agent → export / validate (导出与契约校验)
edge-concept-synthesizer 的输入是「票据目录 + 可选 hints」,输出是「概念集合」。它不负责回测、不负责下单,也不做最终采纳决策——采纳仍保留人工评审环节。
2. 何时应该用它
技能文档列出三个典型场景,这些场景本质上都在解决同一件事:避免从单条 ticket 直接跳到策略所造成的过拟合。
| 场景 | 说明 | 对应实现机制 |
|---|---|---|
| 有大量原始 ticket,需要机制层面的结构化 | ticket 数量多但彼此散乱,无法看出哪些是同一类现象 | 以 hypothesis_type × mechanism_tag × regime 聚类 |
| 想规避 ticket→strategy 的直接过拟合 | 单条 ticket 的偶然性太强,不能直接变成入场规则 | 强制产出 thesis 与 invalidation_signals |
| 策略起草前需要概念级评审 | 希望在写策略代码前先做一次“概念是否成立”的判断 | --min-ticket-support 过滤 + 概念排序 |
另外还有一个隐含场景:当 ticket 样本过少、概念撑不起来时,可以用 --promote-hints 把高质量的 hints.yaml 提升为“合成票据”,补足概念密度(详见第 7 节)。
3. 前置条件与输入目录约定
技能文档的前置条件有四项:
- Python 3.9+
PyYAML- detector 输出产生的 ticket YAML 目录(
tickets/exportable、tickets/research_only) - 可选的
hints.yaml
依赖声明可以在 skills/edge-concept-synthesizer/requirements.txt 中确认:
# Runtime dependencies for standalone .skill installs (issue #330).
# Verified by scripts/check_skill_deps.py.
PyYAML>=6.0
3.1 ticket 文件的最小可用条件
脚本在 discover_ticket_files 中通过 rglob("*.yaml") 递归扫描目录,因此 tickets/exportable/ 与 tickets/research_only/ 两个子目录会被一次扫描覆盖,无需分别运行。
文件被读取后,read_ticket 会做一次硬校验:
if "id" not in payload or "hypothesis_type" not in payload:
return None
也就是说,缺少 id 或 hypothesis_type 的 YAML 会被静默跳过(不报错、不计数)。这一点在排查“明明放了很多文件但概念很少”时非常关键。
3.2 ticket 中真正被读取的字段
从源码看,概念构建实际消费的字段如下(其余字段会被保留在 ticket 中但不影响聚类结果):
| 字段 | 用途 | 读取位置 |
|---|---|---|
id |
写入 evidence.ticket_ids |
build_concept |
hypothesis_type |
聚类键第 1 维 | cluster_key |
mechanism_tag |
聚类键第 2 维,缺省 uncertain |
同上 |
regime |
聚类键第 3 维,缺省 Unknown |
同上 |
priority_score |
计算 avg_priority_score |
build_concept |
entry_family |
统计入场族分布 | build_concept |
observation.symbol 或 symbol |
统计代表标的 | ticket_symbol |
signal_definition.conditions / entry.conditions |
代表条件统计 | ticket_conditions |
date |
推导输出文件的 as_of |
main |
其中 ticket_symbol 的取值优先级是:observation.symbol 优先,其次回退到顶层 symbol,并且统一转成大写。这与 detector 实际写出的 ticket 结构一致——auto_detect_candidates.py 把标的写在 observation.symbol 里。
3.3 hints.yaml 的两种合法结构
read_hints 支持两种形态:
# 形态一:顶层列表
- title: "Breadth-supported breakout regime"
preferred_entry_family: pivot_breakout
regime_bias: RiskOn
# 形态二:{hints: [...]}
hints:
- title: "Seasonal buyback blackout"
observation: "Calendar-driven supply gap"
hypothesis_type: calendar_anomaly
symbols: ["SPY"]
regime_bias: Neutral
mechanism_tag: flow
若传入既不是 list 也不是 dict 的内容,会抛出 ConceptSynthesisError("hints file must be list or {hints: [...]} format");单条 hint 若不是 dict 则被过滤掉。空文件(safe_load 返回 None)会安全地当作“无 hint”处理,返回空列表。
4. 快速开始与工作流
技能文档给出的五步工作流如下,可以直接当作日常操作清单:
- 从自动检测输出中收集 ticket YAML 文件;
- 可选地提供
hints.yaml用于上下文匹配; - 运行
scripts/synthesize_edge_concepts.py; - 概念去重:合并同一假设下条件重叠的概念(包含率 > 阈值);
- 评审概念,只把高支持度的概念提升到策略起草阶段。
命令示例(摘自 SKILL.md):
# 基础用法:最少支持度 2
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
# 启用 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
# 自定义去重阈值
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
成功时会打印一行摘要(见 main):
[OK] concepts=3 synthetic_tickets=2 output=/tmp/edge-concepts/edge_concepts.yaml
5. 完整 CLI 参数表
技能文档只给出了命令示例,未逐项说明参数。以下参数表直接从 parse_args 提取,包含默认值与源码中的实际语义。
| 参数 | 类型 | 默认值 | 作用与实现语义 |
|---|---|---|---|
--tickets-dir |
str,必填 | 无 | 票据目录,递归扫描 *.yaml;不存在时退出码 1 |
--hints |
str | None |
可选 hints 文件;给出但不存在时退出码 1 |
--output |
str | reports/edge_concepts/edge_concepts.yaml |
输出路径,父目录会自动 mkdir(parents=True) |
--min-ticket-support |
int | 1 |
概念保留所需最少票据数;实际比较时取 max(value, 1),传 0 或负数等于 1 |
--promote-hints |
flag | False |
把合格 hint 提升为合成票据参与聚类 |
--synthetic-priority |
float | 30.0 |
合成票据的 priority_score |
--max-synthetic-ratio |
float | None |
合成/真实票据比上限;省略时不设限 |
--overlap-threshold |
float | 0.75 |
去重时条件包含率阈值(严格大于才合并) |
--no-dedup |
flag | False |
关闭去重,source.dedup_merged_count 记为 0 |
--exportable-families |
str | None |
逗号分隔的“可导出入场族”列表,覆盖模块默认集合 |
关于 --exportable-families 需要特别注意:脚本内部的 DEFAULT_EXPORTABLE_FAMILIES 是四个族:
DEFAULT_EXPORTABLE_FAMILIES = {
"pivot_breakout",
"gap_up_continuation",
"panic_reversal",
"news_reaction",
}
见 synthesize_edge_concepts.py。而内部设计文档中 Phase I 的 export 契约只覆盖 pivot_breakout 与 gap_up_continuation 两个族。这意味着在需要严格对齐下游 v1 接口时,应显式用 --exportable-families 收窄可导出族,否则 export_ready_v1 会比 v1 契约宽松:
python3 skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py \
--tickets-dir reports/edge_candidate_auto/tickets \
--output reports/edge_concepts/edge_concepts.yaml \
--min-ticket-support 2 \
--exportable-families pivot_breakout,gap_up_continuation
解析逻辑是简单的 split(",") 后去空白去空项,见 main。
6. 输出契约:逐字段解读 edge_concepts.yaml
concept_schema.md 给出了完整骨架。以下示例完整保留其结构,并在注释中标明由哪段源码生成:
generated_at_utc: "2026-02-22T12:00:00+00:00" # UTC,秒级精度,去掉微秒
as_of: "2026-02-20" # 所有 ticket 中最大的 date
source:
tickets_dir: "/tmp/edge-auto/tickets" # Path.resolve() 后的绝对路径
hints_path: "/tmp/hints.yaml"
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
# 仅在存在合成票据时出现(--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]
6.1 每个 support 字段的真实算法
support 块在 build_concept 中构造,几个容易误读的点:
ticket_count是该聚类内的票据总数,包含合成票据(若启用)。avg_priority_score是对所有 ticket 的priority_score求算术平均后round(..., 2);转换失败的值按0.0处理(safe_float)。symbols最多 10 个,按出现频次降序(symbol_counter.most_common(10))。entry_family_distribution排除两件事:值为research_only的族,以及所有合成票据的族。因此当概念完全由 hint 提升而来时,这个分布会是空字典。representative_conditions最多 6 条,按条件出现次数降序。
6.2 thesis 与 invalidation_signals 是硬性设计规则
concept_schema.md 明确了两条 Design Rule:
- 抽象必须同时包含
thesis与显式的invalidation_signals; export_ready_v1只有在推荐入场族被 pipeline interface v1 支持时才应为 true。
这两条在实现中不是“提示”,而是结构上强制的:abstraction 块由 HYPOTHESIS_TO_THESIS 与 HYPOTHESIS_TO_INVALIDATIONS 两个常量表按 hypothesis_type 直接映射生成,见 build_concept。也就是说,任何概念一定带有 thesis 和至少 2 条失效信号(未识别的假设类型会落到默认的 ["Out-of-sample behavior does not replicate.", "Costs erase edge expectancy."])。
6.3 export_ready_v1 的判定链路
recommended_entry_family = choose_recommended_entry_family(entry_counter, families)
export_ready_v1 = recommended_entry_family in families
见 build_concept。而 choose_recommended_entry_family 的逻辑是:按入场族出现次数从多到少遍历,返回第一个属于可导出集合的族;若一个都没有,返回 None。
这解释了一个实用现象:一个概念即使拥有 90 分的 priority_score,只要票据的 entry_family 都是 research_only,recommended_entry_family 就是 null、export_ready_v1 就是 false。单元测试 test_build_concept_for_news_reaction_is_research_only 正是验证这一行为。
7. hint 提升:--promote-hints 的完整机制
当真实票据不足时,可以把 hints.yaml 中的提示“提升”为合成票据,让概念密度达到 --min-ticket-support 的要求。这并非简单复制,而是一条带类型推断与配比控制的流水线。
7.1 假设类型推断
infer_hypothesis_type 采用两级策略:
- 显式优先:若 hint 有
hypothesis_type且(去空白、转小写后)在白名单KNOWN_HYPOTHESIS_TYPES中,直接采用。因此"Breakout"、" PANIC_REVERSAL "都能正确归一到小写标准值(对应测试test_infer_hypothesis_type_case_insensitive)。 - 关键词回退:把
title与observation拼接后小写,对每个类型的关键词计命中数,取命中最多者;都不命中则落到research_hypothesis。
关键词表位于 synthesize_edge_concepts.py,摘要如下:
| 假设类型 | 关键词 |
|---|---|
breakout |
breakout, pivot, participation, high20 |
earnings_drift |
earnings, drift, post-event, post_event, pead |
news_reaction |
news, reaction, headline, catalyst |
futures_trigger |
futures, cross-asset, cross_asset, propagation |
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 |
注意 KNOWN_HYPOTHESIS_TYPES 只包含 8 个类型,不含 research_hypothesis——它是 FALLBACK_HYPOTHESIS_TYPE,只能在推断失败时出现,不能通过显式字段指定。
7.2 合成票据的生成规则
title为空或纯空白的 hint 直接跳过;mechanism_tag缺省"uncertain",regime缺省"Unknown";preferred_entry_family只有在属于可导出族时才保留,否则统一置为"research_only";- ticket id 形如
hint_promo_<归一化标题>_<序号>,SYNTHETIC_TICKET_PREFIX为hint_promo_; priority_score使用--synthetic-priority(默认 30.0),显著低于真实票据的典型分数;- 仅保留
symbols列表中的第一个标的写入observation.symbol; - 打上内部标记
_synthetic: True,供后续统计区分。
由于第 5 条,entry_family 被置为 research_only 的合成票据不会进入 entry_family_distribution,也就无法单独把概念的 export_ready_v1 顶成 true——合成票据只能补足支持度,不能凭空制造可导出性。
7.3 合成票据上限的精确公式
limit = max( ceil(len(real_tickets) * max_ratio), 3 )
超出上限时按 priority_score 降序裁剪。注意 floor=3 的存在:即便 --max-synthetic-ratio 0,也仍会保留最多 3 条合成票据;这是测试 test_cap_synthetic_tickets_floor_applies 所覆盖的行为。当 --max-synthetic-ratio 省略时,完全不裁剪。
7.4 启用提升后输出多出来的元数据
一旦 --promote-hints,main 会在 source 块中追加:
source:
promote_hints: true
real_ticket_count: 20
synthetic_ticket_count: 4
dedup_enabled: true
overlap_threshold: 0.75
dedup_merged_count: 1
对应地,概念级会额外出现 support.real_ticket_count、support.synthetic_ticket_count 与 evidence.synthetic_ticket_ids。这是审计“概念支持度里有多少来自真实观察”的唯一入口。
8. 概念去重:包含率、贪心合并与字段合并规则
去重的目标在文档中被概括为“同一假设下、条件重叠的概念合并(包含率 > 阈值)”。实现上这是一个两段式设计:先算包含率,再做贪心配对。
8.1 包含率定义(不是 Jaccard)
condition_overlap_ratio 使用包含率而非 Jaccard 相似度:
overlap = |A ∩ B| / min(|A|, |B|)
并且:
- 比较前对每条条件做
strip().lower(),因此Close > MA50与close > ma50视为同一条(test_overlap_ratio_case_insensitive); - 任一侧为空列表时返回
0.0(不合并); - 由于除以
min(|A|,|B|),小集合完全被大集合覆盖时比值就是 1.0(test_overlap_ratio_asymmetric_containment)。
8.2 贪心配对与“严格大于”
deduplicate_concepts 的循环逻辑:
- 只对
hypothesis_type相同的概念对进行比较(test_dedup_different_hypothesis_never_merge); - 使用
overlap > overlap_threshold(严格大于,等于 0.75 时不合并); - 合并后当前概念被替换为新对象,被合并者标记进
merged_indices不再参与后续配对; - 返回
(去重后列表, merge_count),后者写入source.dedup_merged_count。
由于是贪心一次遍历,合并结果与概念在列表中的原始顺序有关;概念顺序又取决于 grouped 字典(按 ticket 出现顺序)的插入次序。这一点在对比两次运行结果时需要留意。
8.3 合并时每个字段怎么处理
merge_concepts 的规则相当细,值得单独列出:
| 字段 | 合并策略 |
|---|---|
| primary 归属 | ticket_count 更多者为主;相等时保留前者 |
support.ticket_count |
直接相加 |
support.avg_priority_score |
按票据数加权平均,保留 2 位小数 |
support.symbols |
有序并集(保持 primary 顺序,追加去重后的 secondary 标的) |
mechanism_tag |
不同则用 "+" 连接排序后的两值,如 behavior+flow;相同则保留 |
support.entry_family_distribution |
按 key 累加 |
support.representative_conditions |
大小写不敏感去重后取并集,再截断到 6 条 |
strategy_design.recommended_entry_family |
primary 优先,None 时回退 secondary |
strategy_design.export_ready_v1 |
用最终 recommended_entry_family 重新判定 |
evidence.ticket_ids |
有序并集(primary 在前) |
evidence.matched_hint_titles |
集合去重后排序 |
evidence.synthetic_ticket_ids |
有序并集,仅当任一侧存在时输出 |
id |
用合并后的 hypothesis + merged_mechanism + regime 重新生成 |
merged_from |
追加被合并概念的 id 列表 |
id 重生成是 merge_concepts 里最容易出乎意料的一步:合并后 id 可能变成 edge_concept_breakout_behavior+flow_riskon,因此不要把概念 id 当作稳定主键缓存到外部系统——它以 merged_from 作为可追溯线索(test_merge_concepts_id_regeneration)。
9. 排序、as_of 与写盘行为
main 收尾的三件事:
- 排序:按
(avg_priority_score, ticket_count)双键降序。也就是说:先看平均优先级,平均分相同再看票据数。 as_of推导:取所有票据中最大date字符串;没有任何date时为null。由于是字符串比较,ticket 的date应使用YYYY-MM-DD格式,与 detector 输出(as_of_date.isoformat())保持一致,否则排序语义不可靠。- 写盘:
output_path.parent.mkdir(parents=True, exist_ok=True)后以yaml.safe_dump(..., sort_keys=False)写入,因此字段顺序与构造顺序一致,便于人工 diff 与审查。
generated_at_utc 使用 datetime.now(timezone.utc).replace(microsecond=0).isoformat(),因此会有 +00:00 后缀,与 schema 示例一致。
10. 错误处理、退出码与排查
脚本用 ConceptSynthesisError 统一收敛可预期的失败,并在 main 中捕获后打印 [ERROR] ... 到 stderr、返回 1。
| 触发条件 | 行为 | 代码位置 |
|---|---|---|
--tickets-dir 不存在 |
<a href="https://link.gitcode.com/i/bca894ae95eb478093bc9f2f1666e61b" target="_blank">ERROR] tickets dir not found: ...,退出码 1 |
[main |
--hints 指定但文件不存在 |
<a href="https://link.gitcode.com/i/520fae3d43ac2329379fc4112cc84fa1" target="_blank">ERROR] hints file not found: ...,退出码 1 |
[main |
| 目录中没有任何合法 ticket | <a href="https://link.gitcode.com/i/12dcadb19e0aa16063402e0ca383d0fa" target="_blank">ERROR] no valid ticket files found,退出码 1 |
[main |
所有概念都被 --min-ticket-support 过滤掉 |
<a href="https://link.gitcode.com/i/b50c194711524a670cd86bdc3f77a655" target="_blank">ERROR] no concepts passed min-ticket-support filter,退出码 1 |
[main |
hints.yaml 结构非法 |
hints file must be list or {hints: <a href="https://link.gitcode.com/i/5370d79a8310e013f3f2c7d46aad68c0" target="_blank">...]} format,退出码 1 |
[read_hints |
排查经验(依据源码推断):
- “no valid ticket files found”但目录里确实有 yaml:先确认文件是顶层 dict(非 list),且同时含
id与hypothesis_type。 - 概念数为 0 但票据很多:多半是
--min-ticket-support设得太高,或票据被切成了过多的hypothesis_type × mechanism_tag × regime组合。此时可以先用--no-dedup且在较低--min-ticket-support 1下运行一次,观察聚类分布。 export_ready_v1全为 false:检查票据entry_family是否多为research_only,以及--exportable-families是否被收得过窄。
11. 在 edge 流水线中的位置与下游衔接
设计文档的流程图把本技能定位为 Stage B,上承 hint 抽取、下接策略设计。这一点在代码中有明确证据:orchestrate_edge_pipeline.py 把本脚本注册为 concepts 阶段:
SCRIPT_PATHS = {
"auto_detect": ... "auto_detect_candidates.py",
"hints": ... "build_hints.py",
"concepts": ... "synthesize_edge_concepts.py",
"drafts": ... "design_strategy_drafts.py",
"review": ... "review_strategy_drafts.py",
"export": ... "export_candidate.py",
}
设计文档给出的标准四段命令(节选自 docs/internal/edge_candidate_agent_design.md)如下,可作为端到端落地模板:
# 1) detector:从 OHLCV 自动检测票据
python3 skills/edge-candidate-agent/scripts/auto_detect_candidates.py \
--ohlcv data/us_ohlcv.parquet \
--output-dir reports/edge_candidate_auto \
--top-n 12 --top-research-n 10
# 2) hints:观察结构化为 hints.yaml
python3 skills/edge-hint-extractor/scripts/build_hints.py \
--market-summary reports/edge_candidate_auto/market_summary.json \
--anomalies reports/edge_candidate_auto/anomalies.json \
--output reports/edge_hints/hints.yaml
# 3) concepts:票据 + hints → 概念
python3 skills/edge-concept-synthesizer/scripts/synthesize_edge_concepts.py \
--tickets-dir reports/edge_candidate_auto/tickets \
--hints reports/edge_hints/hints.yaml \
--output reports/edge_concepts/edge_concepts.yaml \
--min-ticket-support 2
# 4) drafts:概念 → 策略草稿(含 exportable_tickets)
python3 skills/edge-strategy-designer/scripts/design_strategy_drafts.py \
--concepts reports/edge_concepts/edge_concepts.yaml \
--output-dir reports/edge_strategy_drafts \
--exportable-tickets-dir reports/edge_strategy_drafts/exportable_tickets \
--risk-profile balanced
下游有两个明确消费者:
- edge-strategy-designer:读取
edge_concepts.yaml生成core/conservative/research_probe变体; - edge-signal-aggregator:通过
--edge-concepts reports/edge_concepts_*.yaml读取概念文件做聚合。
由于这两个下游都依赖概念文件的结构,abstraction.thesis、abstraction.invalidation_signals、strategy_design.recommended_entry_family、strategy_design.export_ready_v1 这四项在设计中被称为必须的运用项(docs/internal/edge_candidate_agent_design.md)。
12. 运营层的“概念门”:阈值怎么定
设计文档把所有概念评审收敛成一个 Concept Gate:
Concept Gate:
thesis与invalidation_signals明确;support 达到最低阈值以上(--min-ticket-support)。
结合源码,这个门在实际运行时可以落到三组可观测量:
| 检查项 | 判据 | 数据来源 |
|---|---|---|
| 逻辑可解释 | abstraction.thesis 非空、invalidation_signals 至少 2 条 |
由映射表保证 |
| 支持度充足 | support.ticket_count >= --min-ticket-support |
聚类过滤 |
| 可立即验证 | strategy_design.export_ready_v1 == true |
入场族分布 |
文档给出的 MVP 建议是 --min-ticket-support 2、risk profile 固定 balanced、export 仅限 pivot_breakout / gap_up_continuation、每周一次采纳会议、每月一次失效监控。对于 research-only 概念,文档强调「研究候補は捨てない」——不要把 research-only 概念丢掉,而是保留在 edge_concepts.yaml 与 research_probe 草稿中,等接口扩展后再重新提升。
13. 测试覆盖带来的行为保证
单元测试 test_synthesize_edge_concepts.py 共覆盖 40 余个用例,可分为六组,正好对应本文前面拆解的实现点:
| 分组 | 代表用例 | 保证的行为 |
|---|---|---|
| 概念构建 | test_build_concept_for_breakout_is_export_ready |
pivot_breakout 票据 → export_ready_v1: true、ticket_count 正确 |
| 类型推断 | test_infer_hypothesis_type_from_keywords / _fallback |
关键词可命中 calendar_anomaly,无命中落到 research_hypothesis |
| hint 提升 | test_promote_hints_to_tickets_basic / _skips_empty_title |
id 前缀、_synthetic 标记、空标题跳过 |
| 合成上限 | test_cap_synthetic_tickets_limits_count / _floor_applies |
ceil 公式与最小 3 条下限 |
| 包含率 | test_overlap_ratio_asymmetric_containment / _case_insensitive |
除以 min 的包含式定义、大小写不敏感 |
| 去重合并 | test_dedup_high_overlap_merge / _different_hypothesis_never_merge、test_merge_concepts_id_regeneration |
阈值行为、跨假设不合并、id 重生成 |
| 端到端 main | test_main_promote_hints_source_metadata / test_main_overlap_threshold_effect / test_main_no_dedup_flag |
source 元数据、阈值与 --no-dedup 的输出差异 |
测试文件顶部采用 import synthesize_edge_concepts as sec 直接导入模块,因此用例既能验证脚本内部函数,也能通过 monkeypatch 改写 sys.argv 来驱动 main()。若要本地复跑,可按仓库的测试组织方式执行对应目录下的用例(该技能测试位于 skills/edge-concept-synthesizer/scripts/tests/)。
14. 实践检查清单
最后给出一份可直接对照执行的清单,涵盖从准备数据到交付概念的全部关键点:
- 票据目录交给脚本递归扫描,把
exportable/与research_only/放在同一父目录即可。 - 保证每个 ticket 有
id与hypothesis_type,否则会被静默丢弃。 entry_family决定能否导出:research_only不会进入入场族分布,也不会让export_ready_v1为 true。priority_score会进入加权排序,合成票据默认只有 30 分,不要指望它抬高概念排名。date用YYYY-MM-DD,它决定输出中的as_of。- 需要严格对齐下游 v1 接口时显式传
--exportable-families,因为模块默认的可导出族比 v1 契约更宽。 - 去重阈值是严格大于,且只在同
hypothesis_type内生效;合并后概念 id 会变,请用merged_from追溯。 --promote-hints要配--max-synthetic-ratio使用,避免合成票据淹没真实证据;同时检查source.real_ticket_count与synthetic_ticket_count。- 评审时优先看
support.avg_priority_score与support.ticket_count的组合,再看export_ready_v1与regime是否与当前局面匹配。 - 不要删除 research-only 概念,把它们作为“概念资产”保留,等待接口扩展后重新提升。
通过这一层抽象,观测数据、概念资产与策略资产被显式分开:单条 ticket 的价值在于“证据”,edge_concepts.yaml 的价值在于“可复用的机制假设”,而策略只是这一假设的一种实现形式。这正是 edge-concept-synthesizer 在 claude-trading-skills 中不可替代的原因。