Context Engineering 与 Agent 设计¶

请分析这个 16S rRNA 测序数据，找出 T2D 患者和健康人的差异菌群。

System Prompt: 你是肠道微生物组分析专家，擅长 QIIME2 和 LEfSe...
Few-shot: 这是一个类似分析的成功案例 [附上参考输出格式]
RAG 检索: 从知识库找到 3 篇最相关的 T2D 肠道菌群文献摘要
工具输出: QIIME2 的 alpha diversity 计算结果 [数据表]
用户画像: 用户是生信初学者，需要详细解释每一步
记忆: 上次对话中用户提到数据是 V3-V4 区域，Illumina PE250

# 系统提示词示例
system_prompt = """
你是一个宏基因组分析专家。
# 你的能力
- 熟悉 Kraken2、MetaPhlAn4、HUMAnN3 等工具
- 精通 16S 和 shotgun metagenomics 分析流程
# 你的行为准则
- 所有代码加中文注释
- 先解释原理，再给代码
- 遇到不确定的参数，明确说明并给推荐值
"""

# few-shot 示例：教 AI 怎么解读 alpha 多样性结果
few_shot = """
## 输入示例
Shannon 指数：T2D组 = 3.2 ± 0.8，健康组 = 4.5 ± 0.6，p = 0.003

## 期望输出
### Alpha 多样性分析结果
- **Shannon 指数**显示 T2D 组（3.2 ± 0.8）显著低于健康组（4.5 ± 0.6）
- **统计检验**：Wilcoxon 秩和检验 p = 0.003（< 0.05，差异显著）
- **生物学意义**：T2D 患者肠道菌群多样性降低，这与已有文献一致
  （Qin et al., 2012, Nature）
"""

# RAG 流程伪代码
def get_context_from_rag(user_query):
    # 1. 把用户问题转成向量（embedding）
    query_vector = embed(user_query)                # 文本 → 数字向量

    # 2. 从向量数据库搜索最相关的文档片段
    relevant_docs = vector_db.search(               # 搜最近邻
        query_vector,
        top_k=5                                     # 取最相关的5段
    )

    # 3. 把搜到的文档塞进 context
    context = "\n".join([doc.text for doc in relevant_docs])
    return context

# 工具定义示例（MCP 协议格式）
tools = [
    {
        "name": "run_kraken2",                   # 工具名
        "description": "对 FASTQ 文件进行物种注释", # 工具描述（很关键！）
        "parameters": {                          # 参数定义
            "input_fastq": "输入的测序文件路径",
            "database": "Kraken2 数据库路径",
            "confidence": "置信度阈值，默认 0.2"
        }
    }
]
# AI 调用工具后，工具输出会自动进入 context
# 例如 Kraken2 跑完后返回：
# "总 reads: 1000000, 已分类: 650000 (65%), 未分类: 350000 (35%)"

# 长期记忆示例
memory = {
    "user_info": {
        "name": "[用户]",
        "level": "[届别]毕业生，生信初学者",
        "project": "T2D 肠道菌群宏基因组分析"
    },
    "preferences": {
        "language": "中文",
        "code_style": "每行加中文注释",
        "conda_envs": ["ml_env", "bioinfo", "qc_env"]
    },
    "history": [
        "上次讨论了 Kraken2 数据库构建",
        "已完成 FastQC 质控步骤"
    ]
}

# 好的工具定义——清晰、有边界、参数名自解释
{
    "name": "run_diversity_analysis",
    "description": "计算样本的 alpha 多样性指标（Shannon、Simpson、Chao1）。"
                   "输入必须是 QIIME2 的 FeatureTable[Frequency] 格式的 .qza 文件。"
                   "输出为 TSV 表格和箱线图。",
    "parameters": {
        "feature_table": {
            "type": "string",
            "description": "QIIME2 feature table 的绝对路径，如 /data/table.qza"
            # 注意：Anthropic 建议用绝对路径，防止 Agent 在不同目录下迷路
        },
        "metrics": {
            "type": "array",
            "description": "要计算的指标列表",
            "default": ["shannon", "simpson", "chao1"]
        }
    }
}

# 差的观察空间：只返回"成功/失败"
tool_output = {"status": "success"}

# 好的观察空间：返回可验证的详细信息
tool_output = {
    "status": "success",
    "summary": {
        "total_reads": 1000000,         # 总 reads 数
        "classified": 650000,           # 已分类数
        "classified_pct": 65.0,         # 分类率
        "top_species": [                # Top 5 物种
            {"name": "Bacteroides vulgatus", "pct": 12.3},
            {"name": "Faecalibacterium prausnitzii", "pct": 8.7}
        ]
    },
    "warnings": [                       # 潜在问题提醒
        "分类率低于 70%，建议检查数据库版本是否匹配"
    ],
    "output_files": ["/results/kraken2_report.txt"]
}

# Agent 的错误处理策略
error_handling = """
当工具调用失败时：
1. 首先读取错误信息，判断原因
2. 如果是参数错误 → 修正参数重试（最多 3 次）
3. 如果是依赖缺失 → 告知用户需要安装什么
4. 如果是数据格式问题 → 尝试格式转换
5. 如果重试 3 次仍失败 → 暂停并报告给用户
"""

# 面试准备项目

## 用户背景
- [用户]，[届别]毕业生，准备生信工程师面试
- 英语和编程基础薄弱，需要中文解释 + 白话类比

## 项目结构
- project/ - 14天学习计划的实操项目
- knowledge_base/ - 知识库（22篇基础 + 24篇工具教程）

## 操作规则
- 安装任何软件/包之前必须先询问用户
- 所有代码每行加中文注释
- conda 环境：ml_env（机器学习）、bioinfo（生信分析）

## 知识库写作格式
- 白话解释 + 安装配置 + 代码实操 + 常见报错 + 速查表
- 每篇 3000-5000 字

┌─────────────────────────────────────────────┐
│  Layer 1: System Prompt（角色定义）            │
│  "你是宏基因组分析 Agent，精通以下流程..."      │
├─────────────────────────────────────────────┤
│  Layer 2: CLAUDE.md（项目规则）                │
│  "conda 环境、文件路径、输出格式要求..."        │
├─────────────────────────────────────────────┤
│  Layer 3: Tools（可用工具）                    │
│  FastQC, Trimmomatic, Kraken2, HUMAnN3...   │
├─────────────────────────────────────────────┤
│  Layer 4: RAG（知识库检索）                    │
│  按需检索工具文档、参考文献、报错解决方案        │
├─────────────────────────────────────────────┤
│  Layer 5: Memory（记忆）                      │
│  用户偏好、已完成步骤、中间结果                 │
├─────────────────────────────────────────────┤
│  Layer 6: Tool Output（实时反馈）              │
│  每步分析的输出结果，用于决定下一步              │
└─────────────────────────────────────────────┘

# ============================
# 生信分析 Agent 的完整 Context 设计
# ============================

# --- Layer 1: System Prompt ---
system_prompt = """
你是一个专业的宏基因组数据分析 Agent。

## 你的能力
- 执行完整的 shotgun metagenomics 分析流程
- 从原始 FASTQ → 质控 → 物种注释 → 功能注释 → 统计分析 → 报告

## 分析流程（按顺序执行）
1. FastQC 质控检查
2. Trimmomatic / fastp 去接头和低质量碱基
3. Kraken2 + Bracken 物种注释
4. HUMAnN3 功能通路分析
5. Alpha/Beta 多样性分析
6. LEfSe 差异分析
7. 生成 HTML 报告

## 行为准则
- 每个步骤执行后，检查输出文件是否存在且非空
- 如果某步骤失败，先尝试修复，3 次失败后报告用户
- 所有中间结果保存到 results/ 目录
- 关键参数使用前先确认
"""

# --- Layer 2: 工具定义（Tools）---
tools = [
    {
        "name": "run_fastqc",                    # 质控检查工具
        "description": "对 FASTQ 文件运行 FastQC 质量检查。"
                       "输出 HTML 报告和 ZIP 文件到指定目录。",
        "parameters": {
            "input_files": "FASTQ 文件路径列表（绝对路径）",
            "output_dir": "输出目录（绝对路径）",
            "threads": "线程数，默认 4"
        }
    },
    {
        "name": "run_kraken2",                   # 物种注释工具
        "description": "使用 Kraken2 对 reads 进行物种分类注释。"
                       "需要预先构建好的 Kraken2 数据库。"
                       "confidence 建议设为 0.2 以平衡灵敏度和特异性。",
        "parameters": {
            "input_r1": "正向 reads 文件路径",
            "input_r2": "反向 reads 文件路径",
            "database": "Kraken2 数据库绝对路径",
            "confidence": "置信度阈值，默认 0.2",
            "output_dir": "结果输出目录"
        }
    },
    {
        "name": "run_statistical_test",          # 统计检验工具
        "description": "对两组样本进行统计检验（Wilcoxon/Mann-Whitney U）。"
                       "输入为 TSV 表格，需包含 group 列。",
        "parameters": {
            "input_table": "输入数据表路径",
            "group_column": "分组列名",
            "test_method": "检验方法：wilcoxon 或 mannwhitney",
            "p_threshold": "显著性阈值，默认 0.05"
        }
    }
]

# --- Layer 3: Few-shot Examples ---
few_shot_examples = """
## 示例：解读 Kraken2 输出

### 输入
Kraken2 报告显示：
- 分类率：72%
- Top 物种：Bacteroides vulgatus (15%), F. prausnitzii (8%)

### 期望输出格式
#### Kraken2 物种注释结果
- **总体分类率**：72%（正常范围 60-80%）
- **优势物种**：
  1. *Bacteroides vulgatus* (15%) — 拟杆菌属，肠道常见厌氧菌
  2. *Faecalibacterium prausnitzii* (8%) — 产丁酸菌，抗炎标志物
- **提示**：分类率在正常范围内，无需调整参数
"""

# --- Layer 4: Memory（跨对话记忆）---
memory = {
    "project": "T2D 肠道菌群宏基因组分析",
    "completed_steps": ["FastQC", "Trimmomatic"],  # 已完成的步骤
    "data_info": {
        "platform": "Illumina NovaSeq 6000",
        "read_length": "PE150",
        "sample_count": 30,                        # 15 T2D + 15 健康对照
        "region": "shotgun whole genome"
    },
    "issues_encountered": [
        "Kraken2 数据库下载中断过一次，重新下载解决"
    ]
}

用户输入: "分析这批宏基因组数据"
    │
    ▼
Agent 读取 Context（System Prompt + CLAUDE.md + Memory）
    │
    ▼
Agent 制定计划: "需要执行 7 个步骤"
    │
    ▼
Step 1: 调用 run_fastqc → 检查输出 → ✅ 通过
    │
    ▼
Step 2: 调用 run_trimmomatic → 检查输出 → ✅ 通过
    │
    ▼
Step 3: 调用 run_kraken2 → 检查输出 → ⚠️ 分类率只有 45%
    │
    ▼
Agent 判断: "分类率异常低，可能是数据库不匹配"
    │
    ▼
Agent 从 RAG 检索: "Kraken2 分类率低的常见原因"
    │
    ▼
Agent 修复: 切换到更大的数据库 → 重跑 → ✅ 分类率 72%
    │
    ▼
继续后续步骤...

┌──────────────────────────────────────────────┐
│ 层级              │ 内容        │ 动态性      │
├──────────────────────────────────────────────┤
│ System Prompt     │ 角色和规则   │ 静态        │
│ Few-shot          │ 参考示例     │ 半静态      │
│ RAG               │ 检索知识     │ 动态        │
│ Tool Output       │ 工具结果     │ 实时        │
│ Memory            │ 历史记忆     │ 持久        │
│ User Profile      │ 用户画像     │ 半静态      │
└──────────────────────────────────────────────┘

✅ 该写：
  □ AI 猜不到的 bash 命令
  □ 非标准代码风格
  □ 测试命令和运行方式
  □ 项目特殊约定（分支命名、PR 格式）
  □ 环境变量和依赖

❌ 不该写：
  □ AI 能从代码推断的内容
  □ 标准语言规范
  □ 详细 API 文档（给链接）
  □ "写干净的代码"之类的废话

问题                    → 解决方案
───────────────────────────────────
上下文快满了             → /compact 压缩或 /clear 清空
不相关内容混在一起       → 任务间 /clear
探索代码库占太多上下文   → 用子代理探索，汇报摘要
修了好几次还没修好       → /clear 后用更好的初始 prompt
CLAUDE.md 太长被忽略     → 精简，只保留必要规则

入门：读 Simon Willison 的科普文章（10 分钟）
     ↓
进阶：读 Anthropic 的 Building Effective Agents（30 分钟）
     ↓
实践：写好自己项目的 CLAUDE.md（30 分钟）
     ↓
深入：读 Claude Code Best Practices，优化 Agent 配置（1 小时）
     ↓
应用：设计自己领域的 Agent（如生信分析 Agent）