agent-viz

将人类与AI智能体之间的沟通，从聊天扩展为可视化（图表・树形图・热力图・流程图）的持续资产。在 Kaggle / AtCoder Heuristic / 交易模型开发中共用。

构成方针（基于2026-08-24调查）

• 记录的骨架 = MLflow（本地 file store）。智能体写入，人类通过 mlflow ui 查看

• 自定义图表 = 自包含HTML（Plotly）。在 MLflow 的工件视图中内联渲染

• 自行维护的只有「通用试验台账模式」「报告部件」「领域适配器」这一薄层

调查正本: KnowledgeBase 00_Inbox/人类与AI智能体的可视化沟通工具 调查备忘录

Related MCP server: Querytree MCP Server

Phase 0（已实现）

• agentviz.schema — 通用试验台账模式。1次试验 = TrialRecord，案例 = seed / fold / 期间

• agentviz.ledger — TrialLedger。向 MLflow 的 log_trial / fetch_trials

• agentviz.report — build_report。试验台账表格＋指标变化趋势＋按案例×按试验的相对得分热力图的 自包含HTML

使用方法

# セットアップ
.venv\Scripts\python.exe -m pip install -e .[dev]

# テスト
.venv\Scripts\python.exe -m pytest

# デモ（合成AHCデータで台帳→レポート→MLflow記録）
.venv\Scripts\python.exe demo\generate_demo.py

# UI（共有ストアを表示）
.venv\Scripts\python.exe -m mlflow ui --backend-store-uri "<store path>"

默认存储为 %AGENTVIZ_STORE%，未设置时使用 ~\dev\Projects\agent-viz\store。

Phase 1（已实现）

• agentviz.adapters.ahc — 自研AHC运行器实测格式的导入。from_results_json（results/*.json）和 from_experiments_jsonl（1行=1次实验。损坏的行作为错误返回并继续，metrics为空的行从per-seed结果重新计算以救济，其他设备的绝对路径通过 results_dir 进行文件名解析）

• agentviz.adapters.kaggle — from_cv(fold_scores, lb_score=...)。案例=fold，LB 作为 lb_score 指标。 针对指标定义为各标签得分平均值的竞赛（如 macro AUC / macro F1）， 提供 from_per_label(label_scores, label_meta=..., metric_name="macro_auc")（案例=标签）。 不将主指标称为 cv_mean，是为了避免混淆 fold 间的波动（测量噪声）与标签间的落差（实力差异）。 能改变的是后者。label_meta 会进入案例的 meta 中， 可作为按教师信号浓度或阳性数进行分层的材料

• agentviz.adapters.trade — from_walkforward(windows, ...)。案例=前向验证窗口。OOS 作为 oos_score 指标，tier sheet HTML 通过 log_trial(artifact_paths=...) 附加

• agentviz.report — 新增泛化差距散点图（拥有 lb_score / oos_score 的试验达到2个以上时自动显示。将 CV vs LB＝IS vs OOS 视为同构处理）

• agentviz.replay — build_replay(frames, infos, events)。将 ahc069 自研回放骨架（进度条・播放・逐帧・←→键・事件点击跳转）泛化为领域无关的自包含HTML

已用实际数据确认: 从 AtCoder\ahc\ahc069\experiments.jsonl（1191行）导入1133次试验，在1130次试验中完成per-seed案例解析（examples/ingest_ahc069.py）。

Phase 2（已实现）— 双向化

• agentviz.feedback — 分层反馈的正本存储（仅追加JSONL、store/feedback.jsonl）。add / list / resolve

• agentviz.panel — Gradio面板兼MCP服务器。人类查看试验台账・热力图后投递分层指摘（目标试验・目标案例・指示・优先级），智能体通过MCP工具读取并处理，用 resolve_feedback 关闭

# パネル起動（http://127.0.0.1:7861、ポートは AGENTVIZ_PANEL_PORT で変更）
.venv\Scripts\python.exe -m agentviz.panel

# Claude Code への登録（パネル起動中に）
claude mcp add --transport http agentviz http://127.0.0.1:7861/gradio_api/mcp/

不使用MCP时，也可以通过 gradio_client 或 agentviz.feedback.FeedbackStore 直接读写。 在UI下拉选择无法生效的环境中，「重新加载」按钮是可靠的备用方案。

Phase 3（已实现）— 决策点

feedback 处理的是「这层弱，去修」这种指摘→应对的单次往返， 而 decisions 处理的是「在决定采用哪个之前无法继续推进」的论点。由于形态不同，所以分开存放。

• agentviz.decisions — 决策点的存储（仅追加JSONL、store/decisions.jsonl）。propose / decide / supersede

• 选项带有 measured 标志。如果无法将未测量的选项与已测量的选项并列显示，就会把「已测范围内的最佳」误读为「最佳」

• 通过 blocks 持有决策间的依赖。ready() 只返回依赖项已了结的决策

• 每个选项通过 evidence_trials 指向台账中的试验

正本分工: 已确定判断的记述以 KnowledgeBase 的 Vault 为正本。 decisions 持有的是作业面（选项・依据链接・状态），通过 vault_ref 指向Vault侧。 不在两处持有相同文字。

decide 是用于记录人类判断的入口。智能体排列选项（propose_decision）， 人类进行选择。chosen 仅限于已注册的键，不接受自由记述（否则事后无法机械地追溯）。 revise_option 仅带理由地修订依据的状态（evidence_trials / measured / note） （注册时的依据作为事件始终保留在历史中）。

视角对齐（已实现）— 智能体→人类

feedback 是人类→智能体，decisions 是论点的账簿。还缺一个方向: 让智能体当前正在看哪个比较来发言，与人类屏幕上的内容保持一致的手段。

即使智能体说「缩小到9个标签后是8胜1败」，如果人类在看另一个比较， 数字就对不上。用语言重新传达条件就像传话游戏，实际上在这轮往返中 「是排除了，还是看了全部」变得模糊不清。

• agentviz.viewstate — 指认的存储（仅追加JSONL、store/viewstate.jsonl）。 point / clear / current / history

• MCP工具 point_at_comparison — 将基准・候选・从汇总中排除的案例发送到面板， 在同一次调用中同时返回该比较的数字（分开获取可能产生不一致）。 note 为必填。没有理由的画面变更，在人类看来只是「自己变了」

• MCP工具 clear_comparison_pointer / 面板的「解除指认」按钮

不重写台账，也不重写决策。 它不是所见或判断，而是对齐视角的指针。 不默默覆盖人类的选择是设计的关键，面板在应用时会 必定显示「谁在何时出于什么目的指定了它」，并附上解除的入口。

判断视图（已实现）

「平均排名表」无法做出判断——这一情况在实战中反复出现，因此将判断的骨架部件化。 全部以 人类=图 / 智能体=JSON 的双面形式提供。

• 配对差 paired_diff — 2次试验的按案例差异。当平均值的符号与案例多数决不一致时发出 警告（不一致时无法主张排名。在实际数据中多次触发）。 可通过 cases 将汇总限定为子集。这是不将两试验中条件不同的案例混入平均值的入口， 在RSNA中，梯度未到达的3个标签的差异是噪声，却稀释了12个标签的平均值， 平均值 -0.040 与中位数 -0.104 相差3倍。被排除的案例必定进入 excluded_cases， 在图中也不删除，而是以灰色保留（若删除，读者将无法区分是选择了有利的子集 还是排除了条件不同的案例）。 面板上也有「从汇总中排除的案例（可多选）」的选择栏，选择后当场 更新图表和统计（与 MCP compare_trials 的 cases、build_report 的 pairs 第3元素功能相同）

• 分层平均 strata_means — 输出「在这一层中排名会反转」。层的定义（领域知识）由 调用方持有

• 决策杠杆 decision_leverage — 应优先决定哪个决策。前提2条（1决策=1因子、 仅存活的选项）每次作为premises附带

• 按案例详情 case_scores / 点状图 — 将相对热力图中消失的 「案例的绝对难度」作为排列顺序被动地映入眼帘

• 神谕余地 headroom — 约束松弛类方案（如 scheduled sampling 等）在实现前 通过神谕运行测量上限。将「神谕不可采用・是上限・低于阈值则系统性搁置」作为 premises附带

• 泛化差距散点图 — 带 lb_score / oos_score 的试验达到2个以上时自动显示

运维部件

• 试验归档 set_archived / archive_trial — 将阶段推进后已了结的试验 可逆地隐藏，保持可视化的分辨率（不删除。历史保留在MLflow中）

• 深色模式 — 报告支持 prefers-color-scheme（Plotly图通过relayout跟随）

• 面板MCP工具17个（读取13个＋写入为 add_feedback 系・decide / archive_trial・point_at_comparison / clear_comparison_pointer。最后2个不改变台账，只移动人类屏幕正在查看的比较）

实际应用案例（案例研究）

• kaggle-store-sales-workflow — 时间序列验证设计。将12个决策作为决策点记账，分割设计・基线・特征・采用与否 全部以「先测量再决定」的方式运作。甚至包括CV改善的LB迁移分析

• kaggle-house-prices-workflow — nested-CV模型选择。按案例热力图检测出隐藏在平均排名下的分层反转的首次应用

• rsna-knee-abnormality-detection — 弱监督12标签分类（macro ROC-AUC）。 from_per_label 的首次应用。按教师信号浓度对标签分层后， 浓的8个标签为 0.751，而教师信号枯竭的4个标签为 0.525， 指标的1/3实质上未学习这一事实从平均值 0.6807 之下浮现出来。 后续比较中还发现需要限定配对差的汇总范围（全12标签时平均 -0.040， 但缩小到梯度到达的标签后，效果幅度为 -0.090。若仅凭平均值决定采用与否， 会低估一半以上）

• examples/ingest_ahc069.py — AHC自研运行器实测日志1133次试验的导入

路线图

• 残差相关矩阵的视图化（在混合多样性判断中手工实现。部件化候选）

• 命名层存储（人类「指认」的持久化）

• run alias（从多个决策上下文引用同一测量。源自试验复用破坏可见性的教训）

• pahcer格式适配器（拿到实物输出时添加）

• 报告的大小优化（Plotly内嵌约4.9MB/份。已实测对智能体读取无碍）