Context Graph 与决策模型

专题结论

Semantica 最值得参照的是“上下文、决策、审批、先例、有效期和因果关系都作为一等图对象”的数据契约。当前实现把过多职责集中在一个大类中，适合作为领域模型样本，不适合直接扩展为业务核心。

建议：强参照模型与交互语义；不直接复制巨型类；用自有存储、事务和权限服务重建写入链。

1. 核心对象与职责

原始调用链

DecisionRecorder.record_decision()（接收决策、实体和来源文档并协调写入的方法）依次调用 DecisionRecorder._store_decision_node()（把决策写入图存储的方法）、DecisionRecorder.link_entities()（建立决策到实体关系的方法），并在来源管理器存在时调用 DecisionRecorder._track_decision_provenance()（追加决策来源记录的方法）。输入是一个决策对象、实体 ID 列表和来源文档列表；输出是决策 ID；中间会改变图存储与可选来源存储，但源码没有把两者包进同一个跨存储事务。

2. 数据契约要点

2.1 节点和边共享有效期语义

valid_from（节点或边开始在业务上有效的重要字段，约第 328、373 行）与 valid_until（节点或边停止在业务上有效的重要字段，约第 329、374 行）同时存在于节点和边中。这样不仅能问“某实体当时是否存在”，还能问“某条关系当时是否成立”。

state_at()（按指定时刻重建活动节点和活动边的方法，约第 2590 行）将该契约转化为历史快照。这个设计适合决策复盘，但仍应与系统记录时间配合，避免把业务有效时间误当成系统获知时间。

2.2 撤回和物理删除必须分开

retract_node()（保留节点并记录撤回元数据的逻辑撤回方法，约第 1556 行）适合审计场景；purge_node()（删除节点、关联边和索引记录的物理清理方法，约第 1718 行）属于高风险管理操作。

借鉴时应把两种动作拆成不同权限、不同审批和不同审计事件，并默认只开放可恢复的逻辑撤回。

2.3 决策关系比“决策表”更有表达力

DecisionContext（保存一次决策使用的实体快照、风险因素和跨系统输入的模型，约第 140 行）、Policy（保存政策规则、类别、版本及创建和更新时间的模型，本身没有有效期字段，约第 175 行）、Precedent（保存来源决策、相似度和关系类型的先例关系模型，本身没有独立适用条件字段，约第 260 行）与 ApprovalChain（名字虽为审批链、实际保存单条审批的审批人、方式、上下文和时间，没有步骤集合或状态字段，约第 298 行）共同提供解释决策所需的关系素材，但采用时不能把类名所暗示的能力当成已经存在的字段。

record_decision()（创建决策并协调关联实体、来源与后续关系的方法，约第 115 行）适合作为自有系统中“单一决策写入口”的参考，但生产实现必须用数据库事务或可靠事件保证决策与证据不会部分成功。

3. 因果关系的证据等级

add_causal_relationship()（显式写入两个决策之间因果边的方法，约第 2734 行）表达调用方确认的因果关系；trace_decision_causality()（结合显式边、共享实体与时间顺序生成因果或影响链的方法，约第 3544 行）还会生成启发式候选。

原项目关键片段——ContextGraph.trace_decision_causality()（生成启发式影响候选的方法片段）。

固定提交片段：启发式影响候选 原项目关键片段

# Find potential causes (decisions that influenced this one) via
# shared entities/timestamps - additive heuristic, skipping anything
# already covered by an explicit relationship above.
potential_causes = []
for entity in current_decision["entities"]:
    for other_decision_id in self._entity_index.get(entity, set()):
        if other_decision_id != current_id and other_decision_id not in explicit_cause_ids:
            other_decision = self._decisions[other_decision_id]
            if other_decision["timestamp"] < current_decision["timestamp"]:
                potential_causes.append(other_decision_id)

for cause_id in potential_causes:
    cause_dec = self._decisions.get(cause_id, {})
    edge_weight = float(cause_dec.get("confidence", 1.0))
    hop = {
        "from": cause_id,
        "from_scenario": cause_dec.get("scenario", ""),
        "to": current_id,
        "to_scenario": current_decision.get("scenario", ""),
        "type": "influences",
        "edge_weight": edge_weight,
    }

这段实现证明共享实体和较早时间就能产生 influences（启发式影响候选使用的关系类型值）；它支持“显式因果与启发式影响必须分级展示”的事实判断。可借鉴的是候选关系的单独类型和得分；不能照搬的是把候选与调用方明确写入的因果边放进同一种无差别结果视图。

这两类结果不能只用一条“因果链”视觉样式。建议至少显示：

• 显式因果：实线、来源和确认人可见；
• 推测影响：虚线、得分和推测依据可见；
• 未确认候选：默认不参与自动决策，只进入人工审查队列。

4. 建议参照的拆分架构

当前核心图对象同时负责存储、索引、时态、撤回、决策、图分析和跨图链接。参照其数据契约时，建议拆为四层：

职责分配：应用服务保证原子写入；仓储只负责持久化；图查询服务负责遍历与投影；来源服务强制记录证据；审批服务隔离权限和状态机。

5. 抽象代码示例

下面是抽象示例（不是原项目原样代码），用于说明建议的数据契约和证据等级：

decision:
  id: decision-42
  scenario: approve-refund
  outcome: approved
  valid_time: [2026-08-22T09:00:00Z, null]
  recorded_at: 2026-08-22T09:00:03Z
  evidence_ids: [invoice-9, policy-v3]
relations:
  - type: explicit_causal
    target: decision-51
    asserted_by: reviewer-7
  - type: inferred_influence
    target: decision-55
    score: 0.68
    basis: shared_entities_and_time_order

该抽象保留 Semantica 的核心优点，同时把显式事实、启发式候选、有效时间、记录时间和证据引用分开。

6. 可借鉴的交互设计

1. 决策详情中固定展示场景、结果、推理、证据、政策、审批和先例，而不是只展示最终状态。
2. 图上对显式因果、推测影响和普通相关关系采用不同图例、线型与筛选器。
3. 节点撤回时先展示受影响决策和下游关系，再要求填写理由并二次确认。
4. 历史状态查看器把“当时有效”与“当时系统已知”分成两个时间轴入口。
5. 先例推荐必须显示相似依据和置信度，不能把候选自动标成已采纳先例。

7. 引入或参照结论

8. 源码依据

返回 Semantica 项目分析主报告