KnowledgeGraphService 子系统设计

1. 职责定义

KnowledgeGraphService 承接 ADR-007 supplement 中 M1 / M3 / M5 / M6 在工程层的图谱存储 / 查询 / 跨市场映射 / 相位时钟职责。具体覆盖：

• M1 关系建模含跨市场映射边（ADR-007 supplement §2.1 M1）—— 把 M1 输出的实体 / 关系 / 属性、跨市场映射边（direct-counterpart / industry-chain-mirror / narrative-mirror / policy-substitute）、shared-book 候选边持久化为可查询图谱。
• M3 phase 判定（ADR-007 supplement §2.1 M3）—— 维护 M3.t1–M3.t9 全 9 类时钟槽位，含 M3.t8 Koo 资产负债表时钟与 M3.t9 Minsky 子相位；以及综合层的跨时钟相位差矩阵（N×N）。
• M5 制度摩擦传导（ADR-007 supplement §2.1 M5）—— 在 M1 对象图上叠加 M5.1 链路 / M5.2 反身性 / M5.3 shared-book 四形态 / M5.4 制度摩擦层 / M5.5 反向力量 / M5.8 相关性跃迁 / M5.9 Mundell-Fleming 占位。
• M6 资本结构 + 货币双轨（ADR-007 supplement §2.1 M6）—— 承载 M6.X 资本结构层（MM 定理）与 M6.7 名义 / 实质双轨标志位的对象属性写回，喂回 M6.1 估值支柱 WACC / 终值 / 违约距离三处。

输出 ADR-008 supplement 1.1 契约的 causal_graph（含 correlation_regime）与 phase_evidence（含 phase_matrix）两个顶层字段（ADR-008 supplement §2.1 / §2.2）。

2. 接口契约

接口签名采用 pseudo-Python，仅锁定方法签名层级，不写完整实现。字段类型对齐 ADR-008 supplement 工程契约口径（snake_case）。

class KnowledgeGraphService:
    def upsert_entity(self, entity_id: str, entity_attrs: dict) -> None: ...
    def upsert_relation(
        self,
        relation_id: str,
        from_entity_id: str,
        to_entity_id: str,
        relation_type: Literal["direct-counterpart", "industry-chain-mirror",
                               "narrative-mirror", "policy-substitute", ...],
        attrs: dict,
    ) -> None: ...

    def query_subgraph(
        self,
        seed_entity_ids: list[str],
        depth: int = 2,
        edge_types: list[str] | None = None,
    ) -> SubgraphView: ...

    def get_clock_phase(
        self,
        entity_id: str,
        clock_id: Literal["M3.t1", "M3.t2", ..., "M3.t9"],
        as_of: datetime,
    ) -> ClockPhase: ...

    def assemble_phase_matrix(
        self,
        entity_id: str,
        active_clock_ids: list[str],
        as_of: datetime,
    ) -> ClockPhaseMatrix: ...

    def build_transmission_graph(
        self,
        seed_entity_ids: list[str],
        scenario_id: str,
        mca_bucket: MCABucket,
        as_of: datetime,
    ) -> TransmissionGraph: ...

    def classify_correlation_regime(
        self,
        graph: TransmissionGraph,
        market_state_window: MarketStateWindow,
    ) -> CorrelationRegime: ...

    def detect_unbalanced_loops(
        self,
        graph: TransmissionGraph,
    ) -> list[UnbalancedLoopWarning]: ...

TransmissionGraph / ClockPhase / ClockPhaseMatrix / CorrelationRegime / UnbalancedLoopWarning 子模型字段定义以 ADR-008 supplement §2.1 / §2.2 为事实源；派生 Pydantic schema 见 StructuredCognitionResult 1.1 契约源。

子模型类型 placeholder（M0 阶段简定义）

接口签名引用的下列类型在 ADR-008 supplement / 1.1 契约源中尚未给出字段定义，本节给 M0 阶段的最小 Pydantic v2 placeholder，目的仅是让 Codex import 链闭合（class X(BaseModel) 不缺）。字段细节留 M1+ 收紧路径见本子系统 §9 实现里程碑映射 + 后续 milestone-field-evolution-matrix.md 起草；事实源回写发生于 ADR-008 supplement v2 / 1.1 契约源后续 patch 段。

# M0 placeholder 段。M1+ 收紧字段定义；事实源在 ADR-008 supplement v2 / cognition-1.1-contract.md v1.2 时回写。
from pydantic import BaseModel


class MarketStateWindow(BaseModel):
    """M0 placeholder。承载 `classify_correlation_regime` 所需的市场状态窗口元数据。"""

    start_ts: int  # Unix epoch ms
    end_ts: int  # Unix epoch ms
    rolling_days: int = 60  # 默认 60 个交易日，对齐本子系统 §7 待解项口径
    # 其它字段待 M1+ 锁定

3. 数据流

• 输入源：
  • M1 模型输出的实体 / 关系候选（来自 LLM Function Calling 经 Task Orchestration 子系统派发）。
  • 外部数据 Providers 价格 / 链上 / 财报 / 政策公告等归一化证据单元（经 Provider Adapter 与 Evidence + Synthesis 子系统传入）。
  • MCAClassifier 子系统输出的 mca_bucket 元数据（影响 M5.3 形态选择 / M3.t7 命名空间实例化 / M5.8 相关性跃迁阈值）。
• 内部处理：
  • 实体 / 关系 upsert 到底层图谱存储；shared-book 候选边在 mca_bucket 触发条件下激活。
  • 时钟阶段按 entity_id × clock_id × as_of 三元组缓存；综合层调用 assemble_phase_matrix 时按 ADR-007 supplement §M3.t7 的三段式路径拼装。
  • M5 传导图构建走「M1 子图召回 → M4 场景骨架对齐 → M5 子机制叠加（含 M5.4 / M5.5 / M5.6 / M5.8）→ 反向力量召回」。
  • correlation_regime 在传导图构建后调用相关性跃迁分类（按 ADR-007 supplement §2.1 M5.8 Longin-Solnik / MPT 反向应用判定）。
• 输出 StructuredCognitionResult 1.1 字段：
  • phase_evidence.clocks（LLM 产出 + 服务规整）+ phase_evidence.phase_matrix（本子系统综合层拼装）。
  • causal_graph.nodes / causal_graph.edges / causal_graph.reverse_forces / causal_graph.endogeneity / causal_graph.correlation_regime / causal_graph.unbalanced_loop_warnings。
  • 间接喂回 regulation_status.friction_layer（M5.4 制度摩擦层节点 / 边的属性投影，由 ConsistencyMiddleware 与 Evidence + Synthesis 协同消费）。
  • 间接喂回 applicability_flags（M6 三支柱适用性 partial 边缘判定依赖 M6.X 资本结构属性 + M6.7 双轨标志位）。

4. 关键依赖

依赖类型	内容
外部数据源	价格行情 / 链上数据 / SEC filings / 财报数据 / 政策公告 / CFTC TFF / 13F / FX swap / ETF flow / GBTC 折溢价 / 两融余额 等（具体清单见 ADR-007 supplement §5.3 工程依赖段）
内部模块	Evidence + Synthesis 子系统（消费归一化证据）/ MCAClassifier（消费桶位元数据）/ State Management（持久化图谱快照）/ Provider Adapter（LLM 调用经统一接入层）
持久化	图谱存储 v1 走嵌入式 SQLite + 邻接表 + JSON 字段（与架构主稿 §15 数据存储划分 单机本地优先口径对齐）；v2 可演化到 Neo4j / NetworkX 内存视图

5. 测试要求

测试维度对齐 EvalHarness 子系统的 11 维评测 + 7 MCA 桶（评测台架）。

• 单元测试：
  • upsert_entity / upsert_relation 字段约束（关系类型枚举合法性 / 跨市场映射边四类语义完整覆盖）。
  • get_clock_phase 在 M3.t8 Koo 三阶段（正常期 / 偿债优先期 / 修复完成期）与 M3.t9 Minsky 三子相位（Hedge / Speculative / Ponzi）边界条件正确切换。
  • classify_correlation_regime 在 normal / tail-coupled / regime-switched 三态枚举上的判定。
  • detect_unbalanced_loops 在反向力量缺失链路上的 flag 正确性。
• 集成测试：
  • 与 MCAClassifier 联动：MCA 轴 1 = L3 + 轴 4 = N3 + 轴 5 = C3 组合下激活 M5.3 (c) 政策信用触发型；轴 1 = L3 单激活下激活 M5.3 (d) 散户急性版。
  • 与 ConsistencyMiddleware 联动：传导图构建后 correlation_regime.regime_label = regime-switched 触发 ConsistencyMiddleware 的 attention 二阶分支检查。
• 评测维度（消费方为 EvalHarness）：
  • D1 本体识别准确率（M1 全子机制）。
  • D3 跨时钟相位识别（强制评 M3.t1 / M3.t2 / M3.t5 三槽位，其余抽样 IAA）。
  • D4 场景命中 + 传导链路完整性（节点 F1 0.35 + 边 F1 0.35 + 子图同构匹配率 0.30）。
  • D5 金融规律应用 + 规律不适用识别（M6 三支柱 + M6.X 资本结构）。
  • D9 跨市场对照推理（必须跨 ≥ 2 MCA 桶，承接 M5.8 correlation_regime）。
• 端到端测试：M0 走通骨架 5 条样例输入的 causal_graph + phase_evidence 录制 → 重放稳定性校验。

6. v1 工程回退

v1 阶段允许半人工标注的字段（承接 Phase 7 半人工标注 SLA 附录）：

• causal_graph.edges[?].form = "policy-credit"：对应任务 A · M5.3(c) 政策信用触发型标注，事件驱动 ≤ 48 小时 SLA / IAA kappa ≥ 0.65 / 准确率 ≥ 70%。
• causal_graph.edges[?].form = "a-share-retail-acute"：对应任务 B · M5.3(d) A 股散户急性版，事件驱动 ≤ 24 小时 SLA / IAA kappa ≥ 0.70 / 准确率 ≥ 75%。
• M5.3 (c)(d) 形态判定的双 reviewer 盲交叉机制 + 24h SLA + IAA kappa ≥ 0.7 入评测池 + 半人工标注 case 进入 contested-points 不强制收敛。

必须模型自动产出（不允许人工标注覆盖最终值）：

• phase_evidence.clocks 全部子字段。
• phase_evidence.phase_matrix.cells（综合层自动拼装）。
• causal_graph.nodes / causal_graph.edges 主体结构（M1 / M5 链路建模产物）。
• causal_graph.correlation_regime.regime_label（M5.8 相关性跃迁分类）。

7. 待解决问题 / 已知 trade-off

• M5.9 Mundell-Fleming 占位激活路径：ADR-007 supplement §5.1 登记 v1 占位、待 L7 / L11 / L2 case 在 Phase 7+ 接入后激活。v1 阶段 causal_graph.nodes / edges 兼容承载，本子系统不强制语义解读。
• 图谱存储选型 v1 → v2：v1 走 SQLite 嵌入式 + JSON 字段是为了本地优先单机部署口径，但跨子图召回与多跳查询性能上限有限；v2 路径待第一阶段评测压测后决议（候选 Neo4j / NetworkX 内存 / DuckDB 图扩展）。
• M6.X ↔ M6.1 双向耦合求解顺序：ADR-007 supplement §5.3 登记 v1 建议两轮迭代（先 M6.1 baseline → M6.X 调整 → M6.1 二轮收敛），最终求解顺序由架构 ADR 锁定。本子系统暂以「先 M6.1 出 baseline」单轮兜底，二轮收敛留 M1+ 实现。
• 跨市场映射边四类语义的边权重设计：ADR-007 supplement §2.1 M1.2 锁定四类语义，但路径置信度 / 翻译损耗的初始值尚未校准；v1 用一致默认值（0.5 / 0.0），待 14 case 反向校准后调整。
• correlation_regime.pair_correlations 计算窗口：v1 暂以滚动 60 个交易日为默认窗口，未在 ADR 中锁定，待评测反馈后校准。

8. 与其它子系统的接口对齐

• MCAClassifier：本子系统在 build_transmission_graph / classify_correlation_regime / assemble_phase_matrix 调用前必须取得 MCAClassifier 输出的 mca_bucket，桶位组合作为 M5.3 形态选择 / M3.t7 命名空间实例化 / M5.8 阈值的强先验。接口为同步调用，MCAClassifier 输出延迟由其自身 SLA 兜底。
• ConsistencyMiddleware：本子系统输出的 causal_graph + phase_evidence 在认知结论发布前先过 ConsistencyMiddleware 的 S1 横切判定；ConsistencyMiddleware 反向触发（一致性中间件 §3）可能要求本子系统重算 correlation_regime / 调整 M5.5 反向力量召回阈值（M5 / M6 / M7 重算回路）。
• EvalHarness：本子系统的所有顶层字段产物按 评测台架 11 维评测 + 7 MCA 桶分层抽样消费；评测产生的退化追踪反向触发 Phase 5 治理流程（季度全量评估 / 触发式专项）。
• 既有子系统（Evidence + Synthesis / State Management / Provider Adapter）：本子系统是 Evidence + Synthesis 的下游协作模块，证据归一化产物喂入；图谱快照写入 State Management 持久化层；LLM 调用走 Provider Adapter 统一接入层。

9. 实现里程碑映射

承接 架构主稿 §29 v1 实现路径建议 与 M0 Walking Skeleton §3.5。

里程碑	本子系统落地范围	不落地（留下个里程碑）
M0	causal_graph / phase_evidence / correlation_regime 三顶层字段以 extra="ignore" stub 形式存在；build_transmission_graph / assemble_phase_matrix / classify_correlation_regime 接口签名落地，内部返回 fixture 固定结构（不调 LLM）；产物以 JSON blob 落入 audit_events.payload，不入专列	M5.5 反向力量召回算法、M5.8 相关性跃迁判定、M3 9 时钟跨市场命名空间实例化、滚动 60 日窗口校准
M1	causal_graph / phase_evidence 升级为 judgment_records 独立索引列；M5.1–M5.3 主干传导链路上线（M5.5 反向力量先以人工标注 placeholder）；M3.t1 / M3.t2 / M3.t5 三槽位先落，其余 6 槽位走 stub	M5.5 自动召回（仍人工标）、M5.8 相关性跃迁、M3.t8 / M3.t9（Koo / Minsky 子相位）、跨市场命名空间完整实例化
M2	M5.5 反向力量自动召回（按 ADR-007 supplement §2.1 v1→v2 路径门槛）；M3 9 时钟全部上线；correlation_regime.pair_correlations 滚动窗口接入 12 数据 provider	M5.8 相关性跃迁标签自动判定（仍走人工 + 半自动）
M3	M5.8 相关性跃迁自动判定 + M6 三态适用性的图谱侧依赖联动；跨市场命名空间在 B7 EM 主权桶完整实例化	跨工作流的 v2 体系演进项（按 Phase 5 治理流程节奏）