证据

每个分析操作都会把证据写入会话。证据让智能体不只说明发生了 什么变化，也能说明它如何得出该结论 —— 并让人工审阅者把任何结果追溯回产生它的输入。

证据是仅追加的，并持久化在会话的判断存储中（位于项目本地的 .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()

# 已确定的 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)

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

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 的 结论“可审计”而非仅仅“看起来合理”的原因。关于发出这些证据的操作，参见 分析流程。