PRAXIST Run Reports 实战指南：面向研究者与诊断 Agent 的可读性运行报告体系

人工智能AI Agent多智能体Agent 工作流深度研究AI 评测【免费下载链接】PRAXISTAutonomous research system for measurable, computer-executable research.项目地址https://gitcode.com/gh_mirrors/pr/PRAXIST点击查看免费下载本文是 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、PIPrincipal Investigator或 guard 行为。规范证据与派生视图的边界理解 Run Reports 的前提是分清哪些是「规范事实canonical truth」、哪些是「派生视图」类别位置角色规范事实result 与 finding 摘要、frontier/frontier_manifest.json、已提交的gems/gems_state.json、gen_N/generation_boundary.json晋升promotion与代际关闭generation close决策的唯一依据派生视图task/docs/praxist_reports/下的 Markdown/PDF 报告人类可读摘要永不回喂决策原文档明确强调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/写入报告首个可信 frontier 结果在同指标上击败已知 baselinefirst credible frontier result beats a known baseline on the same metric已完成代数达到 3 的倍数3、6、9 …运行进入终态terminal state。这三种触发器在源码 run_report.py 的_due_trigger中逐一实现finalTrue且尚未报告过终态 → 返回final_run_completion尚未报告过「首个可信 baseline 击败」且_has_baseline_beat判定成立 → 返回first_credible_baseline_beatcompleted 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_reportstest_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_blockingtest_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_idgen_id)在L839最终代时以finalTrue调用终态兜底路径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 Relationbeats baseline X/ties baseline X/worse than baseline X、Promotion 状态与证据来源### Strong Signals Requiring Validation需要验证的强信号——可见但不呈现为成熟证据并附带阻断原因blocker。测试test_report_separates_authorized_reduced_maturity_from_routingtest_run_report.py验证了同一指标上promotion_eligibletrue的条目进入Mature Dimension Winners而validation_onlytrue的条目被降级为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_validationEffective 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则视为 succeededGeneration progressgenerations_completed/max_generationsStructured 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_chartsrun_report.py按可信度选择图表标题Best X by generation或Signal-only X observations by generation支持的图表类型为line最受关注指标随代际的 best-value 趋势_generation_best_seriesbar各任务维度的单指标获胜者最多 10 项scatter风险/回报散点要求同时存在 maximize 方向的 reward 类指标与 minimize 方向的 risk 类指标且两点以上才绘制。原文档的关键纪律是方向未知的指标只能作为上下文展示不能用于选择获胜者、触发 baseline 声明或驱动方向性图表。测试test_unknown_direction_is_unranked_and_never_claims_improvementtest_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.yamlname: run_reportkind: tool_serverversion: 0.1.0stability: 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 中的同名函数参数如下参数类型默认值说明run_dirstr \| NoneNone运行目录未提供时使用active_run_dir()基于PRAXIST_RUN_DIR或LOCAL_STORE_DIR环境变量task_dirstr \| NoneNone任务目录务必解析并传入否则报告会写到运行目录而非任务的docs/praxist_reports/triggerstrmanual_tool_call触发来源标识会写入报告文件与内容generation_idint \| NoneNone代际上下文会体现在文件名_genN后缀与报告内容中返回的 JSON payload 字段ok是否成功report_path生成的 Markdown 报告绝对路径pdf_pathPDF 伴生文件路径失败时为Nonetrigger、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_serveradapter.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_directlytest_run_report.py验证了 Codex SDK 运行时会以python -m mcp_stdio_module直接拉起run_report.adapter:create_run_report_server。create_tool_pluginadapter.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」章节给出了完整的使用约定内置报告面built-in run-report surface当活跃任务声明了tool_server:run_report时具备 panel/tool 能力的 Agent 可以直接调用generate_run_report生成所选运行的报告目录解析纪律先解析所选任务目录并传入task_dir否则报告可能写到运行目录而不是任务的docs/praxist_reports/Codex CLI 外部调用在运行中的 Agent 之外从 Codex 侧可以导入源码模块直接调用from praxist.plugins.workflow_stages.research_loop.backend.run_report import ( generate_run_report, ) generate_run_report( run_dir..., task_dirselected_task_dir, triggermanual_cli, )技能还规定了 CLI 展示顺序先打印简明摘要再列出每个生成或复用报告的绝对路径。诊断流程的可确定性前置收集优先运行技能自带的清单脚本run_diagnostic_inventory.pypython 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_dirtest_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.mdPDF 伴生文件为同名.pdf。run_name取运行目录名的安全 slug_safe_slug只保留字母数字与_-.最长 120 字符_genN仅在generation_id非负时追加。单事实面原则生成代码注释明确报告只在上述唯一目录写一份不复制到其他地方A copy is not written elsewhere to avoid multiplying fact surfaces。这是为了避免同一派生事实出现多个拷贝导致事实面分裂。七、证据采集与可信度判定源码深潜collect_report_payloadrun_report.py展示了报告的事实来源全貌数据源读取位置用途frontier manifestfrontier/frontier_manifest.jsonfrontier 条目、validation candidatesrun summaryrun_summary.json运行状态与健康orchestrator statusorchestrator_status.json经read_effective_orchestrator_status代际进度、退出条件Gems 状态gems/gems_state.json证据上下文代际边界gen_*/generation_boundary.jsonglob 遍历最新边界状态共享发现shared_findings/*.json最多 300 条信号来源结果摘要results/**/递归发现的summary.json、evaluation_summary.json、eval_summary.json、tiered_eval_summary.json、custom_*_tiered_eval_summary.json、兼容名result_summary.json最多 700 条结果信号基线task/assets/baselines/*.jsonlbaseline 比较任务指标注册表task.yaml/task_spec.yaml的evaluation、baselines、gems.result_metric_aliases指标方向与别名解析指标方向注册表_task_metric_registry报告从任务规范中收集指标方向来源包括evaluation.primary_metricevaluation.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_namerun_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的同一变体做去重优先按不可变结果工件 keyresult_artifact_keysource_result_sha256判定同一工件同一工件存在时带持久排除的版本会覆盖干净版本避免一条受限事实被干净视图掩盖。测试test_result_summary_wins_dedupe_over_matching_validation_view与test_report_dedupe_applies_routing_to_same_artifact_across_display_fields覆盖了这两种场景。八、写报告时容易被忽略的边界与最佳实践结合文档、源码与测试实践中需要注意以下要点始终传task_dirAgent 手动调用generate_run_report时先解析任务目录再传参否则报告落入 run 目录后续检索task/docs/praxist_reports/会落空SKILL.md 明确强调。不要手工编辑报告来改变运行事实每份报告结尾都有 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.不要用报告驱动决策链路promotion 与 generation close 只能读取规范证据报告内的任何「获胜者」「信号」都只是给研究者看的摘要。方向未知的指标可以展示但不能比较报告会把它放进Unranked Frontier Entries (Direction Unknown)并在图表与 baseline 声明中排除。PDF 失败不必恐慌Markdown 报告仍会生成pdf_path为None即可这属于设计内的降级路径。任务指标声明是报告正确性的前提primary_metric、direction、anchor_metrics、frontier_lanes、baselines、gems.result_metric_aliases共同决定了方向解析与排名质量声明缺失或冲突时报告宁可标记 unknown 也不臆断。九、如何继续深入仓库导航报告生成核心实现run_report.py2417 行含触发、采集、渲染、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 评测【免费下载链接】PRAXISTAutonomous research system for measurable, computer-executable research.项目地址https://gitcode.com/gh_mirrors/pr/PRAXIST点击查看免费下载相关推荐SenseNova-Skills 深度研究 CLI 实战指南独立安装、Harness 编排与可恢复研究报告运行SenseNova Skills 深度研究 CLI 实战指南独立安装、Harness 编排与可恢复研究报告运行 本文围绕 SenseNova Skills 仓AI 技能人工智能深度研究数据分析媒体生成Praxist 入门指南把可运行研究项目变成多代自主研究循环Praxist 入门指南把可运行研究项目变成多代自主研究循环 Praxist 是一个面向可度量、可在计算机上执行研究问题的自主研究系统它把研究当作一个持人工智能AI Agent多智能体Agent 工作流深度研究AI 评测Label Studio Enterprise Support Reports 实战指南匿名化运维诊断报告的原理、生成与安全共享Label Studio Enterprise Support Reports 实战指南匿名化运维诊断报告的原理、生成与安全共享 Support Report数据标注人工智能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考