第 6 章 · 01 ContextGraph 与 record_decision ★

第 6 章 · 01 ContextGraph 与 record_decision ★

本节摘要：全书压轴段。context 模块（15 个文件、19124 行，全书最大模块）的核心是 4260 行的 context_graph.py——一张把决策、原因、结果、证据当作一等图节点的统一上下文图。本节精读旗舰入口 record_decision()（第 3174 行起）：一次调用如何把 AI 决策的类别/场景/理由/结论/置信度/决策者/双时态有效期，经严格校验后落成决策节点，并自动织出 involves（关联实体）、belongs_to（归类）、made_by（决策者）三种边；再读高层容器 AgentContext 如何把记忆、检索、决策五件套组装起来；最后用官方决策智能指南的 What/Why/When 三问收束——为什么决策必须是图节点，而不是一行日志。

内容来源：semantica/context/context_graph.py（4260 行，第 1—106 行模块文档、3174—3851 行决策记录链路）、agent_context.py（2546 行）、docs/guides/decision-intelligence.md、README.md（Decision Intelligence）

⚠️ 注意：context 模块里有两套决策记录 API：ContextGraph.record_decision()（轻量、参数直传、本节主角）与 DecisionRecorder.record_decision(Decision, entities, source_documents)（重型、吃 Decision 数据类、可挂向量嵌入与 PROV-O 溯源）。AgentContext 按 knowledge_graph 是否支持 Cypher 自动选择后端，混用两套时注意对象形态不同。

学习目标

1. 理解 ContextGraph 的定位：决策/实体/类别/决策者共图的统一上下文图。
2. 掌握 record_decision() 的完整参数面与逐字段输入校验。
3. 读懂 _add_decision_to_graph：一次决策记录自动织出哪些节点与边。
4. 理解决策入图的三重理由：与事实关联、可查询、可追溯。
5. 掌握 AgentContext 的组装图：AgentMemory/ContextRetriever/决策五件套如何挂载。

一、旗舰模块导读：1.9 万行的 context

先看全景。context 模块 15 个文件的分工：

context_graph.py     4260 行  统一上下文图（本节主角）
context_retriever.py 2801 行  上下文检索（RAG/GraphRAG 混合）
agent_context.py     2546 行  Agent 高层容器（本节第五节）
agent_memory.py      2302 行  Agent 记忆（6.2 节）
entity_linker.py      898 行  实体链接
policy_engine.py     1043 行  策略门禁（6.3 节）
decision_query.py    1300 行  决策查询
decision_recorder.py  618 行  重型决策记录器
decision_methods.py   924 行  决策方法混入
causal_analyzer.py    779 行  因果链分析（6.2 节）
decision_context.py   479 行 / decision_models.py 398 行 / graph_schema.py 526 行 / ...
​

ContextGraph 的类文档（第 1—106 行）把野心写得很直白：它不只是图存储，而是"Comprehensive Decision Management"——决策记录、先例搜索、影响面分析、因果追踪、策略合规、高级分析六位一体，同时挂接 KG 算法（中心性/社区/Node2Vec 嵌入）与向量库（混合搜索）。README 对它的定义更锋利：

In Semantica, a decision is not a log line. It is a first-class graph node with a full lifecycle.

决策不是日志行，而是一等图节点——这句话就是本模块的存在理由。

二、record_decision：七要素 + 双时态

record_decision（第 3174—3321 行）的签名给出了决策的"法定记载事项"：

def record_decision(
    self,
    category: str,          # 决策类别，如 "loan_approval"
    scenario: str,          # 决策场景描述
    reasoning: str,         # 决策理由（给监管看的那段话）
    outcome: str,           # 决策结论，如 "approved"
    confidence: float,      # 置信度 0.0–1.0
    entities: Optional[List[str]] = None,        # 关联实体
    decision_maker: Optional[str] = None,        # 决策者身份
    metadata: Optional[Dict[str, Any]] = None,
    valid_from: Optional[Union[str, int, float, datetime]] = None,  # 双时态
    valid_until: Optional[Union[str, int, float, datetime]] = None,
    **kwargs,
) -> str:                   # 返回决策 ID
​

这七个必填/常填字段恰好对应监管审计的每一问：什么类别的决策（category）、面对什么情况（scenario）、依据什么（reasoning）、结论是什么（outcome）、多大把握（confidence）、谁拍的板（decision_maker）、关联哪些事实（entities）。valid_from/valid_until 让决策本身带双时态有效期（第 7 章展开）。

接着是全书最严格的输入校验段（第 3208—3267 行，约 60 行）：category 非空且 ≤100 字符；scenario ≤5000；reasoning ≤10000；outcome ≤1000；confidence 必须是数字且在 [0,1]；entities 每项非空字符串 ≤200；metadata 键 ≤100、值序列化后 ≤1000……决策记录是审计证据，所以入库前的每一字节都有度量衡——超限直接 ValueError，绝不静默截断。校验之后生成身份与时间（第 3269—3270 行）：

decision_id = str(uuid.uuid4())
timestamp = datetime.now().timestamp()
​

决策字典（第 3284—3299 行）同时记两枚时间戳：timestamp（业务时间）与 recorded_at（UTC 记录时间）——决策智能已经默认双时态思维。最后落三个索引（第 3311—3318 行）：_decisions 主存储、_decision_index 按类别倒排、_entity_index 按实体倒排、_temporal_index 按时间倒序——先例搜索与因果追踪在数据结构层就已铺好路。

三、_add_decision_to_graph：一次记录，四类节点

决策不是孤立对象。_add_decision_to_graph（第 3747—3851 行）把决策织进图里：

# Add decision node
self.add_node(
    decision["id"], "decision",
    content=decision["scenario"],
    valid_from=decision.get("valid_from"),
    valid_until=decision.get("valid_until"),
    category=decision["category"],
    outcome=decision["outcome"],
    confidence=decision["confidence"],
    timestamp=decision["timestamp"],
    scenario=decision["scenario"],
    decision_maker=decision.get("decision_maker", ""),
    reasoning=decision["reasoning"],
    **safe_metadata, **extra_properties,
)

# Add entity nodes and relationships
for entity in decision["entities"]:
    if not self.find_node(entity):
        self.add_node(entity, "entity", name=entity)
    self.add_edge(decision["id"], entity, "involves",
                  confidence=decision["confidence"])

# Add category node and relationship
category_id = f"category_{decision['category']}"
...
self.add_edge(decision["id"], category_id, "belongs_to")

# Add decision maker node if provided
maker_id = f"maker_{decision['decision_maker']}"
...
self.add_edge(decision["id"], maker_id, "made_by")
​

一次 record_decision 最多织出四种节点、三种边：决策节点（node_type "decision"，scenario 作为 content）经 involves 边连向实体节点、经 belongs_to 连向类别节点、经 made_by 连向决策者节点。这一步是"决策入图"的实质——决策与第 3 章知识图谱里的实体共享同一个图空间：find_neighbors 从决策出发两跳就能摸到业务事实，反过来从实体出发也能 enumerate 它参与过的所有决策。细节上还有两处防御：protected_properties（第 3750 行）防止 metadata 里的同名键覆盖 category/reasoning 等法定字段；整个方法包在 try/except 里，织图失败会留下日志但不中断决策主存储。

四、为什么决策要入图

把动机说透，一共三条，对应官方指南 decision-intelligence.md 开篇的叙事：

第一，与事实关联。 决策引用的证据（客户实体、交易实体、风险实体）就是图里的节点，involves 边把"决策依据了什么"固化成拓扑。指南对此有一句精辟的分类："Agent Memory stores external knowledge...Decision Intelligence stores internal decisions"——外部知识由记忆层管，内部决策由决策层管，而两者在同一张图上相遇。

第二，可查询。 决策成了节点，第 3 章的所有图查询原样可用：find_nodes(node_type="decision") 找决策，类别/实体/时间三个倒排索引加速过滤，get_decision_insights()（第 3491 行）一键产出总数、置信度均值/极值、按类别与结论的分布统计。指南的 shift 交接报告示例（47 个决策、mean confidence 0.87）就是从这些索引里聚合出来的。

第三，可追溯。 决策节点是第 6.2 节因果链的端点：add_causal_relationship(a, b, "CAUSED") 把决策串成因果链，trace_decision_causality 顺链回放"什么证据导致什么决策导致什么结果"；若再接 DecisionRecorder 的 PROV-O 通道（第 587 行 _track_decision_provenance），决策本身还会在溯源账本里登记为 Entity+Activity。README 列出的决策生命周期一图流正是这条链的官方口径：

record_decision()         → 存为带完整上下文的图节点
add_causal_relationship() → 链接上游原因与下游影响
find_similar_decisions()  → 全历史先例语义搜索
trace_decision_chain()    → 回溯到根因的完整因果谱系
analyze_decision_impact() → 下游影响地图
check_decision_rules()    → 策略合规闸门
export / audit trail      → W3C PROV-O / CSV / JSON 提交监管
​

五、AgentContext：把一切装进一个容器

AgentContext（agent_context.py 第 90 行起，2546 行）是决策智能的总装车间。构造函数（第 124—292 行）里可见的装配线：

def __init__(self, vector_store, knowledge_graph=None, retention_days=30,
             max_memories=10000, graph_expansion=True, max_expansion_hops=2,
             hybrid_alpha=0.5, decision_tracking=False, ...):
    ...
    self._memory = AgentMemory(**memory_config)          # ① 记忆层
    if knowledge_graph:
        self._retriever = ContextRetriever(**retriever_config)   # ② 检索层
    ...
    if decision_tracking and knowledge_graph:
        self._decision_recorder = DecisionRecorder(knowledge_graph)  # ③
        self._decision_query = DecisionQuery(...)                    # ④
        self._causal_analyzer = CausalChainAnalyzer(knowledge_graph) # ⑤
        self._policy_engine = PolicyEngine(knowledge_graph)          # ⑥
​

三条装配规则值得记：其一，vector_store 是唯一必填项（第 162 行，缺失直接 ValueError——指南 Info 框专门解释了这个 TypeError/ValueError 的分工）；其二，decision_tracking 打开时按图后端能力分两条路——支持 execute_query（Neo4j/FalkorDB 等）走 Cypher 后端，否则走 ContextGraph 内存后端（第 229—257 行），五件套在两种后端上都有实现；其三，向量库可选挂接 initialize_decision_pipeline，把 Node2Vec 等图特征喂给先例搜索。

装好之后，Agent 的一切动作都有了统一门面：store/retrieve/forget/conversation 管记忆与上下文（记忆细节见 6.2 节），record_decision/find_precedents/get_causal_chain/trace_decision_explainability/get_policy_engine 管决策。一个 Agent 从"会聊天"到"敢签字"，差的正是这组方法。

六、What / Why / When：指南三问

官方指南 decision-intelligence.md 用三段回答了三个根本问题，值得原样消化：

• What：把 Agent 自己的决策（分类、审批、行动）作为可查询、可分析、可复用的结构化数据持久化——决策不再是执行完就蒸发的中间产物，而是带元数据、推理链、因果关系的持久图节点。
• Why：四条理由——可审计的 AI 行为（生产系统每笔决策都有理由、置信度、时间戳）、可解释性（利益相关者问"为什么做 X"时能回放决策链）、先例复用（新决策前搜历史同类保持一致性）、治理合规（策略门禁+全量策略应用记录）。
• When：五个"该用"（自主决策型 Agent、需审计留痕的决策流、金融/医疗/国防等合规行业、多级审批、风险敏感环境）对四个"不该用"（无状态聊天机器人、纯 RAG 检索、只读应用、从不需要审计的不可动人应用）。指南还专门警告两条反模式：记录决策却不连因果边（孤立节点价值减半），以及把先例相似度当证明（高分只说明相关，不说明相同）。

💡 装配要点：本阶是压轴段的地基。心智模型：record_decision = 严格校验（每字段有度量衡）→ uuid4 + 双时间戳 → 四索引落位（主存储/类别/实体/时间）→ 织图（decision 节点 + involves/belongs_to/made_by 三种边）。决策与知识图谱共图，是"可查询"与"可追溯"的前提。AgentContext 是总装容器：vector_store 必填、knowledge_graph 解锁 GraphRAG 与决策五件套、decision_tracking 是决策功能的总开关。轻量 API（ContextGraph）做原型，重型 API（DecisionRecorder+Decision 数据类）接生产，两者经 AgentContext 自动适配。

本节要点回顾

• context 模块 15 文件 19124 行；context_graph.py 4260 行，六位一体：决策记录/先例搜索/影响面分析/因果追踪/策略合规/高级分析。
• record_decision 七要素：category/scenario/reasoning/outcome/confidence/entities/decision_maker，外加 valid_from/valid_until 双时态；约 60 行逐字段校验（category≤100、scenario≤5000、reasoning≤10000、confidence∈[0,1]…），超限即 ValueError。
• 决策字典记双时间戳（timestamp 业务时间 + recorded_at UTC）；落四个索引（主存储+类别+实体+时间倒排）。
• _add_decision_to_graph 自动织图：decision 节点 + involves（实体，带置信度）+ belongs_to（类别节点）+ made_by（决策者节点）；protected_properties 防法定字段被 metadata 覆盖。
• 决策入图三重理由：与事实关联（involves 连图谱实体）、可查询（三索引 + get_decision_insights）、可追溯（因果链 + PROV-O）。
• AgentContext 装配线：memory + retriever + 决策五件套（Recorder/Query/CausalAnalyzer/PolicyEngine），按后端能力自动选 Cypher 或内存路径；vector_store 唯一必填。

下一节：02 因果链追踪与先例语义搜索 ★——trace_decision_causality 的显式边+启发式双通道、置信度衰减与距离带，先例混合检索（0.7 语义 + 0.3 结构），影响面分析与 AgentMemory 的分层设计。