Biomanus/docs/plan.md

系统升级 Prompt：从 Graph Router 到 Graph Planning Engine

任务目标

将现有系统从 Server-level retrieval 升级为 Operation-level multi-hop path retrieval。

当前系统状态

• 图规模：910 servers，3451 tools，4398 nodes，25437 edges
• 现有节点类型：server、tool、category、stage、datatype（14类）、capability（12类）
• 现有边类型：consumes、produces、implements、follows
• 当前逻辑：Query → keywords/capabilities/datatypes → Server scoring → Tool selection

需要修改的核心内容

1. 新增 Operation 节点层

问题：当前 capability 太粗（如 pathway_enrichment），不适合多跳规划

修改：新增 operation 节点，粒度示例：

count_normalization
differential_expression
gene_filtering
gene_id_conversion
kegg_enrichment
go_enrichment
pathway_merge
csv_export

边：

tool --implements--> operation
operation --accepts--> datatype
operation --produces--> datatype
operation --requires--> constraint

2. 扩展 DataType 节点

问题：当前 datatype 只有 14 类，缺少中间类型

修改：扩展 datatype 列表，建议：

raw_count_matrix
normalized_count_matrix
sample_metadata
differential_expression_table
significant_gene_list
ranked_gene_list
gene_symbol_list
entrez_gene_list
kegg_enrichment_table
go_enrichment_table
merged_pathway_table

区分物理格式和语义类型：

datatype 只表示语义类型，不表示 csv/tsv 等格式

3. 新增 Constraint 节点

修改：添加约束节点用于路径过滤

organism_mouse
bulk_rna_seq
requires_raw_integer_counts
requires_entrez_id
requires_replicates
paired_end_reads

边：

operation --requires--> constraint
tool --supports--> constraint

4. 新增 Workflow Motif 节点

修改：添加常见工作流模板作为路径先验

motif.bulk_rnaseq_de_kegg
motif.scRNA_marker_enrichment
motif.metagenomics_taxonomic_profile

边：

motif --contains--> operation

5. 重写检索逻辑

当前：

# 直接检索 server
selected_servers = rank_servers(query, keywords, capabilities, datatypes)

改为：

def multi_hop_planning(query, input_profile):
    # Step 1: 解析任务规格
    task_spec = parse_task_spec(query, input_profile)
    # 输出：input_types, target_output, constraints, required_operations
    
    # Step 2: 检索 operation anchors
    anchors = retrieve_operation_anchors(task_spec.operations)
    
    # Step 3: 类型约束路径搜索
    candidate_paths = constrained_path_search(
        source_types=task_spec.input_types,
        target_type=task_spec.target_output,
        must_pass=anchors,
        constraints=task_spec.constraints,
        max_hops=8
    )
    
    # Step 4: 路径评分排序
    ranked_paths = rank_paths(candidate_paths, task_spec)
    
    # Step 5: 绑定工具
    tool_plan = bind_tools_to_operations(ranked_paths[0], task_spec.constraints)
    
    # Step 6: 合成可执行 DAG
    dag = synthesize_dag(tool_plan, task_spec.workflow_type)
    
    return dag

6. 实现路径搜索算法

推荐从简单版本开始：BFS over DataType-Operation 二部图

# 图结构：DataType → Operation → DataType
def search_path(source_types, target_type, graph, max_hops=8):
    # BFS from source_types
    # 每个节点是 (current_datatype, path_operations)
    # 扩展：operation 接受当前 datatype → 产生新 datatype
    # 剪枝：超过 max_hops、违反 constraints、重复访问

升级版：Beam Search 或 A* Search

7. 修改 Query Parser 输出格式

当前 debug_report 输出：

{
  "keywords": [],
  "capabilities": [],
  "datatypes": [],
  "stages": [],
  "workflow_type": "single_step"
}

修改为：

{
  "task_spec": {
    "input_types": ["raw_count_matrix", "sample_metadata"],
    "target_output": {"semantic_type": "comparative_pathway_table"},
    "constraints": {"organism": "mouse", "assay": "bulk_rna_seq"},
    "required_operations": ["differential_expression", "kegg_enrichment"],
    "workflow_type": "multi_branch_join"
  },
  "operation_anchors": ["differential_expression", "kegg_enrichment"]
}

8. 添加 4 类索引

# 1. Operation Semantic Index (query → operation)
# 2. DataType Recognition Index (file/columns → datatype)
# 3. Path/Motif Index (常见路径缓存)
# 4. Tool Binding Index (operation → candidate tools)

实现优先级

Phase 1（优先完成）

1. 新增 operation 节点和边
2. 扩展 datatype 到 30+ 类
3. 实现 BFS 路径搜索（仅 operation-datatype 二部图）

Phase 2

4. 添加 constraint 节点
5. 实现路径评分函数
6. 修改 Query Parser 输出格式

Phase 3

7. 添加 workflow motif
8. 实现 DAG 合成（支持分支-合并）
9. 添加 4 类索引优化

测试用例

先支持这 5 类多跳任务：

1. count_matrix → DE table → pathway enrichment table
2. FASTQ → QC → alignment → count matrix
3. VCF → annotation → variant summary
4. AnnData → clustering → marker genes → enrichment
5. metagenomic reads → taxonomy → differential abundance

关键设计原则

1. Operation-first, tool-later：先找 operation path，再绑定具体 tool
2. Type-constrained：路径合法性由 input/output datatype 决定
3. Constraint-aware：organism、assay 等约束用于路径剪枝
4. Motif-guided：常见 workflow 作为先验加速搜索
5. 可验证中间状态：每一步都有明确的 datatype 转换

预期效果

升级后系统从：

Query → Server ranking → Tool selection

变为：

Query → Goal decomposition → Operation path search → Tool binding → Executable DAG

核心表述：

"Instead of retrieving isolated MCP servers, the system performs multi-hop subgraph retrieval over a biomedical capability graph, searching for executable operation paths that connect input data types to target outputs while satisfying constraints."