claude-trading-skills 深度解析:Edge Concept Synthesizer 如何把检测器票据抽象为可复用的 Edge Concept

原创2026-11-14 20:00:291,934 阅读
文章标签:金融科技AI 技能人工智能数据分析

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. 快速开始与工作流

技能文档给出的五步工作流如下,可以直接当作日常操作清单:

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

命令示例(摘自 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:

  1. 抽象必须同时包含 thesis 与显式的 invalidation_signals;
  2. 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 采用两级策略:

  1. 显式优先:若 hint 有 hypothesis_type 且(去空白、转小写后)在白名单 KNOWN_HYPOTHESIS_TYPES 中,直接采用。因此 "Breakout"、" PANIC_REVERSAL " 都能正确归一到小写标准值(对应测试 test_infer_hypothesis_type_case_insensitive)。
  2. 关键词回退:把 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 合成票据的生成规则

promote_hints_to_tickets 的规则:

  • 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 合成票据上限的精确公式

cap_synthetic_tickets 使用:

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 的循环逻辑:

  1. 只对 hypothesis_type 相同的概念对进行比较(test_dedup_different_hypothesis_never_merge);
  2. 使用 overlap > overlap_threshold(严格大于,等于 0.75 时不合并);
  3. 合并后当前概念被替换为新对象,被合并者标记进 merged_indices 不再参与后续配对;
  4. 返回 (去重后列表, 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 收尾的三件事:

  1. 排序:按 (avg_priority_score, ticket_count) 双键降序。也就是说:先看平均优先级,平均分相同再看票据数。
  2. as_of 推导:取所有票据中最大 date 字符串;没有任何 date 时为 null。由于是字符串比较,ticket 的 date 应使用 YYYY-MM-DD 格式,与 detector 输出(as_of_date.isoformat())保持一致,否则排序语义不可靠。
  3. 写盘: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

下游有两个明确消费者:

由于这两个下游都依赖概念文件的结构,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. 实践检查清单

最后给出一份可直接对照执行的清单,涵盖从准备数据到交付概念的全部关键点:

  1. 票据目录交给脚本递归扫描,把 exportable/ 与 research_only/ 放在同一父目录即可。
  2. 保证每个 ticket 有 id 与 hypothesis_type,否则会被静默丢弃。
  3. entry_family 决定能否导出:research_only 不会进入入场族分布,也不会让 export_ready_v1 为 true。
  4. priority_score 会进入加权排序,合成票据默认只有 30 分,不要指望它抬高概念排名。
  5. date 用 YYYY-MM-DD,它决定输出中的 as_of。
  6. 需要严格对齐下游 v1 接口时显式传 --exportable-families,因为模块默认的可导出族比 v1 契约更宽。
  7. 去重阈值是严格大于,且只在同 hypothesis_type 内生效;合并后概念 id 会变,请用 merged_from 追溯。
  8. --promote-hints 要配 --max-synthetic-ratio 使用,避免合成票据淹没真实证据;同时检查 source.real_ticket_count 与 synthetic_ticket_count。
  9. 评审时优先看 support.avg_priority_score 与 support.ticket_count 的组合,再看 export_ready_v1 与 regime 是否与当前局面匹配。
  10. 不要删除 research-only 概念,把它们作为“概念资产”保留,等待接口扩展后重新提升。

通过这一层抽象,观测数据、概念资产与策略资产被显式分开:单条 ticket 的价值在于“证据”,edge_concepts.yaml 的价值在于“可复用的机制假设”,而策略只是这一假设的一种实现形式。这正是 edge-concept-synthesizer 在 claude-trading-skills 中不可替代的原因。

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