• 人工智能
• AI Agent
• 多智能体
• Agent 工作流
• 深度研究
• AI 评测

本文是 PRAXIST 自主科研系统中「Run Reports（运行报告）」机制的完整技术指南。Run Reports 是从规范运行证据（canonical run evidence）派生出的人类可读视图（Markdown + PDF），用于向研究者与诊断 Agent 说明一次科研运行「进展到了哪里、最强变体是谁、运行是否健康」，而不会成为新的 result、frontier 或 baseline 的所有者。读完本文，你将掌握 PRAXIST 自动报告的三种触发时机、A/B/C 三段式报告结构、PDF 伴生图表规则、tool_server:run_report工具服务器的调用方式，以及报告与规范证据之间的只读边界。

一、什么是 Run Reports：从规范证据到派生视图

Run Reports 是 PRAXIST 中面向人而非面向机器的证据视图。其核心定位在原文档中定义得非常明确：报告是规范证据的派生视图（derived view），不是新的证据所有者。它解释「进展如何」，但不会成为另一个 result、frontier 或 baseline 的归属方。

文档给出的数据流如下图所示：

这条链路的含义是：报告永远「只读」规范证据并做摘要，规范证据不会因为报告的生成或刷新而发生任何变化。在源码层面，run_report.py 的文件头注释也明确写明了这一设计意图：

The report generator is intentionally deterministic and read-only over run facts. It summarizes frontier/Pareto outcomes, lineage hints, and health signals without changing promotion, frontier, PI, or guard behavior.

即：报告生成器对运行事实是确定性、只读的；它只汇总 frontier/Pareto 结果、血统线索和健康信号，不会改变 promotion、frontier、PI（Principal Investigator）或 guard 行为。

规范证据与派生视图的边界

理解 Run Reports 的前提是分清哪些是「规范事实（canonical truth）」、哪些是「派生视图」：

原文档明确强调：Reports never feed promotion or generation close decisions——报告从不参与 promotion 或 generation close 决策。这一点在 SKILL.md 中同样被反复强调：报告是 derived view，规范事实始终留在 frontier、findings、result summaries、Gems state 和 generation boundaries 中。

二、自动报告的三种触发条件

Praxist 会在以下任一条件满足时，自动向<task>/docs/praxist_reports/写入报告：

1. 首个可信 frontier 结果在同指标上击败已知 baseline（first credible frontier result beats a known baseline on the same metric）；
2. 已完成代数达到 3 的倍数（3、6、9 …）；
3. 运行进入终态（terminal state）。

这三种触发器在源码 run_report.py 的_due_trigger中逐一实现：

• final=True且尚未报告过终态 → 返回final_run_completion；
• 尚未报告过「首个可信 baseline 击败」且_has_baseline_beat判定成立 → 返回first_credible_baseline_beat；
• completed = generation_id + 1，当completed > 0且completed % 3 == 0，且该代尚未被记录 → 返回periodic_3_generation。

_has_baseline_beat的实现要点是：只有同时满足成熟度（mature enough）、无持久晋升排除（durable promotion exclusion）、无报告排除标记的 entry 才会参与 baseline 比较；比较时依据任务声明的指标方向（maximize/minimize）判断是否严格优于已知最优 baseline 值。例如minimize方向要求metric_value < min(baseline_values)，maximize方向要求metric_value > max(baseline_values)（见 run_report.py）。

触发状态的持久化

触发记录存放在<run_dir>/reports/human_report_state.json（源码常量REPORT_STATE_REL = Path("reports") / "human_report_state.json"）。每次报告生成后，maybe_generate_boundary_report会原子写入：

• generated_reports：已生成报告的路径、trigger、generation_id、创建时间；
• first_credible_baseline_beat_reported：标记首个 baseline 击败已报告；
• periodic_generations_reported：已报告的周期性代数列表；
• final_reported：终态已报告标记。

这套状态机保证了同一种触发在单次运行内不会重复产出——test_boundary_triggers_baseline_periodic_and_final_reports（test_run_report.py）验证了同一 generation 反复调用maybe_generate_boundary_report不会重复生成，并验证了三种触发分别对应first_credible_baseline_beat、periodic_3_generation、final_run_completion。

报告生成失败不阻塞运行

报告是「建议性（advisory）」产物。generate_boundary_report_safely与generate_terminal_report_safely都包裹了 try/except，任何异常只记录 warning 并返回None，绝不会中断研究循环。测试test_empty_report_and_safe_hook_failure_are_non_blocking（test_run_report.py）专门验证了这一点。

与任务身份（task identity）的隔离

原文档指出：报告子树被排除在任务身份之外（The generated subtree is excluded from task identity），因此报告刷新不会改变任务 manifest，也不会阻塞兼容的 resume。这保证了每次运行结束后即使报告反复刷新，任务的可恢复性不受影响。

在运行生命周期中的挂载点

报告钩子实际挂载在两条路径上：

• GenerationLoop 代际推进路径：generation_loop.py 在L687每代结束时调用generate_loop_boundary_report(self, generation_id=gen_id)，在L839最终代时以final=True调用；
• 终态兜底路径：startup.py 调用run_report.generate_terminal_report_safely(prepared, summary)，覆盖那些不经过 GenerationLoop 返回的终态路径（例如error、failed、interrupted、stopped等退出条件，且已完成代数大于 0 时才生成）。

三、报告结构：A / B / C 三段式

每一份报告都遵循相同的三段顺序（原文档「Report Structure」一节，亦是 run_report.pyrender_report_markdown的实际渲染顺序）：

A. Strongest variants or Pareto front（最强变体或帕累托前沿）

• 呈现任务声明的指标、可信度（credibility）与简洁的机制摘要（mechanism summaries）；
• 若尚无干净的 frontier 条目，来自较低权威证据（lower-authority evidence，如 validation candidate、shared finding、result summary）的维度获胜者，只能以明确标注的「信号（signal）」形式出现，不得当作干净的晋升事实。

渲染细节上，A 节按情况输出：

• ### Clean Frontier / Pareto Entries：按方向排序的干净 frontier 条目表格，列为 Rank / Variant / Gen / Lane / Metric / Value / Stage / Principle-Evidence；
• ### Unranked Frontier Entries (Direction Unknown)：指标方向未知、无法参与排名比较的 frontier 条目；
• ### Mature Dimension Winners：每个任务维度的成熟获胜者，含 Direction、Baseline Relation（beats baseline X/ties baseline X/worse than baseline X）、Promotion 状态与证据来源；
• ### Strong Signals Requiring Validation：需要验证的强信号——可见但不呈现为成熟证据，并附带阻断原因（blocker）。

测试test_report_separates_authorized_reduced_maturity_from_routing（test_run_report.py）验证了：同一指标上，promotion_eligible=true的条目进入Mature Dimension Winners，而validation_only=true的条目被降级为Strong Signals Requiring Validation。

B. Strong-variant lineage（强变体血统）

只跟踪 A 节中的强变体，沿其**父变体（parent）、代数（generations）、来源结果（source results）与继承思想（inherited ideas）**展开。渲染为Variant | Gen | Parent | Result Source | Parent Usage | Effective Config | Development Note表格，其中：

• parent_candidate/parent_variant/parent_lineage用于追溯父变体；
• source_result_path/result_artifact_path指向来源结果；
• parent_usage说明父变体被如何使用（如direct improvement、repair follow-up、complete_validation）；
• Effective Config 一栏会带上source_result_effective_config_sha256前 12 位摘要，便于核对复现配置。

若强变体未暴露结构化血统字段，报告会明确提示「未来任务应在 finding 的extra或 metrics 中发布parent_candidate、parent_usage与source_result_path」，而不是编造血统。

C. Run health（运行健康）

汇总工件一致性（artifact consistency）、运行摩擦（operational friction）、诊断覆盖度（diagnostic coverage）与caveats（注意事项）。_health_summary会输出：

• Status 与 exit condition（根据run_summary.json/orchestrator_status.json推断succeeded/failed/unknown，如exit_condition为completed/max_generations/plateau则视为 succeeded）；
• Generation progress（generations_completed/max_generations）；
• Structured findings visible 数量；
• 显式 warnings（来自 run_summary 与 orchestrator，最多各取前 5 条）；
• 保留待跟进（validation candidates retained for follow-up）的数量；
• 最新代际边界状态（gen_N/generation_boundary.json的 status）。

PDF 伴生报告与图表纪律

PDF 与 Markdown 使用相同的事实，并且只在任务声明了数值方向（numeric directions）时才添加图表。源码中_build_report_charts（run_report.py）按可信度选择图表标题（Best X by generation或Signal-only X observations by generation），支持的图表类型为：

• line：最受关注指标随代际的 best-value 趋势（_generation_best_series）；
• bar：各任务维度的单指标获胜者（最多 10 项）；
• scatter：风险/回报散点（要求同时存在 maximize 方向的 reward 类指标与 minimize 方向的 risk 类指标，且两点以上才绘制）。

原文档的关键纪律是：方向未知的指标只能作为上下文展示，不能用于选择获胜者、触发 baseline 声明或驱动方向性图表。测试test_unknown_direction_is_unranked_and_never_claims_improvement（test_run_report.py）验证了方向未知的指标不会进入dimension_winners、不会出现在任何图表中，也不会输出beats baseline字样。

PDF 由源码内置的_SimplePdf类（run_report.py）生成——这是一个零第三方依赖的迷你 PDF 写入器，直接输出 PDF 1.4 格式对象，绘制标题、项目符号、柱状图、折线图与散点图。若 PDF 渲染失败（例如缺少字体），Markdown 报告仍然生成成功，仅pdf_path返回None并记录 warning（见测试test_report_survives_pdf_failure_and_health_infers_terminal_status）。

四、手动生成：tool_server:run_report 工具服务器

插件注册信息

run_report是一个标准的 Praxist tool_server 插件，其元数据位于 plugin.yaml：

• name: run_report，kind: tool_server，version: 0.1.0，stability: experimental；
• 服务名server_name: run-report，暴露工具generate_run_report；
• 能力要求tool_server.run_report，可见范围panel；
• 入口entrypoint: adapter:create_tool_plugin；
• 证据契约evidence_schema: core:run_report.v1，凭据范围none（无需任何密钥）。

在 tool-servers.md 的工具服务器目录中，run_report的用途被描述为「Human-readable derived reports」，并且明确指出该专题文档（user-facing-reports-and-init.md）是run_report的契约所有者，涵盖自动/手动触发、结构、指标解释与规范状态边界。

工具签名与返回结构

tool_server:run_report在 Agent 会话内暴露generate_run_report。底层实现是 adapter.py 中的同名函数，参数如下：

返回的 JSON payload 字段：

• ok：是否成功；
• report_path：生成的 Markdown 报告绝对路径；
• pdf_path：PDF 伴生文件路径（失败时为None）；
• trigger、generation_id、report_kind。

当run_dir与task_dir都未提供且环境变量不可用时，返回ok: false与错误信息run_dir is required when PRAXIST_RUN_DIR or LOCAL_STORE_DIR is not set（见 adapter.py）。

MCP 接线方式

create_run_report_server（adapter.py）基于claude_agent_sdk的create_sdk_mcp_server与tool装饰器构造一个名为run-report的 SDK MCP server，将generate_run_report暴露为 MCP 工具；工具参数 schema 为run_dir、task_dir、trigger、generation_id四个字段，返回值以 JSON 文本形式放入{"content": [{"type": "text", "text": ...}]}。

stdio 入口在main.py：通过mcp.server.stdio.stdio_server运行同一 server 实例。测试test_codex_runtime_maps_run_report_server_directly（test_run_report.py）验证了 Codex SDK 运行时会以python -m <mcp_stdio_module>直接拉起run_report.adapter:create_run_report_server。

create_tool_plugin（adapter.py）返回注册器所需的插件描述符；测试同时断言tool_server:run_report同时出现在DEFAULT_RESEARCH_TOOL_SERVER_REFS与PANEL_TOOL_SERVER_REFS中（test_run_report.py）。

五、用 praxist-diagnostic 技能生成与诊断报告

praxist-diagnostic技能可以在一次显式的运行健康分析中生成同一份报告。其 SKILL.md 的「Human-Readable Run Reports」章节给出了完整的使用约定：

1. 内置报告面（built-in run-report surface）：当活跃任务声明了tool_server:run_report时，具备 panel/tool 能力的 Agent 可以直接调用generate_run_report生成所选运行的报告；
2. 目录解析纪律：先解析所选任务目录并传入task_dir，否则报告可能写到运行目录而不是任务的docs/praxist_reports/；
3. Codex CLI 外部调用：在运行中的 Agent 之外，从 Codex 侧可以导入源码模块直接调用：

from praxist.plugins.workflow_stages.research_loop.backend.run_report import ( generate_run_report, ) generate_run_report( run_dir=..., task_dir=<selected_task_dir>, trigger="manual_cli", )

技能还规定了 CLI 展示顺序：先打印简明摘要，再列出每个生成或复用报告的绝对路径。

诊断流程的可确定性前置收集，优先运行技能自带的清单脚本（run_diagnostic_inventory.py）：

python skills/praxist-diagnostic/scripts/run_diagnostic_inventory.py \ --task-path /path/to/task \ --run-dir /path/to/run \ --json

技能同时要求区分「当时 Agent 看到的」（prompt/agenda/leaderboard/evidence-pack 快照）与「运行现在知道的」（规范 result/frontier/Gems/boundary 状态），这正是 Run Reports 派生视图哲学在诊断场景的延伸：用审计快照重建历史视角，用规范状态判断当前晋升、Gems、证据转移与 resume 的真实性。

六、输出目录规则与文件命名

输出目录解析（_report_docs_root）

源码 run_report.py 的_report_docs_root逻辑为：

• 当task_dir提供，且运行目录等于任务目录或位于任务目录之内时 → 输出到<task_dir>/docs/praxist_reports；
• 否则 → 输出到<run_dir>/docs/praxist_reports。

测试test_report_uses_run_docs_when_run_dir_is_outside_task_dir（test_run_report.py）验证：当 run 目录在任务目录之外时，报告写入run_dir/docs/praxist_reports，且不会在任务目录下产生报告目录。

文件名格式

generate_run_report中生成的文件名为：

{YYYYmmdd_HHMMSS}_{run_name}_{trigger}{_genN}.md

例如20261012_005619_run_2026-10-11_first_credible_baseline_beat_gen3.md；PDF 伴生文件为同名.pdf。run_name取运行目录名的安全 slug（_safe_slug，只保留字母数字与_-.，最长 120 字符），_genN仅在generation_id非负时追加。

单事实面原则

生成代码注释明确：报告只在上述唯一目录写一份，不复制到其他地方（"A copy is not written elsewhere to avoid multiplying fact surfaces"）。这是为了避免同一派生事实出现多个拷贝导致事实面分裂。

七、证据采集与可信度判定（源码深潜）

collect_report_payload（run_report.py）展示了报告的事实来源全貌：

指标方向注册表（_task_metric_registry）

报告从任务规范中收集指标方向，来源包括：evaluation.primary_metric+evaluation.direction、evaluation.anchor_metrics、evaluation.frontier_lanes[].axes / optional_axes、baselines[].metric_name + direction。合法的方向值只有maximize与minimize（_VALID_METRIC_DIRECTIONS）。

gems.result_metric_aliases会构建别名图（连通分量），同一连通分量内的指标共享唯一方向；若分量内出现相互冲突的方向（如rmse声明minimize而别名validation_rmse声明maximize），则该分量整体方向视为未知并记录 warning——绝不信任过期的逐条结果元数据（见_metric_direction_for_name，run_report.py）。测试test_task_metric_registry_rejects_conflicted_task_direction与test_task_metric_registry_drives_minimize_winners_charts_and_aliases分别验证了冲突拒绝与别名驱动的获胜者/图表行为。

credible 与 signal 的划分（_report_evidence_class）

每条 entry 被分为「credible（可信）」或「signal（信号）」两类，任一条件命中即为 signal：

• 成熟度快照mature_enough is False；
• 带报告排除标记（suspect、suspect_protocol、protocol_integrity_failed任一为 true）；
• 存在持久晋升排除（durable_promotion_exclusion非空）；
• 带运行失败状态（result_status/final_status/tier_status/status/eval_status命中坏状态，如failed、protocol_integrity_failed等）；
• 来源为result_summary/shared_finding/validation_candidate且未达到 mature。

只有 credible 条目才能进入排名、触发 baseline 声明或驱动方向性图表；signal 条目只能出现在「Strong Signals Requiring Validation」等明确标注的位置，并附带block_reason（如not_scored_complete、validation required、路由排除原因等）。

去重（_dedupe_entries）

报告对来自不同视图（result summary、shared finding、validation candidate、frontier）的同一变体做去重：优先按不可变结果工件 key（result_artifact_key+source_result_sha256）判定同一工件；同一工件存在时，带持久排除的版本会覆盖干净版本（避免一条受限事实被干净视图掩盖）。测试test_result_summary_wins_dedupe_over_matching_validation_view与test_report_dedupe_applies_routing_to_same_artifact_across_display_fields覆盖了这两种场景。

八、写报告时容易被忽略的边界与最佳实践

结合文档、源码与测试，实践中需要注意以下要点：

1. 始终传task_dir：Agent 手动调用generate_run_report时先解析任务目录再传参，否则报告落入 run 目录，后续检索<task>/docs/praxist_reports/会落空（SKILL.md 明确强调）。
2. 不要手工编辑报告来改变运行事实：每份报告结尾都有 Report Semantics 声明——"This Markdown report is a derived human-readable view. Canonical facts remain in frontier, findings, result summaries, Gems state, and generation boundary artifacts. Do not hand-edit this report to change run truth."
3. 不要用报告驱动决策链路：promotion 与 generation close 只能读取规范证据；报告内的任何「获胜者」「信号」都只是给研究者看的摘要。
4. 方向未知的指标可以展示，但不能比较：报告会把它放进Unranked Frontier Entries (Direction Unknown)并在图表与 baseline 声明中排除。
5. PDF 失败不必恐慌：Markdown 报告仍会生成，pdf_path为None即可；这属于设计内的降级路径。
6. 任务指标声明是报告正确性的前提：primary_metric、direction、anchor_metrics、frontier_lanes、baselines、gems.result_metric_aliases共同决定了方向解析与排名质量；声明缺失或冲突时，报告宁可标记 unknown 也不臆断。

九、如何继续深入（仓库导航）

• 报告生成核心实现：run_report.py（2417 行，含触发、采集、渲染、PDF 写入全套逻辑）；
• 工具服务器插件与 MCP 接线：adapter.py、plugin.yaml、main.py；
• 诊断技能使用约定：skills/praxist-diagnostic/SKILL.md（「Human-Readable Run Reports」章节）与清单脚本 run_diagnostic_inventory.py；
• 报告行为契约测试：tests/unit/test_run_report.py（覆盖触发、结构、PDF 降级、去重、方向解析、signal/credible 划分、Codex MCP 映射等 30 余个场景）；
• 工具服务器全景：docs/guides/tool-servers.md；
• 运行循环中的报告钩子：generation_loop.py 与 startup.py。

十、小结

Run Reports 是 PRAXIST「证据所有者」与「证据读者」解耦设计的缩影：规范证据（result/finding 摘要、frontier manifest、Gems 状态、代际边界）拥有全部事实并驱动晋升决策；Markdown + PDF 报告则负责把同一份事实翻译成研究者与诊断 Agent 可读的 A/B/C 摘要与图表。无论是自动触发（首个可信 baseline 击败、每 3 代、终态），还是通过tool_server:run_report/praxist-diagnostic手动生成，报告的边界纪律始终如一——只读、派生、确定性、永不回喂决策。掌握这套体系，你就能在任何 PRAXIST 运行中快速回答「进展如何、最强变体是谁、运行是否健康」，而不会污染运行本身的科学决策。

• 人工智能
• AI Agent
• 多智能体
• Agent 工作流
• 深度研究
• AI 评测