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. 重写检索逻辑

**当前**：
```python
# 直接检索 server
selected_servers = rank_servers(query, keywords, capabilities, datatypes)
```

**改为**：
```python
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 二部图

```python
# 图结构：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 输出**：
```json
{
  "keywords": [],
  "capabilities": [],
  "datatypes": [],
  "stages": [],
  "workflow_type": "single_step"
}
```

**修改为**：
```json
{
  "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 类索引

```python
# 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."