onescience-data-analyzer

输入获取方式

本技能支持两种输入方式：

1. 上下文 handoff（默认）：从调用方传入的 step_handoff 获取任务信息。
2. 文件 handoff（autonomous_mode）：从 .onescience/handoff/step_{step_id}.yaml 读取任务信息。执行后，将结果写入 .onescience/handoff/step_{step_id}_result.yaml。

启动时优先检查 .onescience/handoff/ 目录是否存在对应的交接文件；若存在则使用文件模式，否则使用上下文模式。

文件交接格式参见 skills/onescience-orchestrator/references/file_handoff_contract.md。

onescience-data-analyzer

数据分析执行技能，负责数据分析、可视化与报告输出。

职责

本技能为执行器（executor），专注于执行数据分析任务，不涉及任务规划。规划由其他技能完成后传递给本技能执行。

核心能力

1. 数据分析：统计分析、趋势分析、相关性分析
2. 数据可视化：图表生成、多维展示、交互式可视化
3. 报告生成：结构化报告、图文结合、结果导出

工作流调用

根据任务类型调用对应工作流：

• 统计分析：{{workflow:references/statistical_analysis.md}}
• 可视化生成：{{workflow:references/visualization.md}}
• 报告输出：{{workflow:references/report_generation.md}}

领域知识

工作流执行时会根据数据领域自动匹配 assets/ 目录中的领域知识：

• 气象数据可视化：assets/meteorology_viz.md
• 生物信息学可视化：assets/bioinformatics_viz.md
• 流体力学可视化：assets/fluid_dynamics_viz.md
• 材料科学可视化：assets/materials_science_viz.md

结构可视化原语

先将 bio、biology、bioinformatics 归一化为生信领域。当输入为 .pdb、.cif、.mmcif，或 requirements.viz_type=complex_structure 时：

阶段一：执行资产获取

1. 若 step_handoff.resource_bindings 已包含 visualization_primitive 的完整 content 和 content.execution_assets：

   • 先检查 execution_assets_summary：若 unavailable + failed == total，跳过校验直接进入阶段二降级决策。
   • 否则遍历每个资产，校验 status 为 available 或 materialized 的资产 SHA-256，再物化到工作区。

2. 若资源绑定不完整或缺少执行资产，按以下优先级获取：

   a. 【优先】直接使用 catalog_search：调用 catalog_search 工具（kind=primitive, domain=bio, q=complex_structure_visualization）。此路径直接查询 OneCode 内置 catalog（含 bundled seed 原语），不依赖 onescience-primitives 技能的间接协议，避免因消息模拟链路中的工具可用性或参数传递问题导致检索失败。若命中：

   • 使用 catalog_resolve(id, part=body) 获取完整内容（含 execution_assets）
   • 提取 matched_resources 中 type=visualization_primitive 的资源
   • 直接跳转到阶段一的步骤 3（召回结果校验），跳过步骤 2b

   b. 【回退】通过 onescience-primitives 协议获取：仅当 catalog_search 未命中时，向 onescience-primitives 发起以下资源召回请求：

   • user_request：必须包含可视化信号词（如"交互式 3D 蛋白质结构可视化、pLDDT 置信度着色、PAE 热图渲染"），确保 primitives 技能能正确路由到 visualization category
   • content_request: "完整内容"
   • include_execution_assets: true
   • filters.domain: bio
   • filters.keyword: complex_structure_visualization（必须使用下划线分隔的精确目录名，以触发 primitives 的命名直查模式，绕过语义排序和截断）
   • 不得沿返回的裸 path 直接读取原语资产

3. 【强制】召回结果校验：根据检索路径不同，校验方式如下：

   若来自路径 2a（catalog_resolve 直接返回）：

   • catalog_resolve 成功返回即表示原语已命中，无需再做"是否包含 visualization_primitive"的检查
   • 直接从返回结果中提取 execution_assets（位于 companions 或返回体的 execution_assets 字段）
   • 直接跳转到阶段二降级决策

   若来自路径 2b（resource_retrieval_result）： a. 检查 matched_resources 是否包含 name=complex_structure_visualization 且 type=visualization_primitive 的资源。 b. 若未召回该原语（即返回空列表或不包含 visualization_primitive），不得直接放弃。必须执行以下回退步骤： ① 检查 resource_retrieval_result.detected_domain 是否为 bio，task_intent 是否包含 visualization。 ② 若 task_intent 不包含 visualization，说明 primitives 可能未正确识别可视化意图。此时重新发起请求，将 user_request 修改为以可视化为主意图的描述（如"需要蛋白质复杂结构三维可视化、pLDDT/PAE 置信度着色、交互式 3D 视图的原语规范"），并显式设置 filters.keyword: complex_structure_visualization pLDDT PAE 3D interactive render（保留精确目录名 complex_structure_visualization 作为第一个 keyword 以触发命名直查）。 ③ 二次请求后仍未召回，在 visualization_result.quality_checks 中记录 primitive_not_recalled: true，recall_retry_count: 2，last_error: unable to match complex_structure_visualization after retry，进入阶段二降级决策（仅生成非交互式图表，明确说明结构三维渲染不可用）。 c. 若已召回，检查 execution_assets_summary，进入阶段二降级决策。

阶段二：降级决策

按资产角色分级处理，不允许全有或全无阻断。核心资产定义：

资产	角色	不可用时的行为
scripts/render_complex_structure.py	渲染器入口（必需）	阻塞，无法降级。返回 status: blocked，blocked_details 记录缺失原因。
scripts/vendor/3Dmol-2.5.4.min.js	离线运行时（必需）	阻塞，无法降级。离线 HTML 无法在没有 3Dmol.js 时渲染三维结构。
scripts/interactive_template.html	HTML 模板（可降级）	模板不可用但渲染器和运行时可用时，基于 complex_structure_visualization 的 spec.md 中 # renderer_profiles 和 # top_level_views 章节构建最小功能模板。必须支持默认视图、pLDDT 视图、序列联动和 PAE 面板，但可省略自定义视图和 Dynamic bonds 的完整交互。在 visualization_result.quality_checks 中标记 template_rebuilt_from_spec: true。
scripts/validate_visualization.py	验证器（可跳过）	不可用时跳过静态验证步骤，在 visualization_result.quality_checks 中标记 validation_skipped: true，interaction_smoke_test 设为 not_run。
scripts/vendor/3DMOL-LICENSE.txt	许可证文本（可跳过）	不可用时跳过内联，记录 warning。

降级禁止事项（不可跨越的红线）：

• 渲染器入口不可用时，不得根据 spec.md 或 usage.md 手写替代 render_complex_structure.py——这等同于重写核心渲染逻辑。
• 3Dmol.js 运行时不可用时，不得将离线 HTML 改为 CDN 外链——违反离线确定性交付约束。
• 模板降级仅允许在渲染器和运行时均可用时触发；降级产出的 HTML 必须仍在 # output_schema 约束内，且 capability_downgrades 必须逐项记录缺失功能。

5. orchestrator 交接的 step_handoff.inputs.visualization 与下方直接调用 JSON 的 data_path、requirements 字段映射为同一内部请求。
6. PyMOL 不可用时可以回退交互式 Web renderer，但不得把 Web 输出声明为 .pse 或真实 PyMOL session。
7. samples_manifest_path 非空时进入多样本模式；manifest 中每个样本必须原子绑定同一 seed/sample 的 structure、confidence 与 summary 三个文件，任一缺失或校验失败则整条样本失败。
8. 完整 PAE 只能读取同一样本 confidences.json.pae；summary_confidences.json.chain_pair_pae_min 不能扩展、插值或复制为 PAE matrix。缺失时返回 unavailable，不得伪造热图。
9. single_file_compatibility: true 保留位置参数结构输入；没有完整 confidence JSON 时只生成三维结构视图并禁用 PAE。
10. 生成前校验 atom pLDDT 数量、PAE 方阵、token 映射、样本 ID 和文件来源；生成后使用 public manifest 验证 sample count、pLDDT provenance 与 PAE availability。

使用方式

接收来自规划技能的任务描述，按照以下流程执行：

1. 识别任务类型（分析/可视化/报告）
2. 加载对应工作流
3. 匹配领域知识和已绑定的 visualization primitive（如果需要）
4. 为结构可视化建立 renderer-neutral scene specification
5. 执行分析与生成
6. 执行输出非空、实体可见性和视觉 smoke test
7. 输出结果

输入格式

{
  "task_type": "visualization|analysis|report",
  "data_path": "数据文件路径",
  "samples_manifest_path": "path/to/af3_samples_manifest.json|null",
  "single_file_compatibility": true,
  "confidence_path": "path/to/*_confidences.json|null",
  "summary_confidences_path": "path/to/*_summary_confidences.json|null",
  "domain": "meteorology|bio|bioinformatics|fluid_dynamics|materials_science|general",
  "requirements": {
    "viz_type": "line|scatter|heatmap|contour|3d|complex_structure|...",
    "primitive": "complex_structure_visualization",
    "scene_mode": "auto|single_polymer|protein_multimer|protein_nucleic_acid|protein_ligand|mixed_complex",
    "renderer": "auto|pymol|3dmol|molstar|ngl",
    "confidence_semantic": "none|plddt|b_factor|external",
    "confidence_source": "none|cif_ma_qa_metric_local|cif_b_factor|pdb_b_factor|af3_confidences_json|external_per_residue",
    "requested_views": ["default", "plddt", "custom"],
    "pae_source": "none|af3_confidences_json",
    "analysis_methods": ["correlation", "trend", "distribution"],
    "output_format": "png|svg|pdf|html|pml|pse"
  }
}

输出格式

{
  "status": "success|partial|failed",
  "outputs": {
    "figures": ["path/to/fig1.png", "path/to/fig2.svg"],
    "interactive": ["path/to/structure.html"],
    "pymol": ["path/to/structure.pml", "path/to/structure.pse"],
    "report": "path/to/report.html",
    "data": "path/to/processed_data.csv"
  },
  "visualization_result": {
    "primitive": "complex_structure_visualization",
    "scene_mode": "single_polymer|protein_multimer|protein_nucleic_acid|protein_ligand|mixed_complex",
    "renderer": "pymol|3dmol|molstar|ngl|other",
    "sample_count": 1,
    "provenance": {
      "samples_manifest_path": null,
      "sample_files": []
    },
    "pae": {
      "available": false,
      "source": "none|confidences.json:pae",
      "sample_ids": [],
      "matrices_validated": 0
    },
    "validation_flags": {
      "expected_sample_count": true,
      "sample_ids_unique": true,
      "default_sample_exists": true,
      "atomic_sample_pairing": true,
      "plddt_provenance_all_samples": true,
      "pae_available_all_samples": true,
      "pae_matrix_shape_valid": true,
      "pae_token_mapping_valid": true
    },
    "warnings": [],
    "quality_checks": {"template_rebuilt_from_spec": false,
      "validation_skipped": false,
      "interaction_smoke_test": "passed",
      "primitive_not_recalled": false,
      "recall_retry_count": 0
    }
  },
  "summary": "分析与可视化完成概要"
}