证据链

每个分析操作都会把证据写入会话。这些证据让智能体不只说明发生了什么， 也能说明它如何得出结论；人工审阅者可以沿着这条链追溯到产生结果的输入。

这些记录是仅追加的，并持久化在会话的判断存储中（位于项目本地的 .marivo/）。因此，会话结束后，结论仍然可审计、可重放。

三个层次

证据链分三个层次记录，从原始观察到带版本的判断：

层次	它是什么	关键字段
证据项	从单个产物中提取的原子、类型化观察（例如“West 区域 revenue 环比下降 12%”）。	finding_type、artifact_id、subject、observed_window、quality_status
命题	由系统播种、关于某个主体的论断，从证据项派生（例如“Q4 的 revenue 发生了变化”）。	proposition_type、subject_key、seed_finding_refs
评估	对某个命题的、带版本的判断：它的状态与置信度。	status、confidence、confidence_basis、supersedes_id、is_latest

证据项与命题是不可变的。重新运行操作不会原地修改判断，而是写入一条 新的 评估来取代上一条（supersedes_id），并把最新的一条标记为 is_latest。 完整的判断历史会被保留下来。

读取会话已知的事实

session.knowledge() 返回一个不可变的 SessionKnowledge 快照。这是智能体用来决定下一步的 读取视图，承载观察摘要、已确定的事实 与未决的打开项：

knowledge = session.knowledge()

# 观察到了什么：每次 observe / derive_metric_frame commit 对应一条有界 digest。
for obs in knowledge.observations():
    print(obs.subject.metric, obs.semantic_kind, obs.analysis_purpose, obs.digest)

# 已确定的 facts：带有当前 assessment 的 propositions。
for fact in knowledge.facts(kind="driver"):
    print(fact.dimension, fact.contribution_share, fact.status)

# Open items：等待跟进的未决 anomalies 与 questions。
for item in knowledge.open_items(kind="anomaly"):
    print(item.subject, item.confidence)

# 建议的下一步 operators，已排序。
for action in knowledge.next_steps(top=3):
    print(action)

observations() 按 commit 顺序返回有界摘要：按形状分派的取值摘要（标量的值； 时间序列的首末/极值/方向；segmented 按绝对值排序的 top segments），外加窗口、行数和 analysis_purpose。合计与占比属于组合语义，仅对可加（可加）指标填充； 非可加指标（比率、分位数、采样折叠等）保留逐段取值但不给出合计/占比， 非可加的面板也不做跨桶的分段排名。观察是 ground 事实而不是待检验主张， 因此不携带状态或 confidence。

事实分为五种，每种由一个操作产生：

Fact 种类	由谁产生	携带
change	compare	方向、幅度、对比窗口
driver	attribute	维度、贡献占比、贡献角色
tested_hypothesis	hypothesis_test	方法、alpha、p 值、是否拒绝原假设
forecast	forecast	预测窗口、horizon、预测区间
association	correlate	相关系数、滞后期、连接依据

SessionKnowledge 还提供 open_items(kind="question")、blocked_followups()（在某个问题 解决前无法运行的后续项），以及 for_subject(subject) 将整个快照过滤到单个主体。 evidence_completeness 报告底层证据是 complete、partial 还是 unavailable。

审计一个结论

要获取原始记录与完整审计链，使用 session.evidence 命名空间：

方法	返回
session.evidence.findings(...)	证据项，可按 artifact_id、finding_type、subject 过滤。
session.evidence.propositions(...)	命题，可按 proposition_type、subject、status 过滤。
session.evidence.assessments(...)	评估，默认仅返回最新的。
session.evidence.proposition(id)	按 id 取单个命题。
session.evidence.latest_assessment(id)	当前评估；若从未评估则返回 None。
session.evidence.trace(id)	某个命题的完整 EvidenceTrace。

trace(id) 是审计入口：EvidenceTrace 会把命题连接到它的 latest_assessment、 seed_findings、判断背后的 support_findings 与 oppose_findings，以及产生它的 source_artifacts 与 source_steps。

props = list(session.evidence.propositions(proposition_type="change"))
trace = session.evidence.trace(props[0].proposition_id)

print(trace.proposition.subject_key, "→", trace.latest_assessment.status)
for finding in trace.seed_findings:
    print(finding.finding_type, "from", finding.artifact_id)

人工审阅者可以沿着这条链，从一个结论回溯到支持它的具体观察与分析步骤。这也是 Marivo 结论 “可审计”而不只是“看起来合理”的原因。关于写入这些证据的操作，参见 分析流程。